@lostgradient/cinder 0.2.0 → 0.3.0

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

@@ -1,4 +1,5 @@
 import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
 
 /**
  * Discriminated union for row selection props.
@@ -16,12 +17,14 @@ import type { Snippet } from 'svelte';
  */
 export type TableRowSelectionProps =
   | {
+      /** Whether the row's selection checkbox is checked. Required in selectable tables alongside `onSelectedChange` and `selectionLabel`. */
       selected: boolean;
       onSelectedChange: (next: boolean) => void;
       selectionLabel: string;
       selectionDisabled?: false;
     }
   | {
+      /** When true, renders a disabled selection checkbox for this row, preventing selection while keeping the alignment cell. */
       selectionDisabled: true;
       selected?: undefined;
       onSelectedChange?: undefined;
@@ -40,7 +43,7 @@ export type TableRowSelectionProps =
       selectionDisabled?: undefined;
     };
 
-export type TableRowProps = {
+export type TableRowProps = Omit<HTMLAttributes<HTMLTableRowElement>, 'class'> & {
   /** Additional class names merged with `.cinder-table__row`. */
   class?: string;
   /** Cell children (TableCell or TableHeaderCell). */

package/src/components/tabs/README.md

@@ -64,7 +64,7 @@ trailing badge alone to convey it.
 | `class`           | `string`                       | no       | —       | Additional class names merged with `.cinder-tabs`.                                                                                                                                                            |
 | `orientation`     | `"horizontal"` \| `"vertical"` | no       | —       | Layout orientation. Affects which arrow keys move between tabs.                                                                                                                                               |
 | `value`           | `string`                       | no       | —       | Bound active tab value.                                                                                                                                                                                       |
-| `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      | —       | Tab and TabPanel children. Not expressible in JSON Schema; see the component types for the signature.                                                                                                         |
 
 <!-- generated:props:end -->
 

package/src/components/tabs/tabs.css

@@ -57,6 +57,7 @@
     padding: var(--cinder-space-2) var(--cinder-space-3);
     font: inherit;
     font-size: var(--cinder-text-sm);
+    font-weight: var(--cinder-font-medium);
     color: var(--cinder-text-muted);
     cursor: pointer;
     position: relative;
@@ -96,7 +97,6 @@
 
   .cinder-tab[data-cinder-active] {
     color: var(--cinder-accent-text);
-    font-weight: var(--cinder-font-medium);
   }
 
   /* Active indicator — bottom (horizontal) / right (vertical) accent stripe. */

package/src/components/tag-input/README.md

@@ -26,35 +26,35 @@ Free-form token entry field that turns committed text into removable tags while
 
 <!-- generated:props:start -->
 
-| Prop               | Type                                                                                                          | Required | Default | Description                                                                                                                |
-| ------------------ | ------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `allowDuplicates`  | `boolean`                                                                                                     | no       | —       | Allow the same trimmed tag value to appear more than once.                                                                 |
-| `aria-describedby` | `string` \| `null`                                                                                            | no       | —       | Additional description ids composed into the visible input aria-describedby chain.                                         |
-| `aria-invalid`     | `false` \| `true` \| `"true"` \| `"false"` \| `"grammar"` \| `"spelling"` \| `null`                           | no       | —       | Manual invalid-state override used when no inline validation message or FormField invalid state is active.                 |
-| `aria-label`       | `string` \| `null`                                                                                            | no       | —       | Accessible label applied when no labelled-by chain is present.                                                             |
-| `aria-labelledby`  | `string` \| `null`                                                                                            | no       | —       | Element ids that label both the text input and the committed-tag listbox.                                                  |
-| `autocapitalize`   | `"off"` \| `"on"` \| `"characters"` \| `"none"` \| `"sentences"` \| `"words"` \| `null`                       | no       | —       | Autocapitalization hint forwarded to the visible text input.                                                               |
-| `class`            | `string`                                                                                                      | no       | —       | Additional class merged onto the root element.                                                                             |
-| `defaultValue`     | `string`[]                                                                                                    | no       | —       | Initial tags for uncontrolled usage. Ignored after mount.                                                                  |
-| `disabled`         | `boolean`                                                                                                     | no       | —       | Disable the input and chip removal affordances.                                                                            |
-| `enterkeyhint`     | `"enter"` \| `"done"` \| `"go"` \| `"next"` \| `"previous"` \| `"search"` \| `"send"` \| `null`               | no       | —       | Virtual-keyboard Enter hint forwarded to the visible text input.                                                           |
-| `id`               | `string`                                                                                                      | no       | —       | Stable id for the visible text input. Falls back to FormField context or a generated id.                                   |
-| `inputmode`        | `"email"` \| `"tel"` \| `"url"` \| `"none"` \| `"search"` \| `"text"` \| `"numeric"` \| `"decimal"` \| `null` | no       | —       | Virtual-keyboard input mode forwarded to the visible text input.                                                           |
-| `max`              | `number`                                                                                                      | no       | —       | Maximum number of tags allowed. Non-finite values disable the cap.                                                         |
-| `maxlength`        | `number` \| `null`                                                                                            | no       | —       | Maximum pending-text length forwarded to the visible text input.                                                           |
-| `name`             | `string`                                                                                                      | no       | —       | Hidden input name used for native form submission; one hidden field is rendered per tag.                                   |
-| `placeholder`      | `string` \| `null`                                                                                            | no       | —       | Placeholder text shown while the pending tag input is empty.                                                               |
-| `readonly`         | `boolean`                                                                                                     | no       | —       | Render the pending-tag input as read-only and make committed tags non-removable.                                           |
-| `spellcheck`       | `false` \| `true` \| `"true"` \| `"false"` \| `null`                                                          | no       | —       | Spellcheck setting forwarded to the visible text input.                                                                    |
-| `value`            | `string`[]                                                                                                    | no       | —       | Controlled tags. When provided, the parent owns the tag array.                                                             |
-| `autocomplete`     | `(opaque)`                                                                                                    | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `delimiter`        | `(opaque)`                                                                                                    | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `onblur`           | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onchange`         | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onfocus`          | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `oninput`          | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onkeydown`        | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `validate`         | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop               | Type                                                                                                          | Required | Default | Description                                                                                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allowDuplicates`  | `boolean`                                                                                                     | no       | —       | Allow the same trimmed tag value to appear more than once.                                                                                                 |
+| `aria-describedby` | `string` \| `null`                                                                                            | no       | —       | Additional description ids composed into the visible input aria-describedby chain.                                                                         |
+| `aria-invalid`     | `false` \| `true` \| `"true"` \| `"false"` \| `"grammar"` \| `"spelling"` \| `null`                           | no       | —       | Manual invalid-state override used when no inline validation message or FormField invalid state is active.                                                 |
+| `aria-label`       | `string` \| `null`                                                                                            | no       | —       | Accessible label applied when no labelled-by chain is present.                                                                                             |
+| `aria-labelledby`  | `string` \| `null`                                                                                            | no       | —       | Element ids that label both the text input and the committed-tag listbox.                                                                                  |
+| `autocapitalize`   | `"off"` \| `"on"` \| `"characters"` \| `"none"` \| `"sentences"` \| `"words"` \| `null`                       | no       | —       | Autocapitalization hint forwarded to the visible text input.                                                                                               |
+| `class`            | `string`                                                                                                      | no       | —       | Additional class merged onto the root element.                                                                                                             |
+| `defaultValue`     | `string`[]                                                                                                    | no       | —       | Initial tags for uncontrolled usage. Ignored after mount.                                                                                                  |
+| `disabled`         | `boolean`                                                                                                     | no       | —       | Disable the input and chip removal affordances.                                                                                                            |
+| `enterkeyhint`     | `"enter"` \| `"done"` \| `"go"` \| `"next"` \| `"previous"` \| `"search"` \| `"send"` \| `null`               | no       | —       | Virtual-keyboard Enter hint forwarded to the visible text input.                                                                                           |
+| `id`               | `string`                                                                                                      | no       | —       | Stable id for the visible text input. Falls back to FormField context or a generated id.                                                                   |
+| `inputmode`        | `"email"` \| `"tel"` \| `"url"` \| `"none"` \| `"search"` \| `"text"` \| `"numeric"` \| `"decimal"` \| `null` | no       | —       | Virtual-keyboard input mode forwarded to the visible text input.                                                                                           |
+| `max`              | `number`                                                                                                      | no       | —       | Maximum number of tags allowed. Non-finite values disable the cap.                                                                                         |
+| `maxlength`        | `number` \| `null`                                                                                            | no       | —       | Maximum pending-text length forwarded to the visible text input.                                                                                           |
+| `name`             | `string`                                                                                                      | no       | —       | Hidden input name used for native form submission; one hidden field is rendered per tag.                                                                   |
+| `placeholder`      | `string` \| `null`                                                                                            | no       | —       | Placeholder text shown while the pending tag input is empty.                                                                                               |
+| `readonly`         | `boolean`                                                                                                     | no       | —       | Render the pending-tag input as read-only and make committed tags non-removable.                                                                           |
+| `spellcheck`       | `false` \| `true` \| `"true"` \| `"false"` \| `null`                                                          | no       | —       | Spellcheck setting forwarded to the visible text input.                                                                                                    |
+| `value`            | `string`[]                                                                                                    | no       | —       | Controlled tags. When provided, the parent owns the tag array.                                                                                             |
+| `autocomplete`     | `(opaque)`                                                                                                    | no       | —       | Autocomplete hint forwarded to the visible text input. Not expressible in JSON Schema; see the component types for the signature.                          |
+| `delimiter`        | `(opaque)`                                                                                                    | no       | —       | Key that commits the current input into a tag. Enter always commits separately. Not expressible in JSON Schema; see the component types for the signature. |
+| `onblur`           | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                 |
+| `onchange`         | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                 |
+| `onfocus`          | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                 |
+| `oninput`          | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                 |
+| `onkeydown`        | `(opaque)`                                                                                                    | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                 |
+| `validate`         | `(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 -->
 

package/src/components/tag-input/tag-input.css

@@ -77,9 +77,9 @@
     max-inline-size: 100%;
     padding-inline: var(--cinder-space-2);
     padding-block: var(--cinder-space-1);
-    border: 1px solid var(--cinder-border-muted);
+    border: 1px solid var(--cinder-border);
     border-radius: var(--cinder-radius-full);
-    background: var(--cinder-surface-inset);
+    background: color-mix(in oklch, var(--cinder-surface-inset), var(--cinder-surface) 60%);
     color: var(--cinder-text);
     cursor: default;
   }

package/src/components/tag-input/tag-input.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic tag input",
       "description": "Commit free-form tags with Enter or a comma delimiter.",
-      "code": "<script lang=\"ts\">\n  import { FormField, TagInput } from '@lostgradient/cinder';\n</script>\n\n<FormField\n  id=\"basic-tag-input\"\n  label=\"Topics\"\n  description=\"Press Enter or comma to turn the current text into a tag.\"\n>\n  <TagInput placeholder=\"Add a topic…\" />\n</FormField>\n"
+      "code": "<script lang=\"ts\">\n  import { FormField, TagInput } from '@lostgradient/cinder';\n\n</script>\n\n<FormField\n  id=\"field\"\n  label=\"Topics\"\n  description=\"Press Enter or comma to turn the current text into a tag.\"\n>\n  <TagInput placeholder=\"Add a topic…\" />\n</FormField>\n"
     },
     {
       "id": "disabled",
@@ -27,6 +27,12 @@
       "description": "Start uncontrolled with existing tags and keep editing in place.",
       "code": "<script lang=\"ts\">\n  import { FormField, TagInput } from '@lostgradient/cinder';\n</script>\n\n<FormField\n  id=\"prepopulated-tag-input\"\n  label=\"Technologies\"\n  description=\"Review the initial stack and remove anything that does not apply.\"\n>\n  <TagInput defaultValue={['Svelte', 'Bun', 'TypeScript']} placeholder=\"Add a technology…\" />\n</FormField>\n"
     },
+    {
+      "id": "readonly",
+      "title": "Read-only tags",
+      "description": "With `readonly`, the committed tags stay visible but cannot be removed and the pending-tag input rejects new entries — distinct from `disabled`, which also dims the whole control.",
+      "code": "<script lang=\"ts\">\n  import { FormField, TagInput } from '@lostgradient/cinder';\n</script>\n\n<FormField\n  id=\"readonly-tag-input\"\n  label=\"Applied filters\"\n  description=\"These filters are fixed for this report and cannot be edited.\"\n>\n  <TagInput readonly defaultValue={['Svelte', 'Bun', 'TypeScript']} />\n</FormField>\n"
+    },
     {
       "id": "validation",
       "title": "Validated email tags",

package/src/components/tag-input/tag-input.svelte

@@ -25,6 +25,7 @@
     composeDescribedBy,
     resolveFieldControl,
   } from '../../_internal/field-control.ts';
+  import VisuallyHiddenLiveRegion from '../_visually-hidden-live-region.svelte';
   import { getFormFieldContext } from '../../_internal/form-field-context.ts';
   import { classNames } from '../../utilities/class-names.ts';
   import { handleRovingKeydown, isRovingKey } from '../../utilities/roving-tabindex.ts';
@@ -69,6 +70,16 @@
   let inlineError = $state<string | null>(null);
   let uncontrolledTags = $state(initialDefaultTags);
   let focusedChipIndex = $state(-1);
+  let statusAnnouncement = $state('');
+  // Bumped on every announce so the live region re-fires even when two consecutive
+  // announcements share the same text (e.g. adding the same tag again) — a same-value
+  // `$state` assignment is a no-op in Svelte 5 and would otherwise be swallowed.
+  let statusAnnouncementSequence = $state(0);
+
+  function announceStatus(announcement: string): void {
+    statusAnnouncement = announcement;
+    statusAnnouncementSequence += 1;
+  }
 
   const isControlled = $derived(value !== undefined);
   const currentTags = $derived(isControlled ? (value ?? []) : uncontrolledTags);
@@ -228,14 +239,17 @@
     draftValue = '';
     focusedChipIndex = -1;
     setTags([...currentTags, candidate]);
+    announceStatus(`${candidate} added.`);
     return true;
   }
 
   function removeTag(index: number): void {
     if (field.disabled || resolvedReadonly) return;
     inlineError = null;
+    const removed = currentTags[index] ?? '';
     const nextTags = currentTags.filter((_, candidateIndex) => candidateIndex !== index);
     setTags(nextTags);
+    if (removed) announceStatus(`${removed} removed.`);
   }
 
   function focusAfterRemove(index: number): void {
@@ -416,4 +430,8 @@
       <input type="hidden" {name} value={tag} disabled={field.disabled} />
     {/each}
   {/if}
+  <VisuallyHiddenLiveRegion
+    message={statusAnnouncement}
+    announcementSequence={statusAnnouncementSequence}
+  />
 </div>

package/src/components/textarea/README.md

@@ -23,10 +23,12 @@ Multi-line text input for longer freeform content with optional resize control.
 | `error`       | `string`   | no       | —       | Validation error message; sets `aria-invalid="true"` and `aria-describedby`.                                                                                                                                                                                                                                                                           |
 | `id`          | `string`   | yes      | —       | Unique identifier — required for label association and ARIA wiring.                                                                                                                                                                                                                                                                                    |
 | `label`       | `string`   | no       | —       | Visible label rendered in a `<label>` element associated via `for`.                                                                                                                                                                                                                                                                                    |
+| `maxlength`   | `number`   | no       | —       | Maximum character count. Passed through to the native `maxlength` attribute and shown as the limit in the `showCount` counter.                                                                                                                                                                                                                         |
+| `required`    | `boolean`  | no       | —       | Marks the field as required. Passed through to the native `required` attribute.                                                                                                                                                                                                                                                                        |
 | `rows`        | `number`   | no       | —       | Number of visible text rows. Defaults to 4.                                                                                                                                                                                                                                                                                                            |
 | `showCount`   | `boolean`  | no       | —       | When `true` AND `maxlength` is set, renders a live character counter (`{value.length}/{maxlength}`) below the textarea. The counter element is wired into `aria-describedby` so screen readers announce it as part of the field's description, and it is also placed inside an `aria-live="polite"` region so updates are announced as the user types. |
-| `class`       | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                |
-| `value`       | `(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-textarea`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                           |
+| `value`       | `(opaque)` | no       | —       | Bound value of the textarea. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                |
 
 <!-- generated:props:end -->
 

package/src/components/textarea/textarea.css

@@ -93,6 +93,7 @@
   }
 
   .cinder-textarea[aria-invalid='true']:focus-visible {
+    border-color: transparent;
     box-shadow:
       0 0 0 var(--cinder-ring-offset) var(--cinder-ring-offset-color),
       0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width)) var(--cinder-danger);

package/src/components/textarea/textarea.examples.json

@@ -7,7 +7,25 @@
       "id": "basic",
       "title": "Basic textarea",
       "description": "Multi-line text input with label and bound value.",
-      "code": "<script lang=\"ts\">\n  import { Textarea } from '@lostgradient/cinder/textarea';\n  let bio = $state('');\n</script>\n\n<Textarea\n  id=\"bio\"\n  bind:value={bio}\n  label=\"Bio\"\n  description=\"Tell us a little about yourself.\"\n  placeholder=\"I'm a designer who…\"\n/>\n{#if bio.length > 0}\n  <p style=\"margin-top: 0.5rem; color: var(--cinder-text-muted);\">{bio.length} characters</p>\n{/if}\n"
+      "code": "<script lang=\"ts\">\n  import { Textarea } from '@lostgradient/cinder/textarea';\n\n  let bio = $state('');\n</script>\n\n<Textarea\n  id=\"field\"\n  bind:value={bio}\n  label=\"Bio\"\n  description=\"Tell us a little about yourself.\"\n  placeholder=\"I'm a designer who…\"\n/>\n{#if bio.length > 0}\n  <p style=\"margin-top: 0.5rem; color: var(--cinder-text-muted);\">{bio.length} characters</p>\n{/if}\n"
+    },
+    {
+      "id": "disabled",
+      "title": "Disabled textarea",
+      "description": "A disabled textarea is dimmed and non-editable; its value is still shown so context is preserved while editing is locked.",
+      "code": "<script lang=\"ts\">\n  import { Textarea } from '@lostgradient/cinder/textarea';\n\n</script>\n\n<Textarea\n  id=\"field\"\n  value=\"This account note is read-only and managed by your administrator.\"\n  label=\"Account note\"\n  description=\"Contact an administrator to change this.\"\n  disabled\n/>\n"
+    },
+    {
+      "id": "required",
+      "title": "Required textarea",
+      "description": "Setting `required` forwards the native `required` attribute, which browsers expose as `aria-required=\"true\"` and enforce during form submission.",
+      "code": "<script lang=\"ts\">\n  import { Textarea } from '@lostgradient/cinder/textarea';\n\n  let message = $state('');\n</script>\n\n<Textarea\n  id=\"field\"\n  bind:value={message}\n  label=\"Message\"\n  description=\"This field is required.\"\n  required\n/>\n"
+    },
+    {
+      "id": "with-character-count",
+      "title": "Live character counter",
+      "description": "Set `showCount` together with `maxlength` to render a live `{used}/{limit}` counter below the field that updates as the user types.",
+      "code": "<script lang=\"ts\">\n  import { Textarea } from '@lostgradient/cinder/textarea';\n\n  let summary = $state('A short product summary.');\n</script>\n\n<Textarea\n  id=\"field\"\n  bind:value={summary}\n  label=\"Summary\"\n  description=\"Keep it under 200 characters.\"\n  showCount\n  maxlength={200}\n/>\n"
     },
     {
       "id": "with-error",

package/src/components/textarea/textarea.types.ts

@@ -12,6 +12,16 @@ export type TextareaProps = HTMLTextareaAttributes & {
   error?: string;
   /** Number of visible text rows. Defaults to 4. */
   rows?: number;
+  // `required` and `maxlength` redeclare inherited `HTMLTextareaAttributes` keys,
+  // deliberately narrowing them from `… | null` to clean `boolean` / `number`. The
+  // native "remove the attribute" `null` is noise in the documented prop surface
+  // (this mirrors how `rows` above narrows its inherited type). Both props are
+  // explicitly destructured in textarea.svelte, so the narrowed type is the only
+  // accepted shape — there is no `...rest` escape hatch. textarea.test.ts pins this.
+  /** Marks the field as required. Passed through to the native `required` attribute. */
+  required?: boolean;
+  /** Maximum character count. Passed through to the native `maxlength` attribute and shown as the limit in the `showCount` counter. */
+  maxlength?: number;
   /** Disables the textarea. */
   disabled?: boolean;
   /** Extra class names merged with `.cinder-textarea`. */

package/src/components/timeline/README.md

@@ -39,16 +39,18 @@ Marker snippets are decorative. Do not place focusable or interactive content in
 
 <!-- generated:props:start -->
 
-| Prop                  | Type                                                                                                                                                              | Required | Default      | Description                                                                         |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ----------------------------------------------------------------------------------- |
-| `class`               | `string`                                                                                                                                                          | no       | —            | Additional class names merged with `.cinder-timeline`.                              |
-| `entries`             | ({ datetime: `string`; groupLabel?: `string`; id: `string`; timestamp: `string`; title: `string`; tone?: `"info"` \| `"success"` \| `"warning"` \| `"error"` })[] | yes      | —            | Timeline entries rendered in source order.                                          |
-| `gapThresholdMinutes` | `number`                                                                                                                                                          | no       | —            | Hide the following connector when adjacent valid timestamps exceed this gap.        |
-| `groupBy`             | `"none"` \| `"day"` \| `"week"`                                                                                                                                   | no       | `"none"`     | Optional adjacent UTC day/week grouping mode.                                       |
-| `groupHeaderLevel`    | `1` \| `2` \| `3` \| `4` \| `5` \| `6`                                                                                                                            | no       | `3`          | Heading level applied to rendered group headers.                                    |
-| `label`               | `string`                                                                                                                                                          | no       | —            | Fallback accessible label used only when aria-label and aria-labelledby are absent. |
-| `orientation`         | `"vertical"` \| `"horizontal"`                                                                                                                                    | no       | `"vertical"` | Layout orientation.                                                                 |
-| `weekStartsOn`        | `"sunday"` \| `"monday"`                                                                                                                                          | no       | `"monday"`   | Week start used for UTC week grouping.                                              |
+| Prop                  | Type                                                                                                                                                              | Required | Default      | Description                                                                                                                                               |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`               | `string`                                                                                                                                                          | no       | —            | Additional class names merged with `.cinder-timeline`.                                                                                                    |
+| `entries`             | ({ datetime: `string`; groupLabel?: `string`; id: `string`; timestamp: `string`; title: `string`; tone?: `"info"` \| `"success"` \| `"warning"` \| `"error"` })[] | yes      | —            | Timeline entries rendered in source order.                                                                                                                |
+| `gapThresholdMinutes` | `number`                                                                                                                                                          | no       | —            | Hide the following connector when adjacent valid timestamps exceed this gap (in minutes).                                                                 |
+| `groupBy`             | `"none"` \| `"day"` \| `"week"`                                                                                                                                   | no       | `"none"`     | Optional adjacent UTC day/week grouping mode.                                                                                                             |
+| `groupHeaderLevel`    | `1` \| `2` \| `3` \| `4` \| `5` \| `6`                                                                                                                            | no       | `3`          | Heading level applied to rendered group headers.                                                                                                          |
+| `label`               | `string`                                                                                                                                                          | no       | —            | Fallback accessible label used only when aria-label and aria-labelledby are absent.                                                                       |
+| `orientation`         | `"vertical"` \| `"horizontal"`                                                                                                                                    | no       | `"vertical"` | Layout orientation.                                                                                                                                       |
+| `weekStartsOn`        | `"sunday"` \| `"monday"`                                                                                                                                          | no       | `"monday"`   | Week start used for UTC week grouping.                                                                                                                    |
+| `children`            | `(opaque)`                                                                                                                                                        | no       | —            | Optional per-entry body content. Not expressible in JSON Schema; see the component types for the signature.                                               |
+| `marker`              | `(opaque)`                                                                                                                                                        | no       | —            | Decorative per-entry marker content. Must not contain interactive descendants. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/timeline/timeline.css

@@ -8,7 +8,23 @@
   .cinder-timeline {
     --_cinder-timeline-rail-size: 1.5rem;
     --_cinder-timeline-marker-size: 0.875rem;
-    --_cinder-timeline-rail-center: 0.6875rem;
+    /* The marker is an inline-flex box of --_cinder-timeline-marker-size, laid out at
+       the inline-start of the rail grid cell, with a margin-top of --cinder-space-1.
+       Its center therefore sits at half the marker size from the cell origin (X) and
+       at margin-top + half the marker size from the item's top (Y). The connector is
+       positioned from these.
+
+       This holds for custom markers because the marker box is FIXED-SIZE: the
+       `.cinder-timeline-item__marker` rule pins width/height to this variable and
+       centers content with inline-flex, so a custom `marker` snippet FILLS the box
+       (a glyph, an icon) rather than resizing it. The connector is therefore always
+       anchored to a known marker center, not to content-dependent geometry. A
+       consumer who needs a larger marker overrides --_cinder-timeline-marker-size,
+       which moves the box and the connector together. */
+    --_cinder-timeline-marker-center-x: calc(var(--_cinder-timeline-marker-size) / 2);
+    --_cinder-timeline-marker-center-y: calc(
+      var(--cinder-space-1) + var(--_cinder-timeline-marker-size) / 2
+    );
 
     list-style: none;
     margin: 0;
@@ -38,6 +54,7 @@
     display: grid;
     grid-template-columns: var(--_cinder-timeline-rail-size) 1fr;
     gap: var(--cinder-space-3);
+    position: relative;
   }
 
   .cinder-timeline__group-header {
@@ -50,18 +67,33 @@
     text-transform: uppercase;
   }
 
-  /* Connecting line between items */
-  .cinder-timeline-item::before {
+  /* Connecting line between items. It is anchored to the event row, not the
+     list item, so optional group headers above the event cannot offset it away
+     from the marker. The line spans THIS marker's center to the NEXT marker's
+     center so it terminates cleanly at each dot with no stub gap.
+
+     The bottom offset is measured from the event box's bottom edge down to the
+     next item's marker center. That distance is three tokens, not two:
+       - the item's padding-bottom (space-4) below the event box, plus
+       - the marker's own margin-top (space-1) inside the next event grid, plus
+       - the next marker's center-y within its event box (marker-center-y).
+     The earlier formula omitted the marker margin-top (space-1), so every
+     segment fell exactly space-1 short of the next dot. Verified in the browser:
+     with this offset the line's painted endpoints land on the marker centers
+     (a 63px inter-marker rhythm at the default token scale). */
+  .cinder-timeline-item__event::before {
     content: '';
     position: absolute;
-    left: var(--_cinder-timeline-rail-center);
-    top: 1rem;
-    bottom: 0;
+    left: var(--_cinder-timeline-marker-center-x);
+    top: var(--_cinder-timeline-marker-center-y);
+    bottom: calc(
+      -1 * (var(--cinder-space-4) + var(--cinder-space-1) + var(--_cinder-timeline-marker-center-y))
+    );
     width: 1px;
     background: var(--cinder-border-muted);
   }
 
-  .cinder-timeline-item[data-cinder-connector-after='hidden']::before {
+  .cinder-timeline-item[data-cinder-connector-after='hidden'] .cinder-timeline-item__event::before {
     display: none;
   }
 
@@ -136,7 +168,7 @@
     margin: 0 0 var(--cinder-space-2);
   }
 
-  .cinder-timeline[data-cinder-orientation='horizontal'] .cinder-timeline-item::before {
+  .cinder-timeline[data-cinder-orientation='horizontal'] .cinder-timeline-item__event::before {
     left: calc(var(--_cinder-timeline-marker-size) / 2);
     right: calc(-1 * var(--cinder-space-4));
     top: calc(var(--_cinder-timeline-marker-size) / 2 + var(--cinder-space-1));

package/src/components/timeline/timeline.examples.json

@@ -7,19 +7,25 @@
       "id": "custom-dot-styles",
       "title": "Custom dot styles",
       "description": "A timeline with decorative marker snippets for each tone.",
-      "code": "<script lang=\"ts\">\n  import Timeline from '@lostgradient/cinder/timeline';\n\n  const entries = [\n    {\n      id: 'green',\n      datetime: '2026-05-23T13:00:00Z',\n      timestamp: '8:00 AM',\n      title: 'Health check passed',\n      tone: 'success' as const,\n    },\n    {\n      id: 'yellow',\n      datetime: '2026-05-23T13:05:00Z',\n      timestamp: '8:05 AM',\n      title: 'Capacity warning',\n      tone: 'warning' as const,\n    },\n    {\n      id: 'red',\n      datetime: '2026-05-23T13:12:00Z',\n      timestamp: '8:12 AM',\n      title: 'Rollback triggered',\n      tone: 'error' as const,\n    },\n  ];\n</script>\n\n<Timeline {entries} label=\"Incident timeline\">\n  {#snippet marker(entry)}\n    {entry.tone === 'success' ? '+' : entry.tone === 'warning' ? '!' : 'x'}\n  {/snippet}\n\n  {#snippet children(entry)}\n    {entry.title}\n  {/snippet}\n</Timeline>\n"
+      "code": "<script lang=\"ts\">\n  import Timeline from '@lostgradient/cinder/timeline';\n\n  const entries = [\n    {\n      id: 'green',\n      datetime: '2026-05-23T13:00:00Z',\n      timestamp: '8:00 AM',\n      title: 'Health check passed',\n      tone: 'success' as const,\n    },\n    {\n      id: 'yellow',\n      datetime: '2026-05-23T13:05:00Z',\n      timestamp: '8:05 AM',\n      title: 'Capacity warning',\n      tone: 'warning' as const,\n    },\n    {\n      id: 'red',\n      datetime: '2026-05-23T13:12:00Z',\n      timestamp: '8:12 AM',\n      title: 'Rollback triggered',\n      tone: 'error' as const,\n    },\n  ];\n\n  const details: Record<string, string> = {\n    green: 'All probes returned healthy responses across the deployment target.',\n    yellow: 'Projected load crossed the warning threshold for the current pool.',\n    red: 'Rollback automation started after error rates continued climbing.',\n  };\n</script>\n\n<Timeline {entries} label=\"Incident timeline\">\n  {#snippet marker(entry)}\n    {entry.tone === 'success' ? '+' : entry.tone === 'warning' ? '!' : 'x'}\n  {/snippet}\n\n  {#snippet children(entry)}\n    {details[entry.id]}\n  {/snippet}\n</Timeline>\n"
+    },
+    {
+      "id": "gap-threshold",
+      "title": "Gap threshold",
+      "description": "With `gapThresholdMinutes`, the connector after an entry is hidden when the next entry is more than that many minutes away — visually breaking the line across large time gaps.",
+      "code": "<script lang=\"ts\">\n  import Timeline from '@lostgradient/cinder/timeline';\n\n  const entries = [\n    {\n      id: 'deploy-start',\n      datetime: '2026-05-18T09:00:00Z',\n      timestamp: '9:00 AM',\n      title: 'Deploy started',\n      tone: 'info' as const,\n    },\n    {\n      id: 'deploy-done',\n      datetime: '2026-05-18T09:12:00Z',\n      timestamp: '9:12 AM',\n      title: 'Deploy completed',\n      tone: 'success' as const,\n    },\n    {\n      id: 'incident',\n      datetime: '2026-05-18T14:45:00Z',\n      timestamp: '2:45 PM',\n      title: 'Incident reported',\n      tone: 'warning' as const,\n    },\n  ];\n\n  const details: Record<string, string> = {\n    'deploy-start': 'Release automation began applying the candidate build.',\n    'deploy-done': 'Health checks passed and the candidate was promoted.',\n    incident: 'Support detected a separate issue later in the day.',\n  };\n</script>\n\n<Timeline {entries} gapThresholdMinutes={60} label=\"Release timeline\">\n  {#snippet children(entry)}\n    {details[entry.id]}\n  {/snippet}\n</Timeline>\n"
     },
     {
       "id": "grouped-by-day",
       "title": "Grouped by day",
       "description": "A timeline grouped by UTC day while preserving source order.",
-      "code": "<script lang=\"ts\">\n  import Timeline from '@lostgradient/cinder/timeline';\n\n  const entries = [\n    {\n      id: 'monday-1',\n      datetime: '2026-05-18T15:00:00Z',\n      timestamp: '9:00 AM',\n      title: 'Candidate opened',\n      groupLabel: 'Monday, May 18',\n      tone: 'info' as const,\n    },\n    {\n      id: 'monday-2',\n      datetime: '2026-05-18T17:30:00Z',\n      timestamp: '11:30 AM',\n      title: 'Review completed',\n      tone: 'success' as const,\n    },\n    {\n      id: 'tuesday-1',\n      datetime: '2026-05-19T16:15:00Z',\n      timestamp: '10:15 AM',\n      title: 'Production rollout paused',\n      groupLabel: 'Tuesday, May 19',\n      tone: 'warning' as const,\n    },\n  ];\n</script>\n\n<Timeline {entries} groupBy=\"day\" gapThresholdMinutes={90} label=\"Review timeline\">\n  {#snippet children(entry)}\n    {entry.title}\n  {/snippet}\n</Timeline>\n"
+      "code": "<script lang=\"ts\">\n  import Timeline from '@lostgradient/cinder/timeline';\n\n  const entries = [\n    {\n      id: 'monday-1',\n      datetime: '2026-05-18T15:00:00Z',\n      timestamp: '9:00 AM',\n      title: 'Candidate opened',\n      groupLabel: 'Monday, May 18',\n      tone: 'info' as const,\n    },\n    {\n      id: 'monday-2',\n      datetime: '2026-05-18T17:30:00Z',\n      timestamp: '11:30 AM',\n      title: 'Review completed',\n      tone: 'success' as const,\n    },\n    {\n      id: 'tuesday-1',\n      datetime: '2026-05-19T16:15:00Z',\n      timestamp: '10:15 AM',\n      title: 'Production rollout paused',\n      groupLabel: 'Tuesday, May 19',\n      tone: 'warning' as const,\n    },\n  ];\n\n  const details: Record<string, string> = {\n    'monday-1': 'The release candidate was opened for reviewer feedback.',\n    'monday-2': 'Required approvals landed and the candidate moved forward.',\n    'tuesday-1': 'Rollout paused while capacity warnings were investigated.',\n  };\n</script>\n\n<Timeline {entries} groupBy=\"day\" gapThresholdMinutes={90} label=\"Review timeline\">\n  {#snippet children(entry)}\n    {details[entry.id]}\n  {/snippet}\n</Timeline>\n"
     },
     {
       "id": "horizontal",
       "title": "Horizontal timeline",
       "description": "A compact horizontal timeline for phase comparisons.",
-      "code": "<script lang=\"ts\">\n  import Timeline from '@lostgradient/cinder/timeline';\n\n  const entries = [\n    {\n      id: 'intake',\n      datetime: '2026-05-20',\n      timestamp: 'May 20',\n      title: 'Intake',\n      tone: 'info' as const,\n    },\n    {\n      id: 'design',\n      datetime: '2026-05-21',\n      timestamp: 'May 21',\n      title: 'Design review',\n      tone: 'success' as const,\n    },\n    {\n      id: 'ship',\n      datetime: '2026-05-23',\n      timestamp: 'May 23',\n      title: 'Ship candidate',\n      tone: 'warning' as const,\n    },\n  ];\n</script>\n\n<Timeline {entries} orientation=\"horizontal\" label=\"Project phase timeline\">\n  {#snippet children(entry)}\n    {entry.title}\n  {/snippet}\n</Timeline>\n"
+      "code": "<script lang=\"ts\">\n  import Timeline from '@lostgradient/cinder/timeline';\n\n  const entries = [\n    {\n      id: 'intake',\n      datetime: '2026-05-20',\n      timestamp: 'May 20',\n      title: 'Intake',\n      tone: 'info' as const,\n    },\n    {\n      id: 'design',\n      datetime: '2026-05-21',\n      timestamp: 'May 21',\n      title: 'Design review',\n      tone: 'success' as const,\n    },\n    {\n      id: 'ship',\n      datetime: '2026-05-23',\n      timestamp: 'May 23',\n      title: 'Ship candidate',\n      tone: 'warning' as const,\n    },\n  ];\n\n  const details: Record<string, string> = {\n    intake: 'Requirements and constraints were collected.',\n    design: 'The selected approach passed design review.',\n    ship: 'Release validation is waiting on final checks.',\n  };\n</script>\n\n<Timeline {entries} orientation=\"horizontal\" label=\"Project phase timeline\">\n  {#snippet children(entry)}\n    {details[entry.id]}\n  {/snippet}\n</Timeline>\n"
     },
     {
       "id": "vertical",

package/src/components/timeline/timeline.svelte

@@ -11,7 +11,7 @@
    * @useWhen Displaying workflow steps, audit logs, or run histories where each entry needs connector continuity or gap breaks.
    * @avoidWhen Surfacing a real-time social or activity stream — feed is the higher-affordance composition.
    * @avoidWhen Guiding users through a numbered procedural flow — steps conveys progress more clearly.
-   * @related timeline-item, feed, steps
+   * @related feed, steps
    */
   export type {
     TimelineEntry,
@@ -26,11 +26,14 @@
 
 <script lang="ts">
   import { classNames } from '../../utilities/class-names.ts';
-  import TimelineItem from '../timeline-item/timeline-item.svelte';
+  import TimelineItem from '../_timeline-item/timeline-item.svelte';
   import { buildTimelineRenderPlan } from './timeline-groups.ts';
   import type { TimelineProps } from './timeline.types.ts';
 
-  type TimelineInternalProps = TimelineProps & { role?: unknown };
+  // The public TimelineProps omits `role`; this internal slot exists only so the
+  // `role: _role` destructure below can strip a role injected through an untyped
+  // spread, preserving the `<ol>`'s implicit `list` role for assistive technology.
+  type TimelineInternalProps = TimelineProps & { role?: never };
 
   let {
     entries,

package/src/components/timeline/timeline.types.ts

@@ -44,7 +44,7 @@ export type TimelineProps = Omit<
   weekStartsOn?: TimelineWeekStartsOn | undefined;
   /** Heading level applied to rendered group headers. @default 3 */
   groupHeaderLevel?: TimelineHeadingLevel | undefined;
-  /** Hide the following connector when adjacent valid timestamps exceed this gap. */
+  /** Hide the following connector when adjacent valid timestamps exceed this gap (in minutes). */
   gapThresholdMinutes?: number | undefined;
   /** Fallback accessible label used only when aria-label and aria-labelledby are absent. */
   label?: string | undefined;
@@ -71,7 +71,7 @@ export interface TimelineSchemaProps {
   weekStartsOn?: TimelineWeekStartsOn | undefined;
   /** Heading level applied to rendered group headers. @default 3 */
   groupHeaderLevel?: TimelineHeadingLevel | undefined;
-  /** Hide the following connector when adjacent valid timestamps exceed this gap. */
+  /** Hide the following connector when adjacent valid timestamps exceed this gap (in minutes). */
   gapThresholdMinutes?: number | undefined;
   /** Fallback accessible label used only when aria-label and aria-labelledby are absent. */
   label?: string | undefined;

package/src/components/toast-region/README.md

@@ -16,13 +16,13 @@ ToastRegion provides live toast notifications and a `useToast()` controller for
 
 <!-- generated:props:start -->
 
-| Prop              | Type                                                                                                        | Required | Default | Description                                                                                                                |
-| ----------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`           | `string`                                                                                                    | no       | —       | Additional class names merged with `.cinder-toast-region`.                                                                 |
-| `defaultDuration` | `number`                                                                                                    | no       | —       | Default auto-dismiss duration in ms. Default 5000. Set to 0 for sticky.                                                    |
-| `maxStack`        | `number`                                                                                                    | no       | —       | Maximum simultaneous toasts in each region. Default 5.                                                                     |
-| `position`        | `"top-left"` \| `"top-center"` \| `"top-right"` \| `"bottom-left"` \| `"bottom-center"` \| `"bottom-right"` | no       | —       | Viewport anchor for both live-region channels. Default `bottom-right`.                                                     |
-| `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. |
+| Prop              | Type                                                                                                        | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`           | `string`                                                                                                    | no       | —       | Additional class names merged with `.cinder-toast-region`.                                                                                                                                                                                                                                                                                                                                               |
+| `defaultDuration` | `number`                                                                                                    | no       | —       | Default auto-dismiss duration in ms. Default 5000. Set to 0 for sticky.                                                                                                                                                                                                                                                                                                                                  |
+| `maxStack`        | `number`                                                                                                    | no       | —       | Maximum simultaneous toasts in each region. Default 5.                                                                                                                                                                                                                                                                                                                                                   |
+| `position`        | `"top-left"` \| `"top-center"` \| `"top-right"` \| `"bottom-left"` \| `"bottom-center"` \| `"bottom-right"` | no       | —       | Viewport anchor for both live-region channels. Default `bottom-right`.                                                                                                                                                                                                                                                                                                                                   |
+| `children`        | `(opaque)`                                                                                                  | no       | —       | Optional children. When provided, the region wraps them so descendants can call `useToast()` and read the region's context. Most apps mount `<ToastRegion>` as a self-closing tag at the root of their layout and leave this empty — but some patterns (modal-scoped regions, tests) benefit from explicit child composition. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->