@lostgradient/cinder 0.3.0 → 0.4.1

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);

package/src/components/radio-group/radio-group.examples.json

@@ -7,19 +7,19 @@
       "id": "basic",
       "title": "Basic radio group",
       "description": "Three options with a group legend; arrow keys move selection.",
-      "code": "<script lang=\"ts\">\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n\n  let plan = $state('pro');\n</script>\n\n<RadioGroup name=\"plan\" legend=\"Pricing tier\" bind:value={plan}>\n  <RadioGroup.Option id=\"plan-free\" value=\"free\" label=\"Free — for individuals exploring Cinder\" />\n  <RadioGroup.Option id=\"plan-pro\" value=\"pro\" label=\"Pro — small teams, includes private support\" />\n  <RadioGroup.Option id=\"plan-team\" value=\"team\" label=\"Team — SSO, audit logs, role-based access\" />\n</RadioGroup>\n"
+      "code": "<script lang=\"ts\">\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n\n  let plan = $state('pro');\n</script>\n\n<RadioGroup name=\"plan\" label=\"Pricing tier\" bind:value={plan}>\n  <RadioGroup.Option id=\"plan-free\" value=\"free\" label=\"Free — for individuals exploring Cinder\" />\n  <RadioGroup.Option id=\"plan-pro\" value=\"pro\" label=\"Pro — small teams, includes private support\" />\n  <RadioGroup.Option id=\"plan-team\" value=\"team\" label=\"Team — SSO, audit logs, role-based access\" />\n</RadioGroup>\n"
     },
     {
       "id": "disabled",
       "title": "Disabled radio group",
       "description": "Disabling the group disables every radio inside.",
-      "code": "<script lang=\"ts\">\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n</script>\n\n<RadioGroup name=\"disabled-region\" legend=\"Region (locked for trial accounts)\" value=\"us\" disabled>\n  <RadioGroup.Option id=\"disabled-region-us\" value=\"us\" label=\"United States\" />\n  <RadioGroup.Option id=\"disabled-region-eu\" value=\"eu\" label=\"European Union\" />\n  <RadioGroup.Option id=\"disabled-region-ap\" value=\"ap\" label=\"Asia Pacific\" />\n</RadioGroup>\n"
+      "code": "<script lang=\"ts\">\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n</script>\n\n<RadioGroup name=\"disabled-region\" label=\"Region (locked for trial accounts)\" value=\"us\" disabled>\n  <RadioGroup.Option id=\"disabled-region-us\" value=\"us\" label=\"United States\" />\n  <RadioGroup.Option id=\"disabled-region-eu\" value=\"eu\" label=\"European Union\" />\n  <RadioGroup.Option id=\"disabled-region-ap\" value=\"ap\" label=\"Asia Pacific\" />\n</RadioGroup>\n"
     },
     {
       "id": "with-error",
       "title": "Radio group with error",
       "description": "When validation fails, the group exposes an aria-describedby error message.",
-      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n  let role = $state('');\n  let submitted = $state(false);\n  const showError = $derived(submitted && !role);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.75rem; align-items: flex-start;\">\n  {#if showError}\n    <RadioGroup\n      name=\"with-error-role\"\n      legend=\"Role\"\n      description=\"Pick the role that best describes you.\"\n      bind:value={role}\n      error=\"Choose a role to continue.\"\n    >\n      <RadioGroup.Option id=\"with-error-role-engineer\" value=\"engineer\" label=\"Engineer\" />\n      <RadioGroup.Option id=\"with-error-role-designer\" value=\"designer\" label=\"Designer\" />\n      <RadioGroup.Option id=\"with-error-role-manager\" value=\"manager\" label=\"Manager\" />\n    </RadioGroup>\n  {:else}\n    <RadioGroup\n      name=\"with-error-role\"\n      legend=\"Role\"\n      description=\"Pick the role that best describes you.\"\n      bind:value={role}\n    >\n      <RadioGroup.Option id=\"with-error-role-engineer\" value=\"engineer\" label=\"Engineer\" />\n      <RadioGroup.Option id=\"with-error-role-designer\" value=\"designer\" label=\"Designer\" />\n      <RadioGroup.Option id=\"with-error-role-manager\" value=\"manager\" label=\"Manager\" />\n    </RadioGroup>\n  {/if}\n\n  <Button variant=\"secondary\" onclick={() => (submitted = true)}>Try to submit</Button>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n  let role = $state('');\n  let submitted = $state(false);\n  const showError = $derived(submitted && !role);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.75rem; align-items: flex-start;\">\n  {#if showError}\n    <RadioGroup\n      name=\"with-error-role\"\n      label=\"Role\"\n      description=\"Pick the role that best describes you.\"\n      bind:value={role}\n      error=\"Choose a role to continue.\"\n    >\n      <RadioGroup.Option id=\"with-error-role-engineer\" value=\"engineer\" label=\"Engineer\" />\n      <RadioGroup.Option id=\"with-error-role-designer\" value=\"designer\" label=\"Designer\" />\n      <RadioGroup.Option id=\"with-error-role-manager\" value=\"manager\" label=\"Manager\" />\n    </RadioGroup>\n  {:else}\n    <RadioGroup\n      name=\"with-error-role\"\n      label=\"Role\"\n      description=\"Pick the role that best describes you.\"\n      bind:value={role}\n    >\n      <RadioGroup.Option id=\"with-error-role-engineer\" value=\"engineer\" label=\"Engineer\" />\n      <RadioGroup.Option id=\"with-error-role-designer\" value=\"designer\" label=\"Designer\" />\n      <RadioGroup.Option id=\"with-error-role-manager\" value=\"manager\" label=\"Manager\" />\n    </RadioGroup>\n  {/if}\n\n  <Button variant=\"secondary\" onclick={() => (submitted = true)}>Try to submit</Button>\n</div>\n"
     }
   ]
 }

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

@@ -25,11 +25,12 @@
     errorId as buildErrorId,
   } from '../../_internal/field-control.ts';
   import { classNames } from '../../utilities/class-names.ts';
+  import { devWarn } from '../../utilities/dev-warn.ts';
 
   let {
     value = $bindable(''),
     name,
-    legend,
+    label: legend,
     description,
     error,
     disabled = false,
@@ -66,6 +67,20 @@
       value = next;
     },
   });
+
+  // Warn once when no accessible group name is provided. The `hasWarned` flag
+  // stops the effect re-firing on every `legend` change — matching the
+  // tree.svelte convention and dev-warn.ts's guidance against a warn-only
+  // effect that re-subscribes on each update.
+  let hasWarnedNoLegend = false;
+  $effect(() => {
+    if (!legend && !hasWarnedNoLegend) {
+      hasWarnedNoLegend = true;
+      devWarn(
+        '[cinder/RadioGroup] A <fieldset> was rendered without a label prop. The fieldset will have no <legend>, which makes it inaccessible. Provide a label prop to describe the group.',
+      );
+    }
+  });
 </script>
 
 <!--
@@ -86,7 +101,12 @@
   data-variant={variant === 'card' ? 'card' : undefined}
 >
   {#if legend}
-    <legend class="cinder-radio-group__legend">{legend}</legend>
+    <legend class="cinder-radio-group__legend">
+      {legend}
+      {#if required}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
+    </legend>
   {/if}
 
   <div class="cinder-radio-group__items">

package/src/components/radio-group/radio-group.types.ts

@@ -24,8 +24,12 @@ export type RadioGroupProps = {
   value?: string;
   /** Shared `name` for all radios in the group; required for native form submission. */
   name: string;
-  /** Optional legend rendered as a `<legend>` inside the `<fieldset>`. */
-  legend?: string;
+  /**
+   * 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.
+   */
+  label?: string;
   /** Helper text displayed below the group; wired via `aria-describedby` on the fieldset. */
   description?: string;
   /** Validation error message; sets `aria-invalid="true"` on the group's children. */

package/src/components/rating/README.md

@@ -17,24 +17,24 @@ Star rating control with bindable numeric value, optional half-star precision, a
 
 <!-- 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.                                                                                                                                                                              |
-| `count`           | `number`              | no       | —       | Number of rating slots. Normalized to an integer in `[1, 10]`; non-finite or out-of-range values fall back to `5`.                                                                                                                 |
-| `description`     | `string`              | no       | —       | Optional description text rendered below the rating.                                                                                                                                                                               |
-| `disabled`        | `boolean`             | no       | —       | Disable every rating control and the hidden input.                                                                                                                                                                                 |
-| `error`           | `string`              | no       | —       | Optional error message; sets `aria-invalid="true"` on the rating group.                                                                                                                                                            |
-| `hideLabel`       | `boolean`             | no       | —       | Visually hide the rendered `label` while keeping it programmatically associated.                                                                                                                                                   |
-| `id`              | `string`              | yes      | —       | Stable id used as the radio-group id prefix and as the hidden input id.                                                                                                                                                            |
-| `label`           | `string`              | no       | —       | Visible group label rendered above the rating.                                                                                                                                                                                     |
-| `name`            | `string`              | no       | —       | Form-control name applied to the hidden `<input>` that submits with the form.                                                                                                                                                      |
-| `precision`       | `"whole"` \| `"half"` | no       | —       | Precision of each step. Defaults to `'whole'`.                                                                                                                                                                                     |
-| `readonly`        | `boolean`             | no       | —       | Render a non-interactive display with an accessible text equivalent.                                                                                                                                                               |
-| `required`        | `boolean`             | no       | —       | Mark the group as required for assistive technology.                                                                                                                                                                               |
-| `value`           | `number`              | no       | —       | Bindable rating value. `0` represents an unrated state. External values are clamped into `[0, count]` and snapped to the nearest precision step.                                                                                   |
-| `onchange`        | `(opaque)`            | no       | —       | Fires only for user-initiated committed value changes (click, arrow keys, Space/Enter). Never fires for hover preview or 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `count`           | `number`              | no       | —       | Number of rating slots. Normalized to an integer in `[1, 10]`; non-finite or out-of-range values fall back to `5`.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `description`     | `string`              | no       | —       | Optional description text rendered below the rating.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `disabled`        | `boolean`             | no       | —       | Disable every rating control and the hidden input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `error`           | `string`              | no       | —       | Optional error message; sets `aria-invalid="true"` on the rating group.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `hideLabel`       | `boolean`             | no       | —       | Visually hide the rendered `label` while keeping it programmatically associated.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `id`              | `string`              | yes      | —       | Stable id used as the radio-group id prefix and as the hidden input id.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `label`           | `string`              | no       | —       | Visible group label rendered above the rating.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `name`            | `string`              | no       | —       | Form-control name applied to the hidden `<input>` that submits with the form.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `precision`       | `"whole"` \| `"half"` | no       | —       | Precision of each step. Defaults to `'whole'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `readonly`        | `boolean`             | no       | —       | Render a non-interactive display with an accessible text equivalent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `required`        | `boolean`             | no       | —       | Mark the group as required for assistive technology.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `value`           | `number`              | no       | —       | Bindable rating value. `0` represents an unrated state. External values are clamped into `[0, count]` and snapped to the nearest precision step. **No write-back normalization.** The bound prop reflects exactly what the consumer set — it is NOT mutated back to the clamped/snapped 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. |
+| `onchange`        | `(opaque)`            | no       | —       | Fires only for user-initiated committed value changes (click, arrow keys, Space/Enter). Never fires for hover preview or external prop synchronization. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                    |
 
 <!-- generated:props:end -->
 

package/src/components/rating/rating.svelte

@@ -79,14 +79,6 @@
 
   const resolvedValue = $derived(snapToOption(value ?? 0));
 
-  // Mirror normalized value back onto the prop without firing onchange so
-  // consumers always see a normalized number even when they pass garbage in.
-  $effect(() => {
-    if (resolvedValue !== value) {
-      value = resolvedValue;
-    }
-  });
-
   let hoverValue = $state<number | null>(null);
   const displayValue = $derived(hoverValue ?? resolvedValue);
 

package/src/components/rating/rating.types.ts

@@ -14,6 +14,12 @@ export type RatingProps = {
   /**
    * Bindable rating value. `0` represents an unrated state. External values
    * are clamped into `[0, count]` and snapped to the nearest precision step.
+   *
+   * **No write-back normalization.** The bound prop reflects exactly what the
+   * consumer set — it is NOT mutated back to the clamped/snapped 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?: number;
   /**

package/src/components/review-editor/comment-list.svelte

@@ -1,6 +1,6 @@
 <script lang="ts" module>
   import type { Comment } from '@lostgradient/cinder/commentary/comments';
-  import type { ReviewMode } from './review-editor-types.ts';
+  import type { ReviewMode } from './review-editor.types.ts';
 
   export type CommentListProps = {
     /** Comments to display */

package/src/components/review-editor/index.ts

@@ -18,7 +18,7 @@ export type {
   ReviewEditorViewType,
   ReviewFormData,
   ReviewMode,
-} from './review-editor-types';
+} from './review-editor.types.ts';
 
 // DEP-422: Extracted runes modules for state management (experimental)
 export { createReviewEditorState } from './review-editor-state.svelte';

package/src/components/review-editor/review-editor-controls.svelte

@@ -3,7 +3,7 @@
   import type {
     ReviewEditorDiffViewMode as DiffViewMode,
     ReviewEditorViewType as ViewType,
-  } from './review-editor-types.ts';
+  } from './review-editor.types.ts';
 
   export type ReviewEditorControlsProps = {
     /** Unique ID for accessibility */
@@ -175,7 +175,7 @@
         title="Revert all changes"
       >
         <RotateCcw class="icon-sm" />
-        <span class="sr-only">Revert All</span>
+        <span class="cinder-sr-only">Revert All</span>
       </Button>
     {/if}
 
@@ -201,7 +201,12 @@
 </div>
 
 <!-- Polite live announcer for comment count changes. Empty on initial render. -->
-<div role="status" aria-live="polite" aria-atomic="true" class="comments-count-announcer sr-only">
+<div
+  role="status"
+  aria-live="polite"
+  aria-atomic="true"
+  class="comments-count-announcer cinder-sr-only"
+>
   {liveAnnouncementText}
 </div>
 

package/src/components/review-editor/review-editor-impl.svelte

@@ -7,9 +7,9 @@
     ReviewState,
     AnchorUpdate,
   } from '@lostgradient/cinder/commentary/comments';
-  import type { ReviewEditorProps, ReviewFormData } from './review-editor-types.ts';
+  import type { ReviewEditorProps, ReviewFormData } from './review-editor.types.ts';
 
-  export type { ReviewMode, ReviewEditorProps, ReviewFormData } from './review-editor-types.ts';
+  export type { ReviewMode, ReviewEditorProps, ReviewFormData } from './review-editor.types.ts';
 
   /** Type alias for thread ID to improve readability in state declarations */
   type ThreadId = string;
@@ -58,7 +58,7 @@
   import type {
     ReviewEditorDiffViewMode as DiffViewMode,
     ReviewEditorViewType as ViewType,
-  } from './review-editor-types.ts';
+  } from './review-editor.types.ts';
   import {
     getSelectionAnchorPosition,
     type SelectionAnchorPosition,
@@ -1000,7 +1000,9 @@
    * Includes document changes and comment threads
    * in a structured format suitable for LLM analysis.
    */
-  export function exportMarkdownSummary(options?: MarkdownSummaryOptions): MarkdownSummaryResult {
+  export function exportMarkdownSummary(
+    options: MarkdownSummaryOptions | undefined = undefined,
+  ): MarkdownSummaryResult {
     return generateMarkdownSummary(getState(), options);
   }
 
@@ -1008,7 +1010,9 @@
    * Export a Git-compatible unified diff.
    * The output can be applied with `git apply` or `patch` command.
    */
-  export function exportUnifiedDiff(options?: UnifiedDiffOptions): UnifiedDiffResult {
+  export function exportUnifiedDiff(
+    options: UnifiedDiffOptions | undefined = undefined,
+  ): UnifiedDiffResult {
     return generateUnifiedDiff(getState(), options);
   }
 
@@ -1683,12 +1687,12 @@
           plugins={[anchorPlugin]}
           {snapshotMode}
           onchange={handleEditorBodyChange}
-          onReady={() => {
+          onready={() => {
             if (!editorViewReady) {
               editorViewReady = true;
             }
           }}
-          onSelectionChange={handleSelectionChange}
+          onselectionchange={handleSelectionChange}
         />
       </div>
     {:else if activeView === 'diff'}

package/src/components/review-editor/review-editor-selection-types.ts

@@ -8,7 +8,7 @@ import type {
   PopoverPosition,
   ReviewMode,
   ReviewEditorViewType as ViewType,
-} from './review-editor-types.ts';
+} from './review-editor.types.ts';
 
 /**
  * Options for creating the selection popover manager.

package/src/components/review-editor/review-editor-selection.svelte.ts

@@ -25,7 +25,7 @@ import { extractMentions, generateId } from '@lostgradient/cinder/commentary/com
 import { devWarn } from '../../utilities/dev-warn.ts';
 import { getSelectionAnchorPosition } from './review-editor-selection-geometry.ts';
 import type { SelectionPopover, SelectionPopoverOptions } from './review-editor-selection-types.ts';
-import type { PopoverPosition } from './review-editor-types';
+import type { PopoverPosition } from './review-editor.types.ts';
 
 /** Debounce delay for selection position calculation (ms) */
 const SELECTION_DEBOUNCE_MS = 20;

package/src/components/review-editor/review-editor-state.svelte.ts

@@ -20,7 +20,7 @@ import { normalize } from '@lostgradient/cinder/markdown/pipeline';
 import type {
   ReviewEditorDiffViewMode as DiffViewMode,
   ReviewEditorViewType as ViewType,
-} from './review-editor-types';
+} from './review-editor.types.ts';
 
 /**
  * Diff statistics for tracking content changes.

package/src/components/review-editor/review-editor-threads.svelte.ts

@@ -35,13 +35,13 @@ import {
 } from '@lostgradient/cinder/commentary/comments';
 import type { EditorView } from '@milkdown/kit/prose/view';
 import { devWarn } from '../../utilities/dev-warn.ts';
-import type { PopoverPosition, ReviewMode } from './review-editor-types';
+import type { PopoverPosition, ReviewMode } from './review-editor.types.ts';
 
 /** Type alias for thread ID to improve readability */
 type ThreadId = string;
 
 // Re-export PopoverPosition for backwards compatibility
-export type { PopoverPosition } from './review-editor-types';
+export type { PopoverPosition } from './review-editor.types.ts';
 
 /**
  * Options for creating the thread manager.