@ixfx/components 0.9.8 → 0.10.0

package/dist/{vertical-list-CHrXmmQ3.d.ts → vertical-list--tFanQwM.d.ts}

@@ -1,5 +1,5 @@
-import { L as ListNativeDragStartEvent, P as ListDragPreviewRenderer } from "./tree-component-BW2iCFq9.js";
-import { S as ListSearchController } from "./index--qnhBWZJ.js";
+import { F as ListDragPreviewSourceResolver, P as ListDragPreviewRenderer, R as ListNativeDragStartEvent } from "./tree-component-mw8x-n2Y.js";
+import { S as ListSearchController } from "./index--5BSdbnL.js";
 import { i as ListInteractionMode, l as ListSelectionMode, r as ListElementEventMap } from "./list-selection-types-B5ioL-dG.js";
 import { LitElement, PropertyValues } from "lit";
 import { CommandId, CommandRegistry } from "@clinth/ui-commands";
@@ -64,6 +64,56 @@ declare class VerticalListElement extends LitElement {
    * built-in HTML+canvas preview.
    */
   dragPreviewRenderer: ListDragPreviewRenderer<Element> | undefined;
+  dragPreviewSource: ListDragPreviewSourceResolver<Element> | undefined;
+  /**
+   * Object/adapter item mode (mirrors `ixfx-detail-list`). When set, the list
+   * builds one `<li>` per entry and owns its light-DOM children; `formatter`
+   * renders each entry and `keyProperty` stamps `data-key` so `selectKeys` /
+   * `focusKey` / `getItemByKey` keep working.
+   *
+   * Additive: `addItem(element)` / `setItems(elements)` keep working while
+   * `items` is unset. While `items` is set, a rebuild (on `items` /
+   * `formatter` / `keyProperty` change) discards hand-added children.
+   */
+  items: readonly unknown[] | undefined;
+  /**
+   * Property name on each `items` entry used for stable identity — stamped
+   * as `data-key` on the built row. Preserves selection across rebuilds.
+   */
+  keyProperty: string;
+  /**
+   * Renders one adapter-mode entry. The result may be a `string` (row text),
+   * a `Node` (appended into the row `<li>`), a full row `Element` (an `<li>`
+   * or a `[data-list-item]` custom element, used directly), or a Lit template
+   * result (rendered into the row `<li>` with `render()`). Without a
+   * formatter, string entries become row text and `Node` entries are
+   * appended.
+   */
+  formatter: ((item: unknown, index: number) => unknown) | undefined;
+  /**
+   * Virtualize the list: only the overscanned viewport window exists in the
+   * DOM; offscreen rows are recycled through an off-DOM pool as the list
+   * scrolls. Works for hand-supplied elements AND adapter (`items`) rows —
+   * both are detached/reattached by identity, so selection, cursor and
+   * component state survive scrolling.
+   *
+   * Requires `item-height`: every row must be exactly that tall (use
+   * `--list-item-height` to match). `data-key`s are required for the key
+   * APIs (`selectKeys`, `focusKey`, `renderedKeys`); selection by reference
+   * (click, `select()`) works regardless.
+   *
+   * Limitations while active: drag-select is disabled (the window shifts
+   * under a drag), and incremental-search `filter` mode is excluded (it
+   * collapses rows via `hidden`, corrupting the fixed-stride geometry).
+   * Keyboard navigation stays within the rendered window — scroll first.
+   */
+  virtualize: boolean;
+  /**
+   * Fixed row height in px. Required for `virtualize` — the window math is
+   * pure stride arithmetic (no DOM measurement), mirroring
+   * `ixfx-grid-list`'s `itemSize`.
+   */
+  itemHeight: number;
   private readonly selection;
   private tickled;
   private _syncNativeDraggable;
@@ -83,6 +133,7 @@ declare class VerticalListElement extends LitElement {
    * Collapse + fade `item` out, then detach it. The rows below slide up to
    * close the gap. Resolves once the element has actually been removed.
    * Under `prefers-reduced-motion: reduce` it's removed immediately.
+   * A pooled (offscreen) row under virtualization is removed immediately.
    */
   removeItem(item: Element): Promise<void>;
   /** {@link removeItem} for several items at once. */
@@ -115,9 +166,46 @@ declare class VerticalListElement extends LitElement {
   addSelectedKeys(keys: Iterable<string>): void;
   /** Remove items by key from the selection. */
   removeSelectedKeys(keys: Iterable<string>): void;
-  /** Move the cursor to the item with this key and scroll it into view. */
+  /**
+   * Move the cursor to the item with this key and scroll it into view.
+   * Under virtualization the key's index is scrolled into the rendered
+   * window first (a no-op for unknown keys).
+   */
   focusKey(key: string): void;
+  /** The item carrying this `data-key`, or `undefined`. */
+  getItemByKey(key: string): Element | undefined;
+  /**
+   * Keys of items currently intersecting the viewport — for prioritising
+   * viewport-first work (e.g. metadata/thumbnail fetches). A rect-intersection
+   * test against the scroll container over the already-created rows (the same
+   * cheap trick as `ixfx-detail-list.visibleKeys()`); hidden (filtered-out)
+   * and keyless items are omitted.
+   */
+  visibleKeys(): string[];
+  /**
+   * Keys of the currently rendered window (viewport + overscan) — the
+   * priority set for prefetching, mirroring `ixfx-grid-list.renderedKeys()`.
+   * Use {@link visibleKeys} for the strict viewport intersection. Keyless
+   * rows are omitted. Without virtualization, every visible row's key.
+   */
+  renderedKeys(): string[];
   selectedFilter(kind: `selected` | `checked` | `either`): Generator<Element>;
+  /**
+   * Get the source object behind a row built from `items`. Returns
+   * `undefined` for declarative / programmatic elements.
+   */
+  getItemData(item: Element): unknown;
+  /**
+   * Adapter mode: re-render the row carrying `key` in place — scroll and
+   * selection are untouched. Unknown keys, and keys on rows not built from
+   * `items`, are ignored. A no-op unless `items` is set.
+   *
+   * Rows whose formatter returns a full row element are swapped for the fresh
+   * element; `<li>` rows are refilled. (A custom-element row with a
+   * non-element formatter result cannot be re-rendered in place and is left
+   * alone — have the formatter return a replacement element instead.)
+   */
+  updateItem(key: string, data: unknown): void;
   private _getVisibleItems;
   private _isCheckable;
   private _syncItemStates;
@@ -157,4 +245,4 @@ interface VerticalListElementEventMap extends ListElementEventMap {
 }
 //#endregion
 export { VerticalListElementEventMap as i, CustomCheckboxOptions as n, VerticalListElement as r, AddItemOptions as t };
-//# sourceMappingURL=vertical-list-CHrXmmQ3.d.ts.map
+//# sourceMappingURL=vertical-list--tFanQwM.d.ts.map

package/dist/vertical-list--tFanQwM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertical-list--tFanQwM.d.ts","names":[],"sources":["../src/vertical-list/vertical-list.ts"],"mappings":";;;;;;UAwDiB;EACf,WAAW;EACX;EACA;;UAGe;;;;;;EAMf;;cAYW,4BAA4B;;EAEvC,eAAe;EAGf,iBAAiB;EAGjB,mBAAmB,IAAI;;;;;;EAQvB;;;;;;;;;;;;;;;;;;;EAqBA,oBAAoB,gCAAgC;;;;;;EAQpD;;;;;;EAQA;;;;;EAOA,qBAAqB,wBAAwB;EAG7C,mBAAmB,8BAA8B;;;;;;;;;;;EAajD;;;;;EAOA;;;;;;;;;EAWA,aAAa,eAAe;;;;;;;;;;;;;;;;;;EAoB5B;;;;;;EAQA;mBAsCiB;UAeT;UA6EA;;WA6EC,QAAM,qBAAA;;MAYX,YAAY;EA2BP;EAsBA;EAuEA,QAAQ,SAAS;;MA8EtB,gBAAgB;;MAKhB,iBAAiB,YAAY;EAIjC,QAAQ,MAAM,kBAAkB,UAAU;;;;;;;EA4B1C,WAAW,MAAM,UAAU;;EA2B3B,YAAY,OAAO,SAAS,WAAW;EAIvC;;;;;;EAmBA,SAAS,gBAAgB;;;;;;EAwBzB,SAAS,WAAW,WAAW,OAAO;EAItC,OAAO,MAAM;EAIb,WAAW,OAAO,SAAS;EAI3B,SAAS,MAAM;EAIf;EAIA;;MAQI,gBAAgB;;MAKhB;;EAMJ,WAAW,MAAM;;EAKjB,gBAAgB,MAAM;;EAKtB,mBAAmB,MAAM;;;;;;EASzB,SAAS;;EAgCT,aAAa,cAAc;;;;;;;;EAW3B;;;;;;;EAuBA;EAsBE,eAAe,0CAA0C,UAAU;;;;;EA2CrE,YAAY,MAAM;;;;;;;;;;;EAclB,WAAW,aAAa;UA0dhB;UAgBA;UAOA;UAiBA;;;;;;;UA4GA;;;;;UAuBA;UAcA;UAYA;UAQA;UAWA;UAMA;UAIA;UAwDA;UAUA;UAMA;SAUQ,sBAAM;EAuKb,wBAAM;;QAeT;YACI;IACR,sBAAsB;;YAGd,4BAA4B;;UAGvB,oCAAoC;EACnD,0BAA0B,yBAAyB"}

package/dist/vertical-list.d.ts

@@ -1,4 +1,4 @@
-import { F as ListDragSource, I as ListNativeDragStartDetail, L as ListNativeDragStartEvent, M as ListDragPreview, N as ListDragPreviewContext, P as ListDragPreviewRenderer, j as ListDragEntry } from "./tree-component-BW2iCFq9.js";
+import { I as ListDragSource, L as ListNativeDragStartDetail, M as ListDragPreview, N as ListDragPreviewContext, P as ListDragPreviewRenderer, R as ListNativeDragStartEvent, j as ListDragEntry } from "./tree-component-mw8x-n2Y.js";
 import { a as ListItemClickDetail, c as ListSelectEvent, d as ListTickleEvent, i as ListInteractionMode, l as ListSelectionMode, n as ListActivateEvent, o as ListItemClickEvent, r as ListElementEventMap, s as ListSelectDetail, t as ListActivateDetail, u as ListTickleDetail } from "./list-selection-types-B5ioL-dG.js";
-import { i as VerticalListElementEventMap, n as CustomCheckboxOptions, r as VerticalListElement, t as AddItemOptions } from "./vertical-list-CHrXmmQ3.js";
+import { i as VerticalListElementEventMap, n as CustomCheckboxOptions, r as VerticalListElement, t as AddItemOptions } from "./vertical-list--tFanQwM.js";
 export { AddItemOptions, CustomCheckboxOptions, type ListActivateDetail, type ListActivateEvent, type ListDragEntry, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListElementEventMap, type ListInteractionMode, type ListItemClickDetail, type ListItemClickEvent, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListSelectDetail, type ListSelectEvent, type ListSelectionMode, type ListTickleDetail, type ListTickleEvent, VerticalListElement, VerticalListElementEventMap };