@dalgoridim/headless-cms 0.2.0 → 0.2.1

package/ARCHITECTURE.md

@@ -1,8 +1,7 @@
 # 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).
+see the [README](./README.md).
 
 ## Philosophy: harness, not framework
 

package/README.md

@@ -13,6 +13,11 @@ You build a thin skin over the primitives (see [Styling](#styling-bring-your-own
 the package never pushes a look onto your site. The design rationale and internals
 live in [ARCHITECTURE.md](./ARCHITECTURE.md).
 
+**Live example:** [dalgoridim.com](https://dalgoridim.com) runs on this package.
+Try it: anyone can toggle edit mode and change the content inline, right on the
+page — but saves are gated, so only the authenticated owner's edits actually
+persist. Your changes are yours alone to play with.
+
 ## Install
 
 ```bash
@@ -353,7 +358,6 @@ without ever changing how your site looks.
 - **[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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalgoridim/headless-cms",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Database-agnostic, inline-edit headless CMS engine for React / Next.js apps",
   "license": "UNLICENSED",
   "author": "dalgoridim",
@@ -96,13 +96,14 @@
   },
   "files": [
     "dist",
-    "ARCHITECTURE.md",
-    "REDESIGN.md"
+    "ARCHITECTURE.md"
   ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepare": "tsup"
   },
   "peerDependencies": {
@@ -155,6 +156,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsup": "^8.5.1",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   }
 }

package/REDESIGN.md

@@ -1,250 +0,0 @@
-# Headless CMS — "Harness, Not Framework" Redesign
-
-> Full spec for the "harness, not framework" redesign. Living document — kept in
-> sync as the two tracks land.
-
-## Context
-
-`@dalgoridim/headless-cms` was extracted from `portfolio-2025`. An audit of what
-the package *forces* on its consumers found two layers with opposite philosophies:
-
-- **Data / server layer — already free.** `Section` is schemaless
-  (`{ id, collection, [key]: any }`), the Postgres adapter never drops unmapped
-  fields (JSONB `documents` fallback + `extra` column), and `DataAdapter` is
-  generic. Good.
-- **UI / client layer — a framework, not a harness.** The components ship a
-  finished, portfolio-specific look and hard dependencies. A consumer adopting
-  the package today **inherits portfolio-2025's visual design** and is forced
-  into Tailwind, a dark `neutral` palette, a `primary` design token,
-  `lucide-react`, `sonner`, and a bespoke text-mark syntax.
-
-The goal: make the **whole** package a harness — wire behavior, impose nothing.
-Two tracks, shipped together:
-
-- **Track A** — de-framework-ize the UI (the philosophy fix; highest impact).
-- **Track B** — close the four data-layer capability gaps (query power,
-  relations, loosened `id`/`collection`, auth flexibility).
-
-### Decisions locked in with the user
-- Package goes **pure headless**; the current dark/Tailwind look is **moved into
-  portfolio-2025's own shim components**, not kept in the package.
-- API optimized for **DX**: `className`/`style` passthrough + `data-*` state
-  attributes + injectable deps (icons / notifier / markup parser); render-props
-  / `asChild` only where it genuinely improves control.
-- **Both tracks in one pass.**
-
-### Guiding principles (apply to every change)
-1. Ship **unstyled** by default — no Tailwind, no palette, no `primary` token.
-2. Expose **styling hooks** — `className`, `style`, `data-*` state attributes,
-   and render-props/`asChild` for complex chrome.
-3. Make deps **injectable, not baked** — icons, toasts, markup parser.
-4. **No portfolio-specific code** in the package.
-5. Never silently break portfolio — package + portfolio shims change in lockstep.
-
----
-
-## Current forcing inventory (what we are removing)
-
-| Forced thing | Location | Resolution |
-|---|---|---|
-| Tailwind mandatory (`cn`, utility strings) | all client components, `client/utils.ts` | Strip utility strings; `cn`/`tailwind-merge` leaves core. |
-| Dark `neutral` palette + ring offsets | `ContentEditSpan`, `EditableImage`, `MarkdownEditor` | Move to portfolio shims. |
-| `primary` token (`var(--color-primary)`, `bg-primary`) | `ContentEditSpan.tsx:103`, `EditableImage`, `MarkdownEditor` | Removed from package; portfolio keeps it in its shims. |
-| `lucide-react` + `sonner` baked in | `EditableImage`, `MarkdownEditor`, `PageProvider` default notifier | Drop from hard deps; inject; portfolio supplies them. |
-| Bespoke text-mark syntax (`^^primary^^`, `~~br~~`, `__underline__`) | `ContentEditSpan.tsx:30` `PATTERNS` | Make parser/renderer injectable with a default. |
-| Portfolio leftovers: `collection = "portfolio"` default, `ProjectContentEditor` | `ContentEditSpan.tsx:151`, `MarkdownEditor.tsx:293` | Delete from package; move `ProjectContentEditor` to portfolio. |
-| Hardcoded English copy | `EditableImage`, `MarkdownEditor` | Replace with props/children defaults. |
-| `id` + `collection` forced on content type | `types.ts:12` | Split internal addressing from user's `T` (Track B3). |
-| Tiny query language | `types.ts:48` | Extend neutrally (Track B1). |
-| `AuthIdentity` forces `userId`+`isAdmin` | `types.ts:92` | Minimal contract + open payload + `authorize` predicate (Track B4). |
-
----
-
-## Track A — Headless UI
-
-### A1. `PageProvider` (`src/client/PageProvider.tsx`)
-- `Notifier` is already injectable — keep. **Change the default** from a `sonner`
-  toast sink to a dependency-free console/no-op default so `sonner` is no longer
-  required. Portfolio passes a sonner-backed notifier from its shim.
-- No other behavior change; this file is mostly backend-agnostic already.
-
-### A2. `ContentEditSpan` (`src/client/ContentEditSpan.tsx`)
-- Remove `collection = "portfolio"` default → `collection` becomes required (or
-  resolved from an optional provider-level default-collection context).
-- Extract the `PATTERNS` parser + `RenderStatic` into an **injectable markup
-  contract**: `parse(raw) => Node[]` + `render(nodes)`, defaulted to the current
-  implementation but overridable via prop or a `CmsMarkupContext`. Consumers who
-  want plain text or their own DSL drop in their own.
-- Strip all Tailwind/`primary`/`neutral` classes. Keep `className` passthrough.
-  Emit **state via data attributes**: `data-cms-editable`, `data-editing`,
-  `data-focused` so consumers style with their own CSS.
-- Keep the `as` prop; add `asChild` (lightweight Slot) so the consumer can supply
-  their own element/markup while the primitive wires `contentEditable`.
-
-### A3. `EditableImage` (`src/client/EditableImage.tsx`)
-- Keep the upload/url/pending-image behavior (it's correct and engine-wired).
-- Remove `lucide` icons and all dark modal/overlay styling. Expose a
-  **render-prop API**: the component manages state and hands the consumer
-  `{ src, isEditing, saving, openFilePicker, setUrl, error }`; the consumer
-  renders the overlay/modal. Provide a minimal **unstyled default** render so the
-  simple case still works without writing chrome.
-- Placeholder ("No image available") and modal copy become props/children.
-
-### A4. `MarkdownEditor` (`src/client/MarkdownEditor.tsx`)
-- This is the most styled file. Split into:
-  - **Headless core**: editor state + commands (`insertMarkdown`, preview
-    toggle, save/cancel, char count) exposed via hook/render-prop.
-  - The modal chrome, toolbar, icons (`lucide`), markdown guide, and
-    `react-markdown`/`remark-gfm` preview move to **portfolio**.
-- `react-markdown` + `remark-gfm` leave the package's hard deps (preview is a
-  consumer concern; the core only manages text).
-- **Delete `ProjectContentEditor`** from the package (portfolio-specific) → move
-  to portfolio.
-
-### A5. `client/utils.ts` + deps
-- `cn` relies on `tailwind-merge` (Tailwind-specific). Drop `tailwind-merge` from
-  the package; either remove `cn` from the public API or reduce it to a plain
-  `clsx` join. Tailwind-specific merging belongs in portfolio.
-
-### A6. `package.json` dependency surgery
-Move out of hard `dependencies` (→ removed from package; portfolio installs):
-`lucide-react`, `react-markdown`, `remark-gfm`, `sonner`, `tailwind-merge`.
-Keep only genuinely shared, non-opinion runtime deps (`clsx` at most). Update
-`client/index.ts` exports (remove `ProjectContentEditor`; keep `cn` only if
-retained).
-
----
-
-## Track B — Data-layer freedom
-
-Touch points: `src/types.ts`, `src/adapters/postgres/index.ts`,
-`src/adapters/firestore/index.ts` (read during impl), `src/server/*`.
-
-### B1. Query power (`types.ts:48`, both adapters)
-Extend the neutral `Query` without leaking any backend type:
-- Ops: add `ne`, `nin`, `contains` (case-insensitive substring → SQL `ILIKE
-  %v%`), keep existing.
-- **OR groups**: allow `filters` to nest — an `or: Filter[]` group alongside the
-  implicit top-level `AND`.
-- **Pagination**: add `offset` next to `limit`.
-- Implement fully in Postgres (`colExpr`/`OP_MAP` already structured for it).
-  Implement best-effort in Firestore and **throw a clear error** on ops the
-  backend can't honor (e.g. cross-field `OR`, `contains`) rather than returning
-  wrong results. Document the parity matrix.
-
-### B2. Relations (schemaless-friendly)
-- A reference is just a field holding an id (or `{ collection, id }`) or an array
-  of them — no schema change required to store one.
-- Add an optional `populate?: string[]` to `Query` and a neutral resolver in the
-  engine that, after the primary fetch, **batch-loads referenced docs** via an
-  `in` query and inlines them. Backend-agnostic (works on JSONB + Firestore).
-- Optional `RelationConfig` (field → target collection) so refs that are bare ids
-  know where to resolve.
-
-### B3. Loosen `id` / `collection` (`types.ts:12`)
-- Keep `id`/`collection` as the engine's **internal addressing**, but stop
-  forcing them onto the user's content type. Introduce `Editable<T> = T & {
-  id: string; collection: string }` used internally; public APIs accept the
-  user's clean `T`.
-- Make the field names **configurable** at the adapter level (`idField`,
-  `collectionField`) for consumers whose records use `_id` / `slug`.
-
-### B4. Auth flexibility (`types.ts:92`, `server/createAdminGate.ts`)
-- `AuthIdentity` → minimal `{ isAdmin: boolean }` plus an open payload
-  (`[key: string]: unknown`; `userId`/`email` optional).
-- `verifyRequest` may return any identity shape; the gate authorizes via an
-  injectable `authorize(identity, req) => boolean` predicate, **defaulting** to
-  `identity.isAdmin === true`. Lets consumers gate on roles/scopes without the
-  fixed contract.
-- Client `CmsAuthState` stays minimal but becomes extensible.
-
----
-
-## Portfolio-2025 migration (lockstep)
-
-Portfolio consumes the package only through **thin shims**, so the look moves
-there cleanly:
-
-- `lib/context/PageContent.tsx` — pass a **sonner-backed `notify`** to
-  `PageProvider` (restores toasts).
-- `components/customs/ContentEditSpan.tsx` — wrap the headless primitive,
-  re-apply the dark ring/`primary` Tailwind classes and the default `collection`.
-- `components/customs/EditableImage.tsx` — supply the styled overlay/modal +
-  `lucide` icons via the render-prop.
-- `components/customs/MarkdownEditor.tsx` — supply the modal chrome, toolbar,
-  `lucide` icons, `react-markdown` preview, guide; **define `ProjectContentEditor`
-  here**.
-- Install in portfolio what left the package: `lucide-react`, `sonner`,
-  `react-markdown`, `remark-gfm`, `tailwind-merge` (most already present).
-- `lib/cms/server.ts` / auth shim — adjust only if `AuthIdentity` field changes
-  ripple (expected: none, contract is widened not narrowed).
-
-Portfolio's `app/globals.css` already defines `--primary` / `--color-primary`,
-so its shims keep the exact current look.
-
----
-
-## Sequencing (so nothing breaks mid-flight)
-
-1. **Track B** first (additive, low-risk): `types.ts` Query/Auth widening, then
-   Postgres + Firestore adapter impls. Widening contracts won't break portfolio.
-2. **Track A** package changes: provider default notifier, headless
-   ContentEditSpan / EditableImage / MarkdownEditor, dep surgery, exports.
-3. **Portfolio shims** updated in the same change set to restore look + behavior.
-4. Drop this doc into the package root as `REDESIGN.md`.
-
----
-
-## Verification
-
-- **Package**: `npm run build` (tsup) and `npm run typecheck` in
-  `headless-cms` — both clean.
-- **Portfolio typecheck/build**: `npm run build` in `portfolio-2025` resolves all
-  shims against the new headless API.
-- **Postgres proof** (also a memory milestone): run `scripts/seed-postgres.ts`,
-  then exercise new query ops (`contains`, `or`, `offset`) and a `populate`
-  round-trip against the local `documents` table.
-- **Manual UI** (`/verify` or `/run`): in portfolio admin/edit mode, confirm
-  inline text edit, image upload + external-URL, and the markdown modal all still
-  look and behave as before — proving the look fully survived the move to shims.
-- **Headless smoke**: render `ContentEditSpan` / `EditableImage` with **no**
-  Tailwind/styles to confirm they work unstyled (harness proof).
-
-## Open risks
-- **Firestore query parity** — it cannot honor cross-field `OR` / `contains`
-  generally. Plan: throw explicit "unsupported by this adapter" errors and ship a
-  documented parity matrix rather than silent wrong results.
-- **`asChild`/render-prop surface** — adds API; mitigated by keeping unstyled
-  defaults so trivial cases stay one-liners.
-
----
-
-## Status (landed)
-
-- **Track B1 (query power)** — done. `QueryFilterOp` gains `ne`/`nin`/`contains`;
-  `Query` gains OR groups (`{ or: [...] }`) and `offset`. Postgres implements all;
-  Firestore throws clear errors on `contains` / OR groups.
-- **Track B2 (relations)** — done. `resolveRelations(adapter, docs, opts)` in
-  `src/server/relations.ts` (exported from `/server`); `Query.populate`,
-  `Ref`, `RelationConfig` added.
-- **Track B3 (id/collection)** — **type-level done** (`Editable<T>` +
-  `EntityAddress`; `T` unconstrained). **Deferred:** per-adapter configurable
-  physical `idField`/`collectionField` renaming — bigger SQL change, left as a
-  follow-up to avoid destabilizing the working schemaless path.
-- **Track B4 (auth)** — done. `AuthIdentity` widened to `{ isAdmin } + open
-  payload`; injectable `AuthorizeFn` on `createAdminGate` / `createCmsHandlers`.
-- **Track A (headless UI)** — done. `ContentEditSpan` (injectable `renderValue`,
-  `data-cms-*` attrs, no styles), `EditableImage` (render-prop), `MarkdownEditor`
-  → `useMarkdownEditor` hook. Removed `ProjectContentEditor`, `cn`/`utils.ts`,
-  and all of `lucide-react`/`sonner`/`react-markdown`/`remark-gfm`/`tailwind-merge`
-  from package deps (now **zero** runtime deps).
-- **Portfolio shims** — restyled to restore the exact look: `ContentEditSpan`,
-  `EditableImage`, `MarkdownEditor`+`ProjectContentEditor`, sonner `notify`.
-
-Verified: package `typecheck` + `build` clean; portfolio `tsc --noEmit` clean
-against the new API; portfolio **production build passes** (firebase mode, all
-routes); **Postgres round-trip 12/12** — `contains`, OR groups, `ne`/`nin`,
-`offset`+order (text + typed numeric), and `populate` via `RelationConfig`.
-Caveat surfaced: numeric fields in the schemaless JSONB `documents` table order
-as text (`data->>` is text); register a typed collection for true numeric
-ordering/comparison. Not yet run: manual edit-mode UI pass (needs admin login).