@rdlabo/capacitor-native-ui 0.0.0-stage → 2.0.0-1

package/docs/configuration.md

@@ -0,0 +1,219 @@
+# Configure Native UI
+
+This is the settings reference. Start with [how projection works](../README.md#how-projection-works), then [Ionic setup](setup.md) or [HTML setup](framework-independent.md) for installation.
+
+Call `enableNativeUI()` once after your application's DOM is mounted. Ionic and explicitly marked HTML controls share the standard Swift renderers. The theme is optional; Web layout, safe areas and spacing belong to your app or theme.
+
+```ts
+import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
+
+const shell = await enableNativeUI();
+```
+
+Without Ionic, import the same API from `@rdlabo/capacitor-native-ui/core`. That entry does not load Ionic's optional popover integration. See [plain HTML](framework-independent.md).
+
+## Platform behavior
+
+| Feature                                 | Supported iOS                             | Android               | Browser / older iOS   |
+| --------------------------------------- | ----------------------------------------- | --------------------- | --------------------- |
+| Automatic Ionic controls (`ionic.auto`) | Native                                    | Original Web controls | Original Web controls |
+| Explicit element buttons                | Native                                    | Original Web controls | Original Web controls |
+| Element extensions                      | SwiftUI                                   | Kotlin / Compose      | Original Web content  |
+| Vertical Bars                           | Native when available; otherwise Web rail | Web rail              | Web rail              |
+| `tab-accessory` extensions              | Supported iOS tab host only               | Original Web content  | Original Web content  |
+
+Web rails require the Ionic rail layout or an application-owned HTML `webHost`. Settings never create a device capability.
+
+For HTML-derived light/dark behavior, see [Light and dark appearance](appearance.md). Appearance is configured in Web CSS, not through a startup option.
+
+## All settings
+
+`controls` chooses selection and grouping defaults. `verticalBars` configures the rail. `ionic` configures Ionic discovery and appearance. Omitted fields default to `true` in `controls`, including partial objects.
+
+```ts
+const shell = await enableNativeUI({
+  root: document.body,
+  controls: {
+    buttonGroup: true,
+    button: true,
+    backButton: true,
+    tabs: true,
+    segment: true,
+    fab: true,
+  },
+  verticalBars: {
+    enabled: true,
+    // Optional: placement: { edge: 'trailing', webHost: appOwnedHost },
+  },
+  extensions: [],
+  ionic: {
+    auto: true,
+    verticalBars: {
+      buttonProjection: 'system',
+      buttonDefaultFill: 'glass',
+      popover: false,
+    },
+  },
+  debug: false,
+});
+```
+
+### Selection defaults
+
+Every control accepts `ControlProjection`. `controls` itself accepts the same values as a shorthand for all six fields.
+
+| Value              | Ordinary placement | Vertical rail placement |
+| ------------------ | ------------------ | ----------------------- |
+| `true` (default)   | Selected           | Selected                |
+| `false`            | Not selected       | Not selected            |
+| `'horizontalOnly'` | Selected           | Not selected            |
+| `'verticalOnly'`   | Not selected       | Selected                |
+
+Horizontal and vertical describe **control placement**, not screen orientation or device model. These defaults do not move a control, provide a missing device capability, or make unsupported markup eligible.
+
+| Control       | Responsibility                                                                   |
+| ------------- | -------------------------------------------------------------------------------- |
+| `buttonGroup` | Group already selected actions when the group qualifies. Never selects children. |
+| `button`      | Select ordinary buttons and Ionic menu buttons.                                  |
+| `backButton`  | Select back navigation, independently of its parent group.                       |
+| `tabs`        | Select tabs and their registered search presentation.                            |
+| `segment`     | Select supported segments.                                                       |
+| `fab`         | Select supported floating action buttons.                                        |
+
+Local `data-horizontal-bars="true|false"` and `data-vertical-bars="true|false"` override the matching selection default. On `ion-buttons` they control grouping only. Explicit `data-native-ui` sources are independent of these defaults. Structural exclusions and rail availability still apply. See [toolbar selection and grouping](native-ui.md#toolbar-selection-and-grouping).
+
+### Other settings
+
+| Setting                                | Default         | Meaning                                                                                                                                                     |
+| -------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `root`                                 | `document.body` | Connected source subtree. Controls outside it are not projected.                                                                                            |
+| `verticalBars.enabled`                 | `true`          | Allow rail projection when available.                                                                                                                       |
+| `verticalBars.placement`               | omitted         | Optional `{ edge: 'leading' \| 'trailing', webHost?: HTMLElement }`. Edge is a preference, not a capability declaration.                                    |
+| `extensions`                           | `[]`            | **Experimental.** App-specific SwiftUI / Compose extensions. Independent of `controls` and `ionic.auto`; the app decides when its reader returns content.   |
+| `ionic.auto`                           | `true`          | Enable automatic Ionic discovery. `false` disables it, including local layout opt-ins. Explicit `data-native-ui` sources and extensions remain independent. |
+| `ionic.verticalBars.buttonProjection`  | `'system'`      | `'system'` uses native styling; `'source'` projects supported Ionic styling. Local appearance overrides take precedence.                                    |
+| `ionic.verticalBars.buttonDefaultFill` | `'glass'`       | `'glass'` or `'solid'` for source-style standalone Ionic buttons without explicit fill. Explicit fills and the clear default inside groups take precedence. |
+| `ionic.verticalBars.popover`           | `false`         | Opt into Ionic popovers anchored to native rail buttons. Requires the Ionic entry and its optional peers.                                                   |
+| `debug`                                | `false`         | Log source elements and fallback reasons to the developer console.                                                                                          |
+
+### HTML fallback rail host
+
+`webHost` is an optional, application-styled HTML fallback rail. Its requirements are:
+
+- Connected to the same document as `root`.
+- Outside `root`; neither element may contain the other.
+- Styled and positioned by the application, including any reserved content spacing.
+
+Use a limited `root`, such as your `<main>`, with a sibling host; the default `document.body` cannot have such a host. Without a host, unavailable HTML rails leave original controls visible. Ionic's existing rail layout uses its own fallback adapter.
+
+HTML currently supports buttons and back buttons. Tab, segment and FAB readers remain Ionic adapters; enabling those settings does not infer equivalent structures from arbitrary HTML.
+
+## Common configurations
+
+```ts
+// Ionic or HTML: all supported controls, rail support enabled by default.
+const shell = await enableNativeUI();
+
+// Alternative: automatic selection only in the rail.
+const railOnly = await enableNativeUI({ controls: 'verticalOnly' });
+
+// Alternative: automatically select only tabs.
+const tabsOnly = await enableNativeUI({
+  controls: { buttonGroup: false, button: false, backButton: false, tabs: true, segment: false, fab: false },
+});
+```
+
+These are alternatives: start only one shell. Repeating equivalent startup settings returns its handle; different settings require destroying the previous shell.
+
+`controls: false` disables all default selection and grouping, while local attributes can still opt in. `ionic: { auto: false }` instead disables automatic Ionic discovery altogether. Neither disables explicit HTML sources or extensions.
+
+`verticalBars.enabled: false` leaves rail controls on the Web regardless of selection. It does not affect ordinary controls. `data-native-ui-placement="element"` preserves an explicit control's original position, even with `controls: 'verticalOnly'`. For Ionic groups, put placement on the whole `ion-buttons` group so its shared native surface has one placement.
+
+## Select controls explicitly in a customized Ionic app
+
+Disable automatic Ionic projection while retaining the native rail and your custom extensions:
+
+```ts
+const shell = await enableNativeUI({
+  root: document.querySelector<HTMLElement>('#content')!,
+  ionic: { auto: false },
+  verticalBars: {
+    enabled: true,
+    placement: {
+      edge: 'trailing',
+      webHost: document.querySelector<HTMLElement>('#rail')!,
+    },
+  },
+  extensions: [myExtension],
+});
+```
+
+```html
+<main id="content">
+  <ion-button>Keep this on the Web</ion-button>
+  <ion-button data-native-ui="button" data-native-ui-placement="rail">Project this action</ion-button>
+  <button data-native-ui="button">Project at its original position</button>
+</main>
+<aside id="rail" aria-label="Actions"></aside>
+```
+
+Keep your original handlers on each source. Explicit `ion-button` uses the standard button reader, so supported content and styling rules still apply; the attribute does not make arbitrary custom markup supported. `data-native-ui-placement="rail"` requests the system rail when available. Style the optional `webHost` and reserve space in your app; without it, unavailable explicit rails keep their source controls visible. Unmarked Ionic controls remain Web-rendered. An automatically projected group containing an explicitly marked source stays on the Web to avoid covering that source twice.
+
+Explicit built-in sources support individual `button`, `ion-button`, and `[role="button"]` elements with `data-native-ui="button"` or `"back-button"`. This does not opt existing `ion-back-button`, `ion-menu-button`, button groups, tabs, segments, or FABs into their Ionic-specific readers. Keep automatic projection enabled for the corresponding kind, use a standard explicit button with your own click handler, or register an extension for custom UI.
+
+`verticalBars.enabled` still governs rail availability. To leave a specific source on the Web, remove its explicit marker or use `data-native-ui="disabled"`.
+
+## Change rail use after startup
+
+```ts
+await shell.disableVerticalControlArea();
+await shell.enableVerticalControlArea();
+```
+
+These methods change `verticalBars.enabled` on this shell and preserve appearance, controls and placement. They retire existing projection before transferring ownership, without creating another shell. Calls are serialized. Calling either method after `destroy()` rejects.
+
+```ts
+const lease = await shell.suspend(); // temporarily restore all Web controls
+await lease.resume();
+await shell.destroy(); // stop the shell and restore sources
+```
+
+Disabling rail projection does not remove application CSS or change application-owned spacing. Update your own layout alongside this setting if needed.
+
+## Request a check after an unobserved change
+
+```ts
+shell.markForCheck();
+```
+
+Use this after changing a property or reader state that does not cause a DOM mutation. It schedules a check, batches repeated requests, and sends only changed native snapshots. It returns `void`; it does not wait for native completion or render your framework's DOM. Calls after destruction are ignored. See [source checks and observation](native-ui-extensions.md#schedule-a-source-check).
+
+## Understand why a source stays on the Web
+
+Temporarily add `debug: true` to your existing startup options, then rebuild the Web app. Do not start a second shell to enable diagnostics:
+
+```ts
+const shell = await enableNativeUI({ debug: true, extensions: [myExtension] });
+console.info(shell.getStatus());
+```
+
+Open the WebView developer console and filter for `[Native UI]`. Diagnostics include the DOM source when available. Each reason is logged once per source during that activation, so scrolling or repeated `markForCheck()` calls do not flood the console. Props, action payloads and application exception messages are not logged.
+
+| Diagnostic                                            | What to check                                                                                                        |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `web-fallback`                                        | Platform support, native plugin registration, sync and native rebuild.                                               |
+| `unregistered-extension`                              | Native registration name matches the DOM definition and runs before startup. Newly inserted sources are checked too. |
+| `reader-error` / `invalid-props`                      | Reader implementation, JSON-only values and the 64K size limit.                                                      |
+| `unsupported-placement` / `missing-tab-owner`         | Platform and owning native tab host for a tab accessory.                                                             |
+| `source-hidden` / `source-clipped` / `source-focused` | Visibility, clipping/transformed ancestors, or a focused Web descendant.                                             |
+| `reader-opt-out`                                      | Your reader returned null.                                                                                           |
+| `unsupported-control`                                 | Supported markup, accessible name, fixed placement and styling.                                                      |
+| `native-rejected`                                     | Native props decoding, placement or device support. The bridge reports rejection, not the native exception.          |
+
+`getStatus()` summarizes the shell; it is not a per-element diagnostic report. Normal navigation, suspension and unsupported content can intentionally retain Web presentation. Turn debug off after investigating; it does not change projection eligibility.
+
+## Existing applications
+
+The standalone `enableVerticalControlArea()` defaults selection to `'verticalOnly'`. Its `setPlacement()` helper is a deprecated Web CSS adapter; use the theme's `setVerticalBarsLayout({ edge, inset })` for Web layout. Native availability comes from the plugin's device metrics.
+
+See [upgrading from 1.2.1](migration.md) for package separation, removed options and changed partial-control defaults.

package/docs/framework-independent.md

@@ -0,0 +1,107 @@
+# Native UI without Ionic
+
+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 steps 1–2 to install and mark your HTML buttons, then use the [Web rail configuration](#optional-web-rail) in place of step 3. Remove explicit markers from buttons you want to leave on the Web. Style the rail host in your application and build with step 4 for iOS. 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:
+
+```sh
+npm install @rdlabo/capacitor-native-ui
+```
+
+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.
+
+## 2. Mark source controls
+
+```html
+<main id="app">
+  <button type="button" data-native-ui="button" data-native-ui-placement="element">Add</button>
+  <button type="button" data-native-ui="back-button" data-native-ui-placement="rail">Back</button>
+</main>
+<aside id="rail" aria-label="Navigation"></aside>
+```
+
+| 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.                |
+
+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.
+
+## 3. Start after mounting the controls
+
+```ts
+import { enableNativeUI } from '@rdlabo/capacitor-native-ui/core';
+
+const shell = await enableNativeUI({
+  root: document.querySelector<HTMLElement>('#app')!,
+});
+```
+
+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. With the step 3 configuration, Add renders natively and invokes its original click handler. With the rail configuration below, Add retains native element placement and Back uses the native rail when available. 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
+
+For a Web fallback rail, use this instead of the startup call in step 3. Call once after both the source root and rail host are mounted; call `await shell.destroy()` when their owner is disposed. Do not start a second shell:
+
+```ts
+import { enableNativeUI } from '@rdlabo/capacitor-native-ui/core';
+
+const shell = await enableNativeUI({
+  root: document.querySelector<HTMLElement>('#app')!,
+  verticalBars: {
+    placement: {
+      edge: 'trailing',
+      webHost: document.querySelector<HTMLElement>('#rail')!,
+    },
+  },
+});
+```
+
+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.
+
+Explicit markup chooses placement: Back goes to the rail and Add keeps native element placement. To project only Back, remove `data-native-ui="button"` from Add. `controls` does not disable explicit source declarations. To change rail use later, call `await shell.disableVerticalControlArea()` or `await shell.enableVerticalControlArea()`. Disabling restores original rail controls and removes Web rail proxies without destroying ordinary native projection.
+
+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.
+
+For device-driven spacing and placement, see [Use with Capacitor Foldable](vertical-bars.md#use-with-capacitor-foldable). Read its initial placement and subscribe to changes, applying the edge and inset to your own CSS; the theme package is not required.
+
+## Example
+
+The [plain HTML example](https://github.com/rdlabo-dev/ionic-theme-ios27/tree/main/examples/native-ui-html) demonstrates Add, routerless Home/Details/Back navigation, optional Web rail projection and cleanup. It uses no Ionic or theme CSS.

package/docs/ionic-vertical-bars.md

@@ -0,0 +1,173 @@
+---
+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)                                                               | 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 [Web rail configuration](framework-independent.md#optional-web-rail) | Only `@rdlabo/capacitor-native-ui`, using its `/core` entry. Your app supplies the rail layout. |
+| Already using the iOS 27 theme and Native UI                                   | [Connect device placement](../../theme-ios27/docs/iphone-duo.md#project-controls-into-the-rail)                       | 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). Add the two packages:
+
+```bash
+npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui
+```
+
+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. Preview these steps in Chrome before connecting an iPhone Duo.
+
+### 2. Opt your app into the side layout
+
+Add the class to your existing app root and keep the content inside it:
+
+```html
+<ion-app class="ios-theme-vertical-bars">
+  <!-- Keep your existing pages, tabs, and toolbar controls here. -->
+</ion-app>
+```
+
+The preview reserves `80px` on the physical right. To preview the left side, also add `ios-theme-vertical-bars-left`.
+
+### 3. 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.
+
+### 4. Start the controls after the app root is mounted
+
+Call this once from your application startup after `ion-app` exists in the DOM:
+
+```ts
+import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
+
+const rail = await enableNativeUI({ controls: 'verticalOnly' });
+```
+
+**What you should see:** your existing tab bar moves to the side, and fixed-toolbar buttons with an `ion-icon` or SVG using `slot="icon-only"` appear there too. Content keeps its existing theme and leaves room for the controls. The Web tab rail displays icons; pressing and dragging reveals tab labels.
+
+Use your existing Ionic click handlers, routing, and form associations. All button fills (`default`, `clear`, `solid`, and `outline`) use the same `icon-only` rule, including submit buttons. Actions without that slot remain horizontal. Add `.ios-theme-horizontal-only` to an `ion-buttons` group or individual `ion-button` to keep an action in the horizontal toolbar.
+
+When the application owner is disposed, call `await rail.destroy()` to restore the original controls and release the runtime. If you already use `enableNativeUI()`, keep that runtime and follow the [shared placement guide](../../theme-ios27/docs/iphone-duo.md#project-controls-into-the-rail).
+
+### 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 the startup call in step 4 with:
+
+```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 preview does not appear
+
+| What you see                                | What to check                                                                                                                                                                                                                                                                           |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No space at the side                        | Load `vertical-bars.css` and put the class on `ion-app`.                                                                                                                                                                                                                                |
+| Space appears, but controls stay horizontal | Start `enableNativeUI({ controls: 'verticalOnly' })` after mounting the app root. Use existing tabs or `slot="icon-only"` actions in a fixed header/footer toolbar.                                                                                                                     |
+| One action stays horizontal                 | Check for `slot="icon-only"` on the icon and a fixed toolbar outside scrolling content. Explicitly excluded controls and controls in centered modals stay horizontal; `fill` and `type="submit"` do not prevent movement. See [control requirements](vertical-bars.md#toolbar-actions). |
+
+## Connect an iPhone Duo
+
+Install [`@erkamyaman/capacitor-foldable`](https://github.com/erkamyaman/capacitor-foldable) for device state:
+
+```bash
+npm install @erkamyaman/capacitor-foldable
+npx cap sync ios
+```
+
+Use Capacitor 8.5 or later and build with Xcode 27.1 or newer for actual rail placement and hinge posture on iOS 27.1. Keep your existing SPM or CocoaPods integration; see [Native UI setup](setup.md#4-build-sync-and-run). Keep the theme's `vertical-bars.css`; the device plugin's `ionic-tabs.css` is not needed with our rail projection.
+
+Replace the browser-only startup with the [device placement setup](../../theme-ios27/docs/iphone-duo.md#project-controls-into-the-rail). That setup sends initial values and `barPlacementChange` events to `setVerticalBarsLayout({ edge: verticalBarEdge, inset })`, with subscriptions and cleanup kept in your application.
+
+Pass Foldable's reported logical edge and measured inset to `setVerticalBarsLayout`. The helper resolves RTL. A null edge restores the ordinary Web layout; Native UI detects native rail availability independently.
+
+On supported iOS, controls in the rail use native SwiftUI rendering; your custom Web styling still applies to ordinary content and horizontal controls. Web and Android use Web clones.
+
+## 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/iphone-duo.md#read-the-device-layout) for the subscription example, null values, and monitoring lifetime. See [Adapt the split pane](../../theme-ios27/docs/iphone-duo.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.