@powerhousedao/connect 6.2.3-staging.0 → 6.3.0-dev.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -1
- package/dist/{AddDriveModal-DhNfP94R.js → AddDriveModal-zMepHdWt.js} +43 -17
- package/dist/AddDriveModal-zMepHdWt.js.map +1 -0
- package/dist/{ClearStorageModal-RRBhBwt9.js → ClearStorageModal-Br-y7qXc.js} +10 -12
- package/dist/ClearStorageModal-Br-y7qXc.js.map +1 -0
- package/dist/{ConfirmDocumentUpgradeModal-DcOZy20m.js → ConfirmDocumentUpgradeModal-CoixS60F.js} +4 -4
- package/dist/ConfirmDocumentUpgradeModal-CoixS60F.js.map +1 -0
- package/dist/{CookiesPolicyModal-BLw4pnhn.js → CookiesPolicyModal-BpFjYc7T.js} +4 -4
- package/dist/{CookiesPolicyModal-BLw4pnhn.js.map → CookiesPolicyModal-BpFjYc7T.js.map} +1 -1
- package/dist/CreateDocumentModal-CiIW3pzx.js +45 -0
- package/dist/CreateDocumentModal-CiIW3pzx.js.map +1 -0
- package/dist/{DebugSettingsModal-CszP0h2F.js → DebugSettingsModal-FALLjVVv.js} +10 -10
- package/dist/DebugSettingsModal-FALLjVVv.js.map +1 -0
- package/dist/{DeleteDriveModal-CjGnG0ht.js → DeleteDriveModal-1pAIayG_.js} +5 -5
- package/dist/DeleteDriveModal-1pAIayG_.js.map +1 -0
- package/dist/{DeleteItemModal-BbY_4_xT.js → DeleteItemModal-BUpqmFxS.js} +6 -6
- package/dist/DeleteItemModal-BUpqmFxS.js.map +1 -0
- package/dist/{DisclaimerModal-DuglmEwL.js → DisclaimerModal-TIJXRYLF.js} +6 -6
- package/dist/DisclaimerModal-TIJXRYLF.js.map +1 -0
- package/dist/{DocumentVersionUnsupportedModal-C4fy7fZ6.js → DocumentVersionUnsupportedModal-DH9Zzsyw.js} +6 -6
- package/dist/DocumentVersionUnsupportedModal-DH9Zzsyw.js.map +1 -0
- package/dist/{DownloadDocumentWithErrorsModal-BsPQ5qgy.js → DownloadDocumentWithErrorsModal-Beh-xw8B.js} +5 -5
- package/dist/DownloadDocumentWithErrorsModal-Beh-xw8B.js.map +1 -0
- package/dist/{DriveAuthRequiredModal-CtsB0kwH.js → DriveAuthRequiredModal-XTcoJKvj.js} +6 -6
- package/dist/DriveAuthRequiredModal-XTcoJKvj.js.map +1 -0
- package/dist/DriveSettingsModal-CGZQhzBa.js +127 -0
- package/dist/DriveSettingsModal-CGZQhzBa.js.map +1 -0
- package/dist/FloatingTanStackRouterDevtools-CqogiFob-dxj8lrTP.js +2565 -0
- package/dist/FloatingTanStackRouterDevtools-CqogiFob-dxj8lrTP.js.map +1 -0
- package/dist/{InspectorModal-BirNNcyV.js → InspectorModal-xU_gCAhG.js} +20 -20
- package/dist/InspectorModal-xU_gCAhG.js.map +1 -0
- package/dist/{LoginModal-CI0ogC2-.js → LoginModal-O06ZvWFI.js} +7 -7
- package/dist/LoginModal-O06ZvWFI.js.map +1 -0
- package/dist/{OpenFileDocumentsModal-DKxleujF.js → OpenFileDocumentsModal-DJsC1oR1.js} +19 -14
- package/dist/OpenFileDocumentsModal-DJsC1oR1.js.map +1 -0
- package/dist/{UpgradeDriveModal-CXX6D5Au.js → UpgradeDriveModal-CCWKp5yn.js} +6 -6
- package/dist/UpgradeDriveModal-CCWKp5yn.js.map +1 -0
- package/dist/ai-tools-BGUMFEMV.js +42 -0
- package/dist/ai-tools-BGUMFEMV.js.map +1 -0
- package/dist/ai-tools-D_q-Whju.js +4 -0
- package/dist/app-loader-BQrucpDg.js +4 -0
- package/dist/app-loader-orww5vEA.js +1254 -0
- package/dist/app-loader-orww5vEA.js.map +1 -0
- package/dist/{app-skeleton--Me5zlSz.js → app-skeleton-CMUP2zaz.js} +36 -16
- package/dist/app-skeleton-CMUP2zaz.js.map +1 -0
- package/dist/app-skeleton-CdD1m8G3.js +4 -0
- package/dist/{boot-DPNEOI2A.js → boot-BBIArGAP.js} +32 -9
- package/dist/boot-BBIArGAP.js.map +1 -0
- package/dist/{build-info-DbLCcPJY.js → build-info-BTuoWZYI.js} +10 -6
- package/dist/build-info-BTuoWZYI.js.map +1 -0
- package/dist/components-B3kuhyeE.js +121 -0
- package/dist/components-B3kuhyeE.js.map +1 -0
- package/dist/{connect.config-CaXMoB42.js → connect.config-DL9nKtlW.js} +8 -7
- package/dist/connect.config-DL9nKtlW.js.map +1 -0
- package/dist/{connection-state-Eqc2izmt.js → connection-state-0ippUGEC.js} +28 -12
- package/dist/connection-state-0ippUGEC.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-BxXvPdIY.js → cookie-banner-NclLYtB0.js} +6 -6
- package/dist/{cookie-banner-BxXvPdIY.js.map → cookie-banner-NclLYtB0.js.map} +1 -1
- package/dist/document-editor-container-C91BsZkt.js +4 -0
- package/dist/document-editor-container-Dkk87_q1.js +311 -0
- package/dist/document-editor-container-Dkk87_q1.js.map +1 -0
- package/dist/drive-icon-BIpd8edR.js +49 -0
- package/dist/drive-icon-BIpd8edR.js.map +1 -0
- package/dist/drive-placements-DjeVpTTm.js +38 -0
- package/dist/drive-placements-DjeVpTTm.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 +140 -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-D7c2WAbn.d.ts +4 -0
- package/dist/layout-Dj3_KscE.js +5 -0
- package/dist/layout.d.ts +3 -0
- package/dist/layout.js +4 -0
- package/dist/{load-DaOnJm3B.js → load-C0hy-vOY.js} +48 -48
- package/dist/load-C0hy-vOY.js.map +1 -0
- package/dist/load-runtime-config-BoDzcgEV.js +14 -0
- package/dist/load-runtime-config-BoDzcgEV.js.map +1 -0
- package/dist/main.js +2 -2
- package/dist/open-file-uploads-B5pr1sA2.js +183 -0
- package/dist/open-file-uploads-B5pr1sA2.js.map +1 -0
- package/dist/{package-manager-BbzIV9aN.js → package-manager-B1Nxbull.js} +96 -31
- package/dist/package-manager-B1Nxbull.js.map +1 -0
- package/dist/{pglite-major-p4_YefAE.js → pglite-major-pao-ozRo.js} +5 -5
- package/dist/pglite-major-pao-ozRo.js.map +1 -0
- package/dist/{pglite-migrate-core-BcXcImng.js → pglite-migrate-core-B6FqmhH8.js} +5 -5
- package/dist/pglite-migrate-core-B6FqmhH8.js.map +1 -0
- package/dist/{pglite-seed-Cl2d-iyl.js → pglite-seed-CZsMNsV8.js} +8 -4
- package/dist/pglite-seed-CZsMNsV8.js.map +1 -0
- package/dist/plugin-configs.d.ts +242 -0
- package/dist/plugin-configs.d.ts.map +1 -0
- package/dist/plugin-configs.js +26 -0
- package/dist/plugin-configs.js.map +1 -0
- package/dist/plugins--mJeXJ7w.js +264 -0
- package/dist/plugins--mJeXJ7w.js.map +1 -0
- package/dist/{preferences-store-DZUIAkHE.js → preferences-store-DxYAnGCc.js} +5 -5
- package/dist/preferences-store-DxYAnGCc.js.map +1 -0
- package/dist/prerender.d.ts +38 -0
- package/dist/prerender.d.ts.map +1 -0
- package/dist/prerender.js +195 -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-DQRJpF0r.js → pwa-manifest-link-DNwWvnLV.js} +5 -5
- package/dist/{pwa-manifest-link-DQRJpF0r.js.map → pwa-manifest-link-DNwWvnLV.js.map} +1 -1
- package/dist/reactor-Drpw-sgc.js +1656 -0
- package/dist/reactor-Drpw-sgc.js.map +1 -0
- package/dist/reactor-chat-C6yp2S37.js +15 -0
- package/dist/reactor-chat-C6yp2S37.js.map +1 -0
- package/dist/reactor.worker.js +444 -168
- package/dist/reactor.worker.js.map +1 -1
- package/dist/{registerServiceWorker-smkROQhm.js → registerServiceWorker-OR8nokAn.js} +5 -5
- package/dist/{registerServiceWorker-smkROQhm.js.map → registerServiceWorker-OR8nokAn.js.map} +1 -1
- package/dist/root-v9fj27sn.js +27 -0
- package/dist/root-v9fj27sn.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-BovMNHyn.js +60 -0
- package/dist/route-views-BovMNHyn.js.map +1 -0
- package/dist/route-views-C-H3ofJW.js +4 -0
- package/dist/route-views-DzgRMAx8.js +55 -0
- package/dist/route-views-DzgRMAx8.js.map +1 -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-CWIsjETx.js +54 -0
- package/dist/router-CWIsjETx.js.map +1 -0
- package/dist/router-CnWkTEey.js +4 -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-C0o6eJvm.js +1089 -0
- package/dist/settings-C0o6eJvm.js.map +1 -0
- package/dist/settings-tabs-1V-sBOlj.js +424 -0
- package/dist/settings-tabs-1V-sBOlj.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 +5 -6
- package/dist/start-connect.d.ts.map +1 -1
- package/dist/start-connect.js +8 -5
- 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 +3510 -3667
- package/dist/ui-BITvvqdH.js +66 -0
- package/dist/ui-BITvvqdH.js.map +1 -0
- package/dist/ui-C1-l-Eyh.js +170 -0
- package/dist/ui-C1-l-Eyh.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/dist/workflows-C3qEvx1R.js +63 -0
- package/dist/workflows-C3qEvx1R.js.map +1 -0
- package/fonts.css +177 -0
- package/generic-routes.json +9 -0
- package/package.json +82 -21
- package/scripts/assert-plugin-configs.mjs +47 -0
- package/scripts/prerender-shell.ts +51 -0
- package/skills/customize-connect/SKILL.md +80 -0
- package/skills/customize-connect/references/data-and-navigation.md +315 -0
- package/skills/customize-connect/references/drive-apps.md +44 -0
- package/skills/customize-connect/references/hosts-and-plugins.md +88 -0
- package/skills/customize-connect/references/layout.md +162 -0
- package/skills/customize-connect/references/modals.md +99 -0
- package/skills/customize-connect/references/overrides.md +177 -0
- package/skills/customize-connect/references/packages.md +41 -0
- package/skills/customize-connect/references/pages.md +141 -0
- package/skills/customize-connect/references/runtime-config.md +411 -0
- package/skills/customize-connect/references/styles-and-branding.md +76 -0
- package/skills/customize-connect/references/types-and-troubleshooting.md +64 -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 +6 -23
- package/tailwind.css +12 -0
- package/theme.css +5 -0
- package/dist/AddDriveModal-DhNfP94R.js.map +0 -1
- package/dist/ClearStorageModal-RRBhBwt9.js.map +0 -1
- package/dist/ConfirmDocumentUpgradeModal-DcOZy20m.js.map +0 -1
- package/dist/CreateDocumentModal-Bmv0V-kY.js +0 -36
- package/dist/CreateDocumentModal-Bmv0V-kY.js.map +0 -1
- package/dist/DebugSettingsModal-CszP0h2F.js.map +0 -1
- package/dist/DeleteDriveModal-CjGnG0ht.js.map +0 -1
- package/dist/DeleteItemModal-BbY_4_xT.js.map +0 -1
- package/dist/DisclaimerModal-DuglmEwL.js.map +0 -1
- package/dist/DocumentVersionUnsupportedModal-C4fy7fZ6.js.map +0 -1
- package/dist/DownloadDocumentWithErrorsModal-BsPQ5qgy.js.map +0 -1
- package/dist/DriveAuthRequiredModal-CtsB0kwH.js.map +0 -1
- package/dist/DriveSettingsModal-d1L0eYof.js +0 -57
- package/dist/DriveSettingsModal-d1L0eYof.js.map +0 -1
- package/dist/InspectorModal-BirNNcyV.js.map +0 -1
- package/dist/LoginModal-CI0ogC2-.js.map +0 -1
- package/dist/MissingPackageModal-HFUPQMML.js +0 -49
- package/dist/MissingPackageModal-HFUPQMML.js.map +0 -1
- package/dist/OpenFileDocumentsModal-DKxleujF.js.map +0 -1
- package/dist/SettingsModal-C1vvdYGa.js +0 -571
- package/dist/SettingsModal-C1vvdYGa.js.map +0 -1
- package/dist/UpgradeDriveModal-CXX6D5Au.js.map +0 -1
- package/dist/app-loader-BxojpvRl.js +0 -4
- package/dist/app-loader-wu8Nfpe0.js +0 -2283
- package/dist/app-loader-wu8Nfpe0.js.map +0 -1
- package/dist/app-skeleton--Me5zlSz.js.map +0 -1
- package/dist/app-skeleton-CBN4tenZ.js +0 -4
- package/dist/boot-DPNEOI2A.js.map +0 -1
- package/dist/build-info-DbLCcPJY.js.map +0 -1
- package/dist/components-k4a5c62z.js +0 -5
- package/dist/connect.config-CaXMoB42.js.map +0 -1
- package/dist/connection-state-Eqc2izmt.js.map +0 -1
- package/dist/load-DaOnJm3B.js.map +0 -1
- package/dist/package-manager-BbzIV9aN.js.map +0 -1
- package/dist/pglite-major-p4_YefAE.js.map +0 -1
- package/dist/pglite-migrate-core-BcXcImng.js.map +0 -1
- package/dist/pglite-seed-Cl2d-iyl.js.map +0 -1
- package/dist/preferences-store-DZUIAkHE.js.map +0 -1
- package/dist/reactor-DxTnqFry.js +0 -1095
- package/dist/reactor-DxTnqFry.js.map +0 -1
- package/dist/renown-trust-DRgHpxlZ.js +0 -34
- package/dist/renown-trust-DRgHpxlZ.js.map +0 -1
- package/dist/runtime-config-DtJIUgYw.js +0 -24
- package/dist/runtime-config-DtJIUgYw.js.map +0 -1
- package/dist/sentry-jfDyrxdX.js +0 -15
- package/dist/sentry-jfDyrxdX.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-DuoU75ap.js +0 -453
- package/dist/useRegistryPackages-DuoU75ap.js.map +0 -1
|
@@ -0,0 +1,315 @@
|
|
|
1
|
+
# Data and navigation
|
|
2
|
+
|
|
3
|
+
How a route loads data, reads the open drive and document, types its search params, and how editors and packages navigate without knowing the routes.
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- [Load data](#load-data)
|
|
8
|
+
- [Documents of one type, across drives](#documents-of-one-type-across-drives)
|
|
9
|
+
- [The open drive and document](#the-open-drive-and-document)
|
|
10
|
+
- [Editors read their document from props](#editors-read-their-document-from-props)
|
|
11
|
+
- [Show that an action was rejected](#show-that-an-action-was-rejected)
|
|
12
|
+
- [Render an editor or a drive app yourself](#render-an-editor-or-a-drive-app-yourself)
|
|
13
|
+
- [Read and write search params](#read-and-write-search-params)
|
|
14
|
+
- [Navigate from an editor](#navigate-from-an-editor)
|
|
15
|
+
|
|
16
|
+
## Load data
|
|
17
|
+
|
|
18
|
+
A route's `loader` runs before the route renders, and on every navigation to it. Its `context` is Connect's router context (`ConnectRouterContext`):
|
|
19
|
+
|
|
20
|
+
| Field | What it is |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| `store` | The app's PH store: `drives`, `reactorClient`, `documentCache`, and the rest of `PHGlobal`. |
|
|
23
|
+
| `arrivals` | Whether drives are still arriving, e.g. right after boot (`isPending()`, `isDrivePending(driveId)`, `subscribe`). |
|
|
24
|
+
| `appName` | `connect.branding.appName`, if set. |
|
|
25
|
+
| `shell` | `true` while `ph connect build` prerenders the loading screen: a layout shows its `pendingComponent`. |
|
|
26
|
+
|
|
27
|
+
This loader reads a document through the reactor client:
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
// hosts/connect/routes/_app/documents/$documentId.tsx
|
|
31
|
+
import { createFileRoute, notFound } from "@tanstack/react-router";
|
|
32
|
+
|
|
33
|
+
export const Route = createFileRoute("/_app/documents/$documentId")({
|
|
34
|
+
loader: async ({ context, params, abortController }) => {
|
|
35
|
+
const client = context.store.reactorClient;
|
|
36
|
+
if (!client) throw new Error("The reactor is not ready");
|
|
37
|
+
try {
|
|
38
|
+
const document = await client.get(
|
|
39
|
+
params.documentId,
|
|
40
|
+
undefined,
|
|
41
|
+
abortController.signal,
|
|
42
|
+
);
|
|
43
|
+
return { name: document.header.name, type: document.header.documentType };
|
|
44
|
+
} catch {
|
|
45
|
+
throw notFound();
|
|
46
|
+
}
|
|
47
|
+
},
|
|
48
|
+
component: DocumentSummary,
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
function DocumentSummary() {
|
|
52
|
+
const { name, type } = Route.useLoaderData();
|
|
53
|
+
return <p className="p-6">{name} is a {type}</p>;
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- Connect starts the reactor before it renders the router, so `reactorClient` is set in Connect. The check satisfies the type.
|
|
58
|
+
- Loader data is a snapshot. It does not update when the document changes. For live data, read it in the component with the `@powerhousedao/reactor-browser` hooks (`useDrives`, `useDocument`, `useDocumentById`).
|
|
59
|
+
- `store.drives` holds the drives that have arrived. On a deep link to a remote drive, it can be incomplete while `arrivals.isPending()` is true.
|
|
60
|
+
- `useDocument`, `useDocumentById`, `useDocumentsByIds` and `useDocumentsOfType` suspend until their documents load. Put a `<Suspense>` boundary around the component that calls them, or give the route a `pendingComponent`; otherwise the nearest boundary above shows its fallback, which can be the whole layout.
|
|
61
|
+
|
|
62
|
+
### Documents of one type, across drives
|
|
63
|
+
|
|
64
|
+
`useDocumentsOfType` takes a document model module and returns its documents from every drive, a page at a time, typed by the module. The module is the `PascalCase` constant `ph generate` writes for the model, exported from `document-models/<name>`:
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
// hosts/connect/routes/_app/ledgers.tsx
|
|
68
|
+
import { ProductionLedger } from "document-models/production-ledger";
|
|
69
|
+
import {
|
|
70
|
+
loadDocumentsOfType,
|
|
71
|
+
useDocumentLinkProps,
|
|
72
|
+
useDocumentsOfType,
|
|
73
|
+
} from "@powerhousedao/reactor-browser";
|
|
74
|
+
import { createFileRoute } from "@tanstack/react-router";
|
|
75
|
+
|
|
76
|
+
export const Route = createFileRoute("/_app/ledgers")({
|
|
77
|
+
// The first page arrives with the route, so the page doesn't suspend.
|
|
78
|
+
loader: () => loadDocumentsOfType(ProductionLedger, { limit: 20 }),
|
|
79
|
+
component: Ledgers,
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
function Ledgers() {
|
|
83
|
+
const { documents, hasNextPage, loadNextPage } = useDocumentsOfType(
|
|
84
|
+
ProductionLedger,
|
|
85
|
+
{ limit: 20 },
|
|
86
|
+
);
|
|
87
|
+
return (
|
|
88
|
+
<ul>
|
|
89
|
+
{documents.map((ledger) => (
|
|
90
|
+
<LedgerRow key={ledger.header.id} id={ledger.header.id} name={ledger.header.name} />
|
|
91
|
+
))}
|
|
92
|
+
{hasNextPage && <button onClick={loadNextPage}>More</button>}
|
|
93
|
+
</ul>
|
|
94
|
+
);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
function LedgerRow({ id, name }: { id: string; name: string }) {
|
|
98
|
+
// Opens the document in its drive; undefined until a loaded drive lists it.
|
|
99
|
+
const link = useDocumentLinkProps(id);
|
|
100
|
+
return <li>{link ? <a {...link}>{name}</a> : name}</li>;
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
- `limit` is the page size (25 by default). `loadNextPage()` appends the next page; `hasNextPage` and `isLoadingNextPage` say where it is.
|
|
105
|
+
- The order is the reactor's, not sorted; a local reactor returns them grouped by drive. Sort on the page when order matters.
|
|
106
|
+
- Each document is checked against the module's schema. Documents of the type that fail it, e.g. written by another version of the model, are in `invalid`, not in `documents`.
|
|
107
|
+
- The list follows documents being created and deleted, and each document updates as it changes.
|
|
108
|
+
- In a Connect with a local reactor, the list is what the browser has synced so far.
|
|
109
|
+
- `useDocumentLinkProps(id)` links any document by id through the drive that lists it, and `useDocumentTarget(id)` gives its `{ driveSlug, nodeSlug }`. `driveSlug` is the drive's URL slug (e.g. `book-club-<id>`), not its `header.slug`. A node's URL slug is `makeNodeSlug(node)`, its name's slug plus its id, not the bare document id.
|
|
110
|
+
- To create a document from your own page, call `addDocument(driveId, name, documentType)` from `@powerhousedao/reactor-browser`, then open it with `useDocumentLinkProps(id)` or its node slug. In event handlers, call navigation as `() => void navigate(...)`.
|
|
111
|
+
|
|
112
|
+
### The open drive and document
|
|
113
|
+
|
|
114
|
+
A view reads the drive route's drive, folder and document with `useDriveRouteData()` from `@powerhousedao/connect/layout` (`@powerhousedao/connect-core/router` in a package's routes):
|
|
115
|
+
|
|
116
|
+
```tsx
|
|
117
|
+
const { drive, folder, documentId } = useDriveRouteData();
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
- `useDriveRouteIds()`, from `@powerhousedao/connect/router` or `@powerhousedao/connect-core/router`, gives the ids alone, from the matched route's loader.
|
|
121
|
+
- A drive app gets the drive and a `dispatch` bound to it as props, and its `useSelectedDrive`, `useSelectedFolder` and `useSelectedNode` read the route it is shown in, through a drive context (below).
|
|
122
|
+
- An editor gets the route's document and a `dispatch` bound to it as props, and the `useSelected*Document` hooks inside it read that document. See [Editors read their document from props](#editors-read-their-document-from-props).
|
|
123
|
+
- Connect still writes the route's ids to the app-wide selection (`store.selectedDriveId`, `store.selectedNodeId`) for code outside a route, such as a sidebar widget.
|
|
124
|
+
|
|
125
|
+
### Editors read their document from props
|
|
126
|
+
|
|
127
|
+
Connect passes an editor the route's `document` and a `dispatch` bound to it. `EditorProps<TDocument, TAction>` from `document-model` types both for the editor's document:
|
|
128
|
+
|
|
129
|
+
```tsx
|
|
130
|
+
import { DocumentToolbar } from "@powerhousedao/design-system/connect";
|
|
131
|
+
import type { EditorProps } from "document-model";
|
|
132
|
+
import type { TodoAction, TodoDocument } from "document-models/todo";
|
|
133
|
+
import { TodoList } from "./components/TodoList.js";
|
|
134
|
+
|
|
135
|
+
export default function Editor({
|
|
136
|
+
document,
|
|
137
|
+
}: EditorProps<TodoDocument, TodoAction>) {
|
|
138
|
+
return (
|
|
139
|
+
<>
|
|
140
|
+
<DocumentToolbar document={document} />
|
|
141
|
+
{/* TodoList calls useSelectedTodoDocument(), which reads this document. */}
|
|
142
|
+
<TodoList />
|
|
143
|
+
</>
|
|
144
|
+
);
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
- `ph generate` writes editors this way, and types the editor's module as `EditorModule<TodoDocument, TodoAction>`.
|
|
149
|
+
- Pass `document` to `DocumentToolbar`. Without it, the toolbar shows the app's selected document, which is wrong when a host renders a document by id.
|
|
150
|
+
- Components inside the editor call the generated `useSelected<Model>Document()`. It reads the document the editor was rendered with, from an `EditorDocumentProvider` the host renders around the editor; without one it reads the app's selection.
|
|
151
|
+
- An editor that reads its document from props needs a Connect that passes them (see [Upgrading](./types-and-troubleshooting.md#upgrading)). Editors that only use the hooks work in every Connect.
|
|
152
|
+
|
|
153
|
+
### Show that an action was rejected
|
|
154
|
+
|
|
155
|
+
When a reducer throws one of the model's errors, the operation is stored with the error and the state stays unchanged. The write itself succeeds, so the editor hears about it only if it asks. Pass `dispatch` an `onErrors` callback:
|
|
156
|
+
|
|
157
|
+
```tsx
|
|
158
|
+
const [error, setError] = useState<string>();
|
|
159
|
+
|
|
160
|
+
function rename(title: string) {
|
|
161
|
+
setError(undefined);
|
|
162
|
+
dispatch(actions.setTitle({ title }), (errors) =>
|
|
163
|
+
setError(errors[0]?.message),
|
|
164
|
+
);
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
- Each rejected action arrives as an `OperationRejectedError` from `@powerhousedao/reactor-browser`. `message` is the reducer's error message. The error also has `actionId`, `actionType`, `scope`, the operation's `index`, and `kind`: `"reducer-error"`, or `"denied"` for a write the document's policy refused. `OperationRejectedError.isError(error)` tells it apart from a dispatch that failed outright, such as a missing document.
|
|
169
|
+
- A batch reports only the actions that were rejected; the others still apply.
|
|
170
|
+
- `onSuccess`, the third argument, runs once the write lands, also when an action in it was rejected. Clear the error before dispatching, not in `onSuccess`.
|
|
171
|
+
- This works in every reactor mode: in-process, worker and remote.
|
|
172
|
+
- Don't read `document.operations` for this: Connect does not load an editor's operations. The revision history lists every operation's errors.
|
|
173
|
+
|
|
174
|
+
### Render an editor or a drive app yourself
|
|
175
|
+
|
|
176
|
+
A project route that renders an editor passes it `document` and `dispatch`, and wraps it in `EditorDocumentProvider` from `@powerhousedao/reactor-browser` with the same pair. `useEditorModuleFor(document)` picks the document's editor:
|
|
177
|
+
|
|
178
|
+
```tsx
|
|
179
|
+
import {
|
|
180
|
+
EditorDocumentProvider,
|
|
181
|
+
useDocumentById,
|
|
182
|
+
useEditorModuleFor,
|
|
183
|
+
} from "@powerhousedao/reactor-browser";
|
|
184
|
+
|
|
185
|
+
function HostedEditor({ documentId }: { documentId: string }) {
|
|
186
|
+
const [document, dispatch] = useDocumentById(documentId);
|
|
187
|
+
const editor = useEditorModuleFor(document);
|
|
188
|
+
if (!document || !editor) return null;
|
|
189
|
+
const Editor = editor.Component;
|
|
190
|
+
return (
|
|
191
|
+
<EditorDocumentProvider document={document} dispatch={dispatch}>
|
|
192
|
+
<Editor document={document} dispatch={dispatch} />
|
|
193
|
+
</EditorDocumentProvider>
|
|
194
|
+
);
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
- A drive app goes inside `DriveProvider`, whose value is `{ drive, dispatch, folder?, nodeId?, open?, preload? }`. Without `open`, opening a node navigates the app's router in that drive. With it, the host decides, e.g. it keeps the open node in local state; `preload` warms a node the same way.
|
|
199
|
+
- An editor inside another editor gets its own `EditorDocumentProvider`; hooks read the nearest one.
|
|
200
|
+
|
|
201
|
+
## Read and write search params
|
|
202
|
+
|
|
203
|
+
Connect parses every query param as a string. A route types its own params with `validateSearch`, and reruns its loader on them with `loaderDeps`:
|
|
204
|
+
|
|
205
|
+
```tsx
|
|
206
|
+
// hosts/connect/routes/_app/inventory.tsx
|
|
207
|
+
import { createFileRoute, Link, useNavigate } from "@tanstack/react-router";
|
|
208
|
+
|
|
209
|
+
type Sort = "name" | "size";
|
|
210
|
+
|
|
211
|
+
export const Route = createFileRoute("/_app/inventory")({
|
|
212
|
+
validateSearch: (search: Record<string, unknown>): { sort: Sort; q?: string } => ({
|
|
213
|
+
sort: search.sort === "size" ? "size" : "name",
|
|
214
|
+
q: typeof search.q === "string" ? search.q : undefined,
|
|
215
|
+
}),
|
|
216
|
+
loaderDeps: ({ search }) => ({ sort: search.sort }),
|
|
217
|
+
loader: ({ context, deps }) => {
|
|
218
|
+
const drives = (context.store.drives ?? []).map((drive) => ({
|
|
219
|
+
slug: drive.header.slug,
|
|
220
|
+
name: drive.header.name,
|
|
221
|
+
size: drive.state.global.nodes.length,
|
|
222
|
+
}));
|
|
223
|
+
drives.sort((a, b) =>
|
|
224
|
+
deps.sort === "size" ? b.size - a.size : a.name.localeCompare(b.name),
|
|
225
|
+
);
|
|
226
|
+
return { drives };
|
|
227
|
+
},
|
|
228
|
+
component: Inventory,
|
|
229
|
+
});
|
|
230
|
+
|
|
231
|
+
function Inventory() {
|
|
232
|
+
const { drives } = Route.useLoaderData();
|
|
233
|
+
const { sort, q } = Route.useSearch();
|
|
234
|
+
const navigate = useNavigate({ from: Route.fullPath });
|
|
235
|
+
const shown = drives.filter((d) => !q || d.name.includes(q));
|
|
236
|
+
return (
|
|
237
|
+
<div className="flex flex-col gap-2 p-6">
|
|
238
|
+
<input
|
|
239
|
+
value={q ?? ""}
|
|
240
|
+
onChange={(e) =>
|
|
241
|
+
void navigate({
|
|
242
|
+
search: (prev) => ({ ...prev, q: e.target.value || undefined }),
|
|
243
|
+
replace: true,
|
|
244
|
+
})
|
|
245
|
+
}
|
|
246
|
+
/>
|
|
247
|
+
<Link to="/inventory" search={{ sort: sort === "name" ? "size" : "name" }}>
|
|
248
|
+
Sort by {sort === "name" ? "size" : "name"}
|
|
249
|
+
</Link>
|
|
250
|
+
<ul>
|
|
251
|
+
{shown.map((drive) => (
|
|
252
|
+
<li key={drive.slug}>
|
|
253
|
+
<Link to="/d/$driveSlug/{-$nodeSlug}" params={{ driveSlug: drive.slug }}>
|
|
254
|
+
{drive.name} ({drive.size})
|
|
255
|
+
</Link>
|
|
256
|
+
</li>
|
|
257
|
+
))}
|
|
258
|
+
</ul>
|
|
259
|
+
</div>
|
|
260
|
+
);
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
- `Route.useSearch()` also returns every other param in the URL, typed `string | undefined`.
|
|
265
|
+
- A route's own params are dropped when the user navigates to another route.
|
|
266
|
+
- Global params survive every navigation: `driveUrl`, `theme`, `embed`, `LOG_LEVEL`, `reactorWorker`, and any `FEATURE_*` flag. The list is `GLOBAL_SEARCH_PARAMS` in `@powerhousedao/reactor-browser`; Connect's root route keeps them (`src/router/search.ts` in `@powerhousedao/connect-core`).
|
|
267
|
+
- Non-string values are written with `JSON.stringify`, so `2` becomes `?page=2` and reads back as `"2"`.
|
|
268
|
+
|
|
269
|
+
## Navigate from an editor
|
|
270
|
+
|
|
271
|
+
Editors and packages do not know the project's routes, and may run outside Connect. `@powerhousedao/reactor-browser` navigates by target instead of path, through the host's navigation (Connect's router in Connect; `window.history` elsewhere):
|
|
272
|
+
|
|
273
|
+
- `{ driveSlug, nodeSlug? }` (`PHDriveTarget`): a drive, or a node in it.
|
|
274
|
+
- `{ settings: "<tab>" }` or `{ settings: true }` (`PHSettingsTarget`): a settings tab, or the first tab.
|
|
275
|
+
- `undefined`: home.
|
|
276
|
+
|
|
277
|
+
```tsx
|
|
278
|
+
import {
|
|
279
|
+
openTarget,
|
|
280
|
+
useLinkProps,
|
|
281
|
+
useSearchParams,
|
|
282
|
+
useSetSearchParams,
|
|
283
|
+
} from "@powerhousedao/reactor-browser";
|
|
284
|
+
|
|
285
|
+
// An <a> that navigates in the app and opens new tabs normally.
|
|
286
|
+
export function OpenInvoice(props: { driveSlug: string; nodeSlug: string }) {
|
|
287
|
+
const link = useLinkProps({ driveSlug: props.driveSlug, nodeSlug: props.nodeSlug });
|
|
288
|
+
return <a {...link}>Open invoice</a>;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
export function SettingsButton() {
|
|
292
|
+
return (
|
|
293
|
+
<button onClick={() => openTarget({ settings: "inventory" })}>
|
|
294
|
+
Inventory settings
|
|
295
|
+
</button>
|
|
296
|
+
);
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
// Query params of the current page; an object merges, `undefined` removes a key.
|
|
300
|
+
export function TabSwitch() {
|
|
301
|
+
const { tab = "summary" } = useSearchParams();
|
|
302
|
+
const setSearchParams = useSetSearchParams();
|
|
303
|
+
return (
|
|
304
|
+
<button onClick={() => setSearchParams({ tab: tab === "summary" ? "history" : "summary" })}>
|
|
305
|
+
Showing {tab}
|
|
306
|
+
</button>
|
|
307
|
+
);
|
|
308
|
+
}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
- `useLinkProps(target)` returns `href`, `onClick`, `aria-current` and preload handlers for an `<a>`.
|
|
312
|
+
- `openTarget(target)` and `store.navigation.open(target)` navigate from code.
|
|
313
|
+
- `showPHModal({ type: "settings" })` is deprecated. In Connect it opens `/settings`.
|
|
314
|
+
- A project route can use the same API, but the router's `Link` and `useNavigate` are typed and reach the project's own routes.
|
|
315
|
+
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Drive apps
|
|
2
|
+
|
|
3
|
+
A drive app is the view Connect shows for a drive: its own listing, forms and tools around the open document. It is an editor module for `powerhouse/document-drive`, shipped by a package like any editor. Routes change Connect around it ([overrides.md](./overrides.md)); this guide is the app itself.
|
|
4
|
+
|
|
5
|
+
## Make one
|
|
6
|
+
|
|
7
|
+
Create a `powerhouse/app` document in the Vetra drive, the way the powerhouse-editors skill makes an editor: give it a name and the document types it holds, then set it to CONFIRMED. Codegen writes `editors/<app-id>/`:
|
|
8
|
+
|
|
9
|
+
- `editor.tsx`, the app's root. Codegen writes it once and never again, so edit it.
|
|
10
|
+
- `components/`, a folder tree, folder contents and a create button to start from; it too stays yours.
|
|
11
|
+
- `config.ts`, the app's `allowedDocumentTypes` and drag and drop.
|
|
12
|
+
|
|
13
|
+
## What it gets
|
|
14
|
+
|
|
15
|
+
Connect renders the app in the drive route with these props:
|
|
16
|
+
|
|
17
|
+
- `document`: the drive.
|
|
18
|
+
- `dispatch`: bound to the drive, for drive actions such as `addFolder` and `moveNode` from `@powerhousedao/shared/document-drive`. `moveNode({ srcFolder, targetParentFolder })` moves any node: `srcFolder` is the id of the file or folder being moved.
|
|
19
|
+
- `children`: the open document's editor, or `null` on a folder or the drive's root. Render it where the document goes, and the app's own view when it is `null`.
|
|
20
|
+
|
|
21
|
+
Inside it, the `@powerhousedao/reactor-browser` hooks read the route it is shown in:
|
|
22
|
+
|
|
23
|
+
- `useSelectedDrive()` (a `[drive, dispatch]` pair), `useSelectedFolder()`, `useSelectedNode()` and `useNodesInSelectedDrive()`.
|
|
24
|
+
- `useNodesInSelectedDriveOrFolder()` lists the open folder, or the drive's root when no folder is open. `useNodesInSelectedFolder()` and the generated `use<Model>DocumentsInSelectedFolder()` give `undefined` at the root.
|
|
25
|
+
- The drive view sizes the app to its content: give the app's root element `w-full` (and `h-full` for a full-height layout).
|
|
26
|
+
- `const setSelectedNode = useSetSelectedNode()` inside a drive app: `setSelectedNode(id)` opens a folder or document; `setSelectedNode(undefined)` goes back to the drive's root. Both are router navigations, so Back, Forward and reloads land on the same node.
|
|
27
|
+
- `useLinkProps(useNodeTarget(node))` makes a row a real link.
|
|
28
|
+
- `getDriveName(drive)` is the drive's display name; drives made in the UI leave `header.name` empty.
|
|
29
|
+
- `showCreateDocumentModal(type)` opens Connect's create modal, which adds the document to the open folder and opens it.
|
|
30
|
+
- Documents in Connect don't carry their operations: `document.operations.global` is an empty array, however long the history. Read history with `useDocumentOperations(id, "global")`, and the operation count with `document.header.revision.global`.
|
|
31
|
+
|
|
32
|
+
The `reactor-browser` actions do the same work from outside the app: `addFolder(driveId, name, parentId?)`, `renameDriveNode(driveId, nodeId, name)` and `deleteNode(driveId, nodeId)`.
|
|
33
|
+
|
|
34
|
+
## Which app a drive shows
|
|
35
|
+
|
|
36
|
+
A drive shows the app its `header.meta.preferredEditor` names. With none, or an app no loaded package has, Connect shows its Drive Explorer (`powerhouse/generic-drive-explorer`); a host without the generic plugin shows core's directory listing.
|
|
37
|
+
|
|
38
|
+
- **A new drive in the UI:** Create Drive's "Drive App" picker. Package apps are listed first, so a project's app is preselected.
|
|
39
|
+
- **A new drive in code:** `addDrive(input, appId)` from `@powerhousedao/reactor-browser`, or `driveInput.preferredEditor` in the MCP `addDrive` tool.
|
|
40
|
+
- **A drive every user gets:** a local entry in `connect.drives.defaultDrives` with `"app": "<app-id>"` ([runtime-config.md](./runtime-config.md)). Connect creates it on first boot and opens it in that app.
|
|
41
|
+
- **The Vetra Preview drive:** `"vetra": { "previewDrive": { "app": "<app-id>" } }` in `powerhouse.config.json`. `ph vetra --watch` sets that app on the drive each time it starts, so a fresh clone gets it too.
|
|
42
|
+
- **An existing drive:** `setPreferredEditorOnNode(driveId, appId)` from `@powerhousedao/reactor-browser`, which dispatches `setPreferredEditor`. Connect has no UI for this yet, so a project that needs it adds a button, e.g. on a page that lists the drives. The change syncs like any other drive operation.
|
|
43
|
+
|
|
44
|
+
The home cards and `useAppModuleById(drive.header.meta?.preferredEditor)` show which app a drive uses.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Hosts and plugins
|
|
2
|
+
|
|
3
|
+
A project runs Connect as one or more hosts (`hosts/<name>/host.js`). Each host picks its routes folder, its config and its plugins.
|
|
4
|
+
|
|
5
|
+
## Routes per host
|
|
6
|
+
|
|
7
|
+
Every host of a project mounts `hosts/connect/routes/` by default. A host picks another folder, or none, with `runner.routes`:
|
|
8
|
+
|
|
9
|
+
```js
|
|
10
|
+
// hosts/lab/host.js
|
|
11
|
+
export default {
|
|
12
|
+
name: "lab",
|
|
13
|
+
runner: {
|
|
14
|
+
module: "@powerhousedao/ph-cli/runners/connect",
|
|
15
|
+
routes: "hosts/lab/routes", // or false: Connect's routes only
|
|
16
|
+
},
|
|
17
|
+
};
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
- The folder works like `hosts/connect/routes/`: `_app.tsx`, `_app/` and overrides of Connect's routes apply to that host only.
|
|
21
|
+
- `ph run lab dev` and `ph run lab build` generate its tree in `.ph/hosts/lab/routes.gen.ts`; `hosts/connect/routes/` keeps `.ph/connect-routes.gen.ts`.
|
|
22
|
+
- Only `hosts/connect/routes/` is offered to other Connects (see [Offer a package's routes](./packages.md#offer-a-packages-routes)) and type-checked by `ph build`.
|
|
23
|
+
- To type-check a host's folder, exclude it from the project's `tsconfig.json` and give it its own, which maps the route tree to its generated file:
|
|
24
|
+
|
|
25
|
+
```jsonc
|
|
26
|
+
// hosts/lab/routes/tsconfig.json
|
|
27
|
+
{
|
|
28
|
+
"extends": "../../../tsconfig.json",
|
|
29
|
+
"compilerOptions": {
|
|
30
|
+
"noEmit": true,
|
|
31
|
+
"incremental": false,
|
|
32
|
+
// Replaces the project's paths: copy any others the routes import.
|
|
33
|
+
"paths": {
|
|
34
|
+
"@powerhousedao/connect/route-tree": ["../../../.ph/hosts/lab/routes.gen.ts"],
|
|
35
|
+
"@powerhousedao/connect-core/route-tree": ["../../../.ph/hosts/lab/routes.gen.ts"]
|
|
36
|
+
}
|
|
37
|
+
},
|
|
38
|
+
"include": [".", "../../../.ph/hosts/lab/routes.gen.ts"]
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
- Lint can't use that tsconfig: oxlint's type-aware rules check every file against the project's `tsconfig.json`, so they report the host's route ids as errors. Add the folder to `.oxlintrc.json`'s `ignorePatterns`, and type-check it with `tsc -p hosts/lab/routes/tsconfig.json`.
|
|
43
|
+
|
|
44
|
+
## Run a host
|
|
45
|
+
|
|
46
|
+
`ph run <host> <verb>` runs a host with its runner: `dev`, `build` and `serve` for a Connect host, for `ph` and `ph-cli` alike:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
ph run lab dev
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
- `ph init` writes a `hosts/<name>/host.js` for each built-in host (`connect`, `switchboard`, `vetra` and the others) and a `hosts/README.md` on their format. A project made before 6.3 may have only `hosts/connect/style.css`; write a host's `host.js` yourself, as above.
|
|
53
|
+
- `build` writes to the host's `runner.outDir`, by default `.ph/connect-build/dist` as `ph connect build` does, and `serve` serves the same folder. `dist/` is the package that `ph build` writes.
|
|
54
|
+
- Each host's dev server keeps its own Vite cache, `node_modules/.vite-<host>`, so `ph vetra` and `ph run lab dev` can run side by side.
|
|
55
|
+
|
|
56
|
+
The setting that picks each command's port:
|
|
57
|
+
|
|
58
|
+
| Command | Port | Default |
|
|
59
|
+
| --- | --- | --- |
|
|
60
|
+
| `ph connect studio` | `--port` | 3000 |
|
|
61
|
+
| `ph vetra` | `--connect-port`, else `PH_VETRA_CONNECT_PORT`, else `vetra.connectPort` | 3001 |
|
|
62
|
+
| `ph connect preview` | `--port` | 4173 |
|
|
63
|
+
| `ph run <host> dev` and `serve` | the host's `runner.port`; the `hosts/connect/host.js` that `ph init` writes reads `studio.port` | 3000 |
|
|
64
|
+
|
|
65
|
+
## Host plugins
|
|
66
|
+
|
|
67
|
+
`hosts/connect/host.js` also lists `runner.plugins`, read by `ph run connect`. They transform the served runtime config through the plugin host in `@powerhousedao/connect-core` (its `src/plugins/plugin-host.ts`), which runs the built-in plugins Connect registers ([`apps/connect/src/plugins/`](https://github.com/powerhouse-inc/powerhouse/tree/main/apps/connect/src/plugins)): `@powerhousedao/connect/plugins/generic` (`allowAddDrive`, drive sections), `.../sentry`, `.../openpanel` and `.../assistant`. A listed plugin switches its slice of the config on, and an unlisted one switches it off. Other modules are skipped with a warning.
|
|
68
|
+
|
|
69
|
+
The generic plugin is also Connect's chrome: its sidebar, home screen and settings page. A composition that leaves it out shows core's views instead: a header, an index of the drives, a directory listing for a drive without a drive app, and a JSON view for a document without an editor. Without a declared composition, Connect is classic: every built-in plugin is active.
|
|
70
|
+
|
|
71
|
+
## A plugin's UI
|
|
72
|
+
|
|
73
|
+
A plugin definition's `ui()` loads what the plugin shows, only while the plugin is active (`ConnectPluginUi` in `@powerhousedao/connect-core/plugins`):
|
|
74
|
+
|
|
75
|
+
| Field | What it does |
|
|
76
|
+
| --- | --- |
|
|
77
|
+
| `routes` | Route options by route id, e.g. `"/_app/": { component: Home }`. They apply only while the route shows core's view, so a project's own route file wins. `staticData` merges over the route's. |
|
|
78
|
+
| `addRoutes` | Code routes, e.g. the generic plugin's settings tabs; a route at a path the tree already serves is skipped. |
|
|
79
|
+
| `modals` | Modal views by type, over core's. |
|
|
80
|
+
| `Root` | Rendered once beside the app. |
|
|
81
|
+
| `errorComponent` | Any route's loader or render error. |
|
|
82
|
+
| `commonEditors` | Keeps common's drive explorer and editors, which core leaves out. |
|
|
83
|
+
| `consent` | Needs the viewer's consent to analytics cookies; Connect shows one banner when any active plugin needs it (Sentry and OpenPanel do). |
|
|
84
|
+
|
|
85
|
+
- `loadRuntimeConfig` loads the active plugins' UI before the router exists; the router applies it once. Later plugins in the composition win.
|
|
86
|
+
- `shell` on a definition names the prerendered loading screen that shows its UI; a composition picks the shell of its first plugin that has one, else core's.
|
|
87
|
+
- The generic plugin's code lives in [`apps/connect/src/generic/`](https://github.com/powerhouse-inc/powerhouse/tree/main/apps/connect/src/generic), reached only through its `ui()`, so a composition without it doesn't download it. A project's route builds on it through `@powerhousedao/connect/generic` (or `/layout`).
|
|
88
|
+
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
# Layout and the loading screen
|
|
2
|
+
|
|
3
|
+
A project's `_app.tsx` replaces the layout around Connect's pages: keep Connect's and change its sidebar, or build another from its parts. The layout is also the loading screen.
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- [Replace the sidebar](#replace-the-sidebar)
|
|
8
|
+
- [Replace the layout](#replace-the-layout)
|
|
9
|
+
- [The loading screen](#the-loading-screen)
|
|
10
|
+
|
|
11
|
+
## Replace the sidebar
|
|
12
|
+
|
|
13
|
+
A project's `_app.tsx` replaces Connect's `_app` layout. Connect's routes and the project's `_app/` routes then render inside it.
|
|
14
|
+
|
|
15
|
+
To keep Connect's layout and add a header or footer bar, render `AppLayout` with `header` and `footer`; to change only the sidebar, pass your own `sidebar`. In a layout of your own, `useConnectChrome()` gives `{ embedded, sidebarHidden, sidebarCollapsed }`. `ConnectSidebar` is Connect's sidebar; `extraItems` go after the drives and nav links. Both are the generic plugin's UI, exported from `@powerhousedao/connect/generic` with core's parts:
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
// hosts/connect/routes/_app.tsx
|
|
19
|
+
import {
|
|
20
|
+
AppLayout,
|
|
21
|
+
ConnectSidebar,
|
|
22
|
+
SidebarItem,
|
|
23
|
+
useSidebarMode,
|
|
24
|
+
} from "@powerhousedao/connect/generic";
|
|
25
|
+
import { options } from "@powerhousedao/connect/routes/_app";
|
|
26
|
+
import { isPlainClick } from "@powerhousedao/reactor-browser";
|
|
27
|
+
import { createFileRoute, useRouter } from "@tanstack/react-router";
|
|
28
|
+
|
|
29
|
+
export const Route = createFileRoute("/_app")({
|
|
30
|
+
// Empty today; spread so an option Connect adds later isn't dropped.
|
|
31
|
+
...options,
|
|
32
|
+
component: Layout,
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
function Layout() {
|
|
36
|
+
const router = useRouter();
|
|
37
|
+
// AppLayout handles "hidden"; a custom sidebar handles "collapsed" itself.
|
|
38
|
+
const collapsed = useSidebarMode() === "collapsed";
|
|
39
|
+
return (
|
|
40
|
+
<AppLayout
|
|
41
|
+
sidebar={
|
|
42
|
+
<ConnectSidebar
|
|
43
|
+
collapsed={collapsed}
|
|
44
|
+
extraItems={
|
|
45
|
+
<>
|
|
46
|
+
<SidebarItem title="Docs" href="https://docs.example.com" />
|
|
47
|
+
<SidebarItem
|
|
48
|
+
title="Focus"
|
|
49
|
+
href={router.buildLocation({ to: "/focus" }).publicHref}
|
|
50
|
+
onClick={(event) => {
|
|
51
|
+
if (!isPlainClick(event)) return;
|
|
52
|
+
event.preventDefault();
|
|
53
|
+
void router.navigate({ to: "/focus" });
|
|
54
|
+
}}
|
|
55
|
+
/>
|
|
56
|
+
</>
|
|
57
|
+
}
|
|
58
|
+
/>
|
|
59
|
+
}
|
|
60
|
+
/>
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
- The sidebar shows only icons. `title` is the item's tooltip and its accessible name, and `description` is shown in the tooltip under it and read as its description. An item without an `icon` shows the title's first letter.
|
|
66
|
+
- On a phone, `ConnectSidebar` is a bar under the page, with the items in a row: rendered by `AppLayout`, passed as `sidebar`, or rendered by a component of yours that is. Any other `sidebar` keeps the place its markup gives it.
|
|
67
|
+
|
|
68
|
+
A plain `href` makes the browser load the whole app again. Use it for external links only. For a link inside Connect, navigate through the router, as the "Focus" item does, or render the router's `Link`. `isPlainClick` leaves modified clicks (new tab, new window) to the browser.
|
|
69
|
+
|
|
70
|
+
## Replace the layout
|
|
71
|
+
|
|
72
|
+
`@powerhousedao/connect/layout` exports core's parts to build a different layout, and `@powerhousedao/connect/generic` the generic plugin's as well. `/generic` re-exports everything in `/layout`, so either import works for a `/layout` part. A layout that imports only from `/layout` doesn't load the generic UI:
|
|
73
|
+
|
|
74
|
+
| Export | From | What it is |
|
|
75
|
+
| --- | --- | --- |
|
|
76
|
+
| `AppLayout` | `/generic` | Connect's layout; `sidebar` replaces the sidebar. |
|
|
77
|
+
| `ConnectSidebar` | `/generic` | Connect's sidebar; `extraItems`, `collapsed`. |
|
|
78
|
+
| `SidebarDriveItems` | `/generic` | The drive items and the add-drive item. |
|
|
79
|
+
| `SidebarNavItems` | `/generic` | The `staticData.nav` items. |
|
|
80
|
+
| `SidebarItem` | `/layout` | One sidebar item: `title`, `icon` (an element, unlike `staticData.nav`'s component), `description`, `href` or `onClick`. |
|
|
81
|
+
| `useNavRoutes()` | `/layout` | The `staticData.nav` routes, sorted: `{ label, icon, order, routeId, to }`. |
|
|
82
|
+
| `useSidebarMode()` | `/layout` | The current route's `staticData.sidebar`. |
|
|
83
|
+
| `ContentOutlet` | `/layout` | The matched route, in the container whose scroll Connect resets on new pages and restores on back and forward. |
|
|
84
|
+
|
|
85
|
+
A layout renders a `<ContentOutlet />` for the matched route; a plain `<Outlet />` works too, without the scroll handling. This one replaces the sidebar with a top bar:
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
// hosts/connect/routes/_app.tsx
|
|
89
|
+
import {
|
|
90
|
+
ContentOutlet,
|
|
91
|
+
useNavRoutes,
|
|
92
|
+
useSidebarMode,
|
|
93
|
+
} from "@powerhousedao/connect/layout";
|
|
94
|
+
import { makeDriveSlug, useDrives, useLinkProps } from "@powerhousedao/reactor-browser";
|
|
95
|
+
import { createFileRoute, Link } from "@tanstack/react-router";
|
|
96
|
+
|
|
97
|
+
export const Route = createFileRoute("/_app")({
|
|
98
|
+
component: TopNavLayout,
|
|
99
|
+
});
|
|
100
|
+
|
|
101
|
+
function TopNavLayout() {
|
|
102
|
+
const drives = useDrives();
|
|
103
|
+
const navRoutes = useNavRoutes();
|
|
104
|
+
const settings = useLinkProps({ settings: true });
|
|
105
|
+
const hidden = useSidebarMode() === "hidden";
|
|
106
|
+
return (
|
|
107
|
+
<div className="flex h-full flex-col">
|
|
108
|
+
{!hidden && (
|
|
109
|
+
<nav className="flex gap-2 border-b px-4 py-2">
|
|
110
|
+
<Link to="/" activeOptions={{ exact: true }}>Home</Link>
|
|
111
|
+
{drives?.map((drive) => (
|
|
112
|
+
<Link
|
|
113
|
+
key={drive.header.id}
|
|
114
|
+
to="/d/$driveSlug/{-$nodeSlug}"
|
|
115
|
+
params={{ driveSlug: makeDriveSlug(drive) }}
|
|
116
|
+
>
|
|
117
|
+
{drive.header.name}
|
|
118
|
+
</Link>
|
|
119
|
+
))}
|
|
120
|
+
{navRoutes.map((item) => (
|
|
121
|
+
// `to` is a plain string: the routes are only known at runtime.
|
|
122
|
+
<Link key={item.routeId} to={item.to as never}>
|
|
123
|
+
{item.label}
|
|
124
|
+
</Link>
|
|
125
|
+
))}
|
|
126
|
+
<a {...settings} className="ml-auto">Settings</a>
|
|
127
|
+
</nav>
|
|
128
|
+
)}
|
|
129
|
+
<main className="relative min-h-0 flex-1">
|
|
130
|
+
<ContentOutlet />
|
|
131
|
+
</main>
|
|
132
|
+
</div>
|
|
133
|
+
);
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
- `Link` sets `aria-current="page"` and the `active` class on the current route, for styling.
|
|
138
|
+
- A replaced layout is responsible for `staticData.sidebar` and embedded mode; `AppLayout` handles both, a layout of your own does not.
|
|
139
|
+
- The loading screen in `index.html` is your layout, with `_app`'s `pendingComponent` as its content; see [The loading screen](#the-loading-screen).
|
|
140
|
+
|
|
141
|
+
[`test/versioned-documents/hosts/connect/routes/`](https://github.com/powerhouse-inc/powerhouse/tree/main/test/versioned-documents/hosts/connect/routes) in the Powerhouse repository holds a working project: a full page, and a sidebar route with search params and a nested route.
|
|
142
|
+
|
|
143
|
+
## The loading screen
|
|
144
|
+
|
|
145
|
+
`ph connect build` renders the project's routes at `/` and inlines the result into `index.html`, so the page shows the layout before any JavaScript runs. In that render the layout's content area (`ContentOutlet`) shows the `_app` route's `pendingComponent` in place of the page:
|
|
146
|
+
|
|
147
|
+
```tsx
|
|
148
|
+
// hosts/connect/routes/_app.tsx
|
|
149
|
+
export const Route = createFileRoute("/_app")({
|
|
150
|
+
component: Layout,
|
|
151
|
+
// The loading screen's content, and the layout's own pending view at runtime.
|
|
152
|
+
pendingComponent: () => <div role="status" className="m-auto">Loading…</div>,
|
|
153
|
+
});
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
- Without a `pendingComponent` on `_app`, the loading screen shows core's spinner.
|
|
157
|
+
- The render runs at build time, in Node, with no drives: components on the path to `/` must not touch `window` while rendering, and should show nothing for data that isn't there yet (e.g. `useDrives()` is `undefined`).
|
|
158
|
+
- Studio renders the screen too, at start and on route edits. If it fails, Studio shows the error over the page and in its log, since `ph connect build` fails on it.
|
|
159
|
+
- On a deep link the screen is the same, with no tab marked current; the page appears once the app routes.
|
|
160
|
+
- The screen's CSS is inlined: Tailwind builds the project's `style.css` for just the classes in the screen's markup, with its tokens and rules and without third-party CSS. The full stylesheet loads without blocking the first paint.
|
|
161
|
+
- `staticData.nav` items are links the layout renders, so they appear on the loading screen; drives arrive later, so put them after the static items to avoid a shift.
|
|
162
|
+
|