@powerhousedao/connect 6.2.3-dev.7 → 6.2.3-dev.70
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 +80 -0
- package/README.md +28 -0
- package/RUNTIME-CONFIG.md +472 -0
- package/dist/{AddDriveModal-xAw48kdl.js → AddDriveModal-BjgmiHJr.js} +10 -10
- package/dist/AddDriveModal-BjgmiHJr.js.map +1 -0
- package/dist/{ClearStorageModal-Czo-h6OE.js → ClearStorageModal-BwGVIuLX.js} +11 -13
- package/dist/ClearStorageModal-BwGVIuLX.js.map +1 -0
- package/dist/{ConfirmDocumentUpgradeModal-FUOhZsk7.js → ConfirmDocumentUpgradeModal-CoixS60F.js} +9 -8
- package/dist/ConfirmDocumentUpgradeModal-CoixS60F.js.map +1 -0
- package/dist/{CookiesPolicyModal-BpyPPyxS.js → CookiesPolicyModal-BpFjYc7T.js} +5 -5
- package/dist/{CookiesPolicyModal-BpyPPyxS.js.map → CookiesPolicyModal-BpFjYc7T.js.map} +1 -1
- package/dist/{CreateDocumentModal-C45W8J0V.js → CreateDocumentModal-B-cXzeOA.js} +11 -10
- package/dist/CreateDocumentModal-B-cXzeOA.js.map +1 -0
- package/dist/{DebugSettingsModal-BUkre5Ke.js → DebugSettingsModal-DfOnR4iY.js} +9 -9
- package/dist/DebugSettingsModal-DfOnR4iY.js.map +1 -0
- package/dist/{DeleteDriveModal-Dug84t1j.js → DeleteDriveModal-1pAIayG_.js} +7 -7
- package/dist/DeleteDriveModal-1pAIayG_.js.map +1 -0
- package/dist/{DeleteItemModal-mMzy3V8o.js → DeleteItemModal-BUpqmFxS.js} +8 -8
- package/dist/DeleteItemModal-BUpqmFxS.js.map +1 -0
- package/dist/{DisclaimerModal-DvpD5dPM.js → DisclaimerModal-TIJXRYLF.js} +7 -7
- package/dist/DisclaimerModal-TIJXRYLF.js.map +1 -0
- package/dist/{DocumentVersionUnsupportedModal-C3Q0V75l.js → DocumentVersionUnsupportedModal-DH9Zzsyw.js} +6 -6
- package/dist/DocumentVersionUnsupportedModal-DH9Zzsyw.js.map +1 -0
- package/dist/{DownloadDocumentWithErrorsModal-IKl0ljQb.js → DownloadDocumentWithErrorsModal-Beh-xw8B.js} +8 -7
- package/dist/DownloadDocumentWithErrorsModal-Beh-xw8B.js.map +1 -0
- package/dist/{DriveAuthRequiredModal-DVK7ZQzO.js → DriveAuthRequiredModal-XTcoJKvj.js} +7 -7
- package/dist/DriveAuthRequiredModal-XTcoJKvj.js.map +1 -0
- package/dist/{DriveSettingsModal-C6-mRQiv.js → DriveSettingsModal-DZKawN7w.js} +6 -6
- package/dist/DriveSettingsModal-DZKawN7w.js.map +1 -0
- package/dist/FloatingTanStackRouterDevtools-CqogiFob-dxj8lrTP.js +2565 -0
- package/dist/FloatingTanStackRouterDevtools-CqogiFob-dxj8lrTP.js.map +1 -0
- package/dist/{InspectorModal-C-dm0iSW.js → InspectorModal-BVqRNFfP.js} +70 -30
- package/dist/InspectorModal-BVqRNFfP.js.map +1 -0
- package/dist/{LoginModal-CybbOm3N.js → LoginModal-O06ZvWFI.js} +8 -8
- package/dist/LoginModal-O06ZvWFI.js.map +1 -0
- package/dist/{OpenFileDocumentsModal-DEcFBZ5I.js → OpenFileDocumentsModal-BNHD0vg9.js} +16 -14
- package/dist/OpenFileDocumentsModal-BNHD0vg9.js.map +1 -0
- package/dist/{UpgradeDriveModal-_8t9slxQ.js → UpgradeDriveModal-CCWKp5yn.js} +7 -7
- package/dist/UpgradeDriveModal-CCWKp5yn.js.map +1 -0
- package/dist/app-loader-BjAXSJQ6.js +4 -0
- package/dist/app-loader-DtH6v5CE.js +1244 -0
- package/dist/app-loader-DtH6v5CE.js.map +1 -0
- package/dist/app-skeleton-BFjvlTWd.js +112 -0
- package/dist/app-skeleton-BFjvlTWd.js.map +1 -0
- package/dist/app-skeleton-DFg65Rxa.js +4 -0
- package/dist/boot-N7f3RrY_.js +233 -0
- package/dist/boot-N7f3RrY_.js.map +1 -0
- package/dist/buffer-DNTcuap_.js +66 -0
- package/dist/buffer-DNTcuap_.js.map +1 -0
- package/dist/{build-info-N6D-34wu.js → build-info-TgBEqTq1.js} +10 -6
- package/dist/build-info-TgBEqTq1.js.map +1 -0
- package/dist/components-B_wpF5Is.js +121 -0
- package/dist/components-B_wpF5Is.js.map +1 -0
- package/dist/{connect.config-DaHDEUrw.js → connect.config-D1pGNmaF.js} +25 -13
- package/dist/connect.config-D1pGNmaF.js.map +1 -0
- package/dist/{connection-state-3w4liC1X.js → connection-state-B6fleM37.js} +20 -9
- package/dist/connection-state-B6fleM37.js.map +1 -0
- package/dist/context-De2EB1AA-Ni0d829Q.js +1759 -0
- package/dist/context-De2EB1AA-Ni0d829Q.js.map +1 -0
- package/dist/{cookie-banner-BH6bIq24.js → cookie-banner-CAvd3PC3.js} +7 -7
- package/dist/{cookie-banner-BH6bIq24.js.map → cookie-banner-CAvd3PC3.js.map} +1 -1
- package/dist/document-editor-container-CGLXOl0t.js +4 -0
- package/dist/document-editor-container-FNIEsf8H.js +310 -0
- package/dist/document-editor-container-FNIEsf8H.js.map +1 -0
- package/dist/drive-icon-BiVP8yJc.js +38 -0
- package/dist/drive-icon-BiVP8yJc.js.map +1 -0
- package/dist/error-boundary-BsUBww61.js +155 -0
- package/dist/error-boundary-BsUBww61.js.map +1 -0
- package/dist/esm-BDACZntJ.js +148 -0
- package/dist/esm-BDACZntJ.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-CWO0vYVd.js → i18n-D9WYPgk9.js} +4 -4
- package/dist/{i18n-CWO0vYVd.js.map → i18n-D9WYPgk9.js.map} +1 -1
- package/dist/index-NyJPEHvw.d.ts +4 -0
- package/dist/layout-wfvkfP4J.js +5 -0
- package/dist/layout.d.ts +3 -0
- package/dist/layout.js +4 -0
- package/dist/{load-BxUCaDLH.js → load-CkbGF6wB.js} +48 -46
- package/dist/load-CkbGF6wB.js.map +1 -0
- package/dist/load-runtime-config-DXswYA71.js +14 -0
- package/dist/load-runtime-config-DXswYA71.js.map +1 -0
- package/dist/main.d.ts +2 -1
- package/dist/main.js +8 -8
- package/dist/main.js.map +1 -1
- package/dist/open-file-uploads-B5pr1sA2.js +183 -0
- package/dist/open-file-uploads-B5pr1sA2.js.map +1 -0
- package/dist/package-manager-CPqbVSd8.js +524 -0
- package/dist/package-manager-CPqbVSd8.js.map +1 -0
- package/dist/{pglite-major-B39aOEiE.js → pglite-major-p4_YefAE.js} +23 -5
- package/dist/pglite-major-p4_YefAE.js.map +1 -0
- package/dist/{pglite-migrate-core-Boxqqx-c.js → pglite-migrate-core-DBlU6HIc.js} +9 -7
- package/dist/pglite-migrate-core-DBlU6HIc.js.map +1 -0
- package/dist/{pglite-seed-BqAUvNFw.js → pglite-seed-eGzXMld2.js} +4 -4
- package/dist/{pglite-seed-BqAUvNFw.js.map → pglite-seed-eGzXMld2.js.map} +1 -1
- package/dist/pglite.worker.d.ts +2 -1
- package/dist/pglite.worker.js +4 -3
- package/dist/pglite.worker.js.map +1 -1
- package/dist/pglite.worker.legacy.d.ts +2 -1
- package/dist/pglite.worker.legacy.js +4 -3
- package/dist/pglite.worker.legacy.js.map +1 -1
- package/dist/plugins-CWbr0n_Q.js +246 -0
- package/dist/plugins-CWbr0n_Q.js.map +1 -0
- package/dist/{preferences-store-_5Cw4_YV.js → preferences-store-CSqauT9V.js} +6 -25
- 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-peKE7AqI.js +51 -0
- package/dist/prerendered-shell-peKE7AqI.js.map +1 -0
- package/dist/{pwa-manifest-link-DIgOSo2Q.js → pwa-manifest-link-DQRJpF0r.js} +3 -3
- package/dist/{pwa-manifest-link-DIgOSo2Q.js.map → pwa-manifest-link-DQRJpF0r.js.map} +1 -1
- package/dist/{reactor-Bg0Y9sdl.js → reactor-DLCl-WHi.js} +509 -562
- package/dist/reactor-DLCl-WHi.js.map +1 -0
- package/dist/reactor-chat-LAB-9G3G.js +50 -0
- package/dist/reactor-chat-LAB-9G3G.js.map +1 -0
- package/dist/reactor.worker.d.ts +2 -1
- package/dist/reactor.worker.js +478 -156
- package/dist/reactor.worker.js.map +1 -1
- package/dist/{registerServiceWorker-BSzbNfvz.js → registerServiceWorker-APlHkrmH.js} +5 -5
- package/dist/{registerServiceWorker-BSzbNfvz.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 +2220 -0
- package/dist/route-tree.d.ts.map +1 -0
- package/dist/route-tree.js +135 -0
- package/dist/route-tree.js.map +1 -0
- 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 +2 -0
- package/dist/router.js +3 -0
- package/dist/sentry-Cuc_Nbba.js +22 -0
- package/dist/sentry-Cuc_Nbba.js.map +1 -0
- package/dist/settings-B-apZN_f.js +1084 -0
- package/dist/settings-B-apZN_f.js.map +1 -0
- package/dist/settings-tabs-CRgiuZcb.js +385 -0
- package/dist/settings-tabs-CRgiuZcb.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 -0
- package/dist/shell-plugins.json +1 -0
- package/dist/shell.html +1 -0
- package/dist/start-connect.d.ts +7 -9
- package/dist/start-connect.d.ts.map +1 -1
- package/dist/start-connect.js +9 -8
- package/dist/start-connect.js.map +1 -1
- package/dist/store-lock-Bi3B9VJD.js +159 -0
- package/dist/store-lock-Bi3B9VJD.js.map +1 -0
- package/dist/style.css +3131 -774
- package/dist/{toast-BXIGd4Eb.js → toast-C6WW-_O-.js} +3 -3
- package/dist/{toast-BXIGd4Eb.js.map → toast-C6WW-_O-.js.map} +1 -1
- package/dist/ui-CwbE23ra.js +66 -0
- package/dist/ui-CwbE23ra.js.map +1 -0
- package/dist/{use-renown-login-Cf3va6u_.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 +232 -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 +39 -0
- package/docs/customizing/pages.md +136 -0
- package/docs/customizing/styles-and-branding.md +69 -0
- package/docs/customizing/types-and-troubleshooting.md +63 -0
- package/fonts.css +177 -0
- package/package.json +81 -25
- package/scripts/prerender-shell.ts +51 -0
- package/skills/customize-connect/SKILL.md +74 -0
- package/src/route-tree.ts +3 -0
- package/src/routeTree.gen.ts +235 -0
- package/src/router/index.ts +2 -0
- package/src/router/register.ts +9 -0
- package/src/routes/__root.tsx +12 -0
- 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 +8 -23
- package/tailwind.css +12 -0
- package/theme.css +5 -0
- package/dist/AddDriveModal-xAw48kdl.js.map +0 -1
- package/dist/ClearStorageModal-Czo-h6OE.js.map +0 -1
- package/dist/ConfirmDocumentUpgradeModal-FUOhZsk7.js.map +0 -1
- package/dist/CreateDocumentModal-C45W8J0V.js.map +0 -1
- package/dist/DebugSettingsModal-BUkre5Ke.js.map +0 -1
- package/dist/DeleteDriveModal-Dug84t1j.js.map +0 -1
- package/dist/DeleteItemModal-mMzy3V8o.js.map +0 -1
- package/dist/DisclaimerModal-DvpD5dPM.js.map +0 -1
- package/dist/DocumentVersionUnsupportedModal-C3Q0V75l.js.map +0 -1
- package/dist/DownloadDocumentWithErrorsModal-IKl0ljQb.js.map +0 -1
- package/dist/DriveAuthRequiredModal-DVK7ZQzO.js.map +0 -1
- package/dist/DriveSettingsModal-C6-mRQiv.js.map +0 -1
- package/dist/InspectorModal-C-dm0iSW.js.map +0 -1
- package/dist/LoginModal-CybbOm3N.js.map +0 -1
- package/dist/MissingPackageModal-nBnExqO0.js +0 -49
- package/dist/MissingPackageModal-nBnExqO0.js.map +0 -1
- package/dist/OpenFileDocumentsModal-DEcFBZ5I.js.map +0 -1
- package/dist/SettingsModal-CRBkw7d0.js +0 -569
- package/dist/SettingsModal-CRBkw7d0.js.map +0 -1
- package/dist/UpgradeDriveModal-_8t9slxQ.js.map +0 -1
- package/dist/app-loader-DkQhle_a.js +0 -4
- package/dist/app-loader-lsCT8EWA.js +0 -2244
- package/dist/app-loader-lsCT8EWA.js.map +0 -1
- package/dist/build-info-N6D-34wu.js.map +0 -1
- package/dist/components-DHzkxxly.js +0 -4
- package/dist/connect.config-DaHDEUrw.js.map +0 -1
- package/dist/connection-state-3w4liC1X.js.map +0 -1
- package/dist/load-BxUCaDLH.js.map +0 -1
- package/dist/pglite-major-B39aOEiE.js.map +0 -1
- package/dist/pglite-migrate-core-Boxqqx-c.js.map +0 -1
- package/dist/preferences-store-_5Cw4_YV.js.map +0 -1
- package/dist/reactor-Bg0Y9sdl.js.map +0 -1
- package/dist/runtime-config-DL3QjcfM.js +0 -24
- package/dist/runtime-config-DL3QjcfM.js.map +0 -1
- package/dist/sentry-QXKgQmr2.js +0 -15
- package/dist/sentry-QXKgQmr2.js.map +0 -1
- package/dist/use-renown-login-Cf3va6u_.js.map +0 -1
- package/dist/useRegistryPackages-BnUcL_nZ.js +0 -390
- package/dist/useRegistryPackages-BnUcL_nZ.js.map +0 -1
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Modals
|
|
2
|
+
|
|
3
|
+
Editors, drive apps and Connect open modals with `showPHModal(modal)` from `@powerhousedao/reactor-browser`; the open modal's view reads it with `usePHModal()` and closes it with `closePHModal()`.
|
|
4
|
+
|
|
5
|
+
**Routed modals live in the URL:** `?modal=<id>` plus their fields. A link opens them (`modalHref(modal)` gives the href) and a reload keeps them open. Opening and closing replace the current history entry, so a modal is never a step of its own: Back leaves the page, not the modal.
|
|
6
|
+
|
|
7
|
+
| Modal | `?modal=` | Owner |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `createDocument` | `create-document&documentType=…[&documentModelVersion=…]` | core |
|
|
10
|
+
| `login` | `login` | core |
|
|
11
|
+
| `addDrive` | `add-drive` | generic |
|
|
12
|
+
| `driveSettings` | `drive-settings&driveId=…` | generic |
|
|
13
|
+
| `debugSettings`, `inspector` | `debug-settings`, `inspector` | generic |
|
|
14
|
+
| `disclaimer` | `disclaimer` | generic |
|
|
15
|
+
| `cookiesPolicy` | `cookies-policy` | Connect (analytics consent) |
|
|
16
|
+
|
|
17
|
+
**Confirmations and notices stay out of the URL:** `deleteItem`, `confirmDocumentUpgrade`, `downloadDocumentWithErrors`, `documentVersionUnsupported` and `driveAuthRequired` (core's), `deleteDrive`, `upgradeDrive` and `clearStorage` (generic's), and `openFileDocuments` (Connect's file handler).
|
|
18
|
+
|
|
19
|
+
- **Core** has a plain view for each of its modals, so every host can show what editors and drive apps open.
|
|
20
|
+
- **With the generic plugin**, Connect shows its design-system views for all of them; without it, core's.
|
|
21
|
+
|
|
22
|
+
## Replace a modal's view
|
|
23
|
+
|
|
24
|
+
A route's `staticData.modals` replaces the host's view of a modal while the route matches; the deepest matched route wins. The view reads the modal with `usePHModal()`:
|
|
25
|
+
|
|
26
|
+
```tsx
|
|
27
|
+
// hosts/connect/routes/_app.tsx
|
|
28
|
+
import { closePHModal, usePHModal } from "@powerhousedao/reactor-browser";
|
|
29
|
+
|
|
30
|
+
export const Route = createFileRoute("/_app")({
|
|
31
|
+
component: Layout,
|
|
32
|
+
staticData: { modals: { createDocument: CreateTodoList } },
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
function CreateTodoList() {
|
|
36
|
+
const modal = usePHModal();
|
|
37
|
+
if (modal?.type !== "createDocument") return null;
|
|
38
|
+
return (
|
|
39
|
+
<dialog open>
|
|
40
|
+
New {modal.documentType}
|
|
41
|
+
<button onClick={closePHModal}>Cancel</button>
|
|
42
|
+
</dialog>
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
- On an override of one of Connect's routes, spread `options.staticData` first if it has any.
|
|
48
|
+
- A view that throws closes quietly; the error is logged.
|
|
49
|
+
|
|
50
|
+
## Frame every modal
|
|
51
|
+
|
|
52
|
+
A route's `staticData.modalFrame` lays out every core modal while the route matches, so one component restyles all of them. Each modal passes its title, content and buttons; `ModalDialog` keeps the dialog's behaviour (modal, Escape and the backdrop close it):
|
|
53
|
+
|
|
54
|
+
```tsx
|
|
55
|
+
// hosts/connect/routes/_app.tsx
|
|
56
|
+
import type { ModalFrameProps } from "@powerhousedao/connect/layout";
|
|
57
|
+
import { ModalDialog } from "@powerhousedao/connect/layout";
|
|
58
|
+
|
|
59
|
+
export const Route = createFileRoute("/_app")({
|
|
60
|
+
component: Layout,
|
|
61
|
+
staticData: { modalFrame: Frame },
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
function Frame({ title, titleId, actions, children }: ModalFrameProps) {
|
|
65
|
+
return (
|
|
66
|
+
<ModalDialog labelledBy={titleId} className="rounded-xl p-0 shadow-2xl">
|
|
67
|
+
<h2 id={titleId}>{title}</h2>
|
|
68
|
+
<div>{children}</div>
|
|
69
|
+
<footer>{actions}</footer>
|
|
70
|
+
</ModalDialog>
|
|
71
|
+
);
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- The deepest matched route's frame wins, as with `staticData.modals`. On `_app` it frames the modals opened inside the layout; on the root route, all of them.
|
|
76
|
+
- It frames core's modals. The generic plugin's design-system modals, and views a route gives in `staticData.modals`, draw their own.
|
|
77
|
+
- The content and buttons keep core's markup; style them from the frame, e.g. with `[&_button]:…` classes.
|
|
78
|
+
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Override Connect's routes, loading, not found and errors
|
|
2
|
+
|
|
3
|
+
## Override a Connect route
|
|
4
|
+
|
|
5
|
+
Every page Connect shows is a file route in `@powerhousedao/connect`'s `src/routes/` (`node_modules/@powerhousedao/connect/src/routes/` in a project). A project file at the same path replaces Connect's file. Each of Connect's files exports `options`: everything but the component (loader, search params, pending view, title). An override spreads them and sets its own `component`:
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
// hosts/connect/routes/_app/d/$driveSlug.tsx
|
|
9
|
+
import { useDriveRouteData } from "@powerhousedao/connect/layout";
|
|
10
|
+
import { options } from "@powerhousedao/connect/routes/_app/d/$driveSlug";
|
|
11
|
+
import { createFileRoute, Outlet } from "@tanstack/react-router";
|
|
12
|
+
|
|
13
|
+
export const Route = createFileRoute("/_app/d/$driveSlug")({
|
|
14
|
+
...options,
|
|
15
|
+
component: InventoryDrive,
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
function InventoryDrive() {
|
|
19
|
+
const { drive, folder, documentId } = useDriveRouteData();
|
|
20
|
+
if (!drive) return null;
|
|
21
|
+
// The node route renders the open document in the outlet.
|
|
22
|
+
if (documentId) return <Outlet />;
|
|
23
|
+
return <p>{folder?.name ?? drive.header.name}</p>;
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
| Path | File | What it renders |
|
|
28
|
+
| --- | --- | --- |
|
|
29
|
+
| (every page) | `__root.tsx` | The page, the title, the loading shell. Not overridable. |
|
|
30
|
+
| (layout) | `_app.tsx` | The sidebar beside the content; see [Replace the layout](./layout.md#replace-the-layout). |
|
|
31
|
+
| `/` | `_app/index.tsx` | Home: the drives. |
|
|
32
|
+
| `/d/$driveSlug` | `_app/d/$driveSlug.tsx` | The drive: its drive app, or the sign-in gate, around the node route. |
|
|
33
|
+
| `/d/$driveSlug/{-$nodeSlug}` | `_app/d/$driveSlug/{-$nodeSlug}.tsx` | The open document: its editor, or its revision history with `?history`. Nothing on a folder. |
|
|
34
|
+
| `/settings` | `_app/settings.tsx` | The settings page around the shown tab. |
|
|
35
|
+
| `/settings/<tab>` | `_app/settings/<tab>.tsx` | One settings tab. |
|
|
36
|
+
| unknown paths | `_app/$.tsx` | The 404 page. |
|
|
37
|
+
|
|
38
|
+
- `useDriveRouteData()` returns the open `drive`, `folder` and `documentId` from the drive routes' loaders, live.
|
|
39
|
+
- Connect's routes nested under an overridden one stay: the node route renders in an overridden drive route's `<Outlet />`, and the tabs in an overridden settings page's.
|
|
40
|
+
- Drive apps and editors come from packages, not routes. Override a route only to change Connect around them.
|
|
41
|
+
- Without the generic plugin, each of Connect's files shows core's view instead (a header, an index of drives, a directory listing, a JSON view). An override shows the same view either way.
|
|
42
|
+
- `_app.tsx` and `__root.tsx` are not overridden here: a project's `_app.tsx` replaces the layout ([layout.md](./layout.md)), and the root route is Connect's.
|
|
43
|
+
- To hide a route, override it with a `beforeLoad` that throws `notFound()` or `redirect()`.
|
|
44
|
+
|
|
45
|
+
## Loading, not found and errors
|
|
46
|
+
|
|
47
|
+
Connect uses the router's own states: a route's `pendingComponent`, `notFoundComponent` and `errorComponent`. A project sets them on its routes, or on its overrides of Connect's routes (see [Override a Connect route](#override-a-connect-route)). The loading screen is in [layout.md](./layout.md#the-loading-screen).
|
|
48
|
+
|
|
49
|
+
### Slow routes
|
|
50
|
+
|
|
51
|
+
A route whose loader takes longer than its `pendingMs` shows its `pendingComponent`. Connect's drive routes show a "Loading drive…" note on a cold start and keep the open view on warm navigations. An override spreads their `options` and can set its own:
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
export const Route = createFileRoute("/_app/d/$driveSlug")({
|
|
55
|
+
...options,
|
|
56
|
+
pendingComponent: DriveSkeleton,
|
|
57
|
+
component: InventoryDrive,
|
|
58
|
+
});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### Not found
|
|
62
|
+
|
|
63
|
+
| What | Where to change it |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| A path no route serves | Override `_app/$.tsx`, spreading its `options`. It renders inside the layout, titled `Not found · <app>`; the URL stays as typed. Its loader waits for packages' routes still loading (up to 10 s), so a deep link to a package's page shows the loading state, not this page. |
|
|
66
|
+
| A drive that isn't listed once drives arrive | `notFoundComponent` on an override of `_app/d/$driveSlug.tsx`; `isDriveNotFound(data)` gives the slug. |
|
|
67
|
+
| A project route's own `notFound()` | That route's `notFoundComponent`. |
|
|
68
|
+
| Anything else | Connect's 404 page. |
|
|
69
|
+
|
|
70
|
+
```tsx
|
|
71
|
+
// hosts/connect/routes/_app/d/$driveSlug.tsx
|
|
72
|
+
import { isDriveNotFound } from "@powerhousedao/connect/router";
|
|
73
|
+
import { options } from "@powerhousedao/connect/routes/_app/d/$driveSlug";
|
|
74
|
+
import type { NotFoundRouteProps } from "@tanstack/react-router";
|
|
75
|
+
|
|
76
|
+
export const Route = createFileRoute("/_app/d/$driveSlug")({
|
|
77
|
+
...options,
|
|
78
|
+
component: InventoryDrive,
|
|
79
|
+
notFoundComponent: ({ data }: NotFoundRouteProps) =>
|
|
80
|
+
isDriveNotFound(data) ? <p>No drive {data.driveSlug}.</p> : <p>Not found.</p>,
|
|
81
|
+
});
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
A project route throws `notFound()` the same way:
|
|
85
|
+
|
|
86
|
+
```tsx
|
|
87
|
+
export const Route = createFileRoute("/_app/documents/$documentId")({
|
|
88
|
+
loader: async ({ context, params }) => {
|
|
89
|
+
// ...
|
|
90
|
+
throw notFound();
|
|
91
|
+
},
|
|
92
|
+
notFoundComponent: () => <p className="p-6">No such document.</p>,
|
|
93
|
+
component: DocumentSummary,
|
|
94
|
+
});
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Errors
|
|
98
|
+
|
|
99
|
+
A loader or render error shows the route's `errorComponent`, else Connect's error view (with the generic plugin) or core's. It gets `{ error, reset }`; `reset()` retries the route. Connect reports the error to Sentry when Sentry is configured.
|
|
100
|
+
|
|
101
|
+
```tsx
|
|
102
|
+
export const Route = createFileRoute("/_app/reports")({
|
|
103
|
+
loader: loadReports,
|
|
104
|
+
errorComponent: ({ error, reset }) => (
|
|
105
|
+
<div role="alert">
|
|
106
|
+
<p>{error.message}</p>
|
|
107
|
+
<button onClick={reset}>Try again</button>
|
|
108
|
+
</div>
|
|
109
|
+
),
|
|
110
|
+
component: Reports,
|
|
111
|
+
});
|
|
112
|
+
```
|
|
113
|
+
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Extend Connect from a package
|
|
2
|
+
|
|
3
|
+
## Offer a package's routes
|
|
4
|
+
|
|
5
|
+
A package's `hosts/connect/routes/` also adds routes to every Connect that loads the package, e.g. a Reports page or a settings tab, without code:
|
|
6
|
+
|
|
7
|
+
- Offered: every route file but `_app.tsx` and the files that override Connect's `_app/` routes. Those two only apply to the package's own host. A child of an override joins the loading Connect's route with that id.
|
|
8
|
+
- `ph build` builds them as `./connect-routes` (`dist/browser/connect-routes.js`), in the same build as the package, and sets `connectRoutes: true` in the package's manifest. A module both import, e.g. a store or a React context an editor and a route share, is one chunk, so they share its state. Connect loads the module when it loads a package with the flag, and takes the routes out when the package is removed, replaced or reinstalled.
|
|
9
|
+
- They join the loading Connect's routes by id (`/_app`, `/_app/settings`, `/_app/d/$driveSlug`, ...). A route at an id that Connect already serves is skipped with a warning; `staticData.nav` and `staticData.settings` list them as for a project's routes.
|
|
10
|
+
- A deep link or reload on a package's page waits for the package: Connect holds unknown paths while packages and their routes load (see [Not found](./overrides.md#not-found)).
|
|
11
|
+
- Removing a package while one of its pages is open takes the app home first.
|
|
12
|
+
- Bundled packages (`ph install --local`, `provider: "local"`) register in a production build through the page's import map, as on the dev server.
|
|
13
|
+
- An offered route imports `@powerhousedao/connect-core` (`ContentOutlet`, `useDriveRouteData`, `ModalDialog`), `@tanstack/react-router` and `@powerhousedao/reactor-browser`, which Connect shares with packages. `@powerhousedao/connect` is not shared, so `ph build` fails, naming the file, if an offered route imports it, or reaches a module that does. The rest of the package gets a warning: its build would bundle a copy of the Connect modules it uses, apart from the app's state.
|
|
14
|
+
- The project's own package is the exception: its host build already has its routes.
|
|
15
|
+
- The package's stylesheet styles its routes, as it does its editors; see [A package's styles](./styles-and-branding.md#a-packages-styles).
|
|
16
|
+
|
|
17
|
+
## Register routes from code
|
|
18
|
+
|
|
19
|
+
A package that Connect loads can also register routes from its own module. The registrations live in one registry per page, on `globalThis`, so a package bundled with its own copy of `@powerhousedao/connect-core` still reaches the app. A production build also shares `@powerhousedao/connect-core` and `@tanstack/react-router` through the import map, so the package and Connect use one router.
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
import { registerConnectRoutes } from "@powerhousedao/connect-core/router";
|
|
23
|
+
import { createRoute } from "@tanstack/react-router";
|
|
24
|
+
|
|
25
|
+
// A settings tab; a router already running takes it in.
|
|
26
|
+
registerConnectRoutes(({ settingsRoute }) => [
|
|
27
|
+
createRoute({
|
|
28
|
+
getParentRoute: () => settingsRoute,
|
|
29
|
+
path: "inventory",
|
|
30
|
+
staticData: { settings: { label: "Inventory", order: 50 } },
|
|
31
|
+
component: InventorySettings,
|
|
32
|
+
}),
|
|
33
|
+
]);
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- It returns the unregister.
|
|
37
|
+
- A route at a path a route already serves is skipped with a warning.
|
|
38
|
+
- Core's views are styled with Tailwind classes and `theme.css` tokens (`bg-core-bg`, `text-core-fg`, ...). Core ships no compiled CSS: its host builds with Tailwind 4 and imports `@powerhousedao/connect-core/tailwind.css`, which imports the tokens (`theme.css`) and makes Tailwind scan core's sources. `@powerhousedao/connect/tailwind.css` does this; see [Styles](./styles-and-branding.md#styles).
|
|
39
|
+
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Pages, sidebar links and settings tabs
|
|
2
|
+
|
|
3
|
+
A project adds pages to Connect with file routes in `hosts/connect/routes/`. A route lists itself in the sidebar, changes the sidebar on its page, adds a settings tab and sets its title through its own options.
|
|
4
|
+
|
|
5
|
+
## Add a page
|
|
6
|
+
|
|
7
|
+
1. Add the router to the project, in the version Connect uses (the `@tanstack/react-router` entry in `@powerhousedao/connect`'s `package.json`):
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pnpm add @tanstack/react-router@1.170.41
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
2. Create a route file. A file in `_app/` renders inside Connect's layout; its route id starts with `/_app`, and the URL does not:
|
|
14
|
+
|
|
15
|
+
```tsx
|
|
16
|
+
// hosts/connect/routes/_app/inventory.tsx
|
|
17
|
+
import { useDrives } from "@powerhousedao/reactor-browser";
|
|
18
|
+
import { createFileRoute } from "@tanstack/react-router";
|
|
19
|
+
|
|
20
|
+
export const Route = createFileRoute("/_app/inventory")({
|
|
21
|
+
component: Inventory,
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
function Inventory() {
|
|
25
|
+
const drives = useDrives();
|
|
26
|
+
return <div className="p-6">{drives?.length ?? 0} drives</div>;
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
3. Run `ph connect studio` and open `/inventory`.
|
|
31
|
+
|
|
32
|
+
A file outside `_app/` is a full page, without Connect's layout:
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
// hosts/connect/routes/status.tsx
|
|
36
|
+
import { useDrives } from "@powerhousedao/reactor-browser";
|
|
37
|
+
import { createFileRoute, Link } from "@tanstack/react-router";
|
|
38
|
+
|
|
39
|
+
export const Route = createFileRoute("/status")({
|
|
40
|
+
component: Status,
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
function Status() {
|
|
44
|
+
const drives = useDrives();
|
|
45
|
+
return (
|
|
46
|
+
<div className="p-6">
|
|
47
|
+
<h1>{drives?.length ?? 0} drives</h1>
|
|
48
|
+
<Link to="/">Back to Connect</Link>
|
|
49
|
+
</div>
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Rules:
|
|
55
|
+
|
|
56
|
+
- Connect reads routes only from `hosts/connect/routes/`.
|
|
57
|
+
- Core routes are `/`, `/d/$driveSlug/{-$nodeSlug}`, `/settings` with its Appearance and Packages tabs, and the catch-all `$`. They live in `@powerhousedao/connect-core`. A file in `_app/` at a core route's path overrides it; see [Override a Connect route](./overrides.md#override-a-connect-route). Any other route at a core route's URL fails the build.
|
|
58
|
+
- Files and folders starting with `-` are not routes. Use them for shared components.
|
|
59
|
+
- Route groups, `(name)/`, only organize files.
|
|
60
|
+
- Each route is code-split into its own chunk.
|
|
61
|
+
- Inside a route, navigate with the router's `Link` and `useNavigate`. They are typed with the project's routes and Connect's.
|
|
62
|
+
|
|
63
|
+
## Add a sidebar link
|
|
64
|
+
|
|
65
|
+
A route in `_app/` lists itself in the sidebar with `staticData.nav`:
|
|
66
|
+
|
|
67
|
+
```tsx
|
|
68
|
+
// hosts/connect/routes/_app/inventory.tsx
|
|
69
|
+
export const Route = createFileRoute("/_app/inventory")({
|
|
70
|
+
staticData: { nav: { label: "Inventory", icon: BoxIcon, order: 10 } },
|
|
71
|
+
component: Inventory,
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- Links come after the drives, sorted by `order`, then by `label`.
|
|
76
|
+
- `icon` is optional: any component that takes `size` (and `className`), e.g. from `lucide-react`.
|
|
77
|
+
- Routes with path params (`$id`) are not listed: the sidebar cannot fill in the param.
|
|
78
|
+
|
|
79
|
+
## Hide or collapse the sidebar on a page
|
|
80
|
+
|
|
81
|
+
`staticData.sidebar` changes the sidebar for a route and its children:
|
|
82
|
+
|
|
83
|
+
```tsx
|
|
84
|
+
// hosts/connect/routes/_app/focus.tsx
|
|
85
|
+
export const Route = createFileRoute("/_app/focus")({
|
|
86
|
+
// "hidden" drops the sidebar; "collapsed" keeps only its header and footer.
|
|
87
|
+
staticData: { sidebar: "hidden" },
|
|
88
|
+
component: () => <div className="p-6">No sidebar here.</div>,
|
|
89
|
+
});
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The deepest matched route that sets `sidebar` decides. Embedded mode (`?embed=1`) always hides the sidebar.
|
|
93
|
+
|
|
94
|
+
## Add a settings tab
|
|
95
|
+
|
|
96
|
+
Settings is the page at `/settings`, with one child route per tab. A file in `_app/settings/` with `staticData.settings` adds a tab:
|
|
97
|
+
|
|
98
|
+
```tsx
|
|
99
|
+
// hosts/connect/routes/_app/settings/inventory.tsx
|
|
100
|
+
import { createFileRoute } from "@tanstack/react-router";
|
|
101
|
+
|
|
102
|
+
export const Route = createFileRoute("/_app/settings/inventory")({
|
|
103
|
+
staticData: {
|
|
104
|
+
settings: {
|
|
105
|
+
label: "Inventory",
|
|
106
|
+
// Connect's tabs use multiples of 10, from 0 to 90.
|
|
107
|
+
order: 50,
|
|
108
|
+
// Optional: the tab is hidden, and its URL redirects to the first tab, while this is false.
|
|
109
|
+
enabled: (context) => !!context.store.drives?.length,
|
|
110
|
+
},
|
|
111
|
+
},
|
|
112
|
+
component: () => <div>Inventory settings</div>,
|
|
113
|
+
});
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
- `icon` and `destructive` are optional.
|
|
117
|
+
- The page title becomes `Settings · Inventory · <app>`. The tab needs no `head`.
|
|
118
|
+
- The generic plugin adds its tabs (Package Manager, Default Editors, Danger Zone, About, AI Assistant) as code routes and hides core's (Appearance, Packages); without it, core's are listed. A project file at a tab's path, e.g. `_app/settings/about.tsx`, replaces that tab; it spreads the tab's options from `genericSettingsTabs` (`@powerhousedao/connect/generic`), e.g. `...genericSettingsTabs.about`, to keep its label, icon and order.
|
|
119
|
+
|
|
120
|
+
## Set the page title
|
|
121
|
+
|
|
122
|
+
A route sets the document title with `head`. Connect's titles end with the app name:
|
|
123
|
+
|
|
124
|
+
```tsx
|
|
125
|
+
export const Route = createFileRoute("/_app/inventory")({
|
|
126
|
+
head: ({ match }) => ({
|
|
127
|
+
meta: [{ title: `Inventory · ${match.context.appName ?? "Connect"}` }],
|
|
128
|
+
}),
|
|
129
|
+
component: Inventory,
|
|
130
|
+
});
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
- The deepest route with a title wins. Without one, the page keeps Connect's: the app name.
|
|
134
|
+
- `head` also receives `loaderData`, e.g. `` title: `${loaderData?.name} · ${appName}` ``.
|
|
135
|
+
- Connect's own titles are in `@powerhousedao/connect-core`'s `src/router/titles.ts`: `<node> · <drive> · <app>`, `Settings · <tab> · <app>`, `Not found · <app>`.
|
|
136
|
+
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Styles and branding
|
|
2
|
+
|
|
3
|
+
## Styles
|
|
4
|
+
|
|
5
|
+
A project's styles are in two files, which the page builds as one Tailwind build:
|
|
6
|
+
|
|
7
|
+
- `style.css`, at the root, is the package's: Connect's imports, then the tokens and rules the package's editors and routes use. `ph build` ships it as the package's stylesheet (see [A package's styles](#a-packages-styles)).
|
|
8
|
+
- `hosts/connect/style.css` is this Connect's: its theme and global rules. The host's build adds it after `style.css`; `ph build` never reads it, so it reaches no other Connect.
|
|
9
|
+
|
|
10
|
+
```css
|
|
11
|
+
/* style.css */
|
|
12
|
+
@layer properties, theme, base, components, external-packages, utilities;
|
|
13
|
+
@import "tailwindcss";
|
|
14
|
+
@import "@powerhousedao/connect/tailwind.css";
|
|
15
|
+
|
|
16
|
+
/* A token the package's editors use. */
|
|
17
|
+
@theme {
|
|
18
|
+
--color-brand: #f60;
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```css
|
|
23
|
+
/* hosts/connect/style.css */
|
|
24
|
+
@theme static {
|
|
25
|
+
--color-red-700: #b42318;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
:root.dark {
|
|
29
|
+
--background: #16181c;
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- `@powerhousedao/connect/tailwind.css` brings the design system's tokens, core's theme, Connect's own rules and the `@source` lines for the classes Connect's code uses. Tailwind generates those classes in the project's build, next to the project's own.
|
|
34
|
+
- One build means one copy of each utility, in one `utilities` layer, ordered by Tailwind. Importing a second build (`@powerhousedao/connect/style.css`, or a package's `dist/style.css` built before packages left Connect's classes out) emits the utilities again in source order, so a later `.px-3` beats an earlier `.pl-7`.
|
|
35
|
+
- Third-party CSS (toasts, the JSON viewer, the workflow canvas) comes in through `vendor.css` files: plain rules that Tailwind passes through.
|
|
36
|
+
- Theme Connect in the host's file: override tokens in `@theme static`, and add plain CSS below it. Tailwind emits only the tokens the page's own classes use, so without `static` an override of a token only a package uses never reaches the page, and the package's class keeps Connect's default. A fully static theme would add about 11 KB (3 KB gzipped) to the page; `static` on the host's own block adds just its overrides. Plain rules outside a `@layer` win over all of Connect's CSS, which is layered; put a rule in `@layer components` to let utilities override it.
|
|
37
|
+
- The host's file sits beside its routes folder: `hosts/connect/style.css` for `hosts/connect/routes/`, `hosts/lab/style.css` for a host whose `runner.routes` is `hosts/lab/routes`. `ph connect studio`, `build` and `preview`, `ph vetra` and `ph run <host>` add it, and the loading screen's inline CSS includes it. Studio applies edits to it without a reload.
|
|
38
|
+
- The design system defines the `dark` variant (`.dark` on `<html>`), so a project's `dark:` classes follow Connect's theme toggle.
|
|
39
|
+
- `ph migrate` rewrites the imports at the top of an existing `style.css` to these and keeps the rest of the file. It drops the imports of local packages' builds that `ph install --local` used to add (other `node_modules` CSS stays) and the old template's empty `@theme` block, adds `properties` to an old layer order, creates `hosts/connect/style.css` when it is missing (a host with its own `runner.routes` creates its file by hand), and warns when `style.css` sets tokens or global rules (`:root`, `html`, `body`, `.dark`). It doesn't move them: only the project knows which are the package's and which are this Connect's theme.
|
|
40
|
+
|
|
41
|
+
## A package's styles
|
|
42
|
+
|
|
43
|
+
`ph build` writes a package's stylesheet, `dist/style.css`, from the root `style.css`. It holds the package's own classes and rules, without Tailwind's reset or Connect's classes, since the Connect that loads the package has those:
|
|
44
|
+
|
|
45
|
+
- Tailwind's theme and `@powerhousedao/connect/theme.css` come in by `@reference`. The package's classes can use Connect's tokens, variants and plugins (`bg-background`, `text-core-fg`, `dark:`, `scrollbar-thin`), and the build emits none of them. The classes read the tokens from the page; palette and spacing classes fall back to the referenced values.
|
|
46
|
+
- Tailwind scans the package's browser build (`dist/browser`), so only code that ships adds classes: not host-only routes such as `_app.tsx`, nor components the bundle leaves out.
|
|
47
|
+
- The options of the project's `@import "tailwindcss"` carry over, `prefix(...)` and `important` among them; `source(...)` and `theme(...)` don't, since the build sets both.
|
|
48
|
+
- The rest of `style.css` goes in as written: the package's `@theme` tokens, `@utility` definitions and plain rules. A token or rule set here reaches every Connect that loads the package, so keep a Connect's theme in its host file.
|
|
49
|
+
- The file is in the `external-packages` layer: above Connect's reset, so it styles the package's editors, and below Connect's utilities. It declares Connect's layer order first, so the order holds whichever stylesheet the page loads first.
|
|
50
|
+
- Connect loads the stylesheet with the package: from the registry's CDN for a registry package, and with the package's code for a bundled one (`ph install --local`). `style.css` imports no packages.
|
|
51
|
+
- A bundled package is not added to the project's build with `@source`. Its tokens, `@utility` definitions and rules live in its own `style.css`, which the project's build doesn't read, and the package renders as it does from the registry.
|
|
52
|
+
|
|
53
|
+
## Name and icon per host
|
|
54
|
+
|
|
55
|
+
`connect.branding.appName` and `connect.branding.favicon` in `powerhouse.config.json` name the app and set its tab icon for every host. A host overrides either in its `config`:
|
|
56
|
+
|
|
57
|
+
```js
|
|
58
|
+
// hosts/lab/host.js
|
|
59
|
+
export default {
|
|
60
|
+
name: "lab",
|
|
61
|
+
runner: { module: "@powerhousedao/ph-cli/runners/connect" },
|
|
62
|
+
config: { branding: { appName: "Lab", favicon: "hosts/lab/icon.svg" } },
|
|
63
|
+
};
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- A host's `config` merges over the project's `connect` block field by field, so a host inherits what it doesn't set.
|
|
67
|
+
- `branding.favicon` is a file (`.ico`, `.svg` or `.png`) relative to the project. `ph run lab dev` serves it and `ph run lab build` builds it as `icon.ico`; the built `powerhouse.config.json` leaves the path out. `ph connect build --favicon` wins over it.
|
|
68
|
+
- `ph run lab build` bakes the host's `config` into the build, over `powerhouse.config.json`: the `<title>` and the loading screen take its `branding.appName`, and the build uses its `app.basePath` and `pwa`.
|
|
69
|
+
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Types, troubleshooting and upgrading
|
|
2
|
+
|
|
3
|
+
## Types
|
|
4
|
+
|
|
5
|
+
The build generates `.ph/connect-routes.gen.ts`: the route tree of Connect's routes and the project's. It registers the router type, so `createFileRoute` ids, `Link`, `useNavigate`, loader data and search params are typed.
|
|
6
|
+
|
|
7
|
+
- `ph connect build`, `ph connect studio`, `ph connect preview` and `ph build` generate it. `ph connect studio` regenerates it as route files change.
|
|
8
|
+
- The project's `tsconfig.json` includes `.ph/connect-routes.gen.ts` and maps both `"@powerhousedao/connect-core/route-tree"` and `"@powerhousedao/connect/route-tree"` to `["./.ph/connect-routes.gen.ts"]` in `paths`. New projects are scaffolded with them. In an older project, add them by hand, and drop `.ph` from `exclude`. Core's router types name the tree by `@powerhousedao/connect-core/route-tree`; without that path they use core's own routes.
|
|
9
|
+
- Until the first build, both specifiers resolve to core's own tree. Project routes show type errors (unknown route ids) until `ph connect build` or `ph connect studio` has run.
|
|
10
|
+
- `ph connect build` type-checks the routes and fails on errors. `--ignore-type-errors` skips the check.
|
|
11
|
+
- `@tanstack/react-router` must be the version Connect uses. The routes and Connect share one router, and its types come from the project's copy.
|
|
12
|
+
|
|
13
|
+
## Troubleshooting
|
|
14
|
+
|
|
15
|
+
| Symptom | Cause |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| `Connect could not mount the routes in hosts/connect/routes/` | A route outside `_app/` collides with one of Connect's, or two project files have one path. The message names the files. |
|
|
18
|
+
| A new routes folder is ignored by a running `ph connect studio` | Connect checks for the folder at startup. Restart it. |
|
|
19
|
+
| `createFileRoute("/_app/x")` is a type error | The tree is not generated yet, or the tsconfig lacks the `route-tree` path. See [Types](#types). |
|
|
20
|
+
| A sidebar link reloads the whole app | It is a plain `href`. Navigate through the router; see [Replace the sidebar](./layout.md#replace-the-sidebar). |
|
|
21
|
+
| A `staticData.nav` route is missing from the sidebar | Its path has a param, or it is not in `_app/`, or a replaced layout does not render `SidebarNavItems`/`useNavRoutes`. |
|
|
22
|
+
| A route's search param is gone after navigating | Only global params survive a navigation. Pass the param in `search` on the link. |
|
|
23
|
+
| A loader sees no drive on a deep link | The drive has not arrived yet; see [Load data](./data-and-navigation.md#load-data). |
|
|
24
|
+
| A class has no effect, e.g. `pl-7` next to `px-3` | `style.css` imports a second Tailwind build, such as `@powerhousedao/connect/style.css`. Import `@powerhousedao/connect/tailwind.css` instead, or run `ph migrate`; see [Styles](./styles-and-branding.md#styles). |
|
|
25
|
+
| A package's `dist/style.css` is hundreds of KB, or a host's `@theme` values revert to the defaults once the package loads | The package was built before packages left Connect's CSS out: its stylesheet is a full Tailwind build, whose tokens outrank the host's. Rebuild it with `ph build` and publish it; see [A package's styles](./styles-and-branding.md#a-packages-styles). |
|
|
26
|
+
| A package's token or rule works in its own Connect but not in another | It is in `hosts/connect/style.css`, which `ph build` leaves out. Move what the package's editors and routes need to `style.css`. |
|
|
27
|
+
| A host's token override doesn't reach a package's classes | The page emits only the tokens its own classes use. Override it in `@theme static` in the host's stylesheet; see [Styles](./styles-and-branding.md#styles). |
|
|
28
|
+
| Installing a package re-themes Connect | The package's `style.css` sets Connect's tokens or global rules, which ship in its stylesheet. Move them to its `hosts/connect/style.css`; `ph migrate` warns about them. |
|
|
29
|
+
| `ph build` fails: `./theme.css` is not exported from `@powerhousedao/connect` | The project's `@powerhousedao/connect` is older than `ph-cli`. Update it to the same version. |
|
|
30
|
+
|
|
31
|
+
## Upgrading
|
|
32
|
+
|
|
33
|
+
`ph migrate` updates a project for this version:
|
|
34
|
+
|
|
35
|
+
- `style.css` imports `@powerhousedao/connect/tailwind.css` instead of `@powerhousedao/design-system/theme.css` and `@powerhousedao/connect/style.css`. The project's own rules stay.
|
|
36
|
+
- `tsconfig.json` includes `.ph/connect-routes.gen.ts`, the generated tree that types the project's routes.
|
|
37
|
+
- `style.css` drops the `@import './node_modules/<package>/dist/style.css'` lines that `ph install --local` added. Connect loads a bundled package's stylesheet with its code.
|
|
38
|
+
- `hosts/connect/style.css` holds this Connect's theme; `ph migrate` creates it and warns when `style.css` sets tokens or global rules, which now ship in the package's stylesheet. Move a Connect's theme there by hand.
|
|
39
|
+
- A Tailwind host that imported `@powerhousedao/connect-core/theme.css` for core's classes imports `@powerhousedao/connect-core/tailwind.css`. `theme.css` now holds only core's tokens. `@powerhousedao/connect/tailwind.css` does this already.
|
|
40
|
+
|
|
41
|
+
A package rebuilt with `ph build` ships only its own classes and rules (see [A package's styles](./styles-and-branding.md#a-packages-styles)). Republish packages so the Connects that load them keep one Tailwind build per page.
|
|
42
|
+
|
|
43
|
+
Two `@powerhousedao/reactor-browser` types lost a member, which a project that used them updates by hand:
|
|
44
|
+
|
|
45
|
+
- `PHModal` has no `missingPackage` modal.
|
|
46
|
+
- `PHGlobal` has no `revisionHistoryVisible`. `useRevisionHistoryVisible`, `showRevisionHistory` and `hideRevisionHistory` work as before.
|
|
47
|
+
|
|
48
|
+
Editors receive `document` and `dispatch` as props. For TypeScript users this is breaking:
|
|
49
|
+
|
|
50
|
+
- `EditorModule`'s type parameters are now `<TDocument, TAction, TProps>`. A module typed `EditorModule<{ ...props }>` moves its props to the third parameter.
|
|
51
|
+
- A host that renders an `EditorModule`'s `Component` must pass `document` and `dispatch`, and should wrap it in `EditorDocumentProvider` (see [Render an editor or a drive app yourself](./data-and-navigation.md#render-an-editor-or-a-drive-app-yourself)).
|
|
52
|
+
- An editor whose component takes only its own props must share one with what hosts pass (`documentId`, `context`, `displayToolbar`), or take `EditorProps`.
|
|
53
|
+
- `ph generate` writes editors that read `document` and `dispatch` from props. A package with such an editor needs a Connect with this change: older Connects pass neither prop. Editors that use the `useSelected<Model>Document()` hooks keep working in every Connect.
|
|
54
|
+
|
|
55
|
+
In 6.2.3 dev prereleases only, `RouteSelection` and scoped PH stores (`createScopedPHStore`, `isScopedPHStore`) are gone. Drive apps read the route through `DriveProvider`, editors through `EditorDocumentProvider`, both from `@powerhousedao/reactor-browser`.
|
|
56
|
+
|
|
57
|
+
The generic plugin's UI moved behind the plugin, which a project's routes follow by hand:
|
|
58
|
+
|
|
59
|
+
- `AppLayout`, `ConnectSidebar`, `SidebarDriveItems`, `SidebarNavItems` and `OpenDocument` import from `@powerhousedao/connect/generic`, not `/layout`.
|
|
60
|
+
- `@powerhousedao/connect/route-views` exports only `ConnectRoot`; `Home`, `DriveLayout`, `NodeView`, `DrivePending` and `SettingsPage` import from `/generic`.
|
|
61
|
+
- `generic()`, `genericActive`, `IfPlugin` and `useIsPluginActive` are gone; a plugin's `ui()` provides its views.
|
|
62
|
+
- Connect's About, AI Assistant, Danger Zone, Default Editors and Package Manager tabs are the generic plugin's code routes, so `@powerhousedao/connect/routes/_app/settings/<tab>` no longer exists for them. An override imports the tab's options as `genericSettingsTabs["<tab>"]` from `@powerhousedao/connect/generic` instead; links to these tabs are untyped, so use `useLinkProps({ settings: "<tab>" })`.
|
|
63
|
+
|