@react-x11/components 0.3.0 → 0.5.0

package/src/html/paint.ts

@@ -54,6 +54,9 @@ export interface PaintOptions {
   /** Where the document's origin sits in the window. Scrolling is this. */
   originX: number;
   originY: number;
+  /** Device pixels per logical pixel, for the run rules — a link's
+   *  underline is a logical pixel thick, not a device one. Default 1. */
+  scale?: number;
   /** The rectangle being repainted, in window coordinates, or null for all. */
   damage: Rect | null;
   /** The document range the selection covers, in code units, or null. */
@@ -526,7 +529,13 @@ function paintLines(ctx: PaintContext, box: Box, options: PaintOptions): void {
     for (const text of line.texts) {
       const natural = text.layout.lines[text.layoutLine];
       if (natural)
-        paintRunBackgrounds(ctx, natural, text.drawX + dx, text.drawY + dy);
+        paintRunBackgrounds(
+          ctx,
+          natural,
+          text.drawX + dx,
+          text.drawY + dy,
+          options.scale ?? 1,
+        );
     }
     paintSelection(ctx, line, options);
   }
@@ -556,7 +565,13 @@ function paintLines(ctx: PaintContext, box: Box, options: PaintOptions): void {
     for (const text of line.texts) {
       const natural = text.layout.lines[text.layoutLine];
       if (natural)
-        paintRunRules(ctx, natural, text.drawX + dx, text.drawY + dy);
+        paintRunRules(
+          ctx,
+          natural,
+          text.drawX + dx,
+          text.drawY + dy,
+          options.scale ?? 1,
+        );
     }
     for (const placed of line.atomics) paintBox(ctx, placed.box, options);
   }

package/src/index.ts

@@ -250,6 +250,7 @@ export type {
   NodeChange,
   NodeMouseHandler,
   NodePaintContext,
+  NodeRenderContext,
   PanePosition,
   Viewport,
   XYPosition,
@@ -288,6 +289,59 @@ export type {
   TableStyles,
 } from './table/index.js';
 
+// A 2D map: vector tiles the application supplies, drawn into one element
+// that owns the viewport. `docs/prd-maps.md` is the design record — what
+// the formats are, who serves them, and what each of the three caches
+// underneath this is for. `Map` shadows the built-in of that name inside a
+// module that imports it, so `import { Map as MapView }` is there for a
+// module that needs both.
+export { Map, MapViewNode, MAPVIEW_ELEMENT } from './maps/index.js';
+// The projection and the tile grid, which an application doing its own
+// geography — clustering markers, deciding what to fetch — needs the same
+// arithmetic for. Qualified on the way through the barrel where a bare name
+// would be ambiguous beside a calendar and a terminal.
+export {
+  boundsOf as boundsOfPositions,
+  cameraForBounds,
+  distanceMetres,
+  metresPerPixel,
+  tileBounds,
+  tileCover,
+  tileOf,
+  wrapLon,
+} from './maps/index.js';
+// The tile sources, the default style, and the two format helpers every
+// map application ends up writing.
+export {
+  OSM_ATTRIBUTION,
+  decodePolyline,
+  geoJsonOverlays,
+  googleTileSource,
+  osmRasterSource,
+  osmVectorSource,
+  openMapTilesStyle,
+  shortbreadStyle,
+} from './maps/index.js';
+export type {
+  FitBoundsOptions as MapFitBoundsOptions,
+  LngLat,
+  LngLatBounds,
+  MapCamera,
+  MapFrameStats,
+  MapHandle,
+  MapMarker,
+  MapOverlay,
+  MapPointerEvent,
+  MapProps,
+  MapSource,
+  MapStyle,
+  MapStyleLayer,
+  MapViewProps,
+  TileData,
+  TileId,
+  TileRequest,
+} from './maps/index.js';
+
 export { Markdown, parse as parseMarkdown } from './markdown/index.js';
 export type {
   MarkdownProps,
@@ -482,6 +536,71 @@ export type {
   TimelineVariant,
 } from './timeline/index.js';
 
+// One visible panel at a time. Chakra UI's Tabs with the parts spelled flat,
+// like `<Timeline>` — `Tabs.Root` is `<Tabs>`, `Tabs.Trigger` is
+// `<TabsTrigger>`. Successor to react-x11's own items-array `<Tabs>`.
+export {
+  Tabs,
+  TabsContent,
+  TabsIndicator,
+  TabsList,
+  TabsTrigger,
+} from './tabs/index.js';
+export type {
+  TabsContentProps,
+  TabsIndicatorProps,
+  TabsListProps,
+  TabsProps,
+  TabsSize,
+  TabsTriggerProps,
+  TabsValueChange,
+  TabsVariant,
+} from './tabs/index.js';
+
+// A list the user reorders by dragging. The sortable layer over core's own
+// drag and drop — `@dnd-kit/sortable`'s position over `@dnd-kit/core`, with
+// the engine being react-x11's. `docs/prd-reorder.md` is the survey and the
+// design record. The model comes out with it: an app that drives a list
+// from outside does the same slot arithmetic.
+export {
+  ReorderList,
+  ReorderItem,
+  ReorderHandle,
+  REORDER_TYPE,
+  useReorderItem,
+  arrayMove,
+  closestSlot,
+  insertAtSlot,
+  insertManyAtSlot,
+  isNoopSlot,
+  moveManyToSlot,
+  moveToSlot,
+} from './reorder/index.js';
+export type {
+  ReorderChange,
+  ReorderCombine,
+  ReorderDragEnd,
+  ReorderDragStart,
+  ReorderDragUpdate,
+  ReorderDrop,
+  ReorderDropQuery,
+  ReorderEdge,
+  ReorderHandleProps,
+  ReorderId,
+  ReorderInput,
+  ReorderInsert,
+  ReorderItemProps,
+  ReorderItemState,
+  ReorderListProps,
+  ReorderOrientation,
+  ReorderPoint,
+  ReorderPreviewSize,
+  ReorderRect,
+  ReorderRemove,
+  ReorderSlot,
+  ReorderStyles,
+} from './reorder/index.js';
+
 export {
   TrayHost,
   TrayManager,
@@ -636,3 +755,26 @@ export type {
   ThreeSize,
   ThreeViewport,
 } from './three/index.js';
+export {
+  QmlView,
+  QmlNode,
+  Qt,
+  parseQml,
+  instantiateDocument,
+  registerQmlModule,
+  registerReactComponent,
+  registerControls,
+  createFileResolver,
+  geometryStyle,
+  captureNode,
+  qmlColor,
+} from './qml/index.js';
+export type {
+  QmlViewProps,
+  QmlViewHandle,
+  QmlDocument,
+  QmlTypeDef,
+  QmlFacade,
+  QmlInstance,
+  QmlResolver,
+} from './qml/index.js';

package/src/maps/clip.ts

@@ -0,0 +1,184 @@
+// Clipping geometry to the target, and why anything has to.
+//
+// **Coordinates in this renderer are bounded and the world's are not.**
+// ntk hands a stroke's geometry to XRender as 16.16 fixed point, which
+// overflows a signed 32-bit word at 32,768, and a composite's coordinates
+// are int16. Two things routinely exceed that:
+//
+//  - an **overlay**, which is geography: a route's far end stays where it
+//    is when the camera zooms into one corner of it, and a world is
+//    `512 · 2^zoom` pixels — 134 million at zoom 20;
+//  - a **tile drawn past its own depth**, where one source tile is
+//    rasterized into each cell of a grid over it, so a tile-wide polygon is
+//    `span` tiles wide in the surface's pixels.
+//
+// Both want the same two algorithms, so they live here rather than twice.
+// Cohen-Sutherland for a line, because the common case is a segment wholly
+// inside or wholly outside and both are answered by one `&`/`|` of the
+// endpoints' codes with no arithmetic at all; Sutherland-Hodgman for an
+// area, because a fill needs a closed boundary — the part of a polygon that
+// crosses the window has to come back along the window's edge, which
+// segment clipping cannot produce.
+
+/** The clip window, in the same target pixels the path is built in. */
+export interface ClipRect {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+/**
+ * How far outside the pane geometry is still kept.
+ *
+ * Not zero: a line clipped exactly at the edge would have its join and its
+ * cap drawn at the boundary rather than outside it, which shows as a blunt
+ * end against the pane's edge. A margin wider than any stroke this draws
+ * puts those artefacts off-screen, and is still far inside the range that
+ * overflows.
+ */
+export const CLIP_MARGIN = 256;
+
+export function clipOf(
+  pane: { x: number; y: number; width: number; height: number },
+  scale: number,
+): ClipRect {
+  return {
+    minX: (pane.x - CLIP_MARGIN) * scale,
+    minY: (pane.y - CLIP_MARGIN) * scale,
+    maxX: (pane.x + pane.width + CLIP_MARGIN) * scale,
+    maxY: (pane.y + pane.height + CLIP_MARGIN) * scale,
+  };
+}
+
+const INSIDE = 0;
+const LEFT = 1;
+const RIGHT = 2;
+const BOTTOM = 4;
+const TOP = 8;
+
+function outcode(x: number, y: number, clip: ClipRect): number {
+  let code = INSIDE;
+  if (x < clip.minX) code |= LEFT;
+  else if (x > clip.maxX) code |= RIGHT;
+  if (y < clip.minY) code |= BOTTOM;
+  else if (y > clip.maxY) code |= TOP;
+  return code;
+}
+
+/**
+ * Cohen-Sutherland: the visible piece of one segment, or null.
+ *
+ * Chosen over Liang-Barsky because the common case here is a segment wholly
+ * inside or wholly outside, and both are answered by one `&`/`|` of the two
+ * endpoints' codes with no arithmetic at all.
+ */
+export function clipSegment(
+  ax: number,
+  ay: number,
+  bx: number,
+  by: number,
+  clip: ClipRect,
+): [number, number, number, number] | null {
+  let x0 = ax;
+  let y0 = ay;
+  let x1 = bx;
+  let y1 = by;
+  let code0 = outcode(x0, y0, clip);
+  let code1 = outcode(x1, y1, clip);
+  for (;;) {
+    if ((code0 | code1) === 0) return [x0, y0, x1, y1]; // both inside
+    if ((code0 & code1) !== 0) return null; // both beyond one edge
+    const code = code0 !== 0 ? code0 : code1;
+    let x = 0;
+    let y = 0;
+    if (code & TOP) {
+      x = x0 + ((x1 - x0) * (clip.maxY - y0)) / (y1 - y0);
+      y = clip.maxY;
+    } else if (code & BOTTOM) {
+      x = x0 + ((x1 - x0) * (clip.minY - y0)) / (y1 - y0);
+      y = clip.minY;
+    } else if (code & RIGHT) {
+      y = y0 + ((y1 - y0) * (clip.maxX - x0)) / (x1 - x0);
+      x = clip.maxX;
+    } else {
+      y = y0 + ((y1 - y0) * (clip.minX - x0)) / (x1 - x0);
+      x = clip.minX;
+    }
+    if (code === code0) {
+      x0 = x;
+      y0 = y;
+      code0 = outcode(x0, y0, clip);
+    } else {
+      x1 = x;
+      y1 = y;
+      code1 = outcode(x1, y1, clip);
+    }
+  }
+}
+
+/**
+ * Sutherland-Hodgman: a ring clipped to the rectangle, in place of the
+ * original.
+ *
+ * Rings rather than segments, because a fill needs a closed boundary: the
+ * part of a polygon that crosses the window has to come back along the
+ * window's edge, which segment clipping cannot produce. Winding is
+ * preserved, so an interior ring stays an interior ring and the non-zero
+ * fill still puts a hole where one belongs.
+ */
+export function clipRing(points: readonly number[], clip: ClipRect): number[] {
+  let output = [...points];
+  const edges: [
+    (x: number, y: number) => boolean,
+    (ax: number, ay: number, bx: number, by: number) => [number, number],
+  ][] = [
+    [
+      (x) => x >= clip.minX,
+      (ax, ay, bx, by) => [
+        clip.minX,
+        ay + ((by - ay) * (clip.minX - ax)) / (bx - ax),
+      ],
+    ],
+    [
+      (x) => x <= clip.maxX,
+      (ax, ay, bx, by) => [
+        clip.maxX,
+        ay + ((by - ay) * (clip.maxX - ax)) / (bx - ax),
+      ],
+    ],
+    [
+      (_x, y) => y >= clip.minY,
+      (ax, ay, bx, by) => [
+        ax + ((bx - ax) * (clip.minY - ay)) / (by - ay),
+        clip.minY,
+      ],
+    ],
+    [
+      (_x, y) => y <= clip.maxY,
+      (ax, ay, bx, by) => [
+        ax + ((bx - ax) * (clip.maxY - ay)) / (by - ay),
+        clip.maxY,
+      ],
+    ],
+  ];
+  for (const [inside, intersect] of edges) {
+    const input = output;
+    output = [];
+    if (input.length < 6) return [];
+    for (let i = 0; i < input.length; i += 2) {
+      const ax = input[i];
+      const ay = input[i + 1];
+      const bx = input[(i + 2) % input.length];
+      const by = input[(i + 3) % input.length];
+      const aIn = inside(ax, ay);
+      const bIn = inside(bx, by);
+      if (aIn) output.push(ax, ay);
+      if (aIn !== bIn) {
+        const [ix, iy] = intersect(ax, ay, bx, by);
+        output.push(ix, iy);
+      }
+    }
+  }
+  return output;
+}

package/src/maps/gzip.ts

@@ -0,0 +1,66 @@
+// Un-gzip a tile body, when it is one.
+//
+// Tile servers serve `Content-Encoding: gzip` — which a `fetch` undoes —
+// and a good number of them *also* store the tile gzipped inside that, so
+// the body an application hands over may still have the magic on it. That
+// is a transport detail rather than the decoder's business, so it is
+// unwrapped once, here, and `parseTile` only ever sees protobuf.
+//
+// `node:zlib` is reached the way `src/embed/host.ts` reaches `child_process`
+// and for the same reason: `tsconfig.build.json` sets `types: []`, so `src/`
+// may not name a Node module, and a package that did would stop resolving
+// on a runtime that has no such module. So the module is found on
+// `globalThis` if the host put it there and otherwise not at all — and a
+// runtime with no zlib gets a clear error naming the one line of
+// application code that fixes it, rather than a protobuf parse failure
+// twenty frames away.
+
+/** The two bytes every gzip member starts with. */
+export function isGzip(bytes: Uint8Array): boolean {
+  return bytes.length > 2 && bytes[0] === 0x1f && bytes[1] === 0x8b;
+}
+
+interface Zlib {
+  gunzipSync(data: Uint8Array): Uint8Array;
+}
+
+let zlib: Zlib | null | undefined;
+
+/**
+ * Teach this package how to un-gzip, for a runtime where it cannot find out
+ * by itself.
+ *
+ * ```ts
+ * import { gunzipSync } from 'node:zlib';
+ * setGunzip((data) => gunzipSync(data));
+ * ```
+ */
+export function setGunzip(gunzipSync: (data: Uint8Array) => Uint8Array): void {
+  zlib = { gunzipSync };
+}
+
+function findZlib(): Zlib | null {
+  if (zlib !== undefined) return zlib;
+  // Node and Bun both expose it on `globalThis` under a `require` that a
+  // bundler will not follow, which is what keeps this out of a browser
+  // bundle. Anything else: no zlib, and `setGunzip` is the way in.
+  const g = globalThis as {
+    process?: { getBuiltinModule?(name: string): unknown };
+  };
+  const module = g.process?.getBuiltinModule?.('node:zlib') as Zlib | undefined;
+  zlib = module && typeof module.gunzipSync === 'function' ? module : null;
+  return zlib;
+}
+
+/** The bytes, un-gzipped if they were. */
+export function gunzipIfNeeded(bytes: Uint8Array): Uint8Array {
+  if (!isGzip(bytes)) return bytes;
+  const found = findZlib();
+  if (!found) {
+    throw new Error(
+      'a gzipped tile arrived and this runtime has no zlib — ' +
+        'un-gzip it in your source, or call setGunzip() once at startup',
+    );
+  }
+  return found.gunzipSync(bytes);
+}