@bevel-software/platform-core-frontend 0.14.0 → 0.19.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.
Files changed (360) hide show
  1. package/THIRD-PARTY-NOTICES.md +2 -2
  2. package/package.json +3 -3
  3. package/src/core/CoreAppShell.tsx +34 -26
  4. package/src/core/__tests__/AppChrome.test.tsx +0 -3
  5. package/src/core/__tests__/bootstrap.test.ts +33 -1
  6. package/src/core/__tests__/events.test.ts +43 -0
  7. package/src/core/bootstrap.ts +38 -1
  8. package/src/core/events.ts +85 -3
  9. package/src/core/registry.ts +1 -1
  10. package/src/lib/__tests__/api.test.ts +38 -0
  11. package/src/lib/__tests__/email.test.ts +44 -0
  12. package/src/lib/api.ts +19 -2
  13. package/src/lib/email.ts +37 -1
  14. package/src/lib/utils.ts +2 -0
  15. package/src/modules/access/__tests__/ManageAccessDialog.add-row-picking.test.tsx +141 -0
  16. package/src/modules/access/__tests__/ManageAccessDialog.chip-truncation.test.tsx +204 -0
  17. package/src/modules/access/__tests__/ManageAccessDialog.download-read.test.tsx +234 -0
  18. package/src/modules/access/__tests__/ManageAccessDialog.edited-row-visible.test.tsx +160 -0
  19. package/src/modules/access/__tests__/ManageAccessDialog.placement.test.tsx +2 -2
  20. package/src/modules/access/__tests__/ManageAccessDialog.proposal.test.tsx +166 -0
  21. package/src/modules/access/__tests__/ManageAccessDialog.restrict.test.tsx +510 -0
  22. package/src/modules/access/__tests__/ManageAccessDialog.row-menu-axes.test.tsx +299 -0
  23. package/src/modules/access/__tests__/ManageAccessDialog.row-menu-width.test.tsx +226 -0
  24. package/src/modules/access/__tests__/ManageAccessDialog.test.tsx +781 -76
  25. package/src/modules/access/__tests__/ManageAccessDialog.unknown-email.test.tsx +314 -0
  26. package/src/modules/access/__tests__/manage-access-affordance.test.ts +14 -0
  27. package/src/modules/access/__tests__/plugin-token.test.ts +21 -0
  28. package/src/modules/access/__tests__/tailwindDeclarations.ts +210 -0
  29. package/src/modules/access/api.ts +192 -10
  30. package/src/modules/access/components/ManageAccessDialog.tsx +1337 -570
  31. package/src/modules/access/manage-access-affordance.ts +17 -0
  32. package/src/modules/admin/__tests__/AddMemberInput.test.tsx +297 -0
  33. package/src/modules/admin/__tests__/AdminRolesPage.capabilities.test.tsx +2 -2
  34. package/src/modules/admin/__tests__/AdminRolesPage.fixed-admin.test.tsx +189 -0
  35. package/src/modules/admin/__tests__/AdminRolesPage.suggest.test.tsx +1 -1
  36. package/src/modules/admin/__tests__/ConnectionKeysPage.test.tsx +266 -0
  37. package/src/modules/admin/__tests__/DirectoryGroupsPage.suggest.test.tsx +182 -0
  38. package/src/modules/admin/__tests__/DirectoryGroupsPage.test.tsx +165 -14
  39. package/src/modules/admin/__tests__/UserAccountsPage.test.tsx +401 -4
  40. package/src/modules/admin/__tests__/group-members-path.test.ts +27 -0
  41. package/src/modules/admin/components/AddMemberInput.tsx +268 -0
  42. package/src/modules/admin/components/AdminRolesPage.tsx +97 -132
  43. package/src/modules/admin/components/ConnectionKeysPage.tsx +269 -0
  44. package/src/modules/admin/components/DirectoryGroupsPage.tsx +91 -39
  45. package/src/modules/admin/components/UserAccountsPage.tsx +271 -37
  46. package/src/modules/admin/components/connection-keys-grouping.ts +43 -0
  47. package/src/modules/admin/components/group-members-path.ts +32 -0
  48. package/src/modules/admin/services/connection-keys.api.ts +47 -0
  49. package/src/modules/admin/services/roles.api.ts +12 -1
  50. package/src/modules/auth/__tests__/AccountPage.test.tsx +50 -2
  51. package/src/modules/auth/components/AccountPage.tsx +73 -54
  52. package/src/modules/auth/components/LoginScreen.tsx +1 -0
  53. package/src/modules/auth/services/account.api.ts +78 -4
  54. package/src/modules/change-requests/__tests__/ChangeRequestDialog.access-rules.test.tsx +144 -0
  55. package/src/modules/change-requests/__tests__/ChangeRequestDialog.binary.test.tsx +422 -0
  56. package/src/modules/change-requests/__tests__/ChangeRequestDialog.brings-itself-up-to-date.test.tsx +431 -0
  57. package/src/modules/change-requests/__tests__/ChangeRequestDialog.fork-point.test.tsx +193 -0
  58. package/src/modules/change-requests/__tests__/ChangeRequestDialog.initial-file.test.tsx +142 -0
  59. package/src/modules/change-requests/__tests__/ChangeRequestDialog.moved.test.tsx +202 -0
  60. package/src/modules/change-requests/__tests__/ChangeRequestDialog.test.tsx +205 -13
  61. package/src/modules/change-requests/__tests__/ChangeRequestDialog.unreadable.test.tsx +271 -0
  62. package/src/modules/change-requests/__tests__/FileChangeBoxes.test.tsx +208 -0
  63. package/src/modules/change-requests/__tests__/apply-outcome-for-every-viewer.test.tsx +286 -0
  64. package/src/modules/change-requests/__tests__/propose.concurrent.test.ts +273 -0
  65. package/src/modules/change-requests/__tests__/readFailure.test.ts +122 -0
  66. package/src/modules/change-requests/__tests__/useCrFileDiffs.test.tsx +238 -0
  67. package/src/modules/change-requests/__tests__/useFileOnBranch.test.tsx +56 -1
  68. package/src/modules/change-requests/__tests__/useForkPointFile.test.tsx +79 -0
  69. package/src/modules/change-requests/components/BranchFilePreview.tsx +357 -0
  70. package/src/modules/change-requests/components/ChangeBox.tsx +31 -2
  71. package/src/modules/change-requests/components/ChangeRequestDialog.tsx +862 -72
  72. package/src/modules/change-requests/components/CrFileTree.tsx +74 -58
  73. package/src/modules/change-requests/components/FileChangeBoxes.tsx +19 -15
  74. package/src/modules/change-requests/hooks/useApplyChangeRequest.ts +41 -7
  75. package/src/modules/change-requests/hooks/useCrFileDiffs.ts +181 -23
  76. package/src/modules/change-requests/hooks/useFileOnBranch.ts +70 -7
  77. package/src/modules/change-requests/hooks/useForkPointFile.ts +77 -0
  78. package/src/modules/change-requests/services/change-requests.api.ts +57 -1
  79. package/src/modules/change-requests/services/denied-file.api.ts +53 -0
  80. package/src/modules/change-requests/services/propose.api.ts +97 -8
  81. package/src/modules/change-requests/utils/approval.ts +15 -0
  82. package/src/modules/change-requests/utils/author.ts +32 -0
  83. package/src/modules/change-requests/utils/readFailure.ts +110 -0
  84. package/src/modules/git/__tests__/FileHistoryPanel.test.tsx +20 -0
  85. package/src/modules/git/__tests__/GitSyncFailedBanner.test.tsx +65 -1
  86. package/src/modules/git/components/FileHistoryPanel.tsx +5 -0
  87. package/src/modules/git/components/GitSyncFailedBanner.tsx +68 -5
  88. package/src/modules/git/components/PullRequestsForMe.tsx +51 -24
  89. package/src/modules/git/services/__tests__/error-messages.test.ts +29 -0
  90. package/src/modules/git/services/error-messages.ts +12 -0
  91. package/src/modules/git/services/pr-prompts.ts +5 -5
  92. package/src/modules/layout/__tests__/HeaderAlignment.test.tsx +401 -0
  93. package/src/modules/layout/__tests__/SidebarFooterGrid.test.tsx +286 -0
  94. package/src/modules/layout/__tests__/SidebarFrameResponsive.test.tsx +61 -0
  95. package/src/modules/layout/components/AppLayout.tsx +2 -0
  96. package/src/modules/layout/components/MobileChatLayout.tsx +4 -1
  97. package/src/modules/layout/components/ResizableThreePaneLayout.tsx +4 -1
  98. package/src/modules/layout/components/SidebarFrame.tsx +109 -4
  99. package/src/modules/library/__tests__/AddToPluginDialog.test.tsx +171 -5
  100. package/src/modules/library/__tests__/DeleteToolDialog.test.tsx +356 -0
  101. package/src/modules/library/__tests__/IntegrationsSetupReminder.test.tsx +60 -0
  102. package/src/modules/library/__tests__/LibraryCard.test.tsx +91 -10
  103. package/src/modules/library/__tests__/LibraryRoutes.test.tsx +242 -107
  104. package/src/modules/library/__tests__/LibrarySidebarMenu.test.tsx +104 -99
  105. package/src/modules/library/__tests__/LinkSkillPanel.test.tsx +136 -0
  106. package/src/modules/library/__tests__/LockedPluginView.test.tsx +103 -7
  107. package/src/modules/library/__tests__/NewPluginDialog.test.tsx +18 -8
  108. package/src/modules/library/__tests__/PersonalAddDialog.test.tsx +79 -3
  109. package/src/modules/library/__tests__/PersonalPluginPage.test.tsx +201 -0
  110. package/src/modules/library/__tests__/PluginExtras.test.tsx +115 -9
  111. package/src/modules/library/__tests__/PluginJoinRequests.test.tsx +60 -1
  112. package/src/modules/library/__tests__/PluginPage.test.tsx +453 -7
  113. package/src/modules/library/__tests__/PluginsSidebar.contextmenu.test.tsx +17 -57
  114. package/src/modules/library/__tests__/PluginsSidebar.test.tsx +161 -97
  115. package/src/modules/library/__tests__/PluginsSidebarMenu.test.tsx +16 -0
  116. package/src/modules/library/__tests__/SharedViaPlugins.test.tsx +106 -0
  117. package/src/modules/library/__tests__/SkillPage.test.tsx +391 -78
  118. package/src/modules/library/__tests__/SkillsTree.test.tsx +461 -0
  119. package/src/modules/library/__tests__/ToolConnectionSection.test.tsx +582 -71
  120. package/src/modules/library/__tests__/ToolPage.test.tsx +94 -4
  121. package/src/modules/library/__tests__/WorkspaceItemRoute.test.tsx +279 -21
  122. package/src/modules/library/__tests__/auth-harness.tsx +9 -9
  123. package/src/modules/library/__tests__/card-row-menu.test.tsx +320 -0
  124. package/src/modules/library/__tests__/library-data.mapping.test.tsx +98 -0
  125. package/src/modules/library/__tests__/library-data.stale.test.tsx +183 -0
  126. package/src/modules/library/__tests__/library-data.test.ts +7 -0
  127. package/src/modules/library/__tests__/library-paths.test.ts +75 -0
  128. package/src/modules/library/__tests__/link-membership.test.ts +129 -0
  129. package/src/modules/library/__tests__/name-with-badges.test.tsx +273 -0
  130. package/src/modules/library/__tests__/newSkillMarkdown.test.ts +30 -0
  131. package/src/modules/library/__tests__/owner-pill.test.tsx +357 -0
  132. package/src/modules/library/__tests__/pending-tools.test.tsx +400 -0
  133. package/src/modules/library/__tests__/plugin-entries.test.ts +122 -0
  134. package/src/modules/library/__tests__/plugin-summary.test.ts +67 -0
  135. package/src/modules/library/__tests__/status.test.ts +82 -2
  136. package/src/modules/library/__tests__/tools.api.test.ts +44 -1
  137. package/src/modules/library/__tests__/useJoinRequests.test.tsx +46 -0
  138. package/src/modules/library/components/AccessRequestsBanner.tsx +85 -47
  139. package/src/modules/library/components/AddDialogTabs.tsx +103 -0
  140. package/src/modules/library/components/AddToPluginDialog.tsx +107 -18
  141. package/src/modules/library/components/IntegrationsSetupReminder.tsx +59 -0
  142. package/src/modules/library/components/ItemActionsMenu.tsx +288 -0
  143. package/src/modules/library/components/LibraryCard.tsx +149 -34
  144. package/src/modules/library/components/LibraryLayout.tsx +120 -247
  145. package/src/modules/library/components/LibraryPage.tsx +172 -39
  146. package/src/modules/library/components/LinkSkillPanel.tsx +169 -0
  147. package/src/modules/library/components/LockedPluginView.tsx +63 -35
  148. package/src/modules/library/components/NameWithBadges.tsx +164 -0
  149. package/src/modules/library/components/NewPluginDialog.tsx +19 -5
  150. package/src/modules/library/components/PageActions.tsx +31 -9
  151. package/src/modules/library/components/{PendingSkillReview.tsx → PendingItemReview.tsx} +14 -7
  152. package/src/modules/library/components/PersonalAddDialog.tsx +68 -18
  153. package/src/modules/library/components/PersonalPluginPage.tsx +123 -23
  154. package/src/modules/library/components/PluginExtras.tsx +143 -18
  155. package/src/modules/library/components/PluginIndexRow.tsx +47 -12
  156. package/src/modules/library/components/PluginPage.tsx +234 -38
  157. package/src/modules/library/components/PluginRows.tsx +286 -0
  158. package/src/modules/library/components/PluginsSidebar.tsx +271 -238
  159. package/src/modules/library/components/PluginsSidebarMenu.tsx +26 -1
  160. package/src/modules/library/components/RenamePluginDialog.tsx +136 -0
  161. package/src/modules/library/components/ShareButton.tsx +17 -0
  162. package/src/modules/library/components/SkillsTree.tsx +204 -0
  163. package/src/modules/library/components/StatusDot.tsx +1 -0
  164. package/src/modules/library/components/TeamRoute.tsx +15 -0
  165. package/src/modules/library/components/__tests__/upload-notices-once-per-page.test.tsx +144 -0
  166. package/src/modules/library/components/plugin-page-parts.tsx +132 -23
  167. package/src/modules/library/components/skill-page/SharedViaPlugins.tsx +212 -0
  168. package/src/modules/library/components/skill-page/SkillFilePane.tsx +5 -0
  169. package/src/modules/library/components/skill-page/SkillPage.tsx +337 -121
  170. package/src/modules/library/components/tool-page/DeleteToolDialog.tsx +218 -0
  171. package/src/modules/library/components/tool-page/ToolConnectionSection.tsx +79 -178
  172. package/src/modules/library/components/tool-page/ToolPage.tsx +116 -17
  173. package/src/modules/library/components/tool-page/ToolVarRow.tsx +42 -41
  174. package/src/modules/library/hooks/__tests__/useLibraryData.test.ts +98 -0
  175. package/src/modules/library/hooks/useJoinRequests.ts +48 -18
  176. package/src/modules/library/hooks/useLibraryData.ts +92 -19
  177. package/src/modules/library/routes/LibraryRoutes.tsx +14 -11
  178. package/src/modules/library/routes/WorkspaceItemRoute.tsx +229 -82
  179. package/src/modules/library/routes/library-paths.ts +46 -35
  180. package/src/modules/library/services/library.api.ts +89 -17
  181. package/src/modules/library/services/plugins.api.ts +161 -9
  182. package/src/modules/library/services/teams.api.ts +15 -0
  183. package/src/modules/library/services/tools.api.ts +78 -0
  184. package/src/modules/library/state/library-data.tsx +268 -37
  185. package/src/modules/library/utils/personal-plugin.ts +13 -15
  186. package/src/modules/library/utils/plugin-entries.ts +134 -0
  187. package/src/modules/library/utils/plugin-summary.ts +102 -0
  188. package/src/modules/library/utils/status.ts +204 -35
  189. package/src/modules/onboarding/__tests__/creator-welcome.test.tsx +11 -3
  190. package/src/modules/onboarding/__tests__/onboarding.test.tsx +853 -760
  191. package/src/modules/onboarding/agent-clients.ts +55 -23
  192. package/src/modules/onboarding/components/ConnectAgentPill.tsx +5 -1
  193. package/src/modules/onboarding/components/WelcomePage.tsx +98 -62
  194. package/src/modules/pr/services/pr-merge.api.ts +2 -1
  195. package/src/modules/review/components/MarkdownDiffViewer.tsx +53 -8
  196. package/src/modules/review/components/ReviewPanel.tsx +15 -17
  197. package/src/modules/review/components/__tests__/MarkdownDiffViewer.test.tsx +64 -0
  198. package/src/modules/review/components/__tests__/ReviewPanel.test.tsx +25 -1
  199. package/src/modules/secrets-vault/components/ConnectToolsPage.tsx +454 -117
  200. package/src/modules/secrets-vault/components/SecretsPage.tsx +48 -7
  201. package/src/modules/secrets-vault/components/ToolSecretsPanel.tsx +84 -5
  202. package/src/modules/secrets-vault/components/__tests__/ConnectToolsPage.test.tsx +425 -0
  203. package/src/modules/secrets-vault/components/__tests__/SecretsPage.test.tsx +417 -82
  204. package/src/modules/secrets-vault/components/__tests__/ToolSecretsPanel.test.tsx +105 -0
  205. package/src/modules/secrets-vault/components/__tests__/connect-lists-what-the-banner-counted.test.tsx +407 -0
  206. package/src/modules/secrets-vault/probe/SavedKeyProbeResult.tsx +98 -0
  207. package/src/modules/secrets-vault/probe/__tests__/probe-verdict.test.ts +160 -0
  208. package/src/modules/secrets-vault/probe/probe-verdict.ts +108 -0
  209. package/src/modules/secrets-vault/probe/useSavedKeyProbe.ts +228 -0
  210. package/src/modules/secrets-vault/services/connect.api.ts +36 -5
  211. package/src/modules/secrets-vault/utils/connect-status.ts +98 -0
  212. package/src/modules/settings/components/ClaudeConnectionCard.tsx +154 -0
  213. package/src/modules/settings/components/ClaudeConnectionFields.tsx +23 -0
  214. package/src/modules/settings/components/DeploymentPage.tsx +16 -22
  215. package/src/modules/settings/components/MarketplaceSection.tsx +152 -0
  216. package/src/modules/settings/components/__tests__/ClaudeConnectionCard.test.tsx +63 -0
  217. package/src/modules/settings/components/__tests__/DeploymentPage.test.tsx +74 -1
  218. package/src/modules/settings/components/__tests__/MarketplaceSection.test.tsx +325 -0
  219. package/src/modules/settings/components/__tests__/SettingsLayout.test.tsx +5 -5
  220. package/src/modules/settings/services/github-facade.api.ts +66 -0
  221. package/src/modules/settings/settings-nav-items.tsx +10 -2
  222. package/src/modules/setup/__tests__/setup.oidc.test.tsx +172 -0
  223. package/src/modules/setup/__tests__/setup.probe-refusal.test.tsx +123 -0
  224. package/src/modules/setup/__tests__/setup.test.tsx +615 -4
  225. package/src/modules/setup/__tests__/useSetupStatus.test.tsx +130 -0
  226. package/src/modules/setup/components/SetupGate.tsx +16 -16
  227. package/src/modules/setup/components/SetupScreen.tsx +711 -40
  228. package/src/modules/setup/hooks/useSetupStatus.ts +93 -0
  229. package/src/modules/setup/services/setup.api.ts +218 -3
  230. package/src/modules/setup/utils/__tests__/root-folders.test.ts +72 -0
  231. package/src/modules/setup/utils/root-folders.ts +46 -0
  232. package/src/modules/toolbar/assets/claude-setup/01-add-manually.webp +0 -0
  233. package/src/modules/toolbar/assets/claude-setup/02-add-configuration.webp +0 -0
  234. package/src/modules/toolbar/assets/claude-setup/03-connect-account.webp +0 -0
  235. package/src/modules/toolbar/assets/claude-setup/04-pick-instance.webp +0 -0
  236. package/src/modules/toolbar/assets/claude-setup/05-plugins-add.webp +0 -0
  237. package/src/modules/toolbar/assets/claude-setup/06-add-marketplace.webp +0 -0
  238. package/src/modules/toolbar/assets/claude-setup/07-paste-url-sync.webp +0 -0
  239. package/src/modules/toolbar/assets/claude-setup/08-install-plugins.webp +0 -0
  240. package/src/modules/toolbar/assets/claude-setup/09-select-repository.webp +0 -0
  241. package/src/modules/toolbar/assets/claude-setup/10-connector-not-added.webp +0 -0
  242. package/src/modules/toolbar/assets/claude-setup/11-add-custom-connector.webp +0 -0
  243. package/src/modules/toolbar/assets/claude-setup/README.md +68 -0
  244. package/src/modules/toolbar/components/AgentInstructionsCard.tsx +296 -0
  245. package/src/modules/toolbar/components/ClaudeMarketplaceCarousel.tsx +107 -0
  246. package/src/modules/toolbar/components/ClaudeRegistrationSteps.tsx +127 -0
  247. package/src/modules/toolbar/components/CoworkSetupSteps.tsx +100 -0
  248. package/src/modules/toolbar/components/ExternalAgentAccessPage.tsx +395 -124
  249. package/src/modules/toolbar/components/ScreenshotStep.tsx +77 -0
  250. package/src/modules/toolbar/components/SetupCarousel.tsx +177 -0
  251. package/src/modules/toolbar/components/__tests__/AgentInstructionsCard.test.tsx +370 -0
  252. package/src/modules/toolbar/components/__tests__/ExternalAgentAccessPage.test.tsx +659 -36
  253. package/src/modules/toolbar/components/__tests__/Toolbar.test.tsx +2 -2
  254. package/src/modules/toolbar/components/__tests__/claude-setup-shots.test.ts +104 -0
  255. package/src/modules/toolbar/components/claude-connector-slide.tsx +38 -0
  256. package/src/modules/toolbar/components/claude-setup-shots.ts +167 -0
  257. package/src/modules/toolbar/components/deployment-address.ts +29 -0
  258. package/src/modules/toolbar/components/setup-step-parts.tsx +35 -0
  259. package/src/modules/toolbar/services/__tests__/agent-instructions.api.test.ts +89 -0
  260. package/src/modules/toolbar/services/agent-instructions.api.ts +167 -0
  261. package/src/modules/toolbar/services/external-api-keys.api.ts +8 -0
  262. package/src/modules/workflow/state/ChangeRequestStaleBinder.tsx +43 -0
  263. package/src/modules/workflow/state/EventBusProvider.tsx +122 -11
  264. package/src/modules/workflow/state/__tests__/EventBusProvider.storage.test.tsx +87 -0
  265. package/src/modules/workflow/state/__tests__/EventBusProvider.watch.test.tsx +223 -0
  266. package/src/modules/workflow/state/event-bus.context.ts +10 -0
  267. package/src/modules/workspace/__tests__/testFixtures.ts +6 -3
  268. package/src/modules/workspace/components/FileExplorer.tsx +1527 -367
  269. package/src/modules/workspace/components/FileRoute.tsx +376 -22
  270. package/src/modules/workspace/components/FileViewer.tsx +166 -45
  271. package/src/modules/workspace/components/KbDocumentShell.tsx +50 -6
  272. package/src/modules/workspace/components/KbPageHeader.tsx +120 -55
  273. package/src/modules/workspace/components/TreeActionConfirm.tsx +350 -0
  274. package/src/modules/workspace/components/__tests__/FileExplorer.test.tsx +2473 -129
  275. package/src/modules/workspace/components/__tests__/FileRoute.test.tsx +768 -16
  276. package/src/modules/workspace/components/__tests__/FileViewer.test.tsx +332 -12
  277. package/src/modules/workspace/components/__tests__/KbDocumentShell.test.tsx +39 -0
  278. package/src/modules/workspace/components/__tests__/KbPageHeader.test.tsx +33 -20
  279. package/src/modules/workspace/components/renderers/DocxRenderer.tsx +4 -5
  280. package/src/modules/workspace/components/renderers/DownloadFileButton.tsx +13 -4
  281. package/src/modules/workspace/components/renderers/EmailRenderer.tsx +4 -3
  282. package/src/modules/workspace/components/renderers/HtmlRenderer.tsx +8 -14
  283. package/src/modules/workspace/components/renderers/ImageRenderer.tsx +75 -16
  284. package/src/modules/workspace/components/renderers/KbImage.tsx +180 -0
  285. package/src/modules/workspace/components/renderers/KbMarkdownView.tsx +22 -6
  286. package/src/modules/workspace/components/renderers/MarkdownRenderer.tsx +48 -22
  287. package/src/modules/workspace/components/renderers/PdfRenderer.tsx +4 -5
  288. package/src/modules/workspace/components/renderers/PptxRenderer.tsx +4 -3
  289. package/src/modules/workspace/components/renderers/XlsxRenderer.tsx +4 -3
  290. package/src/modules/workspace/components/renderers/__tests__/DocxRenderer.test.tsx +12 -0
  291. package/src/modules/workspace/components/renderers/__tests__/DownloadFileButton.test.tsx +57 -9
  292. package/src/modules/workspace/components/renderers/__tests__/EmailRenderer.test.tsx +13 -1
  293. package/src/modules/workspace/components/renderers/__tests__/ImageRenderer.test.tsx +163 -0
  294. package/src/modules/workspace/components/renderers/__tests__/KbMarkdownView.test.tsx +237 -0
  295. package/src/modules/workspace/components/renderers/__tests__/MarkdownRenderer.test.tsx +108 -14
  296. package/src/modules/workspace/components/renderers/__tests__/PptxRenderer.test.tsx +14 -1
  297. package/src/modules/workspace/components/renderers/__tests__/XlsxRenderer.test.tsx +16 -1
  298. package/src/modules/workspace/components/renderers/__tests__/rendererSelection.test.tsx +66 -1
  299. package/src/modules/workspace/components/renderers/index.ts +53 -2
  300. package/src/modules/workspace/components/renderers/kbMarkdownPipeline.tsx +25 -4
  301. package/src/modules/workspace/components/renderers/rendererWorkspace.ts +40 -0
  302. package/src/modules/workspace/hooks/__tests__/useImageRevision.test.tsx +174 -0
  303. package/src/modules/workspace/hooks/__tests__/useOpenChangeRequests.test.tsx +179 -1
  304. package/src/modules/workspace/hooks/__tests__/useWorkspaceImageResolver.test.tsx +122 -0
  305. package/src/modules/workspace/hooks/__tests__/useWorkspaceState.test.tsx +892 -7
  306. package/src/modules/workspace/hooks/useImageRevision.ts +101 -0
  307. package/src/modules/workspace/hooks/useMergedWorkspaceTree.ts +89 -0
  308. package/src/modules/workspace/hooks/useWorkspaceImageResolver.ts +55 -0
  309. package/src/modules/workspace/hooks/useWorkspaceState.ts +438 -66
  310. package/src/modules/workspace/routing/__tests__/kb-routes.test.tsx +279 -3
  311. package/src/modules/workspace/routing/kb-routes.ts +207 -30
  312. package/src/modules/workspace/services/__tests__/workspace.api.test.ts +57 -1
  313. package/src/modules/workspace/services/workspace.api.ts +57 -4
  314. package/src/modules/workspace/state/__tests__/applied-request-clears-pending.test.tsx +343 -0
  315. package/src/modules/workspace/state/__tests__/upload-lands-where-it-was-dropped.test.tsx +158 -0
  316. package/src/modules/workspace/state/open-change-requests.tsx +100 -12
  317. package/src/modules/workspace/state/workspace.context.ts +130 -16
  318. package/src/modules/workspace/utils/__tests__/file-trace.test.ts +73 -0
  319. package/src/modules/workspace/utils/__tests__/fileTree.test.ts +234 -5
  320. package/src/modules/workspace/utils/__tests__/pasteLink.test.ts +76 -0
  321. package/src/modules/workspace/utils/__tests__/treeConfirm.test.ts +364 -0
  322. package/src/modules/workspace/utils/__tests__/uploadError.test.ts +35 -0
  323. package/src/modules/workspace/utils/file-trace.ts +50 -0
  324. package/src/modules/workspace/utils/fileTree.ts +126 -52
  325. package/src/modules/workspace/utils/frontmatter.ts +8 -4
  326. package/src/modules/workspace/utils/pasteLink.ts +90 -0
  327. package/src/modules/workspace/utils/treeConfirm.ts +338 -0
  328. package/src/modules/workspace/utils/uploadError.ts +29 -0
  329. package/src/shared/__tests__/marketplace-url.test.ts +59 -0
  330. package/src/shared/components/Badge.tsx +3 -1
  331. package/src/shared/components/Banner.tsx +5 -1
  332. package/src/shared/components/Button.tsx +16 -2
  333. package/src/shared/components/Dialog.tsx +27 -11
  334. package/src/shared/components/Menu.tsx +13 -1
  335. package/src/shared/components/PageShell.tsx +13 -8
  336. package/src/shared/components/__tests__/primitives.test.tsx +116 -2
  337. package/src/shared/components/__tests__/useFocusHandoff.test.tsx +192 -0
  338. package/src/shared/components/index.ts +2 -0
  339. package/src/shared/components/useDismissableMenu.ts +32 -10
  340. package/src/shared/components/useFocusHandoff.ts +51 -0
  341. package/src/shared/components/useLatestRef.ts +28 -0
  342. package/src/shared/markdown/Markdown.tsx +12 -3
  343. package/src/shared/markdown/__tests__/escapeSpacesInLinkDestinations.test.ts +39 -0
  344. package/src/shared/markdown/hrefs.ts +50 -0
  345. package/src/shared/marketplace-url.ts +118 -0
  346. package/src/shared/mcp/ChatGptInstallLink.tsx +3 -3
  347. package/src/shared/mcp/ConnectionInstructions.tsx +38 -27
  348. package/src/shared/mcp/__tests__/connect-snippets.test.ts +3 -3
  349. package/src/shared/mcp/connect-snippets.ts +14 -9
  350. package/src/shared/mcp/index.ts +1 -1
  351. package/src/shared/theme/__tests__/header-band.test.ts +197 -0
  352. package/src/shared/theme/header.ts +75 -0
  353. package/src/shared/theme/measure.ts +7 -4
  354. package/src/shared/theme/tokens.css +34 -0
  355. package/src/modules/library/__tests__/PluginsIndexPage.test.tsx +0 -363
  356. package/src/modules/library/__tests__/PluginsSidebar.locked.test.tsx +0 -97
  357. package/src/modules/library/components/PluginsIndexPage.tsx +0 -265
  358. package/src/modules/update-check/__tests__/UpdateBanner.test.tsx +0 -126
  359. package/src/modules/update-check/components/UpdateBanner.tsx +0 -92
  360. package/src/modules/update-check/services/update-check.api.ts +0 -24
@@ -6,6 +6,7 @@ import {
6
6
  } from 'react';
7
7
  import { X } from 'lucide-react';
8
8
  import { useModalLayer } from './useModalLayer';
9
+ import { useLatestRef } from './useLatestRef';
9
10
 
10
11
  /**
11
12
  * The one centered-modal primitive for the app. Before this existed every
@@ -78,20 +79,29 @@ export function Dialog({
78
79
 
79
80
  // Callers pass a fresh `onClose` arrow each render; mirror it into a ref so
80
81
  // the trap effect below doesn't re-fire (and re-snapshot focus) every render.
81
- const onCloseRef = useRef(onClose);
82
- useEffect(() => {
83
- onCloseRef.current = onClose;
84
- }, [onClose]);
85
-
86
- const busyRef = useRef(busy);
87
- useEffect(() => {
88
- busyRef.current = busy;
89
- }, [busy]);
82
+ const onCloseRef = useLatestRef(onClose);
83
+ const busyRef = useLatestRef(busy);
90
84
 
91
85
  // Only the topmost open modal layer reacts to Escape / backdrop clicks, so a
92
86
  // nested modal (its own or a hand-rolled one that opts in) can be dismissed
93
87
  // without also closing this dialog behind it.
94
88
  const isTopLayer = useModalLayer(open);
89
+ // Whether the pointer went DOWN on the scrim itself, with this dialog as
90
+ // the top layer. Both halves matter, and both must be judged at mousedown:
91
+ //
92
+ // - A menu inside the dialog dismisses itself on `mousedown` and pops its
93
+ // layer as it unmounts, so by the time the scrim's `click` fires the
94
+ // dialog is topmost again — and would close on the same gesture that
95
+ // closed the menu. Escape peels one layer at a time; so does the scrim.
96
+ // - A drag that STARTS inside the panel and releases on the scrim (text
97
+ // selection overshooting the panel edge) makes the browser fire `click`
98
+ // on their common ancestor — this scrim container. The panel's own
99
+ // stopPropagation can't help: the click never happened inside it. Only
100
+ // the mousedown target says where the gesture began.
101
+ //
102
+ // Recorded here rather than in each menu, so no menu has to learn to defer
103
+ // its own pop.
104
+ const scrimPointerDown = useRef(false);
95
105
 
96
106
  // Dialog a11y: move focus into the panel on open, trap focus + Escape closes
97
107
  // + restore focus on close.
@@ -140,15 +150,21 @@ export function Dialog({
140
150
  document.removeEventListener('keydown', onKeyDown);
141
151
  previouslyFocused?.focus?.();
142
152
  };
143
- }, [open, isTopLayer]);
153
+ // The refs are stable for the component's life; listed for the linter.
154
+ }, [open, isTopLayer, onCloseRef, busyRef]);
144
155
 
145
156
  if (!open) return null;
146
157
 
147
158
  return (
148
159
  <div
149
160
  className="fixed inset-0 z-50 bg-scrim flex items-center justify-center p-4"
161
+ onMouseDown={(e) => {
162
+ scrimPointerDown.current = e.target === e.currentTarget && isTopLayer();
163
+ }}
150
164
  onClick={() => {
151
- if (busy || !isTopLayer()) return;
165
+ const startedOnScrim = scrimPointerDown.current;
166
+ scrimPointerDown.current = false;
167
+ if (busy || !startedOnScrim || !isTopLayer()) return;
152
168
  onClose();
153
169
  }}
154
170
  >
@@ -35,6 +35,14 @@ export function MenuPanel({ className, children, ...rest }: MenuPanelProps) {
35
35
  );
36
36
  }
37
37
 
38
+ /**
39
+ * `aria-disabled` is styled the same as `disabled`, and is the spelling to
40
+ * reach for when the item must still be HOVERABLE and FOCUSABLE — a native
41
+ * `disabled` button suppresses pointer events on most engines, which takes its
42
+ * `title` tooltip with it, and drops the item out of the tab order so the
43
+ * keyboard user never learns it exists. It does not block activation on its
44
+ * own: an `aria-disabled` item's `onClick` must return early.
45
+ */
38
46
  export interface MenuItemProps extends ButtonHTMLAttributes<HTMLButtonElement> {
39
47
  tone?: 'default' | 'danger';
40
48
  /** Visual checked/current state. Set `aria-checked`/`aria-current` yourself. */
@@ -58,9 +66,13 @@ export function MenuItem({
58
66
  className={cn(
59
67
  'flex w-full items-center gap-2 rounded-sm px-2.5 py-2 text-left text-ui',
60
68
  'transition-colors disabled:cursor-not-allowed disabled:opacity-50',
69
+ 'aria-disabled:cursor-not-allowed aria-disabled:opacity-50 aria-disabled:hover:bg-transparent',
61
70
  tone === 'danger'
62
71
  ? 'text-danger hover:bg-danger-soft'
63
- : 'text-ink-muted hover:bg-hover hover:text-ink',
72
+ // The aria-disabled text override is tone-local because the hover it
73
+ // undoes is: only the default tone brightens to `text-ink`, and a
74
+ // disabled row that still lights up on hover reads as usable.
75
+ : 'text-ink-muted hover:bg-hover hover:text-ink aria-disabled:hover:text-ink-muted',
64
76
  active && 'font-medium text-ink',
65
77
  className,
66
78
  )}
@@ -9,19 +9,21 @@ export type PageShellWidth = keyof typeof WIDTH_CLASS;
9
9
 
10
10
  /**
11
11
  * Minimal shared chrome for the shell's standalone routed pages (Secrets,
12
- * External agent access, Roles & Members): a full-height scrolling canvas
12
+ * External agent access, App roles): a full-height scrolling canvas
13
13
  * with a centered max-width column, a page-title row and a white content
14
14
  * card. Deliberately tiny — it mirrors the Tailwind idioms the tools
15
15
  * explorer page already uses; it is not a design system.
16
16
  *
17
17
  * `padded` drops the card's default padding for pages that own their inner
18
18
  * layout (e.g. a tab strip flush against the card's top edge).
19
+ * `card={false}` leaves surface ownership to pages with multiple peer cards.
19
20
  */
20
21
  export function PageShell({
21
22
  title,
22
23
  actions,
23
24
  width = '3xl',
24
25
  padded = true,
26
+ card = true,
25
27
  children,
26
28
  }: {
27
29
  title: string;
@@ -29,6 +31,7 @@ export function PageShell({
29
31
  actions?: ReactNode;
30
32
  width?: PageShellWidth;
31
33
  padded?: boolean;
34
+ card?: boolean;
32
35
  children: ReactNode;
33
36
  }) {
34
37
  return (
@@ -41,13 +44,15 @@ export function PageShell({
41
44
  <h1 className="text-lg font-semibold text-ink">{title}</h1>
42
45
  {actions && <div className="flex items-center gap-2">{actions}</div>}
43
46
  </header>
44
- <section
45
- className={`bg-white border border-line rounded-lg ${
46
- padded ? 'p-4' : 'overflow-hidden'
47
- }`}
48
- >
49
- {children}
50
- </section>
47
+ {card ? (
48
+ <section
49
+ className={`bg-white border border-line rounded-lg ${
50
+ padded ? 'p-4' : 'overflow-hidden'
51
+ }`}
52
+ >
53
+ {children}
54
+ </section>
55
+ ) : children}
51
56
  </div>
52
57
  </div>
53
58
  );
@@ -1,12 +1,14 @@
1
1
  import { describe, it, expect, vi } from 'vitest';
2
- import { render, screen } from '@testing-library/react';
2
+ import { fireEvent, render, screen } from '@testing-library/react';
3
3
  import userEvent from '@testing-library/user-event';
4
- import type { ReactElement } from 'react';
4
+ import { useState, type ReactElement } from 'react';
5
5
  import { cn } from '../../../lib/utils';
6
6
  import {
7
7
  Button,
8
8
  buttonClasses,
9
+ Dialog,
9
10
  IconButton,
11
+ useDismissableMenu,
10
12
  Surface,
11
13
  ListRow,
12
14
  Badge,
@@ -331,3 +333,115 @@ describe('Menu', () => {
331
333
  expect(screen.getByText('Appearance')).toBeInTheDocument();
332
334
  });
333
335
  });
336
+
337
+ describe('Dialog', () => {
338
+ /**
339
+ * A menu hosted inside the dialog, built the way `ManageAccessDialog`'s
340
+ * are: it dismisses on an outside `mousedown`, and the HOOK holds the top
341
+ * modal layer while it is open (registering a second layer here would sit
342
+ * above the hook's own and steal its Escape). The layer pops when the menu
343
+ * unmounts — before the same gesture's `click` reaches the scrim.
344
+ */
345
+ function HostedMenu({ name, onClose }: { name?: string; onClose(): void }) {
346
+ const ref = useDismissableMenu<HTMLDivElement>({ open: true, onClose });
347
+ return <div ref={ref} role="menu" aria-label={name ?? 'menu'} />;
348
+ }
349
+ // The menu opens from a control inside the dialog, so its layer lands on
350
+ // the stack ABOVE the dialog's — mounted together, the child's effect
351
+ // would run first and put it underneath.
352
+ function Host({ onClose }: { onClose(): void }) {
353
+ const [menuOpen, setMenuOpen] = useState(false);
354
+ return (
355
+ <Dialog open onClose={onClose} title="Host">
356
+ <button onClick={() => setMenuOpen(true)}>Open the menu</button>
357
+ {menuOpen && <HostedMenu onClose={() => setMenuOpen(false)} />}
358
+ </Dialog>
359
+ );
360
+ }
361
+
362
+ it('a scrim click that dismissed a nested layer on mousedown does not also close the dialog', async () => {
363
+ const user = userEvent.setup();
364
+ const onClose = vi.fn();
365
+ render(<Host onClose={onClose} />);
366
+ await user.click(screen.getByRole('button', { name: 'Open the menu' }));
367
+ expect(screen.getByRole('menu')).toBeInTheDocument();
368
+
369
+ const scrim = screen.getByRole('dialog').parentElement!;
370
+ await user.click(scrim);
371
+ // The menu went on mousedown; the click that followed belonged to it.
372
+ expect(screen.queryByRole('menu')).not.toBeInTheDocument();
373
+ expect(onClose).not.toHaveBeenCalled();
374
+
375
+ // The next scrim click began with the dialog on top, and closes it.
376
+ await user.click(scrim);
377
+ expect(onClose).toHaveBeenCalledTimes(1);
378
+ });
379
+
380
+ it('a drag that starts inside the panel and releases on the scrim does not close the dialog', async () => {
381
+ // Selecting text and overshooting the panel edge makes the browser fire
382
+ // `click` on the common ancestor of mousedown and mouseup — the scrim
383
+ // container. The panel's stopPropagation never sees that click, so the
384
+ // scrim must judge the gesture by where the POINTER WENT DOWN.
385
+ const user = userEvent.setup();
386
+ const onClose = vi.fn();
387
+ render(
388
+ <Dialog open onClose={onClose} title="Host">
389
+ <p>Some selectable text</p>
390
+ </Dialog>,
391
+ );
392
+ const panel = screen.getByRole('dialog');
393
+ const scrim = panel.parentElement!;
394
+
395
+ fireEvent.mouseDown(panel);
396
+ fireEvent.mouseUp(scrim);
397
+ fireEvent.click(scrim);
398
+ expect(onClose).not.toHaveBeenCalled();
399
+
400
+ // A genuine scrim click — down and up on the scrim — still closes.
401
+ await user.click(scrim);
402
+ expect(onClose).toHaveBeenCalledTimes(1);
403
+ });
404
+
405
+ it('Escape peels one layer at a time when two menus are open above the dialog', async () => {
406
+ // Reachable by keyboard only: opening a menu by Enter fires no mousedown,
407
+ // so nothing dismisses the first menu when the second opens. Each press
408
+ // of Escape must close exactly the topmost layer, newest first — never
409
+ // both menus, and never the dialog underneath them.
410
+ const user = userEvent.setup();
411
+ const onClose = vi.fn();
412
+ function TwoMenuHost() {
413
+ const [first, setFirst] = useState(false);
414
+ const [second, setSecond] = useState(false);
415
+ return (
416
+ <Dialog open onClose={onClose} title="Host">
417
+ <button onClick={() => setFirst(true)}>Open first</button>
418
+ <button onClick={() => setSecond(true)}>Open second</button>
419
+ {first && <HostedMenu name="first" onClose={() => setFirst(false)} />}
420
+ {second && <HostedMenu name="second" onClose={() => setSecond(false)} />}
421
+ </Dialog>
422
+ );
423
+ }
424
+ render(<TwoMenuHost />);
425
+ // Enter, not click: a click's mousedown would dismiss the first menu
426
+ // before the second ever opens — which is why this state is
427
+ // keyboard-only in the first place.
428
+ screen.getByRole('button', { name: 'Open first' }).focus();
429
+ await user.keyboard('{Enter}');
430
+ screen.getByRole('button', { name: 'Open second' }).focus();
431
+ await user.keyboard('{Enter}');
432
+ expect(screen.getAllByRole('menu')).toHaveLength(2);
433
+
434
+ await user.keyboard('{Escape}');
435
+ // Only the newest layer went; its sibling and the dialog stand.
436
+ expect(screen.getByRole('menu', { name: 'first' })).toBeInTheDocument();
437
+ expect(screen.queryByRole('menu', { name: 'second' })).not.toBeInTheDocument();
438
+ expect(onClose).not.toHaveBeenCalled();
439
+
440
+ await user.keyboard('{Escape}');
441
+ expect(screen.queryByRole('menu')).not.toBeInTheDocument();
442
+ expect(onClose).not.toHaveBeenCalled();
443
+
444
+ await user.keyboard('{Escape}');
445
+ expect(onClose).toHaveBeenCalledTimes(1);
446
+ });
447
+ });
@@ -0,0 +1,192 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import { render, screen } from '@testing-library/react';
3
+ import userEvent from '@testing-library/user-event';
4
+ import { useEffect, useRef, useState } from 'react';
5
+ import { useFocusHandoff } from '../useFocusHandoff';
6
+
7
+ type View = 'doc' | 'log' | 'diff';
8
+
9
+ /**
10
+ * Two views sharing one column, each with the button that swaps to the other
11
+ * — the shape the Knowledge viewer and the skill page both have. The column
12
+ * also carries a control that swaps the view WITHOUT naming a destination
13
+ * for focus, standing in for a git poll or a file switch.
14
+ *
15
+ * The `key` on each branch is what makes this a test. Without it React sees
16
+ * a `<button>` replacing a `<button>` in the same slot and UPDATES the same
17
+ * DOM node instead of unmounting it: focus never falls to `document`, and
18
+ * every assertion below passes with the hook's `.focus()` deleted. Keys force
19
+ * the real unmount/remount the hook exists for, so the tests can fail.
20
+ */
21
+ function Column({ initial = 'doc' }: { initial?: View }) {
22
+ const [view, setView] = useState<View>(initial);
23
+ const openRef = useRef<HTMLButtonElement>(null);
24
+ const closeRef = useRef<HTMLButtonElement>(null);
25
+ const handoff = useFocusHandoff(view);
26
+ return (
27
+ <>
28
+ <button onClick={() => setView((v) => (v === 'doc' ? 'log' : 'doc'))}>Swap unasked</button>
29
+ {view === 'doc' ? (
30
+ <button
31
+ key="doc"
32
+ ref={openRef}
33
+ onClick={() => {
34
+ handoff('log', closeRef);
35
+ setView('log');
36
+ }}
37
+ >
38
+ Open the log
39
+ </button>
40
+ ) : view === 'log' ? (
41
+ <button
42
+ key="log"
43
+ ref={closeRef}
44
+ onClick={() => {
45
+ handoff('doc', openRef);
46
+ setView('doc');
47
+ }}
48
+ >
49
+ Back to the document
50
+ </button>
51
+ ) : (
52
+ <button
53
+ key="diff"
54
+ onClick={() => {
55
+ // The first named control is not part of the document view;
56
+ // the second is.
57
+ handoff('doc', closeRef, openRef);
58
+ setView('doc');
59
+ }}
60
+ >
61
+ Leave the comparison
62
+ </button>
63
+ )}
64
+ </>
65
+ );
66
+ }
67
+
68
+ describe('useFocusHandoff', () => {
69
+ it('moves focus to the named control once the swap has landed, both ways', async () => {
70
+ const user = userEvent.setup();
71
+ render(<Column />);
72
+
73
+ await user.click(screen.getByRole('button', { name: 'Open the log' }));
74
+ expect(screen.getByRole('button', { name: 'Back to the document' })).toHaveFocus();
75
+
76
+ await user.click(screen.getByRole('button', { name: 'Back to the document' }));
77
+ expect(screen.getByRole('button', { name: 'Open the log' })).toHaveFocus();
78
+ });
79
+
80
+ it('falls through to the next named control when the first is not on screen', async () => {
81
+ const user = userEvent.setup();
82
+ render(<Column initial="diff" />);
83
+
84
+ await user.click(screen.getByRole('button', { name: 'Leave the comparison' }));
85
+ expect(screen.getByRole('button', { name: 'Open the log' })).toHaveFocus();
86
+ });
87
+
88
+ it('moves nothing for a swap the user did not make', async () => {
89
+ const user = userEvent.setup();
90
+ render(<Column />);
91
+
92
+ const unasked = screen.getByRole('button', { name: 'Swap unasked' });
93
+ await user.click(unasked);
94
+ expect(screen.getByRole('button', { name: 'Back to the document' })).toBeInTheDocument();
95
+ // The control that swapped the view is still on screen and keeps focus;
96
+ // nothing was named, so nothing moved.
97
+ expect(unasked).toHaveFocus();
98
+ });
99
+
100
+ /**
101
+ * The request names the state it is for. A commit that lands somewhere
102
+ * else — the stale passive effects React flushes ahead of a click's render
103
+ * are the case that bit — leaves it waiting for the commit that gets there.
104
+ */
105
+ it('waits for the named state rather than the next commit', async () => {
106
+ function Probe() {
107
+ const [view, setView] = useState<View>('doc');
108
+ const target = useRef<HTMLButtonElement>(null);
109
+ const handoff = useFocusHandoff(view);
110
+ return (
111
+ <>
112
+ <button
113
+ onClick={() => {
114
+ handoff('log', target);
115
+ setView('diff');
116
+ }}
117
+ >
118
+ Ask for the log, land elsewhere
119
+ </button>
120
+ <button onClick={() => setView('log')}>Now the log</button>
121
+ {view === 'log' && <button ref={target}>Landed</button>}
122
+ <output>{view}</output>
123
+ </>
124
+ );
125
+ }
126
+ const user = userEvent.setup();
127
+ render(<Probe />);
128
+
129
+ const ask = screen.getByRole('button', { name: 'Ask for the log, land elsewhere' });
130
+ await user.click(ask);
131
+ expect(screen.getByRole('status')).toHaveTextContent('diff');
132
+ expect(ask).toHaveFocus();
133
+
134
+ await user.click(screen.getByRole('button', { name: 'Now the log' }));
135
+ expect(screen.getByRole('button', { name: 'Landed' })).toHaveFocus();
136
+ });
137
+
138
+ /**
139
+ * The handoff runs in a LAYOUT effect, so focus is back before the browser
140
+ * paints the commit — otherwise there is a real frame on screen with focus
141
+ * on `document.body`, which is the thing this hook exists to prevent.
142
+ *
143
+ * "Before paint" is not observable in jsdom, so this asserts the ordering
144
+ * that produces it: layout effects all run ahead of every passive effect,
145
+ * children's included. The probe reports from a CHILD's passive effect — it
146
+ * sees the focused target with a layout effect, and `body` with a passive
147
+ * one, because a passive handoff in the parent would queue behind it.
148
+ */
149
+ it('restores focus before passive effects run, not after', async () => {
150
+ const seen: string[] = [];
151
+ function Reporter() {
152
+ useEffect(() => {
153
+ const active = document.activeElement;
154
+ seen.push(
155
+ !active || active === document.body ? 'BODY' : (active.textContent ?? active.tagName),
156
+ );
157
+ });
158
+ return null;
159
+ }
160
+ function Probe() {
161
+ const [view, setView] = useState<View>('doc');
162
+ const closeRef = useRef<HTMLButtonElement>(null);
163
+ const handoff = useFocusHandoff(view);
164
+ return (
165
+ <>
166
+ {view === 'doc' ? (
167
+ <button
168
+ key="doc"
169
+ onClick={() => {
170
+ handoff('log', closeRef);
171
+ setView('log');
172
+ }}
173
+ >
174
+ Open the log
175
+ </button>
176
+ ) : (
177
+ <button key="log" ref={closeRef}>
178
+ Back to the document
179
+ </button>
180
+ )}
181
+ <Reporter />
182
+ </>
183
+ );
184
+ }
185
+ const user = userEvent.setup();
186
+ render(<Probe />);
187
+ seen.length = 0;
188
+
189
+ await user.click(screen.getByRole('button', { name: 'Open the log' }));
190
+ expect(seen).toEqual(['Back to the document']);
191
+ });
192
+ });
@@ -44,7 +44,9 @@ export type { DialogSize } from './Dialog';
44
44
  export { PageShell } from './PageShell';
45
45
  export type { PageShellWidth } from './PageShell';
46
46
  export { useModalLayer } from './useModalLayer';
47
+ export { useLatestRef } from './useLatestRef';
47
48
  export { useDismissableMenu } from './useDismissableMenu';
48
49
  export type { DismissableMenuOptions } from './useDismissableMenu';
50
+ export { useFocusHandoff } from './useFocusHandoff';
49
51
  export { usePointerMenuPosition } from './usePointerMenuPosition';
50
52
  export type { PointerMenuPosition } from './usePointerMenuPosition';
@@ -1,4 +1,6 @@
1
1
  import { useEffect, useRef, type RefObject } from 'react';
2
+ import { useModalLayer } from './useModalLayer';
3
+ import { useLatestRef } from './useLatestRef';
2
4
 
3
5
  /**
4
6
  * The behaviour `MenuPanel` deliberately does not provide.
@@ -15,14 +17,31 @@ import { useEffect, useRef, type RefObject } from 'react';
15
17
  * whatever opened the menu — otherwise focus is left on a node that just
16
18
  * unmounted and the next Tab starts from the top of the document.
17
19
  *
20
+ * The hook owns two contracts its callers used to carry:
21
+ *
22
+ * - **It is a modal layer.** An open menu registers on the modal-layer stack,
23
+ * and its Escape acts only while the menu is the TOPMOST layer. That is
24
+ * what makes Escape peel one layer at a time in every composition: a menu
25
+ * inside a `<Dialog>` closes before the dialog (the dialog's own Escape
26
+ * guard sees it is not topmost), and two menus open at once — reachable by
27
+ * keyboard, where no mousedown dismisses the first — close one per press,
28
+ * newest first, instead of both on one press. Outside-click is different on
29
+ * purpose: clicking away is "dismiss everything light-weight", so it stays
30
+ * unguarded.
31
+ * - **`onClose` may be a fresh arrow every render.** The hook mirrors it into
32
+ * a ref itself, so its document listeners subscribe once for the life of
33
+ * the open menu. Callers must not wrap it in their own ref-plus-stable-
34
+ * callback scaffolding — that pattern's drift is exactly what this replaces.
35
+ *
18
36
  * Returns the ref to put on the panel.
19
37
  */
20
38
  export interface DismissableMenuOptions {
21
39
  open: boolean;
40
+ /** Close the menu. May be a fresh arrow each render — the hook mirrors it. */
22
41
  onClose: () => void;
23
42
  /**
24
43
  * The control that opened the menu. Clicks on it are ignored (its own
25
- * handler toggles), and Escape hands focus back to it.
44
+ * handler toggles), and Escape hands focus back to it. A stable ref.
26
45
  */
27
46
  returnFocusTo?: RefObject<HTMLElement | null>;
28
47
  }
@@ -33,6 +52,8 @@ export function useDismissableMenu<T extends HTMLElement>({
33
52
  returnFocusTo,
34
53
  }: DismissableMenuOptions): RefObject<T | null> {
35
54
  const panelRef = useRef<T>(null);
55
+ const onCloseRef = useLatestRef(onClose);
56
+ const isTop = useModalLayer(open);
36
57
 
37
58
  useEffect(() => {
38
59
  if (!open) return;
@@ -43,19 +64,20 @@ export function useDismissableMenu<T extends HTMLElement>({
43
64
  // A click on the trigger is the trigger's business — closing here too
44
65
  // would make a toggle button close-then-reopen on a single click.
45
66
  if (returnFocusTo?.current?.contains(target)) return;
46
- onClose();
67
+ onCloseRef.current();
47
68
  }
48
69
 
49
70
  function onKey(e: KeyboardEvent) {
50
71
  if (e.key !== 'Escape') return;
51
- // Stops window-level Escape handlers from also acting on this key. It
52
- // does NOT protect against a `<Dialog>` hosting the menu — Dialog binds
53
- // on `document` too, and same-node listeners are unaffected by
54
- // stopPropagation. Nothing here mounts a menu inside a dialog; if
55
- // something ever does, the fix is `useModalLayer`, not a third
56
- // listener.
72
+ // Only the topmost layer owns this Escape. Same-node `document`
73
+ // listeners are unaffected by stopPropagation, so without this guard a
74
+ // second open menu — or the `<Dialog>` hosting this one — would act on
75
+ // the same keypress. Listeners run in subscription order (oldest
76
+ // first), so every layer below the top returns here and exactly one
77
+ // closes per press.
78
+ if (!isTop()) return;
57
79
  e.stopPropagation();
58
- onClose();
80
+ onCloseRef.current();
59
81
  returnFocusTo?.current?.focus();
60
82
  }
61
83
 
@@ -65,7 +87,7 @@ export function useDismissableMenu<T extends HTMLElement>({
65
87
  document.removeEventListener('mousedown', onPointerDown);
66
88
  document.removeEventListener('keydown', onKey);
67
89
  };
68
- }, [open, onClose, returnFocusTo]);
90
+ }, [open, isTop, returnFocusTo, onCloseRef]);
69
91
 
70
92
  return panelRef;
71
93
  }
@@ -0,0 +1,51 @@
1
+ import { useCallback, useLayoutEffect, useRef, type RefObject } from 'react';
2
+
3
+ /**
4
+ * Hands keyboard focus across a swap that unmounts the control the user just
5
+ * activated.
6
+ *
7
+ * Two views share one column: a document and its git log, say. The clock
8
+ * that opens the log sits in the document's bar, and the bar unmounts with
9
+ * the document; the pressed clock that closes it sits in the log's row, which
10
+ * unmounts with the log. Either way the button a keyboard user just pressed
11
+ * is gone from the DOM, focus falls to `document`, and the next Tab starts
12
+ * from the top of the page.
13
+ *
14
+ * So the click handler names the state the swap lands in and where focus
15
+ * should go once it has, BEFORE it changes that state:
16
+ *
17
+ * const handoff = useFocusHandoff(view);
18
+ * <button onClick={() => { handoff('log', pressedClockRef); setView('log'); }} />
19
+ *
20
+ * When `state` becomes the named value, focus moves to the first named ref
21
+ * that is on screen — name a fallback for a layout that does not render the
22
+ * first. Only a swap the USER made hands focus off: a change that arrives
23
+ * with no request behind it (a poll withdrawing the panel, a different file
24
+ * opening) moves nothing, because nothing was named.
25
+ *
26
+ * Naming the destination state is what makes the request wait for the right
27
+ * commit. A commit whose effects have not flushed yet when the user clicks
28
+ * (a fetch rejecting a moment before) has them flushed BEFORE the click's
29
+ * render; consumed there, the request would look for a control the swap has
30
+ * not mounted yet and find nothing.
31
+ *
32
+ * `useLayoutEffect`, not `useEffect`. The swap has already unmounted the
33
+ * pressed control, so focus is on `document.body` the moment the commit
34
+ * lands. A passive effect runs after the browser has painted that state —
35
+ * one painted frame with focus on the body, which is the very thing this
36
+ * hook exists to avoid. A layout effect restores it before the paint.
37
+ */
38
+ export function useFocusHandoff<S>(
39
+ state: S,
40
+ ): (after: S, ...to: RefObject<HTMLElement | null>[]) => void {
41
+ const pending = useRef<{ after: S; to: RefObject<HTMLElement | null>[] } | null>(null);
42
+ useLayoutEffect(() => {
43
+ const request = pending.current;
44
+ if (!request || !Object.is(request.after, state)) return;
45
+ pending.current = null;
46
+ request.to.find((ref) => ref.current)?.current?.focus();
47
+ }, [state]);
48
+ return useCallback((after: S, ...to: RefObject<HTMLElement | null>[]) => {
49
+ pending.current = { after, to };
50
+ }, []);
51
+ }
@@ -0,0 +1,28 @@
1
+ import { useLayoutEffect, useRef, type RefObject } from 'react';
2
+
3
+ /**
4
+ * Mirror a fresh-every-render value into a stable ref.
5
+ *
6
+ * The pattern this replaces was hand-rolled in three places (Dialog's
7
+ * `onClose`/`busy`, AnchoredMenu's `onDismiss`, AdminRolesPage's `onCancel`)
8
+ * and exists for one reason: callers pass a fresh arrow each render, and an
9
+ * effect that lists it in its deps tears down and re-subscribes its document
10
+ * listeners on every render of an open overlay. Reading the value through
11
+ * this ref instead gives the effect a dependency-free view of the latest
12
+ * callback, so it subscribes once for the life of the overlay.
13
+ *
14
+ * The write happens in a LAYOUT effect — before the browser paints, and so
15
+ * before any document listener can fire for the next event. A passive
16
+ * effect (what the hand-rolled copies used) leaves a window after commit in
17
+ * which a keydown or click still reads the previous render's value: a
18
+ * dialog that had just become `busy` could close, a menu could call a
19
+ * callback the parent had already replaced. Do not read the ref during
20
+ * render; it is for event handlers and effects.
21
+ */
22
+ export function useLatestRef<T>(value: T): RefObject<T> {
23
+ const ref = useRef<T>(value);
24
+ useLayoutEffect(() => {
25
+ ref.current = value;
26
+ }, [value]);
27
+ return ref;
28
+ }