plass-ui 1.2.0 → 1.4.0

package/dist/hooks/usePlDisclosure.d.ts

@@ -0,0 +1,44 @@
+/** What a caller gets back: the answer, and the four ways to change it. */
+export interface PlDisclosureResult {
+    /** Whether the thing is open. */
+    open: boolean;
+    /** Opens it. */
+    onOpen: () => void;
+    /** Closes it. */
+    onClose: () => void;
+    /** Turns it round. */
+    onToggle: () => void;
+    /** Sets it to a value, for the caller who already has one. */
+    setOpen: (open: boolean) => void;
+}
+/**
+ * One boolean and the four callbacks that change it.
+ *
+ * The smallest hook in the library and the one that saves the most typing: a
+ * dialog, a drawer, a popover and a menu each need exactly this, and written by
+ * hand it is a `useState` plus three arrow functions **that are new on every
+ * render**. That last part is the reason it is worth a hook rather than a
+ * snippet — an inline `() => setOpen(false)` handed to a memoised trigger
+ * defeats the memo, and every one of the callbacks here is stable for the life
+ * of the component.
+ *
+ * The names are the props they are handed to. `onOpenChange` is the one shape
+ * every openable component in this library takes, and `setOpen` fits it
+ * exactly, so the ordinary use is a spread:
+ *
+ * ```tsx
+ * const dialog = usePlDisclosure();
+ *
+ * <PlButton onClick={dialog.onOpen}>Delete</PlButton>
+ * <PlModal open={dialog.open} onOpenChange={dialog.setOpen} title="Delete this?">
+ *   <PlButton onClick={dialog.onClose}>Cancel</PlButton>
+ * </PlModal>
+ * ```
+ *
+ * It holds no DOM, watches nothing and has no effect in it, so it costs the
+ * same on a server as it does in a browser.
+ *
+ * @example
+ * const drawer = usePlDisclosure(true);
+ */
+export declare function usePlDisclosure(initial?: boolean): PlDisclosureResult;

package/dist/hooks/usePlDisclosure.js

@@ -0,0 +1 @@
+"use client";import*as e from"react";export function usePlDisclosure(o=!1){const[s,l]=e.useState(o),n=e.useCallback(()=>l(!0),[]),t=e.useCallback(()=>l(!1),[]),u=e.useCallback(()=>l(e=>!e),[]);return e.useMemo(()=>({open:s,onOpen:n,onClose:t,onToggle:u,setOpen:l}),[s,n,t,u])}

package/dist/hooks/usePlElementSize.d.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+/** The box an element is laid out at, in pixels. */
+export interface PlElementSize {
+    width: number;
+    height: number;
+}
+/**
+ * How big an element is, kept up to date as it changes.
+ *
+ * A `ResizeObserver` and the two things a hook has to add. The first is
+ * **when**: the size is read in a layout effect as well as from the observer,
+ * because an observer's first callback arrives after a frame has been painted
+ * and a component that laid itself out from `0 × 0` for one frame flashes.
+ *
+ * The second is what it reports: the **content box**, the room actually left
+ * inside the element once its own padding has been taken off. A hand-written
+ * version nearly always reports `getBoundingClientRect` or `borderBoxSize`
+ * instead, which is a different number — and the wrong one for the question
+ * that made somebody measure the element.
+ *
+ * `null` until there is an element to measure, which is the honest answer on a
+ * server and on the first render: guessing `0` there would let a caller divide
+ * by it.
+ *
+ * @example
+ * const box = React.useRef<HTMLDivElement>(null);
+ * const size = usePlElementSize(box);
+ *
+ * <div ref={box}>{size ? `${Math.round(size.width)}px` : null}</div>
+ */
+export declare function usePlElementSize(target: React.RefObject<HTMLElement | null>): PlElementSize | null;

package/dist/hooks/usePlElementSize.js

@@ -0,0 +1 @@
+"use client";import*as t from"react";export function usePlElementSize(e){const[n,i]=t.useState(null);return t.useLayoutEffect(()=>{const t=e.current;if(!t)return;const read=()=>{const e=function contentBoxOf(t){const e=getComputedStyle(t),n=parseFloat(e.paddingInlineStart)+parseFloat(e.paddingInlineEnd),i=parseFloat(e.paddingBlockStart)+parseFloat(e.paddingBlockEnd);return{width:Math.max(0,t.clientWidth-n),height:Math.max(0,t.clientHeight-i)}}(t);i(t=>t?.width===e.width&&t.height===e.height?t:e)};if(read(),"undefined"==typeof ResizeObserver)return;const n=new ResizeObserver(read);return n.observe(t),()=>n.disconnect()},[e]),n}

package/dist/hooks/usePlHotKeys.d.ts

@@ -0,0 +1,81 @@
+import * as React from 'react';
+import type { PlassHotKeys } from '../types.js';
+/** Anything a listener can be attached to, plus the ref a React caller holds. */
+export type PlHotKeysTarget = Window | Document | HTMLElement | React.RefObject<HTMLElement | null> | null;
+export interface PlHotKeysOptions {
+    /**
+     * Whether the chords are bound at all. `false` removes the listener rather
+     * than making the handlers no-ops, so a shortcut that is off does not consume
+     * the key from whatever else wanted it.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * What the listener is attached to.
+     *
+     * `window` is the default and is what a global shortcut means. A ref, an
+     * element or `document` scopes the binding to a region — but note that a
+     * `keydown` only reaches an element that contains the focus, so scoping to a
+     * panel nobody has tabbed into binds nothing.
+     * @default window
+     */
+    target?: PlHotKeysTarget;
+    /**
+     * Whether a chord is answered while the focus is in a text field.
+     *
+     * Off by default, and this is the decision the hook exists to get right: a
+     * global `/` that jumps to search must not eat the slash out of a URL
+     * somebody is typing into a form.
+     *
+     * It is narrower than it sounds, and only two kinds of chord are ever held
+     * back. A chord carrying **`Mod`, `Ctrl`, `Meta` or `Alt` is answered either
+     * way**, because none of those can appear in a field's value — so the
+     * ordinary `Mod+K` needs nothing set here. Shift does not count as one:
+     * `Shift+A` is how a capital A is typed. And a key that **does nothing in a
+     * field** is answered either way too: `Escape` is the one that matters, since
+     * a panel that closes on Escape has to close from inside its own form.
+     *
+     * What is left is exactly the case this is for: a printable character, or one
+     * of the keys that edits or moves through text, pressed while the focus is in
+     * a field. Turn it on for a chord that belongs to the field the reader is in.
+     * @default false
+     */
+    whileTyping?: boolean;
+}
+/**
+ * Binds keyboard chords outside any one control.
+ *
+ * The map is the same `PlassHotKeys` a field's `hotKeys` prop takes and the
+ * chords are spelled the way `PlHotKeys` draws them, which is the whole point:
+ * a shortcut that is **displayed** on a key cap and a shortcut that is **bound**
+ * are one string rather than two that drift. `Mod` is Command on a Mac and
+ * Control everywhere else.
+ *
+ * `PlCommandPalette` is the hook's first caller — it has bound its own opener
+ * this way since it existed, with a private copy of the matcher — and an
+ * application's own shortcuts are the reason it is public.
+ *
+ * Three rules it shares with the `hotKeys` prop:
+ *
+ * - **A modifier is checked in both directions.** `Enter` does not fire on
+ *   `Shift+Enter`, and `Mod+K` does not fire on `Mod+Shift+K`.
+ * - **A chord that matches is consumed** — `preventDefault()`, so the browser's
+ *   own `Mod+K` search bar does not also open. Read from the other end, an
+ *   event that is **already** consumed is left alone: a field's own `hotKeys`
+ *   map wins over a page's.
+ * - **These are chords rather than letters.** A single unmodified key is
+ *   allowed and is sometimes right (`?` for help), but it is the case
+ *   `whileTyping` is about.
+ *
+ * The handlers are read fresh on every keystroke, so an inline object literal
+ * costs nothing and a handler closing over current state is never stale. What
+ * rebinds the listener is the **set of chords** changing, not the map's
+ * identity.
+ *
+ * @example
+ * usePlHotKeys({
+ *   'Mod+K': () => setPaletteOpen(true),
+ *   'Mod+S': save
+ * });
+ */
+export declare function usePlHotKeys(hotKeys: PlassHotKeys | undefined, options?: PlHotKeysOptions): void;

package/dist/hooks/usePlHotKeys.js

@@ -0,0 +1 @@
+"use client";import*as e from"react";import{editsText as n,hasHardModifier as t,isTypingTarget as r,matchesHotKey as o}from"../internal/keys.js";export function usePlHotKeys(i,u={}){const{enabled:s=!0,target:f,whileTyping:c=!1}=u,l=e.useRef(i);e.useEffect(()=>{l.current=i});const d=Object.keys(i??{}).join("\n");e.useEffect(()=>{const e=function resolve(e){return void 0===e?"undefined"==typeof window?null:window:null===e?null:"current"in e?e.current:e}(f);if(!s||!e||""===d)return;const i=d.split("\n"),onKeyDown=e=>{const u=e;if(!u.defaultPrevented)for(const e of i)if(o(u,e)){if(!c&&!t(e)&&n(u.key)&&r(u.target))return;return u.preventDefault(),void l.current?.[e]?.()}};return e.addEventListener("keydown",onKeyDown),()=>e.removeEventListener("keydown",onKeyDown)},[d,f,s,c])}

package/dist/hooks/usePlMediaQuery.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether the window matches a CSS media query, as a boolean that re-renders
+ * when the answer changes.
+ *
+ * The library has always had this — it is how a `PlSidebar` knows it has become
+ * a drawer and how a `PlAnimate*` finds out that the reader asked for less
+ * motion — and it is public now because the alternative in application code is
+ * a `useState`, an effect and a listener that is nearly always subscribed one
+ * render too late.
+ *
+ * **The first answer in a browser is the server's answer.** There is no window
+ * to measure while the HTML is being generated, so this returns `false` on the
+ * server and through the hydrating render, and the real answer arrives in the
+ * render after that. Anything that has to be right in the *first* frame belongs
+ * in CSS — a Tailwind variant, or the `--plass-*` token that variant sets — and
+ * this hook is for the decisions CSS cannot make, like whether a component
+ * exists at all.
+ *
+ * @example
+ * const coarse = usePlMediaQuery('(pointer: coarse)');
+ */
+export declare function usePlMediaQuery(query: string): boolean;

package/dist/hooks/usePlMediaQuery.js

@@ -0,0 +1 @@
+"use client";import{useMediaQuery as e}from"../internal/media.js";export function usePlMediaQuery(r){return e(r)}

package/dist/hooks/usePlOnScreen.d.ts

@@ -0,0 +1,50 @@
+import * as React from 'react';
+export interface PlOnScreenOptions {
+    /**
+     * How much of the element has to be showing before it counts, from `0` to
+     * `1`.
+     * @default 0
+     */
+    threshold?: number;
+    /**
+     * How far outside the viewport still counts, as a CSS margin — `'200px'`
+     * starts a fetch a screen early.
+     */
+    rootMargin?: string;
+    /**
+     * What it is measured against. The viewport when it is not given; a scrolling
+     * panel otherwise.
+     */
+    root?: React.RefObject<Element | null>;
+    /**
+     * Stops watching the first time it appears.
+     *
+     * On by default, because the question a caller almost always has is "has this
+     * been seen yet" rather than "is it on screen right now" — a lazily loaded
+     * picture, a section that animates once, a page that fetches the next batch.
+     * Turn it off for the answer that keeps changing.
+     * @default true
+     */
+    once?: boolean;
+}
+/**
+ * Whether an element is on screen.
+ *
+ * An `IntersectionObserver` with the three things a hook has to decide, and
+ * the interesting one is `once`. It is **on** by default: the question a caller
+ * almost always has is "has this been seen yet", not "is it on screen right
+ * now", and a hook that kept answering the second one would re-render a page of
+ * lazily loaded pictures every time the reader scrolled past any of them.
+ *
+ * `false` on a server and on the first render, which is the safe answer for
+ * both of the things this is used for: nothing is fetched that did not need to
+ * be, and nothing is played before a reader could see it.
+ *
+ * A browser with no observer is told **yes** rather than no. There is no way to
+ * find out, and a picture that never loads is worse than one that loads early.
+ *
+ * @example
+ * const section = React.useRef<HTMLDivElement>(null);
+ * const seen = usePlOnScreen(section, { rootMargin: '200px' });
+ */
+export declare function usePlOnScreen(target: React.RefObject<Element | null>, { threshold, rootMargin, root, once }?: PlOnScreenOptions): boolean;

package/dist/hooks/usePlOnScreen.js

@@ -0,0 +1 @@
+"use client";import*as e from"react";export function usePlOnScreen(r,{threshold:t=0,rootMargin:n,root:o,once:s=!0}={}){const[c,i]=e.useState(!1);return e.useEffect(()=>{const e=r.current;if(!e)return;if("undefined"==typeof IntersectionObserver)return void i(!0);const c=new IntersectionObserver(([e])=>{e.isIntersecting?(i(!0),s&&c.disconnect()):s||i(!1)},{threshold:t,rootMargin:n,root:o?.current??null});return c.observe(e),()=>c.disconnect()},[r,t,n,o,s]),c}

package/dist/hooks/usePlReducedMotion.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether the reader has asked their platform for less movement.
+ *
+ * `prefers-reduced-motion: reduce`, read as a boolean that re-renders when it
+ * changes. The library answers it on its own behalf everywhere it moves — every
+ * keyframe in the stylesheet is switched off at once, a typewriter simply
+ * arrives finished — and this is the same answer, for the motion an application
+ * writes itself.
+ *
+ * **"Reduced" is not "none", and the library's own components disagree with
+ * each other on purpose.** An entrance is dropped entirely, because an
+ * animation that never played has still delivered everything it was carrying. A
+ * loading indicator is *slowed* rather than stopped, because a spinner that
+ * stopped would be lying about whether anything is still happening. Which of
+ * those two an effect is, is the question to answer before reaching for this.
+ *
+ * The server's answer is `false` — it has no reader and so no preference — and
+ * so is the first answer in a browser. See `usePlMediaQuery` for why, and note
+ * that it is the safe direction here: the reader gets their preference in the
+ * render after hydration, before any of this has had a frame to run in.
+ */
+export declare function usePlReducedMotion(): boolean;

package/dist/hooks/usePlReducedMotion.js

@@ -0,0 +1 @@
+"use client";import{usePrefersReducedMotion as e}from"../internal/media.js";export function usePlReducedMotion(){return e()}

package/dist/index.d.ts

@@ -1,56 +1,85 @@
 export * from './types.js';
+export * from './hooks/index.js';
+export * from './provider/index.js';
 export * from './components/accordion/index.js';
 export * from './components/alert/index.js';
+export * from './components/anchor/index.js';
 export * from './components/animate-appear/index.js';
 export * from './components/animate-blink/index.js';
+export * from './components/animate-counter/index.js';
 export * from './components/animate-fade/index.js';
+export * from './components/animate-float/index.js';
 export * from './components/animate-grow/index.js';
 export * from './components/animate-headline/index.js';
 export * from './components/animate-lighting/index.js';
 export * from './components/animate-marquee/index.js';
+export * from './components/animate-reveal/index.js';
 export * from './components/animate-rotate/index.js';
+export * from './components/animate-scramble/index.js';
+export * from './components/animate-shake/index.js';
 export * from './components/animate-slide/index.js';
+export * from './components/animate-split/index.js';
 export * from './components/animate-typing/index.js';
 export * from './components/animate-zoom/index.js';
+export * from './components/app-logo/index.js';
+export * from './components/area-chart/index.js';
 export * from './components/aspect-ratio/index.js';
 export * from './components/avatar/index.js';
-export * from './components/avatar-group/index.js';
+export * from './components/back-top/index.js';
 export * from './components/badge/index.js';
+export * from './components/bar-chart/index.js';
 export * from './components/blockquote/index.js';
 export * from './components/bottom-navigation/index.js';
 export * from './components/box/index.js';
 export * from './components/breadcrumb/index.js';
 export * from './components/button/index.js';
 export * from './components/button-group/index.js';
+export * from './components/calendar/index.js';
 export * from './components/card/index.js';
 export * from './components/carousel/index.js';
 export * from './components/chat-bubble/index.js';
 export * from './components/checkbox/index.js';
 export * from './components/chip/index.js';
+export * from './components/code-block/index.js';
 export * from './components/collapsible/index.js';
 export * from './components/color-picker/index.js';
 export * from './components/combobox/index.js';
+export * from './components/confirm/index.js';
 export * from './components/command-palette/index.js';
 export * from './components/container/index.js';
+export * from './components/data-list/index.js';
+export * from './components/data-table/index.js';
 export * from './components/date-picker/index.js';
 export * from './components/date-range-picker/index.js';
 export * from './components/date-time-picker/index.js';
 export * from './components/divider/index.js';
 export * from './components/drawer/index.js';
+export * from './components/empty/index.js';
 export * from './components/fieldset/index.js';
 export * from './components/file-picker/index.js';
+export * from './components/flex/index.js';
+export * from './components/floating-action-button/index.js';
 export * from './components/floating-bottom-navigation/index.js';
 export * from './components/footer/index.js';
 export * from './components/form/index.js';
+export * from './components/gallery/index.js';
+export * from './components/gauge-chart/index.js';
 export * from './components/grid/index.js';
 export * from './components/header/index.js';
+export * from './components/heatmap-chart/index.js';
 export * from './components/highlight/index.js';
 export * from './components/hot-keys/index.js';
+export * from './components/hover-card/index.js';
+export * from './components/how-to-steps/index.js';
 export * from './components/icon/index.js';
 export * from './components/icon-button/index.js';
+export * from './components/image/index.js';
+export * from './components/line-chart/index.js';
 export * from './components/list/index.js';
 export * from './components/menu/index.js';
 export * from './components/menubar/index.js';
+export * from './components/meter/index.js';
+export * from './components/mockup/index.js';
 export * from './components/modal/index.js';
 export * from './components/navigation-menu/index.js';
 export * from './components/number-field/index.js';
@@ -59,20 +88,30 @@ export * from './components/overlay/index.js';
 export * from './components/page-layout/index.js';
 export * from './components/pagination/index.js';
 export * from './components/panes/index.js';
+export * from './components/pie-chart/index.js';
 export * from './components/pill/index.js';
+export * from './components/popconfirm/index.js';
 export * from './components/popover/index.js';
+export * from './components/portal/index.js';
 export * from './components/progress-box/index.js';
 export * from './components/progress-circular/index.js';
 export * from './components/progress-linear/index.js';
 export * from './components/radio-group/index.js';
 export * from './components/rating/index.js';
+export * from './components/scatter-chart/index.js';
+export * from './components/scroll-area/index.js';
 export * from './components/scroll-zone/index.js';
 export * from './components/segmented-button/index.js';
 export * from './components/select/index.js';
+export * from './components/show/index.js';
 export * from './components/sidebar/index.js';
 export * from './components/skeleton/index.js';
 export * from './components/slider/index.js';
+export * from './components/sparkline/index.js';
 export * from './components/spoiler/index.js';
+export * from './components/stack/index.js';
+export * from './components/stat/index.js';
+export * from './components/stepper/index.js';
 export * from './components/switch/index.js';
 export * from './components/table/index.js';
 export * from './components/tabs/index.js';
@@ -80,9 +119,15 @@ export * from './components/text-field/index.js';
 export * from './components/text-link/index.js';
 export * from './components/time-picker/index.js';
 export * from './components/timeline/index.js';
+export * from './components/timeline-chart/index.js';
 export * from './components/toast/index.js';
 export * from './components/toggle/index.js';
 export * from './components/toolbar/index.js';
 export * from './components/tooltip/index.js';
+export * from './components/tour/index.js';
+export * from './components/tree/index.js';
+export * from './components/tree-select/index.js';
 export * from './components/transfer/index.js';
 export * from './components/typography/index.js';
+export * from './components/visually-hidden/index.js';
+export * from './components/window-pane/index.js';

package/dist/index.js

@@ -1 +1 @@
-export*from"./types.js";export*from"./components/accordion/index.js";export*from"./components/alert/index.js";export*from"./components/animate-appear/index.js";export*from"./components/animate-blink/index.js";export*from"./components/animate-fade/index.js";export*from"./components/animate-grow/index.js";export*from"./components/animate-headline/index.js";export*from"./components/animate-lighting/index.js";export*from"./components/animate-marquee/index.js";export*from"./components/animate-rotate/index.js";export*from"./components/animate-slide/index.js";export*from"./components/animate-typing/index.js";export*from"./components/animate-zoom/index.js";export*from"./components/aspect-ratio/index.js";export*from"./components/avatar/index.js";export*from"./components/avatar-group/index.js";export*from"./components/badge/index.js";export*from"./components/blockquote/index.js";export*from"./components/bottom-navigation/index.js";export*from"./components/box/index.js";export*from"./components/breadcrumb/index.js";export*from"./components/button/index.js";export*from"./components/button-group/index.js";export*from"./components/card/index.js";export*from"./components/carousel/index.js";export*from"./components/chat-bubble/index.js";export*from"./components/checkbox/index.js";export*from"./components/chip/index.js";export*from"./components/collapsible/index.js";export*from"./components/color-picker/index.js";export*from"./components/combobox/index.js";export*from"./components/command-palette/index.js";export*from"./components/container/index.js";export*from"./components/date-picker/index.js";export*from"./components/date-range-picker/index.js";export*from"./components/date-time-picker/index.js";export*from"./components/divider/index.js";export*from"./components/drawer/index.js";export*from"./components/fieldset/index.js";export*from"./components/file-picker/index.js";export*from"./components/floating-bottom-navigation/index.js";export*from"./components/footer/index.js";export*from"./components/form/index.js";export*from"./components/grid/index.js";export*from"./components/header/index.js";export*from"./components/highlight/index.js";export*from"./components/hot-keys/index.js";export*from"./components/icon/index.js";export*from"./components/icon-button/index.js";export*from"./components/list/index.js";export*from"./components/menu/index.js";export*from"./components/menubar/index.js";export*from"./components/modal/index.js";export*from"./components/navigation-menu/index.js";export*from"./components/number-field/index.js";export*from"./components/otp-field/index.js";export*from"./components/overlay/index.js";export*from"./components/page-layout/index.js";export*from"./components/pagination/index.js";export*from"./components/panes/index.js";export*from"./components/pill/index.js";export*from"./components/popover/index.js";export*from"./components/progress-box/index.js";export*from"./components/progress-circular/index.js";export*from"./components/progress-linear/index.js";export*from"./components/radio-group/index.js";export*from"./components/rating/index.js";export*from"./components/scroll-zone/index.js";export*from"./components/segmented-button/index.js";export*from"./components/select/index.js";export*from"./components/sidebar/index.js";export*from"./components/skeleton/index.js";export*from"./components/slider/index.js";export*from"./components/spoiler/index.js";export*from"./components/switch/index.js";export*from"./components/table/index.js";export*from"./components/tabs/index.js";export*from"./components/text-field/index.js";export*from"./components/text-link/index.js";export*from"./components/time-picker/index.js";export*from"./components/timeline/index.js";export*from"./components/toast/index.js";export*from"./components/toggle/index.js";export*from"./components/toolbar/index.js";export*from"./components/tooltip/index.js";export*from"./components/transfer/index.js";export*from"./components/typography/index.js";
+export*from"./types.js";export*from"./hooks/index.js";export*from"./provider/index.js";export*from"./components/accordion/index.js";export*from"./components/alert/index.js";export*from"./components/anchor/index.js";export*from"./components/animate-appear/index.js";export*from"./components/animate-blink/index.js";export*from"./components/animate-counter/index.js";export*from"./components/animate-fade/index.js";export*from"./components/animate-float/index.js";export*from"./components/animate-grow/index.js";export*from"./components/animate-headline/index.js";export*from"./components/animate-lighting/index.js";export*from"./components/animate-marquee/index.js";export*from"./components/animate-reveal/index.js";export*from"./components/animate-rotate/index.js";export*from"./components/animate-scramble/index.js";export*from"./components/animate-shake/index.js";export*from"./components/animate-slide/index.js";export*from"./components/animate-split/index.js";export*from"./components/animate-typing/index.js";export*from"./components/animate-zoom/index.js";export*from"./components/app-logo/index.js";export*from"./components/area-chart/index.js";export*from"./components/aspect-ratio/index.js";export*from"./components/avatar/index.js";export*from"./components/back-top/index.js";export*from"./components/badge/index.js";export*from"./components/bar-chart/index.js";export*from"./components/blockquote/index.js";export*from"./components/bottom-navigation/index.js";export*from"./components/box/index.js";export*from"./components/breadcrumb/index.js";export*from"./components/button/index.js";export*from"./components/button-group/index.js";export*from"./components/calendar/index.js";export*from"./components/card/index.js";export*from"./components/carousel/index.js";export*from"./components/chat-bubble/index.js";export*from"./components/checkbox/index.js";export*from"./components/chip/index.js";export*from"./components/code-block/index.js";export*from"./components/collapsible/index.js";export*from"./components/color-picker/index.js";export*from"./components/combobox/index.js";export*from"./components/confirm/index.js";export*from"./components/command-palette/index.js";export*from"./components/container/index.js";export*from"./components/data-list/index.js";export*from"./components/data-table/index.js";export*from"./components/date-picker/index.js";export*from"./components/date-range-picker/index.js";export*from"./components/date-time-picker/index.js";export*from"./components/divider/index.js";export*from"./components/drawer/index.js";export*from"./components/empty/index.js";export*from"./components/fieldset/index.js";export*from"./components/file-picker/index.js";export*from"./components/flex/index.js";export*from"./components/floating-action-button/index.js";export*from"./components/floating-bottom-navigation/index.js";export*from"./components/footer/index.js";export*from"./components/form/index.js";export*from"./components/gallery/index.js";export*from"./components/gauge-chart/index.js";export*from"./components/grid/index.js";export*from"./components/header/index.js";export*from"./components/heatmap-chart/index.js";export*from"./components/highlight/index.js";export*from"./components/hot-keys/index.js";export*from"./components/hover-card/index.js";export*from"./components/how-to-steps/index.js";export*from"./components/icon/index.js";export*from"./components/icon-button/index.js";export*from"./components/image/index.js";export*from"./components/line-chart/index.js";export*from"./components/list/index.js";export*from"./components/menu/index.js";export*from"./components/menubar/index.js";export*from"./components/meter/index.js";export*from"./components/mockup/index.js";export*from"./components/modal/index.js";export*from"./components/navigation-menu/index.js";export*from"./components/number-field/index.js";export*from"./components/otp-field/index.js";export*from"./components/overlay/index.js";export*from"./components/page-layout/index.js";export*from"./components/pagination/index.js";export*from"./components/panes/index.js";export*from"./components/pie-chart/index.js";export*from"./components/pill/index.js";export*from"./components/popconfirm/index.js";export*from"./components/popover/index.js";export*from"./components/portal/index.js";export*from"./components/progress-box/index.js";export*from"./components/progress-circular/index.js";export*from"./components/progress-linear/index.js";export*from"./components/radio-group/index.js";export*from"./components/rating/index.js";export*from"./components/scatter-chart/index.js";export*from"./components/scroll-area/index.js";export*from"./components/scroll-zone/index.js";export*from"./components/segmented-button/index.js";export*from"./components/select/index.js";export*from"./components/show/index.js";export*from"./components/sidebar/index.js";export*from"./components/skeleton/index.js";export*from"./components/slider/index.js";export*from"./components/sparkline/index.js";export*from"./components/spoiler/index.js";export*from"./components/stack/index.js";export*from"./components/stat/index.js";export*from"./components/stepper/index.js";export*from"./components/switch/index.js";export*from"./components/table/index.js";export*from"./components/tabs/index.js";export*from"./components/text-field/index.js";export*from"./components/text-link/index.js";export*from"./components/time-picker/index.js";export*from"./components/timeline/index.js";export*from"./components/timeline-chart/index.js";export*from"./components/toast/index.js";export*from"./components/toggle/index.js";export*from"./components/toolbar/index.js";export*from"./components/tooltip/index.js";export*from"./components/tour/index.js";export*from"./components/tree/index.js";export*from"./components/tree-select/index.js";export*from"./components/transfer/index.js";export*from"./components/typography/index.js";export*from"./components/visually-hidden/index.js";export*from"./components/window-pane/index.js";

package/dist/internal/animate.d.ts

@@ -25,15 +25,27 @@
  * `rotate` properties rather than on the `transform` shorthand, so a caller's
  * own transform on the same element survives.
  *
+ * ## Telling the children apart
+ *
+ * `stagger`, `durationStep` and `reverse` move an effect off the box and onto
+ * the things inside it, one after another. There is no `PlAnimateStagger`
+ * component and there should not be: a stagger is a *differential* rather than
+ * an effect, and a wrapper would be a second way to spell something all six
+ * effects can already say. `animateChildren` and `staggerSlots` are what
+ * `PlAnimateAppear` — which was staggering long before the six could — now runs
+ * on as well, because two implementations of "one after another" is two
+ * opinions about the arithmetic.
+ *
  * ## 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.
+ * and their logic stays in their own files. They are also the four that cannot
+ * take a `stagger`, for the same reason: their children are already spoken for.
  */
 import * as React from 'react';
-import type { PlassAnimateRepeat, PlassAnimateTrigger, PlassAnimation, PlassSide } from '../types.js';
+import type { PlassAnimateRepeat, PlassAnimateStaggerProps, PlassAnimateTimelineProps, PlassAnimateTrigger, PlassAnimation, PlassSide } from '../types.js';
 /**
  * Which keyframe an effect runs.
  *
@@ -59,7 +71,15 @@ export declare function isInfinite(repeat: PlassAnimateRepeat | undefined): bool
  * is `both`, so a faded-out element stays faded out instead of snapping back.
  */
 export declare function directionValue(mode: 'in' | 'out', alternate: boolean | undefined): string;
-export interface AnimationSlotOptions {
+/**
+ * Where a scroll-linked effect starts and finishes, as an `animation-range`.
+ *
+ * Finished while the element is still arriving rather than when it reaches the
+ * middle of the screen: an entrance that is only half drawn by the time a
+ * reader has read past it is an entrance that never happened.
+ */
+export declare const defaultViewRange = "entry 0% cover 45%";
+export interface AnimationSlotOptions extends PlassAnimateTimelineProps {
     duration: number;
     delay: number;
     easing?: string;
@@ -73,6 +93,8 @@ export interface AnimationSlotOptions {
     y?: string;
     angle?: string;
     angleTo?: string;
+    /** The `clip-path` a reveal is uncovered from. */
+    clip?: string;
 }
 /**
  * The `--p-anim-*` slots, as an inline style object.
@@ -82,6 +104,14 @@ export interface AnimationSlotOptions {
  * has never seen written down.
  */
 export declare function animationSlots(options: AnimationSlotOptions): React.CSSProperties;
+/**
+ * The `clip-path` a reveal starts from, given the edge it uncovers from.
+ *
+ * `inset()` takes its four sides in the physical order CSS writes them, and
+ * `PlassSide` is physical for the same reason it is on a slide: a title wiped
+ * in from the top is wiped in from the top in every writing direction.
+ */
+export declare function revealClip(from: PlassSide): string;
 /**
  * Which way a slide starts, given the edge it comes from.
  *
@@ -93,7 +123,6 @@ export declare function slideOffsets(from: PlassSide, distance: number | string)
     x: string;
     y: string;
 };
-export declare function usePrefersReducedMotion(): boolean;
 export interface AnimationRunOptions {
     trigger: PlassAnimateTrigger;
     play?: boolean;
@@ -102,6 +131,17 @@ export interface AnimationRunOptions {
     paused?: boolean;
     /** An infinite effect stops when the pointer leaves; a finite one finishes. */
     infinite: boolean;
+    /**
+     * A value that plays the effect again whenever it changes, and never on the
+     * first render.
+     *
+     * `play` is a boolean, so replaying with it means toggling off and on — two
+     * renders for one event, and a piece of state whose only job is to be
+     * flipped back. A response to something that can happen twice needs the
+     * *event*, and a value that has changed is the closest React has to one: a
+     * count of failed attempts already is this.
+     */
+    nonce?: unknown;
 }
 export interface AnimationRun {
     /** Goes on the animated element. */
@@ -132,10 +172,53 @@ export interface AnimationRun {
  * style to settle, and putting it back is the one move that rewinds the element
  * and leaves everything inside it alone.
  */
-export declare function useAnimationRun({ trigger, play, once, threshold, paused, infinite }: AnimationRunOptions): AnimationRun;
-export interface AnimateElementParams extends AnimationSlotOptions, AnimationRunOptions {
+export declare function useAnimationRun({ trigger, play, once, threshold, paused, infinite, nonce }: AnimationRunOptions): AnimationRun;
+export interface StaggerPosition extends Required<PlassAnimateStaggerProps> {
+    index: number;
+    count: number;
+}
+/**
+ * Where one child sits in a staggered run.
+ *
+ * `reverse` turns the *order* round and nothing else: the last child goes
+ * first and every child still plays forwards. An effect that ran backwards is
+ * `mode="out"`, which is a different question and already has an answer.
+ *
+ * The duration is floored at zero rather than allowed to go negative, because a
+ * negative `animation-duration` is invalid and an invalid declaration is
+ * dropped — which would leave that one child playing at the CSS default while
+ * its neighbours honoured the prop.
+ */
+export declare function staggerSlots(slots: AnimationSlotOptions, { index, count, stagger, durationStep, reverse }: StaggerPosition): AnimationSlotOptions;
+/**
+ * Writes one effect onto each child, with that child's own slots.
+ *
+ * Onto the children **themselves** rather than onto wrappers around them, which
+ * is the whole reason this is worth sharing: a row of `<li>`s stays a row of
+ * `<li>`s, a grid's cells stay its direct children, and nothing about the
+ * layout changes because the set is being animated. A wrapper per child would
+ * break every one of those.
+ *
+ * The trade is the one `React.cloneElement` always makes — a child has to
+ * accept a `className` and a `style` — and it is taken here and nowhere else in
+ * the library. It is bearable because what is being copied is *only* the
+ * animation, so a child that ignores both is a child that does not animate,
+ * rather than a child that lands in the wrong place. `PlStack` draws a wrapper
+ * per item instead, and takes the layout cost, precisely because *there* the
+ * failure would not be survivable: a child that dropped the class would land in
+ * the wrong place rather than merely arriving without an entrance.
+ *
+ * A bare string has no element to write onto, so that one is wrapped in a
+ * `<span>`. It is the only case that gets a wrapper.
+ */
+export declare function animateChildren(children: React.ReactNode, className: string, slotsFor: (index: number, count: number) => React.CSSProperties): React.ReactNode[];
+export interface AnimateElementParams extends AnimationSlotOptions, AnimationRunOptions, PlassAnimateStaggerProps {
     /** Which keyframe. `null` for the components that write their own. */
     effect: PlassAnimation | null;
+    /** `transform-origin`, for the two effects that turn about a point. */
+    origin?: string;
+    /** Needed only to be handed back staggered. Passed straight through otherwise. */
+    children?: React.ReactNode;
 }
 export interface AnimateElement {
     ref: React.RefCallback<HTMLElement>;
@@ -143,6 +226,8 @@ export interface AnimateElement {
     style: React.CSSProperties;
     /** The hover handlers and the two data attributes, ready to be spread. */
     props: React.HTMLAttributes<HTMLElement> & Record<string, unknown>;
+    /** The children, with the effect written onto them if it was staggered. */
+    children: React.ReactNode;
 }
 /**
  * Everything a one-keyframe `PlAnimate*` root needs, in one call.

package/dist/internal/animate.js

@@ -1 +1 @@
-import*as e from"react";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"};export const animBaseClass="plass-anim";export function lengthValue(e){return"number"==typeof e?`${e}px`:e}export function repeatValue(e){return"infinite"===e?"infinite":String(e)}export function isInfinite(e){return"infinite"===e}export function directionValue(e,n){return"out"===e?n?"alternate-reverse":"reverse":n?"alternate":"normal"}export function animationSlots(e){const n={"--p-anim-duration":`${e.duration}ms`,"--p-anim-delay":`${e.delay}ms`,"--p-anim-repeat":repeatValue(e.repeat),"--p-anim-direction":directionValue(e.mode??"in",e.alternate)};return e.easing&&(n["--p-anim-ease"]=e.easing),void 0!==e.opacity&&(n["--p-anim-opacity"]=String(e.opacity)),void 0!==e.scale&&(n["--p-anim-scale"]=String(e.scale)),void 0!==e.x&&(n["--p-anim-x"]=e.x),void 0!==e.y&&(n["--p-anim-y"]=e.y),void 0!==e.angle&&(n["--p-anim-angle"]=e.angle),void 0!==e.angleTo&&(n["--p-anim-angle-to"]=e.angleTo),n}export function slideOffsets(e,n){const t=lengthValue(n),a="number"==typeof n?-n+"px":`calc(-1 * ${t})`;switch(e){case"top":return{x:"0px",y:a};case"bottom":return{x:"0px",y:t};case"left":return{x:a,y:"0px"};default:return{x:t,y:"0px"}}}const n="(prefers-reduced-motion: reduce)";function subscribeToMotion(e){if("undefined"==typeof window||!window.matchMedia)return()=>{};const t=window.matchMedia(n);return t.addEventListener("change",e),()=>t.removeEventListener("change",e)}function readMotion(){return!("undefined"==typeof window||!window.matchMedia)&&window.matchMedia(n).matches}function motionOnServer(){return!1}export function usePrefersReducedMotion(){return e.useSyncExternalStore(subscribeToMotion,readMotion,motionOnServer)}export function useAnimationRun({trigger:n,play:t,once:a,threshold:i,paused:o,infinite:r}){const s=e.useRef(null),[u,c]=e.useState("mount"===n),[l,p]=e.useState(0),d=e.useCallback(()=>{c(!0),p(e=>e+1)},[]);e.useLayoutEffect(()=>{const e=s.current;if(!e||0===l)return;const n=[e,...e.querySelectorAll(".plass-anim, .plass-marquee-track")];for(const e of n)e.style.animationName="none";e.offsetWidth;for(const e of n)e.style.animationName=""},[l]),e.useEffect(()=>{if("visible"!==n)return;const e=s.current;if(!e||"undefined"==typeof IntersectionObserver)return void c(!0);const t=new IntersectionObserver(([e])=>{e.isIntersecting?(d(),a&&t.disconnect()):a||c(!1)},{threshold:i});return t.observe(e),()=>t.disconnect()},[n,a,i,d]),e.useEffect(()=>{"manual"===n&&(t?d():c(!1))},[n,t,d]);const f="hover"===n?{onPointerEnter:d,onFocus:d,onPointerLeave:()=>{r&&c(!1)},onBlur:()=>{r&&c(!1)}}:{};return{ref:e.useCallback(e=>{s.current=e},[]),state:u&&!o?"running":"paused",started:u,handlers:f}}export function useAnimateElement(e){const{effect:n,trigger:t,play:a,once:i,threshold:o,paused:r,infinite:s,...u}=e,c=useAnimationRun({trigger:t,play:a,once:i,threshold:o,paused:r,infinite:s});return{ref:c.ref,className:n?`plass-anim ${animationClasses[n]}`:"",style:{...animationSlots(u),"--p-anim-state":c.state},props:{...c.handlers,"data-plass-animation":n??void 0,"data-state":c.state}}}
+import*as e from"react";import{cx as n}from"./styles.js";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",reveal:"plass-anim-reveal"};export const animBaseClass="plass-anim";export function lengthValue(e){return"number"==typeof e?`${e}px`:e}export function repeatValue(e){return"infinite"===e?"infinite":String(e)}export function isInfinite(e){return"infinite"===e}export function directionValue(e,n){return"out"===e?n?"alternate-reverse":"reverse":n?"alternate":"normal"}export const defaultViewRange="entry 0% cover 45%";export function animationSlots(e){const n={"--p-anim-duration":`${e.duration}ms`,"--p-anim-delay":`${e.delay}ms`,"--p-anim-repeat":repeatValue(e.repeat),"--p-anim-direction":directionValue(e.mode??"in",e.alternate)};return e.easing&&(n["--p-anim-ease"]=e.easing),"view"===e.timeline&&(n["--p-anim-timeline"]="view()",n["--p-anim-range"]=e.range??defaultViewRange),void 0!==e.opacity&&(n["--p-anim-opacity"]=String(e.opacity)),void 0!==e.scale&&(n["--p-anim-scale"]=String(e.scale)),void 0!==e.x&&(n["--p-anim-x"]=e.x),void 0!==e.y&&(n["--p-anim-y"]=e.y),void 0!==e.angle&&(n["--p-anim-angle"]=e.angle),void 0!==e.angleTo&&(n["--p-anim-angle-to"]=e.angleTo),void 0!==e.clip&&(n["--p-anim-clip"]=e.clip),n}export function revealClip(e){switch(e){case"top":return"inset(0 0 100% 0)";case"bottom":return"inset(100% 0 0 0)";case"right":return"inset(0 0 0 100%)";default:return"inset(0 100% 0 0)"}}export function slideOffsets(e,n){const t=lengthValue(n),a="number"==typeof n?-n+"px":`calc(-1 * ${t})`;switch(e){case"top":return{x:"0px",y:a};case"bottom":return{x:"0px",y:t};case"left":return{x:a,y:"0px"};default:return{x:t,y:"0px"}}}export function useAnimationRun({trigger:n,play:t,once:a,threshold:i,paused:r,infinite:s,nonce:o}){const l=e.useRef(null),[c,u]=e.useState("mount"===n),[p,m]=e.useState(0),d=e.useCallback(()=>{u(!0),m(e=>e+1)},[]);e.useLayoutEffect(()=>{const e=l.current;if(!e||0===p)return;const n=[e,...e.querySelectorAll(".plass-anim, .plass-marquee-track")];for(const e of n)e.style.animationName="none";e.offsetWidth;for(const e of n)e.style.animationName=""},[p]),e.useEffect(()=>{if("visible"!==n)return;const e=l.current;if(!e||"undefined"==typeof IntersectionObserver)return void u(!0);const t=new IntersectionObserver(([e])=>{e.isIntersecting?(d(),a&&t.disconnect()):a||u(!1)},{threshold:i});return t.observe(e),()=>t.disconnect()},[n,a,i,d]);const f=e.useRef(o);e.useEffect(()=>{Object.is(o,f.current)||(f.current=o,d())},[o,d]),e.useEffect(()=>{"manual"===n&&(t?d():u(!1))},[n,t,d]);const g="hover"===n?{onPointerEnter:d,onFocus:d,onPointerLeave:()=>{s&&u(!1)},onBlur:()=>{s&&u(!1)}}:{};return{ref:e.useCallback(e=>{l.current=e},[]),state:c&&!r?"running":"paused",started:c,handlers:g}}export function staggerSlots(e,{index:n,count:t,stagger:a,durationStep:i,reverse:r}){const s=r?t-1-n:n;return{...e,delay:e.delay+s*a,duration:Math.max(0,e.duration+s*i)}}export function animateChildren(t,a,i){const r=e.Children.toArray(t);return r.map((t,s)=>{const o=i(s,r.length);if(!e.isValidElement(t))return e.createElement("span",{key:s,className:a,style:o},t);const l=t.props;return e.cloneElement(t,{className:n(a,l.className),style:{...o,...l.style}})})}export function useAnimateElement(e){const{effect:n,trigger:t,play:a,once:i,threshold:r,paused:s,infinite:o,nonce:l,stagger:c=0,durationStep:u=0,reverse:p=!1,origin:m,children:d,...f}=e,g=useAnimationRun({trigger:"view"===f.timeline?"mount":t,play:a,once:i,threshold:r,paused:s,infinite:o,nonce:l}),y=n?`plass-anim ${animationClasses[n]}`:"",x=0!==c&&null!==n,v=void 0===m?null:{transformOrigin:m};return{ref:g.ref,className:x?"":y,style:{...v,...x?null:animationSlots(f),"--p-anim-state":g.state},props:{...g.handlers,"data-plass-animation":n??void 0,"data-state":g.state},children:x?animateChildren(d,y,(e,n)=>({...v,...animationSlots(staggerSlots(f,{index:e,count:n,stagger:c,durationStep:u,reverse:p}))})):d}}