@apliteni/apliteni-ui 0.113.0 → 0.114.0

package/src/index.css

@@ -36,6 +36,7 @@
 @import "./styles/filter-bar.css";
 @import "./styles/pagination.css";
 @import "./styles/stat.css";
+@import "./styles/chart.css";
 @import "./styles/empty.css";
 @import "./styles/callout.css";
 @import "./styles/code.css";

package/src/index.d.ts

@@ -86,6 +86,24 @@ export type NumericValueOptions = { value?: string | number | null; unit?: strin
 export type DeltaValueOptions = { value?: string | null; tone?: 'success' | 'danger' | 'neutral'; basisId?: string; missing?: string };
 export declare function formatNumericValue(options?: NumericValueOptions): { text: string; unit: string; missing: string | undefined };
 export declare function formatDeltaValue(options?: DeltaValueOptions): { text: string; className: string; basisId: string | undefined };
+
+/** The smallest band a series is drawn in, as a share of its own reach. */
+export declare const CHART_FLOOR: number;
+export type ChartScaleOptions = { ticks?: number; zero?: boolean; floor?: number; nice?: boolean };
+export type ChartScale = { min: number; max: number; step: number; ticks: number[] };
+export declare function chartScale(values: Iterable<number>, options?: ChartScaleOptions): ChartScale;
+export type BridgeStepInput = { label: string; value?: number; kind?: 'total' | 'change' };
+export type BridgeBar<S> = S & { kind: 'total' | 'change'; value: number; from: number; to: number };
+export declare function bridgeWalk<S extends BridgeStepInput>(steps: Iterable<S>): BridgeBar<S>[];
+export type ChartBox = { left: number; right: number; top: number; bottom: number };
+export type PointTargetLimits = {
+  floor: number; min?: number; box: ChartBox;
+  column: [number, number]; apart?: Iterable<number>;
+};
+export type ChartTarget = { x: number; y: number; w: number; h: number };
+export declare function pointTarget(
+  point: { x: number; y: number }, limits: PointTargetLimits,
+): ChartTarget;
 export declare const SCORE: Record<'exact' | 'prefix' | 'wordStart' | 'contains' | 'keyword' | 'description' | 'subsequence', number>;
 export declare const iconNames: string[];
 export declare const iconCategories: { name: string; names: string[] }[];

package/src/index.js

@@ -35,3 +35,4 @@ export { PAGE_SIZES, DEFAULT_PAGE_SIZE } from './logic/pagination.js';
 export { calloutIcons } from './logic/callout.js';
 export { formatNumericValue, formatDeltaValue } from './logic/table-values.js';
 export { accentSwatchStyle } from './logic/accents.js';
+export { CHART_FLOOR, chartScale, bridgeWalk, pointTarget } from './logic/chart.js';

package/src/inline.js

@@ -50,6 +50,7 @@ export const styles = {
   filterBar: read('styles/filter-bar.css'),
   pagination: read('styles/pagination.css'),
   stat: read('styles/stat.css'),
+  chart: read('styles/chart.css'),
   empty: read('styles/empty.css'),
   callout: read('styles/callout.css'),
   code: read('styles/code.css'),
@@ -86,6 +87,7 @@ export const cssText = [
   styles.filterBar,
   styles.pagination,
   styles.stat,
+  styles.chart,
   styles.empty,
   styles.callout,
   styles.code,

package/src/logic/chart.js

@@ -0,0 +1,143 @@
+// Chart arithmetic, shared by the React Chart and by anything that draws the
+// same shapes without it. No DOM, no pixels: a scale and a walk, both pure.
+// why: docs/components.md#react-charts
+
+/** The steps a whole-unit axis may take, per decade, smallest first. 2.5 is
+ *  among them — 25000 is a whole step and the one that turns a four-tick axis
+ *  into four ticks — but it is taken only where it lands on a whole number, so
+ *  nothing below the units decade can put 2.5 on an axis. */
+const STEPS = [1, 2, 2.5, 5, 10];
+
+/** The smallest band a series is drawn in, as a share of its own reach. Below
+ *  this, a series that barely moves would be stretched into a cliff. */
+export const CHART_FLOOR = 0.25;
+
+const round = (n) => Math.round(n * 1e6) / 1e6;
+
+/** The smallest nice step at or above `raw` that is a whole unit. */
+function niceStep(raw) {
+  if (!(raw > 0)) return 1;
+  const decade = 10 ** Math.floor(Math.log10(raw));
+  for (const s of STEPS) {
+    const step = round(s * decade);
+    if (step >= raw - 1e-9 && step >= 1 && Number.isInteger(step)) return step;
+  }
+  return Math.max(1, Math.ceil(raw));
+}
+
+/**
+ * The band a series is drawn in, and the ticks written beside it.
+ *
+ * @param {Iterable<number>} values every number that has to fit
+ * @param {object} [options]
+ * @param {number} [options.ticks] how many steps to aim for
+ * @param {boolean} [options.zero] keep the zero line inside the band — true for
+ *   bars, which are read from zero, false for a line read against itself
+ * @param {number} [options.floor] the smallest band, as a share of the series'
+ *   own reach; `CHART_FLOOR` for a sparkline
+ * @param {boolean} [options.nice] round the band out to whole steps and return
+ *   them; false for a chart with no axis
+ * @returns {{min: number, max: number, step: number, ticks: number[]}}
+ */
+export function chartScale(values, { ticks = 4, zero = true, floor = 0, nice = true } = {}) {
+  const finite = [...values].filter((v) => Number.isFinite(v));
+  if (finite.length === 0) return { min: 0, max: 1, step: 1, ticks: [0, 1] };
+
+  let min = Math.min(...finite);
+  let max = Math.max(...finite);
+  if (zero) { min = Math.min(min, 0); max = Math.max(max, 0); }
+
+  const reach = Math.max(Math.abs(min), Math.abs(max)) || 1;
+  const want = reach * floor;
+  if (max - min < want) {
+    const pad = (want - (max - min)) / 2;
+    min -= pad;
+    max += pad;
+    if (zero) { min = Math.min(min, 0); max = Math.max(max, 0); }
+  }
+  if (min === max) { min -= 0.5; max += 0.5; }
+
+  if (!nice) return { min: round(min), max: round(max), step: 0, ticks: [] };
+
+  const step = niceStep((max - min) / Math.max(ticks, 1));
+  min = Math.floor(round(min / step)) * step;
+  max = Math.ceil(round(max / step)) * step;
+  const out = [];
+  for (let t = min; t <= max + 1e-9; t += step) out.push(round(t));
+  return { min: round(min), max: round(max), step, ticks: out };
+}
+
+/**
+ * One period walked from a starting total through its components to a result.
+ *
+ * The first step is a total unless it says otherwise; every later step is a
+ * component added to the running total. A step marked `total` with no value of
+ * its own takes the running total, which is how the closing column is written
+ * without repeating a sum the caller already gave piece by piece.
+ *
+ * @param {Iterable<{label: string, value?: number, kind?: 'total'|'change'}>} steps
+ * @returns {Array<{label: string, kind: 'total'|'change', value: number, from: number, to: number}>}
+ *   each column's own amount and the two ends of the bar that draws it
+ */
+export function bridgeWalk(steps) {
+  let running = 0;
+  return [...steps].map((step, index) => {
+    const kind = step.kind || (index === 0 ? 'total' : 'change');
+    if (kind === 'total') {
+      const value = Number.isFinite(step.value) ? step.value : running;
+      running = value;
+      return { ...step, kind, value: round(value), from: 0, to: round(value) };
+    }
+    const value = Number.isFinite(step.value) ? step.value : 0;
+    const from = running;
+    running += value;
+    return { ...step, kind, value: round(value), from: round(from), to: round(running) };
+  });
+}
+
+const clamp = (v, lo, hi) => Math.min(Math.max(v, lo), hi);
+
+/**
+ * The pointer target over one drawn point, as a rectangle.
+ *
+ * A point is a mark a pointer has to reach rather than a control, so its target
+ * is a transparent box laid over it. The box grows to the floor this pointer
+ * asks for, stops at half the clear space to the nearest point on each side,
+ * and is then held inside the box the chart draws in — a target that reached
+ * past the chart's edge would be clipped there, and a nominal 44 that a
+ * drawing clips to 19 is not a target. `min` is the floor it keeps where the
+ * column has room. A narrower column owns the whole column instead, so no point
+ * answers for the period beside it.
+ * why: guidelines/accessibility-floor.md#tap-target-on-a-phone
+ *
+ * @param {{x: number, y: number}} point the point's centre
+ * @param {object} limits
+ * @param {number} limits.floor the target this pointer asks for, each way
+ * @param {number} [limits.min] the smallest target, where the column has room
+ * @param {{left: number, right: number, top: number, bottom: number}} limits.box
+ *   the chart's own drawn box, which nothing may reach past
+ * @param {[number, number]} limits.column the point's own column, left and right
+ * @param {Iterable<number>} [limits.apart] the centre, down, of every other
+ *   point in the same column
+ * @returns {{x: number, y: number, w: number, h: number}}
+ */
+export function pointTarget({ x, y }, { floor, min = floor, box, column, apart = [] }) {
+  const fit = (centre, [outerLo, outerHi], [spaceLo, spaceHi], neighbours) => {
+    let lo = spaceLo;
+    let hi = spaceHi;
+    for (const n of neighbours) {
+      const mid = (centre + n) / 2;
+      if (n < centre) lo = Math.max(lo, mid);
+      if (n > centre) hi = Math.min(hi, mid);
+    }
+    const size = Math.min(floor, Math.max(0, hi - lo));
+    // Centred on the point, then held inside the space it may own, then inside
+    // the chart's box. The box is last so the point on the chart's own edge
+    // keeps a whole target instead of half of one.
+    const owned = clamp(centre - size / 2, lo, Math.max(lo, hi - size));
+    return { at: clamp(owned, outerLo, Math.max(outerLo, outerHi - size)), size };
+  };
+  const across = fit(x, [box.left, box.right], column, []);
+  const down = fit(y, [box.top, box.bottom], [box.top, box.bottom], apart);
+  return { x: across.at, y: down.at, w: across.size, h: down.size };
+}

package/src/styles/chart.css

@@ -0,0 +1,282 @@
+/* ============================================================================
+ * Chart — .ui-chart, the shapes a money dashboard keeps redrawing.
+ *   .ui-chart__legend  one key per series, plus the unfinished-period key
+ *   .ui-chart__frame   the tab stop; the value axis beside the scroller
+ *   .ui-chart__scroll  the scroller, masked on whichever side hides columns
+ *   .ui-chart__plot    the drawing and its column labels
+ *   .ui-chart__data    the same numbers as a table
+ * The component sets --ui-chart-h, the plot's height, which the axis matches.
+ * why: docs/components.md#react-charts
+ * ========================================================================== */
+
+.ui-chart {
+  --ui-chart-col: var(--space-12);
+  /* The ground the marks are drawn on, so an unfinished period and the rim the
+     line is carried on read as cut out of it. A chart outside a card names its
+     own. */
+  --ui-chart-ground: var(--surface);
+  /* The tick's own line box. The axis spans the band the gridlines are drawn
+     in — the plot less the room a stroke needs at each edge — and is half a
+     line box taller at each end, so every tick's middle lands on its gridline
+     without taking a single label out of flow. */
+  --ui-chart-tick: calc(var(--text-xs) * 1.45);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+  font-size: var(--text-xs);
+  color: var(--text);
+}
+
+.ui-chart--bridge { --ui-chart-col: calc(var(--space-16) + var(--space-6)); }
+.ui-chart--spark {
+  --ui-chart-col: var(--space-6);
+  gap: 0;
+  min-width: 0;
+}
+/* No axis, so the scroller takes the whole frame rather than the auto column
+   the axis would have held. */
+.ui-chart--spark .ui-chart__frame { grid-template-columns: minmax(0, 1fr); }
+/* The box, not the drawing: a phone target does not fit in 32px. Written here
+   rather than left to the height attribute, which `.ui-stat__trend svg` beats.
+   why: docs/components.md#react-charts */
+.ui-chart--spark .ui-chart__svg { height: var(--ui-chart-box); }
+
+/* -- the legend ------------------------------------------------------------ */
+
+.ui-chart__legend {
+  /* muted-ink: chrome — the key names the marks and is not the chart's words */
+  color: var(--muted);
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  column-gap: var(--space-4);
+  row-gap: var(--space-1);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.ui-chart__key {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  white-space: nowrap;
+}
+.ui-chart__key-mark { flex: none; }
+.ui-chart__key-swatch { fill: var(--ui-chart-tone); }
+.ui-chart__key-line { fill: none; stroke: var(--ui-chart-tone); stroke-width: 2; stroke-linecap: round; }
+.ui-chart__key-estimated {
+  fill: var(--ui-chart-tone);
+  stroke: var(--ui-chart-ground);
+  stroke-width: 1;
+  stroke-dasharray: 2 2;
+}
+
+/* -- the frame ------------------------------------------------------------- */
+
+.ui-chart__frame {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  align-items: start;
+  column-gap: var(--space-2);
+  padding-block: calc(var(--ring-width, 2px) + var(--ring-offset, 1px));
+  border-radius: var(--radius-xs);
+}
+.ui-chart__frame:focus-visible {
+  outline-offset: var(--ring-offset, 1px);
+}
+
+.ui-chart__axis {
+  /* muted-ink: chrome — a tick names the scale; exact values are reachable through the readout */
+  color: var(--muted);
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  height: calc(var(--ui-chart-h) - var(--ui-chart-pad) * 2 + var(--ui-chart-tick));
+  margin-block: calc(var(--ui-chart-pad) - var(--ui-chart-tick) / 2);
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+.ui-chart__tick { line-height: 1.45; }
+
+/* The mask fades whichever side still hides periods. It paints no ground of its
+   own, so a chart on the card and one on the page both fade correctly — and it
+   sits on the scroller rather than the tab stop, which would mask its ring. */
+.ui-chart__scroll {
+  overflow-x: auto;
+  overflow-y: hidden;
+  overscroll-behavior-x: contain;
+}
+.ui-chart__scroll.is-more-before {
+  mask-image: linear-gradient(to right, transparent 0, #000 var(--space-6));
+}
+.ui-chart__scroll.is-more-after {
+  mask-image: linear-gradient(to right, #000 calc(100% - var(--space-6)), transparent 100%);
+}
+.ui-chart__scroll.is-more-before.is-more-after {
+  mask-image: linear-gradient(
+    to right, transparent 0, #000 var(--space-6),
+    #000 calc(100% - var(--space-6)), transparent 100%);
+}
+
+.ui-chart__plot { min-width: calc(var(--ui-chart-col) * var(--ui-chart-cols, 1)); }
+.ui-chart__svg { display: block; }
+
+.ui-chart__periods {
+  display: grid;
+  grid-auto-flow: column;
+  grid-auto-columns: 1fr;
+  /* The row stood 4px under the plot plus the 2px rule every label reserved for
+     the picked one. The rule is gone and the gap keeps that step on the scale
+     rather than between two of its steps. */
+  padding-top: var(--space-2);
+}
+.ui-chart__period {
+  /* muted-ink: chrome — a period label names a column; its values are reachable through the readout */
+  color: var(--muted);
+  padding-inline: var(--space-1);
+  text-align: center;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+/* The picked column's label: the body ink the rest of the row gives up, at the
+   weight a reader who separates no colours still reads. Selection is otherwise
+   the band behind the column and the band alone — the outline the chart draws
+   belongs to focus. */
+.ui-chart__period.is-selected {
+  color: var(--strong);
+  font-weight: 600;
+}
+
+/* -- the marks ------------------------------------------------------------- */
+
+/* The rules. A hairline at each tick carries a bar's height across twelve columns
+   to the label that names it, which is the one job a grid has; it is the kit's
+   faintest edge, so it is found when a reader looks for it and not before. The
+   zero rule keeps --border-strong above it: the line a signed series is measured
+   from leads the ones it is measured against. Both sit under every mark. */
+.ui-chart__grid { stroke: var(--border); stroke-width: 1; }
+.ui-chart__zero { stroke: var(--border-strong); stroke-width: 1; }
+
+/* The carry a bridge draws between two steps: the running total leaves one
+   column at the height it reached and meets the next where it starts from. It
+   takes --border-strong, the zero rule's weight rather than the grid's, because
+   it is read along rather than looked up. Solid, like every other rule here: a
+   dash would read as a forecast. */
+.ui-chart__carry { stroke: var(--border-strong); stroke-width: 1; }
+
+/* The picked column, behind every mark and every rule. A quiet fill rather than
+   the accent, which the chart spends on a series; it is wider than any bar, so
+   the column is found before the bar in it is read. */
+.ui-chart__band { fill: var(--surface-3); }
+
+.ui-chart__bar {
+  /* One flat tone, the whole bar. A ramp down the bar was the one thing in the
+     drawing that carried no number: it let the middle go while both edges held,
+     so a reader comparing two months compared two shaded cylinders. */
+  fill: var(--ui-chart-tone);
+  stroke: none;
+}
+/* Keep each series' fill weight. Ground-coloured dashes mark unfinished data
+   without joining the mirrored bars across the zero channel. */
+.ui-chart__bar.is-estimated {
+  fill: var(--ui-chart-tone);
+  stroke: var(--ui-chart-ground);
+  stroke-width: 1;
+  stroke-dasharray: 3 2;
+}
+
+/* An isolated value has no segment to draw it. Connected points need no dot. */
+.ui-chart__isolated { fill: var(--ui-chart-tone); stroke: var(--ui-chart-ground); stroke-width: 1; }
+
+.ui-chart__line {
+  fill: none;
+  stroke: var(--ui-chart-tone);
+  stroke-width: 2;
+  stroke-linecap: round;
+}
+.ui-chart__line.is-estimated { stroke-dasharray: 5 3; }
+
+/* The ground carried under the line. The line crosses bars of its own family,
+   where hue alone separates them and luminance does not: a stroke of the ground
+   each side gives the line the 3:1 it cannot get from the bar behind it. It is
+   not drawn where there is nothing to cross — a sparkline has no bars, and at
+   text size the casing would eat the line. The line carries no marker of its
+   own; a dot on every point drew nothing the line had not already drawn. */
+.ui-chart__line-casing {
+  fill: none;
+  stroke: var(--ui-chart-ground);
+  stroke-width: 4;
+  stroke-linecap: round;
+}
+.ui-chart--spark .ui-chart__line-casing { display: none; }
+
+.ui-chart--spark .ui-chart__line { stroke-width: 1.6; }
+
+/* The edge the readout is placed against: the mark's top. Geometry only — it
+   paints nothing. The readout opens above that edge where the frame has the
+   room and flips below it where it has not, which near the top of the plot
+   means covering the mark and the first axis labels. The guideline asks for
+   that flip rather than for a readout outside the part.
+   why: guidelines/hover-readouts.md#prefer-above-the-mark */
+.ui-chart__anchor { fill: none; pointer-events: none; }
+
+/* The hit area a pointer lands on. It is the series' own band in the column, so
+   a pointer between two bars still has a bar to answer with. */
+.ui-chart__hit { fill: transparent; }
+
+/* A chart whose columns can be picked says so under the pointer. The key
+   compound names the element rather than a class, which is how the kit's
+   clickable-chrome gate reads `.ui-seg button` and `.ui-check input`: the mark
+   is this <g> and cannot be moved onto a <button>, so there is no button
+   chrome to measure. */
+.ui-chart--pick [data-mark] { cursor: pointer; }
+
+/* The tones. A series names one; the token behind it is the kit's, and the same
+   in both themes' terms. The neutral one is --muted, which is what
+   --signal-solid-neutral already is: a mid grey in both themes, where --dim
+   would paint a bridge's totals near-black in light and near-white in dark. */
+.ui-chart__tone--accent { --ui-chart-tone: var(--accent); }
+/* The accent's second weight: the same hue, let down towards the ground rather
+   than given an opacity, so a mark painted with it is opaque and a reader
+   measures one colour. The mix crosses 3:1 at 67% against the card AND against
+   the page, in both themes, under all four accents, so 70% ships with room over
+   the bar rather than sitting on it — the 40% the restyle's mock drew measures
+   1.99:1 and 2.03:1 and does not ship. */
+.ui-chart__tone--accent-soft {
+  --ui-chart-tone: color-mix(in srgb, var(--accent) 70%, var(--ui-chart-ground));
+}
+.ui-chart__tone--good { --ui-chart-tone: var(--green); }
+.ui-chart__tone--bad { --ui-chart-tone: var(--pink); }
+.ui-chart__tone--warn { --ui-chart-tone: var(--amber); }
+.ui-chart__tone--info { --ui-chart-tone: var(--cyan); }
+.ui-chart__tone--neutral { --ui-chart-tone: var(--muted); }
+
+/* -- the table ------------------------------------------------------------- */
+
+.ui-chart__data > summary {
+  width: max-content;
+  min-height: var(--tap-min, 44px);
+  display: inline-flex;
+  align-items: center;
+  box-sizing: border-box;
+  padding: var(--space-1) var(--space-2);
+  border-radius: var(--radius-xs);
+  cursor: pointer;
+  font-size: var(--text-sm);
+}
+.ui-chart__data[open] > summary { margin-bottom: var(--space-3); }
+/* The table is the one place a phone reader gets exact values, and how wide it
+   is depends on the caller's series: it carries them sideways inside the kit's
+   own scroller, so the card and the page keep their width whatever it holds.
+   Sideways only — there are as many rows as the chart has columns, and capping
+   their height would hide the last period behind a second scrollbar. */
+.ui-chart__data .ui-table-scroll { --ui-table-height: none; }
+.ui-chart__data .ui-table { margin: 0; }
+/* Why a period is not final is a sentence, not a label, so it wraps under the
+   period it qualifies instead of carrying the money columns another two hundred
+   pixels to the right of a 390px card. */
+.ui-chart__data .ui-table tbody th { white-space: normal; }
+.ui-chart__state {
+  /* muted-ink: state — the word that marks a period as not final */
+  color: var(--muted);
+}