@ixfx/components 0.15.5 → 0.16.0

package/dist/{grid-list-0e7snW6t.d.ts → grid-list-D6n7WH8l.d.ts}

@@ -1,13 +1,61 @@
-import { B as ListNativeDragStartEvent, I as ListDragPreviewRenderer, L as ListDragPreviewSourceResolver } from "./tree-component-C6UHO-w9.js";
-import { S as ListSearchController } from "./index-KN2MW_xD.js";
+import { L as ListDragPreviewRenderer, R as ListDragPreviewSourceResolver, V as ListNativeDragStartEvent } from "./tree-component-DgfkxmVY.js";
+import { a as ViewStateBase, t as GetViewStateOptions } from "./types-LU1u0CB8.js";
+import "./index-9ttcdwlL.js";
+import { S as ListSearchController } from "./index-Dr80Zdl6.js";
 import "./pan-text-CoYmt2qd.js";
 import { i as ListGroupChangeEvent, n as ListGroupBy, o as ListGroupInfo, s as ListGroupLabel, u as ListGroupToggleEvent } from "./grouping-CUKgmkMm.js";
 import { i as ListInteractionMode, l as ListSelectionMode } from "./list-selection-types-PjKdhF-a.js";
 import "./list-group-header.js";
-import "./list-native-drag-controller-O2Nruqpi.js";
+import "./list-native-drag-controller-D_UrXipS.js";
 import { i as TickledItem, n as TickledController } from "./tickled-controller-DodxD3eQ.js";
 import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost, html } from "lit";
 import { CommandRegistry } from "@clinth/ui-commands";
+//#region src/common/view-state/pending.d.ts
+/**
+ * Pure helpers for *pending* view state: keyed intent that is waiting for a
+ * matching item to appear in the data.
+ *
+ * Pending sets / maps are insertion-ordered (oldest first) and capped so a
+ * long-running app with churning data can't grow them without bound.
+ */
+/** Default cap on pending keys per facet. Oldest entries are dropped first. */
+declare const MAX_PENDING_KEYS = 2000;
+type PendingKeys = ReadonlySet<string>;
+type PendingFlags = ReadonlyMap<string, boolean>;
+declare const EMPTY_KEYS: PendingKeys;
+declare const EMPTY_FLAGS: PendingFlags;
+/**
+ * Split `keys` into those `has` reports present (to apply now) and those
+ * still missing (to keep pending). Returns the input set untouched as
+ * `missing` when nothing matched, so callers can cheaply detect "no change".
+ */
+declare function partitionKeys(keys: PendingKeys, has: (key: string) => boolean): {
+  readonly present: readonly string[];
+  readonly missing: PendingKeys;
+};
+/** As {@link partitionKeys}, for keyed boolean flags (e.g. expanded / collapsed). */
+declare function partitionFlags(flags: PendingFlags, has: (key: string) => boolean): {
+  readonly present: ReadonlyArray<readonly [string, boolean]>;
+  readonly missing: PendingFlags;
+};
+/** Keep at most `max` keys, dropping the oldest. */
+declare function capKeys(keys: PendingKeys, max?: number): PendingKeys;
+/** Keep at most `max` flags, dropping the oldest. */
+declare function capFlags(flags: PendingFlags, max?: number): PendingFlags;
+/** `flags` without `key` (same instance when absent). */
+declare function withoutFlag(flags: PendingFlags, key: string): PendingFlags;
+/** JSON record → flags map. Non-boolean values are ignored. */
+declare function flagsFromRecord(record: Readonly<Record<string, boolean>> | undefined): PendingFlags;
+/**
+ * Combine pending and live flags into one JSON record. Live entries win when
+ * a key is in both (it shouldn't be — matched keys leave pending).
+ */
+declare function flagsToRecord(...sources: Array<Iterable<readonly [string, boolean]>>): Record<string, boolean>;
+/** Pending keys followed by live keys, de-duplicated, as a JSON array. */
+declare function keysToArray(...sources: Array<Iterable<string>>): string[];
+/** Map `keys` to `true` flags — for components that record a plain key set. */
+declare function keysAsFlags(keys: Iterable<string>, value?: boolean): Iterable<readonly [string, boolean]>;
+//#endregion
 //#region src/interaction/list-drag-select-controller.d.ts
 /** Surface-relative rectangle: origin at the scroll container's top-left. */
 type DragSelectRect = {
@@ -220,6 +268,29 @@ declare class ListSelectionController<T> {
    * fires once if anything changed.
    */
   removeKeys(keys: Iterable<string>, resolve: (key: string) => T | undefined): void;
+  /** Selected keys waiting for their items to appear. */
+  get pendingKeys(): PendingKeys;
+  /**
+   * Restore a selection by key: keys that resolve are selected now (one
+   * `onChange`), the rest are kept pending for `resolvePending()`. Replaces
+   * any previous selection and pending keys. Unlike `selectKeys`, this works
+   * in `selectionMode="none"` only to the extent of holding keys pending.
+   */
+  restoreKeys(keys: Iterable<string>, resolve: (key: string) => T | undefined): void;
+  /**
+   * Select pending keys whose items now resolve (call after items are added
+   * or rebuilt). Fires `onChange` once when anything was selected; returns
+   * whether it did.
+   */
+  resolvePending(resolve: (key: string) => T | undefined): boolean;
+  /**
+   * Silently deselect `items` that left the data, keeping their keys pending
+   * so they are re-selected if the same keys come back (data reset, re-fetch).
+   * No `onChange`; returns whether the selection changed.
+   */
+  demote(items: Iterable<T>): boolean;
+  /** Drop pending keys without touching the live selection. */
+  clearPending(): void;
   /** Route a click on `item` according to the current interaction mode. */
   handleClick(item: T, gesture: ListSelectionGesture): void;
   /** Route a Space keypress on `item` according to the current interaction mode. */
@@ -234,7 +305,8 @@ declare class ListSelectionController<T> {
   remap(fn: (item: T) => T): void;
   /**
    * Hard reset: empty the selection and clear the anchor without firing
-   * `onChange` (e.g. when all items are removed).
+   * `onChange` (e.g. when all items are removed). Keyed selected items become
+   * pending, so a rebuilt item set re-selects them via `resolvePending()`.
    */
   reset(): void;
   /**
@@ -404,6 +476,23 @@ interface GridListFullElementEventMap extends GridListElementEventMap {
   'list-native-drag-start': ListNativeDragStartEvent;
 }
 //#endregion
+//#region src/grid-list/grid-list-view-state.d.ts
+/**
+ * Pure view-state helpers for `ixfx-grid-list`. The component runs
+ * {@link reconcileGroups} whenever its item set or grouping changes, so a
+ * group's collapsed state survives the group disappearing (data reset,
+ * filter, streaming) and comes back when the group does. Scroll is captured
+ * and restored arithmetically from the virtual layout, along the main axis
+ * (`scrollLeft` in `row` orientation, `scrollTop` otherwise).
+ */
+/**
+ * `ixfx-grid-list` view state. All fields are the shared base fields:
+ * `selected` (item keys), `focus` (keyboard cursor key), `scroll`, and
+ * `expanded` (group key → open; groups default open, so only `false` entries
+ * are ever recorded).
+ */
+type GridListViewState = ViewStateBase;
+//#endregion
 //#region src/grid-list/grid-list.d.ts
 declare class GridListElement<T = unknown> extends LitElement {
   #private;
@@ -417,18 +506,17 @@ declare class GridListElement<T = unknown> extends LitElement {
    */
   disableHoverTickle: boolean;
   /**
-   * Ignore hover-target changes caused by scrolling. With virtualisation, a
-   * wheel / trackpad gesture replaces the cell beneath a stationary pointer,
-   * and the freshly rendered cell's `pointerenter` would move the cursor and
-   * emit `list-tickle` even though the pointer never moved. With this set,
-   * `pointerenter`-driven tickling is suppressed while a scroll gesture is
-   * active — the host also carries a `data-scroll-hover-suppress` attribute
-   * that gates the CSS `:hover` highlight, so the visual cursor holds still
-   * too. Hover resumes on the next real pointer movement, or after the pointer
-   * leaves and re-enters the list. Click selection, keyboard navigation, and
-   * `focusKey()` are unaffected.
-   */
-  disableScrollHoverTickle: boolean;
+   * Let hover follow cells that scroll beneath a stationary pointer. Off by
+   * default: with virtualisation, a wheel / trackpad gesture replaces the cell
+   * beneath the pointer, and following its `pointerenter` would move the
+   * cursor and emit `list-tickle` even though the pointer never moved. While a
+   * scroll gesture is active those enters are ignored and the host carries a
+   * `data-scroll-hover-suppress` attribute that gates the CSS `:hover`
+   * highlight, so the visual cursor holds still too. Hover resumes on the next
+   * real pointer movement, or after the pointer leaves the list. Click
+   * selection, keyboard navigation, and `focusKey()` are unaffected.
+   */
+  scrollHoverTickle: boolean;
   itemSize: number;
   gap: number;
   /**
@@ -618,8 +706,9 @@ declare class GridListElement<T = unknown> extends LitElement {
   removeSelectedKeys(keys: Iterable<string>): void;
   /**
    * Data mode: replace the whole item array. Selection and cursor keep any key
-   * that is still present; keys that vanish are dropped (one `list-select`).
-   * A no-op in element mode.
+   * that is still present; keys that vanish are deselected silently and held
+   * as pending view state, so they come back if the key reappears. A no-op in
+   * element mode.
    */
   setItems(items: readonly T[]): void;
   /**
@@ -636,19 +725,36 @@ declare class GridListElement<T = unknown> extends LitElement {
    */
   updateItem(key: string, item: T): void;
   /**
-   * Data mode: remove the items carrying these keys. Removed keys are dropped
-   * from selection and cursor (via the `items` change). A no-op in element mode.
+   * Data mode: remove the items carrying these keys. Removed keys leave the
+   * selection and cursor silently (via the `items` change) and are held as
+   * pending view state. A no-op in element mode.
    */
   removeItems(keys: Iterable<string>): void;
   /**
    * Data mode: drop every item. Selection and cursor are reset and one
-   * `list-select` with empty sets is emitted. A no-op in element mode.
+   * `list-select` with empty sets is emitted; their keys are held as pending
+   * view state, so re-adding the same keys restores them. A no-op in element
+   * mode.
    */
   clearItems(): void;
   /** Move the cursor to the item with this key and scroll it into view. */
   focusKey(key: string): void;
   /** The key of the item under the cursor, or `undefined`. */
   get tickledKey(): string | undefined;
+  /**
+   * Snapshot selection, collapsed groups, keyboard cursor and scroll as plain
+   * JSON, keyed by item / group key. Includes pending state for keys not
+   * currently present unless `includePending: false`.
+   */
+  getViewState(options?: GetViewStateOptions<GridListViewState>): GridListViewState;
+  /**
+   * Apply saved view state. Fields present replace the current ones; keys
+   * (items or groups) that aren't present yet are applied as they appear.
+   * Restored selection fires `list-select`.
+   */
+  setViewState(state: Partial<GridListViewState>): void;
+  /** Drop view state still waiting for its keys to appear. */
+  clearPendingViewState(): void;
   /** Element mode: the light-DOM element carrying `key`, or `undefined`. */
   getItem(key: string): Element | undefined;
   /** Element mode: the light-DOM element at effective index `index`. */
@@ -689,4 +795,4 @@ interface GridListElement {
   addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
 }
 //#endregion
-export { DragSelectRect as A, TreeKeyboardNavControllerConfig as C, ListSelectionGesture as D, ListSelectionControllerConfig as E, ListDragSelectControllerConfig as M, ListSelectionModes as O, TreeKeyboardNavController as S, ListSelectionController as T, GridListTickleDetail as _, GridListCaptionBackdrop as a, GridListViewportChangeEvent as b, GridListDataAdapter as c, GridListItemClickDetail as d, GridListItemClickEvent as f, GridListSelectEvent as g, GridListSelectDetail as h, GridListCaptionAlign as i, ListDragSelectController as j, isMultiMode as k, GridListElementEventMap as l, GridListOrientation as m, GridListActivateDetail as n, GridListCaptionPosition as o, GridListItemEventDetail as p, GridListActivateEvent as r, GridListCaptionStyle as s, GridListElement as t, GridListFullElementEventMap as u, GridListTickleEvent as v, TreeKeyboardNavItemId as w, TreeKeyboardNavCallbacks as x, GridListViewportChangeDetail as y };
+export { isMultiMode as A, capKeys as B, TreeKeyboardNavController as C, ListSelectionControllerConfig as D, ListSelectionController as E, EMPTY_KEYS as F, partitionFlags as G, flagsToRecord as H, MAX_PENDING_KEYS as I, partitionKeys as K, PendingFlags as L, ListDragSelectController as M, ListDragSelectControllerConfig as N, ListSelectionGesture as O, EMPTY_FLAGS as P, PendingKeys as R, TreeKeyboardNavCallbacks as S, TreeKeyboardNavItemId as T, keysAsFlags as U, flagsFromRecord as V, keysToArray as W, GridListSelectEvent as _, GridListCaptionAlign as a, GridListViewportChangeDetail as b, GridListCaptionStyle as c, GridListFullElementEventMap as d, GridListItemClickDetail as f, GridListSelectDetail as g, GridListOrientation as h, GridListActivateEvent as i, DragSelectRect as j, ListSelectionModes as k, GridListDataAdapter as l, GridListItemEventDetail as m, GridListViewState as n, GridListCaptionBackdrop as o, GridListItemClickEvent as p, withoutFlag as q, GridListActivateDetail as r, GridListCaptionPosition as s, GridListElement as t, GridListElementEventMap as u, GridListTickleDetail as v, TreeKeyboardNavControllerConfig as w, GridListViewportChangeEvent as x, GridListTickleEvent as y, capFlags as z };

package/dist/grid-list.d.ts

@@ -1,5 +1,5 @@
-import { B as ListNativeDragStartEvent, F as ListDragPreviewContext, I as ListDragPreviewRenderer, N as ListDragEntry, P as ListDragPreview, R as ListDragSource, z as ListNativeDragStartDetail } from "./tree-component-C6UHO-w9.js";
+import { B as ListNativeDragStartDetail, F as ListDragPreview, I as ListDragPreviewContext, L as ListDragPreviewRenderer, P as ListDragEntry, V as ListNativeDragStartEvent, z as ListDragSource } from "./tree-component-DgfkxmVY.js";
+import { _ as GridListSelectEvent, a as GridListCaptionAlign, b as GridListViewportChangeDetail, c as GridListCaptionStyle, d as GridListFullElementEventMap, f as GridListItemClickDetail, g as GridListSelectDetail, h as GridListOrientation, i as GridListActivateEvent, l as GridListDataAdapter, m as GridListItemEventDetail, n as GridListViewState, o as GridListCaptionBackdrop, p as GridListItemClickEvent, r as GridListActivateDetail, s as GridListCaptionPosition, t as GridListElement, u as GridListElementEventMap, v as GridListTickleDetail, x as GridListViewportChangeEvent, y as GridListTickleEvent } from "./grid-list-D6n7WH8l.js";
 import { i as ListGroupChangeEvent, l as ListGroupToggleDetail, n as ListGroupBy, o as ListGroupInfo, r as ListGroupChangeDetail, s as ListGroupLabel, u as ListGroupToggleEvent } from "./grouping-CUKgmkMm.js";
 import { i as ListInteractionMode, l as ListSelectionMode } from "./list-selection-types-PjKdhF-a.js";
-import { _ as GridListTickleDetail, a as GridListCaptionBackdrop, b as GridListViewportChangeEvent, c as GridListDataAdapter, d as GridListItemClickDetail, f as GridListItemClickEvent, g as GridListSelectEvent, h as GridListSelectDetail, i as GridListCaptionAlign, l as GridListElementEventMap, m as GridListOrientation, n as GridListActivateDetail, o as GridListCaptionPosition, p as GridListItemEventDetail, r as GridListActivateEvent, s as GridListCaptionStyle, t as GridListElement, u as GridListFullElementEventMap, v as GridListTickleEvent, y as GridListViewportChangeDetail } from "./grid-list-0e7snW6t.js";
-export { type GridListActivateDetail, type GridListActivateEvent, type GridListCaptionAlign, type GridListCaptionBackdrop, type GridListCaptionPosition, type GridListCaptionStyle, type GridListDataAdapter, GridListElement, type GridListElementEventMap, type GridListFullElementEventMap, type GridListItemClickDetail, type GridListItemClickEvent, type GridListItemEventDetail, type GridListOrientation, type GridListSelectDetail, type GridListSelectEvent, type GridListTickleDetail, type GridListTickleEvent, type GridListViewportChangeDetail, type GridListViewportChangeEvent, type ListDragEntry, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListGroupBy, type ListGroupChangeDetail, type ListGroupChangeEvent, type ListGroupInfo, type ListGroupLabel, type ListGroupToggleDetail, type ListGroupToggleEvent, type ListInteractionMode, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListSelectionMode };
+export { type GridListActivateDetail, type GridListActivateEvent, type GridListCaptionAlign, type GridListCaptionBackdrop, type GridListCaptionPosition, type GridListCaptionStyle, type GridListDataAdapter, GridListElement, type GridListElementEventMap, type GridListFullElementEventMap, type GridListItemClickDetail, type GridListItemClickEvent, type GridListItemEventDetail, type GridListOrientation, type GridListSelectDetail, type GridListSelectEvent, type GridListTickleDetail, type GridListTickleEvent, type GridListViewState, type GridListViewportChangeDetail, type GridListViewportChangeEvent, type ListDragEntry, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListGroupBy, type ListGroupChangeDetail, type ListGroupChangeEvent, type ListGroupInfo, type ListGroupLabel, type ListGroupToggleDetail, type ListGroupToggleEvent, type ListInteractionMode, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListSelectionMode };

package/dist/grid-list.js

@@ -1,3 +1,3 @@
 import "./list-group-header.js";
-import { t as GridListElement } from "./grid-list-y6dWJYu3.js";
+import { t as GridListElement } from "./grid-list-CdEkScn-.js";
 export { GridListElement };

package/dist/incr-search.d.ts

@@ -1,2 +1,2 @@
-import { A as FuzzySearch, C as ListSearchControllerOptions, D as IncrSearchTreeOptions, E as IncrSearchTreeController, F as IncrSearchChangeCallback, I as IncrSearchOptions, L as IncrSearchResult, M as HighlightOptions, N as HighlightTarget, O as createAcCompletionProvider, P as IncrSearch, R as IncrSearchState, S as ListSearchController, T as ListSearchMode, _ as DataListSearchAdapterOptions, a as RegisterListSearchCommandsOptions, b as LIST_SEARCH_MODES, c as applyHighlights, d as createFuzzySearch, f as ElementIncrSearch, g as createElementListSearchAdapter, h as ElementListSearchHost, i as LIST_SEARCH_COMMAND_IDS, j as FuzzySearchOptions, k as ElementIncrSearchOptions, l as buildHighlightTargets, m as ElementListSearchAdapterOptions, n as createTreeListSearchAdapter, o as registerListSearchCommands, p as createElementIncrSearch, r as listSearchStyles, s as createIncrSearch, t as TreeListSearchAdapterOptions, u as clearHighlights, v as DataListSearchItem, w as ListSearchHost, x as ListSearchAdapter, y as createDataListSearchAdapter } from "./index-KN2MW_xD.js";
+import { A as FuzzySearch, C as ListSearchControllerOptions, D as IncrSearchTreeOptions, E as IncrSearchTreeController, F as IncrSearchChangeCallback, I as IncrSearchOptions, L as IncrSearchResult, M as HighlightOptions, N as HighlightTarget, O as createAcCompletionProvider, P as IncrSearch, R as IncrSearchState, S as ListSearchController, T as ListSearchMode, _ as DataListSearchAdapterOptions, a as RegisterListSearchCommandsOptions, b as LIST_SEARCH_MODES, c as applyHighlights, d as createFuzzySearch, f as ElementIncrSearch, g as createElementListSearchAdapter, h as ElementListSearchHost, i as LIST_SEARCH_COMMAND_IDS, j as FuzzySearchOptions, k as ElementIncrSearchOptions, l as buildHighlightTargets, m as ElementListSearchAdapterOptions, n as createTreeListSearchAdapter, o as registerListSearchCommands, p as createElementIncrSearch, r as listSearchStyles, s as createIncrSearch, t as TreeListSearchAdapterOptions, u as clearHighlights, v as DataListSearchItem, w as ListSearchHost, x as ListSearchAdapter, y as createDataListSearchAdapter } from "./index-Dr80Zdl6.js";
 export { type DataListSearchAdapterOptions, type DataListSearchItem, type ElementIncrSearch, type ElementIncrSearchOptions, type ElementListSearchAdapterOptions, type ElementListSearchHost, type FuzzySearch, type FuzzySearchOptions, type HighlightOptions, type HighlightTarget, type IncrSearch, type IncrSearchChangeCallback, IncrSearchTreeController as IncrSearchMillerController, IncrSearchTreeController, type IncrSearchTreeOptions as IncrSearchMillerOptions, type IncrSearchTreeOptions, type IncrSearchOptions, type IncrSearchResult, type IncrSearchState, LIST_SEARCH_COMMAND_IDS, LIST_SEARCH_MODES, type ListSearchAdapter, ListSearchController, type ListSearchControllerOptions, type ListSearchHost, type ListSearchMode, type RegisterListSearchCommandsOptions, type TreeListSearchAdapterOptions, applyHighlights, buildHighlightTargets, clearHighlights, createAcCompletionProvider, createDataListSearchAdapter, createElementIncrSearch, createElementListSearchAdapter, createFuzzySearch, createIncrSearch, createTreeListSearchAdapter, listSearchStyles, registerListSearchCommands };

package/dist/index-9ttcdwlL.d.ts

@@ -0,0 +1,71 @@
+import { a as ViewStateBase, c as ViewStateChangeReason, n as ScrollState, t as GetViewStateOptions } from "./types-LU1u0CB8.js";
+import { ReactiveController, ReactiveControllerHost } from "lit";
+//#region src/common/view-state/view-state-controller.d.ts
+type ViewStateControllerOptions<S extends ViewStateBase> = {
+  /** Component kind written into every state, e.g. `tree-list`. */
+  readonly kind: string;
+  /** Build the full current state (pending included). Called when the change event fires. */
+  readonly capture: () => S;
+  /** Trailing debounce for `view-state-change`, ms. Default 150. */
+  readonly debounceMs?: number;
+};
+/**
+ * Plumbing shared by every view-stateful component:
+ *
+ * - **change events** — `notify(reason)` coalesces changes into one debounced
+ *   `view-state-change` event (strongest reason wins: user > data > restore),
+ *   flushed immediately on disconnect so the last change is never lost.
+ * - **restore marking** — changes made inside `restoring(fn)` are reported as
+ *   `restore`, so persistence code can skip writing back what it just loaded.
+ * - **validation** — `accepts(state)` rejects a state for another kind / version.
+ * - **pending scroll** — a scroll position waiting for its anchor item (or for
+ *   enough content). Cancelled by the user's own scroll intent on the target
+ *   given to `observeScrollTarget()`.
+ *
+ * The component owns its facets (selection, expansion, columns) and decides
+ * what's pending; this controller only carries the cross-cutting parts.
+ */
+declare class ViewStateController<S extends ViewStateBase> implements ReactiveController {
+  #private;
+  constructor(host: ReactiveControllerHost & EventTarget, options: ViewStateControllerOptions<S>);
+  get kind(): string;
+  hostConnected(): void;
+  hostDisconnected(): void;
+  /** Record a change. Inside `restoring()` the reason is forced to `restore`. */
+  notify(reason?: ViewStateChangeReason): void;
+  /** Fire any pending change event now. */
+  flush(): void;
+  /** Run `fn` with every `notify()` inside it reported as `restore`. */
+  restoring<T>(fn: () => T): T;
+  /** True while inside `restoring()`. */
+  get isRestoring(): boolean;
+  /** Whether `state` is for this component kind and schema version. Warns when not. */
+  accepts(state: Partial<S> | null | undefined): state is Partial<S>;
+  /**
+   * Stamp `v` / `kind` onto `fields` and apply `include`. Components build
+   * their full field set and pass it through here from `getViewState()`.
+   */
+  shape(fields: Omit<S, `v` | `kind`>, options?: GetViewStateOptions<S>): S;
+  /**
+   * Watch `target` for user scroll intent (wheel / touch / pointer / nav key);
+   * any intent drops the pending scroll. Call again if the scroll container
+   * is replaced.
+   */
+  observeScrollTarget(target: EventTarget): void;
+  get pendingScroll(): ScrollState | undefined;
+  set pendingScroll(scroll: ScrollState | undefined);
+  /**
+   * Try the pending scroll with `apply`; it returns `true` once the position
+   * was fully reached (anchor present, content long enough), which clears it.
+   * Call after each render that may have added items.
+   */
+  applyPendingScroll(apply: (scroll: ScrollState) => boolean): void;
+  /**
+   * Call from the viewport's `scroll` listener. Ignored while a scroll restore
+   * is still pending; the event caused by a restore's own write is reported
+   * as `restore`, anything else as `user`.
+   */
+  notifyScroll(): void;
+}
+//#endregion
+export { ViewStateControllerOptions as n, ViewStateController as t };

package/dist/{index-DEVyVIn8.d.ts → index-Bx0BXPxI.d.ts}

@@ -1,7 +1,9 @@
-import { A as TreeTickleEvent, C as TreeItemDblClickEvent, E as TreeSearchHost, I as ListDragPreviewRenderer, L as ListDragPreviewSourceResolver, O as TreeSelectEvent, _ as TreeDropTarget, a as TreeComponent, c as TreeDragContext, d as TreeDragStartEvent, h as TreeDropEvent, i as TreeCollapseEvent, j as TreeDataModel, l as TreeDragEndEvent, m as TreeDropDetail, n as TreeActivateEvent, o as TreeComponentEventMap, p as TreeDropContext, s as TreeDndMode, u as TreeDragOverEvent, w as TreeNavigateOptions, x as TreeItemClickEvent, y as TreeExpandEvent, z as ListNativeDragStartDetail } from "./tree-component-C6UHO-w9.js";
+import { B as ListNativeDragStartDetail, C as TreeItemDblClickEvent, D as TreeSelectAllOptions, E as TreeSearchHost, L as ListDragPreviewRenderer, M as TreeDataModel, R as ListDragPreviewSourceResolver, _ as TreeDropTarget, a as TreeComponent, c as TreeDragContext, d as TreeDragStartEvent, h as TreeDropEvent, i as TreeCollapseEvent, j as TreeTickleEvent, k as TreeSelectEvent, l as TreeDragEndEvent, m as TreeDropDetail, n as TreeActivateEvent, o as TreeComponentEventMap, p as TreeDropContext, s as TreeDndMode, u as TreeDragOverEvent, w as TreeNavigateOptions, x as TreeItemClickEvent, y as TreeExpandEvent } from "./tree-component-DgfkxmVY.js";
 import { a as TreeItem, i as TreeInteractionMode, n as TreeExclusivity, o as TreeNode, r as TreeFilterPredicate, s as TreeSelectionFilter, t as LoadChildrenCallback } from "./types-Jky6oNAp.js";
-import { S as ListSearchController } from "./index-KN2MW_xD.js";
-import { t as ListNativeDragController } from "./list-native-drag-controller-O2Nruqpi.js";
+import { a as ViewStateBase, t as GetViewStateOptions } from "./types-LU1u0CB8.js";
+import "./index-9ttcdwlL.js";
+import { S as ListSearchController } from "./index-Dr80Zdl6.js";
+import { t as ListNativeDragController } from "./list-native-drag-controller-D_UrXipS.js";
 import { n as TickledController } from "./tickled-controller-DodxD3eQ.js";
 import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost, TemplateResult, nothing } from "lit";
 import { CommandRegistry } from "@clinth/ui-commands";
@@ -12,6 +14,10 @@ type TreeConfig = {
   indent: number;
 };
 //#endregion
+//#region src/tree/tree-view-state.d.ts
+/** `ixfx-tree-list` view state. All fields are the shared base fields. */
+type TreeListViewState = ViewStateBase;
+//#endregion
 //#region src/tree/tree-base.d.ts
 /**
  * `auto` windows the list once it has more than `virtualizeThreshold` visible
@@ -40,6 +46,13 @@ declare class TreeBaseElement extends LitElement implements TreeComponent, TreeS
   get selectedNodes(): ReadonlySet<TreeNode>;
   filterPredicate: TreeFilterPredicate | undefined;
   disableKeyboardNavigation: boolean;
+  /**
+   * Let hover follow rows that scroll beneath a stationary pointer. Off by
+   * default: while a scroll gesture is active, row `pointerenter` is ignored so
+   * the hover cursor holds still instead of trailing the content. Hover resumes
+   * on the next real pointer movement, or when the pointer leaves the tree.
+   */
+  scrollHoverTickle: boolean;
   registry: CommandRegistry<unknown> | undefined;
   /**
    * Space-separated subset of `navigate select filter` — limits which
@@ -89,6 +102,12 @@ declare class TreeBaseElement extends LitElement implements TreeComponent, TreeS
   applyInternalDrop: boolean;
   /** Immutable: replace via `#setExpanded` so the flat-row cache is invalidated. */
   protected _expandedKeys: ReadonlySet<string>;
+  /**
+   * Whether restoring view state may call `loadChildren` / `model` to open
+   * saved branches that aren't loaded yet (one at a time, cascading down the
+   * saved path). Default `true`.
+   */
+  restoreLoads: boolean;
   /** Bumped whenever `_selectedNodes` content may have changed. */
   protected _selectionVersion: number;
   /**
@@ -103,6 +122,13 @@ declare class TreeBaseElement extends LitElement implements TreeComponent, TreeS
   /** Depths at which any loaded node carries an icon (stable across expansion). */
   protected get _depthsWithIcons(): ReadonlySet<number>;
   protected tickled: TickledController<string>;
+  /**
+   * Row `pointerenter` funnel: moves the hover cursor unless a scroll gesture
+   * is sliding rows beneath a stationary pointer (see `scrollHoverTickle`).
+   * Subclasses rendering their own rows should call this rather than the
+   * tickled controller directly.
+   */
+  protected _handleRowPointerEnter(node: TreeNode, depth: number): void;
   protected _focusedDepth: number;
   /** Incremental search (navigate / select / filter). See `docs/infra-incremental.md`. */
   readonly search: ListSearchController<{
@@ -132,11 +158,31 @@ declare class TreeBaseElement extends LitElement implements TreeComponent, TreeS
   disconnectedCallback(): void;
   getConfig(): TreeConfig;
   setConfig(config: Partial<TreeConfig>): void;
+  /**
+   * Snapshot selection, expansion, cursor and scroll as plain JSON, keyed by
+   * `item.key`. Includes pending state for keys not currently loaded.
+   */
+  getViewState(options?: GetViewStateOptions<TreeListViewState>): TreeListViewState;
+  /**
+   * Apply saved view state. Fields present replace the current ones; keys
+   * that aren't loaded yet are applied as they appear — including via
+   * `loadChildren` / `model` for saved-open branches when `restoreLoads`.
+   */
+  setViewState(state: Partial<TreeListViewState>): void;
+  clearPendingViewState(): void;
   select(node: TreeNode): void;
   deselect(node: TreeNode): void;
   clearSelection(): void;
-  selectAll(): void;
-  deselectAll(): void;
+  /**
+   * Select every selectable node in the tree, or only the matches while a
+   * `filterPredicate` is active. Nodes inside collapsed branches are included;
+   * unloaded (lazy) children are not. With `visibleOnly`, only rows that are
+   * showing are selected (Ctrl+A). In `checked` mode checking a row checks its
+   * descendants, so `visibleOnly` makes no difference there.
+   */
+  selectAll(options?: TreeSelectAllOptions): void;
+  /** Mirror of {@link selectAll}: deselect the same set of nodes it would select. */
+  deselectAll(options?: TreeSelectAllOptions): void;
   /**
    * Expand every already-loaded branch in a single update. With `maxDepth`,
    * only branches at depth < `maxDepth` are expanded (the root's children are
@@ -378,4 +424,4 @@ declare class TreeDropController implements ReactiveController {
   hostDisconnected(): void;
 }
 //#endregion
-export { TreeDropVisibleRow as a, TreeListElement as c, TreeBaseElement as d, TreeBaseElementEventMap as f, TreeDropRowInfo as i, TreeCheckboxState as l, TreeConfig as m, TreeDropControllerConfig as n, TreeController as o, TreeVirtualize as p, TreeDropResolvedDrag as r, TreeControllerOptions as s, TreeDropController as t, TreeAnimation as u };
+export { TreeDropVisibleRow as a, TreeListElement as c, TreeBaseElement as d, TreeBaseElementEventMap as f, TreeConfig as h, TreeDropRowInfo as i, TreeCheckboxState as l, TreeListViewState as m, TreeDropControllerConfig as n, TreeController as o, TreeVirtualize as p, TreeDropResolvedDrag as r, TreeControllerOptions as s, TreeDropController as t, TreeAnimation as u };