@vireocodedev/ui 0.2.0 → 0.2.1

package/dist/capabilities/overlays/confirmation/components/overlays/VireoConfirmationDialog/VireoConfirmationDialog.styled.js

@@ -0,0 +1,28 @@
+import { Button, Dialog, DialogActions, DialogContent, } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_CONFIRMATION_DIALOG_NAME } from "./VireoConfirmationDialog.identity.js";
+export const VireoConfirmationDialogRoot = styled(Dialog, {
+    name: VIREO_CONFIRMATION_DIALOG_NAME,
+    slot: "Root",
+    overridesResolver: (_props, styles) => styles.root,
+})({});
+export const VireoConfirmationDialogContent = styled(DialogContent, {
+    name: VIREO_CONFIRMATION_DIALOG_NAME,
+    slot: "Content",
+    overridesResolver: (_props, styles) => styles.content,
+})(({ theme }) => ({ color: theme.palette.text.secondary, whiteSpace: "pre-line" }));
+export const VireoConfirmationDialogActions = styled(DialogActions, {
+    name: VIREO_CONFIRMATION_DIALOG_NAME,
+    slot: "Actions",
+    overridesResolver: (_props, styles) => styles.actions,
+})({});
+export const VireoConfirmationDialogCancelButton = styled(Button, {
+    name: VIREO_CONFIRMATION_DIALOG_NAME,
+    slot: "CancelButton",
+    overridesResolver: (_props, styles) => styles.cancelButton,
+})({});
+export const VireoConfirmationDialogConfirmButton = styled(Button, {
+    name: VIREO_CONFIRMATION_DIALOG_NAME,
+    slot: "ConfirmButton",
+    overridesResolver: (_props, styles) => styles.confirmButton,
+})({});

package/dist/capabilities/overlays/confirmation/components/overlays/VireoConfirmationDialog/VireoConfirmationDialog.types.d.ts

@@ -0,0 +1,67 @@
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../../core/public.js";
+import type { VireoOverlayHeader } from "../../../../../../capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.js";
+import type { Button, ButtonProps, Dialog, DialogActions, DialogContent, DialogProps } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import type { VireoConfirmationDialogClasses, VireoConfirmationDialogClassKey } from "./VireoConfirmationDialog.classes.js";
+import type { VIREO_CONFIRMATION_DIALOG_NAME, VireoConfirmationDialogSlotName } from "./VireoConfirmationDialog.identity.js";
+export type VireoConfirmationDialogOwnerState = {
+    open: boolean;
+    loading: boolean;
+    confirmColor: ButtonProps["color"];
+};
+export interface VireoConfirmationDialogRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoConfirmationDialogHeaderSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoConfirmationDialogContentSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoConfirmationDialogActionsSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoConfirmationDialogCancelButtonSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoConfirmationDialogConfirmButtonSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by {@link VireoConfirmationDialog}. */
+export type VireoConfirmationDialogSlots = {
+    [TSlotName in VireoConfirmationDialogSlotName]: React.ElementType;
+};
+/** Slot props exposed by {@link VireoConfirmationDialog}. */
+export type VireoConfirmationDialogSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoConfirmationDialogSlots, {
+    root: SlotProps<typeof Dialog, VireoConfirmationDialogRootSlotPropsOverrides, VireoConfirmationDialogOwnerState>;
+    header: SlotProps<typeof VireoOverlayHeader, VireoConfirmationDialogHeaderSlotPropsOverrides, VireoConfirmationDialogOwnerState>;
+    content: SlotProps<typeof DialogContent, VireoConfirmationDialogContentSlotPropsOverrides, VireoConfirmationDialogOwnerState>;
+    actions: SlotProps<typeof DialogActions, VireoConfirmationDialogActionsSlotPropsOverrides, VireoConfirmationDialogOwnerState>;
+    cancelButton: SlotProps<typeof Button, VireoConfirmationDialogCancelButtonSlotPropsOverrides, VireoConfirmationDialogOwnerState>;
+    confirmButton: SlotProps<typeof Button, VireoConfirmationDialogConfirmButtonSlotPropsOverrides, VireoConfirmationDialogOwnerState>;
+}>;
+/** Props owned by {@link VireoConfirmationDialog}. */
+export type VireoConfirmationDialogOwnProps = VireoConfirmationDialogSlotsAndSlotProps & {
+    open: boolean;
+    title: React.ReactNode;
+    message: React.ReactNode;
+    onClose: () => void;
+    onConfirm: () => void;
+    /** Called after the dialog's exit transition has fully completed. */
+    onExited?: () => void;
+    closeLabel?: string;
+    cancelLabel?: string;
+    confirmLabel?: string;
+    confirmColor?: ButtonProps["color"];
+    loading?: boolean;
+    classes?: Partial<VireoConfirmationDialogClasses>;
+};
+/** Props VireoConfirmationDialog inherits from MUI Dialog after excluding component-owned props. */
+export type VireoConfirmationDialogInheritedProps = Omit<DialogProps, "children" | "open" | "onClose" | "onTransitionExited" | "slots" | "slotProps" | "title">;
+export type VireoConfirmationDialogProps = VireoConfirmationDialogOwnProps & VireoConfirmationDialogInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_CONFIRMATION_DIALOG_NAME]?: VireoThemeComponent<VireoConfirmationDialogProps, VireoConfirmationDialogClassKey, VireoConfirmationDialogOwnerState, Theme>;
+    }
+}

package/dist/capabilities/overlays/confirmation/components/overlays/VireoConfirmationDialog/VireoConfirmationDialog.types.js

@@ -0,0 +1 @@
+export {};

package/dist/capabilities/overlays/confirmation/components/overlays/VireoConfirmationDialog/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./VireoConfirmationDialog.js";
+export * from "./VireoConfirmationDialog.classes.js";
+export * from "./VireoConfirmationDialog.types.js";

package/dist/capabilities/overlays/confirmation/components/overlays/VireoConfirmationDialog/index.js

@@ -0,0 +1,3 @@
+export * from "./VireoConfirmationDialog.js";
+export * from "./VireoConfirmationDialog.classes.js";
+export * from "./VireoConfirmationDialog.types.js";

package/dist/capabilities/overlays/confirmation/contexts/VireoConfirmationContext/VireoConfirmationContext.d.ts

@@ -0,0 +1,16 @@
+import type { ButtonProps, DialogProps } from "@mui/material";
+import React from "react";
+export type VireoConfirmationOptions = {
+    title: React.ReactNode;
+    message: React.ReactNode;
+    closeLabel?: string;
+    cancelLabel?: string;
+    confirmLabel?: string;
+    confirmColor?: ButtonProps["color"];
+    maxWidth?: DialogProps["maxWidth"];
+    /** Optional action executed while the confirmation remains open and locked. Rejection keeps it open for retry. */
+    onConfirm?: () => unknown | Promise<unknown>;
+};
+export type VireoConfirm = (options: VireoConfirmationOptions) => Promise<boolean>;
+/** Internal context consumed through useVireoConfirmation. */
+export declare const VireoConfirmationContext: React.Context<VireoConfirm | null>;

package/dist/capabilities/overlays/confirmation/contexts/VireoConfirmationContext/VireoConfirmationContext.js

@@ -0,0 +1,3 @@
+import React from "react";
+/** Internal context consumed through useVireoConfirmation. */
+export const VireoConfirmationContext = React.createContext(null);

package/dist/capabilities/overlays/confirmation/hooks/useVireoConfirmation/useVireoConfirmation.d.ts

@@ -0,0 +1,2 @@
+/** Opens the nearest shared confirmation dialog and resolves the user's decision. */
+export declare function useVireoConfirmation(): import("../../../../../capabilities/overlays/confirmation/contexts/VireoConfirmationContext/VireoConfirmationContext.js").VireoConfirm;

package/dist/capabilities/overlays/confirmation/hooks/useVireoConfirmation/useVireoConfirmation.js

@@ -0,0 +1,9 @@
+import { VireoConfirmationContext } from "../../../../../capabilities/overlays/confirmation/contexts/VireoConfirmationContext/VireoConfirmationContext.js";
+import React from "react";
+/** Opens the nearest shared confirmation dialog and resolves the user's decision. */
+export function useVireoConfirmation() {
+    const confirm = React.useContext(VireoConfirmationContext);
+    if (!confirm)
+        throw new Error("useVireoConfirmation must be used within VireoConfirmationProvider");
+    return confirm;
+}

package/dist/capabilities/overlays/confirmation/providers/VireoConfirmationProvider/VireoConfirmationProvider.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+export type VireoConfirmationProviderProps = {
+    children: React.ReactNode;
+    defaultCloseLabel?: string;
+    defaultCancelLabel?: string;
+    defaultConfirmLabel?: string;
+};
+/** Hosts one shared confirmation dialog and exposes a promise-based decision API to descendants. */
+export declare function VireoConfirmationProvider({ children, defaultCloseLabel, defaultCancelLabel, defaultConfirmLabel, }: VireoConfirmationProviderProps): React.JSX.Element;

package/dist/capabilities/overlays/confirmation/providers/VireoConfirmationProvider/VireoConfirmationProvider.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { VireoConfirmationDialog } from "../../../../../capabilities/overlays/confirmation/components/overlays/VireoConfirmationDialog/VireoConfirmationDialog.js";
+import { VireoConfirmationContext, } from "../../../../../capabilities/overlays/confirmation/contexts/VireoConfirmationContext/VireoConfirmationContext.js";
+import React from "react";
+/** Hosts one shared confirmation dialog and exposes a promise-based decision API to descendants. */
+export function VireoConfirmationProvider({ children, defaultCloseLabel = "Close", defaultCancelLabel = "Cancel", defaultConfirmLabel = "Confirm", }) {
+    const [active, setActive] = React.useState(null);
+    const [loading, setLoading] = React.useState(false);
+    const [open, setOpen] = React.useState(false);
+    const activeRef = React.useRef(null);
+    const settle = React.useCallback((confirmed) => {
+        const current = activeRef.current;
+        if (!current)
+            return;
+        activeRef.current = null;
+        setLoading(false);
+        setOpen(false);
+        current.resolve(confirmed);
+    }, []);
+    const handleExited = React.useCallback(() => {
+        if (activeRef.current == null)
+            setActive(null);
+    }, []);
+    const confirm = React.useCallback(options => {
+        activeRef.current?.resolve(false);
+        setLoading(false);
+        return new Promise(resolve => {
+            const next = { options, resolve };
+            activeRef.current = next;
+            setActive(next);
+            setOpen(true);
+        });
+    }, []);
+    const handleConfirm = React.useCallback(async () => {
+        const current = activeRef.current;
+        if (!current)
+            return;
+        if (!current.options.onConfirm) {
+            settle(true);
+            return;
+        }
+        setLoading(true);
+        try {
+            await current.options.onConfirm();
+            if (activeRef.current === current)
+                settle(true);
+        }
+        catch {
+            if (activeRef.current === current)
+                setLoading(false);
+        }
+    }, [settle]);
+    React.useEffect(() => () => activeRef.current?.resolve(false), []);
+    return (_jsxs(VireoConfirmationContext.Provider, { value: confirm, children: [children, _jsx(VireoConfirmationDialog, { open: open, title: active?.options.title ?? "", message: active?.options.message ?? "", closeLabel: active?.options.closeLabel ?? defaultCloseLabel, cancelLabel: active?.options.cancelLabel ?? defaultCancelLabel, confirmLabel: active?.options.confirmLabel ?? defaultConfirmLabel, confirmColor: active?.options.confirmColor, loading: loading, maxWidth: active?.options.maxWidth, onClose: () => settle(false), onConfirm: () => void handleConfirm(), onExited: handleExited })] }));
+}

package/dist/capabilities/overlays/constants/overlay.constants.d.ts

@@ -0,0 +1,16 @@
+import { type DialogProps } from "@mui/material";
+export declare const DEFAULT_DESKTOP_SIDE_PANEL_MIN_WIDTH = 360;
+export declare const DEFAULT_DESKTOP_SIDE_PANEL_MIN_CONTENT_WIDTH = 420;
+export declare const DEFAULT_DESKTOP_SIDE_PANEL_VIEWPORT_INSET = 48;
+export declare const DOCKED_SIDE_PANEL_TRANSITION_MS: 180;
+export declare const SIDE_PANEL_WIDTH_CSS_VAR = "--responsive-overlay-side-panel-width";
+export declare const DOCKED_SIDE_PANEL_TRANSITION_EVENT = "responsive-overlay:docked-side-panel-transition";
+export declare const SIDE_PANEL_RESIZE_HANDLE_WIDTH = 6;
+export declare const SIDE_PANEL_RESIZE_HITBOX_WIDTH = 14;
+export declare const SIDE_PANEL_RESIZE_HOVER_OPACITY = 0.35;
+export declare const SIDE_PANEL_RESIZE_ACTIVE_OPACITY = 0.7;
+export declare const SIDE_PANEL_RESIZE_KEYBOARD_STEP = 16;
+export type DockedSidePanelTransitionEventDetail = {
+    animating: boolean;
+};
+export declare const DESKTOP_SIDE_PANEL_WIDTH_BY_MAX_WIDTH: Record<Exclude<DialogProps["maxWidth"], undefined | false>, number>;

package/dist/capabilities/overlays/constants/overlay.constants.js

@@ -0,0 +1,19 @@
+import { VIREO_MOTION_TOKENS } from "../../../core/public.js";
+export const DEFAULT_DESKTOP_SIDE_PANEL_MIN_WIDTH = 360;
+export const DEFAULT_DESKTOP_SIDE_PANEL_MIN_CONTENT_WIDTH = 420;
+export const DEFAULT_DESKTOP_SIDE_PANEL_VIEWPORT_INSET = 48;
+export const DOCKED_SIDE_PANEL_TRANSITION_MS = VIREO_MOTION_TOKENS.duration.standard;
+export const SIDE_PANEL_WIDTH_CSS_VAR = "--responsive-overlay-side-panel-width";
+export const DOCKED_SIDE_PANEL_TRANSITION_EVENT = "responsive-overlay:docked-side-panel-transition";
+export const SIDE_PANEL_RESIZE_HANDLE_WIDTH = 6;
+export const SIDE_PANEL_RESIZE_HITBOX_WIDTH = 14;
+export const SIDE_PANEL_RESIZE_HOVER_OPACITY = 0.35;
+export const SIDE_PANEL_RESIZE_ACTIVE_OPACITY = 0.7;
+export const SIDE_PANEL_RESIZE_KEYBOARD_STEP = 16;
+export const DESKTOP_SIDE_PANEL_WIDTH_BY_MAX_WIDTH = {
+    xs: 360,
+    sm: 480,
+    md: 560,
+    lg: 760,
+    xl: 960,
+};

package/dist/capabilities/overlays/hooks/useRafViewportWidth/useRafViewportWidth.d.ts

@@ -0,0 +1,2 @@
+/** Tracks viewport width at most once per animation frame while enabled. */
+export declare function useRafViewportWidth(enabled: boolean): number;

package/dist/capabilities/overlays/hooks/useRafViewportWidth/useRafViewportWidth.js

@@ -0,0 +1,32 @@
+import React from "react";
+/** Tracks viewport width at most once per animation frame while enabled. */
+export function useRafViewportWidth(enabled) {
+    const [viewportWidth, setViewportWidth] = React.useState(() => typeof window === "undefined" ? 0 : window.innerWidth);
+    const rafRef = React.useRef(null);
+    React.useEffect(() => {
+        if (!enabled || typeof window === "undefined") {
+            return;
+        }
+        const onResize = () => {
+            if (rafRef.current !== null) {
+                return;
+            }
+            rafRef.current = window.requestAnimationFrame(() => {
+                rafRef.current = null;
+                setViewportWidth(previousWidth => {
+                    const nextWidth = window.innerWidth;
+                    return previousWidth === nextWidth ? previousWidth : nextWidth;
+                });
+            });
+        };
+        window.addEventListener("resize", onResize);
+        return () => {
+            window.removeEventListener("resize", onResize);
+            if (rafRef.current !== null) {
+                window.cancelAnimationFrame(rafRef.current);
+                rafRef.current = null;
+            }
+        };
+    }, [enabled]);
+    return viewportWidth;
+}

package/dist/capabilities/overlays/hooks/useSidePanelResize/useSidePanelResize.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+export declare function useSidePanelResize({ enabled, initialWidth, minWidth, maxWidth, }: {
+    enabled: boolean;
+    initialWidth: number;
+    minWidth: number;
+    maxWidth: number;
+}): {
+    isResizing: boolean;
+    onResizeDoubleClick: (event: React.MouseEvent<HTMLDivElement>) => void;
+    onResizeKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+    onResizeStart: (event: React.MouseEvent<HTMLDivElement>) => void;
+    rootRef: (element: HTMLDivElement | null) => void;
+    width: number;
+};

package/dist/capabilities/overlays/hooks/useSidePanelResize/useSidePanelResize.js

@@ -0,0 +1,137 @@
+import { SIDE_PANEL_RESIZE_KEYBOARD_STEP, SIDE_PANEL_WIDTH_CSS_VAR, } from "../../../../capabilities/overlays/constants/overlay.constants.js";
+import { clampSidePanelWidth } from "../../../../capabilities/overlays/utils/overlay.utils.js";
+import React from "react";
+export function useSidePanelResize({ enabled, initialWidth, minWidth, maxWidth, }) {
+    const [width, setWidth] = React.useState(() => clampSidePanelWidth(initialWidth, minWidth, maxWidth));
+    const [isResizing, setIsResizing] = React.useState(false);
+    const rootRef = React.useRef(null);
+    const widthRef = React.useRef(width);
+    const initialWidthRef = React.useRef(initialWidth);
+    const minWidthRef = React.useRef(minWidth);
+    const maxWidthRef = React.useRef(maxWidth);
+    const hasUserResizedRef = React.useRef(false);
+    const resizeRafRef = React.useRef(null);
+    const pendingWidthRef = React.useRef(null);
+    const cleanupResizeRef = React.useRef(null);
+    const setCssWidth = React.useCallback((nextWidth) => {
+        rootRef.current?.style.setProperty(SIDE_PANEL_WIDTH_CSS_VAR, `${nextWidth}px`);
+    }, []);
+    const setRootElement = React.useCallback((element) => {
+        rootRef.current = element;
+        if (element) {
+            element.style.setProperty(SIDE_PANEL_WIDTH_CSS_VAR, `${widthRef.current}px`);
+        }
+    }, []);
+    React.useEffect(() => {
+        initialWidthRef.current = initialWidth;
+        minWidthRef.current = minWidth;
+        maxWidthRef.current = maxWidth;
+        const nextWidth = clampSidePanelWidth(hasUserResizedRef.current ? widthRef.current : initialWidth, minWidth, maxWidth);
+        if (nextWidth !== widthRef.current) {
+            widthRef.current = nextWidth;
+            setWidth(nextWidth);
+        }
+        setCssWidth(nextWidth);
+    }, [initialWidth, maxWidth, minWidth, setCssWidth]);
+    React.useEffect(() => {
+        return () => {
+            cleanupResizeRef.current?.();
+            if (resizeRafRef.current !== null && typeof window !== "undefined") {
+                window.cancelAnimationFrame(resizeRafRef.current);
+                resizeRafRef.current = null;
+            }
+        };
+    }, []);
+    const commitWidth = React.useCallback((candidate, userResized = true) => {
+        const nextWidth = clampSidePanelWidth(candidate, minWidthRef.current, maxWidthRef.current);
+        pendingWidthRef.current = null;
+        widthRef.current = nextWidth;
+        hasUserResizedRef.current = userResized;
+        setCssWidth(nextWidth);
+        setWidth(nextWidth);
+    }, [setCssWidth]);
+    const onResizeStart = React.useCallback((event) => {
+        if (!enabled || typeof window === "undefined") {
+            return;
+        }
+        if (event.detail > 1) {
+            return;
+        }
+        event.preventDefault();
+        const startX = event.clientX;
+        const startWidth = widthRef.current;
+        const previousBodyCursor = document.body.style.cursor;
+        const previousBodyUserSelect = document.body.style.userSelect;
+        document.body.style.cursor = "col-resize";
+        document.body.style.userSelect = "none";
+        pendingWidthRef.current = null;
+        setIsResizing(true);
+        const syncPendingWidth = () => {
+            resizeRafRef.current = null;
+            if (pendingWidthRef.current === null) {
+                return;
+            }
+            widthRef.current = pendingWidthRef.current;
+            setCssWidth(pendingWidthRef.current);
+        };
+        cleanupResizeRef.current?.();
+        const onPointerMove = (moveEvent) => {
+            const nextWidth = clampSidePanelWidth(startWidth - (moveEvent.clientX - startX), minWidthRef.current, maxWidthRef.current);
+            pendingWidthRef.current = nextWidth;
+            if (resizeRafRef.current === null) {
+                resizeRafRef.current = window.requestAnimationFrame(syncPendingWidth);
+            }
+        };
+        const finishResize = () => {
+            setIsResizing(false);
+            document.body.style.cursor = previousBodyCursor;
+            document.body.style.userSelect = previousBodyUserSelect;
+            if (resizeRafRef.current !== null) {
+                window.cancelAnimationFrame(resizeRafRef.current);
+                resizeRafRef.current = null;
+            }
+            commitWidth(pendingWidthRef.current ?? widthRef.current);
+            window.removeEventListener("pointermove", onPointerMove);
+            window.removeEventListener("pointerup", finishResize);
+            window.removeEventListener("pointercancel", finishResize);
+            cleanupResizeRef.current = null;
+        };
+        cleanupResizeRef.current = finishResize;
+        window.addEventListener("pointermove", onPointerMove);
+        window.addEventListener("pointerup", finishResize);
+        window.addEventListener("pointercancel", finishResize);
+    }, [commitWidth, enabled, setCssWidth]);
+    const onResizeDoubleClick = React.useCallback((event) => {
+        if (!enabled) {
+            return;
+        }
+        event.preventDefault();
+        commitWidth(initialWidthRef.current, false);
+    }, [commitWidth, enabled]);
+    const onResizeKeyDown = React.useCallback((event) => {
+        if (!enabled)
+            return;
+        const step = event.shiftKey ? SIDE_PANEL_RESIZE_KEYBOARD_STEP * 2 : SIDE_PANEL_RESIZE_KEYBOARD_STEP;
+        const nextWidth = event.key === "ArrowLeft"
+            ? widthRef.current + step
+            : event.key === "ArrowRight"
+                ? widthRef.current - step
+                : event.key === "Home"
+                    ? minWidthRef.current
+                    : event.key === "End"
+                        ? maxWidthRef.current
+                        : null;
+        if (nextWidth === null)
+            return;
+        event.preventDefault();
+        commitWidth(nextWidth);
+    }, [commitWidth, enabled]);
+    return {
+        isResizing,
+        onResizeDoubleClick,
+        onResizeKeyDown,
+        onResizeStart,
+        rootRef: setRootElement,
+        width,
+    };
+}

package/dist/capabilities/overlays/page-overlays/contexts/PageOverlayControllerContext/PageOverlayControllerContext.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+export type PageOverlayControllerValue = {
+    hostElement: HTMLElement | null;
+    setHostElement: (element: HTMLElement | null) => void;
+    register: (key: string, requestClose: () => void) => void;
+    unregister: (key: string) => void;
+    requestExclusive: (key: string) => void;
+};
+export declare const PageOverlayControllerContext: React.Context<PageOverlayControllerValue | null>;
+export declare function usePageOverlayController(): PageOverlayControllerValue;

package/dist/capabilities/overlays/page-overlays/contexts/PageOverlayControllerContext/PageOverlayControllerContext.js

@@ -0,0 +1,9 @@
+import React from "react";
+export const PageOverlayControllerContext = React.createContext(null);
+export function usePageOverlayController() {
+    const controller = React.useContext(PageOverlayControllerContext);
+    if (!controller) {
+        throw new Error("usePageOverlayController must be used within PageOverlayControllerProvider");
+    }
+    return controller;
+}

package/dist/capabilities/overlays/page-overlays/hooks/useDelayedOverlayMount/useDelayedOverlayMount.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+export type DelayedOverlayRenderProps = {
+    open: boolean;
+    onClose: () => void;
+    onExited: () => void;
+};
+export type UseDelayedOverlayMountReturn = {
+    mounted: boolean;
+    open: boolean;
+    openOverlay: () => void;
+    closeOverlay: () => void;
+    onExited: () => void;
+    render: (children: (props: DelayedOverlayRenderProps) => React.ReactNode) => React.ReactNode;
+};
+export declare function useDelayedOverlayMount(): UseDelayedOverlayMountReturn;

package/dist/capabilities/overlays/page-overlays/hooks/useDelayedOverlayMount/useDelayedOverlayMount.js

@@ -0,0 +1,41 @@
+import React from "react";
+export function useDelayedOverlayMount() {
+    const [mounted, setMounted] = React.useState(false);
+    const [open, setOpen] = React.useState(false);
+    const openRef = React.useRef(open);
+    React.useEffect(() => {
+        openRef.current = open;
+    }, [open]);
+    const openOverlay = React.useCallback(() => {
+        openRef.current = true;
+        setMounted(true);
+        setOpen(true);
+    }, []);
+    const closeOverlay = React.useCallback(() => {
+        openRef.current = false;
+        setOpen(false);
+    }, []);
+    const onExited = React.useCallback(() => {
+        if (!openRef.current) {
+            setMounted(false);
+        }
+    }, []);
+    const render = React.useCallback((children) => {
+        if (!mounted) {
+            return null;
+        }
+        return children({
+            open,
+            onClose: closeOverlay,
+            onExited,
+        });
+    }, [closeOverlay, mounted, onExited, open]);
+    return React.useMemo(() => ({
+        mounted,
+        open,
+        openOverlay,
+        closeOverlay,
+        onExited,
+        render,
+    }), [mounted, open, openOverlay, closeOverlay, onExited, render]);
+}

package/dist/capabilities/overlays/page-overlays/hooks/useGuardedOverlayModeSwitch/useGuardedOverlayModeSwitch.d.ts

@@ -0,0 +1,2 @@
+export type GuardedOverlayModeSwitch<TPayloadByMode extends Record<string, unknown>> = <TMode extends keyof TPayloadByMode>(mode: TMode, payload: TPayloadByMode[TMode], beforeOpen?: () => void) => void;
+export declare function useGuardedOverlayModeSwitch<TPayloadByMode extends Record<string, unknown>>(overlayOpen: boolean, openMode: (mode: keyof TPayloadByMode, payload: TPayloadByMode[keyof TPayloadByMode]) => void): GuardedOverlayModeSwitch<TPayloadByMode>;

package/dist/capabilities/overlays/page-overlays/hooks/useGuardedOverlayModeSwitch/useGuardedOverlayModeSwitch.js

@@ -0,0 +1,22 @@
+import { useUnsavedChanges } from "../../../../../capabilities/unsaved-changes/public.js";
+import React from "react";
+export function useGuardedOverlayModeSwitch(overlayOpen, openMode) {
+    const { requestDiscard } = useUnsavedChanges();
+    const openModeRef = React.useRef(openMode);
+    const overlayOpenRef = React.useRef(overlayOpen);
+    const requestDiscardRef = React.useRef(requestDiscard);
+    openModeRef.current = openMode;
+    overlayOpenRef.current = overlayOpen;
+    requestDiscardRef.current = requestDiscard;
+    return React.useCallback(((mode, payload, beforeOpen) => {
+        const commitOpen = () => {
+            beforeOpen?.();
+            openModeRef.current(mode, payload);
+        };
+        if (!overlayOpenRef.current) {
+            commitOpen();
+            return;
+        }
+        requestDiscardRef.current({ onDiscard: commitOpen });
+    }), []);
+}

package/dist/capabilities/overlays/page-overlays/hooks/usePageOverlayModes/usePageOverlayModes.d.ts

@@ -0,0 +1,28 @@
+import { type DelayedOverlayRenderProps } from "../../../../../capabilities/overlays/page-overlays/hooks/useDelayedOverlayMount/useDelayedOverlayMount.js";
+import React from "react";
+export type OverlayPayloadMap = Record<string, unknown>;
+export type OverlayState<TMap extends OverlayPayloadMap> = {
+    mode: "none";
+} | {
+    [K in keyof TMap]: {
+        mode: K;
+        payload: TMap[K];
+    };
+}[keyof TMap];
+export type OverlayRendererProps = DelayedOverlayRenderProps & {
+    onExited: () => void;
+};
+export type OverlayRenderers<TMap extends OverlayPayloadMap> = {
+    [K in keyof TMap]: (props: OverlayRendererProps, payload: TMap[K]) => React.ReactElement | null;
+};
+export type UsePageOverlayModesReturn<TMap extends OverlayPayloadMap> = {
+    overlay: {
+        open: boolean;
+        render: () => React.ReactNode;
+    };
+    state: OverlayState<TMap>;
+    open: <K extends keyof TMap>(mode: K, payload: TMap[K]) => void;
+    close: () => void;
+    onExited: () => void;
+};
+export declare function usePageOverlayModes<TMap extends OverlayPayloadMap>(renderers: OverlayRenderers<TMap>): UsePageOverlayModesReturn<TMap>;

package/dist/capabilities/overlays/page-overlays/hooks/usePageOverlayModes/usePageOverlayModes.js

@@ -0,0 +1,39 @@
+import { useDelayedOverlayMount, } from "../../../../../capabilities/overlays/page-overlays/hooks/useDelayedOverlayMount/useDelayedOverlayMount.js";
+import React from "react";
+export function usePageOverlayModes(renderers) {
+    const { closeOverlay, onExited: onOverlayExited, open: overlayOpen, openOverlay, render: renderMountedOverlay, } = useDelayedOverlayMount();
+    const [state, setState] = React.useState({ mode: "none" });
+    const open = React.useCallback((mode, payload) => {
+        setState({ mode, payload });
+        openOverlay();
+    }, [openOverlay]);
+    const close = React.useCallback(() => {
+        closeOverlay();
+    }, [closeOverlay]);
+    const onExited = React.useCallback(() => {
+        setState({ mode: "none" });
+        onOverlayExited();
+    }, [onOverlayExited]);
+    const render = React.useCallback(() => renderMountedOverlay((overlayProps) => {
+        if (!("payload" in state)) {
+            return null;
+        }
+        const mode = state.mode;
+        const renderer = renderers[mode];
+        return renderer({
+            ...overlayProps,
+            onExited,
+        }, state.payload);
+    }), [onExited, renderMountedOverlay, renderers, state]);
+    const overlay = React.useMemo(() => ({
+        open: overlayOpen,
+        render,
+    }), [overlayOpen, render]);
+    return React.useMemo(() => ({
+        overlay,
+        state,
+        open,
+        close,
+        onExited,
+    }), [overlay, state, open, close, onExited]);
+}

package/dist/capabilities/overlays/page-overlays/providers/PageOverlayControllerProvider/PageOverlayControllerProvider.d.ts

@@ -0,0 +1,23 @@
+import React from "react";
+/**
+ * App-level controller for page overlays. Overlays register here and portal
+ * their content into a single shared outlet, so the create/update form and the
+ * history overlay render from the same place. Opening any overlay closes the
+ * others (mutual exclusion), while each overlay keeps its own mount lifecycle so
+ * open/close transitions animate normally.
+ */
+export declare function PageOverlayControllerProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+export type PageOverlayProps = {
+    overlayKey?: string;
+    open: boolean;
+    onRequestClose: () => void;
+    render: React.ReactNode | (() => React.ReactNode);
+};
+/**
+ * Registers a single overlay with the controller and portals its content into
+ * the shared outlet. Pass a falsy {@link render} while the overlay is unmounted.
+ */
+export declare function PageOverlay({ overlayKey, open, onRequestClose, render }: PageOverlayProps): React.ReactPortal | null;
+export declare function PageOverlayOutlet(): React.JSX.Element;