@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.
- package/LICENSE +21 -0
- package/README.md +269 -2
- package/dist/domain/enums.d.ts +55 -0
- package/dist/domain/enums.js +48 -0
- package/dist/domain/index.d.ts +9 -0
- package/dist/domain/index.js +8 -0
- package/dist/domain/layout.d.ts +92 -0
- package/dist/domain/layout.js +216 -0
- package/dist/domain/palette.d.ts +42 -0
- package/dist/domain/palette.js +89 -0
- package/dist/domain/registry.d.ts +135 -0
- package/dist/domain/registry.js +37 -0
- package/dist/domain/resource.d.ts +21 -0
- package/dist/domain/resource.js +62 -0
- package/dist/domain/url.d.ts +16 -0
- package/dist/domain/url.js +145 -0
- package/dist/domain/workspace.d.ts +174 -0
- package/dist/domain/workspace.js +393 -0
- package/dist/index.d.ts +24 -0
- package/dist/index.js +23 -0
- package/dist/shell/Composer.d.ts +23 -0
- package/dist/shell/Composer.js +88 -0
- package/dist/shell/Palette.d.ts +9 -0
- package/dist/shell/Palette.js +124 -0
- package/dist/shell/PanelFrame.d.ts +38 -0
- package/dist/shell/PanelFrame.js +70 -0
- package/dist/shell/PanelHost.d.ts +23 -0
- package/dist/shell/PanelHost.js +201 -0
- package/dist/shell/Peek.d.ts +26 -0
- package/dist/shell/Peek.js +64 -0
- package/dist/shell/RecordLink.d.ts +12 -0
- package/dist/shell/RecordLink.js +55 -0
- package/dist/shell/ViewHost.d.ts +11 -0
- package/dist/shell/ViewHost.js +53 -0
- package/dist/shell/copy.d.ts +73 -0
- package/dist/shell/copy.js +130 -0
- package/dist/shell/icons.d.ts +22 -0
- package/dist/shell/icons.js +19 -0
- package/dist/shell/skin.d.ts +72 -0
- package/dist/shell/skin.js +35 -0
- package/dist/shell/styles.d.ts +19 -0
- package/dist/shell/styles.js +212 -0
- package/dist/state/api.d.ts +36 -0
- package/dist/state/api.js +170 -0
- package/dist/state/drag.d.ts +31 -0
- package/dist/state/drag.js +95 -0
- package/dist/state/store.d.ts +69 -0
- package/dist/state/store.js +200 -0
- package/dist/state/useKeyboard.d.ts +16 -0
- package/dist/state/useKeyboard.js +63 -0
- package/dist/state/useWorkspace.d.ts +23 -0
- package/dist/state/useWorkspace.js +34 -0
- 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
|
-
#
|
|
1
|
+
# @sincpro/web-composer
|
|
2
2
|
|
|
3
|
-
|
|
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 {};
|