@lotics/ui 39.0.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,35 @@ 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

package/docs/catalog.md

@@ -1247,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
@@ -1786,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": "39.0.0",
+  "version": "40.0.0",
   "type": "module",
   "exports": {
     "./vite": {

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();