@lotics/ui 42.0.0 → 42.3.0

package/src/colors.ts

@@ -1,386 +1,17 @@
-const palette = {
-  black: "rgba(0,0,0,1)",
-  white: "rgba(255,255,255,1)",
-
-  // We use RGBA so that we can use React Native Animations with colors
-  red: {
-    50: "rgba(254, 242, 242, 1)",
-    100: "rgba(254, 226, 226, 1)",
-    200: "rgba(254, 202, 202, 1)",
-    300: "rgba(252, 165, 165, 1)",
-    400: "rgba(248, 113, 113, 1)",
-    500: "rgba(239, 68, 68, 1)",
-    600: "rgba(220, 38, 38, 1)",
-    700: "rgba(185, 28, 28, 1)",
-    800: "rgba(153, 27, 27, 1)",
-    900: "rgba(127, 29, 29, 1)",
-    950: "rgba(69, 10, 10, 1)",
-  },
-  orange: {
-    50: "rgba(255, 247, 237, 1)",
-    100: "rgba(255, 237, 213, 1)",
-    200: "rgba(254, 215, 170, 1)",
-    300: "rgba(253, 186, 116, 1)",
-    400: "rgba(251, 146, 60, 1)",
-    500: "rgba(249, 115, 22, 1)",
-    600: "rgba(234, 88, 12, 1)",
-    700: "rgba(194, 65, 12, 1)",
-    800: "rgba(154, 52, 18, 1)",
-    900: "rgba(124, 45, 18, 1)",
-    950: "rgba(67, 20, 7, 1)",
-  },
-  amber: {
-    50: "rgba(255, 251, 235, 1)",
-    100: "rgba(254, 243, 199, 1)",
-    200: "rgba(253, 230, 138, 1)",
-    300: "rgba(252, 211, 77, 1)",
-    400: "rgba(251, 191, 36, 1)",
-    500: "rgba(245, 158, 11, 1)",
-    600: "rgba(217, 119, 6, 1)",
-    700: "rgba(180, 83, 9, 1)",
-    800: "rgba(146, 64, 14, 1)",
-    900: "rgba(120, 53, 15, 1)",
-    950: "rgba(69, 26, 3, 1)",
-  },
-  yellow: {
-    50: "rgba(254, 252, 232, 1)",
-    100: "rgba(254, 249, 195, 1)",
-    200: "rgba(254, 240, 138, 1)",
-    300: "rgba(253, 224, 71, 1)",
-    400: "rgba(250, 204, 21, 1)",
-    500: "rgba(234, 179, 8, 1)",
-    600: "rgba(202, 138, 4, 1)",
-    700: "rgba(161, 98, 7, 1)",
-    800: "rgba(133, 77, 14, 1)",
-    900: "rgba(113, 63, 18, 1)",
-    950: "rgba(66, 32, 6, 1)",
-  },
-  lime: {
-    50: "rgba(247, 254, 231, 1)",
-    100: "rgba(236, 252, 203, 1)",
-    200: "rgba(217, 249, 157, 1)",
-    300: "rgba(190, 242, 100, 1)",
-    400: "rgba(163, 230, 53, 1)",
-    500: "rgba(132, 204, 22, 1)",
-    600: "rgba(101, 163, 13, 1)",
-    700: "rgba(77, 124, 15, 1)",
-    800: "rgba(63, 98, 18, 1)",
-    900: "rgba(54, 83, 20, 1)",
-    950: "rgba(26, 46, 5, 1)",
-  },
-  green: {
-    50: "rgba(240, 253, 244, 1)",
-    100: "rgba(220, 252, 231, 1)",
-    200: "rgba(187, 247, 208, 1)",
-    300: "rgba(134, 239, 172, 1)",
-    400: "rgba(74, 222, 128, 1)",
-    500: "rgba(34, 197, 94, 1)",
-    600: "rgba(22, 163, 74, 1)",
-    700: "rgba(21, 128, 61, 1)",
-    800: "rgba(22, 101, 52, 1)",
-    900: "rgba(20, 83, 45, 1)",
-    950: "rgba(5, 46, 22, 1)",
-  },
-  emerald: {
-    50: "rgba(236, 253, 245, 1)",
-    100: "rgba(209, 250, 229, 1)",
-    200: "rgba(167, 243, 208, 1)",
-    300: "rgba(110, 231, 183, 1)",
-    400: "rgba(52, 211, 153, 1)",
-    500: "rgba(16, 185, 129, 1)",
-    600: "rgba(5, 150, 105, 1)",
-    700: "rgba(4, 120, 87, 1)",
-    800: "rgba(6, 95, 70, 1)",
-    900: "rgba(6, 78, 59, 1)",
-    950: "rgba(2, 44, 34, 1)",
-  },
-  teal: {
-    50: "rgba(240, 253, 250, 1)",
-    100: "rgba(204, 251, 241, 1)",
-    200: "rgba(153, 246, 228, 1)",
-    300: "rgba(94, 234, 212, 1)",
-    400: "rgba(45, 212, 191, 1)",
-    500: "rgba(20, 184, 166, 1)",
-    600: "rgba(13, 148, 136, 1)",
-    700: "rgba(15, 118, 110, 1)",
-    800: "rgba(17, 94, 89, 1)",
-    900: "rgba(19, 78, 74, 1)",
-    950: "rgba(4, 47, 46, 1)",
-  },
-  cyan: {
-    50: "rgba(236, 254, 255, 1)",
-    100: "rgba(207, 250, 254, 1)",
-    200: "rgba(165, 243, 252, 1)",
-    300: "rgba(103, 232, 249, 1)",
-    400: "rgba(34, 211, 238, 1)",
-    500: "rgba(6, 182, 212, 1)",
-    600: "rgba(8, 145, 178, 1)",
-    700: "rgba(14, 116, 144, 1)",
-    800: "rgba(21, 94, 117, 1)",
-    900: "rgba(22, 78, 99, 1)",
-    950: "rgba(8, 51, 68, 1)",
-  },
-  sky: {
-    50: "rgba(240, 249, 255, 1)",
-    100: "rgba(224, 242, 254, 1)",
-    200: "rgba(186, 230, 253, 1)",
-    300: "rgba(125, 211, 252, 1)",
-    400: "rgba(56, 189, 248, 1)",
-    500: "rgba(14, 165, 233, 1)",
-    600: "rgba(2, 132, 199, 1)",
-    700: "rgba(3, 105, 161, 1)",
-    800: "rgba(7, 89, 133, 1)",
-    900: "rgba(12, 74, 110, 1)",
-    950: "rgba(8, 47, 73, 1)",
-  },
-  blue: {
-    50: "rgba(239, 246, 255, 1)",
-    100: "rgba(219, 234, 254, 1)",
-    200: "rgba(191, 219, 254, 1)",
-    300: "rgba(147, 197, 253, 1)",
-    400: "rgba(96, 165, 250, 1)",
-    500: "rgba(59, 130, 246, 1)",
-    600: "rgba(37, 99, 235, 1)",
-    700: "rgba(29, 78, 216, 1)",
-    800: "rgba(30, 64, 175, 1)",
-    900: "rgba(30, 58, 138, 1)",
-    950: "rgba(23, 37, 84, 1)",
-  },
-  indigo: {
-    50: "rgba(238, 242, 255, 1)",
-    100: "rgba(224, 231, 255, 1)",
-    200: "rgba(199, 210, 254, 1)",
-    300: "rgba(165, 180, 252, 1)",
-    400: "rgba(129, 140, 248, 1)",
-    500: "rgba(99, 102, 241, 1)",
-    600: "rgba(79, 70, 229, 1)",
-    700: "rgba(67, 56, 202, 1)",
-    800: "rgba(55, 48, 163, 1)",
-    900: "rgba(49, 46, 129, 1)",
-    950: "rgba(30, 27, 75, 1)",
-  },
-  violet: {
-    50: "rgba(245, 243, 255, 1)",
-    100: "rgba(237, 233, 254, 1)",
-    200: "rgba(221, 214, 254, 1)",
-    300: "rgba(196, 181, 253, 1)",
-    400: "rgba(167, 139, 250, 1)",
-    500: "rgba(139, 92, 246, 1)",
-    600: "rgba(124, 58, 237, 1)",
-    700: "rgba(109, 40, 217, 1)",
-    800: "rgba(91, 33, 182, 1)",
-    900: "rgba(76, 29, 149, 1)",
-    950: "rgba(46, 16, 101, 1)",
-  },
-  purple: {
-    50: "rgba(250, 245, 255, 1)",
-    100: "rgba(243, 232, 255, 1)",
-    200: "rgba(233, 213, 255, 1)",
-    300: "rgba(216, 180, 254, 1)",
-    400: "rgba(192, 132, 252, 1)",
-    500: "rgba(168, 85, 247, 1)",
-    600: "rgba(147, 51, 234, 1)",
-    700: "rgba(126, 34, 206, 1)",
-    800: "rgba(107, 33, 168, 1)",
-    900: "rgba(88, 28, 135, 1)",
-    950: "rgba(59, 7, 100, 1)",
-  },
-  fuchsia: {
-    50: "rgba(253, 244, 255, 1)",
-    100: "rgba(250, 232, 255, 1)",
-    200: "rgba(245, 208, 254, 1)",
-    300: "rgba(240, 171, 252, 1)",
-    400: "rgba(232, 121, 249, 1)",
-    500: "rgba(217, 70, 239, 1)",
-    600: "rgba(192, 38, 211, 1)",
-    700: "rgba(162, 28, 175, 1)",
-    800: "rgba(134, 25, 143, 1)",
-    900: "rgba(112, 26, 117, 1)",
-    950: "rgba(74, 4, 78, 1)",
-  },
-  pink: {
-    50: "rgba(253, 242, 248, 1)",
-    100: "rgba(252, 231, 243, 1)",
-    200: "rgba(251, 207, 232, 1)",
-    300: "rgba(249, 168, 212, 1)",
-    400: "rgba(244, 114, 182, 1)",
-    500: "rgba(236, 72, 153, 1)",
-    600: "rgba(219, 39, 119, 1)",
-    700: "rgba(190, 24, 93, 1)",
-    800: "rgba(157, 23, 77, 1)",
-    900: "rgba(131, 24, 67, 1)",
-    950: "rgba(80, 7, 36, 1)",
-  },
-  rose: {
-    50: "rgba(255, 241, 242, 1)",
-    100: "rgba(255, 228, 230, 1)",
-    200: "rgba(254, 205, 211, 1)",
-    300: "rgba(253, 164, 175, 1)",
-    400: "rgba(251, 113, 133, 1)",
-    500: "rgba(244, 63, 94, 1)",
-    600: "rgba(225, 29, 72, 1)",
-    700: "rgba(190, 18, 60, 1)",
-    800: "rgba(159, 18, 57, 1)",
-    900: "rgba(136, 19, 55, 1)",
-    950: "rgba(76, 5, 25, 1)",
-  },
-  slate: {
-    50: "rgba(248, 250, 252, 1)",
-    100: "rgba(241, 245, 249, 1)",
-    200: "rgba(226, 232, 240, 1)",
-    300: "rgba(203, 213, 225, 1)",
-    400: "rgba(148, 163, 184, 1)",
-    500: "rgba(100, 116, 139, 1)",
-    600: "rgba(71, 85, 105, 1)",
-    700: "rgba(51, 65, 85, 1)",
-    800: "rgba(30, 41, 59, 1)",
-    900: "rgba(15, 23, 42, 1)",
-    950: "rgba(2, 6, 23, 1)",
-  },
-  gray: {
-    50: "rgba(249, 250, 251, 1)",
-    100: "rgba(243, 244, 246, 1)",
-    200: "rgba(229, 231, 235, 1)",
-    300: "rgba(209, 213, 219, 1)",
-    400: "rgba(156, 163, 175, 1)",
-    500: "rgba(107, 114, 128, 1)",
-    600: "rgba(75, 85, 99, 1)",
-    700: "rgba(55, 65, 81, 1)",
-    800: "rgba(31, 41, 55, 1)",
-    900: "rgba(17, 24, 39, 1)",
-    950: "rgba(3, 7, 18, 1)",
-  },
-  zinc: {
-    50: "rgba(250, 250, 250, 1)",
-    100: "rgba(244, 244, 245, 1)",
-    200: "rgba(228, 228, 231, 1)",
-    300: "rgba(212, 212, 216, 1)",
-    400: "rgba(161, 161, 170, 1)",
-    500: "rgba(113, 113, 122, 1)",
-    600: "rgba(82, 82, 91, 1)",
-    700: "rgba(63, 63, 70, 1)",
-    800: "rgba(39, 39, 42, 1)",
-    900: "rgba(24, 24, 27, 1)",
-    950: "rgba(9, 9, 11, 1)",
-  },
-  neutral: {
-    50: "rgba(250, 250, 250, 1)",
-    100: "rgba(245, 245, 245, 1)",
-    200: "rgba(229, 229, 229, 1)",
-    300: "rgba(212, 212, 212, 1)",
-    400: "rgba(163, 163, 163, 1)",
-    500: "rgba(115, 115, 115, 1)",
-    600: "rgba(82, 82, 82, 1)",
-    700: "rgba(64, 64, 64, 1)",
-    800: "rgba(38, 38, 38, 1)",
-    900: "rgba(23, 23, 23, 1)",
-    950: "rgba(10, 10, 10, 1)",
-  },
-  stone: {
-    50: "rgba(250, 250, 249, 1)",
-    100: "rgba(245, 245, 244, 1)",
-    200: "rgba(231, 229, 228, 1)",
-    300: "rgba(214, 211, 209, 1)",
-    400: "rgba(168, 162, 158, 1)",
-    500: "rgba(120, 113, 108, 1)",
-    600: "rgba(87, 83, 78, 1)",
-    700: "rgba(68, 64, 60, 1)",
-    800: "rgba(41, 37, 36, 1)",
-    900: "rgba(28, 25, 23, 1)",
-    950: "rgba(12, 10, 9, 1)",
-  },
-};
-
-export const colors = {
-  ...palette,
-  border: palette.zinc["200"],
-  border_shadow: `0px 1px 2px 0px ${palette.zinc["200"]}`,
-  background: palette.white,
-  shadow: `0px 0px 6px 1px ${palette.zinc["300"]}`,
-};
-
-/**
- * A low-alpha wash of a palette color (hover tints, dimmed chart segments,
- * icon discs). Handles the palette's rgba() strings plus rgb()/#RRGGBB.
- */
-export function withAlpha(color: string, alpha: number): string {
-  if (color.startsWith("rgba(")) return color.replace(/,\s*[\d.]+\s*\)\s*$/, `, ${alpha})`);
-  if (color.startsWith("rgb(")) return color.replace("rgb(", "rgba(").replace(/\)\s*$/, `, ${alpha})`);
-  if (color.startsWith("#") && color.length === 7) {
-    return `${color}${Math.round(alpha * 255)
-      .toString(16)
-      .padStart(2, "0")}`;
-  }
-  return color;
-}
-
-/**
- * A palette FAMILY name — the single, semantic way to reference a color across
- * the system (Badge, status indicators, chart series, breakdown segments).
- * Reference colors by NAME and let the component resolve the shade it needs;
- * never thread a raw hex through props — it drifts (one call site picks 500,
- * another 600, and the same "status" renders two greens). Excludes the
- * non-scale role keys (border/background/shadow/black/white).
- */
-export type ColorName = Exclude<keyof typeof colors, "border" | "border_shadow" | "background" | "shadow" | "black" | "white">;
-
-/**
- * The canonical SOLID shade of a family (500) — status dots, status-grid
- * cells, breakdown segments, chart series. Defined ONCE so every indicator of
- * the same color agrees on the shade.
- */
-export function solid(name: ColorName): string {
-  return colors[name][500];
-}
-
-/** A low-alpha wash of a family's solid shade — cell/segment tints, dimmed
- *  states. `tint("emerald", 0.2)` === `withAlpha(solid("emerald"), 0.2)`. */
-export function tint(name: ColorName, alpha: number): string {
-  return withAlpha(solid(name), alpha);
-}
-
-/** Dark → light stops a `ramp` spans (the usable mid range of a scale). */
-const RAMP_STOPS = [700, 600, 500, 400, 300, 200] as const;
-
-/**
- * `count` distinct shades of ONE family, strong → light — the monochrome
- * "one hue family per dimension" data ramp (a Breakdown's segments, an ordered
- * funnel, any multi-category breakdown of a single dimension). Use this for a
- * COHERENT dimension instead of hand-picking shades or scattering hues; the
- * segment LABEL carries identity, the shade only orders. (For semantic
- * categories whose color carries MEANING — status — give each its own
- * `ColorName` and `solid()` it, don't ramp.)
- */
-export function ramp(name: ColorName, count: number): string[] {
-  const scale = colors[name];
-  if (count <= 1) return [scale[600]];
-  return Array.from({ length: count }, (_, i) => {
-    const idx = Math.round((i / (count - 1)) * (RAMP_STOPS.length - 1));
-    return scale[RAMP_STOPS[idx]];
-  });
-}
-
-/**
- * Is `value` a usable {@link ColorName} — a palette FAMILY, not a role key
- * (`border`/`background`/…) and not `black`/`white`? A family resolves to a
- * shade object; the role/scalar keys resolve to a string, so "value is an
- * object" is the test (no name list to keep in sync).
- */
-export function isColorName(value: unknown): value is ColorName {
-  return (
-    typeof value === "string" &&
-    value in colors &&
-    typeof (colors as Record<string, unknown>)[value] === "object"
-  );
-}
+export * from "./color_tokens";
 
 /**
- * Coerce an arbitrary color token to a {@link ColorName}, falling back to a
- * neutral. The single graceful-degradation point for stored option/status
- * colors: a select option's `color` may be a token a newer table config
- * introduced that this UI build predates, or absent entirely — either way a
- * component renders a neutral badge instead of breaking. Used by `OptionBadge`.
+ * The NATIVE token surface — the literal table, unchanged.
+ *
+ * The values themselves live in `./color_tokens`, which both this file and
+ * `./colors.web.ts` re-export. That indirection exists for one concrete reason:
+ * a relative `./colors` resolves `.web.ts` FIRST on web, so a web variant that
+ * imported `./colors` would import itself, and esbuild reports it as
+ * "Detected cycle while resolving import". Neither variant may name the other;
+ * both name a third module instead.
+ *
+ * Importers never see this split — `@lotics/ui/colors` and the kit's own
+ * `./colors` both keep working, and which of the two files answers is decided by
+ * platform (the `react-native` export condition, and `.web.ts` extension order
+ * inside the kit).
  */
-export function asColorName(value: unknown, fallback: ColorName = "zinc"): ColorName {
-  return isColorName(value) ? value : fallback;
-}

package/src/colors.web.ts

@@ -0,0 +1,43 @@
+import { colors as contract } from "./color_tokens";
+
+export { withAlpha, solid, tint, ramp, isColorName, asColorName } from "./color_tokens";
+export type { ColorName } from "./color_tokens";
+
+/**
+ * The token contract, with its FOUR themeable roles indirected through CSS
+ * variables so an app can carry its own visual identity.
+ *
+ * Why this file exists at all, rather than a React context: 136 of the kit's 320
+ * modules import `colors` directly, at module scope, into `StyleSheet.create`.
+ * A context would have to reach every one of them, turning static stylesheets
+ * into per-render inline styles — the kit's whole performance model — for a
+ * feature that changes four values. A variable costs nothing at runtime and
+ * touches no component: `colors.background` still reads `colors.background`.
+ *
+ * It is safe because react-native-web's `isWebColor` allowlists `var(` ahead of
+ * its own colour normalization, so a variable reaches CSS untouched on every
+ * colour property. That is a web-only guarantee, which is exactly why this is a
+ * `.web.ts` sibling: the `react-native` export condition and `.web.ts` extension
+ * order pick it for the browser; native keeps the literals it can parse.
+ *
+ * It reads its literals from `./color_tokens`, NEVER from `./colors` — on web a
+ * relative `./colors` resolves back to this very file, which esbuild reports as
+ * "Detected cycle while resolving import".
+ *
+ * Each variable carries its literal DEFAULT inline, so the theme is opt-in in
+ * the strictest sense — an app that sets nothing has no `--lotics-*` defined,
+ * every `var()` falls back, and the pixels are identical to before this file.
+ *
+ * ONLY these three. The palette families stay literal, and must: `withAlpha`,
+ * `tint` and `ramp` do string surgery on an `rgba()` to derive a wash, and a
+ * `var()` handed to them would produce garbage no type would catch. Keeping the
+ * themeable set to chrome keeps those functions total — the maintainability
+ * argument and the "colour must keep meaning status" argument turn out to be the
+ * same argument.
+ */
+export const colors = {
+  ...contract,
+  background: `var(--lotics-background, ${contract.background})`,
+  border: `var(--lotics-border, ${contract.border})`,
+  accent: `var(--lotics-accent, ${contract.accent})`,
+};

package/src/summary.tsx

@@ -0,0 +1,217 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { View, StyleSheet } from "react-native";
+import { Metric, type MetricFormat, type MetricTone } from "./metric";
+import { StackedProgressBar } from "./stacked_progress_bar";
+import { SummaryLine, type SummaryLineItem } from "./summary_line";
+import { useLocaleTag } from "./locale";
+import { Text } from "./text";
+
+/**
+ * One bucket of the set being summarized — a slice of the whole, with the colour
+ * it wears wherever it appears.
+ *
+ * The buckets PARTITION the set: their values sum to the total, which is why the
+ * total is derived rather than passed. A count that belongs to the same rows but
+ * does not partition them — a condition rather than a position, "overdue" beside
+ * "draft / sent / paid" — is not a bucket and must not be one, or the bar starts
+ * claiming a share for something that is already inside another segment. Pass
+ * those to `Summary.Facts` as `extra`.
+ */
+export interface SummaryBucket {
+  key: string;
+  /** Reads AFTER the value, like every other label in this family. */
+  label: string;
+  value: number;
+  /** The segment's colour, and the swatch's. Use the same value this bucket
+   *  wears in the rest of the product — a bar that disagrees with the badge
+   *  beside it is worse than no bar. */
+  color: string;
+  /** What this bucket means — the ⓘ beside its count. */
+  info?: string;
+}
+
+interface SummaryContext {
+  buckets: readonly SummaryBucket[];
+  total: number;
+}
+
+const Ctx = createContext<SummaryContext | null>(null);
+
+function useSummary(part: string): SummaryContext {
+  const ctx = useContext(Ctx);
+  if (!ctx) throw new Error(`<Summary.${part}> must be rendered inside <Summary>.`);
+  return ctx;
+}
+
+interface SummaryProps {
+  buckets: readonly SummaryBucket[];
+  children: ReactNode;
+}
+
+/**
+ * The register's summary band — a headline figure, the set's DISTRIBUTION, and
+ * the buckets named — composed from parts rather than configured by props.
+ *
+ * **Why a compound and not one component with more props.** The parts encode a
+ * correspondence that is easy to break and impossible to see broken: the bar,
+ * the legend and the headline all describe ONE set. Passing a `segments` array
+ * beside an `items` array beside a `total` invites exactly three drifts —
+ * segments reordered against their labels, a legend swatch picking a different
+ * shade, and a hardcoded total that stops summing after a bucket is added. So
+ * the buckets are declared ONCE on the root and every part derives from them.
+ * The total is a sum. The swatches are the segments' own colours. Nothing is
+ * restated, so nothing can disagree.
+ *
+ * That correspondence is the reason this is a primitive at all — this kit does
+ * not extract a composition for saving lines of layout.
+ *
+ * Reach for it when the set has a SHAPE worth showing. A summary that is only a
+ * few aggregates stays `SummaryLine`, which is this band's `Facts` row on its
+ * own; a boxed dashboard stat band is `KPIStrip`; a drill-down facet browser
+ * over a large population is `Breakdown`.
+ *
+ *     <Summary buckets={STAGES}>
+ *       <Summary.Header>
+ *         <Summary.Total label="khách hàng" />
+ *         <Summary.Metric value={660_000_000} label="hoa hồng" format="currency" compact />
+ *       </Summary.Header>
+ *       <Summary.Distribution />
+ *       <Summary.Facts extra={[{ label: "đang tắc", value: 3, tone: "warning" }]} />
+ *     </Summary>
+ */
+export function Summary(props: SummaryProps) {
+  const { buckets, children } = props;
+  const total = buckets.reduce((sum, b) => sum + b.value, 0);
+  return (
+    <Ctx.Provider value={{ buckets, total }}>
+      <View style={styles.root}>{children}</View>
+    </Ctx.Provider>
+  );
+}
+
+/** The band's top line: a `Total` at the start, anything else pushed to the end.
+ *  Baseline-aligned, because figures of different sizes sitting on one line is
+ *  the whole reason this row exists. */
+function Header(props: { children: ReactNode }) {
+  return <View style={styles.header}>{props.children}</View>;
+}
+
+/**
+ * The set's SIZE, at display scale — the band's headline.
+ *
+ * The number is the sum of the buckets and is never passed in. A page that
+ * restates its own total eventually restates it wrongly: a bucket gets added,
+ * the constant does not move, and the headline quietly disagrees with the bar
+ * directly beneath it.
+ */
+function Total(props: { label: string; formatValue?: (n: number) => string }) {
+  const { total } = useSummary("Total");
+  const tag = useLocaleTag();
+  // Grouped by the reader's locale by default — a set of 12,345 was rendering
+  // "12345" in the one place on the screen sized to be read first, because the
+  // first app to use this counted in the hundreds. `formatValue` is the escape
+  // hatch for a total whose unit is not a plain count.
+  const shown = props.formatValue ? props.formatValue(total) : total.toLocaleString(tag);
+  return (
+    <View style={styles.pair}>
+      <Text size="xxxl" weight="semibold" tabular>
+        {shown}
+      </Text>
+      <Text size="md" color="muted">
+        {props.label}
+      </Text>
+    </View>
+  );
+}
+
+/**
+ * A second headline figure that is NOT part of the distribution — a sum of money
+ * over the same rows, an average, a rate.
+ *
+ * Deliberately not a bucket: it does not partition the set, so the bar must not
+ * carry it. It sits on the header row because a reader opening a register asks
+ * two questions ("how much of this is there" and "what is it worth"), and the
+ * answers belong side by side.
+ */
+function SummaryMetric(props: {
+  value: number | string | null | undefined;
+  label: string;
+  format?: MetricFormat;
+  currency?: string;
+  compact?: boolean;
+  emptyLabel?: string;
+  tone?: MetricTone;
+}) {
+  const { value, label, ...rest } = props;
+  return (
+    <View style={styles.pair}>
+      <Metric value={value} size="lg" {...rest} />
+      <Text size="sm" color="muted">
+        {label}
+      </Text>
+    </View>
+  );
+}
+
+/**
+ * The set's shape — one segment per bucket, in declaration order.
+ *
+ * Order is the CALLER's, untouched, because for an ordered set (a pipeline, a
+ * ladder, an age bracket) the sequence carries meaning that sorting by size
+ * would destroy. Re-rank the array before passing it if size is what matters.
+ */
+function Distribution(props: { height?: number }) {
+  const { buckets, total } = useSummary("Distribution");
+  return (
+    <StackedProgressBar
+      height={props.height ?? 20}
+      total={total}
+      segments={buckets.map((b) => ({ key: b.key, value: b.value, color: b.color }))}
+    />
+  );
+}
+
+/**
+ * The buckets named, with their counts — the band's legend, and on its own the
+ * whole of `SummaryLine`.
+ *
+ * Each item takes its swatch from its own bucket, so the legend cannot drift
+ * from the bar above it. `extra` appends aggregates that are NOT segments and
+ * therefore get no swatch — the visual difference is the point: a reader can see
+ * that the unswatched figure is not a slice of the bar.
+ */
+function Facts(props: { extra?: readonly SummaryLineItem[] }) {
+  const { buckets } = useSummary("Facts");
+  const items: SummaryLineItem[] = buckets.map((b) => ({
+    label: b.label,
+    value: b.value,
+    color: b.color,
+    info: b.info,
+  }));
+  return <SummaryLine items={[...items, ...(props.extra ?? [])]} />;
+}
+
+Summary.Header = Header;
+Summary.Total = Total;
+Summary.Metric = SummaryMetric;
+Summary.Distribution = Distribution;
+Summary.Facts = Facts;
+
+const styles = StyleSheet.create({
+  // 12, and it is half of what a page must put BETWEEN this band and its
+  // neighbours. The band's parts are one group — a figure, the shape of what it
+  // counts, and that shape's key — so they have to sit closer to each other than
+  // the band sits to the register below it. Measured at 14 against a 16px page
+  // gap, the ratio was 1.14: every block on the screen an equal peer, nothing
+  // grouped, which is what "no rhythm" is when you measure it.
+  root: { gap: 12 },
+  header: {
+    flexDirection: "row",
+    alignItems: "baseline",
+    flexWrap: "wrap",
+    justifyContent: "space-between",
+    columnGap: 20,
+    rowGap: 8,
+  },
+  pair: { flexDirection: "row", alignItems: "baseline", gap: 8 },
+});