@lostgradient/cinder 0.4.0 → 0.5.0

package/src/components/combobox/combobox.svelte

@@ -28,6 +28,7 @@
   let {
     id,
     value = $bindable(''),
+    name,
     inputValue = $bindable(''),
     options,
     label,
@@ -92,8 +93,12 @@
   let open = $state(false);
   let activeIndex = $state(-1);
   let inputElement = $state<HTMLInputElement | null>(null);
+  let hiddenInputElement = $state<HTMLInputElement | null>(null);
   let listboxElement = $state<HTMLElement | null>(null);
   let committedLabel = $state('');
+  let resetSyncTimeout: ReturnType<typeof setTimeout> | undefined;
+  const initialValue = untrack(() => value);
+  const initialInputValue = untrack(() => inputValue);
 
   // Reset active index whenever the filtered set changes so we don't point
   // at a stale option.
@@ -203,6 +208,45 @@
     open = false;
   }
 
+  function resetToInitialValue(event: Event): void {
+    if (resetSyncTimeout !== undefined) clearTimeout(resetSyncTimeout);
+    resetSyncTimeout = setTimeout(() => {
+      resetSyncTimeout = undefined;
+      if (event.defaultPrevented) return;
+      value = initialValue;
+      const matched = options.find((option) => option.value === initialValue);
+      const nextInputValue = matched?.label ?? initialInputValue;
+      inputValue = nextInputValue;
+      committedLabel = matched?.label ?? '';
+      open = false;
+      activeIndex = -1;
+      if (inputElement) inputElement.value = nextInputValue;
+      if (hiddenInputElement) hiddenInputElement.value = initialValue;
+    }, 0);
+  }
+
+  $effect(() => {
+    const input = hiddenInputElement;
+    if (input === null) return;
+    const form = input.form;
+    form?.addEventListener('reset', resetToInitialValue);
+    return () => {
+      form?.removeEventListener('reset', resetToInitialValue);
+      if (resetSyncTimeout !== undefined) {
+        clearTimeout(resetSyncTimeout);
+        resetSyncTimeout = undefined;
+      }
+    };
+  });
+
+  $effect(() => {
+    inputElement?.setCustomValidity(
+      (resolvedRequired && !value) || inputValue !== committedLabel
+        ? 'Please select an option.'
+        : '',
+    );
+  });
+
   function handleKeydown(event: KeyboardEvent) {
     if (event.key === 'ArrowDown') {
       event.preventDefault();
@@ -262,6 +306,7 @@
       autocorrect="off"
       spellcheck="false"
       disabled={resolvedDisabled}
+      required={resolvedRequired}
       {placeholder}
       value={inputValue}
       aria-autocomplete="list"
@@ -278,6 +323,16 @@
     />
   </div>
 
+  {#if name}
+    <input
+      bind:this={hiddenInputElement}
+      type="hidden"
+      {name}
+      {value}
+      disabled={resolvedDisabled}
+    />
+  {/if}
+
   {#if open && filteredOptions.length > 0}
     <Popover
       bind:open

package/src/components/combobox/combobox.types.ts

@@ -38,6 +38,8 @@ export type ComboboxProps<T extends string = string> = {
   id: string;
   /** Currently selected value. Bindable. `''` when nothing is selected. */
   value?: NoInfer<T> | '';
+  /** Native form field name. Renders a hidden input carrying the selected value. */
+  name?: string | undefined;
   /** Free-text input value (the text the user has typed). Bindable. */
   inputValue?: string;
   /** Full set of options to filter. The sole inference source for T. */

package/src/components/cta-section/cta-section.css

@@ -0,0 +1,54 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+/* Compound composition aggregation: CtaSection renders these primitives internally,
+ * so `cinder/cta-section/styles` includes their sidecar styles for slim imports. */
+@import '../button/button.css';
+@import '../container/container.css';
+
+@layer cinder.components {
+  .cinder-cta-section {
+    padding-block: var(--cinder-space-10);
+  }
+
+  .cinder-cta-section__inner {
+    border: 1px solid var(--cinder-border-muted);
+    border-radius: var(--cinder-radius-lg);
+    background: var(--cinder-surface-raised);
+    padding: var(--cinder-space-7);
+    display: grid;
+    gap: var(--cinder-space-4);
+    justify-items: start;
+  }
+
+  .cinder-cta-section[data-cinder-align='center'] .cinder-cta-section__inner {
+    justify-items: center;
+    text-align: center;
+  }
+
+  .cinder-cta-section[data-cinder-tone='accent'] .cinder-cta-section__inner {
+    background: color-mix(in oklch, var(--cinder-accent), transparent 92%);
+    border-color: color-mix(in oklch, var(--cinder-accent), transparent 65%);
+  }
+
+  .cinder-cta-section__title {
+    margin: 0;
+    font-size: var(--cinder-text-3xl);
+    line-height: var(--cinder-leading-tight);
+  }
+
+  .cinder-cta-section__description {
+    margin: 0;
+    color: var(--cinder-text-muted);
+    max-inline-size: 60ch;
+  }
+
+  .cinder-cta-section__actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--cinder-space-3);
+  }
+
+  .cinder-cta-section__extra {
+    color: var(--cinder-text-subtle);
+    font-size: var(--cinder-text-sm);
+  }
+}

package/src/components/cta-section/cta-section.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "cta-section",
+  "import": "@lostgradient/cinder/cta-section",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "CtaSection",
+      "description": "CtaSection with accent tone and primary/secondary conversion actions.",
+      "code": "<script lang=\"ts\">\n  import { CtaSection } from '@lostgradient/cinder/cta-section';\n</script>\n\n<CtaSection\n  title=\"Ready to level up your product UI?\"\n  description=\"Start with Cinder and ship accessible components with confidence.\"\n  primaryActionLabel=\"Start free\"\n  secondaryActionLabel=\"Talk to sales\"\n  tone=\"accent\"\n>\n  <span>No credit card required.</span>\n</CtaSection>\n"
+    }
+  ]
+}

package/src/components/cta-section/cta-section.svelte

@@ -0,0 +1,67 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category domain
+   * @status stable
+   * @purpose Focused conversion band with a short headline, supporting copy, and primary/secondary action buttons.
+   * @tag marketing
+   * @tag cta
+   * @tag conversion
+   * @useWhen Inserting a repeated “ready to get started?” conversion section between page segments.
+   * @useWhen Prompting sign-up or demo actions after readers consume feature or testimonial content.
+   * @avoidWhen Building a full top-of-page hero with complex media and long-form messaging. | hero-section
+   * @avoidWhen Capturing an email address inline with form fields. | newsletter-section
+   * @related hero-section, newsletter-section, button, container
+   */
+  export type { CtaSectionAlign, CtaSectionProps, CtaSectionTone } from './cta-section.types.ts';
+</script>
+
+<script lang="ts">
+  import Button from '../button/button.svelte';
+  import Container from '../container/container.svelte';
+  import { classNames } from '../../utilities/class-names.ts';
+
+  import type { CtaSectionProps } from './cta-section.types.ts';
+
+  let {
+    as = 'section',
+    title,
+    description,
+    primaryActionLabel,
+    secondaryActionLabel,
+    onPrimaryClick,
+    onSecondaryClick,
+    align = 'center',
+    tone = 'default',
+    maxWidth = 'wide',
+    class: className,
+    children,
+    ...rest
+  }: CtaSectionProps = $props();
+</script>
+
+<svelte:element
+  this={as}
+  class={classNames('cinder-cta-section', className)}
+  data-cinder-align={align}
+  data-cinder-tone={tone}
+  {...rest}
+>
+  <Container {maxWidth}>
+    <div class="cinder-cta-section__inner">
+      <h2 class="cinder-cta-section__title">{title}</h2>
+      {#if description}
+        <p class="cinder-cta-section__description">{description}</p>
+      {/if}
+      <div class="cinder-cta-section__actions">
+        <Button label={primaryActionLabel} variant="primary" onclick={onPrimaryClick} />
+        {#if secondaryActionLabel}
+          <Button label={secondaryActionLabel} variant="secondary" onclick={onSecondaryClick} />
+        {/if}
+      </div>
+      {#if children}
+        <div class="cinder-cta-section__extra">{@render children()}</div>
+      {/if}
+    </div>
+  </Container>
+</svelte:element>

package/src/components/cta-section/cta-section.types.ts

@@ -0,0 +1,55 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ContainerMaxWidth } from '../container/container.types.ts';
+
+export type CtaSectionAlign = 'start' | 'center';
+export type CtaSectionTone = 'default' | 'accent';
+
+/** Props for the CtaSection component. */
+export type CtaSectionProps = Omit<HTMLAttributes<HTMLElement>, 'children' | 'class'> & {
+  /** Wrapper element tag. @default "section" */
+  as?: 'section' | 'div';
+  /** Main CTA title. */
+  title: string;
+  /** Optional supporting copy. */
+  description?: string;
+  /** Label for the primary call-to-action button. */
+  primaryActionLabel: string;
+  /** Optional label for a secondary action button. */
+  secondaryActionLabel?: string;
+  /** Primary action click callback. */
+  onPrimaryClick?: () => void;
+  /** Secondary action click callback. */
+  onSecondaryClick?: () => void;
+  /** Content alignment. @default "center" */
+  align?: CtaSectionAlign;
+  /** Visual tone. @default "default" */
+  tone?: CtaSectionTone;
+  /** Max width token forwarded to Container. @default "wide" */
+  maxWidth?: ContainerMaxWidth;
+  /** Optional supplemental content below action buttons. */
+  children?: Snippet;
+  /** Custom class merged with `.cinder-cta-section`. */
+  class?: string;
+};
+
+export interface CtaSectionSchemaProps {
+  /** Wrapper element tag. @default "section" */
+  as?: 'section' | 'div';
+  /** Main CTA title. */
+  title: string;
+  /** Optional supporting copy. */
+  description?: string;
+  /** Label for the primary call-to-action button. */
+  primaryActionLabel: string;
+  /** Optional label for a secondary action button. */
+  secondaryActionLabel?: string;
+  /** Content alignment. @default "center" */
+  align?: CtaSectionAlign;
+  /** Visual tone. @default "default" */
+  tone?: CtaSectionTone;
+  /** Max width token forwarded to Container. @default "wide" */
+  maxWidth?: ContainerMaxWidth;
+  /** Custom class merged with `.cinder-cta-section`. */
+  class?: string;
+}

package/src/components/cta-section/index.ts

@@ -0,0 +1,6 @@
+import './cta-section.css';
+import CtaSection from './cta-section.svelte';
+
+export default CtaSection;
+export type { CtaSectionAlign, CtaSectionProps, CtaSectionTone } from './cta-section.types.ts';
+export { CtaSection };

package/src/components/data-table/data-table.css

@@ -6,6 +6,7 @@
  * an unstyled table and the scroll override below has no base behaviour to
  * extend. Sibling-leaf paths resolve identically in `src/` and `dist/`. */
 @import '../table/table.css';
+@import '../checkbox/checkbox.css';
 
 @layer cinder.components {
   /* ========================================
@@ -38,6 +39,25 @@
     contain: layout paint;
   }
 
+  .cinder-data-table[data-cinder-selectable] .cinder-table__cell--selection,
+  .cinder-data-table[data-cinder-selectable] .cinder-table__header-cell--selection {
+    width: 1px;
+    padding-inline: var(--cinder-space-3);
+    padding-block: var(--cinder-space-2);
+    text-align: center;
+    vertical-align: middle;
+  }
+
+  .cinder-data-table .cinder-table__cell--selection .cinder-checkbox-field,
+  .cinder-data-table .cinder-table__header-cell--selection .cinder-checkbox-field {
+    display: inline-block;
+  }
+
+  .cinder-data-table .cinder-table__cell--selection .cinder-checkbox-row,
+  .cinder-data-table .cinder-table__header-cell--selection .cinder-checkbox-row {
+    display: inline-flex;
+  }
+
   .cinder-data-table[data-cinder-virtualized] .cinder-table__row[data-cinder-virtual-row] {
     block-size: var(--_cinder-data-table-row-height, 44px);
   }

package/src/components/data-table/data-table.svelte

@@ -9,15 +9,21 @@
    * @useWhen Rendering a structured dataset where columns and rows are known at runtime (e.g. API responses, config-driven dashboards).
    * @useWhen You want correct scope=col / scope=row semantics and aria-sort wiring without writing Table.Header / Table.Body manually.
    * @avoidWhen You need custom cell rendering, interactive cells, nested components, or column spanning — use the compositional Table family directly.
-   * @avoidWhen You need row selection — DataTable does not expose a selection prop; use Table with selectable instead.
+   * @avoidWhen You need fully custom cell or row composition — use Table directly.
    * @related table, table-header, table-body, table-row, table-cell, table-header-cell
    */
-  export type { DataTableColumn, DataTableProps, DataTableRow } from './data-table.types.ts';
+  export type {
+    DataTableColumn,
+    DataTableProps,
+    DataTableRow,
+    DataTableSelectionMode,
+  } from './data-table.types.ts';
 </script>
 
 <script lang="ts" generics="Row extends DataTableRow">
-  import { tick } from 'svelte';
+  import { tick, untrack } from 'svelte';
 
+  import Checkbox from '../checkbox/checkbox.svelte';
   import TableBody from '../table-body/table-body.svelte';
   import TableCell from '../table-cell/table-cell.svelte';
   import TableHeaderCell from '../table-header-cell/table-header-cell.svelte';
@@ -40,6 +46,12 @@
     rows,
     caption,
     sort = $bindable(),
+    selectable = 'none',
+    selectedRowIds = $bindable<string[] | Set<string>>([]),
+    getRowId,
+    isRowSelectionDisabled,
+    selectAllLabel = 'Select all rows',
+    rowSelectionLabel,
     stickyHeader = false,
     density = 'comfortable',
     scrollable = false,
@@ -62,6 +74,8 @@
   let previousRowCount = 0;
   let hasObservedRowCount = false;
   let shouldStickAfterAppend = false;
+  let resetSyncTimeout: ReturnType<typeof setTimeout> | undefined;
+  const initialSelectedRowIds = untrack(() => new Set(selectedRowIds));
 
   /**
    * The key of the row-header column. Explicitly set via `column.rowHeader === true`,
@@ -71,6 +85,25 @@
   const rowHeaderKey = $derived(
     (columns.find((column) => column.rowHeader === true) ?? columns[0])?.key,
   );
+  const selectionEnabled = $derived(selectable !== 'none');
+  const selectedRowIdSet = $derived(new Set(selectedRowIds));
+  const selectableRowIds = $derived(
+    rows
+      .map((row, index) => ({
+        id: resolveRowId(row, index),
+        disabled: isRowSelectionDisabled?.(row, index) ?? false,
+      }))
+      .filter((row) => !row.disabled)
+      .map((row) => row.id),
+  );
+  const allRowsSelected = $derived(
+    selectable === 'multiple' &&
+      selectableRowIds.length > 0 &&
+      selectableRowIds.every((id) => selectedRowIdSet.has(id)),
+  );
+  const someRowsSelected = $derived(
+    selectable === 'multiple' && selectableRowIds.some((id) => selectedRowIdSet.has(id)),
+  );
   const shouldVirtualizeRows = $derived(virtualized);
   const resolvedRowHeight = $derived(resolveVirtualItemHeight(rowHeight, 44));
   const resolvedOverscan = $derived(resolveVirtualOverscan(overscan));
@@ -113,6 +146,76 @@
     return undefined;
   }
 
+  function resolveRowId(row: Row, index: number): string {
+    if (getRowId) return getRowId(row, index);
+    const candidate = row['id'];
+    if (typeof candidate === 'string' || typeof candidate === 'number') return String(candidate);
+    return String(index);
+  }
+
+  function readableRowLabel(row: Row, index: number): string {
+    const customLabel = rowSelectionLabel?.(row, index)?.trim();
+    if (customLabel) return customLabel;
+    const rowHeaderValue = rowHeaderKey ? row[rowHeaderKey] : undefined;
+    if (typeof rowHeaderValue === 'string' || typeof rowHeaderValue === 'number') {
+      return `Select ${rowHeaderValue}`;
+    }
+    return `Select row ${index + 1}`;
+  }
+
+  function commitSelectedRowIds(nextSelectedRowIds: Set<string>): void {
+    selectedRowIds =
+      selectedRowIds instanceof Set ? new Set(nextSelectedRowIds) : Array.from(nextSelectedRowIds);
+  }
+
+  function setRowSelected(row: Row, index: number, nextSelected: boolean): void {
+    if (!selectionEnabled || isRowSelectionDisabled?.(row, index)) return;
+    const rowId = resolveRowId(row, index);
+    const nextSelectedRowIds = new Set(selectedRowIdSet);
+
+    if (selectable === 'single') {
+      commitSelectedRowIds(nextSelected ? new Set([rowId]) : new Set());
+      return;
+    }
+
+    if (nextSelected) nextSelectedRowIds.add(rowId);
+    else nextSelectedRowIds.delete(rowId);
+    commitSelectedRowIds(nextSelectedRowIds);
+  }
+
+  function setAllRowsSelected(nextSelected: boolean): void {
+    if (selectable !== 'multiple') return;
+    const nextSelectedRowIds = new Set(selectedRowIdSet);
+    for (const rowId of selectableRowIds) {
+      if (nextSelected) nextSelectedRowIds.add(rowId);
+      else nextSelectedRowIds.delete(rowId);
+    }
+    commitSelectedRowIds(nextSelectedRowIds);
+  }
+
+  function syncSelectionAfterFormReset(event: Event): void {
+    if (resetSyncTimeout !== undefined) clearTimeout(resetSyncTimeout);
+    resetSyncTimeout = setTimeout(() => {
+      resetSyncTimeout = undefined;
+      if (event.defaultPrevented) return;
+      commitSelectedRowIds(initialSelectedRowIds);
+    }, 0);
+  }
+
+  $effect(() => {
+    const form = wrapperElement?.closest('form');
+    if (!form || !selectionEnabled) return;
+
+    form.addEventListener('reset', syncSelectionAfterFormReset);
+    return () => {
+      form.removeEventListener('reset', syncSelectionAfterFormReset);
+      if (resetSyncTimeout !== undefined) {
+        clearTimeout(resetSyncTimeout);
+        resetSyncTimeout = undefined;
+      }
+    };
+  });
+
   $effect(() => {
     const element = wrapperElement;
     if (!element || !shouldVirtualizeRows) return;
@@ -294,6 +397,14 @@
   function handleRowKeydown(event: KeyboardEvent, index: number): void {
     if (!shouldVirtualizeRows) return;
 
+    if (event.key === ' ' && selectionEnabled) {
+      const row = rows[index];
+      if (!row || isRowSelectionDisabled?.(row, index)) return;
+      event.preventDefault();
+      setRowSelected(row, index, !selectedRowIdSet.has(resolveRowId(row, index)));
+      return;
+    }
+
     if (event.key === 'ArrowDown') {
       event.preventDefault();
       focusRow(index + 1);
@@ -326,6 +437,26 @@
   >
     <TableHeader>
       <TableRow>
+        {#if selectionEnabled}
+          <th
+            scope="col"
+            class="cinder-table__header-cell cinder-table__header-cell--selection"
+            aria-label={selectable === 'single' ? 'Row selection' : undefined}
+          >
+            {#if selectable === 'multiple'}
+              <Checkbox
+                checked={allRowsSelected}
+                indeterminate={someRowsSelected && !allRowsSelected}
+                aria-label={selectAllLabel}
+                class="cinder-table__selection-checkbox"
+                onchange={(event) => {
+                  const input = event.currentTarget as HTMLInputElement;
+                  setAllRowsSelected(input.checked);
+                }}
+              />
+            {/if}
+          </th>
+        {/if}
         {#each columns as column (column.key)}
           <TableHeaderCell
             {...column.sortable ? { column: column.key } : {}}
@@ -347,7 +478,7 @@
         <tr class="cinder-data-table__virtual-spacer" aria-hidden="true">
           <td
             class="cinder-data-table__virtual-spacer-cell"
-            colspan={columns.length}
+            colspan={columns.length + (selectionEnabled ? 1 : 0)}
             style:height={`${virtualWindow.leadingSize}px`}
           ></td>
         </tr>
@@ -365,6 +496,26 @@
               }
             : {}}
         >
+          {#if selectionEnabled}
+            {@const rowSelectionDisabled =
+              isRowSelectionDisabled?.(virtualRow.row, virtualRow.index) ?? false}
+            {@const rowId = resolveRowId(virtualRow.row, virtualRow.index)}
+            <td
+              class="cinder-table__cell cinder-table__cell--selection"
+              data-cinder-selection-disabled={rowSelectionDisabled || undefined}
+            >
+              <Checkbox
+                checked={selectedRowIdSet.has(rowId)}
+                disabled={rowSelectionDisabled}
+                aria-label={readableRowLabel(virtualRow.row, virtualRow.index)}
+                class="cinder-table__selection-checkbox"
+                onchange={(event) => {
+                  const input = event.currentTarget as HTMLInputElement;
+                  setRowSelected(virtualRow.row, virtualRow.index, input.checked);
+                }}
+              />
+            </td>
+          {/if}
           {#each columns as column (column.key)}
             <TableCell
               as={column.key === rowHeaderKey ? 'th' : 'td'}
@@ -379,7 +530,7 @@
         <tr class="cinder-data-table__virtual-spacer" aria-hidden="true">
           <td
             class="cinder-data-table__virtual-spacer-cell"
-            colspan={columns.length}
+            colspan={columns.length + (selectionEnabled ? 1 : 0)}
             style:height={`${virtualWindow.trailingSize}px`}
           ></td>
         </tr>
@@ -398,6 +549,7 @@
     className,
   )}
   data-cinder-virtualized={shouldVirtualizeRows ? 'true' : undefined}
+  data-cinder-selectable={selectionEnabled || undefined}
   style:--cinder-data-table-height={shouldVirtualizeRows ? height : undefined}
   style:--_cinder-data-table-row-height={shouldVirtualizeRows
     ? `${resolvedRowHeight}px`

package/src/components/data-table/data-table.types.ts

@@ -44,6 +44,9 @@ export type DataTableColumn<Row extends DataTableRow = DataTableRow> = {
   rowHeader?: boolean;
 };
 
+/** Row-selection mode for DataTable. */
+export type DataTableSelectionMode = 'none' | 'single' | 'multiple';
+
 /**
  * Props for the DataTable component.
  *
@@ -73,6 +76,30 @@ export type DataTableProps<Row extends DataTableRow = DataTableRow> = Omit<
    * write back `undefined` itself (sort always toggles to a column).
    */
   sort?: TableSort | undefined;
+  /**
+   * Enables checkbox-based row selection. `"none"` renders no selection controls,
+   * `"single"` allows one selected row id, and `"multiple"` allows any number.
+   * Selection state is exposed through row checkbox controls; native table rows
+   * do not emit `aria-selected`.
+   * Defaults to `"none"`.
+   */
+  selectable?: DataTableSelectionMode;
+  /**
+   * Bound selected row ids. Arrays stay arrays on update; Sets stay Sets.
+   * When omitted, DataTable starts with an empty array.
+   */
+  selectedRowIds?: string[] | Set<string>;
+  /**
+   * Resolves the stable row id used for selection. Defaults to `row.id` when it
+   * is a string or number, otherwise the row's current positional index.
+   */
+  getRowId?: (row: Row, index: number) => string;
+  /** Returns true when a row should render a disabled selection checkbox. */
+  isRowSelectionDisabled?: (row: Row, index: number) => boolean;
+  /** Accessible label for the multiple-selection header checkbox. */
+  selectAllLabel?: string;
+  /** Accessible label for an individual row selection checkbox. */
+  rowSelectionLabel?: (row: Row, index: number) => string;
   /** When true, the header sticks to the top of the scrolling container. */
   stickyHeader?: boolean;
   /**

package/src/components/data-table/index.ts

@@ -2,5 +2,10 @@ import './data-table.css';
 import DataTable from './data-table.svelte';
 
 export default DataTable;
-export type { DataTableColumn, DataTableProps, DataTableRow } from './data-table.types.ts';
+export type {
+  DataTableColumn,
+  DataTableProps,
+  DataTableRow,
+  DataTableSelectionMode,
+} from './data-table.types.ts';
 export { DataTable };