@sincpro/web-composer 1.2.0 → 1.4.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
@@ -93,6 +93,7 @@ A view opens anything with one call and lets the workspace decide the rest:
93
93
  api.open(ref); // the page — inside the peek, a step IN the drawer
94
94
  api.open(ref, { to: "peek" }); // or "window", or "side"
95
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
96
97
  api.over; // in a modal: the record it was opened over — its context (null elsewhere)
97
98
  api.replace(ref); // show it HERE without a step back: the record a form just created
98
99
  api.setParams({ tenant }); // a filter that lives in the reference: survives reload and links
@@ -106,6 +107,8 @@ api.select(refs); // publish what this view has selected
106
107
  api.context; // read what the user is on and what is selected — references only
107
108
  api.pick(ref, onPick); // open a chooser (a many2one search); its view calls api.answer(ref)
108
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)
111
+ api.pick<boolean>(confirmRef, (ok) => ok && post(), { to: "modal" }); // any value, not only a ref
109
112
  ```
110
113
 
111
114
  A **modal** belongs to the surface it covers — the page, a window, a side panel or the peek —
@@ -116,6 +119,13 @@ with it (asking first if something was typed). What it shares with whoever opene
116
119
  its reference (`params`) and comes back with `api.answer`; `api.over` says what it covers. No
117
120
  blur unless asked.
118
121
 
122
+ **On a phone** — when the workspace is narrower than 640 px (`<Composer phoneBelow>`, `0` never)
123
+ — it is one screen, and the views change nothing: the page takes it all; a window or a side
124
+ panel opens as the page, with its crumb to come back; a chooser opens as a sheet from the bottom,
125
+ so the form that asked stays to receive the answer; the peek is the screen's width. Panels that
126
+ were already open wait in «Also open», mounted, and one tap brings each to the page. Widen it and
127
+ the desk is back as it was.
128
+
119
129
  From the app, around the workspace: `workspace.start(ref)` starts over from a menu (no
120
130
  breadcrumb behind, no peek, the panels stay), and `useWorkspace({ hash: true })` puts the
121
131
  workspace in the URL with the browser's Back working. Unsaved changes are asked with the
@@ -130,6 +140,7 @@ The same gesture means the same thing on every screen:
130
140
  | A row of a list | click | **page**, with breadcrumb |
131
141
  | A record's name INSIDE the peek | click | a step **in the peek**; ← comes back |
132
142
  | The record's name in a column (`RecordLink`) | hover icons, Space, ⇧, ⌘ | **peek**, **side**, **window** |
143
+ | A record's name inside a card that drags (kanban) | `draggable={false}` | the card drags; the name only clicks |
133
144
  | A many2one field | open · search | **window** · a **modal** that **answers** |
134
145
  | A short task on a record (register a payment) | click | **modal** over that record |
135
146
  | A record's buttons that _lead_ (see its items) | click | **side** |
@@ -211,6 +222,42 @@ entries, journal items, bank reconciliation, a form with relations, an audit whe
211
222
  follows the selection, ⌘K, the keyboard, what happens when something fails, and your own
212
223
  design over the composer.
213
224
 
225
+ ### An agent in the browser (WebMCP)
226
+
227
+ [WebMCP](https://webmachinelearning.github.io/webmcp/) lets a page offer **tools** to the agent
228
+ built into the browser (`document.modelContext.registerTool`; a W3C Community Group draft, in
229
+ Chrome behind an origin trial). Everything is feature-detected: without it nothing happens.
230
+
231
+ ```tsx
232
+ <Composer workspace={workspace} registry={registry} agentTools />;
233
+ // workspace.where · workspace.open · workspace.search · workspace.act (the ⌘K actions)
234
+
235
+ // a view offers what ITS screen can do, alive while the view is:
236
+ useViewTool(api, {
237
+ name: "register_payment", // offered as register_payment.invoice-F-1: the record it acts on
238
+ description: "Open the form to register this invoice's payment",
239
+ execute: () => api.open(paymentRef(invoice.id), { to: "modal" }),
240
+ });
241
+ ```
242
+
243
+ The agent is one more person at the desk: it opens through the same `open`, a phone still turns
244
+ a window into the page, and throwing away what was typed still asks first.
245
+
246
+ ### Testing a view
247
+
248
+ A view talks to the workspace only through its `api`, so a test checks what it ASKED for — no
249
+ store, no shell, no browser:
250
+
251
+ ```ts
252
+ import { createTestApi } from "@sincpro/web-composer";
253
+
254
+ const t = createTestApi(invoiceRef("F-1")); // { surface, over, crumbs, selection } optional
255
+ render(<Invoice resource={t.api.self} api={t.api} />);
256
+ // … click «Register payment»
257
+ expect(t.callsTo("open")[0].args).toEqual([paymentRef("F-1"), { to: "modal" }]);
258
+ t.respond(true); // answers the last chooser it opened, as its view would
259
+ ```
260
+
214
261
  ## Your design over it
215
262
 
216
263
  ### Colors
@@ -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, 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";
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, 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
+ 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
  /**
@@ -12,12 +13,17 @@ export type OpenOptions = {
12
13
  /** A modal only: blur what it covers. Off by default — the surface underneath is blocked,
13
14
  * not hidden. */
14
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;
15
19
  };
16
20
  export type PickOptions = {
17
21
  /** Where the chooser opens. A window unless said otherwise. */
18
22
  to?: typeof Destination.Peek | typeof Destination.Window | typeof Destination.Side | typeof Destination.Modal;
19
23
  /** A modal only: blur what it covers. */
20
24
  blur?: boolean;
25
+ /** A window or a modal: the size the chooser opens at, in pixels. */
26
+ size?: Size;
21
27
  };
22
28
  /** One step of a breadcrumb, ready for `List.Crumbs` or `Record.Crumbs`. */
23
29
  export type Crumb = {
@@ -91,11 +97,18 @@ export type WorkspaceApi = {
91
97
  selection: () => readonly ResourceRef[];
92
98
  subscribe: (listener: () => void) => () => void;
93
99
  };
94
- /** Open `ref` as a chooser: when its view calls `answer`, `onPick` receives the value and
95
- * the chooser closes. */
96
- pick: (ref: ResourceRef, onPick: (value: ResourceRef) => void, options?: PickOptions) => void;
97
- /** From a chooser: deliver the value to whoever asked, and close this surface. */
98
- answer: (value: ResourceRef) => void;
100
+ /**
101
+ * Open `ref` as a chooser: when its view calls `answer`, `onPick` receives the value and the
102
+ * chooser closes. The value is a reference by default — a many2one — but it can be anything
103
+ * the chooser's view answers: `true` for a confirmation, a date range, an amount. Closed
104
+ * without an answer, `onPick` is never called.
105
+ *
106
+ * api.pick<boolean>(confirmRef, (ok) => ok && post(), { to: Destination.Modal });
107
+ */
108
+ pick: <T = ResourceRef>(ref: ResourceRef, onPick: (value: T) => void, options?: PickOptions) => void;
109
+ /** From a chooser: deliver the value to whoever asked, and close this surface. Nobody asked
110
+ * (it was opened with `open`, not `pick`): nothing happens. */
111
+ answer: (value: unknown) => void;
99
112
  };
100
113
  /** Named `resource` rather than `ref` because `ref` is a reserved React prop. */
101
114
  export type ViewProps = {
@@ -51,6 +51,13 @@ export type Modal = {
51
51
  view: ResourceRef;
52
52
  /** Blur what it covers. Off unless asked: the host is blocked, not hidden. */
53
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;
54
61
  };
55
62
  /** What a selection belongs to, and the references selected. */
56
63
  export type Selected = {
@@ -94,6 +101,8 @@ export declare const DEFAULT_ZONES: Zones;
94
101
  export declare const MIN_ZONE = 0.12;
95
102
  export declare const MAX_ZONE = 0.72;
96
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;
97
106
  export declare const EMPTY: Workspace;
98
107
  export declare const findPanel: (w: Workspace, id: string) => Panel | null;
99
108
  /** What a surface shows now — the page, the peek, a panel or a modal — or `null` if it is not
@@ -124,6 +133,8 @@ export type OpenPanelOptions = {
124
133
  /** Deduplicating is the right default for a column and the wrong one for «the same table
125
134
  * with two filters». */
126
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;
127
138
  };
128
139
  /** Opens a resource as a panel. If it is already open it moves it to the requested zone and
129
140
  * focuses it, unless a duplicate is explicitly asked for. */
@@ -185,13 +196,14 @@ export declare function peekToPage(w: Workspace): Workspace;
185
196
  export declare function peekToSide(w: Workspace, zone?: Zone): Workspace;
186
197
  export type OpenModalOptions = {
187
198
  blur?: boolean;
199
+ size?: Size;
188
200
  };
189
201
  /**
190
202
  * `view` over `host`, which keeps its place and its state underneath. Asked from inside a
191
203
  * modal, it replaces that one: same host, no stacking. It takes the focus, so the shortcuts and
192
204
  * ⌘K talk to it.
193
205
  */
194
- export declare function openModal(w: Workspace, host: string, view: ResourceRef, { blur }?: OpenModalOptions): Workspace;
206
+ export declare function openModal(w: Workspace, host: string, view: ResourceRef, { blur, size }?: OpenModalOptions): Workspace;
195
207
  /** Closes the modal over `host` (or the modal itself, by its id). The focus goes back to the
196
208
  * surface it covered. */
197
209
  export declare function closeModal(w: Workspace, host: string): Workspace;
@@ -21,6 +21,8 @@ export const MIN_ZONE = 0.12;
21
21
  export const MAX_ZONE = 0.72;
22
22
  export const MIN_SHARE = 0.12;
23
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 };
24
26
  const WINDOW_OFFSET = 28;
25
27
  export const EMPTY = {
26
28
  page: null,
@@ -90,7 +92,7 @@ const normalizeAll = (panels) => DOCKS.reduce((acc, zone) => normalize(acc, zone
90
92
  function topZ(panels) {
91
93
  return panels.reduce((max, p) => (p.placement.zone === Zone.Floating ? Math.max(max, p.placement.z) : max), 0);
92
94
  }
93
- function placementFor(zone, panels) {
95
+ function placementFor(zone, panels, size) {
94
96
  if (zone !== Zone.Floating)
95
97
  return { zone, share: 1 };
96
98
  const floating = panels.filter((p) => p.placement.zone === Zone.Floating).length;
@@ -98,8 +100,8 @@ function placementFor(zone, panels) {
98
100
  zone,
99
101
  x: WINDOW_BOX.x + floating * WINDOW_OFFSET,
100
102
  y: WINDOW_BOX.y + floating * WINDOW_OFFSET,
101
- w: WINDOW_BOX.w,
102
- 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),
103
105
  z: topZ(panels) + 1,
104
106
  };
105
107
  }
@@ -168,11 +170,19 @@ export function openPanel(w, view, options = {}) {
168
170
  const zone = opts.zone ?? Zone.Right;
169
171
  if (opts.allowDuplicate !== true) {
170
172
  const existing = w.panels.find((p) => sameRef(p.view, view));
171
- if (existing)
172
- 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
+ }
173
183
  }
174
184
  const id = nextId(w.panels.map((p) => p.id));
175
- const panel = { id, view, placement: placementFor(zone, w.panels) };
185
+ const panel = { id, view, placement: placementFor(zone, w.panels, opts.size) };
176
186
  return focusPanel({ ...w, panels: normalizeAll([...w.panels, panel]) }, id);
177
187
  }
178
188
  export function movePanel(w, id, zone) {
@@ -361,18 +371,22 @@ export function peekToSide(w, zone = Zone.Right) {
361
371
  * modal, it replaces that one: same host, no stacking. It takes the focus, so the shortcuts and
362
372
  * ⌘K talk to it.
363
373
  */
364
- export function openModal(w, host, view, { blur = false } = {}) {
374
+ export function openModal(w, host, view, { blur = false, size } = {}) {
365
375
  const under = hostOf(host);
366
376
  const over = refOn(w, under);
367
377
  if (over === null)
368
378
  return w;
369
379
  const id = modalId(under);
370
380
  const current = modalOver(w, under);
371
- if (current !== null && sameRef(current.view, view) && current.blur === blur)
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)
372
386
  return focusPanel(w, id);
373
387
  const modals = [
374
388
  ...w.modals.filter((m) => m.host !== under && modalOver(w, m.host) !== null),
375
- { host: under, over, view, blur },
389
+ { host: under, over, view, blur, ...(size === undefined ? {} : { size }) },
376
390
  ];
377
391
  return { ...w, modals, focus: id, selected: dropSelection(w, id) };
378
392
  }
package/dist/index.d.ts CHANGED
@@ -19,7 +19,9 @@ export { RecordLink, type RecordLinkProps } from "./shell/RecordLink.js";
19
19
  export { type ComposerSkin, type ConfirmProps, DEFAULT_ICONS, type ModalProps, type NoticeProps, type PeekProps, type SkinIcons, } from "./shell/skin.js";
20
20
  export { ComposerStyles } from "./shell/styles.js";
21
21
  export { ViewHost, type ViewHostProps } from "./shell/ViewHost.js";
22
+ export { agentAvailable, type AgentTool, type AgentToolAnnotations, registerAgentTool, registerAgentTools, toolName, useViewTool, workspaceTools, type WorkspaceToolsOptions, } from "./state/agent.js";
22
23
  export { type ApiFactory, createApiFactory, type Target, targetOf, } from "./state/api.js";
23
24
  export { type ConfirmDiscard, createWorkspaceStore, type StoreOptions, type WorkspaceStore, } from "./state/store.js";
25
+ export { type ApiCall, createTestApi, type TestApi, type TestApiOptions, } from "./state/testing.js";
24
26
  export { useKeyboard, type UseKeyboardOptions, } from "./state/useKeyboard.js";
25
27
  export { useCrumbs, useWorkspace, useWorkspaceContext, useWorkspaceSlice, useWorkspaceState, } from "./state/useWorkspace.js";
package/dist/index.js CHANGED
@@ -18,7 +18,9 @@ export { RecordLink } from "./shell/RecordLink.js";
18
18
  export { DEFAULT_ICONS, } from "./shell/skin.js";
19
19
  export { ComposerStyles } from "./shell/styles.js";
20
20
  export { ViewHost } from "./shell/ViewHost.js";
21
+ export { agentAvailable, registerAgentTool, registerAgentTools, toolName, useViewTool, workspaceTools, } from "./state/agent.js";
21
22
  export { createApiFactory, targetOf, } from "./state/api.js";
22
23
  export { createWorkspaceStore, } from "./state/store.js";
24
+ export { createTestApi, } from "./state/testing.js";
23
25
  export { useKeyboard, } from "./state/useKeyboard.js";
24
26
  export { useCrumbs, useWorkspace, useWorkspaceContext, useWorkspaceSlice, useWorkspaceState, } from "./state/useWorkspace.js";
@@ -19,5 +19,11 @@ export type ComposerProps = {
19
19
  /** Your design over the composer: icons, the peek drawer, the confirm dialog, the notice, or
20
20
  * `styles: false` to drop the default sheet. What is not passed keeps the default. */
21
21
  skin?: ComposerSkin;
22
+ /** Below this width (px) of the WORKSPACE it behaves as a phone: one screen, windows and side
23
+ * panels open as the page, choosers as a sheet (`domain/phone.ts`). `0` never does. */
24
+ phoneBelow?: number;
25
+ /** Offer the workspace to the browser's agent (WebMCP): where am I, open, search, act. Off by
26
+ * default; without WebMCP in the browser it does nothing. One workspace per page should. */
27
+ agentTools?: boolean;
22
28
  };
23
- export declare function Composer({ workspace, registry, empty, keyboard, defaultOpen, palette: paletteProp, onPaletteChange, skin: skinProp, }: ComposerProps): import("react").JSX.Element;
29
+ export declare function Composer({ workspace, registry, empty, keyboard, defaultOpen, palette: paletteProp, onPaletteChange, skin: skinProp, phoneBelow, agentTools, }: ComposerProps): import("react").JSX.Element;
@@ -1,5 +1,5 @@
1
- import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { Destination, focusedRef, modalOver, PEEK, Surface, Zone, } from "../domain/index.js";
1
+ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
+ import { Destination, destinationOnPhone, focusedRef, modalOver, PEEK, PHONE_WIDTH, Surface, Zone, } from "../domain/index.js";
3
3
  import { composerCopy } from "./copy.js";
4
4
  import { ModalLayer } from "./Modal.js";
5
5
  import { WorkspacePalette } from "./Palette.js";
@@ -8,11 +8,12 @@ import { ChromeButton, ConfirmDialog, PeekDrawer } from "./Peek.js";
8
8
  import { resolveSkin, SkinProvider, } from "./skin.js";
9
9
  import { ComposerStyles } from "./styles.js";
10
10
  import { ViewHost } from "./ViewHost.js";
11
+ import { registerAgentTools, workspaceTools } from "../state/agent.js";
11
12
  import { createApiFactory, targetOf } from "../state/api.js";
12
13
  import { useDropMonitor } from "../state/drag.js";
13
14
  import { useKeyboard } from "../state/useKeyboard.js";
14
15
  import { useWorkspaceState } from "../state/useWorkspace.js";
15
- import { useCallback, useEffect, useMemo, useState } from "react";
16
+ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
16
17
  /**
17
18
  * The question before throwing away what someone typed, drawn with the design system. The store
18
19
  * calls it; a `confirmDiscard` given to the store replaces it.
@@ -31,7 +32,36 @@ function useDiscardDialog(workspace, titleOf) {
31
32
  }, [workspace, titleOf]);
32
33
  return asking;
33
34
  }
34
- export function Composer({ workspace, registry, empty, keyboard = true, defaultOpen = Destination.Page, palette: paletteProp, onPaletteChange, skin: skinProp, }) {
35
+ /**
36
+ * Whether the workspace is a phone, measured BEFORE paint: measuring after it drew the desk for a
37
+ * frame and swapped it, and a click in that frame landed on a panel that was going away. A
38
+ * workspace with no width yet (hidden, or not laid out) is not a phone.
39
+ */
40
+ function usePhone(root, below) {
41
+ const [phone, setPhone] = useState(false);
42
+ useLayoutEffect(() => {
43
+ const el = root.current;
44
+ if (el === null)
45
+ return;
46
+ const measure = (width) => setPhone(width > 0 && width < below);
47
+ measure(el.getBoundingClientRect().width);
48
+ if (typeof ResizeObserver === "undefined")
49
+ return;
50
+ const watch = new ResizeObserver(([entry]) => {
51
+ if (entry !== undefined)
52
+ measure(entry.contentRect.width);
53
+ });
54
+ watch.observe(el);
55
+ return () => watch.disconnect();
56
+ }, [root, below]);
57
+ return phone;
58
+ }
59
+ /** On a phone the panels that were open wait here: one tap brings each to the page. */
60
+ function PhoneDock({ panels, titleOf, onBring, }) {
61
+ const copy = composerCopy().phone;
62
+ return (_jsxs("nav", { "aria-label": copy.alsoOpen, className: "sc-dock", children: [_jsx("span", { className: "sc-dock-label", children: copy.alsoOpen }), panels.map((p) => (_jsx(ChromeButton, { onClick: () => onBring(p.id), children: titleOf(p.view) }, p.id)))] }));
63
+ }
64
+ export function Composer({ workspace, registry, empty, keyboard = true, defaultOpen = Destination.Page, palette: paletteProp, onPaletteChange, skin: skinProp, phoneBelow = PHONE_WIDTH, agentTools = false, }) {
35
65
  const skin = useMemo(() => resolveSkin(skinProp), [skinProp]);
36
66
  const Drawer = skin.Peek ?? PeekDrawer;
37
67
  const Confirm = skin.Confirm ?? ConfirmDialog;
@@ -43,7 +73,18 @@ export function Composer({ workspace, registry, empty, keyboard = true, defaultO
43
73
  setPaletteState(open);
44
74
  onPaletteChange?.(open);
45
75
  }, [onPaletteChange]);
46
- const api = useMemo(() => createApiFactory(workspace, { registry, defaultOpen }), [workspace, registry, defaultOpen]);
76
+ const root = useRef(null);
77
+ const phone = usePhone(root, phoneBelow);
78
+ /* The API reads it at call time: a view's API is not rebuilt when the window is resized. */
79
+ const phoneNow = useRef(phone);
80
+ useLayoutEffect(() => {
81
+ phoneNow.current = phone;
82
+ }, [phone]);
83
+ const api = useMemo(() => createApiFactory(workspace, {
84
+ registry,
85
+ defaultOpen,
86
+ isPhone: () => phoneNow.current,
87
+ }), [workspace, registry, defaultOpen]);
47
88
  useEffect(() => api.dispose, [api]);
48
89
  useKeyboard({
49
90
  workspace,
@@ -57,7 +98,8 @@ export function Composer({ workspace, registry, empty, keyboard = true, defaultO
57
98
  const asking = useDiscardDialog(workspace, api.titleOf);
58
99
  /** Where a chosen search result opens. Without a page yet, the first one becomes it —
59
100
  * whatever was asked: a peek or a window over nothing would be invisible. */
60
- function open(ref, destination) {
101
+ function open(ref, asked) {
102
+ const destination = phone ? destinationOnPhone(asked) : asked;
61
103
  if (workspace.get().page === null)
62
104
  workspace.push(ref);
63
105
  else if (destination === Destination.Peek)
@@ -78,9 +120,25 @@ export function Composer({ workspace, registry, empty, keyboard = true, defaultO
78
120
  return;
79
121
  action.run(api.for(ref, targetOf(w.focus)));
80
122
  }
123
+ /* The tools call the latest `open` and `run`, which close over the current phone state. */
124
+ const latest = useRef({ open, run });
125
+ useLayoutEffect(() => {
126
+ latest.current = { open, run };
127
+ });
128
+ useEffect(() => {
129
+ if (!agentTools)
130
+ return;
131
+ return registerAgentTools(workspaceTools({
132
+ store: workspace,
133
+ registry,
134
+ titleOf: api.titleOf,
135
+ open: (ref, to) => latest.current.open(ref, to),
136
+ run: (action) => latest.current.run(action),
137
+ }));
138
+ }, [agentTools, workspace, registry, api]);
81
139
  const peeked = state.peek;
82
140
  const peekModal = modalOver(state, PEEK);
83
141
  const peekSpec = peeked === null ? null : registry.resolve(peeked);
84
142
  const cameFrom = state.peekTrail.at(-1);
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] }) }));
143
+ return (_jsx(SkinProvider, { value: skin, children: _jsxs("div", { ref: root, className: "sc-root", ...(phone ? { "data-phone": "" } : {}), 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, phone: phone, 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: [phone ? null : (_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, phone: phone }))] })) })), phone && state.page !== null && state.panels.length > 0 ? (_jsx(PhoneDock, { panels: state.panels, titleOf: api.titleOf, onBring: workspace.expandPanel })) : null, _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] }) }));
86
144
  }
@@ -3,7 +3,7 @@ import { type ModalProps } from "./skin.js";
3
3
  import type { ApiFactory } from "../state/api.js";
4
4
  import type { WorkspaceStore } from "../state/store.js";
5
5
  import { type CSSProperties } from "react";
6
- export declare function ModalWindow({ title, blur, onClose, children }: ModalProps): import("react").JSX.Element;
6
+ export declare function ModalWindow({ title, blur, size, phone, onClose, children }: ModalProps): import("react").JSX.Element;
7
7
  export type ModalLayerProps = {
8
8
  modal: Modal;
9
9
  registry: Registry;
@@ -11,7 +11,8 @@ export type ModalLayerProps = {
11
11
  api: ApiFactory;
12
12
  /** Geometry only: where the host is, when the layer is not already inside it. */
13
13
  style?: CSSProperties;
14
+ phone?: boolean;
14
15
  };
15
16
  /** Where a modal stands: over its host's box, taking the workspace focus when touched. The skin
16
17
  * draws what is inside it. */
17
- export declare function ModalLayer({ modal, registry, store, api, style }: ModalLayerProps): import("react").JSX.Element;
18
+ export declare function ModalLayer({ modal, registry, store, api, style, phone, }: ModalLayerProps): import("react").JSX.Element;
@@ -5,7 +5,8 @@ import { useSkin } from "./skin.js";
5
5
  import { ViewHost } from "./ViewHost.js";
6
6
  import { useEffect, useId, useRef, useState, } from "react";
7
7
  /**
8
- * The composer's own modal: a small window centred over the surface that asked for it. It moves
8
+ * The composer's own modal: a small window centred over the surface that asked for it — on a
9
+ * phone, a sheet from the bottom. It moves
9
10
  * by its title — what is underneath may be what the person needs to read to answer — but never
10
11
  * further than its surface: it belongs to it, and leaving it would cover a neighbour that is
11
12
  * not blocked. It does not dim the rest of the workspace; that is the point of it.
@@ -45,7 +46,7 @@ function useMoveByTitle(box) {
45
46
  }
46
47
  return { offset, start };
47
48
  }
48
- export function ModalWindow({ title, blur, onClose, children }) {
49
+ export function ModalWindow({ title, blur, size, phone, onClose, children }) {
49
50
  const copy = composerCopy().modal;
50
51
  const { close: CloseIcon } = useSkin().icons;
51
52
  const box = useRef(null);
@@ -59,17 +60,26 @@ export function ModalWindow({ title, blur, onClose, children }) {
59
60
  opener.focus();
60
61
  };
61
62
  }, []);
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
+ return (_jsx("div", { className: "sc-modal-scrim", ...(blur ? { "data-blur": "" } : {}), ...(phone ? { "data-phone": "" } : {}), children: _jsxs("section", { ref: box, role: "dialog", tabIndex: -1, "aria-labelledby": titleId, className: "sc-modal", style: phone
64
+ ? undefined
65
+ : {
66
+ /* `left`/`top` and not `transform`: a transform makes the modal the box every
67
+ `position: fixed` inside it is placed against — the card a calendar or a kanban
68
+ drags would be drawn off its pointer. */
69
+ left: offset.x,
70
+ top: offset.y,
71
+ ...(size === undefined ? {} : { width: size.w, height: size.h }),
72
+ }, onKeyDown: (e) => {
63
73
  if (e.key !== "Escape" || e.defaultPrevented)
64
74
  return;
65
75
  e.preventDefault();
66
76
  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 })] }) }));
77
+ }, children: [_jsxs("header", { className: "sc-modal-head", onPointerDown: phone ? undefined : 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
78
  }
69
79
  /** Where a modal stands: over its host's box, taking the workspace focus when touched. The skin
70
80
  * draws what is inside it. */
71
- export function ModalLayer({ modal, registry, store, api, style }) {
81
+ export function ModalLayer({ modal, registry, store, api, style, phone = false, }) {
72
82
  const Window = useSkin().Modal ?? ModalWindow;
73
83
  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 }) }) }) }));
84
+ 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, ...(modal.size === undefined ? {} : { size: modal.size }), phone: phone, onClose: () => store.closeModal(host), children: _jsx(ViewHost, { resource: view, registry: registry, api: api.for(view, { surface: Surface.Modal, host }) }) }) }));
75
85
  }
@@ -19,5 +19,7 @@ export type PanelHostProps = {
19
19
  registry: Registry;
20
20
  store: WorkspaceStore;
21
21
  api: ApiFactory;
22
+ /** One screen: the page takes it all, the panels wait hidden, nothing resizes or docks. */
23
+ phone?: boolean;
22
24
  };
23
- export declare function PanelHost({ workspace, overlay, registry, store, api }: PanelHostProps): import("react").JSX.Element;
25
+ export declare function PanelHost({ workspace, overlay, registry, store, api, phone, }: PanelHostProps): import("react").JSX.Element;