elysia-rack 0.1.1 → 0.2.0

package/README.md

@@ -151,55 +151,261 @@ Conventions:
   reads skip soft-deleted rows.
 - `settings.returning: false` omits `data` from mutation responses.
 
-## Dashboard (sidebar, breadcrumb, iframe)
+## Dashboard
 
-Every `rack()` call registers its path, metadata and operations in a
-registry (`listRacks()` / `clearRacks()` from `elysia-rack`). The default
-`/dashboard` page builds a sidebar (grouped by `metadata.group`, ordered
-by `metadata.order`, skipping `hidden`), a breadcrumb
-(Dashboard / Group / Label), and shows the selected resource's `GET`
-panel inside an `<iframe>`:
+`dashboard()` is now a simple *Coming Soon* placeholder. The real navigation lives in `panel` — each `rack()` panel shows a sidebar with the entire tree.
+
+Recommended setup:
+
+```ts
+import { dashboard, rack } from "elysia-rack";
+import { reactPlugin } from "elysia-rack/react";
+
+const app = new Elysia()
+  .use(reactPlugin()) // pages are optional — defaults to dashboard + panel
+  .use(dashboard({ title: "My Panel", path: "/" })) // → Coming Soon at /
+  .use(rack("/catalog/products", { model, metadata: { id: "products", group: "Catalog", order: 1 } }))
+  .use(rack("/catalog/variants", { model, metadata: { id: "variants", group: "Catalog", order: 2, parent: "products" } }));
+// → Panel at /catalog/products now shows sidebar with Catalog > Products > Variants
+```
+
+### Tree metadata
+
+`metadata.parent` builds a hierarchy. Children are rendered nested under their parent in `panel`’s sidebar and kept ordered by `order` then label.
+
+```ts
+rack("/catalog/products", { metadata: { id: "products", group: "Catalog", order: 1 } });
+rack("/catalog/variants", { metadata: { id: "variants", parent: "products", group: "Catalog", order: 2 } });
+```
+
+Helpers: `listRacks()`, `getRack(id)`, `getRackTree()`, `flatRackTree()`, `buildRackTree(racks)`, `clearRacks()` from `elysia-rack`.
+
+You can still render the dashboard manually:
 
 ```ts
-import { page, pages, reactPlugin } from "elysia-rack/react";
+import { page, reactPlugin } from "elysia-rack/react";
 
 const app = new Elysia()
-  .use(reactPlugin({ pages }))
+  .use(reactPlugin())
   .use(rack("/catalog/products", { model, metadata: { ... } }))
-  .get("/", ({ query }) =>
-    page("/dashboard", {
-      name: "My Shop",
-      resource: typeof query.resource === "string" ? query.resource : undefined,
-    }),
-  );
+  .get("/", () => page("/dashboard", { name: "My Shop" }));
+```
+
+`panel` now handles the sidebar + breadcrumb. Each panel loads the full tree via `getRackTree()`, highlights the active resource (`props.resource`), and links via `href: node.path`. No iframe needed.
+
+## Tutorial — make it yours
+
+This guide walks you through `rack()`, `dashboard()` and `react()` the way you would build a real app. Copy, run, tweak.
+
+### 1) `rack()` — describe a resource, get an API + panel
+
+Start with the only required thing: which table/model to use.
+
+```ts
+import { rack } from "elysia-rack";
+
+rack("/catalog/products", {
+  model: { drizzle: { db, table: products } } // or { prisma: { client: prisma, model: prisma.product } }
+});
+```
+
+You already get `GET /`, `QUERY /data`, `POST /`, `PUT/PATCH/DELETE /:id` and a panel. Now make it yours step by step.
+
+**Give it a name and a place in the menu.** `metadata` is what the dashboard reads from memory.
+
+```ts
+rack("/catalog/products", {
+  model: { drizzle: { db, table: products } },
+  metadata: {
+    id: "products",           // unique id, defaults to path
+    label: "Product",         // singular
+    pluralLabel: "Products",  // shown in sidebar
+    group: "Catalog",         // sidebar group
+    order: 1,                 // smaller = higher
+    icon: "📦",
+    parent: "catalog-root",   // nest under another id
+    hidden: false
+  }
+});
 ```
 
-Sidebar links navigate with `?resource=<id>` (full reload, no JavaScript
-needed). Without a selection the first registered resource is shown.
+**Decide what users can do.** Turn operations on/off. If you disable `create`, the “+ New” button disappears automatically.
+
+```ts
+rack("/catalog/products", {
+  model,
+  operations: { list: true, detail: true, create: true, replace: true, update: true, delete: false }
+});
+```
+
+**Shape the list experience.** Which fields can be searched, filtered, sorted? What’s the default?
+
+```ts
+rack("/catalog/products", {
+  model,
+  query: {
+    searchable: ["name", "sku"],
+    filterable: ["status"],
+    sortable: ["name", "price", "createdAt"],
+    defaultSort: { field: "createdAt", direction: "desc" },
+    pagination: { default: 20, max: 100 }
+  }
+});
+```
 
-React panel rendering via the `./react` subpath:
+**Add safety.** Validation and authorization are per-operation. A string like `"products.delete"` checks the `x-permissions` header; a function gives you the full `Request`.
 
 ```ts
-import { page, pages, reactPlugin } from "elysia-rack/react";
+import { t } from "elysia";
+
+rack("/catalog/products", {
+  model,
+  validation: {
+    create: t.Object({ name: t.String({ minLength: 3 }) }),
+    update: t.Partial(t.Object({ name: t.String() })),
+    params: t.Object({ id: t.String() }),
+    query: t.Object({ search: t.Optional(t.String()) })
+  },
+  authorization: {
+    list: true,
+    delete: async ({ request }) => request.headers.get("x-api-key") === "secret"
+    // or: delete: "products.delete"
+  }
+});
+```
+
+**Tweak the small things** when you need them:
+
+```ts
+rack("/catalog/products", {
+  model,
+  page: { enabled: true, path: "/panel" }, // change or disable GET / panel
+  settings: { primaryKey: "slug", softDelete: true, deletedAtField: "deletedAt", returning: true },
+  openapi: { tags: ["Catalog"], description: "Products", operations: { list: { summary: "List products" } } },
+  idempotency: { required: true, header: "Idempotency-Key", ttl: 3600, store: myRedisStore }
+});
+```
+
+That’s the whole `rack()` surface. Start with `model`, then add `metadata` → `query` → `validation/authorization` as your app grows.
+
+### 2) `dashboard()` — one line, now Coming Soon
+
+`dashboard()` mounts `GET /` that renders a *Coming Soon* page. The tree you registered with `rack()` is not shown here — it lives in `panel`.
+
+```ts
+import { dashboard, rack } from "elysia-rack";
+import { reactPlugin } from "elysia-rack/react";
 
 const app = new Elysia()
-  .use(reactPlugin({ pages }))
-  .get("/", () => page("/dashboard", { name: "Ada" }));
+  .use(reactPlugin())                         // 1) UI engine — pages optional
+  .use(dashboard({ title: "My Shop", path: "/" })) // 2) Coming Soon at /
+  .use(rack("/catalog/products", { model, metadata: { id: "products", group: "Catalog", order: 1 } }))
+  .use(rack("/catalog/variants", { model, metadata: { id: "variants", parent: "products", group: "Catalog", order: 2 } }));
+// visit /catalog/products → panel shows sidebar with Catalog > Products > Variants
+```
+
+Options — all optional:
+
+- `path` (default `"/"`) — where the dashboard lives
+- `title` (default `"Panel"`) — header in the sidebar
+- `pagePath` (default `"/dashboard"`) — which React page to render
+
+Need it without the helper? The helper is just sugar for:
+
+```ts
+import { page } from "elysia-rack/react";
+.get("/", ({ query }) => page("/dashboard", { name: "My Shop", resource: query.resource as string }))
 ```
 
-## Panel assets (Vite)
+Helpers to inspect the tree yourself: `listRacks()`, `getRack(id)`, `getRackTree()`, `flatRackTree()`, `buildRackTree(racks)`, `clearRacks()`.
+
+### 3) `react()` — pages and look
+
+`reactPlugin` is the bridge between Elysia and React. `pages` is now optional and mergeable — defaults already include `"/dashboard"` and `"/panel"`, and any custom pages you pass are merged in. You can pass a single registry or an array.
+
+```ts
+import { pages, reactPlugin, page } from "elysia-rack/react";
+
+// Option A: just use defaults
+new Elysia().use(reactPlugin());
+
+// Option B: extend defaults with your own page
+const myPages = { "/hello": () => import("./Hello") };
+new Elysia().use(reactPlugin({ pages: myPages })); // merged with defaults
+
+// Option C: merge multiple registries — array will be merged
+const extra = { "/admin": () => import("./Admin") };
+new Elysia().use(reactPlugin({ pages: [pages, myPages, extra] }));
+
+// With a style override
+new Elysia().use(reactPlugin({
+  pages: myPages, // or [pages, myPages]
+  css: "./my-panel.css", // file path
+  // css: { path: "./my-panel.css" },
+  // css: { content: ":root{--color-primary:red}" },
+  // panelCss: "body{...}" // alias
+})).get("/hello", () => page("/hello", { name: "Ada" }));
+```
+
+What each option does:
+
+- `pages` *(optional, `PageRegistry | PageRegistry[]`)* — registry of lazy page components. If omitted, defaults are used. If you pass one or an array, they are merged with defaults so `"/dashboard"` + `"/panel"` stay available. Later entries win on key collision.
+- `css` / `panelCss` — replace `dist/panel.css` served at `/__rack/panel.css`. If the string points to an existing file it’s used, otherwise it’s treated as raw CSS. Useful for quick theming without forking.
+
+Under the hood `reactPlugin` also serves `/__rack/panel-theme.js` and `/__rack/panel-app.js` and turns any `page()` return value into streamed HTML using `src/react/app.html` (`{{title}}` + `<!--app-->`).
+
+## HTML template
+
+SSR uses `src/react/app.html` as the shell. It is read at runtime, cached,
+and streamed with the React output.
+
+```html
+<!doctype html>
+<html><head>
+  <title>{{title}}</title>
+  <link rel="stylesheet" href="/__rack/panel.css" />
+  <!--app-head-->
+</head><body>
+  <!--app-->
+</body></html>
+```
+
+- `{{title}}` is replaced (escaped) per page.
+- `<!--app-->` (also `{{body}}`, `<!--app-html-->`) marks where the React stream is injected.
+- Fallback shell is used if the file is missing. `dist/app.html` is a static copy of `src/react/app.html` included in the package.
+
+Override the template by editing `src/react/app.html` (and `dist/app.html` for the published package).
+
+## Panel CSS override
+
+Override `panel.css` at `react()` config without forking:
+
+```ts
+import { reactPlugin } from "elysia-rack/react";
+
+// file path (resolved from cwd/dist), raw string, or object — pages optional
+reactPlugin({ css: "./my-panel.css" });
+reactPlugin({ css: { path: "./my-panel.css" } });
+reactPlugin({ css: { content: ":root{--color-primary:red}" } });
+reactPlugin({ panelCss: "body{...}" }); // alias
+// with custom pages: reactPlugin({ pages: myPages, css: "./my.css" })
+// or array: reactPlugin({ pages: [pages, myPages], css: "./my.css" })
+```
+
+If a file path exists it is served; otherwise a raw CSS string is served.
+Fallback is `dist/panel.css`.
+
+## Panel assets
 
-CSS, Tailwind and browser JavaScript go through Vite (`vite.config.ts`,
-`bun run build:assets`):
+Static assets are served under `/__rack/*`:
 
-- `src/react/page/panel.css` — stylesheet entry (Tailwind v4) → `dist/panel.css`
-- `src/react/page/client/theme.ts` — dark/light toggle → `dist/panel-theme.js`
-- `src/react/page/client/panel.ts` — live query + actions → `dist/panel-app.js`
-  (imports shared `components/href.ts` and `components/panelForm.ts`)
+- `dist/panel.css` — panel stylesheet (prebuilt)
+- `dist/panel-theme.js` — dark/light toggle
+- `dist/panel-app.js` — live query + actions (imports `components/href.ts`, `components/panelForm.ts`)
 
 Pages reference `/__rack/panel.css`, `/__rack/panel-theme.js` and
-`/__rack/panel-app.js`, served by `reactPlugin` from `dist/` (run the
-build before `dev`; CI and `prepublishOnly` already chain it).
+`/__rack/panel-app.js` via `reactPlugin`. No build step required — assets are
+static and included in the published package.
 
 ## Panel theme
 
@@ -224,7 +430,7 @@ touching React code.
 1. One-time setup: npmjs.com → package → Settings → Trusted Publisher → GitHub Actions (`notoofly/elysia-rack`, workflow `publish.yml`).
 2. Bump `version` in `package.json`.
 3. Create a GitHub Release with tag `v<version>` (e.g. `v0.1.0`).
-4. The `publish` workflow runs automatically: install, typecheck, asset build, test, build, tag-vs-version check, `npm publish --provenance`.
+4. The `publish` workflow runs automatically: install, typecheck, test, build, tag-vs-version check, `npm publish --provenance`.
 
 ## Scripts
 

package/dist/Dashboard-2j561p7c.js

@@ -0,0 +1,225 @@
+import {
+  buildRackTree,
+  flatRackTree,
+  getRackTree
+} from "./index-4wxvmd8a.js";
+import"./index-37x76zdn.js";
+
+// src/react/page/components/Breadcrumb.tsx
+import { jsxDEV } from "react/jsx-dev-runtime";
+function Breadcrumb({ trail }) {
+  return /* @__PURE__ */ jsxDEV("nav", {
+    "aria-label": "Breadcrumb",
+    className: "pb-3 text-sm",
+    children: /* @__PURE__ */ jsxDEV("ol", {
+      className: "flex flex-wrap items-center gap-1.5",
+      children: trail.map((item, i) => {
+        const last = i === trail.length - 1;
+        return /* @__PURE__ */ jsxDEV("li", {
+          className: "flex items-center gap-1.5",
+          children: [
+            i > 0 ? /* @__PURE__ */ jsxDEV("span", {
+              "aria-hidden": "true",
+              className: "text-text-muted",
+              children: "/"
+            }, undefined, false, undefined, this) : null,
+            item.href && !last ? /* @__PURE__ */ jsxDEV("a", {
+              href: item.href,
+              className: "text-text-muted hover:text-foreground",
+              children: item.label
+            }, undefined, false, undefined, this) : /* @__PURE__ */ jsxDEV("span", {
+              "aria-current": last ? "page" : undefined,
+              className: last ? "text-foreground font-semibold" : "text-text-muted",
+              children: item.label
+            }, undefined, false, undefined, this)
+          ]
+        }, `${item.label}-${i}`, true, undefined, this);
+      })
+    }, undefined, false, undefined, this)
+  }, undefined, false, undefined, this);
+}
+
+// src/react/page/components/Sidebar.tsx
+import { jsxDEV as jsxDEV2 } from "react/jsx-dev-runtime";
+function SidebarItemView({ item, depth = 0 }) {
+  const hasChildren = item.children && item.children.length > 0;
+  return /* @__PURE__ */ jsxDEV2("li", {
+    children: [
+      /* @__PURE__ */ jsxDEV2("a", {
+        href: item.href,
+        "aria-current": item.active ? "page" : undefined,
+        className: item.active ? "bg-sidebar-primary text-sidebar-primary-foreground flex items-center gap-2 rounded-md px-2 py-1.5 text-sm font-semibold" : "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground flex items-center gap-2 rounded-md px-2 py-1.5 text-sm",
+        style: depth > 0 ? { paddingLeft: `${8 + depth * 12}px` } : undefined,
+        children: [
+          item.icon ? /* @__PURE__ */ jsxDEV2("span", {
+            "aria-hidden": "true",
+            children: item.icon
+          }, undefined, false, undefined, this) : null,
+          /* @__PURE__ */ jsxDEV2("span", {
+            children: item.label
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      hasChildren ? /* @__PURE__ */ jsxDEV2("ul", {
+        className: "border-sidebar-border mt-0.5 ml-2 flex flex-col gap-0.5 border-l py-1 pl-2",
+        children: item.children.map((child) => /* @__PURE__ */ jsxDEV2(SidebarItemView, {
+          item: child,
+          depth: depth + 1
+        }, child.id, false, undefined, this))
+      }, undefined, false, undefined, this) : null
+    ]
+  }, undefined, true, undefined, this);
+}
+function hasActive(items) {
+  for (const it of items) {
+    if (it.active)
+      return true;
+    if (it.children && hasActive(it.children))
+      return true;
+  }
+  return false;
+}
+function Sidebar({ title, groups }) {
+  return /* @__PURE__ */ jsxDEV2("aside", {
+    className: "bg-sidebar text-sidebar-foreground border-sidebar-border min-h-0 w-64 shrink-0 overflow-y-auto rounded-lg border",
+    children: [
+      /* @__PURE__ */ jsxDEV2("div", {
+        className: "border-sidebar-border border-b px-4 py-3",
+        children: /* @__PURE__ */ jsxDEV2("p", {
+          className: "font-koran text-xl font-black tracking-tight",
+          children: title
+        }, undefined, false, undefined, this)
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV2("nav", {
+        className: "flex flex-col gap-4 p-3",
+        children: groups.map((group) => /* @__PURE__ */ jsxDEV2("section", {
+          children: /* @__PURE__ */ jsxDEV2("details", {
+            className: "group",
+            open: hasActive(group.items) || undefined,
+            children: [
+              /* @__PURE__ */ jsxDEV2("summary", {
+                className: "font-koran border-sidebar-border flex cursor-pointer list-none items-center justify-between border-b px-2 pb-1 text-base font-bold tracking-tight [&::-webkit-details-marker]:hidden",
+                children: [
+                  /* @__PURE__ */ jsxDEV2("span", {
+                    children: group.name
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV2("span", {
+                    "aria-hidden": "true",
+                    className: "text-text-muted text-xs transition group-open:rotate-180",
+                    children: "▾"
+                  }, undefined, false, undefined, this)
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV2("ul", {
+                className: "border-sidebar-border mt-1 ml-2 flex flex-col gap-0.5 border-l py-1 pl-2",
+                children: group.items.map((item) => /* @__PURE__ */ jsxDEV2(SidebarItemView, {
+                  item
+                }, item.id, false, undefined, this))
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        }, group.name, false, undefined, this))
+      }, undefined, false, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+
+// src/react/page/Dashboard.tsx
+import { jsxDEV as jsxDEV3 } from "react/jsx-dev-runtime";
+function itemLabel(r) {
+  return r.metadata.pluralLabel ?? r.metadata.label ?? r.metadata.id;
+}
+function buildGroups(racks, selectedId) {
+  const byGroup = new Map;
+  for (const r of racks) {
+    if (r.metadata.hidden)
+      continue;
+    const name = r.metadata.group ?? "General";
+    let group = byGroup.get(name);
+    if (!group) {
+      group = { name, items: [] };
+      byGroup.set(name, group);
+    }
+    group.items.push({
+      id: r.metadata.id,
+      label: itemLabel(r),
+      icon: r.metadata.icon,
+      href: `?resource=${encodeURIComponent(r.metadata.id)}`,
+      active: r.metadata.id === selectedId
+    });
+  }
+  const groups = [...byGroup.values()].sort((a, b) => a.name.localeCompare(b.name));
+  for (const group of groups) {
+    const orderOf = (id) => racks.find((r) => r.metadata.id === id)?.metadata.order ?? 0;
+    group.items.sort((a, b) => orderOf(a.id) - orderOf(b.id) || a.label.localeCompare(b.label));
+  }
+  return groups;
+}
+function toSidebarItem(node, selectedId) {
+  return {
+    id: node.metadata.id,
+    label: itemLabel(node),
+    icon: node.metadata.icon,
+    href: `?resource=${encodeURIComponent(node.metadata.id)}`,
+    active: node.metadata.id === selectedId,
+    children: node.children.filter((c) => !c.metadata.hidden).map((c) => toSidebarItem(c, selectedId))
+  };
+}
+function buildGroupsFromTree(tree, selectedId) {
+  const byGroup = new Map;
+  for (const root of tree) {
+    if (root.metadata.hidden)
+      continue;
+    const name = root.metadata.group ?? "General";
+    let group = byGroup.get(name);
+    if (!group) {
+      group = { name, items: [] };
+      byGroup.set(name, group);
+    }
+    group.items.push(toSidebarItem(root, selectedId));
+  }
+  return [...byGroup.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+async function Dashboard(props) {
+  const tree = props.racks !== undefined ? buildRackTree(props.racks.filter((r) => !r.metadata.hidden)) : getRackTree().filter((r) => !r.metadata.hidden);
+  const flat = props.racks !== undefined ? props.racks.filter((r) => !r.metadata.hidden) : flatRackTree(tree).filter((r) => !r.metadata.hidden);
+  const selected = flat.find((r) => r.metadata.id === props.resource) ?? flat[0];
+  const groups = tree.length ? buildGroupsFromTree(tree, selected?.metadata.id) : buildGroups(flat, selected?.metadata.id);
+  const trail = [
+    { label: "Dashboard", href: "?" },
+    ...selected?.metadata.group ? [{ label: selected.metadata.group }] : [],
+    ...selected ? [{ label: itemLabel(selected) }] : []
+  ];
+  return /* @__PURE__ */ jsxDEV3("div", {
+    className: "koran-paper font-koran-body text-foreground flex flex-col min-h-screen",
+    children: /* @__PURE__ */ jsxDEV3("div", {
+      className: "flex min-h-0 flex-1 gap-6 p-4 sm:p-6 h-full",
+      children: [
+        /* @__PURE__ */ jsxDEV3(Sidebar, {
+          title: props.name ?? "Panel",
+          groups
+        }, undefined, false, undefined, this),
+        /* @__PURE__ */ jsxDEV3("main", {
+          className: "flex min-w-0 flex-1 flex-col",
+          children: [
+            /* @__PURE__ */ jsxDEV3(Breadcrumb, {
+              trail
+            }, undefined, false, undefined, this),
+            selected ? /* @__PURE__ */ jsxDEV3("iframe", {
+              src: selected.path,
+              title: itemLabel(selected),
+              sandbox: "allow-scripts allow-same-origin allow-forms",
+              className: "bg-card min-h-0 w-full flex-1 rounded-lg"
+            }, undefined, false, undefined, this) : /* @__PURE__ */ jsxDEV3("p", {
+              className: "text-text-muted border-border rounded-lg border px-4 py-10 text-center",
+              children: "No resources registered. Mount a resource with rack() first."
+            }, undefined, false, undefined, this)
+          ]
+        }, undefined, true, undefined, this)
+      ]
+    }, undefined, true, undefined, this)
+  }, undefined, false, undefined, this);
+}
+export {
+  Dashboard as default
+};