elysia-rack 0.2.2 → 0.3.0

package/README.md

@@ -4,6 +4,12 @@
 
 Model-driven CRUD rack for [Elysia](https://elysiajs.com): declare a resource once, get REST + `QUERY` routes, validation, authorization, query engine, OpenAPI metadata, and a React panel — running on [Bun](https://bun.com) or Node.js 20+.
 
+Full usage guide: [docs/USAGE.md](docs/USAGE.md).
+
+## Documentation
+
+End-user documentation covers installation, configuration, daily usage, and troubleshooting: [docs/index.md](docs/index.md).
+
 ## Install
 
 ```bash
@@ -85,7 +91,7 @@ work through plain `GET` navigation without JavaScript).
 
 The panel ships create / edit / delete UI driven by the same API:
 
-- `+ New` opens a create dialog (fields derived from row columns,
+- `New record` opens a create dialog (fields derived from row columns,
   primary key optional). Submit sends `POST /` with an auto-generated
   `Idempotency-Key`. Tables without known columns fall back to a raw
   JSON body field.
@@ -147,7 +153,7 @@ Conventions:
 - String route ids are coerced to numbers for integer columns
   (e.g. `serial`); anything else passes through. Malformed ids resolve
   to `404`, missing rows to `404`.
-- `searchable` fields use SQL `LIKE` (case-sensitivity follows the DB).
+- `searchable` fields use SQL `ILIKE` through the Drizzle adapter, so search requires a database that supports `ILIKE` (for example PostgreSQL). SQLite search fails with a SQL syntax error.
 - `settings.softDelete: true` writes a timestamp to `deletedAt`
   (override with `settings.deletedAtField`) instead of deleting, and
   reads skip soft-deleted rows.
@@ -155,7 +161,7 @@ Conventions:
 
 ## Dashboard
 
-`dashboard()` is now a simple *Coming Soon* placeholder. The real navigation lives in `panel` — each `rack()` panel shows a sidebar with the entire tree.
+`dashboard()` renders a navigation overview of every registered resource, with a sidebar and a resource table. Each `rack()` panel also shows a sidebar with the entire tree.
 
 Recommended setup:
 
@@ -165,7 +171,7 @@ 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(dashboard({ title: "My Panel", path: "/" })) // → Dashboard 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
@@ -227,14 +233,14 @@ rack("/catalog/products", {
     pluralLabel: "Products",  // shown in sidebar
     group: "Catalog",         // sidebar group
     order: 1,                 // smaller = higher
-    icon: "📦",
+    icon: "package",           // Lucide icon name (kebab-case or PascalCase)
     parent: "catalog-root",   // nest under another id
     hidden: false
   }
 });
 ```
 
-**Decide what users can do.** Turn operations on/off. If you disable `create`, the “+ New” button disappears automatically.
+**Decide what users can do.** Turn operations on/off. If you disable `create`, the “New record” button disappears automatically.
 
 ```ts
 rack("/catalog/products", {
@@ -293,9 +299,9 @@ rack("/catalog/products", {
 
 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
+### 2) `dashboard()`: one line, navigation overview
 
-`dashboard()` mounts `GET /` that renders a *Coming Soon* page. The tree you registered with `rack()` is not shown here — it lives in `panel`.
+`dashboard()` mounts `GET /` and renders a sidebar plus a table of every resource registered with `rack()`.
 
 ```ts
 import { dashboard, rack } from "elysia-rack";
@@ -303,7 +309,7 @@ import { reactPlugin } from "elysia-rack/react";
 
 const app = new Elysia()
   .use(reactPlugin())                         // 1) UI engine — pages optional
-  .use(dashboard({ title: "My Shop", path: "/" })) // 2) Coming Soon at /
+  .use(dashboard({ title: "My Shop", path: "/" })) // 2) Dashboard 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
@@ -404,13 +410,13 @@ Fallback is `dist/panel.css`.
 
 Static assets are served under `/__rack/*`:
 
-- `dist/panel.css` — panel stylesheet (prebuilt)
+- `dist/panel.css` — panel stylesheet (built with Tailwind CSS)
 - `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` via `reactPlugin`. No build step required — assets are
-static and included in the published package.
+`/__rack/panel-app.js` via `reactPlugin`. Run `bun run build` to produce
+`dist/` (`build:css` compiles the stylesheet, `build:js` bundles the clients).
 
 ## Panel theme
 
@@ -420,9 +426,10 @@ static and included in the published package.
   chart, selection, focus, overlay, navigation, table, form, sidebar),
   shadcn/Tailwind compatible, mapped via `@theme inline`.
 - `theme/dark.css` — `.dark` overrides.
-- `theme/koran.css` — default newspaper theme (warm paper, serif
-  headlines). Remove its import for the neutral look.
-- `theme/components.css` — newspaper component classes + base styles.
+- `theme/rack.css` — default theme (black, white, dark blue, gold;
+  Poppins for UI, Chocolate Classical Sans for display headings).
+  Remove its import for the neutral look.
+- `theme/components.css` — base styles, dialog reset, reduced motion.
 
 Dark mode flips automatically: stored choice (`localStorage`), else
 `prefers-color-scheme`. The `◐ Theme` button in the masthead toggles it.

package/dist/Dashboard-4wv82gwx.js

@@ -0,0 +1,212 @@
+import {
+  Masthead,
+  RackIcon,
+  Sidebar
+} from "./index-rg87f3v1.js";
+import {
+  getRackTree
+} from "./index-4wxvmd8a.js";
+import {
+  resolveDonateProp
+} from "./index-b8sq8rbd.js";
+import"./index-37x76zdn.js";
+
+// src/react/page/Dashboard.tsx
+import { Fragment } from "react";
+import { jsxDEV, Fragment as Fragment2 } from "react/jsx-dev-runtime";
+function itemLabel(r) {
+  return r.metadata.pluralLabel ?? r.metadata.label ?? r.metadata.id;
+}
+function toSidebarItem(node, activeId) {
+  return {
+    id: node.metadata.id,
+    label: itemLabel(node),
+    icon: node.metadata.icon,
+    href: node.path,
+    active: node.metadata.id === activeId,
+    children: node.children.filter((c) => !c.metadata.hidden).map((c) => toSidebarItem(c, activeId))
+  };
+}
+function buildGroupsFromTree(tree, activeId) {
+  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, activeId));
+  }
+  return [...byGroup.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function countNodes(nodes) {
+  return nodes.reduce((sum, n) => sum + 1 + countNodes(n.children), 0);
+}
+function operationsLabel(node) {
+  const op = node.operations;
+  const write = [op.create, op.update, op.replace, op.delete];
+  if (!write.some(Boolean))
+    return "Read only";
+  if (write.every(Boolean))
+    return "Full";
+  const labels = [];
+  if (op.create)
+    labels.push("Create");
+  if (op.update)
+    labels.push("Update");
+  if (op.replace)
+    labels.push("Replace");
+  if (op.delete)
+    labels.push("Delete");
+  return labels.join(", ");
+}
+function plural(count, word) {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+function ResourceRow({ node, depth = 0 }) {
+  return /* @__PURE__ */ jsxDEV(Fragment2, {
+    children: [
+      /* @__PURE__ */ jsxDEV("tr", {
+        className: "hover:bg-table-row-hover",
+        children: [
+          /* @__PURE__ */ jsxDEV("td", {
+            className: "border-table-border border-t px-3 py-2.5",
+            children: /* @__PURE__ */ jsxDEV("a", {
+              href: node.path,
+              className: "text-link hover:text-link-hover font-medium hover:underline",
+              style: depth > 0 ? { paddingLeft: depth * 16 } : undefined,
+              children: [
+                node.metadata.icon ? /* @__PURE__ */ jsxDEV(RackIcon, {
+                  name: node.metadata.icon,
+                  size: 16,
+                  className: "mr-1.5 inline size-4 align-text-bottom"
+                }, undefined, false, undefined, this) : null,
+                node.metadata.label ?? node.metadata.id
+              ]
+            }, undefined, true, undefined, this)
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("td", {
+            className: "border-table-border text-text-muted border-t px-3 py-2.5 font-mono text-xs",
+            children: node.path
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("td", {
+            className: "border-table-border text-text-muted border-t px-3 py-2.5 text-xs",
+            children: operationsLabel(node)
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      node.children.filter((c) => !c.metadata.hidden).map((child) => /* @__PURE__ */ jsxDEV(ResourceRow, {
+        node: child,
+        depth: depth + 1
+      }, child.metadata.id, false, undefined, this))
+    ]
+  }, undefined, true, undefined, this);
+}
+async function Dashboard(props) {
+  const tree = getRackTree().filter((r) => !r.metadata.hidden);
+  const groups = buildGroupsFromTree(tree, props.resource);
+  const totalResources = countNodes(tree);
+  const totalGroups = groups.length;
+  const donate = resolveDonateProp(props.donate);
+  return /* @__PURE__ */ jsxDEV("div", {
+    className: "text-foreground flex min-h-screen flex-col lg:flex-row",
+    children: [
+      /* @__PURE__ */ jsxDEV(Sidebar, {
+        title: props.name ?? "Panel",
+        groups
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV("main", {
+        className: "min-w-0 flex-1",
+        children: /* @__PURE__ */ jsxDEV("div", {
+          className: "mx-auto w-full max-w-5xl px-4 py-4 sm:px-6",
+          children: [
+            /* @__PURE__ */ jsxDEV(Masthead, {
+              title: props.name ?? "Panel",
+              detail: `${plural(totalResources, "resource")} in ${plural(totalGroups, "group")}`
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV("div", {
+              className: "bg-table border-border overflow-x-auto rounded-lg border",
+              children: /* @__PURE__ */ jsxDEV("table", {
+                className: "w-full border-collapse text-left text-sm",
+                children: [
+                  /* @__PURE__ */ jsxDEV("thead", {
+                    children: /* @__PURE__ */ jsxDEV("tr", {
+                      children: [
+                        /* @__PURE__ */ jsxDEV("th", {
+                          className: "border-border text-text-muted border-b px-3 py-2 text-xs font-medium",
+                          children: "Resource"
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("th", {
+                          className: "border-border text-text-muted border-b px-3 py-2 text-xs font-medium",
+                          children: "Path"
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("th", {
+                          className: "border-border text-text-muted border-b px-3 py-2 text-xs font-medium",
+                          children: "Operations"
+                        }, undefined, false, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this)
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV("tbody", {
+                    children: groups.length === 0 ? /* @__PURE__ */ jsxDEV("tr", {
+                      children: /* @__PURE__ */ jsxDEV("td", {
+                        colSpan: 3,
+                        className: "text-text-muted px-4 py-10 text-center",
+                        children: "No resources registered. Call rack() before rendering this page."
+                      }, undefined, false, undefined, this)
+                    }, undefined, false, undefined, this) : groups.map((group) => {
+                      const nodes = tree.filter((r) => (r.metadata.group ?? "General") === group.name);
+                      return /* @__PURE__ */ jsxDEV(Fragment, {
+                        children: [
+                          /* @__PURE__ */ jsxDEV("tr", {
+                            className: "bg-surface-muted",
+                            children: /* @__PURE__ */ jsxDEV("th", {
+                              colSpan: 3,
+                              className: "border-border text-text-muted border-b px-3 py-1.5 text-left text-xs font-medium",
+                              children: [
+                                group.name,
+                                " ",
+                                /* @__PURE__ */ jsxDEV("span", {
+                                  className: "text-text-subtle font-normal",
+                                  children: plural(countNodes(nodes), "resource")
+                                }, undefined, false, undefined, this)
+                              ]
+                            }, undefined, true, undefined, this)
+                          }, undefined, false, undefined, this),
+                          nodes.map((node) => /* @__PURE__ */ jsxDEV(ResourceRow, {
+                            node
+                          }, node.metadata.id, false, undefined, this))
+                        ]
+                      }, group.name, true, undefined, this);
+                    })
+                  }, undefined, false, undefined, this)
+                ]
+              }, undefined, true, undefined, this)
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV("footer", {
+              className: "border-border text-text-muted mt-6 flex flex-wrap items-center justify-between gap-2 border-t pt-3 text-xs",
+              children: [
+                /* @__PURE__ */ jsxDEV("span", {
+                  children: "elysia-rack"
+                }, undefined, false, undefined, this),
+                donate.enabled ? /* @__PURE__ */ jsxDEV("a", {
+                  href: donate.url,
+                  target: "_blank",
+                  rel: "noopener noreferrer",
+                  className: "hover:text-foreground underline-offset-4 hover:underline",
+                  children: donate.label
+                }, undefined, false, undefined, this) : null
+              ]
+            }, undefined, true, undefined, this)
+          ]
+        }, undefined, true, undefined, this)
+      }, undefined, false, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+export {
+  Dashboard as default
+};

package/dist/Dashboard-jkvfzyk2.js

@@ -0,0 +1,210 @@
+import {
+  Masthead,
+  Sidebar
+} from "./index-0dwhzk3j.js";
+import {
+  getRackTree
+} from "./index-4wxvmd8a.js";
+import {
+  resolveDonateProp
+} from "./index-b8sq8rbd.js";
+import"./index-37x76zdn.js";
+
+// src/react/page/Dashboard.tsx
+import { Fragment } from "react";
+import { jsxDEV, Fragment as Fragment2 } from "react/jsx-dev-runtime";
+function itemLabel(r) {
+  return r.metadata.pluralLabel ?? r.metadata.label ?? r.metadata.id;
+}
+function toSidebarItem(node, activeId) {
+  return {
+    id: node.metadata.id,
+    label: itemLabel(node),
+    icon: node.metadata.icon,
+    href: node.path,
+    active: node.metadata.id === activeId,
+    children: node.children.filter((c) => !c.metadata.hidden).map((c) => toSidebarItem(c, activeId))
+  };
+}
+function buildGroupsFromTree(tree, activeId) {
+  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, activeId));
+  }
+  return [...byGroup.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function countNodes(nodes) {
+  return nodes.reduce((sum, n) => sum + 1 + countNodes(n.children), 0);
+}
+function operationsLabel(node) {
+  const op = node.operations;
+  const write = [op.create, op.update, op.replace, op.delete];
+  if (!write.some(Boolean))
+    return "Read only";
+  if (write.every(Boolean))
+    return "Full";
+  const labels = [];
+  if (op.create)
+    labels.push("Create");
+  if (op.update)
+    labels.push("Update");
+  if (op.replace)
+    labels.push("Replace");
+  if (op.delete)
+    labels.push("Delete");
+  return labels.join(", ");
+}
+function plural(count, word) {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+function ResourceRow({ node, depth = 0 }) {
+  return /* @__PURE__ */ jsxDEV(Fragment2, {
+    children: [
+      /* @__PURE__ */ jsxDEV("tr", {
+        className: "hover:bg-table-row-hover",
+        children: [
+          /* @__PURE__ */ jsxDEV("td", {
+            className: "border-table-border border-t px-3 py-2.5",
+            children: /* @__PURE__ */ jsxDEV("a", {
+              href: node.path,
+              className: "text-link hover:text-link-hover font-medium hover:underline",
+              style: depth > 0 ? { paddingLeft: depth * 16 } : undefined,
+              children: [
+                node.metadata.icon ? /* @__PURE__ */ jsxDEV("span", {
+                  "aria-hidden": "true",
+                  className: "mr-1.5",
+                  children: node.metadata.icon
+                }, undefined, false, undefined, this) : null,
+                node.metadata.label ?? node.metadata.id
+              ]
+            }, undefined, true, undefined, this)
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("td", {
+            className: "border-table-border text-text-muted border-t px-3 py-2.5 font-mono text-xs",
+            children: node.path
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("td", {
+            className: "border-table-border text-text-muted border-t px-3 py-2.5 text-xs",
+            children: operationsLabel(node)
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      node.children.filter((c) => !c.metadata.hidden).map((child) => /* @__PURE__ */ jsxDEV(ResourceRow, {
+        node: child,
+        depth: depth + 1
+      }, child.metadata.id, false, undefined, this))
+    ]
+  }, undefined, true, undefined, this);
+}
+async function Dashboard(props) {
+  const tree = getRackTree().filter((r) => !r.metadata.hidden);
+  const groups = buildGroupsFromTree(tree, props.resource);
+  const totalResources = countNodes(tree);
+  const totalGroups = groups.length;
+  const donate = resolveDonateProp(props.donate);
+  return /* @__PURE__ */ jsxDEV("div", {
+    className: "text-foreground flex min-h-screen flex-col lg:flex-row",
+    children: [
+      /* @__PURE__ */ jsxDEV(Sidebar, {
+        title: props.name ?? "Panel",
+        groups
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV("main", {
+        className: "min-w-0 flex-1",
+        children: /* @__PURE__ */ jsxDEV("div", {
+          className: "mx-auto w-full max-w-5xl px-4 py-4 sm:px-6",
+          children: [
+            /* @__PURE__ */ jsxDEV(Masthead, {
+              title: props.name ?? "Panel",
+              detail: `${plural(totalResources, "resource")} in ${plural(totalGroups, "group")}`
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV("div", {
+              className: "bg-table border-border overflow-x-auto rounded-lg border",
+              children: /* @__PURE__ */ jsxDEV("table", {
+                className: "w-full border-collapse text-left text-sm",
+                children: [
+                  /* @__PURE__ */ jsxDEV("thead", {
+                    children: /* @__PURE__ */ jsxDEV("tr", {
+                      children: [
+                        /* @__PURE__ */ jsxDEV("th", {
+                          className: "border-border text-text-muted border-b px-3 py-2 text-xs font-medium",
+                          children: "Resource"
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("th", {
+                          className: "border-border text-text-muted border-b px-3 py-2 text-xs font-medium",
+                          children: "Path"
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("th", {
+                          className: "border-border text-text-muted border-b px-3 py-2 text-xs font-medium",
+                          children: "Operations"
+                        }, undefined, false, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this)
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV("tbody", {
+                    children: groups.length === 0 ? /* @__PURE__ */ jsxDEV("tr", {
+                      children: /* @__PURE__ */ jsxDEV("td", {
+                        colSpan: 3,
+                        className: "text-text-muted px-4 py-10 text-center",
+                        children: "No resources registered. Call rack() before rendering this page."
+                      }, undefined, false, undefined, this)
+                    }, undefined, false, undefined, this) : groups.map((group) => {
+                      const nodes = tree.filter((r) => (r.metadata.group ?? "General") === group.name);
+                      return /* @__PURE__ */ jsxDEV(Fragment, {
+                        children: [
+                          /* @__PURE__ */ jsxDEV("tr", {
+                            className: "bg-surface-muted",
+                            children: /* @__PURE__ */ jsxDEV("th", {
+                              colSpan: 3,
+                              className: "border-border text-text-muted border-b px-3 py-1.5 text-left text-xs font-medium",
+                              children: [
+                                group.name,
+                                /* @__PURE__ */ jsxDEV("span", {
+                                  className: "text-text-subtle ml-2 font-normal",
+                                  children: plural(countNodes(nodes), "resource")
+                                }, undefined, false, undefined, this)
+                              ]
+                            }, undefined, true, undefined, this)
+                          }, undefined, false, undefined, this),
+                          nodes.map((node) => /* @__PURE__ */ jsxDEV(ResourceRow, {
+                            node
+                          }, node.metadata.id, false, undefined, this))
+                        ]
+                      }, group.name, true, undefined, this);
+                    })
+                  }, undefined, false, undefined, this)
+                ]
+              }, undefined, true, undefined, this)
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV("footer", {
+              className: "border-border text-text-muted mt-6 flex flex-wrap items-center justify-between gap-2 border-t pt-3 text-xs",
+              children: [
+                /* @__PURE__ */ jsxDEV("span", {
+                  children: "elysia-rack"
+                }, undefined, false, undefined, this),
+                donate.enabled ? /* @__PURE__ */ jsxDEV("a", {
+                  href: donate.url,
+                  target: "_blank",
+                  rel: "noopener noreferrer",
+                  className: "hover:text-foreground underline-offset-4 hover:underline",
+                  children: donate.label
+                }, undefined, false, undefined, this) : null
+              ]
+            }, undefined, true, undefined, this)
+          ]
+        }, undefined, true, undefined, this)
+      }, undefined, false, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+export {
+  Dashboard as default
+};