material-plus-ui 1.5.0 → 1.7.0

package/dist/components/typography/MPTypography.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { useRender } from '@base-ui/react/use-render';
-import type { MPColor } from '../../types.js';
+import type { MPColor, MPTransition } from '../../types.js';
 /**
  * What a piece of text *is*, which decides both its type scale and the element
  * it renders as.
@@ -40,6 +40,13 @@ export interface MPTypographyProps extends Omit<React.ComponentPropsWithoutRef<'
      * has **no default**: prose inherits the surface's own ink unless a role is
      * asked for, because the common case for a paragraph is to look like the
      * paragraphs around it.
+     *
+     * No default means no declaration, not a quiet one. Nothing here writes a
+     * `color` until this prop is passed, so a `text-white` on the dark section
+     * above wins by simply being the only thing that spoke — and a role outside
+     * the four accents is a `className` away: `className="text-mp-on-surface-variant"`
+     * on a `caption` is the muted line this component used to hand out whether or
+     * not it was wanted.
      */
     color?: MPColor;
     /**
@@ -70,6 +77,15 @@ export interface MPTypographyProps extends Omit<React.ComponentPropsWithoutRef<'
      */
     render?: useRender.RenderProp;
     children?: React.ReactNode;
+    /**
+     * An entrance, run once as it mounts.
+     *
+     * `transition="fade"` is the whole of what most callers want; the object form
+     * takes a duration, an edge to come from, or a scale to start at. Anything
+     * that has to run again — on scroll, on hover, under your own control — is an
+     * [MPAnimateFade](../motion/animate-fade) and its siblings.
+     */
+    transition?: MPTransition;
 }
 /**
  * Text at one of Material's type roles.

package/dist/components/typography/MPTypography.js

@@ -1,2 +1,2 @@
 "use client";
-import*as p from"react";import{useRender as t}from"@base-ui/react/use-render";import{accentSlots as e}from"../../internal/accent.js";const r={h1:"[&.mp-typography]:text-mp-display-small",h2:"[&.mp-typography]:text-mp-headline-large",h3:"[&.mp-typography]:text-mp-headline-medium",h4:"[&.mp-typography]:text-mp-headline-small",h5:"[&.mp-typography]:text-mp-title-large",h6:"[&.mp-typography]:text-mp-title-medium",lead:"[&.mp-typography]:text-mp-title-large",body:"[&.mp-typography]:text-mp-body-large",caption:"[&.mp-typography]:text-mp-body-small",overline:"[&.mp-typography]:text-mp-label-small [&.mp-typography]:tracking-[0.08em] uppercase"},a={h1:"regular",h2:"regular",h3:"regular",h4:"regular",h5:"regular",h6:"medium",lead:"regular",body:"regular",caption:"regular",overline:"medium"},m={h1:"h1",h2:"h2",h3:"h3",h4:"h4",h5:"h5",h6:"h6",lead:"p",body:"p",caption:"span",overline:"span"},o=new Set(["caption","overline"]),y={h1:"[&.mp-typography]:mb-4",h2:"[&.mp-typography]:mb-3.5",h3:"[&.mp-typography]:mb-3",h4:"[&.mp-typography]:mb-2.5",h5:"[&.mp-typography]:mb-2",h6:"[&.mp-typography]:mb-2",lead:"[&.mp-typography]:mb-4",body:"[&.mp-typography]:mb-3",caption:"[&.mp-typography]:mb-2",overline:"[&.mp-typography]:mb-2"},h="[&.mp-typography]:mt-0 [&.mp-typography]:ms-0 [&.mp-typography]:me-0",l={regular:"[&.mp-typography]:font-normal",medium:"[&.mp-typography]:font-medium",semibold:"[&.mp-typography]:font-semibold",bold:"[&.mp-typography]:font-bold"},n={start:"text-start",center:"text-center",end:"text-end",justify:"text-justify"},g={1:"truncate",2:"line-clamp-2",3:"line-clamp-3",4:"line-clamp-4",5:"line-clamp-5",6:"line-clamp-6"};export const MPTypography=/*@__PURE__*/p.forwardRef(function({level:i="body",color:c,weight:d,align:s,lines:u,gutter:b=!1,render:x,className:f,style:v,children:j,...w},N){const k=["mp-typography",r[i],l[d??a[i]],h,b?y[i]:"[&.mp-typography]:mb-0",s?n[s]:"",u?g[u]??"line-clamp-6":"",c?"[&.mp-typography]:text-(--_mp-accent)":o.has(i)?"[&.mp-typography]:text-mp-on-surface-variant":"[&.mp-typography]:text-mp-on-surface",f??""].filter(Boolean).join(" ");return t({render:x??p.createElement(m[i]),ref:N,props:{className:k,style:c?{...e(c),...v}:v,children:j,...w}})});
+import*as p from"react";import{useRender as t}from"@base-ui/react/use-render";import{accentSlots as e}from"../../internal/accent.js";import{transitionProps as r}from"../../internal/transition.js";const a={h1:"[&.mp-typography]:text-mp-display-small",h2:"[&.mp-typography]:text-mp-headline-large",h3:"[&.mp-typography]:text-mp-headline-medium",h4:"[&.mp-typography]:text-mp-headline-small",h5:"[&.mp-typography]:text-mp-title-large",h6:"[&.mp-typography]:text-mp-title-medium",lead:"[&.mp-typography]:text-mp-title-large",body:"[&.mp-typography]:text-mp-body-large",caption:"[&.mp-typography]:text-mp-body-small",overline:"[&.mp-typography]:text-mp-label-small [&.mp-typography]:tracking-[0.08em] uppercase"},m={h1:"regular",h2:"regular",h3:"regular",h4:"regular",h5:"regular",h6:"medium",lead:"regular",body:"regular",caption:"regular",overline:"medium"},o={h1:"h1",h2:"h2",h3:"h3",h4:"h4",h5:"h5",h6:"h6",lead:"p",body:"p",caption:"span",overline:"span"},y={h1:"[&.mp-typography]:mb-4",h2:"[&.mp-typography]:mb-3.5",h3:"[&.mp-typography]:mb-3",h4:"[&.mp-typography]:mb-2.5",h5:"[&.mp-typography]:mb-2",h6:"[&.mp-typography]:mb-2",lead:"[&.mp-typography]:mb-4",body:"[&.mp-typography]:mb-3",caption:"[&.mp-typography]:mb-2",overline:"[&.mp-typography]:mb-2"},l="[&.mp-typography]:mt-0 [&.mp-typography]:ms-0 [&.mp-typography]:me-0",h={regular:"[&.mp-typography]:font-normal",medium:"[&.mp-typography]:font-medium",semibold:"[&.mp-typography]:font-semibold",bold:"[&.mp-typography]:font-bold"},n={start:"text-start",center:"text-center",end:"text-end",justify:"text-justify"},i={1:"truncate",2:"line-clamp-2",3:"line-clamp-3",4:"line-clamp-4",5:"line-clamp-5",6:"line-clamp-6"};export const MPTypography=/*@__PURE__*/p.forwardRef(function({level:g="body",color:s,weight:c,align:d,lines:b,gutter:u=!1,render:x,transition:f,className:j,style:v,children:N,...$},w){const k=r(f),B=["mp-typography",a[g],h[c??m[g]],l,u?y[g]:"[&.mp-typography]:mb-0",d?n[d]:"",b?i[b]??"line-clamp-6":"",s?"[&.mp-typography]:text-(--_mp-accent)":"",j??""].filter(Boolean).join(" ");return t({render:x??p.createElement(o[g]),ref:w,props:{className:`${B}${k.className?` ${k.className}`:""}`,style:s?{...e(s),...k.style,...v}:{...k.style,...v},children:N,...$}})});

package/dist/components/visually-hidden/MPVisuallyHidden.d.ts

@@ -0,0 +1,60 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+export interface MPVisuallyHiddenProps extends React.ComponentPropsWithoutRef<'span'> {
+    /** Renders something other than a `<span>`. Base UI's own escape hatch. */
+    render?: useRender.RenderProp;
+    children?: React.ReactNode;
+}
+/**
+ * Text for a screen reader and nobody else.
+ *
+ * The sentence behind a bare number on a badge, the "opens in a new tab" after a
+ * link's label, the name an avatar's initials stand in for, the direction a
+ * sorted column is sorted in. In every one of those the visible mark is a
+ * shorthand a reader who can see it expands instantly and a reader who cannot
+ * gets nothing at all from.
+ *
+ * ```tsx
+ * <button>
+ *   <MPIcon icon={ICONS.close} />
+ *   <MPVisuallyHidden>Close this dialog</MPVisuallyHidden>
+ * </button>
+ * ```
+ *
+ * Nine components in this library were already drawing themselves with it —
+ * `MPPagination`'s live region, `MPRating`'s radios, `MPShortcut`'s key names,
+ * `MPCarousel`'s slide announcement — and an application putting a bare glyph in
+ * a button of its own had no way to reach the same treatment. It had the rule,
+ * not the name.
+ *
+ * ## Not `hidden`, not `display: none`, not `opacity: 0`
+ *
+ * The first two take the text off the accessibility tree along with the screen,
+ * which is the opposite of what is wanted, and the third leaves a clickable ghost
+ * the size of the words. A 1px clipped box is the one form that is invisible to
+ * a sighted reader and present to every other kind.
+ *
+ * ## Why not `sr-only`
+ *
+ * Which is Tailwind's own utility for this, and it is what the rule below is
+ * written out from. It is written out because `sr-only` is *generated*: a
+ * project running its own Tailwind build with a `prefix` configured generates it
+ * under a different name, and a component that hardcoded `sr-only` would come
+ * out visible on their page. The arbitrary properties survive any prefix.
+ *
+ * ## It stays in the layout
+ *
+ * `position: absolute`, so it takes no room — but it is still *in* the document,
+ * which is the whole point: it is read in the order it is written. Put it where
+ * the sentence belongs rather than at the end of the block.
+ *
+ * ## Sharp edges
+ *
+ * - **A focusable thing inside this stays focusable**, and a reader tabbing into
+ *   it lands somewhere they cannot see. Anything that can take focus wants
+ *   `aria-label` on the control instead.
+ * - **It is not a live region.** Text swapped inside it is not announced unless
+ *   the element also carries `aria-live` — which is exactly what the components
+ *   above pass through.
+ */
+export declare const MPVisuallyHidden: React.ForwardRefExoticComponent<MPVisuallyHiddenProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/visually-hidden/MPVisuallyHidden.js

@@ -0,0 +1,2 @@
+"use client";
+import{jsx as r}from"react/jsx-runtime";import*as e from"react";import{useRender as n}from"@base-ui/react/use-render";import{VISUALLY_HIDDEN as a}from"../../internal/visually-hidden.js";export const MPVisuallyHidden=/*@__PURE__*/e.forwardRef(function({render:e,className:i,children:o,...s},t){return n({render:e??r("span",{}),ref:t,props:{...s,className:[a,i].filter(Boolean).join(" "),children:o}})});

package/dist/components/visually-hidden/index.d.ts

@@ -0,0 +1,2 @@
+export { MPVisuallyHidden } from './MPVisuallyHidden.js';
+export type { MPVisuallyHiddenProps } from './MPVisuallyHidden.js';

package/dist/components/visually-hidden/index.js

@@ -0,0 +1 @@
+export{MPVisuallyHidden}from"./MPVisuallyHidden.js";

package/dist/constants/glyphs.d.ts

@@ -34,6 +34,10 @@ export declare const LinkIcon: import("react").ForwardRefExoticComponent<Omit<im
 export declare const ExternalLinkIcon: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
 /** Copy to clipboard. */
 export declare const CopyIcon: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+/** Source as it was written — `MPCodeBlock`'s toggle out of the colouring. */
+export declare const CodeIcon: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+/** A picture that could not be fetched — `MPImage`'s own fallback. */
+export declare const BrokenImageIcon: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
 /** Severity: something worth knowing. */
 export declare const InfoIcon: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
 /** Severity: it worked. */

package/dist/constants/glyphs.js

@@ -1,2 +1,2 @@
 "use client";
-import{ArrowDown as o,ArrowRight as n,ArrowUp as t,CalendarDays as c,Check as r,ChevronDown as e,ChevronLeft as s,ChevronRight as p,ChevronsLeft as x,ChevronsRight as I,ChevronUp as i,CircleAlert as h,CircleCheck as C,Clock as a,Copy as l,Ellipsis as v,ExternalLink as f,Eye as d,EyeOff as w,Info as g,Link as k,LoaderCircle as A,Menu as L,Minus as R,Plus as S,Search as m,Star as u,TriangleAlert as y,Upload as U,X as b}from"lucide-react";export const VisibilityIcon=d;export const VisibilityOffIcon=w;export const CloseIcon=b;export const CheckIcon=r;export const ChevronDownIcon=e;export const ChevronUpIcon=i;export const ChevronLeftIcon=s;export const ChevronRightIcon=p;export const ChevronsLeftIcon=x;export const ChevronsRightIcon=I;export const SearchIcon=m;export const ArrowUpIcon=t;export const ArrowDownIcon=o;export const ArrowRightIcon=n;export const MoreIcon=v;export const LinkIcon=k;export const ExternalLinkIcon=f;export const CopyIcon=l;export const InfoIcon=g;export const SuccessIcon=C;export const WarningIcon=y;export const ErrorIcon=h;export const AddIcon=S;export const RemoveIcon=R;export const UploadIcon=U;export const CalendarIcon=c;export const ClockIcon=a;export const StarIcon=u;export const SpinnerIcon=A;export const MenuIcon=L;
+import{ArrowDown as o,ArrowRight as n,ArrowUp as t,CalendarDays as c,Check as r,ChevronDown as e,ChevronLeft as s,ChevronRight as p,ChevronsLeft as I,ChevronsRight as x,ChevronUp as i,CircleAlert as C,CircleCheck as h,Clock as a,Code as l,Copy as v,Ellipsis as d,ExternalLink as f,Eye as g,ImageOff as k,EyeOff as w,Info as m,Link as A,LoaderCircle as L,Menu as R,Minus as S,Plus as u,Search as y,Star as U,TriangleAlert as b,Upload as D,X as E}from"lucide-react";export const VisibilityIcon=g;export const VisibilityOffIcon=w;export const CloseIcon=E;export const CheckIcon=r;export const ChevronDownIcon=e;export const ChevronUpIcon=i;export const ChevronLeftIcon=s;export const ChevronRightIcon=p;export const ChevronsLeftIcon=I;export const ChevronsRightIcon=x;export const SearchIcon=y;export const ArrowUpIcon=t;export const ArrowDownIcon=o;export const ArrowRightIcon=n;export const MoreIcon=d;export const LinkIcon=A;export const ExternalLinkIcon=f;export const CopyIcon=v;export const CodeIcon=l;export const BrokenImageIcon=k;export const InfoIcon=m;export const SuccessIcon=h;export const WarningIcon=b;export const ErrorIcon=C;export const AddIcon=u;export const RemoveIcon=S;export const UploadIcon=D;export const CalendarIcon=c;export const ClockIcon=a;export const StarIcon=U;export const SpinnerIcon=L;export const MenuIcon=R;

package/dist/constants/icons.d.ts

@@ -60,6 +60,8 @@ export declare const ICONS: {
     readonly link: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly 'external-link': import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly copy: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly code: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly 'broken-image': import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly info: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly success: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly warning: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;

package/dist/constants/icons.js

@@ -1 +1 @@
-export*from"./glyphs.js";import{VisibilityIcon as r,VisibilityOffIcon as o,CloseIcon as e,CheckIcon as n,ChevronDownIcon as c,ChevronUpIcon as i,ChevronLeftIcon as s,ChevronRightIcon as h,ChevronsLeftIcon as l,ChevronsRightIcon as t,SearchIcon as a,ArrowUpIcon as p,ArrowDownIcon as v,ArrowRightIcon as f,MoreIcon as d,MenuIcon as g,LinkIcon as m,ExternalLinkIcon as w,CopyIcon as u,InfoIcon as y,SuccessIcon as k,WarningIcon as x,ErrorIcon as b,AddIcon as j,RemoveIcon as C,UploadIcon as I,CalendarIcon as N,ClockIcon as O,StarIcon as S,SpinnerIcon as q}from"./glyphs.js";export const ICONS={visibility:r,"visibility-off":o,close:e,check:n,"chevron-down":c,"chevron-up":i,"chevron-left":s,"chevron-right":h,"chevrons-left":l,"chevrons-right":t,search:a,"arrow-up":p,"arrow-down":v,"arrow-right":f,more:d,menu:g,link:m,"external-link":w,copy:u,info:y,success:k,warning:x,error:b,add:j,remove:C,upload:I,calendar:N,clock:O,star:S,spinner:q};
+export*from"./glyphs.js";import{VisibilityIcon as r,VisibilityOffIcon as o,CloseIcon as e,CheckIcon as n,ChevronDownIcon as c,ChevronUpIcon as i,ChevronLeftIcon as s,ChevronRightIcon as h,ChevronsLeftIcon as l,ChevronsRightIcon as t,SearchIcon as a,ArrowUpIcon as p,ArrowDownIcon as v,ArrowRightIcon as d,MoreIcon as f,MenuIcon as g,LinkIcon as m,ExternalLinkIcon as w,CopyIcon as k,CodeIcon as u,BrokenImageIcon as y,InfoIcon as b,SuccessIcon as x,WarningIcon as j,ErrorIcon as C,AddIcon as I,RemoveIcon as N,UploadIcon as O,CalendarIcon as S,ClockIcon as q,StarIcon as z,SpinnerIcon as A}from"./glyphs.js";export const ICONS={visibility:r,"visibility-off":o,close:e,check:n,"chevron-down":c,"chevron-up":i,"chevron-left":s,"chevron-right":h,"chevrons-left":l,"chevrons-right":t,search:a,"arrow-up":p,"arrow-down":v,"arrow-right":d,more:f,menu:g,link:m,"external-link":w,copy:k,code:u,"broken-image":y,info:b,success:x,warning:j,error:C,add:I,remove:N,upload:O,calendar:S,clock:q,star:z,spinner:A};

package/dist/hooks/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The machinery this library was already running, with a name a consumer can
+ * import.
+ *
+ * Two kinds live here, and both are the same argument.
+ *
+ * The first existed in `internal/` before it existed here, and was exported
+ * because an application that has told the library something — or that has to
+ * answer a question the library has already answered for itself — should not
+ * have to answer it a second time, in numbers or in detection code that can
+ * drift away from what the components are using.
+ *
+ * The second is the general form of something the library does several times
+ * over and could not export as it stood. `useMPWindowClass` watches four media
+ * queries; `useMPMediaQuery` is one. `MPTabs` measures its own bar;
+ * `useMPElementSize` is that measurement. `trigger="visible"` watches an
+ * element cross the viewport; `useMPOnScreen` is the watching without the
+ * animation. And `useMPDisclosure` is the six lines every page writes to open a
+ * dialog, with the two details a version written in a hurry leaves out.
+ *
+ * `useMPLocale` and `useMPSnackbar` are not here. They belong to a provider and
+ * live with it, the way a hook that reads a context should.
+ *
+ * `useMPColorScheme` is the one that is more than a rename: the stylesheet
+ * had the switch and nothing to drive it with, so every application wrote the
+ * same state, the same storage round trip and the same `<head>` script.
+ */
+export { useMPColorScheme, mpColorSchemeScript } from './useMPColorScheme.js';
+export type { MPColorScheme, MPResolvedColorScheme, MPColorSchemeOptions, MPColorSchemeResult } from './useMPColorScheme.js';
+export { useMPWindowClass } from './useMPWindowClass.js';
+export { useMPReducedMotion } from './useMPReducedMotion.js';
+export { useMPShortcut, useMPPlatform } from './useMPShortcut.js';
+export { useMPMediaQuery } from './useMPMediaQuery.js';
+export { useMPElementSize } from './useMPElementSize.js';
+export type { MPElementSize } from './useMPElementSize.js';
+export { useMPOnScreen } from './useMPOnScreen.js';
+export type { MPOnScreenOptions } from './useMPOnScreen.js';
+export { useMPDisclosure } from './useMPDisclosure.js';
+export type { MPDisclosure } from './useMPDisclosure.js';
+export type { MPShortcutOptions, MPResolvedOS } from './useMPShortcut.js';

package/dist/hooks/index.js

@@ -0,0 +1 @@
+export{useMPColorScheme,mpColorSchemeScript}from"./useMPColorScheme.js";export{useMPWindowClass}from"./useMPWindowClass.js";export{useMPReducedMotion}from"./useMPReducedMotion.js";export{useMPShortcut,useMPPlatform}from"./useMPShortcut.js";export{useMPMediaQuery}from"./useMPMediaQuery.js";export{useMPElementSize}from"./useMPElementSize.js";export{useMPOnScreen}from"./useMPOnScreen.js";export{useMPDisclosure}from"./useMPDisclosure.js";

package/dist/hooks/useMPColorScheme.d.ts

@@ -0,0 +1,135 @@
+import { type MPColorScheme, type MPResolvedColorScheme } from '../internal/color-scheme.js';
+export type { MPColorScheme, MPResolvedColorScheme };
+export interface MPColorSchemeOptions {
+    /**
+     * Where the choice is remembered, in `localStorage`.
+     *
+     * Change it to keep two applications on one origin from sharing a theme, or
+     * to namespace it under a product. It has to match the key given to
+     * `mpColorSchemeScript`, or the page paints one scheme and then corrects
+     * itself to the other.
+     * @default 'mp-color-scheme'
+     */
+    storageKey?: string;
+}
+export interface MPColorSchemeResult {
+    /**
+     * What has been **chosen** — including `'system'`, which is the absence of a
+     * choice rather than a third scheme. This is what a settings control should be
+     * bound to: a three-way radio group is honest about the state, and a two-way
+     * toggle bound to this cannot show "follow the system" at all.
+     */
+    scheme: MPColorScheme;
+    /**
+     * What is actually **painted**, with `'system'` resolved against the operating
+     * system. This is what a page reads to draw a sun or a moon, or to pick an
+     * image.
+     */
+    resolved: MPResolvedColorScheme;
+    /** Whether the choice is `'system'`, spelled out because it reads better. */
+    isSystem: boolean;
+    /** Chooses a scheme. `'system'` gives the choice back to the operating system. */
+    setScheme: (scheme: MPColorScheme) => void;
+    /**
+     * The other one of the two.
+     *
+     * From `'system'` it goes to the opposite of whatever is currently painted,
+     * which is what a reader pressing a single button means by it — never back to
+     * the scheme they are already looking at.
+     */
+    toggle: () => void;
+}
+/**
+ * The page's colour scheme: what it is, and how to change it.
+ *
+ * The stylesheet has always had the switch — `prefers-color-scheme`, and
+ * `data-mp-scheme` for a page that drives it itself. What it did not have was
+ * anything to drive it *with*, so every application wrote the same three things:
+ * a piece of state, a `localStorage` round trip, and a script in the `<head>` to
+ * stop the first paint flashing.
+ *
+ * ```tsx
+ * const { resolved, toggle } = useMPColorScheme();
+ *
+ * <MPIconButton
+ *   icon={<MPIcon icon={resolved === 'dark' ? SunIcon : MoonIcon} />}
+ *   label="Switch theme"
+ *   onClick={toggle}
+ * />;
+ * ```
+ *
+ * ## Three states, not two
+ *
+ * `'system'` is the absence of a choice rather than a third scheme, and keeping
+ * it is the point. A reader who has never touched the toggle should follow their
+ * operating system *as it changes* — including at sunset, which is when a
+ * two-state hook stops tracking and a page goes light in a dark room.
+ *
+ * `scheme` is what was chosen and `resolved` is what is painted. Bind a settings
+ * control to the first and draw with the second.
+ *
+ * ## One page, one answer
+ *
+ * The choice lives in a module-level store rather than in each caller's state,
+ * so a header's toggle and a settings screen's radio group are looking at the
+ * same thing. Two components holding `useState` would each show what they last
+ * set and neither would hear about the other.
+ *
+ * ## What it writes
+ *
+ * `data-mp-scheme` on `<html>`, and `'system'` **removes** it rather than
+ * writing the word — that is how the media query gets its say back.
+ *
+ * It deliberately does not touch `.dark`. That class is what a project's own
+ * Tailwind keys on, and a library reaching in to toggle a class it did not put
+ * there is a library editing somebody else's markup. A page that wants both is
+ * one line of its own in an effect.
+ *
+ * ## Storage can fail, and that is fine
+ *
+ * Reading and writing `localStorage` throws in a private window in some browsers
+ * and behind some cookie policies. Both are caught: the toggle still works for
+ * the visit and the choice is simply not remembered, which is much better than a
+ * theme button that crashes the render.
+ *
+ * ## The first paint
+ *
+ * A hook cannot run before the page paints, so a remembered `dark` arrives one
+ * frame late and the reader sees white. That is what `mpColorSchemeScript` is
+ * for — see it for the two lines that go in the `<head>`.
+ */
+export declare function useMPColorScheme(options?: MPColorSchemeOptions): MPColorSchemeResult;
+/**
+ * The two lines that stop the first paint flashing, as a string to inline.
+ *
+ * A hook runs after the browser has already painted, so a reader who chose dark
+ * gets a white page for a frame and then the right one. The only thing that can
+ * run earlier is a **synchronous script in the `<head>`**, before the body is
+ * parsed, and this is that script.
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * <head>
+ *   <script dangerouslySetInnerHTML={{ __html: mpColorSchemeScript() }} />
+ * </head>
+ * ```
+ *
+ * It reads the same key the hook does, writes the same attribute, and does
+ * nothing at all when the stored value is absent or `system` — leaving the media
+ * query to answer, which it does before the first paint anyway.
+ *
+ * Pass the same `storageKey` you pass the hook. Two different keys is a page
+ * that paints one scheme and then corrects itself to the other, which is the
+ * flash this exists to remove.
+ *
+ * The output is a JavaScript source string and contains no interpolated markup:
+ * the key is JSON-encoded, so a key with a quote in it cannot end the script
+ * early.
+ *
+ * ## It has to be inline
+ *
+ * A `<script src>` is fetched, and a fetch is exactly the delay being avoided.
+ * If the page has a Content Security Policy without `unsafe-inline`, give the
+ * tag a nonce — this returns the source, not the tag, so the tag is yours.
+ */
+export declare function mpColorSchemeScript(options?: MPColorSchemeOptions): string;

package/dist/hooks/useMPColorScheme.js

@@ -0,0 +1,2 @@
+"use client";
+import*as e from"react";import{DEFAULT_STORAGE_KEY as t,SCHEME_ATTRIBUTE as r,setScheme as s,useChosenScheme as o,useSystemScheme as c}from"../internal/color-scheme.js";export function useMPColorScheme(r={}){const{storageKey:m=t}=r,a=o(m),i=c(),l="system"===a?i:a,n=e.useCallback(e=>s(m,e),[m]),u=e.useCallback(()=>s(m,"dark"===l?"light":"dark"),[m,l]);return e.useMemo(()=>({scheme:a,resolved:l,isSystem:"system"===a,setScheme:n,toggle:u}),[a,l,n,u])}export function mpColorSchemeScript(e={}){const{storageKey:s=t}=e;return`try{var s=localStorage.getItem(${JSON.stringify(s)});if(s==="dark"||s==="light")document.documentElement.setAttribute(${JSON.stringify(r)},s)}catch(e){}`}

package/dist/hooks/useMPDisclosure.d.ts

@@ -0,0 +1,58 @@
+/** Whether something is open, and the three ways to change that. */
+export interface MPDisclosure {
+    open: boolean;
+    /** Opens it. Already open, nothing happens and nothing re-renders. */
+    onOpen: () => void;
+    /** Closes it. */
+    onClose: () => void;
+    /** The other one, whichever that is. */
+    onToggle: () => void;
+    /**
+     * Sets it outright, which is what a controlled prop wants: pass this straight
+     * to an `onOpenChange`.
+     */
+    setOpen: (open: boolean) => void;
+}
+/**
+ * Open, and the three ways to change it.
+ *
+ * The most-written six lines in any application using this library. A dialog, a
+ * drawer, a popover, a menu and a command palette are all controlled the same
+ * way — `open` and `onOpenChange` — and every page that mounts one writes the
+ * same `useState` and the same three callbacks, usually as inline arrows that
+ * are a new function on every render.
+ *
+ * ```tsx
+ * const dialog = useMPDisclosure();
+ *
+ * <MPButton onClick={dialog.onOpen}>Delete</MPButton>
+ * <MPDialog open={dialog.open} onOpenChange={dialog.setOpen} title="Delete?">
+ *   <MPButton onClick={dialog.onClose}>Cancel</MPButton>
+ * </MPDialog>;
+ * ```
+ *
+ * ## Why the library ships one at all
+ *
+ * Because the alternative is not "no hook", it is a hook per application, and
+ * the two things this gets right are the two that get left out of one written in
+ * a hurry.
+ *
+ * Every callback is stable for the life of the component. An inline
+ * `onClick={() => setOpen(true)}` is a new function on every render, which
+ * re-renders a memoised trigger for no reason and defeats the `React.memo` a
+ * page put there on purpose.
+ *
+ * And `onOpen` on something already open is not a state change. React bails out
+ * of a `useState` set to the value it already holds, so the three callbacks here
+ * cost nothing when they are asked for what is already true — which matters
+ * because a close handler is often wired to three things at once: a button, an
+ * `onOpenChange`, and an Escape the component also handles.
+ *
+ * ## It is not a controlled/uncontrolled helper
+ *
+ * It holds state, so it makes a thing controlled. A component that should
+ * manage its own open state takes `defaultOpen` and needs none of this.
+ *
+ * @param defaultOpen what it starts as. @default false
+ */
+export declare function useMPDisclosure(defaultOpen?: boolean): MPDisclosure;

package/dist/hooks/useMPDisclosure.js

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

package/dist/hooks/useMPElementSize.d.ts

@@ -0,0 +1,55 @@
+import * as React from 'react';
+/** What an element measures, in CSS pixels. */
+export interface MPElementSize {
+    width: number;
+    height: number;
+}
+/**
+ * How big an element is, kept up to date as it changes.
+ *
+ * The library measures elements in five places — a tab bar deciding whether it
+ * overflows, a field sizing its outline's notch, panes tracking a drag — and an
+ * application that wants the same answer had to write the `ResizeObserver`
+ * out again, including the two parts of it that are easy to get wrong.
+ *
+ * ```tsx
+ * const ref = React.useRef<HTMLDivElement>(null);
+ * const { width } = useMPElementSize(ref);
+ *
+ * <div ref={ref}>{width > 480 ? <Chart /> : <Figure />}</div>;
+ * ```
+ *
+ * This is the answer for **a component's own width**, which is what a container
+ * query asks and a media query cannot: a card in a sidebar and the same card in
+ * a main column are the same window and two different widths.
+ * [useMPMediaQuery](#usempmediaquery) is the other question.
+ *
+ * ## Zero until it has measured
+ *
+ * The first render has no element yet — a ref is filled in during the commit —
+ * so the first answer is `{ width: 0, height: 0 }` and the real one arrives on
+ * the render after it. Branch on a threshold rather than on the number itself,
+ * or a chart will mount, be told it is zero wide, and mount again.
+ *
+ * ## The two parts that are easy to get wrong
+ *
+ * It reads `getBoundingClientRect`, not the observer entry's `contentRect`.
+ * Those differ by the padding and the border — `contentRect` is the content box
+ * — and a caller comparing a measurement against a breakpoint means the box the
+ * element actually occupies.
+ *
+ * And it re-renders only when a number changes. A `ResizeObserver` fires for a
+ * subpixel reflow that rounds to the same integer, and a hook that set state on
+ * every callback would re-render a chart on every scroll of a page with a
+ * sticky header.
+ *
+ * ## Where there is no observer
+ *
+ * A browser without `ResizeObserver` measures once on mount and stays there,
+ * which is right more often than it is wrong: an element that never resizes is
+ * the common case, and the alternative is a `resize` listener that misses every
+ * change the window did not cause.
+ *
+ * @param ref a ref to the element to measure.
+ */
+export declare function useMPElementSize(ref: React.RefObject<Element | null>): MPElementSize;

package/dist/hooks/useMPElementSize.js

@@ -0,0 +1,2 @@
+"use client";
+import*as e from"react";export function useMPElementSize(t){const[n,i]=e.useState({width:0,height:0});return e.useEffect(()=>{const e=t.current;if(!e)return;const n=()=>{const t=e.getBoundingClientRect(),n={width:Math.round(t.width),height:Math.round(t.height)};i(e=>e.width===n.width&&e.height===n.height?e:n)};if(n(),"undefined"==typeof ResizeObserver)return;const r=new ResizeObserver(n);return r.observe(e),()=>r.disconnect()},[t]),n}

package/dist/hooks/useMPMediaQuery.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether a media query matches, and it re-renders when that changes.
+ *
+ * The general form of what this library already does four times over for the
+ * window size classes, and once each for `prefers-reduced-motion` and the
+ * colour scheme. A page has questions of its own — is this a coarse pointer, is
+ * the window tall enough for a two-row bar, is the reader in a high-contrast
+ * mode — and had to write the subscription out again to ask one.
+ *
+ * ```tsx
+ * const coarse = useMPMediaQuery('(pointer: coarse)');
+ *
+ * <MPTooltip disabled={coarse}>…</MPTooltip>;
+ * ```
+ *
+ * ## Reach for `useMPWindowClass` for a width
+ *
+ * A width query written here is a copy of a number the library also holds, and
+ * the two drift the moment an `MPConfigProvider` moves a boundary. Ask
+ * [useMPWindowClass](#usempwindowclass) instead — it reads the same ladder the
+ * grid and the sidebar do.
+ *
+ * ## On a server, and before hydration
+ *
+ * `onServer`, which defaults to `false`. There is no window to ask, and a
+ * default of "matches" would mean every server-rendered page claiming every
+ * preference at once.
+ *
+ * `useSyncExternalStore` is what makes the correction on hydration legitimate
+ * rather than a mismatch React warns about — but it is a second render, so
+ * anything that swaps a whole layout on this does so visibly on a first load.
+ * Where that matters the answer is CSS, which has no first render to be wrong.
+ *
+ * A browser without `matchMedia` gets the same `onServer` answer, for the same
+ * reason: there is no way to ask, and a guess is worse than the caller's own.
+ *
+ * @param query any CSS media query, without the `@media`.
+ * @param onServer what to answer where there is nothing to ask. @default false
+ */
+export declare function useMPMediaQuery(query: string, onServer?: boolean): boolean;

package/dist/hooks/useMPMediaQuery.js

@@ -0,0 +1,2 @@
+"use client";
+import*as e from"react";export function useMPMediaQuery(t,a=!1){const r=e.useMemo(()=>function(e){if("undefined"==typeof window||!window.matchMedia)return null;let t=n.get(e);t||(t=window.matchMedia(e),n.set(e,t));return t}(t),[t]),c=e.useCallback(e=>r?(r.addEventListener("change",e),()=>r.removeEventListener("change",e)):()=>{},[r]),o=e.useCallback(()=>r?r.matches:a,[r,a]),u=e.useCallback(()=>a,[a]);return e.useSyncExternalStore(c,o,u)}const n=new Map;

package/dist/hooks/useMPOnScreen.d.ts

@@ -0,0 +1,58 @@
+import * as React from 'react';
+/** What to watch for. */
+export interface MPOnScreenOptions {
+    /**
+     * How much of the element has to be showing before it counts, from `0` to `1`.
+     *
+     * The same default the `MPAnimate*` components take, so a page's own answer
+     * and the library's arrive at the same scroll position.
+     * @default 0.2
+     */
+    threshold?: number;
+    /**
+     * Whether it stops watching the first time. Off, it reports every entrance and
+     * every exit.
+     * @default true
+     */
+    once?: boolean;
+    /**
+     * A CSS `margin`-shaped string that grows or shrinks the region the element is
+     * tested against — `'200px 0px'` reports something 200px before it arrives.
+     * For loading a picture, or starting a request, ahead of the reader.
+     */
+    rootMargin?: string;
+}
+/**
+ * Whether an element is on screen.
+ *
+ * The `MPAnimate*` components already ask this — `trigger="visible"` is exactly
+ * it — and an application asks it for other reasons: loading an image, starting
+ * a request, marking a section read, pausing something expensive that has
+ * scrolled away.
+ *
+ * ```tsx
+ * const ref = React.useRef<HTMLDivElement>(null);
+ * const seen = useMPOnScreen(ref);
+ *
+ * <div ref={ref}>{seen ? <Chart data={data} /> : <MPSkeleton height={240} />}</div>;
+ * ```
+ *
+ * ## `once` is on, and that is the common case
+ *
+ * Most reasons to ask are one-way: something loads, or is marked read, and does
+ * not unload when it scrolls off. Turn it off for the ones that are not — a
+ * video that should pause, a poll that should stop.
+ *
+ * ## Where there is no observer
+ *
+ * `true`. A browser with no `IntersectionObserver` has no way to be asked, and
+ * showing content is the answer that fails safe: the alternative is a page
+ * whose every deferred section stays a skeleton forever.
+ *
+ * The same is true before the ref is filled in, which is why this starts at
+ * `false` and not at `true` — on the first render there is no element yet, and
+ * an element that has not been observed is not the same as one that cannot be.
+ *
+ * @param ref a ref to the element to watch.
+ */
+export declare function useMPOnScreen(ref: React.RefObject<Element | null>, { threshold, once, rootMargin }?: MPOnScreenOptions): boolean;

package/dist/hooks/useMPOnScreen.js

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

package/dist/hooks/useMPReducedMotion.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Whether the reader has asked for less motion.
+ *
+ * `prefers-reduced-motion: reduce`, which every `MPAnimate*` component in this
+ * library already consults on its own — a fade becomes an appearance, a
+ * typewriter prints its sentence, a marquee stops. This is the same answer,
+ * exported so an application's own motion can be held to the preference the
+ * library is already holding itself to, rather than each of them asking
+ * separately and one of them forgetting.
+ *
+ * ```tsx
+ * const still = useMPReducedMotion();
+ *
+ * <video autoPlay={!still} />;
+ * ```
+ *
+ * ## Why not `usePrefersReducedMotion`
+ *
+ * Which is what it is called internally, and what the ecosystem calls it. The
+ * `MP` prefix is on every name this package exports for the reason the icons
+ * carry it: a file importing from four libraries should be able to tell which
+ * one a name came from without going back to the import block.
+ *
+ * ## On a server
+ *
+ * `false` — motion allowed. A preference is a property of a reader and a server
+ * has none, and the alternative would be a first paint that suppressed animation
+ * for everybody and then started it a moment later for most of them, which is a
+ * flash rather than a preference. `useSyncExternalStore` under this hands over
+ * to the browser's real answer on hydration.
+ */
+export declare function useMPReducedMotion(): boolean;

package/dist/hooks/useMPReducedMotion.js

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