@pasquelin/panels 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alban pasquelin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @pasquelin/panels
+
+**[Live demo ↗](https://pasquelin.github.io/panel/)** · **[Documentation 🇫🇷](docs/fr/README.md)** · **[Documentation 🇬🇧](docs/en/README.md)** · MIT
+
+A React panel chassis: icon rails on the edges, resizable zones around a free centre, and a
+layout that survives a reload.
+
+It is a **layout, not a framework**. What goes in the panels is your project's business — the
+library draws the frame, remembers the sizes, and gets out of the way.
+
+```bash
+pnpm add @pasquelin/panels
+```
+
+```tsx
+import { Panels, Panel } from '@pasquelin/panels'
+import '@pasquelin/panels/styles.css'
+
+type PanelId = 'files' | 'chat'
+
+export function App() {
+  return (
+    <Panels<PanelId>>
+      <Panel<PanelId> id="files" zone="left" title="Files" icon={<FilesIcon />}>
+        <FileTree />
+      </Panel>
+
+      <Panel<PanelId> id="chat" zone="right" title="Assistant" icon={<ChatIcon />}>
+        <Conversation />
+      </Panel>
+
+      <Panels.Center>
+        <Outlet />
+      </Panels.Center>
+    </Panels>
+  )
+}
+```
+
+That is the whole of it. The rails, the resize handles, the persistence and the keyboard are
+already there.
+
+## What you get
+
+- **Five zones** — `left`, `right`, `top`, `bottomLeft`, `bottomRight`. A zone nobody fills takes
+  no room at all.
+- **Two halves per zone** — `primary` and `secondary`, parted by a handle. Panels sharing a half
+  take turns; the rail switches between them.
+- **Icon rails** that stay put when a zone closes, so a closed panel is always one click away.
+- **Resize** by pointer or keyboard, clamped so the centre never disappears.
+- **Persistence** to `localStorage` out of the box, or wherever you say.
+- **Typed ids** — `reveal('chatt')` does not compile.
+- **No dependencies** beyond React. No icon set, no CSS framework, no i18n.
+
+## Panel props
+
+| Prop | Meaning |
+| --- | --- |
+| `id` | Unique, and the type parameter of `<Panels>` |
+| `zone` | Which edge it hangs from |
+| `slot` | `primary` (nearest the edge) or `secondary`. Defaults to `primary` |
+| `title` | Accessible name and header title, **already translated** |
+| `icon` | Anything React renders — the library imposes no icon set |
+| `actions` | Rendered on the panel's own title row |
+| `opens` | The width this panel wants when it leads its zone |
+| `solo` | Takes the zone whole; the other half is put away, not closed, and comes back |
+
+## Driving the panels from anywhere
+
+`usePanels()` is all a header, a shortcut or a menu needs:
+
+```tsx
+const { panels, reveal, close, toggle, isShown } = usePanels<PanelId>()
+```
+
+From **outside React** — a socket message, an Electron menu — build the store yourself and keep
+the reference:
+
+```tsx
+const store = createPanelsStore<PanelId>()
+
+socket.on('alert', () => store.getState().show('alerts'))
+
+<Panels<PanelId> store={store}>…</Panels>
+```
+
+## Making it yours
+
+Three levels, and you can stop at any of them.
+
+**1. Repaint it.** Every value is a custom property on `.pnl-root`:
+
+```css
+.pnl-root {
+  --pnl-panel: #101418;
+  --pnl-chassis: #1b1f24;
+  --pnl-accent: #47965c; /* the rails follow your brand */
+  --pnl-radius: 10px;
+  --pnl-rail: 56px;
+}
+```
+
+**2. Replace a piece.** `Rail`, `PanelHeader`, `ResizeHandle`, `Surface`, `IconButton` and the
+rest are exported. Build your own frame out of the ones you keep.
+
+**3. Take the logic only.** Every component is built on hooks that render nothing:
+
+```tsx
+const zone = useZone('left') // what it draws, its size, its split
+const { reveal, isShown } = usePanels()
+useContainerFit(ref) // re-clamps when the container resizes
+```
+
+Draw whatever you like on top. The chassis has no opinion about it.
+
+## It fits inside your page
+
+The chassis measures **its own container**, never the window. Put it in a route, under your
+navigation, beside your sidebar — the clamps follow the box it is actually in.
+
+## Header and footer are yours
+
+`<Panels>` draws no chrome. `header` and `footer` are slots; pass your own, or nothing. Where a
+project's panels come from — a router, a state machine, a config — is that project's business.
+
+## Examples
+
+All four run at **[pasquelin.github.io/panel](https://pasquelin.github.io/panel/)**, or locally:
+
+```bash
+pnpm dev
+```
+
+- `examples/minimal` — the smallest working chassis
+- `examples/router` — the centre as a React Router outlet
+- `examples/dockview` — document tabs, on the optional Dockview entry point
+- `examples/theme` — the same chassis under four palettes
+
+## Documentation
+
+| | 🇫🇷 Français | 🇬🇧 English |
+| --- | --- | --- |
+| **Guide + index** | [docs/fr/](docs/fr/README.md) | [docs/en/](docs/en/README.md) |
+| Panels | [PANELS.md](docs/fr/PANELS.md) | [PANELS.md](docs/en/PANELS.md) |
+| Layout | [LAYOUT.md](docs/fr/LAYOUT.md) | [LAYOUT.md](docs/en/LAYOUT.md) |
+| Hooks | [HOOKS.md](docs/fr/HOOKS.md) | [HOOKS.md](docs/en/HOOKS.md) |
+| Theming | [THEMING.md](docs/fr/THEMING.md) | [THEMING.md](docs/en/THEMING.md) |
+| Components | [COMPONENTS.md](docs/fr/COMPONENTS.md) | [COMPONENTS.md](docs/en/COMPONENTS.md) |
+| Document tabs | [DOCKVIEW.md](docs/fr/DOCKVIEW.md) | [DOCKVIEW.md](docs/en/DOCKVIEW.md) |
+| Recipes | [RECIPES.md](docs/fr/RECIPES.md) | [RECIPES.md](docs/en/RECIPES.md) |
+| Architecture | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | — |
+
+For coding agents: [`llms.txt`](llms.txt) is the mental model, the API and the traps in one
+page; [`llms-full.txt`](llms-full.txt) is every English chapter concatenated. Both ship with the
+package, and `pnpm llms` regenerates the second from the first plus `docs/`.
+
+## Licence
+
+**MIT** — see [LICENSE](LICENSE).
+
+Every dependency is MIT too, so there is no copyleft obligation anywhere in the tree.
+`zustand` is bundled into the published package and its notice travels with it; everything else
+is a peer dependency the consuming project installs itself. The full accounting is in
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md), and `pnpm licences:check` fails the build if it
+stops being true.

package/dist/components/Band.d.ts

@@ -0,0 +1,13 @@
+import type { PanelsLabels } from './labels';
+export type BandProps = {
+    left: boolean;
+    right: boolean;
+    labels: PanelsLabels;
+};
+/**
+ * The bottom band: one strip, one height, and up to two zones side by side.
+ *
+ * Alone, a half takes the whole strip — and the frame has already run it under the opposite
+ * column. Together they share the width, parted by a handle that starts at the middle.
+ */
+export declare function Band<Id extends string = string>({ left, right, labels }: BandProps): import("react").JSX.Element | null;

package/dist/components/Center.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+export type CenterProps = {
+    children: ReactNode;
+    className?: string;
+};
+/**
+ * Declares what the middle holds — a router outlet, a canvas, a map, document tabs.
+ *
+ * A descriptor like `<Panel>`, and read by `<Panels>` for the same reason: the centre sits
+ * between the zones in the DOM, not where it is written.
+ *
+ * It stays at ONE place in the tree through every arrangement of the zones around it. Moved,
+ * React would unmount it — tearing down whatever engine, canvas or editor it holds.
+ */
+export declare function Center(_props: CenterProps): null;
+export declare namespace Center {
+    var displayName: string;
+}

package/dist/components/IconButton.d.ts

@@ -0,0 +1,20 @@
+import type { ButtonHTMLAttributes, ReactNode, Ref } from 'react';
+export type IconButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'aria-label' | 'aria-pressed' | 'children'> & {
+    /** Free-form. The library imposes no icon set. */
+    icon?: ReactNode;
+    /** Accessible name. Already translated. */
+    label: string;
+    /** Panel currently shown: neutral background, and `aria-pressed`. */
+    active?: boolean;
+    /** Shown AND in the focused zone: accented background. */
+    accented?: boolean;
+    /** Acts rather than toggles: no `aria-pressed`. */
+    acts?: boolean;
+    children?: ReactNode;
+    ref?: Ref<HTMLButtonElement>;
+};
+/**
+ * The rail's button, and the panel header's. One place for the active and accented states, the
+ * accessible name and the geometry — copied at each site, a missing `aria-label` goes unnoticed.
+ */
+export declare function IconButton({ icon, label, active, accented, acts, className, children, ref, ...rest }: IconButtonProps): import("react").JSX.Element;

package/dist/components/Panel.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+import type { PanelSpec, Slot } from '../core/types';
+/**
+ * Everything the chassis knows about a panel, plus what only JSX can carry.
+ *
+ * Derived from `PanelSpec` rather than restated: the two had been written out field by field,
+ * with the documentation copied word for word, so adding one meant remembering to add it twice
+ * — and nothing would have failed if you had not.
+ *
+ * `slot` is the one field that changes shape: it is required in the registry and optional here,
+ * because a panel that does not say lands in the half nearest the edge.
+ */
+export type PanelProps<Id extends string = string> = Omit<PanelSpec<Id>, 'slot'> & {
+    slot?: Slot;
+    /** Actions on the panel's own title row, beside its name. */
+    actions?: ReactNode;
+    children: ReactNode;
+};
+/**
+ * Declares one panel. It is a DESCRIPTOR, never rendered where it is written: `<Panels>` reads
+ * its props to build the rail and hands its children to whichever zone it named.
+ *
+ * The same shape as `<Route>` in React Router — the element describes, the parent arranges. The
+ * alternative was a portal per panel, which puts the panel's content in a different React tree
+ * from the one it was declared in: context, error boundaries and suspense would all stop at the
+ * boundary, and a panel could not read a provider its own file sits under.
+ */
+export declare function Panel<Id extends string = string>(_props: PanelProps<Id>): null;
+export declare namespace Panel {
+    var displayName: string;
+}

package/dist/components/PanelFrame.d.ts

@@ -0,0 +1,23 @@
+import { type PanelSpec } from '../core/types';
+export type PanelFrameProps<Id extends string> = {
+    panel: PanelSpec<Id>;
+    /** Length of its own along the zone's inner axis. Absent takes whatever the other half left. */
+    length?: number;
+    /** Text of the close button, already translated. */
+    closeLabel: string;
+    onFocus: () => void;
+};
+/**
+ * One panel on screen: its surface, its title row, its content.
+ *
+ * Closing is the only way out, on purpose. A collapsed panel is a third state between open and
+ * closed that looks like neither, and the rail already reopens a panel in one click.
+ */
+declare function PanelFrameInner<Id extends string>({ panel, length, closeLabel, onFocus, }: PanelFrameProps<Id>): import("react").JSX.Element;
+/**
+ * Memoised: a zone drag writes a new size on every `pointermove`, and without this each frame
+ * re-renders both halves and everything the project put in them. `onFocus` must stay stable for
+ * that to bite — see `ZoneEdge`.
+ */
+export declare const PanelFrame: typeof PanelFrameInner;
+export {};

package/dist/components/PanelHeader.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+export type PanelHeaderProps = {
+    title: string;
+    /** The panel's own actions, on the same line as its name. */
+    children?: ReactNode;
+    /**
+     * Lets the actions take the free width rather than hug the trailing edge — for a panel whose
+     * row is wide and mostly empty, and which carries a whole bar there rather than a button.
+     */
+    fillActions?: boolean;
+    /** Pinned past the actions: whatever crowds the row, the way out of the panel stays reachable. */
+    trailing?: ReactNode;
+    className?: string;
+};
+export declare function PanelHeader({ title, children, fillActions, trailing, className, }: PanelHeaderProps): import("react").JSX.Element;

package/dist/components/Panels.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from 'react';
+import { type PanelsProviderProps } from '../core/context';
+import { type PanelsLabels } from './labels';
+export type PanelsProps<Id extends string = string> = Omit<PanelsProviderProps<Id>, 'children'> & {
+    /** Above the rails, full width. The project's own — the library imposes no chrome. */
+    header?: ReactNode;
+    /** Below the rails, full width: a status line, counters, a breadcrumb. */
+    footer?: ReactNode;
+    /** Pinned at the top of the left rail, above the icons. */
+    railHeader?: ReactNode;
+    /** Words the chassis says. English by default; pass your own already translated. */
+    labels?: Partial<PanelsLabels>;
+    /**
+     * Forces the palette. Left out, the chassis follows the reader's system setting — which is
+     * what a project wants until it offers a switch of its own.
+     */
+    theme?: 'dark' | 'light';
+    className?: string;
+    /** `<Panel>` and `<Center>` descriptors. Anything else is rendered where it stands. */
+    children: ReactNode;
+};
+/**
+ * The chassis: icon rails stuck to the edges, rounded panels laid over the gutter, a free centre,
+ * and the project's own header and footer around them.
+ */
+export declare function Panels<Id extends string = string>({ header, footer, railHeader, labels, theme, className, children, ...provider }: PanelsProps<Id>): import("react").JSX.Element;
+export declare namespace Panels {
+    var Panel: typeof import("./Panel").Panel;
+    var Center: typeof import("./Center").Center;
+}

package/dist/components/Rail.d.ts

@@ -0,0 +1,23 @@
+import { type Side, type Zone } from '../core/types';
+export type RailProps = {
+    /** Edge the rail sticks to. Each rail also carries the band's half on its own side. */
+    side: Side;
+    /** Rendered above the panel icons — a "new" button, a logo, anything the project pins there. */
+    header?: React.ReactNode;
+    className?: string;
+};
+/**
+ * An edge's icon rail, IDE-style: it stays in place when the zone is closed, so a closed panel
+ * is always one click away.
+ *
+ * Each rail is split into groups — its column's panels at the top, its half of the bottom band
+ * at the foot — so that an icon's position tells where the panel will open.
+ */
+export declare function Rail({ side, header, className }: RailProps): import("react").JSX.Element;
+/**
+ * One zone's icons, cut the way the zone itself is cut: the icons above the separator open in
+ * its first half, the ones below in its second. The rail is the legend of the column.
+ */
+export declare function RailZone<Id extends string = string>({ zone }: {
+    zone: Zone;
+}): import("react").JSX.Element | null;

package/dist/components/ResizeHandle.d.ts

@@ -0,0 +1,37 @@
+export type ResizeHandleProps = {
+    /** `vertical` moves up and down and sets a height; `horizontal` sets a width. */
+    axis: 'vertical' | 'horizontal';
+    /** The panel grows as the pointer moves backwards — true for a right, bottom or lower half. */
+    invert?: boolean;
+    /** Where the cut stands. Absent means CSS is dividing the box, and the handle measures it. */
+    size?: number;
+    onSize: (size: number, available: number) => void;
+    /**
+     * Measures the panel this handle moves, for the case CSS is sizing it and `size` is unknown.
+     * The PARENT supplies it because the parent holds the element: reading
+     * `previousElementSibling` here would break the moment a consumer wraps a zone.
+     */
+    measure?: () => number;
+    /** Names the handle for assistive tech — "Resize the left column". Already translated. */
+    label: string;
+    /** Bounds announced to assistive tech, and the step the keyboard moves by. */
+    min?: number;
+    max?: number;
+    step?: number;
+    className?: string;
+};
+/**
+ * Resize handle. Captures the pointer so the gesture survives a cursor leaving the handle —
+ * without capture, a fast drag detaches.
+ *
+ * It measures the container when the gesture starts and passes that dimension along: it is the
+ * one that knows what is available, the store knows nothing about the DOM.
+ *
+ * It measures the panel it moves through a ref its parent gives it, never through
+ * `previousElementSibling`. Reading the sibling works in a tree one owns and breaks silently in
+ * a library: a consumer wrapping a zone in a `<div>` would move the wrapper's neighbour instead.
+ *
+ * Focusable and driven by the arrow keys: a separator that only answers a pointer is a control
+ * a keyboard user cannot operate at all (WCAG 2.1.1).
+ */
+export declare function ResizeHandle({ axis, invert, size, onSize, measure, label, min, max, step, className, }: ResizeHandleProps): import("react").JSX.Element;

package/dist/components/Separator.d.ts

@@ -0,0 +1,6 @@
+export type SeparatorProps = {
+    orientation?: 'vertical' | 'horizontal';
+    className?: string;
+};
+/** Hairline between groups of controls. Decorative, hence hidden from assistive tech. */
+export declare function Separator({ orientation, className }: SeparatorProps): import("react").JSX.Element;

package/dist/components/Surface.d.ts

@@ -0,0 +1,9 @@
+import type { HTMLAttributes } from 'react';
+/**
+ * The rounded box a panel is drawn on, laid over the chassis gutter.
+ *
+ * Darker than the chassis it sits on in the default theme — that inversion is what reads as
+ * "panels on a frame" rather than as a web page. A project that inverts it back only has to
+ * repaint two tokens.
+ */
+export declare function Surface({ children, className, ...rest }: HTMLAttributes<HTMLElement>): import("react").JSX.Element;

package/dist/components/ZoneEdge.d.ts

@@ -0,0 +1,17 @@
+import { type Zone } from '../core/types';
+import type { PanelsLabels } from './labels';
+export type ZoneEdgeProps = {
+    zone: Zone;
+    labels: PanelsLabels;
+};
+/**
+ * A zone's two halves and its resize handle, ordered by the zone. `left` and `top` put the
+ * panels first; the opposite zones put the handle first, because they grow backwards.
+ */
+declare function ZoneEdgeInner<Id extends string = string>({ zone, labels }: ZoneEdgeProps): import("react").JSX.Element | null;
+/**
+ * Memoised for the reason `PanelFrame` is: with five zones on screen, one frame of a drag used
+ * to re-render all five and every panel under them, where two are owed.
+ */
+export declare const ZoneEdge: typeof ZoneEdgeInner;
+export {};

package/dist/components/content.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+/** What a declared panel renders, kept beside its spec rather than inside the store: React
+ * nodes in a store make every subscriber re-render whenever a child changes. */
+export type PanelContent = {
+    content: ReactNode;
+    actions?: ReactNode;
+};
+export declare const ContentProvider: import("react").Provider<ReadonlyMap<string, PanelContent>>;
+export declare function usePanelContent(id: string): PanelContent | undefined;

package/dist/components/labels.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Every word the chassis puts on screen or announces. Already translated: the library carries
+ * no i18n, and a key would impose a namespace on every project that installs it.
+ */
+export type PanelsLabels = {
+    closePanel: string;
+    resizeZone: string;
+    resizeSplit: string;
+    resizeBand: string;
+};
+/** English, so the library works before a project has said anything about words. */
+export declare const DEFAULT_LABELS: PanelsLabels;

package/dist/core/clamps.d.ts

@@ -0,0 +1,55 @@
+import { type Lengths, type OpenByZone, type Zone } from './types';
+/** Smallest a zone may be dragged to before it is worth closing instead. */
+export declare const MIN_SIZE = 140;
+/** Room the centre must keep, whatever the side zones ask for. */
+export declare const MIN_CENTER = 240;
+/** Room a split keeps for the half it is taken from. */
+export declare const MIN_SPLIT = 100;
+/** What a zone opens at when nothing has been dragged and no panel asks for more. */
+export declare const DEFAULT_SIZES: Record<Zone, number>;
+/**
+ * The half that carries the band's height, stored once: two halves lying at two heights would
+ * leave the frame above them in a step.
+ */
+export declare const BAND_MAIN: Zone;
+/** Where a zone's length is read and written — the band's halves share the one key. */
+export declare function sizeKeyOf(zone: Zone): Zone;
+/** The zone that takes room from the same axis, and therefore bounds this one. */
+export declare const OPPOSITE: Record<Zone, Zone>;
+/**
+ * Clamps a zone size against what the opposite zone already takes. Capping each side at half
+ * the container independently would let left and right add up to the full width, leaving the
+ * centre at zero — and overflowing once the container shrinks.
+ */
+export declare function fitZoneSize(size: number, available: number, opposite: number): number;
+/** Same idea one level down: neither half of a zone may swallow the other. */
+export declare function fitSplit(size: number, available: number): number;
+/** True once either half holds something: an empty zone takes no room at all. */
+export declare function isZoneOpen(open: OpenByZone, zone: Zone): boolean;
+/** The band takes its height as soon as EITHER half holds something: the strip is one strip. */
+export declare function isBandOpen(open: OpenByZone): boolean;
+/**
+ * The room a zone currently takes, or zero when it draws nothing. Read while clamping the
+ * opposite zone: under-report it and the other side may be dragged over room this one is
+ * already drawing in, squeezing the centre past its floor.
+ */
+export declare function sizeOf(lengths: Lengths, open: OpenByZone, zone: Zone, undragged: (zone: Zone) => number): number;
+/**
+ * Every stored length, re-clamped to a container of this size. Sizes are persisted, so a layout
+ * set on a wide screen would otherwise overflow a narrow one — pushing the panels under the
+ * rails and squeezing the centre to nothing.
+ */
+export declare function fitted(lengths: Lengths, open: OpenByZone, width: number, height: number, undragged: (zone: Zone) => number): Lengths;
+/**
+ * The two side zones, bounded so the centre keeps its floor — whether or not either was ever
+ * dragged.
+ *
+ * 🛑 `fitted` cannot do this job: it walks the STORED lengths, and a layout nobody has touched
+ * has none. The zones then took the sizes they ask for and the centre took whatever was left,
+ * which on a narrow container was nothing — measured at 104 px against a floor of 240, on a
+ * 900 px window with two untouched columns.
+ *
+ * When the two do not fit, they give ground in PROPORTION to what they asked for: taking it all
+ * from one would collapse the narrower of them while the wider kept its full width.
+ */
+export declare function sharedSizes(leading: number, trailing: number, available: number): [number, number];

package/dist/core/context.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode } from 'react';
+import { type PanelsState, type PanelsStore } from './store';
+import { type LayoutStorage } from './persistence';
+import type { OpenByZone } from './types';
+export type PanelsProviderProps<Id extends string> = {
+    /**
+     * A store built by the project. Pass one to drive the chassis from OUTSIDE React — a socket
+     * message, a native menu, a keyboard shortcut all call `store.getState().show(id)`. Left out,
+     * the provider makes its own.
+     */
+    store?: PanelsStore<Id>;
+    /** Key the layout is stored under. Two chassis in one application need two keys. */
+    storageKey?: string;
+    /** Where the layout is kept. `localStorage` by default; `null` disables persistence. */
+    storage?: LayoutStorage | null;
+    /** Which halves start open, overriding "the first panel declared for that half". */
+    defaultOpen?: OpenByZone<Id>;
+    children: ReactNode;
+};
+export declare function PanelsProvider<Id extends string = string>({ store, storageKey, storage, defaultOpen, children, }: PanelsProviderProps<Id>): import("react").JSX.Element;
+/** The store this chassis runs on. Throws outside a provider rather than answering nothing. */
+export declare function usePanelsStore<Id extends string = string>(): PanelsStore<Id>;
+/** A slice of the chassis state, subscribed. */
+export declare function usePanelsState<Id extends string, T>(selector: (state: PanelsState<Id>) => T): T;
+/**
+ * The actions, which are stable for the store's lifetime — subscribing to them would only add
+ * selectors re-run on every write.
+ */
+export declare function usePanelsActions<Id extends string = string>(): {
+    show: (id: Id) => void;
+    close: (zone: import("./types").Zone, slot: import("./types").Slot) => void;
+    toggle: (id: Id) => void;
+    focus: (zone: import("./types").Zone | null) => void;
+    resize: (zone: import("./types").Zone, size: number, available: number) => void;
+    resplit: (zone: import("./types").Zone, size: number, available: number) => void;
+    resplitBand: (size: number, available: number) => void;
+    fit: (width: number, height: number) => void;
+    reset: () => void;
+};

package/dist/core/cx.d.ts

@@ -0,0 +1,5 @@
+type ClassValue = string | false | null | undefined;
+/** Joins class names, dropping the falsy ones. The library owns its class names, so there is
+ * nothing to merge or de-duplicate — a consumer's `className` is appended and wins by order. */
+export declare function cx(...classes: ClassValue[]): string;
+export {};

package/dist/core/hooks/useArrangement.d.ts

@@ -0,0 +1,36 @@
+import { type OpenByZone, type PanelSpec, type Zone } from '../types';
+/**
+ * What every reader of `shownIn` and `zoneDraws` needs: the declared panels, and which half of
+ * each zone holds which.
+ *
+ * One hook because four of them had written the same pair of selectors and rebuilt the same
+ * object by hand — so the shape those two functions expect could not change without touching
+ * four files.
+ */
+export declare function useArrangement<Id extends string = string>(): {
+    registry: PanelSpec<Id>[];
+    open: OpenByZone<Id>;
+};
+/** What a zone's two halves actually draw — a `solo` panel silences the other. */
+export declare function useShownIn<Id extends string = string>(zone: Zone): {
+    primary?: Id;
+    secondary?: Id;
+};
+/** Whether a zone draws at all. An empty one takes neither room nor handle. */
+export declare function useZoneDraws<Id extends string = string>(zone: Zone): boolean;
+/**
+ * Whether a zone takes room off the axis it shares with its opposite — the band counting as one
+ * strip. See `zoneTakesRoom`: this is not the same question as whether it draws.
+ */
+export declare function useZoneTakesRoom<Id extends string = string>(zone: Zone): boolean;
+/**
+ * Whether each half of the band draws anything — what the frame asks before it arranges itself:
+ * a column runs to the FOOT unless the band's half on its side is drawing.
+ *
+ * Headless, so it lives here rather than beside `<Band>`: a project replacing the band must be
+ * able to ask this without importing from a component file.
+ */
+export declare function useBandHalves<Id extends string = string>(): {
+    left: boolean;
+    right: boolean;
+};

package/dist/core/hooks/useContainerFit.d.ts

@@ -0,0 +1,9 @@
+import { type RefObject } from 'react';
+/**
+ * Re-clamps the zones when the CONTAINER changes size — not the window.
+ *
+ * The difference is what lets the chassis live inside an existing page: measured against
+ * `window`, a chassis sitting under a navigation bar or beside a sidebar believes it has room
+ * it does not have, and the zones can be dragged over the centre until it disappears.
+ */
+export declare function useContainerFit(ref: RefObject<HTMLElement | null>): void;

package/dist/core/hooks/usePanels.d.ts

@@ -0,0 +1,26 @@
+import type { PanelSpec, Zone } from '../types';
+export type PanelsApi<Id extends string> = {
+    /** Every panel the project has declared, in declaration order. */
+    panels: PanelSpec<Id>[];
+    /** Brings a panel up in the half it declared, and focuses its zone. */
+    reveal: (id: Id) => void;
+    /** Closes THIS panel, or nothing — never whatever happens to stand in its half. */
+    close: (id: Id) => void;
+    /** Reveals it if hidden, closes it if shown. What a rail icon does. */
+    toggle: (id: Id) => void;
+    /**
+     * Whether that panel is on screen right now.
+     *
+     * 🛑 Subscribed, and that is the whole point of reading `open` above: written as a plain
+     * `getState()` read it answered correctly on the render it was called in and never ran again,
+     * so a header built on it kept showing the arrangement as it stood when it last mounted.
+     */
+    isShown: (id: Id) => boolean;
+    focusedZone: Zone | null;
+    reset: () => void;
+};
+/**
+ * The chassis, as a project drives it. Everything a header, a shortcut or a menu needs to act
+ * on the panels without knowing anything about how they are laid out.
+ */
+export declare function usePanels<Id extends string = string>(): PanelsApi<Id>;