@lotics/ui 47.15.1 → 47.16.0

package/docs/catalog.md

@@ -1147,7 +1147,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`

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.0",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",

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>
   );
 }