@sheetxl/grid-react 0.7.28-beta.4 → 0.8.0-beta.10

package/types/src/layer/StickyPortal.d.ts

@@ -0,0 +1,73 @@
+import { default as React } from 'react';
+import { FloatPopperProps } from '@sheetxl/utils-react';
+import { StickyState } from './StickyAnchor';
+import { GridAnchor, GridPlacement, GridBoundary, GridWhenOff, GridWhenPartial } from './useGridAnchor';
+/** The lifecycle a {@link StickyPortal} reports — {@link FloatPopper}'s. */
+export type StickyPortalLifecycle = Pick<FloatPopperProps, 'onMount' | 'onOpening' | 'onOpen' | 'onClosing' | 'onClose'>;
+/**
+ * Props for {@link StickyPortal}.
+ */
+export interface StickyPortalProps extends StickyPortalLifecycle {
+    /** WHERE to anchor — a grid coordinate (range / cell / bounds / edge / point). */
+    anchor: GridAnchor;
+    /** Which side + align the float attaches to. @defaultValue `{ side: 't', align: 'center' }` */
+    placement?: GridPlacement;
+    /** What happens when the anchor leaves the data area. @defaultValue 'hide' */
+    whenOff?: GridWhenOff;
+    /**
+     * What happens, per axis, while the range is partly obstructed — in view, but the anchored edge is
+     * not. @defaultValue `{ side: 'flip', align: 'slide' }`
+     */
+    whenPartial?: GridWhenPartial;
+    /**
+     * Where the float may LIVE — one rect, resolved by {@link GridBoundary}: it is both the anchor's
+     * clip / clamp boundary and the rect `flip` / `shift` collide against. @defaultValue 'data'
+     */
+    boundary?: GridBoundary;
+    /** Px overlap below which a geometried anchor reads as clipped. @defaultValue 0 */
+    minVisible?: number;
+    /** Gap (px) between the anchor edge and the float. @defaultValue 4 */
+    offset?: number;
+    /**
+     * Offset (px) along the anchor EDGE — only applies to `start` / `end` alignment (a centered float has
+     * no edge to slide along). Positive insets the float inward from the corner. @defaultValue 0
+     */
+    alignOffset?: number;
+    /** Controlled visibility (e.g. a hover tooltip). @defaultValue true */
+    open?: boolean;
+    /** Portal container. @defaultValue the fullscreen-aware root (`useFullscreenPortal`). */
+    container?: Element;
+    className?: string;
+    style?: React.CSSProperties;
+    /** The stacking band — a number, or a `zIndexVar` expression. @defaultValue `zIndexVar('grid')` */
+    zIndex?: number | string;
+    /**
+     * Whose theme the float wears: the anchor's (`'anchor'` — a grid label themes with its grid, even where
+     * the grid's mode differs from the app's) or the app's (`'provider'` — chrome, such as a gesture
+     * readout). @defaultValue 'anchor'
+     */
+    themeFrom?: 'provider' | 'anchor';
+    /**
+     * Drawn **instead of** the child while the anchored range has no visible portion (`state.outOfView`) —
+     * the presence left behind under `whenOff: 'clamp'`: an edge marker, a "go to range" pill. Without it
+     * the child itself is drawn, clamped to the edge.
+     */
+    renderOffscreen?: (state: StickyState) => React.ReactNode;
+    /** The float content — a node, or a render function `(state) => node` (e.g. to react to `slid`). */
+    children?: React.ReactNode | ((state: StickyState) => React.ReactNode);
+}
+/**
+ * The **portal renderer** of the grid float family: a {@link StickyAnchor} whose child is drawn by
+ * {@link FloatPopper} at the resolved anchor, in a **portal** (escaping the pane clip, so it can flow past
+ * the pane bounds — e.g. overhang a freeze line). The common case — `<StickyPortal anchor={{ range }}>
+ * A1:B4</StickyPortal>` — with no hand-written positioner. For an in-grid (clipping) label, use
+ * `<StickyAnchor>` with a plain `<div>` child instead.
+ *
+ * @remarks
+ * The resolver (`StickyAnchor`) decides WHERE — the owner pane, the live client rect, the boundary and the
+ * clip / clamp / slide state; the positioner (`FloatPopper`, the same one app menus use) decides how the
+ * box fits there. Both kinds of grid float — a persistent `RangeFloat` and a hover `RangeTooltip` — are
+ * one of these; what differs is who opens and closes them.
+ */
+export declare const StickyPortal: React.FC<StickyPortalProps>;
+//# sourceMappingURL=StickyPortal.d.ts.map

package/types/src/layer/TooltipProvider.d.ts

@@ -0,0 +1,101 @@
+import { default as React } from 'react';
+import { GridPlacement } from './useGridAnchor';
+import { HoverTipProps } from './useHoverIntent';
+/**
+ * The dwell timing of the tooltip group — MUI's model.
+ */
+export interface TooltipTiming {
+    /** Dwell (ms) over a target before the first tip shows. @defaultValue 300 */
+    enterDelay: number;
+    /** Dwell (ms) while the group is **armed** (a tip closed within {@link armedFor}) — the next tip is instant. @defaultValue 0 */
+    enterNextDelay: number;
+    /** The window (ms) after a close in which the next open is fast — MUI's hysteresis. @defaultValue 800 */
+    armedFor: number;
+    /** The linger (ms) after leaving before a tip hides — lets the pointer cross onto an interactive tip, and a tip does not vanish the moment the pointer leaves the grid. @defaultValue 400 */
+    leaveDelay: number;
+}
+export declare const DEFAULT_TOOLTIP_TIMING: TooltipTiming;
+/** What the host's tooltip bubble is handed. */
+export interface TooltipRenderProps {
+    /** The tip's content. */
+    children: React.ReactNode;
+    /** The edge the tip hangs on — for an arrow. */
+    placement: GridPlacement;
+    /** Whether the tip stays open while the pointer is on it (and so takes the pointer at all). */
+    interactive: boolean;
+    /** Spread onto the bubble root: the keep-open handlers and the element registration. */
+    tipProps: HoverTipProps;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** The bubble around a tip's content — the host's chrome, arrow and theme. */
+export type RenderTooltip = (props: TooltipRenderProps) => React.ReactNode;
+/**
+ * A tip registered with its {@link TooltipGroup}. One per `useHoverIntent`; the per-pane copies of a
+ * layer share a `key`, so they count as one tip.
+ */
+export interface TooltipClient {
+    /** Identity: the copies of one tip share it; two tips on the same cell do not. */
+    readonly key: string;
+    /**
+     * A gesture tip holds the group: hover tips may not open while it is up. It is not closed by a press
+     * or a key (its gesture's modifiers), and its close does not arm the group.
+     */
+    readonly gesture: boolean;
+    /** The tip's element once mounted — a pointerdown inside it does not close it. */
+    getElement(): Element | null;
+    /** Close now, no grace (the group took the slot, or the user pressed / typed). */
+    forceClose(): void;
+}
+/**
+ * The single-open coordinator: at most one tip (by key) is up at a time, the next open is fast for
+ * {@link TooltipTiming.armedFor} after a close, a gesture tip preempts hover, and any pointerdown or
+ * keydown closes an open hover tip (a gesture tip closes with its gesture). Owned by the top {@link TooltipProvider} (or one that `isolate`s);
+ * a built-in default serves a tree with no provider.
+ */
+export interface TooltipGroup {
+    /** `client` is opening: every client open on another key closes first, with no grace. */
+    claim(client: TooltipClient): void;
+    /** `client` closed. The group arms when the last client on the open key releases. */
+    release(client: TooltipClient): void;
+    /** A tip closed less than `armedFor` ms ago. */
+    isArmed(armedFor: number): boolean;
+    /** A gesture tip is up. */
+    isHeld(): boolean;
+    /** Close every open tip now. */
+    closeAll(): void;
+}
+export declare const createTooltipGroup: () => TooltipGroup;
+/** The ambient tooltip configuration a tip reads. */
+export interface TooltipSurface {
+    timing: TooltipTiming;
+    /** The host's bubble; `undefined` = the grid's plain default. */
+    renderTooltip?: RenderTooltip;
+    group: TooltipGroup;
+}
+/**
+ * The ambient {@link TooltipSurface}. Works with no provider: MUI timing, the plain bubble and a shared
+ * default group.
+ */
+export declare const useTooltipSurface: () => TooltipSurface;
+export interface TooltipProviderProps {
+    /** Override any of the dwell timings; the rest are inherited. */
+    timing?: Partial<TooltipTiming>;
+    /** The bubble tips in this subtree open in. Inherited when omitted. */
+    renderTooltip?: RenderTooltip;
+    /**
+     * Own a separate single-open group for this subtree instead of sharing the enclosing one. The top
+     * provider (no enclosing one) always owns a group.
+     */
+    isolate?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * Configures the grid's tooltips for a subtree: the dwell timing, the bubble (`renderTooltip`, the way
+ * `FloatProvider` takes `renderFloatPanel`) and the single-open group. Nested providers override only
+ * what they are given and inherit the rest; a hook outside any provider gets the built-in defaults.
+ */
+export declare const TooltipProvider: React.FC<TooltipProviderProps>;
+/** The grid's default bubble — used when no provider supplies `renderTooltip`. */
+export declare const renderDefaultTooltip: RenderTooltip;
+//# sourceMappingURL=TooltipProvider.d.ts.map

package/types/src/layer/index.d.ts

@@ -1,11 +1,15 @@
 export * from './LayerTypes';
 export * from './Layer';
 export * from './VirtualDiv';
-export type { GridAnchor, GridPlacement, GridWhenOff, GridBoundary, GridFloatSide, GridAlign, GridSlide } from './useGridAnchor';
+export type { GridAnchor, GridAnchorReference, GridPlacement, GridWhenOff, GridWhenPartial, GridPartialPolicy, GridBoundary, GridFloatSide, GridAlign, GridSlide } from './useGridAnchor';
 export * from './StickyAnchor';
-export * from './StickyFloat';
+export * from './StickyPortal';
+export * from './GridFloatPanel';
+export * from './TooltipProvider';
 export * from './useHoverIntent';
-export * from './useRangeHover';
-export * from './HoverTipLayer';
+export * from './RangeFloatLayer';
+export * from './RangeTooltipLayer';
+export * from './GestureTip';
 export * from './RangePrompt';
+export * from './RangeTooltip';
 //# sourceMappingURL=index.d.ts.map

package/types/src/layer/useGridAnchor.d.ts

@@ -25,6 +25,27 @@ export interface GridPlacement {
  *   the owner becomes the pane under the clamped pixel and {@link GridAnchorResolved.slid} is set.
  */
 export type GridWhenOff = 'hide' | 'clamp';
+/**
+ * What a float does on ONE axis while the range is **partly obstructed** — in view, but the edge the
+ * float hangs on is not (scrolled under a frozen pane, a header, or the window edge).
+ *
+ * - `'slide'` — the anchor pixel rides the visible edge, over the obstruction, until the range is
+ *   fully out ({@link GridAnchorResolved.slid} reports how far).
+ * - `'flip'` — the float moves to the **opposite edge of the range** when that edge is in view (the
+ *   resolved {@link GridAnchorResolved.placement} reports it); slides when neither edge is. Meaningless
+ *   for a `center` align, which slides.
+ * - `'hide'` — the range counts as out of view as soon as the anchored edge is obstructed.
+ */
+export type GridPartialPolicy = 'slide' | 'flip' | 'hide';
+/**
+ * The {@link GridPartialPolicy} per axis: `side` governs the axis the float sits on (its `side`), `align`
+ * the axis it is aligned along.
+ * @defaultValue `{ side: 'flip', align: 'slide' }`
+ */
+export interface GridWhenPartial {
+    side?: GridPartialPolicy;
+    align?: GridPartialPolicy;
+}
 /**
  * How far the anchor pixel was pushed to stay in frame (the `clamp` fallback). Handed to the sticky
  * child so it can render differently when slid — an arrow toward the true (off-frame) anchor, etc.
@@ -60,15 +81,22 @@ export type GridAnchor = {
     point: Point;
 };
 /**
- * The clip / clamp boundary — a **rect fed to the positioning math**, NOT a DOM parent. This is how
- * "don't slide under the headers" is expressed: clamp to the data viewport.
+ * The clip / clamp boundary — a **rect fed to the positioning math**, NOT a DOM parent. One prop, one
+ * meaning: *where may this thing live*. It governs the anchor's clip / clamp AND (via `StickyPortal`)
+ * where `flip` / `shift` may land the float. This is how "don't slide under the headers" is expressed:
+ * clamp to the data viewport.
+ *
+ * Every grid-derived boundary is further cut to the **browser window** (the layout viewport): a float
+ * the grid does not obscure can still run off the screen, so the edge is always the grid edge ∩ the
+ * window edge. An explicit {@link Bounds} is used verbatim.
  *
  * - `'data'` — the union of the panes' cell areas (headers excluded). Default.
  * - `'pane'` — just the resolving pane's cell area.
  * - `'grid'` — currently the same as `'data'` (until a surface/header rect is threaded).
+ * - `'viewport'` — the browser window alone: the opt-out, for a float that may cover grid chrome.
  * - a {@link Bounds} — an explicit **client-px** rect.
  */
-export type GridBoundary = 'data' | 'pane' | 'grid' | Bounds;
+export type GridBoundary = 'data' | 'pane' | 'grid' | 'viewport' | Bounds;
 /** A `DOMRect`-shaped plain object (works in Floating UI and in Node tests without a DOM). */
 export interface GridAnchorRect {
     x: number;
@@ -102,9 +130,31 @@ export interface GridAnchorResolved {
     /**
      * The anchor's range has **no visible portion** (fully scrolled off) — independent of `whenOff`. Unlike
      * {@link clipped} (which `clamp` forces false), this stays true under `clamp`, so a presence can tell
-     * "partially obstructed / clamped" (still show) from "off-screen" (show a goto affordance).
+     * "partially obstructed / clamped" (still show) from "off-screen" (show a goto affordance). A
+     * `whenPartial: 'hide'` axis also sets it once its edge is obstructed.
      */
     outOfView: boolean;
+    /**
+     * The placement **actually used** — the requested one, or its opposite on an axis a
+     * `whenPartial: 'flip'` moved to the range's other edge. What the float positions by.
+     */
+    placement: GridPlacement;
+}
+/**
+ * The Floating UI **virtual reference** for a grid anchor. Stable identity (so `autoUpdate` subscribes
+ * once), but both members read **live**.
+ */
+export interface GridAnchorReference {
+    /** The anchor's client rect, read live on every call (`autoUpdate` calls it between React renders). */
+    getBoundingClientRect: () => DOMRect;
+    /**
+     * The pane element. `autoUpdate` unwraps a virtual reference to *this* element and gates **every**
+     * DOM-side trigger on it — ancestor `scroll`, the `observeMove` layout-shift detector, element resize.
+     * Without it only the window `resize` listener survives, which is why the float used to need a 60fps
+     * `animationFrame` poll. A **getter**: the pane element only exists after mount, and resolving it
+     * lazily keeps this object's identity stable.
+     */
+    readonly contextElement?: Element;
 }
 /** The hook result: stable live accessors + render-time snapshot values. */
 export interface UseGridAnchorResult {
@@ -112,11 +162,14 @@ export interface UseGridAnchorResult {
      * A Floating UI **virtual reference** with **stable identity** — its `getBoundingClientRect` reads
      * the anchor **live** on every call (Floating UI's `autoUpdate` invokes it between React renders).
      */
-    reference: {
-        getBoundingClientRect: () => DOMRect;
-    };
+    reference: GridAnchorReference;
     /** Live accessor for the boundary rect (for `shift`/`flip`/`hide` limiters). */
     getBoundaryRect: () => DOMRect;
+    /**
+     * Live accessor for the placement's anchor pixel (client px) — the live counterpart of
+     * {@link anchorPoint}, for a child that positions itself on the point between React renders.
+     */
+    getAnchorPoint: () => Point;
     /** Render-time snapshot: anchor outside the boundary. Updates each scroll frame (pane re-render). */
     clipped: boolean;
     /** Render-time snapshot: which side the anchor is off, when clipped. */
@@ -129,17 +182,21 @@ export interface UseGridAnchorResult {
     slid: GridSlide | null;
     /** Render-time snapshot: the range is fully scrolled off (stays true under `clamp`; see resolved). */
     outOfView: boolean;
+    /** Render-time snapshot: the placement actually used (see {@link GridAnchorResolved.placement}). */
+    placement: GridPlacement;
     /** The pane the anchor resolves against (null outside a `GridPaneProvider`). */
     pane: IGridPane | null;
 }
 /** @internal The shared placement default (`StickyAnchor` and the resolver must agree on it). */
 export declare const DEFAULT_PLACEMENT: GridPlacement;
+/** @internal The shared partial-obstruction default: today's behavior made explicit. */
+export declare const DEFAULT_WHEN_PARTIAL: Required<GridWhenPartial>;
 /**
  * Resolve a {@link GridAnchor} to a client rect + clip state against a boundary. **Pure** (given a
  * pane) — no React, no live DOM beyond `getBoundingClientRect`, so it is directly unit-testable with a
  * fake {@link IGridPane}. Shared by {@link useGridAnchor} (the live closures call this per frame).
  */
-export declare const resolveGridAnchor: (pane: IGridPane | null, anchor: GridAnchor, boundary?: GridBoundary, minVisible?: number, placement?: GridPlacement, whenOff?: GridWhenOff) => GridAnchorResolved;
+export declare const resolveGridAnchor: (pane: IGridPane | null, anchor: GridAnchor, boundary?: GridBoundary, minVisible?: number, placement?: GridPlacement, whenOff?: GridWhenOff, whenPartial?: GridWhenPartial) => GridAnchorResolved;
 /**
  * Bridge a {@link GridAnchor} (grid coordinate) to a **live Floating UI virtual reference** plus clip
  * state. The pane already re-renders every layer on scroll (so the snapshot values update per frame),
@@ -153,5 +210,6 @@ export declare const useGridAnchor: (anchor: GridAnchor, options?: {
     minVisible?: number;
     placement?: GridPlacement;
     whenOff?: GridWhenOff;
+    whenPartial?: GridWhenPartial;
 }) => UseGridAnchorResult;
 //# sourceMappingURL=useGridAnchor.d.ts.map

package/types/src/layer/useHoverIntent.d.ts

@@ -2,13 +2,39 @@
  * Options for {@link useHoverIntent}.
  */
 export interface UseHoverIntentOptions {
-    /** Dwell (ms) over a target before opening — kills pass-through flicker. @defaultValue 300 */
+    /**
+     * Dwell (ms) over a target before opening — kills pass-through flicker.
+     * @defaultValue the tooltip group's `enterDelay` (300), or its `enterNextDelay` (0) while armed
+     */
     openDelay?: number;
-    /** Grace (ms) after leaving before closing — lets the pointer cross the gap to the float. @defaultValue 150 */
+    /**
+     * Grace (ms) after leaving before closing — lets the pointer cross the gap to the float.
+     * @defaultValue the tooltip group's `leaveDelay` (400)
+     */
     closeDelay?: number;
+    /**
+     * Join the grid's tooltip group: one tip open at a time, a fast re-open while armed, closed by any
+     * pointerdown or key, refused while a gesture tip is up. `false` for a hover-opened float that is not
+     * a tooltip — a table toolbar, a note's box — which must survive a tip opening beside it.
+     * @defaultValue true
+     */
+    group?: boolean;
+    /**
+     * The tip's identity in the group. A layer rendered once per pane passes one name so its copies count
+     * as ONE tip (they aim and open in lockstep); two layers on the same cell must differ.
+     * @defaultValue this hook instance
+     */
+    name?: string;
+    /**
+     * A gesture readout: opens at once (no dwell) and holds the group, so no hover tip can open until it
+     * closes. @defaultValue false
+     */
+    gesture?: boolean;
 }
 /** Props to spread onto the floated element so hovering IT keeps the float open. */
 export interface HoverTipProps {
+    /** Registers the element with the tooltip group, so a press inside an interactive tip does not close it. */
+    ref: React.RefCallback<Element>;
     onPointerEnter: () => void;
     onPointerLeave: () => void;
     style: React.CSSProperties;
@@ -37,13 +63,14 @@ export interface UseHoverIntentResult {
     close: () => void;
 }
 /**
- * The reusable **hover-intent state machine** behind a hover tooltip — delays + keep-open-on-tip-hover,
- * with NO hit-testing of its own. Feed it a target key via {@link UseHoverIntentResult.setTarget}
- * (`null` = nothing) and it debounces open / close; spread {@link UseHoverIntentResult.tipProps} on the
- * float so moving onto the float itself keeps it open.
+ * The **hover-intent state machine** behind a tip — the per-tip client of the grid's tooltip group
+ * ({@link TooltipProvider}): dwell / grace timing, keep-open-on-tip-hover, and the group's rules
+ * (single open, armed re-open, gesture preempts hover, closed by a press or a key). It does NO
+ * hit-testing: feed it a target key via {@link UseHoverIntentResult.setTarget} (`null` = nothing) and
+ * spread {@link UseHoverIntentResult.tipProps} on the float.
  *
- * {@link useRangeHover} wraps this with a pointer responder against a fixed range; a dynamic consumer
- * (e.g. an error layer discovering the hovered cell) drives `setTarget` itself.
+ * `RangeFloatLayer` drives it from a probe; a dynamic consumer (a layer discovering the hovered note)
+ * drives `setTarget` itself.
  */
 export declare const useHoverIntent: (options?: UseHoverIntentOptions) => UseHoverIntentResult;
 //# sourceMappingURL=useHoverIntent.d.ts.map

package/types/src/list/CheckboxList.d.ts

@@ -1,7 +1,14 @@
 import { default as React } from 'react';
 import { ISelection } from '../selection';
+import { ListProps } from './List';
 export interface CheckboxListAttributes {
     isCheckboxList: () => true;
+    /** The highlighted row, or `-1` when the list is empty. */
+    getHighlightIndex: () => number;
+    /** Move the highlight `delta` rows (clamped to the list) and bring it into view. */
+    moveHighlight: (delta: number) => void;
+    /** Toggle the selected rows, as Space does: the anchor's opposite, applied to every one of them. */
+    toggleHighlighted: () => void;
 }
 export interface ICheckboxListElement extends HTMLDivElement, CheckboxListAttributes {
 }
@@ -13,6 +20,11 @@ export interface CheckboxListProps extends React.HTMLAttributes<HTMLDivElement>
     itemCount: number;
     /** Whether the item at `index` is checked. */
     isChecked: (index: number) => boolean;
+    /**
+     * Whether the item at `index` is partly checked: a row standing for several values (a group)
+     * with some of them checked. Drawn as the tri-state; the row still toggles to `!isChecked`.
+     */
+    isIndeterminate?: (index: number) => boolean;
     /**
      * Set `indices` to `checked`. Called with a single index on a click, every selected row on a keyboard
      * toggle (Space/Enter), and every row from `(Select All)`. The caller maps `index` to its own store.
@@ -32,15 +44,24 @@ export interface CheckboxListProps extends React.HTMLAttributes<HTMLDivElement>
     renderDivider?: () => React.ReactNode;
     /**
      * Show a tri-state **(Select All)** header with this label. It operates over *all* rows — which in a
-     * filtered list are the filtered ones, so it's "Select all (filtered)" automatically.
+     * filtered list are the filtered ones, so it's "Select all (filtered)" automatically. It sits
+     * above the rows, outside the scroll, so it never leaves the view.
      */
     selectAllLabel?: React.ReactNode;
+    /** The header's accessible name and tooltip, when its label does not say what it is (a count). */
+    selectAllTitle?: string;
+    /** The Select All row's own attributes (a surface, a class), over its defaults. */
+    propsSelectAll?: React.HTMLAttributes<HTMLDivElement>;
     /** Uniform row height in px. @defaultValue 24 */
     itemHeight?: number;
     /** Selection model (highlight + Arrow nav). Created internally if omitted. */
     selection?: ISelection;
     /** Content cache-bust; bump when checked state changes without `isChecked`'s identity changing. */
     cacheToken?: unknown;
+    /** See `ListSurfaceProps.autoFocus`. */
+    autoFocus?: boolean;
+    /** See `ListSurfaceProps.viewport`. */
+    viewport?: ListProps['viewport'];
     /** Ref for the Element. */
     ref?: React.Ref<ICheckboxListElement>;
 }

package/types/src/list/List.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { ISelection } from '../selection';
+import { ListSurface } from './ListSurface';
 export interface ListAttributes {
     isList: () => true;
 }
@@ -36,20 +37,28 @@ export interface ListProps extends React.HTMLAttributes<HTMLDivElement> {
      * *rendered* content changed without `renderItem`'s identity changing.
      */
     cacheToken?: unknown;
+    /** See `ListSurfaceProps.scrollTo`. */
+    scrollTo?: {
+        row: number;
+    } | null;
+    /** See `ListSurfaceProps.autoFocus`. */
+    autoFocus?: boolean;
+    /** See `ListSurfaceProps.viewport`. */
+    viewport?: React.ComponentProps<typeof ListSurface>['viewport'];
     /** Ref for the Element. */
     ref?: React.Ref<IListElement>;
 }
 /**
- * A virtualized **list** built on `GridSurface` with the grid's own layers — a `CellLayer` for the
- * items and a `SelectionLayer` for the active-row highlight + Arrow keys (the same shape as the editor
- * demo: a model passed to layers as props).
+ * A virtualized **list** of arbitrary React content, built on {@link ListSurface} — which is the
+ * grid's own machinery (a `CellLayer` for the items and a `SelectionLayer` for the active-row
+ * highlight + Arrow keys) dressed as a list.
  *
  * @remarks
  * The List's whole state is its {@link ListProps.selection}; it has no per-item callbacks and no notion
  * of "checked" or "toggle". Pointer selection is the `SelectionLayer`'s job (it hit-tests the pointer),
  * so the cells are inert, transparent content; the keyboard is the caller's via {@link ListProps.onKeyDown}.
- * The active row fills (no Excel anchor hole) and carries an inset ring, since the anchor is the live
- * Space/scroll target. See {@link CheckboxList} for the checkbox-list specialization.
+ * See {@link CheckboxList} for the checkbox-list specialization and {@link PickList} for the
+ * single-choice text list.
  */
 export declare const List: React.ForwardRefExoticComponent<Omit<ListProps, "ref"> & React.RefAttributes<IListElement>>;
 //# sourceMappingURL=List.d.ts.map

package/types/src/list/ListSearch.d.ts

@@ -0,0 +1,52 @@
+import { default as React } from 'react';
+/**
+ * Props for {@link ListSearch}.
+ */
+export interface ListSearchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange'> {
+    /** The search text. */
+    value: string;
+    /** The search text changed — including to `''` when Escape clears it. */
+    onChange: (value: string) => void;
+    /** Escape on an empty field: the search has nothing left to clear, so the host closes. */
+    onClose?: () => void;
+    /**
+     * The name of the clear button shown in the field while it holds text (its tooltip and
+     * accessible name). Without one the button is unnamed, not absent.
+     */
+    clearLabel?: string;
+    /**
+     * In place of the search glyph inside the field: a control over the search itself (a menu of
+     * its options, drawn with {@link ListSearchGlyph}). The default is the glyph alone.
+     */
+    glyph?: React.ReactNode;
+    /** Shown before the field, on its line: an action over the rows in view. */
+    leading?: React.ReactNode;
+    /** Shown after the field, on its line: an action on the typed text (an Add). */
+    trailing?: React.ReactNode;
+    /** Ref for the input. */
+    ref?: React.Ref<HTMLInputElement>;
+}
+/**
+ * The rows of `items` whose `text` contains `query`, ignoring case. An empty query keeps every row.
+ */
+export declare const filterByText: <T extends {
+    text: string;
+}>(items: readonly T[], query: string) => readonly T[];
+/** The search glyph: a magnifier, drawn in the current color. */
+export declare const ListSearchGlyph: (props: {
+    className?: string;
+}) => React.ReactElement;
+/**
+ * The **search field** shown above a list ({@link PickList}, `CheckboxList`): a plain input that
+ * narrows the rows as typed, a search glyph before the text and a clear button after it while
+ * there is text. Filtering itself is the host's, with {@link filterByText}.
+ *
+ * @remarks
+ * Escape clears the text first and closes only when there is none left, so a mistyped search is
+ * one key from a full list and two from a closed one. The clear button does the first of those
+ * without taking the focus, as the next thing typed is usually another search. Every other key
+ * is the host's through `onKeyDown`, which is how the arrows and Enter reach the list while the
+ * field keeps focus.
+ */
+export declare const ListSearch: React.ForwardRefExoticComponent<Omit<ListSearchProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+//# sourceMappingURL=ListSearch.d.ts.map

package/types/src/list/ListSurface.d.ts

@@ -0,0 +1,93 @@
+import { default as React } from 'react';
+import { Viewport } from '@sheetxl/utils-react';
+import { CellLayerProps, CellRendererProps } from '../cell';
+import { LayerEventProps } from '../layer';
+import { ISelection } from '../selection';
+/**
+ * Props for {@link ListSurface}.
+ */
+export interface ListSurfaceProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Number of rows. */
+    itemCount: number;
+    /**
+     * Render one row, as a grid cell — the `CellLayer` renderer, so the row is handed its bounds, its
+     * pane (zoom) and its resolved `value`. The cell is positioned and clipped by the tiling engine.
+     */
+    renderCell: (props: CellRendererProps) => React.ReactNode;
+    /**
+     * Resolve the visible rows to render (and their `value`). Omit to render every visible row with no
+     * pre-resolved value — `renderCell` then derives its content from the row index.
+     */
+    getVisibleCells?: CellLayerProps['getVisibleCells'];
+    /**
+     * Uniform row height in px. Also the list's natural height (`itemCount * itemHeight`) unless
+     * `style.height` overrides it. @defaultValue 24
+     */
+    itemHeight?: number;
+    /**
+     * Width the **column** should be, in px — the list sizes itself to this PLUS its own chrome (the
+     * vertical scrollbar's gutter), so the column actually ends up this wide.
+     *
+     * @remarks
+     * The distinction matters because the natural thing to pass — a measured content width, e.g.
+     * `ICellRange.getBestFit().width` — describes the column, not the box. Setting it as the box's
+     * `width` instead silently hands the gutter's worth of pixels back, and content sized to fit
+     * exactly then does not. Omit to size from `style` and let the column take what is left.
+     */
+    contentWidth?: number;
+    /**
+     * The selection model — the active-row highlight + Arrow-key navigation. The surface's *state*.
+     * Owned by the caller (so it can read what's selected); a private one is created when omitted.
+     */
+    selection?: ISelection;
+    /**
+     * Event taps installed as the list's TOP layer — so they are offered keys and pointers before the
+     * built-in Arrow navigation and before the selection's own hit test. Handle Space/Enter here (the
+     * grid would otherwise consume them) and `stopPropagation` to override; anything you don't consume
+     * falls through to navigation.
+     */
+    propsLayer?: LayerEventProps;
+    /** Take focus on mount, so the Arrow keys work without a click first. @defaultValue false */
+    autoFocus?: boolean;
+    /**
+     * Whether the vertical scrollbar (and its gutter) is drawn. `'auto'` draws it only while the rows
+     * overflow the box — a list that fits has nothing to scroll and the gutter would only widen it,
+     * and one squeezed by its host (a popup capped to the window) scrolls as a plain list does.
+     * @defaultValue 'auto'
+     */
+    showScrollbar?: boolean | 'auto';
+    /**
+     * Bring `row` into view. Read by identity: a new object scrolls again, the same object does not, so
+     * a caller keeps one per intent (the row highlighted on open, the row a key moved to). The scroll
+     * waits for the surface to have a size, so it can be set before the first paint.
+     */
+    scrollTo?: {
+        row: number;
+    } | null;
+    /**
+     * The scroll state, when the caller owns it — a host that sizes the list itself (`setSizes`) or
+     * drives its scroll. A private one is created when omitted.
+     */
+    viewport?: Viewport;
+    /** Opaque content cache-bust forwarded to the `CellLayer`. */
+    cacheToken?: unknown;
+    /** Ref for the Element. */
+    ref?: React.Ref<HTMLDivElement>;
+}
+/**
+ * The **list chrome**: a virtualized single-column `GridSurface` wearing the grid's own layers — a
+ * `CellLayer` for the rows and a `SelectionLayer` for the active-row highlight + Arrow keys — dressed
+ * so it reads as a list rather than a grid.
+ *
+ * @remarks
+ * Not a list *component*: it renders no row content of its own, has no notion of an item, and adds no
+ * padding — {@link ListSurfaceProps.renderCell} owns the whole row box. It exists because the lists
+ * built on it ({@link List}, whose rows are arbitrary React, and {@link PickList}, whose rows are text)
+ * differ ONLY in that renderer. Everything they share — the viewport, the measured single column, the
+ * selection styling and its rationale, the layer order — is here, once.
+ *
+ * The single column tracks the measured content width, so a row spans the full list; scrolling is
+ * vertical only.
+ */
+export declare const ListSurface: React.ForwardRefExoticComponent<Omit<ListSurfaceProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=ListSurface.d.ts.map