@candor-ui/react 2.2.0 → 2.4.0

package/dist/lib/motion.js

@@ -0,0 +1,380 @@
+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);
+/**
+ * True when a family has one way of drawing its change (fill, move, press, tint, refuse, attention, live and clock).
+ * Its single variant is fixed: there is no `-variant` token to set, and `motion()` writes none, because the family's
+ * utility has nothing to choose between. The docs mark such a family "(fixed)" instead of listing a value that does
+ * nothing. A later release that adds a second word turns the token on without a new name.
+ */
+export const motionVariantIsFixed = (family) => motionFamilies[family].variants.length < 2;
+/**
+ * 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 (!motionVariantIsFixed(family)) {
+        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. The default, 600 ms, is longer than
+ * the longest out moment a brand can set (pop's 300 ms at the slowest speed, 1.5×, is 450 ms). An item that comes back while its
+ * ghost is still leaving takes the ghost's place.
+ */
+export function useLeaving(items, keyOf, fallbackMs = 600) {
+    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";
+}
+/**
+ * `motionMode` for a component that has to react to it: the person's setting where `ref`'s element is, read after
+ * mount and again whenever the app changes `data-motion` or the OS setting changes. It starts as `full` for the first
+ * render, since there is nothing to read until the element exists. Use it for behaviour (a timer that must stop),
+ * not for styling, which the CSS variants already answer.
+ */
+export function useMotionMode(ref) {
+    const [mode, setMode] = React.useState("full");
+    React.useEffect(() => {
+        const read = () => setMode(motionMode(ref.current));
+        read();
+        const observer = new MutationObserver(read);
+        observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-motion"], subtree: true });
+        const query = window.matchMedia?.("(prefers-reduced-motion: reduce)");
+        query?.addEventListener("change", read);
+        return () => {
+            observer.disconnect();
+            query?.removeEventListener("change", read);
+        };
+    }, [ref]);
+    return mode;
+}
+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]);
+}

package/dist/lib/sound.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The names and the reading half of Candor's sound layer. A brand file names a sound per event
+ * (`--cd-sound-needs-you: "/sounds/needs-you.mp3"`); this file knows the five events, reads that token from the
+ * page's computed style, and holds the small arithmetic the Pro hooks share. It plays nothing: nothing is fetched
+ * until `useAttention` or `sound-setting` plays a sound, and a sound is always off until the person turns it on.
+ *
+ * Tokens, all optional, all read when a sound is about to play:
+ * - `--cd-sound-<event>`: a string, the path of an MP3 hosted by the app. No token, no sound, silently.
+ * - `--cd-sound-<event>-ogg`: a string, an Ogg/Opus alternative the browser may prefer.
+ * - `--cd-sound-volume`: 0 to 1, how loud every sound is. `--cd-sound-<event>-volume`: 0 to 1, scales that for one event.
+ *
+ * Safe to import on the server: the document is touched only inside `readSoundToken`.
+ */
+/** The five things the app may make a sound for. A closed list: `reply` and `silent` have no `AttentionKind` until 3.0. */
+export type SoundEvent = "needs-you" | "finished" | "failed" | "reply" | "silent";
+/** Every event, in the order the settings control lists them. */
+export declare const soundEvents: readonly SoundEvent[];
+/** The events a sound is offered for once the person turns sound on; `reply` and `silent` stay off until they pick them. */
+export declare const defaultSoundEvents: readonly SoundEvent[];
+/** A sound as the brand names it: where the file is, an optional Ogg alternative, and how loud (0 to 1). */
+export type SoundToken = {
+    src: string;
+    ogg?: string | undefined;
+    volume: number;
+};
+/** The longest a sound may be, in seconds. `theme check` measures what it can read. */
+export declare const maxSoundSeconds = 1.5;
+/** The least time between two plays of the same event, in milliseconds. A burst plays once. */
+export declare const soundCoalesceMs = 3000;
+/** A CSS custom property's value as the text it names: quotes removed, or the inside of `url(…)`. Empty when unset. */
+export declare function soundString(raw: string): string;
+/** How loud `event` is, 0 to 1: the global `--cd-sound-volume` times the event's own, each 1 when unset. 1 on the server. */
+export declare function readSoundVolume(event: SoundEvent, element?: Element | undefined): number;
+/**
+ * The brand's sound for `event`, read from the computed style of `element` (the document's root when left out), or
+ * `undefined` when the brand names none, or on the server.
+ */
+export declare function readSoundToken(event: SoundEvent, element?: Element | undefined): SoundToken | undefined;
+/**
+ * Whether a play at `now` is allowed, given when each event last played and when anything last played: the same event
+ * waits `soundCoalesceMs` after it played, and any sound in the same instant (a burst) is the one already playing.
+ * Pure; the caller keeps the clock.
+ */
+export declare function mayPlay(event: SoundEvent, last: Partial<Record<SoundEvent, number>>, now: number, burstMs?: number): boolean;

package/dist/lib/sound.js

@@ -0,0 +1,63 @@
+/**
+ * The names and the reading half of Candor's sound layer. A brand file names a sound per event
+ * (`--cd-sound-needs-you: "/sounds/needs-you.mp3"`); this file knows the five events, reads that token from the
+ * page's computed style, and holds the small arithmetic the Pro hooks share. It plays nothing: nothing is fetched
+ * until `useAttention` or `sound-setting` plays a sound, and a sound is always off until the person turns it on.
+ *
+ * Tokens, all optional, all read when a sound is about to play:
+ * - `--cd-sound-<event>`: a string, the path of an MP3 hosted by the app. No token, no sound, silently.
+ * - `--cd-sound-<event>-ogg`: a string, an Ogg/Opus alternative the browser may prefer.
+ * - `--cd-sound-volume`: 0 to 1, how loud every sound is. `--cd-sound-<event>-volume`: 0 to 1, scales that for one event.
+ *
+ * Safe to import on the server: the document is touched only inside `readSoundToken`.
+ */
+/** Every event, in the order the settings control lists them. */
+export const soundEvents = ["needs-you", "finished", "failed", "reply", "silent"];
+/** The events a sound is offered for once the person turns sound on; `reply` and `silent` stay off until they pick them. */
+export const defaultSoundEvents = ["needs-you", "finished", "failed"];
+/** The longest a sound may be, in seconds. `theme check` measures what it can read. */
+export const maxSoundSeconds = 1.5;
+/** The least time between two plays of the same event, in milliseconds. A burst plays once. */
+export const soundCoalesceMs = 3000;
+/** A CSS custom property's value as the text it names: quotes removed, or the inside of `url(…)`. Empty when unset. */
+export function soundString(raw) {
+    const v = raw.trim();
+    const url = /^url\(\s*(['"]?)(.*?)\1\s*\)$/.exec(v);
+    const text = url ? (url[2] ?? "") : v;
+    return text.replace(/^(['"])(.*)\1$/, "$2").trim();
+}
+const unit = (raw) => {
+    const n = Number.parseFloat(raw);
+    return Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : undefined;
+};
+const styleOf = (element) => typeof document === "undefined" || typeof getComputedStyle === "undefined" ? undefined : getComputedStyle(element ?? document.documentElement);
+/** How loud `event` is, 0 to 1: the global `--cd-sound-volume` times the event's own, each 1 when unset. 1 on the server. */
+export function readSoundVolume(event, element) {
+    const style = styleOf(element);
+    if (!style)
+        return 1;
+    return (unit(style.getPropertyValue("--cd-sound-volume")) ?? 1) * (unit(style.getPropertyValue(`--cd-sound-${event}-volume`)) ?? 1);
+}
+/**
+ * The brand's sound for `event`, read from the computed style of `element` (the document's root when left out), or
+ * `undefined` when the brand names none, or on the server.
+ */
+export function readSoundToken(event, element) {
+    const style = styleOf(element);
+    const src = style && soundString(style.getPropertyValue(`--cd-sound-${event}`));
+    if (!style || !src)
+        return undefined;
+    const ogg = soundString(style.getPropertyValue(`--cd-sound-${event}-ogg`));
+    return { src, ...(ogg && { ogg }), volume: readSoundVolume(event, element) };
+}
+/**
+ * Whether a play at `now` is allowed, given when each event last played and when anything last played: the same event
+ * waits `soundCoalesceMs` after it played, and any sound in the same instant (a burst) is the one already playing.
+ * Pure; the caller keeps the clock.
+ */
+export function mayPlay(event, last, now, burstMs = 400) {
+    const before = last[event];
+    if (before !== undefined && now - before < soundCoalesceMs)
+        return false;
+    return !soundEvents.some((e) => (last[e] ?? -Infinity) > now - burstMs);
+}