Utils
Public helpers exported from the root entry and the ./utils subpath.
import { nextZIndex, toast, hasWindow } from '@talex-touch/tuffex/utils'
API Reference
Z-index manager
One source of overlay stacking levels, so components never hard-code z-index.
| Export | Signature | When to use |
|---|---|---|
nextZIndex() | () => number | Claim the next level for a new overlay |
getZIndex() | () => number | Read the current top level without incrementing |
refreshZIndex(seed?, reason?) | (seed?: number, reason?: string) => number | Recount from a given baseline |
resetZIndex(seed?, reason?) | (seed?: number, reason?: string) => number | Reset to the seed after unmount or in tests |
configureZIndex(options) | (options) => void | Set the base seed and overrides globally |
onZIndexEvent(listener) | (listener) => () => void | Subscribe to level changes; returns an unsubscribe |
createZIndexAllocator() | () => TxZIndexAllocator | Builds an allocator with its own counter, not shared module state |
useZIndexAllocator() | () => TxZIndexAllocator | Call in setup for the app-scoped allocator; falls back to the module-level one |
Environment guards
SSR-safe checks before touching window / document / navigator.
| Export | Signature | When to use |
|---|---|---|
hasWindow() | () => boolean | Guard before touching window |
hasDocument() | () => boolean | Guard before touching document |
hasNavigator() | () => boolean | Guard before navigator (vibrate, clipboard) |
Haptics (vibrate)
Semantic patterns over navigator.vibrate.
| Export | Signature | When to use |
|---|---|---|
vibrate | { light() … error(), stop, isSupported } | Fire a preset directly, e.g. vibrate.success() |
useVibrate(type, options?) | (type: VibrateType, options?) => void | Trigger one configurable semantic vibration |
useAutoVibrate(duration, options?) | (duration: number[], options?) => boolean | Vibrates once over a millisecond pattern; returns false where unsupported |
stopVibrate() | () => void | Interrupt an in-progress vibration |
isVibrateSupported() | () => boolean | Capability detection |
Toast
A global toast queue with no per-page host; rendering still needs TxToastHost.
| Export | Signature | When to use |
|---|---|---|
toast(options) | (options) => string | Show a toast; returns an id for dismissing it |
dismissToast(id) | (id: string) => void | Dismiss one toast |
clearToasts() | () => void | Clear every toast |
pauseToasts() | () => void | Holds every auto-dismiss countdown; repeat calls have no effect |
resumeToasts() | () => void | Resumes each countdown from the time it had left |
Dialog manager
Queues global dialogs by priority and runs them one at a time, with lifecycle callbacks.
| Export | Signature | When to use |
|---|---|---|
getDialogManager() | () => DialogManager | Get the global singleton to queue or open dialogs |
DialogManager | class | The queue class behind getDialogManager(); registers and unregisters dialogs by priority |
Animation
| Export | Signature | When to use |
|---|---|---|
useReducedMotion() | () => Ref<boolean> | Reactive prefers-reduced-motion preference; follows mount and KeepAlive activity |
useFlip(targetRef, opts?) | (ref, opts?) => UseFlipReturn | Run a FLIP transition on an element (powers TxFlipOverlay) |
useAutoResize(targetRef, opts?) | (ref, opts?) => UseAutoResizeReturn | Measure and transition size changes (powers TxAutoSizer) |
stepSpring(position, velocity, target, spring, dt) | (position, velocity, target, spring, dt) => [number, number] | Step a value along a spring ({ stiffness, damping, mass? }, dt in seconds) from your own frame loop, keeping velocity when the target moves; usable as useJellyIndicator's glide integrate |
solveSpring(position, velocity, target, spring, t) | (position, velocity, target, spring, t) => [number, number] | The same spring in closed form: the exact position and velocity at any t (seconds); for scrubbed timelines, frame-by-frame renders, and asserting where a motion is at a moment |
createSpringTrack(spring, initial) | (spring, initial) => { retarget(t, target), sample(t) } | A spring track retargeted along the way: each retarget keeps the position and velocity of that moment, and sample(t) reads any moment exactly, in any order |
useMorphBox(box, content, opts?) | (box, content, opts?) => { morphing, settle } | A box that springs to its content's natural size, keeping its speed when the size changes mid-flight; the size engine of TxMorph and TxTransitionSmoothSize |
useIndicatorBox(options) | (options) => UseIndicatorBoxReturn | Measures a target against its container so an indicator can follow it; resizes stay in sync |
useJellyIndicator(options?) | (options?) => UseJellyIndicatorReturn | Spring engine for a sliding indicator in jelly or glide material; the host measures and paints |
resolveGsapEase(value) | (value: string) => string | ((t: number) => number) | Convert an ease before handing it to GSAP: spring(...) and cubic-bezier(...) become progress functions (GSAP knows neither and silently uses its default); GSAP names pass through |
resolveCssEase(spec) | (spec: string | undefined | null) => (t: number) => number | Evaluate a CSS timing function in JS: cubic-bezier(...), evenly spaced linear(...), and linear / ease / ease-in / ease-out / ease-in-out; anything else degrades to clamped linear, never null. Cached per spec, safe per frame |
createSpringEase(omega?, zeta?) | (omega = 10, zeta = 0.72) => (t: number) => number | Closed-form underdamped spring normalized to the timeline: overshoots 1, settles, lands on exactly 1. Unlike frame-stepped stepSpring, usable directly as an ease |
parseSpringEase(value) | (value: string | undefined | null) => ((t: number) => number) | null | Parse spring / spring(omega) / spring(omega, zeta); anything else returns null |
createCubicBezier(x1, y1, x2, y2) | (x1, y1, x2, y2) => (t: number) => number | Equivalent to CSS cubic-bezier(); the charts entry's cubicBezier is this function |
parseCubicBezier(value) | (value: string | undefined | null) => [number, number, number, number] | null | Parse a cubic-bezier(...) string; GSAP names, keywords, spring forms, or x controls outside 0, 1 return null |
applyThemeTransition(updateTheme, options?) | (updateTheme, options?) => Promise<void> | void | Run smooth dark/light mode transitions via the View Transitions API (circle blur, diagonal slash, wipe, etc.), see 《Theming》 |
Install helper
| Export | Signature | When to use |
|---|---|---|
withInstall(component) | <T>(component: T) => T & { install } | Attach install so a component works with app.use() |
Technologies
- Barrel:
packages/tuffex/packages/components/src/utils/index.tsre-exportspackages/tuffex/packages/utils/*. - Subpath entry
@talex-touch/tuffex/utils; the root@talex-touch/tuffexentry exports the same helpers.