elysia-rack 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 notoofly
+
+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,241 @@
+# 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
+
+```bash
+bun add elysia-rack elysia react react-dom
+# or
+npm i elysia-rack elysia react react-dom
+```
+
+`elysia`, `react`, and `react-dom` are peer dependencies.
+
+## Usage
+
+```ts
+import { Elysia } from "elysia";
+import { rack } from "elysia-rack";
+
+const app = new Elysia().use(
+  rack("/catalog/products", {
+    model: { drizzle: { db, table: products } },
+
+    validation: {
+      create: CreateProductSchema,
+      replace: ReplaceProductSchema,
+      update: UpdateProductSchema,
+      params: ProductParamsSchema,
+      query: ProductQuerySchema,
+    },
+
+    authorization: {
+      list: "products.view",
+      create: "products.create",
+      delete: async ({ request }) => canDelete(request),
+    },
+
+    query: {
+      searchable: ["name", "sku"],
+      filterable: ["status", "categoryId"],
+      sortable: ["name", "price", "createdAt"],
+      defaultSort: { field: "createdAt", direction: "desc" },
+      pagination: { default: 20, max: 100 },
+    },
+
+    operations: { create: true, delete: false },
+
+    metadata: {
+      id: "products",
+      label: "Product",
+      pluralLabel: "Products",
+      group: "Catalog",
+    },
+
+    openapi: { tags: ["Products"] },
+    settings: { primaryKey: "id", returning: true },
+  }),
+);
+
+app.listen(3000);
+```
+
+Generated routes (all gated by `operations`, default on):
+
+| Operation | Method | Path |
+|---|---|---|
+| display panel | `GET` | `/` |
+| list data | `QUERY` | `/data` |
+| detail data | `QUERY` | `/data/:id` |
+| create | `POST` | `/` |
+| replace | `PUT` | `/:id` |
+| update | `PATCH` | `/:id` |
+| delete | `DELETE` | `/:id` |
+
+`GET /` renders the React panel via `page("/panel")` (customize with the
+`page` option, disable with `page: { enabled: false }`). All data reads go
+through the `QUERY` method under `/data`. The panel UI calls the same
+endpoint live via fetch (progressive enhancement — links and forms still
+work through plain `GET` navigation without JavaScript).
+
+## Panel actions
+
+The panel ships create / edit / delete UI driven by the same API:
+
+- `+ New` 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.
+- Row `Edit` loads the row via `QUERY /data/:id` into a dialog and saves
+  with `PATCH /:id`. Empty inputs are skipped (partial update).
+- Row `Delete` confirms natively, then `DELETE /:id`.
+- Checkbox selection enables the bulk bar: `Delete selected` loops
+  `DELETE /:id`, and the field applier loops `PATCH /:id` with the
+  chosen field/value. `Clear` resets the selection.
+
+Action UI follows `operations`: disable `create`/`update`/`delete` and
+the corresponding buttons, dialogs and bulk controls disappear.
+
+## Idempotency (POST)
+
+`POST /` requires an idempotency key by default. Send a client-generated
+key per create attempt:
+
+```bash
+curl -X POST localhost:3000/catalog/products \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
+  -d '{"name":"Keyboard"}'
+```
+
+Replays with the same key return the stored `201` response with an
+`Idempotent-Replayed: true` header instead of re-executing. Missing keys
+are rejected with `400`. Tune via the `idempotency` option:
+
+```ts
+rack("/catalog/products", {
+  model: { drizzle: { db, table: products } },
+  idempotency: {
+    required: false,          // allow keyless POST (default true)
+    header: "X-Idempotency-Key",
+    ttl: 3600,                // replay window in seconds (default 86400)
+    store: myRedisStore,      // shared store for multi-instance deploys
+  },
+});
+```
+
+## ORM adapters
+
+`model` selects the adapter. Drizzle needs `drizzle-orm` installed
+(optional peer); Prisma needs no extra dependency — pass any client
+delegate (e.g. `prisma.product`):
+
+```ts
+// Drizzle (Postgres, SQLite, ...)
+import { drizzle } from "drizzle-orm/node-postgres";
+model: { drizzle: { db: drizzle(client), table: products } },
+
+// Prisma
+model: { prisma: { client: prisma, model: prisma.product } },
+```
+
+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).
+- `settings.softDelete: true` writes a timestamp to `deletedAt`
+  (override with `settings.deletedAtField`) instead of deleting, and
+  reads skip soft-deleted rows.
+- `settings.returning: false` omits `data` from mutation responses.
+
+## Dashboard (sidebar, breadcrumb, iframe)
+
+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>`:
+
+```ts
+import { page, pages, reactPlugin } from "elysia-rack/react";
+
+const app = new Elysia()
+  .use(reactPlugin({ pages }))
+  .use(rack("/catalog/products", { model, metadata: { ... } }))
+  .get("/", ({ query }) =>
+    page("/dashboard", {
+      name: "My Shop",
+      resource: typeof query.resource === "string" ? query.resource : undefined,
+    }),
+  );
+```
+
+Sidebar links navigate with `?resource=<id>` (full reload, no JavaScript
+needed). Without a selection the first registered resource is shown.
+
+React panel rendering via the `./react` subpath:
+
+```ts
+import { page, pages, reactPlugin } from "elysia-rack/react";
+
+const app = new Elysia()
+  .use(reactPlugin({ pages }))
+  .get("/", () => page("/dashboard", { name: "Ada" }));
+```
+
+## Panel assets (Vite)
+
+CSS, Tailwind and browser JavaScript go through Vite (`vite.config.ts`,
+`bun run build:assets`):
+
+- `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`)
+
+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).
+
+## Panel theme
+
+`src/react/page/panel.css` is the stylesheet entry:
+
+- `theme/tokens.css` — full semantic tokens (surface, text, status,
+  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.
+
+Dark mode flips automatically: stored choice (`localStorage`), else
+`prefers-color-scheme`. The `◐ Theme` button in the masthead toggles it.
+Components must only use semantic utilities (`bg-background`,
+`text-foreground`, `bg-table-row-hover`, …) so themes swap without
+touching React code.
+
+## Release (maintainer)
+
+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`.
+
+## Scripts
+
+```bash
+bun install        # install dependencies
+bun run dev        # run src/playground.ts
+bun test           # unit tests (bun:test)
+bun run typecheck  # tsc --noEmit
+bun run build      # dist/ (js via bun build + .d.ts via tsc)
+```
+
+## License
+
+MIT © notoofly

package/dist/Dashboard-xpstr7fr.js

@@ -0,0 +1,172 @@
+import {
+  listRacks
+} from "./index-zc7rgvmm.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 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: group.items.some((item) => item.active) || 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("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",
+                    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)
+                }, 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;
+}
+async function Dashboard(props) {
+  const racks = (props.racks ?? listRacks()).filter((r) => !r.metadata.hidden);
+  const selected = racks.find((r) => r.metadata.id === props.resource) ?? racks[0];
+  const groups = buildGroups(racks, 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
+};