@d4gger/design-system 2.7.0

package/dist/docs/container.md

@@ -0,0 +1,255 @@
+---
+title: Container
+status: canonical
+category: Foundations
+archetype: layout-primitive
+package_path: packages/d4gger-design-system/src/components/container/Container.tsx
+css_path: packages/d4gger-design-system/src/styles/components/container.css
+props_path: packages/d4gger-design-system/src/components/container/container.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Container.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/layout.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Box
+  - Flex
+---
+
+# Container
+
+> Source of truth: the package source at `package_path`. The spec mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A layout primitive that centers content horizontally, applies a max-width rhythm,
+and adds horizontal padding. `Container` is a block shell by default. Consumers
+nest `Flex`, `Grid`, or `Stack` for content layout; explicit flex props remain a
+compatibility convenience.
+
+## Anatomy & slots
+
+**Parent:** `Container` (alias of `Container.Root`; flat export, no compound).
+
+**Slots:**
+
+No slots: flat export. `Container` is a single forwardRef that renders a host element chosen by `as`, or `div` by default. The body is whatever the consumer passes as `children`.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `as` | `React.ElementType` | `'div'` | no | Host element. `asChild` takes precedence when set. | no |
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`; consumer supplies the child. | no |
+| `size` | `ResponsiveValue<'1' \| '2' \| '3' \| '4' \| 'content' \| 'wide' \| 'full'>` | `'content'` | no | Max-width ramp. Resolves `--dsx-container-max-width`. `1`→`420px`, `2`→`640px`, `3`→`768px`, `4`→`1024px`, `content`→`1080px`, `wide`→`1200px`, `full`→`none`. The serialized value is also written to the `data-size` attribute when it is a single string. | yes (initial, sm, md, lg, xl, 2xl) |
+| `inset` | `ResponsiveValue<SpaceToken \| string>` | `'margin'` | no | Horizontal padding. Resolves `--dsx-container-inset`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `direction` | `ResponsiveValue<'row' \| 'column' \| 'row-reverse' \| 'column-reverse'>` | `undefined` | no | Inherited from `FlexStyleProps`. `data-direction` is not written; direction flows through `--dsx-flex-direction` and the per-breakpoint utility classes. | yes (initial, sm, md, lg, xl, 2xl) |
+| `align` | `ResponsiveValue<'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'>` | `undefined` | no | Inherited from `FlexStyleProps`. Serialized into `data-align`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `justify` | `ResponsiveValue<'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'>` | `undefined` | no | Inherited from `FlexStyleProps`. Serialized into `data-justify`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `wrap` | `ResponsiveValue<'nowrap' \| 'wrap' \| 'wrap-reverse'>` | `undefined` | no | Inherited from `FlexStyleProps`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `display` | `ResponsiveValue<'block' \| 'inline-block' \| 'inline' \| 'flex' \| 'inline-flex' \| 'grid' \| 'inline-grid' \| 'contents' \| 'none' \| string>` | CSS `block` | no | Inherited from `BoxStyleProps`. The default is supplied by CSS and is not written as an inheritable inline custom property. | yes (initial, sm, md, lg, xl, 2xl) |
+| `gap` | `ResponsiveValue<SpaceToken \| string>` | `undefined` | no | Inherited from `FlexStyleProps`. Resolves `--dsx-box-gap`. Serialized into `data-gap`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `sm` | `Partial<ContainerBreakpointProps>` | `undefined` | no | Breakpoint alias for the `sm` breakpoint. Merged into the responsive prop map for `align`, `direction`, `display`, `gap`, `inset`, `justify`, `size`, `wrap`. | no |
+| `md` | `Partial<ContainerBreakpointProps>` | `undefined` | no | Breakpoint alias for the `md` breakpoint. Merged into the responsive prop map. | no |
+| `lg` | `Partial<ContainerBreakpointProps>` | `undefined` | no | Breakpoint alias for the `lg` breakpoint. Merged into the responsive prop map. | no |
+| (all `Box` style props) | (see [Box](./box.md)) | `undefined` | no | Inherited: `position`, `padding`, `paddingX`, `paddingY`, `px`, `py`, `pt`, `pr`, `pb`, `pl`, `p`, `margin`, `m`, `mx`, `my`, `mt`, `mr`, `mb`, `ml`, `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`, `inset`, `zIndex`, `hide`, `show`, `radius`, `surface`, `shadow`, `border`, `borderTone`, `alignSelf`, `justifySelf`, `flex`, `flexBasis`, `flexGrow`, `flexShrink`, `order`, `gridArea`, `gridColumn`, `gridRow`. Note that `inset` is a `Box` style prop too, but Container overrides it with the `ContainerBreakpointProps.inset` typed value. | yes where Box marks them responsive |
+| `className` | `string` | `undefined` | no | Extra classes appended to the generated utility class string. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style merged with the generated `--dsx-*` variables. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Container body. | no |
+| `ref` | `React.Ref<HTMLElement>` | `undefined` | no | Forwarded to the host element. | no |
+
+Rules:
+
+- Every prop above is declared on `Container` in `Container.tsx` or in `BoxStyleProps` / `FlexStyleProps` / `ContainerStyleProps` from `layout.props.ts`. The runtime type is the source of truth.
+- `data-gap`, `data-align`, and `data-justify` are written as serialized breakpoint maps (`sm:sm`, `lg:center`, `md:between`). The `data-size` attribute is the bare value when `size` is a string.
+- The `Responsive` column is `yes` for `size`, `inset`, `direction`, `align`, `justify`, `wrap`, `display`, and `gap`. The Box-inherited props are `yes` where Box marks them responsive.
+- Container omits `inset` from the `BoxStyleProps` destructure via `Omit<BoxOwnProps, 'inset'>` so the type-level `ContainerStyleProps['inset']` is the only `inset` consumers can pass.
+
+## CSS class contract
+
+**Root class:** `dsx-container`
+
+In addition, Container writes `dsx-flex` and `dsx-box` so the inherited flex and Box tokens apply.
+
+**Modifier attributes:**
+
+| Attribute | Value | Notes |
+|---|---|---|
+| `data-size` | single string `size` value | Only when `size` is a string (e.g. `content`, `wide`, `full`, `1`..`4`). Responsive maps do not write `data-size`. |
+| `data-gap` | serialized `ResponsiveValue` of `gap` | Visual value, e.g. `sm:sm` |
+| `data-align` | serialized `ResponsiveValue` of `align` | Visual value |
+| `data-justify` | serialized `ResponsiveValue` of `justify` | Visual value |
+
+The `dsx-container` selector applies the size + inset cascade:
+
+```css
+.dsx-container {
+  width: 100%;
+  max-width: var(--dsx-container-max-width, 1080px);
+  margin-inline: auto;
+  padding-inline: var(--dsx-container-inset, var(--dsx-space-margin));
+}
+```
+
+`container.css` then re-declares the same rule inside `@media (min-width: ...)` blocks for `sm`, `md`, `lg`, `xl`, `2xl` so per-breakpoint variables resolve in cascade order.
+
+**Slot classes:** none. Container is a flat export.
+
+**Responsive behavior:**
+
+- The runtime writes `--dsx-container-max-width` and `--dsx-container-inset` per breakpoint through `assignResponsiveVars`.
+- The breakpoint alias props `sm`, `md`, `lg` are merged into the responsive prop map and resolve to the matching `--dsx-container-*-<breakpoint>` custom property.
+
+**Reduced motion:**
+
+- Container has no motion. No transitions or animations are declared in `container.css`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Width | `100%` | CSS keyword, not a token |
+| Max width | `var(--dsx-container-max-width, 1080px)` | Resolved from `size` |
+| Margin | `auto` | CSS keyword |
+| Padding inline | `var(--dsx-container-inset, var(--dsx-space-margin))` | Resolved from `inset` |
+| Display | `var(--dsx-box-display, flex)` | Inherited from `dsx-flex` |
+| Gap | `var(--dsx-box-gap, 0)` | Inherited from `dsx-flex` |
+| Size ramp | `1`→`420px`, `2`→`640px`, `3`→`768px`, `4`→`1024px`, `content`→`1080px`, `wide`→`1200px`, `full`→`none` | `size` value resolution |
+| Inset ramp | `var(--dsx-space-{xs,sm,md,lg,xl,2xl,3xl,gutter,margin})` | `inset` value resolution (via `SpaceToken`) |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in the CSS. Tokens only.
+- The `size` ramp values (`420px`, `640px`, `768px`, `1024px`, `1080px`, `1200px`) are resolved in `layout.props.ts` `parseContainerSizeValue`. They are not token-mapped because the roster treats them as primitive container sizes; `content` and `wide` map to `CONTAINER_WIDTHS.content` (`1080`) and `CONTAINER_WIDTHS.wide` (`1200`) from `responsive.props.ts`.
+- The token list is closed; new tokens are a `DESIGN.md` change first.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+Container has no motion. The motion section is intentionally empty.
+
+## Accessibility
+
+**Roles:**
+
+- `Container` has no implicit ARIA role. The host element defaults to `<div>`. Consumers should set `role` explicitly when the surface needs a semantic role.
+
+**Keyboard:**
+
+- Container is not interactive. No keyboard contract beyond the page-level Tab order.
+
+**Focus:**
+
+- Container has no interactive surface. Focus management is the consumer's responsibility.
+
+**Reduced motion:**
+
+- N/A. Container has no motion.
+
+**Color and meaning:**
+
+- Container does not paint a surface, border, or shadow on its own. Any visual state comes from inherited Box props and is paired with the consumer's content for meaning.
+
+**Naming:**
+
+- Container is not interactive and does not require an accessible name on its own. When Container wraps an interactive element, the interactive element's accessible name is the source.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Container` with no extra props and a child node. Asserts the root classes are `dsx-container`, `dsx-flex`, and `dsx-box`, the host element is a `div`, and `--dsx-container-max-width` resolves to `1080px`.
+
+**Size story:**
+
+- Renders `Container size="wide"`, `Container size="full"`, and `Container size={{ initial: 'content', sm: 'wide', md: 'full' }}`. Asserts the matching `--dsx-container-max-width` custom property at each breakpoint, and that the `data-size` attribute is set when `size` is a single string.
+
+**Inset story:**
+
+- Renders `Container inset="xl"` and asserts `--dsx-container-inset` resolves to `var(--dsx-space-xl)`.
+
+**Direction story:**
+
+- Renders `Container direction="column" gap="sm"`. Asserts the matching `dsx-r-fd-column` class and the `data-gap` attribute.
+
+**Align story:**
+
+- Renders `Container align="center" sm={{ align: 'start' }} md={{ align: 'end' }}` and asserts the per-breakpoint `--dsx-flex-align-*` custom property plus the `data-align` attribute.
+
+**Justify story:**
+
+- Renders `Container justify="between"` and asserts the `dsx-r-jc-between` class and the `data-justify` attribute.
+
+**Breakpoint alias story:**
+
+- Renders `Container size="content" sm={{ size: 'wide' }} md={{ size: 'full' }}` and asserts the per-breakpoint `--dsx-container-max-width-*` custom property.
+
+**Responsive story:**
+
+- Renders `Container size={{ initial: 'content', sm: 'wide', md: 'full' }}` and asserts the per-breakpoint cascade.
+
+**Composition story:**
+
+- Renders `Container` with two `Box` children showing different surface tones. Asserts the children keep their own `dsx-box` class and inherit the Container's max-width and padding.
+
+**State story:**
+
+- No discrete state. The story renders a default Container with two children.
+
+**Token story:**
+
+- Container does not honor `data-accent-color`. Render inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. The story asserts the layout is unchanged and any surfaces come from the theme.
+
+**A11y story:**
+
+- Use `vitest-axe` against the rendered Container. The default render is a non-semantic `div` with text content; tests assert no violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `content` |
+| `inset` | select | `margin` |
+| `direction` | select | `row` |
+| `align` | select | `stretch` |
+| `justify` | select | `start` |
+| `wrap` | select | `nowrap` |
+| `gap` | select | `md` |
+| `display` | select | `block` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Box`: the host class and inherited style props. Container writes `dsx-container`, `dsx-flex`, and `dsx-box` together.
+- `Flex`: the flex container, direction, align, justify, wrap, and gap prop classes. Container also writes `data-gap`, `data-align`, and `data-justify`.
+- `Slot` from `@radix-ui/react-slot`: enables `asChild`.
+- `_internal/props/propDef.ts` and the helpers in `_internal/helpers/`: the responsive class + custom-property pipeline.
+- `foundations/Shared.tsx`: `PolymorphicProps` and the `resolve*` helpers.
+- `layout/responsive.props.ts`: `BREAKPOINTS`, `CONTAINER_WIDTHS`, `ResponsiveValue`, `assignResponsiveVars`.
+- `layout/layout.props.ts`: `BoxStyleProps`, `FlexStyleProps`, `ContainerStyleProps`, `BOX_PROP_DEFS`, `FLEX_PROP_DEFS`, `CONTAINER_PROP_DEFS`, `extractLayoutProps`, `parseContainerSizeValue`.
+- `components/container/container.props.ts`: the `containerPropDefs` bag (declares `size` as a `PropDef` enum) and `containerSizeValues`.
+- `styles/components/container.css`: the `.dsx-container` host rule plus breakpoint cascade.
+- `styles/components/box.css`, `styles/components/flex.css`: imported transitively through `container.css`.
+
+**Used by:**
+
+- `Sidebar`, `Shell`, `Header`, `Footer`, `Cabinet Shell`, and most app-shell surfaces: build their centered content on top of `Container`.
+
+**State boundaries:**
+
+- Owned by `Container`: the host element selection (`as` / `asChild`), the responsive prop resolution, the size ramp resolution (`1`/`2`/`3`/`4`/`content`/`wide`/`full`), the inset resolution (`SpaceToken` or string), the generated utility classes, and the host classes.
+- Owned by the consumer: the children, the host element tag, the user-supplied `className` and `style`, the ref target.
+
+**Boundary rules:**
+
+- App-owned data: the children content and any host element chosen via `as` or `asChild`.
+- DS-owned visuals: token bindings, the `dsx-container`, `dsx-flex`, and `dsx-box` root classes, the size ramp values, the responsive utility classes, and the `data-*` attribute contract.
+
+## Penpot build recipe
+
+Container is a layout primitive. The package code is the only authority. There is no published Penpot build recipe for Container. A future Penpot board would show a centered container with the size and inset ramps, but the spec intentionally does not duplicate the runtime class contract in a visual recipe.

package/dist/docs/context-menu.md

@@ -0,0 +1,294 @@
+---
+title: ContextMenu
+status: canonical
+category: Components
+archetype: radix-compound
+package_path: packages/d4gger-design-system/src/components/contextMenu/ContextMenu.tsx
+css_path: packages/d4gger-design-system/src/styles/components/context-menu.css
+props_path: packages/d4gger-design-system/src/components/contextMenu/contextMenu.props.ts
+test_path: packages/d4gger-design-system/src/test/components/ContextMenu.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/overlay.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - "@radix-ui/react-context-menu (the underlying Radix primitive; `ContextMenu.Root`, `Trigger`, `Content`, `Label`, `Separator`, `Group`, `Sub`, `RadioGroup`, `CheckboxItem`, `RadioItem`, `SubTrigger`, `SubContent` proxy to it)"
+  - "Menu (the internal abstraction; `MenuContent`, `MenuItem`, `MenuPortal`, `MenuRoot`, `MenuSeparator` are wrapped to share the framer-motion content open / close animation and the portal theme mirroring)"
+  - "@radix-ui/react-slot (powers `asChild` on `Shortcut` and the prop-def bag on `Item` / `SubTrigger`)"
+  - _internal/BaseDialog (PortalThemeBoundary + PortalThemeWrapper; mirrors the `data-dsx-*` attribute contract into the content portal; `MenuContent` consumes the wrapper)
+  - _internal/motion (MOTION_TRANSITIONS.menu for the content open / close animation, MOTION_TRANSITIONS.reduced for `prefers-reduced-motion: reduce`; consumed by `MenuContent` and inherited by the ContextMenu content)
+  - _internal/helpers/extractProps (turns the prop defs on `Item`, `SubTrigger`, and `Shortcut` into merged class + style output)
+  - Icon (the `chevron-right` glyph on the sub-trigger; the `check` / `minus` glyphs on checkbox items)
+---
+
+# ContextMenu
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+An object-scoped right-click action menu. The DS `ContextMenu` wraps `@radix-ui/react-context-menu` and is the canonical surface for actions on a target object. It is not for general dropdown actions from a button trigger; for that, use `DropdownMenu`.
+
+## Anatomy & slots
+
+**Parent:** `ContextMenu` (alias of `ContextMenu.Root`). The root wraps the Radix root in `MenuRoot` so the content picks up the shared framer-motion open / close animation and the portal theme mirroring. The root also tracks an internal `open` state via `ContextMenuOpenContext` so the content can stay mounted through the animation when `forceMount` is not set.
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `ContextMenu.Root` | Radix `ContextMenu.Root` (via `MenuRoot`) | (no DS class) | The open-state owner. |
+| `ContextMenu.Trigger` | Radix `ContextMenu.Trigger` | (no DS class) | The element that captures the right-click. |
+| `ContextMenu.Content` | Radix `ContextMenu.Content` inside `MenuContent` (which wraps a `motion.div`) | `dsx-context-menu__content` + `data-size` (`sm` \| `md` \| `lg`) | The popover surface. Animates open / close via `AnimatePresence` and `motion.div`. |
+| `ContextMenu.Item` | Radix `ContextMenu.Item` (via `MenuItem`) | `dsx-context-menu__item` + optional `data-destructive`, `data-inset` | A selectable row. |
+| `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.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.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.
+
+## Props contract
+
+### `ContextMenu` (root)
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Standard Radix `onOpenChange` callback. | no |
+| `dir` | `'ltr' \| 'rtl'` | `undefined` | no | Standard Radix `dir` prop. | no |
+| `modal` | `boolean` | `undefined` | no | Standard Radix `modal` prop. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The trigger and content. | no |
+
+### `ContextMenu.Content`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Content size; writes `data-size` on the `motion.div`. | no |
+| `forceMount` | `boolean` | `false` | no | Forwards `forceMount asChild` to the Radix content so the framer-motion animation can play on close. | no |
+| `align` | `'start' \| 'center' \| 'end'` | `undefined` | no | Standard Radix `align`. | no |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `undefined` | no | Standard Radix `side`. | no |
+| `sideOffset` | `number` | `undefined` | no | Standard Radix `sideOffset`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to the content. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The content body. | no |
+
+### `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.
+
+### `ContextMenu.Item`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `destructive` | `boolean` | `false` | no | Marks the item as destructive. Writes `data-destructive="true"`. The class `dsx-context-menu-item-destructive` is also merged through `extractProps`. | no |
+| `inset` | `boolean` | `false` | no | Indents the item to align with icon-led items. Writes `data-inset="true"` and merges `dsx-context-menu-item-inset`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-context-menu__item`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The item content. | no |
+
+### `ContextMenu.SubTrigger`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `inset` | `boolean` | `false` | no | Indents the trigger to align with icon-led items. Writes `data-inset="true"` and merges `dsx-context-menu-sub-trigger-inset`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-context-menu__item dsx-context-menu__sub-trigger`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The trigger content. A `chevron-right` icon is appended. | no |
+
+### `ContextMenu.Shortcut`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot` from `@radix-ui/react-slot`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-context-menu__shortcut`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The shortcut text (for example `⌘C`). | no |
+
+Rules:
+
+- `ContextMenu.Item`, `ContextMenu.SubTrigger`, and `ContextMenu.Shortcut` run through `extractProps` with the matching prop def bag. The remaining slots accept the full Radix prop bag forward.
+- `data-destructive` and `data-inset` are written as attributes; the modifier classes are merged through `extractProps` from the prop defs.
+- `ContextMenu.Content` is wrapped by the `MenuContent` abstraction from `Menu.tsx`. The `MenuContent` consumer passes `open` from `ContextMenuOpenContext` so the framer-motion animation can play on close even when Radix unmounts the content. The same wrapper provides the `PortalThemeWrapper` so the `data-dsx-*` attribute contract mirrors into the portal.
+
+## CSS class contract
+
+**Root class:** `dsx-context-menu__content` (the content surface; the root itself does not own a class)
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | (sizing token bindings) | `context-menu.css` |
+| `data-destructive` | `true` | `.dsx-context-menu__item[data-destructive='true']` | `context-menu.css` |
+| `data-inset` | `true` | `.dsx-context-menu__item[data-inset='true']` | `context-menu.css` |
+| `data-highlighted` | (Radix-native) | `.dsx-context-menu__item[data-highlighted]` | `context-menu.css` |
+
+**Modifier classes (prop-def-derived):**
+
+| Source prop | Class | CSS file |
+|---|---|---|
+| `destructive` (on `Item`) | `dsx-context-menu-item-destructive` | `context-menu.css` |
+| `inset` (on `Item`) | `dsx-context-menu-item-inset` | `context-menu.css` |
+| `inset` (on `SubTrigger`) | `dsx-context-menu-sub-trigger-inset` | `context-menu.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `ContextMenu.Content` | `dsx-context-menu__content` | `context-menu.css` |
+| `ContextMenu.Item` | `dsx-context-menu__item` | `context-menu.css` |
+| `ContextMenu.Label` | `dsx-context-menu__label` | `context-menu.css` |
+| `ContextMenu.Separator` | `dsx-context-menu__separator` | `context-menu.css` |
+| `ContextMenu.CheckboxItem` | `dsx-context-menu__item` (indicator in `dsx-context-menu__item-indicator`) | `context-menu.css` |
+| `ContextMenu.RadioItem` | `dsx-context-menu__item` (indicator + `dsx-context-menu__radio-dot`) | `context-menu.css` |
+| `ContextMenu.SubTrigger` | `dsx-context-menu__item` + `dsx-context-menu__sub-trigger` + `dsx-context-menu__sub-chevron` | `context-menu.css` |
+| `ContextMenu.SubContent` | `dsx-context-menu__content` | `context-menu.css` |
+| `ContextMenu.Shortcut` | `dsx-context-menu__shortcut` | `context-menu.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`.
+
+**Reduced motion:**
+
+- The framer-motion open / close animation is gated by `usePrefersReducedMotion` in `MenuContent`. When reduced motion is active, the animation collapses to an opacity-only fade (`MOTION_TRANSITIONS.reduced`).
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token. The `context-menu.css` file imports `_internal/baseMenu.css` for shared menu item styling.
+
+| Property | Token | Role |
+|---|---|---|
+| Content min-width | `var(--dsx-size-menu-min-width)` | Dropdown minimum width. |
+| Content padding | `var(--dsx-space-xs)` | Content gutter. |
+| Content border radius | `var(--dsx-rounded-lg)` | Content corner roundness. |
+| Content background | `var(--dsx-color-surface-overlay)` | Dropdown surface. |
+| Content border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Dropdown edge. |
+| Content z-index | `var(--dsx-z-index-dropdown)` | Stack above page. |
+| Item min-height | `var(--dsx-size-lg)` | Item touch target. |
+| Item padding | `var(--dsx-space-sm) var(--dsx-space-sm) var(--dsx-space-sm) calc(var(--dsx-space-lg) + var(--dsx-space-sm))` | Item gutter with indicator gutter. |
+| Item border radius | `var(--dsx-rounded-md)` | Item corner roundness. |
+| Item text color | `var(--dsx-color-on-surface)` | Default row color. |
+| Item typography | `var(--dsx-typography-body-medium-*)` | Item font family and size. |
+| Item destructive | `var(--dsx-color-error)` | Destructive item color. |
+| Inset item padding | `calc(var(--dsx-space-xl) + var(--dsx-space-sm))` | Indented item padding. |
+| Indicator width | `var(--dsx-size-md)` | Checkbox / radio indicator gutter. |
+| Radio dot size | `var(--dsx-space-sm)` | Radio dot diameter. |
+| Radio dot radius | `var(--dsx-rounded-full)` | Radio dot roundness. |
+| Shortcut color | `var(--dsx-color-on-surface-variant)` | Shortcut text color. |
+| Shortcut typography | `var(--dsx-typography-label-medium-font-size)` | Shortcut font size. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in `context-menu.css`. The shared `baseMenu.css` file keeps its tokens in the same way.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Content (opacity, y translate) | `MOTION_TRANSITIONS.menu` | `duration.normal`, `ease.emphasized` (or the `MenuContent` defaults) | `MOTION_TRANSITIONS.reduced` (opacity-only fade) |
+
+Rules:
+
+- The open / close animation is owned by `MenuContent` in `Menu.tsx`. The source declares `MOTION_TRANSITIONS.menu` for the default open / close and `MOTION_TRANSITIONS.reduced` for `prefers-reduced-motion: reduce`. The animation is gated by `usePrefersReducedMotion`.
+
+## Accessibility
+
+**Roles:**
+
+- `ContextMenu.Content` is `role="menu"` (Radix).
+- `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.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Shift+F10`, context-menu key | Opens the context menu (browser-default). |
+| `ArrowDown`, `ArrowUp` | Moves through items. |
+| `Enter`, `Space` | Activates the focused item. |
+| `Escape` | Closes the menu. |
+| `ArrowRight` (on sub-trigger) | Opens the submenu. |
+| `ArrowLeft` (inside submenu) | Closes the submenu and returns focus to the sub-trigger. |
+
+**Focus:**
+
+- The CSS file does not declare a focus ring; the shared menu item style in `_internal/baseMenu.css` paints the focus ring on `:focus-visible`. The ring stays visible on dark and light surfaces.
+
+**Reduced motion:**
+
+- The framer-motion animation is gated by `usePrefersReducedMotion`. When reduced motion is active, the animation collapses to an opacity-only fade via `MOTION_TRANSITIONS.reduced`.
+
+**Color and meaning:**
+
+- State is communicated by `data-state` (`open` / `closed`) and the visual indicator on the focused item. Color is not the only signal.
+
+**Naming:**
+
+- Every `ContextMenu.Item` must have an accessible name from its children. Icon-only items need `aria-label`.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `ContextMenu` with a `Trigger` (a div with the right-click cursor) and a `Content` with three items. Asserts the menu does not open until a `contextmenu` event fires. Right-clicks the trigger and asserts the menu is in the DOM.
+
+**Variant story:**
+
+- Renders the content with `size="sm"`, `size="md"`, and `size="lg"`. Asserts `data-size` flips on the content `motion.div`.
+
+**State story:**
+
+- Renders an `Item` with `destructive` and an `Item` with `inset`. Asserts `data-destructive="true"` and `data-inset="true"` plus the matching modifier classes.
+
+**Composition story:**
+
+- Renders a `Label`, a `Separator`, an `Item` with a `Shortcut`, a `Sub` with a `SubTrigger` and `SubContent`, and a `CheckboxItem` plus a `RadioGroup` with two `RadioItem`s. Asserts each slot renders with the expected class.
+
+**Token story:**
+
+- ContextMenu does not own a `data-accent-color` hook, so the token story is omitted. The bar paints with the active theme tokens; the destructive color tracks `var(--dsx-color-error)`, which is theme-aware.
+
+**A11y story:**
+
+- The `ContextMenu.test.tsx` suite fires `fireEvent.contextMenu` and asserts the menuitem role. The registry does not need a separate `vitest-axe` check.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `destructive` | boolean | `false` |
+| `inset` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-context-menu`: the underlying context-menu primitive.
+- `Menu` (internal abstraction): `MenuContent`, `MenuItem`, `MenuPortal`, `MenuRoot`, `MenuSeparator` are wrapped to share the framer-motion open / close animation and the portal theme mirroring. The public menu surfaces never import `Menu` directly.
+- `@radix-ui/react-slot`: enables `asChild` on `Shortcut` and the prop-def bag on `Item` / `SubTrigger`.
+- `_internal/BaseDialog` (`PortalThemeBoundary`, `PortalThemeWrapper`): keeps the `data-dsx-*` attribute contract mirrored into the content portal through `MenuContent`.
+- `_internal/motion` (`MOTION_TRANSITIONS.menu`, `MOTION_TRANSITIONS.reduced`): the JS-side bindings to framer-motion.
+- `_internal/usePrefersReducedMotion`: gates the open / close animation.
+- `_internal/helpers/extractProps`: turns the `Item`, `SubTrigger`, and `Shortcut` prop defs into merged class + style output.
+- `Icon`: the `chevron-right` glyph on the sub-trigger; the `check` / `minus` glyphs on checkbox items.
+
+**Used by:**
+
+- App object surfaces (file rows, list items, canvas elements, table cells). The Cabinet Shell pattern can compose `ContextMenu` for right-click on shell surfaces.
+
+**State boundaries:**
+
+- Owned by `ContextMenu`: the open / closed state, the highlighted item, the destructive / inset attribute flags, and the `data-size` value.
+- Owned by the consumer: the trigger element, the menu registry, the onSelect handlers, the disabled reasons, and the route or command the item triggers.
+
+**Boundary 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.