@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/checkbox/checkbox.svelte

@@ -21,10 +21,12 @@
   import { getFormFieldContext } from '../../_internal/form-field-context.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import { devWarn } from '../../utilities/dev-warn.ts';
+  import { commitValue } from '../../utilities/value-change.ts';
 
   let {
     id,
     checked = $bindable(false),
+    onValueChange,
     indeterminate = $bindable(false),
     label,
     description,
@@ -34,6 +36,7 @@
     class: className,
     'aria-describedby': consumerDescribedBy,
     'aria-invalid': consumerInvalid,
+    onchange: consumerOnchange,
     ...rest
   }: CheckboxProps = $props();
 
@@ -82,6 +85,41 @@
       inputElement.indeterminate = indeterminate && !checked;
     }
   });
+  let resetSyncTimeout: ReturnType<typeof setTimeout> | undefined;
+
+  function syncCheckedAfterFormReset(): void {
+    if (resetSyncTimeout !== undefined) clearTimeout(resetSyncTimeout);
+    resetSyncTimeout = setTimeout(() => {
+      resetSyncTimeout = undefined;
+      if (!inputElement) return;
+      checked = inputElement.checked;
+      inputElement.indeterminate = indeterminate && !inputElement.checked;
+    }, 0);
+  }
+
+  $effect(() => {
+    const form = inputElement?.form;
+    if (!form) return;
+
+    form.addEventListener('reset', syncCheckedAfterFormReset);
+    return () => {
+      form.removeEventListener('reset', syncCheckedAfterFormReset);
+      if (resetSyncTimeout !== undefined) {
+        clearTimeout(resetSyncTimeout);
+        resetSyncTimeout = undefined;
+      }
+    };
+  });
+
+  function handleChange(event: Event): void {
+    const target = event.currentTarget as HTMLInputElement;
+    const committed = commitValue(target.checked, onValueChange, (next) => {
+      checked = next;
+    });
+    target.checked = committed;
+    target.indeterminate = indeterminate && !committed;
+    consumerOnchange?.(event as Parameters<NonNullable<CheckboxProps['onchange']>>[0]);
+  }
 </script>
 
 <div class="cinder-checkbox-field">
@@ -91,13 +129,14 @@
         bind:this={inputElement}
         id={field.id}
         type="checkbox"
+        {...rest}
         disabled={field.disabled}
         required={field.required}
-        bind:checked
+        {checked}
+        onchange={handleChange}
         class={classNames('cinder-checkbox', className)}
         aria-invalid={field.ariaInvalid}
         aria-describedby={field.describedBy}
-        {...rest}
       />
       <span class="cinder-checkbox-field__indicator" aria-hidden="true"></span>
     </span>
@@ -108,6 +147,9 @@
         data-disabled={field.disabled || undefined}
       >
         {label}
+        {#if field.required}
+          <span class="cinder-_required-marker" aria-hidden="true">*</span>
+        {/if}
       </label>
     {/if}
   </div>

package/src/components/checkbox/checkbox.types.ts

@@ -20,6 +20,8 @@ export type CheckboxProps = HTMLInputAttributes & {
   id?: string;
   /** Bound checked state. */
   checked?: boolean;
+  /** Intercept a proposed checked state before the bindable value is written. Return a replacement value to transform it. */
+  onValueChange?: (next: boolean) => boolean | void;
   /** Bound indeterminate state. Mutually exclusive with `checked` visually. */
   indeterminate?: boolean;
   /** Visible label rendered in a `<label>` element associated via `for`. */

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

@@ -22,10 +22,10 @@ Wraps multiple checkboxes under a shared label and validation context.
 | `description` | `string`                | no       | —       | Helper text below the group; wired via `aria-describedby` on the fieldset.                                                                                                                                                                                                                                                                                                                                                                                       |
 | `disabled`    | `boolean`               | no       | —       | Disables every native form control inside via the fieldset's built-in cascade. Renders as the native `disabled` attribute on `<fieldset>`.                                                                                                                                                                                                                                                                                                                       |
 | `error`       | `string`                | no       | —       | Group-level validation message. Rendered as a polite live region and referenced by the fieldset's `aria-describedby`. Also sets `aria-invalid="true"` on the fieldset itself as a supplementary signal. Note: fieldset-level `aria-describedby` is not reliably re-announced as focus moves between descendants. This is best-effort supplemental context — if a specific control must announce as invalid on focus, pass `error` to that `<Checkbox>` directly. |
-| `legend`      | `string`                | no       | —       | Optional legend rendered as a `<legend>` inside the `<fieldset>`.                                                                                                                                                                                                                                                                                                                                                                                                |
-| `required`    | `boolean`               | no       | —       | Marks the group as visually required. Sets `data-cinder-required` on the fieldset so consumers can target it (e.g. legend asterisk). This is a visual/data-attribute hint. It does NOT set `required` on any child `<input>` and does NOT enforce constraint validation. Per-control `required` must be set on the individual `<Checkbox>`.                                                                                                                      |
+| `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.                                                                                                                                                                                                                                                              |
+| `required`    | `boolean`               | no       | —       | Marks the group required: sets `aria-required="true"` and `data-cinder-required` on the fieldset and renders the required asterisk in the legend. It does NOT set `required` on any child `<input>` and does NOT enforce native constraint validation. Per-control `required` must be set on the individual `<Checkbox>`.                                                                                                                                        |
 | `variant`     | `"default"` \| `"card"` | no       | —       | Layout variant. `'default'` is a stacked column. `'card'` styles each direct child `.cinder-checkbox-field` as a bordered card row. Always emitted as `data-variant` on the fieldset. Card variant assumes each direct child of the items container is a single `<Checkbox>`.                                                                                                                                                                                    |
-| `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.                                                                                                                                                                                                                                                                                                                                       |
+| `children`    | `(opaque)`              | yes      | —       | Checkbox children. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                    |
 
 <!-- generated:props:end -->
 

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

@@ -15,6 +15,9 @@
   }
 
   .cinder-checkbox-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/checkbox-group/checkbox-group.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "checkbox-group",
+  "import": "@lostgradient/cinder/checkbox-group",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic checkbox group",
+      "description": "Grouped checkboxes under a shared legend with independent checked states.",
+      "code": "<script lang=\"ts\">\n  import { Checkbox } from '@lostgradient/cinder/checkbox';\n  import { CheckboxGroup } from '@lostgradient/cinder/checkbox-group';\n\n  let email = $state(true);\n  let sms = $state(false);\n  let push = $state(false);\n</script>\n\n<CheckboxGroup label=\"Notification channels\">\n  <Checkbox id=\"email\" label=\"Email\" bind:checked={email} />\n  <Checkbox id=\"sms\" label=\"SMS\" bind:checked={sms} />\n  <Checkbox id=\"push\" label=\"Push notifications\" bind:checked={push} />\n</CheckboxGroup>\n"
+    }
+  ]
+}

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

@@ -23,11 +23,12 @@
     errorId as buildErrorId,
   } from '../../_internal/field-control.ts';
   import { classNames } from '../../utilities/class-names.ts';
+  import { devWarn } from '../../utilities/dev-warn.ts';
 
   const groupId = $props.id();
 
   let {
-    legend,
+    label: legend,
     description,
     error,
     disabled = false,
@@ -39,6 +40,20 @@
   const descriptionId = $derived(describeId(groupId, !!description));
   const errId = $derived(buildErrorId(groupId, !!error));
   const describedBy = $derived(composeDescribedBy(descriptionId, errId));
+
+  // 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/CheckboxGroup] 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>
 
 <!--
@@ -58,12 +73,18 @@
   {disabled}
   aria-invalid={ariaInvalid(!!error)}
   aria-describedby={describedBy}
+  aria-required={required || undefined}
   data-cinder-disabled={disabled || undefined}
   data-cinder-required={required || undefined}
   data-variant={variant}
 >
   {#if legend}
-    <legend class="cinder-checkbox-group__legend">{legend}</legend>
+    <legend class="cinder-checkbox-group__legend">
+      {legend}
+      {#if required}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
+    </legend>
   {/if}
 
   <div class="cinder-checkbox-group__items">

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

@@ -9,8 +9,12 @@ import type { Snippet } from 'svelte';
  * handles the disabled cascade without any Svelte context.
  */
 export type CheckboxGroupProps = {
-  /** 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 below the group; wired via `aria-describedby` on the fieldset. */
   description?: string;
   /**
@@ -30,12 +34,13 @@ export type CheckboxGroupProps = {
    */
   disabled?: boolean;
   /**
-   * Marks the group as visually required. Sets `data-cinder-required` on the
-   * fieldset so consumers can target it (e.g. legend asterisk).
+   * Marks the group required: sets `aria-required="true"` and
+   * `data-cinder-required` on the fieldset and renders the required asterisk in
+   * the legend.
    *
-   * This is a visual/data-attribute hint. It does NOT set `required` on any
-   * child `<input>` and does NOT enforce constraint validation. Per-control
-   * `required` must be set on the individual `<Checkbox>`.
+   * It does NOT set `required` on any child `<input>` and does NOT enforce
+   * native constraint validation. Per-control `required` must be set on the
+   * individual `<Checkbox>`.
    */
   required?: boolean;
   /**

package/src/components/chip/README.md

@@ -20,15 +20,15 @@ Use `Chip mode="display"` for issue labels and tags; use Badge for attached coun
 
 | Prop              | Type                                                                              | Required | Default | Description                                                                                                                |
 | ----------------- | --------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`           | `string`                                                                          | no       | —       |                                                                                                                            |
-| `density`         | `"toolbar"`                                                                       | no       | —       |                                                                                                                            |
-| `disabled`        | `boolean`                                                                         | no       | —       |                                                                                                                            |
-| `label`           | `string`                                                                          | yes      | —       |                                                                                                                            |
-| `mode`            | `"display"` \| `"toggle"` \| `"removable"`                                        | no       | —       |                                                                                                                            |
-| `pressed`         | `boolean`                                                                         | no       | —       |                                                                                                                            |
-| `removeAriaLabel` | `string`                                                                          | no       | —       |                                                                                                                            |
-| `size`            | `"sm"` \| `"md"`                                                                  | no       | —       |                                                                                                                            |
-| `variant`         | `"neutral"` \| `"success"` \| `"warning"` \| `"danger"` \| `"info"` \| `"accent"` | no       | —       |                                                                                                                            |
+| `class`           | `string`                                                                          | no       | —       | Additional class names merged onto the chip element.                                                                       |
+| `density`         | `"toolbar"`                                                                       | no       | —       | When set to `"toolbar"`, opts the chip into compact toolbar sizing to align with sibling toolbar controls.                 |
+| `disabled`        | `boolean`                                                                         | no       | —       | Toggle mode only. When true, disables the toggle button and prevents interaction.                                          |
+| `label`           | `string`                                                                          | yes      | —       | Visible text content of the chip.                                                                                          |
+| `mode`            | `"display"` \| `"toggle"` \| `"removable"`                                        | no       | —       | Rendering and interaction mode. Default `"display"`.                                                                       |
+| `pressed`         | `boolean`                                                                         | no       | —       | Toggle mode only. Whether the chip is currently in the pressed (selected) state. Reflected as `aria-pressed`.              |
+| `removeAriaLabel` | `string`                                                                          | no       | —       | Removable mode only. Accessible label for the remove button. Defaults to `Remove` followed by the chip's `label`.          |
+| `size`            | `"sm"` \| `"md"`                                                                  | no       | —       | Size of the chip. Default `"md"`.                                                                                          |
+| `variant`         | `"neutral"` \| `"success"` \| `"warning"` \| `"danger"` \| `"info"` \| `"accent"` | no       | —       | Color variant applied to the chip. Default `"neutral"`.                                                                    |
 | `leadingIcon`     | `(opaque)`                                                                        | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `onpressedchange` | `(opaque)`                                                                        | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `onremove`        | `(opaque)`                                                                        | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |

package/src/components/chip/chip.svelte

@@ -111,6 +111,16 @@
     }
     return result;
   });
+
+  // A bare `role="group"` needs an accessible name, so removable mode names the
+  // group with its `label` by default. But `aria-label` flows through `rest` for
+  // display/removable modes (see above), so a consumer-supplied `aria-label`
+  // must win. Resolve to the consumer's value when present, falling back to
+  // `label` — and apply it explicitly so it can't be clobbered by the spread.
+  const removableAriaLabel = $derived.by(() => {
+    const forwarded = rest['aria-label'];
+    return typeof forwarded === 'string' && forwarded.trim().length > 0 ? forwarded : label;
+  });
 </script>
 
 {#if mode === 'toggle'}
@@ -141,6 +151,8 @@
 {:else if mode === 'removable'}
   <span
     {...rest}
+    role="group"
+    aria-label={removableAriaLabel}
     data-cinder-mode="removable"
     data-cinder-variant={variant}
     data-cinder-size={size}

package/src/components/chip/chip.types.ts

@@ -11,12 +11,18 @@ export type ChipMode = 'display' | 'toggle' | 'removable';
  */
 export type ChipDensity = 'toolbar';
 export type ChipDisplayProps = Omit<HTMLAttributes<HTMLSpanElement>, 'class'> & {
+  /** Rendering and interaction mode. Default `"display"`. */
   mode?: 'display';
+  /** Visible text content of the chip. */
   label: string;
+  /** Color variant applied to the chip. Default `"neutral"`. */
   variant?: ChipVariant;
+  /** Size of the chip. Default `"md"`. */
   size?: ChipSize;
+  /** When set to `"toolbar"`, opts the chip into compact toolbar sizing to align with sibling toolbar controls. */
   density?: ChipDensity;
   leadingIcon?: Snippet;
+  /** Additional class names merged onto the chip element. */
   class?: string;
   // Cross-variant sentinel props: present as `never` so the union is destructurable in chip.svelte,
   // and consumers get a compile-time error if they pass toggle/removable-only props to display mode.
@@ -35,30 +41,46 @@ export type ChipToggleProps = Omit<
   HTMLButtonAttributes,
   'class' | 'disabled' | 'aria-pressed' | 'type'
 > & {
+  /** Rendering and interaction mode. Must be `"toggle"` for this variant. */
   mode: 'toggle';
+  /** Visible text content of the chip. */
   label: string;
+  /** Color variant applied to the chip. Default `"neutral"`. */
   variant?: ChipVariant;
+  /** Size of the chip. Default `"md"`. */
   size?: ChipSize;
+  /** When set to `"toolbar"`, opts the chip into compact toolbar sizing to align with sibling toolbar controls. */
   density?: ChipDensity;
   leadingIcon?: Snippet;
+  /** Additional class names merged onto the chip element. */
   class?: string;
+  /** Toggle mode only. Whether the chip is currently in the pressed (selected) state. Reflected as `aria-pressed`. */
   pressed: boolean;
   onpressedchange?: (pressed: boolean) => void;
+  /** Toggle mode only. When true, disables the toggle button and prevents interaction. */
   disabled?: boolean;
   // Cross-variant sentinel props
   onremove?: never;
   removeAriaLabel?: never;
 };
 export type ChipRemovableProps = Omit<HTMLAttributes<HTMLSpanElement>, 'class'> & {
+  /** Rendering and interaction mode. Must be `"removable"` for this variant. */
   mode: 'removable';
+  /** Visible text content of the chip and fallback accessible name for the remove button. */
   label: string;
+  /** Color variant applied to the chip. Default `"neutral"`. */
   variant?: ChipVariant;
+  /** Size of the chip. Default `"md"`. */
   size?: ChipSize;
+  /** When set to `"toolbar"`, opts the chip into compact toolbar sizing to align with sibling toolbar controls. */
   density?: ChipDensity;
   leadingIcon?: Snippet;
+  /** Additional class names merged onto the chip element. */
   class?: string;
   onremove?: () => void;
+  /** Removable mode only. When true, disables the remove button and prevents removal. */
   disabled?: boolean;
+  /** Removable mode only. Accessible label for the remove button. Defaults to `Remove` followed by the chip's `label`. */
   removeAriaLabel?: string;
   // Cross-variant sentinel props
   pressed?: never;

package/src/components/choice-grid/README.md

@@ -44,8 +44,8 @@ Responsive grid of large selectable choices with roving keyboard focus, selectio
 | `multiple`       | `boolean`                                  | no       | —       | When true the grid allows multiple simultaneous selections and reads/writes `values` instead of `value`. The ARIA role switches to `group` (items become `checkbox`); single-select uses `radiogroup` (items become `radio`). |
 | `value`          | `string` \| `null`                         | no       | —       | The currently selected value (single-select mode). Bindable. Pass `null` or omit to start with no selection.                                                                                                                  |
 | `values`         | `string`[]                                 | no       | —       | Currently selected values (multi-select mode). Bindable. Only used when `multiple` is `true` — set `multiple` explicitly to switch modes; binding `values` alone does NOT enable multi-select.                                |
-| `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.                                                                                                    |
-| `class`          | `(opaque)`                                 | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                       |
+| `children`       | `(opaque)`                                 | yes      | —       | `ChoiceGridItem` children. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                         |
+| `class`          | `(opaque)`                                 | no       | —       | Additional class names merged with `.cinder-choice-grid`. Not expressible in JSON Schema; see the component types for the signature.                                                                                          |
 
 <!-- generated:props:end -->
 

package/src/components/choice-grid-item/README.md

@@ -20,7 +20,7 @@ composed snippet. The flat `@lostgradient/cinder/choice-grid-item` subpath remai
 | `disabled` | `boolean`                                                  | no       | —       | When true this item cannot be selected or focused.                                                                                                 |
 | `state`    | `"neutral"` \| `"correct"` \| `"incorrect"` \| `"pending"` | no       | —       | Feedback state for assessment / quiz usage. Defaults to `'neutral'`. Layout dimensions do NOT change across states (stable cell sizing guarantee). |
 | `value`    | `string`                                                   | yes      | —       | The value this item represents. Used as the key for selection state, roving tabindex registration, and ARIA attributes.                            |
-| `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.                         |
+| `children` | `(opaque)`                                                 | yes      | —       | Item content — label text, an icon, or richer markup. Not expressible in JSON Schema; see the component types for the signature.                   |
 
 <!-- generated:props:end -->
 

package/src/components/choice-grid-item/choice-grid-item.svelte

@@ -127,7 +127,7 @@
   aria-disabled={isDisabled || undefined}
   tabindex={tabIndex}
   class={classNames('cinder-choice-grid-item', className)}
-  data-cinder-selected={isSelected || undefined}
+  data-cinder-selected={isSelected ? '' : undefined}
   data-cinder-disabled={isDisabled || undefined}
   data-cinder-state={feedbackState !== 'neutral' ? feedbackState : undefined}
   onclick={handleClick}

package/src/components/click-away-listener/README.md

@@ -24,12 +24,12 @@ Headless utility that calls a function when the user clicks or taps outside a su
 
 <!-- generated:props:start -->
 
-| Prop          | Type       | Required | Default | Description                                                                                                                |
-| ------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`       | `string`   | no       | —       | Additional class names merged with the root element.                                                                       |
-| `enabled`     | `boolean`  | no       | —       | When false the document listener is detached and `onClickAway` is never called. Defaults to `true`.                        |
-| `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. |
-| `onClickAway` | `(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 the root element.                                                                                                                                                                                                                  |
+| `enabled`     | `boolean`  | no       | —       | When false the document listener is detached and `onclickaway` is never called. Defaults to `true`.                                                                                                                                                                   |
+| `children`    | `(opaque)` | yes      | —       | Content rendered inside the root element. Required. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                        |
+| `onclickaway` | `(opaque)` | yes      | —       | Called with the triggering PointerEvent (or MouseEvent/TouchEvent on browsers that do not support the Pointer Events API) when the user presses a pointer device outside the root element. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/click-away-listener/click-away-listener.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic click-away listener",
       "description": "Calls a function when the user presses a pointer outside the wrapped subtree.",
-      "code": "<script lang=\"ts\">\n  import { Button, ClickAwayListener } from '@lostgradient/cinder';\n\n  let open = $state(false);\n</script>\n\n<Button onclick={() => (open = true)}>Open inline editor</Button>\n\n{#if open}\n  <ClickAwayListener\n    onClickAway={() => (open = false)}\n    style=\"\n      display: inline-flex;\n      flex-direction: column;\n      gap: var(--cinder-space-3);\n      margin-block-start: var(--cinder-space-4);\n      padding: var(--cinder-space-4);\n      border: 1px solid var(--cinder-border);\n      border-radius: var(--cinder-radius-lg);\n      background: var(--cinder-surface-raised);\n    \"\n  >\n    <p style=\"margin: 0;\">Click outside this box to dismiss it.</p>\n    <Button variant=\"secondary\" onclick={() => (open = false)}>Close</Button>\n  </ClickAwayListener>\n{/if}\n"
+      "code": "<script lang=\"ts\">\n  import { Button, ClickAwayListener } from '@lostgradient/cinder';\n\n  let open = $state(false);\n</script>\n\n<Button onclick={() => (open = true)}>Open inline editor</Button>\n\n{#if open}\n  <ClickAwayListener\n    onclickaway={() => (open = false)}\n    style=\"\n      display: inline-flex;\n      flex-direction: column;\n      gap: var(--cinder-space-3);\n      margin-block-start: var(--cinder-space-4);\n      padding: var(--cinder-space-4);\n      border: 1px solid var(--cinder-border);\n      border-radius: var(--cinder-radius-lg);\n      background: var(--cinder-surface-raised);\n    \"\n  >\n    <p style=\"margin: 0;\">Click outside this box to dismiss it.</p>\n    <Button variant=\"secondary\" onclick={() => (open = false)}>Close</Button>\n  </ClickAwayListener>\n{/if}\n"
     }
   ]
 }

package/src/components/click-away-listener/click-away-listener.svelte

@@ -19,7 +19,7 @@
   import type { ClickAwayListenerProps } from './click-away-listener.types.ts';
 
   let {
-    onClickAway,
+    onclickaway,
     enabled = true,
     class: className,
     children,
@@ -50,7 +50,7 @@
 
       const isInside = target instanceof Node && rootElement.contains(target);
       if (!isInside) {
-        onClickAway(event);
+        onclickaway(event);
       }
     }
 

package/src/components/click-away-listener/click-away-listener.types.ts

@@ -4,7 +4,7 @@ import type { HTMLAttributes } from 'svelte/elements';
 /**
  * Props for the ClickAwayListener component.
  *
- * A headless utility that fires `onClickAway` when the user presses a pointer
+ * A headless utility that fires `onclickaway` when the user presses a pointer
  * (mouse or touch) outside the component's root element. Useful for closing
  * inline-edit fields, custom dropdowns, or any overlay that should dismiss on
  * outside interaction without requiring a full Popover or Modal.
@@ -15,9 +15,9 @@ export type ClickAwayListenerProps = Omit<HTMLAttributes<HTMLDivElement>, 'class
    * browsers that do not support the Pointer Events API) when the user presses
    * a pointer device outside the root element.
    */
-  onClickAway: (event: PointerEvent | MouseEvent | TouchEvent) => void;
+  onclickaway: (event: PointerEvent | MouseEvent | TouchEvent) => void;
   /**
-   * When false the document listener is detached and `onClickAway` is never
+   * When false the document listener is detached and `onclickaway` is never
    * called. Defaults to `true`.
    */
   enabled?: boolean;

package/src/components/code-block/README.md

@@ -1,6 +1,8 @@
 # CodeBlock
 
-Renders syntax-highlighted source code with optional copy and line display controls.
+Renders preformatted source code with optional client-side syntax highlighting and copy controls.
+The first paint may be the escaped plain-code fallback; when highlighting resolves, the block keeps
+the same layout metrics.
 
 ## Usage
 
@@ -16,14 +18,14 @@ Renders syntax-highlighted source code with optional copy and line display contr
 
 <!-- generated:props:start -->
 
-| Prop          | Type       | Required | Default | Description                                                                                                                                                                                                                                                                                                                       |
-| ------------- | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`       | `string`   | no       | —       | Additional class names merged with `.cinder-code-block`.                                                                                                                                                                                                                                                                          |
-| `code`        | `string`   | yes      | —       | The code to render.                                                                                                                                                                                                                                                                                                               |
-| `copyable`    | `boolean`  | no       | —       | When true, render a copy button in the header.                                                                                                                                                                                                                                                                                    |
-| `highlight`   | `boolean`  | no       | —       | Whether to highlight. Defaults to `true` whenever `language` is set. `highlight={false}` is an absolute off switch: it disables ALL highlighting — including an explicit `highlighter` prop — and triggers no Shiki import. The block renders the escaped plain `<pre><code>` fallback while keeping the `language` header label. |
-| `language`    | `string`   | no       | —       | Optional language label rendered in the header; also selects the grammar for highlighting.                                                                                                                                                                                                                                        |
-| `highlighter` | `(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-code-block`.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `code`        | `string`   | yes      | —       | The code to render.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `copyable`    | `boolean`  | no       | —       | When true, render a copy button in the header.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `highlight`   | `boolean`  | no       | —       | Whether to highlight. Defaults to `true` whenever `language` is set. `highlight={false}` is an absolute off switch: it disables ALL highlighting — including an explicit `highlighter` prop — and triggers no Shiki import. The block renders the escaped plain `<pre><code>` fallback while keeping the `language` header label. When highlighting is enabled, client-side colorization may appear after first paint, but the block keeps stable layout metrics. |
+| `language`    | `string`   | no       | —       | Optional language label rendered in the header; also selects the grammar for highlighting.                                                                                                                                                                                                                                                                                                                                                                        |
+| `highlighter` | `(opaque)` | no       | —       | Custom highlighter for this instance, used in place of the bundled Shiki default. Receives `(code, language)` and returns an HTML string (sync or async). When provided, the default highlighter is never imported. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                    |
 
 <!-- generated:props:end -->