react-x11 2.15.2 → 2.16.0

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

@@ -3,16 +3,26 @@
  */
 
 import type { MenuItem } from './components.js';
+import type { DesktopBackend, TrayFeatures } from './capabilities.js';
 
 export interface TrayClickEvent {
   button: 'left' | 'right' | 'middle';
-  /** The item's screen rect, global top-left coordinates in points — 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 —
+   * read `features.clickRect` rather than testing for zero. */
   width: number;
   height: number;
+  /** `1` on the freedesktop rung, which does not count clicks. */
   clickCount: number;
+  /** All `false` on the freedesktop rung, which carries no modifier state.
+   * `features.clickModifiers` is the honest answer. */
   shift: boolean;
   control: boolean;
   option: boolean;
@@ -20,9 +30,27 @@ export interface TrayClickEvent {
 }
 
 export interface TrayOptions {
-  /** An SF Symbol name (`'bell.badge'`), or the bytes of a PNG. Drawn as a
-   * template image so it follows the bar's light and dark. */
+  /** A themed icon name — an SF Symbol on the cocoa rung (`'bell.badge'`),
+   * an icon-theme name on a freedesktop one (`'mail-unread'`) — or the bytes
+   * of a PNG. On the cocoa rung bytes are drawn as a template image so they
+   * follow the bar's light and dark. */
   icon?: string | Uint8Array | null;
+  /** Shown instead of `icon` while `attention` is set. Freedesktop only. */
+  attentionIcon?: string | Uint8Array | null;
+  /** A small badge drawn over the icon. Freedesktop only. */
+  overlayIcon?: string | Uint8Array | null;
+  /** Ask the panel to mark the item — `Status = NeedsAttention`.
+   * Freedesktop only; `features.attention` says so. */
+  attention?: boolean;
+  /** The spec's item category: `'ApplicationStatus'` (default),
+   * `'Communications'`, `'SystemServices'` or `'Hardware'`. Freedesktop
+   * only, and mostly affects where a panel sorts the icon. */
+  category?: string;
+  /** A directory to look `icon` up in, for icons shipped beside the app
+   * rather than installed in a theme. Freedesktop only. */
+  iconThemePath?: string;
+  /** A scroll over the icon. Freedesktop only. */
+  onScroll?: (event: { delta: number; orientation: string }) => void;
   /** Text beside the icon, or alone. */
   title?: string | null;
   tooltip?: string | null;
@@ -40,8 +68,33 @@ export interface TrayOptions {
 }
 
 export interface TrayState {
-  /** Whether this backend has a tray at all — false on X11 today (#353). */
+  /**
+   * Whether **this item** was taken by a tray.
+   *
+   * A measurement, not a prediction: the hook tried. It **settles** — false
+   * on the first frame, true a tick later if a host is there — so render the
+   * fallback first and upgrade. It follows the host, so a panel that exits
+   * 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. */
+  features: Partial<TrayFeatures>;
+  /**
+   * A tray that answered and then **refused**, which is a different fact from
+   * a desktop with no tray — and the only one of the two with a fix. Null
+   * when there is simply no tray.
+   */
+  error: Error | null;
   /** Reserved. */
   rect: null;
 }
@@ -49,6 +102,11 @@ export interface TrayState {
 /**
  * An icon in the system tray while this component is mounted; every field
  * follows its value, and the item is removed on unmount. `null` means no
- * item. Inert off the cocoa backend, with `available: false`.
+ * item.
+ *
+ * `NSStatusItem` on the cocoa backend; `org.kde.StatusNotifierItem` over
+ * D-Bus on a freedesktop session, which needs something hosting a tray —
+ * Plasma and most panels do, GNOME needs an AppIndicator extension. Where
+ * neither answers, `available` stays false and nothing is logged.
  */
 export declare function useTray(options: TrayOptions | null): TrayState;