@lotics/ui 38.1.0 → 40.0.0

package/AGENTS.md

@@ -30,7 +30,11 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 - **Responsive layout measures the CONTAINER, not the screen.** `useContainerSize()` reports the
   nearest `SizeBoundary`; wrap one around any region whose width stops tracking its parent's, and
   `Dialog`/`Drawer`/popover bodies already are boundaries so their contents get the panel
-  rather than the region they were opened from. `useScreenSize()` answers a question about the DEVICE — is there a keyboard
+  rather than the region they were opened from. The overlay's OWN presentation is not one of
+  these questions and is not yours to answer: `PopoverContent` reads the screen itself and takes
+  no prop, because it fills the viewport whatever box opened it — handing it a container width is
+  how a narrow column on a wide display opened a full-bleed phone sheet.
+  `useScreenSize()` answers a question about the DEVICE — is there a keyboard
   worth a shortcut hint, are these touch targets — and reaching for it to decide SPACE is how a
   panel a few hundred pixels wide lays its contents out for the whole display. (A component that
   needs a number rather than a bucket — how many columns fit — measures its own box; `Table`

package/MIGRATION.md

@@ -4,6 +4,60 @@ 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.
 
+## 40.0.0 — `PopoverContent` decides its own presentation; `small` is gone
+
+`PopoverContent` took a `small` prop meaning "render as a bottom sheet". It now asks
+`useScreenSize()` itself. **Delete the prop** — passing it is a type error.
+
+```diff
+- <PopoverContent small={small}>
++ <PopoverContent>
+```
+
+**Why the prop had to go rather than be defaulted.** A popover is an overlay: it fills the
+viewport regardless of which box it was opened from, so the only input is how wide that
+viewport is — and there is exactly one right answer per viewport. Every caller had to
+supply it by hand, and the two ways to get it wrong both shipped: one passed
+`useContainerSize()` — the width of the *column* holding the trigger — so a narrow chat
+column on a 1728px display opened a full-bleed modal sheet; another passed nothing and so
+never became a sheet on a real phone. Leaving the prop as an override would have kept both
+mistakes writable.
+
+**What changes for a NARROW-VIEWPORT host.** The rule is the viewport, not the device, so a
+surface that is a few hundred pixels wide on a desktop — a browser side panel, an embedded
+frame — now gets the bottom sheet where a popover that passed nothing was previously always
+anchored. If that is wrong for your surface, argue it as a change to the threshold or to what
+the rule reads, for every consumer at once; do not reach for a per-instance override.
+
+If you were computing `small` only to feed this prop, drop the hook call too. `useScreenSize`
+remains exported for its real uses — deciding whether a surface is a `Dialog` or a `Popover`
+at all, sizing touch targets, showing a keyboard shortcut.
+
+## 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
@@ -1245,8 +1247,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   control both dismisses this popover AND activates that control in one click; clicking outside,
   scrolling an ancestor, or Escape dismisses. Interactions inside a layer the popover opened
   from within (a nested popover, an `Alert` confirm, a full-screen Modal like the file preview)
-  never dismiss it — clicks, scrolls, and Escape belong to that layer until it closes. Only the
-  `small` (bottom-sheet) presentation is modal (scrim). `PopoverContent` already insets its
+  never dismiss it — clicks, scrolls, and Escape belong to that layer until it closes. In a
+  NARROW VIEWPORT (`small`, under 768) it presents instead as a modal bottom sheet (scrim, close
+  button, slide-up) — decided by `PopoverContent` itself off the screen size, with nothing to pass
+  and no way to answer it differently: an overlay fills the viewport whatever box it was opened
+  from, so the width of the column holding the trigger is never the question. The viewport, not
+  the device — a few-hundred-pixel side panel on a desktop gets the sheet too.
+  `PopoverContent` already insets its
   body 12px — put content directly in it, NEVER add your own padding `View` (that double-pads);
   title/actions go in `PopoverHeader` / `PopoverFooter`. **A fixed width is the `width` PROP,
   never `style`**: `style` reaches only the BODY, and the panel is `max-content`, so a width set
@@ -1784,8 +1791,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   width crosses a threshold — a height-only change (the mobile soft keyboard) and a resize
   inside one bucket both return the identical value. Correct only for
   questions about the device rather than the space: is there a keyboard to show a shortcut
-  for, are these touch-sized targets, and an overlay deciding whether it is a full-screen
-  sheet. Everything spatial wants `useContainerSize`.
+  for, are these touch-sized targets, and whether a surface is a `Dialog` on a phone and a
+  `Popover` otherwise. A popover's own anchored-vs-sheet presentation is NOT one of them —
+  `PopoverContent` reads this itself and takes no prop. Everything spatial wants
+  `useContainerSize`.
 - **`use_async_fn`** — `useAsyncFn`: wrap an async function into a manual-trigger mutation —
   `[run, {loading, data, error}]`, unmount-safe, the error lands in state AND rethrows; the
   pending-state engine for a submit/download/upload action.

package/package.json

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

package/src/popover.tsx

@@ -13,6 +13,7 @@ import { MIN_CONTROL_WIDTH } from "./control_surface";
 import { IconButton } from "./icon_button";
 import { Portal } from "./portal";
 import { SizeBoundary } from "./size_boundary";
+import { useScreenSize } from "./use_screen_size";
 import { Divider } from "./divider";
 import { useOverlayScope } from "./overlay_scope";
 import {
@@ -209,8 +210,6 @@ export interface PopoverContentProps {
    * both.
    */
   width?: number;
-  /** When true, renders as bottom sheet on small screens (close button, slide-up animation) */
-  small?: boolean;
   /** Accessible name for the bottom-sheet close button. Defaults to the locale's `overlay.close` ("Close" / "Đóng"). */
   closeLabel?: string;
   /** When true (default), the popover moves focus into its content on open and
@@ -230,10 +229,26 @@ export function PopoverContent(props: PopoverContentProps) {
     contentContainerStyle,
     disableBodyScroll,
     width,
-    small = false,
     closeLabel = locale.overlay.close,
     manageFocus = true,
   } = props;
+  // The VIEWPORT, never the container, and never a caller's opinion of either.
+  // A popover is an overlay: it fills the viewport regardless of the box it was
+  // opened from, so the only input to "anchored or bottom sheet" is how wide
+  // that viewport is — under `small` (<768) the sheet wins.
+  //
+  // This was a `small` prop and every caller answered it by hand. One answered
+  // with `useContainerSize()`, the width of whatever column held the trigger, so
+  // a narrow chat column on a desktop opened a full-bleed sheet; another passed
+  // nothing and never became a sheet on a real phone. Reading it here is the
+  // only way neither can be written again.
+  //
+  // Note this is the viewport and NOT "is this a phone": a browser side panel is
+  // a few hundred pixels of a desktop and gets the sheet too. That is the rule
+  // behaving as defined rather than a bug, but it is the reason a surface that
+  // wants a different presentation must change the RULE here, for everyone, and
+  // never re-introduce a per-caller override.
+  const { small } = useScreenSize();
   const { open, onOpenChange, triggerRef, side, align, offset, inheritTriggerWidth } =
     usePopoverContext();