@caltho/site-kit 0.2.10 → 0.3.0

package/dist/migrate.js

@@ -0,0 +1,284 @@
+// Moving a site's own code to what a new kit expects, as text: CalOS reads a site's files from its
+// repository, runs the migrations it hasn't had, and commits what they change on the kit update's
+// branch, never main, so Cloudflare builds it as a preview first and it goes live only once that built.
+// Nothing here runs the site's code, and a migration changes a file only where it's exactly the
+// starter's (a known version, or a known block within it): a file the site has made its own is
+// left as it is and the migration reported for a person, who moves it by hand. What a site has had
+// is kept in its repository (.caltho/migrations.json), so each runs once.
+export const MIGRATIONS_FILE = ".caltho/migrations.json";
+async function sha256(text) {
+    const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+// The starter's own header, footer and menu group, every version it has shipped.
+const STARTER_FRAME_FILES = {
+    "components/Header.tsx": [
+        "0bf8abc156b59a5e6302921a7b0a16d4d391f519ee595de61e039aeb4b92ac92",
+        "4b101f874022fe290f659dd519849cc89b79c68791e8bc92386ae86718902bf5",
+        "e4ff7a7f332919c3611bf55f1fe7a29877b24445d164ab99f2875121af3895b9",
+    ],
+    "components/Footer.tsx": ["7971cfd0c2bdf4cef2a69871869dcc90c678bd272d43ce0ac6c8adf45ee8cf54", "88d6efc19fe636fe8c517faa303b4e05ede779942c2d07a3c551011d969873b4"],
+    "components/MenuGroup.tsx": ["4f2e53fbd9bc5fdf3c9e033e28f4e6582470a70a4e05ac51270a233a05345aa8"],
+};
+const OLD_FRAME = `export function Frame({ site, current, children }: { site: Content; current: string; children: ReactNode }) {
+  return (
+    <>
+      <a className="skip" href="#main">
+        Skip to content
+      </a>
+      <Header site={site} current={current} />
+      <main id="main" tabIndex={-1}>
+        {children}
+      </main>
+      <Footer site={site} />
+    </>
+  );
+}`;
+const NEW_FRAME = `/**
+ * The frame around every page: the kit's (skip link, header, footer), so a new header or footer
+ * option reaches this site with a kit release. A site with a header of its own passes it:
+ * <KitFrame header={<MyHeader … />}>, and leaves \`header\` out of content/look.ts unless it follows
+ * the Look's Header (headerOf).
+ */
+export function Frame({ site, current, children }: { site: Content; current: string; children: ReactNode }) {
+  return (
+    <KitFrame site={site} current={current} look={look}>
+      {children}
+    </KitFrame>
+  );
+}`;
+/**
+ * The starter's header and footer become the kit's (KitFrame), which follow the Look's Header, so
+ * the site's look.ts lists one and CalOS offers its options. The starter's footer was its Slate:
+ * kept, where the site's CSS has --dark. The old header and footer CSS is left, unused.
+ */
+/** The starter's design, told to the kit's frame: its dark footer and its words on it, and its buttons' weight. */
+const FRAME_CSS = `/* The kit draws the header and footer (KitFrame): in this design's dark, its buttons as its own. */
+:root {
+  --kit-footer-bg: var(--dark);
+  --kit-footer-fg: var(--on-dark);
+  --kit-footer-muted: var(--muted-on-dark);
+  --kit-footer-line: var(--line-on-dark);
+  --kit-button-weight: var(--b-weight);
+}
+`;
+const kitFrame = {
+    id: "kit-frame",
+    since: "0.2.11",
+    title: "The header and footer are the kit's (KitFrame), so new header and footer options reach this site with kit releases",
+    async run(read) {
+        const page = await read("components/SitePage.tsx");
+        if (!page)
+            return { manual: "it has no components/SitePage.tsx: its pages are drawn its own way" };
+        if (page.includes("KitFrame"))
+            return { done: true };
+        if (!page.includes(OLD_FRAME))
+            return { manual: "its components/SitePage.tsx draws the frame its own way (not the starter's Frame)" };
+        for (const [path, known] of Object.entries(STARTER_FRAME_FILES)) {
+            const text = await read(path);
+            if (text !== null && !known.includes(await sha256(text)))
+                return { manual: `its ${path} is its own, not the starter's` };
+        }
+        const look = await read("content/look.ts");
+        if (!look || !/export const look: LookOptions = \{[\s\S]*\n\};\s*$/.test(look))
+            return { manual: "its content/look.ts isn't the starter's shape" };
+        const imports = /import \{([^}]*)\} from "@caltho\/site-kit\/next";/;
+        const m = page.match(imports);
+        if (!m)
+            return { manual: "its components/SitePage.tsx doesn't import from @caltho/site-kit/next" };
+        const names = [...new Set([...m[1].split(",").map((x) => x.trim()).filter(Boolean), "KitFrame"])].sort((a, b) => a.localeCompare(b));
+        let nextPage = page
+            .replace(OLD_FRAME, NEW_FRAME)
+            .replace(imports, `import { ${names.join(", ")} } from "@caltho/site-kit/next";`)
+            .replace('import { Footer } from "./Footer";\n', "")
+            .replace('import { Header } from "./Header";\n', "");
+        if (!nextPage.includes('from "@/content/look"'))
+            nextPage = nextPage.replace(imports, (line) => `${line}\nimport { look } from "@/content/look";`);
+        const files = [{ path: "components/SitePage.tsx", text: nextPage }];
+        if (!/^\s*header:/m.test(look)) {
+            files.push({
+                path: "content/look.ts",
+                text: look.replace(/\n\};\s*$/, `\n  /** The kit's header (KitFrame) follows the Look's Header, so CalOS offers its options: sticky, with a line under it, name left and menu right to start. */\n  header: { sticky: true, style: "line", layout: "spread" },\n};\n`),
+            });
+        }
+        const css = await read("app/globals.css");
+        if (css && /--dark\s*:/.test(css) && !css.includes("--kit-footer-bg")) {
+            files.push({ path: "app/globals.css", text: `${css.replace(/\s*$/, "")}\n\n${FRAME_CSS}` });
+        }
+        for (const path of Object.keys(STARTER_FRAME_FILES))
+            if ((await read(path)) !== null)
+                files.push({ path, remove: true });
+        return { files };
+    },
+};
+const ACCENT_CSS = `/* The accent colour: a button that stands out on a photo or a dark band (an action's style "accent"). */
+.btn-accent {
+  background: var(--look-accent, var(--accent));
+  border-color: var(--look-accent, var(--accent));
+  color: var(--look-on-accent, var(--ink));
+}
+.btn-accent:hover {
+  background: color-mix(in srgb, var(--look-accent, var(--accent)) 88%, #000000);
+}
+`;
+/**
+ * Actions may be in the accent colour (style "accent"), which the starter's design draws as
+ * .btn-accent: added to a site whose CSS has the starter's buttons (.btn-primary) and none yet.
+ */
+const accentButtons = {
+    id: "accent-buttons",
+    since: "0.2.11",
+    title: "Buttons in the accent colour: an action's style can be the accent, for one that stands out on a photo or a dark band",
+    async run(read) {
+        const css = await read("app/globals.css");
+        if (!css)
+            return { manual: "it has no app/globals.css" };
+        if (css.includes(".btn-accent"))
+            return { done: true };
+        if (!css.includes(".btn-primary {"))
+            return { manual: "its buttons aren't the starter's (.btn-primary): it draws an accent button its own way" };
+        return { files: [{ path: "app/globals.css", text: `${css.replace(/\s*$/, "")}\n\n${ACCENT_CSS}` }] };
+    },
+};
+/** The starter's dark, a palette colour the business may remove (Cal does, building from a picture). */
+const STARTER_DARK = "--dark:var(--look-swatch-slate, #1d2a33);";
+/**
+ * The design's dark (its dark sections and the footer) following the theme when the business has
+ * taken its Slate away: the theme's own dark (the darker of its page and text), not a navy no
+ * colour in the theme shows.
+ */
+const darkFollowsLook = {
+    id: "dark-follows-look",
+    since: "0.2.11",
+    title: "The design's dark follows the theme: with its Slate colour removed, dark sections and the footer take the theme's own dark, not a hidden navy",
+    async run(read) {
+        const css = await read("app/globals.css");
+        if (!css)
+            return { manual: "it has no app/globals.css" };
+        if (css.includes("--dark:var(--look-swatch-slate, var(--look-dark"))
+            return { done: true };
+        if (!css.includes(STARTER_DARK))
+            return { manual: "its dark isn't the starter's (--dark from Slate): it draws its dark its own way" };
+        return { files: [{ path: "app/globals.css", text: css.replace(STARTER_DARK, "--dark:var(--look-swatch-slate, var(--look-dark, #1d2a33));") }] };
+    },
+};
+/** The starter's buttons' border, before and after it reads the Look's button border (width and colour). */
+const BUTTON_BORDER = [
+    ["  border: 2px solid transparent;\n  border-radius: var(--radius-button);", "  border: var(--look-button-border-width, 2px) solid transparent;\n  border-radius: var(--radius-button);"],
+    ["  border-color: color-mix(in srgb, var(--brand-fill) var(--fill), var(--c-link));", "  border-color: var(--look-button-border-colour, color-mix(in srgb, var(--brand-fill) var(--fill), var(--c-link)));"],
+    ["  border-color: var(--look-accent, var(--accent));\n  color: var(--look-on-accent, var(--ink));", "  border-color: var(--look-button-border-colour, var(--look-accent, var(--accent)));\n  color: var(--look-on-accent, var(--ink));"],
+    ["  border-color: var(--on-brand);\n  color: color-mix(in srgb, var(--brand-fill) var(--fill), var(--on-brand));", "  border-color: var(--look-button-border-colour, var(--on-brand));\n  color: color-mix(in srgb, var(--brand-fill) var(--fill), var(--on-brand));"],
+];
+/**
+ * Buttons with the Look's border: its width and colour, where the business chooses one (a dark
+ * outline on a yellow button). Every line the starter's, or it's left for a person.
+ */
+const buttonBorders = {
+    id: "button-borders",
+    since: "0.2.11",
+    title: "Button borders: the Look's button border (its width and colour) on the site's buttons",
+    async run(read) {
+        const css = await read("app/globals.css");
+        if (!css)
+            return { manual: "it has no app/globals.css" };
+        if (css.includes("--look-button-border-width"))
+            return { done: true };
+        if (!BUTTON_BORDER.every(([from]) => css.includes(from)))
+            return { manual: "its buttons aren't the starter's: it draws their borders its own way" };
+        return { files: [{ path: "app/globals.css", text: BUTTON_BORDER.reduce((t, [from, to]) => t.replace(from, to), css) }] };
+    },
+};
+/** The starter's own font imports, which the kit's fonts.css takes the place of. */
+const STARTER_FONT_IMPORTS = /^import "@fontsource\/(fraunces|inter)\/latin-\d+\.css";\n/gm;
+const STARTER_FONTS_LINE = `  fonts: { Inter: '"Inter", system-ui, Arial, sans-serif', Fraunces: '"Fraunces", Georgia, serif' },`;
+/**
+ * The kit's fonts (fonts.css: ten variable families, every weight) in place of the starter's two
+ * fixed-weight ones, and listed in the site's look so the business can pick any of them. Where the
+ * site loads fonts of its own, or lists its own, it's left for a person.
+ */
+const kitFonts = {
+    id: "kit-fonts",
+    since: "0.2.11",
+    title: "The kit's fonts: ten variable families with every weight, any of them a choice in the site's Look",
+    async run(read) {
+        const layout = await read("app/layout.tsx");
+        const look = await read("content/look.ts");
+        if (!layout || !look)
+            return { manual: "it has no app/layout.tsx or content/look.ts like the starter's" };
+        if (layout.includes("@caltho/site-kit/fonts.css"))
+            return { done: true };
+        const own = layout.match(/^import "@fontsource[^"]*";$/gm) ?? [];
+        if (!own.length || own.some((l) => !/^import "@fontsource\/(fraunces|inter)\/latin-\d+\.css";$/.test(l)))
+            return { manual: "its app/layout.tsx loads fonts of its own" };
+        if (!look.includes(STARTER_FONTS_LINE))
+            return { manual: "its content/look.ts lists fonts of its own" };
+        const nextLayout = layout.replace(STARTER_FONT_IMPORTS, "").replace('import "@caltho/site-kit/sections.css";', 'import "@caltho/site-kit/sections.css";\nimport "@caltho/site-kit/fonts.css";');
+        if (!nextLayout.includes("@caltho/site-kit/fonts.css"))
+            return { manual: "its app/layout.tsx doesn't import the kit's sections.css, where the fonts go beside it" };
+        const files = [
+            { path: "app/layout.tsx", text: nextLayout },
+            {
+                path: "content/look.ts",
+                text: look
+                    .replace(STARTER_FONTS_LINE, "  fonts: KIT_FONTS,")
+                    .replace('import type { LookOptions } from "@caltho/site-kit/content";', 'import { KIT_FONTS, type LookOptions } from "@caltho/site-kit/content";'),
+            },
+        ];
+        const css = await read("app/globals.css");
+        if (css)
+            files.push({ path: "app/globals.css", text: css.replace('--font-body: "Inter";', '--font-body: "Inter Variable";').replace('--font-display: "Fraunces";', '--font-display: "Fraunces Variable";') });
+        const pkg = await read("package.json");
+        if (pkg)
+            files.push({ path: "package.json", text: pkg.replace(/^\s*"@fontsource\/(fraunces|inter)": "[^"]*",\n/gm, "") });
+        return { files };
+    },
+};
+/** Every migration, oldest first. */
+export const MIGRATIONS = [kitFrame, accentButtons, kitFonts, darkFollowsLook, buttonBorders];
+const parts = (v) => v.split(".").map(Number);
+function atLeast(v, min) {
+    const [a, b] = [parts(v), parts(min)];
+    for (let i = 0; i < 3; i++)
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    return true;
+}
+/**
+ * What moving a site to kit `version` changes in its own files: each migration up to that version it
+ * hasn't had, in order, each seeing the files as the ones before it left them.
+ */
+export async function migrateSite(read, version, migrations = MIGRATIONS) {
+    const recorded = await read(MIGRATIONS_FILE);
+    let had = [];
+    try {
+        const parsed = recorded ? JSON.parse(recorded) : null;
+        if (Array.isArray(parsed?.applied))
+            had = parsed.applied.filter((x) => typeof x === "string");
+    }
+    catch {
+        // An unreadable record: as if none, each migration checking the files for itself.
+    }
+    const changed = new Map();
+    const view = async (path) => {
+        const c = changed.get(path);
+        return c ? ("remove" in c ? null : c.text) : read(path);
+    };
+    const applied = [];
+    const manual = [];
+    for (const m of migrations) {
+        if (had.includes(m.id) || !atLeast(version, m.since))
+            continue;
+        const r = await m.run(view);
+        if ("manual" in r) {
+            manual.push({ id: m.id, title: m.title, why: r.manual });
+            continue;
+        }
+        if ("files" in r)
+            for (const f of r.files)
+                changed.set(f.path, f);
+        applied.push({ id: m.id, title: m.title });
+    }
+    if (applied.length)
+        changed.set(MIGRATIONS_FILE, { path: MIGRATIONS_FILE, text: `${JSON.stringify({ applied: [...had, ...applied.map((a) => a.id)] }, null, 2)}\n` });
+    return { files: [...changed.values()], applied, manual };
+}

package/dist/next/block-mark.d.ts

@@ -0,0 +1,7 @@
+/** True inside CalOS's preview (SitePreview provides it). */
+export declare const InPreview: import("react").Context<boolean>;
+/** The attribute a block's mark carries: the block's index on its page. */
+export declare const BLOCK_MARK = "data-calos-block";
+export declare function BlockMark({ at }: {
+    at: number;
+}): import("react").JSX.Element | null;

package/dist/next/block-mark.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// Where each block starts, for CalOS's preview: a site puts <BlockMark at={i} /> before each block it
+// draws, and the preview knows exactly what each block drew (none, one, or several elements), with
+// nothing guessed from the words. On the live site it draws nothing; in the preview, an empty
+// <template>, which the browser never shows and styles never see as drawn.
+import { createContext, useContext } from "react";
+/** True inside CalOS's preview (SitePreview provides it). */
+export const InPreview = createContext(false);
+/** The attribute a block's mark carries: the block's index on its page. */
+export const BLOCK_MARK = "data-calos-block";
+export function BlockMark({ at }) {
+    if (!useContext(InPreview))
+        return null;
+    return _jsx("template", { [BLOCK_MARK]: String(at) });
+}

package/dist/next/blocks.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from "react";
+import { type KitBlock, type KitClasses } from "./sections.tsx";
+export declare function KitBlocks<B extends KitBlock>({ blocks, render, classes, level, }: {
+    blocks: readonly B[];
+    /** The site's own component for a block, or null (or undefined) for a kind it leaves to the kit. */
+    render: (block: B, i: number) => ReactNode | null | undefined;
+    /** Classes of the site's own for kit sections, in place of the kit's (KitSection). */
+    classes?: Partial<KitClasses>;
+    /** The heading level of a block's own heading: 1 for the one that carries the page's h1. */
+    level?: (i: number) => number;
+}): import("react").JSX.Element;

package/dist/next/blocks.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// A page's blocks drawn, the same way on every site: each after its mark (BlockMark, for CalOS's
+// preview), in a frame when its Layout has a background (a colour, or a photo under a shade), then
+// the site's own component for it, else the kit's (KitSection). A site hands it how it draws its own
+// kinds (`render`), and nothing else: a block whose kind it doesn't draw (one the business put
+// together in CalOS, a slideshow, one the kit adds later) is drawn by the kit in the site's Look.
+//
+// Classes only, no style attribute (the content security policy blocks them): the frame's colour is
+// a class (sections.css reads the Look's variables), and its words go light by a class when its
+// background is dark, worked out from the Look's colour values (lookValues: at build, and as sent
+// in the preview).
+import { Fragment } from "react";
+import { frameClass, hasBackground, linesClass } from "../content/index.js";
+import { BlockMark } from "./block-mark.js";
+import { lookValues } from "./data.js";
+import { Img } from "./parts/Img.js";
+import { KitSection } from "./sections.js";
+export function KitBlocks({ blocks, render, classes, level = () => 2, }) {
+    const vars = lookValues();
+    return (_jsx(_Fragment, { children: blocks.map((block, i) => {
+            const own = render(block, i);
+            const drawn = own ?? _jsx(KitSection, { s: block, level: level(i), classes: classes });
+            return (_jsxs(Fragment, { children: [_jsx(BlockMark, { at: i }), lined(block, hasBackground(block) ? _jsx(Frame, { block: block, vars: vars, children: drawn }) : drawn)] }, i));
+        }) }));
+}
+/** A section between lines across the page's full width, where its Layout says. */
+function lined(block, drawn) {
+    const cls = linesClass(block);
+    return cls ? _jsx("div", { className: cls, children: drawn }) : drawn;
+}
+/** What's behind a section: its colour, and a photo under a shade, the section drawn over them. */
+function Frame({ block, vars, children }) {
+    const bg = block.placement?.background;
+    return (_jsxs("div", { className: frameClass(block, vars), children: [bg?.photo?.src && (_jsx("div", { className: "kit-frame-bg", "aria-hidden": "true", children: _jsx(Img, { src: bg.photo.src, alt: "", sizes: "100vw" }) })), children] }));
+}

package/dist/next/built.d.ts

@@ -0,0 +1,40 @@
+import { type ImageRef } from "../tree/index.ts";
+import type { KitBlock } from "./sections.tsx";
+/** What a slot of a component is filled with where it's used. */
+type Fill = {
+    text?: string;
+    href?: string;
+    image?: ImageRef;
+};
+/** A built section: its tree, the block's id and Layout on its root. */
+export declare function BuiltSection({ s }: {
+    s: KitBlock;
+}): import("react").JSX.Element | null;
+/** A component used by name, its slots filled; nothing (a quiet box in the preview) when the site has no such component. */
+export declare function UseSection({ s }: {
+    s: KitBlock;
+}): import("react").JSX.Element | null;
+/**
+ * One of the site's components drawn outside a page's blocks (a cookie banner's design): its slots
+ * filled, the kit's attributes on the elements of the slots named in `marks`. Nothing for a
+ * component the site hasn't.
+ */
+export declare function ComponentTree({ name, slots, marks }: {
+    name: string;
+    slots: Record<string, Fill>;
+    marks?: Record<string, Record<string, string>>;
+}): import("react").JSX.Element | null;
+/**
+ * The site's own header or footer (content's ownHeader, ownFooter): its tree drawn as a built
+ * section's, its links to the page it's on marked (aria-current).
+ */
+export declare function BuiltFrame({ tree, current, which }: {
+    tree: {
+        root?: unknown;
+    };
+    current: string;
+    which?: "header" | "footer";
+}): import("react").JSX.Element | null;
+/** A bound value as a link: an email address is a mailto:, a phone number a tel: (dialled as its digits), anything else as it is. */
+export declare function linkFor(v: string): string;
+export {};