@sincpro/web-composer 0.1.0 → 1.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.
Files changed (41) hide show
  1. package/README.md +139 -67
  2. package/dist/domain/enums.d.ts +0 -10
  3. package/dist/domain/enums.js +0 -8
  4. package/dist/domain/index.d.ts +4 -4
  5. package/dist/domain/index.js +4 -4
  6. package/dist/domain/layout.d.ts +37 -20
  7. package/dist/domain/layout.js +136 -100
  8. package/dist/domain/registry.d.ts +33 -7
  9. package/dist/domain/url.d.ts +13 -0
  10. package/dist/domain/url.js +43 -5
  11. package/dist/domain/workspace.d.ts +43 -7
  12. package/dist/domain/workspace.js +136 -15
  13. package/dist/index.d.ts +9 -5
  14. package/dist/index.js +8 -4
  15. package/dist/shell/Composer.d.ts +5 -6
  16. package/dist/shell/Composer.js +42 -13
  17. package/dist/shell/Palette.js +11 -10
  18. package/dist/shell/PanelFrame.d.ts +10 -3
  19. package/dist/shell/PanelFrame.js +57 -31
  20. package/dist/shell/PanelHost.js +44 -31
  21. package/dist/shell/Peek.d.ts +26 -0
  22. package/dist/shell/Peek.js +64 -0
  23. package/dist/shell/RecordLink.js +12 -8
  24. package/dist/shell/ViewHost.js +17 -6
  25. package/dist/shell/copy.d.ts +10 -1
  26. package/dist/shell/copy.js +29 -7
  27. package/dist/shell/icons.d.ts +22 -0
  28. package/dist/shell/icons.js +19 -0
  29. package/dist/shell/skin.d.ts +72 -0
  30. package/dist/shell/skin.js +35 -0
  31. package/dist/shell/styles.d.ts +19 -0
  32. package/dist/shell/styles.js +212 -0
  33. package/dist/state/api.d.ts +7 -3
  34. package/dist/state/api.js +109 -63
  35. package/dist/state/store.d.ts +27 -3
  36. package/dist/state/store.js +165 -41
  37. package/dist/state/useKeyboard.d.ts +4 -0
  38. package/dist/state/useKeyboard.js +11 -3
  39. package/dist/state/useWorkspace.d.ts +5 -1
  40. package/dist/state/useWorkspace.js +6 -0
  41. package/package.json +11 -10
@@ -1,35 +1,87 @@
1
- import { Axis, BoxUnit, HandleKind, Split, Zone, } from "./enums.js";
1
+ import { Axis, HandleKind, Zone } from "./enums.js";
2
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
- };
3
+ const len = (fr, px = 0) => ({ fr, px });
4
+ const plus = (a, b) => len(a.fr + b.fr, a.px + b.px);
5
+ const times = (a, k) => len(a.fr * k, a.px * k);
6
+ /** A length measured on a container `size` pixels long. */
7
+ export const resolve = (l, size) => l.fr * size + l.px;
8
+ const ZERO = len(0);
9
+ const FULL = { left: ZERO, top: ZERO, width: len(1), height: len(1) };
10
+ /** What a minimized panel keeps: its title bar. It matches the frame's header. */
11
+ export const STRIP = 36;
12
+ const isCollapsed = (p) => p.placement.collapsed === true;
13
+ const shareOf = (p) => (p.placement.zone === Zone.Floating ? 0 : p.placement.share);
14
+ const allCollapsed = (panels) => panels.length > 0 && panels.every(isCollapsed);
15
+ /** A zone with every panel minimized shrinks to one strip: the page takes the room back. */
16
+ function extent(w, zone) {
17
+ const panels = panelsIn(w, zone);
18
+ if (panels.length === 0)
19
+ return ZERO;
20
+ return allCollapsed(panels) ? len(0, STRIP) : len(w.zones[zone]);
21
+ }
22
+ /** The lengths the page and each zone take of the container. */
23
+ function frame(w) {
24
+ const left = extent(w, Zone.Left);
25
+ const right = extent(w, Zone.Right);
26
+ const bottom = extent(w, Zone.Bottom);
27
+ const middle = len(Math.max(0, 1 - left.fr - right.fr), -(left.px + right.px));
28
+ return { left, right, bottom, middle, top: len(1 - bottom.fr, -bottom.px) };
29
+ }
30
+ /** A zone stacks top to bottom; the bottom one lays its panels side by side. */
31
+ const stacks = (zone) => zone !== Zone.Bottom;
32
+ /**
33
+ * Along the zone, a minimized panel is a fixed strip and the open ones share the rest, each in
34
+ * proportion to its share among the OPEN ones — so restoring one gives back the size it had.
35
+ * `unit` is the length a share of 1 takes, what a handle between two of them measures against.
36
+ */
37
+ function pieces(panels, along) {
38
+ const strips = panels.filter(isCollapsed).length;
39
+ const all = strips === panels.length;
40
+ const open = panels.reduce((sum, p) => (isCollapsed(p) ? sum : sum + shareOf(p)), 0);
41
+ const unit = open <= 0 ? ZERO : times(plus(along, len(0, -strips * STRIP)), 1 / open);
42
+ let cursor = ZERO;
43
+ const list = panels.map((panel) => {
44
+ const size = all
45
+ ? times(along, 1 / panels.length)
46
+ : isCollapsed(panel)
47
+ ? len(0, STRIP)
48
+ : times(unit, shareOf(panel));
49
+ const piece = { panel, start: cursor, size };
50
+ cursor = plus(cursor, size);
51
+ return piece;
32
52
  });
53
+ return { list, unit };
54
+ }
55
+ function zoneSpace(f, zone) {
56
+ if (zone === Zone.Left)
57
+ return { left: ZERO, top: ZERO, width: f.left, height: len(1) };
58
+ if (zone === Zone.Right)
59
+ return { left: plus(f.left, f.middle), top: ZERO, width: f.right, height: len(1) };
60
+ return { left: f.left, top: f.top, width: f.middle, height: f.bottom };
61
+ }
62
+ function docked(w, f, zone) {
63
+ const panels = panelsIn(w, zone);
64
+ const space = zoneSpace(f, zone);
65
+ const vertical = stacks(zone);
66
+ const all = allCollapsed(panels);
67
+ return pieces(panels, vertical ? space.height : space.width).list.map(({ panel, start, size }) => ({
68
+ id: panel.id,
69
+ view: panel.view,
70
+ panel,
71
+ box: vertical
72
+ ? { left: space.left, top: plus(space.top, start), width: space.width, height: size }
73
+ : {
74
+ left: plus(space.left, start),
75
+ top: space.top,
76
+ width: size,
77
+ height: space.height,
78
+ },
79
+ floating: false,
80
+ z: 0,
81
+ visible: true,
82
+ collapsed: isCollapsed(panel),
83
+ rail: isCollapsed(panel) && (vertical ? all : !all),
84
+ }));
33
85
  }
34
86
  function windows(panels) {
35
87
  return panels.flatMap((panel) => panel.placement.zone !== Zone.Floating
@@ -40,27 +92,19 @@ function windows(panels) {
40
92
  view: panel.view,
41
93
  panel,
42
94
  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,
95
+ left: len(0, panel.placement.x),
96
+ top: len(0, panel.placement.y),
97
+ width: len(0, panel.placement.w),
98
+ height: len(0, isCollapsed(panel) ? STRIP : panel.placement.h),
48
99
  },
49
100
  floating: true,
50
101
  z: panel.placement.z,
51
102
  visible: true,
52
- collapsed: panel.placement.collapsed === true,
103
+ collapsed: isCollapsed(panel),
104
+ rail: false,
53
105
  },
54
106
  ]);
55
107
  }
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
108
  export function layout(w) {
65
109
  const f = frame(w);
66
110
  const slots = [
@@ -71,37 +115,23 @@ export function layout(w) {
71
115
  id: PAGE,
72
116
  view: w.page,
73
117
  panel: null,
74
- box: fraction(f.left, 0, f.middle, f.top),
118
+ box: { left: f.left, top: ZERO, width: f.middle, height: f.top },
75
119
  floating: false,
76
120
  z: 0,
77
121
  visible: true,
78
122
  collapsed: false,
123
+ rail: false,
79
124
  },
80
125
  ]),
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
- }),
126
+ ...docked(w, f, Zone.Left),
127
+ ...docked(w, f, Zone.Right),
128
+ ...docked(w, f, Zone.Bottom),
99
129
  ...windows(w.panels),
100
130
  ];
101
131
  if (w.maximized === null || !slots.some((s) => s.id === w.maximized))
102
132
  return slots;
103
133
  return slots.map((slot) => slot.id === w.maximized
104
- ? { ...slot, box: FULL, floating: false, visible: true, collapsed: false }
134
+ ? { ...slot, box: FULL, floating: false, visible: true, collapsed: false, rail: false }
105
135
  : { ...slot, visible: false });
106
136
  }
107
137
  /** Sorted by id so sibling order does not change when a panel changes zone — reordering
@@ -109,69 +139,75 @@ export function layout(w) {
109
139
  export function stableOrder(slots) {
110
140
  return [...slots].sort((a, b) => a.id.localeCompare(b.id));
111
141
  }
112
- export function sizeAt(handle, p) {
113
- const raw = handle.invert ? handle.origin - p : p - handle.origin;
114
- return raw / handle.span;
142
+ /** The stored size a pointer `p` pixels into a container `size` pixels long asks for. */
143
+ export function sizeAt(handle, p, size) {
144
+ const origin = resolve(handle.origin, size);
145
+ const span = resolve(handle.span, size);
146
+ if (span <= 0)
147
+ return 0;
148
+ return (handle.invert ? origin - p : p - origin) / span;
115
149
  }
116
150
  export function handles(w) {
117
151
  if (w.maximized !== null)
118
152
  return [];
119
153
  const f = frame(w);
120
154
  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)
155
+ const resizable = (zone) => {
156
+ const panels = panelsIn(w, zone);
157
+ return panels.length > 0 && !allCollapsed(panels);
158
+ };
159
+ if (resizable(Zone.Left))
125
160
  result.push({
126
161
  kind: HandleKind.Zone,
127
162
  zone: Zone.Left,
128
163
  axis: Axis.X,
129
164
  at: f.left,
130
- origin: 0,
131
- span: 1,
165
+ origin: ZERO,
166
+ span: len(1),
132
167
  invert: false,
133
168
  });
134
- if (right.length > 0)
169
+ if (resizable(Zone.Right))
135
170
  result.push({
136
171
  kind: HandleKind.Zone,
137
172
  zone: Zone.Right,
138
173
  axis: Axis.X,
139
- at: f.left + f.middle,
140
- origin: 1,
141
- span: 1,
174
+ at: plus(f.left, f.middle),
175
+ origin: len(1),
176
+ span: len(1),
142
177
  invert: true,
143
178
  });
144
- if (bottom.length > 0)
179
+ if (resizable(Zone.Bottom))
145
180
  result.push({
146
181
  kind: HandleKind.Zone,
147
182
  zone: Zone.Bottom,
148
183
  axis: Axis.Y,
149
184
  at: f.top,
150
- origin: 1,
151
- span: 1,
185
+ origin: len(1),
186
+ span: len(1),
152
187
  invert: true,
153
188
  });
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
- }
189
+ for (const zone of [Zone.Left, Zone.Right, Zone.Bottom]) {
190
+ if (!resizable(zone))
191
+ continue;
192
+ const space = zoneSpace(f, zone);
193
+ const vertical = stacks(zone);
194
+ const base = vertical ? space.top : space.left;
195
+ const { list, unit } = pieces(panelsIn(w, zone), vertical ? space.height : space.width);
196
+ list.forEach((piece, i) => {
197
+ const next = list[i + 1];
198
+ if (next === undefined || isCollapsed(piece.panel) || isCollapsed(next.panel))
199
+ return;
200
+ result.push({
201
+ kind: HandleKind.Panel,
202
+ panelId: piece.panel.id,
203
+ axis: vertical ? Axis.Y : Axis.X,
204
+ at: plus(base, next.start),
205
+ origin: plus(base, piece.start),
206
+ span: unit,
207
+ invert: false,
208
+ });
170
209
  });
171
- };
172
- between(left, Axis.Y, 0, 1);
173
- between(right, Axis.Y, 0, 1);
174
- between(bottom, Axis.X, f.left, f.middle);
210
+ }
175
211
  return result;
176
212
  }
177
213
  /** How far an arrow key moves a handle. A mouse-only handle leaves the workspace
@@ -26,22 +26,48 @@ export type Crumb = {
26
26
  export type WorkspaceApi = {
27
27
  self: ResourceRef;
28
28
  surface: Surface;
29
- /** The one way to open a resource: `open(ref)` goes to the page, `open(ref, { to })` where
30
- * the caller says. From a peek or a window, opening the page leaves it where it is. */
29
+ /**
30
+ * The one way to open a resource: `open(ref)` goes where the workspace opens by default (the
31
+ * page), `open(ref, { to })` where the caller says. Opening the page from a window leaves the
32
+ * window where it is; from the peek it closes the drawer — it sat over a page that is no longer
33
+ * there. Inside the peek a plain `open(ref)` drills IN the drawer, and ← comes back: reading
34
+ * does not throw the reader out.
35
+ */
31
36
  open: (ref: ResourceRef, options?: OpenOptions) => void;
32
- /** Change what THIS surface shows, without opening anything. */
37
+ /** Show `ref` HERE, remembering where it was: a crumb on the page, a step back in the peek. A
38
+ * panel has no way back: it just changes. */
33
39
  navigate: (ref: ResourceRef) => void;
34
- /** One page back in the breadcrumb. */
40
+ /** Show `ref` HERE without a step to come back to: the record a form just created, a filter. */
41
+ replace: (ref: ResourceRef) => void;
42
+ /** This resource with `params` merged (`""` removes one), in place: filters live in the
43
+ * reference — they survive a reload, a link and a move to another surface. */
44
+ setParams: (params: Record<string, string>) => void;
45
+ /** One step back: the page's breadcrumb or the peek's own trail. Nothing in a panel. */
35
46
  back: () => void;
36
47
  /** A window, a side panel or the peek grows into the page. Nothing on the page itself. */
37
48
  expand: () => void;
38
- /** Close the container: its panel or the peek drawer. */
49
+ /** Leave what this view is in: its panel or the peek closes; the page goes one step back.
50
+ * «Cancel» on a form is this one call wherever the form was opened. */
39
51
  close: () => void;
40
52
  /** Request workspace focus so shortcuts talk to this view. */
41
53
  focus: () => void;
42
- /** The way here, ready to draw: the pages before this one, each a link, and this one. Empty
43
- * outside the page: a panel's frame already says what it shows. */
54
+ /**
55
+ * The way here, ready for `List.Crumbs` / `Record.Crumbs`: the pages before, each a link, and
56
+ * this one. In the peek the page's crumbs leave the drawer and its own steps stay in it. Empty
57
+ * in a panel: its frame already says what it shows.
58
+ *
59
+ * What it is NOW, and the same array until it changes. A view draws it with `useCrumbs(api)`,
60
+ * which follows it: read during render, a name given later (`setTitle`) would not show.
61
+ */
44
62
  crumbs: () => readonly Crumb[];
63
+ /** The name this resource goes by once loaded — the crumbs, the frame and the peek show it
64
+ * instead of the `ViewSpec` title. `null` gives the title back. Ignored once this surface
65
+ * shows something else, so a late answer cannot rename the wrong record. */
66
+ setTitle: (title: string | null) => void;
67
+ /** Something typed here would be lost. While it is, anything that would throw this view away
68
+ * — a crumb, a close, a reset, the browser's back or a reload — asks first. Set it back to
69
+ * `false` after saving, BEFORE leaving. */
70
+ setDirty: (dirty: boolean) => void;
45
71
  /** Publish what THIS surface has selected, so a detail panel or an assistant can follow it.
46
72
  * An empty list clears it. */
47
73
  select: (refs: readonly ResourceRef[]) => void;
@@ -1,3 +1,16 @@
1
+ import { type ResourceRef } from "./resource.js";
1
2
  import { type Workspace } from "./workspace.js";
2
3
  export declare function toHash(w: Workspace): string;
3
4
  export declare function fromHash(hash: string): Workspace;
5
+ /** What the URL does not carry, written into each browser history entry. */
6
+ export type SessionMemory = {
7
+ trail: readonly ResourceRef[];
8
+ peekTrail: readonly ResourceRef[];
9
+ };
10
+ /**
11
+ * The browser moved through its history: the URL says WHERE, the session says how I got there.
12
+ * With the entry's own memory the trails are exact; without it they are reconciled. The
13
+ * selection survives only while its surface still shows the same resource, and the names views
14
+ * gave stay.
15
+ */
16
+ export declare function restore(now: Workspace, url: Workspace, memory: SessionMemory | null): Workspace;
@@ -1,6 +1,6 @@
1
1
  import { DOCKS, Zone } from "./enums.js";
2
- import { formatRef, parseRef } from "./resource.js";
3
- import { DEFAULT_ZONES, EMPTY, PAGE, } from "./workspace.js";
2
+ import { formatRef, parseRef, sameRef, } from "./resource.js";
3
+ import { DEFAULT_ZONES, EMPTY, PAGE, PEEK, refOn, } from "./workspace.js";
4
4
  /**
5
5
  * The URL carries what is worth sending a colleague so they see the same workspace — the page,
6
6
  * the panels, the sizes — not the trail, the selection or what was typed.
@@ -95,13 +95,51 @@ export function fromHash(hash) {
95
95
  const maximized = query.get("m");
96
96
  const zones = query.get("z");
97
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);
98
101
  return {
99
102
  ...EMPTY,
100
- page: page === null ? null : parseRef(page),
103
+ page: pageRef,
101
104
  panels,
102
105
  zones: zones === null ? DEFAULT_ZONES : unpackZones(zones),
103
- peek: peek === null ? null : parseRef(peek),
104
- focus: has(focus) ? focus : PAGE,
106
+ peek: peekRef,
107
+ focus: has(focus) || (focus === PEEK && peekRef !== null) ? focus : PAGE,
105
108
  maximized: maximized === PAGE || has(maximized) ? maximized : null,
106
109
  };
107
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
+ }
@@ -7,7 +7,8 @@ export type { Dock };
7
7
  *
8
8
  * The PAGE is what I am working on — a list, a record — and its `trail` is the way I came, so a
9
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.
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.
11
12
  *
12
13
  * The space share lives in TWO places on purpose: `zones` is how much of the container each
13
14
  * docked zone takes; `Placement.share` is how much of ITS zone a panel takes. Keeping it all
@@ -46,17 +47,24 @@ export type Workspace = {
46
47
  panels: readonly Panel[];
47
48
  zones: Zones;
48
49
  peek: ResourceRef | null;
49
- /** `PAGE` or a panel id: who the shortcuts talk to. Not the browser's focus, which lives
50
- * inside the view, almost always in a field. */
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. */
51
54
  focus: string;
52
55
  /** A panel id, or `PAGE`. It takes the whole workspace while it lasts. */
53
56
  maximized: string | null;
54
57
  /** The last selection any surface published. A chat or a detail panel follows THIS, not the
55
58
  * focus: clicking into the chat must not make it lose what it was following. */
56
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>>;
57
63
  };
58
64
  /** The page is not a panel and has no id; it needs one so it can be focused and maximized. */
59
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";
60
68
  export declare const DEFAULT_ZONES: Zones;
61
69
  /** Outside these limits one of the two sides stops being usable. */
62
70
  export declare const MIN_ZONE = 0.12;
@@ -64,6 +72,8 @@ export declare const MAX_ZONE = 0.72;
64
72
  export declare const MIN_SHARE = 0.12;
65
73
  export declare const EMPTY: Workspace;
66
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;
67
77
  export declare const panelsIn: (w: Workspace, zone: Zone) => readonly Panel[];
68
78
  /**
69
79
  * Opens `view` as the page and keeps where I was, so the breadcrumb can take me back. The first
@@ -72,6 +82,12 @@ export declare const panelsIn: (w: Workspace, zone: Zone) => readonly Panel[];
72
82
  * workspace: if every call returned a new one, any action would redraw everything.
73
83
  */
74
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;
75
91
  /** Back to the page at `index` of the trail; the pages after it are dropped. A crumb is this. */
76
92
  export declare function goTo(w: Workspace, index: number): Workspace;
77
93
  /** One page back. Nothing to go back to is not an error: it changes nothing. */
@@ -110,19 +126,32 @@ export declare function floatPanel(w: Workspace, id: string, box: WindowBox): Wo
110
126
  export declare function raisePanel(w: Workspace, id: string): Workspace;
111
127
  /** Collapse to its header without closing it: still there, still mounted, taking no room. */
112
128
  export declare function collapsePanel(w: Workspace, id: string): Workspace;
113
- /** Take the whole workspace. Calling it on what is already maximized gives it back. */
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`). */
114
131
  export declare function maximize(w: Workspace, target: string | null): Workspace;
115
132
  /** The WORKSPACE focus, which is who the shortcuts talk to. Opening a panel focuses it. */
116
133
  export declare function focusPanel(w: Workspace, target: string): Workspace;
117
- /** The next one in reading order: the page, then each panel. */
134
+ /** The next one in reading order: the page, the peek over it, then each panel. */
118
135
  export declare function cycleFocus(w: Workspace, delta: number): Workspace;
119
136
  /**
120
137
  * A panel grows into the page: its resource becomes the page, with the previous page in the
121
138
  * breadcrumb, and the panel is gone. «Enlarge» that keeps where you came from.
122
139
  */
123
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
+ */
124
146
  export declare function peek(w: Workspace, view: ResourceRef): Workspace;
125
- export declare const closePeek: (w: Workspace) => 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;
126
155
  /** The peek becomes the page. */
127
156
  export declare function peekToPage(w: Workspace): Workspace;
128
157
  /** It docks to the right because the drawer was already there and the piece does not move. */
@@ -133,6 +162,13 @@ export declare function peekToSide(w: Workspace, zone?: Zone): Workspace;
133
162
  * it only if that surface owned it.
134
163
  */
135
164
  export declare function select(w: Workspace, by: string, refs: readonly ResourceRef[]): Workspace;
136
- /** What the user is working on: the page, or the panel that has the focus. */
165
+ /** What the user is working on: the page, the peek or the panel that has the focus. */
137
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;
138
174
  export declare const selectionOf: (w: Workspace) => readonly ResourceRef[];