material-plus-ui 1.5.0 → 1.6.0

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,8 @@ 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>>;
+/** 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 h,CircleCheck as C,Clock as a,Copy as l,Ellipsis as v,ExternalLink as f,Eye as d,ImageOff as g,EyeOff as k,Info as w,Link as m,LoaderCircle as A,Menu as L,Minus as R,Plus as S,Search as u,Star as y,TriangleAlert as U,Upload as b,X as D}from"lucide-react";export const VisibilityIcon=d;export const VisibilityOffIcon=k;export const CloseIcon=D;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=u;export const ArrowUpIcon=t;export const ArrowDownIcon=o;export const ArrowRightIcon=n;export const MoreIcon=v;export const LinkIcon=m;export const ExternalLinkIcon=f;export const CopyIcon=l;export const BrokenImageIcon=g;export const InfoIcon=w;export const SuccessIcon=C;export const WarningIcon=U;export const ErrorIcon=h;export const AddIcon=S;export const RemoveIcon=R;export const UploadIcon=b;export const CalendarIcon=c;export const ClockIcon=a;export const StarIcon=y;export const SpinnerIcon=A;export const MenuIcon=L;

package/dist/constants/icons.d.ts

@@ -60,6 +60,7 @@ 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 '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 i,ChevronUpIcon as c,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 g,MenuIcon as m,LinkIcon as d,ExternalLinkIcon as w,CopyIcon as k,BrokenImageIcon as u,InfoIcon as y,SuccessIcon as b,WarningIcon as x,ErrorIcon as j,AddIcon as C,RemoveIcon as I,UploadIcon as N,CalendarIcon as O,ClockIcon as S,StarIcon as q,SpinnerIcon as z}from"./glyphs.js";export const ICONS={visibility:r,"visibility-off":o,close:e,check:n,"chevron-down":i,"chevron-up":c,"chevron-left":s,"chevron-right":h,"chevrons-left":l,"chevrons-right":t,search:a,"arrow-up":p,"arrow-down":v,"arrow-right":f,more:g,menu:m,link:d,"external-link":w,copy:k,"broken-image":u,info:y,success:b,warning:x,error:j,add:C,remove:I,upload:N,calendar:O,clock:S,star:q,spinner:z};

package/dist/hooks/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The machinery this library was already running, with a name a consumer can
+ * import.
+ *
+ * Every hook here existed in `internal/` before it existed here, and each was
+ * exported for the same reason: 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.
+ *
+ * `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 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";

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 @@
+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/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 @@
+import{usePrefersReducedMotion as e}from"../internal/animate.js";export function useMPReducedMotion(){return e()}

package/dist/hooks/useMPShortcut.d.ts

@@ -0,0 +1,105 @@
+import { type MPResolvedOS } from '../internal/keys.js';
+/** The three platforms a shortcut is spelled for. */
+export type { MPResolvedOS };
+/** Where the keystroke is listened for, and what happens to it. */
+export interface MPShortcutOptions {
+    /**
+     * Turns the binding off without unmounting whatever holds it. A shortcut
+     * behind a feature flag, or one that belongs to a panel that is closed.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Calls `preventDefault()` on the matching keystroke.
+     *
+     * On by default, and it is the honest default: some browsers put their own
+     * search bar on `Mod+K`, and a page binding that combination has said the key
+     * is theirs. Switch it off for a shortcut that means to run *alongside* the
+     * browser's, which is rare enough to be worth writing down.
+     * @default true
+     */
+    preventDefault?: boolean;
+    /**
+     * Ignores the keystroke while the focus is in a text input, a textarea or
+     * anything `contenteditable`.
+     *
+     * Off by default, because the shortcut most pages bind has a modifier and
+     * `Mod+K` typed into a search field still means "open the palette". Switch it
+     * on for a **bare** key — `/` to focus search, `?` for help — which would
+     * otherwise be swallowed out of the middle of somebody's sentence.
+     * @default false
+     */
+    ignoreInputs?: boolean;
+    /**
+     * What the listener is attached to.
+     * @default the window
+     */
+    target?: EventTarget | null;
+}
+/**
+ * Runs something when a keystroke arrives, spelled the way this library spells
+ * shortcuts everywhere else.
+ *
+ * `MPShortcut` **writes** a shortcut down, `MPCommandPalette` **reads** one off
+ * a real keyboard, and both have always gone through one matcher so that a label
+ * on the screen and the binding under it cannot disagree — see `internal/keys.ts`
+ * for the day they did. This is that matcher, for the shortcuts an application
+ * binds itself.
+ *
+ * ```tsx
+ * useMPShortcut('Mod+K', () => setOpen(true));
+ * useMPShortcut('/', focusSearch, { ignoreInputs: true });
+ * ```
+ *
+ * ## `Mod` is the whole point
+ *
+ * It resolves to Command on a Mac and Control everywhere else, which is what
+ * lets one string be both the binding and the label:
+ *
+ * ```tsx
+ * <MPShortcut keys="Mod+K" />;
+ * useMPShortcut('Mod+K', open);
+ * ```
+ *
+ * Two lines, one spelling, and no way for the page to draw `⌘K` while listening
+ * for `Ctrl+K`.
+ *
+ * Modifiers are matched in **both** directions: `Mod+K` does not fire when Shift
+ * is also held, because that combination may belong to something else. A
+ * shortcut that ignored extra modifiers would be quietly taking keystrokes it
+ * was not given.
+ *
+ * ## The handler is not a dependency
+ *
+ * It is kept in a ref and read at the moment the key arrives, so an inline arrow
+ * function is fine and does not rebind the listener on every render. What *does*
+ * rebind is the shortcut itself, `enabled`, and `target` — the things that change
+ * what is being listened for.
+ *
+ * ## Sharp edges
+ *
+ * - **It listens on the window**, so it fires wherever the focus is unless
+ *   `ignoreInputs` says otherwise. That is what a page-wide shortcut wants and
+ *   not what a shortcut belonging to one panel wants — pass that panel's element
+ *   as `target`.
+ * - **It does not stop propagation.** A page with two hooks bound to one
+ *   combination runs both, which is a collision the page has to resolve rather
+ *   than something the hook can guess at.
+ * - **The platform is detected once.** It cannot change under a running page.
+ */
+export declare function useMPShortcut(keys: string | string[], handler: (event: KeyboardEvent) => void, options?: MPShortcutOptions): void;
+/**
+ * Which keyboard the reader is on — `'mac'`, `'windows'` or `'linux'`.
+ *
+ * The same detection `MPShortcut` prints its key caps from, exported so an
+ * application writing a key cap of its own cannot end up on a different answer
+ * from the component beside it. Three sources are matched at once —
+ * `userAgentData.platform`, `navigator.platform` and the user agent string —
+ * because the question is coarse and browsers freeze or lie about each of them
+ * separately.
+ *
+ * `'windows'` on a server, and corrected on hydration through
+ * `useSyncExternalStore` — which is the one API that tells React the two renders
+ * are *meant* to differ, and is exactly the sequence a Mac reader sees.
+ */
+export declare function useMPPlatform(): MPResolvedOS;

package/dist/hooks/useMPShortcut.js

@@ -0,0 +1,2 @@
+"use client";
+import*as e from"react";import{matchesShortcut as t,useDetectedOS as n}from"../internal/keys.js";const r=/^(input|textarea|select)$/i;export function useMPShortcut(o,i,s={}){const{enabled:u=!0,preventDefault:a=!0,ignoreInputs:c=!1,target:f}=s,d=n(),l=e.useRef(i);l.current=i;const p=Array.isArray(o)?o.join("+"):o;e.useEffect(()=>{if(!u)return;const e=void 0===f?"undefined"==typeof window?null:window:f;if(!e)return;const n=e=>{const n=e;c&&function(e){return e instanceof HTMLElement&&(r.test(e.tagName)||e.isContentEditable)}(n.target)||t(n,p,d)&&(a&&n.preventDefault(),l.current(n))};return e.addEventListener("keydown",n),()=>e.removeEventListener("keydown",n)},[p,d,u,a,c,f])}export function useMPPlatform(){return n()}

package/dist/hooks/useMPWindowClass.d.ts

@@ -0,0 +1,48 @@
+import type { MPWindowClass } from '../types.js';
+/**
+ * Which of Material's five window size classes the window is in.
+ *
+ * The library has always had this axis — `MPGrid` reflows along it, `MPResponsive`
+ * is written in terms of it, `MPSidebar` collapses at it — and a consumer could
+ * name the classes in a prop without ever being able to *ask* which one they
+ * were in. So a page that wanted one more decision than a prop covers had to
+ * write the four breakpoints out again, in numbers that had to match the
+ * library's or the layout would disagree with itself at one width.
+ *
+ * ```tsx
+ * const size = useMPWindowClass();
+ *
+ * return size === 'compact' ? <MPDrawer>{nav}</MPDrawer> : <MPSidebar>{nav}</MPSidebar>;
+ * ```
+ *
+ * ## It reads the media queries, not the width
+ *
+ * Which is what keeps it agreeing with the stylesheet. `innerWidth` counts a
+ * classic scrollbar and a media query does not, so a 615px window with a 15px
+ * scrollbar is `medium` to CSS and `compact` to arithmetic — a layout whose
+ * JavaScript and whose CSS part company at exactly one width, which is the
+ * hardest kind of bug to be shown.
+ *
+ * It also subscribes to the four boundaries rather than to `resize`. A window
+ * dragged from 500 to 1900 wakes this four times; a `resize` listener wakes
+ * several hundred, for the same four answers.
+ *
+ * ## On a server
+ *
+ * There is no window, so there is no true answer — and this returns `onServer`,
+ * which is `'expanded'` unless you say otherwise. That is a **guess**, and the
+ * argument is there because an application usually knows better than the library
+ * does: a marketing site's first paint is mostly phones and `'compact'` is the
+ * closer bet, an internal dashboard's is not.
+ *
+ * The client corrects it on hydration. `useSyncExternalStore` is what makes that
+ * correction legitimate rather than a mismatch React warns about — but the
+ * correction is a second render, so a component that swaps a whole navigation
+ * pattern on this will do so visibly on a first load. Where that matters, the
+ * CSS answer is the one that has no first render to be wrong: `MPGrid`'s
+ * responsive props and Tailwind's own variants are resolved by the browser
+ * before anything paints.
+ *
+ * @param onServer what to answer where there is no window. @default 'expanded'
+ */
+export declare function useMPWindowClass(onServer?: MPWindowClass): MPWindowClass;

package/dist/hooks/useMPWindowClass.js

@@ -0,0 +1 @@
+import{useWindowClass as n}from"../internal/window-class.js";export function useMPWindowClass(e="expanded"){return n(e)}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './types.js';
 export { registerMPMessages, type MPLocale, type MPMessages, type MPPartialMessages } from './internal/i18n.js';
 export * from './constants/icons.js';
+export * from './hooks/index.js';
 export * from './components/accordion/index.js';
 export * from './components/alert/index.js';
 export * from './components/animate-appear/index.js';
@@ -24,12 +25,15 @@ 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/collapsible/index.js';
+export * from './components/config/index.js';
+export * from './components/confirm/index.js';
 export * from './components/color-picker/index.js';
 export * from './components/combobox/index.js';
 export * from './components/command-palette/index.js';
@@ -51,6 +55,7 @@ export * from './components/header/index.js';
 export * from './components/highlight/index.js';
 export * from './components/icon/index.js';
 export * from './components/icon-button/index.js';
+export * from './components/image/index.js';
 export * from './components/list/index.js';
 export * from './components/locale/index.js';
 export * from './components/menu/index.js';
@@ -63,6 +68,7 @@ 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/popconfirm/index.js';
 export * from './components/popover/index.js';
 export * from './components/progress-box/index.js';
 export * from './components/progress-circular/index.js';
@@ -77,6 +83,7 @@ export * from './components/skeleton/index.js';
 export * from './components/slider/index.js';
 export * from './components/snackbar/index.js';
 export * from './components/spoiler/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';
@@ -89,3 +96,4 @@ export * from './components/toggle-group/index.js';
 export * from './components/tooltip/index.js';
 export * from './components/transfer/index.js';
 export * from './components/typography/index.js';
+export * from './components/visually-hidden/index.js';

package/dist/index.js

@@ -1 +1 @@
-export*from"./types.js";export{registerMPMessages}from"./internal/i18n.js";export*from"./constants/icons.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/dialog/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/floating-action-button/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/icon/index.js";export*from"./components/icon-button/index.js";export*from"./components/list/index.js";export*from"./components/locale/index.js";export*from"./components/menu/index.js";export*from"./components/menubar/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/segmented-button/index.js";export*from"./components/select/index.js";export*from"./components/shortcut/index.js";export*from"./components/sidebar/index.js";export*from"./components/skeleton/index.js";export*from"./components/slider/index.js";export*from"./components/snackbar/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/toggle/index.js";export*from"./components/toggle-group/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{registerMPMessages}from"./internal/i18n.js";export*from"./constants/icons.js";export*from"./hooks/index.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/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/collapsible/index.js";export*from"./components/config/index.js";export*from"./components/confirm/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/dialog/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/floating-action-button/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/icon/index.js";export*from"./components/icon-button/index.js";export*from"./components/image/index.js";export*from"./components/list/index.js";export*from"./components/locale/index.js";export*from"./components/menu/index.js";export*from"./components/menubar/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/popconfirm/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/segmented-button/index.js";export*from"./components/select/index.js";export*from"./components/shortcut/index.js";export*from"./components/sidebar/index.js";export*from"./components/skeleton/index.js";export*from"./components/slider/index.js";export*from"./components/snackbar/index.js";export*from"./components/spoiler/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/toggle/index.js";export*from"./components/toggle-group/index.js";export*from"./components/tooltip/index.js";export*from"./components/transfer/index.js";export*from"./components/typography/index.js";export*from"./components/visually-hidden/index.js";

package/dist/internal/Calendar.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { type MPTimeUnit } from './date.js';
+import { type MPCalendarView, type MPTimeUnit } from './date.js';
 import type { MPMessages } from './i18n.js';
 import type { MPColor, MPSize, MPWeekday } from '../types.js';
 /**
@@ -10,7 +10,15 @@ import type { MPColor, MPSize, MPWeekday } from '../types.js';
  * calendars, so three components need this and none of them should have to
  * import another. The two things it reaches *up* for are `MPButton` and
  * `MPIconButton` — the header's steppers are buttons, they are not a new kind of
- * control. Nothing here is exported from `src/index.ts`.
+ * control.
+ *
+ * Nothing here is exported from `src/index.ts` under its own name. `Calendar` is
+ * reachable from outside through `MPCalendar`, which is a wrapper rather than a
+ * re-export: everything below is fully controlled and takes its `labels` already
+ * resolved, because four callers had already decided those things. A consumer
+ * has not, so the public component is where the state and the translation are
+ * put back. That is also why the name went the other way round — the `MP` prefix
+ * belongs to what a consumer can import.
  *
  * The day cells are deliberately *not* buttons in that sense. A cell has states
  * a button has no vocabulary for — inside a range, at the end of a range, today,
@@ -19,7 +27,7 @@ import type { MPColor, MPSize, MPWeekday } from '../types.js';
  */
 /** The strings a picker says that `Intl` has no opinion about. */
 export type MPPickerLabels = MPMessages['picker'];
-export interface MPCalendarProps {
+export interface CalendarProps {
     size: MPSize;
     color: MPColor;
     locale?: string;
@@ -54,6 +62,13 @@ export interface MPCalendarProps {
     autoFocus?: boolean;
     showPreviousButton?: boolean;
     showNextButton?: boolean;
+    /**
+     * The finest view the calendar offers, and therefore what a press answers
+     * with. `'month'` never draws a day grid and `'year'` never draws either of
+     * the other two.
+     * @default 'day'
+     */
+    precision?: MPCalendarView;
     labels: MPPickerLabels;
 }
 /**
@@ -71,7 +86,7 @@ export interface MPCalendarProps {
  * grid instead of walking forty-two cells — the pattern the ARIA date-picker
  * practice describes, and the reason none of the cells is a `disabled` button.
  */
-export declare function MPCalendar({ size, color, locale, weekStartsOn, month, onMonthChange, selected, rangeStart, rangeEnd, onSelect, onPreviewChange, minDate, maxDate, shouldDisableDate, showOutsideDays, autoFocus, showPreviousButton, showNextButton, labels }: MPCalendarProps): React.JSX.Element;
+export declare function Calendar({ size, color, locale, weekStartsOn, month, onMonthChange, selected, rangeStart, rangeEnd, onSelect, onPreviewChange, minDate, maxDate, shouldDisableDate, showOutsideDays, autoFocus, showPreviousButton, showNextButton, precision, labels }: CalendarProps): React.JSX.Element;
 export interface MPTimeGridProps {
     size: MPSize;
     locale?: string;