plass-ui 0.0.1 → 1.0.0

package/dist/components/scroll-zone/PlScrollZone.js

@@ -0,0 +1,411 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { PlIconButton } from '../icon-button/PlIconButton.js';
+import { spacingValue } from '../../internal/grid.js';
+import { ChevronIcon } from '../../internal/icons.js';
+import { cx } from '../../internal/styles.js';
+/**
+ * How far the buttons sit in from the edge they are held against.
+ *
+ * Padding on the overlay rather than an inset on each button, so the two are
+ * written once and a zone with only one of them drawn keeps the other's
+ * position.
+ */
+const buttonInsetClasses = {
+    xs: 'p-1',
+    sm: 'p-1.5',
+    md: 'p-2',
+    lg: 'p-3',
+    xl: 'p-4'
+};
+/** And the air between an inline button and the strip it flanks. */
+const buttonGapClasses = {
+    xs: 'gap-1',
+    sm: 'gap-1.5',
+    md: 'gap-2',
+    lg: 'gap-3',
+    xl: 'gap-4'
+};
+/** How far a press has to travel before it stops being a click. */
+const DRAG_THRESHOLD = 4;
+/** Under this, a press in `hold` mode was a tap and moves one item instead. */
+const TAP_MS = 140;
+/** A reader who has asked for less motion gets the cut rather than the travel. */
+function scrollBehavior() {
+    return typeof window !== 'undefined' &&
+        window.matchMedia?.('(prefers-reduced-motion: reduce)').matches
+        ? 'auto'
+        : 'smooth';
+}
+/**
+ * A strip of anything, laid out in one direction and scrolled in it.
+ *
+ * The mechanism is an ordinary scroll container, and everything the component
+ * offers is a way of driving one. Swiping on a phone, two-finger dragging on a
+ * trackpad, the wheel, the arrow keys and the scrollbar are the browser's own
+ * and are never intercepted; what is added on top is a pair of buttons for the
+ * pointer that has neither a wheel nor a finger, and a mouse drag for the strip
+ * that reads as something to pull rather than something to page.
+ *
+ * Nothing is transformed. A translated track would have to argue for an
+ * exception to the house rule; a scroll offset does not, and it is also what
+ * makes the strip run the other way under RTL without being told, keeps the
+ * scrollbar honest, and lets the browser scroll a focused child into view.
+ *
+ * It draws no sheet of its own, and there is no `elevation` to give it one: a
+ * shelf is a way of laying children out, and the children arrive with their own
+ * surfaces. `variant`, `size`, `color` and `density` reach the two buttons,
+ * which are real `PlIconButton`s.
+ *
+ * `lines` is what separates this from a `PlCarousel`: a carousel is one thing at
+ * a time and knows which one, a scroll zone is a shelf that happens to be longer
+ * than the room it is in.
+ */
+export const PlScrollZone = /* @__PURE__ */ React.forwardRef(function PlScrollZone({ orientation = 'horizontal', lines = 1, spacing = 2, buttons = 'auto', buttonPlacement = 'overlay', mode = 'item', step = 1, speed = 900, snap = false, drag = true, scrollbar = false, variant = 'glass', size = 'md', color = 'primary', density = 'default', label, previousLabel = 'Previous', nextLabel = 'Next', className, style, children, ...props }, ref) {
+    const horizontal = orientation === 'horizontal';
+    const rows = Math.max(1, Math.round(lines));
+    const items = Math.max(1, Math.round(step));
+    const scrollerRef = React.useRef(null);
+    const trackRef = React.useRef(null);
+    /**
+     * Whether there is anything left in each direction, as one object so a
+     * measurement that changed nothing costs no render.
+     */
+    const [reach, setReach] = React.useState({ back: false, forward: false });
+    const measure = React.useCallback(() => {
+        const element = scrollerRef.current;
+        if (!element) {
+            return;
+        }
+        const extent = horizontal ? element.clientWidth : element.clientHeight;
+        const total = horizontal ? element.scrollWidth : element.scrollHeight;
+        // `abs`, because a right-to-left container counts its scroll backwards
+        // from zero. How far along we are is a distance either way.
+        const along = Math.abs(horizontal ? element.scrollLeft : element.scrollTop);
+        setReach((previous) => {
+            const back = along > 1;
+            const forward = total - extent - along > 1;
+            return previous.back === back && previous.forward === forward
+                ? previous
+                : { back, forward };
+        });
+    }, [horizontal]);
+    /*
+     * Three things change what the buttons should say, and only one of them is
+     * an event: the strip being scrolled, the zone being resized, and the
+     * content inside it changing size. The observer covers the last two —
+     * including the case that matters most, a zone that mounts inside a closed
+     * `PlAccordion` or an unselected `PlTab` and is zero wide until it is
+     * opened.
+     */
+    React.useEffect(() => {
+        const element = scrollerRef.current;
+        const track = trackRef.current;
+        if (!element) {
+            return;
+        }
+        measure();
+        if (typeof ResizeObserver === 'undefined') {
+            return;
+        }
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        if (track) {
+            observer.observe(track);
+        }
+        return () => observer.disconnect();
+    }, [measure]);
+    /** Which way "forward" is on the physical axis: flipped under RTL. */
+    const forwardSign = React.useCallback(() => {
+        const element = scrollerRef.current;
+        if (!element || !horizontal) {
+            return 1;
+        }
+        return getComputedStyle(element).direction === 'rtl' ? -1 : 1;
+    }, [horizontal]);
+    const scrollByPixels = React.useCallback((distance, smooth) => {
+        const element = scrollerRef.current;
+        if (!element) {
+            return;
+        }
+        const behavior = smooth ? scrollBehavior() : 'auto';
+        element.scrollBy(horizontal ? { left: distance, behavior } : { top: distance, behavior });
+    }, [horizontal]);
+    /**
+     * Where each child starts, measured from the leading edge of the viewport
+     * and signed so that ahead is positive in both writing directions.
+     *
+     * Distinct offsets rather than one per child, which is what makes `lines`
+     * work: four children stacked two by two are two columns, and pressing next
+     * once should move one column rather than half of one.
+     */
+    const itemStarts = React.useCallback(() => {
+        const element = scrollerRef.current;
+        const track = trackRef.current;
+        if (!element || !track) {
+            return [];
+        }
+        const rtl = horizontal && getComputedStyle(element).direction === 'rtl';
+        const edge = horizontal ? (rtl ? 'right' : 'left') : 'top';
+        const sign = rtl ? -1 : 1;
+        const origin = element.getBoundingClientRect()[edge];
+        const starts = [];
+        for (const child of Array.from(track.children)) {
+            const start = Math.round((child.getBoundingClientRect()[edge] - origin) * sign);
+            if (!starts.includes(start)) {
+                starts.push(start);
+            }
+        }
+        return starts.sort((a, b) => a - b);
+    }, [horizontal]);
+    /** One press, in whichever unit `mode` is counted in. */
+    const advance = React.useCallback((forward, unit = mode) => {
+        const element = scrollerRef.current;
+        if (!element) {
+            return;
+        }
+        const sign = forwardSign();
+        const extent = horizontal ? element.clientWidth : element.clientHeight;
+        if (unit === 'page') {
+            scrollByPixels(extent * (forward ? 1 : -1) * sign, true);
+            return;
+        }
+        // An item, and it is measured rather than assumed: the children of a
+        // scroll zone are whatever the caller put there, so no two of them are
+        // necessarily the same width.
+        const starts = itemStarts();
+        const ahead = starts.filter((start) => start > 1);
+        const behind = starts.filter((start) => start < -1);
+        const target = forward ? ahead[items - 1] : behind[behind.length - items];
+        if (target === undefined) {
+            // Nothing that far along: go as far as there is. Without this, the
+            // last half-item of a strip would be unreachable by button.
+            scrollByPixels(extent * (forward ? 1 : -1) * sign, true);
+            return;
+        }
+        scrollByPixels(target * sign, true);
+    }, [forwardSign, horizontal, itemStarts, items, mode, scrollByPixels]);
+    /*
+     * `hold` — a frame loop rather than an interval, so the strip moves at
+     * `speed` pixels a second whatever the display is doing. The whole gesture
+     * is torn down through one ref, because the `pointerup` that would normally
+     * end it never arrives if the zone is unmounted mid-press.
+     */
+    const holdRef = React.useRef(null);
+    React.useEffect(() => () => holdRef.current?.(), []);
+    const beginHold = React.useCallback((forward, stop) => {
+        if (holdRef.current) {
+            return;
+        }
+        const sign = forwardSign();
+        const started = performance.now();
+        let previous = started;
+        let frame = 0;
+        const tick = (now) => {
+            const elapsed = now - previous;
+            previous = now;
+            scrollByPixels(((speed * elapsed) / 1000) * (forward ? 1 : -1) * sign, false);
+            frame = requestAnimationFrame(tick);
+        };
+        frame = requestAnimationFrame(tick);
+        const release = () => {
+            cancelAnimationFrame(frame);
+            holdRef.current = null;
+            window.removeEventListener(stop, release);
+            window.removeEventListener('pointercancel', release);
+            // A press released outside the browser window throws neither of the
+            // two above, and a frame loop nobody can stop is the worst kind.
+            window.removeEventListener('blur', release);
+            // A press shorter than a hold was a click, and a click that scrolled
+            // three pixels reads as a broken button.
+            if (performance.now() - started < TAP_MS) {
+                advance(forward, 'item');
+            }
+        };
+        holdRef.current = release;
+        window.addEventListener(stop, release);
+        window.addEventListener('pointercancel', release);
+        window.addEventListener('blur', release);
+    }, [advance, forwardSign, scrollByPixels, speed]);
+    /*
+     * Dragging. Mouse and pen only — a finger already scrolls, and the browser's
+     * own scrolling has momentum, rubber-banding and a scrollbar that no handler
+     * reproduces.
+     */
+    const dragRef = React.useRef(null);
+    React.useEffect(() => () => dragRef.current?.(), []);
+    function beginDrag(event) {
+        if (!drag || event.pointerType === 'touch' || event.button !== 0) {
+            return;
+        }
+        // A press released outside the page never reaches the listeners below, so
+        // the drag before this one is torn down here rather than never.
+        dragRef.current?.();
+        const element = event.currentTarget;
+        const fromX = event.clientX;
+        const fromY = event.clientY;
+        const fromLeft = element.scrollLeft;
+        const fromTop = element.scrollTop;
+        let dragging = false;
+        // Taken off the document for the length of the drag rather than fixed
+        // with `preventDefault`, which would also stop the browser focusing what
+        // was pressed. Written prefixed and through `setProperty` because WebKit
+        // implements only `-webkit-user-select`.
+        const selection = document.body.style.getPropertyValue('-webkit-user-select');
+        const move = (moveEvent) => {
+            const dx = moveEvent.clientX - fromX;
+            const dy = moveEvent.clientY - fromY;
+            if (!dragging) {
+                if (Math.abs(horizontal ? dx : dy) < DRAG_THRESHOLD) {
+                    return;
+                }
+                dragging = true;
+                element.setPointerCapture(moveEvent.pointerId);
+                element.dataset.dragging = 'true';
+                document.body.style.setProperty('-webkit-user-select', 'none');
+            }
+            if (horizontal) {
+                element.scrollLeft = fromLeft - dx;
+            }
+            else {
+                element.scrollTop = fromTop - dy;
+            }
+        };
+        const release = () => {
+            dragRef.current = null;
+            element.removeEventListener('pointermove', move);
+            element.removeEventListener('pointerup', end);
+            element.removeEventListener('pointercancel', release);
+            delete element.dataset.dragging;
+            if (selection) {
+                document.body.style.setProperty('-webkit-user-select', selection);
+            }
+            else {
+                document.body.style.removeProperty('-webkit-user-select');
+            }
+        };
+        const end = () => {
+            const moved = dragging;
+            release();
+            if (!moved) {
+                return;
+            }
+            // The `pointerup` that ends a drag is still followed by a click, and
+            // that click lands on whatever card the strip happened to stop under.
+            // It is swallowed on the way down, and the listener is dropped on the
+            // next task in case no click was coming.
+            const swallow = (clickEvent) => {
+                clickEvent.stopPropagation();
+                clickEvent.preventDefault();
+            };
+            element.addEventListener('click', swallow, { capture: true, once: true });
+            window.setTimeout(() => element.removeEventListener('click', swallow, true), 0);
+        };
+        dragRef.current = release;
+        element.addEventListener('pointermove', move);
+        element.addEventListener('pointerup', end);
+        element.addEventListener('pointercancel', release);
+    }
+    function pressHandlers(forward) {
+        if (mode !== 'hold') {
+            return { onClick: () => advance(forward) };
+        }
+        return {
+            onPointerDown: (event) => {
+                if (event.button !== 0) {
+                    return;
+                }
+                beginHold(forward, 'pointerup');
+            },
+            // The keyboard's own half of a hold. Without it the button is a control
+            // a pointer can use and a keyboard cannot, which is the one thing a
+            // scroll affordance must never be.
+            onKeyDown: (event) => {
+                if (event.key !== 'Enter' && event.key !== ' ') {
+                    return;
+                }
+                event.preventDefault();
+                beginHold(forward, 'keyup');
+            }
+        };
+    }
+    const drawn = buttons !== 'none' && (buttons === 'always' || reach.back || reach.forward);
+    const inline = buttonPlacement === 'inline';
+    function scrollButton(forward) {
+        const available = forward ? reach.forward : reach.back;
+        // An overlay button with nowhere to go is not drawn at all; an inline one
+        // leaves its lane behind, because a lane that came and went would resize
+        // the strip under the pointer that had just reached the end of it.
+        // `inert` rather than `hidden`, so the space is kept and the button is out
+        // of the tab order and out of the accessibility tree while it is
+        // invisible.
+        if (buttons === 'auto' && !available && !inline) {
+            return _jsx("span", {});
+        }
+        const turn = horizontal
+            ? forward
+                ? '-rotate-90 rtl:rotate-90'
+                : 'rotate-90 rtl:-rotate-90'
+            : forward
+                ? ''
+                : 'rotate-180';
+        const spare = buttons === 'auto' && !available;
+        const button = (_jsx(PlIconButton, { variant: variant, size: size, color: color, density: density, elevation: 1, label: forward ? nextLabel : previousLabel, disabled: !available, className: "pointer-events-auto", 
+            // Drawn pointing down and turned, which is the one allowance the
+            // no-transform rule makes.
+            icon: _jsx("span", { className: cx('flex items-center', turn), children: _jsx(ChevronIcon, {}) }), ...pressHandlers(forward) }));
+        if (!inline) {
+            return button;
+        }
+        return (_jsx("span", { className: cx('flex shrink-0 items-center justify-center', spare ? 'invisible' : ''), inert: spare, children: button }));
+    }
+    return (_jsxs("div", { ref: ref, 
+        // A flex column, so a zone that was given a height passes it to the
+        // scroller: a vertical strip only scrolls if something bounds it, and
+        // the thing a caller sizes is the component rather than the box inside
+        // it.
+        className: cx('relative flex min-w-0', inline && horizontal ? 'flex-row items-stretch' : 'flex-col', inline ? buttonGapClasses[size] : '', className), 
+        // One slot rather than the whole set: a scroll zone draws no sheet, so
+        // the family only ever shows up in the focus ring the scroller takes.
+        // The buttons are real `PlIconButton`s and carry their own.
+        style: { '--p-ring': `var(--plass-${color}-ring)`, ...style }, ...props, children: [drawn && inline ? scrollButton(false) : null, _jsx("div", { ref: scrollerRef, 
+                // Focusable, so the strip can be scrolled with the arrow keys by
+                // whoever is not using a pointer. That is the browser's own key
+                // handling on a scroll container, which means it is already right
+                // under RTL — a handler of ours mapping ArrowRight to "forward" would
+                // not have been.
+                tabIndex: 0, role: label ? 'group' : undefined, "aria-label": label, className: cx(
+                // `grow` with the basis left at `auto`, never `flex-1`: a zero basis
+                // in a column whose own height is `auto` resolves to no height at
+                // all, and a horizontal strip would come out flat.
+                'min-h-0 min-w-0 grow', horizontal ? 'overflow-x-auto overflow-y-hidden' : 'overflow-y-auto overflow-x-hidden', snap ? (horizontal ? 'snap-x snap-mandatory' : 'snap-y snap-mandatory') : '', scrollbar ? '' : '[scrollbar-width:none] [&::-webkit-scrollbar]:hidden', drag && (reach.back || reach.forward)
+                    ? 'cursor-grab data-[dragging]:cursor-grabbing'
+                    : '', 'focus-visible:[outline:2px_solid_var(--p-ring)] focus-visible:[outline-offset:-2px]'), onScroll: measure, onPointerDown: beginDrag, children: _jsx("div", { ref: trackRef, className: cx(snap ? '[&>*]:snap-start' : ''), 
+                    // The whole track is laid out inline rather than in utilities, for
+                    // the reason `internal/grid.ts` gives: `repeat(3, auto)` is a count
+                    // the caller picked and Tailwind only ever sees class names written
+                    // out literally. Half of the declaration in a class and half of it
+                    // here would be two places to read one layout.
+                    //
+                    // A grid rather than a flex row, because `lines` is exactly the
+                    // thing flex cannot state: a wrapping row wraps at the viewport, and
+                    // what is wanted here is a fixed number of rows and as many columns
+                    // as it takes.
+                    style: {
+                        display: 'grid',
+                        gap: spacingValue(spacing),
+                        gridAutoFlow: horizontal ? 'column' : 'row',
+                        ...(horizontal
+                            ? {
+                                // `max-content`, or the track would be squeezed back to the
+                                // width of the box it is supposed to be longer than.
+                                width: 'max-content',
+                                gridTemplateRows: `repeat(${rows}, auto)`,
+                                gridAutoColumns: 'max-content'
+                            }
+                            : {
+                                gridTemplateColumns: `repeat(${rows}, minmax(0, 1fr))`,
+                                gridAutoRows: 'max-content'
+                            })
+                    }, children: children }) }), drawn && inline ? scrollButton(true) : null, drawn && !inline ? (_jsxs("div", { className: cx('pointer-events-none absolute inset-0 flex justify-between', horizontal ? 'items-center' : 'flex-col items-center', buttonInsetClasses[size]), children: [scrollButton(false), scrollButton(true)] })) : null] }));
+});

package/dist/components/scroll-zone/index.d.ts

@@ -0,0 +1,2 @@
+export { PlScrollZone } from './PlScrollZone.js';
+export type { PlScrollZoneButtonPlacement, PlScrollZoneButtons, PlScrollZoneMode, PlScrollZoneProps } from './PlScrollZone.js';

package/dist/components/scroll-zone/index.js

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

package/dist/components/segmented-button/PlSegmentedButton.d.ts

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import type { PlassElevation, PlassStyleProps, PlassVariant } from '../../types.js';
+/** A segment's value. The same restraint `PlSelect` puts on its own. */
+export type PlSegmentValue = string | number;
+export interface PlSegmentedButtonProps extends Omit<PlassStyleProps, 'variant'>, Omit<React.ComponentPropsWithoutRef<'div'>, 'color' | 'defaultValue' | 'onChange'> {
+    /**
+     * What the groove and the tile riding in it are made of.
+     *
+     * - `solid` — a groove cut into the sheet with a **tinted-glass key** riding
+     *   in it. The loudest, and the one for a control a screen is about to be
+     *   steered by.
+     * - `glass` — the same groove with a hairline round it and a clear tile
+     *   rather than a coloured one. The default.
+     * - `ghost` — no groove at all: the segments sit straight on the page and only
+     *   the chosen one has a surface.
+     * @default 'glass'
+     */
+    variant?: PlassVariant;
+    /** The chosen segment. Use with `onValueChange` for a controlled set. */
+    value?: PlSegmentValue | null;
+    /** Which starts chosen, for an uncontrolled set. */
+    defaultValue?: PlSegmentValue | null;
+    onValueChange?: (value: PlSegmentValue | null) => void;
+    /**
+     * Drop shadow depth of the groove. `0` is the default — a groove is cut into
+     * the page, not laid on it.
+     * @default 0
+     */
+    elevation?: PlassElevation;
+    /** Disables every segment at once. */
+    disabled?: boolean;
+    /** Shows which one is chosen but does not let it be changed. */
+    readOnly?: boolean;
+    /** Identifies the value when a form is submitted. */
+    name?: string;
+    /** The segments share the full width, each taking an equal part of it. */
+    fullWidth?: boolean;
+    children?: React.ReactNode;
+}
+export interface PlSegmentProps extends Omit<React.ComponentPropsWithoutRef<'span'>, 'value' | 'color'> {
+    /** Identifies the segment. What `onValueChange` reports. */
+    value: PlSegmentValue;
+    /** Content before the label. Sized in `em`, so it tracks the label. */
+    startIcon?: React.ReactNode;
+    /** Content after the label — a count, a status dot. */
+    endIcon?: React.ReactNode;
+    /** Unavailable, but still part of the set. */
+    disabled?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * One choice in a segmented button.
+ *
+ * It has no `size`, no `color` and no `variant` of its own: all three belong to
+ * the set, which is the only place they can be set once and mean the same thing
+ * for every segment.
+ */
+export declare const PlSegment: React.ForwardRefExoticComponent<PlSegmentProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Two or more choices in one pill, exactly one of them taken.
+ *
+ * Underneath it is a radio group, and that is the whole accessibility argument:
+ * a segmented button *is* "exactly one of these", so it gets
+ * `role="radiogroup"`, one tab stop for the set, arrow keys within it, and
+ * `aria-checked` on the one that is taken. Building it out of `aria-pressed`
+ * toggles — which is what a row of buttons would give — would announce four
+ * independent switches, three of which happen to be off.
+ *
+ * The tile slides because its `left`, `top`, `width` and `height` are measured
+ * off the chosen segment and animated. Nothing is transformed: the tile is an
+ * empty box, and no label is resampled while it travels. That is what lets the
+ * house no-transform rule survive a component whose entire point is that
+ * something moves.
+ *
+ * `left`, not `inset-inline-start`: `offsetLeft` is a distance from the left
+ * edge and stays one under RTL, and pairing a physical measurement with a
+ * logical property is what would break the direction.
+ */
+export declare const PlSegmentedButton: React.ForwardRefExoticComponent<PlSegmentedButtonProps & React.RefAttributes<HTMLDivElement>>;