@foris/avocado-suite 1.13.0 → 1.14.1

package/dist/components/access-panel/AccessPanel.d.ts

@@ -9,10 +9,15 @@ export type AccessPanelProduct = {
 export interface AccessPanelProps {
     className?: string;
     isOpen?: boolean;
+    /** Header text. Falls back to a localized default. */
     title?: string;
+    /** Products section title. Falls back to a localized default. */
     productsTitle?: string;
+    /** Recent products section title. Falls back to a localized default. */
     recentProductsTitle?: string;
+    /** Custom products section title. Falls back to a localized default. */
     customProductsTitle?: string;
+    /** Pill text on the active product. Falls back to a localized default. */
     activePillText?: string;
     products?: AccessPanelProduct[];
     recentProducts?: AccessPanelProduct[];

package/dist/components/access-panel/accessPanel.locale.d.ts

@@ -0,0 +1,16 @@
+export declare const ACCESS_PANEL_STRINGS: {
+    en: {
+        title: string;
+        productsTitle: string;
+        recentProductsTitle: string;
+        customProductsTitle: string;
+        activePillText: string;
+    };
+    es: {
+        title: string;
+        productsTitle: string;
+        recentProductsTitle: string;
+        customProductsTitle: string;
+        activePillText: string;
+    };
+};

package/dist/components/access-panel/components/access-product/AccessProduct.d.ts

@@ -1,5 +1,6 @@
 import { AccessPanelProduct } from '../../AccessPanel';
 interface AccessProductProps extends AccessPanelProduct {
+    /** Pill text when active. Falls back to a localized default. */
     activePillText?: string;
 }
 declare const AccessProduct: ({ isActive, name, logo, activePillText, onClick, }: AccessProductProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/drawer/Drawer.d.ts

@@ -1,64 +1,101 @@
 import React from 'react';
-export interface DrawerProps {
-    /** Optional custom header row content (shown next to the title area). */
-    header?: React.ReactNode;
-    /** Renders below the main header row when a header is shown. */
-    headerExtra?: React.ReactNode;
-    /** Title shown in the header; omit with `header` / `headerExtra` to control visibility. */
-    title?: React.ReactNode;
-    /** Main panel content (scrollable body). */
-    children: React.ReactNode;
-    /** Sticky footer below the body. */
-    footer?: React.ReactNode;
-    /** When `true`, the drawer is visible (open animation). Controlled from the parent. */
+import { type DrawerMode } from '../drawer-layout/drawerLayoutContext';
+import type { DrawerExpansionConfig } from './types/drawerExpansion.types';
+import type { DrawerHeaderConfig } from './types/drawerHeader.types';
+import type { DrawerCloseReason, DrawerNavigationBinding, DrawerNavigationTarget } from './types/drawerNavigation.types';
+/** Content, presentation and lifecycle options for a contextual panel. */
+export interface DrawerProps<Target extends DrawerNavigationTarget = DrawerNavigationTarget> {
+    /** Controlled visibility; opens or starts the closing animation. */
     isOpen: boolean;
+    /** Notifies the caller after the closing transition, when the panel is removed. */
+    onClose: () => void;
+    /**
+     * Allows or denies user dismissal; false, a thrown error or a rejection keeps the panel open.
+     * Controlled isOpen changes bypass this guard.
+     */
+    beforeClose?: (reason: DrawerCloseReason) => boolean | Promise<boolean>;
+    /** Notifies an allowed user dismissal before the exit completes; onClose remains after-exit. */
+    onRequestClose?: (reason: DrawerCloseReason) => void;
     /**
-     * If `true`, clicking the backdrop closes the drawer. If there is no header, this is often the only way to dismiss without `onClose` from children.
-     *
-     * @default false
+     * Allows a backdrop click to start closing the panel.
+     * @defaultValue false
      */
     closeOnOverlayClick?: boolean;
+    /** Structured header configuration; takes precedence over the legacy header props. */
+    headerConfig?: DrawerHeaderConfig;
+    /** Main content for a static Drawer; navigation supplies its own body when enabled. */
+    children?: React.ReactNode;
+    /** Optional local navigation; each visit renders its own DrawerView and replaces the static slots. */
+    navigation?: DrawerNavigationBinding<Target>;
+    /** Main footer content below the scrollable body; composition belongs to the caller. */
+    footer?: React.ReactNode;
+    /** Optional content below the footer, with caller-owned formatting; also works on its own. */
+    footerMessage?: React.ReactNode;
+    /**
+     * Applies the standard body padding; disable for edge-to-edge embedded content.
+     * @defaultValue true
+     */
+    bodyPadding?: boolean;
+    /** Requested presentation; pinned requires a DrawerLayout host and sufficient space. Without a host it floats. @defaultValue 'floating' */
+    mode?: DrawerMode;
+    /** Accessible panel name; hosted panels default to the structured title, otherwise "Drawer content". */
+    accessibleLabel?: string;
     /**
-     * @description Height gap in pixels to subtract from the drawer's height, so the drawer appears shorter by this amount. Useful for keeping the app header visible above the drawer.
-     *
-     * @default 50
-     * @example
-     * <Drawer heightGap={50} />
+     * Floating top offset in pixels; ignored when pinned or expanded.
+     * @defaultValue 50
      */
     heightGap?: number;
     /**
-     * Slide-in edge: `right` (default) or `left`.
-     *
-     * @default 'right'
+     * Edge from which the panel slides into view.
+     * @defaultValue 'right'
      */
     origin?: 'left' | 'right';
-    /** Class name on the root overlay `section`. */
-    className?: string;
-    /** Class name on the inner panel (`drawer_content`), e.g. to override max-width. */
-    contentClassName?: string;
     /**
-     * When false, the drawer body has no horizontal/vertical padding (default padding is kept for typical form layouts).
-     *
-     * @default true
+     * Panel width outside DrawerLayout: `md` is responsive up to 507px and `lg` up to 600px.
+     * DrawerLayout supplies its own width.
+     * @defaultValue 'md'
      */
-    bodyPadding?: boolean;
+    size?: 'md' | 'lg';
     /**
-     * `fit` caps the panel at `min(600px, 100%)` with `width: 100%` so expand/collapse can animate smoothly (avoiding `width: auto`). Use with children that fill the shell (e.g. ChatPanel). `default` uses `max-width: min(30vw, 507px)` and `min-width: 448px` (same floor as ChatPanel).
-     *
-     * @default 'default'
+     * Standalone width policy.
+     * @deprecated Use `size`: `default` is `md` and `fit` is `lg`. `size` wins when both are set.
      */
     contentWidth?: 'default' | 'fit';
     /**
-     * When `true`, the drawer panel expands to fill the full viewport width.
-     * Controlled from the parent — typically wired to a ChatPanel `onExpandedChange` callback.
-     *
-     * @default false
+     * Fills the viewport, ignores heightGap and releases any pinned column; controlled by the caller.
+     * @defaultValue false
      */
     isExpanded?: boolean;
+    /** Enables the built-in desktop expand/collapse button in either header. Defaults to disabled. */
+    expansion?: boolean | DrawerExpansionConfig;
+    /** Reports an expansion toggle; required when isExpanded controls the built-in button. */
+    onExpandedChange?: (isExpanded: boolean) => void;
+    /** Additional class on the root overlay section. */
+    className?: string;
+    /** Additional class on the inner panel, for example to customize its width. */
+    contentClassName?: string;
     /**
-     * Called after the close animation finishes and the drawer unmounts from the tree (when transitioning from open to closed).
+     * Title content in the legacy header row.
+     * @deprecated Use `headerConfig.title` (plain text) and `headerConfig.closeLabel`.
+     * Move icons and metadata to their dedicated configuration fields.
      */
-    onClose: () => void;
+    title?: React.ReactNode;
+    /**
+     * Custom content beside the legacy title and close button.
+     * @deprecated Use `headerConfig.controls` for desktop presentation actions,
+     * or `headerConfig.toolbar` for actions available on all screen sizes.
+     */
+    header?: React.ReactNode;
+    /**
+     * Additional content below the legacy header row.
+     * @deprecated Use `headerConfig.pills`, `description`, `context` or `toolbar`
+     * according to the content.
+     */
+    headerExtra?: React.ReactNode;
 }
-declare const Drawer: React.FC<DrawerProps>;
+/**
+ * Stable shell that keeps its content mounted through mode changes and until exit completes.
+ * Generic so `navigation.renderView` receives the controller's typed entries.
+ */
+declare function Drawer<Target extends DrawerNavigationTarget = DrawerNavigationTarget>(props: DrawerProps<Target>): import("react/jsx-runtime").JSX.Element | null;
 export default Drawer;

package/dist/components/drawer/Drawer.test.d.ts

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

package/dist/components/drawer/DrawerExpansion.test.d.ts

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

package/dist/components/drawer/DrawerGuards.test.d.ts

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

package/dist/components/drawer/DrawerKeyboard.test.d.ts

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

package/dist/components/drawer/DrawerMotion.test.d.ts

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

package/dist/components/drawer/DrawerNavigation.test.d.ts

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

package/dist/components/drawer/DrawerStacking.test.d.ts

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

package/dist/components/drawer/components/body/DrawerBody.d.ts

@@ -0,0 +1,9 @@
+import { type HTMLAttributes } from 'react';
+/** Shared scrolling surface for static content and navigable visits. */
+export interface DrawerBodyProps extends HTMLAttributes<HTMLElement> {
+    /** Applies the standard content inset; disable for embedded edge-to-edge components. */
+    hasPadding: boolean;
+}
+/** Keeps body geometry identical in both composition modes. */
+declare const DrawerBody: import("react").ForwardRefExoticComponent<DrawerBodyProps & import("react").RefAttributes<HTMLElement>>;
+export default DrawerBody;

package/dist/components/drawer/components/footer/DrawerFooter.d.ts

@@ -0,0 +1,11 @@
+import { type FC, type ReactNode } from 'react';
+/** Optional footer regions supplied by the Drawer shell. */
+export interface DrawerFooterProps {
+    /** Main footer content, such as actions, an input or a custom component. */
+    content?: ReactNode;
+    /** Supporting content below the main slot, with caller-owned formatting. */
+    message?: ReactNode;
+}
+/** Keeps optional footer slots outside the scrolling body without styling their contents. */
+declare const DrawerFooter: FC<DrawerFooterProps>;
+export default DrawerFooter;

package/dist/components/drawer/components/header/DrawerCloseControl.d.ts

@@ -0,0 +1,15 @@
+import type { FC } from 'react';
+/** Private close action shared by the static header and the navigable Drawer shell. */
+export interface DrawerCloseControlProps {
+    /** Localized accessible name for dismissal. */
+    label: string;
+    /** Requests dismissal; the Drawer shell decides whether it is allowed. */
+    onClose: () => void;
+    /** Blocks dismissal while a confirmation is pending or exit has begun. */
+    disabled?: boolean;
+    /** Keeps the button fixed above the visits that slide beneath it. */
+    persistent?: boolean;
+}
+/** One close-button implementation preserves layout and keyboard behavior across modes. */
+declare const DrawerCloseControl: FC<DrawerCloseControlProps>;
+export default DrawerCloseControl;

package/dist/components/drawer/components/header/DrawerHeader.d.ts

@@ -0,0 +1,13 @@
+import type { FC } from 'react';
+import type { DrawerHeaderConfig } from '../../types/drawerHeader.types';
+import { type DrawerCloseControlProps } from './DrawerCloseControl';
+/** Internal connection between the structured header and the Drawer shell. */
+export interface DrawerHeaderProps {
+    /** Identity, actions and optional contextual rows supplied by the caller. */
+    config: Omit<DrawerHeaderConfig, 'closeLabel'>;
+    /** Inline close control; without it, the slot is reserved for the shell's persistent one. */
+    close?: Omit<DrawerCloseControlProps, 'persistent'>;
+}
+/** Renders the header regions; the Drawer shell owns visibility and dismissal. */
+declare const DrawerHeader: FC<DrawerHeaderProps>;
+export default DrawerHeader;

package/dist/components/drawer/components/header/DrawerIconButton.d.ts

@@ -0,0 +1,11 @@
+import type { ButtonHTMLAttributes, FC } from 'react';
+import type { IconTypes } from '../../../../../../avocado-icons';
+/** Private icon-only action shared by the header's leading, Back and close controls. */
+export interface DrawerIconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+    /** Glyph shown inside the button. */
+    icon: IconTypes;
+    /** Localized accessible name, also used as the tooltip. */
+    label: string;
+}
+declare const DrawerIconButton: FC<DrawerIconButtonProps>;
+export default DrawerIconButton;

package/dist/components/drawer/components/header/DrawerLegacyHeader.d.ts

@@ -0,0 +1,19 @@
+import type { FC, ReactNode } from 'react';
+/** @deprecated Private compatibility branch; remove with Drawer's legacy header props. */
+export interface DrawerLegacyHeaderProps {
+    /** Legacy identity content. */
+    title?: ReactNode;
+    /** Legacy controls beside the title. */
+    header?: ReactNode;
+    /** Legacy content below the main row. */
+    headerExtra?: ReactNode;
+    /** Built-in desktop presentation controls; do not create a header on their own. */
+    presentationControls?: ReactNode;
+    /** Requests dismissal through the shell's guard. */
+    onClose: () => void;
+    /** Disables dismissal during a guard or exit. */
+    isCloseDisabled?: boolean;
+}
+/** @deprecated Preserves legacy composition until the next breaking header migration. */
+declare const DrawerLegacyHeader: FC<DrawerLegacyHeaderProps>;
+export default DrawerLegacyHeader;

package/dist/components/drawer/components/navigation/DrawerNavigationView.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+import type { DrawerNavigationBinding, DrawerNavigationTarget } from '../../types/drawerNavigation.types';
+import type { DrawerNavigationSnapshotDetails } from '../../utils/drawerNavigationInternals';
+/** Id of a visit's body, whose accessible name is the visit title. */
+export declare const getDrawerVisitLabelId: (entryKey: string) => string;
+/** Renders every visit in history; only the current one is visible and interactive. */
+export interface DrawerNavigationViewProps<Target extends DrawerNavigationTarget> {
+    /** Controller, view renderer and Back label supplied by the consumer. */
+    navigation: DrawerNavigationBinding<Target>;
+    /** Built-in controls shared by every visit header. */
+    presentationControls?: ReactNode;
+    /** Operation that produced the current snapshot; selects the transition. */
+    lastAction: DrawerNavigationSnapshotDetails['lastAction'];
+    /** Applies the standard body padding when true. */
+    bodyPadding: boolean;
+}
+/** Previous visits stay mounted, so their state, scroll and focus survive Back. */
+declare function DrawerNavigationView<Target extends DrawerNavigationTarget>({ navigation: { controller, renderView, backLabel }, lastAction, bodyPadding, presentationControls, }: DrawerNavigationViewProps<Target>): import("react/jsx-runtime").JSX.Element;
+export default DrawerNavigationView;

package/dist/components/drawer/components/navigation/DrawerNavigationVisit.d.ts

@@ -0,0 +1,17 @@
+import { type FC, type MutableRefObject, type ReactNode } from 'react';
+import { type DrawerVisitContextValue } from '../../contexts/drawerNavigationContext';
+export interface DrawerNavigationVisitProps extends Omit<DrawerVisitContextValue, 'bodyRef'> {
+    /** The current visit; covered and exiting visits are hidden and inert. */
+    isActive: boolean;
+    /** Direction for push/back, or zero for replace/reset. */
+    direction: -1 | 0 | 1;
+    /** Removes horizontal travel and duration for reduced-motion users. */
+    isReducedMotion: boolean;
+    /** False only while the view renders its first visit, which must not take focus. */
+    hasNavigated: MutableRefObject<boolean>;
+    /** The consumer's DrawerView for this visit. */
+    children: ReactNode;
+}
+/** Keeps one visit mounted; Back reveals it with its state, scroll and last focus intact. */
+declare const DrawerNavigationVisit: FC<DrawerNavigationVisitProps>;
+export default DrawerNavigationVisit;

package/dist/components/drawer/components/navigation/DrawerView.d.ts

@@ -0,0 +1,19 @@
+import { type FC, type ReactNode } from 'react';
+import type { DrawerHeaderConfig } from '../../types/drawerHeader.types';
+/** One navigable visit: its header, scrolling body and footer change together. */
+export interface DrawerViewProps {
+    /**
+     * Identity, actions and contextual rows; Back replaces the leading action below the root.
+     * The close label belongs to `navigation.closeLabel`, since Close stays outside the visit.
+     */
+    headerConfig: Omit<DrawerHeaderConfig, 'closeLabel'>;
+    /** Scrolling content of this visit. */
+    children?: ReactNode;
+    /** Optional main footer content for this visit. */
+    footer?: ReactNode;
+    /** Optional supporting content beneath this visit's footer. */
+    footerMessage?: ReactNode;
+}
+/** Composes a visit inside `navigation.renderView`; the shell keeps Close fixed above it. */
+declare const DrawerView: FC<DrawerViewProps>;
+export default DrawerView;

package/dist/components/drawer/contexts/drawerNavigationContext.d.ts

@@ -0,0 +1,19 @@
+import { type RefObject, type ReactNode } from 'react';
+import type { DrawerHeaderAction } from '../types/drawerHeader.types';
+import type { DrawerNavigationController } from '../types/drawerNavigation.types';
+/** Private provider shared by all regions of a navigable Drawer. */
+export declare const DrawerNavigationContext: import("react").Context<DrawerNavigationController<import("../types/drawerNavigation.types").DrawerNavigationTarget> | null>;
+/** Private connection between one rendered visit and the DrawerView it contains. */
+export interface DrawerVisitContextValue {
+    /** Automatic Back action; absent for the root visit. */
+    backAction?: DrawerHeaderAction;
+    /** Built-in presentation controls supplied by the shell. */
+    presentationControls?: ReactNode;
+    /** Applies the standard body padding when true. */
+    bodyPadding: boolean;
+    /** Scrolling body, used as the last focus fallback. */
+    bodyRef: RefObject<HTMLElement>;
+    /** Id of the body, which carries the visit title as its accessible name. */
+    labelId: string;
+}
+export declare const DrawerVisitContext: import("react").Context<DrawerVisitContextValue | null>;

package/dist/components/drawer/drawer.locale.d.ts

@@ -0,0 +1,10 @@
+export declare const DRAWER_STRINGS: {
+    en: {
+        expand: string;
+        collapse: string;
+    };
+    es: {
+        expand: string;
+        collapse: string;
+    };
+};

package/dist/components/drawer/hooks/useDrawerExpansion.d.ts

@@ -0,0 +1,11 @@
+import type { DrawerProps } from '../Drawer';
+/** Owns optional expansion without changing controlled consumers or remounting content. */
+export declare function useDrawerExpansion({ expansion, isExpanded: controlledExpanded, onExpandedChange, shouldRender, }: Pick<DrawerProps, 'expansion' | 'isExpanded' | 'onExpandedChange'> & {
+    shouldRender: boolean;
+}): {
+    enabled: boolean;
+    isExpanded: boolean;
+    label: string;
+    isDisabled: boolean;
+    toggle(): void;
+};

package/dist/components/drawer/hooks/useDrawerLifecycle.d.ts

@@ -0,0 +1,17 @@
+import type { DrawerProps } from '../Drawer';
+import type { DrawerCloseReason } from '../types/drawerNavigation.types';
+import type { DrawerNavigationInternals } from '../utils/drawerNavigationInternals';
+interface DrawerLifecycleOptions extends Pick<DrawerProps, 'isOpen' | 'onClose' | 'beforeClose' | 'onRequestClose'> {
+    /** Optional navigation session sharing the shell's request lock. */
+    internal?: DrawerNavigationInternals;
+}
+/** Keeps dismissal, interrupted transitions and session cleanup independent of rendering. */
+export declare function useDrawerLifecycle(options: DrawerLifecycleOptions): {
+    shouldRender: boolean;
+    isInternalOpen: boolean;
+    isClosing: boolean;
+    isClosePending: boolean;
+    requestClose: (reason: DrawerCloseReason) => Promise<boolean> | undefined;
+    completeClose: () => void;
+};
+export {};

package/dist/components/drawer/hooks/useDrawerNavigation.d.ts

@@ -0,0 +1,3 @@
+import type { DrawerNavigationController, DrawerNavigationOptions, DrawerNavigationTarget } from '../types/drawerNavigation.types';
+/** Owns one local history of visits; data and UI state stay in the consumer's view components. */
+export declare function useDrawerNavigation<Target extends DrawerNavigationTarget>(options: DrawerNavigationOptions<Target>): DrawerNavigationController<Target>;

package/dist/components/drawer/hooks/useDrawerNavigation.test.d.ts

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

package/dist/components/drawer/hooks/useDrawerNavigationContext.d.ts

@@ -0,0 +1,3 @@
+import type { DrawerNavigationController, DrawerNavigationTarget } from '../types/drawerNavigation.types';
+/** Reads the nearest Drawer controller; use the same target union as its owner. */
+export declare function useDrawerNavigationContext<Target extends DrawerNavigationTarget = DrawerNavigationTarget>(): DrawerNavigationController<Target>;

package/dist/components/drawer/hooks/useDrawerStack.d.ts

@@ -0,0 +1,4 @@
+/** Registers an active drawer in the open order; covered = registered but not on top. */
+export declare function useDrawerStack(isActive: boolean): {
+    isCovered: boolean;
+};

package/dist/components/drawer/hooks/useDrawerStack.test.d.ts

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

package/dist/components/drawer/index.d.ts

@@ -0,0 +1,9 @@
+export { default } from './Drawer';
+export type { DrawerProps } from './Drawer';
+export type { DrawerExpansionConfig } from './types/drawerExpansion.types';
+export { default as DrawerView } from './components/navigation/DrawerView';
+export type { DrawerViewProps } from './components/navigation/DrawerView';
+export { useDrawerNavigation } from './hooks/useDrawerNavigation';
+export { useDrawerNavigationContext } from './hooks/useDrawerNavigationContext';
+export type { DrawerHeaderAction, DrawerHeaderConfig, } from './types/drawerHeader.types';
+export type { DrawerCloseReason, DrawerNavigationBinding, DrawerNavigationController, DrawerNavigationEntry, DrawerNavigationOptions, DrawerNavigationRequest, DrawerNavigationTarget, } from './types/drawerNavigation.types';

package/dist/components/drawer/types/drawerExpansion.types.d.ts

@@ -0,0 +1,9 @@
+/** Options for the Drawer's built-in desktop expansion control. */
+export interface DrawerExpansionConfig {
+    /** Initial uncontrolled state; restored after a completed close. */
+    defaultExpanded?: boolean;
+    /** Accessible name and tooltip while collapsed; defaults to the current locale. */
+    expandLabel?: string;
+    /** Accessible name and tooltip while expanded; defaults to the current locale. */
+    collapseLabel?: string;
+}

package/dist/components/drawer/types/drawerHeader.types.d.ts

@@ -0,0 +1,56 @@
+import type { ReactNode } from 'react';
+import type { IconTypes } from '../../../../../avocado-icons';
+/** Optional leading action; its behavior is owned by the caller. */
+export interface DrawerHeaderAction {
+    /** Icon displayed inside the action button. */
+    icon: IconTypes;
+    /** Localized accessible name and tooltip for the action. */
+    label: string;
+    /** Runs when the enabled action is clicked. */
+    onClick: () => void;
+    /**
+     * Prevents interaction while keeping the action visible.
+     * @defaultValue false
+     */
+    disabled?: boolean;
+}
+/** Opt-in composition for Drawer; custom slots remain owned by the consumer. */
+export interface DrawerHeaderConfig {
+    /** Plain-text heading; wraps when it exceeds the available width. */
+    title: string;
+    /**
+     * Places metadata inline (`basic`) or above the title (`stacked`).
+     * @defaultValue 'basic'
+     */
+    layout?: 'basic' | 'stacked';
+    /** Optional icon displayed beside the title. */
+    icon?: IconTypes;
+    /** Supporting identity content, inline or above the title according to the layout. */
+    metadata?: ReactNode;
+    /** Status indicators displayed alongside the metadata. */
+    badges?: ReactNode;
+    /** Optional button before the identity; does not create navigation behavior. */
+    leadingAction?: DrawerHeaderAction;
+    /** Desktop-only presentation controls, ordered expand then pin by the caller. */
+    controls?: ReactNode;
+    /** Localized accessible name and tooltip for the built-in close button. */
+    closeLabel: string;
+    /** Full-width wrapping row, typically composed with Pill. */
+    pills?: ReactNode;
+    /** Supporting text rendered below the pills. */
+    description?: string;
+    /** Full-width content; Drawer adds no card surface or business behavior. */
+    context?: ReactNode;
+    /** Additional actions below the context, available on all screen sizes. */
+    toolbar?: ReactNode;
+    /**
+     * Shows a divider along the bottom of the header.
+     * @defaultValue true
+     */
+    hasDivider?: boolean;
+    /**
+     * Visual emphasis of the bottom divider when it is shown.
+     * @defaultValue 'subtle'
+     */
+    dividerTone?: 'subtle' | 'strong';
+}

package/dist/components/drawer/types/drawerNavigation.types.d.ts

@@ -0,0 +1,68 @@
+import type { ReactNode } from 'react';
+/** Consumer-defined destination; parameters identify data, not rendered components. */
+export interface DrawerNavigationTarget {
+    /** Registered view identifier, such as `subject` or `requirement`. */
+    viewId: string;
+    /** Parameters read by the consumer's view component or data hook. */
+    params?: unknown;
+}
+/** A visit has its own identity even when the same destination appears twice. */
+export type DrawerNavigationEntry<Target extends DrawerNavigationTarget = DrawerNavigationTarget> = Target & {
+    /** Unique identity within this controller, including resets and repeated visits. */
+    readonly key: string;
+};
+/** Options for a local, opt-in history; no URL or browser-history integration. */
+export interface DrawerNavigationOptions<Target extends DrawerNavigationTarget> {
+    /** Latest initial destination, used when context changes or the session resets. */
+    rootView: Target;
+    /** Entity or route identity; changing it replaces the complete history. */
+    navigationKey: string | number;
+    /** Allowed view identifiers; unknown destinations are ignored at runtime. */
+    viewIds: readonly Target['viewId'][];
+    /** Allows or denies user navigation; false, a thrown error or a rejection keeps the view. */
+    beforeNavigate?: (request: DrawerNavigationRequest<Target>) => boolean | Promise<boolean>;
+}
+/** Navigation awaiting the consumer's approval. */
+export interface DrawerNavigationRequest<Target extends DrawerNavigationTarget = DrawerNavigationTarget> {
+    /** Requested history operation. */
+    action: 'push' | 'back' | 'replace' | 'reset';
+    /** Visit being left. */
+    from: DrawerNavigationEntry<Target>;
+    /** Destination, including the previous visit on Back. */
+    to: Target;
+}
+/** User interaction that requested dismissal. */
+export type DrawerCloseReason = 'close-button' | 'backdrop' | 'escape';
+/** Navigation state and commands available to the owner and descendant content. */
+export interface DrawerNavigationController<Target extends DrawerNavigationTarget = DrawerNavigationTarget> {
+    /** Current visit, including its typed destination parameters. */
+    readonly entry: DrawerNavigationEntry<Target>;
+    /** Visits from the root through the current one; all of them stay mounted. */
+    readonly entries: readonly DrawerNavigationEntry<Target>[];
+    /** Whether there is a previous entry to return to. */
+    readonly canGoBack: boolean;
+    /** A navigation or close confirmation is awaiting a decision; other requests resolve false. */
+    readonly isPending: boolean;
+    /** Appends a fresh visit; resolves true when history changed. */
+    push(target: Target): Promise<boolean>;
+    /** Removes the current visit; resolves false at the root. */
+    back(): Promise<boolean>;
+    /** Replaces the current visit without changing history depth. */
+    replace(target: Target): Promise<boolean>;
+    /** Starts a new session at the supplied destination or latest root. */
+    reset(target?: Target): Promise<boolean>;
+}
+/** Connects a controller and the consumer's view renderer to the Drawer shell. */
+export interface DrawerNavigationBinding<Target extends DrawerNavigationTarget = DrawerNavigationTarget> {
+    /** Controller created by useDrawerNavigation for this drawer. */
+    controller: DrawerNavigationController<Target>;
+    /**
+     * Renders one visit, usually as a component that returns DrawerView.
+     * Called for every visit in history; hidden visits stay mounted.
+     */
+    renderView: (entry: DrawerNavigationEntry<Target>) => ReactNode;
+    /** Localized accessible name and tooltip for the automatic back action. */
+    backLabel: string;
+    /** Localized accessible name and tooltip for the close control, fixed above every visit. */
+    closeLabel: string;
+}

package/dist/components/drawer/utils/createDrawerNavigation.d.ts

@@ -0,0 +1,9 @@
+import type { DrawerNavigationController, DrawerNavigationOptions, DrawerNavigationTarget } from '../types/drawerNavigation.types';
+/** Creates one local controller store; nothing is shared across Drawer instances. */
+export declare function createDrawerNavigation<Target extends DrawerNavigationTarget>(initialOptions: DrawerNavigationOptions<Target>, keyPrefix: string): {
+    getSnapshot: () => DrawerNavigationController<Target>;
+    subscribe(listener: () => void): () => void;
+    configure(next: DrawerNavigationOptions<Target>): void;
+    activate(): void;
+    deactivate(): void;
+};

package/dist/components/drawer/utils/createDrawerNavigation.test.d.ts

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

package/dist/components/drawer/utils/drawerKeyboard.d.ts

@@ -0,0 +1,3 @@
+import type { KeyboardEvent } from 'react';
+/** Wraps Tab at the panel boundaries without moving focus on mount or mode changes. */
+export declare function containDrawerTab(event: KeyboardEvent<HTMLDivElement>): void;