@lotics/ui 47.15.1 → 47.16.1

package/docs/catalog.md

@@ -648,7 +648,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`markdown.css`** — import once for the web markdown styling.
 - **`format_date`** — `formatDate` / `parseDate` / `toISODate` + `DateFormatStyle` (incl.
   `monthYear` and `quarterYear`, the two period labels).
-- **`format_money`** — `formatMoney` / `formatCompactNumber`.
+- **`format_money`** — `formatMoney` / `formatCompactNumber`. **`compact` abbreviates in the
+  LOCALE's own words**: `vi` gets "486 tr ₫" / "1,28 tỷ ₫", every other locale gets Intl's
+  compact currency ("$1.2M"). `tỷ` and `tr` are Vietnamese words, so a figure under `en-US`
+  never wears one — it reads as a typo, not as a number.
 - **`text_utils`** — text/typography plumbing: `getTextColor` (the TextColor→hex map incl.
   the AA-cleared valence set), the Inter `fontFamily*` stacks, and `getInputTextStyle` /
   `getInputLineHeight` — the 16px-mobile/14px-desktop input contract that stops Safari iOS
@@ -1147,7 +1150,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   nothing — `message` + `hint` + an optional `icon` anchor, and **no verb at all**. It cannot hold
   the section's add (that lives on the heading row, where it does not move — § The add-placement
   law in composition.md), a no-results empty is HINT-only since the filters that emptied it carry
-  their own clear, and a FAILED read is `ErrorState`, not this. **`compact`** for one BAND of a
+  their own clear, and a FAILED read is `ErrorState`, not this. **`link` ({ label, onPress }) is a
+  DESTINATION, not that verb** — reach for it only where what fills the region is made somewhere
+  else, so the hint has an address to end at; it does not move when the first row lands and it
+  asserts nothing about the read. **`compact`** for one BAND of a
   record — left-aligned, glyph-less, 56px against the default's 178; the centred default speaks
   for a whole region. → composition.md § Empty states.
 - **`error_state`** — `ErrorState`: the region-scale FAILED read — `message` + optional `detail`
@@ -1661,7 +1667,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   **And before reaching for a verb at all, ask whether the value is simply the field's DEFAULT** —
   a tariff, a list price, the figure a line is created with. Then there is no verb: the field
   already holds it, and clearing the field restores it. A button that re-applies what the field
-  would hold anyway is a control for a state the reader cannot reach. `extra` carries a second control belonging
+  would hold anyway is a control for a state the reader cannot reach. **A flat line's `amount: null` is a cost NOBODY HAS STATED** — an excluded service, a
+  figure the supplier still owes — and prints a dash, never the band's zero, because a service
+  shown at zero reads as free; `0` stays a price somebody set. `extra` carries a second control belonging
   to the charge (how it was paid); `warning` names a problem on the line that has it; `locked`
   turns the editors into values for a settled band and draws no verb of any kind; `empty` speaks for a record nobody has priced
   yet. `formatMoney` is the BAND's, so two lines cannot disagree about a currency, and the `total`

package/docs/composition.md

@@ -367,7 +367,7 @@ the add returns to the right edge where the law puts it, and drag/paste keep wor
   with row count is the fault, not the cure.
 - **It renders unconditionally**, empty or not. A heading whose CTA appears only once there is
   data cannot be used to create the first row.
-- **The `EmptyState` then takes NO `action`** — see § Empty states.
+- **The `EmptyState` then carries no add of its own** — see § Empty states.
 - **Only the ADD.** A verb that acts on a SELECTION (delete, export, run) belongs to the
   selection — `FloatingActionBar` — and a verb about ONE row stays on the row.
 
@@ -1457,8 +1457,8 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
 
   The ADD is the one verb this law does NOT place next to its effect, and the add-placement law
   says why. The heading row therefore carries identity + meta + view controls + the section's ADD,
-  and no other content verb. **An add is `primary` wherever it renders** — on that heading row,
-  or inside an `EmptyState` in the one case § Empty states allows, where there is no heading to carry it. It
+  and no other content verb. **An add is `primary` wherever it renders** — and the heading row is
+  where it renders, since `EmptyState` holds no verb (§ Empty states). It
   is the act its section offers, so it carries that section's weight; a lone `secondary` button
   reads as though the real action were somewhere else. The rule that matters is that ONE VERB
   KEEPS ONE WEIGHT — the same add must not be primary on an empty list and secondary on a full one.
@@ -2601,11 +2601,21 @@ what's empty, `hint` = what to do about it).
 duplicating it here would put two buttons for one act in view and make the add jump the moment
 the first row lands. A read that FAILED is not an empty one — it does not know whether there is
 anything — so it gets `ErrorState` (`message` + `detail` + `onRetry`), never an empty state
-wearing an alert glyph. The three empties get DIFFERENT copy:
+wearing an alert glyph.
 
-- **First use** → teach + invite: message names what will live here, and the CTA — the
-  heading's, or `action` where there is no heading — creates the first one ("Chưa có khoản phí"
-  + "Thêm khoản thu/chi cho lô").
+**A DESTINATION is not that verb, and `link` is where it goes.** Where what fills the region is
+made somewhere else entirely — another surface, a terminal, a page the reader has to open — the
+hint needs an address to end at, and neither of the two refusals above applies to one: a
+destination was never this section's add, so it cannot jump when the first row lands, and it
+asserts nothing about the read, so it cannot dress a failure as an empty. It sits under the hint,
+as `Link` (underlined, blue, `role="link"`), and stays the last line: the region still says what
+is empty first. Anything the reader could press to fill the region HERE is the add, and belongs
+on the heading row.
+
+The three empties get DIFFERENT copy:
+
+- **First use** → teach + invite: message names what will live here, and the heading's CTA
+  creates the first one ("Chưa có khoản phí" + "Thêm khoản thu/chi cho lô").
 - **User cleared it** → stay quiet: the user knows why it's empty; confirmation only, no tutorial.
 - **No search/filter results** → help recover: restate the scope ("Không có lô nào khớp
   'ABC'"), hint the fix ("Thử từ khóa khác / xóa bộ lọc"). Never a blank panel or bare "No data".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "47.15.1",
+  "version": "47.16.1",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",

package/src/charge_lines.tsx

@@ -73,7 +73,11 @@ export interface ChargeLineProps {
   quantity?: number | null;
   unitPrice?: number | null;
   /** Flat line: the amount itself. Ignored when `quantity`/`unitPrice` are set,
-   *  because a derived figure and a typed one cannot both be the truth. */
+   *  because a derived figure and a typed one cannot both be the truth.
+   *  `null` is a cost NOBODY HAS STATED — a supplier's exclusion, a line still
+   *  awaiting a figure — and renders as a dash, never as the band's zero: a
+   *  service printed at zero reads as free. Pass `0` for a price somebody
+   *  actually set to nothing. */
   amount?: number | null;
   onAmountChange?: (next: number | null) => void | Promise<void>;
   /** The same, for a FLAT line's amount. Unconditional and `disabled` when idle. */
@@ -204,6 +208,14 @@ export function ChargeLine(props: ChargeLineProps) {
     : undefined;
   const priced = quantity !== undefined || unitPrice !== undefined;
   const amount = priced ? (quantity ?? 0) * (unitPrice ?? 0) : (props.amount ?? 0);
+  /**
+   * A flat line whose amount is NULL has no figure — a cost nobody has stated
+   * yet, a service the supplier excluded. Read-only it used to print the
+   * band's zero, which says the line is free; the editable spelling of the
+   * same value already showed the placeholder dash. One value cannot render
+   * as two different claims, and of the two only the dash is true.
+   */
+  const unstated = !priced && props.amount == null;
   /** The row's money verb — the unit price's on a priced line, the amount's on a
    *  flat one. A locked band has nothing to act on, so it draws none. */
   const warning = props.warning ? (
@@ -276,8 +288,8 @@ export function ChargeLine(props: ChargeLineProps) {
           answer — and it lands in no column, so the total below closes nothing. */}
       <View style={styles.amountSlot}>
         {priced || locked || !props.onAmountChange ? (
-          <Text size="sm" tabular style={[styles.right, styles.inset]}>
-            {money(amount)}
+          <Text size="sm" tabular color={unstated ? "muted" : undefined} style={[styles.right, styles.inset]}>
+            {unstated ? "—" : money(amount)}
           </Text>
         ) : (
           <InlineNumberInput

package/src/empty_state.tsx

@@ -1,6 +1,7 @@
 import { View, StyleSheet } from "react-native";
 import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
+import { Link } from "./link";
 import { colors } from "./colors";
 
 interface EmptyStateBase {
@@ -8,6 +9,16 @@ interface EmptyStateBase {
   message: string;
   /** What the user can do about it ("Thử từ khóa khác"). */
   hint?: string;
+  /**
+   * Where to go — an address, under the hint. NOT the `action` this refuses
+   * below: a destination is a different thing from a verb. It does not move
+   * when the first row lands (it was never this section's add), and it asserts
+   * nothing about the read (it is not a retry).
+   *
+   * Reach for it only where what fills the region lives SOMEWHERE ELSE, so the
+   * hint has an address to end at.
+   */
+  link?: { label: string; onPress: () => void };
 }
 
 /** The whole region: centred, generous, with an optional glyph anchoring it. */
@@ -74,9 +85,10 @@ type EmptyStateProps = EmptyRegionProps | EmptyBandProps;
  *   is that nothing is known — use `ErrorState`. Retrying a true empty just
  *   returns the same nothing.
  *
- * What is left says one thing and offers nothing to press: this region is empty,
- * and here is what would live in it. A no-results empty is hint-only too — the
- * filters that emptied it carry their own clear.
+ * What is left says one thing and points, at most, somewhere else: this region
+ * is empty, here is what would live in it, and — `link` — the address where it
+ * gets made. A no-results empty is hint-only too — the filters that emptied it
+ * carry their own clear.
  */
 export function EmptyState(props: EmptyStateProps) {
   if (props.compact) {
@@ -87,6 +99,11 @@ export function EmptyState(props: EmptyStateProps) {
       <View style={styles.compactContainer}>
         <Text size="sm" color="muted" leading="tight">{props.message}</Text>
         {props.hint ? <Text size="xs" color="muted" leading="tight">{props.hint}</Text> : null}
+        {props.link ? (
+          <Link size="xs" onPress={props.link.onPress}>
+            {props.link.label}
+          </Link>
+        ) : null}
       </View>
     );
   }
@@ -105,6 +122,11 @@ export function EmptyState(props: EmptyStateProps) {
           {props.hint}
         </Text>
       ) : null}
+      {props.link ? (
+        <Link size="xs" onPress={props.link.onPress}>
+          {props.link.label}
+        </Link>
+      ) : null}
     </View>
   );
 }

package/src/format_money.ts

@@ -1,9 +1,10 @@
 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. */
+  /** Abbreviate for display density — in the LOCALE's own words: `vi` gets
+   * "1,28 tỷ ₫" / "486 tr ₫", everywhere else gets Intl's compact currency
+   * ("$1.2M"). For stat strips/cards where the full figure lives in the table
+   * below — never for the table itself. */
   compact?: boolean;
   /** Significant digits below the currency's minor unit. `Intl`'s currency
    *  style floors at that unit — 2 for USD — so a genuine per-unit price like
@@ -14,18 +15,25 @@ export interface FormatMoneyOptions {
 }
 
 /**
- * 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`.
+ * A magnitude abbreviated IN THE READER'S OWN LANGUAGE: `vi` gets its own
+ * words (≥1 tỷ → "1,28 tỷ", ≥1 triệu → "486 tr"), every other locale gets
+ * Intl's compact notation ("1.2M", "486K"). Smaller values render in full.
+ * Bare numbers only — for money, use `formatMoney` with `compact`.
+ *
+ * `tỷ` and `tr` are Vietnamese WORDS, so they belong to a Vietnamese locale
+ * and nowhere else: appending them under `en-US` printed "1 tr USD" on a US
+ * register, which reads as a typo rather than as a number. A locale Intl has
+ * no compact form for falls back to grouped digits — long, and never foreign.
  */
 export function formatCompactNumber(value: number, locale = "vi-VN"): string {
+  if (Math.abs(value) < 1_000_000) return value.toLocaleString(locale);
+  if (!locale.startsWith("vi")) {
+    return value.toLocaleString(locale, { notation: "compact", maximumFractionDigits: 1 });
+  }
   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);
+  return `${Math.round(value / 1_000_000).toLocaleString(locale)} tr`;
 }
 
 /**
@@ -37,6 +45,11 @@ export function formatCompactNumber(value: number, locale = "vi-VN"): string {
 export function formatMoney(value: number, options: FormatMoneyOptions = {}): string {
   const { locale = "vi-VN", currency = "VND", compact = false, maxFractionDigits } = options;
   if (compact && Math.abs(value) >= 1_000_000) {
+    // Outside Vietnamese, Intl abbreviates the CURRENCY itself — "$1.2M" — so
+    // the symbol keeps its place instead of trailing a foreign magnitude word.
+    if (!locale.startsWith("vi")) {
+      return value.toLocaleString(locale, { style: "currency", currency, notation: "compact", maximumFractionDigits: 1 });
+    }
     const suffixed = formatCompactNumber(value, locale);
     return currency === "VND" ? `${suffixed} ₫` : `${suffixed} ${currency}`;
   }