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

package/docs/eslint.md

@@ -2,6 +2,8 @@
 title: Keep lists consistent with ESLint
 ---
 
+# Keep lists consistent with ESLint
+
 Catch missing list groups before they reach the screen. In Ionic Angular apps, `@rdlabo/eslint-plugin-rules` checks the markup used by iOS 27.
 
 ## Enable the list check
@@ -60,7 +62,7 @@ Group the items and import `IonItemGroup` in the standalone component:
 
 The rule checks all `ion-list` elements, including non-inset lists. Radio, reorder, and accordion groups are also supported. It checks Angular templates; it does not inspect React or Vue templates.
 
-See [Using ion-item-group](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/using-ion-item-group) for layout examples and the [rule reference](https://docs.rdlabo.dev/projects/eslint-plugin-rules/docs/rules/require-ion-item-group) for supported structures and automatic fixes.
+See [Using ion-item-group](using-ion-item-group.md) for layout examples and the [rule reference](https://docs.rdlabo.dev/projects/eslint-plugin-rules/docs/rules/require-ion-item-group) for supported structures and automatic fixes.
 
 ## Keep it checked
 

package/docs/features.md

@@ -4,16 +4,20 @@ title: Features
 
 # Features
 
-Customize the theme with CSS variables and Sass mixins, or adopt it one component at a time. Markup-specific opt-ins are documented in [Special markup and classes](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/special-markup).
+Customize the theme with CSS variables and Sass mixins, or adopt it one component at a time. Markup-specific opt-ins are documented in [Special markup and classes](special-markup.md).
 
 ## CSS variables
 
 To customize the library's default styles to match your design, several CSS variables are provided. See this file for details:
 [Default variables](../src/styles/default-variables.scss)
 
-For menus, `--ios-theme-menu-background-rgb` sets the surface RGB channels (light: `225, 230, 240`; dark: `26, 31, 34`). `--ios-theme-menu-background-opacity` controls opacity and defaults to `0.96`. Both are public customization variables and can be set on `ion-menu`.
+| Variable                              | Default                                    | Purpose                                                           |
+| ------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------- |
+| `--ios-theme-menu-background-rgb`     | Light: `225, 230, 240`; dark: `26, 31, 34` | Menu surface RGB channels; set on `ion-menu`.                     |
+| `--ios-theme-menu-background-opacity` | `0.96`                                     | Menu surface opacity; set on `ion-menu`.                          |
+| `--ios-theme-button-press-duration`   | `380ms`                                    | Duration of the button's `:active` scaling with slight overshoot. |
 
-Button press scaling follows `:active` with a slight overshoot. Set `--ios-theme-button-press-duration` (default: `380ms`) to customize its duration instead of the shared activated-transition duration variables.
+Use `--ios-theme-button-press-duration` instead of the shared activated-transition duration variables to customize button press scaling.
 
 ## Liquid Glass mixin
 
@@ -27,9 +31,9 @@ ion-textarea label.textarea-wrapper {
 }
 ```
 
-## Native UI Shell (Preview)
+## Native UI (Preview)
 
-Capacitor iOS apps can use the optional [Native UI Shell](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell) to render supported fixed Ionic controls with UIKit and system Liquid Glass. It is available as a preview in `1.2.0`. Content and application logic stay in the WebView, with Ionic owning routing and page transitions. The guide explains the hybrid approach's origins in Basecamp and Capacitor, setup, supported controls and Web fallback behavior.
+Once your theme is working, [add Native UI](add-native-ui.md) to render supported fixed controls with UIKit and SwiftUI on iOS. Keep theme styles for Web content and fallback controls. Native UI is an optional preview; adding styles alone does not enable it.
 
 ## Selective component imports
 

package/docs/migration.md

@@ -1,42 +1,50 @@
 ---
-title: Migration
+title: Theme migration
 ---
 
-# Migration
+# Theme migration
 
-## Native UI Shell transition adapter
+## Native UI package separation
 
-Use `withNativeUIShellTransition()` to keep your existing Ionic navigation animation while coordinating Native UI Shell controls.
+Theme styles and ordinary theme API imports remain supported. If you previously used native controls through this package, the `/native` and `/vertical-bars` entries have been removed:
 
-- If you already import `iosTransitionAnimation` from `@rdlabo/ionic-theme-ios27`, keep the [package animation setup](./iphone-duo-with-original-theme.md#use-this-package%27s-ios-animation); no configuration change is needed. It now uses the shared adapter internally; do not add another wrapper.
-- If you use Ionic's default animation without a `navAnimation` option, follow [Keep Ionic's default animation](./iphone-duo-with-original-theme.md#keep-ionic%27s-default-animation). The example selects Ionic's standard iOS or MD builder from the transition mode.
-- If you use a custom navigation animation with Native UI Shell or the standalone Vertical Control Area, wrap your existing builder when configuring Ionic:
+| Previous import                           | Replacement                                 |
+| ----------------------------------------- | ------------------------------------------- |
+| `@rdlabo/ionic-theme-ios27/native`        | `@rdlabo/capacitor-native-ui`               |
+| `@rdlabo/ionic-theme-ios27/vertical-bars` | `@rdlabo/capacitor-native-ui/vertical-bars` |
 
-```diff
-+ import { withNativeUIShellTransition } from '@rdlabo/ionic-theme-ios27/vertical-bars';
+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:
 
-  const ionicConfig = {
--   navAnimation: existingTransition,
-+   navAnimation: withNativeUIShellTransition(existingTransition),
-  };
+```sh
+npm install @rdlabo/ionic-theme-ios27 @erkamyaman/capacitor-foldable
 ```
 
-Merge this option into your existing Ionic configuration before initialization. The adapter preserves the animation's effects, duration, and easing while coordinating native retirement, swipe progress, and cancellation. Keep your existing theme stylesheet imports and Native UI Shell or Vertical Control Area startup.
+Replace the former device-layout APIs with Foldable subscriptions:
 
-Use the adapter only for navigation; leave modal and popover animations unchanged. Your builder must create a fresh `Animation` for each navigation because Ionic destroys it afterward. Keep lifecycle events for control registration and transitions without animation. If the custom builder animates a horizontal back button separately, exclude that effect while `.ios-theme-vertical-bars` is active.
+| 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()`                                                   |
 
-See [Connect your navigation animation](./iphone-duo-with-original-theme.md#3.-connect-your-navigation-animation) for the setup and supported scope.
+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 [README setup](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/readme#get-started) selects iOS 27 or iOS 26 styles by browser capability and leaves Ionic's default iOS appearance on older browsers.
+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.
 
 ### 1. Add the new package
 
 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
@@ -127,17 +135,20 @@ To switch entirely to iOS 27, remove the iOS 26 package and replace its styleshe
 + @use '@rdlabo/ionic-theme-ios27/src/styles/md-remove-ios-class-effect.scss';
 ```
 
-Change the animation import from `@rdlabo/ionic-theme-ios26` to `@rdlabo/ionic-theme-ios27`; the existing `isPlatform('ios')` configuration can stay. See the README's [iOS 27-only setup](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/readme#use-only-the-ios-27-theme). Unconditional imports apply the new styles on every browser using Ionic iOS mode.
+Change the animation import from `@rdlabo/ionic-theme-ios26` to `@rdlabo/ionic-theme-ios27`; the existing `isPlatform('ios')` configuration can stay. See the [iOS 27 setup](setup.md). Unconditional imports apply the new styles on every browser using Ionic iOS mode.
 
 ## iOS 27 naming
 
 For the iOS 27 branch or an iOS 27-only app, use `@rdlabo/ionic-theme-ios27`. Its stylesheets are `ionic-theme-ios27.scss` or `ionic-theme-ios27.css`, including the `-dark-always`, `-dark-system`, and `-dark-class` variants. Keep the iOS 26 stylesheet names in the iOS 26 branch of an adaptive setup.
 
-Use the version-independent `--ios-theme-*` CSS variables. The corresponding `--ios26-*` variables remain supported as deprecated fallbacks. When both are set, the new name takes precedence. For example, use `--ios-theme-content-box-shadow-rgb` instead of `--ios26-content-box-shadow-rgb`.
+| Customization       | Current name                                                      | Legacy behavior                                                                                   |
+| ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| CSS variables       | `--ios-theme-*`, for example `--ios-theme-content-box-shadow-rgb` | Corresponding `--ios26-*` names remain deprecated fallbacks. Current names win when both are set. |
+| Theme opt-out class | `ios-theme-disabled`                                              | `ios26-disabled` remains a deprecated alias; migrate existing markup when convenient.             |
 
-For opting out of the theme, use the version-independent `ios-theme-disabled` class. The `ios26-disabled` class remains supported as a deprecated alias; migrate existing markup when convenient.
+Use the version-independent names for new customizations.
 
-See [Special markup and classes](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/special-markup) and [Default variables](../src/styles/default-variables.scss) for the current names.
+See [Special markup and classes](special-markup.md) and [Default variables](../src/styles/default-variables.scss) for the current names.
 
 Earlier migration notes are preserved in the [iOS 26 migration guide](https://docs.rdlabo.dev/projects/ionic-theme-ios26/docs/migration).
 

package/docs/setup.md

@@ -0,0 +1,94 @@
+# Set up the iOS 27 theme
+
+Give an existing Ionic app the iOS 27 appearance in four steps. This guide uses the iOS 27 theme on its own and system dark mode. For browser-dependent iOS 26/27 styling or MD3, use [adaptive themes](adaptive-themes.md) instead.
+
+## Before you start
+
+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 and Foldable
+
+```sh
+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:
+
+```css
+@import '@ionic/core/css/palettes/dark.system.css';
+@import '@rdlabo/ionic-theme-ios27/dist/css/default-variables.css';
+@import '@rdlabo/ionic-theme-ios27/dist/css/ionic-theme-ios27.css';
+@import '@rdlabo/ionic-theme-ios27/dist/css/md-remove-ios-class-effect.css';
+@import '@rdlabo/ionic-theme-ios27/dist/css/ionic-theme-ios27-dark-system.css';
+```
+
+### Choose one dark-mode pair
+
+Use one matching Ionic palette and theme variant. Paths below are relative to `@ionic/core/css/palettes/` and `@rdlabo/ionic-theme-ios27/dist/css/` respectively.
+
+| Mode                   | Ionic palette     | Theme stylesheet                    | Activation                                      |
+| ---------------------- | ----------------- | ----------------------------------- | ----------------------------------------------- |
+| System (example above) | `dark.system.css` | `ionic-theme-ios27-dark-system.css` | System appearance.                              |
+| Manual                 | `dark.class.css`  | `ionic-theme-ios27-dark-class.css`  | Toggle `ion-palette-dark` on the document root. |
+| Always dark            | `dark.always.css` | `ionic-theme-ios27-dark-always.css` | Always active.                                  |
+
+If you also enable Native UI, these styles provide its light/dark appearance marker. Keep the Ionic palette and theme variant paired so Web and native controls agree. See [native appearance inheritance](../../capacitor-native-ui/docs/appearance.md) for the resolution order and shared rail behavior.
+
+## 3. Configure Ionic animations
+
+Set these options in your existing Ionic initialization, before rendering the app:
+
+```ts
+import { iosTransitionAnimation, popoverEnterAnimation, popoverLeaveAnimation } from '@rdlabo/ionic-theme-ios27';
+
+const ionicConfig = {
+  mode: 'ios' as const,
+  navAnimation: iosTransitionAnimation,
+  popoverEnter: popoverEnterAnimation,
+  popoverLeave: popoverLeaveAnimation,
+};
+```
+
+This example deliberately uses `ios` mode so desktop browsers show the theme too. Pass `ionicConfig` to the initializer your app already uses:
+
+| Framework         | Apply the options                                                            |
+| ----------------- | ---------------------------------------------------------------------------- |
+| Angular / Ionic 8 | `provideIonicAngular(ionicConfig)` imported from `@ionic/angular/standalone` |
+| Angular / Ionic 9 | `provideIonicAngular(ionicConfig)` imported from `@ionic/angular`            |
+| React             | `setupIonicReact(ionicConfig)` imported from `@ionic/react`                  |
+| Vue               | `app.use(IonicVue, ionicConfig)` with `IonicVue` from `@ionic/vue`           |
+
+Merge with existing options; do not initialize Ionic twice. To retain Material Design mode on Android, keep your platform-based mode selection and apply these animation options only to the iOS configuration. See [adaptive themes](adaptive-themes.md) for a complete platform-aware example.
+
+## 4. Preview your first screen
+
+Start your application's usual development server and open an existing page. Add this markup inside its `ion-content` (use your framework's component syntax):
+
+```html
+<ion-list inset="true">
+  <ion-item-group>
+    <ion-item><ion-label>Notifications</ion-label></ion-item>
+    <ion-item><ion-label>Appearance</ion-label></ion-item>
+  </ion-item-group>
+</ion-list>
+```
+
+You should see an inset group with rounded edges. Switch the system between light and dark appearance, then navigate between pages to see the theme transition. Read [Using ion-item-group](using-ion-item-group.md) for list structure.
+
+| If you see…                         | Check…                                                        |
+| ----------------------------------- | ------------------------------------------------------------- |
+| Material Design controls on desktop | Set `mode: 'ios'` in the existing Ionic initializer.          |
+| Unstyled controls                   | Load the theme stylesheet globally after Ionic's base styles. |
+| Mixed light and dark surfaces       | Use one matching Ionic palette and theme dark-mode variant.   |
+| Default page transitions            | Pass the animation options before Ionic initializes.          |
+
+## Next steps
+
+- [Customize styles and components](features.md).
+- [Add Native UI](add-native-ui.md) for supported controls in a Capacitor iOS app. Theme installation alone does not enable native controls.
+- [Add Vertical Bars with an existing theme](../../capacitor-native-ui/docs/ionic-vertical-bars.md).
+- [Migrate an existing app](migration.md).

package/docs/special-markup.md

@@ -28,15 +28,38 @@ buttons: [
 ];
 ```
 
-Buttons with no role or `default` keep the normal text color. `cancel` retains Ionic's cancellation behavior, `selected` remains a selection state, and `destructive` uses `--ios-theme-destructive-color`. An existing `confirm` role is not treated as preferred. Use `preferred` for the recommended action, not simply any action that confirms a choice.
+Choose the role by action semantics:
+
+| Role                 | Appearance and behavior                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------------------- |
+| `preferred`          | Filled primary action; dismissal reports `preferred`. Does not automatically select or invoke it. |
+| No role or `default` | Normal text color.                                                                                |
+| `cancel`             | Retains Ionic's cancellation behavior.                                                            |
+| `selected`           | Retains selection state.                                                                          |
+| `destructive`        | Uses `--ios-theme-destructive-color`.                                                             |
+| `confirm`            | Not treated as preferred. Use `preferred` for a recommended action, not simply any confirmation.  |
 
 ## Floating iPad sheets
 
-Set `expandToScroll: false` on a sheet modal to use floating lower corners and a 20px bottom gap on iPad. Ionic then sizes the visible page at each breakpoint, so the theme can style it with CSS alone. Content scrolls within the current breakpoint; dragging the handle still resizes the sheet. With the default `expandToScroll: true`, the sheet keeps Ionic's bottom-attached layout and scroll-to-expand behavior.
+Choose the sheet's scrolling behavior with `expandToScroll`:
+
+| Setting          | iPad appearance                               | Scrolling and resizing                                                                                                                                     |
+| ---------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `false`          | Floating lower corners and a 20px bottom gap. | Content scrolls within the current breakpoint; dragging the handle resizes the sheet. Ionic sizes the visible page at each breakpoint so CSS can style it. |
+| `true` (default) | Ionic's bottom-attached layout.               | Scroll-to-expand behavior.                                                                                                                                 |
 
 ## Tab bar position
 
-Add one of `tab-bar-position-start`, `tab-bar-position-center`, or `tab-bar-position-end` to an iOS `ion-tab-bar` to position the whole bar within its safe area. These classes work with both `slot="top"` and `slot="bottom"` and preserve the bar's width and press animation. Start and end follow the text direction (reversed in RTL). Without a class, the existing placement is unchanged.
+Choose a class on an iOS `ion-tab-bar` to position the whole bar within its safe area:
+
+| Class                     | Placement                       |
+| ------------------------- | ------------------------------- |
+| `tab-bar-position-start`  | Start of the reading direction. |
+| `tab-bar-position-center` | Center.                         |
+| `tab-bar-position-end`    | End of the reading direction.   |
+| None                      | Existing placement unchanged.   |
+
+All three classes support `slot="top"` and `slot="bottom"`, preserve width and press animation, and resolve start/end in RTL.
 
 ```html
 <ion-tab-bar slot="bottom" class="tab-bar-position-center">
@@ -47,15 +70,15 @@ Add one of `tab-bar-position-start`, `tab-bar-position-center`, or `tab-bar-posi
 
 These classes do not reposition a separate `ion-fab`; leave room for it when choosing the bar's position.
 
-## Support iPhone Duo (preview)
+## Support iPhone Duo
 
-iPhone Duo support, including standalone vertical bars, is available as a **preview** in `1.2.0` alongside Native UI Shell. Its APIs and supported behavior may change.
+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 Shell. See [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo) 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://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars) for rail layout classes, control eligibility and native button appearance.
+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.
 
-For standalone setup while keeping your existing theme, see [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme).
+For standalone setup while keeping your existing theme, see [iPhone Duo with your existing theme](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/capacitor-native-ui/docs/ionic-vertical-bars.md).
 
 ## Two-line inset list items
 
@@ -115,7 +138,15 @@ For colored segments, use Ionic's `color` property (for example, `color="primary
 
 Add `.segment-expand` when segment buttons should divide the available width evenly. The class also changes the Liquid Glass effect sizing when `registerSegmentEffect` is used.
 
-Segments use a 32px minimum height in content and a 48px minimum height inside `ion-toolbar`. `.segment-expand` keeps the compact 32px layout in a toolbar. Compact segments retain Ionic's flat background and indicator colors; only the regular toolbar variant has a glass container and scales its outer container while pressed. Content and expanded segments keep their outer bounds. The optional moving glass lens is independent of the container's background.
+### Segment size and press behavior
+
+| Placement                                 | Minimum height | Container behavior                                               |
+| ----------------------------------------- | -------------- | ---------------------------------------------------------------- |
+| In content                                | 32px           | Compact, flat background and indicator; outer bounds stay fixed. |
+| Inside `ion-toolbar`                      | 48px           | Glass container; outer container scales while pressed.           |
+| `.segment-expand`, including in a toolbar | 32px           | Compact, flat background and indicator; outer bounds stay fixed. |
+
+The optional moving glass lens is independent of the container's background.
 
 ```html preview
 <ion-segment class="segment-expand" value="new">
@@ -178,4 +209,4 @@ Add `.ios-theme-disabled` to an individual Ionic component when it must retain I
 <ion-button>iOS 27 theme</ion-button> <ion-button class="ios-theme-disabled">Standard Ionic button</ion-button>
 ```
 
-For the background model behind inset lists, see [Using `ion-item-group`](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/using-ion-item-group).
+For the background model behind inset lists, see [Using `ion-item-group`](using-ion-item-group.md).

package/docs/using-ion-item-group.md

@@ -20,7 +20,7 @@ The examples use framework-neutral Web Component markup. In React or Vue, use th
 
 No wrapper is required for lists that do not use `inset="true"`.
 
-[Check list structure with ESLint](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/eslint).
+[Check list structure with ESLint](eslint.md).
 
 ## Why the wrapper is required
 
@@ -44,4 +44,4 @@ When an application uses this package without `@rdlabo/ionic-theme-md3`, import
 @import '@rdlabo/ionic-theme-ios27/dist/css/md-ion-list-inset.css';
 ```
 
-For two-line items and section-header groups, see [Special markup and classes](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/special-markup).
+For two-line items and section-header groups, see [Special markup and classes](special-markup.md).

package/docs/vertical-bars-layout.md

@@ -0,0 +1,137 @@
+# Vertical Bars layout
+
+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 @erkamyaman/capacitor-foldable
+```
+
+```scss
+@use '@rdlabo/ionic-theme-ios27/dist/css/vertical-bars.css';
+```
+
+The layout behavior below assumes this stylesheet is loaded. For native runtime setup and device placement, follow the [integration guide](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/capacitor-native-ui/docs/ionic-vertical-bars.md).
+
+## 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
+<ion-app class="ios-theme-vertical-bars">...</ion-app>
+```
+
+The classes are physical — `-left` always means the physical left edge — because CSS and the native renderer work in physical coordinates. `setVerticalBarsLayout` applies the logical `verticalBarEdge` reported by the device plugin and resolves it through the document's direction, so an RTL app does not need its own conversion.
+
+### Rail width
+
+| Source                                   | Reserved width                                                                                      |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Classes alone, including Chrome previews | `80px`; no native plugin required.                                                                  |
+| `setVerticalBarsLayout({ edge, inset })` | The supplied inset, even below `80px`.                                                              |
+| Custom CSS preview                       | Override `--ios-theme-vertical-bars-safe-area-left` or `--ios-theme-vertical-bars-safe-area-right`. |
+
+### Content and overlay layout
+
+| Surface                                  | Layout with the rail stylesheet                                                                                                                                                              |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Routers and component backgrounds        | Remain full-viewport.                                                                                                                                                                        |
+| `ion-content`                            | Insets its scroll foreground.                                                                                                                                                                |
+| `ion-toolbar`                            | Insets its container foreground.                                                                                                                                                             |
+| `ion-fab`                                | Adjusts only when placed beside the system UI.                                                                                                                                               |
+| Full-width `ion-modal`, including sheets | Applies the foreground inset. With the runtime enabled, the topmost modal projects eligible toolbar controls into its own rail; sheet rails follow visible bounds as the breakpoint changes. |
+| Centered modal                           | Keeps toolbar buttons and receives no page-rail inset.                                                                                                                                       |
+| `ion-menu` / `ion-popover`               | Internal foreground components retain Ionic's standard safe-area handling, without the main-page conversion.                                                                                 |
+| Menu beside the system UI                | Keeps its full-viewport animation host; offsets only the visible container by the inset.                                                                                                     |
+| Menu on the opposite side                | Unchanged.                                                                                                                                                                                   |
+
+The corresponding Ionic safe-area variable is reset inside inset foreground components so descendants do not add the inset again.
+
+Modal eligibility follows the visible dialog width, not hinge posture or modal type. Left and right remain physical coordinates in RTL; Ionic's `side="start"` and `side="end"` remain logical.
+
+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"`.
+
+## Layout API
+
+```ts
+import { setVerticalBarsLayout } from '@rdlabo/ionic-theme-ios27';
+
+setVerticalBarsLayout({ edge: 'trailing', inset: 80 });
+// Optionally supply a root element and explicit RTL boolean as the next arguments.
+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": "1.2.1",
+  "version": "2.0.0-2",
   "description": "iOS27 Theme for Ionic Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -12,40 +12,25 @@
       "import": "./dist/index.js"
     },
     "./dist/css/*": "./dist/css/*",
-    "./src/styles/*": "./src/styles/*",
-    "./native": {
-      "types": "./dist/native/index.d.ts",
-      "import": "./dist/native/index.js"
-    },
-    "./vertical-bars": {
-      "types": "./dist/vertical-bars.d.ts",
-      "import": "./dist/vertical-bars.js"
-    }
+    "./src/styles/*": "./src/styles/*"
   },
   "files": [
     "dist",
     "src",
-    "package.json",
-    "docs",
-    "ios",
-    "Package.swift"
+    "LICENSE",
+    "README.md",
+    "docs"
   ],
   "scripts": {
-    "build": "npm run docgen && npm run build:css && npm run build:ts",
     "prebuild:css": "rdlabo-copy-structured-list src/styles/utils/structured-list.scss",
     "build:css": "rm -rf dist/css && sass src/styles:dist/css --style=compressed --no-source-map",
     "build:ts": "tsc --noEmit && rdlabo-build-theme",
-    "docgen": "docgen --project tsconfig.docgen.json --api NativeUIShellHandle --output-readme docs/native-ui-shell.md && docgen --project tsconfig.docgen.json --api VerticalControlAreaHandle --output-readme docs/vertical-bars.md",
-    "build:demo": "npm run build && cd demo && npm install && npm run build -- --configuration=production",
-    "lint": "prettier --check \"./**/*.{scss,ts}\" &&  prettier --parser angular --check \"./**/*.html\"",
-    "fmt": "prettier --write \"./**/*.{scss,ts}\" &&  prettier --parser angular --write \"./**/*.html\"",
-    "release": "np --no-tests --no-publish",
-    "prepublishOnly": "npm run build",
-    "test:esm": "rdlabo-check-esm"
+    "build": "rm -rf dist && npm run build:css && npm run build:ts"
   },
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/rdlabo-dev/ionic-theme-ios27.git"
+    "url": "git+ssh://git@github.com/rdlabo-dev/ionic-theme-ios27.git",
+    "directory": "packages/theme-ios27"
   },
   "keywords": [
     "ionic",
@@ -61,20 +46,10 @@
   },
   "homepage": "https://docs.rdlabo.dev/projects/ionic-theme-ios27",
   "dependencies": {
-    "@rdlabo/ionic-theme-utils": "0.1.2"
-  },
-  "devDependencies": {
-    "@capacitor/core": "^8.5.2",
-    "@ionic/angular": "^9.0.0",
-    "@rdlabo/capacitor-docgen": "^0.4.1",
-    "husky": "^9.1.7",
-    "lint-staged": "^16.2.1",
-    "np": "^10.2.0",
-    "prettier": "^3.6.2",
-    "sass": "^1.93.2",
-    "tsdown": "^0.23.0",
-    "typescript": "^5.9.3",
-    "wrangler": "^4.125.0"
+    "@rdlabo/capacitor-native-ui": "2.0.0-2",
+    "@rdlabo/ionic-theme-utils": "0.1.4",
+    "@stencil/core": "^4.43.5",
+    "ionicons": "^8.1.0"
   },
   "peerDependencies": {
     "@capacitor/core": ">=8.0.0 <9",
@@ -85,10 +60,5 @@
       "optional": true
     }
   },
-  "capacitor": {
-    "ios": {
-      "src": "ios"
-    }
-  },
   "type": "module"
 }

package/src/index.ts

@@ -8,7 +8,7 @@ export {
 export * from './tab-bar-searchable';
 export * from './searchbar';
 export * from './transition/ios.transition';
-export { withNativeUIShellTransition } from './native-integration/transition';
+export { withNativeUITransition } from './transition/native-ui';
 export { registerSegmentEffect } from './segment';
 
 export const registerTabBarEffect = (targetElement: HTMLElement): registeredEffect | undefined => {
@@ -75,3 +75,5 @@ export const registerTabBarEffect = (targetElement: HTMLElement): registeredEffe
     },
   };
 };
+
+export { setVerticalBarsLayout, applyFoldStateClasses, type VerticalBarsLayout, type FoldState } from './layout';