@loidolt/theme-tauri 0.0.0-stage → 0.12.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Chris Loidolt
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,522 @@
1
- # Temporary Holding Version
1
+ # @loidolt/theme-tauri
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [Tauri 2](https://tauri.app) adapters that carry the Loidolt theme into desktop apps. The
4
+ components already render well in a window; these make them behave like the desktop around them.
5
+
6
+ - **Knows where it runs.** `isTauri()` and `tauriPlatform()` tell a Tauri window from a browser,
7
+ and macOS from Windows and Linux, without loading the Tauri runtime.
8
+ - **Desktop manners.** Inside a window, `<html>` carries `data-tauri-platform`, and the stylesheet
9
+ stops clicks and drags across the app's chrome from selecting button and tab labels, as in a
10
+ native window. Content stays selectable.
11
+ - **Window chrome.** The window's background and light or dark appearance follow the theme, it
12
+ opens without a white flash, and under a macOS overlay title bar the page clears the window
13
+ buttons. `Topbar` drags the window.
14
+ - **Inert on the web.** Every adapter checks for a Tauri window first, so the same root layout
15
+ ships to the browser and to the server unchanged.
16
+
17
+ Tauri modules are passed in, never imported: install only the plugins you want, and each adapter
18
+ turns on when you hand it its module. Their typings are checked against the real packages in this
19
+ repository's test suite.
20
+
21
+ ## Install
22
+
23
+ ```sh
24
+ npm install @loidolt/theme-tauri
25
+ ```
26
+
27
+ `@tauri-apps/api` 2 and the plugins below are optional peer dependencies. Add whichever you want
28
+ adapters for, together with the matching Rust crate in `src-tauri`:
29
+
30
+ ```sh
31
+ npm install @tauri-apps/plugin-os
32
+ ```
33
+
34
+ | Module | Turns on |
35
+ | ------------------------------------------- | ---------------------------------------------------------------- |
36
+ | `@tauri-apps/api` (`getCurrentWindow`) | Window background, appearance, overlay title bar, hidden launch |
37
+ | `@tauri-apps/plugin-os` | The platform read from Rust instead of the web view's user agent |
38
+ | `@tauri-apps/plugin-notification` | OS notifications from Rust, in `desktop.notifications` |
39
+ | `@tauri-apps/api` (`event`, `tray`, `menu`) | Second launches, and a tray icon with a menu |
40
+ | `@tauri-apps/plugin-deep-link` | URLs that open the app, routed into it |
41
+ | `@tauri-apps/plugin-dialog`, `plugin-fs` | Native open and save dialogs, and files dropped on the window |
42
+ | `@tauri-apps/api` (`menu`) | The native menu bar, built from a command registry |
43
+
44
+ ## Set up
45
+
46
+ **1. The stylesheet**, after the theme's:
47
+
48
+ ```css
49
+ @import '@loidolt/theme-svelte/styles.css';
50
+ @import '@loidolt/theme-tauri/styles.css';
51
+ ```
52
+
53
+ **2. The root layout:**
54
+
55
+ ```svelte
56
+ <script lang="ts">
57
+ import { getCurrentWindow } from '@tauri-apps/api/window';
58
+ import * as os from '@tauri-apps/plugin-os';
59
+ import { setupTauri } from '@loidolt/theme-tauri';
60
+ import { theme } from '$lib/theme'; // the app's createTheme()
61
+
62
+ const desktop = setupTauri({ plugins: { os, window: getCurrentWindow }, theme });
63
+
64
+ let { children } = $props();
65
+ </script>
66
+
67
+ {@render children()}
68
+ ```
69
+
70
+ Every module is optional: `setupTauri()` with no arguments reads the platform from the user agent.
71
+ `desktop.platform` is `'macos'`, `'windows'`, `'linux'` (or `'ios'`, `'android'` for Tauri's
72
+ mobile targets), or `null` in a browser. `desktop.ready` settles once every adapter that needs a
73
+ round trip to Rust has applied, and `desktop.destroy()` removes everything; it runs on its own
74
+ when `setupTauri` is called during component initialisation.
75
+
76
+ `markPlatform: false` leaves `<html>` alone.
77
+
78
+ ## Window chrome
79
+
80
+ Give `setupTauri` the window and the window follows the page. Pass `getCurrentWindow` from
81
+ `@tauri-apps/api/window` uncalled: it reads the Tauri runtime and throws in a browser, so
82
+ `setupTauri` calls it only inside a window. (The standalone exports below take the window itself;
83
+ check `isTauri()` before calling `getCurrentWindow()` for them.)
84
+
85
+ - **Background.** The window is filled with the page's live `background` colour, which is what
86
+ shows before the first frame and while a window resizes, and it follows every theme and preset
87
+ change. `appearance: { backgroundRole: 'surface' }` picks another role.
88
+ - **Appearance.** With `theme` (the app's `createTheme` store), an explicit light or dark choice
89
+ reaches the native window: menus, dialogs and scroll bars match. `system` hands the appearance
90
+ back to the OS. Without `theme` the appearance is left to the OS, since pinning it from the page
91
+ would also pin the web view's `prefers-color-scheme`.
92
+ - **No white flash.** Start the window hidden and give it the theme's launch colour.
93
+ `setupTauri` shows it once the window has its colours and the fonts are in (or after 3 s), and
94
+ `desktop.ready` settles after that. `show: false` leaves showing to you;
95
+ `show: { waitForFonts: false, timeout: 1000 }` tunes the wait.
96
+ - **Overlay title bar.** On macOS, `chrome: { titleBar: 'overlay' }` makes room for the window
97
+ buttons under a transparent title bar through the theme's safe-area knobs, and gives the room
98
+ back in full screen, where they hide. By default `--ldt-safe-top` reserves a 28px strip for
99
+ them, which `Topbar` grows by and drawers and toasts clear. `trafficLights: 'beside'` puts them
100
+ in the `Topbar` row instead, inset from the left by 78px (`--ldt-safe-left` on the bar only);
101
+ move them into the bar's middle with `trafficLightPosition`. `top` and `left` change the room.
102
+ `<html>` carries `data-tauri-traffic-lights` while the buttons show. A no-op on Windows and
103
+ Linux.
104
+ - **Dragging.** `<Topbar dragRegion>` sets `data-tauri-drag-region` on the bar, so it moves the
105
+ window like a title bar; its buttons, links and fields stay clickable.
106
+
107
+ ```jsonc
108
+ // src-tauri/tauri.conf.json, in app.windows[0]
109
+ {
110
+ "visible": false,
111
+ "backgroundColor": "#ebe7dc", // windowBackground('light'); '#161814' for a dark-first app
112
+ "titleBarStyle": "Overlay",
113
+ "hiddenTitle": true,
114
+ }
115
+ ```
116
+
117
+ ```svelte
118
+ <script lang="ts">
119
+ const desktop = setupTauri({
120
+ plugins: { window: getCurrentWindow },
121
+ theme,
122
+ chrome: { titleBar: 'overlay' },
123
+ });
124
+ </script>
125
+
126
+ <Topbar dragRegion>…</Topbar>
127
+ ```
128
+
129
+ Each window call needs its permission in the capability file, on top of `core:default`:
130
+
131
+ ```json
132
+ "permissions": [
133
+ "core:default",
134
+ "core:window:allow-set-background-color",
135
+ "core:window:allow-set-theme",
136
+ "core:window:allow-show",
137
+ "core:window:allow-start-dragging"
138
+ ]
139
+ ```
140
+
141
+ A refused call is swallowed, and the window is still shown, so a missing permission costs the
142
+ effect, never the app. `appearance`, `chrome` and `show` each take `false` to turn one off.
143
+
144
+ ## Notifications
145
+
146
+ ```svelte
147
+ <script lang="ts">
148
+ import * as notification from '@tauri-apps/plugin-notification';
149
+ import { setupTauri } from '@loidolt/theme-tauri';
150
+ import { toaster } from '$lib/app'; // the app's createToaster(), optional
151
+
152
+ const desktop = setupTauri({ plugins: { notification }, notifications: { toaster } });
153
+ </script>
154
+
155
+ <button onclick={() => desktop.notifications?.requestPermission()}>Turn on notifications</button>
156
+ ```
157
+
158
+ ```ts
159
+ // later, from anywhere, for example when a background job ends:
160
+ const shown = await desktop.notifications?.notify({
161
+ title: 'Export finished',
162
+ body: 'The file is ready in your downloads.',
163
+ });
164
+ ```
165
+
166
+ `desktop.notifications` (or `createNotifications({ plugin, toaster })` on its own) picks the best
167
+ way out once, as `backend`:
168
+
169
+ - **`'tauri'`**: inside a window, with `@tauri-apps/plugin-notification` passed in. Register
170
+ `tauri_plugin_notification::init()` in `src-tauri/src/lib.rs` and allow `notification:default`
171
+ in the capability file.
172
+ - **`'web'`**: in a browser, or a window without the plugin, through the Web Notifications API.
173
+ - **`'none'`**: neither, as on the server.
174
+
175
+ `permission` is reactive: `'granted'`, `'denied'`, `'default'` (not asked yet) or `'unsupported'`.
176
+ `requestPermission()` asks only while it is `'default'` and resolves the new state; it never
177
+ throws. In a browser, call it from a click or key handler: browsers ignore, or permanently block,
178
+ a prompt that no user gesture asked for. `notify()` never prompts, so background work can call it
179
+ freely; it resolves `true` when the notification reached the OS. Whatever it cannot show (no
180
+ permission, no API, or a browser like Android Chrome that only notifies through a service worker)
181
+ becomes an `info` toast when a `toaster` was given, and it still resolves `false`.
182
+
183
+ `notifications: false` leaves `desktop.notifications` out.
184
+
185
+ ## Running in the background
186
+
187
+ For an app that keeps working with its window closed: one instance, links that open it, and a
188
+ tray icon.
189
+
190
+ ```svelte
191
+ <script lang="ts">
192
+ import { goto } from '$app/navigation';
193
+ import { defaultWindowIcon } from '@tauri-apps/api/app';
194
+ import * as event from '@tauri-apps/api/event';
195
+ import * as menu from '@tauri-apps/api/menu';
196
+ import * as tray from '@tauri-apps/api/tray';
197
+ import * as deepLink from '@tauri-apps/plugin-deep-link';
198
+ import { isTauri, setupTauri } from '@loidolt/theme-tauri';
199
+
200
+ const desktop = setupTauri({
201
+ plugins: { event, deepLink, tray, menu },
202
+ singleInstance: { onSecondInstance: ({ files }) => files.forEach(openFile) },
203
+ deepLinks: { navigate: goto },
204
+ tray: {
205
+ icon: isTauri() ? defaultWindowIcon() : null,
206
+ tooltip: 'Watching for new files',
207
+ items: [{ id: 'show', label: 'Show window', action: showWindow }, 'separator', 'quit'],
208
+ onClick: showWindow,
209
+ },
210
+ });
211
+ </script>
212
+ ```
213
+
214
+ Each piece is on only when its module and its options are both given, and does nothing in a
215
+ browser. They are also exported on their own: `handleSecondInstance`, `handleDeepLinks` and
216
+ `createTray`, each returning its teardown (`createTray` an object with `destroy()`).
217
+
218
+ ### Single instance
219
+
220
+ `tauri-plugin-single-instance` has no JavaScript side. Register it **first** in
221
+ `src-tauri/src/lib.rs`, with a callback that focuses the running window and emits the second
222
+ launch as an event:
223
+
224
+ ```rust
225
+ use tauri::{Emitter, Manager};
226
+
227
+ #[derive(Clone, serde::Serialize)]
228
+ struct SecondInstance { args: Vec<String>, cwd: String }
229
+
230
+ tauri::Builder::default()
231
+ .plugin(tauri_plugin_single_instance::init(|app, args, cwd| {
232
+ if let Some(window) = app.get_webview_window("main") {
233
+ let _ = window.unminimize();
234
+ let _ = window.show();
235
+ let _ = window.set_focus();
236
+ }
237
+ let _ = app.emit("single-instance", SecondInstance { args, cwd });
238
+ }))
239
+ ```
240
+
241
+ `singleInstance: { onSecondInstance }` (or `handleSecondInstance({ event, onSecondInstance })`)
242
+ listens for it and calls back with `{ args, cwd, files }`. `files` are the paths in `args`:
243
+ everything after the executable that is not a flag or a URL, resolved against `cwd`
244
+ (`filesFromArgs(args, cwd)` does the same on its own). Rust may send `files` itself; on macOS,
245
+ which keeps one instance on its own, files opened from the Finder while the app runs arrive as
246
+ `RunEvent::Opened`, and `examples/tauri` forwards those as the same event. `eventName` changes
247
+ `'single-instance'`.
248
+
249
+ ### Deep links
250
+
251
+ Pass `@tauri-apps/plugin-deep-link` (`tauri_plugin_deep_link::init()`, `deep-link:default`) and
252
+ `deepLinks: { navigate }`: the link that launched the app is read once at startup, and every link
253
+ that arrives while it runs follows. `deepLinkPath` turns `myapp://projects/42` into
254
+ `/projects/42`; `resolve` replaces it (return `null` to skip one), and `onUrl` sees every raw URL.
255
+
256
+ Declare the scheme in `tauri.conf.json`:
257
+
258
+ ```json
259
+ { "plugins": { "deep-link": { "desktop": { "schemes": ["myapp"] } } } }
260
+ ```
261
+
262
+ On macOS the scheme is registered from the bundle's `Info.plist`, so links only open a built and
263
+ installed app (`tauri build`), not `tauri dev`. On Windows and Linux, call
264
+ `app.deep_link().register_all()` in `setup` for development, and enable the `deep-link` feature of
265
+ `tauri-plugin-single-instance` so a link opened while the app runs reaches the running instance
266
+ instead of starting a second one.
267
+
268
+ ### Tray icon
269
+
270
+ Pass `@tauri-apps/api/tray` and `@tauri-apps/api/menu` (and enable the `tray-icon` feature of the
271
+ `tauri` crate) with `tray` options, and `desktop.tray` is an icon in the menu bar or system tray:
272
+ `icon` (a path, bytes, an `Image`, or a promise of one such as `defaultWindowIcon()`), `tooltip`,
273
+ `title` (macOS, beside the icon), and `items`, a list of `{ id, label, enabled?, action? }`,
274
+ `'separator'` or `'quit'` (the platform's own Quit item; not on Linux). `onClick` handles a left
275
+ click on the icon, and then the menu opens on a right click only.
276
+
277
+ `desktop.tray.update({ tooltip, title, icon, items })` changes what it is given, and teardown
278
+ removes the icon and frees its menu.
279
+
280
+ ## Files
281
+
282
+ Native open and save dialogs, and files dropped on the window, both handed over as `File`s: the
283
+ same objects a `Dropzone` or `FileInput` gives you, so one upload path serves the browser and the
284
+ window.
285
+
286
+ ```sh
287
+ npm install @tauri-apps/plugin-dialog @tauri-apps/plugin-fs
288
+ ```
289
+
290
+ Register both plugins in `src-tauri/src/lib.rs` (`.plugin(tauri_plugin_dialog::init())` and
291
+ `.plugin(tauri_plugin_fs::init())`) and allow them in the capability file:
292
+
293
+ ```json
294
+ "permissions": ["core:default", "dialog:default", "fs:allow-read-file", "fs:allow-write-file"]
295
+ ```
296
+
297
+ No fs scope is needed for this: a path chosen in a dialog, and a path dropped on the window, is
298
+ added to the fs scope at run time by the plugins themselves. (`scopeDroppedPaths: false` under
299
+ `plugins.fs` in `tauri.conf.json` turns that off for drops.) Grant wider scopes only for paths the
300
+ app reads on its own.
301
+
302
+ ```svelte
303
+ <script lang="ts">
304
+ import { getCurrentWebview } from '@tauri-apps/api/webview';
305
+ import * as dialog from '@tauri-apps/plugin-dialog';
306
+ import * as fs from '@tauri-apps/plugin-fs';
307
+ import { Dropzone } from '@loidolt/theme-svelte';
308
+ import { setupTauri } from '@loidolt/theme-tauri';
309
+
310
+ let dropzone = $state<ReturnType<typeof Dropzone>>();
311
+
312
+ const desktop = setupTauri({
313
+ plugins: { dialog, fs, webview: getCurrentWebview },
314
+ fileDrop: { target: () => dropzone },
315
+ });
316
+
317
+ async function openFiles() {
318
+ const files = (await desktop.files?.pick({ accept: '.pdf,image/*', multiple: true })) ?? [];
319
+ dropzone?.addFiles(files);
320
+ }
321
+ </script>
322
+
323
+ <Dropzone
324
+ bind:this={dropzone}
325
+ accept=".pdf,image/*"
326
+ multiple
327
+ window
328
+ externalDragging={desktop.fileDrop?.dragging}
329
+ onFiles={upload}
330
+ />
331
+ <button onclick={openFiles}>Open…</button>
332
+ <button onclick={() => desktop.files?.save(new File([bytes], 'export.pdf'))}>Save…</button>
333
+ ```
334
+
335
+ ### Open and save
336
+
337
+ `desktop.files` (or `createDesktopFiles({ dialog, fs })` on its own) has the same shape as
338
+ `createFiles` in `@loidolt/theme-capacitor`, so an app can treat both alike:
339
+
340
+ - **`pick({ accept, multiple, title, defaultPath, filters })`** opens the native dialog and resolves
341
+ the chosen files as `File`s, named and typed by their extension, each with the `path` it was read
342
+ from. `accept` is written as for `<input accept>` and becomes the dialog's filters (`.pdf` →
343
+ `pdf`, `image/*` → every known image extension; `acceptToFilters` does the same on its own); a
344
+ MIME type it has no extension for means no filter rather than nothing pickable. `filters`, as
345
+ Tauri takes them, replaces it. Dismissing the dialog resolves `[]`.
346
+ - **`pickPaths({ …, directory })`** resolves the chosen paths without reading them, folders with
347
+ `directory: true`. A browser has no paths to give, so it resolves `[]` there.
348
+ - **`save(file, { defaultPath, filters, title })`** takes a `File` or `{ blob, name }`, opens the
349
+ save dialog with the name filled in (and, by default, a filter for its extension, which on macOS
350
+ keeps the extension on whatever the user types), and writes it there. It resolves
351
+ `{ method: 'filesystem', path }`, or `{ method: 'cancelled' }` when the dialog is dismissed.
352
+
353
+ In a browser `pick` opens a hidden file input (call it from a click) and `save` downloads,
354
+ resolving `{ method: 'download', name }`. In a window without the plugins `pick` uses the web
355
+ view's own file input, and `save` throws, since a web view has no download manager. On the server
356
+ `pick` resolves `[]` and `save` `{ method: 'none' }`. `files: false` leaves `desktop.files` out.
357
+
358
+ **Large files.** `readFile` and `writeFile` cross the IPC bridge whole, so a picked, dropped or
359
+ saved file is held in memory in full, once as bytes and once as the `File`. That is fine for
360
+ documents and images; for video, archives or anything in the hundreds of megabytes, use
361
+ `pickPaths()` or `onPaths` and hand the paths to a Rust command that streams them.
362
+
363
+ ### Files dropped on the window
364
+
365
+ A Tauri window takes files dragged in from the OS before the page sees them, so the page's HTML
366
+ drag and drop events never fire for them, and a `Dropzone` alone never hears of the drop.
367
+ `fileDrop` (or `createFileDrop({ webview, fs, … })` on its own) listens to the web view's drag and
368
+ drop event instead. Pass `getCurrentWebview` from `@tauri-apps/api/webview` uncalled, as with
369
+ `window`.
370
+
371
+ - **`target`** is where the files go: a `Dropzone` instance (`bind:this`), or a function returning
372
+ one, read at drop time. Its `addFiles()` runs them through its own `accept`, `maxSize` and
373
+ `maxFiles`, its messages and its `onFiles`, as for a drop of its own.
374
+ - **`desktop.fileDrop.dragging`** is reactive while files are over the window, and `paths` holds
375
+ them. Pass it to the `Dropzone`'s `externalDragging` and it shows the same window overlay as for
376
+ a browser drag.
377
+ - **`onFiles`** gets the read files first, **`onPaths`** the raw paths before anything is read,
378
+ and **`onError`** each path that could not be read, such as a dropped folder; the rest still
379
+ arrive.
380
+
381
+ Keep `window` on the `Dropzone`: in a browser that is what takes drops anywhere on the page, and in
382
+ a window it does nothing, because the HTML events do not fire there.
383
+
384
+ **`dragDropEnabled`.** The window's `dragDropEnabled` (on by default in `tauri.conf.json`) is what
385
+ routes OS drops to Tauri. It also stops HTML drag and drop of any kind inside the page on Windows,
386
+ which breaks sortable lists and the like. To keep HTML drag and drop instead, set
387
+ `"dragDropEnabled": false` on the window: Tauri then reports no drops, `fileDrop` stays idle, and
388
+ the `Dropzone`'s own `window` handling takes the drop as in a browser, as `File`s without paths.
389
+
390
+ ## Menu bar
391
+
392
+ The native menu bar, built from the app's command registry (`createCommands` from
393
+ `@loidolt/theme-svelte`): pass `@tauri-apps/api/menu` and `menuBar: { commands }`, and
394
+ `desktop.menuBar` keeps the menus in step with the registry.
395
+
396
+ ```svelte
397
+ <script lang="ts">
398
+ import * as menu from '@tauri-apps/api/menu';
399
+ import { createCommands } from '@loidolt/theme-svelte';
400
+ import { setupTauri } from '@loidolt/theme-tauri';
401
+
402
+ const commands = createCommands();
403
+ commands.registerAll([
404
+ { id: 'new', label: 'New note', shortcut: 'Mod+N', group: 'File', handler: create },
405
+ {
406
+ id: 'save',
407
+ label: 'Save',
408
+ shortcut: 'Mod+S',
409
+ group: 'File',
410
+ enabled: () => dirty,
411
+ handler: save,
412
+ },
413
+ { id: 'zoom-in', label: 'Zoom in', shortcut: 'Mod+=', group: 'View', handler: zoomIn },
414
+ ]);
415
+ $effect(() => commands.listen());
416
+
417
+ const desktop = setupTauri({ plugins: { menu }, menuBar: { commands, appName: 'Notes' } });
418
+ </script>
419
+ ```
420
+
421
+ - **One menu per group**, in the order the groups first appear; commands without a group go in a
422
+ Commands menu (`labels.commands`). Each command is an item with its label, its first shortcut as
423
+ the accelerator (`Mod+S` shows as ⌘S on a Mac and Ctrl+S elsewhere), and its enabled state.
424
+ Choosing it runs `commands.execute(id)`.
425
+ - **In step.** Registering, unregistering and `commands.update()` reach the menu, and so does an
426
+ `enabled` function that reads `$state`. A new label, enabled state or shortcut is changed on the
427
+ item in place; a command coming or going rebuilds the menu. Changes are gathered for `debounce`
428
+ ms (16) first. For an `enabled` that reads something else, call `desktop.menuBar.refresh()`.
429
+ - **macOS manners.** The bar starts with the app menu (About, Services, Hide, Hide Others, Show
430
+ All, Quit) and has an Edit menu (Undo, Redo, Cut, Copy, Paste, Select All) and a Window menu
431
+ (Minimize, Zoom, Close Window), all items the OS provides. Without the Edit menu the clipboard
432
+ shortcuts do nothing in a macOS web view. The order is app, File, Edit, the other groups, Window,
433
+ Help; groups named Edit and Window join the standard menus, and a Help group becomes the system
434
+ Help menu. `appMenu: false`, `editMenu: false` and `windowMenu: false` leave one out.
435
+ - **Windows and Linux** get the registry's groups alone, on the window the page runs in (Tauri's
436
+ `setAsWindowMenu`: a menu bar belongs to a window there). `target: 'app'` puts it on every window
437
+ without a menu of its own instead, and `platforms: ['macos']` keeps Windows and Linux bare.
438
+ - **Plain keys stay with the page.** Only a chord (with Mod, Ctrl, Meta or Alt) or a function key
439
+ becomes an accelerator; `?` or `J` would fire while typing. `menuAccelerator(command)` says
440
+ what an item gets.
441
+ - **`layout`** sees the menus before they are built, `{ id, label, items }` each, and returns the
442
+ menus to build: move a command into the app menu, add a predefined item, drop a group. Items
443
+ are `{ command: id }`, `{ predefined: 'Fullscreen', label? }` or `'separator'`; stray separators
444
+ are tidied away, and a command placed twice appears only at its first place.
445
+
446
+ ```ts
447
+ menuBar: {
448
+ commands,
449
+ layout: (menus) => {
450
+ // Settings… under About, as macOS apps have it; it then stays out of its own group's menu
451
+ menus.find((menu) => menu.id === 'app')?.items.splice(1, 0, 'separator', { command: 'settings' });
452
+ // a group kept out of the bar
453
+ return menus.filter((menu) => menu.id !== 'group:Debug');
454
+ },
455
+ }
456
+ ```
457
+
458
+ Menu ids are `'app'`, `'edit'`, `'window'`, `'help'`, `'commands'` and `group:<name>`.
459
+ `labels` translates the headings (`edit`, `window`, `commands`, and `file` and `help`, the group
460
+ names placed first and last on macOS) and the built-in items (`about`, `quit`, `copy`, …; unset,
461
+ Tauri's own text). `&` in a label is shown as is.
462
+
463
+ **One keystroke, one run.** The registry's own listener and the menu accelerator never both run a
464
+ command for the same key. On macOS, WebKit gives the page the key first and passes the menu only
465
+ what the page did not `preventDefault`, so a shortcut the registry handled stops there, and one
466
+ it left alone — a command without `allowInInputs` while the user types in a field, say — runs from
467
+ the menu, as a native menu item would. For web views that deliver both, the menu bar remembers the
468
+ last keystroke the page handled and skips the menu action it causes, and the other way round.
469
+ Which side sees a key first differs between web views, so keep `commands.listen()` on: it runs
470
+ the shortcuts wherever the menu does not see the key, and in a browser.
471
+
472
+ `desktop.destroy()` (or `createMenuBar(…).destroy()`) puts back the menu bar that was there before,
473
+ Tauri's default on macOS, or leaves an empty one on a window that had none. The menu calls are in
474
+ `core:default`. In a browser and on the server it does nothing.
475
+
476
+ ## Exports
477
+
478
+ Each piece is also exported on its own. Every one is a no-op outside a Tauri window, except
479
+ `createNotifications`, which falls back to the Web Notifications API.
480
+
481
+ | Export | Does |
482
+ | ---------------------- | ------------------------------------------------------------------------------------------- |
483
+ | `setupTauri` | Every adapter in one call; returns `platform`, `ready` and `destroy()` |
484
+ | `isTauri` | Whether the page runs in a Tauri 2 window (`window.isTauri` or `__TAURI_INTERNALS__`) |
485
+ | `tauriPlatform` | `'macos'`, `'windows'`, `'linux'`, `'ios'`, `'android'` or `null` |
486
+ | `markTauriPlatform` | `data-tauri-platform` on `<html>` (or an element), for platform-specific CSS |
487
+ | `syncWindowAppearance` | The window background in the live page colour, and with `theme`, its appearance |
488
+ | `insetWindowChrome` | Insets the page clear of the macOS window buttons under an overlay title bar |
489
+ | `showWindow` | Shows a window that starts hidden once the theme and fonts are in |
490
+ | `windowBackground` | The theme's launch colour, for `backgroundColor` in `tauri.conf.json` |
491
+ | `createNotifications` | `permission`, `requestPermission()` and `notify()`; the Web Notifications API outside Tauri |
492
+ | `handleSecondInstance` | Second launches forwarded by `tauri-plugin-single-instance`, with their files |
493
+ | `filesFromArgs` | The file paths in a command line, resolved against its working directory |
494
+ | `handleDeepLinks` | Links that open the app, at startup and while it runs, into its router |
495
+ | `deepLinkPath` | `myapp://projects/42` → `/projects/42` |
496
+ | `createTray` | A tray icon with a menu, `update()` and `destroy()` |
497
+ | `createDesktopFiles` | `pick()`, `pickPaths()`, `save()`: native dialogs, or a file input and a download |
498
+ | `createFileDrop` | Files dropped on the window, as `File`s into a `Dropzone`, with a reactive `dragging` |
499
+ | `acceptToFilters` | An `accept` string as the dialog filters Tauri takes |
500
+ | `readDesktopFiles` | Paths read into `File`s typed by extension (`readDesktopFile` for one) |
501
+ | `mimeTypeOf` | The MIME type for a file name by its extension |
502
+ | `createMenuBar` | The native menu bar from a command registry, kept in step; `refresh()` and `destroy()` |
503
+ | `menuAccelerator` | The accelerator a command gets in the menu bar, or `null` for a plain key |
504
+ | `isMenuBarModule` | Whether a `menu` module can build a menu bar (not only a tray menu) |
505
+
506
+ `isTauri` reads the same global as `isTauri()` from `@tauri-apps/api/core`, so the two agree; this
507
+ one never loads the Tauri runtime, which keeps it safe in a server bundle.
508
+
509
+ ### Styles
510
+
511
+ `styles.css` is zero-specificity throughout, so your own CSS always wins, and inert in a browser:
512
+ every rule keys to `data-tauri-platform`.
513
+
514
+ - Under `data-tauri-platform`: buttons, switches, tabs, toggle groups, navigation and the topbar
515
+ do not select their labels.
516
+ - Under `data-tauri-traffic-lights="beside"`: the topbar is inset from the left to clear the
517
+ window buttons.
518
+
519
+ ## Example app
520
+
521
+ [`examples/tauri`](../../examples/tauri) is a minimal Tauri 2 app on this package, for trying the
522
+ adapters in a real window. It needs Rust; see its README.
@@ -0,0 +1,23 @@
1
+ import type { DeepLinkPlugin, Teardown } from './types.js';
2
+ /**
3
+ * The in-app path for a URL that opened the app. An `https://` link keeps its path; a custom
4
+ * scheme has no host in the usual sense, so `myapp://projects/42` becomes `/projects/42`. Query
5
+ * and hash are kept. `null` for something that is not a URL, and for a `file:` URL: on macOS a
6
+ * file opened from the Finder arrives the same way, and it is not a route.
7
+ */
8
+ export declare function deepLinkPath(url: string): string | null;
9
+ export interface DeepLinkOptions {
10
+ /** `@tauri-apps/plugin-deep-link`. */
11
+ deepLink: DeepLinkPlugin;
12
+ /** Your router's navigation — `goto` in SvelteKit — called with each link's in-app path. */
13
+ navigate?: (path: string) => void;
14
+ /** Called with each raw URL, before `navigate`. */
15
+ onUrl?: (url: string) => void;
16
+ /** Turns a URL into an in-app path, or `null` to skip `navigate`. Defaults to {@link deepLinkPath}. */
17
+ resolve?: (url: string) => string | null;
18
+ }
19
+ /**
20
+ * Routes the URLs that open the app (`myapp://…`) into its own router: the one that launched it,
21
+ * read once at startup, and every one that arrives while it runs. A no-op outside a Tauri window.
22
+ */
23
+ export declare function handleDeepLinks(options: DeepLinkOptions): Teardown;
@@ -0,0 +1,62 @@
1
+ import { isTauri, listen, noop } from './platform.js';
2
+ /**
3
+ * The in-app path for a URL that opened the app. An `https://` link keeps its path; a custom
4
+ * scheme has no host in the usual sense, so `myapp://projects/42` becomes `/projects/42`. Query
5
+ * and hash are kept. `null` for something that is not a URL, and for a `file:` URL: on macOS a
6
+ * file opened from the Finder arrives the same way, and it is not a route.
7
+ */
8
+ export function deepLinkPath(url) {
9
+ let parsed;
10
+ try {
11
+ parsed = new URL(url);
12
+ }
13
+ catch {
14
+ return null;
15
+ }
16
+ if (parsed.protocol === 'file:')
17
+ return null;
18
+ const web = parsed.protocol === 'http:' || parsed.protocol === 'https:';
19
+ const path = web ? parsed.pathname : `/${parsed.host}${parsed.pathname}`.replace(/\/{2,}/g, '/');
20
+ return `${path || '/'}${parsed.search}${parsed.hash}`;
21
+ }
22
+ /**
23
+ * Routes the URLs that open the app (`myapp://…`) into its own router: the one that launched it,
24
+ * read once at startup, and every one that arrives while it runs. A no-op outside a Tauri window.
25
+ */
26
+ export function handleDeepLinks(options) {
27
+ if (!isTauri())
28
+ return noop;
29
+ const { deepLink, navigate, onUrl, resolve = deepLinkPath } = options;
30
+ let stopped = false;
31
+ let live = false;
32
+ const open = (urls) => {
33
+ if (stopped || !Array.isArray(urls))
34
+ return;
35
+ for (const url of urls) {
36
+ onUrl?.(url);
37
+ const path = navigate ? resolve(url) : null;
38
+ if (path !== null)
39
+ navigate(path);
40
+ }
41
+ };
42
+ let unlisten = noop;
43
+ try {
44
+ unlisten = listen(deepLink.onOpenUrl((urls) => {
45
+ live = true;
46
+ open(urls);
47
+ }));
48
+ deepLink.getCurrent().then(
49
+ // A link that arrived while this was in flight is newer than the one that launched the app.
50
+ (urls) => {
51
+ if (!live)
52
+ open(urls);
53
+ }, () => { });
54
+ }
55
+ catch {
56
+ /* the plugin is installed in JS but not registered in Rust */
57
+ }
58
+ return () => {
59
+ stopped = true;
60
+ unlisten();
61
+ };
62
+ }