@vireocodedev/ui 0.2.0 → 0.2.1

package/dist/capabilities/overlays/components/overlays/VireoDockedSidePanel/VireoDockedSidePanel.js

@@ -0,0 +1,169 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { joinClassNames, mergeSx, resolveSlotProps } from "../../../../../core/public.js";
+import { DOCKED_SIDE_PANEL_TRANSITION_EVENT, DOCKED_SIDE_PANEL_TRANSITION_MS, } from "../../../../../capabilities/overlays/constants/overlay.constants.js";
+import { unstable_composeClasses as composeClasses } from "@mui/material";
+import { useThemeProps } from "@mui/material/styles";
+import { useForkRef } from "@mui/material/utils";
+import React from "react";
+import { getVireoDockedSidePanelUtilityClass } from "./VireoDockedSidePanel.classes.js";
+import { VIREO_DOCKED_SIDE_PANEL_NAME } from "./VireoDockedSidePanel.identity.js";
+import { VireoDockedSidePanelRoot, VireoDockedSidePanelSurface } from "./VireoDockedSidePanel.styled.js";
+function useUtilityClasses(_ownerState, classes) {
+    return composeClasses({
+        root: ["root"],
+        surface: ["surface"],
+    }, getVireoDockedSidePanelUtilityClass, classes);
+}
+/**
+ * Renders an adjacent side-panel surface with coordinated enter and exit transitions.
+ */
+export const VireoDockedSidePanel = React.forwardRef(function VireoDockedSidePanel(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_DOCKED_SIDE_PANEL_NAME });
+    const { children, className, classes: classesProp, isResizing = false, maxWidth, minWidth, onExited, open, resizeHandle, slotProps = {}, slots = {}, style, sx, width, ...other } = props;
+    const [isPanelPresent, setIsPanelPresent] = React.useState(open);
+    const [isPanelEntered, setIsPanelEntered] = React.useState(false);
+    const previousOpenRef = React.useRef(false);
+    const exitedRef = React.useRef(false);
+    const exitTimerRef = React.useRef(null);
+    const transitionTimerRef = React.useRef(null);
+    const transitionRafRef = React.useRef(null);
+    const isTransitioningRef = React.useRef(false);
+    const onExitedRef = React.useRef(onExited);
+    React.useEffect(() => {
+        onExitedRef.current = onExited;
+    }, [onExited]);
+    const clearExitTimer = React.useCallback(() => {
+        if (exitTimerRef.current === null || typeof window === "undefined")
+            return;
+        window.clearTimeout(exitTimerRef.current);
+        exitTimerRef.current = null;
+    }, []);
+    const clearTransitionTimer = React.useCallback(() => {
+        if (transitionTimerRef.current === null || typeof window === "undefined")
+            return;
+        window.clearTimeout(transitionTimerRef.current);
+        transitionTimerRef.current = null;
+    }, []);
+    const clearTransitionRaf = React.useCallback(() => {
+        if (transitionRafRef.current === null || typeof window === "undefined")
+            return;
+        window.cancelAnimationFrame(transitionRafRef.current);
+        transitionRafRef.current = null;
+    }, []);
+    const emitTransitionState = React.useCallback((animating) => {
+        if (typeof window === "undefined" || animating === isTransitioningRef.current)
+            return;
+        isTransitioningRef.current = animating;
+        window.dispatchEvent(new CustomEvent(DOCKED_SIDE_PANEL_TRANSITION_EVENT, {
+            detail: { animating },
+        }));
+    }, []);
+    const endTransition = React.useCallback(() => {
+        clearTransitionTimer();
+        emitTransitionState(false);
+    }, [clearTransitionTimer, emitTransitionState]);
+    const beginTransition = React.useCallback(() => {
+        if (typeof window === "undefined")
+            return;
+        clearTransitionTimer();
+        emitTransitionState(true);
+        transitionTimerRef.current = window.setTimeout(endTransition, DOCKED_SIDE_PANEL_TRANSITION_MS + 80);
+    }, [clearTransitionTimer, emitTransitionState, endTransition]);
+    const emitExited = React.useCallback(() => {
+        if (exitedRef.current)
+            return;
+        exitedRef.current = true;
+        clearExitTimer();
+        onExitedRef.current?.();
+    }, [clearExitTimer]);
+    const finalizeClose = React.useCallback(() => {
+        if (open)
+            return;
+        setIsPanelPresent(false);
+        emitExited();
+        endTransition();
+    }, [emitExited, endTransition, open]);
+    React.useEffect(() => {
+        const wasOpen = previousOpenRef.current;
+        previousOpenRef.current = open;
+        if (open) {
+            exitedRef.current = false;
+            clearExitTimer();
+            setIsPanelPresent(true);
+            if (!wasOpen) {
+                beginTransition();
+                clearTransitionRaf();
+                if (typeof window === "undefined") {
+                    setIsPanelEntered(true);
+                }
+                else {
+                    transitionRafRef.current = window.requestAnimationFrame(() => {
+                        transitionRafRef.current = null;
+                        setIsPanelEntered(true);
+                    });
+                }
+            }
+            return;
+        }
+        clearTransitionRaf();
+        if (!wasOpen || typeof window === "undefined") {
+            setIsPanelEntered(false);
+            setIsPanelPresent(false);
+            return;
+        }
+        exitedRef.current = false;
+        beginTransition();
+        setIsPanelEntered(false);
+        exitTimerRef.current = window.setTimeout(finalizeClose, DOCKED_SIDE_PANEL_TRANSITION_MS + 80);
+        return () => {
+            clearExitTimer();
+            clearTransitionRaf();
+        };
+    }, [beginTransition, clearExitTimer, clearTransitionRaf, finalizeClose, open]);
+    React.useEffect(() => () => {
+        previousOpenRef.current = false;
+        clearExitTimer();
+        clearTransitionTimer();
+        clearTransitionRaf();
+        emitTransitionState(false);
+    }, [clearExitTimer, clearTransitionRaf, clearTransitionTimer, emitTransitionState]);
+    const ownerState = {
+        open,
+        width,
+        minWidth,
+        maxWidth,
+        isResizing,
+        isPanelPresent,
+        isPanelEntered,
+    };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const resolvedSurfaceSlotProps = resolveSlotProps(slotProps.surface, ownerState);
+    const { className: rootSlotClassName, ref: rootSlotRef, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef);
+    const { className: surfaceSlotClassName, onTransitionEnd: surfaceSlotOnTransitionEnd, sx: surfaceSlotSx, ...surfaceSlotOther } = resolvedSurfaceSlotProps;
+    const rootSizingSx = {
+        width: ownerState.isPanelPresent ? ownerState.width : 0,
+        minWidth: ownerState.isPanelPresent ? ownerState.minWidth : 0,
+        maxWidth: ownerState.maxWidth,
+    };
+    const surfaceSizingSx = {
+        width: ownerState.width,
+        minWidth: ownerState.minWidth,
+        maxWidth: ownerState.maxWidth,
+    };
+    const handleTransitionEnd = React.useCallback(event => {
+        surfaceSlotOnTransitionEnd?.(event);
+        if (event.defaultPrevented ||
+            event.target !== event.currentTarget ||
+            !["transform", "opacity"].includes(event.propertyName)) {
+            return;
+        }
+        if (open)
+            endTransition();
+        else
+            finalizeClose();
+    }, [endTransition, finalizeClose, open, surfaceSlotOnTransitionEnd]);
+    return (_jsx(VireoDockedSidePanelRoot, { ...other, ...rootSlotOther, as: slots.root ?? "div", ref: rootRef, ownerState: ownerState, className: joinClassNames(classes.root, className, rootSlotClassName), style: { ...style, ...rootSlotStyle }, sx: mergeSx(rootSizingSx, mergeSx(sx, rootSlotSx)), "aria-hidden": !isPanelPresent, children: _jsxs(VireoDockedSidePanelSurface, { ...surfaceSlotOther, as: slots.surface ?? "aside", ownerState: ownerState, className: joinClassNames(classes.surface, surfaceSlotClassName), onTransitionEnd: handleTransitionEnd, sx: mergeSx(surfaceSizingSx, surfaceSlotSx), children: [resizeHandle, children] }) }));
+});
+VireoDockedSidePanel.displayName = VIREO_DOCKED_SIDE_PANEL_NAME;

package/dist/capabilities/overlays/components/overlays/VireoDockedSidePanel/VireoDockedSidePanel.styled.d.ts

@@ -0,0 +1,7 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type BoxProps } from "@mui/material";
+import { type VireoDockedSidePanelOwnerState } from "./VireoDockedSidePanel.types.js";
+type VireoDockedSidePanelStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoDockedSidePanelOwnerState>;
+export declare const VireoDockedSidePanelRoot: VireoDockedSidePanelStyledSlotComponent<BoxProps>;
+export declare const VireoDockedSidePanelSurface: VireoDockedSidePanelStyledSlotComponent<BoxProps>;
+export {};

package/dist/capabilities/overlays/components/overlays/VireoDockedSidePanel/VireoDockedSidePanel.styled.js

@@ -0,0 +1,46 @@
+import { VIREO_MOTION_TOKENS } from "../../../../../core/public.js";
+import { DOCKED_SIDE_PANEL_TRANSITION_MS } from "../../../../../capabilities/overlays/constants/overlay.constants.js";
+import { Box } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_DOCKED_SIDE_PANEL_NAME } from "./VireoDockedSidePanel.identity.js";
+export const VireoDockedSidePanelRoot = styled(Box, {
+    name: VIREO_DOCKED_SIDE_PANEL_NAME,
+    slot: "Root",
+    overridesResolver: (_props, styles) => styles.root,
+})(({ ownerState }) => ({
+    flex: "0 0 auto",
+    height: "100%",
+    minHeight: 0,
+    overflow: "hidden",
+    pointerEvents: ownerState.open ? "auto" : "none",
+    contain: "layout paint",
+}));
+export const VireoDockedSidePanelSurface = styled(Box, {
+    name: VIREO_DOCKED_SIDE_PANEL_NAME,
+    slot: "Surface",
+    overridesResolver: (_props, styles) => styles.surface,
+})(({ ownerState, theme }) => ({
+    position: "relative",
+    height: "100%",
+    minHeight: 0,
+    display: "flex",
+    flexDirection: "column",
+    overflow: "hidden",
+    backgroundColor: theme.palette.background.paper,
+    borderLeft: `1px solid ${theme.palette.divider}`,
+    transform: ownerState.isPanelEntered ? "translateX(0)" : `translateX(${VIREO_MOTION_TOKENS.distance.surface}px)`,
+    opacity: ownerState.isPanelEntered ? 1 : 0,
+    transition: ownerState.isResizing
+        ? "none"
+        : theme.transitions.create(["transform", "opacity"], {
+            duration: DOCKED_SIDE_PANEL_TRANSITION_MS,
+            easing: VIREO_MOTION_TOKENS.easing.standard,
+        }),
+    willChange: ownerState.isResizing ? "auto" : "transform, opacity",
+    backfaceVisibility: "hidden",
+    "@media (prefers-reduced-motion: reduce)": {
+        transform: "none",
+        transitionDuration: "0ms",
+        willChange: "auto",
+    },
+}));

package/dist/capabilities/overlays/components/overlays/VireoDockedSidePanel/VireoDockedSidePanel.types.d.ts

@@ -0,0 +1,63 @@
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { ResponsiveOverlayFrameDesktopSidePanelWidth } from "../../../../../capabilities/overlays/types/overlay.types.js";
+import type { BoxProps } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoDockedSidePanelClasses, type VireoDockedSidePanelClassKey } from "./VireoDockedSidePanel.classes.js";
+import type { VIREO_DOCKED_SIDE_PANEL_NAME, VireoDockedSidePanelSlotName } from "./VireoDockedSidePanel.identity.js";
+export type VireoDockedSidePanelOwnerState = {
+    open: boolean;
+    width: ResponsiveOverlayFrameDesktopSidePanelWidth;
+    minWidth: number;
+    maxWidth: number;
+    isResizing: boolean;
+    isPanelPresent: boolean;
+    isPanelEntered: boolean;
+};
+export interface VireoDockedSidePanelRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoDockedSidePanelSurfaceSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by {@link VireoDockedSidePanel}. */
+export type VireoDockedSidePanelSlots = {
+    [TSlotName in VireoDockedSidePanelSlotName]: React.ElementType;
+};
+/** Slot props exposed by {@link VireoDockedSidePanel}. */
+export type VireoDockedSidePanelSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoDockedSidePanelSlots, {
+    /** @default 'div' */
+    root: SlotProps<"div", VireoDockedSidePanelRootSlotPropsOverrides, VireoDockedSidePanelOwnerState>;
+    /** @default 'aside' */
+    surface: SlotProps<"aside", VireoDockedSidePanelSurfaceSlotPropsOverrides, VireoDockedSidePanelOwnerState>;
+}>;
+/** Props owned by {@link VireoDockedSidePanel}. */
+export type VireoDockedSidePanelOwnProps = VireoDockedSidePanelSlotsAndSlotProps & {
+    /** Whether the panel is entered and interactive. */
+    open: boolean;
+    /** Width reserved for the visible panel surface. */
+    width: ResponsiveOverlayFrameDesktopSidePanelWidth;
+    /** Minimum visible panel width in pixels. */
+    minWidth: number;
+    /** Maximum visible panel width in pixels. */
+    maxWidth: number;
+    /** Disables surface transitions while pointer resizing is active. @default false */
+    isResizing?: boolean;
+    /** Optional resize control rendered before panel content. */
+    resizeHandle?: React.ReactNode;
+    /** Called once after the panel finishes leaving. */
+    onExited?: () => void;
+    /** Panel contents. */
+    children: React.ReactNode;
+    /** Override or extend the utility classes applied to each slot. */
+    classes?: Partial<VireoDockedSidePanelClasses>;
+};
+/** Props VireoDockedSidePanel inherits from its default root after excluding component-owned props. */
+export type VireoDockedSidePanelInheritedProps = Omit<BoxProps<"div">, "children" | "component" | "ref">;
+/** Props accepted by {@link VireoDockedSidePanel}. */
+export type VireoDockedSidePanelProps = VireoDockedSidePanelOwnProps & VireoDockedSidePanelInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_DOCKED_SIDE_PANEL_NAME]?: VireoThemeComponent<VireoDockedSidePanelProps, VireoDockedSidePanelClassKey, VireoDockedSidePanelOwnerState, Theme>;
+    }
+}

package/dist/capabilities/overlays/components/overlays/VireoDockedSidePanel/VireoDockedSidePanel.types.js

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

package/dist/capabilities/overlays/components/overlays/VireoDockedSidePanel/index.d.ts

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

package/dist/capabilities/overlays/components/overlays/VireoDockedSidePanel/index.js

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

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.classes.d.ts

@@ -0,0 +1,9 @@
+import { type VireoOverlayHeaderSlotName } from "./VireoOverlayHeader.identity.js";
+/** Utility classes available to VireoOverlayHeader. */
+export type VireoOverlayHeaderClasses = Record<VireoOverlayHeaderSlotName, string>;
+/** Valid keys for VireoOverlayHeader utility classes and theme style overrides. */
+export type VireoOverlayHeaderClassKey = keyof VireoOverlayHeaderClasses;
+/** Returns the generated utility class name for a VireoOverlayHeader slot or state. */
+export declare function getVireoOverlayHeaderUtilityClass(slot: string): string;
+/** Generated utility class names keyed by each public VireoOverlayHeader class key. */
+export declare const vireoOverlayHeaderClasses: VireoOverlayHeaderClasses;

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.classes.js

@@ -0,0 +1,10 @@
+import { generateUtilityClass, generateUtilityClasses } from "@mui/material";
+import { VIREO_OVERLAY_HEADER_NAME, VIREO_OVERLAY_HEADER_SLOTS, } from "./VireoOverlayHeader.identity.js";
+/** Returns the generated utility class name for a VireoOverlayHeader slot or state. */
+export function getVireoOverlayHeaderUtilityClass(slot) {
+    return generateUtilityClass(VIREO_OVERLAY_HEADER_NAME, slot);
+}
+/** Generated utility class names keyed by each public VireoOverlayHeader class key. */
+export const vireoOverlayHeaderClasses = generateUtilityClasses(VIREO_OVERLAY_HEADER_NAME, [
+    ...VIREO_OVERLAY_HEADER_SLOTS,
+]);

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.d.ts

@@ -0,0 +1,27 @@
+import React from "react";
+/**
+ * Renders the standard header anatomy for Vireo dialogs, drawers, bottom sheets, and side panels.
+ */
+export declare const VireoOverlayHeader: React.ForwardRefExoticComponent<(Omit<import("./VireoOverlayHeader.types.js").VireoOverlayHeaderSlotsAndSlotProps & {
+    title: React.ReactNode;
+    titleId?: string;
+    leadingAction?: React.ReactNode;
+    actions?: React.ReactNode;
+    sticky?: boolean;
+    classes?: Partial<import("./VireoOverlayHeader.classes.js").VireoOverlayHeaderClasses>;
+} & {
+    onClose: React.MouseEventHandler<HTMLButtonElement>;
+    closeLabel: string;
+    closeDisabled?: boolean;
+} & import("./VireoOverlayHeader.types.js").VireoOverlayHeaderInheritedProps, "ref"> | Omit<import("./VireoOverlayHeader.types.js").VireoOverlayHeaderSlotsAndSlotProps & {
+    title: React.ReactNode;
+    titleId?: string;
+    leadingAction?: React.ReactNode;
+    actions?: React.ReactNode;
+    sticky?: boolean;
+    classes?: Partial<import("./VireoOverlayHeader.classes.js").VireoOverlayHeaderClasses>;
+} & {
+    onClose?: undefined;
+    closeLabel?: never;
+    closeDisabled?: never;
+} & import("./VireoOverlayHeader.types.js").VireoOverlayHeaderInheritedProps, "ref">) & React.RefAttributes<HTMLElement>>;

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.identity.d.ts

@@ -0,0 +1,6 @@
+/** Stable component name shared by every VireoOverlayHeader integration point. */
+export declare const VIREO_OVERLAY_HEADER_NAME = "VireoOverlayHeader";
+/** Canonical public slots exposed by VireoOverlayHeader, in rendered DOM order. */
+export declare const VIREO_OVERLAY_HEADER_SLOTS: readonly ["root", "leadingAction", "title", "actions", "closeButton", "closeIcon"];
+/** Public slot names exposed by VireoOverlayHeader. */
+export type VireoOverlayHeaderSlotName = (typeof VIREO_OVERLAY_HEADER_SLOTS)[number];

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.identity.js

@@ -0,0 +1,11 @@
+/** Stable component name shared by every VireoOverlayHeader integration point. */
+export const VIREO_OVERLAY_HEADER_NAME = "VireoOverlayHeader";
+/** Canonical public slots exposed by VireoOverlayHeader, in rendered DOM order. */
+export const VIREO_OVERLAY_HEADER_SLOTS = [
+    "root",
+    "leadingAction",
+    "title",
+    "actions",
+    "closeButton",
+    "closeIcon",
+];

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { joinClassNames, mergeSx, resolveSlotProps } from "../../../../../core/public.js";
+import { unstable_composeClasses as composeClasses } from "@mui/material";
+import { useThemeProps } from "@mui/material/styles";
+import { useForkRef } from "@mui/material/utils";
+import React from "react";
+import { getVireoOverlayHeaderUtilityClass } from "./VireoOverlayHeader.classes.js";
+import { VIREO_OVERLAY_HEADER_NAME } from "./VireoOverlayHeader.identity.js";
+import { VireoOverlayHeaderActions, VireoOverlayHeaderCloseButton, VireoOverlayHeaderCloseIcon, VireoOverlayHeaderLeadingAction, VireoOverlayHeaderRoot, VireoOverlayHeaderTitle, } from "./VireoOverlayHeader.styled.js";
+function useUtilityClasses(_ownerState, classes) {
+    return composeClasses({
+        root: ["root"],
+        leadingAction: ["leadingAction"],
+        title: ["title"],
+        actions: ["actions"],
+        closeButton: ["closeButton"],
+        closeIcon: ["closeIcon"],
+    }, getVireoOverlayHeaderUtilityClass, classes);
+}
+/**
+ * Renders the standard header anatomy for Vireo dialogs, drawers, bottom sheets, and side panels.
+ */
+export const VireoOverlayHeader = React.forwardRef(function VireoOverlayHeader(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_OVERLAY_HEADER_NAME });
+    const { actions, className, classes: classesProp, closeDisabled = false, closeLabel, leadingAction, onClose, slotProps = {}, slots = {}, sticky = true, style, sx, title, titleId, ...other } = props;
+    const generatedTitleId = React.useId();
+    const ownerState = {
+        sticky,
+        closable: onClose !== undefined,
+        closeDisabled,
+        hasLeadingAction: leadingAction !== undefined && leadingAction !== null,
+        hasActions: actions !== undefined && actions !== null,
+    };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const resolvedLeadingActionSlotProps = resolveSlotProps(slotProps.leadingAction, ownerState);
+    const resolvedTitleSlotProps = resolveSlotProps(slotProps.title, ownerState);
+    const resolvedActionsSlotProps = resolveSlotProps(slotProps.actions, ownerState);
+    const resolvedCloseButtonSlotProps = resolveSlotProps(slotProps.closeButton, ownerState);
+    const resolvedCloseIconSlotProps = resolveSlotProps(slotProps.closeIcon, ownerState);
+    const { className: rootSlotClassName, ref: rootSlotRef, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef);
+    const { className: leadingActionSlotClassName, ...leadingActionSlotOther } = resolvedLeadingActionSlotProps;
+    const { className: titleSlotClassName, id: titleSlotId, ...titleSlotOther } = resolvedTitleSlotProps;
+    const { className: actionsSlotClassName, ...actionsSlotOther } = resolvedActionsSlotProps;
+    const { className: closeButtonSlotClassName, disabled: closeButtonSlotDisabled, onClick: closeButtonSlotOnClick, ...closeButtonSlotOther } = resolvedCloseButtonSlotProps;
+    const { className: closeIconSlotClassName, ...closeIconSlotOther } = resolvedCloseIconSlotProps;
+    const resolvedTitleId = titleId ?? titleSlotId ?? generatedTitleId;
+    const effectiveCloseDisabled = closeDisabled || closeButtonSlotDisabled === true;
+    const handleClose = React.useCallback(event => {
+        closeButtonSlotOnClick?.(event);
+        if (!event.defaultPrevented) {
+            onClose?.(event);
+        }
+    }, [closeButtonSlotOnClick, onClose]);
+    return (_jsxs(VireoOverlayHeaderRoot, { ...other, ...rootSlotOther, as: slots.root ?? "header", ref: rootRef, ownerState: ownerState, className: joinClassNames(classes.root, className, rootSlotClassName), style: { ...style, ...rootSlotStyle }, sx: mergeSx(sx, rootSlotSx), children: [ownerState.hasLeadingAction && (_jsx(VireoOverlayHeaderLeadingAction, { ...leadingActionSlotOther, as: slots.leadingAction, ownerState: ownerState, className: joinClassNames(classes.leadingAction, leadingActionSlotClassName), children: leadingAction })), _jsx(VireoOverlayHeaderTitle, { variant: "h6", ...(slots.title === undefined ? { variantMapping: { h6: "h2" } } : {}), ...titleSlotOther, as: slots.title, id: resolvedTitleId, ownerState: ownerState, className: joinClassNames(classes.title, titleSlotClassName), children: title }), ownerState.hasActions && (_jsx(VireoOverlayHeaderActions, { ...actionsSlotOther, as: slots.actions, ownerState: ownerState, className: joinClassNames(classes.actions, actionsSlotClassName), children: actions })), ownerState.closable && (_jsx(VireoOverlayHeaderCloseButton, { ...closeButtonSlotOther, as: slots.closeButton, ownerState: ownerState, className: joinClassNames(classes.closeButton, closeButtonSlotClassName), "aria-label": closeLabel, disabled: effectiveCloseDisabled, onClick: handleClose, children: _jsx(VireoOverlayHeaderCloseIcon, { ...closeIconSlotOther, as: slots.closeIcon, ownerState: ownerState, className: joinClassNames(classes.closeIcon, closeIconSlotClassName), "aria-hidden": "true", focusable: "false" }) }))] }));
+});
+VireoOverlayHeader.displayName = VIREO_OVERLAY_HEADER_NAME;

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.styled.d.ts

@@ -0,0 +1,11 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type BoxProps, type IconButtonProps, type SvgIconProps, type TypographyProps } from "@mui/material";
+import { type VireoOverlayHeaderOwnerState } from "./VireoOverlayHeader.types.js";
+type VireoOverlayHeaderStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoOverlayHeaderOwnerState>;
+export declare const VireoOverlayHeaderRoot: VireoOverlayHeaderStyledSlotComponent<BoxProps>;
+export declare const VireoOverlayHeaderLeadingAction: VireoOverlayHeaderStyledSlotComponent<BoxProps>;
+export declare const VireoOverlayHeaderTitle: VireoOverlayHeaderStyledSlotComponent<TypographyProps>;
+export declare const VireoOverlayHeaderActions: VireoOverlayHeaderStyledSlotComponent<BoxProps>;
+export declare const VireoOverlayHeaderCloseButton: VireoOverlayHeaderStyledSlotComponent<IconButtonProps>;
+export declare const VireoOverlayHeaderCloseIcon: VireoOverlayHeaderStyledSlotComponent<SvgIconProps>;
+export {};

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.styled.js

@@ -0,0 +1,67 @@
+import { Close } from "@mui/icons-material";
+import { Box, IconButton, Typography, } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_OVERLAY_HEADER_NAME } from "./VireoOverlayHeader.identity.js";
+export const VireoOverlayHeaderRoot = styled(Box, {
+    name: VIREO_OVERLAY_HEADER_NAME,
+    slot: "Root",
+    overridesResolver: (_props, styles) => styles.root,
+})(({ ownerState, theme }) => ({
+    boxSizing: "border-box",
+    width: "100%",
+    flex: "0 0 auto",
+    display: "flex",
+    alignItems: "center",
+    gap: theme.spacing(2),
+    padding: theme.spacing(1.5, 2, 1.5, 3),
+    color: theme.palette.text.primary,
+    backgroundColor: theme.palette.background.paper,
+    borderBottom: `1px solid ${theme.palette.divider}`,
+    ...(ownerState.sticky && {
+        position: "sticky",
+        top: 0,
+        zIndex: 1,
+    }),
+}));
+export const VireoOverlayHeaderLeadingAction = styled(Box, {
+    name: VIREO_OVERLAY_HEADER_NAME,
+    slot: "LeadingAction",
+    overridesResolver: (_props, styles) => styles.leadingAction,
+})({
+    flex: "0 0 auto",
+    display: "flex",
+    alignItems: "center",
+});
+export const VireoOverlayHeaderTitle = styled(Typography, {
+    name: VIREO_OVERLAY_HEADER_NAME,
+    slot: "Title",
+    overridesResolver: (_props, styles) => styles.title,
+})(({ theme }) => ({
+    minWidth: 0,
+    flex: "1 1 auto",
+    color: theme.palette.text.primary,
+    overflowWrap: "anywhere",
+}));
+export const VireoOverlayHeaderActions = styled(Box, {
+    name: VIREO_OVERLAY_HEADER_NAME,
+    slot: "Actions",
+    overridesResolver: (_props, styles) => styles.actions,
+})(({ theme }) => ({
+    flex: "0 0 auto",
+    display: "flex",
+    alignItems: "center",
+    gap: theme.spacing(1),
+}));
+export const VireoOverlayHeaderCloseButton = styled(IconButton, {
+    name: VIREO_OVERLAY_HEADER_NAME,
+    slot: "CloseButton",
+    overridesResolver: (_props, styles) => styles.closeButton,
+})(({ theme }) => ({
+    flex: "0 0 auto",
+    color: theme.palette.action.active,
+}));
+export const VireoOverlayHeaderCloseIcon = styled(Close, {
+    name: VIREO_OVERLAY_HEADER_NAME,
+    slot: "CloseIcon",
+    overridesResolver: (_props, styles) => styles.closeIcon,
+})({});

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.types.d.ts

@@ -0,0 +1,85 @@
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { Close } from "@mui/icons-material";
+import type { BoxProps, IconButton, Typography } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoOverlayHeaderClasses, type VireoOverlayHeaderClassKey } from "./VireoOverlayHeader.classes.js";
+import type { VIREO_OVERLAY_HEADER_NAME, VireoOverlayHeaderSlotName } from "./VireoOverlayHeader.identity.js";
+export type VireoOverlayHeaderOwnerState = {
+    sticky: boolean;
+    closable: boolean;
+    closeDisabled: boolean;
+    hasLeadingAction: boolean;
+    hasActions: boolean;
+};
+export interface VireoOverlayHeaderRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoOverlayHeaderLeadingActionSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoOverlayHeaderTitleSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoOverlayHeaderActionsSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoOverlayHeaderCloseButtonSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoOverlayHeaderCloseIconSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by {@link VireoOverlayHeader}. */
+export type VireoOverlayHeaderSlots = {
+    [TSlotName in VireoOverlayHeaderSlotName]: React.ElementType;
+};
+/** Slot props exposed by {@link VireoOverlayHeader}. */
+export type VireoOverlayHeaderSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoOverlayHeaderSlots, {
+    /** @default 'header' */
+    root: SlotProps<"header", VireoOverlayHeaderRootSlotPropsOverrides, VireoOverlayHeaderOwnerState>;
+    /** @default 'div' */
+    leadingAction: SlotProps<"div", VireoOverlayHeaderLeadingActionSlotPropsOverrides, VireoOverlayHeaderOwnerState>;
+    /** @default Typography */
+    title: SlotProps<typeof Typography, VireoOverlayHeaderTitleSlotPropsOverrides, VireoOverlayHeaderOwnerState>;
+    /** @default 'div' */
+    actions: SlotProps<"div", VireoOverlayHeaderActionsSlotPropsOverrides, VireoOverlayHeaderOwnerState>;
+    /** @default IconButton */
+    closeButton: SlotProps<typeof IconButton, VireoOverlayHeaderCloseButtonSlotPropsOverrides, VireoOverlayHeaderOwnerState>;
+    /** @default Close */
+    closeIcon: SlotProps<typeof Close, VireoOverlayHeaderCloseIconSlotPropsOverrides, VireoOverlayHeaderOwnerState>;
+}>;
+/** Props shared by closable and non-closable overlay headers. */
+export type VireoOverlayHeaderOwnProps = VireoOverlayHeaderSlotsAndSlotProps & {
+    /** Visible overlay title. String values are rendered as text, never parsed as HTML. */
+    title: React.ReactNode;
+    /** ID applied to the title and referenced by the containing overlay surface. */
+    titleId?: string;
+    /** Optional leading navigation or action control. */
+    leadingAction?: React.ReactNode;
+    /** Optional status or action content rendered after the title. */
+    actions?: React.ReactNode;
+    /** Keeps the header above scrolling overlay content. @default true */
+    sticky?: boolean;
+    /** Override or extend the utility classes applied to each slot. */
+    classes?: Partial<VireoOverlayHeaderClasses>;
+};
+/** Props VireoOverlayHeader inherits from its default root after excluding component-owned props. */
+export type VireoOverlayHeaderInheritedProps = Omit<BoxProps<"header">, "children" | "component" | "onClose" | "title">;
+/** A close button is only valid when both its callback and accessible label are provided. */
+export type VireoOverlayHeaderCloseProps = {
+    onClose: React.MouseEventHandler<HTMLButtonElement>;
+    closeLabel: string;
+    closeDisabled?: boolean;
+} | {
+    onClose?: undefined;
+    closeLabel?: never;
+    closeDisabled?: never;
+};
+/** Props accepted by {@link VireoOverlayHeader}. */
+export type VireoOverlayHeaderProps = VireoOverlayHeaderOwnProps & VireoOverlayHeaderCloseProps & VireoOverlayHeaderInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_OVERLAY_HEADER_NAME]?: VireoThemeComponent<VireoOverlayHeaderProps, VireoOverlayHeaderClassKey, VireoOverlayHeaderOwnerState, Theme>;
+    }
+}

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/VireoOverlayHeader.types.js

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

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/index.d.ts

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

package/dist/capabilities/overlays/components/overlays/VireoOverlayHeader/index.js

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

package/dist/capabilities/overlays/components/overlays/VireoResponsiveOverlayFrame/VireoResponsiveOverlayFrame.classes.d.ts

@@ -0,0 +1,9 @@
+import { type VireoResponsiveOverlayFrameSlotName } from "./VireoResponsiveOverlayFrame.identity.js";
+/** Utility classes available to VireoResponsiveOverlayFrame. */
+export type VireoResponsiveOverlayFrameClasses = Record<VireoResponsiveOverlayFrameSlotName, string>;
+/** Valid keys for VireoResponsiveOverlayFrame utility classes and theme style overrides. */
+export type VireoResponsiveOverlayFrameClassKey = keyof VireoResponsiveOverlayFrameClasses;
+/** Returns the generated utility class name for a VireoResponsiveOverlayFrame slot or state. */
+export declare function getVireoResponsiveOverlayFrameUtilityClass(slot: string): string;
+/** Generated utility class names keyed by each public VireoResponsiveOverlayFrame class key. */
+export declare const vireoResponsiveOverlayFrameClasses: VireoResponsiveOverlayFrameClasses;

package/dist/capabilities/overlays/components/overlays/VireoResponsiveOverlayFrame/VireoResponsiveOverlayFrame.classes.js

@@ -0,0 +1,8 @@
+import { generateUtilityClass, generateUtilityClasses } from "@mui/material";
+import { VIREO_RESPONSIVE_OVERLAY_FRAME_NAME, VIREO_RESPONSIVE_OVERLAY_FRAME_SLOTS, } from "./VireoResponsiveOverlayFrame.identity.js";
+/** Returns the generated utility class name for a VireoResponsiveOverlayFrame slot or state. */
+export function getVireoResponsiveOverlayFrameUtilityClass(slot) {
+    return generateUtilityClass(VIREO_RESPONSIVE_OVERLAY_FRAME_NAME, slot);
+}
+/** Generated utility class names keyed by each public VireoResponsiveOverlayFrame class key. */
+export const vireoResponsiveOverlayFrameClasses = generateUtilityClasses(VIREO_RESPONSIVE_OVERLAY_FRAME_NAME, [...VIREO_RESPONSIVE_OVERLAY_FRAME_SLOTS]);