@sincpro/web-composer 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +269 -2
  3. package/dist/domain/enums.d.ts +55 -0
  4. package/dist/domain/enums.js +48 -0
  5. package/dist/domain/index.d.ts +9 -0
  6. package/dist/domain/index.js +8 -0
  7. package/dist/domain/layout.d.ts +92 -0
  8. package/dist/domain/layout.js +216 -0
  9. package/dist/domain/palette.d.ts +42 -0
  10. package/dist/domain/palette.js +89 -0
  11. package/dist/domain/registry.d.ts +135 -0
  12. package/dist/domain/registry.js +37 -0
  13. package/dist/domain/resource.d.ts +21 -0
  14. package/dist/domain/resource.js +62 -0
  15. package/dist/domain/url.d.ts +16 -0
  16. package/dist/domain/url.js +145 -0
  17. package/dist/domain/workspace.d.ts +174 -0
  18. package/dist/domain/workspace.js +393 -0
  19. package/dist/index.d.ts +24 -0
  20. package/dist/index.js +23 -0
  21. package/dist/shell/Composer.d.ts +23 -0
  22. package/dist/shell/Composer.js +88 -0
  23. package/dist/shell/Palette.d.ts +9 -0
  24. package/dist/shell/Palette.js +124 -0
  25. package/dist/shell/PanelFrame.d.ts +38 -0
  26. package/dist/shell/PanelFrame.js +70 -0
  27. package/dist/shell/PanelHost.d.ts +23 -0
  28. package/dist/shell/PanelHost.js +201 -0
  29. package/dist/shell/Peek.d.ts +26 -0
  30. package/dist/shell/Peek.js +64 -0
  31. package/dist/shell/RecordLink.d.ts +12 -0
  32. package/dist/shell/RecordLink.js +55 -0
  33. package/dist/shell/ViewHost.d.ts +11 -0
  34. package/dist/shell/ViewHost.js +53 -0
  35. package/dist/shell/copy.d.ts +73 -0
  36. package/dist/shell/copy.js +130 -0
  37. package/dist/shell/icons.d.ts +22 -0
  38. package/dist/shell/icons.js +19 -0
  39. package/dist/shell/skin.d.ts +72 -0
  40. package/dist/shell/skin.js +35 -0
  41. package/dist/shell/styles.d.ts +19 -0
  42. package/dist/shell/styles.js +212 -0
  43. package/dist/state/api.d.ts +36 -0
  44. package/dist/state/api.js +170 -0
  45. package/dist/state/drag.d.ts +31 -0
  46. package/dist/state/drag.js +95 -0
  47. package/dist/state/store.d.ts +69 -0
  48. package/dist/state/store.js +200 -0
  49. package/dist/state/useKeyboard.d.ts +16 -0
  50. package/dist/state/useKeyboard.js +63 -0
  51. package/dist/state/useWorkspace.d.ts +23 -0
  52. package/dist/state/useWorkspace.js +34 -0
  53. package/package.json +83 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SINCPRO S.R.L
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,270 @@
1
- # Temporary Holding Version
1
+ # @sincpro/web-composer
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **A window manager for enterprise web apps.** A person opens a record, checks another beside
4
+ it, peeks at a third and keeps a fourth floating while they work — without losing their place,
5
+ and without any screen knowing about the others. A rich API for views, standalone: it depends
6
+ on nothing but React. By [Sincpro](https://github.com/Sincpro-SRL), open source.
7
+
8
+ ```bash
9
+ yarn add @sincpro/web-composer react react-dom
10
+ ```
11
+
12
+ ## Manifesto
13
+
14
+ ### Purpose
15
+
16
+ The composer defines **how work between records behaves**: where each thing opens, how you get
17
+ back, what is remembered, and what the others see. One behaviour, reviewed by Sincpro, for
18
+ every application.
19
+
20
+ UI libraries prefer «one screen, one context» because it is clean. But people who work in
21
+ accounting, audit or support spend the day **between** records: the bank statement against the
22
+ invoices, the journal item against its entry, the customer while the order is half filled.
23
+ Without a window manager, every app either navigates away (the list, its filters and its
24
+ selection are gone) or sends people to browser tabs (the context lives in their head) — and
25
+ each app reinvents peeks, breadcrumbs and panels its own way. The composer solves it once.
26
+
27
+ | Who | The question it answers |
28
+ | ---------------- | ------------------------------------------------------------------------ |
29
+ | **The composer** | Where each view lives and how it moves: page, peek, side panel, window |
30
+ | **Your app** | What a record is and how it looks — drawn with web-ui, or anything else |
31
+ | **A framework** | Puts both together (`@sincpro/web-framework` does, over server metadata) |
32
+
33
+ ### Principles — the contract
34
+
35
+ - **One gesture, one destination.** A click opens the page and the breadcrumb keeps the way
36
+ back; a peek, a window, a side panel are one gesture away, never forced on anyone. Someone
37
+ who never opens a panel just sees pages and breadcrumbs.
38
+ - **References, not data.** The workspace stores `domain:kind/id`. A support case points at an
39
+ invoice and the workspace opens it, while the support code never imports accounting. Views
40
+ can open things and publish what they selected, but cannot read the workspace.
41
+ - **Never lose the place, nor what was typed.** The breadcrumb, the URL, the browser's Back,
42
+ asking before discarding. Moving a panel does not remount it; neither does changing only a
43
+ reference's `params`. The peek belongs to its page: when the page becomes another record, it
44
+ closes.
45
+ - **Opinionated defaults, open doors.** Good practice comes built in, and everything is
46
+ replaceable without forks: the look (`--sc-*`, `skin`), the discard question
47
+ (`confirmDiscard`), where a click goes (`defaultOpen`), any reducer (`apply`).
48
+ - **Standalone.** Only React. The design belongs to whoever uses it; the composer ships a
49
+ minimal skin so it works alone, and nothing else.
50
+ - **Each domain declares itself.** Register a `ViewSpec` and it works in pages, panels, the
51
+ peek and ⌘K. Adding a domain changes no file here — the view can be a module another team
52
+ deploys.
53
+ - **Nothing a person arranges can break it.** A view that throws stays in its own panel; a
54
+ reference nobody resolves says so; a broken link loads what is valid; sizes are clamped.
55
+ - **Addressable by people and agents.** The place lives in the URL and in references, so the
56
+ same API (`context`, `open`, `peek`, `select`) serves a person and an AI agent. An MCP or
57
+ WebMCP adapter fits here — as a separate module, not in the core.
58
+ - **A rule comes with its story.** Every behaviour is a Storybook story with its `play`.
59
+
60
+ ### What it is not
61
+
62
+ - **Not a component library.** No form controls, tables or lists — that is your app (web-ui).
63
+ - **Not a data layer.** No fetching, permissions, entities or sessions.
64
+ - **Not a router** of URL paths, and not a free dashboard layout.
65
+ - **No tabs, no multiple workspaces.** One page, its trail, and what is around it.
66
+ - **No design system, no icon library** as a dependency.
67
+
68
+ ### How something new gets in
69
+
70
+ All three, or it belongs in another package:
71
+
72
+ 1. It answers **where does it open? how do I get back? what is remembered? what does the other
73
+ one see** (a panel following the selection, an agent)?
74
+ 2. It serves **any domain** the same way — if it only makes sense for accounting, it is the
75
+ app's.
76
+ 3. It comes from **real use** (forge, web-framework) and arrives with its story.
77
+
78
+ ## The model
79
+
80
+ One **page**, with its **trail** (the breadcrumb), and around it:
81
+
82
+ | Destination | What it is | When to use it |
83
+ | ----------- | ----------------------------------------------------------------------- | -------------------------------------------- |
84
+ | **page** | Replaces the page; the breadcrumb remembers where you were. The default | Opening a record to work on it |
85
+ | **peek** | A drawer over the page that does not cover the panels | Reading without leaving the place |
86
+ | **window** | Floating: moves anywhere, resizes, can grow into the page | A quick look or edit on top of what you do |
87
+ | **side** | Docked left, right or at the bottom, resizable | A second context that stays: compare, follow |
88
+
89
+ A view opens anything with one call and lets the workspace decide the rest:
90
+
91
+ ```ts
92
+ api.open(ref); // the page — inside the peek, a step IN the drawer
93
+ api.open(ref, { to: "peek" }); // or "window", or "side"
94
+ api.replace(ref); // show it HERE without a step back: the record a form just created
95
+ api.setParams({ tenant }); // a filter that lives in the reference: survives reload and links
96
+ api.crumbs(); // the breadcrumb, ready for List.Crumbs / Record.Crumbs
97
+ api.back(); // one step back: the page's breadcrumb, or the peek's own trail
98
+ api.close(); // leave: closes the panel or the peek; on the page, goes back — «Cancel» anywhere
99
+ api.expand(); // a window, a side panel or the peek grows into the page
100
+ api.setTitle(name); // the record's real name, for the crumbs and the frames, once loaded
101
+ api.setDirty(true); // unsaved: a crumb, a close or the browser's Back ask first
102
+ api.select(refs); // publish what this view has selected
103
+ api.context; // read what the user is on and what is selected — references only
104
+ api.pick(ref, onPick); // open a chooser (a many2one search); its view calls api.answer(ref)
105
+ ```
106
+
107
+ From the app, around the workspace: `workspace.start(ref)` starts over from a menu (no
108
+ breadcrumb behind, no peek, the panels stay), and `useWorkspace({ hash: true })` puts the
109
+ workspace in the URL with the browser's Back working. Unsaved changes are asked with the
110
+ composer's own dialog; `useWorkspace({ confirmDiscard })` replaces it.
111
+
112
+ ## Where each behaviour lives
113
+
114
+ The same gesture means the same thing on every screen:
115
+
116
+ | Where | Gesture | Destination |
117
+ | --------------------------------------------------- | ------------------------ | ------------------------------------------- |
118
+ | A row of a list | click | **page**, with breadcrumb |
119
+ | A record's name INSIDE the peek | click | a step **in the peek**; ← comes back |
120
+ | The record's name in a column (`RecordLink`) | hover icons, Space, ⇧, ⌘ | **peek**, **side**, **window** |
121
+ | A many2one field | open · search | **window** · a window that **answers** |
122
+ | A record's buttons that _lead_ (see its items) | click | **side** |
123
+ | A record's buttons that _produce_ (post, reconcile) | click | nothing opens: they act on the record |
124
+ | Ticking rows | select | nothing opens: the context changes |
125
+ | ⌘K | Enter · ⌥ · ⇧ · ⌘ | **page** · **peek** · **side** · **window** |
126
+
127
+ ## Using it
128
+
129
+ Declare a domain:
130
+
131
+ ```tsx
132
+ import { createRegistry } from "@sincpro/web-composer/domain";
133
+
134
+ const registry = createRegistry([
135
+ {
136
+ domain: "accounting",
137
+ kind: "entry",
138
+ title: (ref) => `Entry ${ref.id}`,
139
+ search: async (query) => findEntries(query), // ⌘K asks every domain that searches
140
+ load: async () => (await import("./EntryView")).EntryView, // lazy: a remote module fits here
141
+ },
142
+ ]);
143
+ ```
144
+
145
+ Draw the workspace:
146
+
147
+ ```tsx
148
+ import {
149
+ Composer,
150
+ installComposerCopy,
151
+ SPANISH_COMPOSER_COPY,
152
+ useWorkspace,
153
+ } from "@sincpro/web-composer";
154
+
155
+ installComposerCopy(SPANISH_COMPOSER_COPY); // optional: the composer's words in Spanish
156
+
157
+ export function App() {
158
+ const workspace = useWorkspace();
159
+ return <Composer workspace={workspace} registry={registry} />;
160
+ }
161
+ ```
162
+
163
+ Write a view — it receives its reference and the API, nothing else. It is drawn with whatever
164
+ your app uses; here, web-ui:
165
+
166
+ ```tsx
167
+ import { RecordLink, type ViewProps } from "@sincpro/web-composer";
168
+ import { List } from "@sincpro/web-ui";
169
+
170
+ export function Entries({ api }: ViewProps) {
171
+ return (
172
+ <List items={entries} keyOf={(e) => e.id} onOpen={(e) => api.open(entryRef(e.id))}>
173
+ <List.Bar>
174
+ <List.Crumbs crumbs={api.crumbs()} />
175
+ </List.Bar>
176
+ <List.Table
177
+ columns={[
178
+ {
179
+ id: "number",
180
+ header: "number",
181
+ value: (e) => e.id,
182
+ cell: (e) => (
183
+ <RecordLink api={api} resource={entryRef(e.id)}>
184
+ {e.id}
185
+ </RecordLink>
186
+ ),
187
+ },
188
+ ]}
189
+ />
190
+ </List>
191
+ );
192
+ }
193
+ ```
194
+
195
+ The Storybook in this repository is the long version: eleven accounting use cases — journal
196
+ entries, journal items, bank reconciliation, a form with relations, an audit where the detail
197
+ follows the selection, ⌘K, the keyboard, what happens when something fails, and your own
198
+ design over the composer.
199
+
200
+ ## Your design over it
201
+
202
+ ### Colors
203
+
204
+ Every color, radius and shadow is a CSS variable with a default (light and dark). Set them
205
+ anywhere above the workspace — no stylesheet to import:
206
+
207
+ ```css
208
+ :root {
209
+ --sc-surface: var(--my-surface);
210
+ --sc-accent: var(--my-brand);
211
+ /* --sc-ground --sc-line --sc-line-strong --sc-ink --sc-muted --sc-danger --sc-scrim
212
+ --sc-shadow --sc-radius --sc-radius-control --sc-text --sc-text-small */
213
+ }
214
+ ```
215
+
216
+ ### Three levels
217
+
218
+ The composer owns the behaviour; the look is yours. Take only what you need:
219
+
220
+ 1. **Colors** — the `--sc-*` variables above.
221
+ 2. **Pieces** — `skin` swaps icons and parts one at a time; what you do not pass stays default:
222
+
223
+ ```tsx
224
+ <Composer
225
+ workspace={workspace}
226
+ registry={registry}
227
+ skin={{
228
+ icons: { close: X, more: Ellipsis }, // any component taking className / strokeWidth
229
+ Peek: MyDrawer, // ({ title, onClose, actions, children })
230
+ Confirm: MyConfirm, // ({ open, title, detail, keep, discard, onAnswer })
231
+ Notice: MyNotice, // ({ heading, detail, bad })
232
+ }}
233
+ />
234
+ ```
235
+
236
+ 3. **Everything** — `skin={{ styles: false }}` drops the default sheet; style the stable `sc-*`
237
+ classes from scratch.
238
+
239
+ The story «11 · Tu diseño sobre el composer» plugs web-ui's `Peek` and lucide's icons this way —
240
+ the composer imports neither.
241
+
242
+ ## Development
243
+
244
+ ```bash
245
+ nvm use # Node 26, from .nvmrc
246
+ make init # pre-commit + yarn install
247
+ make test # vitest: the model's rules (Node) + every story with its play (Chrome)
248
+ make build
249
+ make dev # Storybook on :6007 — one story per use case; «Run tests» in the sidebar
250
+ ```
251
+
252
+ Every operation — local or CI — goes through the `Makefile`; run `make` to list the targets.
253
+
254
+ ```text
255
+ src/domain/ the model: pure TypeScript, no browser state, tested in Node
256
+ src/state/ the store and the API views receive
257
+ src/shell/ the React shell, with its own minimal skin (sc-* classes, --sc-* variables)
258
+ tests/ the model's rules, vitest in Node
259
+ stories/ the use cases, over a fake accounting app drawn with web-ui (dev only)
260
+ ```
261
+
262
+ ## CI/CD
263
+
264
+ The workflows in `.github/workflows/` only delegate to the shared `Sincpro-SRL/.github`
265
+ pipeline, which calls `make init`, `make verify-format`, `make test`,
266
+ `make update-version VERSION=x` and `make publish`.
267
+
268
+ ## License
269
+
270
+ MIT © Sincpro S.R.L.
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Closed vocabularies of the composer. Call sites use `Zone.Right`, never a raw `"right"` — a
3
+ * typo then fails at compile time instead of at runtime.
4
+ */
5
+ export declare const Zone: {
6
+ readonly Left: "left";
7
+ readonly Right: "right";
8
+ readonly Bottom: "bottom";
9
+ readonly Floating: "floating";
10
+ };
11
+ export type Zone = (typeof Zone)[keyof typeof Zone];
12
+ export type Dock = Exclude<Zone, typeof Zone.Floating>;
13
+ export declare const DOCKS: readonly Dock[];
14
+ /**
15
+ * Where a resource opens. `Page` is the default — what people expect of a click on a record —
16
+ * and every other destination is one gesture away, never the only way.
17
+ *
18
+ * Page the main page of the workspace; the breadcrumb keeps the way back
19
+ * Peek a drawer to read without leaving the place
20
+ * Window floating: it moves anywhere, resizes, and can grow into the page
21
+ * Side docked beside the page, resizable
22
+ */
23
+ export declare const Destination: {
24
+ readonly Page: "page";
25
+ readonly Peek: "peek";
26
+ readonly Window: "window";
27
+ readonly Side: "side";
28
+ };
29
+ export type Destination = (typeof Destination)[keyof typeof Destination];
30
+ /** What a view is drawn in. A view does not change shape by surface — density does — but it
31
+ * needs to know which actions to offer. */
32
+ export declare const Surface: {
33
+ readonly Page: "page";
34
+ readonly Panel: "panel";
35
+ readonly Peek: "peek";
36
+ };
37
+ export type Surface = (typeof Surface)[keyof typeof Surface];
38
+ export declare const HandleKind: {
39
+ readonly Zone: "zone";
40
+ readonly Panel: "panel";
41
+ };
42
+ export type HandleKind = (typeof HandleKind)[keyof typeof HandleKind];
43
+ export declare const Axis: {
44
+ readonly X: "x";
45
+ readonly Y: "y";
46
+ };
47
+ export type Axis = (typeof Axis)[keyof typeof Axis];
48
+ export declare const DragKind: {
49
+ /** A docked panel dragged by its header, to be dropped on another edge. */
50
+ readonly Panel: "panel";
51
+ /** A reference dragged out of a row or a field, to be dropped on an edge. */
52
+ readonly Ref: "ref";
53
+ readonly Zone: "zone";
54
+ };
55
+ export type DragKind = (typeof DragKind)[keyof typeof DragKind];
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Closed vocabularies of the composer. Call sites use `Zone.Right`, never a raw `"right"` — a
3
+ * typo then fails at compile time instead of at runtime.
4
+ */
5
+ export const Zone = {
6
+ Left: "left",
7
+ Right: "right",
8
+ Bottom: "bottom",
9
+ Floating: "floating",
10
+ };
11
+ export const DOCKS = [Zone.Left, Zone.Right, Zone.Bottom];
12
+ /**
13
+ * Where a resource opens. `Page` is the default — what people expect of a click on a record —
14
+ * and every other destination is one gesture away, never the only way.
15
+ *
16
+ * Page the main page of the workspace; the breadcrumb keeps the way back
17
+ * Peek a drawer to read without leaving the place
18
+ * Window floating: it moves anywhere, resizes, and can grow into the page
19
+ * Side docked beside the page, resizable
20
+ */
21
+ export const Destination = {
22
+ Page: "page",
23
+ Peek: "peek",
24
+ Window: "window",
25
+ Side: "side",
26
+ };
27
+ /** What a view is drawn in. A view does not change shape by surface — density does — but it
28
+ * needs to know which actions to offer. */
29
+ export const Surface = {
30
+ Page: "page",
31
+ Panel: "panel",
32
+ Peek: "peek",
33
+ };
34
+ export const HandleKind = {
35
+ Zone: "zone",
36
+ Panel: "panel",
37
+ };
38
+ export const Axis = {
39
+ X: "x",
40
+ Y: "y",
41
+ };
42
+ export const DragKind = {
43
+ /** A docked panel dragged by its header, to be dropped on another edge. */
44
+ Panel: "panel",
45
+ /** A reference dragged out of a row or a field, to be dropped on an edge. */
46
+ Ref: "ref",
47
+ Zone: "zone",
48
+ };
@@ -0,0 +1,9 @@
1
+ /** The model: no React, no CSS. Tested in Node; survives any change of skin. */
2
+ export type { Dock } from "./enums.js";
3
+ export { Axis, Destination, DOCKS, DragKind, HandleKind, Surface, Zone, } from "./enums.js";
4
+ export { type Box, type Handle, handles, KEYBOARD_STEP, layout, type Length, resolve, sizeAt, type Slot, stableOrder, STRIP, ZONE_LIMITS, } from "./layout.js";
5
+ export { localEntries, matches, MIN_QUERY, type PaletteEntry, PaletteSection, searchEntries, } from "./palette.js";
6
+ export { type Action, createRegistry, type Crumb, loadView, type OpenOptions, type PickOptions, type Registry, type SearchHit, type ViewProps, type ViewSpec, type WorkspaceApi, } from "./registry.js";
7
+ export { formatRef, isRef, parseRef, type ResourceRef, rootRef, sameRef, withParams, } from "./resource.js";
8
+ export { fromHash, restore, type SessionMemory, toHash, } from "./url.js";
9
+ export { back, closePanel, closePeek, collapsePanel, cycleFocus, DEFAULT_ZONES, drillPeek, EMPTY, expandPanel, findPanel, floatPanel, focusedRef, focusPanel, goTo, MAX_ZONE, maximize, MIN_SHARE, MIN_ZONE, movePanel, nameOf, nameRef, navigatePanel, openPanel, type OpenPanelOptions, PAGE, type Panel, panelsIn, PEEK, peek, peekBack, peekGoTo, peekToPage, peekToSide, type Placement, push, raisePanel, refOn, replace, replacePeek, resizePanel, resizeZone, select, type Selected, selectionOf, start, type WindowBox, type Workspace, type Zones, } from "./workspace.js";
@@ -0,0 +1,8 @@
1
+ /** The model: no React, no CSS. Tested in Node; survives any change of skin. */
2
+ export { Axis, Destination, DOCKS, DragKind, HandleKind, Surface, Zone, } from "./enums.js";
3
+ export { handles, KEYBOARD_STEP, layout, resolve, sizeAt, stableOrder, STRIP, ZONE_LIMITS, } from "./layout.js";
4
+ export { localEntries, matches, MIN_QUERY, PaletteSection, searchEntries, } from "./palette.js";
5
+ export { createRegistry, loadView, } from "./registry.js";
6
+ export { formatRef, isRef, parseRef, rootRef, sameRef, withParams, } from "./resource.js";
7
+ export { fromHash, restore, toHash, } from "./url.js";
8
+ export { back, closePanel, closePeek, collapsePanel, cycleFocus, DEFAULT_ZONES, drillPeek, EMPTY, expandPanel, findPanel, floatPanel, focusedRef, focusPanel, goTo, MAX_ZONE, maximize, MIN_SHARE, MIN_ZONE, movePanel, nameOf, nameRef, navigatePanel, openPanel, PAGE, panelsIn, PEEK, peek, peekBack, peekGoTo, peekToPage, peekToSide, push, raisePanel, refOn, replace, replacePeek, resizePanel, resizeZone, select, selectionOf, start, } from "./workspace.js";
@@ -0,0 +1,92 @@
1
+ import { Axis, type Dock, HandleKind } from "./enums.js";
2
+ import type { ResourceRef } from "./resource.js";
3
+ import { type Panel, type Workspace } from "./workspace.js";
4
+ /**
5
+ * Geometry is a pure function, not a nested `<div>` tree: moving a panel must not unmount it.
6
+ * Every panel is a sibling on one layer; only its box changes, so React keeps the node — scroll,
7
+ * filters, and typed input included.
8
+ *
9
+ * ┌──────────┬───────────────────┬──────────┐
10
+ * │ │ │ │ ┌────────┐
11
+ * │ left │ page │ right │ │ window │
12
+ * │ ├───────────────────┤ │ └────────┘
13
+ * │ │ bottom │ │
14
+ * └──────────┴───────────────────┴──────────┘
15
+ */
16
+ /**
17
+ * A fraction of the container plus pixels — `calc(fr·100% + px)`. A minimized panel is a fixed
18
+ * strip while its neighbours are still a share, and neither unit alone can say «the zone minus
19
+ * two headers».
20
+ */
21
+ export type Length = {
22
+ fr: number;
23
+ px: number;
24
+ };
25
+ export type Box = {
26
+ left: Length;
27
+ top: Length;
28
+ width: Length;
29
+ height: Length;
30
+ };
31
+ export type Slot = {
32
+ /** `PAGE` for the page; the panel id for everything else. */
33
+ id: string;
34
+ view: ResourceRef;
35
+ panel: Panel | null;
36
+ box: Box;
37
+ floating: boolean;
38
+ /** Stacking of windows. 0 for docked slots. */
39
+ z: number;
40
+ /** Maximized hides the rest instead of dropping them from the list, so React does not
41
+ * unmount them. */
42
+ visible: boolean;
43
+ collapsed: boolean;
44
+ /** Minimized into a strip that is NARROW, not short: a left or right zone with every panel
45
+ * minimized, or one minimized among open ones at the bottom. Its title reads vertically. */
46
+ rail: boolean;
47
+ };
48
+ /** A length measured on a container `size` pixels long. */
49
+ export declare const resolve: (l: Length, size: number) => number;
50
+ /** What a minimized panel keeps: its title bar. It matches the frame's header. */
51
+ export declare const STRIP = 36;
52
+ export declare function layout(w: Workspace): readonly Slot[];
53
+ /** Sorted by id so sibling order does not change when a panel changes zone — reordering
54
+ * siblings is what unmounts. */
55
+ export declare function stableOrder(slots: readonly Slot[]): readonly Slot[];
56
+ /**
57
+ * A resize handle. Two kinds, two mutations:
58
+ *
59
+ * `zone` the edge between a zone and the page. Mutates `Workspace.zones`.
60
+ * `panel` the edge between two panels in the SAME zone. What one gains, the neighbour loses.
61
+ *
62
+ * A zone shrunk to its strip has no handle, and neither does the edge of a minimized panel:
63
+ * there is nothing to resize until it is restored.
64
+ *
65
+ * Nested split containers (`react-resizable-panels`) are out: they unmount a panel when it
66
+ * changes zone.
67
+ */
68
+ type Measure = {
69
+ axis: Axis;
70
+ at: Length;
71
+ origin: Length;
72
+ span: Length;
73
+ invert: boolean;
74
+ };
75
+ export type Handle = ({
76
+ kind: typeof HandleKind.Zone;
77
+ zone: Dock;
78
+ } & Measure) | ({
79
+ kind: typeof HandleKind.Panel;
80
+ panelId: string;
81
+ } & Measure);
82
+ /** The stored size a pointer `p` pixels into a container `size` pixels long asks for. */
83
+ export declare function sizeAt(handle: Handle, p: number, size: number): number;
84
+ export declare function handles(w: Workspace): readonly Handle[];
85
+ /** How far an arrow key moves a handle. A mouse-only handle leaves the workspace
86
+ * half-assembled for anyone who does not use a pointer. */
87
+ export declare const KEYBOARD_STEP = 0.02;
88
+ export declare const ZONE_LIMITS: {
89
+ min: number;
90
+ max: number;
91
+ };
92
+ export {};