@d4gger/design-system 3.0.1 → 4.0.1

package/dist/docs/components/comment-thread.md

@@ -15,6 +15,56 @@ Controlled one-reply-level discussion UI. Data, relative-time localization, mode
 
 `CommentThread.Root`, `Comment`, `Replies`, `Tombstone`, `Composer`, and `Locked`. Comment renders avatar initials or image, author badge content, semantic `time`, body, and report/reply actions. Composer owns no remote state and exposes value, character limit, locked, and submission state. Tombstones remain visibly present to preserve thread structure.
 
+- Root forwards native div attributes/ref. Comment forwards article attributes/ref;
+  `author` and `dateTime` are strings, `timeLabel`, `badge`, `actions` and body accept
+  React nodes, and `avatarSrc` optionally replaces initials with a decorative image.
+- Replies forwards native div attributes/ref and defaults to role group. One nested
+  reply level is supported; a second Replies inside Replies throws explicitly.
+- Tombstone defaults to `Comment removed`, role status and `data-removed="true"`.
+  Locked defaults to `Comments are locked` and role status. Both accept custom children.
+- Composer forwards form attributes/ref while managing submission. `value` and
+  `onValueChange` are required; `onSubmit`, `maxLength` (default 2000), `locked` and
+  `submitting` are optional. It prevents native navigation and calls onSubmit only
+  for nonblank, within-limit, valid, unlocked, non-submitting content. The app owns asynchronous work.
+- Its controlled native textarea has the default accessible name `Comment` and an
+  associated polite character counter. Locked/submitting disables editing; submitting
+  sets form `aria-busy`. Default submit composes the large DS Button, disabled for
+  empty/locked/submitting content. Custom children replace that default action.
+
+## Paint and containment
+
+Comment uses an avatar column and a zero-minimum content track. Author metadata and
+actions and action labels wrap intrinsically; long body words wrap. Body/actions remain in the content
+column and Replies retains its logical-start indent. No component breakpoint is used.
+
+Composer textarea explicitly fits its parent, uses body-medium typography, keeps
+native vertical resize, and consumes the existing focus ring and disabled roles.
+The `dsx-comment-thread__count` and `dsx-comment-thread__submit` classes identify
+the counter and default action. Button owns focus/pressed/disabled treatment and
+target dimensions (44px at comfortable density). The component adds no motion.
+
 ## Playground demo spec
 
-Show initials and image avatars, badge and time, one reply level, report/reply actions, character count, submitting/locked composers, and a removed tombstone.
+`/docs/comment-thread` composes `blocks-examples.tsx` through the display registry.
+It shows initial/image avatars, author badge/time, one reply level, report/reply
+actions and a removed tombstone. The controlled composer updates its count, shows
+submitting, adds a local comment, and can be locked/unlocked. Separate submitting
+and locked examples remain visible. All demo persistence and action feedback is
+playground-owned; no network or moderation service is implied.
+
+## Discussion enhancement — approved 2026-10-04
+
+`Composer` adds `input(context)` to replace the textarea without duplication,
+`label`, `error`, `status` and `actions`. Context supplies `id`, `value`,
+`onValueChange`, `maxLength`, `disabled`, `describedBy` and `invalid` for accessible
+custom controls. Children retain their existing submit-action override. Count,
+error and status are associated with the input. Blank, over-limit, submitting,
+locked or invalid drafts cannot submit. Consumers own rich-text plain count and
+validation. `Comment.metadata` supports edited state.
+
+`Replies` adds optional `limit`, controlled/uncontrolled `expanded`,
+`onExpandedChange` and `moreLabel`; defaults still show all children. Exactly one
+reply level remains supported. `Tombstone.state` distinguishes `hidden`,
+`removed` and `deleted`, with localized children. Legacy `data-removed` persists.
+Support is demonstrated as a linear composition with a restricted rich editor,
+separate FileUpload/attachments, visibility and failed-send retry, not nested replies.

package/dist/docs/components/config-drawer.md

@@ -4,7 +4,7 @@ status: canonical
 category: Foundations
 archetype: composite
 depends_on:
-  - Sheet
+  - Drawer
   - IconButton
   - Icon
   - SegmentedControl
@@ -18,205 +18,106 @@ depends_on:
 
 # ConfigDrawer
 
-> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+> Source of truth: package source; this spec mirrors its public contract.
 
 ## Purpose
 
-A right-anchored preferences drawer that exposes the live theme controls: appearance mode, accent color, gray palette, radius, density, and scaling. `ConfigDrawer` is the editor half of the theme configuration surface; `ThemePanel` is the read-only inspector. The two share a design language but solve different problems. `ConfigDrawer` reads and writes the active `ThemeProvider` context, so it must be rendered inside a `ThemeProvider` tree.
+One preferences drawer inside ThemeProvider, exposing Theme, Accent, Gray,
+Radius, Density, Scaling and Panel BG. Values and persistence belong to
+ThemeProvider; the drawer supplies their controls. Default side is right.
 
 ## Anatomy & slots
 
-**Parent:** `ConfigDrawer`. The root is a `Sheet` (`Sheet.Root` + `Sheet.Trigger` + `Sheet.Content side="right"`). The drawer is a single function component, not a compound; the consumers do not import any `ConfigDrawer.<Slot>` parts. The internal layout is a vertical `Flex` of `SettingRow` instances separated by `Separator`s.
-
-**Internal regions:**
-
-| Region | Element | Renders | Notes |
-|---|---|---|---|
-| Trigger | `Sheet.Trigger` rendered as `IconButton` (default) or consumer-supplied `trigger` | `dsx-config-drawer__trigger` (class is added when the default trigger renders) | Default trigger is an `IconButton variant="ghost" size="md"` with `aria-label="Open preferences"` and a `settings` `Icon` (size `md`). Consumers can pass a `trigger` prop to replace the default. |
-| Header | `Sheet.Header` + `Sheet.Title` | (inherits `Sheet` styles) | "Preferences" title. |
-| Body | `Flex direction="column" gap="lg"` | `dsx-config-drawer__body` | Scrollable column of `SettingRow` + `Separator` regions. |
-| SettingRow | `Flex direction="row" justify="between" align="center" gap="md"` | `dsx-config-drawer__row` | A label / description / control triplet. The label is a `Label` element; the description (when present) is a `Text variant="label-small" tone="muted"`; the control is whatever the consumer passes as `children`. |
-| SettingRow info | `Flex direction="column" gap="1"` | `dsx-config-drawer__row-info` | The left column of the row, containing the `Label` and the description. |
-| SettingRow control wrapper | `<div>` | `dsx-config-drawer__row-control` | The right column of the row, wrapping the control. |
-| Accent preview swatch | `<span aria-hidden="true">` | `dsx-config-drawer__accent-swatch` + `data-tier` | Non-interactive preview of each accent tier. It does not write `data-accent-color`, because the swatch represents a color value rather than consuming theme scope. |
-| Scaling input (specific) | `NumberInput` | `dsx-config-drawer__scaling-input` | The scaling control. Sized to `7ch` so the percentage fits without breaking the row rhythm. |
-
-**Internal layout:**
-
-- The default trigger is a ghost `IconButton` with a `settings` icon. Passing the `trigger` prop replaces it entirely.
-- The body is a single scrollable column. Each `SettingRow` is a `flex-direction: row` with `justify-content: space-between`, so the label and control sit on opposite ends of the row.
-- The six default rows (Theme, Accent, Gray, Radius, Density, Scaling) are separated by `Separator` components from the package. The order is fixed and reflects the dependency direction: appearance first, then accent, then gray, then radius, then density, then scaling.
-- Each row's control is a `SegmentedControl` (for the categorical tokens) or a `NumberInput` (for the scaling percentage). The control is wrapped in a `<div class="dsx-config-drawer__row-control">` so it stays right-aligned without leaking the `gap` into the control itself.
+Flat export composing lazily loaded Drawer, Trigger, Content, Header, Title and
+Description. No ConfigDrawer compound slots. Default trigger is an inline ghost
+IconButton size md, named “Open preferences”, with settings Icon. The host owns
+positioning. Title is “Preferences”; VisuallyHidden wraps the DrawerDescription.
+Body composes Flex, Label, Text, SegmentedControl, NumberInput and Separator.
 
 ## Props contract
 
-**Root props (`ConfigDrawer`):**
-
-| Prop | Type | Default | Required | Description | Responsive |
-|---|---|---|---|---|---|
-| `open` | `boolean` | `undefined` | no | Controlled open state. Pass alongside `onOpenChange` to own the open flag. | no |
-| `defaultOpen` | `boolean` | `false` | no | Uncontrolled initial open state. | no |
-| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Callback fired when the underlying `Sheet` open state changes. | no |
-| `trigger` | `ReactNode` | default `IconButton` (see above) | no | Custom trigger element. Rendered through `Sheet.Trigger asChild`. | no |
-
-The root does not accept `asChild` directly; consumers can swap the host element by passing a `trigger` or by wrapping the rendered output themselves. The internal `Sheet.Content` is locked to `side="right"`; left-side drawers are out of scope for this component.
-
-**SettingRow props (internal, not exported):**
-
-| Prop | Type | Default | Required | Description | Responsive |
-|---|---|---|---|---|---|
-| `label` | `string` | (none) | **yes** | The label rendered as a `Label` element on the left. | no |
-| `description` | `string` | `undefined` | no | Optional helper text rendered under the label as a muted `Text`. | no |
-| `children` | `ReactNode` | (none) | **yes** | The control rendered on the right (typically a `SegmentedControl` or `NumberInput`). | no |
-
-`SettingRow` is an internal helper; consumers do not compose their own rows. The six default rows are wired inside the component.
-
-## CSS class contract
-
-**Root class:** none at the component level. The component composes `Sheet` (which owns the panel chrome) and the `dsx-config-drawer__*` classes below.
+| Prop | Type | Default | Description | Responsive |
+|---|---|---|---|---|
+| open | boolean | undefined | Controlled open state. | no |
+| onOpenChange | (open: boolean) => void | undefined | Open-state callback. | no |
+| defaultOpen | boolean | false | Uncontrolled initial state. | no |
+| trigger | ReactNode | inline IconButton | Custom trigger via DrawerTrigger asChild. | no |
+| side | top / right / bottom / left | right | Passed to Drawer direction. | no |
+| children | ReactNode | undefined | Host content after built-in rows. | no |
 
-**Slot classes:**
+Categorical controls are SegmentedControl type single, size sm:
 
-| Slot / region | Class | CSS file |
+| Row | Accessible name | Choices |
 |---|---|---|
-| Body | `dsx-config-drawer__body` | `config-drawer.css` |
-| Default trigger | `dsx-config-drawer__trigger` | (added at the className level on the default `IconButton`; no rule in the CSS file currently) |
-| Setting row | `dsx-config-drawer__row` | `config-drawer.css` |
-| Setting row info column | `dsx-config-drawer__row-info` | `config-drawer.css` |
-| Setting row control wrapper | `dsx-config-drawer__row-control` | `config-drawer.css` |
-| Accent preview swatch | `dsx-config-drawer__accent-swatch` | `config-drawer.css` |
-| Scaling `NumberInput` | `dsx-config-drawer__scaling-input` | `config-drawer.css` |
+| Theme | Theme mode | Light / Dark / System |
+| Accent | Accent color | Rift / Warp / Ray / Astral / Spark |
+| Gray | Gray color | Auto / Neutral |
+| Radius | Border radius | None / Small / Medium / Large / Full |
+| Density | Density | Comfortable / Compact |
+| Scaling | Scaling percentage | NumberInput, 90–110%, rounded to steps of 5 |
+| Panel BG | Panel background | Translucent / Solid |
 
-**Responsive behavior:**
+SettingRow is internal: label, optional description, children. Visible labels
+are visual cues; each control has its own programmatic name.
 
-- The component does not write `@media` rules. On narrow viewports the consumer can swap in a different sheet side or a full-screen `Sheet`; `ConfigDrawer` is fixed to a right-anchored panel.
-
-**Reduced motion:**
+## CSS class contract
 
-- The component itself does not animate. Open / close transitions on the wrapping `Sheet` are owned by the `Sheet` component and respect `prefers-reduced-motion` through the standard `MOTION_TRANSITIONS.sheet` preset.
+| Region | Class |
+|---|---|
+| Body | dsx-config-drawer__body |
+| Row | dsx-config-drawer__row |
+| Information | dsx-config-drawer__row-info |
+| Control | dsx-config-drawer__row-control |
+| Swatch | dsx-config-drawer__accent-swatch |
+| Scaling | dsx-config-drawer__scaling-input |
+
+Rows always wrap. Information has min-width 0; controls have min-width 0 and
+max-width 100%. Long categorical groups retain SegmentedControl's own horizontal
+scrolling, including keyboard reveal. Drawer bounds and vertical scrolling use
+the shared Drawer contract. No package width breakpoints.
 
 ## Token mapping
 
-Every CSS value the component paints is a `var(--dsx-*)` token.
+| Property | Token |
+|---|---|
+| Body gap / padding | --dsx-space-lg / --dsx-space-md |
+| Row gap / minimum height | --dsx-space-md / --dsx-size-lg |
+| Information gap | --dsx-space-2xs |
+| Swatch size / gap / radius | --dsx-space-sm / --dsx-space-xs / --dsx-radius-full |
+| Swatch fill | --dsx-color-accent-{rift,warp,ray,astral,spark}-9 |
+| Scaling width | 7ch |
 
-| Property | Token | Role |
-|---|---|---|
-| Body gap | `var(--dsx-space-lg)` | Vertical gap between rows |
-| Body padding | `var(--dsx-space-md) 0` | Vertical padding around the body |
-| Body overflow | `auto` | Vertical scroll when content overflows |
-| Row min-height | `var(--dsx-size-lg)` | Min hit target |
-| Row gap | `var(--dsx-space-md)` | Horizontal gap between info and control |
-| Row info gap | `var(--dsx-space-2xs)` | Vertical gap inside the info column |
-| Accent preview size | `var(--dsx-space-sm)` | Square preview swatch dimensions |
-| Accent preview spacing | `var(--dsx-space-xs)` | Gap between the preview and tier label |
-| Accent preview radius | `var(--dsx-radius-full)` | Circular preview shape |
-| Accent preview fill | `var(--dsx-runtime-accent-{rift,warp,ray}-9)` | Exact value represented by each theme choice |
-| Scaling input width | `7ch` | Fixed width for the percentage `NumberInput` |
-
-The default trigger is an `IconButton`; its visual contract is owned by `IconButton`. The row labels use the `Label` component; their visual contract is owned by `Label`. The segmented controls use the `SegmentedControl` component; their visual contract is owned by `SegmentedControl`.
+Controls, separators and panel chrome retain their own component token contracts.
 
 ## Motion contract
 
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| Sheet open / close | inherited from `Sheet` (`MOTION_TRANSITIONS.sheet`) | sheet preset | reduced |
+Inherited Drawer motion uses MOTION_TRANSITIONS.drawer and reduced fallback.
+ConfigDrawer adds no animation.
 
-The component itself has no motion. The wrapping `Sheet` handles open / close transitions through the standard sheet preset and the `reduced` fallback.
+Rows explicitly compose Flex with wrap="wrap". Row descriptions use a
+max-content flex basis so they retain readable width when the controls wrap. Controls keep their natural width
+within a 100% cap, move below the row description when needed and retain the
+existing SegmentedControl scroll behavior for long choice rails.
 
 ## Accessibility
 
-**Roles:**
-
-- The panel is a `Sheet`, which renders with the standard `role="dialog"` plus `aria-modal` and a labelled-by pointer to the `Sheet.Title`. The title is "Preferences".
-- Each `SegmentedControl` is a `radiogroup` (for `type="single"`) or a `group` of toggles (for `type="multiple"`). The ConfigDrawer uses `type="single"` for all categorical tokens. The `NumberInput` for scaling is a `textbox` with an `aria-label="Scaling percentage"`.
-- The `SettingRow` `Label` is a `<label>` element. Because the controls sit inside the same row rather than as direct label children of the controls, the `aria-label` on each control is the source of truth for the accessible name. The visible `Label` is a visual cue, not a programmatic association.
-
-**Keyboard:**
-
-| Key | Action |
-|---|---|
-| `Tab` | Moves focus through the trigger, the segmented controls, the scaling input, and the sheet close affordance. |
-| `ArrowLeft` / `ArrowRight` | Navigates within a `SegmentedControl` (radiogroup semantics). |
-| `Enter` / `Space` | Activates the focused segmented option or input. |
-| `Escape` | Closes the `Sheet` and returns focus to the trigger. |
-
-**Focus:**
-
-- The `Sheet` is a modal: focus is trapped inside the drawer while it is open and returned to the trigger on close.
-- Each `SegmentedControl` is a roving-focus radiogroup: arrow keys move between options; the focused option gets a visible ring.
-- The `NumberInput` exposes the standard textbox focus ring.
-
-**Reduced motion:**
-
-- Open / close transitions respect `prefers-reduced-motion` through the standard `Sheet` motion contract.
-
-**Color and meaning:**
-
-- The selected `SegmentedControl` option tracks `--dsx-color-primary`. The control itself does not impose additional color cues.
-- The scaling `NumberInput` is a standard numeric entry; no color meaning.
-
-**Naming:**
-
-- Each `SegmentedControl` and the `NumberInput` carry an `aria-label` ("Theme mode", "Accent color", "Gray color", "Border radius", "Density", "Scaling percentage"). The visual `Label` repeats the same string so sighted and screen-reader users get the same word.
-- The drawer title is "Preferences".
+Drawer supplies modal dialog semantics, title/description, focus trapping and
+Escape dismissal with focus return. SegmentedControl supplies single selection
+and roving keyboard navigation; NumberInput supplies numeric entry. Enter/Space
+activate the trigger. The playground's draggable trigger separately preserves
+keyboard activation and suppresses clicks after pointer dragging.
 
 ## Playground demo spec
 
-**Default story:**
-
-- The playground registry does not render `ConfigDrawer` inline because the drawer is already mounted at the app root and a second instance would conflict with the active one. The registry render shows a description of the usage and the canonical placement (alongside `ThemeProvider` at the app root).
-
-**Variant story:** N/A. The component has no variants; the layout is fixed.
-
-**State story:**
-
-- Renders the drawer with `defaultOpen` and confirms the six rows appear with the correct default selections (`System`, `Rift`, `Auto`, `Medium`, `Comfortable`, `100`).
-- Renders the drawer with `open` (controlled) and confirms the same.
-- Renders a custom `trigger` and confirms the custom trigger is rendered when the drawer is closed.
-
-**Composition story:**
-
-- The component owns its own composition. The composition story is the default render: header + six rows + separators.
-
-**Token story:**
-
-- Renders the default drawer inside a `Theme` wrapper with `accentColor="warp"` and `accentColor="ray"`. Asserts the active segmented option tracks `--dsx-color-primary` while each accent preview continues to show the exact tier it represents.
-
-**A11y story:**
-
-- Uses `vitest-axe` against the rendered default story with the `aria-allowed-attr` rule disabled (the `SegmentedControl` ships a non-standard `variant` attribute on `role="group"`). Asserts no other axe violations.
-
-**Props exposed in the playground controls:**
-
-The playground registry for `config-drawer` does not expose prop controls. The component is mounted live at the app root; the registry render explains that placement and notes the `trigger` prop.
+The registry explains usage and lists all seven rows. The live example is the
+single app-root drawer opened with the bottom-right gear; that host uses side
+bottom. Test Light/Dark, every accent, gray palettes, radius, density, scaling
+and panel background at 1280/390/320, including the last row after scrolling.
+No duplicate drawer is mounted just to obtain a screenshot.
 
 ## Wiring notes
 
-**Composes from:**
-
-- `Sheet` (`src/components/sheet/Sheet`): the entire panel chrome. The drawer uses `Sheet.Trigger asChild` for the trigger, `Sheet.Content side="right"` for the panel, and `Sheet.Header` + `Sheet.Title` for the title row.
-- `IconButton` (`src/components/iconButton/IconButton`): the default trigger.
-- `Icon` (`src/components/icon/Icon`): the default `settings` icon.
-- `Label` (`src/components/label/Label`): the row label.
-- `Text` (`src/components/text/Text`): the row description.
-- `Flex` (`src/layout/Flex`): the row layout and the body layout.
-- `SegmentedControl` (`src/components/segmentedControl/SegmentedControl`): the categorical token pickers. The drawer uses `type="single"` and `size="sm"`.
-- `Separator` (`src/components/separator/Separator`): the row separators.
-- `NumberInput` (`src/components/numberInput/NumberInput`): the scaling percentage input, clamped to the 90 to 110 range in 5% steps.
-- `ThemeProvider` (`src/components/themeProvider/ThemeProvider`): the drawer reads and writes the active theme through `useTheme()`. The drawer must be rendered inside a `ThemeProvider` tree.
-
-**Used by:**
-
-- The playground's app shell mounts a single `ConfigDrawer` alongside `ThemeProvider` so every page can toggle the theme without a dedicated settings route.
-- App-level settings surfaces and onboarding flows.
-
-**State boundaries:**
-
-- Owned by ConfigDrawer: the six default rows, their order, the accent previews, and the `SettingRow` layout.
-- Owned by the consumer: the placement of the drawer, the custom `trigger` (if any), the controlled `open` / `onOpenChange` (if any), and the surrounding `ThemeProvider`.
-- Owned by `useTheme()`: every categorical selection (`theme`, `accentColor`, `grayColor`, `radius`, `density`, `scaling`) is read from and written to the active `ThemeProvider` context. The drawer does not own the value; it surfaces the control.
-
-**Boundary rules:**
-
-- App-owned data: the placement of the drawer, the controlled open state, the custom trigger, and the surrounding `ThemeProvider`.
-- DS-owned visuals: token bindings, slot classes, the `Sheet` panel chrome, the segmented control semantics, the `NumberInput` clamping, and the row layout.
+Drawer owns the portal, bounds and focus. ThemeProvider owns selections,
+persistence and system mode. The host owns placement, custom trigger, side,
+controlled open state and optional children. ConfigDrawer owns fixed row order,
+swatches and the numeric scaling clamp. ThemePanel remains the read-only inspector.

package/dist/docs/components/container.md

@@ -153,6 +153,8 @@ Container has no motion. The motion section is intentionally empty.
 
 ## Playground demo spec
 
+The default container retains its 1080px cap; size 1 and wide show 420px and 1200px caps respectively.
+
 **Default story:**
 
 - Renders `Container` with no extra props and a child node. Asserts the root classes are `dsx-container` and `dsx-box` (the `dsx-flex` class is conditional — it is only written when a flex layout prop such as `direction`, `align`, `justify`, `gap`, or `wrap` is set), the host element is a `div`, and `--dsx-container-max-width` resolves to `1080px`.

package/dist/docs/components/context-menu.md

@@ -33,13 +33,13 @@ An object-scoped right-click action menu. The DS `ContextMenu` wraps `@radix-ui/
 | `ContextMenu.Label` | Radix `ContextMenu.Label` | `dsx-context-menu__label` | Non-interactive section label. |
 | `ContextMenu.Separator` | Radix `ContextMenu.Separator` (via `MenuSeparator`) | `dsx-context-menu__separator` | Visual divider. |
 | `ContextMenu.Group` | Radix `ContextMenu.Group` | (no class) | Groups items semantically. |
-| `ContextMenu.Sub` | Radix `ContextMenu.Sub` | (no class) | Submenu owner. |
+| `ContextMenu.Sub` | Radix `ContextMenu.Sub` + `ContextMenuSubOpenContext` | (no class) | Submenu owner; mirrors controlled/uncontrolled state into SubContent. |
 | `ContextMenu.RadioGroup` | Radix `ContextMenu.RadioGroup` | (no class) | Radio selection owner. |
 | `ContextMenu.Portal` | Radix `ContextMenu.Portal` (via `MenuPortal`) | (no class) | Portal wrapper. |
 | `ContextMenu.CheckboxItem` | Radix `ContextMenu.CheckboxItem` | `dsx-context-menu__item` + `dsx-context-menu__item-indicator` | Checkbox row. Renders `check` or `minus` indicator. |
 | `ContextMenu.RadioItem` | Radix `ContextMenu.RadioItem` | `dsx-context-menu__item` + `dsx-context-menu__item-indicator` + `dsx-context-menu__radio-dot` | Radio row. |
 | `ContextMenu.SubTrigger` | Radix `ContextMenu.SubTrigger` | `dsx-context-menu__item` + `dsx-context-menu__sub-trigger` + optional `data-inset` + `chevron-right` | Row that opens the sub-content. |
-| `ContextMenu.SubContent` | Radix `ContextMenu.SubContent` inside `MenuContent` (no portal) | `dsx-context-menu__content` | The submenu panel. `MenuContent` is invoked with `forceMount`, `open`, and `portal === null` so the sub-content renders inline. |
+| `ContextMenu.SubContent` | Radix `ContextMenu.SubContent` inside portalled `MenuContent` | `dsx-context-menu__content` | The submenu panel follows Sub's open state outside the parent's clip box. Explicit `forceMount` is preserved. |
 | `ContextMenu.Shortcut` | `<span>` (or `Slot` child when `asChild`) | `dsx-context-menu__shortcut` | Keyboard hint rendered on the right. |
 
 The roster's `Parent / Slots` column lists `ContextMenu.Root`, `ContextMenu.Trigger`, `ContextMenu.Content`, `ContextMenu.Label`, `ContextMenu.Separator`, `ContextMenu.Item`, `ContextMenu.Group`. The source exports the full Radix part set through `Object.assign`, including `Sub`, `RadioGroup`, `Portal`, `CheckboxItem`, `RadioItem`, `SubTrigger`, `SubContent`, and `Shortcut`. The spec records the full set so the public surface is unambiguous.
@@ -69,7 +69,7 @@ The roster's `Parent / Slots` column lists `ContextMenu.Root`, `ContextMenu.Trig
 
 ### `ContextMenu.Trigger`, `ContextMenu.Label`, `ContextMenu.Separator`, `ContextMenu.Group`, `ContextMenu.Sub`, `ContextMenu.RadioGroup`, `ContextMenu.Portal`, `ContextMenu.CheckboxItem`, `ContextMenu.RadioItem`, `ContextMenu.SubTrigger`, `ContextMenu.SubContent`
 
-These proxy the corresponding Radix props. `ContextMenu.Trigger` accepts the standard Radix trigger props (no class). `ContextMenu.Label` and `ContextMenu.Group` accept the standard Radix props. `ContextMenu.SubContent` accepts the same `align`, `side`, and `sideOffset` props as `Content`; the portal is forced to `null` so the sub-content renders inline.
+These preserve the corresponding Radix props. `ContextMenu.Trigger` accepts standard Radix trigger props and adds the keyboard opening path below. `ContextMenu.Label` and `ContextMenu.Group` accept standard Radix props. `ContextMenu.Sub` preserves controlled `open`, uncontrolled `defaultOpen` and `onOpenChange`. `ContextMenu.SubContent` preserves Radix positioning and `forceMount` props and renders through a theme-preserving portal.
 
 ### `ContextMenu.Item`
 
@@ -194,13 +194,13 @@ Rules:
 - `ContextMenu.Item` is `role="menuitem"`. `ContextMenu.CheckboxItem` is `role="menuitemcheckbox"`; `ContextMenu.RadioItem` is `role="menuitemradio"`. `ContextMenu.SubTrigger` is `role="menuitem"` with `aria-haspopup="menu"`.
 - `ContextMenu.Label` is `role="presentation"` for non-interactive section labels (Radix default).
 - `ContextMenu.Separator` is `role="separator"`.
-- `ContextMenu.Trigger` is the right-click target; it is typically a non-semantic element that owns the context-menu event.
+- `ContextMenu.Trigger` captures right-click and touch long-press. A custom non-interactive host must supply `tabIndex={0}` for keyboard opening. The wrapper forwards the Radix trigger props and ref. Essential touch actions should also have an explicit button/menu composition; long-press alone is not discoverable.
 
 **Keyboard:**
 
 | Key | Action |
 |---|---|
-| `Shift+F10`, context-menu key | Opens the context menu (browser-default). |
+| `Shift+F10`, context-menu key | Opens the menu at the focused trigger's center. The wrapper supplies the context event consistently across browsers; a consumer-cancelled key handler is respected. |
 | `ArrowDown`, `ArrowUp` | Moves through items. |
 | `Enter`, `Space` | Activates the focused item. |
 | `Escape` | Closes the menu. |
@@ -282,3 +282,17 @@ Rules:
 
 - App-owned data: the command set, the disabled reasons, the right-click target, and the keyboard shortcut strings.
 - DS-owned visuals: the `dsx-context-menu__*` slot classes, the token bindings, the data-attribute contract, and the open / close animation.
+
+## Reconciliation stories
+
+`Sub` preserves Radix's controlled `open`, uncontrolled `defaultOpen`, and
+`onOpenChange` contract. `SubContent` follows that state and renders in its own
+theme-preserving portal, outside the root's scroll/clip box. Closed submenus
+are unmounted unless the consumer explicitly requests `forceMount`; they do not
+leave inaccessible menu items behind the parent surface.
+
+The panel's usual minimum width is capped by Radix's available width. A submenu
+can become narrower when neither side has room for the usual menu width; labels
+wrap rather than painting off the viewport. No viewport breakpoint is involved.
+
+The live example uses a real Project actions button for explicit activation, right-click and keyboard opening. It demonstrates selection feedback, a disabled item, a controlled checkbox and radio group, a submenu and a destructive action. Shortcut hints are labels; item callbacks own the action.

package/dist/docs/components/dialog.md

@@ -180,7 +180,7 @@ Rules:
 | Close button size | `var(--dsx-size-lg)` | Square tap target. |
 | Close button radius | `var(--dsx-rounded-full)` | Round close. |
 | Close button offset | `var(--dsx-space-md)` | Distance from the corner. |
-| Backdrop blur | `var(--dsx-blur-md, 8px)` | Optional blur. |
+| Backdrop blur | `var(--dsx-blur-md, 8px)` | Optional blur. `-webkit-backdrop-filter` is declared before `backdrop-filter` so the bundler keeps the standard line (see `card.md`, B-1). |
 | Title typography | `var(--dsx-typography-headline-medium-*)` | Title. |
 | Description typography | `var(--dsx-typography-body-medium-*)` | Description. |
 | Description color | `var(--dsx-color-on-surface-variant)` | Body copy. |
@@ -239,6 +239,8 @@ Rules:
 
 ## Playground demo spec
 
+The live connection-settings example uses the package Select for Region and a nested Popover for display density. Apply closes only the child popover; Save region reports the selected value and returns focus to the dialog launcher. Long-content mode verifies reachable body and footer controls.
+
 **Default story:**
 
 - Renders `DialogRoot` with a `Trigger` and `Content` containing `Header`, `Body`. Asserts the content has `dsx-dialog__content` and `data-size="md"`.
@@ -274,7 +276,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. Asserts the `data-accent-color` attribute on the content wrapper.
+- Renders inside a `Theme` wrapper with `accentColor="rift"` and one with `accentColor="warp"`. Asserts the `data-accent-color` attribute on the content wrapper.
 
 **Props exposed in the playground controls:**
 

package/dist/docs/components/drawer.md

@@ -51,8 +51,6 @@ A mobile or edge-attached modal overlay that slides in from any edge of the view
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Drawer content size; writes `data-size` attribute. | no |
-| `height` | `string` (responsive) | `undefined` | no | Responsive height override via CSS variable. | yes |
-| `width` | `string` (responsive) | `undefined` | no | Responsive width override via CSS variable. | yes |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-drawer__content`. | no |
 
 **Header props:**
@@ -76,7 +74,7 @@ Standard Radix `Title` and `Description` props plus `className`.
 Rules:
 
 - `direction` on Root is wired through `extractProps`.
-- `size`, `height`, and `width` on Content are wired through `extractProps`.
+- `size` on Content are wired through `extractProps`.
 - `asChild` on Header and Footer is wired through `extractProps`.
 - The Root manages open state through a controllable hook (`useControllableDrawerOpenState`) that supports both controlled and uncontrolled modes.
 - The Root provides `DrawerOpenContext` and `DrawerDirectionContext` so Content can access the open state and direction for motion calculations.
@@ -102,12 +100,12 @@ Rules:
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-direction` (on content) | `top`, `right`, `bottom`, `left` | `.dsx-drawer__content[data-direction='...']` | `drawer.css` |
-| `data-size` (on content) | `sm`, `md`, `lg` | (no CSS rules in source; reserved for consumer extension) | n/a |
+| `data-size` (on content) | `sm`, `md`, `lg` | Top/bottom minimum-height and side-panel width bands | n/a |
 | `data-slot` | `drawer-overlay`, `drawer-content`, `drawer-handle`, `drawer-header`, `drawer-footer`, `drawer-title`, `drawer-description` | (CSS hook only) | n/a |
 
 **Responsive behavior:**
 
-- Content `height` and `width` props are responsive via CSS variables (`--dsx-r-height`, `--dsx-r-width`).
+- Content size is single-valued. It does not expose responsive height/width props. Viewport caps and scrolling are intrinsic.
 
 **Reduced motion:**
 
@@ -208,7 +206,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Drawer does not track `data-accent-color` directly; the story asserts the overlay and content surfaces are visually unchanged.
+- Renders inside a `Theme` wrapper with `accentColor="astral"` and `accentColor="spark"`. Drawer does not track `data-accent-color` directly; the story asserts the overlay and content surfaces are visually unchanged.
 
 **A11y story:**
 
@@ -243,3 +241,16 @@ Rules:
 
 - App-owned data: the drawer content, the trigger label, the action handlers, and the open state when controlled.
 - DS-owned visuals: token bindings, the slot CSS classes, the motion presets, and the portal theme mirroring.
+
+## Overlay review containment
+
+Content caps at 100dvh and its containing viewport width, wraps long words,
+and scrolls vertically. Direct content regions do not shrink into each other.
+Left/right content uses height=100dvh with min-height=0 and width bands capped
+at 100%; top/bottom content retains its minimum-height size bands. No width
+media query is required. `/docs/drawer` opens all four directions and offers
+short/long content to verify both the first row and the footer after scrolling.
+
+The package disables Vaul’s offscreen ::after filler on its scrolling shell.
+That pseudo-element otherwise adds blank scroll range and covers bottom-drawer
+footer controls after scrolling; it is unnecessary for the bounded surface.

package/dist/docs/components/dropdown-menu.md

@@ -39,7 +39,7 @@ A button-triggered secondary action menu. The DS `DropdownMenu` wraps `@radix-ui
 | `DropdownMenu.CheckboxItem` | Radix `DropdownMenu.CheckboxItem` | `dsx-dropdown-menu__item` + `dsx-dropdown-menu__item-indicator` | Checkbox row. Renders `check` or `minus` indicator. |
 | `DropdownMenu.RadioItem` | Radix `DropdownMenu.RadioItem` | `dsx-dropdown-menu__item` + `dsx-dropdown-menu__item-indicator` + `dsx-dropdown-menu__radio-dot` | Radio row. |
 | `DropdownMenu.SubTrigger` | Radix `DropdownMenu.SubTrigger` | `dsx-dropdown-menu__item` + `dsx-dropdown-menu__sub-trigger` + optional `data-inset` + `chevron-right` | Row that opens the sub-content. |
-| `DropdownMenu.SubContent` | Radix `DropdownMenu.SubContent` inside `MenuContent` (no portal) | `dsx-dropdown-menu__content` | The submenu panel. `MenuContent` is invoked with `forceMount`, `open`, and `portal === null` so the sub-content renders inline. |
+| `DropdownMenu.SubContent` | Radix `DropdownMenu.SubContent` inside portal-mounted `MenuContent` | `dsx-dropdown-menu__content` | The submenu panel tracks its own Sub open state and uses a portal so the parent scroll frame does not clip it. forceMount remains consumer-controlled. |
 | `DropdownMenu.Shortcut` | `<span>` (or `Slot` child when `asChild`) | `dsx-dropdown-menu__shortcut` | Keyboard hint rendered on the right. |
 
 The roster's `Parent / Slots` column lists `DropdownMenu.Root`, `DropdownMenu.Trigger`, `DropdownMenu.Content`, `DropdownMenu.Label`, `DropdownMenu.Separator`, `DropdownMenu.Item`, `DropdownMenu.Group`. The source exports the full Radix part set through `Object.assign`, including `Sub`, `RadioGroup`, `Portal`, `CheckboxItem`, `RadioItem`, `SubTrigger`, `SubContent`, and `Shortcut`. The spec records the full set so the public surface is unambiguous.
@@ -71,7 +71,7 @@ The roster's `Parent / Slots` column lists `DropdownMenu.Root`, `DropdownMenu.Tr
 
 ### `DropdownMenu.Trigger`, `DropdownMenu.Label`, `DropdownMenu.Separator`, `DropdownMenu.Group`, `DropdownMenu.Sub`, `DropdownMenu.RadioGroup`, `DropdownMenu.Portal`, `DropdownMenu.CheckboxItem`, `DropdownMenu.RadioItem`, `DropdownMenu.SubTrigger`, `DropdownMenu.SubContent`
 
-These proxy the corresponding Radix props. `DropdownMenu.Trigger` accepts the standard Radix trigger props (no class). `DropdownMenu.Label` and `DropdownMenu.Group` accept the standard Radix props. `DropdownMenu.SubContent` accepts the same `align` and `side` props as `Content`; the portal is forced to `null` so the sub-content renders inline.
+These proxy the corresponding Radix props. `DropdownMenu.Trigger` accepts the standard Radix trigger props (no class). `DropdownMenu.Label` and `DropdownMenu.Group` accept the standard Radix props. `DropdownMenu.SubContent` accepts the same `align` and `side` props as `Content`; Sub preserves controlled/uncontrolled open props; SubContent uses the Radix portal and its owning Sub state.
 
 ### `DropdownMenu.Item`
 
@@ -288,3 +288,12 @@ Rules:
 
 - App-owned data: the command set, the disabled reasons, the trigger element, and the keyboard shortcut strings.
 - DS-owned visuals: the `dsx-dropdown-menu__*` slot classes, the token bindings, the data-attribute contract, and the open / close animation.
+
+## Overlay review interaction
+
+Submenus are absent while closed unless forceMount is requested. Sub owns
+controlled/uncontrolled state and SubContent receives that state through a
+private context; it is no longer forced open. Portalling matches the
+[Radix submenu anatomy](https://www.radix-ui.com/primitives/docs/components/dropdown-menu)
+and keeps the submenu outside the parent’s overflow frame. The live example
+demonstrates working Profile/Settings, Autosave and Share project actions.

package/dist/docs/components/em.md

@@ -105,7 +105,7 @@ Rules:
 
 ## Playground demo spec
 
-`Em` is registered in `apps/playground/lib/registry/typography.tsx` under the `em` key. The registry entry imports `emPropDefs` and renders the component with a sample emphasis span. Per-component route: `/docs/em`.
+`Em` is registered in `apps/playground/lib/registry/typography.tsx` under the `em` key. The registry entry imports `emPropDefs` and renders the component with a sample emphasis span. Per-component route: `/docs/em`. The live example uses English and Russian sentence context plus a slotted span.
 
 **Default story:**