@lotics/ui 38.0.0 → 39.0.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,31 @@ 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.
 
+## 39.0.0 — `PageHeader.leading` is `trailing`, and it renders AFTER the title
+
+38.0.0 shipped `leading`, a slot before the title. It is now **`trailing`**, in the same
+place in the props but rendered on the other side of the title text.
+
+```tsx
+// 38.0.0
+<PageHeader title="Members" leading={<IconButton …/>} actions={…} />
+// 39.0.0
+<PageHeader title="Members" trailing={<IconButton …/>} actions={…} />
+```
+
+**Why the side changed.** The title is the page's first word. A control ahead of it makes
+the eye parse chrome before it learns where it is, and on a page whose heading is the only
+thing telling you which section you are in, that is the wrong order. After the title the
+control still reads as part of the heading — which is the whole point of not putting it
+with `actions` — without standing in front of it.
+
+**Why a rename rather than a second slot.** A slot with no consumer is surface that has to
+be understood by everyone who reads the component and used by no one; the kit's cull rule
+says cut it. One slot for "a control belonging to the title" is the whole contract.
+
+The layout law is unchanged and now covers both: the TITLE gives way and wraps, while
+`trailing` and `actions` keep their width.
+
 ## 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`

package/docs/catalog.md

@@ -286,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`),
@@ -521,13 +536,15 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`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) and `leading` puts a control immediately BEFORE the title;
-  `left`/`right` form a separate nav row above. Split `leading` from `actions` by what the
+  the title row (right-aligned) and `trailing` puts a control immediately AFTER the title;
+  `left`/`right` form a separate nav row above. Split `trailing` 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.
+  `trailing` changes what is AROUND it (a side-panel toggle, a view switch). A panel toggle
+  filed under `actions` reads as a peer of "create one of these". It sits AFTER the title
+  because the title is the page's first word and nothing should come between the reader
+  and it. Under a title too long for the row the TITLE gives way and wraps while `trailing`
+  and `actions` keep their width — a wrapped title is merely taller, a control squeezed
+  below its own icon is broken.
 - **`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": "38.0.0",
+  "version": "39.0.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/page_header.tsx

@@ -10,32 +10,36 @@ interface PageHeaderProps {
   /** 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.
+   * A control that belongs to the TITLE, rendered immediately AFTER it on the
+   * title row — a panel toggle, a view switch, anything that reframes the page
+   * rather than acting on it.
    *
    * 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".
+   * export) and collect at the far right, where a scanning eye reaches them
+   * last; `trailing` changes what is AROUND the content and stays with the title
+   * it qualifies, so it is read as part of the heading rather than as one more
+   * thing you can do to your list.
+   *
+   * It sits AFTER the title, not before, because the title is the page's first
+   * word and nothing should come between the reader and it — a control ahead of
+   * the heading makes the eye parse chrome before it learns where it is.
    */
-  leading?: ReactNode;
+  trailing?: 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, leading, actions } = props;
+  const { title, description, left, right, trailing, actions } = props;
 
   const hasNav = !!left || !!right;
 
-  // 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.
+  // ONE shape, whichever slots are filled. Branching the row on the title's own
+  // slot 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.
@@ -62,10 +66,12 @@ export function PageHeader(props: PageHeaderProps) {
           minWidth: 0,
         }}
       >
-        {leading}
         <Text size="xxl" weight="semibold" style={{ flexShrink: 1, minWidth: 0 }}>
           {title}
         </Text>
+        {/* Never shrinks: the title is what gives way, and a control squeezed
+            below its own icon is not a smaller control, it is a broken one. */}
+        {trailing !== undefined && <View style={{ flexShrink: 0 }}>{trailing}</View>}
       </View>
       {actions}
     </View>