@silkui/core 0.1.2 → 0.1.3

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/README.md CHANGED
@@ -115,10 +115,40 @@ through the tree.
115
115
  | `layout` | `bounds`: where layout put the node, in window pixels |
116
116
  | `transitionrun`, `transitionstart`, `transitionend`, `transitioncancel` | `propertyName`, `elapsedTime` |
117
117
  | `animationstart`, `animationiteration`, `animationend`, `animationcancel` | `animationName`, `elapsedTime` |
118
+ | `dragenter`, `dragover`, `dragleave`, `drop` | `clientX`, `clientY`, `dataTransfer` (files dragged in from other apps) |
118
119
 
119
120
  A listener that throws does not stop the dispatch. `setErrorHandler(handler)` receives the
120
121
  exception; without one the host reports it.
121
122
 
123
+ ### The desktop
124
+
125
+ Files dragged in from other apps fire `dragenter`, `dragover`, `dragleave` and `drop` on the
126
+ node under them, and bubble, as on the web. `event.dataTransfer.types` is `["Files"]` while
127
+ they are over the window, and `drop` lists them in `dataTransfer.files`, each with its `name`
128
+ and its `path` on disk.
129
+
130
+ ```ts
131
+ zone.addEventListener("drop", (event) => open(event.dataTransfer.files[0].path));
132
+ ```
133
+
134
+ `Notification` is the web's: `new Notification("Built", { body: "In 2 s" })`, with `onclick`.
135
+ Permission is always granted. Two things the web has no API for come from the package:
136
+
137
+ ```ts
138
+ import { setTray, registerShortcut } from "@silkui/core";
139
+
140
+ setTray({
141
+ icon: { width: 32, height: 32, data: pixels }, // RGBA, as an ImageData
142
+ tooltip: "Builds",
143
+ menu: [{ label: "Build now", click: build }, { type: "separator" }, { label: "Quit", click: quit }],
144
+ });
145
+ registerShortcut("Mod+Shift+B", build); // Mod is Command on macOS, Control elsewhere
146
+ ```
147
+
148
+ `setTray` and `registerShortcut` resolve to whether the system took them. A shortcut works
149
+ whichever app has focus; another app may hold it, and Wayland has none. `removeTray()` and
150
+ `unregisterShortcut(accelerator)` undo them.
151
+
122
152
  ### Attributes and accessibility
123
153
 
124
154
  `setAttribute(name, value)` sets the tree's attributes: `tabIndex`, `disabled`, `label`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@silkui/core",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "The node and event API of a Silk UI tree for JavaScript applications that run on the embedded SilkJS engine",
5
5
  "repository": {
6
6
  "type": "git",
package/src/index.d.ts CHANGED
@@ -298,6 +298,10 @@ export interface EventMap {
298
298
  animationiteration: AnimationEvent;
299
299
  animationend: AnimationEvent;
300
300
  animationcancel: AnimationEvent;
301
+ dragenter: DragEvent;
302
+ dragover: DragEvent;
303
+ dragleave: DragEvent;
304
+ drop: DragEvent;
301
305
  }
302
306
 
303
307
  export function createNode(kind: "text"): Text;
@@ -354,3 +358,80 @@ export function parseMarkdown(text: string, options?: MarkdownOptions): import("
354
358
 
355
359
  /** What happens to an exception a listener throws. Without a handler, the host reports it. */
356
360
  export function setErrorHandler(handler: ((error: unknown) => void) | null): void;
361
+
362
+ /** A file dragged in from the desktop, as the web's `File`, with its `path` on disk. */
363
+ export class DroppedFile {
364
+ readonly name: string;
365
+ readonly path: string;
366
+ readonly type: string;
367
+ }
368
+
369
+ /** What a file drag carries. `files` is filled in `drop`, as on the web. */
370
+ export class DataTransfer {
371
+ readonly files: DroppedFile[];
372
+ readonly items: { kind: "file"; type: string; getAsFile(): DroppedFile }[];
373
+ readonly types: string[];
374
+ dropEffect: string;
375
+ effectAllowed: string;
376
+ getData(format: string): string;
377
+ }
378
+
379
+ /** Files dragged from another app over the window (`dragenter`, `dragover`, `dragleave`, `drop`). */
380
+ export interface DragEvent extends Event {
381
+ clientX: number;
382
+ clientY: number;
383
+ x: number;
384
+ y: number;
385
+ dataTransfer: DataTransfer;
386
+ }
387
+
388
+ export interface NotificationOptions {
389
+ body?: string;
390
+ tag?: string;
391
+ data?: unknown;
392
+ }
393
+
394
+ /** A desktop notification, as the web's. Permission is always granted. */
395
+ export class Notification {
396
+ static readonly permission: "granted";
397
+ static requestPermission(callback?: (permission: "granted") => void): Promise<"granted">;
398
+ constructor(title: string, options?: NotificationOptions);
399
+ readonly title: string;
400
+ readonly body: string;
401
+ readonly tag: string;
402
+ readonly data: unknown;
403
+ onclick: ((event: { type: "click"; target: Notification }) => void) | null;
404
+ onshow: ((event: { type: "show"; target: Notification }) => void) | null;
405
+ onerror: ((event: { type: "error"; target: Notification }) => void) | null;
406
+ onclose: ((event: { type: "close"; target: Notification }) => void) | null;
407
+ close(): void;
408
+ addEventListener(type: "click" | "show" | "error" | "close", listener: (event: { type: string; target: Notification }) => void): void;
409
+ removeEventListener(type: "click" | "show" | "error" | "close", listener: (event: { type: string; target: Notification }) => void): void;
410
+ }
411
+
412
+ export type TrayMenuItem =
413
+ | { label: string; click?: () => void; enabled?: boolean; checked?: boolean }
414
+ | { type: "separator" }
415
+ | { label: string; submenu: TrayMenuItem[] };
416
+
417
+ export interface TrayOptions {
418
+ /** RGBA pixels, as an `ImageData`. 32 by 32 looks right everywhere. */
419
+ icon: { width: number; height: number; data: ArrayLike<number> };
420
+ tooltip?: string;
421
+ /** macOS draws the icon from its alpha, in the menu bar's colours. */
422
+ template?: boolean;
423
+ menu?: TrayMenuItem[];
424
+ /** Runs on a click when there is no menu. `button` is `MouseEvent.button`'s. */
425
+ onClick?: (event: { button: number }) => void;
426
+ }
427
+
428
+ /** Shows an icon in the system tray; calling it again replaces it. Resolves to whether it shows. */
429
+ export function setTray(options: TrayOptions): Promise<boolean>;
430
+ export function removeTray(): void;
431
+
432
+ /**
433
+ * Runs `callback` when `accelerator` (`"Mod+Shift+K"`; `Mod` is Command on macOS, Control
434
+ * elsewhere) is pressed, whichever app has focus. Resolves to whether the system took it.
435
+ */
436
+ export function registerShortcut(accelerator: string, callback: () => void): Promise<boolean>;
437
+ export function unregisterShortcut(accelerator: string): void;
package/src/index.js CHANGED
@@ -26,13 +26,15 @@ const CLICK = KIND_OF.get("click");
26
26
  // As on the web: these reach the target alone.
27
27
  const NO_BUBBLE = new Set(["pointerenter", "pointerleave", "focus", "blur", "scroll", "layout", "load", "error"]);
28
28
  // The tree has a default action to skip for these.
29
- const CANCELABLE = new Set(["pointerdown", "pointerup", "click", "wheel", "keydown", "keyup"]);
29
+ const CANCELABLE = new Set(["pointerdown", "pointerup", "click", "wheel", "keydown", "keyup", "dragenter", "dragover", "drop"]);
30
+ // Files dragged from the desktop: the host dispatches these itself, so nodes need no flag.
31
+ const DRAG_TYPES = new Set(["dragenter", "dragover", "dragleave", "drop"]);
30
32
 
31
33
  // Properties whose numbers are not lengths. Every other number is CSS pixels.
32
34
  const UNITLESS = new Set([
33
35
  "opacity", "flexGrow", "flexShrink", "flex", "order", "zIndex", "fontWeight", "lineHeight",
34
36
  "aspectRatio", "tabSize", "scale", "animationIterationCount", "gridRow", "gridRowStart", "gridRowEnd",
35
- "gridColumn", "gridColumnStart", "gridColumnEnd", "gridArea",
37
+ "gridColumn", "gridColumnStart", "gridColumnEnd", "gridArea", "columnCount", "columns", "orphans", "widows",
36
38
  ]);
37
39
 
38
40
  const nodes = new Map();
@@ -571,14 +573,14 @@ export class Node {
571
573
  */
572
574
  addEventListener(type, listener, options) {
573
575
  const kind = KIND_OF.get(type);
574
- if (kind === undefined) throw new TypeError("the tree has no event '" + type + "'");
576
+ if (kind === undefined && !DRAG_TYPES.has(type)) throw new TypeError("the tree has no event '" + type + "'");
575
577
  const capture = options === true || !!options?.capture;
576
578
  this.#listeners ??= new Map();
577
579
  let list = this.#listeners.get(type);
578
580
  if (!list) this.#listeners.set(type, (list = []));
579
581
  if (list.some((entry) => entry.listener === listener && entry.capture === capture)) return;
580
582
  list.push({ listener, capture, once: !!options?.once });
581
- this.#want(kind);
583
+ if (kind !== undefined) this.#want(kind);
582
584
  }
583
585
 
584
586
  removeEventListener(type, listener, options) {
@@ -588,7 +590,8 @@ export class Node {
588
590
  const index = list.findIndex((entry) => entry.listener === listener && entry.capture === capture);
589
591
  if (index < 0) return;
590
592
  list.splice(index, 1);
591
- this.#want(KIND_OF.get(type));
593
+ const kind = KIND_OF.get(type);
594
+ if (kind !== undefined) this.#want(kind);
592
595
  }
593
596
 
594
597
  /** Runs the capture or the bubble listeners of `event.type`. Used by the dispatcher. */
@@ -1235,3 +1238,273 @@ native.takeError = function () {
1235
1238
  pendingError = null;
1236
1239
  throw error;
1237
1240
  };
1241
+
1242
+ // The desktop around the window: files dragged in from other apps, notifications, the tray
1243
+ // and global shortcuts. The host serves `__ui.shell` calls after the code that made them has
1244
+ // run and answers through `__ui.shellAnswer`; desktop events arrive through `__ui.shellEvent`.
1245
+
1246
+ const shellCalls = new Map();
1247
+ let nextShellCall = 0;
1248
+
1249
+ function shellCall(op, fields) {
1250
+ const call = ++nextShellCall;
1251
+ return new Promise((resolve) => {
1252
+ shellCalls.set(call, resolve);
1253
+ native.shell(call, op, fields.join("\x1f"));
1254
+ });
1255
+ }
1256
+
1257
+ native.shellAnswer = function (call, value) {
1258
+ const resolve = shellCalls.get(call);
1259
+ if (!resolve) return;
1260
+ shellCalls.delete(call);
1261
+ resolve(value);
1262
+ };
1263
+
1264
+ /** A file dragged in from the desktop, as the web's `File`, with its `path` on disk. */
1265
+ export class DroppedFile {
1266
+ constructor(path) {
1267
+ this.path = path;
1268
+ this.name = path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
1269
+ this.type = "";
1270
+ }
1271
+ }
1272
+
1273
+ /**
1274
+ * What a file drag carries, as the web's `DataTransfer`: `types` is `["Files"]` while files
1275
+ * are over the window, and `files` lists them in `drop`, as on the web.
1276
+ */
1277
+ export class DataTransfer {
1278
+ constructor(paths) {
1279
+ this.files = paths.map((path) => new DroppedFile(path));
1280
+ this.items = this.files.map((file) => ({ kind: "file", type: "", getAsFile: () => file }));
1281
+ this.types = ["Files"];
1282
+ this.dropEffect = "copy";
1283
+ this.effectAllowed = "copy";
1284
+ }
1285
+
1286
+ getData() {
1287
+ return "";
1288
+ }
1289
+ }
1290
+
1291
+ let dragTarget = null;
1292
+
1293
+ function dragEvent(type, target, x, y, paths) {
1294
+ const event = new Event(type, target);
1295
+ event.clientX = event.x = x;
1296
+ event.clientY = event.y = y;
1297
+ event.dataTransfer = new DataTransfer(paths);
1298
+ dispatchEvent(event);
1299
+ }
1300
+
1301
+ // As the web: `dragenter` on the node now under the files, `dragleave` on the one before,
1302
+ // then `dragover` on the current one.
1303
+ function dragTo(target, x, y) {
1304
+ if (target !== dragTarget) {
1305
+ const before = dragTarget;
1306
+ dragTarget = target;
1307
+ if (target) dragEvent("dragenter", target, x, y, []);
1308
+ if (before) dragEvent("dragleave", before, x, y, []);
1309
+ }
1310
+ if (target) dragEvent("dragover", target, x, y, []);
1311
+ }
1312
+
1313
+ let trayMenu = new Map();
1314
+ let trayClick = null;
1315
+ const shortcuts = new Map();
1316
+ const shortcutIds = new Map();
1317
+ let nextShortcut = 0;
1318
+ const notifications = new Map();
1319
+
1320
+ native.shellEvent = function (kind, a, x, y, text) {
1321
+ if (kind <= 3) {
1322
+ const target = nodes.get(a) ?? rootNode;
1323
+ if (kind === 2) {
1324
+ const before = dragTarget;
1325
+ dragTarget = null;
1326
+ if (before) dragEvent("dragleave", before, x, y, []);
1327
+ } else if (kind === 3) {
1328
+ if (target !== dragTarget) dragTo(target, x, y);
1329
+ dragTarget = null;
1330
+ if (target) dragEvent("drop", target, x, y, text ? text.split("\n") : []);
1331
+ } else {
1332
+ dragTo(target, x, y);
1333
+ }
1334
+ } else if (kind === 4) {
1335
+ shortcuts.get(a)?.();
1336
+ } else if (kind === 5) {
1337
+ trayClick?.({ button: a });
1338
+ } else if (kind === 6) {
1339
+ trayMenu.get(a)?.();
1340
+ } else if (kind === 7) {
1341
+ const notification = notifications.get(a);
1342
+ if (!notification) return;
1343
+ notifications.delete(a);
1344
+ notification._fire("click");
1345
+ }
1346
+ };
1347
+
1348
+ // Notifications nobody clicked are forgotten after this many newer ones.
1349
+ const NOTIFICATIONS_KEPT = 64;
1350
+
1351
+ /**
1352
+ * A desktop notification, as the web's: `new Notification(title, { body })`, with `onclick`
1353
+ * or a `click` listener. Permission is always granted.
1354
+ */
1355
+ export class Notification {
1356
+ static permission = "granted";
1357
+
1358
+ static requestPermission(callback) {
1359
+ callback?.("granted");
1360
+ return Promise.resolve("granted");
1361
+ }
1362
+
1363
+ #listeners = new Map();
1364
+
1365
+ constructor(title, options = {}) {
1366
+ this.title = String(title);
1367
+ this.body = String(options.body ?? "");
1368
+ this.tag = String(options.tag ?? "");
1369
+ this.data = options.data ?? null;
1370
+ this.onclick = this.onshow = this.onerror = this.onclose = null;
1371
+ shellCall(0, [this.title, this.body]).then((id) => {
1372
+ if (!id) return this._fire("error");
1373
+ notifications.set(id, this);
1374
+ if (notifications.size > NOTIFICATIONS_KEPT) notifications.delete(notifications.keys().next().value);
1375
+ this._fire("show");
1376
+ });
1377
+ }
1378
+
1379
+ /** The system keeps the notification until the user dismisses it. */
1380
+ close() {}
1381
+
1382
+ addEventListener(type, listener) {
1383
+ let list = this.#listeners.get(type);
1384
+ if (!list) this.#listeners.set(type, (list = []));
1385
+ if (!list.includes(listener)) list.push(listener);
1386
+ }
1387
+
1388
+ removeEventListener(type, listener) {
1389
+ const list = this.#listeners.get(type);
1390
+ const index = list ? list.indexOf(listener) : -1;
1391
+ if (index >= 0) list.splice(index, 1);
1392
+ }
1393
+
1394
+ _fire(type) {
1395
+ const event = { type, target: this, currentTarget: this };
1396
+ const handler = this["on" + type];
1397
+ try {
1398
+ if (typeof handler === "function") handler.call(this, event);
1399
+ for (const listener of (this.#listeners.get(type) ?? []).slice()) listener.call(this, event);
1400
+ } catch (error) {
1401
+ reportError(error);
1402
+ }
1403
+ }
1404
+ }
1405
+
1406
+ globalThis.Notification ??= Notification;
1407
+
1408
+ function hex(bytes) {
1409
+ let text = "";
1410
+ for (let i = 0; i < bytes.length; i++) text += (bytes[i] < 16 ? "0" : "") + bytes[i].toString(16);
1411
+ return text;
1412
+ }
1413
+
1414
+ function packMenu(items, lines) {
1415
+ for (const item of items) {
1416
+ if (item.type === "separator") lines.push("S");
1417
+ else if (item.submenu) {
1418
+ lines.push("B" + String(item.label ?? "").replace(/\n/g, " "));
1419
+ packMenu(item.submenu, lines);
1420
+ lines.push("E");
1421
+ } else {
1422
+ const action = trayMenu.size + 1;
1423
+ trayMenu.set(action, typeof item.click === "function" ? item.click : () => {});
1424
+ const label = String(item.label ?? "").replace(/\n/g, " ");
1425
+ lines.push("A" + action + "," + (item.enabled === false ? 0 : 1) + "," + (item.checked ? 1 : 0) + "," + label);
1426
+ }
1427
+ }
1428
+ }
1429
+
1430
+ /**
1431
+ * Shows an icon in the system tray (the macOS menu bar, the Windows notification area, a
1432
+ * StatusNotifierItem on Linux). `icon` is RGBA pixels, as an `ImageData`: `{ width, height,
1433
+ * data }`; macOS draws a `template` icon from its alpha in the menu bar's colours. `menu`
1434
+ * items are `{ label, click, enabled, checked }`, `{ type: "separator" }` or `{ label,
1435
+ * submenu }`. With no menu, `onClick({ button })` runs when the icon is clicked. Calling it
1436
+ * again replaces the tray. Resolves to whether the system shows it.
1437
+ */
1438
+ export function setTray({ icon, tooltip = "", template = false, menu = [], onClick = null }) {
1439
+ if (!icon || !(icon.width > 0) || !(icon.height > 0) || icon.data?.length !== icon.width * icon.height * 4) {
1440
+ throw new TypeError("setTray needs an icon of RGBA pixels: { width, height, data }");
1441
+ }
1442
+ trayMenu = new Map();
1443
+ trayClick = typeof onClick === "function" ? onClick : null;
1444
+ const lines = [];
1445
+ packMenu(menu, lines);
1446
+ const fields = [String(tooltip), icon.width, icon.height, template ? 1 : 0, hex(icon.data), lines.join("\n")];
1447
+ return shellCall(1, fields).then((shown) => shown === 1);
1448
+ }
1449
+
1450
+ /** Takes the tray icon away. */
1451
+ export function removeTray() {
1452
+ trayMenu = new Map();
1453
+ trayClick = null;
1454
+ shellCall(2, []);
1455
+ }
1456
+
1457
+ const MODIFIERS = { shift: 1, ctrl: 2, control: 2, alt: 4, option: 4, meta: 8, cmd: 8, command: 8, super: 8, mod: 16, cmdorctrl: 16, commandorcontrol: 16 };
1458
+ const KEY_NAMES = {
1459
+ up: "ArrowUp", down: "ArrowDown", left: "ArrowLeft", right: "ArrowRight", esc: "Escape", return: "Enter",
1460
+ space: " ", plus: "Equal", "=": "Equal", "-": "Minus", ",": "Comma", ".": "Period", "/": "Slash",
1461
+ ";": "Semicolon", "'": "Quote", "[": "BracketLeft", "]": "BracketRight", "\\": "Backslash", "`": "Backquote",
1462
+ };
1463
+
1464
+ // "Mod+Shift+K" as the UI Events `code` of the key and the modifier bits; `Mod` (also
1465
+ // `CmdOrCtrl`) is Command on macOS and Control elsewhere.
1466
+ function parseShortcut(accelerator) {
1467
+ const parts = String(accelerator).split("+").map((part) => part.trim()).filter(Boolean);
1468
+ let bits = 0;
1469
+ let code = "";
1470
+ for (const part of parts) {
1471
+ const modifier = MODIFIERS[part.toLowerCase()];
1472
+ if (modifier !== undefined) {
1473
+ bits |= modifier;
1474
+ continue;
1475
+ }
1476
+ const named = KEY_NAMES[part.toLowerCase()] ?? part;
1477
+ if (named === " ") code = "Space";
1478
+ else if (/^[a-z]$/i.test(named)) code = "Key" + named.toUpperCase();
1479
+ else if (/^[0-9]$/.test(named)) code = "Digit" + named;
1480
+ else code = named[0].toUpperCase() + named.slice(1);
1481
+ }
1482
+ if (!code) throw new TypeError("'" + accelerator + "' names no key");
1483
+ return { code, bits };
1484
+ }
1485
+
1486
+ /**
1487
+ * Runs `callback` when the keys of `accelerator` are pressed, whichever app has focus:
1488
+ * `"Mod+Shift+K"`, where `Mod` is Command on macOS and Control elsewhere, and the key is a
1489
+ * letter, a digit, a UI Events `code` (`"F5"`, `"ArrowUp"`, `"Slash"`) or a name such as
1490
+ * `Space` or `Esc`. Registering it again replaces the callback. Resolves to whether the
1491
+ * system took it: another app may hold it, and Wayland has no global shortcuts.
1492
+ */
1493
+ export function registerShortcut(accelerator, callback) {
1494
+ const { code, bits } = parseShortcut(accelerator);
1495
+ const key = code + "+" + bits;
1496
+ let id = shortcutIds.get(key);
1497
+ if (id === undefined) shortcutIds.set(key, (id = ++nextShortcut));
1498
+ shortcuts.set(id, callback);
1499
+ return shellCall(3, [id, code, bits]).then((held) => held === 1);
1500
+ }
1501
+
1502
+ /** Stops the shortcut of `accelerator`. */
1503
+ export function unregisterShortcut(accelerator) {
1504
+ const { code, bits } = parseShortcut(accelerator);
1505
+ const id = shortcutIds.get(code + "+" + bits);
1506
+ if (id === undefined) return;
1507
+ shortcutIds.delete(code + "+" + bits);
1508
+ shortcuts.delete(id);
1509
+ shellCall(4, [id]);
1510
+ }