@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/blocks/schema/localized.js

@@ -0,0 +1,53 @@
+// Localized<T>: one value, or one value per locale. Plain strings stay valid, so single-locale
+// and hand-written sites never see locale maps. No React, no zod — safe anywhere.
+export const LOCALE_KEY_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+/** True when `value` is a locale map (`{ en: …, tr: … }`) rather than a value of T. */
+export function isLocaleMap(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every((k) => LOCALE_KEY_RE.test(k));
+}
+const isEmpty = (v) => v === undefined || v === null || v === "";
+const base = (l) => l.split("-")[0].toLowerCase();
+/** The locale chain used by `pickLocale`: exact → base language → each fallback (exact → base). */
+export function localeChain(locale, fallback = ["en"]) {
+    const out = [];
+    for (const l of [locale, ...fallback])
+        for (const c of [l, base(l)])
+            if (!out.includes(c))
+                out.push(c);
+    return out;
+}
+/**
+ * Picks one locale from a `Localized<T>` value. Deterministic: exact locale → its base language →
+ * each fallback → the first non-empty value in insertion order. Empty strings count as missing.
+ *
+ * ```ts
+ * pickLocale({ en: "Book a table", tr: "Masa ayırtın" }, "tr-TR"); // "Masa ayırtın"
+ * pickLocale("Book a table", "tr");                                // "Book a table"
+ * ```
+ */
+export function pickLocale(value, locale, opts = {}) {
+    if (!isLocaleMap(value))
+        return value;
+    const map = value;
+    const lower = {};
+    for (const k in map)
+        lower[k.toLowerCase()] = map[k];
+    for (const l of localeChain(locale, opts.fallback ?? ["en"])) {
+        const v = lower[l.toLowerCase()];
+        if (!isEmpty(v))
+            return v;
+    }
+    for (const k in map)
+        if (!isEmpty(map[k]))
+            return map[k];
+    return Object.values(map)[0];
+}
+/** Locales present (non-empty) in a localized value. A plain value counts as every locale. */
+export function localesOf(value) {
+    if (!isLocaleMap(value))
+        return "all";
+    return Object.keys(value).filter((k) => !isEmpty(value[k]));
+}

package/dist/blocks/schema/migrate.d.ts

@@ -0,0 +1,24 @@
+import type { BlockNode, VamosDoc } from "./types.js";
+import type { AnyBlockDefinition, BlockRegistry } from "./define-block.js";
+export interface MigrationResult {
+    node: BlockNode;
+    from: number;
+    to: number;
+    migrated: boolean;
+    /** Stored with a newer schema than this definition knows: rendered as-is, never downgraded. */
+    newer?: boolean;
+    error?: Error;
+}
+/**
+ * Runs `def.migrate[n]` for every step from the node's `v` (default 1) to `def.version`.
+ * A failing step leaves the node untouched and reports the error — content is never dropped.
+ */
+export declare function migrateNode(node: BlockNode, def: AnyBlockDefinition): MigrationResult;
+/** Document-format migrations: `docMigrations[n]` upgrades a doc from version n to n + 1. */
+export declare const docMigrations: Record<number, (doc: Record<string, unknown>) => Record<string, unknown>>;
+export declare const CURRENT_DOC_VERSION = 1;
+/**
+ * Brings any stored doc to the current format and every block to its current version.
+ * Accepts the plan-06 shape `{ v: 1 }` as an alias of `{ version: 1 }`.
+ */
+export declare function migrateDoc(input: unknown, registry?: BlockRegistry, onResult?: (r: MigrationResult) => void): VamosDoc;

package/dist/blocks/schema/migrate.js

@@ -0,0 +1,75 @@
+// Schema evolution: block props migrate on read (v1 → v2 → …), docs migrate by `version`.
+/**
+ * Runs `def.migrate[n]` for every step from the node's `v` (default 1) to `def.version`.
+ * A failing step leaves the node untouched and reports the error — content is never dropped.
+ */
+export function migrateNode(node, def) {
+    const from = node.v ?? 1;
+    const to = def.version;
+    if (from === to)
+        return { node, from, to, migrated: false };
+    if (from > to)
+        return { node, from, to, migrated: false, newer: true };
+    let props = node.props ?? {};
+    try {
+        for (let n = from; n < to; n++) {
+            const step = def.migrate?.[n];
+            if (!step)
+                throw new Error(`No migration for "${def.type}" v${n} → v${n + 1}.`);
+            props = step(props, node);
+        }
+    }
+    catch (error) {
+        return { node, from, to, migrated: false, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+    return { node: { ...node, v: to, props: props }, from, to, migrated: true };
+}
+/** Document-format migrations: `docMigrations[n]` upgrades a doc from version n to n + 1. */
+export const docMigrations = {};
+export const CURRENT_DOC_VERSION = 1;
+function migrateList(list, registry, onResult) {
+    if (!list)
+        return list;
+    return list.map((node) => {
+        let next = node;
+        const def = registry?.get(node.type);
+        if (def) {
+            const r = migrateNode(node, def);
+            onResult?.(r);
+            next = r.node;
+        }
+        if (next.slots)
+            next = { ...next, slots: Object.fromEntries(Object.entries(next.slots).map(([k, v]) => [k, migrateList(v, registry, onResult)])) };
+        return next;
+    });
+}
+/**
+ * Brings any stored doc to the current format and every block to its current version.
+ * Accepts the plan-06 shape `{ v: 1 }` as an alias of `{ version: 1 }`.
+ */
+export function migrateDoc(input, registry, onResult) {
+    if (!input || typeof input !== "object")
+        throw new TypeError("migrateDoc: expected a document object.");
+    let doc = { ...input };
+    if (doc.version === undefined && typeof doc.v === "number") {
+        doc.version = doc.v;
+        delete doc.v;
+    }
+    let version = typeof doc.version === "number" ? doc.version : 1;
+    while (version < CURRENT_DOC_VERSION) {
+        const step = docMigrations[version];
+        if (!step)
+            throw new Error(`No document migration from version ${version}.`);
+        doc = step(doc);
+        version++;
+    }
+    doc.version = CURRENT_DOC_VERSION;
+    const d = doc;
+    return {
+        ...d,
+        blocks: migrateList(d.blocks ?? [], registry, onResult),
+        ...(d.layout
+            ? { layout: { header: migrateList(d.layout.header, registry, onResult), footer: migrateList(d.layout.footer, registry, onResult), overlay: migrateList(d.layout.overlay, registry, onResult) } }
+            : null),
+    };
+}

package/dist/blocks/schema/nodes.d.ts

@@ -0,0 +1,196 @@
+import { z } from "zod";
+import type { BlockNode, VamosDoc } from "./types.js";
+export declare const ACCENTS: readonly ["lime", "ocean", "ember", "rose", "graphite"];
+export declare const BlockThemeSchema: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+        inherit: "inherit";
+    }>>;
+    surface: z.ZodOptional<z.ZodEnum<{
+        accent: "accent";
+        media: "media";
+        surface: "surface";
+        scene: "scene";
+        "surface-2": "surface-2";
+    }>>;
+    accent: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        lime: "lime";
+        ocean: "ocean";
+        ember: "ember";
+        rose: "rose";
+        graphite: "graphite";
+    }>, z.ZodString]>>;
+    material: z.ZodOptional<z.ZodEnum<{
+        glass: "glass";
+        solid: "solid";
+        inherit: "inherit";
+    }>>;
+    density: z.ZodOptional<z.ZodEnum<{
+        compact: "compact";
+        comfortable: "comfortable";
+        inherit: "inherit";
+    }>>;
+    rhythm: z.ZodOptional<z.ZodEnum<{
+        normal: "normal";
+        loose: "loose";
+        tight: "tight";
+    }>>;
+    background: z.ZodOptional<z.ZodObject<{
+        src: z.ZodString;
+        alt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        blurDataURL: z.ZodOptional<z.ZodString>;
+        focal: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        decorative: z.ZodOptional<z.ZodBoolean>;
+        assetId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Ids: 4–64 chars of `[A-Za-z0-9_-]` (`b_7Hq2`, nanoid, uuid all fit). */
+export declare const BlockIdSchema: z.ZodString;
+export declare const BlockTypeSchema: z.ZodString;
+export declare const AnchorSchema: z.ZodString;
+export declare const ScheduleSchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodISODateTime>;
+    until: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strip>;
+/** Common node fields; `props` stays `unknown` here — `registry.nodeSchema()` narrows it per type. */
+export declare const blockNodeBase: {
+    id: z.ZodString;
+    type: z.ZodString;
+    v: z.ZodOptional<z.ZodNumber>;
+    variant: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodArray<z.ZodType<import("./rich-doc.js").RichInline, unknown, z.core.$ZodTypeInternals<import("./rich-doc.js").RichInline, unknown>>>>;
+    theme: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            inherit: "inherit";
+        }>>;
+        surface: z.ZodOptional<z.ZodEnum<{
+            accent: "accent";
+            media: "media";
+            surface: "surface";
+            scene: "scene";
+            "surface-2": "surface-2";
+        }>>;
+        accent: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            lime: "lime";
+            ocean: "ocean";
+            ember: "ember";
+            rose: "rose";
+            graphite: "graphite";
+        }>, z.ZodString]>>;
+        material: z.ZodOptional<z.ZodEnum<{
+            glass: "glass";
+            solid: "solid";
+            inherit: "inherit";
+        }>>;
+        density: z.ZodOptional<z.ZodEnum<{
+            compact: "compact";
+            comfortable: "comfortable";
+            inherit: "inherit";
+        }>>;
+        rhythm: z.ZodOptional<z.ZodEnum<{
+            normal: "normal";
+            loose: "loose";
+            tight: "tight";
+        }>>;
+        background: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            blurDataURL: z.ZodOptional<z.ZodString>;
+            focal: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+            decorative: z.ZodOptional<z.ZodBoolean>;
+            assetId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    anchor: z.ZodOptional<z.ZodString>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    schedule: z.ZodOptional<z.ZodObject<{
+        from: z.ZodOptional<z.ZodISODateTime>;
+        until: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+};
+/** Storage-level node schema (any type, props unchecked). */
+export declare const BlockNodeSchema: z.ZodType<BlockNode>;
+export declare const SeoMetaSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+    description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+    image: z.ZodOptional<z.ZodObject<{
+        src: z.ZodString;
+        alt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        blurDataURL: z.ZodOptional<z.ZodString>;
+        focal: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        decorative: z.ZodOptional<z.ZodBoolean>;
+        assetId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    canonical: z.ZodOptional<z.ZodString>;
+    noindex: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Builds a VamosDoc schema around a node schema (storage-level or registry-strict). */
+export declare function docSchemaOf(node: z.ZodType<BlockNode>): z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    version: z.ZodLiteral<1>;
+    lang: z.ZodOptional<z.ZodString>;
+    locales: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    translationKey: z.ZodOptional<z.ZodString>;
+    seo: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+        description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+        image: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            blurDataURL: z.ZodOptional<z.ZodString>;
+            focal: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+            decorative: z.ZodOptional<z.ZodBoolean>;
+            assetId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        canonical: z.ZodOptional<z.ZodString>;
+        noindex: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    blocks: z.ZodArray<z.ZodType<BlockNode<Record<string, unknown>>, unknown, z.core.$ZodTypeInternals<BlockNode<Record<string, unknown>>, unknown>>>;
+    layout: z.ZodOptional<z.ZodObject<{
+        header: z.ZodOptional<z.ZodArray<z.ZodType<BlockNode<Record<string, unknown>>, unknown, z.core.$ZodTypeInternals<BlockNode<Record<string, unknown>>, unknown>>>>;
+        footer: z.ZodOptional<z.ZodArray<z.ZodType<BlockNode<Record<string, unknown>>, unknown, z.core.$ZodTypeInternals<BlockNode<Record<string, unknown>>, unknown>>>>;
+        overlay: z.ZodOptional<z.ZodArray<z.ZodType<BlockNode<Record<string, unknown>>, unknown, z.core.$ZodTypeInternals<BlockNode<Record<string, unknown>>, unknown>>>>;
+    }, z.core.$strip>>;
+    meta: z.ZodOptional<z.ZodObject<{
+        wordCount: z.ZodOptional<z.ZodNumber>;
+        readingTime: z.ZodOptional<z.ZodNumber>;
+        toc: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            level: z.ZodNumber;
+            text: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const VamosDocSchema: z.ZodType<VamosDoc>;
+export declare const PageDocSchema: z.ZodType<VamosDoc, unknown, z.core.$ZodTypeInternals<VamosDoc, unknown>>;
+export declare const VAMOS_DOC_SCHEMA_URL = "https://ui.vamos.ist/schema/doc-1.json";
+/**
+ * Text node types every renderer understands without a registry entry (post bodies, articles).
+ * A registry may override any of them with its own definition.
+ */
+export declare const CORE_TEXT_TYPES: readonly ["paragraph", "heading", "list", "list-item", "quote", "code", "divider"];
+export type CoreTextType = (typeof CORE_TEXT_TYPES)[number];
+export declare const isCoreTextType: (t: string) => t is CoreTextType;

package/dist/blocks/schema/nodes.js

@@ -0,0 +1,78 @@
+// zod schemas for the frozen node/document formats (types.ts, BLOCK-FORMAT.md §1–2).
+import { z } from "zod";
+import { ImageRefSchema, localizedSchema } from "./fields.js";
+import { RichInlineSchema } from "./rich-doc-schema.js";
+import { LOCALE_KEY_RE } from "./localized.js";
+export const ACCENTS = ["lime", "ocean", "ember", "rose", "graphite"];
+export const BlockThemeSchema = z
+    .object({
+    mode: z.enum(["inherit", "light", "dark"]),
+    surface: z.enum(["scene", "surface", "surface-2", "accent", "media"]),
+    accent: z.union([z.enum(ACCENTS), z.string().regex(/^oklch\(\s*[\d.]+%?\s+[\d.]+\s+[\d.]+(deg)?\s*(\/\s*[\d.]+%?\s*)?\)$/, { message: "Custom accents must be oklch(L C H)." })]),
+    material: z.enum(["inherit", "glass", "solid"]),
+    density: z.enum(["inherit", "comfortable", "compact"]),
+    rhythm: z.enum(["tight", "normal", "loose"]),
+    background: ImageRefSchema,
+})
+    .partial()
+    .refine((t) => t.surface !== "media" || !!t.background, { message: "A media surface needs a background image.", path: ["background"] });
+/** Ids: 4–64 chars of `[A-Za-z0-9_-]` (`b_7Hq2`, nanoid, uuid all fit). */
+export const BlockIdSchema = z.string().regex(/^[A-Za-z0-9_-]{4,64}$/, { message: "Block ids are 4–64 characters of A–Z, a–z, 0–9, _ and -." });
+export const BlockTypeSchema = z.string().regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, { message: "Block types are kebab-case." });
+export const AnchorSchema = z.string().regex(/^[a-z0-9-]+$/, { message: "Anchors are lowercase letters, digits and hyphens." });
+export const ScheduleSchema = z.object({ from: z.iso.datetime({ offset: true }), until: z.iso.datetime({ offset: true }) }).partial();
+/** Common node fields; `props` stays `unknown` here — `registry.nodeSchema()` narrows it per type. */
+export const blockNodeBase = {
+    id: BlockIdSchema,
+    type: BlockTypeSchema,
+    v: z.number().int().positive().optional(),
+    variant: z.string().optional(),
+    content: z.array(RichInlineSchema).optional(),
+    theme: BlockThemeSchema.optional(),
+    anchor: AnchorSchema.optional(),
+    hidden: z.boolean().optional(),
+    schedule: ScheduleSchema.optional(),
+};
+/** Storage-level node schema (any type, props unchecked). */
+export const BlockNodeSchema = z.lazy(() => z.object({
+    ...blockNodeBase,
+    props: z.record(z.string(), z.unknown()).optional(),
+    slots: z.record(z.string(), z.array(BlockNodeSchema)).optional(),
+}));
+export const SeoMetaSchema = z.object({
+    title: localizedSchema(z.string().max(120)).optional(),
+    description: localizedSchema(z.string().max(320)).optional(),
+    image: ImageRefSchema.optional(),
+    canonical: z.string().optional(),
+    noindex: z.boolean().optional(),
+});
+const LocaleCodeSchema = z.string().regex(LOCALE_KEY_RE);
+/** Builds a VamosDoc schema around a node schema (storage-level or registry-strict). */
+export function docSchemaOf(node) {
+    return z.object({
+        $schema: z.string().optional(),
+        version: z.literal(1),
+        lang: LocaleCodeSchema.optional(),
+        locales: z.array(LocaleCodeSchema).min(1).optional(),
+        translationKey: z.string().optional(),
+        seo: SeoMetaSchema.optional(),
+        blocks: z.array(node),
+        layout: z.object({ header: z.array(node), footer: z.array(node), overlay: z.array(node) }).partial().optional(),
+        meta: z
+            .object({
+            wordCount: z.number().optional(),
+            readingTime: z.number().optional(),
+            toc: z.array(z.object({ id: z.string(), level: z.number(), text: z.string() })).optional(),
+        })
+            .optional(),
+    });
+}
+export const VamosDocSchema = docSchemaOf(BlockNodeSchema);
+export const PageDocSchema = VamosDocSchema;
+export const VAMOS_DOC_SCHEMA_URL = "https://ui.vamos.ist/schema/doc-1.json";
+/**
+ * Text node types every renderer understands without a registry entry (post bodies, articles).
+ * A registry may override any of them with its own definition.
+ */
+export const CORE_TEXT_TYPES = ["paragraph", "heading", "list", "list-item", "quote", "code", "divider"];
+export const isCoreTextType = (t) => CORE_TEXT_TYPES.includes(t);

package/dist/blocks/schema/rich-doc-schema.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { type RichBlock, type RichDoc, type RichInline, type RichMarkType, type RichNodeType } from "./rich-doc.js";
+export declare const RichMarkSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"bold">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"italic">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"underline">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"strike">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"code">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"highlight">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"sub">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"sup">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"link">;
+    href: z.ZodString;
+    newTab: z.ZodOptional<z.ZodBoolean>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export declare const RichInlineSchema: z.ZodType<RichInline>;
+export declare const RichBlockSchema: z.ZodType<RichBlock>;
+export declare const RichDocSchema: z.ZodObject<{
+    type: z.ZodLiteral<"doc">;
+    content: z.ZodArray<z.ZodType<RichBlock, unknown, z.core.$ZodTypeInternals<RichBlock, unknown>>>;
+}, z.core.$strip>;
+/** Problems when a doc uses nodes or marks outside an allow-list (`f.rich({ nodes, marks })`). */
+export declare function richDocAllows(doc: RichDoc, nodes?: readonly RichNodeType[], marks?: readonly RichMarkType[]): string[];

package/dist/blocks/schema/rich-doc-schema.js

@@ -0,0 +1,66 @@
+// zod schema for RichDoc (see rich-doc.ts for the types and BLOCK-FORMAT.md §3).
+import { z } from "zod";
+import { sanitizeHref } from "./safety.js";
+import { isBreak } from "./rich-doc.js";
+export const RichMarkSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("bold") }),
+    z.object({ type: z.literal("italic") }),
+    z.object({ type: z.literal("underline") }),
+    z.object({ type: z.literal("strike") }),
+    z.object({ type: z.literal("code") }),
+    z.object({ type: z.literal("highlight") }),
+    z.object({ type: z.literal("sub") }),
+    z.object({ type: z.literal("sup") }),
+    z.object({
+        type: z.literal("link"),
+        href: z.string().refine((h) => sanitizeHref(h) !== null, { message: "Unsafe link in rich text." }),
+        newTab: z.boolean().optional(),
+        title: z.string().optional(),
+    }),
+]);
+export const RichInlineSchema = z.union([
+    z.object({ type: z.literal("br") }),
+    z.object({ text: z.string(), marks: z.array(RichMarkSchema).optional() }),
+]);
+const inline = z.array(RichInlineSchema).optional();
+export const RichBlockSchema = z.lazy(() => z.discriminatedUnion("type", [
+    z.object({ type: z.literal("paragraph"), content: inline }),
+    z.object({ type: z.literal("heading"), level: z.union([z.literal(2), z.literal(3), z.literal(4)]), content: inline, anchor: z.string().regex(/^[a-z0-9-]+$/).optional() }),
+    z.object({
+        type: z.literal("list"),
+        ordered: z.boolean().optional(),
+        start: z.number().int().optional(),
+        items: z.array(z.object({ content: z.array(RichBlockSchema) })),
+    }),
+    z.object({ type: z.literal("blockquote"), content: z.array(RichBlockSchema), cite: z.string().optional() }),
+    z.object({ type: z.literal("code"), text: z.string(), language: z.string().optional() }),
+    z.object({ type: z.literal("hr") }),
+]));
+export const RichDocSchema = z.object({ type: z.literal("doc"), content: z.array(RichBlockSchema) });
+/** Problems when a doc uses nodes or marks outside an allow-list (`f.rich({ nodes, marks })`). */
+export function richDocAllows(doc, nodes, marks) {
+    const problems = new Set();
+    const checkInline = (c) => {
+        if (!marks || !c)
+            return;
+        for (const n of c)
+            if (!isBreak(n))
+                for (const m of n.marks ?? [])
+                    if (!marks.includes(m.type))
+                        problems.add(`The "${m.type}" mark is not allowed here.`);
+    };
+    const walk = (blocks) => {
+        for (const b of blocks) {
+            if (nodes && !nodes.includes(b.type))
+                problems.add(`The "${b.type}" block is not allowed here.`);
+            if (b.type === "paragraph" || b.type === "heading")
+                checkInline(b.content);
+            else if (b.type === "blockquote")
+                walk(b.content);
+            else if (b.type === "list")
+                b.items.forEach((it) => walk(it.content));
+        }
+    };
+    walk(doc.content);
+    return [...problems];
+}

package/dist/blocks/schema/rich-doc.d.ts

@@ -0,0 +1,90 @@
+/** Inline marks. Order of nesting on render is fixed (link → bold → italic → … → sup). */
+export type RichMark = {
+    type: "bold";
+} | {
+    type: "italic";
+} | {
+    type: "underline";
+} | {
+    type: "strike";
+} | {
+    type: "code";
+} | {
+    type: "highlight";
+} | {
+    type: "sub";
+} | {
+    type: "sup";
+} | {
+    type: "link";
+    href: string;
+    newTab?: boolean;
+    title?: string;
+};
+export type RichMarkType = RichMark["type"];
+/** A run of text with marks. `text` never contains `\n` — use a `{ type: "br" }` run. */
+export interface RichTextRun {
+    text: string;
+    marks?: RichMark[];
+}
+/** A hard line break inside a paragraph or heading. */
+export interface RichBreak {
+    type: "br";
+}
+export type RichInline = RichTextRun | RichBreak;
+export interface RichParagraph {
+    type: "paragraph";
+    content?: RichInline[];
+}
+export interface RichHeading {
+    type: "heading";
+    level: 2 | 3 | 4;
+    content?: RichInline[];
+    /** Optional stable anchor (`id` on the element, TOC target). */
+    anchor?: string;
+}
+export interface RichListItem {
+    /** Paragraphs and nested lists. */
+    content: RichBlock[];
+}
+export interface RichList {
+    type: "list";
+    ordered?: boolean;
+    /** First number of an ordered list. */
+    start?: number;
+    items: RichListItem[];
+}
+export interface RichBlockquote {
+    type: "blockquote";
+    content: RichBlock[];
+    /** Attribution line ("— Ayşe K., head chef"). */
+    cite?: string;
+}
+export interface RichCode {
+    type: "code";
+    text: string;
+    language?: string;
+}
+export interface RichRule {
+    type: "hr";
+}
+export type RichBlock = RichParagraph | RichHeading | RichList | RichBlockquote | RichCode | RichRule;
+export type RichNodeType = RichBlock["type"];
+/** A rich-text field value: `f.rich()` stores `Localized<RichDoc>`. */
+export interface RichDoc {
+    type: "doc";
+    content: RichBlock[];
+}
+export declare const RICH_NODE_TYPES: readonly ["paragraph", "heading", "list", "blockquote", "code", "hr"];
+export declare const RICH_MARK_TYPES: readonly ["bold", "italic", "underline", "strike", "code", "highlight", "sub", "sup", "link"];
+export declare const isBreak: (n: RichInline) => n is RichBreak;
+/** Builds a doc from plain paragraphs (blank line = new paragraph, single newline = `br`). */
+export declare function richFromText(text: string): RichDoc;
+/** Plain text of inline runs (`br` → newline). */
+export declare function inlineToText(content: readonly RichInline[] | undefined): string;
+/** Plain text of a doc (paragraphs separated by a blank line). Search indexes, meta descriptions, reading time. */
+export declare function richToText(doc: RichDoc | readonly RichBlock[] | undefined): string;
+/** Word count (Unicode-aware; works for Turkish, German, etc.). */
+export declare function countWords(text: string): number;
+/** Visits every inline run in a doc. */
+export declare function forEachRun(doc: RichDoc, visit: (run: RichTextRun) => void): void;