tempest-react-sdk 0.4.0 → 0.5.0

package/dist/tempest-react-sdk.d.ts

@@ -550,6 +550,16 @@ export declare interface ChipInputProps {
     className?: string;
 }
 
+/**
+ * Clamp `value` between `min` and `max` (inclusive).
+ *
+ * @example
+ * clamp(120, 0, 100); // 100
+ * clamp(-5, 0, 100);  // 0
+ * clamp(42, 0, 100);  // 42
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+
 declare type ClassValue = string | number | bigint | boolean | null | undefined | ClassValue[];
 
 /**
@@ -1205,6 +1215,8 @@ export declare interface ErrorStateProps {
     className?: string;
 }
 
+export declare function estimatePasswordStrength(value: string): PasswordStrength;
+
 export declare interface EventStreamController {
     close: () => void;
     /** Force an immediate reconnect, resetting the retry counter. */
@@ -2049,6 +2061,38 @@ export declare interface PaginationProps {
  */
 export declare function parseResponse<TSchema extends z.ZodTypeAny>(schema: TSchema, raw: unknown, context: string): z.infer<TSchema>;
 
+/**
+ * Password field with toggle-visibility button and optional strength meter.
+ *
+ * @example
+ * <PasswordInput label="Senha" showStrength autoComplete="new-password" />
+ */
+export declare const PasswordInput: ForwardRefExoticComponent<PasswordInputProps & RefAttributes<HTMLInputElement>>;
+
+export declare interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size"> {
+    /** Label rendered above the input. */
+    label?: ReactNode;
+    /** Helper text below — replaced by `error` when set. */
+    helperText?: ReactNode;
+    /** Error message. Adds `aria-invalid` + red border. */
+    error?: string;
+    /** Visual size of the input. */
+    size?: "sm" | "md" | "lg";
+    /** Show a strength meter below the field. Default `false`. */
+    showStrength?: boolean;
+    /** Override the automatic strength calc (0–4). */
+    strength?: PasswordStrength;
+    /** Custom labels per strength level (5 entries). */
+    strengthLabels?: readonly [string, string, string, string, string];
+    /** Custom toggle button labels for accessibility. */
+    toggleLabels?: {
+        show: string;
+        hide: string;
+    };
+}
+
+export declare type PasswordStrength = 0 | 1 | 2 | 3 | 4;
+
 export { Path }
 
 export declare const PhoneInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
@@ -2056,6 +2100,51 @@ value: string;
 onChange: (value: string) => void;
 } & RefAttributes<HTMLInputElement>>;
 
+/**
+ * One-time-password style input — N independent cells, paste support, auto-
+ * advance on input, backspace flows back, arrow keys navigate.
+ *
+ * @example
+ * <PinInput length={6} type="numeric" onComplete={(otp) => verify(otp)} />
+ */
+export declare const PinInput: ForwardRefExoticComponent<PinInputProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface PinInputProps {
+    /** Number of cells. Default `6`. */
+    length?: number;
+    /** Allowed character set. `numeric` (default) rejects letters, `alphanumeric` allows both. */
+    type?: PinInputType;
+    /** Visual size. Default `"md"`. */
+    size?: PinInputSize;
+    /** Controlled value. */
+    value?: string;
+    /** Initial value (uncontrolled mode). */
+    defaultValue?: string;
+    /** Fires on every change with the current concatenated value. */
+    onChange?: (value: string) => void;
+    /** Fires when the user fills the last cell. */
+    onComplete?: (value: string) => void;
+    /** Show characters obscured (`*`). Default `false`. */
+    masked?: boolean;
+    /** Label rendered above the cells. */
+    label?: string;
+    /** Helper text below the cells. */
+    helperText?: string;
+    /** Error message — turns cells red and replaces helperText. */
+    error?: string;
+    /** Disable all cells. */
+    disabled?: boolean;
+    /** Auto-focus the first cell on mount. Default `false`. */
+    autoFocus?: boolean;
+    /** id for the wrapping group label association. */
+    id?: string;
+    className?: string;
+}
+
+export declare type PinInputSize = "sm" | "md" | "lg";
+
+export declare type PinInputType = "numeric" | "alphanumeric";
+
 /**
  * Convenience wrapper around a shared {@link AudioPlayer}. Use this for
  * one-off notification sounds. For more complex flows (e.g. several
@@ -2296,6 +2385,21 @@ export declare interface RegisterServiceWorkerOptions {
     onError?: (error: unknown) => void;
 }
 
+/**
+ * Render a `Date` / ISO string as a relative-time string. Supports past and
+ * future, PT-BR (default) and English.
+ *
+ * @example
+ * relativeTime(new Date(Date.now() - 90_000));         // "1 min atrás"
+ * relativeTime("2026-05-17T10:00:00Z", { locale: "en" }); // "5h ago"
+ */
+export declare function relativeTime(input: Date | string | number, options?: {
+    locale?: RelativeTimeLocale;
+    now?: Date | number;
+}): string;
+
+export declare type RelativeTimeLocale = "pt-BR" | "en";
+
 export declare interface RequestOptions extends Omit<RequestInit, "body"> {
     body?: unknown;
     params?: Record<string, string | number | boolean | undefined | null>;
@@ -2395,6 +2499,44 @@ export declare interface SearchBarProps extends Omit<InputHTMLAttributes<HTMLInp
     wrapperClassName?: string;
 }
 
+/**
+ * iOS-style segmented control. Two-to-five mutually-exclusive options
+ * rendered as a single connected pill bar.
+ *
+ * @example
+ * <SegmentedControl
+ *     value={view}
+ *     onChange={setView}
+ *     options={[
+ *         { value: "list", label: "Lista" },
+ *         { value: "grid", label: "Grade" },
+ *     ]}
+ * />
+ */
+export declare function SegmentedControl<TValue extends string = string>({ options, value, onChange, size, fullWidth, className, "aria-label": ariaLabel, ...props }: SegmentedControlProps<TValue>): JSX.Element;
+
+export declare interface SegmentedControlOption<TValue extends string = string> {
+    value: TValue;
+    label: ReactNode;
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+
+export declare interface SegmentedControlProps<TValue extends string = string> extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    /** Available segments. */
+    options: SegmentedControlOption<TValue>[];
+    /** Selected value. */
+    value: TValue;
+    /** Fires with the new value when a segment is selected. */
+    onChange: (value: TValue) => void;
+    /** Visual size. Default `"md"`. */
+    size?: "sm" | "md" | "lg";
+    /** Stretch to full width of container. Default `false`. */
+    fullWidth?: boolean;
+    /** Group label for screen readers. */
+    "aria-label"?: string;
+}
+
 /**
  * Native `<select>` wrapper with label/helper/error slots. Either provide
  * `options` for a quick render, or pass `<option>` children directly.
@@ -2546,6 +2688,19 @@ export declare interface SkeletonProps {
  */
 export declare function skipWaiting(worker: ServiceWorker): void;
 
+/**
+ * Convert a string into a URL-safe slug.
+ *
+ * - Strips accents/diacritics.
+ * - Lowercases.
+ * - Replaces non-alphanumeric runs with `-`.
+ * - Trims leading/trailing separators.
+ *
+ * @example
+ * slugify("São Paulo / Centro"); // "sao-paulo-centro"
+ */
+export declare function slugify(input: string): string;
+
 /**
  * Flex spacer — pushes siblings apart inside a flex container. Equivalent
  * to `<div style={{ flex: 1 }}>` but typed and intent-revealing.
@@ -2642,6 +2797,42 @@ export declare interface StepItem {
  */
 export declare function Stepper({ steps, current, orientation, className }: StepperProps): JSX.Element;
 
+/**
+ * Numeric +/− stepper. Common in checkout quantity selectors and admin
+ * forms. Clamps to `[min, max]` and emits already-bounded values.
+ *
+ * @example
+ * <StepperInput value={qty} onChange={setQty} min={1} max={10} />
+ */
+export declare const StepperInput: ForwardRefExoticComponent<StepperInputProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface StepperInputProps {
+    /** Current value. */
+    value: number;
+    /** Fires with the new value (already clamped to min/max). */
+    onChange: (value: number) => void;
+    /** Lower bound. Default `0`. */
+    min?: number;
+    /** Upper bound. Default `Number.POSITIVE_INFINITY`. */
+    max?: number;
+    /** Increment per click. Default `1`. */
+    step?: number;
+    /** Visual size. Default `"md"`. */
+    size?: "sm" | "md" | "lg";
+    /** Disable the whole control. */
+    disabled?: boolean;
+    /** Optional label rendered above. */
+    label?: ReactNode;
+    /** Optional formatter for the displayed value. */
+    format?: (value: number) => string;
+    /** Custom button labels for accessibility. */
+    labels?: {
+        decrement: string;
+        increment: string;
+    };
+    className?: string;
+}
+
 export declare interface StepperProps {
     steps: StepItem[];
     /** Index of the currently active step (0-based). */
@@ -2863,6 +3054,43 @@ export declare interface ThemeProviderProps {
     attribute?: string;
 }
 
+/**
+ * Vertical event timeline — activity feeds, order trackers, audit logs.
+ * Each entry has a marker (color or custom icon), title, optional
+ * description and right-aligned meta column.
+ *
+ * @example
+ * <Timeline items={[
+ *     { id: "1", title: "Pedido criado", meta: "10:24", marker: "primary" },
+ *     { id: "2", title: "Aprovação", meta: "10:25", marker: "success" },
+ *     { id: "3", title: "Saiu pra entrega", meta: "11:00", marker: "warning" },
+ * ]} />
+ */
+export declare function Timeline({ items, connector, className, ...props }: TimelineProps): JSX.Element;
+
+export declare interface TimelineItem {
+    /** Stable identifier (used as React key). */
+    id: string;
+    /** Title rendered as the entry headline. */
+    title: ReactNode;
+    /** Optional subtitle / description below the title. */
+    description?: ReactNode;
+    /** Right-aligned meta column (timestamps, durations). */
+    meta?: ReactNode;
+    /** Optional custom icon rendered inside the marker. */
+    icon?: ReactNode;
+    /** Marker color. Default `"primary"`. */
+    marker?: TimelineMarker;
+}
+
+export declare type TimelineMarker = "primary" | "success" | "warning" | "danger" | "neutral";
+
+export declare interface TimelineProps extends HTMLAttributes<HTMLOListElement> {
+    items: TimelineItem[];
+    /** Show the connecting line between markers. Default `true`. */
+    connector?: boolean;
+}
+
 export declare interface ToastApi {
     show: (options: ToastOptions) => string;
     dismiss: (id: string) => void;
@@ -2927,6 +3155,16 @@ export declare interface TooltipProps {
     openDelay?: number;
 }
 
+/**
+ * Truncate a string to `max` characters, appending `suffix` when cut.
+ * Returns the original when shorter than (or equal to) `max`.
+ *
+ * @example
+ * truncate("The quick brown fox", 12);              // "The quick…"
+ * truncate("The quick brown fox", 12, " (more)");   // "The qu (more)"
+ */
+export declare function truncate(input: string, max: number, suffix?: string): string;
+
 /** Strip any masking and return only digits. */
 export declare function unmask(value: string): string;
 
@@ -3211,6 +3449,17 @@ export declare interface UseGeolocationOptions extends PositionOptions {
     disabled?: boolean;
 }
 
+/**
+ * Track whether the pointer is hovering over the referenced element.
+ * Returns `false` on touch-only devices (no pointer hover).
+ *
+ * @example
+ * const ref = useRef<HTMLDivElement>(null);
+ * const hovered = useHover(ref);
+ * return <div ref={ref}>{hovered ? "✨" : ""}</div>;
+ */
+export declare function useHover<T extends HTMLElement>(ref: RefObject<T | null>): boolean;
+
 /**
  * Access translation helpers. Must be used inside an {@link I18nProvider}.
  */
@@ -3235,6 +3484,15 @@ export declare interface UseIntersectionObserverOptions extends IntersectionObse
     once?: boolean;
 }
 
+/**
+ * Reactive `setInterval`. Pass `null` as `delay` to pause. `fn` is stored in
+ * a ref so inline callbacks don't reset the interval on every render.
+ *
+ * @example
+ * useInterval(() => poll(), enabled ? 5000 : null);
+ */
+export declare function useInterval(fn: () => void, delay: number | null): void;
+
 /**
  * Bind a global keyboard shortcut. Supports modifier combinations and a
  * cross-OS `mod` key (Ctrl on Windows/Linux, Cmd on macOS).
@@ -3265,6 +3523,24 @@ export declare interface UseKeyboardShortcutOptions {
  */
 export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: LocalStorageOptions<T>): [T, (value: T | ((prev: T) => T)) => void, () => void];
 
+/**
+ * Detect long-press / long-tap gestures. Fires `fn` after `delay` ms
+ * while the element is held. Cancels on move beyond `moveThreshold` or
+ * pointer up before `delay`.
+ *
+ * @example
+ * const ref = useRef<HTMLDivElement>(null);
+ * useLongPress(ref, () => openContextMenu(), { delay: 600 });
+ */
+export declare function useLongPress<T extends HTMLElement>(ref: RefObject<T | null>, fn: () => void, options?: UseLongPressOptions): void;
+
+export declare interface UseLongPressOptions {
+    /** Press duration in ms. Default `500`. */
+    delay?: number;
+    /** Pixel threshold — finger/mouse movement beyond this cancels the press. Default `10`. */
+    moveThreshold?: number;
+}
+
 /**
  * Subscribe to a CSS media query and re-render on match changes.
  *
@@ -3371,6 +3647,19 @@ export declare interface UsePollResult<T> {
     start: () => void;
 }
 
+/**
+ * Return the value from the previous render. `undefined` on the first render.
+ *
+ * @example
+ * const previousCount = usePrevious(count);
+ * useEffect(() => {
+ *     if (previousCount !== undefined && previousCount !== count) {
+ *         analytics.track("count.changed", { from: previousCount, to: count });
+ *     }
+ * }, [count, previousCount]);
+ */
+export declare function usePrevious<T>(value: T): T | undefined;
+
 /**
  * React hook around {@link WebPushClient}. Tracks subscription, permission and
  * loading state; exposes imperative `subscribe`/`unsubscribe` actions.
@@ -3434,6 +3723,25 @@ export declare function useTelemetry(): TelemetryAdapter | null;
  */
 export declare function useTheme(): ThemeContextValue;
 
+/**
+ * Return a value that updates at most once every `delay` ms. Complements
+ * `useDebounce` — throttle emits on the leading edge and again after the
+ * interval; debounce only emits after a period of stillness.
+ *
+ * @example
+ * const throttledScroll = useThrottle(scrollY, 100);
+ */
+export declare function useThrottle<T>(value: T, delay: number): T;
+
+/**
+ * Run a callback after `delay` ms. Pass `null` to disable. Resets when
+ * `delay` changes; the callback ref always points at the latest closure.
+ *
+ * @example
+ * useTimeout(() => setShow(false), show ? 3000 : null);
+ */
+export declare function useTimeout(fn: () => void, delay: number | null): void;
+
 /**
  * Access the toast API. Must be used inside a {@link ToastProvider}.
  *
@@ -3493,6 +3801,16 @@ export declare interface UseWebSocketResult<T> {
     reconnect: () => void;
 }
 
+/**
+ * Reactive window dimensions. SSR-safe — returns `{ width: 0, height: 0 }`
+ * until the first client render.
+ *
+ * @example
+ * const { width, height } = useWindowSize();
+ * const columns = width < 640 ? 1 : width < 1024 ? 2 : 3;
+ */
+export declare function useWindowSize(): WindowSize;
+
 /**
  * Convenience wrapper around `react-hook-form`'s `useForm` that wires a zod
  * resolver and infers the form's value type from the schema.
@@ -3672,6 +3990,11 @@ export declare interface WebSocketMessage<T> {
 
 export declare type WebSocketStatus = "idle" | "connecting" | "open" | "closing" | "closed" | "error";
 
+export declare interface WindowSize {
+    width: number;
+    height: number;
+}
+
 /**
  * Minimal `react-hook-form` resolver built on top of zod. Mirrors the shape
  * produced by `@hookform/resolvers/zod` so it can be passed straight to