react-x11 2.6.1 → 2.8.0

package/src/styles.js

@@ -449,6 +449,12 @@ const STYLE_PROPS = new Set([
   // layout nor paint — the one thing it must never do is grow the visuals,
   // since the whole point is a 24px target under a 16px control.
   'hitSlop',
+  // Declares this node a container that the `'@container …'` blocks below
+  // it ask about — CSS's `container-type` and `container-name` in one
+  // property: `true` answers the unnamed queries, a name answers those and
+  // the ones that say it. Neither layout nor paint: it changes nothing about
+  // this node, only what the blocks under it resolve against.
+  'container',
 ]);
 
 export const isStyleProp = (name) => STYLE_PROPS.has(name);
@@ -478,6 +484,25 @@ const isState = (key) => key.charCodeAt(0) === 58; /* ':' */
  */
 const SIZE_QUERY = /^@(width|height)\s*(>=|<=|>|<)\s*(\d+(?:\.\d+)?)$/;
 
+/**
+ * Container queries: `'@container width >= 400'`, or
+ * `'@container sidebar width >= 400'` naming the container. Where a size
+ * query asks about the window, this asks about the box the node is inside
+ * — the nearest ancestor whose style declares `container` (any container
+ * for the unnamed form; for the named form, the one carrying that name,
+ * however many nearer containers it has to reach past).
+ *
+ * The same operators and the same logical pixels as a size query, and the
+ * same licence: a container block may set layout properties. It differs in
+ * *when* it is answered — a container's size is what a layout pass
+ * produces, not what one starts from, so the blocks are resolved after the
+ * pass and the tree laid out once more if an answer moved
+ * (nodes.js, `_resolveContainerQueries`).
+ */
+const CONTAINER_QUERY =
+  /^@container(?:\s+([A-Za-z_][\w-]*))?\s+(width|height)\s*(>=|<=|>|<)\s*(\d+(?:\.\d+)?)$/;
+const CONTAINER_NAME = /^[A-Za-z_][\w-]*$/;
+
 /**
  * Capability queries: `'@supports transparency'`. Where a size query asks
  * about the window, this asks about the *server* — what will actually be
@@ -499,12 +524,23 @@ function parseQuery(key) {
   let q = parsedQueries.get(key);
   if (q === undefined) {
     const size = SIZE_QUERY.exec(key);
-    const supports = size ? null : SUPPORTS_QUERY.exec(key);
+    const container = size ? null : CONTAINER_QUERY.exec(key);
+    const supports = size || container ? null : SUPPORTS_QUERY.exec(key);
     q = size
       ? { kind: 'size', axis: size[1], op: size[2], value: Number(size[3]) }
-      : supports
-        ? { kind: 'supports', feature: supports[1] }
-        : null;
+      : container
+        ? {
+            kind: 'container',
+            // `''` is the unnamed query, and the key the nearest container
+            // of any name answers under
+            name: container[1] ?? '',
+            axis: container[2],
+            op: container[3],
+            value: Number(container[4]),
+          }
+        : supports
+          ? { kind: 'supports', feature: supports[1] }
+          : null;
     parsedQueries.set(key, q);
   }
   return q;
@@ -539,6 +575,69 @@ export const styleHasSizeQueries = (style) => hasQueryOfKind(style, 'size');
 export const styleHasSupportsQueries = (style) =>
   hasQueryOfKind(style, 'supports');
 
+/** Re-resolved after a layout pass moved a container the style asks about. */
+export const styleHasContainerQueries = (style) =>
+  hasQueryOfKind(style, 'container');
+
+/**
+ * Which kinds of `@` block a style carries, in **one** pass over its keys —
+ * a mask of the three below, or 0. What `_syncStyle` asks of every node on
+ * every restyle, so it is asked once rather than once per kind.
+ */
+export const QUERY_SIZE = 1;
+export const QUERY_SUPPORTS = 2;
+export const QUERY_CONTAINER = 4;
+const QUERY_KIND_BITS = {
+  size: QUERY_SIZE,
+  supports: QUERY_SUPPORTS,
+  container: QUERY_CONTAINER,
+};
+export function queryKinds(style) {
+  let kinds = 0;
+  for (const key of Object.keys(style)) {
+    if (!isQuery(key)) continue;
+    const q = parseQuery(key);
+    if (q) kinds |= QUERY_KIND_BITS[q.kind];
+  }
+  return kinds;
+}
+
+/** The container names a style asks about — `''` for the unnamed blocks —
+ *  or null when it asks about none. */
+export function containerQueryNames(style) {
+  let names = null;
+  for (const key of Object.keys(style)) {
+    if (!isQuery(key)) continue;
+    const q = parseQuery(key);
+    if (q?.kind === 'container') (names ??= new Set()).add(q.name);
+  }
+  return names;
+}
+
+/**
+ * Which of a style's container blocks match, as one string with a character
+ * per block in declaration order. What a node remembers between layout
+ * passes so a re-resolution runs only when an answer actually moved, and
+ * what the oscillation check compares (nodes.js `_resolveContainerQueries`).
+ */
+export function containerAnswers(style, containers) {
+  let out = '';
+  for (const key of Object.keys(style)) {
+    if (!isQuery(key)) continue;
+    const q = parseQuery(key);
+    if (q?.kind !== 'container') continue;
+    out += containers && sizeMatches(q, containers[q.name]) ? '1' : '0';
+  }
+  return out;
+}
+
+/** A style value is a container declaration: `true`, a name, or `false` to
+ *  take one back from a style earlier in the array. */
+export const isContainerDeclaration = (value) =>
+  value === true ||
+  value === false ||
+  (typeof value === 'string' && CONTAINER_NAME.test(value));
+
 /**
  * Merge the query blocks that match, in declaration order, over the base.
  * Size and capability blocks resolve in one pass so that ordering between
@@ -558,23 +657,39 @@ export function resolveSizeQueries(style, size) {
   return size ? resolveQueries(style, { size }) : style;
 }
 
-export function resolveQueries(style, { size = null, supports = null } = {}) {
+export function resolveQueries(
+  style,
+  { size = null, supports = null, containers = null } = {},
+) {
   let out = style;
   for (const key of Object.keys(style)) {
     if (!isQuery(key)) continue;
     const q = parseQuery(key);
-    if (!q) continue;
-    const hit =
-      q.kind === 'size'
-        ? size && sizeMatches(q, size)
-        : Boolean(supports?.[q.feature]);
-    if (!hit) continue;
+    if (!q || !queryMatches(q, size, supports, containers)) continue;
     if (out === style) out = { ...style };
     Object.assign(out, style[key]);
   }
   return out;
 }
 
+/**
+ * `containers` maps a container name (`''` for the unnamed query) to that
+ * container's size in the node's logical pixels; a name it does not hold is
+ * a container the node has not got — above it, or laid out yet — and the
+ * block does not apply. That is the rule that lets one component render
+ * inside and outside a `sidebar` container with the same style.
+ */
+function queryMatches(q, size, supports, containers) {
+  switch (q.kind) {
+    case 'size':
+      return Boolean(size) && sizeMatches(q, size);
+    case 'container':
+      return Boolean(containers) && sizeMatches(q, containers[q.name]);
+    default:
+      return Boolean(supports?.[q.feature]);
+  }
+}
+
 /**
  * The two style values that are a small language rather than a number, and
  * therefore the two that can be *wrong* rather than merely absent. Parsed in
@@ -605,7 +720,9 @@ function validateStyle(style, where) {
       if (!parseQuery(key)) {
         throw new Error(
           `react-x11: bad query "${key}" in ${where} (expected a size query ` +
-            'like "@width >= 600", or a capability query like ' +
+            'like "@width >= 600", a container query like ' +
+            '"@container width >= 400" or "@container sidebar width >= 400", ' +
+            'or a capability query like ' +
             `"@supports ${SUPPORTS_FEATURES.join('" / "@supports ')}")`,
         );
       }
@@ -641,6 +758,13 @@ function validateStyle(style, where) {
     // anything wrong, it simply never moves.
     if (key === 'animation') animationsOf(style, where);
     validateValue(key, style[key], where);
+    if (key === 'container' && !isContainerDeclaration(style[key])) {
+      throw new Error(
+        `react-x11: invalid container ${JSON.stringify(style[key])} in ` +
+          `${where} (expected true, or a name like 'sidebar' — letters, ` +
+          "digits, '_' and '-', not starting with a digit)",
+      );
+    }
     if (key === 'flex' && !isFlexShorthand(style[key])) {
       throw new Error(
         `react-x11: invalid flex ${JSON.stringify(style[key])} in ${where} ` +
@@ -671,10 +795,13 @@ export function flattenStyle(style, into) {
   // hoisted style across renders
   if (!into) return style;
   for (const key of Object.keys(style)) {
-    // a state block merges with one already collected rather than replacing
-    // it, so [{':hover': {color}}, {':hover': {backgroundColor}}] keeps both
+    // a state or query block merges with one already collected rather than
+    // replacing it, so [{':hover': {color}}, {':hover': {backgroundColor}}]
+    // keeps both — and so does the same '@width >= 600' key written twice
     into[key] =
-      isState(key) && into[key] ? { ...into[key], ...style[key] } : style[key];
+      (isState(key) || isQuery(key)) && into[key]
+        ? { ...into[key], ...style[key] }
+        : style[key];
   }
   return into;
 }
@@ -788,6 +915,23 @@ const EASINGS = {
 
 export const EASING_NAMES = Object.freeze(Object.keys(EASINGS));
 
+/**
+ * The same curves as cubic-bezier control points, for a presenter whose
+ * render server evaluates them itself (src/cocoa/presenter.js). The two
+ * evaluators have to agree on one declaration, and they do: each polynomial
+ * above and its bezier twin differ by at most 0.01 over the unit interval
+ * (test/style.test.js pins it). Core Animation's *named* curves are not
+ * these — its `easeOut` is (0, 0, 0.58, 1), 0.22 away from `ease` at
+ * t = 0.35 — which is why the presenter sends points rather than names. A
+ * new easing lands in both tables or in neither.
+ */
+export const EASING_CONTROL_POINTS = Object.freeze({
+  linear: Object.freeze([0, 0, 1, 1]),
+  'ease-in': Object.freeze([0.32, 0, 0.67, 0]),
+  'ease-out': Object.freeze([0.33, 1, 0.68, 1]),
+  'ease-in-out': Object.freeze([0.65, 0, 0.35, 1]),
+});
+
 /** A value that is still a `$token` reference, or mentions one. */
 const unresolvedValue = (v) => isToken(v) || mentionsToken(v);
 
@@ -1119,6 +1263,8 @@ export function tint(color, alpha) {
 // ease-out cubic: fast to start, settles gently — the shape almost every UI
 // toolkit defaults to for state changes
 export const ease = (t) => 1 - (1 - t) ** 3;
+/** …and the same curve as control points, for the presenter (above). */
+export const TRANSITION_CONTROL_POINTS = EASING_CONTROL_POINTS['ease-out'];
 
 /**
  * Theme tokens. A style value of `'$name'` resolves against the nearest

package/src/textselection.js

@@ -32,8 +32,6 @@ import { callHandler } from './errors.js';
 import { lastInputTime } from './inputtime.js';
 import { ctrlChordLetter } from './keysyms.js';
 import { codePoints, wordRangeAt } from './textrange.js';
-import { tint } from './styles.js';
-
 // --- who is showing a selection ------------------------------------------
 //
 // One node per app: a `<textinput>`, or the surface below. The registry is
@@ -316,8 +314,7 @@ export class TextSelection {
    * the drag, the keys, and the programmatic `setSelection`.
    */
   apply() {
-    const color =
-      this.node.props.selectionColor ?? tint(this.node.theme.accent, 0.35);
+    const color = this.node.props.selectionColor ?? this.node.theme.selection;
     const next = this.rangesOf(this.ordered());
     let changed = false;
     for (const [node, range] of next) {

package/src/trayhooks.js

@@ -0,0 +1,90 @@
+// `useTray()` — an icon in the system tray for as long as a component is
+// mounted, on the backends that have one.
+//
+// Today that is the cocoa backend's menu-bar extra (`NSStatusItem`,
+// src/cocoa/statusitem.js). The freedesktop counterpart, StatusNotifierItem
+// over D-Bus, is react-x11#353's open question; until it lands the hook is
+// inert on X11 and says so — `available: false`, and a one-time development
+// note — rather than pretending, so an app can keep the feature behind the
+// answer. The inert-props policy of docs/macos.md, for a hook.
+
+import { useEffect, useRef, useState } from 'react';
+
+import { useAppOrNull } from './appcontext.js';
+
+let warnedInert = false;
+
+/**
+ * An icon in the system tray while this component is mounted.
+ *
+ * ```jsx
+ * const { available } = useTray({
+ *   icon: 'bell.badge',              // an SF Symbol name, or PNG bytes
+ *   tooltip: 'Notifications',
+ *   menu: [{ label: 'Open', onSelect: open }, { label: 'Quit', onSelect: quit }],
+ * });
+ * ```
+ *
+ * With `menu`, a click opens it — the same `items` vocabulary `MenuBar` and
+ * `useDockMenu` take, an item's `onSelect` firing when picked. Without one,
+ * `onClick` is called with the button and the item's screen rect, which is
+ * where to anchor a popup of your own. `null` means no item. Every field
+ * follows its value while mounted; the item is removed on unmount.
+ *
+ * `available` is whether this backend has a tray at all: false on X11
+ * today (#353), and the honest answer to branch on.
+ */
+export function useTray(options) {
+  const app = useAppOrNull();
+  const available = typeof app?.createStatusItem === 'function';
+  const itemRef = useRef(null);
+  const [rect] = useState(null);
+
+  // the options a click or a pick reads are the current render's, not the
+  // ones the item was created with three minutes ago
+  const live = useRef(options);
+  live.current = options;
+
+  useEffect(() => {
+    if (!available) {
+      if (process.env.NODE_ENV !== 'production' && !warnedInert && app) {
+        warnedInert = true;
+        console.warn(
+          'react-x11: useTray() is inert on this backend — the freedesktop ' +
+            'tray (StatusNotifierItem) is not implemented yet (#353). Read ' +
+            '`available` to keep the feature behind the answer.',
+        );
+      }
+      return undefined;
+    }
+    if (!options) return undefined;
+    const item = app.createStatusItem({
+      ...options,
+      onClick: (ev) => live.current?.onClick?.(ev),
+    });
+    itemRef.current = item;
+    return () => {
+      itemRef.current = null;
+      item.remove();
+    };
+    // Recreated only when the item comes or goes: the fields patch in
+    // place below, and an `options` object rebuilt every render must not
+    // rebuild the item every render.
+  }, [app, available, options == null]);
+
+  useEffect(() => {
+    const item = itemRef.current;
+    if (!item || !options) return;
+    item.update({ ...options, onClick: (ev) => live.current?.onClick?.(ev) });
+  }, [
+    options?.icon,
+    options?.title,
+    options?.tooltip,
+    options?.visible,
+    options?.template,
+    options?.length,
+    options?.menu,
+  ]);
+
+  return { available, rect };
+}

package/src/types/appearance.d.ts

@@ -3,6 +3,7 @@
  * and reduced motion. See docs/appearance.md.
  */
 
+import type { Theme } from './components.js';
 import type { NtkApp } from './nodes.js';
 
 /**
@@ -32,6 +33,29 @@ export interface SystemAppearance {
    * own brand colour rather than to grey.
    */
   readonly accent: string | null;
+  /**
+   * The ink the desktop writes on its accent — `'#ffffff'` on macOS, whatever
+   * the accent — or **null** where the source names a fill and nothing about
+   * what goes on it (the portal). The built-in palette uses it as
+   * `accentText`, and picks the legible ink by contrast where it is null.
+   */
+  readonly accentText: string | null;
+  /**
+   * The fill the desktop puts under a selected menu or list row — on macOS
+   * `selectedContentBackgroundColor`, a darker cut of the accent — or
+   * **null** where nothing names one. The built-in palette uses it as
+   * `hoverBackground`, and the accent itself where it is null.
+   */
+  readonly selection: string | null;
+  /**
+   * The desktop's whole palette as react-x11 tokens, where the desktop can
+   * name one: on macOS the semantic colours AppKit paints its own windows
+   * and controls with, flattened over the window ground. The built-in
+   * palette merges it over the scheme's own, so an app that says nothing
+   * about colour comes up in the desktop's greys, inks and status colours.
+   * Null from the portal and XSETTINGS, which name no such thing.
+   */
+  readonly palette: Readonly<Partial<Theme>> | null;
   readonly contrast: 'normal' | 'high';
   readonly reducedMotion: boolean;
   /**

package/src/types/components.d.ts

@@ -81,6 +81,16 @@ export interface Theme {
   /** The keyboard focus ring every focusable node under this palette draws
    * on `:focus-visible` — read by the renderer, not by the widgets. */
   focusRing: string;
+  /** The highlight behind selected text: a tint of `accent` unless a
+   * palette names it. A desktop that names one — macOS's Highlight colour —
+   * gives an opaque fill here. */
+  selection: string;
+  /** The insertion caret, or `null` for the text's own colour, which is what
+   * a caret is unless the desktop says otherwise. */
+  caret: string | null;
+  /** Ink for a link. Not the accent: a link is blue everywhere, as a note
+   * is. */
+  link: string;
   focusRingWidth: number;
   focusRingOffset: number;
   radius: number;

package/src/types/elements.d.ts

@@ -23,6 +23,7 @@ import type {
   SubmitEvent,
   SyntheticEvent,
   ViewportEvent,
+  LayoutEvent,
   WheelEvent,
   WindowResizeEvent,
 } from './events.js';
@@ -188,6 +189,15 @@ export interface DrawnProps<T = DrawnNode>
     SelectionProps<T>,
     EventHandlers<T> {
   ref?: Ref<T>;
+  /**
+   * After a layout pass moved or resized this element: `{x, y, width,
+   * height}` in logical pixels, the position within the parent as laid out
+   * — so scrolling does not fire it. Once after the first layout, then only
+   * on change; deferred past the pass, so `setState` in it is safe. The
+   * seam for a decision that is not a style; where it is one, a
+   * `'@container'` block answers in the same frame (docs/styling.md).
+   */
+  onLayout?: (ev: LayoutEvent) => void;
   /**
    * Zoom this subtree, CSS `zoom` rather than a transform: every length
    * under here — and this element's *own* style — is multiplied by it, so
@@ -348,6 +358,10 @@ export interface WindowProps
    *
    * Applied before the window is mapped, which is the only way to open
    * already fullscreen rather than flashing at the normal size first.
+   *
+   * On the cocoa backend `demands_attention` bounces the Dock icon until
+   * the app is activated and is cancelled when the state is removed; the
+   * other names have no verb in the bridge yet and resolve to nothing.
    */
   states?: WindowStateName[];
   /** Sugar for `states={['fullscreen']}`; they union. */

package/src/types/events.d.ts

@@ -335,6 +335,20 @@ export interface ScrollEvent {
   viewportHeight: number;
 }
 
+/**
+ * `onLayout` on any drawn element: the rect a layout pass gave it, in its
+ * own logical pixels — `x`/`y` the position **within the parent as laid
+ * out**, which scrolling does not move. Reported after the first layout and
+ * then only when it changes, deferred past the pass so state set from it is
+ * safe. See docs/react-features.md#measuring-a-node.
+ */
+export interface LayoutEvent {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
 /** `<box onViewport>` — fired from layout, not from scrolling. */
 export interface ViewportEvent {
   width: number;

package/src/types/filedialog.d.ts

@@ -25,20 +25,26 @@ export interface AbortSignalLike {
   removeEventListener(type: 'abort', listener: () => void): void;
 }
 
-/** Which rung of the ladder answered — or would. */
-export type FileDialogBackend = 'portal' | 'osascript' | 'builtin';
+/**
+ * Which rung of the ladder answered — or would. `'cocoa'` is the native
+ * `NSOpenPanel`/`NSSavePanel` on the cocoa backend; `'osascript'` is macOS on
+ * the X11 backend.
+ */
+export type FileDialogBackend = 'cocoa' | 'portal' | 'osascript' | 'builtin';
 
 /**
  * One entry in a dialog's type filter.
  *
  * Give `extensions` where you can: they translate to every backend. MIME types
- * reach the portal exactly and macOS not at all — see docs/filedialog.md.
+ * reach the portal and the native macOS panel exactly, and `osascript` not at
+ * all — see docs/filedialog.md.
  */
 export interface FileFilter {
   name: string;
   /** `['png', 'jpg']` — with or without the leading dot. */
   extensions?: string[];
-  /** `['image/png']`. Portal only. */
+  /** `['image/png']`. The portal and the native macOS panel; dropped by
+   * `osascript`. */
   mimeTypes?: string[];
 }
 
@@ -65,11 +71,16 @@ export interface FileDialogOptions {
   acceptLabel?: string;
   /**
    * The window the dialog belongs to. `transientFor` for the built-in dialog,
-   * `parent_window` for the portal; macOS has no cross-process equivalent and
-   * ignores it. Worth the one line — without it the dialog floats.
+   * `parent_window` for the portal, and the window the native macOS panel is
+   * a **sheet** on; `osascript` has no cross-process equivalent and ignores
+   * it. Worth the one line — without it the dialog floats, and on the cocoa
+   * backend a panel with no window is app-modal and blocks the process until
+   * it is dismissed.
    */
   parentWindow?: WindowTarget;
-  /** Abort the dialog. Closes the portal request or kills `osascript`. */
+  /** Abort the dialog. Closes the portal request, dismisses the native
+   * panel, or kills `osascript`; the promise rejects with the signal's
+   * reason. */
   signal?: AbortSignalLike;
   /**
    * Force a rung instead of taking the best available one. The seam for a

package/src/types/launcher.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The launcher's view of the app: a badge on its icon, and the Dock menu.
+ * See docs/desktop.md "The launcher".
+ */
+
+import type { MenuItem } from './components.js';
+import type { NtkApp } from './nodes.js';
+
+/**
+ * What a badge shows. A number shows on both backends; a string shows on
+ * macOS and is a visible count of nothing on Linux, whose protocol carries
+ * only a count. `0`, `null`, `''`, `false` and `undefined` all clear it.
+ */
+export type BadgeValue = number | string | null | false | undefined;
+
+export interface SetBadgeOptions {
+  /** The connection whose icon to badge, when there are several. */
+  app?: NtkApp;
+}
+
+/**
+ * Show `value` on the app's icon, or clear it.
+ *
+ * `NSDockTile.badgeLabel` on the cocoa backend; the
+ * `com.canonical.Unity.LauncherEntry` signal on Linux, which needs the
+ * identity `registerApplication({ appId })` establishes. Resolves to whether
+ * a launcher was told, and never rejects for anything about the machine.
+ */
+export declare function setBadge(
+  value: BadgeValue,
+  options?: SetBadgeOptions,
+): Promise<boolean>;
+
+/** {@link setBadge} while mounted; cleared on unmount. */
+export declare function useBadge(value: BadgeValue): void;
+
+/**
+ * The menu behind a right-click on the Dock icon, from the same item
+ * vocabulary `MenuBar` takes; an item's `onSelect` fires when picked.
+ * Installed while mounted, replaced when `items` changes, taken down on
+ * unmount. Inert off the cocoa backend.
+ */
+export declare function useDockMenu(items: MenuItem[] | null): void;