@adia-ai/web-components 0.6.33 → 0.6.35

package/components/kbd/kbd.css

@@ -1,28 +1,28 @@
 @scope (kbd-ui) {
   :where(:scope) {
     /* ── Tokens ── */
-    --kbd-bg:        var(--a-bg-muted);
-    --kbd-fg:        var(--a-fg);
-    --kbd-border:    var(--a-border-subtle);
-    --kbd-radius:    var(--a-radius-sm);
-    --kbd-font:      var(--a-font-family-code);
+    --kbd-bg-default:        var(--a-bg-muted);
+    --kbd-fg-default:        var(--a-fg);
+    --kbd-border-default:    var(--a-border-subtle);
+    --kbd-radius-default:    var(--a-radius-sm);
+    --kbd-font-default:      var(--a-font-family-code);
 
     /* Size — defaults to md */
-    --kbd-font-size: var(--a-ui-tiny);
-    --kbd-height:    1.25rem;
-    --kbd-min-width: 1.25rem;
-    --kbd-px:        var(--a-space-1);
-    --kbd-weight:    var(--a-weight-medium);
+    --kbd-font-size-default: var(--a-ui-tiny);
+    --kbd-height-default:    1.25rem;
+    --kbd-min-width-default: 1.25rem;
+    --kbd-px-default:        var(--a-space-1);
+    --kbd-weight-default:    var(--a-weight-medium);
 
     /* Size: sm */
-    --kbd-font-size-sm: var(--a-ui-tiny);
-    --kbd-height-sm:    1rem;
-    --kbd-min-width-sm: 1rem;
+    --kbd-font-size-sm-default: var(--a-ui-tiny);
+    --kbd-height-sm-default:    1rem;
+    --kbd-min-width-sm-default: 1rem;
 
     /* Size: lg */
-    --kbd-font-size-lg: var(--a-ui-sm);
-    --kbd-height-lg:    1.5rem;
-    --kbd-min-width-lg: 1.5rem;
+    --kbd-font-size-lg-default: var(--a-ui-sm);
+    --kbd-height-lg-default:    1.5rem;
+    --kbd-min-width-lg-default: 1.5rem;
     text-align: start;  /* §text-align-reset — blocks inheritance from centered ancestors */
 }
 
@@ -32,18 +32,18 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    min-width: var(--kbd-min-width);
-    height: var(--kbd-height);
-    padding-inline: var(--kbd-px);
-    font-family: var(--kbd-font);
-    font-size: var(--kbd-font-size);
-    font-weight: var(--kbd-weight);
+    min-width: var(--kbd-min-width, var(--kbd-min-width-default));
+    height: var(--kbd-height, var(--kbd-height-default));
+    padding-inline: var(--kbd-px, var(--kbd-px-default));
+    font-family: var(--kbd-font, var(--kbd-font-default));
+    font-size: var(--kbd-font-size, var(--kbd-font-size-default));
+    font-weight: var(--kbd-weight, var(--kbd-weight-default));
     line-height: 1;
-    color: var(--kbd-fg);
-    background: var(--kbd-bg);
-    border: 1px solid var(--kbd-border);
+    color: var(--kbd-fg, var(--kbd-fg-default));
+    background: var(--kbd-bg, var(--kbd-bg-default));
+    border: 1px solid var(--kbd-border, var(--kbd-border-default));
     border-bottom-width: 2px;
-    border-radius: var(--kbd-radius);
+    border-radius: var(--kbd-radius, var(--kbd-radius-default));
     vertical-align: middle;
     white-space: nowrap;
     user-select: none;
@@ -51,13 +51,13 @@
 
   /* Sizes */
   :scope[size="sm"] {
-    --kbd-font-size: var(--kbd-font-size-sm);
-    --kbd-height:    var(--kbd-height-sm);
-    --kbd-min-width: var(--kbd-min-width-sm);
+    --kbd-font-size-default: var(--kbd-font-size-sm, var(--kbd-font-size-sm-default));
+    --kbd-height-default:    var(--kbd-height-sm, var(--kbd-height-sm-default));
+    --kbd-min-width-default: var(--kbd-min-width-sm, var(--kbd-min-width-sm-default));
   }
   :scope[size="lg"] {
-    --kbd-font-size: var(--kbd-font-size-lg);
-    --kbd-height:    var(--kbd-height-lg);
-    --kbd-min-width: var(--kbd-min-width-lg);
+    --kbd-font-size-default: var(--kbd-font-size-lg, var(--kbd-font-size-lg-default));
+    --kbd-height-default:    var(--kbd-height-lg, var(--kbd-height-lg-default));
+    --kbd-min-width-default: var(--kbd-min-width-lg, var(--kbd-min-width-lg-default));
   }
 }

package/components/kbd/kbd.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIKbd } from './class.js';
+import { UIKbd } from './kbd.class.js';
 
 defineIfFree('kbd-ui', UIKbd);
 

package/components/link/link.css

@@ -7,16 +7,16 @@
 
 @scope (link-ui) {
   :where(:scope) {
-    --link-fg:              var(--a-link);
-    --link-fg-hover:        var(--a-link-hover);
-    --link-fg-visited:      var(--a-link-visited);
-    --link-underline-offset: 2px;
-    --link-focus-ring:      var(--a-focus-ring);
+    --link-fg-default:              var(--a-link);
+    --link-fg-hover-default:        var(--a-link-hover);
+    --link-fg-visited-default:      var(--a-link-visited);
+    --link-underline-offset-default: 2px;
+    --link-focus-ring-default:      var(--a-focus-ring);
   }
 
   :scope {
     display: inline;
-    color: var(--link-fg);
+    color: var(--link-fg, var(--link-fg-default));
     /* The text-decoration is on the inner <a>, not the host, so that
        host-level color overrides cascade correctly. */
   }
@@ -24,7 +24,7 @@
   :scope > a {
     color: inherit;
     text-decoration: underline;
-    text-underline-offset: var(--link-underline-offset);
+    text-underline-offset: var(--link-underline-offset, var(--link-underline-offset-default));
     cursor: pointer;
     /* Standard transition for color hover. */
     transition: color var(--a-duration-fast) var(--a-easing);
@@ -38,17 +38,17 @@
   }
 
   :scope > a:hover {
-    color: var(--link-fg-hover);
+    color: var(--link-fg-hover, var(--link-fg-hover-default));
   }
 
   :scope > a:visited {
-    color: var(--link-fg-visited);
+    color: var(--link-fg-visited, var(--link-fg-visited-default));
   }
 
   /* Focus ring on the anchor (the actual focusable element). */
   :scope > a:focus-visible {
     outline: none;
-    box-shadow: var(--link-focus-ring);
+    box-shadow: var(--link-focus-ring, var(--link-focus-ring-default));
     border-radius: var(--a-radius-sm);
   }
 
@@ -67,8 +67,8 @@
      affordance is implied by hover behavior + cursor. For "Already
      have an account?" type prose where the link role is contextual. */
   :scope[variant="quiet"] {
-    --link-fg: inherit;
-    --link-fg-hover: var(--a-link-hover);
+    --link-fg-default: inherit;
+    --link-fg-hover-default: var(--a-link-hover);
   }
   :scope[variant="quiet"] > a {
     text-decoration: none;

package/components/link/link.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UILink } from './class.js';
+import { UILink } from './link.class.js';
 
 defineIfFree('link-ui', UILink);
 

package/components/list/list-item.yaml

@@ -1,9 +1,9 @@
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 #
 # §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
-# component already existed as a sibling class in the parent's class.js
+# component already existed as a sibling class in the parent's list.class.js
 # + was registered alongside the parent (e.g. UIList + UIListItem both
-# from list/class.js). The catalog just lacked its own entry. With the
+# from list/list.class.js). The catalog just lacked its own entry. With the
 # §172 sibling-yaml scanner, this file gets picked up next to the parent
 # yaml.
 

package/components/list/list.css

@@ -1,10 +1,10 @@
 @scope (list-ui) {
   :where(:scope) {
     /* ── Colors ── */
-    --list-divider-color: var(--a-border-subtle);
-    --list-bg-selected:   var(--a-accent-muted);
-    --list-fg-selected:   var(--a-accent-strong);
-    --list-border-selected: var(--a-accent-strong);
+    --list-divider-color-default: var(--a-border-subtle);
+    --list-bg-selected-default:   var(--a-accent-muted);
+    --list-fg-selected-default:   var(--a-accent-strong);
+    --list-border-selected-default: var(--a-accent-strong);
   }
 
   :scope {
@@ -17,7 +17,7 @@
 
   /* ── Divider ── */
   :scope[divider] list-item-ui + list-item-ui {
-    border-top: 1px solid var(--list-divider-color);
+    border-top: 1px solid var(--list-divider-color, var(--list-divider-color-default));
   }
 
   /* ── Item padding / margin (controlled by list-ui attributes) ──
@@ -68,9 +68,9 @@
   }
 
   :scope[selectable] > [role="listitem"][aria-selected="true"] {
-    background: var(--list-bg-selected);
-    color: var(--list-fg-selected);
-    border-inline-start-color: var(--list-border-selected);
+    background: var(--list-bg-selected, var(--list-bg-selected-default));
+    color: var(--list-fg-selected, var(--list-fg-selected-default));
+    border-inline-start-color: var(--list-border-selected, var(--list-border-selected-default));
   }
 
   :scope[selectable] > [role="listitem"]:focus-visible {

package/components/list/list.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIList, UIListItem } from './class.js';
+import { UIList, UIListItem } from './list.class.js';
 
 defineIfFree('list-ui', UIList);
 defineIfFree('list-item-ui', UIListItem);

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
+  }
+}