material-plus-ui 1.6.0 → 1.8.0

package/dist/internal/chart.d.ts

@@ -0,0 +1,461 @@
+import type * as React from 'react';
+import type { MPChartCategory, MPChartCurve, MPChartDatum, MPChartSeries, MPSize } from '../types.js';
+/**
+ * The arithmetic and the vocabulary the charts share.
+ *
+ * Nothing in here draws anything and nothing in here is a class name. It is the
+ * palette a series is handed, the numbers a value is written as, and — as the
+ * plotted charts arrive — the scales and the ticks under them. Kept apart for
+ * the reason `internal/data-table.ts` is: a component whose interesting fifty
+ * lines are buried in machinery is a component nobody can read.
+ */
+/**
+ * How many colours a chart can hand out before it starts repeating.
+ *
+ * Eight, and a chart that reaches the ninth should not have: a ninth hue is
+ * indistinguishable from one of the first eight under colour-vision deficiency
+ * whichever one is chosen. Fold the tail into one "other" series, or draw a
+ * second chart.
+ */
+export declare const CHART_SLOTS = 8;
+/**
+ * What colour a mark is, in the fixed order the palette is handed out in.
+ *
+ * `index` is the series' place in the array it was passed in, **not** its place
+ * among the ones currently visible. That is the whole point: filtering a legend
+ * must not repaint the survivors, because a reader who learned that Europe is
+ * blue has learned something a re-render is not allowed to take back.
+ *
+ * A series that names its own colour gets it. An `MPColor` resolves to that
+ * accent role; anything else is passed through as CSS, so a brand hex or a
+ * custom property of the caller's both work.
+ */
+export declare function seriesColor(index: number, explicit?: string): string;
+/** Where a figure stops being read and starts being counted. */
+export declare const COMPACT_FROM = 10000;
+/**
+ * A number as the reader should see it, compacted once it stops being readable
+ * in full.
+ *
+ * Four digits stay and five do not. `1,284` is a figure anybody takes in at a
+ * glance, and `1.3K` has thrown away two of them to save two characters; at
+ * `12,900` the digits have stopped being read and started being counted, so
+ * `12.9K` loses nothing. Past that it is the only honest picture: nobody
+ * compares `1,284,003` with `1,911,220` by reading them, and `1.3M` against
+ * `1.9M` is what they were going to conclude anyway.
+ *
+ * `format` overrides all of it, because a caller who has said
+ * `{ style: 'currency', currency: 'USD' }` has said what they want and a
+ * component that compacted it anyway would be arguing.
+ */
+export declare function formatStatistic(value: number, locale: string | undefined, format: Intl.NumberFormatOptions | undefined, compact: boolean): string;
+/** Which way a figure has moved, and whether that is the good direction. */
+export interface MPStatisticDelta {
+    /** The change, in the value's own units. */
+    absolute: number;
+    /** And as a share of where it started. `null` when it started at nothing. */
+    percent: number | null;
+    /** `0` when it has not moved at all, which is a third state rather than "up". */
+    direction: -1 | 0 | 1;
+    /** Whether the direction is the one the caller says is good. */
+    good: boolean;
+}
+/**
+ * The move from one figure to another.
+ *
+ * A percentage of zero is `null` rather than `Infinity` or `100%`. Something
+ * that was nothing and is now something has not grown by an amount — it has
+ * started — and every one of the numbers that could be printed there is a lie a
+ * reader would take at face value.
+ */
+export declare function deltaOf(value: number, previous: number, betterWhen: 'up' | 'down'): MPStatisticDelta;
+/**
+ * A point in **plot pixels**, or `null` where the series has a gap.
+ *
+ * Deliberately not `MPChartPoint`, which is the caller's datum. Everything past
+ * this line works in pixels: a builder that could still see a value would be a
+ * builder that has to know which way round the axes are.
+ */
+export type PlotPoint = {
+    x: number;
+    y: number;
+} | null;
+/**
+ * A series as one `d`, broken wherever it has a gap.
+ *
+ * The break is the point. A `null` is a month nothing was measured in, and a
+ * path that joined the two sides of it would draw a straight line through a
+ * value nobody has — which is the one thing a reader would never guess was
+ * invented, because it looks exactly like data.
+ */
+export declare function linePath(points: readonly PlotPoint[], curve: MPChartCurve): string;
+/**
+ * The ribbon between two runs of points.
+ *
+ * Built run by run, so a gap is a gap in the fill as well — and a gap in
+ * *either* edge is a gap in the band, because a ribbon with only one side is
+ * not a shape. An area that closed across a missing month would fill in a value
+ * that was never measured: the same lie the bridged line tells, painted over a
+ * larger part of the chart.
+ *
+ * The underside is drawn with the **same** curve and its opening `M` turned
+ * into an `L`. Both halves matter: a smoothed top over a straight bottom
+ * disagrees with itself about where the band is between two points, and a
+ * second `moveto` inside the path lifts the pen and leaves the fill with no
+ * side.
+ */
+export declare function bandPath(top: readonly PlotPoint[], bottom: readonly PlotPoint[], curve: MPChartCurve): string;
+/**
+ * The same path closed down to a flat baseline, for an area standing on the
+ * axis rather than on another band.
+ */
+export declare function areaPath(points: readonly PlotPoint[], baseline: number, curve: MPChartCurve): string;
+/**
+ * Which edge of a bar is its data end — the one the value is at.
+ *
+ * `none` is the inner segment of a stack, whose two faces are both boundaries
+ * between shares rather than the end of anything, and so are both left square.
+ *
+ * `both` is a **span**: a stretch with two ends, neither of which is more the
+ * value than the other. A bar grows from a baseline and has one data end; a
+ * timeline's bar has no baseline at all.
+ */
+export type BarEnd = 'top' | 'bottom' | 'left' | 'right' | 'none' | 'both';
+/**
+ * A rectangle with the two corners at its **data end** cut off.
+ *
+ * Rounded at the end and square at the baseline, and that is not a stylistic
+ * split. A bar rounded where it meets the axis has lost the exact point it
+ * starts from, and a row of them turns the baseline into a scalloped edge. The
+ * end is where the value is, and that is the end worth softening.
+ *
+ * Which end that is comes from the caller rather than from the geometry,
+ * because it is the *sign* and the orientation together that decide: a negative
+ * bar hangs below the axis and a horizontal one grows sideways, and in both the
+ * corners to soften are the ones furthest from zero.
+ *
+ * The radius shrinks to fit rather than clipping, so a bar two pixels tall is a
+ * bar and not a dome.
+ */
+export declare function barPath(x: number, y: number, width: number, height: number, radius: number, end: BarEnd): string;
+/** The lowest and highest a series reaches, with the caller's overrides applied. */
+export declare function extentOf(values: readonly (number | null)[], min?: number, max?: number): {
+    min: number;
+    max: number;
+};
+/**
+ * The lowest and highest a set of series reaches.
+ *
+ * Stacked is a different question rather than a variation on the same one: what
+ * a stacked chart's axis has to hold is the tallest *column*, and the tallest
+ * column is not made of the largest values. Positives and negatives accumulate
+ * separately, because a column of +8 and −3 is eleven units tall and reaches
+ * from −3 to 8, not from 0 to 5.
+ *
+ * `null` when nothing was measured at all, which is a different answer from
+ * `{ min: 0, max: 0 }` — one is an empty chart and the other is a chart of
+ * zeroes.
+ */
+export declare function seriesExtent(values: readonly (readonly ChartValue[])[], stacked: boolean): {
+    min: number;
+    max: number;
+} | null;
+/** A value axis: where it starts, where it ends, and what it ticks at. */
+export interface ValueScale {
+    min: number;
+    max: number;
+    ticks: number[];
+    /** A value as a fraction of the plot — `0` at `min`, `1` at `max`. */
+    fraction: (value: number) => number;
+}
+/**
+ * The scale a value axis runs on, rounded out to numbers.
+ *
+ * Rounding **outward** is the part that matters. A maximum of 4,830 becomes
+ * 5,000, so the top tick is a round number and the tallest mark stops short of
+ * the ceiling; a scale whose last bar touches the frame reads as clipped even
+ * when it is exactly right.
+ *
+ * Zero stays in range unless the caller says otherwise, because a bar's length
+ * is proportional to its value only from a zero baseline. A line chart of a
+ * quantity that never goes near zero is the case for passing `min` — and it is
+ * a case the caller makes, not one the chart makes for them.
+ */
+export declare function valueScale(extent: {
+    min: number;
+    max: number;
+} | null, options?: {
+    min?: number;
+    max?: number;
+    tickCount?: number;
+    /** Keeps zero in range. Off for an axis the caller pinned. */
+    includeZero?: boolean;
+}): ValueScale;
+/** The plot's box inside the chart, once the axes have taken their bands. */
+export interface PlotBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** A band scale: one slot per category, with the marks centred in it. */
+export interface BandScale {
+    /** The centre of category `index`, in pixels along the axis. */
+    centre: (index: number) => number;
+    /** How wide one slot is. */
+    step: number;
+    /** How much of a slot the marks in it may take, together. */
+    band: number;
+}
+export declare function bandScale(count: number, length: number, ratio: number): BandScale;
+/**
+ * Roughly how wide a string renders at a given font size.
+ *
+ * An estimate on purpose. The exact answer is a canvas measurement per label
+ * per render, on a path that runs again on every resize — and what the number
+ * is used for is deciding how much room to reserve, where a few pixels of
+ * generosity cost nothing and a reflow costs a frame.
+ *
+ * 0.6em is about the advance of a digit in the sans-serifs a UI runs in.
+ * Anything CJK is close to a full em, so the wider characters are counted as
+ * one: a Korean axis reserving 60% of the room it needs is an axis that
+ * overlaps itself.
+ */
+export declare function textWidth(text: string, fontSize: number): number;
+/**
+ * A label cut to the room it has.
+ *
+ * The alternative, when a category name is wider than its slot, is to drop
+ * labels until the survivors fit — and on five categories called things like
+ * "Onboarding flow" that leaves exactly one. An axis with one label is not a
+ * shorter axis, it is an unlabelled one. So cut instead: the first few
+ * characters tell five words apart, and the hover layer and the table both
+ * still carry the whole of it.
+ */
+export declare function truncate(text: string, maxWidth: number, fontSize: number): string;
+/**
+ * How many labels an axis can show before they collide — every nth.
+ *
+ * Every nth rather than rotating them. A rotated axis is unreadable at a
+ * glance, and it takes a band of the plot to be unreadable in.
+ */
+export declare function tickStride(count: number, available: number, labelWidth: number): number;
+/**
+ * Whether the label at `index` survives the stride.
+ *
+ * Every nth, and — where it fits — the last one, which is the part a plain
+ * modulo gets wrong: a fourteen-day axis at a stride of two ends at day
+ * thirteen, and a percentage axis ends at 80%. The end of a scale is the number
+ * a reader looks for first, and dropping it to keep the arithmetic tidy is the
+ * wrong trade.
+ *
+ * `roomForLast` is measured rather than assumed — see `fitsLast`. Forcing a
+ * label that does not fit turns a missing "Jun" into an overlapping "MayJun".
+ */
+export declare function showsTick(index: number, count: number, stride: number, roomForLast: boolean): boolean;
+/**
+ * Whether the last label clears the last one the stride kept.
+ *
+ * The two sit `(count - 1) % stride` steps apart, and they need half of each
+ * label plus a little air: labels are centred on their tick, so only the inner
+ * halves can meet.
+ */
+export declare function fitsLast(count: number, stride: number, step: number, labelWidth: number): boolean;
+/** One datum, unpacked into the parts the frame reads. */
+export interface ChartValue {
+    value: number | null;
+    x?: MPChartCategory;
+    z?: number;
+    color?: string;
+    label?: React.ReactNode;
+}
+/**
+ * A datum in the one shape everything downstream reads.
+ *
+ * Every way of being absent collapses to `value: null` here — `null` itself, a
+ * missing entry, a `NaN`, an `Infinity`. They mean the same thing to a reader
+ * and they must mean the same thing to the path builder, because a `NaN` that
+ * survives this far reaches the scale and leaves the letters `NaN` in the `d`
+ * attribute, where it silently draws nothing at all.
+ */
+export declare function toValue(datum: MPChartDatum): ChartValue;
+/** Every series unpacked, in the order it was given. */
+export declare function toValues(series: readonly MPChartSeries[]): ChartValue[][];
+/**
+ * A category as a number, for an axis that is really a second value axis.
+ *
+ * A `Date` is its epoch milliseconds, which is what makes a scatter of
+ * timestamps work at all. A string is not a place on a number line, so it comes
+ * back `null` rather than `NaN` — the same rule `toValue` follows, for the same
+ * reason.
+ */
+export declare function toNumber(value: MPChartCategory | undefined): number | null;
+/** How many categories there are: the longest series decides. */
+export declare function categoryCount(series: readonly MPChartSeries[]): number;
+/**
+ * What category `index` is called, from the three places it can come from.
+ *
+ * The chart's own `categories` first, then whatever a point said its `x` was,
+ * then the index. A chart given neither still has an axis — it is numbered, and
+ * a numbered axis is a great deal better than a blank one.
+ */
+export declare function categoryAt(index: number, categories: readonly MPChartCategory[] | undefined, values: readonly (readonly ChartValue[])[]): MPChartCategory;
+/**
+ * A category as the axis writes it.
+ *
+ * A `Date` gets a short day rather than a full one: an axis is a row of labels
+ * that have to fit beside each other, and "Mar 4" carries what "March 4, 2026"
+ * carries in a third of the room. The year is the caller's to add with
+ * `tickFormat` when a chart spans one.
+ */
+export declare function formatCategory(value: MPChartCategory, locale: string | undefined): string;
+/**
+ * How tall the drawing is, before the caller says otherwise.
+ *
+ * Not the control ladder. A chart is a figure on a page rather than a control
+ * in a row, so the rungs are set against what a plot needs to be readable: `md`
+ * at 220 gives five gridlines about forty pixels apart, which is roughly where
+ * a reader stops being able to place a value between two of them.
+ */
+export declare const PLOT_HEIGHT: Record<MPSize, number>;
+/**
+ * What the axis labels are set in, in pixels.
+ *
+ * Pixels and not a type role, because these are drawn inside an `<svg>` where a
+ * class does not reach and the number is needed for the arithmetic anyway —
+ * every band an axis reserves is measured from its own font size.
+ */
+export declare const CHART_FONT_SIZE: Record<MPSize, number>;
+/** How heavy a line is. Two pixels at `md`, which is the chart line weight. */
+export declare const LINE_WIDTH: Record<MPSize, number>;
+/**
+ * How big a marker is.
+ *
+ * `md` at 4 makes an 8px dot, which is the floor for a mark a pointer is
+ * expected to land on. Below that the hit target is doing all the work and the
+ * mark is only telling the reader where to aim.
+ */
+export declare const MARKER_RADIUS: Record<MPSize, number>;
+/**
+ * The gap of surface between two marks that would otherwise touch.
+ *
+ * Two pixels, and it is structural rather than decorative: where two fills meet
+ * with no gap the eye reads one shape, and the boundary between them is exactly
+ * the thing the chart is drawing.
+ */
+export declare const MARK_GAP = 2;
+/** How much a bar's data end is rounded. */
+export declare const BAR_RADIUS = 4;
+/**
+ * How thick a bar is allowed to get.
+ *
+ * A cap rather than a size: bars are sized by their band, and two categories in
+ * a wide chart would otherwise be two slabs half the plot across. Past about
+ * this width a bar stops reading as a measured length and starts reading as a
+ * block of colour, and the axis it is measured against gets no easier to use.
+ */
+export declare const BAR_MAX_THICKNESS: Record<MPSize, number>;
+/**
+ * How much of its slot a band of bars takes, leaving the rest as air.
+ *
+ * Bars need the gap and lines do not, which is the whole reason the frame takes
+ * a ratio at all: a row of bars with no space between them is a histogram, and
+ * a histogram means something else — that the categories are contiguous
+ * intervals rather than separate things.
+ */
+export declare const BAR_BAND_RATIO = 0.72;
+/**
+ * A point on a circle, in the convention the round charts use: **zero is twelve
+ * o'clock and the angle grows clockwise**.
+ *
+ * Not the mathematical convention, where zero is three o'clock and the angle
+ * grows the other way. A chart of parts is read the way a clock is read, and
+ * every angle a caller passes — `startAngle`, a gauge's sweep — is easier to
+ * reason about in the one they already have.
+ */
+export declare function polarPoint(cx: number, cy: number, radius: number, angle: number): {
+    x: number;
+    y: number;
+};
+/**
+ * A ring segment, or a pie slice when the inner radius is nothing.
+ *
+ * A full turn is drawn as **two** arcs rather than one, and that is not a
+ * flourish: an SVG arc is defined by its two endpoints, so a sweep of exactly
+ * 360° starts and ends at the same point and the renderer draws nothing at all.
+ * A single-category pie is a real chart, and it would come out blank.
+ */
+export declare function arcPath(cx: number, cy: number, outer: number, inner: number, from: number, to: number): string;
+/**
+ * The extent of the **category** values, for an axis that runs on numbers.
+ *
+ * Only points that have a `y` count. A point with no value is not on the plot,
+ * so letting its `x` stretch the axis would leave a margin of empty plot
+ * standing in for data that was never drawn.
+ */
+export declare function categoryExtent(values: readonly (readonly ChartValue[])[], categories: readonly MPChartCategory[] | undefined): {
+    min: number;
+    max: number;
+} | null;
+/** The shapes a mark can take, in the order they are handed out. */
+export type MPChartMarkShape = 'circle' | 'square' | 'triangle' | 'diamond' | 'cross';
+/**
+ * The five, in an order chosen for how quickly one is told from the next.
+ *
+ * A circle first because it is the mark a scatter is expected to use, then the
+ * two that differ from it most — a square by its corners, a triangle by having
+ * three of them — before the two that are refinements of those.
+ *
+ * They exist because the palette runs out sooner here than anywhere else.
+ * Colour alone separates **three** series where any two marks can touch, and a
+ * scatter is exactly that case; a shape is the second channel that carries the
+ * rest, and it survives greyscale, print and forced colours as well.
+ */
+export declare const MARK_SHAPES: readonly MPChartMarkShape[];
+/** One mark, centred on a point. */
+export declare function markPath(shape: MPChartMarkShape, cx: number, cy: number, radius: number): string;
+/**
+ * Where one point sits along a category axis that runs on numbers.
+ *
+ * The same three sources `categoryAt` reads, in the same order — but per
+ * **point** rather than per column, because on a scatter each series has its
+ * own x at every index and there is no column for them to share.
+ */
+export declare function pointX(value: ChartValue, index: number, categories: readonly MPChartCategory[] | undefined): number | null;
+/**
+ * How big a bubble is, for a magnitude carried by its **area**.
+ *
+ * The radius goes as the square root, and that is the whole of it: area grows
+ * as the square of the radius, so a bubble drawn with its radius proportional
+ * to the value shows four times the ink for twice the number. Every reader
+ * judges the blob and not the line across it, which makes the naive version a
+ * chart that doubles its own data.
+ *
+ * `min` is a floor rather than zero, because a bubble of no radius is a point
+ * that has been removed from the chart.
+ */
+export declare function bubbleRadius(z: number, maxZ: number, max: number, min: number): number;
+/** How many steps the sequential ramp has. */
+export declare const RAMP_STEPS = 5;
+/**
+ * Which step of the ramp a fraction of the range lands on.
+ *
+ * **Steps rather than a gradient**, and that is the decision worth stating. A
+ * continuous fill looks better and is read worse: a reader given a smooth ramp
+ * can say "darker" and nothing else, where five steps let them match a cell to
+ * a band in the legend and come away with a number. Five is about the most
+ * anybody tells apart in one hue.
+ */
+export declare function rampStep(fraction: number): number;
+/** The colour of one step, by its index from the low end. */
+export declare function rampFill(step: number): string;
+/**
+ * The ink a label sits in **on** a ramp step.
+ *
+ * The two darkest steps take the light ink and the rest take the dark one. It
+ * is a threshold rather than a computation because the ramp is five fixed
+ * colours: a contrast calculation here would be arithmetic performed on every
+ * cell, every render, to arrive at an answer that was settled when the ramp was
+ * fitted.
+ */
+export declare function rampInk(step: number): string;

package/dist/internal/chart.js

@@ -0,0 +1 @@
+import{dateTimeFormatter as t,numberFormatter as n}from"./intl.js";export const CHART_SLOTS=8;const o=new Set(["primary","secondary","tertiary","error"]);export function seriesColor(t,n){return n?o.has(n)?`var(--_mp-color-${n})`:n:`var(--_mp-chart-${t%8+1})`}export const COMPACT_FROM=1e4;const r={notation:"compact",maximumFractionDigits:1},e={month:"short",day:"numeric"};export function formatStatistic(t,o,e,a){return Number.isFinite(t)?e?n(o,e).format(t):a&&Math.abs(t)>=1e4?n(o,r).format(t):n(o).format(t):""}export function deltaOf(t,n,o){const r=t-n,e=r>0?1:r<0?-1:0;return{absolute:r,percent:0===n?null:r/Math.abs(n)*100,direction:e,good:0!==e&&1===e==("up"===o)}}function a(t,n){if(0===t.length)return"";if(1===t.length)return`M${t[0].x} ${t[0].y}h0`;const o=`M${t[0].x} ${t[0].y}`;if("smooth"===n)return o+function(t){const n=t.length,o=[];for(let r=0;r<n-1;r+=1){const n=t[r+1].x-t[r].x;o.push(0===n?0:(t[r+1].y-t[r].y)/n)}const r=[o[0]??0];for(let t=1;t<n-1;t+=1){const n=o[t-1],e=o[t];r.push(n*e<=0?0:2*n*e/(n+e))}r.push(o[n-2]??0);const e=[];for(let o=0;o<n-1;o+=1){const n=(t[o+1].x-t[o].x)/3;e.push(`C${t[o].x+n} ${t[o].y+r[o]*n} ${t[o+1].x-n} ${t[o+1].y-r[o+1]*n} ${t[o+1].x} ${t[o+1].y}`)}return e.join("")}(t);const r=[];for(let o=1;o<t.length;o+=1)if("step"===n){const n=(t[o-1].x+t[o].x)/2;r.push(`H${n}V${t[o].y}H${t[o].x}`)}else r.push(`L${t[o].x} ${t[o].y}`);return o+r.join("")}export function linePath(t,n){return function(t){const n=[];let o=[];for(const r of t)null===r?(o.length>0&&n.push(o),o=[]):o.push(r);return o.length>0&&n.push(o),n}(t).map(t=>a(t,n)).join("")}export function bandPath(t,n,o){const r=[];let e=[],i=[];const u=()=>{e.length>0&&r.push(`${a(e,o)}${a([...i].reverse(),o).replace(/^M/,"L")}Z`),e=[],i=[]};return t.forEach((t,o)=>{const r=n[o];null!==t&&null!=r?(e.push(t),i.push(r)):u()}),u(),r.join("")}export function areaPath(t,n,o){return bandPath(t,t.map(t=>null===t?null:{x:t.x,y:n}),o)}export function barPath(t,n,o,r,e,a){const i=Math.abs(o),u=Math.abs(r);if(0===i||0===u)return"";const l=Math.max(0,Math.min(e,i/2,u/2)),c="both"===a,s={tl:c||"top"===a||"left"===a?l:0,tr:c||"top"===a||"right"===a?l:0,br:c||"bottom"===a||"right"===a?l:0,bl:c||"bottom"===a||"left"===a?l:0},x=(t,n,o)=>t>0?`a${t} ${t} 0 0 1 ${n} ${o}`:"";return`M${t+s.tl} ${n}h`+(i-s.tl-s.tr)+x(s.tr,s.tr,s.tr)+"v"+(u-s.tr-s.br)+x(s.br,-s.br,s.br)+"h"+-(i-s.bl-s.br)+x(s.bl,-s.bl,-s.bl)+"v"+-(u-s.tl-s.bl)+x(s.tl,s.tl,-s.tl)+"Z"}export function extentOf(t,n,o){const r=t.filter(t=>null!==t&&Number.isFinite(t)),e=n??(r.length>0?Math.min(...r):0),a=o??(r.length>0?Math.max(...r):0);return e===a?{min:e-.5,max:a+.5}:{min:e,max:a}}export function seriesExtent(t,n){let o=1/0,r=-1/0,e=!1;if(n){const n=t.reduce((t,n)=>Math.max(t,n.length),0);for(let a=0;a<n;a+=1){let n=0,i=0;for(const o of t){const t=o[a]?.value;null!=t&&(e=!0,t>=0?n+=t:i+=t)}o=Math.min(o,i),r=Math.max(r,n)}}else for(const n of t)for(const{value:t}of n)null!==t&&(e=!0,o=Math.min(o,t),r=Math.max(r,t));return e?{min:o,max:r}:null}function i(t){const n=10**Math.floor(Math.log10(t)),o=t/n;return o<=1?n:o<=2?2*n:o<=5?5*n:10*n}export function valueScale(t,n={}){const{tickCount:o=5,includeZero:r=!0}=n;let e=n.min??t?.min??0,a=n.max??t?.max??1;if(r&&void 0===n.min&&(e=Math.min(e,0)),r&&void 0===n.max&&(a=Math.max(a,0)),a===e){const t=Math.abs(a)>0?.5*Math.abs(a):1;e-=t,a+=t}const u=void 0!==n.min&&void 0!==n.max?function(t,n){const o=10**Math.floor(Math.log10(t/Math.max(1,n)));let r=i(t/Math.max(1,n)),e=1/0;for(const a of[.1,1,10])for(const i of[1,2,2.5,5]){const u=i*a*o,l=t/u,c=Math.round(l);if(c<1||Math.abs(l-c)>1e-9)continue;const s=Math.abs(c-n);s<e&&(e=s,r=u)}return r}(a-e,o):i((a-e)/Math.max(1,o)),l=void 0!==n.min?e:Math.floor(e/u)*u,c=void 0!==n.max?a:Math.ceil(a/u)*u,s=c-l||1,x=[];for(let t=l;t<=c+1e-9*u;t+=u)x.push(Number(t.toFixed(12)));return{min:l,max:c,ticks:x,fraction:t=>(t-l)/s}}export function bandScale(t,n,o){const r=t>0?n/t:n;return{step:r,band:r*o,centre:t=>r*(t+.5)}}export function textWidth(t,n){let o=0;for(const n of t)o+=/[ᄀ-ᇿ⺀-꓏가-퟿豈-﫿︰-﹏]/.test(n)?1:.6;return o*n}export function truncate(t,n,o){if(n<=0||textWidth(t,o)<=n)return t;const r=n-textWidth("…",o);let e="",a=0;for(const n of t){const t=a+textWidth(n,o);if(t>r)break;a=t,e+=n}return e.length>0?`${e.trimEnd()}…`:"…"}export function tickStride(t,n,o){return t<=1||n<=0?1:Math.max(1,Math.ceil(t/Math.max(1,Math.floor(n/Math.max(1,o)))))}export function showsTick(t,n,o,r){return t%o===0||r&&t===n-1}export function fitsLast(t,n,o,r){const e=(t-1)%n;return e>0&&e*o>=r+8}export function toValue(t){return null==t?{value:null}:"number"==typeof t?{value:Number.isFinite(t)?t:null}:"object"==typeof t&&"y"in t?{value:null!==t.y&&Number.isFinite(t.y)?t.y:null,x:t.x,z:t.z,color:t.color?seriesColor(0,t.color):void 0,label:t.label}:{value:null}}export function toValues(t){return t.map(t=>t.data.map(toValue))}export function toNumber(t){return t instanceof Date?Number.isFinite(t.getTime())?t.getTime():null:"number"==typeof t&&Number.isFinite(t)?t:null}export function categoryCount(t){return t.reduce((t,n)=>Math.max(t,n.data.length),0)}export function categoryAt(t,n,o){if(n&&t<n.length)return n[t];for(const n of o){const o=n[t]?.x;if(void 0!==o)return o}return t}export function formatCategory(o,r){return o instanceof Date?t(r,e).format(o):"number"==typeof o?n(r).format(o):o}export const PLOT_HEIGHT={xs:120,sm:160,md:220,lg:280,xl:360};export const CHART_FONT_SIZE={xs:10,sm:11,md:12,lg:13,xl:14};export const LINE_WIDTH={xs:1.5,sm:1.75,md:2,lg:2.5,xl:3};export const MARKER_RADIUS={xs:3,sm:3.5,md:4,lg:4.5,xl:5};export const MARK_GAP=2;export const BAR_RADIUS=4;export const BAR_MAX_THICKNESS={xs:24,sm:32,md:40,lg:48,xl:56};export const BAR_BAND_RATIO=.72;export function polarPoint(t,n,o,r){return{x:t+o*Math.sin(r),y:n-o*Math.cos(r)}}export function arcPath(t,n,o,r,e,a){const i=a-e;if(Math.abs(i)<1e-9||o<=0)return"";const u=Math.abs(i)>=2*Math.PI-1e-9,l=u?e+2*Math.PI*Math.sign(i||1):a,c=e+(l-e)/2,s=Math.abs(l-e)>Math.PI?1:0,x=l>e?1:0,h=x?0:1,$=polarPoint(t,n,o,e),f=polarPoint(t,n,o,c),m=polarPoint(t,n,o,l),p=u?`A${o} ${o} 0 0 ${x} ${f.x} ${f.y}A${o} ${o} 0 0 ${x} ${m.x} ${m.y}`:`A${o} ${o} 0 ${s} ${x} ${m.x} ${m.y}`;if(r<=0)return u?`M${$.x} ${$.y}${p}Z`:`M${t} ${n}L${$.x} ${$.y}${p}Z`;const M=polarPoint(t,n,r,l),b=polarPoint(t,n,r,c),d=polarPoint(t,n,r,e),y=u?`A${r} ${r} 0 0 ${h} ${b.x} ${b.y}A${r} ${r} 0 0 ${h} ${d.x} ${d.y}`:`A${r} ${r} 0 ${s} ${h} ${d.x} ${d.y}`;return`M${$.x} ${$.y}${p}L${M.x} ${M.y}${y}Z`}export function categoryExtent(t,n){let o=1/0,r=-1/0,e=!1;return t.forEach(t=>{t.forEach((t,a)=>{if(null===t.value)return;const i=toNumber(t.x??n?.[a]??a);null!==i&&(e=!0,o=Math.min(o,i),r=Math.max(r,i))})}),e?{min:o,max:r}:null}export const MARK_SHAPES=["circle","square","triangle","diamond","cross"];const u={circle:1,square:.886,triangle:1.35,diamond:1.25,cross:1.1};export function markPath(t,n,o,r){const e=r*u[t];switch(t){case"square":return`M${n-e} ${o-e}h${2*e}v${2*e}h${2*-e}Z`;case"triangle":return`M${n} ${o-e}L${n+.866*e} ${o+.5*e}L${n-.866*e} ${o+.5*e}Z`;case"diamond":return`M${n} ${o-e}L${n+e} ${o}L${n} ${o+e}L${n-e} ${o}Z`;case"cross":return`M${n-e} ${o-e}L${n+e} ${o+e}M${n+e} ${o-e}L${n-e} ${o+e}`;default:return`M${n-e} ${o}a${e} ${e} 0 1 0 ${2*e} 0a${e} ${e} 0 1 0 ${2*-e} 0Z`}}export function pointX(t,n,o){return toNumber(t.x??o?.[n]??n)}export function bubbleRadius(t,n,o,r){return n<=0||t<=0?r:r+(o-r)*Math.sqrt(Math.min(1,t/n))}export const RAMP_STEPS=5;export function rampStep(t){return Number.isFinite(t)?Math.min(4,Math.max(0,Math.floor(5*t))):0}export function rampFill(t){return`var(--_mp-chart-scale-${Math.min(5,Math.max(1,t+1))})`}export function rampInk(t){return t>=3?"var(--_mp-color-surface)":"var(--_mp-color-on-surface)"}

package/dist/internal/color-scheme.d.ts

@@ -4,15 +4,6 @@ export type MPColorScheme = 'light' | 'dark' | 'system';
 export type MPResolvedColorScheme = 'light' | 'dark';
 export declare const SCHEME_ATTRIBUTE = "data-mp-scheme";
 export declare const DEFAULT_STORAGE_KEY = "mp-color-scheme";
-/**
- * Puts the choice on the document element, or takes it off.
- *
- * `'system'` **removes** the attribute rather than writing it, which is the
- * whole of how the media query gets its say back: the dark block is reached
- * either by `prefers-color-scheme` on a root that is not forced light, or by the
- * attribute. An attribute spelling out `system` would match neither.
- */
-export declare function applyScheme(scheme: MPColorScheme): void;
 export declare function setScheme(storageKey: string, scheme: MPColorScheme): void;
 export declare function useChosenScheme(storageKey: string): MPColorScheme;
 /**

package/dist/internal/color-scheme.js

@@ -1,2 +1,2 @@
 "use client";
-import*as e from"react";export const SCHEME_ATTRIBUTE="data-mp-scheme";export const DEFAULT_STORAGE_KEY="mp-color-scheme";const t="(prefers-color-scheme: dark)";function n(e){return"light"===e||"dark"===e||"system"===e}let o;const r=new Set;function c(){for(const e of r)e()}export function applyScheme(e){if("undefined"==typeof document)return;const t=document.documentElement;"system"===e?t.removeAttribute("data-mp-scheme"):t.setAttribute("data-mp-scheme",e)}export function setScheme(e,t){o=t,function(e,t){try{"system"===t?localStorage.removeItem(e):localStorage.setItem(e,t)}catch{}}(e,t),applyScheme(t),c()}function s(e){return r.add(e),()=>{r.delete(e)}}function u(e){return o??=function(){if("undefined"==typeof document)return;const e=document.documentElement.getAttribute("data-mp-scheme");return n(e)&&"system"!==e?e:void 0}()??function(e){try{if("undefined"==typeof localStorage)return"system";const t=localStorage.getItem(e);return n(t)?t:"system"}catch{return"system"}}(e),o}export function useChosenScheme(t){const n=e.useCallback(()=>u(t),[t]);return e.useSyncExternalStore(s,n,()=>"system")}function m(e){if("undefined"==typeof window||!window.matchMedia)return()=>{};const n=window.matchMedia(t);return n.addEventListener("change",e),()=>n.removeEventListener("change",e)}function i(){return"undefined"!=typeof window&&window.matchMedia?.(t).matches?"dark":"light"}export function useSystemScheme(){return e.useSyncExternalStore(m,i,()=>"light")}export function resetScheme(){o=void 0,c()}
+import*as e from"react";export const SCHEME_ATTRIBUTE="data-mp-scheme";export const DEFAULT_STORAGE_KEY="mp-color-scheme";const t="(prefers-color-scheme: dark)";function n(e){return"light"===e||"dark"===e||"system"===e}let o;const r=new Set;function c(){for(const e of r)e()}export function setScheme(e,t){o=t,function(e,t){try{"system"===t?localStorage.removeItem(e):localStorage.setItem(e,t)}catch{}}(e,t),function(e){if("undefined"==typeof document)return;const t=document.documentElement;"system"===e?t.removeAttribute("data-mp-scheme"):t.setAttribute("data-mp-scheme",e)}(t),c()}function s(e){return r.add(e),()=>{r.delete(e)}}function u(e){return o??=function(){if("undefined"==typeof document)return;const e=document.documentElement.getAttribute("data-mp-scheme");return n(e)&&"system"!==e?e:void 0}()??function(e){try{if("undefined"==typeof localStorage)return"system";const t=localStorage.getItem(e);return n(t)?t:"system"}catch{return"system"}}(e),o}export function useChosenScheme(t){const n=e.useCallback(()=>u(t),[t]);return e.useSyncExternalStore(s,n,()=>"system")}function m(e){if("undefined"==typeof window||!window.matchMedia)return()=>{};const n=window.matchMedia(t);return n.addEventListener("change",e),()=>n.removeEventListener("change",e)}function i(){return"undefined"!=typeof window&&window.matchMedia?.(t).matches?"dark":"light"}export function useSystemScheme(){return e.useSyncExternalStore(m,i,()=>"light")}export function resetScheme(){o=void 0,c()}

package/dist/internal/config.d.ts

@@ -1,9 +1,10 @@
 /**
- * The two prop defaults an application can move for the whole page.
+ * The prop defaults an application can move for the whole page.
  *
- * `size` and `color` are the only axes where every component in this library
- * starts from the *same* answer — `md` and `primary` — which is what makes a
- * single app-wide default meaningful for them and meaningless for anything else.
+ * `size`, `color` and `density` are the only axes where every component that has
+ * them starts from the *same* answer — `md`, `primary` and `0` — which is what
+ * makes a single app-wide default meaningful for them and meaningless for
+ * anything else.
  * A `variant` default is per component by design (`MPAccordion` is `outlined`,
  * `MPAlert` is `tonal`, `MPBadge` is `filled`), so one global value would be
  * overwriting six considered decisions with one arbitrary one.
@@ -26,11 +27,20 @@
  * has to reach every call site is exactly what context is for.
  */
 import * as React from 'react';
-import type { MPColor, MPSize } from '../types.js';
+import type { MPColor, MPDensity, MPSize, MPWindowClass } from '../types.js';
 /** What an `MPConfigProvider` can set. Anything unset is inherited, then default. */
 export interface MPConfigValue {
     size?: MPSize;
     color?: MPColor;
+    density?: MPDensity;
+    /**
+     * Where the window size classes begin, for the JavaScript half of the library.
+     *
+     * Partial and merged over MD3's own, in CSS pixels. See `MPConfigProvider` for
+     * what this does and does not reach — the stylesheet is not downstream of it,
+     * and cannot be.
+     */
+    breakpoints?: Partial<Record<MPWindowClass, number>>;
 }
 export declare const MPConfigContext: React.Context<MPConfigValue>;
 /** The configuration in force at this point in the tree. */
@@ -41,3 +51,12 @@ export declare function useMPConfig(): MPConfigValue;
  */
 export declare function useMPSize(size: MPSize | undefined): MPSize;
 export declare function useMPColor(color: MPColor | undefined): MPColor;
+/**
+ * The third axis with an app-wide default, and the one most likely to be set
+ * once and never again: a product decides how dense it is at the top, not per
+ * table.
+ *
+ * Only the components that hold things read it, so a page set to `-2` tightens
+ * its lists and leaves its buttons at the height they have to be.
+ */
+export declare function useMPDensity(density: MPDensity | undefined): MPDensity;

package/dist/internal/config.js

@@ -1,2 +1,2 @@
 "use client";
-import*as t from"react";const e=Object.freeze({});export const MPConfigContext=/*@__PURE__*/t.createContext(e);export function useMPConfig(){return t.useContext(MPConfigContext)}export function useMPSize(e){const o=t.useContext(MPConfigContext);return e??o.size??"md"}export function useMPColor(e){const o=t.useContext(MPConfigContext);return e??o.color??"primary"}
+import*as t from"react";const e=Object.freeze({});export const MPConfigContext=/*@__PURE__*/t.createContext(e);export function useMPConfig(){return t.useContext(MPConfigContext)}export function useMPSize(e){const o=t.useContext(MPConfigContext);return e??o.size??"md"}export function useMPColor(e){const o=t.useContext(MPConfigContext);return e??o.color??"primary"}export function useMPDensity(e){const o=t.useContext(MPConfigContext);return e??o.density??0}