@povio/ui 5.0.0-rc.7 → 5.0.0-rc.9

package/README.md

@@ -268,3 +268,51 @@ We're using a helper class for flex, so make sure to add this into your base css
   flex: 1 0 0;
 }
 ```
+
+## App canvas page (`/_canvas`)
+
+From RC.9, Povio UI includes a ready-made page for inspecting all your TanStack Router pages. Install `@povio/ui@5.0.0-rc.9` and retain your application's existing `@tanstack/react-router` dependency (an optional peer for this integration).
+
+For file-based routing, create `src/routes/[_]canvas.tsx` (or use your configured routes directory). The brackets escape TanStack's pathless-layout underscore convention:
+
+```tsx
+import "@povio/ui/app-canvas/styles";
+import { appCanvasRouteOptions } from "@povio/ui/app-canvas/tanstack";
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/_canvas")(appCanvasRouteOptions({ enabled: import.meta.env.DEV }));
+```
+
+Mount `AppCanvasBridge` once beneath the existing router and `UIConfigurationProvider`, alongside the root `Outlet`. The provider must be shared by the canvas route and the normal application pages; keep its existing theme defaults and persistence. If the app does not yet have this provider, add one using `parseThemeCss` on its theme source.
+
+```tsx
+import { isAppCanvasFrame } from "@povio/ui/app-canvas";
+import { AppCanvasBridge, useIsAppCanvasPage } from "@povio/ui/app-canvas/tanstack";
+
+// Inside the app's root component, under its UIConfigurationProvider:
+const canvasPage = useIsAppCanvasPage();
+return (
+  <>
+    <AppCanvasBridge />
+    <Outlet />
+    {!canvasPage && !isAppCanvasFrame() && <ExistingConfigurationLauncher />}
+  </>
+);
+```
+
+`ExistingConfigurationLauncher` represents your existing launcher/editor, if any. Do not render a second `UIConfigurationModal` on `/_canvas`: the supplied page includes its own draggable editor. Keep app-specific debug overlays out of canvas frames too.
+
+For code-based routing, add the package route to the existing root's children **before** creating the router:
+
+```tsx
+import "@povio/ui/app-canvas/styles";
+import { createAppCanvasRoute } from "@povio/ui/app-canvas/tanstack";
+const canvasRoute = createAppCanvasRoute({
+  getParentRoute: () => rootRoute,
+  enabled: import.meta.env.DEV,
+  canvas: { examples: { "/projects/$projectId": { params: { projectId: "example-id" } } } },
+});
+const routeTree = rootRoute.addChildren([homeRoute, projectsRoute, canvasRoute]);
+```
+
+Then open `/_canvas` directly. `enabled` accepts a boolean or a synchronous predicate; false produces a not-found route. Apply your existing access policy if enabling it outside development. Normal page authentication and loaders still run inside the frames. The canvas excludes its own pathname, and dynamic pages without example parameters remain explicitly unresolved. The lower-level `AppCanvasPage` and `AppCanvas` components remain available from `@povio/ui/app-canvas` for custom integrations.