@multiplatform.one/components 6.6.0 → 7.0.0

package/src/layouts/timeline.tsx

@@ -13,14 +13,17 @@ import {
 import { useDirection } from "../hooks/useDirection";
 import {
   MIN_PRESS_TARGET,
+  ensureFocusVisibleRing,
   formatAbsoluteDateTime,
   formatRelativeTimestamp,
+  getGroupPosition,
   pressTargetHitSlop,
   pressTargetStyle,
+  stackRadiusProps,
   useResolvedKnobs,
 } from "@multiplatform.one/theme";
 import React, { useCallback, useMemo, useState } from "react";
-import { useTranslation } from "react-i18next";
+import { useTranslation } from "../shared/i18n";
 import {
   Button,
   H2,
@@ -287,6 +290,80 @@ export function threadEntries(entries: TimelineEntry[]): TimelineThread[] {
   return threads;
 }
 
+/** Flat feed walk: roots, then one-level replies, then an open reply composer. */
+type TimelineFeedItem =
+  | { key: string; kind: "entry"; entry: TimelineEntry; rootId: string; isReply: boolean }
+  | { key: string; kind: "reply-composer"; parent: TimelineEntry; rootId: string };
+
+function flattenFeedItems(
+  threads: TimelineThread[],
+  entries: TimelineEntry[],
+  replyTarget: { rootId: string; parentId: string } | null,
+): TimelineFeedItem[] {
+  const items: TimelineFeedItem[] = [];
+  for (const thread of threads) {
+    items.push({
+      key: thread.entry.id,
+      kind: "entry",
+      entry: thread.entry,
+      rootId: thread.entry.id,
+      isReply: false,
+    });
+    for (const reply of thread.replies) {
+      items.push({
+        key: reply.id,
+        kind: "entry",
+        entry: reply,
+        rootId: thread.entry.id,
+        isReply: true,
+      });
+    }
+    if (replyTarget && replyTarget.rootId === thread.entry.id) {
+      items.push({
+        key: `reply-composer-${thread.entry.id}`,
+        kind: "reply-composer",
+        parent: entries.find((e) => e.id === replyTarget.parentId) ?? thread.entry,
+        rootId: thread.entry.id,
+      });
+    }
+  }
+  return items;
+}
+
+/**
+ * GitHub/Primer + Frappe Desk spine: a flat 1px scheme-aware connector through
+ * the avatar/badge column. First/last items clip the line to the node center
+ * so the rail does not run off the stacked group (Primer `clipSidebar`).
+ */
+function TimelineSpine({
+  show,
+  clipStart,
+  clipEnd,
+  columnPx,
+  insetStart,
+}: {
+  show: boolean;
+  clipStart: boolean;
+  clipEnd: boolean;
+  columnPx: number;
+  insetStart: number;
+}) {
+  if (!show) return null;
+  const nodeCenter = insetStart + columnPx / 2;
+  return (
+    <YStack
+      position="absolute"
+      width={1}
+      top={clipStart ? nodeCenter : 0}
+      bottom={clipEnd ? nodeCenter : 0}
+      backgroundColor={componentColors.divider}
+      pointerEvents="none"
+      zIndex={0}
+      {...(isWeb ? { insetInlineStart: nodeCenter } : { start: nodeCenter })}
+    />
+  );
+}
+
 function getEntryActionLabel(
   entry: TimelineEntry,
   labels: { madeChanges: string; addedAttachment: string; assigned: string },
@@ -337,11 +414,13 @@ function TimelineSkeleton({
 // ---------------------------------------------------------------------------
 
 /**
- * Timeline: a mixed activity feed in the GitHub/Linear mold. Comment entries
- * render as conversation (avatar, bold display name, relative time, body,
- * Reply, one-level threaded replies); system events (version/attachment/
- * assignment/info) render as compact muted single-line rows. An inline
- * composer sits at the top of the feed.
+ * Timeline: a mixed activity feed in the GitHub/Frappe Desk mold. Comment
+ * entries render as conversation cards (avatar on a spine, display name,
+ * relative time, body, Reply, one-level threaded replies); system events
+ * (version/attachment/assignment/info) render as compact muted rows on the
+ * same spine. Feed rows are ONE stacked group (LC-72): outer corners only,
+ * hairlines between items, hover/press inherit that geometry. An inline
+ * composer sits at the top of the feed (Desk communications).
  * Fully data-agnostic -- accepts entries via props and emits callbacks.
  */
 export function Timeline({
@@ -370,7 +449,7 @@ export function Timeline({
   ...stackProps
 }: TimelineProps) {
   const { t } = useTranslation();
-  const { knobProps } = useResolvedKnobs();
+  const { knobProps, control } = useResolvedKnobs();
   const LabelTag = TIMELINE_HEADING_TAGS[headingLevel];
   // Reply arrow bends back toward the quoted message — direction-of-travel,
   // so the glyph pair swaps under RTL (Axiom 15 / useDirection pattern).
@@ -406,6 +485,10 @@ export function Timeline({
   const showSkeleton = !hasError && isLoading && entries.length === 0;
 
   const threads = useMemo(() => threadEntries(entries), [entries]);
+  const feedItems = useMemo(
+    () => flattenFeedItems(threads, entries, replyTarget),
+    [threads, entries, replyTarget],
+  );
 
   const submitComment = useCallback(
     (content: string, parentId?: string) => {
@@ -470,6 +553,9 @@ export function Timeline({
   const systemFontSize = compact ? "$1" : "$2";
   const avatarSize = compact ? "$1.5" : sz === "$5" ? "$3" : "$2";
   const replyAvatarSize = compact ? "$1" : "$1.5";
+  // Twin of the live avatar/badge column — spine centers on this well.
+  const columnPx = compact ? 20 : sz === "$5" ? 34 : 24;
+  const rowPad = compact ? 8 : sz === "$5" ? 16 : 12;
 
   const emptyIconSize = compact
     ? sz === "$3"
@@ -707,7 +793,7 @@ export function Timeline({
       ),
     });
 
-  /** Conversation entry: avatar + bold name + relative time + body + Reply. */
+  /** Conversation entry: avatar on the spine + GitHub/Desk comment card. */
   const renderCommentEntry = (entry: TimelineEntry, rootId: string, isReply: boolean) => {
     const displayName = getEntryDisplayName(entry);
     return (
@@ -716,12 +802,24 @@ export function Timeline({
         aria-label={`${displayName}, ${formatVisibleTimestamp(entry)}`}
         gap={compact ? "$2" : "$3"}
         alignItems="flex-start"
-        borderRadius={radiusToken}
-        onPress={onEntryClick ? () => onEntryClick(entry) : undefined}
-        cursor={onEntryClick ? "pointer" : "default"}
       >
-        {renderAvatar(entry, isReply ? replyAvatarSize : avatarSize)}
-        <YStack flex={1} gap="$1">
+        <YStack
+          width={columnPx}
+          minHeight={columnPx}
+          alignItems="center"
+          justifyContent="flex-start"
+          zIndex={1}
+        >
+          {renderAvatar(entry, isReply ? replyAvatarSize : avatarSize)}
+        </YStack>
+        <YStack
+          flex={1}
+          minWidth={0}
+          gap="$1"
+          backgroundColor={componentColors.surface.background}
+          {...knobProps.borderRadius}
+          padding={compact ? "$2" : "$3"}
+        >
           <XStack gap="$2" alignItems="center" flexWrap="wrap">
             <Text fontSize={nameFontSize} fontWeight="600" color={componentColors.text.primary}>
               {displayName}
@@ -743,7 +841,12 @@ export function Timeline({
               {/* DG-LAY-04 / D-02 press-floor: the chromeless pill paints at
                   the $1/$2 token (20/28px) but the press box is floored at 44
                   via the house pressTarget* channel (grown transparent box +
-                  negative outset + hitSlop) — layout height stays token-sized. */}
+                  negative outset + hitSlop) — layout height stays token-sized.
+                  LC-54 amendment (2026-08-13): the grown box NEVER paints —
+                  the Button's default hover/press fills would spread across
+                  the whole 44px floor and cover the comment text above via
+                  the negative outset, so the consumer eject pins them to
+                  transparent and feedback rides subtree opacity instead. */}
               <Button
                 chromeless
                 size={compact ? "$1" : "$2"}
@@ -752,6 +855,8 @@ export function Timeline({
                 hitSlop={pressTargetHitSlop(compact ? 20 : 28)}
                 borderRadius={radiusToken}
                 opacity={0.8}
+                hoverStyle={{ backgroundColor: "transparent", opacity: 1 }}
+                pressStyle={{ backgroundColor: "transparent", opacity: 0.9 }}
                 icon={<ReplyIcon size={compact ? 10 : 12} />}
                 aria-label={`${replyLabel} ${displayName}`}
                 onPress={(e) => {
@@ -768,7 +873,7 @@ export function Timeline({
     );
   };
 
-  /** System/event entry: compact, muted, icon-led single-line row. */
+  /** System/event entry: compact, muted, badge-on-spine single-line row. */
   const renderSystemEntry = (entry: TimelineEntry) => {
     const displayName = getEntryDisplayName(entry);
     const actionLabel = getEntryActionLabel(entry, {
@@ -777,27 +882,25 @@ export function Timeline({
       assigned: assignedLabel,
     });
     const iconSize = compact ? 12 : 14;
-    const discSize = compact ? 20 : 24;
     return (
       <XStack
         role="article"
         aria-label={`${displayName} ${actionLabel ?? entry.content ?? ""}`.trim()}
         gap={compact ? "$2" : "$3"}
         alignItems="flex-start"
-        borderRadius={radiusToken}
-        onPress={onEntryClick ? () => onEntryClick(entry) : undefined}
-        cursor={onEntryClick ? "pointer" : "default"}
       >
         <YStack
-          width={discSize}
-          height={discSize}
+          width={columnPx}
+          height={columnPx}
           alignItems="center"
           justifyContent="center"
-          opacity={0.6}
+          zIndex={1}
+          backgroundColor={componentColors.surface.background}
+          {...knobProps.borderRadius}
         >
           {getEntryIcon(entry, iconSize)}
         </YStack>
-        <YStack flex={1} gap="$0.5" paddingTop={2}>
+        <YStack flex={1} gap="$0.5" paddingTop={2} minWidth={0}>
           <XStack gap="$1.5" alignItems="center" flexWrap="wrap">
             <Text fontSize={systemFontSize} fontWeight="600" color={mutedColor}>
               {displayName}
@@ -840,46 +943,47 @@ export function Timeline({
     return defaultContent;
   };
 
-  const renderThread = (thread: TimelineThread) => {
-    const rootId = thread.entry.id;
-    const hasThreadTail =
-      thread.replies.length > 0 || (replyTarget && replyTarget.rootId === rootId);
+  const renderStackedRow = (
+    key: string,
+    children: React.ReactNode,
+    index: number,
+    count: number,
+    entry?: TimelineEntry,
+  ) => {
+    const position = getGroupPosition(index, count);
+    const corners = stackRadiusProps(position, radiusToken);
+    const clickable = !!(entry && onEntryClick);
     return (
-      <YStack key={rootId} gap={compact ? "$2" : "$3"}>
-        {renderEntryNode(thread.entry, rootId, false)}
-        {hasThreadTail && (
-          // Avatar-inset: replies indent by the parent avatar column width.
-          // Logical start rail so the thread indent mirrors in RTL; tamagui
-          // borderStartWidth does not compile to working CSS on web (SB-M-1215).
-          <YStack
-            marginInlineStart={compact ? 28 : sz === "$5" ? 46 : 36}
-            gap={compact ? "$2" : "$3"}
-            paddingInlineStart={compact ? "$2" : "$3"}
-            {...(isWeb
-              ? {
-                  borderInlineStartWidth: 1,
-                  borderInlineStartStyle: "solid" as any,
-                  borderInlineStartColor: componentColors.divider,
-                }
-              : { borderStartWidth: 1, borderStartColor: componentColors.divider })}
-          >
-            {thread.replies.map((reply) => (
-              <React.Fragment key={reply.id}>{renderEntryNode(reply, rootId, true)}</React.Fragment>
-            ))}
-            {replyTarget &&
-              replyTarget.rootId === rootId &&
-              renderReplyComposer(
-                entries.find((e) => e.id === replyTarget.parentId) ?? thread.entry,
-              )}
-          </YStack>
-        )}
+      <YStack
+        key={key}
+        position="relative"
+        overflow="hidden"
+        {...corners}
+        padding={rowPad}
+        borderBottomWidth={position === "last" || position === "only" ? 0 : 1}
+        borderBottomColor={componentColors.divider}
+        backgroundColor="transparent"
+        hoverStyle={{ ...control.hoverKnobProps, ...corners }}
+        pressStyle={clickable ? { ...control.pressKnobProps, ...corners } : undefined}
+        onPress={clickable && entry ? () => onEntryClick?.(entry) : undefined}
+        cursor={clickable ? "pointer" : "default"}
+        outlineWidth={0}
+        focusStyle={{ outlineWidth: 0 }}
+        focusVisibleStyle={clickable ? ensureFocusVisibleRing({ outlineOffset: -2 }) : undefined}
+        {...{ "data-group-position": position }}
+      >
+        <TimelineSpine
+          show={count > 1}
+          clipStart={position === "first"}
+          clipEnd={position === "last"}
+          columnPx={columnPx}
+          insetStart={rowPad}
+        />
+        {children}
       </YStack>
     );
   };
 
-  // Twin geometry for the loading rows: live avatar column width by size knob.
-  const skeletonAvatarPx = compact ? 20 : sz === "$5" ? 34 : 24;
-
   return (
     <YStack {...knobProps.gap} {...stackProps}>
       {label && (
@@ -911,11 +1015,7 @@ export function Timeline({
         errorTitle={loadFailedLabel}
         loading={
           showSkeleton ? (
-            <TimelineSkeleton
-              compact={compact}
-              avatarPx={skeletonAvatarPx}
-              loadingLabel={t("Loading")}
-            />
+            <TimelineSkeleton compact={compact} avatarPx={columnPx} loadingLabel={t("Loading")} />
           ) : (
             false
           )
@@ -925,10 +1025,24 @@ export function Timeline({
         <YStack
           role="feed"
           aria-label={label ?? t("Activity feed")}
-          gap={compact ? "$3" : knobProps.gapLg.gap}
           marginTop={canCompose ? "$2" : undefined}
         >
-          {threads.map((thread) => renderThread(thread))}
+          {feedItems.map((item, index) =>
+            item.kind === "entry"
+              ? renderStackedRow(
+                  item.key,
+                  renderEntryNode(item.entry, item.rootId, item.isReply),
+                  index,
+                  feedItems.length,
+                  item.entry,
+                )
+              : renderStackedRow(
+                  item.key,
+                  renderReplyComposer(item.parent),
+                  index,
+                  feedItems.length,
+                ),
+          )}
         </YStack>
       </AsyncBoundary>
     </YStack>

package/src/layouts/toolbar.tsx

@@ -1,8 +1,16 @@
-import { hairline, hairlineWidth, useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  MIN_PRESS_TARGET,
+  Surface,
+  hairline,
+  hairlineWidth,
+  pressTargetHitSlop,
+  pressTargetStyle,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import type React from "react";
-import { useTranslation } from "react-i18next";
+import { useTranslation } from "../shared/i18n";
 import { Button } from "@multiplatform.one/forms";
-import { Group, Separator, XStack, isWeb } from "tamagui";
+import { Group, ScrollView, Separator, XStack, isWeb } from "tamagui";
 
 export interface ToolbarAction {
   label: string;
@@ -69,7 +77,20 @@ function partitionByDestructive(actions: ToolbarAction[]) {
   return { neutral, destructive };
 }
 
-export function Toolbar({
+export function Toolbar(props: ToolbarProps) {
+  // Toolbar chrome is small + compact (Primer ActionBar / Spectrum quiet /
+  // Linear). Pre-LC-76 this rode `compact: true` (which then stepped size AND
+  // space); with the axes split, the Surface host declares the same intent
+  // lawfully: an LC-78 subtree ceiling, so hosted actions clamp to
+  // small+compact while ambient pages keep their own size.
+  return (
+    <Surface size="small" density="compact">
+      <ToolbarInner {...props} />
+    </Surface>
+  );
+}
+
+function ToolbarInner({
   primaryActions = [],
   secondaryActions = [],
   position = "top",
@@ -77,7 +98,15 @@ export function Toolbar({
 }: ToolbarProps) {
   const { t } = useTranslation();
   const loadingLabel = loadingLabelProp ?? t("Loading...");
+  // Must run inside <Surface> so size/density clamp to this ceiling.
+  // Painted actions stay ≥44 via the pressTarget* channel (LC-54).
   const { knobProps } = useResolvedKnobs();
+  // Recipe height, not the flat token ramp — `sizeToken` is the recipe KEY
+  // (LC-75). Flat `$3` is 36 while the painted small control is 28, which
+  // under-slopped the native press target below the 44 floor.
+  const sizePx = knobProps.control.height;
+  const pressFloor = pressTargetStyle();
+  const actionHitSlop = pressTargetHitSlop(sizePx);
 
   // Route emphasis through the intent system (accent/error) instead of
   // hardcoded color themes, so toolbar actions share the app's one solid
@@ -90,7 +119,6 @@ export function Toolbar({
   const renderAction = (action: ToolbarAction) => (
     <Button
       key={action.label}
-      size={knobProps.sizeToken}
       icon={action.icon as any}
       onPress={action.onPress}
       disabled={action.disabled}
@@ -98,13 +126,16 @@ export function Toolbar({
       // and skips the bare-disabled warn; loadingLabel stays for SRs.
       loading={action.loading}
       aria-label={action.loading ? loadingLabel : undefined}
-      // DG-ST-03: reason flows through the Button explain affordance.
       disabledReason={action.disabledReason}
+      disabledReasonPlacement="inline"
+      flexShrink={0}
       {...getButtonIntents(action.variant)}
       // Axiom 13 ONE BODY: the Toolbar's `outlined` variant maps to the
       // Button's canonical boolean `outlined` prop. Passing it as a string
       // `variant` matched no styled-frame key and silently dissolved (DF-10).
       outlined={action.variant === "outlined"}
+      {...pressFloor}
+      {...(!isWeb ? { hitSlop: actionHitSlop } : undefined)}
     >
       {action.label}
     </Button>
@@ -117,6 +148,8 @@ export function Toolbar({
           <Group
             key={`${region}-fused-${index}`}
             orientation="horizontal"
+            flexWrap="nowrap"
+            flexShrink={0}
             data-toolbar-cluster="fused"
             data-toolbar-region={region}
           >
@@ -131,7 +164,8 @@ export function Toolbar({
           key={`${region}-independent-${index}`}
           {...knobProps.gap}
           alignItems="center"
-          flexWrap="wrap"
+          flexWrap="nowrap"
+          flexShrink={0}
           data-toolbar-cluster="independent"
           data-toolbar-region={region}
         >
@@ -147,18 +181,20 @@ export function Toolbar({
   // Two bar children only (start cluster + trailing cluster). The separator
   // lives INSIDE the trailing cluster between neutral and destructive so it
   // cannot float mid-bar under space-between (SB-D-06 / SB-E-05).
+  // Primer ActionBar / Spectrum ActionBar / Linear: one row, leading groups
+  // scroll, trailing (incl. destructive) stays pinned.
   return (
     <XStack
+      role="toolbar"
+      aria-label={t("Toolbar")}
       // LC-39 EARNED-INSET (Axiom 16 ALIGNMENT): the bar paints no
-      // distinguishable surface — its fill is the page `$background` and its
-      // only chrome is the one-edge hairline divider, so it earns no
-      // horizontal inset. Actions sit flush on the page column's alignment
-      // line; vertical padding stays (rhythm against the divider edge the
-      // bar actually paints). If Toolbar ever grows a painted-panel variant,
-      // that variant re-earns `panelPadding` with its visible surface.
-      paddingVertical={knobProps.panelPadding.padding}
+      // distinguishable surface — SF-TRANSPARENT, so it earns no horizontal
+      // inset. Spread the panelPadding recipe whole, then eject the
+      // horizontal sides. Vertical padding stays (rhythm against the
+      // divider edge the bar actually paints).
+      {...knobProps.panelPadding}
       paddingHorizontal={0}
-      {...knobProps.gap}
+      {...knobProps.gapLg}
       // Bar edge is a divider (not a control border): hairline on high-DPI
       // (Axiom 15). Only class the side that carries the rule so the low-DPI
       // fallback cannot paint the other edge.
@@ -168,28 +204,41 @@ export function Toolbar({
         className: position === "top" ? "mp-hairline-b" : "mp-hairline-t",
       })}
       borderColor="$borderColor"
-      {...{ backgroundColor: "$background" }}
+      backgroundColor="transparent"
       justifyContent="space-between"
       alignItems="center"
-      flexWrap="wrap"
+      flexWrap="nowrap"
+      width="100%"
+      minHeight={MIN_PRESS_TARGET}
+      overflow="hidden"
       data-testid="toolbar"
     >
-      <XStack
-        {...knobProps.gap}
-        alignItems="center"
-        flexWrap="wrap"
+      <ScrollView
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        flex={1}
         flexShrink={1}
-        data-toolbar-slot="start"
+        minWidth={0}
+        {...(isWeb ? { overflow: "scroll" as const } : undefined)}
+        contentContainerStyle={{ alignItems: "center" }}
       >
-        {renderClusters(primaryActions, "primary")}
-      </XStack>
+        <XStack
+          {...knobProps.gapLg}
+          alignItems="center"
+          flexWrap="nowrap"
+          flexShrink={0}
+          data-toolbar-slot="start"
+        >
+          {renderClusters(primaryActions, "primary")}
+        </XStack>
+      </ScrollView>
 
       {hasTrailing && (
         <XStack
           {...knobProps.gap}
           alignItems="center"
-          flexWrap="wrap"
-          flexShrink={1}
+          flexWrap="nowrap"
+          flexShrink={0}
           marginInlineStart="auto"
           justifyContent="flex-end"
           data-toolbar-slot="end"
@@ -199,7 +248,9 @@ export function Toolbar({
             <Separator
               vertical
               {...hairline.vline}
-              height={knobProps.sizeToken}
+              // Match the painted control chrome, not the flat token ramp
+              // (LC-75: sizeToken is a key, not a height scalar).
+              height={knobProps.control.height}
               alignSelf="center"
               data-toolbar-separator="destructive"
             />

package/src/shared/i18n.ts

@@ -0,0 +1,26 @@
+import * as ReactI18next from "react-i18next";
+
+/**
+ * react-i18next is an OPTIONAL peer: apps that never render the i18n-using
+ * catalog components (Alert, Toast, Carousel, views/, layouts/, …) may omit
+ * it entirely and tree-shake those components away. When it is missing, the
+ * bundler substitutes an empty optional-peer-dep stub for the package —
+ * direct named imports would then surface as dozens of cryptic
+ * MISSING_EXPORT warnings and undefined-call crashes far from the cause.
+ * Every catalog usage routes through this namespace access instead, so
+ * omission stays warning-free for tree-shakers and fails loudly — naming the
+ * package and the fix — the moment an i18n-using component actually renders.
+ */
+export const useTranslation = ((...args: unknown[]) => {
+  const impl = (ReactI18next as { useTranslation?: (...args: unknown[]) => unknown })
+    .useTranslation;
+  if (typeof impl !== "function") {
+    throw new Error(
+      "[@multiplatform.one/components] react-i18next is not installed, but a component that " +
+        "translates its built-in copy was rendered. Add react-i18next and i18next to your " +
+        "app's dependencies (they are optional peers so apps that never render these " +
+        "components can omit them).",
+    );
+  }
+  return impl(...args);
+}) as typeof ReactI18next.useTranslation;

package/src/shared/textRidesText.ts

@@ -0,0 +1,57 @@
+/**
+ * LC-82 TEXT-RIDES-TEXT (catalog arm) — shared wrap-and-coalesce for child
+ * slots that render into Views. Mirrors the reference remedy in
+ * `public/forms/src/Button/index.tsx`: the singleton auto-wrap misses
+ * `{label}{cond ? suffix : ""}` (TWO string children), which web renders and
+ * native rejects ("Text strings must be rendered within a <Text> component"),
+ * silently dropping the label. Each run of adjacent bare string/number
+ * children coalesces into one concatenated label handed to the slot's own
+ * Text wrapper; element children pass through untouched, order preserved.
+ */
+
+import type { ReactNode } from "react";
+import { Children } from "react";
+
+/** Bare string/number children are legal only inside Text. */
+export const isBareTextChild = (child: unknown): child is string | number =>
+  typeof child === "string" || typeof child === "number";
+
+function coalesceBareTextRuns(
+  children: ReturnType<typeof Children.toArray>,
+  renderLabel: (label: string, key: string) => ReactNode,
+): ReactNode[] {
+  const out: ReactNode[] = [];
+  let run: string | undefined;
+  let runIndex = 0;
+  const flushRun = () => {
+    if (run !== undefined && run !== "") out.push(renderLabel(run, `lc50-run-${runIndex++}`));
+    run = undefined;
+  };
+  for (const child of children) {
+    if (isBareTextChild(child)) {
+      run = (run ?? "") + String(child);
+    } else {
+      flushRun();
+      out.push(child);
+    }
+  }
+  flushRun();
+  return out;
+}
+
+/**
+ * Wrap ALL bare string/number children of a View-rendering slot: singleton
+ * strings/numbers and runs inside arrays go through `renderLabel` (the slot's
+ * Text wrapper); pure-element children return unchanged.
+ */
+export function wrapBareTextChildren(
+  children: ReactNode,
+  renderLabel: (label: string, key?: string) => ReactNode,
+): ReactNode {
+  if (isBareTextChild(children)) return renderLabel(String(children));
+  if (Array.isArray(children)) {
+    const flattened = Children.toArray(children);
+    if (flattened.some(isBareTextChild)) return coalesceBareTextRuns(flattened, renderLabel);
+  }
+  return children;
+}

package/src/shared/useReturnFocusOnClose.ts

@@ -17,6 +17,7 @@
 
 import { useEffect, useRef } from "react";
 import { isWeb } from "tamagui";
+import { wasKeyboardFocus } from "@multiplatform.one/theme";
 
 const canUseDom = () => isWeb && typeof document !== "undefined";
 
@@ -40,7 +41,12 @@ export function useReturnFocusOnClose(open: boolean) {
       const restore = () => {
         const target = prevRef.current;
         if (!target || !target.isConnected) return;
-        if (focusIsDropped()) target.focus();
+        if (focusIsDropped()) {
+          target.focus({
+            preventScroll: true,
+            focusVisible: wasKeyboardFocus(),
+          } as FocusOptions);
+        }
       };
       // Exit animations unmount the overlay a few frames later; retry after
       // the typical exit window. Both calls are idempotent.