@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/text/effects/ink/inkSweep.d.ts

@@ -0,0 +1,13 @@
+import type { TextEffect } from "../../types.js";
+export interface InkSweepOptions {
+    /** The band's colours. Default the theme's primary and accent. */
+    readonly colors?: readonly string[];
+    /** How wide the band is, in % of the text. Default `35`. */
+    readonly width?: number;
+    /** Seconds the band takes to cross. Default `1.4`. */
+    readonly duration?: number;
+    /** Seconds before it starts. Default `0`. */
+    readonly delay?: number;
+}
+/** A band of colour passes over the text once as it enters, and the text settles into its own colour behind it. */
+export declare function inkSweep(options?: InkSweepOptions): TextEffect;

package/dist/text/effects/ink/inkSweep.js

@@ -0,0 +1,33 @@
+import { SHOW, at, defineText, enter, hostOf, partOf, scripted, seconds, v, varName } from "../kit.js";
+import { THEME_COLORS, fromStart, windowEnd, windowParts } from "./kit.js";
+const ID = "inkSweep";
+const parts = windowParts(ID);
+const end = windowEnd(ID);
+// The text is revealed from the reading start just behind the band, so the band seems to leave the text in its wake.
+// The window shows only where an entrance can play: without scripts it would sit still over the start of the text.
+const CSS = `${scripted(parts.css)}
+  ${at(`${hostOf(ID)} ${partOf(ID, "copy")}`)} {
+    background: ${v(ID, "image")};
+    -webkit-background-clip: text;
+    background-clip: text;
+    -webkit-text-fill-color: transparent;
+  }
+${enter(ID, { target: partOf(ID, "win"), name: "win", from: parts.win, frames: `from { ${parts.win} } to { ${end.win} }`, ease: "linear" })}
+${enter(ID, { target: partOf(ID, "copy"), name: "copy", from: parts.copy, frames: `from { ${parts.copy} } to { ${end.copy} }`, ease: "linear" })}
+${enter(ID, { target: SHOW, name: "text", from: `clip-path: ${fromStart("0")};`, frames: `from { clip-path: ${fromStart("0")}; } to { clip-path: ${fromStart("1")}; }`, ease: "linear" })}`;
+/** A band of colour passes over the text once as it enters, and the text settles into its own colour behind it. */
+export function inkSweep(options = {}) {
+    const colors = options.colors ?? THEME_COLORS;
+    return defineText(ID, CSS, {
+        vars: {
+            [varName(ID, "image")]: `linear-gradient(90deg, ${colors.join(", ")})`,
+            [varName(ID, "width")]: options.width ?? 35,
+            [varName(ID, "time")]: seconds(options.duration ?? 1.4),
+            [varName(ID, "stagger")]: "0s",
+            [varName(ID, "delay")]: seconds(options.delay ?? 0),
+        },
+        layers: [{ window: true }],
+        claims: ["enter"],
+        needs: { inView: true },
+    });
+}

package/dist/text/effects/ink/inkSweep.schema.d.ts

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

package/dist/text/effects/ink/inkSweep.schema.js

@@ -0,0 +1,13 @@
+import { colorsField } from "../../../schema/common.js";
+import { defineSchema } from "../../../schema/define.js";
+export const INK_SWEEP_SCHEMA = defineSchema()({
+    id: "inkSweep",
+    family: "text",
+    factory: "inkSweep",
+    fields: {
+        colors: colorsField(["var(--color-sx-primary)", "var(--color-sx-accent)"]),
+        width: { kind: "number", label: "Band width", min: 5, max: 80, step: 1, unit: "%", default: 35 },
+        duration: { kind: "number", label: "Duration", min: 0.3, max: 5, step: 0.1, unit: "s", default: 1.4 },
+        delay: { kind: "number", label: "Delay", min: 0, max: 3, step: 0.05, unit: "s", default: 0 },
+    },
+});

package/dist/text/effects/ink/inkVideo.d.ts

@@ -0,0 +1,11 @@
+import type { TextEffect } from "../../types.js";
+export interface InkVideoOptions {
+    /** The video seen through the letters: muted, looped, played only while the text is on screen. */
+    readonly src?: string;
+    /** A picture shown before the video plays, and under reduced motion. */
+    readonly poster?: string;
+    /** The colour around the letters: the page's background behind the text. Default the theme's surface. */
+    readonly cover?: string;
+}
+/** A video plays inside the letters. One line of text; the video file is the real cost. */
+export declare function inkVideo(options?: InkVideoOptions): TextEffect;

package/dist/text/effects/ink/inkVideo.js

@@ -0,0 +1,23 @@
+import { SHOW, at, defineText, hostOf, layerOf, partOf, v, varName } from "../kit.js";
+const ID = "inkVideo";
+// The video sits behind a cover in the page's colour with the text cut out of it (an SVG mask), so the video shows
+// only through the letters. Browsers can't clip a video to HTML text, so the visible text is the SVG's, on one line;
+// the HTML text stays for screen readers and holds the size, unseen. The cover's outline reaches 2px past the box, so
+// rounding never leaves a sliver of video at an edge (found in Firefox).
+const LOOK = `  ${at(`${hostOf(ID)} ${SHOW}`)} { opacity: 0; white-space: nowrap; }
+  ${at(`${hostOf(ID)} ${layerOf(ID)}`)} { display: block; }
+  ${at(`${hostOf(ID)} ${partOf(ID, "cover")}`)} { fill: ${v(ID, "cover")}; stroke: ${v(ID, "cover")}; stroke-width: 4px; }`;
+/** A video plays inside the letters. One line of text; the video file is the real cost. */
+export function inkVideo(options = {}) {
+    return defineText(ID, "", {
+        look: LOOK,
+        vars: { [varName(ID, "cover")]: options.cover ?? "var(--color-sx-secondary)" },
+        layers: options.src
+            ? [
+                { slot: "under", video: { src: options.src, ...(options.poster ? { poster: options.poster } : {}) } },
+                { svgText: "cutout" },
+            ]
+            : [],
+        claims: ["paint"],
+    });
+}

package/dist/text/effects/ink/inkVideo.schema.d.ts

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

package/dist/text/effects/ink/inkVideo.schema.js

@@ -0,0 +1,11 @@
+import { defineSchema } from "../../../schema/define.js";
+export const INK_VIDEO_SCHEMA = defineSchema()({
+    id: "inkVideo",
+    family: "text",
+    factory: "inkVideo",
+    fields: {
+        src: { kind: "text", label: "Video", url: true, placeholder: "/clip.mp4", required: true },
+        poster: { kind: "text", label: "Poster", url: true, advanced: true, autoNote: "none" },
+        cover: { kind: "color", label: "Around the letters", default: "var(--color-sx-secondary)" },
+    },
+});

package/dist/text/effects/ink/kit.d.ts

@@ -0,0 +1,26 @@
+/** The fills' default colours: the theme's primary and accent. */
+export declare const THEME_COLORS: readonly string[];
+/** A left-to-right gradient that ends where it starts, so a tile of it repeats with no seam. */
+export declare const seamless: (colors: readonly string[]) => string;
+/**
+ * The window: a soft-edged slot `width`% of the text wide slides across it while the copy inside slides back, so the
+ * copy stays put and only the slot moves. Both are `translate`, so the compositor runs it and nothing repaints. The
+ * slot starts just before the reading start and ends just past the reading end. Returns the rules for the layer, and
+ * the two keyframes bodies (`win`, `copy`) to animate.
+ *
+ * The layer is a size container and the copy is `100cqi` wide: exactly the text's width, whatever box holds it. Sized
+ * from the slot (`100 / width` slots) it rounded a hair narrower, wrapped onto a second line and sat off the text in
+ * WebKit and Firefox; and a moving slot is the copy's containing block, so `inset: 0` would measure the slot.
+ */
+export declare function windowParts(id: string): {
+    readonly css: string;
+    readonly win: string;
+    readonly copy: string;
+};
+/** Where the window ends: the slot past the reading end, the copy back by the same distance. */
+export declare const windowEnd: (id: string) => {
+    readonly win: string;
+    readonly copy: string;
+};
+/** `clip-path` that hides all but the first `share` (0 to 1) of the text from the reading start. */
+export declare const fromStart: (share: string) => string;

package/dist/text/effects/ink/kit.js

@@ -0,0 +1,47 @@
+// What the fills share: theme colour lists, a seamless gradient, and the sliding window over a copy of the text.
+import { DIR, at, hostOf, layerOf, partOf, v } from "../kit.js";
+/** The fills' default colours: the theme's primary and accent. */
+export const THEME_COLORS = ["var(--color-sx-primary)", "var(--color-sx-accent)"];
+/** A left-to-right gradient that ends where it starts, so a tile of it repeats with no seam. */
+export const seamless = (colors) => `linear-gradient(90deg, ${[...colors, colors[0] ?? "currentColor"].join(", ")})`;
+/**
+ * The window: a soft-edged slot `width`% of the text wide slides across it while the copy inside slides back, so the
+ * copy stays put and only the slot moves. Both are `translate`, so the compositor runs it and nothing repaints. The
+ * slot starts just before the reading start and ends just past the reading end. Returns the rules for the layer, and
+ * the two keyframes bodies (`win`, `copy`) to animate.
+ *
+ * The layer is a size container and the copy is `100cqi` wide: exactly the text's width, whatever box holds it. Sized
+ * from the slot (`100 / width` slots) it rounded a hair narrower, wrapped onto a second line and sat off the text in
+ * WebKit and Firefox; and a moving slot is the copy's containing block, so `inset: 0` would measure the slot.
+ */
+export function windowParts(id) {
+    const w = v(id, "width");
+    const css = `  ${at(`${hostOf(id)} ${layerOf(id)}`)} { display: block; overflow: hidden; container-type: inline-size; }
+  ${at(`${hostOf(id)} ${partOf(id, "win")}`)} {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 0;
+    inline-size: calc(${w} * 1%);
+    overflow: hidden;
+    -webkit-mask-image: linear-gradient(90deg, transparent, black 35% 65%, transparent);
+    mask-image: linear-gradient(90deg, transparent, black 35% 65%, transparent);
+  }
+  ${at(`${hostOf(id)} ${partOf(id, "copy")}`)} {
+    position: absolute;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    inline-size: 100cqi;
+  }`;
+    return {
+        css,
+        win: `translate: calc(-100% * ${DIR}) 0;`,
+        copy: `translate: calc(${w} * 1% * ${DIR}) 0;`,
+    };
+}
+/** Where the window ends: the slot past the reading end, the copy back by the same distance. */
+export const windowEnd = (id) => ({
+    win: `translate: calc(100% * 100 / ${v(id, "width")} * ${DIR}) 0;`,
+    copy: `translate: calc(-100% * ${DIR}) 0;`,
+});
+/** `clip-path` that hides all but the first `share` (0 to 1) of the text from the reading start. */
+export const fromStart = (share) => `inset(0 calc((1 + ${DIR}) / 2 * (1 - ${share}) * 100%) 0 calc((1 - ${DIR}) / 2 * (1 - ${share}) * 100%))`;

package/dist/text/effects/ink/lines.d.ts

@@ -0,0 +1,8 @@
+export interface LinesSettings {
+    readonly colors: readonly string[];
+    readonly count: number;
+    readonly speed: number;
+    readonly width: number;
+}
+/** Starts it on the text element. Returns what stops it. */
+export declare function attachLines(el: HTMLElement, settings: LinesSettings): () => void;

package/dist/text/effects/ink/lines.js

@@ -0,0 +1,123 @@
+// inkLines' program: the text drawn on a canvas where the page laid it out, with moving curved lines kept inside the
+// letters. Imported only by inkLines, so a page without it downloads none of this.
+import { createColorResolver } from "../../../backgrounds/runtime/color.js";
+import { wordsIn } from "../../runtime/canvasText.js";
+const rgba = ([r, g, b, a]) => `rgba(${r}, ${g}, ${b}, ${a})`;
+/** Starts it on the text element. Returns what stops it. */
+export function attachLines(el, settings) {
+    const layer = el.querySelector('[data-sx-text-layer="inkLines"]');
+    const show = el.querySelector("[data-sx-text-show]");
+    if (!layer || !show)
+        return () => { };
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+    if (!ctx)
+        return () => { };
+    layer.appendChild(canvas);
+    const resolver = createColorResolver(el);
+    const still = window.matchMedia("(prefers-reduced-motion: reduce)");
+    // the letters, drawn once per measure: a solid copy to cut the lines to, a faint one behind them
+    const solid = document.createElement("canvas");
+    const faint = document.createElement("canvas");
+    let colors = [];
+    let w = 0;
+    let h = 0;
+    let dpr = 1;
+    const lettersOn = (target, fill, words, font, rtl) => {
+        target.width = canvas.width;
+        target.height = canvas.height;
+        const c = target.getContext("2d");
+        if (!c)
+            return;
+        c.setTransform(dpr, 0, 0, dpr, 0, 0);
+        c.font = font;
+        c.direction = rtl ? "rtl" : "ltr";
+        c.textAlign = rtl ? "right" : "left";
+        c.textBaseline = "alphabetic";
+        c.fillStyle = fill;
+        for (const word of words) {
+            const m = c.measureText(word.text);
+            const ascent = m.fontBoundingBoxAscent;
+            c.fillText(word.text, word.x, word.y + (word.h - (ascent + m.fontBoundingBoxDescent)) / 2 + ascent);
+        }
+    };
+    const measure = () => {
+        const box = layer.getBoundingClientRect();
+        const style = getComputedStyle(show);
+        const rtl = style.direction === "rtl";
+        const font = `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+        // the letters a faint version of their colour, so lines in any theme colour show on them
+        const [r, g, b, alpha] = resolver.resolve(style.color);
+        colors = settings.colors.map((c) => rgba(resolver.resolve(c)));
+        const words = wordsIn(show, box, rtl);
+        dpr = Math.min(2, window.devicePixelRatio || 1);
+        w = box.width;
+        h = box.height;
+        canvas.width = Math.max(1, Math.round(w * dpr));
+        canvas.height = Math.max(1, Math.round(h * dpr));
+        lettersOn(solid, "black", words, font, rtl);
+        lettersOn(faint, rgba([r, g, b, alpha * 0.3]), words, font, rtl);
+    };
+    // The lines at full strength, cut to the letters, then the faint letters behind them.
+    const draw = (t) => {
+        ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        ctx.globalCompositeOperation = "source-over";
+        ctx.clearRect(0, 0, w, h);
+        ctx.lineWidth = settings.width;
+        ctx.lineCap = "round";
+        for (let i = 0; i < settings.count; i++) {
+            const phase = t * settings.speed + i * 1.7;
+            const y0 = ((i + 0.5) / settings.count) * h;
+            ctx.strokeStyle = colors[i % Math.max(1, colors.length)] ?? "currentColor";
+            ctx.beginPath();
+            ctx.moveTo(-10, y0 + Math.sin(phase) * h * 0.3);
+            ctx.bezierCurveTo(w * 0.3, y0 + Math.cos(phase * 1.3) * h * 0.6, w * 0.7, y0 + Math.sin(phase * 0.8 + 1) * h * 0.6, w + 10, y0 + Math.cos(phase) * h * 0.3);
+            ctx.stroke();
+        }
+        ctx.setTransform(1, 0, 0, 1, 0, 0);
+        ctx.globalCompositeOperation = "destination-in";
+        ctx.drawImage(solid, 0, 0);
+        ctx.globalCompositeOperation = "destination-over";
+        ctx.drawImage(faint, 0, 0);
+        el.setAttribute("data-sx-text-drawn", "");
+    };
+    let frame = 0;
+    let on = false;
+    const start = performance.now();
+    const tick = (now) => {
+        frame = 0;
+        draw((now - start) / 1000);
+        if (on && !still.matches)
+            frame = requestAnimationFrame(tick);
+    };
+    const run = () => {
+        cancelAnimationFrame(frame);
+        frame = requestAnimationFrame(tick);
+    };
+    const io = new IntersectionObserver(([entry]) => {
+        on = !!entry?.isIntersecting;
+        if (on)
+            run();
+    });
+    const ro = new ResizeObserver(() => {
+        measure();
+        run();
+    });
+    measure();
+    io.observe(el);
+    ro.observe(layer);
+    still.addEventListener("change", run);
+    void document.fonts?.ready.then(() => {
+        measure();
+        run();
+    });
+    return () => {
+        cancelAnimationFrame(frame);
+        io.disconnect();
+        ro.disconnect();
+        still.removeEventListener("change", run);
+        resolver.dispose();
+        canvas.remove();
+        el.removeAttribute("data-sx-text-drawn");
+    };
+}

package/dist/text/effects/kit.d.ts

@@ -0,0 +1,115 @@
+import type { TextClaim, TextEffect, TextLayer, TextNeeds, TextProgram, TextTier, TextVars } from "../types.js";
+/** An effect's option as a custom property: `--sx-text-enterRise-time`. */
+export declare const varName: (id: string, name: string) => `--${string}`;
+/** Read it. */
+export declare const v: (id: string, name: string) => string;
+/** 1, or -1 in a right-to-left context. Physical values multiply by it. */
+export declare const DIR = "var(--sx-text-dir)";
+/** The reading start and end as a `transform-origin` x. */
+export declare const START_X = "calc(50% - 50% * var(--sx-text-dir))";
+export declare const END_X = "calc(50% + 50% * var(--sx-text-dir))";
+/** The text element wearing this effect, as a raw selector. */
+export declare const hostOf: (id: string) => string;
+/** The pieces an entrance moves (letters, words, lines, or the whole text), as a raw selector inside the host. */
+export declare const UNIT = "[data-sx-text-unit]";
+/** What shows: the pieces, or the plain text when nothing is cut. */
+export declare const SHOW = "[data-sx-text-show]";
+/** The bar inside each piece (`needs.cover`). */
+export declare const COVER = "[data-sx-text-unit] > [data-sx-text-cover]";
+/** An effect's layer. */
+export declare const layerOf: (id: string, part?: string) => string;
+/** Wrap a raw selector. */
+export declare const at: (raw: string) => string;
+/** The easing most entrances use. */
+export declare const EASE = "var(--ease-sx-out, cubic-bezier(0.2, 0.7, 0.2, 1))";
+/** A springy curve that overshoots and settles. */
+export declare const SPRING = "linear(0, 0.45 12%, 0.85 25%, 1.08 38%, 1.1 46%, 1.03 62%, 0.99 78%, 1)";
+/** Seconds as CSS, rounded so a stagger's float sums don't leak 0.15000000000000002 into the markup. */
+export declare const seconds: (n: number) => string;
+/** How long a page waits for the script before a waiting entrance plays on its own (atlas rule 7). */
+export declare const FAIL_SAFE = "3s";
+export interface EnterRule {
+    /** The element that animates, as a raw selector inside the host. Default the pieces (`UNIT`). */
+    readonly target?: string;
+    /** The keyframes' first frame: the pose the text waits in. Its last frame is the element's own style. */
+    readonly from: string;
+    /** Whole keyframes instead (`0% { … } 55% { … }`); `from` is still the waiting pose. */
+    readonly frames?: string;
+    /** The keyframes' name after `sx-text-<id>-`, when an effect has several. */
+    readonly name?: string;
+    readonly ease?: string;
+    /** Only on hosts that also match this (`[data-sx-text-joined]`), written after the plain rules so it wins. */
+    readonly when?: string;
+}
+/**
+ * An entrance: the waiting pose, then the keyframes, each piece `--sx-o` staggers later. Three states, all inside
+ * `@media (scripting: enabled)`, so a page without scripts shows the text as it is:
+ * - before the script runs: the entrance plays on its own after `FAIL_SAFE`, so text is never stuck hidden;
+ * - the script runs (`data-sx-text-live`), not in view yet: the waiting pose holds;
+ * - in view (`data-sx-in`): it plays. `data-sx-text-done` (lines measured again after it played) stops it at rest.
+ */
+export declare function enter(id: string, rule: EnterRule): string;
+/** Rules that matter only while an entrance can play (a bar over each word): inside `@media (scripting: enabled)`. */
+export declare const scripted: (rules: string) => string;
+/** What a paint effect fills: the span around the text, or around each piece's text (`needs.paint`). */
+export declare const PAINT = "[data-sx-text-paint]";
+/** A part inside an effect's layer. */
+export declare const partOf: (id: string, part: string, layerPart?: string) => string;
+/** Where each paint span sits in the whole text, as a `background-position`: one fill runs across pieces that move. */
+export declare const PAINT_AT = "calc(var(--sx-tx, 0px) * -1) calc(var(--sx-ty, 0px) * -1)";
+/** The whole text's size, as a `background-size`. */
+export declare const PAINT_SIZE = "var(--sx-tw, 100%) var(--sx-th, 100%)";
+/**
+ * Hides the letters' own fill with `-webkit-text-fill-color`, never `color: transparent`: that would also turn every
+ * `currentColor` in the fill, and in an outline, transparent.
+ *
+ * Fills the letters with `background` (one image or a list), sized and placed on the whole text so it stays seamless
+ * however the text is cut. `size` replaces the size list for an effect with several images.
+ */
+export declare function paint(id: string, background: string, extra?: string, size?: string): string;
+/**
+ * An animation that never stops, on `target` inside the text: paused while the text is off screen once the script runs
+ * (`needs.loop` sets `data-sx-text-on`), so a page without scripts still shows it.
+ */
+export declare function loop(id: string, target: string, animation: string): string;
+/**
+ * What `target` looks like while the text, or a link or button around it, is hovered or focused from the keyboard.
+ * `:hover` sits inside the media query, so a tap never leaves it stuck on a phone.
+ */
+export declare function whenOn(id: string, target: string, body: string): string;
+export interface ScrubRule {
+    /** The element that moves, as a raw selector inside the host. Default the pieces (`UNIT`). */
+    readonly target?: string;
+    /** Its declarations at progress `q` (a CSS expression, 0 to 1). The rule calls it with `0`, `1`, and a `calc()`. */
+    readonly pose: (q: string) => string;
+    /** Where on the timeline it plays, in % (cover: 0 = its top meets the screen's bottom; contain: the pinned stretch). */
+    readonly range: readonly [number, number];
+    /** Each piece's share of the range, 0-1: 1 plays them all together; smaller staggers them by `--sx-o`. Default 1. */
+    readonly share?: number;
+    /** `cover` (default) or `contain`, for a text taller than the screen that pins. */
+    readonly timeline?: "cover" | "contain";
+    /** The keyframes' name after `sx-text-<id>-`, when an effect has several. */
+    readonly name?: string;
+}
+/**
+ * A pose tied to the scroll. Two paths from one `pose`:
+ * - native: keyframes from `pose(0)` to `pose(1)` on the text's own view timeline (`--sx-text-view`, which the base sheet
+ *   declares on a text with a scroll effect), each piece its own slice of the range;
+ * - fallback (`data-sx-scroll="js"`): `pose(q)` with `q` computed from `--sx-p` / `--sx-pc`, which `attachScrub` writes.
+ */
+export declare function scrub(id: string, rule: ScrubRule): string;
+export interface TextParts {
+    readonly vars?: TextVars;
+    readonly layers?: readonly TextLayer[];
+    readonly claims?: readonly TextClaim[];
+    readonly needs?: TextNeeds;
+    /** Its look, shipped always (a fill, an outline). The motion goes in the main rules. */
+    readonly look?: string;
+    readonly program?: TextProgram;
+    /** The weakest device that runs it, as in the registry (tested). Default `"all"`. */
+    readonly tier?: TextTier;
+    /** What a device below `tier` wears instead. Required for a `mid` / `high` effect (tested). */
+    readonly fallback?: TextEffect;
+}
+/** A text effect from its registry id, its rules and its parts. Rules go in `@layer components`. */
+export declare function defineText(id: string, css: string, parts?: TextParts): TextEffect;

package/dist/text/effects/kit.js

@@ -0,0 +1,144 @@
+// Helpers for text effects: selectors keyed on `data-sx-text`, the entrance rules, defineText(). Pure strings; no React,
+// no DOM.
+/** An effect's option as a custom property: `--sx-text-enterRise-time`. */
+export const varName = (id, name) => `--sx-text-${id}-${name}`;
+/** Read it. */
+export const v = (id, name) => `var(${varName(id, name)})`;
+/** 1, or -1 in a right-to-left context. Physical values multiply by it. */
+export const DIR = "var(--sx-text-dir)";
+/** The reading start and end as a `transform-origin` x. */
+export const START_X = `calc(50% - 50% * ${DIR})`;
+export const END_X = `calc(50% + 50% * ${DIR})`;
+/** The text element wearing this effect, as a raw selector. */
+export const hostOf = (id) => `[data-sx-text~="${id}"]`;
+/** The pieces an entrance moves (letters, words, lines, or the whole text), as a raw selector inside the host. */
+export const UNIT = "[data-sx-text-unit]";
+/** What shows: the pieces, or the plain text when nothing is cut. */
+export const SHOW = "[data-sx-text-show]";
+/** The bar inside each piece (`needs.cover`). */
+export const COVER = `${UNIT} > [data-sx-text-cover]`;
+/** An effect's layer. */
+export const layerOf = (id, part) => part ? `[data-sx-text-layer="${id}"][data-sx-text-part="${part}"]` : `[data-sx-text-layer="${id}"]`;
+/** Wrap a raw selector. */
+export const at = (raw) => `:where(${raw})`;
+/** The easing most entrances use. */
+export const EASE = "var(--ease-sx-out, cubic-bezier(0.2, 0.7, 0.2, 1))";
+/** A springy curve that overshoots and settles. */
+export const SPRING = "linear(0, 0.45 12%, 0.85 25%, 1.08 38%, 1.1 46%, 1.03 62%, 0.99 78%, 1)";
+/** Seconds as CSS, rounded so a stagger's float sums don't leak 0.15000000000000002 into the markup. */
+export const seconds = (n) => `${Number(n.toFixed(3))}s`;
+/** How long a page waits for the script before a waiting entrance plays on its own (atlas rule 7). */
+export const FAIL_SAFE = "3s";
+/**
+ * An entrance: the waiting pose, then the keyframes, each piece `--sx-o` staggers later. Three states, all inside
+ * `@media (scripting: enabled)`, so a page without scripts shows the text as it is:
+ * - before the script runs: the entrance plays on its own after `FAIL_SAFE`, so text is never stuck hidden;
+ * - the script runs (`data-sx-text-live`), not in view yet: the waiting pose holds;
+ * - in view (`data-sx-in`): it plays. `data-sx-text-done` (lines measured again after it played) stops it at rest.
+ */
+export function enter(id, rule) {
+    const name = `sx-text-${id}${rule.name ? `-${rule.name}` : ""}`;
+    const target = rule.target ?? UNIT;
+    const host = `${hostOf(id)}${rule.when ?? ""}`;
+    const ease = rule.ease ?? EASE;
+    const delay = `calc(${v(id, "delay")} + var(--sx-o, 0) * ${v(id, "stagger")})`;
+    const play = `${name} ${v(id, "time")} ${ease}`;
+    return `  @keyframes ${name} { ${rule.frames ?? `from { ${rule.from} }`} }
+  @keyframes ${name}-wait { from { ${rule.from} } to { ${rule.from} } }
+  @media (scripting: enabled) {
+    ${at(`${host}:not([data-sx-text-live], [data-sx-in]) ${target}`)} { animation: ${play} calc(${FAIL_SAFE} + ${delay}) both; }
+    ${at(`${host}[data-sx-text-live]:not([data-sx-in]) ${target}`)} { animation: ${name}-wait 1s both; }
+    ${at(`${host}[data-sx-in]:not([data-sx-text-done]) ${target}`)} { animation: ${play} ${delay} both; }
+  }`;
+}
+/** Rules that matter only while an entrance can play (a bar over each word): inside `@media (scripting: enabled)`. */
+export const scripted = (rules) => `  @media (scripting: enabled) {\n${rules}\n  }`;
+/** What a paint effect fills: the span around the text, or around each piece's text (`needs.paint`). */
+export const PAINT = "[data-sx-text-paint]";
+/** A part inside an effect's layer. */
+export const partOf = (id, part, layerPart) => `${layerOf(id, layerPart)} [data-sx-text-part="${part}"]`;
+/** Where each paint span sits in the whole text, as a `background-position`: one fill runs across pieces that move. */
+export const PAINT_AT = "calc(var(--sx-tx, 0px) * -1) calc(var(--sx-ty, 0px) * -1)";
+/** The whole text's size, as a `background-size`. */
+export const PAINT_SIZE = "var(--sx-tw, 100%) var(--sx-th, 100%)";
+/**
+ * Hides the letters' own fill with `-webkit-text-fill-color`, never `color: transparent`: that would also turn every
+ * `currentColor` in the fill, and in an outline, transparent.
+ *
+ * Fills the letters with `background` (one image or a list), sized and placed on the whole text so it stays seamless
+ * however the text is cut. `size` replaces the size list for an effect with several images.
+ */
+export function paint(id, background, extra = "", size = PAINT_SIZE) {
+    return `  ${at(`${hostOf(id)} ${PAINT}`)} {
+    background: ${background};
+    background-size: ${size};
+    background-position: ${PAINT_AT};
+    -webkit-background-clip: text;
+    background-clip: text;
+    -webkit-text-fill-color: transparent;${extra ? `\n    ${extra}` : ""}
+  }`;
+}
+/**
+ * An animation that never stops, on `target` inside the text: paused while the text is off screen once the script runs
+ * (`needs.loop` sets `data-sx-text-on`), so a page without scripts still shows it.
+ */
+export function loop(id, target, animation) {
+    return `  ${at(`${hostOf(id)} ${target}`)} { animation: ${animation}; }
+  ${at(`${hostOf(id)}[data-sx-text-live]:not([data-sx-text-on]) ${target}`)} { animation-play-state: paused; }`;
+}
+/**
+ * What `target` looks like while the text, or a link or button around it, is hovered or focused from the keyboard.
+ * `:hover` sits inside the media query, so a tap never leaves it stuck on a phone.
+ */
+export function whenOn(id, target, body) {
+    const host = hostOf(id);
+    const hover = `${host}:hover ${target}, :is(a, button, label):hover ${host} ${target}`;
+    const focus = `:is(a, button, [tabindex]):focus-visible ${host} ${target}, ${host}:focus-visible ${target}`;
+    return `  @media (hover: hover) and (pointer: fine) {
+    ${at(hover)} { ${body} }
+  }
+  ${at(focus)} { ${body} }`;
+}
+/**
+ * A pose tied to the scroll. Two paths from one `pose`:
+ * - native: keyframes from `pose(0)` to `pose(1)` on the text's own view timeline (`--sx-text-view`, which the base sheet
+ *   declares on a text with a scroll effect), each piece its own slice of the range;
+ * - fallback (`data-sx-scroll="js"`): `pose(q)` with `q` computed from `--sx-p` / `--sx-pc`, which `attachScrub` writes.
+ */
+export function scrub(id, rule) {
+    const name = `sx-text-${id}${rule.name ? `-${rule.name}` : ""}`;
+    const target = rule.target ?? UNIT;
+    const host = hostOf(id);
+    const [r0, r1] = rule.range;
+    const share = rule.share ?? 1;
+    const kind = rule.timeline ?? "cover";
+    // this piece's slice, in %: start a, end b
+    const a = share >= 1 ? `${r0}` : `(${r0} + ${r1 - r0} * var(--sx-o, 0) / max(var(--sx-n, 1) - 1, 1) * ${1 - share})`;
+    const b = share >= 1 ? `${r1}` : `(${a} + ${(r1 - r0) * share})`;
+    const p = kind === "contain" ? "var(--sx-pc, 0)" : "var(--sx-p, 0)";
+    const q = `clamp(0, (${p} * 100 - ${a}) / (${b} - ${a}), 1)`;
+    return `  @keyframes ${name} { from { ${rule.pose("0")} } to { ${rule.pose("1")} } }
+  @supports (animation-timeline: view()) {
+    ${at(`${host}:not([data-sx-scroll="js"]) ${target}`)} {
+      animation: ${name} auto linear both;
+      animation-timeline: --sx-text-view;
+      animation-range: ${kind} calc(${a} * 1%) ${kind} calc(${b} * 1%);
+    }
+  }
+  ${at(`${host}[data-sx-scroll="js"] ${target}`)} { ${rule.pose(q)} }`;
+}
+/** A text effect from its registry id, its rules and its parts. Rules go in `@layer components`. */
+export function defineText(id, css, parts = {}) {
+    return {
+        id,
+        tier: parts.tier ?? "all",
+        css: css ? `@layer components {\n${css}\n}` : "",
+        ...(parts.look ? { lookCss: `@layer components {\n${parts.look}\n}` } : {}),
+        vars: parts.vars ?? {},
+        layers: parts.layers ?? [],
+        claims: parts.claims ?? [],
+        needs: parts.needs ?? {},
+        ...(parts.program ? { program: parts.program } : {}),
+        ...(parts.fallback ? { fallback: parts.fallback } : {}),
+    };
+}

package/dist/text/effects/pointer/hit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sets `data-sx-text-hit` on each letter (or word, where letters are not cut) the mouse passes over, and takes it away
+ * when that piece's `animation` (the keyframes' name) ends, so the next pass plays it again. A piece already playing is left alone. Nothing
+ * attaches without a mouse or under reduced motion. Returns what stops it.
+ */
+export declare function attachHit(el: HTMLElement, animation: string): () => void;

package/dist/text/effects/pointer/hit.js

@@ -0,0 +1,34 @@
+// Marks the letter the mouse touches so its animation plays to the end, even after the mouse has moved on: a plain
+// :hover would cut it off the moment the pointer leaves the letter. Browser only; attached by the effect's program.
+import { mayFollow } from "./kit.js";
+/**
+ * Sets `data-sx-text-hit` on each letter (or word, where letters are not cut) the mouse passes over, and takes it away
+ * when that piece's `animation` (the keyframes' name) ends, so the next pass plays it again. A piece already playing is left alone. Nothing
+ * attaches without a mouse or under reduced motion. Returns what stops it.
+ */
+export function attachHit(el, animation) {
+    if (!mayFollow())
+        return () => { };
+    // every animation inside the text bubbles here (an entrance ending on a letter): only the effect's own ends a hit
+    const done = (e) => {
+        if (e.animationName === animation && e.target instanceof Element)
+            e.target.removeAttribute("data-sx-text-hit");
+    };
+    const onOver = (e) => {
+        const target = e.target instanceof Element ? e.target : null;
+        const piece = target?.closest("[data-sx-text-char], [data-sx-text-word]");
+        // the gap between two letters belongs to their word: that is no letter to wobble
+        if (!piece || !el.contains(piece) || (piece.hasAttribute("data-sx-text-word") && piece.querySelector("[data-sx-text-char]")))
+            return;
+        if (!piece.hasAttribute("data-sx-text-hit"))
+            piece.setAttribute("data-sx-text-hit", "");
+    };
+    el.addEventListener("pointerover", onOver, { passive: true });
+    el.addEventListener("animationend", done);
+    return () => {
+        el.removeEventListener("pointerover", onOver);
+        el.removeEventListener("animationend", done);
+        for (const p of el.querySelectorAll("[data-sx-text-hit]"))
+            p.removeAttribute("data-sx-text-hit");
+    };
+}

package/dist/text/effects/pointer/kit.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The piece a hover effect moves, as a raw selector inside the host: each letter, or each whole word where letters are
+ * not cut (Arabic and the other joined scripts move by the word, never by the letter).
+ */
+export declare const LETTER = ":is([data-sx-text-char], [data-sx-text-word]:not(:has([data-sx-text-char])))";
+/** The piece's place in the text: its letter index, or its word index where letters are not cut. */
+export declare const LETTER_I = "var(--sx-i, var(--sx-wi, 0))";
+/** Where a mouse is: hover effects run there only, so a tap never leaves one stuck on a phone. */
+export declare const MOUSE = "(hover: hover) and (pointer: fine)";
+/** The pieces of `el` a pointer program works on: its letters, or its words where letters are not cut. */
+export declare function piecesOf(el: HTMLElement): HTMLElement[];
+/** There is a mouse, and the reader welcomes motion: a pointer program attaches only then. */
+export declare function mayFollow(): boolean;
+/** Rounded for an inline custom property: no float noise in the markup, and an unchanged value is skipped. */
+export declare const round3: (n: number) => string;