@lotics/ui 14.2.0 → 14.3.0

package/examples/tpl_record.tsx

@@ -66,6 +66,8 @@ import { useSelection } from "@lotics/ui/use_selection";
 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 { 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";
@@ -92,9 +94,8 @@ type Part = UIMessagePart<UIDataTypes, UITools>;
 // · Comments        — the discussion thread. When people collaborate here.
 // · Tasks           — the working checklist. Multi-step records with owners.
 // · Documents       — the INTAKE desk: files that ARRIVE + the ONE "Use AI"
-//                     fork (shared with tpl_documents — change BOTH; the one
-//                     divergence: generation lives in the output sections
-//                     here, in the toolbar dialog there).
+//                     fork (the Agents "Document desk" pattern — this template
+//                     is its worked example).
 // · Customer        — the LINKED PARTY: another record referenced, never
 //                     edited here (the linked-record box + drawer).
 // · Fees            — the MONEY LEDGER: cost/charge lines, both directions.
@@ -429,11 +430,10 @@ const GUTTER = RAIL_W + RAIL_GAP;
 /** The reading column's ceiling. */
 const CONTENT_MAX = 720;
 
-// ── the DOCUMENT DESK — the Agents "Document desk" pattern (tpl_documents),
-// carried as the record's documents surface: files feed ONE "Use AI" entry
-// that forks into extract / cross-check / edit-with-AI. The two templates
-// share this desk — change it in BOTH (the one divergence: generation lives
-// in this page's output sections, in tpl_documents' toolbar dialog).
+// ── the DOCUMENT DESK — the Agents "Document desk" pattern, carried as the
+// record's documents surface: files feed ONE "Use AI" entry that forks into
+// extract / cross-check / edit-with-AI; generation lives in this page's
+// output sections (the desk itself is intake-only).
 type ScriptStep = { id: string; toolName: string; input?: unknown; output?: unknown };
 type Task = "extract" | "check";
 type Phase = "fork" | "running" | "review" | "done";
@@ -701,6 +701,7 @@ const DESTINATIONS: PickerOption<string, { country: string }>[] = [
 export function TplRecord() {
   const id = useRef(1);
   const nextId = (prefix: string) => `${prefix}_${(id.current += 1)}`;
+  const { small } = useScreenSize();
 
   // ── first paint = Skeleton MIRRORING the final layout, never a spinner.
   // The 700ms mock stands in for the record query a real app awaits.
@@ -835,8 +836,8 @@ export function TplRecord() {
   const taxId = customer?.taxId ?? "";
   const taxIdValid = TAX_ID_RE.test(taxId);
 
-  // ── the document desk (carried verbatim from tpl_documents — see the module
-  //    banner above; the record's files ARE the desk's register)
+  // ── the document desk (see the module banner above; the record's files ARE
+  //    the desk's register)
   const [files, setFiles] = useState<Doc[]>(DOCS);
   const sel = useSelection();
 
@@ -1885,8 +1886,7 @@ export function TplRecord() {
             </View>
             <View style={{ flex: 1 }} />
             {/* no Create here — GENERATION lives in the Document set section
-                below (this desk = intake); tpl_documents, whose page has no
-                output section, keeps the dialog flavor in this slot */}
+                below (this desk = intake) */}
             <Button
               title="Add files"
               color="secondary"
@@ -2719,7 +2719,7 @@ export function TplRecord() {
       </View>
     </ScrollView>
 
-    {/* ── the document desk's overlays (verbatim from tpl_documents) */}
+    {/* ── the document desk's overlays */}
     <FloatingActionBar count={sel.count} label={sel.count === 1 ? "file selected" : "files selected"} onClear={sel.clear}>
       <Button title="Remove" color="danger-secondary" icon="trash" onPress={removeSelected} />
       <Button title="Download" color="secondary" icon="download" onPress={() => { /* a real app zips or opens each selected file (openExternal) */ }} />
@@ -2734,6 +2734,16 @@ export function TplRecord() {
       <DialogHeader>
         <DialogHeaderTitle>{task === "extract" ? "Extract data" : task === "check" ? "Cross-check" : `Use AI · ${picked.length} ${picked.length === 1 ? "file" : "files"}`}</DialogHeaderTitle>
       </DialogHeader>
+      {phase === "running" ? (
+        // The streaming feed gets its OWN scroller: FollowScroll (the chat list's
+        // inverted mechanism) keeps the newest part in view as the run grows — a
+        // plain DialogScrollArea would let it stream below the fold. The swap back
+        // on the phase flip REMOUNTS the scroll area, so review opens at the TOP.
+        // Padding mirrors DialogScrollArea.
+        <FollowScroll contentContainerStyle={{ paddingBottom: 24, paddingHorizontal: small ? 16 : 24 }}>
+          <AgentRun parts={runItems} state={revealed >= script.length ? "done" : "streaming"} />
+        </FollowScroll>
+      ) : (
       <DialogScrollArea>
         {phase === "fork" ? (
           <View style={{ gap: 16 }}>
@@ -2776,8 +2786,6 @@ export function TplRecord() {
           </View>
         ) : null}
 
-        {phase === "running" ? <AgentRun parts={runItems} state={revealed >= script.length ? "done" : "streaming"} /> : null}
-
         {phase === "review" && task === "extract" ? (
           <View style={{ gap: 16 }}>
             <View style={{ gap: 8 }}>
@@ -2904,6 +2912,7 @@ export function TplRecord() {
           <CompletionState title={`${applyCount} ${applyCount === 1 ? "change" : "changes"} applied to ${code}`} summary="The files stay on the record — each updated field keeps its source document." />
         ) : null}
       </DialogScrollArea>
+      )}
       {phase === "fork" ? (
         <DialogFooter>
           {uploadFlow ? <Button title="Save files only" color="muted" onPress={() => { commitUpload(); closeAi(); }} /> : <Button title="Cancel" color="muted" onPress={closeAi} />}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/follow_scroll.tsx

@@ -1,5 +1,5 @@
-import { useRef, type ReactNode } from "react";
-import { ScrollView, StyleProp, ViewStyle, type NativeScrollEvent, type NativeSyntheticEvent } from "react-native";
+import { type ReactNode } from "react";
+import { FlatList, StyleProp, View, ViewStyle } from "react-native";
 
 export interface FollowScrollProps {
   children: ReactNode;
@@ -9,50 +9,45 @@ export interface FollowScrollProps {
   contentContainerStyle?: StyleProp<ViewStyle>;
 }
 
-// "At the bottom" tolerance: within this many px of the end still counts as
-// pinned, so sub-pixel scroll positions and streaming-growth rounding never
-// silently unpin the follow.
-const PIN_THRESHOLD = 40;
+const DATA = ["content"];
 
 /**
  * A scroll container that FOLLOWS its growing content — pinned to the bottom, it
  * keeps the newest content in view as children stream in (an `AgentRun` in a
- * dialog, a log feed). Scrolling up UNPINS it so the human can read history while
- * the content keeps growing; scrolling back to the bottom re-pins. Chat doesn't
- * need this (its message list is inverted, which follows by construction) — this
- * is for the plain top-down containers everywhere else: dialogs, drawers, panels.
+ * dialog, a log feed). Scrolling up releases the pin so the human can read
+ * history; scrolling back to the bottom re-pins.
+ *
+ * Implemented as a single-cell INVERTED list — the same mechanism as a chat
+ * message list — so the follow happens at LAYOUT level: the browser paints each
+ * growth already pinned (no scroll-after-paint flash, no scroll math). Short
+ * content still reads top-down (the content is end-justified in inverted
+ * coordinates); once it overflows, the newest edge stays in view natively. The
+ * inverted pattern's quirks (scrollbar thumb runs opposite, keyboard paging
+ * inverted) match the chat surface users already know.
  */
 export function FollowScroll(props: FollowScrollProps) {
   const { children, style, contentContainerStyle } = props;
-  const scrollRef = useRef<ScrollView>(null);
-  // Pinned state lives in a ref — it changes on every scroll tick and must never
-  // re-render the (streaming, already-busy) subtree.
-  const pinnedRef = useRef(true);
-
-  const followIfPinned = () => {
-    if (pinnedRef.current) scrollRef.current?.scrollToEnd({ animated: false });
-  };
-
-  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
-    const { contentOffset, contentSize, layoutMeasurement } = e.nativeEvent;
-    const distanceFromBottom = contentSize.height - contentOffset.y - layoutMeasurement.height;
-    pinnedRef.current = distanceFromBottom < PIN_THRESHOLD;
-  };
-
   return (
-    <ScrollView
-      ref={scrollRef}
+    <FlatList
+      inverted
+      data={DATA}
+      keyExtractor={(k) => k}
+      // The consumer's content styles live on an inner wrapper INSIDE the cell —
+      // the cell renders upright (double flip), so authored padding keeps its
+      // visual orientation; the flipped outer container must not carry it.
+      renderItem={() => <View style={contentContainerStyle}>{children}</View>}
+      // Children identity changes every stream tick; without extraData the list
+      // would keep rendering the mounted cell's stale content.
+      extraData={children}
       style={style}
-      contentContainerStyle={contentContainerStyle}
-      // Content grew (a new part streamed in) or the frame resized (dialog
-      // re-measured) — both move the bottom edge, so both re-follow when pinned.
-      onContentSizeChange={followIfPinned}
-      onLayout={followIfPinned}
-      onScroll={onScroll}
-      scrollEventThrottle={16}
+      // flexGrow + flex-end top-aligns SHORT content (flex-end is the visual TOP
+      // in inverted coordinates), so a feed reads top-down until it overflows.
+      contentContainerStyle={followStyles.grow}
       nestedScrollEnabled
-    >
-      {children}
-    </ScrollView>
+    />
   );
 }
+
+const followStyles = {
+  grow: { flexGrow: 1, justifyContent: "flex-end" } as const,
+};