@lotics/ui 33.0.0 → 34.0.0

package/MIGRATION.md

@@ -4,6 +4,50 @@ 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.
 
+## 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),

package/docs/composition.md

@@ -517,7 +517,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "33.0.0",
+  "version": "34.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/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