docs(mobile/v4): native-ui component audit — close the gaps between code and docs

resources/views/docs/mobile/4/digging-deeper/accessibility.md

@@ -20,7 +20,7 @@ Every element accepts two attributes:
 - `a11y-hint` - Supplementary usage guidance, announced after the label (e.g. "Double-tap to open settings").
 
 @verbatim
-```blade
+```blade static
 <native:button icon="gear" a11y-label="Settings" @press="openSettings" />
 <native:slider :value="$volume" a11y-label="Volume" a11y-hint="Adjusts playback volume" />
 ```
@@ -48,7 +48,7 @@ isn't descriptive enough on its own.
 mystery to screen reader users.
 
 @verbatim
-```blade
+```blade static
 {{-- Bad: VoiceOver has nothing meaningful to announce --}}
 <native:button icon="trash" variant="destructive" @press="deleteItem" />
 
@@ -63,7 +63,7 @@ Standalone `<native:icon />` elements are **decorative by default** — they are
 unless you give them an `a11y-label`. If an icon conveys meaning on its own (or is tappable), label it:
 
 @verbatim
-```blade
+```blade static
 <native:icon name="wifi_off" a11y-label="No internet connection" />
 ```
 @endverbatim
@@ -72,7 +72,7 @@ Images take an `alt` attribute, mirroring the web. With `alt`, the image is anno
 is treated as decorative and skipped:
 
 @verbatim
-```blade
+```blade static
 <native:image src="{{ $product->photo }}" alt="{{ $product->name }}" :height="200" />
 ```
 @endverbatim
@@ -82,7 +82,7 @@ is treated as decorative and skipped:
 The tappable trailing icon button on a [list item](../edge-components/list) takes its own label via `trailing-a11y-label`:
 
 @verbatim
-```blade
+```blade static
 <native:list-item
     headline="Backups"
     trailingIconButton="info"

resources/views/docs/mobile/4/digging-deeper/data-binding.md

@@ -10,7 +10,7 @@ Livewire's `wire:model`. Type into a field, toggle a switch, drag a slider, and
 PHP side; change the property in PHP and the control reflects it on the next render.
 
 @verbatim
-```blade
+```blade static
 <native:text-input native:model="name" placeholder="Your name" />
 ```
 @endverbatim
@@ -52,7 +52,7 @@ useful for text inputs where syncing on every character is wasteful:
 | `native:model.debounce.300ms` | After the user stops changing it for the given delay. |
 
 @verbatim
-```blade
+```blade static
 {{-- Sync only when the user leaves the field --}}
 <native:text-input native:model.blur="email" />
 
@@ -87,7 +87,7 @@ properties, derive the rest with computed methods, and let the UI re-render itse
 something other than a public property — set the value and change handler directly:
 
 @verbatim
-```blade
+```blade static
 <native:text-input :value="$name" @change="rename" />
 ```
 @endverbatim

resources/views/docs/mobile/4/digging-deeper/gestures.md

@@ -17,10 +17,10 @@ If you've used Reanimated in React Native, this is the same idea.
 Create one in PHP with `SharedValue::make($initial)`, bind it to a gesture, and read it from any animatable prop:
 
 @verbatim
-```blade
+```blade static
 @php $drag = \Native\Mobile\Edge\SharedValue::make(); @endphp
 
-<native:gesture-area :pan-y="$drag" @drag-end="onRelease">
+<native:gesture-area :pan-y="$drag">
     <native:column
         :translate-y="$drag"
         :opacity="$drag->interpolate([0, 200], [1, 0])"
@@ -49,26 +49,17 @@ derived value, so one gesture can drive many props differently:
 $drag->interpolate([0, 200], [1, 0]);  // 0→1, 200→0, fully faded past 200
 ```
 
-Animatable props that accept a shared value: `translate-x`, `translate-y`, `scale`, `rotate`, and `opacity`.
-
-## Reacting when the gesture ends
-
-Per-frame values stay on the native side, but you often need PHP to make a decision when the user lets go — commit
-or snap back. The [`<native:gesture-area>`](../edge-components/gesture-area) fires `@drag-end` with the final
-value:
+Formulas are chainable — each call returns a new derived value, so you can stack them:
 
 ```php
-public function onRelease(float $value): void
-{
-    if ($value > 150) {
-        $this->dismiss();      // dragged far enough — commit
-    }
-    // otherwise the view springs back to its resting position
-}
+$drag->clamp(0, 200)->multiply(0.5)->add(20);
 ```
 
-Call `->value()` on a shared value inside such a handler to read its PHP-side snapshot (with any formula applied)
-if you need the derived number rather than the raw translation.
+Animatable props that accept a shared value: `translate-x`, `translate-y`, `scale`, `rotate`, and `opacity`.
+
+Everything above runs natively on the UI thread — as the finger moves, the bound props update at the display's
+refresh rate with no PHP involved. If you need the PHP-side number (for example, the current snapshot with its
+formula applied), call `->value()` on the shared value.
 
 ## Property animations
 
@@ -77,7 +68,7 @@ change in `animate-duration` (milliseconds) and the element eases from its old v
 render. The animatable props are `translate-x`, `translate-y`, `scale`, `rotate`, and `opacity`:
 
 @verbatim
-```blade
+```blade static
 {{-- A panel slides up from below when $shown flips to true --}}
 <native:column
     :translate-y="$shown ? 0 : 120"
@@ -104,7 +95,7 @@ Combine transforms freely under one duration — a card can slide, fade, and sca
 Set `animate-loop` to repeat an animation continuously — a pulsing dot, a breathing highlight:
 
 @verbatim
-```blade
+```blade static
 <native:column :scale="$pulsing ? 1.15 : 1.0" :animate-duration="600" :animate-loop="true">
     <native:icon name="heart.fill" />
 </native:column>
@@ -122,7 +113,7 @@ back on release:
 - `press-translate-y` — nudge down while pressed (e.g. `3`)
 
 @verbatim
-```blade
+```blade static
 <native:pressable :press-scale="0.92" :press-opacity="0.85" :press-translate-y="3" @press="open">
     <native:text>Press me</native:text>
 </native:pressable>

resources/views/docs/mobile/4/digging-deeper/lifecycle-hooks.md

@@ -103,7 +103,7 @@ Livewire's updated hooks. The hook name is `updated` + the studly-cased property
 value.
 
 @verbatim
-```blade
+```blade static
 <native:text-input native:model="query" />
 ```
 @endverbatim

resources/views/docs/mobile/4/digging-deeper/reactivity.md

@@ -32,7 +32,7 @@ class CartScreen extends NativeComponent
 Access it as `$this->total` (no parentheses) in PHP, or `@{{ $this->total }}` in the view:
 
 @verbatim
-```blade
+```blade static
 <native:text>Total: {{ $this->total }}</native:text>
 ```
 @endverbatim
@@ -82,7 +82,7 @@ You can also drive a re-render from the view with `native:poll` — useful for a
 without wiring a method:
 
 @verbatim
-```blade
+```blade static
 <native:text native:poll="1s">{{ now()->format('g:i:s A') }}</native:text>
 ```
 @endverbatim

resources/views/docs/mobile/4/digging-deeper/theming.md

@@ -42,12 +42,42 @@ on that surface. Pairing them this way is what keeps contrast correct across lig
 Plus non-color tokens: `radius-sm|md|lg|full`, `font-sm|md|lg|xl`, and `font-family` (`System` resolves to San
 Francisco on iOS / Roboto on Android; set a family name to load a custom font).
 
+Disabled controls draw from the `surface-variant` (fill) and `on-surface-variant` (label) pair on both
+platforms — tune disabled contrast by adjusting those two tokens, not per-component.
+
+## Color values
+
+Anywhere you author a color — a theme token, an element color prop (`headline-color`, badge colors, swipe-action
+tints), or an arbitrary-value class (`bg-[#…]`) — the same formats are accepted:
+
+| Format | Examples |
+| --- | --- |
+| Hex | `#B91C1C`, `#F00` |
+| Hex with alpha — CSS `#RRGGBBAA` order | `#8B5CF680` |
+| Tailwind palette name | `red-300`, `orange-800` |
+| Named | `white`, `black`, `transparent` |
+| Opacity modifier on any of the above | `red-300/20`, `#8B5CF6/50` |
+
+```php
+'light' => [
+    'primary'   => 'violet-600',      // Tailwind palette name
+    'secondary' => 'fuchsia-500/70',  // opacity modifier → tonal fill
+    'surface'   => '#F8FAFC',         // plain hex
+    'accent'    => '#00AAA680',       // hex with alpha (#RRGGBBAA)
+],
+```
+
+Alpha hex is always authored in CSS `#RRGGBBAA` order — the framework converts to what each platform expects.
+Components render color tokens **solid**; when you want a translucent or tonal fill, put the opacity on the token
+(`'secondary' => 'fuchsia-500/70'`) rather than expecting the renderer to soften it. Dark-mode auto-derivation
+preserves the alpha byte.
+
 ## Using tokens in a screen
 
 Reference any token from Blade with the `theme-{token}` class suffix, on background, text, and border utilities:
 
 @verbatim
-```blade
+```blade static
 <native:column class="bg-theme-surface border border-theme-outline rounded-2xl p-4">
     <native:text class="text-theme-on-surface text-lg font-bold">Balance</native:text>
     <native:text class="text-theme-on-surface-variant">Updated just now</native:text>

resources/views/docs/mobile/4/edge-components/activity-indicator.md

@@ -22,6 +22,7 @@ All [shared layout and style attributes](layout) are supported, plus:
 - `size` - `"sm"`, `"md"` (default), or `"lg"` (optional, string). Legacy ints `1`=large, `2`=small are also accepted
 - `color` - Spinner color as hex string (optional). Leave unset to use `theme.primary`
 - `a11y-label` - Accessibility label (optional)
+- `a11y-hint` - Accessibility hint (optional)
 
 <aside>
 
@@ -38,18 +39,21 @@ a non-theme-styled container (e.g. a light spinner over a dark image overlay).
 
 @verbatim
 ```blade
-<native:column fill center>
+<native:column class="w-full h-[200] items-center justify-center">
     <native:activity-indicator size="lg" />
     <native:text class="text-base text-theme-on-surface-variant mt-4">Loading...</native:text>
 </native:column>
 ```
 @endverbatim
 
+On a real loading screen, use `<native:column fill center>` at the page root instead — the fixed `h-[200]` here just
+gives the example a bounded area to center in.
+
 ### Inline loading
 
 @verbatim
 ```blade
-<native:row :gap="8" :align-items="1">
+<native:row class="gap-2 items-center">
     <native:activity-indicator size="sm" />
     <native:text class="text-sm text-theme-on-surface-variant">Refreshing</native:text>
 </native:row>
@@ -79,3 +83,4 @@ ActivityIndicator::make()
 - `size(string|int $size)` - `"sm" | "md" | "lg"`. Legacy: `1`=large, `2`=small
 - `color(string $hex)` - Override the theme tint
 - `a11yLabel(string $value)` - Accessibility label
+- `a11yHint(string $value)` - Accessibility hint

resources/views/docs/mobile/4/edge-components/badge.md

@@ -8,7 +8,8 @@ order: 110
 A small count or text marker, typically used as an overlay on nav items, list rows, or buttons. Renders as a capsule
 pill.
 
-Per Model 3, colors come from the theme via the semantic `variant` prop — there are no per-instance overrides.
+Colors come from the theme via the semantic `variant` prop — `destructive` (the default), `primary`, or `accent`.
+Prefer `variant` for badge colors: it keeps the label legible on both platforms and in both light and dark themes.
 
 @verbatim
 ```blade
@@ -25,6 +26,7 @@ Per Model 3, colors come from the theme via the semantic `variant` prop — ther
     - `primary` — `theme.primary` / `theme.onPrimary`
     - `accent` — `theme.accent` / `theme.onAccent`
 - `a11y-label` - Accessibility label (optional)
+- `a11y-hint` - Accessibility hint (optional)
 
 <aside>
 
@@ -39,7 +41,7 @@ icon, see the `badge` and `news` props on [`<native:bottom-nav-item>`](bottom-na
 
 @verbatim
 ```blade
-<native:row :gap="8" :align-items="1">
+<native:row class="gap-2 items-center">
     <native:icon name="notifications" :size="24" />
     <native:badge :count="$unreadCount" />
 </native:row>
@@ -56,19 +58,40 @@ icon, see the `badge` and `news` props on [`<native:bottom-nav-item>`](bottom-na
 
 ### Anchored to an icon
 
-Use a [`<native:stack>`](stack) to layer the badge over its target:
+Use a [`<native:stack>`](stack) to layer the badge over its target. Size the stack a little larger than the
+icon so the badge has a corner to sit in, and position it with positive `top-*` / `right-*` insets — the
+renderer anchors an absolute child to whichever edges you set (negative insets are not supported):
 
 @verbatim
 ```blade
 <native:stack :width="40" :height="40">
     <native:icon name="cart" :size="32" />
-    <native:column class="absolute" :top="-2" :right="-2">
+    <native:column class="absolute top-px right-px">
         <native:badge :count="$cartItems" />
     </native:column>
 </native:stack>
 ```
 @endverbatim
 
+### Custom background (iOS only)
+
+On iOS you can override the capsule fill with a `bg-*` class and the radius with a `rounded-*` class:
+
+@verbatim
+```blade static
+<native:badge label="Beta" class="bg-amber-600 rounded-md" />
+```
+@endverbatim
+
+<aside>
+
+Per-instance overrides are currently iOS-only: Android ignores `bg-*` and `rounded-*` on badges and always paints
+the variant's colors. The label also keeps the variant's on-color (white for the default `destructive`) even over a
+custom background, so pick a dark fill like `bg-amber-600` to keep the text legible. Prefer `variant` when you need
+colors that work on both platforms.
+
+</aside>
+
 ## Element
 
 ```php
@@ -88,3 +111,4 @@ Badge::make()
 - `label(string $text)` - Short text label (wins over `count`)
 - `variant(string $variant)` - `destructive | primary | accent`
 - `a11yLabel(string $value)` - Accessibility label
+- `a11yHint(string $value)` - Accessibility hint