h2o-library 1.7.1 → 2.0.0

package/dist/hooks/components/src/table/table-utils.d.ts

@@ -0,0 +1,2 @@
+export declare const isInteractiveElement: (element: HTMLElement | null) => boolean;
+export declare const hasInteractiveParent: (element: HTMLElement | null, stopAt: HTMLElement | null) => boolean;

package/dist/hooks/components/src/table/table.d.ts

@@ -0,0 +1,78 @@
+import "./table.css";
+import React from "react";
+/**
+ * Sort state for a column: ascending, descending, or unsorted.
+ * @type {("asc"|"desc"|null)}
+ */
+export type SortDirection = "asc" | "desc" | null;
+/**
+ * One column: accessor `key` maps to `row[key]`, with optional `render` for custom cells.
+ * @template T - Row type.
+ * @property {string} key - Object key on each row, or a synthetic key for custom columns.
+ * @property {boolean} [sortable] - When `true` and `onSort` is provided, header is clickable.
+ * @property {function(unknown, T): React.ReactNode} [render] - If omitted, `String(row[key])` is used.
+ */
+export interface TableColumn<T> {
+    key: string;
+    label: string;
+    sortable?: boolean;
+    minWidth?: string;
+    maxWidth?: string;
+    width?: string;
+    render?: (value: unknown, row: T) => React.ReactNode;
+}
+/**
+ * @template T - Row object type; keys should match `TableColumn.key` where possible.
+ * Full data grid: sort, optional row selection, column edit popover (drag/drop + visibility), pagination, loading.
+ *
+ * @property {TableColumn<T>[]} columns - Column defs; can include a synthetic `__selection` for checkboxes.
+ * @property {T[]} data - Rows to render; order is preserved.
+ * @property {string} [sortKey] - **Controlled** sort column; use with `sortDirection` and `onSort`.
+ * @property {SortDirection} [sortDirection] - Current direction for `sortKey`.
+ * @property {boolean} [columnsEditable] - Enables “Edit columns” popover. Default `false`.
+ * @property {string[]} [visibleColumns] - **Controlled** list of column keys to show. Pair with `onVisibleColumnsChange`.
+ * @property {T[]} [selectedRows] - **Controlled** selected rows. Pair with `onSelectionChange` and `rowKey`.
+ * @property {keyof T} [rowKey] - Unique key field on `T` for selection identity. Often `"id"`.
+ * @property {number} [currentPage] - 1-based page index when `Pagination` is used.
+ * @property {string} [maxHeight] - Max height of the scrollable table body.
+ */
+interface TableProps<T extends Record<string, unknown>> {
+    columns: TableColumn<T>[];
+    data: T[];
+    isLoading?: boolean;
+    className?: string;
+    containerClassName?: string;
+    rowHeight?: string;
+    sortKey?: string;
+    sortDirection?: SortDirection;
+    columnsEditable?: boolean;
+    currentPage?: number;
+    totalPages?: number;
+    perPage?: number;
+    perPageOptions?: {
+        label: string;
+        value: number;
+    }[];
+    onSort?: (key: string, direction: SortDirection) => void;
+    onPageChange?: (page: number) => void;
+    onPerPageChange?: (perPage: number) => void;
+    onVisibleColumnsChange?: (keys: string[]) => void;
+    maxHeight?: string;
+    visibleColumns?: string[];
+    maxVisibleColumns?: number;
+    defaultVisibleColumns?: string[];
+    trailingColumns?: string[];
+    selectedRows?: T[];
+    onSelectionChange?: (rows: T[]) => void;
+    rowKey?: keyof T;
+    onRowClick?: (row: T, rowIndex: number) => void;
+}
+/**
+ * Renders a full-featured table: headers, body, optional selection column, sort indicators, edit-columns popover, and pagination.
+ *
+ * @template T - Row record type.
+ * @param {object} props - Column definitions, data, and optional controlled sorting / pagination / selection.
+ * @returns {JSX.Element} The table shell, scroll region, and optional `Pagination` / `Loader`.
+ */
+export declare function Table<T extends Record<string, unknown>>({ columns, data, isLoading, className, rowHeight, sortKey, sortDirection, onSort, currentPage, totalPages, perPage, perPageOptions, onPageChange, onPerPageChange, maxHeight, columnsEditable, containerClassName, visibleColumns, onVisibleColumnsChange, maxVisibleColumns, defaultVisibleColumns, trailingColumns, selectedRows, onSelectionChange, rowKey, onRowClick, }: TableProps<T>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/hooks/components/src/tabs/tabs.d.ts

@@ -0,0 +1,35 @@
+import "./tabs.css";
+/**
+ * One entry in a `Tabs` `tabs` list.
+ * @property {string} value - Emitted to `onChange` when the tab is activated.
+ */
+export type TabItem = {
+    label: string;
+    value: string;
+    disabled?: boolean;
+};
+/**
+ * **Controlled** tab strip: `selectedTab` must match a `TabItem.value` for the active state.
+ *
+ * @property {TabItem[]} tabs - Tab metadata; `disabled` items are skipped in keyboard nav.
+ * @property {string} selectedTab - Current `value` of the active tab.
+ * @property {(value: string) => void} onChange - Fires with the new tab `value` on click or keyboard.
+ * @property {"sm"|"md"|"lg"} [size] - Size token for the tab list. Default `"md"`.
+ */
+interface TabsProps {
+    tabs: TabItem[];
+    selectedTab: string;
+    onChange: (tab: string) => void;
+    ariaLabel?: string;
+    size?: "sm" | "md" | "lg";
+    tabClassName?: string;
+    className?: string;
+}
+/**
+ * Renders a `tablist` with one `button` per tab, roving tabindex, and arrow-key / Home / End support.
+ *
+ * @param {TabsProps} props - `tabs` / `selectedTab` / `onChange` plus `ariaLabel` for the list.
+ * @returns {JSX.Element} The horizontal tab list.
+ */
+export declare const Tabs: ({ tabs, selectedTab, onChange, ariaLabel, size, tabClassName, className, }: TabsProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/hooks/components/src/tag/tag.d.ts

@@ -0,0 +1,26 @@
+import "./tag.css";
+import React from "react";
+/**
+ * Removable label chip with primary/secondary styles and sizes.
+ *
+ * @property {string} label - Visible text and remove `aria-label` source.
+ * @property {"primary"|"secondary"} [variant] - Color scheme. Default `"primary"`.
+ * @property {"sm"|"md"|"lg"} [size] - Typographic and hit-target scale. Default `"md"`.
+ * @property {() => void} onRemove - Fires when the user clicks the “×” control.
+ */
+type TagProps = {
+    label: string;
+    variant?: "primary" | "secondary";
+    size?: "sm" | "md" | "lg";
+    onRemove: () => void;
+    className?: string;
+};
+/**
+ * A dismissible tag used in multi-selects and filter lists; forwards ref to the root `div`.
+ *
+ * @param {TagProps} props - `label`, `onRemove`, and presentation props.
+ * @param {React.Ref<HTMLDivElement>} ref - Root element ref.
+ * @returns {React.ReactElement} The tag row and remove button.
+ */
+export declare const Tag: React.ForwardRefExoticComponent<TagProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/hooks/components/src/textarea/textarea.d.ts

@@ -0,0 +1,33 @@
+import "./textarea.css";
+import React from "react";
+import type { TooltipPosition } from "../../../types";
+/**
+ * Props for `Textarea`: extends `HTMLTextAreaElement` attributes (omits legacy HTML `size`).
+ *
+ * @property {string} [label] - Optional field label with optional info tooltip.
+ * @property {boolean} [showClear] - Renders clear when non-empty. Default `false`.
+ * @property {string} [note] - Helper line under the field.
+ * @property {string} [error] - Error line; invalid styling when set.
+ * @property {number} [maxLength] - When set, shows a live character counter vs this cap (e.g., 12/200).
+ * @property {"none"|"vertical"} [resize] - CSS resize mode. Default `"none"`.
+ */
+interface TextareaProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size"> {
+    label?: string;
+    showClear?: boolean;
+    note?: string;
+    error?: string;
+    containerClassName?: string;
+    tooltip?: string;
+    tooltipPosition?: TooltipPosition;
+    maxLength?: number;
+    resize?: "none" | "vertical";
+}
+/**
+ * Multi-line input with label, clear, optional counter from `maxLength`, and note/error rows.
+ *
+ * @param {TextareaProps} props - Native `textarea` props plus H2O chrome.
+ * @param {React.Ref<HTMLTextAreaElement>} ref - Forwarded to `<textarea>`.
+ * @returns {React.ReactElement} Labeled field wrapper and counter when applicable.
+ */
+export declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+export {};

package/dist/hooks/components/src/time-picker/time-picker.d.ts

@@ -0,0 +1,31 @@
+import "./time-picker.css";
+/**
+ * Time selection UI: one clock or a start/end **range**; hour/minute columns with optional 12h format.
+ *
+ * @property {"single"|"range"} [mode] - `single` uses `value` as `string | null`; `range` as `[string|null, string|null]`. Default `"single"`.
+ * @property {string|null|[string|null,string|null]} [value] - `"HH:MM"`, partial `"HH:"` while picking hour, or `null` for empty. Range: tuple of same.
+ * @property {(v: string|null|[string|null,string|null]) => void} [onChange] - Emits the same shapes as `value` as the user picks.
+ * @property {12|24} [hourFormat] - 12- or 24-hour labels. Default `24`.
+ * @property {number} [minuteStep] - Minutes grid step, e.g. `5` → `00,05,…,55`. Default `5`.
+ */
+interface TimePickerProps {
+    mode?: "single" | "range";
+    value?: string | null | [string | null, string | null];
+    onChange?: (value: string | null | [string | null, string | null]) => void;
+    hourFormat?: 12 | 24;
+    minuteStep?: number;
+    startLabel?: string;
+    endLabel?: string;
+    disabled?: boolean;
+    className?: string;
+    error?: string;
+    note?: string;
+}
+/**
+ * Picker for a time or time range, with hour/minute dropdowns and optional labels or validation chrome.
+ *
+ * @param {TimePickerProps} props - Mode, `value`/`onChange` shape, and `hourFormat` / `minuteStep`.
+ * @returns {JSX.Element} The field group(s) and time lists when open.
+ */
+export declare const TimePicker: ({ mode, value, onChange, hourFormat, minuteStep, startLabel, endLabel, disabled, className, error, note, }: TimePickerProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/hooks/components/src/toast/toast.d.ts

@@ -0,0 +1,54 @@
+import "./toast.css";
+import type React from "react";
+/**
+ * Color/semantic key for a toast: maps to icon and ARIA `role` (`error`/`warning` → `alert`, others often `status`).
+ * @type {("info"|"error"|"warning"|"success")}
+ */
+export type ToastVariant = "info" | "error" | "warning" | "success";
+/**
+ * Viewport region where `ToastProvider` positions the toast container (CSS BEM variant).
+ * @type {("top-right"|"top-left"|"bottom-right"|"bottom-left"|"top-center"|"bottom-center")}
+ */
+export type ToastPosition = "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";
+interface ToastAction {
+    label: string;
+    action: () => void;
+}
+/**
+ * Options passed to `useToast().show(options)`; describes one transient notification.
+ *
+ * @property {ToastVariant} variant - Visual/semantic style.
+ * @property {string} title - Bold heading in the toast header.
+ * @property {string} [description] - Optional body copy under the title.
+ * @property {ToastAction} [primaryAction] - Primary CTA; presence disables auto-dismiss by default.
+ * @property {ToastAction} [secondaryAction] - Secondary CTA; same as primary for auto-dismiss rules.
+ * @property {number} [duration] - Auto-close delay in ms. Default `5000`; `0` disables (`primaryAction` / `secondaryAction` also keep it open without timer).
+ */
+export interface ToastOptions {
+    variant: ToastVariant;
+    title: string;
+    description?: string;
+    primaryAction?: ToastAction;
+    secondaryAction?: ToastAction;
+    duration?: number;
+}
+/**
+ * Props for `ToastProvider` — mount once near the app root to enable `useToast()`.
+ *
+ * @property {React.ReactNode} children - Your app; context is available to descendants.
+ * @property {ToastPosition} [position] - Viewport region for the stack. Default `"bottom-right"`.
+ * @property {number} [maxToasts] - Max simultaneous toasts; older may be evicted. Default `5`.
+ */
+interface ToastProviderProps {
+    children: React.ReactNode;
+    position?: ToastPosition;
+    maxToasts?: number;
+}
+/**
+ * Context provider: renders `children` and a fixed-position stack of toasts; wires timers and `maxToasts` cap.
+ *
+ * @param {object} props - `position`, `maxToasts`, and `children`.
+ * @returns {JSX.Element} Provider element plus the global toast region.
+ */
+export declare const ToastProvider: React.FC<ToastProviderProps>;
+export {};

package/dist/hooks/components/src/toggle/toggle.d.ts

@@ -0,0 +1,35 @@
+import "./toggle.css";
+import React from "react";
+import type { TooltipPosition } from "../../../types";
+type BaseToggleProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size"> & {
+    label?: string;
+    description?: string;
+    containerClassName?: string;
+    size?: "sm" | "md" | "lg";
+    error?: string;
+    note?: string;
+    tooltip?: string;
+    tooltipPosition?: TooltipPosition;
+};
+type CardToggleProps = BaseToggleProps & {
+    isCard: true;
+    isDraggable?: boolean;
+};
+type InlineToggleProps = BaseToggleProps & {
+    isCard?: false;
+    isDraggable?: never;
+};
+/**
+ * Discriminated union: `isCard: true` enables card layout and optional `isDraggable`; otherwise inline switch.
+ * `size` is visual (`"sm"|"md"|"lg"`), not the HTML `size` attribute.
+ */
+type ToggleProps = CardToggleProps | InlineToggleProps;
+/**
+ * Switch UI backed by a checkbox input; supports inline, card, draggable card, and label tooltip.
+ *
+ * @param {ToggleProps} props - Union of card vs inline props; `ref` targets the `input`.
+ * @param {React.Ref<HTMLInputElement>} ref - Native checkbox ref.
+ * @returns {React.ReactElement} The toggle wrapper and `input` + visual thumb track.
+ */
+export declare const Toggle: React.ForwardRefExoticComponent<ToggleProps & React.RefAttributes<HTMLInputElement>>;
+export {};

package/dist/hooks/components/src/tooltip/tooltip.d.ts

@@ -0,0 +1,38 @@
+import "./tooltip.css";
+import type React from "react";
+import type { TooltipPosition } from "../../../types";
+type BaseProps = {
+    position?: TooltipPosition;
+    className?: string;
+    contentClassName?: string;
+    children: React.ReactNode;
+    variant?: "dark" | "light";
+    delay?: number;
+    maxWidth?: string | number;
+};
+type TextTooltip = BaseProps & {
+    text: string;
+    content?: never;
+};
+type ContentTooltip = BaseProps & {
+    content: React.ReactNode;
+    text?: never;
+};
+/**
+ * Props for `Tooltip`: **either** `text` (plain string) **or** `content` (rich `ReactNode`), not both.
+ *
+ * @property {import("../../../types").TooltipPosition} [position] - Placement vs the trigger. Default `"top"`.
+ * @property {React.ReactNode} children - Trigger element(s) wrapped for hover/focus.
+ * @property {"dark"|"light"} [variant] - Surface style. Default `"dark"`.
+ * @property {number} [delay] - Show delay in ms. Default `0`.
+ * @property {string|number} [maxWidth] - Tooltip body max width (CSS value).
+ */
+type TooltipProps = TextTooltip | ContentTooltip;
+/**
+ * Hover/focus tooltip: positions in a `createPortal` layer, hides on scroll (capture), and supports string or custom body.
+ *
+ * @param {TooltipProps} props - `text` XOR `content`, plus `children` as trigger.
+ * @returns {JSX.Element | null} Wrapper around `children` and the portaled bubble when visible.
+ */
+export declare const Tooltip: React.FC<TooltipProps>;
+export {};

package/dist/hooks/entries/charts.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Subpath entry: `h2o-library/charts`
+ */
+export * from "../charts/index";

package/dist/hooks/entries/hooks.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Subpath entry: `h2o-library/hooks`
+ */
+export * from "../hooks";

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

@@ -0,0 +1,9 @@
+/**
+ * Subpath entry: `h2o-library/types`
+ * Type-only re-exports (no runtime values). Requires TypeScript 5+.
+ */
+export type * from "../types";
+export type * from "../hooks";
+export type * from "../components";
+export type * from "../charts";
+export type * from "../utils";

package/dist/hooks/entries/utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Subpath entry: `h2o-library/utils`
+ * Runtime utilities (e.g. `cn`). No React component surface.
+ */
+export * from "../utils";

package/dist/hooks/hooks/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./src/use-click-outside";
+export * from "./src/use-copy-to-clipboard";
+export * from "./src/use-debounce";
+export * from "./src/use-event-listener";
+export { useEventListener as useEventListner } from "./src/use-event-listener";
+export * from "./src/use-dropdown-position";
+export * from "./src/use-focus-trap";
+export * from "./src/use-idle";
+export * from "./src/use-interval";
+export * from "./src/use-hover";
+export * from "./src/use-key-press";
+export * from "./src/use-long-press";
+export * from "./src/use-media-query";
+export * from "./src/use-mouse";
+export * from "./src/use-timeout";
+export { useToast, ToastContext, type ToastContextType } from "./src/use-toast";
+export * from "./src/use-window-scroll";
+export * from "./src/use-window-size";

package/dist/hooks/hooks/src/use-click-outside.d.ts

@@ -0,0 +1,13 @@
+import type { RefObject } from "react";
+type Handler = (event: MouseEvent | TouchEvent) => void;
+/**
+ * Run a handler when the user clicks/taps outside a referenced element.
+ *
+ * Commonly used to close popovers, dropdowns, menus, and dialogs.
+ *
+ * @param ref - Element ref that defines the “inside” area.
+ * @param handler - Called when an outside interaction happens.
+ * @param mouseEvent - Which mouse event to listen for (defaults to `"mousedown"`).
+ */
+export declare function useClickOutside<T extends HTMLElement = HTMLElement>(ref: RefObject<T>, handler: Handler, mouseEvent?: "mousedown" | "mouseup"): void;
+export {};

package/dist/hooks/hooks/src/use-copy-to-clipboard.d.ts

@@ -0,0 +1,15 @@
+export type UseCopyToClipboardState = {
+    copied: boolean;
+    error: Error | null;
+};
+/**
+ * Copy text to the system clipboard and track success for UI feedback.
+ *
+ * @param resetDelay - If set, `copied` resets to `false` after this many ms. @defaultValue 2000
+ * @returns `copy` function and `copied` / `error` state.
+ */
+export declare function useCopyToClipboard(resetDelay?: number): {
+    readonly copy: (text: string) => Promise<boolean>;
+    readonly copied: boolean;
+    readonly error: Error | null;
+};

package/dist/hooks/hooks/src/use-debounce.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns a value that only updates `delay` ms after `value` stops changing
+ * (leading/trailing: trailing only).
+ *
+ * @param value - Source value (often a string from an input).
+ * @param delay - Debounce window in ms.
+ * @returns The last stable value after the quiet period.
+ */
+export declare function useDebounce<T>(value: T, delay: number): T;

package/dist/hooks/hooks/src/use-dropdown-position.d.ts

@@ -0,0 +1,10 @@
+import type { RefObject } from "react";
+/**
+ * Decide whether a dropdown/menu should open above or below its trigger.
+ *
+ * @param containerRef - Ref to the trigger/container element.
+ * @param isOpen - Only measures while open.
+ * @param direction - Force `"top"`/`"bottom"` or let it auto-detect.
+ * @param menuHeight - Expected menu height (px) used for the calculation.
+ */
+export declare function useDropdownPosition(containerRef: RefObject<HTMLElement>, isOpen: boolean, direction?: "top" | "bottom" | "auto", menuHeight?: number): "top" | "bottom";

package/dist/hooks/hooks/src/use-event-listener.d.ts

@@ -0,0 +1,15 @@
+import type { RefObject } from "react";
+type AddOptions = boolean | AddEventListenerOptions;
+/**
+ * Subscribes to a DOM `EventTarget` and keeps the latest `handler` without
+ * re-attaching on every render.
+ *
+ * @param event - Event name (e.g. `\"resize\"`, `\"click\"`).
+ * @param handler - Listener invoked when the event fires.
+ * @param target - `window` when `undefined`, nothing when `null`, the ref’s
+ *   `current` when a ref, or a raw element.
+ * @param options - Same as `addEventListener`’s third argument.
+ */
+export declare function useEventListener<K extends keyof WindowEventMap>(event: K, handler: (ev: WindowEventMap[K]) => void, target?: RefObject<EventTarget | null> | EventTarget | null, options?: AddOptions): void;
+export declare function useEventListener(event: string, handler: (ev: Event) => void, target?: RefObject<EventTarget | null> | EventTarget | null, options?: AddOptions): void;
+export {};

package/dist/hooks/hooks/src/use-focus-trap.d.ts

@@ -0,0 +1,8 @@
+import type { RefObject } from "react";
+/**
+ * Trap keyboard focus inside a container while `active` is true.
+ *
+ * @param ref - Container element that should contain focus.
+ * @param active - Enables/disables the trap.
+ */
+export declare function useFocusTrap(ref: RefObject<HTMLElement | null>, active: boolean): void;

package/dist/hooks/hooks/src/use-hover.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tracks whether the pointer is over a given element.
+ *
+ * @returns A tuple: `isHovered` and a **ref callback** to pass to a host element’s
+ *   `ref` prop (stores the node and wires `mouseenter` / `mouseleave`).
+ */
+export declare function useHover<T extends HTMLElement = HTMLElement>(): [
+    boolean,
+    (node: T | null) => void
+];

package/dist/hooks/hooks/src/use-idle.d.ts

@@ -0,0 +1,15 @@
+export type UseIdleOptions = {
+    /**
+     * DOM events on `window` that reset the idle timer. @defaultValue common
+     * user interaction events.
+     */
+    events?: Array<keyof WindowEventMap>;
+};
+/**
+ * Returns `true` when the user has been inactive (no registered events) for at least `ms`.
+ *
+ * @param ms - Idle duration in milliseconds.
+ * @param options - Optional list of `window` events that count as activity.
+ * @returns Whether the user is currently considered idle.
+ */
+export declare function useIdle(ms: number, options?: UseIdleOptions): boolean;

package/dist/hooks/hooks/src/use-interval.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Repeats `callback` every `delay` ms. Pauses when `delay` is `null`.
+ *
+ * @param callback - Function called on each tick.
+ * @param delay - Interval in ms, or `null` to clear the interval.
+ */
+export declare function useInterval(callback: () => void, delay: number | null): void;

package/dist/hooks/hooks/src/use-key-press.d.ts

@@ -0,0 +1,13 @@
+type KeyTarget = string | readonly string[];
+/**
+ * Listens for `keydown` on `window` and either reports whether a key is held
+ * or runs a callback on each matching press.
+ *
+ * @param key - `KeyboardEvent.key` value, or a list of keys.
+ * @param handler - If provided, called for each matching `keydown`; no return value.
+ * @returns If `handler` is omitted: whether the key is currently held (`keydown`
+ *   without a matching `keyup` yet). If `handler` is provided: `undefined`.
+ */
+export declare function useKeyPress(key: KeyTarget, handler: (event: KeyboardEvent) => void): void;
+export declare function useKeyPress(key: KeyTarget, handler?: undefined): boolean;
+export {};

package/dist/hooks/hooks/src/use-long-press.d.ts

@@ -0,0 +1,20 @@
+import type { MouseEvent, PointerEvent } from "react";
+export type UseLongPressOptions = {
+    delay?: number;
+    moveThreshold?: number;
+    onClick?: (event: MouseEvent<HTMLElement> | PointerEvent<HTMLElement>) => void;
+};
+/**
+ * Pointer handlers to attach to an element to detect a long-press (hold) vs a short click.
+ *
+ * @param onLongPress - Invoked if the pointer stays down for `delay` without excess movement.
+ * @param options - Timing, move tolerance, and optional short-click handler.
+ * @returns Props to spread on a host element (`onPointerDown`, `onPointerMove`, `onPointerUp`, etc.).
+ */
+export declare function useLongPress(onLongPress: (event: React.PointerEvent<HTMLElement>) => void, options?: UseLongPressOptions): {
+    readonly onPointerDown: (event: React.PointerEvent<HTMLElement>) => void;
+    readonly onPointerMove: (event: React.PointerEvent<HTMLElement>) => void;
+    readonly onPointerUp: (event: React.PointerEvent<HTMLElement>) => void;
+    readonly onPointerCancel: (event: React.PointerEvent<HTMLElement>) => void;
+    readonly onPointerLeave: (event: React.PointerEvent<HTMLElement>) => void;
+};

package/dist/hooks/hooks/src/use-media-query.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Subscribe to a media query and get whether it currently matches.
+ *
+ * @param query - Any valid CSS media query, e.g. `\"(min-width: 768px)\"`.
+ * @returns `true` when the query matches.
+ */
+export declare const useMediaQuery: (query: string) => boolean;

package/dist/hooks/hooks/src/use-mouse.d.ts

@@ -0,0 +1,12 @@
+export type MouseState = {
+    x: number;
+    y: number;
+    hasMoved: boolean;
+};
+/**
+ * Tracks the latest pointer position from `window` `pointermove` / `mousemove` events.
+ *
+ * @param enabled - When `false`, stops listening. @defaultValue true
+ * @returns Last coordinates and whether a move has been observed.
+ */
+export declare function useMouse(enabled?: boolean): MouseState;

package/dist/hooks/hooks/src/use-timeout.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runs `callback` once after `delay` ms. The timer resets when `delay` or
+ * `callback` identity changes; set `delay` to `null` to cancel.
+ *
+ * @param callback - Function to invoke after the delay.
+ * @param delay - Milliseconds, or `null` to skip scheduling.
+ */
+export declare function useTimeout(callback: () => void, delay: number | null): void;

package/dist/hooks/hooks/src/use-toast.d.ts

@@ -0,0 +1,15 @@
+import type { ToastOptions } from "../../components/src/toast/toast";
+/**
+ * Return type of `useToast()`: imperative API to show and remove toasts.
+ */
+export interface ToastContextType {
+    /** Show a toast. Returns the toast id. */
+    show: (options: ToastOptions) => string;
+    /** Programmatically dismiss a toast by id. */
+    dismiss: (id: string) => void;
+}
+export declare const ToastContext: import("react").Context<ToastContextType | undefined>;
+/**
+ * Subscribes to the toast context; throws if `ToastProvider` is not an ancestor.
+ */
+export declare const useToast: () => ToastContextType;

package/dist/hooks/hooks/src/use-window-scroll.d.ts

@@ -0,0 +1,10 @@
+export type WindowScrollState = {
+    x: number;
+    y: number;
+};
+/**
+ * Subscribes to `window` scroll and returns the current `scrollX` / `scrollY`.
+ *
+ * @returns Latest scroll offsets; `{ x: 0, y: 0 }` during SSR.
+ */
+export declare function useWindowScroll(): WindowScrollState;

package/dist/hooks/hooks/src/use-window-size.d.ts

@@ -0,0 +1,10 @@
+export type WindowSize = {
+    width: number;
+    height: number;
+};
+/**
+ * Subscribes to `window` `resize` and returns `innerWidth` / `innerHeight`.
+ *
+ * @returns Viewport size; `{ width: 0, height: 0 }` before mount / during SSR.
+ */
+export declare function useWindowSize(): WindowSize;

package/dist/hooks/index.cjs.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("react");function t(t,n,r,o){const u=e.useRef(n);e.useEffect((()=>{u.current=n}),[n]),e.useEffect((()=>{const e=function(e){return void 0===e?"undefined"!=typeof window?window:null:null===e?null:null!=(t=e)&&"object"==typeof t&&"current"in t?e.current:e;var t}(r);if(null==e)return;const n=e=>u.current(e);return e.addEventListener(t,n,o),()=>{e.removeEventListener(t,n,o)}}),[t,r,o])}const n=["a[href]","button:not([disabled])","input:not([disabled])","textarea:not([disabled])","select:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");const r=["mousemove","mousedown","keydown","touchstart","scroll","wheel"];function o(e,t){return"string"==typeof t?e===t:t.includes(e)}const u=400,s=8;const c=e.createContext(void 0),i=()=>"undefined"==typeof window?{x:0,y:0}:{x:window.scrollX,y:window.scrollY};const d=()=>"undefined"==typeof window?{width:0,height:0}:{width:window.innerWidth,height:window.innerHeight};exports.ToastContext=c,exports.useClickOutside=function(t,n,r="mousedown"){e.useEffect((()=>{const e=e=>{const r=e.target,o=t.current;o&&!o.contains(r)&&n(e)};return document.addEventListener(r,e),document.addEventListener("touchstart",e),()=>{document.removeEventListener(r,e),document.removeEventListener("touchstart",e)}}),[t,n,r])},exports.useCopyToClipboard=function(t=2e3){const[n,r]=e.useState({copied:!1,error:null}),o=e.useRef(null);e.useEffect((()=>()=>{null!==o.current&&clearTimeout(o.current)}),[]);const u=e.useCallback((async e=>{var n;if(null!==o.current&&(clearTimeout(o.current),o.current=null),"undefined"==typeof navigator||!(null===(n=navigator.clipboard)||void 0===n?void 0:n.writeText)){const e=new Error("Clipboard API is not available");return r({copied:!1,error:e}),!1}try{return await navigator.clipboard.writeText(e),r({copied:!0,error:null}),t>0&&(o.current=setTimeout((()=>{r((e=>Object.assign(Object.assign({},e),{copied:!1}))),o.current=null}),t)),!0}catch(e){const t=e instanceof Error?e:new Error(String(e));return r({copied:!1,error:t}),!1}}),[t]);return Object.assign(Object.assign({},n),{copy:u})},exports.useDebounce=function(t,n){const[r,o]=e.useState(t);return e.useEffect((()=>{const e=window.setTimeout((()=>o(t)),n);return()=>window.clearTimeout(e)}),[t,n]),r},exports.useDropdownPosition=function(t,n,r="auto",o=320){const[u,s]=e.useState("bottom");return e.useEffect((()=>{if("auto"!==r)return void s(r);if(!n)return;const e=()=>{if(!t.current)return;const e=t.current.getBoundingClientRect(),n=window.innerHeight-e.bottom,r=e.top;s(n>=o||n>=r?"bottom":"top")};return document.addEventListener("scroll",e,!0),e(),()=>{document.removeEventListener("scroll",e,!0)}}),[n,r,t,o]),u},exports.useEventListener=t,exports.useEventListner=t,exports.useFocusTrap=function(t,r){e.useEffect((()=>{if(!r||!t.current)return;const e=t.current,o=()=>Array.from(e.querySelectorAll(n)),u=o();u.length>0&&u[0].focus();const s=t=>{if("Tab"!==t.key)return;const n=o();if(0===n.length)return;const r=n[0],u=n[n.length-1],s=document.activeElement;t.shiftKey?s!==r&&e.contains(s)||(t.preventDefault(),u.focus()):s!==u&&e.contains(s)||(t.preventDefault(),r.focus())};return document.addEventListener("keydown",s),()=>document.removeEventListener("keydown",s)}),[t,r])},exports.useHover=function(){const[t,n]=e.useState(!1),[r,o]=e.useState(null);return e.useEffect((()=>{if(!r)return;const e=()=>n(!0),t=()=>n(!1);return r.addEventListener("mouseenter",e),r.addEventListener("mouseleave",t),()=>{r.removeEventListener("mouseenter",e),r.removeEventListener("mouseleave",t)}}),[r]),[t,o]},exports.useIdle=function(t,n={}){var o;const u=null!==(o=n.events)&&void 0!==o?o:r,s=u.join(),[c,i]=e.useState(!1),d=e.useRef(null),l=e.useCallback((()=>{null!==d.current&&clearTimeout(d.current),i(!1),d.current=setTimeout((()=>i(!0)),t)}),[t]);return e.useEffect((()=>{if("undefined"==typeof window)return;const e=u;l();for(const t of e)window.addEventListener(t,l,{passive:!0});return()=>{for(const t of e)window.removeEventListener(t,l);null!==d.current&&clearTimeout(d.current)}}),[t,s,l]),c},exports.useInterval=function(t,n){const r=e.useRef(t);e.useEffect((()=>{r.current=t}),[t]),e.useEffect((()=>{if(null===n)return;const e=window.setInterval((()=>r.current()),n);return()=>window.clearInterval(e)}),[n])},exports.useKeyPress=function(t,n){const[r,u]=e.useState(!1),s=e.useRef(n);e.useEffect((()=>{s.current=n}),[n]);const c="string"==typeof t?t:t.join("\0"),i=e.useRef(t);if(i.current=t,e.useEffect((()=>{const e=e=>{o(e.key,i.current)&&(s.current?s.current(e):u(!0))},t=e=>{o(e.key,i.current)&&(s.current||u(!1))};return window.addEventListener("keydown",e),window.addEventListener("keyup",t),()=>{window.removeEventListener("keydown",e),window.removeEventListener("keyup",t)}}),[c]),void 0===n)return r},exports.useLongPress=function(t,n={}){const{delay:r=u,moveThreshold:o=s,onClick:c}=n,i=e.useRef(null),d=e.useRef(null),l=e.useRef(!1),a=e.useCallback((()=>{null!==i.current&&(clearTimeout(i.current),i.current=null)}),[]),f=e.useCallback((e=>{0===e.button&&(l.current=!1,d.current={x:e.clientX,y:e.clientY,id:e.pointerId},a(),i.current=setTimeout((()=>{l.current=!0,t(e),i.current=null}),r))}),[a,r,t]),w=e.useCallback((e=>{if(null===d.current||e.pointerId!==d.current.id)return;const t=e.clientX-d.current.x,n=e.clientY-d.current.y;t*t+n*n>o*o&&(d.current=null,a())}),[a,o]),v=e.useCallback((e=>{null!==d.current&&e.pointerId===d.current.id&&(!l.current&&c&&c(e),d.current=null),a()}),[a,c]);return{onPointerDown:f,onPointerMove:w,onPointerUp:v,onPointerCancel:v,onPointerLeave:v}},exports.useMediaQuery=t=>{const[n,r]=e.useState(!1);return e.useEffect((()=>{if("undefined"==typeof window)return;const e=window.matchMedia(t);e.matches!==n&&r(e.matches);const o=()=>{r(e.matches)};return e.addEventListener("change",o),()=>e.removeEventListener("change",o)}),[n,t]),n},exports.useMouse=function(t=!0){const[n,r]=e.useState({x:0,y:0,hasMoved:!1});return e.useEffect((()=>{if(!t)return;if("undefined"==typeof window)return;const e=e=>{r({x:e.clientX,y:e.clientY,hasMoved:!0})};return window.addEventListener("pointermove",e,{passive:!0}),()=>{window.removeEventListener("pointermove",e)}}),[t]),n},exports.useTimeout=function(t,n){const r=e.useRef(t);e.useEffect((()=>{r.current=t}),[t]),e.useEffect((()=>{if(null===n)return;const e=window.setTimeout((()=>r.current()),n);return()=>window.clearTimeout(e)}),[n])},exports.useToast=()=>{const t=e.useContext(c);if(!t)throw new Error("useToast must be used within a ToastProvider");return t},exports.useWindowScroll=function(){const[t,n]=e.useState(i);return e.useEffect((()=>{const e=()=>n(i);return e(),window.addEventListener("scroll",e,{passive:!0,capture:!0}),()=>window.removeEventListener("scroll",e,{capture:!0})}),[]),t},exports.useWindowSize=function(){const[t,n]=e.useState(d);return e.useEffect((()=>{const e=()=>n(d());return e(),window.addEventListener("resize",e,{passive:!0}),()=>window.removeEventListener("resize",e)}),[]),t};
+//# sourceMappingURL=index.cjs.js.map

package/dist/hooks/index.d.ts

@@ -1,2 +1,4 @@
-export * from "./src/use-click-outside";
-export * from "./src/use-media-query";
+/**
+ * Subpath entry: `h2o-library/hooks`
+ */
+export * from "./hooks";