@lostgradient/cinder 0.4.1 → 0.5.0

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

@@ -1,41 +0,0 @@
-# ChoiceGridItem
-
-Selectable answer tile used inside a ChoiceGrid; carries selected, disabled, correct, incorrect, and pending states without shifting cell dimensions.
-
-## Usage
-
-`ChoiceGridItem` is a compose-only leaf of [`ChoiceGrid`](../choice-grid/README.md).
-The idiomatic API is `ChoiceGrid.Item`, reached through the parent
-namespace — see the [ChoiceGrid README](../choice-grid/README.md#usage) for the
-composed snippet. The flat `@lostgradient/cinder/choice-grid-item` subpath remains exported for
-à-la-carte builds that import the leaf directly.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop       | Type                                                       | Required | Default | Description                                                                                                                                        |
-| ---------- | ---------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`                                                   | no       | —       | Additional class names merged with `.cinder-choice-grid-item`.                                                                                     |
-| `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)`                                                 | 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 -->
-
-## 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/click-away-listener/README.md

@@ -1,50 +0,0 @@
-# ClickAwayListener
-
-Headless utility that calls a function when the user clicks or taps outside a subtree.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import { ClickAwayListener } from '@lostgradient/cinder/click-away-listener';
-</script>
-```
-
-## Guidance
-
-### Use When
-
-- Building a custom inline-edit field, custom dropdown, or any overlay that should close on outside interaction.
-
-### Avoid When
-
-- Using Popover, Dropdown, or Modal — those handle click-away internally.
-
-## Props
-
-<!-- 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)` | 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 -->
-
-## 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/code-block/README.md

@@ -1,46 +0,0 @@
-# CodeBlock
-
-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
-
-```svelte
-<script lang="ts">
-  import CodeBlock from '@lostgradient/cinder/code-block';
-</script>
-
-<CodeBlock />
-```
-
-## Props
-
-<!-- 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. 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 -->
-
-## 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/collapsible/README.md

@@ -1,75 +0,0 @@
-# Collapsible
-
-Single-panel show/hide disclosure — the single-item counterpart to Accordion. A labeled trigger toggles one region, animating its height open and closed with Svelte's native `slide` transition.
-
-## Usage
-
-Uncontrolled — the component owns its state:
-
-```svelte
-<script lang="ts">
-  import Collapsible from '@lostgradient/cinder/collapsible';
-</script>
-
-<Collapsible trigger="Shipping details">
-  <p>Orders ship within two business days.</p>
-</Collapsible>
-```
-
-Controlled — the parent owns the state with `bind:open`:
-
-```svelte
-<script lang="ts">
-  import Collapsible from '@lostgradient/cinder/collapsible';
-
-  let open = $state(false);
-</script>
-
-<Collapsible bind:open trigger="Controlled panel">
-  <p>Open state is shared with the parent.</p>
-</Collapsible>
-```
-
-### State model
-
-Without `bind:open`, `open` is the initial local value and the component manages subsequent toggles; pass `open={true}` to render initially open. With `bind:open`, the parent owns the state. `ontoggle` fires on every toggle with the next boolean, so one-way observers stay in sync.
-
-The `trigger` prop is either a string or a snippet receiving `{ open, disabled }`, letting the label react to state (for example, swapping "Show" and "Hide").
-
-## Accessibility
-
-- The trigger is a native `<button type="button">`, so Enter and Space activation and tab order come from the browser. `disabled` uses the real attribute, removing it from the tab order.
-- The trigger carries `aria-expanded`; the panel is a `role="region"` labeled by the trigger via `aria-labelledby`.
-- The panel is removed from the DOM when closed (standard disclosure behavior). `aria-controls` is emitted only while the panel exists, so it never references a missing element. Each open panel registers as a named `region` landmark — on a page with many open Collapsibles, weigh that against landmark-navigation noise.
-- Height animation collapses to zero duration under `prefers-reduced-motion: reduce`, and the chevron rotation transition is disabled in CSS.
-
-For multiple coordinated sections where opening one may close others, use [`Accordion`](../accordion/README.md) instead. See [`collapsible.a11y.md`](./collapsible.a11y.md) for a detailed comparison of when to use each pattern.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop       | Type       | Required | Default | Description                                                                                                                                                      |
-| ---------- | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`   | no       | —       | Additional classes merged onto the root element.                                                                                                                 |
-| `disabled` | `boolean`  | no       | `false` | When true, the trigger cannot be toggled.                                                                                                                        |
-| `idBase`   | `string`   | no       | —       | Base used to derive the trigger and panel ARIA ids. Auto-generated when omitted.                                                                                 |
-| `open`     | `boolean`  | no       | `false` | Bindable open state. Without binding, the initial value the component then manages.                                                                              |
-| `trigger`  | `string`   | yes      | —       | Trigger label text. (The snippet form is template-only; see the type above.)                                                                                     |
-| `children` | `(opaque)` | yes      | —       | Panel content shown when open. Not expressible in JSON Schema; see the component types for the signature.                                                        |
-| `ontoggle` | `(opaque)` | no       | —       | Fired on every successful toggle with the next open state. Not called while disabled. 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 -->
-<!-- generated:subcomponents:end -->

package/src/components/color-field/README.md

@@ -1,98 +0,0 @@
-# ColorField
-
-A text input that validates and normalizes hex, `rgb()`, and `hsl()` color strings into a canonical hex value emitted on blur. Compose it with `FormField` for label and external-error display, and pair it with `ColorPicker` when users need both visual selection and exact entry.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import ColorField from '@lostgradient/cinder/color-field';
-  import FormField from '@lostgradient/cinder/form-field';
-
-  let color = $state('#3366ff');
-</script>
-
-<FormField id="accent" label="Accent color">
-  <ColorField id="accent" value={color} onchange={(next) => (color = next)} />
-</FormField>
-```
-
-`value` is one-way: the parent sets it, the component reads it, and commits flow back through `onchange`. `bind:value` is intentionally not supported — wire up the callback explicitly so the data flow remains obvious.
-
-## Behavior
-
-- **Validation happens on blur**, not on every keystroke, so users can type intermediate values like `#ab` without seeing the error flicker.
-- The emit value is always lowercase hex. Output is `#rrggbb` unless `alpha={true}` and the parsed value has partial alpha — then it's `#rrggbbaa`. Opaque inputs are never padded to `ff`.
-- When `alpha={false}` (default), `#RRGGBBAA`, `rgba()`, and `hsla()` are accepted as input, but alpha is stripped on emit.
-- The trailing color swatch reads `committedHex` only. It never reflects unparsed text, so a malformed string never paints arbitrary content into the DOM.
-- Pressing **Enter** commits the value. With `enterBehavior='commit-then-submit'` (default), the field then calls `form.requestSubmit()` on the associated form. With `enterBehavior='commit-only'`, submission is suppressed.
-
-## Controlled vs. uncontrolled
-
-- **Controlled**: pass `value` and listen to `onchange`. The component never mutates `value`; it observes external changes via an effect. An externally-supplied invalid string preserves the visible text and raises an error rather than silently clearing.
-- **Uncontrolled**: pass `defaultValue` instead. Subsequent state is owned by the component, and consumers observe commits through `onchange`.
-
-Switching between controlled and uncontrolled at runtime is unsupported. The component captures `isControlled = value !== undefined` once at mount. In dev mode a runtime divergence logs a one-time `console.warn`.
-
-## Form participation
-
-The component renders a single sibling `<input type="hidden">` that serves two purposes. When `name` is set, that input carries the `name` attribute and mirrors the current committed hex so the value participates in native form submission. When `name` is not set, the same input still renders (without a `name`) and acts purely as the anchor used to attach a `reset` listener to the surrounding form. Either way, uncontrolled fields revert to `defaultValue` on form reset (no `onchange` is fired; reset is observable through native form events). Controlled fields do nothing on reset internally; the parent's reset handler updates `value` and the effect reconciles.
-
-Parse errors propagate to the visible `<input>` via `setCustomValidity`, so invalid text participates in HTML constraint validation whether the user pressed Enter or clicked a submit button.
-
-Moving the component across forms at runtime is not supported in v1.
-
-## Limitations
-
-- Modern `rgb(r g b / a)` and `hsl(h s l / a)` slash syntax is rejected by the parser. Only legacy comma-separated forms parse.
-- `rgb()` percent components are rounded to the nearest 0–255 byte.
-- `commit-then-submit` selects the first non-disabled `[type="submit"]` (or unmarked `<button>`) in document order, matching the common case but not every native browser nuance. Forms needing full fidelity should use `enterBehavior='commit-only'` and orchestrate `requestSubmit(submitter)` themselves.
-- The component contributes a form value only when `name` is set — just like a native `<input>` without `name`. Pressing Enter on a field without a `name` still commits and submits, but no color appears in `FormData`.
-- `oninput` is not exposed. The component owns the blur-time commit pipeline; intermediate keystrokes are intentionally not surfaced as a value callback.
-
-## Errors and accessibility
-
-- Parse errors are owned by `ColorField` and rendered by the inner `Input`. The native `<input>` carries `aria-invalid="true"` and an `aria-describedby` that references the inline error message.
-- When wrapped in a `FormField` with its own `error="..."`, both error texts render and both ids appear in `aria-describedby` without collision — the `Input` allocates a distinct id when its own error would collide with the context's error id.
-- The trailing swatch is decorative: it is `aria-hidden="true"`.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop              | Type                                      | Required | Default | Description                                                                                                                                                                                                                                                                                                                                 |
-| ----------------- | ----------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `alpha`           | `boolean`                                 | no       | —       | Accept and emit alpha when the parsed value has partial alpha. When `false` (default), `#RRGGBBAA` and `rgba()`/`hsla()` inputs are parsed but alpha is stripped on emit.                                                                                                                                                                   |
-| `aria-label`      | `string`                                  | no       | —       | Accessible label applied directly to the inner `<input>` when no `FormField` wraps it.                                                                                                                                                                                                                                                      |
-| `aria-labelledby` | `string`                                  | no       | —       | Id of an external element that labels the inner `<input>`.                                                                                                                                                                                                                                                                                  |
-| `class`           | `string`                                  | no       | —       | Additional classes merged onto the **outer wrapper** root (`.cinder-color-field`).                                                                                                                                                                                                                                                          |
-| `defaultValue`    | `string`                                  | no       | —       | Initial value when uncontrolled. Accepts any allowed `formats` input.                                                                                                                                                                                                                                                                       |
-| `disabled`        | `boolean`                                 | no       | —       | Disable the input.                                                                                                                                                                                                                                                                                                                          |
-| `enterBehavior`   | `"commit-then-submit"` \| `"commit-only"` | no       | —       | Commit-on-Enter behavior. Default `'commit-then-submit'`: - `'commit-then-submit'`: Enter commits the value, then lets the form's native submission proceed via `requestSubmit`. - `'commit-only'`: Enter commits and `preventDefault()`s, suppressing form submission (useful in dialogs / multi-field flows where Enter must not submit). |
-| `errorMessage`    | `string`                                  | no       | —       | Override the default parse-failure error message.                                                                                                                                                                                                                                                                                           |
-| `formats`         | (`"hex"` \| `"rgb"` \| `"hsl"`)[]         | no       | —       | Accepted _input_ formats. Defaults to `['hex', 'rgb', 'hsl']`. Output is always hex.                                                                                                                                                                                                                                                        |
-| `id`              | `string`                                  | yes      | —       | Inner `<input>` id. Required (mirrors Input).                                                                                                                                                                                                                                                                                               |
-| `name`            | `string`                                  | no       | —       | Form field name. When set, the hidden mirror input contributes the current committed hex value to native form submission.                                                                                                                                                                                                                   |
-| `placeholder`     | `string`                                  | no       | —       | Placeholder text for the inner `<input>`.                                                                                                                                                                                                                                                                                                   |
-| `readonly`        | `boolean`                                 | no       | —       | Render the inner `<input>` as read-only.                                                                                                                                                                                                                                                                                                    |
-| `required`        | `boolean`                                 | no       | —       | Mark the input as required for form submission and a11y.                                                                                                                                                                                                                                                                                    |
-| `value`           | `string`                                  | no       | —       | Controlled value as a hex string. One-way: parent sets, child reads. Not bindable — use `onchange` to observe commits. Accepts any color string the configured `formats` allow when set externally.                                                                                                                                         |
-| `onchange`        | `(opaque)`                                | no       | —       | Fires on successful blur-time commit when the canonical hex actually changes. Value callback by repo convention — not forwarded to the inner native `<input>`. 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/color-picker/README.md

@@ -1,48 +0,0 @@
-# ColorPicker
-
-Full-featured input for selecting a color via hue, saturation, lightness, and hex entry.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import ColorPicker from '@lostgradient/cinder/color-picker';
-</script>
-
-<ColorPicker />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop           | Type       | Required | Default | Description                                                                                                                                                                                                                |
-| -------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `alpha`        | `boolean`  | no       | —       | Enable the alpha slider and emit `#rrggbbaa`. Default `false`.                                                                                                                                                             |
-| `class`        | `string`   | no       | —       | Additional classes merged onto the root element.                                                                                                                                                                           |
-| `defaultValue` | `string`   | no       | —       | Initial color when `value` is not bound. Same input formats as `value`.                                                                                                                                                    |
-| `disabled`     | `boolean`  | no       | —       | Disable interaction across the picker.                                                                                                                                                                                     |
-| `label`        | `string`   | no       | —       | Accessible label for the picker. Default `'Color picker'`.                                                                                                                                                                 |
-| `name`         | `string`   | no       | —       | Form field name. When set, a hidden input mirrors the current value for form submission.                                                                                                                                   |
-| `swatches`     | `string`[] | no       | —       | Optional palette of preset colors rendered below the picker.                                                                                                                                                               |
-| `value`        | `string`   | no       | —       | Bindable value. Reading the value yields a hex string (`#rrggbb`, or `#rrggbbaa` when `alpha` is true). Setting the value accepts hex, `rgb()`, `rgba()`, `hsl()`, or `hsla()` input; invalid input is normalized to `''`. |
-| `onchange`     | `(opaque)` | no       | —       | Fired on commit (pointer up, swatch click, slider key). Not expressible in JSON Schema; see the component types for the signature.                                                                                         |
-| `oninput`      | `(opaque)` | no       | —       | Fired on every intermediate update (drag, slider key, swatch click). 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/color-swatch-picker/README.md

@@ -1,49 +0,0 @@
-# ColorSwatchPicker
-
-Presents a fixed palette of color swatches for constrained color selection.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import ColorSwatchPicker from '@lostgradient/cinder/color-swatch-picker';
-</script>
-
-<ColorSwatchPicker />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop           | Type                                           | Required | Default | Description                                                                                                                                                                                                                        |
-| -------------- | ---------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`        | `string`                                       | no       | —       | Additional classes merged into the listbox `<ul>`.                                                                                                                                                                                 |
-| `defaultValue` | `string`                                       | no       | —       | Initial selected color for uncontrolled use. Ignored when `value` is set.                                                                                                                                                          |
-| `disabled`     | `boolean`                                      | no       | —       | Disables the entire listbox. Keyboard activation and clicks are ignored.                                                                                                                                                           |
-| `label`        | `string`                                       | yes      | —       | Accessible name for the listbox. Required — `role="listbox"` needs a label so screen readers can announce the control's purpose.                                                                                                   |
-| `layout`       | `"grid"` \| `"stack"`                          | no       | —       | Layout direction. Default `'grid'`. Note: grid layout uses one-dimensional DOM-order navigation for both ArrowLeft/Right and ArrowUp/Down. True column-aware navigation is not implemented in v1 — see a11y memo.                  |
-| `shape`        | `"circle"` \| `"square"`                       | no       | —       | Visual shape of each swatch. Default `'circle'`.                                                                                                                                                                                   |
-| `size`         | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | no       | —       | Swatch dimension token. Default `'md'`.                                                                                                                                                                                            |
-| `value`        | `string`                                       | no       | —       | Controlled selected color. When provided, the parent owns the state.                                                                                                                                                               |
-| `colors`       | `(opaque)`                                     | yes      | —       | Palette to render. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                      |
-| `indicator`    | `(opaque)`                                     | no       | —       | Snippet that replaces the default check-icon indicator on the selected swatch. Receives the active swatch and the computed contrast color for the icon. Not expressible in JSON Schema; see the component types for the signature. |
-| `onchange`     | `(opaque)`                                     | no       | —       | Fired when the selected swatch changes. 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/combobox/README.md

@@ -1,53 +0,0 @@
-# Combobox
-
-Filterable dropdown that combines a text input with a selectable option list.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import Combobox from '@lostgradient/cinder/combobox';
-</script>
-
-<Combobox />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop                | Type       | Required | Default | Description                                                                                                                                                                                                                            |
-| ------------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `aria-describedby`  | `string`   | no       | —       | External element id(s) to compose into `aria-describedby`. Composed after the component-generated description and error ids, matching the field-control contract in Select. Useful for tooltip ids, counter ids, or any external hint. |
-| `class`             | `string`   | no       | —       | Additional class names merged with `.cinder-combobox`.                                                                                                                                                                                 |
-| `description`       | `string`   | no       | —       | Helper text displayed below the input; wired via aria-describedby.                                                                                                                                                                     |
-| `disabled`          | `boolean`  | no       | —       | Disables the combobox. Inherited from a wrapping FormField when unset.                                                                                                                                                                 |
-| `error`             | `string`   | no       | —       | Validation error message; sets aria-invalid="true".                                                                                                                                                                                    |
-| `id`                | `string`   | yes      | —       | Unique identifier — required for label association and ARIA wiring.                                                                                                                                                                    |
-| `inputValue`        | `string`   | no       | —       | Free-text input value (the text the user has typed). Bindable.                                                                                                                                                                         |
-| `label`             | `string`   | no       | —       | Visible label rendered in a `<label>` associated via `for`.                                                                                                                                                                            |
-| `maxVisibleOptions` | `number`   | no       | —       | Hard cap on visible filtered options. Default 200.                                                                                                                                                                                     |
-| `name`              | `string`   | no       | —       | Native form field name. Renders a hidden input carrying the selected value.                                                                                                                                                            |
-| `placeholder`       | `string`   | no       | —       | Placeholder when no value is selected.                                                                                                                                                                                                 |
-| `required`          | `boolean`  | no       | —       | Marks the field required: renders the required marker on the label and sets `aria-required` on the input. Inherited from a wrapping FormField when unset.                                                                              |
-| `filter`            | `(opaque)` | no       | —       | Custom synchronous filter. Receives an option and the current input value; returns true to keep. Defaults to case-insensitive substring match on label. Not expressible in JSON Schema; see the component types for the signature.     |
-| `options`           | `(opaque)` | yes      | —       | Full set of options to filter. The sole inference source for T. Not expressible in JSON Schema; see the component types for the signature.                                                                                             |
-| `value`             | `(opaque)` | no       | —       | Currently selected value. Bindable. `''` when nothing is selected. 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/command-item/README.md

@@ -1,49 +0,0 @@
-# CommandItem
-
-Individual selectable row within a command palette or dropdown command list.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import CommandItem from '@lostgradient/cinder/command-item';
-</script>
-
-<CommandItem />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop               | Type                   | Required | Default | Description                                                                                                                               |
-| ------------------ | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `accessibleLabel`  | `string`               | no       | —       | Accessible name for the option when the rendered row contains secondary text or rich content.                                             |
-| `class`            | `string`               | no       | —       | Class merged with `.cinder-command-item`.                                                                                                 |
-| `description`      | `string`               | no       | —       | Optional secondary text shown below the main label.                                                                                       |
-| `disabled`         | `boolean`              | no       | —       | When true, the item is skipped by arrow keys and cannot be activated.                                                                     |
-| `keyboardShortcut` | `string`               | no       | —       | Keyboard shortcut exposed through `aria-keyshortcuts`, e.g. `Meta+N`.                                                                     |
-| `selectionMode`    | `"item"` \| `"parent"` | no       | —       | The item owns activation. This is the default CommandPalette mode.                                                                        |
-| `value`            | `string`               | yes      | —       | Submitted value; surfaced through the registration record.                                                                                |
-| `children`         | `(opaque)`             | yes      | —       | Main label content. Not expressible in JSON Schema; see the component types for the signature.                                            |
-| `leading`          | `(opaque)`             | no       | —       | Leading content (icon, avatar). Rendered with aria-hidden. Not expressible in JSON Schema; see the component types for the signature.     |
-| `onselect`         | `(opaque)`             | no       | —       | Invoked when the item is activated inside CommandPalette. Not expressible in JSON Schema; see the component types for the signature.      |
-| `trailing`         | `(opaque)`             | no       | —       | Trailing content (kbd hint, badge). Rendered with aria-hidden. 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/command-menu/README.md

@@ -1,61 +0,0 @@
-# CommandMenu
-
-Inline caret-anchored slash-command list for textareas and single-line text inputs.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import { CommandMenu } from '@lostgradient/cinder/command-menu';
-</script>
-```
-
-## Guidance
-
-### Use When
-
-- Showing a contextual command list at the caret while a user types in a textarea or input.
-- Building slash-command insertion flows where the host owns text replacement.
-
-### Avoid When
-
-- Exposing a global app launcher — use command-palette instead.
-- Selecting from a static form option list — use combobox instead.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop            | Type                                                                                                                 | Required | Default | Description                                                                                                                               |
-| --------------- | -------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `caretIndex`    | `number`                                                                                                             | yes      | —       | Caret offset within the anchor value.                                                                                                     |
-| `class`         | `string`                                                                                                             | no       | —       | Class merged with `.cinder-command-menu`.                                                                                                 |
-| `label`         | `string`                                                                                                             | no       | —       | Accessible listbox label. Default `'Commands'`.                                                                                           |
-| `offset`        | `number`                                                                                                             | no       | —       | Distance in px between the caret and menu. Default `6`.                                                                                   |
-| `open`          | `boolean`                                                                                                            | no       | —       | Open state. Bindable. Default `false`.                                                                                                    |
-| `placement`     | `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"top-start"` \| `"top-end"` \| `"bottom-start"` \| `"bottom-end"` | no       | —       | Caret-relative placement. Default `'bottom-start'`.                                                                                       |
-| `query`         | `string`                                                                                                             | no       | —       | Query text after the trigger character. Bindable. Default `''`.                                                                           |
-| `anchor`        | `(opaque)`                                                                                                           | yes      | —       | Text field used as the caret-position anchor. Not expressible in JSON Schema; see the component types for the signature.                  |
-| `empty`         | `(opaque)`                                                                                                           | no       | —       | Optional empty state rendered after item registration settles. Not expressible in JSON Schema; see the component types for the signature. |
-| `items`         | `(opaque)`                                                                                                           | yes      | —       | Render command items for the current query. Not expressible in JSON Schema; see the component types for the signature.                    |
-| `ondismiss`     | `(opaque)`                                                                                                           | no       | —       | Invoked when Escape or outside pointerdown dismisses the menu. Not expressible in JSON Schema; see the component types for the signature. |
-| `onselect`      | `(opaque)`                                                                                                           | no       | —       | Invoked when an enabled command is activated. Not expressible in JSON Schema; see the component types for the signature.                  |
-| `onstatechange` | `(opaque)`                                                                                                           | no       | —       | One-way state output for host-owned field ARIA. 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 -->