@lotics/ui 45.5.1 → 45.6.1

package/AGENTS.md

@@ -68,11 +68,15 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   `HeadingAltitudeContext`. Do not look for a per-surface heading variant and do not hand-pick a
   size: a `##` inside a drawer is 24px over the drawer's own 20px title.
   → [composition.md §The heading ramp](./docs/composition.md).
-- **`EmptyState` carries NO verb, and a FAILED read is not an empty one.** Four region states,
-  picked by what the region can ASSERT: `Skeleton`/`Loading` in flight → **`ErrorState`**
-  (`message`/`detail`/`onRetry`) on failure → `EmptyState` (succeeded, found nothing) →
-  `CompletionState` on done. An alert glyph inside an empty state claims the read succeeded when
-  nothing is known. → [catalog.md §Status / feedback](./docs/catalog.md).
+- **`EmptyState` carries NO verb, a FAILED read is not an empty one, and a BAND is not a region.**
+  Four region states, picked by what the region can ASSERT: `Skeleton`/`Loading` in flight →
+  **`ErrorState`** (`message`/`detail`/`onRetry`) on failure → `EmptyState` (succeeded, found
+  nothing) → `CompletionState` on done. An alert glyph inside an empty state claims the read
+  succeeded when nothing is known. How much quiet it reserves is a density axis — `compact` for
+  one band of a record (left-aligned, and glyph-less because an inline mark beside `sm` text
+  cannot be both legible and cap-aligned in this icon set), the default for a whole region.
+  → [catalog.md §Status / feedback](./docs/catalog.md),
+  [composition.md §Empty states](./docs/composition.md).
 - **Progress: ONE compound, TWO axes — and both are about meaning.** A run of markable rows is
   `checklist` (`Checklist` + `ChecklistGroup` + `ChecklistItem`, over `stepper`). **`connected`**
   asks *is this a sequence* — on for one record walking positions, off for N items handled in any

package/docs/catalog.md

@@ -927,11 +927,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`callout`** — `Callout`, `CalloutTitle`, `CalloutText`, `CalloutActions` (`tone`
   info|success|warning|error|neutral): inline status band — a MESSAGE (`warning`/`error`
   are ARIA `alert`s). For a form / nested content surface use **`Inset`**, never a Callout.
-- **`empty_state`** — `EmptyState`: centered placeholder for a read that SUCCEEDED and found
+- **`empty_state`** — `EmptyState`: placeholder for a read that SUCCEEDED and found
   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.
+  their own clear, and a FAILED read is `ErrorState`, not this. **`compact`** for one BAND of a
+  record — left-aligned, glyph-less, 56px against the default's 178 — because the
+  heading above it has already proved the surface rendered; the centred default speaks for a
+  whole region, where nothing else is in view to say so. → composition.md § Empty states.
 - **`error_state`** — `ErrorState`: the region-scale FAILED read — `message` + optional `detail`
   + `onRetry` (the kit renders the button and words it from the locale pack, so "try again" reads
   the same everywhere). The fourth of the region states: `Skeleton`/`Loading` in flight → this on
@@ -1474,6 +1477,15 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   when a slot is passed: `right` is routinely conditional, and an anatomy that flipped on that
   would make two rows in one list press differently. Nothing to opt into — a decorative
   `right` simply stops being part of the press target.
+  **The row OWNS its `title`/`description` pair, so do not hand-roll one beside it.** Both
+  lines are `sm`, `leading="tight"`, no gap between them — the stacked-pair law in
+  [composition.md](./composition.md), applied by the component rather than restated at each
+  call site. It shipped rendering that pair as PROSE (two 24px boxes plus a 2px gap = 12px
+  between the lines, against the 6px the rule prescribes), and the height was sized around
+  that mistake at 64, which left a correctly-sized `md` mark adrift in it; the row is 56 now.
+  A `description` passed as a NODE keeps its own leading — the component only sets it on the
+  string branch, because forcing a line box on somebody else's subtree re-spaces content that
+  may not be a line of text at all.
 - **`table`** — `Table` + `TableRow` + `TableCell`: the paginated high-volume register
   (columns defined once, `sortLabels` localizable; rows are `PressableRow`-based).
   CONTAINER-RESPONSIVE with no prop (measures itself, like `Breakdown`/`DetailTable`): when

package/docs/composition.md

@@ -2011,6 +2011,33 @@ wearing an alert glyph. The three empties get DIFFERENT copy:
 - **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".
 
+**How much QUIET it reserves depends on what it speaks for — `compact` inside a record.** The
+default holds a screenful because nothing else is in view: collapsing to two grey lines would
+read as a rendering bug rather than a state, which is the first of the three jobs. Inside a
+record that premise is false. The band's heading above it, the sections below it and the add
+verb beside it have already proved the surface rendered; the only open question is what this one
+band holds, and a screenful is a long way to say "nothing yet". Measured on a four-section
+record where three bands can be empty at once, the default spent **178px per band** and pushed
+the section the reader opened the record FOR under the fold on a 768px screen — every probe
+passes on that page, because nothing is wrong with any element on it.
+
+So: `compact` on a band, the default on a region. It is a DENSITY axis, not a second component —
+same three jobs, same two strings, same no-verb rule. Compact also sets its text to the LEFT,
+because the heading directly above it establishes that edge and a centred block beneath a
+left-aligned heading reads as a fragment of a different page (§ Canvas & content column).
+
+**An inline mark beside `sm` text cannot be both legible and aligned, so compact takes no glyph.**
+Worth knowing as a general fact about this icon set, not just about this component: it is lucide
+at a fixed stroke on a 24 viewBox, so the artwork fills 20/24 of whatever box you give it. Beside
+`sm` text the CAP HEIGHT is 11px, so a mark has to be ~13px to sit ON the line instead of
+straddling it — and at 13–16px a glyph with interior detail (`package`, `receipt`, `file-text`)
+closes up into a smudge. At 20px it reads, and its 16.7px of artwork then stands half again as
+tall as the capitals beside it, rising above them and dropping past the baseline. Three sizes,
+three different complaints, no size that answers both. Reach for a mark beside text only where
+the glyph is SIMPLE (`check`, a chevron, a dot) or the text is `md` or larger; a detailed glyph
+wants the block form, where it gets 28px and a line of its own. Here the anchoring is already
+done by the band's heading, which is the premise the whole variant rests on.
+
 ### Buttons & action labels — the outcome, verb-first
 
 A label names the OUTCOME of pressing — verb + object, 2–4 words (GOV.UK: "Save and continue",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "45.5.1",
+  "version": "45.6.1",
   "type": "module",
   "exports": {
     "./vite": {

package/src/empty_state.tsx

@@ -3,20 +3,64 @@ import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
 import { colors } from "./colors";
 
-interface EmptyStateProps {
+interface EmptyStateBase {
   /** What's empty, in plain language ("Không có nhân viên nào khớp"). */
   message: string;
   /** What the user can do about it ("Thử từ khóa khác"). */
   hint?: string;
-  /** Optional Lucide glyph centered above the message — a visual anchor so the
-   *  empty region reads as a deliberate state, not two lone lines of muted text. */
+}
+
+/** The whole region: centred, generous, with an optional glyph anchoring it. */
+interface EmptyRegionProps extends EmptyStateBase {
+  compact?: false;
+  /** Lucide glyph centred above the message — a visual anchor so the empty
+   *  region reads as a deliberate state, not two lone lines of muted text. */
   icon?: IconName;
 }
 
 /**
- * Centered placeholder for an empty list/filter result. Generous vertical
- * space on purpose — an empty region that collapses to nothing reads as a
- * rendering bug, not a state.
+ * ONE BAND of a record, rather than the whole region.
+ *
+ * The default reserves a screenful of quiet because it speaks for everything in
+ * view: nothing else is on the surface, so collapsing to two grey lines would
+ * read as a rendering bug. Inside a record that premise is false — the heading
+ * above it, the sections below it and the add verb beside it all say the surface
+ * rendered fine, and the only open question is what this one band holds.
+ *
+ * Measured on a four-section record where three bands can be empty at once, the
+ * default cost 178px per band and pushed the section a reader had opened the
+ * record FOR below the fold on a 768px screen. Compact says the same thing in
+ * 56, and sets to the LEFT — a band's heading already establishes that edge, and
+ * a centred block under a left-aligned heading reads as a fragment of another
+ * page.
+ *
+ * IT TAKES NO GLYPH, and that is a property of this icon set rather than a
+ * preference. The set is lucide at a fixed stroke on a 24 viewBox, so its
+ * artwork fills 20/24 of whatever box it is given:
+ *
+ *   - beside `sm` text the CAP HEIGHT is 11px, so an inline mark has to be
+ *     ~13px to sit ON the line rather than straddle it;
+ *   - at 13-16px a glyph with interior detail (`package`, `receipt`,
+ *     `file-text`) closes up and reads as a smudge;
+ *   - at 20px it reads, but its artwork is 16.7px against that 11px cap — half
+ *     again as tall as the capitals, rising above them and dropping past the
+ *     baseline.
+ *
+ * There is no size that is both legible and aligned, which is why tuning it
+ * three times produced three different complaints. The anchor's job — "this
+ * region is deliberate, not stray text" — is already done here by the heading
+ * and its add button, which is the very premise this variant rests on. So the
+ * type refuses the prop rather than the component silently dropping it.
+ */
+interface EmptyBandProps extends EmptyStateBase {
+  compact: true;
+  icon?: never;
+}
+
+type EmptyStateProps = EmptyRegionProps | EmptyBandProps;
+
+/**
+ * Placeholder for an empty list, filter result, or record band.
  *
  * IT CARRIES NO VERB — the prop is gone, not narrowed. This took an
  * `action?: ReactNode` and two different things went into it, both wrong here:
@@ -35,6 +79,17 @@ interface EmptyStateProps {
  * filters that emptied it carry their own clear.
  */
 export function EmptyState(props: EmptyStateProps) {
+  if (props.compact) {
+    return (
+      // `tight` on BOTH lines — the two are one object, and prose leading puts
+      // enough empty box between them to read as two (§ Typography). The pair
+      // measured 44px for 26px of type before this.
+      <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}
+      </View>
+    );
+  }
   return (
     <View style={styles.container}>
       {props.icon ? (
@@ -70,4 +125,8 @@ const styles = StyleSheet.create({
   line: {
     textAlign: "center",
   },
+  compactContainer: {
+    paddingVertical: 8,
+    gap: 2,
+  },
 });

package/src/list_item.tsx

@@ -57,15 +57,29 @@ export function ListItem(props: ListItemProps) {
   const body = (
     <>
       {left}
+      {/* A STACKED PAIR, and it was rendered as prose. Both lines are `sm`, so
+          the rungs were never the problem — the LEADING was: two 24px prose line
+          boxes around 14px glyphs leave 5px of empty box above and below each,
+          which is 10px between them, and a `gap: 2` on the container made 12. The
+          composition rule this surface is supposed to follow puts a pair at 6:
+          `leading="tight"` on both body-rung lines and NO gap, because each tight
+          box already contributes 3px a side. Twice the intended distance is what
+          makes a name and its role read as two separate lines rather than one
+          object, which is how the defect gets reported — as "too far apart",
+          never as its cause.
+
+          `tight` goes on the string branch only. A caller passing a NODE owns its
+          own leading, and forcing one on somebody else's subtree would silently
+          re-space a description that is not a line of text at all. */}
       <View style={styles.textContainer}>
         {!!title && (
-          <Text weight="medium" numberOfLines={1} userSelect="none">
+          <Text weight="medium" leading="tight" numberOfLines={1} userSelect="none">
             {title}
           </Text>
         )}
         {!!description &&
           (typeof description === "string" ? (
-            <Text size="sm" color="zinc-500" numberOfLines={1} userSelect="none">
+            <Text size="sm" color="zinc-500" leading="tight" numberOfLines={1} userSelect="none">
               {description}
             </Text>
           ) : (
@@ -157,18 +171,27 @@ function PressRow(props: {
 }
 
 const styles = StyleSheet.create({
+  // 56, not 64. The height was sized around a pair rendered as prose — two 24px
+  // boxes plus a 2px gap is 50, and 64 left 14px of slack the row did not ask
+  // for, which is what made a correctly-sized `md` mark (28px, the documented
+  // rung for a person in a list) look adrift in it. A tight pair is 40, so 56
+  // gives it the same 8-a-side the rest of the kit's rows carry. A title-only
+  // row keeps one 20px line centred in the same box, so the two shapes still
+  // share a beat.
   container: {
     flexDirection: "row",
     alignItems: "center",
     gap: 8,
-    height: 64,
+    height: 56,
     paddingHorizontal: 8,
     marginHorizontal: -8,
     borderRadius: 12,
   },
+  // NO GAP. Each tight line box already contributes 3px above and below its
+  // glyphs, so the pair reads at 6px — a gap here is a third source of space
+  // between two lines meant to read as one object.
   textContainer: {
     flex: 1,
-    gap: 2,
     alignItems: "flex-start",
   },
   selected: {