plass-ui 0.0.1 → 1.0.0

package/dist/components/animate-fade/PlAnimateFade.d.ts

@@ -0,0 +1,35 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import type { PlassAnimateMode, PlassAnimateProps } from '../../types.js';
+export interface PlAnimateFadeProps extends PlassAnimateProps, React.ComponentPropsWithoutRef<'div'> {
+    /**
+     * Whether the content arrives or leaves.
+     * @default 'in'
+     */
+    mode?: PlassAnimateMode;
+    /**
+     * The opacity it starts from, between `0` and `1`. Raise it for content that
+     * should never be completely gone.
+     * @default 0
+     */
+    from?: number;
+    /** Renders something other than a `<div>`. Base UI's own escape hatch. */
+    render?: useRender.RenderProp;
+    children?: React.ReactNode;
+}
+/**
+ * Content arriving or leaving on opacity alone.
+ *
+ * The plainest effect in the set and the one to reach for first: nothing moves,
+ * so nothing reflows and nothing is resampled. A fade is the only entrance that
+ * is safe on a block of text at any size.
+ *
+ * It is also the effect that suits glass. A Plass sheet is defined by what
+ * shows through it, and opacity is the axis the material already answers on —
+ * the same axis the glass ladder itself is built from.
+ *
+ * `mode="out"` is the same animation run backwards, and it is held at the end:
+ * a faded-out element stays faded out rather than snapping back into view when
+ * the animation finishes.
+ */
+export declare const PlAnimateFade: React.ForwardRefExoticComponent<PlAnimateFadeProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/animate-fade/PlAnimateFade.js

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { isInfinite, useAnimateElement } from '../../internal/animate.js';
+import { cx } from '../../internal/styles.js';
+/**
+ * Content arriving or leaving on opacity alone.
+ *
+ * The plainest effect in the set and the one to reach for first: nothing moves,
+ * so nothing reflows and nothing is resampled. A fade is the only entrance that
+ * is safe on a block of text at any size.
+ *
+ * It is also the effect that suits glass. A Plass sheet is defined by what
+ * shows through it, and opacity is the axis the material already answers on —
+ * the same axis the glass ladder itself is built from.
+ *
+ * `mode="out"` is the same animation run backwards, and it is held at the end:
+ * a faded-out element stays faded out rather than snapping back into view when
+ * the animation finishes.
+ */
+export const PlAnimateFade = /* @__PURE__ */ React.forwardRef(function PlAnimateFade({ duration = 300, delay = 0, easing, repeat = 1, alternate, paused, trigger = 'mount', play, once = true, threshold = 0.2, mode = 'in', from = 0, render, className, style, children, ...props }, ref) {
+    const animate = useAnimateElement({
+        effect: 'fade',
+        duration,
+        delay,
+        easing,
+        repeat,
+        alternate,
+        mode,
+        opacity: from,
+        trigger,
+        play,
+        once,
+        threshold,
+        paused,
+        infinite: isInfinite(repeat)
+    });
+    return useRender({
+        render,
+        ref: [ref, animate.ref],
+        props: {
+            ...props,
+            className: cx(animate.className, className),
+            style: { ...animate.style, ...style },
+            ...animate.props,
+            children
+        }
+    });
+});

package/dist/components/animate-fade/index.d.ts

@@ -0,0 +1,2 @@
+export { PlAnimateFade } from './PlAnimateFade.js';
+export type { PlAnimateFadeProps } from './PlAnimateFade.js';

package/dist/components/animate-fade/index.js

@@ -0,0 +1 @@
+export { PlAnimateFade } from './PlAnimateFade.js';

package/dist/components/animate-grow/PlAnimateGrow.d.ts

@@ -0,0 +1,45 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import type { PlassAnimateMode, PlassAnimateProps } from '../../types.js';
+export interface PlAnimateGrowProps extends PlassAnimateProps, React.ComponentPropsWithoutRef<'div'> {
+    /**
+     * Whether the content unfolds or folds away.
+     * @default 'in'
+     */
+    mode?: PlassAnimateMode;
+    /**
+     * The scale it starts from, as a multiple of its final size. Above `1` it
+     * settles down onto the page instead of up out of it.
+     * @default 0.8
+     */
+    from?: number;
+    /**
+     * Which point stays put while the rest moves — any CSS `transform-origin`.
+     * `'top'` unfolds downwards, `'bottom left'` out of a corner.
+     * @default 'center'
+     */
+    origin?: string;
+    /**
+     * Fades in as it grows. Turn it off for something already on the page that is
+     * only changing size.
+     * @default true
+     */
+    fade?: boolean;
+    /** Renders something other than a `<div>`. Base UI's own escape hatch. */
+    render?: useRender.RenderProp;
+    children?: React.ReactNode;
+}
+/**
+ * Content unfolding from a point.
+ *
+ * The difference from Zoom is `origin` and how far it travels: a Grow starts
+ * close to its final size and can be anchored to an edge, so it reads as
+ * something opening out of the thing beside it — a panel out of a toolbar, a
+ * card out of the row it belongs to. A Zoom starts much smaller and always from
+ * the middle.
+ *
+ * Short travel is what makes it safe on glass. A sheet growing from 0.8 stays
+ * recognisably the same sheet the whole way, and the blur behind it never has
+ * to resolve a surface that is a fifth of the size it is about to be.
+ */
+export declare const PlAnimateGrow: React.ForwardRefExoticComponent<PlAnimateGrowProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/animate-grow/PlAnimateGrow.js

@@ -0,0 +1,49 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { isInfinite, useAnimateElement } from '../../internal/animate.js';
+import { cx } from '../../internal/styles.js';
+/**
+ * Content unfolding from a point.
+ *
+ * The difference from Zoom is `origin` and how far it travels: a Grow starts
+ * close to its final size and can be anchored to an edge, so it reads as
+ * something opening out of the thing beside it — a panel out of a toolbar, a
+ * card out of the row it belongs to. A Zoom starts much smaller and always from
+ * the middle.
+ *
+ * Short travel is what makes it safe on glass. A sheet growing from 0.8 stays
+ * recognisably the same sheet the whole way, and the blur behind it never has
+ * to resolve a surface that is a fifth of the size it is about to be.
+ */
+export const PlAnimateGrow = /* @__PURE__ */ React.forwardRef(function PlAnimateGrow({ duration = 320, delay = 0, easing, repeat = 1, alternate, paused, trigger = 'mount', play, once = true, threshold = 0.2, mode = 'in', from = 0.8, origin = 'center', fade = true, render, className, style, children, ...props }, ref) {
+    const animate = useAnimateElement({
+        effect: 'grow',
+        duration,
+        delay,
+        easing,
+        repeat,
+        alternate,
+        mode,
+        scale: from,
+        opacity: fade ? 0 : 1,
+        trigger,
+        play,
+        once,
+        threshold,
+        paused,
+        infinite: isInfinite(repeat)
+    });
+    return useRender({
+        render,
+        ref: [ref, animate.ref],
+        props: {
+            ...props,
+            className: cx(animate.className, className),
+            // `transform-origin` governs the standalone `scale` property too, which
+            // is what lets the effect stay off the `transform` shorthand entirely.
+            style: { transformOrigin: origin, ...animate.style, ...style },
+            ...animate.props,
+            children
+        }
+    });
+});

package/dist/components/animate-grow/index.d.ts

@@ -0,0 +1,2 @@
+export { PlAnimateGrow } from './PlAnimateGrow.js';
+export type { PlAnimateGrowProps } from './PlAnimateGrow.js';

package/dist/components/animate-grow/index.js

@@ -0,0 +1 @@
+export { PlAnimateGrow } from './PlAnimateGrow.js';

package/dist/components/animate-headline/PlAnimateHeadline.d.ts

@@ -0,0 +1,55 @@
+import * as React from 'react';
+import type { PlassAnimateProps } from '../../types.js';
+export interface PlAnimateHeadlineProps extends Omit<PlassAnimateProps, 'alternate'>, React.ComponentPropsWithoutRef<'div'> {
+    /**
+     * How long each line is held before the next one comes up, in milliseconds.
+     * Counted from the moment a line arrives, so it is reading time rather than a
+     * cycle length.
+     * @default 2600
+     */
+    interval?: number;
+    /**
+     * Which line is showing. Pass it to drive the reel yourself — from a step in
+     * a form, a tab, or a timer of your own.
+     */
+    index?: number;
+    /** Where an uncontrolled reel starts. @default 0 */
+    defaultIndex?: number;
+    /** Called with the line that has just come up. */
+    onIndexChange?: (index: number) => void;
+    /**
+     * Starts again after the last line. Off, the reel stops on the last one and
+     * stays there.
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * How far a line travels as it comes up or leaves — a CSS length, or a number
+     * in pixels. `'100%'` is one line's own height.
+     * @default '100%'
+     */
+    rise?: number | string;
+    /** The lines, in the order they should be read. */
+    children?: React.ReactNode;
+}
+/**
+ * One line replacing the one above it, on a timer.
+ *
+ * Every line sits in the same grid cell, so the box is as tall as the longest of
+ * them from the first frame and never resizes as the reel turns — which is the
+ * whole difficulty with this effect, and the reason the lines that are not
+ * showing keep their space with `visibility` rather than being taken out of the
+ * layout.
+ *
+ * It is deliberately not a ticker. A line comes up, it stops, and it is held
+ * long enough to read; `interval` is counted from the moment it arrives rather
+ * than from the start of the cycle, so raising `duration` does not quietly eat
+ * the reading time.
+ *
+ * Use it for a set of phrases where any one of them would have done — three
+ * ways of saying what a product is, a rotating set of customer names. What it is
+ * not for is content a reader has to see, because there is no guarantee they are
+ * looking during the two seconds it is up, and a screen reader is given the line
+ * that happens to be showing rather than the set.
+ */
+export declare const PlAnimateHeadline: React.ForwardRefExoticComponent<PlAnimateHeadlineProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/animate-headline/PlAnimateHeadline.js

@@ -0,0 +1,120 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+import { isInfinite, lengthValue, useAnimationRun, usePrefersReducedMotion } from '../../internal/animate.js';
+import { cx } from '../../internal/styles.js';
+/**
+ * One line replacing the one above it, on a timer.
+ *
+ * Every line sits in the same grid cell, so the box is as tall as the longest of
+ * them from the first frame and never resizes as the reel turns — which is the
+ * whole difficulty with this effect, and the reason the lines that are not
+ * showing keep their space with `visibility` rather than being taken out of the
+ * layout.
+ *
+ * It is deliberately not a ticker. A line comes up, it stops, and it is held
+ * long enough to read; `interval` is counted from the moment it arrives rather
+ * than from the start of the cycle, so raising `duration` does not quietly eat
+ * the reading time.
+ *
+ * Use it for a set of phrases where any one of them would have done — three
+ * ways of saying what a product is, a rotating set of customer names. What it is
+ * not for is content a reader has to see, because there is no guarantee they are
+ * looking during the two seconds it is up, and a screen reader is given the line
+ * that happens to be showing rather than the set.
+ */
+export const PlAnimateHeadline = /* @__PURE__ */ React.forwardRef(function PlAnimateHeadline({ duration = 460, delay = 0, easing, repeat = 'infinite', paused, trigger = 'mount', play, once = true, threshold = 0.2, interval = 2600, index, defaultIndex = 0, onIndexChange, loop = true, rise = '100%', className, style, children, ...props }, ref) {
+    const run = useAnimationRun({
+        trigger,
+        play,
+        once,
+        threshold,
+        paused,
+        infinite: isInfinite(repeat)
+    });
+    const reduced = usePrefersReducedMotion();
+    const items = React.Children.toArray(children);
+    const count = items.length;
+    const [uncontrolled, setUncontrolled] = React.useState(defaultIndex);
+    const active = Math.min(index ?? uncontrolled, Math.max(count - 1, 0));
+    /** The line on its way out. Cleared once its animation has had its time. */
+    const [leaving, setLeaving] = React.useState(null);
+    const previous = React.useRef(active);
+    React.useEffect(() => {
+        if (previous.current !== active) {
+            setLeaving(previous.current);
+            previous.current = active;
+        }
+    }, [active]);
+    React.useEffect(() => {
+        if (leaving === null) {
+            return;
+        }
+        const timer = setTimeout(() => setLeaving(null), duration);
+        return () => clearTimeout(timer);
+    }, [leaving, duration]);
+    const advance = React.useCallback(() => {
+        const next = active + 1;
+        if (next >= count) {
+            if (!loop) {
+                return;
+            }
+            if (index === undefined) {
+                setUncontrolled(0);
+            }
+            onIndexChange?.(0);
+            return;
+        }
+        if (index === undefined) {
+            setUncontrolled(next);
+        }
+        onIndexChange?.(next);
+    }, [active, count, loop, index, onIndexChange]);
+    /**
+     * The reel only turns on its own when it was not handed an `index`. A
+     * controlled Headline is somebody else's timer, and a second one running
+     * underneath it would fight for the same state.
+     */
+    const turned = React.useRef(false);
+    React.useEffect(() => {
+        if (index !== undefined || count < 2 || run.state !== 'running') {
+            return;
+        }
+        if (!loop && active === count - 1) {
+            return;
+        }
+        // `delay` is what happens before the reel starts turning at all, so it is
+        // added once rather than to every line — which is what an `interval` is.
+        const timer = setTimeout(() => {
+            turned.current = true;
+            advance();
+        }, interval + (turned.current ? 0 : delay));
+        return () => clearTimeout(timer);
+    }, [index, count, run.state, interval, delay, advance, loop, active]);
+    return (_jsx("div", { ref: (node) => {
+            run.ref(node);
+            if (typeof ref === 'function') {
+                ref(node);
+            }
+            else if (ref) {
+                ref.current = node;
+            }
+        }, className: cx('plass-headline', className), style: {
+            '--p-anim-duration': `${duration}ms`,
+            '--p-anim-rise': lengthValue(rise),
+            ...(easing ? { '--p-anim-ease': easing } : {}),
+            '--p-anim-state': run.state,
+            ...style
+        }, "data-plass-animation": "headline", "data-state": run.state, ...run.handlers, ...props, children: items.map((child, position) => {
+            const state = position === active ? 'active' : position === leaving && !reduced ? 'leaving' : undefined;
+            const wrap = (content, key) => (_jsx("span", { className: "plass-headline-item", "data-state": state, children: content }, key));
+            if (!React.isValidElement(child)) {
+                return wrap(child, position);
+            }
+            const childProps = child.props;
+            return React.cloneElement(child, {
+                key: position,
+                className: cx('plass-headline-item', childProps.className),
+                'data-state': state
+            });
+        }) }));
+});

package/dist/components/animate-headline/index.d.ts

@@ -0,0 +1,2 @@
+export { PlAnimateHeadline } from './PlAnimateHeadline.js';
+export type { PlAnimateHeadlineProps } from './PlAnimateHeadline.js';

package/dist/components/animate-headline/index.js

@@ -0,0 +1 @@
+export { PlAnimateHeadline } from './PlAnimateHeadline.js';

package/dist/components/animate-lighting/PlAnimateLighting.d.ts

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import type { PlassAnimateProps, PlassColor, PlassSize } from '../../types.js';
+export interface PlAnimateLightingProps extends PlassAnimateProps, Omit<React.ComponentPropsWithoutRef<'div'>, 'color'> {
+    /**
+     * Which family the light is drawn in. The arc turns between that family's two
+     * ends as it travels, exactly as a `solid` fill does.
+     * @default 'primary'
+     */
+    color?: PlassColor;
+    /**
+     * A CSS colour, when a semantic family is not what is wanted. Overrides
+     * `color`, and the arc stops turning — one colour has nowhere to turn to.
+     */
+    glow?: string;
+    /**
+     * The radius the light follows, on the shared ladder. It has to match what is
+     * inside, or the glow will cut a corner the content has rounded off.
+     * @default 'md'
+     */
+    size?: PlassSize;
+    /**
+     * How far past the content the light reaches, in pixels.
+     * @default 3
+     */
+    spread?: number;
+    /**
+     * How much of the outline is lit at once, in degrees. Small is a travelling
+     * spark; large is a sweep.
+     * @default 50
+     */
+    arc?: number;
+    /**
+     * How soft the light is, in pixels. At `0` it is a hard-edged wedge, which
+     * reads as a graphic rather than as light.
+     * @default 5
+     */
+    blur?: number;
+    /** Runs the light the other way round. @default false */
+    reverse?: boolean;
+    /** Renders something other than a `<div>`. Base UI's own escape hatch. */
+    render?: useRender.RenderProp;
+    children?: React.ReactNode;
+}
+/**
+ * A light travelling around the outside of something.
+ *
+ * The light is **behind** the content rather than on it, so what a reader sees
+ * is a glow escaping from under the edges — which is why it works on a PlCard
+ * or a PlButton without touching anything about how they are drawn. Nothing
+ * inside is altered, nothing is overlaid, and the content stays exactly as
+ * legible as it was.
+ *
+ * The arc itself is a gradient that turns between the two ends of the family,
+ * which is the same rule every filled surface in the library follows: a flat
+ * coloured arc would be paint, and nothing here is paint.
+ *
+ * Use it to mark the one thing on a screen that is currently live — the row
+ * that is processing, the field being checked, the plan being recommended. It
+ * draws attention with light rather than by moving anything, which is the only
+ * way this library has of saying "here" without also saying "and it moved".
+ *
+ * `size` has to agree with the radius of what is inside it. The glow follows
+ * the wrapper's own corners, so an `lg` card in an `xs` Lighting will show light
+ * poking out of four corners the card has already rounded away.
+ */
+export declare const PlAnimateLighting: React.ForwardRefExoticComponent<PlAnimateLightingProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/animate-lighting/PlAnimateLighting.js

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { isInfinite, useAnimateElement } from '../../internal/animate.js';
+import { cx, radiusClasses } from '../../internal/styles.js';
+/**
+ * A light travelling around the outside of something.
+ *
+ * The light is **behind** the content rather than on it, so what a reader sees
+ * is a glow escaping from under the edges — which is why it works on a PlCard
+ * or a PlButton without touching anything about how they are drawn. Nothing
+ * inside is altered, nothing is overlaid, and the content stays exactly as
+ * legible as it was.
+ *
+ * The arc itself is a gradient that turns between the two ends of the family,
+ * which is the same rule every filled surface in the library follows: a flat
+ * coloured arc would be paint, and nothing here is paint.
+ *
+ * Use it to mark the one thing on a screen that is currently live — the row
+ * that is processing, the field being checked, the plan being recommended. It
+ * draws attention with light rather than by moving anything, which is the only
+ * way this library has of saying "here" without also saying "and it moved".
+ *
+ * `size` has to agree with the radius of what is inside it. The glow follows
+ * the wrapper's own corners, so an `lg` card in an `xs` Lighting will show light
+ * poking out of four corners the card has already rounded away.
+ */
+export const PlAnimateLighting = /* @__PURE__ */ React.forwardRef(function PlAnimateLighting({ duration = 3000, delay = 0, easing, repeat = 'infinite', alternate, paused, trigger = 'mount', play, once = true, threshold = 0.2, color = 'primary', glow, size = 'md', spread = 3, arc = 50, blur = 5, reverse = false, render, className, style, children, ...props }, ref) {
+    const animate = useAnimateElement({
+        // The keyframe runs on a pseudo-element rather than on the root, so there
+        // is no effect class to apply here — only the slots it reads.
+        effect: null,
+        duration,
+        delay,
+        easing,
+        repeat,
+        alternate,
+        mode: reverse ? 'out' : 'in',
+        trigger,
+        play,
+        once,
+        threshold,
+        paused,
+        infinite: isInfinite(repeat)
+    });
+    return useRender({
+        render,
+        ref: [ref, animate.ref],
+        props: {
+            ...props,
+            className: cx('plass-anim-lighting', radiusClasses[size], className),
+            style: {
+                ...animate.style,
+                '--p-anim-glow-from': glow ?? `var(--plass-${color}-solid)`,
+                '--p-anim-glow-to': glow ?? `var(--plass-${color}-solid-to)`,
+                '--p-anim-glow-width': `${spread}px`,
+                '--p-anim-glow-arc': `${arc}deg`,
+                '--p-anim-glow-blur': `${blur}px`,
+                ...style
+            },
+            ...animate.props,
+            'data-plass-animation': 'lighting',
+            children
+        }
+    });
+});

package/dist/components/animate-lighting/index.d.ts

@@ -0,0 +1,2 @@
+export { PlAnimateLighting } from './PlAnimateLighting.js';
+export type { PlAnimateLightingProps } from './PlAnimateLighting.js';

package/dist/components/animate-lighting/index.js

@@ -0,0 +1 @@
+export { PlAnimateLighting } from './PlAnimateLighting.js';

package/dist/components/animate-marquee/PlAnimateMarquee.d.ts

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import type { PlassAnimateProps, PlassOrientation } from '../../types.js';
+export interface PlAnimateMarqueeProps extends PlassAnimateProps, React.ComponentPropsWithoutRef<'div'> {
+    /**
+     * Which way the strip runs.
+     * @default 'horizontal'
+     */
+    orientation?: PlassOrientation;
+    /**
+     * Runs it the other way — left to right, or bottom to top.
+     * @default false
+     */
+    reverse?: boolean;
+    /**
+     * How fast the content travels, in pixels per second. A speed rather than a
+     * duration, so a strip of four logos and a strip of forty move at the same
+     * pace instead of the long one becoming a blur.
+     * @default 60
+     */
+    speed?: number;
+    /**
+     * The gap between items, and between the last item and the first of the next
+     * pass — a CSS length, or a number in pixels.
+     * @default '2rem'
+     */
+    gap?: number | string;
+    /**
+     * How many copies of the content are laid end to end. Two is enough for
+     * anything at least as wide as its container; raise it when the content is
+     * short enough to leave a hole behind itself.
+     * @default 2
+     */
+    copies?: number;
+    /**
+     * Stops while the pointer is on it, so something scrolling past can actually
+     * be read or clicked.
+     * @default true
+     */
+    pauseOnHover?: boolean;
+    /** The things that scroll past. */
+    children?: React.ReactNode;
+}
+/**
+ * Content scrolling steadily past, forever.
+ *
+ * The content is laid down twice, and each copy travels exactly its own length
+ * plus the gap — so the moment the first copy has left, the second is standing
+ * precisely where it began. There is no seam, no jump and no frame where the
+ * strip is empty, and none of that depends on measuring anything.
+ *
+ * What *is* measured is only the speed. A duration would mean a strip of four
+ * logos and a strip of forty crossing the same box in the same time, with the
+ * long one becoming unreadable; `speed` is pixels per second, so both move at
+ * the pace of a reader instead. The strip is re-measured whenever it changes
+ * size.
+ *
+ * `pauseOnHover` is on by default and is not decoration: content moving past a
+ * pointer cannot be clicked reliably, and a link inside a marquee that never
+ * stops is a link nobody can follow.
+ *
+ * Only the first copy is read out. The rest carry `aria-hidden`, or a screen
+ * reader would announce everything on the strip as many times as it was laid
+ * down.
+ */
+export declare const PlAnimateMarquee: React.ForwardRefExoticComponent<PlAnimateMarqueeProps & React.RefAttributes<HTMLDivElement>>;