@skdx/react 0.26.0 → 0.28.0

package/dist/toast/Toaster.d.ts

@@ -1,30 +1,23 @@
 import * as React from 'react';
 import type { ToasterOptions, ToasterProps, ToasterStore, ToasterToast } from './types.js';
 /**
- * Default auto-dismiss duration (ms). WCAG 2.2.1 wants time limits to be
- * adjustable or long enough to read; 5s is the floor a short toast needs, and
- * the timer additionally pauses on hover, on focus, and while the page is
- * hidden, so the countdown only runs while the message is actually readable.
+ * Default auto-dismiss duration (ms). WCAG 2.2.1: 5s minimum for short toast.
+ * Timer pauses on hover, focus, or when page hidden.
  */
 export declare const DEFAULT_TOAST_DURATION = 5000;
 /**
- * Creates a toast queue: `create`/`update`/`dismiss`/`promise` callable from
- * anywhere in your app, `max` visible at a time with the rest waiting in FIFO
- * order. Create it once at module scope and render one {@link Toaster} for it.
+ * Creates toast queue with `create`/`update`/`dismiss`/`promise` methods.
+ * Max visible at once; rest queue in FIFO. Create once at module scope; render with Toaster.
  *
  * @example
  * ```ts
- * // toaster.ts
  * export const toaster = createToaster({ max: 3, placement: 'bottom-end' });
- *
- * // anywhere
  * toaster.create({ title: 'Saved', type: 'success' });
  * ```
  */
 export declare function createToaster(options?: ToasterOptions): ToasterStore;
 /**
- * Subscribes to a toaster's visible toasts. Only needed if you're rendering
- * the queue yourself instead of mounting {@link Toaster}.
+ * Subscribes to visible toasts; only needed for custom rendering.
  *
  * @example
  * ```tsx
@@ -33,14 +26,9 @@ export declare function createToaster(options?: ToasterOptions): ToasterStore;
  */
 export declare function useToaster(toaster: ToasterStore): readonly ToasterToast[];
 /**
- * Renders a {@link createToaster} queue: a `ToastProvider` + `ToastViewport`
- * region hosting one `Toast` per visible entry. Mount it once near the root
- * of your app; everything after that is imperative
- * (`toaster.create({ title })`) from anywhere.
- *
- * The viewport is a labelled `region` landmark: **F6** moves focus into it
- * from anywhere on the page, **Shift+F6** returns focus to where it was, and
- * focus is restored automatically when the toast holding it is removed.
+ * Renders queue as ToastProvider + ToastViewport region.
+ * Mount once near root; then use `toaster.create()` from anywhere.
+ * Viewport is `region` landmark: F6 enters, Shift+F6 returns; focus auto-restored on remove.
  *
  * @example
  * ```tsx

package/dist/toast/index.d.cts

@@ -1,10 +1,2 @@
-export * from './Toast.cjs';
-export { ToastProvider } from './ToastProvider.cjs';
-export { ToastViewport } from './ToastViewport.cjs';
-export { ToastTitle } from './ToastTitle.cjs';
-export { ToastDescription } from './ToastDescription.cjs';
-export { ToastAction } from './ToastAction.cjs';
-export { ToastClose } from './ToastClose.cjs';
 export { Toaster, createToaster, useToaster, DEFAULT_TOAST_DURATION } from './Toaster.cjs';
-export type { ToasterStore, ToasterOptions, ToasterProps, ToasterPromiseMessages, ToasterToast, ToasterToastAction, ToasterToastOptions, ToasterToastType, ToastPlacement, } from './types.cjs';
-export type { ToastProviderProps, ToastViewportProps, ToastProps, ToastTitleProps, ToastDescriptionProps, ToastActionProps, ToastCloseProps, } from './types.cjs';
+export type { ToasterProps, ToasterStore, ToasterOptions, ToasterPromiseMessages, ToasterToast, ToasterToastAction, ToasterToastOptions, ToasterToastType, ToastPlacement, } from './types.cjs';

package/dist/toast/index.d.ts

@@ -1,10 +1,2 @@
-export * from './Toast.js';
-export { ToastProvider } from './ToastProvider.js';
-export { ToastViewport } from './ToastViewport.js';
-export { ToastTitle } from './ToastTitle.js';
-export { ToastDescription } from './ToastDescription.js';
-export { ToastAction } from './ToastAction.js';
-export { ToastClose } from './ToastClose.js';
 export { Toaster, createToaster, useToaster, DEFAULT_TOAST_DURATION } from './Toaster.js';
-export type { ToasterStore, ToasterOptions, ToasterProps, ToasterPromiseMessages, ToasterToast, ToasterToastAction, ToasterToastOptions, ToasterToastType, ToastPlacement, } from './types.js';
-export type { ToastProviderProps, ToastViewportProps, ToastProps, ToastTitleProps, ToastDescriptionProps, ToastActionProps, ToastCloseProps, } from './types.js';
+export type { ToasterProps, ToasterStore, ToasterOptions, ToasterPromiseMessages, ToasterToast, ToasterToastAction, ToasterToastOptions, ToasterToastType, ToastPlacement, } from './types.js';

package/dist/toast/primitives.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Advanced primitives for `Toast` — the parts `Toaster` composes.
+ *
+ * @example
+ * ```tsx
+ * import { Toast, ToastAction, ToastClose, ToastDescription, ToastProvider, ToastTitle, ToastViewport } from '@skdx/react/primitives/toast';
+ *
+ * <ToastProvider duration={5000}>
+ *   <ToastViewport>
+ *     <Toast>
+ *       <ToastTitle>Message sent</ToastTitle>
+ *       <ToastDescription>Your message was delivered.</ToastDescription>
+ *       <ToastAction altText="Undo sending the message">Undo</ToastAction>
+ *       <ToastClose />
+ *     </Toast>
+ *   </ToastViewport>
+ * </ToastProvider>
+ * ```
+ */
+export { Toast } from './Toast.cjs';
+export { ToastProvider } from './ToastProvider.cjs';
+export { ToastViewport } from './ToastViewport.cjs';
+export { ToastTitle } from './ToastTitle.cjs';
+export { ToastDescription } from './ToastDescription.cjs';
+export { ToastAction } from './ToastAction.cjs';
+export { ToastClose } from './ToastClose.cjs';
+export type { ToastProps, ToastProviderProps, ToastViewportProps, ToastTitleProps, ToastDescriptionProps, ToastActionProps, ToastCloseProps, } from './types.cjs';

package/dist/toast/primitives.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Advanced primitives for `Toast` — the parts `Toaster` composes.
+ *
+ * @example
+ * ```tsx
+ * import { Toast, ToastAction, ToastClose, ToastDescription, ToastProvider, ToastTitle, ToastViewport } from '@skdx/react/primitives/toast';
+ *
+ * <ToastProvider duration={5000}>
+ *   <ToastViewport>
+ *     <Toast>
+ *       <ToastTitle>Message sent</ToastTitle>
+ *       <ToastDescription>Your message was delivered.</ToastDescription>
+ *       <ToastAction altText="Undo sending the message">Undo</ToastAction>
+ *       <ToastClose />
+ *     </Toast>
+ *   </ToastViewport>
+ * </ToastProvider>
+ * ```
+ */
+export { Toast } from './Toast.js';
+export { ToastProvider } from './ToastProvider.js';
+export { ToastViewport } from './ToastViewport.js';
+export { ToastTitle } from './ToastTitle.js';
+export { ToastDescription } from './ToastDescription.js';
+export { ToastAction } from './ToastAction.js';
+export { ToastClose } from './ToastClose.js';
+export type { ToastProps, ToastProviderProps, ToastViewportProps, ToastTitleProps, ToastDescriptionProps, ToastActionProps, ToastCloseProps, } from './types.js';

package/dist/toast/region-focus.d.cts

@@ -1,13 +1,19 @@
+/**
+ * The region's entry shortcut when nothing sets one (F6 by default).
+ */
+export declare const DEFAULT_TOAST_HOTKEY: readonly string[];
+/**
+ * The hotkey as announced in the region's accessible name. Shortcuts must be
+ * announced or keyboard users won't find them.
+ */
+export declare function formatHotkey(hotkey: readonly string[]): string;
 /**
  * Wires the toast region's keyboard traversal and focus recovery onto
  * `node`, and returns its own teardown.
  *
- * A toast never steals focus, so a keyboard user needs a way in: **F6** moves
- * focus to the region from anywhere on the page and **Shift+F6** returns it
- * to wherever it came from — the same landmark-hopping shortcut browsers use,
- * and what React Aria's toast spec prescribes. Focus is also restored
- * automatically when the toast currently holding it is removed (the
- * last-toast-closed case), which otherwise drops focus to `<body>` and loses
- * the user's place entirely.
+ * Toast doesn't steal focus, so keyboard users need a way in: the `hotkey`
+ * (**F6** by default) moves focus to it, and **Shift + hotkey** moves back.
+ * Focus is also restored when the focused toast is removed, which otherwise
+ * drops focus to `<body>`. The hotkey is configurable to avoid collisions.
  */
-export declare function wireRegionFocus(node: HTMLElement): () => void;
+export declare function wireRegionFocus(node: HTMLElement, hotkey?: readonly string[]): () => void;

package/dist/toast/region-focus.d.ts

@@ -1,13 +1,19 @@
+/**
+ * The region's entry shortcut when nothing sets one (F6 by default).
+ */
+export declare const DEFAULT_TOAST_HOTKEY: readonly string[];
+/**
+ * The hotkey as announced in the region's accessible name. Shortcuts must be
+ * announced or keyboard users won't find them.
+ */
+export declare function formatHotkey(hotkey: readonly string[]): string;
 /**
  * Wires the toast region's keyboard traversal and focus recovery onto
  * `node`, and returns its own teardown.
  *
- * A toast never steals focus, so a keyboard user needs a way in: **F6** moves
- * focus to the region from anywhere on the page and **Shift+F6** returns it
- * to wherever it came from — the same landmark-hopping shortcut browsers use,
- * and what React Aria's toast spec prescribes. Focus is also restored
- * automatically when the toast currently holding it is removed (the
- * last-toast-closed case), which otherwise drops focus to `<body>` and loses
- * the user's place entirely.
+ * Toast doesn't steal focus, so keyboard users need a way in: the `hotkey`
+ * (**F6** by default) moves focus to it, and **Shift + hotkey** moves back.
+ * Focus is also restored when the focused toast is removed, which otherwise
+ * drops focus to `<body>`. The hotkey is configurable to avoid collisions.
  */
-export declare function wireRegionFocus(node: HTMLElement): () => void;
+export declare function wireRegionFocus(node: HTMLElement, hotkey?: readonly string[]): () => void;

package/dist/toast/types.d.cts

@@ -4,15 +4,23 @@ import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 export interface ToastProviderContextValue {
     label: string;
     duration: number;
+    /** Swipe direction to dismiss (resolved per toast's writing direction). */
+    swipeDirection: ToastSwipeDirection;
+    /** Distance in px along `swipeDirection` before drag dismisses. */
+    swipeThreshold: number;
     viewportRef: React.RefObject<HTMLDivElement | null>;
-    /** Copies a toast's text into a persistent live region so screen readers reliably announce it. */
+    /** Copies toast text into live region for screen-reader announcement. */
     announce: (message: string, priority: 'polite' | 'assertive') => void;
 }
-/** Props for {@link ToastProvider}, the app-level ancestor that supplies default duration and the accessible announcer. */
+/** Swipe direction to dismiss toast (`'start'` / `'end'` logical, others physical). */
+export type ToastSwipeDirection = 'up' | 'down' | 'left' | 'right' | 'start' | 'end';
+/** Swipe phase (published as `data-swipe` on root). */
+export type ToastSwipePhase = 'start' | 'move' | 'cancel' | 'end';
+/** Props for {@link ToastProvider}} (app-level ancestor with duration and announcer). */
 export interface ToastProviderProps {
     /**
      * The app subtree that renders `ToastViewport` and any mounted `Toast`s.
-     * @default undefined — renders nothing.
+     * @default undefined
      */
     children?: React.ReactNode;
     /**
@@ -21,18 +29,46 @@ export interface ToastProviderProps {
      */
     label?: string;
     /**
-     * Default auto-dismiss duration (ms), used by any `Toast` that doesn't set
-     * its own `duration`.
+     * Default auto-dismiss duration (ms), used by toasts without their own setting.
      * @default 5000
      */
     duration?: number;
+    /**
+     * Swipe direction to dismiss (`'start'` / `'end'` mirror under RTL; gesture is addition to close button / Escape / timer, not replacement per WCAG 2.2.1).
+     * @default 'end'
+     */
+    swipeDirection?: ToastSwipeDirection;
+    /**
+     * Distance in px along `swipeDirection` before drag dismisses.
+     * @default 50
+     */
+    swipeThreshold?: number;
 }
 /** Props for {@link ToastViewport}, the fixed region that hosts and orders rendered toasts. */
 export interface ToastViewportProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Keys that move focus into the region from anywhere on the page, and (with `Shift`) back out again.
+     *
+     * Every entry but the last is a modifier — `'Alt'`, `'Control'`, `'Meta'` —
+     * and the last is the `KeyboardEvent.key` value. `Shift` is not available as
+     * a modifier: `Shift` + the hotkey is the traversal out. The resolved
+     * combination is appended to the region's accessible name
+     * (`"Notifications (F6)"`), since a toast never steals focus.
+     * @default ['F6']
+     */
+    hotkey?: readonly string[];
 }
 /** @internal Shared state distributed from a single {@link Toast} to its parts via context. Not part of the public API. */
 export interface ToastContextValue {
     onClose: () => void;
+    /** Id `ToastTitle` renders with; root's `aria-labelledby` once mounted. */
+    titleId: string;
+    /** Id `ToastDescription` renders with; root's `aria-describedby` once mounted. */
+    descriptionId: string;
+    /** Called by `ToastTitle` on mount/unmount (prevents dangling `aria-labelledby`). */
+    setHasTitle: (present: boolean) => void;
+    /** Called by `ToastDescription` on mount/unmount (prevents dangling `aria-describedby`). */
+    setHasDescription: (present: boolean) => void;
 }
 /** Props for a single {@link Toast} notification. Mount one per notification. */
 export interface ToastProps extends PrimitivePropsWithRef<'div'> {
@@ -42,29 +78,50 @@ export interface ToastProps extends PrimitivePropsWithRef<'div'> {
      */
     open?: boolean;
     /**
-     * Whether the toast is initially open, for uncontrolled usage — since a
-     * toast is typically mounted already-visible.
+     * Whether the toast is initially open, for uncontrolled usage.
      * @default true
      */
     defaultOpen?: boolean;
     /**
-     * Fires with the new open state whenever the toast opens or closes, controlled or not. Drop the toast from your state here when it becomes `false`.
+     * Fires with new open state (drop toast from state when becomes false).
      * @default undefined — no-op.
      */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Auto-dismiss duration (ms). `Infinity` disables auto-dismiss. Falls
-     * back to the ancestor `ToastProvider`'s `duration` when unset. The timer
-     * pauses while the toast is hovered or focused.
-     * @default undefined — falls back to the ancestor `ToastProvider`'s `duration`.
+     * Fires once open-state change finishes (after animation); where `forceMount`ed toast drops from state.
+     * @default undefined — no-op.
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
+    /**
+     * Keep toast in DOM while closed (for exit animation `data-state="closed"`).
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Auto-dismiss duration (ms); `Infinity` disables; pauses on hover / focus.
+     * @default undefined — falls back to `ToastProvider`'s `duration`.
      */
     duration?: number;
     /**
-     * `'foreground'` interrupts the user (announced `assertive`);
-     * `'background'` does not (announced `polite`).
-     * @default 'foreground'
+     * Which live region text copies to (`'assertive'` for errors/warnings user must act on, `'polite'` otherwise).
+     * @default 'background'
      */
     type?: 'foreground' | 'background';
+    /**
+     * Fires on Escape (call `preventDefault()` to keep open).
+     * @default undefined — no-op.
+     */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /**
+     * Fires when timer pauses (held by hover / focus / hidden page; edge-triggered).
+     * @default undefined — no-op.
+     */
+    onPause?: () => void;
+    /**
+     * Callback fired when auto-dismiss timer restarts on remaining time.
+     * @default undefined — no-op.
+     */
+    onResume?: () => void;
 }
 /** Props for {@link ToastTitle}, the toast's heading. */
 export interface ToastTitleProps extends PrimitivePropsWithRef<'div'> {
@@ -85,7 +142,7 @@ export interface ToastCloseProps extends PrimitivePropsWithRef<'button'> {
  * viewport — headless, so the design layer does the actual positioning.
  */
 export type ToastPlacement = 'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end';
-/** Semantic kind of a queued toast. Drives `data-type`, the root's role, and live-region politeness. */
+/** Semantic kind of a queued toast. Drives `data-type` and which of the announcer's two live regions reads it. */
 export type ToasterToastType = 'info' | 'success' | 'warning' | 'error' | 'loading';
 /** An actionable button rendered inside a queued toast (the "Undo" affordance). */
 export interface ToasterToastAction {
@@ -99,8 +156,7 @@ export interface ToasterToastAction {
 /** What {@link ToasterStore.create} and {@link ToasterStore.update} accept. */
 export interface ToasterToastOptions {
     /**
-     * Stable id, so a later `update`/`dismiss` can address this toast. Creating
-     * with an id that is already queued replaces that entry in place.
+     * Stable id, so a later `update`/`dismiss` can address this toast; reusing a queued id replaces that entry.
      * @default undefined — generated.
      */
     id?: string;
@@ -124,18 +180,13 @@ export interface ToasterToastOptions {
 export interface ToasterToast extends ToasterToastOptions {
     id: string;
     type: ToasterToastType;
-    /**
-     * Bumped on every `update`. Renderers key on `id:revision`, so an updated
-     * toast remounts — which is what re-announces the new text and restarts the
-     * auto-dismiss timer for the message the user is now actually reading.
-     */
+    /** Bumped on every `update`; renderers key on `id:revision`, so an updated toast remounts and re-announces. */
     revision: number;
 }
 /** Options for {@link createToaster}. */
 export interface ToasterOptions {
     /**
-     * How many toasts are visible at once; the rest wait in FIFO order and
-     * appear as visible ones are dismissed.
+     * How many toasts are visible at once; the rest wait in FIFO order.
      * @default 3
      */
     max?: number;
@@ -156,9 +207,7 @@ export interface ToasterPromiseMessages<T> {
     error: ToasterToastOptions | ((error: unknown) => ToasterToastOptions);
 }
 /**
- * An imperative toast queue: app code calls `create`/`dismiss` from anywhere
- * (no React tree, no hook), and a mounted {@link Toaster} renders whatever is
- * currently visible.
+ * An imperative toast queue callable from anywhere with no React tree or hook, rendered by a mounted {@link Toaster}.
  */
 export interface ToasterStore {
     /** See {@link ToasterOptions.max}. */

package/dist/toast/types.d.ts

@@ -4,15 +4,23 @@ import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 export interface ToastProviderContextValue {
     label: string;
     duration: number;
+    /** Swipe direction to dismiss (resolved per toast's writing direction). */
+    swipeDirection: ToastSwipeDirection;
+    /** Distance in px along `swipeDirection` before drag dismisses. */
+    swipeThreshold: number;
     viewportRef: React.RefObject<HTMLDivElement | null>;
-    /** Copies a toast's text into a persistent live region so screen readers reliably announce it. */
+    /** Copies toast text into live region for screen-reader announcement. */
     announce: (message: string, priority: 'polite' | 'assertive') => void;
 }
-/** Props for {@link ToastProvider}, the app-level ancestor that supplies default duration and the accessible announcer. */
+/** Swipe direction to dismiss toast (`'start'` / `'end'` logical, others physical). */
+export type ToastSwipeDirection = 'up' | 'down' | 'left' | 'right' | 'start' | 'end';
+/** Swipe phase (published as `data-swipe` on root). */
+export type ToastSwipePhase = 'start' | 'move' | 'cancel' | 'end';
+/** Props for {@link ToastProvider}} (app-level ancestor with duration and announcer). */
 export interface ToastProviderProps {
     /**
      * The app subtree that renders `ToastViewport` and any mounted `Toast`s.
-     * @default undefined — renders nothing.
+     * @default undefined
      */
     children?: React.ReactNode;
     /**
@@ -21,18 +29,46 @@ export interface ToastProviderProps {
      */
     label?: string;
     /**
-     * Default auto-dismiss duration (ms), used by any `Toast` that doesn't set
-     * its own `duration`.
+     * Default auto-dismiss duration (ms), used by toasts without their own setting.
      * @default 5000
      */
     duration?: number;
+    /**
+     * Swipe direction to dismiss (`'start'` / `'end'` mirror under RTL; gesture is addition to close button / Escape / timer, not replacement per WCAG 2.2.1).
+     * @default 'end'
+     */
+    swipeDirection?: ToastSwipeDirection;
+    /**
+     * Distance in px along `swipeDirection` before drag dismisses.
+     * @default 50
+     */
+    swipeThreshold?: number;
 }
 /** Props for {@link ToastViewport}, the fixed region that hosts and orders rendered toasts. */
 export interface ToastViewportProps extends PrimitivePropsWithRef<'div'> {
+    /**
+     * Keys that move focus into the region from anywhere on the page, and (with `Shift`) back out again.
+     *
+     * Every entry but the last is a modifier — `'Alt'`, `'Control'`, `'Meta'` —
+     * and the last is the `KeyboardEvent.key` value. `Shift` is not available as
+     * a modifier: `Shift` + the hotkey is the traversal out. The resolved
+     * combination is appended to the region's accessible name
+     * (`"Notifications (F6)"`), since a toast never steals focus.
+     * @default ['F6']
+     */
+    hotkey?: readonly string[];
 }
 /** @internal Shared state distributed from a single {@link Toast} to its parts via context. Not part of the public API. */
 export interface ToastContextValue {
     onClose: () => void;
+    /** Id `ToastTitle` renders with; root's `aria-labelledby` once mounted. */
+    titleId: string;
+    /** Id `ToastDescription` renders with; root's `aria-describedby` once mounted. */
+    descriptionId: string;
+    /** Called by `ToastTitle` on mount/unmount (prevents dangling `aria-labelledby`). */
+    setHasTitle: (present: boolean) => void;
+    /** Called by `ToastDescription` on mount/unmount (prevents dangling `aria-describedby`). */
+    setHasDescription: (present: boolean) => void;
 }
 /** Props for a single {@link Toast} notification. Mount one per notification. */
 export interface ToastProps extends PrimitivePropsWithRef<'div'> {
@@ -42,29 +78,50 @@ export interface ToastProps extends PrimitivePropsWithRef<'div'> {
      */
     open?: boolean;
     /**
-     * Whether the toast is initially open, for uncontrolled usage — since a
-     * toast is typically mounted already-visible.
+     * Whether the toast is initially open, for uncontrolled usage.
      * @default true
      */
     defaultOpen?: boolean;
     /**
-     * Fires with the new open state whenever the toast opens or closes, controlled or not. Drop the toast from your state here when it becomes `false`.
+     * Fires with new open state (drop toast from state when becomes false).
      * @default undefined — no-op.
      */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Auto-dismiss duration (ms). `Infinity` disables auto-dismiss. Falls
-     * back to the ancestor `ToastProvider`'s `duration` when unset. The timer
-     * pauses while the toast is hovered or focused.
-     * @default undefined — falls back to the ancestor `ToastProvider`'s `duration`.
+     * Fires once open-state change finishes (after animation); where `forceMount`ed toast drops from state.
+     * @default undefined — no-op.
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
+    /**
+     * Keep toast in DOM while closed (for exit animation `data-state="closed"`).
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Auto-dismiss duration (ms); `Infinity` disables; pauses on hover / focus.
+     * @default undefined — falls back to `ToastProvider`'s `duration`.
      */
     duration?: number;
     /**
-     * `'foreground'` interrupts the user (announced `assertive`);
-     * `'background'` does not (announced `polite`).
-     * @default 'foreground'
+     * Which live region text copies to (`'assertive'` for errors/warnings user must act on, `'polite'` otherwise).
+     * @default 'background'
      */
     type?: 'foreground' | 'background';
+    /**
+     * Fires on Escape (call `preventDefault()` to keep open).
+     * @default undefined — no-op.
+     */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /**
+     * Fires when timer pauses (held by hover / focus / hidden page; edge-triggered).
+     * @default undefined — no-op.
+     */
+    onPause?: () => void;
+    /**
+     * Callback fired when auto-dismiss timer restarts on remaining time.
+     * @default undefined — no-op.
+     */
+    onResume?: () => void;
 }
 /** Props for {@link ToastTitle}, the toast's heading. */
 export interface ToastTitleProps extends PrimitivePropsWithRef<'div'> {
@@ -85,7 +142,7 @@ export interface ToastCloseProps extends PrimitivePropsWithRef<'button'> {
  * viewport — headless, so the design layer does the actual positioning.
  */
 export type ToastPlacement = 'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end';
-/** Semantic kind of a queued toast. Drives `data-type`, the root's role, and live-region politeness. */
+/** Semantic kind of a queued toast. Drives `data-type` and which of the announcer's two live regions reads it. */
 export type ToasterToastType = 'info' | 'success' | 'warning' | 'error' | 'loading';
 /** An actionable button rendered inside a queued toast (the "Undo" affordance). */
 export interface ToasterToastAction {
@@ -99,8 +156,7 @@ export interface ToasterToastAction {
 /** What {@link ToasterStore.create} and {@link ToasterStore.update} accept. */
 export interface ToasterToastOptions {
     /**
-     * Stable id, so a later `update`/`dismiss` can address this toast. Creating
-     * with an id that is already queued replaces that entry in place.
+     * Stable id, so a later `update`/`dismiss` can address this toast; reusing a queued id replaces that entry.
      * @default undefined — generated.
      */
     id?: string;
@@ -124,18 +180,13 @@ export interface ToasterToastOptions {
 export interface ToasterToast extends ToasterToastOptions {
     id: string;
     type: ToasterToastType;
-    /**
-     * Bumped on every `update`. Renderers key on `id:revision`, so an updated
-     * toast remounts — which is what re-announces the new text and restarts the
-     * auto-dismiss timer for the message the user is now actually reading.
-     */
+    /** Bumped on every `update`; renderers key on `id:revision`, so an updated toast remounts and re-announces. */
     revision: number;
 }
 /** Options for {@link createToaster}. */
 export interface ToasterOptions {
     /**
-     * How many toasts are visible at once; the rest wait in FIFO order and
-     * appear as visible ones are dismissed.
+     * How many toasts are visible at once; the rest wait in FIFO order.
      * @default 3
      */
     max?: number;
@@ -156,9 +207,7 @@ export interface ToasterPromiseMessages<T> {
     error: ToasterToastOptions | ((error: unknown) => ToasterToastOptions);
 }
 /**
- * An imperative toast queue: app code calls `create`/`dismiss` from anywhere
- * (no React tree, no hook), and a mounted {@link Toaster} renders whatever is
- * currently visible.
+ * An imperative toast queue callable from anywhere with no React tree or hook, rendered by a mounted {@link Toaster}.
  */
 export interface ToasterStore {
     /** See {@link ToasterOptions.max}. */

package/dist/toggle/Toggle.cjs

@@ -1 +1 @@
-"use strict";var P=Object.create;var s=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var y=Object.getPrototypeOf,T=Object.prototype.hasOwnProperty;var C=(e,o)=>{for(var t in o)s(e,t,{get:o[t],enumerable:!0})},f=(e,o,t,r)=>{if(o&&typeof o=="object"||typeof o=="function")for(let a of u(o))!T.call(e,a)&&a!==t&&s(e,a,{get:()=>o[a],enumerable:!(r=b(o,a))||r.enumerable});return e};var k=(e,o,t)=>(t=e!=null?P(y(e)):{},f(o||!e||!e.__esModule?s(t,"default",{value:e,enumerable:!0}):t,e)),x=e=>f(s({},"__esModule",{value:!0}),e);var R={};C(R,{Toggle:()=>p});module.exports=x(R);var i=k(require("react"),1),m=require("../utils/part.cjs"),l=require("../utils/primitive.cjs"),n=require("../utils/useControllableState.cjs"),g=require("react/jsx-runtime"),p=i.forwardRef(({pressed:e,defaultPressed:o=!1,onPressedChange:t,...r},a)=>{let[d=!1,c]=(0,n.useControllableState)({prop:e,defaultProp:o,onChange:t});return(0,g.jsx)(l.Primitive.button,{type:"button","aria-pressed":d,"data-state":d?"on":"off","data-disabled":r.disabled?"":void 0,...r,...(0,m.skdxPart)("toggle","root",r.className),ref:a,onClick:(0,l.composeEventHandlers)(r.onClick,()=>{r.disabled||c(!d)})})});p.displayName="Toggle";0&&(module.exports={Toggle});
+"use strict";var P=Object.create;var d=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var T=Object.getOwnPropertyNames;var C=Object.getPrototypeOf,k=Object.prototype.hasOwnProperty;var v=(e,t)=>{for(var o in t)d(e,o,{get:t[o],enumerable:!0})},i=(e,t,o,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of T(t))!k.call(e,a)&&a!==o&&d(e,a,{get:()=>t[a],enumerable:!(r=y(t,a))||r.enumerable});return e};var x=(e,t,o)=>(o=e!=null?P(C(e)):{},i(t||!e||!e.__esModule?d(o,"default",{value:e,enumerable:!0}):o,e)),R=e=>i(d({},"__esModule",{value:!0}),e);var h={};v(h,{Toggle:()=>p});module.exports=R(h);var n=x(require("react"),1),f=require("../utils/part.cjs"),s=require("../utils/primitive.cjs"),m=require("../utils/useControllableState.cjs"),g=require("react/jsx-runtime"),p=n.forwardRef(({pressed:e,defaultPressed:t=!1,onPressedChange:o,...r},a)=>{let[l=!1,u]=(0,m.useControllableState)({prop:e,defaultProp:t,onChange:o}),c=r.asChild===!0;return(0,g.jsx)(s.Primitive.button,{type:"button","aria-pressed":l,"aria-disabled":c&&r.disabled?!0:void 0,"data-state":l?"on":"off","data-disabled":r.disabled?"":void 0,...r,...(0,f.skdxPart)("toggle","root",r.className),ref:a,onClick:(0,s.composeEventHandlers)(r.onClick,b=>{if(r.disabled){b.preventDefault();return}u(!l)})})});p.displayName="Toggle";0&&(module.exports={Toggle});

package/dist/toggle/Toggle.d.cts

@@ -1,10 +1,8 @@
 import * as React from 'react';
 import type { ToggleProps } from './types.cjs';
 /**
- * A two-state button (e.g. bold in a toolbar). Renders `<button aria-pressed
- * data-state data-disabled>`; toggles `pressed` on click (Space/Enter
- * activation is native `<button>` behavior). Works controlled (`pressed` +
- * `onPressedChange`) or uncontrolled (`defaultPressed`).
+ * Two-state button: renders `<button aria-pressed data-state data-disabled>`,
+ * toggles on click (native Space/Enter activation). Works controlled or uncontrolled.
  *
  * @example
  * ```tsx
@@ -12,5 +10,12 @@ import type { ToggleProps } from './types.cjs';
  *   B
  * </Toggle>
  * ```
+ *
+ * @example With `asChild`, `disabled` binds through `aria-disabled` (native `disabled` ignored on `<a>`):
+ * ```tsx
+ * <Toggle asChild disabled>
+ *   <a href="/docs">Docs</a>
+ * </Toggle>
+ * ```
  */
 export declare const Toggle: React.ForwardRefExoticComponent<Omit<ToggleProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/toggle/Toggle.d.ts

@@ -1,10 +1,8 @@
 import * as React from 'react';
 import type { ToggleProps } from './types.js';
 /**
- * A two-state button (e.g. bold in a toolbar). Renders `<button aria-pressed
- * data-state data-disabled>`; toggles `pressed` on click (Space/Enter
- * activation is native `<button>` behavior). Works controlled (`pressed` +
- * `onPressedChange`) or uncontrolled (`defaultPressed`).
+ * Two-state button: renders `<button aria-pressed data-state data-disabled>`,
+ * toggles on click (native Space/Enter activation). Works controlled or uncontrolled.
  *
  * @example
  * ```tsx
@@ -12,5 +10,12 @@ import type { ToggleProps } from './types.js';
  *   B
  * </Toggle>
  * ```
+ *
+ * @example With `asChild`, `disabled` binds through `aria-disabled` (native `disabled` ignored on `<a>`):
+ * ```tsx
+ * <Toggle asChild disabled>
+ *   <a href="/docs">Docs</a>
+ * </Toggle>
+ * ```
  */
 export declare const Toggle: React.ForwardRefExoticComponent<Omit<ToggleProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;