jfs-components 0.1.50 → 0.1.54

package/lib/typescript/src/components/PlanComparisonCard/PlanComparisonCard.d.ts

@@ -48,6 +48,12 @@ export type PlanComparisonCardProps = {
     columns?: PlanComparisonColumn[];
     /** Feature rows compared across the plan columns. */
     rows?: PlanComparisonRow[];
+    /**
+     * Slot that replaces the default comparison table (Figma `Slot`). When
+     * omitted, the table is built from `columns` + `rows`. Header still
+     * renders from `columns`. `modes` are cascaded into slot children.
+     */
+    children?: React.ReactNode;
     /** Design token modes for theming (e.g. `{ "Color Mode": "Light" }`). */
     modes?: Modes;
     /** Override the outer container style. */
@@ -58,10 +64,11 @@ export type PlanComparisonCardProps = {
  * current plan against one or more alternative plans across a set of feature
  * rows. Implementation of Figma node `4498:2968` (`PlanComparisonCard`).
  *
- * Columns use a 1.8fr / 1fr flex ratio (label vs plan), matching the Figma grid.
+ * Structure: header (from `columns`) + Slot (default table from `rows`, or
+ * custom `children`). Columns use a 1.8fr / 1fr flex ratio (label vs plan).
  *
  * @component
  */
-declare function PlanComparisonCard({ columns, rows, modes, style, }: PlanComparisonCardProps): import("react/jsx-runtime").JSX.Element;
+declare function PlanComparisonCard({ columns, rows, children, modes, style, }: PlanComparisonCardProps): import("react/jsx-runtime").JSX.Element;
 export default PlanComparisonCard;
 //# sourceMappingURL=PlanComparisonCard.d.ts.map

package/lib/typescript/src/components/index.d.ts

@@ -9,8 +9,8 @@ export { default as BenefitCard, type BenefitCardProps, type BenefitCardItem } f
 export { default as BottomNav } from './BottomNav/BottomNav';
 export { default as BottomNavItem } from './BottomNavItem/BottomNavItem';
 export { default as BrandChip, type BrandChipProps } from './BrandChip/BrandChip';
-export { default as Button, type ButtonProps } from './Button/Button';
-export { default as Card } from './Card/Card';
+export { default as Button, type ButtonProps, type ButtonType } from './Button/Button';
+export { default as Card, type CardProps, type CardTextProps, type CardVariant, type CardVariantInput, CARD_MEDIA_ASPECT_RATIO, } from './Card/Card';
 export { default as CardAdvisory, type CardAdvisoryProps } from './CardAdvisory/CardAdvisory';
 export { default as CardBankAccount, type CardBankAccountProps, type CardBankAccountItem, } from './CardBankAccount/CardBankAccount';
 export { default as Carousel } from './Carousel/Carousel';

package/lib/typescript/src/icons/registry.d.ts

@@ -4,7 +4,7 @@
  * Auto-generated from SVG files in src/icons/
  * DO NOT EDIT MANUALLY - Run "npm run icons:generate" to regenerate
  *
- * Generated: 2026-07-25T10:59:52.406Z
+ * Generated: 2026-07-27T15:45:41.882Z
  */
 export declare const iconRegistry: Record<string, {
     path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jfs-components",
-  "version": "0.1.50",
+  "version": "0.1.54",
   "description": "React Native Jio Finance Components Library",
   "author": "sunshuaiqi@gmail.com",
   "license": "MIT",
@@ -17,7 +17,9 @@
     "src",
     "lib",
     "scripts/extract-figma-modes.js",
-    "D2C.md",
+    ".cursor/commands/D2C.md",
+    ".cursor/D2C-FLOW.md",
+    ".cursor/D2C-SCREEN.md",
     "CHANGELOG.md",
     "!**/__tests__",
     "!**/*.stories.*",

package/src/components/ActionFooter/ActionFooter.tsx

@@ -1,27 +1,48 @@
-import React, { useEffect, useMemo, useRef } from 'react'
+import React, { useEffect, useMemo, useState } from 'react'
 import {
-  Animated,
-  Keyboard,
   View,
+  Text,
   Platform,
-  type KeyboardEvent,
+  useWindowDimensions,
+  type LayoutChangeEvent,
+  type TextStyle,
   type ViewStyle,
   type StyleProp,
 } from 'react-native'
+import Animated, {
+  useAnimatedKeyboard,
+  useAnimatedStyle,
+  useSharedValue,
+} from 'react-native-reanimated'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { EMPTY_MODES, cloneChildrenWithModes, flattenChildren } from '../../utils/react-utils'
 import { boxShadow } from '../../utils/shadow'
+import ButtonGroup from '../ButtonGroup/ButtonGroup'
 import IconButton from '../IconButton/IconButton'
+import Slot from '../Slot/Slot'
+import Stack from '../Stack/Stack'
 import type { Modes } from '../../design-tokens'
 
 export type ActionFooterProps = {
   /**
    * Content to render inside the action footer slot.
-   * Typically includes `IconButton` and `Button` components.
-   * `IconButton` children keep their intrinsic square size; everything else
-   * is auto-stretched to share the remaining horizontal space equally.
+   *
+   * **Legacy (fully supported):** pass loose `IconButton` / `Button` children —
+   * IconButtons keep their intrinsic square size; everything else is
+   * auto-stretched to share the remaining horizontal space equally.
+   *
+   * **Figma shape (preferred for new code):** pass a single `ButtonGroup`
+   * (or `Stack` / `Slot`) that owns its own internal layout. ActionFooter will
+   * not re-stretch that composite — it only cascades `modes` and stretches it
+   * to full width.
    */
   children?: React.ReactNode
+  /**
+   * Optional centered title rendered above the action slot (Figma "title wrap").
+   * Omitted / empty string → title wrap is not mounted (identical to the
+   * pre-title layout tree for loose children).
+   */
+  title?: string
   /**
    * Mode configuration passed to the token resolver.
    * Automatically merged into every slot child via {@link cloneChildrenWithModes}
@@ -29,15 +50,30 @@ export type ActionFooterProps = {
    */
   modes?: Modes
   /**
-   * Optional style overrides for the outer container.
+   * Optional style overrides for the footer chrome (not the sticky shell).
    */
   style?: StyleProp<ViewStyle>
   /**
    * Accessibility label for the footer region (announced for the toolbar).
    */
   accessibilityLabel?: string
+  /**
+   * When `true` (default on native), the footer rides above the software
+   * keyboard by exactly the uncovered keyboard height. Web ignores this —
+   * there is no software keyboard inset to track.
+   */
+  avoidKeyboard?: boolean
 }
 
+const IS_WEB = Platform.OS === 'web'
+// Native sticky pinning is the product contract. Web/Storybook stays in normal
+// document flow so stories and docs layouts are not yanked out of their cards.
+const STICKY_BY_DEFAULT = !IS_WEB
+
+// Fallback row height used only until the first onLayout measurement lands.
+// Matches the common Button / IconButton intrinsic height in this library.
+const FALLBACK_ACTION_ROW_HEIGHT = 48
+
 // ---------------------------------------------------------------------------
 // Yoga-safe stretch
 // ---------------------------------------------------------------------------
@@ -66,175 +102,373 @@ const STRETCH_STYLE: ViewStyle = {
   minWidth: 0,
 }
 
+const COMPOSITE_STRETCH_STYLE: ViewStyle = {
+  alignSelf: 'stretch',
+  width: '100%',
+}
+
 // Upward drop shadow routed through the unified helper: native `boxShadow` on
 // web + RN 0.76+, legacy `shadow*` (iOS) / `elevation` (Android) on older RN.
+// Values match `actionFooter/shadow/primary|secondary/*` tokens.
 const SHADOW = boxShadow(
   '0px -12px 24px 0px rgba(12, 13, 16, 0.12), 0px -16px 48px 0px rgba(12, 13, 16, 0.16)',
   { elevation: 16 },
 )
 
-// The runtime token a slot child must equal (by reference) to be treated as
-// an IconButton. `IconButton` is exported wrapped in `React.memo`, so the
-// element.type identity comparison works for both `<IconButton />` from the
-// same module and any `React.memo`-wrapped re-export. The fallback check
-// (`type.type === IconButton`) catches one extra layer of `forwardRef` /
-// `memo` wrapping which can happen when consumers re-export the component.
-function isIconButtonElement(element: React.ReactElement<any>): boolean {
+const SHELL_STYLE: ViewStyle = {
+  // Fill the parent's cross axis without forcing callers to pass width: '100%'.
+  alignSelf: 'stretch',
+  // In a column flex parent, absorb free space above us so the footer sits on
+  // the bottom edge even when siblings above it are short. Harmless when a
+  // sibling already owns `flex: 1` (e.g. FullscreenModal's ScrollView).
+  marginTop: 'auto',
+}
+
+const PINNED_STYLE: ViewStyle = {
+  position: 'absolute',
+  left: 0,
+  right: 0,
+  bottom: 0,
+}
+
+function isElementOfType(
+  element: React.ReactElement<any>,
+  component: React.ComponentType<any>,
+): boolean {
   const t: any = element.type
-  if (t === IconButton) return true
-  if (t && typeof t === 'object' && t.type === IconButton) return true
+  if (t === component) return true
+  // `React.memo` / one extra `forwardRef` layer (re-exports).
+  if (t && typeof t === 'object' && t.type === component) return true
   return false
 }
 
+function isIconButtonElement(element: React.ReactElement<any>): boolean {
+  return isElementOfType(element, IconButton)
+}
+
 /**
- * ActionFooter — a sticky bottom container for primary screen actions.
- *
- * Layout contract:
- *   - The outer container stretches horizontally (`alignSelf: 'stretch'`) so
- *     it fills the parent regardless of whether the parent is a flex column,
- *     a ScrollView contentContainer, or a plain View.
- *   - The inner slot is a single row sized by its tallest child. It does NOT
- *     use `flex: 1` — that previously caused the row to collapse to zero on
- *     the first Yoga pass on native, taking the button labels with it.
- *   - `IconButton` children keep their intrinsic square size.
- *   - Every other child is auto-stretched with the Yoga-safe stretch style
- *     above so two `<Button>` siblings render at equal width on iOS, Android,
- *     and Web.
- *
- * The `modes` prop is automatically pushed down to every slot child via
- * {@link cloneChildrenWithModes}; explicit child-level modes win over the
- * parent's modes.
- *
- * @example
- * ```tsx
- * <ActionFooter modes={modes}>
- *   <IconButton iconName="ic_split" />
- *   <Button label="Request" modes={{ AppearanceBrand: 'Secondary' }} />
- *   <Button label="Pay" modes={{ AppearanceBrand: 'Primary' }} />
- * </ActionFooter>
- * ```
+ * Figma nests `Stack → Slot → ButtonGroup` under ActionFooter. In code, Slot
+ * still exists as a parallel primitive and Stack is the preferred successor —
+ * treat all three as "composites that own their own layout" so we never
+ * double-apply the loose-button stretch math and break their internals.
  */
-function ActionFooter({
-  children,
-  modes = EMPTY_MODES,
-  style,
-  accessibilityLabel,
-}: ActionFooterProps) {
-  // -------------------------------------------------------------------------
-  // Keep the footer locked in place behind the software keyboard (Android).
-  // -------------------------------------------------------------------------
-  //
-  // The Android activity is configured with `windowSoftInputMode="adjustResize"`,
-  // which shrinks the app window by the keyboard height when the keyboard
-  // opens. A bottom-anchored footer therefore gets lifted UP by the keyboard
-  // height — exactly the jump the design does not want.
-  //
-  // To counteract that, we translate the footer back DOWN by the same keyboard
-  // height so it visually stays exactly where it was (now sitting behind the
-  // keyboard). iOS does not resize the window for the keyboard, so the footer
-  // already stays put there; we only run this on Android to avoid pushing the
-  // footer off-screen on platforms that don't lift it in the first place.
-  const keyboardOffset = useRef(new Animated.Value(0)).current
-  useEffect(() => {
-    if (Platform.OS !== 'android') return undefined
-
-    const animateTo = (toValue: number, duration?: number) => {
-      Animated.timing(keyboardOffset, {
-        toValue,
-        // Match the OS keyboard animation so the resize and our counter-shift
-        // cancel out smoothly with no visible footer movement.
-        duration: typeof duration === 'number' && duration > 0 ? duration : 150,
-        useNativeDriver: true,
-      }).start()
-    }
+function isCompositeActionElement(element: React.ReactElement<any>): boolean {
+  return (
+    isElementOfType(element, ButtonGroup) ||
+    isElementOfType(element, Stack) ||
+    isElementOfType(element, Slot)
+  )
+}
 
-    const showSub = Keyboard.addListener('keyboardDidShow', (e: KeyboardEvent) => {
-      animateTo(e?.endCoordinates?.height ?? 0, e?.duration)
-    })
-    const hideSub = Keyboard.addListener('keyboardDidHide', (e: KeyboardEvent) => {
-      animateTo(0, e?.duration)
-    })
+type ResolvedChrome = {
+  containerStyle: ViewStyle
+  slotStyle: ViewStyle
+  titleWrapStyle: ViewStyle
+  titleStyle: TextStyle
+  estimatedHeight: number
+}
 
-    return () => {
-      showSub.remove()
-      hideSub.remove()
-    }
-  }, [keyboardOffset])
-
-  // All token reads collapsed into a single useMemo keyed on `modes`. With
-  // the shared `EMPTY_MODES` default this resolves once for the common path
-  // and never re-allocates the container/slot style objects between renders.
-  const { containerStyle, slotStyle } = useMemo(() => {
-    const backgroundColor =
-      (getVariableByName('actionFooter/background', modes) ?? '#ffffff') as string
-    const gap = (getVariableByName('actionFooter/gap', modes) ?? 8) as number
-    const paddingHorizontal =
-      (getVariableByName('actionFooter/padding/horizontal', modes) ?? 16) as number
-    const paddingTop = (getVariableByName('actionFooter/padding/top', modes) ?? 10) as number
-    const paddingBottom = (getVariableByName('actionFooter/padding/bottom', modes) ?? 41) as number
-
-    const container: ViewStyle = {
-      // `alignSelf: 'stretch'` is the cross-platform way to ask "fill the
-      // parent's cross axis" — in the common case (column parent) this gives
-      // us full-width without the caller needing to pass `width: '100%'`.
+function resolveChrome(modes: Modes): ResolvedChrome {
+  const backgroundColor =
+    (getVariableByName('actionFooter/background', modes) ?? '#ffffff') as string
+  const gap = (getVariableByName('actionFooter/gap', modes) ?? 8) as number
+  const paddingHorizontal =
+    (getVariableByName('actionFooter/padding/horizontal', modes) ?? 16) as number
+  const paddingTop = (getVariableByName('actionFooter/padding/top', modes) ?? 10) as number
+  const paddingBottom = (getVariableByName('actionFooter/padding/bottom', modes) ?? 41) as number
+  const borderRadius = (getVariableByName('actionFooter/radius', modes) ??
+    getVariableByName('radius/actionFooter', modes) ??
+    0) as number
+
+  // Title wrap reuses the Drawer title tokens in Figma (same binding ContentSheet
+  // uses) so the three bottom surfaces stay typographically aligned.
+  const titleColor = (getVariableByName('drawer/title/color', modes) ?? '#0d0d0f') as string
+  const titleSize = (getVariableByName('drawer/title/fontSize', modes) ?? 14) as number
+  const titleLineHeight = (getVariableByName('drawer/title/lineHeight', modes) ?? 17) as number
+  const titleFontFamily = (getVariableByName('drawer/title/fontFamily', modes) ??
+    'JioType Var') as string
+  const titleFontWeightRaw = getVariableByName('drawer/title/fontWeight', modes) ?? 700
+  const titleFontWeight = (
+    typeof titleFontWeightRaw === 'number' ? String(titleFontWeightRaw) : titleFontWeightRaw
+  ) as TextStyle['fontWeight']
+  const titleWrapPaddingTop =
+    (getVariableByName('drawer/titleWrap/padding/top', modes) ?? 16) as number
+  const titleWrapPaddingBottom =
+    (getVariableByName('drawer/titleWrap/padding/bottom', modes) ?? 8) as number
+  const titleWrapPaddingHorizontal =
+    (getVariableByName('drawer/titleWrap/padding/horizontal', modes) ?? 0) as number
+
+  return {
+    containerStyle: {
       alignSelf: 'stretch',
       backgroundColor,
       paddingLeft: paddingHorizontal,
       paddingRight: paddingHorizontal,
       paddingTop,
       paddingBottom,
+      borderRadius,
       ...SHADOW,
-    }
-
-    const slot: ViewStyle = {
+    },
+    slotStyle: {
       flexDirection: 'row',
       // Vertically center the IconButton against the slightly taller Buttons
       // so the row reads as a single optical baseline.
       alignItems: 'center',
+      alignSelf: 'stretch',
       gap,
-    }
+    },
+    titleWrapStyle: {
+      alignSelf: 'stretch',
+      alignItems: 'center',
+      justifyContent: 'center',
+      paddingTop: titleWrapPaddingTop,
+      paddingBottom: titleWrapPaddingBottom,
+      paddingHorizontal: titleWrapPaddingHorizontal,
+    },
+    titleStyle: {
+      color: titleColor,
+      fontSize: titleSize,
+      lineHeight: titleLineHeight,
+      fontFamily: titleFontFamily,
+      fontWeight: titleFontWeight,
+      textAlign: 'center',
+    },
+    // Seed the in-flow spacer so the first frame already reserves room and
+    // scroll siblings never paint under an unmeasured footer.
+    estimatedHeight: paddingTop + paddingBottom + FALLBACK_ACTION_ROW_HEIGHT,
+  }
+}
 
-    return { containerStyle: container, slotStyle: slot }
-  }, [modes])
-
-  // Process children once per (children, modes) tuple:
-  //   1. Flatten Fragments so each action is its own keyed sibling.
-  //   2. Push `modes` down so callers don't have to thread it manually.
-  //   3. Auto-stretch every non-IconButton with the Yoga-safe stretch style.
-  //
-  // The result identity is stable across re-renders when the inputs don't
-  // change, which keeps the `React.memo`-wrapped Button/IconButton children
-  // from re-rendering for no reason.
-  const enhancedChildren = useMemo(() => {
-    const flat = flattenChildren(children)
-    const withModes = cloneChildrenWithModes(flat, modes) as React.ReactNode[]
-    return withModes.map((child, index) => {
-      if (!React.isValidElement(child)) return child
-      const element = child as React.ReactElement<any>
-      if (isIconButtonElement(element)) return element
-      return React.cloneElement(element, {
-        key: element.key ?? `action-footer-item-${index}`,
-        style: [STRETCH_STYLE, element.props.style],
-      })
+/**
+ * Legacy loose-children path — identical stretch semantics to the original
+ * ActionFooter so existing call sites keep pixel parity.
+ */
+function enhanceLooseChildren(children: React.ReactNode, modes: Modes): React.ReactNode[] {
+  const flat = flattenChildren(children)
+  const withModes = cloneChildrenWithModes(flat, modes) as React.ReactNode[]
+  return withModes.map((child, index) => {
+    if (!React.isValidElement(child)) return child
+    const element = child as React.ReactElement<any>
+    if (isIconButtonElement(element)) return element
+    return React.cloneElement(element, {
+      key: element.key ?? `action-footer-item-${index}`,
+      style: [STRETCH_STYLE, element.props.style],
     })
-  }, [children, modes])
+  })
+}
 
-  return (
+function enhanceCompositeChild(
+  element: React.ReactElement<any>,
+  modes: Modes,
+): React.ReactElement<any> {
+  const childModes = element.props.modes ?? EMPTY_MODES
+  return React.cloneElement(element, {
+    modes: { ...modes, ...childModes },
+    style: [COMPOSITE_STRETCH_STYLE, element.props.style],
+  })
+}
+
+type ActionFooterChromeProps = ActionFooterProps & {
+  sticky: boolean
+  animatedStyle?: object
+}
+
+/**
+ * Shared chrome for web + native. On native (`sticky`), an in-flow shell locks
+ * the footer's height into the parent layout while the visible chrome is
+ * absolutely pinned to that shell's bottom edge — so the footer cannot scroll
+ * away or float mid-screen, and keyboard translation never collapses siblings.
+ */
+function ActionFooterChrome({
+  children,
+  title,
+  modes = EMPTY_MODES,
+  style,
+  accessibilityLabel,
+  sticky,
+  animatedStyle,
+}: ActionFooterChromeProps) {
+  const { containerStyle, slotStyle, titleWrapStyle, titleStyle, estimatedHeight } = useMemo(
+    () => resolveChrome(modes),
+    [modes],
+  )
+
+  const showTitle = typeof title === 'string' && title.length > 0
+
+  // Decide once whether the caller passed the Figma composite shape
+  // (ButtonGroup / Stack / Slot) or the legacy loose-button list. This keeps
+  // both APIs working without forcing a migration.
+  const { actionsBody, estimatedActionsHeight } = useMemo(() => {
+    const flat = flattenChildren(children)
+    const sole =
+      flat.length === 1 && React.isValidElement(flat[0])
+        ? (flat[0] as React.ReactElement<any>)
+        : null
+
+    if (sole && isCompositeActionElement(sole)) {
+      return {
+        actionsBody: enhanceCompositeChild(sole, modes),
+        estimatedActionsHeight: FALLBACK_ACTION_ROW_HEIGHT,
+      }
+    }
+
+    return {
+      actionsBody: <View style={slotStyle}>{enhanceLooseChildren(children, modes)}</View>,
+      estimatedActionsHeight: FALLBACK_ACTION_ROW_HEIGHT,
+    }
+  }, [children, modes, slotStyle])
+
+  const body = useMemo(() => {
+    if (!showTitle) {
+      // No title → identical tree shape to the pre-title ActionFooter for the
+      // loose-children path (just the actions row / composite). No extra Stack
+      // wrapper, so existing layouts cannot regress from an added gap node.
+      return actionsBody
+    }
+
+    // Figma: title wrap (sibling) + Stack → Slot → ButtonGroup. We mount a
+    // vertical Stack only when the title is present so the gap between title
+    // and actions is token-driven (`slot/gap` via Stack, cascaded modes).
+    return (
+      <Stack layoutDirection="vertical" fillWidth modes={modes}>
+        <View style={titleWrapStyle} accessibilityRole="header">
+          <Text style={titleStyle}>{title}</Text>
+        </View>
+        {actionsBody}
+      </Stack>
+    )
+  }, [showTitle, actionsBody, modes, title, titleWrapStyle, titleStyle])
+
+  const [footerHeight, setFooterHeight] = useState(
+    estimatedHeight + (showTitle ? 41 : 0),
+  )
+
+  // Token / title presence changes should re-seed the spacer immediately;
+  // the next onLayout then corrects to the true measured height.
+  useEffect(() => {
+    setFooterHeight(estimatedHeight + (showTitle ? 41 : 0))
+  }, [estimatedHeight, showTitle, estimatedActionsHeight])
+
+  const onFooterLayout = (event: LayoutChangeEvent) => {
+    const next = Math.ceil(event.nativeEvent.layout.height)
+    if (next > 0 && next !== footerHeight) {
+      setFooterHeight(next)
+    }
+  }
+
+  const chrome = (
     <Animated.View
-      style={[
-        containerStyle,
-        style,
-        // Counter-translate by the keyboard height on Android so `adjustResize`
-        // can't lift the footer above the keyboard (no-op on iOS/web where the
-        // value stays at 0).
-        { transform: [{ translateY: keyboardOffset }] },
-      ]}
+      style={[sticky ? PINNED_STYLE : null, containerStyle, style, animatedStyle]}
+      onLayout={sticky ? onFooterLayout : undefined}
       accessibilityRole="toolbar"
       accessibilityLabel={accessibilityLabel}
     >
-      <View style={slotStyle}>{enhancedChildren}</View>
+      {body}
     </Animated.View>
   )
+
+  if (!sticky) {
+    return chrome
+  }
+
+  return (
+    <View style={[SHELL_STYLE, { height: footerHeight }]} pointerEvents="box-none">
+      {chrome}
+    </View>
+  )
+}
+
+/**
+ * UI-thread keyboard tracking. Lifts by `keyboard.height - layoutShrink` so:
+ *   - iOS / Android `adjustPan` / `adjustNothing` → full keyboard height
+ *   - Android `adjustResize` (this app's default) → ~0 (window already shrank)
+ * Never double-counts, never depends on callers wiring KeyboardAvoidingView.
+ */
+function KeyboardAwareActionFooter(props: ActionFooterProps) {
+  const { height: windowHeight, width: windowWidth } = useWindowDimensions()
+  const maxWindowHeight = useSharedValue(windowHeight)
+  const layoutShrink = useSharedValue(0)
+  const keyboard = useAnimatedKeyboard()
+
+  // Orientation / split-screen width changes invalidate the height baseline.
+  // Intentionally NOT keyed on `windowHeight` — Android `adjustResize` shrinks
+  // height when the keyboard opens, and resetting the baseline there would
+  // collapse `layoutShrink` to 0 and double-lift the footer.
+  useEffect(() => {
+    maxWindowHeight.value = windowHeight
+    layoutShrink.value = 0
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- width-only baseline
+  }, [windowWidth])
+
+  // Track how much of the keyboard inset the window has already absorbed.
+  // Shared values keep the keyboard worklet free of React re-render lag.
+  useEffect(() => {
+    if (windowHeight > maxWindowHeight.value) {
+      maxWindowHeight.value = windowHeight
+    }
+    layoutShrink.value = Math.max(0, maxWindowHeight.value - windowHeight)
+  }, [windowHeight, maxWindowHeight, layoutShrink])
+
+  const animatedStyle = useAnimatedStyle(() => {
+    const lift = Math.max(0, keyboard.height.value - layoutShrink.value)
+    return {
+      transform: [{ translateY: -lift }],
+    }
+  })
+
+  return <ActionFooterChrome {...props} sticky animatedStyle={animatedStyle} />
+}
+
+/**
+ * ActionFooter — sticky bottom container for primary screen actions.
+ *
+ * Layout contract (native):
+ *   - Self-pins to the bottom of its flex-column screen via `marginTop: 'auto'`
+ *     plus an absolutely positioned chrome inside a height-locked shell.
+ *   - The shell keeps scroll/flex siblings from painting under the footer —
+ *     callers do not need to hand-maintain `paddingBottom`.
+ *   - Keyboard avoidance is owned here: the footer moves up by exactly the
+ *     keyboard height that layout has not already absorbed. Host
+ *     `KeyboardAvoidingView` is unnecessary and should not wrap this.
+ *
+ * Layout contract (web):
+ *   - In-flow stretch container (Storybook / docs friendly). No keyboard inset.
+ *
+ * Content contract:
+ *   - Optional centered `title` (Figma title wrap; Drawer title tokens).
+ *   - Loose `IconButton`/`Button` children keep the original equal-stretch row.
+ *   - A sole `ButtonGroup` / `Stack` / `Slot` child is treated as the Figma
+ *     composite and is not re-stretched internally.
+ *
+ * @example
+ * ```tsx
+ * // Legacy — still the recommended simple path
+ * <ActionFooter>
+ *   <IconButton iconName="ic_split" />
+ *   <Button label="Request" modes={{ AppearanceBrand: 'Secondary' }} />
+ *   <Button label="Pay" modes={{ AppearanceBrand: 'Primary' }} />
+ * </ActionFooter>
+ *
+ * // Figma shape + title
+ * <ActionFooter title="Confirm payment">
+ *   <ButtonGroup>
+ *     <Button label="Request" modes={{ AppearanceBrand: 'Secondary' }} />
+ *     <Button label="Pay" modes={{ AppearanceBrand: 'Primary' }} />
+ *   </ButtonGroup>
+ * </ActionFooter>
+ * ```
+ */
+function ActionFooter({
+  avoidKeyboard = true,
+  ...props
+}: ActionFooterProps) {
+  // Distinct component types keep `useAnimatedKeyboard` hook order stable
+  // (same pattern as ContentSheet). Web never mounts the keyboard path.
+  if (STICKY_BY_DEFAULT && avoidKeyboard) {
+    return <KeyboardAwareActionFooter {...props} />
+  }
+
+  return <ActionFooterChrome {...props} sticky={STICKY_BY_DEFAULT} />
 }
 
 export default React.memo(ActionFooter)