@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/popover/popover.types.ts

@@ -47,6 +47,12 @@ export type PopoverProps = {
   focusManagement?: PopoverFocusManagement;
   /** Whether Popover owns trigger ARIA wiring. Default `true`. */
   wireTriggerAria?: boolean;
+  /**
+   * Whether Escape closes the Popover. Default `true`. Set `false` when a parent
+   * composite widget (e.g. Combobox) owns Escape for the whole interaction, so the
+   * Popover does not shadow the parent's handler while its panel is open.
+   */
+  closeOnEscape?: boolean;
   /** Floating panel width strategy. Default `'content'`. */
   widthMode?: PopoverWidthMode;
   /** Extra class merged onto `.cinder-popover`. */

package/src/components/portal/README.md

@@ -18,12 +18,13 @@ Moves content into `document.body` or another host element while keeping inline
 
 <!-- generated:props:start -->
 
-| Prop                | Type               | Required | Default | Description |
-| ------------------- | ------------------ | -------- | ------- | ----------- |
-| `class`             | `string`           | no       | —       |             |
-| `disabled`          | `boolean`          | no       | —       |             |
-| `inheritAttributes` | `boolean`          | no       | —       |             |
-| `target`            | `string` \| `null` | no       | —       |             |
+| Prop                | Type               | Required | Default | Description                                                                                                                        |
+| ------------------- | ------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `class`             | `string`           | no       | —       | Additional class applied to the portal wrapper element.                                                                            |
+| `disabled`          | `boolean`          | no       | —       | When true, renders the content inline in normal document flow instead of teleporting it to the target.                             |
+| `inheritAttributes` | `boolean`          | no       | —       | When true (default), HTML attributes passed to the portal are forwarded onto the wrapper element inside the target.                |
+| `target`            | `string` \| `null` | no       | —       | CSS selector string or `null` specifying where the portal content is appended. Defaults to `document.body` when `null` or omitted. |
+| `children`          | `(opaque)`         | yes      | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.         |
 
 <!-- generated:props:end -->
 

package/src/components/portal/portal.types.ts

@@ -12,9 +12,13 @@ export type PortalProps = Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'cla
 };
 
 export interface PortalSchemaProps {
+  /** CSS selector string or `null` specifying where the portal content is appended. Defaults to `document.body` when `null` or omitted. */
   target?: string | null;
+  /** When true, renders the content inline in normal document flow instead of teleporting it to the target. */
   disabled?: boolean;
+  /** Additional class applied to the portal wrapper element. */
   class?: string;
+  /** When true (default), HTML attributes passed to the portal are forwarded onto the wrapper element inside the target. */
   inheritAttributes?: boolean;
 }
 

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/README.md

@@ -26,15 +26,16 @@ Presents a single pricing plan with its name, price, feature list, an optional c
 
 <!-- generated:props:start -->
 
-| Prop       | Type       | Required | Default | Description                                            |
-| ---------- | ---------- | -------- | ------- | ------------------------------------------------------ |
-| `caveat`   | `string`   | no       | —       | Optional footnote or caveat beneath the features list. |
-| `class`    | `string`   | no       | —       | Custom class merged with `.cinder-pricing-card`.       |
-| `cta`      | `string`   | yes      | —       | Label for the call-to-action button.                   |
-| `features` | `string`[] | yes      | —       | Feature strings to display in the bulleted list.       |
-| `name`     | `string`   | yes      | —       | Plan name displayed as the card heading.               |
-| `price`    | `string`   | yes      | —       | Price string, e.g. "$9/mo" or "Free".                  |
-| `selected` | `boolean`  | no       | `false` | Whether this card is the currently selected plan.      |
+| Prop       | Type       | Required | Default | Description                                                                                                       |
+| ---------- | ---------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `caveat`   | `string`   | no       | —       | Optional footnote or caveat beneath the features list.                                                            |
+| `class`    | `string`   | no       | —       | Custom class merged with `.cinder-pricing-card`.                                                                  |
+| `cta`      | `string`   | yes      | —       | Label for the call-to-action button.                                                                              |
+| `features` | `string`[] | yes      | —       | Feature strings to display in the bulleted list.                                                                  |
+| `name`     | `string`   | yes      | —       | Plan name displayed as the card heading.                                                                          |
+| `price`    | `string`   | yes      | —       | Price string, e.g. "$9/mo" or "Free".                                                                             |
+| `selected` | `boolean`  | no       | `false` | Whether this card is the currently selected plan.                                                                 |
+| `onselect` | `(opaque)` | yes      | —       | Called when the CTA button is clicked. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

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

@@ -52,15 +52,23 @@
   }
 
   /* Non-color cue for the selected plan (WCAG 1.4.1): a text pill in the header
-   * so selection is conveyed independently of the accent treatment. */
+   * so selection is conveyed independently of the accent treatment.
+   *
+   * This is an affirmative status badge, so it uses the solid accent fill +
+   * accent-contrast label token pair (the same contract a primary Button uses),
+   * which is guaranteed to clear WCAG AA in both color-scheme arms. The earlier
+   * accent-text-on-a-tinted-chip treatment fell to ~4.1:1 in dark mode because
+   * the chip background was a near-transparent accent wash over the dark surface.
+   * The filled badge deliberately reads stronger than the faint selected-header
+   * tint above it: ambient state in the container, explicit state in the chip. */
   .cinder-pricing-card__selected-flag {
     flex-shrink: 0;
     font-size: var(--cinder-text-xs);
     font-weight: var(--cinder-font-semibold);
     letter-spacing: 0.025em;
     text-transform: uppercase;
-    color: var(--cinder-accent-text);
-    background: color-mix(in oklch, var(--cinder-accent), transparent 85%);
+    color: var(--cinder-accent-contrast);
+    background: var(--cinder-accent);
     border-radius: var(--cinder-radius-full);
     padding: var(--cinder-space-1) var(--cinder-space-2);
     line-height: 1;

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)`              | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop          | Type                    | Required | Default | Description                                                                                                                                                                                         |
+| ------------- | ----------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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  let plan = $state('pro');\n</script>\n\n<RadioGroup name=\"basic-plan\" legend=\"Pricing tier\" bind:value={plan}>\n  <RadioGroup.Option\n    id=\"basic-plan-free\"\n    value=\"free\"\n    label=\"Free — for individuals exploring Cinder\"\n  />\n  <RadioGroup.Option\n    id=\"basic-plan-pro\"\n    value=\"pro\"\n    label=\"Pro — small teams, includes private support\"\n  />\n  <RadioGroup.Option\n    id=\"basic-plan-team\"\n    value=\"team\"\n    label=\"Team — SSO, audit logs, role-based access\"\n  />\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       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                       |
+| Prop              | Type                  | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------- | --------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic rating",
       "description": "Five-star rating with whole-star precision and keyboard navigation.",
-      "code": "<script lang=\"ts\">\n  import { Rating } from '@lostgradient/cinder/rating';\n  let score = $state(0);\n</script>\n\n<Rating id=\"basic-rating\" bind:value={score} label=\"Rate this article\" />\n\n{#if score > 0}\n  <p style=\"margin-top: 0.75rem; color: var(--cinder-text-muted);\">You rated this {score} of 5.</p>\n{/if}\n"
+      "code": "<script lang=\"ts\">\n  import { Rating } from '@lostgradient/cinder/rating';\n\n  let score = $state(0);\n</script>\n\n<Rating id=\"rating\" bind:value={score} label=\"Rate this article\" />\n\n{#if score > 0}\n  <p style=\"margin-top: 0.75rem; color: var(--cinder-text-muted);\">You rated this {score} of 5.</p>\n{/if}\n"
     },
     {
       "id": "half-stars",

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/resizable-panels/resizable-panels.types.ts

@@ -63,13 +63,17 @@ export type ResizablePanelsProps = Omit<
 
 export interface ResizablePanelsSchemaProps {
   panes: ResizablePanelDefinition[];
+  /** Direction the panes are arranged. `'horizontal'` (default) places them side by side; `'vertical'` stacks them. */
   orientation?: ResizablePanelsOrientation;
   keyboardStep?: ResizablePanelSize;
   snapThreshold?: ResizablePanelSize;
+  /** When true, double-clicking a separator collapses or expands the adjacent collapsible pane. Default `false`. */
   collapseOnDoubleClick?: boolean;
+  /** Which pane to collapse when double-clicking a separator: `'leading'`, `'trailing'`, or `'nearest-collapsible'` (default). */
   collapseTarget?: ResizablePanelsCollapseTarget;
   onlayoutchange?: (event: ResizablePanelsResizeEvent) => void;
   onlayoutcommit?: (event: ResizablePanelsResizeEvent) => void;
   children: Snippet<[pane: ResizablePanelDefinition, context: ResizablePanelRenderContext]>;
+  /** Additional class merged onto the `.cinder-resizable-panels` root element. */
   class?: string;
 }

package/src/components/review-editor/README.md

@@ -37,13 +37,13 @@ Markdown editor extended with inline review threads, anchored comments, and coll
 | `placeholder`     | `string`                 | no       | —       | Placeholder text when empty.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `snapshotMode`    | `boolean`                | no       | —       | Snapshot mode for visual regression testing. When `true`: - Applies `caret-color: transparent` and `user-select: none` to the editor root via a `data-snapshot-mode` attribute, producing a stable visual state (no blinking cursor, no selection highlights). - Blurs any focused element inside the component on mount so the initial screenshot does not capture a focused ring or active caret. - The inner MarkdownEditor instance also receives `snapshotMode={true}`. This is a purely visual / CSS concern. It does NOT affect editability, ProseMirror state, or any prop controlled by `readonly` / `mode`. |
 | `value`           | `string`                 | no       | —       | Current markdown content (two-way bindable).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `onchange`        | `(opaque)`               | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `oncommentcreate` | `(opaque)`               | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `oncommentdelete` | `(opaque)`               | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `oncommentupdate` | `(opaque)`               | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `onthreadcreate`  | `(opaque)`               | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `onthreaddelete`  | `(opaque)`               | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `threads`         | `(opaque)`               | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `onchange`        | `(opaque)`               | no       | —       | Called when content changes. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `oncommentcreate` | `(opaque)`               | no       | —       | Called when a comment is created in an existing thread. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `oncommentdelete` | `(opaque)`               | no       | —       | Called when a comment is deleted. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `oncommentupdate` | `(opaque)`               | no       | —       | Called when a comment is updated. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `onthreadcreate`  | `(opaque)`               | no       | —       | Called when user initiates thread creation. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `onthreaddelete`  | `(opaque)`               | no       | —       | Called when a thread is deleted. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `threads`         | `(opaque)`               | no       | —       | Comment threads (two-way bindable). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 <!-- generated:props:end -->
 

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';
@@ -31,8 +31,8 @@ export type {
 export { createThreadManager } from './review-editor-threads.svelte';
 export type { ThreadManager, ThreadManagerOptions } from './review-editor-threads.svelte';
 
+export type { SelectionPopover, SelectionPopoverOptions } from './review-editor-selection-types.ts';
 export { createSelectionPopover } from './review-editor-selection.svelte';
-export type { SelectionPopover, SelectionPopoverOptions } from './review-editor-selection.svelte';
 
 export { createAnchorManager, toPersistedThreads } from './review-editor-anchors.svelte';
 export type { AnchorManager, AnchorManagerOptions } from './review-editor-anchors.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>