zz-meridian 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.21.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,16 @@
 
 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

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.21.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/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%$/);
+  });
+});