@lotics/ui 11.6.0 → 11.7.0

package/AGENTS.md

@@ -39,6 +39,9 @@ doc before building any screen, **never from memory**. Exact props are the shipp
 - **Pure primitives only** — no i18n, analytics, or domain types in `src/` (pass `labels`,
   callbacks); Lotics-coupled UI belongs in `@lotics/ui-internal`.
 - **Every state designed** — skeleton (mirroring layout), empty, error; no layout shift.
+- **Copy states content, not mechanics** — a `description` names the section's content or one
+  domain rule; widget behavior ("edits in place, saves on its own") and selling points never
+  appear. Instructions live in empty states / form-field hints. → [composition.md §Microcopy](./docs/composition.md).
 
 ## Keeping this reference current
 

package/docs/catalog.md

@@ -335,7 +335,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   (12, fixed), no body component. `SectionHeadingTitle` is ALWAYS `##` (xl semibold;
   `weight="medium"` opt-down only) + `info` for an ⓘ provenance popover after the title,
   same as `CardHeaderTitle.info`. `SubsectionHeadingTitle` is the `###` lg-semibold level-3
-  title of a named group inside a section — heading-row siblings ride its right edge; the
+  title of a named group inside a section (same `info` ⓘ affordance as the section title) —
+  heading-row siblings ride its right edge; the
   heading ramp is FIXED: `#` xxl / `##` xl / `###` lg, no size props.
 - **`section`** — a SECOND, standalone `Section`: a self-contained titled block
   (`title`/`description`/`collapsible`/`icon`/`titleRight`, imperative
@@ -551,7 +552,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   label+value row for drawer/peek detail; in FORM mode (`labelWidth` set) the value column
   FILLS the row so a stack of inline editors all span the same width + none jumps wider on
   edit; optional `trailing` slot renders a right-side action/badge after the value (units
-  belong IN the value via `InlineNumberInput format`). `DetailTable`: the compound parent of
+  belong IN the value via `InlineNumberInput format`); optional `info` renders an ⓘ popover
+  hugging the label — the row-label member of the one `info` vocabulary (`CardHeaderTitle` /
+  `SectionHeadingTitle` / `SubsectionHeadingTitle`); pass `undefined` to hide it (callers may
+  gate it on their own state). `DetailTable`: the compound parent of
   a row STACK — `labelWidth` (default 130) / `trailingWidth` / `minHeight` (default 40, the
   inline-control grid) declared ONCE + the 6px row gap; with `trailingWidth` every row
   reserves the trailing column so value cells share one width and trailing items align at

package/docs/composition.md

@@ -60,7 +60,8 @@ restyle a heading level per-page.
   `Section` with a `title` string prop — a different component. Import from `section_heading` for
   the grammar described here.
 - **Subsection title** — the level BELOW a section on a long record surface: `Subsection` ›
-  `SubsectionHeading` › `SubsectionHeadingTitle` (`###` — lg semibold; siblings — a `Badge`, a
+  `SubsectionHeading` › `SubsectionHeadingTitle` (`###` — lg semibold, with the same `info` ⓘ
+  affordance as `SectionHeadingTitle`; siblings — a `Badge`, a
   `SectionHeadingMeta`, an action — ride the heading row's right edge). Sibling subsections stack
   in a **`SubsectionStack`** (the same hairline law one step tighter: a fixed 24px beat + hairline
   between groups — no margins, no hand-rolled dividers); a headingless `Subsection` is the
@@ -437,3 +438,75 @@ disabled ink).
 Anything pressable is ≥ 40px tall (8px minimum gap between pressables). 16px between cards, 24–28
 canvas padding, 16–20 inside bands, 10–12 between content lines. Density comes from alignment +
 hierarchy, not cramming.
+
+## Microcopy — content, not mechanics
+
+UI copy states WHAT something is — domain content or one real rule — never how the widget
+behaves, and never a selling point. The control demonstrates its own behavior; copy that
+narrates it ("edits in place, saves on its own", "sửa tại chỗ, lưu ngay") is noise, and copy
+that praises it is marketing.
+
+- **Heading `description`s** name the section's content ("Các bên và điều khoản thương mại
+  của lô.") or one domain invariant ("Each invoice owns its charge lines — a charge never
+  lives apart from the document it bills on."). Never widget mechanics, never usage narration
+  ("drop to add, click to preview"), never feature-brag adjectives.
+- **Instructions live where action is needed** — empty states, callouts, form-field
+  descriptions: imperative, one concrete step ("Drop the CI + PL here."). A heading never
+  instructs.
+- **Restatement is the second noise mode.** A description that repeats what the screen already
+  shows — the title, the subsection names below it, the table's columns — carries zero
+  information and fails even though it "states content". Useful copy states an **invisible
+  truth**: an invariant of the data, a boundary ("P&L lives in the accounting app, not here"),
+  a linkage ("the HS code here feeds the customs declaration"), or a consequence ("past the
+  cut-off, the box misses the sailing").
+- **The deletion test**: if removing the line changes nothing for the reader, remove the line —
+  `description` is optional for a reason; when no invisible truth is worth stating, omit it.
+- **Plain language over jargon; effect over mechanism** ("Record visibility", not "Row-Level
+  Privacy") — if a term needs explaining, replace it. **One concept = one word everywhere** —
+  pick the term once and reuse it on every surface.
+- **Native language**: match the workspace language with native vocabulary — a Vietnamese ops
+  app reads like a Vietnamese ops tool, not a translated brochure. Sentence case; no
+  exclamation marks.
+
+### Error messages — what happened → what it means → what to do
+
+The consensus anatomy (GOV.UK · NN/g · Microsoft): state what happened, what it means for the
+user's data, and the one next step. Field errors go INLINE (`FormField error=`); a page-level
+failure is a `Callout tone="error"` (title = what happened, text = what to do, an action when
+one exists).
+
+- Never blame ("invalid", "you forgot"), never bare "An error occurred", never an error code
+  as the headline (put codes at the end, for support). No ALL-CAPS, no exclamation.
+- Say whether the user's input survived — and PRESERVE it (re-entering data is the real cost).
+- Empty required field → instruct ("Enter the hours you work a week"); constraint violation →
+  describe the constraint ("First name must be 35 characters or less").
+- Apology is reserved for genuine system failure — never for validation.
+- BAD: `Error: invalid input (0x643).` · GOOD: `Không tải được chứng từ lên — tệp vẫn còn trên
+  máy bạn. Thử lại; nếu vẫn lỗi, kiểm tra kết nối mạng.`
+
+### Empty states — confirm, orient, one action
+
+An empty region has three jobs (NN/g): confirm this is EMPTY (not loading, not broken), say
+what belongs here, and offer ONE next action — the `EmptyState` props are this anatomy
+(`message` = what's empty, `hint` = what to do about it, `action` = the one CTA). The three
+empties get DIFFERENT copy:
+
+- **First use** → teach + invite: message names what will live here, `action` creates the first
+  one ("Chưa có khoản phí" + "Thêm khoản thu/chi cho lô" + a Thêm phí button).
+- **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".
+
+### Buttons & action labels — the outcome, verb-first
+
+A label names the OUTCOME of pressing — verb + object, 2–4 words (GOV.UK: "Save and continue",
+"Add another address"). Universal across every source; only casing forks by platform (this kit:
+sentence case, always).
+
+- Never "OK" / "Yes" / "Submit" / "Click here" — a `Button title` says what happens ("Tạo lô
+  hàng", "Xóa 3 tệp").
+- A dialog's confirm button RESTATES the action: "Xóa lô?" → `Xóa` / `Hủy` — never `OK` / `Hủy`
+  (the pair must answer the question without reading the body).
+- Destructive buttons name the object (`color="danger"` + "Xóa lô", not "Xóa") — the label is
+  the last safeguard.
+

package/examples/tpl_record.tsx

@@ -707,7 +707,7 @@ export function TplRecord() {
         <View onLayout={nav.register("details")}>
         <Section>
           <SectionHeading>
-            <SectionHeadingTitle description="Every value edits in place — click a chip, change it, it saves on its own.">Details</SectionHeadingTitle>
+            <SectionHeadingTitle description="The order's core facts — reference, dates, and the amounts every desk reads first.">Details</SectionHeadingTitle>
             <OwnerTag stage="sales" />
           </SectionHeading>
           <DetailTable labelWidth={150} trailingWidth={88}>
@@ -757,7 +757,7 @@ export function TplRecord() {
         <View onLayout={nav.register("customer")}>
         <Section>
           <SectionHeading>
-            <SectionHeadingTitle description="The bill-to. Its tax ID gates invoicing below — add it here.">Customer</SectionHeadingTitle>
+            <SectionHeadingTitle description="The bill-to party — its tax ID gates invoicing below.">Customer</SectionHeadingTitle>
             <OwnerTag stage="sales" />
             {customer && !editingCustomer ? (
               <Button title="Edit" color="secondary" icon="pencil" onPress={() => setEditingCustomer(true)} />
@@ -964,7 +964,7 @@ export function TplRecord() {
         <View onLayout={nav.register("files")}>
         <Section>
           <SectionHeading>
-            <SectionHeadingTitle description="The signed quote, the PO, photos — drop to add, click to preview.">Files</SectionHeadingTitle>
+            <SectionHeadingTitle description="The signed quote, the PO, photos — everything filed on the order.">Files</SectionHeadingTitle>
             <OwnerTag stage="operations" />
             {files.length > 0 ? <SectionHeadingMeta>{`${files.length} ${files.length === 1 ? "file" : "files"}`}</SectionHeadingMeta> : null}
           </SectionHeading>
@@ -1194,7 +1194,7 @@ export function TplRecord() {
         <View onLayout={nav.register("preferences")}>
         <Section>
           <SectionHeading>
-            <SectionHeadingTitle description="Applied as you change them — no Save.">Preferences</SectionHeadingTitle>
+            <SectionHeadingTitle description="Per-order handling and notification preferences.">Preferences</SectionHeadingTitle>
           </SectionHeading>
           <View style={{ flexDirection: "row", alignItems: "center", gap: 12, minHeight: 40 }}>
             <View style={{ flex: 1, gap: 1 }}>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "11.6.0",
+  "version": "11.7.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",

package/src/detail_row.tsx

@@ -1,6 +1,8 @@
 import { createContext, ReactNode, useContext, useState } from "react";
 import { StyleProp, StyleSheet, View, ViewStyle } from "react-native";
 import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
+import { InfoPopover } from "./info_popover";
+import { useLoticsLocale } from "./locale";
 import { Text } from "./text";
 
 interface DetailTableColumns {
@@ -103,6 +105,11 @@ export interface DetailRowProps {
   labelSize?: "xs" | "sm";
   /** Min row height. Default 28 (or the `DetailTable`'s `minHeight`). */
   minHeight?: number;
+  /** An ⓘ popover hugging the label — a short "what this field means" gloss,
+   *  the row-label member of the one `info` vocabulary
+   *  (`CardHeaderTitle` / `SectionHeadingTitle` / `SubsectionHeadingTitle`).
+   *  Pass `undefined` to hide the ⓘ (a caller can gate it on its own state). */
+  info?: string;
 }
 
 /**
@@ -116,10 +123,21 @@ export interface DetailRowProps {
  */
 export function DetailRow(props: DetailRowProps) {
   const table = useContext(DetailTableContext);
-  const { label, children, trailing, labelSize = "sm" } = props;
+  const { label, children, trailing, labelSize = "sm", info } = props;
   const labelWidth = props.labelWidth ?? table?.labelWidth;
   const minHeight = props.minHeight ?? table?.minHeight ?? 28;
   const form = labelWidth != null;
+  const words = useLoticsLocale();
+  // The ⓘ hugs the label text (flexShrink keeps long labels from pushing it
+  // out of the cell) — the label cell keeps its exact width either way.
+  const infoLabel = (cellStyle: StyleProp<ViewStyle>) => (
+    <View style={[styles.labelWithInfo, cellStyle]}>
+      <Text size={labelSize} color="muted" numberOfLines={1} style={styles.labelShrink}>
+        {label}
+      </Text>
+      <InfoPopover text={info ?? ""} accessibilityLabel={words.sectionHeading.info} />
+    </View>
+  );
   if (table?.stacked) {
     // Stacked mode wears the FORM grammar: the label renders exactly like a
     // `FormField` label (medium, default ink), so a narrow record surface
@@ -128,9 +146,18 @@ export function DetailRow(props: DetailRowProps) {
     // inline editor self-persists — only the look converges.
     return (
       <View style={styles.stackedRow}>
-        <Text weight="medium" numberOfLines={1}>
-          {label}
-        </Text>
+        {info != null ? (
+          <View style={styles.labelWithInfo}>
+            <Text weight="medium" numberOfLines={1} style={styles.labelShrink}>
+              {label}
+            </Text>
+            <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} />
+          </View>
+        ) : (
+          <Text weight="medium" numberOfLines={1}>
+            {label}
+          </Text>
+        )}
         <View style={[styles.stackedValueRow, { minHeight }]}>
           <View style={styles.value}>{children}</View>
           {trailing != null ? trailing : null}
@@ -140,9 +167,13 @@ export function DetailRow(props: DetailRowProps) {
   }
   return (
     <View style={[styles.row, { minHeight }]}>
-      <Text size={labelSize} color="muted" style={form ? { width: labelWidth } : styles.flexLabel}>
-        {label}
-      </Text>
+      {info != null ? (
+        infoLabel(form ? { width: labelWidth } : styles.flexLabel)
+      ) : (
+        <Text size={labelSize} color="muted" style={form ? { width: labelWidth } : styles.flexLabel}>
+          {label}
+        </Text>
+      )}
       {form ? <View style={styles.value}>{children}</View> : children}
       {table?.trailingWidth != null ? (
         <View style={[styles.trailingCell, { width: table.trailingWidth }]}>{trailing}</View>
@@ -171,6 +202,8 @@ const styles = StyleSheet.create({
     gap: 12,
   },
   flexLabel: { flex: 1 },
+  labelWithInfo: { flexDirection: "row", alignItems: "center", gap: 4 },
+  labelShrink: { flexShrink: 1 },
   // Form mode (labelWidth set): the value column FILLS the row so every inline
   // editor spans the SAME width — and none jumps wider when it swaps to the
   // (flex:1) edit control. A stretch column, so an InlineEditView / InlineStatic

package/src/section_heading.tsx

@@ -88,18 +88,23 @@ export interface SubsectionHeadingTitleProps {
   children: React.ReactNode;
   /** Heading rank. Defaults to 3 — one level under `SectionHeadingTitle`'s 2. */
   level?: HeadingLevel;
+  /** An ⓘ popover after the title — a short "what this is / where it came from"
+   * gloss, mirroring `SectionHeadingTitle`'s `info`. */
+  info?: string;
 }
 
 /** The subsection title — ALWAYS `###` (lg semibold), the fixed step under the
  * xl section title and above the md/sm body. Grows to push siblings (a
  * `SectionHeadingMeta`, a `Badge`, an action) to the right edge. */
 export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
-  const { children, level = 3 } = props;
+  const { children, level = 3, info } = props;
+  const words = useLoticsLocale();
   return (
-    <View style={{ flex: 1 }}>
+    <View style={{ flex: 1, flexDirection: "row", alignItems: "center", gap: 6 }}>
       <Text level={level} size="lg" weight="semibold">
         {children}
       </Text>
+      {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
     </View>
   );
 }
@@ -139,6 +144,9 @@ export interface SectionHeadingTitleProps {
  * push any sibling actions to the right edge. */
 export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
   const { children, description, icon, level = 2, weight = "semibold", info } = props;
+  // Hoisted — a hook inside the `info ?` ternary breaks hook ordering the
+  // render `info` appears or disappears.
+  const words = useLoticsLocale();
   return (
     <View style={{ flex: 1, gap: 2 }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
@@ -146,7 +154,7 @@ export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
         <Text level={level} weight={weight} size="xl">
           {children}
         </Text>
-        {info ? <InfoPopover text={info} accessibilityLabel={useLoticsLocale().sectionHeading.info} /> : null}
+        {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
       </View>
       {description ? (
         <Text color="zinc-500" size="sm">