@chuvenger/devdock 0.4.1 → 0.6.0

package/README.md

@@ -9,10 +9,11 @@ routes and run custom commands.
 
 - 🔒 **Dev-gated by default** — renders only in a dev build served from a dev host (localhost/LAN), so it never ships to a real URL. Fully overridable.
 - 🧭 **Route jumper** — list routes manually, or auto-detect your `/dev` routes from React Router or SvelteKit.
-- ⚡ **Custom commands** — register any action (reset DB, toggle a flag, copy a token…).
+- ⚡ **Custom commands** — register any action (reset DB, toggle a flag, copy a token…), with live labels and check marks for toggles.
+- 📊 **Custom views** — mount your own UI in the popup for anything a list can't say: a frame-rate meter, a sync status, a segmented control.
 - 🔎 Filter box + keyboard nav (↑/↓/Enter/Esc) and an optional global hotkey.
 - 🎨 Zero CSS to import — inline-styled, high z-index, no runtime dependencies.
-- 🛡️ **Shadow DOM isolated** by default — the host page's CSS can't touch it (and vice versa).
+- 🛡️ **Shadow DOM isolated** by default — the host page's CSS can't touch it (and vice versa), or `shadow: "inherit"` to let your design system in.
 - 🧩 **Framework-agnostic core** with thin **React** and **Svelte** adapters.
 
 ## Architecture
@@ -22,13 +23,13 @@ framework-free core (`createDevDock`) that builds DOM directly. The framework
 adapters are tiny wrappers that drive its `create → update → destroy`
 lifecycle:
 
-| Import | What you get |
-| ------ | ------------ |
-| `@chuvenger/devdock` | `createDevDock(options)` — vanilla core, works anywhere |
-| `@chuvenger/devdock/react` | `<DevDock />` React component |
-| `@chuvenger/devdock/react-router` | `<ReactRouterDevDock />` + route auto-detection |
-| `@chuvenger/devdock/svelte` | `use:devdock` Svelte action |
-| `@chuvenger/devdock/sveltekit` | `use:devdock` + route auto-detection for SvelteKit |
+| Import | What you get | Custom views |
+| ------ | ------------ | ------------ |
+| `@chuvenger/devdock` | `createDevDock(options)` — vanilla core, works anywhere | `mount(host)` → teardown |
+| `@chuvenger/devdock/react` | `<DevDock />` React component | `render: () => <JSX />`, portaled in |
+| `@chuvenger/devdock/react-router` | `<ReactRouterDevDock />` + route auto-detection | same as `/react` |
+| `@chuvenger/devdock/svelte` | `use:devdock` Svelte action | `mount(host)` → teardown |
+| `@chuvenger/devdock/sveltekit` | `use:devdock` + route auto-detection for SvelteKit | `mount(host)` → teardown |
 
 `react`, `react-dom`, `react-router`, and `svelte` are all **optional** peer
 deps — install only what your adapter needs. The react-router adapter imports
@@ -132,6 +133,43 @@ arguments — to reach one, use a command that navigates to a known id:
 <ReactRouterDevDock staticRoutes match={(r) => r.path.length < 20} />
 ```
 
+### React Router framework mode (`app/routes.ts`)
+
+Framework mode works, with one wrinkle: its routes are **lazy**. `handle` is an
+export of the route *module*, so until that module loads it isn't on the route
+object the adapter reads — a `handle.devLabel` on a page you haven't opened has
+nothing to take effect on. Such routes still list by path convention (`/dev/*`),
+labelled with their path.
+
+`loadHandles` closes the gap by importing the lazy route modules to read their
+`handle`:
+
+```tsx
+<ReactRouterDevDock loadHandles />
+```
+
+```tsx
+// app/routes/dev.style-guide.tsx
+export const handle = { devLabel: "Style Guide", devGroup: "Internal" };
+```
+
+It's opt-in because reading a handle up front means importing the module up
+front — every lazy route's module, and any side effect its import carries. That
+only ever happens in development (the dock doesn't render in production), but it
+is real work on a dev page load. Leave it off if path labels are fine; turn it
+on if you want `devLabel` / `devGroup`, or `handle.dev` to mark a route that
+isn't under `/dev` (without it, such a route is never seen at all).
+
+One thing it can't do: list a route the router hasn't discovered yet. Framework
+mode fetches route branches as links render, so the dock watches the tree and
+picks them up as they arrive — but a dev route nothing links to stays unknown
+until you navigate there. Ship the whole tree up front with
+`routeDiscovery: { mode: "initial" }` in `react-router.config.ts`.
+
+`loadHandles` is not framework-only: a plain data router with
+`lazy: () => import("./route")` hides `handle` exactly the same way, and the
+flag reads it the same way.
+
 ## Svelte
 
 `@chuvenger/devdock/svelte` exports a Svelte action — no extra build step, works
@@ -226,6 +264,140 @@ dock.destroy();                  // remove entirely
 
 Use this to build a Vue/Angular/web-component adapter, or wire it up by hand.
 
+## Stateful commands
+
+A command is normally fire-and-forget. Two optional fields turn one into a
+control that shows its own state — both are re-read on every render of the open
+panel, so the row updates in place:
+
+```tsx
+<DevDock
+  commands={[
+    // A function label: the row shows live state.
+    { id: "theme", label: () => `Theme: ${theme}`, keepOpen: true, run: toggleTheme },
+    // `checked` renders a check mark and makes the row a real toggle
+    // (role="checkbox" + aria-checked).
+    { id: "freeze", label: "Freeze animations", checked: () => frozen, keepOpen: true, run: freeze },
+  ]}
+/>
+```
+
+Pair them with `keepOpen: true` so the popup stays put and you can watch the
+value change. Give a command with a function `label` an explicit `id` — the id
+is what keeps the row stable when the text changes.
+
+## Custom views
+
+Some state has no row shape at all: a frame-rate meter, four lines of sync
+facts, a segmented control. Pass those in as **views** — your own UI, mounted
+inside the popup, keeping the dock's shell, hotkey, filter, route detection and
+dev-gating.
+
+Views are mounted when the popup **opens** and torn down when it **closes**,
+which is what makes a `requestAnimationFrame` loop or an event listener inside
+one correct rather than a leak.
+
+### React
+
+```tsx
+<DevDock
+  shadow="inherit"             // ← see below: views need the app's CSS
+  views={[
+    { id: "fps", label: "Frame rate", render: () => <FrameRate /> },
+    { id: "theme", label: "Theme", render: () => <ThemeControl value={theme} onChange={setTheme} /> },
+    // Two views under one "Session" heading, below the routes/commands list.
+    { id: "facts", group: "Session", order: "after", render: () => <SyncFacts /> },
+    { id: "signin", group: "Session", order: "after", render: () => <SignInButton /> },
+  ]}
+/>
+```
+
+The component is rendered with `createPortal` into a host element the dock
+owns, so it stays part of your React tree: context, hooks and state all work,
+and it re-renders when the component holding `<DevDock>` does. A view whose
+`id` is unchanged is **never remounted**, so re-rendering the parent is free.
+
+### Vanilla / Svelte
+
+The core contract is framework-free: fill the host element, return a teardown.
+
+```ts
+createDevDock({
+  views: [
+    {
+      id: "fps",
+      label: "Frame rate",
+      mount: (host) => {
+        let raf = requestAnimationFrame(function tick() {
+          host.textContent = `${fps()} fps`;
+          raf = requestAnimationFrame(tick);
+        });
+        return () => cancelAnimationFrame(raf); // ← runs when the popup closes
+      },
+    },
+  ],
+});
+```
+
+In Svelte the same field takes a component (Svelte 5 shown; on Svelte 4 use
+`new MyPanel({ target: host })` and `component.$destroy()`):
+
+```svelte
+<script lang="ts">
+  import { mount, unmount } from "svelte";
+  import { devdock } from "@chuvenger/devdock/svelte";
+  import SyncFacts from "./SyncFacts.svelte";
+
+  const options = {
+    shadow: "inherit",
+    views: [
+      {
+        id: "facts",
+        label: "Session",
+        mount: (host) => {
+          const view = mount(SyncFacts, { target: host });
+          return () => unmount(view);
+        },
+      },
+    ],
+  };
+</script>
+
+<div use:devdock={options}></div>
+```
+
+### Views and your CSS
+
+The dock renders inside a shadow root, and **the document's stylesheet does not
+cross that boundary** — a view that renders your app's own components renders
+unstyled. If your view needs the host app's CSS, say so:
+
+- `shadow="inherit"` — keep the shadow root, but copy the document's styles
+  into it (`document.adoptedStyleSheets` plus every `<style>` and
+  `<link rel="stylesheet">`, re-synced as your bundler injects or edits them).
+- `shadow={false}` — render in the light DOM, where the page's CSS applies
+  directly.
+
+Isolation stays the default. Two things to know about `"inherit"`:
+
+- The page's CSS can now reach the dock's own chrome too, and your design
+  system's tokens arrive with the page's assumptions — a light-theme token
+  lands on the dock's dark panel. Scope the tokens you need onto the view's
+  own root.
+- **The rules cross the boundary; the element tree does not.** A selector
+  anchored on an ancestor outside the shadow root —
+  `html[data-theme="dark"] .card`, `body.compact .row` — still won't match
+  inside it. Re-apply that state on the view's own root, where it can.
+
+`shadow` is read once, when the dock is created: a shadow root can't be
+detached, so `update()` ignores it.
+
+> Testing a view with `@testing-library/user-event`? It can't type into a
+> shadow root — it installs its value interceptor from a `focus` listener on
+> the document, where the event has been retargeted to the shadow host. Render
+> with `shadow: false` in tests, or write the value through the native setter
+> and dispatch `input` yourself.
+
 ## Controlling when it shows
 
 By default the dock renders only when **both** of these hold:
@@ -271,9 +443,18 @@ tree-shakes it: `{import.meta.env.DEV && <DevDock … />}`.
 The dock is styled entirely with inline styles (no stylesheet to import) and,
 by default, renders inside an **open shadow root** attached to a host element in
 `document.body`. That means the host page's CSS can't leak in and the dock's
-styles can't leak out. Pass `shadow: false` to render in the light DOM instead
-(e.g. if you want to override its look from the page). The host element carries
-a `data-devdock` attribute either way.
+styles can't leak out. The host element carries a `data-devdock` attribute in
+every mode.
+
+| `shadow` | Where it renders | The page's CSS |
+| -------- | ---------------- | -------------- |
+| `true` (default) | shadow root | kept out |
+| `"inherit"` | shadow root | copied in, and kept in sync |
+| `false` | light DOM | applies directly |
+
+Use `"inherit"` (or `false`) when a [custom view](#views-and-your-css) renders
+your app's own components and needs its stylesheet. Otherwise leave it alone —
+isolation is the reason the dock survives arbitrary host CSS.
 
 ## API
 
@@ -283,6 +464,7 @@ a `data-devdock` attribute either way.
 | ------------ | ----------------------------- | ------------------------------------ | ----------- |
 | `routes`     | `DevRoute[]`                  | `[]`                                 | Navigable destinations. |
 | `commands`   | `DevCommand[]`                | `[]`                                 | Custom actions. |
+| `views`      | `DevView[]`                   | `[]`                                 | Custom panels, mounted while the popup is open. |
 | `enabled`    | `boolean \| (() => boolean)`  | dev build **and** dev host           | Whether to render at all. Overrides both default checks. A predicate is re-checked on every update. |
 | `devHostOnly`| `boolean`                     | `true`                               | Also require a localhost/LAN hostname, so dev builds on real URLs stay hidden. Ignored when `enabled` is set. |
 | `onNavigate` | `(path: string) => void`      | `window.location.assign`             | How to navigate on route select. |
@@ -292,21 +474,29 @@ a `data-devdock` attribute either way.
 | `hotkey`     | `string \| null`              | `null`                               | Toggle shortcut, e.g. `"mod+."`. |
 | `zIndex`     | `number`                      | `2147483000`                         | Base z-index. |
 | `container`  | `HTMLElement`                 | `document.body`                      | Where to mount. |
-| `shadow`     | `boolean`                     | `true`                               | Render in a shadow root (CSS-isolated). Set `false` for light DOM. |
+| `shadow`     | `boolean \| "inherit"`        | `true`                               | Render in a shadow root (CSS-isolated). `"inherit"` copies the page's styles in; `false` renders in the light DOM. Read once, at creation. |
 
 `DevRoute`: `{ path: string; label?: string; group?: string }`
 
-`DevCommand`: `{ label: string; run: () => void | Promise<void>; id?: string; group?: string; keepOpen?: boolean }`
+`DevCommand`: `{ label: string | (() => string); run: () => void | Promise<void>; checked?: () => boolean; id?: string; group?: string; keepOpen?: boolean }`
+
+`DevView`: `{ mount: (host: HTMLElement) => void | (() => void); id?: string; label?: string; group?: string; order?: "before" | "after" }` — on the React adapter, `render: () => ReactNode` replaces `mount`.
 
 ### `@chuvenger/devdock` (core)
 
 - `createDevDock(options?): { update(options), destroy() }` — mounts the dock; no-ops during SSR (no `document`).
 - `matchHotkey(spec, event)` — the hotkey matcher (exported for reuse).
 
+### `@chuvenger/devdock/react`
+
+- `DevDock(props)` — the component. Same options as the core, with `views` taking `render: () => ReactNode` instead of `mount`.
+- `DevDockView` — the React view shape.
+
 ### `@chuvenger/devdock/react-router`
 
-- `ReactRouterDevDock(props)` — `DevDock` wired to `useNavigate()` + auto-detected routes. Extra props: `match?: RouteMatcher`, `staticRoutes?: boolean`.
-- `useDetectedRoutes(options?): DevRoute[]` — the detected routes (build your own UI). Takes `{ match?, staticRoutes? }`, or a bare matcher.
+- `ReactRouterDevDock(props)` — `DevDock` wired to `useNavigate()` + auto-detected routes. Extra props: `match?: RouteMatcher`, `staticRoutes?: boolean`, `loadHandles?: boolean`.
+- `useDetectedRoutes(options?): DevRoute[]` — the detected routes (build your own UI). Takes `{ match?, staticRoutes?, loadHandles? }`, or a bare matcher. Re-reads the tree as the router grows it.
+- `loadHandles` — import lazy route modules to read their `handle`; needed for `handle` in [framework mode](#react-router-framework-mode-approutests).
 - `flattenRoutes(routes, parent?, options?): DevRoute[]` — pure helper that flattens a route tree.
 - `RouteMatcher` — `string | RegExp | ((route: DevRoute) => boolean)`.
 

package/dist/chunk-3MVFATRN.js

@@ -0,0 +1,60 @@
+import { keyViews, createDevDock } from './chunk-NXZNFF34.js';
+import { useRef, useState, useMemo, useEffect } from 'react';
+import { createPortal } from 'react-dom';
+import { jsx, Fragment } from 'react/jsx-runtime';
+
+var NO_VIEWS = [];
+function DevDock({ views = NO_VIEWS, ...options }) {
+  const instance = useRef(null);
+  const [hosts, setHosts] = useState(
+    () => /* @__PURE__ */ new Map()
+  );
+  const alive = useRef(true);
+  const keyed = useMemo(() => keyViews(views), [views]);
+  const coreViews = useMemo(
+    () => keyed.map(({ key, view }) => ({
+      id: key,
+      label: view.label,
+      group: view.group,
+      order: view.order,
+      mount: (host) => {
+        setHosts((prev) => new Map(prev).set(key, host));
+        return () => {
+          if (!alive.current) return;
+          setHosts((prev) => {
+            const next = new Map(prev);
+            next.delete(key);
+            return next;
+          });
+        };
+      }
+    })),
+    [keyed]
+  );
+  const latest = useRef({ options, coreViews });
+  latest.current = { options, coreViews };
+  useEffect(() => {
+    alive.current = true;
+    const inst = createDevDock({
+      ...latest.current.options,
+      views: latest.current.coreViews
+    });
+    instance.current = inst;
+    return () => {
+      alive.current = false;
+      inst.destroy();
+      instance.current = null;
+    };
+  }, []);
+  useEffect(() => {
+    instance.current?.update({ ...options, views: coreViews });
+  });
+  return /* @__PURE__ */ jsx(Fragment, { children: keyed.map(({ key, view }) => {
+    const host = hosts.get(key);
+    return host ? createPortal(view.render(), host, key) : null;
+  }) });
+}
+
+export { DevDock };
+//# sourceMappingURL=chunk-3MVFATRN.js.map
+//# sourceMappingURL=chunk-3MVFATRN.js.map

package/dist/chunk-3MVFATRN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/DevDock.tsx"],"names":[],"mappings":";;;;;AA6BA,IAAM,WAA0B,EAAC;AAQ1B,SAAS,QAAQ,EAAE,KAAA,GAAQ,QAAA,EAAU,GAAG,SAAQ,EAAiB;AACtE,EAAA,MAAM,QAAA,GAAW,OAA+B,IAAI,CAAA;AAIpD,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAI,QAAA;AAAA,IACxB,0BAAU,GAAA;AAAI,GAChB;AAGA,EAAA,MAAM,KAAA,GAAQ,OAAO,IAAI,CAAA;AAIzB,EAAA,MAAM,KAAA,GAAQ,QAAQ,MAAM,QAAA,CAAS,KAAK,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AAEpD,EAAA,MAAM,SAAA,GAAY,OAAA;AAAA,IAChB,MACE,KAAA,CAAM,GAAA,CAAI,CAAC,EAAE,GAAA,EAAK,MAAK,MAAO;AAAA,MAC5B,EAAA,EAAI,GAAA;AAAA,MACJ,OAAO,IAAA,CAAK,KAAA;AAAA,MACZ,OAAO,IAAA,CAAK,KAAA;AAAA,MACZ,OAAO,IAAA,CAAK,KAAA;AAAA,MACZ,KAAA,EAAO,CAAC,IAAA,KAAS;AACf,QAAA,QAAA,CAAS,CAAC,SAAS,IAAI,GAAA,CAAI,IAAI,CAAA,CAAE,GAAA,CAAI,GAAA,EAAK,IAAI,CAAC,CAAA;AAC/C,QAAA,OAAO,MAAM;AACX,UAAA,IAAI,CAAC,MAAM,OAAA,EAAS;AACpB,UAAA,QAAA,CAAS,CAAC,IAAA,KAAS;AACjB,YAAA,MAAM,IAAA,GAAO,IAAI,GAAA,CAAI,IAAI,CAAA;AACzB,YAAA,IAAA,CAAK,OAAO,GAAG,CAAA;AACf,YAAA,OAAO,IAAA;AAAA,UACT,CAAC,CAAA;AAAA,QACH,CAAA;AAAA,MACF;AAAA,KACF,CAAE,CAAA;AAAA,IACJ,CAAC,KAAK;AAAA,GACR;AAKA,EAAA,MAAM,MAAA,GAAS,MAAA,CAAO,EAAE,OAAA,EAAS,WAAW,CAAA;AAC5C,EAAA,MAAA,CAAO,OAAA,GAAU,EAAE,OAAA,EAAS,SAAA,EAAU;AAEtC,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,KAAA,CAAM,OAAA,GAAU,IAAA;AAChB,IAAA,MAAM,OAAO,aAAA,CAAc;AAAA,MACzB,GAAG,OAAO,OAAA,CAAQ,OAAA;AAAA,MAClB,KAAA,EAAO,OAAO,OAAA,CAAQ;AAAA,KACvB,CAAA;AACD,IAAA,QAAA,CAAS,OAAA,GAAU,IAAA;AACnB,IAAA,OAAO,MAAM;AACX,MAAA,KAAA,CAAM,OAAA,GAAU,KAAA;AAChB,MAAA,IAAA,CAAK,OAAA,EAAQ;AACb,MAAA,QAAA,CAAS,OAAA,GAAU,IAAA;AAAA,IACrB,CAAA;AAAA,EACF,CAAA,EAAG,EAAE,CAAA;AAEL,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,QAAA,CAAS,SAAS,MAAA,CAAO,EAAE,GAAG,OAAA,EAAS,KAAA,EAAO,WAAW,CAAA;AAAA,EAC3D,CAAC,CAAA;AAED,EAAA,uCAEK,QAAA,EAAA,KAAA,CAAM,GAAA,CAAI,CAAC,EAAE,GAAA,EAAK,MAAK,KAAM;AAC5B,IAAA,MAAM,IAAA,GAAO,KAAA,CAAM,GAAA,CAAI,GAAG,CAAA;AAC1B,IAAA,OAAO,OAAO,YAAA,CAAa,IAAA,CAAK,QAAO,EAAG,IAAA,EAAM,GAAG,CAAA,GAAI,IAAA;AAAA,EACzD,CAAC,CAAA,EACH,CAAA;AAEJ","file":"chunk-3MVFATRN.js","sourcesContent":["import { useEffect, useMemo, useRef, useState, type ReactNode } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { createDevDock, keyViews } from \"../core/dock\";\nimport type {\n  DevDockInstance,\n  DevDockOptions,\n  DevView,\n} from \"../core/types\";\n\n/**\n * A custom panel rendered by React inside the dock's popup. Same contract as\n * the core's {@link DevView}, with `render` in place of `mount`: the component\n * is portaled into the dock, mounted when the popup opens and unmounted when\n * it closes.\n *\n * A view renders inside the dock's shadow root, which the document's\n * stylesheets don't cross — pass `shadow=\"inherit\"` (or `shadow={false}`) if\n * it uses your app's CSS.\n */\nexport interface DevDockView extends Omit<DevView, \"mount\"> {\n  /** The view's content. Called on every render of the host `<DevDock>`. */\n  render: () => ReactNode;\n}\n\nexport type DevDockProps = Omit<DevDockOptions, \"views\"> & {\n  /** Custom panels rendered inside the popup. See {@link DevDockView}. */\n  views?: DevDockView[];\n};\n\nconst NO_VIEWS: DevDockView[] = [];\n\n/**\n * React wrapper around the framework-agnostic core. The dock itself mounts\n * into `document.body` (or `container`) and is torn down on unmount; this\n * component renders only the portals for any `views` you pass, so with none it\n * renders nothing. Safe to leave mounted; it renders nothing in production.\n */\nexport function DevDock({ views = NO_VIEWS, ...options }: DevDockProps) {\n  const instance = useRef<DevDockInstance | null>(null);\n  // The host elements the core created for our views, keyed the same way it\n  // keys them. React draws into these with a portal, which keeps the core free\n  // of any React import.\n  const [hosts, setHosts] = useState<ReadonlyMap<string, HTMLElement>>(\n    () => new Map(),\n  );\n  // `destroy()` tears views down, which would otherwise ask an unmounting\n  // component to set state.\n  const alive = useRef(true);\n\n  // Keyed exactly the way the core keys the host elements, so each portal\n  // finds its own.\n  const keyed = useMemo(() => keyViews(views), [views]);\n\n  const coreViews = useMemo<DevView[]>(\n    () =>\n      keyed.map(({ key, view }) => ({\n        id: key,\n        label: view.label,\n        group: view.group,\n        order: view.order,\n        mount: (host) => {\n          setHosts((prev) => new Map(prev).set(key, host));\n          return () => {\n            if (!alive.current) return;\n            setHosts((prev) => {\n              const next = new Map(prev);\n              next.delete(key);\n              return next;\n            });\n          };\n        },\n      })),\n    [keyed],\n  );\n\n  // The core reconciles views by id and no-ops when their shape is unchanged,\n  // so handing it a fresh array on every render costs nothing and never\n  // remounts a view.\n  const latest = useRef({ options, coreViews });\n  latest.current = { options, coreViews };\n\n  useEffect(() => {\n    alive.current = true;\n    const inst = createDevDock({\n      ...latest.current.options,\n      views: latest.current.coreViews,\n    });\n    instance.current = inst;\n    return () => {\n      alive.current = false;\n      inst.destroy();\n      instance.current = null;\n    };\n  }, []);\n\n  useEffect(() => {\n    instance.current?.update({ ...options, views: coreViews });\n  });\n\n  return (\n    <>\n      {keyed.map(({ key, view }) => {\n        const host = hosts.get(key);\n        return host ? createPortal(view.render(), host, key) : null;\n      })}\n    </>\n  );\n}\n"]}