@d4gger/design-system 3.0.0 → 3.0.1

package/dist/docs/components/control-group.md

@@ -1,261 +0,0 @@
----
-title: ControlGroup
-status: canonical
-category: Components
-archetype: composite
-depends_on:
-  - Select
-  - ToggleGroup
-  - SegmentedControl
-  - Button
-  - Separator
----
-
-# ControlGroup
-
-> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
-
-## Purpose
-
-Visually groups two or more *unlike* interactive controls (a `Select` next to a `ToggleGroup`, a
-`Button` next to a `SegmentedControl`, etc.) inside one shared bordered frame, so they read as one
-settings cluster instead of separate floating widgets.
-
-## Anatomy & slots
-
-**Parent:** `ControlGroup` (flat export — no compound sub-components).
-
-**Slots:**
-
-| Slot | Element | Renders | Notes |
-|---|---|---|---|
-| `ControlGroup` (Root) | `<div>` | Flex container, `role="group"` | Holds any number of DS control children directly — no wrapper slot components. |
-
-No named child slots: unlike `InputGroup` (which wraps its children in `InputGroup.Addon` /
-`InputGroup.Text` / `InputGroup.Button` for input-specific semantics), `ControlGroup`'s children
-are consumed as-is. This is the deliberate distinction from `InputGroup` — see Wiring notes.
-
-## Props contract
-
-| Prop | Type | Default | Required | Description | Responsive |
-|---|---|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Controls the group's height and inner item padding. | no |
-| `radius` | `'md' \| 'full'` | `'full'` | no | Outer corner radius of the group frame and of the first/last child's outer corners. | no |
-| `asChild` | `boolean` | `false` | no | Renders the root as its child via Radix `Slot` instead of a `div`. | no |
-
-Rules:
-
-- Every prop in this table must exist in `controlGroup.props.ts`. The runtime prop def is the source.
-- Every prop in `controlGroup.props.ts` must be in this table. Mismatches fail `qa:contracts`.
-- No `Responsive` column values are `yes` — this component does not vary by breakpoint.
-
-## CSS class contract
-
-**Root class:** `dsx-control-group`
-
-**Modifier classes** (driven by `data-*` attributes written by the component):
-
-| Attribute | Allowed values | Class | CSS file |
-|---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | `.dsx-control-group[data-size="sm"]` | `control-group.css` |
-| `data-group-radius` | `md`, `full` | `.dsx-control-group[data-group-radius="md"]`, `.dsx-control-group[data-group-radius="full"]` | `control-group.css` |
-
-**Not `data-radius`, deliberately (2026-08-26, real bug found live):** `data-radius` is a
-reserved document-theme attribute — `PortalThemeBoundary`'s `getClosestThemeAttribute(el,
-'data-radius')` walks up the nearest ancestor carrying that attribute to mirror the app's global
-radius setting into portaled content (`Select`/`Dialog`/`Popover`/etc). A component that emits
-its own local `data-radius` between a portal trigger and `<html>` gets picked up *instead of* the
-real document-level value. Confirmed live: a `Select` inside a `ControlGroup radius="full"` frame
-opened its dropdown at `9999px` border-radius (`--dsx-rounded-lg` itself resolved to `9999px` on
-the portaled content), while `<html>` still correctly read `data-radius="md"`. Any future
-component with its own per-instance radius axis should avoid the literal `data-radius` name for
-the same reason — this isn't `ControlGroup`-specific.
-
-**Slot classes:** none — flat export, no named slots.
-
-**Corner-radius mechanism:**
-
-The root paints the visible border/background. Direct children get their shared (inner-facing)
-corners squared and outer corners rounded to match the root, via structural selectors
-(`:first-child`, `:last-child`, `:not(:first-child)`) — the same technique `InputGroup` already
-uses, applied here to children that are complete DS components (Select, ToggleGroup, Button,
-SegmentedControl) rather than raw form parts. A child's own border/shadow/background is
-intentionally left alone — `ControlGroup` only manages corner radius on the two outer edges and a
-1px visual seam between children (a `Separator`-style divider, not a border collapse, since
-children are not assumed to share the exact same border width the way stacked inputs do).
-
-**Responsive behavior:**
-
-- The component does not write `@media` rules.
-
-**Reduced motion:**
-
-- No motion — a static layout container.
-
-## Token mapping
-
-| Property | Token | Role |
-|---|---|---|
-| Background | `var(--dsx-color-surface)` | Group frame surface |
-| Border | `var(--dsx-color-outline-variant)` | Group frame edge |
-| Radius (full) | `var(--dsx-rounded-full)` | Pill frame |
-| Radius (md) | `var(--dsx-rounded-md)` | Rectangular frame |
-| Padding | `var(--dsx-space-xs)` | Inner gutter between frame edge and first/last child |
-| Seam | `var(--dsx-color-outline-variant)` | Divider between adjacent children |
-
-Rules:
-
-- No raw color, spacing, radius, or motion values in this table or in the CSS file.
-- Accent-driven children (a `ToggleGroup` item's active fill, a `SegmentedControl`'s active
-  state) keep their own accent tokens — `ControlGroup` does not repaint or override a child's own
-  interactive state, only its outer corner radius.
-
-## Motion contract
-
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| Root | `none` | `none` | `none` |
-
-## Accessibility
-
-**Roles:**
-
-- `group` on the root, so assistive tech announces the contained controls as one related cluster.
-
-**Keyboard:**
-
-- No keyboard handling of its own — each child control owns its own keyboard interaction
-  (`Tab` moves between children exactly as it would without the wrapper).
-
-**Focus:**
-
-- A focused child's own focus ring must remain fully visible — the root's `overflow` stays
-  visible (not `hidden`), so a focus ring is never clipped by the group's rounded corners.
-
-**Reduced motion:**
-
-- N/A — no motion.
-
-**Color and meaning:**
-
-- N/A — a layout container, no semantic state of its own.
-
-**Naming:**
-
-- The root's `aria-label` is left to the consumer when the group's purpose isn't obvious from its
-  children's own labels (e.g. `<ControlGroup aria-label="Currency and language">`).
-
-## Playground demo spec
-
-**Default story:**
-
-- Renders `ControlGroup` with a `Select` and a `ToggleGroup` child, no extra props.
-- Asserts the root class is `dsx-control-group`.
-
-**Variant story** (one per `radius` value):
-
-- `radius="full"` and `radius="md"`, asserting `data-group-radius` matches.
-
-**State story:**
-
-- One child focused (via `Tab`) — asserts the focus ring is not clipped.
-
-**Composition story:**
-
-- Three children (`Select`, `Separator`-free two-item `ToggleGroup`, `Button`) to prove the
-  corner-radius mechanism holds for more than two children.
-
-**Token story:**
-
-- Rendered inside `Theme` with `accentColor="silver"` and `accentColor="bronze"` — asserts a
-  `ToggleGroup` child's active-item fill still resolves to the right accent (proving
-  `ControlGroup` doesn't interfere with a child's own accent scoping).
-
-**A11y story:**
-
-- `vitest-axe` on the composition story.
-
-**Props exposed in the playground controls:**
-
-| Prop | Control | Default |
-|---|---|---|
-| `size` | `select` | `md` |
-| `radius` | `select` | `full` |
-
-## Wiring notes
-
-**Composes from:**
-
-- Any DS interactive component as a direct child — `Select`, `ToggleGroup`, `SegmentedControl`,
-  `Button`, `IconButton` are the ones currently exercised.
-
-**Used by:**
-
-- Landing header's currency + language cluster (`apps/playground/.../landing/_shared/landing-view.tsx`)
-  — the motivating real usage. Previously hand-built as a bordered `Stack` with per-instance CSS
-  overrides for corner radius; migrated to `ControlGroup` in the same change that added this spec.
-
-**State boundaries:**
-
-- Owned by this component: corner-radius/seam geometry only.
-- Owned by the consumer: every child's own value/state — `ControlGroup` never reads or writes a
-  child's `value`/`onValueChange`.
-
-**Boundary rules:**
-
-- App-owned data: which controls are grouped, their values, their change handlers.
-- DS-owned visuals: the group frame's border/background/radius and the inter-child seam.
-
-**Distinction from InputGroup:** `InputGroup`'s purpose is input-centric (a text field with
-leading/trailing addons — "Ideal for search fields, URLs, copy/share flows," per its roster row)
-and its convenience sub-components (`Addon`/`Text`/`Button`/`Input`/`Textarea`) assume the group
-is built around exactly one text-entry control. `ControlGroup` has no such assumption — it exists
-for clusters where no single child is "the" input (e.g. two independent selectors). Using
-`InputGroup` for the landing header (checked before building this) would have stretched it past
-its documented purpose for a resemblance in CSS mechanism alone, not a real semantic fit.
-
-## Penpot build recipe
-
-### Root board
-
-- **Name**: `Components / ControlGroup`.
-- **Dimensions**: `auto × auto` (content-sized).
-- **Layout**: `Flex`.
-- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
-
-### Layer tree
-
-```
-ControlGroup
-  ├── Child 1 (e.g. Select instance)
-  ├── Seam (1px divider)
-  └── Child 2 (e.g. ToggleGroup instance)
-```
-
-### Token bindings (Penpot properties)
-
-| Shape | Property | Token | Token type | Penpot property name |
-|---|---|---|---|---|
-| Root | fill | `--dsx-color-surface` | Color | fills |
-| Root | stroke | `--dsx-color-outline-variant` | Color | strokes |
-| Root | radius | `--dsx-rounded-full` | Radius | corner-radius |
-| Root | padding | `--dsx-space-xs` | Spacing | padding |
-| Seam | fill | `--dsx-color-outline-variant` | Color | fills |
-
-### State transformations
-
-| State | Root fill | Stroke | Text fill | Shadow |
-|---|---|---|---|---|
-| `default` | `--dsx-color-surface` | `--dsx-color-outline-variant` | n/a (children own their own text) | none |
-
-### Variant model
-
-- `radius`: `full`, `md`. Default `full`.
-- `size`: `sm`, `md`, `lg`. Default `md`.
-- Total members: `6`.
-
-### Validation checklist
-
-- [ ] Token bindings resolve at the values `DESIGN.md` describes.
-- [ ] Component is promoted to Main Component under `Components`.
-- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.