@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/blocks/schema/fields.js

@@ -0,0 +1,240 @@
+// Field builders (`f.*`): each returns a zod schema that carries editor metadata via `.meta()`.
+// The stored type decides validation; the metadata decides the editor widget, localization
+// and lint rules. Server/admin only — components import types, never this file.
+import { z } from "zod";
+import { LOCALE_KEY_RE } from "./localized.js";
+import { countEmphasis } from "./emphasis.js";
+import { EMOJI_RE, sanitizeHref } from "./safety.js";
+import { RichDocSchema, richDocAllows } from "./rich-doc-schema.js";
+import { BLOCK_ICONS } from "./icons.js";
+const META = "vamos";
+function withMeta(schema, meta) {
+    const out = { [META]: stripUndefined(meta) };
+    if (meta.label)
+        out.title = meta.label;
+    if (meta.help)
+        out.description = meta.help;
+    return schema.meta(out);
+}
+function stripUndefined(o) {
+    const r = {};
+    for (const [k, v] of Object.entries(o))
+        if (v !== undefined)
+            r[k] = v;
+    return r;
+}
+const WRAPPERS = new Set(["optional", "nullable", "default", "prefault", "readonly", "catch", "nonoptional"]);
+/** Removes optional/default/nullable/readonly wrappers. */
+export function unwrapSchema(schema) {
+    let s = schema;
+    for (let i = 0; i < 10; i++) {
+        const def = s._zod.def;
+        if (WRAPPERS.has(def.type) && def.innerType)
+            s = def.innerType;
+        else
+            break;
+    }
+    return s;
+}
+/** Reads `f.*` metadata from a schema (looks through optional/default wrappers). */
+export function getFieldMeta(schema) {
+    let s = schema;
+    for (let i = 0; i < 10 && s; i++) {
+        const m = z.globalRegistry.get(s);
+        if (m?.[META])
+            return m[META];
+        const def = s._zod.def;
+        s = WRAPPERS.has(def.type) ? def.innerType : undefined;
+    }
+    return undefined;
+}
+/** The zod type name ("object", "array", "string", "union"…) after unwrapping. */
+export const schemaKind = (schema) => unwrapSchema(schema)._zod.def.type;
+const LOCALIZED_RECORDS = new WeakSet();
+/** `T` or `{ [locale]: T }`. `localize()` recognises it anywhere in a schema, with or without `f.*`. */
+export function localizedSchema(inner) {
+    const map = z.record(z.string().regex(LOCALE_KEY_RE), inner);
+    LOCALIZED_RECORDS.add(map);
+    return z.union([inner, map]);
+}
+/** True for a schema built by `localizedSchema` (also after `.meta()` / `.optional()`). */
+export function isLocalizedSchema(schema) {
+    const def = unwrapSchema(schema)._zod.def;
+    return def.type === "union" && !!def.options?.some((o) => LOCALIZED_RECORDS.has(o));
+}
+const noEmoji = (s) => !EMOJI_RE.test(s);
+const plainString = (opts) => {
+    let s = z.string();
+    if (opts.min !== undefined)
+        s = s.min(opts.min);
+    if (opts.max !== undefined)
+        s = s.max(opts.max);
+    return s.refine(noEmoji, { message: "Emoji are not allowed in block copy." });
+};
+const safeHref = z.string().min(1).refine((h) => sanitizeHref(h) !== null, { message: "Unsafe or unsupported link (javascript:, data: and unknown schemes are rejected)." });
+// ---------------------------------------------------------------- shared value schemas
+export const ImageRefSchema = z
+    .object({
+    src: z.string().min(1).refine((h) => sanitizeHref(h) !== null, { message: "Unsupported image URL." }),
+    alt: localizedSchema(z.string()).optional(),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    blurDataURL: z.string().startsWith("data:image/").optional(),
+    focal: z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) }).optional(),
+    decorative: z.boolean().optional(),
+    assetId: z.string().optional(),
+})
+    .refine((v) => v.decorative === true || hasText(v.alt), { message: "Describe the image (alt) or mark it decorative.", path: ["alt"] });
+function hasText(v) {
+    if (typeof v === "string")
+        return v.trim().length > 0;
+    if (v && typeof v === "object")
+        return Object.values(v).some((x) => typeof x === "string" && x.trim().length > 0);
+    return false;
+}
+export const LinkRefSchema = z.object({
+    href: localizedSchema(safeHref),
+    label: localizedSchema(plainString({ max: 80 })),
+    kind: z.enum(["url", "anchor", "tel", "mailto", "whatsapp", "file"]).optional(),
+    newTab: z.boolean().optional(),
+});
+export const TimeRangeSchema = z.object({
+    open: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/),
+    close: z.string().regex(/^([01]\d|2[0-4]):[0-5]\d$/),
+});
+const dateOnly = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, { message: "Use a date-only YYYY-MM-DD value." });
+export const OpeningHoursSchema = z.object({
+    timeZone: z.string().min(1),
+    weekly: z.object({
+        mon: z.array(TimeRangeSchema).optional(),
+        tue: z.array(TimeRangeSchema).optional(),
+        wed: z.array(TimeRangeSchema).optional(),
+        thu: z.array(TimeRangeSchema).optional(),
+        fri: z.array(TimeRangeSchema).optional(),
+        sat: z.array(TimeRangeSchema).optional(),
+        sun: z.array(TimeRangeSchema).optional(),
+    }),
+    special: z
+        .array(z.object({ date: dateOnly, closed: z.boolean().optional(), ranges: z.array(TimeRangeSchema).optional(), note: localizedSchema(z.string()).optional() }))
+        .optional(),
+});
+export const EMBED_PROVIDERS = ["youtube", "vimeo", "google-maps", "openstreetmap", "calendly"];
+const EMBED_HOSTS = {
+    youtube: /^https:\/\/(www\.)?(youtube\.com|youtube-nocookie\.com|youtu\.be)\//i,
+    vimeo: /^https:\/\/(player\.)?vimeo\.com\//i,
+    "google-maps": /^https:\/\/(www\.)?google\.[a-z.]+\/maps|^https:\/\/maps\.app\.goo\.gl\//i,
+    openstreetmap: /^https:\/\/(www\.)?openstreetmap\.org\//i,
+    calendly: /^https:\/\/calendly\.com\//i,
+};
+export const SOCIAL_NETWORKS = ["instagram", "facebook", "linkedin", "x", "youtube", "tiktok", "whatsapp", "telegram", "google-maps", "apple-maps", "yandex-maps"];
+function heading(opts = {}) {
+    const max = opts.max ?? 140;
+    const inner = plainString({ max }).refine((s) => countEmphasis(s) <= 1, { message: "Use at most one *emphasis* per heading." });
+    const localized = opts.localized ?? true;
+    return withMeta(localized ? localizedSchema(inner) : inner, { field: "heading", localized, max, ...opts });
+}
+function text(opts = {}) {
+    const inner = plainString(opts);
+    const localized = opts.localized ?? true;
+    return withMeta(localized ? localizedSchema(inner) : inner, { field: "text", localized, ...opts });
+}
+function rich(opts = {}) {
+    const inner = RichDocSchema.superRefine((doc, ctx) => {
+        for (const problem of richDocAllows(doc, opts.nodes, opts.marks))
+            ctx.addIssue({ code: "custom", message: problem });
+    });
+    const localized = opts.localized ?? true;
+    return withMeta(localized ? localizedSchema(inner) : inner, { field: "rich", localized, ...opts });
+}
+function image(opts = {}) {
+    return withMeta(ImageRefSchema, { field: "image", ...opts });
+}
+function link(opts = {}) {
+    return withMeta(LinkRefSchema, { field: "link", ...opts });
+}
+function cta(opts = {}) {
+    return withMeta(z.object({ link: LinkRefSchema, style: z.enum(["primary", "secondary", "link"]) }), { field: "cta", ...opts });
+}
+function list(item, opts = {}) {
+    let s = z.array(item);
+    if (opts.min !== undefined)
+        s = s.min(opts.min);
+    if (opts.max !== undefined)
+        s = s.max(opts.max);
+    return withMeta(s, { field: "list", ...opts });
+}
+/** A nested object of fields (an FAQ item, a pricing plan). */
+function group(shape, opts = {}) {
+    return withMeta(z.object(shape), { field: "group", ...opts });
+}
+function select(options, opts = {}) {
+    return withMeta(z.enum(options), { field: "select", ...opts });
+}
+function toggle(opts = {}) {
+    return withMeta(z.boolean(), { field: "toggle", ...opts });
+}
+function number(opts = {}) {
+    let s = opts.int ? z.number().int() : z.number();
+    if (opts.min !== undefined)
+        s = s.min(opts.min);
+    if (opts.max !== undefined)
+        s = s.max(opts.max);
+    return withMeta(s, { field: "number", ...opts });
+}
+function icon(opts = {}) {
+    return withMeta(z.enum(BLOCK_ICONS), { field: "icon", ...opts });
+}
+function money(opts = {}) {
+    return withMeta(z.object({
+        amount: z.string().regex(/^-?\d+(\.\d+)?$/, { message: "Money is a decimal string, e.g. \"1250.00\"." }),
+        currency: z.string().regex(/^[A-Z]{3}$/, { message: "Use an ISO 4217 code, e.g. \"TRY\"." }),
+    }), { field: "money", ...opts });
+}
+function phone(opts = {}) {
+    return withMeta(z.string().regex(/^\+[1-9]\d{6,14}$/, { message: "Use E.164, e.g. +902160000000." }), { field: "phone", ...opts });
+}
+function address(opts = {}) {
+    return withMeta(z.object({
+        line: z.string().min(1),
+        district: z.string().optional(),
+        city: z.string().min(1),
+        region: z.string().optional(),
+        postalCode: z.string().optional(),
+        country: z.string().regex(/^[A-Z]{2}$/),
+        geo: z.object({ lat: z.number().min(-90).max(90), lng: z.number().min(-180).max(180) }).optional(),
+    }), { field: "address", ...opts });
+}
+function hours(opts = {}) {
+    return withMeta(OpeningHoursSchema, { field: "hours", ...opts });
+}
+/** A data query resolved by the renderer (`resolvers[resource]`) into the plain prop `into`. */
+function query(resource, opts = {}) {
+    const kinds = (opts.kinds ?? ["latest", "category", "manual"]);
+    return withMeta(z.object({ kind: z.enum(kinds), limit: z.number().int().min(1).max(48).optional(), category: z.string().optional(), ids: z.array(z.string()).optional() }), { field: "query", query: { resource, into: opts.into ?? resource }, ...opts });
+}
+function embed(opts = {}) {
+    const allow = opts.allow ?? EMBED_PROVIDERS;
+    return withMeta(z
+        .object({ provider: z.enum(EMBED_PROVIDERS), url: z.url() })
+        .refine((v) => allow.includes(v.provider), { message: "This embed provider is not allowed here.", path: ["provider"] })
+        .refine((v) => EMBED_HOSTS[v.provider].test(v.url), { message: "The URL does not belong to the selected provider.", path: ["url"] }), { field: "embed", allow, ...opts });
+}
+function social(opts = {}) {
+    return withMeta(z.array(z.object({ network: z.enum(SOCIAL_NETWORKS), href: safeHref })).max(opts.max ?? 12), { field: "social", ...opts });
+}
+function date(opts = {}) {
+    return withMeta(dateOnly, { field: "date", ...opts });
+}
+/**
+ * Field builders. Each returns a zod schema; metadata drives editors, `localize()` and `lintPage()`.
+ *
+ * ```ts
+ * const schema = z.object({
+ *   title: f.heading({ max: 80 }),
+ *   lead: f.text({ multiline: true }).optional(),
+ *   image: f.image({ aspect: "4:5" }),
+ *   actions: f.list(f.cta(), { max: 2 }),
+ * });
+ * ```
+ */
+export const f = { heading, text, rich, image, link, cta, list, group, select, toggle, number, icon, money, phone, address, hours, query, embed, social, date };

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

@@ -0,0 +1,2 @@
+export declare const BLOCK_ICONS: readonly ["map-pin", "map", "navigation", "compass", "phone", "phone-call", "mail", "message-circle", "message-square", "send", "globe", "building", "building-2", "store", "home", "hotel", "landmark", "warehouse", "parking-circle", "car", "bike", "bus", "train-front", "plane", "ship", "accessibility", "baby", "dog", "wifi", "plug", "clock", "calendar", "calendar-check", "calendar-days", "alarm-clock", "timer", "hourglass", "history", "repeat", "bell", "utensils", "utensils-crossed", "chef-hat", "coffee", "cup-soda", "wine", "beer", "cake", "croissant", "pizza", "salad", "soup", "fish", "beef", "egg", "leaf", "wheat", "flame", "ice-cream-cone", "sandwich", "heart", "heart-pulse", "sparkles", "flower", "flower-2", "bath", "droplets", "sun", "moon", "waves", "scissors", "hand", "stethoscope", "pill", "smile", "dumbbell", "palette", "brush", "glasses", "briefcase", "chart-line", "chart-bar", "chart-pie", "trending-up", "target", "gauge", "layers", "layout-grid", "puzzle", "settings", "sliders-horizontal", "wrench", "hammer", "package", "truck", "box", "tag", "receipt", "wallet", "credit-card", "banknote", "piggy-bank", "percent", "shopping-bag", "shopping-cart", "gift", "award", "badge-check", "medal", "user", "users", "user-check", "handshake", "shield", "shield-check", "lock", "key", "eye", "fingerprint", "book-open", "file-text", "newspaper", "pen-line", "image", "camera", "video", "music", "mic", "headphones", "monitor", "smartphone", "tablet", "laptop", "code", "terminal", "database", "cloud", "server", "cpu", "zap", "rocket", "lightbulb", "star", "check", "circle-check", "info", "help-circle", "arrow-right", "external-link"];
+export type BlockIconName = (typeof BLOCK_ICONS)[number];

package/dist/blocks/schema/icons.js

@@ -0,0 +1,26 @@
+// Allow-list for `f.icon()` (150 lucide names) (kebab-case) that read well at 20px / stroke 1.5.
+// Brand marks are not icons — use `f.social()`.
+export const BLOCK_ICONS = [
+    // places & contact
+    "map-pin", "map", "navigation", "compass", "phone", "phone-call", "mail", "message-circle", "message-square", "send",
+    "globe", "building", "building-2", "store", "home", "hotel", "landmark", "warehouse", "parking-circle", "car",
+    "bike", "bus", "train-front", "plane", "ship", "accessibility", "baby", "dog", "wifi", "plug",
+    // time & booking
+    "clock", "calendar", "calendar-check", "calendar-days", "alarm-clock", "timer", "hourglass", "history", "repeat", "bell",
+    // food & venue
+    "utensils", "utensils-crossed", "chef-hat", "coffee", "cup-soda", "wine", "beer", "cake", "croissant", "pizza",
+    "salad", "soup", "fish", "beef", "egg", "leaf", "wheat", "flame", "ice-cream-cone", "sandwich",
+    // wellness & care
+    "heart", "heart-pulse", "sparkles", "flower", "flower-2", "bath", "droplets", "sun", "moon", "waves",
+    "scissors", "hand", "stethoscope", "pill", "smile", "dumbbell", "palette", "brush", "glasses",
+    // business & product
+    "briefcase", "chart-line", "chart-bar", "chart-pie", "trending-up", "target", "gauge", "layers", "layout-grid", "puzzle",
+    "settings", "sliders-horizontal", "wrench", "hammer", "package", "truck", "box", "tag", "receipt", "wallet",
+    "credit-card", "banknote", "piggy-bank", "percent", "shopping-bag", "shopping-cart", "gift", "award", "badge-check", "medal",
+    // people & trust
+    "user", "users", "user-check", "handshake", "shield", "shield-check", "lock", "key", "eye", "fingerprint",
+    // content & tech
+    "book-open", "file-text", "newspaper", "pen-line", "image", "camera", "video", "music", "mic", "headphones",
+    "monitor", "smartphone", "tablet", "laptop", "code", "terminal", "database", "cloud", "server", "cpu",
+    "zap", "rocket", "lightbulb", "star", "check", "circle-check", "info", "help-circle", "arrow-right", "external-link",
+];

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

@@ -0,0 +1,18 @@
+export { z } from "zod";
+export type { BlockNode, VamosDoc, PageDoc, BlockTheme, BuiltInAccent, ImageRef, LinkRef, CtaRef, CtaStyle, MoneyValue, AddressValue, OpeningHours, TimeRange, Weekday, QueryValue, EmbedValue, SocialLink, SocialNetwork, SeoMeta, DocMeta, BlockSchedule, } from "./types.js";
+export type { RichDoc, RichBlock, RichInline, RichTextRun, RichBreak, RichMark, RichMarkType, RichNodeType, RichParagraph, RichHeading, RichList, RichListItem, RichBlockquote, RichCode, RichRule, } from "./rich-doc.js";
+export { RICH_NODE_TYPES, RICH_MARK_TYPES, richFromText, richToText, inlineToText, countWords, forEachRun, isBreak } from "./rich-doc.js";
+export { RichDocSchema, RichBlockSchema, RichInlineSchema, RichMarkSchema, richDocAllows } from "./rich-doc-schema.js";
+export { BlockNodeSchema, VamosDocSchema, PageDocSchema, BlockThemeSchema, BlockIdSchema, BlockTypeSchema, AnchorSchema, ScheduleSchema, SeoMetaSchema, docSchemaOf, CORE_TEXT_TYPES, isCoreTextType, ACCENTS, VAMOS_DOC_SCHEMA_URL, type CoreTextType, } from "./nodes.js";
+export { pickLocale, isLocaleMap, localeChain, localesOf, LOCALE_KEY_RE, type Localized, type LocaleCode, type PickLocaleOptions } from "./localized.js";
+export { localize, localizeProps, type LocalizeOptions } from "./localize.js";
+export { f, getFieldMeta, unwrapSchema, schemaKind, localizedSchema, isLocalizedSchema, ImageRefSchema, LinkRefSchema, OpeningHoursSchema, TimeRangeSchema, EMBED_PROVIDERS, SOCIAL_NETWORKS, type FieldKind, type FieldMeta, type FieldOptions, } from "./fields.js";
+export { BLOCK_ICONS, type BlockIconName } from "./icons.js";
+export { mapFields, walkFields, type FieldVisit, type FieldVisitor } from "./walk.js";
+export { defineBlock, createRegistry, BlockDefinitionError, type BlockDefinition, type BlockDefinitionInput, type AnyBlockDefinition, type BlockRegistry, type BlockCategory, type BlockRegion, type BlockSupports, type SlotSpec, type FieldHints, type BlockPropsOf, type Delocalized, type JsonLdContext, } from "./define-block.js";
+export { migrateNode, migrateDoc, docMigrations, CURRENT_DOC_VERSION, type MigrationResult } from "./migrate.js";
+export { validateNode, type ValidationResult } from "./validate.js";
+export { lintPage, CLICHE_PHRASES, oklchHue, type LintOptions, type LintReport } from "./lint.js";
+export type { LintIssue, LintIssueInput, LintCode, LintSeverity } from "./lint-types.js";
+export { parseEmphasis, countEmphasis, stripEmphasis, type EmphasisPart } from "./emphasis.js";
+export { sanitizeHref, isExternalUrl, linkKindOf, hasEmoji, EMOJI_RE, type LinkKind } from "./safety.js";

package/dist/blocks/schema/index.js

@@ -0,0 +1,21 @@
+// Public API of @vamos-ui/react/blocks/schema — layer 2 (zod, no React). Server, edge and admin only:
+// a site's client bundle never imports this entry (components use `import type`).
+export { z } from "zod";
+export { RICH_NODE_TYPES, RICH_MARK_TYPES, richFromText, richToText, inlineToText, countWords, forEachRun, isBreak } from "./rich-doc.js";
+export { RichDocSchema, RichBlockSchema, RichInlineSchema, RichMarkSchema, richDocAllows } from "./rich-doc-schema.js";
+export { BlockNodeSchema, VamosDocSchema, PageDocSchema, BlockThemeSchema, BlockIdSchema, BlockTypeSchema, AnchorSchema, ScheduleSchema, SeoMetaSchema, docSchemaOf, CORE_TEXT_TYPES, isCoreTextType, ACCENTS, VAMOS_DOC_SCHEMA_URL, } from "./nodes.js";
+// Localization
+export { pickLocale, isLocaleMap, localeChain, localesOf, LOCALE_KEY_RE } from "./localized.js";
+export { localize, localizeProps } from "./localize.js";
+// Fields
+export { f, getFieldMeta, unwrapSchema, schemaKind, localizedSchema, isLocalizedSchema, ImageRefSchema, LinkRefSchema, OpeningHoursSchema, TimeRangeSchema, EMBED_PROVIDERS, SOCIAL_NETWORKS, } from "./fields.js";
+export { BLOCK_ICONS } from "./icons.js";
+export { mapFields, walkFields } from "./walk.js";
+// Definitions, registry, migrations, validation, lint
+export { defineBlock, createRegistry, BlockDefinitionError, } from "./define-block.js";
+export { migrateNode, migrateDoc, docMigrations, CURRENT_DOC_VERSION } from "./migrate.js";
+export { validateNode } from "./validate.js";
+export { lintPage, CLICHE_PHRASES, oklchHue } from "./lint.js";
+// Pure helpers shared with layer 1
+export { parseEmphasis, countEmphasis, stripEmphasis } from "./emphasis.js";
+export { sanitizeHref, isExternalUrl, linkKindOf, hasEmoji, EMOJI_RE } from "./safety.js";

package/dist/blocks/schema/lint-types.d.ts

@@ -0,0 +1,16 @@
+export type LintSeverity = "error" | "warning" | "info";
+export type LintCode = "unknown-block" | "invalid-props" | "duplicate-id" | "duplicate-anchor" | "multiple-h1" | "missing-h1" | "heading-too-long" | "cliche-copy" | "multiple-primary-cta" | "missing-translation" | "too-many-cards" | "monotone-page" | "violet-accent" | "newer-version" | "missing-migration" | (string & {});
+export interface LintIssueInput {
+    code: LintCode;
+    severity?: LintSeverity;
+    message: string;
+    /** Prop path inside the block, e.g. "props.items.2.title". */
+    path?: string;
+}
+export interface LintIssue extends Required<Pick<LintIssueInput, "code" | "message">> {
+    severity: LintSeverity;
+    blockId?: string;
+    blockType?: string;
+    path?: string;
+    locale?: string;
+}

package/dist/blocks/schema/lint-types.js

@@ -0,0 +1,2 @@
+// Lint issue shapes (lintPage + per-block `lint`). Types only.
+export {};

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

@@ -0,0 +1,32 @@
+import { type LocaleCode } from "./localized.js";
+import type { BlockRegistry } from "./define-block.js";
+import type { VamosDoc } from "./types.js";
+import type { LintIssue } from "./lint-types.js";
+/** Stock phrases that make copy read machine-written (D6-6). Matched case-insensitively. */
+export declare const CLICHE_PHRASES: Record<string, readonly string[]>;
+export interface LintOptions {
+    /** Locales to check translations for. Default: `doc.locales`. */
+    locales?: readonly LocaleCode[];
+    /** Max words in a heading before a warning. Default 9. */
+    maxHeadingWords?: number;
+    /** Max card-like (`surface`) sections per page. Default 2. */
+    maxCardSections?: number;
+}
+export interface LintReport {
+    issues: LintIssue[];
+    /** Per-locale translation completeness, 0–100 (only when more than one locale). */
+    completeness: Record<LocaleCode, number>;
+    errorCount: number;
+    warningCount: number;
+}
+/** Hue of an `oklch(L C H)` string, or null. */
+export declare function oklchHue(color: string): number | null;
+/**
+ * Checks a document against the registry and the kit's editorial rules.
+ *
+ * ```ts
+ * const { issues, completeness } = lintPage(doc, siteBlocks);
+ * // completeness → { en: 100, tr: 82 }
+ * ```
+ */
+export declare function lintPage(doc: VamosDoc, registry: BlockRegistry, opts?: LintOptions): LintReport;

package/dist/blocks/schema/lint.js

@@ -0,0 +1,164 @@
+// lintPage(): the D6 "doesn't look AI-generated" rules + structure + translation completeness.
+// Warnings, not locks — builders surface them next to the block.
+import { walkFields } from "./walk.js";
+import { isLocaleMap } from "./localized.js";
+import { stripEmphasis } from "./emphasis.js";
+import { countWords, richToText } from "./rich-doc.js";
+import { isCoreTextType } from "./nodes.js";
+import { localizeProps } from "./localize.js";
+/** Stock phrases that make copy read machine-written (D6-6). Matched case-insensitively. */
+export const CLICHE_PHRASES = {
+    en: ["unlock", "seamless", "elevate", "supercharge", "revolutionize", "revolutionise", "next-gen", "next generation", "ai-powered", "empower", "take it to the next level", "lorem ipsum", "game-changer", "cutting-edge", "world-class", "best-in-class"],
+    tr: ["yeni nesil", "dijital dönüşüm", "bir üst seviyeye taşı", "işinizi büyütün", "sınırları zorlayın", "fark yaratın"],
+};
+const lower = (s) => s.toLocaleLowerCase("tr").replace(/\s+/g, " ");
+function textOf(value) {
+    if (typeof value === "string")
+        return value;
+    if (value && typeof value === "object" && value.type === "doc")
+        return richToText(value);
+    return "";
+}
+/** Hue of an `oklch(L C H)` string, or null. */
+export function oklchHue(color) {
+    const m = /^oklch\(\s*[\d.]+%?\s+([\d.]+)\s+([\d.]+)/.exec(color);
+    if (!m)
+        return null;
+    return Number(m[1]) < 0.03 ? null : Number(m[2]);
+}
+/**
+ * Checks a document against the registry and the kit's editorial rules.
+ *
+ * ```ts
+ * const { issues, completeness } = lintPage(doc, siteBlocks);
+ * // completeness → { en: 100, tr: 82 }
+ * ```
+ */
+export function lintPage(doc, registry, opts = {}) {
+    const issues = [];
+    const locales = opts.locales ?? doc.locales ?? (doc.lang ? [doc.lang] : ["en"]);
+    const maxWords = opts.maxHeadingWords ?? 9;
+    const ids = new Map();
+    const anchors = new Map();
+    const filled = Object.fromEntries(locales.map((l) => [l, 0]));
+    let localizedTotal = 0;
+    let coreH1 = 0;
+    let pageTitleBlocks = 0;
+    let cardSections = 0;
+    let hasImagery = false;
+    const surfaces = new Set();
+    let bodyCount = 0;
+    const add = (node, i) => issues.push({ severity: i.severity ?? "warning", code: i.code, message: i.message, path: i.path, locale: i.locale, blockId: node?.id, blockType: node?.type });
+    const visit = (node, region) => {
+        ids.set(node.id, (ids.get(node.id) ?? 0) + 1);
+        if (node.anchor)
+            anchors.set(node.anchor, (anchors.get(node.anchor) ?? 0) + 1);
+        if (region === "body") {
+            bodyCount++;
+            surfaces.add(`${node.theme?.surface ?? "scene"}/${node.theme?.mode ?? "inherit"}`);
+        }
+        if (node.theme?.surface === "surface")
+            cardSections++;
+        if (node.theme?.surface === "media")
+            hasImagery = true;
+        if (typeof node.theme?.accent === "string") {
+            const hue = oklchHue(node.theme.accent);
+            if (hue !== null && hue >= 265 && hue <= 320)
+                add(node, { code: "violet-accent", message: "Purple/violet custom accents read as generic; prefer a hue outside 265–320°." });
+        }
+        if (isCoreTextType(node.type) && !registry.has(node.type)) {
+            if (node.type === "heading" && node.props?.level === 1)
+                coreH1++;
+        }
+        else {
+            const def = registry.get(node.type);
+            if (!def) {
+                add(node, { code: "unknown-block", message: `Unknown block type "${node.type}". It is kept but not rendered.` });
+            }
+            else {
+                if ((node.v ?? 1) > def.version)
+                    add(node, { code: "newer-version", message: `Saved with v${node.v}; this site knows v${def.version}.` });
+                if (def.supports.pageTitle)
+                    pageTitleBlocks++;
+                const parsed = def.schema.safeParse(node.props ?? {});
+                if (!parsed.success) {
+                    for (const iss of parsed.error.issues)
+                        add(node, { severity: "error", code: "invalid-props", message: iss.message, path: ["props", ...iss.path.map(String)].join(".") });
+                }
+                let primaries = 0;
+                walkFields(def.schema, node.props, (f) => {
+                    const kind = f.meta?.field;
+                    if (kind === "image" && f.value)
+                        hasImagery = true;
+                    if (kind === "cta" && f.value?.style === "primary")
+                        primaries++;
+                    if (!f.localized)
+                        return;
+                    // translation completeness
+                    if (locales.length > 1) {
+                        localizedTotal++;
+                        for (const l of locales) {
+                            const has = !isLocaleMap(f.value) ? textOf(f.value) !== "" || typeof f.value !== "string" : textOf(f.value[l]) !== "";
+                            if (has)
+                                filled[l] = (filled[l] ?? 0) + 1;
+                            else
+                                add(node, { severity: "info", code: "missing-translation", message: `Missing ${l} translation.`, path: `props.${f.path}`, locale: l });
+                        }
+                    }
+                    // copy rules, per locale value
+                    const values = isLocaleMap(f.value) ? Object.entries(f.value) : [[undefined, f.value]];
+                    for (const [loc, raw] of values) {
+                        const t = textOf(raw);
+                        if (!t)
+                            continue;
+                        if (kind === "heading" && countWords(stripEmphasis(t)) > maxWords)
+                            add(node, { code: "heading-too-long", message: `Headings read best under ${maxWords + 1} words.`, path: `props.${f.path}`, locale: loc });
+                        const lt = lower(t);
+                        const lists = loc ? [CLICHE_PHRASES[loc.split("-")[0]] ?? [], CLICHE_PHRASES.en] : Object.values(CLICHE_PHRASES);
+                        const hit = lists.flat().find((p) => lt.includes(p));
+                        if (hit)
+                            add(node, { code: "cliche-copy", message: `“${hit}” is stock copy; say what the business actually does.`, path: `props.${f.path}`, locale: loc });
+                    }
+                });
+                if (primaries > 1)
+                    add(node, { code: "multiple-primary-cta", message: "Use one primary action per block; make the others secondary." });
+                if (def.lint && parsed.success) {
+                    const plain = localizeProps(def.schema, parsed.data, { locale: locales[0] ?? "en", fallback: locales.slice(1) });
+                    for (const i of def.lint(plain, node))
+                        add(node, i);
+                }
+            }
+        }
+        for (const list of Object.values(node.slots ?? {}))
+            for (const c of list)
+                visit(c, "slot");
+    };
+    for (const n of doc.layout?.header ?? [])
+        visit(n, "header");
+    for (const n of doc.blocks)
+        visit(n, "body");
+    for (const n of doc.layout?.footer ?? [])
+        visit(n, "footer");
+    for (const n of doc.layout?.overlay ?? [])
+        visit(n, "overlay");
+    for (const [id, n] of ids)
+        if (n > 1)
+            add(undefined, { severity: "error", code: "duplicate-id", message: `Block id "${id}" is used ${n} times; ids must be unique.` });
+    for (const [a, n] of anchors)
+        if (n > 1)
+            add(undefined, { severity: "error", code: "duplicate-anchor", message: `Anchor "#${a}" is used ${n} times.` });
+    const h1s = coreH1 + (pageTitleBlocks > 0 ? 1 : 0);
+    if (h1s > 1)
+        add(undefined, { severity: "error", code: "multiple-h1", message: "A page has one h1. Demote the extra level-1 headings." });
+    if (h1s === 0 && bodyCount > 0)
+        add(undefined, { severity: "info", code: "missing-h1", message: "No page title: start with a hero or page intro, or add a level-1 heading." });
+    if (cardSections > (opts.maxCardSections ?? 2))
+        add(undefined, { code: "too-many-cards", message: `${cardSections} card sections; keep at most ${opts.maxCardSections ?? 2} and let the rest breathe on the page.` });
+    if (bodyCount >= 4 && surfaces.size === 1 && !hasImagery)
+        add(undefined, { severity: "info", code: "monotone-page", message: "Every section has the same background and there is no imagery; vary one surface or add a photo." });
+    const completeness = {};
+    if (locales.length > 1)
+        for (const l of locales)
+            completeness[l] = localizedTotal ? Math.round(((filled[l] ?? 0) / localizedTotal) * 100) : 100;
+    return { issues, completeness, errorCount: issues.filter((i) => i.severity === "error").length, warningCount: issues.filter((i) => i.severity === "warning").length };
+}

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

@@ -0,0 +1,20 @@
+import type { z } from "zod";
+import { type LocaleCode } from "./localized.js";
+import type { BlockNode } from "./types.js";
+import type { BlockRegistry } from "./define-block.js";
+export interface LocalizeOptions {
+    locale: LocaleCode;
+    /** Tried after `locale`. Default `["en"]`. */
+    fallback?: readonly LocaleCode[];
+}
+/** Localizes a props object with its schema. */
+export declare function localizeProps<T = unknown>(schema: z.ZodType, props: unknown, opts: LocalizeOptions): T;
+/**
+ * Localizes one node (props, theme background alt, child slots). Unknown types are returned
+ * unchanged. `schema` may be the block's props schema or a registry.
+ *
+ * ```ts
+ * localize(node, siteBlocks, { locale: "tr", fallback: ["en"] });
+ * ```
+ */
+export declare function localize(node: BlockNode, source: BlockRegistry | z.ZodType | undefined, opts: LocalizeOptions): BlockNode;

package/dist/blocks/schema/localize.js

@@ -0,0 +1,29 @@
+// localize(): turns Localized<T> props into plain values for one locale (D2a). Components never
+// see locale maps. Deterministic fallback chain: locale → base language → fallbacks → first.
+import { pickLocale } from "./localized.js";
+import { mapFields } from "./walk.js";
+import { BlockThemeSchema } from "./nodes.js";
+/** Localizes a props object with its schema. */
+export function localizeProps(schema, props, opts) {
+    return mapFields(schema, props, (v) => (v.localized ? { replace: pickLocale(v.value, opts.locale, { fallback: opts.fallback }) } : undefined));
+}
+/**
+ * Localizes one node (props, theme background alt, child slots). Unknown types are returned
+ * unchanged. `schema` may be the block's props schema or a registry.
+ *
+ * ```ts
+ * localize(node, siteBlocks, { locale: "tr", fallback: ["en"] });
+ * ```
+ */
+export function localize(node, source, opts) {
+    const schema = !source ? undefined : "definitions" in source ? source.get(node.type)?.schema : source;
+    const out = { ...node };
+    if (schema && node.props !== undefined)
+        out.props = localizeProps(schema, node.props, opts);
+    if (node.theme)
+        out.theme = localizeProps(BlockThemeSchema, node.theme, opts);
+    if (node.slots && source && "definitions" in source) {
+        out.slots = Object.fromEntries(Object.entries(node.slots).map(([k, list]) => [k, list.map((c) => localize(c, source, opts))]));
+    }
+    return out;
+}

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

@@ -0,0 +1,25 @@
+/** BCP 47-ish locale key: `en`, `tr`, `en-GB`, `pt-BR`, `zh-Hant`. */
+export type LocaleCode = string;
+/** `"Book a table"` or `{ en: "Book a table", tr: "Masa ayırtın" }`. */
+export type Localized<T> = T | Partial<Record<LocaleCode, T>>;
+export declare const LOCALE_KEY_RE: RegExp;
+/** True when `value` is a locale map (`{ en: …, tr: … }`) rather than a value of T. */
+export declare function isLocaleMap(value: unknown): value is Record<LocaleCode, unknown>;
+export interface PickLocaleOptions {
+    /** Tried in order after `locale`. Default `["en"]`. */
+    fallback?: readonly LocaleCode[];
+}
+/** The locale chain used by `pickLocale`: exact → base language → each fallback (exact → base). */
+export declare function localeChain(locale: LocaleCode, fallback?: readonly LocaleCode[]): LocaleCode[];
+/**
+ * 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 declare function pickLocale<T>(value: Localized<T> | undefined, locale: LocaleCode, opts?: PickLocaleOptions): T | undefined;
+/** Locales present (non-empty) in a localized value. A plain value counts as every locale. */
+export declare function localesOf(value: unknown): LocaleCode[] | "all";