@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/typography/README.md

@@ -24,13 +24,14 @@ Renders text with a named typographic variant mapped to the design token scale.
 
 <!-- generated:props:start -->
 
-| Prop           | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required | Default   | Description                                                                  |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | ---------------------------------------------------------------------------- |
-| `class`        | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no       | —         | Additional class names merged with `.cinder-typography`.                     |
-| `component`    | `"object"` \| `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"caption"` \| `"label"` \| `"a"` \| `"abbr"` \| `"address"` \| `"article"` \| `"aside"` \| `"audio"` \| `"b"` \| `"bdi"` \| `"bdo"` \| `"blockquote"` \| `"body"` \| `"button"` \| `"canvas"` \| `"cite"` \| `"code"` \| `"colgroup"` \| `"data"` \| `"datalist"` \| `"dd"` \| `"del"` \| `"details"` \| `"dfn"` \| `"dialog"` \| `"div"` \| `"dl"` \| `"dt"` \| `"em"` \| `"fieldset"` \| `"figcaption"` \| `"figure"` \| `"footer"` \| `"form"` \| `"head"` \| `"header"` \| `"hgroup"` \| `"html"` \| `"i"` \| `"iframe"` \| `"ins"` \| `"kbd"` \| `"legend"` \| `"li"` \| `"main"` \| `"map"` \| `"mark"` \| `"menu"` \| `"meter"` \| `"nav"` \| `"noscript"` \| `"ol"` \| `"optgroup"` \| `"option"` \| `"output"` \| `"p"` \| `"picture"` \| `"pre"` \| `"progress"` \| `"q"` \| `"rp"` \| `"rt"` \| `"ruby"` \| `"s"` \| `"samp"` \| `"script"` \| `"search"` \| `"section"` \| `"select"` \| `"slot"` \| `"small"` \| `"span"` \| `"strong"` \| `"style"` \| `"sub"` \| `"summary"` \| `"sup"` \| `"table"` \| `"tbody"` \| `"td"` \| `"template"` \| `"textarea"` \| `"tfoot"` \| `"th"` \| `"thead"` \| `"time"` \| `"title"` \| `"tr"` \| `"u"` \| `"ul"` \| `"var"` \| `"video"` | no       | —         | Override the rendered HTML element while keeping the variant's visual style. |
-| `gutterBottom` | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `false`   | When true, adds bottom margin using the space scale.                         |
-| `noWrap`       | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `false`   | When true, constrains to a single line with ellipsis overflow.               |
-| `variant`      | `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"subtitle1"` \| `"subtitle2"` \| `"body1"` \| `"body2"` \| `"caption"` \| `"overline"` \| `"label"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | no       | `"body1"` | Named typographic style to apply.                                            |
+| Prop           | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required | Default   | Description                                                                                                             |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `class`        | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no       | —         | Additional class names merged with `.cinder-typography`.                                                                |
+| `component`    | `"object"` \| `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"caption"` \| `"label"` \| `"a"` \| `"abbr"` \| `"address"` \| `"article"` \| `"aside"` \| `"audio"` \| `"b"` \| `"bdi"` \| `"bdo"` \| `"blockquote"` \| `"body"` \| `"button"` \| `"canvas"` \| `"cite"` \| `"code"` \| `"colgroup"` \| `"data"` \| `"datalist"` \| `"dd"` \| `"del"` \| `"details"` \| `"dfn"` \| `"dialog"` \| `"div"` \| `"dl"` \| `"dt"` \| `"em"` \| `"fieldset"` \| `"figcaption"` \| `"figure"` \| `"footer"` \| `"form"` \| `"head"` \| `"header"` \| `"hgroup"` \| `"html"` \| `"i"` \| `"iframe"` \| `"ins"` \| `"kbd"` \| `"legend"` \| `"li"` \| `"main"` \| `"map"` \| `"mark"` \| `"menu"` \| `"meter"` \| `"nav"` \| `"noscript"` \| `"ol"` \| `"optgroup"` \| `"option"` \| `"output"` \| `"p"` \| `"picture"` \| `"pre"` \| `"progress"` \| `"q"` \| `"rp"` \| `"rt"` \| `"ruby"` \| `"s"` \| `"samp"` \| `"script"` \| `"search"` \| `"section"` \| `"select"` \| `"slot"` \| `"small"` \| `"span"` \| `"strong"` \| `"style"` \| `"sub"` \| `"summary"` \| `"sup"` \| `"table"` \| `"tbody"` \| `"td"` \| `"template"` \| `"textarea"` \| `"tfoot"` \| `"th"` \| `"thead"` \| `"time"` \| `"title"` \| `"tr"` \| `"u"` \| `"ul"` \| `"var"` \| `"video"` | no       | —         | Override the rendered HTML element while keeping the variant's visual style.                                            |
+| `gutterBottom` | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `false`   | When true, adds bottom margin using the space scale.                                                                    |
+| `noWrap`       | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `false`   | When true, constrains to a single line with ellipsis overflow.                                                          |
+| `variant`      | `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"subtitle1"` \| `"subtitle2"` \| `"body1"` \| `"body2"` \| `"caption"` \| `"overline"` \| `"label"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | no       | `"body1"` | Named typographic style to apply.                                                                                       |
+| `children`     | `(opaque)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | yes      | —         | The text content or composed inline content. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/virtual-list/README.md

@@ -0,0 +1,70 @@
+# VirtualList
+
+Fixed-height windowing primitive for long append-only lists. VirtualList owns a
+native vertical scroll container and renders only the visible rows plus overscan;
+you own the row markup through the `row` snippet.
+
+Version 1 requires a fixed `itemHeight` in pixels. Variable or measured row
+heights are intentionally out of scope for this primitive.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { VirtualList } from '@lostgradient/cinder/virtual-list';
+
+  const events = Array.from({ length: 10_000 }, (_, index) => ({
+    id: `event-${index}`,
+    label: `Event ${index}`,
+  }));
+</script>
+
+<VirtualList
+  items={events}
+  itemHeight={32}
+  height="20rem"
+  getKey={(event) => event.id}
+  aria-label="Events"
+>
+  {#snippet row(event, context)}
+    <div data-index={context.index}>{event.label}</div>
+  {/snippet}
+</VirtualList>
+```
+
+Use `stickToBottom` for live log tails: appending while the user is already at
+the bottom keeps the newest row in view, while appending with the viewport
+scrolled up leaves the scroll position unchanged.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop            | Type       | Required | Default | Description                                                                                                                                                                                                                                                                    |
+| --------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `class`         | `string`   | no       | —       | Additional class names merged with `.cinder-virtual-list`.                                                                                                                                                                                                                     |
+| `height`        | `string`   | no       | —       | CSS block-size for the native scroll container. Defaults to `"20rem"`.                                                                                                                                                                                                         |
+| `itemHeight`    | `number`   | yes      | —       | Fixed row height in pixels. Variable and measured row heights are out of scope for v1; pass the known or estimated fixed height for every row.                                                                                                                                 |
+| `overscan`      | `number`   | no       | —       | Extra rows rendered before and after the visible window. Defaults to 5.                                                                                                                                                                                                        |
+| `stickToBottom` | `boolean`  | no       | —       | When true, appending items while the viewport is already at the bottom keeps the newest item pinned in view. Appending while scrolled up leaves the scroll position unchanged.                                                                                                 |
+| `tabindex`      | `number`   | no       | —       | Override the default focus behavior. The component sets `tabindex="0"` by default so keyboard users can reach the native scroll container for arrow-key scrolling. Pass `tabindex={-1}` when the viewport should be programmatically focusable without entering the tab order. |
+| `getKey`        | `(opaque)` | no       | —       | Stable key extractor. Omit only when items are append-only and never reordered; the component will fall back to full-array indexes. Not expressible in JSON Schema; see the component types for the signature.                                                                 |
+| `items`         | `(opaque)` | yes      | —       | Items in full logical order. Only the visible window is mounted. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                    |
+| `row`           | `(opaque)` | yes      | —       | Rendered row snippet. Receives the item and its virtual row context. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+- `--cinder-virtual-list-height`
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/virtual-list/index.ts

@@ -0,0 +1,16 @@
+import './virtual-list.css';
+import VirtualList from './virtual-list.svelte';
+
+export default VirtualList;
+export {
+  getFixedVirtualWindow,
+  parsePixelLength,
+  resolveVirtualItemHeight,
+  resolveVirtualOverscan,
+} from '../../utilities/fixed-virtual-window.ts';
+export type {
+  FixedVirtualWindow,
+  FixedVirtualWindowItem,
+} from '../../utilities/fixed-virtual-window.ts';
+export type { VirtualListProps, VirtualListRowContext } from './virtual-list.types.ts';
+export { VirtualList };

package/src/components/virtual-list/virtual-list.css

@@ -0,0 +1,30 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+
+@layer cinder.components {
+  .cinder-virtual-list {
+    --cinder-virtual-list-height: 20rem;
+
+    display: block;
+    block-size: var(--cinder-virtual-list-height, 20rem);
+    inline-size: 100%;
+    overflow: auto;
+    overscroll-behavior: contain;
+    -webkit-overflow-scrolling: touch;
+    contain: layout paint;
+  }
+
+  .cinder-virtual-list__spacer {
+    position: relative;
+    min-block-size: 100%;
+    inline-size: 100%;
+  }
+
+  .cinder-virtual-list__window {
+    position: absolute;
+    inset-inline: 0;
+  }
+
+  .cinder-virtual-list__row {
+    overflow: hidden;
+  }
+}

package/src/components/virtual-list/virtual-list.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "virtual-list",
+  "import": "@lostgradient/cinder/virtual-list",
+  "examples": [
+    {
+      "id": "ten-thousand",
+      "title": "10,000 item virtual list",
+      "description": "A native scroll container rendering only the visible slice of a 10,000 item append-only event stream.",
+      "code": "<script lang=\"ts\">\n  import { VirtualList } from '@lostgradient/cinder/virtual-list';\n\n  type EventRow = {\n    id: string;\n    timestamp: string;\n    source: string;\n    message: string;\n  };\n\n  const events: EventRow[] = Array.from({ length: 10_000 }, (_, index) => ({\n    id: `event-${index}`,\n    timestamp: `2026-06-18T${String(index % 24).padStart(2, '0')}:${String(index % 60).padStart(\n      2,\n      '0',\n    )}:00Z`,\n    source: `worker-${index % 12}`,\n    message: `Processed workflow event ${index.toLocaleString('en-US')}`,\n  }));\n</script>\n\n<VirtualList\n  items={events}\n  itemHeight={36}\n  height=\"360px\"\n  overscan={4}\n  getKey={(event) => event.id}\n  aria-label=\"Workflow events\"\n>\n  {#snippet row(event, context)}\n    <div\n      style=\"display: grid; grid-template-columns: 11rem 7rem minmax(0, 1fr); gap: 0.75rem; align-items: center; min-block-size: 36px; padding-inline: 0.75rem; border-block-end: 1px solid var(--cinder-border); font-size: var(--cinder-text-sm);\"\n      data-index={context.index}\n    >\n      <span>{event.timestamp}</span>\n      <strong>{event.source}</strong>\n      <span>{event.message}</span>\n    </div>\n  {/snippet}\n</VirtualList>\n"
+    }
+  ]
+}

package/src/components/virtual-list/virtual-list.svelte

@@ -0,0 +1,192 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category data-display
+   * @status beta
+   * @purpose Fixed-height windowing primitive for long vertical lists that renders only the visible rows plus overscan inside a native scroll container.
+   * @tag list
+   * @tag virtualization
+   * @tag performance
+   * @useWhen Rendering thousands of same-height append-only rows such as logs, event streams, or activity feeds.
+   * @useWhen You need a reusable primitive that owns native vertical scrolling but leaves row markup to a snippet.
+   * @avoidWhen Rows have substantially variable heights that must be measured dynamically — v1 requires a fixed itemHeight.
+   * @avoidWhen Rendering columns or two-dimensional grids — use data-grid for grid semantics and column virtualization.
+   * @related data-list, data-table, data-grid
+   */
+  export type { VirtualListProps, VirtualListRowContext } from './virtual-list.types.ts';
+  export type {
+    FixedVirtualWindow,
+    FixedVirtualWindowItem,
+  } from '../../utilities/fixed-virtual-window.ts';
+  export {
+    getFixedVirtualWindow,
+    parsePixelLength,
+    resolveVirtualItemHeight,
+    resolveVirtualOverscan,
+  } from '../../utilities/fixed-virtual-window.ts';
+</script>
+
+<script lang="ts" generics="Item">
+  import { tick } from 'svelte';
+
+  import { classNames } from '../../utilities/class-names.ts';
+  import { useResizeObserver } from '../../utilities/use-resize-observer.svelte.ts';
+  import type { VirtualListProps } from './virtual-list.types.ts';
+  import {
+    getFixedVirtualWindow,
+    parsePixelLength,
+    resolveVirtualItemHeight,
+    resolveVirtualOverscan,
+  } from '../../utilities/fixed-virtual-window.ts';
+
+  let {
+    items,
+    itemHeight,
+    overscan = 5,
+    height = '20rem',
+    stickToBottom = false,
+    tabindex = 0,
+    getKey,
+    row,
+    role = 'list',
+    onscroll: onScroll,
+    class: className,
+    ...rest
+  }: VirtualListProps<Item> = $props();
+
+  let scrollElement: HTMLElement | undefined = $state();
+  let scrollOffset = $state(0);
+  let measuredViewportHeight = $state(0);
+  let previousItemCount = 0;
+  let hasObservedItemCount = false;
+  let shouldStickAfterAppend = false;
+
+  const resolvedItemHeight = $derived(resolveVirtualItemHeight(itemHeight));
+  const resolvedOverscan = $derived(resolveVirtualOverscan(overscan));
+  const viewportHeight = $derived(
+    measuredViewportHeight || estimateViewportHeight(height, resolvedItemHeight),
+  );
+  const virtualWindow = $derived(
+    getFixedVirtualWindow({
+      itemCount: items.length,
+      itemHeight: resolvedItemHeight,
+      scrollOffset,
+      viewportHeight,
+      overscan: resolvedOverscan,
+      getKey: (index) => {
+        const item = items[index];
+        return item === undefined ? index : (getKey?.(item, index) ?? index);
+      },
+    }),
+  );
+  const renderedItems = $derived(
+    virtualWindow.items.flatMap((virtualItem) => {
+      const item = items[virtualItem.index];
+      return item === undefined ? [] : [{ ...virtualItem, item }];
+    }),
+  );
+
+  $effect(() => {
+    const element = scrollElement;
+    if (!element) return;
+    syncViewport(element);
+  });
+
+  const observeResize = useResizeObserver(() => {
+    if (scrollElement) syncViewport(scrollElement);
+  });
+
+  $effect.pre(() => {
+    const itemCount = items.length;
+    const element = scrollElement;
+
+    if (!hasObservedItemCount) {
+      previousItemCount = itemCount;
+      hasObservedItemCount = true;
+      shouldStickAfterAppend = false;
+      return;
+    }
+
+    shouldStickAfterAppend =
+      stickToBottom &&
+      element !== undefined &&
+      itemCount > previousItemCount &&
+      isAtBottom(element, previousItemCount * resolvedItemHeight, viewportHeight);
+
+    previousItemCount = itemCount;
+  });
+
+  $effect(() => {
+    const itemCount = items.length;
+    const element = scrollElement;
+    if (!stickToBottom || !shouldStickAfterAppend || !element) return;
+
+    void tick().then(() => {
+      element.scrollTop = maxScrollOffset(itemCount * resolvedItemHeight, viewportHeight);
+      syncViewport(element);
+      shouldStickAfterAppend = false;
+    });
+  });
+
+  function estimateViewportHeight(value: string | undefined, resolvedRowHeight: number): number {
+    return parsePixelLength(value) ?? resolvedRowHeight * 10;
+  }
+
+  function syncViewport(element: HTMLElement): void {
+    const rect = element.getBoundingClientRect();
+    measuredViewportHeight =
+      rect.height || element.clientHeight || parsePixelLength(height) || resolvedItemHeight * 10;
+    scrollOffset = Math.max(0, element.scrollTop);
+  }
+
+  function handleScroll(event: UIEvent & { currentTarget: EventTarget & HTMLDivElement }): void {
+    if (typeof onScroll === 'function') onScroll(event);
+    const element = event.currentTarget as HTMLElement;
+    scrollOffset = Math.max(0, element.scrollTop);
+  }
+
+  function maxScrollOffset(totalSize: number, height: number): number {
+    return Math.max(0, totalSize - height);
+  }
+
+  function isAtBottom(element: HTMLElement, totalSize: number, height: number): boolean {
+    return element.scrollTop >= maxScrollOffset(totalSize, height) - 1;
+  }
+</script>
+
+<svelte:element
+  this={'div'}
+  {...rest}
+  bind:this={scrollElement}
+  {@attach observeResize}
+  class={classNames('cinder-virtual-list', className)}
+  {role}
+  {tabindex}
+  data-cinder-stick-to-bottom={stickToBottom ? 'true' : undefined}
+  style:--cinder-virtual-list-height={height}
+  onscroll={handleScroll}
+>
+  <div
+    class="cinder-virtual-list__spacer"
+    style:height={`${virtualWindow.totalSize}px`}
+    aria-hidden={items.length === 0 ? 'true' : undefined}
+  >
+    <div class="cinder-virtual-list__window" style:top={`${virtualWindow.leadingSize}px`}>
+      {#each renderedItems as virtualItem (virtualItem.key)}
+        <div
+          class="cinder-virtual-list__row"
+          role={role === 'list' ? 'listitem' : undefined}
+          data-cinder-virtual-index={virtualItem.index}
+          style:height={`${virtualItem.size}px`}
+        >
+          {@render row(virtualItem.item, {
+            index: virtualItem.index,
+            key: virtualItem.key,
+            start: virtualItem.start,
+            size: virtualItem.size,
+          })}
+        </div>
+      {/each}
+    </div>
+  </div>
+</svelte:element>

package/src/components/virtual-list/virtual-list.types.ts

@@ -0,0 +1,60 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+import type { VirtualListKey } from '../../utilities/fixed-virtual-window.ts';
+
+export type VirtualListRowContext = {
+  /** Zero-based index of the item in the full items array. */
+  index: number;
+  /** Stable key used for the rendered row. */
+  key: VirtualListKey;
+  /** Pixel offset from the top of the full virtual list. */
+  start: number;
+  /** Pixel height of this fixed-height row. */
+  size: number;
+};
+
+export type VirtualListProps<Item = unknown> = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'class' | 'tabindex'
+> & {
+  /** Items in full logical order. Only the visible window is mounted. */
+  items: readonly Item[];
+  /**
+   * Fixed row height in pixels. Variable and measured row heights are out of
+   * scope for v1; pass the known or estimated fixed height for every row.
+   */
+  itemHeight: number;
+  /**
+   * Extra rows rendered before and after the visible window.
+   * Defaults to 5.
+   */
+  overscan?: number;
+  /**
+   * CSS block-size for the native scroll container.
+   * Defaults to `"20rem"`.
+   */
+  height?: string;
+  /**
+   * When true, appending items while the viewport is already at the bottom
+   * keeps the newest item pinned in view. Appending while scrolled up leaves the
+   * scroll position unchanged.
+   */
+  stickToBottom?: boolean;
+  /**
+   * Override the default focus behavior. The component sets `tabindex="0"`
+   * by default so keyboard users can reach the native scroll container for
+   * arrow-key scrolling. Pass `tabindex={-1}` when the viewport should be
+   * programmatically focusable without entering the tab order.
+   */
+  tabindex?: number;
+  /**
+   * Stable key extractor. Omit only when items are append-only and never
+   * reordered; the component will fall back to full-array indexes.
+   */
+  getKey?: (item: Item, index: number) => VirtualListKey;
+  /** Rendered row snippet. Receives the item and its virtual row context. */
+  row: Snippet<[Item, VirtualListRowContext]>;
+  /** Additional class names merged with `.cinder-virtual-list`. */
+  class?: string;
+};

package/src/components/visually-hidden/README.md

@@ -16,11 +16,12 @@ Hides content visually while keeping it accessible to screen readers; supports s
 
 <!-- generated:props:start -->
 
-| Prop        | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required | Default  | Description                                          |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | ---------------------------------------------------- |
-| `as`        | `"object"` \| `"a"` \| `"abbr"` \| `"address"` \| `"article"` \| `"aside"` \| `"audio"` \| `"b"` \| `"bdi"` \| `"bdo"` \| `"blockquote"` \| `"body"` \| `"button"` \| `"canvas"` \| `"caption"` \| `"cite"` \| `"code"` \| `"colgroup"` \| `"data"` \| `"datalist"` \| `"dd"` \| `"del"` \| `"details"` \| `"dfn"` \| `"dialog"` \| `"div"` \| `"dl"` \| `"dt"` \| `"em"` \| `"fieldset"` \| `"figcaption"` \| `"figure"` \| `"footer"` \| `"form"` \| `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"head"` \| `"header"` \| `"hgroup"` \| `"html"` \| `"i"` \| `"iframe"` \| `"ins"` \| `"kbd"` \| `"label"` \| `"legend"` \| `"li"` \| `"main"` \| `"map"` \| `"mark"` \| `"menu"` \| `"meter"` \| `"nav"` \| `"noscript"` \| `"ol"` \| `"optgroup"` \| `"option"` \| `"output"` \| `"p"` \| `"picture"` \| `"pre"` \| `"progress"` \| `"q"` \| `"rp"` \| `"rt"` \| `"ruby"` \| `"s"` \| `"samp"` \| `"script"` \| `"search"` \| `"section"` \| `"select"` \| `"slot"` \| `"small"` \| `"span"` \| `"strong"` \| `"style"` \| `"sub"` \| `"summary"` \| `"sup"` \| `"table"` \| `"tbody"` \| `"td"` \| `"template"` \| `"textarea"` \| `"tfoot"` \| `"th"` \| `"thead"` \| `"time"` \| `"title"` \| `"tr"` \| `"u"` \| `"ul"` \| `"var"` \| `"video"` | no       | `"span"` | Element tag to render.                               |
-| `class`     | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no       | —        | Additional classes merged after the utility classes. |
-| `focusable` | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `false`  | Reveal the element fully when focused.               |
+| Prop        | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                            |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `as`        | `"object"` \| `"a"` \| `"abbr"` \| `"address"` \| `"article"` \| `"aside"` \| `"audio"` \| `"b"` \| `"bdi"` \| `"bdo"` \| `"blockquote"` \| `"body"` \| `"button"` \| `"canvas"` \| `"caption"` \| `"cite"` \| `"code"` \| `"colgroup"` \| `"data"` \| `"datalist"` \| `"dd"` \| `"del"` \| `"details"` \| `"dfn"` \| `"dialog"` \| `"div"` \| `"dl"` \| `"dt"` \| `"em"` \| `"fieldset"` \| `"figcaption"` \| `"figure"` \| `"footer"` \| `"form"` \| `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"head"` \| `"header"` \| `"hgroup"` \| `"html"` \| `"i"` \| `"iframe"` \| `"ins"` \| `"kbd"` \| `"label"` \| `"legend"` \| `"li"` \| `"main"` \| `"map"` \| `"mark"` \| `"menu"` \| `"meter"` \| `"nav"` \| `"noscript"` \| `"ol"` \| `"optgroup"` \| `"option"` \| `"output"` \| `"p"` \| `"picture"` \| `"pre"` \| `"progress"` \| `"q"` \| `"rp"` \| `"rt"` \| `"ruby"` \| `"s"` \| `"samp"` \| `"script"` \| `"search"` \| `"section"` \| `"select"` \| `"slot"` \| `"small"` \| `"span"` \| `"strong"` \| `"style"` \| `"sub"` \| `"summary"` \| `"sup"` \| `"table"` \| `"tbody"` \| `"td"` \| `"template"` \| `"textarea"` \| `"tfoot"` \| `"th"` \| `"thead"` \| `"time"` \| `"title"` \| `"tr"` \| `"u"` \| `"ul"` \| `"var"` \| `"video"` | no       | `"span"` | Element tag to render.                                                                                                                                                                                                                                                                                                                                                                                 |
+| `class`     | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | no       | —        | Additional classes merged after the utility classes.                                                                                                                                                                                                                                                                                                                                                   |
+| `focusable` | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | no       | `false`  | Reveal the element fully when focused.                                                                                                                                                                                                                                                                                                                                                                 |
+| `children`  | `(opaque)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | yes      | —        | Required content — must render something assistive technology can announce. The render site uses optional chaining (`children?.()`) as a JS-consumer safety net, but omitting children defeats the entire purpose of this component: an empty `.cinder-sr-only` announces nothing to AT. Always provide meaningful content. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/waveform/README.md

@@ -26,17 +26,19 @@ Responsive SVG rendering of time-domain audio amplitude data as a waveform path
 
 <!-- generated:props:start -->
 
-| Prop                  | Type                                                | Required | Default | Description |
-| --------------------- | --------------------------------------------------- | -------- | ------- | ----------- |
-| `class`               | `string`                                            | no       | —       |             |
-| `data`                | `number`[]                                          | yes      | —       |             |
-| `dataTableCaption`    | `string`                                            | no       | —       |             |
-| `dataTableVisibility` | `"screen-reader-only"` \| `"visible"` \| `"hidden"` | no       | —       |             |
-| `description`         | `string`                                            | no       | —       |             |
-| `height`              | `number`                                            | no       | —       |             |
-| `label`               | `string`                                            | yes      | —       |             |
-| `loading`             | `boolean`                                           | no       | —       |             |
-| `renderMode`          | `"path"` \| `"bars"`                                | no       | —       |             |
+| Prop                  | Type                                                | Required | Default | Description                                                                                                             |
+| --------------------- | --------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `class`               | `string`                                            | no       | —       | Custom class applied to the root element.                                                                               |
+| `data`                | `number`[]                                          | yes      | —       | Time-domain amplitude samples. Each value should be in the range [-1, 1]; values outside this range are clamped.        |
+| `dataTableCaption`    | `string`                                            | no       | —       | Custom data table caption; falls back to `label`.                                                                       |
+| `dataTableVisibility` | `"screen-reader-only"` \| `"visible"` \| `"hidden"` | no       | —       | Controls data table visibility. Default `screen-reader-only`.                                                           |
+| `description`         | `string`                                            | no       | —       | Optional description rendered below the label.                                                                          |
+| `height`              | `number`                                            | no       | —       | Pixel height of the chart. Default `80`.                                                                                |
+| `label`               | `string`                                            | yes      | —       | Accessible label for the waveform. Required for screen readers.                                                         |
+| `loading`             | `boolean`                                           | no       | —       | Whether the waveform is in a loading state. Default `false`.                                                            |
+| `renderMode`          | `"path"` \| `"bars"`                                | no       | —       | How to render the waveform: as a continuous path or vertical amplitude bars. Default `path`.                            |
+| `empty`               | `(opaque)`                                          | no       | —       | Snippet rendered when the chart has no data. Not expressible in JSON Schema; see the component types for the signature. |
+| `loadingContent`      | `(opaque)`                                          | no       | —       | Snippet rendered while loading. Not expressible in JSON Schema; see the component types for the signature.              |
 
 <!-- generated:props:end -->
 

package/src/components/waveform/waveform.examples.json

@@ -9,6 +9,18 @@
       "description": "Pre-computed audio amplitude samples rendered as vertical amplitude bars.",
       "code": "<script lang=\"ts\">\n  import { Waveform } from '@lostgradient/cinder/waveform';\n\n  // Simulate a voice recording envelope (louder in the middle) with deterministic noise\n  const voiceData = Array.from({ length: 128 }, (_, index) => {\n    const envelope = Math.sin((index / 128) * Math.PI);\n    // Deterministic pseudo-noise using multiple harmonics\n    const noise = (Math.sin(index * 7.3) + Math.sin(index * 13.7) + Math.sin(index * 23.1)) / 7.5;\n    return Math.max(-1, Math.min(1, envelope * 0.8 + noise));\n  });\n</script>\n\n<Waveform\n  label=\"Voice recording waveform\"\n  description=\"Simulated voice recording amplitude envelope displayed as bars.\"\n  data={voiceData}\n  renderMode=\"bars\"\n  height={80}\n/>\n"
     },
+    {
+      "id": "empty",
+      "title": "Empty state",
+      "description": "When `data` is empty, supply an `empty` snippet to explain the absence instead of rendering a flat, meaningless plot.",
+      "code": "<script lang=\"ts\">\n  import { Waveform } from '@lostgradient/cinder/waveform';\n</script>\n\n<Waveform label=\"Voice recording waveform\" data={[]} height={80}>\n  {#snippet empty()}\n    No recording captured yet.\n  {/snippet}\n</Waveform>\n"
+    },
+    {
+      "id": "loading",
+      "title": "Loading state",
+      "description": "While audio is being decoded, set `loading` and supply a `loadingContent` snippet to render a placeholder over the viewport instead of the plot.",
+      "code": "<script lang=\"ts\">\n  import { Waveform } from '@lostgradient/cinder/waveform';\n</script>\n\n<Waveform label=\"Voice recording waveform\" data={[]} height={80} loading>\n  {#snippet loadingContent()}\n    Decoding audio…\n  {/snippet}\n</Waveform>\n"
+    },
     {
       "id": "sine-wave-path",
       "title": "Sine wave (path mode)",

package/src/components/waveform/waveform.svelte

@@ -20,6 +20,7 @@
 <script lang="ts">
   import { dataTableClass } from '../../_internal/chart/chart-utilities.ts';
   import { classNames } from '../../utilities/class-names.ts';
+  import { useResizeObserver } from '../../utilities/use-resize-observer.svelte.ts';
   import type { WaveformProps } from './waveform.types.ts';
 
   let {
@@ -43,25 +44,12 @@
   const descriptionId = $derived(description ? `${rootId}-description` : undefined);
 
   let measuredWidth = $state(400);
-  let rootElement = $state<HTMLElement>();
 
-  $effect(() => {
-    const element = rootElement;
-    if (!element) return;
-    // Guard for SSR / test environments without ResizeObserver.
-    if (typeof ResizeObserver === 'undefined') {
-      const rect = element.getBoundingClientRect();
-      if (rect.width > 0) measuredWidth = rect.width;
-      return;
-    }
-    const observer = new ResizeObserver((entries) => {
-      const entry = entries[0];
-      // Ignore zero-width measurements (hidden / display:none) so the last good
-      // width is kept rather than collapsing the geometry, matching the fallback.
-      if (entry && entry.contentRect.width > 0) measuredWidth = entry.contentRect.width;
-    });
-    observer.observe(element);
-    return () => observer.disconnect();
+  const observeResize = useResizeObserver((entries) => {
+    const entry = entries[0];
+    // Ignore zero-width measurements (hidden / display:none) so the last good
+    // width is kept rather than collapsing the geometry.
+    if (entry && entry.contentRect.width > 0) measuredWidth = entry.contentRect.width;
   });
 
   const isEmpty = $derived(data.length === 0);
@@ -204,7 +192,7 @@
 
 <figure
   {...rest}
-  bind:this={rootElement}
+  {@attach observeResize}
   id={rootId}
   class={classNames('cinder-waveform', customClassName)}
   aria-label={label}

package/src/components/waveform/waveform.types.ts

@@ -33,13 +33,22 @@ export type WaveformProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
 };
 
 export type WaveformSchemaProps = {
+  /** Accessible label for the waveform. Required for screen readers. */
   label: string;
+  /** Optional description rendered below the label. */
   description?: string;
+  /** Time-domain amplitude samples. Each value should be in the range [-1, 1]; values outside this range are clamped. */
   data: number[];
+  /** How to render the waveform: as a continuous path or vertical amplitude bars. Default `path`. */
   renderMode?: WaveformRenderMode;
+  /** Pixel height of the chart. Default `80`. */
   height?: number;
+  /** Whether the waveform is in a loading state. Default `false`. */
   loading?: boolean;
+  /** Controls data table visibility. Default `screen-reader-only`. */
   dataTableVisibility?: ChartDataTableVisibility;
+  /** Custom data table caption; falls back to `label`. */
   dataTableCaption?: string;
+  /** Custom class applied to the root element. */
   class?: string;
 };