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

package/docs/framework-independent.md

@@ -1,17 +1,23 @@
 # Native UI without Ionic
 
-> This guide targets the upcoming package split. Until the first native package release, use the [candidate archive installation](../README.md#try-the-unreleased-packages) in place of registry install commands.
-
 Add native buttons to an existing Web app without Ionic or theme CSS. Keep labels, state, and click handlers on ordinary HTML elements. Standard buttons require no custom Swift registration.
 
 Use a Capacitor 8 app with an iOS project, Xcode 26+, and an iOS 26+ device or simulator. Browsers and Android retain Web controls. For custom Android native content, use [Kotlin/Compose extensions](native-ui-extensions.md#2b-register-compose-content-on-android).
 
+Start with [how projection works](../README.md#how-projection-works): the HTML element remains the source while native controls or Web proxies provide its presentation.
+
+**Want only Vertical Bars?** Follow the [device placement setup](#device-placement-for-vertical-bars), alongside steps 1–4 below. Reuse the step 3 runtime without a fixed placement preference. Remove explicit markers from buttons you want to leave on the Web. You do not need Ionic, `@rdlabo/ionic-theme-ios27`, or `vertical-bars.css`.
+
+For Vertical Bars in an app using `ion-tabs`, `ion-toolbar` or other Ionic components with a custom theme, use the [Ionic Vertical Bars setup](ionic-vertical-bars.md#try-it-in-your-existing-ionic-app) instead. The framework (Angular, React or Vue) alone does not determine which adapter to use.
+
 ## 1. Install the plugin
 
-Keep your existing Capacitor 8 installation and add the plugin directly:
+[Capacitor Foldable](https://github.com/erkamyaman/capacitor-foldable) is our standard integration for device state. Its placement and posture APIs let your app control how the layout adapts; installing it is followed by connecting its initial values and change events.
+
+Keep your existing Capacitor installation and add Native UI and Foldable together:
 
 ```sh
-npm install @rdlabo/capacitor-native-ui
+npm install @rdlabo/capacitor-native-ui @erkamyaman/capacitor-foldable
 ```
 
 The `/core` entry requires `@capacitor/core` but no Ionic dependencies. If this is currently a browser-only application, configure its Capacitor 8 iOS project before running native controls.
@@ -26,12 +32,25 @@ The `/core` entry requires `@capacitor/core` but no Ionic dependencies. If this
 <aside id="rail" aria-label="Navigation"></aside>
 ```
 
-- `data-native-ui="button"` opts into a standard action button.
-- `data-native-ui="back-button"` opts into a standard back button. Its original click handler owns navigation; the plugin never calls `history.back()`.
-- `data-native-ui-placement="rail"` requests Vertical Bars. Without it, the source rectangle is used. `element` explicitly preserves that rectangle.
-- Sources must be `<button>`, explicitly marked `ion-button`, or custom elements exposing `role="button"` and click behavior. Unmarked HTML is never inferred to be a control.
+| Attribute                  | Value               | Effect                                                                                                             |
+| -------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `data-native-ui`           | `button`            | Project a standard action button.                                                                                  |
+| `data-native-ui`           | `back-button`       | Project a standard back button. The source click handler owns navigation; the plugin never calls `history.back()`. |
+| `data-native-ui`           | `disabled`          | Exclude the element and its subtree from projection.                                                               |
+| `data-native-ui-placement` | `element` (default) | Use the source element's rectangle.                                                                                |
+| `data-native-ui-placement` | `rail`              | Request Vertical Bars; use the optional Web rail host when native rail presentation is unavailable.                |
 
-Keep the accessible name, supported static SVG, disabled state and application handlers on the source. Names resolve from `aria-labelledby`, `aria-label`, then text. Native `disabled`, a disabled fieldset and `aria-disabled="true"` are respected. Hidden, removed, excluded or out-of-scope sources are retired and stale actions are rejected. Use `data-native-ui="disabled"` to exclude a subtree.
+Apply `button` and `back-button` to `<button>`, explicitly marked `ion-button`, or elements exposing `role="button"` and click behavior. Unmarked HTML is never inferred to be a control. `data-native-ui-placement` chooses placement for a declared source; it does not opt an unmarked HTML element into projection.
+
+Keep the control's data and behavior on its source:
+
+| Source property      | Projection behavior                                                                        |
+| -------------------- | ------------------------------------------------------------------------------------------ |
+| Accessible name      | Resolves from `aria-labelledby`, then `aria-label`, then text.                             |
+| Artwork              | Uses supported static SVG.                                                                 |
+| Disabled state       | Respects native `disabled`, a disabled fieldset, and `aria-disabled="true"`.               |
+| Visibility and scope | Hidden, removed, excluded or out-of-scope sources are retired; stale actions are rejected. |
+| Application handlers | Remain on the original element.                                                            |
 
 Native and Web-proxy actions click the original element. An ordinary `<button type="submit">` therefore keeps its original form behavior. Use `type="button"` for actions that must not submit. The native bridge does not preserve browser user-activation privileges for APIs such as popup opening.
 
@@ -47,19 +66,39 @@ const shell = await enableNativeUI({
 
 Call once after the source root exists. Keep the handle and call `await shell.destroy()` when that root is disposed. The plugin does not add page padding or safe-area rules; retain your application's CSS. For Angular, React, or Vue, use the [app-root lifecycle examples](setup.md#place-startup-in-your-frameworks-app-root) with the `/core` import. For animated navigation, use [suspension through completion and cancellation](setup.md#navigation-without-the-theme).
 
+### Match the HTML theme
+
+For a custom HTML theme, declare `color-scheme: light` or `color-scheme: dark` in the same CSS that selects your Web palette. Background colors alone do not select native appearance. See [Light and dark appearance](appearance.md) for a manual-toggle example, precedence when Ionic/theme variables are present, and shared rail behavior.
+
 ## 4. Build and run on iOS
 
-Build your Web app, run `npx cap sync ios`, and launch the iOS project from Xcode. The marked Add button should render natively and invoke its original click handler. In a browser, the same button remains an ordinary Web button. Unmarked HTML remains unchanged.
+Build your Web app, run `npx cap sync ios`, and launch the iOS project from Xcode. With the step 3 configuration, Add renders at its source position and invokes its original click handler. Back requests the device-reported native rail when available; connect the device placement below to keep Web spacing in sync. In a browser, the same button remains an ordinary Web button. Unmarked HTML remains unchanged.
 
 If a button stays on the Web on supported iOS, check that it is visible within the configured root, has an accessible name, and that the direct plugin dependency was synced and the iOS app rebuilt.
 
 In an app that also uses Ionic, set `ionic: { auto: false }` to project only explicit sources and registered extensions. See [selective Ionic projection](configuration.md#select-controls-explicitly-in-a-customized-ionic-app).
 
-## Optional Web rail
+## Device placement for Vertical Bars
 
-Replace the startup call in step 3 with the following configuration; do not start a second shell:
+Foldable is already included in the standard installation in step 1. Connect it to your application layout as follows.
+
+Reuse the runtime from step 3 **without `verticalBars.placement`**. Native UI then follows the device-reported edge; a fixed `edge: 'trailing'` would constrain it and can reject a device's leading rail.
+
+Follow [Foldable integration](vertical-bars.md#with-application-owned-css-or-without-ionic):
+
+1. Subscribe to `barPlacementChange`, then read `getBarPlacement()` for the initial edge and inset.
+2. Apply the edge and inset to your application's CSS. On a null edge, restore ordinary spacing and call `shell.disableVerticalControlArea()`; when an edge returns, call `shell.enableVerticalControlArea()`. Serialize these changes with layout updates.
+3. At teardown, remove the listener and destroy the runtime owned by this application.
+
+Keep the explicit source markers from step 2; they declare the controls and their requested placement. To project only Back, remove `data-native-ui="button"` from Add. `controls` does not disable explicit declarations. Without a Web rail host, unavailable native rail controls stay at their original Web positions. The theme package is not required.
+
+## Optional browser rail preview
+
+For a browser-only layout preview, temporarily use this fixed Web rail instead of the startup call in step 3 and the device subscription. Do not copy the fixed placement into the standard device setup. Call once after the source root and host are mounted, and call `await shell.destroy()` when their owner is disposed:
 
 ```ts
+import { enableNativeUI } from '@rdlabo/capacitor-native-ui/core';
+
 const shell = await enableNativeUI({
   root: document.querySelector<HTMLElement>('#app')!,
   verticalBars: {
@@ -73,7 +112,7 @@ const shell = await enableNativeUI({
 
 The plugin uses device-reported rail availability and resolves leading/trailing through the document direction. A placement preference never forces an unsupported system rail. Native rejection restores Web presentation. With `webHost`, explicitly rail-marked HTML controls have Web proxies when native projection is unavailable. Without it, their originals remain visible. The application styles and positions the host and reserves any content spacing. The host must be outside the source root.
 
-To use only rail projection, add `verticalBars.only: true`. To change rail use later, call `await shell.disableVerticalControlArea()` or `await shell.enableVerticalControlArea()`. Disabling restores original controls and removes Web rail proxies without destroying ordinary native projection. `only: true` keeps ordinary controls on the Web throughout.
+Explicit markup chooses placement: Back goes to the preview rail and Add stays at its original position. Disabling rail projection restores original rail controls and removes Web proxies without destroying ordinary native projection. Before building for a device, restore the step 3 runtime and the Foldable subscription above.
 
 Currently the HTML adapter supports buttons and back buttons. Arbitrary HTML tabs, segments, searchbars and FAB structures are not translated. Ionic adapters continue to support their existing controls. Custom element extensions work with the same scoped root; the existing `tab-accessory` extension placement still requires an Ionic tab-bar owner.
 

package/docs/ionic-vertical-bars.md

@@ -0,0 +1,186 @@
+---
+title: Add Vertical Bars while keeping your theme
+---
+
+# Add Vertical Bars while keeping your theme
+
+Keep your app's existing appearance and add Vertical Bars. Choose the setup for your app's components, whether you use Angular, React, Vue or another framework.
+
+Read [how projection works](../README.md#how-projection-works) for the relationship between source DOM, projected controls and actions. Then choose your setup below.
+
+## Choose your setup
+
+| Your app                                                                       | Start here                                                                                                                        | What you add                                                                                              |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Ionic components with your own theme, Ionic's default styles, or another theme | [Ionic setup below](#try-it-in-your-existing-ionic-app)                                                                           | Foldable device placement, standalone rail CSS and the Ionic Native UI adapter. Keep your existing theme. |
+| No Ionic components (plain HTML, React, Vue, Angular, etc.)                    | [HTML setup](framework-independent.md), then its [device rail setup](framework-independent.md#device-placement-for-vertical-bars) | `@rdlabo/capacitor-native-ui/core` and Foldable. Your app supplies the rail layout; no theme package.     |
+| Already using the iOS 27 theme and Native UI                                   | [Connect device placement](../../capacitor-native-ui/docs/vertical-bars.md#use-with-capacitor-foldable)                           | Reuse your existing runtime. Do not start another one.                                                    |
+
+**Without Ionic, follow the HTML guide instead of the steps below.** You do not need `@rdlabo/ionic-theme-ios27`, `vertical-bars.css`, `ion-app`, or Ionic navigation animations. Explicitly marked HTML buttons and back buttons are supported; arbitrary HTML tabs are not automatically converted. A browser preview requires an application-styled `webHost`; native rail presentation also requires supported iOS hardware and software.
+
+The rest of this page is for **Ionic apps**. Both Ionic `ios` and `md` modes are supported. Tabs and supported toolbar actions move to the side; content and horizontal controls keep their existing appearance.
+
+iPhone Duo support and Vertical Bars are stable starting with version 2.0.0.
+
+## Try it in your existing Ionic app
+
+### 1. Install and load the standalone stylesheet
+
+Start with your existing Ionic app (Ionic `>=8.8.1 <10`, Capacitor 8.5 or later). Install Native UI, the layout stylesheet package and the required device-state plugin together:
+
+```bash
+npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui @erkamyaman/capacitor-foldable
+```
+
+Keep your existing theme imports. Add this to your global Sass file:
+
+```scss
+@use '@rdlabo/ionic-theme-ios27/dist/css/vertical-bars.css';
+```
+
+The full iOS 27 theme stylesheets are not required. Keep this stylesheet instead of Foldable's `ionic-tabs.css`; loading both would reposition the same tabs.
+
+We adopt [Capacitor Foldable](https://github.com/erkamyaman/capacitor-foldable) as the standard device integration because it exposes placement, posture and their changes while leaving layout decisions to your app. Pass its logical rail edge and measured inset to the theme's layout helper. Native UI checks native rail availability independently.
+
+### 2. Connect your navigation animation
+
+Configure `navAnimation` before Ionic initializes. Starting the rail runtime does not register this option. The adapter waits for native control retirement and coordinates swipe progress and cancellation while keeping your existing animation.
+
+#### Keep Ionic's default animation
+
+If you have not configured `navAnimation`, wrap Ionic's standard builders. Select the builder from Ionic's transition `mode` so both `ios` and `md` keep their usual animation:
+
+```ts
+import { iosTransitionAnimation, mdTransitionAnimation, type AnimationBuilder } from '@ionic/core';
+import { withNativeUITransition } from '@rdlabo/ionic-theme-ios27';
+
+const defaultTransition: AnimationBuilder = (baseEl, opts) =>
+  (opts.mode === 'ios' ? iosTransitionAnimation : mdTransitionAnimation)(baseEl, opts);
+
+const ionicConfig = {
+  navAnimation: withNativeUITransition(defaultTransition),
+};
+```
+
+Merge this option into your existing Ionic configuration before initialization: pass it to Angular's `provideIonicAngular()`, React's `setupIonicReact()`, or Vue's `IonicVue` plugin options. Keep your existing theme stylesheet imports. No iOS 27 theme stylesheet is required.
+
+#### Use the theme's iOS animation
+
+If you already use the iOS 27 transition, keep this configuration. It includes the native adapter and excludes the horizontal back-button effect in vertical layouts; no additional wrapper is needed. Importing this JavaScript entry point does not load the theme stylesheets.
+
+```ts
+import { iosTransitionAnimation } from '@rdlabo/ionic-theme-ios27';
+
+const ionicConfig = {
+  navAnimation: iosTransitionAnimation,
+};
+```
+
+Apply this option to your existing iOS-mode configuration and keep your MD configuration.
+
+#### Keep your custom animation
+
+If your app uses another builder for `navAnimation`, wrap it:
+
+```ts
+import type { AnimationBuilder } from '@ionic/core';
+import { withNativeUITransition } from '@rdlabo/ionic-theme-ios27';
+
+// Pass the animation builder your app already uses.
+const configureNavigation = (existingTransition: AnimationBuilder) => ({
+  navAnimation: withNativeUITransition(existingTransition),
+});
+```
+
+The adapter returns the original `Animation`, preserving its effects, duration, and easing. Use it only for navigation, not modal or popover animations. The builder must return a fresh `Animation` for each navigation; Ionic destroys it after the transition. Keep lifecycle events for control registration and transitions without animation.
+
+The adapter keeps the builder's animation targets, including any horizontal back-button effect. If you need the iOS 27 transition with that effect excluded in vertical layouts, use `iosTransitionAnimation` from `@rdlabo/ionic-theme-ios27` as your `navAnimation` instead. It already includes the adapter, so no wrapper is needed.
+
+### 3. Connect device placement and start the controls
+
+After `ion-app` is mounted, subscribe to placement changes, read the initial placement, and start one runtime. Keep your existing `ion-app` markup; the helper applies or removes the layout classes from device state:
+
+```ts
+import { Foldable, type BarPlacement } from '@erkamyaman/capacitor-foldable';
+import { setVerticalBarsLayout } from '@rdlabo/ionic-theme-ios27';
+import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
+
+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' });
+```
+
+| Device placement                       | Web layout                                                                 |
+| -------------------------------------- | -------------------------------------------------------------------------- |
+| `leading` or `trailing`                | Reserves the reported inset at that logical edge. The helper resolves RTL. |
+| `null`, including the browser fallback | Restores the ordinary layout; no side rail is forced.                      |
+
+When the application owner is disposed, remove its listener and destroy the runtime it owns:
+
+```ts
+await listener.remove();
+await rail.destroy();
+```
+
+If Native UI is already active, keep that runtime and add only the placement subscription. Do not start a second runtime. For shared configuration and application-owned CSS, see [Foldable integration](vertical-bars.md#use-with-capacitor-foldable).
+
+### 4. Build, sync and run on iPhone Duo
+
+Build your application's Web assets, then sync the native project:
+
+```sh
+npx cap sync ios
+```
+
+Build with Xcode 27.1 or newer and run on iPhone Duo with iOS 27.1 or later. Keep your existing SPM or CocoaPods integration; see [Native UI setup](setup.md#4-build-sync-and-run).
+
+**What you should see when the device reports a rail:** your existing tab bar and eligible fixed-toolbar actions move to the side. Content keeps its theme and reserves the measured inset. Supported iOS rails use SwiftUI; unavailable native presentation retains the Web rail. Devices reporting a null edge keep their ordinary layout. Use the [optional browser preview](#optional-browser-preview) to simulate a rail without a device report.
+
+Keep your existing click handlers, routing and form associations. By default, actions need an `ion-icon` or SVG with `slot="icon-only"` in a fixed toolbar. All fills (`default`, `clear`, `solid`, `outline`) follow this rule, including submit buttons. Other actions remain horizontal. Use `.ios-theme-horizontal-only` on an `ion-buttons` group or individual `ion-button` to keep an action horizontal.
+
+### Optional: choose native button appearance
+
+See [Choose button appearance](vertical-bars.md#choose-button-appearance) for appearance settings and local overrides.
+
+The default is `system`: SwiftUI styles vertical buttons and tints their icons. If your existing theme should supply their fill and colors, replace only the `enableNativeUI` call in step 3 with the following; keep the Foldable subscription:
+
+```ts
+const rail = await enableNativeUI({
+  controls: 'verticalOnly',
+  ionic: { verticalBars: { buttonProjection: 'source', buttonDefaultFill: 'solid' } },
+});
+```
+
+The `solid` default suits ordinary Ionic buttons. Buttons inside `ion-buttons` still default to clear; set `fill="solid"` explicitly to project their background. For one-off exceptions, use the [local projection settings](vertical-bars.md#override-individual-buttons-or-groups). These settings affect native vertical buttons only; Web clones keep their existing appearance.
+
+### If the rail does not appear
+
+| What you see                                | What to check                                                                                                       |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| Ordinary layout                             | Check Foldable's reported edge. A null edge intentionally keeps ordinary layout.                                    |
+| Reported edge but no side spacing           | Load `vertical-bars.css` and apply the initial placement and `barPlacementChange` events after `ion-app` mounts.    |
+| Space appears, but controls stay horizontal | Start the runtime once. Use existing tabs or supported `slot="icon-only"` actions in a fixed header/footer toolbar. |
+| One action stays horizontal                 | Check its icon slot, fixed placement and exclusions. See [control requirements](vertical-bars.md#toolbar-actions).  |
+
+## Optional browser preview
+
+For local layout testing without a device report, temporarily omit the Foldable subscription from step 3 and apply a simulated placement after `ion-app` mounts:
+
+```ts
+setVerticalBarsLayout({ edge: 'trailing', inset: 80 });
+```
+
+Keep the same stylesheet and single Native UI runtime. Use `leading` to preview the other logical edge, or `null` to restore ordinary layout. The helper manages `ios-theme-vertical-bars` and its physical-left variant; manual classes are not part of device setup. See [layout classes](../../theme-ios27/docs/vertical-bars-layout.md#reserve-the-vertical-rail) for CSS-only previews.
+
+Web rail tabs display icons and reveal labels while pressing and dragging. Browser previews verify Web layout and actions, not native SwiftUI appearance. Restore the Foldable subscription for the device build.
+
+## Use hinge posture without projecting controls
+
+If your existing theme needs only a posture-driven split pane or a layout switch, do not start a projection runtime or add `.ios-theme-vertical-bars`. Pass `Foldable.getFoldState()` results and `foldStateChange` events to `applyFoldStateClasses(root, fold)`, removing the listener when finished. There is no separate start/stop monitoring call.
+
+See [Read the device layout](../../theme-ios27/docs/vertical-bars-layout.md#read-the-device-layout) for the subscription example, null values, and monitoring lifetime. See [Adapt the split pane](../../theme-ios27/docs/vertical-bars-layout.md#adapt-the-split-pane) for the opt-in width rules and half-open state.
+
+## Shared layout rules and API
+
+Safe-area handling, overlays, RTL, control eligibility, Web simulation, and the handle API are documented in [Vertical Bars](vertical-bars.md). Read that reference when you need to customize this setup; it is not an additional installation step.

package/docs/migration.md

@@ -4,18 +4,14 @@ title: Migration
 
 # Migration
 
-> This guide targets the upcoming package split. Until the first native package release, use the [candidate archive installation](../README.md#try-the-unreleased-packages) in place of registry install commands.
+## Upgrading from 1.2.1
 
-## Migrating from Native UI Shell Preview
+This guide is for applications using `@rdlabo/ionic-theme-ios27` **1.2.1**, including its Native UI Shell Preview and standalone Vertical Control Area.
 
-Native UI Shell was already published as **Preview** in `@rdlabo/ionic-theme-ios27` 1.2.0 and 1.2.1. Preview users need the migration below when adopting the split packages; changing the import alone is not sufficient for every configuration. Candidate/beta users should also compare their configuration with these mappings and use JavaScript and native code from the same candidate.
+- **Theme only:** update the theme package. Existing theme imports, CSS/Sass paths and animation imports remain valid; no native startup is needed.
+- **Native UI or Vertical Control Area:** install the native package directly, replace imports and startup settings below, then sync Capacitor and rebuild the native app.
 
-1. Install the matching packages and replace removed imports using [package separation](#native-ui-package-separation).
-2. Apply the [API and native naming changes](#native-ui-naming-changes), then translate startup settings using [shared shell configuration](#shared-shell-configuration-and-html-adapters), especially partial `controls` objects.
-3. Update [Web layout ownership](#web-layout-ownership) and the [transition adapter](#native-ui-transition-adapter) if used.
-4. Rebuild Web assets, sync Capacitor, and rebuild the native app. A Web-only update cannot replace the native plugin.
-
-Native UI remains Preview. App-local SwiftUI / Compose **extensions are experimental**, including their TypeScript definitions, native registration APIs and placement behavior. The `defineNativeUI` and `extensions` names stay unchanged; native registration names change as listed below. Applications using extensions should keep their Web fallback and verify their reader, native renderer and action forwarding together after updates. See the [extension guide](native-ui-extensions.md).
+Native UI remains Preview. Experimental Extensions are documented in the [current extension guide](native-ui-extensions.md); this guide covers the published 1.2.1 controls and setup.
 
 ## Native UI package separation
 
@@ -23,11 +19,11 @@ For a new native integration, follow [Native UI setup](setup.md) or, if you alre
 
 The theme and native controls now live in separate packages. Choose dependencies by the behavior your app uses:
 
-| App behavior | Package to use directly |
-| --- | --- |
-| Theme styles, Ionic Web behavior, and theme animations | `@rdlabo/ionic-theme-ios27` |
-| Native UI or standalone Vertical Control Area | `@rdlabo/capacitor-native-ui` |
-| Theme styling together with native controls | Both packages |
+| App behavior                                           | Package to use directly       |
+| ------------------------------------------------------ | ----------------------------- |
+| Theme styles, Ionic Web behavior, and theme animations | `@rdlabo/ionic-theme-ios27`   |
+| Native UI or standalone Vertical Control Area          | `@rdlabo/capacitor-native-ui` |
+| Theme styling together with native controls            | Both packages                 |
 
 The theme owns the appearance and behavior of Ionic's Web elements. Native UI owns projecting supported controls into native iOS views and coordinating their lifecycle with Web navigation. Native UI can be used without the iOS 27 theme; installing it does not apply theme styles. Standard controls on Android and browsers retain Web presentation; Android can render [app-local Compose extensions](native-ui-extensions.md#2b-register-compose-content-on-android).
 
@@ -35,38 +31,28 @@ The theme uses the native package's shared transition/search integration interna
 
 ### 1. Update application dependencies
 
-These commands apply once the packages containing this migration are published.
+When using the theme and Native UI together, update them to the same version. The commands below also install [Capacitor Foldable](https://github.com/erkamyaman/capacitor-foldable) as a separate application dependency for placement and posture reporting. Foldable has its own release versions.
 
 For theme-only apps, update the theme package. Keep existing theme imports and CSS/Sass paths; no native startup or plugin setup is needed for theme-only use.
 
 ```sh
-npm install @rdlabo/ionic-theme-ios27
+npm install @rdlabo/ionic-theme-ios27 @erkamyaman/capacitor-foldable
 ```
 
 For apps using both the theme and native controls, install both as direct application dependencies:
 
 ```sh
-npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui
+npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui @erkamyaman/capacitor-foldable
 ```
 
 For native controls with your existing Web appearance, follow [Native UI only](setup.md). Install the native package directly and keep your existing Web styles. The plugin no longer requires theme variables to select supported controls; Web layout remains the responsibility of your app or theme. Native startup requires Capacitor 8. The Ionic adapter requires Ionic 8.8.1 or later within Ionic 8 or 9; the `/core` entry does not require Ionic.
 
-If you used the intermediate `@ionic-theme/capacitor-native-ui` package name during development, remove it and install `@rdlabo/capacitor-native-ui`. Keep the theme dependency if your app uses its styles or APIs.
-
-```sh
-npm uninstall @ionic-theme/capacitor-native-ui
-npm install @rdlabo/capacitor-native-ui
-```
-
 ### 2. Replace native imports
 
-| Previous import | Replacement |
-| --- | --- |
-| `@rdlabo/ionic-theme-ios27/native` | `@rdlabo/capacitor-native-ui` |
+| Previous import                           | Replacement                                 |
+| ----------------------------------------- | ------------------------------------------- |
+| `@rdlabo/ionic-theme-ios27/native`        | `@rdlabo/capacitor-native-ui`               |
 | `@rdlabo/ionic-theme-ios27/vertical-bars` | `@rdlabo/capacitor-native-ui/vertical-bars` |
-| `@ionic-theme/capacitor-native-ui` | `@rdlabo/capacitor-native-ui` |
-| `@ionic-theme/capacitor-native-ui/vertical-bars` | `@rdlabo/capacitor-native-ui/vertical-bars` |
-| `@ionic-theme/capacitor-native-ui/integration` | `@rdlabo/capacitor-native-ui/integration` |
 
 Update both value and type imports, including lazy imports, test aliases, and bundler configuration. The old theme `/native` and `/vertical-bars` entries have been removed; there are no compatibility aliases.
 
@@ -75,7 +61,7 @@ Update both value and type imports, including lazy imports, test aliases, and bu
 + import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
 ```
 
-Keep existing control markup; review the [startup option changes](#shared-shell-configuration-and-html-adapters), including partial `controls` defaults. The ordinary `@rdlabo/ionic-theme-ios27` entry, theme CSS/Sass paths, and theme animation imports stay unchanged. For custom navigation animations, see the [transition adapter instructions](#native-ui-transition-adapter) below.
+Keep existing control markup; review the [startup option changes](#startup-options), including partial `controls` defaults. The ordinary `@rdlabo/ionic-theme-ios27` entry, theme CSS/Sass paths, and theme animation imports stay unchanged. For custom navigation animations, see the [transition adapter instructions](#native-ui-transition-adapter) below.
 
 ### 3. Sync the native project
 
@@ -87,45 +73,40 @@ npx cap sync ios
 
 The Capacitor plugin is now supplied by the native package. Remove manually linked copies of the old theme Swift package so only the new package supplies the plugin. The Swift package/product and CocoaPods pod are now `RdlaboCapacitorNativeUi`; the Swift module is `NativeUIPlugin`. The Capacitor bridge name is now `NativeUI` on JavaScript, iOS and Android. Run Capacitor sync for each native platform you use and rebuild the native app. An OTA/Web-only update cannot migrate an installed binary containing only the old plugin. Use matching JavaScript and native package versions.
 
-For local Swift package references, the package now lives at `packages/capacitor-native-ui` within this repository; there is no root Swift package. Prefer Capacitor's generated integration for application dependencies.
+Use Capacitor's generated integration for the npm dependency; applications do not need a checkout of this repository or a manually linked Swift package.
 
 ### 4. Verify the migration
 
-- Check `package.json` and the lockfile: native-enabled apps have a direct `@rdlabo/capacitor-native-ui` dependency and no intermediate `@ionic-theme/capacitor-native-ui` dependency.
-- Build the application and confirm there are no imports of the removed theme entries or the intermediate package name.
-- Build and launch the iOS app after sync. Check native controls, navigation/back gestures, and any app-local Swift extensions you use.
+- Check that native-enabled apps declare `@rdlabo/capacitor-native-ui` directly, then build and confirm no imports of the removed theme entries remain.
+- Build and launch the iOS app after sync. Check native controls, navigation/back gestures, and restored Web controls after teardown.
 - Check browser and Android Web presentation where supported by your app, and confirm the theme still looks correct.
 - Check that previously disabled control kinds remain disabled after expanding partial Preview settings. Test toolbar grouping, individually selected actions and back navigation in both horizontal and vertical layouts.
-- For experimental extensions, check native registration, props, click forwarding and restoration of the original Web UI when projection is unavailable. Rebuild and sync Android as well if the app uses Compose extensions.
 
 ## Native UI naming changes
 
-The split package uses Native UI names throughout. These are breaking renames; the old names are not aliases. The historical names below refer to the published theme Preview or pre-release package candidates.
+The split package uses Native UI names throughout. These are breaking renames; the old names are not aliases. The previous names below refer to the published 1.2.1 Preview.
 
-| Previous name | New name |
-| --- | --- |
-| `enableNativeUIShell()` | `enableNativeUI()` |
+| Previous name                                                                                                                                      | New name                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `enableNativeUIShell()`                                                                                                                            | `enableNativeUI()`                                                                                                   |
 | `NativeUIShellOptions`, `NativeUIShellHandle`, `NativeUIShellStatus`, `NativeUIShellSuspension`, `NativeUIShellControls`, `NativeUIShellComponent` | `NativeUIOptions`, `NativeUIHandle`, `NativeUIStatus`, `NativeUISuspension`, `NativeUIControls`, `NativeUIComponent` |
-| `IonicNativeUIShell` (plugin export and bridge registration) | `NativeUI` |
-| `withNativeUIShellTransition()` | `withNativeUITransition()` (still exported by the theme package) |
-| `IonicNativeUIShellPlugin` (Swift module/native class) | `NativeUIPlugin` |
-| `IonicThemeCapacitorNativeUi` (SPM package/product and pod) | `RdlaboCapacitorNativeUi` |
-| `NativeUIShell.register()` (Swift / Kotlin extensions) | `NativeUI.register()` |
-| `data-shell="disabled"` | `data-native-ui="disabled"` |
-| `.ios-theme-shell-disabled` | `.native-ui-disabled` |
-
-Replace the `NativeUIShell` part with `NativeUI` in imports from `/integration` as well (for example `suspendNativeUI` and `setNativeUIIntegration`). App-local Swift extensions now use `import NativeUIPlugin`; Kotlin extensions use `import dev.rdlabo.capacitor.nativeui.NativeUI`.
+| `IonicNativeUIShell` (plugin export and bridge registration)                                                                                       | `NativeUI`                                                                                                           |
+| `withNativeUIShellTransition()`                                                                                                                    | `withNativeUITransition()` (still exported by the theme package)                                                     |
+| `IonicNativeUIShellPlugin` (Swift module/native class)                                                                                             | `NativeUIPlugin`                                                                                                     |
+| `RdlaboIonicThemeIos27` (SPM package/product)                                                                                                      | `RdlaboCapacitorNativeUi`                                                                                            |
+| `data-shell="disabled"`                                                                                                                            | `data-native-ui="disabled"`                                                                                          |
+| `.ios-theme-shell-disabled`                                                                                                                        | `.native-ui-disabled`                                                                                                |
 
 Runtime-owned attributes/events are internal, not configuration: `data-native-ui-shell` is now `data-native-ui-projected`, other `data-native-ui-shell-*` attributes use `data-native-ui-*`, `nativeUIShell*` events use `nativeUI*`, and `.ios-theme-native-ui-shell-*` classes use `.native-ui-*`. Update application tests or diagnostics that inspect them. **Keep explicit source declarations such as `data-native-ui="button"` unchanged**; the projected marker is separate and is managed by the runtime.
 
 ## Native UI transition adapter
 
-The Ionic transition adapter now belongs to `@rdlabo/ionic-theme-ios27`. Replace preview imports from the plugin’s `/integration` or `/vertical-bars` entry with the theme root. Native-only applications can use `shell.suspend()` and the returned `resume()` directly.
+The Ionic transition adapter now belongs to `@rdlabo/ionic-theme-ios27`. Replace the 1.2.1 import of `withNativeUIShellTransition` from `@rdlabo/ionic-theme-ios27/vertical-bars` with `withNativeUITransition` from the theme root. Native-only applications can use `shell.suspend()` and the returned `resume()` directly.
 
 Use `withNativeUITransition()` to keep your existing Ionic navigation animation while coordinating Native UI controls.
 
-- If you already import `iosTransitionAnimation` from `@rdlabo/ionic-theme-ios27`, keep the [package animation setup](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo-with-original-theme.md#use-this-packages-ios-animation); no configuration change is needed. It now uses the shared adapter internally; do not add another wrapper.
-- If you use Ionic's default animation without a `navAnimation` option, follow [Keep Ionic's default animation](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo-with-original-theme.md#keep-ionics-default-animation). The example selects Ionic's standard iOS or MD builder from the transition mode.
+- If you already import `iosTransitionAnimation` from `@rdlabo/ionic-theme-ios27`, keep the [package animation setup](ionic-vertical-bars.md#use-the-themes-ios-animation); no configuration change is needed. It now uses the shared adapter internally; do not add another wrapper.
+- If you use Ionic's default animation without a `navAnimation` option, follow [Keep Ionic's default animation](ionic-vertical-bars.md#keep-ionics-default-animation). The example selects Ionic's standard iOS or MD builder from the transition mode.
 - If you use a custom navigation animation with Native UI or the standalone Vertical Control Area, wrap your existing builder when configuring Ionic:
 
 ```diff
@@ -141,66 +122,63 @@ Merge this option into your existing Ionic configuration before initialization.
 
 Use the adapter only for navigation; leave modal and popover animations unchanged. Your builder must create a fresh `Animation` for each navigation because Ionic destroys it afterward. Keep lifecycle events for control registration and transitions without animation. If the custom builder animates a horizontal back button separately, exclude that effect while `.ios-theme-vertical-bars` is active.
 
-See [Connect your navigation animation](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo-with-original-theme.md#3-connect-your-navigation-animation) for the setup and supported scope.
+See [Connect your navigation animation](ionic-vertical-bars.md#2-connect-your-navigation-animation) for the setup and supported scope.
 
-## Shared shell configuration and HTML adapters
+## Startup options
 
-Run `npx cap sync ios` after updating: JavaScript now sends framework-independent control kinds to Swift. New Swift code also accepts the previous `ion-*` kinds, but new JavaScript requires the matching native plugin.
+In 1.2.1, providing `controls` enabled **only fields set to `true`**. In the new API, omitted fields default to `true`, even in a partial object. Expand your old selection when migrating.
 
-- `controls.toolbar` becomes `ionic.auto.buttons`.
-- `controls.popover` becomes `verticalBars.popover`.
-- Top-level `buttonProjection` and `buttonDefaultFill` move into `verticalBars`.
-- The new `verticalBars.buttonDefaultFill` uses `'glass'` instead of `null`.
-- `verticalBarsOnly: true` becomes `verticalBars: { only: true }`.
-- Omitted automatic kinds now default to `true`, including partial legacy `controls` objects. Published 1.2.x enabled only fields explicitly set to `true` when `controls` was supplied. Expand partial objects when migrating, even if you keep the legacy option name.
-- The global `enableVerticalControlArea()` remains a legacy startup wrapper. New code starts with `enableNativeUI({ verticalBars: { only: true } })`, then uses the returned handle's `enableVerticalControlArea()` / `disableVerticalControlArea()` methods.
-- Legacy option names and global `enabled: false` remain accepted; use `shell.destroy()` to stop new code. If both old and new settings are supplied, the new nested settings take precedence.
+| 1.2.1                               | New configuration                                                                                                                                         |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No `controls`                       | No `controls`: all supported kinds remain selected by default.                                                                                            |
+| `controls: {}`                      | `controls: false` to disable default selection, or `ionic: { auto: false }` to disable Ionic discovery altogether.                                        |
+| `controls.toolbar`                  | Set `controls.buttonGroup`, `controls.button`, and `controls.backButton` to the old toolbar value.                                                        |
+| `controls.tabs`, `.segment`, `.fab` | Same names, but explicitly use `false` for previously omitted fields.                                                                                     |
+| `buttonProjection`                  | `ionic.verticalBars.buttonProjection`                                                                                                                     |
+| `buttonDefaultFill: null`           | `ionic.verticalBars.buttonDefaultFill: 'glass'` (also the default)                                                                                        |
+| `buttonDefaultFill: 'solid'`        | `ionic.verticalBars.buttonDefaultFill: 'solid'`                                                                                                           |
+| `verticalBarsOnly: true`            | `controls: 'verticalOnly'` for default selection in the rail. For a partial selection, use `'verticalOnly'` on each enabled kind and `false` on the rest. |
+| `enabled: false`                    | Do not start the runtime, or call the active handle's `destroy()`.                                                                                        |
 
-For example, preserve a Preview configuration that projected only tabs:
+The old startup option names are removed, without aliases. The standalone `enableVerticalControlArea()` entry remains available and defaults `controls` to `'verticalOnly'`; its appearance settings also move under `ionic.verticalBars`. Use only one startup entry per app.
+
+### Preserve a tabs-only configuration
 
 ```diff
 - import { enableNativeUIShell } from '@rdlabo/ionic-theme-ios27/native';
 + import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
 
 - const shell = await enableNativeUIShell({
-+ const shell = await enableNativeUI({
 -   controls: { tabs: true },
 -   buttonProjection: 'source',
 -   buttonDefaultFill: null,
-+   ionic: { auto: { tabs: true, buttons: false, segment: false, fab: false } },
-+   verticalBars: { buttonProjection: 'source', buttonDefaultFill: 'glass' },
++ const shell = await enableNativeUI({
++   controls: {
++     buttonGroup: false,
++     button: false,
++     backButton: false,
++     tabs: true,
++     segment: false,
++     fab: false,
++   },
++   ionic: {
++     verticalBars: { buttonProjection: 'source', buttonDefaultFill: 'glass' },
++   },
   });
 ```
 
-Likewise, replace `controls: {}` with `ionic: { auto: false }` to keep automatic Ionic projection off. Explicit `data-native-ui` sources and extensions remain independent. Calling `enableNativeUI()` with no options still enables all supported automatic kinds.
-
-### Toolbar selection and grouping by layout
+### Select controls by placement
 
-`horizontal` and `vertical` are new toolbar settings. Omit them to retain automatic selection and grouping, or configure each layout independently:
+All six control fields accept `boolean | 'horizontalOnly' | 'verticalOnly'`. A scalar `controls` value applies to every field. Horizontal and vertical mean ordinary placement and the rail, not device orientation or model.
 
 ```ts
-const shell = await enableNativeUI({
-  horizontal: false,
-  vertical: { buttons: false, button: false, backButton: true },
-});
+const shell = await enableNativeUI({ controls: 'verticalOnly' });
 ```
 
-This selects only eligible back buttons among vertical toolbar actions and disables automatic horizontal toolbar selection. Tabs, segments and FABs retain their own settings. To enable all eligible toolbar actions only in vertical layout, use `{ horizontal: false, vertical: true }`; this follows layout, not the Duo model.
-
-Do not translate `controls.toolbar` or `ionic.auto.buttons` into `vertical.buttons`: those options govern the entire automatic toolbar category, while `horizontal.buttons` / `vertical.buttons` govern **grouping only**. Within each layout, `button` selects ordinary actions and `backButton` selects back navigation independently. All three fields default to `true`; a layout value of `false` sets all three to `false`.
-
-If you used the short-lived development settings at the top level, move `{ buttons, button, backButton }` into `vertical: { buttons, button, backButton }`. Those fields were not part of the published 1.2.0/1.2.1 API and are not compatibility aliases. Existing `buttonProjection` / `buttonDefaultFill` are separate appearance settings, mapped above.
+These are selection defaults, not a hard projection scope. Explicit `data-native-ui` sources and local `data-horizontal-bars="true"` / `data-vertical-bars="true"` can opt in even when a matching default is `false`. Remove the explicit marker or use `data-native-ui="disabled"` to leave an individual source on the Web. `ionic.auto: false` disables automatic Ionic discovery, including local layout opt-ins, but leaves explicit source declarations enabled.
 
-Local `data-horizontal-bars="true|false"` / `data-vertical-bars="true|false"` can override these layout defaults. On `ion-buttons` they affect grouping only and never select children. A back button ignores its group's grouping setting. `ionic.auto` and structural exclusions still apply. See [toolbar selection and grouping](native-ui.md#toolbar-selection-and-grouping) for eligibility and when changes take effect.
-
-See [all settings and defaults](configuration.md) and [plain HTML setup](framework-independent.md). Standard HTML buttons use the same Swift controls as Ionic; they do not require an application-specific Swift extension.
+`buttonGroup` controls grouping only. It does not select children: `buttonGroup: true, button: false` projects no ordinary action without explicit selection. `backButton` controls back navigation independently, including inside an `ion-buttons` container. See [all settings](configuration.md) for the complete selection matrix and [toolbar grouping](native-ui.md#toolbar-selection-and-grouping) for local overrides.
 
 ## Web layout ownership
 
 Import `setVerticalBarsLayout` and `applyFoldStateClasses` from `@rdlabo/ionic-theme-ios27` for theme CSS. Replace `setVerticalControlAreaPlacement({ edge, nativeEdge, inset })` with `setVerticalBarsLayout({ edge, inset })`. Native UI now reads availability from its own device metrics; `nativeEdge` is ignored by the deprecated compatibility helper. Normal startup, disabled rails and teardown do not remove theme classes or alter reserved Web spacing. An unavailable native rail keeps the application’s Web rail layout; applications wanting a horizontal layout must select it themselves. Native-only applications can continue to use their own layout CSS.
-
-## Automatic Ionic controls
-
-Use `ionic.auto` for new configuration. It accepts `true` (default), `false`, or `{ buttons, tabs, segment, fab }`. Unlike legacy `controls`, it affects only automatic Ionic projection; explicit `data-native-ui` sources and registered extensions remain enabled. `verticalBars` independently controls rail projection. See [selective projection](configuration.md#select-controls-explicitly-in-a-customized-ionic-app) for an existing Ionic app that opts in individual buttons.
-
-The legacy `controls` option is marked `@deprecated` and remains available. When `ionic.auto` is omitted, legacy kind settings are used, but omitted kinds now default to `true`; expand partial Preview configurations as shown above. If both are supplied, `ionic.auto` takes precedence for automatic kinds. Move the legacy `popover` option to `verticalBars.popover`.