@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/speed-dial/speed-dial.svelte

@@ -0,0 +1,205 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category action
+   * @status beta
+   * @purpose Floating action cluster that reveals secondary quick actions around a primary FloatingActionButton trigger.
+   * @tag action
+   * @tag floating
+   * @useWhen One primary floating action needs a small set of closely related quick actions.
+   * @avoidWhen The actions are equally important and always visible - use toolbar instead. | toolbar
+   * @avoidWhen The trigger should open rich contextual content - use popover instead. | popover
+   * @related floating-action-button, toolbar, popover
+   */
+  export type {
+    SpeedDialContext,
+    SpeedDialDirection,
+    SpeedDialProps,
+    SpeedDialSchemaProps,
+  } from './speed-dial.types.ts';
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../utilities/class-names.ts';
+  import { handleRovingKeydown } from '../../utilities/roving-tabindex.ts';
+  import FloatingActionButton from '../floating-action-button/floating-action-button.svelte';
+  import { setSpeedDialContext } from './speed-dial.context.ts';
+  import type { SpeedDialProps } from './speed-dial.types.ts';
+
+  const actionsId = $props.id();
+  const defaultAriaLabel = 'Quick actions';
+
+  let {
+    open = $bindable(false),
+    direction = 'up',
+    hidden = false,
+    'aria-label': ariaLabel = defaultAriaLabel,
+    trigger,
+    children,
+    class: customClassName,
+    ...rest
+  }: SpeedDialProps = $props();
+
+  let rootElement = $state<HTMLDivElement | null>(null);
+  let triggerWrapperElement = $state<HTMLDivElement | null>(null);
+  const actionButtons: HTMLButtonElement[] = [];
+
+  const orientation = $derived(
+    direction === 'left' || direction === 'right' ? 'horizontal' : 'vertical',
+  );
+  const accessibleLabel = $derived(normalizeAriaLabel(ariaLabel));
+
+  function normalizeAriaLabel(label: string | null | undefined): string {
+    const trimmed = label?.trim() ?? '';
+    return trimmed.length > 0 ? trimmed : defaultAriaLabel;
+  }
+
+  function getTriggerElement(): HTMLElement | null {
+    return triggerWrapperElement?.querySelector<HTMLElement>('.cinder-fab') ?? null;
+  }
+
+  function getEnabledActionButtons(): HTMLButtonElement[] {
+    return actionButtons.filter((button) => !button.disabled);
+  }
+
+  function getKeyboardNavigationButtons(): HTMLButtonElement[] {
+    const enabledButtons = getEnabledActionButtons();
+    return direction === 'up' || direction === 'left'
+      ? [...enabledButtons].reverse()
+      : enabledButtons;
+  }
+
+  function focusTrigger(): void {
+    queueMicrotask(() => getTriggerElement()?.focus());
+  }
+
+  function close(options: { focusTrigger?: boolean } = {}): void {
+    open = false;
+    if (options.focusTrigger) focusTrigger();
+  }
+
+  function register(button: HTMLButtonElement): void {
+    if (actionButtons.includes(button)) return;
+    actionButtons.push(button);
+  }
+
+  function unregister(button: HTMLButtonElement): void {
+    const index = actionButtons.indexOf(button);
+    if (index === -1) return;
+    actionButtons.splice(index, 1);
+  }
+
+  function toggleOpen(): void {
+    if (hidden) return;
+    open = !open;
+  }
+
+  function handleTriggerKeydown(event: KeyboardEvent): void {
+    if (hidden) return;
+
+    if (
+      event.key !== 'ArrowUp' &&
+      event.key !== 'ArrowDown' &&
+      event.key !== 'ArrowLeft' &&
+      event.key !== 'ArrowRight'
+    ) {
+      return;
+    }
+
+    event.preventDefault();
+    open = true;
+    queueMicrotask(() => getEnabledActionButtons()[0]?.focus());
+  }
+
+  function handleActionsKeydown(event: KeyboardEvent): void {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      close({ focusTrigger: true });
+      return;
+    }
+
+    const target = event.target instanceof HTMLButtonElement ? event.target : null;
+    if (!target) return;
+
+    const enabledButtons = getKeyboardNavigationButtons();
+    const currentIndex = enabledButtons.indexOf(target);
+    if (currentIndex === -1) return;
+
+    const nextIndex = handleRovingKeydown(event, currentIndex, enabledButtons.length, {
+      horizontal: orientation === 'horizontal',
+      vertical: orientation === 'vertical',
+    });
+    if (nextIndex === null) return;
+
+    event.preventDefault();
+    enabledButtons[nextIndex]?.focus();
+  }
+
+  function handleDocumentClick(event: MouseEvent): void {
+    if (!open) return;
+    if (rootElement?.contains(event.target as Node)) return;
+    close({ focusTrigger: rootElement?.contains(document.activeElement) ?? false });
+  }
+
+  $effect(() => {
+    if (!open) return;
+    queueMicrotask(() => getEnabledActionButtons()[0]?.focus());
+  });
+
+  setSpeedDialContext({
+    get isOpen() {
+      return open;
+    },
+    get direction() {
+      return direction;
+    },
+    close,
+    focusTrigger,
+    register,
+    unregister,
+  });
+</script>
+
+<svelte:document onclick={handleDocumentClick} />
+
+<div
+  {...rest}
+  bind:this={rootElement}
+  hidden={hidden ? true : undefined}
+  role="group"
+  aria-label={accessibleLabel}
+  aria-hidden={hidden ? 'true' : undefined}
+  inert={hidden ? true : undefined}
+  class={classNames('cinder-speed-dial', customClassName)}
+  data-cinder-open={open ? 'true' : 'false'}
+  data-cinder-direction={direction}
+  data-cinder-hidden={hidden ? 'true' : undefined}
+>
+  <div
+    id={actionsId}
+    role="toolbar"
+    aria-label="Actions"
+    aria-orientation={orientation}
+    class="cinder-speed-dial__actions"
+    data-cinder-open={open ? 'true' : 'false'}
+    inert={!open ? true : undefined}
+    tabindex="-1"
+    onkeydown={handleActionsKeydown}
+  >
+    {@render children?.()}
+  </div>
+
+  <div bind:this={triggerWrapperElement} class="cinder-speed-dial__trigger">
+    <FloatingActionButton
+      aria-label={accessibleLabel}
+      aria-expanded={open ? 'true' : 'false'}
+      aria-controls={actionsId}
+      disabled={hidden}
+      tabindex={hidden ? -1 : undefined}
+      onclick={toggleOpen}
+      onkeydown={handleTriggerKeydown}
+    >
+      {@render trigger?.()}
+    </FloatingActionButton>
+  </div>
+</div>

package/src/components/speed-dial/speed-dial.types.ts

@@ -0,0 +1,59 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** Direction that SpeedDial actions fan out from the trigger. */
+export type SpeedDialDirection = 'up' | 'down' | 'left' | 'right';
+
+/** Shared context between SpeedDial and SpeedDial.Action. */
+export type SpeedDialContext = {
+  get isOpen(): boolean;
+  get direction(): SpeedDialDirection;
+  close: (options?: { focusTrigger?: boolean }) => void;
+  focusTrigger: () => void;
+  register: (button: HTMLButtonElement) => void;
+  unregister: (button: HTMLButtonElement) => void;
+};
+
+/** Props for the SpeedDial component. */
+export type SpeedDialProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'aria-label' | 'children' | 'class' | 'hidden'
+> & {
+  /** Bindable open state. Trigger, Escape, outside click, and action activation update it. */
+  open?: boolean;
+  /** Direction the actions fan out. */
+  direction?: SpeedDialDirection;
+  /** Applies the native hidden attribute and makes the whole control inert. */
+  hidden?: boolean;
+  /** Accessible label for the root group and trigger button. */
+  'aria-label'?: string;
+  /** Trigger icon or content rendered inside the FloatingActionButton. */
+  trigger: Snippet;
+  /** `SpeedDial.Action` children. */
+  children: Snippet;
+  /** Custom class merged with `.cinder-speed-dial`. */
+  class?: string;
+};
+
+/** Schema-facing props for SpeedDial. */
+export interface SpeedDialSchemaProps {
+  /**
+   * Bindable open state. Trigger, Escape, outside click, and action activation update it.
+   * @default false
+   */
+  open?: boolean;
+  /**
+   * Direction the actions fan out.
+   * @default "up"
+   */
+  direction?: SpeedDialDirection;
+  /**
+   * Applies the native hidden attribute and makes the whole control inert.
+   * @default false
+   */
+  hidden?: boolean;
+  /** Accessible label for the root group and trigger button. */
+  'aria-label'?: string;
+  /** Custom class merged with `.cinder-speed-dial`. */
+  class?: string;
+}

package/src/components/speed-dial-action/README.md

@@ -0,0 +1,51 @@
+# SpeedDialAction
+
+SpeedDialAction is the `SpeedDial.Action` leaf. It must be rendered inside a
+`SpeedDial` parent so it can participate in roving keyboard navigation and close
+the owning dial after activation.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { SpeedDial } from '@lostgradient/cinder/speed-dial';
+</script>
+
+<SpeedDial aria-label="Quick actions">
+  {#snippet trigger()}+{/snippet}
+  <SpeedDial.Action label="Create">
+    {#snippet icon()}C{/snippet}
+  </SpeedDial.Action>
+</SpeedDial>
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop             | Type                                         | Required | Default  | Description                                                                                                                                     |
+| ---------------- | -------------------------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`          | `string`                                     | no       | —        | Custom class merged with `.cinder-speed-dial-action`.                                                                                           |
+| `disabled`       | `boolean`                                    | no       | `false`  | Disables the action and removes it from roving keyboard navigation.                                                                             |
+| `label`          | `string`                                     | yes      | —        | Visible and accessible label for the action.                                                                                                    |
+| `labelPlacement` | `"auto"` \| `"start"` \| `"end"` \| `"none"` | no       | `"auto"` | Placement of the visible label relative to the action button.                                                                                   |
+| `icon`           | `(opaque)`                                   | yes      | —        | Icon or compact content rendered inside the action button. Not expressible in JSON Schema; see the component types for the signature.           |
+| `onclick`        | `(opaque)`                                   | no       | —        | Called when the action is activated. The SpeedDial closes afterward. Not expressible in JSON Schema; see the component types for the signature. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/speed-dial-action/index.ts

@@ -0,0 +1,8 @@
+import SpeedDialAction from './speed-dial-action.svelte';
+
+export default SpeedDialAction;
+export type {
+  SpeedDialActionLabelPlacement,
+  SpeedDialActionProps,
+} from './speed-dial-action.types.ts';
+export { SpeedDialAction };

package/src/components/speed-dial-action/speed-dial-action.svelte

@@ -0,0 +1,77 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category action
+   * @status beta
+   * @purpose Quick-action leaf for SpeedDial that closes the owning dial after activation.
+   * @tag action
+   * @tag floating
+   * @useWhen Rendering a secondary quick action inside SpeedDial.
+   * @avoidWhen Rendering an action outside SpeedDial - use floating-action-button directly. | floating-action-button
+   * @related speed-dial, floating-action-button
+   */
+  export type {
+    SpeedDialActionLabelPlacement,
+    SpeedDialActionProps,
+  } from './speed-dial-action.types.ts';
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../utilities/class-names.ts';
+  import FloatingActionButton from '../floating-action-button/floating-action-button.svelte';
+  import { getSpeedDialContext } from '../speed-dial/speed-dial.context.ts';
+  import type { SpeedDialActionProps } from './speed-dial-action.types.ts';
+
+  const fallbackButtonId = $props.id();
+
+  let {
+    id = fallbackButtonId,
+    label,
+    icon,
+    onclick,
+    disabled = false,
+    labelPlacement = 'auto',
+    class: customClassName,
+    ...rest
+  }: SpeedDialActionProps = $props();
+
+  const context = getSpeedDialContext();
+  let rootElement = $state<HTMLDivElement | null>(null);
+
+  function handleClick(event: MouseEvent): void {
+    if (disabled) return;
+    onclick?.(event);
+    context.close({ focusTrigger: true });
+  }
+
+  $effect(() => {
+    const button = rootElement?.querySelector<HTMLButtonElement>('button.cinder-fab');
+    if (!button) return;
+
+    context.register(button);
+    return () => context.unregister(button);
+  });
+</script>
+
+<div
+  bind:this={rootElement}
+  class={classNames('cinder-speed-dial-action', customClassName)}
+  data-cinder-label-placement={labelPlacement}
+  data-cinder-open={context.isOpen ? 'true' : 'false'}
+  data-cinder-direction={context.direction}
+>
+  <FloatingActionButton
+    {...rest}
+    {id}
+    size="sm"
+    aria-label={label}
+    {disabled}
+    onclick={handleClick}
+  >
+    {@render icon?.()}
+  </FloatingActionButton>
+
+  {#if labelPlacement !== 'none'}
+    <label for={id} class="cinder-speed-dial-action__label" aria-hidden="true">{label}</label>
+  {/if}
+</div>

package/src/components/speed-dial-action/speed-dial-action.types.ts

@@ -0,0 +1,50 @@
+import type { Snippet } from 'svelte';
+
+import type { FloatingActionButtonProps } from '../floating-action-button/floating-action-button.types.ts';
+
+/** Label placement for a SpeedDial.Action. */
+export type SpeedDialActionLabelPlacement = 'auto' | 'start' | 'end' | 'none';
+
+type FloatingActionButtonButtonProps = Extract<FloatingActionButtonProps, { href?: undefined }>;
+
+type SpeedDialActionButtonAttributes = Omit<
+  FloatingActionButtonButtonProps,
+  'aria-label' | 'children' | 'class' | 'disabled' | 'onclick' | 'size' | 'type'
+>;
+
+/** Props for the SpeedDialAction component. */
+export type SpeedDialActionProps = SpeedDialActionButtonAttributes & {
+  /** Visible and accessible label for the action. */
+  label: string;
+  /** Icon or compact content rendered inside the action button. */
+  icon: Snippet;
+  /** Called when the action is activated. The SpeedDial closes afterward. */
+  onclick?: (event: MouseEvent) => void;
+  /** Disables the action and removes it from roving keyboard navigation. */
+  disabled?: boolean;
+  /**
+   * Placement of the visible label relative to the action button.
+   * @default "auto"
+   */
+  labelPlacement?: SpeedDialActionLabelPlacement;
+  /** Custom class merged with `.cinder-speed-dial-action`. */
+  class?: string;
+};
+
+/** Schema-facing props for SpeedDialAction. */
+export interface SpeedDialActionSchemaProps {
+  /** Visible and accessible label for the action. */
+  label: string;
+  /**
+   * Disables the action and removes it from roving keyboard navigation.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Placement of the visible label relative to the action button.
+   * @default "auto"
+   */
+  labelPlacement?: SpeedDialActionLabelPlacement;
+  /** Custom class merged with `.cinder-speed-dial-action`. */
+  class?: string;
+}

package/src/components/stacked-list-item/README.md

@@ -6,10 +6,20 @@ Single row within a stacked list, typically pairing a label with metadata or an
 
 ```svelte
 <script lang="ts">
-  import StackedListItem from '@lostgradient/cinder/stacked-list-item';
+  import { DataList } from '@lostgradient/cinder/data-list';
+  import { StackedListItem } from '@lostgradient/cinder/stacked-list-item';
+
+  const members = [{ id: 'alice', name: 'Alice Chen', role: 'Engineer' }];
 </script>
 
-<StackedListItem />
+<DataList items={members} key={(member) => member.id}>
+  {#snippet children(member)}
+    <StackedListItem>
+      {#snippet title()}{member.name}{/snippet}
+      {#snippet meta()}{member.role}{/snippet}
+    </StackedListItem>
+  {/snippet}
+</DataList>
 ```
 
 ## Props
@@ -20,15 +30,15 @@ Single row within a stacked list, typically pairing a label with metadata or an
 | ------------- | -------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `class`       | `string`                         | no       | —       | Merged with `cinder-stacked-list-item`.                                                                                                                                                                                     |
 | `density`     | `"comfortable"` \| `"condensed"` | no       | —       | Density token surfaced as `data-cinder-density`. When omitted, inherits the enclosing DataList's list-level `density` (if any), then falls back to `comfortable`. An explicit value here always overrides the list default. |
-| `href`        | `string`                         | no       | —       |                                                                                                                                                                                                                             |
-| `hreflang`    | `string` \| `null`               | no       | —       |                                                                                                                                                                                                                             |
-| `rel`         | `string` \| `null`               | no       | —       |                                                                                                                                                                                                                             |
-| `description` | `(opaque)`                       | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                  |
-| `leading`     | `(opaque)`                       | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                  |
-| `meta`        | `(opaque)`                       | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                  |
-| `target`      | `(opaque)`                       | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                     |
-| `title`       | `(opaque)`                       | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                  |
-| `trailing`    | `(opaque)`                       | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                  |
+| `href`        | `string`                         | no       | —       | Destination URL that turns the `title` snippet into an `<a>` link for the row.                                                                                                                                              |
+| `hreflang`    | `string` \| `null`               | no       | —       | `hreflang` attribute forwarded to the title anchor, indicating the language of the linked resource.                                                                                                                         |
+| `rel`         | `string` \| `null`               | no       | —       | `rel` attribute forwarded to the title anchor; `noopener noreferrer` is merged automatically when `target="_blank"`.                                                                                                        |
+| `description` | `(opaque)`                       | no       | —       | Secondary description below the title. Not expressible in JSON Schema; see the component types for the signature.                                                                                                           |
+| `leading`     | `(opaque)`                       | no       | —       | Leading visual (avatar, icon, status dot). Not expressible in JSON Schema; see the component types for the signature.                                                                                                       |
+| `meta`        | `(opaque)`                       | no       | —       | Tertiary metadata (timestamp, badge, system label). Not expressible in JSON Schema; see the component types for the signature.                                                                                              |
+| `target`      | `(opaque)`                       | no       | —       | Browsing context for the title anchor (`_blank`, `_self`, `_parent`, `_top`, or a named frame). Not expressible in JSON Schema; see the component types for the signature.                                                  |
+| `title`       | `(opaque)`                       | yes      | —       | Primary label. Required. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                         |
+| `trailing`    | `(opaque)`                       | no       | —       | Trailing region (chevron, action button, dropdown trigger). Not expressible in JSON Schema; see the component types for the signature.                                                                                      |
 
 <!-- generated:props:end -->
 

package/src/components/stacked-list-item/stacked-list-item.examples.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "stacked-list-item",
+  "import": "@lostgradient/cinder/stacked-list-item",
+  "examples": [
+    {
+      "id": "as-link",
+      "title": "Navigable link rows",
+      "description": "Passing `href` turns the `title` snippet into an `<a>`, making the whole row a navigable link.",
+      "code": "<script lang=\"ts\">\n  import { DataList } from '@lostgradient/cinder/data-list';\n  import { StackedListItem } from '@lostgradient/cinder/stacked-list-item';\n\n  const docs = [\n    { id: 'getting-started', name: 'Getting started', href: '#getting-started' },\n    { id: 'theming', name: 'Theming', href: '#theming' },\n    { id: 'accessibility', name: 'Accessibility', href: '#accessibility' },\n  ];\n</script>\n\n<DataList items={docs} key={(doc) => doc.id}>\n  {#snippet children(doc)}\n    <StackedListItem href={doc.href}>\n      {#snippet title()}{doc.name}{/snippet}\n    </StackedListItem>\n  {/snippet}\n</DataList>\n"
+    },
+    {
+      "id": "basic",
+      "title": "Basic row",
+      "description": "A minimal StackedListItem with the required `title` snippet and a `meta` snippet, mounted inside the DataList container it is designed to compose with.",
+      "code": "<script lang=\"ts\">\n  import { DataList } from '@lostgradient/cinder/data-list';\n  import { StackedListItem } from '@lostgradient/cinder/stacked-list-item';\n\n  const members = [\n    { id: 'alice', name: 'Alice Chen', role: 'Engineer' },\n    { id: 'bob', name: 'Bob Osei', role: 'Designer' },\n    { id: 'carol', name: 'Carol Mwangi', role: 'Product' },\n  ];\n</script>\n\n<DataList items={members} key={(member) => member.id}>\n  {#snippet children(member)}\n    <StackedListItem>\n      {#snippet title()}{member.name}{/snippet}\n      {#snippet meta()}{member.role}{/snippet}\n    </StackedListItem>\n  {/snippet}\n</DataList>\n"
+    },
+    {
+      "id": "with-description-and-icon",
+      "title": "With description and leading icon",
+      "description": "A richer row pairing a `leading` visual (here a StatusDot) with a `title` and a secondary `description` snippet below it.",
+      "code": "<script lang=\"ts\">\n  import { DataList } from '@lostgradient/cinder/data-list';\n  import { StackedListItem } from '@lostgradient/cinder/stacked-list-item';\n  import { StatusDot } from '@lostgradient/cinder/status-dot';\n\n  const services = [\n    {\n      id: 'api',\n      name: 'API gateway',\n      detail: 'All regions healthy',\n      status: 'online' as const,\n      statusLabel: 'Online',\n    },\n    {\n      id: 'db',\n      name: 'Primary database',\n      detail: 'Replication lag 1.2s',\n      status: 'warning' as const,\n      statusLabel: 'Warning',\n    },\n    {\n      id: 'cache',\n      name: 'Cache cluster',\n      detail: 'Node 3 unreachable',\n      status: 'error' as const,\n      statusLabel: 'Error',\n    },\n  ];\n</script>\n\n<DataList items={services} key={(service) => service.id}>\n  {#snippet children(service)}\n    <StackedListItem>\n      {#snippet leading()}\n        <StatusDot status={service.status} label={service.statusLabel} />\n      {/snippet}\n      {#snippet title()}{service.name}{/snippet}\n      {#snippet description()}{service.detail}{/snippet}\n    </StackedListItem>\n  {/snippet}\n</DataList>\n"
+    }
+  ]
+}

package/src/components/stacked-list-item/stacked-list-item.types.ts

@@ -35,9 +35,13 @@ type StackedListItemStatic = StackedListItemBase & {
 };
 /** Linkified row — `title` snippet renders as `<a href>`. */
 type StackedListItemLinked = StackedListItemBase & {
+  /** Destination URL that turns the `title` snippet into an `<a>` link for the row. */
   href: string;
+  /** Browsing context for the title anchor (`_blank`, `_self`, `_parent`, `_top`, or a named frame). */
   target?: HTMLAnchorAttributes['target'];
+  /** `rel` attribute forwarded to the title anchor; `noopener noreferrer` is merged automatically when `target="_blank"`. */
   rel?: HTMLAnchorAttributes['rel'];
+  /** `hreflang` attribute forwarded to the title anchor, indicating the language of the linked resource. */
   hreflang?: HTMLAnchorAttributes['hreflang'];
 };
 export type StackedListItemProps = StackedListItemStatic | StackedListItemLinked;

package/src/components/stat/README.md

@@ -2,13 +2,13 @@
 
 Single metric tile displaying a labelled numeric value with optional trend or unit.
 
-## When to use
+## Choosing this component
 
 - Surfacing a single KPI or headline number in a dashboard or summary card (revenue, users, uptime).
 - Pairing related figures — wrap multiple `Stat` tiles in [`StatGroup`](../stat-group/README.md) for consistent grid layout.
 - Showing a trend or change value alongside the primary number via the `change` prop.
 
-## When not to use
+## Choosing something else
 
 - Code-change line counts (+/- additions and removals) — use [`DiffStatistics`](../diff-statistics/README.md), which is purpose-built for that display.
 - Long lists of data points — use a [`Table`](../table/README.md) or [`DataList`](../data-list/README.md) instead.
@@ -30,15 +30,15 @@ snippet. The flat `@lostgradient/cinder/stat` subpath remains exported for
 
 <!-- generated:props:start -->
 
-| Prop                 | Type                 | Required | Default | Description                                                                                                                |
-| -------------------- | -------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`              | `string`             | no       | —       | Additional class names merged with `.cinder-stat`.                                                                         |
-| `label`              | `string`             | yes      | —       | Short label describing the metric, e.g. "Monthly Revenue".                                                                 |
-| `value`              | `string` \| `number` | yes      | —       | The statistic. Strings rendered verbatim; numbers formatted via formatNumber.                                              |
-| `valueLocale`        | `string`             | no       | —       | Locale forwarded to formatNumber (defaults to en-US).                                                                      |
-| `change`             | `(opaque)`           | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `icon`               | `(opaque)`           | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `valueFormatOptions` | `(opaque)`           | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop                 | Type                 | Required | Default | Description                                                                                                                                     |
+| -------------------- | -------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`              | `string`             | no       | —       | Additional class names merged with `.cinder-stat`.                                                                                              |
+| `label`              | `string`             | yes      | —       | Short label describing the metric, e.g. "Monthly Revenue".                                                                                      |
+| `value`              | `string` \| `number` | yes      | —       | The statistic. Strings rendered verbatim; numbers formatted via formatNumber.                                                                   |
+| `valueLocale`        | `string`             | no       | —       | Locale forwarded to formatNumber (defaults to en-US).                                                                                           |
+| `change`             | `(opaque)`           | no       | —       | Optional change indicator with direction and accessible wording. Not expressible in JSON Schema; see the component types for the signature.     |
+| `icon`               | `(opaque)`           | no       | —       | Optional leading icon snippet (decorative — wrapper is aria-hidden). Not expressible in JSON Schema; see the component types for the signature. |
+| `valueFormatOptions` | `(opaque)`           | no       | —       | Intl.NumberFormat options applied only when `value` is a number. Not expressible in JSON Schema; see the component types for the signature.     |
 
 <!-- generated:props:end -->
 

package/src/components/stat-group/README.md

@@ -32,7 +32,7 @@ The leaf remains importable individually for à-la-carte builds — see
 | `columns`  | `1` \| `2` \| `3` \| `4` \| `"auto"`           | no       | `"'auto'"`    | Grid column count. `'auto'` uses auto-fit with minmax for responsive layout.                                                                                                                                                                                           |
 | `label`    | `string`                                       | no       | —             | Optional accessible label for the whole stat set. When provided, the container becomes `role="group"` and uses this value as its accessible name.                                                                                                                      |
 | `variant`  | `"default"` \| `"cards"` \| `"shared-borders"` | no       | `"'default'"` | Visual variant; surfaced as `data-cinder-variant` for CSS styling. - `'default'` — plain grid, no borders or backgrounds. - `'cards'` — each stat gets a card-style border and shadow. - `'shared-borders'` — single outer border with 1px gap dividers between stats. |
-| `children` | `(opaque)`                                     | no       | —             | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                             |
+| `children` | `(opaque)`                                     | yes      | —             | Stat children, typically one or more `<Stat>` components. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                   |
 
 <!-- generated:props:end -->
 

package/src/components/stat-group/stat-group.examples.json

@@ -3,11 +3,29 @@
   "component": "stat-group",
   "import": "@lostgradient/cinder/stat-group",
   "examples": [
+    {
+      "id": "auto-columns",
+      "title": "Responsive auto columns",
+      "description": "Setting `columns` to `auto` switches the grid to CSS auto-fit with minmax, so tiles reflow to fit the available width instead of locking to a fixed column count.",
+      "code": "<script lang=\"ts\">\n  import { StatGroup } from '@lostgradient/cinder/stat-group';\n</script>\n\n<StatGroup label=\"Workspace usage\" columns=\"auto\">\n  <StatGroup.Stat label=\"Projects\" value={42} />\n  <StatGroup.Stat label=\"Members\" value={18} />\n  <StatGroup.Stat label=\"Storage\" value=\"64 GB\" />\n  <StatGroup.Stat label=\"API calls\" value={128400} valueFormatOptions={{ notation: 'compact' }} />\n</StatGroup>\n"
+    },
     {
       "id": "basic",
       "title": "Basic stat group",
       "description": "A row of summary metrics. Uses the StatGroup namespace API: StatGroup.Stat renders each metric inside the parent StatGroup grid.",
       "code": "<script lang=\"ts\">\n  import { StatGroup } from '@lostgradient/cinder/stat-group';\n</script>\n\n<StatGroup label=\"This quarter\" columns={3}>\n  <StatGroup.Stat\n    label=\"Monthly revenue\"\n    value={48250}\n    valueFormatOptions={{ style: 'currency', currency: 'USD', maximumFractionDigits: 0 }}\n    change={{ value: '4.75%', direction: 'up', description: 'from last month' }}\n  />\n  <StatGroup.Stat\n    label=\"Active users\"\n    value={1289}\n    change={{ value: '12', direction: 'up', description: 'this week' }}\n  />\n  <StatGroup.Stat\n    label=\"Churn\"\n    value=\"2.1%\"\n    change={{ value: '0.3%', direction: 'down', description: 'vs prior period' }}\n  />\n</StatGroup>\n"
+    },
+    {
+      "id": "cards-variant",
+      "title": "Cards variant",
+      "description": "The `cards` variant renders each metric as a discrete bordered card, separating the tiles instead of laying them out edge-to-edge in a shared grid.",
+      "code": "<script lang=\"ts\">\n  import { StatGroup } from '@lostgradient/cinder/stat-group';\n</script>\n\n<StatGroup label=\"This quarter\" columns={3} variant=\"cards\">\n  <StatGroup.Stat label=\"Projects\" value={42} />\n  <StatGroup.Stat label=\"Members\" value={18} />\n  <StatGroup.Stat label=\"Storage\" value=\"64 GB\" />\n</StatGroup>\n"
+    },
+    {
+      "id": "shared-borders-variant",
+      "title": "Shared-borders variant",
+      "description": "The `shared-borders` variant wraps the whole set in a single outer border and divides the tiles with 1px gap rules, keeping the grid visually unified.",
+      "code": "<script lang=\"ts\">\n  import { StatGroup } from '@lostgradient/cinder/stat-group';\n</script>\n\n<StatGroup label=\"This quarter\" columns={3} variant=\"shared-borders\">\n  <StatGroup.Stat label=\"Projects\" value={42} />\n  <StatGroup.Stat label=\"Members\" value={18} />\n  <StatGroup.Stat label=\"Storage\" value=\"64 GB\" />\n</StatGroup>\n"
     }
   ]
 }