plass-ui 0.0.1 → 1.0.0

package/dist/internal/animate.js

@@ -0,0 +1,318 @@
+/**
+ * The machinery every `PlAnimate*` component runs on.
+ *
+ * It lives in `internal/` for the reason `button-group.ts` and `progress.ts`
+ * do: eleven components need it and none of them should have to import another.
+ *
+ * ## The shape of it
+ *
+ * Every effect is one `@keyframes` in `styles.css` running from a state written
+ * entirely in custom properties to the element's natural one. Nothing here
+ * generates CSS — it fills `--p-anim-*` slots and the stylesheet decides what
+ * they mean, which is the same split `controlSlots()` makes for colour and for
+ * the same reason: Tailwind only ever sees class names that appear literally in
+ * the source, so a class per duration would not survive the first prop.
+ *
+ * Because the from-state is the *keyframe* rather than a second class, running
+ * an effect backwards is `animation-direction: reverse` and nothing else. That
+ * is what makes `mode="out"` free on the five that offer it.
+ *
+ * ## Where the design language draws the line
+ *
+ * A Plass **control** never moves — a key that scales resamples its label, and
+ * that rule holds without exception. What moves here is content a caller has
+ * asked to have moved, and it moves on the independent `translate`, `scale` and
+ * `rotate` properties rather than on the `transform` shorthand, so a caller's
+ * own transform on the same element survives.
+ *
+ * ## What is deliberately not here
+ *
+ * An effect that has to know what its children *are* — a marquee that lays them
+ * down twice, a headline that swaps between them, a typewriter that counts
+ * graphemes — cannot be a class name and a few numbers. Those are components,
+ * and their logic stays in their own files.
+ */
+import * as React from 'react';
+/* ---------------------------------------------------------------------------
+ * Slots
+ * ------------------------------------------------------------------------- */
+/**
+ * Which keyframe an effect runs.
+ *
+ * `grow` and `zoom` share one: they are the same arithmetic at two strengths,
+ * and a second identical `@keyframes` would only be a second place to fix a
+ * bug. What separates them is their defaults and their origin, and an origin is
+ * a property rather than a keyframe.
+ */
+export const animationClasses = {
+    fade: 'plass-anim-fade',
+    grow: 'plass-anim-scale',
+    slide: 'plass-anim-slide',
+    zoom: 'plass-anim-scale',
+    rotate: 'plass-anim-rotate',
+    blink: 'plass-anim-blink'
+};
+/** The class that reads the slots. Always paired with one of the above. */
+export const animBaseClass = 'plass-anim';
+/** A number is pixels; a string is already a CSS length. */
+export function lengthValue(value) {
+    return typeof value === 'number' ? `${value}px` : value;
+}
+/** `'infinite'` reaches CSS as the word; a count reaches it as the number. */
+export function repeatValue(repeat) {
+    return repeat === 'infinite' ? 'infinite' : String(repeat);
+}
+export function isInfinite(repeat) {
+    return repeat === 'infinite';
+}
+/**
+ * `normal`, `reverse`, `alternate`, `alternate-reverse` — the four CSS already
+ * has, assembled from the two props that mean something to a caller.
+ *
+ * `mode="out"` is a reversed run rather than a keyframe of its own, which is
+ * also why a reversed animation ends held on its own first frame: `fill-mode`
+ * is `both`, so a faded-out element stays faded out instead of snapping back.
+ */
+export function directionValue(mode, alternate) {
+    if (mode === 'out') {
+        return alternate ? 'alternate-reverse' : 'reverse';
+    }
+    return alternate ? 'alternate' : 'normal';
+}
+/**
+ * The `--p-anim-*` slots, as an inline style object.
+ *
+ * Inline rather than utilities for the reason the colour slots are: these are
+ * per-instance numbers, and Tailwind cannot generate a class for a duration it
+ * has never seen written down.
+ */
+export function animationSlots(options) {
+    const slots = {
+        '--p-anim-duration': `${options.duration}ms`,
+        '--p-anim-delay': `${options.delay}ms`,
+        '--p-anim-repeat': repeatValue(options.repeat),
+        '--p-anim-direction': directionValue(options.mode ?? 'in', options.alternate)
+    };
+    if (options.easing) {
+        slots['--p-anim-ease'] = options.easing;
+    }
+    if (options.opacity !== undefined) {
+        slots['--p-anim-opacity'] = String(options.opacity);
+    }
+    if (options.scale !== undefined) {
+        slots['--p-anim-scale'] = String(options.scale);
+    }
+    if (options.x !== undefined) {
+        slots['--p-anim-x'] = options.x;
+    }
+    if (options.y !== undefined) {
+        slots['--p-anim-y'] = options.y;
+    }
+    if (options.angle !== undefined) {
+        slots['--p-anim-angle'] = options.angle;
+    }
+    if (options.angleTo !== undefined) {
+        slots['--p-anim-angle-to'] = options.angleTo;
+    }
+    return slots;
+}
+/**
+ * Which way a slide starts, given the edge it comes from.
+ *
+ * `PlassSide` is physical everywhere in the library and it stays physical here:
+ * something arriving from the top of the window arrives from the top in every
+ * writing direction.
+ */
+export function slideOffsets(from, distance) {
+    const length = lengthValue(distance);
+    const negative = typeof distance === 'number' ? `${-distance}px` : `calc(-1 * ${length})`;
+    switch (from) {
+        case 'top':
+            return { x: '0px', y: negative };
+        case 'bottom':
+            return { x: '0px', y: length };
+        case 'left':
+            return { x: negative, y: '0px' };
+        default:
+            return { x: length, y: '0px' };
+    }
+}
+/* ---------------------------------------------------------------------------
+ * Running one
+ * ------------------------------------------------------------------------- */
+/**
+ * Whether the reader has asked for less motion.
+ *
+ * The CSS side of this is handled in the stylesheet, where every keyframe is
+ * switched off at once. This is for the effects whose motion is written in
+ * JavaScript — a typewriter, a headline reel — where there is no rule to switch
+ * off and the component has to decide for itself what "still" means.
+ *
+ * `useSyncExternalStore` rather than state plus an effect: a media query is an
+ * external store, and reading it in an effect means every animated element on
+ * the page renders once with the wrong answer and then again with the right
+ * one. Here that first render is the one that would start a typewriter a reader
+ * asked not to see.
+ */
+const reducedMotionQuery = '(prefers-reduced-motion: reduce)';
+function subscribeToMotion(onChange) {
+    if (typeof window === 'undefined' || !window.matchMedia) {
+        return () => { };
+    }
+    const query = window.matchMedia(reducedMotionQuery);
+    query.addEventListener('change', onChange);
+    return () => query.removeEventListener('change', onChange);
+}
+function readMotion() {
+    return typeof window !== 'undefined' && window.matchMedia
+        ? window.matchMedia(reducedMotionQuery).matches
+        : false;
+}
+/** A server has no reader and so no preference. */
+function motionOnServer() {
+    return false;
+}
+export function usePrefersReducedMotion() {
+    return React.useSyncExternalStore(subscribeToMotion, readMotion, motionOnServer);
+}
+/**
+ * Starts, restarts and holds an animation.
+ *
+ * Two things here are less obvious than they look.
+ *
+ * **Waiting is `animation-play-state: paused`, not a second class.** An element
+ * that has not been triggered yet has to already look like its own first frame,
+ * or a `visible` fade would be fully drawn until it scrolled into view and then
+ * blink out to start. With `fill-mode: both` a paused animation shows exactly
+ * that frame, so waiting and running are one animation in two states rather
+ * than two states to keep in step.
+ *
+ * **Restarting reaches for the DOM.** There is no way to rewind a CSS animation
+ * from React: re-rendering with the same class changes nothing, and a `key`
+ * would restart the animation by unmounting the children, taking their state
+ * with it. Clearing `animation-name`, reading a layout property to force the
+ * style to settle, and putting it back is the one move that rewinds the element
+ * and leaves everything inside it alone.
+ */
+export function useAnimationRun({ trigger, play, once, threshold, paused, infinite }) {
+    const node = React.useRef(null);
+    const [started, setStarted] = React.useState(trigger === 'mount');
+    const [run, setRun] = React.useState(0);
+    const start = React.useCallback(() => {
+        setStarted(true);
+        setRun((previous) => previous + 1);
+    }, []);
+    // Nothing to rewind on the first pass — the element has only just been drawn.
+    React.useLayoutEffect(() => {
+        const element = node.current;
+        if (!element || run === 0) {
+            return;
+        }
+        // The element itself for the effects that animate their own root, and its
+        // descendants for the ones that animate their children instead: a staggered
+        // PlAnimateAppear has nothing to rewind on its own box.
+        const targets = [
+            element,
+            ...element.querySelectorAll('.plass-anim, .plass-marquee-track')
+        ];
+        for (const target of targets) {
+            target.style.animationName = 'none';
+        }
+        void element.offsetWidth;
+        for (const target of targets) {
+            target.style.animationName = '';
+        }
+    }, [run]);
+    React.useEffect(() => {
+        if (trigger !== 'visible') {
+            return;
+        }
+        const element = node.current;
+        if (!element || typeof IntersectionObserver === 'undefined') {
+            // No observer means no way to know: show it rather than hide it forever.
+            setStarted(true);
+            return;
+        }
+        const observer = new IntersectionObserver(([entry]) => {
+            if (entry.isIntersecting) {
+                start();
+                if (once) {
+                    observer.disconnect();
+                }
+            }
+            else if (!once) {
+                setStarted(false);
+            }
+        }, { threshold });
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [trigger, once, threshold, start]);
+    React.useEffect(() => {
+        if (trigger !== 'manual') {
+            return;
+        }
+        // `play` is a caller pressing go, and what it starts is a CSS animation.
+        // There is no external system to push to: the run counter *is* the rewind.
+        if (play) {
+            // eslint-disable-next-line react-hooks/set-state-in-effect
+            start();
+        }
+        else {
+            setStarted(false);
+        }
+    }, [trigger, play, start]);
+    const handlers = trigger === 'hover'
+        ? {
+            onPointerEnter: start,
+            // Focus counts, or an effect on something keyboard-reachable would
+            // never run for a reader who is not holding a mouse.
+            onFocus: start,
+            onPointerLeave: () => {
+                if (infinite) {
+                    setStarted(false);
+                }
+            },
+            onBlur: () => {
+                if (infinite) {
+                    setStarted(false);
+                }
+            }
+        }
+        : {};
+    return {
+        ref: React.useCallback((element) => {
+            node.current = element;
+        }, []),
+        state: started && !paused ? 'running' : 'paused',
+        started,
+        handlers
+    };
+}
+/**
+ * Everything a one-keyframe `PlAnimate*` root needs, in one call.
+ *
+ * The six effect components differ only in their defaults and in which slots
+ * they fill, so this is where the identical two-thirds of each of them lives.
+ * The ones that have to understand their children — Appear, Headline, Marquee,
+ * Typing — call `useAnimationRun` directly and put the classes where their own
+ * structure needs them, which is why `effect` is allowed to be `null`.
+ *
+ * `data-plass-animation` and `data-state` are here rather than in each
+ * component because they are the same two facts every time, and because a test
+ * that has to assert on a class name is a test that breaks when a class name
+ * changes.
+ */
+export function useAnimateElement(params) {
+    const { effect, trigger, play, once, threshold, paused, infinite, ...slots } = params;
+    const run = useAnimationRun({ trigger, play, once, threshold, paused, infinite });
+    return {
+        ref: run.ref,
+        className: effect ? `${animBaseClass} ${animationClasses[effect]}` : '',
+        style: { ...animationSlots(slots), '--p-anim-state': run.state },
+        props: {
+            ...run.handlers,
+            'data-plass-animation': effect ?? undefined,
+            'data-state': run.state
+        }
+    };
+}

package/dist/internal/button-group.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a `PlButton` inherits from the `PlButtonGroup` around it.
+ *
+ * A context rather than `React.Children.map` with `cloneElement`, and a file of
+ * its own rather than something the group exports, for one reason each.
+ *
+ * Cloning breaks the moment a caller wraps one of the buttons in a `PlTooltip`,
+ * a `<Fragment>` or a `.map()` — which is most of the time — and a context
+ * reaches the button wherever it ended up. And it lives here rather than beside
+ * the group so that `PlButton` can read it without the two components importing
+ * each other, which is the arrangement `internal/menu.ts` already has.
+ *
+ * Every field is optional, and every one of them means *not specified* rather
+ * than a value: a button falls back to its own default, so a `PlButtonGroup`
+ * with no props of its own changes nothing except the corners.
+ */
+import * as React from 'react';
+import type { PlassColor, PlassDensity, PlassElevation, PlassSize, PlassVariant } from '../types.js';
+export interface PlassButtonGroupContextValue {
+    variant?: PlassVariant;
+    size?: PlassSize;
+    color?: PlassColor;
+    density?: PlassDensity;
+    elevation?: PlassElevation;
+    disabled?: boolean;
+}
+export declare const ButtonGroupContext: React.Context<PlassButtonGroupContextValue | null>;

package/dist/internal/button-group.js

@@ -0,0 +1,19 @@
+/**
+ * What a `PlButton` inherits from the `PlButtonGroup` around it.
+ *
+ * A context rather than `React.Children.map` with `cloneElement`, and a file of
+ * its own rather than something the group exports, for one reason each.
+ *
+ * Cloning breaks the moment a caller wraps one of the buttons in a `PlTooltip`,
+ * a `<Fragment>` or a `.map()` — which is most of the time — and a context
+ * reaches the button wherever it ended up. And it lives here rather than beside
+ * the group so that `PlButton` can read it without the two components importing
+ * each other, which is the arrangement `internal/menu.ts` already has.
+ *
+ * Every field is optional, and every one of them means *not specified* rather
+ * than a value: a button falls back to its own default, so a `PlButtonGroup`
+ * with no props of its own changes nothing except the corners.
+ */
+import * as React from 'react';
+export const ButtonGroupContext = 
+/* @__PURE__ */ React.createContext(null);

package/dist/internal/calendar.d.ts

@@ -0,0 +1,148 @@
+import * as React from 'react';
+import { type TimeUnit } from './date.js';
+import type { PlassColor, PlassDensity, PlassSize, PlassWeekday } from '../types.js';
+/**
+ * The calendar grid and the clock columns, written once for the four pickers.
+ *
+ * They live in `internal/` for the reason `button-group.ts` does: a
+ * `PlDateTimePicker` is a date picker and a time picker in one popup and a
+ * `PlDateRangePicker` is two calendars, so three components need this and none
+ * of them should have to import another. The one thing it reaches *up* for is
+ * `PlButton` — the header's steppers are buttons, they are not a new kind of
+ * control, and `PlPagination` already makes that argument.
+ *
+ * The day cells are deliberately **not** `PlButton`s. A cell has states a
+ * button has no vocabulary for — inside a range, at the end of a range, today,
+ * belonging to the month next door — and four of them have to be told apart at
+ * a glance in a grid of forty-two.
+ */
+/**
+ * Every string a picker says that is not a date.
+ *
+ * One object rather than eighteen props. These are a set: a caller who has to
+ * translate "Previous month" has to translate "Next month" in the same breath,
+ * and a component with eighteen `*Label` props is a component whose signature is
+ * mostly apology. The dates themselves are never in here — those come from
+ * `Intl`, which already knows what July is called in more languages than this
+ * file ever will.
+ */
+export interface PlassPickerLabels {
+    /** The calendar's steppers, in day view. */
+    previousMonth: string;
+    nextMonth: string;
+    /** The same steppers in month view, where they move by a year. */
+    previousYear: string;
+    nextYear: string;
+    /** And in year view, where they move by a page of twelve. */
+    previousYears: string;
+    nextYears: string;
+    /** The two header buttons that open the month grid and the year grid. */
+    chooseMonth: string;
+    chooseYear: string;
+    /** The footer's actions. */
+    today: string;
+    now: string;
+    clear: string;
+    done: string;
+    /** The clock's columns. */
+    hour: string;
+    minute: string;
+    second: string;
+    meridiem: string;
+    /** Which end of a range the calendar is currently asking for. */
+    start: string;
+    end: string;
+}
+export declare const defaultPickerLabels: PlassPickerLabels;
+/** Merges a caller's overrides over the defaults, once per render. */
+export declare function usePickerLabels(overrides?: Partial<PlassPickerLabels>): PlassPickerLabels;
+export interface CalendarProps {
+    size: PlassSize;
+    color: PlassColor;
+    locale?: string;
+    weekStartsOn: PlassWeekday;
+    /** The month on screen. Controlled, so two panels can be kept a month apart. */
+    month: Date;
+    onMonthChange: (month: Date) => void;
+    /** The days drawn filled — one for a single picker, up to two for a range. */
+    selected: readonly (Date | null | undefined)[];
+    /** The two ends the band is drawn between. Both `null` outside range mode. */
+    rangeStart?: Date | null;
+    rangeEnd?: Date | null;
+    onSelect: (date: Date) => void;
+    /** The day under the pointer, for a range that is only half chosen. */
+    onPreviewChange?: (date: Date | null) => void;
+    minDate?: Date | null;
+    maxDate?: Date | null;
+    shouldDisableDate?: (date: Date) => boolean;
+    /**
+     * Draws the leading and trailing days that belong to the neighbouring months.
+     *
+     * On by default, because clicking the 1st of next month from this month's
+     * panel is a real shortcut. A two-month range picker turns it *off*, and not
+     * as a matter of taste: with both panels showing six full weeks, the 1st of
+     * August appears twice — once as a trailing day of July and once as itself —
+     * and two cells with the same name in the same popup is ambiguous to a
+     * pointer and outright broken to a screen reader.
+     * @default true
+     */
+    showOutsideDays?: boolean;
+    /** Takes the focus on mount — the popup has just opened. */
+    autoFocus?: boolean;
+    showPreviousButton?: boolean;
+    showNextButton?: boolean;
+    labels: PlassPickerLabels;
+    className?: string;
+}
+/**
+ * One month, with a way to reach every other one.
+ *
+ * Three views on the same footprint: the days of a month, the twelve months of
+ * a year, twelve years at a time. They are deliberately the same width *and*
+ * the same height — the day view is seven rows counting its header, and the
+ * other two stretch four rows and three rows across that same height — so
+ * switching view never resizes the popup under the pointer that opened it.
+ *
+ * Arrow keys move by one cell, `PageUp`/`PageDown` by a month (a year with
+ * Shift), `Home`/`End` to the ends of the week, and running off an edge steps
+ * the calendar rather than stopping. One roving tab stop, so `Tab` leaves the
+ * grid instead of walking forty-two cells — the pattern the ARIA date-picker
+ * practice describes, and the reason none of the cells is a `disabled` button.
+ */
+export declare function Calendar({ size, color, locale, weekStartsOn, month, onMonthChange, selected, rangeStart, rangeEnd, onSelect, onPreviewChange, minDate, maxDate, shouldDisableDate, showOutsideDays, autoFocus, showPreviousButton, showNextButton, labels, className }: CalendarProps): React.JSX.Element;
+export type { TimeUnit };
+export interface TimeGridProps {
+    size: PlassSize;
+    density: PlassDensity;
+    locale?: string;
+    /** The time on screen, or `null` while nothing has been chosen. */
+    value: Date | null;
+    /** The day the columns write into while `value` is still `null`. */
+    referenceDate: Date;
+    onChange: (value: Date) => void;
+    /** A 12-hour dial with an AM/PM column. Defaults to whatever the locale does. */
+    hour12: boolean;
+    showSeconds: boolean;
+    hourStep: number;
+    minuteStep: number;
+    secondStep: number;
+    shouldDisableTime?: (value: Date, unit: TimeUnit) => boolean;
+    /** Takes the focus on mount — the popup has just opened. */
+    autoFocus?: boolean;
+    labels: PlassPickerLabels;
+    className?: string;
+}
+/**
+ * Hours, minutes and — when asked for — seconds, as columns you scroll rather
+ * than as a dial you drag.
+ *
+ * Columns because they are the shape that answers what a time picker is actually
+ * asked: "half past nine" is two glances, and "any time at all, on the hour" is
+ * a column you never touch. A clock face is prettier and needs a `transform` to
+ * read, which this library does not have.
+ *
+ * The chosen row in each column is scrolled into view once, on open. That is the
+ * only imperative work here and it is not optional: a column of sixty minutes
+ * that opens at `00` while the value is `45` has hidden its own answer.
+ */
+export declare function TimeGrid({ size, density, locale, value, referenceDate, onChange, hour12, showSeconds, hourStep, minuteStep, secondStep, shouldDisableTime, autoFocus, labels, className }: TimeGridProps): React.JSX.Element;