zz-meridian 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",

package/payload/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of ZZ Meridian, newest first. Versions follow semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Each entry says what breaks and what to do instead.
 
+## [0.22.0] · 2026-10-20
+
+### New
+
+- **A tile whose figure is a share reads its change in points** ([#74](https://github.com/zhixuan312/zz-meridian/issues/74)). `MetricTile` takes `deltaFormat` and hands it to `Delta`, whose `format` now takes a name as well as a function: `percent` (the default, a share of the earlier value) or `points`, so a share that went from 33.0% to 46.4% reads "▲13.4 pts" (`delta={0.134}`) with the same arrow, colour and screen-reader word, where it could only read "▲40.6%". `DeltaFormat` and `DELTA_FORMATS` are exported from `@/components/ui/delta`.
+
+### Fixed
+
+- **A Delta with no change reads its format** (#74): "0.0 pts" under `points`, or what a function makes of zero, where it printed a literal "0%" whatever the format. With no format given it still reads "0%".
+
+## [0.21.0] · 2026-10-20
+
+### New
+
+- **`TrendChart` takes `whole`** ([#73](https://github.com/zhixuan312/zz-meridian/issues/73)), as `ColumnChart` does since 0.20.0: the values are counts, a stack of counts too, and every level is a whole number, so a running total whose top is 10 draws no level at 2.5 or 7.5. Pass it on a chart of counts; a chart of a quantity that is not one keeps its halves.
+
 ## [0.20.0] · 2026-10-20
 
 ### New

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. Six layers, from DTCG tokens through four layers of React components to product workspaces, and a Design Atlas, in a light and a dark theme.",

package/payload/src/components/charts/trend-chart/README.md

@@ -7,7 +7,7 @@ Status: beta
 ## Anatomy
 
 1. **Plot**: horizontal gridlines in `chart-grid`, the baseline in `chart-axis`, 1px, crisp.
-2. **Y axis**: 3 or 4 "nice" ticks from zero, labels `text-2xs` `ink-3`, tabular, right-aligned in a gutter sized to the longest label. Axis labels drop cents and exact digits (`$12`, `1.2M`), and money from $10,000 reads at a glance (`$25K`, `$5.0B`) so a large scale does not widen the gutter; the tooltip and table carry the exact amounts.
+2. **Y axis**: 3 or 4 "nice" ticks from zero (whole numbers only with `whole`, for a chart of counts or a stack of them, so a top of 10 draws no level at 2.5 or 7.5), labels `text-2xs` `ink-3`, tabular, right-aligned in a gutter sized to the longest label. Axis labels drop cents and exact digits (`$12`, `1.2M`), and money from $10,000 reads at a glance (`$25K`, `$5.0B`) so a large scale does not widen the gutter; the tooltip and table carry the exact amounts.
 3. **X axis**: dates, `text-2xs` `ink-3`, one label per 92px, counted back from today so the last day is always labelled.
 4. **Series**: monotone curves that never overshoot their data.
 5. **Band** (with `band`): the region from the floor up to the band's ceiling, in `fill-track`, under the gridlines, its top edge drawn as the axis is, and its label at an end of that edge — in `ink-2`, since it stands over the fill as often as over the card and `ink-3` on `fill-track` is 4.43:1 in light.
@@ -125,7 +125,7 @@ import { TrendChart } from '@/components/charts/trend-chart';
 />
 ```
 
-Props: `dates`, `series` (`key`, `label`, `values`, `color`, `kind`), `format` (`count` | `compact` | `cost` | `cost-compact` | `duration` | `percent`), `height` (number or `fill`), `label`, `legend` (defaults to two or more series), `tick`, `stacked`, `baseline`, `band`, `floor`, `marks`, `running` (the last point is still in progress).
+Props: `dates`, `series` (`key`, `label`, `values`, `color`, `kind`), `format` (`count` | `compact` | `cost` | `cost-compact` | `duration` | `percent`), `height` (number or `fill`), `label`, `legend` (defaults to two or more series), `tick`, `stacked`, `whole` (the values are counts: whole levels only), `baseline`, `band`, `floor`, `marks`, `running` (the last point is still in progress).
 
 The colour of a stacked part is `stackPart(place, parts)` from `@/components/charts/scale`, the one mix every one-hue stack takes: the accent into the surface, by the part's place from the bottom.
 

package/payload/src/components/charts/trend-chart/index.tsx

@@ -97,6 +97,7 @@ export function TrendChart({
   legend,
   tick,
   stacked = false,
+  whole = false,
   baseline,
   band,
   floor,
@@ -118,6 +119,8 @@ export function TrendChart({
   tick?: (date: string) => string;
   /** The series are parts of one whole: bands stacked in order, the first at the bottom, each in its categorical slot. */
   stacked?: boolean;
+  /** The values are counts, a stack of counts too: every level is a whole number, so a top of 10 draws none at 2.5 or 7.5 (#73). */
+  whole?: boolean;
   /** What is usual, drawn as a quiet dashed line across the plot with its label at the end: `{ value: 296, label: 'Median 296ms' }`. */
   baseline?: { value: number; label: string };
   /**
@@ -177,7 +180,7 @@ export function TrendChart({
   const from = floor === undefined ? 0 : Math.min(floor, ...values);
   // The levels, and the floor the plot is drawn to: `ticks[0]` is 0 unless the chart was given a floor, and the two ends
   // of the scale are what every point, area, band and level line is measured against.
-  const ticks = ticksBetween(from, max, h < 200 ? 3 : 4);
+  const ticks = ticksBetween(from, max, h < 200 ? 3 : 4, whole);
   const low = ticks[0];
   const top = ticks[ticks.length - 1];
   const left = Math.max(...ticks.map((t) => axis(t).length)) * 6.4 + 12;

package/payload/src/components/patterns/metric-tile/README.md

@@ -20,7 +20,7 @@ Card, Delta, Status dot, Tooltip, Sparkline. Tiles sit in a `Row split="tiles"`,
 
 ## Data
 
-- `value` is the period's figure; `points` one value a point of the same period, oldest first (days on a page of days), or `null` at a point nothing was measured for, which the Sparkline draws as a gap rather than a fall to zero; `delta` the change as a fraction (0.057 is +5.7%), or `null` when there is no earlier period. `compare` names what the change is measured against (default "vs previous period"; "vs the half hour before" when the window is not the period). `note` is a short line in that place when no comparison fits, such as who is past due, carrying `data-note`; in a narrow tile it takes a second line before it is cut ("296 active · 14 trials · 10 past due" in a third of a page with the assistant's panel open), and a note that is text keeps the whole of itself in its title when the tile cuts it. On a compact tile it stays on the tile's one line.
+- `value` is the period's figure; `points` one value a point of the same period, oldest first (days on a page of days), or `null` at a point nothing was measured for, which the Sparkline draws as a gap rather than a fall to zero; `delta` the change as a fraction (0.057 is +5.7%), or `null` when there is no earlier period; `deltaFormat="points"` reads it in percentage points for a figure that is itself a share (a share from 33.0% to 46.4% is `delta={0.134}`, "13.4 pts"). `compare` names what the change is measured against (default "vs previous period"; "vs the half hour before" when the window is not the period). `note` is a short line in that place when no comparison fits, such as who is past due, carrying `data-note`; in a narrow tile it takes a second line before it is cut ("296 active · 14 trials · 10 past due" in a third of a page with the assistant's panel open), and a note that is text keeps the whole of itself in its title when the tile cuts it. On a compact tile it stays on the tile's one line.
 - `intent` says which way is good: `up` (requests), `down` (errors, latency), `neutral` (compute cost).
 - `value` may be a word for a categorical state ("Likely new", "On track"); it is set at `text-2xl` instead of the figure size and wraps to a second line rather than losing its end ("03 Oct 2026" in a narrow tile), and `format` is not used.
 - `format` turns the number into its text: a name (`count`, `compact`, `cost`, `cost-compact`, `duration`, `percent`), which a server page can pass, or a function from a client component; the default split recognises "$298.43" (any currency symbol from `app.currency`), "2.9M", "0.90%" and "294ms".
@@ -139,4 +139,4 @@ import { MetricTile } from '@/components/patterns/metric-tile';
 <MetricTile size="compact" label="Northwind Labs" value={41_200} format="cost-compact" delta={0.12} compare="vs last week" note="Scale" points={last14Days} />
 ```
 
-Props: `label`, `value`, `format`, `split`, `delta`, `compare`, `intent`, `note`, `points`, `baseline`, `finding`, `hint`, `icon`, `emphasis`, `size`, `className`. A compact tile holds a container, so it takes its cell's width and never sizes itself from what it holds: give it a grid cell or a width.
+Props: `label`, `value`, `format`, `split`, `delta`, `deltaFormat`, `compare`, `intent`, `note`, `points`, `baseline`, `finding`, `hint`, `icon`, `emphasis`, `size`, `className`. A compact tile holds a container, so it takes its cell's width and never sizes itself from what it holds: give it a grid cell or a width.

package/payload/src/components/patterns/metric-tile/index.tsx

@@ -5,7 +5,7 @@ import { cn } from '@/lib/cn';
 import { formatDate } from '@/lib/format-date';
 import { fitFigure, formatBy, splitFigure, type NumberFormat } from '@/lib/format';
 import { Card } from '@/components/ui/card';
-import { Delta } from '@/components/ui/delta';
+import { Delta, type DeltaFormat } from '@/components/ui/delta';
 import { Tooltip } from '@/components/ui/tooltip';
 import { Sparkline } from '@/components/charts/sparkline';
 import { useMeridianIndex, usePointMeridian } from '@/components/charts/meridian';
@@ -47,6 +47,7 @@ export function MetricTile({
   hint,
   value,
   delta,
+  deltaFormat,
   note,
   compare = 'vs previous period',
   intent = 'up',
@@ -67,6 +68,8 @@ export function MetricTile({
   value: number | string;
   /** Change against the previous period, as a fraction. */
   delta?: number | null;
+  /** How the change reads: `percent` (of the earlier value, the default) or `points`, for a figure that is itself a share. */
+  deltaFormat?: DeltaFormat | ((n: number) => string);
   /**
    * A short line where the change would sit, for a figure no period comparison fits: who is past due, what is next.
    * On a compact tile it follows the figure on the tile's one line: "$41.2K · next plan".
@@ -126,7 +129,7 @@ export function MetricTile({
               // The figure alone is drawn. Down a wall the words it is against would stand once a tile, so the card that
               // holds the wall says them; here they follow the figure for a screen reader, which meets a tile on its own.
               <p className={cn('flex h-5 items-center justify-self-start', COMPACT_CHANGE)}>
-                <Delta value={delta} intent={intent} />
+                <Delta value={delta} intent={intent} format={deltaFormat} />
                 <span className="sr-only">{' '}{delta === null ? 'No earlier period to compare' : compare}</span>
               </p>
             ) : null}
@@ -185,7 +188,7 @@ export function MetricTile({
               <span className="truncate text-ink-3" title="No earlier period to compare">No earlier period to compare</span>
             ) : delta !== undefined ? (
               <>
-                <Delta value={delta} intent={intent} />
+                <Delta value={delta} intent={intent} format={deltaFormat} />
                 <span className="leading-5 whitespace-nowrap text-ink-3">{compare}</span>
               </>
             ) : note ? (

package/payload/src/components/ui/delta/README.md

@@ -18,11 +18,11 @@ Status: beta
 | Down | Latency, error rate, cost per request | `critical-ink` | `positive-ink` |
 | Neutral | Spend, volume where neither direction is good | `ink-2` | `ink-2` |
 
-A change under 0.05% is flat: no arrow, "0%", `ink-2`. A missing comparison (`null`) is an em dash in `ink-3`: "we measured no change" and "there is nothing to compare with" are different facts.
+A change under 0.05% is flat: no arrow, `ink-2`, and the format reading no change ("0.0 pts" under `points`; "0%" with no format given). A missing comparison (`null`) is an em dash in `ink-3`: "we measured no change" and "there is nothing to compare with" are different facts.
 
 ## Sizes
 
-One size, `text-xs`, so it sits on the caption line under a figure. The format defaults to a percentage with one decimal; pass `format` for absolute changes ("43ms").
+One size, `text-xs`, so it sits on the caption line under a figure. The format defaults to `percent`, the change as a share of the earlier value with one decimal; `points` reads a change in a value that is itself a share in percentage points ("13.4 pts", where `percent` would print a share that went from 33.0% to 46.4% as up 40.6%); pass a function for absolute changes ("43ms").
 
 ## States
 
@@ -64,4 +64,4 @@ import { Delta } from '@/components/ui/delta';
 <Delta value={23.73} format={(n) => `$${n}`} intent="neutral" />
 ```
 
-Props: `value` (a fraction, or null), `format`, `intent` (`up` | `down` | `neutral`), `className`.
+Props: `value` (a fraction, or null), `format` (`percent` | `points` | a function), `intent` (`up` | `down` | `neutral`), `className`.

package/payload/src/components/ui/delta/index.tsx

@@ -1,24 +1,37 @@
 import { cn } from '@/lib/cn';
 
+/**
+ * How a change reads: `percent` is the change as a share of the earlier value (0.12 reads 12.0%); `points` is a change in
+ * a value that is itself a share, in percentage points (0.134 reads 13.4 pts), so a share that went from 33.0% to 46.4%
+ * never reads as having risen 40.6%. A name, so a server page can pass it to a client tile (#74).
+ */
+export type DeltaFormat = 'percent' | 'points';
+export const DELTA_FORMATS: Record<DeltaFormat, (n: number) => string> = {
+  percent: (n) => `${Math.abs(n * 100).toFixed(1)}%`,
+  points: (n) => `${Math.abs(n * 100).toFixed(1)} pts`,
+};
+
 /**
  * A change against the previous period. The arrow carries the direction; the colour carries the judgement, which is
  * not the same thing: for latency or errors, down is good. `intent` says which way is good.
  */
 export function Delta({
   value,
-  format = (n) => `${Math.abs(n * 100).toFixed(1)}%`,
+  format,
   intent = 'up',
   className,
 }: {
-  /** The change as a fraction (0.12 is +12%), or null when there is nothing to compare with. */
+  /** The change as a fraction (0.12 is +12%, or +12 points under `points`), or null when there is nothing to compare with. */
   value: number | null;
-  format?: (n: number) => string;
+  /** How the change reads, a name or a function of its magnitude; `percent` by default. No change reads it too ("0.0 pts"). */
+  format?: DeltaFormat | ((n: number) => string);
   /** Which direction is good. `neutral` paints both directions in ink. */
   intent?: 'up' | 'down' | 'neutral';
   className?: string;
 }) {
   if (value === null || !Number.isFinite(value)) return <span className={cn('text-xs text-ink-3', className)}>—</span>;
   const flat = Math.abs(value) < 0.0005;
+  const read = typeof format === 'function' ? format : DELTA_FORMATS[format ?? 'percent'];
   const up = value > 0;
   const good = intent === 'neutral' || flat ? null : (up && intent === 'up') || (!up && intent === 'down');
   return (
@@ -33,7 +46,8 @@ export function Delta({
         <path d="M5 1.5 8.5 7h-7z" fill="currentColor" />
       </svg>
       <span className="sr-only">{flat ? 'unchanged' : up ? 'up' : 'down'} </span>
-      {flat ? '0%' : format(value)}
+      {/* No change is read as the format reads a change, so a points tile says "0.0 pts", never a literal 0%. */}
+      {flat ? (format ? read(0) : '0%') : read(value)}
     </span>
   );
 }

package/payload/src/components/ui/delta/preview.tsx

@@ -19,6 +19,10 @@ export default function DeltaPreview() {
         <State label="Flat"><Delta value={0} /></State>
         <State label="Nothing to compare"><Delta value={null} /></State>
       </Specimen>
+      <Specimen label="In points" note='format="points": a change in a figure that is itself a share, a refusal share from 33.0% to 46.4%, reads 13.4 points, never 40.6% of itself. No change reads in the same format.'>
+        <State label="Rise"><Delta value={0.134} format="points" intent="down" /></State>
+        <State label="Flat"><Delta value={0} format="points" intent="down" /></State>
+      </Specimen>
       <Specimen label="In context">
         <span className="flex items-center gap-2 text-xs"><Delta value={0.057} /><span className="text-ink-3">vs previous period</span></span>
       </Specimen>

package/payload/tests/metric-tile-delta-format.test.tsx

@@ -0,0 +1,25 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { MetricTile } from '@/components/patterns/metric-tile';
+import { Delta } from '@/components/ui/delta';
+
+describe('a tile whose figure is a share (#74)', () => {
+  it('reads its change in points under deltaFormat="points", with the same arrow, colour and word', () => {
+    const { container } = render(<MetricTile label="Share refused" value={0.464} format="percent" delta={0.134} deltaFormat="points" intent="down" />);
+    const change = container.querySelector('.t-num.inline-flex')!;
+    expect(change).toHaveTextContent(/^up 13\.4 pts$/);
+    expect(change).toHaveClass('text-critical-ink');
+  });
+  it('still reads a change as a percentage of the earlier value without it', () => {
+    const { container } = render(<MetricTile label="Requests" value={1200} delta={0.406} />);
+    expect(container.querySelector('.t-num.inline-flex')).toHaveTextContent(/^up 40\.6%$/);
+  });
+});
+
+describe('a Delta with no change', () => {
+  it('reads it in its format, never a literal 0%', () => {
+    expect(render(<Delta value={0} format="points" />).container).toHaveTextContent(/^unchanged 0\.0 pts$/);
+    expect(render(<Delta value={0} format={(n) => `${n.toFixed(2)} ms`} />).container).toHaveTextContent(/^unchanged 0\.00 ms$/);
+    expect(render(<Delta value={0} />).container).toHaveTextContent(/^unchanged 0%$/);
+  });
+});

package/payload/tests/trend-chart-whole.test.tsx

@@ -0,0 +1,28 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('@/components/charts/use-size', async () => {
+  const { useRef } = await import('react');
+  return { useSize: () => [useRef(null), { width: 640, height: 0 }] as const };
+});
+
+import { TrendChart } from '@/components/charts/trend-chart';
+
+const dates = ['2026-09-07', '2026-09-14', '2026-09-21', '2026-09-28'];
+/** The levels' labels: the axis text beside each gridline. */
+const levels = (c: HTMLElement) => [...c.querySelectorAll('svg g > line + text')].map((t) => t.textContent);
+
+describe('a trend chart of counts (#73)', () => {
+  it('draws whole levels only, a running total of ten as a line or as a stack', () => {
+    const made = render(<TrendChart label="Items in all" whole dates={dates} series={[{ key: 'n', label: 'Items', values: [2, 5, 7, 10], kind: 'line' }]} />);
+    expect(levels(made.container).every((t) => /^\d+$/.test(t ?? ''))).toBe(true);
+    expect(levels(made.container)).not.toContain('2.5');
+    made.unmount();
+    const stack = render(<TrendChart label="Items in all, by team" whole stacked dates={dates} series={[{ key: 'a', label: 'Core', values: [1, 3, 4, 6] }, { key: 'b', label: 'Web', values: [1, 2, 3, 4] }]} />);
+    expect(levels(stack.container).every((t) => /^\d+$/.test(t ?? ''))).toBe(true);
+  });
+  it('keeps halves without it, for a quantity that is not a count', () => {
+    const { container } = render(<TrendChart label="Hours waited" dates={dates} series={[{ key: 'n', label: 'Hours', values: [2, 5, 7, 10], kind: 'line' }]} />);
+    expect(levels(container)).toContain('2.5');
+  });
+});