@lotics/ui 27.15.2 → 27.16.0

package/AGENTS.md

@@ -27,6 +27,14 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   license to hand-roll.
 - **One canonical component per data role** (member → `MemberChip`, select → `OptionBadge`,
   files → `FilePreview` family, …) — the catalog's Reach-by-role outranks neighboring code.
+- **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
+  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`
+  does exactly that.) → [catalog.md §Utility hooks](./docs/catalog.md).
 - **A section's ADD rides its heading row, right edge** — Add files, Add fee, New line: a
   `primary` `Button` beside `SectionHeadingTitle`, rendered empty or full. Under the rows it
   extends, the verb MOVES with the row count and vanishes off-screen on a long list; a heading is

package/docs/catalog.md

@@ -615,9 +615,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`dots_indicator`** — `DotsIndicator`: three looping bouncing dots (`size`/`color`); the
   indeterminate "working/typing" pulse `Loading` composes; use bare beside a caption while
   an agent thinks. Determinate work → `ProgressBar`.
-- **`animation_fade_in`** — `AnimationFadeIn`: the mount transition — children fade (+
-  optional `translateY` rise) into place on first render, once; the entrance polish
-  Accordion/Timeline/Stepper/AgentRun rows use.
+- **`animation_fade_in`** — `AnimationFadeIn`: the mount transition — children fade into
+  place on first render, once; the entrance polish Accordion/Timeline/Stepper/AgentRun
+  rows use. `translateY` adds the rise that reads as settling into place; `translateX`
+  the horizontal travel of a panel arriving from an edge (negative = from the left).
 
 ### Pickers & selection controls
 
@@ -1604,10 +1605,25 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 ### Utility hooks & plumbing
 
-- **`use_screen_size`** — `useScreenSize` / `getScreenSize` / `calculateScreenSize`:
-  `{ small, medium, large }` width-breakpoint booleans (small < 768 ≤ medium < 1728 ≤
-  large); tracks width changes only, so the mobile soft keyboard (a height-only change)
-  never re-renders.
+- **`size_boundary`** — `SizeBoundary` / `useContainerSize`: **reach for this, not
+  `useScreenSize`, for anything rendered in flow.** `useContainerSize()` answers "how much
+  room do *I* have" with the same `{ small, medium, large }` booleans, measured from the
+  nearest enclosing `SizeBoundary` — so a table in a 600px panel lays itself out like a
+  phone, because for its purposes it is one. Wrap a `SizeBoundary` around any region whose
+  width stops tracking the window (beside a dockable panel, inside a resizable rail, around
+  an embedded surface); `Dialog`, `Drawer` and a popover's body already are boundaries, so their
+  contents get the panel's width rather than the region they were opened from. With no boundary in the tree the
+  window is the container, which is the right answer for an app inside its own frame.
+- **`container_size`** — `deriveSizeBuckets` / `ContainerSizeProvider`: the thresholds and
+  the react-native-free core `SizeBoundary` feeds a measured width into. Provide a width
+  directly when you already have one and don't want a measuring wrapper.
+- **`use_screen_size`** — `useScreenSize` / `getScreenSize` / `calculateScreenSize`: the
+  **window**, same buckets (small < 768 ≤ medium < 1728 ≤ large). Re-renders only when the
+  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`.
 - **`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/examples/tpl_record.tsx

@@ -69,7 +69,7 @@ import { FloatingActionBar } from "@lotics/ui/floating_action_bar";
 import { CardSelectItem } from "@lotics/ui/card_select_item";
 import { AgentRun } from "@lotics/ui/agent_run";
 import { FollowScroll } from "@lotics/ui/follow_scroll";
-import { useScreenSize } from "@lotics/ui/use_screen_size";
+import { useContainerSize } from "@lotics/ui/size_boundary";
 import { type SourceRef } from "@lotics/ui/sources";
 import { ChangeValueInput, Change, ChangeField, ChangeFields, ChangeReasoning, ChangeRecord, ChangeReview, ChangeReviewActions, ChangeReviewHeader, type ChangeStatus } from "@lotics/ui/change_review";
 import { CompletionState } from "@lotics/ui/completion_state";
@@ -895,7 +895,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
   const isDrawer = chrome === "drawer";
   const id = useRef(1);
   const nextId = (prefix: string) => `${prefix}_${(id.current += 1)}`;
-  const { small } = useScreenSize();
+  const { small } = useContainerSize();
 
   // ── first paint = Skeleton MIRRORING the final layout, never a spinner.
   // The 700ms mock stands in for the record query a real app awaits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "27.15.2",
+  "version": "27.16.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -158,6 +158,8 @@
     "./fonts.css": "./src/fonts.css",
     "./keyboard": "./src/keyboard.ts",
     "./use_screen_size": "./src/use_screen_size.ts",
+    "./container_size": "./src/container_size.tsx",
+    "./size_boundary": "./src/size_boundary.tsx",
     "./use_auto_grow_height": "./src/use_auto_grow_height.ts",
     "./use_focus_ring": "./src/use_focus_ring.ts",
     "./use_gated_press": "./src/use_gated_press.ts",

package/src/agent_run_pane.tsx

@@ -5,7 +5,7 @@ import type { AgentUIPart } from "./agent_transform";
 import { ClarifyWizard, ClarifyWizardActions, ClarifyWizardScope, type ClarifyWizardAnswer } from "./clarify_wizard";
 import { DialogScrollArea } from "./dialog";
 import { FollowScroll } from "./follow_scroll";
-import { useScreenSize } from "@lotics/ui/use_screen_size";
+import { useContainerSize } from "@lotics/ui/size_boundary";
 
 /**
  * What this pair needs from a run — structurally the shape `useAgentRun()`
@@ -64,7 +64,7 @@ export interface AgentRunPaneProps {
  */
 export function AgentRunPane(props: AgentRunPaneProps) {
   const { run, labelForCall, renderToolOutput, onCancel } = props;
-  const { small } = useScreenSize();
+  const { small } = useContainerSize();
   const pending = run.pendingChoice;
 
   // Mapped once per question set, not per render: the wizard keys its per-step

package/src/animation_fade_in.tsx

@@ -7,10 +7,14 @@ interface AnimationFadeInProps {
   /** Rise this many px while fading in — the "appearing into place" gesture.
    *  Default 0 (fade only). */
   translateY?: number;
+  /** Travel this many px horizontally while fading in — negative enters from the
+   *  left, positive from the right. The gesture for a panel arriving from an
+   *  edge rather than settling into place. Default 0. */
+  translateX?: number;
 }
 
 export function AnimationFadeIn(props: AnimationFadeInProps) {
-  const { children, style, translateY = 0 } = props;
+  const { children, style, translateY = 0, translateX = 0 } = props;
   const progress = useRef(new Animated.Value(0)).current;
 
   useEffect(() => {
@@ -21,9 +25,18 @@ export function AnimationFadeIn(props: AnimationFadeInProps) {
     }).start();
   }, [progress]);
 
-  const transform = translateY
-    ? [{ translateY: progress.interpolate({ inputRange: [0, 1], outputRange: [translateY, 0] }) }]
-    : undefined;
+  const offset = (from: number) =>
+    progress.interpolate({ inputRange: [0, 1], outputRange: [from, 0] });
+  const transform = [
+    ...(translateX ? [{ translateX: offset(translateX) }] : []),
+    ...(translateY ? [{ translateY: offset(translateY) }] : []),
+  ];
 
-  return <Animated.View style={[{ opacity: progress, transform }, style]}>{children}</Animated.View>;
+  return (
+    <Animated.View
+      style={[{ opacity: progress, transform: transform.length ? transform : undefined }, style]}
+    >
+      {children}
+    </Animated.View>
+  );
 }

package/src/container_size.tsx

@@ -0,0 +1,63 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+
+/**
+ * The one set of width thresholds in the kit. `use_screen_size` measures the
+ * window against them and a `SizeBoundary` measures a box, so a 400px panel on a
+ * 4K display reads exactly like a phone — which is the point.
+ */
+const breakpoints = {
+  /** Below this, a box is phone-shaped: stack, and prefer sheets to popovers. */
+  small: 768,
+  /** At or above this, a box has room to spend on density. */
+  large: 1728,
+};
+
+export interface SizeBuckets {
+  /** For most mobile phones — or any box that narrow. */
+  small: boolean;
+  /** iPad Mini through a 16" MacBook Pro — or any box that wide. */
+  medium: boolean;
+  /** Most external monitors — or any box that wide. */
+  large: boolean;
+}
+
+export function deriveSizeBuckets(width: number): SizeBuckets {
+  return {
+    small: width < breakpoints.small,
+    medium: width >= breakpoints.small && width < breakpoints.large,
+    large: width >= breakpoints.large,
+  };
+}
+
+/** Null means no enclosing boundary — the window is the container. */
+export const ContainerSizeContext = createContext<SizeBuckets | null>(null);
+
+/**
+ * Publishes a measured width to descendants as buckets.
+ *
+ * The value is memoized on the buckets, not the width, so a resize that does not
+ * cross a threshold produces no new value and re-renders no consumer. That
+ * matters because a subtree under one boundary can hold dozens of readers, and a
+ * drag on a resizable panel emits a measurement per frame.
+ *
+ * Kept free of `react-native` imports so it is unit-testable; the measuring
+ * wrapper that feeds it a width lives in `size_boundary`.
+ */
+export function ContainerSizeProvider(props: { width: number; children: ReactNode }) {
+  const { width, children } = props;
+  // The two booleans, not the width, are the dependencies — that is what keeps
+  // the published value identical across a resize inside one bucket.
+  const small = width < breakpoints.small;
+  const large = width >= breakpoints.large;
+  const value = useMemo<SizeBuckets>(
+    () => ({ small, medium: !small && !large, large }),
+    [small, large],
+  );
+
+  return <ContainerSizeContext.Provider value={value}>{children}</ContainerSizeContext.Provider>;
+}
+
+/** The nearest boundary's buckets, or null when nothing encloses this component. */
+export function useEnclosingContainerSize(): SizeBuckets | null {
+  return useContext(ContainerSizeContext);
+}

package/src/date_filter.tsx

@@ -6,7 +6,7 @@ import { CONTROL_RADIUS } from "./control_surface";
 import { MenuButton } from "./menu_button";
 import { Calendar, CalendarRangeValue, CalendarRef } from "./date_calendar";
 import { TimePicker } from "./time_picker";
-import { useScreenSize } from "./use_screen_size";
+import { useContainerSize } from "./size_boundary";
 import { SegmentLabels } from "./date_segments";
 import { PresetId, PRESET_IDS, getPresetValue } from "./date_filter_presets";
 import { formatDate } from "./format_date";
@@ -134,7 +134,7 @@ export function DateFilter(props: DateFilterProps) {
     () => ({ ...loc, ...props.labels }),
     [loc, props.labels],
   );
-  const screenSize = useScreenSize();
+  const screenSize = useContainerSize();
   const calendarRef = useRef<CalendarRef>(null);
 
   // A half-picked range is held HERE and never emitted — the same rule

package/src/dialog.tsx

@@ -1,6 +1,7 @@
 import React, { createContext, useCallback, useContext, useMemo, useState } from "react";
 import { Animated, Modal, StyleSheet, View, ScrollView } from "react-native";
 import { useScreenSize } from "@lotics/ui/use_screen_size";
+import { SizeBoundary } from "@lotics/ui/size_boundary";
 import { PortalHost } from "@lotics/ui/portal";
 import { colors } from "@lotics/ui/colors";
 import { IconButton } from "@lotics/ui/icon_button";
@@ -167,7 +168,7 @@ export function Dialog(props: DialogProps) {
                       <View style={[styles.closeButtonContainer, { paddingHorizontal: screenSize.small ? 16 : 24 }]}>
                         <IconButton icon="x" size="lg" accessibilityLabel={locale.overlay.close} onPress={handleClose} />
                       </View>
-                      <View style={styles.container}>{children}</View>
+                      <SizeBoundary style={styles.container}>{children}</SizeBoundary>
                     </View>
                   </PortalHost>
                 </Animated.View>

package/src/drawer.tsx

@@ -1,6 +1,7 @@
 import { ReactNode, useEffect } from "react";
 import { Modal, Pressable, StyleSheet, View } from "react-native";
 import { useScreenSize } from "@lotics/ui/use_screen_size";
+import { SizeBoundary } from "@lotics/ui/size_boundary";
 import { PortalHost } from "@lotics/ui/portal";
 import { colors } from "@lotics/ui/colors";
 import { IconButton } from "@lotics/ui/icon_button";
@@ -123,9 +124,9 @@ export function Drawer(props: DrawerProps) {
               ) : null}
               <IconButton icon="x" size="lg" accessibilityLabel={loc.close} onPress={handleClose} />
             </View>
-            <View testID={testID} style={styles.body}>
+            <SizeBoundary testID={testID} style={styles.body}>
               {children}
-            </View>
+            </SizeBoundary>
           </PortalHost>
         </View>
       </View>

package/src/page_content.tsx

@@ -3,7 +3,7 @@ import { Text } from "@lotics/ui/text";
 import { colors } from "@lotics/ui/colors";
 import { Spacer } from "@lotics/ui/spacer";
 import { ReactNode } from "react";
-import { useScreenSize } from "@lotics/ui/use_screen_size";
+import { useContainerSize } from "@lotics/ui/size_boundary";
 
 interface PageContentProps {
   children: ReactNode;
@@ -23,7 +23,7 @@ interface PageContentProps {
  */
 export function PageContent(props: PageContentProps) {
   const { children, title, titleRight, description, header, footer, size, fullscreen } = props;
-  const screenSize = useScreenSize();
+  const screenSize = useContainerSize();
 
   const maxWidth = !screenSize.small && size ? PAGE_SIZES[size] : undefined;
 

package/src/popover.tsx

@@ -12,6 +12,7 @@ import { colors } from "./colors";
 import { MIN_CONTROL_WIDTH } from "./control_surface";
 import { IconButton } from "./icon_button";
 import { Portal } from "./portal";
+import { SizeBoundary } from "./size_boundary";
 import { Divider } from "./divider";
 import { useOverlayScope } from "./overlay_scope";
 import {
@@ -714,7 +715,7 @@ export function PopoverContent(props: PopoverContentProps) {
         )}
         {header}
         {disableBodyScroll ? (
-          <View style={style}>{bodyChildren}</View>
+          <SizeBoundary style={style}>{bodyChildren}</SizeBoundary>
         ) : (
           // FULL-BLEED HORIZONTALLY, then re-inset by the same 12. The panel
           // pads all four sides, so a scroller sitting inside that padding
@@ -731,7 +732,10 @@ export function PopoverContent(props: PopoverContentProps) {
             style={[SCROLL_BODY, style]}
             contentContainerStyle={[SCROLL_BODY_CONTENT, contentContainerStyle]}
           >
-            {bodyChildren}
+            {/* A popover is a box of its own — a few hundred px — so its contents
+                size to the panel rather than to whatever region it was opened
+                from. Both body paths get it; one of them is not a boundary. */}
+            <SizeBoundary>{bodyChildren}</SizeBoundary>
           </ScrollView>
         )}
         {footer}

package/src/size_boundary.tsx

@@ -0,0 +1,65 @@
+import { useCallback, useState, type ReactNode } from "react";
+import { View, type LayoutChangeEvent, type StyleProp, type ViewStyle } from "react-native";
+import { ContainerSizeProvider, useEnclosingContainerSize, type SizeBuckets } from "./container_size";
+import { useScreenSize } from "./use_screen_size";
+
+/**
+ * Declares the box that descendants should size themselves against.
+ *
+ * Mount one wherever a region's width stops tracking the window — beside a
+ * dockable panel, inside a resizable rail, around an embedded surface — and
+ * never per component. A component under it asks `useContainerSize()` and gets
+ * the box it is actually in, so a table in a 600px column stops laying itself
+ * out as though it had the whole 1600px display.
+ *
+ * Until the first `onLayout` it reports the WINDOW's bucket, so the opening paint
+ * matches what the same tree rendered before any boundary existed. Seeding at
+ * zero instead would start every mount at "phone" and flash the stacked layout on
+ * the way out of it.
+ */
+export function SizeBoundary(props: {
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}) {
+  const { children, style, testID } = props;
+  const screen = useScreenSize();
+  const [width, setWidth] = useState<number | null>(null);
+
+  const handleLayout = useCallback((event: LayoutChangeEvent) => {
+    setWidth(event.nativeEvent.layout.width);
+  }, []);
+
+  return (
+    <View onLayout={handleLayout} style={style} testID={testID}>
+      <ContainerSizeProvider width={width ?? screenSeedWidth(screen)}>
+        {children}
+      </ContainerSizeProvider>
+    </View>
+  );
+}
+
+/** A width that lands in the same bucket the window is in, for the first frame. */
+function screenSeedWidth(screen: SizeBuckets): number {
+  if (screen.small) return 0;
+  if (screen.large) return 1728;
+  return 768;
+}
+
+/**
+ * How much room this component actually has: the nearest `SizeBoundary`, or the
+ * window when nothing encloses it.
+ *
+ * Reach for this over `useScreenSize` for anything rendered *in flow*. The window
+ * is the right question only for chrome that spans it (is this a phone?) and for
+ * overlays, which fill the viewport regardless of what they were opened from.
+ *
+ * Falling back to the window is not a stand-in for a missing value — with no
+ * boundary in the tree the window IS the container, which is also why an app
+ * embedded in its own frame gets the right answer without mounting anything.
+ */
+export function useContainerSize(): SizeBuckets {
+  const enclosing = useEnclosingContainerSize();
+  const screen = useScreenSize();
+  return enclosing ?? screen;
+}

package/src/text_utils.ts

@@ -132,7 +132,10 @@ export function getInputTextStyle(): TextStyle {
  * Returns the input line height for layout calculations.
  * Use this when you need to calculate heights for multiline inputs.
  *
- * @param isSmallScreen - Whether the screen is small (mobile). Get this from useScreenSize().small
+ * @param isSmallScreen - Whether the WINDOW is small (a phone). Input metrics are
+ * a touch-target question, so this comes from `useScreenSize().small` — never
+ * from the enclosing container, or a text field in a narrow desktop panel would
+ * get phone line heights.
  */
 /** {@link multilineInputHeight} at this platform's input line height. */
 export function getMultilineInputHeight(numberOfLines: number, isSmallScreen: boolean): number {

package/src/use_screen_size.ts

@@ -1,13 +1,6 @@
 import { useEffect, useState } from "react";
 import { Dimensions } from "react-native";
-
-const breakpoints = {
-  // small (mobile)
-  small: 768,
-  // medium (tablet and laptop)
-  large: 1728,
-  // large (external monitor)
-};
+import { deriveSizeBuckets } from "./container_size";
 
 export function useScreenSize() {
   // NOTE: DO NOT USE `useWindowDimensions` from `react-native`. On mobile browsers, when the soft keyboard appears, the window.innerHeight or Dimensions can change.
@@ -28,7 +21,14 @@ export function useScreenSize() {
       // This prevents re-renders when keyboards appear/disappear
       if (currentWidth !== lastKnownWidth) {
         lastKnownWidth = currentWidth; // Update the tracked width
-        setSize(calculateScreenSize(screen));
+        // ...and only when the width crosses a THRESHOLD. A new object per pixel
+        // re-renders every consumer through a whole drag for a value that did not
+        // change, and `useContainerSize` calls this on every one of its consumers
+        // to cover the no-boundary case — so the waste multiplies.
+        setSize((prev) => {
+          const next = calculateScreenSize(screen);
+          return next.small === prev.small && next.large === prev.large ? prev : next;
+        });
       }
     });
 
@@ -41,19 +41,10 @@ export function useScreenSize() {
   return size;
 }
 
+/** The window's buckets. `SizeBoundary` measures a box against the same
+ *  thresholds — they are defined once, in `container_size`. */
 export function calculateScreenSize(dimensions: { width: number }) {
-  const small = dimensions.width < breakpoints.small;
-  const medium = dimensions.width >= breakpoints.small && dimensions.width < breakpoints.large;
-  const large = dimensions.width >= breakpoints.large;
-
-  return {
-    /** For most mobile phones */
-    small,
-    /** For tablet and laptop displays ranging from iPad Mini to 16' MacBook Pro */
-    medium,
-    /** For most external monitors */
-    large,
-  };
+  return deriveSizeBuckets(dimensions.width);
 }
 
 export function getScreenSize() {