@bevel-software/platform-core-frontend 0.27.0 → 0.28.1

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.
Files changed (42) hide show
  1. package/package.json +2 -2
  2. package/src/core/ProductName.tsx +4 -4
  3. package/src/core/__tests__/ProductName.test.tsx +46 -0
  4. package/src/core/maker-url.ts +30 -0
  5. package/src/core/registry.ts +27 -0
  6. package/src/lib/__tests__/latest-request.test.ts +48 -0
  7. package/src/lib/latest-request.ts +45 -0
  8. package/src/modules/access/__tests__/ManageAccessDialog.no-sso-invite.test.tsx +222 -0
  9. package/src/modules/access/api.ts +19 -3
  10. package/src/modules/access/components/ManageAccessDialog.tsx +60 -7
  11. package/src/modules/admin/__tests__/AdminRolesPage.fixed-admin.test.tsx +16 -1
  12. package/src/modules/admin/__tests__/UserAccountsPage.test.tsx +284 -39
  13. package/src/modules/admin/components/AdminRolesPage.tsx +13 -14
  14. package/src/modules/admin/components/UserAccountsPage.tsx +91 -107
  15. package/src/modules/admin/services/roles.api.ts +14 -1
  16. package/src/modules/auth/__tests__/LoginScreen.test.tsx +80 -5
  17. package/src/modules/auth/__tests__/sso-strict-probe.test.ts +66 -0
  18. package/src/modules/auth/components/LoginScreen.tsx +100 -75
  19. package/src/modules/auth/services/account.api.ts +31 -2
  20. package/src/modules/auth/services/sso.ts +29 -8
  21. package/src/modules/auth/state/use-sign-in-methods.ts +41 -0
  22. package/src/modules/onboarding/__tests__/InviteButton.test.tsx +214 -0
  23. package/src/modules/onboarding/__tests__/first-page-prompt.test.ts +56 -1
  24. package/src/modules/onboarding/__tests__/get-started-column.test.tsx +538 -81
  25. package/src/modules/onboarding/__tests__/invite-dialog.test.tsx +543 -124
  26. package/src/modules/onboarding/__tests__/invite-emails.test.ts +247 -0
  27. package/src/modules/onboarding/components/GetStartedColumn.tsx +30 -11
  28. package/src/modules/onboarding/components/InviteButton.tsx +119 -15
  29. package/src/modules/onboarding/components/InviteDialog.tsx +392 -75
  30. package/src/modules/onboarding/first-page-prompt.ts +34 -0
  31. package/src/modules/onboarding/invite-emails.ts +171 -33
  32. package/src/modules/onboarding/state/invite-dialog.context.ts +7 -4
  33. package/src/modules/onboarding/state/invite-dialog.tsx +12 -4
  34. package/src/modules/toolbar/commands/actions.tsx +10 -4
  35. package/src/modules/toolbar/commands/useCommandActions.ts +5 -3
  36. package/src/modules/toolbar/components/AppSwitcher.tsx +19 -0
  37. package/src/modules/toolbar/components/__tests__/AppSwitcher.test.tsx +46 -1
  38. package/src/modules/toolbar/components/__tests__/SearchPalette.test.tsx +34 -2
  39. package/src/modules/workspace/hooks/__tests__/useCreatePage.test.ts +137 -0
  40. package/src/modules/workspace/hooks/__tests__/useKnowledgeWriteTarget.test.ts +302 -0
  41. package/src/modules/workspace/hooks/useCreatePage.ts +118 -28
  42. package/src/modules/workspace/hooks/useKnowledgeWriteTarget.ts +238 -0
@@ -0,0 +1,137 @@
1
+ import { beforeEach, describe, expect, it, vi } from 'vitest';
2
+ import { act, renderHook } from '@testing-library/react';
3
+
4
+ /**
5
+ * New page across a branch switch: a create that was started on one branch
6
+ * and is still waiting when the person switches stops rather than write to
7
+ * the workspace it started on, and a page it had already made is not opened
8
+ * over the branch they moved to.
9
+ */
10
+
11
+ const { state, createFile, openWorkspacePath, recheck } = vi.hoisted(() => ({
12
+ state: {
13
+ workspaceBranch: 'alice/draft' as string | null,
14
+ urlBranch: 'alice/draft' as string | null,
15
+ target: { folder: 'kb/KnowledgeBase' as string | null, settled: true, current: true },
16
+ },
17
+ createFile: vi.fn<(path: string, content: string, opts?: { ifAbsent?: boolean }) => Promise<void>>(),
18
+ openWorkspacePath: vi.fn(),
19
+ recheck: vi.fn<() => Promise<string | null>>(),
20
+ }));
21
+
22
+ vi.mock('react-router-dom', async (importOriginal) => ({
23
+ ...(await importOriginal<typeof import('react-router-dom')>()),
24
+ useLocation: () => ({ pathname: '/anything' }),
25
+ }));
26
+ vi.mock('../../routing/kb-routes', async (importOriginal) => ({
27
+ ...(await importOriginal<typeof import('../../routing/kb-routes')>()),
28
+ branchFromPathname: () => state.urlBranch,
29
+ useFileNav: () => ({ openWorkspacePath }),
30
+ }));
31
+ vi.mock('../../state/workspace.context', async (importOriginal) => ({
32
+ ...(await importOriginal<typeof import('../../state/workspace.context')>()),
33
+ useWorkspace: () => ({ kbDirName: 'kb', createFile, workspaceBranch: state.workspaceBranch }),
34
+ }));
35
+ vi.mock('../useMergedWorkspaceTree', () => ({
36
+ useMergedWorkspaceTree: () => ({ tree: null, suggestionOnlyPaths: new Map(), withheld: 0 }),
37
+ }));
38
+ vi.mock('../useKnowledgeWriteTarget', () => ({
39
+ useKnowledgeWriteTarget: () => ({
40
+ ...state.target,
41
+ recheck,
42
+ // As the hook answers it: the last answer when current, else a recheck.
43
+ resolve: () => (state.target.current ? Promise.resolve(state.target.folder) : recheck()),
44
+ withdraw: vi.fn(),
45
+ }),
46
+ }));
47
+
48
+ import { useCreatePage } from '../useCreatePage';
49
+
50
+ function deferred<T>() {
51
+ let resolve!: (value: T) => void;
52
+ const promise = new Promise<T>((r) => (resolve = r));
53
+ return { promise, resolve };
54
+ }
55
+
56
+ /** The person switches to another branch: the workspace on screen and the URL follow. */
57
+ function switchBranch(rerender: () => void) {
58
+ state.workspaceBranch = 'bob/draft';
59
+ state.urlBranch = 'bob/draft';
60
+ act(() => rerender());
61
+ }
62
+
63
+ beforeEach(() => {
64
+ state.workspaceBranch = 'alice/draft';
65
+ state.urlBranch = 'alice/draft';
66
+ state.target = { folder: 'kb/KnowledgeBase', settled: true, current: true };
67
+ createFile.mockReset().mockResolvedValue(undefined);
68
+ openWorkspacePath.mockReset();
69
+ recheck.mockReset();
70
+ });
71
+
72
+ describe('useCreatePage across a branch switch', () => {
73
+ it('stops after its first recheck when the branch changed meanwhile: nothing is written', async () => {
74
+ // The last answer is from before a page change, so the create asks again first.
75
+ state.target = { folder: 'kb/KnowledgeBase', settled: true, current: false };
76
+ const answer = deferred<string | null>();
77
+ recheck.mockReturnValue(answer.promise);
78
+ const { result, rerender } = renderHook(() => useCreatePage());
79
+
80
+ let created!: Promise<string | null>;
81
+ act(() => {
82
+ created = result.current.createPage();
83
+ });
84
+ switchBranch(rerender);
85
+ answer.resolve('kb/KnowledgeBase');
86
+
87
+ expect(await created).toBeNull();
88
+ expect(createFile).not.toHaveBeenCalled();
89
+ expect(openWorkspacePath).not.toHaveBeenCalled();
90
+ });
91
+
92
+ it('does not open a page it made after the person switched away', async () => {
93
+ const write = deferred<void>();
94
+ createFile.mockReturnValue(write.promise);
95
+ const { result, rerender } = renderHook(() => useCreatePage());
96
+
97
+ let created!: Promise<string | null>;
98
+ act(() => {
99
+ created = result.current.createPage();
100
+ });
101
+ await act(async () => {
102
+ await Promise.resolve();
103
+ });
104
+ expect(createFile).toHaveBeenCalledWith('kb/KnowledgeBase/Untitled.md', expect.any(String), { ifAbsent: true });
105
+ switchBranch(rerender);
106
+ write.resolve();
107
+
108
+ // Made, and its path answered, but not opened over the branch on screen now.
109
+ expect(await created).toBe('kb/KnowledgeBase/Untitled.md');
110
+ expect(openWorkspacePath).not.toHaveBeenCalled();
111
+ });
112
+
113
+ it('writes where the target resolves for the page on screen, not the folder the last answer showed', async () => {
114
+ // The last answer (Sales) is from before a page change; the target
115
+ // resolves for the page on screen now (Support).
116
+ state.target = { folder: 'kb/KnowledgeBase/Sales', settled: true, current: false };
117
+ recheck.mockResolvedValueOnce('kb/KnowledgeBase/Support');
118
+ const { result } = renderHook(() => useCreatePage());
119
+ let created!: Promise<string | null>;
120
+ act(() => {
121
+ created = result.current.createPage();
122
+ });
123
+ expect(await created).toBe('kb/KnowledgeBase/Support/Untitled.md');
124
+ expect(createFile).toHaveBeenCalledTimes(1);
125
+ expect(createFile).toHaveBeenCalledWith('kb/KnowledgeBase/Support/Untitled.md', expect.any(String), { ifAbsent: true });
126
+ });
127
+
128
+ it('opens the page as before when nothing changed', async () => {
129
+ const { result } = renderHook(() => useCreatePage());
130
+ let created!: Promise<string | null>;
131
+ act(() => {
132
+ created = result.current.createPage();
133
+ });
134
+ expect(await created).toBe('kb/KnowledgeBase/Untitled.md');
135
+ expect(openWorkspacePath).toHaveBeenCalledWith('kb/KnowledgeBase/Untitled.md', { edit: true });
136
+ });
137
+ });
@@ -0,0 +1,302 @@
1
+ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
2
+ import { act, renderHook, waitFor } from '@testing-library/react';
3
+ import type { FileTreeEntry } from '@bevel-software/platform-shared';
4
+
5
+ /**
6
+ * Where New page writes, through the hook alone: the top of Knowledge, else
7
+ * the folder on screen, else the first folder the person may write in file
8
+ * tree order — asked of the batch access endpoint (at most 500 paths a call):
9
+ * who may write on a protected branch, who may read on a draft.
10
+ */
11
+
12
+ type Verb = 'write' | 'owner' | 'read';
13
+ const { batch, workspace, merged } = vi.hoisted(() => ({
14
+ batch: vi.fn<(workspaceId: string, paths: string[], verb?: Verb) => Promise<{ results: Record<string, boolean> }>>(),
15
+ workspace: {
16
+ current: {
17
+ workspaceId: 'ws-1',
18
+ workspaceBranch: 'target-company-state' as string | null,
19
+ kbDirName: 'kb',
20
+ openFilePath: null as string | null,
21
+ },
22
+ },
23
+ merged: { tree: null as FileTreeEntry | null },
24
+ }));
25
+ vi.mock('../../../access/api', async (importOriginal) => ({
26
+ ...(await importOriginal<typeof import('../../../access/api')>()),
27
+ fetchFileAccessBatch: batch,
28
+ }));
29
+ vi.mock('../../state/workspace.context', async (importOriginal) => ({
30
+ ...(await importOriginal<typeof import('../../state/workspace.context')>()),
31
+ useWorkspace: () => workspace.current,
32
+ }));
33
+ vi.mock('../useMergedWorkspaceTree', () => ({
34
+ useMergedWorkspaceTree: () => ({ tree: merged.tree, suggestionOnlyPaths: new Map(), withheld: 0 }),
35
+ }));
36
+
37
+ import { useKnowledgeWriteTarget } from '../useKnowledgeWriteTarget';
38
+
39
+ const ROOT = 'kb/KnowledgeBase';
40
+ const DRAFT = 'alice/draft';
41
+ let writable = new Set<string>();
42
+ let readable = new Set<string>();
43
+
44
+ const dir = (relativePath: string, children: FileTreeEntry[] = []): FileTreeEntry => ({
45
+ name: relativePath.split('/').pop()!,
46
+ relativePath,
47
+ type: 'directory',
48
+ children,
49
+ });
50
+ const file = (relativePath: string): FileTreeEntry => ({
51
+ name: relativePath.split('/').pop()!,
52
+ relativePath,
53
+ type: 'file',
54
+ });
55
+ const tree = (...children: FileTreeEntry[]) => dir('kb', [dir(ROOT, children)]);
56
+
57
+ /** Product, Sales (with Team), Support — plus a page, and a dot-folder that is no place for one. */
58
+ const FOLDERS = tree(
59
+ file(`${ROOT}/Guide.md`),
60
+ dir(`${ROOT}/.hidden`),
61
+ dir(`${ROOT}/Product`),
62
+ dir(`${ROOT}/Sales`, [dir(`${ROOT}/Sales/Team`), file(`${ROOT}/Sales/a.md`)]),
63
+ dir(`${ROOT}/Support`),
64
+ );
65
+
66
+ function show(over: Partial<typeof workspace.current> = {}, shownTree: FileTreeEntry | null = FOLDERS) {
67
+ workspace.current = { ...workspace.current, ...over };
68
+ merged.tree = shownTree;
69
+ }
70
+
71
+ async function settledTarget(over: Partial<typeof workspace.current> = {}, shownTree?: FileTreeEntry | null) {
72
+ show(over, shownTree);
73
+ const hook = renderHook(() => useKnowledgeWriteTarget(ROOT));
74
+ await waitFor(() => expect(hook.result.current.settled).toBe(true));
75
+ return hook;
76
+ }
77
+
78
+ beforeEach(() => {
79
+ writable = new Set();
80
+ readable = new Set();
81
+ workspace.current = { workspaceId: 'ws-1', workspaceBranch: 'target-company-state', kbDirName: 'kb', openFilePath: null };
82
+ merged.tree = FOLDERS;
83
+ batch.mockReset().mockImplementation(async (_ws, paths, verb = 'write') => ({
84
+ results: Object.fromEntries(paths.map((p) => [p, (verb === 'read' ? readable : writable).has(p)])),
85
+ }));
86
+ });
87
+
88
+ /** The verb every batch call so far asked — one question per branch kind. */
89
+ const verbsAsked = () => new Set(batch.mock.calls.map((c) => c[2] ?? 'write'));
90
+
91
+ afterEach(() => {
92
+ vi.useRealTimers();
93
+ });
94
+
95
+ describe('useKnowledgeWriteTarget on a protected branch', () => {
96
+ it('takes the top of Knowledge when it may be written, whatever is on screen', async () => {
97
+ writable = new Set(['KnowledgeBase', 'KnowledgeBase/Support']);
98
+ const { result } = await settledTarget({ openFilePath: `${ROOT}/Support/FAQ.md` });
99
+ expect(result.current.folder).toBe(ROOT);
100
+ });
101
+
102
+ it('else the folder on screen, asking every folder repo-relative and once, depth first, without dot-folders', async () => {
103
+ writable = new Set(['KnowledgeBase/Sales', 'KnowledgeBase/Support']);
104
+ const { result } = await settledTarget({ openFilePath: `${ROOT}/Support/FAQ.md` });
105
+ expect(result.current.folder).toBe(`${ROOT}/Support`);
106
+ expect(batch).toHaveBeenCalledWith(
107
+ 'ws-1',
108
+ ['KnowledgeBase', 'KnowledgeBase/Support', 'KnowledgeBase/Product', 'KnowledgeBase/Sales', 'KnowledgeBase/Sales/Team'],
109
+ 'write',
110
+ );
111
+ expect(verbsAsked()).toEqual(new Set(['write']));
112
+ });
113
+
114
+ it('else the first folder in tree order', async () => {
115
+ writable = new Set(['KnowledgeBase/Sales', 'KnowledgeBase/Support']);
116
+ const { result } = await settledTarget({ openFilePath: `${ROOT}/Product/Roadmap.md` });
117
+ expect(result.current.folder).toBe(`${ROOT}/Sales`);
118
+ });
119
+
120
+ it('settles on nothing when there is nowhere to write', async () => {
121
+ const { result } = await settledTarget();
122
+ expect(result.current.folder).toBeNull();
123
+ });
124
+
125
+ it('asks in pages the endpoint accepts, stopping at the first that answers', async () => {
126
+ const many = Array.from({ length: 1010 }, (_, i) => dir(`${ROOT}/F${i}`));
127
+ writable = new Set(['KnowledgeBase/F503', 'KnowledgeBase/F1005']);
128
+ const { result } = await settledTarget({}, tree(...many));
129
+ expect(result.current.folder).toBe(`${ROOT}/F503`);
130
+ expect(batch).toHaveBeenCalledTimes(2);
131
+ for (const call of batch.mock.calls) expect(call[1].length).toBeLessThanOrEqual(500);
132
+ });
133
+
134
+ it('settles on nothing when the request fails', async () => {
135
+ batch.mockRejectedValue(new Error('HTTP 500'));
136
+ const { result } = await settledTarget();
137
+ expect(result.current.folder).toBeNull();
138
+ });
139
+
140
+ it('a recheck overtaken by a newer question answers with the newer answer, never a folder of what was left', async () => {
141
+ vi.useFakeTimers();
142
+ writable = new Set(['KnowledgeBase/Sales']);
143
+ show({ openFilePath: `${ROOT}/Sales/a.md` });
144
+ const { result, rerender } = renderHook(() => useKnowledgeWriteTarget(ROOT));
145
+ await act(async () => {
146
+ await vi.advanceTimersByTimeAsync(0);
147
+ });
148
+ expect(result.current.folder).toBe(`${ROOT}/Sales`);
149
+
150
+ // Every later question answers only when told to, in any order.
151
+ const pending: Array<(r: { results: Record<string, boolean> }) => void> = [];
152
+ batch.mockImplementation(() => new Promise((resolve) => pending.push(resolve)));
153
+ // A create asks again (first question)...
154
+ const asked = result.current.recheck();
155
+ // ...and the person moves to a page in Support before it answers (second question, after the debounce).
156
+ show({ openFilePath: `${ROOT}/Support/b.md` });
157
+ rerender();
158
+ await act(async () => {
159
+ await vi.advanceTimersByTimeAsync(300);
160
+ });
161
+ expect(pending).toHaveLength(2);
162
+ // The first answers: Sales, where they were. Then the second: Support.
163
+ await act(async () => {
164
+ pending[0]!({ results: { 'KnowledgeBase/Sales': true } });
165
+ await vi.advanceTimersByTimeAsync(0);
166
+ pending[1]!({ results: { 'KnowledgeBase/Support': true } });
167
+ await vi.advanceTimersByTimeAsync(0);
168
+ });
169
+ expect(await asked).toBe(`${ROOT}/Support`);
170
+ expect(result.current.folder).toBe(`${ROOT}/Support`);
171
+ });
172
+
173
+ it('a recheck that answers for a page left during the debounce asks again for the page on screen', async () => {
174
+ vi.useFakeTimers();
175
+ writable = new Set(['KnowledgeBase/Sales', 'KnowledgeBase/Support']);
176
+ show({ openFilePath: `${ROOT}/Sales/a.md` });
177
+ const { result, rerender } = renderHook(() => useKnowledgeWriteTarget(ROOT));
178
+ await act(async () => {
179
+ await vi.advanceTimersByTimeAsync(0);
180
+ });
181
+ // Top of Knowledge is not writable, so the folder follows the page on screen.
182
+ expect(result.current.folder).toBe(`${ROOT}/Sales`);
183
+
184
+ const pending: Array<() => void> = [];
185
+ batch.mockImplementation(
186
+ (_ws, paths) =>
187
+ new Promise((resolve) =>
188
+ pending.push(() => resolve({ results: Object.fromEntries(paths.map((p) => [p, writable.has(p)])) })),
189
+ ),
190
+ );
191
+ // A create asks about Sales...
192
+ const asked = result.current.recheck();
193
+ // ...the person opens a page in Support, and the Sales answer comes back
194
+ // inside the debounce, before any question about Support was asked.
195
+ show({ openFilePath: `${ROOT}/Support/b.md` });
196
+ rerender();
197
+ await act(async () => {
198
+ pending.shift()!();
199
+ await vi.advanceTimersByTimeAsync(0);
200
+ });
201
+ // Not handed Sales: it asked again, about Support.
202
+ expect(pending).toHaveLength(1);
203
+ await act(async () => {
204
+ pending.shift()!();
205
+ await vi.advanceTimersByTimeAsync(0);
206
+ });
207
+ expect(await asked).toBe(`${ROOT}/Support`);
208
+ // And `resolve` answers the current folder without asking again.
209
+ const calls = batch.mock.calls.length;
210
+ expect(await result.current.resolve()).toBe(`${ROOT}/Support`);
211
+ expect(batch.mock.calls.length).toBe(calls);
212
+ // Let the debounced question the page change scheduled answer too.
213
+ await act(async () => {
214
+ await vi.advanceTimersByTimeAsync(300);
215
+ while (pending.length) pending.shift()!();
216
+ await vi.advanceTimersByTimeAsync(0);
217
+ });
218
+ });
219
+
220
+ it('asks at once the first time, and debounces a tree change after that', async () => {
221
+ vi.useFakeTimers();
222
+ show();
223
+ const { result, rerender } = renderHook(() => useKnowledgeWriteTarget(ROOT));
224
+ await act(async () => {
225
+ await vi.advanceTimersByTimeAsync(0);
226
+ });
227
+ expect(result.current.settled).toBe(true);
228
+ expect(result.current.folder).toBeNull();
229
+ expect(batch).toHaveBeenCalledTimes(1);
230
+
231
+ // An admin shares Support; the tree changes with it.
232
+ writable = new Set(['KnowledgeBase/Support']);
233
+ show({}, tree(dir(`${ROOT}/Product`), dir(`${ROOT}/Support`)));
234
+ rerender();
235
+ await act(async () => {
236
+ await vi.advanceTimersByTimeAsync(200);
237
+ });
238
+ expect(batch).toHaveBeenCalledTimes(1);
239
+ await act(async () => {
240
+ await vi.advanceTimersByTimeAsync(100);
241
+ });
242
+ expect(batch).toHaveBeenCalledTimes(2);
243
+ expect(result.current.folder).toBe(`${ROOT}/Support`);
244
+ });
245
+ });
246
+
247
+ /**
248
+ * A draft branch: no write grant is needed, only read where the page lands,
249
+ * and the tree shows folders the person may not read when something inside
250
+ * them is shared — so every candidate is asked, in the same order and the
251
+ * same pages, about reading.
252
+ */
253
+ describe('useKnowledgeWriteTarget on a draft branch', () => {
254
+ it('takes the top of Knowledge when it may be read, asking no write check', async () => {
255
+ readable = new Set(['KnowledgeBase', 'KnowledgeBase/Support']);
256
+ const { result } = await settledTarget({ workspaceBranch: DRAFT, openFilePath: `${ROOT}/Support/FAQ.md` });
257
+ expect(result.current.folder).toBe(ROOT);
258
+ expect(batch).toHaveBeenCalledWith(
259
+ 'ws-1',
260
+ ['KnowledgeBase', 'KnowledgeBase/Support', 'KnowledgeBase/Product', 'KnowledgeBase/Sales', 'KnowledgeBase/Sales/Team'],
261
+ 'read',
262
+ );
263
+ expect(verbsAsked()).toEqual(new Set(['read']));
264
+ });
265
+
266
+ it('passes over a top shown only for what is inside it, to the folder on screen, else the first in tree order', async () => {
267
+ readable = new Set(['KnowledgeBase/Sales/Team', 'KnowledgeBase/Support']);
268
+ const onScreen = await settledTarget({ workspaceBranch: DRAFT, openFilePath: `${ROOT}/Support/FAQ.md` });
269
+ expect(onScreen.result.current.folder).toBe(`${ROOT}/Support`);
270
+ onScreen.unmount();
271
+ const elsewhere = await settledTarget({ workspaceBranch: DRAFT, openFilePath: `${ROOT}/Product/Roadmap.md` });
272
+ expect(elsewhere.result.current.folder).toBe(`${ROOT}/Sales/Team`);
273
+ });
274
+
275
+ it('settles on nothing when nothing may be read', async () => {
276
+ const { result } = await settledTarget({ workspaceBranch: DRAFT });
277
+ expect(result.current.folder).toBeNull();
278
+ });
279
+
280
+ it('asks in the pages the endpoint accepts, stopping at the first that answers', async () => {
281
+ const many = Array.from({ length: 1010 }, (_, i) => dir(`${ROOT}/F${i}`));
282
+ readable = new Set(['KnowledgeBase/F503', 'KnowledgeBase/F1005']);
283
+ const { result } = await settledTarget({ workspaceBranch: DRAFT }, tree(...many));
284
+ expect(result.current.folder).toBe(`${ROOT}/F503`);
285
+ // The top and F0…F498, then F499…F998: two pages, never the third.
286
+ expect(batch).toHaveBeenCalledTimes(2);
287
+ for (const call of batch.mock.calls) expect(call[1].length).toBeLessThanOrEqual(500);
288
+ expect(verbsAsked()).toEqual(new Set(['read']));
289
+ });
290
+
291
+ it('asks nothing when the tree shows no Knowledge folder', async () => {
292
+ const { result } = await settledTarget({ workspaceBranch: DRAFT }, dir('kb', [dir('kb/Skills')]));
293
+ expect(result.current.folder).toBeNull();
294
+ expect(batch).not.toHaveBeenCalled();
295
+ });
296
+
297
+ it('settles on nothing when the request fails', async () => {
298
+ batch.mockRejectedValue(new Error('HTTP 500'));
299
+ const { result } = await settledTarget({ workspaceBranch: DRAFT });
300
+ expect(result.current.folder).toBeNull();
301
+ });
302
+ });
@@ -1,4 +1,4 @@
1
- import { useCallback } from 'react';
1
+ import { useCallback, useEffect, useRef } from 'react';
2
2
  import { useLocation } from 'react-router-dom';
3
3
  import { KNOWLEDGE_BASE_DIR, type FileTreeEntry } from '@bevel-software/platform-shared';
4
4
  import { useWorkspace } from '../state/workspace.context';
@@ -6,6 +6,7 @@ import { WorkspaceApiError } from '../services/workspace.api';
6
6
  import { branchFromPathname, useFileNav } from '../routing/kb-routes';
7
7
  import { useMergedWorkspaceTree } from './useMergedWorkspaceTree';
8
8
  import { pathExistsInTree } from '../utils/fileTree';
9
+ import { useKnowledgeWriteTarget } from './useKnowledgeWriteTarget';
9
10
 
10
11
  /**
11
12
  * What "New page" writes: a title, so the page is a page from its first save,
@@ -44,25 +45,52 @@ function isNameTaken(err: unknown): boolean {
44
45
  return err instanceof WorkspaceApiError && err.status === 409;
45
46
  }
46
47
 
48
+ /**
49
+ * A refusal to write there: 403. Access rules and a protected branch's gate
50
+ * both answer it, so it is only a cue to ask again where the person may
51
+ * write — the fresh answer tells the two apart. Never shown either way.
52
+ */
53
+ function isRefused(err: unknown): boolean {
54
+ return err instanceof WorkspaceApiError && err.status === 403;
55
+ }
56
+
47
57
  export interface CreatePage {
48
58
  /**
49
- * The Knowledge folder pages are created in, or null while there is nowhere
50
- * safe to create one: before the workspace has bootstrapped, and while the
51
- * workspace on screen is not yet the branch the URL names.
59
+ * The Knowledge folder, or null while there is nowhere safe to create a
60
+ * page: before the workspace has bootstrapped, and while the workspace on
61
+ * screen is not yet the branch the URL names.
52
62
  */
53
63
  knowledgeRoot: string | null;
54
64
  /**
55
- * Create `Untitled.md` (or the next free `Untitled N.md`) in the Knowledge
56
- * folder and open it in edit mode. Resolves with the path; rejects with an
57
- * Error whose message is ready to show ("Couldn’t create the page: …").
65
+ * Create `Untitled.md` (or the next free `Untitled N.md`) in `pageFolder`
66
+ * and open it in edit mode. Resolves with the path, or with null when a
67
+ * write was refused and there is nowhere left to try: a fresh check found
68
+ * nowhere the person may write, or the refusal was not about the folder
69
+ * (New page then disappears; there is nothing to say). Rejects, for any
70
+ * failure but a refusal, with an Error whose message is ready to show
71
+ * ("Couldn’t create the page: …").
58
72
  */
59
- createPage(): Promise<string>;
73
+ createPage(): Promise<string | null>;
74
+ /**
75
+ * The Knowledge folder New page writes to (`useKnowledgeWriteTarget`): the
76
+ * Knowledge folder itself when the person may write it, else the folder of
77
+ * the page on screen, else the first they may write in file tree order.
78
+ * Null until the first check answers and when there is nowhere —
79
+ * everything that offers New page hides it while this is null. A later
80
+ * check (a tree or page change, a switch) keeps the last folder up until
81
+ * it answers, so nothing flickers; `createPage` asks again before writing
82
+ * when that answer is not for the page and branch on screen.
83
+ */
84
+ pageFolder: string | null;
85
+ /** Whether that check has answered, so a list can wait for it rather than flash. */
86
+ pageFolderSettled: boolean;
60
87
  }
61
88
 
62
89
  /**
63
90
  * "New page", shared by everything that offers it — the Get set up list and
64
91
  * the command menu — so both pick names the same way and neither can ever
65
- * overwrite a page.
92
+ * overwrite a page. It writes where the person may write (`pageFolder`),
93
+ * and a refused write asks again rather than showing who may write there.
66
94
  *
67
95
  * The create is EXCLUSIVE (`ifAbsent`): the name comes from the tree on
68
96
  * screen, which may not yet show a page someone else just made, and a plain
@@ -90,27 +118,89 @@ export function useCreatePage(): CreatePage {
90
118
  const ready = kbDirName !== null && workspaceBranch !== null && destination === workspaceBranch;
91
119
  const knowledgeRoot = ready ? `${kbDirName}/${KNOWLEDGE_BASE_DIR}` : null;
92
120
 
93
- const createPage = useCallback(async (): Promise<string> => {
94
- if (!knowledgeRoot) throw new Error('Couldn’t create the page: the workspace is still loading.');
95
- let n = freeUntitledNumber(tree, knowledgeRoot);
96
- let path = untitledPagePath(knowledgeRoot, n);
97
- for (let attempt = 1; ; attempt++) {
98
- try {
99
- await createFile(path, NEW_PAGE_CONTENT, { ifAbsent: true });
100
- break;
101
- } catch (err) {
102
- if (isNameTaken(err) && attempt < NEW_PAGE_ATTEMPTS) {
103
- n = freeUntitledNumber(tree, knowledgeRoot, n + 1);
104
- path = untitledPagePath(knowledgeRoot, n);
105
- continue;
121
+ // Where the person may write is asked of the workspace on screen whatever
122
+ // the URL says, so the list and the menu know it mid-switch too; only the
123
+ // create waits for the two to agree.
124
+ const {
125
+ folder: pageFolder,
126
+ settled: pageFolderSettled,
127
+ recheck,
128
+ resolve,
129
+ withdraw,
130
+ } = useKnowledgeWriteTarget(kbDirName !== null ? `${kbDirName}/${KNOWLEDGE_BASE_DIR}` : null);
131
+
132
+ // What a create was started on. A switch of branch while it waits (for a
133
+ // recheck, for a refused attempt) would otherwise let it write to the
134
+ // workspace it captured and open the page back on the branch just left;
135
+ // after every wait it checks it is still where it started, and stops if
136
+ // not. The page it may have made by then stays where it was made.
137
+ const liveKey = `${workspaceBranch}\n${destination}`;
138
+ const live = useRef(liveKey);
139
+ useEffect(() => {
140
+ live.current = liveKey;
141
+ }, [liveKey]);
142
+
143
+ const createPage = useCallback(async (): Promise<string | null> => {
144
+ if (!knowledgeRoot || !pageFolderSettled) {
145
+ throw new Error('Couldn’t create the page: the workspace is still loading.');
146
+ }
147
+ const startedOn = liveKey;
148
+ const moved = (): boolean => live.current !== startedOn;
149
+ // The folder for the page and branch on screen now (`resolve`): the last
150
+ // answer when it is about them, else asked again — never a folder shown
151
+ // for a page just left during the check's debounce.
152
+ let folder = await resolve();
153
+ if (moved()) return null;
154
+ // Folders a write was refused in, this create: each refusal asks again,
155
+ // and a fresh answer naming one of these says the refusal is not about
156
+ // the folder.
157
+ // Every folder this loop writes comes from `resolve` or a refusal's
158
+ // `recheck`, both answered for the page and branch on screen when they
159
+ // return (see `useKnowledgeWriteTarget`).
160
+ const refused = new Set<string>();
161
+ while (folder) {
162
+ let n = freeUntitledNumber(tree, folder);
163
+ let path = untitledPagePath(folder, n);
164
+ for (let attempt = 1; ; attempt++) {
165
+ if (moved()) return null;
166
+ try {
167
+ await createFile(path, NEW_PAGE_CONTENT, { ifAbsent: true });
168
+ // Made, but the person has moved on: it is not opened over them.
169
+ if (moved()) return path;
170
+ openWorkspacePath(path, { edit: true });
171
+ return path;
172
+ } catch (err) {
173
+ if (isNameTaken(err) && attempt < NEW_PAGE_ATTEMPTS) {
174
+ n = freeUntitledNumber(tree, folder, n + 1);
175
+ path = untitledPagePath(folder, n);
176
+ continue;
177
+ }
178
+ // A refusal is never shown: who may write where is nobody's business
179
+ // here. Access changed since the check, so ask again and move on to
180
+ // the next folder they may write — or, with none, New page is gone.
181
+ if (isRefused(err)) {
182
+ refused.add(folder);
183
+ const next = await recheck();
184
+ if (moved()) return null;
185
+ if (next && !refused.has(next)) {
186
+ folder = next;
187
+ break;
188
+ }
189
+ // The check still says they may write where they were refused:
190
+ // the branch, not the folder, said no, and no folder here would
191
+ // take the page. New page goes rather than fail on every click.
192
+ if (next) withdraw();
193
+ return null;
194
+ }
195
+ // And should any other failure name who may write, that goes too.
196
+ const msg = (err instanceof Error ? err.message : String(err)).replace(/\s*Eligible:[\s\S]*$/, '');
197
+ throw new Error(`Couldn’t create the page: ${msg}`, { cause: err });
106
198
  }
107
- const msg = err instanceof Error ? err.message : String(err);
108
- throw new Error(`Couldn’t create the page: ${msg}`, { cause: err });
109
199
  }
110
200
  }
111
- openWorkspacePath(path, { edit: true });
112
- return path;
113
- }, [knowledgeRoot, tree, createFile, openWorkspacePath]);
201
+ // Nowhere to write: the fresh answer has hidden New page, which says it.
202
+ return null;
203
+ }, [knowledgeRoot, liveKey, pageFolderSettled, resolve, recheck, withdraw, tree, createFile, openWorkspacePath]);
114
204
 
115
- return { knowledgeRoot, createPage };
205
+ return { knowledgeRoot, createPage, pageFolder, pageFolderSettled };
116
206
  }