@lostgradient/cinder 0.3.0 → 0.4.1

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

package/src/components/payload-inspector/README.md

@@ -106,17 +106,17 @@ Pass a `parse` function to support alternative serialization formats:
 
 <!-- generated:props:start -->
 
-| Prop         | Type                               | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------ | ---------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `activeView` | `"summary"` \| `"tree"` \| `"raw"` | no       | —       | Initially active view tab. Defaults to "summary". Bind to control the active tab from outside.                                                                                                                                                                                                                                                                                                                                                                                          |
-| `class`      | `string`                           | no       | —       | Additional CSS classes applied to the root element.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `label`      | `string`                           | no       | —       | Label for the inspector region, used as the accessible name for the containing section. Defaults to "Payload inspector".                                                                                                                                                                                                                                                                                                                                                                |
-| `maxBytes`   | `number`                           | no       | —       | Maximum byte size before the tree view is replaced with an oversize placeholder. Defaults to 1,048,576 (1 MB). Does not affect the raw view.                                                                                                                                                                                                                                                                                                                                            |
-| `truncated`  | `boolean`                          | no       | —       | When true, the payload has been truncated by the producer (e.g. because it exceeded a wire size limit). The inspector renders a truncation badge in the summary and a notice above the raw view.                                                                                                                                                                                                                                                                                        |
-| `format`     | `(opaque)`                         | no       | —       | Custom serializer for the Raw view display text. Receives the parsed value and must return a string. Defaults to JSON.stringify with 2-space indentation. Use this to customize key ordering, indentation, or alternative serialization formats. Does not affect the Summary or Tree views, or the copy buttons. For redaction, transform the value upstream and pass the already-redacted value as `value`. Not expressible in JSON Schema; see the component types for the signature. |
-| `meta`       | `(opaque)`                         | no       | —       | Structured metadata shown in the summary panel. Pass contentType, source, and/or timestamp to populate the description list rows. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                            |
-| `parse`      | `(opaque)`                         | no       | —       | Custom parser applied when `value` is a string. Receives the raw string and must return a parsed value or throw. Defaults to JSON.parse. Use this to support alternative serialization formats. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                              |
-| `value`      | `(opaque)`                         | no       | —       | The payload value to inspect. Pass any JSON-serializable value — object, array, string, number, boolean, or null. Pass a string for already- serialized JSON; the component will attempt to parse it. Pass `undefined` when no payload is available yet. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                     |
+| Prop         | Type                                                                | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------ | ------------------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `activeView` | `"summary"` \| `"tree"` \| `"raw"`                                  | no       | —       | Initially active view tab. Defaults to "summary". Bind to control the active tab from outside.                                                                                                                                                                                                                                                                                                                                                                                          |
+| `class`      | `string`                                                            | no       | —       | Additional CSS classes applied to the root element.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `label`      | `string`                                                            | no       | —       | Label for the inspector region, used as the accessible name for the containing section. Defaults to "Payload inspector".                                                                                                                                                                                                                                                                                                                                                                |
+| `maxBytes`   | `number`                                                            | no       | —       | Maximum byte size before the tree view is replaced with an oversize placeholder. Defaults to 1,048,576 (1 MB). Does not affect the raw view.                                                                                                                                                                                                                                                                                                                                            |
+| `meta`       | { contentType?: `string`; source?: `string`; timestamp?: `string` } | no       | —       | Structured metadata shown in the summary panel. Pass contentType, source, and/or timestamp to populate the description list rows.                                                                                                                                                                                                                                                                                                                                                       |
+| `truncated`  | `boolean`                                                           | no       | —       | When true, the payload has been truncated by the producer (e.g. because it exceeded a wire size limit). The inspector renders a truncation badge in the summary and a notice above the raw view.                                                                                                                                                                                                                                                                                        |
+| `value`      | `unknown`                                                           | no       | —       | The payload value to inspect. Pass any JSON-serializable value — object, array, string, number, boolean, or null. Plain strings are rendered as string values; strings that look like serialized JSON are parsed. Pass `undefined` when no payload is available yet.                                                                                                                                                                                                                    |
+| `format`     | `(opaque)`                                                          | no       | —       | Custom serializer for the Raw view display text. Receives the parsed value and must return a string. Defaults to JSON.stringify with 2-space indentation. Use this to customize key ordering, indentation, or alternative serialization formats. Does not affect the Summary or Tree views, or the copy buttons. For redaction, transform the value upstream and pass the already-redacted value as `value`. Not expressible in JSON Schema; see the component types for the signature. |
+| `parse`      | `(opaque)`                                                          | no       | —       | Custom parser applied when `value` is a string. Receives the raw string and must return a parsed value or throw. Defaults to JSON.parse. Use this to support alternative serialization formats. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                              |
 
 <!-- generated:props:end -->
 

package/src/components/payload-inspector/index.ts

@@ -5,6 +5,8 @@ export default PayloadInspector;
 export type {
   PayloadInspectorMeta,
   PayloadInspectorProps,
+  PayloadInspectorSchemaProps,
+  PayloadInspectorSchemaValue,
   PayloadInspectorView,
 } from './payload-inspector.types.ts';
 export { PayloadInspector };

package/src/components/payload-inspector/payload-inspector.css

@@ -1,4 +1,10 @@
 @layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@import '../badge/badge.css';
+@import '../code-block/code-block.css';
+@import '../copy-button/copy-button.css';
+@import '../description-list/description-list.css';
+@import '../json-viewer/json-viewer.css';
+@import '../tabs/tabs.css';
 
 @layer cinder.components {
   .cinder-payload-inspector {

package/src/components/payload-inspector/payload-inspector.svelte

@@ -2,7 +2,7 @@
   /**
    * @cinder
    * @category data-display
-   * @status beta
+   * @status stable
    * @purpose Composed inspector for structured payloads with summary, tree, and raw views, copy actions, and size/truncation status.
    * @tag json
    * @tag inspector
@@ -16,6 +16,8 @@
   export type {
     PayloadInspectorMeta,
     PayloadInspectorProps,
+    PayloadInspectorSchemaProps,
+    PayloadInspectorSchemaValue,
     PayloadInspectorView,
   } from './payload-inspector.types.ts';
 </script>
@@ -49,12 +51,18 @@
   }: PayloadInspectorProps = $props();
 
   // --------------------------------------------------------------------------
-  // Parsing: when value is a string, attempt to parse it as JSON (or with the
-  // custom parser). On failure, mark as invalid so we can show an error state.
+  // Parsing: preserve plain string values, while still accepting serialized JSON
+  // strings for object, array, and JSON primitive payloads.
   // --------------------------------------------------------------------------
 
   type ParseResult = { ok: true; parsed: unknown } | { ok: false; error: string };
 
+  function shouldParseString(raw: string): boolean {
+    const trimmed = raw.trim();
+    if (/^[{\["]/.test(trimmed)) return true;
+    return /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)$/.test(trimmed);
+  }
+
   const parseResult = $derived.by((): ParseResult => {
     if (typeof value !== 'string') {
       return { ok: true, parsed: value };
@@ -63,6 +71,9 @@
     if (value.trim() === '') {
       return { ok: true, parsed: null };
     }
+    if (parse === undefined && !shouldParseString(value)) {
+      return { ok: true, parsed: value };
+    }
     try {
       const parser = parse ?? JSON.parse;
       return { ok: true, parsed: parser(value) };
@@ -275,11 +286,18 @@
           value={copyFormattedText}
           label="Copy formatted"
           copiedLabel="Formatted copied"
+          title="Copy formatted payload"
           iconOnly
         />
       {/if}
       {#if canCopyRaw}
-        <CopyButton value={copyRawText} label="Copy raw" copiedLabel="Raw copied" iconOnly />
+        <CopyButton
+          value={copyRawText}
+          label="Copy raw"
+          copiedLabel="Raw copied"
+          title="Copy raw payload"
+          iconOnly
+        />
       {/if}
     </div>
   </div>

package/src/components/payload-inspector/payload-inspector.types.ts

@@ -5,6 +5,8 @@ export type PayloadInspectorView = 'summary' | 'tree' | 'raw';
 
 /**
  * Structured metadata about the payload shown in the summary view.
+ *
+ * @schemaObject
  */
 export type PayloadInspectorMeta = {
   /** Content type or serializer label, e.g. "application/json" or "Protobuf". */
@@ -15,15 +17,18 @@ export type PayloadInspectorMeta = {
   timestamp?: string;
 };
 
+/** Schema-facing payload value. Kept permissive to match the runtime `unknown` prop. */
+export type PayloadInspectorSchemaValue = unknown;
+
 /**
  * Props for the PayloadInspector component.
  */
 export type PayloadInspectorProps = Omit<HTMLAttributes<HTMLElement>, 'class' | 'children'> & {
   /**
    * The payload value to inspect. Pass any JSON-serializable value — object,
-   * array, string, number, boolean, or null. Pass a string for already-
-   * serialized JSON; the component will attempt to parse it. Pass `undefined`
-   * when no payload is available yet.
+   * array, string, number, boolean, or null. Plain strings are rendered as
+   * string values; strings that look like serialized JSON are parsed. Pass
+   * `undefined` when no payload is available yet.
    */
   value?: unknown;
   /**
@@ -70,3 +75,49 @@ export type PayloadInspectorProps = Omit<HTMLAttributes<HTMLElement>, 'class' |
   /** Additional CSS classes applied to the root element. */
   class?: string;
 };
+
+/**
+ * Cinder-specific schema surface for PayloadInspector.
+ *
+ * Parser and formatter callbacks are documented but marked unsupported because
+ * functions cannot be represented as JSON Schema controls.
+ */
+export type PayloadInspectorSchemaProps = {
+  /**
+   * The payload value to inspect. Pass any JSON-serializable value — object,
+   * array, string, number, boolean, or null. Plain strings are rendered as
+   * string values; strings that look like serialized JSON are parsed. Pass
+   * `undefined` when no payload is available yet.
+   *
+   * @schemaPermissive
+   */
+  value?: PayloadInspectorSchemaValue;
+  /**
+   * When true, the payload has been truncated by the producer (e.g. because it
+   * exceeded a wire size limit). The inspector renders a truncation badge in the
+   * summary and a notice above the raw view.
+   */
+  truncated?: boolean;
+  /**
+   * Maximum byte size before the tree view is replaced with an oversize
+   * placeholder. Defaults to 1,048,576 (1 MB). Does not affect the raw view.
+   */
+  maxBytes?: number;
+  /**
+   * Structured metadata shown in the summary panel. Pass contentType, source,
+   * and/or timestamp to populate the description list rows.
+   */
+  meta?: PayloadInspectorMeta;
+  /**
+   * Initially active view tab. Defaults to "summary". Bind to control
+   * the active tab from outside.
+   */
+  activeView?: PayloadInspectorView;
+  /**
+   * Label for the inspector region, used as the accessible name for the
+   * containing section. Defaults to "Payload inspector".
+   */
+  label?: string;
+  /** Additional CSS classes applied to the root element. */
+  class?: string;
+};

package/src/components/permission-matrix/permission-matrix.css

@@ -119,6 +119,16 @@
     z-index: 1;
   }
 
+  @media (forced-colors: active) {
+    button.cinder-permission-matrix__cell-control:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      /* 2px is correct here: cell-control has border:0 so there is no
+         ButtonBorder to merge with at 2px. */
+      outline-offset: 2px;
+      box-shadow: none;
+    }
+  }
+
   @media (hover: hover) {
     button.cinder-permission-matrix__cell-control:hover {
       background: var(--cinder-surface-hover);

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

@@ -30,7 +30,7 @@ International phone-number input pairing a country-code dropdown with an as-you-
 | `hideLabel`       | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | no       | —       | Visually hide the rendered `label` while keeping it programmatically associated.                                                                                                                                                                                                                                |
 | `id`              | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | yes      | —       | Stable id used as the national input id and as the id-prefix for the dropdown.                                                                                                                                                                                                                                  |
 | `label`           | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | no       | —       | Visible group label rendered above the controls.                                                                                                                                                                                                                                                                |
-| `locale`          | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | no       | —       | BCP-47 locale used to resolve `Intl.DisplayNames`. Defaults to `navigator.language` after mount and `'en-US'` during SSR.                                                                                                                                                                                       |
+| `locale`          | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | no       | —       | BCP-47 locale used to resolve `Intl.DisplayNames`. Defaults to the nearest LocaleProvider locale, then `navigator.language` after mount and `'en-US'` during SSR.                                                                                                                                               |
 | `name`            | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | no       | —       | Form-control name applied to the hidden `<input>` that submits with the form.                                                                                                                                                                                                                                   |
 | `required`        | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | no       | —       | Mark the group as required for assistive technology.                                                                                                                                                                                                                                                            |
 | `value`           | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | no       | —       | Bindable E.164 value. Defaults to an empty string.                                                                                                                                                                                                                                                              |

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

@@ -36,6 +36,7 @@
     errorId as buildErrorId,
   } 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 {
     computeNationalResult,
@@ -67,6 +68,7 @@
   }: PhoneInputProps = $props();
 
   const context = getFormFieldContext();
+  const localeContext = getLocaleContext();
 
   const { countries: allowedCountries, usedFallback } = $derived.by(() =>
     resolveCountryList(countries),
@@ -82,6 +84,7 @@
 
   const resolvedLocale = $derived.by(() => {
     if (locale) return locale;
+    if (localeContext?.locale) return localeContext.locale;
     if (typeof navigator !== 'undefined' && typeof navigator.language === 'string') {
       return navigator.language;
     }
@@ -116,7 +119,7 @@
 
   function synchronizeNationalDigitsToCountry(
     nextCountry: PhoneInputCountryCode,
-    options?: { recomputeValue?: boolean },
+    options: { recomputeValue?: boolean } | undefined = undefined,
   ): void {
     const { recomputeValue = true } = options ?? {};
     const nationalDigits = digitsOnly(nationalDisplay);
@@ -428,6 +431,9 @@
       data-disabled={resolvedDisabled || undefined}
     >
       {label}
+      {#if resolvedRequired}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
     </span>
   {/if}
 

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

@@ -57,8 +57,9 @@ export type PhoneInputProps = {
   /** Optional allow-list constraining which countries appear in the dropdown. */
   countries?: readonly PhoneInputCountryCode[];
   /**
-   * BCP-47 locale used to resolve `Intl.DisplayNames`. Defaults to
-   * `navigator.language` after mount and `'en-US'` during SSR.
+   * BCP-47 locale used to resolve `Intl.DisplayNames`. Defaults to the nearest
+   * LocaleProvider locale, then `navigator.language` after mount and `'en-US'`
+   * during SSR.
    */
   locale?: string;
   /** Visible group label rendered above the controls. */