@caltho/site-kit 0.2.10 → 0.3.0

package/dist/tree/index.d.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { behavior } from "./behaviors.ts";
+export { checkClasses, classProblem, classTokens, safeClasses, splitVariants, VARIANTS, type ClassCheck } from "./classes.ts";
+export { behavior, BEHAVIORS, type Behavior, type BehaviorName } from "./behaviors.ts";
+export * from "./messages.ts";
+/** The elements a tree may hold: what a page's sections are made of, never script, style or embeds. */
+export declare const TAGS: readonly ["section", "div", "header", "footer", "nav", "article", "aside", "h1", "h2", "h3", "h4", "h5", "h6", "p", "span", "strong", "em", "small", "a", "button", "ul", "ol", "li", "figure", "figcaption", "img", "blockquote", "hr", "br", "icon", "video", "form", "label", "input", "textarea", "select", "option"];
+export type Tag = (typeof TAGS)[number];
+/** Elements that hold no children and no words. */
+export declare const VOID_TAGS: readonly Tag[];
+/** A form's fields: an input, a longer one, a list of choices. Each only inside a form. */
+export declare const FIELD_TAGS: readonly Tag[];
+/** What a field holds: the kinds of input a visitor fills in or picks. */
+export declare const INPUT_KINDS: readonly ["text", "email", "tel", "number", "date", "url", "checkbox", "radio"];
+/**
+ * A form field's own settings: the name its answer is sent as (CalOS takes each by its name: email,
+ * phone, name, message, or a field's key), what it holds, whether it must be filled, the words shown
+ * while it's empty, and a radio's or checkbox's value. Never a name starting _ (the kit's own: its spam trap).
+ */
+export declare const fieldSpec: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        number: "number";
+        date: "date";
+        text: "text";
+        email: "email";
+        tel: "tel";
+        url: "url";
+        checkbox: "checkbox";
+        radio: "radio";
+    }>>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    rows: z.ZodOptional<z.ZodNumber>;
+    checked: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type FieldSpec = z.infer<typeof fieldSpec>;
+/** How deep a tree goes, how many nodes it has, how long a node's classes and words are. */
+export declare const LIMITS: {
+    readonly depth: 16;
+    readonly nodes: 600;
+    readonly classLength: 1200;
+    readonly textLength: 4000;
+};
+/** A node's stable id: made by CalOS when a node is added, kept as it moves; the preview reports clicks by it. */
+export declare const nodeId: z.ZodString;
+/** Where a link goes: a page of the site, a part of a page, or another site over https. Nothing else (no javascript:, data:). */
+export declare const safeHref: z.ZodString;
+export declare const imageRef: z.ZodObject<{
+    src: z.ZodString;
+    alt: z.ZodDefault<z.ZodString>;
+    phoneSrc: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ImageRef = z.infer<typeof imageRef>;
+/**
+ * Shared content a node reads: a dotted path into the site's content ("company.email",
+ * "caseStudies"). With `repeat`, a list whose items the node is copied for; inside it, `bind` paths
+ * starting with "item." read the item ("item.name").
+ */
+export declare const contentPath: z.ZodString;
+export type Node = {
+    id: string;
+    tag: Tag;
+    /** Tailwind classes (classes.ts says which are allowed). */
+    class?: string;
+    /** Its words, light Markdown (bold, italic, links). Not on void tags. */
+    text?: string;
+    href?: string;
+    /** Opens in a new tab (an outside link). */
+    external?: boolean;
+    image?: ImageRef;
+    /** icon: a name from the kit's icon set (../sections/icons.ts). */
+    icon?: string;
+    /** video: a YouTube or Vimeo video by its id; the kit builds the embed's address itself. */
+    video?: {
+        provider: "youtube" | "vimeo";
+        id: string;
+    };
+    /** What it's called in the editor's layers ("Slide", "Card"); its tag otherwise. */
+    name?: string;
+    /** Shows a shared value in place of `text`, `href` or `image` (whichever the value is). */
+    bind?: {
+        path: string;
+        as?: "text" | "href" | "image";
+    };
+    /** One copy of this node per item of a shared list; inside, binds start with "item.". */
+    repeat?: {
+        path: string;
+        limit?: number;
+    };
+    behavior?: z.infer<typeof behavior>;
+    /** A slot of a component, filled where it's used ({ type: "use" } blocks). */
+    slot?: string;
+    /** Hidden on the page, kept in the tree (a draft part). */
+    hidden?: boolean;
+    /** Accessibility: its label where its words don't say what it is (an icon button). */
+    label?: string;
+    /** A form field's settings (input, textarea, select). */
+    field?: FieldSpec;
+    /** A label: the field it names, by its id (in the same tree). */
+    for?: string;
+    /** A form's: the business's form it sends to, by key. */
+    sendTo?: string;
+    children?: Node[];
+};
+export declare const node: z.ZodType<Node>;
+/** Problems with a whole tree beyond each node's own: depth, size, ids used twice. */
+export declare function treeProblems(root: Node): string[];
+/** The section: a tree, as a block of a page. */
+export declare const built: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    root: z.ZodType<Node, unknown, z.core.$ZodTypeInternals<Node, unknown>>;
+}, z.core.$strip>;
+/** A tree kept once and used by name, its slots filled where it's used. */
+export declare const component: z.ZodObject<{
+    key: z.ZodString;
+    name: z.ZodString;
+    root: z.ZodType<Node, unknown, z.core.$ZodTypeInternals<Node, unknown>>;
+}, z.core.$strip>;
+export type Component = z.infer<typeof component>;
+/** A use of a component: its slots' words, links and pictures. */
+export declare const use: z.ZodObject<{
+    component: z.ZodString;
+    slots: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        text: z.ZodOptional<z.ZodString>;
+        href: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            alt: z.ZodDefault<z.ZodString>;
+            phoneSrc: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Every node of a tree, depth first, with its parent and place. */
+export declare function walk(root: Node, parent?: Node | null, index?: number): Generator<{
+    node: Node;
+    parent: Node | null;
+    index: number;
+    depth: number;
+}>;
+/** The node with this id, if the tree has it. */
+export declare function findNode(root: Node, id: string): Node | null;
+/** A new node id, as CalOS makes them. */
+export declare function newNodeId(): string;

package/dist/tree/index.js

@@ -0,0 +1,196 @@
+// A section built in CalOS as a tree of elements styled with Tailwind (cal-os docs/design/site-builder.md):
+// anything a designer builds with HTML and Tailwind, a business (or Cal for it) builds and changes
+// without code. This file is the contract every side keeps to: the kit draws a tree (server and
+// preview), CalOS edits it, Cal proposes changes to it, and all of them check it the same way.
+//
+// A tree is content like any other block: { type: "built", root: Node }. A component is a tree kept
+// once in the site's content (`components`) and used by name with its slots filled.
+import { z } from "zod";
+import { checkClasses } from "./classes.js";
+import { behavior } from "./behaviors.js";
+export { checkClasses, classProblem, classTokens, safeClasses, splitVariants, VARIANTS } from "./classes.js";
+export { behavior, BEHAVIORS } from "./behaviors.js";
+export * from "./messages.js";
+/** The elements a tree may hold: what a page's sections are made of, never script, style or embeds. */
+export const TAGS = ["section", "div", "header", "footer", "nav", "article", "aside", "h1", "h2", "h3", "h4", "h5", "h6", "p", "span", "strong", "em", "small", "a", "button", "ul", "ol", "li", "figure", "figcaption", "img", "blockquote", "hr", "br", "icon", "video", "form", "label", "input", "textarea", "select", "option"];
+/** Elements that hold no children and no words. */
+export const VOID_TAGS = ["img", "hr", "br", "icon", "video", "input", "textarea"];
+/** A form's fields: an input, a longer one, a list of choices. Each only inside a form. */
+export const FIELD_TAGS = ["input", "textarea", "select"];
+/** What a field holds: the kinds of input a visitor fills in or picks. */
+export const INPUT_KINDS = ["text", "email", "tel", "number", "date", "url", "checkbox", "radio"];
+/**
+ * A form field's own settings: the name its answer is sent as (CalOS takes each by its name: email,
+ * phone, name, message, or a field's key), what it holds, whether it must be filled, the words shown
+ * while it's empty, and a radio's or checkbox's value. Never a name starting _ (the kit's own: its spam trap).
+ */
+export const fieldSpec = z
+    .object({
+    name: z.string().regex(/^[a-z][a-z0-9_]{0,39}$/, { error: "A field's name is lowercase letters, numbers and _, like email or best_time" }),
+    type: z.enum(INPUT_KINDS).optional(),
+    required: z.boolean().optional(),
+    placeholder: z.string().max(120).optional(),
+    value: z.string().max(120).optional(),
+    rows: z.number().int().min(2).max(20).optional(),
+    /** A tick box or a choice (radio): chosen at first. */
+    checked: z.boolean().optional(),
+})
+    .strict();
+/** How deep a tree goes, how many nodes it has, how long a node's classes and words are. */
+export const LIMITS = { depth: 16, nodes: 600, classLength: 1200, textLength: 4000 };
+/** A node's stable id: made by CalOS when a node is added, kept as it moves; the preview reports clicks by it. */
+export const nodeId = z.string().regex(/^[a-z0-9]{6,24}$/);
+/** Where a link goes: a page of the site, a part of a page, or another site over https. Nothing else (no javascript:, data:). */
+export const safeHref = z
+    .string()
+    .max(500)
+    .refine((h) => /^\/(?!\/)[^\s]*$/.test(h) || /^#[\w-]+$/.test(h) || /^https?:\/\/[^\s]+$/i.test(h) || /^(mailto|tel):[^\s]+$/i.test(h), "A page path, #part, http(s) address, mailto: or tel:");
+/** A picture: one of the site's own (uploads/… or its own public files), never another site's address. */
+const ownPicture = z.string().max(500).refine((s) => !/^[a-z][a-z0-9+.-]*:/i.test(s) && !s.startsWith("//"), "One of the site's own pictures");
+export const imageRef = z.object({
+    src: ownPicture,
+    alt: z.string().max(300).default(""),
+    /** Another picture of the same thing for phones (a tall screenshot of the phone layout), shown on small screens in its place. */
+    phoneSrc: ownPicture.optional(),
+});
+/**
+ * Shared content a node reads: a dotted path into the site's content ("company.email",
+ * "caseStudies"). With `repeat`, a list whose items the node is copied for; inside it, `bind` paths
+ * starting with "item." read the item ("item.name").
+ */
+export const contentPath = z.string().regex(/^(item\.)?[a-zA-Z][\w]*(\.[a-zA-Z0-9_]+)*$/).max(120);
+const classes = z
+    .string()
+    .max(LIMITS.classLength)
+    .superRefine((c, ctx) => {
+    const r = checkClasses(c);
+    if (!r.ok)
+        ctx.addIssue({ code: "custom", message: `Not allowed: ${r.bad.map((b) => `${b.token} (${b.why})`).join(", ")}` });
+});
+export const node = z.lazy(() => z
+    .object({
+    id: nodeId,
+    tag: z.enum(TAGS),
+    class: classes.optional(),
+    text: z.string().max(LIMITS.textLength).optional(),
+    href: safeHref.optional(),
+    external: z.boolean().optional(),
+    image: imageRef.optional(),
+    icon: z.string().max(60).optional(),
+    video: z.object({ provider: z.enum(["youtube", "vimeo"]), id: z.string().regex(/^[\w-]{6,20}$/) }).strict().optional(),
+    name: z.string().max(60).optional(),
+    bind: z.object({ path: contentPath, as: z.enum(["text", "href", "image"]).optional() }).optional(),
+    repeat: z.object({ path: contentPath, limit: z.number().int().min(1).max(100).optional() }).optional(),
+    behavior: behavior.optional(),
+    slot: z.string().regex(/^[a-z][a-z0-9_]{0,39}$/).optional(),
+    hidden: z.boolean().optional(),
+    label: z.string().max(200).optional(),
+    field: fieldSpec.optional(),
+    for: nodeId.optional(),
+    /** A form's: which of the business's forms it sends to, by its key (contact), never an address. */
+    sendTo: z.string().regex(/^[a-z0-9][a-z0-9-]{0,59}$/, { error: "A form's key is lowercase letters, numbers and -, like contact" }).optional(),
+    children: z.array(node).max(200).optional(),
+})
+    .strict()
+    .superRefine((n, ctx) => {
+    if (VOID_TAGS.includes(n.tag) && (n.children?.length || n.text))
+        ctx.addIssue({ code: "custom", message: `A ${n.tag} holds no words or children` });
+    if (n.tag === "img" && !n.image && !n.bind)
+        ctx.addIssue({ code: "custom", message: "A picture needs its picture" });
+    if (n.tag === "icon" && !n.icon)
+        ctx.addIssue({ code: "custom", message: "An icon needs its name" });
+    if (FIELD_TAGS.includes(n.tag) && !n.field)
+        ctx.addIssue({ code: "custom", message: `A ${n.tag === "select" ? "list of choices" : "field"} needs its name (field.name)` });
+    if (n.field && !FIELD_TAGS.includes(n.tag))
+        ctx.addIssue({ code: "custom", message: "Only a form's fields (input, textarea, select) have field settings" });
+    if (n.sendTo && n.tag !== "form")
+        ctx.addIssue({ code: "custom", message: "Only a form sends to one of the business's forms (sendTo)" });
+    if (n.for && n.tag !== "label")
+        ctx.addIssue({ code: "custom", message: "Only a label names a field (for)" });
+    if (n.tag === "select" && n.children?.some((c) => c.tag !== "option"))
+        ctx.addIssue({ code: "custom", message: "A list of choices holds only its choices (option)" });
+}));
+/** Problems with a whole tree beyond each node's own: depth, size, ids used twice. */
+export function treeProblems(root) {
+    const out = [];
+    const seen = new Set();
+    let count = 0;
+    const fields = new Set();
+    const labels = [];
+    const walk = (n, depth, inForm = false) => {
+        count++;
+        if (depth > LIMITS.depth)
+            out.push(`Nested more than ${LIMITS.depth} deep at ${n.id}`);
+        // A form's parts belong in a form, and a form in no other.
+        if (n.tag === "form" && inForm)
+            out.push(`A form can't be inside another form (${n.id})`);
+        if ((FIELD_TAGS.includes(n.tag) || n.tag === "option") && !inForm && n.tag !== "option")
+            out.push(`A field belongs inside a form (${n.id})`);
+        if (FIELD_TAGS.includes(n.tag))
+            fields.add(n.id);
+        if (n.tag === "label" && n.for)
+            labels.push({ id: n.id, for: n.for });
+        if (seen.has(n.id))
+            out.push(`The id ${n.id} is used twice`);
+        seen.add(n.id);
+        for (const c of n.children ?? [])
+            walk(c, depth + 1, inForm || n.tag === "form");
+    };
+    walk(root, 1);
+    for (const l of labels)
+        if (!fields.has(l.for))
+            out.push(`The label ${l.id} names ${l.for}, which isn't a field of this tree`);
+    if (count > LIMITS.nodes)
+        out.push(`More than ${LIMITS.nodes} elements`);
+    return out;
+}
+/** The section: a tree, as a block of a page. */
+export const built = z
+    .object({
+    name: z.string().max(80).optional().meta({ title: "Name" }),
+    root: node,
+})
+    .superRefine((b, ctx) => {
+    for (const p of treeProblems(b.root))
+        ctx.addIssue({ code: "custom", message: p });
+})
+    .meta({ title: "Built section", description: "Built from elements and Tailwind classes, in the editor or by Cal" });
+/** A tree kept once and used by name, its slots filled where it's used. */
+export const component = z.object({
+    key: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/),
+    name: z.string().max(80),
+    root: node,
+});
+/** A use of a component: its slots' words, links and pictures. */
+export const use = z
+    .object({
+    component: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/),
+    slots: z.record(z.string(), z.object({ text: z.string().max(LIMITS.textLength).optional(), href: safeHref.optional(), image: imageRef.optional() })).default({}),
+})
+    .meta({ title: "Component", description: "One of the site's own components, its words and pictures filled in" });
+/** Every node of a tree, depth first, with its parent and place. */
+export function* walk(root, parent = null, index = 0) {
+    const stack = [{ node: root, parent, index, depth: 0 }];
+    while (stack.length) {
+        const at = stack.pop();
+        yield at;
+        const kids = at.node.children ?? [];
+        for (let i = kids.length - 1; i >= 0; i--)
+            stack.push({ node: kids[i], parent: at.node, index: i, depth: at.depth + 1 });
+    }
+}
+/** The node with this id, if the tree has it. */
+export function findNode(root, id) {
+    for (const { node: n } of walk(root))
+        if (n.id === id)
+            return n;
+    return null;
+}
+/** A new node id, as CalOS makes them. */
+export function newNodeId() {
+    const a = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let s = "";
+    for (let i = 0; i < 10; i++)
+        s += a[Math.floor(Math.random() * a.length)];
+    return s;
+}

package/dist/tree/messages.d.ts

@@ -0,0 +1,45 @@
+/** From the preview to CalOS. */
+export type PreviewToEditor = 
+/** An element of a built section was clicked: its block's place on the page and its node's id. */
+{
+    type: "calos:built-select";
+    block: number;
+    node: string;
+    shift: boolean;
+}
+/** The pointer is over an element (for the editor to outline it in its layers). */
+ | {
+    type: "calos:built-hover";
+    block: number;
+    node: string | null;
+}
+/** Where each built element sits on screen, for the editor's overlays (handles, spacing guides). */
+ | {
+    type: "calos:built-boxes";
+    block: number;
+    boxes: {
+        node: string;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }[];
+};
+/** From CalOS to the preview. */
+export type EditorToPreview = 
+/** Outline these nodes (the selection), scrolled into view. */
+{
+    type: "calos:built-highlight";
+    block: number;
+    nodes: string[];
+}
+/** Draw a node as hovered or focused, while its hover or focus classes are edited. */
+ | {
+    type: "calos:built-state";
+    block: number;
+    node: string;
+    state: "normal" | "hover" | "focus";
+};
+export declare const isPreviewToEditor: (m: unknown) => m is PreviewToEditor;
+/** The attribute that marks a built element with its node's id in the preview. */
+export declare const NODE_ATTR = "data-node";

package/dist/tree/messages.js

@@ -0,0 +1,7 @@
+// What CalOS's editor and the site's preview page (/calos-preview) say to each other about built
+// sections, by postMessage. The preview draws a tree with each element marked by its node's id
+// (data-node, in the preview only), so a click is never guessed from its words, as it is for a coded
+// section (../preview-match.ts).
+export const isPreviewToEditor = (m) => !!m && typeof m === "object" && typeof m.type === "string" && m.type.startsWith("calos:built-");
+/** The attribute that marks a built element with its node's id in the preview. */
+export const NODE_ATTR = "data-node";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caltho/site-kit",
-  "version": "0.2.10",
+  "version": "0.3.0",
   "description": "What every Caltho site is built with: the contract with CalOS (content, and how a site declares what is editable), images, search and security, and the checks",
   "license": "MIT",
   "type": "module",
@@ -49,22 +49,41 @@
       "types": "./dist/sections/index.d.ts",
       "default": "./dist/sections/index.js"
     },
-    "./sections.css": "./dist/sections.css"
+    "./tree": {
+      "types": "./dist/tree/index.d.ts",
+      "default": "./dist/tree/index.js"
+    },
+    "./content-migrate": {
+      "types": "./dist/content-migrate.d.ts",
+      "default": "./dist/content-migrate.js"
+    },
+    "./theme": {
+      "types": "./dist/built/theme.d.ts",
+      "default": "./dist/built/theme.js"
+    },
+    "./migrate": {
+      "types": "./dist/migrate.d.ts",
+      "default": "./dist/migrate.js"
+    },
+    "./sections.css": "./dist/sections.css",
+    "./fonts.css": "./dist/fonts.css"
   },
   "engines": {
     "node": ">=22.18"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -R src/fonts dist/fonts && cp src/sections.css dist/sections.css && chmod +x dist/cli/index.js",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/fonts && cp -R src/fonts/. dist/fonts/ && cp src/sections.css dist/sections.css && cp src/fonts.css dist/fonts.css && chmod +x dist/cli/index.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "bun test src",
     "prepack": "bun run build"
   },
   "dependencies": {
     "@resvg/resvg-js": "2.6.2",
+    "@tailwindcss/browser": "4.3.3",
     "marked": "18.1.0",
     "satori": "0.33.4",
     "sharp": "0.35.5",
+    "tailwindcss": "4.3.3",
     "zod": "4.6.7"
   },
   "peerDependencies": {