@silkui/core 0.1.5 → 0.1.8

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
@@ -157,6 +157,38 @@ registerShortcut("Mod+Shift+B", build); // Mod is Command on macOS, Control else
157
157
  whichever app has focus; another app may hold it, and Wayland has none. `removeTray()` and
158
158
  `unregisterShortcut(accelerator)` undo them.
159
159
 
160
+ `memoryUsage()` is the app's memory as the system shows it to users, to put next to an
161
+ Electron app's in Activity Monitor or Task Manager. It is synchronous and allocates almost
162
+ nothing, so it can run every second.
163
+
164
+ ```ts
165
+ import { memoryUsage } from "@silkui/core";
166
+
167
+ const { footprint, processes } = memoryUsage(); // bytes, and how many processes they cover
168
+ ```
169
+
170
+ `footprint` is `phys_footprint` on macOS (Activity Monitor's "Memory", `/usr/bin/footprint`),
171
+ `Pss` from `/proc/self/smaps_rollup` on Linux and `PrivateUsage` on Windows. `processes` is 1:
172
+ the host runs the app, its tree and its JavaScript in one process. In a web-canvas build it
173
+ is the wasm tree's memory only, without the page's JavaScript heap. It is `null` when the
174
+ host cannot say.
175
+
176
+ `frameStats()` says what reached the screen since its last call: frames presented, presents
177
+ per second, painted frames the GPU never drew, and the milliseconds between presents. Count
178
+ frames with it rather than with `requestAnimationFrame`, which runs once per frame the app
179
+ paints, not per frame the display shows.
180
+
181
+ ```ts
182
+ import { frameStats } from "@silkui/core";
183
+
184
+ setInterval(() => {
185
+ const { fps, dropped, p95 } = frameStats();
186
+ }, 1000);
187
+ ```
188
+
189
+ Intervals are taken where the render thread presents, and a gap over a second (an idle
190
+ window) is left out of the percentiles. It is `null` in a browser build.
191
+
160
192
  ### Attributes and accessibility
161
193
 
162
194
  `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.5",
3
+ "version": "0.1.8",
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
@@ -105,8 +105,14 @@ export class Node {
105
105
  set disabled(value: boolean);
106
106
  focus(): void;
107
107
  scrollTo(x: number, y: number): void;
108
+ scroll(x: number, y: number): void;
108
109
  addEventListener<K extends keyof EventMap>(type: K, listener: Listener<EventMap[K]>, options?: ListenerOptions): void;
110
+ /** The app's own event types, sent with `dispatchEvent`. */
111
+ addEventListener(type: string, listener: (event: globalThis.Event) => void, options?: ListenerOptions): void;
109
112
  removeEventListener<K extends keyof EventMap>(type: K, listener: Listener<EventMap[K]>, options?: ListenerOptions): void;
113
+ removeEventListener(type: string, listener: (event: globalThis.Event) => void, options?: ListenerOptions): void;
114
+ /** Sends `event` through the tree from this node, as on the web. False when a listener prevented the default. */
115
+ dispatchEvent(event: globalThis.Event): boolean;
110
116
  }
111
117
 
112
118
  /** A text leaf. It takes its look from its parent. */
@@ -488,3 +494,38 @@ export function removeTray(): void;
488
494
  */
489
495
  export function registerShortcut(accelerator: string, callback: () => void): Promise<boolean>;
490
496
  export function unregisterShortcut(accelerator: string): void;
497
+
498
+ /** The app's memory: `footprint` in bytes over `processes` processes. */
499
+ export interface MemoryUsage {
500
+ footprint: number;
501
+ processes: number;
502
+ }
503
+
504
+ /**
505
+ * The app's memory as the system shows it to users (macOS `phys_footprint`, Linux `Pss`,
506
+ * Windows `PrivateUsage`). In the browser, the wasm tree's linear memory only. Cheap enough
507
+ * to call every second; `null` when the host cannot say.
508
+ */
509
+ export function memoryUsage(): MemoryUsage | null;
510
+
511
+ /** What the window put on screen over a stretch of time; see `frameStats`. */
512
+ export interface FrameStats {
513
+ /** Frames presented. */
514
+ frames: number;
515
+ /** `frames` per second over the stretch. */
516
+ fps: number;
517
+ /** Painted frames a newer frame replaced before the GPU drew them. */
518
+ dropped: number;
519
+ /** Milliseconds between presents: median, 95th and 99th percentile, longest. */
520
+ p50: number;
521
+ p95: number;
522
+ p99: number;
523
+ max: number;
524
+ }
525
+
526
+ /**
527
+ * The frames the window presented since the last call (since the app started, the first
528
+ * time), which `requestAnimationFrame` cannot count. Cheap enough to call every second;
529
+ * `null` in a browser build.
530
+ */
531
+ export function frameStats(): FrameStats | null;
package/src/index.js CHANGED
@@ -573,13 +573,18 @@ export class Node {
573
573
  native.scrollTo(this.nodeId, x, y);
574
574
  }
575
575
 
576
+ scroll(x, y) {
577
+ native.scrollTo(this.nodeId, x, y);
578
+ }
579
+
576
580
  /**
577
581
  * As on the web. `options` is `true` or `{ capture: true }` for the capture phase, and
578
- * `{ once: true }` for a listener that runs once.
582
+ * `{ once: true }` for a listener that runs once. A type the tree has no event for is the
583
+ * app's own, sent with `dispatchEvent`.
579
584
  */
580
585
  addEventListener(type, listener, options) {
586
+ if (listener == null) return;
581
587
  const kind = KIND_OF.get(type);
582
- if (kind === undefined && !DRAG_TYPES.has(type)) throw new TypeError("the tree has no event '" + type + "'");
583
588
  const capture = options === true || !!options?.capture;
584
589
  this.#listeners ??= new Map();
585
590
  let list = this.#listeners.get(type);
@@ -600,6 +605,12 @@ export class Node {
600
605
  if (kind !== undefined) this.#want(kind);
601
606
  }
602
607
 
608
+ /** Sends `event` (an `Event` or `CustomEvent`) through the tree from this node, as on the web. */
609
+ dispatchEvent(event) {
610
+ if (typeof event?.type !== "string") throw new TypeError("dispatchEvent takes an Event");
611
+ return dispatchEvent(adopt(event, this));
612
+ }
613
+
603
614
  /** Runs the capture or the bubble listeners of `event.type`. Used by the dispatcher. */
604
615
  _run(event, capture) {
605
616
  const list = this.#listeners?.get(event.type);
@@ -1563,7 +1574,8 @@ function fill(event, kind, a, b, modifiers, d, e, first, second, third, fourth)
1563
1574
  * listener prevented the default.
1564
1575
  */
1565
1576
  export function dispatchEvent(event) {
1566
- const path = event.composedPath();
1577
+ const path = [];
1578
+ for (let node = event.target; node; node = node.parentNode) path.push(node);
1567
1579
  for (let i = path.length - 1; i > 0 && !event._stopped; i--) {
1568
1580
  event.eventPhase = 1;
1569
1581
  event.currentTarget = path[i];
@@ -1587,6 +1599,28 @@ export function dispatchEvent(event) {
1587
1599
  return !event.defaultPrevented;
1588
1600
  }
1589
1601
 
1602
+ // An event the app made, from the runtime's `Event` class: its target and phase become
1603
+ // fields the dispatcher sets, and its stop methods record what the dispatcher reads.
1604
+ function adopt(event, target) {
1605
+ if (!("_stopped" in event)) {
1606
+ let stopped = false;
1607
+ let immediate = false;
1608
+ const stop = event.stopPropagation;
1609
+ const stopNow = event.stopImmediatePropagation;
1610
+ Object.defineProperties(event, {
1611
+ _stopped: { get: () => stopped || event.cancelBubble === true, configurable: true },
1612
+ _immediate: { get: () => immediate, configurable: true },
1613
+ stopPropagation: { value() { stopped = true; stop?.call(event); }, configurable: true },
1614
+ stopImmediatePropagation: { value() { stopped = immediate = true; stopNow?.call(event); }, configurable: true },
1615
+ });
1616
+ }
1617
+ for (const [name, value] of [["target", target], ["currentTarget", null], ["eventPhase", 0]]) {
1618
+ if (Object.getOwnPropertyDescriptor(event, name)?.writable) event[name] = value;
1619
+ else Object.defineProperty(event, name, { value, writable: true, configurable: true });
1620
+ }
1621
+ return event;
1622
+ }
1623
+
1590
1624
  // The host calls this for every event record, before the tree runs the default action.
1591
1625
  native.dispatch = function (kind, id, a, b, modifiers, d, e, first, second, third, fourth) {
1592
1626
  const target = nodes.get(id);
@@ -1897,3 +1931,40 @@ export function unregisterShortcut(accelerator) {
1897
1931
  shortcuts.delete(id);
1898
1932
  shellCall(4, [id]);
1899
1933
  }
1934
+
1935
+ /**
1936
+ * The app's memory in bytes, as the system shows it to users: `phys_footprint` on macOS
1937
+ * (Activity Monitor's "Memory"), `Pss` on Linux and `PrivateUsage` on Windows. `processes` is
1938
+ * how many processes `footprint` counts: the host is one. In the browser it is the wasm
1939
+ * tree's linear memory, without the page's JavaScript heap. `null` when there is no answer.
1940
+ */
1941
+ export function memoryUsage() {
1942
+ const footprint = native.memoryUsage?.() ?? 0;
1943
+ return footprint > 0 ? { footprint, processes: 1 } : null;
1944
+ }
1945
+
1946
+ let frameStatsSince = 0;
1947
+
1948
+ /**
1949
+ * The frames the window put on screen since the last call (since the app started, the first
1950
+ * time). `frames` counts presents, which `requestAnimationFrame` cannot: a callback can run
1951
+ * for a frame the GPU never drew. `dropped` counts painted frames a newer one replaced before
1952
+ * the GPU took them; `p50` to `max` are milliseconds between presents. `null` where the host
1953
+ * has no window of its own (a browser build).
1954
+ */
1955
+ export function frameStats() {
1956
+ if (!native.frameStats) return null;
1957
+ const now = performance.now();
1958
+ const seconds = (now - frameStatsSince) / 1000;
1959
+ frameStatsSince = now;
1960
+ const frames = native.frameStats(0);
1961
+ return {
1962
+ frames,
1963
+ fps: seconds > 0 ? frames / seconds : 0,
1964
+ dropped: native.frameStats(1),
1965
+ p50: native.frameStats(2),
1966
+ p95: native.frameStats(3),
1967
+ p99: native.frameStats(4),
1968
+ max: native.frameStats(5),
1969
+ };
1970
+ }