@lostgradient/cinder 0.3.0 → 0.4.0

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. */

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

@@ -17,25 +17,25 @@ Segmented one-time-code input with auto-advance, paste distribution, and optiona
 
 <!-- generated:props:start -->
 
-| Prop              | Type                            | Required | Default | Description                                                                                                                                                                                                           |
-| ----------------- | ------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `aria-label`      | `string`                        | no       | —       | Group accessible name when no visible `label` is supplied.                                                                                                                                                            |
-| `aria-labelledby` | `string`                        | no       | —       | Space-separated list of ids that label the group when no `label` is supplied.                                                                                                                                         |
-| `class`           | `string`                        | no       | —       | Extra class names appended to the root group element.                                                                                                                                                                 |
-| `description`     | `string`                        | no       | —       | Optional description text rendered below the segments.                                                                                                                                                                |
-| `disabled`        | `boolean`                       | no       | —       | Disable every segment and the hidden input.                                                                                                                                                                           |
-| `error`           | `string`                        | no       | —       | Optional error message; sets `aria-invalid="true"` on every segment.                                                                                                                                                  |
-| `hideLabel`       | `boolean`                       | no       | —       | Visually hide the rendered `label` while keeping it programmatically associated.                                                                                                                                      |
-| `id`              | `string`                        | yes      | —       | Stable id used as the segment id prefix and as the hidden input id.                                                                                                                                                   |
-| `label`           | `string`                        | no       | —       | Visible group label rendered above the segments.                                                                                                                                                                      |
-| `length`          | `number`                        | no       | —       | Number of segments to render. Normalized to an integer in `[1, 12]`; non-finite or out-of-range values fall back to `6`.                                                                                              |
-| `masked`          | `boolean`                       | no       | —       | Render segments as password-style fields without changing the emitted value.                                                                                                                                          |
-| `mode`            | `"numeric"` \| `"alphanumeric"` | no       | —       | Character set accepted in each segment. Defaults to `'numeric'`.                                                                                                                                                      |
-| `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 code value. Defaults to an empty string.                                                                                                                                                                     |
-| `autocomplete`    | `(opaque)`                      | no       | —       | `autocomplete` value applied to the first segment. Defaults to `'one-time-code'` so iOS and Android can autofill SMS codes. Not expressible in JSON Schema; see the component types for the signature.                |
-| `onchange`        | `(opaque)`                      | no       | —       | Fires only for user-initiated committed value changes (typing, paste, autofill, backspace). Never fires for external prop synchronization. Not expressible in JSON Schema; see the component types for the signature. |
+| Prop              | Type                            | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ----------------- | ------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `aria-label`      | `string`                        | no       | —       | Group accessible name when no visible `label` is supplied.                                                                                                                                                                                                                                                                                                                                                                                    |
+| `aria-labelledby` | `string`                        | no       | —       | Space-separated list of ids that label the group when no `label` is supplied.                                                                                                                                                                                                                                                                                                                                                                 |
+| `class`           | `string`                        | no       | —       | Extra class names appended to the root group element.                                                                                                                                                                                                                                                                                                                                                                                         |
+| `description`     | `string`                        | no       | —       | Optional description text rendered below the segments.                                                                                                                                                                                                                                                                                                                                                                                        |
+| `disabled`        | `boolean`                       | no       | —       | Disable every segment and the hidden input.                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `error`           | `string`                        | no       | —       | Optional error message; sets `aria-invalid="true"` on every segment.                                                                                                                                                                                                                                                                                                                                                                          |
+| `hideLabel`       | `boolean`                       | no       | —       | Visually hide the rendered `label` while keeping it programmatically associated.                                                                                                                                                                                                                                                                                                                                                              |
+| `id`              | `string`                        | yes      | —       | Stable id used as the segment id prefix and as the hidden input id.                                                                                                                                                                                                                                                                                                                                                                           |
+| `label`           | `string`                        | no       | —       | Visible group label rendered above the segments.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `length`          | `number`                        | no       | —       | Number of segments to render. Normalized to an integer in `[1, 12]`; non-finite or out-of-range values fall back to `6`.                                                                                                                                                                                                                                                                                                                      |
+| `masked`          | `boolean`                       | no       | —       | Render segments as password-style fields without changing the emitted value.                                                                                                                                                                                                                                                                                                                                                                  |
+| `mode`            | `"numeric"` \| `"alphanumeric"` | no       | —       | Character set accepted in each segment. Defaults to `'numeric'`.                                                                                                                                                                                                                                                                                                                                                                              |
+| `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 code value. Defaults to an empty string. **No write-back normalization.** The bound prop reflects exactly what the consumer set — it is NOT mutated back to the filtered/length-capped value. The displayed and submitted value is normalized via `$derived`, but the binding itself is left untouched. This is intentional: the consumer owns the source of truth, and silent mutation of a bound prop is a surprising side-effect. |
+| `autocomplete`    | `(opaque)`                      | no       | —       | `autocomplete` value applied to the first segment. Defaults to `'one-time-code'` so iOS and Android can autofill SMS codes. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                        |
+| `onchange`        | `(opaque)`                      | no       | —       | Fires only for user-initiated committed value changes (typing, paste, autofill, backspace). Never fires for external prop synchronization. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                         |
 
 <!-- generated:props:end -->
 

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

@@ -78,17 +78,12 @@
   // characters, then pad to the normalized length. Every writer (commit,
   // distributeFrom, handleKeyDown) drives `value`, so deriving segments keeps
   // a single source of truth instead of a $state + sync-$effect pair.
-  const segments = $derived.by(() => {
-    const filtered = filterValue(value ?? '');
-    return Array.from({ length: normalizedLength }, (_, index) => filtered[index] ?? '');
-  });
-
-  $effect(() => {
-    // The only effectful residue: normalize the bound value when an external
-    // setter (or a length/mode change) leaves disallowed characters in it.
-    const filtered = filterValue(value ?? '');
-    if (filtered !== value) value = filtered;
-  });
+  // `normalizedValue` is the canonical form — always filtered and truncated.
+  // It is what gets displayed in segments and stored in the hidden input.
+  const normalizedValue = $derived(filterValue(value ?? ''));
+  const segments = $derived(
+    Array.from({ length: normalizedLength }, (_, index) => normalizedValue[index] ?? ''),
+  );
 
   const groupLabelId = $derived(label ? `${id}-label` : undefined);
   const defaultDescriptionId = $derived(describeId(id, !!description));
@@ -276,6 +271,9 @@
       data-disabled={resolvedDisabled || undefined}
     >
       {label}
+      {#if resolvedRequired}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
     </span>
   {/if}
 
@@ -325,7 +323,13 @@
   </div>
 
   {#if name}
-    <input type="hidden" {name} {value} required={resolvedRequired} disabled={resolvedDisabled} />
+    <input
+      type="hidden"
+      {name}
+      value={normalizedValue}
+      required={resolvedRequired}
+      disabled={resolvedDisabled}
+    />
   {/if}
 
   {#if description}

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

@@ -15,7 +15,16 @@ export type PinInputMode = 'numeric' | 'alphanumeric';
 export type PinInputProps = {
   /** Stable id used as the segment id prefix and as the hidden input id. */
   id: string;
-  /** Bindable code value. Defaults to an empty string. */
+  /**
+   * Bindable code value. Defaults to an empty string.
+   *
+   * **No write-back normalization.** The bound prop reflects exactly what the
+   * consumer set — it is NOT mutated back to the filtered/length-capped value.
+   * The displayed and submitted value is normalized via `$derived`, but the
+   * binding itself is left untouched. This is intentional: the consumer owns
+   * the source of truth, and silent mutation of a bound prop is a surprising
+   * side-effect.
+   */
   value?: string;
   /**
    * Number of segments to render. Normalized to an integer in `[1, 12]`;

package/src/components/portal/portal.utilities.svelte.ts

@@ -67,8 +67,11 @@ export function copyInheritedPortalAttributes(
     theme: element.getAttribute('data-cinder-theme'),
   },
 ) {
+  const preservesExplicitDirection = element.dataset['cinderExplicitDirection'] === 'true';
   const inheritedDir =
-    inheritAttributes && source ? source.closest<HTMLElement>('[dir]')?.getAttribute('dir') : null;
+    inheritAttributes && source && !preservesExplicitDirection
+      ? source.closest<HTMLElement>('[dir]')?.getAttribute('dir')
+      : null;
   const nextDir = inheritedDir ?? fallbackAttributes.dir;
   if (nextDir) {
     element.setAttribute('dir', nextDir);

package/src/components/pricing-card/pricing-card.svelte

@@ -17,6 +17,7 @@
 
 <script lang="ts">
   import { classNames } from '../../utilities/class-names.ts';
+  import { devWarn } from '../../utilities/dev-warn.ts';
   import Button from '../button/button.svelte';
   import type { PricingCardProps } from './pricing-card.types.ts';
 
@@ -31,6 +32,30 @@
     class: className,
     ...rest
   }: PricingCardProps = $props();
+
+  // Deduplicate features by value (first occurrence wins) so the keyed {#each}
+  // never receives duplicate keys and Svelte cannot throw each_key_duplicate.
+  // A dev warning is emitted when duplicates are found so the data author can fix
+  // their input, but the component continues to render the deduplicated list.
+  const renderableFeatures = $derived.by(() => {
+    const seen = new Set<string>();
+    const result: string[] = [];
+    let hasDuplicates = false;
+    for (const feature of features) {
+      if (seen.has(feature)) {
+        hasDuplicates = true;
+      } else {
+        seen.add(feature);
+        result.push(feature);
+      }
+    }
+    if (hasDuplicates) {
+      devWarn(
+        '[cinder/PricingCard] Duplicate feature values detected. Each feature must be unique when used as a list key. Duplicates were removed; only the first occurrence of each value is shown.',
+      );
+    }
+    return result;
+  });
 </script>
 
 <div
@@ -54,7 +79,7 @@
 
   <div class="cinder-pricing-card__body">
     <ul class="cinder-pricing-card__features">
-      {#each features as feature, index (index)}
+      {#each renderableFeatures as feature (feature)}
         <li class="cinder-pricing-card__feature">{feature}</li>
       {/each}
     </ul>

package/src/components/radio-group/README.md

@@ -16,18 +16,18 @@ Coordinates a set of radio buttons under a single name with shared validation st
 
 <!-- generated:props:start -->
 
-| Prop          | Type                    | Required | Default | Description                                                                                |
-| ------------- | ----------------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
-| `class`       | `string`                | no       | —       | Additional class names merged with `.cinder-radio-group`.                                  |
-| `description` | `string`                | no       | —       | Helper text displayed below the group; wired via `aria-describedby` on the fieldset.       |
-| `disabled`    | `boolean`               | no       | —       | Disables the entire group.                                                                 |
-| `error`       | `string`                | no       | —       | Validation error message; sets `aria-invalid="true"` on the group's children.              |
-| `legend`      | `string`                | no       | —       | Optional legend rendered as a `<legend>` inside the `<fieldset>`.                          |
-| `name`        | `string`                | yes      | —       | Shared `name` for all radios in the group; required for native form submission.            |
-| `required`    | `boolean`               | no       | —       | When true, marks the group's radios as required for form submission.                       |
-| `value`       | `string`                | no       | —       | Bound selected value.                                                                      |
-| `variant`     | `"default"` \| `"card"` | no       | —       | Visual layout. 'card' wraps each radio row in a bordered surface.                          |
-| `children`    | `(opaque)`              | yes      | —       | Radio children. Not expressible in JSON Schema; see the component types for the signature. |
+| Prop          | Type                    | Required | Default | Description                                                                                                                                                                                         |
+| ------------- | ----------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`       | `string`                | no       | —       | Additional class names merged with `.cinder-radio-group`.                                                                                                                                           |
+| `description` | `string`                | no       | —       | Helper text displayed below the group; wired via `aria-describedby` on the fieldset.                                                                                                                |
+| `disabled`    | `boolean`               | no       | —       | Disables the entire group.                                                                                                                                                                          |
+| `error`       | `string`                | no       | —       | Validation error message; sets `aria-invalid="true"` on the group's children.                                                                                                                       |
+| `label`       | `string`                | no       | —       | Visible group caption. Rendered as a `<legend>` inside the `<fieldset>`. Named `label` for consistency with every other form control — the element is a `<legend>` because the group is a fieldset. |
+| `name`        | `string`                | yes      | —       | Shared `name` for all radios in the group; required for native form submission.                                                                                                                     |
+| `required`    | `boolean`               | no       | —       | When true, marks the group's radios as required for form submission.                                                                                                                                |
+| `value`       | `string`                | no       | —       | Bound selected value.                                                                                                                                                                               |
+| `variant`     | `"default"` \| `"card"` | no       | —       | Visual layout. 'card' wraps each radio row in a bordered surface.                                                                                                                                   |
+| `children`    | `(opaque)`              | yes      | —       | Radio children. Not expressible in JSON Schema; see the component types for the signature.                                                                                                          |
 
 <!-- generated:props:end -->
 

package/src/components/radio-group/radio-group.css

@@ -15,6 +15,9 @@
   }
 
   .cinder-radio-group__legend {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cinder-space-1);
     font-size: var(--cinder-text-xs);
     font-weight: var(--cinder-font-medium);
     color: var(--cinder-text);