jfs-components 0.0.62 → 0.0.64

package/src/components/Section/Section.tsx

@@ -1,93 +1,335 @@
-import React, { useState, useRef, useCallback, useEffect } from 'react'
+import React, { useState, useMemo, useRef, useCallback } from 'react'
 import { View, Text, Pressable, Platform, type StyleProp, type ViewStyle, type PressableStateCallbackType } from 'react-native'
+import Animated, {
+  FadeInUp,
+  FadeOutUp,
+  ReduceMotion,
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+} from 'react-native-reanimated'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import NavArrow from '../NavArrow/NavArrow'
+import IconCapsule from '../IconCapsule/IconCapsule'
+import ListItem from '../ListItem/ListItem'
 import { usePressableWebSupport, type WebAccessibilityProps } from '../../utils/web-platform-utils'
-import { cloneChildrenWithModes, flattenChildren } from '../../utils/react-utils'
+import { EMPTY_MODES, cloneChildrenWithModes, flattenChildren } from '../../utils/react-utils'
+
+// Match Button: delay the press visual on iOS so a scroll-cancelled touch
+// never applies the "pressed" style. See Button.tsx for the rationale.
+const IS_WEB = Platform.OS === 'web'
+const IS_IOS = Platform.OS === 'ios'
+const HEADER_PRESS_DELAY = IS_IOS ? 130 : 0
+
+// Module-scope style constants — never re-allocated per render.
+const headerWrapStyle: ViewStyle = {
+  flexDirection: 'row',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+}
+const headerHoverStyle: ViewStyle = { opacity: 0.95 }
+const headerPressedStyle: ViewStyle = { opacity: 0.85 }
+const headerFocusStyle: ViewStyle = { borderColor: '#222', borderWidth: 1 }
 
 // ---------------------------------------------------------------------------
-// Shared grid layout: measures widest child, enforces uniform width,
-// chunks into fixed rows of up to maxColumns, space-between per row.
+// Shared grid layout — first-row-anchored sizing.
+//
+// We measure each cell of the *first row* via `onLayout`, take their max as
+// the canonical cellWidth, then apply that explicit width to every cell in
+// every row. Combined with `justify-content: space-between`, this preserves
+// three visual invariants regardless of viewport width:
+//   1. The first cell hugs the container's left edge.
+//   2. The last cell hugs the container's right edge.
+//   3. Cells in row N column K align with cells in row N+1 column K
+//      (uniform cell width across the whole grid).
+//
+// Why first-row-anchored?
+//
+// The first row is *always present* (collapsed and expanded both render it),
+// so the measurement happens exactly once on first mount and stays valid for
+// the lifetime of the SlotGrid — the cellWidth is *stable across toggles*.
+// New cells in row 2+ mount when the user expands, and by that time
+// `cellWidth` is already cached, so their `Animated.View` `entering` cascade
+// is never interrupted by a re-measurement-driven re-render.
+//
+// Why not container-width math (e.g. `(containerWidth - gaps) / columns`)?
+// That makes every cell wide enough to fill its share of the row. On wide
+// viewports each cell becomes much wider than its content (icon + label),
+// the content centers inside its oversized cell, and the visible result is
+// a "dead margin" of empty space on the left and right of the grid. Sizing
+// cells to natural content + `space-between` instead pushes the first cell
+// flush left and the last cell flush right, distributing leftover space as
+// the inter-cell gap.
+//
+// Why not measure every cell?
+// The original implementation did, and `max()` could change when the item
+// count changed (collapsed picks one max, expanded another), producing a
+// visible width jump on toggle. The per-cell remeasurement also forced a
+// re-render in the same React batch as the `entering` animation mounting,
+// which Reanimated treats as a cancellation signal — cells visibly didn't
+// animate. Anchoring to the first row eliminates both costs.
+//
+// First-frame behavior is preserved (no blank-flash): until the first-row
+// `onLayout` fires, cells render at their natural width with `space-between`
+// already laying them out correctly; the only thing that changes after
+// measurement is that subsequent rows snap to the same cellWidth so columns
+// align.
 // ---------------------------------------------------------------------------
 const SLOT_GRID_MAX_COLUMNS = 4
 
+// Beyond this many "extra" cells, additional cells reuse the cap delay so very
+// large grids (16, 32, …) still feel snappy instead of cascading for >1s.
+const SLOT_GRID_STAGGER_CAP = 8
+const SLOT_GRID_ENTER_STAGGER_MS = 35
+const SLOT_GRID_EXIT_STAGGER_MS = 20
+const SLOT_GRID_EXIT_DURATION_MS = 160
+
 type SlotGridProps = {
   items: React.ReactNode[];
   gap: number;
   maxColumns?: number;
+  /**
+   * If set, cells whose index is `>= animateExtrasFromIndex` are wrapped in
+   * `Animated.View` with staggered FadeInUp/FadeOutUp builders so that they
+   * fade in (and reverse-fade out) when they mount or unmount. Cells below
+   * this threshold render as plain `<View>` and are unaffected.
+   */
+  animateExtrasFromIndex?: number;
+  /**
+   * If true, the rows container animates its height via an explicit
+   * `useSharedValue` + `withSpring` driven by `onLayout` measurements of the
+   * inner content (with `overflow: 'hidden'` to clip mid-animation). Cells
+   * inside always render at their natural size — they are *never* resized
+   * during the transition. Default false.
+   */
+  animateContainerLayout?: boolean;
 }
 
-function SlotGrid({ items, gap, maxColumns = SLOT_GRID_MAX_COLUMNS }: SlotGridProps) {
-  const [maxItemWidth, setMaxItemWidth] = useState<number | null>(null)
-  const [measureTimedOut, setMeasureTimedOut] = useState(false)
-  const itemWidthsRef = useRef<Map<number, number>>(new Map())
-  const totalItems = items.length
-
-  useEffect(() => {
-    itemWidthsRef.current.clear()
-    setMaxItemWidth(null)
-    setMeasureTimedOut(false)
-  }, [totalItems])
-
-  useEffect(() => {
-    if (maxItemWidth !== null) return
-    const timer = setTimeout(() => setMeasureTimedOut(true), 500)
-    return () => clearTimeout(timer)
-  }, [maxItemWidth, totalItems])
-
-  const handleItemLayout = useCallback((index: number, width: number) => {
-    itemWidthsRef.current.set(index, width)
-    if (itemWidthsRef.current.size >= totalItems && totalItems > 0) {
-      setMaxItemWidth(Math.max(...itemWidthsRef.current.values()))
-    }
-  }, [totalItems])
+const slotGridRowFlowStyle: ViewStyle = {
+  flexDirection: 'row',
+  justifyContent: 'space-between',
+}
 
-  const isMeasured = maxItemWidth !== null
+const SlotGrid = React.memo(function SlotGrid({
+  items,
+  gap,
+  maxColumns = SLOT_GRID_MAX_COLUMNS,
+  animateExtrasFromIndex,
+  animateContainerLayout,
+}: SlotGridProps) {
+  const totalItems = items.length
   const columns = Math.min(maxColumns, totalItems || 1)
+  // Number of cells in the first row. Capped by `columns` (a fully-filled row)
+  // and by `totalItems` (e.g. a 1-item grid has a 1-cell first row).
+  const firstRowSize = Math.min(columns, totalItems)
+
+  // First-row width measurement. Only cells whose `itemIndex < firstRowSize`
+  // get an `onLayout` callback. Once we have a width sample for each first-row
+  // cell, we publish the max and the callbacks become inert — no further
+  // measurement happens for the rest of the SlotGrid's lifetime, so toggles
+  // never trigger a re-measurement-driven re-render.
+  const [firstRowMaxWidth, setFirstRowMaxWidth] = useState<number | null>(null)
+  const firstRowWidthsRef = useRef<Map<number, number>>(new Map())
+  const handleFirstRowItemLayout = useCallback(
+    (index: number, width: number) => {
+      const widths = firstRowWidthsRef.current
+      const previous = widths.get(index)
+      if (previous !== undefined && Math.abs(previous - width) < 0.5) return
+      widths.set(index, width)
+      if (widths.size >= firstRowSize && firstRowSize > 0) {
+        let newMax = 0
+        for (const w of widths.values()) {
+          if (w > newMax) newMax = w
+        }
+        setFirstRowMaxWidth((prev) =>
+          prev !== null && Math.abs(prev - newMax) < 0.5 ? prev : newMax
+        )
+      }
+    },
+    [firstRowSize]
+  )
+
+  const cellWidth = firstRowMaxWidth
 
   const rows: React.ReactNode[][] = []
   for (let i = 0; i < items.length; i += columns) {
     rows.push(items.slice(i, i + columns))
   }
 
-  return (
-    <View style={{ gap, ...(isMeasured || measureTimedOut ? {} : { opacity: 0 }) }}>
+  const containerStyle = useMemo<ViewStyle>(() => ({ gap }), [gap])
+  const cellStyle = useMemo<ViewStyle | undefined>(
+    () => (cellWidth !== null ? { width: cellWidth } : undefined),
+    [cellWidth]
+  )
+
+  // `space-between` distributes any leftover row space as inter-cell gap, so
+  // the first cell is flush-left and the last cell is flush-right regardless
+  // of whether cellWidth has been measured yet. Identical layout strategy
+  // before and after measurement — no first-frame layout shift.
+  const rowStyle = slotGridRowFlowStyle
+
+  const animationsEnabled = animateExtrasFromIndex !== undefined
+  // Resolve the threshold once. When undefined we treat it as
+  // Number.POSITIVE_INFINITY so the per-cell branch always picks the plain
+  // `<View>` path.
+  const extrasThreshold = animationsEnabled
+    ? (animateExtrasFromIndex as number)
+    : Number.POSITIVE_INFINITY
+  // Total count of "extra" cells currently rendered. Used to compute the
+  // reverse-stagger delay for the exiting animation so that the last cell
+  // leaves first.
+  const extrasCount = animationsEnabled
+    ? Math.max(0, totalItems - extrasThreshold)
+    : 0
+
+  const useAnimatedContainer = animateContainerLayout === true
+
+  // Explicit-height clip animation:
+  //
+  // Reanimated's `LinearTransition` interpolates the container's bounds, and
+  // in practice that interpolation drags on the cells inside (they momentarily
+  // appear squashed because the parent is shorter than its natural content
+  // for the duration of the animation). To keep cells at their *natural size
+  // throughout*, we instead:
+  //   1. Render the rows inside an inner `<View>` that sizes to its content
+  //      naturally — cells are never squeezed, never resized.
+  //   2. Wrap that inner view in an `Animated.View` with `overflow: 'hidden'`
+  //      and an explicit `height` driven by a shared value.
+  //   3. The inner view reports its natural height via `onLayout`. The first
+  //      measurement snaps the shared value (no first-mount animation). Every
+  //      subsequent change (e.g. expand/collapse adds or removes rows) springs
+  //      the shared value to the new natural height.
+  //
+  // Visually: the container reveals/conceals content like a curtain, and the
+  // cells never deform.
+  const animatedHeight = useSharedValue<number>(-1)
+  const isFirstHeightLayoutRef = useRef(true)
+  const handleContentLayout = useCallback(
+    (e: { nativeEvent: { layout: { height: number } } }) => {
+      const h = e.nativeEvent.layout.height
+      if (h <= 0) return
+      if (isFirstHeightLayoutRef.current) {
+        isFirstHeightLayoutRef.current = false
+        animatedHeight.value = h
+        return
+      }
+      animatedHeight.value = withSpring(h, {
+        damping: 22,
+        stiffness: 180,
+        reduceMotion: ReduceMotion.System,
+      })
+    },
+    [animatedHeight]
+  )
+  const animatedHeightStyle = useAnimatedStyle(() =>
+    animatedHeight.value < 0
+      ? {}
+      : { height: animatedHeight.value, overflow: 'hidden' as const }
+  )
+
+  const rowsChildren = (
+    <>
       {rows.map((row, rowIndex) => {
         const spacersNeeded = row.length < columns ? columns - row.length : 0
         return (
-          <View
-            key={rowIndex}
-            style={{
-              flexDirection: 'row' as const,
-              justifyContent: 'space-between' as const,
-            }}
-          >
+          <View key={rowIndex} style={rowStyle}>
             {row.map((child, colIndex) => {
               const itemIndex = rowIndex * columns + colIndex
+              // Only first-row cells participate in measurement, and only
+              // until firstRowMaxWidth has been published. After that the
+              // onLayout becomes a no-op (we elide it).
+              const onLayoutHandler =
+                firstRowMaxWidth === null && itemIndex < firstRowSize
+                  ? (e: { nativeEvent: { layout: { width: number } } }) =>
+                      handleFirstRowItemLayout(
+                        itemIndex,
+                        e.nativeEvent.layout.width
+                      )
+                  : undefined
+
+              if (itemIndex >= extrasThreshold) {
+                const extraOrdinal = itemIndex - extrasThreshold
+                const enterStaggerSteps = Math.min(
+                  extraOrdinal,
+                  SLOT_GRID_STAGGER_CAP
+                )
+                const reverseOrdinal = Math.max(
+                  0,
+                  extrasCount - 1 - extraOrdinal
+                )
+                const exitStaggerSteps = Math.min(
+                  reverseOrdinal,
+                  SLOT_GRID_STAGGER_CAP
+                )
+                const entering = FadeInUp.springify()
+                  .damping(18)
+                  .delay(enterStaggerSteps * SLOT_GRID_ENTER_STAGGER_MS)
+                  .reduceMotion(ReduceMotion.System)
+                const exiting = FadeOutUp.duration(SLOT_GRID_EXIT_DURATION_MS)
+                  .delay(exitStaggerSteps * SLOT_GRID_EXIT_STAGGER_MS)
+                  .reduceMotion(ReduceMotion.System)
+                return (
+                  <Animated.View
+                    key={itemIndex}
+                    entering={entering}
+                    exiting={exiting}
+                    {...(onLayoutHandler ? { onLayout: onLayoutHandler } : null)}
+                    style={cellStyle}
+                  >
+                    {child}
+                  </Animated.View>
+                )
+              }
+
               return (
                 <View
                   key={itemIndex}
-                  onLayout={
-                    !isMeasured
-                      ? (e) => handleItemLayout(itemIndex, e.nativeEvent.layout.width)
-                      : undefined
-                  }
-                  style={isMeasured ? { width: maxItemWidth } : undefined}
+                  {...(onLayoutHandler ? { onLayout: onLayoutHandler } : null)}
+                  style={cellStyle}
                 >
                   {child}
                 </View>
               )
             })}
-            {isMeasured &&
+            {cellWidth !== null &&
               spacersNeeded > 0 &&
               Array.from({ length: spacersNeeded }, (_, i) => (
-                <View key={`spacer-${i}`} style={{ width: maxItemWidth }} />
+                <View key={`spacer-${i}`} style={cellStyle} />
               ))}
           </View>
         )
       })}
-    </View>
+    </>
   )
+
+  if (useAnimatedContainer) {
+    // Outer Animated.View clips and animates height. Inner View holds the
+    // rows at natural size and reports its natural height for the spring
+    // target. Cell-width measurement happens on the cells themselves
+    // (first-row only) — no container-level onLayout is needed.
+    return (
+      <Animated.View style={animatedHeightStyle}>
+        <View style={containerStyle} onLayout={handleContentLayout}>
+          {rowsChildren}
+        </View>
+      </Animated.View>
+    )
+  }
+
+  return <View style={containerStyle}>{rowsChildren}</View>
+}, slotGridPropsAreEqual)
+
+function slotGridPropsAreEqual(prev: SlotGridProps, next: SlotGridProps) {
+  if (prev.gap !== next.gap) return false
+  if ((prev.maxColumns ?? SLOT_GRID_MAX_COLUMNS) !== (next.maxColumns ?? SLOT_GRID_MAX_COLUMNS)) return false
+  if (prev.animateExtrasFromIndex !== next.animateExtrasFromIndex) return false
+  if (prev.animateContainerLayout !== next.animateContainerLayout) return false
+  if (prev.items === next.items) return true
+  if (prev.items.length !== next.items.length) return false
+  for (let i = 0; i < prev.items.length; i++) {
+    if (prev.items[i] !== next.items[i]) return false
+  }
+  return true
 }
 
 type SectionProps = {
@@ -132,40 +374,27 @@ type SectionProps = {
  * @param {string} [props.accessibilityLabel] - Accessibility label for the section. If not provided, uses title
  * @param {string} [props.accessibilityHint] - Additional accessibility hint for screen readers
  */
-function Section({
-  title = 'Section title',
-  supportText = 'Section support text',
-  showSupportText = true,
-  slot,
-  slotDirection = 'row',
-  modes = {},
-  onPress,
-  style,
-  accessibilityLabel,
-  accessibilityHint,
-  webAccessibilityProps,
-  ...rest
-}: SectionProps) {
-  const [isHeaderFocused, setIsHeaderFocused] = useState(false)
-  const [isHeaderHovered, setIsHeaderHovered] = useState(false)
-  const [isHeaderPressed, setIsHeaderPressed] = useState(false)
-  const headerFocusStyle: ViewStyle = isHeaderFocused ? { borderColor: '#222', borderWidth: 1 } : {}
-  const headerHoverStyle: ViewStyle = isHeaderHovered ? { opacity: 0.95 } : {}
-  const headerPressedStyle: ViewStyle = isHeaderPressed ? { opacity: 0.85 } : {}
-  // Resolve section container tokens
+interface SectionTokens {
+  containerStyle: ViewStyle;
+  headerStyle: ViewStyle;
+  titleStyle: ViewStyle;
+  supportTextStyle: ViewStyle;
+  sectionGap: number;
+  slotGap: number;
+}
+
+function resolveSectionTokens(modes: Record<string, any>): SectionTokens {
   const backgroundColor = getVariableByName('section/background/color', modes) || '#ffffff'
-  const sectionGap = getVariableByName('section/gap', modes) || 12
-  const slotGap = getVariableByName('slot/gap', modes) || 12
+  const sectionGap = (getVariableByName('section/gap', modes) || 12) as number
+  const slotGap = (getVariableByName('slot/gap', modes) || 12) as number
   const paddingHorizontal = getVariableByName('section/padding/horizontal', modes) || 12
   const paddingVertical = getVariableByName('section/padding/vertical', modes) || 16
   const radius = getVariableByName('section/radius', modes) || 12
 
-  // Resolve section header tokens
   const headerGap = getVariableByName('section/header/gap', modes) || 8
   const headerPaddingHorizontal = getVariableByName('section/header/padding/horizontal', modes) || 0
   const headerPaddingVertical = getVariableByName('section/header/padding/vertical', modes) || 0
 
-  // Resolve section title tokens
   const titleColor = getVariableByName('section/title/color', modes) || '#0f0d0a'
   const titleFontSize = getVariableByName('section/title/fontSize', modes) || 18
   const titleLineHeight = getVariableByName('section/title/lineHeight', modes) || 20
@@ -176,7 +405,6 @@ function Section({
       ? titleFontWeightRaw.toString()
       : titleFontWeightRaw
 
-  // Resolve section support text tokens
   const supportTextColor = getVariableByName('section/supportText/color', modes) || '#1f1a14'
   const supportTextFontSize = getVariableByName('section/supportText/fontSize', modes) || 14
   const supportTextLineHeight = getVariableByName('section/supportText/lineHeight', modes) || 18
@@ -187,46 +415,85 @@ function Section({
       ? supportTextFontWeightRaw.toString()
       : supportTextFontWeightRaw
 
-  const containerStyle = {
-    backgroundColor,
-    paddingHorizontal,
-    paddingVertical,
-    borderRadius: radius,
-    gap: sectionGap,
-  }
-
-  const headerStyle = {
-    paddingHorizontal: headerPaddingHorizontal,
-    paddingVertical: headerPaddingVertical,
-    gap: headerGap,
-  }
-
-  const headerWrapStyle: ViewStyle = {
-    flexDirection: 'row' as const,
-    alignItems: 'center' as const,
-    justifyContent: 'space-between' as const,
-  }
-
-  const titleStyle = {
-    flex: 1,
-    color: titleColor,
-    fontSize: titleFontSize,
-    lineHeight: titleLineHeight,
-    fontFamily: titleFontFamily,
-    fontWeight: titleFontWeight,
+  return {
+    containerStyle: {
+      backgroundColor,
+      paddingHorizontal,
+      paddingVertical,
+      borderRadius: radius,
+      gap: sectionGap,
+    },
+    headerStyle: {
+      paddingHorizontal: headerPaddingHorizontal,
+      paddingVertical: headerPaddingVertical,
+      gap: headerGap,
+    },
+    titleStyle: {
+      flex: 1,
+      color: titleColor,
+      fontSize: titleFontSize,
+      lineHeight: titleLineHeight,
+      fontFamily: titleFontFamily,
+      fontWeight: titleFontWeight,
+    } as ViewStyle,
+    supportTextStyle: {
+      color: supportTextColor,
+      fontSize: supportTextFontSize,
+      lineHeight: supportTextLineHeight,
+      fontFamily: supportTextFontFamily,
+      fontWeight: supportTextFontWeight,
+    } as ViewStyle,
+    sectionGap,
+    slotGap,
   }
+}
 
-  const supportTextStyle = {
-    color: supportTextColor,
-    fontSize: supportTextFontSize,
-    lineHeight: supportTextLineHeight,
-    fontFamily: supportTextFontFamily,
-    fontWeight: supportTextFontWeight,
-  }
+function Section({
+  title = 'Section title',
+  supportText = 'Section support text',
+  showSupportText = true,
+  slot,
+  slotDirection = 'row',
+  modes = EMPTY_MODES,
+  onPress,
+  style,
+  // accessibilityLabel is intentionally accepted on the type for API
+  // back-compat, but the inner Pressable/View deliberately pass
+  // `accessibilityLabel={undefined}` (the title Text carries the label
+  // instead). Prefix to satisfy the unused-var lint while keeping the prop
+  // shape unchanged.
+  accessibilityLabel: _accessibilityLabel,
+  accessibilityHint,
+  webAccessibilityProps,
+  ...rest
+}: SectionProps) {
+  // Focus and hover are still mirrored in React because they are visible,
+  // sustained states (web-only in practice). The setters are gated so they
+  // never fire on native — keeping the component render-free during touch.
+  // Press is handled imperatively via the `Pressable` style callback so a
+  // scroll-cancelled touch never schedules a React render.
+  const [isHeaderFocused, setIsHeaderFocused] = useState(false)
+  const [isHeaderHovered, setIsHeaderHovered] = useState(false)
 
-  // Generate default accessibility label from title and supportText
-  const defaultAccessibilityLabel = accessibilityLabel ||
-    (showSupportText ? `${title}. ${supportText}` : title)
+  // Mirror user handlers in a ref so our wrappers can stay referentially
+  // stable. Without this, every parent re-render would hand Pressable fresh
+  // function identities and re-bind every event.
+  const userHandlersRef = useRef<{
+    onPressIn?: (e: any) => void
+    onPressOut?: (e: any) => void
+    onHoverIn?: (e: any) => void
+    onHoverOut?: (e: any) => void
+    onFocus?: (e: any) => void
+    onBlur?: (e: any) => void
+  }>({})
+  userHandlersRef.current.onPressIn = (rest as any)?.onPressIn
+  userHandlersRef.current.onPressOut = (rest as any)?.onPressOut
+  userHandlersRef.current.onHoverIn = (rest as any)?.onHoverIn
+  userHandlersRef.current.onHoverOut = (rest as any)?.onHoverOut
+  userHandlersRef.current.onFocus = (rest as any)?.onFocus
+  userHandlersRef.current.onBlur = (rest as any)?.onBlur
+
+  const tokens = useMemo(() => resolveSectionTokens(modes), [modes])
 
   // Get web platform support props (only used when onPress is defined)
   const webProps = usePressableWebSupport({
@@ -241,7 +508,7 @@ function Section({
     <>
       <View style={headerWrapStyle}>
         <Text
-          style={titleStyle}
+          style={tokens.titleStyle}
           numberOfLines={1}
           accessibilityElementsHidden={true}
           importantForAccessibility="no"
@@ -254,7 +521,7 @@ function Section({
       </View>
       {showSupportText && (
         <Text
-          style={supportTextStyle}
+          style={tokens.supportTextStyle}
           numberOfLines={2}
           accessibilityElementsHidden={true}
           importantForAccessibility="no"
@@ -265,10 +532,53 @@ function Section({
     </>
   )
 
+  // Stable handler identities. User handlers are read through the ref so
+  // these wrappers don't need new identities each render.
+  const handlePressIn = useCallback((e: any) => {
+    userHandlersRef.current.onPressIn?.(e)
+  }, [])
+  const handlePressOut = useCallback((e: any) => {
+    userHandlersRef.current.onPressOut?.(e)
+  }, [])
+  const handleHoverIn = useCallback((e: any) => {
+    if (IS_WEB) setIsHeaderHovered(true)
+    userHandlersRef.current.onHoverIn?.(e)
+  }, [])
+  const handleHoverOut = useCallback((e: any) => {
+    if (IS_WEB) setIsHeaderHovered(false)
+    userHandlersRef.current.onHoverOut?.(e)
+  }, [])
+  const handleFocus = useCallback((e: any) => {
+    if (IS_WEB) setIsHeaderFocused(true)
+    userHandlersRef.current.onFocus?.(e)
+  }, [])
+  const handleBlur = useCallback((e: any) => {
+    if (IS_WEB) setIsHeaderFocused(false)
+    userHandlersRef.current.onBlur?.(e)
+  }, [])
+
+  // The pressed visual is applied by the host view directly through the
+  // Pressable style callback — no React render is scheduled. We still want
+  // the (constant) hover style on web so we keep it in the array.
+  const headerStyleCallback = useCallback(
+    ({ pressed }: PressableStateCallbackType): StyleProp<ViewStyle> => [
+      tokens.headerStyle,
+      pressed ? headerPressedStyle : null,
+      isHeaderHovered ? headerHoverStyle : null,
+      isHeaderFocused ? headerFocusStyle : null,
+    ],
+    [tokens.headerStyle, isHeaderHovered, isHeaderFocused]
+  )
+
+  const containerStyleArray = useMemo(
+    () => [tokens.containerStyle, style],
+    [tokens.containerStyle, style]
+  )
+
   return (
     <View
-      style={[containerStyle, style]}
-      {...(Platform.OS === 'web' ? { accessibilityRole: 'region' as any } : undefined)}
+      style={containerStyleArray}
+      {...(IS_WEB ? { accessibilityRole: 'region' as any } : undefined)}
       accessibilityLabel={undefined}
       accessibilityHint={accessibilityHint}
       {...rest}
@@ -277,62 +587,66 @@ function Section({
         <Pressable
           accessibilityRole="button"
           accessibilityLabel={undefined}
-          accessibilityHint={accessibilityHint || "Opens section details"}
+          accessibilityHint={accessibilityHint || 'Opens section details'}
           onPress={onPress}
-          onPressIn={(e: any) => {
-            setIsHeaderPressed(true)
-              ; (rest as any)?.onPressIn?.(e)
-          }}
-          onPressOut={(e: any) => {
-            setIsHeaderPressed(false)
-              ; (rest as any)?.onPressOut?.(e)
-          }}
-          onFocus={(e: any) => {
-            setIsHeaderFocused(true)
-              ; (rest as any)?.onFocus?.(e)
-          }}
-          onBlur={(e: any) => {
-            setIsHeaderFocused(false)
-              ; (rest as any)?.onBlur?.(e)
-          }}
-          onHoverIn={(e: any) => {
-            setIsHeaderHovered(true)
-              ; (rest as any)?.onHoverIn?.(e)
-          }}
-          onHoverOut={(e: any) => {
-            setIsHeaderHovered(false)
-              ; (rest as any)?.onHoverOut?.(e)
-          }}
-          style={({ pressed }: PressableStateCallbackType) => [
-            headerStyle,
-            pressed ? headerPressedStyle : null,
-            headerHoverStyle,
-            headerFocusStyle,
-          ]}
+          onPressIn={handlePressIn}
+          onPressOut={handlePressOut}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onHoverIn={handleHoverIn}
+          onHoverOut={handleHoverOut}
+          unstable_pressDelay={HEADER_PRESS_DELAY}
+          style={headerStyleCallback}
           {...webProps}
         >
           {headerContent}
         </Pressable>
       ) : (
-        <View style={headerStyle}>
+        <View style={tokens.headerStyle}>
           {headerContent}
         </View>
       )}
-      {slot && slotDirection === 'row' && (
-        <SlotGrid
-          items={cloneChildrenWithModes(flattenChildren(slot), modes)}
-          gap={sectionGap}
-        />
-      )}
-      {slot && slotDirection === 'column' && (
-        <View style={{ flexDirection: 'column' as const, gap: slotGap }}>
-          {cloneChildrenWithModes(flattenChildren(slot), modes)}
-        </View>
-      )}
+      {slot && <SectionSlot slot={slot} modes={modes} direction={slotDirection} rowGap={tokens.sectionGap} columnGap={tokens.slotGap} />}
     </View>
   )
 }
 
+type SectionSlotProps = {
+  slot: React.ReactNode;
+  modes: Record<string, any>;
+  direction: 'row' | 'column';
+  rowGap: number;
+  columnGap: number;
+}
+
+/**
+ * Internal helper that processes the slot children once per (slot, modes) pair
+ * and dispatches to the row (SlotGrid) or column layout. Splitting this out of
+ * `Section` lets the parent re-render (e.g. for header press/hover state)
+ * without re-walking the slot tree via `cloneChildrenWithModes`.
+ */
+function SectionSlot({ slot, modes, direction, rowGap, columnGap }: SectionSlotProps) {
+  const processed = useMemo(
+    () => cloneChildrenWithModes(flattenChildren(slot), modes),
+    [slot, modes]
+  )
+
+  const columnContainerStyle = useMemo<ViewStyle>(
+    () => ({ flexDirection: 'column', gap: columnGap }),
+    [columnGap]
+  )
+
+  if (direction === 'row') {
+    return <SlotGrid items={processed} gap={rowGap} />
+  }
+  return <View style={columnContainerStyle}>{processed}</View>
+}
+
+type BentoToggleRenderState = {
+  expanded: boolean;
+  toggle: () => void;
+}
+
 type SectionBentoProps = {
   navSlot?: React.ReactNode;
   upiSlot?: React.ReactNode;
@@ -344,6 +658,43 @@ type SectionBentoProps = {
    * Web-specific accessibility props (only used on web platform)
    */
   webAccessibilityProps?: WebAccessibilityProps;
+  /**
+   * Total cell count visible when collapsed (real items + the toggle cell).
+   * Defaults to {@link SLOT_GRID_MAX_COLUMNS} (4) so the collapsed state fills
+   * exactly one row. When `navSlot.length <= collapsedCount`, expansion is
+   * disabled (no toggle injected, no animation wrappers — identical to the
+   * legacy behavior for back-compat).
+   */
+  collapsedCount?: number;
+  /**
+   * Uncontrolled initial expanded state. Ignored when `expanded` is provided.
+   * Defaults to `false`.
+   */
+  defaultExpanded?: boolean;
+  /**
+   * Controlled expanded state. When provided, `onExpandedChange` should also
+   * be provided so the component can request changes.
+   */
+  expanded?: boolean;
+  /**
+   * Called when the user taps the toggle. Required in controlled mode; ignored
+   * in uncontrolled mode unless you want to observe the change.
+   */
+  onExpandedChange?: (next: boolean) => void;
+  /** Label shown on the toggle cell when collapsed. Default `'More'`. */
+  toggleMoreLabel?: string;
+  /** Label shown on the toggle cell when expanded. Default `'Less'`. */
+  toggleLessLabel?: string;
+  /** Icon name shown on the toggle when collapsed. Default `'ic_chevron_down'`. */
+  toggleMoreIcon?: string;
+  /** Icon name shown on the toggle when expanded. Default `'ic_chevron_up'`. */
+  toggleLessIcon?: string;
+  /**
+   * Escape hatch: render a custom toggle cell instead of the default ListItem.
+   * The provided node is rendered in the toggle's grid slot. Wire `toggle()` to
+   * any tap interaction inside it. Height + per-cell animations still apply.
+   */
+  renderToggle?: (state: BentoToggleRenderState) => React.ReactNode;
 } & React.ComponentProps<typeof View>;
 
 /**
@@ -368,37 +719,118 @@ type SectionBentoProps = {
  * @param {string} [props.accessibilityLabel] - Accessibility label for the section
  * @param {string} [props.accessibilityHint] - Additional accessibility hint for screen readers
  */
+const sectionBentoUpiRowStyle: ViewStyle = { flexDirection: 'row', gap: 8 }
+
 function SectionBento({
   navSlot,
   upiSlot,
-  modes = {},
+  modes = EMPTY_MODES,
   style,
-  accessibilityLabel = undefined,
+  // Same rationale as Section: accepted on the type but unused internally.
+  accessibilityLabel: _accessibilityLabel,
   accessibilityHint,
+  collapsedCount = SLOT_GRID_MAX_COLUMNS,
+  defaultExpanded = false,
+  expanded: controlledExpanded,
+  onExpandedChange,
+  toggleMoreLabel = 'More',
+  toggleLessLabel = 'Less',
+  toggleMoreIcon = 'ic_chevron_down',
+  toggleLessIcon = 'ic_chevron_up',
+  renderToggle,
   ...rest
 }: SectionBentoProps) {
-  // Resolve section container tokens
   const backgroundColor = getVariableByName('section/background/color', modes) || '#ffffff'
   const gap = getVariableByName('section/gap', modes) || 12
   const paddingHorizontal = getVariableByName('section/padding/horizontal', modes) || 12
   const paddingVertical = getVariableByName('section/padding/vertical', modes) || 16
   const radius = getVariableByName('section/radius', modes) || 12
 
-  const containerStyle = {
-    backgroundColor,
-    paddingHorizontal,
-    paddingVertical,
-    borderRadius: radius,
-    gap,
-  }
+  const containerStyle = useMemo<ViewStyle>(
+    () => ({
+      backgroundColor,
+      paddingHorizontal,
+      paddingVertical,
+      borderRadius: radius,
+      gap,
+    }),
+    [backgroundColor, paddingHorizontal, paddingVertical, radius, gap]
+  )
+
+  const processedNavSlot = useMemo(
+    () => (navSlot ? cloneChildrenWithModes(flattenChildren(navSlot), modes) : null),
+    [navSlot, modes]
+  )
+
+  const processedUpiSlot = useMemo(
+    () => (upiSlot ? cloneChildrenWithModes(flattenChildren(upiSlot), modes) : null),
+    [upiSlot, modes]
+  )
 
-  const processedNavSlot = navSlot
-    ? cloneChildrenWithModes(flattenChildren(navSlot), modes)
-    : null
+  // `canExpand` is true iff there are strictly more real items than fit into
+  // the collapsed grid. When `allRealItems.length === collapsedCount` we just
+  // render them all with no toggle — identical to the pre-feature behavior.
+  const allRealItems = useMemo(() => processedNavSlot ?? [], [processedNavSlot])
+  const canExpand = allRealItems.length > collapsedCount
+
+  const isControlled = controlledExpanded !== undefined
+  const [internalExpanded, setInternalExpanded] = useState<boolean>(defaultExpanded)
+  const expanded = isControlled ? (controlledExpanded as boolean) : internalExpanded
+
+  // Mirror onExpandedChange in a ref so `toggle` can stay referentially stable.
+  const onExpandedChangeRef = useRef(onExpandedChange)
+  onExpandedChangeRef.current = onExpandedChange
+  const isControlledRef = useRef(isControlled)
+  isControlledRef.current = isControlled
+  const expandedRef = useRef(expanded)
+  expandedRef.current = expanded
+
+  const toggle = useCallback(() => {
+    const next = !expandedRef.current
+    if (!isControlledRef.current) {
+      setInternalExpanded(next)
+    }
+    onExpandedChangeRef.current?.(next)
+  }, [])
 
-  const processedUpiSlot = upiSlot
-    ? cloneChildrenWithModes(flattenChildren(upiSlot), modes)
-    : null
+  const navGridItems = useMemo<React.ReactNode[]>(() => {
+    if (!canExpand) {
+      return allRealItems
+    }
+    // Leave the last collapsed slot for the toggle cell.
+    const visibleRealItems = expanded
+      ? allRealItems
+      : allRealItems.slice(0, collapsedCount - 1)
+
+    const toggleNode = renderToggle
+      ? renderToggle({ expanded, toggle })
+      : (
+        <DefaultBentoToggle
+          expanded={expanded}
+          onPress={toggle}
+          modes={modes}
+          moreLabel={toggleMoreLabel}
+          lessLabel={toggleLessLabel}
+          moreIcon={toggleMoreIcon}
+          lessIcon={toggleLessIcon}
+          extraCount={allRealItems.length - (collapsedCount - 1)}
+        />
+      )
+
+    return [...visibleRealItems, toggleNode]
+  }, [
+    canExpand,
+    allRealItems,
+    expanded,
+    collapsedCount,
+    renderToggle,
+    toggle,
+    modes,
+    toggleMoreLabel,
+    toggleLessLabel,
+    toggleMoreIcon,
+    toggleLessIcon,
+  ])
 
   return (
     <View
@@ -408,14 +840,20 @@ function SectionBento({
       accessibilityHint={accessibilityHint}
       {...rest}
     >
-      {processedNavSlot && (
+      {navGridItems.length > 0 && (
         <SlotGrid
-          items={processedNavSlot as React.ReactNode[]}
+          items={navGridItems}
           gap={gap}
+          {...(canExpand
+            ? {
+                animateExtrasFromIndex: collapsedCount,
+                animateContainerLayout: true,
+              }
+            : null)}
         />
       )}
       {processedUpiSlot && (
-        <View style={{ flexDirection: 'row' as const, gap: 8 }}>
+        <View style={sectionBentoUpiRowStyle}>
           {processedUpiSlot}
         </View>
       )}
@@ -423,6 +861,64 @@ function SectionBento({
   )
 }
 
+// ---------------------------------------------------------------------------
+// DefaultBentoToggle — internal toggle cell rendered by `SectionBento` when no
+// `renderToggle` prop is provided. Uses a vertical `ListItem` so the cell
+// matches the visual rhythm of the surrounding nav items in every mode.
+//
+// Two icons (`ic_chevron_down` / `ic_chevron_up`) are used instead of a
+// rotating single icon, because the toggle cell is reconciled by position
+// (collapsed: end of row 1; expanded: end of last row), so any persistent
+// shared-value-driven rotation would lose its anchor across toggles.
+// ---------------------------------------------------------------------------
+type DefaultBentoToggleProps = {
+  expanded: boolean;
+  onPress: () => void;
+  modes: Record<string, any>;
+  moreLabel: string;
+  lessLabel: string;
+  moreIcon: string;
+  lessIcon: string;
+  /** How many additional actions become visible when expanding. Used in the a11y hint. */
+  extraCount: number;
+}
+
+function DefaultBentoToggle({
+  expanded,
+  onPress,
+  modes,
+  moreLabel,
+  lessLabel,
+  moreIcon,
+  lessIcon,
+  extraCount,
+}: DefaultBentoToggleProps) {
+  const label = expanded ? lessLabel : moreLabel
+  const iconName = expanded ? lessIcon : moreIcon
+  const accessibilityState = useMemo(() => ({ expanded }), [expanded])
+  const webAccessibilityProps = useMemo(
+    () => ({ ariaExpanded: expanded }),
+    [expanded]
+  )
+  const accessibilityHint = expanded
+    ? `Hides ${extraCount} additional ${extraCount === 1 ? 'action' : 'actions'}`
+    : `Shows ${extraCount} additional ${extraCount === 1 ? 'action' : 'actions'}`
+
+  return (
+    <ListItem
+      layout="Vertical"
+      supportText={label}
+      leading={<IconCapsule iconName={iconName} modes={modes} />}
+      modes={modes}
+      onPress={onPress}
+      accessibilityLabel={label}
+      accessibilityHint={accessibilityHint}
+      accessibilityState={accessibilityState}
+      webAccessibilityProps={webAccessibilityProps}
+    />
+  )
+}
+
 // Attach Bento as a property of Section using namespace pattern
 Section.Bento = SectionBento