---
title: Utils
description: Public helpers exported from the root entry and the ./utils subpath.
category: Foundations
status: beta
since: 1.0.0
tags: [utils, helpers, z-index, toast]
syncStatus: reviewed
verified: false
---

```ts
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 |

### 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 |
| `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 |

### 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 |

### Animation

| Export | Signature | When to use |
|--------|-----------|-------------|
| `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` |
| `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` |

### 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.ts` re-exports `packages/tuffex/packages/utils/*`.
- Subpath entry `@talex-touch/tuffex/utils`; the root `@talex-touch/tuffex` entry exports the same helpers.