@rdlabo/ionic-theme-ios27 1.2.0-beta.pr243.shae972a0e49191 → 1.2.0-beta.pr246.sha237333ceac21

package/docs/native-ui-shell.md

@@ -1,10 +1,10 @@
 ---
-title: Native UI Shell (Experimental)
+title: Native UI Shell (Preview)
 ---
 
-# Native UI Shell (Experimental)
+# Native UI Shell (Preview)
 
-Native UI Shell is experimental. Its API and supported controls may change.
+Native UI Shell is available as a **preview** in `1.2.0`. Its API and supported controls may change before stable status. Stable status is planned after the official release of Xcode 27.1.
 
 Native UI Shell gives an Ionic app native navigation and action controls around its Web content. The optional Capacitor iOS plugin renders supported fixed Ionic controls with UIKit or SwiftUI and the system's Liquid Glass material. Page content, scrolling, application state and routing remain in Ionic's WebView.
 
@@ -52,12 +52,14 @@ The table below describes the ordinary Native UI Shell. Vertical Bars uses the s
 | `ion-segment`                                 | Fixed toolbar, non-scrollable, text **or** one icon per item                                              | `UISegmentedControl`                                                  |
 | `ion-fab` / `ion-fab-button` / `ion-fab-list` | Glass FAB in an `ion-content` fixed slot; one main button and optional directional lists                  | Persistent glass `UIButton` per button; one FAB synchronization group |
 
-For the ordinary Native UI Shell, only iOS-mode components with the theme variables installed are eligible. Explicitly enabled Vertical Bars is mode-independent as described below. `ionic-theme-disabled`, `ios-theme-disabled`, and the legacy `ios26-disabled` on an element or ancestor always exclude it. A disabled theme on one tab/segment item keeps its whole group on the Web.
+For the ordinary Native UI Shell, only iOS-mode components with the theme variables installed are eligible. Explicitly enabled Vertical Bars is mode-independent as described below. `ios-theme-disabled` and the legacy `ios26-disabled` on an element or ancestor always exclude it. A disabled theme on one tab/segment item keeps its whole group on the Web.
 
-Use `ios-theme-shell-disabled` to disable only the iOS Native UI Shell while keeping the Web theme. It excludes the element and all its descendants. Adding or removing the class at runtime automatically restores Web rendering or re-evaluates native eligibility.
+Use `data-shell="disabled"` (or the equivalent `ios-theme-shell-disabled` class) to disable only the iOS Native UI Shell while keeping the Web theme. It excludes the element and all its descendants. Adding or removing the attribute or class at runtime automatically restores Web rendering or re-evaluates native eligibility.
+
+Only the exact value `disabled` opts out; an empty or unknown value is ignored. Remove the attribute to re-enable projection. If the class is also present, remove both to re-enable projection. This does not disable clicks or change the Web theme. The data attribute is available in `1.2.0`.
 
 ```html
-<ion-toolbar class="ios-theme-shell-disabled">
+<ion-toolbar data-shell="disabled">
   <ion-button>Web glass button</ion-button>
 </ion-toolbar>
 ```
@@ -171,9 +173,9 @@ Suspensions are nestable and `resume()` is idempotent. Native projection resumes
 
 The native material and control appearance follow the running iOS version; an iOS 26 device does not acquire iOS 27's appearance merely by installing this theme.
 
-## Support iPhone Duo (experimental)
+## Support iPhone Duo (preview)
 
-iPhone Duo support is experimental, including standalone use without Native UI Shell. It is available in the `1.2.0-0` prerelease alongside Native UI Shell. Its APIs and supported behavior may change.
+iPhone Duo support, including standalone vertical bars without Native UI Shell, is available as a **preview** in `1.2.0` alongside Native UI Shell. Its APIs and supported behavior may change.
 
 The standalone Vertical Control Area entry point (`@rdlabo/ionic-theme-ios27/vertical-bars`) and `dist/css/vertical-bars.css` work without loading the iOS 27 theme. Call `enableVerticalControlArea()` for this use case; it projects only controls placed in the vertical area. Apps already calling `enableNativeUIShell()` should keep that single runtime rather than starting both. See [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo) for the complete setup, including hinge posture and the split-pane layout for apps that do not use this shell at all.
 
@@ -181,7 +183,7 @@ Vertical Bars uses a SwiftUI `TabView` and toolbar in the system rail. Ionic rem
 
 In Vertical Bars, fixed-toolbar `ion-button` actions need an `ion-icon` or SVG with `slot="icon-only"`. All fills and Ionic colors are eligible; submit buttons follow the same placement rule. Add `.ios-theme-horizontal-only` to a button or its `ion-buttons` group to keep it horizontal. See [Toolbar actions](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#toolbar-actions) for placement and exclusion rules.
 
-**Unreleased button appearance options:** the next release defaults native vertical buttons to `buttonProjection: 'system'`. Use `source` to project Ionic fill and colors, with `ios-theme-projection-source` / `ios-theme-projection-system` classes for local exceptions. These settings affect native vertical `ion-button` and `ion-menu-button` actions only. Horizontal controls and Web clones keep their existing behavior. See [Choose button appearance](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#choose-button-appearance) for migration, priority and fill rules.
+**Native button appearance:** `1.2.0` defaults native vertical buttons to `buttonProjection: 'system'`. Use `source` to project Ionic fill and colors, with `data-projection="source|system"` or the equivalent `ios-theme-projection-source` / `ios-theme-projection-system` classes for local exceptions. These settings affect native vertical `ion-button` and `ion-menu-button` actions only. Horizontal controls and Web clones keep their existing behavior. See [Choose button appearance](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#choose-button-appearance) for migration, priority and fill rules.
 
 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).
 

package/docs/special-markup.md

@@ -47,9 +47,9 @@ 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 (experimental)
+## Support iPhone Duo (preview)
 
-iPhone Duo support is experimental. It is available in the `1.2.0-0` prerelease alongside Native UI Shell. Its APIs and supported behavior may change.
+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 — 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.
 

package/docs/vertical-bars.md

@@ -1,14 +1,14 @@
 ---
-title: Vertical Bars (experimental)
+title: Vertical Bars (preview)
 ---
 
-# Vertical Bars (experimental)
+# Vertical Bars (preview)
 
 Vertical Bars moves eligible Ionic navigation and actions into a side rail while keeping the original components as the source of labels, icons and behavior. It works with this theme or an existing Ionic theme, independently of hinge posture and the full Native UI Shell.
 
 Use this page for layout, control eligibility, native button appearance and the runtime API. For device events and split panes, see [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo). For a step-by-step browser preview and native setup, start with [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme).
 
-Vertical Bars is experimental; APIs and supported behavior may change. The button appearance options below are unreleased.
+Available in `1.2.0` as a **preview** feature. APIs and supported behavior may change.
 
 ## Enable Vertical Bars
 
@@ -87,7 +87,7 @@ The rule applies to individual buttons and buttons inside `ion-buttons`, on ordi
 
 ### Choose button appearance
 
-**Unreleased:** `buttonProjection` and the local projection classes below are part of the next release. They are not available in the `1.2.0-1` package used by the introductory guide. The following rules describe this branch.
+`buttonProjection` and the local projection settings below are available in `1.2.0`.
 
 For native vertical `ion-button` and `ion-menu-button` actions, choose who controls appearance:
 
@@ -102,18 +102,23 @@ const rail = await enableVerticalControlArea({ buttonProjection: 'source' });
 
 Both `enableVerticalControlArea()` and `enableNativeUIShell()` accept the option. Use one runtime, and destroy it before restarting with different options. Either mode preserves actions, disabled state and grouping. These appearance settings do not affect horizontal controls, source elements or Web fallback clones, so compare the native appearance on supported iOS.
 
-**Migration:** the default changes from source styling to `system`. Set `buttonProjection: 'source'` to retain the previous projection behavior. This does not change the feature's experimental status.
+**Migration from the experimental releases:** the default changes from source styling to `system`. Set `buttonProjection: 'source'` to retain the previous projection behavior.
 
 ### Override individual buttons or groups
 
-Use `ios-theme-projection-source` or `ios-theme-projection-system` for local exceptions:
+Use `data-projection` for local exceptions. Existing classes remain supported:
+
+| Attribute | Equivalent class |
+| --- | --- |
+| `data-projection="source"` | `ios-theme-projection-source` |
+| `data-projection="system"` | `ios-theme-projection-system` |
 
 ```html
-<ion-buttons class="ios-theme-projection-source">
+<ion-buttons data-projection="source">
   <ion-button fill="solid" aria-label="Add">
     <ion-icon name="add-outline" slot="icon-only"></ion-icon>
   </ion-button>
-  <ion-button class="ios-theme-projection-system" aria-label="Search">
+  <ion-button data-projection="system" aria-label="Search">
     <ion-icon name="search-outline" slot="icon-only"></ion-icon>
   </ion-button>
 </ion-buttons>
@@ -121,11 +126,13 @@ Use `ios-theme-projection-source` or `ios-theme-projection-system` for local exc
 
 The first matching setting wins:
 
-1. The button's projection class.
-2. Its nearest `ion-buttons` projection class.
+1. The button's local setting.
+2. Its nearest `ion-buttons` local setting.
 3. The startup `buttonProjection` option, or `system` if omitted.
 
-If both classes are present on the same element, `system` wins. Removing the classes restores the inherited setting. Class changes apply without restarting the runtime; grouping and placement stay unchanged. Only native vertical `ion-button` and `ion-menu-button` actions interpret these classes. Other ancestors, back buttons, tabs and FABs do not.
+On the same element, a valid `data-projection` value takes precedence over the classes. Empty or unknown values are ignored. Without a valid attribute, `system` wins if both classes are present. Removing an attribute falls back to the element's classes, then the next level above. Attribute and class changes apply without restarting the runtime; grouping and placement stay unchanged.
+
+Only native vertical `ion-button` and `ion-menu-button` actions interpret these settings. Other ancestors, back buttons, tabs and FABs do not. They do not change Web styling. To keep a control or subtree on the Web entirely, use [`data-shell="disabled"`](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell#supported-markup).
 
 ### Source fill rules
 
@@ -146,7 +153,7 @@ const rail = await enableVerticalControlArea({ buttonDefaultFill: 'solid' });
 
 ```html
 <!-- In a fixed toolbar, outside ion-buttons: omitted fill resolves to solid. -->
-<ion-button class="ios-theme-projection-source" aria-label="Add">
+<ion-button data-projection="source" aria-label="Add">
   <ion-icon name="add-outline" slot="icon-only"></ion-icon>
 </ion-button>
 ```
@@ -158,7 +165,7 @@ const rail = await enableVerticalControlArea({ buttonDefaultFill: 'solid' });
 | `outline` | Computed border color and width, with native glass |
 | `null` | Native glass with source icon colors |
 
-Inside `ion-buttons`, explicitly set `fill="solid"` to project a background; `buttonDefaultFill: 'solid'` does not override the group's clear default. Native Liquid Glass tinting can differ from the CSS color, especially for translucent backgrounds. With the iOS theme, ordinary `ion-buttons` retain group projection; `ion-buttons.ios-theme-disabled` projects eligible buttons individually. Projection classes do not change that grouping rule.
+Inside `ion-buttons`, explicitly set `fill="solid"` to project a background; `buttonDefaultFill: 'solid'` does not override the group's clear default. Native Liquid Glass tinting can differ from the CSS color, especially for translucent backgrounds. With the iOS theme, ordinary `ion-buttons` retain group projection; `ion-buttons.ios-theme-disabled` projects eligible buttons individually. Local projection settings do not change that grouping rule.
 
 ## Tab bar
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rdlabo/ionic-theme-ios27",
   "private": false,
-  "version": "1.2.0-beta.pr243.shae972a0e49191",
+  "version": "1.2.0-beta.pr246.sha237333ceac21",
   "description": "iOS27 Theme for Ionic Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/native/definitions.ts

@@ -13,9 +13,10 @@ export interface NativeUIShellStatus {
 export interface VerticalControlAreaOptions {
   /** Appearance of native vertical ion-button and ion-menu-button actions.
    * `system` (default) uses SwiftUI styling and template icons; `source` projects supported Ionic fill and colors.
-   * Local ios-theme-projection-source / ios-theme-projection-system classes take precedence:
-   * the button itself, then its nearest ion-buttons, then this option. On the same element, system wins.
-   * Classes update live; removing them restores inheritance. Actions, disabled state and grouping are preserved.
+   * Local data-projection="source|system" or ios-theme-projection-source / ios-theme-projection-system take precedence:
+   * the button itself, then its nearest ion-buttons, then this option. On the same element, a valid attribute wins;
+   * otherwise system wins if both classes are present. Invalid attribute values are ignored.
+   * Local settings update live; removing them restores inheritance. Actions, disabled state and grouping are preserved.
    * Does not affect back buttons, tabs, FABs, horizontal controls, source elements or Web clones.
    */
   buttonProjection?: 'source' | 'system';

package/src/native/prehide.ts

@@ -74,6 +74,8 @@ export const prehideVerticalBarsToolbarSources = (doc: Document): { suspend: ()
     };
     const sources = scope.matches('ion-back-button') ? [scope] : Array.from(scope.querySelectorAll<HTMLElement>(sourceSelector));
     sources.forEach((element) => {
+      // Shell opt-out is temporary; decide initial placement once it is lifted.
+      if (isShellDisabled(element)) return;
       if (!modalUsesVerticalBars(element) || element.closest(overlays) || (scope.matches('.ion-page') && routedPage(element) !== scope))
         return;
       if (element.matches('ion-buttons')) {
@@ -228,7 +230,7 @@ export const prehideVerticalBarsToolbarSources = (doc: Document): { suspend: ()
     childList: true,
     attributes: true,
     attributeOldValue: true,
-    attributeFilter: ['class', 'hidden', 'inert', 'icon', 'color'],
+    attributeFilter: ['class', 'data-shell', 'hidden', 'inert', 'icon', 'color'],
   });
   return {
     suspend: () => {

package/src/native/shared/candidate.ts

@@ -65,13 +65,17 @@ export const appendItem = (
   const badgeStyle = badge && visible(badge) ? getComputedStyle(badge) : undefined;
   const sourceFill = (child as HTMLIonButtonElement).fill;
   const projectionOwner = [child, child.closest('ion-buttons')].find((element) =>
-    element?.matches('.ios-theme-projection-source, .ios-theme-projection-system'),
+    element?.matches('[data-projection="source"], [data-projection="system"], .ios-theme-projection-source, .ios-theme-projection-system'),
   );
-  const projection = projectionOwner
-    ? projectionOwner.classList.contains('ios-theme-projection-system')
-      ? 'system'
-      : 'source'
-    : candidate.buttonProjection;
+  const attributeProjection = projectionOwner?.getAttribute('data-projection');
+  const projection =
+    attributeProjection === 'source' || attributeProjection === 'system'
+      ? attributeProjection
+      : projectionOwner
+        ? projectionOwner.classList.contains('ios-theme-projection-system')
+          ? 'system'
+          : 'source'
+        : candidate.buttonProjection;
   const systemButton = projection !== 'source' && isVerticalBarsSource(child) && child.matches('ion-button, ion-menu-button');
   // Ionic defaults buttons inside ion-buttons to clear, even when the app defaults to solid.
   const defaultFill = child.closest('ion-buttons') ? 'clear' : candidate.buttonDefaultFill;

package/src/native/shared/dom.ts

@@ -52,7 +52,7 @@ export const isDark = (style: CSSStyleDeclaration): boolean => {
   const background = style.getPropertyValue('--ion-background-color-rgb').match(/\d+/g)?.slice(0, 3).map(Number);
   return !!background && background.length === 3 && background[0] * 0.2126 + background[1] * 0.7152 + background[2] * 0.0722 < 128;
 };
-const permanentlyExcluded = '.ionic-theme-disabled, .ios-theme-disabled, .ios26-disabled, .ion-cloned-element, [hidden], [inert]';
+const permanentlyExcluded = '.ios-theme-disabled, .ios26-disabled, .ion-cloned-element, [hidden], [inert]';
 export const excluded = `${permanentlyExcluded}, .ion-page-hidden, .ion-page-invisible`;
 const enteringPages = new WeakSet<HTMLElement>();
 export const setVerticalBarsEnteringPage = (page: HTMLElement, entering: boolean): void => {
@@ -88,8 +88,8 @@ export const createVerticalBarsPageState = () => {
     },
   };
 };
-const disabledButtonGroup = 'ion-buttons:is(.ionic-theme-disabled, .ios-theme-disabled, .ios26-disabled)';
-const shellDisabledSelector = '.ios-theme-shell-disabled';
+const disabledButtonGroup = 'ion-buttons:is(.ios-theme-disabled, .ios26-disabled)';
+const shellDisabledSelector = '.ios-theme-shell-disabled, [data-shell="disabled"]';
 
 export const isDisabledButtonGroupChild = (element: HTMLElement): boolean =>
   element.matches('ion-button') && element.parentElement?.matches(disabledButtonGroup) === true;
@@ -188,7 +188,7 @@ export const isVerticalBarsToolbarGroup = (element: HTMLElement): boolean => {
   return (
     element.matches('ion-buttons') &&
     verticalBarsOwned(element) &&
-    !element.matches('.ionic-theme-disabled, .ios-theme-disabled, .ios26-disabled') &&
+    !element.matches('.ios-theme-disabled, .ios26-disabled') &&
     !isShellDisabled(element)
   );
 };

package/src/styles/vertical-bars.scss

@@ -283,7 +283,8 @@ html.ios-theme-native-ui-shell-prehide
     [icon],
     [color],
     .ios-theme-vertical-bars-back-web-owned,
-    .ionic-theme-disabled,
+    .ios-theme-shell-disabled,
+    [data-shell='disabled'],
     .ios-theme-disabled,
     .ios26-disabled,
     .ios-theme-vertical-bars-back-button-projection
@@ -296,7 +297,7 @@ html.ios-theme-native-ui-shell-prehide
       ion-footer[collapse] *,
       ion-buttons.ios-theme-horizontal-only *,
       .ios-theme-shell-disabled *,
-      .ionic-theme-disabled *,
+      [data-shell='disabled'] *,
       .ios-theme-disabled *,
       .ios26-disabled *
     )