@react-x11/components 0.8.0 → 0.10.0

package/src/html/gif.ts

@@ -0,0 +1,233 @@
+// A GIF's first frame, as RGBA.
+//
+// ntk decodes PNG and JPEG, and a document handed to this component is
+// still full of GIFs: a mail's logo and its spacer images, a table layout's
+// one-pixel shims sized by `width` and `height`. An image that does not
+// decode is drawn as a frame, which on a spacer is a line through the
+// layout that the author meant to be nothing. So the format is read here:
+// GIF89a (and 87a) is small, fixed and unambiguous, and the decoder is the
+// LZW variant the format defines, nothing more.
+//
+// Only the first frame. An animation is drawn as it stands before it moves,
+// which is what a paused animation shows; playing one would mean a timer per
+// image and a repaint per frame, which is not this renderer's business.
+
+/** A decoded frame: straight RGBA, `width * height * 4` bytes — the shape
+ *  ntk's `Image` is constructed from. */
+export interface DecodedGif {
+  width: number;
+  height: number;
+  data: Uint8Array;
+}
+
+/** The most pixels a GIF may say it has: past this a malformed header is a
+ *  request for gigabytes, not an image. */
+const MAX_PIXELS = 1 << 25;
+
+/**
+ * Decode a GIF's first frame, or null for bytes that are not a GIF. The
+ * logical screen is the image; what the frame does not cover, and its
+ * transparent colour, are transparent. Data that ends early leaves the rest
+ * of the frame transparent rather than failing the image.
+ */
+export function decodeGif(bytes: Uint8Array): DecodedGif | null {
+  if (
+    bytes.length < 13 ||
+    bytes[0] !== 0x47 || // G
+    bytes[1] !== 0x49 || // I
+    bytes[2] !== 0x46 || // F
+    bytes[3] !== 0x38 || // 8
+    (bytes[4] !== 0x37 && bytes[4] !== 0x39) || // 7 or 9
+    bytes[5] !== 0x61 // a
+  ) {
+    return null;
+  }
+  const width = bytes[6] | (bytes[7] << 8);
+  const height = bytes[8] | (bytes[9] << 8);
+  if (!width || !height || width * height > MAX_PIXELS) return null;
+  const packed = bytes[10];
+  let at = 13;
+  let global: Uint8Array | null = null;
+  if (packed & 0x80) {
+    const size = 3 * (1 << ((packed & 7) + 1));
+    global = bytes.subarray(at, at + size);
+    at += size;
+  }
+  const data = new Uint8Array(width * height * 4);
+  let transparent = -1;
+
+  while (at < bytes.length) {
+    const block = bytes[at++];
+    if (block === 0x3b) break; // the trailer
+    if (block === 0x21) {
+      // an extension: a Graphic Control one says which colour is not drawn
+      const label = bytes[at++];
+      if (label === 0xf9 && bytes[at] >= 4) {
+        const flags = bytes[at + 1];
+        transparent = flags & 1 ? bytes[at + 4] : -1;
+      }
+      at = skipSubBlocks(bytes, at);
+      continue;
+    }
+    if (block !== 0x2c) return null; // neither: not a GIF this can read
+    if (at + 9 > bytes.length) return null;
+    const left = bytes[at] | (bytes[at + 1] << 8);
+    const top = bytes[at + 2] | (bytes[at + 3] << 8);
+    const frameWidth = bytes[at + 4] | (bytes[at + 5] << 8);
+    const frameHeight = bytes[at + 6] | (bytes[at + 7] << 8);
+    const flags = bytes[at + 8];
+    at += 9;
+    let palette = global;
+    if (flags & 0x80) {
+      const size = 3 * (1 << ((flags & 7) + 1));
+      palette = bytes.subarray(at, at + size);
+      at += size;
+    }
+    if (!palette || frameWidth * frameHeight > MAX_PIXELS) return null;
+    const minCodeSize = bytes[at++];
+    if (minCodeSize < 2 || minCodeSize > 11) return null;
+    const indices = lzw(bytes, at, minCodeSize, frameWidth * frameHeight);
+    const interlaced = (flags & 0x40) !== 0;
+    for (let row = 0; row < frameHeight; row += 1) {
+      const y = top + (interlaced ? interlacedRow(row, frameHeight) : row);
+      if (y >= height) continue;
+      for (let col = 0; col < frameWidth; col += 1) {
+        const x = left + col;
+        if (x >= width) continue;
+        const index = indices[row * frameWidth + col];
+        if (index === transparent || index * 3 + 2 >= palette.length) continue;
+        const o = (y * width + x) * 4;
+        data[o] = palette[index * 3];
+        data[o + 1] = palette[index * 3 + 1];
+        data[o + 2] = palette[index * 3 + 2];
+        data[o + 3] = 255;
+      }
+    }
+    return { width, height, data };
+  }
+  return null;
+}
+
+/** Past a run of data sub-blocks: each a length byte and that many bytes,
+ *  ended by an empty one. */
+function skipSubBlocks(bytes: Uint8Array, at: number): number {
+  while (at < bytes.length) {
+    const size = bytes[at++];
+    if (size === 0) break;
+    at += size;
+  }
+  return at;
+}
+
+/** Which row of the frame an interlaced image's `n`th stored row is: every
+ *  eighth from 0, every eighth from 4, every fourth from 2, every second
+ *  from 1. */
+function interlacedRow(n: number, height: number): number {
+  const passes: [number, number][] = [
+    [0, 8],
+    [4, 8],
+    [2, 4],
+    [1, 2],
+  ];
+  for (const [start, step] of passes) {
+    const rows = Math.ceil(Math.max(0, height - start) / step);
+    if (n < rows) return start + n * step;
+    n -= rows;
+  }
+  return height;
+}
+
+/**
+ * The colour indices of one frame, from its LZW data (GIF89a, Appendix F):
+ * variable-width codes, least significant bit first, across data sub-blocks,
+ * starting a code wider than the palette's and growing to twelve bits. A
+ * frame whose data ends early has the rest of its indices 0, which the
+ * caller never reaches past the pixels it has — they are left transparent
+ * only when the frame said the colour 0 was.
+ */
+function lzw(
+  bytes: Uint8Array,
+  at: number,
+  minCodeSize: number,
+  pixels: number,
+): Uint8Array {
+  const out = new Uint8Array(pixels);
+  const clear = 1 << minCodeSize;
+  const end = clear + 1;
+  const prefix = new Uint16Array(4096);
+  const suffix = new Uint8Array(4096);
+  const stack = new Uint8Array(4097);
+  for (let i = 0; i < clear; i += 1) suffix[i] = i;
+
+  let size = minCodeSize + 1;
+  let mask = (1 << size) - 1;
+  let next = clear + 2;
+  let previous = -1;
+  let first = 0;
+  let written = 0;
+
+  // the bit reader, over the sub-blocks
+  let block = 0;
+  let bits = 0;
+  let count = 0;
+
+  while (written < pixels) {
+    while (count < size) {
+      if (block === 0) {
+        if (at >= bytes.length) return out;
+        block = bytes[at++];
+        if (block === 0) return out;
+      }
+      if (at >= bytes.length) return out;
+      bits |= bytes[at++] << count;
+      count += 8;
+      block -= 1;
+    }
+    let code = bits & mask;
+    bits >>>= size;
+    count -= size;
+
+    if (code === clear) {
+      size = minCodeSize + 1;
+      mask = (1 << size) - 1;
+      next = clear + 2;
+      previous = -1;
+      continue;
+    }
+    if (code === end) break;
+    if (previous === -1) {
+      if (code >= clear) break; // a first code that is no colour: corrupt
+      out[written++] = code;
+      previous = code;
+      first = code;
+      continue;
+    }
+    const incoming = code;
+    let top = 0;
+    if (code >= next) {
+      // the code being defined by this very step: the previous string and
+      // its own first character (the "KwKwK" case)
+      if (code > next) break;
+      stack[top++] = first;
+      code = previous;
+    }
+    while (code >= clear) {
+      stack[top++] = suffix[code];
+      code = prefix[code];
+    }
+    first = code;
+    stack[top++] = first;
+    if (next < 4096) {
+      prefix[next] = previous;
+      suffix[next] = first;
+      next += 1;
+      if ((next & mask) === 0 && next < 4096) {
+        size += 1;
+        mask = (1 << size) - 1;
+      }
+    }
+    previous = incoming;
+    while (top > 0 && written < pixels) out[written++] = stack[--top];
+  }
+  return out;
+}

package/src/html/index.ts

@@ -22,15 +22,16 @@ import {
   Select,
   useTheme,
 } from 'react-x11';
-import type { DrawnNode, MouseEvent as X11MouseEvent } from 'react-x11';
+import type { DrawnNode, MouseEvent as X11MouseEvent, Rect } from 'react-x11';
 import { tint } from 'react-x11/style';
 import type { Style } from 'react-x11/style';
 
 import type {} from 'react-x11/jsx-runtime';
 
 import { useLinkClicks, useSelectionMenu } from '../richtext/index.js';
+import { useFontPrewarm } from '../internal/prewarm.js';
 import { hx } from './hx.js';
-import { attr } from './dom.js';
+import { attr, tagOf } from './dom.js';
 import type { Document, Element } from './dom.js';
 import { ELEMENT, HtmlViewNode, registerHtmlView } from './node.js';
 import type { HtmlViewProps, ScriptRequest } from './node.js';
@@ -41,7 +42,7 @@ import {
   selectedOption,
   textareaValue,
 } from './controls.js';
-import type { ControlRect } from './controls.js';
+import type { BareField, ControlRect } from './controls.js';
 import type { ResourceRequest, ResourceResult } from './resources.js';
 
 export {
@@ -51,7 +52,7 @@ export {
 } from './node.js';
 export type { HtmlViewProps, ScriptRequest } from './node.js';
 export type { ResourceRequest, ResourceResult } from './resources.js';
-export type { ControlRect } from './controls.js';
+export type { BareField, ControlRect } from './controls.js';
 export type { ComputedStyle, RootLook } from './css/style.js';
 export type {
   AnyNode,
@@ -97,15 +98,37 @@ export interface HtmlProps {
   selectable?: boolean;
   /** Extra author stylesheets, applied after the document's own. */
   stylesheet?: string | string[];
+  /**
+   * The encoding the host decoded `source` from, as a label (`'shift_jis'`,
+   * `'windows-1251'`). A stylesheet `onResource` hands over as bytes, with no
+   * byte order mark, charset or `@charset` of its own, is decoded with it, as
+   * CSS says a sheet is in its document's encoding. Default UTF-8.
+   */
+  charset?: string;
+  /**
+   * The URL the document came from. Given one — or a document with an
+   * absolute `<base href>` — every URL the document names reaches
+   * `onResource` and `onLink` absolute: resolved against its `<base href>`
+   * or this, and a `url()` in a linked stylesheet against the stylesheet's
+   * own URL, as a browser resolves it. Absent, URLs are handed over as the
+   * document wrote them.
+   *
+   * Nothing is fetched because of it: it says where relative URLs point,
+   * and `onResource` still decides whether anything goes there.
+   */
+  baseUrl?: string | null;
   /**
    * An external resource is wanted — an `<img src>`, a `<link rel=stylesheet>`
-   * or an `@import`. Return the bytes or the text, or a promise of them, or
-   * `null` to decline.
+   * or an `@import`, or a font an `@font-face` declares and the document
+   * uses. Return the bytes or the text, or a promise of them, or `null` to
+   * decline. A stylesheet's bytes are decoded as CSS says, from the
+   * `charset` the protocol named, if the host passes it on, and its `url`,
+   * if the host passes that, is where it came from after redirects.
    *
    * **Absent, nothing loads.** This component has no network and no
-   * filesystem of its own; images render as a frame and linked stylesheets
-   * are skipped. The host is the one that knows its cache, its proxy and
-   * whether this document is trusted.
+   * filesystem of its own; images render as a frame, linked stylesheets are
+   * skipped and text is set in the fonts the system has. The host is the one
+   * that knows its cache, its proxy and whether this document is trusted.
    */
   onResource?: (
     request: ResourceRequest,
@@ -118,15 +141,17 @@ export interface HtmlProps {
   onScript?: (script: ScriptRequest) => void;
   /**
    * A link was activated. Absent means clicks do nothing: this component
-   * never navigates by itself.
+   * never navigates by itself. The `href` is resolved against the
+   * document's base where it has one (`baseUrl`), and as written where not.
    */
   onLink?: (href: string, ev: X11MouseEvent<DrawnNode>) => void;
   /** The parsed document, each time it is re-parsed — the DOM handle. */
   onDocument?: (document: Document) => void;
   /**
-   * A form control changed. The element is the one in the DOM, so a handler
-   * that wants to keep the value writes it back with `setAttribute`-shaped
-   * mutation and calls the handle's `refresh()`.
+   * A form control changed, or a `<button>` was pressed — reported with its
+   * `value`. The element is the one in the DOM, so a handler that wants to
+   * keep the value writes it back with `setAttribute`-shaped mutation and
+   * calls the handle's `refresh()`.
    */
   onControlChange?: (element: Element, value: string | boolean) => void;
   /** Base text style. Defaults: theme `fontSize` (14), `sans-serif`. */
@@ -165,8 +190,23 @@ export interface HtmlHandle {
   refresh(): void;
   /** The element under a point, in the window's coordinates. */
   elementAt(x: number, y: number): Element | null;
+  /** The link under a point, in the window's coordinates — resolved, as
+   *  `onLink` is handed one — for a status bar, or a menu on a link. */
+  hrefAt(x: number, y: number): string | null;
+  /**
+   * Where an element is, in logical pixels from the document's top left:
+   * the space the offset of a box scrolling the document is in, so a link
+   * to `#section` is `scroller.scrollTo({ y: handle.elementRect(el).y })`.
+   * A block's border box; an inline element's across its fragments, padding
+   * and border included, as `getBoundingClientRect` measures it, and as
+   * tall as its lines. Null for an element with no box.
+   */
+  elementRect(element: Element): Rect | null;
   /** The document's `<title>`, if it had one. */
   readonly title: string | null;
+  /** The URL the document's relative URLs resolve against — its
+   *  `<base href>`, or `baseUrl` — or null where it has none. */
+  readonly base: string | null;
 }
 
 // --- the look ---------------------------------------------------------------
@@ -193,6 +233,30 @@ function deriveLook(
   };
 }
 
+/** What a document sets in the code face: the elements the UA sheet puts in
+ *  it, and a style sheet that names `monospace`, in either case. */
+const CODE_MARKUP = /<(?:code|pre|kbd|samp|tt|listing|xmp)\b|monospace/i;
+
+/**
+ * The code face, once the source holds code, and null before. A source that
+ * grows is read once, from a little before where it was last read to find a
+ * name a chunk split, so a document streamed in thousands of pieces is not
+ * read again at each one; a source that does not start with the last is
+ * read whole. Once found, found: warming a face twice warms nothing.
+ */
+function useCodeFamily(source: string, family: string): string | null {
+  const read = React.useRef({ source: '', found: false });
+  const seen = read.current;
+  if (!seen.found && source !== seen.source) {
+    const from = source.startsWith(seen.source)
+      ? Math.max(0, seen.source.length - 'monospace'.length)
+      : 0;
+    seen.found = CODE_MARKUP.test(from ? source.slice(from) : source);
+    seen.source = source;
+  }
+  return seen.found ? family : null;
+}
+
 // --- the component ----------------------------------------------------------
 
 /**
@@ -214,6 +278,8 @@ export function Html(props: HtmlProps): ReactElement {
     partial = true,
     selectable = true,
     stylesheet,
+    charset,
+    baseUrl,
     onLink,
     onResource,
     onScript,
@@ -224,12 +290,17 @@ export function Html(props: HtmlProps): ReactElement {
 
   const theme = useTheme() as unknown as Record<string, unknown>;
   const links = useLinkClicks(onLink);
+  const buttons = useButtonPresses(onControlChange);
   const menu = useSelectionMenu(selectable);
 
   const look = React.useMemo(
     () => deriveLook(theme, props),
     [theme, props.fontSize, props.fontFamily, props.monoFamily],
   );
+  // a document with code in it sets that code in the mono family, and its
+  // render is the head start its first layout would otherwise wait on the
+  // system's font matcher for (`useFontPrewarm`)
+  useFontPrewarm(useCodeFamily(source, look.monoFamily));
 
   const documentRef = React.useRef<Document | null>(null);
   const [controls, setControls] = React.useState<ControlRect[]>([]);
@@ -258,6 +329,8 @@ export function Html(props: HtmlProps): ReactElement {
     source,
     complete: !partial,
     stylesheet,
+    charset,
+    baseUrl,
     look,
     selectionColor,
     onResource,
@@ -266,7 +339,9 @@ export function Html(props: HtmlProps): ReactElement {
     onControls: handleControls,
     domRevision,
     ref: props.ref as React.Ref<unknown>,
-    style: { alignSelf: 'stretch' },
+    // grown with the component, where an application grows it: the root's
+    // background covers the whole of it, as a page's covers the window
+    style: { alignSelf: 'stretch', flexGrow: 1 },
   };
 
   const children: ReactNode[] = [
@@ -297,6 +372,14 @@ export function Html(props: HtmlProps): ReactElement {
       selectable,
       selectionColor: props.selectionColor,
       ...links,
+      onMouseDown: (ev: X11MouseEvent<DrawnNode>) => {
+        links.onMouseDown(ev);
+        buttons.onMouseDown(ev);
+      },
+      onMouseUp: (ev: X11MouseEvent<DrawnNode>) => {
+        links.onMouseUp(ev);
+        buttons.onMouseUp(ev);
+      },
       ...menu,
       'data-testname': props['data-testname'],
     } as Record<string, unknown>,
@@ -327,17 +410,72 @@ export function useHtmlHandle(): HtmlHandle & { ref: React.Ref<unknown> } {
       get title() {
         return nodeRef.current?.title ?? null;
       },
+      get base() {
+        return nodeRef.current?.documentBase ?? null;
+      },
       refresh: () => {
         nodeRef.current?.touchDocument();
         force();
       },
       elementAt: (x: number, y: number) =>
         nodeRef.current?.elementAtPoint(x, y) ?? null,
+      hrefAt: (x: number, y: number) =>
+        nodeRef.current?.hrefAtPoint(x, y) ?? null,
+      elementRect: (element: Element) =>
+        nodeRef.current?.elementRect(element) ?? null,
     }),
     [],
   );
 }
 
+/**
+ * A press and a release on the same `<button>` the document draws, reported
+ * as a pressed widget reports one: `onControlChange` with the button and its
+ * `value`. A `<button>` is laid out and drawn like any box (the UA sheet's
+ * `button` rule) — its content is the page's, and most of the buttons on
+ * the web are an icon or a pill of a page's own design — so it is the
+ * element that finds out it was pressed, not a widget. A disabled one, or
+ * a press that lands in a link inside one, is not a press of it.
+ */
+function useButtonPresses(onControlChange: HtmlProps['onControlChange']): {
+  onMouseDown: (ev: X11MouseEvent<DrawnNode>) => void;
+  onMouseUp: (ev: X11MouseEvent<DrawnNode>) => void;
+} {
+  const press = React.useRef<Element | null>(null);
+  const buttonAt = (ev: X11MouseEvent<DrawnNode>): Element | null => {
+    const target = ev.target as {
+      elementAtPoint?: (x: number, y: number) => Element | null;
+    } | null;
+    let node =
+      typeof target?.elementAtPoint === 'function'
+        ? target.elementAtPoint(ev.x, ev.y)
+        : null;
+    for (
+      ;
+      node;
+      node = node.parent?.type === 'tag' ? (node.parent as Element) : null
+    ) {
+      if (tagOf(node) === 'a' && attr(node, 'href') !== undefined) return null;
+      if (tagOf(node) === 'button') {
+        return attr(node, 'disabled') === undefined ? node : null;
+      }
+    }
+    return null;
+  };
+  return {
+    onMouseDown: (ev) => {
+      press.current = onControlChange && ev.button === 1 ? buttonAt(ev) : null;
+    },
+    onMouseUp: (ev) => {
+      const pressed = press.current;
+      press.current = null;
+      if (!pressed || !onControlChange || ev.button !== 1) return;
+      if (buttonAt(ev) !== pressed) return;
+      onControlChange(pressed, attr(pressed, 'value') ?? '');
+    },
+  };
+}
+
 // --- the widgets ------------------------------------------------------------
 
 /**
@@ -359,13 +497,16 @@ function renderControl(
   const key = `${rect.kind}:${rect.x},${rect.y}`;
   const disabled = attr(el, 'disabled') !== undefined;
   const readOnly = attr(el, 'readonly') !== undefined;
+  // a field whose box the document draws takes its content box
+  const at = rect.bare ?? rect;
   const frame: Style = {
     position: 'absolute',
-    left: Math.round(rect.x),
-    top: Math.round(rect.y),
-    width: Math.round(rect.width),
-    height: Math.round(rect.height),
+    left: Math.round(at.x),
+    top: Math.round(at.y),
+    width: Math.round(at.width),
+    height: Math.round(at.height),
   };
+  const field = rect.bare ? bareField(rect.bare) : fieldChrome(look);
   const report = (value: string | boolean): void => {
     onChange?.(el, value);
     touch();
@@ -444,7 +585,7 @@ function renderControl(
       // with whatever was last echoed into the DOM.
       widget = hx('textarea', {
         defaultValue: textareaValue(el),
-        style: [fieldChrome(look), { width: '100%', height: '100%' }],
+        style: [field, { width: '100%', height: '100%' }],
         onChange: readOnly ? undefined : (ev) => reportText(ev.value),
       });
       break;
@@ -456,7 +597,7 @@ function renderControl(
         // Core's word for a password field: nothing in it reaches a
         // selection, PRIMARY included.
         sensitive: type === 'password',
-        style: [fieldChrome(look), { width: '100%', height: '100%' }],
+        style: [field, { width: '100%', height: '100%' }],
         onChange: readOnly
           ? undefined
           : (ev) => {
@@ -495,6 +636,25 @@ function fieldChrome(look: RootLook): Style {
   };
 }
 
+/**
+ * A text field whose box the author styled: the document draws the border
+ * and the background, so the widget draws neither, and its text is the
+ * element's colour and font, which the author chose to go on that
+ * background, rather than the theme's.
+ */
+function bareField(bare: BareField): Style {
+  return {
+    backgroundColor: 'transparent',
+    borderWidth: 0,
+    borderRadius: 0,
+    paddingLeft: 0,
+    paddingRight: 0,
+    color: bare.color,
+    fontFamily: bare.fontFamily,
+    fontSize: bare.fontSize,
+  };
+}
+
 function clearRadioGroup(el: Element): void {
   const name = attr(el, 'name');
   if (!name) return;