react-x11 2.15.3 → 2.16.1

package/src/types/components.d.ts

@@ -418,6 +418,17 @@ export interface SliderProps
   disabled?: boolean;
   height?: number;
   style?: StyleProp;
+  /**
+   * The thumb's style, over its default: a 16px circle on `surface` with a
+   * ring. Its `width` and `height`, as numbers, are what the drag's travel
+   * and the control's height are measured with.
+   */
+  thumbStyle?: StyleProp;
+  /** The track's style, over `height` and `track`. Its `height` is the
+   *  fill's too. */
+  trackStyle?: StyleProp;
+  /** The filled part of the track, up to the value, over `accent`. */
+  fillStyle?: StyleProp;
 }
 export const Slider: ComponentType<SliderProps>;
 
@@ -761,6 +772,28 @@ export function anchorRect(
   options?: AnchorOptions,
 ): AnchorRect | null;
 
+/**
+ * The same placement against a rect **on the screen** rather than a node —
+ * the item a tray click reports, a point where the pointer was — in logical
+ * screen pixels on both sides. With no node to ask, `scale` is the
+ * display's (default 1) and `direction` decides `'start'` and `'end'`; the
+ * popup is kept on the monitor the rect is on. `null` for a rect with no
+ * `x`/`y`.
+ */
+export function anchorScreenRect(
+  app: unknown,
+  rect: ScreenAnchorRect,
+  options?: Omit<AnchorOptions, 'at' | 'alignTo'> & { scale?: number },
+): AnchorRect | null;
+
+/** A rect on the screen, in logical pixels; `{x, y}` alone is a point. */
+export interface ScreenAnchorRect {
+  x: number;
+  y: number;
+  width?: number;
+  height?: number;
+}
+
 /** Centre a popup of this size on the node's screen. */
 export function centerRect(
   node: DrawnNode,

package/src/types/elements.d.ts

@@ -5,14 +5,14 @@
  */
 
 import type { Ref, RefObject, ReactNode, Key } from 'react';
-import type { Color, Cursor, StyleProp } from './style.js';
+import type { Color, Cursor, FontWeight, StyleProp } from './style.js';
 import type {
   DrawnNode,
   NtkWindow,
   ScrollableNode,
   TextInputNode,
 } from './nodes.js';
-import type { AnchorOptions } from './components.js';
+import type { AnchorOptions, ScreenAnchorRect } from './components.js';
 import type {
   ChangeEvent,
   SelectionChangeEvent,
@@ -580,6 +580,16 @@ export interface PopupProps extends WindowProps {
    * this client at all. Needs ntk >= 3.7.0.
    */
   grab?: boolean;
+  /**
+   * Take the keyboard while the popup is up: its keys come to it whatever
+   * holds the focus, which is what a popover a tray click opened needs — a
+   * menu-bar app has no window of its own for keys to arrive at. A keyboard
+   * grab on X, taken and dropped with the map like `grab`. On macOS a window
+   * AppKit can make key, shown activating the app, as `NSPopover`'s own
+   * window is — decided when the popup is created, so it does not change on
+   * a mounted one. A grabbing popup on Wayland has the keyboard already.
+   */
+  grabKeyboard?: boolean;
   /**
    * `true` (the default) keeps the window manager out entirely, which is
    * what makes a menu a menu — no frame, no repositioning, no taskbar entry.
@@ -597,7 +607,9 @@ export interface PopupProps extends WindowProps {
   /**
    * Hang this popup off a node — `anchorRect`'s options plus the node to
    * measure, and the popup works out its own position from them, ignoring
-   * `x`/`y`.
+   * `x`/`y`. Or off a rect on the screen with no node behind it, `rect`
+   * instead of `to`: the item a tray click reports, placed against with the
+   * same flip and clamp.
    *
    * What this does that computing a rect in the application cannot: a popup
    * with an `'auto'` size only knows how big it is *inside* `realize()`,
@@ -622,12 +634,26 @@ export interface PopupProps extends WindowProps {
  *  that renders them) or the node itself. */
 export type AnchorTarget = DrawnNode | RefObject<DrawnNode | null> | null;
 
-export interface PopupAnchor extends Omit<AnchorOptions, 'alignTo'> {
+/** Where a popup hangs: a node, or a rect on the screen. */
+export type PopupAnchor = NodeAnchor | ScreenAnchor;
+
+export interface NodeAnchor extends Omit<AnchorOptions, 'alignTo'> {
   /** The node this popup hangs off. */
   to: AnchorTarget;
   /** Takes the alignment axis from another node — see
    *  {@link AnchorOptions.alignTo}. */
   alignTo?: AnchorTarget;
+  rect?: never;
+}
+
+export interface ScreenAnchor extends Omit<AnchorOptions, 'alignTo' | 'at'> {
+  /**
+   * A rect on the screen, in logical pixels — what `useTray`'s `onClick`
+   * reports where the platform knows the item's frame. `{x, y}` alone is a
+   * point. Nothing moves it but a new one, and it is never out of view.
+   */
+  rect: ScreenAnchorRect;
+  to?: never;
 }
 
 // --- drawn elements --------------------------------------------------------
@@ -758,10 +784,35 @@ export interface FileUrl {
 
 /**
  * What `src` accepts: a file path or file URL (PNG/JPEG, decoded in JS),
- * encoded PNG/JPEG bytes, raw RGBA pixels, or an ntk `Image`/`Surface`.
+ * encoded PNG/JPEG bytes, raw RGBA pixels, an ntk `Image`/`Surface`, or a
+ * symbol by name.
  */
 export type ImageSource =
-  string | FileUrl | Uint8Array | RawImageSource | DirectImageSource;
+  | string
+  | FileUrl
+  | Uint8Array
+  | RawImageSource
+  | DirectImageSource
+  | SymbolImageSource;
+
+/**
+ * The platform's own icon by name, drawn in the text colour: an SF Symbol on
+ * macOS (`'speaker.wave.3.fill'`), and elsewhere an icon from the user's
+ * freedesktop icon theme (`'audio-volume-high'`), its `-symbolic` variant
+ * preferred. Sized like the text around it — the size its `fontSize` calls
+ * for — unless the element is styled a size of its own. A name this desktop
+ * does not have takes no room and draws nothing.
+ */
+export interface SymbolImageSource {
+  symbol: string;
+  /** Default: the weight of the text around it. SF Symbols only. */
+  weight?: FontWeight;
+  /** Relative to the text size, default `'medium'`. SF Symbols only. */
+  scale?: 'small' | 'medium' | 'large';
+  /** How much of a variable symbol shows, 0 to 1 — the waves of
+   *  `speaker.wave.3.fill` at a volume. SF Symbols on macOS 13 and later. */
+  variableValue?: number;
+}
 
 /**
  * An existing server-side Picture, named by X id. The size is stated by the

package/src/types/events.d.ts

@@ -541,6 +541,11 @@ export interface AcceleratorOptions {
  * matched against the Latin keysym so a layout switch does not turn it off,
  * and behind whatever a focused element consumed with `preventDefault()`.
  * See docs/events.md.
+ *
+ * With no `scope` the binding belongs to the tree's top-level `<window>`, or,
+ * in an app that has none, to the root-level `<popup>` holding the keyboard —
+ * a tray popover. One that can reach neither binds nothing and says so once
+ * in development.
  */
 export function useAccelerator(
   shortcut: MenuShortcut,

package/src/types/filedialog.d.ts

@@ -162,7 +162,9 @@ export interface FileDialogs {
  *
  * Exact when the tree has one top-level window, which is nearly every app.
  * With several it prefers the focused one and warns in development when it
- * has to guess — see docs/filedialog.md.
+ * has to guess; with none — a menu-bar app, which is a tray item and a
+ * popover — it answers the root-level `<popup>` that took the keyboard. See
+ * docs/filedialog.md.
  */
 export declare function useTopLevelWindow(): {
   readonly current: NtkWindow | DrawnNode | null;

package/src/types/style.d.ts

@@ -305,6 +305,14 @@ export interface PaintStyle {
   outlineColor?: Color;
   /** The gap between the border box and the ring. Default 1. */
   outlineOffset?: number;
+  /**
+   * How opaque the node is **with everything inside it**, from 0 to 1: the
+   * subtree is drawn once and composited at this alpha, so a card, its
+   * border, its icon and its text fade as one. A paint property — legal in a
+   * state block, and it transitions and loops. `0` draws nothing and is
+   * still hit; values outside 0..1 are clamped.
+   */
+  opacity?: number;
 }
 
 /**
@@ -327,6 +335,34 @@ export type TextOverflow = 'clip' | 'ellipsis';
 export type TextRendering =
   'auto' | 'optimizeSpeed' | 'optimizeLegibility' | 'geometricPrecision';
 
+/** One `fontVariantNumeric` keyword, and the OpenType feature it turns on. */
+export type NumericVariant =
+  | 'lining-nums' // lnum
+  | 'oldstyle-nums' // onum
+  | 'proportional-nums' // pnum
+  | 'tabular-nums' // tnum
+  | 'diagonal-fractions' // frac
+  | 'stacked-fractions' // afrc
+  | 'ordinal' // ordn
+  | 'slashed-zero'; // zero
+
+/**
+ * CSS's `font-variant-numeric`: `'normal'`, or keywords separated by spaces,
+ * at most one of each pair that contradicts — lining or oldstyle,
+ * proportional or tabular, diagonal or stacked fractions. Typed as a first
+ * keyword and whatever follows; the rest is checked when the style is.
+ */
+export type FontVariantNumeric =
+  'normal' | NumericVariant | `${NumericVariant} ${string}`;
+
+/**
+ * CSS's `font-feature-settings`, by OpenType tag: the tags to turn on,
+ * `['tnum', 'ss01']`, or tag → on or off, or the alternate a feature picks,
+ * `{ liga: false, salt: 2 }`.
+ */
+export type FontFeatureSettings =
+  readonly string[] | Readonly<Record<string, boolean | number>>;
+
 /** Text properties. All affect measurement except `color`. */
 export interface TextStyle {
   color?: Color;
@@ -346,6 +382,19 @@ export interface TextStyle {
    *  at any size. `'auto'` (default) lets size decide. Changing it repaints
    *  without reflowing: it cannot move anything. */
   textRendering?: TextRendering;
+  /** CSS's `letter-spacing`, in pixels: added after every character, the
+   *  last on a line included, and negative to tighten. Spaced text drops the
+   *  optional ligatures (`liga`, `clig`, `dlig`, `hlig`) unless
+   *  `fontFeatureSettings` names them. Inherits. */
+  letterSpacing?: number;
+  /** Which figures: `'tabular-nums'` gives every digit one width, so a
+   *  number that changes holds its width while it does. The friendly names
+   *  for features `fontFeatureSettings` can also set by tag, and it wins
+   *  where the two meet. Inherits, apart from `fontFeatureSettings`. */
+  fontVariantNumeric?: FontVariantNumeric;
+  /** Any OpenType feature, by tag. A feature the face does not have is
+   *  ignored. Compared by value, so an object literal is fine. Inherits. */
+  fontFeatureSettings?: FontFeatureSettings;
   textAlign?: TextAlign;
   lineHeight?: number;
   /** CSS's `text-wrap`. `'nowrap'` measures the text at unbounded width, so
@@ -436,6 +485,14 @@ export interface AnimationSpec {
   easing?: Easing;
   /** Turn around at each end instead of wrapping back to `from`. */
   alternate?: boolean;
+  /**
+   * When the loop's own time starts, in ms — CSS's `animation-delay`. A
+   * positive delay holds `from` that long before the first crossing; a
+   * negative one starts the loop that far in. Default `0`. What staggers
+   * loops of one duration: three dots at `0`, `-150` and `-300` never move
+   * together.
+   */
+  delay?: number;
 }
 
 /**

package/src/types/system.d.ts

@@ -267,6 +267,110 @@ export interface DesktopSettings {
  */
 export function useDesktopSettings(): DesktopSettings;
 
+// --------------------------------------------------------------------------
+// The app's own settings
+// --------------------------------------------------------------------------
+
+/** A value a settings store can keep: what JSON can. */
+export type SettingValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly SettingValue[]
+  | { readonly [key: string]: SettingValue };
+
+export interface SettingsOptions<T extends Record<string, SettingValue>> {
+  /**
+   * A reverse-DNS name no other app uses, like `'com.example.myapp'`: the
+   * name of the app's settings directory. Nothing is registered with it.
+   */
+  appId: string;
+  /** Each setting's value when nothing was saved. */
+  defaults?: T;
+  /** Where `settings.json` goes instead of the per-user directory for the
+   *  app — for a portable install, or a test. */
+  directory?: string;
+}
+
+/** A value's kind: `false` as `boolean`, `'brown'` as `string`, so a
+ *  default does not narrow what the setting may be set to. */
+export type SettingKind<V> = V extends boolean
+  ? boolean
+  : V extends string
+    ? string
+    : V extends number
+      ? number
+      : V;
+
+/** A setting's type: its default's kind, for a key the defaults name, else
+ *  the fallback's. */
+export type SettingOf<T, K, V> = SettingKind<K extends keyof T ? T[K] : V>;
+
+/**
+ * What an app remembers between launches, kept in `settings.json` in its
+ * per-user directory, written atomically and coalesced.
+ */
+export interface Settings<T extends Record<string, SettingValue>> {
+  /** The file the values are kept in. */
+  readonly path: string;
+  /** `[value, setValue]` for one setting, like `useState`; every component
+   *  using the key sees the same value, and a change is saved. A key with no
+   *  default takes a fallback. */
+  use<K extends string, V extends SettingValue = never>(
+    key: K,
+    fallback?: V,
+  ): [
+    SettingOf<T, K, V>,
+    (
+      value:
+        | SettingOf<T, K, V>
+        | ((previous: SettingOf<T, K, V>) => SettingOf<T, K, V>),
+    ) => void,
+  ];
+  get<K extends string, V extends SettingValue = never>(
+    key: K,
+    fallback?: V,
+  ): K extends keyof T ? SettingOf<T, K, V> : SettingOf<T, K, V> | undefined;
+  /** Change a setting now, and save it a moment later — a quarter second
+   *  after the last change, and at least once a second while they keep
+   *  coming. Throws a `TypeError` for a value JSON cannot keep. */
+  set<K extends string>(
+    key: K,
+    value: K extends keyof T ? SettingOf<T, K, never> : SettingValue,
+  ): void;
+  /** Forget what was saved for a setting: its default again. */
+  reset(key: string): void;
+  /** Save what is waiting now. Resolves when it is on disk. */
+  flush(): Promise<void>;
+  /** Hear every change; returns the unsubscribe. */
+  subscribe(listener: () => void): () => void;
+}
+
+/**
+ * The settings store for an app — one per file in the process, so every call
+ * with the same `appId` shares values.
+ *
+ * ```tsx
+ * const settings = createSettings({
+ *   appId: 'com.example.Hush',
+ *   defaults: { volume: 0.5, dark: false },
+ * });
+ * function Volume() {
+ *   const [volume, setVolume] = settings.use('volume');
+ *   return <Slider value={volume} onChange={setVolume} />;
+ * }
+ * ```
+ *
+ * It lives in `~/Library/Application Support/<appId>/settings.json` on macOS
+ * and `$XDG_CONFIG_HOME/<appId>/settings.json` elsewhere, and is read the
+ * first time a value is asked for. What is still unsaved when the process
+ * exits is written then.
+ */
+export function createSettings<T extends Record<string, SettingValue>>(
+  options: SettingsOptions<T>,
+): Settings<T>;
+
 // --------------------------------------------------------------------------
 // Locale
 // --------------------------------------------------------------------------

package/src/types/tray.d.ts

@@ -7,8 +7,12 @@ import type { DesktopBackend, TrayFeatures } from './capabilities.js';
 
 export interface TrayClickEvent {
   button: 'left' | 'right' | 'middle';
-  /** Where the click was, in global top-left screen coordinates — the anchor
-   * for a popup of your own. */
+  /** Where the click was: global top-left screen coordinates in **logical
+   * pixels**, the unit a `<popup>`'s `x`/`y` and `anchor={{ rect }}` take —
+   * the anchor for a popup of your own. The freedesktop protocol names no
+   * unit for its point and hosts differ, so there it is read against the
+   * monitors and the pointer; docs/desktop.md "The tray" says where that
+   * cannot tell. */
   x: number;
   y: number;
   /** The item's rect. `0` on the freedesktop rung, whose protocol has none —
@@ -73,6 +77,14 @@ export interface TrayState {
    * flips it back.
    */
   available: boolean;
+  /**
+   * Whether `available` is an answer yet: true on the first frame on macOS,
+   * where the status item is made there and then, and for `null` options;
+   * on the freedesktop tray, once the host has taken or refused the item. An
+   * app whose whole UI is its tray renders nothing until this, instead of a
+   * fallback window that flashes on every start.
+   */
+  settled: boolean;
   /** Which mechanism took it, or null. */
   backend: DesktopBackend | null;
   /** What that mechanism can do. Empty until `available` settles. */