docs: say how to load an image in Card.Media

Author: raajnadar

CHANGELOG.md

@@ -12,7 +12,17 @@ Prior history: these packages were published as `@onlynative/*` through
 ## Unreleased
 
 **No breaking change.** One fix, two new `ListItem` props and one new
-`List` part in `components`, and one fix in the `llms.txt` files.
+`List` part in `components`, one fix in the `llms.txt` files, and one new
+docs section.
+
+### The Card page says how to load an image
+
+The library has no image component, and the Card page did not say so. A
+React Native `Image` in `Card.Media` has no loading state and no error
+state, so a slow or broken URL left the region empty. The new "Images"
+section says that `Card.Media` sizes the image and does not load it, and
+names `expo-image` with `placeholder`, `placeholderContentFit`,
+`transition` and `onError`. No code change.
 
 ### `List.Headline` for a long list in a `FlatList`
 

docs/docs/components/card.mdx

@@ -167,6 +167,31 @@ The card needs an `onPress` to become interactive. `Link` adds its own navigatio
 
 With `height` or `aspectRatio` set, each child fills the region, so a plain `Image` needs no style of its own. The children stack in order, so a second child is an overlay. A child's own `width` or `height` wins.
 
+### Images
+
+The library has no image component. `Card.Media` sizes the image component that you give it, and it does not load the image. A React Native `Image` has no loading state and no error state, so a slow or broken URL leaves the region empty.
+
+On Expo, use [`expo-image`](https://docs.expo.dev/versions/latest/sdk/image/):
+
+- `placeholder` shows while no image has loaded: a blurhash or a thumbhash from your data, or a local image.
+- `placeholderContentFit="cover"` gives the placeholder the same fit as the image. The default, `'scale-down'`, can flicker when the image replaces the placeholder.
+- `transition` fades the image in. A number is the time in milliseconds.
+- `onError` fires when the load fails. Show your own fallback there.
+
+```tsx
+import { Image } from 'expo-image'
+
+<Card.Media height={195}>
+  <Image
+    source={{ uri: article.imageUrl }}
+    placeholder={{ blurhash: article.blurhash }}
+    placeholderContentFit="cover"
+    contentFit="cover"
+    transition={200}
+  />
+</Card.Media>
+```
+
 ### Raw children still work
 
 The slots are additive. A card with raw children renders exactly as before and stays unpadded, so you own the spacing: