@lostgradient/cinder 0.2.0 → 0.4.0

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

@@ -21,6 +21,15 @@
     border-bottom: 1px solid var(--cinder-border-muted);
   }
 
+  .cinder-navigation-bar[data-cinder-placement='bottom'] {
+    justify-content: center;
+    min-height: 4rem;
+    height: auto;
+    padding-inline: var(--cinder-space-2);
+    border-bottom: none;
+    border-top: 1px solid var(--cinder-border-muted);
+  }
+
   /* ----------------------------------------
  * Sections
  * ---------------------------------------- */
@@ -44,6 +53,12 @@
     min-width: 0;
   }
 
+  .cinder-navigation-bar[data-cinder-placement='bottom'] .cinder-navigation-bar__items {
+    align-self: stretch;
+    justify-content: space-around;
+    gap: 0;
+  }
+
   .cinder-navigation-bar__actions {
     display: flex;
     align-items: center;
@@ -60,6 +75,53 @@
     display: none;
   }
 
+  .cinder-navigation-bar[data-cinder-placement='bottom']
+    .cinder-navigation-item[data-variant='mobile'] {
+    flex: 1 1 0;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    gap: var(--cinder-space-1);
+    min-block-size: 3.75rem;
+    padding: var(--cinder-space-2);
+    border-bottom: none;
+    border-top: 2px solid transparent;
+    border-radius: 0;
+    text-align: center;
+  }
+
+  .cinder-navigation-bar[data-cinder-placement='bottom']
+    .cinder-navigation-item[data-variant='mobile'][data-active='true'] {
+    border-top-color: var(--cinder-accent);
+    background-color: var(--cinder-surface-inset);
+  }
+
+  .cinder-navigation-bar[data-cinder-placement='bottom']
+    .cinder-navigation-item[data-variant='mobile']
+    [data-cinder-navigation-label] {
+    max-inline-size: 100%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .cinder-navigation-bar[data-cinder-placement='bottom'][data-cinder-label-visibility='active']
+    .cinder-navigation-item[data-variant='mobile']:not([data-active='true'])
+    [data-cinder-navigation-label],
+  .cinder-navigation-bar[data-cinder-placement='bottom'][data-cinder-label-visibility='never']
+    .cinder-navigation-item[data-variant='mobile']
+    [data-cinder-navigation-label] {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
   /* ----------------------------------------
  * Collapsible mobile mode
  * Scoped under [data-collapsible='true'] so non-opted-in bars are
@@ -132,5 +194,9 @@
     .cinder-navigation-bar[data-collapsible='true'] .cinder-navigation-bar__items {
       border-bottom-color: CanvasText;
     }
+
+    .cinder-navigation-bar[data-cinder-placement='bottom'] {
+      border-top-color: CanvasText;
+    }
   }
 }

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

@@ -8,6 +8,12 @@
       "title": "Basic navigation bar",
       "description": "Brand, link and button navigation items, disabled state, and an action in the trailing slot.",
       "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { NavigationBar } from '@lostgradient/cinder/navigation-bar';\n  import { NavigationItem } from '@lostgradient/cinder/navigation-item';\n  let active = $state('home');\n  let mobileMenuOpen = $state(false);\n</script>\n\n<NavigationBar bind:mobileMenuOpen>\n  {#snippet brand()}\n    <strong>Acme</strong>\n  {/snippet}\n  {#snippet menuToggle(attrs)}\n    <button type=\"button\" {...attrs} aria-label={mobileMenuOpen ? 'Close menu' : 'Open menu'}>\n      <span aria-hidden=\"true\">☰</span>\n    </button>\n  {/snippet}\n  {#snippet items({ variant })}\n    <NavigationItem {variant} onclick={() => (active = 'home')} active={active === 'home'}>\n      Home\n    </NavigationItem>\n    <NavigationItem {variant} onclick={() => (active = 'docs')} active={active === 'docs'}>\n      Docs\n    </NavigationItem>\n    <NavigationItem {variant} href=\"#blog\" active={active === 'blog'}>Blog</NavigationItem>\n    <NavigationItem {variant} onclick={() => (active = 'billing')} disabled>Billing</NavigationItem>\n  {/snippet}\n  {#snippet actions()}\n    <Button variant=\"primary\" size=\"sm\" label=\"Sign up\" />\n  {/snippet}\n</NavigationBar>\n"
+    },
+    {
+      "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\" 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

@@ -13,7 +13,9 @@
    * @related navigation-item, breadcrumbs, side-navigation
    */
   export type {
+    NavigationBarLabelVisibility,
     NavigationBarItemsContext,
+    NavigationBarPlacement,
     NavigationBarProps,
     NavigationBarToggleAttributes,
     NavigationVariant,
@@ -28,22 +30,28 @@
 
   let {
     class: className,
+    placement = 'top',
+    showLabels = 'always',
     brand,
     items,
     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,
+    'data-cinder-placement': _dataCinderPlacement,
+    'data-cinder-label-visibility': _dataCinderLabelVisibility,
     onkeydown: consumerOnKeyDown,
     ...rest
   }: NavigationBarProps = $props();
   const navigationItemSelector = '[data-cinder-navigation-item]';
 
+  const isCollapsible = $derived(placement === 'top' && menuToggle !== undefined);
+
   const variant: NavigationVariant = $derived(
-    menuToggle !== undefined && mobileMenuOpen ? 'mobile' : 'horizontal',
+    placement === 'bottom' ? 'mobile' : isCollapsible && mobileMenuOpen ? 'mobile' : 'horizontal',
   );
 
   // Stores the toggle element for focus return after Escape-close.
@@ -99,7 +107,7 @@
     }
     if (event.defaultPrevented) return;
 
-    if (event.key === 'Escape' && mobileMenuOpen) {
+    if (event.key === 'Escape' && isCollapsible && mobileMenuOpen) {
       mobileMenuOpen = false;
       // Return focus synchronously — toggleElement is captured on each click.
       toggleElement?.focus();
@@ -126,9 +134,11 @@
 
 <nav
   {...rest}
-  aria-label={navAriaLabel}
+  aria-label={label}
   class={classNames('cinder-navigation-bar', className)}
-  data-collapsible={menuToggle !== undefined ? 'true' : 'false'}
+  data-collapsible={isCollapsible ? 'true' : 'false'}
+  data-cinder-placement={placement}
+  data-cinder-label-visibility={showLabels}
   onkeydown={handleKeyDown}
 >
   {#if brand}
@@ -137,7 +147,7 @@
     </div>
   {/if}
 
-  {#if menuToggle}
+  {#if isCollapsible && menuToggle}
     <div class="cinder-navigation-bar__menu-toggle">
       {@render menuToggle({
         'aria-expanded': (mobileMenuOpen ? 'true' : 'false') as 'true' | 'false',
@@ -152,9 +162,9 @@
     id={regionId}
     class="cinder-navigation-bar__items"
     data-open={mobileMenuOpen ? 'true' : 'false'}
-    inert={menuToggle !== undefined && !mobileMenuOpen ? true : undefined}
+    inert={isCollapsible && !mobileMenuOpen ? true : undefined}
   >
-    {@render items({ variant })}
+    {@render items({ variant, placement, showLabels })}
   </div>
 
   {#if actions}

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

@@ -1,6 +1,8 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 export type NavigationVariant = 'horizontal' | 'mobile';
+export type NavigationBarPlacement = 'top' | 'bottom';
+export type NavigationBarLabelVisibility = 'always' | 'active' | 'never';
 /** Attributes injected into the consumer's toggle button via the menuToggle snippet parameter. */
 export type NavigationBarToggleAttributes = {
   'aria-expanded': 'true' | 'false';
@@ -10,10 +12,26 @@ export type NavigationBarToggleAttributes = {
 /** Context passed to the items snippet so items can adapt their layout. */
 export type NavigationBarItemsContext = {
   variant: NavigationVariant;
+  placement?: NavigationBarPlacement;
+  showLabels?: NavigationBarLabelVisibility;
 };
 export type NavigationBarProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
   /** Custom class merged onto the root `<nav>` element. */
   class?: string;
+  /**
+   * Visual placement mode. `bottom` renders a mobile tab-bar composition, but
+   * still does not fix or stick itself to the viewport.
+   *
+   * @default "top"
+   */
+  placement?: NavigationBarPlacement;
+  /**
+   * Label visibility for mobile bottom-tab compositions. Hidden labels remain in
+   * the accessibility tree when wrapped in `[data-cinder-navigation-label]`.
+   *
+   * @default "always"
+   */
+  showLabels?: NavigationBarLabelVisibility;
   brand?: Snippet;
   /** Receives a context object with the current variant. */
   items: Snippet<[NavigationBarItemsContext]>;
@@ -23,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/navigation-item/README.md

@@ -18,14 +18,14 @@ Individual link or button within a navigation bar, supporting active and disable
 
 | Prop       | Type                                                                     | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | ---------- | ------------------------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `active`   | `boolean`                                                                | no       | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `class`    | `string`                                                                 | no       | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `active`   | `boolean`                                                                | no       | —       | Marks this item as the currently active destination; emits `aria-current` and applies active visual styling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `class`    | `string`                                                                 | no       | —       | Additional class merged onto the `.cinder-navigation-item` root element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `current`  | `"true"` \| `"page"` \| `"step"` \| `"location"` \| `"date"` \| `"time"` | no       | —       | The `aria-current` token emitted while `active` is true. Defaults to `'page'`, which is correct for navigation bars and breadcrumb-adjacent links. Use `'true'` (or another standard token such as `'step'` / `'location'`) for section/view switchers, where `'page'` would mislabel the current section as the current page in the browsing context.                                                                                                                                                                                                                                                  |
-| `disabled` | `boolean`                                                                | no       | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `href`     | `string`                                                                 | no       | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `disabled` | `boolean`                                                                | no       | —       | Prevents interaction: removes the item from the tab order, blocks clicks, and applies disabled visual styling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `href`     | `string`                                                                 | no       | —       | Destination URL. Providing this prop renders the item as an `<a>` element instead of a `<button>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `variant`  | `"horizontal"` \| `"vertical"` \| `"mobile"`                             | no       | —       | Controls item geometry. Emitted as `data-variant`. Default `'horizontal'`. - `'horizontal'`: top-rounded radius, accent bottom-border active indicator. Used inside `NavigationBar` and similar horizontal tab-bar contexts. - `'mobile'`: stacked full-width layout when an owning navigation surface enters its narrow container mode. - `'vertical'`: square row geometry, neutral selected surface, and accent inline-start border active indicator. Used inside `SideNavigation` (set automatically by `SideNavigationItem`) or standalone sidebar footers where flush sidebar edges are required. |
-| `children` | `(opaque)`                                                               | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `onclick`  | `(opaque)`                                                               | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `children` | `(opaque)`                                                               | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `onclick`  | `(opaque)`                                                               | no       | —       | Optional click handler called for the rendered `<a>` element. Useful for intercepting plain left-clicks for SPA navigation while letting modified clicks (cmd/ctrl/shift/alt or middle-click) fall through to native browser behavior. Disabled-state preventDefault still applies. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                          |
 
 <!-- generated:props:end -->
 

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

@@ -2,7 +2,9 @@ import type { Snippet } from 'svelte';
 import type { HTMLAnchorAttributes, HTMLButtonAttributes } from 'svelte/elements';
 
 type CommonArm = {
+  /** Marks this item as the currently active destination; emits `aria-current` and applies active visual styling. */
   active?: boolean;
+  /** Prevents interaction: removes the item from the tab order, blocks clicks, and applies disabled visual styling. */
   disabled?: boolean;
   /**
    * The `aria-current` token emitted while `active` is true. Defaults to `'page'`,
@@ -12,6 +14,7 @@ type CommonArm = {
    * the current page in the browsing context.
    */
   current?: 'page' | 'step' | 'location' | 'date' | 'time' | 'true';
+  /** Additional class merged onto the `.cinder-navigation-item` root element. */
   class?: string;
   /**
    * Controls item geometry. Emitted as `data-variant`. Default `'horizontal'`.
@@ -35,6 +38,7 @@ type CommonArm = {
 // `buttonAttributes` runtime cast).
 export type LinkArm = CommonArm &
   Omit<HTMLAnchorAttributes, 'class' | 'href' | 'onclick' | 'aria-current' | 'aria-disabled'> & {
+    /** Destination URL. Providing this prop renders the item as an `<a>` element instead of a `<button>`. */
     href: string;
     /**
      * Optional click handler called for the rendered `<a>` element. Useful for

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       | —       |                                                                                                                            |
-| `description`  | `string`           | no       | —       |                                                                                                                            |
-| `disabled`     | `boolean`          | no       | —       |                                                                                                                            |
-| `error`        | `string`           | no       | —       |                                                                                                                            |
-| `id`           | `string`           | yes      | —       |                                                                                                                            |
-| `label`        | `string`           | no       | —       |                                                                                                                            |
-| `locale`       | `string`           | no       | —       |                                                                                                                            |
-| `max`          | `number`           | no       | —       |                                                                                                                            |
-| `min`          | `number`           | no       | —       |                                                                                                                            |
-| `name`         | `string`           | no       | —       |                                                                                                                            |
-| `required`     | `boolean`          | no       | —       |                                                                                                                            |
-| `step`         | `number`           | no       | —       |                                                                                                                            |
-| `value`        | `number` \| `null` | no       | —       |                                                                                                                            |
-| `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,22 +11,45 @@ export type NumberInputProps = Omit<
   | 'oninput'
   | 'onchange'
   | 'onfocus'
-  | 'onblur'
   | 'onkeydown'
 > & {
+  /** HTML `id` for the underlying input, used to associate the `<label>` and ARIA attributes. Required. */
   id: string;
+  /** Bindable current numeric value, or `null` when the field is empty. */
   value?: number | null;
+  /** Initial value used when the component is uncontrolled or when the form is reset. */
   defaultValue?: number | null;
-  min?: number;
-  max?: number;
-  step?: number;
+  /** Minimum permitted value; the stepper decrement button disables when this bound is reached. */
+  min?: number | undefined;
+  /** Maximum permitted value; the stepper increment button disables when this bound is reached. */
+  max?: number | undefined;
+  /** Amount added or subtracted per stepper click or arrow-key press. Default `1`. */
+  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 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;
+  /** Marks the input as required for form validation, matching the native `required` attribute. */
   required?: boolean;
+  /** Name used to identify this field's value in form data. */
   name?: string;
+  /** Visible label text rendered above the input and linked via `for`/`id`. */
   label?: string;
+  /** Helper text rendered below the input and associated via `aria-describedby`. */
   description?: string;
+  /** Error message rendered below the input; also sets `aria-invalid` on the input. */
   error?: string;
   class?: string;
   onchange?: (value: number | null) => void;