@lostgradient/cinder 0.3.0 → 0.4.0

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

@@ -29,6 +29,8 @@
 <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 type { DropdownContext } from '../dropdown/dropdown.types.ts';
   import DropdownItem from '../dropdown-item/dropdown-item.svelte';
@@ -47,6 +49,7 @@
 
   type RestSafeProps = MenuBarProps & {
     role?: string;
+    dir?: 'ltr' | 'rtl' | 'auto';
     'aria-label'?: string;
     'aria-labelledby'?: string;
     'aria-orientation'?: string;
@@ -59,6 +62,7 @@
     labelledBy,
     class: customClassName,
     role: _role,
+    dir: providedDirection,
     'aria-label': _ariaLabel,
     'aria-labelledby': _ariaLabelledBy,
     'aria-orientation': _ariaOrientation,
@@ -74,8 +78,37 @@
   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;
+  const localeContext = getLocaleContext();
   const menuElements = new Map<string, HTMLElement>();
+  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;
+    });
+  });
 
   const enabledIndexes = $derived(
     menus.map((menu, index) => ({ menu, index })).filter(({ menu }) => !menu.disabled),
@@ -153,6 +186,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;
   }
@@ -209,7 +247,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 +268,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 +283,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) {
@@ -258,7 +314,7 @@
   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,17 +377,27 @@
 
     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;
@@ -339,7 +405,7 @@
 
       if (target?.closest('[role="menu"]')) {
         event.preventDefault();
-        const nextIndex = nextEnabledMenuIndex(openMenuIndex, event.key === 'ArrowRight' ? 1 : -1);
+        const nextIndex = nextEnabledMenuIndex(openMenuIndex, horizontalArrowDirection(event.key));
         if (nextIndex !== -1) openMenu(nextIndex, 'first');
       }
     }
@@ -376,6 +442,7 @@
 
 <div
   {...rest}
+  {...renderedRootDirection ? { dir: renderedRootDirection } : {}}
   bind:this={rootElement}
   id={rootId}
   class={classNames('cinder-menu-bar', customClassName)}
@@ -485,7 +552,7 @@
                     onkeydown={(event) => {
                       if (entry.disabled) return;
                       if (
-                        event.key === 'ArrowRight' ||
+                        event.key === submenuOpenArrow(submenuTrigger) ||
                         event.key === 'Enter' ||
                         event.key === ' '
                       ) {
@@ -503,7 +570,7 @@
                     context={makeContext({
                       menuId: submenuKey,
                       anchorElement: () => findElementById(submenuTrigger),
-                      fallbackPlacement: 'right-start',
+                      fallbackPlacement: () => submenuFallbackPlacement(submenuTrigger),
                       isOpen: () => openSubmenuKey === submenuKey,
                       close: () => closeMenuAndFocusTrigger(menuIndex),
                       focusTrigger: () => focusSubmenuTriggerAfterClose(submenuTrigger),
@@ -517,6 +584,8 @@
                   >
                     <DropdownMenu
                       class="cinder-menu-bar__submenu-menu"
+                      dir={submenuDirection(submenuTrigger)}
+                      data-cinder-menu-bar-submenu-trigger-id={submenuTrigger}
                       aria-labelledby={submenuTrigger}
                     >
                       {#each entry.items as submenuEntry, submenuEntryIndex (ancestryKey('submenu', submenuKey, submenuEntryIndex, submenuEntry.id))}

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"
+    }
+  ]
+}

package/src/components/number-input/number-input.svelte

@@ -17,15 +17,11 @@
 
 <script lang="ts">
   import type { NumberInputProps } from './number-input.types.ts';
-  import { onMount, untrack } from 'svelte';
-
-  import {
-    ariaInvalid,
-    composeDescribedBy,
-    describeId,
-    errorId as buildErrorId,
-  } from '../../_internal/field-control.ts';
+  import { untrack } from 'svelte';
+
+  import { resolveFieldControl } from '../../_internal/field-control.ts';
   import { getFormFieldContext } from '../../_internal/form-field-context.ts';
+  import { getLocaleContext } from '../../_internal/locale-context.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import { formatNumber } from '../../utilities/format-number.ts';
   import { parseLocaleNumber } from '../../utilities/parse-locale-number.ts';
@@ -47,16 +43,22 @@
     error,
     class: className,
     onchange,
+    onblur: consumerBlur,
     'aria-describedby': consumerDescribedBy,
     ...rest
   }: NumberInputProps = $props();
 
   const context = getFormFieldContext();
+  const localeContext = getLocaleContext();
 
   let editorBuffer = $state('');
   let isFocused = $state(false);
   let hasMounted = $state(false);
   let inputElement: HTMLInputElement | undefined = $state();
+
+  $effect(() => {
+    hasMounted = true;
+  });
   // Two-part internal-invalid surface: malformed (parse failure) and
   // required-empty (no value when the field demands one). Both drive
   // `aria-invalid` so screen readers stay aligned with native validity.
@@ -71,11 +73,9 @@
     }
   });
 
-  onMount(() => {
-    hasMounted = true;
-  });
-
-  const resolvedLocale = $derived(locale ?? (hasMounted ? navigator.language : 'en-US'));
+  const resolvedLocale = $derived(
+    locale ?? localeContext?.locale ?? (hasMounted ? navigator.language : 'en-US'),
+  );
 
   const resolvedMin = $derived(typeof min === 'number' && Number.isFinite(min) ? min : -Infinity);
   const resolvedMax = $derived(typeof max === 'number' && Number.isFinite(max) ? max : Infinity);
@@ -300,6 +300,36 @@
     return formatNumber(v, resolvedLocale, editFormat);
   }
 
+  function ariaValueNowFromText(text: string): number | undefined {
+    const result = parseLocaleNumber(text, resolvedLocale, format);
+    if (result.status !== 'valid') return undefined;
+    return Number.isFinite(result.value) ? result.value : undefined;
+  }
+
+  const resolvedAriaValueNow = $derived(
+    isFocused
+      ? ariaValueNowFromText(editorBuffer)
+      : value === null || value === undefined
+        ? undefined
+        : format?.style === 'percent'
+          ? roundToPrecision(value * 100, 12)
+          : value,
+  );
+  const resolvedAriaValueMin = $derived(
+    Number.isFinite(resolvedMin)
+      ? format?.style === 'percent'
+        ? roundToPrecision(resolvedMin * 100, 12)
+        : resolvedMin
+      : undefined,
+  );
+  const resolvedAriaValueMax = $derived(
+    Number.isFinite(resolvedMax)
+      ? format?.style === 'percent'
+        ? roundToPrecision(resolvedMax * 100, 12)
+        : resolvedMax
+      : undefined,
+  );
+
   function onFocus() {
     // Preserve the editor buffer when re-focusing after a malformed blur so
     // the user can correct their own text instead of having it disappear.
@@ -309,10 +339,11 @@
     isFocused = true;
   }
 
-  function onBlur() {
+  function onBlur(event: FocusEvent & { currentTarget: EventTarget & HTMLInputElement }) {
     const buffered = editorBuffer;
     isFocused = false;
     commitFromText('typed', buffered);
+    consumerBlur?.(event);
   }
 
   function onInput(event: Event & { currentTarget: EventTarget & HTMLInputElement }) {
@@ -448,19 +479,6 @@
     };
   });
 
-  const defaultDescriptionId = $derived(describeId(id, !!description));
-  const defaultErrorId = $derived(buildErrorId(id, !!error));
-  const ownDescriptionId = $derived(
-    description && defaultDescriptionId === context?.descriptionId
-      ? `${id}-number-input-description`
-      : defaultDescriptionId,
-  );
-  const ownErrorId = $derived(
-    error && defaultErrorId === context?.errorId ? `${id}-number-input-error` : defaultErrorId,
-  );
-  const resolvedDescriptionId = $derived(ownDescriptionId ?? context?.descriptionId);
-  const resolvedErrorId = $derived(ownErrorId ?? context?.errorId);
-
   // Internal error region — rendered when the parse failed and the consumer
   // didn't supply their own `error` text. Without it, screen readers would
   // hear `aria-invalid="true"` with no associated message describing why.
@@ -473,19 +491,31 @@
   );
   const internalErrorId = $derived(internalErrorMessage ? `${id}-internal-error` : undefined);
 
-  const describedBy = $derived(
-    composeDescribedBy(
-      resolvedDescriptionId,
-      resolvedErrorId,
-      internalErrorId,
+  // `hasError` is scoped to the consumer's `error` text (which drives the
+  // rendered error <p> and its id). The broader invalid surface — internal
+  // parse failure or required-empty — is fed through `consumerInvalid` so it
+  // sets aria-invalid without fabricating an error-element id that points at
+  // nothing. The internal message is wired into describedBy via its own id.
+  const internalInvalid = $derived(malformedError || requiredEmptyError ? 'true' : undefined);
+  const field = $derived(
+    resolveFieldControl({
+      id,
+      generatedId: id,
+      context,
+      hasDescription: !!description,
+      hasError: !!error,
+      localIdNamespace: 'number-input',
       consumerDescribedBy,
-    ),
-  );
-  const resolvedAriaInvalid = $derived(
-    error || malformedError || requiredEmptyError
-      ? ariaInvalid(true)
-      : (context?.invalid ?? rest['aria-invalid'] ?? ariaInvalid(false)),
+      consumerInvalid: internalInvalid ?? (rest['aria-invalid'] as 'true' | 'false' | undefined),
+      additionalDescribedBy: [internalErrorId],
+      required,
+      disabled,
+    }),
   );
+  const ownDescriptionId = $derived(field.ownDescriptionId);
+  const ownErrorId = $derived(field.ownErrorId);
+  const describedBy = $derived(field.describedBy);
+  const resolvedAriaInvalid = $derived(field.ariaInvalid);
 
   const incrementDisabled = $derived(
     resolvedDisabled || (value !== null && value !== undefined && value >= resolvedMax),
@@ -510,6 +540,9 @@
   {#if label}
     <label for={id} class="cinder-input-field__label" data-disabled={resolvedDisabled || undefined}>
       {label}
+      {#if resolvedRequired}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
     </label>
   {/if}
 
@@ -518,6 +551,7 @@
       bind:this={inputElement}
       {id}
       type="text"
+      role="spinbutton"
       inputmode="decimal"
       value={displayValue}
       disabled={resolvedDisabled}
@@ -526,6 +560,9 @@
       {...rest}
       aria-invalid={resolvedAriaInvalid}
       aria-describedby={describedBy}
+      aria-valuenow={resolvedAriaValueNow}
+      aria-valuemin={resolvedAriaValueMin}
+      aria-valuemax={resolvedAriaValueMax}
       oninput={onInput}
       onfocus={onFocus}
       onblur={onBlur}
@@ -536,6 +573,7 @@
       class="cinder-number-input__stepper cinder-number-input__stepper--increment"
       aria-label={`Increment${stepperLabelSuffix}`}
       disabled={incrementDisabled}
+      tabindex="-1"
       onclick={() => stepBy('increment')}
     >
       <span aria-hidden="true">+</span>
@@ -545,6 +583,7 @@
       class="cinder-number-input__stepper cinder-number-input__stepper--decrement"
       aria-label={`Decrement${stepperLabelSuffix}`}
       disabled={decrementDisabled}
+      tabindex="-1"
       onclick={() => stepBy('decrement')}
     >
       <span aria-hidden="true">&#x2212;</span>

package/src/components/number-input/number-input.types.ts

@@ -11,7 +11,6 @@ export type NumberInputProps = Omit<
   | 'oninput'
   | 'onchange'
   | 'onfocus'
-  | 'onblur'
   | 'onkeydown'
 > & {
   /** HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. Required. */
@@ -21,13 +20,24 @@ export type NumberInputProps = Omit<
   /** Initial value used when the component is uncontrolled or when the form is reset. */
   defaultValue?: number | null;
   /** Minimum permitted value; the stepper decrement button disables when this bound is reached. */
-  min?: number;
+  min?: number | undefined;
   /** Maximum permitted value; the stepper increment button disables when this bound is reached. */
-  max?: number;
+  max?: number | undefined;
   /** Amount added or subtracted per stepper click or arrow-key press. Default `1`. */
-  step?: number;
+  step?: number | undefined;
+  /**
+   * 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.
+   */
   format?: Intl.NumberFormatOptions;
-  /** BCP 47 locale tag used for number formatting and parsing. Defaults to `navigator.language`. */
+  /**
+   * 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.
+   */
   locale?: string;
   /** When true, disables the input and stepper buttons, matching the native `disabled` attribute. */
   disabled?: boolean;

package/src/components/pagination/README.md

@@ -7,9 +7,11 @@ Page-navigation control for stepping through multi-page result sets.
 ```svelte
 <script lang="ts">
   import Pagination from '@lostgradient/cinder/pagination';
+
+  let currentPage = $state(1);
 </script>
 
-<Pagination />
+<Pagination bind:currentPage totalPages={10} />
 ```
 
 ## Props