@lotics/ui 45.9.0 → 45.10.1

package/src/waterfall_chart.tsx

@@ -0,0 +1,398 @@
+import { useMemo } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors, solid } from "./colors";
+import { useLoticsLocale } from "./locale";
+import { SPACE } from "./spacing";
+import { Text } from "./text";
+
+/**
+ * What a bar STANDS for, which is also what decides where it starts.
+ *
+ * `basis` and `total` are LEVELS — they stand on zero, so their `value` is read
+ * as an absolute height. `delta` is a STEP — it floats between the level before
+ * it and the level after, so its `value` is read as a signed contribution.
+ */
+export type WaterfallKind = "basis" | "delta" | "total";
+
+export interface WaterfallItem {
+  key: string;
+  /** The step's name, under the bar ("Giá vốn", "Ad spend"). */
+  label: string;
+  /** `basis`/`total`: the level the bar reaches. `delta`: the signed step. */
+  value: number;
+  /** Default `delta`. */
+  kind?: WaterfallKind;
+  /**
+   * A neutral QUALIFIER under the label — a count, a period, a basis of
+   * calculation. Never a problem or a state: one bar's meta being a fact and
+   * another's a complaint is what makes the row read inconsistent.
+   */
+  meta?: string;
+  /**
+   * Override the derived colour. The defaults already carry the meaning —
+   * a step that ADDS is `emerald`, one that SUBTRACTS is `red`, a basis is
+   * neutral, and a closing total takes the colour of its own sign — so reach
+   * for this only when the domain colours a step against its arithmetic.
+   */
+  color?: string;
+}
+
+/** One bar's resolved geometry, in value units and as a fraction of the span. */
+export interface WaterfallBar {
+  key: string;
+  label: string;
+  meta?: string;
+  kind: WaterfallKind;
+  value: number;
+  color: string;
+  /** The lower and upper level this bar spans, in value units. */
+  from: number;
+  to: number;
+  /** Where the bar starts, as a 0–1 fraction of the plotted span. */
+  offset: number;
+  /** How much of the plotted span the bar covers, 0–1. */
+  size: number;
+  /** The running level this bar leaves behind — where its connector sits. */
+  level: number;
+  /** That same level as a 0–1 fraction of the plotted span. */
+  levelFraction: number;
+}
+
+export interface WaterfallLayout {
+  bars: WaterfallBar[];
+  /** The plotted span, which always includes zero. */
+  min: number;
+  max: number;
+  /** Zero as a 0–1 fraction of the span — where the baseline is drawn. */
+  zeroFraction: number;
+}
+
+function derivedColor(kind: WaterfallKind, value: number, level: number): string {
+  if (kind === "basis") return colors.zinc[400];
+  if (kind === "total") return level < 0 ? solid("red") : solid("emerald");
+  return value < 0 ? solid("red") : solid("emerald");
+}
+
+/**
+ * Walk the items into bar geometry. Pure, exported and separately tested,
+ * because a bridge is only worth drawing if the floating bars land on the
+ * levels the arithmetic says they do — and that is the one part of the chart
+ * no screenshot can confirm.
+ */
+export function waterfallLayout(items: WaterfallItem[]): WaterfallLayout {
+  let level = 0;
+  const walked = items.map((item) => {
+    const kind = item.kind ?? "delta";
+    const from = kind === "delta" ? level : 0;
+    const to = kind === "delta" ? level + item.value : item.value;
+    level = to;
+    return { item, kind, from, to, level };
+  });
+
+  // Zero is always in the span: a bridge is read against its baseline, and a
+  // set of bars that never touches it would otherwise float on a scale that
+  // exaggerates every step.
+  const levels = walked.flatMap((w) => [w.from, w.to]);
+  const min = Math.min(0, ...levels);
+  const max = Math.max(0, ...levels);
+  const span = max - min || 1;
+
+  const bars: WaterfallBar[] = walked.map((w) => {
+    const low = Math.min(w.from, w.to);
+    const high = Math.max(w.from, w.to);
+    return {
+      key: w.item.key,
+      label: w.item.label,
+      meta: w.item.meta,
+      kind: w.kind,
+      value: w.item.value,
+      color: w.item.color ?? derivedColor(w.kind, w.item.value, w.level),
+      from: low,
+      to: high,
+      offset: (low - min) / span,
+      size: (high - low) / span,
+      level: w.level,
+      levelFraction: (w.level - min) / span,
+    };
+  });
+
+  return { bars, min, max, zeroFraction: (0 - min) / span };
+}
+
+export interface WaterfallChartProps {
+  items: WaterfallItem[];
+  /**
+   * `vertical` is the classic bridge — columns left to right, the shape most
+   * readers already know. `horizontal` turns it into rows, which is what a
+   * narrow container or long step names need: a column 70px wide cannot hold
+   * "Giá vốn và phí giao hàng" and a rotated label is not an answer.
+   */
+  orientation?: "vertical" | "horizontal";
+  /** Formats every figure on the chart. Pass the surface's own money formatter. */
+  formatNumber?: (n: number) => string;
+  /** Plot height in px for `vertical`; bar thickness for `horizontal`. */
+  height?: number;
+  emptyLabel?: string;
+}
+
+const defaultFormatNumber = (n: number): string =>
+  new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 }).format(n);
+
+/**
+ * The BRIDGE: an opening level, the signed steps that move it, and the level
+ * they close at — revenue walked down to net, budget walked to actual, opening
+ * balance walked to closing. Each step floats between the level before it and
+ * the level after, connectors carry the eye across, and the run of colour says
+ * which way the money went without the reader adding anything up.
+ *
+ * Pick it over `Ledger` when the reader is scanning for SHAPE — which step is
+ * the big one, does the total survive — and over `BarChart` whenever the bars
+ * are steps in one arithmetic rather than independent quantities: a bar chart
+ * of a P&L draws five columns that all start at zero and states a comparison
+ * nobody meant. `Ledger` stays right where the figures must be read exactly and
+ * reconciled line by line; a dashboard wants this.
+ *
+ * The steps must be the arithmetic, all of it — a bridge earns its trust by
+ * closing on the total it draws, so derive the steps and the close from ONE
+ * computation rather than from two that can drift apart.
+ */
+export function WaterfallChart(props: WaterfallChartProps) {
+  const locale = useLoticsLocale();
+  const {
+    items,
+    orientation = "vertical",
+    formatNumber = defaultFormatNumber,
+    height = orientation === "vertical" ? 180 : 14,
+    emptyLabel = locale.chart.noData,
+  } = props;
+
+  const layout = useMemo(() => waterfallLayout(items), [items]);
+
+  if (items.length === 0) {
+    return (
+      <View style={styles.empty}>
+        <Text color="muted">{emptyLabel}</Text>
+      </View>
+    );
+  }
+
+  // Rows: the step's name and its figure on one line, the bar on the FULL width
+  // beneath them. Not a label column / track / figure column — three fixed
+  // columns leave the track a sliver of a card, which is the one part of a
+  // bridge that has to be seen rather than read, and it truncates the figure
+  // that is the other part.
+  if (orientation === "horizontal") {
+    return (
+      <View style={styles.rows}>
+        {layout.bars.map((bar, i) => (
+          <View key={bar.key} style={styles.row}>
+            <View style={styles.head}>
+              <View style={styles.headText}>
+                <Text
+                  size="sm"
+                  weight={bar.kind === "delta" ? "regular" : "medium"}
+                  numberOfLines={2}
+                  leading="tight"
+                >
+                  {bar.label}
+                </Text>
+                {bar.meta ? (
+                  <Text size="xs" color="muted" numberOfLines={1} leading="tight">
+                    {bar.meta}
+                  </Text>
+                ) : null}
+              </View>
+              <Text
+                size="sm"
+                tabular
+                align="right"
+                weight={bar.kind === "delta" ? "regular" : "medium"}
+              >
+                {formatNumber(bar.kind === "delta" ? bar.value : bar.level)}
+              </Text>
+            </View>
+            <View style={[styles.rowTrack, { height }]}>
+              {layout.min < 0 ? (
+                <View
+                  style={[styles.baselineVertical, { left: `${layout.zeroFraction * 100}%` }]}
+                />
+              ) : null}
+              <View
+                style={[
+                  styles.bar,
+                  styles.barHorizontal,
+                  {
+                    left: `${bar.offset * 100}%`,
+                    width: `${bar.size * 100}%`,
+                    backgroundColor: bar.color,
+                  },
+                ]}
+              />
+              {i < layout.bars.length - 1 ? (
+                <View
+                  style={[styles.connectorVertical, { left: `${bar.levelFraction * 100}%` }]}
+                />
+              ) : null}
+            </View>
+          </View>
+        ))}
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.columns}>
+      <View style={[styles.plot, { height }]}>
+        {layout.min < 0 ? (
+          <View
+            style={[styles.baselineHorizontal, { bottom: `${layout.zeroFraction * 100}%` }]}
+          />
+        ) : null}
+        {layout.bars.map((bar, i) => (
+          <View key={bar.key} style={styles.column}>
+            <View
+              style={[
+                styles.bar,
+                styles.barVertical,
+                {
+                  bottom: `${bar.offset * 100}%`,
+                  height: `${bar.size * 100}%`,
+                  backgroundColor: bar.color,
+                },
+              ]}
+            />
+            {i < layout.bars.length - 1 ? (
+              <View
+                style={[styles.connectorHorizontal, { bottom: `${bar.levelFraction * 100}%` }]}
+              />
+            ) : null}
+          </View>
+        ))}
+      </View>
+      <View style={styles.captions}>
+        {layout.bars.map((bar) => (
+          <View key={bar.key} style={styles.caption}>
+            <Text
+              size="sm"
+              tabular
+              align="center"
+              weight={bar.kind === "delta" ? "regular" : "medium"}
+              numberOfLines={1}
+            >
+              {formatNumber(bar.kind === "delta" ? bar.value : bar.level)}
+            </Text>
+            <Text size="xs" color="muted" align="center" leading="tight" numberOfLines={2}>
+              {bar.label}
+            </Text>
+            {bar.meta ? (
+              <Text size="xs" color="muted" align="center" leading="tight" numberOfLines={1}>
+                {bar.meta}
+              </Text>
+            ) : null}
+          </View>
+        ))}
+      </View>
+    </View>
+  );
+}
+
+// The connector is a hairline in the SAME ink as a table's rules: it joins two
+// bars, it is not a third quantity, so it must never read as one.
+const CONNECTOR = colors.zinc[300];
+
+/** The gap between two steps in `horizontal` — and the connector's own length. */
+const ROW_GAP = SPACE.lg;
+
+const styles = StyleSheet.create({
+  empty: {
+    justifyContent: "center",
+  },
+  columns: {
+    gap: SPACE.sm,
+  },
+  plot: {
+    flexDirection: "row",
+    alignItems: "stretch",
+    gap: SPACE.sm,
+  },
+  column: {
+    flex: 1,
+    position: "relative",
+  },
+  // The bar is absolute in BOTH orientations, and the axis it does NOT float on
+  // has to be pinned — a horizontal bar given only `left`/`width` collapses to
+  // its `minHeight` and draws a hairline where a bar was asked for.
+  bar: {
+    position: "absolute",
+    borderRadius: 2,
+  },
+  barVertical: {
+    left: 0,
+    right: 0,
+    minHeight: 2,
+  },
+  barHorizontal: {
+    top: 0,
+    bottom: 0,
+    minWidth: 2,
+  },
+  // Bridges the gap to the NEXT column, drawn from inside this one so the
+  // connector cannot drift out of step with the bar whose level it leaves.
+  connectorHorizontal: {
+    position: "absolute",
+    left: "100%",
+    width: SPACE.sm,
+    height: 1,
+    backgroundColor: CONNECTOR,
+  },
+  baselineHorizontal: {
+    position: "absolute",
+    left: 0,
+    right: 0,
+    height: 1,
+    backgroundColor: CONNECTOR,
+  },
+  captions: {
+    flexDirection: "row",
+    gap: SPACE.sm,
+  },
+  caption: {
+    flex: 1,
+    gap: 1,
+  },
+  // Between two steps, more than between a step's own name, figure and bar:
+  // those three are one object, and the connector spans exactly this gap.
+  rows: {
+    gap: ROW_GAP,
+  },
+  row: {
+    gap: SPACE.xs,
+  },
+  head: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: SPACE.md,
+  },
+  headText: {
+    flex: 1,
+    minWidth: 0,
+    gap: 1,
+  },
+  rowTrack: {
+    position: "relative",
+  },
+  connectorVertical: {
+    position: "absolute",
+    top: "100%",
+    height: ROW_GAP,
+    width: 1,
+    backgroundColor: CONNECTOR,
+  },
+  baselineVertical: {
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    width: 1,
+    backgroundColor: CONNECTOR,
+  },
+});