From bef511fed9abc3a28576ab982c86931b686ce206 Mon Sep 17 00:00:00 2001
From: sonali-dudhia <sonali8849@gmail.com>
Date: Mon, 12 Oct 2026 15:40:40 +0530
Subject: [PATCH] docs(mobile/4): note inline handlers only work in Jump

Inline handlers like @press="$showSheet = false" work in Jump previews
but mobile-air doesn't support them, so copied examples leave modals and
sheets that won't close. Add a note under the first modal and
bottom-sheet example showing the method-based alternative.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../mobile/4/edge-components/bottom-sheet.md  | 20 +++++++++++++++++++
 .../docs/mobile/4/edge-components/modal.md    | 20 +++++++++++++++++++
 tests/Feature/DocumentationRenderingTest.php  | 18 +++++++++++++++++
 3 files changed, 58 insertions(+)

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 4bbdd035f..d49bf8a27 100644
--- a/resources/views/docs/mobile/4/edge-components/bottom-sheet.md
+++ b/resources/views/docs/mobile/4/edge-components/bottom-sheet.md
@@ -30,6 +30,26 @@ Per Material 3, the container color resolves from `theme.surface`. For a custom
 ```
 @endverbatim
 
+<aside>
+
+Inline handlers like `@press="$showSheet = true"` work in Jump previews. In your own app, call a method instead:
+
+```php
+public bool $showSheet = false;
+
+public function openSheet(): void { $this->showSheet = true; }
+public function closeSheet(): void { $this->showSheet = false; }
+```
+
+@verbatim
+```blade
+<native:button label="Open" @press="openSheet" />
+<native:bottom-sheet :visible="$showSheet" @dismiss="closeSheet">
+```
+@endverbatim
+
+</aside>
+
 ## Props
 
 - `visible` - Whether the sheet is shown (required, boolean)
diff --git a/resources/views/docs/mobile/4/edge-components/modal.md b/resources/views/docs/mobile/4/edge-components/modal.md
index f547d7e2d..59e4e35cd 100644
--- a/resources/views/docs/mobile/4/edge-components/modal.md
+++ b/resources/views/docs/mobile/4/edge-components/modal.md
@@ -31,6 +31,26 @@ Per Material 3, backdrop and surface colors come from `theme.background`. The cl
 ```
 @endverbatim
 
+<aside>
+
+Inline handlers like `@press="$showDetails = true"` work in Jump previews. In your own app, call a method instead:
+
+```php
+public bool $showDetails = false;
+
+public function openDetails(): void { $this->showDetails = true; }
+public function closeDetails(): void { $this->showDetails = false; }
+```
+
+@verbatim
+```blade
+<native:button label="View details" @press="openDetails" />
+<native:modal :visible="$showDetails" @dismiss="closeDetails">
+```
+@endverbatim
+
+</aside>
+
 ## Props
 
 - `visible` - Whether the modal is shown (required, boolean)
diff --git a/tests/Feature/DocumentationRenderingTest.php b/tests/Feature/DocumentationRenderingTest.php
index cf7f17d75..36b08de94 100644
--- a/tests/Feature/DocumentationRenderingTest.php
+++ b/tests/Feature/DocumentationRenderingTest.php
@@ -43,6 +43,24 @@ public function layouts_page_shows_example_component_tag_literally_instead_of_co
             ->assertSee('<x-layouts.app>');
     }
 
+    #[Test]
+    public function modal_and_bottom_sheet_pages_note_that_inline_handlers_only_work_in_jump(): void
+    {
+        $pages = [
+            'modal' => 'openDetails',
+            'bottom-sheet' => 'openSheet',
+        ];
+
+        foreach ($pages as $page => $method) {
+            $this->withoutVite()
+                ->get("/docs/mobile/4/edge-components/{$page}")
+                ->assertOk()
+                ->assertSee('work in Jump previews. In your own app, call a method instead', false)
+                ->assertSee("public function {$method}(): void", false)
+                ->assertSee("@press=&quot;{$method}&quot;", false);
+        }
+    }
+
     #[Test]
     public function every_documentation_page_renders_without_evaluating_example_variables(): void
     {