@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/sections/shared/context.js

@@ -0,0 +1,57 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useId, useMemo, useRef } from "react";
+import { partAttrs, sectionRootAttrs } from "./attrs.js";
+import { resolveReveal, SECTION_REVEAL_CSS } from "./reveal.js";
+import { fadeUp } from "../../transitions/effects/css/reveals.js";
+import { TransitionStyle, useTransition } from "../../transitions/hosts/shared.js";
+import { useInView } from "../../transitions/reveal/Reveal.js";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+const DEFAULT_REVEAL = fadeUp();
+/**
+ * One context per section type, so `<About.Title>` can never read a Hero's
+ * content. `name` only feeds the error message.
+ */
+export function createSectionContext(name) {
+    const Context = createContext(null);
+    function useSection(part) {
+        const value = useContext(Context);
+        if (!value) {
+            throw new Error(`[@sharedex/ui] <${name}.${part}> must be rendered inside <${name}.Root>.`);
+        }
+        return value;
+    }
+    function Provider({ layout, content, reveal: revealOption, unstyled = false, actionEffect, titleEffect, eyebrowEffect, titleCycle, statRoll, children, }) {
+        const titleId = useId();
+        const reveal = useShellReveal(revealOption);
+        const value = useMemo(() => ({ layout, content, titleId, reveal, unstyled, actionEffect, titleEffect, eyebrowEffect, titleCycle, statRoll }), [layout, content, titleId, reveal, unstyled, actionEffect, titleEffect, eyebrowEffect, titleCycle, statRoll]);
+        return _jsx(Context.Provider, { value: value, children: children(titleId, reveal) });
+    }
+    return { Provider, useSection };
+}
+/** The `reveal` prop as the shell and the parts use it, with the device's pick of the transition. */
+function useShellReveal(option) {
+    const resolved = resolveReveal(option);
+    const transition = useTransition(resolved ? (resolved.effect ?? DEFAULT_REVEAL) : undefined);
+    const key = resolved && JSON.stringify([resolved.stagger, resolved.delay, resolved.duration, resolved.once, resolved.threshold]);
+    return useMemo(() => {
+        if (!resolved || !transition)
+            return null;
+        const { stagger, delay, duration, once, threshold } = resolved;
+        return { transition, stagger, delay, duration, once, threshold };
+        // the resolved timing by value: an inline `reveal={{ stagger: 0.2 }}` is a new object every render
+    }, [transition, key]);
+}
+/**
+ * The `<section>` every section renders, plus the inner box that holds its
+ * layout grid. Container queries measure the `<section>`, so layouts respond
+ * to the space they get, not to the viewport. `background` (usually a
+ * `<Background.Root>`) is rendered first; the section is its stacking context
+ * (`isolation: isolate`), so it paints above the section colour and below
+ * the content, with no z-index on the content.
+ */
+export function SectionShell({ section, layout, unstyled, titleId, className, background, reveal = null, children, }) {
+    const inner = useRef(null);
+    useInView(inner, "data-sx-in", reveal?.once ?? true, reveal?.threshold ?? 0, reveal !== null);
+    return (_jsxs("section", { ...sectionRootAttrs({ section, layout, unstyled }), "aria-labelledby": titleId, className: className, children: [background, _jsxs("div", { ref: inner, ...partAttrs(section, "inner"), children: [reveal ? (_jsxs(_Fragment, { children: [_jsx(TransitionStyle, { transition: reveal.transition }), _jsx("style", { href: styleHref("section-reveal", SECTION_REVEAL_CSS), precedence: "sx", children: SECTION_REVEAL_CSS })] })) : null, children] })] }));
+}

package/dist/sections/shared/reveal.d.ts

@@ -0,0 +1,55 @@
+import type { CSSProperties } from "react";
+import type { CssTransition } from "../../transitions/types.js";
+export interface SectionReveal {
+    /** The transition each part plays. Default `fadeUp()`. Generated nodes (pixelGrid, slicer …) are not rendered. */
+    readonly effect?: CssTransition;
+    /** Seconds between one part and the next. Default `0.12`. */
+    readonly stagger?: number;
+    /** Seconds before the first part starts. Default `0`. */
+    readonly delay?: number;
+    /** Seconds each part takes. Default: the transition's own (`0.9`). */
+    readonly duration?: number;
+    /** Play once (default) or every time the section comes back into view. */
+    readonly once?: boolean;
+    /** How much of the section must be on screen before it plays, 0–1. Default `0.15`. */
+    readonly threshold?: number;
+}
+/** `true` = `fadeUp()` with the defaults; a transition = that one with the defaults. */
+export type SectionRevealOption = boolean | CssTransition | SectionReveal;
+export interface ResolvedReveal {
+    readonly effect: CssTransition | undefined;
+    readonly stagger: number;
+    readonly delay: number;
+    readonly duration: number | undefined;
+    readonly once: boolean;
+    readonly threshold: number;
+}
+/** Null when the section does not reveal. `effect` undefined = the default (`fadeUp()`, filled in by the host). */
+export declare function resolveReveal(option: SectionRevealOption | undefined): ResolvedReveal | null;
+/** What a section hands its parts: the tier-picked transition and the timing. */
+export interface PartReveal {
+    readonly transition: CssTransition;
+    readonly stagger: number;
+    readonly delay: number;
+    readonly duration: number | undefined;
+}
+export interface RevealAttrs {
+    readonly "data-sx-tr"?: string;
+    readonly "data-sx-tr-mode"?: "reveal";
+    readonly "data-sx-sr"?: "";
+    readonly style?: CSSProperties;
+}
+/**
+ * The attributes a part spreads to play the reveal as the `order`-th part
+ * (0 = first). Nothing when the section does not reveal.
+ */
+export declare function revealAttrs(reveal: PartReveal | null, order: number): RevealAttrs;
+/**
+ * The reveals that fade their content, not their element (a carousel slot owns
+ * its element's opacity). A section part is often a box of its own (a Services
+ * card's border and background), which would sit there empty while its content
+ * faded in: for these the part fades as a whole.
+ */
+export declare const FADING_REVEALS: readonly ["fadeUp", "blurFade", "zoomOut"];
+/** Shows every revealing part once its section is in view (see the note at the top). */
+export declare const SECTION_REVEAL_CSS: string;

package/dist/sections/shared/reveal.js

@@ -0,0 +1,59 @@
+// A section's `reveal` prop: its main parts play a CSS transition one after
+// another when the section scrolls into view. Pure: no React, testable.
+//
+// The parts themselves play it (they are the layout's grid items, so a wrapper
+// would break the layout). The section's inner box is observed and gets
+// `data-sx-in`; every part that plays carries `data-sx-sr`, and the rule below
+// shows it once any ancestor is in. A descendant rule, not the base sheet's
+// child rule, so the Services cards (inside their list) play too.
+import { LAYER_ORDER } from "../../backgrounds/runtime/rootCss.js";
+const isTransition = (v) => typeof v === "object" && "kind" in v;
+/** Null when the section does not reveal. `effect` undefined = the default (`fadeUp()`, filled in by the host). */
+export function resolveReveal(option) {
+    if (!option)
+        return null;
+    const o = option === true ? {} : isTransition(option) ? { effect: option } : option;
+    return {
+        effect: o.effect,
+        stagger: o.stagger ?? 0.12,
+        delay: o.delay ?? 0,
+        duration: o.duration,
+        once: o.once ?? true,
+        threshold: o.threshold ?? 0.15,
+    };
+}
+const seconds = (n) => `${Number(n.toFixed(3))}s`;
+/**
+ * The attributes a part spreads to play the reveal as the `order`-th part
+ * (0 = first). Nothing when the section does not reveal.
+ */
+export function revealAttrs(reveal, order) {
+    if (!reveal)
+        return {};
+    const { transition, stagger, delay, duration } = reveal;
+    const style = { ...transition.vars, "--sx-tr-delay": seconds(delay + order * stagger) };
+    if (duration !== undefined)
+        style["--sx-tr-duration"] = seconds(duration);
+    return { "data-sx-tr": transition.id, "data-sx-tr-mode": "reveal", "data-sx-sr": "", style: style };
+}
+/**
+ * The reveals that fade their content, not their element (a carousel slot owns
+ * its element's opacity). A section part is often a box of its own (a Services
+ * card's border and background), which would sit there empty while its content
+ * faded in: for these the part fades as a whole.
+ */
+export const FADING_REVEALS = ["fadeUp", "blurFade", "zoomOut"];
+const fading = `[data-sx-sr]:is(${FADING_REVEALS.map((id) => `[data-sx-tr="${id}"]`).join(", ")})`;
+/** Shows every revealing part once its section is in view (see the note at the top). */
+export const SECTION_REVEAL_CSS = `${LAYER_ORDER}
+@layer components {
+  [data-sx-in] [data-sx-sr] {
+    --sx-p: 1;
+  }
+  ${fading} {
+    opacity: var(--sx-p);
+  }
+  ${fading} > * {
+    opacity: 1;
+  }
+}`;

package/dist/sections/shared/stat.d.ts

@@ -0,0 +1,18 @@
+export interface ParsedStat {
+    /** What sits before the number ("€", "~"). */
+    readonly prefix: string;
+    readonly value: number;
+    /** What follows it ("+", "%", "k+", "/5"). */
+    readonly suffix: string;
+    /** Picked so the number formats back to exactly how it was written. */
+    readonly locale: string;
+    readonly format: Intl.NumberFormatOptions;
+}
+/**
+ * `text` as a prefix, one number and a suffix, with the locale and format that write the number back exactly as it
+ * stands (`1,250` keeps its comma, `4,9` its decimal comma); `null` when it isn't one.
+ *
+ * A separator followed by exactly three digits groups thousands (`10,000`, `1.500`); otherwise it is the decimal point
+ * (`4.9`, `4,9`). When both kinds appear, the last one is the decimal point.
+ */
+export declare function parseStat(text: string): ParsedStat | null;

package/dist/sections/shared/stat.js

@@ -0,0 +1,47 @@
+// About's figures as numbers NumberRoll can roll to: "40+" is 40 with a "+" after it, "€1.2M" is 1.2 between "€" and
+// "M". Pure; tested. A figure that isn't one number written plainly ("24/7" is fine, "1 000" is not) stays text.
+import { formatNumber } from "../../text/number/format.js";
+// the number ends where the text stops being part of it: "1 000" and "1’000" group with a space or a quote, and stay text
+const FIGURE = /^(\D*?)(\d(?:[\d.,]*\d)?)(?![\s  '’]\d)(\D.*)?$/s;
+/**
+ * `text` as a prefix, one number and a suffix, with the locale and format that write the number back exactly as it
+ * stands (`1,250` keeps its comma, `4,9` its decimal comma); `null` when it isn't one.
+ *
+ * A separator followed by exactly three digits groups thousands (`10,000`, `1.500`); otherwise it is the decimal point
+ * (`4.9`, `4,9`). When both kinds appear, the last one is the decimal point.
+ */
+export function parseStat(text) {
+    const m = FIGURE.exec(text.trim());
+    if (!m)
+        return null;
+    const [, prefix = "", number = "", suffix = ""] = m;
+    const seps = [...number.matchAll(/[.,]/g)].map((s) => ({ char: s[0], at: s.index }));
+    let decimal;
+    let group;
+    if (seps.length > 0) {
+        const kinds = new Set(seps.map((s) => s.char));
+        const last = seps[seps.length - 1];
+        if (kinds.size > 1) {
+            decimal = last.char;
+            group = decimal === "." ? "," : ".";
+        }
+        else if (seps.length === 1 && number.length - last.at - 1 !== 3) {
+            decimal = last.char;
+        }
+        else {
+            group = last.char;
+        }
+    }
+    const plain = number.split(group ?? "\u0000").join("").replace(decimal ?? "\u0000", ".");
+    const value = Number(plain);
+    if (!Number.isFinite(value))
+        return null;
+    const decimals = decimal ? number.length - number.lastIndexOf(decimal) - 1 : 0;
+    // a decimal comma or a grouping point reads as German; everything else as US English
+    const locale = decimal === "," || group === "." ? "de-DE" : "en-US";
+    const format = { useGrouping: group !== undefined, minimumFractionDigits: decimals, maximumFractionDigits: decimals };
+    // only when it writes back exactly as it stands (a misplaced separator, "1,50,000", doesn't)
+    if (formatNumber(value, locale, format) !== number)
+        return null;
+    return { prefix, value, suffix, locale, format };
+}

package/dist/sections/shared/types.d.ts

@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+import type { ButtonEffect } from "../../buttons/types.js";
+import type { WordCycleProps } from "../../text/cycle/WordCycle.js";
+import type { NumberRollProps } from "../../text/number/NumberRoll.js";
+import type { TextEffect } from "../../text/types.js";
+/** A link rendered as a call to action. The first one in a list is the primary. */
+export interface SectionAction {
+    readonly label: string;
+    readonly href: string;
+}
+/** The button effects a section's primary action wears (`actionEffect`): one, or a list that stacks. */
+export type SectionActionEffect = ButtonEffect | readonly ButtonEffect[];
+/** The text effects a section's title or eyebrow wears (`titleEffect`, `eyebrowEffect`): one, or a list that stacks. */
+export type SectionTextEffect = TextEffect | readonly TextEffect[];
+/** How the Hero's cycling word changes (`titleCycle`): `WordCycle`'s props, without the words (they are content). */
+export type SectionTitleCycle = Omit<WordCycleProps, "words" | "as" | "className" | "style">;
+/**
+ * How About's figures roll (`statRoll`): `NumberRoll`'s props, without the value and its format (both are read from
+ * each stat's text: `"40+"` rolls to 40 and keeps its `+`).
+ */
+export type SectionStatRoll = Omit<NumberRollProps, "value" | "to" | "clock" | "format" | "locale" | "units" | "timeZone" | "as" | "className" | "style">;
+/**
+ * What fills a section's media slot. `node` is the escape hatch: any element,
+ * including a `<Carousel.Root>`.
+ */
+export type SectionMedia = {
+    readonly kind: "image";
+    readonly src: string;
+    readonly alt: string;
+} | {
+    readonly kind: "video";
+    readonly src: string;
+    /** Read out instead of the video. Required: a video has no alt text. */
+    readonly label: string;
+    readonly poster?: string;
+    /** Muted, looping, no controls. Off by default; only for decorative footage. */
+    readonly autoPlay?: boolean;
+} | {
+    readonly kind: "node";
+    readonly node: ReactNode;
+};
+/** Props every section part takes. `children` replaces the part's default content. */
+export interface SectionPartProps {
+    readonly className?: string;
+    readonly children?: ReactNode;
+}

package/dist/sections/shared/types.js

@@ -0,0 +1 @@
+export {};

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}";