react-x11 2.11.0 → 2.13.0

package/src/host.d.ts

@@ -21,7 +21,6 @@ import type { NtkApp } from './types/nodes.js';
 export interface HostContext {
   isInsideText: boolean;
   isInsideSvg: boolean;
-  isInside3d: boolean;
 }
 
 export interface ElementDefinition {
@@ -86,3 +85,233 @@ export function knownElements(): string[];
 
 /** Kinds that lay out with yoga and paint into the owning window (a copy). */
 export function drawnKinds(): string[];
+
+// --- layouts and positions (docs/extending.md) ------------------------------
+
+/**
+ * What an option of a layout or a position may be. A `'length'` is written
+ * in logical pixels, like every length in a style, and handed to the
+ * algorithm in device pixels. An array is the values the option may take.
+ */
+export type OptionType =
+  | 'length'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'string'
+  | 'any'
+  | readonly (string | number | boolean)[];
+
+export interface OptionSpec {
+  type: OptionType;
+  default?: unknown;
+}
+
+/** The options a layout or a position takes, by name. */
+export type OptionSchema = Record<string, OptionSpec>;
+
+export type MeasureMode = 'exactly' | 'at-most' | 'unconstrained';
+
+/** The room on offer, in the vocabulary `measureContent` speaks: device
+ *  pixels, and `Infinity` on an axis with no bound. */
+export interface LayoutConstraints {
+  width: number;
+  height: number;
+  widthMode: MeasureMode;
+  heightMode: MeasureMode;
+}
+
+/**
+ * A child, as a layout algorithm sees it: something to measure and read
+ * options off, never a node. Every size is the child's **margin box**, in
+ * device pixels.
+ */
+export interface LayoutChild {
+  /** Where it is in the list the algorithm was handed. */
+  readonly index: number;
+  /** Its `layoutItem`, against the layout's `childOptions`: defaults filled
+   *  in, lengths in device pixels. */
+  readonly options: Readonly<Record<string, any>>;
+  /**
+   * The size it takes under `constraints`. An axis given a number and no
+   * mode is `'exactly'` that; an axis left out is `'unconstrained'`;
+   * `'at-most'` is CSS's fit-content, never below its content floor.
+   */
+  measure(constraints?: Partial<LayoutConstraints>): {
+    width: number;
+    height: number;
+  };
+  /** The narrowest it can be drawn at — its content floor — and the width
+   *  it would take with no bound at all. */
+  intrinsicSizes(): { minContentWidth: number; maxContentWidth: number };
+  /** Its own resolved style, in device pixels — what a grid places it by
+   *  (`gridColumn`, `gridArea`) and aligns it with (`alignSelf`,
+   *  `justifySelf`). */
+  readonly style: Readonly<import('./types/style.js').StyleProperties>;
+}
+
+/** Where one child goes, from the content box's corner. A `width` or
+ *  `height` left out is the child's own. */
+export interface LayoutRect {
+  x: number;
+  y: number;
+  width?: number;
+  height?: number;
+}
+
+export interface LayoutResult {
+  /** The content box's size, device pixels. */
+  width: number;
+  height: number;
+  /** One rect per child — required of the call that places, the one with
+   *  both modes `'exactly'`. */
+  children?: readonly LayoutRect[];
+}
+
+export interface LayoutInfo {
+  /** The box's own resolved style — `gap`, `justifyContent`, `alignItems`
+   *  — in device pixels. */
+  style: Readonly<import('./types/style.js').StyleProperties>;
+  scale: number;
+  /**
+   * Say that something in the style is wrong but can be laid out around —
+   * a grid area nobody named — the way a bad style value is said: once,
+   * on the console and to the test harness. `consequence` is what happens
+   * instead. A throw is for what cannot be laid out at all.
+   */
+  report(message: string, consequence: string): void;
+}
+
+export interface LayoutDefinition {
+  options?: OptionSchema;
+  /** What a child's `layoutItem` may say to this layout. */
+  childOptions?: OptionSchema;
+  /**
+   * How big the box's content is for `constraints` — asked several times
+   * per pass, so a pure function of its arguments — and, when both modes
+   * are `'exactly'`, where each child goes.
+   */
+  layout(
+    children: readonly LayoutChild[],
+    constraints: LayoutConstraints,
+    options: Readonly<Record<string, any>>,
+    info: LayoutInfo,
+  ): LayoutResult;
+  /** Replace an existing registration. Off by default. */
+  override?: boolean;
+}
+
+/** Teach react-x11 a layout algorithm, for `style={{ layout: name }}`
+ *  (docs/extending.md, "A layout algorithm of your own"). */
+export function registerLayout(
+  name: string,
+  definition: LayoutDefinition,
+): void;
+
+/** Undo a registration; true if there was one. The built-in layouts stay. */
+export function unregisterLayout(name: string): boolean;
+
+/** Registered layout names, the built-in ones first. */
+export function registeredLayouts(): string[];
+
+export interface Edges {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+/** What a position's `place` is handed: window coordinates, device
+ *  pixels, the space `abs` is in. */
+export interface PositionContext {
+  /** Where layout put the node, before any placement moved it. */
+  laidOut: { x: number; y: number; width: number; height: number };
+  /** The nearest scroll pane above the node — its scrollport is inside its
+   *  border and over its padding — or null when nothing above scrolls. */
+  pane: { scrollport: Edges; scrollX: number; scrollY: number } | null;
+  /** The box it is contained by: its parent's content box, or the whole
+   *  scrolled content for a direct child of the pane. */
+  container: Edges;
+  margin: Edges;
+  direction: 'ltr' | 'rtl';
+  scale: number;
+  /** The frame clock, in ms. */
+  now: number;
+  options: Readonly<Record<string, any>>;
+}
+
+export interface PositionDefinition {
+  options?: OptionSchema;
+  /**
+   * How far to move the node from where layout put it, or null for not at
+   * all. `again: true` asks for another frame, for a position that
+   * animates. Runs after every layout pass; resizes nothing.
+   */
+  place(
+    node: Node,
+    context: PositionContext,
+  ): { x: number; y: number; again?: boolean } | null;
+  /** Replace an existing registration. Off by default. */
+  override?: boolean;
+}
+
+/** Teach react-x11 a positioning scheme, for `style={{ position: name }}`
+ *  (docs/extending.md, "A position of your own"). CSS's own names —
+ *  `static`, `relative`, `absolute`, `fixed`, `sticky` — are not available. */
+export function registerPosition(
+  name: string,
+  definition: PositionDefinition,
+): void;
+
+/** Undo a registration; true if there was one. */
+export function unregisterPosition(name: string): boolean;
+
+/** Registered position names, in registration order. */
+export function registeredPositions(): string[];
+
+/**
+ * The layouts a style can name, each with the options it takes. Augment it
+ * to add yours:
+ *
+ * ```ts
+ * declare module 'react-x11/host' {
+ *   interface CustomLayouts {
+ *     radial: { radius?: number };
+ *   }
+ * }
+ * ```
+ */
+export interface CustomLayouts {
+  masonry: { columns?: number; columnWidth?: number };
+  'equal-row': Record<never, never>;
+  /** CSS grid — `layout: 'grid'` is `display: 'grid'`. It takes no options:
+   *  its tracks are the box's own style, `gridTemplateColumns` and the rest. */
+  grid: Record<never, never>;
+}
+
+/** What a child's `layoutItem` may tell the layout arranging it — augmented
+ *  the same way. */
+export interface CustomLayoutItem {
+  /** `masonry`: how many columns the child is laid across. */
+  span?: number;
+}
+
+/** The registered positions a style can name, each with its options —
+ *  augmented the same way as `CustomLayouts`. */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface CustomPositions {}
+
+/** A layout, by name or written with its options. */
+export type LayoutValue = {
+  [K in keyof CustomLayouts]: K | ({ name: K } & CustomLayouts[K]);
+}[keyof CustomLayouts];
+
+/** CSS's positions, and the registered ones by name or with their options. */
+export type PositionValue =
+  | 'static'
+  | 'relative'
+  | 'absolute'
+  | 'sticky'
+  | {
+      [K in keyof CustomPositions]: K | ({ name: K } & CustomPositions[K]);
+    }[keyof CustomPositions];

package/src/host.js

@@ -1,13 +1,21 @@
 // `react-x11/host` — the seam a package that is not react-x11 uses to add
-// a host element. See docs/extending.md for the node contract; this file is
-// only the entry point.
+// a host element, a layout algorithm or a positioning scheme. See
+// docs/extending.md for the contracts; this file is only the entry point.
 export {
   registerElement,
   unregisterElement,
   registeredElements,
 } from './registry.js';
+export {
+  registerLayout,
+  unregisterLayout,
+  registeredLayouts,
+  registerPosition,
+  unregisterPosition,
+  registeredPositions,
+} from './layouts.js';
 
-import { DRAWN_KINDS as DRAWN } from './nodes.js';
+import { DRAWN_KINDS as DRAWN } from './nodes/kinds.js';
 import { registeredElements } from './registry.js';
 
 const BUILT_IN = Object.freeze([

package/src/imagesource.js

@@ -4,7 +4,7 @@
 //
 // The split follows `decorations.js`: classification, validation, decoding
 // and the `cacheKey` cache live here, where a test needs no server; the node
-// half in nodes.js is only lifecycle — when to resolve, when to claim
+// half in nodes/image.js is only lifecycle — when to resolve, when to claim
 // damage, when to let go.
 import { Image, Picture, decodeImage } from 'ntk';
 

package/src/index.d.ts

@@ -76,7 +76,10 @@ export type TransferType = 'text' | 'files' | 'uris' | (string & {});
 
 export interface ClipboardOptions {
   /** Selection atom name; `'CLIPBOARD'` by default, `'PRIMARY'` for the
-   * middle-click buffer. Any name works. */
+   * middle-click buffer. Any name works on X11. On the Cocoa backend only
+   * `'CLIPBOARD'` is the pasteboard: every other name is a selection nobody
+   * can paste from — writes resolve and change nothing, reads find it
+   * empty. */
   selection?: string;
   /** ms to wait for the owner at each protocol step. */
   timeout?: number;
@@ -154,8 +157,27 @@ export function useClipboard(): Clipboard;
  * policy it is false whatever the machine could do, because the indirect
  * backend is what draws. `app.glCapabilities()` is the machine's answer, and
  * says why.
+ *
+ * `'nativeControls'` is whether this backend renders the platform's own
+ * control bezels — the Cocoa backend, never X11. The widget set already
+ * branches on it through the theme's `controls: 'auto'` policy; this is for
+ * application code composing its own controls to sit beside native ones. It
+ * is a property of the backend and never changes over the app's life.
+ *
+ * `'embedding'` is whether this connection can take another process's window
+ * into its own — X11, never Cocoa or the headless mock. Ask it before
+ * rendering a `<foreign>`, which refuses with one `onError` where it is
+ * false. Also a property of the backend, and it never changes either.
+ *
+ * `'glOverlay'` is whether the children of a `<glarea>` are drawn above its
+ * GL surface — laid out in its box, painted on panes stacked over it, hit
+ * before it. Both backends draw them; translucency is the difference,
+ * composited by Core Animation on Cocoa and opaque on X11, where what a
+ * child leaves unpainted shows the surface's `clearColor` (docs/elements.md).
+ * Ask it before handing a surface its HUD. A property of the backend.
  */
-export type SupportsFeature = 'transparency' | 'shaders';
+export type SupportsFeature =
+  'transparency' | 'shaders' | 'nativeControls' | 'embedding' | 'glOverlay';
 
 /**
  * Can this **display** do something? `'transparency'` is true when the
@@ -206,11 +228,18 @@ export interface RootOptions {
    * as the bridge reports it, 16 where the OS cannot say. A number here
    * applies to every window instead. `pumpInterval` is the AppKit event
    * pump's cadence, in ms (8 by default), which is the floor under input
-   * latency. `appName` is what the Dock, ⌘-Tab and the app menu print for
+   * latency; an app started under `react-x11/cocoa-main` has no pump.
+   * `resizeWait` is how long, in ms, AppKit may hold a live-resize tick for
+   * the app's frame at the new size under `react-x11/cocoa-main`, where
+   * the frame is painted on another thread (50 by default; 0 lets the edge
+   * move without waiting). `appName` is what the Dock, ⌘-Tab and the app menu print for
    * an unbundled process (a bundle's Info.plist wins); `activationPolicy`
    * is `'regular'` (a Dock tile, a ⌘-Tab entry — the default),
    * `'accessory'` (a menu-bar app: windows but no tile) or `'prohibited'`,
-   * fixed before the app finishes launching. `exitOnQuit` (default `true`)
+   * fixed before the app finishes launching — under `react-x11/cocoa-main`
+   * the app launches before its code runs, so there the launch policy is
+   * `APPKIT_ACTIVATION_POLICY`'s, and this one a switch once the code
+   * runs. `exitOnQuit` (default `true`)
    * ends the process once a quit request — the Dock's Quit, ⌘Q, a logout —
    * has closed the app: the request routes through the primary window's
    * close request first, so `onCloseRequest` there is where an app
@@ -222,6 +251,7 @@ export interface RootOptions {
     promote?: boolean;
     frameInterval?: number;
     pumpInterval?: number;
+    resizeWait?: number;
     appName?: string;
     activationPolicy?: 'regular' | 'accessory' | 'prohibited';
     exitOnQuit?: boolean;

package/src/index.js

@@ -1,3 +1,7 @@
+// First, before anything else in the package: on macOS it moves the app
+// onto a worker before the app's own code runs (src/bootstrap.js).
+import './bootstrap.js';
+
 export { createRoot, Renderer } from './Reconciler.js';
 export { createStyles, flattenStyle } from './styles.js';
 export { windowIdOf, useWindowId, useTopLevelWindow } from './windowid.js';
@@ -42,7 +46,11 @@ export { BusUnavailableError, closeBus, sessionBus, systemBus } from './bus.js';
 export { announce } from './a11y.js';
 // the standard Undo/Cut/Copy/Paste menu, for an element that edits or
 // selects text of its own — `<textinput>`'s own menu is a caller of it
-export { closeEditMenu, editMenuOpen, openEditMenu } from './nodes.js';
+export {
+  closeEditMenu,
+  editMenuOpen,
+  openEditMenu,
+} from './nodes/editmenupopup.js';
 export { useSessionBus, useSystemBus } from './bushooks.js';
 export { REGISTRAR_NAME, useGlobalMenu } from './globalmenu.js';
 export {