@lotics/ui 45.5.0 → 45.6.0

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/MIGRATION.md

@@ -20,11 +20,14 @@ chips from carrying their own remove ✕.
 now means the removable RESTING chip and takes `(option, { remove })`, so borrowing it for the
 menu put a ✕ on every option in the list.
 
-**Every option list's rows sit 4px apart.** `OptionList` declared that spacing all along, but
+**Every option list's rows sit 2px apart.** `OptionList` declared that spacing all along, but
 put it on the ScrollView's viewport rather than its content container, where it fell between
 nothing — so rows rendered flush and two adjacent SELECTED rows merged into one tinted block. Every
 selector that opens a list (`Select`, `Picker`, `InlineSelect`, the member pickers, menus) is now
-slightly taller for the same number of rows, and a list capped at its 320px max shows one fewer.
+slightly taller for the same number of rows. A field's chips take 4px on BOTH axes — the row gap was
+half the column gap, pinching a wrapped field against its own first line. A list row is read top to
+bottom and needs only enough space not to merge with its neighbour; a chip sits beside other
+objects and wants the wider setting.
 
 **A multi `InlineSelect`'s chips follow the working set while its list is open** — the draft you
 are building, not the stored value. Ticking a row or pressing a chip's ✕ now shows immediately

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

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.0",
+  "version": "45.6.0",
   "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/inline_select.tsx

@@ -306,6 +306,9 @@ export function InlineSelect<T extends string, D = unknown>(props: InlineSelectP
 }
 
 const styles = StyleSheet.create({
-  tags: { flexDirection: "row", alignItems: "center", flexWrap: "wrap", columnGap: 4, rowGap: 2 },
+  // ONE gap on both axes: a wrapped chip is the same object as the one beside it,
+  // so the second line should breathe like the first. The row gap used to be half
+  // the column gap, which pinched a wrapped field against its own first line.
+  tags: { flexDirection: "row", alignItems: "center", flexWrap: "wrap", gap: 4 },
   error: { marginTop: 4 },
 });

package/src/option_list.tsx

@@ -244,7 +244,11 @@ const styles = StyleSheet.create({
     maxHeight: 320,
   },
   optionsContent: {
-    gap: 4,
+    // 2, where a field's chips sit at 4. A row here is a 40px LIST line read top to
+    // bottom, and needs only enough space to stop two tinted rows reading as one
+    // block; a chip is an object sitting beside other objects and wants the wider
+    // setting. Two numbers because they answer two questions, not one token split.
+    gap: 2,
   },
   selectAllContainer: {
     flexDirection: "row",