entangle-ui 0.7.0 → 0.8.0

package/dist/types/components/primitives/VisuallyHidden/VisuallyHidden.types.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+/**
+ * HTML element types that VisuallyHidden can render as.
+ *
+ * Most cases use `span` (default). Use `div` when wrapping block content,
+ * `label` for form labels, `p` for prose.
+ */
+type VisuallyHiddenElement = 'span' | 'div' | 'label' | 'p';
+interface VisuallyHiddenBaseProps extends BaseComponent<HTMLSpanElement> {
+    /**
+     * HTML element to render as.
+     * @default "span"
+     */
+    as?: VisuallyHiddenElement;
+    /**
+     * When true, the element becomes visible when it (or any descendant)
+     * receives focus. Used for skip-to-content links.
+     * @default false
+     */
+    focusable?: boolean;
+    /** Content rendered inside the hidden region. */
+    children: React.ReactNode;
+}
+type VisuallyHiddenProps = Prettify<VisuallyHiddenBaseProps>;
+
+export type { VisuallyHiddenBaseProps, VisuallyHiddenElement, VisuallyHiddenProps };

package/dist/types/hooks/useClickOutside/useClickOutside.d.ts

@@ -0,0 +1,37 @@
+import { RefObject } from 'react';
+
+interface UseClickOutsideOptions {
+    /**
+     * When false, the listener is not attached. Useful for toggling without
+     * unmount.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Mouse / pointer event to listen for.
+     * @default 'mousedown'
+     */
+    event?: 'mousedown' | 'click' | 'pointerdown';
+}
+/**
+ * Fire a callback when a click occurs outside the referenced element(s).
+ *
+ * Accepts either a single ref or an array of refs. The handler fires only
+ * when the click lands outside ALL provided refs — useful for popover +
+ * trigger pairs where clicking either should be considered "inside".
+ *
+ * Defaults to `mousedown` so the handler runs before `click`. SSR-safe;
+ * cleans up on unmount and when `enabled` flips to `false`.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null);
+ * useClickOutside(ref, () => setOpen(false), { enabled: isOpen });
+ *
+ * return <div ref={ref}>...</div>;
+ * ```
+ */
+declare function useClickOutside<T extends HTMLElement = HTMLElement>(ref: RefObject<T | null> | Array<RefObject<HTMLElement | null>>, handler: (event: MouseEvent) => void, options?: UseClickOutsideOptions): void;
+
+export { useClickOutside };
+export type { UseClickOutsideOptions };

package/dist/types/hooks/useClipboard/useClipboard.d.ts

@@ -0,0 +1,24 @@
+import { UseClipboardOptions, UseClipboardReturn } from './useClipboard.types.js';
+
+/**
+ * Copy text to the clipboard with a built-in timeout-driven feedback state.
+ *
+ * Uses `navigator.clipboard.writeText` when available; falls back to
+ * `document.execCommand('copy')` only when the modern API is missing.
+ * In SSR or restricted contexts where neither path is available, `copy`
+ * resolves to `false` and `status` flips to `'error'` without throwing.
+ *
+ * @example
+ * ```tsx
+ * const { copy, copied } = useClipboard({ timeout: 1500 });
+ *
+ * return (
+ *   <Button onClick={() => copy('Hello!')}>
+ *     {copied ? 'Copied!' : 'Copy'}
+ *   </Button>
+ * );
+ * ```
+ */
+declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;
+
+export { useClipboard };

package/dist/types/hooks/useClipboard/useClipboard.types.d.ts

@@ -0,0 +1,22 @@
+type ClipboardStatus = 'idle' | 'copied' | 'error';
+interface UseClipboardOptions {
+    /**
+     * How long the `copied` state stays before resetting to `idle`, in ms.
+     * @default 2000
+     */
+    timeout?: number;
+}
+interface UseClipboardReturn {
+    /** Current state — flips to 'copied' for `timeout` ms after a successful copy. */
+    status: ClipboardStatus;
+    /** Convenience boolean — `status === 'copied'`. */
+    copied: boolean;
+    /** Last error from a failed copy attempt, if any. */
+    error: Error | null;
+    /** Copy text to clipboard. Returns the resolved success boolean. */
+    copy: (text: string) => Promise<boolean>;
+    /** Manually reset status to 'idle'. */
+    reset: () => void;
+}
+
+export type { ClipboardStatus, UseClipboardOptions, UseClipboardReturn };

package/dist/types/hooks/useControlledState/useControlledState.d.ts

@@ -0,0 +1,38 @@
+interface UseControlledStateOptions<T> {
+    /** Controlled value — when defined, drives the returned value. */
+    value?: T;
+    /** Default value used when the hook is uncontrolled. */
+    defaultValue?: T;
+    /** Called when the consumer requests a change in either mode. */
+    onChange?: (value: T) => void;
+    /** Fallback used when both `value` and `defaultValue` are undefined. */
+    fallback: T;
+}
+/**
+ * Manage a value that may be either controlled (via prop) or uncontrolled
+ * (managed internally with a default).
+ *
+ * Returns a `[value, setValue]` tuple just like `useState`. When
+ * `options.value` is defined the state is read from there and `setValue`
+ * becomes a pure side-effect callback that calls `onChange` only — internal
+ * state is never mutated. When `options.value` is undefined the hook owns the
+ * state and `setValue` updates it as well as calls `onChange`.
+ *
+ * Switching between controlled and uncontrolled within a component's lifetime
+ * is a known pitfall (matches React's own warning for `<input value/defaultValue>`).
+ * The hook emits a development-only warning when this happens.
+ *
+ * @example
+ * ```ts
+ * const [value, setValue] = useControlledState({
+ *   value: props.value,
+ *   defaultValue: props.defaultValue,
+ *   onChange: props.onChange,
+ *   fallback: '',
+ * });
+ * ```
+ */
+declare function useControlledState<T>(options: UseControlledStateOptions<T>): [T, (next: T | ((prev: T) => T)) => void];
+
+export { useControlledState };
+export type { UseControlledStateOptions };

package/dist/types/hooks/useDisclosure/useDisclosure.d.ts

@@ -0,0 +1,25 @@
+import { UseDisclosureOptions, UseDisclosureReturn } from './useDisclosure.types.js';
+
+/**
+ * Manage an open/closed state with stable `open`, `close`, `toggle` callbacks.
+ *
+ * Supports both controlled (driven by an `open` prop) and uncontrolled
+ * (managed internally with `defaultOpen`) modes. Built on top of
+ * `useControlledState` so the same controlled / uncontrolled rules apply —
+ * including the development warning when switching modes mid-life.
+ *
+ * @example
+ * ```tsx
+ * const { isOpen, open, close, toggle } = useDisclosure();
+ *
+ * return (
+ *   <>
+ *     <Button onClick={open}>Open</Button>
+ *     <Dialog open={isOpen} onClose={close}>...</Dialog>
+ *   </>
+ * );
+ * ```
+ */
+declare function useDisclosure(options?: UseDisclosureOptions): UseDisclosureReturn;
+
+export { useDisclosure };

package/dist/types/hooks/useDisclosure/useDisclosure.types.d.ts

@@ -0,0 +1,22 @@
+interface UseDisclosureOptions {
+    /** Initial state for uncontrolled mode. @default false */
+    defaultOpen?: boolean;
+    /** Controlled value — when defined, drives the returned state. */
+    open?: boolean;
+    /** Called when state changes (from either controlled or uncontrolled paths). */
+    onOpenChange?: (open: boolean) => void;
+}
+interface UseDisclosureReturn {
+    /** Current open state. */
+    isOpen: boolean;
+    /** Set open to `true`. */
+    open: () => void;
+    /** Set open to `false`. */
+    close: () => void;
+    /** Flip current open state. */
+    toggle: () => void;
+    /** Set open to an explicit value. */
+    setOpen: (next: boolean) => void;
+}
+
+export type { UseDisclosureOptions, UseDisclosureReturn };

package/dist/types/hooks/useFocusTrap/useFocusTrap.d.ts

@@ -0,0 +1,30 @@
+import { RefObject, KeyboardEvent } from 'react';
+
+interface UseFocusTrapOptions {
+    /** Ref to the container element whose focusable descendants are trapped. */
+    containerRef: RefObject<HTMLElement | null>;
+    /**
+     * When false, the trap is bypassed (Tab works normally). Useful for toggling
+     * trap state without unmounting.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Trap focus within a container element. Tab and Shift+Tab cycle through the
+ * focusable descendants without escaping the container.
+ *
+ * Returns a keyboard event handler to attach to the container's `onKeyDown`.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null);
+ * const handleKeyDown = useFocusTrap({ containerRef: ref, enabled: isOpen });
+ *
+ * return <div ref={ref} onKeyDown={handleKeyDown}>...</div>;
+ * ```
+ */
+declare function useFocusTrap({ containerRef, enabled, }: UseFocusTrapOptions): (event: KeyboardEvent) => void;
+
+export { useFocusTrap };
+export type { UseFocusTrapOptions };

package/dist/types/hooks/useHotkey/useHotkey.d.ts

@@ -0,0 +1,23 @@
+import { UseHotkeyOptions } from './useHotkey.types.js';
+
+/**
+ * Bind a single keyboard combo to a callback.
+ *
+ * Combos use the same `+`-separated string format as `MenuBar`'s `shortcut`
+ * prop: `"Ctrl+S"`, `"Cmd+Shift+P"`, `"Escape"`. Modifiers: `Ctrl`, `Cmd`
+ * (= Meta), `Alt` / `Option`, `Shift`. `Cmd` automatically maps to `Ctrl` on
+ * non-Mac platforms via `getPlatform()`.
+ *
+ * The handler reference is stable — passing a fresh inline function on every
+ * render is safe and does not re-subscribe the underlying listener.
+ *
+ * @example
+ * ```tsx
+ * useHotkey('Ctrl+S', e => save(), { preventDefault: true });
+ * useHotkey('Escape', () => setOpen(false));
+ * useHotkey('Cmd+K', () => openCommandPalette()); // Cmd on Mac, Ctrl elsewhere
+ * ```
+ */
+declare function useHotkey(combo: string, handler: (event: KeyboardEvent) => void, options?: UseHotkeyOptions): void;
+
+export { useHotkey };

package/dist/types/hooks/useHotkey/useHotkey.types.d.ts

@@ -0,0 +1,36 @@
+import { RefObject } from 'react';
+
+type HotkeyTarget = EventTarget | RefObject<EventTarget | null> | null;
+interface UseHotkeyOptions {
+    /**
+     * When false, the binding is not active.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to fire when focus is inside an editable element
+     * (`<input>`, `<textarea>`, `[contenteditable]`).
+     * @default false
+     */
+    enableInInputs?: boolean;
+    /**
+     * Call `event.preventDefault()` before invoking the handler.
+     * @default true
+     */
+    preventDefault?: boolean;
+    /**
+     * Call `event.stopPropagation()` after the handler runs.
+     * @default false
+     */
+    stopPropagation?: boolean;
+    /**
+     * Override the target element. Accepts either an `EventTarget` directly
+     * (e.g. `document`, an `HTMLElement`) or a `RefObject` whose `.current`
+     * resolves to one. The latter form re-attaches the listener once the ref
+     * mounts, so passing `ref` directly works without waiting a render. Defaults
+     * to `window`.
+     */
+    target?: HotkeyTarget;
+}
+
+export type { HotkeyTarget, UseHotkeyOptions };

package/dist/types/hooks/useKeyboard/types.d.ts

@@ -0,0 +1,14 @@
+import { LiteralUnion } from '../../types/utilities.js';
+
+type ModifierKeys = 'control' | 'shift' | 'alt' | 'meta';
+type KeyCode = string;
+type KeyboardModifierKeysState = {
+    [key in ModifierKeys]: boolean;
+};
+type KeyboardState = {
+    pressedKeys: KeyCode[];
+    modifiers: KeyboardModifierKeysState;
+};
+type AllKeys = LiteralUnion<ModifierKeys, string>;
+
+export type { AllKeys, KeyCode, KeyboardModifierKeysState, KeyboardState, ModifierKeys };

package/dist/types/hooks/useKeyboard/useKeyboard.d.ts

@@ -0,0 +1,36 @@
+import { KeyboardState } from './types.js';
+export { AllKeys, ModifierKeys } from './types.js';
+
+/**
+ * Hook for tracking keyboard state including modifier keys and pressed keys.
+ *
+ * Useful for components that need to respond to keyboard modifiers like
+ * Ctrl+drag for snapping, Shift+drag for precision, etc.
+ * @returns Current keyboard state
+ *
+ * @example
+ * ```tsx
+ * // Track all keys and modifiers
+ * const keyboard = useKeyboard();
+ *
+ * const handleMouseMove = (e: MouseEvent) => {
+ *   if (keyboard.ctrl) {
+ *     // Snap to grid
+ *   } else if (keyboard.shift) {
+ *     // Precision mode
+ *   }
+ * };
+ *
+ * // Track only specific keys
+ * const keyboard = useKeyboard({
+ *   trackAllKeys: false,
+ *   trackedKeys: ['Space', 'Enter', 'Escape']
+ * });
+ *
+ * // Check if specific key is pressed
+ * const isSpacePressed = keyboard.pressedKeys.includes('Space');
+ * ```
+ */
+declare const useKeyboard: () => KeyboardState;
+
+export { KeyboardState, useKeyboard };

package/dist/types/hooks/useKeyboard/utils.d.ts

@@ -0,0 +1,6 @@
+import { KeyboardState, AllKeys, ModifierKeys } from './types.js';
+
+declare const isModifierKey: (key: string) => key is ModifierKeys;
+declare const isKeyPressed: (keyboardState: KeyboardState, key: AllKeys) => boolean;
+
+export { isKeyPressed, isModifierKey };

package/dist/types/hooks/useMergedRef/useMergedRef.d.ts

@@ -0,0 +1,22 @@
+import { Ref, RefCallback } from 'react';
+
+/**
+ * Merge multiple refs into a single callback ref. Each provided ref (object
+ * ref, callback ref, or `null`/`undefined`) receives the node when the merged
+ * ref fires.
+ *
+ * Useful when a component needs to keep an internal ref to a DOM node while
+ * also forwarding the same node through an externally supplied `ref` prop
+ * (ref-as-prop in React 19).
+ *
+ * @example
+ * ```tsx
+ * const internalRef = useRef<HTMLDivElement>(null);
+ * const mergedRef = useMergedRef(internalRef, props.ref);
+ *
+ * return <div ref={mergedRef} />;
+ * ```
+ */
+declare function useMergedRef<T>(...refs: Array<Ref<T> | undefined | null>): RefCallback<T>;
+
+export { useMergedRef };

package/dist/types/hooks/useResizeObserver/useResizeObserver.d.ts

@@ -0,0 +1,35 @@
+import { RefObject } from 'react';
+
+interface UseResizeObserverOptions {
+    /**
+     * When false, the observer is not attached. Toggling this from `false` to
+     * `true` (re-)attaches the observer; toggling back disconnects it.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Observe size changes on an element. SSR-safe; cleans up on unmount.
+ *
+ * The callback is wrapped in a ref so consumers do not have to memoize it —
+ * the underlying observer never re-subscribes when the callback identity
+ * changes.
+ *
+ * The hook re-checks `ref.current` on every render so it picks up nodes that
+ * mount later (e.g. through conditional rendering). When the observed node
+ * has not changed the only cost is a single identity comparison.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null);
+ * useResizeObserver(ref, entry => {
+ *   console.log(entry.contentRect.width);
+ * });
+ *
+ * return <div ref={ref} />;
+ * ```
+ */
+declare function useResizeObserver<T extends HTMLElement>(ref: RefObject<T | null>, callback: (entry: ResizeObserverEntry) => void, options?: UseResizeObserverOptions): void;
+
+export { useResizeObserver };
+export type { UseResizeObserverOptions };

package/dist/types/hooks/useTheme/useTheme.d.ts

@@ -0,0 +1,48 @@
+import { UseThemeReturn } from './useTheme.types.js';
+
+/**
+ * Read the current theme at runtime.
+ *
+ * Returns the resolved CSS variable snapshot from `:root`, the detected
+ * theme variant, and helpers for reading individual tokens by path.
+ * Components should prefer compile-time tokens via Vanilla Extract
+ * (`vars.*` from `@/theme`) — reach for `useTheme` only when a runtime
+ * read is genuinely required (canvas drawing, third-party libraries that
+ * take colors as plain strings).
+ *
+ * **Scope:** the hook always reads from `:root` — both the variant and
+ * the resolved values come from `document.documentElement`. A light- or
+ * custom-themed subtree wrapped in `VanillaThemeProvider` will **not** be
+ * reflected here; for that, components inside the subtree should style
+ * via Vanilla Extract `vars.*` (which the browser resolves correctly per
+ * scope) rather than runtime reads.
+ *
+ * **SSR:** returns the dark-theme defaults as a fallback. The hook
+ * re-evaluates against the live DOM on mount via `useLayoutEffect`, so
+ * the second render contains the real values before the browser paints.
+ *
+ * **Reactivity:** v0.8 reads once on mount. Toggling the root theme at
+ * runtime is not reflected — remount the consuming subtree to pick up
+ * the new theme. A `MutationObserver`-based subscription may be added
+ * in a later release if consumer demand emerges.
+ *
+ * @example
+ * ```tsx
+ * const { values, variant, getVar, getToken } = useTheme();
+ *
+ * // Canvas drawing with theme-aware colors
+ * ctx.strokeStyle = values.colors.accent.primary;
+ *
+ * // Conditional logic
+ * if (variant === 'dark') loadDarkAssets();
+ *
+ * // Inline styles that follow theme changes automatically
+ * <div style={{ color: getVar('colors.text.primary') }} />
+ *
+ * // One-off token resolution
+ * const accent = getToken('colors.accent.primary');
+ * ```
+ */
+declare function useTheme(): UseThemeReturn;
+
+export { useTheme };

package/dist/types/hooks/useTheme/useTheme.types.d.ts

@@ -0,0 +1,60 @@
+import { ThemeValues } from '../../theme/createCustomTheme.js';
+
+/**
+ * Same shape as `ThemeValues` but with each leaf widened to `string`.
+ *
+ * `darkThemeValues` is declared `as const`, which makes its leaf types
+ * literal (e.g. `'#007acc'`). At runtime the hook reads arbitrary CSS
+ * custom-property strings from the DOM — those values are not constrained
+ * to the dark-theme literals, so the return type widens to plain strings
+ * to stay sound for light, custom, or computed values.
+ */
+type ResolvedThemeValues = WidenLeaves<ThemeValues>;
+type WidenLeaves<T> = T extends string ? string : T extends number ? number : {
+    -readonly [K in keyof T]: WidenLeaves<T[K]>;
+};
+/**
+ * Detected theme variant.
+ *
+ * Detection is **root-only**: the hook reports `'light'` only when the
+ * `lightThemeClass` produced by `createLightTheme()` is applied to
+ * `document.documentElement` — the same element the hook reads CSS
+ * variable values from. A light-themed subtree wrapped in
+ * `VanillaThemeProvider` does **not** flip this variant, because the
+ * resolved values would still come from the root.
+ *
+ * - `'dark'` — the default; no `lightThemeClass` on `:root`.
+ * - `'light'` — `lightThemeClass` is on `:root`.
+ * - `'custom'` — reserved. v0.8 does not auto-detect themes produced by
+ *   `createCustomTheme(selector, overrides)`; the union member exists so
+ *   future releases can add detection without a breaking type change.
+ */
+type ThemeVariant = 'dark' | 'light' | 'custom';
+interface UseThemeReturn {
+    /** Current root-theme variant. See `ThemeVariant` for detection rules. */
+    variant: ThemeVariant;
+    /** Resolved theme values — CSS variable values read from `:root`. */
+    values: ResolvedThemeValues;
+    /**
+     * Resolve a single token to its current CSS-var value, e.g. `'#007acc'`.
+     *
+     * Falls back to the dark-theme default when the underlying CSS variable
+     * is unset or when no DOM is available (SSR). Returns an empty string
+     * only for paths that don't resolve to a leaf in the theme contract.
+     * Repeated calls for the same path are cached for the life of the hook
+     * instance.
+     */
+    getToken: (path: string) => string;
+    /**
+     * Get the `var(--etui-...)` reference for a token, e.g.
+     * `'var(--etui-color-accent-primary)'`. Useful for inline styles that
+     * must follow theme changes automatically.
+     *
+     * SSR-safe — the returned string is constructed from the contract and
+     * works identically in browser and server rendering. Returns an empty
+     * string only for paths that don't resolve to a leaf in the contract.
+     */
+    getVar: (path: string) => string;
+}
+
+export type { ResolvedThemeValues, ThemeVariant, UseThemeReturn };