@lotics/ui 45.9.0 → 45.10.1

package/docs/testing.md

@@ -3,8 +3,7 @@
 Three kit anatomies where the accessibility tree says one thing and an automated
 driver has to do another. Each is **by design** — the shape that makes the
 component correct for a keyboard and a screen reader is the shape that defeats a
-naive `click()` — so each will read as a bug the first time, and the wrong
-reaction (`force: true`, or "the component is broken") costs a debugging session.
+naive `click()` — so each will read as a bug the first time.
 
 Everything here is true wherever the kit renders. The iframe that a Lotics app
 runs inside adds one more rule on top — `lotics docs building_an_app` § 8.
@@ -25,9 +24,7 @@ So the a11y tree shows `button "Open ACME-1042"`, and clicking it fails:
 subtree intercepts pointer events
 ```
 
-That is the design working, not a defect — the visible row is above the door
-precisely so a pointer lands on the row rather than the door. Drive it the way a
-mouse user does:
+That is the design working, not a defect. Drive it the way a mouse user does:
 
 - **click the row container** — the `generic [cursor=pointer]` wrapping the door;
   the click bubbles to `PressableRow`
@@ -66,5 +63,4 @@ and the window are the right ones. From the dragged element,
 
 Then check **both** halves: re-snapshot for the optimistic move, and re-read the
 record to confirm the mutation actually persisted. An optimistic move that never
-reached the server looks identical on screen, which is the whole reason to check
-the second one.
+reached the server looks identical on screen.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "45.9.0",
+  "version": "45.10.1",
   "type": "module",
   "exports": {
     "./vite": {
@@ -83,6 +83,8 @@
     "./gantt": "./src/gantt/index.ts",
     "./progress_ring": "./src/progress_ring.tsx",
     "./stacked_progress_bar": "./src/stacked_progress_bar.tsx",
+    "./stacked_bar_chart": "./src/stacked_bar_chart.tsx",
+    "./waterfall_chart": "./src/waterfall_chart.tsx",
     "./legend_item": "./src/legend_item.tsx",
     "./breakdown": "./src/breakdown.tsx",
     "./funnel": "./src/funnel.tsx",

package/src/bar_chart.tsx

@@ -1,4 +1,4 @@
-import { View, StyleSheet } from "react-native";
+import { View, StyleSheet, type ViewStyle } from "react-native";
 import { useMemo } from "react";
 import { Text } from "./text";
 import { colors } from "./colors";
@@ -293,7 +293,25 @@ const styles = StyleSheet.create({
   horizontalAxisTick: {
     position: "absolute",
     alignItems: "center",
-    transform: [{ translateX: -12 }],
+    /**
+     * `max-content` + a half-width shift, so the label sizes to its own text and
+     * then centres on its tick at ANY label length.
+     *
+     * Both halves are load-bearing. An absolutely-positioned box with only
+     * `left` set is sized by the space remaining to the container's RIGHT EDGE,
+     * so the tick at 100% shrink-wraps to a few pixels and breaks its text
+     * across two lines — visible only at the widths where that label happens
+     * not to fit, which is why it survives a desktop-only pass. And a fixed
+     * pixel nudge cannot centre anything: it assumes one label width, so every
+     * tick is off by however far its own label differs from the guess.
+     */
+    transform: "translateX(-50%)",
+    // The one style here RN cannot type: `DimensionValue` covers numbers and
+    // percentages, and `max-content` is a real CSS width that react-native-web
+    // passes straight through. Nothing typed does this job — a number floor
+    // only moves the breaking point to the next longer label, and dropping to
+    // the track's own width is what breaks it in the first place.
+    ...({ width: "max-content" } as unknown as ViewStyle),
   },
   tickMark: {
     width: 1,

package/src/chip_group.tsx

@@ -4,9 +4,11 @@ import { PressableHighlight } from "./pressable_highlight";
 import { chipSurfaceStyle } from "./control_surface";
 
 // One-of-N chips: every option visible, one tap to switch, the row wraps on
-// narrow widths. Quiet zinc styling — bordered white at rest, dark fill when
-// active (color stays reserved for status + primary actions). Two jobs, one
-// control:
+// narrow widths. Quiet zinc styling — bordered white at rest, and the active one
+// keeps that same ground and takes a doubled zinc-900 EDGE instead, so a
+// selection never spends the brand and never speaks the row's language (the
+// reasoning is on `chipSurfaceStyle`). Colour stays reserved for status +
+// primary actions. Two jobs, one control:
 //   - a SMALL, HOT FILTER the user flips between constantly ("narrow this
 //     view") — model the unfiltered state as an explicit option (e.g. "All").
 //   - a small REQUIRED single-select in a form / composer (a call outcome, a

package/src/finding.tsx

@@ -142,7 +142,7 @@ export function Finding(props: FindingProps) {
             {readings.map((reading, index) => (
               <View key={`${reading.source}-${index}`} style={styles.reading}>
                 <SourceName label={reading.source} onOpen={props.onOpenSource} />
-                <Text size="sm" weight="medium" tabular numberOfLines={1}>
+                <Text size="sm" weight="medium" tabular numberOfLines={1} style={styles.readingValue}>
                   {reading.value}
                 </Text>
               </View>
@@ -181,13 +181,18 @@ export function Finding(props: FindingProps) {
 function SourceName({ label, onOpen }: { label: string; onOpen?: (source: string) => void }) {
   if (!onOpen) {
     return (
-      <Text size="sm" color="muted" numberOfLines={1}>
+      <Text size="sm" color="muted" numberOfLines={1} style={styles.sourceName}>
         {label}
       </Text>
     );
   }
   return (
-    <PressableHighlight onPress={() => onOpen(label)} accessibilityRole="link" accessibilityLabel={label}>
+    <PressableHighlight
+      onPress={() => onOpen(label)}
+      accessibilityRole="link"
+      accessibilityLabel={label}
+      style={styles.sourceName}
+    >
       <Text size="sm" weight="medium" decoration="underline" numberOfLines={1}>
         {label}
       </Text>
@@ -217,4 +222,14 @@ const styles = StyleSheet.create({
   // each source with its own value at every width and needs no separator at all.
   readings: { flexDirection: "column", alignItems: "flex-start", gap: 4 },
   reading: { flexDirection: "row", alignItems: "baseline", gap: 5, minWidth: 0 },
+  // The same split as `title`/`delta` one row up, for the same reason: the SOURCE
+  // is a label and gives way, the VALUE is the figure and never does. Both halves
+  // are required on the label — a React Native `Text` is `flexShrink: 0` unlike
+  // the web, and `flexShrink` alone then floors it at its longest word. Without
+  // this pair the row laid both children out at intrinsic width and simply ran
+  // off the card: measured at x=790 in a 390px frame, clipped, with no page
+  // scroll to reach it — so on a phone the evidence a Finding exists to show was
+  // the part you could not read.
+  sourceName: { flexShrink: 1, minWidth: 0 },
+  readingValue: { flexShrink: 0 },
 });

package/src/line_chart.tsx

@@ -4,6 +4,7 @@ import { colors } from "./colors";
 import { useMemo, useState, useCallback } from "react";
 import Svg, { Circle, Defs, Line, LinearGradient, Polygon, Polyline, Stop } from "react-native-svg";
 import { useLoticsLocale } from "./locale";
+import { lineChartLabelIndices } from "./line_chart_labels";
 
 export interface LineChartPoint {
   x: string | number;
@@ -96,20 +97,10 @@ export function LineChart(props: LineChartProps) {
   const visibleLabels = useMemo(() => {
     if (data.length === 0 || chartWidth === 0) return [];
 
-    const minLabelWidth = 50;
-    const maxLabels = Math.max(2, Math.floor(chartWidth / minLabelWidth));
-    const step = Math.max(1, Math.ceil(data.length / maxLabels));
-
-    const labels: { index: number; label: string }[] = [];
-    for (let i = 0; i < data.length; i++) {
-      const isFirst = i === 0;
-      const isLast = i === data.length - 1;
-      const isStep = i % step === 0;
-      if (isFirst || isLast || isStep) {
-        labels.push({ index: i, label: formatXLabel(data[i].x) });
-      }
-    }
-    return labels;
+    return lineChartLabelIndices(data.length, chartWidth).map((index) => ({
+      index,
+      label: formatXLabel(data[index].x),
+    }));
   }, [data, chartWidth, formatXLabel]);
 
   if (data.length === 0) {

package/src/line_chart_labels.ts

@@ -0,0 +1,32 @@
+/**
+ * Which of a line chart's x positions get a printed label.
+ *
+ * A label is roughly `minLabelWidth` wide, so only so many fit across the
+ * track; the rest are thinned out. The rule that matters is WHERE the thinning
+ * is anchored: stepping forwards from the first point and then forcing the last
+ * one in collides whenever the series length minus one is not a multiple of the
+ * step — the newest label lands a few pixels from the one before it while every
+ * other pair is a full step apart. Anchoring on the LAST point makes the spacing
+ * uniform by construction, and the last point is the one a reader looks up
+ * first. The first point is then kept only when it clears the same distance.
+ */
+export function lineChartLabelIndices(
+  count: number,
+  chartWidth: number,
+  minLabelWidth = 50,
+): number[] {
+  if (count <= 0 || chartWidth <= 0) return [];
+  if (count === 1) return [0];
+
+  const last = count - 1;
+  const maxLabels = Math.max(2, Math.floor(chartWidth / minLabelWidth));
+  const step = Math.max(1, Math.ceil(count / maxLabels));
+
+  const kept: number[] = [];
+  for (let i = last; i >= 0; i -= step) kept.unshift(i);
+
+  const firstKept = kept[0] ?? 0;
+  if (firstKept > 0 && (firstKept / last) * chartWidth >= minLabelWidth) kept.unshift(0);
+
+  return kept;
+}

package/src/page_header.tsx

@@ -48,12 +48,20 @@ export function PageHeader(props: PageHeaderProps) {
   // then floors the item at its MIN-CONTENT width — the longest word — so
   // `minWidth: 0` is what lets it actually wrap. `DetailRow`'s spread value is
   // the same pair for the same reason.
+  // `flexWrap` is the floor under the shrink rule below, not a competing one. A
+  // title shrinks only as far as its longest WORD; past that, min-content title
+  // plus a full-width CTA can still exceed the row, and a row that cannot wrap
+  // has nowhere to put the excess but off the edge — measured at 393px of
+  // content in a 360px frame, clipped, scrolling sideways, which `composition.md`
+  // bans outright. Wrapping drops the actions to their own line and keeps the
+  // stated bargain intact: the CTA stays reachable, the header is merely taller.
   const titleRow = (
     <View
       style={{
         flexDirection: "row",
         alignItems: "center",
         justifyContent: "space-between",
+        flexWrap: "wrap",
         gap: 12,
       }}
     >
@@ -73,7 +81,11 @@ export function PageHeader(props: PageHeaderProps) {
             below its own icon is not a smaller control, it is a broken one. */}
         {trailing !== undefined && <View style={{ flexShrink: 0 }}>{trailing}</View>}
       </View>
-      {actions}
+      {/* Wrapped so which side gives way is STATED rather than left to whatever
+          the caller happened to pass. A bare `{actions}` inherited its own
+          shrink behaviour, so the row's bargain held or broke depending on the
+          CTA — and a bargain that depends on the other party is not one. */}
+      {actions !== undefined && <View style={{ flexShrink: 0 }}>{actions}</View>}
     </View>
   );
 

package/src/pressable_row.tsx

@@ -14,10 +14,11 @@ export interface PressableRowProps {
   marked?: boolean;
   /**
    * - "register" (THE record-list default): a rounded row whose hover/open/`marked`
-   *   wash spans the FULL row width (incl. nested controls); content stays on the
-   *   20px column gutter so a `Table` header and its cells still align. The `Table`
-   *   separates rows with a `Divider` (the wash is the hover/selection state, the
-   *   hairline the resting separation) — every app inherits this register look.
+   *   wash spans the FULL row width (incl. nested controls); the wash BLEEDS outward
+   *   and the content stays on the container's own edge, so a `Table` header and its
+   *   cells still align. The `Table` draws NOTHING between rows — it spaces them by
+   *   4px and the wash is the only mark a row makes — every app inherits this
+   *   register look.
    * - "bleed" (legacy): px-20, square wash to the edges, `Divider`-separated.
    *   The pre-rounded register row — kept for an edge-to-edge data grid that
    *   genuinely wants hard rules, not the floating default.
@@ -143,7 +144,8 @@ const styles = StyleSheet.create({
     paddingHorizontal: ROW_WASH_BLEED,
     marginHorizontal: -ROW_WASH_BLEED,
   },
-  // Square, full-bleed — lines up with the Dividers between register rows. Legacy.
+  // Square, full-bleed — the pre-rounded register row, for a grid that draws its own
+  // rules between rows. The register variant draws none. Legacy.
   bleed: {
     paddingHorizontal: ROW_WASH_BLEED,
     marginHorizontal: -ROW_WASH_BLEED,

package/src/stacked_bar_chart.tsx

@@ -0,0 +1,197 @@
+import { useMemo } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors } from "./colors";
+import { LegendItem } from "./legend_item";
+import { useLoticsLocale } from "./locale";
+import { SPACE } from "./spacing";
+import { Text } from "./text";
+import type { TextColor } from "./text_utils";
+
+export interface StackedBarSeries {
+  key: string;
+  label: string;
+  color: string;
+}
+
+export interface StackedBarRow {
+  key: string;
+  /** The entity this row is about — a campaign, a depot, a month. */
+  label: string;
+  /** A neutral qualifier beside the label ("Đang chạy", "12 đơn"). */
+  meta?: string;
+  /** Per-series magnitudes, keyed by `StackedBarSeries.key`. Negatives are dropped. */
+  values: Record<string, number>;
+  /** The row's headline figure, right of the label. Already formatted by the caller. */
+  value?: string;
+  valueTone?: TextColor;
+  /** One full sentence under the bar, saying what the segments amount to. */
+  caption?: string;
+}
+
+export interface StackedBarChartProps {
+  series: StackedBarSeries[];
+  rows: StackedBarRow[];
+  /**
+   * The shared scale every row is measured on. Defaults to the largest row
+   * total, which is what makes this a chart: leave it alone unless a second
+   * chart beside this one must be read against the same ruler.
+   */
+  max?: number;
+  /** Bar thickness in px. Default 12. */
+  height?: number;
+  /** Render the series legend above the rows. Default true. */
+  legend?: boolean;
+  emptyLabel?: string;
+}
+
+/**
+ * Rows of stacked bars on ONE SHARED SCALE — spend against return per campaign,
+ * cost make-up per product line, hours per crew. Each row's bar is as long as
+ * that row's total is against the largest row, and the segments inside it split
+ * that length; so bar LENGTH answers "how big is this one" and the segment run
+ * answers "what is it made of", in one pass.
+ *
+ * That shared scale is the whole difference from `StackedProgressBar`, and the
+ * reason this is a separate component rather than a prop on it. That one draws
+ * ONE whole split across segments and fills its track whatever the total — put
+ * it on ten rows and ten unequal totals draw ten equal bars, which reads as a
+ * chart and states nothing. `Breakdown` is the other neighbour: one whole, one
+ * bar, ranked share rows beneath it. Reach here the moment there are SEVERAL
+ * wholes to compare.
+ *
+ * Segments carry meaning by colour, so the legend is on by default and the
+ * colours are the caller's — one `ColorName` family per dimension, per the
+ * kit's colour discipline. A row's `caption` is the second channel: colour
+ * alone never has to carry the point.
+ */
+export function StackedBarChart(props: StackedBarChartProps) {
+  const locale = useLoticsLocale();
+  const {
+    series,
+    rows,
+    max: maxProp,
+    height = 12,
+    legend = true,
+    emptyLabel = locale.chart.noData,
+  } = props;
+
+  const totals = useMemo(
+    () =>
+      rows.map((r) => series.reduce((t, s) => t + Math.max(0, r.values[s.key] ?? 0), 0)),
+    [rows, series],
+  );
+  const max = maxProp ?? Math.max(...totals, 0);
+
+  if (rows.length === 0) {
+    return (
+      <View style={styles.empty}>
+        <Text color="muted">{emptyLabel}</Text>
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      {legend ? (
+        <View style={styles.legend}>
+          {series.map((s) => (
+            <LegendItem key={s.key} color={s.color} label={s.label} />
+          ))}
+        </View>
+      ) : null}
+      <View style={styles.rows}>
+        {rows.map((row, i) => {
+          const total = totals[i];
+          const share = max > 0 ? total / max : 0;
+          return (
+            <View key={row.key} style={styles.row}>
+              {/* The name over its qualifier, the figure alongside — not three
+                  things on one line. A row's name is its identity, and a line
+                  that also has to fit a status and a figure spends a narrow
+                  container's width truncating exactly that. */}
+              <View style={styles.head}>
+                <View style={styles.headText}>
+                  <Text size="sm" weight="medium" numberOfLines={2} leading="tight">
+                    {row.label}
+                  </Text>
+                  {row.meta ? (
+                    <Text size="xs" color="muted" numberOfLines={1} leading="tight">
+                      {row.meta}
+                    </Text>
+                  ) : null}
+                </View>
+                {row.value ? (
+                  <Text size="sm" weight="medium" tabular align="right" color={row.valueTone}>
+                    {row.value}
+                  </Text>
+                ) : null}
+              </View>
+              <View style={[styles.track, { height }]}>
+                <View style={[styles.fill, { width: `${share * 100}%` }]}>
+                  {series
+                    .filter((s) => (row.values[s.key] ?? 0) > 0)
+                    .map((s) => (
+                      <View
+                        key={s.key}
+                        style={{ flex: row.values[s.key], backgroundColor: s.color }}
+                      />
+                    ))}
+                </View>
+              </View>
+              {row.caption ? (
+                <Text size="xs" color="muted">
+                  {row.caption}
+                </Text>
+              ) : null}
+            </View>
+          );
+        })}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  empty: {
+    justifyContent: "center",
+  },
+  container: {
+    gap: SPACE.md,
+  },
+  legend: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    gap: SPACE.md,
+  },
+  // Between two rows, more than between a row's own name, bar and sentence:
+  // the three belong to one campaign and have to read as one object.
+  rows: {
+    gap: SPACE.lg,
+  },
+  row: {
+    gap: 6,
+  },
+  head: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: SPACE.md,
+  },
+  headText: {
+    flex: 1,
+    minWidth: 0,
+    gap: 1,
+  },
+  // The track is the SHARED ruler; the fill is this row's share of it, and the
+  // segments split the fill. Three boxes, because collapsing the middle one is
+  // exactly how a stacked bar loses its scale.
+  track: {
+    borderRadius: 999,
+    overflow: "hidden",
+    backgroundColor: colors.zinc[100],
+  },
+  fill: {
+    flexDirection: "row",
+    height: "100%",
+    minWidth: 2,
+  },
+});

package/src/table.tsx

@@ -181,9 +181,9 @@ export interface TableProps {
  * THE columnar register — define `columns` once and the header band + every row's
  * cell widths come from it, so they can't drift (no hand-rolled `W` map, no
  * `<View style={{width}}>` per cell). Renders a full-bleed eyebrow header (a
- * sortable column becomes a `SortHeader`) and its `TableRow` children,
- * `Divider`-separated. Compose `TableRow` / `TableCell` for the body. For a
- * non-columnar list (entity piles, card stacks) use `PressableRow` directly.
+ * sortable column becomes a `SortHeader`) and its `TableRow` children, spaced by
+ * 4px with no rule between them. Compose `TableRow` / `TableCell` for the body.
+ * For a non-columnar list (entity piles, card stacks) use `PressableRow` directly.
  *
  * The register is container-responsive with no prop: when the measured width
  * can't fit every column it drops droppable columns by `priority`, and below
@@ -312,10 +312,10 @@ export interface TableGroupProps {
  * column: that is a sort, and it costs a band of chrome per value while telling
  * them what the cell beside it says.
  *
- * The band separates itself with AIR rather than a rule, because it is the
- * biggest boundary inside the register and the row hairlines are the smallest —
- * drawing both as lines makes them compete. The heading also takes no rule
- * beneath it, which would orphan the title from the rows it opens.
+ * The band separates itself with AIR rather than a rule, because the register
+ * already separates its own rows with air and keeps ONE line — the band capping
+ * the columns — so a second would compete with it. The heading takes no rule
+ * beneath it either, which would orphan the title from the rows it opens.
  *
  * A group's rows keep their own `ordinal` numbering if they carry one: restart
  * inside each band, where the reader's question is "which of these" rather than
@@ -609,8 +609,8 @@ const styles = StyleSheet.create({
     paddingTop: 16,
     paddingBottom: 16,
   },
-  // A hairline under the column header anchors the columns; the rows below it are
-  // Divider-separated.
+  // A hairline under the column header anchors the columns; the rows below it carry
+  // none — see the file header for why that boundary is the register's only rule.
   headerBandFilled: {
     // The literal neutral, not `accent_wash`: this band is a lid on the columns,
     // never a "you are here", and reading it through the brand token made a
@@ -644,11 +644,12 @@ const styles = StyleSheet.create({
   body: {
     gap: 4,
   },
-  // Air, not a rule. A band boundary is the LARGEST break inside a register and
-  // the row hairlines are the smallest; drawing both as lines makes the two
-  // compete and the grouping stops reading. The first band's heading sits under
-  // the column band's own hairline, so it takes less top space than the ones
-  // that follow — handled by the heading's own padding rather than by the caller.
+  // Air, not a rule. A band boundary is the LARGEST break inside a register, and the
+  // register does not rule the smallest one either — rows are spaced, not ruled — so
+  // a line here would be a second rule competing with the column band's, and the
+  // grouping stops reading. The first band's heading sits under the column band's own
+  // hairline, so it takes less top space than the ones that follow — handled by the
+  // heading's own padding rather than by the caller.
   groupHeading: {
     flexDirection: "row",
     alignItems: "center",