@lotics/ui 38.1.0 → 39.0.0

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

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

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