@abuzareal/contour-ui 0.4.0 → 0.6.0

package/dist/components/ui/ThemeScope.d.ts

@@ -0,0 +1,13 @@
+import type { HTMLAttributes } from "react";
+import type { Theme } from "../../hooks/useTheme.js";
+export type ThemeScopeProps = HTMLAttributes<HTMLDivElement> & {
+    theme: Theme;
+    /** Caller owns persistence; omitting this makes embedded theme controls read-only. */
+    onThemeChange?: (theme: Theme) => void;
+};
+declare const ThemeScope: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+    theme: Theme;
+    /** Caller owns persistence; omitting this makes embedded theme controls read-only. */
+    onThemeChange?: (theme: Theme) => void;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default ThemeScope;

package/dist/components/ui/ThemeScope.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useMemo } from "react";
+import { ThemeScopeContext } from "../../lib/themeScope.js";
+import { cx } from "../../lib/classNames.js";
+const ThemeScope = forwardRef(function ThemeScope({ theme, onThemeChange, className, children, ...rest }, ref) {
+    const context = useMemo(() => ({ theme, onThemeChange }), [theme, onThemeChange]);
+    return (_jsx(ThemeScopeContext.Provider, { value: context, children: _jsx("div", { ...rest, ref: ref, "data-contour-theme": theme, className: cx("contour-root", className), children: children }) }));
+});
+export default ThemeScope;

package/dist/components/ui/ThemeToggle.d.ts

@@ -1,6 +1,9 @@
 export type ThemeToggleProps = {
     /** When false the theme switches instantly instead of animating. */
     animate: boolean;
+    darkLabel?: string;
+    lightTitle?: string;
+    darkTitle?: string;
 };
 declare const ThemeToggle: import("react").ForwardRefExoticComponent<ThemeToggleProps & import("react").RefAttributes<HTMLButtonElement>>;
 export default ThemeToggle;

package/dist/components/ui/ThemeToggle.js

@@ -1,12 +1,13 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 /** Header button that switches between the light and dark themes. */
 import { forwardRef } from "react";
 import { Moon, Sun } from "lucide-react";
 import useTheme from "../../hooks/useTheme.js";
-const ThemeToggle = forwardRef(function ThemeToggle({ animate }, ref) {
-    const { theme, toggle } = useTheme(animate);
+const ThemeToggle = forwardRef(function ThemeToggle({ animate, darkLabel = "Dark theme", lightTitle = "Switch to light theme", darkTitle = "Switch to dark theme", }, ref) {
+    const { theme, toggle, canToggle } = useTheme(animate);
     const dark = theme === "dark";
-    return (_jsxs("button", { ref: ref, type: "button", className: "theme-toggle", "aria-label": "Dark theme", "aria-pressed": dark, title: dark ? "Switch to light theme" : "Switch to dark theme", onClick: (event) => toggle(event.currentTarget), children: [_jsx(Moon, { className: "theme-icon-moon", size: 16, "aria-hidden": "true" }), _jsx(Sun, { className: "theme-icon-sun", size: 17, "aria-hidden": "true" })] }));
+    return (_jsxs("button", { ref: ref, type: "button", className: ccx("theme-toggle"), "aria-label": darkLabel, "aria-pressed": dark, disabled: !canToggle, title: dark ? lightTitle : darkTitle, onClick: (event) => toggle(event.currentTarget), children: [_jsx(Moon, { className: ccx("theme-icon-moon"), size: 16, "aria-hidden": "true" }), _jsx(Sun, { className: ccx("theme-icon-sun"), size: 17, "aria-hidden": "true" })] }));
 });
 export default ThemeToggle;

package/dist/components/ui/TiltCard.js

@@ -1,11 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ccx } from "../../lib/classNames.js";
 /** Card that tilts in 3D toward a fine pointer with a moving glare highlight. */
 import { useRef } from "react";
 import { motionDisabledFor } from "../../lib/motion.js";
 export default function TiltCard({ children, maxTilt = 12 }) {
     const ref = useRef(null);
-    return (_jsx("div", { className: "tilt-stage", children: _jsxs("div", { ref: ref, className: "tilt-card", onPointerMove: (event) => {
+    return (_jsx("div", { className: ccx("tilt-stage"), children: _jsxs("div", { ref: ref, className: ccx("tilt-card"), onPointerMove: (event) => {
                 const element = ref.current;
                 if (!element ||
                     event.pointerType !== "mouse" ||
@@ -20,5 +21,5 @@ export default function TiltCard({ children, maxTilt = 12 }) {
                 element.style.setProperty("--glare-y", `${y * 100}%`);
             }, onPointerLeave: () => {
                 ["--tilt-x", "--tilt-y", "--glare-x", "--glare-y"].forEach((name) => ref.current?.style.removeProperty(name));
-            }, children: [children, _jsx("span", { className: "tilt-glare", "aria-hidden": "true" })] }) }));
+            }, children: [children, _jsx("span", { className: ccx("tilt-glare"), "aria-hidden": "true" })] }) }));
 }

package/dist/components/ui/Timeline.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Vertical timeline of dated entries joined by a rule, with an acid marker for the current one. */
-import { cx } from "../../lib/classNames.js";
+import { ccx } from "../../lib/classNames.js";
 export default function Timeline({ entries }) {
-    return (_jsx("ol", { className: "timeline", children: entries.map((entry) => (_jsxs("li", { className: cx("timeline-entry", entry.current && "timeline-current"), children: [_jsx("span", { className: "timeline-date mono", children: entry.date }), _jsx("span", { className: "timeline-title", children: entry.title }), entry.body && _jsx("span", { className: "timeline-body", children: entry.body })] }, `${entry.date}-${entry.title}`))) }));
+    return (_jsx("ol", { className: ccx("timeline"), children: entries.map((entry) => (_jsxs("li", { className: ccx("timeline-entry", entry.current && "timeline-current"), children: [_jsx("span", { className: ccx("timeline-date mono"), children: entry.date }), _jsx("span", { className: ccx("timeline-title"), children: entry.title }), entry.body && (_jsx("span", { className: ccx("timeline-body"), children: entry.body }))] }, `${entry.date}-${entry.title}`))) }));
 }

package/dist/components/ui/ToastProvider.d.ts

@@ -1,5 +1,8 @@
 /** Renders queued toasts in a polite live region; each auto-dismisses unless hovered or focused. */
 import { type ReactNode } from "react";
-export default function ToastProvider({ children }: {
+export type ToastProviderProps = {
     children: ReactNode;
-}): import("react").JSX.Element;
+    label?: string;
+    dismissLabel?: string;
+};
+export default function ToastProvider({ children, label, dismissLabel, }: ToastProviderProps): import("react").JSX.Element;

package/dist/components/ui/ToastProvider.js

@@ -4,9 +4,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { X } from "lucide-react";
 import { ToastContext, } from "../../hooks/useToast.js";
-import { cx } from "../../lib/classNames.js";
+import { ccx } from "../../lib/classNames.js";
 const autoDismissAfter = 5000;
-function Toast({ toast, onDismiss, }) {
+function Toast({ toast, onDismiss, dismissLabel, }) {
     const [paused, setPaused] = useState(false);
     useEffect(() => {
         if (paused)
@@ -14,9 +14,9 @@ function Toast({ toast, onDismiss, }) {
         const timer = window.setTimeout(() => onDismiss(toast.id), autoDismissAfter);
         return () => window.clearTimeout(timer);
     }, [paused, toast.id, onDismiss]);
-    return (_jsxs("li", { className: cx("toast", `toast-${toast.tone ?? "neutral"}`), onPointerEnter: () => setPaused(true), onPointerLeave: () => setPaused(false), onFocus: () => setPaused(true), onBlur: () => setPaused(false), children: [_jsx("span", { className: "toast-bar", "aria-hidden": "true" }), _jsxs("div", { className: "toast-content", children: [_jsx("strong", { children: toast.title }), toast.message && _jsx("p", { children: toast.message })] }), _jsx("button", { type: "button", className: "toast-close", "aria-label": "Dismiss notification", onClick: () => onDismiss(toast.id), children: _jsx(X, { size: 15 }) })] }));
+    return (_jsxs("li", { className: ccx("toast", `toast-${toast.tone ?? "neutral"}`), onPointerEnter: () => setPaused(true), onPointerLeave: () => setPaused(false), onFocus: () => setPaused(true), onBlur: () => setPaused(false), children: [_jsx("span", { className: ccx("toast-bar"), "aria-hidden": "true" }), _jsxs("div", { className: ccx("toast-content"), children: [_jsx("strong", { children: toast.title }), toast.message && _jsx("p", { children: toast.message })] }), _jsx("button", { type: "button", className: ccx("toast-close"), "aria-label": dismissLabel, onClick: () => onDismiss(toast.id), children: _jsx(X, { size: 15 }) })] }));
 }
-export default function ToastProvider({ children }) {
+export default function ToastProvider({ children, label = "Notifications", dismissLabel = "Dismiss notification", }) {
     const [toasts, setToasts] = useState([]);
     const nextId = useRef(0);
     const dismiss = useCallback((id) => setToasts((current) => current.filter((toast) => toast.id !== id)), []);
@@ -26,5 +26,5 @@ export default function ToastProvider({ children }) {
             { ...toast, id: (nextId.current += 1) },
         ]),
     }), []);
-    return (_jsxs(ToastContext.Provider, { value: value, children: [children, _jsx("ol", { className: "toast-viewport", "aria-live": "polite", "aria-label": "Notifications", children: toasts.map((toast) => (_jsx(Toast, { toast: toast, onDismiss: dismiss }, toast.id))) })] }));
+    return (_jsxs(ToastContext.Provider, { value: value, children: [children, _jsx("ol", { className: ccx("toast-viewport"), "aria-live": "polite", "aria-label": label, children: toasts.map((toast) => (_jsx(Toast, { toast: toast, onDismiss: dismiss, dismissLabel: dismissLabel }, toast.id))) })] }));
 }

package/dist/components/ui/Tooltip.d.ts

@@ -1,11 +1,11 @@
-/** Ink tooltip shown on hover or focus, dismissible with Escape, described via aria-describedby. */
 import { type ReactElement } from "react";
-export type TooltipProps = {
+import type { FloatingOptions } from "../../hooks/useFloatingPanel.js";
+export type TooltipProps = Omit<FloatingOptions, "side"> & {
     content: string;
-    /** A single focusable element, e.g. a button. */
+    /** One focusable element. Supplemental noninteractive text only. */
     children: ReactElement<{
         "aria-describedby"?: string;
     }>;
     placement?: "top" | "bottom" | "left" | "right";
 };
-export default function Tooltip({ content, children, placement, }: TooltipProps): import("react").JSX.Element;
+export default function Tooltip({ content, children, placement, align, sideOffset, collisionPadding, portal, container, }: TooltipProps): import("react").JSX.Element;

package/dist/components/ui/Tooltip.js

@@ -1,17 +1,77 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/** Ink tooltip shown on hover or focus, dismissible with Escape, described via aria-describedby. */
-import { cloneElement, useId, useState } from "react";
-import { cx } from "../../lib/classNames.js";
-export default function Tooltip({ content, children, placement = "top", }) {
+import { useContext, cloneElement, useMemo, useEffect, useId, useRef, useState, } from "react";
+import { composeRefs } from "../../lib/composeRefs.js";
+import { ccx } from "../../lib/classNames.js";
+import { LayerVisibility } from "../../lib/layers.js";
+import useDismiss from "../../hooks/useLayerDismiss.js";
+import FloatingPortal from "./FloatingPortal.js";
+export default function Tooltip({ content, children, placement = "top", align = "center", sideOffset = 10, collisionPadding = 8, portal = true, container, }) {
     const id = useId();
-    const [open, setOpen] = useState(false);
-    return (_jsxs("span", { className: "tooltip-anchor", onPointerEnter: () => setOpen(true), onPointerLeave: () => setOpen(false), onFocus: () => setOpen(true), onBlur: () => setOpen(false), onKeyDown: (event) => {
-            if (event.key === "Escape")
-                setOpen(false);
-        }, children: [cloneElement(children, {
+    const anchor = useRef(null), panel = useRef(null);
+    const [anchorElement, setAnchorElement] = useState(null);
+    const attachAnchor = useMemo(() => composeRefs(anchor, setAnchorElement), []);
+    const [hovered, setHovered] = useState(false), [focused, setFocused] = useState(false);
+    const [dismissed, setDismissed] = useState(false);
+    const parentVisible = useContext(LayerVisibility);
+    const open = (hovered || focused) && !dismissed && parentVisible;
+    const timer = useRef(undefined);
+    const clear = () => {
+        clearTimeout(timer.current);
+        timer.current = undefined;
+    };
+    const enter = () => {
+        clear();
+        setHovered(true);
+        if (!focused && !hovered)
+            setDismissed(false);
+    };
+    const leave = () => {
+        clear();
+        timer.current = setTimeout(() => {
+            setHovered(false);
+        }, 160);
+    };
+    useEffect(() => () => clearTimeout(timer.current), []);
+    useEffect(() => {
+        if (!hovered)
+            return;
+        const doc = anchor.current?.ownerDocument;
+        const move = (event) => {
+            const a = anchor.current?.getBoundingClientRect(), p = panel.current?.getBoundingClientRect();
+            if (!a || !p)
+                return;
+            // Keep the pointer corridor between trigger and hint available, including slow travel.
+            const inside = event.clientX >= Math.min(a.left, p.left) - 4 &&
+                event.clientX <= Math.max(a.right, p.right) + 4 &&
+                event.clientY >= Math.min(a.top, p.top) - 4 &&
+                event.clientY <= Math.max(a.bottom, p.bottom) + 4;
+            if (inside)
+                clear();
+            else
+                leave();
+        };
+        doc?.addEventListener("pointermove", move);
+        return () => doc?.removeEventListener("pointermove", move);
+    }, [hovered]);
+    useDismiss(anchor, open, () => setDismissed(true), {
+        branches: [panel],
+        layerElement: panel,
+    });
+    return (_jsxs("span", { ref: attachAnchor, className: ccx("tooltip-anchor"), onPointerEnter: enter, onPointerLeave: leave, onFocus: () => {
+            setFocused(true);
+            if (!hovered)
+                setDismissed(false);
+        }, onBlur: () => setFocused(false), children: [cloneElement(children, {
                 "aria-describedby": [children.props["aria-describedby"], id]
                     .filter(Boolean)
                     .join(" "),
-            }), _jsx("span", { id: id, role: "tooltip", className: cx("tooltip mono", `tooltip-${placement}`, open && "is-open"), children: content })] }));
+            }), _jsx(FloatingPortal, { anchorElement: anchorElement, anchor: anchor, panel: panel, open: open, options: {
+                    side: placement,
+                    align,
+                    sideOffset,
+                    collisionPadding,
+                    portal,
+                    container,
+                }, children: _jsx("span", { ref: panel, id: id, role: "tooltip", className: ccx("tooltip mono", `tooltip-${placement}`, open && "is-open"), onPointerEnter: enter, onPointerLeave: leave, children: content }) })] }));
 }

package/dist/data-display.css

@@ -0,0 +1,5 @@
+@import "./scoped/tokens.css";
+@import "./scoped/base.css";
+@import "./scoped/utilities.css";
+@import "./scoped/ui.css";
+@import "./scoped/kit/data-display.css";

package/dist/effects.css

@@ -0,0 +1,6 @@
+@import "./scoped/tokens.css";
+@import "./scoped/base.css";
+@import "./scoped/utilities.css";
+@import "./scoped/ui.css";
+@import "./scoped/kit/effects.css";
+@import "./scoped/marquee.css";

package/dist/feedback.css

@@ -0,0 +1,5 @@
+@import "./scoped/tokens.css";
+@import "./scoped/base.css";
+@import "./scoped/utilities.css";
+@import "./scoped/ui.css";
+@import "./scoped/kit/feedback.css";

package/dist/fonts-latin.css

@@ -4,8 +4,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 1000;
-  src: url("./fonts/dm-sans-latin-wght-normal.woff2")
-    format("woff2-variations");
+  src: url("./fonts/dm-sans-latin-wght-normal.woff2") format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC,
     U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212,
@@ -30,6 +29,13 @@
   font-style: normal;
   font-display: swap;
   font-weight: 400;
-  src: url("./fonts/dm-mono-latin-400-normal.woff2")
-    format("woff2");
+  src: url("./fonts/dm-mono-latin-400-normal.woff2") format("woff2");
+}
+
+/* Explicit branded typography for isolated components; import after scoped styles. */
+:where(:root) {
+  --contour-font-sans: "DM Sans Variable", "DM Sans", system-ui, sans-serif;
+  --contour-font-display:
+    "Space Grotesk Variable", "Space Grotesk", system-ui, sans-serif;
+  --contour-font-mono: "DM Mono", ui-monospace, monospace;
 }

package/dist/fonts.css

@@ -1,3 +1,11 @@
 @import "@fontsource-variable/dm-sans/wght.css";
 @import "@fontsource-variable/space-grotesk/wght.css";
 @import "@fontsource/dm-mono/400.css";
+
+/* Explicit branded typography for isolated components; import after scoped styles. */
+:where(:root) {
+  --contour-font-sans: "DM Sans Variable", "DM Sans", system-ui, sans-serif;
+  --contour-font-display:
+    "Space Grotesk Variable", "Space Grotesk", system-ui, sans-serif;
+  --contour-font-mono: "DM Mono", ui-monospace, monospace;
+}

package/dist/forms.css

@@ -0,0 +1,5 @@
+@import "./scoped/tokens.css";
+@import "./scoped/base.css";
+@import "./scoped/utilities.css";
+@import "./scoped/ui.css";
+@import "./scoped/kit/forms.css";

package/dist/hooks/useComboboxAnchor.d.ts

@@ -0,0 +1,17 @@
+import { type RefObject } from "react";
+/** Use public virtual-anchor/Rect extension points; keep upstream focus/selection and positioning. */
+export default function useComboboxAnchor(input: HTMLInputElement | null, floating: RefObject<HTMLDivElement | null>): {
+    anchor?: undefined;
+    collisionBoundary?: undefined;
+} | {
+    anchor: {
+        contextElement: HTMLElement;
+        getBoundingClientRect(): DOMRect;
+    };
+    collisionBoundary: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+};

package/dist/hooks/useComboboxAnchor.js

@@ -0,0 +1,61 @@
+"use client";
+import { useMemo } from "react";
+import { platform } from "@floating-ui/dom";
+/** Fixed children of a zoomed body need anchor and viewport in the same local CSS units. */
+function windowScale(element) {
+    if (!element ||
+        platform.getOffsetParent?.(element) !== element.ownerDocument.defaultView)
+        return { x: 1, y: 1 };
+    const scale = platform.getScale?.(element);
+    if (!scale ||
+        !("x" in scale) ||
+        !("y" in scale) ||
+        !Number.isFinite(scale.x) ||
+        !Number.isFinite(scale.y) ||
+        scale.x <= 0 ||
+        scale.y <= 0)
+        return { x: 1, y: 1 };
+    return scale;
+}
+/** Use public virtual-anchor/Rect extension points; keep upstream focus/selection and positioning. */
+export default function useComboboxAnchor(input, floating) {
+    return useMemo(() => {
+        const source = input?.parentElement ?? input;
+        if (!source)
+            return {};
+        return {
+            anchor: {
+                contextElement: source,
+                getBoundingClientRect() {
+                    const rect = source.getBoundingClientRect(), scale = windowScale(floating.current);
+                    rect.x /= scale.x;
+                    rect.y /= scale.y;
+                    rect.width /= scale.x;
+                    rect.height /= scale.y;
+                    return rect;
+                },
+            },
+            // Getters are evaluated on each upstream update, including scroll, zoom and mobile viewport resize.
+            collisionBoundary: {
+                get x() {
+                    return ((source.ownerDocument.defaultView?.visualViewport?.offsetLeft ??
+                        0) / windowScale(floating.current).x);
+                },
+                get y() {
+                    return ((source.ownerDocument.defaultView?.visualViewport?.offsetTop ?? 0) /
+                        windowScale(floating.current).y);
+                },
+                get width() {
+                    return ((source.ownerDocument.defaultView?.visualViewport?.width ??
+                        source.ownerDocument.documentElement.clientWidth) /
+                        windowScale(floating.current).x);
+                },
+                get height() {
+                    return ((source.ownerDocument.defaultView?.visualViewport?.height ??
+                        source.ownerDocument.documentElement.clientHeight) /
+                        windowScale(floating.current).y);
+                },
+            },
+        };
+    }, [input, floating]);
+}

package/dist/hooks/useDismiss.d.ts

@@ -1,3 +1,12 @@
-/** Calls onDismiss on Escape or a pointer press outside the container while `active`. */
-import { type RefObject } from "react";
-export default function useDismiss(container: RefObject<HTMLElement | null>, active: boolean, onDismiss: (reason: "escape" | "outside") => void): void;
+import type { RefObject } from "react";
+import type { DismissReason } from "../lib/layers.js";
+export type DismissOptions = {
+    /** Additional owned elements, including portaled content and the trigger. */
+    layerElement?: RefObject<HTMLElement | null>;
+    branches?: RefObject<HTMLElement | null>[];
+    /** Native modal backdrops own outside-click behavior. */
+    outside?: boolean;
+};
+/** Topmost layer dismissal in the container's document; caller cancellation is respected. */
+/** Preserves the public void-returning dismissal hook; built-in layers use an internal handle. */
+export default function useDismiss(container: RefObject<HTMLElement | null>, active: boolean, onDismiss: (reason: DismissReason, event: KeyboardEvent | PointerEvent) => void, options?: DismissOptions): void;

package/dist/hooks/useDismiss.js

@@ -1,23 +1,7 @@
 "use client";
-/** Calls onDismiss on Escape or a pointer press outside the container while `active`. */
-import { useEffect } from "react";
-export default function useDismiss(container, active, onDismiss) {
-    useEffect(() => {
-        if (!active)
-            return;
-        const onKeyDown = (event) => {
-            if (event.key === "Escape")
-                onDismiss("escape");
-        };
-        const onPointerDown = (event) => {
-            if (!container.current?.contains(event.target))
-                onDismiss("outside");
-        };
-        document.addEventListener("keydown", onKeyDown);
-        document.addEventListener("pointerdown", onPointerDown);
-        return () => {
-            document.removeEventListener("keydown", onKeyDown);
-            document.removeEventListener("pointerdown", onPointerDown);
-        };
-    }, [container, active, onDismiss]);
+import useLayerDismiss from "./useLayerDismiss.js";
+/** Topmost layer dismissal in the container's document; caller cancellation is respected. */
+/** Preserves the public void-returning dismissal hook; built-in layers use an internal handle. */
+export default function useDismiss(container, active, onDismiss, options = {}) {
+    useLayerDismiss(container, active, onDismiss, options);
 }

package/dist/hooks/useFloatingPanel.d.ts

@@ -0,0 +1,14 @@
+import { type RefObject } from "react";
+export type FloatingOptions = {
+    side?: "top" | "bottom" | "left" | "right";
+    align?: "start" | "center" | "end";
+    sideOffset?: number;
+    collisionPadding?: number;
+    /** false keeps content inline; default portals into its owner body or active modal with inherited theme variables. */
+    portal?: boolean;
+    /** Must belong to the trigger's document and be inside the active modal, when applicable. */
+    container?: HTMLElement | null;
+};
+export declare function floatingContainer(anchor: HTMLElement, options: FloatingOptions): HTMLElement;
+/** DOM adapter: clean up observers and ignore obsolete asynchronous positioning results. */
+export default function useFloatingPanel(anchor: RefObject<HTMLElement | null>, panel: RefObject<HTMLElement | null>, open: boolean, { side, align, sideOffset, collisionPadding, container, }: FloatingOptions): void;

package/dist/hooks/useFloatingPanel.js

@@ -0,0 +1,157 @@
+"use client";
+import { useLayoutEffect } from "react";
+import { autoUpdate, computePosition, flip, offset, shift, size, platform, } from "@floating-ui/dom";
+export function floatingContainer(anchor, options) {
+    // Select the enclosing native dialog before showModal runs: default-open children
+    // render in the same commit, while its open attribute is still absent.
+    const modal = anchor.closest("dialog");
+    if (options.container &&
+        options.container.ownerDocument === anchor.ownerDocument &&
+        (!modal || modal.contains(options.container)))
+        return options.container;
+    return modal ?? anchor.ownerDocument.body;
+}
+/** DOM adapter: clean up observers and ignore obsolete asynchronous positioning results. */
+export default function useFloatingPanel(anchor, panel, open, { side = "bottom", align = "start", sideOffset = 8, collisionPadding = 8, container, }) {
+    useLayoutEffect(() => {
+        const reference = anchor.current, floating = panel.current;
+        const gap = Number.isFinite(sideOffset) ? sideOffset : 8;
+        const inset = Number.isFinite(collisionPadding)
+            ? Math.max(0, collisionPadding)
+            : 8;
+        if (!open || !reference || !floating)
+            return;
+        let disposed = false, revision = 0;
+        const properties = [
+            "position",
+            "left",
+            "right",
+            "top",
+            "bottom",
+            "transform",
+            "max-width",
+            "max-height",
+            "min-width",
+        ];
+        const previous = properties.map((name) => ({
+            name,
+            value: floating.style.getPropertyValue(name),
+            priority: floating.style.getPropertyPriority(name),
+        }));
+        const previousPlacement = floating.getAttribute("data-placement");
+        const view = reference.ownerDocument.defaultView;
+        const update = async () => {
+            const request = ++revision;
+            if (disposed || !floating.isConnected)
+                return;
+            floating.style.position = "fixed";
+            try {
+                const scale = await platform.getScale(floating);
+                const offsetParent = await platform.getOffsetParent(floating);
+                if (disposed || request !== revision)
+                    return;
+                // A window offset parent does not normalize inherited CSS zoom. Measure its
+                // rendered dimensions and convert viewport coordinates back to local CSS pixels.
+                const windowScaled = offsetParent === view && (scale.x !== 1 || scale.y !== 1);
+                const factorX = windowScaled ? scale.x : 1;
+                const factorY = windowScaled ? scale.y : 1;
+                const padding = {
+                    left: inset * factorX,
+                    right: inset * factorX,
+                    top: inset * factorY,
+                    bottom: inset * factorY,
+                };
+                const result = await computePosition(reference, floating, {
+                    strategy: "fixed",
+                    placement: align === "center" ? side : `${side}-${align}`,
+                    platform: windowScaled
+                        ? {
+                            ...platform,
+                            getDimensions(element) {
+                                if (element === floating) {
+                                    const rect = floating.getBoundingClientRect();
+                                    return { width: rect.width, height: rect.height };
+                                }
+                                return platform.getDimensions(element);
+                            },
+                        }
+                        : platform,
+                    middleware: [
+                        offset(gap * (side === "left" || side === "right" ? factorX : factorY)),
+                        flip({ padding }),
+                        shift({ padding, crossAxis: true }),
+                        size({
+                            padding,
+                            apply({ availableWidth, availableHeight }) {
+                                if (disposed || request !== revision)
+                                    return;
+                                const maximumWidth = Math.max(0, availableWidth / factorX);
+                                floating.style.maxWidth = `${maximumWidth}px`;
+                                floating.style.maxHeight = `${Math.max(0, availableHeight / factorY)}px`;
+                                // A CSS minimum must not defeat the viewport constraint at high zoom.
+                                const minimum = Number.parseFloat(view?.getComputedStyle(floating).minWidth ?? "0");
+                                if (Number.isFinite(minimum) && minimum > maximumWidth)
+                                    floating.style.minWidth = `${maximumWidth}px`;
+                            },
+                        }),
+                    ],
+                });
+                if (disposed || request !== revision)
+                    return;
+                Object.assign(floating.style, {
+                    position: "fixed",
+                    left: `${result.x / factorX}px`,
+                    top: `${result.y / factorY}px`,
+                    right: "auto",
+                    bottom: "auto",
+                    transform: "none",
+                });
+                floating.dataset.placement = result.placement;
+            }
+            catch (error) {
+                if (disposed || request !== revision)
+                    return;
+                // Preserve reachable content if the owner document cannot provide geometry.
+                Object.assign(floating.style, {
+                    position: "fixed",
+                    left: `${inset}px`,
+                    top: `${inset}px`,
+                    right: "auto",
+                    bottom: "auto",
+                    transform: "none",
+                });
+                floating.dataset.placement = "fallback";
+                console.warn("Contour floating positioning used its viewport fallback.", error);
+            }
+        };
+        const cleanup = autoUpdate(reference, floating, () => {
+            void update();
+        }, {
+            elementResize: typeof view?.ResizeObserver === "function",
+            layoutShift: typeof view?.IntersectionObserver === "function",
+        });
+        return () => {
+            disposed = true;
+            cleanup();
+            for (const { name, value, priority } of previous) {
+                if (value)
+                    floating.style.setProperty(name, value, priority);
+                else
+                    floating.style.removeProperty(name);
+            }
+            if (previousPlacement === null)
+                floating.removeAttribute("data-placement");
+            else
+                floating.setAttribute("data-placement", previousPlacement);
+        };
+    }, [
+        anchor,
+        panel,
+        open,
+        side,
+        align,
+        sideOffset,
+        collisionPadding,
+        container,
+    ]);
+}

package/dist/hooks/useLayerDismiss.d.ts

@@ -0,0 +1,4 @@
+import { type RefObject } from "react";
+import { type DismissReason } from "../lib/layers.js";
+import type { DismissOptions } from "./useDismiss.js";
+export default function useLayerDismiss(container: RefObject<HTMLElement | null>, active: boolean, onDismiss: (reason: DismissReason, event: KeyboardEvent | PointerEvent) => void, options?: DismissOptions): symbol;