From a80addff9648f188bfa89450473206016fca41e5 Mon Sep 17 00:00:00 2001
From: Simon Hamp <simon.hamp@me.com>
Date: Fri, 23 Oct 2026 13:25:47 +0100
Subject: [PATCH 1/2] Document image fit names and how each fit draws

The image page said fit modes 0/1 and 2/3 each draw the same way, which
was only ever true on iOS and stopped being true with mobile-ui#153.
Describe the four fits as they draw now on both platforms, the names and
ImageFit cases fit takes from 4.7 (mobile-air#572), and that an image
with a width and no height sizes from its aspect ratio. The examples use
the names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../docs/mobile/4/edge-components/image.md    | 34 ++++++++++++-------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/resources/views/docs/mobile/4/edge-components/image.md b/resources/views/docs/mobile/4/edge-components/image.md
index 86271d97c..bd9a354b4 100644
--- a/resources/views/docs/mobile/4/edge-components/image.md
+++ b/resources/views/docs/mobile/4/edge-components/image.md
@@ -13,7 +13,7 @@ Displays an image from a URL. Loaded asynchronously by the native platform — `
     src="https://picsum.photos/seed/nativephp/400/300"
     :width="200"
     :height="150"
-    :fit="2"
+    fit="cover"
     class="rounded-xl"
 />
 ```
@@ -24,17 +24,25 @@ Displays an image from a URL. Loaded asynchronously by the native platform — `
 All [shared layout and style attributes](layout) are supported, plus:
 
 - `src` - Image URL (required, string)
-- `fit` - Content fit mode (optional, int, default: `1`):
-    - `0` / `1` — fit (scale to fit within bounds, preserving aspect ratio)
-    - `2` / `3` — fill (scale to fill bounds, cropping excess)
+- `fit` <x-docs.version-badge changed="4.7" /> - How the image fills its frame, following CSS `object-fit`.
+  Takes `none`, `contain`, `cover` or `fill`, an `ImageFit` case, or the integer `0`/`1`/`2`/`3` (optional,
+  default: `contain`):
+    - `none` (`0`) - Draws the image at its own size, one image pixel per point on iOS or per dp on Android,
+      centered and cropped to the frame
+    - `contain` (`1`) - Scales the image to fit inside the frame, keeping its aspect ratio, and centers it
+    - `cover` (`2`) - Scales the image to fill the frame, keeping its aspect ratio, centered and cropped
+    - `fill` (`3`) - Stretches the image to the frame's exact width and height, ignoring its aspect ratio
 - `tint-color` - Apply a color tint as hex string (optional)
 - `alt` - Accessibility alt text (optional). When set, screen readers announce the image with this label; when
   omitted, the image is treated as decorative and hidden from VoiceOver/TalkBack. See [Accessibility](../digging-deeper/accessibility)
 
 <aside>
 
-The renderer collapses fit modes to two effective behaviors: `fit` and `fill`. Modes `0`/`1` both render as fit;
-`2`/`3` both render as fill. Use `:fit="1"` for "scale within" and `:fit="2"` for "scale to fill / crop".
+Before 4.7, `fit` only takes the integer. The `object-none`, `object-contain`, `object-cover` and `object-fill`
+[classes](layout#supported-tailwind-classes) set it too.
+
+An image with a width but no height, like a `w-full` image in a list, takes its height from the image's aspect
+ratio. That holds for every `fit`.
 
 `<native:image />` is a self-closing element. It does not accept children.
 
@@ -46,7 +54,7 @@ The renderer collapses fit modes to two effective behaviors: `fit` and `fill`. M
 
 @verbatim
 ```blade
-<native:image src="https://picsum.photos/seed/hero/800/400" class="w-full rounded-xl" :height="200" :fit="2" />
+<native:image src="https://picsum.photos/seed/hero/800/400" class="w-full rounded-xl" :height="200" fit="cover" />
 ```
 @endverbatim
 
@@ -58,7 +66,7 @@ The renderer collapses fit modes to two effective behaviors: `fit` and `fill`. M
     src="https://i.pravatar.cc/128?img=12"
     :width="64"
     :height="64"
-    :fit="2"
+    fit="cover"
     class="rounded-full"
 />
 ```
@@ -72,7 +80,7 @@ The renderer collapses fit modes to two effective behaviors: `fit` and `fill`. M
     src="https://www.php.net/images/logos/new-php-logo.png"
     :width="80"
     :height="42"
-    :fit="1"
+    fit="contain"
     tint-color="#7C3AED"
 />
 ```
@@ -91,7 +99,7 @@ this example is shown as code only.
 @verbatim
 ```blade
 <native:column class="w-full p-2 rounded-2xl border border-theme-outline bg-theme-surface">
-    <native:image src="https://picsum.photos/seed/cover/800/360" class="w-full rounded-xl" :height="180" :fit="2" />
+    <native:image src="https://picsum.photos/seed/cover/800/360" class="w-full rounded-xl" :height="180" fit="cover" />
     <native:column class="p-3 gap-2">
         <native:text class="text-lg font-bold text-theme-on-surface">Article Title</native:text>
         <native:text class="text-base text-theme-on-surface-variant">A brief description of the article.</native:text>
@@ -104,12 +112,14 @@ this example is shown as code only.
 
 ```php
 use Native\Mobile\Edge\Elements\Image;
+use Native\Mobile\Edge\Enums\ImageFit;
 
 Image::make('https://picsum.photos/seed/nativephp/400/300')
-    ->fit(2)
+    ->fit(ImageFit::Cover)
     ->tintColor('#7C3AED');
 ```
 
 - `make(string $src = '')` - Create an image with a source URL
-- `fit(int $mode)` - `0`/`1` = fit, `2`/`3` = fill
+- `fit(int|string|ImageFit $mode)` <x-docs.version-badge changed="4.7" /> - `none`/`contain`/`cover`/`fill`, an
+  `ImageFit` case, or `0`/`1`/`2`/`3`
 - `tintColor(string $hex)` - Apply a color tint

From 6cf5b64da15dc28b654d686864fcbeb3c9357475 Mon Sep 17 00:00:00 2001
From: Simon Hamp <simon.hamp@me.com>
Date: Fri, 23 Oct 2026 13:30:52 +0100
Subject: [PATCH 2/2] Use fit names in the other image examples

Modal, bottom sheet, carousel, lazy grid and stack examples still passed
:fit="1" and :fit="2". Switch them to fit="contain" and fit="cover" so
every v4 page uses the names the image page documents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 resources/views/docs/mobile/4/edge-components/bottom-sheet.md | 2 +-
 resources/views/docs/mobile/4/edge-components/carousel.md     | 2 +-
 resources/views/docs/mobile/4/edge-components/lazy-grid.md    | 4 ++--
 resources/views/docs/mobile/4/edge-components/modal.md        | 2 +-
 resources/views/docs/mobile/4/edge-components/stack.md        | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/resources/views/docs/mobile/4/edge-components/bottom-sheet.md b/resources/views/docs/mobile/4/edge-components/bottom-sheet.md
index c8e9f19ac..2a1928343 100644
--- a/resources/views/docs/mobile/4/edge-components/bottom-sheet.md
+++ b/resources/views/docs/mobile/4/edge-components/bottom-sheet.md
@@ -130,7 +130,7 @@ Accepts any EDGE elements as children. The children are rendered inside the shee
     <native:button label="Preview" @press="$showPreview = true" />
 
     <native:bottom-sheet :visible="$showPreview" @dismiss="$showPreview = false" detents="0.4">
-        <native:image src="{{ $previewUrl }}" class="w-full h-full" :fit="2" />
+        <native:image src="{{ $previewUrl }}" class="w-full h-full" fit="cover" />
     </native:bottom-sheet>
 </native:column>
 ```
diff --git a/resources/views/docs/mobile/4/edge-components/carousel.md b/resources/views/docs/mobile/4/edge-components/carousel.md
index 32e93413a..413af78ec 100644
--- a/resources/views/docs/mobile/4/edge-components/carousel.md
+++ b/resources/views/docs/mobile/4/edge-components/carousel.md
@@ -70,7 +70,7 @@ wrapping a [`<native:row>`](row).
                 <native:column class="w-full h-full rounded-full bg-theme-surface-variant items-center justify-center">
                     <native:text class="text-base font-bold text-theme-on-surface-variant">{{ $contact->initials }}</native:text>
                 </native:column>
-                <native:image src="{{ $contact->avatar }}" :width="64" :height="64" class="rounded-full" :fit="2" alt="{{ $contact->name }}" />
+                <native:image src="{{ $contact->avatar }}" :width="64" :height="64" class="rounded-full" fit="cover" alt="{{ $contact->name }}" />
             </native:stack>
             <native:text class="text-xs text-theme-on-surface">{{ $contact->name }}</native:text>
         </native:column>
diff --git a/resources/views/docs/mobile/4/edge-components/lazy-grid.md b/resources/views/docs/mobile/4/edge-components/lazy-grid.md
index d2991899e..a7c5e5f37 100644
--- a/resources/views/docs/mobile/4/edge-components/lazy-grid.md
+++ b/resources/views/docs/mobile/4/edge-components/lazy-grid.md
@@ -61,7 +61,7 @@ it be the screen's scroll container) to keep lazy composition.
 <native:lazy-grid :columns="3" :gap="2" class="w-full">
     @foreach (range(1, 9) as $i)
         <native:column :height="120">
-            <native:image src="https://picsum.photos/seed/grid{{ $i }}/300" class="w-full h-full" :fit="2" />
+            <native:image src="https://picsum.photos/seed/grid{{ $i }}/300" class="w-full h-full" fit="cover" />
         </native:column>
     @endforeach
 </native:lazy-grid>
@@ -99,7 +99,7 @@ width.
 <native:lazy-grid :columns="2" :gap="12" horizontal>
     @foreach($products as $product)
         <native:column :width="160" class="p-3 gap-2 rounded-lg bg-theme-surface">
-            <native:image src="{{ $product->image }}" :width="136" :height="100" class="rounded-lg" :fit="2" />
+            <native:image src="{{ $product->image }}" :width="136" :height="100" class="rounded-lg" fit="cover" />
             <native:text class="text-sm font-medium">{{ $product->name }}</native:text>
         </native:column>
     @endforeach
diff --git a/resources/views/docs/mobile/4/edge-components/modal.md b/resources/views/docs/mobile/4/edge-components/modal.md
index f547d7e2d..7aec6c4aa 100644
--- a/resources/views/docs/mobile/4/edge-components/modal.md
+++ b/resources/views/docs/mobile/4/edge-components/modal.md
@@ -71,7 +71,7 @@ Programmatically setting `visible` to `false` from PHP does not fire the callbac
 
     <native:modal :visible="$showImage" @dismiss="$showImage = false">
         <native:column class="w-full h-full" center>
-            <native:image src="{{ $previewUrl }}" class="w-full" :fit="1" />
+            <native:image src="{{ $previewUrl }}" class="w-full" fit="contain" />
         </native:column>
     </native:modal>
 </native:column>
diff --git a/resources/views/docs/mobile/4/edge-components/stack.md b/resources/views/docs/mobile/4/edge-components/stack.md
index f4a89d754..c9f4de6b3 100644
--- a/resources/views/docs/mobile/4/edge-components/stack.md
+++ b/resources/views/docs/mobile/4/edge-components/stack.md
@@ -78,7 +78,7 @@ In a real app the base layer would typically be a `<native:image>` avatar (e.g.
 @verbatim
 ```blade
 <native:stack class="w-full h-[250] rounded-2xl">
-    <native:image src="https://picsum.photos/seed/banner/800/500" class="w-full h-full" :fit="2" />
+    <native:image src="https://picsum.photos/seed/banner/800/500" class="w-full h-full" fit="cover" />
     <native:column class="w-full h-full justify-end p-4 bg-black/40">
         <native:text class="text-2xl font-bold text-white">Featured Article</native:text>
         <native:text class="text-base text-white">Read more about this topic</native:text>