@chuvenger/devdock 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruven Chu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# devdock
+
+A tiny, dependency-free dev-only floating button. It sits in a corner of your
+app, **only renders in development**, and opens a popup to jump between dev
+routes and run custom commands.
+
+- 🔒 **Dev-gated by default** — hidden when `process.env.NODE_ENV === "production"`. Fully overridable.
+- 🧭 **Route jumper** — list routes manually, or auto-detect them from React Router.
+- ⚡ **Custom commands** — register any action (reset DB, toggle a flag, copy a token…).
+- 🔎 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).
+- 🧩 **Framework-agnostic core** with thin **React** and **Svelte** adapters.
+
+## Architecture
+
+The button, popup, filtering, keyboard handling, and dev-gating live in a
+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 |
+
+`react`, `react-dom`, `react-router-dom`, and `svelte` are all **optional** peer
+deps — install only what your adapter needs.
+
+## Install
+
+```bash
+npm install @chuvenger/devdock
+# or: bun add @chuvenger/devdock / pnpm add @chuvenger/devdock
+```
+
+## React
+
+```tsx
+import { DevDock } from "@chuvenger/devdock/react";
+
+export function App() {
+  return (
+    <>
+      {/* …your app… */}
+      <DevDock
+        routes={[
+          { path: "/admin", label: "Admin" },
+          { path: "/style-guide", label: "Style guide" },
+        ]}
+        commands={[
+          { label: "Reset onboarding", run: () => localStorage.clear() },
+          { label: "Log current user", run: async () => console.log(await getUser()) },
+        ]}
+        hotkey="mod+."
+      />
+    </>
+  );
+}
+```
+
+In production the component renders nothing, so it's safe to leave mounted.
+
+### React Router (auto-detected routes)
+
+For a React Router **data router** (`createBrowserRouter`), use the dedicated
+entry. It navigates through the SPA router (no full reload) and discovers your
+routes automatically:
+
+```tsx
+import { ReactRouterDevDock } from "@chuvenger/devdock/react-router";
+
+function Layout() {
+  return (
+    <>
+      <Outlet />
+      <ReactRouterDevDock commands={[{ label: "Reload", run: () => location.reload() }]} />
+    </>
+  );
+}
+```
+
+Render it inside the router tree. Dynamic (`:id`) and splat (`*`) routes are
+skipped since they need arguments. Customize per route via React Router's
+`handle`:
+
+```tsx
+{ path: "reports", element: <Reports />, handle: { devLabel: "Reports", devGroup: "Internal", hidden: false } }
+```
+
+**Scope which routes are detected** with `match` — a glob (`*` = any
+characters), a `RegExp`, or a predicate. Manual `routes` are always included:
+
+```tsx
+<ReactRouterDevDock match="/dev/*" />          // only routes under /dev
+<ReactRouterDevDock match={/^\/(admin|dev)/} />
+<ReactRouterDevDock match={(r) => r.path.length < 20} />
+```
+
+## Svelte
+
+`@chuvenger/devdock/svelte` exports a Svelte action — no extra build step, works
+in any Svelte 4/5 app:
+
+```svelte
+<script lang="ts">
+  import { devdock } from "@chuvenger/devdock/svelte";
+
+  const options = {
+    routes: [{ path: "/admin", label: "Admin" }],
+    commands: [{ label: "Reset", run: () => localStorage.clear() }],
+    hotkey: "mod+.",
+    onNavigate: (path) => goto(path), // e.g. SvelteKit's goto
+  };
+</script>
+
+<!-- The dock mounts to document.body; this element is just an anchor. -->
+<div use:devdock={options}></div>
+```
+
+Reactive `options` flow through automatically (the action's `update` re-renders).
+
+## Vanilla / any framework
+
+```ts
+import { createDevDock } from "@chuvenger/devdock";
+
+const dock = createDevDock({
+  routes: [{ path: "/admin", label: "Admin" }],
+  commands: [{ label: "Reset", run: () => localStorage.clear() }],
+});
+
+// later…
+dock.update({ enabled: false }); // hide
+dock.destroy();                  // remove entirely
+```
+
+Use this to build a Vue/Angular/web-component adapter, or wire it up by hand.
+
+## Controlling when it shows
+
+`enabled` overrides the default `NODE_ENV` check — pass a boolean or a
+predicate (re-evaluated on every update):
+
+```tsx
+// Show in dev, plus in prod when ?debug is present:
+<DevDock enabled={import.meta.env.DEV || location.search.includes("debug")} />
+
+// Or a callback, e.g. gate on a role or a runtime flag:
+<DevDock enabled={() => currentUser?.isStaff ?? false} />
+```
+
+To strip it from production bundles entirely, gate the element so the minifier
+tree-shakes it: `{import.meta.env.DEV && <DevDock … />}`.
+
+## Styling & isolation
+
+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.
+
+## API
+
+### Options (shared by every adapter)
+
+| Option       | Type                          | Default                              | Description |
+| ------------ | ----------------------------- | ------------------------------------ | ----------- |
+| `routes`     | `DevRoute[]`                  | `[]`                                 | Navigable destinations. |
+| `commands`   | `DevCommand[]`                | `[]`                                 | Custom actions. |
+| `enabled`    | `boolean \| (() => boolean)`  | `NODE_ENV !== "production"`          | Whether to render at all. A predicate is re-checked on every update. |
+| `onNavigate` | `(path: string) => void`      | `window.location.assign`             | How to navigate on route select. |
+| `position`   | `"bottom-left" \| "bottom-right" \| "top-left" \| "top-right"` | `"bottom-left"` | Corner. |
+| `label`      | `string`                      | `"DEV"`                              | Button text. |
+| `title`      | `string`                      | `"Dev Menu"`                         | Popup heading. |
+| `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. |
+
+`DevRoute`: `{ path: string; label?: string; group?: string }`
+
+`DevCommand`: `{ label: string; run: () => void | Promise<void>; id?: string; group?: string; keepOpen?: boolean }`
+
+### `@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-router`
+
+- `ReactRouterDevDock(props)` — `DevDock` wired to `useNavigate()` + auto-detected routes. Extra prop: `match?: RouteMatcher`.
+- `useDetectedRoutes(match?): DevRoute[]` — the detected routes, optionally scoped (build your own UI).
+- `flattenRoutes(routes, parent?): DevRoute[]` — pure helper that flattens a route tree.
+- `RouteMatcher` — `string | RegExp | ((route: DevRoute) => boolean)`.
+
+## Examples
+
+Runnable demos consuming the library straight from source live in
+[`examples/`](./examples):
+
+```bash
+cd examples/react   && bun install && bun run dev   # React + React Router
+cd examples/svelte  && bun install && bun run dev   # Svelte 5 (use:devdock)
+```
+
+## Development
+
+```bash
+bun install
+bun run test        # vitest (core + react + svelte + react-router)
+bun run build       # tsup → dist (ESM + CJS + d.ts, one entry per adapter)
+bun run typecheck
+```
+
+## License
+
+MIT

package/dist/chunk-NJ3FCNK6.js

@@ -0,0 +1,391 @@
+// src/core/hotkey.ts
+function matchHotkey(spec, e) {
+  const parts = spec.toLowerCase().split("+").map((p) => p.trim()).filter(Boolean);
+  if (parts.length === 0) return false;
+  const key = parts[parts.length - 1];
+  const mods = new Set(parts.slice(0, -1));
+  const isMac = typeof navigator !== "undefined" && /mac/i.test(navigator.platform);
+  const wantMeta = mods.has("meta") || mods.has("cmd") || mods.has("mod") && isMac;
+  const wantCtrl = mods.has("ctrl") || mods.has("control") || mods.has("mod") && !isMac;
+  const wantShift = mods.has("shift");
+  const wantAlt = mods.has("alt") || mods.has("option");
+  if (e.metaKey !== wantMeta) return false;
+  if (e.ctrlKey !== wantCtrl) return false;
+  if (e.shiftKey !== wantShift) return false;
+  if (e.altKey !== wantAlt) return false;
+  return e.key.toLowerCase() === key;
+}
+
+// src/core/dock.ts
+var isDev = () => {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return false;
+  }
+};
+function el(tag, styles, props) {
+  const node = document.createElement(tag);
+  if (styles) Object.assign(node.style, styles);
+  if (props) Object.assign(node, props);
+  return node;
+}
+function cornerStyle(position) {
+  const gap = "16px";
+  switch (position) {
+    case "bottom-right":
+      return { bottom: gap, right: gap };
+    case "top-left":
+      return { top: gap, left: gap };
+    case "top-right":
+      return { top: gap, right: gap };
+    default:
+      return { bottom: gap, left: gap };
+  }
+}
+function panelAnchor(position) {
+  const isTop = position.startsWith("top");
+  const isRight = position.endsWith("right");
+  return {
+    position: "absolute",
+    [isTop ? "top" : "bottom"]: "calc(100% + 8px)",
+    [isRight ? "right" : "left"]: "0"
+  };
+}
+var FONT = "ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif";
+function createDevDock(initial = {}) {
+  if (typeof document === "undefined") {
+    return { update() {
+    }, destroy() {
+    } };
+  }
+  let opts = { ...initial };
+  let open = false;
+  let query = "";
+  let active = 0;
+  let mounted = false;
+  const host = el("div");
+  host.setAttribute("data-devdock", "");
+  const useShadow = (initial.shadow ?? true) && typeof host.attachShadow === "function";
+  const shadowRoot = useShadow ? host.attachShadow({ mode: "open" }) : null;
+  const mountPoint = shadowRoot ?? host;
+  const root = el("div", { fontFamily: FONT });
+  mountPoint.appendChild(root);
+  const panel = el("div", {
+    width: "280px",
+    maxHeight: "min(70vh, 480px)",
+    display: "flex",
+    flexDirection: "column",
+    background: "#16181d",
+    color: "#e7e9ee",
+    border: "1px solid #2a2e37",
+    borderRadius: "12px",
+    boxShadow: "0 12px 40px rgba(0,0,0,0.45)",
+    overflow: "hidden"
+  });
+  panel.setAttribute("role", "dialog");
+  const heading = el("div", {
+    padding: "10px 12px",
+    borderBottom: "1px solid #2a2e37",
+    fontSize: "12px",
+    fontWeight: "600",
+    letterSpacing: "0.4px",
+    textTransform: "uppercase",
+    color: "#8b909c"
+  });
+  const inputWrap = el("div", { padding: "8px" });
+  const input = el("input", {
+    width: "100%",
+    boxSizing: "border-box",
+    padding: "8px 10px",
+    fontSize: "13px",
+    color: "#e7e9ee",
+    background: "#0f1115",
+    border: "1px solid #2a2e37",
+    borderRadius: "8px",
+    outline: "none"
+  });
+  input.placeholder = "Filter\u2026";
+  inputWrap.appendChild(input);
+  const list = el("div", { overflowY: "auto", padding: "0 6px 8px" });
+  panel.append(heading, inputWrap, list);
+  const button = el("button", {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: "6px",
+    padding: "8px 12px",
+    fontSize: "12px",
+    fontWeight: "700",
+    letterSpacing: "0.6px",
+    color: "#fff",
+    background: "#111317",
+    border: "1px solid #2a2e37",
+    borderRadius: "999px",
+    boxShadow: "0 4px 14px rgba(0,0,0,0.35)",
+    cursor: "pointer"
+  });
+  button.type = "button";
+  button.setAttribute("aria-label", "Toggle dev menu");
+  const dot = el("span", {
+    width: "8px",
+    height: "8px",
+    borderRadius: "999px",
+    background: "#22c55e",
+    display: "inline-block"
+  });
+  const buttonLabel = el("span");
+  button.append(dot, buttonLabel);
+  root.appendChild(button);
+  const enabled = () => {
+    const e = opts.enabled;
+    if (typeof e === "function") return e();
+    return e ?? isDev();
+  };
+  const navigate = (path) => {
+    if (opts.onNavigate) opts.onNavigate(path);
+    else if (typeof window !== "undefined") window.location.assign(path);
+  };
+  const buildItems = () => {
+    const out = [];
+    (opts.routes ?? []).forEach((r, i) => {
+      out.push({
+        kind: "route",
+        key: `route:${r.path}:${i}`,
+        label: r.label ?? r.path,
+        group: r.group ?? "Routes",
+        route: r
+      });
+    });
+    (opts.commands ?? []).forEach((c, i) => {
+      out.push({
+        kind: "command",
+        key: `cmd:${c.id ?? c.label}:${i}`,
+        label: c.label,
+        group: c.group ?? "Commands",
+        command: c
+      });
+    });
+    return out;
+  };
+  const getFiltered = () => {
+    const q = query.trim().toLowerCase();
+    const items = buildItems();
+    if (!q) return items;
+    return items.filter(
+      (it) => it.label.toLowerCase().includes(q) || it.kind === "route" && it.route.path.toLowerCase().includes(q)
+    );
+  };
+  const runItem = async (it) => {
+    if (it.kind === "route") {
+      navigate(it.route.path);
+      setOpen(false);
+      return;
+    }
+    try {
+      await it.command.run();
+    } finally {
+      if (!it.command.keepOpen) setOpen(false);
+    }
+  };
+  const renderList = () => {
+    const filtered = getFiltered();
+    active = Math.min(active, Math.max(0, filtered.length - 1));
+    list.replaceChildren();
+    if (filtered.length === 0) {
+      list.appendChild(
+        el(
+          "div",
+          { padding: "12px", fontSize: "13px", color: "#6b7280" },
+          { textContent: "Nothing here." }
+        )
+      );
+      return;
+    }
+    const groups = /* @__PURE__ */ new Map();
+    for (const it of filtered) {
+      const arr = groups.get(it.group) ?? [];
+      arr.push(it);
+      groups.set(it.group, arr);
+    }
+    for (const [groupName, groupItems] of groups) {
+      const section = el("div", { marginTop: "6px" });
+      section.appendChild(
+        el(
+          "div",
+          {
+            padding: "6px 8px 2px",
+            fontSize: "10px",
+            fontWeight: "700",
+            letterSpacing: "0.6px",
+            textTransform: "uppercase",
+            color: "#6b7280"
+          },
+          { textContent: groupName }
+        )
+      );
+      for (const it of groupItems) {
+        const idx = filtered.indexOf(it);
+        const isActive = idx === active;
+        const row = el("button", {
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: "8px",
+          width: "100%",
+          textAlign: "left",
+          padding: "8px 10px",
+          fontSize: "13px",
+          color: "#e7e9ee",
+          background: isActive ? "#2563eb" : "transparent",
+          border: "none",
+          borderRadius: "8px",
+          cursor: "pointer"
+        });
+        row.type = "button";
+        const labelSpan = el(
+          "span",
+          {
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+            whiteSpace: "nowrap"
+          },
+          { textContent: it.label }
+        );
+        row.appendChild(labelSpan);
+        if (it.kind === "route" && it.route.path !== it.label) {
+          row.appendChild(
+            el(
+              "span",
+              {
+                fontSize: "11px",
+                color: isActive ? "#cfe0ff" : "#6b7280",
+                fontFamily: "ui-monospace, SFMono-Regular, monospace",
+                flexShrink: "0"
+              },
+              { textContent: it.route.path }
+            )
+          );
+        }
+        row.addEventListener("mouseenter", () => {
+          active = idx;
+          renderList();
+        });
+        row.addEventListener("click", () => void runItem(it));
+        section.appendChild(row);
+      }
+      list.appendChild(section);
+    }
+  };
+  const renderShell = () => {
+    const position = opts.position ?? "bottom-left";
+    const zIndex = opts.zIndex ?? 2147483e3;
+    Object.assign(root.style, {
+      position: "fixed",
+      zIndex: String(zIndex),
+      top: "",
+      bottom: "",
+      left: "",
+      right: ""
+    });
+    Object.assign(root.style, cornerStyle(position));
+    heading.textContent = opts.title ?? "Dev Menu";
+    panel.setAttribute("aria-label", opts.title ?? "Dev Menu");
+    Object.assign(panel.style, panelAnchor(position));
+    buttonLabel.textContent = opts.label ?? "DEV";
+    button.style.background = open ? "#2563eb" : "#111317";
+    button.setAttribute("aria-expanded", String(open));
+  };
+  function setOpen(next) {
+    if (open === next) return;
+    open = next;
+    if (open) {
+      query = "";
+      input.value = "";
+      active = 0;
+      panel.isConnected || root.insertBefore(panel, button);
+      renderShell();
+      renderList();
+      requestAnimationFrame(() => input.focus());
+    } else if (panel.isConnected) {
+      panel.remove();
+    }
+    renderShell();
+  }
+  input.addEventListener("input", () => {
+    query = input.value;
+    active = 0;
+    renderList();
+  });
+  panel.addEventListener("keydown", (e) => {
+    const filtered = getFiltered();
+    if (e.key === "Escape") {
+      e.preventDefault();
+      setOpen(false);
+    } else if (e.key === "ArrowDown") {
+      e.preventDefault();
+      active = Math.min(active + 1, filtered.length - 1);
+      renderList();
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      active = Math.max(active - 1, 0);
+      renderList();
+    } else if (e.key === "Enter") {
+      e.preventDefault();
+      const it = filtered[active];
+      if (it) void runItem(it);
+    }
+  });
+  button.addEventListener("click", () => setOpen(!open));
+  const onDocMouseDown = (e) => {
+    if (open && !e.composedPath().includes(root)) setOpen(false);
+  };
+  const onKeyDown = (e) => {
+    if (opts.hotkey && matchHotkey(opts.hotkey, e)) {
+      e.preventDefault();
+      setOpen(!open);
+    }
+  };
+  const addListeners = () => {
+    document.addEventListener("mousedown", onDocMouseDown);
+    window.addEventListener("keydown", onKeyDown);
+  };
+  const removeListeners = () => {
+    document.removeEventListener("mousedown", onDocMouseDown);
+    window.removeEventListener("keydown", onKeyDown);
+  };
+  const mount = () => {
+    if (mounted) return;
+    (opts.container ?? document.body).appendChild(host);
+    addListeners();
+    mounted = true;
+  };
+  const unmount = () => {
+    if (!mounted) return;
+    removeListeners();
+    host.remove();
+    mounted = false;
+  };
+  renderShell();
+  if (enabled()) mount();
+  return {
+    update(next) {
+      opts = { ...opts, ...next };
+      if (enabled()) {
+        mount();
+        renderShell();
+        if (open) renderList();
+      } else {
+        setOpen(false);
+        unmount();
+      }
+    },
+    destroy() {
+      setOpen(false);
+      unmount();
+    }
+  };
+}
+
+export { createDevDock, matchHotkey };
+//# sourceMappingURL=chunk-NJ3FCNK6.js.map
+//# sourceMappingURL=chunk-NJ3FCNK6.js.map