@lotics/ui 37.1.0 → 38.0.0

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

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