material-plus-ui 1.6.0 → 1.8.0

package/dist/components/gauge-chart/MPGaugeChart.d.ts

@@ -0,0 +1,78 @@
+import * as React from 'react';
+import type { MPColor, MPSize, MPThreshold } from '../../types.js';
+export interface MPGaugeChartProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'color' | 'children'> {
+    /** The reading. */
+    value: number;
+    /** @default 0 */
+    min?: number;
+    /** @default 100 */
+    max?: number;
+    /**
+     * How far round the dial goes, in degrees, centred on twelve o'clock.
+     *
+     * `180` is a half dial sitting on its base; `240` is the classic gauge, open
+     * at the bottom. Past about 300 the two ends meet and the reader can no
+     * longer tell the start from the finish.
+     * @default 240
+     */
+    sweep?: number;
+    /** What the reading is called, under the figure. */
+    label?: React.ReactNode;
+    /**
+     * Where the reading changes colour. The last threshold it has reached wins,
+     * so they are listed smallest first.
+     */
+    thresholds?: readonly MPThreshold[];
+    /**
+     * Paints the **track** in threshold bands as well as the fill, so a reader
+     * sees where the trouble starts before the needle gets there.
+     * @default false
+     */
+    bands?: boolean;
+    /** The family the dial carries before any threshold is reached. @default 'primary' */
+    color?: MPColor;
+    /** How the figure in the middle is written. */
+    format?: Intl.NumberFormatOptions;
+    /** Which language that figure is written in. */
+    locale?: string;
+    /** How tall the drawing is. Defaults to the `size` ladder. */
+    height?: number | string;
+    /** @default 'md' */
+    size?: MPSize;
+}
+/**
+ * One reading on a dial.
+ *
+ * ```tsx
+ * <MPGaugeChart value={72} label="CPU" thresholds={[{ from: 80, color: 'error' }]} />
+ * ```
+ *
+ * ## Consider not using one
+ *
+ * A gauge spends a whole panel on a single number, and the arc adds nothing a
+ * reader could not get from the figure and a bar: an angle is judged less
+ * accurately than a length, and a dial's ends are the two places the eye is
+ * worst at. [MPStatistic](statistic) with an [MPMeter](../feedback/meter) under
+ * it says the same thing in a third of the room and reads better.
+ *
+ * What a gauge is genuinely good for is a **thresholded** reading somebody
+ * watches — a dial where the amber band is drawn on the face, so the question
+ * "how close is this to trouble" is answered by where the needle sits rather
+ * than by arithmetic. That is what `bands` is for, and it is the case worth
+ * reaching for this shape over the other two.
+ *
+ * ## It is a meter, in the markup
+ *
+ * `role="meter"` with the value, the minimum and the maximum on it — the same
+ * semantics [MPMeter](../feedback/meter) carries, because they are the same
+ * quantity in two shapes. There is no table behind it and no hover layer: a
+ * chart of one number has nothing a reader could uncover that the figure in the
+ * middle is not already saying.
+ *
+ * ## Thresholds name roles
+ *
+ * `{ from: 80, color: 'error' }` and never a hex, so a dial and a bar on the
+ * same page cannot disagree about where the amber starts. Both read the same
+ * resolver.
+ */
+export declare function MPGaugeChart({ value, min, max, sweep, label, thresholds, bands, color: colorProp, format, locale: localeProp, height, size: sizeProp, className, style, ...props }: MPGaugeChartProps): React.JSX.Element;

package/dist/components/gauge-chart/MPGaugeChart.js

@@ -0,0 +1,2 @@
+"use client";
+import{jsx as e,jsxs as t}from"react/jsx-runtime";import*as a from"react";import{Meter as l}from"@base-ui/react/meter";import{useMPElementSize as r}from"../../hooks/useMPElementSize.js";import{useMPColor as o,useMPSize as m}from"../../internal/config.js";import{useMPLocale as i}from"../../internal/locale.js";import{accentSlots as s}from"../../internal/accent.js";import{thresholdColor as n}from"../../internal/threshold.js";import{progressFraction as c}from"../../internal/progress.js";import{CHART_FONT_SIZE as h,PLOT_HEIGHT as p,arcPath as f,formatStatistic as u}from"../../internal/chart.js";import{cssLength as d}from"../../internal/length.js";import{META_TEXT as x}from"../../internal/scale.js";const g={xs:"text-mp-title-medium",sm:"text-mp-title-large",md:"text-mp-headline-small",lg:"text-mp-headline-medium",xl:"text-mp-display-small"};export function MPGaugeChart({value:v,min:j=0,max:M=100,sweep:_=240,label:b,thresholds:y,bands:w=!1,color:N,format:P,locale:$,height:z,size:I,className:k,style:B,...R}){const C=m(I),E=o(N),G=i($),L=a.useRef(null),S=r(L),V=c(v,j,M)??0,W=n(v,E,y),q=h[C],A=S.width,D="number"==typeof z?z:void 0===z?p[C]:S.height,F=Math.min(300,Math.max(30,_))*Math.PI/180,H=F/2,J=H>Math.PI/2?Math.cos(Math.PI-H):0,K=Math.min(A/2,D/(1+J)),O=Math.max(0,K-2),Q=.78*O,T=A/2,U=O+2,X=-H,Y=H,Z=X+V*F,ee=a.useMemo(()=>{if(!w||!y||0===y.length)return[{from:0,to:1,color:E}];const e=[...y.map(e=>({at:c(e.from,j,M)??0,color:e.color})).filter(e=>e.at>0&&e.at<1).sort((e,t)=>e.at-t.at)],t=[];let a=0,l=E;for(const r of e)t.push({from:a,to:r.at,color:l}),a=r.at,l=r.color;return t.push({from:a,to:1,color:l}),t},[w,y,E,j,M]),te=u(v,G,P,!1);return t(l.Root,{value:v,min:j,max:M,format:P,"data-mp-size":C,className:["mp-gauge-chart flex min-w-0 flex-col items-center",k??""].filter(Boolean).join(" "),style:{...s(W),...B},...R,children:[t("div",{ref:L,className:"mp-gauge-chart__dial relative w-full",style:{height:d(z)??p[C]},children:[A>0&&O>0?t("svg",{width:A,height:D,viewBox:`0 0 ${A} ${D}`,"aria-hidden":"true",className:"block overflow-visible",children:[ee.map((t,a)=>e("path",{d:f(T,U,O,Q,X+t.from*F,X+t.to*F),fill:w?`var(--_mp-color-${t.color})`:"var(--_mp-color-on-surface)",opacity:w?.22:.12},a)),e("path",{d:f(T,U,O,Q,X,Z),fill:"var(--_mp-accent)"}),e("path",{d:f(T,U,O,Q,X,X+.004*F),fill:"var(--_mp-color-outline)"}),e("path",{d:f(T,U,O,Q,Y-.004*F,Y),fill:"var(--_mp-color-outline)"})]}):null,t("div",{className:"pointer-events-none absolute inset-x-0 flex flex-col items-center",style:{top:U-.45*Q},children:[e(l.Value,{className:`mp-gauge-chart__value text-mp-on-surface font-medium tabular-nums ${g[C]}`,children:e=>P?e:te}),b?e(l.Label,{className:`mp-gauge-chart__label text-mp-on-surface-variant ${x}`,style:{maxWidth:1.8*Q},children:b}):null]})]}),J>0?e("span",{"aria-hidden":"true",style:{height:q/2}}):null]})}

package/dist/components/gauge-chart/index.d.ts

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

package/dist/components/gauge-chart/index.js

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

package/dist/components/grid/MPGrid.d.ts

@@ -15,19 +15,28 @@ export type MPGridAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
 /** The same, for one item overriding the row it is in. */
 export type MPGridAlignSelf = MPGridAlign | 'auto';
 /**
- * How wide one item is: a number of the grid's columns, or `'grow'`.
+ * How wide one item is: a number of the grid's columns, `'grow'` or `'auto'`.
  *
- * `'grow'` is the one value that is not a measurement. It is "whatever the row
- * has left after everybody else has taken theirs", which is the width a
- * thumbnail's neighbour wants and the one thing a twelve-column arithmetic
- * cannot express — the remainder is only known once the other items in *that*
- * row have been laid out, and no `span` a caller writes down knows what else is
- * in the row.
+ * Neither word is a measurement, and they are the two ends of the same question
+ * a column count cannot answer. `'grow'` is "whatever the row has left after
+ * everybody else has taken theirs" — the width a thumbnail's neighbour wants,
+ * and one the arithmetic cannot reach because the remainder is only known once
+ * the other items in *that* row have been laid out. `'auto'` is "exactly what is
+ * inside me", which the arithmetic cannot reach either: what is inside an item
+ * is measured by the browser, and a share of twelve columns has to be written
+ * down in advance.
+ *
+ * They pair. A control bar whose left half is a set of transport buttons and
+ * whose right half is however many icon buttons the page turned out to need is
+ * `span="grow"` and `span="auto"`, and neither side has a number in it — which
+ * matters because the number would be wrong: four 32px buttons in `span={2}` of
+ * a 768px bar is 128px against 128px, and the pixel that sub-pixel rounding
+ * takes off wraps the last button onto a second row.
  *
  * Two growing items in a row split the remainder equally rather than by their
  * contents, which is the useful half of what makes it predictable.
  */
-export type MPGridSpan = number | 'grow';
+export type MPGridSpan = number | 'grow' | 'auto';
 export interface MPGridProps extends React.ComponentPropsWithoutRef<'div'> {
     /**
      * How many columns a row is divided into. Every `span` and every `offset`
@@ -96,6 +105,14 @@ export interface MPGridItemProps extends React.ComponentPropsWithoutRef<'div'> {
      * when the picture's column count changes. It is responsive like any other
      * value: `span={{ compact: 12, medium: 'grow' }}` stacks on a phone and fills
      * the rest of the row from 600dp.
+     *
+     * `span="auto"` is the other end of that: exactly the width of what is inside
+     * the item, however much that turns out to be. It is the span for a group
+     * whose size is a runtime question — a row of icon buttons where how many
+     * there are depends on what the page can do — and it pairs with `'grow'`, one
+     * item taking what it needs and the other taking the rest. An `'auto'` item
+     * does not shrink, so contents wider than the row overflow rather than
+     * squeezing what is beside them.
      * @default the grid's full width
      */
     span?: MPResponsive<MPGridSpan>;

package/dist/components/grid/MPGrid.js

@@ -1,2 +1,2 @@
 "use client";
-import*as e from"react";import{useRender as t}from"@base-ui/react/use-render";import{WINDOW_CLASSES as n}from"../../internal/window-class.js";function r(e){return null==e?{}:"object"==typeof e?e:{compact:e}}function o(e,t,o){const s=r(t),a={};for(const t of n){const n=s[t];void 0!==n&&(a[`--_mp-${e}-${t}`]=o(n))}return a}function s(e,t){return null==e?t:"object"==typeof e?{compact:t,...e}:e}function a(e){return String(Math.max(1,Math.round(e)))}function c(e){return String(Math.max(1,Math.round(e)))}function i(e){const t=r(e),o=Object.values(t).some(e=>"grow"===e),s={};for(const e of n){const n=t[e];void 0!==n&&("grow"!==n&&(s[`--_mp-span-${e}`]=c(n)),o&&(s[`--_mp-grow-${e}`]="grow"===n?"1":"0"))}return s}function f(e){return String(Math.max(0,Math.round(e)))}function l(e){const t=.25*Math.max(0,e);return`${Number(t.toFixed(5))}rem`}const u={start:"justify-start",center:"justify-center",end:"justify-end","space-between":"justify-between","space-around":"justify-around","space-evenly":"justify-evenly"},p={start:"items-start",center:"items-center",end:"items-end",stretch:"items-stretch",baseline:"items-baseline"},m={start:"content-start",center:"content-center",end:"content-end","space-between":"content-between","space-around":"content-around","space-evenly":"content-evenly",stretch:"content-stretch"},d={auto:"self-auto",start:"self-start",center:"self-center",end:"self-end",stretch:"self-stretch",baseline:"self-baseline"};export const MPGrid=/*@__PURE__*/e.forwardRef(function({columns:e,spacing:n,rowSpacing:r,columnSpacing:c,justifyContent:i,alignItems:f,alignContent:d,wrap:g=!0,render:y,className:h,style:w,children:b,...j},x){return t({render:y,ref:x,props:{className:["mp-grid flex",g?"flex-wrap":"flex-nowrap","gap-x-(--_mp-gap-x) gap-y-(--_mp-gap-y)",i?u[i]:"",f?p[f]:"",d?m[d]:"",h??""].filter(Boolean).join(" "),style:{...o("cols",s(e,12),a),...o("gap-x",s(c??n,4),l),...o("gap-y",s(r??n,4),l),...w},children:b,...j}})});export const MPGridItem=/*@__PURE__*/e.forwardRef(function({span:e,offset:n,alignSelf:r,render:s,className:a,style:c,children:l,...u},p){return t({render:s,ref:p,props:{className:["mp-grid-item",r?d[r]:"",a??""].filter(Boolean).join(" "),style:{...i(e),...o("offset",n,f),...c},children:l,...u}})});
+import*as e from"react";import{useRender as t}from"@base-ui/react/use-render";import{classMap as n,responsiveSlots as r,withBaseline as s}from"../../internal/responsive.js";import{WINDOW_CLASSES as a}from"../../internal/window-class.js";function o(e){return String(Math.max(1,Math.round(e)))}function c(e){return String(Math.max(1,Math.round(e)))}function i(e){const t=n(e),r=Object.values(t),s=r.some(e=>"grow"===e),o=r.some(e=>"auto"===e),i={};for(const e of a){const n=t[e];void 0!==n&&("grow"!==n&&"auto"!==n&&(i[`--_mp-span-${e}`]=c(n)),s&&(i[`--_mp-grow-${e}`]="grow"===n?"1":"0"),o&&(i[`--_mp-width-${e}`]="auto"===n?"auto":"var(--_mp-span-width)"))}return i}function l(e){return String(Math.max(0,Math.round(e)))}function f(e){const t=.25*Math.max(0,e);return`${Number(t.toFixed(5))}rem`}const p={start:"justify-start",center:"justify-center",end:"justify-end","space-between":"justify-between","space-around":"justify-around","space-evenly":"justify-evenly"},u={start:"items-start",center:"items-center",end:"items-end",stretch:"items-stretch",baseline:"items-baseline"},m={start:"content-start",center:"content-center",end:"content-end","space-between":"content-between","space-around":"content-around","space-evenly":"content-evenly",stretch:"content-stretch"},d={auto:"self-auto",start:"self-start",center:"self-center",end:"self-end",stretch:"self-stretch",baseline:"self-baseline"};export const MPGrid=/*@__PURE__*/e.forwardRef(function({columns:e,spacing:n,rowSpacing:a,columnSpacing:c,justifyContent:i,alignItems:l,alignContent:d,wrap:g=!0,render:h,className:w,style:y,children:x,...j},b){return t({render:h,ref:b,props:{className:["mp-grid flex",g?"flex-wrap":"flex-nowrap","gap-x-(--_mp-gap-x) gap-y-(--_mp-gap-y)",i?p[i]:"",l?u[l]:"",d?m[d]:"",w??""].filter(Boolean).join(" "),style:{...r("cols",s(e,12),o),...r("gap-x",s(c??n,4),f),...r("gap-y",s(a??n,4),f),...y},children:x,...j}})});export const MPGridItem=/*@__PURE__*/e.forwardRef(function({span:e,offset:n,alignSelf:s,render:a,className:o,style:c,children:f,...p},u){return t({render:a,ref:u,props:{className:["mp-grid-item",s?d[s]:"",o??""].filter(Boolean).join(" "),"data-mp-offset":null==n?void 0:"",style:{...i(e),...r("offset",n,l),...c},children:f,...p}})});

package/dist/components/header/MPHeader.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { useRender } from '@base-ui/react/use-render';
-import type { MPAlign, MPPosition, MPSize, MPVariant } from '../../types.js';
+import type { MPAlign, MPDensity, MPMeasure, MPPosition, MPResponsive, MPSize, MPElevation, MPVariant } from '../../types.js';
 export interface MPHeaderProps extends Omit<React.ComponentPropsWithoutRef<'header'>, 'title'> {
     /**
      * The leading slot: the mark, the product's name, the thing that is the same
@@ -50,6 +50,16 @@ export interface MPHeaderProps extends Omit<React.ComponentPropsWithoutRef<'head
      * @default 'tonal'
      */
     variant?: MPVariant;
+    /**
+     * How far off the page the bar is lifted, on MD3's own scale.
+     *
+     * It moves the tone as well as the shadow — see `MPElevation`. A bar's
+     * `elevated` is level 2 rather than 1, because a bar sits over the page's
+     * content rather than in it; an explicit level says exactly what it says.
+     *
+     * Left unset, `variant` decides.
+     */
+    elevation?: MPElevation;
     /**
      * The bar's height floor, its gutter and the air between its slots.
      *
@@ -59,13 +69,25 @@ export interface MPHeaderProps extends Omit<React.ComponentPropsWithoutRef<'head
      * @default 'md'
      */
     size?: MPSize;
+    /**
+     * Takes room out of the bar's gutter.
+     *
+     * The height floor is `size`'s and stays where it is: a top app bar that a
+     * dense page shrank would move every fixed thing under it, and the bar is the
+     * one part of a screen a reader locates by position. What tightens is the
+     * room at its edges.
+     * @default 0
+     */
+    density?: MPDensity;
     /**
      * Holds the row of slots to a measure and centres it while the sheet itself
-     * still spans the window. The same ladder [MPContainer](./container)'s
-     * `maxWidth` uses, so a header and the container under it line up on one edge.
+     * still spans the window. The same prop [MPContainer](./container)'s
+     * `maxWidth` is — a rung of the size ladder, a CSS length of your own, or a
+     * map keyed by window size class — so a header and the container under it line
+     * up on one edge by being given the same value.
      * @default 'none'
      */
-    maxWidth?: MPSize | 'none';
+    maxWidth?: MPResponsive<MPMeasure>;
     /**
      * The gutter down each side of the row.
      * @default true

package/dist/components/header/MPHeader.js

@@ -1,2 +1,2 @@
 "use client";
-import{jsx as e,jsxs as t}from"react/jsx-runtime";import*as a from"react";import{useRender as i}from"@base-ui/react/use-render";import{BAR_SURFACE as n,MPPageLayoutContext as r}from"../../internal/page-layout.js";import{hasContent as s,MEASURE as l,SHEET_PAD_X as m}from"../../internal/scale.js";import{useMPSize as d}from"../../internal/config.js";const o={xs:"min-h-12",sm:"min-h-14",md:"min-h-16",lg:"min-h-20",xl:"min-h-24"},c={xs:"text-mp-title-small",sm:"text-mp-title-medium",md:"text-mp-title-large",lg:"text-mp-headline-small",xl:"text-mp-headline-medium"},p={xs:"gap-1.5",sm:"gap-2",md:"gap-3",lg:"gap-4",xl:"gap-5"},x={xs:"gap-3",sm:"gap-4",md:"gap-6",lg:"gap-8",xl:"gap-10"},f={static:"",absolute:"absolute inset-x-0 top-0 z-30",sticky:"sticky top-0 z-30",fixed:"fixed inset-x-0 top-0 z-40"},u={start:"shrink-0",center:"flex-1 basis-0",end:"shrink-0"},h={start:"flex min-w-0 flex-1 items-center justify-start",center:"flex min-w-0 shrink items-center justify-center",end:"flex min-w-0 flex-1 items-center justify-end"};export const MPHeader=/*@__PURE__*/a.forwardRef(function({brand:g,actions:b,align:j="start",position:v="sticky",variant:w="tonal",size:y,maxWidth:N="none",padded:k=!0,label:_,render:z,className:$,children:B,...C},H){const M=d(y),{register:P}=a.useContext(r),R=a.useCallback(e=>{P("header",e),"function"==typeof H?H(e):H&&(H.current=e)},[P,H]);return i({render:z??e("header",{}),ref:R,props:{"aria-label":_,"data-mp-size":M,"data-mp-variant":w,className:["mp-header text-mp-on-surface box-border w-full min-w-0",n[w],"outlined"===w?"border-mp-outline-variant border-b":"",f[v],$??""].filter(Boolean).join(" "),children:t("div",{className:["flex w-full items-center",o[M],x[M],k?m[M]:"","none"===N?"":`${l[N]} mx-auto`].filter(Boolean).join(" "),children:[s(g)?e("div",{className:["mp-header__brand flex min-w-0 items-center",u[j],p[M],c[M]].join(" "),children:g}):"center"===j?e("div",{"aria-hidden":"true",className:u[j]}):null,s(B)?e("div",{className:`mp-header__middle ${h[j]} ${p[M]}`,children:B}):null,s(b)?e("div",{className:["mp-header__actions flex min-w-0 items-center justify-end",u[j],p[M]].join(" "),children:b}):"center"===j?e("div",{"aria-hidden":"true",className:u[j]}):null]}),...C}})});
+import{jsx as e,jsxs as t}from"react/jsx-runtime";import*as i from"react";import{useRender as n}from"@base-ui/react/use-render";import{barSurface as r,MPPageLayoutContext as a}from"../../internal/page-layout.js";import{hasContent as s}from"../../internal/scale.js";import{sheetPadX as l}from"../../internal/density.js";import{measureValue as m}from"../../internal/measure.js";import{useWindowMins as o}from"../../internal/window-class.js";import{responsiveSlots as d,withBaseline as c}from"../../internal/responsive.js";import{useMPDensity as p,useMPSize as f}from"../../internal/config.js";const x={xs:"min-h-12",sm:"min-h-14",md:"min-h-16",lg:"min-h-20",xl:"min-h-24"},u={xs:"text-mp-title-small",sm:"text-mp-title-medium",md:"text-mp-title-large",lg:"text-mp-headline-small",xl:"text-mp-headline-medium"},h={xs:"gap-1.5",sm:"gap-2",md:"gap-3",lg:"gap-4",xl:"gap-5"},g={xs:"gap-3",sm:"gap-4",md:"gap-6",lg:"gap-8",xl:"gap-10"},j={static:"",absolute:"absolute inset-x-0 top-0 z-30",sticky:"sticky top-0 z-30",fixed:"fixed inset-x-0 top-0 z-40"},b={start:"shrink-0",center:"flex-1 basis-0",end:"shrink-0"},v={start:"flex min-w-0 flex-1 items-center justify-start",center:"flex min-w-0 shrink items-center justify-center",end:"flex min-w-0 flex-1 items-center justify-end"};export const MPHeader=/*@__PURE__*/i.forwardRef(function({brand:y,actions:w,align:N="start",position:k="sticky",variant:_="tonal",elevation:z,size:B,density:C,maxWidth:$="none",padded:H=!0,label:M,render:P,className:R,children:W,...q},A){const D=f(B),E=p(C),F=o(),{register:G}=i.useContext(a),I=i.useCallback(e=>{G("header",e),"function"==typeof A?A(e):A&&(A.current=e)},[G,A]);return n({render:P??e("header",{}),ref:I,props:{"aria-label":M,"data-mp-size":D,"data-mp-variant":_,className:["mp-header text-mp-on-surface box-border w-full min-w-0",r(_,z),"outlined"===_?"border-mp-outline-variant border-b":"",j[k],R??""].filter(Boolean).join(" "),children:t("div",{className:["flex w-full items-center",x[D],g[D],H?l(D,E):"","none"===$?"":"mp-measure mx-auto"].filter(Boolean).join(" "),style:"none"===$?void 0:d("measure",c($,"none"),e=>m(e,F)),children:[s(y)?e("div",{className:["mp-header__brand flex min-w-0 items-center",b[N],h[D],u[D]].join(" "),children:y}):"center"===N?e("div",{"aria-hidden":"true",className:b[N]}):null,s(W)?e("div",{className:`mp-header__middle ${v[N]} ${h[D]}`,children:W}):null,s(w)?e("div",{className:["mp-header__actions flex min-w-0 items-center justify-end",b[N],h[D]].join(" "),children:w}):"center"===N?e("div",{"aria-hidden":"true",className:b[N]}):null]}),...q}})});

package/dist/components/heatmap-chart/MPHeatmapChart.d.ts

@@ -0,0 +1,75 @@
+import * as React from 'react';
+import { type ChartBaseProps } from '../../internal/ChartChrome.js';
+import type { MPChartAxis, MPChartCategory, MPChartSeries } from '../../types.js';
+export interface MPHeatmapChartProps extends ChartBaseProps {
+    /**
+     * The rows. Each series is one row and its `data` are that row's cells, in
+     * the order `categories` names the columns.
+     */
+    series: readonly MPChartSeries[];
+    /** The column headings. */
+    categories?: readonly MPChartCategory[];
+    /** The column axis. Only `label`, `hidden` and `tickFormat` mean anything here. */
+    xAxis?: MPChartAxis;
+    /** The row axis, same three. */
+    yAxis?: MPChartAxis;
+    /**
+     * Where the colour scale starts and ends. Taken from the data otherwise.
+     *
+     * Worth pinning when two heatmaps are meant to be compared: without it each
+     * one scales to its own range, and the darkest cell of a quiet week looks
+     * exactly like the darkest cell of a bad one.
+     */
+    min?: number;
+    max?: number;
+    /**
+     * Writes each cell's value in it, where the cell is big enough to hold the
+     * text. One that does not fit is dropped rather than clipped.
+     * @default false
+     */
+    valueLabels?: boolean;
+}
+/**
+ * A grid of cells, coloured by how much.
+ *
+ * ```tsx
+ * <MPHeatmapChart
+ *   categories={['Mon', 'Tue', 'Wed']}
+ *   series={[
+ *     { name: '09:00', data: [4, 9, 2] },
+ *     { name: '10:00', data: [7, 12, 5] }
+ *   ]}
+ * />
+ * ```
+ *
+ * Two categorical axes and a magnitude in the cells. It is the shape for a
+ * pattern across two dimensions — a week by hour, a cohort by month — where
+ * what a reader is looking for is *where* the dense part is rather than what
+ * any one cell holds.
+ *
+ * ## Its colour is a ramp, not the palette
+ *
+ * The eight chart slots are an **identity** channel: they say which series, and
+ * nobody can tell whether slot 6 is more than slot 3. A cell's colour here has
+ * to say how much, so it comes from a sequential ramp instead — one hue, five
+ * steps, running pale to deep on a light page and deep to bright on a dark one,
+ * because "more" has to be further from the page in both.
+ *
+ * That also sidesteps the cap the palette runs into: every cell touches its
+ * neighbours, and colour separates only three touching series. A ramp is not
+ * being asked to separate anything — it is being asked to be ordered.
+ *
+ * ## Steps rather than a gradient
+ *
+ * A smooth fill looks better and reads worse. Given a gradient a reader can say
+ * "darker" and nothing else; given five steps they can match a cell to a band
+ * in the legend and come away with a number.
+ *
+ * ## Pin the scale to compare two of them
+ *
+ * By default each heatmap scales to its own range, so two side by side say
+ * nothing to each other — the darkest cell of a quiet week looks exactly like
+ * the darkest cell of a bad one. Give both the same `min` and `max` when the
+ * comparison is the point.
+ */
+export declare function MPHeatmapChart({ series, categories, xAxis, yAxis, min, max, valueLabels, height, format, locale: localeProp, label, legend, tooltip, empty, size: sizeProp, className, style, ...rest }: MPHeatmapChartProps): React.JSX.Element;

package/dist/components/heatmap-chart/MPHeatmapChart.js

@@ -0,0 +1,2 @@
+"use client";
+import{jsx as e,jsxs as l}from"react/jsx-runtime";import*as t from"react";import{useMPElementSize as n}from"../../hooks/useMPElementSize.js";import{useMPLocale as a,useMPMessages as r}from"../../internal/locale.js";import{useMPSize as o}from"../../internal/config.js";import{CHART as i}from"../../internal/messages/chart.js";import{TABLE as m}from"../../internal/messages/table.js";import{ChartShell as s,ChartTable as c,ChartTooltipPanel as h}from"../../internal/ChartChrome.js";import{CHART_FONT_SIZE as u,MARK_GAP as d,PLOT_HEIGHT as f,RAMP_STEPS as p,formatCategory as x,formatStatistic as g,rampFill as v,rampInk as y,rampStep as w,textWidth as b,toValues as k,truncate as M}from"../../internal/chart.js";export function MPHeatmapChart({series:j,categories:A,xAxis:N,yAxis:S,min:$,max:_,valueLabels:z=!1,height:B,format:C,locale:P,label:D,legend:R,tooltip:L,empty:E,size:F,className:I,style:W,...H}){const K=o(F),U=a(P),X=r(i,U),Y=r(m,U),q=t.useRef(null),G=n(q),J=t.useId(),[O,Q]=t.useState(null),T=t.useMemo(()=>k(j),[j]),V=T.reduce((e,l)=>Math.max(e,l.length),0),Z=t.useCallback(e=>g(e,U,C,!0),[C,U]),ee=j.map((e,l)=>e.name??String(l+1)),le=Array.from({length:V},(e,l)=>N?.tickFormat?String(N.tickFormat(A?.[l]??l,l)):x(A?.[l]??l,U)),te=T.flat().filter(e=>null!==e.value),ne=$??(te.length>0?Math.min(...te.map(e=>e.value)):0),ae=_??(te.length>0?Math.max(...te.map(e=>e.value)):0),re=ae-ne||1,oe=u[K],ie=G.width,me="number"==typeof B?B:void 0===B?f[K]:G.height,se=ee.reduce((e,l)=>Math.max(e,b(l,oe)),0),ce=S?.hidden?0:S?.thickness??Math.min(140,se+10),he=N?.hidden?0:N?.thickness??oe+12,ue=ce,de=0,fe=Math.max(0,ie-ce),pe=Math.max(0,me-he),xe=V>0?fe/V:0,ge=T.length>0?pe/T.length:0,ve=(e,l)=>{Q(t=>{const n=t??{row:0,column:0};return{row:Math.min(T.length-1,Math.max(0,n.row+(t?e:0))),column:Math.min(V-1,Math.max(0,n.column+(t?l:0)))}})},ye=O?T[O.row]?.[O.column]??null:null,we=O&&ye&&null!==ye.value?[{seriesIndex:O.row,name:ee[O.row],color:v(w((ye.value-ne)/re)),value:ye.value,formatted:Z(ye.value),label:ye.label}]:[],be=!1===L?{mode:"none"}:!0===L||void 0===L?{}:L,ke=!1!==R&&te.length>0,Me=0===V||0===T.length||0===te.length,je=Array.from({length:V},(e,l)=>T.map(e=>e[l]??{value:null}));return e(s,{...H,size:K,className:["mp-heatmap-chart",I??""].filter(Boolean).join(" "),style:W,plotRef:q,name:D??X.label,describedBy:Me?void 0:J,interactive:!Me,height:B,legendSide:"bottom",plotProps:{onPointerMove:Me||"none"===be.mode?void 0:e=>Q(((e,l)=>{const t=q.current;if(!t||xe<=0||ge<=0)return null;const n=t.getBoundingClientRect(),a=Math.floor((e-n.left-ue)/xe),r=Math.floor((l-n.top-de)/ge);return a<0||a>=V||r<0||r>=T.length?null:{row:r,column:a}})(e.clientX,e.clientY)),onPointerLeave:()=>Q(null),onKeyDown:Me||"none"===be.mode?void 0:e=>{if("ArrowRight"===e.key)ve(0,1);else if("ArrowLeft"===e.key)ve(0,-1);else if("ArrowDown"===e.key)ve(1,0);else if("ArrowUp"===e.key)ve(-1,0);else{if("Escape"!==e.key)return;Q(null)}e.preventDefault()},onBlur:()=>Q(null)},tooltip:O&&we.length>0&&"none"!==be.mode?e(h,{heading:`${ee[O.row]} · ${le[O.column]}`,items:we,x:ue+(O.column+.5)*xe,y:de+(O.row+.5)*ge,flip:O.column>V/2,size:K}):null,legend:ke?l("div",{className:"mp-chart__legend flex items-center justify-center gap-2",children:[e("span",{className:"text-mp-on-surface-variant text-mp-label-small tabular-nums",children:Z(ne)}),e("span",{className:"flex","aria-hidden":"true",children:Array.from({length:p},(l,t)=>e("span",{className:"block h-3 w-6 first:rounded-s-mp-xs last:rounded-e-mp-xs",style:{background:v(t)}},t))}),e("span",{className:"text-mp-on-surface-variant text-mp-label-small tabular-nums",children:Z(ae)})]}):null,status:{heading:O?`${ee[O.row]} · ${le[O.column]}`:void 0,items:we},table:Me?null:e(c,{id:J,caption:D??X.table,corner:S?.label??X.category,categories:ee,names:le,values:je,format:Z,locale:U,empty:Y.empty}),children:Me?e("div",{className:"text-mp-on-surface-variant text-mp-body-small flex h-full items-center justify-center",children:E??Y.empty}):ie>0&&me>0?l("svg",{width:ie,height:me,viewBox:`0 0 ${ie} ${me}`,"aria-hidden":"true",className:"block overflow-visible",children:[e("g",{className:"mp-heatmap-chart__cells",children:T.map((t,n)=>Array.from({length:V},(a,r)=>{const o=t[r],i=O?.row===n&&O?.column===r,m=ue+r*xe,s=de+n*ge,c=Math.max(0,xe-d),h=Math.max(0,ge-d);if(!o||null===o.value)return e("rect",{x:m+d/2,y:s+d/2,width:c,height:h,fill:"none",stroke:"var(--_mp-color-outline-variant)",strokeWidth:1,strokeDasharray:"2 2",rx:2},r);const u=w((o.value-ne)/re);return l("g",{children:[e("rect",{x:m+d/2,y:s+d/2,width:c,height:h,fill:o.color??v(u),rx:2,stroke:i?"var(--_mp-color-on-surface)":"none",strokeWidth:i?2:0}),z&&c>b(Z(o.value),oe)+8&&h>oe+4?e("text",{x:m+xe/2,y:s+ge/2,textAnchor:"middle",dominantBaseline:"central",fill:y(u),fontSize:oe,children:Z(o.value)}):null]},r)}))}),S?.hidden?null:ee.map((l,t)=>e("text",{x:ue-8,y:de+(t+.5)*ge,textAnchor:"end",dominantBaseline:"central",fill:"var(--_mp-color-on-surface-variant)",fontSize:oe,children:M(l,ce-10,oe)},`r${t}`)),N?.hidden?null:le.map((l,t)=>e("text",{x:ue+(t+.5)*xe,y:de+pe+oe+4,textAnchor:"middle",fill:"var(--_mp-color-on-surface-variant)",fontSize:oe,children:M(l,xe-2,oe)},`c${t}`))]}):null})}

package/dist/components/heatmap-chart/index.d.ts

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

package/dist/components/heatmap-chart/index.js

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

package/dist/components/hover-card/MPHoverCard.d.ts

@@ -0,0 +1,101 @@
+import * as React from 'react';
+import type { MPAlign, MPDensity, MPSide, MPSize } from '../../types.js';
+/**
+ * The same axes an `MPPopover` takes, and for the same reasons.
+ *
+ * No `variant`, because the five weights answer "how much does this surface
+ * assert itself against the page" and a card that arrives uninvited has already
+ * been answered for. No `color`, because MD3's answer for a small sheet
+ * anchored to something is `surface-container`, neutral — and a card that could
+ * be dyed would dye whatever preview somebody put in it. No `elevation`,
+ * because a card floating over the page is the whole idea and a prop that could
+ * sit it flat would undo it.
+ */
+export interface MPHoverCardProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'color' | 'title' | 'children'> {
+    /**
+     * What the card hangs off. Exactly one element, which must accept a ref and
+     * spread props — every Material Plus component does.
+     *
+     * Usually an `MPTextLink` or an `MPAvatar`: the two things a reader wants to
+     * know more about without leaving the sentence they are in.
+     */
+    trigger: React.ReactElement;
+    /** The heading, rendered as the element that names the card. */
+    title?: React.ReactNode;
+    /** A line under it, and the card's accessible description. */
+    description?: React.ReactNode;
+    /** The body. */
+    children?: React.ReactNode;
+    /**
+     * Which edge of the trigger it appears on. Flips when there is no room.
+     * @default 'bottom'
+     */
+    side?: MPSide;
+    /** Where it sits along that edge. @default 'center' */
+    align?: MPAlign;
+    /** Distance from the trigger, in pixels. @default 8 */
+    sideOffset?: number;
+    /** Shift along that edge, in pixels. @default 0 */
+    alignOffset?: number;
+    /**
+     * Draws the wedge pointing at the trigger.
+     *
+     * Off by default, as on `MPPopover`: a sheet eight pixels from what opened it
+     * does not need to say what it belongs to.
+     * @default false
+     */
+    arrow?: boolean;
+    /** Whether the card is open. Use with `onOpenChange` for a controlled one. */
+    open?: boolean;
+    /** Whether it starts open, for an uncontrolled one. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * How long the pointer has to rest on the trigger before the card opens, in
+     * milliseconds. Base UI's own default is long enough that crossing a
+     * paragraph of links does not open four of them.
+     */
+    delay?: number;
+    /**
+     * How long the card stays after the pointer has left, in milliseconds. This
+     * is what makes the gap between the trigger and the card crossable.
+     */
+    closeDelay?: number;
+    /** A hard cap on the card's width, overriding the one `size` implies. */
+    width?: number | string;
+    /** The type scale and the room inside. @default 'md' */
+    size?: MPSize;
+    /** Takes room out of that padding, two pixels a face per step. @default 0 */
+    density?: MPDensity;
+}
+/** The wedge, at roughly a third of the sheet's corner per step. */
+/**
+ * A card that opens when the pointer rests on something, holding a preview of
+ * what is on the other side of it.
+ *
+ * ```tsx
+ * <MPHoverCard trigger={<MPTextLink href="/people/priya">Priya Raman</MPTextLink>} title="Priya Raman">
+ *   Platform team. Joined 2023.
+ * </MPHoverCard>
+ * ```
+ *
+ * ## Where it sits between the other two popups
+ *
+ * A tooltip is a **label**: one line, no interaction, and the pointer never
+ * reaches it. A popover is a panel that was **asked for** by a press, so it can
+ * hold a form. This one is uninvited like a tooltip and reachable like a
+ * popover — the pointer can cross into it, and a link inside it can be
+ * followed.
+ *
+ * ## Because it is uninvited, it is never the only way to anything
+ *
+ * A keyboard with no hover, a touchscreen with no pointer, and a screen reader
+ * all arrive by the trigger's own route instead. So whatever is in here has to
+ * exist on the page the trigger leads to as well. Treat it as a shortcut for
+ * the reader who has a pointer, never as the place a fact lives.
+ *
+ * That is also why there is no keyboard equivalent bolted on. A card that
+ * opened on focus would interrupt every keyboard reader tabbing through a
+ * paragraph of links, which is a worse answer than not opening at all.
+ */
+export declare function MPHoverCard({ trigger, title, description, children, side, align, sideOffset, alignOffset, arrow, open, defaultOpen, onOpenChange, delay, closeDelay, width, size: sizeProp, density: densityProp, className, style, ...props }: MPHoverCardProps): React.JSX.Element;

package/dist/components/hover-card/MPHoverCard.js

@@ -0,0 +1,2 @@
+"use client";
+import{jsx as e,jsxs as r}from"react/jsx-runtime";import*as i from"react";import{POPUP_ARROW_SIZE as a,POPUP_ARROW_TURN as l,PopupArrow as n}from"../../internal/PopupArrow.js";import{PreviewCard as o}from"@base-ui/react/preview-card";import{cssLength as s}from"../../internal/length.js";import{sheetPad as t}from"../../internal/density.js";import{hasContent as d,META_TEXT as m,PROSE_TEXT as c,SHEET_GAP as p,SHEET_TITLE as f}from"../../internal/scale.js";import{FADE as u,PORTAL_LAYER as x}from"../../internal/surface.js";import{useMPDensity as h,useMPSize as v}from"../../internal/config.js";const g={xs:"max-w-64",sm:"max-w-72",md:"max-w-96",lg:"max-w-md",xl:"max-w-xl"};export function MPHoverCard({trigger:w,title:j,description:y,children:b,side:N="bottom",align:O="center",sideOffset:P=8,alignOffset:_=0,arrow:$=!1,open:z,defaultOpen:C,onOpenChange:A,delay:D,closeDelay:B,width:H,size:I,density:M,className:R,style:T,...W}){const k=v(I),q=h(M),E=d(j)||d(y),F=a[k],G=i.useId(),J=`${G}-title`,K=`${G}-description`;return r(o.Root,{open:z,defaultOpen:C,onOpenChange:e=>A?.(e),children:[e(o.Trigger,{render:w,delay:D,closeDelay:B}),e(o.Portal,{children:e(o.Positioner,{className:x,side:N,align:O,sideOffset:P,alignOffset:_,children:r(o.Popup,{"data-mp-size":k,"aria-labelledby":d(j)?J:void 0,"aria-describedby":d(y)?K:void 0,className:["mp-hover-card rounded-mp-md relative flex flex-col outline-none","bg-mp-surface-container text-mp-on-surface shadow-mp-2","box-border",t(k,q),p[k],c[k],void 0===H?g[k]:"",u,R??""].filter(Boolean).join(" "),style:{...void 0===H?null:{maxWidth:s(H)},...T},...W,children:[$?e(o.Arrow,{className:l,children:e(n,{size:F,fill:"var(--_mp-color-surface-container)"})}):null,E?r("div",{className:"flex min-w-0 flex-col",children:[d(j)?e("div",{id:J,className:`mp-hover-card__title m-0 ${f[k]}`,children:j}):null,d(y)?e("div",{id:K,className:`mp-hover-card__description text-mp-on-surface-variant m-0 ${m}`,children:y}):null]}):null,d(b)?e("div",{className:"min-w-0",children:b}):null]})})})]})}

package/dist/components/hover-card/index.d.ts

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

package/dist/components/hover-card/index.js

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

package/dist/components/icon/MPIcon.js

@@ -1,2 +1,2 @@
 "use client";
-import{jsx as e}from"react/jsx-runtime";import*as i from"react";function o(e){return!i.isValidElement(e)}export const MPIcon=/*@__PURE__*/i.forwardRef(function({icon:r,size:t,color:l,strokeWidth:n,center:s=!1,label:c,className:a,style:d,...f},m){const u=["mp-icon inline-flex shrink-0 items-center justify-center align-middle",void 0===t?"":"[&>svg]:block [&>svg]:size-full [&>img]:block [&>img]:size-full",s?"justify-self-center":"",a??""].filter(Boolean).join(" ");return e("span",{ref:m,className:u,style:{...void 0===t?{}:{width:t,height:t,fontSize:t},...void 0===l?{}:{color:l},...d},role:c?"img":void 0,"aria-label":c,"aria-hidden":!c||void 0,...f,children:o(r)?i.createElement(r,{size:t,color:void 0===l?"currentColor":l,strokeWidth:n}):r})});
+import{jsx as e}from"react/jsx-runtime";import*as i from"react";function o(e){return!i.isValidElement(e)}export const MPIcon=/*@__PURE__*/i.forwardRef(function({icon:r,size:t,color:n,strokeWidth:l,center:s=!1,label:c,className:a,style:d,...m},f){const h=["mp-icon inline-flex shrink-0 items-center justify-center align-middle","[&>svg]:shrink-0 [&>img]:shrink-0",void 0===t?"":"[&>svg]:block [&>svg]:size-full [&>img]:block [&>img]:size-full",s?"justify-self-center":"",a??""].filter(Boolean).join(" ");return e("span",{ref:f,className:h,style:{...void 0===t?{}:{width:t,height:t,fontSize:t},...void 0===n?{}:{color:n},...d},role:c?"img":void 0,"aria-label":c,"aria-hidden":!c||void 0,...m,children:o(r)?i.createElement(r,{size:t,color:void 0===n?"currentColor":n,strokeWidth:l}):r})});

package/dist/components/image/MPImage.d.ts

@@ -1,9 +1,35 @@
 import * as React from 'react';
 import type { MPSize } from '../../types.js';
-/** How the picture is fitted into the box it was given. CSS's own four. */
-export type MPImageFit = 'cover' | 'contain' | 'fill' | 'none';
+/** How the picture is fitted into the box it was given. CSS's own words. */
+export type MPImageFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
 /** What the picture is doing right now. */
 export type MPImageState = 'loading' | 'loaded' | 'error';
+/** A picture that stands in while the real one arrives. */
+export interface MPImagePlaceholder {
+    /**
+     * A URL, a data URI, or a `Blob` such as a file the reader has just picked.
+     *
+     * A `Blob` is drawn through an object URL made for it, so keep the same Blob
+     * from one render to the next: a new one on every render makes a new URL on
+     * every render, and each of those renders again.
+     */
+    src: string | Blob;
+    /**
+     * Blurs the stand-in. `true` is a 20px radius, and a number is a radius in
+     * pixels.
+     * @default false
+     */
+    blur?: boolean | number;
+}
+/** A turn in degrees, clockwise, a quarter at a time. */
+export type MPImageRotate = 0 | 90 | 180 | 270;
+/** Which way the picture is mirrored, along the axes it is shown on. */
+export type MPImageFlip = 'none' | 'horizontal' | 'vertical' | 'both';
+/**
+ * The part of the picture a crop keeps, in `object-position`'s words: the
+ * centre, a side, a corner, or two percentages across and down.
+ */
+export type MPImagePosition = 'center' | 'top' | 'right' | 'bottom' | 'left' | 'top left' | 'top right' | 'bottom left' | 'bottom right' | `${number}% ${number}%`;
 export interface MPImageProps extends Omit<React.ComponentPropsWithoutRef<'img'>, 'onError'> {
     /** Where the picture is. */
     src?: string;
@@ -26,18 +52,44 @@ export interface MPImageProps extends Omit<React.ComponentPropsWithoutRef<'img'>
      */
     ratio?: number | string;
     /**
-     * How the picture is fitted into that box.
+     * How the picture is fitted into that box. `scale-down` is `contain` that
+     * never enlarges a file smaller than the box.
      * @default 'cover'
      */
     fit?: MPImageFit;
+    /**
+     * The width of the file, or of the box when it is given without `height`.
+     *
+     * With `height` as well, the two are the file's size in pixels, as on an
+     * `<img>`, and they reserve its proportion. Alone, it makes the box that wide,
+     * no wider than its container, and as tall as the picture or `ratio` makes
+     * it. A number or a string of digits is pixels, and any other string is a CSS
+     * length.
+     */
+    width?: number | string;
+    /**
+     * The height of the file, or of the box when it is given without `width`.
+     *
+     * With `width` as well, the two are the file's size in pixels. Alone, it makes
+     * the box that tall and as wide as its container, or as wide as `ratio` makes
+     * it when there is one. A number or a string of digits is pixels, and any
+     * other string is a CSS length.
+     */
+    height?: number | string;
     /**
      * Drawn while the picture is on its way.
      *
      * A shimmer by default, on the surface the box sits on. `false` draws nothing,
      * which is what a picture inside something that already has its own loading
      * treatment wants.
+     *
+     * `{ src, blur }` draws a picture instead: a small copy of the file, a data
+     * URI or a `Blob`, fitted, placed, turned and mirrored like the picture, and
+     * blurred if `blur` says so. It gives way once the picture has faded in over
+     * it. Like the shimmer, it fills the box, so the box needs a reserved size: a
+     * `ratio`, or both `width` and `height`.
      */
-    placeholder?: React.ReactNode | false;
+    placeholder?: React.ReactNode | false | MPImagePlaceholder;
     /**
      * Drawn instead of the picture when it does not arrive.
      *
@@ -64,8 +116,73 @@ export interface MPImageProps extends Omit<React.ComponentPropsWithoutRef<'img'>
     previewSrc?: string;
     /** The label on the button `preview` turns the box into. */
     previewLabel?: string;
-    /** Called when the state changes, for a caller that wants to know. */
+    /**
+     * Called when the state changes, for a caller that wants to know.
+     *
+     * **This is the signal to use, not `onLoad`.** `onLoad` is the `<img>`'s own
+     * event and is passed straight through, so it does not fire for a picture the
+     * browser already has: the load has been and gone before React attached
+     * anything, which is the whole reason this component exists. `onStateChange`
+     * is reported from the `complete` check as well as from the event, so it
+     * arrives either way.
+     */
     onStateChange?: (state: MPImageState) => void;
+    /**
+     * Turns the picture clockwise, in quarter turns.
+     *
+     * Only quarters, because a picture turned by any other angle stops covering
+     * its box, and filling the corners would mean enlarging it by an amount the
+     * caller would then want to tune. A quarter turn swaps the box's proportion:
+     * `width` and `height`, when both are given, are read as the file's size and
+     * reserve the turned shape, and without them the shape is read from the file
+     * once it arrives. An explicit `ratio` is the layout's shape and is kept.
+     *
+     * Drawn with the `rotate` property rather than `transform`, so a `transform`
+     * of your own, such as a hover zoom, still applies on top.
+     * @default 0
+     */
+    rotate?: MPImageRotate;
+    /**
+     * Mirrors the picture along the axes it is shown on.
+     *
+     * `horizontal` swaps left and right on the screen whether or not the picture
+     * is turned. Drawn with the `scale` property, so it leaves `transform` free as
+     * `rotate` does, and `preview` opens the picture mirrored.
+     * @default 'none'
+     */
+    flip?: MPImageFlip;
+    /**
+     * Which part of the picture a `cover` crop keeps, and where `contain`, `none`
+     * and `scale-down` leave their empty space.
+     *
+     * Read on the picture as it is shown, so `top` keeps the top of a picture
+     * that has been turned or mirrored. Physical rather than logical: the subject
+     * of a photograph does not move to the other side on a right-to-left page. A
+     * value in any other form reaches `object-position` as written.
+     * @default 'center'
+     */
+    position?: MPImagePosition;
+    /**
+     * What fills the room `fit` leaves around the picture.
+     *
+     * `blur` draws the same picture behind itself, covering the box and blurred,
+     * the way a video player fills the sides of a portrait clip. It reuses the
+     * picture's request, and it is drawn only for a `fit` that can leave room:
+     * `contain`, `none` and `scale-down`. Any other string is a CSS `background`
+     * painted behind the picture: a colour, a custom property or a gradient.
+     * @default 'none'
+     */
+    letterbox?: 'none' | 'blur' | (string & {});
+    /**
+     * Loads this picture first: the one a page is judged by, which is usually its
+     * Largest Contentful Paint.
+     *
+     * Sets `loading="eager"` and a high fetch priority. A `loading` or
+     * `fetchPriority` of your own still wins. Give it to one picture per page: a
+     * high priority on every picture raises none of them above the others.
+     * @default false
+     */
+    priority?: boolean;
     /** The corner and type scale of the placeholder and the fallback. @default 'md' */
     size?: MPSize;
 }