@caltho/site-kit 0.2.10 → 0.3.0

package/README.md

@@ -45,7 +45,11 @@ export default function CalosPreview() { return <Preview origins={previewOrigins
 
 Components read content only through the kit (`site()`, `image()`), so the same components draw the
 built pages (from `.site/prepared.json`) and the draft (from CalOS). A click on the preview is matched
-back to the field it meant with nothing added to the components. Only the business's own CalOS
+back to the field it meant with nothing added to the components. Which block a click landed in is
+exact where the page puts `<BlockMark at={i} />` (from `@caltho/site-kit/next`) before each block it
+draws: a block may then draw nothing (a list with nothing in it yet) or several elements. It draws
+nothing on the live site. Without marks, blocks are found among `main`'s children, by their words
+when there isn't one for each. Only the business's own CalOS
 addresses, which the build is given with the content, may frame the page or send it anything.
 
 Forms are separate and optional. A block can post to any address (a CalOS form, another service, or none);
@@ -62,7 +66,7 @@ the kit only checks it's a URL.
 | **Search** | Titles that fit, canonical addresses, the business as schema.org data (hours, areas, address), FAQ and breadcrumb data, robots.txt, the sitemap. |
 | **Policies** | Privacy, accessibility and terms, written from the business's facts and what the site does. Optional: a site calls `policy()` where it wants them. |
 | **Helpers for components** (`@caltho/site-kit/lib`) | The pieces that touch no files: `md` (Markdown that can't run HTML), `plain`, `policy`, the search data, `imagesIn`, `clock`, `dayRange`, `telHref`. |
-| **Next.js helpers** (`@caltho/site-kit/next`) | The prepared content, a page by its path, page metadata, `Img` (the prepared widths), `Md` (Markdown that can't run HTML), `JsonLd`, `previewOrigins`. The content is a store: on the server it reads `.site/prepared.json`; in the preview, what CalOS sends. |
+| **Next.js helpers** (`@caltho/site-kit/next`) | The prepared content, a page by its path, page metadata, `Img` (the prepared widths), `Md` (Markdown that can't run HTML), `JsonLd`, `BlockMark` (where each block starts, for the preview), `previewOrigins`. The content is a store: on the server it reads `.site/prepared.json`; in the preview, what CalOS sends. |
 | **Preview** (`@caltho/site-kit/next/preview`) | `SitePreview`: CalOS's draft drawn with the site's own components, a click matched to its field, outlines with each section's name. |
 | **Schema** (`@caltho/site-kit/schema`) | What CalOS needs of a declaration with no site code: validate content against the JSON Schema with messages a person can act on, make a blank block or entry, list the kinds of block, and the checks across pages. |
 
@@ -70,14 +74,32 @@ the kit only checks it's a URL.
 
 Sections any site can use, built once here (accessible, sized for each screen, inside the content
 security policy) so a site gets them with a kit update rather than code of its own. CalOS offers
-them in its editor like the site's own, and Cal can add one. Today: **gallery** (photos in a grid,
-each with an optional caption, opening its largest copy; 2 to 4 across, square, landscape, portrait
-or as taken) and **slideshow** (photos one at a time, fading from one to the next, with captions).
-
-**Your own section** (`own`) is built in CalOS rather than in code: one to four columns (or a wide one
-beside a narrow one), each a list of parts (heading, text, photo, button, list, quote, facts in a row,
-price, photos in a grid, slideshow, space), left or centred, plain or in the brand colour. Its parts
-wear the site's own classes, so what's built looks like the site. One that's wanted again is saved by
+them in its editor like the site's own, and Cal can add one. Today:
+
+- **gallery**: photos in a grid, each with an optional caption, opening its largest copy; 2 to 4
+  across, square, landscape, portrait or as taken.
+- **slideshow**: photos one at a time, fading from one to the next, with captions.
+- **own**: your own section, columns of parts (below).
+- **built**: a section built in CalOS (or by Cal) as a tree of elements styled with Tailwind
+  classes: anything a designer builds with HTML and Tailwind (below, "Built sections").
+- **use**: one of the site's components (a tree kept once in the content's `components`) with its
+  slots' words, links and pictures filled in; changing the component changes every use.
+
+**Your own section** (`own`) is built in CalOS rather than in code: a heading and intro over one to
+four columns (or a wide one beside a narrow one), each a list of parts (heading, text, photo, button,
+list, quote, facts in a row, price, photos in a grid, slideshow, space, table, icon, logos, video),
+left or centred, plain or in the brand colour. A column can be drawn as a card (`card: true`). Its
+parts wear the site's own classes, so what's built looks like the site.
+
+- **table**: 2 to 5 columns (the first over the rows' labels, its heading may be ""), 1 to 20 rows,
+  a column picked out (`highlight`, counting from 1 after the labels). A cell "yes" or "no" is a tick
+  or a dash, read out as the word. A real table from 640px up; below, each row a small card.
+- **icon**: one of the kit's line icons by name (`ICON_NAMES`: check, calendar, clock, users, …),
+  drawn inline in the brand colour, small, medium or large.
+- **logos**: 2 to 12, in a row in grey, with a line above if it has one.
+- **video**: a YouTube or Vimeo address and what the video is (its title, for a screen reader), shown
+  in YouTube's no-cookie player or Vimeo's with tracking off. `finish` lets the player in
+  (`frame-src`) only on a page that shows one, and in the preview. One that's wanted again is saved by
 name in the content's `saved` list, and CalOS offers it beside the site's own kinds.
 
 `Slideshow` (from `@caltho/site-kit/next`) is also a building block a site's own sections use: SCV's
@@ -92,17 +114,125 @@ A site takes them in once, three lines:
 import { sections } from "@caltho/site-kit/sections";
 export const blocks = { ...sections, hero, about /* … */ };
 
-// the site's block renderer: whatever it hasn't a component for
-default:
-  return <KitSection s={block} />;
+// the site's page: every block after its mark, framed when it has a background, the kit drawing
+// whatever kind the site's own `render` leaves (returns null for)
+<KitBlocks blocks={page.blocks} render={(block, i) => <Block s={block} />} level={(i) => (i === 0 ? 1 : 2)} />
 
 // app/layout.tsx
 import "@caltho/site-kit/sections.css";
 ```
 
-From then on each section the kit adds reaches the site with `cal sites kit update`. They're themed by
-the site's Look (`--look-*`); a site with a design of its own gives its own classes so they sit in
-it like its own: `<KitSection s={block} classes={{ section: "", wrap: "mx-auto max-w-5xl px-4 py-12", heading: "font-display text-3xl", text: "…", button: "…", buttonQuiet: "…" }} />`.
+A section of the business's own has a background (`tone`: plain, soft, brand or dark, from the
+Look's `--look-*`, with `--look-page` and `--look-ink` from the Look's `background` and `ink`), space
+above and below (`spacing`: tight, normal, roomy) and can have a photo behind it (`background`, under
+a scrim). On soft, brand or dark it's a card inset within the content's width in the theme's corners
+(`shape: "card"`, the default) or a band across the page (`shape: "band"`). On brand, dark or a photo the kit keeps its words and buttons readable over the site's own
+colour classes. `presets` (from `@caltho/site-kit/sections`) are ready-made ones (an opening, words
+over a photo, three reasons, a client's words, prices, a call to get in touch, contact, common
+questions, a photo and words, facts in a row, a comparison, features with icons, a logo strip, a
+video), each an `own` block to add and edit like any other.
+
+From then on each section the kit adds reaches the site with `cal sites kit update`. They're drawn
+from the site's Look (`--look-*`: its type scale, colours, buttons, width and spacing) and need no
+classes of the site's; a site may still give its own for any part, in place of the kit's:
+`<KitBlocks … classes={{ headingLarge: "font-display text-3xl" }} />`.
+
+## Built sections
+
+A **built** section is a tree of elements (`@caltho/site-kit/tree`: the `Node` type, its zod schema
+`built`, `component` and `use`, the class checker, behaviors' settings, and the messages between
+CalOS's editor and the preview). The kit draws each node as its tag with its Tailwind classes:
+
+- **Checked as it's drawn**, whatever the content says: a tag outside the list is left out, a class
+  the checker refuses is dropped (`safeClasses`), a link that isn't a page, `#part`, http(s), mailto:
+  or tel: goes nowhere (an outside one marked `external` opens in a new tab with
+  `rel="noopener noreferrer"`), a picture is one of the site's own through the kit's images, a video
+  is the kit's own YouTube (no-cookie) or Vimeo (no tracking) player built from a provider and an
+  id, words are light Markdown whose HTML is shown as text, `label` is its `aria-label`, `hidden`
+  nodes aren't drawn. A tree's depth, size and ids are checked with the content.
+- **Shared values**: `bind` shows a value from the site's content by its dotted path
+  (`company.email`); `repeat` draws a node once for each item of a list (`caseStudies`), its binds
+  reading `item.…`.
+- **Classes are prefixed** as drawn (`p-4` is `kit:p-4`), so nothing of the site's own is restyled
+  by them, nor they by its classes of the same names. `prepare` compiles exactly the classes the
+  content's trees use with Tailwind's own compiler (`tailwindcss` 4.3.3), with **no reset** and in no
+  cascade layer, into `public/_kit/built.<hash>.css`; a page with a built section links it (React
+  puts the link in the head), a page without doesn't.
+- **The Look is the theme**: colours by role (`bg-brand`, `text-on-brand`, `text-ink`, `bg-page`,
+  `text-muted`, `border-line`, `bg-soft`, `text-accent`, `bg-light`, `bg-dark`) and the site's own by
+  their slug (`bg-dark-sand`), fonts (`font-display`/`font-heading`, `font-body`/`font-text`), the
+  type scale (`text-display`, `text-h1` … `text-small`, each with its line height, tracking and
+  weight), corners (`rounded-card`, `rounded-button`), width (`max-w-content`) and spacing
+  (`px-gutter`, `py-section`), each reading the Look's `--look-*` variable, so a change of Look needs
+  no build of the CSS. Tailwind's own scale and colours are there too. `@caltho/site-kit/theme` has
+  the tokens and the input both compilers are given (`tailwindInput`).
+- **Behaviors**, chosen not written: `carousel` (dots, arrows, a stop button, the arrow keys, a
+  swipe; its own controls where the design marks nodes with the slots prev, next and dots), `tabs`
+  (the first child holds the tabs, the children after it are the panels), `accordion` (each child an
+  item, its first child the heading that opens it), `marquee`, `reveal`, `count-up`, and `sticky`
+  (CSS alone). Each is a small script of its own, written by `prepare` to `public/_kit` and loaded
+  only on a page that uses it. Without scripting a carousel shows its first slide, tabs show every
+  panel, every accordion item is open, a marquee's row is still and scrollable; nothing moves for
+  someone who asked for less motion.
+- **In CalOS's preview** each element carries `data-node` (never on the published page), so a click
+  names its node (`calos:built-select`, with shift), the pointer's node is said (`calos:built-hover`)
+  and where each element is (`calos:built-boxes`); the editor outlines nodes (`calos:built-highlight`,
+  bringing up the slide, tab or item that holds one) and draws one as hovered or focused
+  (`calos:built-state`). Classes take effect as they're typed with Tailwind's browser build
+  (`@tailwindcss/browser` 4.3.3, the same input as the build's), loaded by the preview page only;
+  visitors never load it. The preview page's policy allows its inline styles for that.
+
+**What a site needs to do**: nothing beyond what it has, on 0.3.0: its schema takes the kit's
+`sections` (built and use come with them), it draws blocks with `KitBlocks`, imports
+`sections.css`, and runs `prepare` and `finish`. `public/_kit` is written by every build (add it to
+`.gitignore` with `public/_img`).
+
+## Cookie banner
+
+Off unless a site turns it on (`consent: { on: true }` in its content, edited in CalOS): visits are
+then counted only once a visitor accepts (finish loads the counter after the choice, never before),
+and `KitFrame` draws a banner in the site's words (`text`, `accept`, `decline`, a `policy` link),
+along the bottom or top or in a corner (`place`), in the kit's design or one of the site's components
+(`design`: a tree with the slots text, accept, decline and policy). The kit's script shows it to a
+visitor who hasn't chosen, keeps the choice in their browser, and brings it back from anything
+marked `data-kit-consent="change"`. The privacy policy says it. Off, visits are counted without
+cookies as before, and no banner is needed.
+
+## Content formats
+
+A site is the starter plus its configuration, so the configuration's format is the kit's. The
+content says its format (`format`; none is 0, before built sections; this kit's is
+`CONTENT_FORMAT`, 1). When a kit changes a shape, a migration in `@caltho/site-kit/content-migrate`
+moves content to it, as data: `migrateContent(content)` runs those it hasn't had, in order, once
+each, and returns `{ ok: true, content, from, format, applied }`, or `{ ok: false, error: { id,
+message, path } }` with the content as it was when one can't move something (for Caltho to fix in
+the migration, never a site by hand). CalOS runs it on a site's draft and published content when
+the site moves to a newer kit; `prepare` runs it too, so content not moved yet still builds. A new
+kind of block or optional field needs no migration, only the number. Code migrations (a site's own
+files) are `@caltho/site-kit/migrate`.
+
+## The theme
+
+The Look is the site's theme. Beside its fonts, brand and accent colours, corners and buttons, it has
+the page's colours by role (`page`, `ink`, `muted`, `line`, `soft`), colours of the site's own by name
+(`palette`), a type scale (`type`: display, h1, h2, h3, body and small, each a size in px, a weight,
+tracking in em and a line height), the content's `width` and the `space` between sections. A site's
+`look` options are its design as it is (the defaults CalOS shows); its CSS reads the variables
+(`--look-page`, `--look-swatch-sand`, `--look-type-h2-size`, `--look-width`, `--look-section-pad`, the
+full list in src/content/look.ts) so a change in CalOS reaches every page. `--look-gutter` is the
+space each side of the content (the site's `gutter` option in px on a wide screen, 40 unless said,
+half on a phone): a site's own wrap reads it so its sections and the kit's line up.
+
+The menu edited in CalOS can have links under a link (`children`, up to 8, one level): `menuOf`
+returns them, and the site's header draws them (the starter: a dropdown on a wide screen, indented
+in the phone's menu). `blockLabel(block, kindTitle)` (`@caltho/site-kit/schema`) is what a block is
+called in a list: its heading, an `own` section's first heading part, else its kind.
+
+Every section's Layout (`placement`, on unless a site sets `placement: false`) has a **Background**: a
+colour (a role, or one of the site's own by its slug) and a photo under a shade. KitBlocks draws it as
+a frame around the section (`frameClass`), its words light when the colour or photo is dark
+(`backgroundIsDark`, from the Look's values at build and in the preview). The schema a site writes
+carries the ready-made sections its `own` kind takes, as `x-presets` at its root.
 
 ## Share cards
 

package/dist/behaviors/accordion.d.ts

@@ -0,0 +1,4 @@
+export declare function accordion(el: HTMLElement, s: {
+    single?: boolean;
+    open?: number;
+}): void;

package/dist/behaviors/accordion.js

@@ -0,0 +1,56 @@
+// An accordion: each child of the node is an item, its first child the heading that opens and closes
+// it, the rest what it opens. The heading works as a button (a click, Enter or Space) and says
+// whether it's open. Without scripting every item is open, so all of it can be read.
+//
+// Self-contained: sent to visitors as its own script (./index.ts). The kit marks the items
+// (data-kit-item), headings (data-kit-head) and what they open (data-kit-body) (../next/built.tsx).
+export function accordion(el, s) {
+    const items = Array.from(el.querySelectorAll(":scope > [data-kit-item]"));
+    const key = Math.random().toString(36).slice(2, 8);
+    const parts = items.map((item, i) => {
+        const head = item.querySelector(":scope > [data-kit-head]");
+        const body = Array.from(item.querySelectorAll(":scope > [data-kit-body]"));
+        body.forEach((b, j) => (b.id ||= `kit-acc-${key}-${i}-${j}`));
+        return { item, head, body };
+    });
+    const set = (i, open) => {
+        const p = parts[i];
+        p.item.toggleAttribute("data-open", open);
+        p.head?.setAttribute("aria-expanded", String(open));
+        p.body.forEach((b) => (b.hidden = !open));
+    };
+    parts.forEach((p, i) => {
+        const head = p.head;
+        if (!head)
+            return;
+        if (head.tagName !== "BUTTON") {
+            head.setAttribute("role", "button");
+            head.tabIndex = 0;
+        }
+        head.setAttribute("aria-controls", p.body.map((b) => b.id).join(" "));
+        const toggle = () => {
+            const open = head.getAttribute("aria-expanded") !== "true";
+            if (open && s.single)
+                parts.forEach((_, j) => j !== i && set(j, false));
+            set(i, open);
+        };
+        head.addEventListener("click", (e) => {
+            e.preventDefault();
+            toggle();
+        });
+        head.addEventListener("keydown", (e) => {
+            if (head.tagName !== "BUTTON" && (e.key === "Enter" || e.key === " ")) {
+                e.preventDefault();
+                toggle();
+            }
+        });
+        set(i, i === s.open);
+    });
+    // CalOS's preview asks for the item holding what's selected to be opened.
+    el.addEventListener("kit:show", (e) => {
+        const i = parts.findIndex((p) => p.item.contains(e.target));
+        if (i >= 0)
+            set(i, true);
+    });
+    el.setAttribute("data-kit-ready", "");
+}

package/dist/behaviors/carousel.d.ts

@@ -0,0 +1,4 @@
+export declare function carousel(el: HTMLElement, s: {
+    seconds?: number;
+    pauseOnHover?: boolean;
+}, still: boolean): void;

package/dist/behaviors/carousel.js

@@ -0,0 +1,127 @@
+// A carousel: its slides one at a time, by its dots and arrows (buttons, each saying what it shows),
+// the arrow keys while it has focus, or a swipe; and every few seconds, where it's set to, while it's
+// on screen and not pointed at or focused, with a button to stop it, and never for someone who asked
+// for less motion. Without scripting the first slide shows (sections.css), and the controls don't.
+//
+// Self-contained (nothing from outside the function): it's sent to visitors as its own script
+// (./index.ts). The kit draws what it works on (../next/built.tsx): the slides in a track
+// (data-kit-track, data-kit-slide, the first data-active), the dots (data-kit-to), arrows
+// (data-kit-prev, data-kit-next) and the stop button (data-kit-pause).
+export function carousel(el, s, still) {
+    const track = el.querySelector(":scope > [data-kit-track]");
+    if (!track)
+        return;
+    const slides = Array.from(track.children).filter((c) => c.hasAttribute("data-kit-slide"));
+    const n = slides.length;
+    const mine = (sel) => Array.from(el.querySelectorAll(sel)).filter((x) => x.closest('[data-kit-behavior="carousel"]') === el);
+    const dots = mine("[data-kit-to]");
+    const pause = mine("[data-kit-pause]")[0];
+    const slideWise = track.getAttribute("data-kit-transition") === "slide";
+    const reduce = still || window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    let at = Math.max(0, slides.findIndex((x) => x.hasAttribute("data-active")));
+    let timer = 0;
+    let held = false;
+    let stopped = false;
+    let seen = true;
+    const show = (i) => {
+        at = ((i % n) + n) % n;
+        slides.forEach((x, j) => {
+            const on = j === at;
+            x.toggleAttribute("data-active", on);
+            if (on)
+                x.removeAttribute("aria-hidden");
+            else
+                x.setAttribute("aria-hidden", "true");
+            x.inert = !on;
+            // Sideways: each slide moved by the place shown (a style set from script, which the page's policy allows).
+            if (slideWise)
+                x.style.transform = `translateX(${-100 * at}%)`;
+        });
+        dots.forEach((d, j) => d.setAttribute("aria-current", j === at ? "true" : "false"));
+        wait();
+    };
+    const moving = () => !!s.seconds && !reduce && !held && !stopped && seen && !document.hidden && n > 1;
+    function wait() {
+        clearTimeout(timer);
+        if (moving())
+            timer = window.setTimeout(() => (el.isConnected ? show(at + 1) : undefined), Math.max(2, s.seconds ?? 5) * 1000);
+    }
+    // A control that isn't a button of its own (a designed arrow drawn as a div) still works from the keyboard.
+    const press = (b, go) => {
+        if (b.tagName !== "BUTTON") {
+            b.setAttribute("role", "button");
+            b.tabIndex = 0;
+            b.addEventListener("keydown", (e) => {
+                if (e.key === "Enter" || e.key === " ") {
+                    e.preventDefault();
+                    go();
+                }
+            });
+        }
+        b.addEventListener("click", (e) => {
+            e.preventDefault();
+            go();
+        });
+    };
+    if (n < 2)
+        return void el.setAttribute("data-kit-ready", "");
+    dots.forEach((d) => press(d, () => show(Number(d.getAttribute("data-kit-to")))));
+    mine("[data-kit-prev]").forEach((b) => press(b, () => show(at - 1)));
+    mine("[data-kit-next]").forEach((b) => press(b, () => show(at + 1)));
+    if (pause) {
+        // Nothing turns by itself (no seconds, less motion asked for, CalOS's still preview): no pause to press.
+        // Set as a style too, since the element's own display class (inline-flex) would outrank [hidden].
+        if (!s.seconds || reduce) {
+            pause.hidden = true;
+            pause.style.display = "none";
+        }
+        press(pause, () => {
+            stopped = !stopped;
+            pause.setAttribute("aria-pressed", String(stopped));
+            pause.setAttribute("aria-label", stopped ? "Play the slides" : "Pause the slides");
+            pause.toggleAttribute("data-stopped", stopped);
+            wait();
+        });
+    }
+    el.addEventListener("keydown", (e) => {
+        const t = e.target;
+        if (t.closest("input, textarea, select, [contenteditable]"))
+            return;
+        if (e.key === "ArrowLeft" || e.key === "ArrowRight") {
+            e.preventDefault();
+            show(at + (e.key === "ArrowRight" ? 1 : -1));
+        }
+    });
+    if (s.pauseOnHover !== false) {
+        el.addEventListener("pointerenter", () => ((held = true), wait()));
+        el.addEventListener("pointerleave", () => ((held = false), wait()));
+    }
+    el.addEventListener("focusin", () => ((held = true), wait()));
+    el.addEventListener("focusout", (e) => {
+        if (!el.contains(e.relatedTarget))
+            (held = false), wait();
+    });
+    // A swipe on a touch screen.
+    let from = null;
+    track.addEventListener("pointerdown", (e) => (from = e.clientX));
+    track.addEventListener("pointerup", (e) => {
+        if (from !== null && Math.abs(e.clientX - from) > 40)
+            show(at + (e.clientX < from ? 1 : -1));
+        from = null;
+    });
+    // Off screen or in another tab, it waits.
+    if (typeof IntersectionObserver !== "undefined")
+        new IntersectionObserver(([e]) => {
+            seen = !!e?.isIntersecting;
+            wait();
+        }).observe(el);
+    document.addEventListener("visibilitychange", wait);
+    // CalOS's preview asks for the slide holding what's selected to be shown.
+    el.addEventListener("kit:show", (e) => {
+        const i = slides.findIndex((x) => x.contains(e.target));
+        if (i >= 0)
+            show(i);
+    });
+    el.setAttribute("data-kit-ready", "");
+    show(at);
+}

package/dist/behaviors/filter.d.ts

@@ -0,0 +1 @@
+export declare function filter(el: HTMLElement): void;

package/dist/behaviors/filter.js

@@ -0,0 +1,25 @@
+// A filter: the buttons inside it choose which of the items repeated inside it show, by a field of the
+// list (its settings' field): a button matches the items whose value is its words (lowercase, dashes
+// for spaces: "Real estate" is real-estate), "All" (or no words) shows every one. The chosen button says
+// so (aria-pressed), for its design's aria-pressed: classes. Without scripting every item shows.
+//
+// Self-contained: sent to visitors as its own script (./index.ts). The kit marks each item with its value
+// (data-kit-filter-value, ../next/built.tsx).
+export function filter(el) {
+    const norm = (v) => v.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const items = () => Array.from(el.querySelectorAll("[data-kit-filter-value]"));
+    const buttons = Array.from(el.querySelectorAll("button")).filter((b) => !b.closest("[data-kit-filter-value]"));
+    const valueOf = (b) => {
+        const v = norm(b.textContent ?? "");
+        return v === "all" ? "" : v;
+    };
+    const choose = (chosen) => {
+        const v = chosen ? valueOf(chosen) : "";
+        items().forEach((i) => (i.hidden = !!v && i.getAttribute("data-kit-filter-value") !== v));
+        buttons.forEach((b) => b.setAttribute("aria-pressed", String(b === chosen)));
+    };
+    buttons.forEach((b) => b.addEventListener("click", (e) => (e.preventDefault(), choose(b))));
+    // Every item to start, its "All" button pressed where it has one.
+    choose(buttons.find((b) => valueOf(b) === "") ?? null);
+    el.setAttribute("data-kit-ready", "");
+}

package/dist/behaviors/index.d.ts

@@ -0,0 +1,14 @@
+import type { BehaviorName } from "../tree/index.ts";
+type Run = (el: HTMLElement, settings: Record<string, unknown>, still: boolean) => void;
+/** Each behavior that has a script. */
+export declare const BEHAVIOR_RUNS: Partial<Record<BehaviorName, Run>>;
+/** The attribute naming an element's behavior, and the one holding its settings. */
+export declare const BEHAVIOR_ATTR = "data-kit-behavior";
+export declare const SETTINGS_ATTR = "data-kit-settings";
+/** The script a published page carries for one behavior: its own code and the starter, nothing else. */
+export declare function behaviorScript(name: BehaviorName): string | null;
+/** Starts every behavior on the page (CalOS's preview, still: nothing moves by itself). */
+export declare function startBehaviors(still: boolean): void;
+/** Asks whatever behavior holds this element to show it (a carousel's slide, a tab's panel, an accordion's item): the preview, when it's selected. */
+export declare function showWithin(el: Element): void;
+export {};

package/dist/behaviors/index.js

@@ -0,0 +1,78 @@
+import { accordion } from "./accordion.js";
+import { carousel } from "./carousel.js";
+import { countUp, marquee, reveal } from "./motion.js";
+import { tabs } from "./tabs.js";
+import { filter } from "./filter.js";
+/** Each behavior that has a script. */
+export const BEHAVIOR_RUNS = {
+    carousel: carousel,
+    tabs: tabs,
+    accordion: accordion,
+    marquee: marquee,
+    reveal: reveal,
+    "count-up": countUp,
+    filter: filter,
+};
+/** The attribute naming an element's behavior, and the one holding its settings. */
+export const BEHAVIOR_ATTR = "data-kit-behavior";
+export const SETTINGS_ATTR = "data-kit-settings";
+/**
+ * Starts every element of this behavior not started yet, now and as more are drawn. `still`: nothing
+ * moves by itself (CalOS's preview, so what's being edited stays put). Written to be sent as its own
+ * script as well as called here, so it uses nothing from outside itself but `run`.
+ */
+function start(name, run, still) {
+    const go = () => {
+        for (const el of Array.from(document.querySelectorAll(`[data-kit-behavior="${name}"]:not([data-kit-on])`))) {
+            el.setAttribute("data-kit-on", "");
+            let settings = {};
+            try {
+                settings = JSON.parse(el.getAttribute("data-kit-settings") || "{}");
+            }
+            catch {
+                // Settings the kit wrote can't be broken; the behavior's own defaults if they somehow are.
+            }
+            try {
+                run(el, settings, still);
+            }
+            catch (err) {
+                console.error(`site-kit: the ${name} behavior stopped`, err);
+            }
+        }
+    };
+    let queued = false;
+    const soon = () => {
+        if (queued)
+            return;
+        queued = true;
+        requestAnimationFrame(() => {
+            queued = false;
+            go();
+        });
+    };
+    const begin = () => {
+        go();
+        new MutationObserver(soon).observe(document.body, { childList: true, subtree: true });
+    };
+    // Loaded before the page is all there (an async script): it waits for the whole page, so a carousel isn't started with half its slides.
+    if (document.readyState === "loading")
+        document.addEventListener("DOMContentLoaded", begin, { once: true });
+    else
+        begin();
+}
+/** The script a published page carries for one behavior: its own code and the starter, nothing else. */
+export function behaviorScript(name) {
+    const run = BEHAVIOR_RUNS[name];
+    if (!run)
+        return null;
+    return `(()=>{const run=${run.toString()};(${start.toString()})(${JSON.stringify(name)},run,false);})();\n`;
+}
+/** Starts every behavior on the page (CalOS's preview, still: nothing moves by itself). */
+export function startBehaviors(still) {
+    for (const [name, run] of Object.entries(BEHAVIOR_RUNS))
+        start(name, run, still);
+}
+/** Asks whatever behavior holds this element to show it (a carousel's slide, a tab's panel, an accordion's item): the preview, when it's selected. */
+export function showWithin(el) {
+    el.dispatchEvent(new CustomEvent("kit:show", { bubbles: true }));
+}

package/dist/behaviors/motion.d.ts

@@ -0,0 +1,13 @@
+/** The kit draws the row twice in a track (data-kit-track, its copy data-kit-copy, hidden from screen readers); this moves it by one copy's width. */
+export declare function marquee(el: HTMLElement, s: {
+    seconds?: number;
+    reverse?: boolean;
+}, still: boolean): void;
+/** Hidden until it's scrolled to (sections.css, by its effect), then in; its children one after another where it staggers them. */
+export declare function reveal(el: HTMLElement, s: {
+    stagger?: number;
+}, still: boolean): void;
+/** The first number in its words ("$1,200+", "98%"), counted up from nothing, then left exactly as written. */
+export declare function countUp(el: HTMLElement, s: {
+    seconds?: number;
+}, still: boolean): void;

package/dist/behaviors/motion.js

@@ -0,0 +1,88 @@
+// The behaviors that only move things: a marquee (a row scrolling past without end), reveal (in as
+// it's scrolled to) and count-up (a number counting up to itself as it's scrolled to). Each does
+// nothing for someone who asked for less motion, and without scripting what they hold is simply
+// there: the row still (scrollable), everything shown, the number as written.
+//
+// Each self-contained: sent to visitors as its own script (./index.ts).
+/** The kit draws the row twice in a track (data-kit-track, its copy data-kit-copy, hidden from screen readers); this moves it by one copy's width. */
+export function marquee(el, s, still) {
+    const track = el.querySelector(":scope > [data-kit-track]");
+    const copy = track?.querySelector(":scope > [data-kit-copy]");
+    const first = track?.firstElementChild;
+    if (!track || !copy || !first || still || window.matchMedia("(prefers-reduced-motion: reduce)").matches)
+        return;
+    // Styles set from script (the page's policy allows them): how far one round goes and how long it takes.
+    const measure = () => el.style.setProperty("--kit-marquee-shift", `${copy.offsetLeft - first.offsetLeft}px`);
+    measure();
+    el.style.setProperty("--kit-marquee-seconds", `${s.seconds ?? 30}s`);
+    if (s.reverse)
+        el.setAttribute("data-kit-reverse", "");
+    if (typeof ResizeObserver !== "undefined")
+        new ResizeObserver(measure).observe(track);
+    el.setAttribute("data-kit-ready", "");
+}
+/** Hidden until it's scrolled to (sections.css, by its effect), then in; its children one after another where it staggers them. */
+export function reveal(el, s, still) {
+    if (still || window.matchMedia("(prefers-reduced-motion: reduce)").matches || typeof IntersectionObserver === "undefined")
+        return;
+    if (s.stagger) {
+        el.setAttribute("data-kit-stagger", "");
+        Array.from(el.children).forEach((c, i) => (c.style.transitionDelay = `${i * s.stagger}ms`));
+    }
+    const o = new IntersectionObserver((entries) => {
+        if (!entries.some((e) => e.isIntersecting))
+            return;
+        el.setAttribute("data-kit-shown", "");
+        o.disconnect();
+    }, { rootMargin: "0px 0px -10% 0px" });
+    // Ready first (hidden), then watched: what's already on screen comes in at once.
+    el.setAttribute("data-kit-ready", "");
+    o.observe(el);
+}
+/** The first number in its words ("$1,200+", "98%"), counted up from nothing, then left exactly as written. */
+export function countUp(el, s, still) {
+    if (still || window.matchMedia("(prefers-reduced-motion: reduce)").matches || typeof IntersectionObserver === "undefined")
+        return;
+    const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+    let text = null;
+    for (let t = walker.nextNode(); t; t = walker.nextNode()) {
+        if (/\d/.test(t.textContent ?? "")) {
+            text = t;
+            break;
+        }
+    }
+    if (!text)
+        return;
+    const written = text.textContent;
+    const m = /(\d[\d,]*)(\.\d+)?/.exec(written);
+    if (!m)
+        return;
+    const target = Number((m[1] + (m[2] ?? "")).replace(/,/g, ""));
+    const decimals = m[2] ? m[2].length - 1 : 0;
+    const commas = m[1].includes(",");
+    const format = (v) => {
+        const fixed = v.toFixed(decimals);
+        return commas ? fixed.replace(/\B(?=(\d{3})+(?!\d))/g, ",") : fixed;
+    };
+    const node = text;
+    // Read out as written, not as it counts.
+    if (!el.hasAttribute("aria-label"))
+        el.setAttribute("aria-label", el.textContent?.trim() ?? written);
+    node.textContent = written.slice(0, m.index) + format(0) + written.slice(m.index + m[0].length);
+    const o = new IntersectionObserver((entries) => {
+        if (!entries.some((e) => e.isIntersecting))
+            return;
+        o.disconnect();
+        const start = performance.now();
+        const ms = (s.seconds ?? 1.2) * 1000;
+        const step = (now) => {
+            const t = Math.min(1, (now - start) / ms);
+            const eased = 1 - Math.pow(1 - t, 3);
+            node.textContent = t < 1 ? written.slice(0, m.index) + format(target * eased) + written.slice(m.index + m[0].length) : written;
+            if (t < 1)
+                requestAnimationFrame(step);
+        };
+        requestAnimationFrame(step);
+    });
+    o.observe(el);
+}

package/dist/behaviors/tabs.d.ts

@@ -0,0 +1,3 @@
+export declare function tabs(el: HTMLElement, s: {
+    first?: number;
+}): void;