@loidolt/theme-tauri 0.0.0-stage → 0.12.1

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.
@@ -0,0 +1,129 @@
1
+ import { type Commands, type RegisteredCommand } from '@loidolt/theme-svelte';
2
+ import type { MenuBarModule, MenuModule, OsPlugin, PredefinedMenuItemName } from './types.js';
3
+ /** The desktop systems with a menu bar. */
4
+ export type MenuBarPlatform = 'macos' | 'windows' | 'linux';
5
+ /** One line of a menu: a registry command by id, an item the OS provides, or a rule. */
6
+ export type MenuBarEntry = {
7
+ command: string;
8
+ } | {
9
+ predefined: PredefinedMenuItemName;
10
+ label?: string;
11
+ } | 'separator';
12
+ /** One heading of the menu bar and what drops down from it. */
13
+ export interface MenuBarMenu {
14
+ /**
15
+ * `'app'`, `'edit'`, `'window'` and `'help'` for the standard menus, `'commands'` for commands
16
+ * registered without a group, and `group:<name>` for every other group.
17
+ */
18
+ id: string;
19
+ label: string;
20
+ items: MenuBarEntry[];
21
+ }
22
+ /** Every string the menu bar shows that is not a command label, for translation. */
23
+ export interface MenuBarLabels {
24
+ /** The standard Edit menu, and the registry group it takes in. Default `'Edit'`. */
25
+ edit?: string;
26
+ /** The standard Window menu, and the registry group it takes in. Default `'Window'`. */
27
+ window?: string;
28
+ /** The registry group placed before Edit on macOS. Default `'File'`. */
29
+ file?: string;
30
+ /** The registry group placed last on macOS, as the system Help menu. Default `'Help'`. */
31
+ help?: string;
32
+ /** The menu for commands registered without a group. Default `'Commands'`. */
33
+ commands?: string;
34
+ /**
35
+ * The built-in items. Unset, each keeps the text Tauri gives it ("About", "Hide Others",
36
+ * "Select All", …).
37
+ */
38
+ about?: string;
39
+ services?: string;
40
+ hide?: string;
41
+ hideOthers?: string;
42
+ showAll?: string;
43
+ quit?: string;
44
+ undo?: string;
45
+ redo?: string;
46
+ cut?: string;
47
+ copy?: string;
48
+ paste?: string;
49
+ selectAll?: string;
50
+ minimize?: string;
51
+ maximize?: string;
52
+ fullscreen?: string;
53
+ closeWindow?: string;
54
+ bringAllToFront?: string;
55
+ }
56
+ export interface MenuBarLayoutContext {
57
+ platform: MenuBarPlatform;
58
+ commands: Commands;
59
+ }
60
+ export interface MenuBarOptions {
61
+ /** `@tauri-apps/api/menu`. */
62
+ menu: MenuBarModule;
63
+ /** The registry the menus are built from: one menu per group, in order. */
64
+ commands: Commands;
65
+ /** macOS: the name in the app menu's About item. */
66
+ appName?: string;
67
+ /** macOS: the app menu (About, Services, Hide, Quit) first. On by default. */
68
+ appMenu?: boolean;
69
+ /**
70
+ * macOS: an Edit menu with Undo, Redo, Cut, Copy, Paste and Select All. On by default: without
71
+ * it the clipboard shortcuts do nothing in a macOS web view. A registry group named Edit joins
72
+ * it.
73
+ */
74
+ editMenu?: boolean;
75
+ /** macOS: a Window menu with Minimize, Zoom and Close Window. On by default. */
76
+ windowMenu?: boolean;
77
+ /**
78
+ * Rearranges the menus before they are built: moves a command into the app menu, drops a
79
+ * group, adds a predefined item. Receives a fresh copy each time, which it may change and
80
+ * return. Reactive state it reads is tracked.
81
+ */
82
+ layout?: (menus: MenuBarMenu[], context: MenuBarLayoutContext) => MenuBarMenu[];
83
+ labels?: MenuBarLabels;
84
+ /**
85
+ * Windows and Linux, where a menu bar belongs to a window: `'window'` (the default) puts it on
86
+ * the window this page runs in, `'app'` on every window that has no menu of its own. macOS has
87
+ * one menu bar for the app and always takes `'app'`.
88
+ */
89
+ target?: 'app' | 'window';
90
+ /** Where to build a menu bar. Default all three; `['macos']` keeps Windows and Linux bare. */
91
+ platforms?: readonly MenuBarPlatform[];
92
+ /** How long changes are gathered before the menu is touched, in ms. Default 16. */
93
+ debounce?: number;
94
+ }
95
+ export interface MenuBar {
96
+ /** Settles once the first menu bar is in place (or failed to get there). Never rejects. */
97
+ readonly ready: Promise<void>;
98
+ /**
99
+ * Re-reads the registry now: for an `enabled` that depends on something other than Svelte
100
+ * state. Changes to the registry and to `$state` are picked up on their own.
101
+ */
102
+ refresh(): Promise<void>;
103
+ /** Puts back the menu bar that was there before, and frees this one. Safe to call twice. */
104
+ destroy(): void;
105
+ }
106
+ /** Whether the module passed as `plugins.menu` can build a menu bar, not just a tray menu. */
107
+ export declare function isMenuBarModule(menu: MenuModule): menu is MenuBarModule;
108
+ /**
109
+ * The accelerator a native menu shows for a command: its first shortcut, if it is a chord or a
110
+ * function key. A plain key (`?`, `J`, `Shift+N`, an arrow) is left to the page: as an
111
+ * accelerator it would fire while the user types.
112
+ */
113
+ export declare function menuAccelerator(command: Pick<RegisteredCommand, 'shortcuts'>): string | null;
114
+ /**
115
+ * The native menu bar, built from a command registry: one menu per group, in registration order,
116
+ * each command an item with its label, its first shortcut as the accelerator, and its enabled
117
+ * state, all kept in step with the registry. Choosing an item runs the command. On macOS the
118
+ * standard app, Edit and Window menus are added around them, so About, Hide, Quit and the
119
+ * clipboard shortcuts work as in any Mac app.
120
+ *
121
+ * ```ts
122
+ * import * as menu from '@tauri-apps/api/menu';
123
+ * const bar = createMenuBar({ menu, commands, appName: 'Notes' });
124
+ * ```
125
+ *
126
+ * A keystroke runs its command once: the page's shortcut listener and the menu accelerator never
127
+ * both act on the same key. A no-op outside a Tauri desktop window.
128
+ */
129
+ export declare function createMenuBar(options: MenuBarOptions, os?: OsPlugin): MenuBar;
@@ -0,0 +1,439 @@
1
+ import { matchesShortcut, toAccelerator, } from '@loidolt/theme-svelte';
2
+ import { untrack } from 'svelte';
3
+ import { isTauri, quietly, tauriPlatform } from './platform.js';
4
+ const inert = { ready: Promise.resolve(), refresh: async () => { }, destroy() { } };
5
+ /** Whether the module passed as `plugins.menu` can build a menu bar, not just a tray menu. */
6
+ export function isMenuBarModule(menu) {
7
+ const pieces = menu;
8
+ return typeof pieces.Submenu?.new === 'function' && typeof pieces.MenuItem?.new === 'function';
9
+ }
10
+ /**
11
+ * The accelerator a native menu shows for a command: its first shortcut, if it is a chord or a
12
+ * function key. A plain key (`?`, `J`, `Shift+N`, an arrow) is left to the page: as an
13
+ * accelerator it would fire while the user types.
14
+ */
15
+ export function menuAccelerator(command) {
16
+ const first = command.shortcuts[0];
17
+ if (!first)
18
+ return null;
19
+ const chord = first.mod || first.ctrl || first.meta || first.alt || /^F\d{1,2}$/.test(first.key);
20
+ return chord ? toAccelerator(first) : null;
21
+ }
22
+ const LABEL_KEYS = {
23
+ About: 'about',
24
+ Services: 'services',
25
+ Hide: 'hide',
26
+ HideOthers: 'hideOthers',
27
+ ShowAll: 'showAll',
28
+ Quit: 'quit',
29
+ Undo: 'undo',
30
+ Redo: 'redo',
31
+ Cut: 'cut',
32
+ Copy: 'copy',
33
+ Paste: 'paste',
34
+ SelectAll: 'selectAll',
35
+ Minimize: 'minimize',
36
+ Maximize: 'maximize',
37
+ Fullscreen: 'fullscreen',
38
+ CloseWindow: 'closeWindow',
39
+ BringAllToFront: 'bringAllToFront',
40
+ };
41
+ const predefined = (names) => names.map((name) => (name === '-' ? 'separator' : { predefined: name }));
42
+ /** The menus a registry makes before `layout` sees them. */
43
+ function defaultMenus(commands, platform, options, labels) {
44
+ const groups = commands.groups().map(({ group, commands: list }) => ({
45
+ id: group === undefined ? 'commands' : `group:${group}`,
46
+ label: group ?? labels.commands,
47
+ items: list.map((command) => ({ command: command.id })),
48
+ }));
49
+ if (platform !== 'macos')
50
+ return groups;
51
+ // The macOS order: app, File, Edit, the rest, Window, Help.
52
+ const take = (label) => {
53
+ const index = groups.findIndex((menu) => menu.id === `group:${label}`);
54
+ return index === -1 ? undefined : groups.splice(index, 1)[0];
55
+ };
56
+ const file = take(labels.file);
57
+ const edit = take(labels.edit);
58
+ const window = take(labels.window);
59
+ const help = take(labels.help);
60
+ const joined = (id, label, standard, group) => standard || group
61
+ ? [
62
+ {
63
+ id,
64
+ label,
65
+ items: [
66
+ ...(standard || []),
67
+ ...(standard && group ? ['separator'] : []),
68
+ ...(group?.items ?? []),
69
+ ],
70
+ },
71
+ ]
72
+ : [];
73
+ return [
74
+ ...(options.appMenu !== false
75
+ ? [
76
+ {
77
+ id: 'app',
78
+ label: options.appName ?? '',
79
+ items: predefined([
80
+ 'About',
81
+ '-',
82
+ 'Services',
83
+ '-',
84
+ 'Hide',
85
+ 'HideOthers',
86
+ 'ShowAll',
87
+ '-',
88
+ 'Quit',
89
+ ]),
90
+ },
91
+ ]
92
+ : []),
93
+ ...(file ? [file] : []),
94
+ ...joined('edit', labels.edit, options.editMenu !== false &&
95
+ predefined(['Undo', 'Redo', '-', 'Cut', 'Copy', 'Paste', 'SelectAll']), edit),
96
+ ...groups,
97
+ ...joined('window', labels.window, options.windowMenu !== false && predefined(['Minimize', 'Maximize', '-', 'CloseWindow']), window),
98
+ ...(help ? [{ ...help, id: 'help' }] : []),
99
+ ];
100
+ }
101
+ /** `&` marks a mnemonic in every native menu; `&&` is a literal one. */
102
+ const escape = (text) => text.replaceAll('&', '&&');
103
+ /** Separators only between items: none leading, trailing or doubled. */
104
+ function tidy(items) {
105
+ const result = [];
106
+ for (const item of items) {
107
+ if (item.kind === 'separator' && (!result.length || result.at(-1).kind === 'separator')) {
108
+ continue;
109
+ }
110
+ result.push(item);
111
+ }
112
+ if (result.at(-1)?.kind === 'separator')
113
+ result.pop();
114
+ return result;
115
+ }
116
+ function plan(menus, commands, labels) {
117
+ // eslint-disable-next-line svelte/prefer-svelte-reactivity -- bookkeeping, never rendered
118
+ const seen = new Set();
119
+ const planned = [];
120
+ for (const menu of menus) {
121
+ const items = tidy(menu.items.flatMap((entry) => {
122
+ if (entry === 'separator')
123
+ return [{ kind: 'separator' }];
124
+ if ('predefined' in entry) {
125
+ const key = LABEL_KEYS[entry.predefined];
126
+ return [
127
+ {
128
+ kind: 'predefined',
129
+ item: entry.predefined,
130
+ text: entry.label ?? (key ? labels[key] : undefined),
131
+ },
132
+ ];
133
+ }
134
+ const command = commands.get(entry.command);
135
+ // A command placed twice is built once: one native item has one place.
136
+ if (!command || seen.has(command.id))
137
+ return [];
138
+ seen.add(command.id);
139
+ return [
140
+ {
141
+ kind: 'command',
142
+ id: command.id,
143
+ text: escape(command.label),
144
+ enabled: commands.isEnabled(command.id),
145
+ accelerator: menuAccelerator(command),
146
+ },
147
+ ];
148
+ }));
149
+ if (items.length)
150
+ planned.push({ id: menu.id, text: escape(menu.label), items });
151
+ }
152
+ const structure = JSON.stringify(planned.map((menu) => [
153
+ menu.id,
154
+ menu.items.map((item) => item.kind === 'command'
155
+ ? `c:${item.id}`
156
+ : item.kind === 'predefined'
157
+ ? `p:${item.item}:${item.text ?? ''}`
158
+ : '-'),
159
+ ]));
160
+ return { structure, menus: planned };
161
+ }
162
+ /**
163
+ * How long a keystroke the page handled and a menu action for the same command count as one:
164
+ * well past the round trip a menu action takes to reach the page.
165
+ */
166
+ const SAME_KEYSTROKE_MS = 500;
167
+ /**
168
+ * The other way round, a menu action and then the keydown, is kept short: a second press of the
169
+ * same chord a moment later is a press of its own.
170
+ */
171
+ const MENU_THEN_KEY_MS = 100;
172
+ /**
173
+ * The native menu bar, built from a command registry: one menu per group, in registration order,
174
+ * each command an item with its label, its first shortcut as the accelerator, and its enabled
175
+ * state, all kept in step with the registry. Choosing an item runs the command. On macOS the
176
+ * standard app, Edit and Window menus are added around them, so About, Hide, Quit and the
177
+ * clipboard shortcuts work as in any Mac app.
178
+ *
179
+ * ```ts
180
+ * import * as menu from '@tauri-apps/api/menu';
181
+ * const bar = createMenuBar({ menu, commands, appName: 'Notes' });
182
+ * ```
183
+ *
184
+ * A keystroke runs its command once: the page's shortcut listener and the menu accelerator never
185
+ * both act on the same key. A no-op outside a Tauri desktop window.
186
+ */
187
+ export function createMenuBar(options, os) {
188
+ if (!isTauri())
189
+ return inert;
190
+ const platform = tauriPlatform(os);
191
+ const allowed = options.platforms ?? ['macos', 'windows', 'linux'];
192
+ if (platform !== 'macos' && platform !== 'windows' && platform !== 'linux')
193
+ return inert;
194
+ if (!allowed.includes(platform))
195
+ return inert;
196
+ const { menu: module, commands, layout, debounce = 16 } = options;
197
+ const labels = options.labels ?? {};
198
+ const names = {
199
+ edit: labels.edit ?? 'Edit',
200
+ window: labels.window ?? 'Window',
201
+ file: labels.file ?? 'File',
202
+ help: labels.help ?? 'Help',
203
+ commands: labels.commands ?? 'Commands',
204
+ };
205
+ const mac = platform === 'macos';
206
+ const asApp = mac || options.target === 'app';
207
+ const install = (target) => asApp ? target.setAsAppMenu() : target.setAsWindowMenu();
208
+ const resolve = () => {
209
+ const menus = defaultMenus(commands, platform, options, names);
210
+ return plan(layout ? layout(menus, { platform, commands }) : menus, commands, labels);
211
+ };
212
+ let destroyed = false;
213
+ let built = null;
214
+ /** The menu bar before ours: `undefined` until ours went in, `null` if there was none. */
215
+ let previous;
216
+ let latest = null;
217
+ let timer;
218
+ let running = null;
219
+ let again = false;
220
+ // --- One keystroke, one run ---------------------------------------------------------------
221
+ // On macOS the web view sees a key first and hands the menu only what the page left alone, so
222
+ // the registry's `preventDefault` already keeps the accelerator from firing. Other web views
223
+ // may deliver both, in either order; these two records catch whichever comes second.
224
+ let lastKey = null;
225
+ let lastMenuRun = null;
226
+ const sameKey = (event, id) => {
227
+ const shortcut = commands.get(id)?.shortcuts[0];
228
+ return Boolean(shortcut && matchesShortcut(event, shortcut, commands.platform));
229
+ };
230
+ const onKeydown = (event) => {
231
+ const now = Date.now();
232
+ if (lastMenuRun && now - lastMenuRun.at < MENU_THEN_KEY_MS && sameKey(event, lastMenuRun.id)) {
233
+ // The menu already ran this keystroke's command: keep the registry's listener off it.
234
+ lastMenuRun = null;
235
+ event.preventDefault();
236
+ return;
237
+ }
238
+ lastKey = { event, at: now };
239
+ };
240
+ // Capture, so this runs before the registry's own listener on `window` or anything inside.
241
+ window.addEventListener('keydown', onKeydown, true);
242
+ const run = (id) => {
243
+ if (destroyed)
244
+ return;
245
+ const now = Date.now();
246
+ if (lastKey &&
247
+ now - lastKey.at < SAME_KEYSTROKE_MS &&
248
+ lastKey.event.defaultPrevented &&
249
+ sameKey(lastKey.event, id)) {
250
+ // The page's listener already ran it for this keystroke.
251
+ lastKey = null;
252
+ return;
253
+ }
254
+ lastMenuRun = { id, at: now };
255
+ commands.execute(id);
256
+ };
257
+ // --- Building and updating ---------------------------------------------------------------
258
+ const release = (resource) => {
259
+ if (resource)
260
+ quietly(resource.close());
261
+ };
262
+ const releaseBuilt = (target) => {
263
+ if (!target)
264
+ return;
265
+ for (const { handle } of target.items.values())
266
+ release(handle);
267
+ for (const { handle } of target.submenus)
268
+ release(handle);
269
+ release(target.menu);
270
+ };
271
+ async function build(next) {
272
+ // eslint-disable-next-line svelte/prefer-svelte-reactivity -- native handles, never rendered
273
+ const items = new Map();
274
+ const submenus = [];
275
+ for (const planned of next.menus) {
276
+ const children = [];
277
+ for (const item of planned.items) {
278
+ if (item.kind === 'separator')
279
+ children.push({ item: 'Separator' });
280
+ else if (item.kind === 'predefined') {
281
+ const kind = item.item === 'About'
282
+ ? { About: options.appName ? { name: options.appName } : null }
283
+ : item.item;
284
+ children.push(item.text === undefined ? { item: kind } : { item: kind, text: item.text });
285
+ }
286
+ else {
287
+ const handle = await module.MenuItem.new({
288
+ text: item.text,
289
+ enabled: item.enabled,
290
+ ...(item.accelerator ? { accelerator: item.accelerator } : {}),
291
+ action: () => run(item.id),
292
+ });
293
+ items.set(item.id, { state: item, handle });
294
+ children.push(handle);
295
+ }
296
+ }
297
+ const handle = await module.Submenu.new({ text: planned.text, items: children });
298
+ submenus.push({ id: planned.id, text: planned.text, handle });
299
+ if (mac && planned.id === 'window')
300
+ quietly(handle.setAsWindowsMenuForNSApp?.());
301
+ if (mac && planned.id === 'help')
302
+ quietly(handle.setAsHelpMenuForNSApp?.());
303
+ }
304
+ const menu = await module.Menu.new({ items: submenus.map(({ handle }) => handle) });
305
+ return { plan: next, menu, submenus, items };
306
+ }
307
+ /** Changes labels, enabled states and accelerators of the menu in place. */
308
+ async function patch(target, next) {
309
+ const calls = [];
310
+ next.menus.forEach((planned, index) => {
311
+ const submenu = target.submenus[index];
312
+ if (submenu.text !== planned.text) {
313
+ submenu.text = planned.text;
314
+ calls.push(submenu.handle.setText(planned.text));
315
+ }
316
+ for (const item of planned.items) {
317
+ if (item.kind !== 'command')
318
+ continue;
319
+ const entry = target.items.get(item.id);
320
+ const { state, handle } = entry;
321
+ if (state.text !== item.text)
322
+ calls.push(handle.setText(item.text));
323
+ if (state.enabled !== item.enabled)
324
+ calls.push(handle.setEnabled(item.enabled));
325
+ if (state.accelerator !== item.accelerator) {
326
+ calls.push(handle.setAccelerator(item.accelerator));
327
+ }
328
+ entry.state = item;
329
+ }
330
+ });
331
+ target.plan = next;
332
+ await Promise.all(calls.map((call) => call.catch(() => { })));
333
+ }
334
+ async function sync() {
335
+ const next = latest ?? untrack(resolve);
336
+ if (built && built.plan.structure === next.structure)
337
+ return patch(built, next);
338
+ const fresh = await build(next);
339
+ if (destroyed)
340
+ return releaseBuilt(fresh);
341
+ let replaced;
342
+ try {
343
+ replaced = await install(fresh.menu);
344
+ }
345
+ catch (error) {
346
+ releaseBuilt(fresh);
347
+ throw error;
348
+ }
349
+ if (previous === undefined)
350
+ previous = replaced;
351
+ // The menu it replaced is ours from the last build, handed back under a new handle.
352
+ else
353
+ release(replaced);
354
+ releaseBuilt(built);
355
+ built = fresh;
356
+ }
357
+ const kick = () => {
358
+ if (destroyed)
359
+ return Promise.resolve();
360
+ if (running) {
361
+ again = true;
362
+ return running;
363
+ }
364
+ running = (async () => {
365
+ do {
366
+ again = false;
367
+ try {
368
+ await sync();
369
+ }
370
+ catch {
371
+ /* a call the capability does not allow, or no menu bar on this desktop */
372
+ }
373
+ } while (again && !destroyed);
374
+ })().finally(() => {
375
+ running = null;
376
+ });
377
+ return running;
378
+ };
379
+ let resolveReady;
380
+ const ready = new Promise((resolve) => (resolveReady = resolve));
381
+ const schedule = () => {
382
+ if (destroyed)
383
+ return;
384
+ clearTimeout(timer);
385
+ timer = setTimeout(() => {
386
+ kick().then(resolveReady);
387
+ }, debounce);
388
+ };
389
+ // Reading the registry inside an effect tracks every list change and every `enabled` function
390
+ // that reads `$state`; the effect batches a burst of changes into one run.
391
+ const stopTracking = $effect.root(() => {
392
+ $effect(() => {
393
+ latest = resolve();
394
+ schedule();
395
+ });
396
+ });
397
+ async function restore() {
398
+ await running;
399
+ const target = built;
400
+ built = null;
401
+ if (!target)
402
+ return;
403
+ try {
404
+ if (previous)
405
+ await install(previous);
406
+ else {
407
+ // Nothing to give back (a window with no menu of its own): leave an empty one.
408
+ const empty = await module.Menu.new({ items: [] });
409
+ release(await install(empty));
410
+ release(empty);
411
+ }
412
+ }
413
+ catch {
414
+ /* not allowed by the capability */
415
+ }
416
+ release(previous);
417
+ releaseBuilt(target);
418
+ }
419
+ return {
420
+ ready,
421
+ async refresh() {
422
+ if (destroyed)
423
+ return;
424
+ latest = untrack(resolve);
425
+ clearTimeout(timer);
426
+ await kick().then(resolveReady);
427
+ },
428
+ destroy() {
429
+ if (destroyed)
430
+ return;
431
+ destroyed = true;
432
+ clearTimeout(timer);
433
+ stopTracking();
434
+ window.removeEventListener('keydown', onKeydown, true);
435
+ resolveReady();
436
+ quietly(restore());
437
+ },
438
+ };
439
+ }
@@ -0,0 +1,67 @@
1
+ import type { NotificationPlugin } from './types.js';
2
+ /**
3
+ * Whether the app may notify: `'granted'`, `'denied'`, `'default'` (not asked yet), or
4
+ * `'unsupported'` where there is no way to notify at all (the server, an old browser, a web view
5
+ * without the API).
6
+ */
7
+ export type NotificationPermissionState = 'granted' | 'denied' | 'default' | 'unsupported';
8
+ /** Where notifications go: the OS through the Tauri plugin, the Web Notifications API, or nowhere. */
9
+ export type NotificationBackend = 'tauri' | 'web' | 'none';
10
+ export interface NotifyOptions {
11
+ title: string;
12
+ body?: string;
13
+ /** An icon URL or path. The OS may ignore it and show the app's own icon. */
14
+ icon?: string;
15
+ /** No sound. */
16
+ silent?: boolean;
17
+ }
18
+ /** The slice of the theme's `Toaster` the fallback calls. `createToaster()` fits it. */
19
+ export interface NotificationToaster {
20
+ info(title: string, options?: {
21
+ description?: string;
22
+ }): unknown;
23
+ }
24
+ export interface NotificationsOptions {
25
+ /** `@tauri-apps/plugin-notification`, for OS notifications from Rust inside a Tauri window. */
26
+ plugin?: NotificationPlugin;
27
+ /**
28
+ * Shows a notification as an in-app toast when it cannot reach the OS: permission denied or not
29
+ * yet given, or no notification API at all. `notify()` still resolves `false` then.
30
+ */
31
+ toaster?: NotificationToaster;
32
+ }
33
+ export interface Notifications {
34
+ /** Where notifications go. Fixed once created. */
35
+ readonly backend: NotificationBackend;
36
+ /** Reactive. Starts as the best synchronous guess and settles by {@link ready}. */
37
+ readonly permission: NotificationPermissionState;
38
+ /** Settles once the permission has been read (one round trip to Rust inside Tauri). */
39
+ readonly ready: Promise<void>;
40
+ /**
41
+ * Asks the user, if they have not answered yet, and resolves the resulting state. Never
42
+ * throws. In a browser call it from a click or key handler: browsers ignore or block a prompt
43
+ * that no user gesture asked for.
44
+ */
45
+ requestPermission(): Promise<NotificationPermissionState>;
46
+ /**
47
+ * Shows a notification when permission is granted and resolves whether it reached the OS. It
48
+ * never prompts, so it is safe to call from background work; ask first with
49
+ * {@link requestPermission}. With a `toaster`, anything it cannot show becomes a toast.
50
+ */
51
+ notify(options: NotifyOptions): Promise<boolean>;
52
+ destroy(): void;
53
+ }
54
+ /**
55
+ * OS notifications with the permission flow handled. Inside a Tauri window with
56
+ * `@tauri-apps/plugin-notification` they come from Rust; in a browser, or a window without the
57
+ * plugin, from the Web Notifications API; with neither, `notify()` resolves `false` (or shows a
58
+ * toast, given a `toaster`). A denied permission never throws.
59
+ *
60
+ * ```ts
61
+ * const notifications = createNotifications({ plugin: notification, toaster });
62
+ * // on a button: await notifications.requestPermission();
63
+ * // later, from anywhere:
64
+ * notifications.notify({ title: 'Export finished', body: 'The file is in Downloads.' });
65
+ * ```
66
+ */
67
+ export declare function createNotifications(options?: NotificationsOptions): Notifications;