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

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

@@ -0,0 +1,118 @@
+import Combine
+import SwiftUI
+import UIKit
+
+@available(iOS 26.0, *)
+final class ShellVerticalSearchModel: ObservableObject {
+    @Published private(set) var configuration: ShellSearch
+    @Published var text: String
+    @Published var presented: Bool
+    @Published var focused: Bool
+    private weak var railView: UIView?
+    private let activate: (String) -> Void
+    private let changed: (String, ShellSearchPhase, String, Bool, Int) -> Int
+    private let inputDelegate = ShellSearchInputDelegate()
+    private var editingSequence = 0
+    private var valueVersion: Int
+
+    init(_ configuration: ShellSearch, in railView: UIView,
+         activate: @escaping (String) -> Void,
+         changed: @escaping (String, ShellSearchPhase, String, Bool, Int) -> Int) {
+        self.configuration = configuration
+        self.railView = railView
+        self.activate = activate
+        self.changed = changed
+        text = configuration.value
+        presented = configuration.available && configuration.active
+        focused = configuration.focused
+        valueVersion = configuration.valueVersion
+        inputDelegate.clear = { [weak self] in self?.emit(.clear) }
+    }
+
+    var ownsKeyboardChrome: Bool { presented && (focused || textField?.isFirstResponder == true) }
+
+    private var textField: UISearchTextField? {
+        func find(_ view: UIView) -> UISearchTextField? {
+            guard !view.isHidden, view.alpha > 0.01 else { return nil }
+            if let field = view as? UISearchTextField { return field }
+            for child in view.subviews {
+                if let field = find(child) { return field }
+            }
+            return nil
+        }
+        return railView.flatMap(find)
+    }
+
+    func apply(_ next: ShellSearch) {
+        let previous = configuration
+        configuration = next
+        if next.valueVersion != valueVersion || next.editSequence >= editingSequence {
+            valueVersion = next.valueVersion
+            text = next.value
+        }
+        presented = next.available && next.active
+        // The first Web acknowledgement still carries the old focus state.
+        if !next.active { focused = false }
+        else if previous.focused != next.focused { focused = next.focused }
+    }
+
+    func input(_ value: String) {
+        text = value
+        emit(.input)
+    }
+
+    func present(_ value: Bool) {
+        presented = value
+        if value != configuration.active {
+            activate(value ? configuration.trigger.id : configuration.closeId)
+        }
+    }
+
+    func focus(_ value: Bool) {
+        focused = value
+        emit(value ? .focus : .blur)
+    }
+
+    func commit() { emit(.commit) }
+
+    func configureField() {
+        guard let field = textField else { return }
+        field.accessibilityIdentifier = configuration.id
+        field.accessibilityLabel = configuration.field.accessibilityLabel
+        field.isEnabled = !configuration.disabled
+        field.autocapitalizationType = .none
+        field.autocorrectionType = .no
+        field.spellCheckingType = .no
+        field.clearButtonMode = .always
+        if field.delegate !== inputDelegate {
+            inputDelegate.original = field.delegate
+            field.delegate = inputDelegate
+        }
+    }
+
+    private func emit(_ phase: ShellSearchPhase) {
+        editingSequence = changed(configuration.id, phase, text,
+                                  textField?.markedTextRange != nil, valueVersion)
+    }
+}
+
+@available(iOS 26.0, *)
+struct ShellVerticalSearchModifier: ViewModifier {
+    @ObservedObject var model: ShellVerticalSearchModel
+    @FocusState private var focused: Bool
+
+    @ViewBuilder func body(content: Content) -> some View {
+        if model.configuration.available {
+            content
+                .searchable(text: Binding(get: { model.text }, set: model.input),
+                            isPresented: Binding(get: { model.presented }, set: model.present),
+                            placement: .toolbar, prompt: Text(model.configuration.placeholder))
+                .searchToolbarBehavior(.minimize)
+                .searchPresentationToolbarBehavior(.avoidHidingContent)
+                .searchFocused($focused)
+                .onSubmit(of: .search, model.commit)
+                .onChange(of: focused) { _, value in model.focus(value) }
+                .onChange(of: model.focused) { _, value in focused = value }
+        } else { content }
+    }
+}

package/ios/Sources/IonicNativeUIShellPlugin/IonicNativeUIShellPlugin.swift

@@ -46,7 +46,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
                     self.host?.isHidden = true
                     self.verticalBars?.view.isHidden = true
                 }
-                var searchOwnsKeyboard = false
+                var searchOwnsKeyboard = self.verticalBars?.ownsKeyboardChrome == true
                 self.searchControllers.values.forEach { controller in
                     if controller.ownsKeyboardChrome { searchOwnsKeyboard = true }
                     if !keyboard { controller.surface.isHidden = true }
@@ -195,6 +195,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
             let existing = Set(self.controls.keys)
             let verticalBars = snapshot.controls.filter { $0.placement == .verticalBars }
             let snapshots = snapshot.controls.filter { $0.placement != .verticalBars }
+            let verticalSearchActive = verticalBars.contains { $0.search.map { $0.available && $0.active } ?? false }
             let width = snapshot.viewportWidth
             self.revision = next
             if snapshots.isEmpty && verticalBars.isEmpty {
@@ -210,12 +211,16 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
             var fabs: [(ShellFab, ShellControl)] = []
             var searches: [(ShellSearchControlling, ShellControl, CGRect, CGRect, UIView?, Bool)] = []
             var rejectedSearches: [String] = []
-            if verticalBars.isEmpty || self.keyboardVisible {
+            if verticalBars.isEmpty || (self.keyboardVisible && !verticalSearchActive) {
                 self.verticalBars?.detach()
                 self.verticalBars = nil
                 if self.keyboardVisible { rejectedControls.append(contentsOf: verticalBars.map(\.id)) }
             } else if let owner = self.bridge?.viewController {
-                let rail = self.verticalBars ?? ShellVerticalBarsController(activate: { [weak self] id in self?.activate(id) })
+                let rail = self.verticalBars ?? ShellVerticalBarsController(
+                    activate: { [weak self] id in self?.activate(id) },
+                    changed: { [weak self] id, phase, value, composing, valueVersion in
+                        self?.searchChanged(id, phase: phase, value: value, composing: composing, valueVersion: valueVersion) ?? 0
+                    })
                 self.verticalBars = rail
                 rail.attach(to: owner, in: owner.view)
                 if let frame = snapshot.verticalBarFrame {
@@ -274,11 +279,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
                             controller = ShellSearchController()
                             controller.activate = { [weak self] id in self?.activate(id) }
                             controller.changed = { [weak self] id, phase, value, composing, valueVersion in
-                                guard let self else { return 0 }
-                                self.sequence += 1
-                                self.notifyListeners("search", data: ["id": id, "phase": phase.rawValue, "value": value,
-                                    "composing": composing, "valueVersion": valueVersion, "sequence": self.sequence, "revision": self.revision])
-                                return self.sequence
+                                self?.searchChanged(id, phase: phase, value: value, composing: composing, valueVersion: valueVersion) ?? 0
                             }
                             controller.attach(to: owner, in: owner.view)
                             self.searchControllers[id] = controller
@@ -379,6 +380,14 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
         activate(itemId)
     }
 
+    private func searchChanged(_ id: String, phase: ShellSearchPhase, value: String,
+                               composing: Bool, valueVersion: Int) -> Int {
+        sequence += 1
+        notifyListeners("search", data: ["id": id, "phase": phase.rawValue, "value": value,
+            "composing": composing, "valueVersion": valueVersion, "sequence": sequence, "revision": revision])
+        return sequence
+    }
+
     private func activate(_ id: String) {
         sequence += 1
         notifyListeners("activate", data: ["id": id, "revision": revision, "sequence": sequence])

package/ios/Sources/IonicNativeUIShellPlugin/Shared/ShellSnapshot.swift

@@ -99,6 +99,7 @@ struct ShellBadge: Decodable, Equatable {
 
 struct ShellItemContent: Decodable, Equatable {
     enum IconPosition: String, Decodable { case leading, trailing, top }
+    enum ButtonFill: String, Decodable { case clear, solid, outline }
     let id: String
     var label: String
     let accessibilityLabel: String
@@ -107,6 +108,7 @@ struct ShellItemContent: Decodable, Equatable {
     let fontSize: Double
     let fontWeight: Double
     let color: String
+    let buttonFill: ButtonFill?
     let backgroundColor: String?
     let borderColor: String?
     let borderWidth: CGFloat?

package/ios/Tests/IonicNativeUIShellPluginTests/ShellSnapshotTests.swift

@@ -53,16 +53,19 @@ final class ShellSnapshotTests: XCTestCase {
         guard #available(iOS 26.0, *) else { throw XCTSkip("Requires SwiftUI adaptive controls") }
         let controls = try decode([control(["kind": "ion-buttons", "items": [
             item(["backgroundColor": "rgb(0, 122, 255)"]),
+            item(["id": "clear", "buttonFill": "clear"]),
             item(["id": "outline", "borderColor": "rgb(255, 0, 0)", "borderWidth": 2.0])
         ]])]).controls
         XCTAssertEqual(controls.first?.items.first?.content.backgroundColor, "rgb(0, 122, 255)")
         let model = ShellVerticalBarsModel()
         model.apply(controls, rendering: ShellRendering())
         XCTAssertNotNil(model.groups.first?.items.first?.background)
+        XCTAssertEqual(model.groups.first?.items.map(\.clear), [false, true, false])
         XCTAssertNotNil(model.groups.first?.items.last?.borderColor)
         XCTAssertEqual(model.groups.first?.items.last?.borderWidth, 2)
         model.apply(try decode([control(["kind": "ion-button"])]).controls, rendering: ShellRendering())
         XCTAssertNil(model.groups.first?.items.first?.background)
+        XCTAssertEqual(model.groups.first?.items.first?.clear, false)
         XCTAssertNil(model.groups.first?.items.first?.borderColor)
         XCTAssertEqual(model.groups.first?.items.first?.borderWidth, 0)
     }
@@ -607,4 +610,41 @@ final class ShellSnapshotTests: XCTestCase {
         XCTAssertEqual(phases, ["input"])
     }
 
+    func testVerticalSearchBridgesInputFocusAndDismissalWithoutStaleWebEchoes() throws {
+        guard #available(iOS 26.0, *) else { throw XCTSkip("Requires native glass search") }
+        func node(active: Bool, value: String = "", version: Int = 0) throws -> ShellControl {
+            let search: JSObject = ["id": "search", "field": item(),
+                "trigger": item(["id": "trigger"]), "closeId": "close", "active": active,
+                "available": true, "focused": false, "value": value, "placeholder": "Search",
+                "disabled": false, "editSequence": 0, "valueVersion": version]
+            return try XCTUnwrap(decode([control(["kind": "ion-tab-bar", "placement": "vertical-bars",
+                "search": search, "items": [item(["id": "first", "selected": true]), item(["id": "second"])]])]).controls.first)
+        }
+        var actions: [String] = []
+        var values: [String] = []
+        let rail = UIView()
+        let model = ShellVerticalSearchModel(try XCTUnwrap(node(active: false).search), in: rail,
+            activate: { actions.append($0) },
+            changed: { _, _, value, _, _ in values.append(value); return values.count })
+        model.present(true)
+        XCTAssertEqual(actions, ["trigger"])
+        model.apply(try XCTUnwrap(node(active: true).search))
+        XCTAssertTrue(model.presented)
+        model.input("native query")
+        XCTAssertEqual(values, ["native query"])
+        model.apply(try XCTUnwrap(node(active: true).search))
+        XCTAssertEqual(model.text, "native query")
+        // The first presentation acknowledgement must not undo native focus.
+        model.focus(true)
+        model.apply(try XCTUnwrap(node(active: true).search))
+        XCTAssertTrue(model.focused)
+        model.apply(try XCTUnwrap(node(active: true, value: "application", version: 1).search))
+        XCTAssertEqual(model.text, "application")
+        model.present(false)
+        XCTAssertEqual(actions, ["trigger", "close"])
+        model.apply(try XCTUnwrap(node(active: false).search))
+        XCTAssertFalse(model.presented)
+        XCTAssertFalse(model.focused)
+    }
+
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rdlabo/ionic-theme-ios27",
   "private": false,
-  "version": "1.2.0-2",
+  "version": "1.2.0-4",
   "description": "iOS27 Theme for Ionic Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -34,13 +34,14 @@
     "build": "npm run docgen && npm run build:css && npm run build:ts",
     "prebuild:css": "rdlabo-copy-structured-list src/styles/utils/structured-list.scss",
     "build:css": "rm -rf dist/css && sass src/styles:dist/css --style=compressed --no-source-map",
-    "build:ts": "tsc",
-    "docgen": "docgen --project tsconfig.docgen.json --api NativeUIShellHandle --output-readme docs/native-ui-shell.md && docgen --project tsconfig.docgen.json --api VerticalControlAreaHandle --output-readme docs/iphone-duo.md",
+    "build:ts": "tsc --noEmit && rdlabo-build-theme",
+    "docgen": "docgen --project tsconfig.docgen.json --api NativeUIShellHandle --output-readme docs/native-ui-shell.md && docgen --project tsconfig.docgen.json --api VerticalControlAreaHandle --output-readme docs/vertical-bars.md",
     "build:demo": "npm run build && cd demo && npm install && npm run build -- --configuration=production",
     "lint": "prettier --check \"./**/*.{scss,ts}\" &&  prettier --parser angular --check \"./**/*.html\"",
     "fmt": "prettier --write \"./**/*.{scss,ts}\" &&  prettier --parser angular --write \"./**/*.html\"",
     "release": "np --no-tests --no-publish",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test:esm": "rdlabo-check-esm"
   },
   "repository": {
     "type": "git",
@@ -60,7 +61,7 @@
   },
   "homepage": "https://docs.rdlabo.dev/projects/ionic-theme-ios27",
   "dependencies": {
-    "@rdlabo/ionic-theme-utils": "0.1.1"
+    "@rdlabo/ionic-theme-utils": "0.1.2"
   },
   "devDependencies": {
     "@capacitor/core": "^8.5.2",
@@ -71,6 +72,7 @@
     "np": "^10.2.0",
     "prettier": "^3.6.2",
     "sass": "^1.93.2",
+    "tsdown": "^0.23.0",
     "typescript": "^5.9.3",
     "wrangler": "^4.125.0"
   },
@@ -87,5 +89,6 @@
     "ios": {
       "src": "ios"
     }
-  }
+  },
+  "type": "module"
 }

package/src/native/components/index.ts

@@ -1,3 +1,4 @@
+import type { VerticalControlAreaOptions } from '../definitions';
 import * as button from './ion-button';
 import * as buttons from './ion-buttons';
 import * as backButton from './ion-back-button';
@@ -29,7 +30,7 @@ export const motionSelector = [
 
 export const isVerticalBarsCandidate = isVerticalBarsSource;
 
-export const readCandidate = (element: HTMLElement, id: Identify): Candidate | undefined => {
+export const readCandidate = (element: HTMLElement, id: Identify, options: VerticalControlAreaOptions = {}): Candidate | undefined => {
   const verticalBars = isVerticalBarsCandidate(element);
   if (
     (!element.classList.contains('ios') && !verticalBars) ||
@@ -47,5 +48,5 @@ export const readCandidate = (element: HTMLElement, id: Identify): Candidate | u
   )
     return;
   if (element.contains(element.ownerDocument.activeElement)) return;
-  return components.find((component) => component.tag === element.localName)?.read(element, id);
+  return components.find((component) => component.tag === element.localName)?.read(element, id, options);
 };

package/src/native/components/ion-button.ts

@@ -1,3 +1,4 @@
+import type { VerticalControlAreaOptions } from '../definitions';
 import { modalUsesVerticalBars } from '../shared/modal';
 import { createCandidate, appendItem } from '../shared/candidate';
 import type { Candidate, Identify } from '../shared/candidate';
@@ -5,7 +6,7 @@ import { inFixedToolbar, isVerticalBarsToolbarAction, isVerticalBarsToolbarGroup
 
 export const tag = 'ion-button';
 
-export const read = (element: HTMLElement, id: Identify): Candidate | undefined => {
+export const read = (element: HTMLElement, id: Identify, options: VerticalControlAreaOptions = {}): Candidate | undefined => {
   const button = element as HTMLIonButtonElement;
   const verticalBars =
     !element.closest('ion-menu, ion-popover') && modalUsesVerticalBars(element) && !!element.closest('ion-app.ios-theme-vertical-bars');
@@ -18,6 +19,6 @@ export const read = (element: HTMLElement, id: Identify): Candidate | undefined
     (!verticalBars && button.classList.contains('ion-color'))
   )
     return;
-  const candidate = createCandidate(element, tag, id);
+  const candidate = createCandidate(element, tag, id, options);
   return appendItem(candidate, element, id) ? candidate : undefined;
 };

package/src/native/components/ion-buttons.ts

@@ -1,3 +1,4 @@
+import type { VerticalControlAreaOptions } from '../definitions';
 import { modalUsesVerticalBars } from '../shared/modal';
 import { createCandidate, appendItem } from '../shared/candidate';
 import type { Candidate, Identify } from '../shared/candidate';
@@ -7,10 +8,10 @@ import * as menuButton from './ion-menu-button';
 export const tag = 'ion-buttons';
 export const tracksMotion = true;
 
-export const read = (element: HTMLElement, id: Identify): Candidate | undefined => {
+export const read = (element: HTMLElement, id: Identify, options: VerticalControlAreaOptions = {}): Candidate | undefined => {
   if (!inFixedToolbar(element)) return;
   let children = childElements(element);
-  if (children.length === 1) return menuButton.read(element, id);
+  if (children.length === 1) return menuButton.read(element, id, options);
   const verticalBars =
     !element.closest('ion-menu, ion-popover') && modalUsesVerticalBars(element) && !!element.closest('ion-app.ios-theme-vertical-bars');
   if (verticalBars && !isVerticalBarsToolbarGroup(element)) return;
@@ -25,7 +26,7 @@ export const read = (element: HTMLElement, id: Identify): Candidate | undefined
     )
   )
     return;
-  const candidate = createCandidate(element, tag, id);
+  const candidate = createCandidate(element, tag, id, options);
   if (verticalBars && children.length !== childElements(element).length) candidate.sources = children;
   for (const child of children) {
     const supported = child.matches(menuButton.tag)

package/src/native/components/ion-menu-button.ts

@@ -1,5 +1,6 @@
 import { createCandidate, appendItem } from '../shared/candidate';
 import type { Candidate, Identify } from '../shared/candidate';
+import type { VerticalControlAreaOptions } from '../definitions';
 import { childElements, inFixedToolbar } from '../shared/dom';
 
 export const tag = 'ion-menu-button';
@@ -13,11 +14,11 @@ export const append = (candidate: Candidate, button: HTMLIonMenuButtonElement, i
   return !!content && !!appendItem(candidate, button, id, content);
 };
 
-export const read = (group: HTMLElement, id: Identify): Candidate | undefined => {
+export const read = (group: HTMLElement, id: Identify, options: VerticalControlAreaOptions = {}): Candidate | undefined => {
   const children = group.matches('ion-buttons') ? childElements(group) : [];
   if (!inFixedToolbar(group) || children.length !== 1) return;
   const button = children[0];
   if (!button?.matches(`${tag}${group.closest('ion-app.ios-theme-vertical-bars') ? '' : '.ios'}`)) return;
-  const candidate = createCandidate(group, tag, id);
+  const candidate = createCandidate(group, tag, id, options);
   return append(candidate, button as HTMLIonMenuButtonElement, id) ? candidate : undefined;
 };

package/src/native/components/searchable-tabs.ts

@@ -167,7 +167,12 @@ export const createSearchSupport = (doc: Document, id: (element: Element) => str
     keyboard(visible: boolean) {
       keyboardVisible = visible;
       if (!visible) {
-        states.forEach((state) => (state.keyboardHidden = false));
+        for (const [binding, state] of states) {
+          // Ionic can wait for the pre-keyboard height indefinitely after rotation.
+          // Release the visibility override we own when native search's keyboard closes.
+          if (state.keyboardHidden) binding.tabBar.classList.remove('tab-bar-hidden');
+          state.keyboardHidden = false;
+        }
         releaseKeyboardResize();
       }
       schedule();
@@ -202,15 +207,7 @@ export const createSearchSupport = (doc: Document, id: (element: Element) => str
       };
       for (const binding of bindings) {
         const candidate = candidates.find((c) => c.element === binding.tabBar);
-        // The vertical rail has no search surface; hiding the FAB/footer there
-        // would leave searchable tabs without any search control.
-        if (
-          !candidate ||
-          candidate.control.search ||
-          candidate.control.placement === 'vertical-bars' ||
-          binding.tabBar.getAttribute('slot') !== 'bottom'
-        )
-          continue;
+        if (!candidate || candidate.control.search || binding.tabBar.getAttribute('slot') !== 'bottom') continue;
         const fab = binding.trigger.parentElement;
         // Search also supports the existing page-level fixed FAB, outside scrolling content.
         if (
@@ -441,8 +438,8 @@ export const createSearchSupport = (doc: Document, id: (element: Element) => str
     },
     retire(binding: NativeSearchBinding) {
       const state = states.get(binding);
+      // Keep ownership until keyboardWillHide can release this class.
       if (state?.keyboardHidden && keyboardVisible) binding.tabBar.classList.add('tab-bar-hidden');
-      if (state) state.keyboardHidden = false;
       if (state?.focused) {
         state.focused = false;
         state.input.dispatchEvent(new FocusEvent('blur'));

package/src/native/definitions.ts

@@ -10,7 +10,26 @@ export interface NativeUIShellStatus {
   reason?: string;
 }
 
-export interface NativeUIShellOptions {
+export interface VerticalControlAreaOptions {
+  /** Appearance of native vertical ion-button and ion-menu-button actions.
+   * `system` (default) uses SwiftUI styling and template icons; `source` projects supported Ionic fill and colors.
+   * Local data-projection="source|system" or ios-theme-projection-source / ios-theme-projection-system take precedence:
+   * the button itself, then its nearest ion-buttons, then this option. On the same element, a valid attribute wins;
+   * otherwise system wins if both classes are present. Invalid attribute values are ignored.
+   * Local settings update live; removing them restores inheritance. Actions, disabled state and grouping are preserved.
+   * Does not affect back buttons, tabs, FABs, horizontal controls, source elements or Web clones.
+   */
+  buttonProjection?: 'source' | 'system';
+  /** Default fill for native vertical ion-button actions resolved to `source`, including local overrides.
+   * Use `solid` for Ionic's default design, or `null` (also the omitted default) for the iOS theme's glass design.
+   * Applies when fill is omitted or `default`, outside ion-buttons. Inside ion-buttons the default is clear.
+   * Explicit clear, solid and outline take precedence; clear and outline cannot be configured as defaults.
+   * Source elements and Web clones are unchanged.
+   */
+  buttonDefaultFill?: 'solid' | null;
+}
+
+export interface NativeUIShellOptions extends VerticalControlAreaOptions {
   /** Enables Native UI Shell globally. Defaults to `true`. */
   enabled?: boolean;
   /** Controls eligible for native projection. Omit to enable every control; when present, only `true` controls are enabled. */
@@ -82,6 +101,8 @@ export interface ShellItem extends Frame {
   fontSize: number;
   fontWeight: number;
   color: string;
+  /** Resolved ion-button fill for vertical projection; clear omits the native glass background. */
+  buttonFill?: 'clear' | 'solid' | 'outline';
   backgroundColor?: string;
   borderColor?: string;
   borderWidth?: number;

package/src/native/foldable/fold-state.ts

@@ -0,0 +1,9 @@
+import type { FoldState } from './types';
+
+/** Keep posture on ion-app so descendants can follow it through CSS. */
+export function applyFoldStateClasses(root: HTMLElement, fold: FoldState): void {
+  for (const state of ['flat', 'half-opened', 'closed']) {
+    root.classList.toggle(`ios-theme-fold-${state}`, fold.state === state);
+  }
+  root.classList.toggle('ios-theme-fold-expanded', fold.state === 'half-opened' || (fold.state === 'flat' && !!fold.hingeBounds));
+}

package/src/native/foldable/types.ts

@@ -0,0 +1,4 @@
+export interface FoldState {
+  state: 'flat' | 'half-opened' | 'closed';
+  hingeBounds?: { x: number; y: number; width: number; height: number };
+}

package/src/native/index.ts

@@ -7,6 +7,7 @@ import type {
   VerticalBarEdge,
   VerticalBarPlacement,
   VerticalControlAreaHandle,
+  VerticalControlAreaOptions,
   WebViewMetrics,
 } from './definitions';
 import { createRuntime } from './runtime';
@@ -23,6 +24,7 @@ export type {
   VerticalBarEdge,
   VerticalBarPlacement,
   VerticalControlAreaHandle,
+  VerticalControlAreaOptions,
   WebViewMetrics,
 } from './definitions';
 
@@ -160,9 +162,18 @@ export const setVerticalControlAreaPlacement = (placement: VerticalBarEdge | Ver
   document.defaultView?.dispatchEvent(new Event('nativeUIShellRefresh'));
 };
 
-/** Call once at application startup. Ionic markup remains the source of truth. */
-export const enableVerticalControlArea = async (): Promise<VerticalControlAreaHandle> => {
-  const handle = await enableNativeUIShell({ controls: { tabs: true, toolbar: true }, verticalBarsOnly: true });
+/**
+ * Call once after ion-app is mounted. Ionic markup remains the source of truth.
+ * Native vertical buttons default to SwiftUI appearance.
+ * See VerticalControlAreaOptions for source styling and local overrides.
+ */
+export const enableVerticalControlArea = async (options: VerticalControlAreaOptions = {}): Promise<VerticalControlAreaHandle> => {
+  const handle = await enableNativeUIShell({
+    buttonProjection: options.buttonProjection,
+    buttonDefaultFill: options.buttonDefaultFill,
+    controls: { tabs: true, toolbar: true },
+    verticalBarsOnly: true,
+  });
   return {
     getStatus: () => handle.getStatus(),
     suspend: () => handle.suspend(),
@@ -188,6 +199,9 @@ export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise
   const controls = options.controls;
   const configuration = JSON.stringify([
     options.verticalBarsOnly === true,
+    options.buttonProjection ?? 'system',
+    // Local source overrides can use this even when the startup projection is system.
+    options.buttonDefaultFill ?? null,
     ...(['tabs', 'toolbar', 'segment', 'fab'] as const).map((component) => !controls || controls[component] === true),
   ]);
   if (active && activeConfiguration !== configuration)

package/src/native/prehide.ts

@@ -74,6 +74,8 @@ export const prehideVerticalBarsToolbarSources = (doc: Document): { suspend: ()
     };
     const sources = scope.matches('ion-back-button') ? [scope] : Array.from(scope.querySelectorAll<HTMLElement>(sourceSelector));
     sources.forEach((element) => {
+      // Shell opt-out is temporary; decide initial placement once it is lifted.
+      if (isShellDisabled(element)) return;
       if (!modalUsesVerticalBars(element) || element.closest(overlays) || (scope.matches('.ion-page') && routedPage(element) !== scope))
         return;
       if (element.matches('ion-buttons')) {
@@ -228,7 +230,7 @@ export const prehideVerticalBarsToolbarSources = (doc: Document): { suspend: ()
     childList: true,
     attributes: true,
     attributeOldValue: true,
-    attributeFilter: ['class', 'hidden', 'inert', 'icon', 'color'],
+    attributeFilter: ['class', 'data-shell', 'hidden', 'inert', 'icon', 'color'],
   });
   return {
     suspend: () => {

package/src/native/runtime.ts

@@ -172,14 +172,14 @@ export const createRuntime = async (
       measuringPointerPages.add(pointerPage);
       pointerPage.style.setProperty('pointer-events', 'auto', 'important');
       try {
-        candidate = readCandidate(element, id);
+        candidate = readCandidate(element, id, options);
       } finally {
         if (previous) pointerPage.style.setProperty('pointer-events', previous, priority);
         else pointerPage.style.removeProperty('pointer-events');
         if (!hadStyle && !pointerPage.style.length) pointerPage.removeAttribute('style');
         win.setTimeout(() => measuringPointerPages.delete(pointerPage), 0);
       }
-    } else candidate = readCandidate(element, id);
+    } else candidate = readCandidate(element, id, options);
     if (candidate && isVerticalBarsCandidate(element)) {
       if (!nativeVerticalBars()) return undefined;
       candidate.control.placement = 'vertical-bars';
@@ -608,24 +608,29 @@ export const createRuntime = async (
     'focusout',
   ])
     on(doc, name);
-  on(doc, 'visibilitychange', () => {
-    if (doc.hidden) getNativeSearchBindings(doc).forEach((binding) => search.retire(binding));
+  const refreshLayout = () => {
+    rejected = new WeakMap();
+    forceRefresh = true;
     schedule();
+  };
+  on(doc, 'visibilitychange', () => {
+    if (doc.hidden) {
+      getNativeSearchBindings(doc).forEach((binding) => search.retire(binding));
+      schedule();
+    } else refreshLayout();
   });
-  on(win, 'resize');
+  on(win, 'resize', refreshLayout);
   on(win, 'keyboardWillShow', () => search.keyboard(true));
   on(win, 'keyboardWillHide', () => search.keyboard(false));
   on(win, 'scroll');
   on(win.matchMedia('(prefers-color-scheme: dark)'), 'change');
   on(win, 'nativeUIShellRefresh', (event) => {
-    rejected = new WeakMap();
     if ((event as Event & { retireSearch?: boolean }).retireSearch)
       getNativeSearchBindings(doc).forEach((binding) => search.retire(binding));
-    forceRefresh = true;
-    schedule();
+    refreshLayout();
   });
   if (win.visualViewport) {
-    on(win.visualViewport, 'resize');
+    on(win.visualViewport, 'resize', refreshLayout);
     on(win.visualViewport, 'scroll');
   }
   const handle: NativeUIShellHandle = {