panelui-web 0.0.0-stage → 0.1.0

package/dist/components/day-grid/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * DayGrid — a run of days as a field of dots, each sized by how much happened
+ * on it.
+ *
+ * ```tsx
+ * <DayGrid cells={days} columns={7} />
+ * <DayGrid.Legend />
+ * ```
+ *
+ * ## Size carries the amount, not only shade
+ *
+ * A day is level 0 to 4, and its dot grows with the level: a speck for a day
+ * with nothing on it, a full disc for the busiest. The period reads the way a
+ * halftone print does, heavy where a lot happened and thin where little did,
+ * and it still reads for someone who cannot tell two shades of one colour
+ * apart.
+ *
+ * ## The pointer is a lens
+ *
+ * Dots swell as the pointer comes near and settle as it leaves, so the day
+ * under the pointer is the largest thing on the grid and its neighbours lean
+ * towards it. The day's `label` is shown in a tag above it. The lens changes
+ * nothing about what the grid says; it is there to make one day easy to
+ * single out among forty.
+ *
+ * ## Days you can ask about
+ *
+ * Pass `onValueChange` and each day becomes a button. The grid then behaves as
+ * one control to the keyboard: a single Tab stop, with the arrow keys moving
+ * between days, so forty days are not forty presses of Tab.
+ */
+import { type ComponentProps, type ReactNode } from 'react';
+/** How much happened on a day: 0 is nothing, 4 is the most. */
+export type DayLevel = 0 | 1 | 2 | 3 | 4;
+/** Which of the theme's roles the dots are drawn in. */
+export type DayGridColor = 'primary' | 'info' | 'success' | 'warning' | 'destructive';
+export interface DayCell {
+    level: DayLevel;
+    /** What the day is, for the tag and a screen reader: "14 May, 6 commits". */
+    label?: string;
+}
+export interface DayGridProps extends Omit<ComponentProps<'div'>, 'children' | 'onChange' | 'color'> {
+    /** The days, in order. They fill the grid row by row. */
+    cells: DayCell[];
+    /** Cells per row. Seven makes each row a week. */
+    columns?: number;
+    /**
+     * Cells per column. Giving this fills the grid column by column, and
+     * `columns` is ignored. Seven makes each column a week, which lays a long
+     * period out wide and short.
+     */
+    rows?: number;
+    /** Which of the theme's roles the dots are drawn in. */
+    color?: DayGridColor;
+    /** The index of the selected day, when the caller holds it. */
+    value?: number | null;
+    /**
+     * Called with the index of a day when it is pressed. Passing this makes the
+     * days buttons; without it the grid is a picture.
+     */
+    onValueChange?: (index: number) => void;
+    /** Set to `false` for dots that hold still under the pointer. */
+    lens?: boolean;
+    /** What a screen reader calls the grid. */
+    label?: string;
+}
+declare function DayGridRoot({ cells, columns, rows: perColumn, color, value, onValueChange, lens, label, className, style, onPointerMove, onPointerLeave, ...props }: DayGridProps): import("react").JSX.Element;
+declare namespace DayGridRoot {
+    var displayName: string;
+}
+export interface DayGridLegendProps extends Omit<ComponentProps<'div'>, 'children' | 'color'> {
+    /** The same role the grid is drawn in. */
+    color?: DayGridColor;
+    /** The word at the quiet end of the scale. */
+    less?: ReactNode;
+    /** The word at the busy end of the scale. */
+    more?: ReactNode;
+}
+/** The five sizes, quietest to busiest, with a word at each end. */
+declare function DayGridLegend({ color, less, more, className, ...props }: DayGridLegendProps): import("react").JSX.Element;
+declare namespace DayGridLegend {
+    var displayName: string;
+}
+export declare const DayGrid: typeof DayGridRoot & {
+    Legend: typeof DayGridLegend;
+};
+export { DayGridLegend };

package/dist/components/day-grid/index.js

@@ -0,0 +1,251 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * DayGrid — a run of days as a field of dots, each sized by how much happened
+ * on it.
+ *
+ * ```tsx
+ * <DayGrid cells={days} columns={7} />
+ * <DayGrid.Legend />
+ * ```
+ *
+ * ## Size carries the amount, not only shade
+ *
+ * A day is level 0 to 4, and its dot grows with the level: a speck for a day
+ * with nothing on it, a full disc for the busiest. The period reads the way a
+ * halftone print does, heavy where a lot happened and thin where little did,
+ * and it still reads for someone who cannot tell two shades of one colour
+ * apart.
+ *
+ * ## The pointer is a lens
+ *
+ * Dots swell as the pointer comes near and settle as it leaves, so the day
+ * under the pointer is the largest thing on the grid and its neighbours lean
+ * towards it. The day's `label` is shown in a tag above it. The lens changes
+ * nothing about what the grid says; it is there to make one day easy to
+ * single out among forty.
+ *
+ * ## Days you can ask about
+ *
+ * Pass `onValueChange` and each day becomes a button. The grid then behaves as
+ * one control to the keyboard: a single Tab stop, with the arrow keys moving
+ * between days, so forty days are not forty presses of Tab.
+ */
+import { useEffect, useMemo, useRef, useState, } from 'react';
+import { tv } from 'tailwind-variants';
+const dayGridVariants = tv({
+    slots: {
+        root: 'relative grid w-full gap-1',
+        // The cell is the target and keeps its size. Only the dot inside it grows.
+        cell: 'relative flex aspect-square w-full items-center justify-center rounded-full outline-none',
+        /*
+         * One scale made of three parts: how big the level is, how near the
+         * pointer is, and whether the grid has arrived yet. Kept as variables so
+         * each can change without a class changing.
+         */
+        dot: 'block size-full rounded-full [scale:calc(var(--pu-size)*(1+var(--pu-lens,0)*0.5)*var(--pu-in,1))] transition-[scale,box-shadow] duration-200 ease-[cubic-bezier(0.34,1.56,0.64,1)] motion-reduce:transition-none',
+        tag: 'pointer-events-none absolute z-20 whitespace-nowrap rounded-lg bg-foreground px-2 py-1 text-xs font-medium text-background shadow-lg',
+        legend: 'flex items-center gap-1.5 text-xs text-muted-foreground',
+        swatch: 'flex size-4 items-center justify-center',
+    },
+    variants: {
+        /*
+         * The colour is written to one variable and every dot reads it. The legend
+         * is a sibling of the grid, not a child, so it takes the same variant.
+         */
+        color: {
+            primary: { root: '[--pu-color:var(--primary)]', legend: '[--pu-color:var(--primary)]' },
+            info: { root: '[--pu-color:var(--info)]', legend: '[--pu-color:var(--info)]' },
+            success: { root: '[--pu-color:var(--success)]', legend: '[--pu-color:var(--success)]' },
+            warning: { root: '[--pu-color:var(--warning)]', legend: '[--pu-color:var(--warning)]' },
+            destructive: {
+                root: '[--pu-color:var(--destructive)]',
+                legend: '[--pu-color:var(--destructive)]',
+            },
+        },
+        level: {
+            0: { dot: 'bg-muted-foreground/30 [--pu-size:0.2]' },
+            1: { dot: 'bg-[color-mix(in_oklab,var(--pu-color)_45%,transparent)] [--pu-size:0.42]' },
+            2: { dot: 'bg-[color-mix(in_oklab,var(--pu-color)_65%,transparent)] [--pu-size:0.6]' },
+            3: { dot: 'bg-[color-mix(in_oklab,var(--pu-color)_85%,transparent)] [--pu-size:0.8]' },
+            // The busiest days carry a little light of their own.
+            4: {
+                dot: 'bg-[var(--pu-color)] shadow-[0_0_14px_color-mix(in_oklab,var(--pu-color)_45%,transparent)] [--pu-size:1]',
+            },
+        },
+        interactive: {
+            true: {
+                cell: 'cursor-pointer focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+            },
+        },
+        selected: {
+            true: { cell: 'ring-2 ring-foreground ring-offset-2 ring-offset-background' },
+        },
+    },
+});
+const LEVELS = [0, 1, 2, 3, 4];
+/** How far the lens reaches, in cells. */
+const LENS_REACH = 2.4;
+/** Milliseconds between one diagonal of dots arriving and the next. */
+const STAGGER = 22;
+function DayGridRoot({ cells, columns = 7, rows: perColumn, color = 'primary', value = null, onValueChange, lens = true, label = 'Activity', className, style, onPointerMove, onPointerLeave, ...props }) {
+    const slots = dayGridVariants({ color });
+    const root = useRef(null);
+    const nodes = useRef([]);
+    const frame = useRef(0);
+    const interactive = onValueChange !== undefined;
+    // The day whose tag is showing: the one under the pointer, or with focus.
+    const [pointed, setPointed] = useState(null);
+    // The dots start at nothing and arrive along the diagonals.
+    const [arrived, setArrived] = useState('no');
+    // Which way the days run: along each row, or down each column.
+    const byColumn = perColumn !== undefined;
+    const across = byColumn ? Math.ceil(cells.length / Math.max(1, perColumn)) : columns;
+    const rows = byColumn ? Math.max(1, perColumn) : Math.ceil(cells.length / columns);
+    useEffect(() => {
+        const start = requestAnimationFrame(() => setArrived('arriving'));
+        // Once the last diagonal is in, the delays come off. Left on, they would
+        // hold every dot back from the lens by its own share of the stagger.
+        const settle = setTimeout(() => setArrived('yes'), (rows + across) * STAGGER + 450);
+        return () => {
+            cancelAnimationFrame(start);
+            clearTimeout(settle);
+        };
+    }, [rows, across]);
+    useEffect(() => () => cancelAnimationFrame(frame.current), []);
+    const summary = useMemo(() => {
+        const active = cells.filter((cell) => cell.level > 0).length;
+        return `${label}: something on ${active} of ${cells.length} days.`;
+    }, [cells, label]);
+    const moveLens = (event) => {
+        onPointerMove?.(event);
+        // A finger covers what a lens would show, and has no hover to end it.
+        if (event.pointerType === 'touch')
+            return;
+        const still = !lens || window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        const { clientX, clientY } = event;
+        cancelAnimationFrame(frame.current);
+        frame.current = requestAnimationFrame(() => {
+            let nearest = null;
+            let best = Infinity;
+            nodes.current.forEach((node, index) => {
+                if (!node)
+                    return;
+                const box = node.getBoundingClientRect();
+                const distance = Math.hypot(clientX - (box.left + box.width / 2), clientY - (box.top + box.height / 2));
+                if (!still) {
+                    const near = Math.max(0, 1 - distance / (box.width * LENS_REACH));
+                    // Eased, so the swell has a soft edge and a round top.
+                    node.style.setProperty('--pu-lens', (near * near * (3 - 2 * near)).toFixed(3));
+                }
+                if (distance < best && distance < box.width * 0.75) {
+                    best = distance;
+                    nearest = index;
+                }
+            });
+            setPointed(nearest);
+        });
+    };
+    const leave = (event) => {
+        onPointerLeave?.(event);
+        cancelAnimationFrame(frame.current);
+        for (const node of nodes.current)
+            node?.style.removeProperty('--pu-lens');
+        setPointed(null);
+    };
+    const layout = byColumn
+        ? {
+            gridTemplateRows: `repeat(${rows}, auto)`,
+            gridAutoFlow: 'column',
+            gridAutoColumns: 'minmax(0, 1fr)',
+            ...style,
+        }
+        : { gridTemplateColumns: `repeat(${across}, minmax(0, 1fr))`, ...style };
+    /** Where a dot is in its entrance, as the styles that put it there. */
+    const dotStyle = (index) => {
+        if (arrived === 'yes')
+            return undefined;
+        const diagonal = byColumn
+            ? Math.floor(index / rows) + (index % rows)
+            : Math.floor(index / across) + (index % across);
+        return {
+            ['--pu-in']: arrived === 'no' ? 0 : 1,
+            transitionDelay: `${diagonal * STAGGER}ms`,
+            transitionDuration: '420ms',
+        };
+    };
+    const tag = (() => {
+        if (pointed === null)
+            return null;
+        const text = cells[pointed]?.label;
+        const node = nodes.current[pointed];
+        const box = root.current;
+        if (!text || !node || !box)
+            return null;
+        const centre = node.offsetLeft + node.offsetWidth / 2;
+        // Hung from whichever side keeps it inside the grid.
+        const share = centre / box.offsetWidth;
+        const shift = share < 0.25 ? '-12%' : share > 0.75 ? '-88%' : '-50%';
+        return (_jsx("span", { "aria-hidden": "true", className: slots.tag(), style: { left: centre, top: node.offsetTop - 6, translate: `${shift} -100%` }, children: text }));
+    })();
+    if (!interactive) {
+        return (_jsxs("div", { ref: root, role: "img", "aria-label": summary, className: slots.root({ className }), style: layout, onPointerMove: moveLens, onPointerLeave: leave, ...props, children: [cells.map((cell, index) => {
+                    const part = dayGridVariants({ level: cell.level });
+                    return (_jsx("span", { ref: (node) => {
+                            nodes.current[index] = node;
+                        }, className: part.cell(), children: _jsx("span", { className: part.dot(), style: dotStyle(index) }) }, index));
+                }), tag] }));
+    }
+    // One Tab stop for the grid: the selected day, or the first.
+    const focusable = value !== null && value >= 0 && value < cells.length ? value : 0;
+    const onKeyDown = (event, index) => {
+        const rtl = getComputedStyle(event.currentTarget).direction === 'rtl';
+        const moves = {
+            // One day along a row, or one whole column when the days run downwards.
+            ArrowLeft: (rtl ? 1 : -1) * (byColumn ? rows : 1),
+            ArrowRight: (rtl ? -1 : 1) * (byColumn ? rows : 1),
+            ArrowUp: byColumn ? -1 : -across,
+            ArrowDown: byColumn ? 1 : across,
+        };
+        let next;
+        if (event.key in moves)
+            next = index + (moves[event.key] ?? 0);
+        else if (event.key === 'Home')
+            next = 0;
+        else if (event.key === 'End')
+            next = cells.length - 1;
+        if (next === undefined || next < 0 || next >= cells.length)
+            return;
+        event.preventDefault();
+        nodes.current[next]?.focus();
+        onValueChange(next);
+    };
+    return (_jsxs("div", { ref: root, role: "group", "aria-label": summary, className: slots.root({ className }), style: layout, onPointerMove: moveLens, onPointerLeave: leave, ...props, children: [cells.map((cell, index) => {
+                const part = dayGridVariants({
+                    level: cell.level,
+                    interactive: true,
+                    selected: value === index,
+                });
+                return (_jsx("button", { ref: (node) => {
+                        nodes.current[index] = node;
+                    }, type: "button", "aria-label": cell.label ?? `Day ${index + 1}, level ${cell.level} of 4`, "aria-pressed": value === index, tabIndex: index === focusable ? 0 : -1, onClick: () => onValueChange(index), onKeyDown: (event) => onKeyDown(event, index), onFocus: (event) => {
+                        // Only for focus that came from the keyboard: a click focuses
+                        // too, and the pointer is already showing that day's tag.
+                        if (event.currentTarget.matches(':focus-visible'))
+                            setPointed(index);
+                    }, onBlur: () => setPointed((current) => (current === index ? null : current)), className: part.cell(), children: _jsx("span", { className: part.dot(), style: dotStyle(index) }) }, index));
+            }), tag] }));
+}
+DayGridRoot.displayName = 'DayGrid';
+/** The five sizes, quietest to busiest, with a word at each end. */
+function DayGridLegend({ color = 'primary', less = 'Less', more = 'More', className, ...props }) {
+    const slots = dayGridVariants({ color });
+    return (_jsxs("div", { className: slots.legend({ className }), ...props, children: [_jsx("span", { children: less }), LEVELS.map((level) => (_jsx("span", { "aria-hidden": "true", className: slots.swatch(), children: _jsx("span", { className: dayGridVariants({ level }).dot({ className: 'shadow-none' }) }) }, level))), _jsx("span", { children: more })] }));
+}
+DayGridLegend.displayName = 'DayGrid.Legend';
+export const DayGrid = Object.assign(DayGridRoot, {
+    Legend: DayGridLegend,
+});
+/* By name as well, for a Server Component, which cannot dot into a client
+   module. */
+export { DayGridLegend };

package/dist/components/feedback/index.d.ts

@@ -0,0 +1,135 @@
+import { type ComponentProps, type ReactElement, type ReactNode } from 'react';
+export interface FeedbackProps {
+    children?: ReactNode;
+    /** Whether the dialog is open, when the caller holds that. */
+    open?: boolean;
+    /** Called when the dialog asks to open or close. */
+    onOpenChange?: (open: boolean) => void;
+    /** Whether it starts open, when the caller does not hold it. */
+    defaultOpen?: boolean;
+    /** The message, when the caller holds it. Leave unset to let the field keep it. */
+    value?: string;
+    /** The message to start with, when the caller does not hold it. */
+    defaultValue?: string;
+    /** Called with the message each time it changes. */
+    onValueChange?: (value: string) => void;
+    /**
+     * Whether a click outside or the Escape key closes the dialog. Turn it off
+     * for a message that would be lost by a stray click; Cancel and the close
+     * button still work.
+     */
+    dismissible?: boolean;
+}
+declare function FeedbackRoot({ children, open, onOpenChange, defaultOpen, value, defaultValue, onValueChange, dismissible, }: FeedbackProps): import("react").JSX.Element;
+declare namespace FeedbackRoot {
+    var displayName: string;
+}
+export interface FeedbackTriggerProps extends Omit<ComponentProps<'button'>, 'children'> {
+    children?: ReactNode;
+    /**
+     * Your own element to be the trigger, such as a styled button. It is given
+     * the click handler and the attributes that tie it to the dialog.
+     */
+    render?: ReactElement;
+}
+/** What opens the dialog. A plain button unless `render` supplies one. */
+declare function FeedbackTrigger({ render, children, ...props }: FeedbackTriggerProps): import("react").JSX.Element;
+declare namespace FeedbackTrigger {
+    var displayName: string;
+}
+export interface FeedbackContentProps extends Omit<ComponentProps<'div'>, 'children'> {
+    children?: ReactNode;
+    /**
+     * Draw it in the page instead of over it: no backdrop, no trigger, always
+     * there. For a feedback box that is part of the page, such as the end of an
+     * article. `open` is ignored, and Cancel and the close button only report
+     * through `onOpenChange`.
+     */
+    inline?: boolean;
+    /** Frost the page behind the dialog instead of only dimming it. */
+    blur?: boolean;
+}
+/** The shell: the darker band, and everything set in it. */
+declare function FeedbackContent({ inline, blur, className, children, ...props }: FeedbackContentProps): import("react").JSX.Element;
+declare namespace FeedbackContent {
+    var displayName: string;
+}
+export interface FeedbackPanelProps extends ComponentProps<'div'> {
+}
+/** The well set into the shell: the title, the close button and the field. */
+declare function FeedbackPanel({ className, ...props }: FeedbackPanelProps): import("react").JSX.Element;
+declare namespace FeedbackPanel {
+    var displayName: string;
+}
+export interface FeedbackTitleProps extends ComponentProps<'h2'> {
+}
+/** The question. In a dialog it is also what the dialog is announced as. */
+declare function FeedbackTitle({ className, ...props }: FeedbackTitleProps): import("react").JSX.Element;
+declare namespace FeedbackTitle {
+    var displayName: string;
+}
+export interface FeedbackCloseProps extends Omit<ComponentProps<'button'>, 'children'> {
+    /** How the button announces itself to a screen reader. */
+    label?: string;
+}
+/** The ✕ in the panel's corner. */
+declare function FeedbackClose({ label, className, onClick, ...props }: FeedbackCloseProps): import("react").JSX.Element;
+declare namespace FeedbackClose {
+    var displayName: string;
+}
+export interface FeedbackFieldProps extends Omit<ComponentProps<'textarea'>, 'value' | 'defaultValue' | 'onChange'> {
+    /** The message. Leave unset to let the dialog hold it. */
+    value?: string;
+    /** Called with the message each time it changes. */
+    onValueChange?: (value: string) => void;
+    /** Room to write in, in pixels, before the field starts to grow. */
+    minHeight?: number;
+    /** How tall the field may grow, in pixels, before the area round it scrolls. */
+    maxHeight?: number;
+}
+/**
+ * What is being written. No border and no background of its own: it is
+ * already inside a well.
+ */
+declare function FeedbackField({ value, onValueChange, minHeight, maxHeight, className, style, onKeyDown, ref, 'aria-label': ariaLabel, ...props }: FeedbackFieldProps): import("react").JSX.Element;
+declare namespace FeedbackField {
+    var displayName: string;
+}
+export interface FeedbackFooterProps extends ComponentProps<'div'> {
+}
+/** The action row, in the band under the panel. */
+declare function FeedbackFooter({ className, ...props }: FeedbackFooterProps): import("react").JSX.Element;
+declare namespace FeedbackFooter {
+    var displayName: string;
+}
+export interface FeedbackActionProps extends ComponentProps<'button'> {
+}
+/** Discards and closes. Call `preventDefault` in `onClick` to keep it open. */
+declare function FeedbackCancel({ children, className, disabled, onClick, ...props }: FeedbackActionProps): import("react").JSX.Element;
+declare namespace FeedbackCancel {
+    var displayName: string;
+}
+export interface FeedbackSubmitProps extends Omit<FeedbackActionProps, 'onSubmit'> {
+    /**
+     * Called with the message. The dialog stays open: close it yourself once
+     * the message has been sent, so a failure still has somewhere to be shown.
+     */
+    onSubmit?: (value: string) => void;
+}
+/** Sends. Inert while the field is empty, unless `disabled` says otherwise. */
+declare function FeedbackSubmit({ children, className, disabled, onClick, onSubmit, ...props }: FeedbackSubmitProps): import("react").JSX.Element;
+declare namespace FeedbackSubmit {
+    var displayName: string;
+}
+export declare const Feedback: typeof FeedbackRoot & {
+    Trigger: typeof FeedbackTrigger;
+    Content: typeof FeedbackContent;
+    Panel: typeof FeedbackPanel;
+    Title: typeof FeedbackTitle;
+    Close: typeof FeedbackClose;
+    Field: typeof FeedbackField;
+    Footer: typeof FeedbackFooter;
+    Cancel: typeof FeedbackCancel;
+    Submit: typeof FeedbackSubmit;
+};
+export { FeedbackTrigger, FeedbackContent, FeedbackPanel, FeedbackTitle, FeedbackClose, FeedbackField, FeedbackFooter, FeedbackCancel, FeedbackSubmit, };