@farcaster/snap 2.5.1 → 2.6.1

package/dist/react-native/components/snap-paginator.js

@@ -0,0 +1,194 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useStateStore } from "@json-render/react-native";
+import { Children, useEffect, useMemo, useRef, useState, } from "react";
+import { Animated, Pressable, StyleSheet, View } from "react-native";
+import { ChevronLeft, ChevronRight } from "lucide-react-native";
+import { useSnapPalette } from "../use-snap-palette.js";
+import { useSnapTheme } from "../theme.js";
+import { clampPaginatorPage, pageFromValue, SNAP_PAGINATOR_PAGE_COUNT_PATH, SNAP_PAGINATOR_PAGE_PATH, } from "../../ui/paginator-state.js";
+function clampInitialPage(value, pageCount) {
+    if (typeof value !== "number" || !Number.isInteger(value))
+        return 0;
+    return Math.min(Math.max(value, 0), Math.max(pageCount - 1, 0));
+}
+export function SnapPaginator({ element: { props }, children, }) {
+    const pages = useMemo(() => Children.toArray(children), [children]);
+    const { colors, mode } = useSnapTheme();
+    const { accentHex } = useSnapPalette();
+    const { get, set } = useStateStore();
+    const initialPage = clampInitialPage(props.initialPage, pages.length);
+    const page = clampPaginatorPage(pageFromValue(get(SNAP_PAGINATOR_PAGE_PATH), initialPage), pages.length);
+    const activePage = Math.min(page, Math.max(pages.length - 1, 0));
+    const showControls = props.showControls !== false && pages.length > 1;
+    const showIndicators = props.showIndicators !== false && pages.length > 1;
+    const controlsPosition = props.controlsPosition === "top" ? "top" : "bottom";
+    const transition = props.transition === "fade" ||
+        props.transition === "scale" ||
+        props.transition === "none"
+        ? props.transition
+        : "slide";
+    const showControlBar = showControls || showIndicators;
+    const [transitionDirection, setTransitionDirection] = useState("next");
+    const pageAnim = useRef(new Animated.Value(1)).current;
+    const canGoPrev = activePage > 0;
+    const canGoNext = activePage < pages.length - 1;
+    const goToPage = (targetPage) => {
+        const nextPage = clampPaginatorPage(targetPage, pages.length);
+        if (nextPage !== activePage) {
+            setTransitionDirection(nextPage > activePage ? "next" : "previous");
+        }
+        set(SNAP_PAGINATOR_PAGE_PATH, nextPage);
+    };
+    const goPrev = () => goToPage(activePage - 1);
+    const goNext = () => goToPage(activePage + 1);
+    useEffect(() => {
+        if (pages.length === 0)
+            return;
+        const nextPage = clampPaginatorPage(pageFromValue(get(SNAP_PAGINATOR_PAGE_PATH), initialPage), pages.length);
+        if (get(SNAP_PAGINATOR_PAGE_PATH) !== nextPage) {
+            set(SNAP_PAGINATOR_PAGE_PATH, nextPage);
+        }
+        if (get(SNAP_PAGINATOR_PAGE_COUNT_PATH) !== pages.length) {
+            set(SNAP_PAGINATOR_PAGE_COUNT_PATH, pages.length);
+        }
+    }, [get, initialPage, pages.length, set]);
+    useEffect(() => {
+        if (transition === "none") {
+            pageAnim.setValue(1);
+            return;
+        }
+        pageAnim.setValue(0);
+        Animated.timing(pageAnim, {
+            toValue: 1,
+            duration: transition === "scale" ? 240 : transition === "slide" ? 260 : 180,
+            useNativeDriver: true,
+        }).start();
+    }, [activePage, pageAnim, transition]);
+    if (pages.length === 0)
+        return null;
+    const controlBar = showControlBar ? (_jsxs(View, { style: styles.footer, children: [showControls ? (_jsx(Pressable, { accessibilityRole: "button", accessibilityLabel: "Previous page", disabled: !canGoPrev, onPress: goPrev, style: [
+                    styles.control,
+                    {
+                        borderColor: colors.border,
+                        backgroundColor: colors.muted,
+                        opacity: canGoPrev ? 1 : 0.35,
+                    },
+                ], children: _jsx(ChevronLeft, { size: 15, color: colors.text }) })) : (_jsx(View, { style: styles.controlPlaceholder })), showIndicators ? (_jsx(View, { style: styles.indicators, children: pages.map((_, index) => {
+                    const current = index === activePage;
+                    return (_jsx(View, { accessibilityLabel: `Page ${index + 1}${current ? ", current" : ""}`, style: [
+                            styles.dot,
+                            current ? styles.dotCurrent : styles.dotInactive,
+                            {
+                                backgroundColor: current
+                                    ? accentHex
+                                    : mode === "dark"
+                                        ? "rgba(255,255,255,0.5)"
+                                        : "rgba(0,0,0,0.28)",
+                                borderColor: current
+                                    ? mode === "dark"
+                                        ? "rgba(255,255,255,0.18)"
+                                        : "rgba(0,0,0,0.12)"
+                                    : "transparent",
+                            },
+                        ] }, index));
+                }) })) : (_jsx(View, { style: styles.indicators })), showControls ? (_jsx(Pressable, { accessibilityRole: "button", accessibilityLabel: "Next page", disabled: !canGoNext, onPress: goNext, style: [
+                    styles.control,
+                    {
+                        borderColor: colors.border,
+                        backgroundColor: colors.muted,
+                        opacity: canGoNext ? 1 : 0.35,
+                    },
+                ], children: _jsx(ChevronRight, { size: 15, color: colors.text }) })) : (_jsx(View, { style: styles.controlPlaceholder }))] })) : null;
+    const animatedPageStyle = transition === "none"
+        ? undefined
+        : {
+            opacity: pageAnim.interpolate({
+                inputRange: [0, 1],
+                outputRange: [transition === "fade" ? 0.2 : 0.35, 1],
+            }),
+            transform: transition === "scale"
+                ? [
+                    {
+                        scale: pageAnim.interpolate({
+                            inputRange: [0, 1],
+                            outputRange: [0.94, 1],
+                        }),
+                    },
+                ]
+                : transition === "slide"
+                    ? [
+                        {
+                            translateX: pageAnim.interpolate({
+                                inputRange: [0, 1],
+                                outputRange: [
+                                    transitionDirection === "previous" ? -22 : 22,
+                                    0,
+                                ],
+                            }),
+                        },
+                        {
+                            scale: pageAnim.interpolate({
+                                inputRange: [0, 1],
+                                outputRange: [0.985, 1],
+                            }),
+                        },
+                    ]
+                    : [],
+        };
+    return (_jsxs(View, { style: styles.wrap, children: [controlsPosition === "top" ? controlBar : null, _jsx(Animated.View, { style: [
+                    styles.page,
+                    animatedPageStyle,
+                ], children: pages[activePage] }), controlsPosition === "bottom" ? controlBar : null] }));
+}
+const styles = StyleSheet.create({
+    wrap: {
+        width: "100%",
+        minWidth: 0,
+        gap: 8,
+    },
+    page: {
+        width: "100%",
+        minWidth: 0,
+    },
+    footer: {
+        minHeight: 28,
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: 8,
+    },
+    control: {
+        width: 28,
+        height: 28,
+        borderWidth: 1,
+        borderRadius: 6,
+        alignItems: "center",
+        justifyContent: "center",
+    },
+    controlPlaceholder: {
+        width: 28,
+        height: 28,
+    },
+    indicators: {
+        flex: 1,
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: 6,
+    },
+    dot: {
+        borderWidth: 0,
+        overflow: "hidden",
+    },
+    dotInactive: {
+        width: 8,
+        height: 8,
+        borderRadius: 4,
+    },
+    dotCurrent: {
+        width: 10,
+        height: 10,
+        borderRadius: 5,
+        borderWidth: 2,
+    },
+});

package/dist/react-native/components/snap-text.js

@@ -3,8 +3,8 @@ import { StyleSheet, Text, View } from "react-native";
 import { useSnapStackDirection } from "../stack-direction-context.js";
 import { useSnapTheme } from "../theme.js";
 const SIZE_STYLES = {
-    md: { fontSize: 16, lineHeight: 24 },
-    sm: { fontSize: 13, lineHeight: 18 },
+    md: { fontSize: 16, lineHeight: 22 },
+    sm: { fontSize: 13, lineHeight: 16 },
 };
 const WEIGHT_MAP = {
     bold: "700",
@@ -20,6 +20,7 @@ export function SnapText({ element: { props }, }) {
     const resolvedWeight = weight ? WEIGHT_MAP[weight] : sizeStyle?.fontWeight;
     const textAlign = align === "center" ? "center" : align === "right" ? "right" : "left";
     const inHorizontalStack = useSnapStackDirection() === "horizontal";
+    const maxLines = typeof props.maxLines === "number" ? props.maxLines : undefined;
     return (_jsx(View, { style: inHorizontalStack ? styles.wrapRow : styles.wrapCol, children: _jsx(Text, { style: [
                 styles.base,
                 {
@@ -29,7 +30,7 @@ export function SnapText({ element: { props }, }) {
                     fontWeight: resolvedWeight,
                     textAlign,
                 },
-            ], children: content }) }));
+            ], numberOfLines: maxLines, children: content }) }));
 }
 const styles = StyleSheet.create({
     /** Full width for vertical stacks (alignment / wrapping). */

package/dist/react-native/expand-state.d.ts

@@ -0,0 +1,19 @@
+export declare const SNAP_MAX_HEIGHT = 500;
+export type SnapExpansionOptions = {
+    contentHeight: number;
+    internalExpanded: boolean;
+    forceExpanded?: boolean;
+    onExpandPress?: (() => void) | undefined;
+    expandButtonLabel?: string | undefined;
+    showOverflowWarning?: boolean | undefined;
+};
+export type SnapExpansionState = {
+    expandable: boolean;
+    clipped: boolean;
+    showButton: boolean;
+    buttonLabel: string;
+    useInternalToggle: boolean;
+    showOverflowWarning: boolean;
+    maxHeight: number | undefined;
+};
+export declare function getSnapExpansionState({ contentHeight, internalExpanded, forceExpanded, onExpandPress, expandButtonLabel, showOverflowWarning, }: SnapExpansionOptions): SnapExpansionState;

package/dist/react-native/expand-state.js

@@ -0,0 +1,18 @@
+export const SNAP_MAX_HEIGHT = 500;
+export function getSnapExpansionState({ contentHeight, internalExpanded, forceExpanded = false, onExpandPress, expandButtonLabel, showOverflowWarning = false, }) {
+    const hostControlled = typeof onExpandPress === "function";
+    const overflowWarning = showOverflowWarning && !forceExpanded;
+    const expandable = !forceExpanded && !overflowWarning && contentHeight > SNAP_MAX_HEIGHT + 1;
+    const clipped = expandable && !internalExpanded;
+    const showButton = expandable;
+    const useInternalToggle = !hostControlled;
+    return {
+        expandable,
+        clipped,
+        showButton,
+        buttonLabel: clipped && expandButtonLabel ? expandButtonLabel : internalExpanded ? "Show less" : "Show more",
+        useInternalToggle,
+        showOverflowWarning: overflowWarning,
+        maxHeight: clipped ? SNAP_MAX_HEIGHT : undefined,
+    };
+}

package/dist/react-native/index.d.ts

@@ -7,7 +7,7 @@ import { hexToRgba } from "./use-snap-palette.js";
 export type { JsonValue, SnapPage, SnapActionHandlers } from "./types.js";
 export { useSnapTheme, hexToRgba };
 export type { SnapNativeColors };
-export declare function SnapCard({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
+export declare function SnapCard({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -27,4 +27,10 @@ export declare function SnapCard({ snap, handlers, loading, appearance, colors,
     plain?: boolean;
     /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
     loadingOverlay?: ReactNode;
+    /** When true, render full content height without 500px clipping or expand controls. */
+    forceExpanded?: boolean;
+    /** Custom label for the collapsed expand button. */
+    expandButtonLabel?: string;
+    /** Called from the collapsed expand button instead of toggling internal state. */
+    onExpandPress?: () => void;
 }): import("react").JSX.Element;

package/dist/react-native/index.js

@@ -7,9 +7,9 @@ import { SnapCardV2 } from "./v2/snap-view.js";
 // ─── Re-exports ───────────────────────────────────────
 export { useSnapTheme, hexToRgba };
 // ─── SnapCard (version-switching) ─────────────────────
-export function SnapCard({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
+export function SnapCard({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }) {
     if (snap.version === SPEC_VERSION_2) {
-        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
+        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress }));
     }
-    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
+    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress }));
 }

package/dist/react-native/snap-version-context.d.ts

@@ -0,0 +1,3 @@
+import type { SpecVersion } from "@farcaster/snap";
+export declare const SnapVersionProvider: any;
+export declare function useSnapVersion(): SpecVersion;

package/dist/react-native/snap-version-context.js

@@ -0,0 +1,6 @@
+import { createContext, useContext } from "react";
+const SnapVersionContext = createContext("1.0");
+export const SnapVersionProvider = SnapVersionContext.Provider;
+export function useSnapVersion() {
+    return useContext(SnapVersionContext);
+}

package/dist/react-native/snap-view-core.d.ts

@@ -3,7 +3,7 @@ import type { SnapPage, SnapActionHandlers } from "./types.js";
 export declare function applyStatePaths(model: Record<string, unknown>, changes: {
     path: string;
     value: unknown;
-}[] | Record<string, unknown>): void;
+}[] | Record<string, unknown> | null | undefined): void;
 export declare function resolveAccentHex(accent: string | undefined, appearance: "light" | "dark"): string;
 export declare function SnapViewCoreInner({ snap, handlers, loading, loadingOverlay, }: {
     snap: SnapPage;

package/dist/react-native/snap-view-core.js

@@ -4,11 +4,14 @@ import { SnapCatalogView } from "./catalog-renderer.js";
 import { ConfettiOverlay } from "./confetti-overlay.js";
 import { FireworksOverlay } from "./fireworks-overlay.js";
 import { useSnapTheme } from "./theme.js";
+import { SnapVersionProvider } from "./snap-version-context.js";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { ActivityIndicator, StyleSheet, View } from "react-native";
 import { DEFAULT_THEME_ACCENT, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, } from "@farcaster/snap";
 // ─── Shared helpers ──────────────────────────────────
 export function applyStatePaths(model, changes) {
+    if (!changes)
+        return;
     const entries = Array.isArray(changes)
         ? changes.map((c) => [c.path, c.value])
         : Object.entries(changes);
@@ -39,6 +42,26 @@ export function applyStatePaths(model, changes) {
         }
     }
 }
+function withDefaultElementProps(spec) {
+    if (!spec || typeof spec !== "object" || !("elements" in spec))
+        return spec;
+    const elements = spec.elements;
+    if (!elements || typeof elements !== "object")
+        return spec;
+    let changed = false;
+    const nextElements = {};
+    for (const [id, element] of Object.entries(elements)) {
+        if (element.props !== undefined) {
+            nextElements[id] = element;
+            continue;
+        }
+        changed = true;
+        nextElements[id] = { ...element, props: {} };
+    }
+    return changed
+        ? { ...spec, elements: nextElements }
+        : spec;
+}
 export function resolveAccentHex(accent, appearance) {
     const map = appearance === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
     const name = accent && Object.hasOwn(map, accent)
@@ -49,7 +72,7 @@ export function resolveAccentHex(accent, appearance) {
 // ─── Core rendering component (no validation) ────────
 export function SnapViewCoreInner({ snap, handlers, loading = false, loadingOverlay, }) {
     const { mode } = useSnapTheme();
-    const spec = snap.ui;
+    const spec = useMemo(() => withDefaultElementProps(snap.ui), [snap.ui]);
     const accentHex = resolveAccentHex(snap.theme?.accent, mode);
     const initialState = useMemo(() => ({
         ...(spec.state ?? {}),
@@ -150,9 +173,9 @@ export function SnapViewCoreInner({ snap, handlers, loading = false, loadingOver
                 ? loadingOverlay === undefined
                     ? (_jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex }))
                     : loadingOverlay
-                : null, _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
-                    applyStatePaths(stateRef.current, changes);
-                }, onAction: handleAction }, pageKey), showConfetti && _jsx(ConfettiOverlay, {}, confettiKey), showFireworks && _jsx(FireworksOverlay, {}, fireworksKey)] }));
+                : null, _jsx(SnapVersionProvider, { value: snap.version === "2.0" ? "2.0" : "1.0", children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
+                        applyStatePaths(stateRef.current, changes);
+                    }, onAction: handleAction }, pageKey) }), showConfetti && _jsx(ConfettiOverlay, {}, confettiKey), showFireworks && _jsx(FireworksOverlay, {}, fireworksKey)] }));
 }
 export function SnapLoadingOverlay({ appearance, accentHex, }) {
     return (_jsx(View, { style: [

package/dist/react-native/v1/snap-view.d.ts

@@ -16,7 +16,7 @@ export declare function SnapViewV1({ snap, handlers, loading, appearance, colors
     /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
     loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapCardV1({ snap, handlers, loading, appearance, colors, borderRadius, actionError, plain, loadingOverlay, }: {
+export declare function SnapCardV1({ snap, handlers, loading, appearance, colors, borderRadius, actionError, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -27,4 +27,10 @@ export declare function SnapCardV1({ snap, handlers, loading, appearance, colors
     plain?: boolean;
     /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
     loadingOverlay?: ReactNode;
+    /** When true, render full content height without 500px clipping or expand controls. */
+    forceExpanded?: boolean;
+    /** Custom label for the collapsed expand button. */
+    expandButtonLabel?: string;
+    /** Called from the collapsed expand button instead of toggling internal state. */
+    onExpandPress?: () => void;
 }): import("react").JSX.Element;

package/dist/react-native/v1/snap-view.js

@@ -3,7 +3,7 @@ import { useEffect, useState } from "react";
 import { View, Text, StyleSheet, Pressable } from "react-native";
 import { SnapThemeProvider, useSnapTheme } from "../theme.js";
 import { SnapLoadingOverlay, SnapViewCoreInner, resolveAccentHex, } from "../snap-view-core.js";
-const SNAP_MAX_HEIGHT = 500;
+import { getSnapExpansionState } from "../expand-state.js";
 // ─── SnapViewV1 (no validation) ──────────────────────
 export function SnapViewV1Inner({ snap, handlers, loading = false, loadingOverlay, }) {
     return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }));
@@ -12,7 +12,7 @@ export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark
     return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }) }));
 }
 // ─── SnapCardV1 (card frame with expandable clipping) ──
-function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, actionError, appearance, plain, loadingOverlay, }) {
+function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, actionError, appearance, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }) {
     const { colors, mode } = useSnapTheme();
     const accentHex = resolveAccentHex(snap.theme?.accent, mode);
     const [contentHeight, setContentHeight] = useState(0);
@@ -21,8 +21,14 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
         setIsExpanded(false);
         setContentHeight(0);
     }, [snap]);
-    const isExpandable = contentHeight > SNAP_MAX_HEIGHT + 1;
-    const isClipped = isExpandable && !isExpanded;
+    const expansion = getSnapExpansionState({
+        contentHeight,
+        internalExpanded: isExpanded,
+        forceExpanded,
+        onExpandPress,
+        expandButtonLabel,
+    });
+    const expandButtonInsideCard = typeof onExpandPress === "function";
     const isDark = mode === "dark";
     const pillBg = isDark ? "rgba(40,40,40,0.92)" : "rgba(255,255,255,0.92)";
     const pillBgPressed = isDark ? "rgba(60,60,60,0.95)" : "rgba(240,240,240,0.95)";
@@ -33,9 +39,11 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
                                 borderColor: colors.border,
                                 backgroundColor: colors.surface,
                             },
-                        ], children: [_jsx(View, { style: isClipped ? { maxHeight: SNAP_MAX_HEIGHT, overflow: "hidden" } : undefined, children: _jsx(View, { collapsable: false, onLayout: (event) => {
+                        ], children: [_jsx(View, { style: expansion.clipped
+                                    ? { maxHeight: expansion.maxHeight, overflow: "hidden" }
+                                    : undefined, children: _jsx(View, { collapsable: false, onLayout: (event) => {
                                         const nextHeight = Math.round(event.nativeEvent.layout.height);
-                                        setContentHeight((currentHeight) => isClipped
+                                        setContentHeight((currentHeight) => expansion.clipped
                                             ? Math.max(currentHeight, nextHeight)
                                             : currentHeight === nextHeight
                                                 ? currentHeight
@@ -44,15 +52,22 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
                                 ? loadingOverlay === undefined
                                     ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
                                     : loadingOverlay
-                                : null] }), isExpandable ? (_jsx(View, { pointerEvents: "box-none", style: cardStyles.expandFloat, children: _jsx(Pressable, { style: ({ pressed }) => [
+                                : null] }), expansion.showButton ? (_jsx(View, { pointerEvents: "box-none", style: expandButtonInsideCard
+                            ? cardStyles.expandFloatInset
+                            : cardStyles.expandFloat, children: _jsx(Pressable, { style: ({ pressed }) => [
                                 cardStyles.expandButton,
                                 {
                                     backgroundColor: pressed ? pillBgPressed : pillBg,
                                     borderColor: colors.border,
                                 },
                             ], onPress: () => {
-                                setIsExpanded((value) => !value);
-                            }, children: _jsx(Text, { style: [cardStyles.expandButtonText, { color: colors.text }], children: isExpanded ? "Show less" : "Show more" }) }) })) : null] }), actionError && (_jsx(Text, { style: [
+                                if (expansion.useInternalToggle) {
+                                    setIsExpanded((value) => !value);
+                                }
+                                else {
+                                    onExpandPress?.();
+                                }
+                            }, children: _jsx(Text, { style: [cardStyles.expandButtonText, { color: colors.text }], children: expansion.buttonLabel }) }) })) : null] }), actionError && (_jsx(Text, { style: [
                     cardStyles.actionError,
                     {
                         color: appearance === "dark"
@@ -61,8 +76,8 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
                     },
                 ], children: actionError }))] }));
 }
-export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, actionError, plain = false, loadingOverlay, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV1Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay }) }));
+export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, actionError, plain = false, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV1Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress }) }));
 }
 const cardStyles = StyleSheet.create({
     frameRing: { alignSelf: "stretch" },
@@ -77,6 +92,15 @@ const cardStyles = StyleSheet.create({
         alignItems: "center",
         justifyContent: "center",
     },
+    expandFloatInset: {
+        position: "absolute",
+        left: 0,
+        right: 0,
+        bottom: 10,
+        height: 28,
+        alignItems: "center",
+        justifyContent: "center",
+    },
     expandButton: {
         minWidth: 92,
         alignItems: "center",

package/dist/react-native/v2/snap-view.d.ts

@@ -21,7 +21,7 @@ export declare function SnapViewV2({ snap, handlers, loading, appearance, colors
     /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
     loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapCardV2({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
+export declare function SnapCardV2({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -35,4 +35,10 @@ export declare function SnapCardV2({ snap, handlers, loading, appearance, colors
     plain?: boolean;
     /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
     loadingOverlay?: ReactNode;
+    /** When true, render full content height without 500px clipping or expand controls. */
+    forceExpanded?: boolean;
+    /** Custom label for the collapsed expand button. */
+    expandButtonLabel?: string;
+    /** Called from the collapsed expand button instead of toggling internal state. */
+    onExpandPress?: () => void;
 }): import("react").JSX.Element;