@lostgradient/cinder 0.4.0 → 0.5.0

package/src/components/date-range-field/README.md

@@ -1,142 +0,0 @@
-# DateRangeField
-
-Controlled start/end date range picker with preset shortcuts and validation feedback, designed for time-window filtering on dashboards, event streams, and audit logs.
-
-## Overview
-
-`DateRangeField` renders two native date or date-time inputs (start and end) along with a row of preset shortcut buttons (Today, Yesterday & today, Last 7 days by default). It is fully controlled: the consumer owns the `value` and responds to `onchange` callbacks. It does not own routing, query-string synchronization, timezone conversion, or data fetching.
-
-Values are ISO-8601 local strings. `granularity="day"` emits `YYYY-MM-DD`; `granularity="hour"`, `"minute"`, and `"second"` use native `datetime-local` inputs and emit values truncated to the selected precision.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import { DateRangeField } from '@lostgradient/cinder/date-range-field';
-  import type { DateRangeValue } from '@lostgradient/cinder/date-range-field';
-
-  let range: DateRangeValue = $state({ start: undefined, end: undefined });
-</script>
-
-<DateRangeField
-  id="event-time-filter"
-  label="Time window"
-  bind:value={range}
-  onchange={(next) => {
-    range = next;
-  }}
-/>
-```
-
-### With custom presets
-
-```svelte
-<script lang="ts">
-  import { DateRangeField } from '@lostgradient/cinder/date-range-field';
-  import type { DateRangeDatePreset, DateRangeValue } from '@lostgradient/cinder/date-range-field';
-
-  let range: DateRangeValue = $state({ start: undefined, end: undefined });
-
-  function formatLocalDate(date: Date): string {
-    const year = date.getFullYear();
-    const month = String(date.getMonth() + 1).padStart(2, '0');
-    const day = String(date.getDate()).padStart(2, '0');
-    return `${year}-${month}-${day}`;
-  }
-
-  const presets: DateRangeDatePreset[] = [
-    {
-      id: 'today',
-      label: 'Today',
-      resolve: () => {
-        const today = formatLocalDate(new Date());
-        return { start: today, end: today };
-      },
-    },
-    {
-      id: 'this-month',
-      label: 'This month',
-      resolve: () => {
-        const now = new Date();
-        const start = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-01`;
-        const end = formatLocalDate(now);
-        return { start, end };
-      },
-    },
-  ];
-</script>
-
-<DateRangeField id="billing-filter" label="Billing period" {presets} bind:value={range} />
-```
-
-### With validation error
-
-```svelte
-<script lang="ts">
-  import { DateRangeField } from '@lostgradient/cinder/date-range-field';
-  import type { DateRangeValue } from '@lostgradient/cinder/date-range-field';
-
-  let range: DateRangeValue = $state({ start: undefined, end: undefined });
-
-  let error = $derived(
-    range.start && range.end && range.start > range.end
-      ? 'Start date must be on or before the end date.'
-      : undefined,
-  );
-</script>
-
-<DateRangeField id="validated-filter" label="Date range" bind:value={range} {error} />
-```
-
-## Props
-
-```
-id           string               no        Unique identifier for label and ARIA wiring. Generated via `$props.id()` when omitted.
-value        DateRangeValue       no        Current range. Bindable. Both fields start undefined.
-label        string               no        Visible legend rendered above the inputs.
-startLabel   string               no        Label for the start input. Default: "Start date".
-endLabel     string               no        Label for the end input. Default: "End date".
-granularity  DateRangeGranularity no        Precision for native inputs: day, hour, minute, or second. Default: day.
-presets      DateRangeDatePreset[]  no      Custom preset buttons. Defaults to today, yesterday-today, last-7d.
-hidePresets  boolean              no        When true, hides the preset row. Default: false.
-description  string               no        Helper text below the field, wired via aria-describedby.
-error        string               no        Validation error. Sets aria-invalid="true" on inputs.
-disabled     boolean              no        Disables all inputs and preset buttons. Default: false.
-class        string               no        Additional CSS classes on the root element.
-onchange     (value) => void      no        Called when the range changes via preset or manual input.
-```
-
-## Types
-
-```ts
-type DateRangeValue = {
-  start: string | undefined; // ISO-8601 local date or datetime string
-  end: string | undefined; // ISO-8601 local date or datetime string
-};
-
-type DateRangeDatePreset = {
-  id: string;
-  label: string;
-  resolve: () => DateRangeValue;
-};
-```
-
-## Accessibility
-
-The component implements accessible form labelling throughout:
-
-- Each date input is associated with a `<label>` via `for`/`id`.
-- The optional legend (`label` prop) is a `<p>` associated with the group visually.
-- The preset button row carries `role="group"` with `aria-label="Date range presets"`.
-- Each preset button carries `aria-pressed` to communicate current selection state to assistive technology.
-- The error region uses `aria-live="polite"` and is always in the DOM so screen readers reliably pick up the live region before text is injected.
-- When `error` is set, both inputs carry `aria-invalid="true"`.
-- The root carries `role="group"` and `aria-labelledby` pointing to the legend element when a `label` prop is provided, associating the label with the start/end input group.
-- `description` and `error` elements are wired into each input via `aria-describedby`, so a screen reader user tabbing to an input hears the description and any active error.
-- Forced-colors (Windows High Contrast) mode: inputs and preset buttons receive a solid `outline` instead of `box-shadow` focus rings, which are ignored in that mode.
-
-## Scope limits
-
-- Timezone conversion is caller-owned. Native `datetime-local` values are local wall-clock strings without timezone offsets.
-- The browser owns the date and date-time picker UI. Keyboard behavior inside those native pickers is browser-controlled.
-- No range constraint enforcement. The component sets `min`/`max` on the inputs to hint the browser's picker (end min = start, start max = end), but does not block the user from entering out-of-order values programmatically. Validation is the consumer's responsibility via the `error` prop.

package/src/components/description-list/README.md

@@ -1,42 +0,0 @@
-# DescriptionList
-
-Semantic dl/dt/dd list for term–description pairs such as metadata or attributes.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import DescriptionList from '@lostgradient/cinder/description-list';
-</script>
-
-<DescriptionList />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop      | Type                                                       | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                              |
-| --------- | ---------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `class`   | `string`                                                   | no       | —       | Additional class merged onto the `.cinder-description-list` root element.                                                                                                                                                                                                                                                                                                |
-| `variant` | `"default"` \| `"striped"` \| `"two-column"` \| `"narrow"` | no       | —       | Controls the visual layout: - `default`: stacked rows with visible terms. - `striped`: alternating row backgrounds. - `two-column`: term and definition share a row; collapses to stacked at narrow widths. - `narrow`: `<dt>` is visually hidden via `.cinder-sr-only`. Only appropriate when surrounding context already labels the value. NOT a general compact mode. |
-| `actions` | `(opaque)`                                                 | no       | —       | Optional snippet rendered once per row. Receives the full `DescriptionListItem` so consumers can build disambiguated `aria-label` strings (e.g. `aria-label="Edit ${item.term}"`). Any interactive element in `actions` MUST set an unambiguous `aria-label`. Not expressible in JSON Schema; see the component types for the signature.                                 |
-| `items`   | `(opaque)`                                                 | yes      | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                  |
-
-<!-- generated:props:end -->
-
-## CSS Variables
-
-<!-- generated:variables:start -->
-
-This component does not declare any local CSS variables.
-
-<!-- generated:variables:end -->
-
-## Subcomponents
-
-<!-- generated:subcomponents:start -->
-
-None.
-
-<!-- generated:subcomponents:end -->

package/src/components/diff-statistics/README.md

@@ -1,61 +0,0 @@
-# DiffStatistics
-
-Compact inline display of added, modified, and removed line counts for a file diff.
-
-## Choosing this component
-
-- Showing the line-change summary for a single file or commit in a code review, pull-request list, or activity feed.
-- Toolbars and compact layouts — use `density="toolbar"` to snap to the shared control-height tier.
-- Suppressing zero-count values cleanly with `hideZero` when a file has only additions or only deletions.
-
-## Choosing something else
-
-- General numeric metrics (revenue, users, errors) — use [`Stat`](../stat/README.md) or [`StatGroup`](../stat-group/README.md) for dashboard figures.
-- Full diff rendering (side-by-side or unified views of the actual line changes) — DiffStatistics only summarises counts; use a diff renderer component for the actual content.
-
-## Related components
-
-- [`Stat`](../stat/README.md) — general-purpose metric tile for non-diff numeric values.
-- [`StatGroup`](../stat-group/README.md) — grid container for multiple `Stat` tiles.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import DiffStatistics from '@lostgradient/cinder/diff-statistics';
-</script>
-
-<DiffStatistics />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop       | Type                       | Required | Default | Description                                                                                                                                          |
-| ---------- | -------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `added`    | `number`                   | yes      | —       | Number of added lines.                                                                                                                               |
-| `class`    | `string`                   | no       | —       | Additional class names merged with `.cinder-diff-statistics`.                                                                                        |
-| `density`  | `"toolbar"`                | no       | —       | Toolbar density opt-in (compact variant only). When set, pills snap to the shared `--cinder-control-height-sm` tier.                                 |
-| `hideZero` | `boolean`                  | no       | —       | Hide statistics with a zero value.                                                                                                                   |
-| `modified` | `number`                   | yes      | —       | Number of modified lines.                                                                                                                            |
-| `removed`  | `number`                   | yes      | —       | Number of removed lines.                                                                                                                             |
-| `variant`  | `"default"` \| `"compact"` | no       | —       | Layout variant. `default` shows full statistic markup; `compact` trims it for tight surfaces. Distinct from `density`, which adjusts control height. |
-
-<!-- generated:props:end -->
-
-## CSS Variables
-
-<!-- generated:variables:start -->
-
-This component does not declare any local CSS variables.
-
-<!-- generated:variables:end -->
-
-## Subcomponents
-
-<!-- generated:subcomponents:start -->
-
-None.
-
-<!-- generated:subcomponents:end -->

package/src/components/diff-viewer/README.md

@@ -1,59 +0,0 @@
-# DiffViewer
-
-Side-by-side or unified Markdown diff surface with hunk grouping, word-level inline changes, and size-based debounce gating.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import { DiffViewer } from '@lostgradient/cinder/diff-viewer';
-</script>
-```
-
-## Guidance
-
-### Use When
-
-- Comparing two Markdown documents and wanting the bundled toolbar, view-mode toggle, front-matter handling, and large-payload safeguards.
-- Building a review workflow that needs hunked, line-anchored Markdown diffs out of the box as a heavyweight suite.
-
-### Avoid When
-
-- Showing only a counts summary — use diff-statistics on its own for a lightweight presentation.
-- Diffing non-Markdown source code where syntax-aware highlighting matters more than prose-aware rendering.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop              | Type                                     | Required | Default | Description                                                                                                                                                                                                                                 |
-| ----------------- | ---------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`           | `string`                                 | no       | —       | Additional CSS classes                                                                                                                                                                                                                      |
-| `current`         | `string`                                 | yes      | —       | The current/modified text                                                                                                                                                                                                                   |
-| `normalizeInputs` | `boolean`                                | no       | —       | Whether to normalize markdown inputs before comparison. When true (default), both original and current are normalized to canonical form before diffing, preventing false positives from formatting differences.                             |
-| `original`        | `string`                                 | yes      | —       | The original/baseline text                                                                                                                                                                                                                  |
-| `readonly`        | `boolean`                                | no       | —       | Whether the viewer is read-only (hides revert buttons)                                                                                                                                                                                      |
-| `viewMode`        | `"unified"` \| `"final"` \| `"original"` | no       | —       | Bindable: reactive access to current view mode. Parent components can bind to control or observe the view mode.                                                                                                                             |
-| `hunks`           | `(opaque)`                               | no       | —       | Bindable: reactive access to computed hunks. Parent components can bind to this to reactively access hunk data. Not expressible in JSON Schema; see the component types for the signature.                                                  |
-| `onrevertall`     | `(opaque)`                               | no       | —       | Called when user wants to revert all changes Not expressible in JSON Schema; see the component types for the signature.                                                                                                                     |
-| `onreverthunk`    | `(opaque)`                               | no       | —       | Called when user wants to revert a specific hunk Not expressible in JSON Schema; see the component types for the signature.                                                                                                                 |
-| `toolbar`         | `(opaque)`                               | no       | —       | Override the entire toolbar for advanced customization. When provided, replaces the default toolbar completely. Not expressible in JSON Schema; see the component types for the signature.                                                  |
-| `toolbarActions`  | `(opaque)`                               | no       | —       | Additional toolbar actions rendered in the toolbar-right section. Use this to inject custom buttons (e.g., export actions) without replacing the entire toolbar. Not expressible in JSON Schema; see the component types for the signature. |
-
-<!-- generated:props:end -->
-
-## CSS Variables
-
-<!-- generated:variables:start -->
-
-This component does not declare any local CSS variables.
-
-<!-- generated:variables:end -->
-
-## Subcomponents
-
-<!-- generated:subcomponents:start -->
-
-None.
-
-<!-- generated:subcomponents:end -->

package/src/components/divider/README.md

@@ -1,59 +0,0 @@
-# Divider
-
-A 1px visual rule for separating content regions. Horizontal by default; pass `orientation="vertical"` for toolbar group separators inside a flex container.
-
-The canonical use case is **vertical dividers between toolbar groups**—for example, between action clusters in a `NavigationBar`. Because toolbars use horizontal flex layout, a vertical divider stretches to the row height automatically via `align-self: stretch`.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import Divider from '@lostgradient/cinder/divider';
-</script>
-
-<!-- Horizontal rule between sections -->
-<Divider />
-
-<!-- Vertical rule between toolbar groups -->
-<div style="display: flex; align-items: center; gap: 8px;">
-  <button>Bold</button>
-  <Divider orientation="vertical" />
-  <button>Insert</button>
-</div>
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop          | Type                           | Required | Default        | Description                                                        |
-| ------------- | ------------------------------ | -------- | -------------- | ------------------------------------------------------------------ |
-| `class`       | `string`                       | no       | —              | Additional class names merged with `.cinder-divider`.              |
-| `decorative`  | `boolean`                      | no       | `true`         | When `true` the element is hidden from assistive technology.       |
-| `inset`       | `boolean`                      | no       | `false`        | Shortens the rule by `--cinder-space-2` on the perpendicular axis. |
-| `orientation` | `"horizontal"` \| `"vertical"` | no       | `"horizontal"` | Layout axis the rule spans.                                        |
-| `tone`        | `"subtle"` \| `"strong"`       | no       | `"subtle"`     | Visual weight of the divider line.                                 |
-
-<!-- generated:props:end -->
-
-## Accessibility
-
-`decorative={true}` (the default) hides the element from assistive technology entirely with `aria-hidden="true"`. Use this for visual polish only.
-
-`decorative={false}` exposes the element to screen readers. A horizontal divider renders as `<hr>`; a vertical divider renders as `<span role="separator" aria-orientation="vertical">`.
-
-## CSS Variables
-
-<!-- generated:variables:start -->
-
-This component does not declare any local CSS variables.
-
-<!-- generated:variables:end -->
-
-## Subcomponents
-
-<!-- generated:subcomponents:start -->
-
-None.
-
-<!-- generated:subcomponents:end -->

package/src/components/drawer/README.md

@@ -1,66 +0,0 @@
-# Drawer
-
-Side-anchored overlay panel for supplementary content without leaving the current page.
-
-## Choosing this component
-
-- Showing detail or edit forms alongside a list or table where the user needs to stay in context.
-- Navigation trees, filter panels, or settings that the user may want to keep open while interacting with the page.
-- Secondary workflows that complement the current view rather than replacing it.
-
-## Choosing something else
-
-- Full-screen workflows that require the user's full attention — use a [`Modal`](../modal/README.md) or navigate to a new page.
-- Mobile-style bottom sheets — use [`Sheet`](../sheet/README.md) for the bottom-anchored variant.
-- Brief contextual explanations or single-action prompts — use a [`Popover`](../popover/README.md) instead.
-
-## Related components
-
-- [`Modal`](../modal/README.md) — blocking full-attention overlay when the user cannot continue without acting.
-- [`Sheet`](../sheet/README.md) — bottom-anchored overlay optimised for mobile interactions.
-- [`Sidebar`](../sidebar/README.md) — persistent side panel that is always visible (not overlaid).
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import Drawer from '@lostgradient/cinder/drawer';
-</script>
-
-<Drawer />
-```
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop             | Type                                 | Required | Default | Description                                                                                                                                                                                                                                                                                                              |
-| ---------------- | ------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `ariaLabelledBy` | `string`                             | no       | —       | Optional id of an element that names the drawer. When supplied, drawer wires `aria-labelledby` to this id and renders no internal heading. Use this when a custom `header` snippet has its own visible heading — supply `ariaLabelledBy` pointing to that heading's id so the visible and accessible names stay in sync. |
-| `class`          | `string`                             | no       | —       | Additional class names merged with `.cinder-drawer`.                                                                                                                                                                                                                                                                     |
-| `open`           | `boolean`                            | no       | —       | Whether the drawer is open. Bindable via `bind:open`.                                                                                                                                                                                                                                                                    |
-| `side`           | `"left"` \| `"right"`                | no       | —       | Edge the drawer slides in from. Default `right`.                                                                                                                                                                                                                                                                         |
-| `size`           | `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | no       | —       | Drawer width token. Default `md`.                                                                                                                                                                                                                                                                                        |
-| `title`          | `string`                             | yes      | —       | Accessible name for the drawer. Required for screen-reader labelling. Rendered as a visible `<h2>` in the default header. When a custom `header` snippet is provided without `ariaLabelledBy`, this text is rendered in a visually-hidden `<h2>` as the accessible name fallback.                                        |
-| `children`       | `(opaque)`                           | yes      | —       | Drawer body content. Required. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                |
-| `footer`         | `(opaque)`                           | no       | —       | Optional footer (e.g. action buttons). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                        |
-| `header`         | `(opaque)`                           | no       | —       | Custom header. Falls back to a default header that renders `title`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                           |
-| `triggerRef`     | `(opaque)`                           | no       | —       | Optional reference to the element that opened the drawer. When supplied, focus returns to this element on close. When omitted, focus restores to the element that held focus before the drawer opened. Not expressible in JSON Schema; see the component types for the signature.                                        |
-
-<!-- generated:props:end -->
-
-## CSS Variables
-
-<!-- generated:variables:start -->
-
-This component does not declare any local CSS variables.
-
-<!-- generated:variables:end -->
-
-## Subcomponents
-
-<!-- generated:subcomponents:start -->
-
-None.
-
-<!-- generated:subcomponents:end -->

package/src/components/dropdown/README.md

@@ -1,71 +0,0 @@
-# Dropdown
-
-Composite dropdown root that coordinates the trigger, menu, and item subcomponents.
-
-## Usage
-
-`Dropdown` is a compound component. Import the parent and compose its leaves
-via the namespace API: `Dropdown.Trigger`, `Dropdown.Menu`, `Dropdown.Item`,
-`Dropdown.Label`, `Dropdown.Separator`, and `Dropdown.Group`.
-
-```svelte
-<script lang="ts">
-  import { Dropdown } from '@lostgradient/cinder/dropdown';
-</script>
-
-<Dropdown id="dropdown-actions">
-  <Dropdown.Trigger>Options</Dropdown.Trigger>
-  <Dropdown.Menu>
-    <Dropdown.Label id="dropdown-actions-document">Document</Dropdown.Label>
-    <Dropdown.Item>Edit</Dropdown.Item>
-    <Dropdown.Item>Duplicate</Dropdown.Item>
-    <Dropdown.Separator />
-    <Dropdown.Item variant="danger">Delete</Dropdown.Item>
-  </Dropdown.Menu>
-</Dropdown>
-```
-
-The leaves remain importable individually for à-la-carte builds — see
-`@lostgradient/cinder/dropdown-trigger`, `@lostgradient/cinder/dropdown-menu`, `@lostgradient/cinder/dropdown-item`,
-`@lostgradient/cinder/dropdown-label`, `@lostgradient/cinder/dropdown-separator`, and `@lostgradient/cinder/dropdown-group`.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop        | Type                               | Required | Default | Description                                                                                                                |
-| ----------- | ---------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`     | `string`                           | no       | —       | Additional class names merged with the component's root class.                                                             |
-| `id`        | `string`                           | no       | —       | HTML id applied to the dropdown root element. Auto-generated when omitted.                                                 |
-| `open`      | `boolean`                          | no       | —       | Controls the open state of the dropdown menu; bindable for controlled usage.                                               |
-| `placement` | `"bottom-start"` \| `"bottom-end"` | no       | —       | Preferred side of the trigger on which the menu opens. Default `bottom-start`.                                             |
-| `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. |
-| `trigger`   | `(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 -->
-
-## CSS Variables
-
-<!-- generated:variables:start -->
-
-This component does not declare any local CSS variables.
-
-<!-- generated:variables:end -->
-
-## Subcomponents
-
-<!-- generated:subcomponents:start -->
-
-- `Dropdown.Trigger` — the button that toggles the menu; see
-  [`dropdown-trigger`](../dropdown-trigger/README.md).
-- `Dropdown.Menu` — the menu surface; see [`dropdown-menu`](../dropdown-menu/README.md).
-- `Dropdown.Item` — a menu item with optional `variant="danger"`; see
-  [`dropdown-item`](../dropdown-item/README.md).
-- `Dropdown.Label` — accessible section label inside the menu; see
-  [`dropdown-label`](../dropdown-label/README.md).
-- `Dropdown.Separator` — a visual divider; see
-  [`dropdown-separator`](../dropdown-separator/README.md).
-- `Dropdown.Group` — accessible grouping for related items inside the menu; see
-  [`dropdown-group`](../dropdown-group/README.md).
-
-<!-- generated:subcomponents:end -->

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

@@ -1,52 +0,0 @@
-# DropdownGroup
-
-Accessible group boundary that clusters related dropdown-item rows inside a dropdown-menu.
-
-## Usage
-
-```svelte
-<script lang="ts">
-  import { DropdownGroup } from '@lostgradient/cinder/dropdown-group';
-</script>
-```
-
-## Guidance
-
-### Use When
-
-- Grouping related dropdown actions under one accessible heading.
-- Pairing dropdown-label with a role='group' container inside dropdown-menu.
-
-### Avoid When
-
-- Rendering a clickable row — use dropdown-item.
-- Separating sections without a group label — use dropdown-separator.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop         | Type       | Required | Default | Description                                                                                                                        |
-| ------------ | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `class`      | `string`   | no       | —       | Additional class names merged onto the group root.                                                                                 |
-| `label`      | `string`   | no       | —       | Accessible label for the group, applied as aria-label. Provide exactly one of `label` or `labelledBy`.                             |
-| `labelledBy` | `string`   | no       | —       | ID of an existing element whose text labels the group, applied as aria-labelledby. Provide exactly one of `label` or `labelledBy`. |
-| `children`   | `(opaque)` | no       | —       | DropdownLabel plus grouped DropdownItem rows. Not expressible in JSON Schema; see the component types for the signature.           |
-
-<!-- generated:props:end -->
-
-## CSS Variables
-
-<!-- generated:variables:start -->
-
-This component does not declare any local CSS variables.
-
-<!-- generated:variables:end -->
-
-## Subcomponents
-
-<!-- generated:subcomponents:start -->
-
-None.
-
-<!-- generated:subcomponents:end -->

package/src/components/dropdown-item/README.md

@@ -1,46 +0,0 @@
-# DropdownItem
-
-Selectable item within a dropdown menu, supporting icons, labels, and keyboard navigation.
-
-## Usage
-
-`DropdownItem` is a compose-only leaf of [`Dropdown`](../dropdown/README.md).
-The idiomatic API is `Dropdown.Item`, reached through the parent
-namespace — see the [dropdown README](../dropdown/README.md#usage) for the composed
-snippet. The flat `@lostgradient/cinder/dropdown-item` subpath remains exported for
-à-la-carte builds that import the leaf directly.
-
-## Props
-
-<!-- generated:props:start -->
-
-| Prop            | Type                                  | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| --------------- | ------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `checked`       | `boolean`                             | no       | —       | Checked state for `itemRole="menuitemradio"`. Omitted for normal menu items.                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `class`         | `string`                              | no       | —       | Additional class names merged with the component's root class.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `closeOnSelect` | `boolean`                             | no       | —       | When true, the parent dropdown closes after this item is activated. Default `true`.                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `disabled`      | `boolean`                             | no       | —       | When true the item is inert: click is blocked and aria-disabled is set.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `href`          | `string`                              | no       | —       | Destination URL. Any defined value — including an empty string — selects the anchor branch and renders an `<a>`. Omit `href` entirely to render a `<button>`.                                                                                                                                                                                                                                                                                                                                             |
-| `inset`         | `boolean`                             | no       | —       | When true, adds leading padding to align the item with items that have a leading icon or indicator. Default `false`.                                                                                                                                                                                                                                                                                                                                                                                      |
-| `itemRole`      | `"menuitem"` \| `"menuitemradio"`     | no       | —       | ARIA role for the row. Use `menuitemradio` for mutually exclusive menu selections.                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `type`          | `"button"` \| `"submit"` \| `"reset"` | no       | —       | Button type forwarded to the `<button>` element. Defaults to `"button"`. NOTE: `type="submit"` only submits a surrounding `<form>` when the menu stays inside that form's DOM subtree. DropdownMenu portals its panel to `document.body` on the non-popover fallback path, so a submit item is then NOT a form descendant and native submission is skipped. To submit a form from a portaled menu, set `form="<form-id>"` to associate the button with the form by id, or handle submission in `onclick`. |
-| `variant`       | `"default"` \| `"danger"`             | no       | —       | Visual style of the item. Use `danger` to signal a destructive action. Default `default`.                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `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.                                                                                                                                                                                                                                                                                                                                                                                |
-
-<!-- generated:props:end -->
-
-## CSS Variables
-
-<!-- generated:variables:start -->
-
-This component does not declare any local CSS variables.
-
-<!-- generated:variables:end -->
-
-## Subcomponents
-
-<!-- generated:subcomponents:start -->
-
-None.
-
-<!-- generated:subcomponents:end -->