@react-x11/components 0.8.0 → 0.10.0

package/src/flow/types.ts

@@ -509,6 +509,12 @@ export interface NodeBodyRect extends FlowRect {
    * units. */
   zoom: number;
   selected: boolean;
+  /** The whole card the body sits in, in the same frame as the body's rect:
+   *  `<Flow>` paints it (`paintCard`) under the body, so card and body are
+   *  stacked together. */
+  card: FlowRect;
+  /** The pointer is over the node — its card paints its hover border. */
+  hovered: boolean;
 }
 
 // --- the imperative surface ------------------------------------------------
@@ -649,11 +655,117 @@ export interface FlowProps<N = FlowNodeData, E = unknown> {
    * between the drawn half and the mounted one, and the raw `<flowgraph>`
    * element is the only reason it is a prop rather than a private method.
    *
+   * Each rect is relative to `origin`: where the graph's own origin sits in
+   * the pane, which is the viewport's translation. A pan moves the origin
+   * and nothing else, and re-sends the same `bodies` array — so the bodies
+   * can be laid out in one box at `origin` that a pan moves, rather than
+   * each moved by a render of its own.
+   *
    * `sync` is true when the change came out of a live gesture — a drag
    * step, a wheel tick, an arrow key. Motion dispatches at continuous
    * priority, which React may hold across several frames while the pane
    * paints each step immediately; a gesture-time receiver must commit
    * synchronously or the mounted bodies visibly trail the drawn cards.
+   *
+   * `held` is true while a zoom is moving: the bodies are to stay mounted
+   * and be hidden, and `bodies`/`origin` are the last ones sent, unchanged.
+   * The next call, once the zoom has rested, has `held` false and the
+   * bodies at the new scale.
+   */
+  /**
+   * Where the minimap and the controls are, relative to the pane's top-left
+   * — sent when that changes. `<Flow>` paints them on canvases of its own
+   * over the node bodies (`setPanelCanvases`).
+   * @internal
+   */
+  onPanels?: (rects: readonly FlowRect[]) => void;
+  onNodeBodies?: (
+    bodies: readonly NodeBodyRect[],
+    sync: boolean,
+    origin: XYPosition,
+    held: boolean,
+  ) => void;
+  /**
+   * Which renderer draws the graph. `'retained'` (the default) draws through
+   * the 2D context, everywhere a window can. `'gl'` draws through a
+   * `<glarea>`, every frame from the whole scene, and needs direct GL —
+   * `useSupports('shaders')`; where it has none, or its surface fails, the
+   * pane falls back to `'retained'` and says so through `onError`.
+   *
+   * **Not yet a replacement.** The GL renderer draws the graph — cards,
+   * edges, arrowheads, handles, labels, the grid, the minimap — but not yet
+   * a node type's own `paint`, nor a mounted body over the surface. Labels
+   * are drawn from distance fields, sharp at every zoom, and a string drawn
+   * for the first time arrives a frame or two after the frame that asked
+   * for it; `onFrame`'s `gaps` counts what a frame left out.
+   * `docs/prd-flow-gl.md` has the plan and the numbers.
+   */
+  renderer?: 'retained' | 'gl';
+  /**
+   * Every frame the pane drew, on either renderer, with what it cost this
+   * thread — `<Map onFrame>`'s shape, for the same reason: one callback an
+   * application can read an FPS off without caring which renderer drew.
+   *
+   * A frame, not a paint: the 2D renderer may paint several damage rects in
+   * one window flush, and those are reported once, summed. Both renderers
+   * draw on change and not otherwise, so an idle pane reports nothing.
+   */
+  onFrame?: (stats: FlowFrameStats) => void;
+  /**
+   * How mounted node bodies ride a zoom gesture. Re-scaling a body is a
+   * restyle, a layout and a repaint of its whole subtree on every step —
+   * about a millisecond each — so each step predicts what the bodies on
+   * screen would add, and over the budget they sit the gesture out: mounted,
+   * state intact, off screen, back at the new scale once the zoom rests.
+   *
+   * `true` (the default) budgets 8 ms a step; `{ budgetMs }` picks another,
+   * `0` holding them through every gesture zoom; `false` never holds them —
+   * every body zooms live, whatever it costs. A pan or a programmatic
+   * viewport change never holds them.
    */
-  onNodeBodies?: (bodies: readonly NodeBodyRect[], sync: boolean) => void;
+  adaptive?: boolean | { budgetMs?: number };
+  /** The GL renderer could not draw, and the pane went back to the 2D one. */
+  onError?: (error: Error) => void;
+}
+
+/** One frame — see {@link FlowProps.onFrame}. The draw-call and buffer
+ *  counts are the GL renderer's, and always `0` on the retained one. */
+export interface FlowFrameStats {
+  /** Which renderer drew the frame. */
+  renderer: 'retained' | 'gl';
+  /** Milliseconds building the scene: routing, culling, colours. */
+  sceneMs: number;
+  /** Milliseconds packing it into instance streams — `0` on the retained
+   *  renderer, which packs nothing. */
+  packMs: number;
+  /** Milliseconds issuing it: the 2D calls, or the uploads and draws. */
+  drawMs: number;
+  drawCalls: number;
+  lines: number;
+  boxes: number;
+  triangles: number;
+  /** Bytes handed to the GPU this frame. */
+  uploadBytes: number;
+  /** Whether the graph was rebuilt and re-uploaded this frame, rather than
+   *  drawn from the GPU where a pan moved it. False on a pan. */
+  worldRebuilt: boolean;
+  /** What the frame could not draw yet: strings, and nodes whose type
+   *  paints itself. */
+  gaps: { text: number; custom: number };
+  /** The mounted bodies' budget (`adaptive`) as the frame found it. */
+  bodies: FlowBodyBudget;
+}
+
+/** Where mounted node bodies stand against `adaptive`'s budget. */
+export interface FlowBodyBudget {
+  /** Bodies on screen. */
+  count: number;
+  /** Sitting the current zoom gesture out. */
+  held: boolean;
+  /** What re-scaling one body adds to a zoom step, learned from frames. */
+  perBodyMs: number;
+  /** `count × perBodyMs`: what a zoom step would pay to re-scale them. */
+  predictedMs: number;
+  /** The budget that is held against — `Infinity` when `adaptive` is off. */
+  budgetMs: number;
 }

package/src/html/controls.ts

@@ -23,6 +23,7 @@ import type { Element } from 'domhandler';
 
 import { attr, tagOf } from './dom.js';
 import type { ComputedStyle } from './css/style.js';
+import { isTransparent } from './css/values.js';
 import type { BoxTree, ReplacedKind } from './layout/boxes.js';
 import type { FontsLike } from './layout/inline.js';
 
@@ -46,6 +47,24 @@ export interface ControlRect {
   y: number;
   width: number;
   height: number;
+  /**
+   * Set on a text field whose own box the author styled — gave it a border
+   * or a background (`styledField`). The document draws that box, and the
+   * widget goes bare inside its content box, here, with no frame or fill
+   * of its own and its text in the element's colour and font.
+   */
+  bare?: BareField;
+}
+
+/** Where a styled text field's widget goes, and how its text looks. */
+export interface BareField {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  color: string;
+  fontFamily: string;
+  fontSize: number;
 }
 
 /** The rectangles every control in a laid-out document landed on. */
@@ -54,18 +73,59 @@ export function controlRectsOf(tree: BoxTree): ControlRect[] {
   for (const box of tree.controls) {
     if (!box.el) continue;
     if (box.width <= 0 || box.height <= 0) continue;
-    out.push({
+    const rect: ControlRect = {
       element: box.el,
       kind: box.replaced,
       x: box.x,
       y: box.y,
       width: box.width,
       height: box.height,
-    });
+    };
+    if (styledField(box.replaced, box.style)) {
+      rect.bare = {
+        x: box.contentX,
+        y: box.contentY,
+        width: box.contentWidth,
+        height: box.contentHeight,
+        color: box.style.color,
+        fontFamily: box.style.fontFamily,
+        fontSize: box.style.fontSize,
+      };
+    }
+    out.push(rect);
   }
   return out;
 }
 
+/**
+ * Whether a text field's box is the author's to draw: one given a border or
+ * a background of its own, which the UA sheet gives no control, or set to
+ * `appearance: none`, which says so outright. A browser drops a field's
+ * native look for the author's then (CSS UI 4 7.1, `appearance`), and so
+ * does this: the widget's frame and fill would hide the author's, and what
+ * they would draw is the theme's rather than the page's. `appearance: none`
+ * is how a design system writes every field it has — meetup.com's search
+ * pill holds two with no background, only one of them with a border.
+ */
+export function styledField(kind: ReplacedKind, style: ComputedStyle): boolean {
+  if (kind !== 'input' && kind !== 'textarea') return false;
+  return (
+    style.appearance === 'none' ||
+    !isTransparent(style.backgroundColor) ||
+    !!style.backgroundImage ||
+    !!style.backgroundGradient ||
+    !!style.backgroundImages ||
+    edged(style.borderTopStyle, style.borderTopWidth) ||
+    edged(style.borderRightStyle, style.borderRightWidth) ||
+    edged(style.borderBottomStyle, style.borderBottomWidth) ||
+    edged(style.borderLeftStyle, style.borderLeftWidth)
+  );
+}
+
+function edged(style: ComputedStyle['borderTopStyle'], width: number): boolean {
+  return style !== 'none' && style !== 'hidden' && width > 0;
+}
+
 /**
  * The size a control's box takes in the flow.
  *
@@ -119,9 +179,17 @@ export function measureControl(
         height: lineHeight + chrome,
       };
     }
+    // a field the author drew the box of is its text and no more, as a
+    // browser's is: the room around it is the author's border and padding
     case 'textarea': {
       const cols = numberAttr(el, 'cols') ?? 30;
       const rows = numberAttr(el, 'rows') ?? 3;
+      if (styledField(kind, style)) {
+        return {
+          width: Math.round(ch * cols),
+          height: Math.round(lineHeight * rows),
+        };
+      }
       return {
         width: Math.round(ch * cols + padding * 2 + chrome),
         height: Math.round(lineHeight * rows + chrome),
@@ -129,6 +197,9 @@ export function measureControl(
     }
     case 'input': {
       const size = numberAttr(el, 'size') ?? 20;
+      if (styledField(kind, style)) {
+        return { width: Math.round(ch * size), height: lineHeight };
+      }
       return {
         width: Math.round(ch * size + padding * 2 + chrome),
         height: lineHeight + chrome,

package/src/html/css/calc.ts

@@ -0,0 +1,385 @@
+// `calc()`, `min()`, `max()` and `clamp()` (CSS Values 4 10), read down to
+// what a length here can hold: device pixels, or a percentage of what
+// layout knows with pixels added (`Pct.px`) — every `calc()` that adds and
+// scales, which is what documents write: `calc(100% - 2em)`. A comparison
+// with a percentage in it, `min(100%, 600px)`, is a different sum at every
+// width, and is kept as one (`Pct.of`) for layout to resolve; sums and
+// scales distribute into it, so `calc(min(100%, 600px) - 2rem)` is
+// `min(100% - 2rem, 600px - 2rem)`.
+
+import type { Len } from './values.js';
+
+/** A sum: a number, or a length as pixels plus a percentage. */
+interface Linear {
+  kind: 'linear';
+  length: boolean;
+  px: number;
+  pct: number;
+  /** A percentage was written, even where the sum cancels it: against a
+   *  height nothing sets, `calc(40px + 10% - 20% / 2)` is still `auto`. */
+  hasPct: boolean;
+}
+
+/** `min()` or `max()` of lengths, a percentage among them. */
+interface Compare {
+  kind: 'compare';
+  max: boolean;
+  args: Term[];
+}
+
+type Term = Linear | Compare;
+
+type Token =
+  | { t: 'num'; value: number; unit: string }
+  | { t: 'op'; value: '+' | '-' | '*' | '/' }
+  | { t: 'open'; fn: string }
+  | { t: 'close' }
+  | { t: 'comma' }
+  | { t: 'space' };
+
+/**
+ * A math function's value as a length, or null where it is none — a
+ * number, a type that does not add up, a division by zero. `dimension`
+ * reads one `10px` or `2em` as this package's lengths do.
+ */
+export function parseMath(
+  value: string,
+  dimension: (token: string) => number | null,
+): Len | null {
+  const term = parseTerm(value, dimension);
+  if (!term || !isLength(term)) return null;
+  return toLen(term);
+}
+
+/** A math function's value as a number (`calc(1 + 0.5)`), or null. */
+export function parseMathNumber(value: string): number | null {
+  const term = parseTerm(value, () => null);
+  if (!term || term.kind !== 'linear' || term.length) return null;
+  return censor(term.px);
+}
+
+function parseTerm(
+  value: string,
+  dimension: (token: string) => number | null,
+): Term | null {
+  const tokens = tokenize(value);
+  if (!tokens) return null;
+  const parser = new Parser(tokens, dimension);
+  const term = parser.value();
+  return term && parser.pos === tokens.length ? term : null;
+}
+
+function isLength(term: Term): boolean {
+  return term.kind === 'linear' ? term.length : true;
+}
+
+function toLen(term: Term): Len | null {
+  if (term.kind === 'compare') {
+    const args: Len[] = [];
+    for (const arg of term.args) {
+      const len = toLen(arg);
+      if (len === null) return null;
+      args.push(len);
+    }
+    return { pct: 0, of: { max: term.max, args } };
+  }
+  if (!term.hasPct) return censor(term.px);
+  return { pct: censor(term.pct), px: censor(term.px) };
+}
+
+const NUMBER = /^[+-]?(?:\d*\.\d+|\d+)(?:e[+-]?\d+)?/;
+
+const CONSTANT = /^(?:-?infinity|nan|pi|e)(?![a-z0-9_(-])/;
+
+const CONSTANTS: Record<string, number> = {
+  infinity: Infinity,
+  '-infinity': -Infinity,
+  nan: NaN,
+  pi: Math.PI,
+  e: Math.E,
+};
+
+/**
+ * What a calculation that is no finite number comes to (CSS Values 4,
+ * 10.9): NaN is 0, and an infinity the largest length there is — which,
+ * as in a browser, is still a length: a radius of it is a pill.
+ */
+function censor(n: number): number {
+  if (Number.isNaN(n)) return 0;
+  if (n === Infinity) return LARGEST;
+  if (n === -Infinity) return -LARGEST;
+  return n;
+}
+
+/** The largest length a browser holds, 2^25 pixels less a little: what a
+ *  calculation's infinity comes to, and what any length is kept within
+ *  (`parseLength`, `resolve`). */
+export const LARGEST = 33554428;
+
+function tokenize(text: string): Token[] | null {
+  const out: Token[] = [];
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f') {
+      while (i < text.length && /[ \t\n\r\f]/.test(text[i])) i += 1;
+      if (out.length && out[out.length - 1].t !== 'space') {
+        out.push({ t: 'space' });
+      }
+      continue;
+    }
+    if (c === '(') {
+      out.push({ t: 'open', fn: '' });
+      i += 1;
+      continue;
+    }
+    if (c === ')' || c === ',') {
+      if (out.length && out[out.length - 1].t === 'space') out.pop();
+      out.push(c === ')' ? { t: 'close' } : { t: 'comma' });
+      i += 1;
+      continue;
+    }
+    if (c === '*' || c === '/') {
+      out.push({ t: 'op', value: c });
+      i += 1;
+      continue;
+    }
+    // a sign belongs to the number after it, as the tokenizer reads it:
+    // `1px -2px` is two values, and `1px - 2px` a difference
+    const m = NUMBER.exec(text.slice(i));
+    if (m) {
+      i += m[0].length;
+      const unit = /^(?:%|[a-z]+)/.exec(text.slice(i))?.[0] ?? '';
+      i += unit.length;
+      out.push({ t: 'num', value: Number(m[0]), unit });
+      continue;
+    }
+    const name = /^-?[a-z][a-z0-9-]*\(/.exec(text.slice(i))?.[0];
+    if (name) {
+      out.push({ t: 'open', fn: name.slice(0, -1) });
+      i += name.length;
+      continue;
+    }
+    // the numbers CSS Values 4 names (10.7.1): Tailwind 4 writes a pill's
+    // radius as `calc(infinity * 1px)`
+    const constant = CONSTANT.exec(text.slice(i))?.[0];
+    if (constant) {
+      out.push({ t: 'num', value: CONSTANTS[constant], unit: '' });
+      i += constant.length;
+      continue;
+    }
+    if (c === '+' || c === '-') {
+      out.push({ t: 'op', value: c });
+      i += 1;
+      continue;
+    }
+    return null;
+  }
+  return out;
+}
+
+class Parser {
+  pos = 0;
+  constructor(
+    private tokens: Token[],
+    private dimension: (token: string) => number | null,
+  ) {}
+
+  private peek(): Token | undefined {
+    return this.tokens[this.pos];
+  }
+
+  private skipSpace(): void {
+    if (this.peek()?.t === 'space') this.pos += 1;
+  }
+
+  /** A whole math function, `calc(…)` and the rest. */
+  value(): Term | null {
+    this.skipSpace();
+    const open = this.peek();
+    if (open?.t !== 'open' || !open.fn) return null;
+    const term = this.fn();
+    this.skipSpace();
+    return term;
+  }
+
+  private fn(): Term | null {
+    const open = this.tokens[this.pos] as { t: 'open'; fn: string };
+    this.pos += 1;
+    const fn = open.fn.replace(/^-webkit-/, '');
+    const args: Term[] = [];
+    for (;;) {
+      const sum = this.sum();
+      if (!sum) return null;
+      args.push(sum);
+      const next = this.peek();
+      if (next?.t === 'comma') {
+        this.pos += 1;
+        continue;
+      }
+      if (next?.t !== 'close') return null;
+      this.pos += 1;
+      break;
+    }
+    switch (fn) {
+      case '':
+      case 'calc':
+        return args.length === 1 ? args[0] : null;
+      case 'min':
+      case 'max':
+        return compare(args, fn === 'max');
+      case 'clamp': {
+        if (args.length !== 3) return null;
+        const upper = compare([args[1], args[2]], false);
+        return upper && compare([args[0], upper], true);
+      }
+      default:
+        return null;
+    }
+  }
+
+  private sum(): Term | null {
+    this.skipSpace();
+    let left = this.product();
+    if (!left) return null;
+    for (;;) {
+      const at = this.pos;
+      // `+` and `-` need white space on both sides
+      if (this.peek()?.t !== 'space') break;
+      this.pos += 1;
+      const op = this.peek();
+      if (op?.t !== 'op' || (op.value !== '+' && op.value !== '-')) {
+        this.pos = at;
+        break;
+      }
+      this.pos += 1;
+      if (this.peek()?.t !== 'space') return null;
+      this.pos += 1;
+      const right = this.product();
+      if (!right) return null;
+      left = add(left, right, op.value === '+' ? 1 : -1);
+      if (!left) return null;
+    }
+    this.skipSpace();
+    return left;
+  }
+
+  private product(): Term | null {
+    let left = this.unit();
+    if (!left) return null;
+    for (;;) {
+      const at = this.pos;
+      this.skipSpace();
+      const op = this.peek();
+      if (op?.t !== 'op' || (op.value !== '*' && op.value !== '/')) {
+        this.pos = at;
+        return left;
+      }
+      this.pos += 1;
+      this.skipSpace();
+      const right = this.unit();
+      if (!right) return null;
+      if (op.value === '*') {
+        // one side a number, which scales the other
+        if (isNumber(left)) left = scale(right, left.px);
+        else if (isNumber(right)) left = scale(left, right.px);
+        else return null;
+      } else {
+        if (!isNumber(right) || right.px === 0) return null;
+        left = scale(left, 1 / right.px);
+      }
+    }
+  }
+
+  private unit(): Term | null {
+    const token = this.peek();
+    if (!token) return null;
+    if (token.t === 'open') return this.fn();
+    if (token.t !== 'num') return null;
+    this.pos += 1;
+    if (token.unit === '') return linear(false, token.value, 0, false);
+    if (token.unit === '%') return linear(true, 0, token.value, true);
+    const px = this.dimension(`${token.value}${token.unit}`);
+    return px === null ? null : linear(true, px, 0, false);
+  }
+}
+
+function linear(
+  length: boolean,
+  px: number,
+  pct: number,
+  hasPct: boolean,
+): Linear {
+  return { kind: 'linear', length, px, pct, hasPct };
+}
+
+function isNumber(term: Term): term is Linear {
+  return term.kind === 'linear' && !term.length;
+}
+
+/** `a + b`, or `a - b` for a sign of -1, distributed into a comparison. */
+function add(a: Term, b: Term, sign: 1 | -1): Term | null {
+  if (isLength(a) !== isLength(b)) return null;
+  if (a.kind === 'compare') {
+    const args: Term[] = [];
+    for (const arg of a.args) {
+      const sum = add(arg, b, sign);
+      if (!sum) return null;
+      args.push(sum);
+    }
+    return { kind: 'compare', max: a.max, args };
+  }
+  if (b.kind === 'compare') {
+    // `a - min(x, y)` is `max(a - x, a - y)`
+    const args: Term[] = [];
+    for (const arg of b.args) {
+      const sum = add(a, arg, sign);
+      if (!sum) return null;
+      args.push(sum);
+    }
+    return { kind: 'compare', max: sign === 1 ? b.max : !b.max, args };
+  }
+  return linear(
+    a.length,
+    a.px + sign * b.px,
+    a.pct + sign * b.pct,
+    a.hasPct || b.hasPct,
+  );
+}
+
+/** `term * k`, distributed into a comparison, which a negative `k` turns
+ *  over. */
+function scale(term: Term, k: number): Term {
+  if (term.kind === 'compare') {
+    return {
+      kind: 'compare',
+      max: k < 0 ? !term.max : term.max,
+      args: term.args.map((arg) => scale(arg, k)),
+    };
+  }
+  // nought stays nought, so that an infinity scaling a length is not also
+  // a NaN of the percentage it has none of
+  return linear(
+    term.length,
+    term.px === 0 ? 0 : term.px * k,
+    term.pct === 0 ? 0 : term.pct * k,
+    term.hasPct,
+  );
+}
+
+/** `min()` or `max()` of terms of one type: a number where no percentage
+ *  is among them, and a comparison for layout where one is. */
+function compare(args: Term[], max: boolean): Term | null {
+  const length = isLength(args[0]);
+  if (args.some((a) => isLength(a) !== length)) return null;
+  if (args.every((a) => a.kind === 'linear' && !a.hasPct)) {
+    const values = args.map((a) => (a as Linear).px);
+    return linear(
+      length,
+      max ? Math.max(...values) : Math.min(...values),
+      0,
+      false,
+    );
+  }
+  return { kind: 'compare', max, args };
+}