@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/sidebar/sidebar.svelte

@@ -31,7 +31,7 @@
   let {
     id: sidebarId,
     collapsed = $bindable(false),
-    ariaLabel = 'Sidebar',
+    label = 'Sidebar',
     class: className,
     brand: brandSnippet,
     navigation: navigationSnippet,
@@ -42,10 +42,10 @@
   }: SidebarRuntimeProps = $props();
 
   const validatedLabel = $derived.by(() => {
-    if (ariaLabel.trim() === '') {
-      throw new Error('Sidebar requires a non-empty ariaLabel.');
+    if (label.trim() === '') {
+      throw new Error('Sidebar requires a non-empty label.');
     }
-    return ariaLabel;
+    return label;
   });
 
   // The inner <nav> landmark gets a distinct accessible name so the outer

package/src/components/sidebar/sidebar.types.ts

@@ -20,7 +20,7 @@ export type SidebarProps = Omit<
    * by appending `' navigation'` so screen readers can distinguish the
    * outer complementary region from the inner navigation region.
    */
-  ariaLabel?: string;
+  label?: string;
   /** Additional CSS class merged with `.cinder-sidebar`. */
   class?: string;
   /** Optional branding region rendered above the navigation. */

package/src/components/slider/slider.css

@@ -40,18 +40,18 @@
   .cinder-slider__range {
     position: absolute;
     inset-block: 0;
-    left: var(--_cinder-slider-low);
-    right: calc(100% - var(--_cinder-slider-high));
+    inset-inline-start: var(--_cinder-slider-low);
+    inset-inline-end: calc(100% - var(--_cinder-slider-high));
     background: var(--cinder-accent);
     border-radius: var(--cinder-radius-full);
     transition:
-      left var(--cinder-duration-fast, 120ms) var(--cinder-ease-standard, ease),
-      right var(--cinder-duration-fast, 120ms) var(--cinder-ease-standard, ease);
+      inset-inline-start var(--cinder-duration-fast, 120ms) var(--cinder-ease-standard, ease),
+      inset-inline-end var(--cinder-duration-fast, 120ms) var(--cinder-ease-standard, ease);
   }
 
   .cinder-slider:not(.cinder-slider--range) .cinder-slider__range {
-    left: 0;
-    right: calc(100% - var(--_cinder-slider-low));
+    inset-inline-start: 0;
+    inset-inline-end: calc(100% - var(--_cinder-slider-low));
   }
 
   .cinder-slider__ticks {
@@ -63,7 +63,7 @@
   .cinder-slider__tick {
     position: absolute;
     top: 50%;
-    left: var(--_cinder-slider-tick);
+    inset-inline-start: var(--_cinder-slider-tick);
     width: 2px;
     height: 0.5rem;
     background: var(--cinder-border, currentColor);
@@ -75,7 +75,7 @@
   .cinder-slider__thumb {
     position: absolute;
     top: 50%;
-    left: var(--_cinder-slider-pos);
+    inset-inline-start: var(--_cinder-slider-pos);
     width: var(--_cinder-slider-thumb-size);
     height: var(--_cinder-slider-thumb-size);
     background: var(--cinder-surface-raised, white);
@@ -89,10 +89,15 @@
    * gesture for scrolling when pointerdown lands directly on the thumb. */
     touch-action: none;
     transition:
-      left var(--cinder-duration-fast, 120ms) var(--cinder-ease-standard, ease),
+      inset-inline-start var(--cinder-duration-fast, 120ms) var(--cinder-ease-standard, ease),
       box-shadow var(--cinder-duration-fast, 120ms) var(--cinder-ease-standard, ease);
   }
 
+  .cinder-slider__tick:dir(rtl),
+  .cinder-slider__thumb:dir(rtl) {
+    transform: translate(50%, -50%);
+  }
+
   /* The most recently moved thumb in range mode is raised above its sibling
  * so that when the two values coincide, the active one remains the click
  * target. */

package/src/components/slider/slider.svelte

@@ -25,6 +25,8 @@
   import type { SliderProps, SliderValue } from './slider.types.ts';
   import { untrack } from 'svelte';
   import { getFormFieldContext } from '../../_internal/form-field-context.ts';
+  import { getLocaleContext } from '../../_internal/locale-context.ts';
+  import { observeTextDirection, resolveTextDirection } from '../../_internal/text-direction.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import { devWarn } from '../../utilities/dev-warn.ts';
 
@@ -46,7 +48,24 @@
   }: SliderProps = $props();
 
   const formField = getFormFieldContext();
+  const localeContext = getLocaleContext();
   const disabled = $derived(disabledProp || (formField?.disabled ?? false));
+  let rootElement = $state<HTMLDivElement | null>(null);
+  let directionRevision = $state(0);
+  const resolvedDirection = $derived.by(() => {
+    directionRevision;
+    return rootElement
+      ? resolveTextDirection(rootElement.parentElement, localeContext?.direction)
+      : localeContext?.direction;
+  });
+  const rootDirection = $derived(localeContext?.direction ? resolvedDirection : null);
+  const isRightToLeft = $derived(resolvedDirection === 'rtl');
+
+  $effect(() => {
+    return observeTextDirection(rootElement?.parentElement, () => {
+      directionRevision += 1;
+    });
+  });
 
   // Guarantee a usable step. `0`, `NaN`, and negative values would let the
   // tick generator loop forever, so fall back to `1`. Keep the derived pure — the
@@ -228,13 +247,22 @@
     if (disabled) return;
     const current = thumb === 'high' ? highValue : lowValue;
     const hasTickArray = tickList !== null && tickList.length > 0;
+    const horizontalStepDirection: 1 | -1 = isRightToLeft ? -1 : 1;
     let next = current;
     switch (event.key) {
       case 'ArrowRight':
+        next = hasTickArray
+          ? neighborTick(current, horizontalStepDirection)
+          : current + horizontalStepDirection * safeStep;
+        break;
+      case 'ArrowLeft':
+        next = hasTickArray
+          ? neighborTick(current, horizontalStepDirection === 1 ? -1 : 1)
+          : current - horizontalStepDirection * safeStep;
+        break;
       case 'ArrowUp':
         next = hasTickArray ? neighborTick(current, 1) : current + safeStep;
         break;
-      case 'ArrowLeft':
       case 'ArrowDown':
         next = hasTickArray ? neighborTick(current, -1) : current - safeStep;
         break;
@@ -273,7 +301,8 @@
     if (!trackElement) return min;
     const rect = trackElement.getBoundingClientRect();
     if (rect.width === 0) return min;
-    const ratio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+    const physicalRatio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+    const ratio = isRightToLeft ? 1 - physicalRatio : physicalRatio;
     return min + ratio * (max - min);
   }
 
@@ -394,8 +423,10 @@
 />
 
 <div
+  bind:this={rootElement}
   class={classNames('cinder-slider', isRange && 'cinder-slider--range', className)}
   data-cinder-disabled={disabled || undefined}
+  {...rootDirection ? { dir: rootDirection } : {}}
 >
   {#if isRange}
     <span id={lowQualifierId} class="cinder-sr-only">

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

@@ -7,9 +7,26 @@ Drag-and-drop reorderable list that emits the new order on each change.
 ```svelte
 <script lang="ts">
   import SortableList from '@lostgradient/cinder/sortable-list';
+
+  let items = $state([
+    { id: '1', label: 'First item' },
+    { id: '2', label: 'Second item' },
+    { id: '3', label: 'Third item' },
+  ]);
 </script>
 
-<SortableList />
+<SortableList
+  {items}
+  getKey={(item) => item.id}
+  getItemLabel={(item) => item.label}
+  onreorder={(reordered) => {
+    items = reordered;
+  }}
+>
+  {#snippet row({ item })}
+    <span>{item.label}</span>
+  {/snippet}
+</SortableList>
 ```
 
 ## Props

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

@@ -50,7 +50,7 @@
   }
 
   .cinder-sortable-item--shifting {
-    transition: transform 150ms ease;
+    transition: transform var(--cinder-duration-fast) var(--cinder-ease-standard);
   }
 
   @media (prefers-reduced-motion: reduce) {

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

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "sortable-list",
+  "import": "@lostgradient/cinder/sortable-list",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic sortable list",
+      "description": "Keyboard and pointer reorderable list with announcer feedback.",
+      "code": "<script lang=\"ts\">\n  import { SortableList } from '@lostgradient/cinder/sortable-list';\n  import type { SortableListProps } from '@lostgradient/cinder/sortable-list';\n\n  type Task = { id: string; label: string };\n\n  let items = $state<Task[]>([\n    { id: 'task-1', label: 'Write release notes' },\n    { id: 'task-2', label: 'Review pull requests' },\n    { id: 'task-3', label: 'Update dependencies' },\n    { id: 'task-4', label: 'Deploy to staging' },\n  ]);\n\n  function getKey(item: Task): string {\n    return item.id;\n  }\n\n  function getItemLabel(item: Task, _originalIndex: number): string {\n    return item.label;\n  }\n\n  // `onreorder` receives the reordered items AND a `change` descriptor (from/to\n  // indices, moved key). This example only needs the new order, but the full\n  // signature is shown so the canonical call shape is accurate.\n  const handleReorder: SortableListProps<Task>['onreorder'] = (nextItems, _change) => {\n    items = nextItems;\n  };\n</script>\n\n<SortableList {items} {getKey} {getItemLabel} onreorder={handleReorder} label=\"Task priority\">\n  {#snippet children(item, _context)}\n    <span style=\"padding: 0.5rem 0.75rem; display: block;\">{item.label}</span>\n  {/snippet}\n</SortableList>\n"
+    }
+  ]
+}

package/src/components/spectrogram/spectrogram.examples.json

@@ -19,6 +19,7 @@
       "id": "voice-spectrogram",
       "title": "Voice spectrogram",
       "description": "Time × frequency heatmap showing how frequency content changes over time.",
+      "featured": true,
       "code": "<script lang=\"ts\">\n  import { Spectrogram } from '@lostgradient/cinder/spectrogram';\n\n  const frequencyLabels = [\n    '50 Hz',\n    '100 Hz',\n    '200 Hz',\n    '400 Hz',\n    '800 Hz',\n    '1.6 kHz',\n    '3.2 kHz',\n    '6.4 kHz',\n  ];\n\n  // Simulate a vowel formant pattern changing over time\n  function makeFrame(\n    label: string,\n    formant1: number,\n    formant2: number,\n  ): { label: string; bins: number[] } {\n    return {\n      label,\n      bins: frequencyLabels.map((_, index) => {\n        const f1 = Math.exp(-Math.pow(index - formant1, 2) / 1.5) * 0.9;\n        const f2 = Math.exp(-Math.pow(index - formant2, 2) / 1.5) * 0.6;\n        // Deterministic micro-variation using index and formant positions\n        const microVariation = Math.sin(index * 17.3 + formant1 * 5.7) * 0.025;\n        return Math.min(1, f1 + f2 + Math.abs(microVariation));\n      }),\n    };\n  }\n\n  const frames = [\n    makeFrame('0 ms', 1, 4),\n    makeFrame('20 ms', 1.2, 4.2),\n    makeFrame('40 ms', 1.5, 4.5),\n    makeFrame('60 ms', 2, 5),\n    makeFrame('80 ms', 2.5, 5.5),\n    makeFrame('100 ms', 2.2, 5.2),\n    makeFrame('120 ms', 1.8, 4.8),\n    makeFrame('140 ms', 1.5, 4.5),\n    makeFrame('160 ms', 1.2, 4.2),\n    makeFrame('180 ms', 1, 4),\n  ];\n</script>\n\n<Spectrogram\n  label=\"Voice spectrogram — vowel formant transition\"\n  description=\"Time × frequency heatmap showing vowel formant frequency shifts over 180 ms.\"\n  {frames}\n  {frequencyLabels}\n  height={220}\n  dataTableVisibility=\"visible\"\n/>\n"
     }
   ]

package/src/components/spectrogram/spectrogram.svelte

@@ -30,6 +30,7 @@
     toFiniteOrNull,
   } from '../../_internal/chart/heatmap-utilities.ts';
   import { classNames } from '../../utilities/class-names.ts';
+  import { useResizeObserver } from '../../utilities/use-resize-observer.svelte.ts';
   import type { SpectrogramProps } from './spectrogram.types.ts';
 
   let {
@@ -58,25 +59,12 @@
   const marginLeft = 60;
 
   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 plotWidth = $derived(Math.max(1, measuredWidth - marginLeft - marginRight));
@@ -177,7 +165,7 @@
 
 <figure
   {...rest}
-  bind:this={rootElement}
+  {@attach observeResize}
   id={rootId}
   class={classNames('cinder-spectrogram', customClassName)}
   aria-label={label}

package/src/components/spectrum-chart/spectrum-chart.svelte

@@ -21,6 +21,7 @@
 <script lang="ts">
   import { dataTableClass, formatNumericValue } from '../../_internal/chart/chart-utilities.ts';
   import { classNames } from '../../utilities/class-names.ts';
+  import { useResizeObserver } from '../../utilities/use-resize-observer.svelte.ts';
   import type { SpectrumChartProps } from './spectrum-chart.types.ts';
 
   let {
@@ -48,25 +49,12 @@
   const marginLeft = 40;
 
   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 plotWidth = $derived(Math.max(1, measuredWidth - marginLeft - marginRight));
@@ -140,7 +128,7 @@
 
 <figure
   {...rest}
-  bind:this={rootElement}
+  {@attach observeResize}
   id={rootId}
   class={classNames('cinder-spectrum-chart', customClassName)}
   aria-label={label}

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

@@ -47,7 +47,7 @@
     transform: translateY(-50%);
   }
 
-  .cinder-speed-dial[data-cinder-open='true'] .cinder-speed-dial__actions {
+  .cinder-speed-dial[data-cinder-open] .cinder-speed-dial__actions {
     pointer-events: auto;
   }
 
@@ -62,7 +62,7 @@
       transform var(--cinder-duration-fast) var(--cinder-ease-standard);
   }
 
-  .cinder-speed-dial[data-cinder-open='true'] .cinder-speed-dial-action {
+  .cinder-speed-dial[data-cinder-open] .cinder-speed-dial-action {
     opacity: 1;
     transform: none;
   }
@@ -100,7 +100,7 @@
     white-space: nowrap;
   }
 
-  .cinder-speed-dial[data-cinder-open='false'] .cinder-speed-dial-action {
+  .cinder-speed-dial:not([data-cinder-open]) .cinder-speed-dial-action {
     pointer-events: none;
   }
 

package/src/components/speed-dial/speed-dial.examples.json

@@ -13,7 +13,7 @@
       "id": "directions",
       "title": "Directions",
       "description": "Actions can fan out up, down, left, or right from the trigger.",
-      "code": "<script lang=\"ts\">\n  import { SpeedDial } from '@lostgradient/cinder/speed-dial';\n</script>\n\n<div\n  style=\"min-height: 14rem; display: flex; align-items: center; justify-content: center; gap: 5rem;\"\n>\n  <SpeedDial aria-label=\"Open upward actions\" direction=\"up\">\n    {#snippet trigger()}<span aria-hidden=\"true\">U</span>{/snippet}\n    <SpeedDial.Action label=\"Create\"\n      >{#snippet icon()}<span aria-hidden=\"true\">C</span>{/snippet}</SpeedDial.Action\n    >\n    <SpeedDial.Action label=\"Share\"\n      >{#snippet icon()}<span aria-hidden=\"true\">S</span>{/snippet}</SpeedDial.Action\n    >\n  </SpeedDial>\n\n  <SpeedDial aria-label=\"Open left actions\" direction=\"left\">\n    {#snippet trigger()}<span aria-hidden=\"true\">L</span>{/snippet}\n    <SpeedDial.Action label=\"Create\"\n      >{#snippet icon()}<span aria-hidden=\"true\">C</span>{/snippet}</SpeedDial.Action\n    >\n    <SpeedDial.Action label=\"Share\"\n      >{#snippet icon()}<span aria-hidden=\"true\">S</span>{/snippet}</SpeedDial.Action\n    >\n  </SpeedDial>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { SpeedDial } from '@lostgradient/cinder/speed-dial';\n</script>\n\n<div\n  style=\"min-height: 14rem; display: grid; grid-template-columns: minmax(10rem, 1fr) minmax(16rem, 1fr); align-items: center; gap: clamp(3rem, 10vw, 8rem);\"\n>\n  <div style=\"display: flex; justify-content: center;\">\n    <SpeedDial aria-label=\"Open upward actions\" direction=\"up\">\n      {#snippet trigger()}<span aria-hidden=\"true\">U</span>{/snippet}\n      <SpeedDial.Action label=\"Create\"\n        >{#snippet icon()}<span aria-hidden=\"true\">C</span>{/snippet}</SpeedDial.Action\n      >\n      <SpeedDial.Action label=\"Share\"\n        >{#snippet icon()}<span aria-hidden=\"true\">S</span>{/snippet}</SpeedDial.Action\n      >\n    </SpeedDial>\n  </div>\n\n  <div\n    style=\"display: flex; justify-content: flex-end; padding-inline-end: clamp(2rem, 8vw, 6rem);\"\n  >\n    <SpeedDial aria-label=\"Open left actions\" direction=\"left\">\n      {#snippet trigger()}<span aria-hidden=\"true\">L</span>{/snippet}\n      <SpeedDial.Action label=\"Create\"\n        >{#snippet icon()}<span aria-hidden=\"true\">C</span>{/snippet}</SpeedDial.Action\n      >\n      <SpeedDial.Action label=\"Share\"\n        >{#snippet icon()}<span aria-hidden=\"true\">S</span>{/snippet}</SpeedDial.Action\n      >\n    </SpeedDial>\n  </div>\n</div>\n"
     }
   ]
 }

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

@@ -171,7 +171,7 @@
   aria-hidden={hidden ? 'true' : undefined}
   inert={hidden ? true : undefined}
   class={classNames('cinder-speed-dial', customClassName)}
-  data-cinder-open={open ? 'true' : 'false'}
+  data-cinder-open={open ? '' : undefined}
   data-cinder-direction={direction}
   data-cinder-hidden={hidden ? 'true' : undefined}
 >
@@ -181,7 +181,7 @@
     aria-label="Actions"
     aria-orientation={orientation}
     class="cinder-speed-dial__actions"
-    data-cinder-open={open ? 'true' : 'false'}
+    data-cinder-open={open ? '' : undefined}
     inert={!open ? true : undefined}
     tabindex="-1"
     onkeydown={handleActionsKeydown}

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

@@ -57,7 +57,7 @@
   bind:this={rootElement}
   class={classNames('cinder-speed-dial-action', customClassName)}
   data-cinder-label-placement={labelPlacement}
-  data-cinder-open={context.isOpen ? 'true' : 'false'}
+  data-cinder-open={context.isOpen ? '' : undefined}
   data-cinder-direction={context.direction}
 >
   <FloatingActionButton

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

@@ -19,7 +19,7 @@
       "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"
+      "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: 'danger' as const,\n      statusLabel: 'Danger',\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/stat/README.md

@@ -35,7 +35,7 @@ snippet. The flat `@lostgradient/cinder/stat` subpath remains exported for
 | `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).                                                                                           |
+| `valueLocale`        | `string`             | no       | —       | Locale forwarded to formatNumber. Defaults to the nearest LocaleProvider locale, then 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.     |

package/src/components/stat/stat.svelte

@@ -17,6 +17,7 @@
 
 <script lang="ts">
   import type { StatProps } from './stat.types.ts';
+  import { getLocaleContext } from '../../_internal/locale-context.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import { formatNumber } from '../../utilities/format-number.ts';
 
@@ -37,12 +38,16 @@
     ...rest
   }: StatProps = $props();
 
+  const localeContext = getLocaleContext();
+
   const stableId = $derived(id ?? generatedId);
   const labelId = $derived(`${stableId}-label`);
   const valueId = $derived(`${stableId}-value`);
 
   const displayValue = $derived(
-    typeof value === 'number' ? formatNumber(value, valueLocale, valueFormatOptions) : value,
+    typeof value === 'number'
+      ? formatNumber(value, valueLocale ?? localeContext?.locale, valueFormatOptions)
+      : value,
   );
 
   const arrowGlyph = $derived(
@@ -51,7 +56,7 @@
 
   const changeAccessibleText = $derived.by(() => {
     if (!change) return '';
-    if (change.ariaLabel) return change.ariaLabel;
+    if (change.label) return change.label;
     const suffix = change.description ? ` ${change.description}` : '';
     if (change.direction === 'up') return `increased by ${change.value}${suffix}`;
     if (change.direction === 'down') return `decreased by ${change.value}${suffix}`;

package/src/components/stat/stat.types.ts

@@ -15,7 +15,7 @@ export type StatChange = {
    * When omitted, a phrase is synthesized from `direction` + `value` (+ optional `description`).
    * When provided, used verbatim — the caller owns the full wording.
    */
-  ariaLabel?: string;
+  label?: string;
 };
 export type StatProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
   /** Short label describing the metric, e.g. "Monthly Revenue". */
@@ -28,7 +28,7 @@ export type StatProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
   icon?: Snippet;
   /** Intl.NumberFormat options applied only when `value` is a number. */
   valueFormatOptions?: Intl.NumberFormatOptions;
-  /** Locale forwarded to formatNumber (defaults to en-US). */
+  /** Locale forwarded to formatNumber. Defaults to the nearest LocaleProvider locale, then en-US. */
   valueLocale?: string;
   /** Additional class names merged with `.cinder-stat`. */
   class?: string;

package/src/components/stat-group/stat-group.css

@@ -10,7 +10,7 @@
   }
 
   .cinder-stat-group[data-cinder-columns='auto'] {
-    grid-template-columns: repeat(auto-fit, minmax(min(14rem, 100%), 1fr));
+    grid-template-columns: repeat(auto-fit, minmax(min(16rem, 100%), 1fr));
   }
 
   .cinder-stat-group[data-cinder-columns='1'] {

package/src/components/status-dot/README.md

@@ -16,13 +16,15 @@ A semantic status indicator that pairs a colored dot with an accessible label.
 
 <!-- generated:props:start -->
 
-| Prop        | Type                                                                                                             | Required | Default | Description                                                                                                                                |
-| ----------- | ---------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `class`     | `string`                                                                                                         | no       | —       | Extra classes appended to the root element.                                                                                                |
-| `label`     | `string`                                                                                                         | no       | —       | Optional human label. Rendered visibly when `showLabel` is true; used as the accessible name either way.                                   |
-| `showLabel` | `boolean`                                                                                                        | no       | `true`  | Whether to render the visible label.                                                                                                       |
-| `size`      | `"sm"` \| `"md"`                                                                                                 | no       | `"md"`  | Dot size.                                                                                                                                  |
-| `status`    | `"online"` \| `"offline"` \| `"warning"` \| `"error"` \| `"pending"` \| `"neutral"` \| `"success"` \| `"accent"` | yes      | —       | Required semantic status. Drives color via `data-cinder-status`. `success` maps to `--cinder-success`; `accent` maps to `--cinder-accent`. |
+| Prop              | Type                                                                                                              | Required | Default | Description                                                                                                                                                                                    |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`           | `string`                                                                                                          | no       | —       | Extra classes appended to the root element.                                                                                                                                                    |
+| `connectionState` | `"connected"` \| `"connecting"` \| `"disconnected"` \| `"error"`                                                  | no       | —       | Realtime connection preset. Sets status, default label, and live-region semantics.                                                                                                             |
+| `label`           | `string`                                                                                                          | no       | —       | Optional human label. Rendered visibly when `showLabel` is true; used as the accessible name either way.                                                                                       |
+| `live`            | `boolean`                                                                                                         | no       | —       | Use role="status" with polite live-region attributes. Defaults true when connectionState is provided.                                                                                          |
+| `showLabel`       | `boolean`                                                                                                         | no       | `true`  | Whether to render the visible label.                                                                                                                                                           |
+| `size`            | `"sm"` \| `"md"`                                                                                                  | no       | `"md"`  | Dot size.                                                                                                                                                                                      |
+| `status`          | `"online"` \| `"offline"` \| `"warning"` \| `"danger"` \| `"pending"` \| `"neutral"` \| `"success"` \| `"accent"` | no       | —       | Semantic status. Drives color via `data-cinder-status`; defaults to a neutral dot or derives from `connectionState`. `success` maps to `--cinder-success`; `accent` maps to `--cinder-accent`. |
 
 <!-- generated:props:end -->
 

package/src/components/status-dot/index.ts

@@ -2,5 +2,10 @@ import './status-dot.css';
 import StatusDot from './status-dot.svelte';
 
 export default StatusDot;
-export type { StatusDotProps, StatusDotSize, StatusDotStatus } from './status-dot.types.ts';
+export type {
+  StatusDotConnectionState,
+  StatusDotProps,
+  StatusDotSize,
+  StatusDotStatus,
+} from './status-dot.types.ts';
 export { StatusDot };

package/src/components/status-dot/status-dot.css

@@ -24,6 +24,30 @@
     vertical-align: middle;
   }
 
+  .cinder-status-dot[data-cinder-state] {
+    padding: var(--cinder-space-0-5) var(--cinder-space-2);
+    font-size: var(--cinder-text-xs);
+    font-weight: var(--cinder-font-medium);
+    border-radius: var(--cinder-radius-full);
+    background: var(--cinder-surface-inset);
+  }
+
+  .cinder-status-dot[data-cinder-state='connected'] {
+    color: var(--cinder-success);
+  }
+
+  .cinder-status-dot[data-cinder-state='connecting'] {
+    color: var(--cinder-warning);
+  }
+
+  .cinder-status-dot[data-cinder-state='disconnected'] {
+    color: var(--cinder-text-muted);
+  }
+
+  .cinder-status-dot[data-cinder-state='error'] {
+    color: var(--cinder-danger);
+  }
+
   .cinder-status-dot__indicator {
     display: inline-block;
     flex-shrink: 0;
@@ -66,7 +90,7 @@
     --cinder-status-dot-color: var(--cinder-warning);
   }
 
-  .cinder-status-dot[data-cinder-status='error'] {
+  .cinder-status-dot[data-cinder-status='danger'] {
     --cinder-status-dot-color: var(--cinder-danger);
   }
 
@@ -85,4 +109,24 @@
   .cinder-status-dot[data-cinder-status='accent'] {
     --cinder-status-dot-color: var(--cinder-accent);
   }
+
+  .cinder-status-dot[data-cinder-state='connecting'] .cinder-status-dot__indicator {
+    animation: cinder-status-dot-pulse 1.4s ease-in-out infinite;
+  }
+
+  @keyframes cinder-status-dot-pulse {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.3;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .cinder-status-dot[data-cinder-state='connecting'] .cinder-status-dot__indicator {
+      animation: none;
+    }
+  }
 }

package/src/components/status-dot/status-dot.examples.json

@@ -13,7 +13,7 @@
       "id": "statuses",
       "title": "Status dot statuses",
       "description": "All eight semantic status values.",
-      "code": "<script lang=\"ts\">\n  import { StatusDot } from '@lostgradient/cinder/status-dot';\n</script>\n\n<div class=\"example-preview-row\">\n  <StatusDot status=\"online\" label=\"Online\" />\n  <StatusDot status=\"offline\" label=\"Offline\" />\n  <StatusDot status=\"warning\" label=\"Warning\" />\n  <StatusDot status=\"error\" label=\"Error\" />\n  <StatusDot status=\"pending\" label=\"Pending\" />\n  <StatusDot status=\"neutral\" label=\"Neutral\" />\n  <StatusDot status=\"success\" label=\"Success\" />\n  <StatusDot status=\"accent\" label=\"Accent\" />\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { StatusDot } from '@lostgradient/cinder/status-dot';\n</script>\n\n<div class=\"example-preview-row\">\n  <StatusDot status=\"online\" label=\"Online\" />\n  <StatusDot status=\"offline\" label=\"Offline\" />\n  <StatusDot status=\"warning\" label=\"Warning\" />\n  <StatusDot status=\"danger\" label=\"Danger\" />\n  <StatusDot status=\"pending\" label=\"Pending\" />\n  <StatusDot status=\"neutral\" label=\"Neutral\" />\n  <StatusDot status=\"success\" label=\"Success\" />\n  <StatusDot status=\"accent\" label=\"Accent\" />\n</div>\n"
     }
   ]
 }