@sincpro/web-composer 1.5.0 → 1.6.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
@@ -252,6 +252,26 @@ useViewTool(api, {
252
252
  The agent is one more person at the desk: it opens through the same `open`, a phone still turns
253
253
  a window into the page, and throwing away what was typed still asks first.
254
254
 
255
+ ### When a view breaks
256
+
257
+ Each view draws inside its own boundary: a view that throws while drawing shows a notice in its
258
+ panel and the rest of the workspace goes on. `onViewError` tells the application, once per
259
+ failure, with the reference the view was opened with — hand it to the error reporter the use
260
+ cases report to:
261
+
262
+ ```tsx
263
+ <Composer
264
+ workspace={workspace}
265
+ registry={registry}
266
+ // @sincpro/client-framework's reportError, or the application's own reporter
267
+ onViewError={(error, { resource }) => reportError(error, `view ${formatRef(resource)}`)}
268
+ />
269
+ ```
270
+
271
+ A host drawn outside `Composer` (`PanelHost`, `ViewHost`) reads the same handler from
272
+ `ViewErrorProvider`. A handler that throws is ignored: telling about a failure never becomes a
273
+ second one.
274
+
255
275
  ### Testing a view
256
276
 
257
277
  A view talks to the workspace only through its `api`, so a test checks what it ASKED for — no
package/dist/index.d.ts CHANGED
@@ -18,7 +18,7 @@ export { PanelHost, type PanelHostProps } from "./shell/PanelHost.js";
18
18
  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
- export { ViewHost, type ViewHostProps } from "./shell/ViewHost.js";
21
+ export { type OnViewError, type ViewErrorAbout, ViewErrorProvider, ViewHost, type ViewHostProps, } from "./shell/ViewHost.js";
22
22
  export { agentAvailable, type AgentTool, type AgentToolAnnotations, registerAgentTool, registerAgentTools, toolName, useViewTool, workspaceTools, type WorkspaceToolsOptions, } from "./state/agent.js";
23
23
  export { type ApiFactory, createApiFactory, type Target, targetOf, } from "./state/api.js";
24
24
  export { type ConfirmDiscard, createWorkspaceStore, type StoreOptions, type WorkspaceStore, } from "./state/store.js";
package/dist/index.js CHANGED
@@ -17,7 +17,7 @@ export { PanelHost } from "./shell/PanelHost.js";
17
17
  export { RecordLink } from "./shell/RecordLink.js";
18
18
  export { DEFAULT_ICONS, } from "./shell/skin.js";
19
19
  export { ComposerStyles } from "./shell/styles.js";
20
- export { ViewHost } from "./shell/ViewHost.js";
20
+ export { ViewErrorProvider, ViewHost, } from "./shell/ViewHost.js";
21
21
  export { agentAvailable, registerAgentTool, registerAgentTools, toolName, useViewTool, workspaceTools, } from "./state/agent.js";
22
22
  export { createApiFactory, targetOf, } from "./state/api.js";
23
23
  export { createWorkspaceStore, } from "./state/store.js";
@@ -1,5 +1,6 @@
1
1
  import { Destination, type Registry } from "../domain/index.js";
2
2
  import { type ComposerSkin } from "./skin.js";
3
+ import { type OnViewError } from "./ViewHost.js";
3
4
  import type { WorkspaceStore } from "../state/store.js";
4
5
  import { type ReactNode } from "react";
5
6
  export type ComposerProps = {
@@ -25,5 +26,8 @@ export type ComposerProps = {
25
26
  /** Offer the workspace to the browser's agent (WebMCP): where am I, open, search, act. Off by
26
27
  * default; without WebMCP in the browser it does nothing. One workspace per page should. */
27
28
  agentTools?: boolean;
29
+ /** Told when a view breaks while drawing — hand it to the app's error reporter. Its panel
30
+ * shows a notice and the rest of the workspace goes on either way. */
31
+ onViewError?: OnViewError;
28
32
  };
29
- export declare function Composer({ workspace, registry, empty, keyboard, defaultOpen, palette: paletteProp, onPaletteChange, skin: skinProp, phoneBelow, agentTools, }: ComposerProps): import("react").JSX.Element;
33
+ export declare function Composer({ workspace, registry, empty, keyboard, defaultOpen, palette: paletteProp, onPaletteChange, skin: skinProp, phoneBelow, agentTools, onViewError, }: ComposerProps): import("react").JSX.Element;
@@ -7,7 +7,7 @@ import { PanelHost } from "./PanelHost.js";
7
7
  import { ChromeButton, ConfirmDialog, PeekDrawer } from "./Peek.js";
8
8
  import { resolveSkin, SkinProvider, } from "./skin.js";
9
9
  import { ComposerStyles } from "./styles.js";
10
- import { ViewHost } from "./ViewHost.js";
10
+ import { ViewErrorProvider, ViewHost, } from "./ViewHost.js";
11
11
  import { registerAgentTools, workspaceTools } from "../state/agent.js";
12
12
  import { createApiFactory, targetOf } from "../state/api.js";
13
13
  import { useDropMonitor } from "../state/drag.js";
@@ -61,7 +61,7 @@ function PhoneDock({ panels, titleOf, onBring, }) {
61
61
  const copy = composerCopy().phone;
62
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
63
  }
64
- export function Composer({ workspace, registry, empty, keyboard = true, defaultOpen = Destination.Page, palette: paletteProp, onPaletteChange, skin: skinProp, phoneBelow = PHONE_WIDTH, agentTools = false, }) {
64
+ export function Composer({ workspace, registry, empty, keyboard = true, defaultOpen = Destination.Page, palette: paletteProp, onPaletteChange, skin: skinProp, phoneBelow = PHONE_WIDTH, agentTools = false, onViewError, }) {
65
65
  const skin = useMemo(() => resolveSkin(skinProp), [skinProp]);
66
66
  const Drawer = skin.Peek ?? PeekDrawer;
67
67
  const Confirm = skin.Confirm ?? ConfirmDialog;
@@ -140,5 +140,6 @@ export function Composer({ workspace, registry, empty, keyboard = true, defaultO
140
140
  const peekModal = modalOver(state, PEEK);
141
141
  const peekSpec = peeked === null ? null : registry.resolve(peeked);
142
142
  const cameFrom = state.peekTrail.at(-1);
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] }) }));
143
+ const desk = (_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] }));
144
+ return (_jsx(SkinProvider, { value: skin, children: onViewError === undefined ? (desk) : (_jsx(ViewErrorProvider, { value: onViewError, children: desk })) }));
144
145
  }
@@ -1,5 +1,21 @@
1
1
  import { type Registry, type ResourceRef, type WorkspaceApi } from "../domain/index.js";
2
2
  import { type ReactNode } from "react";
3
+ /** Where a view failed: the reference it was opened with, and React's stack of components. */
4
+ export type ViewErrorAbout = {
5
+ resource: ResourceRef;
6
+ componentStack: string | undefined;
7
+ };
8
+ /**
9
+ * Told when a view breaks while drawing — once per failure, after the panel shows its notice.
10
+ *
11
+ * Context: the boundary keeps the rest of the workspace alive, but a console line is nobody's
12
+ * report: the application hands this to its error reporter (GlitchTip, Sentry), the same place
13
+ * its use cases report to. Whatever it does, it never breaks the workspace — a handler that
14
+ * throws is ignored.
15
+ */
16
+ export type OnViewError = (error: Error, about: ViewErrorAbout) => void;
17
+ /** `Composer onViewError` sets it for every view it hosts; a host of its own sets it here. */
18
+ export declare const ViewErrorProvider: import("react").Provider<OnViewError | undefined>;
3
19
  export type ViewHostProps = {
4
20
  resource: ResourceRef;
5
21
  registry: Registry;
@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { formatRef, loadView, rootRef, } from "../domain/index.js";
3
3
  import { composerCopy } from "./copy.js";
4
4
  import { useSkin } from "./skin.js";
5
- import { Component, lazy, memo, Suspense, useMemo, } from "react";
5
+ import { Component, createContext, lazy, memo, Suspense, useContext, useMemo, } from "react";
6
6
  /**
7
7
  * The only thing that turns a reference into pixels. Resolves against the
8
8
  * registry, isolates failure, and lends the navigation API — the view never
@@ -20,6 +20,9 @@ import { Component, lazy, memo, Suspense, useMemo, } from "react";
20
20
  function DefaultNotice({ heading, detail, bad = false }) {
21
21
  return (_jsxs("div", { role: "status", className: "sc-notice", ...(bad ? { "data-tone": "bad" } : {}), children: [_jsx("strong", { children: heading }), _jsx("code", { children: detail })] }));
22
22
  }
23
+ const ViewErrorContext = createContext(undefined);
24
+ /** `Composer onViewError` sets it for every view it hosts; a host of its own sets it here. */
25
+ export const ViewErrorProvider = ViewErrorContext.Provider;
23
26
  class ErrorBoundary extends Component {
24
27
  state = { error: null };
25
28
  static getDerivedStateFromError(error) {
@@ -27,6 +30,15 @@ class ErrorBoundary extends Component {
27
30
  }
28
31
  componentDidCatch(error, info) {
29
32
  console.error(`[view ${this.props.name}] failed to render`, error, info.componentStack);
33
+ try {
34
+ this.props.onError?.(error, {
35
+ resource: this.props.resource,
36
+ componentStack: info.componentStack ?? undefined,
37
+ });
38
+ }
39
+ catch {
40
+ // Telling someone about a failure never becomes a second one.
41
+ }
30
42
  }
31
43
  componentDidUpdate(prev) {
32
44
  if (prev.name !== this.props.name && this.state.error !== null) {
@@ -44,10 +56,11 @@ function Host({ resource, registry, api, fallback }) {
44
56
  const key = formatRef(resource);
45
57
  const spec = registry.resolve(resource);
46
58
  const Notice = useSkin().Notice ?? DefaultNotice;
59
+ const onError = useContext(ViewErrorContext);
47
60
  const View = useMemo(() => (spec === null ? null : lazy(async () => ({ default: await loadView(spec) }))), [spec]);
48
61
  if (spec === null || View === null) {
49
62
  return (_jsx(Notice, { heading: composerCopy().view.unresolved, detail: `${key} — is the «${resource.domain}» domain missing from the registry?` }));
50
63
  }
51
- return (_jsx(ErrorBoundary, { name: key, Notice: Notice, children: _jsx(Suspense, { fallback: fallback ?? _jsx("p", { className: "sc-loading", children: composerCopy().view.loading(spec.domain) }), children: _jsx(View, { resource: resource, api: api }, formatRef(rootRef(resource))) }) }));
64
+ return (_jsx(ErrorBoundary, { name: key, resource: resource, Notice: Notice, onError: onError, children: _jsx(Suspense, { fallback: fallback ?? _jsx("p", { className: "sc-loading", children: composerCopy().view.loading(spec.domain) }), children: _jsx(View, { resource: resource, api: api }, formatRef(rootRef(resource))) }) }));
52
65
  }
53
66
  export const ViewHost = memo(Host);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sincpro/web-composer",
3
- "version": "1.5.0",
3
+ "version": "1.6.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",