plass-ui 1.2.0 → 1.4.0

package/dist/internal/chart.d.ts

@@ -0,0 +1,473 @@
+/**
+ * The arithmetic every chart is made of.
+ *
+ * Here rather than in a component for the reason `internal/progress.ts` is: five
+ * components draw five different marks and ask exactly the same four questions
+ * first — what is the range, where does a value land in the plot, what are the
+ * clean numbers to tick at, and what colour is series four. A chart file that
+ * also has to answer those is a file where the drawing cannot be read.
+ *
+ * There is no React in here and nothing in it knows what an SVG is. What it
+ * knows is data and pixels; `internal/chart-frame.tsx` is where those become elements.
+ *
+ * The scales are deliberately not a `d3-scale`. A linear scale is six lines, a
+ * band scale is four, and `nice numbers` is twelve — against a charting stack
+ * that would be the largest thing in the package. The same trade `internal/color.ts`
+ * makes.
+ */
+import type * as React from 'react';
+import type { PlassChartCategory, PlassChartDatum, PlassChartSeries, PlassDensity, PlassSize } from '../types.js';
+/**
+ * How tall a plot is when nobody said, in pixels.
+ *
+ * A chart is one of the few things in the library with no intrinsic height — it
+ * is as tall as it is given — so this ladder is what stops every chart on a
+ * dashboard being a different shape. The steps climb faster than the control
+ * ladder because the thing being scaled is a *picture*: at `xs` this is a strip
+ * beside a number, at `xl` it is what the screen is about.
+ *
+ * The axis band is drawn *inside* this, not added to it. A card sized to the
+ * plot and then handed axis labels is the card that grows a two-line scrollbar.
+ */
+export declare const plotHeights: Record<PlassSize, number>;
+/**
+ * A PlSparkline's own ladder, which is a different object: it has no axes, no
+ * legend and nothing to read off it but the shape, so it is sized against the
+ * line of text it sits next to rather than against the page.
+ */
+export declare const sparklineHeights: Record<PlassSize, number>;
+/**
+ * The weight of a line, in pixels. `md` is 2, which is the width a data line
+ * wants everywhere — thin enough to stay a line where two of them cross, heavy
+ * enough to hold a hue at 3:1.
+ */
+export declare const lineWidths: Record<PlassSize, number>;
+/**
+ * The radius of a marker. `md` is 4, so the dot is 8px across before its ring —
+ * the floor below which a marker stops being something a pointer can find.
+ */
+export declare const markerRadii: Record<PlassSize, number>;
+/**
+ * Tick and label type, in pixels rather than as a class.
+ *
+ * SVG text does not inherit a Tailwind utility usefully — the `<text>` has to
+ * carry a `font-size` the layout arithmetic can also read, because the room the
+ * axis reserves is measured from it. These are `metaTextClasses` as numbers;
+ * keep the two in step.
+ */
+export declare const chartFontSizes: Record<PlassSize, number>;
+/**
+ * How thick a bar is allowed to get, in pixels.
+ *
+ * A cap and not a width: the band a bar sits in is whatever the plot divided by
+ * the category count gives, and a bar that fills its band leaves the chart with
+ * no air in it at all. Past this the leftover stays as space.
+ */
+export declare const barMaxThickness: Record<PlassSize, number>;
+/**
+ * How much of a band the bars in it take, before the cap above applies.
+ * `density` is the only thing that moves it — the same rule as everywhere else,
+ * spacing and nothing but spacing.
+ */
+export declare const barBandRatio: Record<PlassDensity, number>;
+/** The gap the surface shows through between two touching marks, in pixels. */
+export declare const markGap = 2;
+/** The corner cut off the data end of a bar. Square at the baseline. */
+export declare const barRadius = 4;
+/** The eight slots, as the `var()`s that resolve them per theme. */
+export declare const chartPalette: readonly string[];
+/** A `PlassColor` resolves to its readable-on-surface accent; anything else is CSS. */
+export declare function resolveColor(value: string): string;
+/**
+ * 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 that a re-render is not allowed to take back.
+ *
+ * Past the eighth slot it wraps, and a chart that gets there should not have —
+ * a ninth hue is indistinguishable from one of the first eight under colour
+ * vision deficiency no matter which one is chosen. Fold the tail into an
+ * "Other" series, or draw a second chart.
+ */
+export declare function seriesColor(series: Pick<PlassChartSeries, 'color'> | undefined, index: number, palette?: readonly string[]): string;
+/** A datum unpacked into the shape the drawing code reads. */
+export interface ChartValue {
+    value: number | null;
+    x?: PlassChartCategory;
+    z?: number;
+    color?: string;
+    label?: React.ReactNode;
+}
+/**
+ * One datum, whichever of the three ways it was written.
+ *
+ * `NaN` is folded into `null` here rather than at every call site: it arrives
+ * from a division somewhere upstream, it means the same thing a gap means, and
+ * a scale that is handed one produces a path with the letters `NaN` in it —
+ * which fails silently as a blank chart rather than loudly as an error.
+ */
+export declare function toValue(datum: PlassChartDatum): ChartValue;
+/** Every series unpacked, in the order it was given. */
+export declare function toValues(series: readonly PlassChartSeries[]): ChartValue[][];
+/**
+ * A category as a number, for a category axis that is really a value axis.
+ *
+ * A `Date` is its epoch milliseconds, which is what makes a scatter of
+ * timestamps work at all. A string is not a position on a number line, so it
+ * comes back `null` rather than `NaN` — the same rule `toValue` follows, and
+ * for the same reason: a `NaN` reaches the scale and leaves the letters in the
+ * path.
+ */
+export declare function toNumber(value: PlassChartCategory | undefined): number | null;
+/**
+ * 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 PlassChartCategory[] | undefined): number | null;
+/**
+ * The extent of the category values, for a chart whose x is a number.
+ *
+ * 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 ChartValue[][], categories: readonly PlassChartCategory[] | undefined): {
+    min: number;
+    max: number;
+} | null;
+/**
+ * The radius a bubble gets for its `z`, in pixels.
+ *
+ * `z` is an **area** and not a radius, which is the single most common way a
+ * bubble chart lies: encode it as a radius and a value twice as large draws a
+ * mark four times the size. The square root is what makes the ink on the page
+ * proportional to the number behind it.
+ *
+ * `min` is a floor rather than a scale — a bubble for a small-but-real value
+ * has to stay something a pointer can find, and a zero is the only thing
+ * allowed to disappear.
+ */
+export declare function bubbleRadius(z: number, maxZ: number, max: number, min: number): number;
+/** How many categories the widest series has. */
+export declare function categoryCount(series: readonly PlassChartSeries[]): number;
+/**
+ * What the category axis says at position `index`.
+ *
+ * `categories` wins, then whatever the first series that has one calls its own
+ * point, then the index. Three sources rather than one because a chart is
+ * written both ways in the wild — a column of labels beside a column of
+ * numbers, or points that carry their own `x` — and neither is wrong.
+ */
+export declare function categoryAt(index: number, categories: readonly PlassChartCategory[] | undefined, values: readonly ChartValue[][]): PlassChartCategory;
+/**
+ * The extent of the values, with the stacking rule applied.
+ *
+ * Stacked charts measure the *totals* and not the parts, and the two arms are
+ * accumulated separately so a series that goes negative does not shorten the
+ * bar above it. An all-`null` chart has no extent at all, which is what the
+ * `null` return says — the caller draws its empty state rather than an axis
+ * from `Infinity` to `-Infinity`.
+ */
+export declare function extentOf(values: readonly ChartValue[][], stacked: boolean): {
+    min: number;
+    max: number;
+} | null;
+/** A value scale: where it starts, where it ends, and what it ticks at. */
+export interface ValueScale {
+    min: number;
+    max: number;
+    ticks: number[];
+    /** A value → a fraction of the plot, `0` at `min` and `1` at `max`. */
+    fraction: (value: number) => number;
+}
+/**
+ * The scale a value axis runs on, rounded out to clean numbers.
+ *
+ * Rounding *outward* is the part that matters: a maximum of 4,830 becomes 5,000
+ * and not 4,830, so the top tick is a number and the tallest bar stops short of
+ * the ceiling. A scale whose last bar touches the frame reads as clipped even
+ * when it is exactly right.
+ *
+ * Zero is included unless the caller says otherwise, because bar length is only
+ * proportional to value when the baseline is zero. A line chart of a quantity
+ * that never approaches zero is the case for passing `min` — and it is a case
+ * the caller has to make, 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 a line chart told an explicit `min`. */
+    includeZero?: boolean;
+}): ValueScale;
+/** The units a time axis is allowed to step in. */
+export type TimeUnit = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/** A value scale whose numbers are instants, and the unit its ticks step in. */
+export interface TimeScale extends ValueScale {
+    unit: TimeUnit;
+    /** How many of that unit each step covers — 1, 5, 15 minutes and so on. */
+    step: number;
+}
+/**
+ * The scale a time axis runs on, ticking where a calendar ticks.
+ *
+ * The ends round *outward* to the step for the reason `valueScale`'s do: a span
+ * that starts exactly on the left edge reads as clipped rather than as
+ * starting there. Past a year the 1-2-5 family comes back, because above the
+ * year time really is decimal — decades and centuries are the only units left.
+ */
+export declare function timeScale(extent: {
+    min: number;
+    max: number;
+} | null, options?: {
+    min?: number;
+    max?: number;
+    tickCount?: number;
+}): TimeScale;
+/** One instant on a time axis, written unambiguously — for a tooltip or a table. */
+export declare function formatTimeValue(value: number, unit: TimeUnit, locale?: string): string;
+/**
+ * A whole axis of ticks, written the way an axis is read.
+ *
+ * The year is decided for the axis rather than for each tick, and that is the
+ * part worth explaining. Writing it only where it *changes* is what a reader
+ * wants and is not safe here: the labels are thinned again downstream, by a
+ * stride measured against the plot's real width, and the tick the year was
+ * riding on is exactly the one that gets dropped — leaving `Oct 2025 · Dec ·
+ * Feb` with nothing to say which year February is in.
+ *
+ * So: an axis inside one year names it once, on the first tick, which is the
+ * one tick a stride never removes. An axis that crosses a year names it on
+ * every tick, so whichever ones survive are each unambiguous. Wider labels mean
+ * a heavier stride, and a heavier stride is the better failure.
+ */
+export declare function formatTimeTicks(ticks: readonly number[], unit: TimeUnit, locale?: string): string[];
+/**
+ * How many ticks a category axis can show before the labels collide, and which
+ * ones they are.
+ *
+ * Every nth label rather than rotating them: a rotated axis is unreadable at a
+ * glance and it steals a band of the plot to be unreadable in. `n` is chosen so
+ * the labels clear each other at the measured width, and it always keeps the
+ * first — a reader who cannot see where the axis starts cannot read any of it.
+ */
+export declare function tickStride(count: number, available: number, labelWidth: number): number;
+/**
+ * Whether the label at `index` survives the stride.
+ *
+ * Every nth, and — when 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 the other half of it and is measured rather than guessed —
+ * see `fitsLast`. Forcing a label that does not fit turns a missing "Jun" into
+ * an overlapping "MayJun", which is worse than what it fixed.
+ */
+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 are `(count - 1) % stride` steps apart, and they need half of each
+ * label plus a little air between them — labels are centred on their tick, so
+ * only the inner halves can collide.
+ */
+export declare function fitsLast(count: number, stride: number, step: number, labelWidth: number): boolean;
+/**
+ * Roughly how wide a string renders at a given font size.
+ *
+ * An estimate on purpose. The alternative is a canvas measurement per label per
+ * render, which is a layout read on a path that runs on every resize — and what
+ * this number is used for is deciding how much room to reserve, where being a
+ * few pixels generous costs nothing and being exact costs a reflow.
+ *
+ * 0.6em is the average advance of a digit in the sans-serifs a UI runs in;
+ * anything CJK is close to a full em, so the widest character decides.
+ */
+export declare function textWidth(text: string, fontSize: number): number;
+/**
+ * A label cut to the room it has, with an ellipsis.
+ *
+ * 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 of them on the axis — an axis with
+ * one label is not a shorter axis, it is an unlabelled one. Cut instead: the
+ * first few characters distinguish five words, and the tooltip and the table
+ * both still have the whole thing.
+ */
+export declare function truncate(text: string, maxWidth: number, fontSize: number): string;
+/** 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 wide the marks in a slot are allowed to be, together. */
+    band: number;
+}
+export declare function bandScale(count: number, length: number, ratio: number): BandScale;
+/**
+ * A path through the points, in whichever of the three shapes was asked for.
+ *
+ * `null` breaks the path rather than interpolating across it — the `M` that
+ * starts a new subpath is the gap. A line that bridges a missing month is a
+ * line that invents a number.
+ *
+ * `smooth` is a monotone cubic and not a Catmull-Rom, which is not a detail: a
+ * plain spline overshoots between two close points, so a series that never goes
+ * below zero draws a curve that does. A chart is allowed to be curved and it is
+ * not allowed to show a value that is not in the data.
+ */
+export declare function linePath(points: readonly ({
+    x: number;
+    y: number;
+} | null)[], curve: 'linear' | 'smooth' | 'step'): string;
+/**
+ * The same path closed down to a baseline, for an area.
+ *
+ * Built from the runs rather than from the whole line so a gap is a gap in the
+ * fill too — an area that closes across a missing month fills in a value that
+ * was never measured, which is the same lie the bridged line tells, painted
+ * over a larger part of the chart.
+ */
+export declare function areaPath(points: readonly ({
+    x: number;
+    y: number;
+} | null)[], baseline: readonly ({
+    x: number;
+    y: number;
+} | null)[] | number, curve: 'linear' | 'smooth' | 'step'): string;
+/**
+ * A rectangle with the two corners at its *data end* cut off.
+ *
+ * Rounded at the end and square at the baseline, which is not a stylistic
+ * split: a bar that is rounded where it meets the axis has lost the exact
+ * moment it starts, 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.
+ *
+ * The radius shrinks to fit rather than clipping, so a bar two pixels tall is a
+ * bar and not a circle. `end` is which way the value grows.
+ */
+export declare function barPath(x: number, y: number, width: number, height: number, radius: number, end: 'up' | 'down' | 'left' | 'right'): string;
+/**
+ * The shapes a point mark can take.
+ *
+ * The dependable second identity channel, and the only chart form with one
+ * going spare: a line cannot be a triangle and a bar cannot be a cross, but a
+ * dot can be anything. Five is enough for every palette a chart is allowed.
+ */
+export type MarkShape = 'circle' | 'square' | 'triangle' | 'diamond' | 'cross';
+/** The order shapes are handed out in, matching the palette: fixed, never cycled. */
+export declare const markShapes: readonly MarkShape[];
+/**
+ * One point mark, as a path, centred on `cx`/`cy` and covering the same area a
+ * circle of radius `r` would.
+ *
+ * A circle comes back as a path too rather than as a `<circle>`, so whoever
+ * draws the marks writes one element and not a branch — the ring, the fill and
+ * the hover treatment are then unarguably the same on all five.
+ */
+export declare function markPath(shape: MarkShape, cx: number, cy: number, r: number): string;
+/**
+ * The centre line of that slice, as an *open* path.
+ *
+ * `arcPath` below draws the slice itself, which is a closed shape — and a shape
+ * whose `d` has to be rewritten every time the value moves. `d` is not a
+ * property CSS can travel along, so a dial drawn that way jumps to each new
+ * reading. Stroked instead, the same ring is one line with a width, and how much
+ * of it is drawn is `stroke-dashoffset`, which is a number and does travel.
+ *
+ * It is what ProgressCircular already does, bent to an arbitrary span — which is
+ * the point: a gauge is a Meter bent into an arc, and the four indicators in
+ * this library have to agree about what a value changing looks like.
+ *
+ * Angles are degrees clockwise from twelve o'clock, as below.
+ */
+export declare function ringPath(cx: number, cy: number, radius: number, from: number, to: number): string;
+/**
+ * A slice of a ring, as a path.
+ *
+ * `inner` of 0 is a pie and anything above it is a donut. Angles are degrees
+ * clockwise from twelve o'clock, which is where a reader starts reading a
+ * circle — SVG's own zero is at three o'clock, and the offset is applied here
+ * once rather than at four call sites.
+ */
+export declare function arcPath(cx: number, cy: number, outer: number, inner: number, from: number, to: number): string;
+/** Which way a magnitude is coloured. */
+export type ChartScaleKind = 'sequential' | 'diverging';
+/** How many steps each ramp has. Five, and the reason is in `styles.css`. */
+export declare const rampSteps = 5;
+/**
+ * The step a value lands on, and the ink a label on it wears.
+ *
+ * A magnitude is not an identity, so it does not come off the eight-slot
+ * categorical ramp — see the note above `--plass-chart-seq-1`. It comes off a
+ * one-hue ladder, and which rung is arithmetic on the value.
+ *
+ * A diverging scale is read from its *middle* rather than from its bottom, so
+ * it is the distance either side of the neutral that is scaled — and by the
+ * larger of the two arms, so a set running from −2 to +40 does not paint every
+ * negative the deepest blue there is.
+ */
+export declare function rampStep(value: number, min: number, max: number, kind: ChartScaleKind, midpoint?: number): number;
+/** The `var()` for a step of the ramp, and for the ink that reads on it. */
+export declare function rampFill(step: number, kind: ChartScaleKind): string;
+export declare function rampInk(step: number, kind: ChartScaleKind): string;
+/** One tile, in pixels, and which value it came from. */
+export interface TreemapTile {
+    index: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A squarified treemap: the values as boxes whose areas are proportional, laid
+ * out as close to square as they can be got.
+ *
+ * Squarified rather than sliced, and the difference is the whole reason the
+ * forty lines are worth it. A slice-and-dice treemap of twenty values ends in
+ * slivers a pixel wide, and a sliver's *area* is unreadable however exact it is
+ * — the reader compares its length instead, which is not the encoded quantity.
+ * Bruls, Huizing and van Wijk's answer is greedy and simple: fill a row along
+ * the box's shorter side, keep adding to it while the worst aspect ratio in it
+ * improves, and start a new row the moment it stops.
+ *
+ * The order is the caller's; the layout sorts descending internally because the
+ * algorithm needs it and hands the original index back on every tile, so a
+ * tile's colour and its name are still its own.
+ */
+export declare function squarify(values: readonly number[], width: number, height: number): TreemapTile[];
+/**
+ * How a category is written when nobody said.
+ *
+ * A `Date` gets the reader's own short form, because the alternative is an ISO
+ * string across the bottom of every time series. Everything else is `String`,
+ * which is what the caller wrote it as.
+ */
+export declare function formatCategory(value: PlassChartCategory, locale?: string): string;
+/**
+ * A number, compactly enough that a y-axis of thousands is not four labels of
+ * seven characters.
+ *
+ * Only when the caller passed no `format` of their own — the moment they do,
+ * they have said what the number means and the library's opinion about
+ * thousands separators stops being welcome.
+ */
+export declare function compactNumber(value: number, locale?: string): string;

package/dist/internal/chart.js

@@ -0,0 +1 @@
+import{dateFormatter as t,numberFormatter as e}from"./format.js";export const plotHeights={xs:120,sm:160,md:220,lg:280,xl:360};export const sparklineHeights={xs:16,sm:20,md:28,lg:40,xl:56};export const lineWidths={xs:1.5,sm:1.75,md:2,lg:2.25,xl:2.5};export const markerRadii={xs:3,sm:3.5,md:4,lg:4.5,xl:5};export const chartFontSizes={xs:10,sm:11,md:12,lg:13,xl:14};export const barMaxThickness={xs:14,sm:18,md:24,lg:30,xl:36};export const barBandRatio={default:.62,compact:.82};export const markGap=2;export const barRadius=4;export const chartPalette=["var(--plass-chart-1)","var(--plass-chart-2)","var(--plass-chart-3)","var(--plass-chart-4)","var(--plass-chart-5)","var(--plass-chart-6)","var(--plass-chart-7)","var(--plass-chart-8)"];const n=new Set(["primary","secondary","success","warning","danger","info"]);export function resolveColor(t){return n.has(t)?`var(--plass-${t}-accent)`:t}export function seriesColor(t,e,n=chartPalette){return resolveColor(t?.color?t.color:n[e%n.length]??chartPalette[0])}export function toValue(t){return null==t?{value:null}:"number"==typeof t?{value:Number.isFinite(t)?t:null}:(t=>"object"==typeof t&&null!==t)(t)?{value:null!==t.y&&Number.isFinite(t.y)?t.y:null,x:t.x,z:t.z,color:t.color?resolveColor(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 pointX(t,e,n){return toNumber(t.x??n?.[e]??e)}export function categoryExtent(t,e){let n=1/0,r=-1/0,o=!1;return t.forEach(t=>{t.forEach((t,a)=>{if(null===t.value)return;const i=pointX(t,a,e);null!==i&&(o=!0,n=Math.min(n,i),r=Math.max(r,i))})}),o?{min:n,max:r}:null}export function bubbleRadius(t,e,n,r){return e>0&&Number.isFinite(t)&&!(t<=0)?Math.max(r,Math.sqrt(Math.min(t,e)/e)*n):0===t?0:r}export function categoryCount(t){return t.reduce((t,e)=>Math.max(t,e.data.length),0)}export function categoryAt(t,e,n){if(e&&t<e.length)return e[t];for(const e of n){const n=e[t]?.x;if(void 0!==n)return n}return t}export function extentOf(t,e){let n=1/0,r=-1/0,o=!1;if(e){const e=t.reduce((t,e)=>Math.max(t,e.length),0);for(let a=0;a<e;a++){let e=0,i=0;for(const n of t){const t=n[a]?.value;null!=t&&(o=!0,t>=0?e+=t:i+=t)}n=Math.min(n,i),r=Math.max(r,e)}}else for(const e of t)for(const{value:t}of e)null!==t&&(o=!0,n=Math.min(n,t),r=Math.max(r,t));return o?{min:n,max:r}:null}function niceStep(t){const e=10**Math.floor(Math.log10(t)),n=t/e;return n<=1?e:n<=2?2*e:n<=5?5*e:10*e}export function valueScale(t,e={}){const{tickCount:n=5,includeZero:r=!0}=e;let o=e.min??(t?t.min:0),a=e.max??(t?t.max:1);if(r&&void 0===e.min&&(o=Math.min(o,0)),r&&void 0===e.max&&(a=Math.max(a,0)),a===o){const t=Math.abs(a)>0?.5*Math.abs(a):1;o-=t,a+=t}const i=void 0!==e.min&&void 0!==e.max?function dividingStep(t,e){const n=10**Math.floor(Math.log10(t/Math.max(1,e)));let r=niceStep(t/Math.max(1,e)),o=1/0;for(const a of[.1,1,10])for(const i of[1,2,2.5,5]){const u=i*a*n,s=t/u,c=Math.round(s);if(c<1||Math.abs(s-c)>1e-9)continue;const l=Math.abs(c-e);l<o&&(o=l,r=u)}return r}(a-o,n):niceStep((a-o)/Math.max(1,n)),u=void 0!==e.min?o:Math.floor(o/i)*i,s=void 0!==e.max?a:Math.ceil(a/i)*i,c=s-u||1,l=[];for(let t=u;t<=s+1e-9*i;t+=i)l.push(Number(t.toFixed(12)));return{min:u,max:s,ticks:l,fraction:t=>(t-u)/c}}const r=1e3,o=6e4,a=36e5,i=24*a,u=[{unit:"second",count:1,size:r},{unit:"second",count:5,size:5e3},{unit:"second",count:15,size:15e3},{unit:"second",count:30,size:3e4},{unit:"minute",count:1,size:o},{unit:"minute",count:5,size:3e5},{unit:"minute",count:15,size:9e5},{unit:"minute",count:30,size:18e5},{unit:"hour",count:1,size:a},{unit:"hour",count:3,size:3*a},{unit:"hour",count:6,size:6*a},{unit:"hour",count:12,size:12*a},{unit:"day",count:1,size:i},{unit:"day",count:2,size:2*i},{unit:"week",count:1,size:7*i},{unit:"week",count:2,size:14*i},{unit:"month",count:1,size:30*i},{unit:"quarter",count:1,size:91*i},{unit:"month",count:6,size:182*i},{unit:"year",count:1,size:365*i}];function addTime(t,e,n){const a=new Date(t);if("year"===e)a.setFullYear(a.getFullYear()+n);else if("quarter"===e)a.setMonth(a.getMonth()+3*n);else if("month"===e)a.setMonth(a.getMonth()+n);else if("week"===e)a.setDate(a.getDate()+7*n);else if("day"===e)a.setDate(a.getDate()+n);else{if("hour"!==e)return t+n*("minute"===e?o:r);a.setHours(a.getHours()+n)}return a.getTime()}const s={second:"minute",minute:"hour",hour:"day",day:"month",week:"week",month:"year",quarter:"year",year:"year"};export function timeScale(t,e={}){const{tickCount:n=6}=e;let a=e.min??t?.min??Date.parse("2000-01-01T00:00:00"),c=e.max??t?.max??a+i;c<=a&&(a-=i/2,c+=i/2);const l=c-a;let h=u[0],m=1/0;for(const t of u){const e=Math.abs(l/t.size-n);e<m&&(m=e,h=t)}const $=h.unit,f="year"===$?Math.max(1,Math.round(niceStep(l/n/(365*i)))):h.count,x=e.min??function alignTime(t,e,n){let a=function floorTime(t,e){const n=new Date(t);if("year"===e)return new Date(n.getFullYear(),0,1).getTime();if("quarter"===e)return new Date(n.getFullYear(),3*Math.floor(n.getMonth()/3),1).getTime();if("month"===e)return new Date(n.getFullYear(),n.getMonth(),1).getTime();if("week"===e){const t=new Date(n.getFullYear(),n.getMonth(),n.getDate());return t.setDate(t.getDate()-t.getDay()),t.getTime()}return"day"===e?new Date(n.getFullYear(),n.getMonth(),n.getDate()).getTime():"hour"===e?new Date(n.getFullYear(),n.getMonth(),n.getDate(),n.getHours()).getTime():"minute"===e?Math.floor(t/o)*o:Math.floor(t/r)*r}(t,s[e]);if("year"===e&&n>1){const t=new Date(a).getFullYear();a=new Date(t-(t%n+n)%n,0,1).getTime()}for(let r=0;r<500;r++){const r=addTime(a,e,n);if(r>t)return a;a=r}return a}(a,$,f),p=[];let M=x;for(let t=0;t<500&&(p.push(M),!(M>c));t++)M=addTime(M,$,f);const g=e.max??p[p.length-1],d=g-x||1;return{min:x,max:g,ticks:p.filter(t=>t>=x&&t<=g),unit:$,step:f,fraction:t=>(t-x)/d}}function timeParts(t,e){if("second"===t)return{hour:"2-digit",minute:"2-digit",second:"2-digit",hourCycle:"h23"};if("minute"===t||"hour"===t)return{hour:"2-digit",minute:"2-digit",hourCycle:"h23"};if("year"===t)return{year:"numeric"};const n="month"===t||"quarter"===t?{month:"short"}:{month:"short",day:"numeric"};return e?{...n,year:"numeric"}:n}export function formatTimeValue(e,n,r){return t(r,timeParts(n,!0)).format(new Date(e))}export function formatTimeTicks(e,n,r){const o=new Set(e.map(t=>new Date(t).getFullYear())).size>1;return e.map((e,a)=>t(r,timeParts(n,o||0===a)).format(new Date(e)))}export function tickStride(t,e,n){if(t<=1||e<=0)return 1;const r=Math.max(1,Math.floor(e/Math.max(1,n)));return Math.max(1,Math.ceil(t/r))}export function showsTick(t,e,n,r){return t%n===0||r&&t===e-1}export function fitsLast(t,e,n,r){const o=(t-1)%e;return o>0&&o*n>=r+8}export function textWidth(t,e){let n=0;for(const e of t)n+=/[ᄀ-ᇿ⺀-꓏가-퟿豈-﫿︰-﹏]/.test(e)?1:.6;return n*e}export function truncate(t,e,n){if(e<=0||textWidth(t,n)<=e)return t;const r=e-textWidth("…",n);let o="",a=0;for(const e of t){const t=a+textWidth(e,n);if(t>r)break;a=t,o+=e}return o.length>0?`${o.trimEnd()}…`:"…"}export function bandScale(t,e,n){const r=t>0?e/t:e;return{step:r,band:r*n,centre:t=>r*(t+.5)}}export function linePath(t,e){const n=[];let r=[];const flush=()=>{if(0!==r.length){if(1===r.length)n.push(`M${r[0].x} ${r[0].y}h0`);else if("step"===e){n.push(`M${r[0].x} ${r[0].y}`);for(let t=1;t<r.length;t++){const e=(r[t-1].x+r[t].x)/2;n.push(`H${e}V${r[t].y}H${r[t].x}`)}}else if("smooth"===e)n.push(`M${r[0].x} ${r[0].y}`),n.push(function monotonePath(t){const e=t.length,n=[];for(let r=0;r<e-1;r++){const e=t[r+1].x-t[r].x;n.push(0===e?0:(t[r+1].y-t[r].y)/e)}const r=[n[0]??0];for(let t=1;t<e-1;t++){const e=n[t-1],o=n[t];r.push(e*o<=0?0:2*e*o/(e+o))}r.push(n[e-2]??0);const o=[];for(let n=0;n<e-1;n++){const e=(t[n+1].x-t[n].x)/3;o.push(`C${t[n].x+e} ${t[n].y+r[n]*e} ${t[n+1].x-e} ${t[n+1].y-r[n+1]*e} ${t[n+1].x} ${t[n+1].y}`)}return o.join("")}(r));else{n.push(`M${r[0].x} ${r[0].y}`);for(let t=1;t<r.length;t++)n.push(`L${r[t].x} ${r[t].y}`)}r=[]}};for(const e of t)null===e?flush():r.push(e);return flush(),n.join("")}export function areaPath(t,e,n){const r=[];let o=0;const flush=a=>{const i=t.slice(o,a).filter(Boolean);if(0===i.length)return;const u="number"==typeof e?i.map(t=>({x:t.x,y:e})).reverse():e.slice(o,a).filter(Boolean).reverse();if(0===u.length)return;const s=linePath(i,n),c=linePath(u,n).replace(/^M/,"L");r.push(`${s}${c}Z`)};for(let e=0;e<t.length;e++)null===t[e]&&(flush(e),o=e+1);return flush(t.length),r.join("")}export function barPath(t,e,n,r,o,a){const i=Math.max(0,Math.min(o,n/2,r/2));if(0===i||n<=0||r<=0)return`M${t} ${e}h${n}v${r}h${-n}Z`;const arc=(t,e)=>`a${i} ${i} 0 0 1 ${t} ${e}`;return"up"===a?`M${t} ${e+r}V${e+i}${arc(i,-i)}H${t+n-i}${arc(i,i)}V${e+r}Z`:"down"===a?`M${t} ${e}H${t+n}V${e+r-i}${arc(-i,i)}H${t+i}${arc(-i,-i)}Z`:"right"===a?`M${t} ${e}H${t+n-i}${arc(i,i)}V${e+r-i}${arc(-i,i)}H${t}Z`:`M${t+n} ${e+r}H${t+i}${arc(-i,-i)}V${e+i}${arc(i,-i)}H${t+n}Z`}export const markShapes=["circle","square","triangle","diamond","cross"];const c={circle:1,square:.8862,triangle:1.5551,diamond:1.2533,cross:1.189};export function markPath(t,e,n,r){const o=Math.max(0,r)*c[t];if(0===o)return"";if("circle"===t)return`M${e-o} ${n}a${o} ${o} 0 1 0 ${2*o} 0a${o} ${o} 0 1 0 ${2*-o} 0Z`;if("square"===t)return`M${e-o} ${n-o}h${2*o}v${2*o}h${2*-o}Z`;if("diamond"===t)return`M${e} ${n-o}L${e+o} ${n}L${e} ${n+o}L${e-o} ${n}Z`;if("triangle"===t)return`M${[0,120,240].map(t=>{const r=(t-90)*Math.PI/180;return`${e+o*Math.cos(r)} ${n+o*Math.sin(r)}`}).join("L")}Z`;const a=o/3;return`M${e-a} ${n-o}h${2*a}v${o-a}h${o-a}v${2*a}h${-(o-a)}v${o-a}h${2*-a}v${-(o-a)}h${-(o-a)}v${2*-a}h${o-a}Z`}export function ringPath(t,e,n,r,o){const point=r=>{const o=(r-90)*Math.PI/180;return`${t+n*Math.cos(o)} ${e+n*Math.sin(o)}`};if(Math.abs(o-r)>=360){const t=r+180;return`M${point(r)}A${n} ${n} 0 1 1 ${point(t)}A${n} ${n} 0 1 1 ${point(r)}`}const a=Math.abs(o-r)>180?1:0;return`M${point(r)}A${n} ${n} 0 ${a} 1 ${point(o)}`}export function arcPath(t,e,n,r,o,a){const point=(n,r)=>{const o=(r-90)*Math.PI/180;return`${t+n*Math.cos(o)} ${e+n*Math.sin(o)}`};if(Math.abs(a-o)>=360){const t=o+180;return r>0?`M${point(n,o)}A${n} ${n} 0 1 1 ${point(n,t)}A${n} ${n} 0 1 1 ${point(n,o)}ZM${point(r,o)}A${r} ${r} 0 1 0 ${point(r,t)}A${r} ${r} 0 1 0 ${point(r,o)}Z`:`M${point(n,o)}A${n} ${n} 0 1 1 ${point(n,t)}A${n} ${n} 0 1 1 ${point(n,o)}Z`}const i=Math.abs(a-o)>180?1:0;return r<=0?`M${t} ${e}L${point(n,o)}A${n} ${n} 0 ${i} 1 ${point(n,a)}Z`:`M${point(n,o)}A${n} ${n} 0 ${i} 1 ${point(n,a)}L${point(r,a)}A${r} ${r} 0 ${i} 0 ${point(r,o)}Z`}export const rampSteps=5;export function rampStep(t,e,n,r,o=0){if("diverging"===r){const r=Math.max(Math.abs(n-o),Math.abs(o-e));if(!(r>0))return 2;const a=(t-o)/r;return Math.min(4,Math.max(0,2+Math.round(2*a)))}const a=n-e;return a>0?Math.min(4,Math.max(0,Math.floor((t-e)/a*5))):4}export function rampFill(t,e){return`var(--plass-chart-${"diverging"===e?"div":"seq"}-${t+1})`}export function rampInk(t,e){return`var(--plass-chart-${"diverging"===e?"div":"seq"}-on-${t+1})`}export function squarify(t,e,n){const r=t.reduce((t,e)=>t+Math.max(0,e),0);if(!(r>0)||e<=0||n<=0)return[];const o=e*n/r,a=t.map((t,e)=>({index:e,area:Math.max(0,t)*o})).filter(t=>t.area>0).sort((t,e)=>e.area-t.area),i=[];let u=0,s=0,c=e,l=n,h=[];const worst=t=>{const e=Math.min(c,l),n=t.reduce((t,e)=>t+e.area,0);if(!(n>0&&e>0))return 1/0;const r=t[0].area,o=t[t.length-1].area;return Math.max(e*e*r/(n*n),n*n/(e*e*o))},place=()=>{const t=h.reduce((t,e)=>t+e.area,0),e=Math.min(c,l),n=e>0?t/e:0,r=c>=l;let o=0;for(const t of h){const e=n>0?t.area/n:0;i.push(r?{index:t.index,x:u,y:s+o,width:n,height:e}:{index:t.index,x:u+o,y:s,width:e,height:n}),o+=e}r?(u+=n,c-=n):(s+=n,l-=n),h=[]};for(const t of a)0===h.length||worst([...h,t])<=worst(h)||place(),h.push(t);return h.length>0&&place(),i}const l={month:"short",day:"numeric"},h={notation:"compact",maximumFractionDigits:1},m={maximumFractionDigits:2};export function formatCategory(e,n){return e instanceof Date?t(n,l).format(e):String(e)}export function compactNumber(t,n){return Math.abs(t)>=1e4?e(n,h).format(t):e(n,m).format(t)}

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

@@ -0,0 +1,23 @@
+/** What the reader chose. `system` is the absence of a choice, not a third theme. */
+export type PlColorScheme = 'light' | 'dark' | 'system';
+/** What the page is actually painted in, once `system` has been resolved. */
+export type PlResolvedColorScheme = 'light' | 'dark';
+export declare const DEFAULT_STORAGE_KEY = "plass-color-scheme";
+export declare const darkQuery = "(prefers-color-scheme: dark)";
+/**
+ * Writes the choice onto `<html>`.
+ *
+ * **Both** the attribute and the class, and not as belt and braces: the
+ * attribute is what this library's tokens read, and the class is what a
+ * consumer's own Tailwind `dark:` utilities read when they are configured
+ * against a class rather than the media query. A toggle that moved one and not
+ * the other would leave a page half switched.
+ *
+ * `system` removes both, which is not the same as writing `light`: it hands the
+ * question back to `prefers-color-scheme`, so the page follows the platform
+ * again rather than being pinned to the platform's current answer.
+ */
+export declare function applyColorScheme(scheme: PlColorScheme): void;
+/** Whatever was stored, if it is one of the three. */
+export declare function readStoredScheme(key: string): PlColorScheme | null;
+export declare function useColorSchemeStore(key: string, fallback: PlColorScheme): [PlColorScheme, (next: PlColorScheme) => void];

package/dist/internal/color-scheme.js

@@ -0,0 +1 @@
+"use client";import*as e from"react";export const DEFAULT_STORAGE_KEY="plass-color-scheme";export const darkQuery="(prefers-color-scheme: dark)";export function applyColorScheme(e){if("undefined"==typeof document)return;const t=document.documentElement;t.classList.remove("light","dark"),"system"!==e?(t.dataset.theme=e,t.classList.add(e)):delete t.dataset.theme}export function readStoredScheme(e){if("undefined"==typeof localStorage)return null;try{const t=localStorage.getItem(e);return"light"===t||"dark"===t||"system"===t?t:null}catch{return null}}const t=new Map;function storeFor(e,r){let o=t.get(e);return o||(o={scheme:readStoredScheme(e)??r,listeners:new Set},t.set(e,o)),o}export function useColorSchemeStore(t,r){const o=e.useCallback(e=>{const o=storeFor(t,r);o.listeners.add(e);const onStorage=e=>{if(e.key!==t)return;const s=readStoredScheme(t)??r;s!==o.scheme&&(o.scheme=s,applyColorScheme(s),o.listeners.forEach(e=>e()))};return window.addEventListener("storage",onStorage),()=>{o.listeners.delete(e),window.removeEventListener("storage",onStorage)}},[t,r]),s=e.useCallback(()=>storeFor(t,r).scheme,[t,r]),n=e.useCallback(()=>r,[r]),c=e.useSyncExternalStore(o,s,n),l=e.useCallback(e=>{const o=storeFor(t,r);o.scheme=e,function writeStoredScheme(e,t){try{localStorage.setItem(e,t)}catch{}}(t,e),applyColorScheme(e),o.listeners.forEach(e=>e())},[t,r]);return[c,l]}

package/dist/internal/data-table.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The arithmetic a data table does before it draws anything.
+ *
+ * Sorting, paging and range selection are decisions about values rather than
+ * about the DOM, so they are here as plain functions: they can be read without
+ * a browser, tested without one, and — the reason that matters — they are the
+ * same three answers the Flutter build gives, which is what keeps a table
+ * sorted one way on the web from being sorted another way in an app.
+ */
+import type * as React from 'react';
+/** Which way a column runs when it is sorted. */
+export type PlassSortDirection = 'asc' | 'desc';
+/** A column and the direction it is sorted in. */
+export interface PlassSort {
+    /** The column's `key`. */
+    key: string;
+    /** Which way it runs. */
+    direction: PlassSortDirection;
+}
+/**
+ * Puts two cell values in order.
+ *
+ * Numbers and dates compare as themselves, strings compare the way the reader's
+ * language orders them, and everything else falls back to its text. Two rules
+ * carry the weight:
+ *
+ * **Nothing sorts last, in both directions.** A column of amounts with three
+ * blanks in it is a column whose blanks are not the smallest amounts, and a
+ * reader who reversed the sort to find the largest should not be handed the
+ * empty ones instead. So the answer for a missing value is decided here, before
+ * the direction is applied, and the caller flips only the rest.
+ *
+ * **Strings compare with `localeCompare`.** `'a' < 'B'` is false by code point,
+ * which puts every capitalised word above every lower-case one and sorts `Ösi`
+ * after `Zoe`. A list of names a reader cannot scan is a list that was sorted
+ * for the machine.
+ */
+export declare function compareValues(a: unknown, b: unknown): number;
+/**
+ * What pressing a column heading does next.
+ *
+ * Ascending, then descending, then **off** — a third press puts the rows back
+ * in the order they arrived in. That order is information: it is usually the
+ * order the server chose, and a table that can never be put back has thrown it
+ * away. Pressing a different column starts that column ascending rather than
+ * inheriting the direction of the one before it.
+ */
+export declare function nextSort(current: PlassSort | null, key: string): PlassSort | null;
+/**
+ * The keys of every row between two of them, inclusive, in the order the rows
+ * are currently in.
+ *
+ * What a shift-click ticks. "Currently in" is the point: a reader dragging a
+ * range down a sorted table means the rows they can see, not the rows the
+ * unsorted array happens to hold between those two indices.
+ *
+ * An unknown key selects nothing rather than throwing, because the anchor can
+ * legitimately have been filtered away between the two clicks.
+ */
+export declare function keysBetween(keys: readonly React.Key[], from: React.Key, to: React.Key): React.Key[];
+/**
+ * Which rows a page shows, as a `[start, end)` pair into the sorted set.
+ *
+ * Clamped rather than trusted: a page number that has gone past the end — the
+ * usual way being a filter that shortened the list under a reader sitting on
+ * page nine — shows the last page instead of an empty table with a pager that
+ * says there is something there.
+ */
+export declare function pageBounds(total: number, page: number, pageSize: number): [number, number];

package/dist/internal/data-table.js

@@ -0,0 +1 @@
+export function compareValues(e,n){const t=null==e||""===e,o=null==n||""===n;return t||o?t&&o?0:t?1:-1:"number"==typeof e&&"number"==typeof n?e-n:"boolean"==typeof e&&"boolean"==typeof n?Number(e)-Number(n):e instanceof Date&&n instanceof Date?e.getTime()-n.getTime():String(e).localeCompare(String(n))}export function nextSort(e,n){return null===e||e.key!==n?{key:n,direction:"asc"}:"asc"===e.direction?{key:n,direction:"desc"}:null}export function keysBetween(e,n,t){const o=e.indexOf(n),r=e.indexOf(t);return-1===o||-1===r?[]:o<=r?e.slice(o,r+1):e.slice(r,o+1)}export function pageBounds(e,n,t){const o=Math.max(1,Math.ceil(e/t)),r=(Math.min(Math.max(1,Math.trunc(n)),o)-1)*t;return[r,Math.min(r+t,e)]}

package/dist/internal/date.d.ts

@@ -48,6 +48,8 @@ export declare function isValidDate(value: unknown): value is Date;
 export declare function startOfDay(date: Date): Date;
 /** The first day of the month this date is in, at midnight. */
 export declare function startOfMonth(date: Date): Date;
+/** The 1st of January of the year this date is in, at midnight. */
+export declare function startOfYear(date: Date): Date;
 /** How many days a month has, leap years included. */
 export declare function daysInMonth(year: number, month: number): number;
 /** Today, at midnight. The one place the pickers read the clock for a *date*. */
@@ -77,6 +79,18 @@ export declare function clampDate(date: Date, min?: Date | null, max?: Date | nu
  * once an hour has been chosen.
  */
 export declare function isDayOutside(date: Date, min?: Date | null, max?: Date | null): boolean;
+/**
+ * Is *every* day of this month outside the allowed span?
+ *
+ * A month is unreachable only when nothing in it is reachable: the month a
+ * `minDate` of the 15th falls in still exists, it just starts late. That is the
+ * rule the month grid has always drawn, and it is also what a `month` picker
+ * reads its bounds at — a bound on a picker that returns a month is a bound on
+ * months.
+ */
+export declare function isMonthOutside(date: Date, min?: Date | null, max?: Date | null): boolean;
+/** The same question about a whole year, for a `year` picker. */
+export declare function isYearOutside(date: Date, min?: Date | null, max?: Date | null): boolean;
 /** Seconds since local midnight — what `minTime`/`maxTime` are compared on. */
 export declare function secondsOfDay(date: Date): number;
 /** Which column of a clock a candidate time is being offered for. */
@@ -143,6 +157,13 @@ export declare function withPlaceholder(samples: string[], placeholder: unknown)
  * server that already parses those needs no new code.
  */
 export declare function toISODate(date: Date): string;
+/**
+ * The two shorter spellings, for a picker that only asked for a month or a
+ * year. `YYYY-MM` is what the native `<input type="month">` submits; there is no
+ * native control that submits a year, so a year is just the year.
+ */
+export declare function toISOMonth(date: Date): string;
+export declare function toISOYear(date: Date): string;
 export declare function toISOTime(date: Date, withSeconds?: boolean): string;
 export declare function toISODateTime(date: Date, withSeconds?: boolean): string;
 /**