entangle-ui 0.8.2 → 0.10.0

package/dist/types/components/primitives/viewport/Viewport.types.d.ts

@@ -0,0 +1,257 @@
+import { Point2D, CanvasThemeColors } from '../canvas/canvas.types.js';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+import React from 'react';
+
+/**
+ * Viewport transform — screen-space translation + uniform scale.
+ *
+ * `screenPos = worldPos * zoom + (x, y)`
+ *
+ * Equivalent to the 2D matrix `[zoom, 0, 0, zoom, x, y]`.
+ */
+interface ViewportTransform {
+    /** Screen-space translation X in CSS pixels, applied after scaling. */
+    x: number;
+    /** Screen-space translation Y in CSS pixels, applied after scaling. */
+    y: number;
+    /** Uniform scale (1 = identity). */
+    zoom: number;
+}
+/** Axis-aligned rectangle in world coordinates. */
+interface WorldRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Viewport dimensions in CSS pixels. */
+interface ViewportSize {
+    width: number;
+    height: number;
+}
+type ViewportMouseButton = 'left' | 'middle' | 'right';
+type ViewportModifier = 'shift' | 'meta' | 'ctrl' | 'alt';
+/** Pan gesture configuration. */
+interface ViewportPanConfig {
+    /**
+     * Mouse button used for click-and-drag pan. Set to `false` to disable
+     * button-driven pan entirely (space-key may still enable pan if active).
+     * @default 'middle'
+     */
+    button?: ViewportMouseButton | false;
+    /**
+     * When true, holding Space turns any left-button drag into a pan
+     * (overrides marquee if both are enabled).
+     * @default true
+     */
+    spaceKey?: boolean;
+}
+/** Zoom gesture configuration. */
+interface ViewportZoomConfig {
+    /**
+     * Enable wheel-to-zoom (zooms toward cursor position).
+     * @default true
+     */
+    wheel?: boolean;
+    /**
+     * Enable trackpad pinch-to-zoom (handled as `ctrlKey + wheel`,
+     * which is the browser convention for trackpad pinch).
+     * @default true
+     */
+    pinch?: boolean;
+    /**
+     * Zoom factor per wheel unit. Lower = finer steps.
+     * @default 0.0015
+     */
+    speed?: number;
+}
+/** Marquee (selection rectangle) gesture configuration. */
+interface ViewportSelectionConfig {
+    /**
+     * Enable marquee selection on drag from empty viewport background.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Mouse button used to start marquee.
+     * @default 'left'
+     */
+    button?: ViewportMouseButton;
+    /**
+     * Modifier key that, when held, flags the selection as additive
+     * (passed via `onSelectionChange` info).
+     * @default 'shift'
+     */
+    additiveModifier?: ViewportModifier;
+}
+/** Marquee selection result. */
+interface ViewportSelectionEvent {
+    /** Selection rectangle in world coordinates (normalized: width/height >= 0). */
+    rect: WorldRect;
+    /** True when the additive modifier was held during the gesture. */
+    additive: boolean;
+    /** True for intermediate updates during drag, false on the final pointerup. */
+    inProgress: boolean;
+}
+/** Info passed to `onPanEnd`. */
+interface ViewportPanEndInfo {
+    /** Velocity at gesture end in screen px / ms (smoothed over a small window). */
+    velocity: {
+        x: number;
+        y: number;
+    };
+}
+interface ViewportHandle {
+    /**
+     * Pan and zoom so that `bounds` fits inside the viewport with optional inner padding.
+     * Padding is in screen pixels (deducted from the viewport on each side).
+     */
+    fitToContent(bounds: WorldRect, padding?: number): void;
+    /** Alias for `fitToContent` — pan/zoom to fit the given world rect. */
+    zoomToRect(rect: WorldRect, padding?: number): void;
+    /** Center the viewport on a world point, optionally setting zoom. */
+    centerOn(point: Point2D, zoom?: number): void;
+    /** Read the current transform. */
+    getTransform(): ViewportTransform;
+    /** Read the current viewport size in CSS pixels. */
+    getSize(): ViewportSize;
+    /**
+     * Force a redraw. With no `layerName`, all layers redraw on the next frame;
+     * with `layerName`, only that layer redraws.
+     */
+    invalidate(layerName?: string): void;
+}
+/** Info passed to a layer's `draw` callback. */
+interface ViewportLayerDrawInfo {
+    /** Current viewport size in CSS pixels. */
+    size: ViewportSize;
+    /** Current transform. */
+    transform: ViewportTransform;
+    /** Resolved theme colors for canvas 2D drawing. */
+    theme: CanvasThemeColors;
+    /** Convert a world point to a screen (CSS-pixel) point. */
+    worldToScreen(point: Point2D): Point2D;
+    /** Convert a screen (CSS-pixel) point to a world point. */
+    screenToWorld(point: Point2D): Point2D;
+}
+interface ViewportLayerBaseProps {
+    /** Unique layer name, used by `handle.invalidate(name)`. */
+    name: string;
+    /** Draw callback. Called whenever the layer invalidates. */
+    draw: (ctx: CanvasRenderingContext2D, info: ViewportLayerDrawInfo) => void;
+    /** Extra reactive dependencies that trigger a redraw when they change. */
+    invalidateOn?: ReadonlyArray<unknown>;
+    /**
+     * Pause drawing for this layer. The layer canvas stays mounted; it just
+     * stops re-rendering on transform/size/`invalidateOn` changes.
+     * @default false
+     */
+    paused?: boolean;
+    /** Optional className applied to the underlying `<canvas>` element. */
+    className?: string;
+}
+type ViewportLayerProps = Prettify<ViewportLayerBaseProps>;
+interface ViewportWorldBaseProps {
+    /** Children positioned in world coordinates. Use `position: absolute` + `left`/`top`. */
+    children?: React.ReactNode;
+    /** Optional className for the world-space wrapper. */
+    className?: string;
+    /** Optional inline styles for the world-space wrapper. */
+    style?: React.CSSProperties;
+}
+type ViewportWorldProps = Prettify<ViewportWorldBaseProps>;
+interface ViewportOverlayBaseProps {
+    /** Children positioned in screen coordinates (above world + layers). */
+    children?: React.ReactNode;
+    /** Optional className for the overlay wrapper. */
+    className?: string;
+    /** Optional inline styles for the overlay wrapper. */
+    style?: React.CSSProperties;
+}
+type ViewportOverlayProps = Prettify<ViewportOverlayBaseProps>;
+interface ViewportContextValue {
+    transform: ViewportTransform;
+    size: ViewportSize;
+    handle: ViewportHandle;
+    /** True when the user is actively panning (cursor visual hint). */
+    isPanning: boolean;
+}
+interface ViewportBaseProps extends Omit<BaseComponent, 'onChange' | 'ref'> {
+    /** Controlled transform. */
+    transform?: ViewportTransform;
+    /**
+     * Default transform when uncontrolled.
+     * @default { x: 0, y: 0, zoom: 1 }
+     */
+    defaultTransform?: ViewportTransform;
+    /** Called when the transform changes (gestures or imperative API). */
+    onTransformChange?: (transform: ViewportTransform) => void;
+    /**
+     * Minimum zoom level.
+     * @default 0.1
+     */
+    minZoom?: number;
+    /**
+     * Maximum zoom level.
+     * @default 8
+     */
+    maxZoom?: number;
+    /**
+     * Pan gesture configuration, or `false` to disable all pan gestures.
+     * @default { button: 'middle', spaceKey: true }
+     */
+    pan?: ViewportPanConfig | false;
+    /**
+     * Zoom gesture configuration, or `false` to disable all zoom gestures.
+     * @default { wheel: true, pinch: true }
+     */
+    zoom?: ViewportZoomConfig | false;
+    /**
+     * Marquee selection rectangle. Disabled by default.
+     * @default { enabled: false }
+     */
+    selectionRect?: ViewportSelectionConfig;
+    /** Called during marquee drag (intermediate + final). */
+    onSelectionChange?: (info: ViewportSelectionEvent) => void;
+    /** Called when a pan gesture starts. */
+    onPanStart?: () => void;
+    /** Called when a pan gesture ends. Includes velocity for inertia recipes. */
+    onPanEnd?: (info: ViewportPanEndInfo) => void;
+    /** Called when a zoom gesture starts. */
+    onZoomStart?: () => void;
+    /** Called when a zoom gesture ends (after a brief idle period). */
+    onZoomEnd?: () => void;
+    /**
+     * Whether the viewport fills its parent (uses ResizeObserver).
+     * @default false
+     */
+    responsive?: boolean;
+    /**
+     * Fixed height in pixels (ignored when `responsive` is true).
+     * @default 300
+     */
+    height?: number;
+    /**
+     * Disable all interaction and dim the viewport.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * ARIA role applied to the viewport wrapper.
+     * @default 'application'
+     */
+    role?: string;
+    ariaLabel?: string;
+    ariaRoledescription?: string;
+    /**
+     * Layers (`<ViewportLayer>`), world children (`<ViewportWorld>`),
+     * and overlay children (`<ViewportOverlay>`).
+     */
+    children?: React.ReactNode;
+    /** Imperative handle (fitToContent, centerOn, etc.). */
+    ref?: React.Ref<ViewportHandle>;
+}
+type ViewportProps = Prettify<ViewportBaseProps>;
+
+export type { ViewportBaseProps, ViewportContextValue, ViewportHandle, ViewportLayerBaseProps, ViewportLayerDrawInfo, ViewportLayerProps, ViewportModifier, ViewportMouseButton, ViewportOverlayBaseProps, ViewportOverlayProps, ViewportPanConfig, ViewportPanEndInfo, ViewportProps, ViewportSelectionConfig, ViewportSelectionEvent, ViewportSize, ViewportTransform, ViewportWorldBaseProps, ViewportWorldProps, ViewportZoomConfig, WorldRect };

package/dist/types/components/primitives/viewport/ViewportContext.d.ts

@@ -0,0 +1,23 @@
+import { ViewportContextValue } from './Viewport.types.js';
+
+/**
+ * Read viewport state from inside `<Viewport>` children.
+ *
+ * Returns `transform`, `size`, `isPanning`, and the imperative `handle`.
+ * The hook subscribes to every store mutation — if you only need one slice
+ * (e.g. just the transform) reach for `useViewportStore()` directly and
+ * subscribe to a single slice with `useSyncExternalStore`.
+ *
+ * @throws If called outside a `<Viewport>` subtree.
+ *
+ * @example
+ * ```tsx
+ * function Minimap() {
+ *   const { transform, size, handle } = useViewportContext();
+ *   // ...
+ * }
+ * ```
+ */
+declare function useViewportContext(): ViewportContextValue;
+
+export { useViewportContext };

package/dist/types/components/primitives/viewport/ViewportLayer.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+import { ViewportLayerProps } from './Viewport.types.js';
+
+/**
+ * A perf-isolated canvas layer inside a `<Viewport>`.
+ *
+ * Each layer owns its own `<canvas>` element and runs an independent draw
+ * cycle. Draws are scheduled via `requestAnimationFrame` whenever the
+ * viewport transform, viewport size, or any `invalidateOn` dependency
+ * changes — or when the imperative `handle.invalidate(name)` is called.
+ *
+ * @example
+ * ```tsx
+ * <ViewportLayer
+ *   name="grid"
+ *   draw={(ctx, { size, transform, theme }) => {
+ *     ctx.fillStyle = theme.borderDefault;
+ *     // ... draw grid
+ *   }}
+ *   invalidateOn={[gridStep]}
+ * />
+ * ```
+ */
+declare const ViewportLayer: React.FC<ViewportLayerProps>;
+
+export { ViewportLayer };

package/dist/types/components/primitives/viewport/ViewportOverlay.d.ts

@@ -0,0 +1,27 @@
+import React from 'react';
+import { ViewportOverlayProps } from './Viewport.types.js';
+
+/**
+ * Container for HTML children positioned in **screen coordinates**, rendered
+ * above all canvas layers and world children.
+ *
+ * Typical use: toolbars, status text, minimap, or any UI that should stay
+ * pinned to the viewport regardless of pan/zoom.
+ *
+ * Pointer events from interactive overlay children (buttons, sliders, …)
+ * are stopped at the overlay boundary so a click on the toolbar does not
+ * also start a Viewport pan or marquee gesture. The wrapper itself stays
+ * `pointer-events: none`; children opt in with `pointerEvents: 'auto'`.
+ *
+ * @example
+ * ```tsx
+ * <ViewportOverlay>
+ *   <div style={{ position: 'absolute', bottom: 8, right: 8 }}>
+ *     <Minimap />
+ *   </div>
+ * </ViewportOverlay>
+ * ```
+ */
+declare const ViewportOverlay: React.FC<ViewportOverlayProps>;
+
+export { ViewportOverlay };

package/dist/types/components/primitives/viewport/ViewportWorld.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import { ViewportWorldProps } from './Viewport.types.js';
+
+/**
+ * Container for HTML children positioned in **world coordinates**.
+ *
+ * The wrapper applies the viewport's `translate(x, y) scale(zoom)` so that
+ * children whose `left`/`top` are expressed in world units render at the
+ * correct screen position and follow pan/zoom automatically.
+ *
+ * Subscribes only to the `transform` slice of the store — re-renders when
+ * the transform changes, not when `isPanning` or `marqueeRect` flip.
+ *
+ * @example
+ * ```tsx
+ * <ViewportWorld>
+ *   <div style={{ position: 'absolute', left: 100, top: 200 }}>
+ *     Node at world (100, 200)
+ *   </div>
+ * </ViewportWorld>
+ * ```
+ */
+declare const ViewportWorld: React.FC<ViewportWorldProps>;
+
+export { ViewportWorld };

package/dist/types/components/primitives/viewport/viewportCoords.d.ts

@@ -0,0 +1,25 @@
+import { ViewportTransform } from './Viewport.types.js';
+import { Point2D } from '../canvas/canvas.types.js';
+
+/**
+ * Convert a world-space point to a screen-space (CSS-pixel) point.
+ *
+ * Uses the canonical transform: `screenPos = worldPos * zoom + (x, y)`.
+ */
+declare function worldToScreen(point: Point2D, transform: ViewportTransform): Point2D;
+/**
+ * Convert a screen-space (CSS-pixel) point to a world-space point.
+ *
+ * Inverse of `worldToScreen`.
+ */
+declare function screenToWorld(point: Point2D, transform: ViewportTransform): Point2D;
+/**
+ * Compute the screen-space (CSS-pixel) position of a pointer event relative
+ * to a viewport element.
+ */
+declare function getViewportPointerPosition(event: {
+    clientX: number;
+    clientY: number;
+}, viewport: HTMLElement): Point2D;
+
+export { getViewportPointerPosition, screenToWorld, worldToScreen };

package/dist/types/components/primitives/viewport/viewportMath.d.ts

@@ -0,0 +1,35 @@
+import { ViewportSize, ViewportTransform, WorldRect } from './Viewport.types.js';
+import { Point2D } from '../canvas/canvas.types.js';
+
+interface ZoomLimits {
+    minZoom: number;
+    maxZoom: number;
+}
+/**
+ * Compute a transform that fits `bounds` (in world coordinates) into the
+ * viewport `size`, with optional uniform inner `padding` in screen pixels.
+ *
+ * The resulting transform preserves aspect ratio (uniform zoom on both axes)
+ * and centers the content within the viewport.
+ */
+declare function computeFitTransform(bounds: WorldRect, size: ViewportSize, padding: number, limits: ZoomLimits): ViewportTransform;
+/**
+ * Compute a transform that centers `point` (world coordinates) in the
+ * viewport, optionally setting a new zoom.
+ */
+declare function computeCenterTransform(point: Point2D, size: ViewportSize, current: ViewportTransform, limits: ZoomLimits, nextZoom?: number): ViewportTransform;
+/**
+ * Compute the new transform for a "zoom toward pivot" gesture.
+ *
+ * The world point currently under `pivot` (screen pixels) stays under
+ * the pivot after the zoom change.
+ */
+declare function computeZoomTowardPivot(pivot: Point2D, factor: number, current: ViewportTransform, limits: ZoomLimits): ViewportTransform;
+/**
+ * Normalize a rectangle so that width and height are non-negative,
+ * adjusting the origin accordingly. Useful for marquee selection
+ * where the user may drag in any direction.
+ */
+declare function normalizeRect(rect: WorldRect): WorldRect;
+
+export { computeCenterTransform, computeFitTransform, computeZoomTowardPivot, normalizeRect };

package/dist/types/components/shell/AppShell/AppShell.types.d.ts

@@ -1,11 +1,11 @@
-import { ReactNode } from 'react';
 import { BaseComponent } from '../../../types/common.js';
 import { Prettify } from '../../../types/utilities.js';
+import { ReactNode } from 'react';
 
 type ToolbarPosition = 'top' | 'left' | 'right';
 type AppShellTopChromeSeparator = 'none' | 'border' | 'shadow' | 'both';
 type AppShellSideChromeSeparator = 'none' | 'border' | 'shadow' | 'both';
-interface AppShellBaseProps extends Omit<BaseComponent<HTMLDivElement>, 'children'> {
+interface AppShellBaseProps extends Omit<BaseComponent, 'children'> {
     /** Lock the shell to the viewport (injects global html/body styles) */
     viewportLock?: boolean;
     /**

package/dist/types/components/shell/FloatingPanel/FloatingPanel.types.d.ts

@@ -1,6 +1,6 @@
-import { ReactNode } from 'react';
 import { BaseComponent } from '../../../types/common.js';
 import { Prettify } from '../../../types/utilities.js';
+import { ReactNode } from 'react';
 
 interface Position {
     x: number;
@@ -10,7 +10,7 @@ interface FloatingPanelSize {
     width: number;
     height: number;
 }
-interface FloatingPanelBaseProps extends Omit<BaseComponent<HTMLDivElement>, 'children'> {
+interface FloatingPanelBaseProps extends Omit<BaseComponent, 'children'> {
     /** Panel title displayed in the header */
     title: string;
     /** Controlled position */

package/dist/types/components/shell/MenuBar/MenuBar.types.d.ts

@@ -1,9 +1,9 @@
-import { ReactNode } from 'react';
 import { BaseComponent } from '../../../types/common.js';
 import { Prettify } from '../../../types/utilities.js';
+import { ReactNode } from 'react';
 
 type MenuBarSize = 'sm' | 'md';
-interface MenuBarBaseProps extends BaseComponent<HTMLDivElement> {
+interface MenuBarBaseProps extends BaseComponent {
     /** Size of the menu bar */
     size?: MenuBarSize;
     /** Vertical gap in pixels between top-level trigger and dropdown */
@@ -12,7 +12,7 @@ interface MenuBarBaseProps extends BaseComponent<HTMLDivElement> {
     children?: ReactNode;
 }
 type MenuBarProps = Prettify<MenuBarBaseProps>;
-interface MenuBarMenuBaseProps extends BaseComponent<HTMLDivElement> {
+interface MenuBarMenuBaseProps extends BaseComponent {
     /** The trigger label */
     label: string;
     /** Dropdown menu items */
@@ -34,7 +34,7 @@ interface MenuBarItemBaseProps extends Omit<BaseComponent<HTMLButtonElement>, 'o
     children?: ReactNode;
 }
 type MenuBarItemProps = Prettify<MenuBarItemBaseProps>;
-interface MenuBarSubBaseProps extends BaseComponent<HTMLDivElement> {
+interface MenuBarSubBaseProps extends BaseComponent {
     /** Sub-menu trigger label */
     label: string;
     /** Sub-menu items */
@@ -43,6 +43,6 @@ interface MenuBarSubBaseProps extends BaseComponent<HTMLDivElement> {
     disabled?: boolean;
 }
 type MenuBarSubProps = Prettify<MenuBarSubBaseProps>;
-type MenuBarSeparatorProps = Prettify<BaseComponent<HTMLDivElement>>;
+type MenuBarSeparatorProps = Prettify<BaseComponent>;
 
 export type { MenuBarBaseProps, MenuBarItemBaseProps, MenuBarItemProps, MenuBarMenuBaseProps, MenuBarMenuProps, MenuBarProps, MenuBarSeparatorProps, MenuBarSize, MenuBarSubBaseProps, MenuBarSubProps };

package/dist/types/components/shell/StatusBar/StatusBar.types.d.ts

@@ -1,10 +1,10 @@
-import { ReactNode } from 'react';
 import { BaseComponent } from '../../../types/common.js';
 import { Prettify } from '../../../types/utilities.js';
+import { ReactNode } from 'react';
 
 type StatusBarSize = 'sm' | 'md';
 type StatusBarVariant = 'default' | 'error' | 'accent';
-interface StatusBarBaseProps extends BaseComponent<HTMLDivElement> {
+interface StatusBarBaseProps extends BaseComponent {
     /** Size of the status bar */
     size?: StatusBarSize;
     /** Visual variant */
@@ -14,7 +14,7 @@ interface StatusBarBaseProps extends BaseComponent<HTMLDivElement> {
 }
 type StatusBarProps = Prettify<StatusBarBaseProps>;
 type StatusBarSectionSide = 'left' | 'right';
-interface StatusBarSectionBaseProps extends BaseComponent<HTMLDivElement> {
+interface StatusBarSectionBaseProps extends BaseComponent {
     /** Which side of the status bar */
     side?: StatusBarSectionSide;
     /** Children (StatusBar.Item components) */

package/dist/types/components/shell/Toolbar/Toolbar.types.d.ts

@@ -1,11 +1,11 @@
-import { ReactNode } from 'react';
 import { BaseComponent } from '../../../types/common.js';
 import { Prettify } from '../../../types/utilities.js';
+import { ReactNode } from 'react';
 
 type ToolbarOrientation = 'horizontal' | 'vertical';
 type ToolbarSize = 'sm' | 'md';
 type ToolbarButtonVariant = 'default' | 'ghost' | 'filled';
-interface ToolbarBaseProps extends BaseComponent<HTMLDivElement> {
+interface ToolbarBaseProps extends BaseComponent {
     /** Orientation of the toolbar */
     orientation?: ToolbarOrientation;
     /** Size of toolbar items */
@@ -46,14 +46,14 @@ interface ToolbarToggleBaseProps extends BaseComponent<HTMLButtonElement> {
     disabled?: boolean;
 }
 type ToolbarToggleProps = Prettify<ToolbarToggleBaseProps>;
-interface ToolbarGroupBaseProps extends BaseComponent<HTMLDivElement> {
+interface ToolbarGroupBaseProps extends BaseComponent {
     /** Group label for accessibility */
     'aria-label'?: string;
     /** Children (Toolbar.Button, Toolbar.Toggle) */
     children?: ReactNode;
 }
 type ToolbarGroupProps = Prettify<ToolbarGroupBaseProps>;
-type ToolbarSeparatorProps = Prettify<BaseComponent<HTMLDivElement>>;
-type ToolbarSpacerProps = Prettify<BaseComponent<HTMLDivElement>>;
+type ToolbarSeparatorProps = Prettify<BaseComponent>;
+type ToolbarSpacerProps = Prettify<BaseComponent>;
 
 export type { ToolbarBaseProps, ToolbarButtonBaseProps, ToolbarButtonProps, ToolbarButtonVariant, ToolbarGroupBaseProps, ToolbarGroupProps, ToolbarOrientation, ToolbarProps, ToolbarSeparatorProps, ToolbarSize, ToolbarSpacerProps, ToolbarToggleBaseProps, ToolbarToggleProps };

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

@@ -0,0 +1,19 @@
+import { UseBreakpointReturn } from './useBreakpoint.types.js';
+
+/**
+ * Reactive named-breakpoint matcher.
+ *
+ * Returns booleans for each named breakpoint plus the largest matching
+ * `current`. Built on top of `useMediaQuery`. Breakpoint values come from
+ * `@/theme/breakpoints` and match the values used by `Stack` and other
+ * responsive layout components.
+ *
+ * @example
+ * ```tsx
+ * const { md, current } = useBreakpoint();
+ * return md ? <Sidebar /> : <BottomSheet />;
+ * ```
+ */
+declare function useBreakpoint(): UseBreakpointReturn;
+
+export { useBreakpoint };

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

@@ -0,0 +1,20 @@
+import { Breakpoint } from '../../theme/breakpoints.js';
+
+interface BreakpointMap {
+    /** Always `true` — base mobile breakpoint. */
+    xs: boolean;
+    /** `min-width: 576px`. */
+    sm: boolean;
+    /** `min-width: 768px`. */
+    md: boolean;
+    /** `min-width: 992px`. */
+    lg: boolean;
+    /** `min-width: 1200px`. */
+    xl: boolean;
+}
+interface UseBreakpointReturn extends BreakpointMap {
+    /** Name of the largest matching breakpoint. */
+    current: Breakpoint;
+}
+
+export type { BreakpointMap, UseBreakpointReturn };

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

@@ -0,0 +1,15 @@
+interface UseDebouncedCallbackOptions {
+    /** Fire on the leading edge in addition to trailing. @default false */
+    leading?: boolean;
+    /** Maximum time the callback may be deferred before being forced. */
+    maxWait?: number;
+}
+interface DebouncedCallback<Args extends unknown[]> {
+    (...args: Args): void;
+    /** Cancel a pending call. */
+    cancel: () => void;
+    /** Fire a pending call immediately (no-op when nothing is pending). */
+    flush: () => void;
+}
+
+export type { DebouncedCallback, UseDebouncedCallbackOptions };

package/dist/types/hooks/useDebounced/useDebouncedCallback.d.ts

@@ -0,0 +1,22 @@
+import { UseDebouncedCallbackOptions, DebouncedCallback } from './useDebounced.types.js';
+
+/**
+ * Wrap a function so rapid calls collapse into one. By default the call
+ * fires on the trailing edge — pass `leading: true` to also fire
+ * immediately. `maxWait` forces a call even when calls keep coming.
+ *
+ * The wrapper identity is stable; passing fresh inline functions across
+ * renders is safe and does not reset pending timers.
+ *
+ * @example
+ * ```tsx
+ * const onResize = useDebouncedCallback(measure, 150);
+ * useEffect(() => {
+ *   window.addEventListener('resize', onResize);
+ *   return () => window.removeEventListener('resize', onResize);
+ * }, [onResize]);
+ * ```
+ */
+declare function useDebouncedCallback<Args extends unknown[]>(fn: (...args: Args) => void, delay: number, options?: UseDebouncedCallbackOptions): DebouncedCallback<Args>;
+
+export { useDebouncedCallback };

package/dist/types/hooks/useDebounced/useDebouncedValue.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Returns a copy of `value` that updates only after `delay` ms have elapsed
+ * without further changes (trailing-edge debounce).
+ *
+ * @deprecated Prefer React's `useDeferredValue` for the common case — keeping
+ * an input responsive while an expensive derivation (filtering, search) lags
+ * behind it. It needs no fixed delay, integrates with concurrent rendering,
+ * and gives better interactivity on large lists. Reach for `useDebouncedCallback`
+ * when you need to debounce a *side effect* (a network request, an analytics
+ * ping) rather than a rendered value. This hook stays exported for now but
+ * will not see further work.
+ *
+ * @example
+ * ```tsx
+ * // Preferred: defer the value that drives the expensive derivation.
+ * const deferredQuery = useDeferredValue(query);
+ * const results = useMemo(
+ *   () => filter(items, deferredQuery),
+ *   [items, deferredQuery]
+ * );
+ * ```
+ */
+declare function useDebouncedValue<T>(value: T, delay: number): T;
+
+export { useDebouncedValue };