@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 +21 -0
- package/README.md +521 -2
- package/dist/deep-links.d.ts +23 -0
- package/dist/deep-links.js +62 -0
- package/dist/file-drop.svelte.d.ts +62 -0
- package/dist/file-drop.svelte.js +100 -0
- package/dist/files.d.ts +130 -0
- package/dist/files.js +241 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.js +10 -0
- package/dist/menu-bar.svelte.d.ts +129 -0
- package/dist/menu-bar.svelte.js +439 -0
- package/dist/notifications.svelte.d.ts +67 -0
- package/dist/notifications.svelte.js +100 -0
- package/dist/platform.d.ts +37 -0
- package/dist/platform.js +102 -0
- package/dist/setup.d.ts +135 -0
- package/dist/setup.js +91 -0
- package/dist/single-instance.d.ts +34 -0
- package/dist/single-instance.js +69 -0
- package/dist/styles.css +35 -0
- package/dist/tray.d.ts +68 -0
- package/dist/tray.js +118 -0
- package/dist/types.d.ts +203 -0
- package/dist/types.js +8 -0
- package/dist/window.svelte.d.ts +102 -0
- package/dist/window.svelte.js +158 -0
- package/package.json +92 -4
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
|
-
#
|
|
1
|
+
# @loidolt/theme-tauri
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
}
|