@rdlabo/capacitor-native-ui 0.0.0-stage → 1.2.1

package/docs/configuration.md

@@ -0,0 +1,187 @@
+# Configure Native UI
+
+Call `enableNativeUI()` once after your application's DOM is mounted. Ionic and explicitly marked HTML controls share the standard Swift renderers. The theme is optional; Web layout, safe areas and spacing belong to your app or theme.
+
+```ts
+import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
+
+const shell = await enableNativeUI();
+```
+
+Without Ionic, import the same API from `@rdlabo/capacitor-native-ui/core`. That entry does not load Ionic's optional popover integration. See [plain HTML](framework-independent.md).
+
+## Platform behavior
+
+| Feature | Supported iOS | Android | Browser / older iOS |
+| --- | --- | --- | --- |
+| Automatic Ionic controls (`ionic.auto`) | Native | Original Web controls | Original Web controls |
+| Explicit element buttons | Native | Original Web controls | Original Web controls |
+| Element extensions | SwiftUI | Kotlin / Compose | Original Web content |
+| Vertical Bars | Native when available; otherwise Web rail | Web rail | Web rail |
+| `tab-accessory` extensions | Supported iOS tab host only | Original Web content | Original Web content |
+
+Web rails require the Ionic rail layout or an application-owned HTML `webHost`. Settings never create a device capability. `verticalBars.only: true` excludes element extensions on every platform; leave it false when combining a Web rail with Android extensions.
+
+## All settings
+
+All nested objects merge with their defaults. For example, `ionic: { auto: { tabs: false } }` disables only tabs.
+
+```ts
+const shell = await enableNativeUI({
+  root: document.body,
+  debug: false,
+  ionic: {
+    auto: {
+      buttons: true,
+      tabs: true,
+      segment: true,
+      fab: true,
+    },
+  },
+  verticalBars: {
+    enabled: true,
+    only: false,
+    buttonProjection: 'system',
+    buttonDefaultFill: 'glass',
+    popover: false,
+    // Optional: placement: { edge: 'trailing', webHost: appOwnedHost },
+  },
+  horizontal: true,
+  vertical: true,
+  extensions: [],
+});
+```
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `ionic.auto` | `true` | `true` or omitted enables automatic Ionic projection; `false` disables it; an object selects kinds. Explicit `data-native-ui` sources and extensions are unaffected. |
+| `horizontal` / `vertical` | `true` | Automatic Ionic toolbar selection and grouping per layout: boolean or `{ buttons, button, backButton }`. Omitted fields are `true`; local attributes may override. See [toolbar settings](native-ui.md#toolbar-selection-and-grouping). |
+| `debug` | `false` | Log source elements and Web fallback reasons to the developer console; no props or application exception messages. |
+| `root` | `document.body` | Connected source subtree. Controls outside it are not projected. |
+| `ionic.auto.buttons` | `true` | Automatic Ionic toolbar/back/menu controls. Explicitly marked buttons are independent. |
+| `ionic.auto.tabs` | `true` | Ionic tabs and their registered native search. |
+| `ionic.auto.segment` | `true` | Supported Ionic segments. |
+| `ionic.auto.fab` | `true` | Supported Ionic floating action buttons. |
+| `verticalBars.enabled` | `true` | Allow rail projection when available. Device capability is always checked; enabling cannot create a system rail. |
+| `verticalBars.only` | `false` | Restrict native projection to rail controls. Other controls stay Web. |
+| `verticalBars.buttonProjection` | `'system'` | `'system'` uses native styling; `'source'` uses supported source styling. Local overrides take precedence. |
+| `verticalBars.buttonDefaultFill` | `'glass'` | `'glass'` or `'solid'` for source-style standalone Ionic buttons with no explicit fill. Explicit fills and the clear default inside `ion-buttons` take precedence. |
+| `verticalBars.popover` | `false` | Opt into Ionic popovers anchored to native rail buttons. Requires the Ionic entry and its optional peers; no effect on plain HTML. |
+| `verticalBars.placement` | omitted | Optional `{ edge: 'leading' \| 'trailing', webHost?: HTMLElement }`. Edge is a preference, not a device capability declaration. |
+| `extensions` | `[]` | **Experimental.** Application-specific SwiftUI / Compose extensions, paired with native registrations. API and behavior may change. |
+
+`webHost` is an optional, application-styled HTML fallback rail. It must be connected in the same document and outside `root`, with neither element containing the other. Use a limited `root`, such as your `<main>`, when supplying a sibling host; the default `document.body` cannot have such a host. Without a host, unavailable HTML rails leave their original controls visible. Ionic's existing rail layout uses its own fallback adapter.
+
+HTML currently supports buttons and back buttons. Tab, segment and FAB readers remain Ionic adapters; enabling those settings does not infer equivalent structures from arbitrary HTML.
+
+## Common configurations
+
+```ts
+// Ionic or HTML: all supported controls, rail support enabled by default.
+const shell = await enableNativeUI();
+
+// Alternative startup: Ionic with only Vertical Bars native presentation.
+const railOnly = await enableNativeUI({ verticalBars: { only: true } });
+
+// Alternative startup: automatically project only Ionic tabs; explicit sources remain independent.
+const tabsOnly = await enableNativeUI({
+  ionic: { auto: { buttons: false, segment: false, fab: false } },
+});
+```
+
+These are alternatives: start only one shell. Repeating the same startup returns its handle; different startup settings require destroying the previous shell.
+
+| Rail setting | Rail available | Rail unavailable |
+| --- | --- | --- |
+| `enabled: true, only: false` | Eligible rail and ordinary native controls | Ordinary native controls; unavailable rail controls retain Web fallback |
+| `enabled: true, only: true` | Eligible rail controls only | Web fallback |
+| `enabled: false, only: false` | Ordinary native controls; rail controls remain Web | Same |
+| `enabled: false, only: true` | All controls remain Web | Same |
+
+`data-native-ui-placement="element"` preserves a control's original position. It is never moved into a rail; with `only: true` it stays Web. For Ionic groups, put the placement on the whole `ion-buttons` group so its shared native surface has a single placement.
+
+## Select controls explicitly in a customized Ionic app
+
+Disable automatic Ionic projection while retaining the native rail and your custom extensions:
+
+```ts
+const shell = await enableNativeUI({
+  root: document.querySelector<HTMLElement>('#content')!,
+  ionic: { auto: false },
+  verticalBars: { enabled: true, placement: {
+    edge: 'trailing',
+    webHost: document.querySelector<HTMLElement>('#rail')!,
+  } },
+  extensions: [myExtension],
+});
+```
+
+```html
+<main id="content">
+  <ion-button>Keep this on the Web</ion-button>
+  <ion-button data-native-ui="button" data-native-ui-placement="rail">Project this action</ion-button>
+  <button data-native-ui="button">Project at its original position</button>
+</main>
+<aside id="rail" aria-label="Actions"></aside>
+```
+
+Keep your original handlers on each source. Explicit `ion-button` uses the standard button reader, so supported content and styling rules still apply; the attribute does not make arbitrary custom markup supported. `data-native-ui-placement="rail"` requests the system rail when available. Style the optional `webHost` and reserve space in your app; without it, unavailable explicit rails keep their source controls visible. Unmarked Ionic controls remain Web-rendered. An automatically projected group containing an explicitly marked source stays on the Web to avoid covering that source twice.
+
+Explicit built-in sources support individual `button`, `ion-button`, and `[role="button"]` elements with `data-native-ui="button"` or `"back-button"`. This does not opt existing `ion-back-button`, `ion-menu-button`, button groups, tabs, segments, or FABs into their Ionic-specific readers. Keep automatic projection enabled for the corresponding kind, use a standard explicit button with your own click handler, or register an extension for custom UI.
+
+`verticalBars.enabled` and `only` still govern rail availability and projection scope. For example, `only: true` leaves explicitly marked element-position buttons and ordinary element extensions on the Web too.
+
+## Change rail use after startup
+
+```ts
+await shell.disableVerticalControlArea();
+await shell.enableVerticalControlArea();
+```
+
+These methods change `verticalBars.enabled` on this shell and preserve `only`, appearance, controls and placement. They retire existing projection before transferring ownership, without creating another shell. Calls are serialized. Calling either method after `destroy()` rejects.
+
+```ts
+const lease = await shell.suspend(); // temporarily restore all Web controls
+await lease.resume();
+await shell.destroy();              // stop the shell and restore sources
+```
+
+Disabling rail projection does not remove application CSS or change application-owned spacing. Update your own layout alongside this setting if needed.
+
+## Request a check after an unobserved change
+
+```ts
+shell.markForCheck();
+```
+
+Use this after changing a property or reader state that does not cause a DOM mutation. It schedules a check, batches repeated requests, and sends only changed native snapshots. It returns `void`; it does not wait for native completion or render your framework's DOM. Calls after destruction are ignored. See [source checks and observation](native-ui-extensions.md#schedule-a-source-check).
+
+## Understand why a source stays on the Web
+
+Temporarily add `debug: true` to your existing startup options, then rebuild the Web app. Do not start a second shell to enable diagnostics:
+
+```ts
+const shell = await enableNativeUI({ debug: true, extensions: [myExtension] });
+console.info(shell.getStatus());
+```
+
+Open the WebView developer console and filter for `[Native UI]`. Diagnostics include the DOM source when available. Each reason is logged once per source during that activation, so scrolling or repeated `markForCheck()` calls do not flood the console. Props, action payloads and application exception messages are not logged.
+
+| Diagnostic | What to check |
+| --- | --- |
+| `web-fallback` | Platform support, native plugin registration, sync and native rebuild. |
+| `unregistered-extension` | Native registration name matches the DOM definition and runs before startup. Newly inserted sources are checked too. |
+| `reader-error` / `invalid-props` | Reader implementation, JSON-only values and the 64K size limit. |
+| `unsupported-placement` / `missing-tab-owner` | Platform and owning native tab host for a tab accessory. |
+| `source-hidden` / `source-clipped` / `source-focused` | Visibility, clipping/transformed ancestors, or a focused Web descendant. |
+| `reader-opt-out` / `rail-only` | Your reader returned null, or `verticalBars.only` excludes an element extension. |
+| `unsupported-control` | Supported markup, accessible name, fixed placement and styling. |
+| `native-rejected` | Native props decoding, placement or device support. The bridge reports rejection, not the native exception. |
+
+`getStatus()` summarizes the shell; it is not a per-element diagnostic report. Normal navigation, suspension and unsupported content can intentionally retain Web presentation. Turn debug off after investigating; it does not change projection eligibility.
+
+## Compatibility
+
+`controls` is deprecated. If `ionic.auto` is omitted, existing `controls` settings retain their previous behavior, including `buttons: false` disabling explicitly marked buttons. When `ionic.auto` is supplied, it takes precedence for automatic controls and explicit sources are independent. Move `controls.popover` to `verticalBars.popover`. Partial objects retain enabled defaults for omitted kinds; use `false` to disable all automatic kinds.
+
+The existing global `enableVerticalControlArea()` remains a startup wrapper for Ionic rail-only usage, while `setVerticalControlAreaPlacement()` is a deprecated Web CSS compatibility adapter. Its `nativeEdge` input is ignored; native availability is obtained from the plugin’s own device metrics. Use the theme’s `setVerticalBarsLayout({ edge, inset })` for Web layout. New code should use the shared startup and handle methods above. See [migration](migration.md) for legacy settings and the changed partial-control defaults.

package/docs/framework-independent.md

@@ -0,0 +1,82 @@
+# Native UI without Ionic
+
+> This guide targets the upcoming package split. Until the first native package release, use the [candidate archive installation](../README.md#try-the-unreleased-packages) in place of registry install commands.
+
+Add native buttons to an existing Web app without Ionic or theme CSS. Keep labels, state, and click handlers on ordinary HTML elements. Standard buttons require no custom Swift registration.
+
+Use a Capacitor 8 app with an iOS project, Xcode 26+, and an iOS 26+ device or simulator. Browsers and Android retain Web controls. For custom Android native content, use [Kotlin/Compose extensions](native-ui-extensions.md#2b-register-compose-content-on-android).
+
+## 1. Install the plugin
+
+Keep your existing Capacitor 8 installation and add the plugin directly:
+
+```sh
+npm install @rdlabo/capacitor-native-ui
+```
+
+The `/core` entry requires `@capacitor/core` but no Ionic dependencies. If this is currently a browser-only application, configure its Capacitor 8 iOS project before running native controls.
+
+## 2. Mark source controls
+
+```html
+<main id="app">
+  <button type="button" data-native-ui="button" data-native-ui-placement="element">Add</button>
+  <button type="button" data-native-ui="back-button" data-native-ui-placement="rail">Back</button>
+</main>
+<aside id="rail" aria-label="Navigation"></aside>
+```
+
+- `data-native-ui="button"` opts into a standard action button.
+- `data-native-ui="back-button"` opts into a standard back button. Its original click handler owns navigation; the plugin never calls `history.back()`.
+- `data-native-ui-placement="rail"` requests Vertical Bars. Without it, the source rectangle is used. `element` explicitly preserves that rectangle.
+- Sources must be `<button>`, explicitly marked `ion-button`, or custom elements exposing `role="button"` and click behavior. Unmarked HTML is never inferred to be a control.
+
+Keep the accessible name, supported static SVG, disabled state and application handlers on the source. Names resolve from `aria-labelledby`, `aria-label`, then text. Native `disabled`, a disabled fieldset and `aria-disabled="true"` are respected. Hidden, removed, excluded or out-of-scope sources are retired and stale actions are rejected. Use `data-native-ui="disabled"` to exclude a subtree.
+
+Native and Web-proxy actions click the original element. An ordinary `<button type="submit">` therefore keeps its original form behavior. Use `type="button"` for actions that must not submit. The native bridge does not preserve browser user-activation privileges for APIs such as popup opening.
+
+## 3. Start after mounting the controls
+
+```ts
+import { enableNativeUI } from '@rdlabo/capacitor-native-ui/core';
+
+const shell = await enableNativeUI({
+  root: document.querySelector<HTMLElement>('#app')!,
+});
+```
+
+Call once after the source root exists. Keep the handle and call `await shell.destroy()` when that root is disposed. The plugin does not add page padding or safe-area rules; retain your application's CSS. For Angular, React, or Vue, use the [app-root lifecycle examples](setup.md#place-startup-in-your-frameworks-app-root) with the `/core` import. For animated navigation, use [suspension through completion and cancellation](setup.md#navigation-without-the-theme).
+
+## 4. Build and run on iOS
+
+Build your Web app, run `npx cap sync ios`, and launch the iOS project from Xcode. The marked Add button should render natively and invoke its original click handler. In a browser, the same button remains an ordinary Web button. Unmarked HTML remains unchanged.
+
+If a button stays on the Web on supported iOS, check that it is visible within the configured root, has an accessible name, and that the direct plugin dependency was synced and the iOS app rebuilt.
+
+In an app that also uses Ionic, set `ionic: { auto: false }` to project only explicit sources and registered extensions. See [selective Ionic projection](configuration.md#select-controls-explicitly-in-a-customized-ionic-app).
+
+## Optional Web rail
+
+Replace the startup call in step 3 with the following configuration; do not start a second shell:
+
+```ts
+const shell = await enableNativeUI({
+  root: document.querySelector<HTMLElement>('#app')!,
+  verticalBars: {
+    placement: {
+      edge: 'trailing',
+      webHost: document.querySelector<HTMLElement>('#rail')!,
+    },
+  },
+});
+```
+
+The plugin uses device-reported rail availability and resolves leading/trailing through the document direction. A placement preference never forces an unsupported system rail. Native rejection restores Web presentation. With `webHost`, explicitly rail-marked HTML controls have Web proxies when native projection is unavailable. Without it, their originals remain visible. The application styles and positions the host and reserves any content spacing. The host must be outside the source root.
+
+To use only rail projection, add `verticalBars.only: true`. To change rail use later, call `await shell.disableVerticalControlArea()` or `await shell.enableVerticalControlArea()`. Disabling restores original controls and removes Web rail proxies without destroying ordinary native projection. `only: true` keeps ordinary controls on the Web throughout.
+
+Currently the HTML adapter supports buttons and back buttons. Arbitrary HTML tabs, segments, searchbars and FAB structures are not translated. Ionic adapters continue to support their existing controls. Custom element extensions work with the same scoped root; the existing `tab-accessory` extension placement still requires an Ionic tab-bar owner.
+
+## Example
+
+The [plain HTML example](https://github.com/rdlabo-dev/ionic-theme-ios27/tree/main/examples/native-ui-html) demonstrates Add, routerless Home/Details/Back navigation, optional Web rail projection and cleanup. It uses no Ionic or theme CSS.

package/docs/migration.md

@@ -0,0 +1,206 @@
+---
+title: Migration
+---
+
+# Migration
+
+> This guide targets the upcoming package split. Until the first native package release, use the [candidate archive installation](../README.md#try-the-unreleased-packages) in place of registry install commands.
+
+## Migrating from Native UI Shell Preview
+
+Native UI Shell was already published as **Preview** in `@rdlabo/ionic-theme-ios27` 1.2.0 and 1.2.1. Preview users need the migration below when adopting the split packages; changing the import alone is not sufficient for every configuration. Candidate/beta users should also compare their configuration with these mappings and use JavaScript and native code from the same candidate.
+
+1. Install the matching packages and replace removed imports using [package separation](#native-ui-package-separation).
+2. Apply the [API and native naming changes](#native-ui-naming-changes), then translate startup settings using [shared shell configuration](#shared-shell-configuration-and-html-adapters), especially partial `controls` objects.
+3. Update [Web layout ownership](#web-layout-ownership) and the [transition adapter](#native-ui-transition-adapter) if used.
+4. Rebuild Web assets, sync Capacitor, and rebuild the native app. A Web-only update cannot replace the native plugin.
+
+Native UI remains Preview. App-local SwiftUI / Compose **extensions are experimental**, including their TypeScript definitions, native registration APIs and placement behavior. The `defineNativeUI` and `extensions` names stay unchanged; native registration names change as listed below. Applications using extensions should keep their Web fallback and verify their reader, native renderer and action forwarding together after updates. See the [extension guide](native-ui-extensions.md).
+
+## Native UI package separation
+
+For a new native integration, follow [Native UI setup](setup.md) or, if you already use the iOS theme, [Add Native UI to your theme](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/add-native-ui.md). The steps below cover existing applications migrating package names and native projects.
+
+The theme and native controls now live in separate packages. Choose dependencies by the behavior your app uses:
+
+| App behavior | Package to use directly |
+| --- | --- |
+| Theme styles, Ionic Web behavior, and theme animations | `@rdlabo/ionic-theme-ios27` |
+| Native UI or standalone Vertical Control Area | `@rdlabo/capacitor-native-ui` |
+| Theme styling together with native controls | Both packages |
+
+The theme owns the appearance and behavior of Ionic's Web elements. Native UI owns projecting supported controls into native iOS views and coordinating their lifecycle with Web navigation. Native UI can be used without the iOS 27 theme; installing it does not apply theme styles. Standard controls on Android and browsers retain Web presentation; Android can render [app-local Compose extensions](native-ui-extensions.md#2b-register-compose-content-on-android).
+
+The theme uses the native package's shared transition/search integration internally. This dependency does not enable native controls automatically. Apps using native controls must declare the native package directly so Capacitor can discover the plugin.
+
+### 1. Update application dependencies
+
+These commands apply once the packages containing this migration are published.
+
+For theme-only apps, update the theme package. Keep existing theme imports and CSS/Sass paths; no native startup or plugin setup is needed for theme-only use.
+
+```sh
+npm install @rdlabo/ionic-theme-ios27
+```
+
+For apps using both the theme and native controls, install both as direct application dependencies:
+
+```sh
+npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui
+```
+
+For native controls with your existing Web appearance, follow [Native UI only](setup.md). Install the native package directly and keep your existing Web styles. The plugin no longer requires theme variables to select supported controls; Web layout remains the responsibility of your app or theme. Native startup requires Capacitor 8. The Ionic adapter requires Ionic 8.8.1 or later within Ionic 8 or 9; the `/core` entry does not require Ionic.
+
+If you used the intermediate `@ionic-theme/capacitor-native-ui` package name during development, remove it and install `@rdlabo/capacitor-native-ui`. Keep the theme dependency if your app uses its styles or APIs.
+
+```sh
+npm uninstall @ionic-theme/capacitor-native-ui
+npm install @rdlabo/capacitor-native-ui
+```
+
+### 2. Replace native imports
+
+| Previous import | Replacement |
+| --- | --- |
+| `@rdlabo/ionic-theme-ios27/native` | `@rdlabo/capacitor-native-ui` |
+| `@rdlabo/ionic-theme-ios27/vertical-bars` | `@rdlabo/capacitor-native-ui/vertical-bars` |
+| `@ionic-theme/capacitor-native-ui` | `@rdlabo/capacitor-native-ui` |
+| `@ionic-theme/capacitor-native-ui/vertical-bars` | `@rdlabo/capacitor-native-ui/vertical-bars` |
+| `@ionic-theme/capacitor-native-ui/integration` | `@rdlabo/capacitor-native-ui/integration` |
+
+Update both value and type imports, including lazy imports, test aliases, and bundler configuration. The old theme `/native` and `/vertical-bars` entries have been removed; there are no compatibility aliases.
+
+```diff
+- import { enableNativeUIShell } from '@rdlabo/ionic-theme-ios27/native';
++ import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
+```
+
+Keep existing control markup; review the [startup option changes](#shared-shell-configuration-and-html-adapters), including partial `controls` defaults. The ordinary `@rdlabo/ionic-theme-ios27` entry, theme CSS/Sass paths, and theme animation imports stay unchanged. For custom navigation animations, see the [transition adapter instructions](#native-ui-transition-adapter) below.
+
+### 3. Sync the native project
+
+After updating dependencies and imports, rebuild your app's Web assets with its usual build command, then run:
+
+```sh
+npx cap sync ios
+```
+
+The Capacitor plugin is now supplied by the native package. Remove manually linked copies of the old theme Swift package so only the new package supplies the plugin. The Swift package/product and CocoaPods pod are now `RdlaboCapacitorNativeUi`; the Swift module is `NativeUIPlugin`. The Capacitor bridge name is now `NativeUI` on JavaScript, iOS and Android. Run Capacitor sync for each native platform you use and rebuild the native app. An OTA/Web-only update cannot migrate an installed binary containing only the old plugin. Use matching JavaScript and native package versions.
+
+For local Swift package references, the package now lives at `packages/capacitor-native-ui` within this repository; there is no root Swift package. Prefer Capacitor's generated integration for application dependencies.
+
+### 4. Verify the migration
+
+- Check `package.json` and the lockfile: native-enabled apps have a direct `@rdlabo/capacitor-native-ui` dependency and no intermediate `@ionic-theme/capacitor-native-ui` dependency.
+- Build the application and confirm there are no imports of the removed theme entries or the intermediate package name.
+- Build and launch the iOS app after sync. Check native controls, navigation/back gestures, and any app-local Swift extensions you use.
+- Check browser and Android Web presentation where supported by your app, and confirm the theme still looks correct.
+- Check that previously disabled control kinds remain disabled after expanding partial Preview settings. Test toolbar grouping, individually selected actions and back navigation in both horizontal and vertical layouts.
+- For experimental extensions, check native registration, props, click forwarding and restoration of the original Web UI when projection is unavailable. Rebuild and sync Android as well if the app uses Compose extensions.
+
+## Native UI naming changes
+
+The split package uses Native UI names throughout. These are breaking renames; the old names are not aliases. The historical names below refer to the published theme Preview or pre-release package candidates.
+
+| Previous name | New name |
+| --- | --- |
+| `enableNativeUIShell()` | `enableNativeUI()` |
+| `NativeUIShellOptions`, `NativeUIShellHandle`, `NativeUIShellStatus`, `NativeUIShellSuspension`, `NativeUIShellControls`, `NativeUIShellComponent` | `NativeUIOptions`, `NativeUIHandle`, `NativeUIStatus`, `NativeUISuspension`, `NativeUIControls`, `NativeUIComponent` |
+| `IonicNativeUIShell` (plugin export and bridge registration) | `NativeUI` |
+| `withNativeUIShellTransition()` | `withNativeUITransition()` (still exported by the theme package) |
+| `IonicNativeUIShellPlugin` (Swift module/native class) | `NativeUIPlugin` |
+| `IonicThemeCapacitorNativeUi` (SPM package/product and pod) | `RdlaboCapacitorNativeUi` |
+| `NativeUIShell.register()` (Swift / Kotlin extensions) | `NativeUI.register()` |
+| `data-shell="disabled"` | `data-native-ui="disabled"` |
+| `.ios-theme-shell-disabled` | `.native-ui-disabled` |
+
+Replace the `NativeUIShell` part with `NativeUI` in imports from `/integration` as well (for example `suspendNativeUI` and `setNativeUIIntegration`). App-local Swift extensions now use `import NativeUIPlugin`; Kotlin extensions use `import dev.rdlabo.capacitor.nativeui.NativeUI`.
+
+Runtime-owned attributes/events are internal, not configuration: `data-native-ui-shell` is now `data-native-ui-projected`, other `data-native-ui-shell-*` attributes use `data-native-ui-*`, `nativeUIShell*` events use `nativeUI*`, and `.ios-theme-native-ui-shell-*` classes use `.native-ui-*`. Update application tests or diagnostics that inspect them. **Keep explicit source declarations such as `data-native-ui="button"` unchanged**; the projected marker is separate and is managed by the runtime.
+
+## Native UI transition adapter
+
+The Ionic transition adapter now belongs to `@rdlabo/ionic-theme-ios27`. Replace preview imports from the plugin’s `/integration` or `/vertical-bars` entry with the theme root. Native-only applications can use `shell.suspend()` and the returned `resume()` directly.
+
+Use `withNativeUITransition()` to keep your existing Ionic navigation animation while coordinating Native UI controls.
+
+- If you already import `iosTransitionAnimation` from `@rdlabo/ionic-theme-ios27`, keep the [package animation setup](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo-with-original-theme.md#use-this-packages-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](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo-with-original-theme.md#keep-ionics-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 or the standalone Vertical Control Area, wrap your existing builder when configuring Ionic:
+
+```diff
++ import { withNativeUITransition } from '@rdlabo/ionic-theme-ios27';
+
+  const ionicConfig = {
+-   navAnimation: existingTransition,
++   navAnimation: withNativeUITransition(existingTransition),
+  };
+```
+
+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 or Vertical Control Area startup.
+
+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.
+
+See [Connect your navigation animation](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo-with-original-theme.md#3-connect-your-navigation-animation) for the setup and supported scope.
+
+## Shared shell configuration and HTML adapters
+
+Run `npx cap sync ios` after updating: JavaScript now sends framework-independent control kinds to Swift. New Swift code also accepts the previous `ion-*` kinds, but new JavaScript requires the matching native plugin.
+
+- `controls.toolbar` becomes `ionic.auto.buttons`.
+- `controls.popover` becomes `verticalBars.popover`.
+- Top-level `buttonProjection` and `buttonDefaultFill` move into `verticalBars`.
+- The new `verticalBars.buttonDefaultFill` uses `'glass'` instead of `null`.
+- `verticalBarsOnly: true` becomes `verticalBars: { only: true }`.
+- Omitted automatic kinds now default to `true`, including partial legacy `controls` objects. Published 1.2.x enabled only fields explicitly set to `true` when `controls` was supplied. Expand partial objects when migrating, even if you keep the legacy option name.
+- The global `enableVerticalControlArea()` remains a legacy startup wrapper. New code starts with `enableNativeUI({ verticalBars: { only: true } })`, then uses the returned handle's `enableVerticalControlArea()` / `disableVerticalControlArea()` methods.
+- Legacy option names and global `enabled: false` remain accepted; use `shell.destroy()` to stop new code. If both old and new settings are supplied, the new nested settings take precedence.
+
+For example, preserve a Preview configuration that projected only tabs:
+
+```diff
+- import { enableNativeUIShell } from '@rdlabo/ionic-theme-ios27/native';
++ import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
+
+- const shell = await enableNativeUIShell({
++ const shell = await enableNativeUI({
+-   controls: { tabs: true },
+-   buttonProjection: 'source',
+-   buttonDefaultFill: null,
++   ionic: { auto: { tabs: true, buttons: false, segment: false, fab: false } },
++   verticalBars: { buttonProjection: 'source', buttonDefaultFill: 'glass' },
+  });
+```
+
+Likewise, replace `controls: {}` with `ionic: { auto: false }` to keep automatic Ionic projection off. Explicit `data-native-ui` sources and extensions remain independent. Calling `enableNativeUI()` with no options still enables all supported automatic kinds.
+
+### Toolbar selection and grouping by layout
+
+`horizontal` and `vertical` are new toolbar settings. Omit them to retain automatic selection and grouping, or configure each layout independently:
+
+```ts
+const shell = await enableNativeUI({
+  horizontal: false,
+  vertical: { buttons: false, button: false, backButton: true },
+});
+```
+
+This selects only eligible back buttons among vertical toolbar actions and disables automatic horizontal toolbar selection. Tabs, segments and FABs retain their own settings. To enable all eligible toolbar actions only in vertical layout, use `{ horizontal: false, vertical: true }`; this follows layout, not the Duo model.
+
+Do not translate `controls.toolbar` or `ionic.auto.buttons` into `vertical.buttons`: those options govern the entire automatic toolbar category, while `horizontal.buttons` / `vertical.buttons` govern **grouping only**. Within each layout, `button` selects ordinary actions and `backButton` selects back navigation independently. All three fields default to `true`; a layout value of `false` sets all three to `false`.
+
+If you used the short-lived development settings at the top level, move `{ buttons, button, backButton }` into `vertical: { buttons, button, backButton }`. Those fields were not part of the published 1.2.0/1.2.1 API and are not compatibility aliases. Existing `buttonProjection` / `buttonDefaultFill` are separate appearance settings, mapped above.
+
+Local `data-horizontal-bars="true|false"` / `data-vertical-bars="true|false"` can override these layout defaults. On `ion-buttons` they affect grouping only and never select children. A back button ignores its group's grouping setting. `ionic.auto` and structural exclusions still apply. See [toolbar selection and grouping](native-ui.md#toolbar-selection-and-grouping) for eligibility and when changes take effect.
+
+See [all settings and defaults](configuration.md) and [plain HTML setup](framework-independent.md). Standard HTML buttons use the same Swift controls as Ionic; they do not require an application-specific Swift extension.
+
+## Web layout ownership
+
+Import `setVerticalBarsLayout` and `applyFoldStateClasses` from `@rdlabo/ionic-theme-ios27` for theme CSS. Replace `setVerticalControlAreaPlacement({ edge, nativeEdge, inset })` with `setVerticalBarsLayout({ edge, inset })`. Native UI now reads availability from its own device metrics; `nativeEdge` is ignored by the deprecated compatibility helper. Normal startup, disabled rails and teardown do not remove theme classes or alter reserved Web spacing. An unavailable native rail keeps the application’s Web rail layout; applications wanting a horizontal layout must select it themselves. Native-only applications can continue to use their own layout CSS.
+
+## Automatic Ionic controls
+
+Use `ionic.auto` for new configuration. It accepts `true` (default), `false`, or `{ buttons, tabs, segment, fab }`. Unlike legacy `controls`, it affects only automatic Ionic projection; explicit `data-native-ui` sources and registered extensions remain enabled. `verticalBars` independently controls rail projection. See [selective projection](configuration.md#select-controls-explicitly-in-a-customized-ionic-app) for an existing Ionic app that opts in individual buttons.
+
+The legacy `controls` option is marked `@deprecated` and remains available. When `ionic.auto` is omitted, legacy kind settings are used, but omitted kinds now default to `true`; expand partial Preview configurations as shown above. If both are supplied, `ionic.auto` takes precedence for automatic kinds. Move the legacy `popover` option to `verticalBars.popover`.

package/docs/native-mini-player.md

@@ -0,0 +1,47 @@
+---
+title: Native UI Extension: Now Playing
+---
+
+# Native UI Extension: Now Playing
+
+This example uses the experimental extension API, which may change in future releases.
+
+Use the [app-local extension API](native-ui-extensions.md) to add a SwiftUI mini-player with a Web fallback. The demo's Index → Native UI Extension page provides a sample you can copy into your application.
+
+- [Web component](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/src/app/mini-player/mini-player.component.ts): owns playback state and the Now Playing modal. Play/pause is separate from opening the player. Tap or swipe up on the track opens the same modal.
+- [Web renderer + DOM reader](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/src/native-ui/mini-player.ts): renders the Web UI from attributes, sends title, artist and playback state to SwiftUI, and maps `open` / `toggle` to the original Web buttons.
+- [SwiftUI View](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/ios/App/App/NativeMiniPlayer.swift): uses `Button`, SF Symbols, `DragGesture`, and a capsule glass background. It awaits `NativeUIActions.activate()` rather than duplicating playback state or presenting its own modal.
+
+The SwiftUI sample uses `NativeUIContext.sourceFrame.width` for compact spacing and `actions.isAvailable(...)` to disable actions whose Web targets are unavailable. See [projection context](native-ui-extensions.md#read-source-geometry-and-presentation-state) for coordinate units and system placement.
+
+Register the View once in the app delegate and pass `miniPlayer` in `enableNativeUI({ extensions: [miniPlayer] })`. Copy these app-local files to adapt the sample to your own playback state and artwork. The original sunset artwork is drawn with SwiftUI shapes, with a matching local SVG for the Web. The compact player shows only artwork, track metadata and playback; elapsed time stays in Now Playing.
+
+The sample uses the default **element projection**: SwiftUI follows the Web element’s position and size on iOS 26+, with ordinary tabs or Vertical Bars. Browsers and unsupported environments retain the Web player. Use the **Native extension** toggle to switch native projection on or off. The player starts in Web mode; disabling the extension restores its Web UI. It is shown only on this demo page; leaving the page hides it without resetting playback state.
+
+The Web fallback reserves its own bottom-slot space and keeps play state across tab changes. Opening Now Playing retires the native player through the shell's existing overlay policy; dismissing it restores the current Web state.
+
+This is a UI example: elapsed time is fixed and no audio engine is started. Applications own playback and reflect current values into the Web DOM. Connect your application's audio engine to the sample's playback events before using it as a player.
+
+## Use the Web + SwiftUI set in your application
+
+The local TypeScript file includes both a renderer for an ordinary DOM element and its native reader. Copy it together with `NativeMiniPlayer.swift`; in your app, replace the demo’s relative `defineNativeUI` import with `@rdlabo/capacitor-native-ui`. The Web renderer works without Angular, Capacitor or an enabled Native UI; SwiftUI replaces it only after native accepts the projection.
+
+```ts
+import { miniPlayer, mountNowPlaying } from './native-ui/mini-player';
+import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
+
+const player = document.querySelector<HTMLElement>('[data-mini-player]')!;
+const destroyWeb = mountNowPlaying(player); // Run on every platform, including the Web.
+player.addEventListener('togglePlayback', () => {
+  player.setAttribute('data-playing', String(player.getAttribute('data-playing') !== 'true'));
+});
+player.addEventListener('openNowPlaying', () => openNowPlaying());
+await enableNativeUI({ extensions: [miniPlayer] });
+// Call destroyWeb() when the application's source element is destroyed.
+```
+
+```html
+<section data-mini-player data-title="Midnight Drive" data-artist="The Coast" data-playing="true"></section>
+```
+
+The sample does not specify `placement`; the default is `'element'`. Applications can opt into `placement: 'tab-accessory'` when they want a system tab accessory; see the [placement options and host requirements](native-ui-extensions.md#content-and-placement-are-independent). Its surrounding Web layout belongs to the application. The same attributes feed the Web view and SwiftUI; both dispatch the same events. The application updates attributes after its playback state changes. Mount into an empty element. The Web renderer owns only its generated children and releases its observer and handlers on teardown. Frameworks own the host's attributes, not those children. Text is rendered as text, never interpreted as HTML.