@lotics/ui 37.1.0 → 38.1.0

package/AGENTS.md

@@ -118,9 +118,10 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   anyway. Use `FileRow` / `FileRows`, where the full name is the row and a second line can
   carry a date, a size, a status, a diff. Photos, scans and drawings are identified by their
   CONTENT — the filename is `IMG_4471.jpg` and tells nobody anything — so use
-  `FileThumbnailGrid`, where the picture is the identity and many fit on one screen. A mixed
-  set follows its majority; an app whose attachments are overwhelmingly paperwork should not
-  pay a grid's wasted space for the occasional photo.
+  `FileThumbnailGrid`, where the picture is the identity and many fit on one screen. **A mixed
+  set follows its MAJORITY, and that one surface holds the whole set — never split a pile by
+  file type** — the cost lands on the minority by design, not on the reader, who would otherwise
+  get two places to look for one thing.
   → [catalog.md](./docs/catalog.md).
 - **A reference to another record is a FIELD** — it wears the inline editor's own resting
   surface and PEEKS its facts on press; EVERY verb lives in the peek's footer as a `Button`,

package/MIGRATION.md

@@ -4,6 +4,34 @@ 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.
 
+## 38.0.0 — the `lg` avatar is a control (40), not a size (48)
+
+`AVATAR_PX.lg` was 48 and `AVATAR_TEXT.lg` was `lg` type. They are now **40** and `md`
+type. Every `size="lg"` avatar — `Avatar`, `MemberChip`, `GroupAvatar` — renders 8px
+smaller. Nothing to pass; there is no way to ask for 48.
+
+**Why.** The scale's whole argument is that a rung quotes a number the system already
+owns, which is why `md` is `CONTROL_CONTENT_HEIGHT` (28). `lg` quoted nothing. It is
+the rung for an avatar that stands in a band **on its own** — an account menu beside a
+row of icon buttons — and those are `CONTROL_HEIGHT`, so at 48 the avatar was the one
+item in the row that visibly got out. 40 is that number.
+
+**If a surface genuinely needs a bigger person figure**, it is not in a control band,
+and `xl` (72) is the rung for it. If neither fits, the surface is setting its own row
+height and should say so rather than reaching for an avatar rung to do it.
+
+### `PageHeader` gained `leading`, and its title now wraps instead of overflowing
+
+`leading` is additive — a control rendered immediately BEFORE the title, for something
+that changes what is AROUND the content (a side-panel toggle, a back arrow), as opposed
+to `actions`, which act on the content itself.
+
+The behaviour change to check: a title too long for the row used to keep its intrinsic
+width and push `actions` clean off the row — measured at 417px outside a 480px header.
+It now wraps, and `actions` hold their place. **If you worked around this** by shortening
+a title, hiding the CTA at narrow widths, or capping the header's width, that workaround
+is now what is distorting the layout — drop it.
+
 ## 37.0.0 — `PageContent`'s side gutter is a token, and responsive
 
 `PageContent` padded `16` at every width. It now uses `pagePad` from

package/docs/catalog.md

@@ -76,20 +76,23 @@ 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 / 28 / 48 / 72
+**Size is a RUNG, never a pixel count** — `sm | md | lg | xl` = 24 / 28 / 40 / 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 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.
+**Both middle rungs quote `control_surface`, and which one you want depends on whether the
+avatar is IN a control or IS one.** `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. `lg` is `CONTROL_HEIGHT` (40) — the avatar that stands in a band on its
+own, an account menu beside a row of icon buttons, so it measures what they do. Anything bigger
+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
@@ -283,6 +286,21 @@ says the read succeeded and found nothing, a failed read knows neither.
 
 ### Files
 
+**Pick the surface FIRST, and pick exactly one per set.** Documents get a LIST (`FileRows`),
+images get a GRID (`FileThumbnailGrid`) — the discriminator is what identifies the file to the
+person hunting for it: a PDF's thumbnail is a grey page identical to every other grey page, so
+its NAME is the identity; a photo's filename is `IMG_4471.jpg` and tells nobody anything, so its
+CONTENT is. **A mixed pile follows its majority and stays whole.** Sorting one pile by mime type
+into a list *and* a grid is the mistake — it gives the reader two places to look for the same
+thing. The minority is not stranded by this: a non-image tile in a grid renders a `DocumentCard`
+printing its filename, and a photo in a list keeps its full name plus a meta line and is ONE tap
+from the picture, because a `FileRows` row press opens the built-in gallery. (The badge is
+MIME-driven, so that row shows a generic image mark, not the shot itself — which is the cost the
+majority already decided to pay.) A screen showing BOTH surfaces (`tpl_record`) does
+so because it holds two distinct SETS the reader asks different questions of — the paperwork
+that arrived on the record, and the hand-over photos taken against it — not because one set was
+split by type.
+
 `FilesEditor` (THE attachment surface: an upload-aware grid whose bar you COMPOSE — the root
 owns selection + gallery + confirmed remove, the bar pieces and any HOST verb go below it via
 `useFilesEditorSelection`),
@@ -517,7 +535,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   useSeparator` inserts and what menus/popovers put between option groups.
 - **`container`** — `Container`: centers content at a max width (`ContainerSize` sm|md|lg,
   `CONTAINER_SIZES`).
-- **`page_header`** — `PageHeader`: the page's title band; `actions` puts page-level CTAs on the title row (right-aligned), while `left`/`right` form a separate nav row above.
+- **`page_header`** — `PageHeader`: the page's title band. `actions` puts page-level CTAs on
+  the title row (right-aligned) and `leading` puts a control immediately BEFORE the title;
+  `left`/`right` form a separate nav row above. Split `leading` from `actions` by what the
+  control acts on: `actions` do something to the page's CONTENT (create, sort, export),
+  `leading` changes what is AROUND it (a side-panel toggle, a back arrow). A panel toggle
+  filed under `actions` reads as a peer of "create one of these". Under a title too long
+  for the row the TITLE gives way and wraps while `actions` keep their width — a wrapped
+  title is merely taller, a CTA pushed off the row is unreachable.
 - **`page_content`** — `PageContent` + `PAGE_SIZES`: the page's padded, width-capped content
   region — a centred column with optional `title`/`titleRight`/`description`, `header`/`footer`
   slots and `fullscreen`. **Reach for it before hand-rolling a screen shell**: a scroller, a

package/examples/tpl_record.tsx

@@ -2683,7 +2683,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
         </Section>
         </View>
 
-        {/* PHOTOS — the same collection, the other SURFACE.
+        {/* PHOTOS — a second SET, and therefore the other SURFACE.
 
             Files above is a row LIST because a shipping document is identified by
             its NAME: a PDF thumbnail is a grey page identical to every other grey
@@ -2693,6 +2693,17 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
             same verbs, different surface, decided by what the reader recognises.
             (AGENTS.md: documents get a LIST, images get a GRID.)
 
+            READ THIS BEFORE COPYING THE SHAPE. Two sections here does NOT mean
+            "sort one pile by mime type into a list and a grid". This record holds
+            two distinct SETS — the paperwork that arrived on it, and the hand-over
+            photos taken against it — which the reader asks different questions of.
+            A SINGLE pile picks ONE surface by its majority and keeps it: the odd
+            .docx among forty phone photos stays in the grid, where it renders a
+            `DocumentCard` printing its filename, and the odd photo among forty
+            PDFs stays in the list, where its row carries the full name and a press
+            opens the gallery. Splitting one set by type would give the reader two
+            places to look for the same thing.
+
             The ADD rides the heading row, right edge, exactly as it does on Files
             and Fees — a section's add sits in the same spot whether the section
             holds nought or forty. Note it is a plain `Button` + `pickFiles`, not

package/package.json

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

package/src/avatar_size.ts

@@ -28,6 +28,13 @@ export type AvatarSize = "sm" | "md" | "lg" | "xl";
  * 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.
+ *
+ * The same argument fixes the rung ABOVE it. An avatar that stands on its own in
+ * a band — an account menu next to a row of icon buttons — is not a child of a
+ * control, it IS one, so its number is `CONTROL_HEIGHT` (40), not a size picked
+ * for looking prominent. Both live rungs therefore quote `control_surface`; only
+ * `sm` (too small for two letters) and `xl` (a profile header, in no band at all)
+ * are free.
  */
 export const AVATAR_PX: Record<AvatarSize, number> = {
   /** Dense rows and inline chips — one initial, because two do not fit. */
@@ -35,8 +42,12 @@ export const AVATAR_PX: Record<AvatarSize, number> = {
   /** 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,
+  /** An avatar that IS a control rather than one sitting inside a control — the
+   *  account-menu trigger in a top bar, a prominent row's leading figure. Equals
+   *  `CONTROL_HEIGHT` (`control_surface`), so it lines up with the icon buttons
+   *  beside it. It was 48, which anchored to nothing: the bar's other controls
+   *  are 40, and a 48px circle among them reads as the one thing that got out. */
+  lg: 40,
   /** A profile's own header. */
   xl: 72,
 };
@@ -51,13 +62,17 @@ export const AVATAR_PX: Record<AvatarSize, number> = {
  *
  *   sm  12 on 24 = 50%
  *   md  12 on 28 = 43%
- *   lg  20 on 48 = 42%
+ *   lg  16 on 40 = 40%
  *   xl  32 on 72 = 44%
  *
- * 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.
+ * The two-letter rungs sit within 4 points of each other, so an avatar reads the
+ * same at every size rather than growing emptier as it grows — `lg` at 48 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.
+ *
+ * `lg` keeps `md` type now that the circle is 40, and the next rung up would be
+ * worse in the other direction: `lg` type is 20, which on 40 is 50% — the fattest
+ * of the two-letter rungs, and the same defect this table was written to fix.
  *
  * `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
@@ -68,7 +83,7 @@ export const AVATAR_PX: Record<AvatarSize, number> = {
 export const AVATAR_TEXT: Record<AvatarSize, TextSize> = {
   sm: "xs", // 12 on 24 — one letter, so it carries a larger share of the circle
   md: "xs", // 12 on 28
-  lg: "lg", // 20 on 48
+  lg: "md", // 16 on 40
   xl: "xxl", // 32 on 72
 };
 

package/src/page_header.tsx

@@ -5,29 +5,70 @@ import { ReactNode } from "react";
 interface PageHeaderProps {
   title: string;
   description?: string | null;
+  /** The nav row ABOVE the title — breadcrumbs, a back control, row-level status. */
   left?: ReactNode;
+  /** The nav row ABOVE the title, right-aligned. */
   right?: ReactNode;
+  /**
+   * A control that belongs to the TITLE, rendered immediately before it on the
+   * title row — a panel toggle, a back arrow into the page you came from.
+   *
+   * The distinction from `actions` is what the control acts ON, not where it
+   * looks best. `actions` are things you do to the page's CONTENT (create, sort,
+   * export) and collect at the right, where a scanning eye reaches them last;
+   * `leading` changes what is AROUND the content, and belongs against the title
+   * it frames. Putting a panel toggle in `actions` files it with the CTAs and
+   * makes the reader parse "open a side panel" as a peer of "create one of
+   * these".
+   */
+  leading?: ReactNode;
   /** Page-level actions (CTAs), rendered on the title row, right-aligned —
    *  distinct from `left`/`right`, which form a separate nav row above. */
   actions?: ReactNode;
 }
 
 export function PageHeader(props: PageHeaderProps) {
-  const { title, description, left, right, actions } = props;
+  const { title, description, left, right, leading, actions } = props;
 
   const hasNav = !!left || !!right;
 
-  const titleRow = actions ? (
-    <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 12 }}>
-      <Text size="xxl" weight="semibold">
-        {title}
-      </Text>
+  // ONE shape, whichever slots are filled. Branching the row on `leading` gave
+  // the title two different behaviours under a long string — shrinking when a
+  // panel toggle happened to be present and overflowing when it was not — which
+  // is a layout law decided by an unrelated prop.
+  //
+  // The title is what gives way; `actions` keep their width, because a CTA
+  // pushed off the row is unreachable while a wrapped title is merely taller.
+  // Both halves of the pair are required: a React Native `View`/`Text` does NOT
+  // shrink by default (`flexShrink: 0`, unlike the web), and `flexShrink` alone
+  // then floors the item at its MIN-CONTENT width — the longest word — so
+  // `minWidth: 0` is what lets it actually wrap. `DetailRow`'s spread value is
+  // the same pair for the same reason.
+  const titleRow = (
+    <View
+      style={{
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: 12,
+      }}
+    >
+      <View
+        style={{
+          flexDirection: "row",
+          alignItems: "center",
+          gap: 8,
+          flexShrink: 1,
+          minWidth: 0,
+        }}
+      >
+        {leading}
+        <Text size="xxl" weight="semibold" style={{ flexShrink: 1, minWidth: 0 }}>
+          {title}
+        </Text>
+      </View>
       {actions}
     </View>
-  ) : (
-    <Text size="xxl" weight="semibold">
-      {title}
-    </Text>
   );
 
   return (