react-x11 1.2.0 → 2.0.0

package/src/types/nodes.d.ts

@@ -0,0 +1,199 @@
+/**
+ * What a `ref` gives you. Drawn elements hand back their retained node;
+ * `<window>` and `<popup>` hand back the live ntk `Window`, so the whole
+ * ntk API is available from a ref.
+ */
+
+/** A rectangle within the owning window, valid after layout. */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** The retained node behind a drawn element. */
+export interface DrawnNode {
+  /** Element name — `'box'`, `'text'`, and the name a registered element
+   * was registered under. What queries and paint order match on:
+   * `screen.all((n) => n.kind === 'gauge')`. */
+  readonly kind: string;
+  /** Position and size within the owning window, valid after layout. */
+  readonly abs: Rect;
+  readonly parent: DrawnNode | null;
+  readonly children: readonly DrawnNode[];
+  /** Take the keyboard focus, if this node is focusable. Returns the node,
+   * so a component can hand it straight out of an imperative handle. */
+  focus(): this;
+  blur(): this;
+  /** Whether this node has the owning window's focus. */
+  readonly focused: boolean;
+  /** Whether focus is on this node or inside it — CSS `:focus-within`. */
+  readonly focusWithin: boolean;
+  /**
+   * Which way this node reads, resolved — `'ltr'` or `'rtl'`, never
+   * `'inherit'`. The `direction` style property here or on the nearest
+   * element above, and the palette's under all of them.
+   *
+   * What a widget measuring a pointer against a laid-out box has to ask: a
+   * coordinate means the opposite thing in the two directions, so a drag
+   * reads this rather than the theme.
+   */
+  readonly direction: 'ltr' | 'rtl';
+  /** Whether `node` is this node or a descendant of it (DOM `contains`). */
+  contains(node: DrawnNode | null): boolean;
+  getClientRects(): Rect[];
+
+  // --- text geometry (docs/elements.md, "Selection") ------------------------
+  //
+  // Every drawn node answers these; an element with no text answers `null`,
+  // `0` and `[]`. Indices are **code points** and rectangles are in the
+  // owning window's coordinates — the same space as `abs` and a mouse
+  // event's `x`/`y`.
+
+  /** This element's text, or null when it has none. */
+  textContent(): string | null;
+  /** The character boundary nearest a point. Clamps to the ends. */
+  textIndexAt(x: number, y: number): number;
+  /** Where a caret at this index stands — a zero-width rect. */
+  textCaretRect(index: number): Rect | null;
+  /** The bands a highlight over `[start, end)` fills: one per line, and one
+   * per direction run within a line. */
+  textRangeRects(start: number, end: number): Rect[];
+  /** The part of this element's text the document selection covers. */
+  readonly selectionRange: { start: number; end: number } | null;
+  /** What to fill `textRangeRects` with while `selectionRange` is set. */
+  readonly selectionColor: string | null;
+
+  // --- being a selection surface (`selectable`) -----------------------------
+
+  /** The selection this element owns, or null when it is not `selectable`.
+   * A snapshot: read it again after a change. */
+  readonly textSelection: TextSelectionSnapshot | null;
+  /** Select everything in this surface, and take PRIMARY with it. */
+  selectAll(): this;
+  /** Drop the selection. PRIMARY is left where it is. */
+  clearSelection(): this;
+  /** What a copy would put on the clipboard. */
+  selectedText(): string;
+  /** Set both ends by hand. `setSelection(null)` clears. */
+  setSelection(anchor: TextPosition | null, focus?: TextPosition | null): this;
+}
+
+/** One end of a selection: a code-point index into an element's text. */
+export interface TextPosition {
+  node: DrawnNode;
+  index: number;
+}
+
+/** What `node.selection` answers with. */
+export interface TextSelectionSnapshot {
+  isCollapsed: boolean;
+  /** The assembled text, with the separators a copy would use. */
+  text: string;
+  /** Every element the selection reaches, in document order. */
+  ranges: readonly (TextPosition & { start: number; end: number })[];
+}
+
+export interface ScrollTarget {
+  x?: number;
+  y?: number;
+}
+
+/**
+ * What a `<box>` ref is: a drawn node that also scrolls. The scrolling half
+ * is live only while the node's style says `overflow: 'scroll'` — before
+ * that `scrollTo` has nowhere to go and the offsets stay 0.
+ */
+export interface ScrollableNode extends DrawnNode {
+  readonly scrollX: number;
+  readonly scrollY: number;
+  readonly contentWidth: number;
+  readonly contentHeight: number;
+  /** A number scrolls the vertical axis; an object moves either or both. */
+  scrollTo(to: number | ScrollTarget): void;
+  scrollBy(by: number | ScrollTarget): void;
+  /**
+   * Is there room to move on the axis a delta names? What the wheel's
+   * default action asks before it scrolls this node instead of the next one
+   * out — see [extending.md](../../docs/extending.md).
+   */
+  canScroll(dx: number, dy: number): boolean;
+  /**
+   * Scroll the minimum amount on both axes that makes a descendant fully
+   * visible. Safe to call right after that node mounts — the request is
+   * resolved on the next layout pass, when it has geometry.
+   */
+  scrollIntoView(node: DrawnNode): void;
+}
+
+/** `<textinput>` / `<textarea>`. */
+export interface TextInputNode extends DrawnNode {
+  /**
+   * The control's current text. Inside an `onChange` handler this is the
+   * value the edit produced, even in controlled mode — which is what makes
+   * `ev.target.value` mean what a DOM form library expects it to.
+   *
+   * Writable, as a DOM input's `value` is: assigning sets the text without
+   * firing `onChange`, and on a controlled input the next render puts
+   * `props.value` back. react-hook-form's `register()` resets a field this
+   * way.
+   */
+  value: string;
+  /** The `name` prop, for form libraries that key fields by it. */
+  readonly name?: string;
+  /**
+   * Step back one edit, as Ctrl+Z does. False when there is nothing to
+   * undo. Controlled inputs report the restored value through `onChange`,
+   * so the display follows the same round trip typing does.
+   */
+  undo(): boolean;
+  /** Step forward one undone edit, as Ctrl+Shift+Z does. */
+  redo(): boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+}
+
+/**
+ * ntk's `Window`, as handed back by a `<window>` or `<popup>` ref. This
+ * covers what a react-x11 program usually reaches for; ntk has more (see
+ * its docs/window.md), and the index signature keeps the rest reachable
+ * without pretending this is a full description of the class.
+ */
+export interface NtkWindow {
+  readonly id: number;
+  width: number;
+  height: number;
+  x: number;
+  y: number;
+  map(): void;
+  unmap(): void;
+  raise(): NtkWindow;
+  lower(): NtkWindow;
+  move(x: number, y: number): void;
+  resize(width: number, height: number): void;
+  moveResize(x: number, y: number, width: number, height: number): void;
+  setTitle(title: string): NtkWindow;
+  setCursor(name: string | null): NtkWindow;
+  focus(revertTo?: number): NtkWindow;
+  getContext(name: '2d' | 'opengl' | 'x11', ...args: unknown[]): unknown;
+  requestAnimationFrame(cb: (time: number) => void): number;
+  cancelAnimationFrame(id: number): void;
+  destroy(): void;
+  on(event: string, handler: (...args: any[]) => void): unknown;
+  off?(event: string, handler: (...args: any[]) => void): unknown;
+  [key: string]: any;
+}
+
+/**
+ * An ntk `App` — the X connection. `createRoot()` makes one for you; pass
+ * your own to render into an existing connection.
+ */
+export interface NtkApp {
+  readonly X: any;
+  readonly display: any;
+  createWindow(args?: Record<string, unknown>): NtkWindow;
+  rootWindow(screen?: number): NtkWindow;
+  close(): Promise<void>;
+  [key: string]: any;
+}

package/src/types/screencolor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Sampling a colour from the screen — the eyedropper. See docs/eyedropper.md.
+ */
+
+import type { AbortSignalLike, WindowTarget } from './filedialog.js';
+import type { NtkApp } from './nodes.js';
+
+/** Which rung of the ladder answered — or would. */
+export type ScreenColorBackend = 'portal' | 'x11';
+
+export interface PickScreenColorOptions {
+  /**
+   * The window the picker belongs to — `parent_window` for the portal, and
+   * (when it points at a mounted node) the connection the X11 rung grabs on.
+   * `useEyedropper()` infers it from the tree.
+   */
+  parentWindow?: WindowTarget;
+  /** Abort the pick. Closes the portal request, or releases the X11 grab —
+   * the grab is released **before** the rejection is reported. */
+  signal?: AbortSignalLike;
+  /** Force a rung, for kiosks and for tests. */
+  backend?: ScreenColorBackend;
+  /**
+   * The connection the X11 rung grabs and reads on. Required for that rung
+   * when `parentWindow` does not resolve to a mounted node — the hook passes
+   * the tree's own.
+   */
+  app?: NtkApp;
+}
+
+/**
+ * Nothing here can sample the screen, and nothing can be drawn instead. A
+ * **typed** rejection — the `NoFileDialogError` rule — so a caller hides its
+ * eyedropper button rather than crashing; `useEyedropper().supported` is
+ * that branch made render state.
+ */
+export declare class NoScreenColorError extends Error {
+  readonly name: 'NoScreenColorError';
+  readonly cause?: unknown;
+}
+
+/**
+ * Sample one pixel from the screen: the desktop's own picker
+ * (`org.freedesktop.portal.Screenshot.PickColor`, Screenshot interface
+ * version 2) where there is one, a crosshair pointer grab on plain X11
+ * everywhere else.
+ *
+ * Resolves to `'#rrggbb'`, or `null` when the user cancelled — Escape on the
+ * X11 rung, the dialog's own cancel on the portal. Rejects with
+ * {@link NoScreenColorError} when neither rung is reachable.
+ */
+export declare function pickScreenColor(
+  options?: PickScreenColorOptions,
+): Promise<string | null>;
+
+/**
+ * Which rung this machine lands on, without grabbing anything. `'x11'` needs
+ * a connection to answer with — pass `app`, or a `parentWindow` pointing at
+ * a mounted node — and `null` means {@link pickScreenColor} would reject.
+ */
+export declare function screenColorBackend(
+  options?: Pick<PickScreenColorOptions, 'app' | 'backend' | 'parentWindow'>,
+): Promise<ScreenColorBackend | null>;
+
+export interface Eyedropper {
+  /**
+   * Start a pick. `'#rrggbb'`, or `null` when cancelled. While one is in
+   * flight, another call returns the **same promise** rather than queueing a
+   * second grab.
+   */
+  pick(options?: Omit<PickScreenColorOptions, 'app'>): Promise<string | null>;
+  /** `screenColorBackend()` resolved, for hiding or disabling the button. */
+  supported: boolean;
+  /** A pick is in flight — the button's pressed state. */
+  picking: boolean;
+}
+
+/**
+ * The eyedropper for a component: the tree's connection and owner window
+ * bound once, `picking` and `supported` as render state.
+ */
+export declare function useEyedropper(
+  defaults?: Omit<PickScreenColorOptions, 'app'>,
+): Eyedropper;