@powerhousedao/connect 6.2.3-dev.65 → 6.2.3-dev.67
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/CUSTOMIZING.md +77 -0
- package/README.md +18 -91
- package/RUNTIME-CONFIG.md +472 -0
- package/dist/{AddDriveModal-D_3jDwjp.js → AddDriveModal-BjgmiHJr.js} +6 -6
- package/dist/AddDriveModal-BjgmiHJr.js.map +1 -0
- package/dist/{ClearStorageModal-BWSktCmz.js → ClearStorageModal-_03VgDb5.js} +6 -6
- package/dist/ClearStorageModal-_03VgDb5.js.map +1 -0
- package/dist/{ConfirmDocumentUpgradeModal-CrU2Z1CL.js → ConfirmDocumentUpgradeModal-CoixS60F.js} +5 -5
- package/dist/ConfirmDocumentUpgradeModal-CoixS60F.js.map +1 -0
- package/dist/{CookiesPolicyModal-DQwsgDI9.js → CookiesPolicyModal-BpFjYc7T.js} +4 -4
- package/dist/{CookiesPolicyModal-DQwsgDI9.js.map → CookiesPolicyModal-BpFjYc7T.js.map} +1 -1
- package/dist/{CreateDocumentModal-Cf1APibL.js → CreateDocumentModal-B-cXzeOA.js} +10 -10
- package/dist/CreateDocumentModal-B-cXzeOA.js.map +1 -0
- package/dist/{DebugSettingsModal-FR4Ygn1r.js → DebugSettingsModal-CGScJ_r2.js} +8 -8
- package/dist/DebugSettingsModal-CGScJ_r2.js.map +1 -0
- package/dist/{DeleteDriveModal-lE9eCBua.js → DeleteDriveModal-1pAIayG_.js} +5 -5
- package/dist/DeleteDriveModal-1pAIayG_.js.map +1 -0
- package/dist/{DeleteItemModal-BFgcGsm3.js → DeleteItemModal-BUpqmFxS.js} +5 -5
- package/dist/DeleteItemModal-BUpqmFxS.js.map +1 -0
- package/dist/{DisclaimerModal-CF6JkIIu.js → DisclaimerModal-TIJXRYLF.js} +5 -5
- package/dist/DisclaimerModal-TIJXRYLF.js.map +1 -0
- package/dist/{DocumentVersionUnsupportedModal-Cm9Jb9W7.js → DocumentVersionUnsupportedModal-DH9Zzsyw.js} +5 -5
- package/dist/DocumentVersionUnsupportedModal-DH9Zzsyw.js.map +1 -0
- package/dist/{DownloadDocumentWithErrorsModal-CShKhfEQ.js → DownloadDocumentWithErrorsModal-Beh-xw8B.js} +5 -5
- package/dist/DownloadDocumentWithErrorsModal-Beh-xw8B.js.map +1 -0
- package/dist/{DriveAuthRequiredModal-CMwPUyZf.js → DriveAuthRequiredModal-XTcoJKvj.js} +6 -6
- package/dist/DriveAuthRequiredModal-XTcoJKvj.js.map +1 -0
- package/dist/{DriveSettingsModal-BSImj4BH.js → DriveSettingsModal-DZKawN7w.js} +5 -5
- package/dist/DriveSettingsModal-DZKawN7w.js.map +1 -0
- package/dist/{InspectorModal-Df_Dj4Gy.js → InspectorModal-DA_TGmM6.js} +16 -16
- package/dist/InspectorModal-DA_TGmM6.js.map +1 -0
- package/dist/{LoginModal-DT_05uva.js → LoginModal-O06ZvWFI.js} +6 -6
- package/dist/LoginModal-O06ZvWFI.js.map +1 -0
- package/dist/{OpenFileDocumentsModal-X9GnX2Bk.js → OpenFileDocumentsModal-BNHD0vg9.js} +6 -6
- package/dist/OpenFileDocumentsModal-BNHD0vg9.js.map +1 -0
- package/dist/{UpgradeDriveModal-DvM-PNWe.js → UpgradeDriveModal-CCWKp5yn.js} +5 -5
- package/dist/UpgradeDriveModal-CCWKp5yn.js.map +1 -0
- package/dist/{app-loader-FBmwAnUq.js → app-loader-CEN_4I3I.js} +149 -196
- package/dist/app-loader-CEN_4I3I.js.map +1 -0
- package/dist/app-loader-Cj2p8L1I.js +4 -0
- package/dist/{app-skeleton-gzg8cRzm.js → app-skeleton-BFjvlTWd.js} +11 -11
- package/dist/app-skeleton-BFjvlTWd.js.map +1 -0
- package/dist/{app-skeleton-DYLZ7npI.js → app-skeleton-DFg65Rxa.js} +3 -3
- package/dist/{boot-CC_DgQKX.js → boot-JTGLJtmJ.js} +6 -6
- package/dist/boot-JTGLJtmJ.js.map +1 -0
- package/dist/{build-info-D89jTqV-.js → build-info-DkY9PU7c.js} +5 -5
- package/dist/{build-info-D89jTqV-.js.map → build-info-DkY9PU7c.js.map} +1 -1
- package/dist/{components-Ksj8WTJ5.js → components-2wvJ3_Ho.js} +11 -10
- package/dist/{components-Ksj8WTJ5.js.map → components-2wvJ3_Ho.js.map} +1 -1
- package/dist/{connect.config-uZF-gnvV.js → connect.config-D1pGNmaF.js} +4 -4
- package/dist/connect.config-D1pGNmaF.js.map +1 -0
- package/dist/{connection-state-C_477Kr_.js → connection-state-B6fleM37.js} +6 -6
- package/dist/connection-state-B6fleM37.js.map +1 -0
- package/dist/{cookie-banner-HPgyuHM5.js → cookie-banner-CAvd3PC3.js} +6 -6
- package/dist/{cookie-banner-HPgyuHM5.js.map → cookie-banner-CAvd3PC3.js.map} +1 -1
- package/dist/document-editor-container-BnEjlmaN.js +307 -0
- package/dist/document-editor-container-BnEjlmaN.js.map +1 -0
- package/dist/document-editor-container-kgS38mkb.js +4 -0
- package/dist/error-boundary-BsUBww61.js +155 -0
- package/dist/error-boundary-BsUBww61.js.map +1 -0
- package/dist/generic.d.ts +116 -0
- package/dist/generic.d.ts.map +1 -0
- package/dist/generic.js +31 -0
- package/dist/generic.js.map +1 -0
- package/dist/{i18n-CTgT1HG-.js → i18n-D9WYPgk9.js} +4 -4
- package/dist/{i18n-CTgT1HG-.js.map → i18n-D9WYPgk9.js.map} +1 -1
- package/dist/index-B4g8swZG.d.ts +4 -0
- package/dist/layout-BOX6fL5v.js +5 -0
- package/dist/layout.d.ts +2 -28
- package/dist/layout.js +4 -6
- package/dist/{load-B-M2dI6C.js → load-CCCHqC0d.js} +11 -11
- package/dist/{load-B-M2dI6C.js.map → load-CCCHqC0d.js.map} +1 -1
- package/dist/load-runtime-config-Dhy-b5wT.js +14 -0
- package/dist/load-runtime-config-Dhy-b5wT.js.map +1 -0
- package/dist/main.js +2 -2
- package/dist/{open-file-uploads-BcyWmUZn.js → open-file-uploads-B5pr1sA2.js} +4 -4
- package/dist/{open-file-uploads-BcyWmUZn.js.map → open-file-uploads-B5pr1sA2.js.map} +1 -1
- package/dist/{package-manager-BkFRzovd.js → package-manager-x_fK8Hzm.js} +92 -60
- package/dist/package-manager-x_fK8Hzm.js.map +1 -0
- package/dist/{pglite-seed-BsEPByVM.js → pglite-seed-eGzXMld2.js} +4 -4
- package/dist/{pglite-seed-BsEPByVM.js.map → pglite-seed-eGzXMld2.js.map} +1 -1
- package/dist/{plugin-host--lBWChr9.js → plugins-B9VBgzio.js} +75 -83
- package/dist/plugins-B9VBgzio.js.map +1 -0
- package/dist/{preferences-store-DANUajdg.js → preferences-store-CSqauT9V.js} +5 -5
- package/dist/preferences-store-CSqauT9V.js.map +1 -0
- package/dist/prerender.d.ts +38 -0
- package/dist/prerender.d.ts.map +1 -0
- package/dist/prerender.js +177 -0
- package/dist/prerender.js.map +1 -0
- package/dist/{prerendered-shell-DxCUDEXL.js → prerendered-shell-peKE7AqI.js} +10 -4
- package/dist/prerendered-shell-peKE7AqI.js.map +1 -0
- package/dist/{reactor-CMXWKWup.js → reactor-BmI-D8O-.js} +25 -156
- package/dist/reactor-BmI-D8O-.js.map +1 -0
- package/dist/{registerServiceWorker-CkVxA2KC.js → registerServiceWorker-APlHkrmH.js} +4 -4
- package/dist/{registerServiceWorker-CkVxA2KC.js.map → registerServiceWorker-APlHkrmH.js.map} +1 -1
- package/dist/root-B1Pq9x6S.js +24 -0
- package/dist/root-B1Pq9x6S.js.map +1 -0
- package/dist/route-tree.d.ts +147 -156
- package/dist/route-tree.d.ts.map +1 -1
- package/dist/route-tree.js +93 -169
- package/dist/route-tree.js.map +1 -1
- package/dist/route-views-BF0p-4Fi.js +60 -0
- package/dist/route-views-BF0p-4Fi.js.map +1 -0
- package/dist/route-views-CTARvT5N.js +55 -0
- package/dist/route-views-CTARvT5N.js.map +1 -0
- package/dist/route-views-D8I-1PWU.js +4 -0
- package/dist/route-views.d.ts +7 -0
- package/dist/route-views.d.ts.map +1 -0
- package/dist/route-views.js +4 -0
- package/dist/router-BguOMBUh.js +4 -0
- package/dist/router-L9X9U-97.js +46 -0
- package/dist/router-L9X9U-97.js.map +1 -0
- package/dist/router.d.ts +1 -3
- package/dist/router.js +3 -7
- package/dist/sentry-Cuc_Nbba.js +22 -0
- package/dist/sentry-Cuc_Nbba.js.map +1 -0
- package/dist/{settings-D7lXsfBl.js → settings-DjQfTrBe.js} +488 -22
- package/dist/settings-DjQfTrBe.js.map +1 -0
- package/dist/settings-tabs-iTlo2pYz.js +365 -0
- package/dist/settings-tabs-iTlo2pYz.js.map +1 -0
- package/dist/shell-core-head.html +2 -0
- package/dist/shell-core.html +1 -0
- package/dist/shell-head.html +2 -1
- package/dist/shell-plugins.json +1 -0
- package/dist/shell.html +1 -1
- package/dist/start-connect.d.ts +5 -9
- package/dist/start-connect.d.ts.map +1 -1
- package/dist/start-connect.js +5 -6
- package/dist/start-connect.js.map +1 -1
- package/dist/style.css +3127 -4014
- package/dist/ui-b6sMhi5V.js +66 -0
- package/dist/ui-b6sMhi5V.js.map +1 -0
- package/dist/{use-renown-login-BzOSQETV.js → use-renown-login-dPpDOYq5.js} +4 -4
- package/dist/use-renown-login-dPpDOYq5.js.map +1 -0
- package/docs/customizing/data-and-navigation.md +177 -0
- package/docs/customizing/hosts-and-plugins.md +65 -0
- package/docs/customizing/layout.md +149 -0
- package/docs/customizing/modals.md +78 -0
- package/docs/customizing/overrides.md +113 -0
- package/docs/customizing/packages.md +38 -0
- package/docs/customizing/pages.md +136 -0
- package/docs/customizing/styles-and-branding.md +41 -0
- package/docs/customizing/types-and-troubleshooting.md +44 -0
- package/package.json +41 -18
- package/scripts/prerender-shell.ts +35 -84
- package/skills/customize-connect/SKILL.md +74 -0
- package/src/route-tree.ts +3 -0
- package/src/routeTree.gen.ts +134 -192
- package/src/router/index.ts +2 -51
- package/src/router/register.ts +1 -1
- package/src/routes/__root.tsx +8 -24
- package/src/routes/_app/$.tsx +13 -0
- package/src/routes/_app/d/$driveSlug/{-$nodeSlug}.tsx +13 -0
- package/src/routes/_app/d/$driveSlug.tsx +13 -0
- package/src/routes/_app/index.tsx +13 -0
- package/src/routes/_app/settings/appearance.tsx +13 -0
- package/src/routes/_app/settings/packages.tsx +13 -0
- package/src/routes/_app/settings.tsx +13 -0
- package/src/routes/_app.tsx +13 -0
- package/style.css +5 -22
- package/tailwind.css +12 -0
- package/dist/AddDriveModal-D_3jDwjp.js.map +0 -1
- package/dist/ClearStorageModal-BWSktCmz.js.map +0 -1
- package/dist/ConfirmDocumentUpgradeModal-CrU2Z1CL.js.map +0 -1
- package/dist/CreateDocumentModal-Cf1APibL.js.map +0 -1
- package/dist/DebugSettingsModal-FR4Ygn1r.js.map +0 -1
- package/dist/DeleteDriveModal-lE9eCBua.js.map +0 -1
- package/dist/DeleteItemModal-BFgcGsm3.js.map +0 -1
- package/dist/DisclaimerModal-CF6JkIIu.js.map +0 -1
- package/dist/DocumentVersionUnsupportedModal-Cm9Jb9W7.js.map +0 -1
- package/dist/DownloadDocumentWithErrorsModal-CShKhfEQ.js.map +0 -1
- package/dist/DriveAuthRequiredModal-CMwPUyZf.js.map +0 -1
- package/dist/DriveSettingsModal-BSImj4BH.js.map +0 -1
- package/dist/InspectorModal-Df_Dj4Gy.js.map +0 -1
- package/dist/LoginModal-DT_05uva.js.map +0 -1
- package/dist/MissingPackageModal-DtISKgub.js +0 -49
- package/dist/MissingPackageModal-DtISKgub.js.map +0 -1
- package/dist/OpenFileDocumentsModal-X9GnX2Bk.js.map +0 -1
- package/dist/UpgradeDriveModal-DvM-PNWe.js.map +0 -1
- package/dist/app-layout-BIq-ZW-6.js +0 -394
- package/dist/app-layout-BIq-ZW-6.js.map +0 -1
- package/dist/app-loader-DWVnAJhQ.js +0 -4
- package/dist/app-loader-FBmwAnUq.js.map +0 -1
- package/dist/app-skeleton-gzg8cRzm.js.map +0 -1
- package/dist/boot-CC_DgQKX.js.map +0 -1
- package/dist/connect-router-KmNBGS0G.js +0 -434
- package/dist/connect-router-KmNBGS0G.js.map +0 -1
- package/dist/connect.config-uZF-gnvV.js.map +0 -1
- package/dist/connection-state-C_477Kr_.js.map +0 -1
- package/dist/index-UrZFqSgm.d.ts +0 -166
- package/dist/index-UrZFqSgm.d.ts.map +0 -1
- package/dist/layout.d.ts.map +0 -1
- package/dist/multi-reactor-fSKpLBjT.js +0 -220
- package/dist/multi-reactor-fSKpLBjT.js.map +0 -1
- package/dist/package-manager-BkFRzovd.js.map +0 -1
- package/dist/plugin-host--lBWChr9.js.map +0 -1
- package/dist/preferences-store-DANUajdg.js.map +0 -1
- package/dist/prerendered-shell-DxCUDEXL.js.map +0 -1
- package/dist/reactor-CMXWKWup.js.map +0 -1
- package/dist/route-components-BkztQruF.js +0 -148
- package/dist/route-components-BkztQruF.js.map +0 -1
- package/dist/router-Bh19hdNU.js +0 -4
- package/dist/router-Cxt7uaaL.js +0 -604
- package/dist/router-Cxt7uaaL.js.map +0 -1
- package/dist/runtime-config-DdN1Frg7.js +0 -34
- package/dist/runtime-config-DdN1Frg7.js.map +0 -1
- package/dist/runtime-flag-B8IYhkz-.js +0 -4
- package/dist/runtime-flag-CT5OKujT.js +0 -45
- package/dist/runtime-flag-CT5OKujT.js.map +0 -1
- package/dist/sentry-CJb7--mu.js +0 -18
- package/dist/sentry-CJb7--mu.js.map +0 -1
- package/dist/settings-CjvK8OKA.js +0 -91
- package/dist/settings-CjvK8OKA.js.map +0 -1
- package/dist/settings-D7lXsfBl.js.map +0 -1
- package/dist/sidebar-BXf8OEwm.d.ts +0 -34
- package/dist/sidebar-BXf8OEwm.d.ts.map +0 -1
- package/dist/sidebar-lAVFRsni.js +0 -31
- package/dist/sidebar-lAVFRsni.js.map +0 -1
- package/dist/use-renown-login-BzOSQETV.js.map +0 -1
- package/dist/useIsEmbedded-BWJ0qb7w.js +0 -26
- package/dist/useIsEmbedded-BWJ0qb7w.js.map +0 -1
- package/dist/useRegistryPackages-BqIWwXV-.js +0 -452
- package/dist/useRegistryPackages-BqIWwXV-.js.map +0 -1
- package/scripts/critical-css.ts +0 -243
- package/src/router/connect-router.ts +0 -170
- package/src/router/drive-route-loader.ts +0 -116
- package/src/router/navigation.ts +0 -230
- package/src/router/perf-marks.test.tsx +0 -98
- package/src/router/perf-marks.ts +0 -97
- package/src/router/route-components.tsx +0 -98
- package/src/router/route-tree.ts +0 -88
- package/src/router/scroll.ts +0 -69
- package/src/router/search.ts +0 -66
- package/src/router/settings.ts +0 -120
- package/src/router/sidebar.ts +0 -55
- package/src/router/titles.test.ts +0 -24
- package/src/router/titles.ts +0 -33
- package/src/routes/core/_app/$.tsx +0 -13
- package/src/routes/core/_app/_content/d/$driveSlug/{-$nodeSlug}.tsx +0 -52
- package/src/routes/core/_app/_content/index.tsx +0 -3
- package/src/routes/core/_app/_content.tsx +0 -9
- package/src/routes/core/_app/settings/about.tsx +0 -20
- package/src/routes/core/_app/settings/ai-assistant.tsx +0 -20
- package/src/routes/core/_app/settings/danger-zone.tsx +0 -21
- package/src/routes/core/_app/settings/default-editors.tsx +0 -20
- package/src/routes/core/_app/settings/package-manager.tsx +0 -20
- package/src/routes/core/_app/settings.tsx +0 -35
- package/src/routes/core/_app.tsx +0 -10
package/CUSTOMIZING.md
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Customizing Connect
|
|
2
|
+
|
|
3
|
+
How a Powerhouse project (scaffolded by `ph init`) changes what Connect shows: its own pages, sidebar links, settings tabs, and the layout around them.
|
|
4
|
+
|
|
5
|
+
## TL;DR
|
|
6
|
+
|
|
7
|
+
Connect routes with [TanStack Router](https://tanstack.com/router) file routes. A project adds file routes to `hosts/connect/routes/`, and `ph connect build`, `ph connect studio` and `ph connect preview` mount them beside Connect's own routes in one router.
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
hosts/connect/routes/
|
|
11
|
+
├── _app.tsx optional: replaces Connect's layout (sidebar)
|
|
12
|
+
├── _app/
|
|
13
|
+
│ ├── inventory.tsx /inventory, inside the layout
|
|
14
|
+
│ └── settings/
|
|
15
|
+
│ └── inventory.tsx /settings/inventory, a settings tab
|
|
16
|
+
└── status.tsx /status, a full page without the layout
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- A file in `_app/` renders inside Connect's layout, with the sidebar.
|
|
20
|
+
- Any other file renders as a full page.
|
|
21
|
+
- A route lists itself in the sidebar with `staticData.nav`, and adds a settings tab with `staticData.settings`.
|
|
22
|
+
- Route loaders read the app's PH store from the router context.
|
|
23
|
+
|
|
24
|
+
Connect's runtime settings (app name, drives, Renown, package registry) are the other way to customize it. They live in `powerhouse.config.json`; see [RUNTIME-CONFIG.md](./RUNTIME-CONFIG.md).
|
|
25
|
+
|
|
26
|
+
## Guides
|
|
27
|
+
|
|
28
|
+
| Guide | Covers |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| [Pages, sidebar links and settings tabs](./docs/customizing/pages.md) | Add a page, list it in the sidebar, hide the sidebar on it, add a settings tab, set the page title. |
|
|
31
|
+
| [Layout and the loading screen](./docs/customizing/layout.md) | Replace the sidebar or the whole layout; what the prerendered loading screen shows. |
|
|
32
|
+
| [Data and navigation](./docs/customizing/data-and-navigation.md) | Route loaders, the open drive and document, typed search params, navigating from editors. |
|
|
33
|
+
| [Override Connect's routes](./docs/customizing/overrides.md) | Replace home, the drive view, the open document, settings or the 404 page; slow routes, not found and errors. |
|
|
34
|
+
| [Modals](./docs/customizing/modals.md) | Routed modals, replacing a modal's view, framing every modal. |
|
|
35
|
+
| [Styles and branding](./docs/customizing/styles-and-branding.md) | The project's Tailwind build and theme tokens; app name and favicon per host. |
|
|
36
|
+
| [Hosts and plugins](./docs/customizing/hosts-and-plugins.md) | Routes per host, host plugins, the generic plugin and a plugin's UI. |
|
|
37
|
+
| [Extend Connect from a package](./docs/customizing/packages.md) | A package's routes in every Connect that loads it; registering routes from code. |
|
|
38
|
+
| [Types, troubleshooting and upgrading](./docs/customizing/types-and-troubleshooting.md) | The generated route tree, common symptoms, `ph migrate`. |
|
|
39
|
+
|
|
40
|
+
Coding agents start from the [customize-connect skill](./skills/customize-connect/SKILL.md), which links to these guides.
|
|
41
|
+
|
|
42
|
+
## UI screenshots of core's views
|
|
43
|
+
|
|
44
|
+
`ui:shots` in `@powerhousedao/connect-core` renders core's views in a real Connect and saves one PNG per scene to `packages/connect-core/.ui-shots/` (gitignored):
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
pnpm --filter @powerhousedao/connect-core ui:serve # Connect plus a browser window on seeded drives
|
|
48
|
+
pnpm --filter @powerhousedao/connect-core ui:shots # every scene
|
|
49
|
+
pnpm --filter @powerhousedao/connect-core ui:shots document-json --theme dark
|
|
50
|
+
pnpm --filter @powerhousedao/connect-core ui:shots --list
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
- Connect is a production build of `test/versioned-documents` (`ph connect build --outDir .ph/ui-shots/dist`), served by `ph connect preview` on `:4350` (`UI_SHOTS_CONNECT_PORT`, 4350-4359). The stack starts it unless the port answers, stops what it started, and rebuilds when the connect-core, Connect, builder-tools or project sources are newer than the build. `UI_CONNECT_DEV=1` runs `ph connect studio` instead.
|
|
54
|
+
- Each browser context overrides the served `powerhouse.config.json` with `connect.composition: []`, so the generic plugin is absent and core's views show. `--generic` keeps the classic chrome, for comparison.
|
|
55
|
+
- Each run seeds local drives through Connect's reactor: folders, a Todo document, Reactor Group documents (no editor, so the JSON view) and a drive whose `preferredEditor` is a drive app.
|
|
56
|
+
- Flags: `--width`, `--height`, `--out`; `UI_SHOTS_VERBOSE=1` prints the server logs. Scenes live in `SCENES` in `packages/connect-core/scripts/ui-shots.ts`.
|
|
57
|
+
|
|
58
|
+
## Reference: key files
|
|
59
|
+
|
|
60
|
+
| File | What it holds |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| `apps/connect/src/routes/` | Connect's routes, which a project's files override: core's `options` and core's views, which plugins' UI replaces. |
|
|
63
|
+
| `packages/connect-core/src/routes/` | Core's routes: each file's `options` and core's view. |
|
|
64
|
+
| `packages/connect-core/src/plugins/plugin-ui.ts` | Loading, merging and applying plugins' UI. |
|
|
65
|
+
| `apps/connect/src/generic/ui.tsx` | The generic plugin's UI. |
|
|
66
|
+
| `apps/connect/src/layout/index.ts` | The `@powerhousedao/connect/layout` exports: core's layout parts. |
|
|
67
|
+
| `apps/connect/src/generic/index.ts` | The `@powerhousedao/connect/generic` exports: the generic plugin's parts, with core's. |
|
|
68
|
+
| `packages/connect-core/src/router/sidebar.ts` | `staticData.nav` and `staticData.sidebar`. |
|
|
69
|
+
| `packages/connect-core/src/router/settings.ts` | `staticData.settings`. |
|
|
70
|
+
| `packages/connect-core/src/router/drive-route-loader.ts` | `ConnectRouterContext`. |
|
|
71
|
+
| `packages/connect-core/src/router/search.ts` | Search param parsing and the global params. |
|
|
72
|
+
| `packages/connect-core/src/router/titles.ts` | Connect's titles. |
|
|
73
|
+
| `packages/builder-tools/connect-utils/vite-plugins/connect-routes.ts` | Routes folder lookup and tree generation. |
|
|
74
|
+
| `apps/connect/tailwind.css` | Connect's Tailwind source, which a project's `style.css` imports. |
|
|
75
|
+
| `apps/connect/src/prerender/shell-css.ts` | The loading screen's CSS, built by Tailwind's compiler. |
|
|
76
|
+
| `packages/reactor-browser/src/hooks/navigation.ts`, `link-props.ts` | The navigation API for editors. |
|
|
77
|
+
| `test/versioned-documents/hosts/connect/routes/` | A working example project. |
|
package/README.md
CHANGED
|
@@ -64,104 +64,31 @@ Connect's runtime settings (renown URL, package registry, default drives, log le
|
|
|
64
64
|
|
|
65
65
|
## Routes
|
|
66
66
|
|
|
67
|
-
Connect routes with [TanStack Router](https://tanstack.com/router) file routes.
|
|
67
|
+
Connect routes with [TanStack Router](https://tanstack.com/router) file routes. Core's routes live in `@powerhousedao/connect-core` (`packages/connect-core/src/routes/`): the root route, the pathless `_app` layout, and `/`, `/d/$driveSlug/{-$nodeSlug}`, `/settings` with its Appearance and Packages tabs, and the 404 catch-all `$` inside it. Connect's `src/routes/` has one file per core route: it spreads core's `options` and shows core's view, which the active plugins' UI replaces (the generic plugin draws the sidebar, home, drive views and its own settings tabs). `src/routeTree.gen.ts` is generated from them (`pnpm exec tsr generate`, or `vite dev`) and committed.
|
|
68
68
|
|
|
69
|
-
|
|
69
|
+
A project customizes Connect with file routes in `hosts/connect/routes/`, which `ph vetra`, `ph connect studio`, `ph connect build` and `ph build` mount beside Connect's routes in one router:
|
|
70
70
|
|
|
71
|
-
### Adding routes to a deployment
|
|
72
|
-
|
|
73
|
-
A project built with `ph connect build` (or served by `ph connect studio`/`preview`, or `ph run connect`) adds routes by placing file routes in `hosts/connect/routes/`. A plain `ph build` reads the same folder.
|
|
74
|
-
|
|
75
|
-
```tsx
|
|
76
|
-
// hosts/connect/routes/hello.tsx
|
|
77
|
-
import { createFileRoute } from "@tanstack/react-router";
|
|
78
|
-
|
|
79
|
-
export const Route = createFileRoute("/hello")({
|
|
80
|
-
// The router context carries the app's PH store.
|
|
81
|
-
loader: ({ context }) => ({ driveCount: context.store.drives?.length ?? 0 }),
|
|
82
|
-
component: Hello,
|
|
83
|
-
});
|
|
84
71
|
```
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
Where a file sits decides whether its page has Connect's sidebar:
|
|
95
|
-
|
|
96
|
-
- `_app/<x>.tsx` renders inside Connect's `_app` layout, with the sidebar. Its id starts with `/_app`, e.g. `createFileRoute("/_app/reports")`; the URL is `/reports`.
|
|
97
|
-
- Any other file, e.g. `hello.tsx`, renders full-page, without the sidebar.
|
|
98
|
-
- Route groups, `(name)/`, only organise files.
|
|
99
|
-
|
|
100
|
-
A route adds itself to the sidebar with `staticData.nav`, and changes the sidebar for its page (and its children) with `staticData.sidebar`:
|
|
101
|
-
|
|
102
|
-
```tsx
|
|
103
|
-
// hosts/connect/routes/_app/reports.tsx
|
|
104
|
-
export const Route = createFileRoute("/_app/reports")({
|
|
105
|
-
// Listed after the drives, by order; routes with path params are not listed.
|
|
106
|
-
staticData: { nav: { label: "Reports", order: 10, icon: FileText } },
|
|
107
|
-
component: Reports,
|
|
108
|
-
});
|
|
109
|
-
|
|
110
|
-
// hosts/connect/routes/_app/focus.tsx
|
|
111
|
-
export const Route = createFileRoute("/_app/focus")({
|
|
112
|
-
// "hidden" drops the sidebar; "collapsed" keeps only its header and footer.
|
|
113
|
-
staticData: { sidebar: "hidden" },
|
|
114
|
-
component: Focus,
|
|
115
|
-
});
|
|
72
|
+
hosts/connect/routes/
|
|
73
|
+
├── _app.tsx optional: replaces Connect's layout
|
|
74
|
+
├── _app/
|
|
75
|
+
│ ├── reports.tsx /reports, inside the layout
|
|
76
|
+
│ ├── d/$driveSlug.tsx overrides Connect's drive view
|
|
77
|
+
│ └── settings/
|
|
78
|
+
│ └── reports.tsx /settings/reports, a settings tab
|
|
79
|
+
└── hello.tsx /hello, a full page without the layout
|
|
116
80
|
```
|
|
117
81
|
|
|
118
|
-
A
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
export const Route = createFileRoute("/_app")({
|
|
126
|
-
component: () => (
|
|
127
|
-
<AppLayout
|
|
128
|
-
sidebar={<ConnectSidebar extraItems={<SidebarItem title="Docs" href="https://docs.example" />} />}
|
|
129
|
-
/>
|
|
130
|
-
),
|
|
131
|
-
});
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
The prerendered loading shell in `index.html` always shows Connect's sidebar. With a replaced layout, or on a full-page route, the page swaps to its own layout once the app renders.
|
|
135
|
-
|
|
136
|
-
### Not found
|
|
137
|
-
|
|
138
|
-
- An unknown path matches the catch-all `core/_app/$.tsx`, so its 404 page renders inside the `_app` layout, with the sidebar. The page shows the requested path and a link home; the title is `Not found · <app>`. The URL stays as typed.
|
|
139
|
-
- A drive that is not listed once drive arrivals settle shows the same page, "Drive `<slug>` not found", in place of the content view. A deep-linked drive that is still arriving shows the pending view first.
|
|
140
|
-
- A missing document still redirects to its drive.
|
|
141
|
-
- A project route's own `notFoundComponent` handles its loader's `notFound()`; without one, Connect's 404 page shows in its place.
|
|
142
|
-
|
|
143
|
-
### Adding a settings tab
|
|
144
|
-
|
|
145
|
-
Settings is a page at `/settings`, with one child route per tab (`/settings/package-manager`, `/settings/about`, ...). Bare `/settings` redirects to the first tab. The tab list is built from the children of `/settings` that declare `staticData.settings`, so a project adds a tab with a file in `_app/settings/`:
|
|
146
|
-
|
|
147
|
-
```tsx
|
|
148
|
-
// hosts/connect/routes/_app/settings/reports.tsx
|
|
149
|
-
import { createFileRoute } from "@tanstack/react-router";
|
|
150
|
-
import { FileText } from "lucide-react";
|
|
151
|
-
|
|
152
|
-
export const Route = createFileRoute("/_app/settings/reports")({
|
|
153
|
-
// label, order (Connect's tabs use 0-90), optional icon, destructive and enabled(context)
|
|
154
|
-
staticData: { settings: { label: "Reports", order: 50, icon: FileText } },
|
|
155
|
-
component: ReportsSettings,
|
|
156
|
-
});
|
|
157
|
-
```
|
|
82
|
+
- A file in `_app/` renders inside the layout; its id starts with `/_app`, e.g. `createFileRoute("/_app/reports")`, and its URL does not.
|
|
83
|
+
- A file at one of Connect's route paths overrides it by spreading that route's `options` (`@powerhousedao/connect/routes/...`). A route outside `_app/` at one of Connect's URLs fails the build.
|
|
84
|
+
- `staticData.nav` lists a route in the sidebar, `staticData.settings` makes it a settings tab, and `staticData.sidebar` hides or collapses the sidebar on its page.
|
|
85
|
+
- `ph connect build` prerenders the project's layout into `index.html` as the loading screen, with `_app`'s `pendingComponent` as its content.
|
|
86
|
+
- The tree is generated into `.ph/connect-routes.gen.ts`, which types `createFileRoute`, `Link` and `useNavigate` with the project's routes.
|
|
87
|
+
- Without a routes folder, Connect uses its prebuilt route tree.
|
|
158
88
|
|
|
159
|
-
|
|
160
|
-
- A tab whose `enabled(context)` returns false is not listed, and its URL redirects to the first tab.
|
|
161
|
-
- `_app/settings.tsx` itself belongs to Connect; a project file for it fails the build.
|
|
162
|
-
- Code opens settings with `store.navigation.open({ settings: "reports" })` (or `{ settings: true }` for the first tab), or links to it with `useLinkProps`. `showPHModal({ type: "settings" })` is deprecated and opens the page.
|
|
89
|
+
[CUSTOMIZING.md](./CUSTOMIZING.md) indexes the task-by-task guides in [`docs/customizing/`](./docs/customizing/), and coding agents start from the [customize-connect skill](./skills/customize-connect/SKILL.md).
|
|
163
90
|
|
|
164
|
-
|
|
91
|
+
Code that does not build with Vite adds code routes with `registerConnectRoutes` from `@powerhousedao/connect/router`: it receives Connect's routes (`appRoute` for the layout, `rootRoute` for a full page, `settingsRoute` for a tab) and returns the routes to add; see [Extend Connect from a package](./docs/customizing/packages.md#register-routes-from-code).
|
|
165
92
|
|
|
166
93
|
## Troubleshooting
|
|
167
94
|
|