@rdlabo/capacitor-native-ui 1.2.1 → 2.0.0-2

package/docs/native-ui-extensions.md

@@ -6,16 +6,16 @@ title: App-local Native UI extensions (experimental)
 
 > **Experimental:** The extension API, native registration interfaces and behavior may change in future releases. This applies to both SwiftUI and Kotlin/Compose extensions, including `element` and `tab-accessory` placement.
 
-> 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.
-
 An extension projects your existing Web UI into a SwiftUI View on iOS or Jetpack Compose content on Android. Keep both definitions in your application: no npm package, separate library, or Capacitor plugin is required. The Web element remains the source of truth and the fallback UI.
 
+Extensions use the same [projection model](../README.md#how-projection-works) as built-in controls. Define the DOM data and actions to expose, then provide their native presentation.
+
 ## Before you start
 
 Start with an existing Capacitor 8 app and install the plugin if you have not already:
 
 ```sh
-npm install @rdlabo/capacitor-native-ui
+npm install @rdlabo/capacitor-native-ui @erkamyaman/capacitor-foldable
 ```
 
 Choose the native platform you want to support:
@@ -63,9 +63,18 @@ source.querySelector('button')!.addEventListener('click', () => {
   source.querySelector('[data-count-label]')!.textContent = `Count: ${count}`;
 });
 ```
- The shell observes DOM changes and sends the new props to the native content. State rendered into DOM attributes or text is observed automatically. For properties or external state read by the reader that do not mutate the DOM, call `shell.markForCheck()` after changing them.
 
-The reader is synchronous and read-only. Return `null` when the source should stay on the Web. Props are a JSON object (finite numbers, strings, booleans, null, arrays and objects), limited to 64K characters. Action names map to the source itself or its descendants; missing, hidden and disabled targets cannot be activated. Up to 30 actions are supported per source.
+The shell observes DOM changes and sends the new props to the native content. State rendered into DOM attributes or text is observed automatically. For properties or external state read by the reader that do not mutate the DOM, call `shell.markForCheck()` after changing them.
+
+### Reader contract
+
+| Part           | Requirement                                                                                                    |
+| -------------- | -------------------------------------------------------------------------------------------------------------- |
+| Execution      | Synchronous and read-only.                                                                                     |
+| Web fallback   | Return `null` when the source should stay on the Web.                                                          |
+| `props`        | JSON object containing finite numbers, strings, booleans, null, arrays and objects; limited to 64K characters. |
+| Action targets | The source itself or its descendants. Missing, hidden and disabled targets cannot be activated.                |
+| Action count   | Up to 30 per source.                                                                                           |
 
 ## 2a. Register a SwiftUI View on iOS
 
@@ -221,14 +230,23 @@ For source-specific fallback reasons, temporarily enable [`debug: true`](configu
 
 ## Content and placement are independent
 
-| `placement` | Behavior |
-| --- | --- |
+| `placement`            | Behavior                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------- |
 | Omitted or `'element'` | Hosts native content in the source element's Web frame on iOS 26+ or Android API 24+. |
-| `'tab-accessory'` | Attaches the View to a projected tab bar's system SwiftUI tab accessory on iOS 26.1+. |
+| `'tab-accessory'`      | Attaches the View to a projected tab bar's system SwiftUI tab accessory on iOS 26.1+. |
+
+Extensions are independent of `controls` and `ionic.auto`, including with `enableVerticalControlArea()`. The application controls their presentation: return `null` from the reader when a source should stay on the Web, then call `markForCheck()` when that condition changes. Accessories still require their supported native tab host.
 
-For `tab-accessory`, place the source inside its owning `ion-tabs`. The shell resolves that tabs element's `ion-tab-bar`; applications do not pass native controller references. Currently only the **Vertical Bars SwiftUI tab host** supports this placement. Ordinary UIKit tab bars, missing native tabs, iOS 26.0, or multiple competing accessories keep the source on the Web. The shell does not approximate a system accessory with a floating overlay. Keep an equivalent Web layout (for example, a fixed footer); the source retains its layout space while hidden.
+### Tab accessory requirements
 
-`enableVerticalControlArea({ extensions: [...] })` also accepts extensions. In this standalone mode only accessories belonging to native Vertical Bars are eligible; ordinary element projections require `enableNativeUI`.
+| Requirement         | Supported configuration                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------- |
+| Source location     | Inside its owning `ion-tabs`; the shell resolves that element's `ion-tab-bar`.                    |
+| Native host         | Vertical Bars SwiftUI tab host on iOS 26.1+.                                                      |
+| Accessory count     | A single accessory for the host.                                                                  |
+| Web fallback layout | Keep an equivalent Web layout, such as a fixed footer; the source retains its space while hidden. |
+
+Ordinary UIKit tab bars, missing native tabs, iOS 26.0 or competing accessories keep the source on the Web. Applications do not pass native controller references, and the shell does not approximate a system accessory with a floating overlay.
 
 ## Read source geometry and presentation state
 
@@ -246,16 +264,16 @@ try NativeUI.register("app.counter") {
 
 The existing `(props, actions)` closure remains supported. Both forms use the same registration names and duplicate-name checks.
 
-| Context property | Meaning |
-| --- | --- |
-| `sourceID` | Opaque source identity for its current lifetime; not the HTML `id`. |
-| `sourceFrame` | DOM `getBoundingClientRect()` in CSS pixels relative to the Web viewport, including `x`, `y`, `width`, and `height`. |
-| `sourceFrameInWebView` | The source rectangle converted to UIKit points in the WebView's local coordinate system; not screen coordinates. |
-| `viewportWidth` | CSS viewport width used for that snapshot's coordinate conversion. |
-| `pointsPerCSSPixel` | UIKit points per CSS pixel; not device pixel density. |
-| `placement` | `.element` or `.tabAccessory`. |
-| `colorScheme` | `.light` or `.dark`, also applied to the SwiftUI environment. |
-| `layoutDirection` | `.leftToRight` or `.rightToLeft`, also applied to the SwiftUI environment. |
+| Context property       | Meaning                                                                                                              |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `sourceID`             | Opaque source identity for its current lifetime; not the HTML `id`.                                                  |
+| `sourceFrame`          | DOM `getBoundingClientRect()` in CSS pixels relative to the Web viewport, including `x`, `y`, `width`, and `height`. |
+| `sourceFrameInWebView` | The source rectangle converted to UIKit points in the WebView's local coordinate system; not screen coordinates.     |
+| `viewportWidth`        | CSS viewport width used for that snapshot's coordinate conversion.                                                   |
+| `pointsPerCSSPixel`    | UIKit points per CSS pixel; not device pixel density.                                                                |
+| `placement`            | `.element` or `.tabAccessory`.                                                                                       |
+| `colorScheme`          | `.light` or `.dark`, also applied to the SwiftUI environment.                                                        |
+| `layoutDirection`      | `.leftToRight` or `.rightToLeft`, also applied to the SwiftUI environment.                                           |
 
 The closure receives a fresh context when the shell applies an updated snapshot, including source movement, resizing, and appearance changes. Use the current context rather than caching its geometry in `@State`. Updates cross the Web/native bridge; they are not a synchronous DOM measurement from Swift.
 
@@ -272,16 +290,16 @@ Do not apply `sourceFrame.x` or `y` as another SwiftUI offset: the shell already
 
 ## Use the shared projection capabilities
 
-| Capability | How an extension uses it |
-| --- | --- |
-| Position and size | Automatic host placement plus `NativeUIContext`; actual local bounds through `GeometryReader`. |
-| Dark mode and RTL | `context` or SwiftUI `@Environment(\.colorScheme)` and `@Environment(\.layoutDirection)`. |
-| Reduce Motion and accessibility | SwiftUI environment values such as `@Environment(\.accessibilityReduceMotion)` and native accessibility modifiers. Give custom controls accessible names. |
-| DOM-backed application state | Return JSON `props` from `read(element)`; DOM changes trigger synchronization. For changes without a DOM mutation, call `shell.markForCheck()`. |
-| Enabled/visible action targets | `actions.availableNames` or `actions.isAvailable("increment")`; unavailable DOM targets are omitted. |
-| Invoke the original Web action | `try await actions.activate("increment")`; completion and failure follow the contract below. |
-| Temporary Web fallback and teardown | Managed automatically for unsupported content, overlays, navigation suspension, and source removal. |
-| Application-controlled suspension | Use the shell handle's `suspend()`, the returned token's `resume()`, and `destroy()` from JavaScript. |
+| Capability                          | How an extension uses it                                                                                                                                  |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Position and size                   | Automatic host placement plus `NativeUIContext`; actual local bounds through `GeometryReader`.                                                            |
+| Dark mode and RTL                   | `context` or SwiftUI `@Environment(\.colorScheme)` and `@Environment(\.layoutDirection)`.                                                                 |
+| Reduce Motion and accessibility     | SwiftUI environment values such as `@Environment(\.accessibilityReduceMotion)` and native accessibility modifiers. Give custom controls accessible names. |
+| DOM-backed application state        | Return JSON `props` from `read(element)`; DOM changes trigger synchronization. For changes without a DOM mutation, call `shell.markForCheck()`.           |
+| Enabled/visible action targets      | `actions.availableNames` or `actions.isAvailable("increment")`; unavailable DOM targets are omitted.                                                      |
+| Invoke the original Web action      | `try await actions.activate("increment")`; completion and failure follow the contract below.                                                              |
+| Temporary Web fallback and teardown | Managed automatically for unsupported content, overlays, navigation suspension, and source removal.                                                       |
+| Application-controlled suspension   | Use the shell handle's `suspend()`, the returned token's `resume()`, and `destroy()` from JavaScript.                                                     |
 
 For example, disable a native button when its original action is unavailable:
 
@@ -358,8 +376,19 @@ The shell owns discovery, geometry, state synchronization, native controller con
 
 Element placement requires the source to fit fully inside the viewport and its ancestors' overflow clipping bounds, including Ionic's shadow scroll containers. Partially clipped sources stay on the Web and become eligible again when scrolled fully into view. Tab accessories use the system host's placement instead.
 
-`try await actions.activate(name)` completes after the original Web element receives its click. It does **not** wait for application work launched by the click handler (network requests, navigation or modal presentation). Disabled, removed or stale actions reject; teardown, native task cancellation and bridge timeouts settle pending calls. The bridge acknowledgement is a Capacitor Promise method.
+### Action completion
+
+| Event                                                              | Result of `try await actions.activate(name)` |
+| ------------------------------------------------------------------ | -------------------------------------------- |
+| Original Web element receives its click                            | Completes.                                   |
+| Handler starts a network request, navigation or modal presentation | Does not wait for that application work.     |
+| Action is disabled, removed or stale                               | Rejects.                                     |
+| Teardown, native task cancellation or bridge timeout               | Settles pending calls.                       |
+
+The bridge acknowledgement is a Capacitor Promise method.
 
 The [demo reader](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/src/native-ui/counter.ts) and [demo SwiftUI View](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/ios/App/App/NativeUICounter.swift) show both placements using app-local files. Open the Native UI demo page to compare native projection with its Web fallback.
 
-For a complete application feature, see the [SwiftUI mini-player example](native-mini-player.md): artwork, track metadata, playback controls and swipe-to-open, all defined in the demo application.
+## Example: mini-player
+
+The demo mini-player shows the same pattern with track metadata and playback actions: a [DOM reader and Web fallback](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/src/native-ui/mini-player.ts) paired with an [app-local SwiftUI View](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/demo/ios/App/App/NativeMiniPlayer.swift). The Web app owns playback state and modal presentation; native `open` and `toggle` actions activate its original buttons. This is a UI example, not an audio engine. Adapt the files after completing the extension setup above.