@loidolt/theme-capacitor 0.12.2 → 0.13.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,44 @@ 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-hinge` | `closed`, `partially-open` or `fully-open`, on a device with a hinge |
201
+
202
+ `current` holds the whole report, the reserved regions included, for layouts the attributes
203
+ don't cover. `setupCapacitor` turns it on unless `deviceLayout: false`. Nothing is written on
204
+ other devices, before iOS 27.1, in a browser, or in an app built without running `cap sync` after
205
+ installing this package. See Apple's
206
+ [Designing for iPhone Duo](https://developer.apple.com/design/human-interface-guidelines/designing-for-iphone-duo)
207
+ for where controls belong.
208
+
209
+ `styles.css` acts on them, so an app built on `AppShell`, `Topbar` and `TabBar` follows the
210
+ system without code of its own:
211
+
212
+ - **Bars on the side.** The safe area on the bar edge widens into a strip, at least 4.5rem, that
213
+ `AppShell`, `Topbar`, toasts and drawers all clear. `Topbar`'s actions move into the strip
214
+ below the camera and status bar, and the `TabBar` runs down it from the foot, within reach of
215
+ the thumb. `Topbar` stays at the top of the content as a slim header with the brand and
216
+ navigation. The current tab's accent edge faces the content.
217
+ - **The fold.** Dialogs move to the half before the fold, as the system's alerts do; top and
218
+ bottom drawers cover that half only; side drawers stop short of it; toasts stay in the half
219
+ after it.
220
+
221
+ Inner screen in portrait, every other device and the browser are unchanged.
222
+
181
223
  ### Haptics
182
224
 
183
225
  `install()` ticks on activation of switches, checkboxes, radios, tabs, toggle buttons, options
@@ -0,0 +1,85 @@
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
+ * Follows the native layout and tells the stylesheet about it, so a page that draws its own bars
74
+ * can follow the system's on devices like iPhone Duo:
75
+ *
76
+ * - `data-bar-edge="left"` or `"right"` on `<html>` while the system puts bars vertically on that
77
+ * side, with `--ldt-bar-start`, how far down the strip the page's controls can begin.
78
+ * - `data-fold="vertical"` (or `"horizontal"`) while the device is partly open, with
79
+ * `--ldt-fold-start` and `--ldt-fold-end`, the band to keep controls out of.
80
+ * - `data-hinge`, the hinge status, where the device has one.
81
+ *
82
+ * Needs the iOS plugin bundled with this package (run `cap sync` after installing) and iOS 27.1;
83
+ * elsewhere nothing is written. A no-op in a browser.
84
+ */
85
+ export declare function createDeviceLayout(options?: DeviceLayoutOptions): DeviceLayout;
@@ -0,0 +1,99 @@
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
+ const px = (value) => `${Math.round(value * 100) / 100}px`;
29
+ /**
30
+ * Follows the native layout and tells the stylesheet about it, so a page that draws its own bars
31
+ * can follow the system's on devices like iPhone Duo:
32
+ *
33
+ * - `data-bar-edge="left"` or `"right"` on `<html>` while the system puts bars vertically on that
34
+ * side, with `--ldt-bar-start`, how far down the strip the page's controls can begin.
35
+ * - `data-fold="vertical"` (or `"horizontal"`) while the device is partly open, with
36
+ * `--ldt-fold-start` and `--ldt-fold-end`, the band to keep controls out of.
37
+ * - `data-hinge`, the hinge status, where the device has one.
38
+ *
39
+ * Needs the iOS plugin bundled with this package (run `cap sync` after installing) and iOS 27.1;
40
+ * elsewhere nothing is written. A no-op in a browser.
41
+ */
42
+ export function createDeviceLayout(options = {}) {
43
+ let current = $state(null);
44
+ let teardown = () => { };
45
+ const root = options.element ?? (typeof document === 'undefined' ? null : document.documentElement);
46
+ if (nativePlatform() === 'ios' && root) {
47
+ const plugin = options.DeviceLayout ?? registerPlugin('DeviceLayout');
48
+ const clear = () => {
49
+ delete root.dataset.barEdge;
50
+ delete root.dataset.fold;
51
+ delete root.dataset.hinge;
52
+ for (const name of ['--ldt-bar-start', '--ldt-fold-start', '--ldt-fold-end']) {
53
+ root.style.removeProperty(name);
54
+ }
55
+ };
56
+ const write = (layout) => {
57
+ current = layout;
58
+ clear();
59
+ if (layout.barEdge) {
60
+ root.dataset.barEdge = layout.barEdge;
61
+ root.style.setProperty('--ldt-bar-start', px(barStartOf(layout)));
62
+ }
63
+ const fold = foldOf(layout);
64
+ if (fold) {
65
+ root.dataset.fold = fold.axis;
66
+ root.style.setProperty('--ldt-fold-start', px(fold.start));
67
+ root.style.setProperty('--ldt-fold-end', px(fold.end));
68
+ }
69
+ if (layout.hinge && layout.hinge.status !== 'unknown') {
70
+ root.dataset.hinge = layout.hinge.status;
71
+ }
72
+ };
73
+ let changed = false;
74
+ const remove = listen(plugin.addListener('change', (layout) => {
75
+ changed = true;
76
+ write(layout);
77
+ }));
78
+ // An app built without the native half rejects here; the page then just keeps its layout.
79
+ const initial = plugin.getLayout().then((layout) => {
80
+ if (!changed)
81
+ write(layout);
82
+ });
83
+ quietly(initial);
84
+ teardown = combine(remove, clear);
85
+ }
86
+ const destroy = () => teardown();
87
+ try {
88
+ onDestroy(destroy);
89
+ }
90
+ catch {
91
+ /* module scope: the caller owns `destroy()` */
92
+ }
93
+ return {
94
+ get current() {
95
+ return current;
96
+ },
97
+ destroy,
98
+ };
99
+ }
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 } 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 } 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,133 @@
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
+ :where(:root[data-bar-edge='right']) {
59
+ --ldt-bar-width: max(var(--safe-area-inset-right, env(safe-area-inset-right, 0px)), 4.5rem);
60
+ --ldt-safe-right: var(--ldt-bar-width);
61
+ }
62
+ :where(:root[data-bar-edge='left']) {
63
+ --ldt-bar-width: max(var(--safe-area-inset-left, env(safe-area-inset-left, 0px)), 4.5rem);
64
+ --ldt-safe-left: var(--ldt-bar-width);
65
+ }
66
+ /* The strip's surface, full height, under the system's items and the page's own. */
67
+ :where([data-bar-edge] body)::after {
68
+ content: '';
69
+ position: fixed;
70
+ inset-block: 0;
71
+ z-index: var(--loidolt-z-sticky);
72
+ width: var(--ldt-bar-width);
73
+ background: var(--loidolt-surface);
74
+ pointer-events: none;
75
+ }
76
+ :where([data-bar-edge='right'] body)::after {
77
+ right: 0;
78
+ border-left: var(--loidolt-border-width) solid var(--loidolt-border);
79
+ }
80
+ :where([data-bar-edge='left'] body)::after {
81
+ left: 0;
82
+ border-right: var(--loidolt-border-width) solid var(--loidolt-border);
83
+ }
84
+ :where([data-bar-edge] .ldt-topbar__actions) {
85
+ position: fixed;
86
+ top: var(--ldt-bar-start, 0px);
87
+ z-index: calc(var(--loidolt-z-sticky) + 1);
88
+ width: var(--ldt-bar-width);
89
+ margin: 0;
90
+ padding-block: var(--loidolt-space-2);
91
+ flex-direction: column;
92
+ overflow: visible;
93
+ }
94
+ :where([data-bar-edge='right'] .ldt-topbar__actions) {
95
+ right: 0;
96
+ }
97
+ :where([data-bar-edge='left'] .ldt-topbar__actions) {
98
+ left: 0;
99
+ }
100
+ :where([data-bar-edge] .ldt-app-shell > .ldt-tab-bar) {
101
+ position: fixed;
102
+ bottom: 0;
103
+ z-index: calc(var(--loidolt-z-sticky) + 1);
104
+ width: var(--ldt-bar-width);
105
+ /* Room enough below the system's items for a few of Topbar's actions above the tabs. */
106
+ max-height: calc(100dvh - var(--ldt-bar-start, 0px) - 6rem);
107
+ overflow-y: auto;
108
+ flex-direction: column;
109
+ justify-content: flex-end;
110
+ padding: 0 0 var(--ldt-safe-bottom);
111
+ border-top: 0;
112
+ background: transparent;
113
+ }
114
+ :where([data-bar-edge='right'] .ldt-app-shell > .ldt-tab-bar) {
115
+ right: 0;
116
+ }
117
+ :where([data-bar-edge='left'] .ldt-app-shell > .ldt-tab-bar) {
118
+ left: 0;
119
+ }
120
+ :where([data-bar-edge] .ldt-tab-bar__item) {
121
+ flex: none;
122
+ }
123
+ /* The current tab's indicator stays on the edge facing the content. */
124
+ :where([data-bar-edge='right'] .ldt-tab-bar__item[aria-current='page']) {
125
+ box-shadow: inset var(--loidolt-stroke-indicator) 0 0 var(--loidolt-accent);
126
+ }
127
+ :where([data-bar-edge='left'] .ldt-tab-bar__item[aria-current='page']) {
128
+ box-shadow: inset calc(-1 * var(--loidolt-stroke-indicator)) 0 0 var(--loidolt-accent);
129
+ }
130
+ /* With the TabBar out of the grid, the page is the last row and clears the bottom itself. Only a
131
+ full-screen shell has bars at the side, and its page row is `<main>`. */
132
+ :where([data-bar-edge] .ldt-app-shell > main) {
133
+ padding-bottom: var(--ldt-safe-bottom, env(safe-area-inset-bottom, 0px));
134
+ }
135
+
136
+ /*
137
+ * The fold (`data-fold`, with `--ldt-fold-start` and `--ldt-fold-end`), while the device is partly
138
+ * open. Taps over it may not register, so what the theme centres on the screen moves to one side
139
+ * of it, as the system's alerts and sheets do: the first half, or the second for what already
140
+ * sits at the end (toasts). Side drawers stop short of it.
141
+ */
142
+ :where([data-fold='vertical'] .ldt-dialog) {
143
+ left: calc(var(--ldt-fold-start) / 2);
144
+ width: min(var(--ldt-dialog-width, 34rem), calc(var(--ldt-fold-start) - 2rem));
145
+ }
146
+ :where([data-fold='horizontal'] .ldt-dialog) {
147
+ top: calc(var(--ldt-fold-start) / 2);
148
+ max-height: calc(var(--ldt-fold-start) - 2rem);
149
+ }
150
+ :where([data-fold='vertical'] :is(.ldt-drawer--top, .ldt-drawer--bottom)) {
151
+ right: auto;
152
+ width: var(--ldt-fold-start);
153
+ /* It no longer reaches the right edge, so there is no inset there to clear. */
154
+ padding-right: 0;
155
+ }
156
+ :where([data-fold='vertical'] .ldt-drawer--left) {
157
+ width: min(var(--ldt-drawer-size, 20rem), var(--ldt-fold-start));
158
+ }
159
+ :where([data-fold='vertical'] .ldt-drawer--right) {
160
+ width: min(var(--ldt-drawer-size, 20rem), calc(100vw - var(--ldt-fold-end)));
161
+ }
162
+ :where([data-fold='horizontal'] .ldt-drawer--top) {
163
+ height: min(var(--ldt-drawer-size, 20rem), var(--ldt-fold-start));
164
+ }
165
+ :where([data-fold='horizontal'] .ldt-drawer--bottom) {
166
+ height: min(var(--ldt-drawer-size, 20rem), calc(100dvh - var(--ldt-fold-end)));
167
+ }
168
+ :where([data-fold='vertical'] .ldt-toast-viewport) {
169
+ width: min(
170
+ 24rem,
171
+ calc(
172
+ 100vw - var(--ldt-fold-end) - 2rem - var(--ldt-safe-right, env(safe-area-inset-right, 0px))
173
+ )
174
+ );
175
+ }
176
+
50
177
  /*
51
178
  * Native touch manners (`data-native-platform`, written by `markNativePlatform`): no grey flash
52
179
  * 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.13.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.13.0",
45
+ "@loidolt/theme-tokens": "^0.13.0"
39
46
  },
40
47
  "peerDependencies": {
41
48
  "@capacitor/app": "^8.0.0",