Utils
The plain TypeScript helpers exported from @groupthought/tradecraft-ui/utils: DOM checks, layout measurement, focus preservation, state machines, and directive modifier parsing.
The plain TypeScript helpers the plugins are built from, imported from @groupthought/tradecraft-ui/utils. These modules are internal and can change between versions.
dom
Element checks, form submission plumbing, and scheduling helpers.
isHtmlElement(node)
Type guard for element nodes; most plugins call it first
isImageElement / isVideoElement / isSourceElement / isScriptElement / isAnchorElement / isFormElement / isDialogElement / isInputElement / isButtonElement / isSummaryElement / isTemplateElement
Per-tag type guards
isInputRangeElement(node) / isInputNumberElement(node)
Guards for type="range" and type="number" inputs
isHiddenInput(el)
Guard for type="hidden" inputs
isProductForm(el) / isInProductForm(el)
True for a cart/add form, or an element inside one
isShopifyAppBlock(el) / isShopifyElement(el)
True for app-block and Shopify-injected elements
isTouchOnlyDevice()
True when the main pointer cannot hover. Same test as the touch: style variant, so JavaScript and CSS agree
isIOSDevice()
True on an iPhone or iPad, including an iPad that reports a Macintosh user agent, which its touch points tell apart from a Mac
isHoverSupported() / isPopoverApiSupported() / isDialogApiSupported() / isFormDataSubmitterSupported()
Capability checks
isTouchEvent(e) / isLeftMouseButton(e) / isPrimaryPointer(e)
Pointer event checks; isPrimaryPointer filters out right clicks and secondary touch points
isElementKeyboardAccessible(el)
True when the element is natively focusable
isNodeOrChild(parent, child)
True when child is parent or a descendant of it
getWritingDirection(el)
ltr or rtl from computed style
getFormSubmissionInfo(target, submitter)
Action, method, FormData, and enctype from a form, button, or submit input
submitFormData(info, init)
Fetches with that info: JSON body for application/json, multipart otherwise, query string for GET
serializeFormData(formData)
Nested JSON object from bracketed field names (properties[gift])
parseMultipart(body, contentType)
Structured data back out of a multipart request body
isModifiedEvent(e) / shouldProcessLinkClick(e, target)
True when a click should navigate normally (modifier key, non-left button, target="_blank")
isClipboardWriteAllowed()
Resolves whether clipboard.writeText can run; assumes yes where the permission cannot be queried
isClickingOutside(e, container) / isPointWithinElement(x, y, el)
Outside-click checks; the first uses composedPath() so content swapped after the click still counts as inside
onDocumentReady(cb)
Runs on DOMContentLoaded, or at once when the document is already complete
requestIdleCallback(cb, options) / cancelIdleCallback(id)
Idle scheduling with a setTimeout fallback. Always pass a timeout, or a busy main thread can put the callback off forever
onFirstScroll(cb)
Runs at the first scroll, or right after the next paint when the page is already scrolled (anchor links, back button). Returns a cancel function
getCartApiSections()
Section ids that carry data-cart-api-section, for the cart API sections parameter
createCartRequestGroup(onSettle)
Groups overlapping cart requests and settles once with the request that started last, or null when it failed
layout-measure
Reads layout without forcing synchronous reflows. Callbacks scheduled in the same frame share one flush with reads running first, so batched reads never interleave with batched writes.
onFirstLayout(el, fn)
Runs once the element has a layout box, inside a ResizeObserver callback: reads are free and style writes still land in the same frame's paint. Use it to measure, then apply initial styles
afterNextPaint(fn)
Runs after the next paint. Reads are free; writes render one frame later, so never apply initial visual state here. Returns a cancel function
afterNextPaintAsync()
Promise form of afterNextPaint
readLayoutAfterPaint(fn)
Runs the read after the next paint, before that frame's afterNextPaint callbacks, and resolves with its result
afterFrames(count)
Resolves once the browser has run count animation frames. Use it to wait for work that another library schedules a known number of frames ahead
preserve-focus
Preserves keyboard focus across DOM swaps (Alpine.morph or innerHTML replacement). When a swap replaces the focused node, the browser silently drops focus to <body> and the next Tab restarts from the top of the document.
captureFocus(rootEl)
Snapshot of the focused element inside the root: tag, id, name, labels, ancestors, and text selection. Null when focus is elsewhere
restoreFocus(rootEl, snapshot)
After the swap, refocuses the surviving or replacement element, or the nearest surviving container's first focusable element. No-op when focus already sits on a real element
relocateFocusFrom(container)
Moves focus out of a subtree before it is hidden or removed: following siblings first, then preceding, then the nearest focusable outside. Prefers a neighbor with the same aria-label
data-preserve-focus-key
Attribute giving an element a stable identity across renders when its id or label changes
state-machine
A typed finite state machine. The async plugins (async-form, async-link) use it for their request states.
new StateMachine(initialState, states, transitions)
States are a string tuple; transitions map each state to the states it can move to
machine.state
Get the current state, or set it. Setting an invalid transition throws
machine.prevState
The previous state, or null at the initial state
machine.setTransientState(state, nextState, ms)
Enters a state and moves to the next after the timeout, for short-lived UI states like a success message
machine.on(listener) / .off(listener)
Subscribe to state changes with (newState, prevState)
revertible-value
A value that remembers its previous value.
new RevertibleValue(initial)
Holds currentValue and previousValue
value
Get or set. Setting a different value moves the old one to previousValue
revert()
Restores the previous value
commit()
Makes the current value the new baseline
modifiers
Parses values out of directive modifier lists (x-marquee.speed.60 gives ['speed', '60']). Each parser returns null when the modifier is absent or malformed.
getModifierValue(modifiers, name)
The raw token after the named modifier
getNumberModifierValue(modifiers, name)
The token as a finite number
getPositiveNumberModifierValue(modifiers, name)
The token as a number greater than zero
getMillisecondsModifierValue(modifiers, name)
A 500ms token as 500
getPercentageModifierValue(modifiers, name)
A 50% token as 50
getPixelModifierValue(modifiers, name)
A -12px token as -12
getMassModifierValue(modifiers, name, minimumMass)
A spring mass in units of the minimum mass, so .mass.20 gives 0.2
getSpringModifierConfig(modifiers, defaults, minimumMass)
Applies .mass, .stiffness, and .damping modifiers to a Motion spring config
math
clamp(n, min, max)
The value clamped between min and max
mod(n, m)
Modulo that handles negative numbers: mod(-1, 5) is 4
getDPR(element) / roundByDPR(element, value)
The device pixel ratio, and rounding to it so positioned elements land on device pixels
toScrollValue(value)
Rounds the way browsers round scroll positions, to the nearest half integer
isNumeric(value)
True when a string parses fully as a number
object
camelizeKeys(record, upperCamel)
A copy of the record with snake_case keys converted to camelCase
isPlainObject(x)
True for plain objects; false for arrays and dates
mergeProperties(target, ...sources)
Like Object.assign but copies property descriptors, so getters and setters keep working
renameProperty(obj, oldName, newName)
Renames a property in place, preserving its descriptor
copyProperty(obj, newObj, oldName, newName)
Copies a property descriptor to another object
trackProperty(obj, key, trackingKey)
Proxy that writes the old value to the tracking key whenever the tracked value actually changes
string
toCamelCase(string, upperCamel)
snake_case to camelCase (or UpperCamelCase)
isString(x)
Type guard for strings
function
isFunction(x)
Type guard for functions
product
Lookups against a product object in Shopify's JSON shape.
getVariantById(product, variantId)
The variant with that id, or null
getVariantsForOptions(product, options)
Every variant whose options match the given values, including a partial set
section
closestSectionEl(el)
The containing .shopify-section element, or the element itself when it is one
connection
Reads the Network Information API where the browser has it; each check returns undefined where it does not.
isSavingData()
True when the visitor has data saver on
isSlowConnection()
True on a 2g-class connection
hasConnection(navigator)
Type guard for navigator.connection
device
isReducedMotion()
True when the visitor prefers reduced motion
isLowPowerDevice()
True with 2 or fewer CPU cores or 2GB or less memory
yield-to-main
yieldToMain()
Resolves after yielding to the main thread (scheduler.yield with a setTimeout fallback), to break a long task into smaller ones
Last updated
Was this helpful?

