@veevarts/design-system 2.1.0-beta.14 → 2.1.0-beta.15

package/dist/patterns/AdminToolbar/AdminToolbar.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { AdminToolbarSearchWidth, AdminToolbarSize } from './types';
 export interface AdminToolbarProps {
     searchValue: string;
     onSearchChange: (value: string) => void;
@@ -10,12 +11,19 @@ export interface AdminToolbarProps {
     searchIcon?: React.ReactNode;
     /** Shows a clear button inside the search box while it holds text. Off by default. */
     searchClearable?: boolean;
+    /** The clear button's accessible name. `'Clear search'` by default; pass a translation. */
+    clearLabel?: string;
     /** Filters, sort pickers, a toggle — laid out after the search box. */
     children?: React.ReactNode;
     /** Pushed to the far right, for a primary action. */
     trailing?: React.ReactNode;
-    /** Search box width. `'md'` (280px) by default, `'lg'` (360px) for wide tables. */
-    searchWidth?: 'md' | 'lg';
+    /**
+     * Search box width. `'md'` (280px; 250px framed) by default, `'lg'` (360px)
+     * for wide tables, `'fill'` to grow into the space the row leaves.
+     */
+    searchWidth?: AdminToolbarSearchWidth;
+    /** `'lg'` is the 48px touch field with 16px text; `'md'` (default) keeps each variant's own height. */
+    size?: AdminToolbarSize;
     variant?: 'default' | 'framed';
     className?: string;
     'data-testid'?: string;

package/dist/patterns/AdminToolbar/index.d.ts

@@ -1,2 +1,3 @@
 export { AdminToolbar } from './AdminToolbar';
 export type { AdminToolbarProps } from './AdminToolbar';
+export type { AdminToolbarSearchWidth, AdminToolbarSize } from './types';

package/dist/patterns/AdminToolbar/styles.d.ts

@@ -0,0 +1,49 @@
+import { AdminToolbarSearchWidth, AdminToolbarSize } from './types';
+/** The default variant: a pixel-port of the accounting mockups, so its values stay in px. */
+export declare const DEFAULT_CLASS: {
+    readonly base: "flex flex-wrap items-center gap-3 mb-4";
+    readonly trailing: "ml-auto";
+    readonly icon: "flex text-acct-muted";
+    readonly inputWrapper: string;
+    readonly input: "text-[13.5px] text-acct-ink";
+};
+export declare const DEFAULT_SEARCH_WIDTH: Record<AdminToolbarSearchWidth, string>;
+export declare const FRAMED_WIDE_REM = 48;
+export declare const FRAMED_CLASS: {
+    readonly base: "flex flex-wrap items-center gap-2.5 border-b border-pos-hair px-4 py-[0.875rem]";
+    readonly narrow: "[&_[data-slot=filter-select]]:!max-w-none [&_[data-slot=filter-select]]:!min-w-[calc(50%-0.3125rem)] [&_[data-slot=filter-select]]:grow [&_[data-slot=filter-select]]:basis-[calc(50%-0.3125rem)]";
+    readonly searchWide: "ml-auto";
+    /** Fill wins over the narrow rule: it already takes the row, and keeps a trailing action beside it until 12.5rem. */
+    readonly searchFill: "min-w-[12.5rem] flex-1";
+    readonly searchNarrow: "basis-full";
+    readonly inputBaseNarrow: "w-full";
+    readonly inputWrapper: "h-[2.375rem] min-h-[2.375rem] !h-[2.375rem] rounded-[0.625rem] border border-pos-field bg-white pl-3 pr-3 shadow-none data-[hover=true]:border-pos-field group-data-[focus=true]:border-primary";
+    readonly innerWrapper: "gap-[0.3125rem]";
+    readonly input: "text-ellipsis text-[0.875rem] text-default-900 data-[has-start-content=true]:ps-0.5";
+    readonly icon: "flex text-default-400 [&_svg]:size-4";
+};
+export declare const FRAMED_SEARCH_WIDTH: Record<AdminToolbarSearchWidth, string>;
+/**
+ * `lg` is the POS register's touch row: a 48px field with 16px text and a 20px
+ * glyph, in rem so the text-size setting scales it. Merged after either
+ * variant's own classes, so it overrides their height and type only.
+ */
+export declare const LG_CLASS: {
+    readonly inputWrapper: "h-12 min-h-12 !h-12";
+    readonly input: "text-base";
+    readonly icon: "[&_svg]:size-5";
+};
+/**
+ * The clear control: a DS `Button`, so it is in the tab order and takes a
+ * translated name, unlike HeroUI's `isClearable` (tabIndex -1, English label).
+ * 32px inside the 38–40px fields, 44px inside the 48px one.
+ */
+export declare const CLEAR_CLASS: {
+    readonly button: "shrink-0 text-default-500";
+    /** The browser's own search "x" would sit beside ours. */
+    readonly input: "[&::-webkit-search-cancel-button]:appearance-none";
+};
+export declare const CLEAR_SIZE_CLASS: Record<AdminToolbarSize, {
+    button: string;
+    icon: string;
+}>;

package/dist/patterns/AdminToolbar/types.d.ts

@@ -0,0 +1,2 @@
+export type AdminToolbarSearchWidth = 'md' | 'lg' | 'fill';
+export type AdminToolbarSize = 'md' | 'lg';

package/dist/patterns/DiscardGuard/DiscardGuard.d.ts

@@ -0,0 +1,23 @@
+import { default as React } from 'react';
+import { DiscardGuardController } from './useDiscardGuard';
+/** @internal Used by `ModalPanels` to make each panel its own guard scope. */
+export declare const DiscardGuardScope: React.FC<{
+    scope: string;
+    children: React.ReactNode;
+}>;
+export interface DiscardGuardProps {
+    /** The controller from `useDiscardGuard()`. */
+    guard: DiscardGuardController;
+    children: React.ReactNode;
+    /** Confirmation heading. Default `'Discard changes?'`. */
+    title?: string;
+    /** What is lost by confirming. Default `'What you entered will be lost.'`. */
+    description?: React.ReactNode;
+    /** Confirm (discard) label. Default `'Discard'`. */
+    confirmLabel?: string;
+    /** Label of the action that returns to the form. Default `'Keep editing'`. */
+    keepEditingLabel?: string;
+    /** Root test id of the confirmation; derives `-confirm` and `-dismiss`. Default `'discard-guard'`. */
+    'data-testid'?: string;
+}
+export declare const DiscardGuard: React.FC<DiscardGuardProps>;

package/dist/patterns/DiscardGuard/context.d.ts

@@ -0,0 +1,25 @@
+import { DirtyReport, Leave } from './useDiscardGuard';
+export interface DiscardGuardContextValue {
+    guardScope: (scope: string | null, leave: Leave) => void;
+    bypass: (leave: Leave) => void;
+    report: (id: string, report: DirtyReport) => void;
+    unreport: (id: string) => void;
+}
+export declare const DiscardGuardContext: import('react').Context<DiscardGuardContextValue>;
+/** The scope a reporter or a Back press belongs to. `ModalPanels` sets one per panel. */
+export declare const DiscardScopeContext: import('react').Context<string | null>;
+/**
+ * Call from a form while it is mounted. Unmounting withdraws the report, so a
+ * form that is gone never holds an exit hostage.
+ */
+export declare function useReportUnsavedChanges(isDirty: boolean): void;
+export interface DiscardGuardActions {
+    /** Leave the whole surface: asks when any form is dirty. */
+    guard: (leave: Leave) => void;
+    /** Leave without asking — the input was saved. */
+    bypass: (leave: Leave) => void;
+}
+/** The guard's exits, for components rendered inside `<DiscardGuard>`. */
+export declare function useDiscardGuardActions(): DiscardGuardActions;
+/** @internal Back inside a panel: asks only when that panel holds unsaved input. */
+export declare function useScopedDiscardGuard(): (leave: Leave) => void;

package/dist/patterns/DiscardGuard/index.d.ts

@@ -0,0 +1,6 @@
+export { DiscardGuard } from './DiscardGuard';
+export type { DiscardGuardProps } from './DiscardGuard';
+export { useDiscardGuard } from './useDiscardGuard';
+export type { DiscardGuardController } from './useDiscardGuard';
+export { useDiscardGuardActions, useReportUnsavedChanges } from './context';
+export type { DiscardGuardActions } from './context';

package/dist/patterns/DiscardGuard/useDiscardGuard.d.ts

@@ -0,0 +1,38 @@
+export type Leave = () => void;
+/** One mounted reporter: which scope (panel) it belongs to and whether it holds unsaved input. */
+export interface DirtyReport {
+    scope: string | null;
+    isDirty: boolean;
+}
+interface PendingLeave {
+    leave: Leave;
+}
+/** Wiring `<DiscardGuard>` reads; not part of the consumer contract. */
+interface DiscardGuardInternals {
+    pending: PendingLeave | null;
+    /** Bumped on confirm so the dialog unmounts in the same commit as the exit (see the file header). */
+    confirmKey: number;
+    confirm: () => void;
+    keepEditing: () => void;
+    report: (id: string, report: DirtyReport) => void;
+    unreport: (id: string) => void;
+    guardScope: (scope: string | null, leave: Leave) => void;
+}
+export interface DiscardGuardController {
+    /** True while any mounted form reports unsaved input. */
+    readonly isDirty: boolean;
+    /** Runs `leave` now, or after the operator confirms when a form is dirty. */
+    guard: (leave: Leave) => void;
+    /** Runs `leave` without asking — for exits that keep the input, like a successful save. */
+    bypass: (leave: Leave) => void;
+    /**
+     * Wraps a modal's `onOpenChange` so its close button, Escape and outside
+     * click go through `guard`. Opening passes straight through.
+     */
+    guardOpenChange: (onOpenChange: (open: boolean) => void) => (open: boolean) => void;
+    /** @internal Read by `<DiscardGuard>`. */
+    readonly internals: DiscardGuardInternals;
+}
+/** Creates the guard. Call it in the component that owns the modal. */
+export declare function useDiscardGuard(): DiscardGuardController;
+export {};

package/dist/patterns/EntityRow/EntityList.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { EntityListProps, EntityListSkeletonProps } from './types';
+export declare const EntityList: React.FC<EntityListProps>;
+/**
+ * The list in skeleton form, at the same row height so nothing shifts when the
+ * rows arrive. The placeholder rows are hidden from assistive tech; `label` is
+ * announced once through a `role="status"` region instead.
+ */
+export declare const EntityListSkeleton: React.FC<EntityListSkeletonProps>;

package/dist/patterns/EntityRow/EntityRow.d.ts

@@ -0,0 +1,3 @@
+import { default as React } from 'react';
+import { EntityRowProps } from './types';
+export declare const EntityRow: React.FC<EntityRowProps>;

package/dist/patterns/EntityRow/context.d.ts

@@ -0,0 +1,2 @@
+/** True inside an `EntityList`, so rows default to `li`. */
+export declare const EntityListContext: import('react').Context<boolean>;

package/dist/patterns/EntityRow/icons.d.ts

@@ -0,0 +1,3 @@
+/** Inline so the defaults render offline and without an icon registry. */
+export declare const ChevronRightIcon: () => import("react/jsx-runtime").JSX.Element;
+export declare const MenuDotsIcon: () => import("react/jsx-runtime").JSX.Element;

package/dist/patterns/EntityRow/index.d.ts

@@ -0,0 +1,3 @@
+export { EntityRow } from './EntityRow';
+export { EntityList, EntityListSkeleton } from './EntityList';
+export type { EntityRowProps, EntityRowSize, EntityRowVariant, EntityRowTag, EntityRowTagTone, EntityRowLeading, EntityRowAction, EntityListProps, EntityListSkeletonProps, } from './types';

package/dist/patterns/EntityRow/initials.d.ts

@@ -0,0 +1,6 @@
+/**
+ * "Chidi Okafor" → "CO", "Ana María de la Cruz" → "AC", "Cher" → "C".
+ * First and last word, so a long name does not spell an acronym the way
+ * HeroUI's default (every word's initial) does. Empty → "—".
+ */
+export declare function initialsFromName(name: string): string;

package/dist/patterns/EntityRow/styles.d.ts

@@ -0,0 +1,59 @@
+import { EntityListProps, EntityRowSize, EntityRowTagTone, EntityRowVariant } from './types';
+export declare const entityRowClass: {
+    readonly base: "relative flex w-full items-center gap-2 transition-colors";
+    readonly content: "flex min-w-0 flex-1 items-center gap-3 text-left";
+    /**
+     * The press target is a HeroUI `Button` (or `Link`) stretched over the row
+     * by its `::after`. Its base classes have to be undone for that to work:
+     * `relative` would make the button the overlay's containing block,
+     * `transform-gpu` would too, `overflow-hidden` clips the overlay,
+     * `min-w-max` and `whitespace-nowrap` defeat truncation, and the focus
+     * outline is moved from the button to the overlay so it rings the row.
+     */
+    readonly pressTarget: string;
+    readonly text: "flex min-w-0 flex-col";
+    readonly titleLine: "flex min-w-0 items-center gap-2";
+    readonly title: "truncate font-medium text-default-900";
+    readonly subtitle: "truncate text-default-600";
+    readonly tags: "flex shrink-0 items-center gap-1";
+    /** Lifted above the stretched overlay so each stays its own control. */
+    readonly side: "relative z-10 flex shrink-0 items-center gap-1";
+    readonly chevron: "flex shrink-0 text-default-500";
+    readonly menuTrigger: "text-default-600";
+    readonly avatar: "shrink-0 bg-default-200 text-default-700";
+    readonly dangerItem: "text-danger";
+};
+/**
+ * Text overrides for flat chips whose HeroUI tone measures under 4.5:1 on the
+ * plain row's hover tint (default-100): primary 4.39:1 and warning 4.03:1 at
+ * their `-700` text. One step darker clears it; the others already do.
+ */
+export declare const entityRowTagToneClass: Record<EntityRowTagTone, string | undefined>;
+export declare const entityRowVariantClass: Record<EntityRowVariant, {
+    row: string;
+    hover: string;
+    overlay: string;
+}>;
+export declare const entityRowSizeClass: Record<EntityRowSize, {
+    row: string;
+    content: string;
+    title: string;
+    subtitle: string;
+    avatar: 'sm' | 'md';
+    control: 'md' | 'lg';
+}>;
+export declare const entityRowMenuItemClass: Record<EntityRowSize, string | undefined>;
+export declare const entityListGapClass: Record<NonNullable<EntityListProps['gap']>, string>;
+export declare const entityListClass = "m-0 flex list-none flex-col p-0";
+export declare const entityListSkeletonClass: {
+    readonly row: "flex items-center gap-3 px-2";
+    readonly avatar: {
+        readonly md: "size-8 shrink-0 rounded-full";
+        readonly lg: "size-10 shrink-0 rounded-full";
+    };
+    readonly lines: "flex flex-col gap-2";
+    readonly title: "h-4 rounded-md";
+    readonly subtitle: "h-3 w-44 rounded-md";
+    /** Varied so the placeholder does not read as a ruled grid. */
+    readonly titleWidths: readonly ["w-32", "w-28", "w-36", "w-24", "w-40", "w-28"];
+};

package/dist/patterns/EntityRow/types.d.ts

@@ -0,0 +1,118 @@
+import { ElementType, ReactNode } from 'react';
+/** `md` is a desk row (48px), `lg` a touch row (56px). */
+export type EntityRowSize = 'md' | 'lg';
+/** `plain` sits in a list and tints on hover; `bordered` is a standalone hairline card. */
+export type EntityRowVariant = 'plain' | 'bordered';
+export type EntityRowTagTone = 'default' | 'primary' | 'success' | 'warning' | 'danger';
+export interface EntityRowTag {
+    key: string;
+    label: ReactNode;
+    /** Maps to the HeroUI `Chip` color, always `variant="flat"`. */
+    tone?: EntityRowTagTone;
+}
+/**
+ * What the row leads with. Always decorative (`aria-hidden`): the title is the
+ * row's name. Precedence: `src`, then `icon`, then initials (`initials`, else
+ * derived from `name`, else from a string `title`).
+ */
+export interface EntityRowLeading {
+    /** Image URL. */
+    src?: string;
+    /** An icon tile instead of initials (a household, an organization). */
+    icon?: ReactNode;
+    /** Explicit initials, used verbatim. */
+    initials?: string;
+    /** Source for derived initials when the title is not the person's name. */
+    name?: string;
+    /** `circle` for people (default), `square` for a tile. */
+    shape?: 'circle' | 'square';
+}
+export interface EntityRowAction {
+    key: string;
+    label: string;
+    icon?: ReactNode;
+    tone?: 'default' | 'danger';
+    isDisabled?: boolean;
+    onAction: () => void;
+    /** Defaults to `<row testid>-menu-<key>`. */
+    'data-testid'?: string;
+}
+/**
+ * Actions and their label travel together: an overflow trigger is icon-only,
+ * so without a label it is announced as "button" and nothing else.
+ */
+type EntityRowActionsProps = {
+    actions?: undefined;
+    actionsLabel?: undefined;
+} | {
+    /** Overflow menu items. An empty array renders no trigger. */
+    actions: EntityRowAction[];
+    /**
+     * Accessible name of the `⋯` trigger and of the menu. Include the
+     * subject: "Actions for Chidi Okafor", not "Actions" — a list of
+     * these otherwise reads as a column of identical buttons.
+     */
+    actionsLabel: string;
+};
+interface EntityRowBaseProps {
+    /** The row's accessible name. */
+    title: ReactNode;
+    /** Second line (contact details, a count, "View household"). */
+    subtitle?: ReactNode;
+    leading?: EntityRowLeading;
+    /** Chips beside the title. */
+    tags?: EntityRowTag[];
+    /**
+     * Makes the whole row a button. The press target is stretched over the
+     * row; `trailing` and the actions menu stay their own controls.
+     */
+    onPress?: () => void;
+    /** Makes the whole row a link (wins over `onPress` for semantics; both fire). */
+    href?: string;
+    /** Router link component for `href` (Next.js `Link`, React Router `Link`). */
+    linkAs?: ElementType;
+    /** e.g. `'dialog'` when the row opens a picker. Only for button rows. */
+    'aria-haspopup'?: 'dialog' | 'menu' | 'listbox' | true;
+    /** Explicit control between the text and the menu ("Select", "Add"). */
+    trailing?: ReactNode;
+    /** Trailing chevron: the row leads somewhere. */
+    showChevron?: boolean;
+    /** Overrides the default chevron glyph. */
+    chevronIcon?: ReactNode;
+    /** Overrides the default `⋯` glyph. */
+    actionsIcon?: ReactNode;
+    /** Defaults from `DensityProvider`: `touch` → `lg`, otherwise `md`. */
+    size?: EntityRowSize;
+    variant?: EntityRowVariant;
+    /** Disables the press target and the actions trigger (not `trailing`, which the host owns). */
+    isDisabled?: boolean;
+    /** Container element. Defaults to `li` inside `EntityList`, `div` elsewhere. */
+    as?: 'li' | 'div';
+    className?: string;
+    /**
+     * Row container. Derived: `-trigger` (press target), `-menu-trigger`,
+     * `-menu`, `-menu-<key>`.
+     */
+    'data-testid'?: string;
+}
+export type EntityRowProps = EntityRowBaseProps & EntityRowActionsProps;
+export interface EntityListProps {
+    children: ReactNode;
+    /** Name the list: `aria-label` or `aria-labelledby` (one is required by a11y review). */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    /** Spacing between rows; `bordered` rows read better apart. */
+    gap?: 'none' | 'sm' | 'md';
+    className?: string;
+    'data-testid'?: string;
+}
+export interface EntityListSkeletonProps {
+    /** Announced to assistive tech while the rows load ("Loading contacts"). */
+    label: string;
+    rows?: number;
+    /** Defaults from `DensityProvider`, like `EntityRow`. */
+    size?: EntityRowSize;
+    className?: string;
+    'data-testid'?: string;
+}
+export {};

package/dist/patterns/InlineConfirm/InlineConfirm.d.ts

@@ -0,0 +1,38 @@
+import { default as React } from 'react';
+export type InlineConfirmVariant = 'danger' | 'warning';
+export type InlineConfirmSize = 'sm' | 'md' | 'lg';
+export interface InlineConfirmProps {
+    /** The question. Also the accessible name of the alertdialog. */
+    message: React.ReactNode;
+    /** Optional consequences. Becomes `aria-describedby`. */
+    description?: React.ReactNode;
+    /** Label for the confirm action. Carry the verb ("Remove"), not "OK". */
+    confirmLabel: string;
+    /** Label for the cancel action. Default `'Cancel'`. */
+    cancelLabel?: string;
+    onConfirm: () => void;
+    /** Fires from the Cancel button and from Escape. */
+    onCancel: () => void;
+    /** Drives the surface tone and the confirm colour. Default `'danger'`. */
+    variant?: InlineConfirmVariant;
+    /** Spinner on confirm; Cancel and Escape locked. Default `false`. */
+    isPending?: boolean;
+    /** Which button receives focus on mount. Default `'cancel'`. */
+    initialFocus?: 'cancel' | 'confirm';
+    /** Stop Escape from reaching ancestors (e.g. an enclosing Modal). Default `true`. */
+    containEscape?: boolean;
+    /**
+     * Button size: `'sm'` 32px (default), `'md'` 40px, `'lg'` 48px for a touch
+     * register.
+     */
+    size?: InlineConfirmSize;
+    /**
+     * `'li'` wraps the box in a list item, for swapping it in place of a row of
+     * a `ul`/`ol`. Default `'div'`.
+     */
+    as?: 'li' | 'div';
+    className?: string;
+    /** Root test id; the buttons get `<id>-confirm` and `<id>-cancel`. */
+    'data-testid'?: string;
+}
+export declare const InlineConfirm: React.FC<InlineConfirmProps>;

package/dist/patterns/InlineConfirm/index.d.ts

@@ -0,0 +1,2 @@
+export { InlineConfirm } from './InlineConfirm';
+export type { InlineConfirmProps, InlineConfirmVariant, InlineConfirmSize } from './InlineConfirm';

package/dist/patterns/InlineConfirm/styles.d.ts

@@ -0,0 +1,16 @@
+import { InlineConfirmVariant } from './InlineConfirm';
+export declare const inlineConfirmClass: {
+    /** The `li` that keeps list semantics when the box replaces a row. */
+    readonly item: "list-none";
+    /**
+     * The alertdialog itself. It only takes focus programmatically, while pending,
+     * and then shows the system focus ring when the user is on the keyboard.
+     */
+    readonly box: "outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
+    readonly body: "gap-3 px-4 py-3";
+    readonly text: "flex min-w-0 flex-col gap-1";
+    readonly message: "text-sm text-gray-900 [overflow-wrap:anywhere]";
+    readonly description: "text-sm text-gray-600 [overflow-wrap:anywhere]";
+    readonly actions: "flex flex-wrap items-center gap-2";
+};
+export declare const inlineConfirmSurface: Record<InlineConfirmVariant, string>;

package/dist/patterns/ModalPanels/ModalPanels.d.ts

@@ -0,0 +1,35 @@
+import { default as React } from 'react';
+import { ModalPanelEntry, ModalPanelsController } from './useModalPanels';
+export interface ModalPanelsProps<TPanel> {
+    /** The stack from `useModalPanels()`. */
+    panels: ModalPanelsController<TPanel>;
+    /** Renders one panel. Called for every entry on the stack; only the top one is shown. */
+    children: (panel: TPanel, entry: ModalPanelEntry<TPanel>) => React.ReactNode;
+}
+export declare function ModalPanels<TPanel>({ panels, children }: ModalPanelsProps<TPanel>): React.ReactElement;
+export interface ModalPanelHeaderProps {
+    /** Panel title, rendered as an `h2`. */
+    title: React.ReactNode;
+    /**
+     * Where Back goes. Default: the panel beneath, from the stack. Either way
+     * it goes through the discard guard, scoped to this panel.
+     */
+    onBack?: () => void;
+    /** Back's accessible name. Default `'Back'`. */
+    backLabel?: string;
+    isBackDisabled?: boolean;
+    /** Back button size: `'md'` 40px, `'lg'` 48px (touch registers). Default `'md'`. */
+    size?: 'md' | 'lg';
+    /** Content at the end of the header, before the modal's close button. */
+    actions?: React.ReactNode;
+    className?: string;
+    /** Root test id; derives `-back` and `-title`. Default `'modal-panel-header'`. */
+    'data-testid'?: string;
+}
+/**
+ * Back + title for a panel pushed over the first one. Back is navigation, not
+ * one of the footer's decisions, so it lives top-left where it never moves.
+ * It is shown when there is somewhere to go back to (or `onBack` is given),
+ * and it is the element focus lands on when the panel opens.
+ */
+export declare const ModalPanelHeader: React.FC<ModalPanelHeaderProps>;

package/dist/patterns/ModalPanels/context.d.ts

@@ -0,0 +1,20 @@
+export interface ModalPanelContextValue {
+    isActive: boolean;
+    canGoBack: boolean;
+    back: () => void;
+    setEntryFocus: (node: HTMLElement | null) => void;
+}
+export declare const ModalPanelContext: import('react').Context<ModalPanelContextValue | null>;
+export interface ModalPanelState {
+    /** True for the panel on screen. */
+    isActive: boolean;
+    /** True when a panel lies beneath this one. */
+    canGoBack: boolean;
+    /** Returns to the panel beneath — asking first if this panel holds unsaved input. */
+    back: () => void;
+}
+/**
+ * The enclosing panel, for controls other than the header's Back — a footer
+ * Cancel, say. Outside `ModalPanels` it reports a lone, active panel.
+ */
+export declare function useModalPanel(): ModalPanelState;

package/dist/patterns/ModalPanels/focus.d.ts

@@ -0,0 +1,39 @@
+/** First element in `container` a Tab press would reach, skipping anything inside a hidden or inert subtree. */
+export declare function firstTabbable(container: HTMLElement): HTMLElement | null;
+/** Still in `container` and still able to take focus — not removed, disabled or hidden since it was recorded. */
+export declare function canStillFocus(element: HTMLElement | null, container: HTMLElement): element is HTMLElement;
+/**
+ * A popup (menu, listbox) currently open from a trigger inside `container`,
+ * found through the trigger's own ARIA wiring: `aria-expanded="true"` plus
+ * `aria-controls` naming the popup.
+ */
+export declare function openPopupFrom(container: HTMLElement): HTMLElement | null;
+/**
+ * Fired by react-aria's `FocusScope` on the element it is about to restore
+ * focus to when an overlay (a menu, a select, a dialog) unmounts; cancelable,
+ * and bubbles from that element. It is react-aria's own seam for redirecting a
+ * restore, and the reason no timer is needed here (see the file header).
+ */
+export declare const FOCUS_RESTORE_EVENT = "react-aria-focus-scope-restore";
+/** DOM handles per panel key, and which panel is on screen. Plain bookkeeping; never read during render. */
+export declare class PanelFocusMemory {
+    private readonly panels;
+    private active;
+    setContainer(key: string, node: HTMLElement | null): void;
+    setEntry(key: string, node: HTMLElement | null): void;
+    remember(key: string, node: HTMLElement): void;
+    /** The panel now on screen, and whether the operator came back to it (vs. opened it). */
+    setActive(key: string, isReturn: boolean): void;
+    /**
+     * Puts focus in the panel on screen, unless it is already there. Returning:
+     * the element that last had focus in it — the opener of the panel just left.
+     * Entering, or when that element is gone: Back, then the first tabbable element.
+     */
+    focusActive(): void;
+    /**
+     * Focus was dropped by an overlay closing over a hidden panel. If the
+     * operator has since opened a menu or select in the panel on screen, that
+     * is where they are; otherwise it is the panel's own target.
+     */
+    recoverFocus(): void;
+}

package/dist/patterns/ModalPanels/index.d.ts

@@ -0,0 +1,6 @@
+export { ModalPanels, ModalPanelHeader } from './ModalPanels';
+export type { ModalPanelsProps, ModalPanelHeaderProps } from './ModalPanels';
+export { useModalPanel } from './context';
+export type { ModalPanelState } from './context';
+export { useModalPanels } from './useModalPanels';
+export type { ModalPanelsController, ModalPanelEntry } from './useModalPanels';

package/dist/patterns/ModalPanels/styles.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ModalPanelHeader slots. The header mirrors HeroUI's `ModalHeader` slot
+ * (`flex py-4 px-6 flex-initial text-large font-semibold`) so a panel header
+ * and the first panel's `ModalHeader` line up when they swap.
+ *
+ * `pl-4`, not `px-6`: the Back button's hit area is wider than its 20px glyph,
+ * so starting it 16px in puts the arrow on the 24px content edge. `pr-12`
+ * leaves the corner to HeroUI's absolutely-positioned close button.
+ */
+export declare const modalPanelHeaderClass = "flex flex-initial items-center gap-2 py-4 pl-4 pr-12 text-large font-semibold";
+export declare const modalPanelTitleClass = "min-w-0 flex-1 truncate text-large font-semibold";
+export declare const modalPanelActionsClass = "flex shrink-0 items-center gap-2";
+export declare const modalPanelBackIconClass = "size-5";

package/dist/patterns/ModalPanels/useModalPanels.d.ts

@@ -0,0 +1,30 @@
+/** One panel on the stack. `key` is unique per visit, so pushing the same panel twice mounts it twice. */
+export interface ModalPanelEntry<TPanel> {
+    readonly key: string;
+    readonly panel: TPanel;
+}
+export interface ModalPanelsController<TPanel> {
+    /** The panel on top — the one on screen. */
+    readonly current: TPanel;
+    /** Bottom to top. Every entry stays mounted; only the last one is shown. */
+    readonly entries: readonly ModalPanelEntry<TPanel>[];
+    /** True when there is a panel beneath the current one. */
+    readonly canGoBack: boolean;
+    /** Opens `panel` on top; Back returns to the one showing now. */
+    push: (panel: TPanel) => void;
+    /** Returns to the panel beneath. No-op on the first panel. */
+    back: () => void;
+    /** Swaps the top panel for `panel` (e.g. a saved form for its detail); Back skips the old one. */
+    replace: (panel: TPanel) => void;
+    /** Starts over with a single fresh panel — `initial` unless another is given. */
+    reset: (panel?: TPanel) => void;
+}
+/**
+ * The back-stack behind `ModalPanels`: which panel is on screen, and where Back
+ * goes from it. Back goes where the operator came from because the stack
+ * remembers it — no per-panel "return to" flags to keep in step.
+ *
+ * Owned by the component that owns the modal, so it outlives the modal's
+ * content; call `reset()` when the modal closes to start the next visit fresh.
+ */
+export declare function useModalPanels<TPanel>(initial: TPanel): ModalPanelsController<TPanel>;

package/dist/patterns/PaginationSummary/PaginationSummary.d.ts

@@ -3,6 +3,12 @@ export interface PaginationSummaryClassNames {
     base?: string;
     emphasis?: string;
 }
+/** The range `format` receives; `from` and `to` are both 0 when there is nothing to show. */
+export interface PaginationSummaryRange {
+    from: number;
+    to: number;
+    total: number;
+}
 export interface PaginationSummaryProps {
     /** Current page, 1-based. */
     page: number;
@@ -19,6 +25,12 @@ export interface PaginationSummaryProps {
      * avoid reading the change twice.
      */
     announce?: boolean;
+    /**
+     * Writes the sentence instead of the built-in English "Showing {range} of
+     * {total} {unit}". Use it to translate; `unit` and `classNames.emphasis`
+     * do not apply, since the returned node is the whole sentence.
+     */
+    format?: (range: PaginationSummaryRange) => React.ReactNode;
     className?: string;
     classNames?: PaginationSummaryClassNames;
     'data-testid'?: string;

package/dist/patterns/PaginationSummary/index.d.ts

@@ -1,3 +1,3 @@
 export { PaginationSummary } from './PaginationSummary';
-export type { PaginationSummaryProps, PaginationSummaryClassNames } from './PaginationSummary';
+export type { PaginationSummaryProps, PaginationSummaryClassNames, PaginationSummaryRange } from './PaginationSummary';
 export { pageRange } from './page-range';