npm - @republicroad/seal-appshell - Versions diffs - 1.1.0 - Mend

@republicroad/seal-appshell 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (105) hide show

package/LICENSE +21 -0
package/README.md +74 -0
package/dist/assets/custom-node-schema.json.d.ts +549 -0
package/dist/components/__tests__/skinned-decision-graph.test.d.ts +1 -0
package/dist/components/__tests__/skinned-header.test.d.ts +1 -0
package/dist/components/__tests__/skinned-panels.test.d.ts +1 -0
package/dist/components/__tests__/skinned-simulator-panel.test.d.ts +1 -0
package/dist/components/__tests__/skinned-simulator.test.d.ts +1 -0
package/dist/components/custom-node/__tests__/custom-node-button.test.d.ts +1 -0
package/dist/components/custom-node/__tests__/schema-container-tab.test.d.ts +1 -0
package/dist/components/custom-node/crypto-node.d.ts +5 -0
package/dist/components/custom-node/current-date-node.d.ts +8 -0
package/dist/components/custom-node/http-request-node.d.ts +5 -0
package/dist/components/custom-node/key-value-editor.d.ts +16 -0
package/dist/components/custom-node/locked-corner-badge.d.ts +2 -0
package/dist/components/custom-node/query-list-node.d.ts +5 -0
package/dist/components/custom-node/schema-container-tab.d.ts +13 -0
package/dist/components/icons/code.d.ts +3 -0
package/dist/components/icons/flash-circle.d.ts +3 -0
package/dist/components/reui/alert.d.ts +9 -0
package/dist/components/reui/autocomplete.d.ts +40 -0
package/dist/components/reui/badge.d.ts +14 -0
package/dist/components/reui/cascader/cascader-async.d.ts +86 -0
package/dist/components/reui/cascader/cascader-columns.d.ts +26 -0
package/dist/components/reui/cascader/cascader-context.d.ts +190 -0
package/dist/components/reui/cascader/cascader-footer.d.ts +83 -0
package/dist/components/reui/cascader/cascader-i18n.d.ts +13 -0
package/dist/components/reui/cascader/cascader-item.d.ts +112 -0
package/dist/components/reui/cascader/cascader-lib.d.ts +137 -0
package/dist/components/reui/cascader/cascader-nav.d.ts +56 -0
package/dist/components/reui/cascader/cascader-types.d.ts +179 -0
package/dist/components/reui/cascader/cascader-virtual.d.ts +62 -0
package/dist/components/reui/cascader/cascader.d.ts +325 -0
package/dist/components/shell-header.d.ts +20 -0
package/dist/components/skinned-decision-graph.d.ts +19 -0
package/dist/components/ui/alert-dialog.d.ts +20 -0
package/dist/components/ui/avatar.d.ts +5 -0
package/dist/components/ui/badge.d.ts +9 -0
package/dist/components/ui/button.d.ts +11 -0
package/dist/components/ui/dropdown-menu.d.ts +27 -0
package/dist/components/ui/field.d.ts +24 -0
package/dist/components/ui/input.d.ts +3 -0
package/dist/components/ui/label.d.ts +4 -0
package/dist/components/ui/scroll-area.d.ts +4 -0
package/dist/components/ui/select.d.ts +13 -0
package/dist/components/ui/separator.d.ts +3 -0
package/dist/components/ui/sheet.d.ts +23 -0
package/dist/components/ui/sonner.d.ts +5 -0
package/dist/components/ui/spinner.d.ts +2 -0
package/dist/components/ui/switch.d.ts +3 -0
package/dist/components/ui/tabs.d.ts +6 -0
package/dist/components/ui/toggle-group.d.ts +13 -0
package/dist/components/ui/toggle.d.ts +12 -0
package/dist/components/ui/tooltip.d.ts +7 -0
package/dist/components/version-history/__tests__/version-history-panel.test.d.ts +1 -0
package/dist/components/version-history/version-history-panel.d.ts +40 -0
package/dist/context/theme.provider.d.ts +29 -0
package/dist/hooks/useCustomNodes.d.ts +16 -0
package/dist/index.d.ts +24 -0
package/dist/index.js +121959 -0
package/dist/integration/decision-graph-appshell.stories.d.ts +10 -0
package/dist/lib/__tests__/crypto-protocol.test.d.ts +1 -0
package/dist/lib/__tests__/custom-node-registry.test.d.ts +1 -0
package/dist/lib/__tests__/http-request-protocol.test.d.ts +1 -0
package/dist/lib/__tests__/json-path-protocol.test.d.ts +1 -0
package/dist/lib/__tests__/storage-key.test.d.ts +1 -0
package/dist/lib/auth/__tests__/adapter.test.d.ts +1 -0
package/dist/lib/auth/adapter.d.ts +7 -0
package/dist/lib/auth-client.d.ts +3 -0
package/dist/lib/crypto-protocol.d.ts +28 -0
package/dist/lib/custom-node-plans.d.ts +24 -0
package/dist/lib/custom-node-registry.d.ts +13 -0
package/dist/lib/custom-node-schema-source.d.ts +6 -0
package/dist/lib/custom-node-types.d.ts +73 -0
package/dist/lib/http-request-protocol.d.ts +47 -0
package/dist/lib/json-path-protocol.d.ts +11 -0
package/dist/lib/roster-source.d.ts +12 -0
package/dist/lib/storage-key.d.ts +5 -0
package/dist/lib/user-resolver.d.ts +6 -0
package/dist/lib/utils.d.ts +2 -0
package/dist/reui/icons/animated/duotone/lock.d.ts +3 -0
package/dist/reui/icons/animated/outline/play-circle.d.ts +3 -0
package/dist/reui/icons/default/outline/plus-circle.d.ts +3 -0
package/dist/reui/icons/default/outline/shield-search.d.ts +3 -0
package/dist/reui/icons/default/outline/trash-square.d.ts +3 -0
package/dist/setupTests.d.ts +0 -0
package/dist/shell/__tests__/default-simulate.test.d.ts +1 -0
package/dist/shell/__tests__/graphs-http-adapter.test.d.ts +1 -0
package/dist/shell/__tests__/indexed-db-adapter.test.d.ts +0 -0
package/dist/shell/__tests__/restore.test.d.ts +0 -0
package/dist/shell/default-simulate.d.ts +3 -0
package/dist/shell/editor-shell.context.d.ts +22 -0
package/dist/shell/execute-simulate.d.ts +8 -0
package/dist/shell/graphs-http-adapter.d.ts +7 -0
package/dist/shell/index.d.ts +10 -0
package/dist/shell/indexed-db-adapter.d.ts +16 -0
package/dist/shell/persistence.d.ts +89 -0
package/dist/shell/restore.d.ts +21 -0
package/dist/shell/types.d.ts +20 -0
package/dist/skin/__tests__/apply.test.d.ts +1 -0
package/dist/skin/apply.d.ts +7 -0
package/dist/skin/layout.d.ts +17 -0
package/dist/skin/types.d.ts +73 -0
package/dist/style.css +2 -0
package/package.json +73 -0

package/dist/components/reui/cascader/cascader-lib.d.ts ADDED Viewed

@@ -0,0 +1,137 @@
+import { CascaderCollapse, CascaderFlatNode, CascaderIndex, CascaderNode, CascaderPathSegment, CascaderSelectable } from '../../../components/reui/cascader/cascader-types';
+/** Root level key in `childrenOf`. NUL-prefixed so no real value collides. */
+export declare const CASCADER_ROOT_KEY = "\0root";
+/**
+ * Paging pseudo-node prefix. Written as an escape sequence, not a raw 0x00
+ * byte: a literal NUL makes this module read as binary and `grep -I` skips it.
+ */
+export declare const CASCADER_MORE_PREFIX = "\0more:";
+/**
+ * The four scroll classes. In the lib because `cascader-columns.tsx` needs them
+ * too and must not import `cascader.tsx`. Shell > bound > scrollport > rows.
+ */
+/**
+ * The bound. `min()` over an undefined custom property is an INVALID
+ * declaration that drops the whole max-height, hence the `100vh` fallback: an
+ * inline panel has no positioner, so no `--available-height`. `24rem` is the
+ * default cap, so the common case sets no variable at all.
+ */
+export declare const CASCADER_LIST_HEIGHT_CLASS = "max-h-[min(var(--available-height,100vh),var(--cascader-max-height,24rem))]";
+/**
+ * Each style's list padding: rows take it as `padding`, the scrollport as
+ * `scroll-padding` floored at 4px so lyra's `0` does not strand a row.
+ * Mirrored per style from `registry/styles/style-*.css`; keep them in step.
+ */
+export declare const CASCADER_LIST_PAD_CLASS = "[--cascader-list-pad:4px]";
+/** The scrollport: a `max-h-*` on the ScrollArea ROOT bounds nothing. */
+export declare const CASCADER_SCROLL_CLASS = "size-full min-h-0 **:data-[slot=scroll-area-viewport]:h-full **:data-[slot=scroll-area-viewport]:overscroll-contain **:data-[slot=scroll-area-viewport]:scroll-py-[max(var(--cascader-list-pad,4px),4px)]";
+/** The rows' box; `data-empty:p-0` keeps an empty state from double inset. */
+export declare const CASCADER_ROWS_CLASS = "p-(--cascader-list-pad,4px) data-empty:p-0";
+/** The footer's own stops; an `aria-disabled` command still counts as one. */
+export declare function getCascaderFooterStops(scope: HTMLElement): HTMLElement[];
+/** Where Tab lands, or `null` to let the browser out: focus is never trapped. */
+export declare function getCascaderTabTarget(panel: HTMLElement, from: Element | null, backwards: boolean): HTMLElement | null;
+/**
+ * The writing direction at `element`. `DirectionProvider` may only vote yes:
+ * unmounted it answers `"ltr"`, which would override a real `<html dir="rtl">`.
+ */
+export declare function isCascaderRtl(element: Element, provided: string): boolean;
+/**
+ * The paging row as a REAL node, not a DOM-only row after the list: every index
+ * Base UI hands out indexes the RENDERED array, so a DOM-only row shifts them.
+ */
+export declare function createCascaderMoreNode<T = unknown>(parentKey: string, loadedCount?: number): CascaderNode<T>;
+export declare function isCascaderMoreNode<T>(node: CascaderNode<T>): boolean;
+/** The level key a paging pseudo-node belongs to, or `null` for a real node. */
+export declare function getCascaderMoreParent<T>(node: CascaderNode<T>): string | null;
+/** Either input shape into one index. Cycle-guarded depths; first wins. */
+export declare function buildCascaderIndex<T = unknown>(items: readonly CascaderNode<T>[] | undefined, getParent?: (node: CascaderNode<T>) => string | null | undefined): CascaderIndex<T>;
+/**
+ * Folds loaded pages into an index built from `items`, so a re-render with a
+ * new `items` array keeps what the user drilled into. Static `items` wins;
+ * `detached` is `byValue` ONLY, or deep search doubles it and `childrenOf` lies.
+ */
+export declare function mergeCascaderIndex<T = unknown>(base: CascaderIndex<T>, pages: ReadonlyMap<string, readonly CascaderNode<T>[]>, detached?: ReadonlyMap<string, CascaderNode<T>>): CascaderIndex<T>;
+/** Children of `parent`, or the root level when `parent` is nullish. */
+export declare function getCascaderChildren<T>(index: CascaderIndex<T>, parent?: string | null): CascaderNode<T>[];
+/** A branch has known children, or `hasChildren` for an unfetched level. */
+export declare function isCascaderBranch<T>(index: CascaderIndex<T>, node: CascaderNode<T>): boolean;
+/** Trailing count for the default row. Explicit `count` wins over the tree. */
+export declare function getCascaderCount<T>(index: CascaderIndex<T>, node: CascaderNode<T>): number;
+/** Whether a node may be committed as a selection. */
+export declare function isCascaderSelectable<T>(index: CascaderIndex<T>, node: CascaderNode<T>, selectable: CascaderSelectable<T>): boolean;
+/** Ancestor chain for `value`, root first. Empty while async data loads. */
+export declare function getCascaderPath<T>(index: CascaderIndex<T>, value: string | null | undefined): CascaderNode<T>[];
+/**
+ * `toLocaleLowerCase`, not `toLowerCase`: the invariant mapping turns Turkish
+ * "I" into "i" not "ı", so "ışık" would never match "IŞIK". Both sides fold here.
+ */
+export declare function foldCascaderText(text: string): string;
+/** Folds once so callers can hoist the cost out of a per-node loop. */
+export declare function normalizeCascaderQuery(query: string): string;
+/** Case-insensitive substring over label and keywords; pre-fold the query. */
+export declare function matchesCascaderQuery<T>(node: CascaderNode<T>, normalized: string): boolean;
+/** Filters one level in place-order. Returns the input when the query is empty. */
+export declare function filterCascaderLevel<T>(nodes: readonly CascaderNode<T>[], query: string, matches?: (node: CascaderNode<T>, normalized: string) => boolean): CascaderNode<T>[];
+/** Searches every node, optionally under `within`, in one pass over `all`. */
+export declare function searchCascaderDeep<T>(index: CascaderIndex<T>, query: string, options?: {
+    within?: string | null;
+    limit?: number;
+    matches?: (node: CascaderNode<T>, normalized: string) => boolean;
+}): CascaderNode<T>[];
+/**
+ * Flattens the tree into tree mode's visible rows. A `sentinels` paging row
+ * COUNTS as a sibling in `aria-setsize`: it holds an index of its own.
+ */
+export declare function flattenCascaderTree<T>(index: CascaderIndex<T>, expanded: ReadonlySet<string>, sentinels?: ReadonlySet<string>): CascaderFlatNode<T>[];
+/** Shortens a path; the ellipsis segment still carries the hidden nodes. */
+export declare function collapseCascaderPath<T>(path: readonly CascaderNode<T>[], options?: {
+    maxSegments?: number;
+    collapse?: CascaderCollapse;
+}): CascaderPathSegment<T>[];
+/**
+ * Every LOADED node under `value`, root first. Reaching an unfetched descendant
+ * would mean a network request per level of the subtree on every selection.
+ */
+export declare function collectCascaderSubtree<T>(index: CascaderIndex<T>, value: string): CascaderNode<T>[];
+/**
+ * Toggles `value` with its loaded subtree, then reconciles ancestors. One flat
+ * array, no hidden "checked" state: a branch is in the selection exactly when
+ * every selectable loaded child of it is, which keeps a row's checked state an
+ * O(1) lookup. Nodes `isSelectable` rejects are skipped down AND ignored up,
+ * the pressed node excepted.
+ */
+export declare function applyCascadeSelection<T>(index: CascaderIndex<T>, selected: readonly string[], value: string, select: boolean, isSelectable?: (node: CascaderNode<T>) => boolean): string[];
+/**
+ * How many selected nodes each value has BELOW it, itself excluded. Walks UP
+ * from each selection: a per-row subtree scan would be quadratic and re-paid.
+ */
+export declare function getCascaderSelectedDescendants<T>(index: CascaderIndex<T>, selected: readonly string[]): Map<string, number>;
+/** The PARTIALLY selected values, read off counts the caller already holds. */
+export declare function getCascaderIndeterminateFrom(counts: ReadonlyMap<string, number>, selected: readonly string[]): Set<string>;
+/** The one-call form; the root uses the two halves above and its own counts. */
+export declare function getCascaderIndeterminate<T>(index: CascaderIndex<T>, selected: readonly string[]): Set<string>;
+/** How `getCascaderCheckedValues` condenses a full-closure selection. */
+export type CascaderCheckedStrategy = 'all' | 'parent' | 'child';
+/**
+ * The cascade selection under a reporting strategy. DERIVED OUTPUT ONLY: the
+ * STORED value stays the full closure, which keeps a checked state an O(1)
+ * lookup. `"all"` is the closure; `"parent"` drops a value whose parent is
+ * selected; `"child"` drops one with a selected child.
+ */
+export declare function getCascaderCheckedValues<T>(index: CascaderIndex<T>, selected: readonly string[], strategy: CascaderCheckedStrategy): readonly string[];
+/** Values in `nodes` whose label collides, so the chip must show its path. */
+export declare function findAmbiguousCascaderLabels<T>(nodes: readonly CascaderNode<T>[]): Set<string>;
+/** Warns once per `key`, never in production, never by throwing. */
+export declare function warnCascaderOnce(key: string, message: string): void;
+/** Empties the ledger. Tests only; a warning is meant to be seen once. */
+export declare function resetCascaderWarnings(): void;
+/** What a dev-time scan of the consumer's `items` found wrong with it. */
+export interface CascaderDataIssues {
+    /** Values appearing more than once. First wins, so a duplicate drops a row. */
+    duplicates: string[];
+    /** Values on a `getParent` cycle. Depth is clamped, so the tree reads wrong. */
+    cycles: string[];
+}
+/** Dev-time scan, kept out of `buildCascaderIndex` so the build stays hot. */
+export declare function findCascaderDataIssues<T>(items: readonly CascaderNode<T>[] | undefined, getParent?: (node: CascaderNode<T>) => string | null | undefined): CascaderDataIssues;

package/dist/components/reui/cascader/cascader-nav.d.ts ADDED Viewed

@@ -0,0 +1,56 @@
+import { Combobox as ComboboxPrimitive } from '@base-ui/react';
+import { useRender } from '@base-ui/react/use-render';
+import { CascaderCollapse, CascaderNode, CascaderValueDisplay } from '../../../components/reui/cascader/cascader-types';
+import * as React from 'react';
+export type CascaderNavProps = useRender.ComponentProps<'div'>;
+/**
+ * Header: back control, search input, and the separator under them. The
+ * breadcrumb belongs with the list below: it describes the rows, not the field.
+ */
+declare function CascaderNav({ className, ...props }: CascaderNavProps): React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+export interface CascaderBackProps extends Omit<useRender.ComponentProps<'button'>, 'children'> {
+    children?: React.ReactNode;
+}
+/** Pops one level. Renders nothing at the root, so no dead header space. */
+declare function CascaderBack({ className, children, ...props }: CascaderBackProps): React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
+export interface CascaderBreadcrumbProps extends Omit<useRender.ComponentProps<'nav'>, 'children'> {
+    /** Maximum visible node segments before the middle collapses. */
+    maxSegments?: number;
+    collapse?: CascaderCollapse;
+    /** Clicking a segment navigates back to that level. Defaults to true. */
+    interactive?: boolean;
+}
+/**
+ * Compact trail of the current level AND its ancestors, collapsed by the same
+ * helper as `CascaderValue` so panel and trigger cannot disagree. The current
+ * level IS the last crumb: dropping it read as a rendering bug, a trail naming
+ * only the places you are not.
+ */
+declare function CascaderBreadcrumb({ className, maxSegments, collapse, interactive, ...props }: CascaderBreadcrumbProps): React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
+export interface CascaderInputProps extends ComboboxPrimitive.Input.Props {
+    /** Renders the back control inline, before the field. Defaults to true. */
+    showBack?: boolean;
+}
+/**
+ * Search field. MUST render inside the positioner: only there does Base UI skip
+ * the refill from the committed selection that would fight every level swap.
+ */
+declare function CascaderInput({ className, showBack, placeholder, onKeyDown, 'aria-describedby': ariaDescribedBy, ...props }: CascaderInputProps): React.JSX.Element;
+export interface CascaderValueProps extends Omit<useRender.ComponentProps<'span'>, 'children'> {
+    /** `path` shows the full trail, `leaf` only the node, `count` only a total. */
+    display?: CascaderValueDisplay;
+    maxSegments?: number;
+    collapse?: CascaderCollapse;
+    separator?: React.ReactNode;
+    /** Renders the selected node's icon before the trail. */
+    showIcon?: boolean;
+    placeholder?: React.ReactNode;
+    /** Replaces the whole rendering. Receives the resolved selection and path. */
+    children?: (selected: CascaderNode[], path: CascaderNode[]) => React.ReactNode;
+}
+/**
+ * Trigger display. Defaults to the collapsed selection path rather than a bare
+ * leaf label, which in a nested picker is frequently ambiguous.
+ */
+declare function CascaderValue({ className, display, maxSegments, collapse, separator, showIcon, placeholder, children, ...props }: CascaderValueProps): React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+export { CascaderNav, CascaderBack, CascaderBreadcrumb, CascaderInput, CascaderValue };

package/dist/components/reui/cascader/cascader-types.d.ts ADDED Viewed

@@ -0,0 +1,179 @@
+import type * as React from 'react';
+/**
+ * A node in the cascader tree. Two input shapes normalize to one internal
+ * index: nested (nodes carry `children`), or flat adjacency plus the root's
+ * `getParent`, which skips the re-nesting step for large datasets.
+ */
+export interface CascaderNode<T = unknown> {
+    /** Stable id. Also the committed selection value. */
+    value: string;
+    label: string;
+    icon?: React.ReactNode;
+    description?: string;
+    children?: CascaderNode<T>[];
+    /** Declares a branch before load; async nodes read as leaves without it. */
+    hasChildren?: boolean;
+    /** Trailing count. Defaults to known children; set it for async nodes. */
+    count?: number;
+    disabled?: boolean;
+    keywords?: string[];
+    /**
+     * Only read on a node nested inside a `getChildren` result. For the level a
+     * node OWNS the authoritative signal is that level's `CascaderLoadResult`.
+     */
+    hasMore?: boolean;
+    data?: T;
+}
+/**
+ * One footer ACTION. Deliberately not a `CascaderNode`, so a command can never
+ * be passed where an option is expected and join the ring, filter or selection.
+ */
+export interface CascaderActionItem {
+    /** Stable key. Falls back to the label when it is a string, then the index. */
+    value?: string;
+    label: React.ReactNode;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+    /** Ignored when `items` is present - a flyout opens instead. */
+    onSelect?: () => void;
+    /** Turns the row into a submenu trigger. One level deep on purpose. */
+    items?: CascaderActionItem[];
+    /** Consecutive entries sharing a heading are drawn under one. */
+    group?: string;
+}
+/** Panel layout. See the docs for the keyboard map of each. */
+export type CascaderMode = 'drill' | 'columns' | 'tree';
+export type CascaderSearchScope = 'level' | 'deep';
+/**
+ * Which nodes may be committed. The predicate arm is generic over the payload
+ * rather than quantified per call: a per-call `<T>` would force every predicate
+ * to accept EVERY payload, so `(node: CascaderNode<Member>) => boolean` could
+ * never satisfy it.
+ */
+export type CascaderSelectable<T = unknown> = 'leaf' | 'any' | ((node: CascaderNode<T>) => boolean);
+export type CascaderCollapse = 'middle' | 'start' | 'none';
+export type CascaderValueDisplay = 'path' | 'leaf' | 'count';
+export type CascaderChangeReason = 'select' | 'deselect' | 'clear';
+/** Second argument to `onValueChange`: resolved nodes, so no re-lookup. */
+export interface CascaderChangeDetails<T = unknown> {
+    /** The node committed or toggled. Null when the selection was cleared. */
+    node: CascaderNode<T> | null;
+    /** Ancestor chain of `node`, root first, node last. */
+    path: CascaderNode<T>[];
+    nodes: CascaderNode<T>[];
+    reason: CascaderChangeReason;
+}
+/** Normalized tree, built once per `items` identity, shared by every mode. */
+export interface CascaderIndex<T = unknown> {
+    byValue: Map<string, CascaderNode<T>>;
+    /** Children by parent value. Root children are keyed by `ROOT_KEY`. */
+    childrenOf: Map<string, CascaderNode<T>[]>;
+    parentOf: Map<string, string | null>;
+    /** Zero-based depth by node value. */
+    depthOf: Map<string, number>;
+    /** Top level nodes, in input order. */
+    roots: CascaderNode<T>[];
+    /** Every node in a stable, depth-first order. Used by deep search. */
+    all: CascaderNode<T>[];
+}
+export interface CascaderFlatNode<T = unknown> {
+    node: CascaderNode<T>;
+    depth: number;
+    /** Known children, or a declared `hasChildren`. */
+    branch: boolean;
+    expanded: boolean;
+    /** Sibling count, plus one when the level has a paging row. */
+    setSize: number;
+    /** One-based index among siblings. */
+    posInSet: number;
+}
+/** One segment of a rendered path, after collapsing. */
+export type CascaderPathSegment<T = unknown> = {
+    type: 'node';
+    node: CascaderNode<T>;
+} | {
+    type: 'ellipsis';
+    hidden: CascaderNode<T>[];
+};
+/**
+ * Async load state for one node's children. Deliberately WITHOUT a `status`
+ * field: "declared a branch, never fetched" and "fetched and genuinely empty"
+ * are told apart by MAP MEMBERSHIP, and a second source of that truth would
+ * eventually disagree with the first.
+ */
+export interface CascaderLoadState {
+    loading: boolean;
+    error: boolean;
+    hasMore: boolean;
+    /** Opaque cursor handed back to `getChildren` for the next page. */
+    cursor?: string;
+}
+/** Why a level was fetched. `resolve`: `resolveValue` hit an unloaded node. */
+export type CascaderLoadReason = 'level' | 'more' | 'prefetch' | 'retry' | 'resolve';
+/** Argument handed to `getChildren`. */
+export interface CascaderLoadContext {
+    /** Aborted when the request is superseded or the popup closes. */
+    signal: AbortSignal;
+    cursor?: string;
+    reason?: CascaderLoadReason;
+}
+/** Value returned by `getChildren`. A bare array is also accepted. */
+export interface CascaderLoadResult<T = unknown> {
+    items: CascaderNode<T>[];
+    nextCursor?: string;
+    /** Defaults to whether `nextCursor` was supplied. */
+    hasMore?: boolean;
+}
+/** Argument handed to `onSearch`. */
+export interface CascaderSearchContext {
+    signal: AbortSignal;
+    /** The path the user is searching within, deepest last. */
+    path: string[];
+}
+/**
+ * Every user facing string, so the primitive ships no hardcoded copy. The
+ * callbacks take plain labels, not nodes: a `CascaderNode<T>` parameter would
+ * force this object to carry the item generic. `*Announcement` is live-region.
+ */
+export interface CascaderLabels {
+    search: string | ((parentLabel?: string) => string);
+    back: string;
+    /** A level's FIRST page. `loadingMore` is the next, `loadMore` its idle row. */
+    loading: string;
+    loadingMore: string;
+    loadMore: string;
+    error: string;
+    retry: string;
+    empty: string;
+    /** Rendered by `CascaderValue` when `display="count"`. */
+    selectedCount: (count: number) => string;
+    breadcrumbLabel: string;
+    chipsLabel: string;
+    removeChip: (label: string) => string;
+    /** Trail separator. Not every locale writes one with a slash. */
+    pathSeparator: string;
+    /** Names the root level wherever there is no parent node to name it. */
+    rootLevel: string;
+    itemCount: (count: number) => string;
+    /** Appended to a branch row's name outside tree mode: it opens another list. */
+    branchAffordance: string;
+    /** Columns-trail rows are plain buttons, so they carry no `aria-selected`. */
+    selectedState: string;
+    /** Same for the mixed state, which a `role="button"` row may not carry. */
+    partiallySelectedState: string;
+    columnsLabel: string;
+    actionsLabel: string;
+    submenuAffordance: string;
+    panelLabel: string;
+    /** Read per mode AND per direction: the level keys mirror in RTL. */
+    keyboardHint: (mode: CascaderMode, dir: 'ltr' | 'rtl') => string;
+    rootAnnouncement: (count: number) => string;
+    expandedAnnouncement: (label: string, count: number) => string;
+    collapsedAnnouncement: (label: string) => string;
+    levelAnnouncement: (parentLabel: string, depth: number, count: number) => string;
+    resultsAnnouncement: (count: number) => string;
+    maxReachedAnnouncement: (max: number) => string;
+    /** `count` is the descendants swept along; `selecting` is the direction. */
+    cascadeAnnouncement: (label: string, count: number, selecting: boolean) => string;
+    searchingAnnouncement: string;
+}

package/dist/components/reui/cascader/cascader-virtual.d.ts ADDED Viewed

@@ -0,0 +1,62 @@
+import { Virtualizer } from '@tanstack/react-virtual';
+import { CascaderColumn } from '../../../components/reui/cascader/cascader-context';
+import * as React from 'react';
+/**
+ * Windowing for the cascader, in its own file so the primitive's own install
+ * never pulls `@tanstack/react-virtual` in. Base UI forces three rules:
+ *
+ * 1. A windowed row MUST carry an explicit `index`; the fallback
+ *    `findItemIndex` is O(n) per row and returns `-1` on the frame a level swap
+ *    renders empty, dangling `aria-activedescendant`.
+ * 2. That index is DESTRUCTIVE while unvirtualized (`useCompositeListItem`
+ *    skips registration, `CompositeList` truncates `elementsRef` to zero and
+ *    the first arrow key highlights nothing), so rows stay plain until the root
+ *    flips `virtualized`, gated inside `CascaderItem`.
+ * 3. No `Combobox.Collection` and no FUNCTION CHILD on `Combobox.List`, which
+ *    implicitly wraps one in a Collection: a Collection renders every filtered
+ *    item.
+ */
+export interface UseCascaderVirtualizerOptions {
+    count: number;
+    getScrollElement: () => HTMLElement | null;
+    estimateSize?: number;
+    overscan?: number;
+    /** Key rows by node value, never by index: a tree expand shifts every index. */
+    getItemKey: (index: number) => string | number;
+    /** Render index of the highlighted row, or `-1`. Pinned into the window. */
+    activeIndex?: number;
+}
+export type CascaderVirtualizer = Virtualizer<HTMLElement, HTMLElement>;
+/**
+ * The cascader's virtualizer: TanStack plus the highlight pinning and
+ * scroll-into-view a combobox list needs. `activeIndex` is clamped here, not by
+ * the caller: emitted from a layout effect, it can be one commit ahead of a
+ * level that just shrank and would otherwise scroll to a row that is gone.
+ */
+export declare function useCascaderVirtualizer({ count, getScrollElement, estimateSize, overscan, getItemKey, activeIndex, }: UseCascaderVirtualizerOptions): CascaderVirtualizer;
+export interface CascaderVirtualItemsProps {
+    /** Row height before measurement. Defaults to the root `estimateRowSize`. */
+    estimateSize?: number;
+    /** Rows rendered beyond each edge. Defaults to the root `overscan`. */
+    overscan?: number;
+}
+/**
+ * Windowed replacement for `CascaderItems`, dropped inside `CascaderList`. The
+ * registration is a LAYOUT effect because the root derives `virtualized` from
+ * it and the flip has to land before the browser paints. Until the root has
+ * seen it, this renders exactly what `CascaderItems` does, so no frame carries
+ * indexed rows while Base UI still owns the composite list.
+ */
+declare function CascaderVirtualItems(props: CascaderVirtualItemsProps): React.JSX.Element;
+export interface CascaderVirtualColumnProps extends CascaderVirtualItemsProps {
+    column: CascaderColumn;
+}
+/**
+ * Windowed replacement for one Miller column, passed through the
+ * `CascaderColumns` render slot. One virtualizer PER COLUMN, since columns
+ * scroll independently, and only the deepest is Base UI's listbox: the trail
+ * behind is `as="button"` rows outside Base UI, so it windows on its own row
+ * count rather than waiting for the root to flip.
+ */
+declare function CascaderVirtualColumn({ column, estimateSize, overscan }: CascaderVirtualColumnProps): React.JSX.Element;
+export { CascaderVirtualColumn, CascaderVirtualItems };