elysia-rack 0.1.2 → 0.2.2

package/README.md

@@ -1,5 +1,7 @@
 # elysia-rack
 
+[![Ko-fi Donate](https://img.shields.io/badge/Ko--fi-Donate-ff5e5b?logo=ko-fi&logoColor=white)](https://ko-fi.com/notoofly_manu) [![npm](https://img.shields.io/npm/v/elysia-rack)](https://www.npmjs.com/package/elysia-rack)
+
 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+.
 
 ## Install
@@ -153,25 +155,25 @@ Conventions:
 
 ## Dashboard
 
-Recommended setup uses `react()`, `dashboard()`, and `rack()`. Each `rack()`
-stores its metadata tree in memory (registry) and `dashboard()` loads it at
-render time via `getRackTree()`.
+`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 { pages, reactPlugin } from "elysia-rack/react";
+import { reactPlugin } from "elysia-rack/react";
 
 const app = new Elysia()
-  .use(reactPlugin({ pages }))
-  .use(dashboard({ title: "My Panel", path: "/" }))
+  .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 the sidebar and kept ordered by `order` then label.
+`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 } });
@@ -180,25 +182,182 @@ rack("/catalog/variants", { metadata: { id: "variants", parent: "products", grou
 
 Helpers: `listRacks()`, `getRack(id)`, `getRackTree()`, `flatRackTree()`, `buildRackTree(racks)`, `clearRacks()` from `elysia-rack`.
 
-The dashboard page itself can also be used manually:
+### Donate — disable on website
+Donate link (Ko-fi) tampil di Dashboard & Panel footer. Disable via `dashboard({ donate: false })` atau global `reactPlugin({ donate: false })` (default `true`).
+
+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
+  }
+});
+```
+
+**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 }
+  }
+});
 ```
 
-The sidebar groups by `metadata.group`, sorts by `order`, skips `hidden`,
-and shows the selected resource's panel inside an `<iframe>`. Links use
-`?resource=<id>` (no JavaScript required).
+**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 { 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())                         // 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 }))
+```
+
+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
 
@@ -227,13 +386,15 @@ Override the template by editing `src/react/app.html` (and `dist/app.html` for t
 Override `panel.css` at `react()` config without forking:
 
 ```ts
-import { pages, reactPlugin } from "elysia-rack/react";
-
-// file path (resolved from cwd/dist), raw string, or object
-reactPlugin({ pages, css: "./my-panel.css" });
-reactPlugin({ pages, css: { path: "./my-panel.css" } });
-reactPlugin({ pages, css: { content: ":root{--color-primary:red}" } });
-reactPlugin({ pages, panelCss: "body{...}" }); // alias
+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.
@@ -286,6 +447,16 @@ bun run typecheck  # tsc --noEmit
 bun run build      # dist/ (js via bun build + .d.ts via tsc)
 ```
 
+## Donate
+
+Support pengembangan elysia-rack — traktir kopi via Ko-fi:
+
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-Donate-ff5e5b?logo=ko-fi&logoColor=white)](https://ko-fi.com/notoofly_manu)
+
+> https://ko-fi.com/notoofly_manu
+
+Terima kasih sudah mendukung open-source!
+
 ## License
 
 MIT © notoofly

package/dist/Dashboard-0da8dvbv.js

@@ -0,0 +1,225 @@
+import {
+  Breadcrumb,
+  Masthead,
+  Sidebar
+} from "./index-xsfqad54.js";
+import {
+  getRackTree
+} from "./index-4wxvmd8a.js";
+import"./index-37x76zdn.js";
+
+// src/react/page/Dashboard.tsx
+import { jsxDEV } 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));
+}
+async function Dashboard(props) {
+  const tree = getRackTree().filter((r) => !r.metadata.hidden);
+  const groups = buildGroupsFromTree(tree, props.resource);
+  const totalResources = tree.length + tree.reduce((a, n) => a + n.children.length, 0);
+  const totalGroups = groups.length;
+  return /* @__PURE__ */ jsxDEV("div", {
+    className: "koran-paper font-koran-body text-foreground flex min-h-screen flex-col",
+    children: /* @__PURE__ */ jsxDEV("div", {
+      className: "flex flex-1 gap-6 p-4 sm:p-6",
+      children: [
+        /* @__PURE__ */ jsxDEV(Sidebar, {
+          title: props.name ?? "Panel",
+          groups
+        }, undefined, false, undefined, this),
+        /* @__PURE__ */ jsxDEV("main", {
+          className: "flex min-w-0 flex-1 flex-col",
+          children: [
+            /* @__PURE__ */ jsxDEV(Breadcrumb, {
+              trail: [{ label: "Dashboard" }]
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV("div", {
+              className: "mx-auto w-full max-w-5xl px-4 pb-10 sm:px-6",
+              children: [
+                /* @__PURE__ */ jsxDEV(Masthead, {
+                  title: props.name ?? "ERP Demo",
+                  group: "Dashboard",
+                  resource: "dashboard",
+                  total: totalResources
+                }, undefined, false, undefined, this),
+                /* @__PURE__ */ jsxDEV("div", {
+                  className: "grid grid-cols-2 gap-3 pb-6 lg:grid-cols-4",
+                  children: [
+                    /* @__PURE__ */ jsxDEV("div", {
+                      className: "bg-card border-border rounded-lg border px-4 py-3",
+                      children: [
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "text-text-muted text-xs font-semibold tracking-widest uppercase",
+                          children: "Resources"
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "font-koran text-2xl font-black",
+                          children: totalResources
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "text-text-muted text-xs",
+                          children: [
+                            totalGroups,
+                            " groups"
+                          ]
+                        }, undefined, true, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this),
+                    /* @__PURE__ */ jsxDEV("div", {
+                      className: "bg-card border-border rounded-lg border px-4 py-3",
+                      children: [
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "text-text-muted text-xs font-semibold tracking-widest uppercase",
+                          children: "Modules"
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "font-koran text-2xl font-black",
+                          children: totalGroups
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "text-text-muted text-xs",
+                          children: "Core → Governance"
+                        }, undefined, false, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this),
+                    /* @__PURE__ */ jsxDEV("div", {
+                      className: "bg-card border-border rounded-lg border px-4 py-3",
+                      children: [
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "text-text-muted text-xs font-semibold tracking-widest uppercase",
+                          children: "Status"
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "font-koran text-2xl font-black",
+                          children: "Ready"
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "text-text-muted text-xs",
+                          children: "PGlite in-memory"
+                        }, undefined, false, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this),
+                    /* @__PURE__ */ jsxDEV("div", {
+                      className: "bg-card border-border rounded-lg border px-4 py-3",
+                      children: [
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "text-text-muted text-xs font-semibold tracking-widest uppercase",
+                          children: "Tree"
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "font-koran text-2xl font-black",
+                          children: tree.length
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("p", {
+                          className: "text-text-muted text-xs",
+                          children: "root nodes"
+                        }, undefined, false, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this)
+                  ]
+                }, undefined, true, undefined, this),
+                /* @__PURE__ */ jsxDEV("div", {
+                  className: "border-border bg-card rounded-lg border",
+                  children: [
+                    /* @__PURE__ */ jsxDEV("div", {
+                      className: "border-border flex items-center justify-between border-b px-4 py-3",
+                      children: [
+                        /* @__PURE__ */ jsxDEV("h2", {
+                          className: "text-sm font-semibold tracking-widest uppercase",
+                          children: "Resource Tree"
+                        }, undefined, false, undefined, this),
+                        /* @__PURE__ */ jsxDEV("span", {
+                          className: "text-text-muted text-xs",
+                          children: [
+                            totalResources,
+                            " resources"
+                          ]
+                        }, undefined, true, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this),
+                    /* @__PURE__ */ jsxDEV("div", {
+                      className: "divide-border divide-y",
+                      children: [
+                        groups.map((g) => /* @__PURE__ */ jsxDEV("div", {
+                          className: "px-4 py-3",
+                          children: [
+                            /* @__PURE__ */ jsxDEV("p", {
+                              className: "text-xs font-semibold tracking-widest uppercase text-form-label",
+                              children: g.name
+                            }, undefined, false, undefined, this),
+                            /* @__PURE__ */ jsxDEV("ul", {
+                              className: "mt-2 flex flex-wrap gap-2",
+                              children: g.items.map((it) => /* @__PURE__ */ jsxDEV("li", {
+                                children: [
+                                  /* @__PURE__ */ jsxDEV("a", {
+                                    href: it.href,
+                                    className: "bg-secondary text-secondary-foreground inline-flex items-center gap-1.5 rounded-md px-2.5 py-1 text-xs font-medium hover:underline",
+                                    children: [
+                                      /* @__PURE__ */ jsxDEV("span", {
+                                        children: it.icon ?? "•"
+                                      }, undefined, false, undefined, this),
+                                      " ",
+                                      it.label
+                                    ]
+                                  }, undefined, true, undefined, this),
+                                  (it.children?.length ?? 0) > 0 && /* @__PURE__ */ jsxDEV("span", {
+                                    className: "text-text-muted ml-1 text-xs",
+                                    children: [
+                                      "+",
+                                      it.children?.length ?? 0,
+                                      " child"
+                                    ]
+                                  }, undefined, true, undefined, this)
+                                ]
+                              }, it.id, true, undefined, this))
+                            }, undefined, false, undefined, this)
+                          ]
+                        }, g.name, true, undefined, this)),
+                        groups.length === 0 && /* @__PURE__ */ jsxDEV("p", {
+                          className: "text-text-muted px-4 py-6 text-center text-sm",
+                          children: "Belum ada resource terdaftar — pastikan rack() sudah dipanggil sebelum dashboard render."
+                        }, undefined, false, undefined, this)
+                      ]
+                    }, undefined, true, undefined, this)
+                  ]
+                }, undefined, true, undefined, this),
+                /* @__PURE__ */ jsxDEV("footer", {
+                  className: "border-border text-text-muted mt-6 border-t pt-3 text-center text-xs tracking-widest uppercase",
+                  children: "Printed by elysia-rack — ERP blueprint"
+                }, undefined, false, undefined, this)
+              ]
+            }, undefined, true, undefined, this)
+          ]
+        }, undefined, true, undefined, this)
+      ]
+    }, undefined, true, undefined, this)
+  }, undefined, false, undefined, this);
+}
+export {
+  Dashboard as default
+};