@rdlabo/capacitor-native-ui 1.2.1 → 2.0.0-2

package/docs/vertical-bars.md

@@ -1,46 +1,86 @@
 ---
-title: Vertical Bars (preview)
+title: Vertical Bars
 ---
 
-# Vertical Bars (preview)
+# Vertical Bars
 
-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 the iOS theme or an existing Ionic theme, independently of hinge posture and the full Native UI.
+Vertical Bars moves eligible Ionic controls or explicitly marked HTML buttons into a side rail while keeping the original elements as the source of labels, icons and behavior. It works with the iOS theme or an existing Ionic theme, independently of hinge posture and the full Native UI.
 
-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://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo.md). For a step-by-step browser preview and native setup, start with [iPhone Duo with your existing theme](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo-with-original-theme.md).
+Choose your setup before using this reference:
 
-Available in `1.2.0` as a **preview** feature. APIs and supported behavior may change.
+- **Ionic with a custom or default theme:** [Ionic rail setup](ionic-vertical-bars.md#try-it-in-your-existing-ionic-app).
+- **No Ionic:** [HTML setup](framework-independent.md) and its [device rail setup](framework-independent.md#device-placement-for-vertical-bars). Use `/core` and your own layout; the Ionic setup below does not apply.
+- **Existing iOS 27 theme and Native UI:** [Connect device placement](../../capacitor-native-ui/docs/vertical-bars.md#use-with-capacitor-foldable) using your existing runtime.
+
+This page covers device-plugin integration, control eligibility, native appearance and runtime options. For posture-driven Ionic split panes, see [Device layout and split panes](../../theme-ios27/docs/vertical-bars-layout.md).
+
+Vertical Bars and iPhone Duo support are stable starting with version 2.0.0.
 
 See [shared configuration](configuration.md) for all defaults and live `rail.enableVerticalControlArea()` / `rail.disableVerticalControlArea()` methods. [Plain HTML controls](framework-independent.md) use the same native rail renderers.
 
 ## Enable Vertical Bars
 
-Install the native package as a direct dependency:
+Install Native UI and the required Foldable device-state plugin as direct application dependencies:
 
 ```sh
-npm install @rdlabo/capacitor-native-ui
+npm install @rdlabo/capacitor-native-ui @erkamyaman/capacitor-foldable
 ```
 
-For Capacitor iOS, build your Web assets and run `npx cap sync ios`. Supply the Web layout through your app or theme as described below.
+For Ionic, follow the [standard setup](ionic-vertical-bars.md): load your rail CSS, configure navigation, then connect Foldable's initial placement and `barPlacementChange` events before starting one runtime. The [integration below](#use-with-capacitor-foldable) also covers existing runtimes and application-owned CSS. Build your Web assets, run `npx cap sync ios`, and rebuild the native app.
+
+A runtime alone does not reserve Web space. Keep the device subscription for the standard setup; manual placement belongs to the [optional browser preview](ionic-vertical-bars.md#optional-browser-preview). If Native UI is already active, reuse it rather than starting another runtime.
+
+The `/vertical-bars` entry point requires `@capacitor/core`, including in browser builds. Using only the theme’s rail CSS needs no native runtime. For native setup and navigation transitions, follow the [existing-theme guide](ionic-vertical-bars.md).
+
+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.
+
+## Placement and Web layout
+
+The application or theme owns Web spacing, rail positioning, and fallback styles. The plugin reads the supplied Ionic layout and placement; it does not reserve Web content space on its own. With the iOS27 theme, use its `setVerticalBarsLayout({ edge, inset })` helper. Native-only applications use their own CSS; no theme helper is required. Native availability comes from device metrics, independently of Web layout.
+
+The [theme's optional rail stylesheet](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/vertical-bars-layout.md) supplies one ready-made layout. Its classes and CSS variables are not a requirement to install the theme package: applications may provide equivalent layout themselves. The runtime currently uses the `ios-theme-vertical-bars` class on `ion-app` to identify the rail layout, regardless of who supplies its styles.
+
+## Use with Capacitor Foldable
+
+[`@erkamyaman/capacitor-foldable`](https://github.com/erkamyaman/capacitor-foldable) is required in the standard Vertical Bars setup. Install it with Native UI as shown above, and connect its device placement to your Web layout. Native UI does not subscribe to Foldable automatically.
+
+| Owner                | Responsibility                                                                              |
+| -------------------- | ------------------------------------------------------------------------------------------- |
+| Foldable             | Report initial device state and subsequent placement/posture changes.                       |
+| Application or theme | Reserve Web space and choose the layout using the reported logical edge and measured inset. |
+| Native UI            | Check native rail availability independently and project eligible source controls.          |
 
-After `ion-app` is mounted, start one runtime:
+### With the theme's Ionic rail layout
+
+After loading [the rail stylesheet](../../theme-ios27/docs/vertical-bars-layout.md) and mounting `ion-app`, connect device placement and start the runtime once:
 
 ```ts
+import { Foldable, type BarPlacement } from '@erkamyaman/capacitor-foldable';
+import { setVerticalBarsLayout } from '@rdlabo/ionic-theme-ios27';
 import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
 
-const rail = await enableNativeUI({ verticalBars: { only: true } });
+const applyPlacement = ({ verticalBarEdge, inset }: BarPlacement) => setVerticalBarsLayout({ edge: verticalBarEdge, inset });
+const listener = await Foldable.addListener('barPlacementChange', applyPlacement);
+applyPlacement(await Foldable.getBarPlacement());
+const rail = await enableNativeUI({ controls: 'verticalOnly' });
 ```
 
-Configure your Web rail layout and [apply device placement](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo.md#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 `enableNativeUI()`, keep that runtime; it includes Vertical Bars. Do not start both.
+If a runtime is already active, keep it and add only the placement subscription. `setVerticalBarsLayout` resolves logical edges for RTL; a null edge restores the ordinary Web layout. Use the measured inset instead of a fixed width. Keep the theme's rail stylesheet; Foldable's `ionic-tabs.css` is not needed for this integration.
 
-The `/vertical-bars` entry point requires `@capacitor/core`, including in browser builds. Using only the theme’s rail CSS needs no native runtime. For native setup and navigation transitions, follow the [existing-theme guide](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo-with-original-theme.md).
+When the application owner is disposed, remove its subscription and destroy the runtime it owns:
 
-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.
+```ts
+await listener.remove();
+await rail.destroy();
+```
 
-## Placement and Web layout
+### With application-owned CSS or without Ionic
 
-The application or theme owns Web spacing, rail positioning, and fallback styles. The plugin reads the supplied Ionic layout and placement; it does not reserve Web content space on its own. With the iOS27 theme, use its `setVerticalBarsLayout({ edge, inset })` helper. Native-only applications use their own CSS; no theme helper is required. Native availability comes from device metrics, independently of Web layout.
+Use the same `getBarPlacement()` / `barPlacementChange` subscription, but apply the edge and inset to your own CSS instead of calling `setVerticalBarsLayout`. A null edge means your layout should restore its ordinary spacing. For Ionic, retain the rail layout classes described above; for plain HTML, use the `/core` entry and [device rail setup](framework-independent.md#device-placement-for-vertical-bars). Neither Foldable nor Native UI supplies the application's CSS. Explicit HTML rail markers remain active independently of CSS; to return those sources to their original placement on a null edge, call `disableVerticalControlArea()`, then `enableVerticalControlArea()` when a rail edge returns. Serialize these changes with your layout updates.
 
-The [theme's optional rail stylesheet](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/vertical-bars-layout.md) supplies one ready-made layout. Its classes and CSS variables are not a requirement to install the theme package: applications may provide equivalent layout themselves. The runtime currently uses the `ios-theme-vertical-bars` class on `ion-app` to identify the rail layout, regardless of who supplies its styles.
+Keep Web layout updates separate from native availability: do not pass Foldable's edge through the deprecated `nativeEdge` option. Native UI reads that capability itself. Only an optional browser layout preview substitutes simulated placement for this subscription.
+
+For hinge-driven content layout, read `getFoldState()` and subscribe to `foldStateChange` separately. Hinge posture does not select controls or enable the rail; see the theme's [posture subscription and split-pane example](../../theme-ios27/docs/vertical-bars-layout.md#read-the-device-layout).
 
 ## Native rendering
 
@@ -48,7 +88,6 @@ On supported iOS versions, adding `.ios-theme-vertical-bars` changes only contro
 
 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 [optional theme rail layout](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/vertical-bars-layout.md#reserve-the-vertical-rail) when that stylesheet is used; custom layouts remain the application’s responsibility.
 
-
 ### Native popovers (Vertical Bars only)
 
 Native popover presentation is limited to popovers anchored to accepted native Vertical Bars `ion-button` controls. It is available with the standalone Vertical Bars runtime; the full Native UI is not required. Enable it explicitly when starting the runtime (`popover` defaults to `false`):
@@ -57,24 +96,24 @@ Native popover presentation is limited to popovers anchored to accepted native V
 import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
 
 const rail = await enableNativeUI({
-  verticalBars: { only: true, popover: true },
+  controls: 'verticalOnly',
+  ionic: { verticalBars: { popover: true } },
 });
 ```
 
 Use an `ion-popover` whose `trigger` identifies the projected button, or pass that button's click event to `PopoverController.create({ event, ... })`. Ordinary toolbar and body popovers remain on the Web. If a rail-anchored popover falls back to Web rendering, the rail also returns to Web projection until dismissal. See [native popover behavior and limitations](native-ui.md#popovers-anchored-to-vertical-bars).
 
-
 ## 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.
 
 By default, 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 |
+| Icon markup                              | Placement                   |
+| ---------------------------------------- | --------------------------- |
+| `slot="icon-only"`                       | Vertical rail               |
 | `slot="start"`, `slot="end"`, or no slot | Original horizontal toolbar |
-| No icon | Original horizontal toolbar |
+| No icon                                  | Original horizontal toolbar |
 
 ```html
 <ion-header>
@@ -96,29 +135,22 @@ A toolbar whose content has all moved into the rail collapses while projection i
 
 ### Select actions and grouping independently
 
-Use `vertical: { buttons, button, backButton }` to configure toolbar actions.
-All fields default to `true`. `vertical: false` disables automatic toolbar
-selection and grouping; local attributes may still opt in.
-For vertical-layout-only automatic toolbar projection, use
-`enableNativeUI({ horizontal: false, vertical: true })`.
-This selects by layout, not device model, and leaves tabs, segments and FABs unchanged.
-See [toolbar configuration](native-ui.md#toolbar-selection-and-grouping)
-for horizontal settings, boolean shorthands and defaults.
-
-| Option | Responsibility | What it does not do |
-| --- | --- | --- |
-| `button` | Automatically select eligible `ion-button` and `ion-menu-button` actions, whether inside or outside `ion-buttons`. | Does not select back buttons. |
-| `buttons` | Allow selected actions in `ion-buttons` to project as a group when the existing grouping rules allow it. | Does not select, enable or disable any child action. |
-| `backButton` | Automatically select eligible `ion-back-button` elements, independently of their parent group. | Does not group back buttons with other actions. |
+Use `controls` to configure toolbar selection and grouping. Each field accepts `true`, `false`, `'horizontalOnly'`, or `'verticalOnly'`, with omitted fields defaulting to `true`. Use `controls: 'verticalOnly'` for all default selection in the rail. Local attributes can override selection; explicit sources and extensions remain independent. See [all selection defaults](configuration.md#selection-defaults).
+
+| Option        | Responsibility                                                                                                     | What it does not do                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| `button`      | Automatically select eligible `ion-button` and `ion-menu-button` actions, whether inside or outside `ion-buttons`. | Does not select back buttons.                        |
+| `buttonGroup` | Allow selected actions in `ion-buttons` to project as a group when the existing grouping rules allow it.           | Does not select, enable or disable any child action. |
+| `backButton`  | Automatically select eligible `ion-back-button` elements, independently of their parent group.                     | Does not group back buttons with other actions.      |
 
 For ordinary icon-only buttons in a group, with no local attributes:
 
-| `buttons` | `button` | Result |
-| --- | --- | --- |
-| `true` | `true` | Eligible buttons project together when the group qualifies. |
-| `false` | `true` | Eligible buttons project individually. |
-| `true` | `false` | No ordinary buttons project; grouping alone selects nothing. |
-| `false` | `false` | No ordinary buttons project. |
+| `buttonGroup` | `button` | Result                                                       |
+| ------------- | -------- | ------------------------------------------------------------ |
+| `true`        | `true`   | Eligible buttons project together when the group qualifies.  |
+| `false`       | `true`   | Eligible buttons project individually.                       |
+| `true`        | `false`  | No ordinary buttons project; grouping alone selects nothing. |
+| `false`       | `false`  | No ordinary buttons project.                                 |
 
 These results concern ordinary actions only. Back navigation, tabs and native
 search are independent. For example, to select only back navigation among toolbar
@@ -126,8 +158,7 @@ actions:
 
 ```ts
 const rail = await enableNativeUI({
-  verticalBars: { only: true },
-  vertical: { buttons: false, button: false, backButton: true },
+  controls: { buttonGroup: false, button: false, backButton: 'verticalOnly', tabs: 'verticalOnly', segment: false, fab: false },
 });
 ```
 
@@ -138,19 +169,21 @@ This does not disable tab projection or tab rail CSS.
 Use `data-vertical-bars="true|false"` on the element whose behavior you want to
 override. The attribute is **not inherited**.
 
-| Element | Meaning of its attribute | Fallback when absent or invalid |
-| --- | --- | --- |
-| `ion-button` / `ion-menu-button` | Select or exclude this action. Explicit `true` bypasses the icon-only selection rule. | `button` and the automatic shape rules |
-| `ion-buttons` | Enable or disable grouping of already-selected actions. Never selects children. | `buttons` and the existing grouping rules |
-| `ion-back-button` | Select or exclude this back button. | `backButton` and the supported back-button rules |
+| Element                          | `data-vertical-bars="true"`                                                    | `data-vertical-bars="false"`                                    | Default when absent or invalid                     |
+| -------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- | -------------------------------------------------- |
+| `ion-button` / `ion-menu-button` | Select the action, including supported text actions without an icon-only slot. | Exclude the action from the rail.                               | `controls.button` and automatic shape rules.       |
+| `ion-buttons`                    | Allow grouping of already-selected actions.                                    | Project selected actions individually.                          | `controls.buttonGroup` and grouping eligibility.   |
+| `ion-back-button`                | Select back navigation independently of its group.                             | Exclude this back button from the rail.                         | `controls.backButton` and back-button eligibility. |
+| `ion-tab-bar`                    | Select eligible rail tabs and their native search presentation.                | Disable native rail tab selection; existing Web layout remains. | `controls.tabs` and tab-bar eligibility.           |
+
+The group's attribute never selects or excludes its children. All opt-ins remain subject to structural exclusions and rail availability.
 
 Empty or unknown attribute values are ignored. To disable automatic action
 selection and explicitly select a text button:
 
 ```ts
 const rail = await enableNativeUI({
-  verticalBars: { only: true },
-  vertical: { buttons: true, button: false, backButton: false },
+  controls: { buttonGroup: 'verticalOnly', button: false, backButton: false, tabs: 'verticalOnly', segment: false, fab: false },
 });
 ```
 
@@ -164,7 +197,7 @@ const rail = await enableNativeUI({
 Only Save moves; Cancel stays in the horizontal toolbar. Adding
 `data-vertical-bars="true"` to the group would not select Cancel.
 
-To group two explicitly selected actions even when `buttons: false`:
+To group two explicitly selected actions even when `buttonGroup: false`:
 
 ```html
 <ion-buttons data-vertical-bars="true">
@@ -188,7 +221,7 @@ startup options.
 ### Back buttons inside groups
 
 An `ion-back-button` remains a navigation action even inside `ion-buttons`.
-It ignores `buttons`, `button`, and the group's `data-vertical-bars` attribute.
+It ignores `buttonGroup`, `button`, and the group's `data-vertical-bars` attribute.
 Its own attribute overrides `backButton`. It uses the dedicated back position,
 never an ordinary action group, and is not duplicated as a toolbar action.
 
@@ -210,35 +243,41 @@ remain opt-outs; those are distinct from the grouping setting.
 
 ### Placement versus appearance
 
-`data-vertical-bars` controls selection or grouping as described above.
-`data-projection="source|system"` controls native appearance and follows its own
-button-then-group inheritance rules. Neither appearance value selects an action.
+| Setting                    | Values                              | Responsibility                                              | Applies to                                                                                                         |
+| -------------------------- | ----------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `data-native-ui`           | `button`, `back-button`, `disabled` | Declare an explicit source or exclude a subtree.            | [Explicit source elements](framework-independent.md#2-mark-source-controls); `disabled` also applies to ancestors. |
+| `data-native-ui-placement` | `element`, `rail`                   | Choose the original element position or request the rail.   | Explicit sources; `element` also keeps automatic Ionic controls at their original position.                        |
+| `data-vertical-bars`       | `true`, `false`                     | Override rail selection or grouping defaults.               | Ionic actions and groups listed above.                                                                             |
+| `data-horizontal-bars`     | `true`, `false`                     | Override ordinary-placement selection or grouping defaults. | [Ordinary Ionic controls](native-ui.md#toolbar-selection-and-grouping).                                            |
+| `data-projection`          | `system`, `source`                  | Choose native appearance without selecting an action.       | Native vertical `ion-button` and `ion-menu-button`; inherited from the nearest `ion-buttons`.                      |
+
+Selection attributes are not inherited. Appearance follows the button-then-group priority described below. An attribute never makes unsupported markup or a missing native rail available.
+
+The rail shares one light/dark appearance across projected controls. See [Shared Vertical Bars appearance](appearance.md#shared-vertical-bars-appearance) when configuring your Web theme.
 
 ### Choose button appearance
 
-`buttonProjection` and the local projection settings below are available in `1.2.0`.
+Use `ionic.verticalBars.buttonProjection` to choose native button appearance.
 
 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). |
+| `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 enableNativeUI({ verticalBars: { only: true, buttonProjection: 'source' } });
+const rail = await enableNativeUI({ controls: 'verticalOnly', ionic: { verticalBars: { buttonProjection: 'source' } } });
 ```
 
-`enableNativeUI()` accepts these settings inside `verticalBars`; the legacy global `enableVerticalControlArea()` still accepts its original top-level settings. Use one runtime, and destroy it before restarting with different options. Either mode preserves actions, disabled state and grouping. Disabled icons use the native disabled appearance. These appearance settings do not affect horizontal controls, source elements or Web fallback clones, so compare the native appearance on supported iOS.
-
-**Migration from the experimental releases:** the default changes from source styling to `system`. Set `buttonProjection: 'source'` to retain the previous projection behavior.
+`enableNativeUI()` and the standalone `enableVerticalControlArea()` accept these settings inside `ionic.verticalBars`. Use one runtime, and destroy it before restarting with different options. Either mode preserves actions, disabled state and grouping. Disabled icons use the native disabled appearance. These appearance settings do not affect horizontal controls, source elements or Web fallback clones, so compare the native appearance on supported iOS.
 
 ### Override individual buttons or groups
 
 Use `data-projection` for local exceptions. Existing classes remain supported:
 
-| Attribute | Equivalent class |
-| --- | --- |
+| Attribute                  | Equivalent class              |
+| -------------------------- | ----------------------------- |
 | `data-projection="source"` | `ios-theme-projection-source` |
 | `data-projection="system"` | `ios-theme-projection-system` |
 
@@ -267,17 +306,17 @@ Only native vertical `ion-button` and `ion-menu-button` actions interpret these
 
 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` |
+| 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` |
 
 `verticalBars.buttonDefaultFill` accepts `'solid'` or `'glass'`; omission is equivalent to `'glass'`. Use `'solid'` for Ionic's default button design, or `'glass'` for a 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 enableNativeUI({ verticalBars: { only: true, buttonDefaultFill: 'solid' } });
+const rail = await enableNativeUI({ controls: 'verticalOnly', ionic: { verticalBars: { buttonDefaultFill: 'solid' } } });
 ```
 
 ```html
@@ -287,12 +326,12 @@ const rail = await enableNativeUI({ verticalBars: { only: true, buttonDefaultFil
 </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 |
+| 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.
 

package/ios/Sources/NativeUIPlugin/NativeUIPlugin.swift

@@ -210,7 +210,7 @@ public class NativeUIPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDelegate {
                     self.bridge?.webView?.layoutIfNeeded()
                     // Ionic already paints the header edge; a second native effect can
                     // add a dark scrim when the OS and Web themes differ.
-                    if call.getBool("verticalBarsOnly") != true, let effect = self.bridge?.webView?.scrollView.topEdgeEffect {
+                    if call.getBool("suppressScrollEdgeEffect") == true, let effect = self.bridge?.webView?.scrollView.topEdgeEffect {
                         let hidden = effect.isHidden
                         effect.isHidden = true
                         self.restoreTopEdge = { [weak effect] in effect?.isHidden = hidden }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.1",
+  "version": "2.0.0-2",
   "author": "Masahiko Sakakibara <sakakibara@rdlabo.jp>",
   "license": "MIT",
   "repository": {

package/src/core.ts

@@ -6,9 +6,8 @@ export type {
   NativeUIOptions,
   NativeUIVerticalBarsOptions,
   NativeUIControls,
-  AutoIonicControls,
+  ControlProjection,
   IonicProjectionOptions,
-  ToolbarProjectionOptions,
   NativeUIHandle,
   NativeUIStatus,
   NativeUISuspension,

package/src/native/activation.ts

@@ -1,3 +1,4 @@
+import { controlDefault } from './shared/control-options';
 import { toolbarOptions } from './shared/toolbar-options';
 import { createDiagnostics } from './shared/diagnostics';
 import { createHTMLWebProjection } from './html';
@@ -160,15 +161,6 @@ const webProjection = (doc: Document, options: NativeUIRuntimeOptions, enabled:
 
 /** Call once at application startup. Ionic markup remains the source of truth. */
 export const enableNativeUI = (options: NativeUIRuntimeOptions = {}, overlayFactory?: OverlayFactory): Promise<NativeUIRuntimeHandle> => {
-  if (options.enabled === false) {
-    const current = active;
-    if (current)
-      stopActivation(
-        current,
-        current.then((handle) => handle.destroy()),
-      );
-    return (stopping ?? Promise.resolve()).then(() => web('Disabled'));
-  }
   if (typeof document === 'undefined') return Promise.resolve(web('Requires a document'));
   const extensions = [...(options.extensions ?? [])];
   const nativeState: NonNullable<NativeUIRuntimeOptions['nativeState']> = (options.nativeState = {});
@@ -177,22 +169,20 @@ export const enableNativeUI = (options: NativeUIRuntimeOptions = {}, overlayFact
   } catch (error) {
     return Promise.reject(error);
   }
-  const controls = options.controls;
   const configuration = JSON.stringify([
     options.source ?? 'ionic',
     options.debug === true,
-    options.explicitControls !== false,
+    options.ionic?.auto !== false,
     options.verticalBars?.enabled !== false,
     options.verticalBars?.placement?.edge,
     options.rail?.edge,
-    options.verticalBarsOnly === true,
     toolbarOptions(options, false),
     toolbarOptions(options, true),
-    options.buttonProjection ?? 'system',
+    options.ionic?.verticalBars?.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),
-    controls?.popover === true,
+    options.ionic?.verticalBars?.buttonDefaultFill ?? 'glass',
+    ...(['tabs', 'segment', 'fab'] as const).flatMap((kind) => [controlDefault(options, kind, false), controlDefault(options, kind, true)]),
+    options.ionic?.verticalBars?.popover === true,
   ]);
   if (active && activeFailed) {
     const previous = active;
@@ -248,7 +238,7 @@ export const enableNativeUI = (options: NativeUIRuntimeOptions = {}, overlayFact
       const diagnose = createDiagnostics(options.debug);
       const stopModals = options.source === 'html' ? () => {} : observeVerticalBarsModals(document);
       const prehide =
-        platform !== 'android' && options.source !== 'html' && (options.controls === undefined || options.controls.toolbar === true)
+        platform !== 'android' && options.source !== 'html' && options.ionic?.auto !== false
           ? prehideVerticalBarsToolbarSources(document, () => options.verticalBars?.enabled !== false, options.root, options)
           : undefined;
       const fallback = (reason: string) => {
@@ -290,7 +280,10 @@ export const enableNativeUI = (options: NativeUIRuntimeOptions = {}, overlayFact
         }
       };
       try {
-        const capabilities = await bounded(plugin.configure({ verticalBarsOnly: options.verticalBarsOnly === true }));
+        const ordinaryControls = (['button', 'backButton', 'tabs', 'segment', 'fab'] as const).some((kind) =>
+          controlDefault(options, kind, false),
+        );
+        const capabilities = await bounded(plugin.configure({ suppressScrollEdgeEffect: ordinaryControls }));
         if (!capabilities.supported) return fallback('Native UI is unavailable on this device');
         const unavailableExtensions = new Map<string, string>();
         for (const extension of extensions) {
@@ -313,7 +306,6 @@ export const enableNativeUI = (options: NativeUIRuntimeOptions = {}, overlayFact
               unavailableExtensions,
             },
             () => false,
-            options.verticalBarsOnly === true,
             runtimeStopped,
           );
           runtime = combine(runtime, webProjection(document, options));
@@ -349,7 +341,7 @@ export const enableNativeUI = (options: NativeUIRuntimeOptions = {}, overlayFact
           return physicalEdge === nativeState.edge;
         };
         const applyMetrics = (metrics: WebViewMetrics) => {
-          if (!options.verticalBarsOnly) nativeWebViewMetrics.radius = metrics.radius;
+          if (ordinaryControls) nativeWebViewMetrics.radius = metrics.radius;
           deviceEdge = metrics.verticalBarEdge ?? null;
           updateNativeEdge();
           document.defaultView?.dispatchEvent(new Event('nativeUIRefresh'));
@@ -363,14 +355,13 @@ export const enableNativeUI = (options: NativeUIRuntimeOptions = {}, overlayFact
           plugin,
           { ...options, extensions, unavailableExtensions },
           nativeVerticalBars,
-          options.verticalBarsOnly === true,
           runtimeStopped,
         );
         runtime = combine(
           native,
           webProjection(document, options, () => !nativeVerticalBars() || native.getStatus().projected === 0),
         );
-        if (controls?.popover === true && overlayFactory)
+        if (options.ionic?.verticalBars?.popover === true && overlayFactory)
           overlays = await overlayFactory(document, plugin, options, native.retain, nativeVerticalBars);
         return manage(runtime, {
           suspend: async () => {