react-x11 2.15.3 → 2.16.0

package/src/statusnotifier.js

@@ -37,14 +37,55 @@
 //
 // The protocol carries far less about a click than AppKit does. There is no
 // click count, no modifier state, and no item rectangle — `Activate(x, y)`
-// gives the pointer position and nothing else. Those fields are reported as
+// gives a position and nothing else. Those fields are reported as
 // `0`/`false` rather than guessed at, and `docs/desktop.md` says so, because a
 // tray menu that only opens on shift-click is an app built on a field this
 // rung cannot fill. The menu is the portable interaction; `onClick` is the
 // one that degrades.
+//
+// ## The position has no unit
+//
+// The spec says "screen coordinates" and stops, which on a scaled display is
+// two different numbers — and the hosts split between them:
+//
+//   - **X root coordinates, device pixels.** Plasma since 5.27, on purpose:
+//     its xembed-sni-proxy synthesises X clicks from them. GNOME's
+//     AppIndicator extension passes its stage coordinates through, which are
+//     device pixels on X11 and in Wayland's physical layout, the default up
+//     to GNOME 49.
+//   - **The host's own logical pixels.** xfce4-panel, Budgie and LXQt pass
+//     their toolkit's root position through, and Cinnamon sends the icon's
+//     corner over its UI scale. GNOME's stage is in logical pixels from 50,
+//     and before it on Fedora and Debian 13, which switch the layout on
+//     downstream. So did Plasma before 5.27.
+//   - **Not a screen position.** MATE sends the item's corner in its applet's
+//     own window, and snixembed's `Activate` is always `(0, 0)`.
+//
+// Dividing by the scale is right for the first group and halves every click
+// in the second; passing the numbers through is the opposite. So a click is
+// read both ways and the screen picks (`clickReadings`, `clickPoint`):
+//
+//   1. **A reading no monitor holds is not one.** A tray is on the screen,
+//      and a device-pixel host's item at the right or the bottom of it —
+//      where panels put the tray — is off the screen when read as logical
+//      pixels. The common device-pixel click costs nothing more.
+//   2. **Then the pointer.** A host that sends a position sends the
+//      pointer's or its icon's, so one `QueryPointer` names the reading the
+//      click was at.
+//   3. **Otherwise the numbers as sent.** The pointer is somewhere else
+//      because the click was a key, or the connection is XWayland's, which
+//      is told nothing of a pointer over a Wayland panel. As sent is what the
+//      second group needs, and the first group's usual trays were settled at
+//      step 1.
+//
+// What that leaves wrong is a device-pixel host under XWayland whose tray
+// still lands on a monitor read as logical pixels: in the top-left quarter
+// of the screen, or on a desk where it falls on another monitor.
 
 import { loadTransport, sessionBus } from './bus.js';
 import { DbusMenuExport } from './dbusmenuexport.js';
+import { scaleOf } from './scale.js';
+import { screensSnapshot } from './screens.js';
 
 export const WATCHER_NAME = 'org.kde.StatusNotifierWatcher';
 export const WATCHER_PATH = '/StatusNotifierWatcher';
@@ -91,6 +132,43 @@ export function toPixmapArray(image) {
   return [[width, height, out]];
 }
 
+/**
+ * How far from the pointer a click's point may be and still be the click, in
+ * logical pixels. A host that sends the pointer is within a pixel or two of
+ * it, and Cinnamon, which sends its icon's corner, within the icon. A point
+ * further off is taken as sent — which for Cinnamon, a logical-pixel host,
+ * is right anyway.
+ */
+const CLICK_REACH = 64;
+
+/**
+ * A host's `(x, y)` read both ways — as X root coordinates, and as the host's
+ * own logical pixels — keeping the readings some monitor holds. Each is the
+ * point on the screen it names, in device pixels, and what it means in
+ * logical ones. See "The position has no unit" in the header.
+ *
+ * `screens` are device-pixel rects, as `screensSnapshot(app).screens` holds
+ * them; with none known both readings stand, and with neither on a monitor
+ * the host sent something that is not a position.
+ */
+function clickReadings(x, y, scale, screens = []) {
+  const readings = [
+    { device: { x, y }, logical: { x: x / scale, y: y / scale } },
+    { device: { x: x * scale, y: y * scale }, logical: { x, y } },
+  ];
+  if (!screens.length) return readings;
+  // Edges count: a host that sends an icon's far corner can land on one.
+  return readings.filter(({ device: p }) =>
+    screens.some(
+      (m) =>
+        p.x >= m.x &&
+        p.y >= m.y &&
+        p.x <= m.x + m.width &&
+        p.y <= m.y + m.height,
+    ),
+  );
+}
+
 /** `visible: false` is `Passive`, which is how the spec spells "hidden". */
 function statusOf(options) {
   if (options?.visible === false) return 'Passive';
@@ -129,8 +207,13 @@ function iconOf(icon, decode) {
  * in quick succession cannot put two registrations in flight.
  */
 export class StatusNotifierItem {
-  constructor({ getOptions, appId, decodeIcon, onError, slot } = {}) {
+  constructor({ getOptions, app, appId, decodeIcon, onError, slot } = {}) {
     this.getOptions = getOptions ?? (() => null);
+    // The display the tray is on — not for the protocol, which is D-Bus
+    // only, but for a click's position: its scale, its monitors and its
+    // pointer are what put the host's numbers into logical pixels. Null is
+    // no display to ask, and a click's numbers are then passed as sent.
+    this.app = app ?? null;
     this.appId = appId ?? 'react-x11';
     this.decodeIcon = decodeIcon ?? (() => null);
     this.onError = onError ?? (() => {});
@@ -453,27 +536,91 @@ export class StatusNotifierItem {
     if (this.menu) this.menu.update(next.menu ?? []);
   }
 
+  // ------------------------------------------------------------------ click
+
+  /**
+   * A click's `(x, y)` in logical screen pixels — the unit a `<popup>`'s
+   * `x`/`y` and `anchor={{ rect }}` take. Read both ways and settled by the
+   * monitors, then the pointer, then as sent: the header has why.
+   */
+  async clickPoint(x, y) {
+    const scale = scaleOf(this.app);
+    if (scale === 1) return { x, y };
+    const readings = clickReadings(
+      x,
+      y,
+      scale,
+      screensSnapshot(this.app).screens,
+    );
+    if (readings.length === 1) return readings[0].logical;
+    const pointer = readings.length ? await this.queryPointer() : null;
+    if (!pointer) return { x, y };
+    let near = null;
+    let nearest = CLICK_REACH * scale;
+    for (const reading of readings) {
+      const d = Math.hypot(
+        reading.device.x - pointer.x,
+        reading.device.y - pointer.y,
+      );
+      if (d <= nearest) {
+        near = reading;
+        nearest = d;
+      }
+    }
+    return near?.logical ?? { x, y };
+  }
+
+  /**
+   * Where the pointer is on the X screen, in device pixels, or null where
+   * nothing can say: a backend with no X server behind it, a failed request,
+   * a pointer on another screen.
+   */
+  queryPointer() {
+    const X = this.app?.X;
+    const root = X?.display?.screen?.[0]?.root;
+    if (typeof X?.QueryPointer !== 'function' || root == null) {
+      return Promise.resolve(null);
+    }
+    return new Promise((resolve) => {
+      try {
+        X.QueryPointer(root, (err, reply) =>
+          resolve(
+            err || !reply?.sameScreen
+              ? null
+              : { x: reply.rootX, y: reply.rootY },
+          ),
+        );
+      } catch {
+        resolve(null);
+      }
+    });
+  }
+
   // --------------------------------------------------------------- protocol
 
   defineItem(dbus) {
     const opts = () => this.options;
     const icon = () => iconOf(opts().icon, this.decodeIcon);
-    const click = (button) => (args) => {
-      // No click count, no modifiers, no item rect: the protocol has none of
-      // them. Reported as zero rather than invented — see the header.
-      opts().onClick?.({
-        button,
-        x: args?.x ?? 0,
-        y: args?.y ?? 0,
-        width: 0,
-        height: 0,
-        clickCount: 1,
-        shift: false,
-        control: false,
-        option: false,
-        command: false,
+    // No click count, no modifiers, no item rect: the protocol has none of
+    // them. Reported as zero rather than invented — see the header. The
+    // position it does have is put into logical pixels first, and the call is
+    // answered once the app has had the click, so a throw in `onClick` still
+    // reaches the host as the error it was.
+    const click = (button) => (args) =>
+      this.clickPoint(args?.x ?? 0, args?.y ?? 0).then(({ x, y }) => {
+        opts().onClick?.({
+          button,
+          x,
+          y,
+          width: 0,
+          height: 0,
+          clickCount: 1,
+          shift: false,
+          control: false,
+          option: false,
+          command: false,
+        });
       });
-    };
 
     return dbus.defineInterface({
       name: ITEM_IFACE,

package/src/styles.js

@@ -247,6 +247,12 @@ const PAINT_PROPS = new Set([
   'outlineWidth',
   'outlineColor',
   'outlineOffset',
+  // How opaque the node is **with everything in it**: the subtree is drawn
+  // once and composited at this alpha (`NodePaint._paintGroup`), so a card, its
+  // border, its icon and its text fade as one — the thing a colour's own
+  // alpha cannot do for more than one flat fill (#587). A number from 0 to 1,
+  // which transitions and loops like any other.
+  'opacity',
 ]);
 
 // Text style props. All affect measurement except color.
@@ -275,8 +281,105 @@ export const TEXT_LAYOUT_PROPS = new Set([
   // fits on a line, so it is a measurement input like the rest of this set.
   'textOverflow',
   'maxLines',
+  // CSS's letter-spacing, in px: added after every character, the last on a
+  // line included, which is how both text engines add it (#588)
+  'letterSpacing',
+  // Figures and the rest of the OpenType features. `fontVariantNumeric` is
+  // CSS's keywords for the numeric ones — `tabular-nums` for a readout that
+  // holds its width while it changes — and `fontFeatureSettings` names any
+  // feature by tag, winning over the keyword where the two meet, as in CSS
+  'fontVariantNumeric',
+  'fontFeatureSettings',
 ]);
 
+/**
+ * `fontVariantNumeric` keywords → the OpenType feature each one turns on, and
+ * the group it belongs to. CSS allows several keywords at once but one from
+ * each group, since the two in a group contradict each other: `'tabular-nums
+ * slashed-zero'` is a value, `'lining-nums oldstyle-nums'` is not.
+ */
+const NUMERIC_VARIANTS = {
+  'lining-nums': ['lnum', 'figures'],
+  'oldstyle-nums': ['onum', 'figures'],
+  'proportional-nums': ['pnum', 'spacing'],
+  'tabular-nums': ['tnum', 'spacing'],
+  'diagonal-fractions': ['frac', 'fractions'],
+  'stacked-fractions': ['afrc', 'fractions'],
+  ordinal: ['ordn', 'ordinal'],
+  'slashed-zero': ['zero', 'slashed-zero'],
+};
+
+/** The feature tags a `fontVariantNumeric` value turns on, or null when the
+ *  value is not one CSS would accept. `'normal'` turns none on. */
+function numericVariantTags(value) {
+  if (typeof value !== 'string') return null;
+  const words = value.trim().split(/\s+/);
+  if (words.length === 1 && words[0] === 'normal') return [];
+  const tags = [];
+  const groups = new Set();
+  for (const word of words) {
+    const [tag, group] = NUMERIC_VARIANTS[word] ?? [];
+    if (!tag || groups.has(group)) return null;
+    groups.add(group);
+    tags.push(tag);
+  }
+  return tags;
+}
+
+/** An OpenType feature tag: four printable ASCII characters. */
+const FEATURE_TAG = /^[\x20-\x7e]{4}$/;
+
+/** Whether `value` is a `fontFeatureSettings`: an array of tags to turn on,
+ *  or an object of tag → on or off, or the number of the alternate a feature
+ *  picks. */
+function isFeatureSettings(value) {
+  if (Array.isArray(value)) {
+    return value.every(
+      (tag) => typeof tag === 'string' && FEATURE_TAG.test(tag),
+    );
+  }
+  if (!value || typeof value !== 'object') return false;
+  return Object.entries(value).every(
+    ([tag, v]) =>
+      FEATURE_TAG.test(tag) &&
+      (typeof v === 'boolean' || (Number.isInteger(v) && v >= 0)),
+  );
+}
+
+// the resolved `features` for one (variant, settings) pair, kept so that the
+// same pair is the same object every time: a cascade compares two resolved
+// styles with `!==` (`resolvedTextDelta`), and a fresh object per node would
+// read as a change and re-measure text that did not move
+const resolvedFeatures = new Map();
+
+/**
+ * What the text engines are handed: every feature the two properties set, as
+ * tag → value (1 on, 0 off, or the alternate), `fontFeatureSettings` over
+ * the keywords. `undefined` when neither says anything, which is nearly
+ * every node.
+ */
+export function featuresOf(variantNumeric, featureSettings) {
+  if (variantNumeric === undefined && featureSettings === undefined) {
+    return undefined;
+  }
+  const key = `${variantNumeric ?? ''}\u0000${JSON.stringify(featureSettings ?? null)}`;
+  if (resolvedFeatures.has(key)) return resolvedFeatures.get(key);
+  const features = {};
+  for (const tag of numericVariantTags(variantNumeric) ?? []) features[tag] = 1;
+  if (Array.isArray(featureSettings)) {
+    for (const tag of featureSettings) features[tag] = 1;
+  } else if (featureSettings) {
+    for (const [tag, value] of Object.entries(featureSettings)) {
+      features[tag] = value === true ? 1 : value === false ? 0 : value;
+    }
+  }
+  const out =
+    Object.keys(features).length > 0 ? Object.freeze(features) : undefined;
+  if (resolvedFeatures.size > 256) resolvedFeatures.clear();
+  resolvedFeatures.set(key, out);
+  return out;
+}
+
 /**
  * Text style props that change how the text is **drawn** and provably not
  * where any of it lands. They still invalidate the cached layout — the value
@@ -298,7 +401,8 @@ export const TEXT_PAINT_PROPS = new Set(['textRendering']);
  * dims the labels under it the way it would in CSS.
  *
  * This is CSS's inherited set narrowed to what a *descendant* can act on: the
- * face, the size, the ink and the glyph rounding. `textAlign`, `lineHeight`,
+ * face, the size, the ink, the glyph rounding, the spacing between letters
+ * and the OpenType features. `textAlign`, `lineHeight`,
  * `textWrap`, `textOverflow`, `maxLines` and `textBoxTrim` stay out even
  * though CSS inherits the first two — here they are read by the node that
  * owns the **box** the text flows in, and a box is not something a descendant
@@ -313,6 +417,9 @@ export const INHERITED_TEXT_PROPS = new Set([
   'fontVariationSettings',
   'textRendering',
   'color',
+  'letterSpacing',
+  'fontVariantNumeric',
+  'fontFeatureSettings',
 ]);
 
 /**
@@ -340,7 +447,7 @@ export function localTextStyleChanged(style, before) {
 export function inheritedTextChanged(style, before) {
   if (style === before) return false;
   for (const key of INHERITED_TEXT_PROPS) {
-    if (key === 'fontVariationSettings') {
+    if (key === 'fontVariationSettings' || key === 'fontFeatureSettings') {
       if (!axesEqual(style[key], before[key])) return true;
     } else if (style[key] !== before[key]) return true;
   }
@@ -370,7 +477,9 @@ export function resolvedTextDelta(a, b) {
     a.size !== b.size ||
     a.weight !== b.weight ||
     a.style !== b.style ||
-    !axesEqual(a.variations, b.variations)
+    !axesEqual(a.variations, b.variations) ||
+    a.letterSpacing !== b.letterSpacing ||
+    a.features !== b.features
   ) {
     return TEXT_REMEASURE;
   }
@@ -746,6 +855,64 @@ const GRID_VALUES = new Set([...GRID_CONTAINER_PROPS, ...GRID_ITEM_PROPS]);
  * grammar is concerned), so this checks the shape and never the colours.
  */
 function validateValue(key, value, where) {
+  if (key === 'letterSpacing') {
+    if (
+      value != null &&
+      !(typeof value === 'number' && Number.isFinite(value)) &&
+      !isToken(value)
+    ) {
+      throw new Error(
+        `react-x11: invalid letterSpacing ${JSON.stringify(value)} in ${where} ` +
+          '(expected a number of pixels, like letterSpacing: 1.5, or a $token)',
+      );
+    }
+    return;
+  }
+  if (key === 'fontVariantNumeric') {
+    if (
+      value != null &&
+      numericVariantTags(value) === null &&
+      !isToken(value)
+    ) {
+      throw new Error(
+        `react-x11: invalid fontVariantNumeric ${JSON.stringify(value)} in ` +
+          `${where} (expected 'normal', or keywords from ` +
+          `${Object.keys(NUMERIC_VARIANTS).join(', ')} with at most one of ` +
+          'lining/oldstyle, proportional/tabular and diagonal/stacked, like ' +
+          "'tabular-nums' or 'tabular-nums slashed-zero')",
+      );
+    }
+    return;
+  }
+  if (key === 'fontFeatureSettings') {
+    if (value != null && !isFeatureSettings(value) && !isToken(value)) {
+      throw new Error(
+        `react-x11: invalid fontFeatureSettings ${JSON.stringify(value)} in ` +
+          `${where} (expected four-letter OpenType tags — an array of tags to ` +
+          "turn on, ['tnum'], or an object of tag to on/off or an alternate, " +
+          '{ tnum: true, liga: false, salt: 2 })',
+      );
+    }
+    return;
+  }
+  if (key === 'opacity') {
+    // unset, the way a conditional writes it: `opacity: dim ? 0.5 : undefined`
+    if (value == null) return;
+    // A string that is not a token is the one mistake worth stopping for:
+    // `'50%'` or `'0.5'` would otherwise compare as not-below-1 and paint
+    // the node fully opaque, silently. A number outside 0..1 is clamped
+    // where it is painted, as CSS clamps it.
+    if (
+      !(typeof value === 'number' && !Number.isNaN(value)) &&
+      !isToken(value)
+    ) {
+      throw new Error(
+        `react-x11: invalid opacity ${JSON.stringify(value)} in ${where} ` +
+          '(expected a number from 0 to 1 — opacity: 0.5 is half — or a $token)',
+      );
+    }
+    return;
+  }
   const grid = GRID_VALUES.has(key);
   if (!grid && key !== 'backgroundImage' && key !== 'boxShadow') return;
   try {
@@ -962,6 +1129,9 @@ const NOT_ANIMATABLE = new Set([
   'fontFamily',
   'fontWeight',
   'fontStyle',
+  // a keyword and a bag of tags: there is no halfway figure
+  'fontVariantNumeric',
+  'fontFeatureSettings',
   'textAlign',
   // nothing is drawn from it, so there is no frame in which a halfway value
   // would be visible — and it may be an object, which does not lerp
@@ -1056,6 +1226,9 @@ const parsedAnimations = new WeakMap();
  * a thing that does not move: a loop nobody wrote a stop for is exactly the
  * feature where silence is unreadable.
  */
+/** What one property's loop may say. */
+const LOOP_OPTIONS = ['from', 'to', 'duration', 'easing', 'alternate', 'delay'];
+
 function parseAnimation(spec, where) {
   if (typeof spec !== 'object' || spec === null || Array.isArray(spec)) {
     throw new Error(
@@ -1077,15 +1250,15 @@ function parseAnimation(spec, where) {
     if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
       throw new Error(
         `react-x11: invalid animation for ${at} — expected ` +
-          '{ from?, to, duration, easing?, alternate? }, got ' +
+          '{ from?, to, duration, easing?, alternate?, delay? }, got ' +
           JSON.stringify(entry),
       );
     }
     for (const key of Object.keys(entry)) {
-      if (!['from', 'to', 'duration', 'easing', 'alternate'].includes(key)) {
+      if (!LOOP_OPTIONS.includes(key)) {
         throw new Error(
           `react-x11: unknown animation option "${key}" for ${at} ` +
-            '(expected from, to, duration, easing, alternate)',
+            `(expected ${LOOP_OPTIONS.join(', ')})`,
         );
       }
     }
@@ -1109,6 +1282,14 @@ function parseAnimation(spec, where) {
           `${at} (expected one of ${EASING_NAMES.join(', ')})`,
       );
     }
+    const delay = entry.delay ?? 0;
+    if (typeof delay !== 'number' || !Number.isFinite(delay)) {
+      throw new Error(
+        `react-x11: animation for ${at} needs "delay" in ms — before the ` +
+          'loop starts, or negative to start it that far in — got ' +
+          JSON.stringify(entry.delay),
+      );
+    }
     entries.push({
       prop,
       from: entry.from,
@@ -1117,6 +1298,7 @@ function parseAnimation(spec, where) {
       easing,
       ease: EASINGS[easing],
       alternate: Boolean(entry.alternate),
+      delay,
     });
   }
   return entries;
@@ -1184,7 +1366,8 @@ export function sameAnimation(a, b) {
     a.to === b.to &&
     a.duration === b.duration &&
     a.easing === b.easing &&
-    a.alternate === b.alternate
+    a.alternate === b.alternate &&
+    a.delay === b.delay
   );
 }
 
@@ -1193,9 +1376,14 @@ export function sameAnimation(a, b) {
  * the looping: the phase comes from a modulo of the elapsed time rather than
  * from a per-cycle restart, so a bar that has been spinning for an hour is
  * exactly where the clock says and no rounding has accumulated.
+ *
+ * The delay is where the loop's own time starts: `from` until a positive one
+ * has passed, and already that far in for a negative one — CSS's
+ * `animation-delay` with `animation-fill-mode: backwards`, which is also
+ * what Core Animation shows for the same declaration.
  */
 export function animationValueAt(spec, elapsed) {
-  const cycles = Math.max(0, elapsed) / spec.duration;
+  const cycles = Math.max(0, elapsed - spec.delay) / spec.duration;
   let t = cycles % 1;
   if (spec.alternate && Math.floor(cycles) % 2 === 1) t = 1 - t;
   return interpolate(spec.from, spec.to, spec.ease(t)) ?? spec.from;
@@ -1670,6 +1858,7 @@ export const SCALED_LENGTH_PROPS = [
   'outlineWidth',
   'outlineOffset',
   'fontSize',
+  'letterSpacing',
 ];
 
 const SCALED_LENGTHS = new Set(SCALED_LENGTH_PROPS);
@@ -1834,6 +2023,9 @@ export function paintPropsChanged(props, oldProps = {}) {
 
 /** Resolved text style (TextLayout base style) from props + inherited. */
 export function textStyleFrom(props, inherited) {
+  const variantNumeric = props.fontVariantNumeric ?? inherited.variantNumeric;
+  const featureSettings =
+    props.fontFeatureSettings ?? inherited.featureSettings;
   return {
     family: props.fontFamily ?? inherited.family,
     size: props.fontSize ?? inherited.size,
@@ -1844,6 +2036,14 @@ export function textStyleFrom(props, inherited) {
     variations: props.fontVariationSettings ?? inherited.variations,
     textRendering: props.textRendering ?? inherited.textRendering,
     color: props.color ?? inherited.color,
+    letterSpacing: props.letterSpacing ?? inherited.letterSpacing,
+    // Inherited apart, as CSS inherits the two properties apart — a child's
+    // `fontVariantNumeric` replaces the keyword above it and leaves an
+    // inherited `fontFeatureSettings` alone — and resolved together into what
+    // the engines read.
+    variantNumeric,
+    featureSettings,
+    features: featuresOf(variantNumeric, featureSettings),
   };
 }
 
@@ -1865,6 +2065,10 @@ export const DEFAULT_TEXT_STYLE = {
   variations: undefined,
   textRendering: undefined,
   color: 'black',
+  letterSpacing: undefined,
+  variantNumeric: undefined,
+  featureSettings: undefined,
+  features: undefined,
 };
 
 /**