@sincpro/web-composer 1.1.0 → 1.2.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,37 @@ 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.over; // in a modal: the record it was opened over — its context (null elsewhere)
94
97
  api.replace(ref); // show it HERE without a step back: the record a form just created
95
98
  api.setParams({ tenant }); // a filter that lives in the reference: survives reload and links
96
99
  useCrumbs(api); // the breadcrumb, ready for List.Crumbs / Record.Crumbs — follows setTitle
97
100
  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
101
+ api.close(); // leave: closes the panel, the peek or the modal; on the page, goes back
99
102
  api.expand(); // a window, a side panel or the peek grows into the page
100
103
  api.setTitle(name); // the record's real name, for the crumbs and the frames, once loaded
101
104
  api.setDirty(true); // unsaved: a crumb, a close or the browser's Back ask first
102
105
  api.select(refs); // publish what this view has selected
103
106
  api.context; // read what the user is on and what is selected — references only
104
107
  api.pick(ref, onPick); // open a chooser (a many2one search); its view calls api.answer(ref)
108
+ api.pick(ref, onPick, { to: "modal" }); // the chooser as a modal over the form
105
109
  ```
106
110
 
111
+ A **modal** belongs to the surface it covers — the page, a window, a side panel or the peek —
112
+ and blocks only that one: the rest of the workspace keeps answering, and a window keeps moving
113
+ and closing by its own title bar. One per surface: opening another one over the same surface,
114
+ or from inside it, replaces it. When its surface shows another record or closes, the modal goes
115
+ with it (asking first if something was typed). What it shares with whoever opened it travels in
116
+ its reference (`params`) and comes back with `api.answer`; `api.over` says what it covers. No
117
+ blur unless asked.
118
+
107
119
  From the app, around the workspace: `workspace.start(ref)` starts over from a menu (no
108
120
  breadcrumb behind, no peek, the panels stay), and `useWorkspace({ hash: true })` puts the
109
121
  workspace in the URL with the browser's Back working. Unsaved changes are asked with the
@@ -118,7 +130,8 @@ The same gesture means the same thing on every screen:
118
130
  | A row of a list | click | **page**, with breadcrumb |
119
131
  | A record's name INSIDE the peek | click | a step **in the peek**; ← comes back |
120
132
  | 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** |
133
+ | A many2one field | open · search | **window** · a **modal** that **answers** |
134
+ | A short task on a record (register a payment) | click | **modal** over that record |
122
135
  | A record's buttons that _lead_ (see its items) | click | **side** |
123
136
  | A record's buttons that _produce_ (post, reconcile) | click | nothing opens: they act on the record |
124
137
  | Ticking rows | select | nothing opens: the context changes |
@@ -210,7 +223,8 @@ anywhere above the workspace — no stylesheet to import:
210
223
  --sc-surface: var(--my-surface);
211
224
  --sc-accent: var(--my-brand);
212
225
  /* --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 */
226
+ --sc-shadow --sc-radius --sc-radius-control --sc-text --sc-text-small
227
+ --sc-icon (14px: every icon in a control, yours too) --sc-modal-scrim --sc-modal-blur */
214
228
  }
215
229
  ```
216
230
 
@@ -226,8 +240,9 @@ The composer owns the behaviour; the look is yours. Take only what you need:
226
240
  workspace={workspace}
227
241
  registry={registry}
228
242
  skin={{
229
- icons: { close: X, more: Ellipsis }, // any component taking className / strokeWidth
243
+ icons: { close: X, more: Ellipsis }, // drawn at --sc-icon, whatever size they come in
230
244
  Peek: MyDrawer, // ({ title, onClose, actions, children })
245
+ Modal: MyModal, // ({ title, blur, onClose, children })
231
246
  Confirm: MyConfirm, // ({ open, title, detail, keep, discard, onAnswer })
232
247
  Notice: MyNotice, // ({ heading, detail, bad })
233
248
  }}
@@ -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",
@@ -6,4 +6,4 @@ export { localEntries, matches, MIN_QUERY, type PaletteEntry, PaletteSection, se
6
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
7
  export { formatRef, isRef, parseRef, type ResourceRef, rootRef, sameRef, withParams, } from "./resource.js";
8
8
  export { fromHash, restore, type SessionMemory, toHash, } from "./url.js";
9
- export { back, closePanel, closePeek, collapsePanel, cycleFocus, DEFAULT_ZONES, drillPeek, EMPTY, expandPanel, findPanel, floatPanel, focusedRef, focusPanel, goTo, MAX_ZONE, maximize, MIN_SHARE, MIN_ZONE, movePanel, nameOf, nameRef, navigatePanel, openPanel, type OpenPanelOptions, PAGE, type Panel, panelsIn, PEEK, peek, peekBack, peekGoTo, peekToPage, peekToSide, type Placement, push, raisePanel, refOn, replace, replacePeek, resizePanel, resizeZone, select, type Selected, selectionOf, start, type WindowBox, type Workspace, type Zones, } from "./workspace.js";
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_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, start, type WindowBox, type Workspace, type Zones, } from "./workspace.js";
@@ -5,4 +5,4 @@ export { localEntries, matches, MIN_QUERY, PaletteSection, searchEntries, } from
5
5
  export { createRegistry, loadView, } from "./registry.js";
6
6
  export { formatRef, isRef, parseRef, rootRef, sameRef, withParams, } from "./resource.js";
7
7
  export { fromHash, restore, toHash, } from "./url.js";
8
- export { back, closePanel, closePeek, collapsePanel, cycleFocus, DEFAULT_ZONES, drillPeek, EMPTY, expandPanel, findPanel, floatPanel, focusedRef, focusPanel, goTo, MAX_ZONE, maximize, MIN_SHARE, MIN_ZONE, movePanel, nameOf, nameRef, navigatePanel, openPanel, PAGE, panelsIn, PEEK, peek, peekBack, peekGoTo, peekToPage, peekToSide, push, raisePanel, refOn, replace, replacePeek, resizePanel, resizeZone, select, selectionOf, start, } from "./workspace.js";
8
+ export { back, closeModal, closePanel, closePeek, collapsePanel, cycleFocus, DEFAULT_ZONES, drillPeek, EMPTY, expandPanel, findPanel, floatPanel, focusedRef, focusPanel, goTo, hostOf, MAX_ZONE, maximize, MIN_SHARE, 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";
@@ -9,10 +9,15 @@ export { Surface } from "./enums.js";
9
9
  export type OpenOptions = {
10
10
  /** Where it opens. Without it, the workspace's default: the page. */
11
11
  to?: Destination;
12
+ /** A modal only: blur what it covers. Off by default — the surface underneath is blocked,
13
+ * not hidden. */
14
+ blur?: boolean;
12
15
  };
13
16
  export type PickOptions = {
14
17
  /** Where the chooser opens. A window unless said otherwise. */
15
- to?: typeof Destination.Peek | typeof Destination.Window | typeof Destination.Side;
18
+ to?: typeof Destination.Peek | typeof Destination.Window | typeof Destination.Side | typeof Destination.Modal;
19
+ /** A modal only: blur what it covers. */
20
+ blur?: boolean;
16
21
  };
17
22
  /** One step of a breadcrumb, ready for `List.Crumbs` or `Record.Crumbs`. */
18
23
  export type Crumb = {
@@ -26,35 +31,44 @@ export type Crumb = {
26
31
  export type WorkspaceApi = {
27
32
  self: ResourceRef;
28
33
  surface: Surface;
34
+ /**
35
+ * In a modal, what it was opened over — the record of the window, panel or page underneath:
36
+ * its context. `null` on any other surface. Anything else the two share travels in the
37
+ * modal's reference (`params`) and comes back with `answer`.
38
+ */
39
+ over: ResourceRef | null;
29
40
  /**
30
41
  * The one way to open a resource: `open(ref)` goes where the workspace opens by default (the
31
42
  * page), `open(ref, { to })` where the caller says. Opening the page from a window leaves the
32
43
  * window where it is; from the peek it closes the drawer — it sat over a page that is no longer
33
44
  * there. Inside the peek a plain `open(ref)` drills IN the drawer, and ← comes back: reading
34
- * does not throw the reader out.
45
+ * does not throw the reader out. `{ to: "modal" }` opens it over THIS surface, blocking only
46
+ * it; from inside a modal, it replaces that modal.
35
47
  */
36
48
  open: (ref: ResourceRef, options?: OpenOptions) => void;
37
49
  /** 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. */
50
+ * panel or a modal has no way back: it just changes. */
39
51
  navigate: (ref: ResourceRef) => void;
40
52
  /** Show `ref` HERE without a step to come back to: the record a form just created, a filter. */
41
53
  replace: (ref: ResourceRef) => void;
42
54
  /** This resource with `params` merged (`""` removes one), in place: filters live in the
43
55
  * reference — they survive a reload, a link and a move to another surface. */
44
56
  setParams: (params: Record<string, string>) => void;
45
- /** One step back: the page's breadcrumb or the peek's own trail. Nothing in a panel. */
57
+ /** One step back: the page's breadcrumb or the peek's own trail. Nothing in a panel or a
58
+ * modal. */
46
59
  back: () => void;
47
- /** A window, a side panel or the peek grows into the page. Nothing on the page itself. */
60
+ /** A window, a side panel or the peek grows into the page. Nothing on the page itself, nor in
61
+ * a modal: it is a moment over something, not a place. */
48
62
  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. */
63
+ /** Leave what this view is in: its panel, the peek or the modal closes; the page goes one
64
+ * step back. «Cancel» on a form is this one call wherever the form was opened. */
51
65
  close: () => void;
52
66
  /** Request workspace focus so shortcuts talk to this view. */
53
67
  focus: () => void;
54
68
  /**
55
69
  * The way here, ready for `List.Crumbs` / `Record.Crumbs`: the pages before, each a link, and
56
70
  * 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.
71
+ * in a panel or a modal: its frame already says what it shows.
58
72
  *
59
73
  * What it is NOW, and the same array until it changes. A view draws it with `useCrumbs(api)`,
60
74
  * 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,23 @@ 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
+ };
38
55
  /** What a selection belongs to, and the references selected. */
39
56
  export type Selected = {
40
57
  by: string;
@@ -60,11 +77,18 @@ export type Workspace = {
60
77
  /** The names views gave their resources once loaded (`api.setTitle`), by `formatRef`. The
61
78
  * crumbs and the frames show them instead of the slug. Session memory, not in the URL. */
62
79
  titles: Readonly<Record<string, string>>;
80
+ /** At most one per host. Session memory, not in the URL: a modal is a moment, not a place. */
81
+ modals: readonly Modal[];
63
82
  };
64
83
  /** The page is not a panel and has no id; it needs one so it can be focused and maximized. */
65
84
  export declare const PAGE = "page";
66
85
  /** Nor is the peek; it needs one to take the focus and publish a selection. */
67
86
  export declare const PEEK = "peek";
87
+ /** A modal is known by its host: `modal:page`, `modal:p2`. */
88
+ export declare const MODAL = "modal:";
89
+ export declare const modalId: (host: string) => string;
90
+ /** The surface under a modal; any other surface is its own host. */
91
+ export declare const hostOf: (id: string) => string;
68
92
  export declare const DEFAULT_ZONES: Zones;
69
93
  /** Outside these limits one of the two sides stops being usable. */
70
94
  export declare const MIN_ZONE = 0.12;
@@ -72,8 +96,11 @@ export declare const MAX_ZONE = 0.72;
72
96
  export declare const MIN_SHARE = 0.12;
73
97
  export declare const EMPTY: Workspace;
74
98
  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. */
99
+ /** What a surface shows now — the page, the peek, a panel or a modal — or `null` if it is not
100
+ * there. */
76
101
  export declare function refOn(w: Workspace, surface: string): ResourceRef | null;
102
+ /** The modal over `host`, while its host still shows what it was opened over. */
103
+ export declare function modalOver(w: Workspace, host: string): Modal | null;
77
104
  export declare const panelsIn: (w: Workspace, zone: Zone) => readonly Panel[];
78
105
  /**
79
106
  * Opens `view` as the page and keeps where I was, so the breadcrumb can take me back. The first
@@ -156,6 +183,24 @@ export declare function closePeek(w: Workspace): Workspace;
156
183
  export declare function peekToPage(w: Workspace): Workspace;
157
184
  /** It docks to the right because the drawer was already there and the piece does not move. */
158
185
  export declare function peekToSide(w: Workspace, zone?: Zone): Workspace;
186
+ export type OpenModalOptions = {
187
+ blur?: boolean;
188
+ };
189
+ /**
190
+ * `view` over `host`, which keeps its place and its state underneath. Asked from inside a
191
+ * modal, it replaces that one: same host, no stacking. It takes the focus, so the shortcuts and
192
+ * ⌘K talk to it.
193
+ */
194
+ export declare function openModal(w: Workspace, host: string, view: ResourceRef, { blur }?: OpenModalOptions): Workspace;
195
+ /** Closes the modal over `host` (or the modal itself, by its id). The focus goes back to the
196
+ * surface it covered. */
197
+ export declare function closeModal(w: Workspace, host: string): Workspace;
198
+ /**
199
+ * Forgets every modal whose host no longer shows what it was opened over. Without it a modal
200
+ * left behind would come back with its record — open a record, open a modal, go to another
201
+ * page and back, and the question would be asked again. The store runs it after every change.
202
+ */
203
+ export declare function settleModals(w: Workspace): Workspace;
159
204
  /**
160
205
  * What a surface has selected — the rows of a list. The workspace keeps only references, so a
161
206
  * 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,
@@ -27,6 +33,7 @@ export const EMPTY = {
27
33
  maximized: null,
28
34
  selected: null,
29
35
  titles: {},
36
+ modals: [],
30
37
  };
31
38
  const clampZone = (n) => Math.max(MIN_ZONE, Math.min(MAX_ZONE, n));
32
39
  /** The id comes from the content and not from a global counter, so two identical workspaces
@@ -38,14 +45,25 @@ function nextId(used) {
38
45
  return `p${n}`;
39
46
  }
40
47
  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. */
48
+ /** What a surface shows now — the page, the peek, a panel or a modal — or `null` if it is not
49
+ * there. */
42
50
  export function refOn(w, surface) {
43
51
  if (surface === PAGE)
44
52
  return w.page;
45
53
  if (surface === PEEK)
46
54
  return w.peek;
55
+ if (isModalId(surface))
56
+ return modalOver(w, hostOf(surface))?.view ?? null;
47
57
  return findPanel(w, surface)?.view ?? null;
48
58
  }
59
+ /** The modal over `host`, while its host still shows what it was opened over. */
60
+ export function modalOver(w, host) {
61
+ const modal = w.modals.find((m) => m.host === host);
62
+ if (modal === undefined)
63
+ return null;
64
+ const shown = refOn(w, host);
65
+ return shown !== null && sameRef(rootRef(shown), rootRef(modal.over)) ? modal : null;
66
+ }
49
67
  export const panelsIn = (w, zone) => w.panels.filter((p) => p.placement.zone === zone);
50
68
  function withPanel(w, id, change) {
51
69
  if (!w.panels.some((p) => p.id === id))
@@ -168,13 +186,13 @@ export function movePanel(w, id, zone) {
168
186
  export function closePanel(w, id) {
169
187
  if (findPanel(w, id) === null)
170
188
  return w;
171
- return {
189
+ return settleModals({
172
190
  ...w,
173
191
  panels: normalizeAll(w.panels.filter((p) => p.id !== id)),
174
192
  maximized: w.maximized === id ? null : w.maximized,
175
193
  focus: w.focus === id ? PAGE : w.focus,
176
194
  selected: dropSelection(w, id),
177
- };
195
+ });
178
196
  }
179
197
  /** Changes what a panel looks at without moving or closing it. */
180
198
  export function navigatePanel(w, id, view) {
@@ -338,6 +356,51 @@ export function peekToPage(w) {
338
356
  export function peekToSide(w, zone = Zone.Right) {
339
357
  return w.peek === null ? w : closePeek(openPanel(w, w.peek, { zone }));
340
358
  }
359
+ /**
360
+ * `view` over `host`, which keeps its place and its state underneath. Asked from inside a
361
+ * modal, it replaces that one: same host, no stacking. It takes the focus, so the shortcuts and
362
+ * ⌘K talk to it.
363
+ */
364
+ export function openModal(w, host, view, { blur = false } = {}) {
365
+ const under = hostOf(host);
366
+ const over = refOn(w, under);
367
+ if (over === null)
368
+ return w;
369
+ const id = modalId(under);
370
+ const current = modalOver(w, under);
371
+ if (current !== null && sameRef(current.view, view) && current.blur === blur)
372
+ return focusPanel(w, id);
373
+ const modals = [
374
+ ...w.modals.filter((m) => m.host !== under && modalOver(w, m.host) !== null),
375
+ { host: under, over, view, blur },
376
+ ];
377
+ return { ...w, modals, focus: id, selected: dropSelection(w, id) };
378
+ }
379
+ /** Closes the modal over `host` (or the modal itself, by its id). The focus goes back to the
380
+ * surface it covered. */
381
+ export function closeModal(w, host) {
382
+ const under = hostOf(host);
383
+ if (!w.modals.some((m) => m.host === under))
384
+ return w;
385
+ const id = modalId(under);
386
+ return {
387
+ ...w,
388
+ modals: w.modals.filter((m) => m.host !== under),
389
+ focus: w.focus === id ? (refOn(w, under) === null ? PAGE : under) : w.focus,
390
+ selected: dropSelection(w, id),
391
+ };
392
+ }
393
+ /**
394
+ * Forgets every modal whose host no longer shows what it was opened over. Without it a modal
395
+ * left behind would come back with its record — open a record, open a modal, go to another
396
+ * page and back, and the question would be asked again. The store runs it after every change.
397
+ */
398
+ export function settleModals(w) {
399
+ const gone = w.modals.filter((m) => modalOver(w, m.host) === null);
400
+ if (gone.length === 0)
401
+ return w;
402
+ return gone.reduce((acc, m) => closeModal(acc, m.host), w);
403
+ }
341
404
  /* ── Context ────────────────────────────────────────────────────────── */
342
405
  const NO_REFS = [];
343
406
  function dropSelection(w, by) {
@@ -370,6 +433,7 @@ const reachable = (w) => [
370
433
  ...w.peekTrail,
371
434
  ...(w.peek === null ? [] : [w.peek]),
372
435
  ...w.panels.map((p) => p.view),
436
+ ...w.modals.map((m) => m.view),
373
437
  ];
374
438
  /**
375
439
  * 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";
package/dist/index.js CHANGED
@@ -10,6 +10,7 @@ export { Destination, focusedRef, PAGE, PaletteSection, PEEK, selectionOf, Surfa
10
10
  export { Composer } from "./shell/Composer.js";
11
11
  export { composerCopy, ENGLISH_COMPOSER_COPY, installComposerCopy, SPANISH_COMPOSER_COPY, } from "./shell/copy.js";
12
12
  export {} from "./shell/icons.js";
13
+ export { ModalLayer, ModalWindow, } from "./shell/Modal.js";
13
14
  export { WorkspacePalette, } from "./shell/Palette.js";
14
15
  export { PanelFrame, } from "./shell/PanelFrame.js";
15
16
  export { PanelHost } from "./shell/PanelHost.js";
@@ -17,7 +18,7 @@ export { RecordLink } from "./shell/RecordLink.js";
17
18
  export { DEFAULT_ICONS, } from "./shell/skin.js";
18
19
  export { ComposerStyles } from "./shell/styles.js";
19
20
  export { ViewHost } from "./shell/ViewHost.js";
20
- export { createApiFactory, } from "./state/api.js";
21
+ export { createApiFactory, targetOf, } from "./state/api.js";
21
22
  export { createWorkspaceStore, } from "./state/store.js";
22
23
  export { useKeyboard, } from "./state/useKeyboard.js";
23
24
  export { useCrumbs, useWorkspace, useWorkspaceContext, useWorkspaceSlice, useWorkspaceState, } from "./state/useWorkspace.js";
@@ -1,13 +1,14 @@
1
1
  import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { Destination, focusedRef, PAGE, PEEK, Surface, Zone, } from "../domain/index.js";
2
+ import { Destination, focusedRef, modalOver, PEEK, Surface, Zone, } from "../domain/index.js";
3
3
  import { composerCopy } from "./copy.js";
4
+ import { ModalLayer } from "./Modal.js";
4
5
  import { WorkspacePalette } from "./Palette.js";
5
6
  import { PanelHost } from "./PanelHost.js";
6
7
  import { ChromeButton, ConfirmDialog, PeekDrawer } from "./Peek.js";
7
8
  import { resolveSkin, SkinProvider, } from "./skin.js";
8
9
  import { ComposerStyles } from "./styles.js";
9
10
  import { ViewHost } from "./ViewHost.js";
10
- import { createApiFactory } from "../state/api.js";
11
+ import { createApiFactory, targetOf } from "../state/api.js";
11
12
  import { useDropMonitor } from "../state/drag.js";
12
13
  import { useKeyboard } from "../state/useKeyboard.js";
13
14
  import { useWorkspaceState } from "../state/useWorkspace.js";
@@ -69,20 +70,17 @@ export function Composer({ workspace, registry, empty, keyboard = true, defaultO
69
70
  workspace.push(ref);
70
71
  }
71
72
  /** An action runs with the API of the surface its resource is on — the page, the peek I am
72
- * reading or a panel — so «audit» can open beside it or navigate it. */
73
+ * reading, a panel or a modal — so «audit» can open beside it or navigate it. */
73
74
  function run(action) {
74
75
  const w = workspace.get();
75
76
  const ref = focusedRef(w);
76
77
  if (ref === null)
77
78
  return;
78
- action.run(api.for(ref, w.focus === PAGE
79
- ? { surface: Surface.Page }
80
- : w.focus === PEEK
81
- ? { surface: Surface.Peek }
82
- : { surface: Surface.Panel, panelId: w.focus }));
79
+ action.run(api.for(ref, targetOf(w.focus)));
83
80
  }
84
81
  const peeked = state.peek;
82
+ const peekModal = modalOver(state, PEEK);
85
83
  const peekSpec = peeked === null ? null : registry.resolve(peeked);
86
84
  const cameFrom = state.peekTrail.at(-1);
87
- return (_jsx(SkinProvider, { value: skin, children: _jsxs("div", { className: "sc-root", children: [skin.styles ? _jsx(ComposerStyles, {}) : null, state.page === null ? (_jsx("div", { className: "sc-empty", children: empty })) : (_jsx(PanelHost, { workspace: state, registry: registry, store: workspace, api: api, overlay: peeked === null ? null : (_jsx("div", { style: { display: "contents" }, onPointerDownCapture: () => workspace.focusPanel(PEEK), children: _jsx(Drawer, { title: api.titleOf(peeked), onClose: workspace.closePeek, actions: _jsxs(_Fragment, { children: [_jsx(ChromeButton, { onClick: () => workspace.peekToSide(peekSpec?.preferredZone ?? Zone.Right), children: copy.peek.openAsPanel }), cameFrom === undefined ? null : (_jsx(ChromeButton, { role: "ghost", icon: skin.icons.back, onClick: workspace.peekBack, children: copy.peek.back(api.titleOf(cameFrom)) })), _jsx(ChromeButton, { role: "ghost", onClick: workspace.peekToPage, children: copy.peek.openAsPage })] }), children: _jsx(ViewHost, { resource: peeked, registry: registry, api: api.for(peeked, { surface: Surface.Peek }) }) }) })) })), _jsx(Confirm, { open: asking !== null, title: copy.discard.title, detail: asking === null ? "" : copy.discard.detail(asking.names), keep: copy.discard.keep, discard: copy.discard.discard, onAnswer: (ok) => asking?.answer(ok) }), palette ? (_jsx(WorkspacePalette, { registry: registry, focused: focusedRef(state), onOpen: open, onAction: run, onClose: () => setPalette(false) })) : null] }) }));
85
+ return (_jsx(SkinProvider, { value: skin, children: _jsxs("div", { className: "sc-root", children: [skin.styles ? _jsx(ComposerStyles, {}) : null, state.page === null ? (_jsx("div", { className: "sc-empty", children: empty })) : (_jsx(PanelHost, { workspace: state, registry: registry, store: workspace, api: api, overlay: peeked === null ? null : (_jsxs(_Fragment, { children: [_jsx("div", { style: { display: "contents" }, inert: peekModal !== null, onPointerDownCapture: () => workspace.focusPanel(PEEK), children: _jsx(Drawer, { title: api.titleOf(peeked), onClose: workspace.closePeek, actions: _jsxs(_Fragment, { children: [_jsx(ChromeButton, { onClick: () => workspace.peekToSide(peekSpec?.preferredZone ?? Zone.Right), children: copy.peek.openAsPanel }), cameFrom === undefined ? null : (_jsx(ChromeButton, { role: "ghost", icon: skin.icons.back, onClick: workspace.peekBack, children: copy.peek.back(api.titleOf(cameFrom)) })), _jsx(ChromeButton, { role: "ghost", onClick: workspace.peekToPage, children: copy.peek.openAsPage })] }), children: _jsx(ViewHost, { resource: peeked, registry: registry, api: api.for(peeked, { surface: Surface.Peek }) }) }) }), peekModal === null ? null : (_jsx(ModalLayer, { modal: peekModal, registry: registry, store: workspace, api: api }))] })) })), _jsx(Confirm, { open: asking !== null, title: copy.discard.title, detail: asking === null ? "" : copy.discard.detail(asking.names), keep: copy.discard.keep, discard: copy.discard.discard, onAnswer: (ok) => asking?.answer(ok) }), palette ? (_jsx(WorkspacePalette, { registry: registry, focused: focusedRef(state), onOpen: open, onAction: run, onClose: () => setPalette(false) })) : null] }) }));
88
86
  }
@@ -0,0 +1,17 @@
1
+ import { type Modal, type Registry } from "../domain/index.js";
2
+ import { type ModalProps } from "./skin.js";
3
+ import type { ApiFactory } from "../state/api.js";
4
+ import type { WorkspaceStore } from "../state/store.js";
5
+ import { type CSSProperties } from "react";
6
+ export declare function ModalWindow({ title, blur, onClose, children }: ModalProps): import("react").JSX.Element;
7
+ export type ModalLayerProps = {
8
+ modal: Modal;
9
+ registry: Registry;
10
+ store: WorkspaceStore;
11
+ api: ApiFactory;
12
+ /** Geometry only: where the host is, when the layer is not already inside it. */
13
+ style?: CSSProperties;
14
+ };
15
+ /** Where a modal stands: over its host's box, taking the workspace focus when touched. The skin
16
+ * draws what is inside it. */
17
+ export declare function ModalLayer({ modal, registry, store, api, style }: ModalLayerProps): import("react").JSX.Element;
@@ -0,0 +1,75 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { modalId, Surface, } from "../domain/index.js";
3
+ import { composerCopy } from "./copy.js";
4
+ import { useSkin } from "./skin.js";
5
+ import { ViewHost } from "./ViewHost.js";
6
+ import { useEffect, useId, useRef, useState, } from "react";
7
+ /**
8
+ * The composer's own modal: a small window centred over the surface that asked for it. It moves
9
+ * by its title — what is underneath may be what the person needs to read to answer — but never
10
+ * further than its surface: it belongs to it, and leaving it would cover a neighbour that is
11
+ * not blocked. It does not dim the rest of the workspace; that is the point of it.
12
+ */
13
+ /** How much of the window must stay inside its surface, so it can always be grabbed back. */
14
+ const KEEP_VISIBLE = 48;
15
+ /** Follows the pointer until it is released, on `window`: leaving the title does not drop the
16
+ * gesture. */
17
+ function useMoveByTitle(box) {
18
+ const [offset, setOffset] = useState({ x: 0, y: 0 });
19
+ function start(e) {
20
+ const el = box.current;
21
+ const layer = el?.parentElement?.getBoundingClientRect();
22
+ if (el === null || layer === undefined || e.button !== 0)
23
+ return;
24
+ e.preventDefault();
25
+ const from = { x: e.clientX, y: e.clientY };
26
+ const origin = offset;
27
+ const rect = el.getBoundingClientRect();
28
+ /* Where the window is with no offset, so the limits are absolute and not cumulative. */
29
+ const base = { left: rect.left - origin.x, top: rect.top - origin.y };
30
+ const onMove = (ev) => {
31
+ const left = base.left + origin.x + ev.clientX - from.x;
32
+ const top = base.top + origin.y + ev.clientY - from.y;
33
+ const x = Math.max(layer.left - rect.width + KEEP_VISIBLE, Math.min(left, layer.right - KEEP_VISIBLE));
34
+ const y = Math.max(layer.top, Math.min(top, layer.bottom - KEEP_VISIBLE));
35
+ setOffset({ x: x - base.left, y: y - base.top });
36
+ };
37
+ const stop = () => {
38
+ window.removeEventListener("pointermove", onMove);
39
+ window.removeEventListener("pointerup", stop);
40
+ window.removeEventListener("pointercancel", stop);
41
+ };
42
+ window.addEventListener("pointermove", onMove);
43
+ window.addEventListener("pointerup", stop);
44
+ window.addEventListener("pointercancel", stop);
45
+ }
46
+ return { offset, start };
47
+ }
48
+ export function ModalWindow({ title, blur, onClose, children }) {
49
+ const copy = composerCopy().modal;
50
+ const { close: CloseIcon } = useSkin().icons;
51
+ const box = useRef(null);
52
+ const titleId = useId();
53
+ const { offset, start } = useMoveByTitle(box);
54
+ useEffect(() => {
55
+ const opener = document.activeElement;
56
+ box.current?.focus();
57
+ return () => {
58
+ if (opener instanceof HTMLElement && opener.isConnected)
59
+ opener.focus();
60
+ };
61
+ }, []);
62
+ return (_jsx("div", { className: "sc-modal-scrim", ...(blur ? { "data-blur": "" } : {}), children: _jsxs("section", { ref: box, role: "dialog", tabIndex: -1, "aria-labelledby": titleId, className: "sc-modal", style: { transform: `translate(${offset.x}px, ${offset.y}px)` }, onKeyDown: (e) => {
63
+ if (e.key !== "Escape" || e.defaultPrevented)
64
+ return;
65
+ e.preventDefault();
66
+ onClose();
67
+ }, children: [_jsxs("header", { className: "sc-modal-head", onPointerDown: start, children: [_jsx("h2", { id: titleId, className: "sc-modal-title", children: title }), _jsx("button", { type: "button", className: "sc-control", "aria-label": copy.close, title: copy.close, onPointerDown: (e) => e.stopPropagation(), onClick: onClose, children: _jsx(CloseIcon, {}) })] }), _jsx("div", { className: "sc-modal-body", children: children })] }) }));
68
+ }
69
+ /** Where a modal stands: over its host's box, taking the workspace focus when touched. The skin
70
+ * draws what is inside it. */
71
+ export function ModalLayer({ modal, registry, store, api, style }) {
72
+ const Window = useSkin().Modal ?? ModalWindow;
73
+ const { host, view } = modal;
74
+ return (_jsx("div", { className: "sc-modal-layer", ...(style === undefined ? {} : { style }), onPointerDownCapture: () => store.focusPanel(modalId(host)), children: _jsx(Window, { title: api.titleOf(view), blur: modal.blur, onClose: () => store.closeModal(host), children: _jsx(ViewHost, { resource: view, registry: registry, api: api.for(view, { surface: Surface.Modal, host }) }) }) }));
75
+ }
@@ -31,8 +31,11 @@ export type PanelFrameProps = {
31
31
  onFocus: () => void;
32
32
  /** Pointer down on the title of a window: the host moves it. */
33
33
  onMoveStart?: (e: ReactPointerEvent) => void;
34
+ /** A modal over this panel's view. It blocks the view only: the header still moves, minimizes
35
+ * and closes the panel. */
36
+ modal?: ReactNode;
34
37
  children: ReactNode;
35
38
  };
36
- declare function Frame({ title, actions, zone, maximized, collapsed, rail, focused, dragId, onMaximize, onFocus, onMoveStart, children, }: PanelFrameProps): import("react").JSX.Element;
39
+ declare function Frame({ title, actions, zone, maximized, collapsed, rail, focused, dragId, onMaximize, onFocus, onMoveStart, modal, children, }: PanelFrameProps): import("react").JSX.Element;
37
40
  export declare const PanelFrame: import("react").MemoExoticComponent<typeof Frame>;
38
41
  export {};
@@ -58,13 +58,13 @@ function MoveMenu({ zone, onMove }) {
58
58
  onMove(z);
59
59
  }, children: [_jsx(Icon, {}), label, _jsx("span", { className: "sc-menu-hint", children: hint })] }, z)))] })) : null] }));
60
60
  }
61
- function Frame({ title, actions, zone, maximized, collapsed, rail = false, focused, dragId, onMaximize, onFocus, onMoveStart, children, }) {
61
+ function Frame({ title, actions, zone, maximized, collapsed, rail = false, focused, dragId, onMaximize, onFocus, onMoveStart, modal, children, }) {
62
62
  const copy = composerCopy().panel;
63
63
  const icons = useSkin().icons;
64
64
  const header = useRef(null);
65
65
  const floating = zone === Zone.Floating;
66
66
  const dragging = useDraggablePanel(header, dragId ?? "", dragId !== undefined && !floating);
67
67
  const flag = (on) => (on ? "" : undefined);
68
- return (_jsxs("section", { role: "region", "aria-label": title, onPointerDownCapture: onFocus, className: "sc-frame", "data-focused": flag(focused), "data-floating": flag(floating), "data-dragging": flag(dragging), children: [rail ? (_jsxs("header", { ref: header, className: "sc-header", "data-rail": "", children: [_jsx(Control, { icon: icons.minimize, label: copy.restore, active: true, onClick: actions.onCollapse }), _jsx("span", { className: "sc-title", children: title }), _jsx(Control, { icon: icons.close, label: copy.close, danger: true, onClick: actions.onClose })] })) : (_jsxs("header", { ref: header, className: "sc-header", "data-floating": flag(floating), onPointerDown: floating ? onMoveStart : undefined, children: [_jsx("span", { className: "sc-title", children: title }), _jsx(MoveMenu, { zone: zone, onMove: actions.onMove }), _jsx(Control, { icon: icons.expand, label: copy.expand, onClick: actions.onExpand }), _jsx(Control, { icon: icons.minimize, label: collapsed ? copy.restore : copy.minimize, active: collapsed, onClick: actions.onCollapse }), _jsx(Control, { icon: maximized ? icons.restore : icons.maximize, label: maximized ? copy.restore : copy.enlarge, active: maximized, onClick: onMaximize }), _jsx(Control, { icon: icons.close, label: copy.close, danger: true, onClick: actions.onClose })] })), _jsx("div", { hidden: collapsed, className: "sc-body", children: children })] }));
68
+ return (_jsxs("section", { role: "region", "aria-label": title, onPointerDownCapture: onFocus, className: "sc-frame", "data-focused": flag(focused), "data-floating": flag(floating), "data-dragging": flag(dragging), children: [rail ? (_jsxs("header", { ref: header, className: "sc-header", "data-rail": "", children: [_jsx(Control, { icon: icons.minimize, label: copy.restore, active: true, onClick: actions.onCollapse }), _jsx("span", { className: "sc-title", children: title }), _jsx(Control, { icon: icons.close, label: copy.close, danger: true, onClick: actions.onClose })] })) : (_jsxs("header", { ref: header, className: "sc-header", "data-floating": flag(floating), onPointerDown: floating ? onMoveStart : undefined, children: [_jsx("span", { className: "sc-title", children: title }), _jsx(MoveMenu, { zone: zone, onMove: actions.onMove }), _jsx(Control, { icon: icons.expand, label: copy.expand, onClick: actions.onExpand }), _jsx(Control, { icon: icons.minimize, label: collapsed ? copy.restore : copy.minimize, active: collapsed, onClick: actions.onCollapse }), _jsx(Control, { icon: maximized ? icons.restore : icons.maximize, label: maximized ? copy.restore : copy.enlarge, active: maximized, onClick: onMaximize }), _jsx(Control, { icon: icons.close, label: copy.close, danger: true, onClick: actions.onClose })] })), _jsxs("div", { hidden: collapsed, className: "sc-body-wrap", children: [_jsx("div", { inert: modal !== undefined && modal !== null, className: "sc-body", children: children }), modal] })] }));
69
69
  }
70
70
  export const PanelFrame = memo(Frame);
@@ -1,10 +1,11 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { Axis, HandleKind, handles, KEYBOARD_STEP, layout, PAGE, sizeAt, stableOrder, Surface, Zone, } from "../domain/index.js";
2
+ import { Axis, HandleKind, handles, KEYBOARD_STEP, layout, modalOver, PAGE, sizeAt, stableOrder, Surface, Zone, } from "../domain/index.js";
3
3
  import { composerCopy } from "./copy.js";
4
+ import { ModalLayer } from "./Modal.js";
4
5
  import { PanelFrame } from "./PanelFrame.js";
5
6
  import { ViewHost } from "./ViewHost.js";
6
7
  import { useDropZone, usePanelDragArmed } from "../state/drag.js";
7
- import { useCallback, useRef, } from "react";
8
+ import { Fragment, useCallback, useRef, } from "react";
8
9
  const HANDLE_THICKNESS = 9;
9
10
  /** A window never gets smaller than this: below it the controls overlap. */
10
11
  const MIN_WINDOW = { w: 280, h: 160 };
@@ -185,11 +186,14 @@ export function PanelHost({ workspace, overlay, registry, store, api }) {
185
186
  ...boxStyle(slot.box),
186
187
  ...(slot.floating ? { zIndex: 20 + slot.z } : {}),
187
188
  };
189
+ const modal = modalOver(workspace, slot.id);
190
+ /* The page has no frame to hold its modal: it stands beside it, over the same box, and
191
+ the page underneath is inert. */
188
192
  if (isPage) {
189
- return (_jsx("div", { hidden: !slot.visible, style: style, onPointerDownCapture: () => store.focusPanel(PAGE), className: "sc-slot", "data-page": "", children: _jsx(ViewHost, { resource: slot.view, registry: registry, api: api.for(slot.view, { surface: Surface.Page }) }) }, slot.id));
193
+ return (_jsxs(Fragment, { children: [_jsx("div", { hidden: !slot.visible, inert: modal !== null, style: style, onPointerDownCapture: () => store.focusPanel(PAGE), className: "sc-slot", "data-page": "", children: _jsx(ViewHost, { resource: slot.view, registry: registry, api: api.for(slot.view, { surface: Surface.Page }) }) }), modal === null || !slot.visible ? null : (_jsx(ModalLayer, { modal: modal, registry: registry, store: store, api: api, style: boxStyle(slot.box) }))] }, slot.id));
190
194
  }
191
195
  const zone = slot.panel?.placement.zone ?? Zone.Right;
192
- return (_jsxs("div", { hidden: !slot.visible, style: style, className: "sc-slot", "data-pad": slotPadding(slot), children: [_jsx(PanelFrame, { title: api.titleOf(slot.view), zone: zone, collapsed: slot.collapsed, rail: slot.rail, focused: workspace.focus === slot.id, maximized: workspace.maximized === slot.id, ...(slot.floating ? {} : { dragId: slot.id }), onMaximize: () => store.maximize(slot.id), onFocus: () => store.focusPanel(slot.id), onMoveStart: (e) => moveWindow(e, slot), actions: {
196
+ return (_jsxs("div", { hidden: !slot.visible, style: style, className: "sc-slot", "data-pad": slotPadding(slot), children: [_jsx(PanelFrame, { title: api.titleOf(slot.view), zone: zone, collapsed: slot.collapsed, rail: slot.rail, focused: workspace.focus === slot.id, maximized: workspace.maximized === slot.id, ...(slot.floating ? {} : { dragId: slot.id }), onMaximize: () => store.maximize(slot.id), onFocus: () => store.focusPanel(slot.id), onMoveStart: (e) => moveWindow(e, slot), modal: modal === null ? null : (_jsx(ModalLayer, { modal: modal, registry: registry, store: store, api: api })), actions: {
193
197
  onMove: (z) => store.movePanel(slot.id, z),
194
198
  onCollapse: () => store.collapsePanel(slot.id),
195
199
  onExpand: () => store.expandPanel(slot.id),
@@ -32,6 +32,9 @@ export type ComposerCopy = {
32
32
  close: string;
33
33
  back: (to: string) => string;
34
34
  };
35
+ modal: {
36
+ close: string;
37
+ };
35
38
  discard: {
36
39
  title: string;
37
40
  detail: (names: readonly string[]) => string;
@@ -32,6 +32,7 @@ export const ENGLISH_COMPOSER_COPY = {
32
32
  close: "Close the preview",
33
33
  back: (to) => `Back to ${to}`,
34
34
  },
35
+ modal: { close: "Close" },
35
36
  discard: {
36
37
  title: "Discard the changes?",
37
38
  detail: (names) => `What was typed in ${names.join(", ")} has not been saved.`,
@@ -57,8 +58,8 @@ export const ENGLISH_COMPOSER_COPY = {
57
58
  { keys: "⌥←", action: "one page back, or one step back in the peek" },
58
59
  { keys: "⌘⌥[ / ⌘⌥]", action: "move focus between the page and the panels" },
59
60
  { keys: "⌘⇧⏎", action: "maximize the focused surface, or restore it" },
60
- { keys: "⌘⇧⌫", action: "close the focused panel or the peek" },
61
- { keys: "Esc", action: "close the peek, or restore the maximized view" },
61
+ { keys: "⌘⇧⌫", action: "close the focused panel, modal or the peek" },
62
+ { keys: "Esc", action: "close the modal or the peek, or restore the maximized view" },
62
63
  { keys: "← → on a handle", action: "resize without the mouse" },
63
64
  ],
64
65
  };
@@ -91,6 +92,7 @@ export const SPANISH_COMPOSER_COPY = {
91
92
  close: "Cerrar la vista previa",
92
93
  back: (to) => `Volver a ${to}`,
93
94
  },
95
+ modal: { close: "Cerrar" },
94
96
  discard: {
95
97
  title: "¿Descartar los cambios?",
96
98
  detail: (names) => `Lo escrito en ${names.join(", ")} no se guardó.`,
@@ -116,8 +118,8 @@ export const SPANISH_COMPOSER_COPY = {
116
118
  { keys: "⌥←", action: "una página atrás, o un paso atrás en el vistazo" },
117
119
  { keys: "⌘⌥[ / ⌘⌥]", action: "mover el foco entre la página y los paneles" },
118
120
  { keys: "⌘⇧⏎", action: "maximizar la superficie con foco, o restaurarla" },
119
- { keys: "⌘⇧⌫", action: "cerrar el panel con foco o el vistazo" },
120
- { keys: "Esc", action: "cerrar el vistazo, o restaurar la vista maximizada" },
121
+ { keys: "⌘⇧⌫", action: "cerrar el panel o el modal con foco, o el vistazo" },
122
+ { keys: "Esc", action: "cerrar el modal o el vistazo, o restaurar la vista maximizada" },
121
123
  { keys: "← → en un divisor", action: "redimensionar sin el mouse" },
122
124
  ],
123
125
  };
@@ -8,6 +8,9 @@ import type { ComponentType, ReactNode } from "react";
8
8
  *
9
9
  * <Composer skin={{ icons: { close: X, more: Ellipsis }, Peek: MyDrawer }} … />
10
10
  *
11
+ * An icon passed here is drawn at the composer's size (`--sc-icon`, 14px), whatever size it
12
+ * draws itself at: a 24px icon library does not inflate the controls.
13
+ *
11
14
  * Three levels, from least to most work: the `--sc-*` variables (colors, radius), these pieces,
12
15
  * and `styles: false` to drop the default sheet and style the `sc-*` classes from scratch.
13
16
  */
@@ -36,6 +39,20 @@ export type PeekProps = {
36
39
  actions?: ReactNode;
37
40
  children: ReactNode;
38
41
  };
42
+ /**
43
+ * A modal over ONE surface: it covers that surface — the page, a window, a side panel or the
44
+ * peek — and nothing else, so the rest of the workspace keeps answering. The composer places it
45
+ * and blocks what is underneath; this draws the scrim and the window. It must take the focus on
46
+ * open, give it back on close, and close on Escape while the focus is inside — claiming the key
47
+ * with `preventDefault`. The default one moves by its title.
48
+ */
49
+ export type ModalProps = {
50
+ title: string;
51
+ /** Blur what it covers. Off unless the view that opened it asked. */
52
+ blur: boolean;
53
+ onClose: () => void;
54
+ children: ReactNode;
55
+ };
39
56
  /** The question before throwing away what was typed. `onAnswer(false)` is the safe answer and
40
57
  * what Escape gives. */
41
58
  export type ConfirmProps = {
@@ -56,6 +73,7 @@ export type NoticeProps = {
56
73
  export type Skin = {
57
74
  icons: SkinIcons;
58
75
  Peek: ComponentType<PeekProps> | null;
76
+ Modal: ComponentType<ModalProps> | null;
59
77
  Confirm: ComponentType<ConfirmProps> | null;
60
78
  Notice: ComponentType<NoticeProps> | null;
61
79
  /** `false` drops the default sheet: the `sc-*` classes are then yours to style. */
@@ -20,6 +20,7 @@ export const DEFAULT_ICONS = {
20
20
  const DEFAULT_SKIN = {
21
21
  icons: DEFAULT_ICONS,
22
22
  Peek: null,
23
+ Modal: null,
23
24
  Confirm: null,
24
25
  Notice: null,
25
26
  styles: true,
@@ -1,5 +1,5 @@
1
1
  /**
2
- * The composer's own skin: the frames, the drawer, the rail, the dialog and ⌘K, with no design
2
+ * The composer's own skin: the frames, the drawer, the modal, the rail, the dialog and ⌘K, with no design
3
3
  * system behind it. It is the minimum that makes the windows usable — the views inside them are
4
4
  * the application's, drawn with whatever it uses.
5
5
  *
@@ -1,6 +1,6 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
2
  /**
3
- * The composer's own skin: the frames, the drawer, the rail, the dialog and ⌘K, with no design
3
+ * The composer's own skin: the frames, the drawer, the modal, the rail, the dialog and ⌘K, with no design
4
4
  * system behind it. It is the minimum that makes the windows usable — the views inside them are
5
5
  * the application's, drawn with whatever it uses.
6
6
  *
@@ -33,6 +33,10 @@ const CSS = `
33
33
  --_radius-control: var(--sc-radius-control, 6px);
34
34
  --_text: var(--sc-text, 13px);
35
35
  --_text-small: var(--sc-text-small, 12px);
36
+ /* Every glyph the composer places — its own or the application's — is drawn at this size. */
37
+ --_icon: var(--sc-icon, 14px);
38
+ --_modal-scrim: var(--sc-modal-scrim, rgb(0 0 0 / 0.14));
39
+ --_modal-blur: var(--sc-modal-blur, 3px);
36
40
  --_tint: color-mix(in srgb, var(--_accent) 10%, transparent);
37
41
  --_hover: color-mix(in srgb, var(--_ink) 7%, transparent);
38
42
 
@@ -47,6 +51,10 @@ const CSS = `
47
51
  }
48
52
  .sc-root *, .sc-root *::before, .sc-root *::after { box-sizing: border-box; }
49
53
  .sc-root :focus-visible { outline: 2px solid var(--_accent); outline-offset: 1px; }
54
+ .sc-root :is(.sc-control, .sc-button, .sc-menu-item, .sc-palette-search, .sc-option-icon) svg {
55
+ flex-shrink: 0; width: var(--_icon); height: var(--_icon);
56
+ }
57
+ .sc-root .sc-link-icons .sc-control svg { width: calc(var(--_icon) - 2px); height: calc(var(--_icon) - 2px); }
50
58
 
51
59
  .sc-empty { display: flex; flex: 1; min-height: 0; align-items: center; justify-content: center; padding: 32px; }
52
60
  .sc-host { position: relative; flex: 1; min-height: 0; overflow: hidden; }
@@ -79,6 +87,7 @@ const CSS = `
79
87
  font-size: var(--_text-small); font-weight: 500;
80
88
  }
81
89
  .sc-header[data-rail] .sc-title { min-height: 0; padding: 4px 0; writing-mode: vertical-rl; }
90
+ .sc-body-wrap { position: relative; display: flex; flex: 1; flex-direction: column; min-height: 0; }
82
91
  .sc-body { flex: 1; min-height: 0; overflow: auto; container-type: inline-size; }
83
92
 
84
93
  .sc-control {
@@ -143,6 +152,29 @@ const CSS = `
143
152
  .sc-peek-actions { display: flex; flex-shrink: 0; flex-wrap: wrap; gap: 6px; padding: 6px 12px; border-bottom: 1px solid var(--_line); }
144
153
  .sc-peek-body { flex: 1; min-height: 0; overflow: auto; padding: 12px; container-type: inline-size; }
145
154
 
155
+ .sc-modal-layer { position: absolute; inset: 0; z-index: 1; }
156
+ .sc-overlay > .sc-modal-layer { z-index: 31; }
157
+ .sc-modal-scrim {
158
+ position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
159
+ padding: 12px; overflow: hidden; background: var(--_modal-scrim);
160
+ }
161
+ .sc-modal-scrim[data-blur] { backdrop-filter: blur(var(--_modal-blur)); }
162
+ .sc-modal {
163
+ display: flex; flex-direction: column; width: min(28rem, 100%); max-height: 100%;
164
+ overflow: hidden; background: var(--_surface); border: 1px solid var(--_line-strong);
165
+ border-radius: var(--_radius); box-shadow: var(--_shadow); outline: 0;
166
+ }
167
+ .sc-modal-head {
168
+ display: flex; flex-shrink: 0; align-items: center; gap: 8px; height: 34px; padding: 0 3px 0 12px;
169
+ background: var(--_ground); border-bottom: 1px solid var(--_line);
170
+ cursor: move; user-select: none; touch-action: none;
171
+ }
172
+ .sc-modal-title {
173
+ flex: 1; min-width: 0; margin: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
174
+ font-size: var(--_text-small); font-weight: 600;
175
+ }
176
+ .sc-modal-body { flex: 1; min-height: 0; overflow: auto; container-type: inline-size; }
177
+
146
178
  .sc-button {
147
179
  display: inline-flex; align-items: center; gap: 6px; height: 28px; padding: 0 10px;
148
180
  border: 1px solid var(--_line-strong); border-radius: var(--_radius-control);
@@ -17,7 +17,12 @@ export type Target = {
17
17
  panelId: string;
18
18
  } | {
19
19
  surface: typeof Surface.Peek;
20
+ } | {
21
+ surface: typeof Surface.Modal;
22
+ host: string;
20
23
  };
24
+ /** The other way: the target of a surface the workspace knows by `id` — the focus, say. */
25
+ export declare function targetOf(id: string): Target;
21
26
  export type ApiFactory = {
22
27
  for: (resource: ResourceRef, target: Target) => WorkspaceApi;
23
28
  /** Zone to open into when nobody asks: the one the domain prefers. */
package/dist/state/api.js CHANGED
@@ -1,12 +1,25 @@
1
1
  import * as model from "../domain/index.js";
2
2
  import { Destination, formatRef, PAGE, PEEK, Surface, Zone, } from "../domain/index.js";
3
- /** The id the workspace knows the surface by: `PAGE`, `PEEK` or the panel id. */
3
+ /** The id the workspace knows the surface by: `PAGE`, `PEEK`, the panel id or `modal:<host>`. */
4
4
  const surfaceId = (target) => target.surface === Surface.Panel
5
5
  ? target.panelId
6
6
  : target.surface === Surface.Peek
7
7
  ? PEEK
8
- : PAGE;
9
- /** A panel's frame already says what it shows. One array, so it reads as «unchanged». */
8
+ : target.surface === Surface.Modal
9
+ ? model.modalId(target.host)
10
+ : PAGE;
11
+ /** The other way: the target of a surface the workspace knows by `id` — the focus, say. */
12
+ export function targetOf(id) {
13
+ if (id === PAGE)
14
+ return { surface: Surface.Page };
15
+ if (id === PEEK)
16
+ return { surface: Surface.Peek };
17
+ if (id.startsWith(model.MODAL))
18
+ return { surface: Surface.Modal, host: model.hostOf(id) };
19
+ return { surface: Surface.Panel, panelId: id };
20
+ }
21
+ /** A panel's or a modal's frame already says what it shows. One array, so it reads as
22
+ * «unchanged». */
10
23
  const NO_CRUMBS = [];
11
24
  export function createApiFactory(store, { registry, defaultOpen = Destination.Page } = {}) {
12
25
  const cache = new Map();
@@ -32,13 +45,18 @@ export function createApiFactory(store, { registry, defaultOpen = Destination.Pa
32
45
  function build(resource, target) {
33
46
  const me = surfaceId(target);
34
47
  const inPeek = target.surface === Surface.Peek;
48
+ const inModal = target.surface === Surface.Modal;
35
49
  /** Still showing what this API was lent for. */
36
50
  const here = () => {
37
51
  const now = model.refOn(store.get(), me);
38
52
  return now !== null && model.sameRef(now, resource);
39
53
  };
40
- function open(ref, to) {
41
- if (to === Destination.Peek) {
54
+ /** In a modal, its blur stays what it was opened with when its view changes. */
55
+ const blurNow = () => model.modalOver(store.get(), model.hostOf(me))?.blur ?? false;
56
+ function open(ref, to, blur = false) {
57
+ if (to === Destination.Modal)
58
+ store.openModal(me, ref, { blur });
59
+ else if (to === Destination.Peek) {
42
60
  if (inPeek)
43
61
  store.drillPeek(ref);
44
62
  else
@@ -54,6 +72,8 @@ export function createApiFactory(store, { registry, defaultOpen = Destination.Pa
54
72
  function replace(ref) {
55
73
  if (target.surface === Surface.Panel)
56
74
  store.navigatePanel(target.panelId, ref);
75
+ else if (inModal)
76
+ store.openModal(me, ref, { blur: blurNow() });
57
77
  else if (inPeek)
58
78
  store.replacePeek(ref);
59
79
  else
@@ -85,7 +105,7 @@ export function createApiFactory(store, { registry, defaultOpen = Destination.Pa
85
105
  * equal labels on an equal trail are an equal breadcrumb. */
86
106
  let last = null;
87
107
  function crumbs() {
88
- if (target.surface === Surface.Panel)
108
+ if (target.surface === Surface.Panel || inModal)
89
109
  return NO_CRUMBS;
90
110
  const next = freshCrumbs();
91
111
  const key = `${store.get().trail.length}\u0000${next.map((c) => c.label).join("\u0000")}`;
@@ -97,12 +117,15 @@ export function createApiFactory(store, { registry, defaultOpen = Destination.Pa
97
117
  return {
98
118
  self: resource,
99
119
  surface: target.surface,
120
+ over: inModal ? (model.modalOver(store.get(), target.host)?.over ?? null) : null,
100
121
  context,
101
122
  open: (ref, options) => open(ref, options?.to ??
102
- (inPeek && defaultOpen === Destination.Page ? Destination.Peek : defaultOpen)),
123
+ (inPeek && defaultOpen === Destination.Page ? Destination.Peek : defaultOpen), options?.blur),
103
124
  navigate: (to) => {
104
125
  if (target.surface === Surface.Panel)
105
126
  store.navigatePanel(target.panelId, to);
127
+ else if (inModal)
128
+ replace(to);
106
129
  else if (inPeek)
107
130
  store.drillPeek(to);
108
131
  else
@@ -130,6 +153,8 @@ export function createApiFactory(store, { registry, defaultOpen = Destination.Pa
130
153
  close: () => {
131
154
  if (target.surface === Surface.Panel)
132
155
  store.closePanel(target.panelId);
156
+ else if (inModal)
157
+ store.closeModal(me);
133
158
  else if (inPeek)
134
159
  store.closePeek();
135
160
  else
@@ -145,6 +170,11 @@ export function createApiFactory(store, { registry, defaultOpen = Destination.Pa
145
170
  select: (refs) => store.apply((w) => model.select(w, me, refs)),
146
171
  pick: (ref, onPick, options) => {
147
172
  const to = options?.to ?? Destination.Window;
173
+ if (to === Destination.Modal) {
174
+ open(ref, to, options?.blur);
175
+ choosers.set(model.modalId(model.hostOf(me)), onPick);
176
+ return;
177
+ }
148
178
  if (to === Destination.Peek) {
149
179
  store.peek(ref);
150
180
  choosers.set(PEEK, onPick);
@@ -162,7 +192,9 @@ export function createApiFactory(store, { registry, defaultOpen = Destination.Pa
162
192
  /* Forget it BEFORE closing, so closing is not mistaken for anything else. */
163
193
  choosers.delete(me);
164
194
  onPick(value);
165
- if (inPeek)
195
+ if (inModal)
196
+ store.closeModal(me);
197
+ else if (inPeek)
166
198
  store.closePeek();
167
199
  else if (target.surface === Surface.Panel)
168
200
  store.closePanel(target.panelId);
@@ -1,4 +1,4 @@
1
- import type { Dock, OpenPanelOptions, ResourceRef, WindowBox, Workspace, Zone } from "../domain/index.js";
1
+ import type { Dock, OpenModalOptions, OpenPanelOptions, ResourceRef, WindowBox, Workspace, Zone } from "../domain/index.js";
2
2
  /**
3
3
  * The pure reducers already are the state handling; this only binds them to the browser. An
4
4
  * external store, not `useState`: with state in the component every action recreated the API
@@ -47,6 +47,10 @@ export type WorkspaceStore = {
47
47
  closePeek: () => void;
48
48
  peekToPage: () => void;
49
49
  peekToSide: (zone?: Zone) => void;
50
+ /** `view` over `host` (`PAGE`, `PEEK`, a panel id — or a modal's id, to replace it), blocking
51
+ * only that surface. */
52
+ openModal: (host: string, view: ResourceRef, options?: OpenModalOptions) => void;
53
+ closeModal: (host: string) => void;
50
54
  /** The name a view gives `ref` (see `api.setTitle`). */
51
55
  setTitle: (ref: ResourceRef, title: string | null) => void;
52
56
  /** `surface` (`PAGE`, `PEEK` or a panel id) has unsaved changes for `ref`. Ignored if it no
@@ -87,7 +87,7 @@ export function createWorkspaceStore({ initial = model.EMPTY, hash = false, onCh
87
87
  /** Runs `change`, asking first if it would throw away something unsaved. After a «yes» it
88
88
  * runs again on the state of THEN — the answer may have taken a while. */
89
89
  function run(change, mode) {
90
- const next = change(state);
90
+ const next = model.settleModals(change(state));
91
91
  if (next === state)
92
92
  return;
93
93
  const lost = lostIn(next);
@@ -182,6 +182,8 @@ export function createWorkspaceStore({ initial = model.EMPTY, hash = false, onCh
182
182
  closePeek: () => go(model.closePeek),
183
183
  peekToPage: () => go(model.peekToPage),
184
184
  peekToSide: (zone) => go((w) => model.peekToSide(w, zone)),
185
+ openModal: (host, view, options) => go((w) => model.openModal(w, host, view, options), History.Replace),
186
+ closeModal: (host) => go((w) => model.closeModal(w, host), History.Replace),
185
187
  setTitle: (ref, title) => go((w) => model.nameRef(w, ref, title), History.Replace),
186
188
  setDirty: (surface, ref, on) => {
187
189
  const shown = model.refOn(state, surface);
@@ -1,4 +1,4 @@
1
- import { PAGE, PEEK } from "../domain/index.js";
1
+ import { MODAL, PAGE, PEEK } from "../domain/index.js";
2
2
  import { useEffect } from "react";
3
3
  /** Inside a field only Escape survives. Stealing a key from someone who is typing is worse than
4
4
  * having no shortcuts. */
@@ -52,6 +52,8 @@ export function useKeyboard({ workspace, enabled = true, onPalette }) {
52
52
  else if (mod && e.shiftKey && e.code === "Backspace" && state.focus !== PAGE) {
53
53
  if (state.focus === PEEK)
54
54
  workspace.closePeek();
55
+ else if (state.focus.startsWith(MODAL))
56
+ workspace.closeModal(state.focus);
55
57
  else
56
58
  workspace.closePanel(state.focus);
57
59
  e.preventDefault();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sincpro/web-composer",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "The Sincpro workspace for React: one page with its breadcrumb, a peek, side panels and windows, and ⌘K — all over references, never data.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",