@streamsai/ui 0.0.0-stage → 0.1.1

package/dist/lib/utils.d.ts

@@ -0,0 +1,11 @@
+import type { CnFunction } from 'cn';
+/**
+ * Class merger for `@streamsai/ui`.
+ *
+ * Extends the default `cn` tables so our custom type-scale utilities
+ * (`text-body-*`, `text-body-15`, `text-compact`, `text-h3`, `text-message`) count as font sizes, not colors.
+ * Without that, merging `text-primary-foreground` with `text-body-3` drops the
+ * color — primary `Button size="sm"` labels then inherit near-black body text
+ * on a blue background.
+ */
+export declare const cn: CnFunction;

package/dist/lib/utils.js

@@ -0,0 +1,30 @@
+import { createCn } from 'cn/config';
+/**
+ * Class merger for `@streamsai/ui`.
+ *
+ * Extends the default `cn` tables so our custom type-scale utilities
+ * (`text-body-*`, `text-body-15`, `text-compact`, `text-h3`, `text-message`) count as font sizes, not colors.
+ * Without that, merging `text-primary-foreground` with `text-body-3` drops the
+ * color — primary `Button size="sm"` labels then inherit near-black body text
+ * on a blue background.
+ */
+export const cn = createCn({
+    extend: {
+        classGroups: {
+            'font-size': [
+                {
+                    text: [
+                        'body-1',
+                        'body-2',
+                        'body-3',
+                        'body-15',
+                        'compact',
+                        'h3',
+                        'message',
+                        'message-jumbo',
+                    ],
+                },
+            ],
+        },
+    },
+});

package/dist/motion/components.d.ts

@@ -0,0 +1,184 @@
+import type { AnimatePresenceProps, HTMLMotionProps, Transition } from 'motion/react';
+import type { Key, PropsWithChildren, ReactNode } from 'react';
+/**
+ * Mounted once at the app root (and in both Storybooks). Honours the OS reduced-motion setting
+ * for every `motion` element below it (transforms are dropped, opacity still fades) and makes
+ * `transitions.base` the default for any element that does not name its own.
+ */
+declare function MotionProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Makes every JS animation finish instantly. Call it from test setup and from Storybook when a
+ * browser test runner drives it, so assertions (and axe) never catch an element mid-fade.
+ */
+declare function disableMotion(): void;
+/** Test helper: lets JS animations run for real again, for a test of what happens mid-animation. */
+declare function enableMotion(): void;
+/**
+ * Test helper: keep instant animations (`skipAnimations`) but retain exiting children so presence
+ * exit targets can be asserted. Pair with `disablePresenceExits` in `afterEach`.
+ */
+declare function enablePresenceExits(): void;
+/** Restores the default `disableMotion` presence shortcut after `enablePresenceExits`. */
+declare function disablePresenceExits(): void;
+/**
+ * `motion`'s `AnimatePresence`, except that under `disableMotion` it steps aside: leaving children
+ * unmount in the same render instead of a frame later, so a test can assert an indicator is gone
+ * straight after the state change. Everything in the repo uses this one, never motion's directly.
+ */
+declare function AnimatePresence(props: PropsWithChildren<AnimatePresenceProps>): import("react").JSX.Element;
+type DivMotionProps = Omit<HTMLMotionProps<'div'>, 'initial' | 'animate' | 'exit'>;
+interface PageTransitionProps extends DivMotionProps {
+    /** Changes whenever the content is a different page (route path, stream id, session id). */
+    transitionKey: Key;
+    /** Show the content without the entrance, when something else already moves the page. */
+    still?: boolean;
+}
+/**
+ * Route and pane content arriving: a fade and a short rise each time `transitionKey` changes. It is
+ * enter-only on purpose. The old page is gone the moment the router swaps it, so the new one
+ * shows at once and never waits on an exit.
+ */
+declare function PageTransition({ transitionKey, still, className, ...props }: PageTransitionProps): import("react").JSX.Element;
+interface CollapseProps extends DivMotionProps {
+    open: boolean;
+    /** Skip the animation on first render, so content that starts open does not grow in on mount. */
+    initialOpen?: boolean;
+    /**
+     * `'x'` animates width instead, for a side panel beside flexible content. Give the child a fixed
+     * width so it slides in whole rather than reflowing on every frame.
+     */
+    axis?: 'y' | 'x';
+}
+/**
+ * Height (or width) 0 ↔ auto disclosure. Content unmounts when closed.
+ *
+ * Opening waits for the frame after the content first paints. Mounting a heavy panel can take a
+ * long frame, and an animation whose clock started before it would show up already most of the
+ * way open; starting after it keeps every frame of the reveal on screen.
+ */
+declare function Collapse({ open, initialOpen, axis, className, style, ...props }: CollapseProps): import("react").JSX.Element;
+/**
+ * The OS reduced-motion preference, following live changes. (`motion`'s `useReducedMotion` reads
+ * it once and does not re-render when it flips.) For components that must stop animating the
+ * moment the person asks, such as a height already on its way.
+ */
+declare function usePrefersReducedMotion(): boolean;
+interface AutoHeightProps extends Omit<HTMLMotionProps<'div'>, 'initial' | 'animate' | 'exit' | 'transition' | 'children'> {
+    children?: ReactNode;
+    /** `resize.step` for a whole step changing, `resize.reveal` (default) for small reveals. */
+    transition?: Transition;
+    /** Class for the measured inner block (the children's own layout, such as `flex flex-col gap-3`). */
+    innerClassName?: string;
+}
+/**
+ * A block that grows and shrinks to its content instead of jumping: a form step with a different
+ * number of lines, an error appearing, a list expanding. The inner block is measured with a
+ * ResizeObserver and the outer one animates an explicit pixel height with `resize.reveal`.
+ * It clips only while moving, so a focus ring is not cut off at rest. The tree is the same with or
+ * without reduced motion; under it the height changes in zero time.
+ */
+declare function AutoHeight({ innerClassName, children, transition, style, ...props }: AutoHeightProps): import("react").JSX.Element;
+type SwapPresetName = 'swap' | 'wheelUp' | 'wheelDown';
+interface SwapProps extends DivMotionProps {
+    /** The state being shown. A new key crossfades the old content out and the new content in. */
+    swapKey: Key;
+    /** Render as an inline element (text and icon swaps inside a button). */
+    inline?: boolean;
+    /**
+     * Motion preset for the swap. Default `swap` (blur-scale crossfade). `wheelUp` / `wheelDown`
+     * are odometer rolls — clip the parent with `overflow-hidden` so travel stays in the box.
+     */
+    preset?: SwapPresetName;
+}
+/**
+ * Dynamic variants keyed by the latest `custom` preset. AnimatePresence's `custom` is what the
+ * exiting child reads, so a wheelUp → wheelDown change exits upward (`-100%`), not with the
+ * mount-time `wheelUp` exit.
+ */
+declare const swapVariants: {
+    initial: (preset: SwapPresetName) => {
+        readonly opacity: 0;
+        readonly scale: 0.98;
+        readonly filter: "blur(2px)";
+    } | {
+        readonly y: "-100%";
+        readonly opacity: 0;
+    } | {
+        readonly y: "100%";
+        readonly opacity: 0;
+    };
+    animate: (preset: SwapPresetName) => {
+        readonly opacity: 1;
+        readonly scale: 1;
+        readonly filter: "blur(0px)";
+        readonly transition: {
+            readonly duration: 0.12;
+            readonly ease: [number, number, number, number];
+        };
+        readonly transitionEnd: {
+            readonly filter: "none";
+        };
+    } | {
+        readonly y: 0;
+        readonly opacity: 1;
+        readonly transition: {
+            readonly duration: 0.12;
+            readonly ease: [number, number, number, number];
+        };
+    } | {
+        readonly y: 0;
+        readonly opacity: 1;
+        readonly transition: {
+            readonly duration: 0.12;
+            readonly ease: [number, number, number, number];
+        };
+    };
+    exit: (preset: SwapPresetName) => {
+        readonly opacity: 0;
+        readonly scale: 0.98;
+        readonly filter: "blur(2px)";
+        readonly transition: {
+            readonly duration: 0.12;
+            readonly ease: [number, number, number, number];
+        };
+    } | {
+        readonly y: "100%";
+        readonly opacity: 0;
+        readonly transition: {
+            readonly duration: 0.1;
+            readonly ease: [number, number, number, number];
+        };
+    } | {
+        readonly y: "-100%";
+        readonly opacity: 0;
+        readonly transition: {
+            readonly duration: 0.1;
+            readonly ease: [number, number, number, number];
+        };
+    };
+};
+/**
+ * One piece of content replacing another in the same spot: Copy → Copied, an icon changing, a
+ * status label flipping, or a counter rolling. The two overlap briefly (`popLayout`), so the
+ * surrounding layout does not jump while they swap.
+ */
+declare function Swap({ swapKey, inline, preset, className, ...props }: SwapProps): import("react").JSX.Element;
+interface StaggerItemProps extends DivMotionProps {
+    /** Position in the group; later items start a beat later, capped by `stagger.max`. */
+    index: number;
+    /** `rise` for rows, `lift` for cards, `pop` for chips, `scaleIn` for tiles that grow in place. */
+    preset?: 'rise' | 'lift' | 'pop' | 'fade' | 'scaleIn';
+    /** Seconds between peers; `stagger.offset` for a Sense peer group. */
+    step?: number;
+    /** `li` for a row in a list. */
+    as?: 'div' | 'li';
+}
+/**
+ * A card, row or widget in a group that should cascade in on first render (settings cards,
+ * analytics widgets, catalog tiles). The cascade is capped, so a long list is never slow to show.
+ */
+declare function StaggerItem({ index, preset, step, as, ...props }: StaggerItemProps): import("react").JSX.Element;
+export { MotionProvider, disableMotion, enableMotion, enablePresenceExits, disablePresenceExits, AnimatePresence, PageTransition, Collapse, AutoHeight, usePrefersReducedMotion, Swap, swapVariants, StaggerItem, };
+export type { PageTransitionProps, CollapseProps, AutoHeightProps, SwapProps, SwapPresetName, StaggerItemProps, };

package/dist/motion/components.js

@@ -0,0 +1,211 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { AnimatePresence as MotionAnimatePresence, MotionConfig, MotionGlobalConfig, PresenceContext, animate, motion, useIsPresent, useMotionValue, } from 'motion/react';
+import { useCallback, useContext, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore, } from 'react';
+import { presets, resize, staggerDelay, transitions } from './config.js';
+/**
+ * Mounted once at the app root (and in both Storybooks). Honours the OS reduced-motion setting
+ * for every `motion` element below it (transforms are dropped, opacity still fades) and makes
+ * `transitions.base` the default for any element that does not name its own.
+ */
+function MotionProvider({ children }) {
+    return (_jsx(MotionConfig, { reducedMotion: "user", transition: transitions.base, children: children }));
+}
+/**
+ * Makes every JS animation finish instantly. Call it from test setup and from Storybook when a
+ * browser test runner drives it, so assertions (and axe) never catch an element mid-fade.
+ */
+function disableMotion() {
+    MotionGlobalConfig.skipAnimations = true;
+    exitsDisabled = true;
+}
+/** Test helper: lets JS animations run for real again, for a test of what happens mid-animation. */
+function enableMotion() {
+    MotionGlobalConfig.skipAnimations = false;
+    exitsDisabled = false;
+}
+/**
+ * Test helper: keep instant animations (`skipAnimations`) but retain exiting children so presence
+ * exit targets can be asserted. Pair with `disablePresenceExits` in `afterEach`.
+ */
+function enablePresenceExits() {
+    exitsDisabled = false;
+}
+/** Restores the default `disableMotion` presence shortcut after `enablePresenceExits`. */
+function disablePresenceExits() {
+    exitsDisabled = true;
+}
+/** Set once, before the first render, by `disableMotion`; flipped only by the test helpers above. */
+let exitsDisabled = false;
+/**
+ * `motion`'s `AnimatePresence`, except that under `disableMotion` it steps aside: leaving children
+ * unmount in the same render instead of a frame later, so a test can assert an indicator is gone
+ * straight after the state change. Everything in the repo uses this one, never motion's directly.
+ */
+function AnimatePresence(props) {
+    if (exitsDisabled)
+        return _jsx(_Fragment, { children: props.children });
+    return _jsx(MotionAnimatePresence, { ...props });
+}
+/**
+ * Route and pane content arriving: a fade and a short rise each time `transitionKey` changes. It is
+ * enter-only on purpose. The old page is gone the moment the router swaps it, so the new one
+ * shows at once and never waits on an exit.
+ */
+function PageTransition({ transitionKey, still = false, className, ...props }) {
+    return (_jsx(motion.div, { initial: still ? false : presets.rise.initial, animate: presets.rise.animate, className: className, ...props }, transitionKey));
+}
+/**
+ * Height (or width) 0 ↔ auto disclosure. Content unmounts when closed.
+ *
+ * Opening waits for the frame after the content first paints. Mounting a heavy panel can take a
+ * long frame, and an animation whose clock started before it would show up already most of the
+ * way open; starting after it keeps every frame of the reveal on screen.
+ */
+function Collapse({ open, initialOpen = true, axis = 'y', className, style, ...props }) {
+    return (_jsx(AnimatePresence, { initial: !initialOpen, children: open ? (_jsx(CollapseBody, { axis: axis, className: className, style: style, ...props }, "collapse")) : null }));
+}
+function CollapseBody({ axis, style, onAnimationStart, onAnimationComplete, ...props }) {
+    const preset = axis === 'x' ? presets.collapseX : presets.collapse;
+    // `initial: false` from the presence means this is the first render of content that starts open
+    // (`initialOpen`): it appears as it is. Anything opened after that grows in.
+    const skipEntrance = useContext(PresenceContext)?.initial === false;
+    const [painted, setPainted] = useState(skipEntrance || exitsDisabled);
+    // The body clips only while its edge moves. Open and at rest it does not, so a focus ring, a
+    // shadow or a negative margin on the content is not cut off at the body's edge.
+    const [settled, setSettled] = useState(painted);
+    const present = useIsPresent();
+    useEffect(() => {
+        if (painted)
+            return;
+        // Two frames: the first still runs before the mount's own layout and paint.
+        let frame = requestAnimationFrame(() => {
+            frame = requestAnimationFrame(() => setPainted(true));
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [painted]);
+    return (_jsx(motion.div, { initial: preset.initial, animate: painted ? preset.animate : preset.initial, exit: preset.exit, style: { overflow: settled ? undefined : 'hidden', ...style }, onAnimationStart: (definition) => {
+            setSettled(false);
+            onAnimationStart?.(definition);
+        }, onAnimationComplete: (definition) => {
+            setSettled(painted && present);
+            onAnimationComplete?.(definition);
+        }, ...props }));
+}
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+function subscribeReducedMotion(notify) {
+    if (typeof window.matchMedia !== 'function')
+        return () => { };
+    const query = window.matchMedia(REDUCED_MOTION_QUERY);
+    query.addEventListener('change', notify);
+    return () => query.removeEventListener('change', notify);
+}
+const reducedMotionNow = () => typeof window.matchMedia === 'function' && window.matchMedia(REDUCED_MOTION_QUERY).matches;
+/**
+ * The OS reduced-motion preference, following live changes. (`motion`'s `useReducedMotion` reads
+ * it once and does not re-render when it flips.) For components that must stop animating the
+ * moment the person asks, such as a height already on its way.
+ */
+function usePrefersReducedMotion() {
+    return useSyncExternalStore(subscribeReducedMotion, reducedMotionNow, () => false);
+}
+/**
+ * A block that grows and shrinks to its content instead of jumping: a form step with a different
+ * number of lines, an error appearing, a list expanding. The inner block is measured with a
+ * ResizeObserver and the outer one animates an explicit pixel height with `resize.reveal`.
+ * It clips only while moving, so a focus ring is not cut off at rest. The tree is the same with or
+ * without reduced motion; under it the height changes in zero time.
+ */
+function AutoHeight({ innerClassName, children, transition = resize.reveal, style, ...props }) {
+    const reduced = usePrefersReducedMotion();
+    const innerRef = useRef(null);
+    const height = useMotionValue('auto');
+    const control = useRef(null);
+    const measured = useRef(false);
+    const [moving, setMoving] = useState(false);
+    // The latest options, so the observer (set up once) never goes stale.
+    const options = useRef({ reduced, transition });
+    useLayoutEffect(() => {
+        options.current = { reduced, transition };
+    });
+    const measure = useCallback(() => {
+        const node = innerRef.current;
+        if (!node)
+            return;
+        const next = Math.ceil(node.getBoundingClientRect().height);
+        control.current?.stop();
+        // The first measure replaces `auto`, which cannot be animated, so it is set as it is.
+        if (!measured.current || options.current.reduced) {
+            measured.current = true;
+            height.set(next);
+            setMoving(false);
+            return;
+        }
+        if (height.get() === next) {
+            // Back where it was before the animation got going: nothing left to wait for.
+            setMoving(false);
+            return;
+        }
+        setMoving(true);
+        control.current = animate(height, next, {
+            ...options.current.transition,
+            onComplete: () => setMoving(false),
+        });
+    }, [height]);
+    // Asking for less motion mid-animation settles the height where it is going, at once.
+    useLayoutEffect(() => {
+        if (reduced)
+            measure();
+    }, [reduced, measure]);
+    useLayoutEffect(() => {
+        measure();
+        const node = innerRef.current;
+        if (!node || typeof ResizeObserver === 'undefined')
+            return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(node);
+        return () => {
+            observer.disconnect();
+            control.current?.stop();
+        };
+    }, [measure]);
+    return (_jsx(motion.div, { style: { height, overflow: moving ? 'hidden' : undefined, ...style }, ...props, children: _jsx("div", { ref: innerRef, className: innerClassName, children: children }) }));
+}
+/**
+ * Dynamic variants keyed by the latest `custom` preset. AnimatePresence's `custom` is what the
+ * exiting child reads, so a wheelUp → wheelDown change exits upward (`-100%`), not with the
+ * mount-time `wheelUp` exit.
+ */
+const swapVariants = {
+    initial: (preset) => presets[preset].initial,
+    animate: (preset) => presets[preset].animate,
+    exit: (preset) => presets[preset].exit,
+};
+/**
+ * One piece of content replacing another in the same spot: Copy → Copied, an icon changing, a
+ * status label flipping, or a counter rolling. The two overlap briefly (`popLayout`), so the
+ * surrounding layout does not jump while they swap.
+ */
+function Swap({ swapKey, inline = false, preset = 'swap', className, ...props }) {
+    // `custom` on AnimatePresence is the exit direction for the outgoing keyed child.
+    return (_jsx(AnimatePresence, { mode: "popLayout", initial: false, custom: preset, children: inline ? (_jsx(motion.span, { custom: preset, variants: swapVariants, initial: "initial", animate: "animate", exit: "exit", className: className, ...props }, swapKey)) : (_jsx(motion.div, { custom: preset, variants: swapVariants, initial: "initial", animate: "animate", exit: "exit", className: className, ...props }, swapKey)) }));
+}
+/** Adds `delay` to a transition and to each per-value transition inside it, which ignore the top level. */
+const withDelay = (transition, delay) => Object.fromEntries([
+    ...Object.entries(transition).map(([key, value]) => value && typeof value === 'object' && !Array.isArray(value)
+        ? [key, { ...value, delay: (value.delay ?? 0) + delay }]
+        : [key, value]),
+    ['delay', delay],
+]);
+/**
+ * A card, row or widget in a group that should cascade in on first render (settings cards,
+ * analytics widgets, catalog tiles). The cascade is capped, so a long list is never slow to show.
+ */
+function StaggerItem({ index, preset = 'rise', step, as = 'div', ...props }) {
+    const { initial, animate, exit } = presets[preset];
+    const Element = as === 'li' ? motion.li : motion.div;
+    return (_jsx(Element, { initial: initial, animate: {
+            ...animate,
+            transition: withDelay(animate.transition, staggerDelay(index, step)),
+        }, exit: exit, ...props }));
+}
+export { MotionProvider, disableMotion, enableMotion, enablePresenceExits, disablePresenceExits, AnimatePresence, PageTransition, Collapse, AutoHeight, usePrefersReducedMotion, Swap, swapVariants, StaggerItem, };