material-plus-ui 1.8.0 → 1.10.0

package/dist/tailwind.css

@@ -95,6 +95,27 @@
  * Only the *derived* colours need it. Everything else here is a literal value
  * with no `var()` to freeze, so plain inheritance from `:root` is enough.
  *
+ * ## Why `*` and `::backdrop`, but not `::before` and `::after`
+ *
+ * The rule reaches every element of the page it is loaded into, not only the
+ * ones this library rendered, so what it costs per element is a cost to the
+ * whole page. A `::before` or `::after` in the selector multiplies it: a
+ * browser has to resolve both pseudo-elements of every element on the page to
+ * find out whether either one draws anything, and resolving each one means
+ * substituting all of the roles below again.
+ *
+ * Neither needs its own copy. A `::before` and an `::after` inherit from the
+ * element they belong to, which already holds the roles as resolved where it
+ * sits, and nothing sets a source colour, a tone stop or a role on a
+ * pseudo-element — so the copy they would compute is the copy they inherit.
+ * `::placeholder` and `::marker` have always been read this way. `::backdrop`
+ * stays, because before 2024 it inherited from nothing at all.
+ *
+ * Measured on a plain page of 1,430 elements with nothing of this library on
+ * it, the first style pass took 164ms in WebKit with the pseudo-elements in the
+ * selector and 21ms without them, against 9ms with no stylesheet at all;
+ * Firefox went from 68ms to 26ms. iOS runs every browser on WebKit.
+ *
  * The computed results are `--_mp-*`: private, read by the components, and not
  * a name to set. Material Web marks its own internal tokens the same way. The
  * indirection is load-bearing — it is what keeps a consumer's
@@ -530,8 +551,6 @@
    * passes the edge by less than 4% of one channel.
    */
   *,
-  ::before,
-  ::after,
   ::backdrop {
     /*
      * The grey each accent tone sits on, in linear light: an OKLCh lightness
@@ -2045,8 +2064,6 @@
     }
 
     *,
-    ::before,
-    ::after,
     ::backdrop {
       --_mp-color-primary: var(
         --mp-sys-color-primary,
@@ -3849,6 +3866,21 @@
   }
 }
 
+/*
+ * And the same for a page read without JavaScript.
+ *
+ * An entrance waiting for `trigger="visible"`, `manual` or `hover` sits paused
+ * on its first frame until script starts it, and with no script that is
+ * forever: the content was in the markup and drawn at `opacity: 0`, invisible
+ * to the reader and present for nobody but a crawler. With scripting off the
+ * entrance is dropped and the content shown, which is what it was carrying.
+ */
+@media (scripting: none) {
+  .mp-anim {
+    animation: none;
+  }
+}
+
 /*
  * Lighting: a light travelling around the outside of something.
  *
@@ -3917,6 +3949,23 @@
   }
 }
 
+/*
+ * The endless loops, held while they are off screen.
+ *
+ * `data-mp-offscreen` is written by the component while its element is out of
+ * the viewport. A loop nobody can see is still one the browser runs — a style
+ * pass a frame for the glow's angle, and a layout pass a frame for the linear
+ * indicator, whose bars move by `inset`. Paused, each carries on from where it
+ * stopped when it comes back, which for a loop is no difference at all.
+ */
+.mp-anim-lighting[data-mp-offscreen]::before,
+.mp-progress-linear[data-mp-offscreen] .mp-progress-linear-lead,
+.mp-progress-linear[data-mp-offscreen] .mp-progress-linear-trail,
+.mp-progress-circular[data-mp-offscreen] .mp-progress-circular-turn,
+.mp-progress-circular[data-mp-offscreen] .mp-progress-circular-arc {
+  animation-play-state: paused;
+}
+
 /*
  * Marquee: two identical copies, both moving by exactly one copy plus the gap.
  *
@@ -4469,3 +4518,66 @@
   inline-size: calc(var(--_mp-tree-indent) / 2 - 2px);
   border-block-start: 1px solid var(--_mp-color-outline-variant);
 }
+
+/* ---------------------------------------------------------------------------
+ * A fixed header's room, before the layout has measured it
+ *
+ * `MPPageLayout` keeps a fixed `MPHeader` from covering the top of the page by
+ * measuring the bar and padding the page by its height. The measurement is an
+ * effect, so on a server-rendered page the content was drawn under the bar and
+ * then pushed down by its height once the page had hydrated — a layout shift
+ * of a whole header's worth, on every page with one.
+ *
+ * These give the padding a first answer that needs no script: a fixed bar's
+ * height is its size's rung on the ladder, plus a pixel for the rule an
+ * `outlined` one draws under itself. The measurement still wins the moment it
+ * arrives, and it then moves nothing unless the bar's content made it taller
+ * than its rung. Only a bar that is the layout's own header is counted — the
+ * slot it sits in when the header spans the page, or the content column's when
+ * it does not — so a layout nested inside another does not answer for it.
+ *
+ * In a browser without `:has()` there is no first answer, which is how every
+ * browser behaved before.
+ * ------------------------------------------------------------------------- */
+
+.mp-page-layout:is(
+  :has(> .mp-header[data-mp-position='fixed'][data-mp-variant='outlined']),
+  :has(> div > div > .mp-header[data-mp-position='fixed'][data-mp-variant='outlined'])
+) {
+  --_mp-layout-header-rule: 1px;
+}
+
+.mp-page-layout:is(
+  :has(> .mp-header[data-mp-position='fixed'][data-mp-size='xs']),
+  :has(> div > div > .mp-header[data-mp-position='fixed'][data-mp-size='xs'])
+) {
+  --_mp-layout-header-seed: calc(3rem + var(--_mp-layout-header-rule, 0px));
+}
+
+.mp-page-layout:is(
+  :has(> .mp-header[data-mp-position='fixed'][data-mp-size='sm']),
+  :has(> div > div > .mp-header[data-mp-position='fixed'][data-mp-size='sm'])
+) {
+  --_mp-layout-header-seed: calc(3.5rem + var(--_mp-layout-header-rule, 0px));
+}
+
+.mp-page-layout:is(
+  :has(> .mp-header[data-mp-position='fixed'][data-mp-size='md']),
+  :has(> div > div > .mp-header[data-mp-position='fixed'][data-mp-size='md'])
+) {
+  --_mp-layout-header-seed: calc(4rem + var(--_mp-layout-header-rule, 0px));
+}
+
+.mp-page-layout:is(
+  :has(> .mp-header[data-mp-position='fixed'][data-mp-size='lg']),
+  :has(> div > div > .mp-header[data-mp-position='fixed'][data-mp-size='lg'])
+) {
+  --_mp-layout-header-seed: calc(5rem + var(--_mp-layout-header-rule, 0px));
+}
+
+.mp-page-layout:is(
+  :has(> .mp-header[data-mp-position='fixed'][data-mp-size='xl']),
+  :has(> div > div > .mp-header[data-mp-position='fixed'][data-mp-size='xl'])
+) {
+  --_mp-layout-header-seed: calc(6rem + var(--_mp-layout-header-rule, 0px));
+}

package/dist/types.d.ts

@@ -309,8 +309,70 @@ export interface MPTimelineSeries {
     /** Overrides the palette slot this row would otherwise take. */
     color?: MPColor | (string & {});
 }
+/**
+ * How the series of a stacking chart are piled up.
+ *
+ * - `false` — side by side, or overlapping. The parts are compared with each
+ *   other.
+ * - `true` — on each other, so the far edge is the total. The totals are
+ *   compared and the parts make them up.
+ * - `'percent'` — on each other and normalised, so every column is full. The
+ *   **composition** is compared and the totals are gone from the picture.
+ *
+ * A percent stack answers "what is this made of" and refuses to answer "how
+ * much of it is there", which is the trade it makes and the reason it is a
+ * third setting rather than a flag on the second. Two columns of wildly
+ * different size are drawn identically, so the total belongs somewhere else on
+ * the page — a figure beside the chart, or a second chart.
+ *
+ * A negative has no share of a whole, so a percent stack leaves it out the way
+ * `MPPieChart` does. The table behind the chart still has the number.
+ */
+export type MPChartStack = boolean | 'percent';
 /** How a line gets from one point to the next. */
 export type MPChartCurve = 'linear' | 'smooth' | 'step';
+/**
+ * What a line or an area does where a series has no value.
+ *
+ * - `break` — the line stops and starts again on the far side. The default,
+ *   because a straight run through values nobody has is the one kind of
+ *   invented data a reader never questions: it looks exactly like the rest of
+ *   the line.
+ * - `connect` — the two sides are joined, and the joining run is drawn
+ *   **dashed** so the picture still says which part of it was measured. An
+ *   area's fill closes across the gap as well.
+ * - `zero` — the missing reading is drawn at zero, and the value axis is
+ *   widened to hold it. Right where a gap really does mean "none of it
+ *   happened", and wrong where it means "nobody was counting".
+ *
+ * Only the drawing changes. The hover panel and the table behind the chart
+ * still report a gap as a gap, whichever of the three is chosen, because they
+ * are the copy of the data a reader gets when they need the number itself.
+ */
+export type MPChartGaps = 'break' | 'connect' | 'zero';
+/**
+ * What an axis does with a tick label too wide for the room it has.
+ *
+ * - `auto` — leaves the labels flat while they fit and turns them when they do
+ *   not. The default, because flat labels are what a reader takes in fastest
+ *   and a name cut to "Onbo…" has lost the thing it was there to say.
+ * - `truncate` — cuts a long label with an ellipsis and never turns anything.
+ * - `rotate` — turns every label 45°.
+ * - `vertical` — stands every label on end.
+ *
+ * The last two turn **all** of the labels rather than only the long ones: a row
+ * at two different angles is a row a reader has to scan twice.
+ *
+ * Only the axis along the **bottom** reads it. Labels stacked up the side
+ * already have a row each, which is the room a turn would be buying them.
+ *
+ * And `auto` turns names rather than ticks. A value axis is a ruler, so showing
+ * every nth of its labels loses nothing a reader cannot interpolate; where the
+ * bottom of a chart is one — a bar chart on its side, a scatter — `auto` leaves
+ * it striding. `rotate` and `vertical` still apply there when they are asked
+ * for by name.
+ */
+export type MPChartTickLabels = 'auto' | 'truncate' | 'rotate' | 'vertical';
 /**
  * Which values are written onto the marks themselves.
  *
@@ -320,6 +382,20 @@ export type MPChartCurve = 'linear' | 'smooth' | 'step';
  * `all` is there for the eight-bar chart where it genuinely is the answer.
  */
 export type MPChartValueLabels = 'none' | 'last' | 'extremes' | 'all';
+/**
+ * What ink a chart writes the text naming a series in.
+ *
+ * `'ink'` is `on-surface-variant` — one colour for every name, whichever mark
+ * it belongs to. `'series'` matches the name to its mark, which pairs a long
+ * legend with a crowded plot faster than a swatch alone can.
+ *
+ * The trade is contrast. The eight palette slots are fitted to 3:1 against the
+ * surface, which is the bar a **mark** has to clear; small text is held to
+ * 4.5:1, and a series colour does not reach it. So the swatch carries the
+ * colour by default and the word stays legible, and this is the caller saying
+ * their chart is better off the other way round.
+ */
+export type MPChartLabelColor = 'ink' | 'series';
 /**
  * What the pointer uncovers.
  *
@@ -348,13 +424,42 @@ export interface MPChartTooltipItem {
 export interface MPChartTooltipContext {
     index: number;
     category: MPChartCategory;
-    /** Only the series that are visible and have a value here. */
+    /** Only the series that are visible and have a value here, in `sort`'s order. */
     items: readonly MPChartTooltipItem[];
+    /** What they add up to, where the chart is a picture of that sum. */
+    total?: string;
 }
+/**
+ * What order the rows of a hover panel come in.
+ *
+ * - `series` — the order they were passed, which is the order the legend lists
+ *   them in and the order the colours were handed out in. A reader who has
+ *   learned the legend can find a row without reading it.
+ * - `value` — largest first. What a chart of eight series wants: the row a
+ *   reader is looking for is usually the big one, and hunting for it down a
+ *   list in a fixed order is the work the panel exists to save.
+ *
+ * Neither is right for every chart, which is why there is a prop. Ties keep
+ * their series order, so a panel never reorders itself over nothing.
+ */
+export type MPChartTooltipSort = 'series' | 'value';
 /** The hover layer, where `true` and `false` are not enough. */
 export interface MPChartTooltip {
     /** @default 'index', or 'item' where the marks are not arranged in columns */
     mode?: MPChartTooltipMode;
+    /** @default 'series' */
+    sort?: MPChartTooltipSort;
+    /**
+     * Adds a row for what the column adds up to.
+     *
+     * On by default where the chart **is** that total — a stack, whose whole
+     * point is the height of the column — and off everywhere else. A percent
+     * stack is left out of that: its total is 100% at every category, and a row
+     * that says the same thing four times is a row nobody reads. An unstacked
+     * chart is off because its series are not parts of anything, and adding them
+     * up would be the panel inventing a quantity.
+     */
+    total?: boolean;
     /**
      * The line dropped through the plot at the active category. On in `index`
      * mode and never drawn in `item` mode: a crosshair says "these numbers all
@@ -402,12 +507,114 @@ export interface MPChartAxis {
     tickCount?: number;
     /** How a tick is written, overriding the chart's own `format`. */
     tickFormat?: (value: MPChartCategory, index: number) => React.ReactNode;
+    /**
+     * What to do with a label too wide for the room it has: cut it, or turn it.
+     *
+     * Read by the axis along the **bottom** only — the category axis on an
+     * upright chart, and the value axis on one turned on its side. Labels down
+     * the left already have a row each.
+     * @default 'auto'
+     */
+    tickLabels?: MPChartTickLabels;
     /**
      * How much room it keeps for its ticks and its label, in pixels. Measured off
      * the ticks themselves otherwise. Set it when a long category name needs
      * more, or when two charts stacked on a dashboard have to line their plots up.
      */
     thickness?: number;
+    /**
+     * Lines and bands drawn across the plot at places on **this** axis' scale — a
+     * target, a threshold, the range a reading should stay inside.
+     *
+     * The scale is widened to hold them, because a target the plot is cropped
+     * above is a target nobody can see. Pin `min` or `max` to stop that.
+     *
+     * Read by an axis that has a scale: the value axis always, and the category
+     * axis where it runs on numbers rather than on names. A row of categories has
+     * no place between two of them for a line to be at.
+     */
+    references?: readonly MPChartReference[];
+}
+/**
+ * A line drawn across the plot at a place on one of its scales, or a band where
+ * it has two ends.
+ *
+ * A target, a service level, the day a release went out, the range a reading is
+ * meant to stay inside. It is **not** data: it is a fact the reader brought
+ * with them, so it is drawn in the chrome's ink rather than out of the series
+ * palette, and a chart is never asked to invent one.
+ *
+ * The axis it is given to is the scale its `value` is on, which is also the
+ * axis it is drawn perpendicular to — a reference on the value axis of an
+ * upright chart is a horizontal line, and the same reference on a chart turned
+ * on its side is a vertical one.
+ */
+export interface MPChartReference {
+    /**
+     * Where it sits, on that axis' own scale. A `Date` on an axis of dates, which
+     * is the one place a reference is most often asked for — today, a release, a
+     * deadline.
+     */
+    value: number | Date;
+    /**
+     * And where it ends, which makes it a **band** rather than a line: the range
+     * a reading should stay inside, the window something was down for.
+     */
+    to?: number | Date;
+    /**
+     * What it is called, written at its own end of the line and read out with the
+     * chart. A line nobody can name is a line nobody can use.
+     */
+    label?: React.ReactNode;
+    /**
+     * Which family it wears. An `MPColor`, or any CSS colour.
+     *
+     * The outline role by default, which is what keeps a reference reading as
+     * chrome rather than as another series. `error` is the one worth reaching
+     * for: a threshold somebody is watching is exactly what that role is for.
+     */
+    color?: MPColor | (string & {});
+    /**
+     * Draws it dashed, so it cannot be mistaken for a gridline or a baseline.
+     * @default true
+     */
+    dashed?: boolean;
+}
+/**
+ * Dragging a range out of a long category axis.
+ *
+ * What it is for is the chart with ninety points on it, where the shape of one
+ * week is inside a picture of a quarter. A reader drags across the plot, the
+ * chart redraws to what they picked, and the scale re-fits to it — so the
+ * window is a *chart of that range* rather than a magnified picture of the
+ * whole one.
+ *
+ * Everything follows the window: the value scale, the hover panel, the spoken
+ * readout and the table behind the picture. The table is what a reader who
+ * cannot see the plot is given **instead** of it, so a table still listing
+ * ninety points would be describing a chart that is not on the page.
+ *
+ * Only a chart whose categories are a row of slots takes it. A scatter has two
+ * value axes and no row to cut, and a pie has no axis at all.
+ */
+export interface MPChartZoom {
+    /**
+     * The range drawn, as a first and last **category index**, or `null` for all
+     * of them. Use with `onRangeChange` for a controlled window.
+     */
+    range?: readonly [number, number] | null;
+    /** Where the window starts out. Ignored once `range` is given. */
+    defaultRange?: readonly [number, number] | null;
+    /** Called with what the reader dragged, and with `null` when they reset it. */
+    onRangeChange?: (range: readonly [number, number] | null) => void;
+    /**
+     * The fewest categories a drag may leave.
+     *
+     * Two, because a window of one category is not a chart of anything — there is
+     * no distance left in it for a line to have travelled.
+     * @default 2
+     */
+    min?: number;
 }
 /** Where the legend sits, and what it does when it is used. */
 export interface MPChartLegend {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "material-plus-ui",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "A React component library written from the Material Design 3 specification and extended past it — wider versions of the components it names, and the charts, data table and command palette it does not. Built on Base UI and Tailwind CSS v4, themed with CSS custom properties so it coexists with an existing Material setup. ESM only, types included.",
   "type": "module",
   "sideEffects": [
@@ -18,7 +18,7 @@
     "url": "https://github.com/jooy2/material-plus-ui/issues"
   },
   "scripts": {
-    "build": "npm run format:fix && node scripts/clean-dist.mjs && tsc --project tsconfig.prod.json && node scripts/specify-imports.mjs && node scripts/annotate-pure.mjs && npm run minify && node scripts/mark-client.mjs && node scripts/build-styles.mjs && node scripts/build-split-styles.mjs && node scripts/measure-bundle.mjs",
+    "build": "npm run format:fix && node scripts/clean-dist.mjs && tsc --project tsconfig.prod.json && node scripts/specify-imports.mjs && node scripts/annotate-pure.mjs && npm run minify && node scripts/mark-client.mjs && node scripts/build-styles.mjs && node scripts/build-split-styles.mjs && node scripts/build-a2ui-catalog.mjs && node scripts/measure-bundle.mjs",
     "lint": "eslint . --ext .js,.ts .",
     "lint:fix": "eslint . --ext .js,.ts --fix .",
     "minify": "terser-glob 'dist/**/*.js' --config-file terser.config.json",
@@ -59,6 +59,11 @@
       "module": "./dist/hooks/index.js",
       "default": "./dist/hooks/index.js"
     },
+    "./a2ui": {
+      "types": "./dist/a2ui/index.d.ts",
+      "module": "./dist/a2ui/index.js",
+      "default": "./dist/a2ui/index.js"
+    },
     "./components/*": {
       "types": "./dist/components/*/index.d.ts",
       "module": "./dist/components/*/index.js",
@@ -124,6 +129,8 @@
     "composition"
   ],
   "devDependencies": {
+    "@a2ui/react": "^0.11.1",
+    "@a2ui/web_core": "^0.11.0",
     "@base-ui/react": "^1.8.0",
     "@eslint/js": "^9.39.1",
     "@tailwindcss/postcss": "^4.3.3",
@@ -156,21 +163,35 @@
     "vitepress-i18n": "^1.4.0",
     "vitepress-sidebar": "^1.40.0",
     "vitest": "^5.0.1",
-    "vitest-browser-react": "^2.3.0"
+    "vitest-browser-react": "^2.3.0",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.25.2"
   },
   "dependencies": {
     "highlight.js": "^11.12.0",
     "lucide-react": "^1.47.0"
   },
   "peerDependencies": {
+    "@a2ui/react": "^0.11.0",
+    "@a2ui/web_core": "^0.11.0",
     "@base-ui/react": "^1.7.0",
     "@types/react": "^18.0.0 || ^19.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "zod": "^3.25.76"
   },
   "peerDependenciesMeta": {
+    "@a2ui/react": {
+      "optional": true
+    },
+    "@a2ui/web_core": {
+      "optional": true
+    },
     "@types/react": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   }
 }