@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.
Files changed (77) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +380 -2
  3. package/lib/cjs/errors.cjs +73 -0
  4. package/lib/cjs/errors.cjs.map +1 -0
  5. package/lib/cjs/index.cjs +46 -0
  6. package/lib/cjs/index.cjs.map +1 -0
  7. package/lib/cjs/native/icons.cjs +123 -0
  8. package/lib/cjs/native/icons.cjs.map +1 -0
  9. package/lib/cjs/native/loader.cjs +123 -0
  10. package/lib/cjs/native/loader.cjs.map +1 -0
  11. package/lib/cjs/native/types.cjs +4 -0
  12. package/lib/cjs/native/types.cjs.map +1 -0
  13. package/lib/cjs/notifications/NotificationCenter.cjs +328 -0
  14. package/lib/cjs/notifications/NotificationCenter.cjs.map +1 -0
  15. package/lib/cjs/tray/TrayIcon.cjs +367 -0
  16. package/lib/cjs/tray/TrayIcon.cjs.map +1 -0
  17. package/lib/cjs/tray/assets.cjs +31 -0
  18. package/lib/cjs/tray/assets.cjs.map +1 -0
  19. package/lib/esm/errors.js +65 -0
  20. package/lib/esm/errors.js.map +1 -0
  21. package/lib/esm/index.js +28 -0
  22. package/lib/esm/index.js.map +1 -0
  23. package/lib/esm/native/icons.js +117 -0
  24. package/lib/esm/native/icons.js.map +1 -0
  25. package/lib/esm/native/loader.js +116 -0
  26. package/lib/esm/native/loader.js.map +1 -0
  27. package/lib/esm/native/types.js +8 -0
  28. package/lib/esm/native/types.js.map +1 -0
  29. package/lib/esm/notifications/NotificationCenter.js +322 -0
  30. package/lib/esm/notifications/NotificationCenter.js.map +1 -0
  31. package/lib/esm/tray/TrayIcon.js +362 -0
  32. package/lib/esm/tray/TrayIcon.js.map +1 -0
  33. package/lib/esm/tray/assets.js +26 -0
  34. package/lib/esm/tray/assets.js.map +1 -0
  35. package/lib/types/errors.d.cts +56 -0
  36. package/lib/types/errors.d.mts +56 -0
  37. package/lib/types/index.d.cts +27 -0
  38. package/lib/types/index.d.mts +27 -0
  39. package/lib/types/native/icons.d.cts +71 -0
  40. package/lib/types/native/icons.d.mts +71 -0
  41. package/lib/types/native/loader.d.cts +37 -0
  42. package/lib/types/native/loader.d.mts +37 -0
  43. package/lib/types/native/types.d.cts +104 -0
  44. package/lib/types/native/types.d.mts +104 -0
  45. package/lib/types/notifications/NotificationCenter.d.cts +163 -0
  46. package/lib/types/notifications/NotificationCenter.d.mts +163 -0
  47. package/lib/types/tray/TrayIcon.d.cts +174 -0
  48. package/lib/types/tray/TrayIcon.d.mts +174 -0
  49. package/lib/types/tray/assets.d.cts +25 -0
  50. package/lib/types/tray/assets.d.mts +25 -0
  51. package/native/tray-icon-node/Cargo.lock +1511 -0
  52. package/native/tray-icon-node/Cargo.toml +45 -0
  53. package/native/tray-icon-node/Cross.toml +10 -0
  54. package/native/tray-icon-node/LICENSE +21 -0
  55. package/native/tray-icon-node/UPSTREAM-README.md +281 -0
  56. package/native/tray-icon-node/UPSTREAM.md +213 -0
  57. package/native/tray-icon-node/build-manifest.json +16 -0
  58. package/native/tray-icon-node/build.rs +5 -0
  59. package/native/tray-icon-node/index.d.ts +368 -0
  60. package/native/tray-icon-node/index.js +609 -0
  61. package/native/tray-icon-node/package.json +55 -0
  62. package/native/tray-icon-node/rustfmt.toml +31 -0
  63. package/native/tray-icon-node/source-manifest.json +30 -0
  64. package/native/tray-icon-node/src/common.rs +101 -0
  65. package/native/tray-icon-node/src/icon.rs +255 -0
  66. package/native/tray-icon-node/src/lib.rs +449 -0
  67. package/native/tray-icon-node/src/menu.rs +849 -0
  68. package/native/tray-icon-node/src/tray.rs +251 -0
  69. package/native/tray-icon-node/tray-icon-node.linux-x64-gnu.node +0 -0
  70. package/package.json +131 -4
  71. package/scripts/for-os-build.mjs +60 -0
  72. package/scripts/for-os-init.mjs +327 -0
  73. package/scripts/for-os-install.mjs +47 -0
  74. package/scripts/for-os-integration.mjs +137 -0
  75. package/scripts/for-os-integrity.mjs +51 -0
  76. package/scripts/for-os-package.mjs +49 -0
  77. package/scripts/lib/native.mjs +591 -0
@@ -0,0 +1,251 @@
1
+ use crate::common::{MouseButton, MouseButtonState, Rect};
2
+ use crate::icon::Icon;
3
+ use crate::menu::Menu;
4
+ use napi::bindgen_prelude::*;
5
+ use napi_derive::napi;
6
+ use tray_icon::{
7
+ TrayIcon as RawTrayIcon, TrayIconBuilder as RawTrayIconBuilder,
8
+ TrayIconEvent as RawTrayIconEvent,
9
+ };
10
+
11
+ #[napi(object)]
12
+ pub struct TrayIconEvent {
13
+ pub event_type: String,
14
+ pub id: String,
15
+ pub x: f64,
16
+ pub y: f64,
17
+ pub icon_rect: Rect,
18
+ pub button: MouseButton,
19
+ pub button_state: MouseButtonState,
20
+ }
21
+
22
+ impl From<RawTrayIconEvent> for TrayIconEvent {
23
+ fn from(event: RawTrayIconEvent) -> Self {
24
+ match event {
25
+ RawTrayIconEvent::Click {
26
+ id,
27
+ position,
28
+ rect,
29
+ button,
30
+ button_state,
31
+ } => Self {
32
+ event_type: "click".to_string(),
33
+ id: id.0,
34
+ x: position.x,
35
+ y: position.y,
36
+ icon_rect: rect.into(),
37
+ button: button.into(),
38
+ button_state: button_state.into(),
39
+ },
40
+ RawTrayIconEvent::DoubleClick {
41
+ id,
42
+ position,
43
+ rect,
44
+ button,
45
+ } => Self {
46
+ event_type: "double-click".to_string(),
47
+ id: id.0,
48
+ x: position.x,
49
+ y: position.y,
50
+ icon_rect: rect.into(),
51
+ button: button.into(),
52
+ button_state: MouseButtonState::Down,
53
+ },
54
+ RawTrayIconEvent::Enter { id, position, rect } => Self {
55
+ event_type: "enter".to_string(),
56
+ id: id.0,
57
+ x: position.x,
58
+ y: position.y,
59
+ icon_rect: rect.into(),
60
+ button: MouseButton::Left,
61
+ button_state: MouseButtonState::Up,
62
+ },
63
+ RawTrayIconEvent::Move { id, position, rect } => Self {
64
+ event_type: "move".to_string(),
65
+ id: id.0,
66
+ x: position.x,
67
+ y: position.y,
68
+ icon_rect: rect.into(),
69
+ button: MouseButton::Left,
70
+ button_state: MouseButtonState::Up,
71
+ },
72
+ RawTrayIconEvent::Leave { id, position, rect } => Self {
73
+ event_type: "leave".to_string(),
74
+ id: id.0,
75
+ x: position.x,
76
+ y: position.y,
77
+ icon_rect: rect.into(),
78
+ button: MouseButton::Left,
79
+ button_state: MouseButtonState::Up,
80
+ },
81
+ _ => Self {
82
+ event_type: "unknown".to_string(),
83
+ id: String::new(),
84
+ x: 0.0,
85
+ y: 0.0,
86
+ icon_rect: Rect {
87
+ x: 0.0,
88
+ y: 0.0,
89
+ width: 0.0,
90
+ height: 0.0,
91
+ },
92
+ button: MouseButton::Left,
93
+ button_state: MouseButtonState::Up,
94
+ },
95
+ }
96
+ }
97
+ }
98
+
99
+ #[napi]
100
+ pub fn poll_tray_events() -> Option<TrayIconEvent> {
101
+ tray_icon::TrayIconEvent::receiver()
102
+ .try_recv()
103
+ .ok()
104
+ .map(std::convert::Into::into)
105
+ }
106
+
107
+ #[napi]
108
+ pub struct TrayIcon(Option<RawTrayIcon>);
109
+
110
+ #[napi]
111
+ impl TrayIcon {
112
+ /// Sets the tray icon image.
113
+ ///
114
+ /// # Errors
115
+ ///
116
+ /// Returns an error if the OS fails to update the icon.
117
+ #[napi]
118
+ pub fn set_icon(&mut self, icon: Option<&Icon>) -> Result<()> {
119
+ if let Some(tray) = &self.0 {
120
+ tray.set_icon(icon.map(|i| i.inner.clone()))
121
+ .map_err(|e| Error::from_reason(format!("Failed to set icon: {e}")))?;
122
+ }
123
+ Ok(())
124
+ }
125
+
126
+ /// Sets the tooltip text shown on hover.
127
+ ///
128
+ /// # Errors
129
+ ///
130
+ /// Returns an error if the OS fails to update the tooltip.
131
+ #[napi]
132
+ pub fn set_tooltip(&mut self, tooltip: Option<String>) -> Result<()> {
133
+ if let Some(tray) = &self.0 {
134
+ tray.set_tooltip(tooltip)
135
+ .map_err(|e| Error::from_reason(format!("Failed to set tooltip: {e}")))?;
136
+ }
137
+ Ok(())
138
+ }
139
+
140
+ /// Sets the title text shown next to the tray icon (macOS only).
141
+ ///
142
+ /// # Errors
143
+ ///
144
+ /// This method currently never returns an error but the `Result` type
145
+ /// is provided for future-proofing and API consistency.
146
+ #[napi]
147
+ pub fn set_title(&mut self, title: Option<String>) -> Result<()> {
148
+ if let Some(tray) = &self.0 {
149
+ tray.set_title(title);
150
+ }
151
+ Ok(())
152
+ }
153
+
154
+ /// Sets the visibility of the tray icon.
155
+ ///
156
+ /// # Errors
157
+ ///
158
+ /// Returns an error if the OS fails to change visibility.
159
+ #[napi]
160
+ pub fn set_visible(&mut self, visible: bool) -> Result<()> {
161
+ if let Some(tray) = &self.0 {
162
+ tray.set_visible(visible)
163
+ .map_err(|e| Error::from_reason(format!("Failed to set visibility: {e}")))?;
164
+ }
165
+ Ok(())
166
+ }
167
+ }
168
+
169
+ #[napi]
170
+ #[derive(Clone)]
171
+ pub struct TrayIconBuilder {
172
+ icon: Option<tray_icon::Icon>,
173
+ tooltip: Option<String>,
174
+ title: Option<String>,
175
+ menu: Option<tray_icon::menu::Menu>,
176
+ }
177
+
178
+ #[napi]
179
+ impl TrayIconBuilder {
180
+ #[napi(constructor)]
181
+ pub fn new() -> Self {
182
+ Self {
183
+ icon: None,
184
+ tooltip: None,
185
+ title: None,
186
+ menu: None,
187
+ }
188
+ }
189
+
190
+ #[napi]
191
+ #[must_use]
192
+ pub fn with_icon(&mut self, icon: &Icon) -> Self {
193
+ self.icon = Some(icon.inner.clone());
194
+ self.clone()
195
+ }
196
+
197
+ #[napi]
198
+ #[must_use]
199
+ pub fn with_tooltip(&mut self, tooltip: String) -> Self {
200
+ self.tooltip = Some(tooltip);
201
+ self.clone()
202
+ }
203
+
204
+ #[napi]
205
+ #[must_use]
206
+ pub fn with_title(&mut self, title: String) -> Self {
207
+ self.title = Some(title);
208
+ self.clone()
209
+ }
210
+
211
+ #[napi]
212
+ #[must_use]
213
+ pub fn with_menu(&mut self, menu: &Menu) -> Self {
214
+ self.menu = Some(menu.inner.clone());
215
+ self.clone()
216
+ }
217
+
218
+ /// Builds the tray icon.
219
+ ///
220
+ /// # Errors
221
+ ///
222
+ /// Returns an error if the underlying OS fails to create the tray icon
223
+ /// (e.g., no system tray available, invalid icon data).
224
+ #[napi]
225
+ pub fn build(&self) -> Result<TrayIcon> {
226
+ let mut builder = RawTrayIconBuilder::new();
227
+ if let Some(icon) = &self.icon {
228
+ builder = builder.with_icon(icon.clone());
229
+ }
230
+ if let Some(tooltip) = &self.tooltip {
231
+ builder = builder.with_tooltip(tooltip);
232
+ }
233
+ if let Some(title) = &self.title {
234
+ builder = builder.with_title(title);
235
+ }
236
+ if let Some(menu) = &self.menu {
237
+ builder = builder.with_menu(Box::new(menu.clone()));
238
+ }
239
+
240
+ let tray = builder
241
+ .build()
242
+ .map_err(|e| Error::from_reason(format!("Failed to build tray icon: {e}")))?;
243
+ Ok(TrayIcon(Some(tray)))
244
+ }
245
+ }
246
+
247
+ impl Default for TrayIconBuilder {
248
+ fn default() -> Self {
249
+ Self::new()
250
+ }
251
+ }
package/package.json CHANGED
@@ -1,6 +1,133 @@
1
1
  {
2
2
  "name": "@decaf-ts/for-os",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.7",
4
+ "description": "Native operating-system bridges for Decaf.ts: Rust system tray and desktop notifications exposed to TypeScript, with runtime icon switching, notification timers, and JavaScript button mapping",
5
+ "type": "module",
6
+ "exports": {
7
+ ".": {
8
+ "import": {
9
+ "types": "./lib/types/index.d.mts",
10
+ "default": "./lib/esm/index.js"
11
+ },
12
+ "require": {
13
+ "types": "./lib/types/index.d.cts",
14
+ "default": "./lib/cjs/index.cjs"
15
+ },
16
+ "default": "./lib/esm/index.js"
17
+ }
18
+ },
19
+ "main": "./lib/cjs/index.cjs",
20
+ "module": "./lib/esm/index.js",
21
+ "types": "./lib/types/index.d.mts",
22
+ "sideEffects": false,
23
+ "scripts": {
24
+ "do-install": "NPM_TOKEN=$(cat .npmtoken) npm install",
25
+ "update-dependencies": "PREFIX=\"decaf-ts\"; npm ls | grep \"$PREFIX\" | awk -F/ '{print $NF}' | sed 's/@.*//' | xargs -I package npm update @\"$PREFIX\"/package",
26
+ "update-scripts": "npx update-scripts",
27
+ "release": "tag-release",
28
+ "on-first-run": "npx update-scripts --boot",
29
+ "set-git-auth": "decaf utils credentials git-helper",
30
+ "flash-forward": "npx npm-check-updates -u && npm run do-install",
31
+ "reset": "rm -rf * && git checkout . && git pull && npm run do-install",
32
+ "build": "build-scripts --dev",
33
+ "build:prod": "build-scripts --prod",
34
+ "postinstall": "node scripts/for-os-install.mjs",
35
+ "for-os:init": "node scripts/for-os-init.mjs",
36
+ "for-os:init:check": "node scripts/for-os-init.mjs --check",
37
+ "for-os:build": "node scripts/for-os-build.mjs",
38
+ "for-os:build:check": "node scripts/for-os-build.mjs --check",
39
+ "for-os:package:check": "node scripts/for-os-package.mjs",
40
+ "for-os:package:prepare": "node scripts/for-os-package.mjs --write",
41
+ "for-os:install": "node scripts/for-os-install.mjs",
42
+ "for-os:install:required": "node scripts/for-os-install.mjs --require-build",
43
+ "for-os:integrity:record": "node scripts/for-os-integrity.mjs",
44
+ "for-os:integrity:check": "node scripts/for-os-integrity.mjs --check",
45
+ "for-os:test:rust": "cargo test --locked --manifest-path native/tray-icon-node/Cargo.toml",
46
+ "for-os:integration": "npm run build && node scripts/for-os-integration.mjs",
47
+ "for-os:smoke": "npm run build && node scripts/for-os-integration.mjs --smoke",
48
+ "for-os:buttons": "npm run build && node scripts/for-os-integration.mjs --buttons",
49
+ "test": "npm run test:all",
50
+ "test:unit": "jest --testPathPatterns=\"/tests/unit\" --passWithNoTests --detectOpenHandles",
51
+ "test:integration": "jest --testPathPatterns=\"/tests/(integration)\" --passWithNoTests --detectOpenHandles",
52
+ "test:all": "jest --testPathPatterns=\"/tests\" --passWithNoTests --detectOpenHandles",
53
+ "test:dist": "TEST_TARGET=lib npm run test:all && TEST_TARGET=dist npm run test:all",
54
+ "test:circular": "dpdm -T --no-warning --no-tree ./src/index.ts",
55
+ "prepare-it-tests": "echo \"prepare-it-tests: run npm run for-os:init\"",
56
+ "coverage": "rimraf ./workdocs/reports/data/*.json && npm run test:all -- --coverage --config=./workdocs/reports/jest.coverage.config.cjs",
57
+ "lint": "eslint .",
58
+ "lint-fix": "eslint --fix .",
59
+ "prepare-pr": "npm run lint-fix && npm run build:prod && npm run coverage && npm run docs",
60
+ "prepare-release": "npm run lint-fix && npm run build:prod && npm run for-os:integrity:record && npm run coverage && npm run test:dist && npm run docs && npm run for-os:integrity:check",
61
+ "repo:init": "codex exec \"$(cat ./.codex/prompts/repo-setup.md)\nbase_path is `./`, initialize the repository\" -s workspace-write",
62
+ "repo:setup": "codex exec \"$(cat ./.codex/prompts/repo-setup.md)\nbase_path is ./\" -s workspace-write",
63
+ "repo:doc": "codex exec \"$(cat ./.codex/prompts/doc.md) $(cat ./.codex/prompts/bulk-docs.md)\nbase_path is ./\" -s workspace-write",
64
+ "repo:tests": "codex exec \"$(cat ./.codex/prompts/bulk-tests.md)\nbase_path is ./ and coverage is 95%\" -s workspace-write",
65
+ "repo:readme": "codex exec \"$(cat ./.codex/prompts/update-readme.md)\nbase_path is ./\" -s workspace-write",
66
+ "repo:pr": "npm run repo:doc && npm run repo:tests && npm run repo:readme",
67
+ "drawings": "for FILE in workdocs/drawings/*.drawio; do echo \"converting $FILE to image...\" && docker run --rm -v $(pwd):/data rlespinasse/drawio-export --format png $FILE; done && cp -rf workdocs/drawings/export/* workdocs/resources/",
68
+ "uml": "cd workdocs/uml && for FILE in ./*.puml; do docker run --rm -v $(pwd):/work -w /work miy4/plantuml -DPLANTUML_LIMIT_SIZE=8192 -tpng $FILE; done && cd ../.. && cp -fr workdocs/uml/*.png workdocs/resources/",
69
+ "docs": "npx rimraf ./docs && mkdir docs && build-scripts --docs",
70
+ "publish-docs": "docker run -it --rm --user $(id -u):$(id -g) -v \"$(pwd)/workdocs/confluence:/content\" -e ATLASSIAN_API_TOKEN=\"$(DECAF_BANNER=false decaf utils credentials get --name confluence --logLevel error)\" ghcr.io/markdown-confluence/publish:latest"
71
+ },
72
+ "repository": {
73
+ "type": "git",
74
+ "url": "git+https://github.com/decaf-ts/for-os.git"
75
+ },
76
+ "engines": {
77
+ "node": ">=20.0.0",
78
+ "npm": ">=10.0.0"
79
+ },
80
+ "files": [
81
+ "lib",
82
+ "native/tray-icon-node",
83
+ "scripts",
84
+ "!native/tray-icon-node/target",
85
+ "!native/tray-icon-node/target/**"
86
+ ],
87
+ "keywords": [
88
+ "decaf-ts",
89
+ "os",
90
+ "native",
91
+ "rust",
92
+ "napi",
93
+ "system-tray",
94
+ "systray",
95
+ "tray-icon",
96
+ "notifications",
97
+ "desktop-notifications",
98
+ "typescript",
99
+ "node",
100
+ "cross-platform"
101
+ ],
102
+ "author": "Tiago Venceslau",
103
+ "license": "MIT",
104
+ "bugs": {
105
+ "url": "https://github.com/decaf-ts/for-os/issues"
106
+ },
107
+ "homepage": "https://github.com/decaf-ts/for-os#readme",
108
+ "dependencies": {
109
+ "@decaf-ts/db-decorators": "^0.21.0",
110
+ "@decaf-ts/decorator-validation": "^1.25.0",
111
+ "@decaf-ts/logging": "^0.30.3"
112
+ },
113
+ "devDependencies": {
114
+ "@decaf-ts/for-testing": "^1.3.7",
115
+ "@decaf-ts/utils": "^2.3.0",
116
+ "@types/jest": "^30.0.0"
117
+ },
118
+ "overrides": {
119
+ "open": "^11.0.0",
120
+ "glob": "^14.0.4",
121
+ "minimatch": "^11.0.5",
122
+ "eslint": {
123
+ "minimatch": "^11.0.5"
124
+ },
125
+ "dpdm": {
126
+ "glob": "^14.0.4",
127
+ "minimatch": "^11.0.5"
128
+ },
129
+ "typescript-eslint": {
130
+ "minimatch": "^11.0.5"
131
+ }
132
+ }
133
+ }
@@ -0,0 +1,60 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Explicit build entry point for the vendored `tray-icon-node` addon.
4
+ *
5
+ * Verifies `native/tray-icon-node` against `source-manifest.json`, then runs
6
+ * `cargo build --release --locked` and writes `build-manifest.json` next to the
7
+ * copied binary. `--check` reports the verified source/build state only.
8
+ * @module scripts/for-os-build
9
+ */
10
+ import { buildNative, inspectNative, verifySourceTree } from "./lib/native.mjs";
11
+
12
+ const process = globalThis.process;
13
+
14
+ const HELP = `Usage: node scripts/for-os-build.mjs [--check] [--target <rust-triple>]
15
+
16
+ Builds the vendored tray-icon-node native addon from native/tray-icon-node
17
+ with cargo and writes build-manifest.json next to the binary.
18
+
19
+ --check verify the native source tree and report the existing build
20
+ --target build for one of the supported Rust target triples
21
+ --help show this help
22
+
23
+ Prerequisites: Rust stable (cargo, rustc) and, on Linux, the GTK/appindicator
24
+ development headers. Run \`npm run for-os:init\` to install them.`;
25
+
26
+ function main(argv) {
27
+ if (argv.includes("--help") || argv.includes("-h")) {
28
+ console.log(HELP);
29
+ return 0;
30
+ }
31
+ const targetIndex = argv.indexOf("--target");
32
+ const target = targetIndex >= 0 ? argv[targetIndex + 1] : undefined;
33
+ const unknown = argv.filter(
34
+ (argument, index) =>
35
+ argument !== "--check" &&
36
+ argument !== "--target" &&
37
+ !(targetIndex >= 0 && index === targetIndex + 1)
38
+ );
39
+ if (targetIndex >= 0 && !target) unknown.push("--target");
40
+ if (unknown.length) {
41
+ console.error(`Unknown argument "${unknown[0]}".\n\n${HELP}`);
42
+ return 2;
43
+ }
44
+ try {
45
+ if (argv.includes("--check")) {
46
+ inspectNative();
47
+ return 0;
48
+ }
49
+ verifySourceTree();
50
+ buildNative({ target });
51
+ return 0;
52
+ } catch (failure) {
53
+ console.error(
54
+ `for-os-build: ${String(failure instanceof Error ? failure.message : failure)}`
55
+ );
56
+ return 1;
57
+ }
58
+ }
59
+
60
+ process.exitCode = main(process.argv.slice(2));