@decaf-ts/for-os 0.0.0-stage → 0.2.7
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.md +21 -0
- package/README.md +380 -2
- package/lib/cjs/errors.cjs +73 -0
- package/lib/cjs/errors.cjs.map +1 -0
- package/lib/cjs/index.cjs +46 -0
- package/lib/cjs/index.cjs.map +1 -0
- package/lib/cjs/native/icons.cjs +123 -0
- package/lib/cjs/native/icons.cjs.map +1 -0
- package/lib/cjs/native/loader.cjs +123 -0
- package/lib/cjs/native/loader.cjs.map +1 -0
- package/lib/cjs/native/types.cjs +4 -0
- package/lib/cjs/native/types.cjs.map +1 -0
- package/lib/cjs/notifications/NotificationCenter.cjs +328 -0
- package/lib/cjs/notifications/NotificationCenter.cjs.map +1 -0
- package/lib/cjs/tray/TrayIcon.cjs +367 -0
- package/lib/cjs/tray/TrayIcon.cjs.map +1 -0
- package/lib/cjs/tray/assets.cjs +31 -0
- package/lib/cjs/tray/assets.cjs.map +1 -0
- package/lib/esm/errors.js +65 -0
- package/lib/esm/errors.js.map +1 -0
- package/lib/esm/index.js +28 -0
- package/lib/esm/index.js.map +1 -0
- package/lib/esm/native/icons.js +117 -0
- package/lib/esm/native/icons.js.map +1 -0
- package/lib/esm/native/loader.js +116 -0
- package/lib/esm/native/loader.js.map +1 -0
- package/lib/esm/native/types.js +8 -0
- package/lib/esm/native/types.js.map +1 -0
- package/lib/esm/notifications/NotificationCenter.js +322 -0
- package/lib/esm/notifications/NotificationCenter.js.map +1 -0
- package/lib/esm/tray/TrayIcon.js +362 -0
- package/lib/esm/tray/TrayIcon.js.map +1 -0
- package/lib/esm/tray/assets.js +26 -0
- package/lib/esm/tray/assets.js.map +1 -0
- package/lib/types/errors.d.cts +56 -0
- package/lib/types/errors.d.mts +56 -0
- package/lib/types/index.d.cts +27 -0
- package/lib/types/index.d.mts +27 -0
- package/lib/types/native/icons.d.cts +71 -0
- package/lib/types/native/icons.d.mts +71 -0
- package/lib/types/native/loader.d.cts +37 -0
- package/lib/types/native/loader.d.mts +37 -0
- package/lib/types/native/types.d.cts +104 -0
- package/lib/types/native/types.d.mts +104 -0
- package/lib/types/notifications/NotificationCenter.d.cts +163 -0
- package/lib/types/notifications/NotificationCenter.d.mts +163 -0
- package/lib/types/tray/TrayIcon.d.cts +174 -0
- package/lib/types/tray/TrayIcon.d.mts +174 -0
- package/lib/types/tray/assets.d.cts +25 -0
- package/lib/types/tray/assets.d.mts +25 -0
- package/native/tray-icon-node/Cargo.lock +1511 -0
- package/native/tray-icon-node/Cargo.toml +45 -0
- package/native/tray-icon-node/Cross.toml +10 -0
- package/native/tray-icon-node/LICENSE +21 -0
- package/native/tray-icon-node/UPSTREAM-README.md +281 -0
- package/native/tray-icon-node/UPSTREAM.md +213 -0
- package/native/tray-icon-node/build-manifest.json +16 -0
- package/native/tray-icon-node/build.rs +5 -0
- package/native/tray-icon-node/index.d.ts +368 -0
- package/native/tray-icon-node/index.js +609 -0
- package/native/tray-icon-node/package.json +55 -0
- package/native/tray-icon-node/rustfmt.toml +31 -0
- package/native/tray-icon-node/source-manifest.json +30 -0
- package/native/tray-icon-node/src/common.rs +101 -0
- package/native/tray-icon-node/src/icon.rs +255 -0
- package/native/tray-icon-node/src/lib.rs +449 -0
- package/native/tray-icon-node/src/menu.rs +849 -0
- package/native/tray-icon-node/src/tray.rs +251 -0
- package/native/tray-icon-node/tray-icon-node.linux-x64-gnu.node +0 -0
- package/package.json +131 -4
- package/scripts/for-os-build.mjs +60 -0
- package/scripts/for-os-init.mjs +327 -0
- package/scripts/for-os-install.mjs +47 -0
- package/scripts/for-os-integration.mjs +137 -0
- package/scripts/for-os-integrity.mjs +51 -0
- package/scripts/for-os-package.mjs +49 -0
- package/scripts/lib/native.mjs +591 -0
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module for-os.native.icons
|
|
3
|
+
* @description Converts TypeScript icon sources into native tray icon handles.
|
|
4
|
+
* @summary The native addon loads icons from file paths (or raw RGBA), so
|
|
5
|
+
* base64 and byte-buffer sources are materialized into a private temporary
|
|
6
|
+
* directory that is removed when the owning tray closes.
|
|
7
|
+
*/
|
|
8
|
+
import type { NativeIconFactory } from "./types.d.mts";
|
|
9
|
+
/** Raw RGBA pixels accepted by {@link IconSource}. */
|
|
10
|
+
export type RgbaIcon = {
|
|
11
|
+
rgba: Buffer | Uint8Array;
|
|
12
|
+
width: number;
|
|
13
|
+
height: number;
|
|
14
|
+
};
|
|
15
|
+
/**
|
|
16
|
+
* Any icon representation accepted by {@link IconResolver.resolve}.
|
|
17
|
+
* - `string`: absolute or relative image file path
|
|
18
|
+
* - `{ path }`: image file path
|
|
19
|
+
* - `{ base64 }`: base64-encoded image bytes (PNG/JPEG, decided by `extension`)
|
|
20
|
+
* - `{ png }` / `{ bytes }`: raw encoded image bytes
|
|
21
|
+
* - `{ rgba, width, height }`: uncompressed RGBA pixels
|
|
22
|
+
*
|
|
23
|
+
* Caller-supplied `extension` values are sanitized to a safe alphanumeric/dot
|
|
24
|
+
* file suffix (capped at 16 characters) and fall back to `.png`.
|
|
25
|
+
*/
|
|
26
|
+
export type IconSource = string | {
|
|
27
|
+
path: string;
|
|
28
|
+
} | {
|
|
29
|
+
base64: string;
|
|
30
|
+
extension?: string;
|
|
31
|
+
} | {
|
|
32
|
+
png: Buffer | Uint8Array;
|
|
33
|
+
} | {
|
|
34
|
+
bytes: Buffer | Uint8Array;
|
|
35
|
+
extension?: string;
|
|
36
|
+
} | RgbaIcon;
|
|
37
|
+
/**
|
|
38
|
+
* @description Owns the temporary directory used to materialize file-backed icons.
|
|
39
|
+
* @summary One resolver is normally owned by a tray or notification host and
|
|
40
|
+
* disposed with it. Resolving an already-native handle is intentionally not
|
|
41
|
+
* supported; callers pass a source and the resolver keeps the native object.
|
|
42
|
+
* @param {NativeIconFactory} api native icon factory used to build handles
|
|
43
|
+
* @param {function(string): string} [createDirectory] creates the private
|
|
44
|
+
* temporary directory; defaults to `fs.mkdtempSync` under the OS temp dir
|
|
45
|
+
* @param {function(string): void} [removeDirectory] removes the private
|
|
46
|
+
* directory on {@link IconResolver.dispose}; defaults to a recursive `fs.rmSync`
|
|
47
|
+
* @class IconResolver
|
|
48
|
+
*/
|
|
49
|
+
export declare class IconResolver {
|
|
50
|
+
private readonly api;
|
|
51
|
+
private readonly createDirectory;
|
|
52
|
+
private readonly removeDirectory;
|
|
53
|
+
private directory?;
|
|
54
|
+
constructor(api: NativeIconFactory, createDirectory?: (prefix: string) => string, removeDirectory?: (directory: string) => void);
|
|
55
|
+
private ensureDirectory;
|
|
56
|
+
/**
|
|
57
|
+
* Materializes `source` into a native icon handle.
|
|
58
|
+
* @param {IconSource} source the icon path, bytes, base64, or RGBA data
|
|
59
|
+
* @return {unknown} the native icon handle expected by the addon
|
|
60
|
+
* @throws {IconError} when the source is invalid or points to a missing file
|
|
61
|
+
*/
|
|
62
|
+
resolve(source: IconSource): unknown;
|
|
63
|
+
private fromPath;
|
|
64
|
+
private fromBytes;
|
|
65
|
+
/** Removes every materialized icon file; idempotent. */
|
|
66
|
+
dispose(): void;
|
|
67
|
+
/** Directory holding materialized icons, when one has been created. */
|
|
68
|
+
get iconDirectory(): string | undefined;
|
|
69
|
+
}
|
|
70
|
+
/** Returns a stable file extension for a path, defaulting to `.png`. */
|
|
71
|
+
export declare function iconExtension(path: string): string;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module for-os.native.loader
|
|
3
|
+
* @description Locates and loads the vendored `tray-icon-node` NAPI-RS addon.
|
|
4
|
+
* @summary The addon is built from `native/tray-icon-node` by
|
|
5
|
+
* `scripts/for-os-install.mjs` and materialized into `node_modules/tray-icon-node`.
|
|
6
|
+
* Resolution order is an explicit `FOR_OS_NATIVE_MODULE` path, normal Node
|
|
7
|
+
* package resolution from the current project, then the crate's checked-in
|
|
8
|
+
* `index.js` under the current project. Loading never throws: callers decide
|
|
9
|
+
* whether a missing addon is fatal.
|
|
10
|
+
*/
|
|
11
|
+
import type { NativeModule } from "./types.d.cts";
|
|
12
|
+
/** Environment variable that pins an explicit native addon module path. */
|
|
13
|
+
export declare const NATIVE_MODULE_ENV = "FOR_OS_NATIVE_MODULE";
|
|
14
|
+
/** Package name of the vendored addon. */
|
|
15
|
+
export declare const NATIVE_MODULE_PACKAGE = "tray-icon-node";
|
|
16
|
+
/** A successful or failed native-module load. */
|
|
17
|
+
export type NativeLoadResult = {
|
|
18
|
+
available: true;
|
|
19
|
+
api: NativeModule;
|
|
20
|
+
modulePath: string;
|
|
21
|
+
} | {
|
|
22
|
+
available: false;
|
|
23
|
+
error: Error;
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* Loads the native addon, reusing one process-wide result.
|
|
27
|
+
* @return {NativeLoadResult} the loaded module or the reason it is unavailable
|
|
28
|
+
*/
|
|
29
|
+
export declare function loadNativeModule(): NativeLoadResult;
|
|
30
|
+
/**
|
|
31
|
+
* Loads the native addon or throws {@link NativeModuleUnavailableError}.
|
|
32
|
+
* @return {NativeModule} the loaded native module
|
|
33
|
+
* @throws {NativeModuleUnavailableError} when no usable addon was found
|
|
34
|
+
*/
|
|
35
|
+
export declare function requireNativeModule(): NativeModule;
|
|
36
|
+
/** Clears the process-wide load cache (used by tests and re-installs). */
|
|
37
|
+
export declare function resetNativeModuleCache(): void;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module for-os.native.loader
|
|
3
|
+
* @description Locates and loads the vendored `tray-icon-node` NAPI-RS addon.
|
|
4
|
+
* @summary The addon is built from `native/tray-icon-node` by
|
|
5
|
+
* `scripts/for-os-install.mjs` and materialized into `node_modules/tray-icon-node`.
|
|
6
|
+
* Resolution order is an explicit `FOR_OS_NATIVE_MODULE` path, normal Node
|
|
7
|
+
* package resolution from the current project, then the crate's checked-in
|
|
8
|
+
* `index.js` under the current project. Loading never throws: callers decide
|
|
9
|
+
* whether a missing addon is fatal.
|
|
10
|
+
*/
|
|
11
|
+
import type { NativeModule } from "./types.d.mts";
|
|
12
|
+
/** Environment variable that pins an explicit native addon module path. */
|
|
13
|
+
export declare const NATIVE_MODULE_ENV = "FOR_OS_NATIVE_MODULE";
|
|
14
|
+
/** Package name of the vendored addon. */
|
|
15
|
+
export declare const NATIVE_MODULE_PACKAGE = "tray-icon-node";
|
|
16
|
+
/** A successful or failed native-module load. */
|
|
17
|
+
export type NativeLoadResult = {
|
|
18
|
+
available: true;
|
|
19
|
+
api: NativeModule;
|
|
20
|
+
modulePath: string;
|
|
21
|
+
} | {
|
|
22
|
+
available: false;
|
|
23
|
+
error: Error;
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* Loads the native addon, reusing one process-wide result.
|
|
27
|
+
* @return {NativeLoadResult} the loaded module or the reason it is unavailable
|
|
28
|
+
*/
|
|
29
|
+
export declare function loadNativeModule(): NativeLoadResult;
|
|
30
|
+
/**
|
|
31
|
+
* Loads the native addon or throws {@link NativeModuleUnavailableError}.
|
|
32
|
+
* @return {NativeModule} the loaded native module
|
|
33
|
+
* @throws {NativeModuleUnavailableError} when no usable addon was found
|
|
34
|
+
*/
|
|
35
|
+
export declare function requireNativeModule(): NativeModule;
|
|
36
|
+
/** Clears the process-wide load cache (used by tests and re-installs). */
|
|
37
|
+
export declare function resetNativeModuleCache(): void;
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module for-os.native.types
|
|
3
|
+
* @description Structural types for the vendored `tray-icon-node` NAPI-RS addon.
|
|
4
|
+
* @summary These mirror `native/tray-icon-node/index.d.ts` but stay deliberately
|
|
5
|
+
* narrow so the bridges can be exercised with a fake native module in tests.
|
|
6
|
+
*/
|
|
7
|
+
/** Rectangle reported for tray-icon events. */
|
|
8
|
+
export type NativeRect = {
|
|
9
|
+
x: number;
|
|
10
|
+
y: number;
|
|
11
|
+
width: number;
|
|
12
|
+
height: number;
|
|
13
|
+
};
|
|
14
|
+
/** Raw tray-icon event emitted by the native event loop. */
|
|
15
|
+
export type NativeTrayEvent = {
|
|
16
|
+
eventType: string;
|
|
17
|
+
id: string;
|
|
18
|
+
x: number;
|
|
19
|
+
y: number;
|
|
20
|
+
iconRect: NativeRect;
|
|
21
|
+
button: number;
|
|
22
|
+
buttonState: number;
|
|
23
|
+
};
|
|
24
|
+
/** Menu event emitted when the user activates a menu item. */
|
|
25
|
+
export type NativeMenuEvent = {
|
|
26
|
+
id: string;
|
|
27
|
+
};
|
|
28
|
+
/** Handle to a native menu entry. */
|
|
29
|
+
export type NativeMenuItemHandle = {
|
|
30
|
+
setText(text: string): void;
|
|
31
|
+
setEnabled(enabled: boolean): void;
|
|
32
|
+
};
|
|
33
|
+
/** Handle to a native checkable menu entry. */
|
|
34
|
+
export type NativeCheckMenuItemHandle = NativeMenuItemHandle & {
|
|
35
|
+
isChecked(): boolean;
|
|
36
|
+
setChecked(checked: boolean): void;
|
|
37
|
+
};
|
|
38
|
+
/** Handle to a native menu (or submenu). */
|
|
39
|
+
export type NativeMenuHandle = {
|
|
40
|
+
appendMenuItem(item: NativeMenuItemHandle, id?: string | null): void;
|
|
41
|
+
appendCheckMenuItem(item: NativeCheckMenuItemHandle, id: string): void;
|
|
42
|
+
appendPredefinedMenuItem(item: unknown): void;
|
|
43
|
+
isChecked(id: string): boolean;
|
|
44
|
+
toggleCheck(id: string): boolean;
|
|
45
|
+
setText(id: string, text: string): void;
|
|
46
|
+
};
|
|
47
|
+
/** Handle to a live native tray icon. */
|
|
48
|
+
export type NativeTrayHost = {
|
|
49
|
+
setIcon(icon: unknown | null): void;
|
|
50
|
+
setTooltip(tooltip: string | null): void;
|
|
51
|
+
setTitle(title: string | null): void;
|
|
52
|
+
setVisible(visible: boolean): void;
|
|
53
|
+
};
|
|
54
|
+
/** Native icon factory. */
|
|
55
|
+
export type NativeIconFactory = {
|
|
56
|
+
fromPath(path: string): unknown;
|
|
57
|
+
fromRgba(rgba: Buffer | Uint8Array, width: number, height: number): unknown;
|
|
58
|
+
};
|
|
59
|
+
/** Native tray-icon builder. */
|
|
60
|
+
export type NativeTrayIconBuilder = {
|
|
61
|
+
withIcon(icon: unknown): NativeTrayIconBuilder;
|
|
62
|
+
withTooltip(tooltip: string): NativeTrayIconBuilder;
|
|
63
|
+
withTitle(title: string): NativeTrayIconBuilder;
|
|
64
|
+
withMenu(menu: NativeMenuHandle): NativeTrayIconBuilder;
|
|
65
|
+
build(): NativeTrayHost;
|
|
66
|
+
};
|
|
67
|
+
/** Notification action button understood by the native addon. */
|
|
68
|
+
export type NativeNotificationAction = {
|
|
69
|
+
id: string;
|
|
70
|
+
label: string;
|
|
71
|
+
};
|
|
72
|
+
/**
|
|
73
|
+
* The subset of the `tray-icon-node` module consumed by the TypeScript bridges.
|
|
74
|
+
* Optional members are absent on older locally built binaries.
|
|
75
|
+
*/
|
|
76
|
+
export type NativeModule = {
|
|
77
|
+
initialize(): void;
|
|
78
|
+
update(): void;
|
|
79
|
+
Icon: NativeIconFactory;
|
|
80
|
+
Menu: new () => NativeMenuHandle;
|
|
81
|
+
MenuItemBuilder: new () => {
|
|
82
|
+
withText(text: string): unknown;
|
|
83
|
+
withEnabled(enabled: boolean): unknown;
|
|
84
|
+
withId(id: string): unknown;
|
|
85
|
+
build(): NativeMenuItemHandle;
|
|
86
|
+
};
|
|
87
|
+
CheckMenuItemBuilder?: new () => {
|
|
88
|
+
withText(text: string): unknown;
|
|
89
|
+
withEnabled(enabled: boolean): unknown;
|
|
90
|
+
withChecked(checked: boolean): unknown;
|
|
91
|
+
withId(id: string): unknown;
|
|
92
|
+
build(): NativeCheckMenuItemHandle;
|
|
93
|
+
};
|
|
94
|
+
PredefinedMenuItem?: {
|
|
95
|
+
separator(): unknown;
|
|
96
|
+
};
|
|
97
|
+
TrayIconBuilder: new () => NativeTrayIconBuilder;
|
|
98
|
+
pollMenuEvents(): NativeMenuEvent | null;
|
|
99
|
+
pollTrayEvents?(): NativeTrayEvent | null;
|
|
100
|
+
showNotification(title: string, body: string, timeoutMs?: number | null): void;
|
|
101
|
+
showNotificationWithActions?(title: string, body: string, actions: NativeNotificationAction[], timeoutMs?: number | null): void;
|
|
102
|
+
showAppointmentNotification?(title: string, body: string, timeoutMs?: number | null): void;
|
|
103
|
+
pollNotificationActions?(): string | null;
|
|
104
|
+
};
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module for-os.native.types
|
|
3
|
+
* @description Structural types for the vendored `tray-icon-node` NAPI-RS addon.
|
|
4
|
+
* @summary These mirror `native/tray-icon-node/index.d.ts` but stay deliberately
|
|
5
|
+
* narrow so the bridges can be exercised with a fake native module in tests.
|
|
6
|
+
*/
|
|
7
|
+
/** Rectangle reported for tray-icon events. */
|
|
8
|
+
export type NativeRect = {
|
|
9
|
+
x: number;
|
|
10
|
+
y: number;
|
|
11
|
+
width: number;
|
|
12
|
+
height: number;
|
|
13
|
+
};
|
|
14
|
+
/** Raw tray-icon event emitted by the native event loop. */
|
|
15
|
+
export type NativeTrayEvent = {
|
|
16
|
+
eventType: string;
|
|
17
|
+
id: string;
|
|
18
|
+
x: number;
|
|
19
|
+
y: number;
|
|
20
|
+
iconRect: NativeRect;
|
|
21
|
+
button: number;
|
|
22
|
+
buttonState: number;
|
|
23
|
+
};
|
|
24
|
+
/** Menu event emitted when the user activates a menu item. */
|
|
25
|
+
export type NativeMenuEvent = {
|
|
26
|
+
id: string;
|
|
27
|
+
};
|
|
28
|
+
/** Handle to a native menu entry. */
|
|
29
|
+
export type NativeMenuItemHandle = {
|
|
30
|
+
setText(text: string): void;
|
|
31
|
+
setEnabled(enabled: boolean): void;
|
|
32
|
+
};
|
|
33
|
+
/** Handle to a native checkable menu entry. */
|
|
34
|
+
export type NativeCheckMenuItemHandle = NativeMenuItemHandle & {
|
|
35
|
+
isChecked(): boolean;
|
|
36
|
+
setChecked(checked: boolean): void;
|
|
37
|
+
};
|
|
38
|
+
/** Handle to a native menu (or submenu). */
|
|
39
|
+
export type NativeMenuHandle = {
|
|
40
|
+
appendMenuItem(item: NativeMenuItemHandle, id?: string | null): void;
|
|
41
|
+
appendCheckMenuItem(item: NativeCheckMenuItemHandle, id: string): void;
|
|
42
|
+
appendPredefinedMenuItem(item: unknown): void;
|
|
43
|
+
isChecked(id: string): boolean;
|
|
44
|
+
toggleCheck(id: string): boolean;
|
|
45
|
+
setText(id: string, text: string): void;
|
|
46
|
+
};
|
|
47
|
+
/** Handle to a live native tray icon. */
|
|
48
|
+
export type NativeTrayHost = {
|
|
49
|
+
setIcon(icon: unknown | null): void;
|
|
50
|
+
setTooltip(tooltip: string | null): void;
|
|
51
|
+
setTitle(title: string | null): void;
|
|
52
|
+
setVisible(visible: boolean): void;
|
|
53
|
+
};
|
|
54
|
+
/** Native icon factory. */
|
|
55
|
+
export type NativeIconFactory = {
|
|
56
|
+
fromPath(path: string): unknown;
|
|
57
|
+
fromRgba(rgba: Buffer | Uint8Array, width: number, height: number): unknown;
|
|
58
|
+
};
|
|
59
|
+
/** Native tray-icon builder. */
|
|
60
|
+
export type NativeTrayIconBuilder = {
|
|
61
|
+
withIcon(icon: unknown): NativeTrayIconBuilder;
|
|
62
|
+
withTooltip(tooltip: string): NativeTrayIconBuilder;
|
|
63
|
+
withTitle(title: string): NativeTrayIconBuilder;
|
|
64
|
+
withMenu(menu: NativeMenuHandle): NativeTrayIconBuilder;
|
|
65
|
+
build(): NativeTrayHost;
|
|
66
|
+
};
|
|
67
|
+
/** Notification action button understood by the native addon. */
|
|
68
|
+
export type NativeNotificationAction = {
|
|
69
|
+
id: string;
|
|
70
|
+
label: string;
|
|
71
|
+
};
|
|
72
|
+
/**
|
|
73
|
+
* The subset of the `tray-icon-node` module consumed by the TypeScript bridges.
|
|
74
|
+
* Optional members are absent on older locally built binaries.
|
|
75
|
+
*/
|
|
76
|
+
export type NativeModule = {
|
|
77
|
+
initialize(): void;
|
|
78
|
+
update(): void;
|
|
79
|
+
Icon: NativeIconFactory;
|
|
80
|
+
Menu: new () => NativeMenuHandle;
|
|
81
|
+
MenuItemBuilder: new () => {
|
|
82
|
+
withText(text: string): unknown;
|
|
83
|
+
withEnabled(enabled: boolean): unknown;
|
|
84
|
+
withId(id: string): unknown;
|
|
85
|
+
build(): NativeMenuItemHandle;
|
|
86
|
+
};
|
|
87
|
+
CheckMenuItemBuilder?: new () => {
|
|
88
|
+
withText(text: string): unknown;
|
|
89
|
+
withEnabled(enabled: boolean): unknown;
|
|
90
|
+
withChecked(checked: boolean): unknown;
|
|
91
|
+
withId(id: string): unknown;
|
|
92
|
+
build(): NativeCheckMenuItemHandle;
|
|
93
|
+
};
|
|
94
|
+
PredefinedMenuItem?: {
|
|
95
|
+
separator(): unknown;
|
|
96
|
+
};
|
|
97
|
+
TrayIconBuilder: new () => NativeTrayIconBuilder;
|
|
98
|
+
pollMenuEvents(): NativeMenuEvent | null;
|
|
99
|
+
pollTrayEvents?(): NativeTrayEvent | null;
|
|
100
|
+
showNotification(title: string, body: string, timeoutMs?: number | null): void;
|
|
101
|
+
showNotificationWithActions?(title: string, body: string, actions: NativeNotificationAction[], timeoutMs?: number | null): void;
|
|
102
|
+
showAppointmentNotification?(title: string, body: string, timeoutMs?: number | null): void;
|
|
103
|
+
pollNotificationActions?(): string | null;
|
|
104
|
+
};
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module for-os.notifications
|
|
3
|
+
* @description Desktop-notification bridge with timers and JavaScript action callbacks.
|
|
4
|
+
* @summary `NotificationCenter` sends notifications through the native addon,
|
|
5
|
+
* exposes action buttons as JavaScript callbacks, and owns the auto-dismiss
|
|
6
|
+
* timer contract. Button delivery is native on Linux (through
|
|
7
|
+
* `notify-send --wait`); macOS and Windows render a plain notification and
|
|
8
|
+
* report that no buttons are available.
|
|
9
|
+
*/
|
|
10
|
+
import type { NativeModule } from "../native/types.d.cts";
|
|
11
|
+
/** Default auto-dismiss delay for a notification, in milliseconds. */
|
|
12
|
+
export declare const DEFAULT_NOTIFICATION_TIMEOUT_MS = 10000;
|
|
13
|
+
/** Callback invoked when a notification action or button is activated. */
|
|
14
|
+
export type NotificationActionHandler = (actionId: string, notification?: NotificationRecord) => void;
|
|
15
|
+
/**
|
|
16
|
+
* One action button rendered on a notification.
|
|
17
|
+
* @summary Button ids match literally. The `default` action id emitted by the
|
|
18
|
+
* native service for a notification-body click is reserved: it resolves to the
|
|
19
|
+
* first button of the owning notification unless a button is explicitly named
|
|
20
|
+
* `default`.
|
|
21
|
+
*/
|
|
22
|
+
export type NotificationButton = {
|
|
23
|
+
/** Stable id reported to the handler. */
|
|
24
|
+
id: string;
|
|
25
|
+
/** Button label rendered by the operating system. */
|
|
26
|
+
label: string;
|
|
27
|
+
/** Optional per-button callback. */
|
|
28
|
+
onClick?: NotificationActionHandler;
|
|
29
|
+
};
|
|
30
|
+
/** Reason a notification is considered dismissed. */
|
|
31
|
+
export type DismissReason = "timer" | "manual";
|
|
32
|
+
/** Public state of a dispatched notification. */
|
|
33
|
+
export type NotificationRecord = {
|
|
34
|
+
/** Stable id generated by the bridge. */
|
|
35
|
+
readonly id: string;
|
|
36
|
+
readonly title: string;
|
|
37
|
+
readonly body: string;
|
|
38
|
+
/** Configured auto-dismiss delay; `0` disables the timer. */
|
|
39
|
+
readonly timeoutMs: number;
|
|
40
|
+
/** Action buttons captured at dispatch; treat this array as read-only. */
|
|
41
|
+
readonly buttons: NotificationButton[];
|
|
42
|
+
/** Whether the operating system accepted the notification. */
|
|
43
|
+
readonly delivered: boolean;
|
|
44
|
+
/** Whether the timer or a manual call marked the notification dismissed. */
|
|
45
|
+
readonly dismissed: boolean;
|
|
46
|
+
/** Marks the notification dismissed and invokes `onDismiss` once. */
|
|
47
|
+
dismiss(reason?: DismissReason): void;
|
|
48
|
+
/** Registers an additional action handler for this notification. */
|
|
49
|
+
onAction(handler: NotificationActionHandler): NotificationRecord;
|
|
50
|
+
};
|
|
51
|
+
/** Options accepted by {@link NotificationCenter.notify}. */
|
|
52
|
+
export type NotifyOptions = {
|
|
53
|
+
title: string;
|
|
54
|
+
body: string;
|
|
55
|
+
/**
|
|
56
|
+
* Auto-dismiss delay in milliseconds. Defaults to
|
|
57
|
+
* {@link DEFAULT_NOTIFICATION_TIMEOUT_MS}; `0` disables the timer. The native
|
|
58
|
+
* host honours the delay where its notification service supports expiry
|
|
59
|
+
* (Linux, Windows); macOS applies the system dismissal policy while the
|
|
60
|
+
* bridge still tracks the timer locally.
|
|
61
|
+
*/
|
|
62
|
+
timeoutMs?: number;
|
|
63
|
+
/** Action buttons; native delivery is Linux-only. */
|
|
64
|
+
buttons?: NotificationButton[];
|
|
65
|
+
/** Notification-level action callback. */
|
|
66
|
+
onAction?: NotificationActionHandler;
|
|
67
|
+
/** Called once when the timer fires or {@link NotificationRecord.dismiss} runs. */
|
|
68
|
+
onDismiss?: (reason: DismissReason, notification: NotificationRecord) => void;
|
|
69
|
+
};
|
|
70
|
+
/** Construction options for {@link NotificationCenter}. */
|
|
71
|
+
export type NotificationCenterOptions = {
|
|
72
|
+
/** Native module override (tests/embedding); defaults to the built addon. */
|
|
73
|
+
api?: NativeModule;
|
|
74
|
+
/** Global action dispatch interval (defaults to 100 ms). */
|
|
75
|
+
pollIntervalMs?: number;
|
|
76
|
+
/** Best-effort diagnostics sink. */
|
|
77
|
+
log?: (message: string) => void;
|
|
78
|
+
};
|
|
79
|
+
/**
|
|
80
|
+
* @description Sends native notifications and maps their buttons to JavaScript callbacks.
|
|
81
|
+
* @summary Use one centre per process. Action ids are matched against
|
|
82
|
+
* registered global handlers, the notification's own `onAction`, and each
|
|
83
|
+
* button's `onClick`. An id that matches no live notification reaches global
|
|
84
|
+
* handlers only, and dismissed notifications are pruned from the record set.
|
|
85
|
+
* The reserved `default` body-click id maps to the owning notification's first
|
|
86
|
+
* button. `close()` clears the timer and poll loop.
|
|
87
|
+
* @param {NotificationCenterOptions} [options] native module override, poll
|
|
88
|
+
* interval, and diagnostics sink
|
|
89
|
+
* @class NotificationCenter
|
|
90
|
+
* @example
|
|
91
|
+
* import { NotificationCenter } from "@decaf-ts/for-os";
|
|
92
|
+
* const center = new NotificationCenter();
|
|
93
|
+
* const notification = center.notify({
|
|
94
|
+
* title: "Build finished",
|
|
95
|
+
* body: "The native addon is ready.",
|
|
96
|
+
* timeoutMs: 5000,
|
|
97
|
+
* buttons: [{ id: "open", label: "Open" }],
|
|
98
|
+
* });
|
|
99
|
+
* notification.onAction((actionId) => console.log(actionId));
|
|
100
|
+
* center.close();
|
|
101
|
+
*/
|
|
102
|
+
export declare class NotificationCenter {
|
|
103
|
+
private readonly api?;
|
|
104
|
+
private readonly pollIntervalMs;
|
|
105
|
+
private readonly log;
|
|
106
|
+
private readonly globalHandlers;
|
|
107
|
+
private readonly records;
|
|
108
|
+
private poll?;
|
|
109
|
+
private counter;
|
|
110
|
+
private closed;
|
|
111
|
+
constructor(options?: NotificationCenterOptions);
|
|
112
|
+
/** Whether a native notification backend is available. */
|
|
113
|
+
get available(): boolean;
|
|
114
|
+
private native;
|
|
115
|
+
/**
|
|
116
|
+
* Registers a global handler for an action id.
|
|
117
|
+
* @param {string} id action id
|
|
118
|
+
* @param {NotificationActionHandler} handler callback
|
|
119
|
+
* @return {NotificationCenter} this instance
|
|
120
|
+
*/
|
|
121
|
+
registerAction(id: string, handler: NotificationActionHandler): this;
|
|
122
|
+
/**
|
|
123
|
+
* Removes a global action handler.
|
|
124
|
+
* @param {string} id action id
|
|
125
|
+
* @param {NotificationActionHandler} handler callback
|
|
126
|
+
* @return {NotificationCenter} this instance
|
|
127
|
+
*/
|
|
128
|
+
unregisterAction(id: string, handler: NotificationActionHandler): this;
|
|
129
|
+
/**
|
|
130
|
+
* Sends a notification and returns its handle.
|
|
131
|
+
* @param {NotifyOptions} options title, body, timer, and buttons
|
|
132
|
+
* @return {NotificationRecord} the dispatched notification
|
|
133
|
+
* @throws {ValidationError} for missing title/body or invalid options
|
|
134
|
+
* @throws {NativeModuleUnavailableError} when no native backend is available
|
|
135
|
+
*/
|
|
136
|
+
notify(options: NotifyOptions): NotificationRecord;
|
|
137
|
+
/**
|
|
138
|
+
* Sends an appointment-style notification with Accept and See buttons.
|
|
139
|
+
* @param {Omit<NotifyOptions, "buttons">} options notification content
|
|
140
|
+
* @return {NotificationRecord} the dispatched notification
|
|
141
|
+
*/
|
|
142
|
+
notifyAppointment(options: Omit<NotifyOptions, "buttons">): NotificationRecord;
|
|
143
|
+
/**
|
|
144
|
+
* Drains pending native actions immediately.
|
|
145
|
+
* @return {string[]} action ids dispatched in this drain
|
|
146
|
+
*/
|
|
147
|
+
pollActions(): string[];
|
|
148
|
+
/** Clears timers, the poll loop, and retained notification records. */
|
|
149
|
+
close(): void;
|
|
150
|
+
private createRecord;
|
|
151
|
+
private dismiss;
|
|
152
|
+
private removeRecord;
|
|
153
|
+
private dispatch;
|
|
154
|
+
private findRecord;
|
|
155
|
+
private invoke;
|
|
156
|
+
private startPoll;
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* Sends one notification through a short-lived default centre.
|
|
160
|
+
* @param {NotifyOptions} options notification content
|
|
161
|
+
* @return {NotificationRecord} the dispatched notification
|
|
162
|
+
*/
|
|
163
|
+
export declare function notify(options: NotifyOptions): NotificationRecord;
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module for-os.notifications
|
|
3
|
+
* @description Desktop-notification bridge with timers and JavaScript action callbacks.
|
|
4
|
+
* @summary `NotificationCenter` sends notifications through the native addon,
|
|
5
|
+
* exposes action buttons as JavaScript callbacks, and owns the auto-dismiss
|
|
6
|
+
* timer contract. Button delivery is native on Linux (through
|
|
7
|
+
* `notify-send --wait`); macOS and Windows render a plain notification and
|
|
8
|
+
* report that no buttons are available.
|
|
9
|
+
*/
|
|
10
|
+
import type { NativeModule } from "../native/types.d.mts";
|
|
11
|
+
/** Default auto-dismiss delay for a notification, in milliseconds. */
|
|
12
|
+
export declare const DEFAULT_NOTIFICATION_TIMEOUT_MS = 10000;
|
|
13
|
+
/** Callback invoked when a notification action or button is activated. */
|
|
14
|
+
export type NotificationActionHandler = (actionId: string, notification?: NotificationRecord) => void;
|
|
15
|
+
/**
|
|
16
|
+
* One action button rendered on a notification.
|
|
17
|
+
* @summary Button ids match literally. The `default` action id emitted by the
|
|
18
|
+
* native service for a notification-body click is reserved: it resolves to the
|
|
19
|
+
* first button of the owning notification unless a button is explicitly named
|
|
20
|
+
* `default`.
|
|
21
|
+
*/
|
|
22
|
+
export type NotificationButton = {
|
|
23
|
+
/** Stable id reported to the handler. */
|
|
24
|
+
id: string;
|
|
25
|
+
/** Button label rendered by the operating system. */
|
|
26
|
+
label: string;
|
|
27
|
+
/** Optional per-button callback. */
|
|
28
|
+
onClick?: NotificationActionHandler;
|
|
29
|
+
};
|
|
30
|
+
/** Reason a notification is considered dismissed. */
|
|
31
|
+
export type DismissReason = "timer" | "manual";
|
|
32
|
+
/** Public state of a dispatched notification. */
|
|
33
|
+
export type NotificationRecord = {
|
|
34
|
+
/** Stable id generated by the bridge. */
|
|
35
|
+
readonly id: string;
|
|
36
|
+
readonly title: string;
|
|
37
|
+
readonly body: string;
|
|
38
|
+
/** Configured auto-dismiss delay; `0` disables the timer. */
|
|
39
|
+
readonly timeoutMs: number;
|
|
40
|
+
/** Action buttons captured at dispatch; treat this array as read-only. */
|
|
41
|
+
readonly buttons: NotificationButton[];
|
|
42
|
+
/** Whether the operating system accepted the notification. */
|
|
43
|
+
readonly delivered: boolean;
|
|
44
|
+
/** Whether the timer or a manual call marked the notification dismissed. */
|
|
45
|
+
readonly dismissed: boolean;
|
|
46
|
+
/** Marks the notification dismissed and invokes `onDismiss` once. */
|
|
47
|
+
dismiss(reason?: DismissReason): void;
|
|
48
|
+
/** Registers an additional action handler for this notification. */
|
|
49
|
+
onAction(handler: NotificationActionHandler): NotificationRecord;
|
|
50
|
+
};
|
|
51
|
+
/** Options accepted by {@link NotificationCenter.notify}. */
|
|
52
|
+
export type NotifyOptions = {
|
|
53
|
+
title: string;
|
|
54
|
+
body: string;
|
|
55
|
+
/**
|
|
56
|
+
* Auto-dismiss delay in milliseconds. Defaults to
|
|
57
|
+
* {@link DEFAULT_NOTIFICATION_TIMEOUT_MS}; `0` disables the timer. The native
|
|
58
|
+
* host honours the delay where its notification service supports expiry
|
|
59
|
+
* (Linux, Windows); macOS applies the system dismissal policy while the
|
|
60
|
+
* bridge still tracks the timer locally.
|
|
61
|
+
*/
|
|
62
|
+
timeoutMs?: number;
|
|
63
|
+
/** Action buttons; native delivery is Linux-only. */
|
|
64
|
+
buttons?: NotificationButton[];
|
|
65
|
+
/** Notification-level action callback. */
|
|
66
|
+
onAction?: NotificationActionHandler;
|
|
67
|
+
/** Called once when the timer fires or {@link NotificationRecord.dismiss} runs. */
|
|
68
|
+
onDismiss?: (reason: DismissReason, notification: NotificationRecord) => void;
|
|
69
|
+
};
|
|
70
|
+
/** Construction options for {@link NotificationCenter}. */
|
|
71
|
+
export type NotificationCenterOptions = {
|
|
72
|
+
/** Native module override (tests/embedding); defaults to the built addon. */
|
|
73
|
+
api?: NativeModule;
|
|
74
|
+
/** Global action dispatch interval (defaults to 100 ms). */
|
|
75
|
+
pollIntervalMs?: number;
|
|
76
|
+
/** Best-effort diagnostics sink. */
|
|
77
|
+
log?: (message: string) => void;
|
|
78
|
+
};
|
|
79
|
+
/**
|
|
80
|
+
* @description Sends native notifications and maps their buttons to JavaScript callbacks.
|
|
81
|
+
* @summary Use one centre per process. Action ids are matched against
|
|
82
|
+
* registered global handlers, the notification's own `onAction`, and each
|
|
83
|
+
* button's `onClick`. An id that matches no live notification reaches global
|
|
84
|
+
* handlers only, and dismissed notifications are pruned from the record set.
|
|
85
|
+
* The reserved `default` body-click id maps to the owning notification's first
|
|
86
|
+
* button. `close()` clears the timer and poll loop.
|
|
87
|
+
* @param {NotificationCenterOptions} [options] native module override, poll
|
|
88
|
+
* interval, and diagnostics sink
|
|
89
|
+
* @class NotificationCenter
|
|
90
|
+
* @example
|
|
91
|
+
* import { NotificationCenter } from "@decaf-ts/for-os";
|
|
92
|
+
* const center = new NotificationCenter();
|
|
93
|
+
* const notification = center.notify({
|
|
94
|
+
* title: "Build finished",
|
|
95
|
+
* body: "The native addon is ready.",
|
|
96
|
+
* timeoutMs: 5000,
|
|
97
|
+
* buttons: [{ id: "open", label: "Open" }],
|
|
98
|
+
* });
|
|
99
|
+
* notification.onAction((actionId) => console.log(actionId));
|
|
100
|
+
* center.close();
|
|
101
|
+
*/
|
|
102
|
+
export declare class NotificationCenter {
|
|
103
|
+
private readonly api?;
|
|
104
|
+
private readonly pollIntervalMs;
|
|
105
|
+
private readonly log;
|
|
106
|
+
private readonly globalHandlers;
|
|
107
|
+
private readonly records;
|
|
108
|
+
private poll?;
|
|
109
|
+
private counter;
|
|
110
|
+
private closed;
|
|
111
|
+
constructor(options?: NotificationCenterOptions);
|
|
112
|
+
/** Whether a native notification backend is available. */
|
|
113
|
+
get available(): boolean;
|
|
114
|
+
private native;
|
|
115
|
+
/**
|
|
116
|
+
* Registers a global handler for an action id.
|
|
117
|
+
* @param {string} id action id
|
|
118
|
+
* @param {NotificationActionHandler} handler callback
|
|
119
|
+
* @return {NotificationCenter} this instance
|
|
120
|
+
*/
|
|
121
|
+
registerAction(id: string, handler: NotificationActionHandler): this;
|
|
122
|
+
/**
|
|
123
|
+
* Removes a global action handler.
|
|
124
|
+
* @param {string} id action id
|
|
125
|
+
* @param {NotificationActionHandler} handler callback
|
|
126
|
+
* @return {NotificationCenter} this instance
|
|
127
|
+
*/
|
|
128
|
+
unregisterAction(id: string, handler: NotificationActionHandler): this;
|
|
129
|
+
/**
|
|
130
|
+
* Sends a notification and returns its handle.
|
|
131
|
+
* @param {NotifyOptions} options title, body, timer, and buttons
|
|
132
|
+
* @return {NotificationRecord} the dispatched notification
|
|
133
|
+
* @throws {ValidationError} for missing title/body or invalid options
|
|
134
|
+
* @throws {NativeModuleUnavailableError} when no native backend is available
|
|
135
|
+
*/
|
|
136
|
+
notify(options: NotifyOptions): NotificationRecord;
|
|
137
|
+
/**
|
|
138
|
+
* Sends an appointment-style notification with Accept and See buttons.
|
|
139
|
+
* @param {Omit<NotifyOptions, "buttons">} options notification content
|
|
140
|
+
* @return {NotificationRecord} the dispatched notification
|
|
141
|
+
*/
|
|
142
|
+
notifyAppointment(options: Omit<NotifyOptions, "buttons">): NotificationRecord;
|
|
143
|
+
/**
|
|
144
|
+
* Drains pending native actions immediately.
|
|
145
|
+
* @return {string[]} action ids dispatched in this drain
|
|
146
|
+
*/
|
|
147
|
+
pollActions(): string[];
|
|
148
|
+
/** Clears timers, the poll loop, and retained notification records. */
|
|
149
|
+
close(): void;
|
|
150
|
+
private createRecord;
|
|
151
|
+
private dismiss;
|
|
152
|
+
private removeRecord;
|
|
153
|
+
private dispatch;
|
|
154
|
+
private findRecord;
|
|
155
|
+
private invoke;
|
|
156
|
+
private startPoll;
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* Sends one notification through a short-lived default centre.
|
|
160
|
+
* @param {NotifyOptions} options notification content
|
|
161
|
+
* @return {NotificationRecord} the dispatched notification
|
|
162
|
+
*/
|
|
163
|
+
export declare function notify(options: NotifyOptions): NotificationRecord;
|