@lostgradient/cinder 0.1.1 → 0.3.0

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

@@ -0,0 +1,181 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  /* ========================================
+ * PRICING CARD
+ * ======================================== */
+
+  .cinder-pricing-card {
+    container-type: inline-size;
+    container-name: cinder-pricing-card;
+    display: flex;
+    flex-direction: column;
+    inline-size: 100%;
+    border-radius: var(--cinder-radius-lg);
+    background: var(--cinder-surface-raised);
+    border: 1px solid var(--cinder-border-muted);
+    color: var(--cinder-text);
+    box-shadow: var(--cinder-shadow-sm);
+    overflow: hidden;
+    transition:
+      border-color var(--cinder-duration-fast) var(--cinder-ease-standard),
+      box-shadow var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  .cinder-pricing-card[data-cinder-selected] {
+    border-color: var(--cinder-accent);
+    box-shadow:
+      var(--cinder-shadow-sm),
+      0 0 0 2px color-mix(in oklch, var(--cinder-accent), transparent 70%);
+  }
+
+  /* ----------------------------------------
+ * Header
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__header {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-1);
+    padding: var(--cinder-space-4) var(--cinder-space-4) var(--cinder-space-3);
+    border-bottom: 1px solid var(--cinder-border-muted);
+  }
+
+  .cinder-pricing-card[data-cinder-selected] .cinder-pricing-card__header {
+    background: color-mix(in oklch, var(--cinder-accent), transparent 92%);
+  }
+
+  .cinder-pricing-card__heading-row {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--cinder-space-2);
+  }
+
+  /* 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.
+   *
+   * 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-contrast);
+    background: var(--cinder-accent);
+    border-radius: var(--cinder-radius-full);
+    padding: var(--cinder-space-1) var(--cinder-space-2);
+    line-height: 1;
+  }
+
+  /* ----------------------------------------
+ * Name & price
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__name {
+    font-size: var(--cinder-text-sm);
+    font-weight: var(--cinder-font-semibold);
+    color: var(--cinder-text);
+    margin: 0;
+    letter-spacing: 0.025em;
+    text-transform: uppercase;
+  }
+
+  .cinder-pricing-card[data-cinder-selected] .cinder-pricing-card__name {
+    color: var(--cinder-accent-text);
+  }
+
+  .cinder-pricing-card__price {
+    font-size: var(--cinder-text-3xl);
+    font-weight: var(--cinder-font-bold);
+    color: var(--cinder-text);
+    margin: 0;
+    line-height: 1;
+  }
+
+  /* ----------------------------------------
+ * Body
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__body {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-3);
+    padding: var(--cinder-space-4);
+  }
+
+  /* ----------------------------------------
+ * Features list
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__features {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-2);
+  }
+
+  .cinder-pricing-card__feature {
+    display: flex;
+    align-items: baseline;
+    gap: var(--cinder-space-2);
+    font-size: var(--cinder-text-sm);
+    color: var(--cinder-text);
+  }
+
+  .cinder-pricing-card__feature::before {
+    content: '';
+    display: inline-block;
+    inline-size: 0.375rem;
+    block-size: 0.375rem;
+    border-radius: var(--cinder-radius-full);
+    background: var(--cinder-accent);
+    flex-shrink: 0;
+    translate: 0 0.1em;
+  }
+
+  /* ----------------------------------------
+ * Caveat
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__caveat {
+    font-size: var(--cinder-text-xs);
+    color: var(--cinder-text-subtle);
+    margin: 0;
+    font-style: italic;
+  }
+
+  /* ----------------------------------------
+ * Footer (CTA)
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__footer {
+    padding: var(--cinder-space-3) var(--cinder-space-4) var(--cinder-space-4);
+    border-top: 1px solid var(--cinder-border-muted);
+  }
+
+  /* ----------------------------------------
+ * Responsive
+ * ---------------------------------------- */
+
+  /* Shrink the price only when the card itself is genuinely cramped — near the
+   * tight end of an auto-fit grid (examples floor at ~14rem). A viewport @media
+   * here would be wrong: a pricing card reacts to its own box width, not the
+   * viewport (RESPONSIVE-POLICY.md). The previous 640px viewport breakpoint
+   * fired on phones; the equivalent container threshold is far smaller because
+   * pricing cards render at ~14–22rem, not full-viewport width. */
+  @container cinder-pricing-card (max-width: 16rem) {
+    .cinder-pricing-card__price {
+      font-size: var(--cinder-text-2xl);
+    }
+  }
+}

package/src/components/pricing-card/pricing-card.examples.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "pricing-card",
+  "import": "@lostgradient/cinder/pricing-card",
+  "examples": [
+    {
+      "id": "tiers",
+      "title": "Pricing tiers",
+      "description": "Three plan tiles side by side with one pre-selected.",
+      "code": "<script lang=\"ts\">\n  import { PricingCard } from '@lostgradient/cinder/pricing-card';\n\n  let selectedPlan = $state<'starter' | 'pro' | 'enterprise'>('pro');\n</script>\n\n<div\n  style=\"display: grid; grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr)); gap: var(--cinder-space-4); align-items: start;\"\n>\n  <PricingCard\n    name=\"Starter\"\n    price=\"Free\"\n    features={['3 projects', '1 GB storage', 'Community support']}\n    cta=\"Get started\"\n    selected={selectedPlan === 'starter'}\n    onselect={() => {\n      selectedPlan = 'starter';\n    }}\n  />\n\n  <PricingCard\n    name=\"Pro\"\n    price=\"$9/mo\"\n    features={['Unlimited projects', '10 GB storage', 'Priority support', 'Custom domains']}\n    cta=\"Choose Pro\"\n    selected={selectedPlan === 'pro'}\n    onselect={() => {\n      selectedPlan = 'pro';\n    }}\n  />\n\n  <PricingCard\n    name=\"Enterprise\"\n    price=\"$49/mo\"\n    features={[\n      'Unlimited projects',\n      '500 GB storage',\n      'Dedicated support',\n      'Custom domains',\n      'SSO & audit logs',\n    ]}\n    cta=\"Contact sales\"\n    selected={selectedPlan === 'enterprise'}\n    onselect={() => {\n      selectedPlan = 'enterprise';\n    }}\n  />\n</div>\n"
+    },
+    {
+      "id": "with-caveat",
+      "title": "With caveat",
+      "description": "A pricing card with a consumer-supplied caveat beneath the feature list, useful for legal disclaimers or billing notes.",
+      "code": "<script lang=\"ts\">\n  import { PricingCard } from '@lostgradient/cinder/pricing-card';\n</script>\n\n<div style=\"max-inline-size: 22rem;\">\n  <PricingCard\n    name=\"Growth\"\n    price=\"$29/mo\"\n    features={['Unlimited projects', '50 GB storage', 'Email & chat support', 'Advanced analytics']}\n    caveat=\"Billed annually. Monthly billing available at $35/mo.\"\n    cta=\"Start free trial\"\n    onselect={() => {}}\n  />\n</div>\n"
+    }
+  ]
+}

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

@@ -0,0 +1,70 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category data-display
+   * @status alpha
+   * @purpose Presents a single pricing plan with its name, price, feature list, and a call-to-action button.
+   * @tag pricing
+   * @tag plan
+   * @useWhen Letting users compare and select subscription tiers or product plans.
+   * @useWhen Highlighting one tier as selected or recommended in a pricing comparison.
+   * @avoidWhen Showing generic grouped content without a distinct price or CTA — use card instead.
+   * @avoidWhen Displaying a single key metric in isolation — use stat or stat-group instead.
+   * @related card, button, stat, stat-group
+   */
+  export type { PricingCardProps } from './pricing-card.types.ts';
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../utilities/class-names.ts';
+  import Button from '../button/button.svelte';
+  import type { PricingCardProps } from './pricing-card.types.ts';
+
+  let {
+    name,
+    price,
+    features,
+    cta,
+    onselect,
+    caveat,
+    selected = false,
+    class: className,
+    ...rest
+  }: PricingCardProps = $props();
+</script>
+
+<div
+  class={classNames('cinder-pricing-card', className)}
+  data-cinder-selected={selected ? '' : undefined}
+  aria-current={selected ? 'true' : undefined}
+  {...rest}
+>
+  <div class="cinder-pricing-card__header">
+    <div class="cinder-pricing-card__heading-row">
+      <h3 class="cinder-pricing-card__name">{name}</h3>
+      <!-- A visible, non-color cue for the selected plan: the accent border and
+           CTA tint alone would not be perceivable to a colour-blind sighted
+           user (WCAG 1.4.1), so the selected state also carries explicit text. -->
+      {#if selected}
+        <span class="cinder-pricing-card__selected-flag">Selected</span>
+      {/if}
+    </div>
+    <p class="cinder-pricing-card__price">{price}</p>
+  </div>
+
+  <div class="cinder-pricing-card__body">
+    <ul class="cinder-pricing-card__features">
+      {#each features as feature, index (index)}
+        <li class="cinder-pricing-card__feature">{feature}</li>
+      {/each}
+    </ul>
+
+    {#if caveat}
+      <p class="cinder-pricing-card__caveat" data-cinder-caveat="">{caveat}</p>
+    {/if}
+  </div>
+
+  <div class="cinder-pricing-card__footer">
+    <Button label={cta} variant={selected ? 'primary' : 'secondary'} fullWidth onclick={onselect} />
+  </div>
+</div>

package/src/components/pricing-card/pricing-card.types.ts

@@ -0,0 +1,49 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** Props for the PricingCard component. */
+export type PricingCardProps = Omit<HTMLAttributes<HTMLDivElement>, 'onselect'> & {
+  /** Plan name displayed as the card heading. */
+  name: string;
+  /** Price string, e.g. "$9/mo" or "Free". Rendered verbatim — include any currency symbol and billing period. */
+  price: string;
+  /** List of feature strings to display. Rendered as a bulleted list. */
+  features: string[];
+  /** Label for the call-to-action button. */
+  cta: string;
+  /** Called when the CTA button is clicked. */
+  onselect: () => void;
+  /**
+   * Optional footnote or caveat displayed beneath the features list.
+   * Use for legal disclaimers, billing notes, or conditional terms.
+   * Rendered in a visually subdued style to distinguish it from the main feature list.
+   */
+  caveat?: string;
+  /**
+   * Whether this card represents the currently selected plan.
+   * Sets `data-cinder-selected` and `aria-current="true"` on the root element.
+   */
+  selected?: boolean;
+  /** Merged with the root element's class list. */
+  class?: string;
+};
+
+/** Cinder-specific props for the PricingCard component, used by the schema generator. */
+export interface PricingCardSchemaProps {
+  /** Plan name displayed as the card heading. */
+  name: string;
+  /** Price string, e.g. "$9/mo" or "Free". */
+  price: string;
+  /** Feature strings to display in the bulleted list. */
+  features: string[];
+  /** Label for the call-to-action button. */
+  cta: string;
+  /** Optional footnote or caveat beneath the features list. */
+  caveat?: string;
+  /**
+   * Whether this card is the currently selected plan.
+   * @default false
+   */
+  selected?: boolean;
+  /** Custom class merged with `.cinder-pricing-card`. */
+  class?: string;
+}

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.              |
+| `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. |
 
 <!-- generated:props:end -->
 

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

@@ -7,7 +7,7 @@
       "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\" 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"
     },
     {
       "id": "disabled",

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.                                                                                   |
+| `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/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

@@ -0,0 +1,64 @@
+# ReviewEditor
+
+Markdown editor extended with inline review threads, anchored comments, and collaborative annotation state.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { ReviewEditor } from '@lostgradient/cinder/review-editor';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Building a document review experience that needs both a Markdown editor and anchored comment threads in one bundled surface.
+- Threading reviewer commentary against specific selections inside a long-form document.
+
+### Avoid When
+
+- Plain authoring with no review threads — markdown-editor is the lighter primitive.
+- Reviewing diffs between two documents rather than annotating one — use diff-viewer instead.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop              | Type                     | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------- | ------------------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`           | `string`                 | no       | —       | Additional CSS classes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `currentUserId`   | `string`                 | no       | —       | Current user ID for permissions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `id`              | `string`                 | yes      | —       | Unique identifier for accessibility (required).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `mode`            | `"edit"` \| `"readonly"` | no       | —       | Editor mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `name`            | `string`                 | no       | —       | Form field name prefix for hidden inputs (enables form participation).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `original`        | `string`                 | no       | —       | Original/baseline content for diff comparison.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `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       | —       | 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 -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

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

@@ -254,11 +254,10 @@
   }
 
   .comment-composer-textarea:focus {
-    outline: none;
     border-color: var(--cinder-accent);
-    box-shadow:
-      0 0 0 var(--cinder-ring-offset) var(--cinder-ring-offset-color),
-      0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width)) var(--cinder-accent);
+    outline: var(--cinder-ring-width) solid transparent;
+    outline-offset: var(--cinder-ring-offset);
+    box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
   .comment-composer-textarea:disabled {
@@ -271,10 +270,11 @@
     border-color: var(--cinder-danger);
   }
 
-  .comment-composer-textarea[data-has-error='true']:focus {
-    box-shadow:
-      0 0 0 var(--cinder-ring-offset) var(--cinder-ring-offset-color),
-      0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width)) var(--cinder-danger);
+  @media (forced-colors: active) {
+    .comment-composer-textarea:focus {
+      outline: var(--cinder-ring-width) solid Highlight;
+      outline-offset: 1px;
+    }
   }
 
   .comment-composer-error {

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

@@ -258,8 +258,17 @@
   }
 
   .comment-edit-textarea:focus {
-    outline: none;
     border-color: var(--cinder-accent);
+    outline: var(--cinder-ring-width) solid transparent;
+    outline-offset: var(--cinder-ring-offset);
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  @media (forced-colors: active) {
+    .comment-edit-textarea:focus {
+      outline: var(--cinder-ring-width) solid Highlight;
+      outline-offset: 1px;
+    }
   }
 
   .comment-edit-actions {

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

@@ -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-impl.svelte

@@ -59,7 +59,10 @@
     ReviewEditorDiffViewMode as DiffViewMode,
     ReviewEditorViewType as ViewType,
   } from './review-editor-types.ts';
-  import { getSelectionAnchorPosition } from './review-editor-selection-geometry.ts';
+  import {
+    getSelectionAnchorPosition,
+    type SelectionAnchorPosition,
+  } from './review-editor-selection-geometry.ts';
   import DiffViewer from '../diff-viewer/diff-viewer.svelte';
   import SelectionPopover from '../selection-popover/selection-popover.svelte';
   import { computeLineDiff, getDiffStats } from '@lostgradient/cinder/markdown/diff/line-diff';
@@ -217,7 +220,7 @@
   // =========================================================================
 
   /** Position for the selection popover (viewport-relative) */
-  let selectionPopoverPosition = $state<{ x: number; y: number } | null>(null);
+  let selectionPopoverPosition = $state<SelectionAnchorPosition | null>(null);
 
   /**
    * Captured selection range for thread creation.

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

@@ -1,6 +1,8 @@
 export type SelectionAnchorPosition = {
   x: number;
   y: number;
+  /** Height of the selection rect in CSS pixels. */
+  height: number;
 };
 
 type SelectionRangeGeometry = Pick<Range, 'getBoundingClientRect' | 'getClientRects'>;
@@ -24,5 +26,6 @@ export function getSelectionAnchorPosition(
   return {
     x: rect.left + rect.width / 2,
     y: rect.top,
+    height: rect.height,
   };
 }