@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/chat-conversation-header/chat-conversation-header.css

@@ -0,0 +1,51 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+/* ChatConversationHeader renders ConversationExportActions, which composes Dropdown
+ * leaves. Keep the header style subpath self-sufficient for a-la-carte imports. */
+@import '../dropdown/dropdown.css';
+
+@layer cinder.components {
+  .cinder-chat-conversation-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--cinder-space-4);
+    min-width: 0;
+    padding: var(--cinder-space-3) var(--cinder-space-4);
+    border-bottom: 1px solid var(--cinder-border);
+  }
+
+  .cinder-chat-conversation-header__main {
+    min-width: 0;
+  }
+
+  .cinder-chat-conversation-header__title {
+    margin: 0;
+    overflow: hidden;
+    color: var(--cinder-text);
+    font-size: var(--cinder-text-lg);
+    font-weight: var(--cinder-font-semibold);
+    line-height: var(--cinder-leading-tight);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .cinder-chat-conversation-header__meta {
+    margin: var(--cinder-space-0-5) 0 0;
+    overflow: hidden;
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-sm);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .cinder-chat-conversation-header__status {
+    text-transform: capitalize;
+  }
+
+  .cinder-chat-conversation-header__actions {
+    display: inline-flex;
+    flex-shrink: 0;
+    align-items: center;
+    gap: var(--cinder-space-2);
+  }
+}

package/src/components/chat-conversation-header/chat-conversation-header.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "chat-conversation-header",
+  "import": "@lostgradient/cinder/chat-conversation-header",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic conversation header",
+      "description": "A header derived from the active compatible conversation snapshot.",
+      "code": "<script lang=\"ts\">\n  import { ChatConversationHeader } from '@lostgradient/cinder';\n  import { appendAssistantMessage, createConversation } from '@lostgradient/cinder/chat';\n\n  let conversation = createConversation({\n    id: 'launch-support',\n    title: 'Launch support',\n  });\n\n  conversation = {\n    ...appendAssistantMessage(conversation, 'I drafted the launch checklist.'),\n    metadata: { _participantNames: ['Ada', 'Grace', 'Lin'] },\n  };\n</script>\n\n<ChatConversationHeader {conversation} />\n"
+    }
+  ]
+}

package/src/components/chat-conversation-header/chat-conversation-header.svelte

@@ -0,0 +1,83 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category domain
+   * @status domain-suite
+   * @purpose Header primitive for the active Chat conversation, composed as a sibling above Chat rather than inside it.
+   * @tag chat
+   * @tag conversation
+   * @tag header
+   * @useWhen Showing the active conversation title, participants, status, and export controls above a Chat transcript.
+   * @useWhen Building a multi-conversation chat layout where the list, header, and Chat surface are composed as siblings.
+   * @avoidWhen Rendering the conversation switcher — use chat-conversation-list.
+   * @avoidWhen Rendering the transcript body and composer — use chat.
+   * @related chat, chat-conversation-list
+   */
+  export type {
+    ChatConversationHeaderHeadingLevel,
+    ChatConversationHeaderProps,
+  } from './chat-conversation-header.types.ts';
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../utilities/class-names.ts';
+  import ConversationExportActions from '../chat/export/conversation-export-actions.svelte';
+  import { deriveConversationSummary } from '../chat-conversation-list/conversation-summary.ts';
+  import type {
+    ChatConversationHeaderHeadingLevel,
+    ChatConversationHeaderProps,
+  } from './chat-conversation-header.types.ts';
+
+  let {
+    conversation,
+    headingLevel = 2,
+    showExportActions = true,
+    class: className,
+    actions,
+    ...rest
+  }: ChatConversationHeaderProps = $props();
+
+  const summary = $derived(deriveConversationSummary(conversation));
+  const headingTag = $derived(
+    `h${headingLevel}` satisfies `h${ChatConversationHeaderHeadingLevel}`,
+  );
+  const participantLabel = $derived(
+    summary.participantNames.length === 0
+      ? undefined
+      : summary.participantNames.length <= 2
+        ? summary.participantNames.join(', ')
+        : `${summary.participantNames.slice(0, 2).join(', ')} +${summary.participantNames.length - 2}`,
+  );
+  const fullParticipantLabel = $derived(summary.participantNames.join(', '));
+</script>
+
+<header class={classNames('cinder-chat-conversation-header', className)} {...rest}>
+  <div class="cinder-chat-conversation-header__main">
+    <svelte:element this={headingTag} class="cinder-chat-conversation-header__title">
+      {summary.title}
+    </svelte:element>
+    <p class="cinder-chat-conversation-header__meta">
+      {summary.messageCount}
+      {summary.messageCount === 1 ? 'message' : 'messages'}
+      <span aria-hidden="true"> · </span>
+      <span class="cinder-chat-conversation-header__status">{summary.status}</span>
+      {#if participantLabel}
+        <span aria-hidden="true"> · </span>
+        <span title={fullParticipantLabel} aria-label={fullParticipantLabel}>
+          {participantLabel}
+        </span>
+      {/if}
+    </p>
+  </div>
+
+  {#if showExportActions || actions}
+    <div class="cinder-chat-conversation-header__actions">
+      {#if showExportActions}
+        <ConversationExportActions id={`${conversation.id}-export-actions`} {conversation} />
+      {/if}
+      {#if actions}
+        {@render actions(summary)}
+      {/if}
+    </div>
+  {/if}
+</header>

package/src/components/chat-conversation-header/chat-conversation-header.types.ts

@@ -0,0 +1,20 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ConversationSummary } from '../chat-conversation-list/conversation-summary.ts';
+import type { ConversationHistory } from '../chat/conversation-model.ts';
+
+export type ChatConversationHeaderHeadingLevel = 2 | 3 | 4;
+
+/** Props for the ChatConversationHeader component. */
+export type ChatConversationHeaderProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Active compatible conversation snapshot. */
+  conversation: ConversationHistory;
+  /** Heading level for the conversation title. Default `2`. */
+  headingLevel?: ChatConversationHeaderHeadingLevel;
+  /** Whether to render the built-in conversation export actions. Default `true`. */
+  showExportActions?: boolean;
+  /** Additional class name merged with `.cinder-chat-conversation-header`. */
+  class?: string;
+  /** Additional action controls rendered after the built-in export actions. */
+  actions?: Snippet<[ConversationSummary]>;
+};

package/src/components/chat-conversation-header/index.ts

@@ -0,0 +1,9 @@
+import './chat-conversation-header.css';
+import ChatConversationHeader from './chat-conversation-header.svelte';
+
+export default ChatConversationHeader;
+export type {
+  ChatConversationHeaderHeadingLevel,
+  ChatConversationHeaderProps,
+} from './chat-conversation-header.types.ts';
+export { ChatConversationHeader };

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

@@ -0,0 +1,45 @@
+# 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/chat-conversation-list/chat-conversation-list.css

@@ -0,0 +1,114 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  .cinder-chat-conversation-list {
+    display: block;
+  }
+
+  .cinder-chat-conversation-list__items {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-1);
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  .cinder-chat-conversation-list__item {
+    list-style: none;
+  }
+
+  .cinder-chat-conversation-list__button {
+    position: relative;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) max-content;
+    gap: var(--cinder-space-0-5) var(--cinder-space-2);
+    align-items: start;
+    width: 100%;
+    min-height: 3.25rem;
+    padding: var(--cinder-space-2) var(--cinder-space-3);
+    text-align: start;
+    color: var(--cinder-text);
+    background: transparent;
+    border: 1px solid transparent;
+    border-radius: var(--cinder-radius-md);
+  }
+
+  .cinder-chat-conversation-list__button[data-cinder-conversation-interactive] {
+    cursor: pointer;
+  }
+
+  .cinder-chat-conversation-list__button[data-cinder-conversation-selected] {
+    background: var(--cinder-surface-raised);
+    border-color: var(--cinder-border);
+  }
+
+  @media (hover: hover) {
+    .cinder-chat-conversation-list__button[data-cinder-conversation-interactive]:hover {
+      background: var(--cinder-surface-hover);
+    }
+  }
+
+  .cinder-chat-conversation-list__button[data-cinder-conversation-interactive]:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  .cinder-chat-conversation-list__title {
+    grid-column: 1;
+    grid-row: 1;
+    min-width: 0;
+    overflow: hidden;
+    font-weight: var(--cinder-font-medium);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .cinder-chat-conversation-list__preview {
+    grid-column: 1;
+    grid-row: 2;
+    min-width: 0;
+    overflow: hidden;
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-sm);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .cinder-chat-conversation-list__badge {
+    grid-column: 2;
+    grid-row: 1 / span 2;
+    align-self: center;
+    justify-self: end;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: 1.5rem;
+    min-height: 1.5rem;
+    inline-size: max-content;
+    max-inline-size: max-content;
+    padding-inline: var(--cinder-space-1);
+    color: var(--cinder-accent-text);
+    background: color-mix(in oklch, var(--cinder-accent), transparent 88%);
+    border-radius: var(--cinder-radius-full);
+    font-size: var(--cinder-text-xs);
+    font-weight: var(--cinder-font-medium);
+  }
+
+  .cinder-chat-conversation-list__empty {
+    margin: 0;
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-sm);
+  }
+
+  .cinder-chat-conversation-list .sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+}

package/src/components/chat-conversation-list/chat-conversation-list.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "chat-conversation-list",
+  "import": "@lostgradient/cinder/chat-conversation-list",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic conversation list",
+      "description": "Conversation summaries with an active conversation and unread count.",
+      "code": "<script lang=\"ts\">\n  import { ChatConversationList, type ConversationSummary } from '@lostgradient/cinder';\n\n  const conversations: ConversationSummary[] = [\n    {\n      id: 'launch',\n      title: 'Launch support',\n      status: 'active',\n      messageCount: 12,\n      unreadCount: 2,\n      createdAt: '2026-06-01T08:00:00.000Z',\n      updatedAt: '2026-06-01T08:45:00.000Z',\n      lastMessageId: 'launch-last',\n      lastMessageRole: 'assistant',\n      lastMessageText: 'I drafted the launch checklist.',\n      lastMessageAt: '2026-06-01T08:45:00.000Z',\n      participantNames: ['Ada', 'Grace'],\n    },\n    {\n      id: 'billing',\n      title: 'Billing question',\n      status: 'active',\n      messageCount: 4,\n      unreadCount: 0,\n      createdAt: '2026-06-01T07:00:00.000Z',\n      updatedAt: '2026-06-01T07:20:00.000Z',\n      lastMessageId: 'billing-last',\n      lastMessageRole: 'user',\n      lastMessageText: 'Can you resend the invoice?',\n      lastMessageAt: '2026-06-01T07:20:00.000Z',\n      participantNames: ['Lin'],\n    },\n  ];\n</script>\n\n<ChatConversationList {conversations} activeConversationId=\"launch\" />\n"
+    }
+  ]
+}

package/src/components/chat-conversation-list/chat-conversation-list.svelte

@@ -0,0 +1,110 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category domain
+   * @status domain-suite
+   * @purpose Conversation navigation list for switching among Chat transcripts without embedding the list inside Chat.
+   * @tag chat
+   * @tag conversation
+   * @tag navigation
+   * @useWhen Rendering a multi-conversation chat sidebar beside one active Chat transcript.
+   * @useWhen Showing unread counts and last-message previews for compatible conversation snapshots.
+   * @avoidWhen Rendering the message transcript itself — use chat for the active conversation surface.
+   * @avoidWhen Building app-wide primary navigation — use side-navigation or navigation-bar.
+   * @related chat, chat-conversation-header, side-navigation
+   */
+  export type { ChatConversationListProps } from './chat-conversation-list.types.ts';
+  export type { ConversationSummary } from './conversation-summary.ts';
+  export { deriveConversationSummary } from './conversation-summary.ts';
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../utilities/class-names.ts';
+  import type { ChatConversationListProps } from './chat-conversation-list.types.ts';
+  import { conversationSummaryTimestamp } from './conversation-summary.ts';
+
+  let {
+    conversations,
+    activeConversationId = null,
+    ariaLabel = 'Conversations',
+    emptyText = 'No conversations',
+    class: className,
+    onselectconversation,
+    ...rest
+  }: ChatConversationListProps = $props();
+
+  const sortedConversations = $derived.by(() =>
+    [...conversations].sort(
+      (a, b) => conversationSummaryTimestamp(b) - conversationSummaryTimestamp(a),
+    ),
+  );
+
+  function preview(summary: (typeof sortedConversations)[number]): string {
+    const text = summary.lastMessageText?.trim();
+    if (!text) return summary.messageCount === 1 ? '1 message' : `${summary.messageCount} messages`;
+    return text.length > 96 ? `${text.slice(0, 93)}...` : text;
+  }
+
+  function unreadMessageLabel(unreadCount: number): string {
+    return unreadCount === 1 ? '1 unread message' : `${unreadCount} unread messages`;
+  }
+
+  const resolvedAriaLabel = $derived(
+    typeof ariaLabel === 'string' && ariaLabel.trim().length > 0 ? ariaLabel : undefined,
+  );
+</script>
+
+<nav
+  {...rest}
+  class={classNames('cinder-chat-conversation-list', className)}
+  aria-label={resolvedAriaLabel}
+>
+  {#if sortedConversations.length === 0}
+    <p class="cinder-chat-conversation-list__empty" role="status">{emptyText}</p>
+  {:else}
+    <ul class="cinder-chat-conversation-list__items">
+      {#each sortedConversations as conversation (conversation.id)}
+        {@const isActive = conversation.id === activeConversationId}
+        <li class="cinder-chat-conversation-list__item">
+          {#if onselectconversation}
+            <button
+              type="button"
+              class="cinder-chat-conversation-list__button"
+              aria-current={isActive ? 'page' : undefined}
+              data-cinder-conversation-item
+              data-cinder-conversation-interactive
+              data-cinder-conversation-selected={isActive ? '' : undefined}
+              onclick={() => onselectconversation(conversation.id)}
+            >
+              <span class="cinder-chat-conversation-list__title">{conversation.title}</span>
+              <span class="cinder-chat-conversation-list__preview">{preview(conversation)}</span>
+              {#if conversation.unreadCount > 0}
+                <span class="cinder-chat-conversation-list__badge" aria-hidden="true">
+                  {conversation.unreadCount > 99 ? '99+' : conversation.unreadCount}
+                </span>
+                <span class="sr-only">, {unreadMessageLabel(conversation.unreadCount)}</span>
+              {/if}
+            </button>
+          {:else}
+            <div
+              class="cinder-chat-conversation-list__button"
+              aria-current={isActive ? 'page' : undefined}
+              data-cinder-conversation-item
+              data-cinder-conversation-static
+              data-cinder-conversation-selected={isActive ? '' : undefined}
+            >
+              <span class="cinder-chat-conversation-list__title">{conversation.title}</span>
+              <span class="cinder-chat-conversation-list__preview">{preview(conversation)}</span>
+              {#if conversation.unreadCount > 0}
+                <span class="cinder-chat-conversation-list__badge" aria-hidden="true">
+                  {conversation.unreadCount > 99 ? '99+' : conversation.unreadCount}
+                </span>
+                <span class="sr-only">, {unreadMessageLabel(conversation.unreadCount)}</span>
+              {/if}
+            </div>
+          {/if}
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</nav>

package/src/components/chat-conversation-list/chat-conversation-list.types.ts

@@ -0,0 +1,18 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ConversationSummary } from './conversation-summary.ts';
+
+/** Props for the ChatConversationList component. */
+export type ChatConversationListProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Conversation summaries to render. Sorts by latest message/update time descending. */
+  conversations: readonly ConversationSummary[];
+  /** Currently active conversation id. */
+  activeConversationId?: string | null;
+  /** Accessible name for the conversations navigation landmark. Default `"Conversations"`. */
+  ariaLabel?: string;
+  /** Empty state text when no conversations are present. Default `"No conversations"`. */
+  emptyText?: string;
+  /** Additional class name merged with `.cinder-chat-conversation-list`. */
+  class?: string;
+  /** Called when a conversation is selected. */
+  onselectconversation?: (conversationId: string) => void;
+};

package/src/components/chat-conversation-list/conversation-summary.ts

@@ -0,0 +1,88 @@
+import type {
+  ConversationHistory,
+  ConversationStatus,
+  Message,
+} from '../chat/conversation-model.ts';
+import { getMessageText } from '../chat/utilities';
+import { getMessages } from '../chat/utilities/conversation.ts';
+
+export type ConversationSummary = {
+  /** Conversation identifier. */
+  id: string;
+  /** Human-readable conversation title. */
+  title: string;
+  /** Compatible conversation lifecycle status. */
+  status: ConversationStatus;
+  /** Number of visible transcript messages. */
+  messageCount: number;
+  /** Optional unread count derived from namespaced conversation metadata. */
+  unreadCount: number;
+  /** ISO timestamp used for sorting and recency display. */
+  updatedAt: string;
+  /** ISO timestamp for the conversation creation time. */
+  createdAt: string;
+  /** Last visible message id, when present. */
+  lastMessageId?: string;
+  /** Last visible message role, when present. */
+  lastMessageRole?: Message['role'];
+  /** Text preview for the last visible message. */
+  lastMessageText?: string;
+  /** Created timestamp for the last visible message. */
+  lastMessageAt?: string;
+  /** Optional participant names derived from namespaced conversation metadata. */
+  participantNames: readonly string[];
+};
+
+function metadataNumber(metadata: Readonly<Record<string, unknown>>, key: string): number {
+  const value = metadata[key];
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+
+function metadataStringArray(
+  metadata: Readonly<Record<string, unknown>>,
+  key: string,
+): readonly string[] {
+  const value = metadata[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === 'string' && item.trim() !== '');
+}
+
+function fallbackTitle(message: Message | undefined): string {
+  if (!message) return 'Untitled conversation';
+
+  const text = getMessageText(message).trim().replace(/\s+/g, ' ');
+  if (text.length === 0) return 'Untitled conversation';
+  return text.length > 64 ? `${text.slice(0, 61)}...` : text;
+}
+
+/** Derives a list/header summary from a compatible ConversationHistory snapshot. */
+export function deriveConversationSummary(conversation: ConversationHistory): ConversationSummary {
+  const messages = getMessages(conversation);
+  const lastMessage = messages.at(-1);
+  const title = conversation.title?.trim() || fallbackTitle(lastMessage);
+
+  return {
+    id: conversation.id,
+    title,
+    status: conversation.status,
+    messageCount: messages.length,
+    unreadCount: metadataNumber(conversation.metadata, '_unreadCount'),
+    updatedAt: conversation.updatedAt,
+    createdAt: conversation.createdAt,
+    participantNames: metadataStringArray(conversation.metadata, '_participantNames'),
+    ...(lastMessage
+      ? {
+          lastMessageId: lastMessage.id,
+          lastMessageRole: lastMessage.role,
+          lastMessageText: getMessageText(lastMessage),
+          lastMessageAt: lastMessage.createdAt,
+        }
+      : {}),
+  };
+}
+
+export function conversationSummaryTimestamp(summary: ConversationSummary): number {
+  const timestamp = summary.lastMessageAt ?? summary.updatedAt ?? summary.createdAt;
+  const time = Date.parse(timestamp);
+  return Number.isNaN(time) ? 0 : time;
+}

package/src/components/chat-conversation-list/index.ts

@@ -0,0 +1,11 @@
+import './chat-conversation-list.css';
+import ChatConversationList from './chat-conversation-list.svelte';
+
+export default ChatConversationList;
+export type { ChatConversationListProps } from './chat-conversation-list.types.ts';
+export {
+  conversationSummaryTimestamp,
+  deriveConversationSummary,
+  type ConversationSummary,
+} from './conversation-summary.ts';
+export { ChatConversationList };

package/src/components/checkbox/README.md

@@ -25,7 +25,7 @@ Single boolean toggle for opt-in selections within forms or settings.
 | `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       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                             |
+| `class`         | `(opaque)` | no       | —       | Extra class names merged with `.cinder-checkbox`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                        |
 
 <!-- generated:props:end -->
 

package/src/components/checkbox/checkbox.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic checkbox",
       "description": "Unchecked and checked variants with associated labels.",
-      "code": "<script lang=\"ts\">\n  import { Checkbox } from '@lostgradient/cinder/checkbox';\n  let acceptTerms = $state(false);\n  let subscribed = $state(true);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.75rem;\">\n  <Checkbox id=\"checkbox-terms\" label=\"I accept the terms of service\" bind:checked={acceptTerms} />\n  <Checkbox\n    id=\"checkbox-newsletter\"\n    label=\"Subscribe to the newsletter\"\n    bind:checked={subscribed}\n  />\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { Checkbox } from '@lostgradient/cinder/checkbox';\n\n  let acceptTerms = $state(false);\n  let subscribed = $state(true);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.75rem;\">\n  <Checkbox id=\"terms\" label=\"I accept the terms of service\" bind:checked={acceptTerms} />\n  <Checkbox id=\"newsletter\" label=\"Subscribe to the newsletter\" bind:checked={subscribed} />\n</div>\n"
     },
     {
       "id": "disabled",

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

@@ -25,7 +25,7 @@ Wraps multiple checkboxes under a shared label and validation context.
 | `legend`      | `string`                | no       | —       | Optional legend rendered as a `<legend>` inside the `<fieldset>`.                                                                                                                                                                                                                                                                                                                                                                                                |
 | `required`    | `boolean`               | no       | —       | Marks the group as visually required. Sets `data-cinder-required` on the fieldset so consumers can target it (e.g. legend asterisk). This is a visual/data-attribute hint. It does NOT set `required` on any child `<input>` and does NOT enforce constraint validation. Per-control `required` must be set on the individual `<Checkbox>`.                                                                                                                      |
 | `variant`     | `"default"` \| `"card"` | no       | —       | Layout variant. `'default'` is a stacked column. `'card'` styles each direct child `.cinder-checkbox-field` as a bordered card row. Always emitted as `data-variant` on the fieldset. Card variant assumes each direct child of the items container is a single `<Checkbox>`.                                                                                                                                                                                    |
-| `children`    | `(opaque)`              | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                       |
+| `children`    | `(opaque)`              | yes      | —       | Checkbox children. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                    |
 
 <!-- generated:props:end -->
 

package/src/components/chip/README.md

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