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

package/dist/utils.js

@@ -1,71 +1,63 @@
-export const getElementRoot = (el, fallback = el) => {
-    return el.shadowRoot || fallback;
+//#region src/utils.ts
+const getElementRoot = (el, fallback = el) => {
+	return el.shadowRoot || fallback;
 };
-export const raf = (h) => {
-    if (typeof __zone_symbol__requestAnimationFrame === 'function') {
-        return __zone_symbol__requestAnimationFrame(h);
-    }
-    if (typeof requestAnimationFrame === 'function') {
-        return requestAnimationFrame(h);
-    }
-    return setTimeout(h);
+const raf = (h) => {
+	if (typeof __zone_symbol__requestAnimationFrame === "function") return __zone_symbol__requestAnimationFrame(h);
+	if (typeof requestAnimationFrame === "function") return requestAnimationFrame(h);
+	return setTimeout(h);
 };
-export const cloneElement = (tagName, useCache = true) => {
-    if (useCache) {
-        const cachedElement = document.querySelector(`${tagName}.ion-cloned-element`);
-        if (cachedElement !== null) {
-            return cachedElement;
-        }
-    }
-    const clonedEl = document.createElement(tagName);
-    clonedEl.classList.add('ion-cloned-element');
-    clonedEl.style.setProperty('display', 'none');
-    document.body.appendChild(clonedEl);
-    return clonedEl;
+const cloneElement = (tagName, useCache = true) => {
+	if (useCache) {
+		const cachedElement = document.querySelector(`${tagName}.ion-cloned-element`);
+		if (cachedElement !== null) return cachedElement;
+	}
+	const clonedEl = document.createElement(tagName);
+	clonedEl.classList.add("ion-cloned-element");
+	clonedEl.style.setProperty("display", "none");
+	document.body.appendChild(clonedEl);
+	return clonedEl;
 };
-export const getStep = (targetX, animationPosition) => {
-    if (animationPosition === undefined) {
-        return 0;
-    }
-    const currentX = targetX - animationPosition.width / 2;
-    let progress = (currentX - animationPosition.minPositionX) / (animationPosition.maxPositionX - animationPosition.minPositionX);
-    progress = Math.max(0, Math.min(1, progress));
-    return progress;
+const getStep = (targetX, animationPosition) => {
+	if (animationPosition === void 0) return 0;
+	let progress = (targetX - animationPosition.width / 2 - animationPosition.minPositionX) / (animationPosition.maxPositionX - animationPosition.minPositionX);
+	progress = Math.max(0, Math.min(1, progress));
+	return progress;
 };
-export const changeSelectedElement = (targetElement, selectedElement, effectTagName, selectedClassName) => {
-    targetElement.querySelectorAll(effectTagName).forEach((element) => {
-        element.classList.remove(selectedClassName);
-        element.classList.remove('ion-activated');
-    });
-    selectedElement.classList.add('ion-activated');
+const changeSelectedElement = (targetElement, selectedElement, effectTagName, selectedClassName) => {
+	targetElement.querySelectorAll(effectTagName).forEach((element) => {
+		element.classList.remove(selectedClassName);
+		element.classList.remove("ion-activated");
+	});
+	selectedElement.classList.add("ion-activated");
 };
-export class Config {
-    constructor() {
-        this.m = new Map();
-    }
-    reset(configObj) {
-        this.m = new Map(Object.entries(configObj));
-    }
-    get(key, fallback) {
-        const value = this.m.get(key);
-        return value !== undefined ? value : fallback;
-    }
-    getBoolean(key, fallback = false) {
-        const val = this.m.get(key);
-        if (val === undefined) {
-            return fallback;
-        }
-        if (typeof val === 'string') {
-            return val === 'true';
-        }
-        return !!val;
-    }
-    getNumber(key, fallback) {
-        const val = parseFloat(String(this.m.get(key)));
-        return isNaN(val) ? (fallback !== undefined ? fallback : NaN) : val;
-    }
-    set(key, value) {
-        this.m.set(key, value);
-    }
-}
-export const config = new Config();
+var Config = class {
+	constructor() {
+		this.m = /* @__PURE__ */ new Map();
+	}
+	reset(configObj) {
+		this.m = new Map(Object.entries(configObj));
+	}
+	get(key, fallback) {
+		const value = this.m.get(key);
+		return value !== void 0 ? value : fallback;
+	}
+	getBoolean(key, fallback = false) {
+		const val = this.m.get(key);
+		if (val === void 0) return fallback;
+		if (typeof val === "string") return val === "true";
+		return !!val;
+	}
+	getNumber(key, fallback) {
+		const val = parseFloat(String(this.m.get(key)));
+		return isNaN(val) ? fallback !== void 0 ? fallback : NaN : val;
+	}
+	set(key, value) {
+		this.m.set(key, value);
+	}
+};
+const config = /*@__PURE__*/ new Config();
+//#endregion
+export { Config, changeSelectedElement, cloneElement, config, getElementRoot, getStep, raf };
+
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import { AnimationPosition } from './sheets-of-glass/interfaces';\nimport { IonicConfig } from '@ionic/core';\n\ndeclare const __zone_symbol__requestAnimationFrame: ((callback: FrameRequestCallback) => number) | undefined;\ndeclare const requestAnimationFrame: ((callback: FrameRequestCallback) => number) | undefined;\n\nexport const getElementRoot = (el: HTMLElement, fallback: HTMLElement = el) => {\n  return el.shadowRoot || fallback;\n};\n\nexport const raf = (h: FrameRequestCallback) => {\n  if (typeof __zone_symbol__requestAnimationFrame === 'function') {\n    return __zone_symbol__requestAnimationFrame(h);\n  }\n  if (typeof requestAnimationFrame === 'function') {\n    return requestAnimationFrame(h);\n  }\n  return setTimeout(h);\n};\n\nexport const cloneElement = (tagName: string, useCache: boolean = true): HTMLElement => {\n  if (useCache) {\n    const cachedElement = document.querySelector(`${tagName}.ion-cloned-element`);\n    if (cachedElement !== null) {\n      return cachedElement as HTMLElement;\n    }\n  }\n\n  const clonedEl = document.createElement(tagName) as HTMLElement;\n  clonedEl.classList.add('ion-cloned-element');\n  clonedEl.style.setProperty('display', 'none');\n  document.body.appendChild(clonedEl);\n\n  return clonedEl;\n};\n\nexport const getStep = (targetX: number, animationPosition: AnimationPosition) => {\n  if (animationPosition === undefined) {\n    return 0;\n  }\n  const currentX = targetX - animationPosition.width / 2;\n  let progress = (currentX - animationPosition.minPositionX) / (animationPosition.maxPositionX - animationPosition.minPositionX);\n  progress = Math.max(0, Math.min(1, progress)); // clamp 0〜1\n  return progress;\n};\n\nexport const changeSelectedElement = (\n  targetElement: HTMLElement,\n  selectedElement: HTMLElement,\n  effectTagName: string,\n  selectedClassName: string,\n): void => {\n  targetElement.querySelectorAll(effectTagName).forEach((element) => {\n    element.classList.remove(selectedClassName);\n    element.classList.remove('ion-activated');\n  });\n  selectedElement.classList.add('ion-activated');\n};\n\nexport class Config {\n  private m = new Map<keyof IonicConfig, unknown>();\n\n  reset(configObj: IonicConfig) {\n    this.m = new Map<keyof IonicConfig, unknown>(Object.entries(configObj) as [keyof IonicConfig, unknown][]);\n  }\n\n  get<T>(key: keyof IonicConfig, fallback?: T): T {\n    const value = this.m.get(key);\n    return value !== undefined ? (value as T) : (fallback as T);\n  }\n\n  getBoolean(key: keyof IonicConfig, fallback = false): boolean {\n    const val = this.m.get(key);\n    if (val === undefined) {\n      return fallback;\n    }\n    if (typeof val === 'string') {\n      return val === 'true';\n    }\n    return !!val;\n  }\n\n  getNumber(key: keyof IonicConfig, fallback?: number): number {\n    const val = parseFloat(String(this.m.get(key)));\n    return isNaN(val) ? (fallback !== undefined ? fallback : NaN) : val;\n  }\n\n  set(key: keyof IonicConfig, value: unknown) {\n    this.m.set(key, value);\n  }\n}\n\nexport const config = /*@__PURE__*/ new Config();\n"],"mappings":";AAMA,MAAa,kBAAkB,IAAiB,WAAwB,OAAO;CAC7E,OAAO,GAAG,cAAc;AAC1B;AAEA,MAAa,OAAO,MAA4B;CAC9C,IAAI,OAAO,yCAAyC,YAClD,OAAO,qCAAqC,CAAC;CAE/C,IAAI,OAAO,0BAA0B,YACnC,OAAO,sBAAsB,CAAC;CAEhC,OAAO,WAAW,CAAC;AACrB;AAEA,MAAa,gBAAgB,SAAiB,WAAoB,SAAsB;CACtF,IAAI,UAAU;EACZ,MAAM,gBAAgB,SAAS,cAAc,GAAG,QAAQ,oBAAoB;EAC5E,IAAI,kBAAkB,MACpB,OAAO;CAEX;CAEA,MAAM,WAAW,SAAS,cAAc,OAAO;CAC/C,SAAS,UAAU,IAAI,oBAAoB;CAC3C,SAAS,MAAM,YAAY,WAAW,MAAM;CAC5C,SAAS,KAAK,YAAY,QAAQ;CAElC,OAAO;AACT;AAEA,MAAa,WAAW,SAAiB,sBAAyC;CAChF,IAAI,sBAAsB,KAAA,GACxB,OAAO;CAGT,IAAI,YADa,UAAU,kBAAkB,QAAQ,IAC1B,kBAAkB,iBAAiB,kBAAkB,eAAe,kBAAkB;CACjH,WAAW,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,QAAQ,CAAC;CAC5C,OAAO;AACT;AAEA,MAAa,yBACX,eACA,iBACA,eACA,sBACS;CACT,cAAc,iBAAiB,aAAa,CAAC,CAAC,SAAS,YAAY;EACjE,QAAQ,UAAU,OAAO,iBAAiB;EAC1C,QAAQ,UAAU,OAAO,eAAe;CAC1C,CAAC;CACD,gBAAgB,UAAU,IAAI,eAAe;AAC/C;AAEA,IAAa,SAAb,MAAoB;;EAClB,KAAQ,oBAAI,IAAI,IAAgC;;CAEhD,MAAM,WAAwB;EAC5B,KAAK,IAAI,IAAI,IAAgC,OAAO,QAAQ,SAAS,CAAmC;CAC1G;CAEA,IAAO,KAAwB,UAAiB;EAC9C,MAAM,QAAQ,KAAK,EAAE,IAAI,GAAG;EAC5B,OAAO,UAAU,KAAA,IAAa,QAAe;CAC/C;CAEA,WAAW,KAAwB,WAAW,OAAgB;EAC5D,MAAM,MAAM,KAAK,EAAE,IAAI,GAAG;EAC1B,IAAI,QAAQ,KAAA,GACV,OAAO;EAET,IAAI,OAAO,QAAQ,UACjB,OAAO,QAAQ;EAEjB,OAAO,CAAC,CAAC;CACX;CAEA,UAAU,KAAwB,UAA2B;EAC3D,MAAM,MAAM,WAAW,OAAO,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC;EAC9C,OAAO,MAAM,GAAG,IAAK,aAAa,KAAA,IAAY,WAAW,MAAO;CAClE;CAEA,IAAI,KAAwB,OAAgB;EAC1C,KAAK,EAAE,IAAI,KAAK,KAAK;CACvB;AACF;AAEA,MAAa,uBAAuB,IAAI,OAAO"}

package/dist/vertical-bars.d.ts

@@ -1,4 +1,5 @@
-export { enableVerticalControlArea, setVerticalControlAreaPlacement, IonicNativeUIShell } from './native';
-export { withNativeUIShellTransition } from './native-integration/transition';
-export type { NativeUIShellStatus, NativeUIShellSuspension, VerticalBarEdge, VerticalControlAreaHandle } from './native';
-//# sourceMappingURL=vertical-bars.d.ts.map
+import { withNativeUIShellTransition } from "./native-integration/transition.js";
+import { NativeUIShellStatus, NativeUIShellSuspension, VerticalBarEdge, VerticalControlAreaHandle, VerticalControlAreaOptions } from "./native/definitions.js";
+import { applyFoldStateClasses } from "./native/foldable/fold-state.js";
+import { IonicNativeUIShell, enableVerticalControlArea, setVerticalControlAreaPlacement } from "./native/index.js";
+export { IonicNativeUIShell, type NativeUIShellStatus, type NativeUIShellSuspension, type VerticalBarEdge, type VerticalControlAreaHandle, type VerticalControlAreaOptions, applyFoldStateClasses, enableVerticalControlArea, setVerticalControlAreaPlacement, withNativeUIShellTransition };

package/dist/vertical-bars.js

@@ -1,2 +1,4 @@
-export { enableVerticalControlArea, setVerticalControlAreaPlacement, IonicNativeUIShell } from './native';
-export { withNativeUIShellTransition } from './native-integration/transition';
+import { withNativeUIShellTransition } from "./native-integration/transition.js";
+import { IonicNativeUIShell, enableVerticalControlArea, setVerticalControlAreaPlacement } from "./native/index.js";
+import { applyFoldStateClasses } from "./native/foldable/fold-state.js";
+export { IonicNativeUIShell, applyFoldStateClasses, enableVerticalControlArea, setVerticalControlAreaPlacement, withNativeUIShellTransition };

package/docs/iphone-duo-with-original-theme.md

@@ -112,13 +112,25 @@ Use your existing Ionic click handlers, routing, and form associations. All butt
 
 When the application owner is disposed, call `await rail.destroy()` to restore the original controls and release the runtime. If you already use `enableNativeUIShell()`, keep that runtime and follow the [shared placement guide](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#project-controls-into-the-rail).
 
+### Optional: choose native button appearance (unreleased)
+
+The next release adds `buttonProjection` and local projection settings. These options are not available in the `1.2.0-1` installation above. See [Choose button appearance](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#choose-button-appearance) for availability and migration details.
+
+The new default is `system`: SwiftUI styles vertical buttons and tints their icons. If your existing theme should supply their fill and colors, use:
+
+```ts
+const rail = await enableVerticalControlArea({ 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](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#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 `enableVerticalControlArea()` 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](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#toolbar-actions). |
+| 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](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#toolbar-actions). |
 
 ## Connect an iPhone Duo
 
@@ -131,41 +143,18 @@ 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. Native UI Shell uses Swift Package Manager; existing CocoaPods apps can follow [Native UI Shell setup](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell#enable-the-shell). Keep this package's `vertical-bars.css`; the device plugin's `ionic-tabs.css` is not needed with our rail projection.
 
-Replace the browser-only startup above with this after `ion-app` is mounted:
-
-```ts
-import { Capacitor, type PluginListenerHandle } from '@capacitor/core';
-import { enableVerticalControlArea } from '@rdlabo/ionic-theme-ios27/vertical-bars';
-import { Foldable } from '@erkamyaman/capacitor-foldable';
-
-const rail = await enableVerticalControlArea();
-let layoutListener: PluginListenerHandle | undefined;
-
-if (Capacitor.getPlatform() === 'ios') {
-  layoutListener = await Foldable.addListener('barPlacementChange', ({ verticalBarEdge, inset }) =>
-    rail.setPlacement({ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset }),
-  );
-  const { verticalBarEdge, inset } = await Foldable.getBarPlacement();
-  rail.setPlacement({ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset });
-}
-
-// Call when the application owner is disposed.
-const stopVerticalArea = async () => {
-  await layoutListener?.remove();
-  await rail.destroy();
-};
-```
+Replace the browser-only startup with the [device placement setup](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#project-controls-into-the-rail). That setup sends initial values and `barPlacementChange` events to `setVerticalControlAreaPlacement({ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset })`, with subscriptions and cleanup kept in your application.
 
-`setPlacement()` resolves the logical edge through the document direction. Pass Foldable’s measured `inset` with the reported edge so the theme reserves the actual bar width and follows width changes. An inset of `0` clears the explicit width; manually requested rails then use the theme’s CSS safe-area rules. A `null` edge restores the ordinary layout. Devices without a reported rail return `null`, so this example restores the ordinary layout there. On iOS 27.1 or later, Foldable can infer Duo bar placement from safe-area insets when the app is built with an older SDK. To deliberately request a rail when the plugin reports no edge, have your application choose a fixed edge with `rail.setPlacement('trailing')` instead of applying that null placement. This simulates the layout; it does not provide a real system rail or hinge measurements.
+Pass both the requested and native edge with Foldable's measured inset. The placement API resolves RTL. A null edge restores the ordinary layout.
 
-On supported iOS, controls in the rail use the system SwiftUI appearance; your custom Web styling still applies to ordinary content and horizontal controls. Web and Android use Web clones.
+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`. Use `Foldable.getFoldState()` and `foldStateChange` directly, removing the listener when finished. There is no separate start/stop monitoring call.
+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](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#read-the-device-layout) for the subscription example, null values, and monitoring lifetime. See [Adapt the split pane](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo#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 [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo). Those rules apply to this standalone setup too.
+Safe-area handling, overlays, RTL, control eligibility, Web simulation, and the handle API are documented in [Vertical Bars](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars). Those rules apply to this standalone setup too.

package/docs/iphone-duo.md

@@ -6,7 +6,7 @@ title: iPhone Duo support (experimental)
 
 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](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme) to preview the side layout in Chrome. This page explains device events, placement, split panes, and the API.
+**New here?** Start with [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme) to preview the side layout in Chrome. This page explains device events, placement and split panes. [Vertical Bars](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars) documents control projection and the runtime API.
 
 Available in `1.2.0-0` as an **experimental** feature alongside [Native UI Shell](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell). APIs and supported behavior may change. The real system rail and hinge reporting require iOS 27.1 or later and an app built with Xcode 27.1 or newer.
 
@@ -19,7 +19,7 @@ Device state belongs to [`@erkamyaman/capacitor-foldable`](https://github.com/er
 
 ## Choose what to adopt
 
-To keep your existing theme and add only the standalone support, follow [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme). This page covers the shared device-layout rules and API.
+To keep your existing theme and add only the standalone support, follow [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme). This page covers the shared device-layout rules.
 
 | Goal                                             | Stylesheet          | Runtime                                                            |
 | ------------------------------------------------ | ------------------- | ------------------------------------------------------------------ |
@@ -47,128 +47,73 @@ 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.
 
-For a posture-driven split pane, subscribe directly without starting a projection runtime:
+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, type FoldState } from '@erkamyaman/capacitor-foldable';
-
-const applyFold = (fold: FoldState) => {
-  const pane = document.querySelector('ion-split-pane');
-  pane?.classList.toggle('ios-theme-split-pane-half-open', fold.state === 'half-opened');
-  const expanded = fold.state === 'half-opened' || (fold.state === 'flat' && !!fold.hingeBounds);
-  pane?.setAttribute('when', expanded ? '(min-width: 900px)' : '(min-width: 992px)');
-};
-let receivedEvent = false;
-let disposed = false;
-const listener = await Foldable.addListener('foldStateChange', (fold) => {
-  receivedEvent = true;
-  if (!disposed) applyFold(fold);
-});
-const initialFold = await Foldable.getFoldState();
-if (!disposed && !receivedEvent) applyFold(initialFold);
-
-// When the consumer goes away:
-// disposed = true;
-// await listener.remove();
-```
-
-`getFoldState()` and `foldStateChange` report `state` (`'flat'`, `'half-opened'`, or `'closed'`), `posture`, and optional hinge geometry. Without fold information, the plugin returns a flat state without `hingeBounds`; restore the ordinary split-pane breakpoint in that case. The Web implementation also returns a flat state. A half-opened state uses the 900px breakpoint even without hinge geometry; a flat state with hinge geometry also uses 900px. A closed state restores the ordinary 992px breakpoint. Events received during initialization take precedence over the initial read.
+import { Foldable } from '@erkamyaman/capacitor-foldable';
+import { applyFoldStateClasses } from '@rdlabo/ionic-theme-ios27/vertical-bars';
 
-`getBarPlacement()` and `barPlacementChange` report `{ verticalBarEdge: 'leading' | 'trailing' | null, inset: number }`. The edge is **logical**: leading is the physical left in LTR and the physical right in RTL. Pass `{ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset }` to `setPlacement()`. No start/stop monitoring calls are needed; remove each listener when its owner is disposed.
+const root = document.querySelector('ion-app')!;
+const listener = await Foldable.addListener('foldStateChange', (fold) => applyFoldStateClasses(root, fold));
+applyFoldStateClasses(root, await Foldable.getFoldState());
+```
 
-The theme never reads UIKit bar-placement traits. The application supplies `nativeEdge` on the initial read and each event, even when choosing a fixed `edge`. Omit `nativeEdge` to keep the last supplied value; pass `null` when the plugin reports no edge. An explicit `nativeEdge: null` or an initial unregistered edge prevents native vertical projection: `enableVerticalControlArea()` keeps the requested Web rail, while the full Native UI Shell temporarily restores its ordinary horizontal layout. The requested rail is retained so a later reported edge can restore vertical layout. Native vertical projection starts only after a matching non-null edge is supplied. Omitting `nativeEdge` after supplying it preserves that value, including `null`. Passing `{ edge: null, nativeEdge }` updates the reported edge while keeping the rail disabled.
+When the application owner is disposed:
 
-Foldable reports the measured width reserved by the native bar as `inset` and notifies changes through `barPlacementChange`. Pass this value to `setPlacement()` when following the reported edge, rather than assuming a fixed width. When no bar is reported, `inset` is `0`; the theme clears the explicit width and uses its CSS safe-area rules if the application still requests a Web rail. Applications choosing a different edge can supply their own width or use the CSS fallback. WebView corner radius remains a rendering concern: `configureNativeTransition()` uses the shell's `getWebViewMetrics()` API, independently of `Foldable`.
+```ts
+await listener.remove();
+```
 
-**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.
+Subscribe to changes, then read the current state. The same helper handles initial values and events.
 
-## Reserve the vertical rail
+`applyFoldStateClasses` keeps one of `ios-theme-fold-flat`, `ios-theme-fold-half-opened`, and `ios-theme-fold-closed` on the supplied root, preserving unrelated classes. It also sets `ios-theme-fold-expanded` for a half-opened state or a flat state with hinge geometry. A flat state without geometry (including the Web fallback) and a closed state clear that class. The helper does not subscribe to the plugin or change Ionic's split-pane `when` property.
 
-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:
+For rail placement, use `setVerticalControlAreaPlacement` as shown below. Pass the reported logical edge as both `edge` and `nativeEdge`, together with the measured `inset`. Leading is the physical left in LTR and the physical right in RTL. A null edge restores the ordinary layout; an inset of zero clears the explicit width. No start/stop monitoring calls are needed.
 
-```html
-<ion-app class="ios-theme-vertical-bars">...</ion-app>
-```
+WebView corner radius remains a rendering concern: `configureNativeTransition()` uses the shell's `getWebViewMetrics()` API, independently of `Foldable`.
 
-The classes are physical — `-left` always means the physical left edge — because CSS and the native renderer work in physical coordinates. `setPlacement` (below) is the usual way to apply them: it accepts the logical `verticalBarEdge` reported by `Foldable` and resolves it through the document's direction, so an RTL app does not need its own conversion.
-
-For Chrome development, no native plugin is needed — the class alone reserves `80px` to simulate iPhone Duo. When `setPlacement` receives an explicit `{ edge, inset }`, that inset replaces the fallback width, even when it is less than `80px`. Override `--ios-theme-vertical-bars-safe-area-left` or `--ios-theme-vertical-bars-safe-area-right` when simulating a different layout.
-
-This keeps routers and component backgrounds full-viewport. `ion-content` moves its scroll foreground, `ion-toolbar` moves its container foreground, and `ion-fab` adjusts only when placed beside the system UI. The corresponding Ionic safe-area variable is reset inside those foreground components so descendants do not add the inset again.
+**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.
 
-`ion-modal` applies the same foreground correction when its visible dialog spans the viewport width. With the Vertical Control Area runtime enabled, the topmost full-width modal also projects eligible toolbar buttons into its own rail; centered dialogs keep their toolbar buttons and receive no page-rail inset. This includes full-width sheet modals: their rail follows the visible sheet bounds as the breakpoint changes. Eligibility follows the visible dialog width, not the hinge posture or modal type. `ion-menu` and `ion-popover` are handled as separate surfaces: their internal foreground components do not receive the main-page conversion and retain Ionic's standard safe-area handling. A menu presented beside the system UI keeps Ionic's full-viewport animation host and offsets only its visible container by the corresponding inset; a menu from the opposite side is unchanged. Left and right remain physical coordinates in RTL, while Ionic's `side="start"` and `side="end"` values remain logical.
+## Reserve the vertical rail
 
-The mode is component-mode independent: an app can keep Ionic `mode: 'md'` on iOS and still enable Vertical Bars. No component needs `mode="ios"`.
+Load `vertical-bars.css` as shown above. For class-based browser simulation, safe-area handling, RTL and overlay layout, see [Reserve the vertical rail](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#reserve-the-vertical-rail). On device, the placement helper below applies the layout classes and measured inset.
 
 ## Project controls into the rail
 
-Start the standalone runtime once at application startup:
+Start the standalone runtime once after `ion-app` is mounted, and apply the plugin's placement with `setVerticalControlAreaPlacement`:
 
 ```ts
-import { Capacitor, type PluginListenerHandle } from '@capacitor/core';
-import { enableVerticalControlArea } from '@rdlabo/ionic-theme-ios27/vertical-bars';
 import { Foldable } from '@erkamyaman/capacitor-foldable';
+import { setVerticalControlAreaPlacement, enableVerticalControlArea } from '@rdlabo/ionic-theme-ios27/vertical-bars';
 
-// Start on Chrome too; the Web projection stays idle until the class is present.
 const rail = await enableVerticalControlArea();
-let layoutListener: PluginListenerHandle | undefined;
-
-if (Capacitor.getPlatform() === 'ios') {
-  layoutListener = await Foldable.addListener('barPlacementChange', ({ verticalBarEdge, inset }) =>
-    rail.setPlacement({ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset }),
-  );
-  const { verticalBarEdge, inset } = await Foldable.getBarPlacement();
-  rail.setPlacement({ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset });
-}
-
-// Call when the application owner is disposed.
-const stopVerticalArea = async () => {
-  await layoutListener?.remove();
-  await rail.destroy();
-};
+const listener = await Foldable.addListener('barPlacementChange', ({ verticalBarEdge, inset }) =>
+  setVerticalControlAreaPlacement({ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset }),
+);
+const { verticalBarEdge, inset } = await Foldable.getBarPlacement();
+setVerticalControlAreaPlacement({ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset });
 ```
 
-`setPlacement` on the handle and the exported `setVerticalControlAreaPlacement` are the same function; either applies the application's chosen placement to the CSS layout and both projections. It requires a mounted `ion-app` — call it after the app root exists.
-
-- Pass `{ edge, nativeEdge }`: `edge` is the application's chosen logical edge; `nativeEdge` is `verticalBarEdge` from `Foldable.getBarPlacement()`/`barPlacementChange`. They resolve through the nearest `dir` attribute, or the explicit `rtl` argument.
-- Pass `null` to restore the ordinary layout.
-- The device-layout listener reports what iOS chose; the application decides whether to apply it. The theme compares the application's chosen edge with its supplied `nativeEdge`; a mismatch uses the Web rail until the edges match again. For a fixed right-in-LTR rail, pass `{ edge: 'trailing', nativeEdge: verticalBarEdge }` on each `Foldable` update.
-
-Start either `enableVerticalControlArea()` or the full `enableNativeUIShell()` — not both. Repeating the same configuration returns the shared runtime; starting a different configuration while it is active throws an error. The application should have one owner responsible for destroying that runtime. If the app already uses `enableNativeUIShell()`, keep that single runtime and call `setVerticalControlAreaPlacement({ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset })` from its listener.
-
-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. Back navigation can come from outside a fixed toolbar; menu buttons and other toolbar actions still require one.
+When the application owner is disposed:
 
-### Toolbar actions
-
-An `ion-button` moves into the rail when it contains an `ion-icon` or SVG with `slot="icon-only"`. The button must be in a fixed `ion-toolbar` directly inside `ion-header` or `ion-footer`, outside scrolling `ion-content`.
+```ts
+await listener.remove();
+await rail.destroy();
+```
 
-| Icon markup | Placement |
-| --- | --- |
-| `slot="icon-only"` | Vertical rail |
-| `slot="start"`, `slot="end"`, or no slot | Original horizontal toolbar |
-| No icon | Original horizontal toolbar |
+Supply `nativeEdge` on both the initial read and each event so the renderer knows which rail the system actually provides. 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](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#reserve-the-vertical-rail) without connecting device placement.
 
-This rule applies to `fill="default"`, `clear`, `solid`, and `outline`, including buttons with an Ionic `color`. Solid actions retain their background color through a prominent native button; outline actions retain their border color and width. The runtime preserves the original click or form-submit behavior. `type="submit"` and `.button-submit` do not select a different placement.
+Start either `enableVerticalControlArea()` or the full `enableNativeUIShell()` — not both. If the app already uses Native UI Shell, keep that runtime and use the same `setVerticalControlAreaPlacement` callback. The application owner removes its listeners and destroys its runtime on teardown.
 
-```html
-<ion-header>
-  <ion-toolbar>
-    <ion-buttons slot="end">
-      <ion-button type="button" fill="outline" color="primary" aria-label="Done">
-        <ion-icon name="checkmark-outline" slot="icon-only"></ion-icon>
-      </ion-button>
-    </ion-buttons>
-  </ion-toolbar>
-</ion-header>
-```
+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](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#toolbar-actions) for control eligibility.
 
-Give icon-only actions an accessible name, such as `aria-label="Done"`. Keep the original Ionic event handler or form association on the source button.
+### Toolbar actions
 
-The same rule applies to individual buttons and buttons inside `ion-buttons`, on ordinary pages and in the topmost full-width modal. Centered modals, menus, and popovers keep their own toolbar layout. Add `.ios-theme-horizontal-only` to a group or individual button to keep it horizontal. Placement is chosen when a routed page enters; changing an existing button's content or icon slot does not move it between the toolbar and rail until the page leaves and re-enters.
+See [Vertical Bars: Toolbar actions](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#toolbar-actions) for eligible markup, placement, button appearance and local overrides.
 
 ### Tab bar
 
-When the app contains `ion-tabs`, its tab bar moves into the reserved region and uses the native Duo edge spacing; the Ionic `slot` value does not select a different position. Without native projection, the stable Web rail is icon-only, matching the native resting presentation. While the user presses and drags across that rail, every icon-and-label tab reveals its label so the pending destination stays identifiable. The Web tab bar receives pointer input in the simulated system region. Native tabs and a restored Web tab bar fade in over 180ms; disappearance remains immediate. Reduced motion disables this fade. Use `ion-menu` when navigation should become a sidebar; this mode does not convert tabs into a menu. Web clones also work when no `ion-tabs` exists. Disabling the mode or leaving the page removes the native ownership or Web clones and restores their sources. Override `--ios-theme-vertical-bars-toolbar-top` when the simulated system controls use a different vertical layout.
+See [Vertical Bars: Tab bar](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#tab-bar) for navigation, labels and Web fallback behavior.
 
 ## Adapt the split pane
 
@@ -176,7 +121,7 @@ For a side-by-side menu on iPhone Duo, opt the `ion-split-pane` into the separat
 
 ```html
 <ion-split-pane
-  [class.ios-theme-split-pane-half-open]="halfOpened"
+  class="split-pane-fold-layout"
   contentId="main-content"
   when="(min-width: 900px)"
 >
@@ -188,7 +133,7 @@ For a side-by-side menu on iPhone Duo, opt the `ion-split-pane` into the separat
 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 {
+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);
@@ -196,115 +141,10 @@ ion-split-pane {
 }
 ```
 
-The registered `--ios-theme-split-pane-width` defaults to `320px`; `.ios-theme-split-pane-half-open` sets it to `50vw`. Set `halfOpened` when `foldStateChange` reports `state === 'half-opened'` (and read the initial value with `getFoldState()`). Ionic's `when` decides whether the menu is a persistent side pane; use the 900px breakpoint for a half-opened state or a flat state with hinge geometry, and the ordinary 992px breakpoint when closed or flat without geometry. Missing `hingeBounds` alone does not mean the device is flat. The application chooses where to apply this width rule; an ordinary split pane elsewhere is unchanged. This layout does not enable Vertical Bars or move an overlay menu.
-
-## Vertical Control Area API
-
-The generated reference below documents the handle returned by `enableVerticalControlArea()`.
-
-<docgen-index>
-
-* [`setPlacement(...)`](#setplacement)
-* [`getStatus()`](#getstatus)
-* [`suspend()`](#suspend)
-* [`destroy()`](#destroy)
-* [Interfaces](#interfaces)
-* [Type Aliases](#type-aliases)
-
-</docgen-index>
-
-<docgen-api>
-<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
-
-### setPlacement(...)
-
-```typescript
-setPlacement(placement: VerticalBarEdge | VerticalBarPlacement, rtl?: boolean | undefined) => void
-```
-
-Applies the application's chosen placement to both Web and native controls.
-
-| Param           | Type                                                                                                                    |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| **`placement`** | <code><a href="#verticalbaredge">VerticalBarEdge</a> \| <a href="#verticalbarplacement">VerticalBarPlacement</a></code> |
-| **`rtl`**       | <code>boolean</code>                                                                                                    |
+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
 
-### getStatus()
-
-```typescript
-getStatus() => NativeUIShellStatus
-```
-
-Returns the current Web/native projection state.
-
-**Returns:** <code><a href="#nativeuishellstatus">NativeUIShellStatus</a></code>
-
---------------------
-
-
-### suspend()
-
-```typescript
-suspend() => Promise<NativeUIShellSuspension>
-```
-
-Restores projected controls to the Web until the returned lease is resumed.
-
-**Returns:** <code>Promise&lt;<a href="#nativeuishellsuspension">NativeUIShellSuspension</a>&gt;</code>
-
---------------------
-
-
-### destroy()
-
-```typescript
-destroy() => Promise<void>
-```
-
-Stops synchronization, restores Web controls and releases native resources.
-
---------------------
-
-
-### Interfaces
-
-
-#### VerticalBarPlacement
-
-| Prop             | Type                                                        | Description                                                                                                                                                                                                                       |
-| ---------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`edge`**       | <code><a href="#verticalbaredge">VerticalBarEdge</a></code> |                                                                                                                                                                                                                                   |
-| **`inset`**      | <code>number</code>                                         | Explicit rail width in CSS pixels; omitted to use the stylesheet's safe-area rules.                                                                                                                                               |
-| **`nativeEdge`** | <code><a href="#verticalbaredge">VerticalBarEdge</a></code> | Native logical edge reported by the application's device plugin. Null or an unregistered edge uses a Web rail in verticalBarsOnly mode, or the ordinary Native UI Shell layout otherwise. Omission keeps the last supplied value. |
-
-
-#### NativeUIShellStatus
-
-| Prop            | Type                                        |
-| --------------- | ------------------------------------------- |
-| **`state`**     | <code>'native' \| 'stopped' \| 'web'</code> |
-| **`projected`** | <code>number</code>                         |
-| **`updates`**   | <code>number</code>                         |
-| **`reason`**    | <code>string</code>                         |
-
-
-#### NativeUIShellSuspension
-
-| Method     | Signature                    | Description                                                                                    |
-| ---------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
-| **resume** | () =&gt; Promise&lt;void&gt; | Releases this suspension. Native projection resumes after all active suspensions are released. |
-
-
-### Type Aliases
-
-
-#### VerticalBarEdge
-
-Logical edge in the reading direction, matching UIVerticalBarEdge and capacitor-foldable.
-
-<code>'leading' | 'trailing' | null</code>
-
-</docgen-api>
+The runtime handle reference is maintained in [Vertical Bars](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#vertical-control-area-api).