@powerhousedao/connect 6.2.3-dev.7 → 6.2.3-dev.71
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 +481 -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-DxBXLSmH.js} +11 -13
- package/dist/ClearStorageModal-DxBXLSmH.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-D1I-K2Gf.js} +9 -9
- package/dist/DebugSettingsModal-D1I-K2Gf.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-D85U4oKJ.js} +70 -30
- package/dist/InspectorModal-D85U4oKJ.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-B9c-CsKT.js} +16 -14
- package/dist/OpenFileDocumentsModal-B9c-CsKT.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-D5GEwpML.js +4 -0
- package/dist/app-loader-casiq2T2.js +1253 -0
- package/dist/app-loader-casiq2T2.js.map +1 -0
- package/dist/app-skeleton-BHgmbYld.js +4 -0
- package/dist/app-skeleton-ClRUYLE_.js +121 -0
- package/dist/app-skeleton-ClRUYLE_.js.map +1 -0
- package/dist/boot-CFPdHSqB.js +233 -0
- package/dist/boot-CFPdHSqB.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-Cn2f6llN.js} +10 -6
- package/dist/build-info-Cn2f6llN.js.map +1 -0
- package/dist/components-C4K5xyad.js +121 -0
- package/dist/components-C4K5xyad.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-BIpd8edR.js +49 -0
- package/dist/drive-icon-BIpd8edR.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-DcDV9hi4.js} +48 -46
- package/dist/load-DcDV9hi4.js.map +1 -0
- package/dist/load-runtime-config-Deq75NYr.js +14 -0
- package/dist/load-runtime-config-Deq75NYr.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-CzBsaUUd.js +524 -0
- package/dist/package-manager-CzBsaUUd.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/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-CegSox2x.js +263 -0
- package/dist/plugins-CegSox2x.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 +181 -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-BGYR1N7Z.js} +509 -562
- package/dist/reactor-BGYR1N7Z.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-2aB1ZZPP.js +55 -0
- package/dist/route-views-2aB1ZZPP.js.map +1 -0
- package/dist/route-views-CDVZytw4.js +60 -0
- package/dist/route-views-CDVZytw4.js.map +1 -0
- package/dist/route-views-D_873yb_.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-B0OQvO11.js +4 -0
- package/dist/router-Cu0PH6sh.js +46 -0
- package/dist/router-Cu0PH6sh.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-CFn4TA0g.js +1090 -0
- package/dist/settings-CFn4TA0g.js.map +1 -0
- package/dist/settings-tabs-BC8gAacB.js +410 -0
- package/dist/settings-tabs-BC8gAacB.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 +3144 -764
- 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-BOTsJPoc.js +66 -0
- package/dist/ui-BOTsJPoc.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/dist/workflows-C3qEvx1R.js +63 -0
- package/dist/workflows-C3qEvx1R.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 +88 -26
- package/scripts/assert-plugin-configs.mjs +47 -0
- 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,149 @@
|
|
|
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
|
+
## Replace the sidebar
|
|
6
|
+
|
|
7
|
+
A project's `_app.tsx` replaces Connect's `_app` layout. Connect's routes and the project's `_app/` routes then render inside it.
|
|
8
|
+
|
|
9
|
+
To keep Connect's layout and change only the sidebar, render `AppLayout` with your own `sidebar`. `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:
|
|
10
|
+
|
|
11
|
+
```tsx
|
|
12
|
+
// hosts/connect/routes/_app.tsx
|
|
13
|
+
import {
|
|
14
|
+
AppLayout,
|
|
15
|
+
ConnectSidebar,
|
|
16
|
+
SidebarItem,
|
|
17
|
+
useSidebarMode,
|
|
18
|
+
} from "@powerhousedao/connect/generic";
|
|
19
|
+
import { isPlainClick } from "@powerhousedao/reactor-browser";
|
|
20
|
+
import { createFileRoute, useRouter } from "@tanstack/react-router";
|
|
21
|
+
|
|
22
|
+
export const Route = createFileRoute("/_app")({
|
|
23
|
+
component: Layout,
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
function Layout() {
|
|
27
|
+
const router = useRouter();
|
|
28
|
+
// AppLayout handles "hidden"; a custom sidebar handles "collapsed" itself.
|
|
29
|
+
const collapsed = useSidebarMode() === "collapsed";
|
|
30
|
+
return (
|
|
31
|
+
<AppLayout
|
|
32
|
+
sidebar={
|
|
33
|
+
<ConnectSidebar
|
|
34
|
+
collapsed={collapsed}
|
|
35
|
+
extraItems={
|
|
36
|
+
<>
|
|
37
|
+
<SidebarItem title="Docs" href="https://docs.example.com" />
|
|
38
|
+
<SidebarItem
|
|
39
|
+
title="Focus"
|
|
40
|
+
href={router.buildLocation({ to: "/focus" }).publicHref}
|
|
41
|
+
onClick={(event) => {
|
|
42
|
+
if (!isPlainClick(event)) return;
|
|
43
|
+
event.preventDefault();
|
|
44
|
+
void router.navigate({ to: "/focus" });
|
|
45
|
+
}}
|
|
46
|
+
/>
|
|
47
|
+
</>
|
|
48
|
+
}
|
|
49
|
+
/>
|
|
50
|
+
}
|
|
51
|
+
/>
|
|
52
|
+
);
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
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.
|
|
57
|
+
|
|
58
|
+
## Replace the layout
|
|
59
|
+
|
|
60
|
+
`@powerhousedao/connect/layout` exports core's parts to build a different layout, and `@powerhousedao/connect/generic` the generic plugin's as well. A layout that imports only from `/layout` doesn't load the generic UI:
|
|
61
|
+
|
|
62
|
+
| Export | From | What it is |
|
|
63
|
+
| --- | --- | --- |
|
|
64
|
+
| `AppLayout` | `/generic` | Connect's layout; `sidebar` replaces the sidebar. |
|
|
65
|
+
| `ConnectSidebar` | `/generic` | Connect's sidebar; `extraItems`, `collapsed`. |
|
|
66
|
+
| `SidebarDriveItems` | `/generic` | The drive items and the add-drive item. |
|
|
67
|
+
| `SidebarNavItems` | `/generic` | The `staticData.nav` items. |
|
|
68
|
+
| `SidebarItem` | `/layout` | One sidebar item. |
|
|
69
|
+
| `useNavRoutes()` | `/layout` | The `staticData.nav` routes, sorted: `{ label, icon, order, routeId, to }`. |
|
|
70
|
+
| `useSidebarMode()` | `/layout` | The current route's `staticData.sidebar`. |
|
|
71
|
+
| `ContentOutlet` | `/layout` | The matched route, in the container whose scroll Connect resets on new pages and restores on back and forward. |
|
|
72
|
+
|
|
73
|
+
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:
|
|
74
|
+
|
|
75
|
+
```tsx
|
|
76
|
+
// hosts/connect/routes/_app.tsx
|
|
77
|
+
import {
|
|
78
|
+
ContentOutlet,
|
|
79
|
+
useNavRoutes,
|
|
80
|
+
useSidebarMode,
|
|
81
|
+
} from "@powerhousedao/connect/layout";
|
|
82
|
+
import { makeDriveSlug, useDrives, useLinkProps } from "@powerhousedao/reactor-browser";
|
|
83
|
+
import { createFileRoute, Link } from "@tanstack/react-router";
|
|
84
|
+
|
|
85
|
+
export const Route = createFileRoute("/_app")({
|
|
86
|
+
component: TopNavLayout,
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
function TopNavLayout() {
|
|
90
|
+
const drives = useDrives();
|
|
91
|
+
const navRoutes = useNavRoutes();
|
|
92
|
+
const settings = useLinkProps({ settings: true });
|
|
93
|
+
const hidden = useSidebarMode() === "hidden";
|
|
94
|
+
return (
|
|
95
|
+
<div className="flex h-full flex-col">
|
|
96
|
+
{!hidden && (
|
|
97
|
+
<nav className="flex gap-2 border-b px-4 py-2">
|
|
98
|
+
<Link to="/" activeOptions={{ exact: true }}>Home</Link>
|
|
99
|
+
{drives?.map((drive) => (
|
|
100
|
+
<Link
|
|
101
|
+
key={drive.header.id}
|
|
102
|
+
to="/d/$driveSlug/{-$nodeSlug}"
|
|
103
|
+
params={{ driveSlug: makeDriveSlug(drive) }}
|
|
104
|
+
>
|
|
105
|
+
{drive.header.name}
|
|
106
|
+
</Link>
|
|
107
|
+
))}
|
|
108
|
+
{navRoutes.map((item) => (
|
|
109
|
+
// `to` is a plain string: the routes are only known at runtime.
|
|
110
|
+
<Link key={item.routeId} to={item.to as never}>
|
|
111
|
+
{item.label}
|
|
112
|
+
</Link>
|
|
113
|
+
))}
|
|
114
|
+
<a {...settings} className="ml-auto">Settings</a>
|
|
115
|
+
</nav>
|
|
116
|
+
)}
|
|
117
|
+
<main className="relative min-h-0 flex-1">
|
|
118
|
+
<ContentOutlet />
|
|
119
|
+
</main>
|
|
120
|
+
</div>
|
|
121
|
+
);
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
- `Link` sets `aria-current="page"` and the `active` class on the current route, for styling.
|
|
126
|
+
- A replaced layout is responsible for `staticData.sidebar` and embedded mode; `AppLayout` handles both, a layout of your own does not.
|
|
127
|
+
- The loading screen in `index.html` is your layout, with `_app`'s `pendingComponent` as its content; see [The loading screen](#the-loading-screen).
|
|
128
|
+
|
|
129
|
+
[`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.
|
|
130
|
+
|
|
131
|
+
## The loading screen
|
|
132
|
+
|
|
133
|
+
`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:
|
|
134
|
+
|
|
135
|
+
```tsx
|
|
136
|
+
// hosts/connect/routes/_app.tsx
|
|
137
|
+
export const Route = createFileRoute("/_app")({
|
|
138
|
+
component: Layout,
|
|
139
|
+
// The loading screen's content, and the layout's own pending view at runtime.
|
|
140
|
+
pendingComponent: () => <div role="status" className="m-auto">Loading…</div>,
|
|
141
|
+
});
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
- Without a `pendingComponent` on `_app`, the loading screen shows core's spinner.
|
|
145
|
+
- 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`).
|
|
146
|
+
- On a deep link the screen is the same, with no tab marked current; the page appears once the app routes.
|
|
147
|
+
- 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.
|
|
148
|
+
- `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.
|
|
149
|
+
|
|
@@ -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, and either wins over the `_16x16`…`_64x64` favicons taken from `branding.icon` (whose app icons still apply).
|
|
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
|
+
|