panelui-web 0.5.0 → 0.7.0

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

@@ -17,7 +17,7 @@ export interface SheetProps {
      */
     dismissible?: boolean;
 }
-declare function SheetRoot({ children, open, onOpenChange, defaultOpen, side, dismissible, }: SheetProps): import("react").JSX.Element;
+declare function SheetRoot(props: SheetProps): import("react").JSX.Element;
 declare namespace SheetRoot {
     var displayName: string;
 }
@@ -28,12 +28,50 @@ export interface SheetTriggerProps extends Omit<ComponentProps<'button'>, 'child
      * the click handler and the attributes that tie it to the sheet.
      */
     render?: ReactElement;
+    /**
+     * The `name` of a `Sheet.Next` to open instead of the sheet this trigger is
+     * in. Any button in a sheet can open the next one this way, wherever it sits.
+     */
+    to?: string;
+    /**
+     * Handed to the `Sheet.Next` that `to` names, as the argument of its
+     * children function. Use it to open one sheet for every row of a list.
+     */
+    payload?: unknown;
 }
-/** What opens the sheet. A plain button unless `render` supplies one. */
-declare function SheetTrigger({ render, children, ...props }: SheetTriggerProps): import("react").JSX.Element;
+/**
+ * What opens a sheet: its own, or with `to`, the `Sheet.Next` of that name.
+ * A plain button unless `render` supplies one.
+ */
+declare function SheetTrigger({ render, children, to, payload, ...props }: SheetTriggerProps): import("react").JSX.Element;
 declare namespace SheetTrigger {
     var displayName: string;
 }
+export interface SheetNextProps extends Omit<SheetContentProps, 'children' | 'inline'> {
+    /** What a `Sheet.Trigger` passes as `to` to open this sheet. Unique within one stack of sheets. */
+    name: string;
+    /**
+     * The sheet's parts. Pass a function to read the `payload` of the trigger
+     * that opened it; it is `undefined` when that trigger has none.
+     */
+    children?: ReactNode | ((payload: any) => ReactNode);
+    /** The edge it rises from. Default: the edge of the sheet it is declared in. */
+    side?: SheetSide;
+    /** Whether a click outside, a swipe or Escape closes it. Default true. */
+    dismissible?: boolean;
+    /** Called when it opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A sheet opened from the one it is declared in, by any `Sheet.Trigger` whose
+ * `to` is its `name`. Put it anywhere inside the first sheet's content; it
+ * takes `Sheet.Content`'s props and draws its own content, so its children are
+ * the header, body and footer.
+ */
+declare function SheetNext({ name, children, side, dismissible, onOpenChange, ...content }: SheetNextProps): import("react").JSX.Element;
+declare namespace SheetNext {
+    var displayName: string;
+}
 export interface SheetContentProps extends Omit<ComponentProps<'div'>, 'children'> {
     children?: ReactNode;
     /**
@@ -136,6 +174,7 @@ declare namespace SheetStage {
 }
 export declare const Sheet: typeof SheetRoot & {
     Trigger: typeof SheetTrigger;
+    Next: typeof SheetNext;
     Content: typeof SheetContent;
     Header: typeof SheetHeader;
     Title: typeof SheetTitle;
@@ -145,4 +184,4 @@ export declare const Sheet: typeof SheetRoot & {
     Close: typeof SheetClose;
     Stage: typeof SheetStage;
 };
-export { SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetBody, SheetFooter, SheetClose, SheetStage, };
+export { SheetTrigger, SheetNext, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetBody, SheetFooter, SheetClose, SheetStage, };

package/dist/components/sheet/index.js

@@ -34,6 +34,13 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * still shows, and dimmed. Only the first sheet darkens the page, so two open
  * sheets do not stack two shades of black.
  *
+ * The next sheet is declared once, as `Sheet.Next` with a `name`, and opened
+ * by any `Sheet.Trigger to="name"` in the sheet: a row in the body, an icon in
+ * the header, a button in the footer. The trigger and the sheet it opens are
+ * apart in the markup because they are apart on the screen: a list of rows
+ * that each open a sheet should not have to wrap every row in one. A trigger
+ * can carry a `payload`, so one `Sheet.Next` serves every row of a list.
+ *
  * ## The hand decides
  *
  * Every sheet follows a drag and leaves on a flick toward its own edge. The
@@ -48,7 +55,7 @@ import { tv } from 'tailwind-variants';
  * back, the page receding. A fast start that eases into place reads as weight,
  * where a symmetric ease reads as a slide show.
  */
-const MOVE = '[transition:transform_450ms_cubic-bezier(0.32,0.72,0,1),border-radius_450ms_cubic-bezier(0.32,0.72,0,1),margin_450ms_cubic-bezier(0.32,0.72,0,1)]';
+const MOVE = '[transition:transform_450ms_cubic-bezier(0.32,0.72,0,1),border-radius_450ms_cubic-bezier(0.32,0.72,0,1),margin_450ms_cubic-bezier(0.32,0.72,0,1),height_450ms_cubic-bezier(0.32,0.72,0,1)]';
 const sheetVariants = tv({
     slots: {
         backdrop: [
@@ -83,6 +90,17 @@ const sheetVariants = tv({
             "after:pointer-events-none after:absolute after:inset-0 after:rounded-[inherit] after:bg-popover after:opacity-0 after:transition-opacity after:duration-[450ms] after:content-['']",
             'data-nested-drawer-open:after:opacity-50',
         ],
+        /*
+         * A top or bottom sheet behind another takes the front one's height, so
+         * the strip that shows past it is the same whichever of the two is taller.
+         * A taller sheet behind would otherwise stand above the stack, and a
+         * shorter one would vanish behind the front one entirely.
+         */
+        stacked: [
+            'data-nested-drawer-open:h-(--drawer-frontmost-height) data-nested-drawer-open:overflow-hidden',
+            // Lets the height animate to and from `auto` where the browser can.
+            '[interpolate-size:allow-keywords]',
+        ],
         grabber: [
             'pointer-events-none absolute inset-x-0 z-10 mx-auto flex h-6 w-24 justify-center',
             'before:h-[5px] before:w-9 before:rounded-full before:bg-muted-foreground/35',
@@ -206,6 +224,19 @@ const SWIPE = {
     left: 'left',
     right: 'right',
 };
+function createStack() {
+    const handles = new Map();
+    return {
+        handle(name) {
+            let handle = handles.get(name);
+            if (!handle) {
+                handle = Drawer.createHandle();
+                handles.set(name, handle);
+            }
+            return handle;
+        },
+    };
+}
 const SheetContext = createContext(null);
 function useSheet(part) {
     const context = useContext(SheetContext);
@@ -213,10 +244,16 @@ function useSheet(part) {
         throw new Error(`${part} must be used inside a <Sheet>.`);
     return context;
 }
-function SheetRoot({ children, open, onOpenChange, defaultOpen = false, side = 'bottom', dismissible = true, }) {
+function SheetRoot(props) {
+    return _jsx(SheetFrame, { ...props });
+}
+SheetRoot.displayName = 'Sheet';
+function SheetFrame({ children, open, onOpenChange, defaultOpen = false, side = 'bottom', dismissible = true, handle: drawerHandle, }) {
     // A sheet inside another sheet's content finds that sheet's context.
     const parent = useContext(SheetContext);
     const nested = parent !== null && !parent.inline;
+    const [ownStack] = useState(createStack);
+    const stack = nested && parent ? parent.stack : ownStack;
     // Held here as well as by the primitive, so a sheet opened from this one
     // can close it.
     const [internalOpen, setInternalOpen] = useState(defaultOpen);
@@ -243,6 +280,7 @@ function SheetRoot({ children, open, onOpenChange, defaultOpen = false, side = '
     useEffect(() => (nested && parent ? parent.register(handle) : undefined), [nested, parent, handle]);
     const context = useMemo(() => ({
         side,
+        stack,
         nested,
         inline: false,
         showClose: true,
@@ -252,8 +290,8 @@ function SheetRoot({ children, open, onOpenChange, defaultOpen = false, side = '
         },
         closeTree: handle.closeTree,
         hasOpenChild: () => [...opened.current].some((child) => child.isOpen()),
-    }), [side, nested, handle]);
-    return (_jsx(SheetContext.Provider, { value: context, children: _jsx(Drawer.Root, { open: isOpen, swipeDirection: SWIPE[side], disablePointerDismissal: !dismissible, onOpenChange: (next, details) => {
+    }), [side, stack, nested, handle]);
+    return (_jsx(SheetContext.Provider, { value: context, children: _jsx(Drawer.Root, { open: isOpen, handle: drawerHandle, swipeDirection: SWIPE[side], disablePointerDismissal: !dismissible, onOpenChange: (next, details) => {
                 // The primitive has a switch for a press outside and none for
                 // Escape or a swipe, so those are refused here.
                 if (!next &&
@@ -263,14 +301,43 @@ function SheetRoot({ children, open, onOpenChange, defaultOpen = false, side = '
                     return;
                 }
                 setOpen(next);
-            }, children: children }) }));
+            }, children: typeof children === 'function'
+                ? ({ payload }) => children(payload)
+                : children }) }));
 }
-SheetRoot.displayName = 'Sheet';
-/** What opens the sheet. A plain button unless `render` supplies one. */
-function SheetTrigger({ render, children, ...props }) {
+/**
+ * What opens a sheet: its own, or with `to`, the `Sheet.Next` of that name.
+ * A plain button unless `render` supplies one.
+ */
+function SheetTrigger({ render, children, to, payload, ...props }) {
+    const sheet = useContext(SheetContext);
+    if (to !== undefined) {
+        if (!sheet)
+            throw new Error('Sheet.Trigger with `to` must be used inside a <Sheet>.');
+        return (_jsx(Drawer.Trigger, { handle: sheet.stack.handle(to), payload: payload, render: render, ...props, children: children }));
+    }
     return (_jsx(Drawer.Trigger, { render: render, ...props, children: children }));
 }
 SheetTrigger.displayName = 'Sheet.Trigger';
+/**
+ * A sheet opened from the one it is declared in, by any `Sheet.Trigger` whose
+ * `to` is its `name`. Put it anywhere inside the first sheet's content; it
+ * takes `Sheet.Content`'s props and draws its own content, so its children are
+ * the header, body and footer.
+ */
+function SheetNext({ name, children, side, dismissible, onOpenChange, ...content }) {
+    const parent = useSheet('Sheet.Next');
+    return (_jsx(SheetFrame, { handle: parent.stack.handle(name), side: side ?? parent.side, dismissible: dismissible, onOpenChange: onOpenChange, children: (payload) => (_jsx(SheetContent, { ...content, children: typeof children === 'function' ? _jsx(NextParts, { render: children, payload: payload }) : children })) }));
+}
+SheetNext.displayName = 'Sheet.Next';
+/**
+ * Calls a `Sheet.Next` children function. As a component of its own it only
+ * runs once the sheet is open and its content mounted, which is when the
+ * trigger has handed over its payload.
+ */
+function NextParts({ render, payload }) {
+    return _jsx(_Fragment, { children: render(payload) });
+}
 /** The sheet itself, with the backdrop behind it. */
 function SheetContent({ children, detached = true, size = 'auto', showGrabber, showClose = true, blur = false, inline = false, className, ...props }) {
     const sheet = useSheet('Sheet.Content');
@@ -291,7 +358,7 @@ function SheetContent({ children, detached = true, size = 'auto', showGrabber, s
                 onClick: () => {
                     if (sheet.hasOpenChild())
                         sheet.closeTree();
-                } })), _jsx(Drawer.Viewport, { className: slots.viewport(), children: _jsx(Drawer.Popup, { className: slots.popup({ className }), ...props, children: _jsx(SheetContext.Provider, { value: context, children: inside }) }) })] }));
+                } })), _jsx(Drawer.Viewport, { className: slots.viewport(), children: _jsx(Drawer.Popup, { className: slots.popup({ className: [vertical && slots.stacked(), className] }), ...props, children: _jsx(SheetContext.Provider, { value: context, children: inside }) }) })] }));
 }
 SheetContent.displayName = 'Sheet.Content';
 /**
@@ -359,6 +426,7 @@ function SheetStage({ className, children, ...props }) {
 SheetStage.displayName = 'Sheet.Stage';
 export const Sheet = Object.assign(SheetRoot, {
     Trigger: SheetTrigger,
+    Next: SheetNext,
     Content: SheetContent,
     Header: SheetHeader,
     Title: SheetTitle,
@@ -368,4 +436,4 @@ export const Sheet = Object.assign(SheetRoot, {
     Close: SheetClose,
     Stage: SheetStage,
 });
-export { SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetBody, SheetFooter, SheetClose, SheetStage, };
+export { SheetTrigger, SheetNext, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetBody, SheetFooter, SheetClose, SheetStage, };

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

@@ -0,0 +1,195 @@
+/**
+ * Soundwave — what a voice looks like while an app listens to it.
+ *
+ * ```tsx
+ * <Soundwave variant="dots" state="listening" level={level} />
+ *
+ * <Soundwave variant="radial" state="speaking">
+ *   <Soundwave.Center>
+ *     <Avatar name="Khalid Abdi" size="xl" />
+ *   </Soundwave.Center>
+ * </Soundwave>
+ * ```
+ *
+ * Seven looks. Four are the app's: `pills` over a microphone button, `bars`
+ * for a metering strip, `line` for a travelling wave, `ambient` for a glow
+ * behind a whole screen. Three are drawn in dots and spokes: `dots`, a field
+ * of dots lit into a wave; `radial`, spokes around a person; and `ring`,
+ * rings of dots lit outward by angle.
+ *
+ * ## It draws a level; it does not record one
+ *
+ * Nothing here touches the microphone. The app owns the recorder and hands
+ * over a number from 0 to 1, so the same wave works against a real meter, a
+ * synthesised one or a remote peer's. With no level it runs its own motion
+ * for the current `state`, so a voice screen can be built before any audio
+ * exists.
+ *
+ * ## Levels arrive faster than React should render
+ *
+ * A meter reports dozens of times a second. `level` takes a ref as well as a
+ * number: write each reading into `ref.current` and the wave picks it up on
+ * its next frame with nothing above it rendering. Each frame writes the `d`
+ * of one or two SVG paths, never React state, and the dots are zero-length
+ * round-capped segments, so a field of four hundred dots is a single path.
+ *
+ * Either way the level is smoothed with a fast attack and a slow release,
+ * which is what makes it read as a meter: it snaps up on a syllable and falls
+ * back gently instead of chattering on every sample.
+ */
+import { type ComponentProps, type ReactNode, type RefObject } from 'react';
+export type SoundwaveVariant = 'pills' | 'bars' | 'line' | 'ambient' | 'dots' | 'radial' | 'ring';
+export type SoundwaveState = 'idle' | 'listening' | 'thinking' | 'speaking';
+/** A role from the theme. The wave never carries a colour of its own. */
+export type SoundwaveColor = 'foreground' | 'primary' | 'info' | 'success' | 'warning' | 'destructive' | 'chart-1' | 'chart-2' | 'chart-3' | 'chart-4' | 'chart-5';
+export interface SoundwaveProps extends Omit<ComponentProps<'div'>, 'color' | 'children'> {
+    /**
+     * Which look to draw: `pills` for a few capsules over a microphone button,
+     * `bars` for a metering strip, `line` for a travelling wave, `ambient` for a
+     * glow that fills its parent, `dots` for a field of dots lit into a wave,
+     * `radial` for spokes around a centre, and `ring` for rings of dots lit
+     * outward by angle.
+     */
+    variant?: SoundwaveVariant;
+    /**
+     * What the app is doing. With no `level` it picks the motion the wave runs
+     * on its own, and it always sets what a screen reader announces.
+     */
+    state?: SoundwaveState;
+    /**
+     * How loud the input is now, from 0 to 1. Pass a ref and write each
+     * reading into `ref.current` to keep updates out of React entirely. Leave
+     * it out and the wave runs its own motion for `state`.
+     */
+    level?: number | RefObject<number | null>;
+    /**
+     * Sound to draw, in place of `level`: a `MediaStream` from a microphone or
+     * a call, or an `<audio>` or `<video>` element. A media file has to be on
+     * the same site or sent with CORS headers, or the browser hides its sound
+     * from the page and the wave stays still.
+     */
+    source?: SoundwaveSource | null;
+    /**
+     * Fixed values, 0 to 1 each: the stored shape of a recording, a frequency
+     * analysis, or one value per angle for `ring` (24 for the hours of a day).
+     * Resampled to the bar count, and drawn still rather than animated.
+     */
+    levels?: readonly number[];
+    /**
+     * How far a recording has played, from 0 to 1. Bars and dots behind it keep
+     * full ink and the rest are dimmed. `bars` and `dots`, with `levels`.
+     */
+    progress?: number;
+    /** How many capsules, bars or spokes, or how many angles for `ring`. `dots` fits as many columns as the width allows. */
+    bars?: number;
+    /** Capsule or bar width, the stroke of `line` and `radial`, or the size of a dot. */
+    barWidth?: number;
+    /** Space between capsules, or between dots. `bars` spaces itself across the width. */
+    barGap?: number;
+    /** Drawing height. For `radial` and `ring` it is the diameter. `ambient` fills its parent instead. */
+    height?: number;
+    /**
+     * `static` gives every bar a share of the current level; `scrolling` keeps a
+     * history that slides across, newest at the trailing edge. `bars` and `dots`.
+     */
+    mode?: 'static' | 'scrolling';
+    /** Grow bars and dots from the middle out rather than up from the bottom. */
+    centered?: boolean;
+    /** Fade a strip out at both ends, so it does not stop at a hard edge. */
+    fadeEdges?: boolean;
+    /** Multiplier on the incoming level, applied before it is capped at 1. */
+    sensitivity?: number;
+    /** Multiplier on the wave's own tempo, including how fast a history scrolls. */
+    speed?: number;
+    /**
+     * The ink, as a role from the theme. Left unset the wave is drawn in the
+     * text colour of whatever it sits in, which is right on most surfaces;
+     * `ambient` defaults to `info`, since a glow in the text colour reads as a
+     * shadow.
+     */
+    color?: SoundwaveColor;
+    /**
+     * Colours across the wave instead of one ink, as theme roles: left to right
+     * for the strips, up from the bottom for `ambient`.
+     */
+    gradient?: readonly SoundwaveColor[];
+    /**
+     * The colour of the unlit dots in `dots` and `ring`, and of the part of a
+     * recording not yet played in `bars`. Defaults to the ink, faint.
+     */
+    trackColor?: SoundwaveColor;
+    /** Hold the current frame. */
+    paused?: boolean;
+    /** What a screen reader calls it. Defaults to the state: "Listening". */
+    label?: string;
+    /** For `radial` and `ring`: a `Soundwave.Center` holding what sits in the middle. */
+    children?: ReactNode;
+}
+/** A voice as a wave. Draws a `level` it is handed, or runs its own motion for `state`. */
+declare function SoundwaveRoot({ variant, state, level: levelProp, source, levels, progress, bars, barWidth, barGap, height, mode, centered, fadeEdges, sensitivity, speed, color, gradient, trackColor, paused, label, className, style, children, ...props }: SoundwaveProps): import("react").JSX.Element;
+declare namespace SoundwaveRoot {
+    var displayName: string;
+}
+export interface SoundwaveCenterProps extends ComponentProps<'div'> {
+}
+/**
+ * What sits in the hole of a `radial` or `ring` wave: a person's avatar, a
+ * figure, a button. It is sized to the hole and centred in it.
+ */
+declare function SoundwaveCenter({ className, ...props }: SoundwaveCenterProps): import("react").JSX.Element;
+declare namespace SoundwaveCenter {
+    var displayName: string;
+}
+export declare const Soundwave: typeof SoundwaveRoot & {
+    Center: typeof SoundwaveCenter;
+};
+export { SoundwaveCenter };
+/** Something with sound in it: a microphone or call stream, or an `<audio>` or `<video>` element. */
+export type SoundwaveSource = MediaStream | HTMLMediaElement;
+export interface AudioLevelOptions {
+    /**
+     * The quietest sound that still moves the wave, in decibels below full
+     * scale. Default `-60`. Raise it towards `-45` in a noisy room.
+     */
+    floor?: number;
+    /** The loudness that fills the wave, in decibels below full scale. Default `-12`. */
+    ceiling?: number;
+}
+/**
+ * How loud `source` is, from 0 to 1, kept in a ref that is updated every
+ * frame. Pass the ref to `Soundwave` as `level`, or read `ref.current`
+ * yourself. With no source the ref holds 0.
+ */
+export declare function useAudioLevel(source: SoundwaveSource | null | undefined, { floor, ceiling }?: AudioLevelOptions): RefObject<number>;
+export type MicrophoneStatus = 'idle' | 'requesting' | 'listening' | 'denied' | 'unsupported';
+export interface UseMicrophoneOptions extends AudioLevelOptions {
+    /** Passed to `getUserMedia` as `audio`, to pick a device or change its processing. */
+    constraints?: MediaTrackConstraints;
+}
+export interface MicrophoneControls {
+    /** How loud the microphone is, from 0 to 1. Pass it to `Soundwave` as `level`. */
+    level: RefObject<number>;
+    /** The live stream while listening, for a recorder or a call. `null` otherwise. */
+    stream: MediaStream | null;
+    /** `requesting` while the browser asks for permission, `denied` if it was refused or there is no microphone. */
+    status: MicrophoneStatus;
+    /** Whether it is listening now. */
+    active: boolean;
+    /** Ask for the microphone and start listening. Call it from a click: browsers only allow sound to start from one. */
+    start: () => Promise<void>;
+    /** Stop listening and release the microphone, which turns the browser's recording light off. */
+    stop: () => void;
+    /** `start` when stopped, `stop` when listening. */
+    toggle: () => void;
+}
+/**
+ * The microphone, ready to draw. Nothing is asked for until `start`, and the
+ * microphone is released on `stop` and when the component unmounts.
+ *
+ * ```tsx
+ * const mic = useMicrophone();
+ * <Soundwave level={mic.active ? mic.level : undefined} />
+ * <Button onClick={mic.toggle}>{mic.active ? 'Stop' : 'Speak'}</Button>
+ * ```
+ */
+export declare function useMicrophone({ constraints, ...options }?: UseMicrophoneOptions): MicrophoneControls;