@sincpro/web-composer 1.1.0 → 1.3.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/README.md CHANGED
@@ -85,25 +85,46 @@ One **page**, with its **trail** (the breadcrumb), and around it:
85
85
  | **peek** | A drawer over the page that does not cover the panels | Reading without leaving the place |
86
86
  | **window** | Floating: moves anywhere, resizes, can grow into the page | A quick look or edit on top of what you do |
87
87
  | **side** | Docked left, right or at the bottom, resizable | A second context that stays: compare, follow |
88
+ | **modal** | Over the surface that asked, blocking only it; moves by its title | A question, a chooser, a short form |
88
89
 
89
90
  A view opens anything with one call and lets the workspace decide the rest:
90
91
 
91
92
  ```ts
92
93
  api.open(ref); // the page — inside the peek, a step IN the drawer
93
94
  api.open(ref, { to: "peek" }); // or "window", or "side"
95
+ api.open(ref, { to: "modal" }); // over THIS surface only; { blur: true } blurs what it covers
96
+ api.open(ref, { to: "window", size: { w: 720, h: 520 } }); // a window or a modal at that size
97
+ api.over; // in a modal: the record it was opened over — its context (null elsewhere)
94
98
  api.replace(ref); // show it HERE without a step back: the record a form just created
95
99
  api.setParams({ tenant }); // a filter that lives in the reference: survives reload and links
96
100
  useCrumbs(api); // the breadcrumb, ready for List.Crumbs / Record.Crumbs — follows setTitle
97
101
  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
102
+ api.close(); // leave: closes the panel, the peek or the modal; on the page, goes back
99
103
  api.expand(); // a window, a side panel or the peek grows into the page
100
104
  api.setTitle(name); // the record's real name, for the crumbs and the frames, once loaded
101
105
  api.setDirty(true); // unsaved: a crumb, a close or the browser's Back ask first
102
106
  api.select(refs); // publish what this view has selected
103
107
  api.context; // read what the user is on and what is selected — references only
104
108
  api.pick(ref, onPick); // open a chooser (a many2one search); its view calls api.answer(ref)
109
+ api.pick(ref, onPick, { to: "modal" }); // the chooser as a modal over the form
110
+ api.pick(ref, onPick, { size: { w: 720, h: 520 } }); // a chooser window at that size (480×360 without it)
105
111
  ```
106
112
 
113
+ A **modal** belongs to the surface it covers — the page, a window, a side panel or the peek —
114
+ and blocks only that one: the rest of the workspace keeps answering, and a window keeps moving
115
+ and closing by its own title bar. One per surface: opening another one over the same surface,
116
+ or from inside it, replaces it. When its surface shows another record or closes, the modal goes
117
+ with it (asking first if something was typed). What it shares with whoever opened it travels in
118
+ its reference (`params`) and comes back with `api.answer`; `api.over` says what it covers. No
119
+ blur unless asked.
120
+
121
+ **On a phone** — when the workspace is narrower than 640 px (`<Composer phoneBelow>`, `0` never)
122
+ — it is one screen, and the views change nothing: the page takes it all; a window or a side
123
+ panel opens as the page, with its crumb to come back; a chooser opens as a sheet from the bottom,
124
+ so the form that asked stays to receive the answer; the peek is the screen's width. Panels that
125
+ were already open wait in «Also open», mounted, and one tap brings each to the page. Widen it and
126
+ the desk is back as it was.
127
+
107
128
  From the app, around the workspace: `workspace.start(ref)` starts over from a menu (no
108
129
  breadcrumb behind, no peek, the panels stay), and `useWorkspace({ hash: true })` puts the
109
130
  workspace in the URL with the browser's Back working. Unsaved changes are asked with the
@@ -118,7 +139,8 @@ The same gesture means the same thing on every screen:
118
139
  | A row of a list | click | **page**, with breadcrumb |
119
140
  | A record's name INSIDE the peek | click | a step **in the peek**; ← comes back |
120
141
  | 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** |
142
+ | A many2one field | open · search | **window** · a **modal** that **answers** |
143
+ | A short task on a record (register a payment) | click | **modal** over that record |
122
144
  | A record's buttons that _lead_ (see its items) | click | **side** |
123
145
  | A record's buttons that _produce_ (post, reconcile) | click | nothing opens: they act on the record |
124
146
  | Ticking rows | select | nothing opens: the context changes |
@@ -210,7 +232,8 @@ anywhere above the workspace — no stylesheet to import:
210
232
  --sc-surface: var(--my-surface);
211
233
  --sc-accent: var(--my-brand);
212
234
  /* --sc-ground --sc-line --sc-line-strong --sc-ink --sc-muted --sc-danger --sc-scrim
213
- --sc-shadow --sc-radius --sc-radius-control --sc-text --sc-text-small */
235
+ --sc-shadow --sc-radius --sc-radius-control --sc-text --sc-text-small
236
+ --sc-icon (14px: every icon in a control, yours too) --sc-modal-scrim --sc-modal-blur */
214
237
  }
215
238
  ```
216
239
 
@@ -226,8 +249,9 @@ The composer owns the behaviour; the look is yours. Take only what you need:
226
249
  workspace={workspace}
227
250
  registry={registry}
228
251
  skin={{
229
- icons: { close: X, more: Ellipsis }, // any component taking className / strokeWidth
252
+ icons: { close: X, more: Ellipsis }, // drawn at --sc-icon, whatever size they come in
230
253
  Peek: MyDrawer, // ({ title, onClose, actions, children })
254
+ Modal: MyModal, // ({ title, blur, onClose, children })
231
255
  Confirm: MyConfirm, // ({ open, title, detail, keep, discard, onAnswer })
232
256
  Notice: MyNotice, // ({ heading, detail, bad })
233
257
  }}
@@ -25,6 +25,8 @@ export declare const Destination: {
25
25
  readonly Peek: "peek";
26
26
  readonly Window: "window";
27
27
  readonly Side: "side";
28
+ /** Over the surface that asked, blocking only it: a question, a chooser, a short form. */
29
+ readonly Modal: "modal";
28
30
  };
29
31
  export type Destination = (typeof Destination)[keyof typeof Destination];
30
32
  /** What a view is drawn in. A view does not change shape by surface — density does — but it
@@ -33,6 +35,7 @@ export declare const Surface: {
33
35
  readonly Page: "page";
34
36
  readonly Panel: "panel";
35
37
  readonly Peek: "peek";
38
+ readonly Modal: "modal";
36
39
  };
37
40
  export type Surface = (typeof Surface)[keyof typeof Surface];
38
41
  export declare const HandleKind: {
@@ -23,6 +23,8 @@ export const Destination = {
23
23
  Peek: "peek",
24
24
  Window: "window",
25
25
  Side: "side",
26
+ /** Over the surface that asked, blocking only it: a question, a chooser, a short form. */
27
+ Modal: "modal",
26
28
  };
27
29
  /** What a view is drawn in. A view does not change shape by surface — density does — but it
28
30
  * needs to know which actions to offer. */
@@ -30,6 +32,7 @@ export const Surface = {
30
32
  Page: "page",
31
33
  Panel: "panel",
32
34
  Peek: "peek",
35
+ Modal: "modal",
33
36
  };
34
37
  export const HandleKind = {
35
38
  Zone: "zone",
@@ -1,9 +1,10 @@
1
1
  /** The model: no React, no CSS. Tested in Node; survives any change of skin. */
2
2
  export type { Dock } from "./enums.js";
3
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";
4
+ export { type Box, type Handle, handles, KEYBOARD_STEP, layout, type Length, phoneLayout, resolve, sizeAt, type Slot, stableOrder, STRIP, ZONE_LIMITS, } from "./layout.js";
5
5
  export { localEntries, matches, MIN_QUERY, type PaletteEntry, PaletteSection, searchEntries, } from "./palette.js";
6
+ export { chooserOnPhone, destinationOnPhone, PHONE_WIDTH, } from "./phone.js";
6
7
  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
8
  export { formatRef, isRef, parseRef, type ResourceRef, rootRef, sameRef, withParams, } from "./resource.js";
8
9
  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";
10
+ export { back, closeModal, closePanel, closePeek, collapsePanel, cycleFocus, DEFAULT_ZONES, drillPeek, EMPTY, expandPanel, findPanel, floatPanel, focusedRef, focusPanel, goTo, hostOf, MAX_ZONE, maximize, MIN_SHARE, MIN_WINDOW, MIN_ZONE, MODAL, type Modal, modalId, modalOver, movePanel, nameOf, nameRef, navigatePanel, openModal, type OpenModalOptions, 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, settleModals, type Size, start, type WindowBox, type Workspace, type Zones, } from "./workspace.js";
@@ -1,8 +1,9 @@
1
1
  /** The model: no React, no CSS. Tested in Node; survives any change of skin. */
2
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";
3
+ export { handles, KEYBOARD_STEP, layout, phoneLayout, resolve, sizeAt, stableOrder, STRIP, ZONE_LIMITS, } from "./layout.js";
4
4
  export { localEntries, matches, MIN_QUERY, PaletteSection, searchEntries, } from "./palette.js";
5
+ export { chooserOnPhone, destinationOnPhone, PHONE_WIDTH, } from "./phone.js";
5
6
  export { createRegistry, loadView, } from "./registry.js";
6
7
  export { formatRef, isRef, parseRef, rootRef, sameRef, withParams, } from "./resource.js";
7
8
  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";
9
+ export { back, closeModal, closePanel, closePeek, collapsePanel, cycleFocus, DEFAULT_ZONES, drillPeek, EMPTY, expandPanel, findPanel, floatPanel, focusedRef, focusPanel, goTo, hostOf, MAX_ZONE, maximize, MIN_SHARE, MIN_WINDOW, MIN_ZONE, MODAL, modalId, modalOver, movePanel, nameOf, nameRef, navigatePanel, openModal, openPanel, PAGE, panelsIn, PEEK, peek, peekBack, peekGoTo, peekToPage, peekToSide, push, raisePanel, refOn, replace, replacePeek, resizePanel, resizeZone, select, selectionOf, settleModals, start, } from "./workspace.js";
@@ -50,6 +50,9 @@ export declare const resolve: (l: Length, size: number) => number;
50
50
  /** What a minimized panel keeps: its title bar. It matches the frame's header. */
51
51
  export declare const STRIP = 36;
52
52
  export declare function layout(w: Workspace): readonly Slot[];
53
+ /** On a phone the page takes the whole workspace and every panel waits, mounted and hidden, to be
54
+ * brought to the page (see `phone.ts`). Hidden, not dropped: what was typed in it survives. */
55
+ export declare function phoneLayout(slots: readonly Slot[]): readonly Slot[];
53
56
  /** Sorted by id so sibling order does not change when a panel changes zone — reordering
54
57
  * siblings is what unmounts. */
55
58
  export declare function stableOrder(slots: readonly Slot[]): readonly Slot[];
@@ -134,6 +134,13 @@ export function layout(w) {
134
134
  ? { ...slot, box: FULL, floating: false, visible: true, collapsed: false, rail: false }
135
135
  : { ...slot, visible: false });
136
136
  }
137
+ /** On a phone the page takes the whole workspace and every panel waits, mounted and hidden, to be
138
+ * brought to the page (see `phone.ts`). Hidden, not dropped: what was typed in it survives. */
139
+ export function phoneLayout(slots) {
140
+ return slots.map((slot) => slot.id === PAGE
141
+ ? { ...slot, box: FULL, floating: false, visible: true, collapsed: false, rail: false }
142
+ : { ...slot, visible: false });
143
+ }
137
144
  /** Sorted by id so sibling order does not change when a panel changes zone — reordering
138
145
  * siblings is what unmounts. */
139
146
  export function stableOrder(slots) {
@@ -0,0 +1,18 @@
1
+ import { Destination } from "./enums.js";
2
+ /**
3
+ * On a phone there is ONE screen. A side panel has no side to dock to and a window has nowhere
4
+ * to float, so they are not shrunk — they are translated into what a phone already has: the page,
5
+ * with its breadcrumb to come back. The peek and the modal stay: a drawer the width of the screen
6
+ * and a sheet from the bottom are what a phone does anyway.
7
+ *
8
+ * It is the WORKSPACE's width that decides, not the device's: a narrow embed on a wide screen is
9
+ * a phone too. Nothing in the model changes: the panels keep their zones, so widening the window
10
+ * brings the desk back as it was.
11
+ */
12
+ /** Below this many pixels the workspace is a phone. */
13
+ export declare const PHONE_WIDTH = 640;
14
+ /** Where `open(ref, { to })` goes on a phone. */
15
+ export declare function destinationOnPhone(to: Destination): Destination;
16
+ /** Where a chooser opens on a phone. Not the page: it would push the form that asked into the
17
+ * breadcrumb — and the form has to stay where it is to receive the answer. */
18
+ export declare function chooserOnPhone(to: Destination): Destination;
@@ -0,0 +1,22 @@
1
+ import { Destination } from "./enums.js";
2
+ /**
3
+ * On a phone there is ONE screen. A side panel has no side to dock to and a window has nowhere
4
+ * to float, so they are not shrunk — they are translated into what a phone already has: the page,
5
+ * with its breadcrumb to come back. The peek and the modal stay: a drawer the width of the screen
6
+ * and a sheet from the bottom are what a phone does anyway.
7
+ *
8
+ * It is the WORKSPACE's width that decides, not the device's: a narrow embed on a wide screen is
9
+ * a phone too. Nothing in the model changes: the panels keep their zones, so widening the window
10
+ * brings the desk back as it was.
11
+ */
12
+ /** Below this many pixels the workspace is a phone. */
13
+ export const PHONE_WIDTH = 640;
14
+ /** Where `open(ref, { to })` goes on a phone. */
15
+ export function destinationOnPhone(to) {
16
+ return to === Destination.Window || to === Destination.Side ? Destination.Page : to;
17
+ }
18
+ /** Where a chooser opens on a phone. Not the page: it would push the form that asked into the
19
+ * breadcrumb — and the form has to stay where it is to receive the answer. */
20
+ export function chooserOnPhone(to) {
21
+ return to === Destination.Window || to === Destination.Side ? Destination.Modal : to;
22
+ }
@@ -1,5 +1,6 @@
1
1
  import type { Destination, Surface, Zone } from "./enums.js";
2
2
  import type { ResourceRef } from "./resource.js";
3
+ import type { Size } from "./workspace.js";
3
4
  import type { ComponentType } from "react";
4
5
  export { Surface } from "./enums.js";
5
6
  /**
@@ -9,10 +10,20 @@ export { Surface } from "./enums.js";
9
10
  export type OpenOptions = {
10
11
  /** Where it opens. Without it, the workspace's default: the page. */
11
12
  to?: Destination;
13
+ /** A modal only: blur what it covers. Off by default — the surface underneath is blocked,
14
+ * not hidden. */
15
+ blur?: boolean;
16
+ /** A window or a modal: the size it opens at, in pixels (a window: 480×360 without it). What
17
+ * does not fit is shrunk to what there is. On a phone there are no windows: it is ignored. */
18
+ size?: Size;
12
19
  };
13
20
  export type PickOptions = {
14
21
  /** Where the chooser opens. A window unless said otherwise. */
15
- to?: typeof Destination.Peek | typeof Destination.Window | typeof Destination.Side;
22
+ to?: typeof Destination.Peek | typeof Destination.Window | typeof Destination.Side | typeof Destination.Modal;
23
+ /** A modal only: blur what it covers. */
24
+ blur?: boolean;
25
+ /** A window or a modal: the size the chooser opens at, in pixels. */
26
+ size?: Size;
16
27
  };
17
28
  /** One step of a breadcrumb, ready for `List.Crumbs` or `Record.Crumbs`. */
18
29
  export type Crumb = {
@@ -26,35 +37,44 @@ export type Crumb = {
26
37
  export type WorkspaceApi = {
27
38
  self: ResourceRef;
28
39
  surface: Surface;
40
+ /**
41
+ * In a modal, what it was opened over — the record of the window, panel or page underneath:
42
+ * its context. `null` on any other surface. Anything else the two share travels in the
43
+ * modal's reference (`params`) and comes back with `answer`.
44
+ */
45
+ over: ResourceRef | null;
29
46
  /**
30
47
  * The one way to open a resource: `open(ref)` goes where the workspace opens by default (the
31
48
  * page), `open(ref, { to })` where the caller says. Opening the page from a window leaves the
32
49
  * window where it is; from the peek it closes the drawer — it sat over a page that is no longer
33
50
  * there. Inside the peek a plain `open(ref)` drills IN the drawer, and ← comes back: reading
34
- * does not throw the reader out.
51
+ * does not throw the reader out. `{ to: "modal" }` opens it over THIS surface, blocking only
52
+ * it; from inside a modal, it replaces that modal.
35
53
  */
36
54
  open: (ref: ResourceRef, options?: OpenOptions) => void;
37
55
  /** 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. */
56
+ * panel or a modal has no way back: it just changes. */
39
57
  navigate: (ref: ResourceRef) => void;
40
58
  /** Show `ref` HERE without a step to come back to: the record a form just created, a filter. */
41
59
  replace: (ref: ResourceRef) => void;
42
60
  /** This resource with `params` merged (`""` removes one), in place: filters live in the
43
61
  * reference — they survive a reload, a link and a move to another surface. */
44
62
  setParams: (params: Record<string, string>) => void;
45
- /** One step back: the page's breadcrumb or the peek's own trail. Nothing in a panel. */
63
+ /** One step back: the page's breadcrumb or the peek's own trail. Nothing in a panel or a
64
+ * modal. */
46
65
  back: () => void;
47
- /** A window, a side panel or the peek grows into the page. Nothing on the page itself. */
66
+ /** A window, a side panel or the peek grows into the page. Nothing on the page itself, nor in
67
+ * a modal: it is a moment over something, not a place. */
48
68
  expand: () => void;
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. */
69
+ /** Leave what this view is in: its panel, the peek or the modal closes; the page goes one
70
+ * step back. «Cancel» on a form is this one call wherever the form was opened. */
51
71
  close: () => void;
52
72
  /** Request workspace focus so shortcuts talk to this view. */
53
73
  focus: () => void;
54
74
  /**
55
75
  * The way here, ready for `List.Crumbs` / `Record.Crumbs`: the pages before, each a link, and
56
76
  * 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.
77
+ * in a panel or a modal: its frame already says what it shows.
58
78
  *
59
79
  * What it is NOW, and the same array until it changes. A view draws it with `useCrumbs(api)`,
60
80
  * which follows it: read during render, a name given later (`setTitle`) would not show.
@@ -11,6 +11,6 @@ export type SessionMemory = {
11
11
  * The browser moved through its history: the URL says WHERE, the session says how I got there.
12
12
  * With the entry's own memory the trails are exact; without it they are reconciled. The
13
13
  * selection survives only while its surface still shows the same resource, and the names views
14
- * gave stay.
14
+ * gave stay. So does a modal, while what it covers is still there.
15
15
  */
16
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
2
  import { formatRef, parseRef, sameRef, } from "./resource.js";
3
- import { DEFAULT_ZONES, EMPTY, PAGE, PEEK, refOn, } from "./workspace.js";
3
+ import { DEFAULT_ZONES, EMPTY, hostOf, PAGE, PEEK, refOn, settleModals, } 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.
@@ -78,8 +78,10 @@ export function toHash(w) {
78
78
  parts.push(`z=${packZones(w.zones)}`);
79
79
  if (w.peek !== null)
80
80
  parts.push(`k=${formatRef(w.peek)}`);
81
- if (w.focus !== PAGE)
82
- parts.push(`f=${w.focus}`);
81
+ /* A modal is not in the URL: its host stands for it. */
82
+ const focus = hostOf(w.focus);
83
+ if (focus !== PAGE)
84
+ parts.push(`f=${focus}`);
83
85
  if (w.maximized !== null)
84
86
  parts.push(`m=${w.maximized}`);
85
87
  return `#/w?${parts.join("&")}`;
@@ -124,7 +126,7 @@ function trailTo(now, page) {
124
126
  * The browser moved through its history: the URL says WHERE, the session says how I got there.
125
127
  * With the entry's own memory the trails are exact; without it they are reconciled. The
126
128
  * selection survives only while its surface still shows the same resource, and the names views
127
- * gave stay.
129
+ * gave stay. So does a modal, while what it covers is still there.
128
130
  */
129
131
  export function restore(now, url, memory) {
130
132
  const peekTrail = url.peek === null
@@ -135,11 +137,12 @@ export function restore(now, url, memory) {
135
137
  const before = by === undefined ? null : refOn(now, by);
136
138
  const after = by === undefined ? null : refOn(url, by);
137
139
  const keeps = before !== null && after !== null && sameRef(before, after);
138
- return {
140
+ return settleModals({
139
141
  ...url,
140
142
  trail: url.page === null ? [] : (memory?.trail ?? trailTo(now, url.page)),
141
143
  peekTrail,
142
144
  selected: keeps ? now.selected : null,
143
145
  titles: now.titles,
144
- };
146
+ modals: now.modals,
147
+ });
145
148
  }
@@ -35,6 +35,30 @@ export type Panel = {
35
35
  };
36
36
  /** How much of the container each docked zone takes. */
37
37
  export type Zones = Record<Dock, number>;
38
+ /**
39
+ * A view over ONE surface — the page, the peek or a panel — blocking only it: a question, a
40
+ * chooser, a short form. One per surface: a modal over a modal is the road to simulated windows,
41
+ * so opening another one over the same surface replaces it.
42
+ *
43
+ * It belongs to what its host shows (`over`): when the host shows another resource or goes away
44
+ * the modal is gone, and coming back to that resource does not bring it back.
45
+ */
46
+ export type Modal = {
47
+ /** `PAGE`, `PEEK` or a panel id. */
48
+ host: string;
49
+ /** What the host showed when the modal opened — its context (`api.over`). */
50
+ over: ResourceRef;
51
+ view: ResourceRef;
52
+ /** Blur what it covers. Off unless asked: the host is blocked, not hidden. */
53
+ blur: boolean;
54
+ /** The size its view asked for; without it, the modal's own. */
55
+ size?: Size;
56
+ };
57
+ /** A size a view asks for, in pixels. What does not fit is shrunk to what there is. */
58
+ export type Size = {
59
+ w: number;
60
+ h: number;
61
+ };
38
62
  /** What a selection belongs to, and the references selected. */
39
63
  export type Selected = {
40
64
  by: string;
@@ -60,20 +84,32 @@ export type Workspace = {
60
84
  /** The names views gave their resources once loaded (`api.setTitle`), by `formatRef`. The
61
85
  * crumbs and the frames show them instead of the slug. Session memory, not in the URL. */
62
86
  titles: Readonly<Record<string, string>>;
87
+ /** At most one per host. Session memory, not in the URL: a modal is a moment, not a place. */
88
+ modals: readonly Modal[];
63
89
  };
64
90
  /** The page is not a panel and has no id; it needs one so it can be focused and maximized. */
65
91
  export declare const PAGE = "page";
66
92
  /** Nor is the peek; it needs one to take the focus and publish a selection. */
67
93
  export declare const PEEK = "peek";
94
+ /** A modal is known by its host: `modal:page`, `modal:p2`. */
95
+ export declare const MODAL = "modal:";
96
+ export declare const modalId: (host: string) => string;
97
+ /** The surface under a modal; any other surface is its own host. */
98
+ export declare const hostOf: (id: string) => string;
68
99
  export declare const DEFAULT_ZONES: Zones;
69
100
  /** Outside these limits one of the two sides stops being usable. */
70
101
  export declare const MIN_ZONE = 0.12;
71
102
  export declare const MAX_ZONE = 0.72;
72
103
  export declare const MIN_SHARE = 0.12;
104
+ /** Below this a window's controls overlap; a size asked for is never smaller. */
105
+ export declare const MIN_WINDOW: Size;
73
106
  export declare const EMPTY: Workspace;
74
107
  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. */
108
+ /** What a surface shows now — the page, the peek, a panel or a modal — or `null` if it is not
109
+ * there. */
76
110
  export declare function refOn(w: Workspace, surface: string): ResourceRef | null;
111
+ /** The modal over `host`, while its host still shows what it was opened over. */
112
+ export declare function modalOver(w: Workspace, host: string): Modal | null;
77
113
  export declare const panelsIn: (w: Workspace, zone: Zone) => readonly Panel[];
78
114
  /**
79
115
  * Opens `view` as the page and keeps where I was, so the breadcrumb can take me back. The first
@@ -97,6 +133,8 @@ export type OpenPanelOptions = {
97
133
  /** Deduplicating is the right default for a column and the wrong one for «the same table
98
134
  * with two filters». */
99
135
  allowDuplicate?: boolean;
136
+ /** A window only: the size it opens at — and the size an open one takes when asked again. */
137
+ size?: Size;
100
138
  };
101
139
  /** Opens a resource as a panel. If it is already open it moves it to the requested zone and
102
140
  * focuses it, unless a duplicate is explicitly asked for. */
@@ -156,6 +194,25 @@ export declare function closePeek(w: Workspace): Workspace;
156
194
  export declare function peekToPage(w: Workspace): Workspace;
157
195
  /** It docks to the right because the drawer was already there and the piece does not move. */
158
196
  export declare function peekToSide(w: Workspace, zone?: Zone): Workspace;
197
+ export type OpenModalOptions = {
198
+ blur?: boolean;
199
+ size?: Size;
200
+ };
201
+ /**
202
+ * `view` over `host`, which keeps its place and its state underneath. Asked from inside a
203
+ * modal, it replaces that one: same host, no stacking. It takes the focus, so the shortcuts and
204
+ * ⌘K talk to it.
205
+ */
206
+ export declare function openModal(w: Workspace, host: string, view: ResourceRef, { blur, size }?: OpenModalOptions): Workspace;
207
+ /** Closes the modal over `host` (or the modal itself, by its id). The focus goes back to the
208
+ * surface it covered. */
209
+ export declare function closeModal(w: Workspace, host: string): Workspace;
210
+ /**
211
+ * Forgets every modal whose host no longer shows what it was opened over. Without it a modal
212
+ * left behind would come back with its record — open a record, open a modal, go to another
213
+ * page and back, and the question would be asked again. The store runs it after every change.
214
+ */
215
+ export declare function settleModals(w: Workspace): Workspace;
159
216
  /**
160
217
  * What a surface has selected — the rows of a list. The workspace keeps only references, so a
161
218
  * chat in another domain can read them without knowing what they are. Selecting nothing clears
@@ -5,6 +5,12 @@ export { DOCKS, Zone };
5
5
  export const PAGE = "page";
6
6
  /** Nor is the peek; it needs one to take the focus and publish a selection. */
7
7
  export const PEEK = "peek";
8
+ /** A modal is known by its host: `modal:page`, `modal:p2`. */
9
+ export const MODAL = "modal:";
10
+ export const modalId = (host) => `${MODAL}${host}`;
11
+ const isModalId = (id) => id.startsWith(MODAL);
12
+ /** The surface under a modal; any other surface is its own host. */
13
+ export const hostOf = (id) => (isModalId(id) ? id.slice(MODAL.length) : id);
8
14
  export const DEFAULT_ZONES = {
9
15
  [Zone.Left]: 0.28,
10
16
  [Zone.Right]: 0.36,
@@ -15,6 +21,8 @@ export const MIN_ZONE = 0.12;
15
21
  export const MAX_ZONE = 0.72;
16
22
  export const MIN_SHARE = 0.12;
17
23
  const WINDOW_BOX = { x: 72, y: 56, w: 480, h: 360 };
24
+ /** Below this a window's controls overlap; a size asked for is never smaller. */
25
+ export const MIN_WINDOW = { w: 280, h: 160 };
18
26
  const WINDOW_OFFSET = 28;
19
27
  export const EMPTY = {
20
28
  page: null,
@@ -27,6 +35,7 @@ export const EMPTY = {
27
35
  maximized: null,
28
36
  selected: null,
29
37
  titles: {},
38
+ modals: [],
30
39
  };
31
40
  const clampZone = (n) => Math.max(MIN_ZONE, Math.min(MAX_ZONE, n));
32
41
  /** The id comes from the content and not from a global counter, so two identical workspaces
@@ -38,14 +47,25 @@ function nextId(used) {
38
47
  return `p${n}`;
39
48
  }
40
49
  export const findPanel = (w, id) => w.panels.find((p) => p.id === id) ?? null;
41
- /** What a surface shows now — the page, the peek or a panel — or `null` if it is not there. */
50
+ /** What a surface shows now — the page, the peek, a panel or a modal — or `null` if it is not
51
+ * there. */
42
52
  export function refOn(w, surface) {
43
53
  if (surface === PAGE)
44
54
  return w.page;
45
55
  if (surface === PEEK)
46
56
  return w.peek;
57
+ if (isModalId(surface))
58
+ return modalOver(w, hostOf(surface))?.view ?? null;
47
59
  return findPanel(w, surface)?.view ?? null;
48
60
  }
61
+ /** The modal over `host`, while its host still shows what it was opened over. */
62
+ export function modalOver(w, host) {
63
+ const modal = w.modals.find((m) => m.host === host);
64
+ if (modal === undefined)
65
+ return null;
66
+ const shown = refOn(w, host);
67
+ return shown !== null && sameRef(rootRef(shown), rootRef(modal.over)) ? modal : null;
68
+ }
49
69
  export const panelsIn = (w, zone) => w.panels.filter((p) => p.placement.zone === zone);
50
70
  function withPanel(w, id, change) {
51
71
  if (!w.panels.some((p) => p.id === id))
@@ -72,7 +92,7 @@ const normalizeAll = (panels) => DOCKS.reduce((acc, zone) => normalize(acc, zone
72
92
  function topZ(panels) {
73
93
  return panels.reduce((max, p) => (p.placement.zone === Zone.Floating ? Math.max(max, p.placement.z) : max), 0);
74
94
  }
75
- function placementFor(zone, panels) {
95
+ function placementFor(zone, panels, size) {
76
96
  if (zone !== Zone.Floating)
77
97
  return { zone, share: 1 };
78
98
  const floating = panels.filter((p) => p.placement.zone === Zone.Floating).length;
@@ -80,8 +100,8 @@ function placementFor(zone, panels) {
80
100
  zone,
81
101
  x: WINDOW_BOX.x + floating * WINDOW_OFFSET,
82
102
  y: WINDOW_BOX.y + floating * WINDOW_OFFSET,
83
- w: WINDOW_BOX.w,
84
- h: WINDOW_BOX.h,
103
+ w: Math.max(MIN_WINDOW.w, size?.w ?? WINDOW_BOX.w),
104
+ h: Math.max(MIN_WINDOW.h, size?.h ?? WINDOW_BOX.h),
85
105
  z: topZ(panels) + 1,
86
106
  };
87
107
  }
@@ -150,11 +170,19 @@ export function openPanel(w, view, options = {}) {
150
170
  const zone = opts.zone ?? Zone.Right;
151
171
  if (opts.allowDuplicate !== true) {
152
172
  const existing = w.panels.find((p) => sameRef(p.view, view));
153
- if (existing)
154
- return focusPanel(movePanel(w, existing.id, zone), existing.id);
173
+ if (existing) {
174
+ const moved = movePanel(w, existing.id, zone);
175
+ const sized = opts.size === undefined || zone !== Zone.Floating
176
+ ? moved
177
+ : floatPanel(moved, existing.id, {
178
+ w: Math.max(MIN_WINDOW.w, opts.size.w),
179
+ h: Math.max(MIN_WINDOW.h, opts.size.h),
180
+ });
181
+ return focusPanel(sized, existing.id);
182
+ }
155
183
  }
156
184
  const id = nextId(w.panels.map((p) => p.id));
157
- const panel = { id, view, placement: placementFor(zone, w.panels) };
185
+ const panel = { id, view, placement: placementFor(zone, w.panels, opts.size) };
158
186
  return focusPanel({ ...w, panels: normalizeAll([...w.panels, panel]) }, id);
159
187
  }
160
188
  export function movePanel(w, id, zone) {
@@ -168,13 +196,13 @@ export function movePanel(w, id, zone) {
168
196
  export function closePanel(w, id) {
169
197
  if (findPanel(w, id) === null)
170
198
  return w;
171
- return {
199
+ return settleModals({
172
200
  ...w,
173
201
  panels: normalizeAll(w.panels.filter((p) => p.id !== id)),
174
202
  maximized: w.maximized === id ? null : w.maximized,
175
203
  focus: w.focus === id ? PAGE : w.focus,
176
204
  selected: dropSelection(w, id),
177
- };
205
+ });
178
206
  }
179
207
  /** Changes what a panel looks at without moving or closing it. */
180
208
  export function navigatePanel(w, id, view) {
@@ -338,6 +366,55 @@ export function peekToPage(w) {
338
366
  export function peekToSide(w, zone = Zone.Right) {
339
367
  return w.peek === null ? w : closePeek(openPanel(w, w.peek, { zone }));
340
368
  }
369
+ /**
370
+ * `view` over `host`, which keeps its place and its state underneath. Asked from inside a
371
+ * modal, it replaces that one: same host, no stacking. It takes the focus, so the shortcuts and
372
+ * ⌘K talk to it.
373
+ */
374
+ export function openModal(w, host, view, { blur = false, size } = {}) {
375
+ const under = hostOf(host);
376
+ const over = refOn(w, under);
377
+ if (over === null)
378
+ return w;
379
+ const id = modalId(under);
380
+ const current = modalOver(w, under);
381
+ if (current !== null &&
382
+ sameRef(current.view, view) &&
383
+ current.blur === blur &&
384
+ current.size?.w === size?.w &&
385
+ current.size?.h === size?.h)
386
+ return focusPanel(w, id);
387
+ const modals = [
388
+ ...w.modals.filter((m) => m.host !== under && modalOver(w, m.host) !== null),
389
+ { host: under, over, view, blur, ...(size === undefined ? {} : { size }) },
390
+ ];
391
+ return { ...w, modals, focus: id, selected: dropSelection(w, id) };
392
+ }
393
+ /** Closes the modal over `host` (or the modal itself, by its id). The focus goes back to the
394
+ * surface it covered. */
395
+ export function closeModal(w, host) {
396
+ const under = hostOf(host);
397
+ if (!w.modals.some((m) => m.host === under))
398
+ return w;
399
+ const id = modalId(under);
400
+ return {
401
+ ...w,
402
+ modals: w.modals.filter((m) => m.host !== under),
403
+ focus: w.focus === id ? (refOn(w, under) === null ? PAGE : under) : w.focus,
404
+ selected: dropSelection(w, id),
405
+ };
406
+ }
407
+ /**
408
+ * Forgets every modal whose host no longer shows what it was opened over. Without it a modal
409
+ * left behind would come back with its record — open a record, open a modal, go to another
410
+ * page and back, and the question would be asked again. The store runs it after every change.
411
+ */
412
+ export function settleModals(w) {
413
+ const gone = w.modals.filter((m) => modalOver(w, m.host) === null);
414
+ if (gone.length === 0)
415
+ return w;
416
+ return gone.reduce((acc, m) => closeModal(acc, m.host), w);
417
+ }
341
418
  /* ── Context ────────────────────────────────────────────────────────── */
342
419
  const NO_REFS = [];
343
420
  function dropSelection(w, by) {
@@ -370,6 +447,7 @@ const reachable = (w) => [
370
447
  ...w.peekTrail,
371
448
  ...(w.peek === null ? [] : [w.peek]),
372
449
  ...w.panels.map((p) => p.view),
450
+ ...w.modals.map((m) => m.view),
373
451
  ];
374
452
  /**
375
453
  * The name a view gives its resource once it has loaded it — «Acme S.R.L.» instead of
package/dist/index.d.ts CHANGED
@@ -11,14 +11,15 @@ export { Destination, focusedRef, PAGE, PaletteSection, PEEK, selectionOf, Surfa
11
11
  export { Composer, type ComposerProps } from "./shell/Composer.js";
12
12
  export { type ComposerCopy, composerCopy, ENGLISH_COMPOSER_COPY, installComposerCopy, SPANISH_COMPOSER_COPY, } from "./shell/copy.js";
13
13
  export { type IconProps } from "./shell/icons.js";
14
+ export { ModalLayer, type ModalLayerProps, ModalWindow, } from "./shell/Modal.js";
14
15
  export { WorkspacePalette, type WorkspacePaletteProps, } from "./shell/Palette.js";
15
16
  export { type PanelActions, PanelFrame, type PanelFrameProps, } from "./shell/PanelFrame.js";
16
17
  export { PanelHost, type PanelHostProps } from "./shell/PanelHost.js";
17
18
  export { RecordLink, type RecordLinkProps } from "./shell/RecordLink.js";
18
- export { type ComposerSkin, type ConfirmProps, DEFAULT_ICONS, type NoticeProps, type PeekProps, type SkinIcons, } from "./shell/skin.js";
19
+ export { type ComposerSkin, type ConfirmProps, DEFAULT_ICONS, type ModalProps, type NoticeProps, type PeekProps, type SkinIcons, } from "./shell/skin.js";
19
20
  export { ComposerStyles } from "./shell/styles.js";
20
21
  export { ViewHost, type ViewHostProps } from "./shell/ViewHost.js";
21
- export { type ApiFactory, createApiFactory, type Target, } from "./state/api.js";
22
+ export { type ApiFactory, createApiFactory, type Target, targetOf, } from "./state/api.js";
22
23
  export { type ConfirmDiscard, createWorkspaceStore, type StoreOptions, type WorkspaceStore, } from "./state/store.js";
23
24
  export { useKeyboard, type UseKeyboardOptions, } from "./state/useKeyboard.js";
24
25
  export { useCrumbs, useWorkspace, useWorkspaceContext, useWorkspaceSlice, useWorkspaceState, } from "./state/useWorkspace.js";