@lostgradient/cinder 0.4.0 → 0.5.0

package/src/components/chat/README.md

@@ -1,190 +0,0 @@
-# Chat
-
-Opinionated conversation surface bundling message list, composer, attachments, and scroll affordances for AI or support transcripts.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import {
-    Chat,
-    appendAssistantMessage,
-    appendUserMessage,
-    createConversation,
-  } from '@lostgradient/cinder/chat';
-
-  const conversation = appendAssistantMessage(
-    appendUserMessage(createConversation({ id: 'demo' }), 'Can you summarize this plan?'),
-    'The plan is ready to implement.',
-  );
-</script>
-
-<!-- Chat fills its parent; give the ancestor a definite height. -->
-<div style="height: 34rem;">
-  <Chat id="demo-chat" {conversation} />
-</div>
-```
-
-> [!IMPORTANT] Chat needs a definite-height ancestor
-> Chat's root element fills its parent (`height: 100%`). Place it inside an
-> ancestor with a resolved height—a fixed height, a flex or grid cell, or
-> `height: 100dvh`—or the message viewport collapses and Chat renders as a
-> small card instead of filling its space. See [Layout and sizing](#layout-and-sizing).
-
-## Layout and sizing
-
-Chat's root (`.chat-container`) is `height: 100%`. When no ancestor on the
-chain resolves to a definite height, that `100%` resolves against `auto` and
-Chat collapses to the intrinsic height of its empty state plus composer. There
-is no browser error: it just silently shrinks to a small card. Give Chat a
-sized ancestor with one of the three patterns below.
-
-**Fixed-height container.** The simplest option—wrap Chat in an element with
-an explicit height. This is what every example in this component uses.
-
-```svelte
-<div style="height: 34rem;">
-  <Chat id="support-chat" {conversation} />
-</div>
-```
-
-**Full-viewport flex column.** For an app shell where Chat should fill the
-remaining space, give the column a definite height and let the Chat cell
-`flex: 1` with `min-height: 0` (so it can shrink below its content and scroll
-internally rather than overflowing the page).
-
-```svelte
-<div class="chat-page">
-  <header>…</header>
-  <Chat id="app-chat" class="chat-page-surface" {conversation} />
-</div>
-
-<style>
-  .chat-page {
-    display: flex;
-    flex-direction: column;
-    height: 100dvh;
-  }
-
-  /* `:global` because the class lands on Chat's own root element. */
-  .chat-page :global(.chat-page-surface) {
-    flex: 1;
-    min-height: 0;
-  }
-</style>
-```
-
-**Grid cell.** The same shape works in a grid: give the container a resolved
-track (`grid-template-rows: auto 1fr`), place Chat in the `1fr` row, and keep
-`min-height: 0` on the Chat cell so it can shrink and scroll internally instead
-of overflowing the page.
-
-```svelte
-<div class="chat-grid">
-  <header>…</header>
-  <Chat id="grid-chat" class="chat-grid-surface" {conversation} />
-</div>
-
-<style>
-  .chat-grid {
-    display: grid;
-    grid-template-rows: auto 1fr;
-    height: 100dvh;
-  }
-
-  .chat-grid :global(.chat-grid-surface) {
-    min-height: 0;
-  }
-</style>
-```
-
-## Guidance
-
-### Use When
-
-- Shipping a full chat surface with composer, scroll-anchor, unread indicator, and attachments bundled as one heavyweight drop-in.
-- Building an AI assistant or support thread where conversation state is modeled as a transcript of role-tagged messages.
-
-### Avoid When
-
-- Rendering a one-off message list — compose lighter primitives directly instead of pulling the full suite.
-- The transcript is read-only and needs no composer — a simple list of message bubbles is a better fit.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop                               | Type                           | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ---------------------------------- | ------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `atBottom`                         | `boolean`                      | no       | —       | Whether the message viewport is scrolled to the bottom. Bindable; updated automatically as the user scrolls. Default `true`.                                                                                                                                                                                                                                                                                                           |
-| `bottomThreshold`                  | `number`                       | no       | —       | Distance in pixels from the bottom of the scroll viewport within which the chat is considered "at bottom" and will auto-scroll on new messages. Default `150`.                                                                                                                                                                                                                                                                         |
-| `class`                            | `string`                       | no       | —       | Additional class name merged onto the `.chat-container` root element.                                                                                                                                                                                                                                                                                                                                                                  |
-| `density`                          | `"comfortable"` \| `"compact"` | no       | —       | Controls spacing density of the message timeline. - `'comfortable'` (default): standard padding and gap. - `'compact'`: tighter spacing for data-dense contexts (e.g., embedded panels). Action buttons keep `min-height: var(--cinder-touch-target-min)` regardless.                                                                                                                                                                  |
-| `emptyPrompts`                     | `string`[]                     | no       | —       | List of suggested starter prompt strings shown as clickable buttons in the default empty state. Clicking a prompt submits it immediately as a user message. Has no effect when a custom `empty` snippet is provided.                                                                                                                                                                                                                   |
-| `id`                               | `string`                       | yes      | —       | Unique identifier used to scope accessibility attributes across the chat surface.                                                                                                                                                                                                                                                                                                                                                      |
-| `jumpThreshold`                    | `number`                       | no       | —       | Distance in pixels scrolled up from the bottom required before the jump-to-latest button appears. Must be greater than `bottomThreshold` to prevent button flickering. Default `200`.                                                                                                                                                                                                                                                  |
-| `loadEarlierLabel`                 | `string`                       | no       | —       | Label for the history pagination trigger. Default `"Load earlier messages"`.                                                                                                                                                                                                                                                                                                                                                           |
-| `loadingEarlierLabel`              | `string`                       | no       | —       | Status text while older messages are loading. Default `"Loading earlier messages"`.                                                                                                                                                                                                                                                                                                                                                    |
-| `moreHistoryAvailable`             | `boolean`                      | no       | —       | Whether the explicit "Load earlier messages" trigger is shown when a load handler exists. Default `true`.                                                                                                                                                                                                                                                                                                                              |
-| `newMessageIndicatorVisible`       | `boolean`                      | no       | —       | Whether the "new messages" indicator is currently visible above the composer. Bindable; cleared automatically when the viewport reaches the bottom. Default `false`.                                                                                                                                                                                                                                                                   |
-| `streaming`                        | `boolean`                      | no       | —       | Whether a streaming response is currently in progress. When `true`, the composer is disabled and a stop-generating button is shown. Default `false`.                                                                                                                                                                                                                                                                                   |
-| `streamingStatus`                  | `string`                       | no       | —       | Optional status label displayed in the typing indicator while `streaming` is `true` and no streaming content has arrived yet (e.g. `"Thinking…"` or `"Analyzing file…"`). When omitted, three animated dots are shown.                                                                                                                                                                                                                 |
-| `surfaceMode`                      | `"default"` \| `"transparent"` | no       | —       | Controls the background of the chat surface. Use `'transparent'` to inherit the host element's background when embedding chat inside a card or panel. Default `'default'`.                                                                                                                                                                                                                                                             |
-| `unreadCount`                      | `number`                       | no       | —       | Number of messages received while the viewport was scrolled away from the bottom. Bindable; resets to `0` when the user scrolls to the bottom. Default `0`.                                                                                                                                                                                                                                                                            |
-| `variant`                          | `"bubble"` \| `"flat"`         | no       | —       | Visual treatment for message bubbles. - `'bubble'` (default): colored backgrounds differentiate user from assistant. - `'flat'`: no bubble backgrounds; role is communicated via alignment and role label. Text-on-surface contrast meets WCAG AA via `--cinder-text` on `--cinder-surface-inset`.                                                                                                                                     |
-| `virtualizationEstimatedRowHeight` | `number`                       | no       | —       | Estimated row height in pixels for virtualized message rows. Default `88`.                                                                                                                                                                                                                                                                                                                                                             |
-| `virtualizationInitialHeight`      | `number`                       | no       | —       | Initial virtualized viewport height used before measurement. Default `640`.                                                                                                                                                                                                                                                                                                                                                            |
-| `virtualizationOverscan`           | `number`                       | no       | —       | Number of extra virtual rows rendered before and after the viewport. Default `3`.                                                                                                                                                                                                                                                                                                                                                      |
-| `virtualized`                      | `boolean`                      | no       | —       | Use the virtualized message render path for long transcripts. The complete `ConversationHistory` remains unchanged; only the DOM window is reduced. Default `false`.                                                                                                                                                                                                                                                                   |
-| `adapter`                          | `(opaque)`                     | no       | —       | Optional command/transport boundary around `conversation`. Its methods take precedence over the matching callback props (e.g. `sendMessage` over `onsubmit`); omit it and Chat behaves exactly as with plain callbacks. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                     |
-| `capabilities`                     | `(opaque)`                     | no       | —       | Feature-capability flags. Pass a `ChatCapabilities` object to enable or disable individual Chat features (attachments, search, copy, editing, retry) as a group rather than as five separate boolean props. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                 |
-| `conversation`                     | `(opaque)`                     | yes      | —       | The conversation transcript to render. Pass a {@link ConversationHistory} snapshot; consumers holding a stateful conversation object pass its current snapshot (e.g. `conversation.current`). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                               |
-| `empty`                            | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `header`                           | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `messageActions`                   | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `messagePart`                      | `(opaque)`                     | no       | —       | Per-message-part override. Replaces the rendering of an individual body part (markdown, tool call, tool result) while delegating the rest to the built-ins via the `renderDefault` snippet it receives. Image parts are excluded — they render through the grouped attachment grid, not this override. Not expressible in JSON Schema; see the component types for the signature.                                                      |
-| `messageReasoning`                 | `(opaque)`                     | no       | —       | Override or supplement the reasoning text for a message. Called per-message; return a non-empty string to show a reasoning block, `undefined` to fall back to `message.metadata['cinder:reasoning']`, empty string to suppress reasoning. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                   |
-| `messageStatus`                    | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `messageSteps`                     | `(opaque)`                     | no       | —       | Override or supplement the step list for a message. Called per-message; return an array to show step indicators, `undefined` to fall back to `message.metadata['cinder:steps']`. An empty array suppresses steps. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                           |
-| `messageSuggestions`               | `(opaque)`                     | no       | —       | Override or supplement the suggestion list for a message. Called per-message; return an array of label strings to show suggestion chips, `undefined` to fall back to `message.metadata['cinder:suggestions']`. An empty array suppresses suggestions. Not expressible in JSON Schema; see the component types for the signature.                                                                                                       |
-| `onadaptererror`                   | `(opaque)`                     | no       | —       | Called when an adapter command fails — either a rejected promise or a synchronous throw from the method. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                    |
-| `onapprove`                        | `(opaque)`                     | no       | —       | Called when the user approves an action-required tool call. The consumer is responsible for updating its transcript (e.g. calling conversationalist to unblock the pending tool) and triggering a new generation. When an adapter is also wired, Chat calls `adapter.approveToolCall(toolCallId)` first and then this callback. Not expressible in JSON Schema; see the component types for the signature.                             |
-| `onattachmentadd`                  | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `onattachmentfailure`              | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `onattachmentremove`               | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `ondeny`                           | `(opaque)`                     | no       | —       | Called when the user denies an action-required tool call. When an adapter is also wired, Chat calls `adapter.denyToolCall(toolCallId)` first and then this callback. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                        |
-| `onedit`                           | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `onexpandedchange`                 | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `onjumptolatest`                   | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `onloadhistory`                    | `(opaque)`                     | no       | —       | Called when the explicit history trigger is activated. The consumer prepends compatible messages into `conversation`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                       |
-| `onpushmessage`                    | `(opaque)`                     | no       | —       | Forwarded from the adapter's real-time `onMessage` push (consumer owns the transcript). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                     |
-| `onreadreceipt`                    | `(opaque)`                     | no       | —       | Forwarded from the adapter's real-time `onReadReceipt` push. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                |
-| `onretry`                          | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `onscrollstatechange`              | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `onstopgenerating`                 | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `onsubmit`                         | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `onsuggestionselect`               | `(opaque)`                     | no       | —       | Called when the user selects a suggestion chip. The label string is passed back. The consumer is responsible for submitting it as a new user message. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                       |
-| `ontypingchange`                   | `(opaque)`                     | no       | —       | Forwarded from the adapter's real-time `onTypingChange` push. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                               |
-| `onunreadindicatorchange`          | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-| `readReceipts`                     | `(opaque)`                     | no       | —       | Per-message read receipt state. Out-of-band UI state — NOT stored on `Message`. Pass a `Map` keyed by message id with a {@link ReadReceipt} value; the component renders a receipt badge on USER messages only. The adapter's `onReadReceipt` push handler populates the same state when an adapter is wired. Default `undefined` (no receipts shown). Not expressible in JSON Schema; see the component types for the signature.      |
-| `row`                              | `(opaque)`                     | no       | —       | Full-row override. Renders an entire message row; receives the message and a `renderDefault` snippet for the built-in row (inversion of control), so a consumer can wrap or fully replace specific rows. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                    |
-| `typingParticipants`               | `(opaque)`                     | no       | —       | Participants who are currently typing. Out-of-band UI state — NOT stored on `Message`. Pass an array of {@link TypingParticipant} objects; the component renders a per-participant typing indicator above the input. The adapter's `onTypingChange` push handler feeds the same indicator when an adapter is wired. Default `undefined` (indicator hidden). Not expressible in JSON Schema; see the component types for the signature. |
-| `viewportAttachment`               | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
-
-<!-- generated:props:end -->
-
-## 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/chat/container/use-chat-reasoning-state.svelte.ts

@@ -1,93 +0,0 @@
-/**
- * Runes helper for tracking which reasoning blocks are expanded.
- *
- * Owns the expanded-reasoning-ids Set and provides a toggle function. When a
- * virtualizer remeasure callback is registered (optional), toggling fires it
- * so the virtualizer can remeasure the row after the disclosure opens/closes.
- */
-
-/** Options for the reasoning state helper. */
-export type UseChatReasoningStateOptions = {
-  /**
-   * Optional callback to trigger a virtualizer remeasure for a specific message
-   * row after the reasoning disclosure state changes. If the virtualizer is not
-   * wired (e.g. in non-virtualized mode), pass `undefined` or omit — the toggle
-   * still works, no remeasure fires.
-   */
-  onRemeasureRow?: ((messageId: string) => void) | undefined;
-};
-
-/** Return type for the reasoning state helper. */
-export type UseChatReasoningStateReturn = {
-  /** Whether the reasoning block for the given message id is expanded. */
-  isExpanded: (messageId: string) => boolean;
-  /**
-   * Toggle the expanded state for the given message id. Also fires the
-   * remeasure callback when wired (virtualizer support).
-   */
-  toggle: (messageId: string) => void;
-  /**
-   * Reset all expanded state to empty. Called on conversation change so stale
-   * expanded reasoning blocks from the previous conversation are cleared.
-   */
-  reset: () => void;
-};
-
-/**
- * Creates reactive state for reasoning block expansion.
- *
- * The returned `isExpanded` and `toggle` are stable references — safe to pass
- * as props without triggering extra re-renders.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { useChatReasoningState } from './use-chat-reasoning-state.svelte';
- *
- *   const reasoningState = useChatReasoningState({});
- * </script>
- *
- * <!-- in template: -->
- * <ReasoningPart
- *   {part}
- *   expanded={reasoningState.isExpanded(message.id)}
- *   ontoggle={() => reasoningState.toggle(message.id)}
- * />
- * ```
- */
-export function useChatReasoningState(
-  options: UseChatReasoningStateOptions,
-): UseChatReasoningStateReturn {
-  const { onRemeasureRow } = options;
-
-  // Set of message ids whose reasoning blocks are currently expanded.
-  // Collapsed by default (reasoning starts closed).
-  let expandedIds = $state(new Set<string>());
-
-  function isExpanded(messageId: string): boolean {
-    return expandedIds.has(messageId);
-  }
-
-  function toggle(messageId: string): void {
-    const next = new Set(expandedIds);
-    if (next.has(messageId)) {
-      next.delete(messageId);
-    } else {
-      next.add(messageId);
-    }
-    expandedIds = next;
-    // Notify the virtualizer so it can remeasure the row after the DOM
-    // transitions to its new open/closed height. No-op when not wired.
-    onRemeasureRow?.(messageId);
-  }
-
-  function reset(): void {
-    expandedIds = new Set();
-  }
-
-  return {
-    isExpanded,
-    toggle,
-    reset,
-  };
-}

package/src/components/chat-conversation-header/README.md

@@ -1,40 +0,0 @@
-# ChatConversationHeader
-
-Header primitive for the active Chat conversation, composed as a sibling above Chat rather than inside it.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import ChatConversationHeader from '@lostgradient/cinder/chat-conversation-header';
-</script>
-
-<ChatConversationHeader conversation={activeConversation} />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop                | Type              | Required | Default | Description                                                                                                                                       |
-| ------------------- | ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`             | `string`          | no       | —       | Additional class name merged with `.cinder-chat-conversation-header`.                                                                             |
-| `headingLevel`      | `2` \| `3` \| `4` | no       | —       | Heading level for the conversation title. Default `2`.                                                                                            |
-| `showExportActions` | `boolean`         | no       | —       | Whether to render the built-in conversation export actions. Default `true`.                                                                       |
-| `actions`           | `(opaque)`        | no       | —       | Additional action controls rendered after the built-in export actions. Not expressible in JSON Schema; see the component types for the signature. |
-| `conversation`      | `(opaque)`        | yes      | —       | Active compatible conversation snapshot. 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/chat-conversation-list/README.md

@@ -1,45 +0,0 @@
-# ChatConversationList
-
-Conversation navigation list for switching among Chat transcripts without embedding the list inside Chat.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import ChatConversationList from '@lostgradient/cinder/chat-conversation-list';
-</script>
-
-<ChatConversationList
-  conversations={conversationSummaries}
-  activeConversationId={activeConversation.id}
-  onselectconversation={selectConversation}
-/>
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop                   | Type               | Required | Default | Description                                                                                                                                                  |
-| ---------------------- | ------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `activeConversationId` | `string` \| `null` | no       | —       | Currently active conversation id.                                                                                                                            |
-| `ariaLabel`            | `string`           | no       | —       | Accessible name for the conversations navigation landmark. Default `"Conversations"`.                                                                        |
-| `class`                | `string`           | no       | —       | Additional class name merged with `.cinder-chat-conversation-list`.                                                                                          |
-| `emptyText`            | `string`           | no       | —       | Empty state text when no conversations are present. Default `"No conversations"`.                                                                            |
-| `conversations`        | `(opaque)`         | yes      | —       | Conversation summaries to render. Sorts by latest message/update time descending. Not expressible in JSON Schema; see the component types for the signature. |
-| `onselectconversation` | `(opaque)`         | no       | —       | Called when a conversation 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 -->
-<!-- generated:subcomponents:end -->

package/src/components/checkbox/README.md

@@ -1,47 +0,0 @@
-# Checkbox
-
-Single boolean toggle for opt-in selections within forms or settings.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import Checkbox from '@lostgradient/cinder/checkbox';
-</script>
-
-<Checkbox />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop            | Type       | Required | Default | Description                                                                                                                                                                                                                                         |
-| --------------- | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `checked`       | `boolean`  | no       | —       | Bound checked state.                                                                                                                                                                                                                                |
-| `description`   | `string`   | no       | —       | Helper text displayed below the checkbox; wired via `aria-describedby`.                                                                                                                                                                             |
-| `disabled`      | `boolean`  | no       | —       | Disables the checkbox.                                                                                                                                                                                                                              |
-| `error`         | `string`   | no       | —       | Validation error message; sets `aria-invalid="true"` and `aria-describedby`.                                                                                                                                                                        |
-| `id`            | `string`   | no       | —       | Unique identifier for label association and ARIA wiring. Optional: when omitted, a stable id is generated via `$props.id()` (or inherited from a FormField context), matching Input/Autocomplete. Provide it when you need a known id to reference. |
-| `indeterminate` | `boolean`  | no       | —       | Bound indeterminate state. Mutually exclusive with `checked` visually.                                                                                                                                                                              |
-| `label`         | `string`   | no       | —       | Visible label rendered in a `<label>` element associated via `for`.                                                                                                                                                                                 |
-| `class`         | `(opaque)` | no       | —       | Extra class names merged with `.cinder-checkbox`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                        |
-| `onValueChange` | `(opaque)` | no       | —       | Intercept a proposed checked state before the bindable value is written. Return a replacement value to transform it. 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/checkbox-group/README.md

@@ -1,46 +0,0 @@
-# CheckboxGroup
-
-Wraps multiple checkboxes under a shared label and validation context.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import CheckboxGroup from '@lostgradient/cinder/checkbox-group';
-</script>
-
-<CheckboxGroup />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop          | Type                    | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------- | ----------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`       | `string`                | no       | —       | Additional class names merged with `.cinder-checkbox-group`.                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `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. |
-| `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)`              | yes      | —       | Checkbox children. 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/chip/README.md

@@ -1,52 +0,0 @@
-# Chip
-
-Compact token for issue labels, free-form tags, applied filters, selected entities, and removable or toggleable metadata.
-
-Use `Chip mode="display"` for issue labels and tags; use Badge for attached counts, statuses, and compact annotations.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import Chip from '@lostgradient/cinder/chip';
-</script>
-
-<Chip label="frontend" mode="display" variant="info" />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop              | Type                                                                              | Required | Default | Description                                                                                                                |
-| ----------------- | --------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `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. |
-
-<!-- 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/choice-grid/README.md

@@ -1,66 +0,0 @@
-# ChoiceGrid
-
-Responsive grid of large selectable choices with roving keyboard focus, selection state, and optional correct/incorrect/pending feedback for quiz and assessment surfaces.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import { ChoiceGrid } from '@lostgradient/cinder/choice-grid';
-
-  let selected = $state<string | null>(null);
-</script>
-
-<ChoiceGrid ariaLabel="Choose a difficulty" bind:value={selected}>
-  <ChoiceGrid.Item value="easy">Easy</ChoiceGrid.Item>
-  <ChoiceGrid.Item value="medium">Medium</ChoiceGrid.Item>
-  <ChoiceGrid.Item value="hard">Hard</ChoiceGrid.Item>
-</ChoiceGrid>
-```
-
-## Guidance
-
-### Use When
-
-- Presenting a small fixed set of large selectable answers where all options should stay visible (quiz or assessment surfaces).
-- Building a touch-friendly selector grid with stable cell dimensions that must not shift when feedback states are applied.
-
-### Avoid When
-
-- Selecting from a long dynamic list — use combobox or select instead.
-- Choosing one of two to five short values in a compact inline context — use segmented-control instead.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop             | Type                                       | Required | Default | Description                                                                                                                                                                                                                   |
-| ---------------- | ------------------------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ariaLabel`      | `string`                                   | no       | —       | Accessible label for the grid (required unless `ariaLabelledby` is set).                                                                                                                                                      |
-| `ariaLabelledby` | `string`                                   | no       | —       | Id of an external element that labels this grid.                                                                                                                                                                              |
-| `columns`        | `"responsive"` \| `1` \| `2` \| `3` \| `4` | no       | —       | Column layout. - `'responsive'` — `auto-fill` at a minimum cell width (default). - `1 \| 2 \| 3 \| 4` — fixed number of columns.                                                                                              |
-| `disabled`       | `boolean`                                  | no       | —       | Disables all items in the grid.                                                                                                                                                                                               |
-| `minColumnWidth` | `string`                                   | no       | —       | Minimum cell width for `columns="responsive"`. Accepts any CSS `<length>` (e.g. `"12rem"`, `"200px"`). Default: `"10rem"`.                                                                                                    |
-| `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)`                                 | 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 -->
-
-## 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 -->