@d4gger/design-system 2.7.0

package/dist/docs/config-drawer.md

@@ -0,0 +1,223 @@
+---
+title: ConfigDrawer
+status: canonical
+category: Foundations
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/configDrawer/ConfigDrawer.tsx
+css_path: packages/d4gger-design-system/src/styles/components/config-drawer.css
+props_path: packages/d4gger-design-system/src/components/configDrawer/configDrawer.props.ts
+test_path: packages/d4gger-design-system/src/test/components/ConfigDrawer.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/utility.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Sheet
+  - IconButton
+  - Icon
+  - SegmentedControl
+  - NumberInput
+  - Separator
+  - Text
+  - Label
+  - Flex
+  - ThemeProvider (consumes useTheme)
+---
+
+# ConfigDrawer
+
+> 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
+
+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.
+
+## 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. |
+| 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 seven 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.
+
+## 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 seven 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.
+
+**Slot classes:**
+
+| Slot / region | Class | CSS file |
+|---|---|---|
+| 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` |
+| Scaling `NumberInput` | `dsx-config-drawer__scaling-input` | `config-drawer.css` |
+
+**Responsive behavior:**
+
+- 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:**
+
+- 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.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| 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 |
+| 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`.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Sheet open / close | inherited from `Sheet` (`MOTION_TRANSITIONS.sheet`) | sheet preset | reduced |
+
+The component itself has no motion. The wrapping `Sheet` handles open / close transitions through the standard sheet preset and the `reduced` fallback.
+
+## 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".
+
+## 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 seven rows appear with the correct default selections (`System`, `Amber`, `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 + seven rows + separators.
+
+**Token story:**
+
+- Renders the default drawer inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the active segmented option tracks `--dsx-color-primary` and is not affected by the accent token.
+
+**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.
+
+## 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 seven default rows, their order, 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.