@lotics/ui 33.0.0 → 35.0.0

package/AGENTS.md

@@ -17,7 +17,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (the `FilesEditor` COMPOUND — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md)., the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows, master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget). |
 
 ## Iron rules

package/MIGRATION.md

@@ -4,6 +4,79 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 35.0.0 — `FilterChip` has no Clear footer; the × is the clear
+
+`FilterChip` no longer renders a Clear button in its popover footer. **Nothing to
+change at a call site** — `onClear` and `clearLabel` are unchanged, and the × on
+the pill still clears, still carries `clearLabel` as its tooltip, and still
+replaces the chevron whenever the chip is active.
+
+**Why.** The pill's × and the footer button did the same thing, and the footer
+cost a whole bordered band to say it twice. The editors this pill exists to wrap
+bring their own bottom actions — an `OptionList` with `enableSelectAll` renders
+"Select all / Deselect all" in a bordered band of its own — so a multi-select
+filter ended with TWO stacked rules, the lower one holding a single button that
+"Deselect all" directly above it already performed. Measured on a live filter:
+bands of 49px and 47px, each with its own 1px top border.
+
+The × is also the more reachable of the two: it is on the pill, which is on
+screen whether or not the popover is open, while the footer button needed the
+panel opened first.
+
+**One behaviour change worth knowing:** passing a custom `footer` no longer
+suppresses the ×. `showClear` used to gate both, so a Save-footer pill silently
+lost its clear — if you were relying on that to hide the ×, pass no `onClear`
+instead, which is what "not clearable" has always meant.
+
+**If your filter had no other way to empty itself**, it still does: the ×. And if
+your editor genuinely needs a clear INSIDE the panel (a range slider, a counter —
+controls with no per-option deselect), put one in the `footer` slot, which is
+still there and is now the only thing that draws a footer band.
+
+## 34.0.0 — one avatar rung fits a control band
+
+**`AVATAR_PX.md` is 28, not 36.** Nothing to change at a call site — `md` is still
+the default and still shows two initials — but every `Avatar`, `MemberChip` and
+`GroupAvatar` on that rung renders 8px smaller (its initials drop a type rung with
+it, to hold the same share of the circle), and the controls holding them get
+SHORTER, which is the point.
+
+`CONTROL_HEIGHT` is a promise: a toolbar row, a record's value column and a
+picker's option list read as one band because every control on them is 40. TEXT
+keeps that promise for free — a line is ~20, so `minHeight` governs and a
+surface's vertical padding never binds. That is exactly why each 40px surface had
+quietly picked its own inset (`Select`'s trigger 4, the inline editor 6,
+`InlineSlot` 8) with no number to pick it from, and nothing on a resting screen
+ever showed the disagreement.
+
+Putting a 36px avatar in one broke all three at once. The same member chip
+measured **46** in a `Select` trigger, **50** in an inline editor and **54** in an
+`InlineSlot` — a record whose value column is the only thing telling a reader
+these fields belong to one record, with the member row 10px off every other row
+in it.
+
+So the budget is stated once and the surfaces derive from it:
+
+- **`CONTROL_CONTENT_HEIGHT`** (28) — the tallest fixed-height node a 40px band
+  seats, 6 per side of air. Not a fresh number: it is what `InlineButton` and a
+  `md` `IconButton` had already settled on for sitting inside a field. An avatar
+  is not a special kind of child, so it gets the same height they do.
+- **`CONTROL_PADDING_V`** (5) — derived, and the 1px border counts inside the 6
+  per side. Reading the padding and forgetting the border is how the drift
+  started.
+
+Both from `@lotics/ui/control_surface`. **If you build your own 40px control, pad
+by `CONTROL_PADDING_V` and keep fixed-height children at or under
+`CONTROL_CONTENT_HEIGHT`** — anything taller belongs in a row that sets its own
+height, not in a control.
+
+Two knock-on effects worth looking at once:
+
+- A **multi-line control at rest** (a rich select showing title + description) is
+  ~2px shorter, since its padding came off the same constant.
+- An `InlineSlot`/`InlineStatic` value now actually matches the editor beside it.
+  It always claimed to; it was 2px more padded, invisible at one line.
+
 ## 33.0.0 — `DrawerScrollArea`
 
 A `Drawer` gets the content primitive its siblings already had, named to match

package/docs/catalog.md

@@ -76,12 +76,20 @@ inline: a picker option, an assignee, a `select_member` value. Pure: resolve the
 your directory and pass `name` / `image`; never hand-roll `Avatar` + `Text`. (`MemberSelect`
 renders these per option.)
 
-**Size is a RUNG, never a pixel count** — `sm | md | lg | xl` = 24 / 36 / 48 / 72
+**Size is a RUNG, never a pixel count** — `sm | md | lg | xl` = 24 / 28 / 48 / 72
 (`@lotics/ui/avatar_size`, shared by `Avatar`, `MemberChip` and `GroupAvatar`). Default `md`.
 The number was removed because the same concept had drifted to eleven different values across
 the product and its apps, so one person looked different on every screen. Pick by density:
-`sm` for a dense row or inline cell, `md` for a register or list (the default), `lg` for a
-prominent row or the account menu, `xl` for a profile's own header.
+`sm` for a dense row or inline cell, `md` for a control band, register or list (the default),
+`lg` for a prominent row or the account menu, `xl` for a profile's own header.
+
+**`md` is `CONTROL_CONTENT_HEIGHT`** (28) — the largest rung a 40px control band seats without
+growing, and the height `InlineButton` and a `md` `IconButton` already used to sit inside a
+field. An avatar is the tallest thing in whatever row holds it, so a rung that overshoots
+doesn't look slightly big, it RESIZES the control: at the old 36 the same member chip measured
+46 in a `Select` trigger, 50 in an inline editor and 54 in an `InlineSlot`, because each
+surface had picked its own inset with no number to pick it from. Put nothing taller than `md`
+in a control — a bigger avatar belongs in a row that sets its own height.
 
 **`sm` shows ONE initial; every larger rung shows two** — two letters are not legible at 24px.
 That is the practical reason not to reach for `sm` by reflex: on a real roster a single letter
@@ -411,7 +419,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   hand-rolled plain DOM/CSS (nothing injects them automatically; `@lotics/ui` components
   don't need them).
 - **`spacing`** — the `SPACE` scale + `SpaceToken`.
-- **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_RADIUS` (10), `CONTROL_TEXT_INSET`
+- **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_CONTENT_HEIGHT` (28 — the tallest
+  FIXED-height node a 40px band seats, 6 per side of air; what `InlineButton` and a `md`
+  `IconButton` already used, now named so an avatar or any other child lands on it too. Text
+  never needs it because `minHeight` governs a single line, which is exactly why three surfaces
+  could each pick a different inset and only disagree once an avatar went in),
+  `CONTROL_PADDING_V` (5 — derived from the pair, BORDER INCLUDED in the 6 per side; every 40px
+  surface pads by it instead of a number of its own), `CONTROL_RADIUS` (10), `CONTROL_TEXT_INSET`
   (9 — how far a control insets its OWN text: 1px border + 8px padding; anything that must line
   up with a control's WORDS rather than its box carries it — a caption under an inline editor,
   a note under a figure — rather than a hand-measured 8),
@@ -1103,7 +1117,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `isColumnFilterActive` + `columnFilterSummary`: the typed per-column filter pill; for a
   register filtering on several columns.
 - **`filter_chip`** — `FilterChip` + `selectSummary`: the toolbar filter pill hosting a
-  facet (options, a `Slider range`, a `Counter`).
+  facet (options, a `Slider range`, a `Counter`). It draws NO bottom band of its own — the ×
+  on the pill is the clear, and the editor inside brings whatever actions it has, so a
+  multi-select's "select all / deselect all" is the only rule in the panel. `footer` is for an
+  editor that must COMMIT (Cancel / Save); reach for it only then, since it adds a second band
+  under an editor that already has one.
 - **`summary_line`** — `SummaryLine`: the light inline summary of a register/list's FILTERED
   view, sits below the toolbar; NOT the boxed dashboard `kpi_strip` band. Every item is an
   AGGREGATE over the rows in view (a count, a sum, a fill), and the strip goes with the set it

package/docs/composition.md

@@ -397,6 +397,58 @@ so `Table` also serves read-only tabular data (a fee breakdown, a spec sheet), n
 registers. A pressable `TableRow` REQUIRES `accessibilityLabel` ("Open …") — its keyboard door is
 an empty overlay with no content to derive a name from.
 
+**A CELL THAT DOES NOT SET THE ROW'S HEIGHT MUST NOT VARY WITH THE DATA.** A row centres its
+cells, so such a cell's first line lands at `(rowH − cellH) / 2`: one line on some rows and two
+on others puts that first line at two different offsets, and the column stops having a baseline.
+Uniform ROW heights hide it completely — the rows measure identical, the content inside them does
+not — and the drift is against the row's own centred chrome (ordinal, checkbox) as much as
+against the neighbouring columns.
+
+**It takes a height FLOOR to bite**, which is the part worth understanding rather than
+memorising. A `TableRow` with `minHeight` above its tallest cell holds slack that centring then
+distributes; without the floor the tallest cell sets the row, every cell starts at the top of its
+own row, and nothing drifts. So the cell that IS tallest may vary freely — it just makes the rows
+ragged instead, which is a different and far more visible problem. It is the cells living inside
+another cell's slack that have to hold still.
+
+**"Fixed" means the same every row, NOT one line.** A two-line cell is fine if it is two lines on
+every row. And the cost is real: bounding a cell usually means `numberOfLines={1}` and
+truncation, so you are buying a baseline with clipped text. Worth it for an identifier beside a
+contact; think harder for a cell whose job is prose, where the honest answer may be to move that
+content off the register entirely.
+
+Two corollaries, both counter-intuitive enough to state:
+
+- **Shrinking a NEIGHBOURING cell does not fix it.** The spread is a function of the varying
+  cell's own range, not of the row's height: a 20/42 cell spreads 11px in a 52px row and 11px in
+  a 68px one. Only bounding the cell that varies removes it.
+- **The fix is never a cross-axis knob.** `Table` has no `align` (see MIGRATION 32.0.0): topping
+  the cells leaves the chrome centred, so the row reads as scatter instead.
+
+Bound a cell by giving every row the same content, not by hoping the data is uniform. A line that
+appears only when its field is set is the defect; RESERVING the line is the fix — **but only when
+the field is nearly always present.** A box reserved for a value that half the rows lack reads as
+a column that forgot something, which is its own defect: prefer a field the rows actually carry
+(an identifier, a contact) over one that is merely interesting. A cell may hold more than one line
+freely when something FIXED occupies its top — a meter, a thumbnail — because the primary text
+then still lands near the row's centre, where the chrome already is. `tpl_item_list`'s identity
+cell is the worked example: name on top, the supporting values UNCONDITIONALLY beneath.
+
+**A pressable CELL wears `ROW_CONTROL_HOVER` / `ROW_CONTROL_PRESS`, never a hand-picked grey.**
+Reaching a cell means crossing its row, so both wash at once — a cell painting the row's own
+`zinc-100` vanishes under the pointer, and anything LIGHTER reads as a hole punched in the row.
+The tokens are one step darker for exactly that reason, and they are what `IconButton`,
+`CopyButton` and `CommentsButton` already paint, so a register whose cells use them speaks one
+hover language. Bleed the wash outward (`marginHorizontal: -8` against its own padding) so the
+cell's content stays on the column's edge — see `ROW_WASH_BLEED`.
+
+**Size a flexible column by what it CARRIES, measured.** A `flex` share is a claim about content;
+when the content shrinks — a value moves to the record, a stacked pair becomes a count — the
+share left behind is white space, and the columns beside it pay for it. Measure the widest row's
+content per column and set `flex` from that. A column whose cell holds a PROPORTION (a meter, a
+bar) is the exception in one direction only: cap it, because a gauge stops reading as an
+instrument once its track is long enough to be a rule across the row.
+
 Make a register SELECTABLE with the `Table` `leading` gutter + `selectAll` slot — a
 `CheckboxInput` per `TableRow` (its `leading` slot) + a select-all in the header band, the ticked
 rows `marked`, paired with a `FloatingActionBar` (its "Clear" escape is locale-resolved — pass
@@ -517,7 +569,19 @@ shape.
 
 ## One view-control vocabulary
 
-All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping band:
+All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping band.
+
+**A 40px band affords 28 (`CONTROL_CONTENT_HEIGHT`), and a surface pads by
+`CONTROL_PADDING_V` rather than a number of its own.** The height only holds for free when the
+content is TEXT: a line is ~20, so `minHeight` governs and the padding never binds — which is
+why a surface can pick any inset it likes and nothing on a resting screen ever contradicts it.
+The moment something with a FIXED height goes in — an avatar, a swatch, a thumbnail — that
+inset decides the control's whole height, and three surfaces that had each chosen their own
+(4, 6, 8) rendered one member chip at 46, 50 and 54. So: a fixed-height child is sized against
+the band's budget, never against how it looks alone, and a surface that needs more room than
+the budget is not a control. The budget is 28 because that is what `InlineButton` and a `md`
+`IconButton` were already using inside a field — a control's children must not differ in height
+by what KIND of thing they are, so an avatar takes the same number rather than a fourth one.
 
 - **`SearchInput`** is THE search box — a white `TextInputField` preset (the shared
   `CONTROL_RADIUS` like every other input, a thin border, the leading search glyph + a clear ✕).

package/examples/tpl_item_list.tsx

@@ -237,7 +237,16 @@ function HoSoRow({ hs, ordinal, daThu, selected, marked, selectable, onToggle, o
               because it is the one value copied often enough to earn one (a desk
               pastes it into a message, a rep dials it). The verb rides the value
               inside its own cell: the trailing gutter belongs to the ⋯, and with
-              two values in this cell it would have nothing to name. */}
+              two values in this cell it would have nothing to name.
+
+              UNCONDITIONAL, and that is the load-bearing part of this shape. A
+              row centres its cells, so a supporting line that appears only when
+              its field is set makes this cell two heights, and the NAME above it
+              then sits at two different offsets down the column while every row
+              still measures the same. That is why the values here are ones every
+              record carries — a key, a contact — rather than whichever field is
+              most interesting: the line has to be honest on every row to be
+              reservable at all. */}
           <View style={{ flexDirection: "row", alignItems: "center", gap: 2 }}>
             {/* The KEY, muted, on the supporting line — at most this, never a
                 column and never the row's name.
@@ -250,8 +259,13 @@ function HoSoRow({ hs, ordinal, daThu, selected, marked, selectable, onToggle, o
                 gives way, which is also the right order of loss: the phone has a
                 Copy control beside it that hands over the full value regardless. */}
             <Text size="xs" color="muted" tabular numberOfLines={1} style={{ flexShrink: 0 }}>{hs.ma}</Text>
-            <Text size="xs" color="muted" style={{ flexShrink: 0 }}> · </Text>
-            <Text size="xs" color="muted" tabular numberOfLines={1} style={{ flexShrink: 1 }}>{hs.dienThoai}</Text>
+            {/* A GAP, not a middot. Two facts of different kinds sat either side
+                of a ` · ` here, which is the separator this kit bans outright —
+                punctuation claiming a relation it refuses to name, and dropped
+                entirely by a screen reader. Spacing separates them without
+                asserting anything, and the two are already told apart by shape:
+                one is a key, one is a number with a Copy control on it. */}
+            <Text size="xs" color="muted" tabular numberOfLines={1} style={{ flexShrink: 1, marginLeft: 8 }}>{hs.dienThoai}</Text>
             <CopyButton value={hs.dienThoai} label="Copy phone number" />
           </View>
         </View>

package/package.json

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

package/src/avatar_size.ts

@@ -13,11 +13,28 @@ import type { TextSize } from "./text";
  */
 export type AvatarSize = "sm" | "md" | "lg" | "xl";
 
+/**
+ * THE RUNGS.
+ *
+ * `md` IS `CONTROL_CONTENT_HEIGHT`, and that is the whole design. An avatar is
+ * the tallest thing in any row that holds one, so a rung that overshoots its
+ * container does not look slightly big — it RESIZES the container. The default
+ * rung therefore has to be the largest a 40px control band can seat, and that
+ * number was already fixed elsewhere in the kit: 28, what `InlineButton` and a
+ * `md` `IconButton` use to sit inside a field. An avatar is not a special kind
+ * of child; it gets the same height they do.
+ *
+ * It was 36, which fits nothing. The same member chip measured 46 in a `Select`
+ * trigger, 50 in an inline editor and 54 in an `InlineSlot` — three heights for
+ * one control band, because each surface had picked its own inset and none of
+ * them had a number to pick it FROM.
+ */
 export const AVATAR_PX: Record<AvatarSize, number> = {
   /** Dense rows and inline chips — one initial, because two do not fit. */
   sm: 24,
-  /** The default: registers, lists, anywhere a person is a row. */
-  md: 36,
+  /** The default: a 40px control band, a register, a list — anywhere a person is
+   *  a row. Equals `CONTROL_CONTENT_HEIGHT` (`control_surface`). */
+  md: 28,
   /** Prominent rows, the account menu. */
   lg: 48,
   /** A profile's own header. */
@@ -32,19 +49,27 @@ export const AVATAR_PX: Record<AvatarSize, number> = {
  * native, and `text.css` moves again at 768px, so these are the desktop numbers
  * and only a render can give them):
  *
- *   sm  12 on 24 = 50%   ·  md  14 on 36 = 39%
- *   lg  20 on 48 = 42%   ·  xl  32 on 72 = 44%
+ *   sm  12 on 24 = 50%
+ *   md  12 on 28 = 43%
+ *   lg  20 on 48 = 42%
+ *   xl  32 on 72 = 44%
  *
- * The two-letter rungs sit within 6 points of each other, so an avatar reads the
+ * The two-letter rungs sit within 2 points of each other, so an avatar reads the
  * same at every size rather than growing emptier as it grows — `lg` was on `md`
  * type (16 on 48 = 33%) and was visibly the thin one. `sm` runs richer by design:
  * one letter in a small circle needs the weight.
+ *
+ * `md` shares `sm`'s rung and is NOT the odd one out for it: the same 12px reads
+ * as 50% of a 24px circle holding one letter and 43% of a 28px circle holding
+ * two. Keeping it on `sm` type (14) would have put `md` at 50% — the fattest of
+ * the two-letter rungs, and the same defect in the other direction as the `lg`
+ * one this table was written to fix.
  */
 export const AVATAR_TEXT: Record<AvatarSize, TextSize> = {
   sm: "xs", // 12 on 24 — one letter, so it carries a larger share of the circle
-  md: "sm", // 14 on 36
-  lg: "lg", // 18 on 48
-  xl: "xxl", // 28 on 72
+  md: "xs", // 12 on 28
+  lg: "lg", // 20 on 48
+  xl: "xxl", // 32 on 72
 };
 
 const words = (name: string): string[] => name.trim().split(/\s+/).filter((w) => w !== "");

package/src/control_surface.ts

@@ -5,6 +5,38 @@ import { colors } from "./colors";
  *  buttons) aligns to it so a toolbar row reads as one band. */
 export const CONTROL_HEIGHT = 40;
 
+/**
+ * THE TALLEST FIXED-HEIGHT NODE A CONTROL BAND CAN SEAT — and so the inner height
+ * every 40px surface must afford. 6 per side of air, BORDER INCLUDED.
+ *
+ * `CONTROL_HEIGHT` is a promise — a toolbar row, a record's value column and a
+ * picker's option list read as one band because every control on them is 40. TEXT
+ * keeps that promise for free: a line is ~20, so `minHeight` governs and a
+ * surface's padding never binds. That is precisely why the promise broke the
+ * first time a control was handed something with a FIXED height. Each surface had
+ * quietly picked its own inset — 4, 6, 8 — with no number to pick it from, and
+ * nothing on a resting screen could reveal the disagreement; the moment a 36px
+ * avatar went in, the same member chip came out 46 in a `Select` trigger, 50 in
+ * an inline editor and 54 in an `InlineSlot`.
+ *
+ * 28 is not a fresh choice: it is what `InlineButton` and an `IconButton` at `md`
+ * had ALREADY settled on for sitting inside a field, air and all. Naming it once
+ * is what stops the next fixed-height child inventing a fourth number, and it is
+ * why an avatar on the default rung is 28 too — a control's children should not
+ * differ in height by what kind of thing they are.
+ *
+ * Anything taller does not belong in a control at all; it belongs in a row that
+ * sets its own height.
+ */
+export const CONTROL_CONTENT_HEIGHT = 28;
+
+/** A control's own vertical inset, derived so the band seats
+ *  {@link CONTROL_CONTENT_HEIGHT} at exactly {@link CONTROL_HEIGHT}. The 1px
+ *  border is part of the 6, so a bordered surface pads by this and an unbordered
+ *  one by this + 1 — reading the padding and forgetting the border is what let
+ *  three surfaces drift in the first place. */
+export const CONTROL_PADDING_V = (CONTROL_HEIGHT - CONTROL_CONTENT_HEIGHT) / 2 - 1;
+
 /** The narrowest a control may be and still be usable — below it, editors get
  *  crushed and option text has nowhere to go. It is the threshold at which a
  *  `DetailTable` gives up its side-by-side columns and stacks, and the floor

package/src/filter_chip.tsx

@@ -7,7 +7,6 @@ import { Chip } from "./chip";
 import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
 import type { PopoverSide, PopoverAlign } from "./popover";
 import { useLoticsLocale } from "./locale";
-import { Button } from "./button";
 
 export interface FilterChipProps {
   /** The dimension name — shown alone when inactive ("Owner"), prefixed when
@@ -18,10 +17,12 @@ export interface FilterChipProps {
    *  selection RICHLY in the trigger (member avatars, colour dots). Empty /
    *  undefined renders the inactive pill (label + chevron, no clear). */
   summary?: ReactNode;
-  /** Clears the dimension — renders the × on the pill AND a Clear in the popover
-   *  footer whenever a summary is present. */
+  /** Clears the dimension — renders the × on the pill whenever a summary is
+   *  present. The × is the ONLY clear: the editor inside brings its own bottom
+   *  actions, and a second clear in the popover footer stacked a redundant band
+   *  under them. */
   onClear?: () => void;
-  /** Label for the clear affordances (pass a translated string). */
+  /** Tooltip on the pill's × (pass a translated string). */
   clearLabel?: string;
   /** The editor revealed on press — a premium primitive (`Slider range`,
    *  `Counter`, `OptionList` multi) or any composed control. `FilterChip` owns
@@ -35,8 +36,11 @@ export interface FilterChipProps {
   /** Optional controlled popover state — for an editor that closes on Save. */
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
-  /** A custom popover footer (e.g. Cancel / Save) — replaces the baked Clear.
-   *  Lets a non-filter VALUE pill (a setting gate) reuse the same shell. */
+  /** A custom popover footer (e.g. Cancel / Save) — for an editor that commits
+   *  rather than applying live. Lets a non-filter VALUE pill (a setting gate)
+   *  reuse the same shell. Reach for it only when the editor NEEDS a commit: an
+   *  editor that already carries bottom actions of its own gets a second
+   *  bordered band from this. */
   footer?: ReactNode;
 }
 
@@ -61,9 +65,11 @@ export function selectSummary(
  * filter dimension, the sibling of `ChipGroup` (which lays ONE hot dimension's
  * options out inline). Many dimensions stay scannable because each collapses to
  * a single pill: inactive reads "Label ⌄", active reads "Label: summary" with an
- * × to clear. `FilterChip` bakes the consistent chrome — the preview pill, a
- * padded popover body for the composed editor, and a Clear footer when active —
- * so every filter looks and behaves the same. Drop a premium primitive inside
+ * × to clear. `FilterChip` bakes the consistent chrome — the preview pill and a
+ * padded popover body for the composed editor — so every filter looks and
+ * behaves the same. It adds NO bottom band of its own: the editor inside brings
+ * whatever actions it has, and a shell that also contributed one gave every
+ * multi-select filter two stacked rules. Drop a premium primitive inside
  * (`Slider range`, `Counter`, `OptionList` multi). With `footer` (+ controlled
  * `open`/`onOpenChange`) the same shell wraps a non-filter VALUE pill — a
  * setting gate with Cancel/Save — keeping it on the one pill surface. The table
@@ -73,9 +79,23 @@ export function FilterChip(props: FilterChipProps) {
   const { label, summary, onClear, children, side = "bottom", align = "start", open, onOpenChange, footer } = props;
   const clearLabel = props.clearLabel ?? useLoticsLocale().filterChip.clear;
   const active = summary != null && (typeof summary !== "string" || summary.length > 0);
-  // The clear × / Clear footer only when there's a clearable selection AND no
-  // custom footer — a valued, non-clearable pill ("Target: 20") keeps its chevron.
-  const showClear = active && !!onClear && !footer;
+  // THE × IS THE CLEAR, and it is the only one. A valued, non-clearable pill
+  // ("Target: 20") keeps its chevron.
+  //
+  // There used to be a baked Clear in the popover footer as well, and it was a
+  // duplicate that cost a whole extra band. The editors this pill is built for
+  // bring their own bottom actions — an `OptionList` with `enableSelectAll`
+  // renders "Select all / Deselect all" in a bordered band of its own — so the
+  // popover ended with TWO stacked rules whose lower one held a single button
+  // that "Deselect all" directly above it already performed. Measured on a live
+  // filter: bands at 49px and 47px, each with its own 1px top border.
+  //
+  // The × is also the more discoverable of the two: it sits on the pill, which
+  // is on screen whether or not the popover is open, and it carries `clearLabel`
+  // as its tooltip. The footer button was reachable only by opening the panel
+  // first. A custom `footer` (Cancel / Save) no longer suppresses it either —
+  // that coupling meant a Save-footer pill silently lost its clear.
+  const showClear = active && !!onClear;
 
   // Own the open state so the editor can close itself via the render-prop
   // `close`, while still honoring a controlled `open`/`onOpenChange` from the
@@ -112,13 +132,7 @@ export function FilterChip(props: FilterChipProps) {
       </PopoverTrigger>
       <PopoverContent style={styles.body} disableBodyScroll>
         {typeof children === "function" ? children({ close: () => setOpen(false) }) : children}
-        {footer ? (
-          <PopoverFooter>{footer}</PopoverFooter>
-        ) : showClear ? (
-          <PopoverFooter align="start">
-            <Button title={clearLabel} color="muted" onPress={onClear} />
-          </PopoverFooter>
-        ) : null}
+        {footer ? <PopoverFooter>{footer}</PopoverFooter> : null}
       </PopoverContent>
     </Popover>
   );
@@ -126,9 +140,9 @@ export function FilterChip(props: FilterChipProps) {
 
 const styles = StyleSheet.create({
   // The popover hugs its content — a wide control (e.g. Slider) sets its
-  // OWN fixed width; the shell never forces one. No extra padding: the editor and
-  // the Clear footer then share the popover's own 8px inset, so a multi-select's
-  // options, its select-all, and the Clear all line up on one left edge.
+  // OWN fixed width; the shell never forces one. No extra padding: the editor
+  // then sits on the popover's own 8px inset, so a multi-select's options and
+  // its select-all band line up on one left edge.
   body: {
     gap: 8,
   },

package/src/inline_button.tsx

@@ -2,11 +2,14 @@ import { type GestureResponderEvent } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 import { PressableHighlight } from "./pressable_highlight";
-import { CONTROL_TRANSITION } from "./control_surface";
+import { CONTROL_CONTENT_HEIGHT, CONTROL_TRANSITION } from "./control_surface";
 
 /** The height that fits INSIDE the 40px inline control band with 6px of air
- *  above and below — the same air a `DetailRow`'s label gets against its value. */
-const INLINE_BUTTON_HEIGHT = 28;
+ *  above and below — the same air a `DetailRow`'s label gets against its value.
+ *  This file is where that number was FIRST worked out; it now lives in
+ *  `control_surface` so an avatar or any other fixed-height child of a control
+ *  lands on the same line rather than inventing its own. */
+const INLINE_BUTTON_HEIGHT = CONTROL_CONTENT_HEIGHT;
 
 interface InlineButtonProps {
   /** The verb, as a word. An inline button is never icon-only — it sits on a

package/src/inline_edit.tsx

@@ -6,7 +6,7 @@ import { useLoticsLocale } from "./locale";
 import { ActivityIndicator } from "./activity_indicator";
 import { FocusRingPressable } from "./focus_ring_pressable";
 import { colors } from "./colors";
-import { FOCUS_RING, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
+import { FOCUS_RING, CONTROL_RADIUS, CONTROL_PADDING_V, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
 import { fontFamilyRegular, getInputTextStyle, getMultilineInputHeight, getTextColor, type TextColor } from "./text_utils";
 import { getInteractionModality } from "./interaction_modality";
 import { shouldOpenOnFocus, shouldRestoreFocusOnClose } from "./inline_focus";
@@ -653,11 +653,15 @@ const styles = StyleSheet.create({
     borderColor: colors.border,
     backgroundColor: colors.white,
     paddingHorizontal: 8,
-    // Vertical padding matters only when the display content is TALLER than
-    // one line (a rich select showing title + description at rest): minHeight
-    // still governs single-line rows, so those render pixel-identical, while
-    // multi-line content gets breathing room instead of touching the edges.
-    paddingVertical: 6,
+    // Vertical padding binds on two kinds of content, never on a single line
+    // (minHeight governs there, so those rows render pixel-identical whatever
+    // this is): content TALLER than one line, which gets breathing room instead
+    // of touching the edges, and content of FIXED height — an avatar, a swatch —
+    // which this decides the field's whole height for. Hence the shared
+    // constant: an editor seats a `CONTROL_CONTENT_HEIGHT` node at exactly 40,
+    // the same as every other 40px surface, rather than at a number this file
+    // happened to choose.
+    paddingVertical: CONTROL_PADDING_V,
     flexDirection: "row",
     alignItems: "center",
     gap: 6,

package/src/inline_slot.tsx

@@ -1,6 +1,6 @@
 import { StyleSheet, View, type StyleProp, type ViewStyle } from "react-native";
 import { type ReactNode } from "react";
-import { CONTROL_RADIUS } from "./control_surface";
+import { CONTROL_PADDING_V, CONTROL_RADIUS } from "./control_surface";
 import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
 
 export interface InlineSlotProps {
@@ -46,13 +46,16 @@ const styles = StyleSheet.create({
     borderWidth: 1,
     borderColor: "transparent",
     paddingHorizontal: 8,
-    // The editors' vertical padding too, not just the horizontal. A single line
-    // hides its absence — the box is `minHeight` 40 and the text is ~20, so both
-    // sides land on 40 whether or not this exists — but an auto-growing input
-    // sizes itself to content PLUS its padding and border, so from the SECOND
-    // line on, a value without this sits ~14px shorter than the input that
-    // replaces it. Matching by coincidence at one line is not matching.
-    paddingVertical: 8,
+    // The editors' vertical padding too, not just the horizontal — and it comes
+    // from the shared constant, NOT from the 8 the horizontal happens to use. A
+    // single line hides both the absence and a mismatch: the box is `minHeight`
+    // 40 and the text is ~20, so any padding from 0 to 10 lands on 40. It bites
+    // from the SECOND line on (an auto-growing input sizes to content PLUS its
+    // padding and border, so a value without this sits shorter than the input
+    // that replaces it) and on any FIXED-height content, where this slot's old
+    // hand-picked 8 made it 4px taller than the editor beside it for the very
+    // same child. Matching by coincidence at one line is not matching.
+    paddingVertical: CONTROL_PADDING_V,
     justifyContent: "center",
   },
 });

package/src/member_chip.tsx

@@ -12,7 +12,8 @@ interface MemberChipProps {
   image?: string | null;
   /** Optional secondary line under the name — e.g. email, role, department. */
   secondary?: string | null;
-  /** A rung on the shared avatar scale. Default `md`. */
+  /** A rung on the shared avatar scale. Default `md`, which is sized to seat in a
+   *  40px control band; drop to `sm` for a dense cell. See `AVATAR_PX`. */
   size?: AvatarSize;
   style?: StyleProp<ViewStyle>;
 }
@@ -26,6 +27,12 @@ interface MemberChipProps {
  * Pure: pass the member's fields in (from `useMembers`, or a resolved
  * `select_member` cell joined against that roster); this component fetches
  * nothing and carries no domain types.
+ *
+ * A chip's usual home is a 40px CONTROL BAND — a picker option, a select's
+ * trigger, an inline editor at rest, a diff slot — and the default `md` is sized
+ * to seat in one (`CONTROL_CONTENT_HEIGHT`). That is not a coincidence to
+ * preserve by hand: it is why `md` is 28 rather than the 36 that used to grow
+ * those three surfaces to 46, 50 and 54 for the very same chip.
  */
 export function MemberChip({ name, image, secondary, size = "md", style }: MemberChipProps) {
   const displayName = name?.trim() || "Unknown";

package/src/select.tsx

@@ -1,7 +1,7 @@
 import { StyleSheet, View, type GestureResponderEvent, type StyleProp, type ViewStyle } from "react-native";
 import { useState, useCallback, useMemo, type ReactNode, type Ref } from "react";
 import { colors } from "./colors";
-import { FOCUS_RING, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
+import { FOCUS_RING, CONTROL_RADIUS, CONTROL_HEIGHT, CONTROL_PADDING_V, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
 import { FocusRingPressable } from "./focus_ring_pressable";
 import { Text } from "./text";
 import { Popover, PopoverTrigger, PopoverContent } from "./popover";
@@ -293,11 +293,14 @@ const styles = StyleSheet.create({
     flexDirection: "row",
     alignItems: "center",
     paddingHorizontal: 6,
-    paddingVertical: 4,
+    // Shared, so a trigger seats a `CONTROL_CONTENT_HEIGHT` node at exactly
+    // `CONTROL_HEIGHT` — the hand-picked 4 here made this trigger 4px shorter
+    // than the inline editor holding the identical chip.
+    paddingVertical: CONTROL_PADDING_V,
     borderWidth: 1,
     borderColor: colors.border,
     borderRadius: CONTROL_RADIUS,
-    minHeight: 40,
+    minHeight: CONTROL_HEIGHT,
   },
   opened: {
     // Mouse-opened, so the trigger never takes keyboard focus — wear the same 2px