@lotics/ui 47.13.1 → 47.14.0

package/src/matrix.tsx

@@ -1,13 +1,28 @@
 import { Children, createContext, isValidElement, useContext, useMemo, type ReactNode } from "react";
-import { StyleSheet, View } from "react-native";
+import { ScrollView, StyleSheet, View } from "react-native";
 import { colors, withAlpha, type ColorName } from "./colors";
 import { Text } from "./text";
 import { FocusRingPressable } from "./focus_ring_pressable";
-import { matrixTotals, type MatrixAxisItem, type MatrixCellRef } from "./matrix_totals";
+import { LEADING_GAP } from "./cell_stack";
+import {
+  matrixHeatScale,
+  matrixTotals,
+  type MatrixAxisItem,
+  type MatrixCellRef,
+  type MatrixHeatScale,
+} from "./matrix_totals";
 import { useLoticsLocale } from "./locale";
 
 type Display = "number" | "heat" | "both";
 
+/** How much of the hue a wash may spend, per display. Behind a NUMBER the wash
+ *  has to stay under the glyphs; when the colour IS the value it takes the lot. */
+const HEAT_BAND: Record<Display, [number, number]> = {
+  both: [0.05, 0.45],
+  heat: [0.15, 1],
+  number: [0.05, 0.45],
+};
+
 interface MatrixContextValue {
   rows: MatrixAxisItem[];
   cols: MatrixAxisItem[];
@@ -20,6 +35,10 @@ interface MatrixContextValue {
   selected: MatrixCellRef | null;
   onSelectCell?: (cell: MatrixCellRef | null) => void;
   heatBase: string;
+  /** Value → alpha. The cells and the legend read this ONE function. */
+  heatAlpha: (value: number) => number;
+  /** The legend's swatch alphas, sampled from `heatAlpha`. */
+  heatLegend: number[];
   formatValue: (n: number) => string;
   rowLabelWidth: number;
 }
@@ -32,6 +51,12 @@ export const MATRIX_COL_GAP = 3;
  *  cần một khoảng với mép nền; dán sát thì nó đọc như bị cắt. Tiêu đề cột cộng
  *  đúng số này vào `paddingRight` của nó để hai bên kết thúc trên một đường. */
 const MATRIX_CELL_PAD = 6;
+/** Sàn bề ngang của một ô. `styles.cell` và phép tính bề ngang tối thiểu của cả
+ *  lưới phải đọc CÙNG một con số: lệch nhau là lưới tự tin mình vừa khung trong
+ *  khi ô đã bị bóp. */
+const MATRIX_CELL_MIN = 52 + MATRIX_CELL_PAD * 2;
+/** Sàn của cột Tổng — xem `styles.totalCell`. */
+const MATRIX_TOTAL_MIN = 64;
 
 const MatrixContext = createContext<MatrixContextValue | null>(null);
 
@@ -56,6 +81,12 @@ export interface MatrixProps {
   onSelectCell?: (cell: MatrixCellRef | null) => void;
   /** Heat hue. Intensity is alpha within it; zero cells go neutral. Default blue. */
   heatColor?: ColorName;
+  /**
+   * How a value becomes ink. `rank` spends the band on the cells' ORDER, `linear`
+   * on their share of the largest cell. Default: `rank` behind numbers, `linear`
+   * for a pure heatmap, where the colour is the only statement of magnitude.
+   */
+  heatScale?: MatrixHeatScale;
   formatValue?: (n: number) => string;
   /** Width of the leading row-label column. Default 140 (room for long names). */
   rowLabelWidth?: number;
@@ -81,6 +112,7 @@ export function Matrix(props: MatrixProps) {
     selected = null,
     onSelectCell,
     heatColor = "blue",
+    heatScale,
     formatValue = defaultFormat,
     rowLabelWidth = 140,
     children,
@@ -94,11 +126,31 @@ export function Matrix(props: MatrixProps) {
     [children],
   );
 
+  // The band a wash may spend is decided by what the GRID draws, and the legend
+  // is that same scale seen from the side — so the scale is resolved once here,
+  // where both bands can read it, rather than in each of them.
+  const display = useMemo<Display>(() => {
+    const grid = Children.toArray(children).find(
+      (c) => isValidElement(c) && typeof c.type === "function" && "isMatrixGrid" in c.type,
+    );
+    return isValidElement<MatrixGridProps>(grid) ? grid.props.display ?? "both" : "both";
+  }, [children]);
+
   const { max, rowTotals, colTotals, grandTotal } = useMemo(
     () => matrixTotals(rows, cols, value),
     [rows, cols, value],
   );
 
+  const heat = useMemo(
+    () =>
+      matrixHeatScale(
+        rows.flatMap((r) => cols.map((c) => value(r.key, c.key))),
+        heatScale ?? (display === "heat" ? "linear" : "rank"),
+        HEAT_BAND[display],
+      ),
+    [rows, cols, value, heatScale, display],
+  );
+
   const ctx: MatrixContextValue = {
     rows,
     cols,
@@ -111,13 +163,26 @@ export function Matrix(props: MatrixProps) {
     selected,
     onSelectCell,
     heatBase: colors[heatColor][600],
+    heatAlpha: heat.alpha,
+    heatLegend: heat.legend,
     formatValue,
     rowLabelWidth,
   };
 
+  // Bề ngang tối thiểu để lưới còn ĐỌC được, rồi cuộn ngang khi khung hẹp hơn
+  // thế. Không có nó, ô co lại theo `flex` cho tới khi cột nhãn — thứ duy nhất
+  // nói mỗi hàng là gì — bị bóp còn một chữ cái, và cột Tổng trôi ra ngoài mép:
+  // một ma trận 30 cột vẫn "vừa khung" và không còn đọc được gì.
+  const minWidth =
+    rowLabelWidth +
+    cols.length * (MATRIX_CELL_MIN + MATRIX_COL_GAP) +
+    (hasTotals ? MATRIX_TOTAL_MIN + MATRIX_COL_GAP : 0);
+
   return (
     <MatrixContext.Provider value={ctx}>
-      <View style={styles.container}>{children}</View>
+      <ScrollView horizontal contentContainerStyle={styles.scrollContent}>
+        <View style={[styles.container, { minWidth }]}>{children}</View>
+      </ScrollView>
     </MatrixContext.Provider>
   );
 }
@@ -170,9 +235,15 @@ function MatrixGrid({ display = "both" }: MatrixGridProps) {
     <View style={styles.grid}>
       {rows.map((r) => (
         <View key={r.key} style={styles.row}>
-          <Text size="sm" numberOfLines={1} style={[styles.rowLabel, { width: rowLabelWidth }]}>
-            {r.label}
-          </Text>
+          {/* Mark then label, inside the SAME `rowLabelWidth` — the mark eats the
+              label's width rather than widening the column, so a marked matrix
+              lines up with an unmarked one and the caller's budget still holds. */}
+          <View style={[styles.rowLabel, styles.rowLabelCell, { width: rowLabelWidth }]}>
+            {r.leading}
+            <Text size="sm" numberOfLines={1} style={styles.rowLabelText}>
+              {r.label}
+            </Text>
+          </View>
           {cols.map((c) => (
             <MatrixCell key={c.key} ctx={ctx} display={display} row={r} col={c} value={value(r.key, c.key)} />
           ))}
@@ -196,16 +267,14 @@ interface MatrixCellProps {
 }
 
 function MatrixCell({ ctx, display, row, col, value }: MatrixCellProps) {
-  const { max, selected, onSelectCell, heatBase, formatValue } = ctx;
+  const { selected, onSelectCell, heatBase, heatAlpha, formatValue } = ctx;
   const showHeat = display === "heat" || display === "both";
   const showNumber = display === "number" || display === "both";
 
-  // A gentler wash behind a number (keeps it legible); the full ramp when the
-  // colour IS the value (a pure heatmap).
   const background = showHeat
     ? value === 0
       ? colors.zinc[100]
-      : withAlpha(heatBase, display === "both" ? 0.05 + 0.4 * (value / max) : 0.15 + 0.85 * (value / max))
+      : withAlpha(heatBase, heatAlpha(value))
     : colors.background;
 
   const isSelected = selected?.row === row.key && selected?.col === col.key;
@@ -278,15 +347,18 @@ export interface MatrixLegendProps {
 }
 
 function MatrixLegend({ lessLabel, moreLabel }: MatrixLegendProps) {
-  const { heatBase } = useMatrix();
+  const { heatBase, heatLegend } = useMatrix();
   const locale = useLoticsLocale();
+  // Nothing painted, nothing to explain — a less→more ramp over an empty grid
+  // asserts a scale no cell is on.
+  if (heatLegend.length === 0) return null;
   return (
     <View style={styles.scale}>
       <Text size="xs" color="muted">
         {lessLabel ?? locale.matrix.less}
       </Text>
-      {[0.15, 0.36, 0.57, 0.78, 1].map((alpha) => (
-        <View key={alpha} style={[styles.swatch, { backgroundColor: withAlpha(heatBase, alpha) }]} />
+      {heatLegend.map((alpha, i) => (
+        <View key={i} style={[styles.swatch, { backgroundColor: withAlpha(heatBase, alpha) }]} />
       ))}
       <Text size="xs" color="muted">
         {moreLabel ?? locale.matrix.more}
@@ -296,13 +368,26 @@ function MatrixLegend({ lessLabel, moreLabel }: MatrixLegendProps) {
 }
 
 Matrix.Header = MatrixHeader;
-Matrix.Grid = MatrixGrid;
+Matrix.Grid = Object.assign(MatrixGrid, { isMatrixGrid: true as const });
 Matrix.Totals = Object.assign(MatrixTotals, { isMatrixTotals: true as const });
 Matrix.Legend = MatrixLegend;
 
 const styles = StyleSheet.create({
+  scrollContent: {
+    // Lưới hẹp hơn khung thì vẫn trải hết khung — không có dòng này nó co về bề
+    // ngang nội dung và bỏ lại một khoảng trắng bên phải.
+    minWidth: "100%",
+  },
   container: {
     gap: MATRIX_COL_GAP,
+    // Và `minWidth: "100%"` một mình KHÔNG đủ: khung cuộn ngang xếp con theo
+    // HÀNG, nên cái khung nội dung rộng bằng khung ngoài còn cái lưới bên trong
+    // vẫn co về bề ngang nội dung của nó. Chỗ trống ấy không hiện ra thành một
+    // khoảng trắng ai cũng thấy — nó hiện ra thành những ô xuống dòng: lưới tự
+    // tin mình chỉ đáng bấy nhiêu, ô đứng ở sàn 64, còn một phần ba cái thẻ bỏ
+    // không ngay bên cạnh. Cho nó nhận phần dư thì ô rộng ra trước, và cuộn
+    // ngang chỉ còn xảy ra khi lưới thật sự dài hơn khung.
+    flexGrow: 1,
   },
   headRow: {
     flexDirection: "row",
@@ -320,13 +405,28 @@ const styles = StyleSheet.create({
   },
   rowLabel: {
     paddingRight: 8,
+    // Cột nhãn không bao giờ nhường chỗ: nó là thứ duy nhất nói mỗi hàng là gì.
+    flexShrink: 0,
+  },
+  // Chỉ hàng dữ liệu: ô nhãn là một hàng ngang mark + chữ. Dải Tổng và góc tiêu
+  // đề không mang mark nên giữ nguyên `rowLabel`.
+  rowLabelCell: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: LEADING_GAP,
+  },
+  rowLabelText: {
+    // Chữ nhận phần còn lại sau cái mark; `minWidth: 0` để nó chịu cắt bớt thay
+    // vì đẩy mark ra ngoài mép cột.
+    flex: 1,
+    minWidth: 0,
   },
   cell: {
     flex: 1,
     // 52 + hai lần MATRIX_CELL_PAD: cái đệm mới ăn vào bề ngang, nên sàn tối
     // thiểu phải cộng thêm đúng ngần ấy, không thì ô chật đi và con số dài nhất
     // là con số đầu tiên bị ép.
-    minWidth: 52 + MATRIX_CELL_PAD * 2,
+    minWidth: MATRIX_CELL_MIN,
     height: 36,
     borderRadius: 4,
     borderWidth: 2,
@@ -372,7 +472,7 @@ const styles = StyleSheet.create({
     // many columns in a narrow frame never gets a total column narrower than it
     // used to have.
     flex: 1,
-    minWidth: 64,
+    minWidth: MATRIX_TOTAL_MIN,
     paddingLeft: 4,
   },
   totalsRow: {

package/src/matrix_totals.ts

@@ -1,13 +1,24 @@
+import type { ReactNode } from "react";
+
 /**
  * The data layer for `Matrix` — axis types + the cross-tab aggregation. Kept
- * free of any React-Native import so it unit-tests directly (the component in
- * `matrix.tsx` renders these numbers; a consumer can drive a KPI off the same
- * `matrixTotals` it shows in the grid).
+ * free of any React-Native import (the axis mark is a TYPE-only `ReactNode`, so
+ * nothing here runs) and it unit-tests directly: the component in `matrix.tsx`
+ * renders these numbers, and a consumer can drive a KPI off the same
+ * `matrixTotals` it shows in the grid.
  */
 
 export interface MatrixAxisItem {
   key: string;
   label: string;
+  /**
+   * An identity mark before the label — an `Avatar`, a status dot. ROWS ONLY:
+   * a row is a subject and a mark is what makes it recognizable at a glance,
+   * while a column is a period or a category and has no identity to carry, so
+   * `Matrix.Header` ignores this. The mark is drawn INSIDE `rowLabelWidth`, so
+   * it eats the label's width rather than widening the column.
+   */
+  leading?: ReactNode;
 }
 
 /** The inspected cell — host renders its detail (a filtered list) underneath. */
@@ -24,6 +35,63 @@ export interface MatrixTotalsResult {
   max: number;
 }
 
+/** How a cell's value becomes ink. See `matrixHeatScale`. */
+export type MatrixHeatScale = "linear" | "rank";
+
+export interface MatrixHeatScaleResult {
+  /** The alpha this scale paints a cell with. Zero (and below) paints nothing. */
+  alpha: (value: number) => number;
+  /** The legend's swatches — the SAME alphas, sampled across the painted set. */
+  legend: number[];
+}
+
+/**
+ * Value → ink, and the legend that explains it, from ONE expression.
+ *
+ * `linear` maps a cell onto the band by its share of the largest cell. That is
+ * honest only when the values are spread; on the long tail every real dataset
+ * has (one big month, eleven ordinary ones) it spends the whole band on the
+ * outlier and leaves everything else inside a step the eye cannot resolve.
+ * `rank` maps a cell by its POSITION among the DISTINCT values painted, so the
+ * band is spent on the differences the reader can see, the smallest cell always
+ * lands on `lo` and the largest on `hi`, and equal cells keep equal ink.
+ *
+ * The legend is SAMPLED from that same function rather than restated, so it can
+ * never paint a shade the grid cannot reach: a legend written as its own list of
+ * alphas is a second copy of the scale, and it drifts the moment the band moves.
+ */
+export function matrixHeatScale(
+  values: number[],
+  scale: MatrixHeatScale,
+  band: [number, number],
+): MatrixHeatScaleResult {
+  const [lo, hi] = band;
+  const distinct = [...new Set(values.filter((v) => v > 0))].sort((a, b) => a - b);
+  const top = distinct[distinct.length - 1] ?? 1;
+  const at = (t: number) => lo + (hi - lo) * t;
+
+  // One pass to rank: a per-cell scan would be quadratic on a wide sheet.
+  const rank = new Map<number, number>();
+  distinct.forEach((v, i) => rank.set(v, i));
+
+  const alpha = (v: number): number => {
+    if (v <= 0) return 0;
+    // A single distinct value has no order to spend a band on — every cell is
+    // the largest one, and the top of the band is what says so.
+    if (distinct.length < 2) return hi;
+    if (scale === "linear") return at(v / top);
+    return at((rank.get(v) ?? distinct.length - 1) / (distinct.length - 1));
+  };
+
+  return {
+    alpha,
+    legend:
+      distinct.length === 0
+        ? []
+        : [0, 0.25, 0.5, 0.75, 1].map((q) => alpha(distinct[Math.round(q * (distinct.length - 1))])),
+  };
+}
+
 /**
  * Row sums, column sums, grand total, and the max single cell — computed in one
  * pass. The single source of truth for the matrix's totals.

package/src/month_math.ts

@@ -0,0 +1,16 @@
+// Month arithmetic on `yyyy-MM-dd` strings, free of React and of the clock.
+// A month is keyed by its first day so a value round-trips through a date
+// field unchanged.
+
+/** The first day of the month `iso` falls in. */
+export function monthStart(iso: string): string {
+  return `${iso.slice(0, 7)}-01`;
+}
+
+/** `delta` months from `iso`, as that month's first day. */
+export function shiftMonth(iso: string, delta: number): string {
+  const y = Number(iso.slice(0, 4));
+  const m = Number(iso.slice(5, 7)) - 1 + delta;
+  const d = new Date(y, m, 1);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-01`;
+}

package/src/month_stepper.tsx

@@ -0,0 +1,62 @@
+import { StyleSheet, View } from "react-native";
+import { formatDate } from "./format_date";
+import { IconButton } from "./icon_button";
+import { useLoticsLocale } from "./locale";
+import { monthStart, shiftMonth } from "./month_math";
+import { Text } from "./text";
+
+export interface MonthStepperLabels {
+  previous: string;
+  next: string;
+}
+
+export interface MonthStepperProps {
+  /** The month, as any day in it (`yyyy-MM-dd`); `onChange` always hands back its first day. */
+  value: string;
+  onChange: (next: string) => void;
+  /** The last month that may be stepped INTO — this month, for a surface about what has happened. */
+  max?: string;
+  min?: string;
+  labels?: Partial<MonthStepperLabels>;
+  /** BCP-47 for the month name. Defaults to the active locale. */
+  locale?: string;
+  testID?: string;
+}
+
+/**
+ * ‹ Tháng 9 2026 › — the period control for a surface keyed by a MONTH: a
+ * plan, a roster, a month's attendance. `DateRangeFilterField` is for a
+ * surface that takes any range; a month-keyed record cannot take "the 3rd to
+ * the 19th", so the control offers only the moves that exist.
+ *
+ * The bound is the contract. A stepper that walks into next year reads a plan
+ * for a month nobody has given one for, and two hand-rolled steppers in one
+ * app disagreed on exactly this — one refused the future, one did not.
+ */
+export function MonthStepper(props: MonthStepperProps) {
+  const { value, onChange, max, min, labels, locale, testID } = props;
+  const pack = useLoticsLocale();
+  const l = { ...pack.monthStepper, ...labels };
+  const month = monthStart(value);
+  const prev = shiftMonth(month, -1);
+  const next = shiftMonth(month, 1);
+  const atMin = min !== undefined && prev < monthStart(min);
+  const atMax = max !== undefined && next > monthStart(max);
+
+  return (
+    <View style={styles.row} testID={testID}>
+      <IconButton icon="chevron-left" size="sm" accessibilityLabel={l.previous} disabled={atMin} onPress={() => onChange(prev)} />
+      <Text size="sm" weight="medium" tabular align="center" numberOfLines={1} style={styles.label}>
+        {formatDate(`${month}T00:00:00`, { format: "monthYear", locale: locale ?? pack.bcp47 })}
+      </Text>
+      <IconButton icon="chevron-right" size="sm" accessibilityLabel={l.next} disabled={atMax} onPress={() => onChange(next)} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: { flexDirection: "row", alignItems: "center", gap: 4, alignSelf: "flex-start" },
+  // Wide enough for the longest month name in either pack, so the arrows do not
+  // shuffle sideways as the reader steps.
+  label: { minWidth: 148 },
+});

package/src/organization_name.ts

@@ -0,0 +1,94 @@
+/**
+ * An organization's name without the legal form it opens or closes with.
+ *
+ * A register of companies marks the same letters on every row, because the
+ * name opens with "Công ty TNHH" or closes with "Ltd." — the identity mark is
+ * derived from the first letters, and the first 60px of the name column are
+ * spent on words that tell no two rows apart. composition.md § Identity marks
+ * says to strip the form from BOTH ends before the name reaches the mark, and
+ * to show the stripped name as the row's title; this is that function, so two
+ * screens cannot disagree about what counts as a form.
+ *
+ * The forms are the ones the kit's two locales meet. A name that IS only a
+ * form comes back unchanged — an empty title is worse than a generic one.
+ */
+const LEADING = [
+  "công ty cổ phần",
+  "công ty cp",
+  "cty cp",
+  "công ty tnhh một thành viên",
+  "công ty tnhh mtv",
+  "công ty tnhh",
+  "cty tnhh",
+  "tổng công ty",
+  "công ty",
+  "cty",
+  "hợp tác xã",
+  "htx",
+  "hộ kinh doanh",
+  "hkd",
+  "doanh nghiệp tư nhân",
+  "dntn",
+  "tập đoàn",
+  "chi nhánh",
+  "the",
+];
+
+const TRAILING = [
+  "co., ltd.",
+  "co., ltd",
+  "co. ltd",
+  "co ltd",
+  "pte. ltd.",
+  "pte ltd",
+  "ltd.",
+  "ltd",
+  "limited",
+  "llc",
+  "inc.",
+  "inc",
+  "corp.",
+  "corp",
+  "corporation",
+  "company",
+  "jsc",
+  "plc",
+  "gmbh",
+  "s.a.",
+  "cổ phần",
+  "tnhh",
+  "cp",
+];
+
+/** Longest first, so "công ty tnhh mtv" is tried before "công ty tnhh" before "công ty". */
+const byLength = (a: string, b: string) => b.length - a.length;
+const LEAD = [...LEADING].sort(byLength);
+const TRAIL = [...TRAILING].sort(byLength);
+
+const SEP = /^[\s,.\-–—]+|[\s,.\-–—]+$/g;
+
+function stripOnce(name: string): string {
+  const lower = name.toLowerCase();
+  for (const form of LEAD) {
+    if (lower.startsWith(form) && (lower.length === form.length || /[\s,.]/.test(lower.charAt(form.length)))) {
+      return name.slice(form.length).replace(SEP, "");
+    }
+  }
+  for (const form of TRAIL) {
+    const at = lower.length - form.length;
+    if (at > 0 && lower.endsWith(form) && /[\s,.]/.test(lower.charAt(at - 1))) {
+      return name.slice(0, at).replace(SEP, "");
+    }
+  }
+  return name;
+}
+
+export function stripLegalForm(name: string): string {
+  let cur = name.trim();
+  for (;;) {
+    const next = stripOnce(cur);
+    if (next === cur) break;
+    cur = next;
+  }
+  return cur === "" ? name.trim() : cur;
+}

package/src/search_match.ts

@@ -16,3 +16,22 @@ export function normalizeForSearch(s: string): string {
     .replace(/\p{Diacritic}/gu, "")
     .replaceAll(String.fromCharCode(0x111), "d");
 }
+
+/**
+ * A CODE the way a person types it — a plate, a container number, a voucher
+ * number. `14B-031.02` is punctuated three different ways across one yard's
+ * paperwork and nobody typing fast reproduces any of them, so both sides drop
+ * everything that is not a letter or a digit before matching: `14b031` finds
+ * it, and so does `031.02`. Still a substring test, never a subsequence one, or
+ * `1402` would match half the register.
+ */
+export function codeKey(s: string): string {
+  return normalizeForSearch(s).replace(/[^a-z0-9]/g, "");
+}
+
+/** Does any of these fields answer the query, as a code? An empty query matches everything. */
+export function codeMatches(query: string, ...fields: string[]): boolean {
+  const q = codeKey(query);
+  if (q === "") return true;
+  return fields.some((f) => codeKey(f).includes(q));
+}