Initial Commit

packages/ui/react/react-control-surface/src/grouping/panel/panel.md

@@ -0,0 +1,69 @@
+# `<Panel>`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`<Panel>` is the labelled grouping primitive that wraps a group of controls
+in a titled box, optionally with collapse-toggle behaviour. Unlike
+`<Group>` (pure layout) and `<Rack>` (slot frame), `<Panel>` carries
+chrome — a header, an `aria-label`ed body region, and a stable
+`section` landmark for screen readers.
+
+The collapse-toggle is implemented as a `<button>` with `aria-expanded`
+and `aria-controls` linked to a uniquely-id'd body region. When the panel
+collapses, the body is unmounted (not just hidden via CSS) so descendant
+focus is moved naturally and tab order shrinks to skip the collapsed
+content.
+
+## Features
+
+- Always-present labelled `<section>` landmark.
+- Optional collapse-toggle button driven by local React state.
+- `defaultCollapsed` initial state for SSR-friendly hydration.
+- Stable `aria-controls` linkage via `useId`.
+- `data-panel-id` attribute mirroring the schema id.
+
+## Usage: Basic
+
+```tsx
+<Panel id="reverb" label="Reverb">
+    <Knob label="Decay" />
+    <Knob label="Mix" />
+</Panel>
+```
+
+## Usage: Advanced
+
+```tsx
+<Panel
+    id="compressor"
+    label="Compressor"
+    collapsible
+    defaultCollapsed
+    className="dark"
+    style={{ borderRadius: 8 }}
+>
+    <Knob label="Threshold" />
+    <Knob label="Ratio" />
+    <Switch2 label="Auto-makeup" />
+</Panel>
+```
+
+## API Reference
+
+- `<Panel>` props: `id`, `label?`, `collapsible?` (default `false`),
+  `defaultCollapsed?` (default `false`), `className?`, `style?`,
+  `children?`.
+
+## Implementation Notes
+
+The toggle button text uses ASCII `+` and `-` glyphs rather than Unicode
+chevrons so the rendered output stays consistent across font stacks (the
+icon glyphs are skin-driven in skinned deployments). The label is reused
+for both the section's `aria-label` and the inner region's `aria-label`
+because the section landmark name is what screen readers announce when
+the user navigates to the region, while the inner region's name is what
+the toggle's `aria-controls` resolves against.