@thebes/cadmea 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BowenLabs
+
+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,133 @@
+# @thebes/cadmea
+
+Generic SolidJS admin-UI components for `@thebes/cadmus/cms` collections.
+
+> **0.x — active development.** APIs will change. Not production-ready.
+> Star [bowenlabs/project-thebes](https://github.com/bowenlabs/project-thebes) to follow along.
+
+---
+
+## What is this?
+
+Cadmus's `cms` subpath (collection config, schema codegen, the Local API,
+admin-introspection metadata) is the engine — framework-agnostic, no UI of
+its own. This package is the other half: the actual SolidJS components
+that render a generic admin UI from that metadata, the same way Payload
+splits `payload` core from `@payloadcms/next`/`@payloadcms/ui`.
+
+`app/workers/cadmea` (Thebes's reference CMS) consumes this package rather
+than owning the components directly.
+
+---
+
+## Install
+
+```bash
+pnpm add @thebes/cadmea @thebes/cadmus solid-js
+```
+
+Built with [Vite+'s `vp pack`](https://viteplus.dev/guide/pack)
+(Rolldown-based, wraps [`tsdown`](https://tsdown.dev) internally) plus
+[`@rolldown/plugin-babel`](https://github.com/rolldown/plugins) running
+Solid's JSX through `babel-preset-solid` directly, to produce real
+fine-grained-reactive output — not the generic `createElement`-style
+transform plain Rolldown/esbuild would otherwise produce by default. See
+`DECISIONS.md`'s 2026-06-24 entry for how the babel plugin is wired into
+`vp pack`'s `pack` block in `vite.config.ts`. Ships separate
+`browser`/`worker`/`node`/`deno` export conditions,
+matching how `solid-js` itself ships, so the right build
+(client-hydration vs. SSR) resolves automatically wherever you consume it
+— including from outside this monorepo, unlike the source-only shape this
+package started as (see `DECISIONS.md`'s 2026-06-22 entries).
+
+---
+
+## Components
+
+```typescript
+import { CollectionList, CollectionEdit } from '@thebes/cadmea'
+```
+
+**`CollectionList`** — generic table view. Renders one column per field
+(excluding `id` and `richText` fields, which aren't supported as plain
+table cells yet), with optional row-click navigation.
+
+**`CollectionEdit`** — generic create/edit form. Renders one input per
+field (excluding `id`), with `text`/`select`/`number` editable inputs and
+`date` fields shown read-only. Fields without a supported renderer
+(`richText`/`relationship`/`array`/`upload`/`checkbox`) are silently
+skipped rather than crashing — contributions welcome.
+
+Both take a `CollectionConfig` (from `@thebes/cadmus/cms`) as their
+`config` prop.
+
+---
+
+## TanStack Start mounting helper
+
+```typescript
+import {
+  createCollectionListPage,
+  createCollectionCreatePage,
+  createCollectionEditPage,
+} from '@thebes/cadmea/tanstack-start'
+```
+
+The equivalent of Payload's `@payloadcms/next` catch-all route pattern —
+factory functions that wire `CollectionList`/`CollectionEdit` together
+with `@tanstack/solid-query` (fetching, mutating, cache invalidation) and
+return a ready-to-use route `component`. TanStack Router's file-based
+routing still needs a real file per route (there's no runtime catch-all
+the way Next.js's `[[...segments]]` works), but each route file shrinks
+from ~40 hand-wired lines to ~15:
+
+```tsx
+// src/routes/admin/pages/index.tsx
+import { createCollectionListPage } from '@thebes/cadmea/tanstack-start'
+import { createFileRoute, useNavigate } from '@tanstack/solid-router'
+import { pagesCollection } from '../../../../cadmea.config.js'
+import { getPages } from '../../server-functions/pages'
+
+export const Route = createFileRoute('/admin/pages/')({ component: PagesPage })
+
+function PagesPage() {
+  const navigate = useNavigate()
+  const Page = createCollectionListPage({
+    collection: pagesCollection,
+    label: 'Pages',
+    queryKey: ['pages'],
+    queryFn: () => getPages(),
+    newHref: '/admin/pages/new',
+    onRowClick: (row) => navigate({ to: '/admin/pages/$pageId', params: { pageId: String(row.id) } }),
+  })
+  return <Page />
+}
+```
+
+Navigation (`onRowClick`, `onCreated`, `onDeleted`) stays in the route
+file rather than this package calling `useNavigate()` itself — TanStack
+Router's route-typing is generated per-app, so a generic package can't
+produce a correctly-typed `navigate()` call for routes it doesn't know
+about. See `app/workers/cadmea/src/routes/admin/pages/` in this repo for
+all three factories in real use (list, create, edit+delete).
+
+---
+
+## What this isn't (yet)
+
+No code-generation CLI that writes these route files for you from a
+collection config — you still create one thin file per collection per
+view. Worth revisiting once enough collections exist to justify that
+investment. See this repo's `DECISIONS.md`.
+
+---
+
+## Licensing
+
+MIT. See [LICENSE](./LICENSE) for full terms.
+
+---
+
+## Maintained by
+
+[BowenLabs](https://bowenlabs.com)

package/dist/RichTextEditor-BPilh7Pw.js

@@ -0,0 +1,36 @@
+import { effect, setAttribute, template, use } from "solid-js/web";
+import { onCleanup, onMount } from "solid-js";
+import { Editor } from "@tiptap/core";
+import StarterKit from "@tiptap/starter-kit";
+//#region src/RichTextEditor.tsx
+var _tmpl$ = /*#__PURE__*/ template(`<div class="textarea h-auto min-h-32 w-full">`);
+function RichTextEditor(props) {
+	let container;
+	let editor;
+	onMount(() => {
+		if (!container) return;
+		editor = new Editor({
+			element: container,
+			extensions: [StarterKit],
+			content: props.content ?? "",
+			onUpdate: ({ editor: current }) => {
+				props.onChange(current.getJSON());
+			}
+		});
+	});
+	onCleanup(() => {
+		editor?.destroy();
+	});
+	return (() => {
+		var _el$ = _tmpl$();
+		use((el) => {
+			container = el;
+		}, _el$);
+		effect(() => setAttribute(_el$, "id", props.id));
+		return _el$;
+	})();
+}
+//#endregion
+export { RichTextEditor };
+
+//# sourceMappingURL=RichTextEditor-BPilh7Pw.js.map

package/dist/RichTextEditor-BPilh7Pw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RichTextEditor-BPilh7Pw.js","names":["Editor","StarterKit","onCleanup","onMount","RichTextEditorProps","id","content","onChange","doc","RichTextEditor","props","container","HTMLDivElement","editor","element","extensions","onUpdate","current","getJSON","destroy","_el$","_tmpl$","_$use","el","_$effect","_$setAttribute"],"sources":["../src/RichTextEditor.tsx"],"sourcesContent":["import { Editor } from \"@tiptap/core\";\nimport StarterKit from \"@tiptap/starter-kit\";\nimport { onCleanup, onMount } from \"solid-js\";\n\nexport interface RichTextEditorProps {\n  id?: string;\n  /** TipTap's native JSON document shape — stored as-is, no transform layer. */\n  content?: object;\n  onChange: (doc: object) => void;\n}\n\n// No official Solid binding for TipTap exists, so this wraps @tiptap/core's\n// vanilla `Editor` class directly in Solid's onMount/onCleanup lifecycle —\n// per CLAUDE.md's preference for the framework-agnostic core API over an\n// unofficial community port (same reasoning already applied to Phosphor\n// icons). `content` is only read once at mount, matching how this form's\n// other fields are initialized from `initialValues` rather than reacting\n// to prop changes after the fact — there is no live re-sync if `content`\n// changes out from under an already-mounted editor.\nexport function RichTextEditor(props: RichTextEditorProps) {\n  let container: HTMLDivElement | undefined;\n  let editor: Editor | undefined;\n\n  onMount(() => {\n    if (!container) return;\n    editor = new Editor({\n      element: container,\n      extensions: [StarterKit],\n      content: props.content ?? \"\",\n      onUpdate: ({ editor: current }) => {\n        props.onChange(current.getJSON());\n      },\n    });\n  });\n\n  onCleanup(() => {\n    editor?.destroy();\n  });\n\n  return (\n    <div\n      id={props.id}\n      class=\"textarea h-auto min-h-32 w-full\"\n      ref={(el) => {\n        container = el;\n      }}\n    />\n  );\n}\n"],"mappings":";;;;;;AAmBA,SAAgBS,eAAeC,OAA4B;CACzD,IAAIC;CACJ,IAAIE;CAEJV,cAAc;EACZ,IAAI,CAACQ,WAAW;EAChBE,SAAS,IAAIb,OAAO;GAClBc,SAASH;GACTI,YAAY,CAACd,UAAU;GACvBK,SAASI,MAAMJ,WAAW;GAC1BU,WAAW,EAAEH,QAAQI,cAAc;IACjCP,MAAMH,SAASU,QAAQC,QAAQ,CAAC;GAClC;EACF,CAAC;CACH,CAAC;CAEDhB,gBAAgB;EACdW,QAAQM,QAAQ;CAClB,CAAC;CAED,cAAA;EAAA,IAAAC,OAAAC,OAAA;EAAAC,KAIUC,OAAO;GACXZ,YAAYY;EACd,GAACH,IAAA;EAAAI,aAAAC,aAAAL,MAAA,MAJGV,MAAML,EAAE,CAAA;EAAA,OAAAe;CAAA,EAAA,CAAA;AAOlB"}

package/dist/RichTextEditor-DcLqdFY7.js

@@ -0,0 +1,15 @@
+import { escape, ssr, ssrAttribute } from "solid-js/web";
+import { onCleanup, onMount } from "solid-js";
+import "@tiptap/core";
+import "@tiptap/starter-kit";
+//#region src/RichTextEditor.tsx
+var _tmpl$ = ["<div", " class=\"textarea h-auto min-h-32 w-full\"></div>"];
+function RichTextEditor(props) {
+	onMount(() => {});
+	onCleanup(() => {});
+	return ssr(_tmpl$, ssrAttribute("id", escape(props.id, true), false));
+}
+//#endregion
+export { RichTextEditor };
+
+//# sourceMappingURL=RichTextEditor-DcLqdFY7.js.map

package/dist/RichTextEditor-DcLqdFY7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RichTextEditor-DcLqdFY7.js","names":["Editor","StarterKit","onCleanup","onMount","RichTextEditorProps","id","content","onChange","doc","RichTextEditor","props","container","HTMLDivElement","editor","element","extensions","onUpdate","current","getJSON","destroy","_$ssr","_tmpl$","_$ssrAttribute","_$escape"],"sources":["../src/RichTextEditor.tsx"],"sourcesContent":["import { Editor } from \"@tiptap/core\";\nimport StarterKit from \"@tiptap/starter-kit\";\nimport { onCleanup, onMount } from \"solid-js\";\n\nexport interface RichTextEditorProps {\n  id?: string;\n  /** TipTap's native JSON document shape — stored as-is, no transform layer. */\n  content?: object;\n  onChange: (doc: object) => void;\n}\n\n// No official Solid binding for TipTap exists, so this wraps @tiptap/core's\n// vanilla `Editor` class directly in Solid's onMount/onCleanup lifecycle —\n// per CLAUDE.md's preference for the framework-agnostic core API over an\n// unofficial community port (same reasoning already applied to Phosphor\n// icons). `content` is only read once at mount, matching how this form's\n// other fields are initialized from `initialValues` rather than reacting\n// to prop changes after the fact — there is no live re-sync if `content`\n// changes out from under an already-mounted editor.\nexport function RichTextEditor(props: RichTextEditorProps) {\n  let container: HTMLDivElement | undefined;\n  let editor: Editor | undefined;\n\n  onMount(() => {\n    if (!container) return;\n    editor = new Editor({\n      element: container,\n      extensions: [StarterKit],\n      content: props.content ?? \"\",\n      onUpdate: ({ editor: current }) => {\n        props.onChange(current.getJSON());\n      },\n    });\n  });\n\n  onCleanup(() => {\n    editor?.destroy();\n  });\n\n  return (\n    <div\n      id={props.id}\n      class=\"textarea h-auto min-h-32 w-full\"\n      ref={(el) => {\n        container = el;\n      }}\n    />\n  );\n}\n"],"mappings":";;;;;;AAmBA,SAAgBS,eAAeC,OAA4B;CAIzDP,cAAc,CAUd,CAAC;CAEDD,gBAAgB,CAEhB,CAAC;CAED,OAAAkB,IAAAC,QAAAC,aAAA,MAAAC,OAEQb,MAAML,IAAE,IAAA,GAAA,KAAA,CAAA;AAOlB"}

package/dist/index/index.d.ts

@@ -0,0 +1,147 @@
+import { JSX } from "solid-js";
+import { CollectionConfig } from "@thebes/cadmus/cms";
+
+//#region src/capabilities.d.ts
+/**
+ * Drives action gating in `CollectionEdit` and the `tanstack-start` list/
+ * edit page factories — hide/disable an action a context can't perform
+ * rather than let it fail server-side after a click. A field left
+ * `undefined` reads as "allowed", mirroring `@thebes/cadmus/cms`'s own
+ * "no access fn configured = allowed" default, so collections that don't
+ * wire this up at all keep today's unrestricted behavior.
+ */
+interface CollectionCapabilities {
+  canCreate?: boolean;
+  canUpdate?: boolean;
+  canDelete?: boolean;
+}
+//#endregion
+//#region src/CollectionEdit.d.ts
+interface RelationshipOption {
+  id: number;
+  label: string;
+}
+/**
+ * Replaces the generic "Save" button with "Save draft"/"Publish" when the
+ * collection has `versions: { drafts: true }` — a separate privilege from
+ * a plain update, matching `access.publish` in `@thebes/cadmus/cms`.
+ * `onPublish` takes no values: publishing acts on whatever was last saved
+ * as a draft (the consuming route tracks which version that is), not on
+ * the live form state.
+ */
+interface DraftActions {
+  onSaveDraft: (values: Record<string, unknown>) => void | Promise<void>;
+  onPublish?: () => void | Promise<void>;
+  /**
+   * Opens a live preview of the last saved draft (issue #28) — like
+   * `onPublish`, acts on whatever was last saved as a draft, not the live
+   * form state. Omit to not render the Preview button at all.
+   */
+  onPreview?: () => void | Promise<void>;
+  saving?: boolean;
+  publishing?: boolean;
+  previewing?: boolean;
+  /** Disables Publish — e.g. until a draft has been saved at least once. */
+  canPublish?: boolean;
+  /** Disables Preview — same gating as canPublish, a draft must exist first. */
+  canPreview?: boolean;
+  saveDraftLabel?: string;
+  publishLabel?: string;
+  previewLabel?: string;
+}
+interface CollectionEditProps {
+  config: CollectionConfig;
+  initialValues?: Record<string, unknown>;
+  onSubmit: (values: Record<string, unknown>) => void | Promise<void>;
+  submitLabel?: string;
+  error?: string;
+  /** Disables the Save button and shows a spinner in its place. */
+  saving?: boolean;
+  /**
+   * Resolves an `upload` field's selected file to a stored URL. Required
+   * if the collection has any `upload` fields — `CollectionEdit` never
+   * talks to storage directly (stays agnostic of R2/cadmus/storage), so
+   * the consuming route wires this to a server function that calls an
+   * `ImageService`'s `upload()`.
+   */
+  onUploadFile?: (file: File) => Promise<{
+    url: string;
+  }>;
+  /**
+   * Options for `relationship` fields (hasMany:false only — see
+   * RelationshipFieldConfig's `hasMany` caveat), keyed by the field's
+   * `relationTo` collection slug. `CollectionEdit` can't query another
+   * collection itself, so the consuming route fetches the related rows
+   * and passes them in.
+   */
+  relationshipOptions?: Partial<Record<string, RelationshipOption[]>>;
+  /**
+   * Fired whenever the dirty (unsaved-changes) state changes — wire this
+   * to a router-level navigation guard (e.g. `useBlocker` in the
+   * consuming route) since `CollectionEdit` has no router access itself.
+   */
+  onDirtyChange?: (dirty: boolean) => void;
+  /** Only rendered when `config.versions?.drafts` is also true. */
+  draftActions?: DraftActions;
+  /**
+   * Hides the Save button when `canUpdate` is `false` — see issue #26's
+   * RBAC-aware admin UI. Undefined (the default — most collections don't
+   * wire this up) reads as "allowed", same as `@thebes/cadmus/cms`'s own
+   * "no access fn = allowed" default.
+   */
+  capabilities?: CollectionCapabilities;
+}
+declare function CollectionEdit(props: CollectionEditProps): import("solid-js").JSX.Element;
+//#endregion
+//#region src/CollectionList.d.ts
+interface CollectionListProps {
+  config: CollectionConfig;
+  rows: Record<string, unknown>[];
+  onRowClick?: (row: Record<string, unknown>) => void;
+  /**
+   * 1-based current page. Omit (along with `pageSize`) to render without
+   * the pagination bar entirely — list views with no `find()` paging
+   * wired up yet still render correctly.
+   */
+  page?: number;
+  pageSize?: number;
+  /** Total row count across all pages — see `LocalApi.count()`. Enables
+   * disabling "Next" exactly at the last page; omit to fall back to a
+   * `rows.length < pageSize` heuristic. */
+  totalCount?: number;
+  onPageChange?: (page: number) => void;
+  /** Field key currently sorted on. Omit to hide the sort control. */
+  sortField?: string;
+  sortDirection?: "asc" | "desc";
+  onSortChange?: (field: string, direction: "asc" | "desc") => void;
+  /** Shows the "Select" bulk-select mode toggle. */
+  selectable?: boolean;
+  selectedIds?: ReadonlySet<number>;
+  onSelectionChange?: (selectedIds: Set<number>) => void;
+}
+declare function CollectionList(props: CollectionListProps): import("solid-js").JSX.Element;
+//#endregion
+//#region src/SearchPalette.d.ts
+interface SearchPaletteResult {
+  collection: string;
+  id: number;
+  label: string;
+}
+interface SearchPaletteProps {
+  /** Runs a query against `LocalApi.search()` for every searchable collection — see `@thebes/cadmus/cms`'s `getCollectionsMeta`. */
+  onSearch: (query: string) => Promise<SearchPaletteResult[]>;
+  /** Navigates to the chosen result; the palette closes itself afterward. */
+  onSelect: (result: SearchPaletteResult) => void;
+}
+/**
+ * Self-contained Cmd+K (Ctrl+K on non-Mac) search palette — issue #29.
+ * Owns its own open/closed state and keyboard listener; the host app only
+ * supplies `onSearch` (wired to a server function that fans out across
+ * every collection with `search` configured) and `onSelect` (navigation).
+ * Mirrors PanelNav's focus-trap-on-open / restore-focus-on-close pattern
+ * rather than introducing a second one.
+ */
+declare function SearchPalette(props: SearchPaletteProps): JSX.Element;
+//#endregion
+export { type CollectionCapabilities, CollectionEdit, type CollectionEditProps, CollectionList, type CollectionListProps, SearchPalette, type SearchPaletteProps, type SearchPaletteResult };
+//# sourceMappingURL=index.d.ts.map