@rdlabo/ionic-theme-ios27 1.2.0-2 → 1.2.0-4

package/docs/native-ui-shell.md

@@ -40,7 +40,7 @@ Native appearance follows the applied class, system or always-dark theme CSS. Sy
 
 ## Supported markup
 
-The table below describes the ordinary Native UI Shell. Vertical Bars uses the separate [toolbar action rules](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#toolbar-actions).
+The table below describes the ordinary Native UI Shell. Vertical Bars uses the separate [toolbar action rules](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#toolbar-actions).
 
 | Ionic component                               | Supported appearance and placement                                                                        | Native rendering                                                      |
 | --------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
@@ -52,12 +52,14 @@ The table below describes the ordinary Native UI Shell. Vertical Bars uses the s
 | `ion-segment`                                 | Fixed toolbar, non-scrollable, text **or** one icon per item                                              | `UISegmentedControl`                                                  |
 | `ion-fab` / `ion-fab-button` / `ion-fab-list` | Glass FAB in an `ion-content` fixed slot; one main button and optional directional lists                  | Persistent glass `UIButton` per button; one FAB synchronization group |
 
-For the ordinary Native UI Shell, only iOS-mode components with the theme variables installed are eligible. Explicitly enabled Vertical Bars is mode-independent as described below. `ionic-theme-disabled`, `ios-theme-disabled`, and the legacy `ios26-disabled` on an element or ancestor always exclude it. A disabled theme on one tab/segment item keeps its whole group on the Web.
+For the ordinary Native UI Shell, only iOS-mode components with the theme variables installed are eligible. Explicitly enabled Vertical Bars is mode-independent as described below. `ios-theme-disabled` and the legacy `ios26-disabled` on an element or ancestor always exclude it. A disabled theme on one tab/segment item keeps its whole group on the Web.
 
-Use `ios-theme-shell-disabled` to disable only the iOS Native UI Shell while keeping the Web theme. It excludes the element and all its descendants. Adding or removing the class at runtime automatically restores Web rendering or re-evaluates native eligibility.
+Use `data-shell="disabled"` (or the equivalent `ios-theme-shell-disabled` class) to disable only the iOS Native UI Shell while keeping the Web theme. It excludes the element and all its descendants. Adding or removing the attribute or class at runtime automatically restores Web rendering or re-evaluates native eligibility.
+
+Only the exact value `disabled` opts out; an empty or unknown value is ignored. Remove the attribute to re-enable projection. If the class is also present, remove both to re-enable projection. This does not disable clicks or change the Web theme. The data attribute is unreleased.
 
 ```html
-<ion-toolbar class="ios-theme-shell-disabled">
+<ion-toolbar data-shell="disabled">
   <ion-button>Web glass button</ion-button>
 </ion-toolbar>
 ```
@@ -84,19 +86,21 @@ The DOM owns labels, SVG content, placement, selected values and application beh
 
 For forms, retain `ion-button type="submit"` and the form's existing submit handler. An external form is still passed as `[form]="formRef"`. The plugin does not call `form.submit()`, add a second submit path or change Angular form ownership. Segment values retain their original type because the original `ion-segment-button` is clicked; programmatic value changes do not emit a synthetic `ionChange`.
 
-Labels use native text. Local static SVGs and resolved `ion-icon` SVGs (including `name` and changes to `name`) are rasterized at the display scale and cached, preserving their colors. Tab SVGs that follow text color use native template rendering, so icons and labels change selection color together without waiting for another bridge image. Explicit multicolor artwork retains its original colors. External references, `<use>`, animation, embedded HTML/images, SVG text and stylesheets are excluded. Web fonts and arbitrary slot layouts are not reproduced exactly.
+Labels use native text. Local static SVGs and resolved `ion-icon` SVGs (including `name` and changes to `name`) are rasterized at the display scale and cached. Source projection preserves their colors; system projection of vertical toolbar buttons uses template icons tinted by SwiftUI. Tab SVGs that follow text color use native template rendering, so icons and labels change selection color together without waiting for another bridge image. Multicolor tab artwork retains its original colors. External references, `<use>`, animation, embedded HTML/images, SVG text and stylesheets are excluded. Web fonts and arbitrary slot layouts are not reproduced exactly.
 
 The native host accepts input only within native controls. Tab interaction and accessibility are provided by the standard [UITabBar](https://developer.apple.com/documentation/uikit/uitabbar) control. Empty areas pass touches to the WebView. Ionic iOS hides empty badges by default. An empty visible `ion-badge` becomes a native notification dot; a non-empty badge displays its text. Badge background and text colors come from computed DOM styles, including Ionic `color` palettes. Hidden or removed badges clear the native badge. Tabs use UIKit’s standard tab control for selection, touch behavior, badges and accessibility, retaining item identity across selection updates. UIKit owns the item layout within the measured bar, so arbitrary CSS item placement is not reproduced. Native controls expose names, disabled/selected traits and badges to accessibility; the source is hidden from Web accessibility while projected. This is not a guarantee of identical VoiceOver traversal between Web and UIKit.
 
 ## Searchable tabs
 
-Existing `attachTabBarSearchable(tabBar, fabButton, footer)` registrations automatically use native search when their bottom tab bar and glass search controls are supported. No new component option, route, native setup or page listener is required. Ordinary tab bars continue using `UITabBar`; searchable groups use a persistent `UITabBarController`, `UITab` / `UISearchTab`, and `UISearchController`. The original Capacitor WebView continues to render results and handle navigation.
+Existing `attachTabBarSearchable(tabBar, fabButton, footer)` registrations automatically use native search when their bottom tab bar and glass search controls are supported. No new component option, route, native setup or page listener is required. Ordinary tab bars continue using `UITabBar`; horizontal searchable groups use a persistent `UITabBarController`, `UITab` / `UISearchTab`, and `UISearchController`. The original Capacitor WebView continues to render results and handle navigation.
+
+With vertical bars, the native rail keeps every tab and its selection. SwiftUI’s `searchable` and `searchToolbarBehavior(.minimize)` provide the system search button, field, dismissal control and transitions within the same native navigation surface. Apple determines their placement for the current device layout and focuses the native field when system search opens. Input, focus, clear and submit events use the same bridge as horizontal search. When native search is unavailable, the Web search presentation also preserves vertical tabs.
 
 Search registration does not bypass placement restrictions. Its searchbar and close button must be in fixed footer toolbars. Its trigger must belong to an `ion-fab[slot="fixed"]` directly inside `ion-content`, or directly on the existing non-scrolling `.ion-page` layout. A wrapper inside scrolling content is not a fixed slot.
 
-While a registration is alive, Native UI Shell keeps the searchable controller even when the page is transitioning or temporarily unavailable (`available: false`), instead of demoting back to a separate ordinary control identity. Resting chrome (including Album before search opens) uses the same `UITabBar` + `ShellTabBar.fit` path as ordinary tabs, with the search trigger pinned to the FAB when available; `UISearchTab` is shown only while the search session is active. Flipping availability or entering/leaving search crossfades between those layers. Register before the destination page finishes entering (for example in `ionViewWillEnter`) so the first visit does not paint ordinary tabs and then swap.
+For horizontal tabs, while a registration is alive, Native UI Shell keeps the searchable controller even when the page is transitioning or temporarily unavailable (`available: false`), instead of demoting back to a separate ordinary control identity. Resting chrome (including Album before search opens) uses the same `UITabBar` + `ShellTabBar.fit` path as ordinary tabs, with the search trigger pinned to the FAB when available; `UISearchTab` is shown only while the search session is active. Flipping availability or entering/leaving search crossfades between those layers. Register before the destination page finishes entering (for example in `ionViewWillEnter`) so the first visit does not paint ordinary tabs and then swap.
 
-Opening search preserves the selected Ionic tab and does not automatically show the keyboard (`automaticallyActivatesSearch` stays off). Tap the field or call `ion-searchbar.setFocus()` for the keyboard. While search is active, Native UI Shell freezes Web layout projection and holds Capacitor Keyboard resize at `none`; UIKit owns tab/search chrome (no Ionic `fit` mid-session). Leave re-fits ordinary tabs to `ion-tab-bar` and search to the FAB. Ordinary native tabs keep an optimistic selection until the Web `selected` state catches up. Input events and application `value` updates continue across the bridge until search closes. The trigger's resolved SVG and the search icon are projected from Ionic, including `ion-icon name`.
+With horizontal tabs, opening search preserves the selected Ionic tab and does not automatically show the keyboard (`automaticallyActivatesSearch` stays off). Tap the field or call `ion-searchbar.setFocus()` for the keyboard. While search is active, Native UI Shell freezes Web layout projection and holds Capacitor Keyboard resize at `none`; UIKit owns tab/search chrome (no Ionic `fit` mid-session). Leave re-fits ordinary tabs to `ion-tab-bar` and search to the FAB. Ordinary native tabs keep an optimistic selection until the Web `selected` state catches up. Input events and application `value` updates continue across the bridge until search closes. The trigger's resolved SVG and the search icon are projected from Ionic, including `ion-icon name`.
 
 Native edits pass through Ionic's input handlers, preserving `ionInput` debounce, `ionChange`, `ionFocus`, `ionBlur`, and `ionClear`. Programmatic `value` changes do not emit `ionInput`; synchronous application corrections and stale native input are distinguished. Native editing owns marked text and the caret. Returning through the footer's close action retains the value and does not emit `ionCancel` or `ionClear`.
 
@@ -175,11 +179,11 @@ iPhone Duo support is experimental, including standalone use without Native UI S
 
 The standalone Vertical Control Area entry point (`@rdlabo/ionic-theme-ios27/vertical-bars`) and `dist/css/vertical-bars.css` work without loading the iOS 27 theme. Call `enableVerticalControlArea()` for this use case; it projects only controls placed in the vertical area. Apps already calling `enableNativeUIShell()` should keep that single runtime rather than starting both. See [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo) for the complete setup, including hinge posture and the split-pane layout for apps that do not use this shell at all.
 
-On supported iOS versions, adding `.ios-theme-vertical-bars` changes only controls that the system relocates into the physical side rail. Native UI Shell presents eligible tabs, back navigation, menu buttons, and toolbar actions through a SwiftUI `TabView` and toolbar once the class is applied. When the OS reports a rail edge — on iPhone Duo linked against iOS 27.1 or later — it must agree with the applied placement; a disagreeing report keeps the rail on the Web. Older toolchains that cannot report an edge trust the DOM placement directly. SwiftUI owns their adaptive placement and Liquid Glass appearance; Ionic remains the source of labels, icons, selected/disabled state, routing, form submission, and click handlers.
+Vertical Bars uses a SwiftUI `TabView` and toolbar in the system rail. Ionic remains the source of labels, icons, selected/disabled state and actions. See [Vertical Bars](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars) for rail layout, native fallback and supported overlays.
 
-The SwiftUI surface is clipped and hit-tested to the system rail. Web content remains visible and interactive outside that physical region. The runtime optimistically updates tab selection before forwarding the action to the original `ion-tab-button`, using the same event and stale-revision protection as the other native controls. A topmost full-width modal supplies its own eligible toolbar actions and rail bounds, including when it is a sheet. Centered modals, menus, and popovers keep their own toolbar layout. Modal placement follows the visible dialog width rather than its type or hinge posture.
+In Vertical Bars, fixed-toolbar `ion-button` actions need an `ion-icon` or SVG with `slot="icon-only"`. All fills and Ionic colors are eligible; submit buttons follow the same placement rule. Add `.ios-theme-horizontal-only` to a button or its `ion-buttons` group to keep it horizontal. See [Toolbar actions](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#toolbar-actions) for placement and exclusion rules.
 
-In Vertical Bars, fixed-toolbar `ion-button` actions use an `ion-icon` or SVG with `slot="icon-only"`. All fills (`default`, `clear`, `solid`, and `outline`) and Ionic colors are eligible; submit buttons follow the same placement rule. Solid actions retain their background color and outline actions retain their border color and width. Actions without `icon-only` stay horizontal. Scrolling and explicitly opted-out controls retain their Web presentation. Add `.ios-theme-horizontal-only` to an `ion-buttons` group or individual `ion-button` to keep it in the horizontal Web toolbar. On Web, Android, older iOS, or when native projection is unavailable during setup, the Web projection remains the fallback.
+**Unreleased button appearance options:** the next release defaults native vertical buttons to `buttonProjection: 'system'`. Use `source` to project Ionic fill and colors, with `data-projection="source|system"` or the equivalent `ios-theme-projection-source` / `ios-theme-projection-system` classes for local exceptions. These settings affect native vertical `ion-button` and `ion-menu-button` actions only. Horizontal controls and Web clones keep their existing behavior. See [Choose button appearance](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#choose-button-appearance) for migration, priority and fill rules.
 
 For standalone setup while keeping your existing theme, see [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme).
 

package/docs/special-markup.md

@@ -53,6 +53,8 @@ iPhone Duo support is experimental. It is available in the `1.2.0-0` prerelease
 
 iPhone Duo support — the vertical system rail, hinge posture, and the posture-driven split-pane layout — is independent of the iOS 27 theme and the full Native UI Shell. See [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo) for the complete setup, including device-layout monitoring without a projection runtime.
 
+See [Vertical Bars](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars) for rail layout classes, control eligibility and native button appearance.
+
 For standalone setup while keeping your existing theme, see [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme).
 
 ## Two-line inset list items

package/docs/vertical-bars.md

@@ -0,0 +1,283 @@
+---
+title: Vertical Bars (experimental)
+---
+
+# Vertical Bars (experimental)
+
+Vertical Bars moves eligible Ionic navigation and actions into a side rail while keeping the original components as the source of labels, icons and behavior. It works with this theme or an existing Ionic theme, independently of hinge posture and the full Native UI Shell.
+
+Use this page for layout, control eligibility, native button appearance and the runtime API. For device events and split panes, see [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo). For a step-by-step browser preview and native setup, start with [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme).
+
+Vertical Bars is experimental; APIs and supported behavior may change. The button appearance options below are unreleased.
+
+## Enable Vertical Bars
+
+Load the opt-in stylesheet:
+
+```scss
+@use '@rdlabo/ionic-theme-ios27/dist/css/vertical-bars.css';
+```
+
+After `ion-app` is mounted, start one runtime:
+
+```ts
+import { enableVerticalControlArea } from '@rdlabo/ionic-theme-ios27/vertical-bars';
+
+const rail = await enableVerticalControlArea();
+```
+
+Add the layout class below for browser simulation, or [apply device placement](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#project-controls-into-the-rail) for an iPhone Duo. The application owns placement and cleanup: call `await rail.destroy()` when its owner is disposed. If you already use `enableNativeUIShell()`, keep that runtime; it includes Vertical Bars. Do not start both.
+
+The `/vertical-bars` entry point requires `@capacitor/core`, including in browser builds. CSS-only use needs no runtime. For native setup and navigation transitions, follow the [existing-theme guide](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme).
+
+On supported Capacitor iOS, eligible controls use native SwiftUI rendering. Web, Android and unavailable native projection use Web clones. A browser preview can verify layout and actions, but cannot compare native button appearance.
+
+## Reserve the vertical rail
+
+Add `.ios-theme-vertical-bars` to `ion-app` to reserve the rail region on the physical right, or add `.ios-theme-vertical-bars-left` as well to use the physical left:
+
+```html
+<ion-app class="ios-theme-vertical-bars">...</ion-app>
+```
+
+The classes are physical — `-left` always means the physical left edge — because CSS and the native renderer work in physical coordinates. `setVerticalControlAreaPlacement` applies the logical `verticalBarEdge` reported by the device plugin and resolves it through the document's direction, so an RTL app does not need its own conversion.
+
+For Chrome development, no native plugin is needed — the class alone reserves `80px` to simulate iPhone Duo. When `setVerticalControlAreaPlacement` receives `{ edge, nativeEdge, inset }`, the inset replaces the fallback width, even when it is less than `80px`. Override `--ios-theme-vertical-bars-safe-area-left` or `--ios-theme-vertical-bars-safe-area-right` when simulating a different layout.
+
+This keeps routers and component backgrounds full-viewport. `ion-content` moves its scroll foreground, `ion-toolbar` moves its container foreground, and `ion-fab` adjusts only when placed beside the system UI. The corresponding Ionic safe-area variable is reset inside those foreground components so descendants do not add the inset again.
+
+`ion-modal` applies the same foreground correction when its visible dialog spans the viewport width. With the Vertical Control Area runtime enabled, the topmost full-width modal also projects eligible toolbar buttons into its own rail; centered dialogs keep their toolbar buttons and receive no page-rail inset. This includes full-width sheet modals: their rail follows the visible sheet bounds as the breakpoint changes. Eligibility follows the visible dialog width, not the hinge posture or modal type. `ion-menu` and `ion-popover` are handled as separate surfaces: their internal foreground components do not receive the main-page conversion and retain Ionic's standard safe-area handling. A menu presented beside the system UI keeps Ionic's full-viewport animation host and offsets only its visible container by the corresponding inset; a menu from the opposite side is unchanged. Left and right remain physical coordinates in RTL, while Ionic's `side="start"` and `side="end"` values remain logical.
+
+The mode is component-mode independent: an app can keep Ionic `mode: 'md'` on iOS and still enable Vertical Bars. No component needs `mode="ios"`.
+
+## Native rendering
+
+On supported iOS versions, adding `.ios-theme-vertical-bars` changes only controls that the system relocates into the physical side rail. Native UI Shell presents eligible tabs, back navigation, menu buttons, and toolbar actions through a SwiftUI `TabView` and toolbar once the class is applied. When the OS reports a rail edge — on iPhone Duo linked against iOS 27.1 or later — it must agree with the applied placement; a disagreeing report keeps the rail on the Web. Older toolchains that cannot report an edge trust the DOM placement directly. SwiftUI owns their adaptive placement and Liquid Glass appearance; Ionic remains the source of labels, icons, selected/disabled state, routing, form submission, and click handlers.
+
+The SwiftUI surface is clipped and hit-tested to the system rail. Web content remains visible and interactive outside that physical region. The runtime optimistically updates tab selection before forwarding the action to the original `ion-tab-button`, using the same event and stale-revision protection as the other native controls. Overlay layout follows the [rail reservation rules](#reserve-the-vertical-rail).
+
+
+## Toolbar actions
+
+A standard `ion-back-button` can project from outside a fixed toolbar, including routed content or a persistent app shell. `ion-menu-button` and other toolbar actions require a fixed toolbar.
+
+An `ion-button` moves into the rail when it contains an `ion-icon` or SVG with `slot="icon-only"`. The button must be in a fixed `ion-toolbar` directly inside `ion-header` or `ion-footer`, outside scrolling `ion-content`.
+
+| Icon markup | Placement |
+| --- | --- |
+| `slot="icon-only"` | Vertical rail |
+| `slot="start"`, `slot="end"`, or no slot | Original horizontal toolbar |
+| No icon | Original horizontal toolbar |
+
+```html
+<ion-header>
+  <ion-toolbar>
+    <ion-buttons slot="end">
+      <ion-button aria-label="Done">
+        <ion-icon name="checkmark-outline" slot="icon-only"></ion-icon>
+      </ion-button>
+    </ion-buttons>
+  </ion-toolbar>
+</ion-header>
+```
+
+All fills (`default`, `clear`, `solid`, and `outline`) and Ionic colors follow this placement rule. Keep accessible names and the original click or form-submit handlers on the source buttons. `type="submit"` and `.button-submit` do not select a different placement.
+
+The rule applies to individual buttons and buttons inside `ion-buttons`, on ordinary pages and in the topmost full-width modal. Centered modals, menus, and popovers keep their own toolbar layout. Add `.ios-theme-horizontal-only` to a group or individual button to keep it horizontal. Placement is chosen when a routed page enters; changing an existing button's content or icon slot does not move it between the toolbar and rail until the page leaves and re-enters.
+
+### Choose button appearance
+
+**Unreleased:** `buttonProjection` and the local projection settings below are part of the next release. They are not available in the `1.2.0-1` package used by the introductory guide. The following rules describe this branch.
+
+For native vertical `ion-button` and `ion-menu-button` actions, choose who controls appearance:
+
+| `buttonProjection` | Appearance |
+| --- | --- |
+| `'system'` (default) | SwiftUI styles the buttons and tints their icons. Ionic fill, colors and borders are not applied. |
+| `'source'` | Projects the supported Ionic fill and computed colors described in [Source fill rules](#source-fill-rules). |
+
+```ts
+const rail = await enableVerticalControlArea({ buttonProjection: 'source' });
+```
+
+Both `enableVerticalControlArea()` and `enableNativeUIShell()` accept the option. Use one runtime, and destroy it before restarting with different options. Either mode preserves actions, disabled state and grouping. These appearance settings do not affect horizontal controls, source elements or Web fallback clones, so compare the native appearance on supported iOS.
+
+**Migration:** the default changes from source styling to `system`. Set `buttonProjection: 'source'` to retain the previous projection behavior. This does not change the feature's experimental status.
+
+### Override individual buttons or groups
+
+Use `data-projection` for local exceptions. Existing classes remain supported:
+
+| Attribute | Equivalent class |
+| --- | --- |
+| `data-projection="source"` | `ios-theme-projection-source` |
+| `data-projection="system"` | `ios-theme-projection-system` |
+
+```html
+<ion-buttons data-projection="source">
+  <ion-button fill="solid" aria-label="Add">
+    <ion-icon name="add-outline" slot="icon-only"></ion-icon>
+  </ion-button>
+  <ion-button data-projection="system" aria-label="Search">
+    <ion-icon name="search-outline" slot="icon-only"></ion-icon>
+  </ion-button>
+</ion-buttons>
+```
+
+The first matching setting wins:
+
+1. The button's local setting.
+2. Its nearest `ion-buttons` local setting.
+3. The startup `buttonProjection` option, or `system` if omitted.
+
+On the same element, a valid `data-projection` value takes precedence over the classes. Empty or unknown values are ignored. Without a valid attribute, `system` wins if both classes are present. Removing an attribute falls back to the element's classes, then the next level above. Attribute and class changes apply without restarting the runtime; grouping and placement stay unchanged.
+
+Only native vertical `ion-button` and `ion-menu-button` actions interpret these settings. Other ancestors, back buttons, tabs and FABs do not. They do not change Web styling. To keep a control or subtree on the Web entirely, use [`data-shell="disabled"`](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell#supported-markup).
+
+### Source fill rules
+
+For an `ion-button` resolved to `source`, fill is chosen separately from the projection mode:
+
+| Button | Effective fill |
+| --- | --- |
+| Explicit `fill="clear"`, `"solid"` or `"outline"` | The explicit value |
+| Omitted fill or `fill="default"` inside `ion-buttons` | `clear` |
+| Omitted fill or `fill="default"` outside `ion-buttons` | `buttonDefaultFill` |
+
+`buttonDefaultFill` accepts only `'solid'` or `null`; omission is equivalent to `null`. Use `'solid'` for Ionic's default button design, or `null` for this theme's default glass design. It applies to every button resolved to `source`, including a local exception under a global `system` setting.
+
+```ts
+// Keep system styling globally; local source buttons use Ionic's default fill.
+const rail = await enableVerticalControlArea({ buttonDefaultFill: 'solid' });
+```
+
+```html
+<!-- In a fixed toolbar, outside ion-buttons: omitted fill resolves to solid. -->
+<ion-button data-projection="source" aria-label="Add">
+  <ion-icon name="add-outline" slot="icon-only"></ion-icon>
+</ion-button>
+```
+
+| Effective fill | Native appearance in `source` mode |
+| --- | --- |
+| `clear` | Icon color, without a glass background; CSS backgrounds are ignored |
+| `solid` | Computed background color tints a prominent glass button |
+| `outline` | Computed border color and width, with native glass |
+| `null` | Native glass with source icon colors |
+
+Inside `ion-buttons`, explicitly set `fill="solid"` to project a background; `buttonDefaultFill: 'solid'` does not override the group's clear default. Native Liquid Glass tinting can differ from the CSS color, especially for translucent backgrounds. With the iOS theme, ordinary `ion-buttons` retain group projection; `ion-buttons.ios-theme-disabled` projects eligible buttons individually. Local projection settings do not change that grouping rule.
+
+## Tab bar
+
+When the app contains `ion-tabs`, its tab bar moves into the reserved region and uses the native Duo edge spacing; the Ionic `slot` value does not select a different position. Without native projection, the stable Web rail is icon-only, matching the native resting presentation. While the user presses and drags across that rail, every icon-and-label tab reveals its label so the pending destination stays identifiable. The Web tab bar receives pointer input in the simulated system region. Native tabs and a restored Web tab bar fade in over 180ms; disappearance remains immediate. Reduced motion disables this fade. Use `ion-menu` when navigation should become a sidebar; this mode does not convert tabs into a menu. Web clones also work when no `ion-tabs` exists. Disabling the mode or leaving the page removes the native ownership or Web clones and restores their sources. Override `--ios-theme-vertical-bars-toolbar-top` when the simulated system controls use a different vertical layout.
+
+## Vertical Control Area API
+
+The generated reference below documents the handle returned by `enableVerticalControlArea()`.
+
+<docgen-index>
+
+* [`setPlacement(...)`](#setplacement)
+* [`getStatus()`](#getstatus)
+* [`suspend()`](#suspend)
+* [`destroy()`](#destroy)
+* [Interfaces](#interfaces)
+* [Type Aliases](#type-aliases)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### setPlacement(...)
+
+```typescript
+setPlacement(placement: VerticalBarEdge | VerticalBarPlacement, rtl?: boolean | undefined) => void
+```
+
+Applies the application's chosen placement to both Web and native controls.
+
+| Param           | Type                                                                                                                    |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **`placement`** | <code><a href="#verticalbaredge">VerticalBarEdge</a> \| <a href="#verticalbarplacement">VerticalBarPlacement</a></code> |
+| **`rtl`**       | <code>boolean</code>                                                                                                    |
+
+--------------------
+
+
+### getStatus()
+
+```typescript
+getStatus() => NativeUIShellStatus
+```
+
+Returns the current Web/native projection state.
+
+**Returns:** <code><a href="#nativeuishellstatus">NativeUIShellStatus</a></code>
+
+--------------------
+
+
+### suspend()
+
+```typescript
+suspend() => Promise<NativeUIShellSuspension>
+```
+
+Restores projected controls to the Web until the returned lease is resumed.
+
+**Returns:** <code>Promise&lt;<a href="#nativeuishellsuspension">NativeUIShellSuspension</a>&gt;</code>
+
+--------------------
+
+
+### destroy()
+
+```typescript
+destroy() => Promise<void>
+```
+
+Stops synchronization, restores Web controls and releases native resources.
+
+--------------------
+
+
+### Interfaces
+
+
+#### VerticalBarPlacement
+
+| Prop             | Type                                                        | Description                                                                                                                                                                                                                       |
+| ---------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`edge`**       | <code><a href="#verticalbaredge">VerticalBarEdge</a></code> |                                                                                                                                                                                                                                   |
+| **`inset`**      | <code>number</code>                                         | Explicit rail width in CSS pixels; omitted to use the stylesheet's safe-area rules.                                                                                                                                               |
+| **`nativeEdge`** | <code><a href="#verticalbaredge">VerticalBarEdge</a></code> | Native logical edge reported by the application's device plugin. Null or an unregistered edge uses a Web rail in verticalBarsOnly mode, or the ordinary Native UI Shell layout otherwise. Omission keeps the last supplied value. |
+
+
+#### NativeUIShellStatus
+
+| Prop            | Type                                        |
+| --------------- | ------------------------------------------- |
+| **`state`**     | <code>'native' \| 'stopped' \| 'web'</code> |
+| **`projected`** | <code>number</code>                         |
+| **`updates`**   | <code>number</code>                         |
+| **`reason`**    | <code>string</code>                         |
+
+
+#### NativeUIShellSuspension
+
+| Method     | Signature                    | Description                                                                                    |
+| ---------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
+| **resume** | () =&gt; Promise&lt;void&gt; | Releases this suspension. Native projection resumes after all active suspensions are released. |
+
+
+### Type Aliases
+
+
+#### VerticalBarEdge
+
+Logical edge in the reading direction, matching UIVerticalBarEdge and capacitor-foldable.
+
+<code>'leading' | 'trailing' | null</code>
+
+</docgen-api>

package/ios/Sources/IonicNativeUIShellPlugin/Components/ShellSearchController.swift

@@ -35,7 +35,7 @@ final class ShellSearchHost: UIView {
 }
 
 // Preserve UISearchBar's delegate while returning its clear action to Ionic.
-private final class ShellSearchInputDelegate: NSObject, UITextFieldDelegate {
+final class ShellSearchInputDelegate: NSObject, UITextFieldDelegate {
     weak var original: UITextFieldDelegate?
     var clear: (() -> Void)?
     override func responds(to selector: Selector!) -> Bool {

package/ios/Sources/IonicNativeUIShellPlugin/Components/ShellVerticalBars.swift

@@ -6,6 +6,7 @@ protocol ShellVerticalBarsControlling: AnyObject {
     var view: UIView { get }
     func attach(to owner: UIViewController, in parent: UIView)
     @MainActor func apply(_ controls: [ShellControl], rendering: ShellRendering, edge: String)
+    var ownsKeyboardChrome: Bool { get }
     func detach()
 }
 
@@ -16,6 +17,7 @@ final class ShellVerticalBarsModel: ObservableObject {
         let label: String
         let accessibilityLabel: String
         let image: UIImage?
+        let clear: Bool
         let background: Color?
         let borderColor: Color?
         let borderWidth: CGFloat
@@ -30,6 +32,7 @@ final class ShellVerticalBarsModel: ObservableObject {
         let slot: ShellControl.ToolbarSlot?
     }
 
+    @Published var search: ShellVerticalSearchModel?
     @Published var back: Item?
     @Published var groups: [Group] = []
     @Published var tabs: [Item] = []
@@ -45,6 +48,7 @@ final class ShellVerticalBarsModel: ObservableObject {
             Item(id: source.id, label: source.content.label,
                  accessibilityLabel: source.content.accessibilityLabel,
                  image: rendering.image(source.content),
+                 clear: source.content.buttonFill == .clear,
                  background: source.content.backgroundColor.map { Color(uiColor: rendering.color($0)) },
                  borderColor: source.content.borderColor.map { Color(uiColor: rendering.color($0)) },
                  borderWidth: source.content.borderWidth ?? 0,
@@ -123,6 +127,21 @@ private func verticalBarsButton(_ item: ShellVerticalBarsModel.Item, model: Shel
     }
 }
 
+@available(iOS 26.0, *)
+private struct ShellVerticalBarsButton: ToolbarContent {
+    @ObservedObject var model: ShellVerticalBarsModel
+    let id: String
+    let placement: ToolbarItemPlacement
+
+    // Observe here so same-ID updates also refresh the shared toolbar background.
+    var body: some ToolbarContent {
+        if let item = model.groups.lazy.flatMap(\.items).first(where: { $0.id == id }) {
+            ToolbarItem(placement: placement) { verticalBarsButton(item, model: model) }
+                .sharedBackgroundVisibility(item.clear ? .hidden : .automatic)
+        }
+    }
+}
+
 @available(iOS 26.0, *)
 private func verticalBarsBackButton(_ item: ShellVerticalBarsModel.Item, model: ShellVerticalBarsModel) -> some View {
     Button { model.activate(item.id) } label: { Image(systemName: "chevron.backward") }
@@ -163,6 +182,7 @@ private struct ShellVerticalBarsView: View {
                 }
             }
         }
+        .modifier(ShellVerticalBarsSearch(model: model))
         .modifier(ShellVerticalBarsCompression())
         .background(Color.clear)
     }
@@ -179,6 +199,16 @@ private struct ShellVerticalBarsPage: View {
     }
 }
 
+@available(iOS 26.0, *)
+private struct ShellVerticalBarsSearch: ViewModifier {
+    @ObservedObject var model: ShellVerticalBarsModel
+    @ViewBuilder func body(content: Content) -> some View {
+        if let search = model.search {
+            content.modifier(ShellVerticalSearchModifier(model: search))
+        } else { content }
+    }
+}
+
 @available(iOS 26.0, *)
 private struct ShellVerticalBarsCompression: ViewModifier {
     @ViewBuilder func body(content: Content) -> some View {
@@ -225,20 +255,22 @@ private struct ShellVerticalBarsToolbar: ViewModifier {
                 .axisBehavior(.verticalPreferred)
             }
             ForEach(model.groups.filter { $0.slot == .start }) { group in
-                ToolbarItemGroup(placement: .topBarLeading) {
-                    ForEach(group.items) { item in
-                        verticalBarsButton(item, model: model)
-                    }
+                if group.id != model.groups.first(where: { $0.slot == .start })?.id {
+                    ToolbarSpacer(.fixed, placement: .topBarLeading)
+                }
+                ForEach(group.items) { item in
+                    ShellVerticalBarsButton(model: model, id: item.id, placement: .topBarLeading)
+                    .axisBehavior(.verticalPreferred)
                 }
-                .axisBehavior(.verticalPreferred)
             }
             ForEach(model.groups.filter { $0.slot != .start }) { group in
-                ToolbarItemGroup(placement: .topBarTrailing) {
-                    ForEach(group.items) { item in
-                        verticalBarsButton(item, model: model)
-                    }
+                if group.id != model.groups.first(where: { $0.slot != .start })?.id {
+                    ToolbarSpacer(.fixed, placement: .topBarTrailing)
+                }
+                ForEach(group.items) { item in
+                    ShellVerticalBarsButton(model: model, id: item.id, placement: .topBarTrailing)
+                    .axisBehavior(.verticalPreferred)
                 }
-                .axisBehavior(.verticalPreferred)
             }
         }
     }
@@ -257,10 +289,11 @@ private struct ShellVerticalBarsLegacyToolbar: ViewModifier {
                 }
             }
             ForEach(model.groups) { group in
-                ToolbarItemGroup(placement: .primaryAction) {
-                    ForEach(group.items) { item in
-                        verticalBarsButton(item, model: model)
-                    }
+                if group.id != model.groups.first?.id {
+                    ToolbarSpacer(.fixed, placement: .primaryAction)
+                }
+                ForEach(group.items) { item in
+                    ShellVerticalBarsButton(model: model, id: item.id, placement: .primaryAction)
                 }
             }
         }
@@ -271,9 +304,11 @@ private struct ShellVerticalBarsLegacyToolbar: ViewModifier {
 final class ShellVerticalBarsController: ShellVerticalBarsControlling {
     private final class TransparentHostingController<Content: View>: UIHostingController<Content> {
         var railEdge = "right"
+        var layoutSearch: (() -> Void)?
         override func viewDidLayoutSubviews() {
             super.viewDidLayoutSubviews()
             makeFullSizeSurfacesTransparent(in: view)
+            layoutSearch?()
         }
 
         private func makeFullSizeSurfacesTransparent(in surface: UIView) {
@@ -323,7 +358,7 @@ final class ShellVerticalBarsController: ShellVerticalBarsControlling {
         private func containsBarSurface(in view: UIView, at point: CGPoint) -> Bool {
             guard !view.isHidden, view.alpha > 0.05 else { return false }
             let name = NSStringFromClass(type(of: view))
-            if (name.contains("TabBar") || name.contains("Platter") || name.contains("Pocket") || name.contains("Sidebar")),
+            if (name.contains("TabBar") || name.contains("Platter") || name.contains("Pocket") || name.contains("Sidebar") || view is UISearchBar || view is UINavigationBar),
                convert(view.bounds, from: view).contains(point) { return true }
             return view.subviews.contains { containsBarSurface(in: $0, at: point) }
         }
@@ -333,14 +368,20 @@ final class ShellVerticalBarsController: ShellVerticalBarsControlling {
     private lazy var controller = TransparentHostingController(rootView: ShellVerticalBarsView(model: model))
     private let container = RailContainer()
     private weak var owner: UIViewController?
+    private let changed: (String, ShellSearchPhase, String, Bool, Int) -> Int
 
     var view: UIView { container }
 
-    init(activate: @escaping (String) -> Void) {
+    var ownsKeyboardChrome: Bool { model.search?.ownsKeyboardChrome == true }
+
+    init(activate: @escaping (String) -> Void,
+         changed: @escaping (String, ShellSearchPhase, String, Bool, Int) -> Int) {
+        self.changed = changed
         model.activate = activate
         container.backgroundColor = .clear
         controller.view.backgroundColor = .clear
         controller.view.isOpaque = false
+        controller.layoutSearch = { [weak self] in self?.model.search?.configureField() }
     }
 
     func attach(to owner: UIViewController, in parent: UIView) {
@@ -361,6 +402,10 @@ final class ShellVerticalBarsController: ShellVerticalBarsControlling {
         container.railEdge = edge
         controller.railEdge = edge
         let tabsAppear = model.tabs.isEmpty && controls.contains { $0.kind == .tabBar && !$0.items.isEmpty }
+        if let search = controls.first(where: { $0.search != nil })?.search {
+            if model.search?.configuration.id == search.id { model.search?.apply(search) }
+            else { model.search = ShellVerticalSearchModel(search, in: container, activate: model.activate, changed: changed) }
+        } else { model.search = nil }
         model.apply(controls, rendering: rendering)
         if tabsAppear { ShellCrossfade.enter(container, duration: ShellCrossfade.duration(180)) }
         controller.overrideUserInterfaceStyle = controls.contains(where: \.dark) ? .dark : .light