@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/faceted-filter-bar/faceted-filter-bar.examples.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "faceted-filter-bar",
+  "import": "@lostgradient/cinder/faceted-filter-bar",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic faceted filter bar",
+      "description": "Search field with status and queue facets, applied-filter chips, and a clear-all action.",
+      "code": "<script lang=\"ts\">\n  import { FacetedFilterBar } from '@lostgradient/cinder/faceted-filter-bar';\n  import type { AppliedFilter, FacetDefinition } from '@lostgradient/cinder/faceted-filter-bar';\n\n  const facets: FacetDefinition[] = [\n    {\n      type: 'select',\n      key: 'status',\n      label: 'Status',\n      placeholder: 'All statuses',\n      options: [\n        { value: 'running', label: 'Running' },\n        { value: 'failed', label: 'Failed' },\n        { value: 'paused', label: 'Paused' },\n        { value: 'completed', label: 'Completed' },\n      ],\n    },\n    {\n      type: 'select',\n      key: 'queue',\n      label: 'Queue',\n      placeholder: 'All queues',\n      options: [\n        { value: 'default', label: 'Default' },\n        { value: 'priority', label: 'Priority' },\n        { value: 'background', label: 'Background' },\n      ],\n    },\n  ];\n\n  let appliedFilters = $state<AppliedFilter[]>([]);\n  let searchQuery = $state('');\n\n  function handleFacetChange(key: string, value: string) {\n    const facet = facets.find((f) => f.key === key);\n    if (!value) {\n      appliedFilters = appliedFilters.filter((f) => f.key !== key);\n      return;\n    }\n    appliedFilters = [\n      ...appliedFilters.filter((f) => f.key !== key),\n      { key, value, label: facet?.label ?? key },\n    ];\n  }\n\n  function handleFilterRemove(key: string) {\n    appliedFilters = appliedFilters.filter((f) => f.key !== key);\n  }\n\n  function handleClearAll() {\n    appliedFilters = [];\n    searchQuery = '';\n  }\n</script>\n\n<FacetedFilterBar\n  aria-label=\"Workflow filters\"\n  {facets}\n  {appliedFilters}\n  {searchQuery}\n  searchPlaceholder=\"Search workflows…\"\n  onsearchchange={(q) => (searchQuery = q)}\n  onfacetchange={handleFacetChange}\n  onfilterremove={handleFilterRemove}\n  onclearall={handleClearAll}\n/>\n"
+    },
+    {
+      "id": "disabled",
+      "title": "Disabled state",
+      "description": "All controls are disabled when disabled=true — selects, chips, and the clear-all button.",
+      "code": "<script lang=\"ts\">\n  import { FacetedFilterBar } from '@lostgradient/cinder/faceted-filter-bar';\n  import type { FacetDefinition } from '@lostgradient/cinder/faceted-filter-bar';\n\n  const facets: FacetDefinition[] = [\n    {\n      type: 'select',\n      key: 'status',\n      label: 'Status',\n      placeholder: 'All statuses',\n      options: [\n        { value: 'running', label: 'Running' },\n        { value: 'failed', label: 'Failed' },\n      ],\n    },\n  ];\n</script>\n\n<FacetedFilterBar\n  aria-label=\"Disabled filter bar\"\n  {facets}\n  appliedFilters={[{ key: 'status', value: 'failed', label: 'Status' }]}\n  disabled\n/>\n"
+    },
+    {
+      "id": "workflow-list",
+      "title": "Workflow list filters",
+      "description": "Status, failure category, queue, and workflow type facets for a dense operational workflow list view.",
+      "code": "<script lang=\"ts\">\n  import { FacetedFilterBar } from '@lostgradient/cinder/faceted-filter-bar';\n  import type { AppliedFilter, FacetDefinition } from '@lostgradient/cinder/faceted-filter-bar';\n\n  const facets: FacetDefinition[] = [\n    {\n      type: 'select',\n      key: 'status',\n      label: 'Status',\n      placeholder: 'All statuses',\n      options: [\n        { value: 'running', label: 'Running' },\n        { value: 'failed', label: 'Failed' },\n        { value: 'paused', label: 'Paused' },\n        { value: 'scheduled', label: 'Scheduled' },\n        { value: 'completed', label: 'Completed' },\n      ],\n    },\n    {\n      type: 'select',\n      key: 'failure_category',\n      label: 'Failure category',\n      placeholder: 'All categories',\n      options: [\n        { value: 'timeout', label: 'Timeout' },\n        { value: 'network', label: 'Network error' },\n        { value: 'resource', label: 'Resource exhausted' },\n        { value: 'logic', label: 'Logic error' },\n      ],\n    },\n    {\n      type: 'select',\n      key: 'queue',\n      label: 'Queue',\n      placeholder: 'All queues',\n      options: [\n        { value: 'default', label: 'Default' },\n        { value: 'priority', label: 'Priority' },\n        { value: 'background', label: 'Background' },\n        { value: 'scheduled', label: 'Scheduled' },\n      ],\n    },\n    {\n      type: 'select',\n      key: 'workflow_type',\n      label: 'Workflow type',\n      placeholder: 'All types',\n      options: [\n        { value: 'data_pipeline', label: 'Data pipeline' },\n        { value: 'notification', label: 'Notification' },\n        { value: 'sync', label: 'Sync' },\n        { value: 'report', label: 'Report' },\n      ],\n    },\n  ];\n\n  let appliedFilters = $state<AppliedFilter[]>([\n    { key: 'status', value: 'failed', label: 'Status' },\n  ]);\n  let searchQuery = $state('');\n\n  function handleFacetChange(key: string, value: string) {\n    const facet = facets.find((f) => f.key === key);\n    if (!value) {\n      appliedFilters = appliedFilters.filter((f) => f.key !== key);\n      return;\n    }\n    appliedFilters = [\n      ...appliedFilters.filter((f) => f.key !== key),\n      { key, value, label: facet?.label ?? key },\n    ];\n  }\n\n  function handleFilterRemove(key: string) {\n    appliedFilters = appliedFilters.filter((f) => f.key !== key);\n  }\n\n  function handleClearAll() {\n    appliedFilters = [];\n    searchQuery = '';\n  }\n</script>\n\n<FacetedFilterBar\n  aria-label=\"Workflow list filters\"\n  {facets}\n  {appliedFilters}\n  {searchQuery}\n  searchPlaceholder=\"Search by workflow name or ID…\"\n  onsearchchange={(q) => (searchQuery = q)}\n  onfacetchange={handleFacetChange}\n  onfilterremove={handleFilterRemove}\n  onclearall={handleClearAll}\n/>\n"
+    }
+  ]
+}

package/src/components/faceted-filter-bar/faceted-filter-bar.svelte

@@ -0,0 +1,193 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category form
+   * @status beta
+   * @purpose Composed filtering toolbar with search, select facets, applied-filter chips, and clear-all for dense operational list views.
+   * @tag form
+   * @tag filter
+   * @useWhen Filtering a list or table by multiple dimensions such as status, category, and queue simultaneously.
+   * @useWhen Showing applied filters as removable chips so users can see and undo active constraints.
+   * @avoidWhen A single search field or one select is sufficient — compose SearchField or Select directly.
+   * @avoidWhen Filtering navigates to a new page — the bar owns no routing or persistence.
+   * @related search-field, chip, select, toolbar
+   */
+  export type {
+    AppliedFilter,
+    CustomFacet,
+    FacetDefinition,
+    FacetedFilterBarProps,
+    FacetOption,
+    SelectFacet,
+  } from './faceted-filter-bar.types.ts';
+</script>
+
+<script lang="ts">
+  import VisuallyHiddenLiveRegion from '../_visually-hidden-live-region.svelte';
+  import SearchField from '../search-field/search-field.svelte';
+  import Chip from '../chip/chip.svelte';
+  import Button from '../button/button.svelte';
+  import { classNames } from '../../utilities/class-names.ts';
+
+  import type { FacetedFilterBarProps, SelectFacet } from './faceted-filter-bar.types.ts';
+
+  const generatedId = $props.id();
+
+  let {
+    'aria-label': ariaLabel = 'Filters',
+    searchQuery,
+    searchPlaceholder = 'Search…',
+    searchAriaLabel = 'Search',
+    facets = [],
+    appliedFilters = [],
+    disabled = false,
+    class: className,
+    onsearchchange,
+    onfacetchange,
+    onfilterremove,
+    onclearall,
+    ...rest
+  }: FacetedFilterBarProps = $props();
+
+  const searchId = $derived(`${generatedId}-search`);
+
+  // Internal uncontrolled search value when searchQuery is not provided.
+  let internalSearchQuery = $state('');
+  const isSearchControlled = $derived(searchQuery !== undefined);
+  const currentSearchQuery = $derived(
+    isSearchControlled ? (searchQuery ?? '') : internalSearchQuery,
+  );
+
+  // Facet controls are fully controlled by `appliedFilters`: the value a facet
+  // shows is whatever applied filter owns its key, or empty. There is no
+  // separate internal source of truth — that would let a select keep showing a
+  // value the parent has cleared (URL-state reset, clear-all, saved filters).
+  // A facet change is reported via `onfacetchange`; the consumer commits it
+  // back through `appliedFilters`.
+  function resolveFacetValue(key: string): string {
+    return appliedFilters.find((filter) => filter.key === key)?.value ?? '';
+  }
+
+  const hasAppliedFilters = $derived(appliedFilters.length > 0 || currentSearchQuery.length > 0);
+  const totalActiveCount = $derived(appliedFilters.length);
+
+  // Live region summary message — always in DOM, content changes when filters change.
+  const summaryMessage = $derived.by(() => {
+    if (totalActiveCount === 0) return '';
+    const parts = appliedFilters.map((filter) => `${filter.label}: ${filter.value}`);
+    return `${totalActiveCount} active filter${totalActiveCount === 1 ? '' : 's'}: ${parts.join(', ')}`;
+  });
+
+  function handleSearchInput(value: string): void {
+    if (!isSearchControlled) {
+      internalSearchQuery = value;
+    }
+    onsearchchange?.(value);
+  }
+
+  function handleFilterRemove(key: string): void {
+    onfilterremove?.(key);
+  }
+
+  function handleClearAll(): void {
+    if (!isSearchControlled) {
+      internalSearchQuery = '';
+    }
+    onclearall?.();
+  }
+
+  function getFacetCurrentValue(key: string): string {
+    return resolveFacetValue(key);
+  }
+</script>
+
+<div
+  {...rest}
+  class={classNames('cinder-faceted-filter-bar', className)}
+  role="search"
+  aria-label={ariaLabel}
+  data-disabled={disabled ? '' : undefined}
+>
+  <!-- Controls row: search field + facet selects -->
+  <div class="cinder-faceted-filter-bar__controls">
+    <SearchField
+      id={searchId}
+      class="cinder-faceted-filter-bar__search"
+      value={currentSearchQuery}
+      placeholder={searchPlaceholder}
+      aria-label={searchAriaLabel}
+      {disabled}
+      oninput={handleSearchInput}
+    />
+
+    {#each facets as facet (facet.key)}
+      {#if facet.type === 'select'}
+        {@const selectFacet = facet as SelectFacet}
+        <div class="cinder-faceted-filter-bar__facet">
+          <label
+            class="cinder-faceted-filter-bar__facet-label cinder-sr-only"
+            for={`${generatedId}-facet-${selectFacet.key}`}
+          >
+            {selectFacet.label}
+          </label>
+          <select
+            id={`${generatedId}-facet-${selectFacet.key}`}
+            class="cinder-faceted-filter-bar__select"
+            value={resolveFacetValue(selectFacet.key)}
+            disabled={disabled || selectFacet.disabled}
+            aria-label={selectFacet.label}
+            onchange={(event) => {
+              const target = event.currentTarget as HTMLSelectElement;
+              onfacetchange?.(selectFacet.key, target.value);
+            }}
+          >
+            <option value="">{selectFacet.placeholder ?? selectFacet.label}</option>
+            {#each selectFacet.options as option (option.value)}
+              <option value={option.value} disabled={option.disabled}>{option.label}</option>
+            {/each}
+          </select>
+          <span class="cinder-faceted-filter-bar__select-chevron" aria-hidden="true"></span>
+        </div>
+      {:else if facet.type === 'custom'}
+        <div class="cinder-faceted-filter-bar__facet">
+          {@render facet.control({
+            value: getFacetCurrentValue(facet.key),
+            onchange: (value: string) => {
+              onfacetchange?.(facet.key, value);
+            },
+          })}
+        </div>
+      {/if}
+    {/each}
+  </div>
+
+  <!-- Active controls row: chips + clear all -->
+  {#if hasAppliedFilters}
+    <div class="cinder-faceted-filter-bar__chips" aria-label="Active filter controls">
+      {#each appliedFilters as filter (filter.key)}
+        <Chip
+          mode="removable"
+          label={`${filter.label}: ${filter.value}`}
+          removeAriaLabel={`Remove filter: ${filter.label}: ${filter.value}`}
+          {disabled}
+          onremove={() => handleFilterRemove(filter.key)}
+        />
+      {/each}
+
+      <Button
+        variant="ghost"
+        size="sm"
+        class="cinder-faceted-filter-bar__clear-all"
+        {disabled}
+        onclick={handleClearAll}
+      >
+        Clear all
+      </Button>
+    </div>
+  {/if}
+
+  <!-- Always-in-DOM live region for accessible filter count summary.
+       Visibility toggled by content, never by {#if}, so the region is
+       registered with ATs before text is injected. -->
+  <VisuallyHiddenLiveRegion message={summaryMessage} priority="polite" />
+</div>

package/src/components/faceted-filter-bar/faceted-filter-bar.types.ts

@@ -0,0 +1,98 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** A single option available within a select-type facet. */
+export type FacetOption = {
+  /** The value submitted when this option is selected. */
+  value: string;
+  /** The human-readable label shown in the option list. */
+  label: string;
+  /** When true, the option is visible but not selectable. */
+  disabled?: boolean;
+};
+
+/**
+ * A facet configured with a fixed list of options rendered as a native select.
+ * Use for status, category, queue, or any enumerable filter dimension.
+ */
+export type SelectFacet = {
+  /** Discriminant that determines how the facet is rendered. */
+  type: 'select';
+  /** Unique key used to identify this facet in the applied-filter map. */
+  key: string;
+  /** Accessible label for the facet control. */
+  label: string;
+  /** Placeholder text shown when no value is selected. */
+  placeholder?: string;
+  /** Options available for selection. */
+  options: readonly FacetOption[];
+  /** Whether the facet control is disabled. */
+  disabled?: boolean;
+};
+
+/**
+ * A facet rendered by a consumer-supplied snippet. Use for date-range pickers,
+ * comboboxes, or any control that cannot be expressed as a select list.
+ */
+export type CustomFacet = {
+  /** Discriminant that determines how the facet is rendered. */
+  type: 'custom';
+  /** Unique key used to identify this facet in the applied-filter map. */
+  key: string;
+  /** Accessible label for the facet (used in the applied-filter chip). */
+  label: string;
+  /** Consumer-supplied snippet that renders the full facet control. */
+  control: Snippet<[{ value: string; onchange: (value: string) => void }]>;
+};
+
+/** Union of all supported facet definition types. */
+export type FacetDefinition = SelectFacet | CustomFacet;
+
+/** An applied filter entry: a facet key paired with its current value and display label. */
+export type AppliedFilter = {
+  /** The facet key this filter belongs to. */
+  key: string;
+  /** The current value of the filter. */
+  value: string;
+  /** The human-readable label used in the removable chip. */
+  label: string;
+};
+
+/**
+ * Props for the FacetedFilterBar component.
+ *
+ * A composed filtering toolbar that combines a leading search field, consumer-defined
+ * facet controls, applied-filter chips, and a clear-all action into one accessible unit.
+ */
+export type FacetedFilterBarProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
+  /** Accessible label for the filter toolbar region. Required for screen readers. */
+  'aria-label'?: string;
+  /** Current text search query. When provided, the search field is controlled. */
+  searchQuery?: string;
+  /** Placeholder text shown in the leading search field. */
+  searchPlaceholder?: string;
+  /** Accessible label for the search input. Defaults to 'Search'. */
+  searchAriaLabel?: string;
+  /**
+   * Facet definitions rendered as filter controls after the search field.
+   * Each entry is either a select-type facet or a custom snippet-driven facet.
+   */
+  facets?: readonly FacetDefinition[];
+  /**
+   * Applied filters displayed as removable chips below the controls row.
+   * Controlled by the consumer; each entry is a key/value/label triple.
+   */
+  appliedFilters?: readonly AppliedFilter[];
+  /** When true, all filter controls and chips are disabled. */
+  disabled?: boolean;
+  /** Additional CSS classes applied to the root element. */
+  class?: string;
+  /** Fires when the search query changes. */
+  onsearchchange?: (query: string) => void;
+  /** Fires when a facet value changes, with the facet key and new value. */
+  onfacetchange?: (key: string, value: string) => void;
+  /** Fires when a specific applied filter chip is removed. */
+  onfilterremove?: (key: string) => void;
+  /** Fires when the clear-all button is clicked. */
+  onclearall?: () => void;
+};

package/src/components/faceted-filter-bar/index.ts

@@ -0,0 +1,13 @@
+import './faceted-filter-bar.css';
+import FacetedFilterBar from './faceted-filter-bar.svelte';
+
+export default FacetedFilterBar;
+export type {
+  AppliedFilter,
+  CustomFacet,
+  FacetDefinition,
+  FacetOption,
+  FacetedFilterBarProps,
+  SelectFacet,
+} from './faceted-filter-bar.types.ts';
+export { FacetedFilterBar };

package/src/components/feed/README.md

@@ -35,9 +35,9 @@ The leaf remains importable individually for à-la-carte builds — see
 
 | Prop       | Type       | Required | Default | Description                                                                                                                                                                                                                                                                               |
 | ---------- | ---------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`   | no       | —       |                                                                                                                                                                                                                                                                                           |
+| `class`    | `string`   | no       | —       | Additional class merged onto the `.cinder-feed` root element.                                                                                                                                                                                                                             |
 | `live`     | `boolean`  | no       | —       | When true, the wrapper becomes an ARIA live region: `aria-live="polite"` and `aria-atomic="false"`. Use for feeds that mutate while the user is on the page (streaming notifications, log tails, chat-like activity). Defaults to false — a polite live region on a static feed is noise. |
-| `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      | —       | Feed events (typically `<FeedEvent>` children). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                |
 
 <!-- generated:props:end -->
 

package/src/components/feed/feed.types.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 export type FeedProps = Omit<HTMLAttributes<HTMLOListElement>, 'children' | 'class'> & {
+  /** Additional class merged onto the `.cinder-feed` root element. */
   class?: string;
   /**
    * When true, the wrapper becomes an ARIA live region: `aria-live="polite"`

package/src/components/feed-event/README.md

@@ -16,13 +16,13 @@ snippet. The flat `@lostgradient/cinder/feed-event` subpath remains exported for
 
 | Prop             | Type                    | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | ---------------- | ----------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`          | `string`                | no       | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `class`          | `string`                | no       | —       | Additional class merged onto the `.cinder-feed-event` root element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `datetime`       | `string`                | yes      | —       | ISO 8601 datetime string. Rendered as `<time datetime={datetime}>` so assistive tech and parsers receive a machine-readable timestamp. This is always the authoritative value; the visible label is separate (see `timestamp` / `timestampLabel`).                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `timestamp`      | `string`                | no       | —       | Visible time label, as plain text — the common case (`"2m ago"`, `"May 12, 3:30 PM"`). Rendered inside the `<time>` element. Optional, with a deliberate three-way contract: - **omitted** (`undefined`) and no `timestampLabel` → falls back to the raw `datetime` string, which is deterministic and SSR-safe (no locale or timezone dependence). - **explicit empty string** (`timestamp=""`) → renders no visible label. This is treated as "intentionally blank", NOT as omitted, so it does **not** trigger the `datetime` fallback. Use it to hide the label while keeping the machine-readable `<time datetime>` for assistive tech. - **non-empty string** → rendered verbatim. |
 | `variant`        | `"icon"` \| `"minimal"` | no       | —       | Icon variant: renders a circular badge on the rail with the icon inside.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `icon`           | `(opaque)`              | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `timestampLabel` | `(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)`              | no       | —       | Main event body — the description, links, and secondary metadata. Passed as the default children snippet: `svelte <FeedEvent datetime="…" timestamp="2m ago">   <strong>{user.name}</strong> pushed 3 commits </FeedEvent> ` Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                  |
+| `icon`           | `(opaque)`              | no       | —       | Required for the icon variant. Type-enforced by the discriminated union. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `timestampLabel` | `(opaque)`              | no       | —       | Rich visible time label, for the rare case where the label needs markup (e.g. an `<abbr>` or nested element). Takes precedence over `timestamp` when both are supplied. Most consumers should use the `timestamp` string instead. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                             |
 
 <!-- generated:props:end -->
 

package/src/components/feed-event/feed-event.types.ts

@@ -2,6 +2,7 @@ import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 export type FeedEventVariant = 'icon' | 'minimal';
 type FeedEventBase = Omit<HTMLAttributes<HTMLLIElement>, 'children' | 'class'> & {
+  /** Additional class merged onto the `.cinder-feed-event` root element. */
   class?: string;
   /**
    * ISO 8601 datetime string. Rendered as `<time datetime={datetime}>` so

package/src/components/file-upload/README.md

@@ -34,21 +34,21 @@ announces results, and can render consumer-driven upload progress rows.
 
 <!-- generated:props:start -->
 
-| Prop         | Type       | Required | Default | Description                                                                                                                |
-| ------------ | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `accept`     | `string`   | no       | —       | Native file accept filter.                                                                                                 |
-| `disabled`   | `boolean`  | no       | —       | Disables the file picker and drag-and-drop surface.                                                                        |
-| `id`         | `string`   | no       | —       | Stable id for the native file input. Required when composing with `FormField`.                                             |
-| `maxSize`    | `number`   | no       | —       | Maximum allowed file size in bytes.                                                                                        |
-| `multiple`   | `boolean`  | no       | —       | Allow more than one file. Default `false`.                                                                                 |
-| `name`       | `string`   | no       | —       | Native input name used for form submission.                                                                                |
-| `class`      | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `dragActive` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `fileList`   | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `files`      | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `idle`       | `(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. |
-| `onreject`   | `(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                                                                                                                                       |
+| ------------ | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `accept`     | `string`   | no       | —       | Native file accept filter.                                                                                                                        |
+| `disabled`   | `boolean`  | no       | —       | Disables the file picker and drag-and-drop surface.                                                                                               |
+| `id`         | `string`   | no       | —       | Stable id for the native file input. Required when composing with `FormField`.                                                                    |
+| `maxSize`    | `number`   | no       | —       | Maximum allowed file size in bytes.                                                                                                               |
+| `multiple`   | `boolean`  | no       | —       | Allow more than one file. Default `false`.                                                                                                        |
+| `name`       | `string`   | no       | —       | Native input name used for form submission.                                                                                                       |
+| `class`      | `(opaque)` | no       | —       | Additional classes merged with `.cinder-file-upload`. Not expressible in JSON Schema; see the component types for the signature.                  |
+| `dragActive` | `(opaque)` | no       | —       | Replaces the default drag-active dropzone body. Not expressible in JSON Schema; see the component types for the signature.                        |
+| `fileList`   | `(opaque)` | no       | —       | Replaces the default file-list renderer. Receives the resolved rows. Not expressible in JSON Schema; see the component types for the signature.   |
+| `files`      | `(opaque)` | no       | —       | Consumer-driven file rows, including upload progress and error states. Not expressible in JSON Schema; see the component types for the signature. |
+| `idle`       | `(opaque)` | no       | —       | Replaces the default resting-state dropzone body. Not expressible in JSON Schema; see the component types for the signature.                      |
+| `onchange`   | `(opaque)` | no       | —       | Fires with accepted files after local validation passes. Not expressible in JSON Schema; see the component types for the signature.               |
+| `onreject`   | `(opaque)` | no       | —       | Fires with rejected files and reasons after local validation runs. Not expressible in JSON Schema; see the component types for the signature.     |
 
 <!-- generated:props:end -->
 

package/src/components/floating-action-button/README.md

@@ -25,14 +25,15 @@ Circular button representing the single most important action on a screen.
 
 <!-- generated:props:start -->
 
-| Prop       | Type                                        | Required | Default     | Description                                              |
-| ---------- | ------------------------------------------- | -------- | ----------- | -------------------------------------------------------- |
-| `class`    | `string`                                    | no       | —           | Custom class merged with `.cinder-fab`.                  |
-| `color`    | `"primary"` \| `"secondary"` \| `"surface"` | no       | `"primary"` | Color palette.                                           |
-| `disabled` | `boolean`                                   | no       | `false`     | When true, disables the button and prevents interaction. |
-| `href`     | `string`                                    | no       | —           | Render as an anchor `<a>` element with this href.        |
-| `size`     | `"sm"` \| `"md"` \| `"lg"`                  | no       | `"md"`      | Size of the FAB.                                         |
-| `variant`  | `"filled"` \| `"extended"`                  | no       | `"filled"`  | Visual variant. `filled` = circle, `extended` = pill.    |
+| Prop       | Type                                        | Required | Default     | Description                                                                                                                                                                                                                            |
+| ---------- | ------------------------------------------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`                                    | no       | —           | Custom class merged with `.cinder-fab`.                                                                                                                                                                                                |
+| `color`    | `"primary"` \| `"secondary"` \| `"surface"` | no       | `"primary"` | Color palette.                                                                                                                                                                                                                         |
+| `disabled` | `boolean`                                   | no       | `false`     | When true, disables the button and prevents interaction.                                                                                                                                                                               |
+| `href`     | `string`                                    | no       | —           | Render as an anchor `<a>` element with this href.                                                                                                                                                                                      |
+| `size`     | `"sm"` \| `"md"` \| `"lg"`                  | no       | `"md"`      | Size of the FAB.                                                                                                                                                                                                                       |
+| `variant`  | `"filled"` \| `"extended"`                  | no       | `"filled"`  | Visual variant. `filled` = circle, `extended` = pill.                                                                                                                                                                                  |
+| `children` | `(opaque)`                                  | no       | —           | The icon (or icon + label for extended variant). Always provide `aria-label` when the FAB renders an icon without visible text — i.e. the `filled` variant. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/floating-action-button/floating-action-button.css

@@ -41,7 +41,8 @@
     outline: var(--cinder-ring-width) solid 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-ring-color),
+      0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width))
+        var(--_cinder-fab-ring, var(--cinder-ring-color)),
       var(--_cinder-fab-elevation);
   }
 
@@ -119,6 +120,7 @@
 
   /* primary — accent fill with contrast foreground */
   .cinder-fab[data-cinder-color='primary'] {
+    --_cinder-fab-ring: var(--cinder-ring-on-accent);
     background: var(--cinder-accent);
     color: var(--cinder-accent-contrast);
   }

package/src/components/focus-trap/README.md

@@ -19,13 +19,14 @@ Traps keyboard focus within a container and restores focus to the previously foc
 
 <!-- generated:props:start -->
 
-| Prop            | Type               | Required | Default | Description |
-| --------------- | ------------------ | -------- | ------- | ----------- |
-| `active`        | `boolean`          | no       | —       |             |
-| `class`         | `string`           | no       | —       |             |
-| `fallbackFocus` | `string` \| `null` | no       | —       |             |
-| `initialFocus`  | `string` \| `null` | no       | —       |             |
-| `restoreFocus`  | `boolean`          | no       | —       |             |
+| Prop            | Type               | Required | Default | Description                                                                                                                                        |
+| --------------- | ------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `active`        | `boolean`          | no       | —       | When true (default), Tab key navigation is constrained within the trap container. Set to false to temporarily suspend trapping without unmounting. |
+| `class`         | `string`           | no       | —       | Additional class applied to the focus-trap wrapper element.                                                                                        |
+| `fallbackFocus` | `string` \| `null` | no       | —       | CSS selector for the element that receives focus when `initialFocus` is unset or unresolvable. Defaults to the trap container itself.              |
+| `initialFocus`  | `string` \| `null` | no       | —       | CSS selector for the element that should receive focus when the trap activates. Falls back to `fallbackFocus` when the selector matches nothing.   |
+| `restoreFocus`  | `boolean`          | no       | —       | When true (default), returns focus to the previously focused element when the trap is deactivated or unmounted.                                    |
+| `children`      | `(opaque)`         | yes      | —       | 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/focus-trap/focus-trap.types.ts

@@ -13,10 +13,15 @@ export type FocusTrapProps = Omit<HTMLAttributes<HTMLDivElement>, 'children' | '
 };
 
 export interface FocusTrapSchemaProps {
+  /** When true (default), Tab key navigation is constrained within the trap container. Set to false to temporarily suspend trapping without unmounting. */
   active?: boolean;
+  /** When true (default), returns focus to the previously focused element when the trap is deactivated or unmounted. */
   restoreFocus?: boolean;
+  /** CSS selector for the element that should receive focus when the trap activates. Falls back to `fallbackFocus` when the selector matches nothing. */
   initialFocus?: string | null;
+  /** CSS selector for the element that receives focus when `initialFocus` is unset or unresolvable. Defaults to the trap container itself. */
   fallbackFocus?: string | null;
+  /** Additional class applied to the focus-trap wrapper element. */
   class?: string;
 }
 

package/src/components/focus-trap/focus-trap.utilities.svelte.ts

@@ -15,6 +15,20 @@ export type FocusTrapOptions = {
   restoreFocus?: boolean;
   initialFocus?: FocusTargetInput;
   fallbackFocus?: FocusTargetInput;
+  /**
+   * Whether the trap moves focus into its panel when it activates. Defaults to
+   * `true` — the trap focuses {@link initialFocus} → first tabbable → fallback →
+   * the root on open, which is what stand-alone overlays (popovers, menus) want.
+   *
+   * Set to `false` for hosts that perform their OWN initial focus (native
+   * `<dialog>.showModal()` already focuses, and Modal/Sheet/Drawer then deliberately
+   * move focus to a `tabindex="-1"` body container so reading starts at the content,
+   * not the close button). With `manageInitialFocus: false` the trap still provides
+   * Tab-wrapping and trap-stack membership, but never overrides the host's chosen
+   * initial focus. Such hosts also own focus restoration, so they pair this with
+   * `restoreFocus: false`.
+   */
+  manageInitialFocus?: boolean;
 };
 
 type TrapInstance = {
@@ -52,7 +66,14 @@ function isHiddenByTree(element: HTMLElement): boolean {
 function isFocusableCandidate(element: HTMLElement): boolean {
   if (isHiddenByTree(element)) return false;
   if (element.hasAttribute('disabled')) return false;
-  if (element.getAttribute('tabindex') === '-1') return false;
+  // Reject ALL explicit negative tabindex values (not just "-1"). `tabindex="-2"`
+  // is programmatically focusable but NOT reachable via sequential Tab, so
+  // including it in `getTabbableElements` would corrupt the first/last boundary
+  // the Tab-wrap logic relies on. Gate on `hasAttribute` first so the IDL
+  // `tabIndex` property is only read for elements that actually set it — natively
+  // focusable elements without the attribute keep their default tabbability
+  // without depending on the DOM environment's IDL defaults (happy-dom vs real).
+  if (element.hasAttribute('tabindex') && element.tabIndex < 0) return false;
   return true;
 }
 
@@ -153,6 +174,7 @@ export function createFocusTrap(options: FocusTrapOptions = {}): Attachment<HTML
     const restoreFocus = options.restoreFocus ?? true;
     const initialFocus = options.initialFocus ?? null;
     const fallbackFocus = options.fallbackFocus ?? null;
+    const manageInitialFocus = options.manageInitialFocus ?? true;
 
     let activated = false;
     // Bumped on every `activate()`. The deferred `focusTrapTarget` microtask snapshots this value
@@ -191,12 +213,19 @@ export function createFocusTrap(options: FocusTrapOptions = {}): Attachment<HTML
           ? document.activeElement
           : null;
       pushTrap({ id: trapId, node });
+      // Hosts that own their own initial focus (Modal/Sheet/Drawer focus a body
+      // container after showModal()) opt out so the trap never overrides that choice
+      // by yanking focus to the first tabbable (the close button) on the next microtask.
+      if (!manageInitialFocus) return;
       // Defer focusing so the trap's content is in the DOM. Guard against the trap being
       // deactivated (or deactivated then reactivated) before this microtask drains — moving focus
       // into a no-longer-current activation would steal it back after `deactivate()` already
-      // restored it to the previously-focused element.
+      // restored it to the previously-focused element. The `!isActive()` check covers the
+      // synchronous open→close window: `deactivate()` runs on the next effect flush (after this
+      // microtask), but the live reactive `active` getter already reads false, so a host that
+      // closes immediately after opening does not have focus dragged into the trap post-close.
       queueMicrotask(() => {
-        if (!activated || generation !== activationGeneration) return;
+        if (!activated || generation !== activationGeneration || !isActive()) return;
         focusTrapTarget();
       });
     }