@sharedex/ui 0.0.0-stage → 0.10.0

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;

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

@@ -0,0 +1,22 @@
+// What the pointer effects share: the piece that moves under the pointer, and the checks their programs make before
+// they attach anything. Selectors are pure strings; the functions below them run only in the browser.
+/**
+ * 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 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 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 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 function piecesOf(el) {
+    const chars = [...el.querySelectorAll("[data-sx-text-char]")];
+    return chars.length > 0 ? chars : [...el.querySelectorAll("[data-sx-text-word]")];
+}
+/** There is a mouse, and the reader welcomes motion: a pointer program attaches only then. */
+export function mayFollow() {
+    return window.matchMedia(MOUSE).matches && !window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+/** Rounded for an inline custom property: no float noise in the markup, and an unchanged value is skipped. */
+export const round3 = (n) => String(Math.round(n * 1000) / 1000);

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

@@ -0,0 +1,18 @@
+export interface NearRule {
+    /**
+     * `"radius"`: the distance in any direction, fading out at `reach` px. `"row"`: the distance along the line only,
+     * fading out at `reach` × the text's width (the whole line is in play, like pressing on it).
+     */
+    readonly shape: "radius" | "row";
+    readonly reach: number;
+    /** Also write which way the pointer is from each piece (`--sx-text-nx`, `--sx-text-ny`, -1 to 1): for a pull. */
+    readonly direction?: boolean;
+}
+/**
+ * Writes `--sx-text-near` (0 to 1) on each letter (or word, where letters are not cut) of `el`, at most once per frame,
+ * only while the mouse is over it. Sets `data-sx-text-follow` once attached (with `--sx-text-weight`, the text's own
+ * weight, so a weight effect starts from it) and `data-sx-text-near` while the mouse is over. Each centre is measured
+ * once, when the mouse arrives: a measure every frame would force a layout each time. Nothing attaches without a mouse
+ * or under reduced motion. Returns what stops it.
+ */
+export declare function attachNear(el: HTMLElement, rule: NearRule): () => void;

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

@@ -0,0 +1,89 @@
+// How near the pointer is to each letter, written as a number the effect's CSS turns into weight, width, size or pull.
+// Shared by pointerProximity and pointerPressure. Browser only; attached by their programs, never by Text.
+import { mayFollow, piecesOf, round3 } from "./kit.js";
+/** A smooth fall-off: 1 at the pointer, 0 at the edge of its reach, with no corner at either end. */
+const ease = (t) => t * t * (3 - 2 * t);
+/**
+ * Writes `--sx-text-near` (0 to 1) on each letter (or word, where letters are not cut) of `el`, at most once per frame,
+ * only while the mouse is over it. Sets `data-sx-text-follow` once attached (with `--sx-text-weight`, the text's own
+ * weight, so a weight effect starts from it) and `data-sx-text-near` while the mouse is over. Each centre is measured
+ * once, when the mouse arrives: a measure every frame would force a layout each time. Nothing attaches without a mouse
+ * or under reduced motion. Returns what stops it.
+ */
+export function attachNear(el, rule) {
+    if (!mayFollow())
+        return () => { };
+    el.setAttribute("data-sx-text-follow", "");
+    el.style.setProperty("--sx-text-weight", getComputedStyle(el).fontWeight);
+    let pieces = [];
+    let centres = [];
+    let written = [];
+    let width = 0;
+    let frame = 0;
+    let at;
+    const write = () => {
+        frame = 0;
+        if (!at)
+            return;
+        const box = el.getBoundingClientRect();
+        const px = at.x - box.left;
+        const py = at.y - box.top;
+        const reach = rule.shape === "row" ? Math.max(1, rule.reach * width) : Math.max(1, rule.reach);
+        pieces.forEach((piece, i) => {
+            const c = centres[i];
+            const dx = px - c.x;
+            const dy = py - c.y;
+            const d = rule.shape === "row" ? Math.abs(dx) : Math.hypot(dx, dy);
+            const near = round3(ease(Math.max(0, 1 - d / reach)));
+            if (written[i] === near)
+                return;
+            written[i] = near;
+            piece.style.setProperty("--sx-text-near", near);
+            if (rule.direction) {
+                const len = Math.hypot(dx, dy) || 1;
+                piece.style.setProperty("--sx-text-nx", round3(dx / len));
+                piece.style.setProperty("--sx-text-ny", round3(dy / len));
+            }
+        });
+    };
+    const onMove = (e) => {
+        at = { x: e.clientX, y: e.clientY };
+        if (!frame)
+            frame = requestAnimationFrame(write);
+    };
+    const onEnter = (e) => {
+        pieces = piecesOf(el);
+        const box = el.getBoundingClientRect();
+        width = box.width;
+        centres = pieces.map((p) => {
+            const r = p.getBoundingClientRect();
+            return { x: r.left + r.width / 2 - box.left, y: r.top + r.height / 2 - box.top };
+        });
+        written = [];
+        el.setAttribute("data-sx-text-near", "");
+        el.addEventListener("pointermove", onMove, { passive: true });
+        onMove(e);
+    };
+    const onLeave = () => {
+        el.removeEventListener("pointermove", onMove);
+        cancelAnimationFrame(frame);
+        frame = 0;
+        at = undefined;
+        el.removeAttribute("data-sx-text-near");
+        // back to rest: the effect's transition eases each piece home
+        for (const piece of pieces) {
+            piece.style.removeProperty("--sx-text-near");
+            piece.style.removeProperty("--sx-text-nx");
+            piece.style.removeProperty("--sx-text-ny");
+        }
+        written = [];
+    };
+    el.addEventListener("pointerenter", onEnter);
+    el.addEventListener("pointerleave", onLeave);
+    return () => {
+        onLeave();
+        el.removeEventListener("pointerenter", onEnter);
+        el.removeAttribute("data-sx-text-follow");
+        el.style.removeProperty("--sx-text-weight");
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { TextEffect } from "../../types.js";
+export interface PointerJelloOptions {
+    /** How far each letter squashes and stretches, 1 the default. */
+    readonly strength?: number;
+    /** Seconds one wobble takes. Default `0.8`. */
+    readonly duration?: number;
+}
+/**
+ * Each letter the mouse touches wobbles like jelly, and finishes its wobble after the mouse moves on. Mouse only: on a
+ * touch screen the text stays as it is. It carries code: the page needs `"use client"`.
+ */
+export declare function pointerJello(options?: PointerJelloOptions): TextEffect;

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

@@ -0,0 +1,30 @@
+import { at, defineText, hostOf, v, varName } from "../kit.js";
+import { attachHit } from "./hit.js";
+import { LETTER } from "./kit.js";
+const ID = "pointerJello";
+const S = v(ID, "strength");
+/** One squash or stretch, `k` of the way: x wider and y shorter for a positive `k`, the other way round for a negative. */
+const squash = (k) => `scale3d(calc(1 + ${k} * ${S}), calc(1 - ${k} * ${S}), 1)`;
+// A jelly wobble that dies away. It plays on a letter the program marks, and runs to its end after the mouse moves on.
+const CSS = `  @keyframes sx-text-${ID} {
+    30% { transform: ${squash(0.25)}; }
+    40% { transform: ${squash(-0.25)}; }
+    50% { transform: ${squash(0.15)}; }
+    65% { transform: ${squash(-0.05)}; }
+    75% { transform: ${squash(0.05)}; }
+    to { transform: none; }
+  }
+  ${at(`${hostOf(ID)} ${LETTER}[data-sx-text-hit]`)} { animation: sx-text-${ID} ${v(ID, "time")} ease-out; }`;
+/**
+ * Each letter the mouse touches wobbles like jelly, and finishes its wobble after the mouse moves on. Mouse only: on a
+ * touch screen the text stays as it is. It carries code: the page needs `"use client"`.
+ */
+export function pointerJello(options = {}) {
+    const program = { attach: (el) => attachHit(el, `sx-text-${ID}`), signature: ID };
+    return defineText(ID, CSS, {
+        vars: { [varName(ID, "strength")]: options.strength ?? 1, [varName(ID, "time")]: `${options.duration ?? 0.8}s` },
+        claims: ["move"],
+        needs: { split: "chars" },
+        program,
+    });
+}

package/dist/text/effects/pointer/pointerJello.schema.d.ts

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

package/dist/text/effects/pointer/pointerJello.schema.js

@@ -0,0 +1,10 @@
+import { defineSchema } from "../../../schema/define.js";
+export const POINTER_JELLO_SCHEMA = defineSchema()({
+    id: "pointerJello",
+    family: "text",
+    factory: "pointerJello",
+    fields: {
+        strength: { kind: "number", label: "Wobble", min: 0, max: 2, step: 0.1, default: 1 },
+        duration: { kind: "number", label: "Duration", min: 0.2, max: 2, step: 0.05, unit: "s", default: 0.8 },
+    },
+});

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

@@ -0,0 +1,14 @@
+import type { TextEffect } from "../../types.js";
+export interface PointerPressureOptions {
+    /** The letters' weight goes from light, far from the mouse, to heavy under it. Default `true`. */
+    readonly weight?: boolean;
+    /** Their width goes from narrow to wide the same way (a font with a width axis). Default `true`. */
+    readonly width?: boolean;
+    /** How far along the line the press spreads, as a share of the text's width. Default `0.35`. */
+    readonly reach?: number;
+}
+/**
+ * Letters swell heavier and wider where the mouse presses along the line, and thin out away from it (needs a variable
+ * font; best with one that has weight and width axes). Mouse only. It carries code: the page needs `"use client"`.
+ */
+export declare function pointerPressure(options?: PointerPressureOptions): TextEffect;