@loidolt/theme-capacitor 0.12.2 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/Package.swift ADDED
@@ -0,0 +1,26 @@
1
+ // swift-tools-version: 5.9
2
+ import PackageDescription
3
+
4
+ // The native half of @loidolt/theme-capacitor. `cap sync` finds it through the `capacitor` field in
5
+ // package.json and adds it to the app's Swift package. It uses UIKit API from the iOS 27.1 SDK,
6
+ // so it needs Xcode 27.1 or later to build; on older iOS it reports nothing at runtime.
7
+ let package = Package(
8
+ name: "LoidoltThemeCapacitor",
9
+ platforms: [.iOS(.v15)],
10
+ products: [
11
+ .library(
12
+ name: "LoidoltThemeCapacitor",
13
+ targets: ["DeviceLayoutPlugin"])
14
+ ],
15
+ dependencies: [
16
+ .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
17
+ ],
18
+ targets: [
19
+ .target(
20
+ name: "DeviceLayoutPlugin",
21
+ dependencies: [
22
+ .product(name: "Capacitor", package: "capacitor-swift-pm")
23
+ ],
24
+ path: "ios/Sources/DeviceLayoutPlugin")
25
+ ]
26
+ )
package/README.md CHANGED
@@ -60,6 +60,9 @@ npm install @capacitor/app @capacitor/keyboard @capacitor/haptics @capacitor/pre
60
60
  | `@capacitor/filesystem` | Saving files to the device, and sharing a `File` or Blob natively |
61
61
  | `@capacitor/status-bar` | Only for Android apps that opt out of edge-to-edge |
62
62
 
63
+ The package also has a small native iOS half for the device layout (below). `npx cap sync ios`
64
+ adds it to the app's Swift package; it needs Xcode 27.1 or later to build.
65
+
63
66
  ## Set up
64
67
 
65
68
  Three pieces: the Capacitor config, the viewport, and one call in the root layout.
@@ -142,26 +145,27 @@ and `native.ready` settles once the theme is restored and the splash is gone.
142
145
  Each piece is also exported on its own, for apps that want only one or wire them differently.
143
146
  Every one returns a teardown (or a store with `destroy()`), and is a no-op outside a native shell.
144
147
 
145
- | Export | Does |
146
- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
147
- | `syncNativeAppearance` | Bar icon styles from the `surface` role (configurable per bar), legacy Android status bar colour, iOS keyboard appearance |
148
- | `handleBackButton` | Android back: closes the top layer, then `onBack`, then history, then `atRoot` (`minimize`, `exit`, `none`) |
149
- | `closeTopLayer` | Closes the innermost open overlay the way Escape does; returns whether something took it |
150
- | `createNativeKeyboard` | `visible` and `height`, `data-keyboard="open"`, `--ldt-keyboard-height` and `--ldt-keyboard-inset` on `<html>` |
151
- | `createHaptics` | `impact(weight)`, `selection()`, `notify(variant)`, and `install()` for delegated feedback on controls |
152
- | `withHaptics` | Wraps a toaster so status toasts play the matching notification pattern |
153
- | `persistTheme` | Restores and mirrors a `createTheme` store through `Preferences`; `ready` settles once restored |
154
- | `createAppLifecycle` | Reactive `active`; pauses playing media in the background; `onPause` and `onResume` |
155
- | `handleDeepLinks` | Universal links, app links and custom schemes into the app router (`deepLinkPath` maps the URL) |
156
- | `createNetworkStatus` | Reactive `connected` and `type`; optional offline and back-online toasts |
157
- | `openExternalLinks` | Other-origin links open in the in-app browser with a themed toolbar |
158
- | `hideSplashScreen` | Lifts the splash after `until`, the fonts and a painted frame; no fade under reduced motion |
159
- | `followSystemTextSize` | Applies the system text size, and re-reads it on resume; on iOS also `--ldt-text-zoom` on `<html>` |
160
- | `bridgeClipboard` | Routes `navigator.clipboard.writeText` through the Clipboard plugin |
161
- | `createShare` | `share(content)` through the native sheet, the Web Share API, then a download or the clipboard; `canShare(content?)` |
162
- | `createFiles` | `pick({ accept, multiple })` resolves `File`s from the native picker or a file input; `save(file)` to Documents or a download |
163
- | `markNativePlatform` | `data-native-platform="ios"` or `"android"` on `<html>`, for platform-specific CSS |
164
- | `nativePlatform` | `'ios'`, `'android'` or `null` |
148
+ | Export | Does |
149
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
150
+ | `syncNativeAppearance` | Bar icon styles from the `surface` role (configurable per bar), legacy Android status bar colour, iOS keyboard appearance |
151
+ | `handleBackButton` | Android back: closes the top layer, then `onBack`, then history, then `atRoot` (`minimize`, `exit`, `none`) |
152
+ | `closeTopLayer` | Closes the innermost open overlay the way Escape does; returns whether something took it |
153
+ | `createDeviceLayout` | iPhone Duo's vertical bar edge, fold and reserved regions: `data-bar-edge`, `data-fold`, `data-hinge` and variables on `<html>` |
154
+ | `createNativeKeyboard` | `visible` and `height`, `data-keyboard="open"`, `--ldt-keyboard-height` and `--ldt-keyboard-inset` on `<html>` |
155
+ | `createHaptics` | `impact(weight)`, `selection()`, `notify(variant)`, and `install()` for delegated feedback on controls |
156
+ | `withHaptics` | Wraps a toaster so status toasts play the matching notification pattern |
157
+ | `persistTheme` | Restores and mirrors a `createTheme` store through `Preferences`; `ready` settles once restored |
158
+ | `createAppLifecycle` | Reactive `active`; pauses playing media in the background; `onPause` and `onResume` |
159
+ | `handleDeepLinks` | Universal links, app links and custom schemes into the app router (`deepLinkPath` maps the URL) |
160
+ | `createNetworkStatus` | Reactive `connected` and `type`; optional offline and back-online toasts |
161
+ | `openExternalLinks` | Other-origin links open in the in-app browser with a themed toolbar |
162
+ | `hideSplashScreen` | Lifts the splash after `until`, the fonts and a painted frame; no fade under reduced motion |
163
+ | `followSystemTextSize` | Applies the system text size, and re-reads it on resume; on iOS also `--ldt-text-zoom` on `<html>` |
164
+ | `bridgeClipboard` | Routes `navigator.clipboard.writeText` through the Clipboard plugin |
165
+ | `createShare` | `share(content)` through the native sheet, the Web Share API, then a download or the clipboard; `canShare(content?)` |
166
+ | `createFiles` | `pick({ accept, multiple })` resolves `File`s from the native picker or a file input; `save(file)` to Documents or a download |
167
+ | `markNativePlatform` | `data-native-platform="ios"` or `"android"` on `<html>`, for platform-specific CSS |
168
+ | `nativePlatform` | `'ios'`, `'android'` or `null` |
165
169
 
166
170
  ### Back button and overlays
167
171
 
@@ -178,6 +182,51 @@ needed. With `keyboardResize: 'none'` the keyboard draws over the page, and `--l
178
182
  becomes the bottom safe area, so `AppShell`'s last row, toasts, floating bars and drawers lift
179
183
  above it. `--ldt-keyboard-height` is there for anything of your own.
180
184
 
185
+ ### Device layout
186
+
187
+ On iPhone Duo the system moves toolbars and tab bars to one side, beside the status bar and the
188
+ camera, on the cover screen and on the inner screen in landscape. A page that draws its own bars
189
+ doesn't get that for free, and a web page can't see where the system put them: the safe area says
190
+ how far to stay from each edge, not that bars went to the side, nor where the fold is when the
191
+ device is partly open. `createDeviceLayout` reads them natively (iOS 27.1, through the plugin
192
+ bundled with this package) and writes them on `<html>`:
193
+
194
+ | Written | When |
195
+ | ------------------------------------------- | --------------------------------------------------------------------------------------- |
196
+ | `data-bar-edge="left"` or `"right"` | The system puts bars vertically on that side. A physical side, in every text direction. |
197
+ | `--ldt-bar-start` | With it: how far down that strip your controls can start, below the camera and status |
198
+ | `data-fold="vertical"` or `"horizontal"` | The device is partly open |
199
+ | `--ldt-fold-start`, `--ldt-fold-end` | With it: the band across the fold to keep controls out of; taps there may not register |
200
+ | `data-top-cutout="left"` or `"right"` | Bars stay horizontal and the camera and status bar take that top corner |
201
+ | `--ldt-cutout-width`, `--ldt-cutout-height` | With it: the cutout's size, from the screen edge and from the top |
202
+ | `data-hinge` | `closed`, `partially-open` or `fully-open`, on a device with a hinge |
203
+
204
+ `current` holds the whole report, the reserved regions included, for layouts the attributes
205
+ don't cover. `setupCapacitor` turns it on unless `deviceLayout: false`. Nothing is written on
206
+ other devices, before iOS 27.1, in a browser, or in an app built without running `cap sync` after
207
+ installing this package. See Apple's
208
+ [Designing for iPhone Duo](https://developer.apple.com/design/human-interface-guidelines/designing-for-iphone-duo)
209
+ for where controls belong.
210
+
211
+ `styles.css` acts on them, so an app built on `AppShell`, `Topbar` and `TabBar` follows the
212
+ system without code of its own:
213
+
214
+ - **Bars on the side.** The safe area on the bar edge widens into a strip, at least 4.5rem, that
215
+ `AppShell`, `Topbar`, toasts and drawers all clear. `Topbar`'s actions move into the strip
216
+ below the camera and status bar, and the `TabBar` runs down it from the foot, within reach of
217
+ the thumb. `Topbar` stays at the top of the content as a slim header with the brand and
218
+ navigation. The current tab's accent edge faces the content. The strip's controls share the
219
+ 4.5rem column iOS centres its clock and status icons in, on the content side of the strip, so
220
+ they sit in line under them.
221
+ - **A cutout in a top corner** (the inner screen in portrait). `Topbar` moves up into the band
222
+ beside the camera and status bar, ending where the cutout ends and stopping short of it, so its
223
+ row lines up with the clock instead of starting below a blank strip.
224
+ - **The fold.** Dialogs move to the half before the fold, as the system's alerts do; top and
225
+ bottom drawers cover that half only; side drawers stop short of it; toasts stay in the half
226
+ after it.
227
+
228
+ Every other device and the browser are unchanged.
229
+
181
230
  ### Haptics
182
231
 
183
232
  `install()` ticks on activation of switches, checkboxes, radios, tabs, toggle buttons, options
@@ -0,0 +1,98 @@
1
+ import type { PluginListenerHandle } from './types.js';
2
+ /** A rectangle in CSS pixels, measured from the top left of the web view. */
3
+ export interface DeviceRect {
4
+ x: number;
5
+ y: number;
6
+ width: number;
7
+ height: number;
8
+ }
9
+ /**
10
+ * Part of the display the system keeps for itself. `occlusion` is covered by hardware, such as a
11
+ * front camera and the Dynamic Island around it; `division` is where the display folds, present
12
+ * only while the device is partly open. Taps over either may not register, so keep controls off
13
+ * them. The rectangle includes the system's margins for interactive content.
14
+ */
15
+ export interface DeviceRegion extends DeviceRect {
16
+ kind: 'occlusion' | 'division';
17
+ margins: {
18
+ top: number;
19
+ right: number;
20
+ bottom: number;
21
+ left: number;
22
+ };
23
+ }
24
+ export type HingeStatus = 'closed' | 'partially-open' | 'fully-open' | 'unknown';
25
+ /** What the native side reports. Fields it can't read on this device are left out. */
26
+ export interface DeviceLayoutSnapshot {
27
+ /** The web view's size, in CSS pixels. */
28
+ width: number;
29
+ height: number;
30
+ /**
31
+ * The side where the system puts toolbars and tab bars vertically, as on iPhone Duo's cover
32
+ * screen. A physical side: the system keeps it beside the hardware in every writing direction.
33
+ * Absent where bars stay horizontal.
34
+ */
35
+ barEdge?: 'left' | 'right';
36
+ regions: DeviceRegion[];
37
+ /** The hinge, on a device that has one. `angle` is in degrees: 0 closed, 180 flat. */
38
+ hinge?: {
39
+ status: HingeStatus;
40
+ angle: number;
41
+ };
42
+ }
43
+ /** The native plugin bundled with `@loidolt/theme-capacitor` (iOS). */
44
+ export interface DeviceLayoutPlugin {
45
+ getLayout(): Promise<DeviceLayoutSnapshot>;
46
+ addListener(eventName: 'change', listener: (layout: DeviceLayoutSnapshot) => void): Promise<PluginListenerHandle>;
47
+ }
48
+ export interface DeviceLayoutOptions {
49
+ /** Defaults to the plugin bundled with this package. */
50
+ DeviceLayout?: DeviceLayoutPlugin;
51
+ /** Where the attributes and variables are written. Defaults to `<html>`. */
52
+ element?: HTMLElement;
53
+ }
54
+ export interface DeviceLayout {
55
+ /** The latest report, or `null` before the first one and outside a native shell. Reactive. */
56
+ readonly current: DeviceLayoutSnapshot | null;
57
+ /** Removes the listener, the attributes and the variables. */
58
+ destroy(): void;
59
+ }
60
+ /** The fold, when the device is partly open: where it starts and ends along the axis it crosses. */
61
+ export declare function foldOf(layout: DeviceLayoutSnapshot): {
62
+ axis: 'vertical' | 'horizontal';
63
+ start: number;
64
+ end: number;
65
+ } | null;
66
+ /**
67
+ * How far down the vertical bar's strip the page's own controls should start: below what the
68
+ * system reserves at the top of that strip, the camera with the status bar beside it. 0 when
69
+ * there's no vertical bar.
70
+ */
71
+ export declare function barStartOf(layout: DeviceLayoutSnapshot): number;
72
+ /**
73
+ * The camera's cutout in a top corner, while the bars stay horizontal: iPhone Duo's inner screen
74
+ * in portrait keeps the camera and status bar in a block at the top of one side, and the rest of
75
+ * that band is free. Its width from the screen edge and its height from the top; `null` when
76
+ * there's a vertical bar, or no occlusion touches a top corner, as with a Dynamic Island.
77
+ */
78
+ export declare function topCutoutOf(layout: DeviceLayoutSnapshot): {
79
+ side: 'left' | 'right';
80
+ width: number;
81
+ height: number;
82
+ } | null;
83
+ /**
84
+ * Follows the native layout and tells the stylesheet about it, so a page that draws its own bars
85
+ * can follow the system's on devices like iPhone Duo:
86
+ *
87
+ * - `data-bar-edge="left"` or `"right"` on `<html>` while the system puts bars vertically on that
88
+ * side, with `--ldt-bar-start`, how far down the strip the page's controls can begin.
89
+ * - `data-fold="vertical"` (or `"horizontal"`) while the device is partly open, with
90
+ * `--ldt-fold-start` and `--ldt-fold-end`, the band to keep controls out of.
91
+ * - `data-top-cutout="left"` or `"right"` while the camera and status bar take one top corner and
92
+ * the bars stay horizontal, with `--ldt-cutout-width` and `--ldt-cutout-height`, its size.
93
+ * - `data-hinge`, the hinge status, where the device has one.
94
+ *
95
+ * Needs the iOS plugin bundled with this package (run `cap sync` after installing) and iOS 27.1;
96
+ * elsewhere nothing is written. A no-op in a browser.
97
+ */
98
+ export declare function createDeviceLayout(options?: DeviceLayoutOptions): DeviceLayout;
@@ -0,0 +1,139 @@
1
+ import { registerPlugin } from '@capacitor/core';
2
+ import { onDestroy } from 'svelte';
3
+ import { combine, listen, nativePlatform, quietly } from './platform.js';
4
+ /** The fold, when the device is partly open: where it starts and ends along the axis it crosses. */
5
+ export function foldOf(layout) {
6
+ const fold = layout.regions.find((region) => region.kind === 'division');
7
+ if (!fold)
8
+ return null;
9
+ return fold.height >= fold.width
10
+ ? { axis: 'vertical', start: fold.x, end: fold.x + fold.width }
11
+ : { axis: 'horizontal', start: fold.y, end: fold.y + fold.height };
12
+ }
13
+ /**
14
+ * How far down the vertical bar's strip the page's own controls should start: below what the
15
+ * system reserves at the top of that strip, the camera with the status bar beside it. 0 when
16
+ * there's no vertical bar.
17
+ */
18
+ export function barStartOf(layout) {
19
+ const side = layout.barEdge;
20
+ if (!side)
21
+ return 0;
22
+ const middle = layout.width / 2;
23
+ const inStrip = (rect) => side === 'right' ? rect.x + rect.width / 2 > middle : rect.x + rect.width / 2 < middle;
24
+ return layout.regions
25
+ .filter((region) => region.kind === 'occlusion' && inStrip(region))
26
+ .reduce((bottom, rect) => Math.max(bottom, rect.y + rect.height), 0);
27
+ }
28
+ /**
29
+ * The camera's cutout in a top corner, while the bars stay horizontal: iPhone Duo's inner screen
30
+ * in portrait keeps the camera and status bar in a block at the top of one side, and the rest of
31
+ * that band is free. Its width from the screen edge and its height from the top; `null` when
32
+ * there's a vertical bar, or no occlusion touches a top corner, as with a Dynamic Island.
33
+ */
34
+ export function topCutoutOf(layout) {
35
+ if (layout.barEdge)
36
+ return null;
37
+ const corner = layout.regions.filter((region) => region.kind === 'occlusion' && region.y <= 1 && region.width < layout.width / 2);
38
+ const right = corner.filter((region) => region.x + region.width >= layout.width - 1);
39
+ const left = corner.filter((region) => region.x <= 1);
40
+ // One corner only: with both taken there's no free run of the band to put a header in.
41
+ if (right.length && left.length)
42
+ return null;
43
+ const side = right.length ? 'right' : left.length ? 'left' : null;
44
+ if (!side)
45
+ return null;
46
+ const regions = side === 'right' ? right : left;
47
+ return {
48
+ side,
49
+ width: Math.max(...regions.map((region) => side === 'right' ? layout.width - region.x : region.x + region.width)),
50
+ height: Math.max(...regions.map((region) => region.y + region.height)),
51
+ };
52
+ }
53
+ const px = (value) => `${Math.round(value * 100) / 100}px`;
54
+ /**
55
+ * Follows the native layout and tells the stylesheet about it, so a page that draws its own bars
56
+ * can follow the system's on devices like iPhone Duo:
57
+ *
58
+ * - `data-bar-edge="left"` or `"right"` on `<html>` while the system puts bars vertically on that
59
+ * side, with `--ldt-bar-start`, how far down the strip the page's controls can begin.
60
+ * - `data-fold="vertical"` (or `"horizontal"`) while the device is partly open, with
61
+ * `--ldt-fold-start` and `--ldt-fold-end`, the band to keep controls out of.
62
+ * - `data-top-cutout="left"` or `"right"` while the camera and status bar take one top corner and
63
+ * the bars stay horizontal, with `--ldt-cutout-width` and `--ldt-cutout-height`, its size.
64
+ * - `data-hinge`, the hinge status, where the device has one.
65
+ *
66
+ * Needs the iOS plugin bundled with this package (run `cap sync` after installing) and iOS 27.1;
67
+ * elsewhere nothing is written. A no-op in a browser.
68
+ */
69
+ export function createDeviceLayout(options = {}) {
70
+ let current = $state(null);
71
+ let teardown = () => { };
72
+ const root = options.element ?? (typeof document === 'undefined' ? null : document.documentElement);
73
+ if (nativePlatform() === 'ios' && root) {
74
+ const plugin = options.DeviceLayout ?? registerPlugin('DeviceLayout');
75
+ const clear = () => {
76
+ delete root.dataset.barEdge;
77
+ delete root.dataset.fold;
78
+ delete root.dataset.hinge;
79
+ delete root.dataset.topCutout;
80
+ for (const name of [
81
+ '--ldt-bar-start',
82
+ '--ldt-fold-start',
83
+ '--ldt-fold-end',
84
+ '--ldt-cutout-width',
85
+ '--ldt-cutout-height',
86
+ ]) {
87
+ root.style.removeProperty(name);
88
+ }
89
+ };
90
+ const write = (layout) => {
91
+ current = layout;
92
+ clear();
93
+ if (layout.barEdge) {
94
+ root.dataset.barEdge = layout.barEdge;
95
+ root.style.setProperty('--ldt-bar-start', px(barStartOf(layout)));
96
+ }
97
+ const fold = foldOf(layout);
98
+ if (fold) {
99
+ root.dataset.fold = fold.axis;
100
+ root.style.setProperty('--ldt-fold-start', px(fold.start));
101
+ root.style.setProperty('--ldt-fold-end', px(fold.end));
102
+ }
103
+ const cutout = topCutoutOf(layout);
104
+ if (cutout) {
105
+ root.dataset.topCutout = cutout.side;
106
+ root.style.setProperty('--ldt-cutout-width', px(cutout.width));
107
+ root.style.setProperty('--ldt-cutout-height', px(cutout.height));
108
+ }
109
+ if (layout.hinge && layout.hinge.status !== 'unknown') {
110
+ root.dataset.hinge = layout.hinge.status;
111
+ }
112
+ };
113
+ let changed = false;
114
+ const remove = listen(plugin.addListener('change', (layout) => {
115
+ changed = true;
116
+ write(layout);
117
+ }));
118
+ // An app built without the native half rejects here; the page then just keeps its layout.
119
+ const initial = plugin.getLayout().then((layout) => {
120
+ if (!changed)
121
+ write(layout);
122
+ });
123
+ quietly(initial);
124
+ teardown = combine(remove, clear);
125
+ }
126
+ const destroy = () => teardown();
127
+ try {
128
+ onDestroy(destroy);
129
+ }
130
+ catch {
131
+ /* module scope: the caller owns `destroy()` */
132
+ }
133
+ return {
134
+ get current() {
135
+ return current;
136
+ },
137
+ destroy,
138
+ };
139
+ }
package/dist/index.d.ts CHANGED
@@ -6,6 +6,8 @@ export { syncNativeAppearance, systemBarStyleFor } from './appearance.js';
6
6
  export type { NativeAppearanceOptions, SystemBarStyle } from './appearance.js';
7
7
  export { closeTopLayer, handleBackButton } from './back-button.js';
8
8
  export type { BackButtonEvent, BackButtonOptions } from './back-button.js';
9
+ export { barStartOf, createDeviceLayout, foldOf, topCutoutOf } from './device-layout.svelte.js';
10
+ export type { DeviceLayout, DeviceLayoutOptions, DeviceLayoutPlugin, DeviceLayoutSnapshot, DeviceRect, DeviceRegion, HingeStatus, } from './device-layout.svelte.js';
9
11
  export { createNativeKeyboard } from './keyboard.svelte.js';
10
12
  export type { NativeKeyboard, NativeKeyboardOptions } from './keyboard.svelte.js';
11
13
  export { createHaptics, SELECTION_TARGETS, withHaptics } from './haptics.js';
package/dist/index.js CHANGED
@@ -2,6 +2,7 @@ export { isNativePlatform, markNativePlatform, nativePlatform } from './platform
2
2
  export { setupCapacitor } from './setup.js';
3
3
  export { syncNativeAppearance, systemBarStyleFor } from './appearance.js';
4
4
  export { closeTopLayer, handleBackButton } from './back-button.js';
5
+ export { barStartOf, createDeviceLayout, foldOf, topCutoutOf } from './device-layout.svelte.js';
5
6
  export { createNativeKeyboard } from './keyboard.svelte.js';
6
7
  export { createHaptics, SELECTION_TARGETS, withHaptics } from './haptics.js';
7
8
  export { persistTheme } from './theme-storage.svelte.js';
package/dist/setup.d.ts CHANGED
@@ -4,6 +4,7 @@ import { type BackButtonOptions } from './back-button.js';
4
4
  import { type HapticsOptions, type InstallHapticsOptions, type NativeHaptics } from './haptics.js';
5
5
  import { type NativeKeyboard, type NativeKeyboardOptions } from './keyboard.svelte.js';
6
6
  import { type DeepLinkOptions } from './deep-links.js';
7
+ import { type DeviceLayout, type DeviceLayoutOptions, type DeviceLayoutPlugin } from './device-layout.svelte.js';
7
8
  import { type AppLifecycle, type AppLifecycleOptions } from './lifecycle.svelte.js';
8
9
  import { type ExternalLinksOptions } from './links.js';
9
10
  import { type NetworkStatus, type NetworkStatusOptions } from './network.svelte.js';
@@ -16,6 +17,8 @@ export interface CapacitorPlugins {
16
17
  App?: BackButtonPlugin & AppStatePlugin & AppUrlPlugin & AppResumePlugin;
17
18
  Browser?: BrowserPlugin;
18
19
  Clipboard?: ClipboardPlugin;
20
+ /** Defaults to the iOS plugin bundled with this package. */
21
+ DeviceLayout?: DeviceLayoutPlugin;
19
22
  FilePicker?: FilePickerPlugin;
20
23
  Filesystem?: FilesystemPlugin;
21
24
  Haptics?: HapticsPlugin;
@@ -47,6 +50,7 @@ export interface SetupCapacitorOptions {
47
50
  splash?: Toggle<Omit<HideSplashOptions, 'SplashScreen' | 'until'>>;
48
51
  share?: Toggle<Omit<NativeShareOptions, 'Share' | 'Filesystem' | 'toaster'>>;
49
52
  files?: Toggle<Omit<NativeFilesOptions, 'FilePicker' | 'Filesystem'>>;
53
+ deviceLayout?: Toggle<Omit<DeviceLayoutOptions, 'DeviceLayout'>>;
50
54
  textSize?: boolean;
51
55
  clipboard?: boolean;
52
56
  }
@@ -69,6 +73,11 @@ export interface CapacitorSetup {
69
73
  * input and a download in a browser. Present unless `files: false`: the browser needs no plugin.
70
74
  */
71
75
  readonly files: NativeFiles | undefined;
76
+ /**
77
+ * Where the system puts its vertical bar and which parts of the display are reserved (iPhone
78
+ * Duo). Present unless `deviceLayout: false`; it reports nothing outside iOS 27.1.
79
+ */
80
+ readonly deviceLayout: DeviceLayout | undefined;
72
81
  /** The toaster you passed, with haptics on its status toasts when `Haptics` was given. */
73
82
  readonly toaster: Toaster | undefined;
74
83
  /** Settles once the stored theme is restored and the splash screen has lifted. */
package/dist/setup.js CHANGED
@@ -4,6 +4,7 @@ import { handleBackButton } from './back-button.js';
4
4
  import { createHaptics, withHaptics, } from './haptics.js';
5
5
  import { createNativeKeyboard, } from './keyboard.svelte.js';
6
6
  import { handleDeepLinks } from './deep-links.js';
7
+ import { createDeviceLayout, } from './device-layout.svelte.js';
7
8
  import { createAppLifecycle, } from './lifecycle.svelte.js';
8
9
  import { openExternalLinks } from './links.js';
9
10
  import { createNetworkStatus, } from './network.svelte.js';
@@ -40,7 +41,7 @@ const on = (value) => value === false ? null : (value ?? {});
40
41
  */
41
42
  export function setupCapacitor(options) {
42
43
  const { plugins, theme, navigate } = options;
43
- const { App, Browser, Clipboard, Haptics, Keyboard, Network, Preferences } = plugins;
44
+ const { App, Browser, Clipboard, DeviceLayout, Haptics, Keyboard, Network, Preferences } = plugins;
44
45
  const { FilePicker, Filesystem, Share, SplashScreen, StatusBar, TextZoom } = plugins;
45
46
  const teardowns = [markNativePlatform()];
46
47
  const appearance = on(options.appearance);
@@ -96,6 +97,12 @@ export function setupCapacitor(options) {
96
97
  : undefined;
97
98
  const filesOptions = on(options.files);
98
99
  const files = filesOptions ? createFiles({ ...filesOptions, FilePicker, Filesystem }) : undefined;
100
+ const deviceLayoutOptions = on(options.deviceLayout);
101
+ const deviceLayout = deviceLayoutOptions
102
+ ? createDeviceLayout({ ...deviceLayoutOptions, DeviceLayout })
103
+ : undefined;
104
+ if (deviceLayout)
105
+ teardowns.push(deviceLayout.destroy);
99
106
  const restored = persisted?.ready ?? Promise.resolve();
100
107
  const splash = on(options.splash);
101
108
  const ready = SplashScreen && splash
@@ -108,5 +115,16 @@ export function setupCapacitor(options) {
108
115
  catch {
109
116
  /* module scope: the caller owns `destroy()` */
110
117
  }
111
- return { files, haptics, keyboard, lifecycle, network, share, toaster, ready, destroy };
118
+ return {
119
+ deviceLayout,
120
+ files,
121
+ haptics,
122
+ keyboard,
123
+ lifecycle,
124
+ network,
125
+ share,
126
+ toaster,
127
+ ready,
128
+ destroy,
129
+ };
112
130
  }
package/dist/styles.css CHANGED
@@ -47,6 +47,179 @@
47
47
  display: none;
48
48
  }
49
49
 
50
+ /*
51
+ * Bars on the side (`createDeviceLayout`'s `data-bar-edge`). On iPhone Duo's cover screen, and on
52
+ * its inner screen in landscape, iOS moves toolbars and tab bars into a strip on one edge, below
53
+ * the camera and status bar. The strip is that edge's safe area, widened if need be to fit a tab,
54
+ * and every `--ldt-safe-*` reader (AppShell, Topbar, toasts, drawers) then clears it as a whole.
55
+ * Top to bottom it holds what the system reserves (`--ldt-bar-start`), Topbar's actions, and the
56
+ * TabBar at the foot, within reach of the thumb. Topbar stays as a slim header in the content.
57
+ *
58
+ * iOS lines its own items (the clock, the status icons) up in a 4.5rem column on the content side
59
+ * of the strip, and leaves what's left of a wider strip as margin at the bezel; on iPhone Duo the
60
+ * strip is 84pt and the column's centre 48pt in from the edge. The page's controls share that
61
+ * column (`--ldt-bar-outer` is the margin), so they sit in line under the clock.
62
+ */
63
+ :where(:root[data-bar-edge='right']) {
64
+ --ldt-bar-width: max(var(--safe-area-inset-right, env(safe-area-inset-right, 0px)), 4.5rem);
65
+ --ldt-bar-outer: calc(var(--ldt-bar-width) - 4.5rem);
66
+ --ldt-safe-right: var(--ldt-bar-width);
67
+ }
68
+ :where(:root[data-bar-edge='left']) {
69
+ --ldt-bar-width: max(var(--safe-area-inset-left, env(safe-area-inset-left, 0px)), 4.5rem);
70
+ --ldt-bar-outer: calc(var(--ldt-bar-width) - 4.5rem);
71
+ --ldt-safe-left: var(--ldt-bar-width);
72
+ }
73
+ /* The strip's surface, full height, under the system's items and the page's own. */
74
+ :where([data-bar-edge] body)::after {
75
+ content: '';
76
+ position: fixed;
77
+ inset-block: 0;
78
+ z-index: var(--loidolt-z-sticky);
79
+ width: var(--ldt-bar-width);
80
+ background: var(--loidolt-surface);
81
+ pointer-events: none;
82
+ }
83
+ :where([data-bar-edge='right'] body)::after {
84
+ right: 0;
85
+ border-left: var(--loidolt-border-width) solid var(--loidolt-border);
86
+ }
87
+ :where([data-bar-edge='left'] body)::after {
88
+ left: 0;
89
+ border-right: var(--loidolt-border-width) solid var(--loidolt-border);
90
+ }
91
+ :where([data-bar-edge] .ldt-topbar__actions) {
92
+ position: fixed;
93
+ top: var(--ldt-bar-start, 0px);
94
+ z-index: calc(var(--loidolt-z-sticky) + 1);
95
+ width: var(--ldt-bar-width);
96
+ margin: 0;
97
+ padding-block: var(--loidolt-space-2);
98
+ flex-direction: column;
99
+ overflow: visible;
100
+ }
101
+ :where([data-bar-edge='right'] .ldt-topbar__actions) {
102
+ right: 0;
103
+ padding-right: var(--ldt-bar-outer);
104
+ }
105
+ :where([data-bar-edge='left'] .ldt-topbar__actions) {
106
+ left: 0;
107
+ padding-left: var(--ldt-bar-outer);
108
+ }
109
+ :where([data-bar-edge] .ldt-app-shell > .ldt-tab-bar) {
110
+ position: fixed;
111
+ bottom: 0;
112
+ z-index: calc(var(--loidolt-z-sticky) + 1);
113
+ width: var(--ldt-bar-width);
114
+ /* Room enough below the system's items for a few of Topbar's actions above the tabs. */
115
+ max-height: calc(100dvh - var(--ldt-bar-start, 0px) - 6rem);
116
+ overflow-y: auto;
117
+ flex-direction: column;
118
+ justify-content: flex-end;
119
+ border-top: 0;
120
+ background: transparent;
121
+ }
122
+ :where([data-bar-edge='right'] .ldt-app-shell > .ldt-tab-bar) {
123
+ right: 0;
124
+ padding: 0 var(--ldt-bar-outer) var(--ldt-safe-bottom) 0;
125
+ }
126
+ :where([data-bar-edge='left'] .ldt-app-shell > .ldt-tab-bar) {
127
+ left: 0;
128
+ padding: 0 0 var(--ldt-safe-bottom) var(--ldt-bar-outer);
129
+ }
130
+ :where([data-bar-edge] .ldt-tab-bar__item) {
131
+ flex: none;
132
+ }
133
+ /* The current tab's indicator stays on the edge facing the content. */
134
+ :where([data-bar-edge='right'] .ldt-tab-bar__item[aria-current='page']) {
135
+ box-shadow: inset var(--loidolt-stroke-indicator) 0 0 var(--loidolt-accent);
136
+ }
137
+ :where([data-bar-edge='left'] .ldt-tab-bar__item[aria-current='page']) {
138
+ box-shadow: inset calc(-1 * var(--loidolt-stroke-indicator)) 0 0 var(--loidolt-accent);
139
+ }
140
+ /* With the TabBar out of the grid, the page is the last row and clears the bottom itself. Only a
141
+ full-screen shell has bars at the side, and its page row is `<main>`. */
142
+ :where([data-bar-edge] .ldt-app-shell > main) {
143
+ padding-bottom: var(--ldt-safe-bottom, env(safe-area-inset-bottom, 0px));
144
+ }
145
+
146
+ /*
147
+ * A camera cutout in one top corner (`data-top-cutout`, with `--ldt-cutout-width` and
148
+ * `--ldt-cutout-height`): iPhone Duo's inner screen in portrait. The status bar lives in the
149
+ * cutout, so the top inset spans the whole width though only that corner is taken. Topbar moves
150
+ * up into the band beside it, ending where the cutout ends and stopping short of it at the side,
151
+ * rather than starting below a blank strip; its row then lines up with the clock. Only Topbar:
152
+ * overlays still clear the band. The cutout comes with a phone-width screen, where Topbar pads a
153
+ * row of 44px touch targets by `space-3` above and below.
154
+ */
155
+ :where([data-top-cutout] .ldt-topbar) {
156
+ --ldt-safe-top: max(0px, calc(var(--ldt-cutout-height) - 2 * var(--loidolt-space-3) - 44px));
157
+ }
158
+ :where([data-top-cutout='right'] .ldt-topbar) {
159
+ --ldt-safe-right: max(
160
+ var(--safe-area-inset-right, env(safe-area-inset-right, 0px)),
161
+ calc(var(--ldt-cutout-width) - var(--loidolt-pad-bar-x))
162
+ );
163
+ }
164
+ :where([data-top-cutout='left'] .ldt-topbar) {
165
+ --ldt-safe-left: max(
166
+ var(--safe-area-inset-left, env(safe-area-inset-left, 0px)),
167
+ calc(var(--ldt-cutout-width) - var(--loidolt-pad-bar-x))
168
+ );
169
+ }
170
+ /* The status bar backdrop covers the cutout only, not the header beside it. */
171
+ :where([data-native-platform][data-top-cutout] body)::before {
172
+ width: var(--ldt-cutout-width);
173
+ height: var(--ldt-cutout-height);
174
+ }
175
+ :where([data-native-platform][data-top-cutout='right'] body)::before {
176
+ left: auto;
177
+ }
178
+ :where([data-native-platform][data-top-cutout='left'] body)::before {
179
+ right: auto;
180
+ }
181
+
182
+ /*
183
+ * The fold (`data-fold`, with `--ldt-fold-start` and `--ldt-fold-end`), while the device is partly
184
+ * open. Taps over it may not register, so what the theme centres on the screen moves to one side
185
+ * of it, as the system's alerts and sheets do: the first half, or the second for what already
186
+ * sits at the end (toasts). Side drawers stop short of it.
187
+ */
188
+ :where([data-fold='vertical'] .ldt-dialog) {
189
+ left: calc(var(--ldt-fold-start) / 2);
190
+ width: min(var(--ldt-dialog-width, 34rem), calc(var(--ldt-fold-start) - 2rem));
191
+ }
192
+ :where([data-fold='horizontal'] .ldt-dialog) {
193
+ top: calc(var(--ldt-fold-start) / 2);
194
+ max-height: calc(var(--ldt-fold-start) - 2rem);
195
+ }
196
+ :where([data-fold='vertical'] :is(.ldt-drawer--top, .ldt-drawer--bottom)) {
197
+ right: auto;
198
+ width: var(--ldt-fold-start);
199
+ /* It no longer reaches the right edge, so there is no inset there to clear. */
200
+ padding-right: 0;
201
+ }
202
+ :where([data-fold='vertical'] .ldt-drawer--left) {
203
+ width: min(var(--ldt-drawer-size, 20rem), var(--ldt-fold-start));
204
+ }
205
+ :where([data-fold='vertical'] .ldt-drawer--right) {
206
+ width: min(var(--ldt-drawer-size, 20rem), calc(100vw - var(--ldt-fold-end)));
207
+ }
208
+ :where([data-fold='horizontal'] .ldt-drawer--top) {
209
+ height: min(var(--ldt-drawer-size, 20rem), var(--ldt-fold-start));
210
+ }
211
+ :where([data-fold='horizontal'] .ldt-drawer--bottom) {
212
+ height: min(var(--ldt-drawer-size, 20rem), calc(100dvh - var(--ldt-fold-end)));
213
+ }
214
+ :where([data-fold='vertical'] .ldt-toast-viewport) {
215
+ width: min(
216
+ 24rem,
217
+ calc(
218
+ 100vw - var(--ldt-fold-end) - 2rem - var(--ldt-safe-right, env(safe-area-inset-right, 0px))
219
+ )
220
+ );
221
+ }
222
+
50
223
  /*
51
224
  * Native touch manners (`data-native-platform`, written by `markNativePlatform`): no grey flash
52
225
  * on tap, and long-pressing a control does not select its label or open the link callout.
@@ -0,0 +1,180 @@
1
+ import Capacitor
2
+ import UIKit
3
+
4
+ /// Tells the web view where iOS puts its vertical bar and which parts of the display are reserved,
5
+ /// so a page drawing its own bars can follow the system's layout on iPhone Duo.
6
+ ///
7
+ /// A web page can't read these: `env(safe-area-inset-*)` says how far content stays from each
8
+ /// edge, but not that the system has moved bars to the side, nor where the fold is when the
9
+ /// device is partly open. This reads them natively and sends them to the page as one `change`
10
+ /// event, and on request through `getLayout()`.
11
+ ///
12
+ /// Everything is in the web view's coordinate space, which is CSS pixels in a page with
13
+ /// `width=device-width` and no zoom. On iOS before 27.1 the page gets no edge and no regions.
14
+ @objc(DeviceLayoutPlugin)
15
+ public class DeviceLayoutPlugin: CAPPlugin, CAPBridgedPlugin {
16
+ public let identifier = "DeviceLayoutPlugin"
17
+ public let jsName = "DeviceLayout"
18
+ public let pluginMethods: [CAPPluginMethod] = [
19
+ CAPPluginMethod(name: "getLayout", returnType: CAPPluginReturnPromise)
20
+ ]
21
+
22
+ private var observer: LayoutObserverView?
23
+ private var hingeStatus: String?
24
+ private var hingeAngle: Double?
25
+ private var lastLayout: JSObject?
26
+ private var publishScheduled = false
27
+
28
+ override public func load() {
29
+ Task { @MainActor [weak self] in self?.install() }
30
+ }
31
+
32
+ @objc func getLayout(_ call: CAPPluginCall) {
33
+ Task { @MainActor [weak self] in
34
+ guard let self else { return call.resolve(DeviceLayoutPlugin.emptyLayout) }
35
+ call.resolve(self.currentLayout())
36
+ }
37
+ }
38
+
39
+ /// Adds an invisible view to the web view, sized with it, that reports every change the layout
40
+ /// depends on: size, safe area, the vertical bar's traits and the hinge. It goes inside the web
41
+ /// view because at load the web view isn't in its view controller's hierarchy yet.
42
+ @MainActor
43
+ private func install() {
44
+ guard observer == nil, let webView = bridge?.webView else { return }
45
+ let view = LayoutObserverView(frame: webView.bounds)
46
+ view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
47
+ view.isUserInteractionEnabled = false
48
+ view.isAccessibilityElement = false
49
+ view.backgroundColor = .clear
50
+ view.onChange = { [weak self] in self?.schedulePublish() }
51
+ webView.insertSubview(view, at: 0)
52
+ observer = view
53
+
54
+ if #available(iOS 27.1, *) {
55
+ view.registerForTraitChanges(UITraitCollection.systemTraitsAffectingVerticalBarEdge) {
56
+ (observed: LayoutObserverView, _: UITraitCollection) in
57
+ observed.onChange?()
58
+ }
59
+ // Opening the device part-way adds the fold without changing the view's size, so the
60
+ // hinge is what tells us to look again.
61
+ view.addInteraction(UIHingeInteraction { [weak self] _, update in
62
+ guard let self else { return }
63
+ if let hinge = update.hinge {
64
+ self.hingeStatus = DeviceLayoutPlugin.name(of: hinge.status)
65
+ // UIKit reports radians; degrees read more naturally in a page.
66
+ self.hingeAngle = Double(hinge.angle) * 180 / .pi
67
+ } else {
68
+ self.hingeStatus = nil
69
+ self.hingeAngle = nil
70
+ }
71
+ self.schedulePublish()
72
+ })
73
+ }
74
+ schedulePublish()
75
+ }
76
+
77
+ /// Several changes arrive together when the device folds; send one event after them.
78
+ @MainActor
79
+ private func schedulePublish() {
80
+ guard !publishScheduled else { return }
81
+ publishScheduled = true
82
+ Task { @MainActor [weak self] in
83
+ guard let self else { return }
84
+ self.publishScheduled = false
85
+ let layout = self.currentLayout()
86
+ if let last = self.lastLayout, NSDictionary(dictionary: last).isEqual(to: layout) { return }
87
+ self.lastLayout = layout
88
+ self.notifyListeners("change", data: layout, retainUntilConsumed: true)
89
+ }
90
+ }
91
+
92
+ @MainActor
93
+ private func currentLayout() -> JSObject {
94
+ guard let webView = bridge?.webView else { return DeviceLayoutPlugin.emptyLayout }
95
+ var layout: JSObject = [
96
+ "width": Double(webView.bounds.width),
97
+ "height": Double(webView.bounds.height),
98
+ "regions": [JSValue]()
99
+ ]
100
+ if #available(iOS 27.1, *) {
101
+ if let edge = DeviceLayoutPlugin.side(of: webView.traitCollection.verticalBarEdge,
102
+ in: webView.effectiveUserInterfaceLayoutDirection) {
103
+ layout["barEdge"] = edge
104
+ }
105
+ let kinds: [(String, UIView.ReservedRegion.Kind)] = [
106
+ ("occlusion", .occlusion), ("division", .division)
107
+ ]
108
+ var regions = [JSValue]()
109
+ for (name, kind) in kinds {
110
+ for region in webView.reservedRegions(kind: kind) {
111
+ var entry = DeviceLayoutPlugin.rect(region.frame)
112
+ entry["kind"] = name
113
+ entry["margins"] = [
114
+ "top": Double(region.margins.top),
115
+ "right": Double(region.margins.right),
116
+ "bottom": Double(region.margins.bottom),
117
+ "left": Double(region.margins.left)
118
+ ] as JSObject
119
+ regions.append(entry)
120
+ }
121
+ }
122
+ layout["regions"] = regions
123
+ if let hingeStatus { layout["hinge"] = ["status": hingeStatus, "angle": hingeAngle ?? 0] as JSObject }
124
+ }
125
+ return layout
126
+ }
127
+
128
+ private static let emptyLayout: JSObject = ["width": 0, "height": 0, "regions": [JSValue]()]
129
+
130
+ private static func rect(_ rect: CGRect) -> JSObject {
131
+ [
132
+ "x": Double(rect.minX),
133
+ "y": Double(rect.minY),
134
+ "width": Double(rect.width),
135
+ "height": Double(rect.height)
136
+ ]
137
+ }
138
+
139
+ /// The edge as a physical side. The system keeps the bar beside the hardware, so a page lays
140
+ /// it out with `left` and `right`, not with the writing direction.
141
+ @available(iOS 27.1, *)
142
+ private static func side(of edge: UIVerticalBarEdge,
143
+ in direction: UIUserInterfaceLayoutDirection) -> String? {
144
+ switch edge {
145
+ case .leading: return direction == .rightToLeft ? "right" : "left"
146
+ case .trailing: return direction == .rightToLeft ? "left" : "right"
147
+ default: return nil
148
+ }
149
+ }
150
+
151
+ @available(iOS 27.1, *)
152
+ private static func name(of status: UIHinge.Status) -> String {
153
+ switch status {
154
+ case .closed: return "closed"
155
+ case .partiallyOpen: return "partially-open"
156
+ case .fullyOpen: return "fully-open"
157
+ default: return "unknown"
158
+ }
159
+ }
160
+ }
161
+
162
+ /// Calls `onChange` whenever UIKit lays it out or its safe area moves.
163
+ final class LayoutObserverView: UIView {
164
+ var onChange: (@MainActor () -> Void)?
165
+
166
+ override func layoutSubviews() {
167
+ super.layoutSubviews()
168
+ onChange?()
169
+ }
170
+
171
+ override func safeAreaInsetsDidChange() {
172
+ super.safeAreaInsetsDidChange()
173
+ onChange?()
174
+ }
175
+
176
+ override func didMoveToWindow() {
177
+ super.didMoveToWindow()
178
+ onChange?()
179
+ }
180
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@loidolt/theme-capacitor",
3
- "version": "0.12.2",
3
+ "version": "0.14.0",
4
4
  "description": "Capacitor adapters that carry the Loidolt theme into native iOS and Android apps",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -20,11 +20,18 @@
20
20
  "./package.json": "./package.json"
21
21
  },
22
22
  "files": [
23
- "dist"
23
+ "dist",
24
+ "ios/Sources",
25
+ "Package.swift"
24
26
  ],
25
27
  "sideEffects": [
26
28
  "**/*.css"
27
29
  ],
30
+ "capacitor": {
31
+ "ios": {
32
+ "src": "ios"
33
+ }
34
+ },
28
35
  "scripts": {
29
36
  "build": "svelte-package -i src/lib -o dist && cp src/styles.css dist/styles.css",
30
37
  "prepack": "npm run build",
@@ -34,8 +41,8 @@
34
41
  "clean": "rimraf dist"
35
42
  },
36
43
  "dependencies": {
37
- "@loidolt/theme-svelte": "^0.12.2",
38
- "@loidolt/theme-tokens": "^0.12.2"
44
+ "@loidolt/theme-svelte": "^0.14.0",
45
+ "@loidolt/theme-tokens": "^0.14.0"
39
46
  },
40
47
  "peerDependencies": {
41
48
  "@capacitor/app": "^8.0.0",