docs(mobile/3): full revise of edge-components + new chrome / nav / safe-area pages

Edge components — reconciled every existing page with element + iOS/Android renderers:

- bottom-nav: active-color, background-color, text-color, news; TabBar / Tab builder
  API; safe-area auto-handling; tab taps use replace semantics.
- top-bar: subtitle, background-color, text-color, elevation (hairline overlay,
  not SwiftUI shadow); NavBar / NavAction builder API; navigationOptions().
- scroll-view: shows-indicators flagged iOS-only; Android LazyRow/Column.
- stack: rewrote around the new custom Layout — children at natural size, centered.
- layout: align-self stretch override of items-center; flex-1 shorthand.
- button, toggle, checkbox, slider, select, radio-group, button-group, chip,
  text-input: Model 3 styling rule (per-instance bg/padding/font-size dropped).
- text-input: replaced the (non-existent) <native:text-input> doc with separate
  outlined and filled coverage; corrected keyboard string enum.
- image: corrected fit modes (renderer collapses to fit/fill).
- text: fixed font-weight 7 → .heavy (was "extrabold").
- shapes: per-shape sections (rect / circle / line); flagged that <native:line>
  ignores from/to (renderer always draws horizontal).
- divider: clarified border-color drives line color; horizontal-divider alias.
- introduction: refreshed component inventory.

New edge-components pages:
- badge, button-group, canvas, card, carousel, checkbox, chip, list (covers
  list-item), modal, progress-bar, radio-group (covers radio), screen, select,
  slider, tab-row (covers tab).

New the-basics pages:
- layouts: NativeLayout + StackLayout / TabsLayout, route attachment,
  wrapWithChrome flow, navigationOptions / setNavBar / navTitle.
- navigation: navigate / back / replace / exitToWeb, transitions, param/data.
- safe-area: safeArea / safeAreaTop / safeAreaBottom; bitmask + auto-handling
  via wrapWithChrome based on which bars are present.
- positioning: absolute / relative + anchor convention; FAB pattern; stack caveat.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: shanerbaner82

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

@@ -5,8 +5,9 @@ order: 350
 
 ## Overview
 
-A native loading spinner. Use this to indicate background activity or loading states. Renders as a platform-native
-progress indicator (spinning wheel on iOS, circular indicator on Android).
+A circular spinner indicating background activity. Always indeterminate — for determinate progress use
+[`<native:progress-bar>`](progress-bar). Renders as a SwiftUI `ProgressView` on iOS and Material3
+`CircularProgressIndicator` on Android.
 
 @verbatim
 ```blade
@@ -18,13 +19,17 @@ progress indicator (spinning wheel on iOS, circular indicator on Android).
 
 All [shared layout and style attributes](layout) are supported, plus:
 
-- `size` - Indicator size (optional, float): `0`=default, `1`=large, `2`=small
-- `color` - Spinner color as hex string (optional, default: platform default)
+- `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)
 
 <aside>
 
 `<native:activity-indicator />` is a self-closing element. It does not accept children.
 
+The default tint comes from `theme.primary`. The `color` prop is an escape hatch — useful when the spinner sits on
+a non-theme-styled container (e.g. a light spinner over a dark image overlay).
+
 </aside>
 
 ## Examples
@@ -34,7 +39,7 @@ All [shared layout and style attributes](layout) are supported, plus:
 @verbatim
 ```blade
 <native:column fill center>
-    <native:activity-indicator :size="1" color="#7C3AED" />
+    <native:activity-indicator size="lg" />
     <native:text class="text-base text-slate-400 mt-4">Loading...</native:text>
 </native:column>
 ```
@@ -45,24 +50,32 @@ All [shared layout and style attributes](layout) are supported, plus:
 @verbatim
 ```blade
 <native:row :gap="8" :align-items="1">
-    <native:activity-indicator :size="2" />
+    <native:activity-indicator size="sm" />
     <native:text class="text-sm text-slate-500">Refreshing</native:text>
 </native:row>
 ```
 @endverbatim
 
-### Conditional loading
+### Override the tint
 
 @verbatim
 ```blade
-@if($loading)
-    <native:column fill center>
-        <native:activity-indicator color="#3B82F6" />
-    </native:column>
-@else
-    <native:column fill :padding="16">
-        {{-- Content --}}
-    </native:column>
-@endif
+<native:activity-indicator color="#7C3AED" />
 ```
 @endverbatim
+
+## Element
+
+```php
+use Nativephp\NativeUi\Elements\ActivityIndicator;
+
+ActivityIndicator::make()
+    ->size('lg')
+    ->color('#7C3AED')
+    ->a11yLabel('Loading messages');
+```
+
+- `make()` - Create a new indicator
+- `size(string|int $size)` - `"sm" | "md" | "lg"`. Legacy: `1`=large, `2`=small
+- `color(string $hex)` - Override the theme tint
+- `a11yLabel(string $value)` - Accessibility label

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

@@ -0,0 +1,90 @@
+---
+title: Badge
+order: 360
+---
+
+## Overview
+
+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.
+
+@verbatim
+```blade
+<native:badge :count="3" />
+```
+@endverbatim
+
+## Props
+
+- `count` - Numeric count. Renders as `"99+"` for values above 99 (optional, int)
+- `label` - Arbitrary short text. Wins over `count` when both are set (optional, string)
+- `variant` - Color variant (optional, string, default: `destructive`):
+    - `destructive` — `theme.destructive` / `theme.onDestructive`
+    - `primary` — `theme.primary` / `theme.onPrimary`
+    - `accent` — `theme.accent` / `theme.onAccent`
+- `a11y-label` - Accessibility label (optional)
+
+<aside>
+
+`<native:badge />` is a self-closing element. It does not accept children. For a badge attached to a navigation
+icon, see the `badge` and `news` props on [`<native:bottom-nav-item>`](bottom-nav).
+
+</aside>
+
+## Examples
+
+### Count badge
+
+@verbatim
+```blade
+<native:row :gap="8" :align-items="1">
+    <native:icon name="notifications" :size="24" />
+    <native:badge :count="$unreadCount" />
+</native:row>
+```
+@endverbatim
+
+### Label badge
+
+@verbatim
+```blade
+<native:badge label="New" variant="primary" />
+```
+@endverbatim
+
+### Anchored to an icon
+
+Use a [`<native:stack>`](stack) to layer the badge over its target:
+
+@verbatim
+```blade
+<native:stack :width="40" :height="40">
+    <native:icon name="cart" :size="32" />
+    <native:column class="absolute" :top="-2" :right="-2">
+        <native:badge :count="$cartItems" />
+    </native:column>
+</native:stack>
+```
+@endverbatim
+
+## Element
+
+```php
+use Nativephp\NativeUi\Elements\Badge;
+
+Badge::make()
+    ->count(3)
+    ->variant('primary');
+
+Badge::make()
+    ->label('New')
+    ->variant('accent');
+```
+
+- `make()` - Create a badge
+- `count(int $count)` - Numeric count (capped display at `99+`)
+- `label(string $text)` - Short text label (wins over `count`)
+- `variant(string $variant)` - `destructive | primary | accent`
+- `a11yLabel(string $value)` - Accessibility label

resources/views/docs/mobile/3/edge-components/bottom-nav.md

@@ -40,28 +40,84 @@ A bottom navigation bar with up to 5 items. Used for your app's primary navigati
 
 - `label-visibility` - `labeled`, `selected`, or `unlabeled` (optional, default: `labeled`)
 - `dark` - Force dark mode styling (optional)
+- `active-color` - Color of the active tab's icon and label. Hex string (optional)
+- `background-color` - Bar background color. Hex string. Wins over `dark`'s default (optional)
+- `text-color` - Color of inactive tab icons and labels. Hex string. Active tabs use `active-color` (optional)
+
+<aside>
+
+The bar handles its own bottom safe-area inset internally — the home-indicator zone on iOS, the gesture-bar zone on
+Android. Don't add your own padding for it. The bar's background extends to the screen edge while its content stays
+above the indicator, mirroring iOS `UITabBar`.
+
+</aside>
 
 ## Children
 
 A `<native:bottom-nav>` can contain up to 5 `<native:bottom-nav-item>` elements.
 
+### Props
+
 - `id` - Unique identifier (required)
 - `icon` - A named [icon](icons) (required)
 - `label` - Accessibility label (required)
 - `url` - A URL to navigate to in the web view (required)
 - `active` - Highlight this item as active (optional, default: `false`)
-- `badge` - Badge text/number (optional)
-- `news` - Show "new" indicator dot (optional, default: `false`)
+- `badge` - Badge text/number, e.g. `"2"` — small red pill anchored top-right of the icon (optional)
+- `news` - Show a small red dot anchored top-right of the icon. Mutually exclusive with `badge` (optional, default: `false`)
 
 <aside>
 
-Any `url` that doesn't match the web view's domain will open in the user's default browser.
+Tab taps use `replace` semantics — tapping a tab swaps the current screen rather than pushing onto the stack. The
+back chevron pops the entire tabs section in one step instead of stepping through tab history.
+
+Any `url` that doesn't match a registered native route will exit to the web view and load that URL there.
 
 </aside>
 
 ### `badge` example
+
 <div class="sm:w-1/2">
 
 ![](/img/docs/edge-bottom-nav-item-badge.png)
 
 </div>
+
+## Builder API
+
+When a `<native:bottom-nav>` is supplied by a [layout](../the-basics/layouts), you build it fluently with the `TabBar`
+and `Tab` builders rather than writing it in Blade.
+
+```php
+use Native\Mobile\Edge\Layouts\Builders\Tab;
+use Native\Mobile\Edge\Layouts\Builders\TabBar;
+
+TabBar::make()
+    ->dark()
+    ->activeColor('#0891b2')
+    ->labelVisibility('labeled')
+    ->backgroundColor('#0F172A')
+    ->textColor('#94A3B8')
+    ->add(Tab::link('Chats',   '/syncup',          icon: 'chat_bubble')->badge('2'))
+    ->add(Tab::link('Friends', '/syncup/friends',  icon: 'person.3.fill')->news())
+    ->add(Tab::link('Profile', '/syncup/profile',  icon: 'person')->active());
+```
+
+### `TabBar` methods
+
+- `make()` - Create a new builder
+- `dark(bool $dark = true)` - Force dark mode styling
+- `activeColor(string $color)` - Color of the active tab's icon and label
+- `backgroundColor(string $color)` - Bar background color (overrides `dark()`'s default)
+- `textColor(string $color)` - Color of inactive tab icons and labels
+- `labelVisibility(string $mode)` - `"labeled"`, `"selected"`, or `"unlabeled"`
+- `add(Tab $tab)` - Append a tab item
+
+### `Tab` methods
+
+- `link(string $label, string $url, ?string $icon = null)` - Build a tab. The id defaults to the label slugified
+- `id(string $id)` - Override the auto-generated id
+- `icon(string $icon)` - A named [icon](icons)
+- `badge(string $badge, ?string $color = null)` - Show a numeric/text badge
+- `news(bool $news = true)` - Show a red dot indicator
+- `active(bool $active = true)` - Mark this tab as active

resources/views/docs/mobile/3/edge-components/bottom-sheet.md

@@ -5,8 +5,12 @@ order: 700
 
 ## Overview
 
-A modal bottom sheet that slides up from the bottom of the screen. Use it for contextual actions, forms, and detail
-views that overlay the main content. Renders as a native bottom sheet on both iOS and Android.
+A modal panel that slides up from the bottom of the screen. Use it for contextual actions, forms, and detail views
+that overlay the main content. Renders as SwiftUI's `.sheet` with `presentationDetents` on iOS and a Material3
+`ModalBottomSheet` on Android.
+
+Per Model 3, the container color resolves from `theme.surface`. For a custom surface wrap content in a
+`<native:column class="bg-...">`.
 
 @verbatim
 ```blade
@@ -22,13 +26,18 @@ views that overlay the main content. Renders as a native bottom sheet on both iO
 
 ## Props
 
-All [shared layout and style attributes](layout) are supported, plus:
-
 - `visible` - Whether the sheet is shown (required, boolean)
+- `detents` - Allowed sheet heights (optional, default: `"medium,large"`). Comma-separated combination of:
+    - `small` (25% of screen)
+    - `medium`
+    - `large`
+    - `full` (100% of screen)
+    - A numeric fraction `0.0`–`1.0` for a custom height (e.g. `"0.4"` for 40%)
+- `a11y-label` - Accessibility label (optional)
 
 ## Events
 
-- `@dismiss` - Livewire method called when the sheet is dismissed (e.g. by swiping down or tapping the scrim)
+- `@dismiss` - Livewire method called when the sheet is dismissed (swipe down or tap outside)
 
 ## Children
 
@@ -40,18 +49,18 @@ Accepts any EDGE elements as children. The children are rendered inside the shee
 
 @verbatim
 ```blade
-<native:bottom-sheet :visible="$showActions" @dismiss="hideActions">
+<native:bottom-sheet :visible="$showActions" @dismiss="hideActions" detents="small">
     <native:column class="w-full gap-0 pb-8">
         <native:pressable @press="editItem" class="w-full px-4 py-3">
             <native:row :gap="12" :align-items="1">
-                <native:icon name="edit" :size="24" color="#1E293B" />
+                <native:icon name="edit" :size="24" />
                 <native:text class="text-base">Edit</native:text>
             </native:row>
         </native:pressable>
         <native:divider />
         <native:pressable @press="shareItem" class="w-full px-4 py-3">
             <native:row :gap="12" :align-items="1">
-                <native:icon name="share" :size="24" color="#1E293B" />
+                <native:icon name="share" :size="24" />
                 <native:text class="text-base">Share</native:text>
             </native:row>
         </native:pressable>
@@ -71,42 +80,50 @@ Accepts any EDGE elements as children. The children are rendered inside the shee
 
 @verbatim
 ```blade
-<native:bottom-sheet :visible="$showForm" @dismiss="closeForm">
+<native:bottom-sheet :visible="$showForm" @dismiss="closeForm" detents="medium,large">
     <native:column class="w-full p-4 gap-4">
         <native:text class="text-xl font-bold">Add Item</native:text>
-        <native:text-input label="Name" @model="itemName" />
-        <native:text-input label="Description" @model="itemDescription" multiline :min-lines="3" />
+        <native:outlined-text-input label="Name" native:model="itemName" />
+        <native:outlined-text-input label="Description" native:model="itemDescription" multiline :min-lines="3" />
         <native:row :gap="8" :justify-content="2">
-            <native:button label="Cancel" @press="closeForm" />
-            <native:button label="Save" @press="saveItem" color="#7C3AED" label-color="#FFFFFF" />
+            <native:button label="Cancel" variant="secondary" @press="closeForm" />
+            <native:button label="Save" @press="saveItem" />
         </native:row>
     </native:column>
 </native:bottom-sheet>
 ```
 @endverbatim
 
-### Toggling a sheet
-
-The sheet is controlled by a Livewire property. Set `visible` to `true` to show it, and handle the `@dismiss` event to
-hide it when the user swipes it away.
+### Custom height
 
 @verbatim
 ```blade
-{{-- Trigger --}}
-<native:button label="Show Options" @press="showSheet" />
-
-{{-- Sheet --}}
-<native:bottom-sheet :visible="$showSheet" @dismiss="hideSheet">
-    <native:column class="w-full p-4">
-        <native:text>Sheet content</native:text>
-    </native:column>
+<native:bottom-sheet :visible="$showPreview" @dismiss="closePreview" detents="0.4">
+    <native:image src="{{ $previewUrl }}" class="w-full h-full" :fit="2" />
 </native:bottom-sheet>
 ```
 @endverbatim
 
 <aside>
 
-Always handle the `@dismiss` event to update your Livewire state. If you don't, the `visible` property will be out of
-sync with the actual sheet state after the user dismisses it by gesture.
+Always handle the `@dismiss` event to update your Livewire state. If you don't, the `visible` property will be out
+of sync with the actual sheet state after the user dismisses it by gesture.
 
 </aside>
+
+## Element
+
+```php
+use Nativephp\NativeUi\Elements\BottomSheet;
+
+BottomSheet::make()
+    ->visible($showSheet)
+    ->detents('medium,large')
+    ->onDismiss('hideSheet');
+```
+
+- `make()` - Create a bottom sheet
+- `visible(bool $value = true)` - Toggle visibility
+- `detents(string $detents)` - Allowed heights
+- `a11yLabel(string $value)` - Accessibility label
+- `onDismiss(string $method)` - Livewire method invoked on dismissal