@lotics/ui 2.4.0 → 2.5.0

package/src/filter_pill.tsx

@@ -0,0 +1,106 @@
+import { type ReactNode } from "react";
+import { StyleSheet } from "react-native";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { colors } from "./colors";
+import { LinkButton } from "./link_button";
+import { PillButton } from "./pill_button";
+import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
+import type { PopoverSide, PopoverAlign } from "./popover";
+
+export interface FilterPillProps {
+  /** The dimension name — shown alone when inactive ("Owner"), prefixed when
+   *  active ("Owner: Maria, James"). */
+  label: string;
+  /** A short human summary of the active selection ("Maria, James", "≥ 10").
+   *  Empty / undefined renders the inactive pill (label + chevron, no clear).
+   *  Build it with `rangeSummary` / `selectSummary` for a consistent preview. */
+  summary?: string;
+  /** Clears the dimension — renders the × on the pill AND a Clear in the popover
+   *  footer whenever a summary is present. */
+  onClear?: () => void;
+  /** Label for the clear affordances (pass a translated string). */
+  clearLabel?: string;
+  /** The editor revealed on press — a premium primitive (`RangeSlider`,
+   *  `Counter`, `PickerMenu` multi) or any composed control. `FilterPill` owns
+   *  the pill + popover chrome; the consumer owns the value and applies it. */
+  children: ReactNode;
+  side?: PopoverSide;
+  align?: PopoverAlign;
+  /** Optional controlled popover state — for an editor that closes on Save. */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** A custom popover footer (e.g. Cancel / Save) — replaces the baked Clear.
+   *  Lets a non-filter VALUE pill (a setting gate) reuse the same shell. */
+  footer?: ReactNode;
+}
+
+/**
+ * A short summary of a multi-select for a `FilterPill` preview — "Maria, James"
+ * up to `max` labels, else "N selected", and `undefined` when nothing is
+ * chosen. The select sibling of `rangeSummary`.
+ */
+export function selectSummary(
+  selected: string[],
+  options: { value: string; label: string }[],
+  opts?: { max?: number },
+): string | undefined {
+  if (selected.length === 0) return undefined;
+  const max = opts?.max ?? 2;
+  if (selected.length > max) return `${selected.length} selected`;
+  return selected.map((v) => options.find((o) => o.value === v)?.label ?? v).join(", ");
+}
+
+/**
+ * A toolbar filter pill — the compact, popover-backed control for a SECONDARY
+ * filter dimension, the sibling of `ChipGroup` (which lays ONE hot dimension's
+ * options out inline). Many dimensions stay scannable because each collapses to
+ * a single pill: inactive reads "Label ⌄", active reads "Label: summary" with an
+ * × to clear. `FilterPill` bakes the consistent chrome — the preview pill, a
+ * padded popover body for the composed editor, and a Clear footer when active —
+ * so every filter looks and behaves the same. Drop a premium primitive inside
+ * (`RangeSlider`, `Counter`, `PickerMenu` multi). With `footer` (+ controlled
+ * `open`/`onOpenChange`) the same shell wraps a non-filter VALUE pill — a
+ * setting gate with Cancel/Save — keeping it on the one pill surface. The table
+ * toolbar's `ColumnFilter` is this pill plus its query-condition mapping.
+ */
+export function FilterPill(props: FilterPillProps) {
+  const { label, summary, onClear, clearLabel = "Clear", children, side = "bottom", align = "start", open, onOpenChange, footer } = props;
+  const active = summary != null && summary.length > 0;
+  // The clear × / Clear footer only when there's a clearable selection AND no
+  // custom footer — a valued, non-clearable pill ("Target: 20") keeps its chevron.
+  const showClear = active && !!onClear && !footer;
+
+  return (
+    <Popover side={side} align={align} open={open} onOpenChange={onOpenChange}>
+      <PopoverTrigger>
+        <PillButton onDismiss={showClear ? onClear : undefined} dismissTooltip={clearLabel}>
+          <Text size="sm" weight="medium" color={active ? "zinc-900" : "zinc-700"} numberOfLines={1}>
+            {active ? `${label}: ${summary}` : label}
+          </Text>
+          {!showClear ? <Icon name="chevron-down" size={14} color={colors.zinc["400"]} /> : null}
+        </PillButton>
+      </PopoverTrigger>
+      <PopoverContent style={styles.body} disableBodyScroll>
+        {children}
+        {footer ? (
+          <PopoverFooter>{footer}</PopoverFooter>
+        ) : showClear ? (
+          <PopoverFooter align="start">
+            <LinkButton title={clearLabel} onPress={onClear} />
+          </PopoverFooter>
+        ) : null}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+const styles = StyleSheet.create({
+  // The popover hugs its content — a wide control (e.g. RangeSlider) sets its
+  // OWN fixed width; the shell never forces one. No extra padding: the editor and
+  // the Clear footer then share the popover's own 8px inset, so a multi-select's
+  // options, its select-all, and the Clear all line up on one left edge.
+  body: {
+    gap: 8,
+  },
+});

package/src/floating_action_bar.tsx

@@ -0,0 +1,57 @@
+import { ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import { Button } from "./button";
+import { Card } from "./card";
+import { Text } from "./text";
+
+export interface FloatingActionBarProps {
+  /** How many rows are selected — the bar shows only while > 0. */
+  count: number;
+  /** The noun after the count — "leads selected", "in-policy requests". */
+  label: string;
+  /** Clears the selection — the always-present escape. */
+  onClear: () => void;
+  clearLabel?: string;
+  /** The bulk action(s) — a primary `Button` or an "Assign to…" `Popover`. */
+  children: ReactNode;
+}
+
+/**
+ * The floating action bar — pinned bottom-center while ≥1 row is selected across a
+ * checkbox-select register, showing the count + Clear + the bulk action(s), with
+ * the primary action kept RIGHTMOST (Clear is the secondary escape to its left).
+ * The shared surface for assign/reassign (a CRM pile), bulk-approve, batch-build,
+ * etc. Lift the selection `Set` into the host; this is presentation only. The
+ * `box-none` wrapper lets clicks fall through everywhere except the bar.
+ */
+export function FloatingActionBar(props: FloatingActionBarProps) {
+  const { count, label, onClear, clearLabel = "Clear", children } = props;
+  if (count <= 0) return null;
+  return (
+    <View pointerEvents="box-none" style={styles.wrap}>
+      <Card style={styles.bar}>
+        <Text size="sm" weight="semibold" tabular>{`${count} ${label}`}</Text>
+        <Button title={clearLabel} color="secondary" onPress={onClear} />
+        {children}
+      </Card>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  wrap: {
+    position: "absolute",
+    bottom: 20,
+    left: 0,
+    right: 0,
+    alignItems: "center",
+    zIndex: 20,
+  },
+  bar: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+    paddingVertical: 10,
+    paddingHorizontal: 16,
+  },
+});

package/src/fonts.css

@@ -1,23 +1,20 @@
 /*
  * Inter @font-face for custom-code apps.
  *
- * The woff2 files are served by the backend at /iframe/fonts/<name>.woff2 —
- * same-origin to a deployed app's sandboxed iframe, sent as font/woff2 with
- * immutable cache headers, so the browser caches them across every app and
- * every render.
+ * Served from static.lotics.ai (public, CORS-enabled R2) by ABSOLUTE URL, so the
+ * same stylesheet resolves on every origin an app is served from — `lotics app
+ * dev` on localhost, the API same-origin, and a per-app deploy origin — with no
+ * per-origin font routing (no vite /iframe proxy, no app-host worker proxy).
  *
- * Kept tiny on purpose: base64-inlining the fonts would put ~440 KB of font
- * binary into this render-blocking stylesheet and delay first paint. As
- * separate files with `font-display: swap`, nothing blocks the first paint.
- *
- * `lotics app dev` serves the app from localhost, where `/iframe/...` would
- * 404 — the starter vite.config proxies /iframe to the API for development.
+ * NOT base64-inlined: ~440 KB of inlined font binary would make this stylesheet
+ * render-blocking and delay first paint. Separate cached files with
+ * `font-display: swap` block nothing.
  */
 @font-face {
   font-family: Inter_400Regular;
   font-style: normal;
   font-weight: 400;
-  src: url("/iframe/fonts/Inter_400Regular.woff2") format("woff2");
+  src: url("https://static.lotics.ai/fonts/Inter_400Regular.woff2") format("woff2");
   font-display: swap;
 }
 
@@ -25,7 +22,7 @@
   font-family: Inter_500Medium;
   font-style: normal;
   font-weight: 500;
-  src: url("/iframe/fonts/Inter_500Medium.woff2") format("woff2");
+  src: url("https://static.lotics.ai/fonts/Inter_500Medium.woff2") format("woff2");
   font-display: swap;
 }
 
@@ -33,6 +30,6 @@
   font-family: Inter_600SemiBold;
   font-style: normal;
   font-weight: 600;
-  src: url("/iframe/fonts/Inter_600SemiBold.woff2") format("woff2");
+  src: url("https://static.lotics.ai/fonts/Inter_600SemiBold.woff2") format("woff2");
   font-display: swap;
 }

package/src/format_money.ts

@@ -0,0 +1,38 @@
+export interface FormatMoneyOptions {
+  locale?: string;
+  currency?: string;
+  /** Abbreviate for display density: ≥1 tỷ → "1,28 tỷ ₫", ≥1 triệu →
+   * "486 tr ₫". For stat strips/cards where the full figure lives in the
+   * table below — never for the table itself. */
+  compact?: boolean;
+}
+
+/**
+ * Compact vi-style magnitude suffixes: ≥1 tỷ → "1,28 tỷ", ≥1 triệu →
+ * "486 tr"; smaller values render in full. Bare numbers only — for money,
+ * use `formatMoney` with `compact`.
+ */
+export function formatCompactNumber(value: number, locale = "vi-VN"): string {
+  if (Math.abs(value) >= 1_000_000_000) {
+    return `${(value / 1_000_000_000).toLocaleString(locale, { maximumFractionDigits: 2 })} tỷ`;
+  }
+  if (Math.abs(value) >= 1_000_000) {
+    return `${Math.round(value / 1_000_000).toLocaleString(locale)} tr`;
+  }
+  return value.toLocaleString(locale);
+}
+
+/**
+ * THE money formatter — `Metric` (and through it `KPICard`/`KPIStrip`)
+ * delegates here; table cells and captions call it directly. Defaults to
+ * the product's home market: `1.234.567 ₫`. Never hand-roll digit grouping
+ * or the ₫ suffix.
+ */
+export function formatMoney(value: number, options: FormatMoneyOptions = {}): string {
+  const { locale = "vi-VN", currency = "VND", compact = false } = options;
+  if (compact && Math.abs(value) >= 1_000_000) {
+    const suffixed = formatCompactNumber(value, locale);
+    return currency === "VND" ? `${suffixed} ₫` : `${suffixed} ${currency}`;
+  }
+  return value.toLocaleString(locale, { style: "currency", currency });
+}

package/src/heatmap.tsx

@@ -0,0 +1,153 @@
+import { useState } from "react";
+import { Pressable, StyleSheet, View } from "react-native";
+import { colors, withAlpha } from "./colors";
+import { Text } from "./text";
+
+export interface HeatmapAxisItem {
+  key: string;
+  label: string;
+}
+
+export interface HeatmapCell {
+  row: string;
+  col: string;
+}
+
+export interface HeatmapProps {
+  rows: HeatmapAxisItem[];
+  cols: HeatmapAxisItem[];
+  /** values[rowIndex][colIndex] — intensity scales to the matrix max. */
+  values: number[][];
+  /** The hue. Intensity is alpha within it; zero cells go neutral. */
+  color?: string;
+  /** The inspected cell — host renders its detail underneath. */
+  selected?: HeatmapCell | null;
+  /** Press a cell to inspect (press the same cell again to clear). Omit
+   * for an informational heatmap. */
+  onSelectCell?: (cell: HeatmapCell | null) => void;
+  formatValue?: (n: number) => string;
+}
+
+const defaultFormat = (n: number): string => n.toLocaleString("en-US");
+
+/**
+ * Density over two dimensions — "when/where does it cluster?" (alarms by
+ * site × day, errors by hour, demand by lane × week). One hue; intensity
+ * carries the value; zero stays neutral so gaps read as quiet, not as
+ * data. Pressing a cell selects it for the host to drill (detail band,
+ * filtered list). Pair with a row dimension that matches the screen's
+ * other bands so a hot cell points somewhere actionable.
+ */
+export function Heatmap(props: HeatmapProps) {
+  const { rows, cols, values, color = colors.blue[600], selected = null, onSelectCell, formatValue = defaultFormat } = props;
+  const max = Math.max(1, ...values.flat());
+
+  return (
+    <View style={styles.container}>
+      {rows.map((row, r) => (
+        <View key={row.key} style={styles.row}>
+          <Text size="xs" color="muted" numberOfLines={1} style={styles.rowLabel}>
+            {row.label}
+          </Text>
+          {cols.map((col, c) => {
+            const value = values[r]?.[c] ?? 0;
+            const isSelected = selected?.row === row.key && selected?.col === col.key;
+            return (
+              <Cell
+                key={col.key}
+                label={`${row.label} · ${col.label}: ${formatValue(value)}`}
+                background={value === 0 ? colors.zinc[100] : withAlpha(color, 0.15 + 0.85 * (value / max))}
+                selected={isSelected}
+                onPress={
+                  onSelectCell
+                    ? () => onSelectCell(isSelected ? null : { row: row.key, col: col.key })
+                    : undefined
+                }
+              />
+            );
+          })}
+        </View>
+      ))}
+      <View style={styles.row}>
+        <View style={styles.rowLabel} />
+        {cols.map((col) => (
+          <Text key={col.key} size="xs" color="muted" tabular align="center" numberOfLines={1} style={styles.colLabel}>
+            {col.label}
+          </Text>
+        ))}
+      </View>
+      <View style={styles.scale}>
+        <Text size="xs" color="muted">Less</Text>
+        {[0.15, 0.36, 0.57, 0.78, 1].map((alpha) => (
+          <View key={alpha} style={[styles.scaleSwatch, { backgroundColor: withAlpha(color, alpha) }]} />
+        ))}
+        <Text size="xs" color="muted">More</Text>
+      </View>
+    </View>
+  );
+}
+
+interface CellProps {
+  label: string;
+  background: string;
+  selected: boolean;
+  onPress?: () => void;
+}
+
+function Cell(props: CellProps) {
+  const { label, background, selected, onPress } = props;
+  const [hovered, setHovered] = useState(false);
+  const base = {
+    backgroundColor: background,
+    borderColor: selected ? colors.zinc[900] : hovered && onPress ? colors.zinc[400] : "transparent",
+  };
+  if (!onPress) return <View style={[styles.cell, base]} />;
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityState={{ selected }}
+      accessibilityLabel={label}
+      onPress={onPress}
+      onHoverIn={() => setHovered(true)}
+      onHoverOut={() => setHovered(false)}
+      style={[styles.cell, base]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    gap: 3,
+  },
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 3,
+  },
+  rowLabel: {
+    width: 88,
+    paddingRight: 8,
+  },
+  cell: {
+    flex: 1,
+    height: 26,
+    borderRadius: 4,
+    borderWidth: 2,
+  },
+  colLabel: {
+    flex: 1,
+    paddingTop: 2,
+  },
+  scale: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "flex-end",
+    gap: 4,
+    paddingTop: 8,
+  },
+  scaleSwatch: {
+    width: 14,
+    height: 10,
+    borderRadius: 3,
+  },
+});

package/src/icon.tsx

@@ -92,6 +92,7 @@ import History from "lucide-react-native/dist/esm/icons/history";
 import House from "lucide-react-native/dist/esm/icons/house";
 import Image from "lucide-react-native/dist/esm/icons/image";
 import Inbox from "lucide-react-native/dist/esm/icons/inbox";
+import Info from "lucide-react-native/dist/esm/icons/info";
 import Italic from "lucide-react-native/dist/esm/icons/italic";
 import Keyboard from "lucide-react-native/dist/esm/icons/keyboard";
 import Languages from "lucide-react-native/dist/esm/icons/languages";
@@ -283,6 +284,7 @@ const iconComponents = {
   house: House,
   image: Image,
   inbox: Inbox,
+  info: Info,
   italic: Italic,
   keyboard: Keyboard,
   languages: Languages,

package/src/icon_button.tsx

@@ -10,6 +10,10 @@ interface IconButtonBase {
   testID?: string;
   icon: IconName;
   color?: "none" | "secondary" | "white";
+  /** `md` (28px, 18px glyph) for toolbars; `sm` (24px, 14px glyph) for
+   * inline affordances sitting next to body/sm text — e.g. the ⓘ in a
+   * CardHeader. Both keep a 40px touch target via hitSlop. */
+  size?: "md" | "sm";
   iconColor?: string;
   tooltipSide?: TooltipSide;
   onPress?: (event: GestureResponderEvent) => void;
@@ -34,6 +38,7 @@ export function IconButton(props: IconButtonProps) {
     iconColor,
     onPress,
     color = "none",
+    size = "md",
     tooltip,
     tooltipSide,
     accessibilityLabel,
@@ -56,12 +61,15 @@ export function IconButton(props: IconButtonProps) {
       tooltipSide={tooltipSide}
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel ?? tooltip}
-      style={[styles.button, styles[color], disabled && styles.disabled, style]}
+      style={[styles.button, styles[size], styles[color], disabled && styles.disabled, style]}
       onPress={handlePress}
       disabled={disabled}
+      // 40px touch target regardless of visual size (28 + 2×6 / 24 + 2×8)
+      // without shifting surrounding layouts.
+      hitSlop={size === "sm" ? 8 : 6}
     >
       <Icon
-        size={18}
+        size={size === "sm" ? 14 : 18}
         name={icon}
         color={iconColor || (color === "white" ? colors.white : colors.zinc[700])}
       />
@@ -76,9 +84,15 @@ const styles = StyleSheet.create({
     alignItems: "center",
     justifyContent: "center",
     borderRadius: 999,
+  },
+  md: {
     width: 28,
     height: 28,
   },
+  sm: {
+    width: 24,
+    height: 24,
+  },
   disabled: {
     opacity: 0.3,
   },

package/src/index.css

@@ -353,6 +353,7 @@ html {
    - Frontend: /fonts/Inter_*.woff2 (served from public/)
    - Extension: fonts/Inter_*.woff2 (relative, in dist/fonts/)
    See frontend/public/fonts/ and browser_extension/public/fonts.css.
-   Contexts without a stable font-file path (custom-code apps served under the
-   /v1/apps/{id}/asset/ proxy) can `import "@lotics/ui/fonts.css"` — a
-   path-independent base64 @font-face bundle. See src/fonts.css. */
+   Contexts without a stable font-file path (custom-code apps served from a
+   per-app deploy origin) can `import "@lotics/ui/fonts.css"` — it loads Inter
+   from static.lotics.ai by absolute, CORS-enabled URL, so it works from any
+   origin. See src/fonts.css. */

package/src/info_popover.tsx

@@ -17,21 +17,19 @@ export interface InfoPopoverProps {
 }
 
 /**
- * A "?" icon button that opens a popover explaining something — a metric, a
+ * The ⓘ button that opens a popover explaining something — a metric, a
  * field, a setting. The middle ground between Tooltip (a short hover label)
  * and composing Popover directly (rich, interactive content): a labeled,
  * keyboard-accessible help affordance for a sentence or two of text.
+ * Sized to sit inline next to sm/body text (a CardHeaderTitle, a form
+ * label) without inflating the line.
  */
 export function InfoPopover(props: InfoPopoverProps) {
   const { text, accessibilityLabel = "More information", side = "bottom", align = "end" } = props;
   return (
     <Popover side={side} align={align}>
       <PopoverTrigger>
-        <IconButton
-          icon="message-circle-question-mark"
-          iconColor={colors.zinc[500]}
-          accessibilityLabel={accessibilityLabel}
-        />
+        <IconButton icon="info" size="sm" iconColor={colors.zinc[500]} accessibilityLabel={accessibilityLabel} />
       </PopoverTrigger>
       <PopoverContent style={styles.content} disableBodyScroll>
         <Text size="sm" color="muted">

package/src/kpi_card.tsx

@@ -2,6 +2,7 @@ import { View, StyleSheet, type ViewStyle, type StyleProp } from "react-native";
 import { Text } from "./text";
 import { Metric, type MetricFormat, type MetricSize, type MetricTone } from "./metric";
 import { TrendChip } from "./trend_chip";
+import { InfoPopover } from "./info_popover";
 import { SPACE } from "./spacing";
 
 interface KPICardProps {
@@ -13,6 +14,8 @@ interface KPICardProps {
   currency?: string;
   locale?: string;
   emptyLabel?: string;
+  /** Abbreviate large values (≥1 triệu) — see Metric.compact. */
+  compact?: boolean;
   /** Numeric size hint. Default `lg`; pass `hero` for the dominant
    * metric in a card; `md` for supporting metrics in a horizontal strip. */
   size?: MetricSize;
@@ -23,10 +26,12 @@ interface KPICardProps {
   trend?: number | null;
   /**
    * Goes below the value. Free text. Typical uses: comparator detail
-   * ("Tháng trước: 50.000.000 đ"), unit hint ("Hồ sơ"), or short caveat
-   * ("Tính theo ngày tạo").
+   * ("Last month: 50,000,000 ₫"), unit hint, or short caveat.
    */
   caption?: string;
+  /** What this metric means / how it's computed — renders the ⓘ next to
+   * the label, opening the explanation in a popover. */
+  info?: string;
   style?: StyleProp<ViewStyle>;
 }
 
@@ -44,12 +49,15 @@ interface KPICardProps {
  * mediocre dashboards.
  */
 export function KPICard(props: KPICardProps) {
-  const { label, value, format, currency, locale, emptyLabel, size = "lg", tone, trend, caption, style } = props;
+  const { label, value, format, currency, locale, emptyLabel, compact, size = "lg", tone, trend, caption, info, style } = props;
   return (
     <View style={[styles.container, style]}>
-      <Text size="xs" color="muted" transform="uppercase">
-        {label}
-      </Text>
+      <View style={styles.labelRow}>
+        <Text size="xs" color="muted" transform="uppercase">
+          {label}
+        </Text>
+        {info ? <InfoPopover text={info} accessibilityLabel={`About ${label}`} /> : null}
+      </View>
       <View style={styles.valueRow}>
         <Metric
           value={value}
@@ -57,6 +65,7 @@ export function KPICard(props: KPICardProps) {
           currency={currency}
           locale={locale}
           emptyLabel={emptyLabel}
+          compact={compact}
           size={size}
           tone={tone}
         />
@@ -73,5 +82,9 @@ export function KPICard(props: KPICardProps) {
 
 const styles = StyleSheet.create({
   container: { gap: SPACE.xs },
+  // Reserve the inline ⓘ button's height (sm IconButton = 24) on EVERY label row
+  // so columns with and without `info` center their labels — and thus their value
+  // rows — on the same baseline. Without this the no-info columns sit 4px higher.
+  labelRow: { flexDirection: "row", alignItems: "center", gap: 2, minHeight: 24 },
   valueRow: { flexDirection: "row", alignItems: "baseline", gap: SPACE.sm, flexWrap: "wrap" },
 });

package/src/kpi_strip.tsx

@@ -0,0 +1,89 @@
+import { StyleSheet, View } from "react-native";
+import { Card } from "./card";
+import { colors } from "./colors";
+import { KPICard } from "./kpi_card";
+import type { MetricFormat, MetricSize, MetricTone } from "./metric";
+
+export interface KPIStripItem {
+  /** Short uppercase label above the value. */
+  label: string;
+  value: number | string | null | undefined;
+  format?: MetricFormat;
+  currency?: string;
+  locale?: string;
+  emptyLabel?: string;
+  tone?: MetricTone;
+  /** Abbreviate large values (≥1 triệu → "486 tr") — strip columns are
+   *  narrow; the full figure belongs in the content below. */
+  compact?: boolean;
+  /** Optional ±% trend chip — the "is this good?" indicator. */
+  trend?: number | null;
+  /** Optional comparator/unit line below the value. */
+  caption?: string;
+  /** What this metric means / how it's computed — the ⓘ next to the label
+   * opens it in a popover. KPI strips are INFORMATIONAL: filtering belongs
+   * to the tabs/chips below, never to the strip. */
+  info?: string;
+}
+
+export interface KPIStripProps {
+  items: KPIStripItem[];
+  /** Value scale, uniform across every column by design. Default `lg` —
+   *  the big-number dashboard register. */
+  size?: MetricSize;
+}
+
+/**
+ * THE stat band at the top of a screen — one Card, hairline-divided columns
+ * of KPICard with a uniform value scale. Screens must not hand-compose stat
+ * strips: the same four-numbers-in-a-row should look identical on a
+ * dashboard, an inventory register, or a payroll page. Wraps on narrow
+ * screens (columns keep a 180px floor).
+ */
+export function KPIStrip(props: KPIStripProps) {
+  const { items, size = "lg" } = props;
+  return (
+    <Card style={styles.card}>
+      <View style={styles.row}>
+        {items.map((item, i) => (
+          <View key={item.label} style={[styles.cell, i > 0 && styles.divided]}>
+            <KPICard
+              label={item.label}
+              value={item.value}
+              format={item.format}
+              currency={item.currency}
+              locale={item.locale}
+              emptyLabel={item.emptyLabel}
+              compact={item.compact}
+              tone={item.tone}
+              trend={item.trend}
+              caption={item.caption}
+              info={item.info}
+              size={size}
+            />
+          </View>
+        ))}
+      </View>
+    </Card>
+  );
+}
+
+const styles = StyleSheet.create({
+  card: {
+    padding: 0,
+  },
+  row: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+  },
+  cell: {
+    flexGrow: 1,
+    flexBasis: 180,
+    paddingVertical: 16,
+    paddingHorizontal: 20,
+  },
+  divided: {
+    borderLeftWidth: 1,
+    borderLeftColor: colors.zinc[100],
+  },
+});