neba 1.3.0 → 1.5.0

package/dist/internal/chart.d.ts

@@ -0,0 +1,456 @@
+/**
+ * The arithmetic every chart is made of.
+ *
+ * Here rather than in a component for the reason `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; `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 — and the package still has
+ * one runtime dependency, which is the same trade `color.ts` makes.
+ */
+import type * as React from 'react';
+import type { NebaChartCategory, NebaChartDatum, NebaChartSeries, NebaDensity, NebaSize } from '../types';
+/**
+ * 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<NebaSize, number>;
+/**
+ * A Sparkline'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<NebaSize, 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<NebaSize, 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<NebaSize, 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<NebaSize, 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<NebaSize, 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<NebaDensity, 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 `NebaColor` 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<NebaChartSeries, '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?: NebaChartCategory;
+    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: NebaChartDatum): ChartValue;
+/** Every series unpacked, in the order it was given. */
+export declare function toValues(series: readonly NebaChartSeries[]): 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: NebaChartCategory | 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 NebaChartCategory[] | 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 NebaChartCategory[] | 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 NebaChartSeries[]): 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 NebaChartCategory[] | undefined, values: readonly ChartValue[][]): NebaChartCategory;
+/**
+ * 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;
+/**
+ * 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 `--neba-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: NebaChartCategory, 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";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(--neba-chart-1)","var(--neba-chart-2)","var(--neba-chart-3)","var(--neba-chart-4)","var(--neba-chart-5)","var(--neba-chart-6)","var(--neba-chart-7)","var(--neba-chart-8)"];const n=new Set(["primary","secondary","success","warning","danger","info"]);export function resolveColor(t){return n.has(t)?`var(--neba-${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 r(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:o=!0}=e;let a=e.min??(t?t.min:0),i=e.max??(t?t.max:1);if(o&&void 0===e.min&&(a=Math.min(a,0)),o&&void 0===e.max&&(i=Math.max(i,0)),i===a){const t=Math.abs(i)>0?.5*Math.abs(i):1;a-=t,i+=t}const u=void 0!==e.min&&void 0!==e.max?function(t,e){const n=10**Math.floor(Math.log10(t/Math.max(1,e)));let o=r(t/Math.max(1,e)),a=1/0;for(const r of[.1,1,10])for(const i of[1,2,2.5,5]){const u=i*r*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<a&&(a=l,o=u)}return o}(i-a,n):r((i-a)/Math.max(1,n)),s=void 0!==e.min?a:Math.floor(a/u)*u,c=void 0!==e.max?i:Math.ceil(i/u)*u,l=c-s||1,h=[];for(let t=s;t<=c+1e-9*u;t+=u)h.push(Number(t.toFixed(12)));return{min:s,max:c,ticks:h,fraction:t=>(t-s)/l}}const o=1e3,a=6e4,i=36e5,u=24*i,s=[{unit:"second",count:1,size:o},{unit:"second",count:5,size:5e3},{unit:"second",count:15,size:15e3},{unit:"second",count:30,size:3e4},{unit:"minute",count:1,size:a},{unit:"minute",count:5,size:3e5},{unit:"minute",count:15,size:9e5},{unit:"minute",count:30,size:18e5},{unit:"hour",count:1,size:i},{unit:"hour",count:3,size:3*i},{unit:"hour",count:6,size:6*i},{unit:"hour",count:12,size:12*i},{unit:"day",count:1,size:u},{unit:"day",count:2,size:2*u},{unit:"week",count:1,size:7*u},{unit:"week",count:2,size:14*u},{unit:"month",count:1,size:30*u},{unit:"quarter",count:1,size:91*u},{unit:"month",count:6,size:182*u},{unit:"year",count:1,size:365*u}];function c(t,e,n){const r=new Date(t);if("year"===e)r.setFullYear(r.getFullYear()+n);else if("quarter"===e)r.setMonth(r.getMonth()+3*n);else if("month"===e)r.setMonth(r.getMonth()+n);else if("week"===e)r.setDate(r.getDate()+7*n);else if("day"===e)r.setDate(r.getDate()+n);else{if("hour"!==e)return t+n*("minute"===e?a:o);r.setHours(r.getHours()+n)}return r.getTime()}const l={second:"minute",minute:"hour",hour:"day",day:"month",week:"week",month:"year",quarter:"year",year:"year"};function h(t,e,n){let r=function(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/a)*a:Math.floor(t/o)*o}(t,l[e]);if("year"===e&&n>1){const t=new Date(r).getFullYear();r=new Date(t-(t%n+n)%n,0,1).getTime()}for(let o=0;o<500;o++){const o=c(r,e,n);if(o>t)return r;r=o}return r}export function timeScale(t,e={}){const{tickCount:n=6}=e;let o=e.min??t?.min??Date.parse("2000-01-01T00:00:00"),a=e.max??t?.max??o+u;a<=o&&(o-=u/2,a+=u/2);const i=a-o;let l=s[0],m=1/0;for(const t of s){const e=Math.abs(i/t.size-n);e<m&&(m=e,l=t)}const f=l.unit,$="year"===f?Math.max(1,Math.round(r(i/n/(365*u)))):l.count,x=e.min??h(o,f,$),p=[];let M=x;for(let t=0;t<500&&(p.push(M),!(M>a));t++)M=c(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:f,step:$,fraction:t=>(t-x)/d}}function m(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,m(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,m(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 o=()=>{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(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?o():r.push(e);return o(),n.join("")}export function areaPath(t,e,n){const r=[];let o=0;const a=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]&&(a(e),o=e+1);return a(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 u=(t,e)=>`a${i} ${i} 0 0 1 ${t} ${e}`;return"up"===a?`M${t} ${e+r}V${e+i}${u(i,-i)}H${t+n-i}${u(i,i)}V${e+r}Z`:"down"===a?`M${t} ${e}H${t+n}V${e+r-i}${u(-i,i)}H${t+i}${u(-i,-i)}Z`:"right"===a?`M${t} ${e}H${t+n-i}${u(i,i)}V${e+r-i}${u(-i,i)}H${t}Z`:`M${t+n} ${e+r}H${t+i}${u(-i,-i)}V${e+i}${u(i,-i)}H${t+n}Z`}export const markShapes=["circle","square","triangle","diamond","cross"];const f={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)*f[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 arcPath(t,e,n,r,o,a){const i=(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${i(n,o)}A${n} ${n} 0 1 1 ${i(n,t)}A${n} ${n} 0 1 1 ${i(n,o)}ZM${i(r,o)}A${r} ${r} 0 1 0 ${i(r,t)}A${r} ${r} 0 1 0 ${i(r,o)}Z`:`M${i(n,o)}A${n} ${n} 0 1 1 ${i(n,t)}A${n} ${n} 0 1 1 ${i(n,o)}Z`}const u=Math.abs(a-o)>180?1:0;return r<=0?`M${t} ${e}L${i(n,o)}A${n} ${n} 0 ${u} 1 ${i(n,a)}Z`:`M${i(n,o)}A${n} ${n} 0 ${u} 1 ${i(n,a)}L${i(r,a)}A${r} ${r} 0 ${u} 0 ${i(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(--neba-chart-${"diverging"===e?"div":"seq"}-${t+1})`}export function rampInk(t,e){return`var(--neba-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 m=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))},f=()=>{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||m([...h,t])<=m(h)||f(),h.push(t);return h.length>0&&f(),i}const $={month:"short",day:"numeric"},x={notation:"compact",maximumFractionDigits:1},p={maximumFractionDigits:2};export function formatCategory(e,n){return e instanceof Date?t(n,$).format(e):String(e)}export function compactNumber(t,n){return Math.abs(t)>=1e4?e(n,x).format(t):e(n,p).format(t)}

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

@@ -0,0 +1,170 @@
+/**
+ * The arithmetic a DataTable is made of.
+ *
+ * Here rather than in the component for the reason `progress.ts` and `color.ts`
+ * are here: none of it is layout and none of it is a class name. Sorting rows,
+ * matching a query against them, cutting a page out of the result and working
+ * out which twenty of forty thousand rows are actually on screen are four
+ * questions with numeric answers, and a component file that also has to draw a
+ * resize handle is not where they can be read.
+ *
+ * `color.ts` is the precedent for a single-consumer file: the test is whether
+ * the thing is separable, not whether two components happen to want it. Every
+ * function below takes plain values and returns plain values — there is no
+ * React in this file, and nothing in it knows what a column is.
+ */
+import type { NebaDensity, NebaSize } from '../types';
+/**
+ * Row height, in **pixels**, and the one number in the library that has to be a
+ * number rather than a class.
+ *
+ * Virtual scrolling is arithmetic on this value: how far down the list a scroll
+ * offset lands, how tall the spacer above the first rendered row is, how many
+ * rows fit in the viewport for PageDown. A Tailwind class cannot be added up.
+ *
+ * The ladder is deliberately below `controlHeightClasses` at every step — 28px
+ * at `md` against a Button's 32 — because a DataTable is a hundred rows on one
+ * screen and a Table is eight. A row here is the height of the text plus enough
+ * air to click, and nothing more; `density` is what takes the last of the air
+ * out. A caller who puts a Chip or an Avatar in a cell raises `rowHeight`.
+ */
+export declare const dataRowHeights: Record<NebaDensity, Record<NebaSize, number>>;
+/**
+ * The header, one step taller than the rows under it.
+ *
+ * A fixed number rather than "whatever the content measures", because a sticky
+ * header over a group row needs an offset to stick the second row at, and a
+ * measured one would be a layout read on every scroll frame.
+ */
+export declare const dataHeaderHeights: Record<NebaDensity, Record<NebaSize, number>>;
+/**
+ * The tick column, and the resize handle's grab area.
+ *
+ * The tick column is `tickSizeClasses` plus the two padding tracks, rounded to
+ * a whole pixel: a column narrower than the box in it clips the focus ring.
+ */
+export declare const dataTickWidths: Record<NebaSize, number>;
+/** How wide a column is when neither the caller nor a drag has said. */
+export declare const defaultColumnWidth = 160;
+/** How narrow a drag may make one. Below this the heading is a single letter. */
+export declare const minColumnWidth = 48;
+export type SortDirection = 'asc' | 'desc';
+/** One key of a sort, and which way it runs. */
+export interface SortEntry {
+    key: string;
+    direction: SortDirection;
+}
+/**
+ * The default comparison, for the columns that do not bring one.
+ *
+ * Empty sorts last in both directions, which is the one asymmetry here and the
+ * one every spreadsheet has: a blank is not the smallest value, it is the
+ * absence of one, and a descending sort whose first screen is forty blanks has
+ * answered the wrong question.
+ *
+ * Numbers compare as numbers, dates as instants, booleans with `false` first,
+ * and everything else through the collator — which is `numeric`, so `item2`
+ * comes before `item10` rather than after it.
+ */
+export declare function compareValues(a: unknown, b: unknown, collator: Intl.Collator): number;
+/**
+ * Sorts by every key at once, first key outermost.
+ *
+ * The sort is **stable** — `Array.prototype.sort` has been since ES2019 — which
+ * is what makes a multi-key sort composable: sorting by name and then adding
+ * date to the end of the list leaves rows with the same date in name order,
+ * because that is the order they were already in.
+ *
+ * `comparatorFor` returns `null` for a key no column claims, so a sort left
+ * over from a column that has since been removed is skipped rather than
+ * throwing.
+ */
+export declare function sortRows<T>(rows: readonly T[], sort: readonly SortEntry[], comparatorFor: (key: string) => ((a: T, b: T) => number) | null): T[];
+/**
+ * What pressing a heading does, given what the sort already says.
+ *
+ * Three states rather than two — ascending, descending, unsorted — because the
+ * order the rows arrived in is a state a caller cannot get back to by pressing
+ * anything if the cycle only has two. This is the opposite of the choice
+ * TreeView's single select makes, and for the same reason: there, "nothing
+ * chosen" is reachable by pressing something else; here it is not.
+ *
+ * `additive` is what a Shift-click sets. It keeps the column where it already
+ * is in the list rather than moving it to the end, so flipping the second key
+ * of a two-key sort does not silently make it the first.
+ */
+export declare function nextSort(current: readonly SortEntry[], key: string, additive: boolean): SortEntry[];
+/**
+ * A cell value as something a query can be matched against.
+ *
+ * Case-folded and stripped of combining marks, so `jose` finds `José` and
+ * `SEOUL` finds `Seoul`. `NFD` splits an accented letter into the letter and
+ * its accent and the range then deletes the accent; a search field is the one
+ * place where losing that distinction is the point.
+ *
+ * A `Date` is deliberately *not* formatted here. What a reader sees in the cell
+ * came out of the caller's `render`, and guessing a format the search would
+ * agree with is how a table ends up not finding a date that is on the screen —
+ * a column that wants its dates searchable gives them a `value`.
+ */
+export declare function searchText(value: unknown): string;
+/** Where one page starts and stops, and how many there are. */
+export interface PageBounds {
+    /** How many pages the rows come to. Never below `1`. */
+    pages: number;
+    /** The page actually shown, clamped into range. */
+    page: number;
+    /** Index of the first row on it. */
+    start: number;
+    /** One past the last. */
+    end: number;
+}
+/**
+ * The page arithmetic, with the clamp in it.
+ *
+ * The clamp is the whole reason this is a function: a filter that cuts a
+ * twenty-page table to three leaves the caller's `page` at 14, and a table that
+ * answers with an empty screen has told the reader their search found nothing.
+ * The page moves to the last one that exists instead.
+ */
+export declare function pageBounds(total: number, page: number, pageSize: number): PageBounds;
+/** Which rows are rendered, and how much empty space stands in for the rest. */
+export interface VirtualWindow {
+    /** Index of the first row rendered. */
+    start: number;
+    /** One past the last. */
+    end: number;
+    /** The height of the spacer row above, in pixels. */
+    before: number;
+    /** And of the one below. */
+    after: number;
+}
+/**
+ * The rows a scroll offset puts on screen, plus a margin either side.
+ *
+ * Two spacer rows rather than a translated `<tbody>`: a transform on the body
+ * of a table breaks `position: sticky` on the header above it, and the library
+ * has a rule about transforms anyway. Padding is also what keeps the scrollbar
+ * honest — the scroll height is the real one, so dragging the thumb to the
+ * middle lands in the middle of the data.
+ *
+ * `viewport` of `0` is the first render, before anything has been measured. It
+ * cannot mean "no rows" — the layout effect that measures runs after a render
+ * and there would be nothing to measure — so it renders a screen's worth on
+ * spec and corrects before the frame is painted.
+ */
+export declare function virtualWindow(scrollTop: number, viewport: number, rowHeight: number, count: number, overscan: number): VirtualWindow;
+/**
+ * Every key between two, inclusive, in the order the rows are currently in.
+ *
+ * "Currently" is the point: a Shift-click selects what the reader can see
+ * between the two rows they clicked, so the range is taken from the sorted,
+ * filtered order rather than from the order `items` arrived in. Which of the
+ * two keys is the anchor does not matter — dragging up selects the same rows as
+ * dragging down.
+ *
+ * A key that is no longer in the list (a row the current filter hides) yields
+ * an empty range rather than a range from one end, which is what an index of
+ * `-1` would silently produce.
+ */
+export declare function keysBetween(order: readonly string[], from: string, to: string): string[];

package/dist/internal/data-table.js

@@ -0,0 +1 @@
+export const dataRowHeights={default:{xs:24,sm:28,md:32,lg:38,xl:44},compact:{xs:20,sm:24,md:28,lg:32,xl:38}};export const dataHeaderHeights={default:{xs:28,sm:32,md:36,lg:42,xl:48},compact:{xs:24,sm:28,md:32,lg:36,xl:42}};export const dataTickWidths={xs:30,sm:34,md:38,lg:42,xl:50};export const defaultColumnWidth=160;export const minColumnWidth=48;export function compareValues(t,e,n){const o=null==t||""===t,r=null==e||""===e;return o||r?o&&r?0:o?1:-1:"number"==typeof t&&"number"==typeof e?Number.isNaN(t)||Number.isNaN(e)?Number.isNaN(t)&&Number.isNaN(e)?0:Number.isNaN(t)?1:-1:t-e:"boolean"==typeof t&&"boolean"==typeof e?Number(t)-Number(e):t instanceof Date&&e instanceof Date?t.getTime()-e.getTime():n.compare(String(t),String(e))}export function sortRows(t,e,n){if(0===e.length)return t;const o=e.map(t=>{const e=n(t.key);return e?{compare:e,sign:"desc"===t.direction?-1:1}:null}).filter(t=>null!==t);return 0===o.length?t:[...t].sort((t,e)=>{for(const n of o){const o=n.compare(t,e);if(0!==o)return o*n.sign}return 0})}export function nextSort(t,e,n){const o=t.find(t=>t.key===e),r=void 0===o?"asc":"asc"===o.direction?"desc":null;return n?null===r?t.filter(t=>t.key!==e):void 0===o?[...t,{key:e,direction:r}]:t.map(t=>t.key===e?{key:e,direction:r}:t):null===r?[]:[{key:e,direction:r}]}export function searchText(t){return null==t||"object"==typeof t?"":String(t).normalize("NFD").replace(/[\u0300-\u036f]/g,"").toLowerCase()}export function pageBounds(t,e,n){const o=Math.max(1,Math.floor(n)),r=Math.max(1,Math.ceil(t/o)),a=Math.min(Math.max(Math.floor(e),1),r),i=(a-1)*o;return{pages:r,page:a,start:i,end:Math.min(i+o,t)}}export function virtualWindow(t,e,n,o,r){const a=e>0?Math.ceil(e/n):3*r,i=Math.max(0,Math.floor(t/n)-r),s=Math.min(o,i+a+2*r);return{start:i,end:s,before:i*n,after:Math.max(0,(o-s)*n)}}export function keysBetween(t,e,n){const o=t.indexOf(e),r=t.indexOf(n);return-1===o||-1===r?[]:t.slice(Math.min(o,r),Math.max(o,r)+1)}

package/dist/internal/date.d.ts

@@ -109,8 +109,6 @@ export declare function mergeDateAndTime(date: Date, time: Date): Date;
 export declare function calendarWeeks(month: Date, weekStartsOn: NebaWeekday): Date[][];
 /** The first year on the page a given year falls on. 2026 → 2016 at 12 a page. */
 export declare function yearPageStart(year: number): number;
-/** A memoised `Intl.DateTimeFormat`. `undefined` locale means the runtime's own. */
-export declare function dateFormatter(locale: string | undefined, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
 /** Formats a date, tolerating the `null` a cleared picker holds. */
 export declare function formatDate(date: Date | null | undefined, locale: string | undefined, options: Intl.DateTimeFormatOptions): string;
 /**