@d4gger/design-system 3.0.0 → 4.0.0

package/dist/docs/components/floating-panel.md

@@ -12,27 +12,21 @@ depends_on:
 
 # FloatingPanel
 
-> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
-
 ## Purpose
 
-A generic floating content surface with drag, resize, and persistent placement. The panel is a `position: fixed` element whose top-left position, width, and height are local state; the header acts as the drag handle, a built-in close button unmounts the panel, and an inline resize handle in the southeast corner (or south / east) adjusts the size.
+A movable, resizable nonmodal surface. The package owns local position, size
+and close state. A consumer persists callback values and remounts with them
+when reopening. This is not a focus-trapped modal dialog.
 
 ## Anatomy & slots
 
-**Parent:** `FloatingPanel` (alias of `FloatingPanelRoot`, which is exported as `FloatingPanel`).
-
-**Slots:**
-
-| Slot | Element | Renders | Notes |
-|---|---|---|---|
-| `FloatingPanel.Root` (alias `FloatingPanel`) | `<div>` (or `Slot` host) | `dsx-floating-panel` | The shell. Owns position, size, drag, and resize state. Hard-codes `position: fixed`. |
-| `FloatingPanel.Header` | `<div>` (or `Slot` host) | `dsx-floating-panel__header` | The drag handle. Carries `data-floating-panel-handle` so the root's drag handler can ignore mouse-downs on it. |
-| `FloatingPanel.Content` | `<div>` (or `Slot` host) | `dsx-floating-panel__content` | The scrollable body region. Flexes to fill the remaining height. |
-| `FloatingPanel.Handle` | `<div>` (or `Slot` host) | `dsx-floating-panel__handle`, `dsx-floating-panel__handle--{direction}` | The resize handle. The root auto-mounts an `se`-direction handle unless `asChild` is set. |
-| (close button, internal) | `<button>` | `dsx-floating-panel__close` | Auto-rendered by the root. Clicking it calls `onClose` and unmounts the panel. |
-
-The `Handle` is internal in practice. The root renders one with `direction="se"` automatically; consumers that pass `asChild` on the root take responsibility for the close button and the resize handle.
+| Part | Host / class | Responsibility |
+|---|---|---|
+| Root | div or Slot / `dsx-floating-panel` | Local placement, size and gesture state |
+| Header | div or Slot / `dsx-floating-panel__header` | Drag target, marked `data-floating-panel-handle` |
+| Content | div or Slot / `dsx-floating-panel__content` | Scrollable body |
+| Handle | div or Slot / `dsx-floating-panel__handle--{se,s,e}` | Resize target |
+| Close | button / `dsx-floating-panel__close` | Internal close, `data-slot=floating-panel-close` |
 
 ## Props contract
 
@@ -40,11 +34,11 @@ The `Handle` is internal in practice. The root renders one with `direction="se"`
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Visual scale hint. Drives `data-size` on the root. The CSS does not currently consume `data-size`; see Anomalies. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Initial size band: sm=240×180, md=320×240, lg=480×360. Writes `data-size`; JavaScript owns dimensions. | no |
 | `defaultPosition` | `{ x: number; y: number }` | `{ x: 0; y: 0 }` | no | Initial top-left position in viewport pixels. | no |
-| `defaultSize` | `{ width: number; height: number }` | `{ width: 320; height: 240 }` | no | Initial size in viewport pixels. | no |
-| `onDragEnd` | `(position: { x: number; y: number }) => void` | `undefined` | no | Called once when the user releases the mouse after a drag. Receives the final position. | no |
-| `onResize` | `(size: { width: number; height: number }) => void` | `undefined` | no | Called once when the user releases the mouse after a resize. Receives the final size. | no |
+| `defaultSize` | `{ width: number; height: number }` | `{ width: 320; height: 240 }` | no | Initial size in viewport pixels; overrides the size-derived default. | no |
+| `onDragEnd` | `(position: { x: number; y: number }) => void` | `undefined` | no | Called on completed pointer/mouse drag or keyboard movement. Receives the final bounded position. | no |
+| `onResize` | `(size: { width: number; height: number }) => void` | `undefined` | no | Called on completed pointer/mouse resize or keyboard resize. Receives the final bounded size. | no |
 | `onClose` | `() => void` | `undefined` | no | Called when the user closes the panel via the close button or the `Escape` key. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. When set, the root no longer auto-mounts the close button or the resize handle. | no |
 | `children` | `React.ReactNode` | `undefined` | no | Header, Content, and (when `asChild` is set) Handle nodes. | no |
@@ -86,294 +80,94 @@ The Content also accepts every `React.HTMLAttributes<HTMLDivElement>` key.
 
 The Handle also accepts every `React.HTMLAttributes<HTMLDivElement>` key. The internal `onResize` wiring between the root and the handle is not part of the public `Handle` API; the root supplies the wiring only when it auto-mounts the handle.
 
-Rules that apply to this row:
+Rules:
 
-- The Root is `position: fixed` and overrides any consumer-supplied `position`, `left`, `top`, `width`, and `height` style. The consumer `style` prop is spread into the inline style but the root's own keys win.
-- Open state is internal. The component returns `null` after `onClose` (or after the user clicks the close button or presses `Escape`). There is no `open` / `onOpenChange` prop; once closed, the consumer must remount the component to reopen it.
-- The Header is the drag handle. The root's drag handler ignores mouse-downs on the header only when the consumer provides a `Header` slot. Without a `Header`, every mouse-down starts a drag.
-- `asChild` is the only polymorphic infra. It is exposed on Root, Header, Content, and Handle.
-- The min width for resize is `150` and the min height is `100`. These are raw values in JS, not tokens; see Anomalies.
+- Consumer `style` merges after the generated position and dimensions and may override them. Such overrides can constrain the gesture behavior.
+- Open state is internal and initially true. Closing unmounts the panel; reopen by remounting it.
+- A Header is the drag target when present. Without one, noninteractive body areas can drag. Buttons, links and input controls do not start dragging.
+- `asChild` is supported on Root, Header, Content and Handle. A custom root supplies its own close control and handle.
+- Header and Handle default to tabIndex=0 and role=group, with “Move panel” / “Resize panel” labels and keyboard instructions in their title. Consumer HTML attributes can override these defaults.
+- JS resize floors remain 150×100px, capped by available bounds when smaller. No new token or controlled-position API is introduced.
 
 ## CSS class contract
 
-**Root class:** `dsx-floating-panel`
-
-**Modifier classes** (driven by `data-*` attributes written by the component):
-
-| Attribute | Allowed values | Class | CSS file |
-|---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | (no CSS consumer; see Anomalies) | `floating-panel.css` |
-| `data-dragging` | (presence) | `.dsx-floating-panel[data-dragging]` (shadow upgrade + grabbing cursor) | `floating-panel.css` |
-
-**Slot classes:**
-
-| Slot | Class | CSS file |
-|---|---|---|
-| `FloatingPanel.Root` | `dsx-floating-panel` | `floating-panel.css` |
-| `FloatingPanel.Header` | `dsx-floating-panel__header` | `floating-panel.css` |
-| `FloatingPanel.Content` | `dsx-floating-panel__content` | `floating-panel.css` |
-| `FloatingPanel.Handle` | `dsx-floating-panel__handle`, `dsx-floating-panel__handle--{direction}` | `floating-panel.css` |
-| (close button, internal) | `dsx-floating-panel__close` | `floating-panel.css` |
-
-**Data attributes from the runtime:**
-
-| Element | Attribute | Allowed values | Class hook | CSS file |
-|---|---|---|---|---|
-| Root | `data-dragging` | (presence) | `.dsx-floating-panel[data-dragging]` | `floating-panel.css` |
-| Header | `data-floating-panel-handle` | (presence) | (not styled; the root's drag handler reads the attribute to ignore mouse-downs) | `floating-panel.css` |
-
-**Data slots** (used by QA and audit tooling, not visual):
-
-| Element | `data-slot` |
-|---|---|
-| Close button | `floating-panel-close` |
-
-**Responsive behavior:**
-
-- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size is single-value only.
-- The component's CSS file is breakpoint-agnostic.
-
-**Reduced motion:**
-
-- The shell, close button, and handle each transition properties (box-shadow, color, background, opacity) against `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. The runtime does not import `usePrefersReducedMotion`; rely on the global `prefers-reduced-motion` stylesheet.
+Root writes `data-size=sm/md/lg`; dimensions are consumed in JavaScript, not
+CSS size selectors. `data-dragging` activates the grabbing cursor and elevation.
+Header's existing handle attribute selects drag behavior. All existing part
+classes remain unchanged. There are no width breakpoints.
 
 ## Token mapping
 
-Every CSS value the component paints is a `var(--dsx-*)` token.
-
 | Property | Token | Role |
 |---|---|---|
-| Shell radius | `var(--dsx-rounded-xl)` | Panel corner radius. |
-| Shell border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Panel edge. |
-| Shell fill | `var(--dsx-color-panel-translucent)` | Panel surface. |
-| Shell shadow (rest) | `var(--dsx-shadow-md)` | Resting elevation. |
-| Shell shadow (dragging) | `var(--dsx-shadow-xl)` | Active elevation. |
-| Shell overflow | `hidden` (raw) | Contain children. |
-| Shell z-index | `var(--dsx-z-index-overlay-local)` | Above page content. |
-| Header padding | `var(--dsx-space-sm)` block, `var(--dsx-space-md)` inline | Inner gutter. |
-| Header gap | `var(--dsx-space-sm)` | Gap between children. |
-| Header border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline-variant)` | Header divider. |
-| Header fill | `var(--dsx-color-surface-raised)` | Header surface. |
-| Header cursor | `grab` (raw) | Drag affordance. |
-| Header user-select | `none` (raw) | Prevent text selection while dragging. |
-| Header active cursor | `grabbing` (raw) | Dragging state. |
-| Close button size | `var(--dsx-size-md)` square | Tap target. |
-| Close button radius | `var(--dsx-rounded-sm)` | Round affordance. |
-| Close button position | `var(--dsx-space-xs)` from top-right | Edge anchor. |
-| Close button text | `var(--dsx-color-on-surface-variant)` | Resting glyph. |
-| Close button hover fill | `var(--dsx-effect-hover-layer)` | Hover surface. |
-| Close button hover text | `var(--dsx-color-on-surface)` | Hover glyph. |
-| Close button z-index | `var(--dsx-z-index-elevated)` | Above panel content. |
-| Content padding | `var(--dsx-space-md)` | Inner gutter. |
-| Content overflow | `auto` (raw) | Scrollable body. |
-| Handle size (se) | `var(--dsx-space-lg)` square | Resize target. |
-| Handle size (s) | `var(--dsx-space-xl)` wide, `var(--dsx-space-sm)` tall | South edge handle. |
-| Handle size (e) | `var(--dsx-space-sm)` wide, `var(--dsx-space-xl)` tall | East edge handle. |
-| Handle cursor (se) | `nwse-resize` (raw) | Resize affordance. |
-| Handle cursor (s) | `ns-resize` (raw) | Resize affordance. |
-| Handle cursor (e) | `ew-resize` (raw) | Resize affordance. |
-| Handle grip color | `var(--dsx-color-on-surface-variant)` | Grip stroke. |
-| Handle grip opacity | `var(--dsx-opacity-muted)` | Resting fade. |
-| Handle grip border width | `var(--dsx-border-width-md)` | Grip thickness. |
-| Handle z-index | `var(--dsx-z-index-elevated)` | Above panel content. |
-| Motion | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` / `--dsx-motion-easing-in-out` | Shell, close, and handle transitions. |
-
-Rules:
-
-- Tokens come from `DESIGN.md` and the generated `tokens.css`. The intentional non-token values are the cursor keywords (`grab`, `grabbing`, `nwse-resize`, `ns-resize`, `ew-resize`), the `none` user-select, the `hidden` and `auto` overflow values, and the resize min dimensions in JS (`150` × `100`).
-- The CSS file imports `../../_internal/baseCard.css`. The import only matches `.dsx-card` and `.dsx-alert` selectors, so the import is a no-op for `FloatingPanel`. See Anomalies.
+| Shell radius | `--dsx-rounded-xl` | Corner |
+| Shell border | `--dsx-border-width-sm`, `--dsx-color-outline` | Edge |
+| Shell fill | `--dsx-color-panel-translucent` | Surface |
+| Rest / drag shadow | `--dsx-shadow-elevation-2` / `--dsx-shadow-elevation-5` | Feedback |
+| Shell layer | `--dsx-z-index-overlay-local` | Local floating surface |
+| Viewport size cap | 100vw / 100dvh minus `--dsx-space-xl` | Keep shell reachable |
+| Header spacing | `--dsx-space-sm`, `--dsx-space-md`, `--dsx-space-2xl` | Includes close-control clearance |
+| Header floor | `--dsx-size-xl` | 40px header |
+| Close box / inset | `--dsx-size-md` / `--dsx-space-sm` | 24px square with 8px clearance from the shell edge |
+| Southeast handle | `--dsx-space-lg`, `--dsx-space-sm`, `--dsx-space-xs`, `--dsx-border-width-sm` | 24px target with two diagonal resize strokes, matching the native textarea affordance |
+| South / east handle | `--dsx-space-xl` × `--dsx-size-md`, transposed for east | Resize target |
+| Focus | `--dsx-shadow-focus-ring` inset | Header, handle and close focus |
+| Body spacing | `--dsx-space-md` | Scrollable interior |
+
+Root bounds are the viewport for fixed positioning, or the offset parent's
+client dimensions for an overridden nonfixed position. Fixed bounds use the
+smaller root client/border-box width so a reserved scrollbar gutter remains
+outside the draggable area. Initial placement,
+window resize, gestures and keyboard updates clamp the panel to these bounds.
+The default southeast handle paints a decorative `dsx-floating-panel__resize-grip`
+span with two CSS strokes; it does not introduce an icon name. South/east
+handles retain the existing `grip-vertical` glyph and rotation. Custom children
+replace the decoration. The native TextAreaField resize grip remains browser-owned.
+Content has min-height=0 and overflow=auto. Header remains nonshrinking;
+close and resize controls sit above body content.
 
 ## Motion contract
 
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| Shell box-shadow | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Resting → dragging shadow upgrade | None declared in the file. Relies on the global `prefers-reduced-motion` stylesheet. |
-| Close button color and background | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Hover state swap | None declared in the file. Relies on the global stylesheet. |
-| Handle grip opacity | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Opacity lift on hover | None declared in the file. Relies on the global stylesheet. |
-
-Rules:
-
-- This row does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts`. All motion is CSS-only.
-- Drag and resize are JS-driven; the drag itself does not animate (the position update is synchronous). The shadow upgrade is the only visual cue during drag.
-- A future promotion that adds framer-motion should pick a preset from `MOTION_TRANSITIONS` and gate it with `usePrefersReducedMotion`. A future CSS-only promotion should add a `@media (prefers-reduced-motion: reduce)` block that sets `transition: none` on the shell, close button, and handle.
+Position and dimensions follow gestures directly. Cosmetic transitions use
+motion-duration-fast and standard/in-out easing. The local reduced-motion
+rule disables shell, close and handle transitions. Header and resize handles
+use touch-action=none while body controls retain their ordinary behavior.
 
 ## Accessibility
 
-**Roles:**
-
-- The root is a plain `<div>` with no implicit role. Consumers that need a dialog role should add `role="dialog"` and `aria-modal` at the app level (the roster lists this as a "heavy surface" that may need full dialog semantics).
-- The close button is a `<button type="button">` with `aria-label="Close panel"`. The runtime hard-codes the label.
-- The handle is a plain `<div>` with no role. Mouse-only interaction; see Keyboard.
-
-**Keyboard:**
-
-| Key | Action |
-|---|---|
-| `Tab` | Moves focus to / from any focusable element inside the panel, and to the close button. |
-| `Escape` | Closes the panel and calls `onClose`. The runtime installs a `document` keydown listener while the panel is open. |
-| `Enter`, `Space` | Activates the focused control (close button, content buttons, etc.). |
-| Arrow keys | The component does not implement keyboard-driven drag or resize. Mouse only. |
-
-**Focus:**
+Tab reaches Header, body controls, Close and Handle. Focused Header arrows
+move 8px; focused Handle arrows resize 8px along its enabled axes. Shift
+uses 40px steps. Input arrows remain input interactions. Header/Handle labels
+can be overridden using existing HTML attributes.
 
-- The runtime does not trap focus inside the panel. Focus management is the consumer's responsibility; for full dialog behavior, wrap in a Radix Dialog or set up focus trapping at the app level.
-- The runtime does not auto-focus the panel on mount. The close button is in the tab order; consumers that want the close button to be the focus target on mount can add `autoFocus` via app-level wrapping.
+Escape closes the focused panel, or the last panel in DOM order if none has
+focus, provided the event has not already been handled. It does not close all
+open panels. Consumer focus entry/return and persistence remain app-owned.
+Do not add aria-modal without actual modal behavior.
 
-**Reduced motion:**
-
-- The CSS transitions rely on the global `prefers-reduced-motion` stylesheet. The drag and resize math is synchronous and is not affected by the media query.
-
-**Color and meaning:**
-
-- The drag and resize affordances are communicated by the cursor keyword (`grab` / `grabbing` / `nwse-resize`). Color is not the only signal.
-
-**Naming:**
-
-- The close button is auto-labeled `Close panel`. The runtime hard-codes the label.
-- The panel has no implicit name. Consumers that need a panel name should add `aria-label` or `aria-labelledby` at the app level.
-- The handle is decorative and has no accessible name.
+Pointer cancellation restores gesture-start placement/size without committing
+a callback. Gesture document listeners are removed on completion and unmount.
+Keyboard alternatives do not alone establish WCAG dragging-movements
+conformance: an application also needs a single-pointer placement alternative.
 
 ## Playground demo spec
 
-The demo file at `demo_path` exposes the component to the playground. The playground lives at `apps/playground/app/` (Next.js app router, no per-component routes today). The `demo_path` recorded here is the current playground root; the spec assumes a single shared page that renders all components. Per-component routes are an aspirational target and not yet present in the repo.
-
-**Default story:**
-
-- Renders `FloatingPanel` with a `Header`, a `Content`, and the auto-mounted close + resize handle. Asserts the root class is `dsx-floating-panel` and the close button carries `aria-label="Close panel"`.
-
-**Variant story** (one per size and direction):
-
-- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute on the root (the CSS does not currently consume it; see Anomalies).
-- Renders a custom `Handle` with `direction="se"`, `direction="s"`, and `direction="e"`. Asserts the matching `dsx-floating-panel__handle--{direction}` modifier class and the cursor style.
-
-**Composition story** (one per slot):
-
-- Renders the full slot hierarchy: `FloatingPanel` > `Header` > `Content`, with the auto-mounted `Handle`. Asserts each slot renders the right class.
-- Renders `FloatingPanel` with `asChild`. Asserts the close button and the resize handle are no longer auto-mounted.
-
-**State story:**
-
-- Renders the default panel. Mouse-downs on the header, drags, and mouse-ups. Asserts the panel's `left` and `top` inline styles match the final position and that `onDragEnd` was called.
-- Mouse-downs on the resize handle, drags, and mouse-ups. Asserts the panel's `width` and `height` inline styles match the final size and that `onResize` was called.
-- Clicks the close button. Asserts the panel unmounts and `onClose` was called.
-- Opens the panel and presses `Escape`. Asserts the panel unmounts and `onClose` was called.
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the panel surface and shadow track the active theme.
-
-**A11y story:**
-
-- Uses `vitest-axe` against the rendered default FloatingPanel. Asserts the close button has an accessible name and the panel does not introduce violations.
-
-**Props exposed in the playground controls:**
-
-| Prop | Control | Default |
-|---|---|---|
-| `size` | select | `md` |
-| `defaultPosition` | text (JSON) | `{ x: 0, y: 0 }` |
-| `defaultSize` | text (JSON) | `{ width: 320, height: 240 }` |
-| `asChild` | boolean | `false` |
+`/docs/floating-panel` launches real editable notes in a wrapping TextArea in all size bands; the whole note is readable without widening the panel. Its live
+example retains callback placement/size and note text when reopening, offers
+Reset placement and numeric placement controls without dragging, and returns
+focus to its launcher when closed. Review mouse/touch header movement, corner
+resize, body editing, keyboard control and viewport containment.
 
 ## Wiring notes
 
-**Composes from:**
-
-- `Popover` and `Dialog` (declared composed-from engines per the roster; the current runtime does not import either). The current runtime manages open state, position, size, drag, and resize in source. See Anomalies.
-- `Icon` (lucide-react `X`): renders the default close-button glyph.
-- `@radix-ui/react-slot`: enables `asChild` on Root, Header, Content, and Handle.
-
-**Used by:**
-
-- App-level floating surfaces that need persistent placement and resizing: dashboards, design tools, chart inspectors. No DS component currently wraps `FloatingPanel`. The roster classifies this as a heavy surface; the package owns the shell, the token bindings, and the drag / resize plumbing; apps own persistence, the panel registry, and the focus-trap / dialog semantics.
-
-**State boundaries:**
-
-- Owned by FloatingPanel: the open state, the position, the size, the drag delta, the resize delta, the `Escape` keydown listener, the auto-mounted close button, and the auto-mounted resize handle.
-- Owned by the consumer: the Header content, the Content body, the optional custom Handle, the `defaultPosition` and `defaultSize` inputs, the `onDragEnd` / `onResize` / `onClose` callbacks, and the focus / dialog semantics.
-
-**Boundary rules:**
-
-- App-owned data: the panel registry, the persistence of position and size across sessions, the routing integration, and the focus management.
-- DS-owned visuals: token bindings, the `dsx-floating-panel` and slot classes, the `data-size` and `data-dragging` attributes, the close button label, and the resize handle directions.
-- The component does not own a `Dialog` integration. Wrap in a Radix `Dialog` (or set up focus trapping) at the app level for full modal semantics.
-
-**Anomalies** (open items that this spec flags):
-
-1. **Roster says `Popover, Dialog`; runtime uses neither.** The current runtime at `package_path` does not import Radix Popover or Radix Dialog. Open state, focus, and `Escape` are managed in source via `useState` and a `document.addEventListener('keydown')` listener. Promoting to a `BaseDialog`-backed runtime is tracked as a future item.
-2. **`data-size` attribute has no CSS consumer.** The TSX writes `data-size` on the root and the prop def lists three values (`sm`, `md`, `lg`), but the CSS does not define any `[data-size]` rule. The attribute is a forward-looking hook; the visual treatment today is the same across all three sizes.
-3. **`baseCard.css` import is a no-op.** The CSS file imports `../../_internal/baseCard.css`, which only targets `.dsx-card` and `.dsx-alert`. The import should be removed or `baseCard.css` should be extended to also match `.dsx-floating-panel`.
-4. **Resize min dimensions are raw JS values.** The resize handler clamps the size to `width >= 150` and `height >= 100`. These are not tokens; the next promotion should add `--dsx-floating-panel-min-width` and `--dsx-floating-panel-min-height` (or fold the constraints into the existing size scale).
-5. **Open state is internal and one-shot.** The runtime does not expose `open` or `onOpenChange` props. The component returns `null` after `onClose`; the consumer must remount to reopen. A future promotion should lift the open state.
-6. **Drag math ignores the resize handle and the close button.** The root's `onMouseDown` starts a drag unless the target is the closest `[data-floating-panel-handle]`. The close button does not have `data-floating-panel-handle`, but the drag handler can still fire on a click that lands inside it because the mouse-up handler is bound to `document`. A future promotion should also bail out of drag on `[data-floating-panel-close]`.
-7. **No `prefers-reduced-motion` block in `floating-panel.css`.** The shell, close button, and handle transitions are not explicitly collapsed on the media query. The next promotion should add a `@media (prefers-reduced-motion: reduce)` block.
-8. **The auto-mounted `Handle` always uses `direction="se"`.** Consumers that need south or east edge handles must render the `Handle` themselves and set `asChild` on the root, which also removes the close button. There is no public API to keep the close button while changing the handle direction.
+The component uses React state and pointer/mouse document listeners. Slot
+supports custom hosts. Consumer handlers are composed before root gesture
+handling and can preventDefault. No public controlled position/open props,
+new tokens, or `_internal` engine changes are introduced.
 
 ## Penpot build recipe
 
-> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
-
-The package does not yet publish a Penpot asset for FloatingPanel. Recipe is visual reference only and tracks the CSS contract.
-
-### Root board
-
-- **Name**: `Components / FloatingPanel`.
-- **Dimensions**: `320 × 240` (default), `width × height` driven by `defaultSize`.
-- **Layout**: `Flex` (column, header above content).
-- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'fix'`. Position is `fixed` with `left` / `top` driven by `defaultPosition`.
-
-### Layer tree
-
-```
-<Root Board: FloatingPanel>
-  ├── <Frame: header (drag handle)>
-  │   └── <Text: title>
-  ├── <Frame: content (scrollable)>
-  │   └── <Text: body>
-  ├── <Button: close (X icon, top-right)>
-  └── <Shape: resize handle (southeast corner)>
-```
-
-### Token bindings (Penpot properties)
-
-| Shape | Property | Token | Token type | Penpot property name |
-|---|---|---|---|---|
-| Shell | fill | `--dsx-color-panel-translucent` | Color | `fills` |
-| Shell | stroke | `--dsx-color-outline` | Color | `strokes` |
-| Shell | radius | `--dsx-rounded-xl` | Radius | `radius` |
-| Shell | shadow | `--dsx-shadow-md` | Effect | `shadow` |
-| Shell (dragging) | shadow | `--dsx-shadow-xl` | Effect | `shadow` (state) |
-| Header | fill | `--dsx-color-surface-raised` | Color | `fills` |
-| Header | stroke | `--dsx-color-outline-variant` | Color | `strokes` |
-| Content | padding | `--dsx-space-md` | Spacing | `padding` |
-| Close | fill | `transparent` | Color | `fills` |
-| Close (hover) | fill | `--dsx-effect-hover-layer` | Color | `fills` (state) |
-| Close (hover) | text | `--dsx-color-on-surface` | Color | `fills` (state) |
-| Handle | stroke | `--dsx-color-on-surface-variant` | Color | `strokes` |
-| Handle | opacity | `--dsx-opacity-muted` | Effect | `opacity` |
-
-### State transformations
-
-| State | Shell shadow | Header cursor | Close fill | Handle opacity |
-|---|---|---|---|---|
-| `default` | `--dsx-shadow-md` | `grab` | `transparent` | `--dsx-opacity-muted` |
-| `dragging` | `--dsx-shadow-xl` | `grabbing` | `transparent` | `1` |
-| `close-hover` | `--dsx-shadow-md` | `grab` | `--dsx-effect-hover-layer` | `--dsx-opacity-muted` |
-| `handle-hover` | `--dsx-shadow-md` | `grab` | `transparent` | `1` |
-
-### Variant model
-
-- `size`: `sm`, `md`, `lg`. Default `md`. (CSS consumer pending; see Anomalies.)
-- `direction` (handle): `se`, `s`, `e`. Default `se`.
-- Total members for the visual matrix: 3 × 3 = 9 once the `data-size` CSS consumer lands. Today the visual matrix is 3 (handle direction only).
-
-### 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.
-- [ ] The close button label is `Close panel`; do not treat the label as themable in Penpot.
-- [ ] The close button glyph is the `X` Icon; do not treat the glyph as themable in Penpot.
-- [ ] When the `data-size` CSS consumer lands, re-run the spec QA and re-validate the Penpot recipe against the new CSS.
-- [ ] When the `BaseDialog` portal routing lands, re-run the spec QA and confirm the panel tracks `data-accent-color` and the rest of the theme contract.
-- [ ] When the resize min dimensions are tokenized, update the JS clamp to read from the token instead of the hard-coded `150` and `100`.
+No published asset is changed. Mirror existing shell, header, scrollable body,
+close corner and directional handles using the token mapping above. Use
+240×180 / 320×240 / 480×360 initial frames with the viewport cap; static art
+cannot establish drag or keyboard behavior.

package/dist/docs/components/form.md

@@ -326,3 +326,7 @@ The package does not yet publish a Penpot asset for Form. Recipe is visual refer
 - [ ] Component is promoted to Main Component under `Components`.
 - [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
 - [ ] The form's `data-slot` attributes are baked in for QA tooling.
+
+## Reconciliation stories
+
+The live example wires React Hook Form instances to both Profile and Event forms. It proves invalid email feedback, successful submit, reset, labelled fields, room selection and a one-to-two-column event row through Grid. Hosts use width:100% with a maximum width; inline actions wrap at 320/390px.

package/dist/docs/components/grid.md

@@ -29,8 +29,8 @@ No slots: flat export. `Grid` is a single forwardRef that renders a host element
 |---|---|---|---|---|---|
 | `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 |
-| `columns` | `ResponsiveValue<number \| string>` | `undefined` | no | CSS `grid-template-columns`. Number values resolve to `repeat(n, minmax(0, 1fr))`. String values are written through (e.g. `7rem`, `200px 1fr`). When `minItemWidth` is set, the runtime uses `repeat(auto-fit, minmax(<minItemWidth>, 1fr))` instead. Resolves `--dsx-grid-columns`. | yes (initial, sm, md, lg, xl, 2xl) |
-| `rows` | `ResponsiveValue<number \| string>` | `undefined` | no | CSS `grid-template-rows`. Number values resolve to `repeat(n, minmax(0, 1fr))`. String values are written through. Resolves `--dsx-grid-rows`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `columns` | `ResponsiveValue<number \| string>` | `undefined` | no | CSS `grid-template-columns`. Number values and digit-only strings resolve to `repeat(n, minmax(0, 1fr))`. Other string values are written through (e.g. `7rem`, `200px 1fr`). When `minItemWidth` is set, the runtime uses `repeat(auto-fit, minmax(<minItemWidth>, 1fr))` instead. Resolves `--dsx-grid-columns`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `rows` | `ResponsiveValue<number \| string>` | `undefined` | no | CSS `grid-template-rows`. Number values and digit-only strings resolve to `repeat(n, minmax(0, 1fr))`. Other string values are written through. Resolves `--dsx-grid-rows`. | yes (initial, sm, md, lg, xl, 2xl) |
 | `areas` | `ResponsiveValue<string>` | `undefined` | no | CSS `grid-template-areas`. Resolves `--dsx-grid-areas`. | yes (initial, sm, md, lg, xl, 2xl) |
 | `flow` | `ResponsiveValue<'row' \| 'column' \| 'dense' \| 'row dense' \| 'column dense'>` | `undefined` | no | CSS `grid-auto-flow`. Resolves `--dsx-grid-auto-flow`. | yes (initial, sm, md, lg, xl, 2xl) |
 | `gap` | `ResponsiveValue<SpaceToken \| string>` | `undefined` | no | Gap between children. Resolves `--dsx-box-gap`. Serialized into `data-gap`. | yes (initial, sm, md, lg, xl, 2xl) |
@@ -94,7 +94,8 @@ The `dsx-grid` selector wires the grid-template custom properties:
 **Responsive behavior:**
 
 - The runtime writes `--dsx-grid-columns` (and other `--dsx-grid-*` variables) per breakpoint through `assignResponsiveVars` for the inline-style cascade.
-- The breakpoint alias props `sm`, `md`, `lg` are merged into the responsive prop map and resolve to the matching `--dsx-grid-*-<breakpoint>` custom property.
+- The breakpoint alias props `sm`, `md`, `lg` override their corresponding entries and preserve the rest of the responsive map, including `xl` and `2xl`.
+- Columns and rows use only the component custom-property cascade; duplicate track utility classes are not emitted. Auto-fit minimum widths carry forward as widths and take precedence over column counts until another minimum width is supplied.
 
 **Reduced motion:**
 
@@ -157,65 +158,11 @@ Grid has no motion. The motion section is intentionally empty.
 
 - Grid is not interactive and does not require an accessible name on its own. When Grid wraps an interactive element, the interactive element's accessible name is the source.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders `Grid columns="3" gap="sm"` with six child squares. Asserts the root class is `dsx-grid`, the host element is a `div`, and the children render.
-
-**Column story:**
-
-- Renders `Grid columns={2}` and `Grid columns={{ initial: 1, sm: 2, md: 3 }}`. Asserts the `dsx-grid` class and the per-breakpoint `--dsx-grid-columns` custom property.
-
-**Areas story:**
-
-- Renders `Grid areas='"head head" "side main"'` and asserts `--dsx-grid-areas` resolves to that value.
-
-**Flow story:**
-
-- Renders `Grid flow="column dense"` and asserts `--dsx-grid-auto-flow` resolves to `column dense`.
-
-**MinItemWidth story:**
-
-- Renders `Grid minItemWidth={200}` and asserts `--dsx-grid-columns` resolves to `repeat(auto-fit, minmax(200px, 1fr))`.
-
-**Breakpoint alias story:**
-
-- Renders `Grid columns={2} sm={{ columns: 3, gap: 'sm' }} md={{ columns: 4, gap: 'lg' }} lg={{ columns: 6, gap: 'xl' }}`. Asserts the merged values resolve in the per-breakpoint custom properties.
-
-**Responsive story:**
+The matrix numbers all six cells at a fixed available width; the live example arranges realistic project cards in one initial column and two columns at sm.
 
-- Renders `Grid gap={{ initial: 'md', lg: 'xl' }}` and asserts the `data-gap` attribute serializes as `initial:md;lg:xl` and the per-breakpoint `--dsx-box-gap-*` variables resolve.
-
-**Composition story:**
-
-- Renders `Grid` with mixed `Box` children. Asserts the children keep their own `dsx-box` class and inherit the Grid container's gap.
-
-**State story:**
-
-- No discrete state. The story renders a default Grid with six children.
-
-**Token story:**
-
-- Grid 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 Grid. The default render is a non-semantic `div` with text content; tests assert no violations.
-
-**Props exposed in the playground controls:**
+## Playground demo spec
 
-| Prop | Control | Default |
-|---|---|---|
-| `columns` | number | `3` |
-| `rows` | number | `undefined` |
-| `gap` | select | `md` |
-| `flow` | select | `row` |
-| `align` | select | `stretch` |
-| `justify` | select | `start` |
-| `alignContent` | select | `normal` |
-| `justifyItems` | select | `legacy` |
-| `minItemWidth` | number | `undefined` |
+The columns matrix shows six numbered cells at one fixed available width for one, two and three columns. The live example shows four project cards using columns={{ initial: '1', sm: '2' }} and gap="md". Narrow screens stack the cards; desktop uses two equal tracks.
 
 ## Wiring notes
 
@@ -247,3 +194,7 @@ Grid has no motion. The motion section is intentionally empty.
 ## Penpot build recipe
 
 Grid is a layout primitive. The package code is the only authority. There is no published Penpot build recipe for Grid. A future Penpot board would show a grid container with columns, rows, areas, and gap controls, but the spec intentionally does not duplicate the runtime class contract in a visual recipe.
+
+## Reconciliation stories
+
+The live example compares numeric and digit-string responsive columns, sm aliases with retained xl/2xl entries, carried auto-fit widths and numeric responsive rows. Browser checks measure actual track count and geometry at breakpoint boundaries.