@rdlabo/ionic-theme-ios27 2.0.0-1 → 2.0.0-2

package/README.md

@@ -1,6 +1,6 @@
 # Ionic Theme iOS27
 
-Install with `npm install @rdlabo/ionic-theme-ios27`. For 1.x, use the [v1.2.1 guide](https://github.com/rdlabo-dev/ionic-theme-ios27/tree/ios27-v1.2.1).
+Install with `npm install @rdlabo/ionic-theme-ios27 @erkamyaman/capacitor-foldable`. For 1.x, use the [v1.2.1 guide](https://github.com/rdlabo-dev/ionic-theme-ios27/tree/ios27-v1.2.1).
 A theme for Ionic apps that brings iOS 27 Liquid Glass and motion to the Web. Capacitor iOS apps can also opt into a preview Native UI for supported controls.
 
 **[Ionic 9 demo](https://ionic-theme-ios27.rdlabo.dev/) · [Ionic 8 demo](https://ionic8-theme-ios27.rdlabo.dev/) · [Setup guide](docs/setup.md)**
@@ -27,7 +27,9 @@ A theme for Ionic apps that brings iOS 27 Liquid Glass and motion to the Web. Ca
 
 ## Get started
 
-Use the [four-step setup guide](docs/setup.md) to install the theme, load styles, configure animations, and preview your first screen. It supports Ionic 8.8.1 or later within Ionic 8 or 9, including Angular, React, and Vue. Capacitor is not required.
+We use [Capacitor Foldable](https://github.com/erkamyaman/capacitor-foldable), an excellent community plugin by Erkam Yaman, as our standard device-layout integration. It exposes fold state, hinge geometry, bar placement and change events to your application, giving you control over how the layout responds. Foldable handles device reporting; the theme provides Web layout helpers and Native UI projects controls. Install it alongside the package you use, then connect its events in your app.
+
+Use the [four-step setup guide](docs/setup.md) to install the theme, load styles, configure animations, and preview your first screen. It supports Ionic 8.8.1 or later within Ionic 8 or 9, including Angular, React, and Vue. A native Capacitor project is not required for browser use.
 
 The theme styles toolbars, tabs, lists, buttons, search, and overlays, with light and dark appearances. It does not activate native controls. Once the Web theme is working, you can optionally [add Native UI](docs/add-native-ui.md).
 
@@ -38,5 +40,4 @@ The theme styles toolbars, tabs, lists, buttons, search, and overlays, with ligh
 - [Using ion-item-group](docs/using-ion-item-group.md): inset list markup.
 - [Animation](docs/animation.md): tab, segment, and search effects.
 - [ESLint](docs/eslint.md): catch unsupported list structure.
-- [Vertical Bars layout](docs/vertical-bars-layout.md): spacing, RTL, and layout helpers.
-- [iPhone Duo device layout](docs/iphone-duo.md): connect device placement and hinge posture.
+- [Vertical Bars layout](docs/vertical-bars-layout.md): spacing, RTL, device placement, posture, and split panes.

package/docs/adaptive-themes.md

@@ -7,7 +7,7 @@ Use this optional setup when you want browser capabilities to select iOS styles,
 Install both themes in an existing Ionic 8 or 9 app (`@ionic/core` 8.8.1 or later):
 
 ```bash
-npm install @rdlabo/ionic-theme-ios26 @rdlabo/ionic-theme-ios27
+npm install @rdlabo/ionic-theme-ios26 @rdlabo/ionic-theme-ios27 @erkamyaman/capacitor-foldable
 ```
 
 ## 2. Load styles
@@ -106,7 +106,7 @@ Use this markup to preview the inset grouped list look. For the list structure t
 Install all three themes to use iOS 27 on supported Safari versions, fall back to iOS 26 on the preceding Safari generation, and use MD3 whenever Ionic runs in Material Design mode. All three themes require `@ionic/core` 8.8.1 or later:
 
 ```bash
-npm install @rdlabo/ionic-theme-ios26 @rdlabo/ionic-theme-ios27 @rdlabo/ionic-theme-md3
+npm install @rdlabo/ionic-theme-ios26 @rdlabo/ionic-theme-ios27 @rdlabo/ionic-theme-md3 @erkamyaman/capacitor-foldable
 ```
 
 Keep the two iOS themes behind the same browser feature checks used in step 2 above, then load MD3 unconditionally. Using `meta.load-css()` throughout also keeps the MD3 styles after the conditional iOS styles in the generated CSS:

package/docs/add-native-ui.md

@@ -10,10 +10,10 @@ Read [how projection works](../../capacitor-native-ui/README.md#how-projection-w
 
 This guide assumes a Capacitor 8 application with an iOS project. Web-only theme users can continue without Capacitor; adding native iOS controls requires setting up that native project first. See [Native UI requirements](../../capacitor-native-ui/README.md#requirements) for supported Ionic, iOS, and Xcode versions.
 
-Install both packages together from npm so the theme and native plugin use the same version:
+Update the theme and Native UI together to keep their versions aligned, and install Foldable as a separate application dependency:
 
 ```sh
-npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui
+npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui @erkamyaman/capacitor-foldable
 ```
 
 Keep your existing theme stylesheets. Capacitor's default plugin discovery requires a direct dependency; the copy installed through the theme alone does not register the native plugin.
@@ -46,7 +46,7 @@ Run the app on a supported iOS device or simulator. Eligible fixed controls shou
 
 ## Optional: Vertical Bars
 
-For a side rail, load the [Vertical Bars layout stylesheet](vertical-bars-layout.md) and configure [device placement](iphone-duo.md). The Shell includes the rail runtime; no additional startup call is needed. To automatically select rail controls, use `enableNativeUI({ controls: 'verticalOnly' })` instead of the default startup call. See [configuration options](../../capacitor-native-ui/docs/configuration.md).
+For a side rail, follow the [standard Vertical Bars setup](../../capacitor-native-ui/docs/ionic-vertical-bars.md): load the layout stylesheet and connect the installed Foldable plugin’s initial placement and events. The Shell includes the rail runtime; no additional startup call is needed. To automatically select rail controls, use `enableNativeUI({ controls: 'verticalOnly' })` instead of the default startup call. See [configuration options](../../capacitor-native-ui/docs/configuration.md).
 
 ## Upgrading an existing native integration
 

package/docs/migration.md

@@ -15,6 +15,26 @@ Theme styles and ordinary theme API imports remain supported. If you previously
 
 Add the native package as a direct application dependency, update imports, rebuild Web assets, and run `npx cap sync ios`. Follow the [Native UI migration guide](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/capacitor-native-ui/docs/migration.md) for 1.2.1 startup settings and native project changes. Theme-only apps do not need native startup or plugin setup.
 
+## Device layout in 2.0
+
+Install Foldable alongside the theme as part of the standard setup:
+
+```sh
+npm install @rdlabo/ionic-theme-ios27 @erkamyaman/capacitor-foldable
+```
+
+Replace the former device-layout APIs with Foldable subscriptions:
+
+| Previous API                         | Replacement                                                                         |
+| ------------------------------------ | ----------------------------------------------------------------------------------- |
+| `DeviceLayout`, `HingeStatus`        | `BarPlacement`, `FoldState` and `HingeStatus` from `@erkamyaman/capacitor-foldable` |
+| `getDeviceLayout()`                  | `Foldable.getBarPlacement()` and `Foldable.getFoldState()`                          |
+| `deviceLayoutChange`                 | `barPlacementChange` and `foldStateChange` listeners                                |
+| Start/stop device-layout monitoring  | Subscribe with `addListener()`; remove each listener at teardown                    |
+| One-shot WebView corner-radius reads | Native UI's `getWebViewMetrics()`                                                   |
+
+Apply placement with `setVerticalBarsLayout` and posture with `applyFoldStateClasses`, both imported from the theme. Read the initial state as well as subscribing to changes. See [device layout and split panes](vertical-bars-layout.md#read-the-device-layout) and [rail projection](../../capacitor-native-ui/docs/vertical-bars.md#use-with-capacitor-foldable) for the current setup. Installing the packages alone does not subscribe to device events or activate projection.
+
 ## From the iOS 26 theme
 
 For an app using `@rdlabo/ionic-theme-ios26`, the recommended migration keeps that package and adds `@rdlabo/ionic-theme-ios27`. The [adaptive theme setup](adaptive-themes.md) selects iOS 27 or iOS 26 styles by browser capability and leaves Ionic's default iOS appearance on older browsers.
@@ -24,7 +44,7 @@ For an app using `@rdlabo/ionic-theme-ios26`, the recommended migration keeps th
 Keep the iOS 26 package and add iOS 27. The new theme requires `@ionic/core` 8.8.1 or later (Ionic 8 or 9).
 
 ```bash
-npm install @rdlabo/ionic-theme-ios27
+npm install @rdlabo/ionic-theme-ios27 @erkamyaman/capacitor-foldable
 ```
 
 ### 2. Make the styles adaptive

package/docs/setup.md

@@ -4,14 +4,16 @@ Give an existing Ionic app the iOS 27 appearance in four steps. This guide uses
 
 ## Before you start
 
-Use an existing Ionic Angular, React, or Vue application with Ionic `>=8.8.1 <10`. Keep Ionic's base CSS imports. Capacitor is not required, including for browser-only apps.
+Use an existing Ionic Angular, React, or Vue application with Ionic `>=8.8.1 <10`. Keep Ionic's base CSS imports. Browser-only apps do not need a native Capacitor project.
 
-## 1. Install the theme
+## 1. Install the theme and Foldable
 
 ```sh
-npm install @rdlabo/ionic-theme-ios27
+npm install @rdlabo/ionic-theme-ios27 @erkamyaman/capacitor-foldable
 ```
 
+[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. Connect it using the [layout guide](vertical-bars-layout.md) when configuring device layout.
+
 ## 2. Load the styles
 
 Add these imports to your global stylesheet after Ionic's base styles. Replace an existing Ionic dark palette import rather than loading multiple palettes:

package/docs/special-markup.md

@@ -74,7 +74,7 @@ These classes do not reposition a separate `ion-fab`; leave room for it when cho
 
 iPhone Duo support, including standalone Vertical Bars, is stable starting with version 2.0.0.
 
-iPhone Duo support — the vertical system rail, hinge posture, and the posture-driven split-pane layout — is independent of the iOS 27 theme and the full Native UI. See [iPhone Duo support](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo.md) for the complete setup, including device-layout monitoring without a projection runtime.
+iPhone Duo support — the vertical system rail, hinge posture, and the posture-driven split-pane layout — is independent of the iOS 27 theme and the full Native UI. See [Device layout and split panes](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/vertical-bars-layout.md) for the complete setup, including device-layout monitoring without a projection runtime.
 
 See [Vertical Bars](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/capacitor-native-ui/docs/vertical-bars.md) for rail layout classes, control eligibility and native button appearance.
 

package/docs/vertical-bars-layout.md

@@ -3,7 +3,7 @@
 This optional theme stylesheet owns Web spacing and positioning around a vertical rail. It can be used with your existing theme without loading the full iOS 27 appearance. Native rendering and state synchronization are provided separately by [Capacitor Native UI](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/capacitor-native-ui/docs/vertical-bars.md).
 
 ```sh
-npm install @rdlabo/ionic-theme-ios27
+npm install @rdlabo/ionic-theme-ios27 @erkamyaman/capacitor-foldable
 ```
 
 ```scss
@@ -14,6 +14,8 @@ The layout behavior below assumes this stylesheet is loaded. For native runtime
 
 ## Reserve the vertical rail
 
+For device setup, use the installed Foldable plugin and apply its initial placement and events through `setVerticalBarsLayout`; follow the [standard Ionic rail setup](../../capacitor-native-ui/docs/ionic-vertical-bars.md). The classes below describe the stylesheet's layout inputs and optional browser simulation, not a manual device setup step.
+
 Add `.ios-theme-vertical-bars` to `ion-app` to reserve the rail region on the physical right, or add `.ios-theme-vertical-bars-left` as well to use the physical left:
 
 ```html
@@ -62,6 +64,74 @@ setVerticalBarsLayout({ edge: null }); // restore ordinary Web layout
 
 The helper operates on Web CSS only and works without Capacitor or Native UI startup. The application supplies device state and owns subscriptions. Starting, disabling or destroying Native UI does not change these layout classes or the reserved inset. Unsupported native rails retain the chosen Web rail; choose `edge: null` explicitly if the application wants a horizontal layout instead.
 
+## Read the device layout
+
+The standard theme and Native UI setup commands install Foldable as a separate application dependency. After building your Web assets, sync the native project:
+
+```bash
+npx cap sync
+```
+
+Use Capacitor 8.5 or later and build with Xcode 27.1 or newer for iPhone Duo's iOS 27.1 APIs. Foldable supplies placement and posture in the standard setup. Browser simulation can temporarily replace its subscription with fixed layout values. Do not import the plugin's `ionic-tabs.css` alongside this package's rail projection; both would reposition the same tabs.
+
+After `ion-app` is mounted, pass device state to `applyFoldStateClasses`. The application owns subscriptions and cleanup. No projection runtime is needed for posture-driven layout.
+
+```ts
+import { Foldable } from '@erkamyaman/capacitor-foldable';
+import { applyFoldStateClasses } from '@rdlabo/ionic-theme-ios27';
+
+const root = document.querySelector('ion-app')!;
+const listener = await Foldable.addListener('foldStateChange', (fold) => applyFoldStateClasses(root, fold));
+applyFoldStateClasses(root, await Foldable.getFoldState());
+```
+
+When the application owner is disposed:
+
+```ts
+await listener.remove();
+```
+
+Subscribe to changes, then read the current state. The same helper handles initial values and events.
+
+### Posture classes
+
+`applyFoldStateClasses` updates the supplied root while preserving unrelated classes:
+
+| Class                        | Applied when                                                                                                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `ios-theme-fold-flat`        | Flat posture.                                                                                                            |
+| `ios-theme-fold-half-opened` | Half-opened posture.                                                                                                     |
+| `ios-theme-fold-closed`      | Closed posture.                                                                                                          |
+| `ios-theme-fold-expanded`    | Half-opened, or flat with hinge geometry. Cleared for flat without geometry (including Web fallback) and closed posture. |
+
+Only one of the first three classes is retained. The helper does not subscribe to the plugin or change Ionic's split-pane `when` property.
+
+## Adapt the split pane
+
+For a side-by-side menu on iPhone Duo, opt the `ion-split-pane` into the separately measured Settings layout. The sidebar is 320pt when fully unfolded and reaches the display midpoint when half-opened (50vw). The application supplies the posture; both states have the same viewport width, so a width media query cannot distinguish them:
+
+```html
+<ion-split-pane class="split-pane-fold-layout" contentId="main-content" when="(min-width: 900px)">
+  <ion-menu contentId="main-content">...</ion-menu>
+  <div id="main-content">...</div>
+</ion-split-pane>
+```
+
+Set the ordinary split-pane width to 320pt in the application's stylesheet, and let the half-open class change only the width value:
+
+```css
+ion-split-pane.split-pane-fold-layout {
+  --ios-theme-menu-width: var(--ios-theme-split-pane-width);
+  --side-width: var(--ios-theme-menu-width);
+  --side-max-width: var(--ios-theme-menu-width);
+  transition: --ios-theme-split-pane-width 300ms ease;
+}
+```
+
+The registered `--ios-theme-split-pane-width` defaults to `320px`. `applyFoldStateClasses` sets `ios-theme-fold-half-opened` on `ion-app`; the stylesheet then sets only descendant split panes with `split-pane-fold-layout` to `50vw`. Add this opt-in class once; no state-dependent class binding is needed. Other split panes retain their existing width.
+
+Ionic's `when` still controls whether the menu is persistent. The example chooses a fixed 900px breakpoint. If your app needs different breakpoints for folded and ordinary displays, use the `ios-theme-fold-expanded` class applied by the helper to select that policy in your application's layout code. The helper only updates state classes, not `when`. This layout does not enable Vertical Bars or move an overlay menu.
+
 ## Migration
 
 Move `setVerticalControlAreaPlacement` calls from the plugin to `setVerticalBarsLayout({ edge, inset })` from the theme. Move `applyFoldStateClasses` imports to the theme too. Remove `nativeEdge`: it no longer reports availability. The old plugin helpers are deprecated; update existing imports using the [migration guide](../../capacitor-native-ui/docs/migration.md#web-layout-ownership).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rdlabo/ionic-theme-ios27",
   "private": false,
-  "version": "2.0.0-1",
+  "version": "2.0.0-2",
   "description": "iOS27 Theme for Ionic Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -46,7 +46,7 @@
   },
   "homepage": "https://docs.rdlabo.dev/projects/ionic-theme-ios27",
   "dependencies": {
-    "@rdlabo/capacitor-native-ui": "2.0.0-1",
+    "@rdlabo/capacitor-native-ui": "2.0.0-2",
     "@rdlabo/ionic-theme-utils": "0.1.4",
     "@stencil/core": "^4.43.5",
     "ionicons": "^8.1.0"

package/docs/iphone-duo.md

@@ -1,177 +0,0 @@
----
-title: iPhone Duo support
----
-
-# iPhone Duo support
-
-Adapt your Ionic app to iPhone Duo: place navigation and actions in its vertical system rail, and adjust your split pane as the device opens and closes. Existing Ionic markup remains the source of labels, icons, routing, and click handlers.
-
-**New here?** Start with [iPhone Duo with your existing theme](../../capacitor-native-ui/docs/ionic-vertical-bars.md) to preview the side layout in Chrome. This page explains device events, placement and split panes. [Vertical Bars](../../capacitor-native-ui/docs/vertical-bars.md) documents control projection and the runtime API.
-
-iPhone Duo support is stable starting with version 2.0.0. The real system rail and hinge reporting require iOS 27.1 or later and an app built with Xcode 27.1 or newer.
-
-Use the theme layout and native plugin independently for that hardware. Neither requires the full iOS 27 appearance:
-
-- Theme: `dist/css/vertical-bars.css` — opt-in classes that reserve the rail's safe area, plus a registered custom property for a posture-driven split-pane width.
-- Native UI: `enableNativeUI({ controls: 'verticalOnly' })` — selects eligible tabs and toolbar controls placed in the reserved area. On Capacitor iOS they are rendered by a native SwiftUI `TabView` and toolbar; everywhere else the same controls appear as Web clones.
-
-Device state belongs to [`@erkamyaman/capacitor-foldable`](https://github.com/erkamyaman/capacitor-foldable). The **application** subscribes to its events and chooses its layout. The theme reserves space and adapts the split pane; Native UI projects eligible controls. The theme does not monitor hinge state or bar placement.
-
-| Owner               | Responsibility                                                                                              |
-| ------------------- | ----------------------------------------------------------------------------------------------------------- |
-| Foldable            | Report bar placement and hinge posture, initially and when they change.                                     |
-| Application / theme | Subscribe to device events and apply Web layout through `setVerticalBarsLayout` or `applyFoldStateClasses`. |
-| Native UI           | Project eligible controls and determine native rail availability independently.                             |
-
-For the native package's integration, including application-owned CSS and plain HTML, see [Use with Capacitor Foldable](../../capacitor-native-ui/docs/vertical-bars.md#use-with-capacitor-foldable).
-
-## Choose what to adopt
-
-To keep your existing theme and add only the standalone support, follow [iPhone Duo with your existing theme](../../capacitor-native-ui/docs/ionic-vertical-bars.md). This page covers the shared device-layout rules.
-
-| Goal                                       | Stylesheet          | Runtime                                        |
-| ------------------------------------------ | ------------------- | ---------------------------------------------- |
-| Hinge posture only (layout switches)       | none                | none — subscribe to `Foldable` directly        |
-| Posture-driven split-pane width            | `vertical-bars.css` | none — subscribe to `Foldable` directly        |
-| Vertical rail for tabs and toolbar actions | `vertical-bars.css` | `enableNativeUI({ controls: 'verticalOnly' })` |
-| Native shell plus the rail                 | `vertical-bars.css` | `enableNativeUI()` — includes rail projection  |
-
-```scss
-@use '@rdlabo/ionic-theme-ios27/dist/css/vertical-bars.css';
-```
-
-The stylesheet never changes ordinary Ionic UI by itself; every rule requires an opt-in class. Load it unconditionally — these values are simulation and layout inputs, independent from Ionic's normal safe-area variables.
-
-The `/vertical-bars` entry point imports `@capacitor/core` at module load, so install it even for Web-only use (it is an optional peer dependency). Apps that want only the stylesheet and its opt-in classes need nothing else.
-
-## Read the device layout
-
-Install the device-state plugin in the application, then sync the native project:
-
-```bash
-npm install @erkamyaman/capacitor-foldable
-npx cap sync
-```
-
-Use Capacitor 8.5 or later and build with Xcode 27.1 or newer for iPhone Duo's iOS 27.1 APIs. The dependency is needed for device-driven layout, not for the theme's CSS, browser simulation, or native control projection alone. Do not import the plugin's `ionic-tabs.css` alongside this package's rail projection; both would reposition the same tabs.
-
-After `ion-app` is mounted, pass device state to `applyFoldStateClasses`. The application owns subscriptions and cleanup. No projection runtime is needed for posture-driven layout.
-
-```ts
-import { Foldable } from '@erkamyaman/capacitor-foldable';
-import { applyFoldStateClasses } from '@rdlabo/ionic-theme-ios27';
-
-const root = document.querySelector('ion-app')!;
-const listener = await Foldable.addListener('foldStateChange', (fold) => applyFoldStateClasses(root, fold));
-applyFoldStateClasses(root, await Foldable.getFoldState());
-```
-
-When the application owner is disposed:
-
-```ts
-await listener.remove();
-```
-
-Subscribe to changes, then read the current state. The same helper handles initial values and events.
-
-### Posture classes
-
-`applyFoldStateClasses` updates the supplied root while preserving unrelated classes:
-
-| Class                        | Applied when                                                                                                             |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `ios-theme-fold-flat`        | Flat posture.                                                                                                            |
-| `ios-theme-fold-half-opened` | Half-opened posture.                                                                                                     |
-| `ios-theme-fold-closed`      | Closed posture.                                                                                                          |
-| `ios-theme-fold-expanded`    | Half-opened, or flat with hinge geometry. Cleared for flat without geometry (including Web fallback) and closed posture. |
-
-Only one of the first three classes is retained. The helper does not subscribe to the plugin or change Ionic's split-pane `when` property.
-
-### Placement values
-
-For rail placement, import `setVerticalBarsLayout` from the theme and pass the reported logical `edge` with the measured `inset`:
-
-| Value              | Web layout effect                                    |
-| ------------------ | ---------------------------------------------------- |
-| `edge: 'leading'`  | Physical left in LTR; physical right in RTL.         |
-| `edge: 'trailing'` | Physical right in LTR; physical left in RTL.         |
-| `edge: null`       | Restores ordinary layout.                            |
-| Measured `inset`   | Reserves that width; zero clears the explicit width. |
-
-The helper does not report native availability or activate projection. No start/stop monitoring calls are needed. See [Project controls into the rail](#project-controls-into-the-rail) for the subscription.
-
-WebView corner radius remains a rendering concern: `configureNativeTransition()` uses the shell's `getWebViewMetrics()` API, independently of `Foldable`.
-
-**Migration:** the theme's former `DeviceLayout`, `HingeStatus`, `getDeviceLayout()`, `deviceLayoutChange`, and start/stop device-layout monitoring APIs have been removed. Replace device subscriptions with the `Foldable` APIs above; use `getWebViewMetrics()` for one-shot radius reads. Foldable can infer Duo bar placement from safe-area insets when the app is built without the iOS 27.1 SDK. Hinge data still requires the newer SDK. Apps can also request a fixed rail placement independently of the reported edge.
-
-## Reserve the vertical rail
-
-Load `vertical-bars.css` as shown above. For class-based browser simulation, safe-area handling, RTL and overlay layout, see [Reserve the vertical rail](vertical-bars-layout.md#reserve-the-vertical-rail). On device, the placement helper below applies the layout classes and measured inset.
-
-## Project controls into the rail
-
-Enable rail projection once after `ion-app` is mounted, and apply Foldable's placement to the Web layout with `setVerticalBarsLayout`:
-
-```ts
-import { Foldable } from '@erkamyaman/capacitor-foldable';
-import { setVerticalBarsLayout } from '@rdlabo/ionic-theme-ios27';
-import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
-
-const rail = await enableNativeUI({ controls: 'verticalOnly' });
-const listener = await Foldable.addListener('barPlacementChange', ({ verticalBarEdge, inset }) =>
-  setVerticalBarsLayout({ edge: verticalBarEdge, inset }),
-);
-const { verticalBarEdge, inset } = await Foldable.getBarPlacement();
-setVerticalBarsLayout({ edge: verticalBarEdge, inset });
-```
-
-When the application owner is disposed:
-
-```ts
-await listener.remove();
-await rail.destroy();
-```
-
-Native UI detects native availability independently through its own device metrics. The theme helper controls Web layout only. The measured `inset` is passed through instead of assuming a fixed width. Devices without a reported rail, including Web and Android, return a null edge and retain the ordinary layout. For browser simulation, use the [class-based preview](vertical-bars-layout.md#reserve-the-vertical-rail) without connecting device placement.
-
-Start either `enableNativeUI({ controls: 'verticalOnly' })` or the full `enableNativeUI()` — not both. If the app already uses Native UI, keep that runtime and use the same `setVerticalBarsLayout` callback. The application owner removes its listeners and destroys its runtime on teardown.
-
-On supported iOS versions the runtime hands eligible tabs, back navigation, menu buttons, and fixed-toolbar actions to a native SwiftUI `TabView` and toolbar; on Web, Android, or when native projection is unavailable, Web clones remain the fallback. See [Toolbar actions](../../capacitor-native-ui/docs/vertical-bars.md#toolbar-actions) for control eligibility.
-
-### Toolbar actions
-
-See [Vertical Bars: Toolbar actions](../../capacitor-native-ui/docs/vertical-bars.md#toolbar-actions) for eligible markup, placement, button appearance and local overrides.
-
-### Tab bar
-
-See [Vertical Bars: Tab bar](../../capacitor-native-ui/docs/vertical-bars.md#tab-bar) for navigation, labels and Web fallback behavior.
-
-## Adapt the split pane
-
-For a side-by-side menu on iPhone Duo, opt the `ion-split-pane` into the separately measured Settings layout. The sidebar is 320pt when fully unfolded and reaches the display midpoint when half-opened (50vw). The application supplies the posture; both states have the same viewport width, so a width media query cannot distinguish them:
-
-```html
-<ion-split-pane class="split-pane-fold-layout" contentId="main-content" when="(min-width: 900px)">
-  <ion-menu contentId="main-content">...</ion-menu>
-  <div id="main-content">...</div>
-</ion-split-pane>
-```
-
-Set the ordinary split-pane width to 320pt in the application's stylesheet, and let the half-open class change only the width value:
-
-```css
-ion-split-pane.split-pane-fold-layout {
-  --ios-theme-menu-width: var(--ios-theme-split-pane-width);
-  --side-width: var(--ios-theme-menu-width);
-  --side-max-width: var(--ios-theme-menu-width);
-  transition: --ios-theme-split-pane-width 300ms ease;
-}
-```
-
-The registered `--ios-theme-split-pane-width` defaults to `320px`. `applyFoldStateClasses` sets `ios-theme-fold-half-opened` on `ion-app`; the stylesheet then sets only descendant split panes with `split-pane-fold-layout` to `50vw`. Add this opt-in class once; no state-dependent class binding is needed. Other split panes retain their existing width.
-
-Ionic's `when` still controls whether the menu is persistent. The example chooses a fixed 900px breakpoint. If your app needs different breakpoints for folded and ordinary displays, use the `ios-theme-fold-expanded` class applied by the helper to select that policy in your application's layout code. The helper only updates state classes, not `when`. This layout does not enable Vertical Bars or move an overlay menu.
-
-## Vertical Control Area API
-
-The runtime handle reference is maintained in [Vertical Bars](../../capacitor-native-ui/docs/vertical-bars.md#vertical-control-area-api).