@sincpro/web-composer 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -93,7 +93,7 @@ api.open(ref); // the page — inside the peek, a step IN the drawer
93
93
  api.open(ref, { to: "peek" }); // or "window", or "side"
94
94
  api.replace(ref); // show it HERE without a step back: the record a form just created
95
95
  api.setParams({ tenant }); // a filter that lives in the reference: survives reload and links
96
- api.crumbs(); // the breadcrumb, ready for List.Crumbs / Record.Crumbs
96
+ useCrumbs(api); // the breadcrumb, ready for List.Crumbs / Record.Crumbs — follows setTitle
97
97
  api.back(); // one step back: the page's breadcrumb, or the peek's own trail
98
98
  api.close(); // leave: closes the panel or the peek; on the page, goes back — «Cancel» anywhere
99
99
  api.expand(); // a window, a side panel or the peek grows into the page
@@ -164,14 +164,15 @@ Write a view — it receives its reference and the API, nothing else. It is draw
164
164
  your app uses; here, web-ui:
165
165
 
166
166
  ```tsx
167
- import { RecordLink, type ViewProps } from "@sincpro/web-composer";
167
+ import { RecordLink, useCrumbs, type ViewProps } from "@sincpro/web-composer";
168
168
  import { List } from "@sincpro/web-ui";
169
169
 
170
170
  export function Entries({ api }: ViewProps) {
171
+ const crumbs = useCrumbs(api);
171
172
  return (
172
173
  <List items={entries} keyOf={(e) => e.id} onOpen={(e) => api.open(entryRef(e.id))}>
173
174
  <List.Bar>
174
- <List.Crumbs crumbs={api.crumbs()} />
175
+ <List.Crumbs crumbs={crumbs} />
175
176
  </List.Bar>
176
177
  <List.Table
177
178
  columns={[
@@ -55,6 +55,9 @@ export type WorkspaceApi = {
55
55
  * The way here, ready for `List.Crumbs` / `Record.Crumbs`: the pages before, each a link, and
56
56
  * this one. In the peek the page's crumbs leave the drawer and its own steps stay in it. Empty
57
57
  * in a panel: its frame already says what it shows.
58
+ *
59
+ * What it is NOW, and the same array until it changes. A view draws it with `useCrumbs(api)`,
60
+ * which follows it: read during render, a name given later (`setTitle`) would not show.
58
61
  */
59
62
  crumbs: () => readonly Crumb[];
60
63
  /** The name this resource goes by once loaded — the crumbs, the frame and the peek show it
package/dist/index.d.ts CHANGED
@@ -21,4 +21,4 @@ export { ViewHost, type ViewHostProps } from "./shell/ViewHost.js";
21
21
  export { type ApiFactory, createApiFactory, type Target, } from "./state/api.js";
22
22
  export { type ConfirmDiscard, createWorkspaceStore, type StoreOptions, type WorkspaceStore, } from "./state/store.js";
23
23
  export { useKeyboard, type UseKeyboardOptions, } from "./state/useKeyboard.js";
24
- export { useWorkspace, useWorkspaceContext, useWorkspaceSlice, useWorkspaceState, } from "./state/useWorkspace.js";
24
+ export { useCrumbs, useWorkspace, useWorkspaceContext, useWorkspaceSlice, useWorkspaceState, } from "./state/useWorkspace.js";
package/dist/index.js CHANGED
@@ -20,4 +20,4 @@ export { ViewHost } from "./shell/ViewHost.js";
20
20
  export { createApiFactory, } from "./state/api.js";
21
21
  export { createWorkspaceStore, } from "./state/store.js";
22
22
  export { useKeyboard, } from "./state/useKeyboard.js";
23
- export { useWorkspace, useWorkspaceContext, useWorkspaceSlice, useWorkspaceState, } from "./state/useWorkspace.js";
23
+ export { useCrumbs, useWorkspace, useWorkspaceContext, useWorkspaceSlice, useWorkspaceState, } from "./state/useWorkspace.js";
package/dist/state/api.js CHANGED
@@ -6,6 +6,8 @@ const surfaceId = (target) => target.surface === Surface.Panel
6
6
  : target.surface === Surface.Peek
7
7
  ? PEEK
8
8
  : PAGE;
9
+ /** A panel's frame already says what it shows. One array, so it reads as «unchanged». */
10
+ const NO_CRUMBS = [];
9
11
  export function createApiFactory(store, { registry, defaultOpen = Destination.Page } = {}) {
10
12
  const cache = new Map();
11
13
  const choosers = new Map();
@@ -59,7 +61,7 @@ export function createApiFactory(store, { registry, defaultOpen = Destination.Pa
59
61
  }
60
62
  /** In the peek the page's crumbs leave the drawer — a crumb is the page — and its own steps
61
63
  * stay in it. */
62
- function crumbs() {
64
+ function freshCrumbs() {
63
65
  const w = store.get();
64
66
  const page = w.page ?? resource;
65
67
  const pageCrumbs = w.trail.map((past, i) => ({
@@ -78,6 +80,20 @@ export function createApiFactory(store, { registry, defaultOpen = Destination.Pa
78
80
  { label: titleOf(w.peek ?? resource) },
79
81
  ];
80
82
  }
83
+ /** The SAME array until a label or the length of the trail changes: `useCrumbs` subscribes
84
+ * with it, and a new array per read would redraw forever. The links are by position, so
85
+ * equal labels on an equal trail are an equal breadcrumb. */
86
+ let last = null;
87
+ function crumbs() {
88
+ if (target.surface === Surface.Panel)
89
+ return NO_CRUMBS;
90
+ const next = freshCrumbs();
91
+ const key = `${store.get().trail.length}\u0000${next.map((c) => c.label).join("\u0000")}`;
92
+ if (last?.key === key)
93
+ return last.crumbs;
94
+ last = { key, crumbs: next };
95
+ return next;
96
+ }
81
97
  return {
82
98
  self: resource,
83
99
  surface: target.surface,
@@ -120,7 +136,7 @@ export function createApiFactory(store, { registry, defaultOpen = Destination.Pa
120
136
  store.back();
121
137
  },
122
138
  focus: () => store.focusPanel(me),
123
- crumbs: () => (target.surface === Surface.Panel ? [] : crumbs()),
139
+ crumbs,
124
140
  setTitle: (title) => {
125
141
  if (here())
126
142
  store.setTitle(resource, title);
@@ -1,4 +1,4 @@
1
- import type { Workspace, WorkspaceApi } from "../domain/index.js";
1
+ import type { Crumb, Workspace, WorkspaceApi } from "../domain/index.js";
2
2
  import { type StoreOptions, type WorkspaceStore } from "./store.js";
3
3
  /**
4
4
  * `useSyncExternalStore` is React, not a state library. What it adds over
@@ -20,4 +20,8 @@ export declare function useWorkspaceContext(api: WorkspaceApi): {
20
20
  focused: import("../domain/index.js").ResourceRef | null;
21
21
  selection: readonly import("../domain/index.js").ResourceRef[];
22
22
  };
23
+ /** The breadcrumb that FOLLOWS the workspace: a name a view gives later (`setTitle`) redraws
24
+ * it. `api.crumbs()` read during render is what it was then — nothing redraws a view when a
25
+ * title changes, and the API it holds stays the same object on purpose. */
26
+ export declare function useCrumbs(api: WorkspaceApi): readonly Crumb[];
23
27
  export type { StoreOptions as UseWorkspaceOptions, WorkspaceStore };
@@ -32,3 +32,9 @@ export function useWorkspaceContext(api) {
32
32
  selection: useSyncExternalStore(subscribe, selection, selection),
33
33
  };
34
34
  }
35
+ /** The breadcrumb that FOLLOWS the workspace: a name a view gives later (`setTitle`) redraws
36
+ * it. `api.crumbs()` read during render is what it was then — nothing redraws a view when a
37
+ * title changes, and the API it holds stays the same object on purpose. */
38
+ export function useCrumbs(api) {
39
+ return useSyncExternalStore(api.context.subscribe, api.crumbs, api.crumbs);
40
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sincpro/web-composer",
3
- "version": "1.0.0",
3
+ "version": "1.1.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",