@candor-ui/react 2.1.0 → 2.3.0

package/dist/lib/motion.js

@@ -0,0 +1,350 @@
+import * as React from "react";
+/** The CSS each easing name stands for, as a brand file writes it. */
+export const motionEases = {
+    standard: "var(--cd-ease)",
+    inout: "var(--cd-ease-inout)",
+    spring: "var(--cd-ease-spring)",
+    linear: "linear",
+};
+/** The family defaults. Durations, easings and amplitudes are 2.2's, so an app with no brand file looks the same. */
+export const motionFamilies = {
+    reveal: {
+        reports: "Content opened or closed to its measured size; a chevron turns.",
+        spatial: true,
+        essential: false,
+        dur: { default: 200, min: 150, max: 300 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard", "inout"],
+        amp: null,
+        variants: ["size", "fade"],
+        calm: "Snaps to its measured size.",
+    },
+    arrive: {
+        reports: "Something new, added after the first draw.",
+        spatial: true,
+        essential: false,
+        dur: { default: 240, min: 150, max: 300 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard", "spring"],
+        amp: { name: "distance", default: "8px", min: 0, max: 16, unit: "px", subtle: 0.5 },
+        variants: ["rise", "fade", "pop"],
+        calm: "Fades in, up to 150 ms.",
+    },
+    pop: {
+        reports: "Added, removed, or a small mark appearing.",
+        spatial: true,
+        essential: false,
+        dur: { default: 200, min: 100, max: 300 },
+        outDur: { default: 120, min: 80, max: 300 },
+        ease: "standard",
+        eases: ["standard", "spring"],
+        amp: { name: "scale", default: "0.85", min: 0.8, max: 1, unit: "", subtle: 0 },
+        variants: ["scale", "fade"],
+        calm: "Fades, up to 150 ms.",
+    },
+    mark: {
+        reports: "A tick or cross drawn when a result settles.",
+        spatial: true,
+        essential: false,
+        dur: { default: 360, min: 200, max: 500 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard"],
+        amp: null,
+        variants: ["draw", "pop", "drop"],
+        calm: "The finished mark fades in, up to 150 ms.",
+    },
+    fill: {
+        reports: "A bar or ring moving between measured values.",
+        spatial: true,
+        essential: false,
+        dur: { default: 360, min: 200, max: 600 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard", "inout"],
+        amp: null,
+        variants: ["grow"],
+        calm: "Snaps to the new value; its colour may fade.",
+    },
+    value: {
+        reports: "A number or word changed in place.",
+        spatial: false,
+        essential: false,
+        dur: { default: 120, min: 80, max: 200 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard"],
+        amp: { name: "distance", default: "2px", min: 0, max: 4, unit: "px", subtle: 0 },
+        variants: ["fade", "slide"],
+        calm: "Crossfades, up to 150 ms.",
+    },
+    move: {
+        reports: "A thing changed place: a reorder, a tab indicator, a toast restacking, a scroll.",
+        spatial: true,
+        essential: false,
+        dur: { default: 200, min: 150, max: 300 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard", "spring"],
+        amp: null,
+        variants: ["slide"],
+        calm: "Jumps to its new place.",
+    },
+    overlay: {
+        reports: "A dialog, sheet, popover, menu or tooltip opened or closed.",
+        spatial: true,
+        essential: false,
+        dur: { default: 150, min: 100, max: 500 },
+        outDur: { default: 150, min: 80, max: 300 },
+        ease: "standard",
+        eases: ["standard", "inout", "spring"],
+        amp: { name: "scale", default: "0.95", min: 0.9, max: 1, unit: "", subtle: 1 },
+        variants: ["scale", "slide", "fade"],
+        calm: "Fades, up to 150 ms.",
+    },
+    press: {
+        reports: "A press registered.",
+        spatial: true,
+        essential: false,
+        dur: { default: 150, min: 80, max: 200 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard"],
+        amp: { name: "scale", default: "0.96", min: 0.9, max: 1, unit: "", subtle: 0.5 },
+        variants: ["scale"],
+        calm: "Doesn't scale; the colour still answers.",
+    },
+    tint: {
+        reports: "Hover, focus, selected, a drop target: a colour or opacity change.",
+        spatial: false,
+        essential: false,
+        dur: { default: 150, min: 0, max: 200 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard", "inout"],
+        amp: null,
+        variants: ["fade"],
+        calm: "Colour and opacity only, up to 150 ms.",
+    },
+    refuse: {
+        reports: "A locked control was pressed: the reason is shown, and under expressive it shakes.",
+        spatial: true,
+        essential: false,
+        dur: { default: 360, min: 200, max: 500 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard"],
+        amp: { name: "distance", default: "3px", min: 0, max: 6, unit: "px", subtle: 0 },
+        variants: ["shake"],
+        calm: "No shake; the reason's colour still changes.",
+    },
+    attention: {
+        reports: "Something new waits on the person: a ring that grows and fades.",
+        spatial: false,
+        essential: false,
+        dur: { default: 900, min: 600, max: 1600 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard"],
+        amp: { name: "count", default: "1", min: 1, max: 3, unit: "", subtle: 1 },
+        variants: ["ring"],
+        calm: "One ring that fades without growing, up to 150 ms.",
+    },
+    live: {
+        reports: "Work that is being heard from: a dot's pulse, a caret, a spinner, a shimmer, a skeleton.",
+        spatial: false,
+        essential: false,
+        dur: { default: 1600, min: 1000, max: 3000 },
+        outDur: null,
+        ease: "standard",
+        eases: ["standard", "inout", "linear"],
+        amp: null,
+        variants: ["pulse"],
+        calm: "Still, with its word.",
+    },
+    clock: {
+        reports: "Real time passing: a hold, a deadline, a replay. Painted from the clock.",
+        spatial: true,
+        essential: true,
+        dur: null,
+        outDur: null,
+        ease: "linear",
+        eases: ["linear"],
+        amp: null,
+        variants: ["glide"],
+        calm: "Steps instead of gliding; never off.",
+    },
+};
+/** The family names, in the order the docs and the theme builder list them. */
+export const motionFamilyNames = Object.keys(motionFamilies);
+/**
+ * The CSS value a variant is written as. CSS can only choose a drawing by keyframe name, so a variant's value is its
+ * keyframe's: the word with Candor's prefix, which keeps an app's own `@keyframes rise` from taking over.
+ */
+export const motionVariantValue = (variant) => `cd-${variant}`;
+const momentKey = Symbol.for("candor.motion.moment");
+const ms = (n) => `${n}ms`;
+/**
+ * Builds a moment's chain. Call it once at module level and spread the result into the element's `style`, beside the
+ * family utility that the component adds at the honest moment:
+ *
+ * ```tsx
+ * const tick = motion("copy-field", "tick", "pop")
+ * <Check style={tick} className={cn(copied && "cd-pop")} />
+ * ```
+ *
+ * The brand reaches the moment with `--cd-motion-copy-field-tick` (its level), `-dur`, `-ease`, the family's amplitude
+ * suffix and `-variant`; anything it doesn't set falls back to the family (`--cd-motion-pop-*`), then to `defaults`,
+ * then to Candor's. Two families on one element compose: `style={{ ...press, ...tint }}`.
+ */
+export function motion(item, moment, family, defaults = {}) {
+    const spec = motionFamilies[family];
+    const own = `--cd-motion-${item}-${moment}`;
+    const fam = `--cd-motion-${family}`;
+    const local = `--cd-m-${family}`;
+    const style = {
+        [local]: `var(${own}, var(${fam}, var(--cd-motion-preset)))`,
+    };
+    if (spec.dur)
+        style[`${local}-dur`] = `var(${own}-dur, var(${fam}-dur, ${ms(defaults.dur ?? spec.dur.default)}))`;
+    if (spec.outDur)
+        style[`${local}-out-dur`] = `var(${own}-out-dur, var(${fam}-out-dur, ${ms(defaults.outDur ?? spec.outDur.default)}))`;
+    if (spec.dur)
+        style[`${local}-ease`] = `var(${own}-ease, var(${fam}-ease, ${motionEases[defaults.ease ?? spec.ease]}))`;
+    if (spec.amp)
+        style[`${local}-amp`] = `var(${own}-${spec.amp.name}, var(${fam}-${spec.amp.name}, ${defaults.amp ?? spec.amp.default}))`;
+    if (spec.variants.length > 1) {
+        const variant = motionVariantValue(defaults.variant ?? spec.variants[0]);
+        style[`${local}-variant`] = `var(${own}-variant, var(${fam}-variant, ${variant}))`;
+    }
+    Object.defineProperty(style, momentKey, { value: { item, moment, family }, enumerable: false });
+    return style;
+}
+/** The moment a chain was built for, or `undefined` for a plain style object. */
+export const motionMomentOf = (style) => style?.[momentKey];
+/* ---------------------------------------------------------------- mount still */
+const isFinished = (status) => status === "succeeded" || status === "failed";
+const isOver = (status) => isFinished(status) || status === "cancelled" || status === "skipped";
+const runTest = { settled: isFinished, over: isOver };
+export function useSettled(value, test) {
+    const { settled: done, over = done } = (test ?? runTest);
+    const [settled, setSettled] = React.useState(0);
+    const previous = React.useRef(value);
+    React.useLayoutEffect(() => {
+        const was = previous.current;
+        previous.current = value;
+        if (was !== value && !over(was) && done(value))
+            setSettled((n) => n + 1);
+    }, [value, done, over]);
+    return settled;
+}
+/**
+ * Which keys were added after the component first drew. Keys present at the first render answer false, so a list
+ * that loads with fifty entries draws them still; a key added later answers true until it leaves (and true again if
+ * it comes back).
+ */
+export function useArrived(keys) {
+    const [arrived, setArrived] = React.useState(() => new Set());
+    const previous = React.useRef(null);
+    React.useLayoutEffect(() => {
+        const before = previous.current;
+        previous.current = keys;
+        if (!before)
+            return;
+        const was = new Set(before);
+        const now = new Set(keys);
+        const added = keys.filter((key) => !was.has(key));
+        const gone = before.filter((key) => !now.has(key));
+        if (!added.length && !gone.length)
+            return;
+        setArrived((set) => {
+            const next = new Set(set);
+            for (const key of gone)
+                next.delete(key);
+            for (const key of added)
+                next.add(key);
+            return next;
+        });
+    }, [keys]);
+    return React.useCallback((key) => arrived.has(key), [arrived]);
+}
+/**
+ * Items that just left, kept as inert ghosts for the length of their out moment. Each ghost goes when `left(item)` is
+ * called (from its `onAnimationEnd`), or after `fallbackMs` when nothing animated. An item that comes back while its
+ * ghost is still leaving takes the ghost's place.
+ */
+export function useLeaving(items, keyOf, fallbackMs = 400) {
+    const [leaving, setLeaving] = React.useState([]);
+    const previous = React.useRef(null);
+    React.useLayoutEffect(() => {
+        const before = previous.current;
+        previous.current = items;
+        if (!before)
+            return;
+        const now = new Set(items.map(keyOf));
+        const gone = before.filter((item) => !now.has(keyOf(item)));
+        setLeaving((list) => {
+            const kept = list.filter((item) => !now.has(keyOf(item)));
+            return kept.length === list.length && gone.length === 0 ? list : [...kept, ...gone];
+        });
+    }, [items, keyOf]);
+    React.useEffect(() => {
+        if (leaving.length === 0)
+            return;
+        const timer = window.setTimeout(() => setLeaving([]), fallbackMs);
+        return () => window.clearTimeout(timer);
+    }, [leaving, fallbackMs]);
+    const left = React.useCallback((item) => setLeaving((list) => list.filter((x) => x !== item)), []);
+    return { leaving, left };
+}
+/**
+ * The person's setting where `el` is: `none` under `data-motion="none"`, `calm` under the OS's reduced-motion setting
+ * or `data-motion="calm"`, else `full`. `none` or `calm` anywhere above wins (the same reach as the CSS variants), the
+ * OS setting can't be raised by the app, and values that aren't Candor's (Radix writes its own `data-motion` on menu
+ * panels) are ignored.
+ */
+export function motionMode(el) {
+    if (el?.closest('[data-motion="none"]'))
+        return "none";
+    if (typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches)
+        return "calm";
+    if (el?.closest('[data-motion="calm"]'))
+        return "calm";
+    return "full";
+}
+const number = (value) => {
+    const n = Number.parseFloat(value);
+    return Number.isFinite(n) ? n : undefined;
+};
+/**
+ * The level a moment resolves to on `el`, read from its computed style: the moment's token, its family's, the preset,
+ * then capped by `data-motion`. A page without Candor's CSS reads as subtle.
+ */
+export function motionLevel(el, moment) {
+    if (!el || typeof getComputedStyle === "undefined")
+        return 1;
+    const style = getComputedStyle(el);
+    const read = (name) => number(style.getPropertyValue(name));
+    const { item, moment: name, family } = typeof moment === "string" ? { item: undefined, moment: undefined, family: moment } : moment;
+    const level = (item ? read(`--cd-motion-${item}-${name}`) : undefined) ?? read(`--cd-motion-${family}`) ?? read("--cd-motion-preset") ?? 1;
+    const cap = read("--cd-motion-cap") ?? 2;
+    const resolved = Math.max(0, Math.min(2, Math.round(Math.min(level, cap))));
+    return (motionFamilies[family].essential ? Math.max(1, resolved) : resolved);
+}
+/**
+ * For motion that CSS can't stop (smooth scrolling, the Web Animations API, a bar painted from the clock): a stable
+ * function that answers, at the moment of the motion, whether it may play on `ref`'s element. False under
+ * `data-motion="none"`, under the calm level (reduced motion), and when the moment's resolved level is 0. Pass the
+ * moment's chain from `motion()`, or a family name for the family's level.
+ */
+export function useMotionAllowed(ref, moment) {
+    const target = typeof moment === "string" ? moment : motionMomentOf(moment);
+    return React.useCallback(() => {
+        const el = ref.current;
+        if (motionMode(el) !== "full")
+            return false;
+        return target ? motionLevel(el, target) > 0 : true;
+    }, [ref, target]);
+}