@lostgradient/cinder 0.3.0 → 0.4.1

package/src/components/sheet/sheet.svelte

@@ -19,13 +19,11 @@
   import type { SheetProps } from './sheet.types.ts';
   import { onDestroy, tick } from 'svelte';
 
-  import { captureFocus, lockBodyScroll, pushEscapeHandler } from '../../_internal/overlay.ts';
-  import { waitForTransitionCompletion } from '../../_internal/transition-completion.ts';
   import { overflowFade } from '../../utilities/attachments.ts';
   import { createFocusTrap } from '../focus-trap/index.ts';
   import { classNames } from '../../utilities/class-names.ts';
-  import { restoreFocusTo } from '../../utilities/focus.ts';
   import { useReducedMotion } from '../../utilities/use-reduced-motion.svelte.ts';
+  import { createSlidingDialogState } from '../_internal/create-sliding-dialog-state.svelte.ts';
 
   let {
     open = $bindable(false),
@@ -45,66 +43,33 @@
   let dialogElement: HTMLDialogElement | undefined = $state();
   let bodyElement: HTMLDivElement | undefined = $state();
   let panelElement: HTMLDivElement | undefined = $state();
-  let hydrated = $state(false);
-  let renderPanel = $state(open);
-  let isClosing = $state(false);
-  let closeGeneration = $state(0);
   let pendingOpenFocus = $state(false);
 
-  let capturedFocus: HTMLElement | null = null;
-  let releaseScrollLock: (() => void) | null = null;
-  let releaseEscape: (() => void) | null = null;
-  let cancelPendingClose: (() => void) | null = null;
-
   const reducedMotion = useReducedMotion();
   const bodyOverflowFade = overflowFade();
-
-  function acquireScrollLock(): void {
-    if (releaseScrollLock) return;
-    releaseScrollLock = lockBodyScroll();
-  }
-
-  function acquireEscapeMarker(): void {
-    if (releaseEscape) return;
-    // No-op handler: presence marker so stacked non-dialog overlays
-    // route ESC to themselves. Native <dialog> owns the actual ESC close.
-    releaseEscape = pushEscapeHandler(() => {});
-  }
+  const dialogState = createSlidingDialogState({
+    getOpen: () => open,
+    setOpen: (nextOpen) => {
+      open = nextOpen;
+    },
+    getDialogElement: () => dialogElement,
+    getPanelElement: () => panelElement,
+    getReducedMotion: () => reducedMotion.current,
+    getTriggerRef: () => triggerRef,
+    onOpen: () => {
+      pendingOpenFocus = true;
+    },
+    onClosed: () => {
+      pendingOpenFocus = false;
+    },
+  });
 
   $effect(() => {
-    hydrated = true;
+    dialogState.markHydrated();
   });
 
   $effect(() => {
-    if (!dialogElement) return;
-    if (open) {
-      if (isClosing) {
-        closeGeneration += 1;
-        cancelPendingClose?.();
-        cancelPendingClose = null;
-        isClosing = false;
-      }
-
-      if (!renderPanel) {
-        renderPanel = true;
-      }
-
-      if (!dialogElement.open) {
-        capturedFocus = captureFocus();
-        pendingOpenFocus = true;
-        dialogElement.showModal();
-        acquireScrollLock();
-        acquireEscapeMarker();
-      }
-      return;
-    }
-
-    if (dialogElement.open) {
-      beginClosing();
-    } else {
-      renderPanel = false;
-      pendingOpenFocus = false;
-    }
+    dialogState.syncOpenState();
   });
 
   $effect(() => {
@@ -123,109 +88,29 @@
     });
   });
 
-  function beginClosing(): void {
-    if (!dialogElement?.open || isClosing) return;
-    if (!panelElement) {
-      finishClosing(closeGeneration);
-      return;
-    }
-
-    isClosing = true;
-    const generation = ++closeGeneration;
-    cancelPendingClose?.();
-    cancelPendingClose = waitForTransitionCompletion({
-      element: panelElement,
-      reducedMotion: reducedMotion.current,
-      onComplete: () => finishClosing(generation),
-    });
-  }
-
-  function finishClosing(generation: number): void {
-    if (generation !== closeGeneration) return;
-    cancelPendingClose?.();
-    cancelPendingClose = null;
-    isClosing = false;
-    renderPanel = false;
-    pendingOpenFocus = false;
-    if (dialogElement?.open) {
-      dialogElement.close();
-    }
-  }
-
-  function handleClose() {
-    if (releaseScrollLock) {
-      releaseScrollLock();
-      releaseScrollLock = null;
-    }
-    if (releaseEscape) {
-      releaseEscape();
-      releaseEscape = null;
-    }
-    open = false;
-    const candidates: Array<HTMLElement | null> = [triggerRef, capturedFocus];
-    capturedFocus = null;
-    for (const candidate of candidates) {
-      if (restoreFocusTo(candidate)) break;
-    }
-  }
-
-  function requestClose(): void {
-    if (!open && (isClosing || !dialogElement?.open)) return;
-    open = false;
-    beginClosing();
-  }
-
-  function handleBackdropClick(event: MouseEvent) {
-    if (event.target === dialogElement) {
-      requestClose();
-    }
-  }
-
-  function handleNativeCancel(event: Event) {
-    event.preventDefault();
-    requestClose();
-  }
-
   onDestroy(() => {
-    cancelPendingClose?.();
-    cancelPendingClose = null;
-    const wasOpen = releaseScrollLock !== null || releaseEscape !== null;
-    if (releaseScrollLock) {
-      releaseScrollLock();
-      releaseScrollLock = null;
-    }
-    if (releaseEscape) {
-      releaseEscape();
-      releaseEscape = null;
-    }
-    if (wasOpen) {
-      const candidates: Array<HTMLElement | null> = [triggerRef, capturedFocus];
-      capturedFocus = null;
-      for (const candidate of candidates) {
-        if (restoreFocusTo(candidate)) break;
-      }
-    }
+    dialogState.destroy();
   });
 </script>
 
-{#if hydrated}
+{#if dialogState.hydrated}
   <dialog
     {...rest}
     bind:this={dialogElement}
     class={classNames('cinder-sheet', className)}
     aria-modal="true"
     aria-labelledby={ariaLabelledBy ?? titleId}
-    data-cinder-closing={isClosing ? '' : undefined}
-    onclose={handleClose}
-    oncancel={handleNativeCancel}
-    onclick={handleBackdropClick}
+    data-cinder-closing={dialogState.isClosing ? '' : undefined}
+    onclose={() => dialogState.handleClose()}
+    oncancel={(event) => dialogState.handleNativeCancel(event)}
+    onclick={(event) => dialogState.handleBackdropClick(event)}
   >
     {#snippet closeButton()}
       <button
         type="button"
         class="cinder-sheet__close"
         aria-label="Close sheet"
-        onclick={requestClose}
+        onclick={() => dialogState.requestClose()}
       >
         <svg
           class="cinder-sheet__close-icon"
@@ -241,14 +126,14 @@
       </button>
     {/snippet}
 
-    {#if renderPanel}
+    {#if dialogState.renderPanel}
       <div
         bind:this={panelElement}
         class="cinder-sheet__panel"
-        data-cinder-closing={isClosing ? '' : undefined}
-        inert={isClosing}
+        data-cinder-closing={dialogState.isClosing ? '' : undefined}
+        inert={dialogState.isClosing}
         {@attach createFocusTrap({
-          active: () => open && !isClosing,
+          active: () => open && !dialogState.isClosing,
           restoreFocus: false,
           manageInitialFocus: false,
         })}

package/src/components/shortcut-hint/shortcut-hint.svelte

@@ -47,7 +47,7 @@
   {/if}
 
   <span class="cinder-shortcut-hint__keys" aria-hidden="true">
-    {#each keys as key, index (key + index)}
+    {#each keys as key, index (index)}
       <Kbd label={key} size="sm" />
       {#if index < keys.length - 1}
         <span class="cinder-shortcut-hint__separator">+</span>

package/src/components/side-navigation/side-navigation.examples.json

@@ -13,7 +13,7 @@
       "id": "docs-sidebar",
       "title": "Docs sidebar",
       "description": "Documentation sidebar with grouped navigation sections. The active item receives aria-current=\"page\".",
-      "code": "<script lang=\"ts\" module>\n  export const title = 'Docs sidebar';\n  export const description =\n    'Documentation sidebar with grouped navigation sections. The active item receives aria-current=\"page\".' +\n    ' Composed inside Sidebar so the column collapses to a drawer below the ~767px viewport breakpoint —' +\n    ' resize your browser window to see the mobile drawer behavior.';\n</script>\n\n<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n  import { Sidebar } from '@lostgradient/cinder/sidebar';\n\n  let collapsed = $state(false);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div>\n    <Button\n      label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}\n      onclick={() => (collapsed = !collapsed)}\n    />\n  </div>\n\n  <div\n    style=\"display: flex; min-height: 28rem; border: 1px solid var(--cinder-border); border-radius: 0.5rem; overflow: hidden;\"\n  >\n    <Sidebar bind:collapsed ariaLabel=\"Documentation\">\n      {#snippet brand()}\n        <strong style=\"font-size: 0.875rem;\">Cinder Docs</strong>\n      {/snippet}\n\n      {#snippet navigation()}\n        <SideNavigation ariaLabel=\"Documentation sections\">\n          <SideNavigation.Group label=\"Getting Started\">\n            <SideNavigation.Item href=\"#introduction\" active>Introduction</SideNavigation.Item>\n            <SideNavigation.Item href=\"#installation\">Installation</SideNavigation.Item>\n            <SideNavigation.Item href=\"#quick-start\">Quick start</SideNavigation.Item>\n          </SideNavigation.Group>\n          <SideNavigation.Group label=\"Components\">\n            <SideNavigation.Item href=\"#button\">Button</SideNavigation.Item>\n            <SideNavigation.Item href=\"#form-section\">FormSection</SideNavigation.Item>\n            <SideNavigation.Item href=\"#side-navigation\">SideNavigation</SideNavigation.Item>\n          </SideNavigation.Group>\n          <SideNavigation.Group label=\"API Reference\">\n            <SideNavigation.Item href=\"#props\">Props</SideNavigation.Item>\n            <SideNavigation.Item href=\"#types\">Types</SideNavigation.Item>\n            <SideNavigation.Item href=\"#css-variables\">CSS variables</SideNavigation.Item>\n          </SideNavigation.Group>\n        </SideNavigation>\n      {/snippet}\n    </Sidebar>\n\n    <main style=\"flex: 1; padding: 1.5rem;\">\n      <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n        Main content area. Resize the browser viewport below ~767px to see the navigation collapse\n        into a mobile drawer.\n      </p>\n    </main>\n  </div>\n</div>\n"
+      "code": "<script lang=\"ts\" module>\n  export const title = 'Docs sidebar';\n  export const description =\n    'Documentation sidebar with grouped navigation sections. The active item receives aria-current=\"page\".' +\n    ' Composed inside Sidebar so the column collapses to a drawer below the ~767px viewport breakpoint —' +\n    ' resize your browser window to see the mobile drawer behavior.';\n</script>\n\n<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n  import { Sidebar } from '@lostgradient/cinder/sidebar';\n\n  let collapsed = $state(false);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div>\n    <Button\n      label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}\n      onclick={() => (collapsed = !collapsed)}\n    />\n  </div>\n\n  <div\n    style=\"display: flex; min-height: 28rem; border: 1px solid var(--cinder-border); border-radius: 0.5rem; overflow: hidden;\"\n  >\n    <Sidebar bind:collapsed label=\"Documentation\">\n      {#snippet brand()}\n        <strong style=\"font-size: 0.875rem;\">Cinder Docs</strong>\n      {/snippet}\n\n      {#snippet navigation()}\n        <SideNavigation ariaLabel=\"Documentation sections\">\n          <SideNavigation.Group label=\"Getting Started\">\n            <SideNavigation.Item href=\"#introduction\" active>Introduction</SideNavigation.Item>\n            <SideNavigation.Item href=\"#installation\">Installation</SideNavigation.Item>\n            <SideNavigation.Item href=\"#quick-start\">Quick start</SideNavigation.Item>\n          </SideNavigation.Group>\n          <SideNavigation.Group label=\"Components\">\n            <SideNavigation.Item href=\"#button\">Button</SideNavigation.Item>\n            <SideNavigation.Item href=\"#form-section\">FormSection</SideNavigation.Item>\n            <SideNavigation.Item href=\"#side-navigation\">SideNavigation</SideNavigation.Item>\n          </SideNavigation.Group>\n          <SideNavigation.Group label=\"API Reference\">\n            <SideNavigation.Item href=\"#props\">Props</SideNavigation.Item>\n            <SideNavigation.Item href=\"#types\">Types</SideNavigation.Item>\n            <SideNavigation.Item href=\"#css-variables\">CSS variables</SideNavigation.Item>\n          </SideNavigation.Group>\n        </SideNavigation>\n      {/snippet}\n    </Sidebar>\n\n    <main style=\"flex: 1; padding: 1.5rem;\">\n      <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n        Main content area. Resize the browser viewport below ~767px to see the navigation collapse\n        into a mobile drawer.\n      </p>\n    </main>\n  </div>\n</div>\n"
     }
   ]
 }

package/src/components/sidebar/README.md

@@ -9,7 +9,11 @@ Persistent side panel that houses navigation, filters, or supplementary page con
   import Sidebar from '@lostgradient/cinder/sidebar';
 </script>
 
-<Sidebar />
+<Sidebar label="App sidebar">
+  {#snippet navigation()}
+    <nav><!-- navigation items --></nav>
+  {/snippet}
+</Sidebar>
 ```
 
 ## Props
@@ -18,9 +22,9 @@ Persistent side panel that houses navigation, filters, or supplementary page con
 
 | Prop         | Type       | Required | Default | Description                                                                                                                                                                                                                                                                                                                                              |
 | ------------ | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ariaLabel`  | `string`   | no       | —       | Accessible name for the outer landmark and the mobile drawer. Required — defaults to `'Sidebar'` for convenience but must be unique per page. The inner `<nav>` landmark derives its own accessible name from this value by appending `' navigation'` so screen readers can distinguish the outer complementary region from the inner navigation region. |
 | `class`      | `string`   | no       | —       | Additional CSS class merged with `.cinder-sidebar`.                                                                                                                                                                                                                                                                                                      |
 | `collapsed`  | `boolean`  | no       | —       | Whether the sidebar is collapsed. Bindable via `bind:collapsed`. Default `false`. On desktop (>= md breakpoint) `collapsed=true` switches the sidebar to icon-only mode. Below the md breakpoint the sidebar renders inside a `<Drawer>` and `collapsed=true` means the drawer is closed.                                                                |
+| `label`      | `string`   | no       | —       | Accessible name for the outer landmark and the mobile drawer. Required — defaults to `'Sidebar'` for convenience but must be unique per page. The inner `<nav>` landmark derives its own accessible name from this value by appending `' navigation'` so screen readers can distinguish the outer complementary region from the inner navigation region. |
 | `brand`      | `(opaque)` | no       | —       | Optional branding region rendered above the navigation. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                       |
 | `footer`     | `(opaque)` | no       | —       | Optional footer region (e.g. user account, sign-out). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                         |
 | `navigation` | `(opaque)` | no       | —       | Navigation region. Typically a `<SideNavigation>` subtree. Optional — when omitted, no `<nav>` landmark is rendered (so the sidebar can serve as app chrome without a navigation list, and an empty `<nav>` isn't announced to screen readers). Not expressible in JSON Schema; see the component types for the signature.                               |

package/src/components/sidebar/sidebar.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic sidebar",
       "description": "Layout-level sidebar with brand, navigation, and footer regions. Collapse toggles icon-only mode on desktop and closes the drawer on mobile.",
-      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { NavigationItem } from '@lostgradient/cinder/navigation-item';\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n  import { SideNavigationGroup } from '@lostgradient/cinder/side-navigation-group';\n  import { SideNavigationItem } from '@lostgradient/cinder/side-navigation-item';\n  import { Sidebar } from '@lostgradient/cinder/sidebar';\n  let collapsed = $state(false);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div>\n    <Button\n      label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}\n      onclick={() => (collapsed = !collapsed)}\n    />\n  </div>\n\n  <div\n    style=\"display: flex; min-height: 24rem; border: 1px solid #e5e7eb; border-radius: 0.5rem; overflow: hidden;\"\n  >\n    <Sidebar bind:collapsed ariaLabel=\"Workspace\">\n      {#snippet brand()}\n        <strong style=\"font-size: 0.875rem;\">Cinder</strong>\n      {/snippet}\n\n      {#snippet navigation()}\n        <SideNavigation ariaLabel=\"Workspace sections\">\n          {#snippet children()}\n            <SideNavigationItem href=\"#dashboard\">\n              {#snippet children()}Dashboard{/snippet}\n            </SideNavigationItem>\n            <SideNavigationItem href=\"#projects\" active>\n              {#snippet children()}Projects{/snippet}\n            </SideNavigationItem>\n            <SideNavigationGroup label=\"Settings\">\n              {#snippet children()}\n                <SideNavigationItem href=\"#general\">\n                  {#snippet children()}General{/snippet}\n                </SideNavigationItem>\n                <SideNavigationItem href=\"#billing\">\n                  {#snippet children()}Billing{/snippet}\n                </SideNavigationItem>\n              {/snippet}\n            </SideNavigationGroup>\n          {/snippet}\n        </SideNavigation>\n      {/snippet}\n\n      {#snippet footer()}\n        <NavigationItem variant=\"vertical\" href=\"#account\">\n          {#snippet children()}Account{/snippet}\n        </NavigationItem>\n      {/snippet}\n    </Sidebar>\n\n    <main style=\"flex: 1; padding: 1rem;\">\n      <p>Main content area.</p>\n      <p>Resize the viewport below ~767px to see the mobile drawer behavior.</p>\n    </main>\n  </div>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { NavigationItem } from '@lostgradient/cinder/navigation-item';\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n  import { SideNavigationGroup } from '@lostgradient/cinder/side-navigation-group';\n  import { SideNavigationItem } from '@lostgradient/cinder/side-navigation-item';\n  import { Sidebar } from '@lostgradient/cinder/sidebar';\n  let collapsed = $state(false);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div>\n    <Button\n      label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}\n      onclick={() => (collapsed = !collapsed)}\n    />\n  </div>\n\n  <div\n    style=\"display: flex; min-height: 24rem; border: 1px solid #e5e7eb; border-radius: 0.5rem; overflow: hidden;\"\n  >\n    <Sidebar bind:collapsed label=\"Workspace\">\n      {#snippet brand()}\n        <strong style=\"font-size: 0.875rem;\">Cinder</strong>\n      {/snippet}\n\n      {#snippet navigation()}\n        <SideNavigation ariaLabel=\"Workspace sections\">\n          {#snippet children()}\n            <SideNavigationItem href=\"#dashboard\">\n              {#snippet children()}Dashboard{/snippet}\n            </SideNavigationItem>\n            <SideNavigationItem href=\"#projects\" active>\n              {#snippet children()}Projects{/snippet}\n            </SideNavigationItem>\n            <SideNavigationGroup label=\"Settings\">\n              {#snippet children()}\n                <SideNavigationItem href=\"#general\">\n                  {#snippet children()}General{/snippet}\n                </SideNavigationItem>\n                <SideNavigationItem href=\"#billing\">\n                  {#snippet children()}Billing{/snippet}\n                </SideNavigationItem>\n              {/snippet}\n            </SideNavigationGroup>\n          {/snippet}\n        </SideNavigation>\n      {/snippet}\n\n      {#snippet footer()}\n        <NavigationItem variant=\"vertical\" href=\"#account\">\n          {#snippet children()}Account{/snippet}\n        </NavigationItem>\n      {/snippet}\n    </Sidebar>\n\n    <main style=\"flex: 1; padding: 1rem;\">\n      <p>Main content area.</p>\n      <p>Resize the viewport below ~767px to see the mobile drawer behavior.</p>\n    </main>\n  </div>\n</div>\n"
     }
   ]
 }

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/sortable-list/sortable-list.types.ts

@@ -3,7 +3,7 @@ export type {
   SortableAnnouncements,
   SortableItemContext,
   SortableReorderChange,
-} from '../../utilities/sortable-controller.svelte.ts';
+} from '../../utilities/sortable-controller.types.ts';
 /** Props for the SortableList component. */
 export type SortableListProps<Item> = {
   /** The list of items to render. */
@@ -24,15 +24,15 @@ export type SortableListProps<Item> = {
   /** Fires with the full reordered array and change metadata on drop. */
   onreorder: (
     nextItems: Item[],
-    change: import('../../utilities/sortable-controller.svelte.ts').SortableReorderChange,
+    change: import('../../utilities/sortable-controller.types.ts').SortableReorderChange,
   ) => void;
   /** Optional overrides for announcement strings. */
   announcements?: Partial<
-    import('../../utilities/sortable-controller.svelte.ts').SortableAnnouncements
+    import('../../utilities/sortable-controller.types.ts').SortableAnnouncements
   >;
   /** Row content snippet. Receives the item and a per-row context. */
   children: Snippet<
-    [Item, import('../../utilities/sortable-controller.svelte.ts').SortableItemContext]
+    [Item, import('../../utilities/sortable-controller.types.ts').SortableItemContext]
   >;
   /** Accessible name for the list (applied as aria-label on the list root). */
   label?: string;

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}