@lostgradient/cinder 0.6.0 → 0.8.0

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

@@ -0,0 +1,75 @@
+<script lang="ts" module>
+export { deriveConversationSummary } from './conversation-summary.ts';
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import { conversationSummaryTimestamp } from './conversation-summary.ts';
+let { conversations, activeConversationId = null, ariaLabel = 'Conversations', emptyText = 'No conversations', class: className, onselectconversation, ...rest } = $props();
+const sortedConversations = $derived.by(() => [...conversations].sort((a, b) => conversationSummaryTimestamp(b) - conversationSummaryTimestamp(a)));
+function preview(summary) {
+    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) {
+    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/chat-conversation-list.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

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/checkbox.schema.ts

@@ -0,0 +1,59 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    checked: {
+      type: 'boolean',
+      description: 'Bound checked state.',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disables the checkbox.',
+    },
+    indeterminate: {
+      type: 'boolean',
+      description: 'Bound indeterminate state. Mutually exclusive with `checked` visually.',
+    },
+    id: {
+      type: 'string',
+      description:
+        'Unique identifier for label association and ARIA wiring. Optional: when omitted,\na stable id is generated via `$props.id()` (or inherited from a FormField context),\nmatching Input/Autocomplete. Provide it when you need a known id to reference.',
+    },
+    label: {
+      type: 'string',
+      description: 'Visible label rendered in a `<label>` element associated via `for`.',
+    },
+    description: {
+      type: 'string',
+      description: 'Helper text displayed below the checkbox; wired via `aria-describedby`.',
+    },
+    error: {
+      type: 'string',
+      description: 'Validation error message; sets `aria-invalid="true"` and `aria-describedby`.',
+    },
+    fieldClass: {
+      type: 'string',
+      description: 'Extra class names merged with the outer checkbox field wrapper.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'class',
+        reason: 'unknown-shape',
+        description: 'Extra class names merged with `.cinder-checkbox`.',
+      },
+      {
+        name: 'onValueChange',
+        reason: 'function-or-snippet',
+        description:
+          'Intercept a proposed checked state before the bindable value is written. Return a replacement value to transform it.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/checkbox/checkbox.svelte

@@ -0,0 +1,126 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { resolveFieldControl } from '../../_internal/field-control.ts';
+import { getFormFieldContext } from '../../_internal/form-field-context.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import { devWarn } from '../../utilities/dev-warn.ts';
+import { commitValue } from '../../utilities/value-change.ts';
+let { id, checked = $bindable(false), onValueChange, indeterminate = $bindable(false), label, description, error, disabled, required, fieldClass, class: className, 'aria-describedby': consumerDescribedBy, 'aria-invalid': consumerInvalid, onchange: consumerOnchange, ...rest } = $props();
+// Stable generated id fallback (Svelte 5 $props.id()), used when neither the `id`
+// prop nor a FormField context controlId is present — matches input/autocomplete.
+// Passing the (possibly undefined) `id` prop as the fallback would leave field.id
+// undefined for an unlabeled standalone checkbox, breaking for=/id=/describedby.
+const generatedId = $props.id();
+const context = getFormFieldContext();
+const field = $derived(resolveFieldControl({
+    // Conditionally spread `id` so `id: undefined` isn't passed (exactOptionalPropertyTypes);
+    // matches autocomplete. The generatedId fallback covers the no-id case.
+    ...(id !== undefined ? { id } : {}),
+    generatedId,
+    context,
+    hasDescription: !!description,
+    hasError: !!error,
+    localIdNamespace: 'checkbox',
+    consumerDescribedBy,
+    consumerInvalid,
+    disabled,
+    // HTMLInputAttributes types `required` as boolean | null | undefined; the helper
+    // wants boolean | undefined, so coerce a null to undefined (keeps false/true).
+    required: required ?? undefined,
+}));
+// Dev-mode guard (matches Input/Autocomplete): inside a FormField, a consumer `id`
+// that disagrees with the FormField's controlId means the FormField's <label for>
+// points at a different id than this input renders, breaking the label association.
+$effect(() => {
+    if (context && id && context.controlId !== id) {
+        devWarn(`[cinder/Checkbox] id mismatch: Checkbox id="${id}" but wrapping FormField expects controlId="${context.controlId}". Set the same id on both, or omit id on the Checkbox to inherit it.`);
+    }
+});
+// `indeterminate` is a DOM property, not an attribute. Sync it whenever
+// either the prop or the bound element changes. Toggling `checked` clears
+// indeterminate to match native behavior.
+let inputElement = $state();
+$effect(() => {
+    if (inputElement) {
+        inputElement.indeterminate = indeterminate && !checked;
+    }
+});
+let resetSyncTimeout;
+function syncCheckedAfterFormReset() {
+    if (resetSyncTimeout !== undefined)
+        clearTimeout(resetSyncTimeout);
+    resetSyncTimeout = setTimeout(() => {
+        resetSyncTimeout = undefined;
+        if (!inputElement)
+            return;
+        checked = inputElement.checked;
+        inputElement.indeterminate = indeterminate && !inputElement.checked;
+    }, 0);
+}
+$effect(() => {
+    const form = inputElement?.form;
+    if (!form)
+        return;
+    form.addEventListener('reset', syncCheckedAfterFormReset);
+    return () => {
+        form.removeEventListener('reset', syncCheckedAfterFormReset);
+        if (resetSyncTimeout !== undefined) {
+            clearTimeout(resetSyncTimeout);
+            resetSyncTimeout = undefined;
+        }
+    };
+});
+function handleChange(event) {
+    const target = event.currentTarget;
+    const committed = commitValue(target.checked, onValueChange, (next) => {
+        checked = next;
+    });
+    target.checked = committed;
+    target.indeterminate = indeterminate && !committed;
+    consumerOnchange?.(event);
+}
+</script>
+
+<div class={classNames('cinder-checkbox-field', fieldClass)}>
+  <div class="cinder-checkbox-row">
+    <span class="cinder-checkbox-field__control">
+      <input
+        bind:this={inputElement}
+        id={field.id}
+        type="checkbox"
+        {...rest}
+        disabled={field.disabled}
+        required={field.required}
+        {checked}
+        onchange={handleChange}
+        class={classNames('cinder-checkbox', className)}
+        aria-invalid={field.ariaInvalid}
+        aria-describedby={field.describedBy}
+      />
+      <span class="cinder-checkbox-field__indicator" aria-hidden="true"></span>
+    </span>
+    {#if label}
+      <label
+        for={field.id}
+        class="cinder-checkbox-field__label"
+        data-disabled={field.disabled || undefined}
+      >
+        {label}
+        {#if field.required}
+          <span class="cinder-_required-marker" aria-hidden="true">*</span>
+        {/if}
+      </label>
+    {/if}
+  </div>
+
+  {#if description}
+    <p id={field.ownDescriptionId} class="cinder-checkbox-field__description">{description}</p>
+  {/if}
+
+  {#if error}
+    <p id={field.ownErrorId} class="cinder-checkbox-field__error" aria-live="polite">{error}</p>
+  {/if}
+</div>

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

@@ -0,0 +1,39 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+/**
+ * Props for the Checkbox component.
+ *
+ * Backed by a native `<input type="checkbox">` so it participates in form
+ * submission and reset without extra wiring. The component owns the
+ * label/description/error wrapper but delegates state, `name`, `value`,
+ * and `disabled` semantics to the native element.
+ *
+ * `indeterminate` is a DOM property, not an attribute — Svelte's effect
+ * sets it imperatively each time the prop changes, then clears it once
+ * the user toggles `checked`.
+ */
+export type CheckboxProps = HTMLInputAttributes & {
+  /**
+   * 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.
+   */
+  id?: string;
+  /** Bound checked state. */
+  checked?: boolean;
+  /** Intercept a proposed checked state before the bindable value is written. Return a replacement value to transform it. */
+  onValueChange?: (next: boolean) => boolean | void;
+  /** Bound indeterminate state. Mutually exclusive with `checked` visually. */
+  indeterminate?: boolean;
+  /** Visible label rendered in a `<label>` element associated via `for`. */
+  label?: string;
+  /** Helper text displayed below the checkbox; wired via `aria-describedby`. */
+  description?: string;
+  /** Validation error message; sets `aria-invalid="true"` and `aria-describedby`. */
+  error?: string;
+  /** Disables the checkbox. */
+  disabled?: boolean;
+  /** Extra class names merged with the outer checkbox field wrapper. */
+  fieldClass?: string;
+  /** Extra class names merged with `.cinder-checkbox`. */
+  class?: string;
+};

package/src/components/checkbox/checkbox.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/checkbox/index.ts

@@ -0,0 +1,6 @@
+import './checkbox.css';
+import Checkbox from './checkbox.svelte';
+
+export default Checkbox;
+export type { CheckboxProps } from './checkbox.types.ts';
+export { Checkbox };

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

@@ -0,0 +1,54 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    label: {
+      type: 'string',
+      description:
+        'Visible group caption. Rendered as a `<legend>` inside the `<fieldset>`.\nNamed `label` for consistency with every other form control — the element\nis a `<legend>` because the group is a fieldset.',
+    },
+    description: {
+      type: 'string',
+      description: 'Helper text below the group; wired via `aria-describedby` on the fieldset.',
+    },
+    error: {
+      type: 'string',
+      description:
+        'Group-level validation message. Rendered as a polite live region and\nreferenced by the fieldset\'s `aria-describedby`. Also sets\n`aria-invalid="true"` on the fieldset itself as a supplementary signal.\n\nNote: fieldset-level `aria-describedby` is not reliably re-announced as\nfocus moves between descendants. This is best-effort supplemental context\n— if a specific control must announce as invalid on focus, pass `error`\nto that `<Checkbox>` directly.',
+    },
+    disabled: {
+      type: 'boolean',
+      description:
+        "Disables every native form control inside via the fieldset's built-in\ncascade. Renders as the native `disabled` attribute on `<fieldset>`.",
+    },
+    required: {
+      type: 'boolean',
+      description:
+        'Marks the group required: sets `aria-required="true"` and\n`data-cinder-required` on the fieldset and renders the required asterisk in\nthe legend.\n\nIt does NOT set `required` on any child `<input>` and does NOT enforce\nnative constraint validation. Per-control `required` must be set on the\nindividual `<Checkbox>`.',
+    },
+    variant: {
+      enum: ['default', 'card'],
+      description:
+        "Layout variant. `'default'` is a stacked column. `'card'` styles each\ndirect child `.cinder-checkbox-field` as a bordered card row.\n\nAlways emitted as `data-variant` on the fieldset. Card variant assumes\neach direct child of the items container is a single `<Checkbox>`.",
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-checkbox-group`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Checkbox children.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

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

@@ -0,0 +1,69 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { ariaInvalid, composeDescribedBy, describeId, errorId as buildErrorId, } from '../../_internal/field-control.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import { devWarn } from '../../utilities/dev-warn.ts';
+const groupId = $props.id();
+let { label: legend, description, error, disabled = false, required = false, variant = 'default', class: className, children, } = $props();
+const descriptionId = $derived(describeId(groupId, !!description));
+const errId = $derived(buildErrorId(groupId, !!error));
+const describedBy = $derived(composeDescribedBy(descriptionId, errId));
+// Warn once when no accessible group name is provided. The `hasWarned` flag
+// stops the effect re-firing on every `legend` change — matching the
+// tree.svelte convention and dev-warn.ts's guidance against a warn-only
+// effect that re-subscribes on each update.
+let hasWarnedNoLegend = false;
+$effect(() => {
+    if (!legend && !hasWarnedNoLegend) {
+        hasWarnedNoLegend = true;
+        devWarn('[cinder/CheckboxGroup] A <fieldset> was rendered without a label prop. The fieldset will have no <legend>, which makes it inaccessible. Provide a label prop to describe the group.');
+    }
+});
+</script>
+
+<!--
+  `aria-invalid` on the <fieldset> (implicit role=group) is a deliberate,
+  best-effort supplemental signal — see checkbox-group.a11y.md. ARIA does not
+  formally list aria-invalid for role=group and most screen readers do not
+  announce it there, so the PRIMARY error signal is the visible aria-live region
+  referenced by aria-describedby. This group wraps independent checkboxes and
+  does not propagate its error to them; per-control aria-invalid is set by each
+  <Checkbox> from its own `error` prop, which the consumer supplies when a
+  specific control is invalid. The lint rule is suppressed for this documented,
+  tested tradeoff.
+-->
+<!-- svelte-ignore a11y_role_supports_aria_props_implicit -->
+<fieldset
+  class={classNames('cinder-checkbox-group', className)}
+  {disabled}
+  aria-invalid={ariaInvalid(!!error)}
+  aria-describedby={describedBy}
+  aria-required={required || undefined}
+  data-cinder-disabled={disabled || undefined}
+  data-cinder-required={required || undefined}
+  data-variant={variant}
+>
+  {#if legend}
+    <legend class="cinder-checkbox-group__legend">
+      {legend}
+      {#if required}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
+    </legend>
+  {/if}
+
+  <div class="cinder-checkbox-group__items">
+    {@render children()}
+  </div>
+
+  {#if description}
+    <p id={descriptionId} class="cinder-checkbox-group__description">{description}</p>
+  {/if}
+
+  {#if error}
+    <p id={errId} class="cinder-checkbox-group__error" aria-live="polite">{error}</p>
+  {/if}
+</fieldset>

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

@@ -0,0 +1,58 @@
+import type { Snippet } from 'svelte';
+/**
+ * Props for the CheckboxGroup component.
+ *
+ * Wraps a set of independent checkboxes in a `<fieldset>` + `<legend>`
+ * structure for semantic grouping. Unlike RadioGroup, this component does
+ * NOT own a shared `value` or `name` — each child `<Checkbox>` owns its
+ * own name and checked state. Native `<fieldset disabled>` propagation
+ * handles the disabled cascade without any Svelte context.
+ */
+export type CheckboxGroupProps = {
+  /**
+   * Visible group caption. Rendered as a `<legend>` inside the `<fieldset>`.
+   * Named `label` for consistency with every other form control — the element
+   * is a `<legend>` because the group is a fieldset.
+   */
+  label?: string;
+  /** Helper text below the group; wired via `aria-describedby` on the fieldset. */
+  description?: string;
+  /**
+   * 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.
+   */
+  error?: string;
+  /**
+   * Disables every native form control inside via the fieldset's built-in
+   * cascade. Renders as the native `disabled` attribute on `<fieldset>`.
+   */
+  disabled?: boolean;
+  /**
+   * 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>`.
+   */
+  required?: boolean;
+  /**
+   * 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>`.
+   */
+  variant?: 'default' | 'card';
+  /** Additional class names merged with `.cinder-checkbox-group`. */
+  class?: string;
+  /** Checkbox children. */
+  children: Snippet;
+};

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

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

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

@@ -0,0 +1,6 @@
+import './checkbox-group.css';
+import CheckboxGroup from './checkbox-group.svelte';
+
+export default CheckboxGroup;
+export type { CheckboxGroupProps } from './checkbox-group.types.ts';
+export { CheckboxGroup };