@adia-ai/web-components 0.6.33 → 0.6.34

package/components/list-window/list-window.a2ui.json

@@ -0,0 +1,277 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ListWindow.json",
+  "title": "ListWindow",
+  "description": "Virtualized / windowed list primitive. Renders only the visible slice of a large items[] array (chat threads, feeds, log streams, nav lists, search-result panes) — typically ≤50 DOM rows regardless of the underlying collection size. Composes a `render`-function prop OR a slotted <template> for row materialization; ships a fixed-size fast-path (constant-time index→offset math) and a variable-size measurement fallback. Distinct from <list-ui> (renders every child, preferred for short lists < 50 items) and <table-ui> (tabular data with columns). Use list-window-ui when items.length is large enough that rendering every row would block the main thread or stutter scroll.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "items": {
+      "description": "The items to virtualize. Required for prop-driven authoring; ignored when data-stream-src is set.",
+      "type": "array",
+      "default": []
+    },
+    "component": {
+      "const": "ListWindow"
+    },
+    "direction": {
+      "description": "Scroll axis — vertical (default) or horizontal carousel.",
+      "type": "string",
+      "enum": [
+        "vertical",
+        "horizontal"
+      ],
+      "default": "vertical"
+    },
+    "estimatedSize": {
+      "description": "Initial guess for variable-height rows. Used until the first measurement pass refines the offset cache.",
+      "type": "number",
+      "default": 48
+    },
+    "itemSize": {
+      "description": "Fixed item height in pixels. When > 0, uses the constant-time fast path (avoids per-row measurement).",
+      "type": "number",
+      "default": 0
+    },
+    "itemSizeRem": {
+      "description": "Fixed item height in rem. Useful for typographic-scale rows that should track the body type.",
+      "type": "number",
+      "default": 0
+    },
+    "loading": {
+      "description": "Render skeleton rows in the visible window. Sets aria-busy=\"true\" on the host.",
+      "type": "boolean",
+      "default": false
+    },
+    "overscan": {
+      "description": "Rows to render above + below the visible window. 0–20 is reasonable; > 50 negates the windowing benefit.",
+      "type": "number",
+      "default": 3
+    },
+    "pinBottom": {
+      "description": "When appending items, keep scroll pinned to the bottom (chat-thread / log-tail pattern).",
+      "type": "boolean",
+      "default": false
+    },
+    "startIndex": {
+      "description": "Index to scroll to on mount. Useful for restoring scroll position on remount.",
+      "type": "number",
+      "default": 0
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "{ \"component\": \"ListWindow\", \"items\": [/* 10000 items */], \"item-size\": 48 }\n",
+        "why": "Rendering 10k items into <list-ui> blows up the DOM and main thread. Scroll\njank, mount lag, and memory pressure all degrade.\n",
+        "wrong": "{ \"component\": \"List\", \"items\": [/* 10000 items */] }\n"
+      },
+      {
+        "fix": "Wrap in a container with a height, or set style=\"height:480px\" on the\nListWindow itself.\n",
+        "why": "Without a height bound, the scroll container has no viewport, so the windowing\nmath reports \"all items visible\" and the whole list mounts.\n",
+        "wrong": "{ \"component\": \"ListWindow\", \"items\": [/* … */] }\n(with no parent height + no item-size + no estimated-size)\n"
+      },
+      {
+        "fix": "{ \"component\": \"ListWindow\", \"overscan\": 5, \"items\": [/* … */] }\n",
+        "why": "Overscan=200 materializes 200 rows above + below the viewport. That defeats\nthe entire point of windowing.\n",
+        "wrong": "{ \"component\": \"ListWindow\", \"overscan\": 200, \"items\": [/* … */] }\n"
+      }
+    ],
+    "category": "display",
+    "composes": [
+      "skeleton-ui"
+    ],
+    "events": {
+      "item-click": {
+        "description": "Fired when a rendered row is clicked.",
+        "detail": {
+          "index": {
+            "description": "Item index in the full items[] array.",
+            "type": "number"
+          },
+          "item": {
+            "description": "The clicked item (full item-shape from items[])."
+          }
+        }
+      },
+      "measure": {
+        "description": "Fired when a variable-height row is measured. Useful for instrumenting the offset cache.",
+        "detail": {
+          "height": {
+            "description": "Measured row height in pixels.",
+            "type": "number"
+          },
+          "index": {
+            "description": "Index of the row that was measured.",
+            "type": "number"
+          }
+        }
+      },
+      "range-change": {
+        "description": "Fired when the visible row range (start/end indices) changes due to scroll.",
+        "detail": {
+          "items": {
+            "description": "The items currently materialized in the window.",
+            "type": "array"
+          },
+          "endIndex": {
+            "description": "Last rendered row index (exclusive).",
+            "type": "number"
+          },
+          "startIndex": {
+            "description": "First rendered row index.",
+            "type": "number"
+          }
+        }
+      },
+      "scroll-end": {
+        "description": "Fired when the user scrolls to the bottom (within 1 viewport). Use for infinite-load patterns.",
+        "detail": {
+          "index": {
+            "description": "Last visible row index.",
+            "type": "number"
+          }
+        }
+      },
+      "scroll-start": {
+        "description": "Fired when the user scrolls to the top (within 1 viewport). Use for \"load older\" patterns.",
+        "detail": {
+          "index": {
+            "description": "First visible row index.",
+            "type": "number"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Virtualized chat-thread message list with declarative <template> rows.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\"thread\"]\n  },\n  {\n    \"id\": \"thread\",\n    \"component\": \"ListWindow\",\n    \"item-size\": 56,\n    \"overscan\": 5,\n    \"pin-bottom\": true\n  }\n]",
+        "name": "chat-thread-list"
+      },
+      {
+        "description": "SSE-streamed JSONL log tail with sticky-bottom pin.",
+        "a2ui": "[\n  {\n    \"id\": \"logs\",\n    \"component\": \"ListWindow\",\n    \"item-size\": 24,\n    \"pin-bottom\": true\n  }\n]",
+        "name": "log-tail-stream"
+      }
+    ],
+    "keywords": [
+      "list-window",
+      "virtualized",
+      "windowed",
+      "virtual-scroll",
+      "infinite-scroll",
+      "large-list",
+      "feed",
+      "chat-thread",
+      "log-stream",
+      "10k-rows"
+    ],
+    "name": "UIListWindow",
+    "related": [
+      "List",
+      "ListItem",
+      "Feed",
+      "ChatThread",
+      "Table"
+    ],
+    "slots": {
+      "default": {
+        "description": "A single <template> element used to clone rows (declarative-template authoring). Mutually exclusive with the render prop."
+      },
+      "after": {
+        "description": "Sticky-bottom content (composer, \"load older\" button)."
+      },
+      "before": {
+        "description": "Sticky-top content (filter chips, summary stat)."
+      },
+      "empty": {
+        "description": "Custom empty-state content when items.length === 0."
+      },
+      "loading": {
+        "description": "Custom skeleton row template; falls back to <skeleton-ui> when omitted."
+      }
+    },
+    "states": [
+      {
+        "description": "Default — rendering and reconciling normally.",
+        "name": "idle"
+      },
+      {
+        "description": "Skeleton rows; data fetch in flight.",
+        "attribute": "loading",
+        "name": "loading"
+      },
+      {
+        "description": "items.length === 0.",
+        "attribute": "empty",
+        "name": "empty"
+      },
+      {
+        "description": "First-mount measurement pass on variable-height rows; suppresses scroll-end events.",
+        "attribute": "measuring",
+        "name": "measuring"
+      },
+      {
+        "description": "Pointer events blocked.",
+        "attribute": "disabled",
+        "name": "disabled"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "infinite-scroll": [
+        "virtualized",
+        "virtual-scroll",
+        "list-window"
+      ],
+      "large-list": [
+        "virtualized",
+        "list-window"
+      ],
+      "virtual-scroll": [
+        "virtualized",
+        "windowed",
+        "list-window"
+      ],
+      "virtualized": [
+        "virtual-scroll",
+        "windowed",
+        "list-window"
+      ],
+      "windowed": [
+        "virtualized",
+        "virtual-scroll",
+        "list-window"
+      ]
+    },
+    "tag": "list-window-ui",
+    "tokens": {
+      "--list-window-bg": {
+        "description": "Host background (defaults to --a-bg)."
+      },
+      "--list-window-overscan-bg": {
+        "description": "Visible buffer rows background — transparent by default."
+      },
+      "--list-window-row-gap": {
+        "description": "Row spacing in the visible window (defaults to --a-space-1)."
+      },
+      "--list-window-sentinel-size": {
+        "description": "Top + bottom IntersectionObserver-target sentinel size (defaults to --a-space-2)."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/list-window/list-window.css

@@ -0,0 +1,124 @@
+@scope (list-window-ui) {
+  /* ── Block 1 — TOKENS (zero-specificity, exposable for theming) ── */
+  :where(:scope) {
+    --list-window-bg-default:              var(--a-bg);
+    --list-window-row-gap-default:         var(--a-space-1);
+    --list-window-overscan-bg-default:     transparent;
+    --list-window-sentinel-size-default:   var(--a-space-2);
+  }
+
+  /* ── Block 2 — BASE styles consuming the tokens above ── */
+  :scope {
+    box-sizing: border-box;
+    display: block;
+    position: relative;
+    overflow: auto;
+    contain: strict;
+    background: var(--list-window-bg, var(--list-window-bg-default));
+    isolation: isolate;
+    outline: none;
+  }
+
+  :scope:focus-visible {
+    outline: 2px solid var(--a-accent-strong);
+    outline-offset: -2px;
+  }
+
+  /* Phantom spacer reserves total scroll height = sum of all row sizes.
+     Width pinned to 1px so it never contributes horizontal scroll in
+     vertical mode (and vice versa). */
+  :scope > [data-phantom] {
+    position: relative;
+    pointer-events: none;
+  }
+
+  /* The visible-rows container is absolutely positioned and translated
+     to align with the current scroll window. flex-column lays rows
+     vertically; gap controls row spacing without margin-collapse
+     surprises. */
+  :scope > [data-window] {
+    position: absolute;
+    top: 0;
+    inset-inline-start: 0;
+    inset-inline-end: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--list-window-row-gap, var(--list-window-row-gap-default));
+    will-change: transform;
+  }
+
+  /* Each row is its own block — height defined by content (variable
+     mode) or the item-size prop (fixed mode). min-width:0 prevents
+     overflow:hidden flex children from blowing out the host. */
+  :scope > [data-window] > [data-row] {
+    flex: 0 0 auto;
+    min-width: 0;
+  }
+
+  /* Sentinel nodes are tiny invisible markers tracked by the host's
+     IntersectionObserver. The top sentinel sits at the top of the
+     phantom; the bottom sentinel at the bottom. They emit
+     scroll-start / scroll-end when intersecting the host viewport. */
+  :scope > [data-sentinel] {
+    position: absolute;
+    inset-inline-start: 0;
+    inset-inline-end: 0;
+    height: var(--list-window-sentinel-size, var(--list-window-sentinel-size-default));
+    pointer-events: none;
+  }
+  :scope > [data-sentinel="top"]    { top: 0; }
+  :scope > [data-sentinel="bottom"] { bottom: 0; }
+
+  /* Sticky slots — sit at the top/bottom of the scroll container so they
+     stay visible while the window scrolls. */
+  :scope > [slot="before"] {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    background: var(--list-window-bg, var(--list-window-bg-default));
+  }
+  :scope > [slot="after"] {
+    position: sticky;
+    bottom: 0;
+    z-index: 1;
+    background: var(--list-window-bg, var(--list-window-bg-default));
+  }
+
+  /* ── Horizontal mode ── */
+  :scope[direction="horizontal"] > [data-window] {
+    flex-direction: row;
+  }
+  :scope[direction="horizontal"] > [data-sentinel] {
+    width: var(--list-window-sentinel-size, var(--list-window-sentinel-size-default));
+    height: auto;
+    top: 0;
+    bottom: 0;
+    inset-inline-start: auto;
+    inset-inline-end: auto;
+  }
+  :scope[direction="horizontal"] > [data-sentinel="top"]    { inset-inline-start: 0; }
+  :scope[direction="horizontal"] > [data-sentinel="bottom"] { inset-inline-end: 0; }
+
+  /* ── States ── */
+  :scope[empty] > [data-window] {
+    display: none;
+  }
+  :scope[empty] > [slot="empty"] {
+    display: block;
+  }
+
+  :scope:not([empty]) > [slot="empty"] {
+    display: none;
+  }
+
+  :scope[measuring] > [data-window] {
+    /* Suppress row-gap during initial measurement pass to avoid
+       layout shift between estimated and measured offsets. */
+    gap: 0;
+  }
+
+  :scope[disabled] {
+    pointer-events: none;
+    opacity: 0.5;
+  }
+}

package/components/list-window/list-window.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `<list-window-ui>` — Virtualized / windowed list primitive. Renders only the visible slice of a large items[] array (chat threads, feeds, log streams, nav lists, search-result panes) — typically ≤50 DOM rows regardless of the underlying collection size. Composes a `render`-function prop OR a slotted <template> for row materialization; ships a fixed-size fast-path (constant-time index→offset math) and a variable-size measurement fallback. Distinct from <list-ui> (renders every child, preferred for short lists < 50 items) and <table-ui> (tabular data with columns). Use list-window-ui when items.length is large enough that rendering every row would block the main thread or stutter scroll.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/list-window
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export interface ListWindowItemClickEventDetail {
+  /** Item index in the full items[] array. */
+  index: number;
+  /** The clicked item (full item-shape from items[]). */
+  item: string;
+}
+
+export type ListWindowItemClickEvent = CustomEvent<ListWindowItemClickEventDetail>;
+export interface ListWindowMeasureEventDetail {
+  /** Measured row height in pixels. */
+  height: number;
+  /** Index of the row that was measured. */
+  index: number;
+}
+
+export type ListWindowMeasureEvent = CustomEvent<ListWindowMeasureEventDetail>;
+export interface ListWindowRangeChangeEventDetail {
+  /** The items currently materialized in the window. */
+  items: unknown[];
+  /** Last rendered row index (exclusive). */
+  endIndex: number;
+  /** First rendered row index. */
+  startIndex: number;
+}
+
+export type ListWindowRangeChangeEvent = CustomEvent<ListWindowRangeChangeEventDetail>;
+export interface ListWindowScrollEndEventDetail {
+  /** Last visible row index. */
+  index: number;
+}
+
+export type ListWindowScrollEndEvent = CustomEvent<ListWindowScrollEndEventDetail>;
+export interface ListWindowScrollStartEventDetail {
+  /** First visible row index. */
+  index: number;
+}
+
+export type ListWindowScrollStartEvent = CustomEvent<ListWindowScrollStartEventDetail>;
+
+export class UIListWindow extends UIElement {
+  /** The items to virtualize. Required for prop-driven authoring; ignored when data-stream-src is set. */
+  items: unknown[];
+  /** Scroll axis — vertical (default) or horizontal carousel. */
+  direction: 'vertical' | 'horizontal';
+  /** Initial guess for variable-height rows. Used until the first measurement pass refines the offset cache. */
+  estimatedSize: number;
+  /** Fixed item height in pixels. When > 0, uses the constant-time fast path (avoids per-row measurement). */
+  itemSize: number;
+  /** Fixed item height in rem. Useful for typographic-scale rows that should track the body type. */
+  itemSizeRem: number;
+  /** Render skeleton rows in the visible window. Sets aria-busy="true" on the host. */
+  loading: boolean;
+  /** Rows to render above + below the visible window. 0–20 is reasonable; > 50 negates the windowing benefit. */
+  overscan: number;
+  /** When appending items, keep scroll pinned to the bottom (chat-thread / log-tail pattern). */
+  pinBottom: boolean;
+  /** Index to scroll to on mount. Useful for restoring scroll position on remount. */
+  startIndex: number;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIListWindow, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'item-click', listener: (ev: ListWindowItemClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'measure', listener: (ev: ListWindowMeasureEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'range-change', listener: (ev: ListWindowRangeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'scroll-end', listener: (ev: ListWindowScrollEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'scroll-start', listener: (ev: ListWindowScrollStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/list-window/list-window.examples.md

@@ -0,0 +1,73 @@
+# list-window — Examples
+
+## basic — fixed-size rows
+
+```html
+<list-window-ui item-size="40" overscan="3" style="height:320px">
+</list-window-ui>
+<script>
+  const el = document.querySelector('list-window-ui');
+  el.renderRow = (item) => {
+    const row = document.createElement('list-item-ui');
+    row.setAttribute('text', item.text);
+    return row;
+  };
+  el.items = Array.from({ length: 1000 }, (_, i) => ({
+    id: `b-${i}`,
+    text: `Row ${i + 1}`,
+  }));
+</script>
+```
+
+## 10,000 rows
+
+```html
+<list-window-ui item-size="32" overscan="5" style="height:320px">
+</list-window-ui>
+<script>
+  const el = document.querySelector('list-window-ui');
+  el.items = Array.from({ length: 10_000 }, (_, i) => ({
+    id: `lg-${i}`,
+    text: `Log line ${i}`,
+  }));
+</script>
+```
+
+## pin-bottom — chat-thread / log-tail
+
+```html
+<list-window-ui item-size="28" pin-bottom style="height:240px">
+</list-window-ui>
+<script>
+  const el = document.querySelector('list-window-ui');
+  el.items = initialMessages;
+  // Appending keeps scroll pinned at the bottom.
+  el.items = [...el.items, ...newMessages];
+</script>
+```
+
+## variable-height — feed cards
+
+```html
+<list-window-ui estimated-size="120" overscan="2" style="height:360px">
+</list-window-ui>
+<script>
+  const el = document.querySelector('list-window-ui');
+  el.renderRow = (item) => buildCardElement(item);
+  el.items = cards;
+</script>
+```
+
+## loading state
+
+```html
+<list-window-ui item-size="48" loading style="height:240px"></list-window-ui>
+```
+
+## empty state
+
+```html
+<list-window-ui item-size="40" style="height:160px">
+  <div slot="empty">No items to display.</div>
+</list-window-ui>
+```

package/components/list-window/list-window.js

@@ -0,0 +1,17 @@
+/**
+ * `<list-window-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIListWindow } from '@adia-ai/web-components/components/list-window/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIListWindow } from './class.js';
+
+defineIfFree('list-window-ui', UIListWindow);
+
+export { UIListWindow };