## Overview [#overview]
`Stage` coordinates nested resizable panel groups from a typed preset record.
Each configured group is its own preset machine, so regions such as a main
chat/canvas split and a bottom terminal can change independently.
Stage does not own app surfaces. Add backgrounds, borders, and layout chrome
with `className` on `Stage` or `Stage.Panel`; Stage owns preset orchestration,
transitioning, mounted state, and resize handles.
## Usage [#usage]
```tsx
import {
Stage,
defineStageConfig,
useStageSnapshot,
} from "@tilt-legal/cubitt-components/stage";
```
```tsx
const mainConfig = defineStageConfig({
chat: {
thread: "fill",
canvas: 0,
},
canvas: {
thread: { size: 33.333, minSize: "260px" },
canvas: {
size: "fill",
minSize: "240px",
collapseToPreset: "chat",
},
},
});
const shellConfig = defineStageConfig({
closed: {
content: "fill",
terminal: 0,
},
open: {
content: "fill",
terminal: { size: "280px", minSize: "180px", collapseToPreset: "closed" },
},
});
const configs = {
shell: shellConfig,
main: mainConfig,
};
export function Component() {
return (
Thread
Canvas
Terminal
);
}
```
## Examples [#examples]
### Controlled Presets [#controlled-presets]
### Responsive Group Size Presets [#responsive-group-size-presets]
`groupSizePresets` requests presets when a group enters a measured size band
along its orientation axis. Rules are ordered from the smallest `below`
threshold to the largest. Omit `below` on the final rule to request a preset
when no threshold matches.
```tsx
Transcript
Outline
```
The rule fires when the group enters a different matching size band. It is not a
hard constraint, so custom controls can still call `setPreset` while the group
remains in the same band. If no rule matches and no final catch-all rule exists,
Stage does not request a preset.
### Stage Snapshot [#stage-snapshot]
Use `useStageSnapshot` when controls or integrations need the layout state Stage
is already observing internally.
```tsx
function SummaryInspector() {
const snapshot = useStageSnapshot();
const summary = snapshot.groups.summary;
return (
);
}
```
The snapshot includes registered groups, configured presets, group size rules,
the current active preset record, observed group sizes, and observed panel
sizes. Panel sizes are live measurements from the resizable panel, not preset
targets.
### Terminal Toggle [#terminal-toggle]
## API Reference [#api-reference]
### Stage [#stage]
Root provider and preset orchestrator.
| Prop | Type | Default | Description |
| ----------------- | ----------------------------- | ------- | ----------------------------------------------------------------------- |
| `configs` | `StageConfigs` | - | Preset machine configs keyed by matching group id. |
| `preset` | `StagePresetRecord` | - | Controlled active preset record. |
| `defaultPreset` | `StagePresetRecord` | - | Uncontrolled initial preset record. |
| `onPresetChange` | `(next, event) => void` | - | Fires when `setPreset` or `collapseToPreset` requests a machine preset. |
| `onPresetSettled` | `(event) => void` | - | Fires once a changed machine preset transition has visually settled. |
| `className` | `string` | - | Additional classes for the stage root. |
### Stage.Group [#stagegroup]
Axis wrapper for sibling panels.
| Prop | Type | Default | Description |
| ------------------ | -------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | - | Group key that must match one key in `configs`. |
| `orientation` | `"horizontal" \| "vertical"` | - | Panel layout axis. |
| `groupSizePresets` | `({ below: "520px"; preset: string } \| { preset: string })[]` | - | Ordered pixel breakpoints that request a preset when the measured group size enters a matching band. Omit `below` on the final rule to request a preset when no threshold matches. |
| `children` | `Stage.Panel[]` | - | Direct panel children only. |
### Stage.Panel [#stagepanel]
Addressable content region within the nearest group.
| Prop | Type | Default | Description |
| ------------- | --------- | ------- | ---------------------------------------------------------------------------------------------- |
| `id` | `string` | - | Panel key scoped to the nearest group. |
| `keepMounted` | `boolean` | `false` | Preserve closed panel content state while hiding it from interaction and assistive technology. |
| `className` | `string` | - | Additional classes for the mounted panel content wrapper. |
### useStage [#usestage]
Use the hook for custom controls inside the provider.
```tsx
const useAppStage = () =>
useStage();
```
### useStageSnapshot [#usestagesnapshot]
Use the hook for controls or integrations that react to live Stage layout state.
```tsx
const snapshot = useStageSnapshot();
```