@sincpro/web-composer 0.0.0-stage → 0.1.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 +198 -2
- package/dist/domain/enums.d.ts +65 -0
- package/dist/domain/enums.js +56 -0
- package/dist/domain/index.d.ts +9 -0
- package/dist/domain/index.js +8 -0
- package/dist/domain/layout.d.ts +75 -0
- package/dist/domain/layout.js +180 -0
- package/dist/domain/palette.d.ts +42 -0
- package/dist/domain/palette.js +89 -0
- package/dist/domain/registry.d.ts +112 -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 +3 -0
- package/dist/domain/url.js +107 -0
- package/dist/domain/workspace.d.ts +138 -0
- package/dist/domain/workspace.js +272 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +19 -0
- package/dist/shell/Composer.d.ts +24 -0
- package/dist/shell/Composer.js +59 -0
- package/dist/shell/Palette.d.ts +9 -0
- package/dist/shell/Palette.js +123 -0
- package/dist/shell/PanelFrame.d.ts +31 -0
- package/dist/shell/PanelFrame.js +44 -0
- package/dist/shell/PanelHost.d.ts +23 -0
- package/dist/shell/PanelHost.js +188 -0
- package/dist/shell/RecordLink.d.ts +12 -0
- package/dist/shell/RecordLink.js +51 -0
- package/dist/shell/ViewHost.d.ts +11 -0
- package/dist/shell/ViewHost.js +42 -0
- package/dist/shell/copy.d.ts +64 -0
- package/dist/shell/copy.js +108 -0
- package/dist/state/api.d.ts +32 -0
- package/dist/state/api.js +140 -0
- package/dist/state/drag.d.ts +31 -0
- package/dist/state/drag.js +95 -0
- package/dist/state/store.d.ts +45 -0
- package/dist/state/store.js +76 -0
- package/dist/state/useKeyboard.d.ts +12 -0
- package/dist/state/useKeyboard.js +55 -0
- package/dist/state/useWorkspace.d.ts +23 -0
- package/dist/state/useWorkspace.js +34 -0
- package/package.json +82 -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,199 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @sincpro/web-composer
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**How enterprise screens are put together.** A workspace for React where a person opens a
|
|
4
|
+
record, checks another one beside it, peeks at a third, and keeps a fourth floating while they
|
|
5
|
+
work — without losing their place, and without any screen knowing about the others. By
|
|
6
|
+
[Sincpro](https://github.com/Sincpro-SRL), open source.
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
yarn add @sincpro/web-composer @sincpro/web-ui react react-dom
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Requires React 19 or newer and [`@sincpro/web-ui`](https://github.com/Sincpro-SRL/sincpro_web_ui).
|
|
13
|
+
|
|
14
|
+
## Why
|
|
15
|
+
|
|
16
|
+
People who work in an ERP spend the day **between records**. An accountant reconciles a bank
|
|
17
|
+
statement against invoices. An auditor walks journal items and checks the entry each one came
|
|
18
|
+
from. Somebody filling an order needs to look at the customer, the stock and last month's
|
|
19
|
+
invoice — now, not after closing the form.
|
|
20
|
+
|
|
21
|
+
Most business software answers that with one of two bad options:
|
|
22
|
+
|
|
23
|
+
- **Navigate away.** You open the invoice, and the list you were working on is gone. You come
|
|
24
|
+
back and the filters, the scroll and the selection are gone too.
|
|
25
|
+
- **Open another browser tab.** Now the context lives in your head: which tab had what, and
|
|
26
|
+
which one is stale.
|
|
27
|
+
|
|
28
|
+
Both make people do the remembering. The composer makes the workspace do it.
|
|
29
|
+
|
|
30
|
+
## The vision
|
|
31
|
+
|
|
32
|
+
Sincpro builds enterprise interfaces with two packages, and each one owns a different question:
|
|
33
|
+
|
|
34
|
+
| Package | The question it answers |
|
|
35
|
+
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
|
|
36
|
+
| [`@sincpro/web-ui`](https://github.com/Sincpro-SRL/sincpro_web_ui) | **What a screen looks like** — tokens, primitives, `List` (N records), `Record` (one) |
|
|
37
|
+
| `@sincpro/web-composer` | **How screens are put together** — where a record opens, how two of them sit side by side, how one follows another |
|
|
38
|
+
| Your application | **What a record is** — invoices, payments, journal entries |
|
|
39
|
+
|
|
40
|
+
Neither package knows your domain. Together they are how we build business software: web-ui
|
|
41
|
+
draws the screens, the composer arranges them, and the application only declares its records.
|
|
42
|
+
|
|
43
|
+
### Principles
|
|
44
|
+
|
|
45
|
+
- **A click does the predictable thing.** Opening a record replaces the page, and the
|
|
46
|
+
breadcrumb keeps the way back. Everything else — a peek, a window, a side panel — is one
|
|
47
|
+
gesture away, never forced on anyone. Someone who never opens a panel just sees pages and
|
|
48
|
+
breadcrumbs.
|
|
49
|
+
- **References, not data.** The workspace stores `domain:kind/id`. A support case can point at
|
|
50
|
+
an invoice and the workspace opens it, while the support code never imports accounting.
|
|
51
|
+
- **Each domain declares itself.** Register a `ViewSpec` and it works: in pages, panels, the
|
|
52
|
+
peek and ⌘K. Adding a domain changes no file in this package — and the view can be a module
|
|
53
|
+
another team deploys.
|
|
54
|
+
- **Nothing a person arranges can break it.** A view that throws stays in its own panel. A
|
|
55
|
+
reference nobody can resolve says so. A broken link loads what is valid. Sizes are clamped.
|
|
56
|
+
- **Moving is not remounting.** Every surface is a sibling on one layer; only its box changes.
|
|
57
|
+
A panel moved to another edge keeps its scroll, its filters and what was typed in it.
|
|
58
|
+
- **Views stay apart.** A view can open things and publish what it selected, but it cannot read
|
|
59
|
+
the workspace — two domains talk through references, never through each other.
|
|
60
|
+
|
|
61
|
+
## The model
|
|
62
|
+
|
|
63
|
+
One **page**, with its **trail** (the breadcrumb), and around it:
|
|
64
|
+
|
|
65
|
+
| Destination | What it is | When to use it |
|
|
66
|
+
| ----------- | ----------------------------------------------------------------------- | -------------------------------------------- |
|
|
67
|
+
| **page** | Replaces the page; the breadcrumb remembers where you were. The default | Opening a record to work on it |
|
|
68
|
+
| **peek** | A drawer over the page that does not cover the panels | Reading without leaving the place |
|
|
69
|
+
| **window** | Floating: moves anywhere, resizes, can grow into the page | A quick look or edit on top of what you do |
|
|
70
|
+
| **side** | Docked left, right or at the bottom, resizable | A second context that stays: compare, follow |
|
|
71
|
+
|
|
72
|
+
A view opens anything with one call and lets the workspace decide the rest:
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
api.open(ref); // the page
|
|
76
|
+
api.open(ref, { to: "peek" }); // or "window", or "side"
|
|
77
|
+
api.crumbs(); // the breadcrumb, ready for List.Crumbs / Record.Crumbs
|
|
78
|
+
api.back(); // one page back
|
|
79
|
+
api.expand(); // a window, a side panel or the peek grows into the page
|
|
80
|
+
api.select(refs); // publish what this view has selected
|
|
81
|
+
api.context; // read what the user is on and what is selected — references only
|
|
82
|
+
api.pick(ref, onPick); // open a chooser (a many2one search); its view calls api.answer(ref)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Where each behaviour lives
|
|
86
|
+
|
|
87
|
+
The same gesture means the same thing on every screen:
|
|
88
|
+
|
|
89
|
+
| Where | Gesture | Destination |
|
|
90
|
+
| --------------------------------------------------- | ------------------------ | ------------------------------------------- |
|
|
91
|
+
| A row of a list | click | **page**, with breadcrumb |
|
|
92
|
+
| The record's name in a column (`RecordLink`) | hover icons, Space, ⇧, ⌘ | **peek**, **side**, **window** |
|
|
93
|
+
| A many2one field | open · search | **window** · a window that **answers** |
|
|
94
|
+
| A record's buttons that _lead_ (see its items) | click | **side** |
|
|
95
|
+
| A record's buttons that _produce_ (post, reconcile) | click | nothing opens: they act on the record |
|
|
96
|
+
| Ticking rows | select | nothing opens: the context changes |
|
|
97
|
+
| ⌘K | Enter · ⌥ · ⇧ · ⌘ | **page** · **peek** · **side** · **window** |
|
|
98
|
+
|
|
99
|
+
## Using it
|
|
100
|
+
|
|
101
|
+
Declare a domain:
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
import { createRegistry } from "@sincpro/web-composer/domain";
|
|
105
|
+
|
|
106
|
+
const registry = createRegistry([
|
|
107
|
+
{
|
|
108
|
+
domain: "accounting",
|
|
109
|
+
kind: "entry",
|
|
110
|
+
title: (ref) => `Entry ${ref.id}`,
|
|
111
|
+
search: async (query) => findEntries(query), // ⌘K asks every domain that searches
|
|
112
|
+
load: async () => (await import("./EntryView")).EntryView, // lazy: a remote module fits here
|
|
113
|
+
},
|
|
114
|
+
]);
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Draw the workspace:
|
|
118
|
+
|
|
119
|
+
```tsx
|
|
120
|
+
import {
|
|
121
|
+
Composer,
|
|
122
|
+
installComposerCopy,
|
|
123
|
+
SPANISH_COMPOSER_COPY,
|
|
124
|
+
useWorkspace,
|
|
125
|
+
} from "@sincpro/web-composer";
|
|
126
|
+
|
|
127
|
+
installComposerCopy(SPANISH_COMPOSER_COPY); // optional: the composer's words in Spanish
|
|
128
|
+
|
|
129
|
+
export function App() {
|
|
130
|
+
const workspace = useWorkspace();
|
|
131
|
+
return <Composer workspace={workspace} registry={registry} />;
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Write a view — it receives its reference and the API, nothing else:
|
|
136
|
+
|
|
137
|
+
```tsx
|
|
138
|
+
import { RecordLink, type ViewProps } from "@sincpro/web-composer";
|
|
139
|
+
import { List } from "@sincpro/web-ui";
|
|
140
|
+
|
|
141
|
+
export function Entries({ api }: ViewProps) {
|
|
142
|
+
return (
|
|
143
|
+
<List items={entries} keyOf={(e) => e.id} onOpen={(e) => api.open(entryRef(e.id))}>
|
|
144
|
+
<List.Bar>
|
|
145
|
+
<List.Crumbs crumbs={api.crumbs()} />
|
|
146
|
+
</List.Bar>
|
|
147
|
+
<List.Table
|
|
148
|
+
columns={[
|
|
149
|
+
{
|
|
150
|
+
id: "number",
|
|
151
|
+
header: "number",
|
|
152
|
+
value: (e) => e.id,
|
|
153
|
+
cell: (e) => (
|
|
154
|
+
<RecordLink api={api} resource={entryRef(e.id)}>
|
|
155
|
+
{e.id}
|
|
156
|
+
</RecordLink>
|
|
157
|
+
),
|
|
158
|
+
},
|
|
159
|
+
]}
|
|
160
|
+
/>
|
|
161
|
+
</List>
|
|
162
|
+
);
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
The Storybook in this repository is the long version: ten accounting use cases — journal
|
|
167
|
+
entries, journal items, bank reconciliation, a form with relations, an audit where the detail
|
|
168
|
+
follows the selection, ⌘K, the keyboard, and what happens when something fails.
|
|
169
|
+
|
|
170
|
+
## Development
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
nvm use # Node 26, from .nvmrc
|
|
174
|
+
make init # pre-commit + yarn install
|
|
175
|
+
make test
|
|
176
|
+
make build
|
|
177
|
+
make dev # Storybook on :6007 — one story per use case
|
|
178
|
+
make smoke # every story in headless Chrome, play functions included
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Every operation — local or CI — goes through the `Makefile`; run `make` to list the targets.
|
|
182
|
+
|
|
183
|
+
```text
|
|
184
|
+
src/domain/ the model: pure TypeScript, no browser state, tested in Node
|
|
185
|
+
src/state/ the store and the API views receive
|
|
186
|
+
src/shell/ the React shell, drawn with @sincpro/web-ui
|
|
187
|
+
tests/ node --test over the TypeScript sources
|
|
188
|
+
stories/ the use cases, over a fake accounting domain in stories/contabilidad/
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## CI/CD
|
|
192
|
+
|
|
193
|
+
The workflows in `.github/workflows/` only delegate to the shared `Sincpro-SRL/.github`
|
|
194
|
+
pipeline, which calls `make init`, `make verify-format`, `make test`,
|
|
195
|
+
`make update-version VERSION=x` and `make publish`.
|
|
196
|
+
|
|
197
|
+
## License
|
|
198
|
+
|
|
199
|
+
MIT © Sincpro S.R.L.
|
|
@@ -0,0 +1,65 @@
|
|
|
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 BoxUnit: {
|
|
39
|
+
readonly Fraction: "fraction";
|
|
40
|
+
readonly Pixel: "pixel";
|
|
41
|
+
};
|
|
42
|
+
export type BoxUnit = (typeof BoxUnit)[keyof typeof BoxUnit];
|
|
43
|
+
export declare const HandleKind: {
|
|
44
|
+
readonly Zone: "zone";
|
|
45
|
+
readonly Panel: "panel";
|
|
46
|
+
};
|
|
47
|
+
export type HandleKind = (typeof HandleKind)[keyof typeof HandleKind];
|
|
48
|
+
export declare const Axis: {
|
|
49
|
+
readonly X: "x";
|
|
50
|
+
readonly Y: "y";
|
|
51
|
+
};
|
|
52
|
+
export type Axis = (typeof Axis)[keyof typeof Axis];
|
|
53
|
+
export declare const Split: {
|
|
54
|
+
readonly Vertical: "vertical";
|
|
55
|
+
readonly Horizontal: "horizontal";
|
|
56
|
+
};
|
|
57
|
+
export type Split = (typeof Split)[keyof typeof Split];
|
|
58
|
+
export declare const DragKind: {
|
|
59
|
+
/** A docked panel dragged by its header, to be dropped on another edge. */
|
|
60
|
+
readonly Panel: "panel";
|
|
61
|
+
/** A reference dragged out of a row or a field, to be dropped on an edge. */
|
|
62
|
+
readonly Ref: "ref";
|
|
63
|
+
readonly Zone: "zone";
|
|
64
|
+
};
|
|
65
|
+
export type DragKind = (typeof DragKind)[keyof typeof DragKind];
|
|
@@ -0,0 +1,56 @@
|
|
|
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 BoxUnit = {
|
|
35
|
+
Fraction: "fraction",
|
|
36
|
+
Pixel: "pixel",
|
|
37
|
+
};
|
|
38
|
+
export const HandleKind = {
|
|
39
|
+
Zone: "zone",
|
|
40
|
+
Panel: "panel",
|
|
41
|
+
};
|
|
42
|
+
export const Axis = {
|
|
43
|
+
X: "x",
|
|
44
|
+
Y: "y",
|
|
45
|
+
};
|
|
46
|
+
export const Split = {
|
|
47
|
+
Vertical: "vertical",
|
|
48
|
+
Horizontal: "horizontal",
|
|
49
|
+
};
|
|
50
|
+
export const DragKind = {
|
|
51
|
+
/** A docked panel dragged by its header, to be dropped on another edge. */
|
|
52
|
+
Panel: "panel",
|
|
53
|
+
/** A reference dragged out of a row or a field, to be dropped on an edge. */
|
|
54
|
+
Ref: "ref",
|
|
55
|
+
Zone: "zone",
|
|
56
|
+
};
|
|
@@ -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, BoxUnit, Destination, DOCKS, DragKind, HandleKind, Split, Surface, Zone, } from "./enums.js";
|
|
4
|
+
export { type Box, type Handle, handles, KEYBOARD_STEP, layout, sizeAt, type Slot, stableOrder, 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, toHash } from "./url.js";
|
|
9
|
+
export { back, closePanel, closePeek, collapsePanel, cycleFocus, DEFAULT_ZONES, EMPTY, expandPanel, findPanel, floatPanel, focusedRef, focusPanel, goTo, MAX_ZONE, maximize, MIN_SHARE, MIN_ZONE, movePanel, navigatePanel, openPanel, type OpenPanelOptions, PAGE, type Panel, panelsIn, peek, peekToPage, peekToSide, type Placement, push, raisePanel, resizePanel, resizeZone, select, type Selected, selectionOf, 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, BoxUnit, Destination, DOCKS, DragKind, HandleKind, Split, Surface, Zone, } from "./enums.js";
|
|
3
|
+
export { handles, KEYBOARD_STEP, layout, sizeAt, stableOrder, 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, toHash } from "./url.js";
|
|
8
|
+
export { back, closePanel, closePeek, collapsePanel, cycleFocus, DEFAULT_ZONES, EMPTY, expandPanel, findPanel, floatPanel, focusedRef, focusPanel, goTo, MAX_ZONE, maximize, MIN_SHARE, MIN_ZONE, movePanel, navigatePanel, openPanel, PAGE, panelsIn, peek, peekToPage, peekToSide, push, raisePanel, resizePanel, resizeZone, select, selectionOf, } from "./workspace.js";
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import { Axis, BoxUnit, 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
|
+
export type Box = {
|
|
17
|
+
unit: BoxUnit;
|
|
18
|
+
left: number;
|
|
19
|
+
top: number;
|
|
20
|
+
width: number;
|
|
21
|
+
height: number;
|
|
22
|
+
};
|
|
23
|
+
export type Slot = {
|
|
24
|
+
/** `PAGE` for the page; the panel id for everything else. */
|
|
25
|
+
id: string;
|
|
26
|
+
view: ResourceRef;
|
|
27
|
+
panel: Panel | null;
|
|
28
|
+
box: Box;
|
|
29
|
+
floating: boolean;
|
|
30
|
+
/** Stacking of windows. 0 for docked slots. */
|
|
31
|
+
z: number;
|
|
32
|
+
/** Maximized hides the rest instead of dropping them from the list, so React does not
|
|
33
|
+
* unmount them. */
|
|
34
|
+
visible: boolean;
|
|
35
|
+
collapsed: boolean;
|
|
36
|
+
};
|
|
37
|
+
export declare function layout(w: Workspace): readonly Slot[];
|
|
38
|
+
/** Sorted by id so sibling order does not change when a panel changes zone — reordering
|
|
39
|
+
* siblings is what unmounts. */
|
|
40
|
+
export declare function stableOrder(slots: readonly Slot[]): readonly Slot[];
|
|
41
|
+
/**
|
|
42
|
+
* A resize handle. Two kinds, two mutations:
|
|
43
|
+
*
|
|
44
|
+
* `zone` the edge between a zone and the page. Mutates `Workspace.zones`.
|
|
45
|
+
* `panel` the edge between two panels in the SAME zone. What one gains, the neighbour loses.
|
|
46
|
+
*
|
|
47
|
+
* Nested split containers (`react-resizable-panels`) are out: they unmount a panel when it
|
|
48
|
+
* changes zone.
|
|
49
|
+
*/
|
|
50
|
+
export type Handle = {
|
|
51
|
+
kind: typeof HandleKind.Zone;
|
|
52
|
+
zone: Dock;
|
|
53
|
+
axis: Axis;
|
|
54
|
+
at: number;
|
|
55
|
+
origin: number;
|
|
56
|
+
span: number;
|
|
57
|
+
invert: boolean;
|
|
58
|
+
} | {
|
|
59
|
+
kind: typeof HandleKind.Panel;
|
|
60
|
+
panelId: string;
|
|
61
|
+
axis: Axis;
|
|
62
|
+
at: number;
|
|
63
|
+
origin: number;
|
|
64
|
+
span: number;
|
|
65
|
+
invert: boolean;
|
|
66
|
+
};
|
|
67
|
+
export declare function sizeAt(handle: Handle, p: number): number;
|
|
68
|
+
export declare function handles(w: Workspace): readonly Handle[];
|
|
69
|
+
/** How far an arrow key moves a handle. A mouse-only handle leaves the workspace
|
|
70
|
+
* half-assembled for anyone who does not use a pointer. */
|
|
71
|
+
export declare const KEYBOARD_STEP = 0.02;
|
|
72
|
+
export declare const ZONE_LIMITS: {
|
|
73
|
+
min: number;
|
|
74
|
+
max: number;
|
|
75
|
+
};
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
import { Axis, BoxUnit, HandleKind, Split, Zone, } from "./enums.js";
|
|
2
|
+
import { MAX_ZONE, MIN_ZONE, PAGE, panelsIn, } from "./workspace.js";
|
|
3
|
+
const fraction = (left, top, width, height) => ({
|
|
4
|
+
unit: BoxUnit.Fraction,
|
|
5
|
+
left,
|
|
6
|
+
top,
|
|
7
|
+
width,
|
|
8
|
+
height,
|
|
9
|
+
});
|
|
10
|
+
const FULL = fraction(0, 0, 1, 1);
|
|
11
|
+
/** Title bar of a window when it is minimized. Matches the header. */
|
|
12
|
+
const WINDOW_TITLEBAR = 36;
|
|
13
|
+
const extent = (w, zone) => panelsIn(w, zone).length === 0 ? 0 : w.zones[zone];
|
|
14
|
+
function split(panels, axis, box) {
|
|
15
|
+
let cursor = 0;
|
|
16
|
+
return panels.map((panel) => {
|
|
17
|
+
const share = panel.placement.zone === Zone.Floating ? 0 : panel.placement.share;
|
|
18
|
+
const slotBox = axis === Split.Vertical
|
|
19
|
+
? fraction(box.left, box.top + box.height * cursor, box.width, box.height * share)
|
|
20
|
+
: fraction(box.left + box.width * cursor, box.top, box.width * share, box.height);
|
|
21
|
+
cursor += share;
|
|
22
|
+
return {
|
|
23
|
+
id: panel.id,
|
|
24
|
+
view: panel.view,
|
|
25
|
+
panel,
|
|
26
|
+
box: slotBox,
|
|
27
|
+
floating: false,
|
|
28
|
+
z: 0,
|
|
29
|
+
visible: true,
|
|
30
|
+
collapsed: panel.placement.collapsed === true,
|
|
31
|
+
};
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
function windows(panels) {
|
|
35
|
+
return panels.flatMap((panel) => panel.placement.zone !== Zone.Floating
|
|
36
|
+
? []
|
|
37
|
+
: [
|
|
38
|
+
{
|
|
39
|
+
id: panel.id,
|
|
40
|
+
view: panel.view,
|
|
41
|
+
panel,
|
|
42
|
+
box: {
|
|
43
|
+
unit: BoxUnit.Pixel,
|
|
44
|
+
left: panel.placement.x,
|
|
45
|
+
top: panel.placement.y,
|
|
46
|
+
width: panel.placement.w,
|
|
47
|
+
height: panel.placement.collapsed === true ? WINDOW_TITLEBAR : panel.placement.h,
|
|
48
|
+
},
|
|
49
|
+
floating: true,
|
|
50
|
+
z: panel.placement.z,
|
|
51
|
+
visible: true,
|
|
52
|
+
collapsed: panel.placement.collapsed === true,
|
|
53
|
+
},
|
|
54
|
+
]);
|
|
55
|
+
}
|
|
56
|
+
/** The fractions of the container the page and each zone take. */
|
|
57
|
+
function frame(w) {
|
|
58
|
+
const left = extent(w, Zone.Left);
|
|
59
|
+
const right = extent(w, Zone.Right);
|
|
60
|
+
const bottom = extent(w, Zone.Bottom);
|
|
61
|
+
const middle = Math.max(0, 1 - left - right);
|
|
62
|
+
return { left, right, bottom, middle, top: Math.max(0, 1 - bottom) };
|
|
63
|
+
}
|
|
64
|
+
export function layout(w) {
|
|
65
|
+
const f = frame(w);
|
|
66
|
+
const slots = [
|
|
67
|
+
...(w.page === null
|
|
68
|
+
? []
|
|
69
|
+
: [
|
|
70
|
+
{
|
|
71
|
+
id: PAGE,
|
|
72
|
+
view: w.page,
|
|
73
|
+
panel: null,
|
|
74
|
+
box: fraction(f.left, 0, f.middle, f.top),
|
|
75
|
+
floating: false,
|
|
76
|
+
z: 0,
|
|
77
|
+
visible: true,
|
|
78
|
+
collapsed: false,
|
|
79
|
+
},
|
|
80
|
+
]),
|
|
81
|
+
...split(panelsIn(w, Zone.Left), Split.Vertical, {
|
|
82
|
+
left: 0,
|
|
83
|
+
top: 0,
|
|
84
|
+
width: f.left,
|
|
85
|
+
height: 1,
|
|
86
|
+
}),
|
|
87
|
+
...split(panelsIn(w, Zone.Right), Split.Vertical, {
|
|
88
|
+
left: f.left + f.middle,
|
|
89
|
+
top: 0,
|
|
90
|
+
width: f.right,
|
|
91
|
+
height: 1,
|
|
92
|
+
}),
|
|
93
|
+
...split(panelsIn(w, Zone.Bottom), Split.Horizontal, {
|
|
94
|
+
left: f.left,
|
|
95
|
+
top: f.top,
|
|
96
|
+
width: f.middle,
|
|
97
|
+
height: f.bottom,
|
|
98
|
+
}),
|
|
99
|
+
...windows(w.panels),
|
|
100
|
+
];
|
|
101
|
+
if (w.maximized === null || !slots.some((s) => s.id === w.maximized))
|
|
102
|
+
return slots;
|
|
103
|
+
return slots.map((slot) => slot.id === w.maximized
|
|
104
|
+
? { ...slot, box: FULL, floating: false, visible: true, collapsed: false }
|
|
105
|
+
: { ...slot, visible: false });
|
|
106
|
+
}
|
|
107
|
+
/** Sorted by id so sibling order does not change when a panel changes zone — reordering
|
|
108
|
+
* siblings is what unmounts. */
|
|
109
|
+
export function stableOrder(slots) {
|
|
110
|
+
return [...slots].sort((a, b) => a.id.localeCompare(b.id));
|
|
111
|
+
}
|
|
112
|
+
export function sizeAt(handle, p) {
|
|
113
|
+
const raw = handle.invert ? handle.origin - p : p - handle.origin;
|
|
114
|
+
return raw / handle.span;
|
|
115
|
+
}
|
|
116
|
+
export function handles(w) {
|
|
117
|
+
if (w.maximized !== null)
|
|
118
|
+
return [];
|
|
119
|
+
const f = frame(w);
|
|
120
|
+
const result = [];
|
|
121
|
+
const left = panelsIn(w, Zone.Left);
|
|
122
|
+
const right = panelsIn(w, Zone.Right);
|
|
123
|
+
const bottom = panelsIn(w, Zone.Bottom);
|
|
124
|
+
if (left.length > 0)
|
|
125
|
+
result.push({
|
|
126
|
+
kind: HandleKind.Zone,
|
|
127
|
+
zone: Zone.Left,
|
|
128
|
+
axis: Axis.X,
|
|
129
|
+
at: f.left,
|
|
130
|
+
origin: 0,
|
|
131
|
+
span: 1,
|
|
132
|
+
invert: false,
|
|
133
|
+
});
|
|
134
|
+
if (right.length > 0)
|
|
135
|
+
result.push({
|
|
136
|
+
kind: HandleKind.Zone,
|
|
137
|
+
zone: Zone.Right,
|
|
138
|
+
axis: Axis.X,
|
|
139
|
+
at: f.left + f.middle,
|
|
140
|
+
origin: 1,
|
|
141
|
+
span: 1,
|
|
142
|
+
invert: true,
|
|
143
|
+
});
|
|
144
|
+
if (bottom.length > 0)
|
|
145
|
+
result.push({
|
|
146
|
+
kind: HandleKind.Zone,
|
|
147
|
+
zone: Zone.Bottom,
|
|
148
|
+
axis: Axis.Y,
|
|
149
|
+
at: f.top,
|
|
150
|
+
origin: 1,
|
|
151
|
+
span: 1,
|
|
152
|
+
invert: true,
|
|
153
|
+
});
|
|
154
|
+
const between = (panels, axis, origin, span) => {
|
|
155
|
+
let cursor = 0;
|
|
156
|
+
panels.forEach((panel, i) => {
|
|
157
|
+
const share = panel.placement.zone === Zone.Floating ? 0 : panel.placement.share;
|
|
158
|
+
cursor += share;
|
|
159
|
+
if (i < panels.length - 1) {
|
|
160
|
+
result.push({
|
|
161
|
+
kind: HandleKind.Panel,
|
|
162
|
+
panelId: panel.id,
|
|
163
|
+
axis,
|
|
164
|
+
at: origin + span * cursor,
|
|
165
|
+
origin: origin + span * (cursor - share),
|
|
166
|
+
span,
|
|
167
|
+
invert: false,
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
});
|
|
171
|
+
};
|
|
172
|
+
between(left, Axis.Y, 0, 1);
|
|
173
|
+
between(right, Axis.Y, 0, 1);
|
|
174
|
+
between(bottom, Axis.X, f.left, f.middle);
|
|
175
|
+
return result;
|
|
176
|
+
}
|
|
177
|
+
/** How far an arrow key moves a handle. A mouse-only handle leaves the workspace
|
|
178
|
+
* half-assembled for anyone who does not use a pointer. */
|
|
179
|
+
export const KEYBOARD_STEP = 0.02;
|
|
180
|
+
export const ZONE_LIMITS = { min: MIN_ZONE, max: MAX_ZONE };
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { Action, Registry, ViewSpec } from "./registry.js";
|
|
2
|
+
import { type ResourceRef } from "./resource.js";
|
|
3
|
+
/**
|
|
4
|
+
* ⌘K in three layers: GO TO a screen, DO something with what I am on, and
|
|
5
|
+
* what each domain FOUND for the query. Pure on purpose — what the palette
|
|
6
|
+
* offers and how a query matches are tested without drawing it.
|
|
7
|
+
*/
|
|
8
|
+
export declare const PaletteSection: {
|
|
9
|
+
readonly Goto: "goto";
|
|
10
|
+
readonly Actions: "actions";
|
|
11
|
+
readonly Found: "found";
|
|
12
|
+
};
|
|
13
|
+
export type PaletteSection = (typeof PaletteSection)[keyof typeof PaletteSection];
|
|
14
|
+
type Icon = ViewSpec["icon"];
|
|
15
|
+
export type PaletteEntry = {
|
|
16
|
+
section: typeof PaletteSection.Goto | typeof PaletteSection.Found;
|
|
17
|
+
id: string;
|
|
18
|
+
label: string;
|
|
19
|
+
detail?: string;
|
|
20
|
+
icon?: Icon;
|
|
21
|
+
ref: ResourceRef;
|
|
22
|
+
} | {
|
|
23
|
+
section: typeof PaletteSection.Actions;
|
|
24
|
+
id: string;
|
|
25
|
+
label: string;
|
|
26
|
+
icon?: Icon;
|
|
27
|
+
shortcut?: string;
|
|
28
|
+
keywords?: readonly string[];
|
|
29
|
+
action: Action;
|
|
30
|
+
};
|
|
31
|
+
/** Shorter than this, every domain answers with half its table. */
|
|
32
|
+
export declare const MIN_QUERY = 2;
|
|
33
|
+
/** Every word of the query, in any order, ignoring accents and case:
|
|
34
|
+
* «facturacion» finds «Facturación», «nueva fac» finds «Nueva factura». */
|
|
35
|
+
export declare function matches(entry: PaletteEntry, query: string): boolean;
|
|
36
|
+
/** What is known without asking anyone: the screens, and the actions of the
|
|
37
|
+
* resource the user is on. */
|
|
38
|
+
export declare function localEntries(registry: Registry, focused: ResourceRef | null): readonly PaletteEntry[];
|
|
39
|
+
/** Asks every domain that searches. A domain that fails is logged and left
|
|
40
|
+
* out; the others still answer. */
|
|
41
|
+
export declare function searchEntries(registry: Registry, query: string): Promise<readonly PaletteEntry[]>;
|
|
42
|
+
export {};
|