@lostgradient/cinder 0.3.0 → 0.4.1

package/src/components/menu-bar/menu-bar.svelte

@@ -29,7 +29,14 @@
 <script lang="ts">
   import { tick } from 'svelte';
 
+  import { getLocaleContext } from '../../_internal/locale-context.ts';
+  import { observeTextDirection, resolveTextDirection } from '../../_internal/text-direction.ts';
   import { classNames } from '../../utilities/class-names.ts';
+  import {
+    findTypeaheadMatch,
+    isTypeaheadKey,
+    TypeaheadBuffer,
+  } from '../../utilities/typeahead.ts';
   import type { DropdownContext } from '../dropdown/dropdown.types.ts';
   import DropdownItem from '../dropdown-item/dropdown-item.svelte';
   import DropdownLabel from '../dropdown-label/dropdown-label.svelte';
@@ -47,6 +54,7 @@
 
   type RestSafeProps = MenuBarProps & {
     role?: string;
+    dir?: 'ltr' | 'rtl' | 'auto';
     'aria-label'?: string;
     'aria-labelledby'?: string;
     'aria-orientation'?: string;
@@ -59,6 +67,7 @@
     labelledBy,
     class: customClassName,
     role: _role,
+    dir: providedDirection,
     'aria-label': _ariaLabel,
     'aria-labelledby': _ariaLabelledBy,
     'aria-orientation': _ariaOrientation,
@@ -74,8 +83,50 @@
   let openMenuIndex = $state<number | null>(null);
   let openSubmenuKey = $state<string | null>(null);
   let initialFocus = $state<'first' | 'last' | 'none' | undefined>(undefined);
+  let directionRevision = $state(0);
   let suppressSubmenuFocusOpen = false;
+  let submenuCloseTimer: ReturnType<typeof setTimeout> | null = null;
+  let pendingSubmenuCloseKey: string | null = null;
+  let pendingSubmenuTriggerId: string | null = null;
+  let submenuLeavePoint: { x: number; y: number } | null = null;
+  let latestPointerPoint: { x: number; y: number } | null = null;
+  const localeContext = getLocaleContext();
   const menuElements = new Map<string, HTMLElement>();
+  const typeaheadBuffer = new TypeaheadBuffer();
+  const directionElement = $derived(
+    providedDirection === 'auto' ? rootElement : (rootElement?.parentElement ?? rootElement),
+  );
+  const resolvedDirection = $derived.by(() => {
+    directionRevision;
+    return providedDirection === 'rtl' || providedDirection === 'ltr'
+      ? providedDirection
+      : resolveTextDirection(directionElement, localeContext?.direction);
+  });
+  const rootDirection = $derived(providedDirection === 'auto' ? 'auto' : resolvedDirection);
+  const renderedRootDirection = $derived.by(() => {
+    if (
+      providedDirection === 'auto' ||
+      providedDirection === 'rtl' ||
+      providedDirection === 'ltr'
+    ) {
+      return rootDirection;
+    }
+    return localeContext?.direction ? resolvedDirection : null;
+  });
+
+  $effect(() => {
+    if (providedDirection === 'rtl' || providedDirection === 'ltr') return;
+    return observeTextDirection(directionElement, () => {
+      directionRevision += 1;
+    });
+  });
+
+  $effect(() => {
+    return () => {
+      clearSubmenuCloseTimer();
+      typeaheadBuffer.reset();
+    };
+  });
 
   const enabledIndexes = $derived(
     menus.map((menu, index) => ({ menu, index })).filter(({ menu }) => !menu.disabled),
@@ -153,6 +204,11 @@
     return indexes[(currentPosition + direction + indexes.length) % indexes.length] ?? -1;
   }
 
+  function horizontalArrowDirection(key: 'ArrowLeft' | 'ArrowRight'): -1 | 1 {
+    if (key === 'ArrowRight') return resolvedDirection === 'rtl' ? -1 : 1;
+    return resolvedDirection === 'rtl' ? 1 : -1;
+  }
+
   function firstEnabledMenuIndex(): number {
     return enabledIndexes[0]?.index ?? -1;
   }
@@ -164,6 +220,7 @@
   function openMenu(index: number, focus: 'first' | 'last' = 'first'): void {
     const menu = menus[index];
     if (!menu || menu.disabled) return;
+    typeaheadBuffer.reset();
     activeMenuIndex = index;
     openMenuIndex = index;
     openSubmenuKey = null;
@@ -176,6 +233,8 @@
   }
 
   function closeAll(): void {
+    clearSubmenuCloseTimer();
+    typeaheadBuffer.reset();
     openMenuIndex = null;
     openSubmenuKey = null;
     initialFocus = undefined;
@@ -209,7 +268,9 @@
   function makeContext(options: {
     menuId: string;
     anchorElement: () => HTMLElement | null;
-    fallbackPlacement?: DropdownContext['fallbackPlacement'];
+    fallbackPlacement?:
+      | DropdownContext['fallbackPlacement']
+      | (() => DropdownContext['fallbackPlacement']);
     isOpen: () => boolean;
     close: () => void;
     focusTrigger: () => void;
@@ -228,7 +289,9 @@
         return options.anchorElement();
       },
       get fallbackPlacement() {
-        return options.fallbackPlacement ?? 'bottom-start';
+        return typeof options.fallbackPlacement === 'function'
+          ? options.fallbackPlacement()
+          : (options.fallbackPlacement ?? 'bottom-start');
       },
       get widthMode() {
         return 'menu' as const;
@@ -241,6 +304,20 @@
     };
   }
 
+  function submenuDirection(submenuTriggerId: string): 'ltr' | 'rtl' | undefined {
+    return resolveTextDirection(findElementById(submenuTriggerId), resolvedDirection);
+  }
+
+  function submenuFallbackPlacement(
+    submenuTriggerId: string,
+  ): DropdownContext['fallbackPlacement'] {
+    return submenuDirection(submenuTriggerId) === 'rtl' ? 'left-start' : 'right-start';
+  }
+
+  function submenuOpenArrow(submenuTriggerId: string): 'ArrowLeft' | 'ArrowRight' {
+    return submenuDirection(submenuTriggerId) === 'rtl' ? 'ArrowLeft' : 'ArrowRight';
+  }
+
   function makeMenuRegister(menuId: string): (element: HTMLElement | null) => void {
     return (element) => {
       if (element) {
@@ -255,10 +332,199 @@
     return Array.from(menuElements.values()).some((element) => element.contains(target));
   }
 
+  function isPointerStillInsideCurrentTarget(event: MouseEvent | PointerEvent): boolean {
+    return event.relatedTarget instanceof Node && event.currentTarget instanceof HTMLElement
+      ? event.currentTarget.contains(event.relatedTarget)
+      : false;
+  }
+
+  function handleSubmenuPointerOut(
+    event: MouseEvent | PointerEvent,
+    submenuKey: string,
+    triggerId: string,
+  ): void {
+    if (isPointerStillInsideCurrentTarget(event)) return;
+    if (openSubmenuKey === submenuKey) scheduleSubmenuClose(submenuKey, triggerId, event);
+  }
+
+  function clearSubmenuCloseTimer(): void {
+    if (submenuCloseTimer !== null) {
+      clearTimeout(submenuCloseTimer);
+      submenuCloseTimer = null;
+    }
+    pendingSubmenuCloseKey = null;
+    pendingSubmenuTriggerId = null;
+    submenuLeavePoint = null;
+    latestPointerPoint = null;
+  }
+
+  function pointInTriangle(
+    point: { x: number; y: number },
+    first: { x: number; y: number },
+    second: { x: number; y: number },
+    third: { x: number; y: number },
+  ): boolean {
+    const area =
+      0.5 *
+      (-second.y * third.x +
+        first.y * (-second.x + third.x) +
+        first.x * (second.y - third.y) +
+        second.x * third.y);
+    if (area === 0) return false;
+    const sign = area < 0 ? -1 : 1;
+    const firstWeight =
+      (sign *
+        (second.y * third.x -
+          second.x * third.y +
+          (third.y - second.y) * point.x +
+          (second.x - third.x) * point.y)) /
+      (2 * Math.abs(area));
+    const secondWeight =
+      (sign *
+        (first.x * third.y -
+          first.y * third.x +
+          (first.y - third.y) * point.x +
+          (third.x - first.x) * point.y)) /
+      (2 * Math.abs(area));
+    const thirdWeight = 1 - firstWeight - secondWeight;
+    return firstWeight >= 0 && secondWeight >= 0 && thirdWeight >= 0;
+  }
+
+  function pointInRect(point: { x: number; y: number }, rect: DOMRect): boolean {
+    return (
+      point.x >= rect.left && point.x <= rect.right && point.y >= rect.top && point.y <= rect.bottom
+    );
+  }
+
+  function isPointerInsideSubmenu(submenuKey: string): boolean {
+    if (!latestPointerPoint) return false;
+    const submenu = menuElements.get(submenuKey);
+    if (!submenu) return false;
+
+    const submenuRect = submenu.getBoundingClientRect();
+    if (submenuRect.width === 0 && submenuRect.height === 0) return false;
+    return pointInRect(latestPointerPoint, submenuRect);
+  }
+
+  function isPointerMovingTowardSubmenu(triggerId: string): boolean {
+    if (!submenuLeavePoint || !latestPointerPoint) return false;
+    if (
+      submenuLeavePoint.x === latestPointerPoint.x &&
+      submenuLeavePoint.y === latestPointerPoint.y
+    ) {
+      return false;
+    }
+    const submenu = openSubmenuKey ? menuElements.get(openSubmenuKey) : undefined;
+    const trigger = findElementById(triggerId);
+    if (!submenu || !trigger) return false;
+
+    const submenuRect = submenu.getBoundingClientRect();
+    const triggerRect = trigger.getBoundingClientRect();
+    if (submenuRect.width === 0 && submenuRect.height === 0) return false;
+
+    const submenuIsInlineStart = submenuRect.right <= triggerRect.left;
+    const nearX = submenuIsInlineStart ? submenuRect.right : submenuRect.left;
+    return pointInTriangle(
+      latestPointerPoint,
+      submenuLeavePoint,
+      { x: nearX, y: submenuRect.top },
+      { x: nearX, y: submenuRect.bottom },
+    );
+  }
+
+  function clearSubmenuCloseState(): void {
+    pendingSubmenuCloseKey = null;
+    pendingSubmenuTriggerId = null;
+    submenuLeavePoint = null;
+    latestPointerPoint = null;
+  }
+
+  function armSubmenuCloseTimer(): void {
+    submenuCloseTimer = setTimeout(() => {
+      submenuCloseTimer = null;
+      const submenuKey = pendingSubmenuCloseKey;
+      const triggerId = pendingSubmenuTriggerId;
+      if (!submenuKey || !triggerId || openSubmenuKey !== submenuKey) {
+        clearSubmenuCloseState();
+        return;
+      }
+      if (isPointerInsideSubmenu(submenuKey)) {
+        clearSubmenuCloseState();
+        return;
+      }
+      if (isPointerMovingTowardSubmenu(triggerId)) {
+        submenuLeavePoint = latestPointerPoint;
+        armSubmenuCloseTimer();
+        return;
+      }
+      openSubmenuKey = null;
+      clearSubmenuCloseState();
+    }, 150);
+  }
+
+  function scheduleSubmenuClose(
+    submenuKey: string,
+    triggerId: string,
+    event: MouseEvent | PointerEvent | undefined = undefined,
+  ): void {
+    clearSubmenuCloseTimer();
+    pendingSubmenuCloseKey = submenuKey;
+    pendingSubmenuTriggerId = triggerId;
+    if (event) {
+      submenuLeavePoint = { x: event.clientX, y: event.clientY };
+      latestPointerPoint = submenuLeavePoint;
+    }
+    armSubmenuCloseTimer();
+  }
+
+  function handleDocumentPointermove(event: PointerEvent): void {
+    if (submenuCloseTimer === null) return;
+    latestPointerPoint = { x: event.clientX, y: event.clientY };
+    const submenuKey = pendingSubmenuCloseKey;
+    const triggerId = pendingSubmenuTriggerId;
+    if (!submenuKey || !triggerId || openSubmenuKey !== submenuKey) return;
+    if (isPointerInsideSubmenu(submenuKey) || isPointerMovingTowardSubmenu(triggerId)) return;
+
+    clearSubmenuCloseTimer();
+    openSubmenuKey = null;
+  }
+
+  function handleMenuTypeahead(event: KeyboardEvent, menu: HTMLElement): boolean {
+    if (!isTypeaheadKey(event)) return false;
+    const items = Array.from(
+      menu.querySelectorAll<HTMLElement>(
+        [
+          '[role="menuitem"]:not([data-disabled])',
+          '[role="menuitemcheckbox"]:not([data-disabled])',
+          '[role="menuitemradio"]:not([data-disabled])',
+        ].join(', '),
+      ),
+    ).filter((item) => item.closest('[role="menu"]') === menu);
+    if (!items.length) return false;
+
+    const currentIndex = items.findIndex((item) => item === document.activeElement);
+    const prefix = typeaheadBuffer.push(event.key);
+    const match = findTypeaheadMatch(
+      items.map((item, index) => ({
+        value: index,
+        label: item.textContent?.trim() ?? '',
+        disabled: item.hasAttribute('data-disabled'),
+      })),
+      prefix,
+      currentIndex,
+    );
+    if (match !== undefined) {
+      event.preventDefault();
+      items[match]?.focus();
+      return true;
+    }
+    return false;
+  }
+
   function handleTriggerKeydown(event: KeyboardEvent, index: number): void {
     if (event.key === 'ArrowRight' || event.key === 'ArrowLeft') {
       event.preventDefault();
-      const nextIndex = nextEnabledMenuIndex(index, event.key === 'ArrowRight' ? 1 : -1);
+      const nextIndex = nextEnabledMenuIndex(index, horizontalArrowDirection(event.key));
       if (nextIndex === -1) return;
       activeMenuIndex = nextIndex;
       focusTopLevelTrigger(nextIndex);
@@ -321,27 +587,44 @@
 
     if (openMenuIndex !== null && (event.key === 'ArrowRight' || event.key === 'ArrowLeft')) {
       const target = event.target instanceof HTMLElement ? event.target : null;
-      if (target?.closest('.cinder-menu-bar__submenu-menu')) {
-        if (event.key === 'ArrowLeft') {
-          event.preventDefault();
-          const triggerId = target
+      const submenuMenu = target?.closest<HTMLElement>('.cinder-menu-bar__submenu-menu');
+      if (submenuMenu) {
+        const triggerId =
+          submenuMenu.dataset['cinderMenuBarSubmenuTriggerId'] ??
+          submenuMenu
             .closest<HTMLElement>('.cinder-menu-bar__submenu')
             ?.querySelector<HTMLElement>('[data-cinder-menu-bar-submenu-trigger]')?.id;
+        const closeArrow =
+          resolveTextDirection(submenuMenu, resolvedDirection) === 'rtl'
+            ? 'ArrowRight'
+            : 'ArrowLeft';
+        if (event.key === closeArrow) {
+          event.preventDefault();
           openSubmenuKey = null;
-          if (triggerId) void tick().then(() => focusElement(triggerId));
+          if (triggerId) focusSubmenuTriggerAfterClose(triggerId);
         } else {
           event.preventDefault();
-          const nextIndex = nextEnabledMenuIndex(openMenuIndex, 1);
+          const nextIndex = nextEnabledMenuIndex(
+            openMenuIndex,
+            horizontalArrowDirection(event.key),
+          );
           if (nextIndex !== -1) openMenu(nextIndex, 'first');
         }
         return;
       }
 
       if (target?.closest('[role="menu"]')) {
+        const menu = target.closest<HTMLElement>('[role="menu"]');
+        if (menu && handleMenuTypeahead(event, menu)) return;
+
         event.preventDefault();
-        const nextIndex = nextEnabledMenuIndex(openMenuIndex, event.key === 'ArrowRight' ? 1 : -1);
+        const nextIndex = nextEnabledMenuIndex(openMenuIndex, horizontalArrowDirection(event.key));
         if (nextIndex !== -1) openMenu(nextIndex, 'first');
       }
+    } else {
+      const target = event.target instanceof HTMLElement ? event.target : null;
+      const menu = target?.closest<HTMLElement>('[role="menu"]');
+      if (menu) handleMenuTypeahead(event, menu);
     }
   }
 
@@ -370,12 +653,14 @@
 
 <svelte:document
   onpointerdown={handleDocumentPointerdown}
+  onpointermove={handleDocumentPointermove}
   onfocusin={handleDocumentFocusin}
   onkeydown={handleDocumentKeydown}
 />
 
 <div
   {...rest}
+  {...renderedRootDirection ? { dir: renderedRootDirection } : {}}
   bind:this={rootElement}
   id={rootId}
   class={classNames('cinder-menu-bar', customClassName)}
@@ -448,6 +733,7 @@
                     openSubmenuKey = null;
                   }}
                   onpointerenter={() => {
+                    clearSubmenuCloseTimer();
                     openSubmenuKey = null;
                   }}
                 >
@@ -461,7 +747,20 @@
               {:else if isSubmenu(entry)}
                 {@const submenuKey = submenuMenuId(menuIndex, menu, entryIndex, entry)}
                 {@const submenuTrigger = submenuTriggerId(menuIndex, menu, entryIndex, entry)}
-                <div class="cinder-menu-bar__submenu">
+                <div
+                  class="cinder-menu-bar__submenu"
+                  role="presentation"
+                  onpointerenter={() => {
+                    if (openSubmenuKey === submenuKey) clearSubmenuCloseTimer();
+                  }}
+                  onfocusin={() => {
+                    if (openSubmenuKey === submenuKey) clearSubmenuCloseTimer();
+                  }}
+                  onpointerout={(event) =>
+                    handleSubmenuPointerOut(event, submenuKey, submenuTrigger)}
+                  onmouseleave={(event) =>
+                    handleSubmenuPointerOut(event, submenuKey, submenuTrigger)}
+                >
                   <DropdownItem
                     id={submenuTrigger}
                     class="cinder-menu-bar__submenu-trigger"
@@ -479,13 +778,18 @@
                         openSubmenu(submenuKey, 'none');
                     }}
                     onpointerenter={() => {
+                      clearSubmenuCloseTimer();
                       if (openMenuIndex === menuIndex && !entry.disabled)
                         openSubmenu(submenuKey, 'none');
                     }}
+                    onpointerout={(event) =>
+                      handleSubmenuPointerOut(event, submenuKey, submenuTrigger)}
+                    onmouseleave={(event) =>
+                      handleSubmenuPointerOut(event, submenuKey, submenuTrigger)}
                     onkeydown={(event) => {
                       if (entry.disabled) return;
                       if (
-                        event.key === 'ArrowRight' ||
+                        event.key === submenuOpenArrow(submenuTrigger) ||
                         event.key === 'Enter' ||
                         event.key === ' '
                       ) {
@@ -503,7 +807,7 @@
                     context={makeContext({
                       menuId: submenuKey,
                       anchorElement: () => findElementById(submenuTrigger),
-                      fallbackPlacement: 'right-start',
+                      fallbackPlacement: () => submenuFallbackPlacement(submenuTrigger),
                       isOpen: () => openSubmenuKey === submenuKey,
                       close: () => closeMenuAndFocusTrigger(menuIndex),
                       focusTrigger: () => focusSubmenuTriggerAfterClose(submenuTrigger),
@@ -517,7 +821,19 @@
                   >
                     <DropdownMenu
                       class="cinder-menu-bar__submenu-menu"
+                      dir={submenuDirection(submenuTrigger)}
+                      data-cinder-menu-bar-submenu-trigger-id={submenuTrigger}
                       aria-labelledby={submenuTrigger}
+                      onfocusin={() => {
+                        clearSubmenuCloseTimer();
+                      }}
+                      onpointerenter={() => {
+                        clearSubmenuCloseTimer();
+                      }}
+                      onpointerout={(event) =>
+                        handleSubmenuPointerOut(event, submenuKey, submenuTrigger)}
+                      onmouseleave={(event) =>
+                        handleSubmenuPointerOut(event, submenuKey, submenuTrigger)}
                     >
                       {#each entry.items as submenuEntry, submenuEntryIndex (ancestryKey('submenu', submenuKey, submenuEntryIndex, submenuEntry.id))}
                         {#if isItem(submenuEntry)}

package/src/components/navigation-bar/README.md

@@ -47,8 +47,8 @@ the app shell:
 | Prop             | Type                                  | Required | Default    | Description                                                                                                                                                                                                                                                                                         |
 | ---------------- | ------------------------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `class`          | `string`                              | no       | —          | Custom class merged onto the root `<nav>` element.                                                                                                                                                                                                                                                  |
+| `label`          | `string`                              | no       | —          | Accessible name for the <nav> landmark. Wins over any aria-label passed via rest. Default 'Main navigation'.                                                                                                                                                                                        |
 | `mobileMenuOpen` | `boolean`                             | no       | —          | Two-way bindable open state of the mobile menu.                                                                                                                                                                                                                                                     |
-| `navAriaLabel`   | `string`                              | no       | —          | Accessible name for the <nav> landmark. Wins over any aria-label passed via rest. Default 'Main navigation'.                                                                                                                                                                                        |
 | `placement`      | `"top"` \| `"bottom"`                 | no       | `"top"`    | Visual placement mode. `bottom` renders a mobile tab-bar composition, but still does not fix or stick itself to the viewport.                                                                                                                                                                       |
 | `showLabels`     | `"always"` \| `"active"` \| `"never"` | no       | `"always"` | Label visibility for mobile bottom-tab compositions. Hidden labels remain in the accessibility tree when wrapped in `[data-cinder-navigation-label]`.                                                                                                                                               |
 | `actions`        | `(opaque)`                            | no       | —          | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                          |

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

@@ -13,7 +13,7 @@
       "id": "bottom-tabs",
       "title": "Bottom mobile tabs",
       "description": "NavigationBar can render a bottom tab-bar composition while links keep aria-current semantics.",
-      "code": "<script lang=\"ts\">\n  import { NavigationBar } from '@lostgradient/cinder/navigation-bar';\n  import { NavigationItem } from '@lostgradient/cinder/navigation-item';\n\n  let active = $state('home');\n</script>\n\n<div style=\"max-width: 28rem; border: 1px solid var(--cinder-border-muted);\">\n  <main style=\"min-height: 10rem; padding: var(--cinder-space-4);\">\n    <strong>{active}</strong>\n  </main>\n  <NavigationBar placement=\"bottom\" showLabels=\"active\" navAriaLabel=\"Mobile primary navigation\">\n    {#snippet items({ variant })}\n      <NavigationItem {variant} onclick={() => (active = 'home')} active={active === 'home'}>\n        <span aria-hidden=\"true\">H</span>\n        <span data-cinder-navigation-label>Home</span>\n      </NavigationItem>\n      <NavigationItem {variant} onclick={() => (active = 'search')} active={active === 'search'}>\n        <span aria-hidden=\"true\">S</span>\n        <span data-cinder-navigation-label>Search</span>\n      </NavigationItem>\n      <NavigationItem\n        {variant}\n        onclick={() => (active = 'settings')}\n        active={active === 'settings'}\n      >\n        <span aria-hidden=\"true\">G</span>\n        <span data-cinder-navigation-label>Settings</span>\n      </NavigationItem>\n    {/snippet}\n  </NavigationBar>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { NavigationBar } from '@lostgradient/cinder/navigation-bar';\n  import { NavigationItem } from '@lostgradient/cinder/navigation-item';\n\n  let active = $state('home');\n</script>\n\n<div style=\"max-width: 28rem; border: 1px solid var(--cinder-border-muted);\">\n  <main style=\"min-height: 10rem; padding: var(--cinder-space-4);\">\n    <strong>{active}</strong>\n  </main>\n  <NavigationBar placement=\"bottom\" showLabels=\"active\" label=\"Mobile primary navigation\">\n    {#snippet items({ variant })}\n      <NavigationItem {variant} onclick={() => (active = 'home')} active={active === 'home'}>\n        <span aria-hidden=\"true\">H</span>\n        <span data-cinder-navigation-label>Home</span>\n      </NavigationItem>\n      <NavigationItem {variant} onclick={() => (active = 'search')} active={active === 'search'}>\n        <span aria-hidden=\"true\">S</span>\n        <span data-cinder-navigation-label>Search</span>\n      </NavigationItem>\n      <NavigationItem\n        {variant}\n        onclick={() => (active = 'settings')}\n        active={active === 'settings'}\n      >\n        <span aria-hidden=\"true\">G</span>\n        <span data-cinder-navigation-label>Settings</span>\n      </NavigationItem>\n    {/snippet}\n  </NavigationBar>\n</div>\n"
     }
   ]
 }

package/src/components/navigation-bar/navigation-bar.svelte

@@ -37,7 +37,7 @@
     actions,
     menuToggle,
     mobileMenuOpen = $bindable(false),
-    navAriaLabel = 'Main navigation',
+    label = 'Main navigation',
     // Strip these from rest so they cannot collide with internal attributes.
     'aria-label': _ariaLabel,
     'data-collapsible': _dataCollapsible,
@@ -134,7 +134,7 @@
 
 <nav
   {...rest}
-  aria-label={navAriaLabel}
+  aria-label={label}
   class={classNames('cinder-navigation-bar', className)}
   data-collapsible={isCollapsible ? 'true' : 'false'}
   data-cinder-placement={placement}

package/src/components/navigation-bar/navigation-bar.types.ts

@@ -41,5 +41,5 @@ export type NavigationBarProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
   /** Two-way bindable open state of the mobile menu. */
   mobileMenuOpen?: boolean;
   /** Accessible name for the <nav> landmark. Wins over any aria-label passed via rest. Default 'Main navigation'. */
-  navAriaLabel?: string;
+  label?: string;
 };

package/src/components/number-input/README.md

@@ -16,24 +16,24 @@ Numeric text input with increment and decrement stepper controls.
 
 <!-- generated:props:start -->
 
-| Prop           | Type               | Required | Default | Description                                                                                                                |
-| -------------- | ------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `defaultValue` | `number` \| `null` | no       | —       | Initial value used when the component is uncontrolled or when the form is reset.                                           |
-| `description`  | `string`           | no       | —       | Helper text rendered below the input and associated via `aria-describedby`.                                                |
-| `disabled`     | `boolean`          | no       | —       | When true, disables the input and stepper buttons, matching the native `disabled` attribute.                               |
-| `error`        | `string`           | no       | —       | Error message rendered below the input; also sets `aria-invalid` on the input.                                             |
-| `id`           | `string`           | yes      | —       | HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. Required.                         |
-| `label`        | `string`           | no       | —       | Visible label text rendered above the input and linked via `for`/`id`.                                                     |
-| `locale`       | `string`           | no       | —       | BCP 47 locale tag used for number formatting and parsing. Defaults to `navigator.language`.                                |
-| `max`          | `number`           | no       | —       | Maximum permitted value; the stepper increment button disables when this bound is reached.                                 |
-| `min`          | `number`           | no       | —       | Minimum permitted value; the stepper decrement button disables when this bound is reached.                                 |
-| `name`         | `string`           | no       | —       | Name used to identify this field's value in form data.                                                                     |
-| `required`     | `boolean`          | no       | —       | Marks the input as required for form validation, matching the native `required` attribute.                                 |
-| `step`         | `number`           | no       | —       | Amount added or subtracted per stepper click or arrow-key press. Default `1`.                                              |
-| `value`        | `number` \| `null` | no       | —       | Bindable current numeric value, or `null` when the field is empty.                                                         |
-| `class`        | `(opaque)`         | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `format`       | `(opaque)`         | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `onchange`     | `(opaque)`         | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop           | Type               | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                 |
+| -------------- | ------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultValue` | `number` \| `null` | no       | —       | Initial value used when the component is uncontrolled or when the form is reset.                                                                                                                                                                                                                                                                                                                            |
+| `description`  | `string`           | no       | —       | Helper text rendered below the input and associated via `aria-describedby`.                                                                                                                                                                                                                                                                                                                                 |
+| `disabled`     | `boolean`          | no       | —       | When true, disables the input and stepper buttons, matching the native `disabled` attribute.                                                                                                                                                                                                                                                                                                                |
+| `error`        | `string`           | no       | —       | Error message rendered below the input; also sets `aria-invalid` on the input.                                                                                                                                                                                                                                                                                                                              |
+| `id`           | `string`           | yes      | —       | HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. Required.                                                                                                                                                                                                                                                                                                          |
+| `label`        | `string`           | no       | —       | Visible label text rendered above the input and linked via `for`/`id`.                                                                                                                                                                                                                                                                                                                                      |
+| `locale`       | `string`           | no       | —       | BCP 47 locale tag used for number formatting and parsing. Defaults to the nearest LocaleProvider locale, then `navigator.language` after mount and `en-US` during server rendering.                                                                                                                                                                                                                         |
+| `max`          | `number`           | no       | —       | Maximum permitted value; the stepper increment button disables when this bound is reached.                                                                                                                                                                                                                                                                                                                  |
+| `min`          | `number`           | no       | —       | Minimum permitted value; the stepper decrement button disables when this bound is reached.                                                                                                                                                                                                                                                                                                                  |
+| `name`         | `string`           | no       | —       | Name used to identify this field's value in form data.                                                                                                                                                                                                                                                                                                                                                      |
+| `required`     | `boolean`          | no       | —       | Marks the input as required for form validation, matching the native `required` attribute.                                                                                                                                                                                                                                                                                                                  |
+| `step`         | `number`           | no       | —       | Amount added or subtracted per stepper click or arrow-key press. Default `1`.                                                                                                                                                                                                                                                                                                                               |
+| `value`        | `number` \| `null` | no       | —       | Bindable current numeric value, or `null` when the field is empty.                                                                                                                                                                                                                                                                                                                                          |
+| `class`        | `(opaque)`         | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                     |
+| `format`       | `(opaque)`         | no       | —       | Locale-aware formatting options passed to `Intl.NumberFormat`. Supports all `Intl.NumberFormatOptions` properties such as `style` (`'decimal'`, `'currency'`, `'percent'`, `'unit'`), `currency`, `minimumFractionDigits`, `maximumFractionDigits`, and `notation`. Defaults to locale-standard decimal formatting when omitted. Not expressible in JSON Schema; see the component types for the signature. |
+| `onchange`     | `(opaque)`         | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                  |
 
 <!-- generated:props:end -->
 

package/src/components/number-input/number-input.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "number-input",
+  "import": "@lostgradient/cinder/number-input",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic number input",
+      "description": "Numeric field with label, bounds, and a committed-value display.",
+      "code": "<script lang=\"ts\">\n  import { NumberInput } from '@lostgradient/cinder/number-input';\n\n  let quantity = $state<number | null>(1);\n\n  function handleChange(value: number | null) {\n    quantity = value;\n  }\n</script>\n\n<NumberInput\n  id=\"quantity\"\n  label=\"Quantity\"\n  value={quantity}\n  min={1}\n  max={99}\n  onchange={handleChange}\n/>\n<p style=\"margin-top: 0.5rem; color: var(--cinder-text-muted);\">\n  Value: {quantity ?? 'empty'}\n</p>\n"
+    }
+  ]
+}