@backmatter/core 0.0.15 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Experimental Backmatter SDK. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {

package/src/config.ts

@@ -8,6 +8,8 @@ export type BackmatterDirs = {
   models?: string;
   /** Folder with one `defineBlock` default export per file. Default: "blocks". */
   blocks?: string;
+  /** Folder with one in-content `defineBlock` per file. Default: "richtext". */
+  richtext?: string;
   /** Folder with one MDX tag component default export per file. Default: "mdx". */
   mdx?: string;
   /** Folder with one layout default export per model type. Default: "layouts". */
@@ -51,6 +53,7 @@ export type ResolvedConfig = Omit<BackmatterConfig, "dirs" | "defaultLocale"> &
 export const DEFAULT_DIRS: Required<BackmatterDirs> = {
   models: "models",
   blocks: "blocks",
+  richtext: "richtext",
   mdx: "mdx",
   layouts: "layouts",
   objects: "objects",
@@ -159,6 +162,7 @@ export function resolveConfig(
     dirs: {
       models: config.dirs?.models ?? DEFAULT_DIRS.models,
       blocks: config.dirs?.blocks ?? DEFAULT_DIRS.blocks,
+      richtext: config.dirs?.richtext ?? DEFAULT_DIRS.richtext,
       mdx: config.dirs?.mdx ?? DEFAULT_DIRS.mdx,
       layouts: config.dirs?.layouts ?? DEFAULT_DIRS.layouts,
       objects: config.dirs?.objects ?? DEFAULT_DIRS.objects,

package/src/model.ts

@@ -85,6 +85,8 @@ export type SchemaSnapshot = {
   version: number;
   models: ModelSnapshot[];
   blocks?: BlockSnapshot[];
+  /** In-content blocks from `richtext/`. Separate from page-builder `blocks`. */
+  richtext?: BlockSnapshot[];
   objects?: ObjectSnapshot[];
 };
 
@@ -178,6 +180,7 @@ export function serializeSchema(
   models: ModelDef[],
   blocks?: BlockDef[],
   objects?: ObjectDef[],
+  richtext?: BlockDef[],
 ): SchemaSnapshot {
   const snapshot: SchemaSnapshot = {
     version: 1,
@@ -186,6 +189,9 @@ export function serializeSchema(
   if (blocks && blocks.length > 0) {
     snapshot.blocks = blocks.map(serializeBlock);
   }
+  if (richtext && richtext.length > 0) {
+    snapshot.richtext = richtext.map(serializeBlock);
+  }
   if (objects && objects.length > 0) {
     snapshot.objects = objects.map(serializeObject);
   }
@@ -301,6 +307,28 @@ export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
     }
   }
 
+  let richtext: BlockSnapshot[] = [];
+  if (value.richtext !== undefined) {
+    if (!Array.isArray(value.richtext)) {
+      throw new Error("schema.richtext must be an array");
+    }
+    richtext = value.richtext.map((raw, i) => {
+      try {
+        return parseBlockSnapshot(raw);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "invalid block";
+        throw new Error(`schema.richtext[${i}]: ${msg}`);
+      }
+    });
+    const richtextNames = new Set<string>();
+    for (const block of richtext) {
+      if (richtextNames.has(block.name)) {
+        throw new Error(`duplicate richtext block name: ${block.name}`);
+      }
+      richtextNames.add(block.name);
+    }
+  }
+
   let objects: ObjectSnapshot[] = [];
   if (value.objects !== undefined) {
     if (!Array.isArray(value.objects)) {
@@ -323,5 +351,11 @@ export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
     }
   }
 
-  return { version, models, blocks, objects };
+  return {
+    version,
+    models,
+    blocks,
+    ...(richtext.length > 0 ? { richtext } : {}),
+    objects,
+  };
 }

package/src/node/cli.ts

@@ -234,8 +234,10 @@ export async function runGenerate(args: CliArgs): Promise<GenerateResult> {
     root,
     modelsDir: config.dirs.models,
     blocksDir: config.dirs.blocks,
+    richtextDir: config.dirs.richtext,
     mdxDir: config.dirs.mdx,
     layoutsDir: config.dirs.layouts,
+    objectsDir: config.dirs.objects,
   });
 }
 
@@ -247,8 +249,9 @@ function renderConfigFile(sdk: string): string {
 import { defineConfig } from "${from}";
 
 // General settings only. Models live in models/*.ts, composer blocks in
-// blocks/*.tsx, MDX tags in mdx/*.tsx, and content in
-// content/{locale}/{type}/{slug}.{mdx,json} — all discovered automatically.
+// blocks/*.tsx, in-content blocks in richtext/*.tsx, MDX tags in mdx/*.tsx,
+// and content in content/{locale}/{type}/{slug}.{mdx,json} — all discovered
+// automatically.
 // Set workspaceId from General settings (not an env var).
 // API URL defaults to https://api.backmatter.app in production; tokens stay env.
 export default defineConfig({
@@ -263,11 +266,13 @@ function renderCatchAllPage(registryImport: string): string {
 import { cacheLife } from "next/cache";
 import { createCatchAll } from "@backmatter/next/routes";
 import { cms } from "${registryImport}";
-import { components } from "${registryImport}/mdx";
+import { components as mdxComponents } from "${registryImport}/mdx";
+import { richtextComponents } from "${registryImport}/richtext";
 import { blockLoaders } from "${registryImport}/blocks";
 import { blockFallbacks } from "${registryImport}/block-fallbacks";
 import { layouts } from "${registryImport}/layouts";
 
+const components = { ...richtextComponents, ...mdxComponents };
 const route = createCatchAll(cms, { components, blocks: blockLoaders, fallbacks: blockFallbacks, layouts });
 
 export const generateStaticParams = route.generateStaticParams;
@@ -451,7 +456,7 @@ export async function runInit(args: CliArgs): Promise<string[]> {
     notes.push("no @backmatter/next dependency: skipped the catch-all route");
   }
 
-  for (const dir of ["models", "content", "blocks", "mdx", "layouts"]) {
+  for (const dir of ["models", "content", "blocks", "richtext", "mdx", "layouts"]) {
     await mkdir(path.join(root, dir), { recursive: true });
   }
 

package/src/node/create-backmatter.ts

@@ -18,6 +18,8 @@ export type CreateBackmatterOptions<Models extends readonly ModelDef[] = readonl
   BackmatterConfig & {
     models: Models;
     blocks?: readonly BlockDef[];
+    /** In-content blocks (`richtext/*.tsx`). Synced separately from page blocks. */
+    richtext?: readonly BlockDef[];
     objects?: readonly ObjectDef[];
     /**
      * When true, API fetches use Next cache tags instead of `cache: "no-store"`.
@@ -67,7 +69,7 @@ function toSnapshots(models: readonly ModelDef[]): ModelSnapshot[] {
 export function createBackmatter<const Models extends readonly ModelDef[]>(
   options: CreateBackmatterOptions<Models>,
 ): BackmatterClient<Models> {
-  const { models: modelDefs, blocks: blockDefs, objects: objectDefs, taggedApiFetch, sync = true, ...rest } = options;
+  const { models: modelDefs, blocks: blockDefs, richtext: richtextDefs, objects: objectDefs, taggedApiFetch, sync = true, ...rest } = options;
   const config = resolveConfig(rest);
   const models = toSnapshots(modelDefs);
   const siteRoot = config.siteRoot ?? process.cwd();
@@ -91,6 +93,7 @@ export function createBackmatter<const Models extends readonly ModelDef[]>(
         hostToken,
         models: [...modelDefs],
         blocks: blockDefs ? [...blockDefs] : undefined,
+        richtext: richtextDefs ? [...richtextDefs] : undefined,
         objects: objectDefs ? [...objectDefs] : undefined,
         branch: config.branch,
         siteUrl,

package/src/node/generate.ts

@@ -31,6 +31,7 @@ export type GenerateOptions = {
   outDir?: string;
   modelsDir?: string;
   blocksDir?: string;
+  richtextDir?: string;
   mdxDir?: string;
   layoutsDir?: string;
   objectsDir?: string;
@@ -59,6 +60,7 @@ export type GenerateResult = {
   changed: string[];
   models: ModelFile[];
   blocks: BlockFile[];
+  richtext: BlockFile[];
   mdx: BlockFile[];
   layouts: ModelFile[];
   objects: ModelFile[];
@@ -161,11 +163,13 @@ export function renderSyncBarrel(input: {
   outDir: string;
   models: ModelFile[];
   blocks: BlockFile[];
+  richtext?: BlockFile[];
   objects?: ModelFile[];
   configFile: string | null;
   sdk: string;
 }): string {
   const objects = input.objects ?? [];
+  const richtext = input.richtext ?? [];
   const lines = [GENERATED_HEADER, `import { createBackmatter } from "${input.sdk}";`];
   if (input.configFile) {
     lines.push(`import config from "${importSpecifier(input.outDir, input.configFile)}";`);
@@ -178,6 +182,9 @@ export function renderSyncBarrel(input: {
   for (const b of input.blocks) {
     lines.push(`import ${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
   }
+  for (const b of richtext) {
+    lines.push(`import richtext${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
+  }
   for (const object of objects) {
     lines.push(`import ${object.importName} from "${importSpecifier(input.outDir, object.file)}";`);
   }
@@ -187,10 +194,16 @@ export function renderSyncBarrel(input: {
   lines.push("");
   lines.push(`export const blocks = [${input.blocks.map((b) => b.name).join(", ")}] as const;`);
   lines.push("");
+  lines.push(
+    `export const richtext = [${richtext.map((b) => `richtext${b.name}`).join(", ")}] as const;`,
+  );
+  lines.push("");
   lines.push(`export const objects = [${objects.map((o) => o.importName).join(", ")}] as const;`);
   lines.push("");
   lines.push("/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */");
-  lines.push("export const cms = createBackmatter({ ...config, models, blocks, objects, sync: true });");
+  lines.push(
+    "export const cms = createBackmatter({ ...config, models, blocks, richtext, objects, sync: true });",
+  );
   return `${lines.join("\n")}\n`;
 }
 
@@ -206,6 +219,18 @@ export function renderMdxBarrel(input: { outDir: string; mdx: BlockFile[] }): st
   return `${lines.join("\n")}\n`;
 }
 
+export function renderRichtextBarrel(input: { outDir: string; richtext: BlockFile[] }): string {
+  const lines = [GENERATED_HEADER];
+  for (const b of input.richtext) {
+    lines.push(`import ${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
+  }
+  lines.push("");
+  lines.push("/** In-content blocks: <Image /> in MDX resolves to richtext/Image.tsx. */");
+  const entries = input.richtext.map((b) => `${b.name}: ${b.name}.component`);
+  lines.push(`export const richtextComponents = ${entries.length ? `{ ${entries.join(", ")} }` : "{}"};`);
+  return `${lines.join("\n")}\n`;
+}
+
 export function renderBlocksBarrel(input: { outDir: string; blocks: BlockFile[] }): string {
   const lines = [GENERATED_HEADER, ""];
   lines.push('/** Composer loaders: JSON `{ type: "Hero" }` → dynamic import of blocks/Hero.tsx. */');
@@ -257,6 +282,7 @@ export const REGISTRY_FILES = [
   "blocks.ts",
   "block-fallbacks.ts",
   "mdx.ts",
+  "richtext.ts",
   "layouts.ts",
   "sync.ts",
 ] as const;
@@ -269,6 +295,10 @@ export function generate(options: GenerateOptions): GenerateResult {
     root,
     options.blocksDir ?? DEFAULT_DIRS.blocks,
   );
+  const { blocks: richtext, skipped: skippedRichtext } = listBlockFiles(
+    root,
+    options.richtextDir ?? DEFAULT_DIRS.richtext,
+  );
   const fallbacks = listBlockFallbackFiles(root, options.blocksDir ?? DEFAULT_DIRS.blocks);
   const { blocks: mdx, skipped: skippedMdx } = listMdxFiles(
     root,
@@ -285,8 +315,9 @@ export function generate(options: GenerateOptions): GenerateResult {
     "blocks.ts": renderBlocksBarrel({ outDir, blocks }),
     "block-fallbacks.ts": renderBlockFallbacksBarrel({ outDir, fallbacks }),
     "mdx.ts": renderMdxBarrel({ outDir, mdx }),
+    "richtext.ts": renderRichtextBarrel({ outDir, richtext }),
     "layouts.ts": renderLayoutsBarrel({ outDir, layouts }),
-    "sync.ts": renderSyncBarrel({ outDir, models, blocks, objects, configFile, sdk }),
+    "sync.ts": renderSyncBarrel({ outDir, models, blocks, richtext, objects, configFile, sdk }),
   };
   const outputs: GeneratedFile[] = REGISTRY_FILES.map((name) => {
     const file = path.join(outDir, name);
@@ -304,10 +335,11 @@ export function generate(options: GenerateOptions): GenerateResult {
     changed: outputs.filter((o) => o.changed).map((o) => o.rel),
     models,
     blocks,
+    richtext,
     mdx,
     layouts,
     objects,
-    skippedBlocks,
+    skippedBlocks: [...skippedBlocks, ...skippedRichtext],
     skippedMdx,
     configFile,
   };

package/src/node/index.ts

@@ -32,6 +32,7 @@ export {
   renderBlocksBarrel,
   renderLayoutsBarrel,
   renderMdxBarrel,
+  renderRichtextBarrel,
   renderModelsBarrel,
   renderSyncBarrel,
   DEFAULT_OUT_DIR,

package/src/sync-schema.ts

@@ -23,6 +23,8 @@ export type SyncSchemaOptions = {
   hostToken: string;
   models: Array<ModelDef | ModelSnapshot>;
   blocks?: BlockDef[];
+  /** In-content blocks from the client `richtext/` directory. */
+  richtext?: BlockDef[];
   objects?: ObjectDef[];
   branch?: string;
   siteUrl?: string;
@@ -34,6 +36,7 @@ export async function syncSchema(options: SyncSchemaOptions): Promise<void> {
     options.models as ModelDef[],
     options.blocks,
     options.objects,
+    options.richtext,
   );
   const body: { payload: ReturnType<typeof serializeSchema>; branch: string; siteUrl?: string } = {
     payload,