@dalgoridim/headless-cms 0.1.0 → 0.2.0

package/ARCHITECTURE.md

@@ -0,0 +1,126 @@
+# Architecture & design notes
+
+Core/internal documentation for `@dalgoridim/headless-cms`. For consumer usage,
+see the [README](./README.md). For the history of the headless redesign, see
+[REDESIGN.md](./REDESIGN.md).
+
+## Philosophy: harness, not framework
+
+The package wires **behavior** and imposes nothing else. Concretely:
+
+- **Zero runtime dependencies.** No CSS framework, icon set, toast library, or
+  markdown renderer is bundled. Anything visual or opinionated is the consumer's.
+- **The UI primitives are headless.** They manage `contentEditable`, uploads,
+  saves, and edit state, and expose that state (via `data-*` attributes,
+  render-props, and hooks) so the consumer owns 100% of the markup.
+- **The store is schemaless.** The engine only ever adds an `id` and `collection`
+  for addressing; your content type `T` is never forced to declare them
+  (`Editable<T> = T & { id; collection }`).
+
+This is a deliberate reaction to the original extraction, where the components
+shipped a finished, portfolio-specific look (Tailwind + a dark palette + a
+`primary` token + a bespoke markup syntax). Adopting the package then meant
+inheriting that design. The redesign split **behavior (package)** from
+**appearance (consumer)**.
+
+## Two layers
+
+| Layer | Responsibility | Freedom |
+|---|---|---|
+| **Data / server** | CRUD, the neutral `Query`, auth gating, storage signing | Schemaless; adapters are generic over `T` |
+| **UI / client** | inline-edit behavior, save buffering, upload flow | Headless; consumer supplies all styling/markup |
+
+## Subpath exports & the client/server bundle boundary
+
+Server-only SDKs must never reach the client bundle. Two mechanisms enforce this:
+
+1. **Split entries per concern.** Each storage adapter is two modules:
+   - `storage/<x>` — the **client** half (`upload`), pure `fetch`, safe in client
+     components.
+   - `storage/<x>/server` — the **server** half (`sign`), pulls in the SDK.
+
+   This split exists because a single module that *also* contained a lazy
+   `import("cloudinary")` still got traced into the client bundle by
+   Next/Turbopack → `Can't resolve 'fs'`. Splitting the entry removes the trace
+   entirely.
+
+2. **Auth/data adapters live behind `/server`, `/adapters/*`, `/auth/*`** so a
+   client import can never transitively pull a Node-only SDK.
+
+## One React context across entries
+
+The built-in auth providers (e.g. `auth/firebase/client`) import
+`CmsAuthProvider` through the package's **public** `@dalgoridim/headless-cms/client`
+specifier — not a relative path — so the provider and the consumer's primitives
+share the **same** context instance at runtime. This is enforced with a tsup
+`external` regex (`/^@dalgoridim\/headless-cms(\/.*)?$/`) plus `tsconfig` paths.
+Using a relative import here would create a second context instance and silently
+break `useCmsAuth`.
+
+## The neutral Query & backend parity
+
+`Query` is intentionally backend-agnostic so no native query type (Firestore's
+`Query`, raw SQL) leaks through the engine. Not every backend can honor every
+operator; rather than return wrong results, an adapter **throws** on what it
+cannot do.
+
+| Capability | Postgres | Firestore |
+|---|:--:|:--:|
+| `eq` `ne` `lt` `lte` `gt` `gte` | ✅ | ✅ |
+| `in` / `nin` | ✅ | ✅ |
+| `contains` (case-insensitive substring) | ✅ (`ILIKE`) | ❌ throws (no native substring) |
+| `{ or: [...] }` groups | ✅ | ❌ throws |
+| `offset` pagination | ✅ | ✅ |
+
+## Hybrid Postgres adapter
+
+Two storage strategies under one adapter:
+
+- **Unregistered collections** → a shared JSONB `documents` table, keyed by a
+  composite `PRIMARY KEY (collection, id)` (global `id` PKs collided across
+  collections — e.g. `project/1`, `skill/1`). Fully schemaless, zero config.
+- **Registered collections** → flat fields mapped onto typed columns, **plus** a
+  JSONB `extra` column so unmapped fields are never dropped.
+
+Notable details:
+
+- `ON CONFLICT DO UPDATE` for typed-table upsert qualifies `extra` as
+  `<table>.extra` — a bare `extra` is ambiguous between the target table and the
+  `excluded` pseudo-relation.
+- **Caveat:** JSONB fields are extracted as **text** (`data->>'field'`), so
+  numeric ordering/comparison in the schemaless table is lexicographic
+  (`"10" < "5"`). Register the collection with a typed `int`/`float` column for
+  true numeric behavior.
+
+## Relations
+
+References are plain field values — a self-describing `{ collection, id }`, a bare
+id string, or an array of either. `resolveRelations(adapter, docs, opts)` runs
+**engine-side** (never in an adapter) so it works identically over Postgres,
+Firestore, or any custom `DataAdapter`. Loads are deduplicated (one `fetchById`
+per unique `(collection, id)`) and parallelized; unresolved refs are left
+untouched.
+
+## Auth model
+
+`AuthIdentity` is minimal and open: only `isAdmin` is meaningful to the default
+gate; carry any other claims (roles, scopes, tenant) as extra keys. The gate
+authorizes via an injectable `AuthorizeFn` (`(identity, req) => boolean`),
+defaulting to `identity.isAdmin === true`. This lets a consumer gate on anything
+without the package prescribing an identity shape.
+
+## Headless UI internals
+
+- **`ContentEditSpan`** — wires `contentEditable`, persists on blur, and emits
+  `data-cms-editable` / `data-cms-editing` / `data-cms-focused`. Rich-text
+  rendering is injected via `renderValue(raw) => ReactNode` (default: plain text).
+- **`EditableImage`** — owns the file input, object-URL previews, external-URL
+  validation, and the pending-upload queue; hands all state to a render-prop.
+- **`useMarkdownEditor`** — value state + a selection-aware `insert` command +
+  save/reset, with no UI. (The reference app skins it with `@uiw/react-md-editor`.)
+
+## Build
+
+`tsup` produces ESM + CJS + `.d.ts` per subpath entry, with every backend SDK and
+the package's own specifier marked `external`. `files: ["dist"]` (plus the
+markdown docs) controls what ships to npm.

package/README.md

@@ -1,24 +1,30 @@
 # @dalgoridim/headless-cms
 
-Database-agnostic, inline-edit headless CMS engine for React / Next.js apps.
+Database-agnostic, **inline-edit** headless CMS engine for React / Next.js apps.
 
-Content lives in your database and is editable **inline on the live site** by an
-authenticated admin. The persistence, auth, and storage layers are fully
-pluggable — swap Firestore for Postgres, Cloudinary for S3, Firebase auth for
-NextAuth, without touching the editing UI.
+Content lives in *your* database and is editable **inline on the live site** by an
+authenticated admin. Persistence, auth, and storage are fully pluggable — swap
+Firestore for Postgres, Cloudinary for S3, Firebase auth for NextAuth, without
+touching your UI.
+
+**Harness, not framework.** Zero runtime dependencies; the editing components are
+headless (you own all markup and styling); your content shape stays unconstrained.
+You build a thin skin over the primitives (see [Styling](#styling-bring-your-own-look)) —
+the package never pushes a look onto your site. The design rationale and internals
+live in [ARCHITECTURE.md](./ARCHITECTURE.md).
 
 ## Install
 
 ```bash
 npm install @dalgoridim/headless-cms
-# plus the adapters you actually use, e.g.:
+# plus only the adapters you actually use:
 npm install firebase firebase-admin cloudinary   # Firestore + Cloudinary + Firebase
 npm install pg                                    # Postgres
 npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner  # S3
 ```
 
 `react` / `react-dom` are peer deps; every backend SDK is an **optional** peer —
-you only install the ones your chosen adapters need.
+install only what your chosen adapters need.
 
 ## Subpath exports
 
@@ -27,31 +33,32 @@ Server-only code never leaks into the client bundle. Import from the right entry
 | Entry | Contents |
 |---|---|
 | `@dalgoridim/headless-cms` | Shared types only (safe anywhere) |
-| `.../client` | `PageProvider`, `usePageContext`, `ContentEditSpan`, `EditableImage`, `MarkdownEditor`, `CmsAuthProvider`, `useCmsAuth` |
-| `.../server` | `createCmsHandlers`, `createAdminGate` |
+| `.../client` | `PageProvider`, `usePageContext`, `ContentEditSpan`, `EditableImage`, `useMarkdownEditor`, `CmsAuthProvider`, `useCmsAuth` |
+| `.../server` | `createCmsHandlers`, `createAdminGate`, `resolveRelations` |
 | `.../adapters/firestore` | `FirestoreDataAdapter` |
 | `.../adapters/postgres` | `PostgresDataAdapter` (hybrid JSONB + typed tables) |
-| `.../storage/cloudinary` \| `.../storage/s3` \| `.../storage/local` | **Client** upload adapters (`cloudinaryStorage`, `s3Storage`, `localStorage`) — pure `fetch`, safe in client components |
-| `.../storage/cloudinary/server` \| `.../storage/s3/server` \| `.../storage/local/server` | **Server** signers (`cloudinarySign`, `s3Sign`, `localSign`) — pull in SDKs, server-only |
+| `.../storage/{cloudinary,s3,local}` | **Client** upload adapters — pure `fetch`, safe in client components |
+| `.../storage/{cloudinary,s3,local}/server` | **Server** signers — pull in SDKs, server-only |
 | `.../auth/firebase` | `firebaseAuth` (server gate) |
 | `.../auth/firebase/client` | `FirebaseAuthProvider`, `useFirebaseAuth` |
 | `.../auth/nextauth` | `nextAuthAuth`, `customAuth` |
 
-## The three core interfaces
+## Core interfaces
 
 ```ts
 import type { DataAdapter, AuthAdapter, StorageAdapter } from "@dalgoridim/headless-cms";
 ```
 
-- **`DataAdapter`** — backend CRUD over a neutral `Query`.
-- **`AuthAdapter`** — `verifyRequest(req)` gates every admin route, server-side.
-- **Storage** is split into two halves so server SDKs never reach the client
-  bundle: `ClientStorageAdapter` (`upload`, from `.../storage/<x>`) and
+- **`DataAdapter`** — backend CRUD over a neutral [`Query`](#the-query-language).
+- **`AuthAdapter`** — `verifyRequest(req)` resolves an identity; the gate decides
+  ([auth](#auth-the-gate-is-yours)).
+- **Storage** is split in two so server SDKs never reach the client bundle:
+  `ClientStorageAdapter` (`upload`, from `.../storage/<x>`) and
   `ServerStorageAdapter` (`sign`, from `.../storage/<x>/server`).
 
-## Wiring (Next.js App Router)
+## Quick start (Next.js App Router)
 
-**1. The admin CRUD route** — replaces a hand-written handler:
+### 1. Admin CRUD route
 
 ```ts
 // app/api/admin/[collection]/[id]/route.ts
@@ -71,7 +78,7 @@ export const { GET, PATCH, PUT, DELETE } = createCmsHandlers({
 });
 ```
 
-**2. The storage sign route** — uses the **server** signer:
+### 2. Storage sign route (server signer)
 
 ```ts
 // app/api/admin/sign/route.ts
@@ -90,16 +97,15 @@ export const POST = createCmsHandlers({
 }).sign;
 ```
 
-**3. Providers + editable content** (client):
+### 3. Providers (client)
 
 ```tsx
 "use client";
-import { PageProvider, ContentEditSpan, EditableImage } from "@dalgoridim/headless-cms/client";
+import { PageProvider } from "@dalgoridim/headless-cms/client";
 import { FirebaseAuthProvider } from "@dalgoridim/headless-cms/auth/firebase/client";
 import { cloudinaryStorage } from "@dalgoridim/headless-cms/storage/cloudinary";
 import { auth, googleProvider } from "@/lib/firebase/config";
 
-// Client upload adapter — posts to the sign route, then to Cloudinary.
 const storage = cloudinaryStorage({ folder: "uploads", signEndpoint: "/api/admin/sign" });
 
 export function Providers({ initialSections, children }) {
@@ -111,18 +117,156 @@ export function Providers({ initialSections, children }) {
     </FirebaseAuthProvider>
   );
 }
+```
+
+`PageProvider` saves `PATCH ${apiBasePath}/{collection}/{id}` (default `apiBasePath`
+= `/api/admin`). Edit mode is driven by `useCmsAuth().isEditing`, which the auth
+providers feed. Pass `notify` to surface your own toasts — the default logs to the
+console so the package carries no toast dependency.
+
+## The editing primitives (headless)
+
+### `ContentEditSpan` — inline-editable text
 
-// Anywhere inside:
-<ContentEditSpan collection="portfolio" sectionKey="hero" fieldKey="title" as="h1">
+Wires `contentEditable`, reads/writes the field, and exposes edit state via
+`data-*` attributes. It ships **no styling and no markup language** — supply your
+own via `className` and `renderValue`.
+
+```tsx
+import { ContentEditSpan } from "@dalgoridim/headless-cms/client";
+
+<ContentEditSpan
+  collection="pages"
+  sectionKey="hero"
+  fieldKey="title"
+  as="h1"                       // any element/tag; defaults to "span"
+  renderValue={(raw) => raw}    // turn the stored string into nodes (default: plain text)
+  className="my-heading"
+>
   Default title
 </ContentEditSpan>
-<EditableImage collection="portfolio" sectionKey="hero" fieldKey="image"
-  docId="hero" src={section.image} />
 ```
 
-`PageProvider` saves `PATCH ${apiBasePath}/{collection}/{id}` (default
-`apiBasePath` = `/api/admin`). Edit mode is driven by `useCmsAuth().isEditing`;
-the built-in auth providers feed that context.
+State is exposed as attributes so you can style with plain CSS (or Tailwind
+`data-[...]` variants):
+
+| Attribute | Present when |
+|---|---|
+| `data-cms-editable` | always (the primitive is mounted) |
+| `data-cms-editing` | the current user is in edit mode |
+| `data-cms-focused` | the field is actively being edited |
+
+```css
+[data-cms-focused] { outline: 2px solid var(--accent); border-radius: 4px; }
+[data-cms-editing]:hover { outline: 1px dashed var(--accent); cursor: text; }
+```
+
+Want rich text? Pass a `renderValue` that parses your own syntax (markdown, a
+custom mini-language, etc.) into React nodes — the package no longer dictates one.
+
+### `EditableImage` — upload / external-URL via render-prop
+
+Manages file picking, object URLs, external-URL validation, and the pending-upload
+queue. You render the chrome:
+
+```tsx
+import { EditableImage } from "@dalgoridim/headless-cms/client";
+
+<EditableImage collection="pages" sectionKey="hero" fieldKey="image"
+  docId="hero" src={section.image}>
+  {({ isEditing, saving, hasError, openFilePicker, setExternalUrl, imgProps }) => (
+    <div className="relative">
+      <img {...imgProps} alt="" />
+      {isEditing && (
+        <button onClick={openFilePicker} disabled={saving}>Replace</button>
+      )}
+    </div>
+  )}
+</EditableImage>
+```
+
+Omit the render-prop child and it falls back to a bare unstyled `<img>`.
+
+### `useMarkdownEditor` — headless markdown editing
+
+State + a selection-aware `insert` command. Bring your own modal, toolbar, icons,
+and preview (e.g. `react-markdown`):
+
+```tsx
+import { useMarkdownEditor } from "@dalgoridim/headless-cms/client";
+
+function Editor({ initialValue, onSave }) {
+  const md = useMarkdownEditor({ initialValue, onSave });
+  return (
+    <>
+      <button onClick={() => md.insert("**", "**", "bold")}>Bold</button>
+      <textarea ref={md.textareaRef} value={md.value}
+        onChange={(e) => md.setValue(e.target.value)} />
+      <span>{md.charCount} chars</span>
+      <button onClick={md.save}>Save</button>
+    </>
+  );
+}
+```
+
+## The Query language
+
+A neutral, backend-agnostic query passed to `DataAdapter.fetchCollection`:
+
+```ts
+type Query = {
+  filters?: (QueryFilter | { or: QueryFilter[] })[];   // top level AND; groups OR
+  orderBy?: { field: string; direction: "asc" | "desc" }[];
+  limit?: number;
+  offset?: number;
+  populate?: string[];   // reference fields to inline-resolve (see Relations)
+};
+```
+
+**Operators** (`QueryFilter = { field, op, value }`):
+
+| op | meaning | Postgres | Firestore |
+|---|---|:--:|:--:|
+| `eq` / `ne` | equals / not equals | ✅ | ✅ |
+| `lt` `lte` `gt` `gte` | comparisons | ✅ | ✅ |
+| `in` / `nin` | value in / not in array | ✅ | ✅ |
+| `contains` | case-insensitive substring | ✅ | ❌ throws |
+| `{ or: [...] }` | disjunction | ✅ | ❌ throws |
+
+Where a backend can't honor an op, it throws a clear error rather than returning
+wrong results.
+
+```ts
+await data.fetchCollection("posts", {
+  filters: [
+    { field: "title", op: "contains", value: "hello" },
+    { or: [{ field: "tag", op: "eq", value: "react" },
+           { field: "tag", op: "eq", value: "sql" }] },
+  ],
+  orderBy: [{ field: "createdAt", direction: "desc" }],
+  limit: 20,
+  offset: 40,
+});
+```
+
+## Relations
+
+References are just fields — a self-describing `{ collection, id }`, a bare id
+string, or an array of either. Resolve them after a fetch with `resolveRelations`
+(engine-side, works over any adapter):
+
+```ts
+import { resolveRelations } from "@dalgoridim/headless-cms/server";
+
+const posts = await data.fetchCollection("posts");
+await resolveRelations(data, posts, {
+  populate: ["authorId"],
+  relations: { authorId: { collection: "authors" } }, // needed for bare-id refs
+});
+// each post.authorId is now the resolved author document
+```
+
+Loads are deduplicated and parallelized; unresolved refs are left untouched.
 
 ## Postgres (hybrid)
 
@@ -136,35 +280,81 @@ import { PostgresDataAdapter } from "@dalgoridim/headless-cms/adapters/postgres"
 const data = new PostgresDataAdapter({
   connectionString: process.env.DATABASE_URL!,
   collections: {
-    projects: { table: "projects", columns: { title: "text", date: "date" } },
+    projects: { table: "projects", columns: { title: "text", views: "int", date: "date" } },
   },
 });
 await data.migrate(); // creates documents + registered tables if missing
 ```
 
-## Content markup
+> **Caveat:** fields in the schemaless JSONB `documents` table are extracted as
+> **text**, so numeric ordering/comparison is lexicographic (`"10" < "5"`).
+> Register the collection with a typed `int`/`float` column for true numeric
+> behavior.
 
-`ContentEditSpan` supports inline marks: `**bold**`, `*italic*`, `~~strike~~`,
-`^^primary color^^`, `__underline__`, `~~br~~`, and `[label](https://url)`.
-`MarkdownEditor` provides full GitHub-flavored markdown editing.
+## Auth: the gate is yours
 
-## Styling
+`AuthIdentity` is intentionally minimal and open — only `isAdmin` is meaningful to
+the default gate; carry any other claims and authorize on them yourself.
 
-The client components ship **Tailwind utility classes** (and use a `--color-primary`
-custom property / `text-primary` utility for accents). The consuming app is
-responsible for Tailwind. With Tailwind v4, point it at the package so those
-classes are generated, and define a primary color:
+```ts
+interface AuthIdentity {
+  isAdmin: boolean;
+  userId?: string;
+  email?: string;
+  [claim: string]: unknown;   // roles, scopes, tenant, …
+}
+```
 
-```css
-/* globals.css */
-@import "tailwindcss";
-@source "../node_modules/@dalgoridim/headless-cms/dist";
+Pass an `authorize` predicate to gate on whatever you like (defaults to
+`identity.isAdmin === true`):
 
-@theme inline {
-  --color-primary: var(--primary);
-}
+```ts
+createCmsHandlers({
+  data,
+  auth,
+  authorize: (identity) => identity.role === "editor" || identity.isAdmin,
+});
+```
+
+## Your content types stay unconstrained
+
+The engine only adds addressing fields; your domain type `T` is never forced to
+declare them:
+
+```ts
+import type { Editable } from "@dalgoridim/headless-cms";
+
+interface Post { title: string; body: string }   // your shape — clean
+type StoredPost = Editable<Post>;                 // Post & { id: string; collection: string }
 ```
 
+## Styling: bring your own look
+
+The package ships **no styles**. Skin the primitives in your app — for example, a
+thin wrapper that applies your design system:
+
+```tsx
+// components/EditableTitle.tsx
+import { ContentEditSpan } from "@dalgoridim/headless-cms/client";
+
+export const EditableTitle = (props) => (
+  <ContentEditSpan
+    {...props}
+    className="text-4xl font-bold data-[cms-focused]:ring-2 data-[cms-focused]:ring-blue-500"
+  />
+);
+```
+
+This keeps your design isolated from the engine and lets the package upgrade
+without ever changing how your site looks.
+
+## Documentation
+
+- **[README](./README.md)** — this guide: install and usage.
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** — design rationale and internals
+  (bundle boundaries, backend parity, the hybrid Postgres model, headless UI).
+- **[REDESIGN.md](./REDESIGN.md)** — the "harness, not framework" redesign spec.
+
 ## Build
 
 ```bash
@@ -174,5 +364,5 @@ npm run typecheck  # tsc --noEmit
 
 ## Stability
 
-Pre-`1.0`: the API may change between minor versions as the engine evolves.
-Pin an exact version if you depend on it in production.
+Pre-`1.0`: the API may change between minor versions as the engine evolves. Pin an
+exact version if you depend on it in production.