@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
@@ -0,0 +1,145 @@
1
+ import { DOCKS, Zone } from "./enums.js";
2
+ import { formatRef, parseRef, sameRef, } from "./resource.js";
3
+ import { DEFAULT_ZONES, EMPTY, PAGE, PEEK, refOn, } from "./workspace.js";
4
+ /**
5
+ * The URL carries what is worth sending a colleague so they see the same workspace — the page,
6
+ * the panels, the sizes — not the trail, the selection or what was typed.
7
+ *
8
+ * Separators are characters a reference cannot contain, because `formatRef` percent-encodes
9
+ * them: `;` between panels, `!` between a panel's fields, `,` inside a placement. The panel
10
+ * separator cannot be `+`: `URLSearchParams` decodes it as a space.
11
+ */
12
+ const FLAG = {
13
+ [Zone.Left]: "l",
14
+ [Zone.Right]: "r",
15
+ [Zone.Bottom]: "b",
16
+ };
17
+ const ZONE = { l: Zone.Left, r: Zone.Right, b: Zone.Bottom };
18
+ const n2 = (n) => n.toFixed(2);
19
+ function packPlacement(placement) {
20
+ const collapsed = placement.collapsed === true ? ",c" : "";
21
+ if (placement.zone === Zone.Floating) {
22
+ const { x, y, w, h, z } = placement;
23
+ return `f,${Math.round(x)},${Math.round(y)},${Math.round(w)},${Math.round(h)},${z}${collapsed}`;
24
+ }
25
+ return `${FLAG[placement.zone]},${n2(placement.share)}${collapsed}`;
26
+ }
27
+ function unpackPlacement(text) {
28
+ const [flag, ...rest] = text.split(",");
29
+ if (flag === "f") {
30
+ const [x, y, w, h, z] = rest.map(Number);
31
+ if ([x, y, w, h].some((v) => v === undefined || Number.isNaN(v)))
32
+ return null;
33
+ return {
34
+ zone: Zone.Floating,
35
+ x: x,
36
+ y: y,
37
+ w: w,
38
+ h: h,
39
+ z: z === undefined || Number.isNaN(z) ? 1 : z,
40
+ ...(rest.includes("c") ? { collapsed: true } : {}),
41
+ };
42
+ }
43
+ const zone = flag === undefined ? undefined : ZONE[flag];
44
+ const share = Number(rest[0]);
45
+ if (zone === undefined || rest[0] === undefined || Number.isNaN(share))
46
+ return null;
47
+ return rest.includes("c") ? { zone, share, collapsed: true } : { zone, share };
48
+ }
49
+ const packPanels = (panels) => panels.map((p) => `${p.id}!${formatRef(p.view)}!${packPlacement(p.placement)}`).join(";");
50
+ function unpackPanels(text) {
51
+ const panels = [];
52
+ for (const chunk of text.split(";")) {
53
+ const [id, refText, placementText] = chunk.split("!");
54
+ const view = refText === undefined ? null : parseRef(refText);
55
+ const placement = placementText === undefined ? null : unpackPlacement(placementText);
56
+ if (id !== undefined && id !== "" && view !== null && placement !== null)
57
+ panels.push({ id, view, placement });
58
+ }
59
+ return panels;
60
+ }
61
+ const packZones = (zones) => DOCKS.map((z) => n2(zones[z])).join(",");
62
+ function unpackZones(text) {
63
+ const values = text.split(",").map(Number);
64
+ const next = { ...DEFAULT_ZONES };
65
+ DOCKS.forEach((zone, i) => {
66
+ const v = values[i];
67
+ if (v !== undefined && !Number.isNaN(v))
68
+ next[zone] = v;
69
+ });
70
+ return next;
71
+ }
72
+ export function toHash(w) {
73
+ const parts = [];
74
+ if (w.page !== null)
75
+ parts.push(`p=${formatRef(w.page)}`);
76
+ if (w.panels.length > 0)
77
+ parts.push(`s=${packPanels(w.panels)}`);
78
+ parts.push(`z=${packZones(w.zones)}`);
79
+ if (w.peek !== null)
80
+ parts.push(`k=${formatRef(w.peek)}`);
81
+ if (w.focus !== PAGE)
82
+ parts.push(`f=${w.focus}`);
83
+ if (w.maximized !== null)
84
+ parts.push(`m=${w.maximized}`);
85
+ return `#/w?${parts.join("&")}`;
86
+ }
87
+ export function fromHash(hash) {
88
+ if (!hash.startsWith("#/w"))
89
+ return EMPTY;
90
+ const query = new URLSearchParams(hash.slice(hash.indexOf("?") + 1));
91
+ const page = query.get("p");
92
+ const peek = query.get("k");
93
+ const panels = unpackPanels(query.get("s") ?? "");
94
+ const focus = query.get("f");
95
+ const maximized = query.get("m");
96
+ const zones = query.get("z");
97
+ const has = (id) => id !== null && panels.some((p) => p.id === id);
98
+ const pageRef = page === null ? null : parseRef(page);
99
+ /* A drawer needs a page to sit over: without one it is dropped, like any broken part. */
100
+ const peekRef = peek === null || pageRef === null ? null : parseRef(peek);
101
+ return {
102
+ ...EMPTY,
103
+ page: pageRef,
104
+ panels,
105
+ zones: zones === null ? DEFAULT_ZONES : unpackZones(zones),
106
+ peek: peekRef,
107
+ focus: has(focus) || (focus === PEEK && peekRef !== null) ? focus : PAGE,
108
+ maximized: maximized === PAGE || has(maximized) ? maximized : null,
109
+ };
110
+ }
111
+ /** A page reached without memory — a link typed or clicked: one already in the trail goes back
112
+ * to it; any other is one step forward. */
113
+ function trailTo(now, page) {
114
+ if (page === null)
115
+ return [];
116
+ if (now.page !== null && sameRef(now.page, page))
117
+ return now.trail;
118
+ const index = now.trail.findIndex((past) => sameRef(past, page));
119
+ if (index >= 0)
120
+ return now.trail.slice(0, index);
121
+ return now.page === null ? [] : [...now.trail, now.page];
122
+ }
123
+ /**
124
+ * The browser moved through its history: the URL says WHERE, the session says how I got there.
125
+ * With the entry's own memory the trails are exact; without it they are reconciled. The
126
+ * selection survives only while its surface still shows the same resource, and the names views
127
+ * gave stay.
128
+ */
129
+ export function restore(now, url, memory) {
130
+ const peekTrail = url.peek === null
131
+ ? []
132
+ : (memory?.peekTrail ??
133
+ (now.peek !== null && sameRef(now.peek, url.peek) ? now.peekTrail : []));
134
+ const by = now.selected?.by;
135
+ const before = by === undefined ? null : refOn(now, by);
136
+ const after = by === undefined ? null : refOn(url, by);
137
+ const keeps = before !== null && after !== null && sameRef(before, after);
138
+ return {
139
+ ...url,
140
+ trail: url.page === null ? [] : (memory?.trail ?? trailTo(now, url.page)),
141
+ peekTrail,
142
+ selected: keeps ? now.selected : null,
143
+ titles: now.titles,
144
+ };
145
+ }
@@ -0,0 +1,174 @@
1
+ import { type Dock, DOCKS, Zone } from "./enums.js";
2
+ import { type ResourceRef } from "./resource.js";
3
+ export { DOCKS, Zone };
4
+ export type { Dock };
5
+ /**
6
+ * One page, and what is open around it.
7
+ *
8
+ * The PAGE is what I am working on — a list, a record — and its `trail` is the way I came, so a
9
+ * breadcrumb can take me back. Around it, any number of PANELS: docked beside it (`Side`) or
10
+ * floating over it (`Window`). A peek is a drawer to read without leaving, with its own trail of
11
+ * what was drilled inside it.
12
+ *
13
+ * The space share lives in TWO places on purpose: `zones` is how much of the container each
14
+ * docked zone takes; `Placement.share` is how much of ITS zone a panel takes. Keeping it all
15
+ * in the panel made the size of the first one mean «the width of the zone» and the size of the
16
+ * rest mean nothing.
17
+ */
18
+ export type Placement = {
19
+ zone: Dock;
20
+ share: number;
21
+ collapsed?: boolean;
22
+ } | {
23
+ zone: typeof Zone.Floating;
24
+ x: number;
25
+ y: number;
26
+ w: number;
27
+ h: number;
28
+ z: number;
29
+ collapsed?: boolean;
30
+ };
31
+ export type Panel = {
32
+ id: string;
33
+ view: ResourceRef;
34
+ placement: Placement;
35
+ };
36
+ /** How much of the container each docked zone takes. */
37
+ export type Zones = Record<Dock, number>;
38
+ /** What a selection belongs to, and the references selected. */
39
+ export type Selected = {
40
+ by: string;
41
+ refs: readonly ResourceRef[];
42
+ };
43
+ export type Workspace = {
44
+ page: ResourceRef | null;
45
+ /** The pages I came through to reach `page`, oldest first. Session memory. */
46
+ trail: readonly ResourceRef[];
47
+ panels: readonly Panel[];
48
+ zones: Zones;
49
+ peek: ResourceRef | null;
50
+ /** What I drilled through INSIDE the peek to reach `peek`, oldest first. Session memory. */
51
+ peekTrail: readonly ResourceRef[];
52
+ /** `PAGE`, `PEEK` or a panel id: who the shortcuts talk to. Not the browser's focus, which
53
+ * lives inside the view, almost always in a field. */
54
+ focus: string;
55
+ /** A panel id, or `PAGE`. It takes the whole workspace while it lasts. */
56
+ maximized: string | null;
57
+ /** The last selection any surface published. A chat or a detail panel follows THIS, not the
58
+ * focus: clicking into the chat must not make it lose what it was following. */
59
+ selected: Selected | null;
60
+ /** The names views gave their resources once loaded (`api.setTitle`), by `formatRef`. The
61
+ * crumbs and the frames show them instead of the slug. Session memory, not in the URL. */
62
+ titles: Readonly<Record<string, string>>;
63
+ };
64
+ /** The page is not a panel and has no id; it needs one so it can be focused and maximized. */
65
+ export declare const PAGE = "page";
66
+ /** Nor is the peek; it needs one to take the focus and publish a selection. */
67
+ export declare const PEEK = "peek";
68
+ export declare const DEFAULT_ZONES: Zones;
69
+ /** Outside these limits one of the two sides stops being usable. */
70
+ export declare const MIN_ZONE = 0.12;
71
+ export declare const MAX_ZONE = 0.72;
72
+ export declare const MIN_SHARE = 0.12;
73
+ export declare const EMPTY: Workspace;
74
+ export declare const findPanel: (w: Workspace, id: string) => Panel | null;
75
+ /** What a surface shows now — the page, the peek or a panel — or `null` if it is not there. */
76
+ export declare function refOn(w: Workspace, surface: string): ResourceRef | null;
77
+ export declare const panelsIn: (w: Workspace, zone: Zone) => readonly Panel[];
78
+ /**
79
+ * Opens `view` as the page and keeps where I was, so the breadcrumb can take me back. The first
80
+ * page has nothing behind it. When there is nothing to change it returns THE SAME object —
81
+ * every reducer here does, and that is what makes it possible to subscribe to a part of the
82
+ * workspace: if every call returned a new one, any action would redraw everything.
83
+ */
84
+ export declare function push(w: Workspace, view: ResourceRef): Workspace;
85
+ /** Puts `view` where the page is WITHOUT a crumb: a filter that changed, or the record a form
86
+ * just created — the form should not stay in the way back. */
87
+ export declare function replace(w: Workspace, view: ResourceRef): Workspace;
88
+ /** Starting over, from a menu: `view` is the page and the way back starts with it. The panels
89
+ * stay — they are how the person arranged the desk, not where they were. */
90
+ export declare function start(w: Workspace, view: ResourceRef): Workspace;
91
+ /** Back to the page at `index` of the trail; the pages after it are dropped. A crumb is this. */
92
+ export declare function goTo(w: Workspace, index: number): Workspace;
93
+ /** One page back. Nothing to go back to is not an error: it changes nothing. */
94
+ export declare const back: (w: Workspace) => Workspace;
95
+ export type OpenPanelOptions = {
96
+ zone?: Zone;
97
+ /** Deduplicating is the right default for a column and the wrong one for «the same table
98
+ * with two filters». */
99
+ allowDuplicate?: boolean;
100
+ };
101
+ /** Opens a resource as a panel. If it is already open it moves it to the requested zone and
102
+ * focuses it, unless a duplicate is explicitly asked for. */
103
+ export declare function openPanel(w: Workspace, view: ResourceRef, options?: Zone | OpenPanelOptions): Workspace;
104
+ export declare function movePanel(w: Workspace, id: string, zone: Zone): Workspace;
105
+ /** Closing the maximized or the focused one has to give the rest back, or the workspace ends
106
+ * up empty with panels inside it. */
107
+ export declare function closePanel(w: Workspace, id: string): Workspace;
108
+ /** Changes what a panel looks at without moving or closing it. */
109
+ export declare function navigatePanel(w: Workspace, id: string, view: ResourceRef): Workspace;
110
+ /** How much of the container a docked zone takes. */
111
+ export declare function resizeZone(w: Workspace, zone: Dock, size: number): Workspace;
112
+ /**
113
+ * How much of ITS zone a panel takes. What it gains it takes from the neighbour below, like
114
+ * any divider between two panels: moving a handle has to affect both sides and nobody else.
115
+ */
116
+ export declare function resizePanel(w: Workspace, id: string, share: number): Workspace;
117
+ export type WindowBox = Partial<{
118
+ x: number;
119
+ y: number;
120
+ w: number;
121
+ h: number;
122
+ }>;
123
+ /** Moves or resizes a window. */
124
+ export declare function floatPanel(w: Workspace, id: string, box: WindowBox): Workspace;
125
+ /** Bring to front. Without this, two overlapping windows cannot be pulled apart. */
126
+ export declare function raisePanel(w: Workspace, id: string): Workspace;
127
+ /** Collapse to its header without closing it: still there, still mounted, taking no room. */
128
+ export declare function collapsePanel(w: Workspace, id: string): Workspace;
129
+ /** Take the whole workspace. Calling it on what is already maximized gives it back. The peek is
130
+ * a drawer: it grows into the page instead (`peekToPage`). */
131
+ export declare function maximize(w: Workspace, target: string | null): Workspace;
132
+ /** The WORKSPACE focus, which is who the shortcuts talk to. Opening a panel focuses it. */
133
+ export declare function focusPanel(w: Workspace, target: string): Workspace;
134
+ /** The next one in reading order: the page, the peek over it, then each panel. */
135
+ export declare function cycleFocus(w: Workspace, delta: number): Workspace;
136
+ /**
137
+ * A panel grows into the page: its resource becomes the page, with the previous page in the
138
+ * breadcrumb, and the panel is gone. «Enlarge» that keeps where you came from.
139
+ */
140
+ export declare function expandPanel(w: Workspace, id: string): Workspace;
141
+ /**
142
+ * Opened from outside — a row, ⌘K — the drawer starts fresh: its trail is only of what was
143
+ * drilled INSIDE it. It takes the focus, so ⌘K acts on what I am reading. Without a page there
144
+ * is nothing to read beside, so it becomes the page.
145
+ */
146
+ export declare function peek(w: Workspace, view: ResourceRef): Workspace;
147
+ /** From inside the drawer: what it shows now goes to its trail, so ← comes back to it. */
148
+ export declare function drillPeek(w: Workspace, view: ResourceRef): Workspace;
149
+ /** Another face, or the record a form in the drawer just created: no step in its trail. */
150
+ export declare function replacePeek(w: Workspace, view: ResourceRef): Workspace;
151
+ /** Back to the step at `index` of the drawer's trail. */
152
+ export declare function peekGoTo(w: Workspace, index: number): Workspace;
153
+ export declare const peekBack: (w: Workspace) => Workspace;
154
+ export declare function closePeek(w: Workspace): Workspace;
155
+ /** The peek becomes the page. */
156
+ export declare function peekToPage(w: Workspace): Workspace;
157
+ /** It docks to the right because the drawer was already there and the piece does not move. */
158
+ export declare function peekToSide(w: Workspace, zone?: Zone): Workspace;
159
+ /**
160
+ * What a surface has selected — the rows of a list. The workspace keeps only references, so a
161
+ * chat in another domain can read them without knowing what they are. Selecting nothing clears
162
+ * it only if that surface owned it.
163
+ */
164
+ export declare function select(w: Workspace, by: string, refs: readonly ResourceRef[]): Workspace;
165
+ /** What the user is working on: the page, the peek or the panel that has the focus. */
166
+ export declare function focusedRef(w: Workspace): ResourceRef | null;
167
+ /**
168
+ * The name a view gives its resource once it has loaded it — «Acme S.R.L.» instead of
169
+ * `acme`. `null` gives the `ViewSpec` title back. Names of what is no longer reachable are
170
+ * forgotten on the way, so the map does not grow with the session.
171
+ */
172
+ export declare function nameRef(w: Workspace, ref: ResourceRef, title: string | null): Workspace;
173
+ export declare const nameOf: (w: Workspace, ref: ResourceRef) => string | null;
174
+ export declare const selectionOf: (w: Workspace) => readonly ResourceRef[];