@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/text/Text.d.ts

@@ -0,0 +1,36 @@
+import { type ComponentPropsWithRef, type CSSProperties, type ElementType, type ReactNode } from "react";
+import type { TextEffect } from "./types.js";
+interface TextOwnProps<E extends ElementType> {
+    /** The element to render. Default `p`. */
+    readonly as?: E;
+    /** One effect or a list; they stack. */
+    readonly effect?: TextEffect | readonly TextEffect[];
+    /** Play an entrance once (default), or every time the text comes back into view. */
+    readonly once?: boolean;
+    /** How much must be on screen before an entrance plays, 0-1. Default `0.2`. */
+    readonly threshold?: number;
+    /** For scripts written without spaces: the language, so words are cut where a reader expects. */
+    readonly locale?: string;
+    /** How far something has got, 0 to 1 (`inkProgress` fills the letters that far). */
+    readonly progress?: number;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    /** Plain text: effects that move letters, words or lines need a string. */
+    readonly children?: ReactNode;
+}
+export type TextProps<E extends ElementType = "p"> = TextOwnProps<E> & Omit<ComponentPropsWithRef<E>, keyof TextOwnProps<E>>;
+/**
+ * A heading or paragraph that wears any number of text effects.
+ *
+ * ```tsx
+ * <Text as="h1" effect={enterRise({ by: "chars" })}>Build faster websites</Text>
+ * <Text as="h2" effect={[enterMask(), inkGradient()]}>Colour that flows</Text>
+ * ```
+ *
+ * Screen readers and search engines read the text once, as words: the pieces that move are hidden from them. Words
+ * and letters are cut on the server, so the HTML already holds them; lines are measured in the browser once the fonts
+ * have loaded, and again when the width changes. Letters are cut only where they stand alone: Arabic and other joined
+ * scripts move by the word. Without scripts, or under reduced motion, the text shows as it is, in its look.
+ */
+export declare function Text<E extends ElementType = "p">(props: TextProps<E>): import("react").JSX.Element;
+export {};

package/dist/text/Text.js

@@ -0,0 +1,246 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { styleHref } from "../backgrounds/hosts/CssHost.js";
+import { renderSvgElement } from "../backgrounds/hosts/svgElement.js";
+import { claimConflicts } from "../buttons/claims.js";
+import { warnOnce } from "../buttons/runtime/dev.js";
+import { motionOnly } from "../transitions/progress.js";
+import { useInView } from "../transitions/reveal/inView.js";
+import { TEXT_BASE_CSS } from "./base.js";
+import { orderOf, randomsOf } from "./order.js";
+import { fitDrawings } from "./runtime/fit.js";
+import { measurePaint } from "./runtime/paint.js";
+import { runtimes } from "./runtime/slots.js";
+import { useOnScreen } from "./runtime/useOnScreen.js";
+import { useTextPointer } from "./runtime/useTextPointer.js";
+import { graphemes, isJoined, lettersOf, lineStarts, splitWords } from "./split.js";
+/** How finely each level cuts. */
+const FINE = { lines: 1, words: 2, chars: 3 };
+/** Letters past this many drop to words (atlas rule 2), unless an effect says fewer. */
+const MAX_LETTERS = 120;
+/** Tiers by rank: a device of rank n (0 low, 1 mid, 2 high) runs an effect whose tier sits at n or below. */
+const TIERS = ["all", "mid", "high"];
+/** The effects as a list, each id once (the last one wins). */
+function effectList(effect) {
+    if (!effect)
+        return [];
+    const list = Array.isArray(effect) ? effect : [effect];
+    return [...new Map(list.map((e) => [e.id, e])).values()];
+}
+function unitProps(plan, i) {
+    if (!plan)
+        return {};
+    const r = plan.randoms?.[i];
+    const style = { "--sx-o": plan.order[i] ?? 0, ...(r ? { "--sx-ra": r[0], "--sx-rb": r[1], "--sx-rc": r[2] } : {}) };
+    return { style, "data-sx-text-unit": "" };
+}
+const Cover = ({ plan }) => (plan?.cover ? _jsx("span", { "data-sx-text-cover": "" }) : null);
+/** The text, in a paint span when an effect paints the letters. */
+const Ink = ({ paint, children }) => paint ? _jsx("span", { "data-sx-text-paint": "", children: children }) : _jsx(_Fragment, { children: children });
+/** The text drawn as SVG on one line, centred in the frame (the frame is as wide as the text). */
+function SvgLine({ text }) {
+    return (_jsx("text", { x: "50%", y: "50%", textAnchor: "middle", dominantBaseline: "central", children: text }));
+}
+function Layer({ effect, layer, uid, text }) {
+    return (_jsxs("span", { "data-sx-text-layer": effect.id, "data-sx-text-part": layer.part, "data-sx-text-slot": layer.slot ?? "over", "aria-hidden": true, children: [layer.copy ? text : null, layer.window ? (_jsx("span", { "data-sx-text-part": "win", children: _jsx("span", { "data-sx-text-part": "copy", children: text }) })) : null, layer.video ? _jsx("video", { src: layer.video.src, poster: layer.video.poster, muted: true, loop: true, playsInline: true, preload: "metadata" }) : null, layer.svgText === "draw" ? (_jsx("svg", { focusable: "false", children: _jsx(SvgLine, { text: text }) })) : null, layer.svgText === "cutout" ? (_jsxs("svg", { focusable: "false", children: [_jsx("defs", { children: _jsxs("mask", { id: `${uid}-cut`, children: [_jsx("rect", { width: "100%", height: "100%", fill: "white" }), _jsx("g", { fill: "black", children: _jsx(SvgLine, { text: text }) })] }) }), _jsx("rect", { "data-sx-text-part": "cover", width: "100%", height: "100%", mask: `url(#${uid}-cut)` })] })) : null, layer.svg ? (_jsx("svg", { viewBox: layer.svg.viewBox, preserveAspectRatio: layer.svg.preserveAspectRatio, focusable: "false", children: layer.svg.children.map((el, i) => renderSvgElement(el, uid, i, "data-sx-text-part")) })) : null, layer.nodes?.map((vars, i) => _jsx("span", { "data-sx-text-node": "", style: vars }, i))] }));
+}
+/**
+ * A heading or paragraph that wears any number of text effects.
+ *
+ * ```tsx
+ * <Text as="h1" effect={enterRise({ by: "chars" })}>Build faster websites</Text>
+ * <Text as="h2" effect={[enterMask(), inkGradient()]}>Colour that flows</Text>
+ * ```
+ *
+ * Screen readers and search engines read the text once, as words: the pieces that move are hidden from them. Words
+ * and letters are cut on the server, so the HTML already holds them; lines are measured in the browser once the fonts
+ * have loaded, and again when the width changes. Letters are cut only where they stand alone: Arabic and other joined
+ * scripts move by the word. Without scripts, or under reduced motion, the text shows as it is, in its look.
+ */
+export function Text(props) {
+    const { as, effect, once = true, threshold = 0.2, locale, progress, className, style, children, ref, ...rest } = props;
+    const Tag = as ?? "p";
+    const asked = effectList(effect);
+    // A weaker device wears each heavy effect's fallback. The server and the first render use the lightest link, and the
+    // check (which the heavy effects bring, runtimes.tier) upgrades after mount: no hydration mismatch.
+    const heavy = asked.some((e) => e.tier !== "all");
+    const [device, setDevice] = useState(0);
+    useEffect(() => void (heavy && setDevice(runtimes.tier?.() ?? 0)), [heavy]);
+    // the first link of each fallback chain this device runs, or the last (always "all")
+    const effects = asked.map((e) => {
+        while (TIERS.indexOf(e.tier) > device && e.fallback)
+            e = e.fallback;
+        return e;
+    });
+    for (const { claim, ids } of claimConflicts(effects)) {
+        warnOnce(`text effects ${ids.join(" and ")} both write the "${claim}" channel: the last one wins. Keep one of them.`);
+    }
+    const own = useRef(null);
+    const setRef = useCallback((el) => {
+        own.current = el;
+        if (typeof ref === "function")
+            ref(el);
+        else if (ref)
+            ref.current = el;
+    }, [ref]);
+    const text = typeof children === "string" ? children : typeof children === "number" ? String(children) : undefined;
+    const needs = effects.map((e) => e.needs);
+    const wanted = needs.reduce((a, n) => (n.split && (!a || FINE[n.split] > FINE[a]) ? n.split : a), undefined);
+    const lined = needs.some((n) => n.split === "lines");
+    const lead = needs.find((n) => n.order !== undefined || n.scatter || n.cover);
+    const paints = needs.some((n) => n.paint);
+    const inner = needs.some((n) => n.inner);
+    const maxLetters = Math.min(MAX_LETTERS, ...needs.map((n) => n.maxPieces ?? MAX_LETTERS));
+    if (wanted && text === undefined)
+        warnOnce("a text effect that moves letters, words or lines needs plain text: with anything else, it moves the whole text.");
+    // letters only in short text (atlas rule 2); past it the text moves by the word
+    const tooLong = wanted === "chars" && text !== undefined && graphemes(text).length > maxLetters;
+    if (tooLong)
+        warnOnce(`text effects cut at most ${maxLetters} letters: this text moves by the word. Split headings, not paragraphs.`);
+    const split = text === undefined ? undefined : tooLong ? "words" : wanted;
+    const unitLevel = lead?.split === "chars" && tooLong ? "words" : lead?.split;
+    const pieces = useMemo(() => split === undefined || text === undefined
+        ? []
+        : splitWords(text, locale).map((p) => ({ ...p, letters: split === "chars" && !p.space ? lettersOf(p.text) : null })), [split, text, locale]);
+    // lines: the first word of each, once measured (null = render words and measure)
+    const [starts, setStarts] = useState(null);
+    useInView(own, "data-sx-in", once, threshold, needs.some((n) => n.inView));
+    useOnScreen(own, needs.some((n) => n.loop) || effects.some((e) => e.layers.some((l) => l.video)));
+    useTextPointer(own, needs.some((n) => n.pointer));
+    useEffect(() => own.current?.setAttribute("data-sx-text-live", ""), []);
+    const scrolls = needs.some((n) => n.scroll);
+    useEffect(() => {
+        const el = own.current;
+        // the fallback comes with the scroll effects (runtimes.scrub), not with Text
+        return scrolls && el ? runtimes.scrub?.(el) : undefined;
+    }, [scrolls]);
+    useLayoutEffect(() => {
+        const root = own.current;
+        if (!lined || !root || pieces.length === 0)
+            return;
+        const again = () => {
+            // lines measured again after the entrance played must not play it again
+            if (once && root.hasAttribute("data-sx-in"))
+                root.setAttribute("data-sx-text-done", "");
+            setStarts(null);
+        };
+        if (starts === null) {
+            const words = [...root.querySelectorAll("[data-sx-text-word]")];
+            if (words.length > 0)
+                setStarts(lineStarts(words.map((w) => w.offsetTop)));
+        }
+        // measured with the fallback font: measure again once the real one is in (atlas rule 3)
+        let gone = false;
+        if (typeof document !== "undefined" && document.fonts?.status === "loading")
+            void document.fonts.ready.then(() => !gone && again());
+        // The room the text has is its parent's width: a text only as wide as its lines (centred in a flex box) never
+        // changes width on its own. Compared with the width once the lines are in, so the words-to-lines swap itself, which
+        // can resize a parent that fits its content, never counts as a change.
+        const box = root.parentElement ?? root;
+        const widthOf = () => Math.round(box.getBoundingClientRect().width);
+        const settled = starts === null ? -1 : widthOf();
+        const ro = typeof ResizeObserver === "undefined" || settled === -1
+            ? undefined
+            : new ResizeObserver(() => {
+                if (widthOf() !== settled)
+                    again();
+            });
+        ro?.observe(box);
+        return () => {
+            gone = true;
+            ro?.disconnect();
+        };
+    }, [lined, starts, pieces, once]);
+    // drawings round the text, sized to it in px, again when it resizes
+    const fits = effects.some((e) => e.layers.some((l) => l.svg?.fit));
+    useLayoutEffect(() => {
+        const root = own.current;
+        const frame = root?.querySelector("[data-sx-text-frame]");
+        if (!fits || !root || !frame)
+            return;
+        fitDrawings(root);
+        let gone = false;
+        if (document.fonts?.status === "loading")
+            void document.fonts.ready.then(() => !gone && fitDrawings(root));
+        const ro = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(() => fitDrawings(root));
+        ro?.observe(frame);
+        return () => {
+            gone = true;
+            ro?.disconnect();
+        };
+    }, [fits, starts, pieces]);
+    // paint: where each paint span sits in the whole, measured after every layout of the pieces and when the text resizes
+    useLayoutEffect(() => {
+        const show = own.current?.querySelector("[data-sx-text-show]");
+        if (!paints || !show)
+            return;
+        measurePaint(show);
+        let gone = false;
+        if (document.fonts?.status === "loading")
+            void document.fonts.ready.then(() => !gone && measurePaint(show));
+        const ro = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(() => measurePaint(show));
+        ro?.observe(show);
+        return () => {
+            gone = true;
+            ro?.disconnect();
+        };
+    }, [paints, starts, pieces]);
+    const programs = effects.filter((e) => e.program);
+    const programKey = programs.map((e) => `${e.id}:${e.program.signature}`).join(" ");
+    useEffect(() => {
+        const el = own.current;
+        if (!el || programs.length === 0)
+            return;
+        const stops = programs.map((e) => e.program.attach(el, text));
+        return () => stops.forEach((stop) => stop());
+        // a factory called during render makes a new program every time: only its options and the text restart it
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [programKey, text]);
+    // what the entrance moves: letters, words, lines, or the whole text (no string, or lines not measured yet)
+    const wordCount = pieces.filter((p) => !p.space).length;
+    const letterCount = pieces.reduce((n, p) => n + (p.letters?.length ?? 0), 0);
+    const level = text === undefined ? undefined : unitLevel === "lines" && !starts ? undefined : unitLevel;
+    const count = !lead ? 0 : level === "chars" ? letterCount : level === "words" ? wordCount : level === "lines" ? (starts?.length ?? 1) : 1;
+    const plan = lead
+        ? { order: orderOf(count, lead.order ?? "start", lead.seed), randoms: lead.scatter ? randomsOf(count, lead.seed ?? 1) : null, cover: !!lead.cover }
+        : null;
+    const progressVar = progress === undefined ? {} : { "--sx-text-progress": Math.min(1, Math.max(0, progress)) };
+    // ids for masks and gradients inside layers, unique per text and valid in url(#…)
+    const uid = `sx${useId().replace(/[^\w-]/g, "")}`;
+    const vars = { ...Object.assign({}, ...effects.map((e) => e.vars)), ...(lead ? { "--sx-n": count } : {}), ...progressVar, ...style };
+    let letter = 0;
+    let word = 0;
+    const wordSpan = (p, key) => {
+        const wi = word++;
+        const unit = level === "words" ? unitProps(plan, wi) : {};
+        return (_jsxs("span", { "data-sx-text-word": "", ...unit, style: { "--sx-wi": wi, ...unit.style }, children: [p.letters ? (p.letters.map((l, j) => {
+                    const ci = letter++;
+                    const piece = level === "chars" ? unitProps(plan, ci) : {};
+                    return (_jsxs("span", { "data-sx-text-char": "", ...piece, style: { "--sx-i": ci, ...piece.style }, children: [_jsx(Ink, { paint: paints, children: l }), level === "chars" ? _jsx(Cover, { plan: plan }) : null] }, j));
+                })) : (_jsx(Ink, { paint: paints, children: p.text })), level === "words" ? _jsx(Cover, { plan: plan }) : null] }, key));
+    };
+    const run = (from, to) => pieces.slice(from, to).map((p, i) => (p.space ? p.text : wordSpan(p, from + i)));
+    let content;
+    if (split === undefined)
+        content = _jsx(Ink, { paint: paints, children: children });
+    else if (lined && starts) {
+        const wordAt = pieces.flatMap((p, i) => (p.space ? [] : [i]));
+        content = starts.map((start, line) => {
+            const from = line === 0 ? 0 : (wordAt[start] ?? pieces.length);
+            const to = line + 1 < starts.length ? (wordAt[starts[line + 1]] ?? pieces.length) : pieces.length;
+            const unit = level === "lines" ? unitProps(plan, line) : {};
+            return (_jsxs("span", { "data-sx-text-line": "", ...unit, style: { "--sx-li": line, ...unit.style }, children: [run(from, to), level === "lines" ? _jsx(Cover, { plan: plan }) : null] }, line));
+        });
+    }
+    else
+        content = run(0, pieces.length);
+    const showUnit = lead && level === undefined ? unitProps(plan, 0) : {};
+    const show = (_jsxs("span", { "data-sx-text-show": "", "aria-hidden": split !== undefined || undefined, ...showUnit, children: [inner ? _jsx("span", { "data-sx-text-inner": "", children: content }) : content, lead && level === undefined ? _jsx(Cover, { plan: plan }) : null] }));
+    const plain = text ?? children;
+    const layers = effects.flatMap((e) => e.layers.map((layer, i) => _jsx(Layer, { effect: e, layer: layer, uid: uid, text: plain }, `${e.id}-${i}`)));
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("text-base", TEXT_BASE_CSS), precedence: "sx", children: TEXT_BASE_CSS }), effects.filter((e) => e.lookCss).map((e) => (_jsx("style", { href: styleHref(`text-${e.id}-look`, e.lookCss), precedence: "sx", children: e.lookCss }, `${e.id}-look`))), effects.filter((e) => e.css).map((e) => {
+                const css = motionOnly(e.css);
+                return (_jsx("style", { href: styleHref(`text-${e.id}`, css), precedence: "sx", children: css }, e.id));
+            }), _jsxs(Tag, { ...rest, ref: setRef, "data-sx-text": effects.map((e) => e.id).join(" ") || undefined, "data-sx-text-joined": text !== undefined && isJoined(text) ? "" : undefined, "data-sx-text-wait": needs.some((n) => n.wait) ? "" : undefined, "data-sx-text-scroll": scrolls ? "" : undefined, className: className, style: vars, children: [split !== undefined ? _jsx("span", { "data-sx-text-read": "", children: text }) : null, layers.length > 0 ? (_jsxs("span", { "data-sx-text-frame": "", children: [show, layers] })) : (show)] })] }));
+}

package/dist/text/base.d.ts

@@ -0,0 +1 @@
+export declare const TEXT_BASE_CSS = "@layer theme, base, components, utilities;\n@layer components {\n  :where([data-sx-text]) {\n    --sx-text-dir: 1;\n    position: relative;\n  }\n  :where([data-sx-text]:dir(rtl)) {\n    --sx-text-dir: -1;\n  }\n  :where([data-sx-text-read]) {\n    position: absolute;\n    inline-size: 1px;\n    block-size: 1px;\n    overflow: hidden;\n    clip-path: inset(50%);\n    white-space: nowrap;\n  }\n  :where([data-sx-text-frame]) {\n    position: relative;\n    display: inline-block;\n    max-inline-size: 100%;\n    isolation: isolate;\n  }\n  :where([data-sx-text-show] > [data-sx-text-paint]) {\n    display: inline-block;\n    max-inline-size: 100%;\n  }\n  :where([data-sx-text-show]) {\n    display: inline-block;\n    max-inline-size: 100%;\n  }\n  :where([data-sx-text-line]) {\n    display: block;\n  }\n  :where([data-sx-text-word], [data-sx-text-char]) {\n    display: inline-block;\n  }\n  :where([data-sx-text-word]) {\n    white-space: nowrap;\n  }\n  :where([data-sx-text-char]) {\n    white-space: pre;\n  }\n  :where([data-sx-text-cover], [data-sx-text-layer]) {\n    display: none;\n    pointer-events: none;\n  }\n  :where([data-sx-text-layer]) {\n    position: absolute;\n    inset: 0;\n  }\n  :where([data-sx-text-layer][data-sx-text-slot=\"under\"]) {\n    z-index: -1;\n  }\n  :where([data-sx-text-layer] > :is(svg, video, canvas)) {\n    position: absolute;\n    inset: 0;\n    display: block;\n    inline-size: 100%;\n    block-size: 100%;\n  }\n  :where([data-sx-text-layer] > svg) {\n    overflow: visible;\n  }\n  :where([data-sx-text-fitted] path[data-sx-text-fit]) {\n    vector-effect: none;\n  }\n  :where([data-sx-text-layer] > video) {\n    object-fit: cover;\n  }\n  :where([data-sx-text-layer] svg text) {\n    font: inherit;\n    letter-spacing: inherit;\n  }\n  @supports (animation-timeline: view()) {\n    :where([data-sx-text-scroll]:not([data-sx-scroll=\"js\"])) { view-timeline: --sx-text-view block; }\n  }\n  :where([data-sx-text-node]) {\n    position: absolute;\n  }\n}";

package/dist/text/base.js

@@ -0,0 +1,86 @@
+// The structural sheet every Text ships: the pieces' boxes, the readable copy, the direction. Positioning only, no
+// colours: the text keeps the element's own look. Pure string, so it works without theme.css. See ./CLAUDE.md.
+import { LAYER_ORDER } from "../backgrounds/runtime/rootCss.js";
+// The readable copy is absolutely positioned. With no positioned parent it escaped a table's scroll box and widened the
+// docs page by 212px on a phone, so the text element holds it.
+export const TEXT_BASE_CSS = `${LAYER_ORDER}
+@layer components {
+  :where([data-sx-text]) {
+    --sx-text-dir: 1;
+    position: relative;
+  }
+  :where([data-sx-text]:dir(rtl)) {
+    --sx-text-dir: -1;
+  }
+  :where([data-sx-text-read]) {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+  :where([data-sx-text-frame]) {
+    position: relative;
+    display: inline-block;
+    max-inline-size: 100%;
+    isolation: isolate;
+  }
+  :where([data-sx-text-show] > [data-sx-text-paint]) {
+    display: inline-block;
+    max-inline-size: 100%;
+  }
+  :where([data-sx-text-show]) {
+    display: inline-block;
+    max-inline-size: 100%;
+  }
+  :where([data-sx-text-line]) {
+    display: block;
+  }
+  :where([data-sx-text-word], [data-sx-text-char]) {
+    display: inline-block;
+  }
+  :where([data-sx-text-word]) {
+    white-space: nowrap;
+  }
+  :where([data-sx-text-char]) {
+    white-space: pre;
+  }
+  :where([data-sx-text-cover], [data-sx-text-layer]) {
+    display: none;
+    pointer-events: none;
+  }
+  :where([data-sx-text-layer]) {
+    position: absolute;
+    inset: 0;
+  }
+  :where([data-sx-text-layer][data-sx-text-slot="under"]) {
+    z-index: -1;
+  }
+  :where([data-sx-text-layer] > :is(svg, video, canvas)) {
+    position: absolute;
+    inset: 0;
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+  :where([data-sx-text-layer] > svg) {
+    overflow: visible;
+  }
+  :where([data-sx-text-fitted] path[data-sx-text-fit]) {
+    vector-effect: none;
+  }
+  :where([data-sx-text-layer] > video) {
+    object-fit: cover;
+  }
+  :where([data-sx-text-layer] svg text) {
+    font: inherit;
+    letter-spacing: inherit;
+  }
+  @supports (animation-timeline: view()) {
+    :where([data-sx-text-scroll]:not([data-sx-scroll="js"])) { view-timeline: --sx-text-view block; }
+  }
+  :where([data-sx-text-node]) {
+    position: absolute;
+  }
+}`;

package/dist/text/cycle/WordCycle.d.ts

@@ -0,0 +1,40 @@
+import { type CSSProperties, type ElementType } from "react";
+import { type CycleLook } from "./css.js";
+export interface WordCycleProps {
+    /** The words that take turns. The first shows first, and alone without scripts or under reduced motion. */
+    readonly words: readonly string[];
+    /**
+     * How one word gives way to the next:
+     * - `slide` (default), `flip`, `blur`: the word slides up, turns over, or blurs into the next;
+     * - `box`: in a coloured box that fits each word; `layout`: the sentence around it reflows to each word's width;
+     * - `flap`: letter tiles flip like an airport board; `morph`: the words melt into each other;
+     * - `anagram`: the letters move to their places in the next word; `shuffle`: each letter rolls like a slot machine;
+     * - `strike`: the old word is struck through, the new one writes in;
+     * - `focus`: every word shows, one sharp in a frame, the rest blurred (a sentence, not words in one place).
+     */
+    readonly look?: CycleLook;
+    /** Seconds each word stays. Default `2.5`. */
+    readonly interval?: number;
+    /** Seconds the change takes. Default `0.5`. */
+    readonly duration?: number;
+    /** Where a shorter word sits in the space of the longest: `start` (default), `center`, `end`. */
+    readonly align?: "start" | "center" | "end";
+    /** The box's (`box`) or the frame's (`focus`) colour. Default the theme's accent. */
+    readonly color?: string;
+    /** The element to render. Default `span`. */
+    readonly as?: ElementType;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * One word in a sentence that keeps changing: "We build websites / apps / brands".
+ *
+ * ```tsx
+ * <h1>We build <WordCycle words={["websites", "apps", "brands"]} look="flip" /></h1>
+ * ```
+ *
+ * Every word is in the HTML, stacked in one place, so search engines read them all and the space is the longest
+ * word's: nothing around it jumps (except with `layout`, whose point is the reflow). Screen readers read the words once,
+ * not on every change. It moves on only while on screen; under reduced motion the first word stays.
+ */
+export declare function WordCycle({ words, look, interval, duration, align, color, as: Tag, className, style, }: WordCycleProps): import("react").JSX.Element;

package/dist/text/cycle/WordCycle.js

@@ -0,0 +1,179 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+import { rng } from "../../backgrounds/runtime/rng.js";
+import { motionOnly } from "../../transitions/progress.js";
+import { reducedMotion, watchOnScreen } from "../runtime/onScreen.js";
+import { loopsPaused, onLoopsPaused } from "../runtime/loops.js";
+import { lettersOf, splitWords } from "../split.js";
+import { CYCLE_BASE_CSS, CYCLE_LOOK_CSS } from "./css.js";
+const seconds = (n) => `${Number(n.toFixed(3))}s`;
+/** Random letters a shuffle reel passes through before it lands. */
+const REEL = 6;
+/** How many times the word has changed, every `interval` seconds while on screen and motion is welcome. */
+function useTurn(ref, count, interval) {
+    const [turn, setTurn] = useState(0);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        el.setAttribute("data-sx-live", "");
+        if (count < 2 || reducedMotion())
+            return;
+        let timer = 0;
+        let visible = false;
+        // runs only on screen and while the page's loops aren't paused (setLoopsPaused / usePauseLoops)
+        const sync = () => {
+            window.clearInterval(timer);
+            if (visible && !loopsPaused())
+                timer = window.setInterval(() => !document.hidden && setTurn((t) => t + 1), interval * 1000);
+        };
+        const stop = watchOnScreen(el, (on) => {
+            visible = on;
+            sync();
+        });
+        const stopPause = onLoopsPaused(sync);
+        return () => {
+            stop();
+            stopPause();
+            window.clearInterval(timer);
+        };
+    }, [ref, count, interval]);
+    return turn;
+}
+const stateOf = (i, on, prev) => (i === on ? "on" : i === prev ? "off" : "wait");
+/**
+ * One word in a sentence that keeps changing: "We build websites / apps / brands".
+ *
+ * ```tsx
+ * <h1>We build <WordCycle words={["websites", "apps", "brands"]} look="flip" /></h1>
+ * ```
+ *
+ * Every word is in the HTML, stacked in one place, so search engines read them all and the space is the longest
+ * word's: nothing around it jumps (except with `layout`, whose point is the reflow). Screen readers read the words once,
+ * not on every change. It moves on only while on screen; under reduced motion the first word stays.
+ */
+export function WordCycle({ words, look = "slide", interval = 2.5, duration = 0.5, align = "start", color = "var(--color-sx-accent)", as: Tag = "span", className, style, }) {
+    const ref = useRef(null);
+    // the turn only moves on by one, so the word leaving is known in the same render as the one arriving
+    const turn = useTurn(ref, words.length, interval);
+    const count = Math.max(1, words.length);
+    const on = turn % count;
+    const last = turn > 0 ? (turn - 1) % count : -1;
+    const uid = `sx${useId().replace(/[^\w-]/g, "")}`;
+    // letters of each word (whole words in a joined script), for the looks that move letters
+    const letters = useMemo(() => words.map((w) => splitWords(w).flatMap((p) => (p.space ? [p.text] : lettersOf(p.text)))), [words]);
+    const longest = Math.max(0, ...letters.map((l) => l.length));
+    useMeasure(ref, look, on, words);
+    useAnagram(ref, look, on);
+    const vars = {
+        "--sx-cycle-time": seconds(duration),
+        "--sx-cycle-align": align,
+        "--sx-cycle-color": color,
+        "--sx-cycle-blur": "0.08em",
+        ...(look === "morph" ? { "--sx-cycle-filter": `url(#${uid}-morph)` } : {}),
+        ...style,
+    };
+    const motion = motionOnly(CYCLE_LOOK_CSS[look]);
+    let body;
+    if (look === "focus") {
+        // the words as one sentence; four corners frame the sharp one
+        body = (_jsxs(_Fragment, { children: [words.map((w, i) => (_jsxs("span", { children: [i > 0 ? " " : null, _jsx("span", { "data-sx-cycle-word": "", "data-sx-cycle-state": i === on ? "on" : "wait", children: w })] }, i))), _jsx("span", { "data-sx-cycle-frame": "", children: [0, 1, 2, 3].map((c) => _jsx("span", { "data-c": c }, c)) })] }));
+    }
+    else if (look === "flap") {
+        // one tile per letter of the longest word; each tile holds that letter of every word
+        body = (_jsx("span", { "data-sx-cycle-tiles": "", children: Array.from({ length: longest }, (_, t) => (_jsx("span", { "data-sx-cycle-tile": "", style: { "--sx-i": t }, children: letters.map((l, i) => (_jsx("span", { "data-sx-cycle-state": stateOf(i, on, last), children: l[t] ?? " " }, i))) }, t))) }));
+    }
+    else if (look === "anagram") {
+        // every word sizes the stack; the live word's letters are keyed by letter and its count, so a letter that the next
+        // word shares is the same element, and moves there
+        const seen = new Map();
+        body = (_jsxs(_Fragment, { children: [words.map((w, i) => _jsx("span", { "data-sx-cycle-size": "", children: w }, i)), _jsx("span", { "data-sx-cycle-live": "", children: (letters[on] ?? []).map((l) => {
+                        const n = seen.get(l) ?? 0;
+                        seen.set(l, n + 1);
+                        return _jsx("span", { "data-sx-cycle-letter": "", "data-sx-cycle-key": `${l}-${n}`, children: l }, `${l}-${n}`);
+                    }) })] }));
+    }
+    else {
+        body = (_jsxs(_Fragment, { children: [look === "box" ? _jsx("span", { "data-sx-cycle-box": "" }) : null, words.map((w, i) => (_jsxs("span", { "data-sx-cycle-word": "", "data-sx-cycle-state": stateOf(i, on, last), "data-sx-cycle-i": i, children: [look === "shuffle" ? _jsx(Reel, { letters: letters[i] ?? [], pool: letters.flat(), seed: i + 1 }) : w, look === "strike" ? _jsx("span", { "data-sx-cycle-line": "" }) : null] }, i)))] }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("cycle-base", CYCLE_BASE_CSS), precedence: "sx", children: CYCLE_BASE_CSS }), _jsx("style", { href: styleHref(`cycle-${look}`, motion), precedence: "sx", children: motion }), _jsxs(Tag, { ref: ref, "data-sx-cycle": look, className: className, style: vars, children: [_jsx("span", { "data-sx-text-read": "", children: look === "focus" ? words.join(" ") : words.join(", ") }), look === "morph" ? (_jsx("svg", { "data-sx-cycle-defs": "", "aria-hidden": true, focusable: "false", children: _jsx("filter", { id: `${uid}-morph`, children: _jsx("feColorMatrix", { in: "SourceGraphic", type: "matrix", values: "1 0 0 0 0  0 1 0 0 0  0 0 1 0 0  0 0 0 255 -140" }) }) })) : null, _jsx("span", { "data-sx-cycle-stack": "", "aria-hidden": true, children: body })] })] }));
+}
+/** A slot-machine reel per letter: seeded random letters, then the real one, rolled into place. */
+function Reel({ letters, pool, seed }) {
+    const chars = pool.filter((c) => c.trim());
+    const r = rng(seed);
+    return (_jsx(_Fragment, { children: letters.map((l, i) => l.trim() ? (_jsxs("span", { "data-sx-cycle-reel": "", style: { "--sx-i": i, "--sx-cycle-k": REEL }, children: [_jsx("span", { "data-sx-cycle-letter-size": "", children: l }), _jsxs("span", { "data-sx-cycle-strip": "", children: [Array.from({ length: REEL }, (_, k) => _jsx("span", { children: chars[Math.floor(r() * chars.length)] ?? l }, k)), _jsx("span", { children: l })] })] }, i)) : (l)) }));
+}
+/** The looks that need sizes: the box's share of the widest word, the layout's width, the focus frame's box. */
+function useMeasure(ref, look, on, words) {
+    useLayoutEffect(() => {
+        const el = ref.current;
+        const stack = el?.querySelector("[data-sx-cycle-stack]");
+        if (!el || !stack || (look !== "box" && look !== "layout" && look !== "focus"))
+            return;
+        const measure = () => {
+            const word = stack.querySelector(`[data-sx-cycle-word][data-sx-cycle-state="on"]`);
+            if (!word)
+                return;
+            if (look === "focus") {
+                const box = stack.getBoundingClientRect();
+                const r = word.getBoundingClientRect();
+                const rtl = getComputedStyle(el).direction === "rtl";
+                stack.style.setProperty("--fx", `${rtl ? box.right - r.right : r.left - box.left}px`);
+                stack.style.setProperty("--fy", `${r.top - box.top}px`);
+                stack.style.setProperty("--fw", `${r.width}px`);
+                stack.style.setProperty("--fh", `${r.height}px`);
+                el.setAttribute("data-sx-cycle-measured", "");
+                return;
+            }
+            const widths = [...stack.querySelectorAll("[data-sx-cycle-word]")].map((w) => w.offsetWidth);
+            const widest = Math.max(1, ...widths);
+            if (look === "box")
+                el.style.setProperty("--sx-cycle-w", String(word.offsetWidth / widest));
+            else
+                el.style.setProperty("--sx-cycle-w-px", `${word.offsetWidth}px`);
+        };
+        measure();
+        let gone = false;
+        void document.fonts?.ready.then(() => !gone && measure());
+        const ro = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(measure);
+        ro?.observe(el.parentElement ?? el);
+        return () => {
+            gone = true;
+            ro?.disconnect();
+        };
+    }, [ref, look, on, words]);
+}
+/** Anagram: each letter that stays starts where it was in the last word and moves to its new place (FLIP). */
+function useAnagram(ref, look, on) {
+    const before = useRef(new Map());
+    useLayoutEffect(() => {
+        const live = ref.current?.querySelector("[data-sx-cycle-live]");
+        if (look !== "anagram" || !live)
+            return;
+        const letters = [...live.querySelectorAll("[data-sx-cycle-letter]")];
+        const was = before.current;
+        const now = new Map(letters.map((l) => [l.dataset["sxCycleKey"] ?? "", l.getBoundingClientRect()]));
+        if (was.size > 0 && !reducedMotion()) {
+            for (const l of letters) {
+                const key = l.dataset["sxCycleKey"] ?? "";
+                const from = was.get(key);
+                const to = now.get(key);
+                l.setAttribute("data-sx-cycle-jump", "");
+                if (from && to)
+                    l.style.translate = `${from.left - to.left}px ${from.top - to.top}px`;
+                else
+                    l.setAttribute("data-sx-cycle-new", "");
+            }
+            void live.offsetWidth; // apply the starting places before they move
+            for (const l of letters) {
+                l.removeAttribute("data-sx-cycle-jump");
+                l.removeAttribute("data-sx-cycle-new");
+                l.style.translate = "";
+            }
+        }
+        before.current = now;
+    }, [ref, look, on]);
+}

package/dist/text/cycle/WordCycle.schema.d.ts

@@ -0,0 +1 @@
+export declare const WORD_CYCLE_SCHEMA: import("../../schema/types.js").Schema;

package/dist/text/cycle/WordCycle.schema.js

@@ -0,0 +1,28 @@
+import { defineSchema } from "../../schema/define.js";
+// WordCycle's props as a form (the Hero's `titleCycle`). The words are the page's content, written by the page.
+export const WORD_CYCLE_SCHEMA = defineSchema()({
+    id: "wordCycle",
+    family: "word-cycle",
+    factory: "WordCycle",
+    code: ["words", "as", "className", "style"],
+    fields: {
+        look: {
+            kind: "choice", label: "Look",
+            values: ["slide", "flip", "blur", "box", "layout", "flap", "morph", "anagram", "shuffle", "strike", "focus"],
+            labels: {
+                slide: "Slide up", flip: "Flip over", blur: "Blur", box: "In a coloured box", layout: "Sentence reflows",
+                flap: "Airport board", morph: "Melt", anagram: "Letters rearrange", shuffle: "Slot machine", strike: "Strike and rewrite",
+                focus: "Focus frame (all words show)",
+            },
+            default: "slide",
+        },
+        interval: { kind: "number", label: "Each word stays", min: 1, max: 8, step: 0.5, unit: "s", default: 2.5 },
+        duration: { kind: "number", label: "Change takes", min: 0.2, max: 1.5, step: 0.05, unit: "s", default: 0.5 },
+        align: {
+            kind: "choice", label: "Shorter words sit", values: ["start", "center", "end"],
+            labels: { start: "At the start", center: "In the middle", end: "At the end" }, default: "start",
+            help: "The space is the longest word's, so nothing around it jumps.",
+        },
+        color: { kind: "color", label: "Box or frame colour", default: "var(--color-sx-accent)", help: "Used by the box and focus looks." },
+    },
+});

package/dist/text/cycle/css.d.ts

@@ -0,0 +1,5 @@
+export declare const CYCLE_LOOKS: readonly ["slide", "flip", "blur", "box", "layout", "flap", "morph", "anagram", "shuffle", "strike", "focus"];
+export type CycleLook = (typeof CYCLE_LOOKS)[number];
+/** Words that take turns share one grid cell: the stack is as wide as the longest, so nothing around it moves. */
+export declare const CYCLE_BASE_CSS = "@layer theme, base, components, utilities;\n@layer components {\n  :where([data-sx-cycle]) { --sx-cycle-dir: 1; position: relative; }\n  :where([data-sx-cycle]:dir(rtl)) { --sx-cycle-dir: -1; }\n  :where([data-sx-cycle] [data-sx-text-read]) {\n    position: absolute;\n    inline-size: 1px;\n    block-size: 1px;\n    overflow: hidden;\n    clip-path: inset(50%);\n    white-space: nowrap;\n  }\n  :where([data-sx-cycle] [data-sx-cycle-stack]) { position: relative; display: inline-grid; vertical-align: bottom; white-space: nowrap; }\n  :where([data-sx-cycle] [data-sx-cycle-stack] > *) { grid-area: 1 / 1; justify-self: var(--sx-cycle-align, start); }\n  :where([data-sx-cycle] [data-sx-cycle-word]:not([data-sx-cycle-state=\"on\"]), [data-sx-cycle] [data-sx-cycle-size]) { visibility: hidden; }\n  :where([data-sx-cycle] :is([data-sx-cycle-tile], [data-sx-cycle-letter])) { display: inline-block; white-space: pre; }\n  :where([data-sx-cycle] [data-sx-cycle-tiles]) { display: inline-flex; }\n  :where([data-sx-cycle] [data-sx-cycle-tile]) { display: inline-grid; }\n  :where([data-sx-cycle] [data-sx-cycle-tile] > *) { grid-area: 1 / 1; }\n  :where([data-sx-cycle] [data-sx-cycle-tile] > :not([data-sx-cycle-state=\"on\"])) { visibility: hidden; }\n  :where([data-sx-cycle] :is([data-sx-cycle-line], [data-sx-cycle-box], [data-sx-cycle-frame], [data-sx-cycle-defs])) { display: none; }\n  :where([data-sx-cycle] [data-sx-cycle-reel]) { position: relative; display: inline-block; overflow: clip; vertical-align: bottom; }\n  :where([data-sx-cycle] [data-sx-cycle-reel] > [data-sx-cycle-letter-size]) { visibility: hidden; }\n  :where([data-sx-cycle] [data-sx-cycle-strip]) {\n    position: absolute;\n    inset-block-start: 0;\n    inset-inline: 0;\n    display: flex;\n    flex-direction: column;\n    align-items: center;\n    translate: 0 calc(var(--sx-cycle-k) * -1lh);\n  }\n  :where([data-sx-cycle][data-sx-cycle=\"focus\"] [data-sx-cycle-stack]) { display: inline; white-space: normal; }\n  :where([data-sx-cycle][data-sx-cycle=\"focus\"] [data-sx-cycle-word]) { visibility: visible; }\n  :where([data-sx-cycle][data-sx-cycle=\"layout\"] [data-sx-cycle-stack]) { overflow: clip; inline-size: var(--sx-cycle-w-px, auto); }\n}";
+export declare const CYCLE_LOOK_CSS: Readonly<Record<CycleLook, string>>;