material-plus-ui 0.0.1 → 1.0.0

package/README.md

@@ -1,3 +1,9 @@
+<!-- An absolute URL, not `docs/public/logo-large.png`: this file is the package
+     page on npm as well as the front page on GitHub, `.npmignore` keeps `docs/`
+     out of the tarball, and npm resolves a relative image against the published
+     package before it falls back to anything else. -->
+<img src="https://raw.githubusercontent.com/jooy2/material-plus/main/docs/public/logo-large.png" alt="Material Plus" width="96" height="96">
+
 # Material Plus
 
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jooy2/material-plus/blob/main/LICENSE) ![Programming Language Usage](https://img.shields.io/github/languages/top/jooy2/material-plus) [![npm downloads](https://img.shields.io/npm/dm/material-plus-ui.svg)](https://www.npmjs.com/package/material-plus-ui) [![npm latest package](https://img.shields.io/npm/v/material-plus-ui/latest.svg)](https://www.npmjs.com/package/material-plus-ui) ![npm bundle size](https://img.shields.io/bundlephobia/min/material-plus-ui)
@@ -8,11 +14,12 @@ Live previews and full props for every component. This README is just the quick
 
 ---
 
-**Material Plus is a React component library that extends Material UI.** It is the pile of components you end up writing in every MUI project — the field that handles IME composition properly, the icon wrapper that agrees with your set — extracted, documented and tested.
+**Material Plus is a React component library implementing Material Design 3.** It is the pile of components you end up writing in every Material project — the field that handles IME composition properly, the icon wrapper that agrees with your set — extracted, documented and tested.
 
-It is not a replacement for `@mui/material` and does not try to be one. Every component is built out of MUI, reads your `ThemeProvider`, and sits at the same height as the MUI control next to it in the same form.
+It follows the specification directly rather than wrapping somebody's implementation of it, so its colour roles, type scale and shapes are the ones the spec names.
 
-- **MUI is a peer, not a copy.** `@mui/material` and Emotion stay your dependencies, so there is never a second MUI in the bundle or a second theme in the tree.
+- **Themed in one line.** Set `--mp-source-color` and every colour role follows, the way Material generates a scheme from a source colour. No provider, no theme object, no re-render.
+- **It coexists.** Nothing here is page-level — no reset, no provider, no global styling — and it reads the `--md-sys-color-*` tokens your page already has if they are there. A project already running Material keeps its own setup.
 - **IME-safe by construction.** Korean, Japanese and Chinese composition survives whatever your `onChange` does with the value.
 - **Bring your own icons.** `MPIcon` takes a component or an element from any set. `lucide-react` ships with the package, gathered in one readable constants file.
 - **ESM only**, TypeScript declarations included, tree-shakeable — every component compiles to its own module.
@@ -42,15 +49,12 @@ pnpm add material-plus-ui
 
 ### Peer dependencies
 
-You already have all of these in an MUI project:
-
-| Package                             | Versions     |
-| ----------------------------------- | ------------ |
-| `@mui/material`                     | 6, 7, 8 or 9 |
-| `@emotion/react`, `@emotion/styled` | 11           |
-| `react`, `react-dom`                | 18 or 19     |
+| Package              | Versions |
+| -------------------- | -------- |
+| `@base-ui/react`     | 1        |
+| `react`, `react-dom` | 18 or 19 |
 
-Only MUI 9 is exercised in CI, though the components use APIs stable since MUI 5.
+`@base-ui/react` is a peer rather than a dependency because it carries React context: a `Form` of yours has to be able to see a field of ours, and that only works with one copy in the tree.
 
 ### Setup
 
@@ -60,7 +64,7 @@ Add one line to your app's CSS entry point:
 @import 'material-plus-ui/styles.css';
 ```
 
-This is finished CSS — no PostCSS plugin, no `@source`, no build-side configuration. It deliberately contains **no reset**: `CssBaseline` from `@mui/material` is already one, and Tailwind's Preflight would restyle every MUI component on your page rather than only the ones from here.
+This is finished CSS — no PostCSS plugin, no `@source`, no build-side configuration. It deliberately contains **no reset**, and no page-level styling of any kind: a component resets what it owns on the element it owns, so whatever your page already does stays in charge.
 
 If Tailwind v4 is already in your project, import the token sheet instead:
 
@@ -71,39 +75,46 @@ If Tailwind v4 is already in your project, import the token sheet instead:
 
 ## Usage
 
-Material Plus components go anywhere an MUI component goes, inside the same provider.
+There is no provider. Import a component and render it.
 
 ```tsx
 import { useState } from 'react';
-import CssBaseline from '@mui/material/CssBaseline';
-import { ThemeProvider, createTheme } from '@mui/material/styles';
 import { MPTextField, MPIcon, ICONS } from 'material-plus-ui';
 
-const theme = createTheme({ palette: { mode: 'light' } });
-
 export default function App() {
   const [email, setEmail] = useState('');
 
   return (
-    <ThemeProvider theme={theme}>
-      <CssBaseline />
-      <MPTextField
-        label="Email"
-        type="email"
-        value={email}
-        onChange={setEmail}
-        startIcon={<MPIcon icon={ICONS.search} size={18} />}
-      />
-    </ThemeProvider>
+    <MPTextField
+      label="Email"
+      type="email"
+      value={email}
+      onChange={setEmail}
+      startIcon={<MPIcon icon={ICONS.search} size={18} />}
+    />
   );
 }
 ```
 
+## Theming
+
+Material generates a whole scheme from one source colour, and so does this.
+
+```css
+:root {
+  --mp-source-color: #7c3aed;
+}
+```
+
+Dark mode follows `prefers-color-scheme` on its own; `data-mp-scheme="dark"` or `.dark` on any element drives it yourself. To disagree with one generated colour, set that role — `--mp-sys-color-outline` — and to follow tokens your page already defines, do nothing: `--md-sys-color-*` is read where it is present.
+
+Full details, including scoped and runtime theming, are in [the theming guide](https://material-plus.cdget.com/guide/getting-started#theming).
+
 ## Components
 
 | Component | What it is |
 | --- | --- |
-| [`MPTextField`](https://material-plus.cdget.com/components/inputs/text-field) | A text field that survives an IME, with the label, helper text, adornments and password toggle already assembled. |
+| [`MPTextField`](https://material-plus.cdget.com/components/inputs/text-field) | An outlined text field that survives an IME, with the label, supporting text, adornments and password toggle already assembled. |
 | [`MPIcon`](https://material-plus.cdget.com/components/display/icon) | A glyph at a known size in a known colour, from whichever icon set you use. |
 
 ### Why `MPTextField` exists

package/dist/components/accordion/MPAccordion.d.ts

@@ -0,0 +1,115 @@
+import * as React from 'react';
+import type { MPSize, MPVariant } from '../../types';
+export interface MPAccordionProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'defaultValue' | 'onChange'> {
+    /**
+     * Whether more than one section may be open at once.
+     *
+     * `false` by default, which is the whole reason an accordion is not just a
+     * stack of [collapsibles](./collapsible): closing the last one as the next
+     * opens is what keeps the page from growing under the reader.
+     * @default false
+     */
+    multiple?: boolean;
+    /** Which sections are open. Use with `onValueChange` for a controlled accordion. */
+    value?: (string | number)[];
+    /** Which start open, for an uncontrolled one. */
+    defaultValue?: (string | number)[];
+    onValueChange?: (value: (string | number)[]) => void;
+    /**
+     * Separates the sections with a hairline rather than with space.
+     *
+     * On by default, which is the other way round from `MPList`. A list of tiles
+     * is a list; an accordion of tiles is a stack of cards that happen to fold,
+     * and the rule is what says the sections are parts of one thing.
+     * @default true
+     */
+    dividers?: boolean;
+    /** Unavailable. Every section stops answering. */
+    disabled?: boolean;
+    /**
+     * How much surface the sheet paints.
+     * @default 'outlined'
+     */
+    variant?: MPVariant;
+    /**
+     * The room inside every section, and the type scale of its header and body.
+     * @default 'md'
+     */
+    size?: MPSize;
+    /**
+     * Keeps closed panels in the DOM so the browser's own page search can find and
+     * open them. Overrides `keepMounted`.
+     * @default false
+     */
+    hiddenUntilFound?: boolean;
+    /**
+     * Keeps closed panels in the DOM. For content that is expensive to build, or
+     * that holds form state which should survive being folded away.
+     * @default false
+     */
+    keepMounted?: boolean;
+    /** The `MPAccordionItem`s. */
+    children?: React.ReactNode;
+}
+export interface MPAccordionItemProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'title' | 'onChange'> {
+    /**
+     * Identifies the section to `value` / `defaultValue`. Base UI generates one
+     * when it is left out, which is enough for an accordion nobody drives from
+     * code.
+     */
+    value?: string | number;
+    /** The heading on the fold. */
+    title?: React.ReactNode;
+    /** A second line under it, one step down the type scale and muted. */
+    subtitle?: React.ReactNode;
+    /** Content before the title — a glyph, a status dot, a count. */
+    startIcon?: React.ReactNode;
+    /**
+     * A control pinned to the end of the header, **outside** the trigger.
+     *
+     * Deliberately outside it: a header that both folds and holds a switch has two
+     * things to press, and a `<button>` inside a `<button>` is markup the browser
+     * rewrites on parse. The same shape `MPCollapsible` and `MPListItem` use.
+     */
+    action?: React.ReactNode;
+    /** Unavailable. This section stops folding; the rest keep working. */
+    disabled?: boolean;
+    /** The body. */
+    children?: React.ReactNode;
+}
+/**
+ * A stack of sections, one of which is open.
+ *
+ * Base UI owns the parts that are genuinely hard: the `<button>`/`region`
+ * pairing and the `aria-controls` / `aria-expanded` wiring between them, the set
+ * of open values, and measuring each panel so it has a height to animate from.
+ * What is here is the surface, the ladders and Material's state layer.
+ *
+ * ## Why this is not a stack of collapsibles
+ *
+ * Because of `multiple`. A [collapsible](./collapsible) has an `open` of its
+ * own and answers to nobody; an accordion owns the *set*, and closing the last
+ * section as the next one opens is the whole reason the component exists — it is
+ * what keeps the page from growing under the reader. Sections that are genuinely
+ * unrelated should be collapsibles, and a component that closed one because the
+ * other opened would be inventing a relationship the page does not have.
+ *
+ * ## The surface stays neutral
+ *
+ * Even on `filled`, which here is `surface-container-highest` — MD3's own filled
+ * card — rather than the accent. An accordion is a box holding somebody else's
+ * content, and dyeing the box dyes their content's background. That is also why
+ * there is no `color`: nothing would read it.
+ */
+export declare const MPAccordion: React.ForwardRefExoticComponent<MPAccordionProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * One section.
+ *
+ * The header is always a row, and what is inside it is a real `<button>`
+ * covering the title and the chevron, with `action` sitting outside that button
+ * as a control of its own. The same shape `MPChip` and `MPListItem` use, for the
+ * same two reasons: a `<div>` carrying a click handler is invisible to a
+ * keyboard, and a `<button>` inside a `<button>` is markup the browser rewrites
+ * on parse.
+ */
+export declare const MPAccordionItem: React.ForwardRefExoticComponent<MPAccordionItemProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/accordion/MPAccordion.js

@@ -0,0 +1 @@
+import{jsx as e,jsxs as n}from"react/jsx-runtime";import*as t from"react";import{Accordion as i}from"@base-ui/react/accordion";import{MPIcon as a}from"../icon/MPIcon";import{ChevronDownIcon as r}from"../../constants/icons";import{MPStateLayer as o}from"../../internal/StateLayer";import{CONTROL_GAP as s,CONTROL_ICON as l,hasContent as d,META_TEXT as c,PROSE_TEXT as m,SHEET_PAD_X as u,SHEET_PAD_Y as f,SHEET_TITLE as p}from"../../internal/scale";import{CONTAINER_SURFACE as h}from"../../internal/surface";const x=t.createContext({size:"md",dividers:!0}),v=["h-(--accordion-panel-height) overflow-hidden","transition-[height] duration-(--mp-sys-motion-duration-short4) ease-mp-standard","motion-reduce:transition-none","data-starting-style:h-0 data-ending-style:h-0"].join(" "),b={xs:"pb-2.5",sm:"pb-3",md:"pb-4",lg:"pb-5",xl:"pb-6"};export const MPAccordion=t.forwardRef(function({multiple:n=!1,value:a,defaultValue:r,onValueChange:o,dividers:s=!0,disabled:l=!1,variant:d="outlined",size:c="md",hiddenUntilFound:m=!1,keepMounted:u=!1,className:f,children:p,...v},b){const N=t.useMemo(()=>({size:c,dividers:s}),[c,s]);return e(x.Provider,{value:N,children:e(i.Root,{ref:b,multiple:n,value:a,defaultValue:r,onValueChange:e=>o?.(e),disabled:l,hiddenUntilFound:m,keepMounted:u,"data-mp-size":c,"data-mp-variant":d,className:["mp-accordion rounded-mp-md flex w-full flex-col",h[d],"text-mp-on-surface",s?"overflow-hidden [&>div+div]:border-mp-outline-variant [&>div+div]:border-t":"p-1",f??""].filter(Boolean).join(" "),...v,children:p})})});export const MPAccordionItem=t.forwardRef(function({value:h,title:N,subtitle:g,startIcon:j,action:w,disabled:y=!1,className:z,children:M,...k},P){const{size:C,dividers:I}=t.useContext(x),V=u[C],B=f[C];return n(i.Item,{ref:P,value:h,disabled:y,className:["mp-accordion__item flex flex-col",z??""].filter(Boolean).join(" "),...k,children:[n(i.Header,{className:"m-0 flex w-full items-center font-[inherit]",children:[n(i.Trigger,{className:["group relative flex min-w-0 flex-1 cursor-pointer items-center text-start","appearance-none border-0 bg-transparent font-[inherit] text-inherit",V,B,s[C],I?"":"rounded-mp-sm","outline-mp-secondary focus-visible:outline-2 focus-visible:-outline-offset-2","focus-visible:outline-solid outline-none","disabled:text-mp-on-surface/38 disabled:cursor-default"].filter(Boolean).join(" "),children:[e(o,{}),d(j)?e("span",{className:"text-mp-on-surface-variant flex h-[1lh] shrink-0 items-center",children:j}):null,n("span",{className:"flex min-w-0 flex-1 flex-col",children:[d(N)?e("span",{className:`truncate ${p[C]}`,children:N}):null,d(g)?e("span",{className:`text-mp-on-surface-variant truncate ${c}`,children:g}):null]}),e("span",{className:["text-mp-on-surface-variant flex h-[1lh] shrink-0 items-center","transition-[rotate] duration-(--mp-sys-motion-duration-short4)","ease-mp-standard motion-reduce:transition-none","group-data-panel-open:rotate-180"].join(" "),children:e(a,{icon:r,size:l[C]})})]}),d(w)?e("span",{className:`flex shrink-0 items-center ${V}`,children:w}):null]}),e(i.Panel,{className:v,children:e("div",{className:["min-w-0",m[C],"text-mp-on-surface-variant",V,b[C]].join(" "),children:M})})]})});

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

@@ -0,0 +1,2 @@
+export { MPAccordion, MPAccordionItem } from './MPAccordion';
+export type { MPAccordionItemProps, MPAccordionProps } from './MPAccordion';

package/dist/components/accordion/index.js

@@ -0,0 +1 @@
+export{MPAccordion,MPAccordionItem}from"./MPAccordion";

package/dist/components/alert/MPAlert.d.ts

@@ -0,0 +1,91 @@
+import * as React from 'react';
+import type { MPColor, MPSize, MPVariant } from '../../types';
+export interface MPAlertProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'color' | 'title'> {
+    /**
+     * How much surface the alert paints.
+     *
+     * `tonal` rather than `filled`, which is the one place this component's default
+     * differs from a button's. A container tone is MD3's own answer for a message
+     * set into a page — it separates itself from the surface without competing
+     * with the primary action that is usually sitting right beside it, and a page
+     * with three saturated alerts on it has no emphasis left to spend.
+     * @default 'tonal'
+     */
+    variant?: MPVariant;
+    /**
+     * Which accent family it reads.
+     *
+     * Four roles, not a severity ladder — there is no `info`, `success` or
+     * `warning` here, because [the specification's colour
+     * system](../design/color) has no way to derive them and a library that
+     * invented three more families would be promising tokens the sheet cannot
+     * produce. `error` is the one severity Material does name, and the rest is an
+     * emphasis decision: `primary` for a notice, `secondary` or `tertiary` for one
+     * that should sit further back.
+     * @default 'primary'
+     */
+    color?: MPColor;
+    /**
+     * The room inside, and the type scale of the text in it.
+     * @default 'md'
+     */
+    size?: MPSize;
+    /**
+     * The heading line. With it the alert is two-part — a headline and the detail
+     * under it; without it the whole thing is one line.
+     */
+    title?: React.ReactNode;
+    /**
+     * The glyph at the start.
+     *
+     * Defaults to the one that goes with `color`; pass `false` to drop it, or a
+     * node to replace it. Only two defaults exist because only two are honest: the
+     * error family gets the error glyph and everything else gets the informational
+     * one. An alert that means "this worked" should say so with an `icon` of its
+     * own rather than by having the library guess from a colour.
+     */
+    icon?: React.ReactNode | false;
+    /**
+     * Content pinned to the end of the row — a "Retry" button, a link. Kept out of
+     * `children` so it stays on the first line while the message wraps.
+     */
+    action?: React.ReactNode;
+    /** Passing it is what makes the dismiss button appear. */
+    onClose?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * The accessible name of the dismiss button. Defaults to the word for
+     * "dismiss" in `locale`.
+     */
+    closeLabel?: string;
+    /**
+     * Which language the dismiss button's default name is written in. Falls back
+     * to the nearest `MPLocaleProvider`, then to English.
+     */
+    locale?: string;
+    /** The message. */
+    children?: React.ReactNode;
+}
+/**
+ * A message about something that happened, set into the page it is about.
+ *
+ * The three shapes people mean by "an alert" are one component with different
+ * slots filled rather than three components: a bare line (`<MPAlert icon={false}>`),
+ * a line with a glyph (the default), and a glyph with a headline and the detail
+ * under it (`title` plus `children`). Nothing about the surface changes between
+ * them — only how much of it is used.
+ *
+ * There is no Base UI primitive under this, and there should not be: an alert has
+ * no interaction to delegate. It is a live region with a layout, and the only
+ * interactive parts it can grow — the action and the dismiss button — are real
+ * buttons that the caller either passes in or gets by passing `onClose`.
+ *
+ * ## Why this is not a snackbar
+ *
+ * An alert belongs to the flow of the page it interrupts; a snackbar floats over
+ * it and leaves on a timer. That is not a styling difference: a message the
+ * reader has to act on must not be able to disappear before it has been read,
+ * and a message about the page's *current* state has to still be there when they
+ * look back at it. If it can be missed without consequence, it is
+ * [MPSnackbar](../feedback/snackbar).
+ */
+export declare const MPAlert: React.ForwardRefExoticComponent<MPAlertProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/alert/MPAlert.js

@@ -0,0 +1 @@
+import{jsx as e,jsxs as t}from"react/jsx-runtime";import*as n from"react";import{MPIcon as r}from"../icon/MPIcon";import{CloseIcon as a,ErrorIcon as l,InfoIcon as o}from"../../constants/icons";import{accentSlots as i}from"../../internal/accent";import{useMPLocale as s,useMPMessages as c}from"../../internal/locale";import{MPStateLayer as m}from"../../internal/StateLayer";import{CONTROL_ICON as d,hasContent as f,PROSE_TEXT as p,SHEET_GAP as u,SHEET_PAD as x,SHEET_TITLE as h,STACK_GAP as v}from"../../internal/scale";const b={filled:"bg-(--_mp-accent) text-(--_mp-on-accent)",tonal:"bg-(--_mp-accent-container) text-(--_mp-on-accent-container)",elevated:"shadow-mp-1 bg-mp-surface-container-low text-mp-on-surface",outlined:"border-mp-outline border bg-transparent text-mp-on-surface",text:"bg-transparent text-mp-on-surface"},y={filled:"",tonal:"",elevated:"text-(--_mp-accent)",outlined:"text-(--_mp-accent)",text:"text-(--_mp-accent)"},N={filled:"",tonal:"",elevated:"text-mp-on-surface-variant",outlined:"text-mp-on-surface-variant",text:"text-mp-on-surface-variant"},j={primary:"status",secondary:"status",tertiary:"status",error:"alert"};export const MPAlert=n.forwardRef(function({variant:n="tonal",color:g="primary",size:_="md",title:w,icon:z,action:k,onClose:B,closeLabel:C,locale:L,className:M,style:P,children:A,...I},R){const S=s(L),$=c("alert",S),q=y[n],D=f(w),E=void 0===z?e(r,{icon:"error"===g?l:o,size:d[_]}):z;return t("div",{ref:R,role:j[g],"data-mp-size":_,"data-mp-variant":n,className:["mp-alert rounded-mp-md flex w-full items-start","box-border",x[_],u[_],p[_],b[n],M??""].filter(Boolean).join(" "),style:{...i(g),...P},...I,children:[f(E)?e("span",{className:["flex h-[1lh] shrink-0 items-center",q].filter(Boolean).join(" "),children:E}):null,t("div",{className:`flex min-w-0 flex-1 flex-col ${v[_]}`,children:[D?e("div",{className:[h[_],q].filter(Boolean).join(" "),children:w}):null,f(A)?e("div",{className:D?N[n]:void 0,children:A}):null]}),f(k)?e("div",{className:"flex h-[1lh] shrink-0 items-center",children:k}):null,B?e("span",{className:"flex h-[1lh] shrink-0 items-center",children:t("button",{type:"button","aria-label":C??$.dismiss,onClick:B,className:["group rounded-mp-full relative -m-1 flex size-8 cursor-pointer items-center","justify-center bg-transparent text-inherit","outline-mp-secondary focus-visible:outline-2 focus-visible:outline-offset-2","focus-visible:outline-solid outline-none"].join(" "),children:[e(m,{}),e(r,{icon:a,size:d[_]})]})}):null]})});

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

@@ -0,0 +1,2 @@
+export { MPAlert } from './MPAlert';
+export type { MPAlertProps } from './MPAlert';

package/dist/components/alert/index.js

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

package/dist/components/aspect-ratio/MPAspectRatio.d.ts

@@ -0,0 +1,69 @@
+import * as React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import type { MPSize } from '../../types';
+/**
+ * How the media inside is fitted to the box, spelled the way CSS spells it.
+ *
+ * These are `object-fit`'s own values rather than a nicer set of words, and for
+ * the same reason `MPSide` keeps `top`/`right`/`bottom`/`left`: inventing
+ * `fill-the-box` would only make a reader look up which CSS it maps to.
+ */
+export type MPAspectFit = 'cover' | 'contain' | 'fill' | 'none';
+export interface MPAspectRatioProps extends React.ComponentPropsWithoutRef<'div'> {
+    /**
+     * The proportion the box holds, written the way CSS writes it — a number
+     * (`1.5`) or a ratio (`'16 / 9'`). Both reach `aspect-ratio` untouched.
+     * @default 1
+     */
+    ratio?: number | string;
+    /**
+     * How a single piece of media inside is fitted.
+     *
+     * Applies to an `img`, a `video`, a `canvas`, an `svg`, a `picture` or an
+     * `iframe` that is a *direct* child; those are stretched to the full box and
+     * then fitted. Anything else is laid out normally and this prop does not reach
+     * it.
+     * @default 'cover'
+     */
+    fit?: MPAspectFit;
+    /**
+     * Rounds the corners to the `size` rung.
+     *
+     * Off by default. A layout component draws nothing, and a photograph with its
+     * corners cut is a decision about the photograph — but it is such a common one
+     * that making the caller reach for a `className` would be perverse.
+     * @default false
+     */
+    rounded?: boolean;
+    /**
+     * Which corner `rounded` uses. There is no height and no type scale on a box
+     * whose whole job is a proportion, so this is the one axis `size` has here.
+     * @default 'md'
+     */
+    size?: MPSize;
+    /**
+     * Renders something other than a `<div>`: `render={<figure />}`,
+     * `render={<a href="…" />}`. Base UI's own escape hatch.
+     */
+    render?: useRender.RenderProp;
+    children?: React.ReactNode;
+}
+/**
+ * A box that keeps a proportion whatever width it is given.
+ *
+ * It draws nothing — no surface, no border, no shadow, no colour — which is what
+ * makes it layout rather than a component in the Material sense. What it does is
+ * *reserve* the space: a card whose image arrives late does not reflow the page
+ * around it, and a row of thumbnails is a row of one shape.
+ *
+ * That is worth more than it sounds. Material's layout guidance is built on a
+ * grid whose rows line up, and the single most common way a real page stops
+ * lining up is media of unknown height arriving after the text around it has
+ * already been laid out.
+ *
+ * The proportion is CSS's own `aspect-ratio`, so a caller who already knows
+ * `16 / 9` has nothing to translate. `fit` is the one convenience on top: the
+ * media inside is stretched to the box and then fitted, which is the pair of
+ * declarations every use of this component would otherwise start with.
+ */
+export declare const MPAspectRatio: React.ForwardRefExoticComponent<MPAspectRatioProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/aspect-ratio/MPAspectRatio.js

@@ -0,0 +1 @@
+import*as e from"react";import{useRender as o}from"@base-ui/react/use-render";const i={xs:"rounded-mp-xs",sm:"rounded-mp-sm",md:"rounded-mp-md",lg:"rounded-mp-md",xl:"rounded-mp-xl"},t=["[&>img]:size-full","[&>video]:size-full","[&>canvas]:size-full","[&>svg]:size-full","[&>iframe]:size-full","[&>picture]:size-full","[&>picture>img]:size-full"].join(" "),r={cover:"[&>img]:object-cover [&>video]:object-cover [&>picture>img]:object-cover",contain:"[&>img]:object-contain [&>video]:object-contain [&>picture>img]:object-contain",fill:"[&>img]:object-fill [&>video]:object-fill [&>picture>img]:object-fill",none:"[&>img]:object-none [&>video]:object-none [&>picture>img]:object-none"};export const MPAspectRatio=e.forwardRef(function({ratio:e=1,fit:c="cover",rounded:l=!1,size:n="md",render:s,className:d,style:m,children:a,...u},f){const p=["mp-aspect-ratio relative block w-full overflow-hidden",t,r[c],l?i[n]:"",d??""].filter(Boolean).join(" ");return o({render:s,ref:f,props:{"data-mp-size":n,className:p,style:{aspectRatio:e,...m},children:a,...u}})});

package/dist/components/aspect-ratio/index.d.ts

@@ -0,0 +1,2 @@
+export { MPAspectRatio } from './MPAspectRatio';
+export type { MPAspectFit, MPAspectRatioProps } from './MPAspectRatio';

package/dist/components/aspect-ratio/index.js

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

package/dist/components/avatar/MPAvatar.d.ts

@@ -0,0 +1,97 @@
+import * as React from 'react';
+import type { MPColor, MPSize, MPVariant } from '../../types';
+/** What Base UI reports about the picture as it loads. */
+export type MPAvatarLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error';
+/**
+ * The crop.
+ *
+ * `circle` is the default and is what Material draws: MD3's avatar is a circle,
+ * and a round crop is what a portrait has been for as long as there have been
+ * portraits.
+ *
+ * `square` cuts the corners off instead, which is what a logo or a repository
+ * icon wants — those are drawn to the edges of a rectangle and a round crop eats
+ * them.
+ */
+export type MPAvatarShape = 'circle' | 'square';
+export interface MPAvatarProps extends Omit<React.ComponentPropsWithoutRef<'span'>, 'color'> {
+    /**
+     * The picture. Until it loads — and forever, if it fails — the fallback is
+     * what is drawn, so an avatar is never an empty box.
+     */
+    src?: string;
+    /** Candidate images at other resolutions, as on any `<img>`. */
+    srcSet?: string;
+    /**
+     * What the picture says, for a reader who cannot see it. Defaults to `name`,
+     * and to nothing at all when there is no name — an avatar next to the person's
+     * own name in the row is decoration, and reading it out says the name twice.
+     */
+    alt?: string;
+    /**
+     * Who or what this is. One prop doing three jobs: it names the picture, the
+     * initials are derived from it, and it is the sentence a screen reader hears
+     * instead of those initials.
+     *
+     * The initials are the first character of the first word plus the first
+     * character of the last — "Jane Doe" is `JD`, "홍길동" is `홍`. That rule is
+     * wrong for some names, which is what `initials` is for.
+     */
+    name?: string;
+    /** The initials, written out, for when the rule derived the wrong ones. */
+    initials?: string;
+    /**
+     * The crop.
+     * @default 'circle'
+     */
+    shape?: MPAvatarShape;
+    /**
+     * How much surface is painted behind the fallback. Invisible once a picture
+     * has loaded, apart from the edge `outlined` keeps.
+     *
+     * `tonal` is the default because it is what MD3 draws a monogram on: the
+     * container tone of the accent family, with the matching `on-` ink. A page of
+     * `filled` avatars is a page of saturated circles nobody can read a name off.
+     * @default 'tonal'
+     */
+    variant?: MPVariant;
+    /**
+     * The box the picture is drawn in — the control heights, so an avatar and the
+     * button beside it in a toolbar are the same height.
+     * @default 'md'
+     */
+    size?: MPSize;
+    /** @default 'primary' */
+    color?: MPColor;
+    /**
+     * How long to wait before drawing the fallback, in milliseconds. Set it to
+     * roughly the time a cached image takes and the initials stop flashing up in
+     * front of a picture that was about to arrive anyway.
+     */
+    delay?: number;
+    /** Anything else the `<img>` needs — `loading`, `crossOrigin`, `referrerPolicy`. */
+    imageProps?: Omit<React.ComponentPropsWithoutRef<'img'>, 'src' | 'srcSet' | 'alt'>;
+    /** Called as the picture moves between `idle`, `loading`, `loaded` and `error`. */
+    onLoadingStatusChange?: (status: MPAvatarLoadingStatus) => void;
+    /**
+     * The fallback, drawn instead of the initials. An icon, a logo, a single emoji
+     * — whatever stands in for this particular thing when there is no picture of
+     * it.
+     */
+    children?: React.ReactNode;
+}
+/**
+ * A picture of a person or a thing, at a known size, that is never an empty box.
+ *
+ * Three things can be drawn in it and exactly one of them is at a time: the
+ * picture, if `src` is given and loads; otherwise whatever stands in for it —
+ * `children`, or `initials`, or the initials derived from `name`; and failing
+ * all of those, a silhouette. Which one is showing is Base UI's `Avatar` to
+ * decide, because "has the image loaded" is a question with four answers and a
+ * race in the middle of it.
+ *
+ * It carries no status dot of its own. An avatar with a green mark on it is an
+ * `MPBadge` with an avatar in it, and inventing a second spelling for that would
+ * give the library two of them.
+ */
+export declare const MPAvatar: React.ForwardRefExoticComponent<MPAvatarProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/avatar/MPAvatar.js

@@ -0,0 +1 @@
+import{jsx as e,jsxs as a}from"react/jsx-runtime";import*as t from"react";import{Avatar as n}from"@base-ui/react/avatar";import{accentSlots as r}from"../../internal/accent";import{CONTROL_SQUARE as l,hasContent as i}from"../../internal/scale";import{VISUALLY_HIDDEN as o}from"../../internal/visually-hidden";const m={xs:"text-mp-label-medium",sm:"text-mp-label-large",md:"text-mp-title-large",lg:"text-mp-headline-small",xl:"text-mp-headline-medium"},s={xs:"rounded-mp-xs",sm:"rounded-mp-sm",md:"rounded-mp-md",lg:"rounded-mp-md",xl:"rounded-mp-md"},c={filled:"bg-(--_mp-accent) text-(--_mp-on-accent)",tonal:"bg-(--_mp-accent-container) text-(--_mp-on-accent-container)",elevated:"shadow-mp-1 bg-mp-surface-container-low text-(--_mp-accent)",outlined:"border-mp-outline border bg-transparent text-(--_mp-accent)",text:"text-mp-on-surface-variant bg-transparent"};function d(){return a("svg",{viewBox:"0 0 24 24",fill:"currentColor","aria-hidden":"true",className:"size-[60%]",children:[e("path",{d:"M12 12a4.5 4.5 0 1 0 0-9 4.5 4.5 0 0 0 0 9Z"}),e("path",{d:"M12 14.25c-4.28 0-7.75 2.42-7.75 5.4 0 .75.6 1.35 1.35 1.35h12.8c.75 0 1.35-.6 1.35-1.35 0-2.98-3.47-5.4-7.75-5.4Z"})]})}export const MPAvatar=t.forwardRef(function({src:t,srcSet:p,alt:u,name:f,initials:h,shape:x="circle",variant:g="tonal",size:v="md",color:b="primary",delay:y,imageProps:N,onLoadingStatusChange:j,className:w,style:z,children:_,...C},A){const B=f?function(e){const a=e.normalize("NFC").trim().split(/\s+/).filter(Boolean);return 0===a.length?"":((Array.from(a[0])[0]??"")+(a.length>1?Array.from(a[a.length-1])[0]??"":"")).toLocaleUpperCase()}(f):"",S=u??f,L=i(_)?_:(h??B)||e(d,{}),M=i(_)||Boolean(h??B),k=["mp-avatar relative inline-flex shrink-0 items-center justify-center overflow-hidden","align-middle leading-none font-medium whitespace-nowrap select-none",l[v],m[v],"circle"===x?"rounded-mp-full":s[v],c[g],w??""].filter(Boolean).join(" ");return a(n.Root,{ref:A,"data-mp-size":v,"data-mp-variant":g,className:k,style:{...r(b),...z},...C,children:[t?e(n.Image,{src:t,srcSet:p,alt:S??"",className:"size-full object-cover",onLoadingStatusChange:j,...N}):null,a(n.Fallback,{delay:t?y:void 0,className:"flex size-full items-center justify-center",children:[S&&M?e("span",{className:o,children:S}):null,e("span",{"aria-hidden":!(!S||!M)||void 0,className:"contents",children:L})]})]})});

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

@@ -0,0 +1,2 @@
+export { MPAvatar } from './MPAvatar';
+export type { MPAvatarLoadingStatus, MPAvatarProps, MPAvatarShape } from './MPAvatar';

package/dist/components/avatar/index.js

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