jfs-components 0.1.0 → 0.1.8

package/src/components/DropdownInput/DropdownInput.tsx

@@ -1,6 +1,8 @@
 import React, {
+    forwardRef,
     useCallback,
     useEffect,
+    useImperativeHandle,
     useMemo,
     useRef,
     useState,
@@ -27,6 +29,7 @@ import Icon from '../../icons/Icon'
 import SupportText from '../SupportText/SupportText'
 import type { SupportTextStatus } from '../SupportText/SupportTextIcon'
 import Dropdown, { DropdownItem, type DropdownItemProps } from '../Dropdown/Dropdown'
+import type { Modes } from '../../design-tokens'
 
 const IS_WEB = Platform.OS === 'web'
 
@@ -51,6 +54,28 @@ export type DropdownInputOption = {
 
 type Rect = { x: number; y: number; width: number; height: number }
 
+/**
+ * Imperative handle exposed via `ref`. Lets the consumer drive the dropdown
+ * from outside — e.g. close it when an Android hardware/system button is
+ * pressed, or open it programmatically from a sibling control.
+ */
+export type DropdownInputHandle = {
+    /** Opens the options menu (no-op when disabled / read-only). */
+    open: () => void
+    /** Closes the options menu. */
+    close: () => void
+    /** Toggles the options menu open/closed. */
+    toggle: () => void
+    /** Moves focus to the trigger (web). */
+    focus: () => void
+    /** Removes focus from the trigger (web). */
+    blur: () => void
+    /** Measures the trigger in window coordinates. */
+    measureInWindow: (
+        callback: (x: number, y: number, width: number, height: number) => void
+    ) => void
+}
+
 export type DropdownInputProps = {
     /** Label rendered above the input. */
     label?: string
@@ -131,7 +156,7 @@ export type DropdownInputProps = {
     /** Whether tapping the backdrop closes the menu. */
     closeOnBackdropPress?: boolean
     /** Modes for design token resolution. */
-    modes?: Record<string, any>
+    modes?: Modes
     /** Style overrides for the outermost wrapper. */
     style?: StyleProp<ViewStyle>
     /** Style overrides for the input row. */
@@ -152,7 +177,7 @@ export type DropdownInputProps = {
 // Token resolution
 // ---------------------------------------------------------------------------
 
-function useChevronTokens(modes: Record<string, any>) {
+function useChevronTokens(modes: Modes) {
     return useMemo(() => {
         const iconSize =
             parseInt(getVariableByName('input/iconSize', modes), 10) || 32
@@ -172,7 +197,7 @@ function toNumber(value: unknown, fallback: number): number {
     return fallback
 }
 
-function useFormFieldTokens(modes: Record<string, any>) {
+function useFormFieldTokens(modes: Modes) {
     return useMemo(() => {
         const labelColor =
             (getVariableByName('formField/label/color', modes) as string) ||
@@ -306,7 +331,7 @@ function collectOptionsFromChildren(
 // Component
 // ---------------------------------------------------------------------------
 
-function DropdownInput({
+const DropdownInput = forwardRef<DropdownInputHandle, DropdownInputProps>(function DropdownInput({
     label,
     placeholder = 'Select an option',
     items,
@@ -337,7 +362,7 @@ function DropdownInput({
     accessibilityHint,
     onFocus,
     onBlur,
-}: DropdownInputProps) {
+}: DropdownInputProps, ref: React.Ref<DropdownInputHandle>) {
     // ---------------- Modes ----------------
     const { modes: globalModes } = useTokens()
     const baseModes = useMemo(
@@ -496,6 +521,34 @@ function DropdownInput({
         [measure]
     )
 
+    // ---------------- Imperative handle ----------------
+    useImperativeHandle(
+        ref,
+        () => ({
+            open: () => {
+                if (isDisabled || isReadOnly) return
+                measure()
+                setOpenState(true)
+            },
+            close: closeMenu,
+            toggle: () => {
+                if (isDisabled || isReadOnly) return
+                measure()
+                toggleMenu()
+            },
+            focus: () => {
+                ;(triggerRef.current as unknown as { focus?: () => void })?.focus?.()
+            },
+            blur: () => {
+                ;(triggerRef.current as unknown as { blur?: () => void })?.blur?.()
+            },
+            measureInWindow: (callback) => {
+                triggerRef.current?.measureInWindow(callback)
+            },
+        }),
+        [isDisabled, isReadOnly, measure, setOpenState, closeMenu, toggleMenu]
+    )
+
     // ---------------- Popup positioning ----------------
     const [menuSize, setMenuSize] = useState<{
         width: number
@@ -829,7 +882,7 @@ function DropdownInput({
                 transparent
                 statusBarTranslucent
                 navigationBarTranslucent
-                animationType="fade"
+                animationType="none"
                 onRequestClose={closeMenu}
             >
                 <Pressable
@@ -862,7 +915,7 @@ function DropdownInput({
             </Modal>
         </View>
     )
-}
+})
 
 const webNoOutline: any = {
     outlineStyle: 'none',

package/src/components/EmptyState/EmptyState.tsx

@@ -5,6 +5,7 @@ import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import IconCapsule from '../IconCapsule/IconCapsule'
 import Button from '../Button/Button'
 import { EMPTY_MODES } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 export type EmptyStateProps = {
     /**
@@ -35,7 +36,7 @@ export type EmptyStateProps = {
     /**
      * Mode configuration for theming
      */
-    modes?: Record<string, any>;
+    modes?: Modes;
     style?: StyleProp<ViewStyle>;
     testID?: string;
 }

package/src/components/ExpandableCheckbox/ExpandableCheckbox.tsx

@@ -10,6 +10,7 @@ import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { EMPTY_MODES } from '../../utils/react-utils'
 import Checkbox from '../Checkbox/Checkbox'
 import Button from '../Button/Button'
+import type { Modes } from '../../design-tokens'
 
 export type ExpandableCheckboxProps = {
   /** Long text label rendered next to the checkbox. */
@@ -35,7 +36,7 @@ export type ExpandableCheckboxProps = {
   /** Number of lines to show when collapsed. Defaults to `1`. */
   collapsedLines?: number
   /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
-  modes?: Record<string, any>
+  modes?: Modes
   /** Override outer container styles. */
   style?: StyleProp<ViewStyle>
   /** Override the label text styles. */

package/src/components/FilterBar/FilterBar.tsx

@@ -3,12 +3,13 @@ import { View, type StyleProp, type ViewStyle } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import TextInput from '../TextInput/TextInput'
 import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 type RenderInputArgs = {
   placeholder: string;
   value: string;
   onChangeText?: ((text: string) => void) | undefined;
-  modes: Record<string, any>;
+  modes: Modes;
   accessibilityLabel: string;
   accessibilityHint?: string | undefined;
   onFocus?: (e: any) => void;
@@ -30,7 +31,7 @@ type FilterBarProps = {
    * respect the higher-level FilterBar API.
    */
   renderInput?: (args: RenderInputArgs) => React.ReactNode;
-  modes?: Record<string, any>;
+  modes?: Modes;
   style?: StyleProp<ViewStyle>;
   accessibilityLabel?: string;
   accessibilityHint?: string;

package/src/components/Form/Form.tsx

@@ -3,6 +3,7 @@ import { View, type StyleProp, type ViewStyle } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import { EMPTY_MODES } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 type FormContextValue = {
   validationErrors: Record<string, string | string[]>;
@@ -19,7 +20,7 @@ export type FormProps = {
   children: React.ReactNode;
   validationErrors?: Record<string, string | string[]>;
   onSubmit?: () => void;
-  modes?: Record<string, any>;
+  modes?: Modes;
   style?: StyleProp<ViewStyle>;
   accessibilityLabel?: string;
   testID?: string;

package/src/components/FormField/FormField.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useMemo, useState } from 'react'
+import React, { forwardRef, useCallback, useMemo, useState } from 'react'
 import {
   View,
   Text,
@@ -15,6 +15,7 @@ import SupportText from '../SupportText/SupportText'
 import type { SupportTextStatus } from '../SupportText/SupportTextIcon'
 import Icon from '../../icons/Icon'
 import { useFormContext } from '../Form/Form'
+import type { Modes } from '../../design-tokens'
 
 export type FormFieldType = 'text' | 'password' | 'email' | 'search' | 'number' | 'phone' | 'url'
 
@@ -76,7 +77,7 @@ export type FormFieldProps = {
   /** When true, focuses the input on mount. */
   autoFocus?: boolean
   /** Modes for design token resolution. */
-  modes?: Record<string, any>
+  modes?: Modes
   /** Style overrides for the outermost wrapper. */
   style?: StyleProp<ViewStyle>
   /** Style overrides for the input row container. */
@@ -116,7 +117,7 @@ function toFontWeight(value: unknown, fallback: TextStyle['fontWeight']): TextSt
   return fallback
 }
 
-function useFormFieldTokens(modes: Record<string, any>) {
+function useFormFieldTokens(modes: Modes) {
   return useMemo(() => {
     // Wrapper
     const gap = toNumber(getVariableByName('formField/gap', modes), 8)
@@ -300,7 +301,7 @@ function firstError(error: string | string[] | undefined): string | undefined {
 // Component
 // ---------------------------------------------------------------------------
 
-function FormField({
+const FormField = forwardRef<RNTextInput, FormFieldProps>(function FormField({
   label,
   placeholder,
   value,
@@ -328,7 +329,7 @@ function FormField({
   accessibilityLabel,
   accessibilityHint,
   testID,
-}: FormFieldProps) {
+}: FormFieldProps, ref: React.Ref<RNTextInput>) {
   // -- Form context integration -------------------------------------------
   const formCtx = useFormContext()
   const formError =
@@ -551,6 +552,7 @@ function FormField({
           </View>
         )}
         <RNTextInput
+          ref={ref}
           style={[inputTextStyles, inputTextStyle]}
           value={value ?? ''}
           onChangeText={handleChangeText}
@@ -589,6 +591,6 @@ function FormField({
       )}
     </View>
   )
-}
+})
 
 export default FormField

package/src/components/FullscreenModal/FullscreenModal.tsx

@@ -1,8 +1,9 @@
-import React, { useMemo, useRef } from 'react'
+import React, { useMemo, useRef, useState, useCallback } from 'react'
 import {
   View,
   Text,
   Animated,
+  type LayoutChangeEvent,
   type StyleProp,
   type ViewStyle,
   type TextStyle,
@@ -16,6 +17,7 @@ import Disclaimer from '../Disclaimer/Disclaimer'
 import IconButton from '../IconButton/IconButton'
 import ActionFooter from '../ActionFooter/ActionFooter'
 import Slot from '../Slot/Slot'
+import type { Modes } from '../../design-tokens'
 
 // ---------------------------------------------------------------------------
 // Forced modes
@@ -99,7 +101,7 @@ export type FullscreenModalProps = {
    * and `context5` is always forced to `'Fullscreen Modal'` (non-overridable).
    * The resolved modes cascade to the body, hero media, and the `ActionFooter`.
    */
-  modes?: Record<string, any>
+  modes?: Modes
   /** Style overrides for the outer container. */
   style?: StyleProp<ViewStyle>
   /** Style overrides for the transparent body wrapper. */
@@ -118,7 +120,7 @@ type HeroTextProps = {
   headline?: string
   supportingText?: string
   priceText?: string
-  modes: Record<string, any>
+  modes: Modes
 }
 
 function HeroText({ eyebrow, headline, supportingText, priceText, modes }: HeroTextProps) {
@@ -300,11 +302,57 @@ function FullscreenModal({
   )
   const heroTranslateY = useMemo(() => Animated.multiply(scrollY, -1), [scrollY])
 
-  const processedHeroMedia = useMemo(
-    () =>
-      heroMedia ? cloneChildrenWithModes(heroMedia, modes, FULLSCREEN_MODAL_FORCED_MODES) : null,
-    [heroMedia, modes]
-  )
+  // The hero media is a full-bleed background pinned to the top of the modal.
+  // Its wrapper is absolutely positioned (`top/left/right: 0`) so it never
+  // contributes to scroll height. We measure the modal's own width so we can
+  // give the hero media a DEFINITE { width, height } box (see
+  // `processedHeroMedia` below) — relying on the media's own `width: '100%'` +
+  // `aspectRatio` is unreliable inside an indefinite-height absolute box (RN's
+  // `<Image>` falls back to its intrinsic width and leaves a gap), so we size
+  // it explicitly here instead.
+  const [containerWidth, setContainerWidth] = useState(0)
+  const onContainerLayout = useCallback((e: LayoutChangeEvent) => {
+    const w = e.nativeEvent.layout.width
+    setContainerWidth((prev) => (prev !== w ? w : prev))
+  }, [])
+
+  const processedHeroMedia = useMemo(() => {
+    if (!heroMedia) return null
+    // Defer rendering the hero until we have measured the modal width. This
+    // matters for image sharpness: React Native decodes a bitmap once, on the
+    // first render, and caches it. If we rendered the media before knowing the
+    // final box, that first decode would be sized/sampled for the wrong box and
+    // the cached (downsampled) bitmap would then just be scaled up — blurry.
+    // Rendering only once the explicit { width, height } box is known means the
+    // very first decode is already full-resolution for the correct box.
+    if (containerWidth <= 0) return null
+    const withModes = cloneChildrenWithModes(heroMedia, modes, FULLSCREEN_MODAL_FORCED_MODES)
+
+    // Force the hero to fill the modal width edge to edge, top-aligned, with the
+    // height derived from the media's native aspect ratio.
+    //
+    // Why we inject explicit width/height instead of relying on the media's own
+    // `width: '100%'` + `aspectRatio`: the hero wrapper is absolutely positioned
+    // with an INDEFINITE height, and in that layout context React Native's
+    // `<Image>` falls back to its INTRINSIC width (so a 361px-wide asset renders
+    // 361px wide and leaves a gap on the right) rather than stretching to the
+    // parent. By computing `height = containerWidth / ratio` here and passing a
+    // DEFINITE { width, height } box (which makes `<Image>` skip aspectRatio and
+    // cover-fit into that exact box), the hero always fills the width with the
+    // correct ratio-derived height.
+    return React.Children.map(withModes, (child) => {
+      if (!React.isValidElement(child)) return child
+      const props = child.props as { ratio?: number; width?: unknown; height?: unknown }
+      const ratio = typeof props.ratio === 'number' && props.ratio > 0 ? props.ratio : undefined
+      // Only size media that exposes a numeric `ratio` and hasn't already been
+      // given an explicit box by the caller.
+      if (ratio == null || props.width != null || props.height != null) return child
+      return React.cloneElement(child, {
+        width: containerWidth,
+        height: containerWidth / ratio,
+      } as Partial<typeof props>)
+    })
+  }, [heroMedia, modes, containerWidth])
 
   const processedChildren = useMemo(
     () =>
@@ -369,7 +417,7 @@ function FullscreenModal({
   }
 
   return (
-    <View style={[rootStyle, style]} testID={testID}>
+    <View style={[rootStyle, style]} testID={testID} onLayout={onContainerLayout}>
       {/*
        * Layout model:
        *  - `processedHeroMedia` is a ROOT-LEVEL full-bleed background pinned to
@@ -387,7 +435,17 @@ function FullscreenModal({
        */}
       {processedHeroMedia ? (
         <Animated.View
-          style={[heroBackgroundStyle, { transform: [{ translateY: heroTranslateY }] }]}
+          style={[
+            heroBackgroundStyle,
+            // Give the absolute wrapper a DEFINITE width (the measured modal
+            // width) so the media's `width: '100%'` + `aspectRatio` resolves to
+            // a true edge-to-edge fill with a ratio-derived height, top-aligned.
+            // Before the first layout pass `containerWidth` is 0 — fall back to
+            // stretching via `left/right: 0` so there is no flash of a mis-sized
+            // image.
+            containerWidth > 0 ? { width: containerWidth } : null,
+            { transform: [{ translateY: heroTranslateY }] },
+          ]}
           pointerEvents="none"
         >
           {processedHeroMedia}

package/src/components/Gauge/Gauge.tsx

@@ -5,6 +5,7 @@ import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
 import SupportText, { type SupportTextProps } from '../SupportText/SupportText'
+import type { Modes } from '../../design-tokens'
 
 type GaugeBaseProps = Omit<React.ComponentProps<typeof View>, 'children' | 'style'>
 
@@ -32,7 +33,7 @@ export type GaugeProps = GaugeBaseProps & {
   /** Hides default support text when no custom readout slot is provided. */
   showSupportText?: boolean
   /** Design token modes forwarded to token lookups and slot children. */
-  modes?: Record<string, any>
+  modes?: Modes
   /** Slot rendered in the center of the gauge arc. Receives `modes` recursively. */
   children?: React.ReactNode
   /** Container style override. */

package/src/components/HStack/HStack.tsx

@@ -3,6 +3,7 @@ import { View, StyleProp, ViewStyle, ViewProps } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import { cloneChildrenWithModes, EMPTY_MODES } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 export interface HStackProps extends ViewProps {
     /**
@@ -35,7 +36,7 @@ export interface HStackProps extends ViewProps {
     /**
      * Modes object to override default variable values.
      */
-    modes?: Record<string, any>;
+    modes?: Modes;
 }
 
 /**

package/src/components/HoldingsCard/HoldingsCard.tsx

@@ -11,6 +11,7 @@ import {
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import Radio from '../Radio/Radio'
 import { EMPTY_MODES } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 export interface HoldingsCardDetailItem {
     label: string
@@ -33,7 +34,7 @@ export interface HoldingsCardProps {
     /** Called when the card is pressed (toggles selection). */
     onPress?: () => void
     /** Modes object for design-token resolution. */
-    modes?: Record<string, any>
+    modes?: Modes
     /** Custom style for the outer container. */
     style?: StyleProp<ViewStyle>
     /** Test ID for testing. */

package/src/components/Icon/Icon.tsx

@@ -10,6 +10,7 @@ import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
 import BaseIcon from '../../icons/Icon'
 import type { UnifiedSource } from '../../utils/MediaSource'
+import type { Modes } from '../../design-tokens'
 
 type IconProps = AccessibilityProps & {
   /**
@@ -43,7 +44,7 @@ type IconProps = AccessibilityProps & {
    * from the `icon/size` design token.
    */
   size?: number
-  modes?: Record<string, any>
+  modes?: Modes
   style?: StyleProp<ViewStyle>
 }
 
@@ -53,7 +54,7 @@ interface IconTokens {
   iconSize: number
 }
 
-function resolveIconTokens(modes: Record<string, any>): IconTokens {
+function resolveIconTokens(modes: Modes): IconTokens {
   const iconColor = (getVariableByName('icon/color', modes) || '#ad8444') as string
   const iconSize = (getVariableByName('icon/size', modes) || 18) as number
   const paddingLeft = (getVariableByName('icon/padding/left', modes) || 0) as number

package/src/components/IconButton/IconButton.tsx

@@ -14,6 +14,7 @@ import { EMPTY_MODES } from '../../utils/react-utils'
 import type { UnifiedSource } from '../../utils/MediaSource'
 import Skeleton from '../../skeleton/Skeleton'
 import { useSkeleton } from '../../skeleton/SkeletonGroup'
+import type { Modes } from '../../design-tokens'
 
 type IconButtonProps = SafePressableProps & {
   /** Built-in icon name from the registry (default state). */
@@ -26,7 +27,7 @@ type IconButtonProps = SafePressableProps & {
    * follows design tokens just like a built-in icon. See {@link UnifiedSource}.
    */
   source?: UnifiedSource;
-  modes?: Record<string, any>;
+  modes?: Modes;
   onPress?: () => void;
   disabled?: boolean;
   style?: StyleProp<ViewStyle>;
@@ -96,7 +97,7 @@ interface IconButtonTokens {
   iconSize: number;
 }
 
-function resolveIconButtonTokens(modes: Record<string, any>, disabled: boolean): IconButtonTokens {
+function resolveIconButtonTokens(modes: Modes, disabled: boolean): IconButtonTokens {
   const radiusRaw = (getVariableByName('iconButton/radius', modes) ?? 9999) as number
   const padding = (getVariableByName('iconButton/padding', modes) ?? 12) as number
   const backgroundColor = (getVariableByName('iconButton/background', modes) ?? '#cfa159') as string

package/src/components/IconCapsule/IconCapsule.tsx

@@ -5,6 +5,7 @@ import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import { EMPTY_MODES } from '../../utils/react-utils'
 import Icon from '../../icons/Icon'
 import type { UnifiedSource } from '../../utils/MediaSource'
+import type { Modes } from '../../design-tokens'
 
 type IconCapsuleProps = {
   iconName?: string;
@@ -17,7 +18,7 @@ type IconCapsuleProps = {
    * {@link UnifiedSource}.
    */
   source?: UnifiedSource;
-  modes?: Record<string, any>;
+  modes?: Modes;
   accessibilityLabel?: string;
   accessibilityRole?: string;
 } & React.ComponentProps<typeof View>;
@@ -28,7 +29,7 @@ interface IconCapsuleTokens {
   iconSize: number;
 }
 
-function resolveIconCapsuleTokens(modes: Record<string, any>): IconCapsuleTokens {
+function resolveIconCapsuleTokens(modes: Modes): IconCapsuleTokens {
   const size = (getVariableByName('iconCapsule/size', modes) || 42) as number
   const radiusRaw = (getVariableByName('iconCapsule/radius', modes) || 9999) as number
   const backgroundColor = (getVariableByName('iconCapsule/background', modes) || '#cfa159') as string

package/src/components/Image/Image.tsx

@@ -8,6 +8,8 @@ import {
   type ViewStyle,
   type ImageResizeMode,
 } from 'react-native'
+
+type ImageResizeMethod = 'auto' | 'resize' | 'scale' | 'none'
 import Skeleton from '../../skeleton/Skeleton'
 import { useSkeleton } from '../../skeleton/SkeletonGroup'
 
@@ -33,6 +35,21 @@ export type ImageProps = {
   ratio?: number | undefined
   /** How the image is fit inside its box. Defaults to `'cover'`. */
   resizeMode?: ImageResizeMode | undefined
+  /**
+   * (Android only) How the bitmap is resampled when the source resolution
+   * differs from the rendered box.
+   *
+   * RN's own default is `'auto'`, which for large source images silently picks
+   * `'resize'`: a pre-decode software downsample that DESTROYS detail and makes
+   * big hero/background images look soft/pixelated even when the asset is
+   * high-res. To avoid that, this component defaults to:
+   *   - `'none'` when an explicit `width` + `height` box is set (full-bleed
+   *     hero/background usage — full resolution, maximum sharpness), and
+   *   - `'scale'` otherwise (GPU scaling — high quality and memory-safe for
+   *     ordinary aspect-ratio images).
+   * Pass an explicit value to override. No-op on iOS/web.
+   */
+  resizeMethod?: ImageResizeMethod | undefined
   /**
    * Optional explicit width. If omitted and a `ratio` is set, the image
    * defaults to `width: '100%'` so it fills its parent.
@@ -96,6 +113,7 @@ function Image({
   imageSource,
   ratio = DEFAULT_RATIO,
   resizeMode = 'cover',
+  resizeMethod,
   width,
   height,
   borderRadius,
@@ -107,11 +125,16 @@ function Image({
 }: ImageProps) {
   const source = useMemo(() => normalizeSource(imageSource), [imageSource])
 
+  // Explicit { width, height } means a "fill an exact box" layout — typically a
+  // full-bleed hero/background where the asset is high-res and sharpness
+  // matters most. There, default to `'none'` (full-resolution, no pre-decode
+  // downsample) so detail is never thrown away. Aspect-ratio images keep the
+  // memory-safe `'scale'` default. A caller-supplied `resizeMethod` always wins.
+  const isExplicitBox = width != null && height != null
+  const effectiveResizeMethod: ImageResizeMethod =
+    resizeMethod ?? (isExplicitBox ? 'none' : 'scale')
+
   const layoutStyle: ImageStyle = useMemo(() => {
-    // If the caller has fully specified width AND height, they're doing a
-    // non-aspect layout (e.g. "fill the parent") — respect that and skip
-    // `aspectRatio` so it doesn't conflict.
-    const isExplicitBox = width != null && height != null
     const s: ImageStyle = {
       width: width ?? '100%',
       ...(isExplicitBox
@@ -120,7 +143,7 @@ function Image({
     }
     if (borderRadius != null) s.borderRadius = borderRadius
     return s
-  }, [ratio, width, height, borderRadius])
+  }, [ratio, width, height, borderRadius, isExplicitBox])
 
   const { active: groupActive } = useSkeleton()
   const isLoading = loading ?? groupActive
@@ -146,6 +169,7 @@ function Image({
       source={source}
       style={[layoutStyle, style]}
       resizeMode={resizeMode}
+      resizeMethod={effectiveResizeMethod}
       accessibilityLabel={accessibilityLabel}
       accessibilityElementsHidden={accessibilityElementsHidden}
       importantForAccessibility={importantForAccessibility}