@silkui/core 0.1.6 → 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
@@ -173,6 +173,22 @@ the host runs the app, its tree and its JavaScript in one process. In a web-canv
173
173
  is the wasm tree's memory only, without the page's JavaScript heap. It is `null` when the
174
174
  host cannot say.
175
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
+
176
192
  ### Attributes and accessibility
177
193
 
178
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.6",
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. */
@@ -501,3 +507,25 @@ export interface MemoryUsage {
501
507
  * to call every second; `null` when the host cannot say.
502
508
  */
503
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);
@@ -1908,3 +1942,29 @@ export function memoryUsage() {
1908
1942
  const footprint = native.memoryUsage?.() ?? 0;
1909
1943
  return footprint > 0 ? { footprint, processes: 1 } : null;
1910
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
+ }