@react-x11/components 0.4.0 → 0.6.0

package/src/maps/types.ts

@@ -0,0 +1,260 @@
+// The public vocabulary: what `<Map>` takes, what it hands back, and what
+// its events carry.
+//
+// Separate from `index.ts` for the reason `src/flow/types.ts` is: the
+// element, the component and the tests all name these, and a types module
+// with no runtime in it can be imported by any of them without dragging the
+// others in.
+import type { Style } from 'react-x11/style';
+import type { ReactNode, Ref } from 'react';
+
+import type { LngLat, LngLatBounds, MapCamera, TileId } from './proj.js';
+import type { MapSource } from './sources.js';
+import type { MapStyle } from './style.js';
+import type { MapMarker, MapOverlay } from './overlay.js';
+
+export type { LngLat, LngLatBounds, MapCamera };
+export type { MapSource, TileData, TileRequest } from './sources.js';
+export type { MapMarker, MapOverlay, OverlayPalette } from './overlay.js';
+export type {
+  MapStyle,
+  MapStyleLayer,
+  MapFilter,
+  FillLayer,
+  LineLayer,
+  CircleLayer,
+  SymbolLayer,
+  Zoomed,
+} from './style.js';
+
+/** Where a pointer event happened, in every space that could be wanted. */
+export interface MapPointerEvent {
+  /** Geographic. */
+  lngLat: LngLat;
+  /** Pane-local logical pixels. */
+  x: number;
+  y: number;
+  /** The marker under the pointer, when there was one. */
+  marker: MapMarker | null;
+  /** Modifier state, as the synthetic event reported it. */
+  shiftKey: boolean;
+  ctrlKey: boolean;
+  altKey: boolean;
+  metaKey: boolean;
+  /** `1` left, `2` middle, `3` right. */
+  button: number;
+}
+
+/** What one frame cost — for a performance HUD, and what
+ *  `scripts/bench/maps.ts` reads. */
+export interface MapFrameStats {
+  /** Milliseconds spent rasterizing tiles into their surfaces this frame.
+   *  Bounded by `rasterBudgetMs` except for the one run that crossed it. */
+  rasterMs: number;
+  /** …and compositing them, drawing the labels, overlays and markers. */
+  drawMs: number;
+  /** Tiles the cover asked for. */
+  tiles: number;
+  /** …of which were composited from their own finished surface. Under
+   *  `progressive` this also counts the half-drawn ones. */
+  ready: number;
+  /** …and how many were drawn from a coarser ancestor instead, scaled up.
+   *  What covers a hole while zooming *in*. */
+  fromAncestor: number;
+  /** …and how many from their finer descendants, scaled down. What covers
+   *  a hole while zooming *out*, where there is no ancestor to borrow. */
+  fromDescendant: number;
+  /** Tiles still to rasterize — non-zero means the map is still sharpening
+   *  and another frame is already scheduled. */
+  pending: number;
+  /** Labels placed, and labels drawn. */
+  labels: number;
+  /**
+   * Tiles in the cover whose load failed and are waiting on a retry.
+   *
+   * Here because a map whose tiles all fail looks exactly like a map that
+   * is still loading — an empty background and nothing else — and the
+   * difference is not something a user can see.
+   */
+  errors: number;
+  /** Bytes of rendered surfaces the cache is holding. */
+  surfaceBytes: number;
+  /**
+   * What this pass repainted, in device pixels, or `null` for a full one.
+   *
+   * The number to watch when a map looks busy: a frame that is only
+   * continuing a rasterization should claim almost nothing, because the
+   * tile being drawn is a second surface nobody is looking at. A run of
+   * full-pane damage while tiles are still landing means something is
+   * asking for repaints it does not need — which on a backend that paints
+   * many frames a second reads as flashing.
+   */
+  damage: { x: number; y: number; width: number; height: number } | null;
+  /** What the rasterizer did, summed over the tiles drawn this frame. */
+  draw: {
+    features: number;
+    vertices: number;
+    decimated: number;
+    culled: number;
+    batches: number;
+  };
+}
+
+/** Options for framing a box. */
+export interface FitBoundsOptions {
+  /** Logical pixels kept clear on every side. 24 by default. */
+  padding?: number;
+  maxZoom?: number;
+}
+
+/** The imperative surface, through `ref`. */
+export interface MapHandle {
+  getCamera(): MapCamera;
+  setCamera(camera: Partial<MapCamera>): void;
+  panBy(dx: number, dy: number): void;
+  zoomIn(step?: number): void;
+  zoomOut(step?: number): void;
+  zoomTo(zoom: number): void;
+  /** Frame a box. */
+  fitBounds(bounds: LngLatBounds, options?: FitBoundsOptions): void;
+  /** Frame every marker, or the ones named. */
+  fitMarkers(ids?: readonly string[], options?: FitBoundsOptions): void;
+  /** What the pane can see. `west > east` across the antimeridian. */
+  getBounds(): LngLatBounds;
+  /** Geography to pane-local logical pixels, and back. */
+  project(position: LngLat): { x: number; y: number };
+  unproject(x: number, y: number): LngLat;
+  /** The marker at a pane-local point, or null. */
+  markerAt(x: number, y: number): MapMarker | null;
+  /** Throw away every rendered tile — after a style edit an application
+   *  made in place, which the map cannot see. */
+  refresh(): void;
+  /** What the last frame cost. */
+  stats(): MapFrameStats | null;
+}
+
+/** What the `<mapview>` element takes. `<Map>` adds the uncontrolled
+ *  camera and the box around it. */
+export interface MapViewProps {
+  /**
+   * Where tiles come from, drawn in order — a basemap, then an overlay
+   * pyramid over it. Empty draws the style's background and nothing else,
+   * which is what a map with only markers on it wants.
+   */
+  sources?: readonly MapSource[];
+  /** How to draw them. Defaults to {@link shortbreadStyle} in the theme's
+   *  light or dark palette. */
+  mapStyle?: MapStyle;
+  /**
+   * The camera, controlled. Leave it out and the **element** owns it —
+   * which is not just a convenience: an element-owned camera means a pan is
+   * a blit and a claim, with no React render in the loop at all.
+   */
+  camera?: MapCamera;
+  /** Where an element-owned camera starts. Read once, at construction. */
+  defaultCamera?: MapCamera;
+  onCameraChange?: (camera: MapCamera) => void;
+  /** Fired when a gesture ends and the camera has settled — the moment to
+   *  fetch what is now on screen. */
+  onMoveEnd?: (camera: MapCamera) => void;
+  minZoom?: number;
+  maxZoom?: number;
+  markers?: readonly MapMarker[];
+  overlays?: readonly MapOverlay[];
+  onMapClick?: (event: MapPointerEvent) => void;
+  onMarkerClick?: (marker: MapMarker, event: MapPointerEvent) => void;
+  /**
+   * The marker under the pointer, or null when it left every marker.
+   *
+   * `event` is null for the leave that comes from the pointer leaving the
+   * map altogether: there is no position on the map to report, and
+   * inventing one would be worse than saying so.
+   */
+  onMarkerHover?: (
+    marker: MapMarker | null,
+    event: MapPointerEvent | null,
+  ) => void;
+  /** `false` freezes the camera: no drag, no wheel, no keys. The map still
+   *  draws and still reports clicks. */
+  interactive?: boolean;
+  /**
+   * Show a tile as it is drawn rather than when it is finished.
+   *
+   * `false` by default, which is what every other map client does: a tile
+   * appears whole, and until it does the coarser one already in the cache
+   * is scaled up in its place. `true` composites a tile's surface as soon
+   * as it exists — so a dense tile arrives as water, then landuse, then
+   * road casings, then roads, across a dozen frames — which is honest about
+   * what the renderer is doing and does not look like a map.
+   *
+   * The one thing the default costs is a transition that invalidates every
+   * surface at once: a `mapStyle` change, `refresh()`, or a display-scale
+   * change leaves no finished tile *and* no finished ancestor, so the map
+   * drops to its background colour until the new tiles land. `true` shows
+   * it repainting instead.
+   */
+  progressive?: boolean;
+  /**
+   * Milliseconds a frame may spend rasterizing tiles. 8 by default, which
+   * leaves the rest of a 60 Hz frame for everything else; a tile that takes
+   * longer than the budget is finished over the frames after it. `0`
+   * suspends rasterization, which is what a gesture does on its own.
+   */
+  rasterBudgetMs?: number;
+  /**
+   * Device pixels per logical pixel for the tile surfaces, if not the
+   * display's.
+   *
+   * Lowering it to 1 on a retina panel makes rasterization about 1.6×
+   * quicker and the basemap correspondingly softer; labels, markers and
+   * overlays are unaffected, since none of them goes through a tile
+   * surface. Worth having on a slow machine, and worth knowing about before
+   * reaching for it.
+   */
+  rasterScale?: number;
+  /** Bytes of rendered tile surfaces to keep. 128 MB by default. */
+  surfaceBudget?: number;
+  /**
+   * Vertices after which the rasterizer flushes its path. 12,000 by
+   * default.
+   *
+   * A real trade on X11, where a fill becomes one coverage-mask upload and
+   * a bigger path is fewer of them over the same pixels. It used to be a
+   * per-backend trade — `CGContextStrokePath` was quadratic in the number
+   * of subpaths, so the Cocoa backend wanted the opposite value and this
+   * element probed for it — and react-x11 2.6.1 chunks that stroke inside
+   * the backend instead (react-x11#457). Set it only with a profile in
+   * hand.
+   */
+  batchVertices?: number;
+  /** What the licence requires, drawn in the corner. Taken from the
+   *  sources when they carry one; `''` removes it, which is the
+   *  application saying it has put the attribution somewhere else. */
+  attribution?: string;
+  /** Called once per painted frame with what it cost. */
+  onFrame?: (stats: MapFrameStats) => void;
+  /**
+   * Called once per failed tile load, with whatever the source threw.
+   *
+   * Nothing is drawn for a failed tile, so without this a source that is
+   * misconfigured, rate-limited or down is indistinguishable from one that
+   * is slow. The tile is retried on a backoff (0.5 s doubling to 30 s), so
+   * this fires again for each retry rather than once and forever.
+   */
+  onTileError?: (error: unknown, tile: TileId & { sourceId: string }) => void;
+  style?: Style;
+  role?: string;
+  'aria-label'?: string;
+  'data-testname'?: string;
+  ref?: Ref<unknown>;
+}
+
+/** What `<Map>` takes. */
+export interface MapProps extends Omit<MapViewProps, 'ref'> {
+  ref?: Ref<MapHandle>;
+  /** Anything absolutely positioned over the map — a legend, a control
+   *  panel. Laid out as siblings of the drawn pane rather than inside it,
+   *  because a registered element paints its children *before* its own
+   *  drawing and anything inside would be painted over. */
+  children?: ReactNode;
+}

package/src/markdown/ast.ts

@@ -1,9 +1,10 @@
 // The markdown AST `parse.ts` produces and `index.ts` renders. Deliberately
 // small: it is the GFM constructs this component draws, not a general
 // mdast — but it is shaped so that growing it stays additive. In particular
-// `component` is reserved for the MDX direction: a parser extension can emit
-// one without the renderer, the selection model or the caches changing shape
-// (see "MDX" in index.ts).
+// `component` is the MDX direction: `ComponentBlock` is parsed and rendered
+// (docs/prd-mdx.md, M1), and `ComponentInline` is still reserved — see the
+// note on it for why the inline half needs machinery `<richtext>` does not
+// have yet.
 
 /** Inline content, inside a paragraph, heading, list item or table cell. */
 export type InlineNode =
@@ -12,7 +13,19 @@ export type InlineNode =
   | EmphasisInline
   | LinkInline
   | BreakInline
-  | ComponentInline;
+  | ComponentInline
+  | ExpressionInline;
+
+/**
+ * `{count}` in the middle of a sentence: unevaluated source, which the
+ * renderer compiles against its `scope` and turns into text. Only emitted
+ * when `ParseOptions.expressions` says so, so `{braces}` in an ordinary
+ * document remain the characters they have always been.
+ */
+export interface ExpressionInline {
+  type: 'expression';
+  src: string;
+}
 
 /** A run of plain text. Softbreaks arrive collapsed to spaces. */
 export interface TextInline {
@@ -51,14 +64,41 @@ export interface BreakInline {
 }
 
 /**
- * Reserved for MDX: `<Chart data={…} />` would parse to one of these. The
- * current parser never emits it; the renderer maps unknown names to plain
- * text so a future parser upgrade cannot crash an older renderer.
+ * An attribute's value. `literal` is what an attribute string or a `{json}`
+ * attribute resolves to at parse time; `expression` holds unevaluated source
+ * for the rung that compiles it, so that parsing stays pure and one AST can
+ * be rendered against two scopes (docs/prd-mdx.md, M2). The parser emits
+ * only `literal` today.
+ */
+export type AttributeValue =
+  { kind: 'literal'; value: unknown } | { kind: 'expression'; src: string };
+
+/**
+ * A spread (`{...props}`) is an attribute with no name, so it is keyed
+ * `...0`, `...1`, … in the order it appeared. An attribute name cannot start
+ * with `.`, so these cannot collide with one; a renderer walking
+ * `Object.entries` in insertion order applies each spread where it was
+ * written, which is what decides whether it overrides `height` or `height`
+ * overrides it.
+ */
+export const SPREAD_PREFIX = '...';
+
+/**
+ * **Still reserved.** `<Badge/>` in the middle of a sentence parses to one of
+ * these — except that nothing emits them yet, because nothing can render
+ * them: a paragraph is laid out as a single `<richtext>`, and a `TextRun`
+ * has no way to say "reserve this much advance width for an element someone
+ * else paints". Giving it one is the inline half of MDX and is its own piece
+ * of work (baseline alignment, wrapping around the element, and what a
+ * selection dragged across it should copy).
+ *
+ * Kept in the union so the shape stays stable, and so a renderer written
+ * against it today cannot be broken by the parser learning to emit them.
  */
 export interface ComponentInline {
   type: 'component';
   name: string;
-  attributes: Record<string, string>;
+  attributes: Record<string, AttributeValue>;
   children: InlineNode[];
 }
 
@@ -70,7 +110,22 @@ export type BlockNode =
   | QuoteBlock
   | ListBlock
   | TableBlock
-  | RuleBlock;
+  | RuleBlock
+  | ComponentBlock;
+
+/**
+ * A component standing where a paragraph would: `<Chart data={…} />` on its
+ * own line, or `<Callout>` … `</Callout>` around blocks.
+ *
+ * Only emitted when `ParseOptions.isComponent` says the name is one — which
+ * is what keeps every document that renders today rendering the same way.
+ */
+export interface ComponentBlock {
+  type: 'component';
+  name: string;
+  attributes: Record<string, AttributeValue>;
+  children: BlockNode[];
+}
 
 export interface ParagraphBlock {
   type: 'paragraph';
@@ -160,4 +215,25 @@ export interface ParseOptions {
    * underline or a rule) is held back. Pass false for text that is final.
    */
   partial?: boolean;
+  /**
+   * Whether `name` is a component this document may use. Absent — the
+   * default — means no tag is a component and `<Chart/>` stays the literal
+   * text it has always been, so turning MDX on is opt-in and turning it off
+   * is byte-for-byte the old behaviour.
+   *
+   * `<Markdown>` supplies one from its `components` prop. A dotted name
+   * (`Card.Header`) is passed through whole; resolving it is the caller's.
+   */
+  isComponent?: (name: string) => boolean;
+  /**
+   * Whether `{…}` may hold a JavaScript expression — in an attribute, as a
+   * `{...spread}`, or bare in the prose. Off by default, and off is the
+   * whole of rung 1: a `{…}` attribute must be JSON, and a brace in a
+   * paragraph is a brace.
+   *
+   * `<Markdown>` turns this on when it is given a `scope`, which is the prop
+   * that says the application accepts a document running code. Parsing still
+   * evaluates nothing — an expression is kept as source.
+   */
+  expressions?: boolean;
 }

package/src/markdown/expressions.ts

@@ -0,0 +1,223 @@
+// Compiling `{…}` — the rung where a document runs code (docs/prd-mdx.md,
+// M2), and the one place in this component that calls `new Function`.
+//
+// It is a small file on purpose. Everything hard about MDX expressions was
+// decided elsewhere: the parser holds an expression as *source* rather than
+// a value, so a parse is pure and one AST can be rendered against two
+// scopes; and `<Markdown>` only turns any of this on when the application
+// passes a `scope`, which is the prop that means "I accept that this
+// document may compute". What is left here is compiling the source once, and
+// not letting a half-typed expression take down a document that is still
+// being typed.
+//
+// **There is no sandbox.** `new Function` runs in this process with this
+// process's authority. That is why the gate is a prop, and why the docs say
+// in as few words as they can: do not pass `scope` alongside a document you
+// did not write.
+
+import type { BlockNode, Document, InlineNode } from './ast.js';
+
+/** A compiled expression, or null if it would not compile at all. */
+type Compiled = ((...args: unknown[]) => unknown) | null;
+
+/**
+ * Keyed on the scope's shape *and* the source, because a compiled function
+ * closes over its parameter names. Bounded the way `richtext/node.ts` bounds
+ * its layout cache: a streaming document recompiles its tail on every chunk,
+ * and an unbounded map would hold every intermediate spelling of an
+ * expression that was being typed.
+ */
+const CACHE = new Map<string, Compiled>();
+const LIMIT = 256;
+
+let warned = false;
+
+/**
+ * Say so, once, when an expression does not work out. A document that
+ * silently loses a value should not be a mystery — and saying it on every
+ * frame of a streaming render would be worse than saying nothing.
+ *
+ * `process` and `console` come off `globalThis` because `src/` compiles with
+ * `types: []` — a Node global that wandered in would fail the build rather
+ * than become an implicit `@types/node` dependency.
+ */
+function warnFailed(src: string, error: unknown): void {
+  if (warned) return;
+  warned = true;
+  const g = globalThis as {
+    process?: { env?: Record<string, string | undefined> };
+    console?: { warn(message: string, ...rest: unknown[]): void };
+  };
+  if (g.process?.env?.NODE_ENV === 'production') return;
+  g.console?.warn(
+    '@react-x11/components: a markdown expression did not evaluate, so it ' +
+      `rendered as nothing: {${src}}`,
+    error,
+  );
+}
+
+function compile(src: string, keys: readonly string[]): Compiled {
+  const key = `${keys.join(',')} ${src}`;
+  const hit = CACHE.get(key);
+  if (hit !== undefined) return hit;
+  let compiled: Compiled = null;
+  try {
+    // `return (…)` rather than a bare body: an expression is what the braces
+    // promised, and the parentheses keep an object literal an object literal
+    // rather than a block.
+    compiled = new Function(...keys, `"use strict"; return (${src});`) as (
+      ...args: unknown[]
+    ) => unknown;
+  } catch (error) {
+    // A syntax error is the ordinary state of an expression being typed.
+    warnFailed(src, error);
+  }
+  if (CACHE.size >= LIMIT) CACHE.clear();
+  CACHE.set(key, compiled);
+  return compiled;
+}
+
+/**
+ * What a renderer calls: source in, value out, `undefined` if it did not
+ * work. Never throws — a document being edited is full of expressions that
+ * do not work yet.
+ */
+export type Evaluate = (src: string) => unknown;
+
+/**
+ * An evaluator over `scope`. The keys are read once, so a scope mutated in
+ * place after this is called keeps its old shape — the same contract every
+ * other seam here has, and the reason the prop doc asks for a stable object.
+ */
+export function evaluator(scope: Record<string, unknown>): Evaluate {
+  const keys = Object.keys(scope);
+  const values = keys.map((k) => scope[k]);
+  return (src) => {
+    const fn = compile(src, keys);
+    if (!fn) return undefined;
+    try {
+      return fn(...values);
+    } catch (error) {
+      warnFailed(src, error);
+      return undefined;
+    }
+  };
+}
+
+/**
+ * Only the tests need to reach in: a compile cache that survived between
+ * them would make one test's expression another's, and the warn-once flag
+ * would hide the second failure anyone asserted on.
+ */
+export function clearExpressionCache(): void {
+  CACHE.clear();
+  warned = false;
+}
+
+// --- resolving a parsed document ------------------------------------------
+
+/**
+ * A copy of `nodes` with every `expression` replaced by the text it
+ * evaluates to. Primitives stringify; anything else — an object, an array, a
+ * React element — renders as nothing, because a paragraph is text and there
+ * is nowhere in a text run to put an element (see "The inline half" in
+ * docs/prd-mdx.md). `null` and `undefined` are nothing on purpose, so
+ * `{maybe}` reads as absent rather than as the word "undefined".
+ */
+function resolveInline(nodes: InlineNode[], evaluate: Evaluate): InlineNode[] {
+  let changed = false;
+  const out: InlineNode[] = [];
+  for (const node of nodes) {
+    if (node.type === 'expression') {
+      changed = true;
+      const value = evaluate(node.src);
+      const text =
+        value == null ||
+        typeof value === 'object' ||
+        typeof value === 'function'
+          ? ''
+          : String(value);
+      if (text) out.push({ type: 'text', text });
+      continue;
+    }
+    if ('children' in node) {
+      const children = resolveInline(node.children, evaluate);
+      if (children !== node.children) {
+        changed = true;
+        out.push({ ...node, children });
+        continue;
+      }
+    }
+    out.push(node);
+  }
+  return changed ? out : nodes;
+}
+
+function resolveBlocks(blocks: BlockNode[], evaluate: Evaluate): BlockNode[] {
+  let changed = false;
+  const out = blocks.map((block): BlockNode => {
+    switch (block.type) {
+      case 'paragraph':
+      case 'heading': {
+        const children = resolveInline(block.children, evaluate);
+        if (children === block.children) return block;
+        changed = true;
+        return { ...block, children };
+      }
+      case 'quote':
+      case 'component': {
+        const children = resolveBlocks(block.children, evaluate);
+        if (children === block.children) return block;
+        changed = true;
+        return { ...block, children };
+      }
+      case 'list': {
+        let itemsChanged = false;
+        const items = block.items.map((item) => {
+          const children = resolveBlocks(item.children, evaluate);
+          if (children === item.children) return item;
+          itemsChanged = true;
+          return { ...item, children };
+        });
+        if (!itemsChanged) return block;
+        changed = true;
+        return { ...block, items };
+      }
+      case 'table': {
+        let rowsChanged = false;
+        const rows = block.rows.map((row) =>
+          row.map((cell) => {
+            const next = resolveInline(cell, evaluate);
+            if (next !== cell) rowsChanged = true;
+            return next;
+          }),
+        );
+        const header = block.header.map((cell) => {
+          const next = resolveInline(cell, evaluate);
+          if (next !== cell) rowsChanged = true;
+          return next;
+        });
+        if (!rowsChanged) return block;
+        changed = true;
+        return { ...block, header, rows };
+      }
+      default:
+        return block;
+    }
+  });
+  return changed ? out : blocks;
+}
+
+/**
+ * The document with its expressions evaluated. `raws` is carried over
+ * untouched: it is the block cache's key, and what changed is the values an
+ * expression produced, not the text that produced them — a change of `scope`
+ * invalidates that cache through its own identity instead.
+ */
+export function resolveExpressions(
+  doc: Document,
+  evaluate: Evaluate,
+): Document {
+  const blocks = resolveBlocks(doc.blocks, evaluate);
+  return blocks === doc.blocks ? doc : { blocks, raws: doc.raws };
+}