koguma 0.4.5 → 0.5.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koguma",
-  "version": "0.4.5",
+  "version": "0.5.0-rc.1",
   "description": "🐻 A little CMS with big heart — schema-driven, runs on Cloudflare's free tier",
   "type": "module",
   "license": "MIT",
@@ -47,12 +47,27 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "hono": "^4.0.0"
+    "hono": "^4.0.0",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260304.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
     "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "concurrently": "^9.2.1",
+    "happy-dom": "^17.4.4",
     "miniflare": "^4.20260301.1",
     "typescript": "^5.7.0",
     "wrangler": "^4.71.0"

package/src/config/field.ts

@@ -9,23 +9,23 @@
  *   field.image("Hero Photo")
  *   field.refs("featureCard", "Highlights")
  */
-import { z } from "zod/v4";
-import type { KogumaAsset, RichTextDocument, EntryReference } from "./types.ts";
+import { z } from 'zod/v4';
+import type { KogumaAsset, KogumaDocument, EntryReference } from './types.ts';
 
 // ── Field metadata (extracted by the admin + schema generator) ──────
 
 export type FieldType =
-  | "text"
-  | "longText"
-  | "richText"
-  | "url"
-  | "image"
-  | "boolean"
-  | "number"
-  | "date"
-  | "select"
-  | "reference"
-  | "references";
+  | 'text'
+  | 'longText'
+  | 'richText'
+  | 'url'
+  | 'image'
+  | 'boolean'
+  | 'number'
+  | 'date'
+  | 'select'
+  | 'reference'
+  | 'references';
 
 export interface FieldMeta {
   label: string;
@@ -82,7 +82,10 @@ export class FieldBuilder<T extends z.ZodType = z.ZodType> {
 
   /** Set a default value */
   default(value: z.infer<T>): FieldBuilder {
-    return new FieldBuilder((this._schema as z.ZodType).default(value as never), this._meta);
+    return new FieldBuilder(
+      (this._schema as z.ZodType).default(value as never),
+      this._meta
+    );
   }
 }
 
@@ -91,76 +94,85 @@ export class FieldBuilder<T extends z.ZodType = z.ZodType> {
 export const field = {
   /** Short text field */
   text(label: string) {
-    return new FieldBuilder(
-      z.string().optional().describe(label),
-      { label, fieldType: "text", required: false },
-    );
+    return new FieldBuilder(z.string().optional().describe(label), {
+      label,
+      fieldType: 'text',
+      required: false
+    });
   },
 
   /** Multi-line text field */
   longText(label: string) {
-    return new FieldBuilder(
-      z.string().optional().describe(label),
-      { label, fieldType: "longText", required: false },
-    );
+    return new FieldBuilder(z.string().optional().describe(label), {
+      label,
+      fieldType: 'longText',
+      required: false
+    });
   },
 
-  /** Rich text field (Tiptap JSON document) */
+  /** Rich text field (Lexical rich text document) */
   richText(label: string) {
     return new FieldBuilder(
-      z.custom<RichTextDocument>().optional().describe(label),
-      { label, fieldType: "richText", required: false },
+      z.custom<KogumaDocument>().optional().describe(label),
+      { label, fieldType: 'richText', required: false }
     );
   },
 
   /** URL field with validation */
   url(label: string) {
-    return new FieldBuilder(
-      z.string().url().optional().describe(label),
-      { label, fieldType: "url", required: false },
-    );
+    return new FieldBuilder(z.string().url().optional().describe(label), {
+      label,
+      fieldType: 'url',
+      required: false
+    });
   },
 
   /** Image/media field (reference to R2 asset) */
   image(label: string) {
     return new FieldBuilder(
       z.custom<KogumaAsset>().optional().describe(label),
-      { label, fieldType: "image", required: false },
+      { label, fieldType: 'image', required: false }
     );
   },
 
   /** Boolean toggle */
   boolean(label: string) {
-    return new FieldBuilder(
-      z.boolean().optional().describe(label),
-      { label, fieldType: "boolean", required: false },
-    );
+    return new FieldBuilder(z.boolean().optional().describe(label), {
+      label,
+      fieldType: 'boolean',
+      required: false
+    });
   },
 
   /** Numeric field */
   number(label: string) {
-    return new FieldBuilder(
-      z.number().optional().describe(label),
-      { label, fieldType: "number", required: false },
-    );
+    return new FieldBuilder(z.number().optional().describe(label), {
+      label,
+      fieldType: 'number',
+      required: false
+    });
   },
 
   /** Date field */
   date(label: string) {
-    return new FieldBuilder(
-      z.string().datetime().optional().describe(label),
-      { label, fieldType: "date", required: false },
-    );
+    return new FieldBuilder(z.string().datetime().optional().describe(label), {
+      label,
+      fieldType: 'date',
+      required: false
+    });
   },
 
   /** Dropdown select */
   select(label: string, opts: { options: string[] }) {
-    const enumSchema = z.enum(opts.options as [string, ...string[]]).optional().describe(label);
+    const enumSchema = z
+      .enum(opts.options as [string, ...string[]])
+      .optional()
+      .describe(label);
     return new FieldBuilder(enumSchema, {
       label,
-      fieldType: "select",
+      fieldType: 'select',
       required: false,
-      options: opts.options,
+      options: opts.options
     });
   },
 
@@ -168,7 +180,12 @@ export const field = {
   ref(contentType: string, label: string) {
     return new FieldBuilder(
       z.custom<EntryReference>().optional().describe(label),
-      { label, fieldType: "reference", required: false, refContentType: contentType },
+      {
+        label,
+        fieldType: 'reference',
+        required: false,
+        refContentType: contentType
+      }
     );
   },
 
@@ -176,7 +193,12 @@ export const field = {
   refs(contentType: string, label: string) {
     return new FieldBuilder(
       z.array(z.custom<EntryReference>()).optional().describe(label),
-      { label, fieldType: "references", required: false, refContentType: contentType },
+      {
+        label,
+        fieldType: 'references',
+        required: false,
+        refContentType: contentType
+      }
     );
-  },
+  }
 };

package/src/config/index.ts

@@ -20,7 +20,19 @@ export { field } from './field.ts';
 export type { FieldBuilder, FieldType, FieldMeta } from './field.ts';
 
 // Runtime types
-export type { KogumaAsset, RichTextDocument, EntryReference } from './types.ts';
+export type {
+  KogumaAsset,
+  KogumaDocument,
+  KogumaBlockNode,
+  KogumaInlineNode,
+  KogumaListItem,
+  KogumaTableRow,
+  KogumaTableCell,
+  EntryReference
+} from './types.ts';
+
+// Rich text utilities
+export { richTextToPlain } from '../rich-text/index.ts';
 
 // Meta registry (for dev tools like the Schema Builder)
 export { fieldRegistry, fieldSuggestions } from './meta.ts';

package/src/config/types.ts

@@ -1,6 +1,6 @@
 /**
  * Core CMS types used across Koguma.
- * These are the runtime types for assets and rich text — not Zod schemas.
+ * These are the runtime types for assets, rich text, and references.
  */
 
 /** A media asset stored in R2 */
@@ -13,20 +13,100 @@ export interface KogumaAsset {
   height?: number;
 }
 
-/** A Tiptap/ProseMirror-compatible rich text document */
-export interface RichTextDocument {
-  type: "doc";
-  content: RichTextNode[];
+// ── Rich Text ─────────────────────────────────────────────────────────
+
+/**
+ * A koguma-normalized rich text document.
+ * Editor-agnostic — does not expose Lexical internals.
+ * Produced server-side from Lexical's SerializedEditorState.
+ */
+export interface KogumaDocument {
+  nodes: KogumaBlockNode[];
 }
 
-export interface RichTextNode {
-  type: string;
-  content?: RichTextNode[];
-  text?: string;
-  marks?: { type: string; attrs?: Record<string, unknown> }[];
-  attrs?: Record<string, unknown>;
+export type KogumaBlockNode =
+  | {
+      type: 'paragraph';
+      key?: string;
+      align?: 'left' | 'center' | 'right' | 'justify';
+      children: KogumaInlineNode[];
+    }
+  | {
+      type: 'heading';
+      key?: string;
+      level: 1 | 2 | 3 | 4 | 5 | 6;
+      children: KogumaInlineNode[];
+    }
+  | { type: 'list'; key?: string; ordered: boolean; items: KogumaListItem[] }
+  | { type: 'quote'; key?: string; children: KogumaInlineNode[] }
+  | { type: 'code'; key?: string; language?: string; text: string }
+  | {
+      type: 'image';
+      key?: string;
+      url: string;
+      alt?: string;
+      width?: number;
+      height?: number;
+    }
+  | { type: 'hr'; key?: string }
+  | { type: 'table'; key?: string; rows: KogumaTableRow[] }
+  | { type: 'layout'; key?: string; columns: KogumaBlockNode[][] }
+  | {
+      type: 'custom';
+      key?: string;
+      name: string;
+      data: Record<string, unknown>;
+    };
+
+/** A list item — supports nesting and checklists */
+export interface KogumaListItem {
+  key?: string;
+  children: KogumaInlineNode[];
+  /** Defined = checklist item. true = checked, false = unchecked */
+  checked?: boolean;
+  nestedList?: { ordered: boolean; items: KogumaListItem[] };
 }
 
+export interface KogumaTableRow {
+  key?: string;
+  isHeader?: boolean;
+  cells: KogumaTableCell[];
+}
+
+export interface KogumaTableCell {
+  key?: string;
+  children: KogumaInlineNode[];
+}
+
+export type KogumaInlineNode =
+  | {
+      type: 'text';
+      key?: string;
+      text: string;
+      bold?: boolean;
+      italic?: boolean;
+      underline?: boolean;
+      code?: boolean;
+      strikethrough?: boolean;
+      superscript?: boolean;
+      subscript?: boolean;
+    }
+  | {
+      type: 'link';
+      key?: string;
+      url: string;
+      newTab?: boolean;
+      children: KogumaInlineNode[];
+    }
+  | { type: 'inline-image'; key?: string; url: string; alt?: string }
+  | { type: 'line-break'; key?: string }
+  | {
+      type: 'custom';
+      key?: string;
+      name: string;
+      data: Record<string, unknown>;
+    };
+
 /** Reference to another entry */
 export interface EntryReference<T = Record<string, unknown>> {
   id: string;

package/src/db/queries.ts

@@ -6,6 +6,7 @@
  */
 import type { ContentTypeConfig } from '../config/define.ts';
 import type { FieldMeta } from '../config/field.ts';
+import { lexicalToKoguma } from '../rich-text/index.ts';
 
 // ── D1 database interface (Cloudflare Workers binding) ──────────────
 
@@ -60,9 +61,9 @@ export async function getEntry(
   for (const [fieldId, meta] of scalarFields(ct)) {
     if (meta.fieldType === 'richText' && typeof entry[fieldId] === 'string') {
       try {
-        entry[fieldId] = JSON.parse(entry[fieldId] as string);
+        entry[fieldId] = lexicalToKoguma(JSON.parse(entry[fieldId] as string));
       } catch {
-        // leave as string if not valid JSON
+        // leave as-is if not valid JSON
       }
     }
   }
@@ -106,7 +107,9 @@ export async function getEntries(
     for (const [fieldId, meta] of scalarFields(ct)) {
       if (meta.fieldType === 'richText' && typeof entry[fieldId] === 'string') {
         try {
-          entry[fieldId] = JSON.parse(entry[fieldId] as string);
+          entry[fieldId] = lexicalToKoguma(
+            JSON.parse(entry[fieldId] as string)
+          );
         } catch {
           /* skip */
         }