react-x11 2.22.13 → 2.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.22.13",
+  "version": "2.23.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [

package/src/events.js

@@ -1213,7 +1213,7 @@ export class EventManager {
       n.props.onMouseEnter?.(this._makeEvent('mouseEnter', native, n));
     }
     this.hoverPath = newPath;
-    this._updateCursor(newPath);
+    this._updateCursor(newPath, native);
   }
 
   /**
@@ -1322,14 +1322,32 @@ export class EventManager {
     callHandler(node, 'unstable_onAttention', handler, ev);
   }
 
-  /** Apply the deepest hovered node's `cursor` prop to the window.
-   * Feature-detected: needs ntk with Window.setCursor (> 3.1.0). */
-  _updateCursor(path) {
+  /** Apply the deepest hovered node's cursor to the window: its `cursor`
+   * style, or what it says of the point under the pointer (`cursorAt`), or
+   * its `defaultCursor` — and failing all three, its parent's. Asked on
+   * every motion. Feature-detected: needs ntk with Window.setCursor
+   * (> 3.1.0). */
+  _updateCursor(path, native = null) {
     const wnd = this.node.window;
     if (typeof wnd.setCursor !== 'function') return;
+    // An element that draws what is inside it — a document, a graph, an
+    // editor — is one node with many cursors, and only it knows which part
+    // is a link, a handle or text: it answers for the point, in the device
+    // pixels `abs` is in, as `textIndexAt` does. While a capture holds the
+    // pointer it is not asked — hover is frozen for the gesture and the
+    // point may be anywhere — and keeps what it named where the gesture
+    // began, while a style the press changed still shows.
+    const asking = native != null && !this._captured();
+    const named = (this._pointCursors ??= new WeakMap());
     let cursor = null;
     for (let i = path.length - 1; i >= 0; i--) {
-      const c = path[i].style.cursor ?? path[i].defaultCursor;
+      const node = path[i];
+      let c = node.style.cursor;
+      if (c == null && node.cursorAt) {
+        if (asking) named.set(node, node.cursorAt(native.x, native.y) ?? null);
+        c = named.get(node) ?? null;
+      }
+      c ??= node.defaultCursor;
       if (c != null) {
         cursor = c;
         break;
@@ -1687,7 +1705,11 @@ export class EventManager {
       // …and nothing scrolls to meet it either: the node is coming back to
       // the arrangement it left, and this reveal's layout has not run, so a
       // scroll here would be computed from a rect that does not exist yet.
-      if (!restoring) this._scrollIntoView(node);
+      // Nor for a press: the node is under the pointer, so the part that
+      // matters is on screen already, and a document taller than its pane
+      // was scrolled to its top by every click on it — the drag that
+      // followed selecting from there.
+      if (!restoring && reason !== 'pointer') this._scrollIntoView(node);
       if (this.keyboardFocused) {
         this._defaultFocusOn = true;
         node.defaultFocus?.({ reason, backwards });

package/src/frame/index.js

@@ -45,6 +45,7 @@ import React, {
 
 import { useAppOrNull } from '../appcontext.js';
 import { canEmbed } from '../embedding.js';
+import { WHEEL_NOTCH_PX } from '../events.js';
 import { FrameEnv } from './env.js';
 import { CallbackTable, PROTOCOL } from './protocol.js';
 
@@ -607,9 +608,13 @@ function PaneHostView({
     onMouseDown: forward('mousedown', (ev) => ({ keycode: ev.button ?? 1 })),
     onMouseUp: forward('mouseup', (ev) => ({ keycode: ev.button ?? 1 })),
     onMouseMove: forward('mousemove', () => ({})),
+    // The host's event is in pixels — events.js turned each notch into
+    // WHEEL_NOTCH_PX of them — and the pane's window turns what it is sent
+    // into pixels again, so it is sent notches: sent the pixels, one notch
+    // scrolled a page 2304 of them.
     onWheel: forward('wheel', (ev) => ({
-      deltaX: ev.deltaX ?? 0,
-      deltaY: ev.deltaY ?? 0,
+      deltaX: (ev.deltaX ?? 0) / WHEEL_NOTCH_PX,
+      deltaY: (ev.deltaY ?? 0) / WHEEL_NOTCH_PX,
       deltaMode: ev.deltaMode ?? 'line',
       smooth: Boolean(ev.smooth),
       source: 'forwarded',

package/src/node.d.ts

@@ -699,6 +699,15 @@ export declare class Node {
   /** The cursor to show over this element when nothing in the style says
    * otherwise — `'text'` for something editable. A `cursor` style wins. */
   defaultCursor?: string;
+  /**
+   * The cursor for a point inside this element, for one that draws parts
+   * only it can tell apart — a link in a document, a handle in a graph, the
+   * text in an editor. Asked on every motion over it, with the pointer in
+   * device pixels, the unit `abs` is in. Null says nothing in particular is
+   * there, and `defaultCursor` answers. A `cursor` style still wins, and a
+   * capture holding the pointer freezes the cursor with the rest of hover.
+   */
+  cursorAt?(x: number, y: number): string | null;
   /**
    * The ARIA role this element is when the application writes none — the
    * registered-element counterpart of `<textinput>` defaulting to

package/src/nodes/animation.js

@@ -138,8 +138,14 @@ export class NodeAnimation {
     }
     // A grid reads its tracks off the style, where yoga never sees them, so
     // a change to one asks the algorithm again — and gives one that threw
-    // another go.
-    if (this.yoga && gridContainerMoved(displayed, this.style)) {
+    // another go. Asked of a layout host alone, the only node it acts on:
+    // seven properties read off two styles of every shape is a scan every
+    // node paid on each of the several swaps a mount makes, 3% of it.
+    if (
+      this.yoga &&
+      (this._host !== null || this._layoutAbandoned !== null) &&
+      gridContainerMoved(displayed, this.style)
+    ) {
       if (this._host !== null) this._hostChanged();
       else if (this._layoutAbandoned !== null) {
         this._layoutAbandoned = null;

package/src/nodes/layouthost.js

@@ -8,6 +8,7 @@ import {
   createLayoutNode,
   isMeasuringExactly,
   measuringExactly,
+  setLayoutValue,
 } from '../styles.js';
 import { Yoga } from '../yoga.js';
 import {
@@ -342,11 +343,11 @@ export class NodeLayoutHost {
     // A floor written while it was a flex item means nothing to a layout,
     // which sizes the child itself — and would outlast it as a minimum.
     if (child._floorMinW != null) {
-      cy.setMinWidth(child.style.minWidth);
+      setLayoutValue(cy, 'minWidth', child.style.minWidth);
       child._floorMinW = undefined;
     }
     if (child._floorMinH != null) {
-      cy.setMinHeight(child.style.minHeight);
+      setLayoutValue(cy, 'minHeight', child.style.minHeight);
       child._floorMinH = undefined;
     }
     child._hostSlot = null;

package/src/nodes/queries.js

@@ -7,6 +7,7 @@ import {
   localTextStyleChanged,
   containerAnswers,
 } from '../styles.js';
+import { reportStyleProblem } from '../errors.js';
 import { DEV } from './util.js';
 
 /** How many extra layout passes a flush spends settling `@container` blocks
@@ -193,7 +194,25 @@ export class NodeQueries {
       // catch-up looks the dirty flags are spent and no leaf's height moved
       // — so the floor of a card that turned from a row into a column would
       // stay the row's, and yoga would squeeze the column down to it.
-      if (applyLayoutStyle(this.yoga, this.style, before) && this.root) {
+      //
+      // This runs in a frame, so a value the layout refuses is dropped and
+      // reported rather than thrown: nothing would catch it.
+      const refused = [];
+      const moved = applyLayoutStyle(this.yoga, this.style, before, refused);
+      for (const { key, value, error } of refused) {
+        // an enum's own message already says what it is and what it takes
+        const said = error.message.startsWith('react-x11:')
+          ? error.message
+          : `react-x11: invalid ${key} ${JSON.stringify(value)} ` +
+            `(${error.message})`;
+        reportStyleProblem(
+          this,
+          `${said} in <${this.kind} style>, applied when a query block ` +
+            'started matching',
+          'The declaration is dropped, as CSS drops one it cannot parse',
+        );
+      }
+      if (moved && this.root) {
         this.root._floorsDirty = true;
         this.root._floorsContentDirty = true;
         this.root._floorsSources.add(this);

package/src/nodes/scrollable.js

@@ -889,14 +889,8 @@ export const Scrollable = (Base) =>
           ? this.yoga.getComputedWidth() - left - w
           : left;
       const far = near + w;
-      if (bottom > this.scrollY + this.abs.height) {
-        this.scrollY = bottom - this.abs.height;
-      }
-      if (top < this.scrollY) this.scrollY = top;
-      if (far > this.scrollX + this.abs.width) {
-        this.scrollX = far - this.abs.width;
-      }
-      if (near < this.scrollX) this.scrollX = near;
+      this.scrollY = nearestScroll(this.scrollY, this.abs.height, top, bottom);
+      this.scrollX = nearestScroll(this.scrollX, this.abs.width, near, far);
     }
 
     paint(ctx) {
@@ -1035,6 +1029,23 @@ export const Scrollable = (Base) =>
     }
   };
 
+/**
+ * Where one axis of a viewport scrolls to bring `[start, end)` into view,
+ * the way CSSOM View's `block: nearest` does it: a span already inside, or
+ * one that covers the viewport, leaves it where it is — nothing more of it
+ * can be shown — and one partly or wholly out comes in by the edge that
+ * moves it least, which is its near edge where it fits and its far edge
+ * where it is the larger. A document taller than its pane was scrolled to
+ * its top, wherever it had been read to.
+ */
+function nearestScroll(scroll, size, start, end) {
+  const before = start < scroll;
+  const after = end > scroll + size;
+  if (before === after) return scroll;
+  const larger = end - start > size;
+  return before !== larger ? start : end - size;
+}
+
 // An arrow key scrolls by a wheel notch — literally the one events.js
 // converts a notch into, so the two input routes agree about what one step
 // is however far a notch turns out to be.

package/src/nodes/text.js

@@ -1,7 +1,11 @@
 // <text> and its chunks: shaped, wrapped and elided text, the line bands a
 // selection paints, and the glyph strip.
 
-import { localTextStyleChanged, TEXT_REMEASURE } from '../styles.js';
+import {
+  lineHeightOf,
+  localTextStyleChanged,
+  TEXT_REMEASURE,
+} from '../styles.js';
 import { cssColorStraight } from 'ntk/color';
 import { hooks as a11yHooks } from '../a11y.js';
 import { codePointAtOffset, codeUnitOffsets } from '../textrange.js';
@@ -419,7 +423,7 @@ export class TextNode extends Node {
       layout = fonts.layout(spans, base, {
         maxWidth: Number.isFinite(maxWidth) ? maxWidth : undefined,
         align: this.style.textAlign,
-        lineHeight: this.style.lineHeight,
+        lineHeight: lineHeightOf(this.style.lineHeight),
         maxLines: Number.isFinite(maxLines) ? maxLines : undefined,
         // 'clip' is ntk's default, so an unset property and the CSS default
         // are the same request rather than two paths through the layout.

package/src/nodes/window/floors.js

@@ -3,6 +3,7 @@
 // minimums. Free functions over nodes; WindowNode drives them from size.js,
 // and a layout host from layouthost.js.
 
+import { setLayoutValue } from '../../styles.js';
 import { Yoga } from '../../yoga.js';
 import { NO_CHILDREN } from '../util.js';
 
@@ -688,7 +689,9 @@ export function freezeWidths(node, out) {
 
 /** …and back to the width the style asks for, on exactly what was pinned. */
 export function restoreWidths(frozen) {
-  for (const child of frozen) child.yoga.setWidth(child.style.width);
+  for (const child of frozen) {
+    setLayoutValue(child.yoga, 'width', child.style.width);
+  }
 }
 
 /**
@@ -909,14 +912,9 @@ export function writeFloors(node, axis) {
       if (extent > 0) floor = extent;
     }
     if ((horizontal ? child._floorMinW : child._floorMinH) === floor) continue;
-    const value = floor ?? child.style[own];
-    if (horizontal) {
-      child.yoga.setMinWidth(value);
-      child._floorMinW = floor;
-    } else {
-      child.yoga.setMinHeight(value);
-      child._floorMinH = floor;
-    }
+    setLayoutValue(child.yoga, own, floor ?? child.style[own]);
+    if (horizontal) child._floorMinW = floor;
+    else child._floorMinH = floor;
   }
 }
 

package/src/palette.js

@@ -503,6 +503,25 @@ const desktopPalettes = new Map();
  * `'no-preference'` means *use your own default*, which is the light one.
  */
 export function paletteFor(appearance) {
+  // An appearance is a frozen snapshot, replaced whole when the desktop
+  // changes (appearance.js), so the last one asked about answers by
+  // identity. `baseTheme()` asks with the same snapshot for every node
+  // created — each one detached, with no theme above it yet — and spelling
+  // the key to the palettes below was 200 ns of each on a desktop with an
+  // accent: a thousand rows scrolling into a table, a document mounting.
+  if (appearance === lastAppearance) return lastPalette;
+  const palette = paletteOf(appearance);
+  if (Object.isFrozen(appearance)) {
+    lastAppearance = appearance;
+    lastPalette = palette;
+  }
+  return palette;
+}
+
+let lastAppearance = null;
+let lastPalette = null;
+
+function paletteOf(appearance) {
   const scheme = appearance.colorScheme === 'dark' ? DarkTheme : DefaultTheme;
   if (appearance.palette) return withDesktopPalette(scheme, appearance.palette);
   const { accent, accentText, selection } = appearance;

package/src/styles.js

@@ -11,7 +11,7 @@ import {
   GRID_CONTAINER_PROPS,
   GRID_ITEM_PROPS,
 } from './grid.js';
-import { Yoga } from './yoga.js';
+import { Yoga, layoutLoaded } from './yoga.js';
 
 const FLEX_DIRECTION = {
   row: Yoga.FLEX_DIRECTION_ROW,
@@ -855,6 +855,19 @@ const GRID_VALUES = new Set([...GRID_CONTAINER_PROPS, ...GRID_ITEM_PROPS]);
  * grammar is concerned), so this checks the shape and never the colours.
  */
 function validateValue(key, value, where) {
+  const text = TEXT_VALUE_CHECKS.get(key);
+  if (text !== undefined) {
+    // unset, the way a conditional writes it
+    if (value == null || value === '' || isToken(value)) return;
+    const [valid, expected] = text;
+    if (!valid(value)) {
+      throw new Error(
+        `react-x11: invalid ${key} ${JSON.stringify(value)} in ${where} ` +
+          `(expected ${expected})`,
+      );
+    }
+    return;
+  }
   if (key === 'letterSpacing') {
     if (
       value != null &&
@@ -913,6 +926,26 @@ function validateValue(key, value, where) {
     }
     return;
   }
+  // A layout value the layout cannot take — `width: 'hidden'`, `padding:
+  // 'auto'`, `flexDirection: 'sideways'` — throws where it is applied, and
+  // inside a query block that is a frame, not a commit: a block that starts
+  // matching on a resize took the process down. So it is asked here, of the
+  // same appliers, wherever it is written. A `$token` is not a length until
+  // it resolves, and is answered by the frame then (`_sizeQueriesChanged`).
+  const refused =
+    isToken(value) || mentionsToken(value) ? null : layoutRefusal(key, value);
+  if (refused) {
+    // an enum's own message lists the choices; yoga's names only itself
+    if (refused.message.startsWith('react-x11:')) {
+      refused.message += `\n  in ${where}`;
+      throw refused;
+    }
+    const auto = layoutRefusal(key, 'auto') === null ? ", or 'auto'" : '';
+    throw new Error(
+      `react-x11: invalid ${key} ${JSON.stringify(value)} in ${where} ` +
+        `(expected a number of pixels or a percentage like '50%'${auto})`,
+    );
+  }
   const grid = GRID_VALUES.has(key);
   if (!grid && key !== 'backgroundImage' && key !== 'boxShadow') return;
   try {
@@ -1566,11 +1599,15 @@ const TOKEN_IN_VALUE = /\$[A-Za-z_][A-Za-z0-9_-]*/g;
 const mentionsToken = (v) =>
   typeof v === 'string' && v.charCodeAt(0) !== 36 && v.includes('$');
 
-/** The nested blocks a token can hide in, one level down: a state block,
- *  whose values are style values, and `animation`, whose values are the
- *  per-property declarations *whose* values are style values. Both are
- *  walked by everything that looks for a `$name`, so a themed loop resolves
- *  by the same rules as a themed hover. */
+/** The nested blocks a token can hide in, one level down: a state block or
+ *  a query block, whose values are style values, and `animation`, whose
+ *  values are the per-property declarations *whose* values are style
+ *  values. All are walked by everything that looks for a `$name`, so a
+ *  themed loop resolves by the same rules as a themed hover — and a themed
+ *  wide layout too. The query blocks were missed: `'@width >= 600':
+ *  { padding: '$gutter' }` handed yoga the string `'$gutter'` the moment
+ *  it matched, which threw from the frame. */
+const holdsStyle = (key) => isState(key) || isQuery(key);
 const animationBlocks = (style) =>
   style.animation && typeof style.animation === 'object'
     ? Object.values(style.animation).filter((e) => e && typeof e === 'object')
@@ -1580,7 +1617,7 @@ export function styleUsesTokens(style) {
   for (const key of Object.keys(style)) {
     const v = style[key];
     if (isToken(v) || mentionsToken(v)) return true;
-    if (key.charCodeAt(0) === 58 && v && styleUsesTokens(v)) return true;
+    if (holdsStyle(key) && v && styleUsesTokens(v)) return true;
   }
   return animationBlocks(style).some(styleUsesTokens);
 }
@@ -1594,7 +1631,7 @@ export function tokenNames(style, out = new Set()) {
     if (isToken(v)) out.add(v);
     else if (mentionsToken(v))
       for (const m of v.match(TOKEN_IN_VALUE) ?? []) out.add(m);
-    else if (key.charCodeAt(0) === 58 && v) tokenNames(v, out);
+    else if (holdsStyle(key) && v) tokenNames(v, out);
   }
   for (const block of animationBlocks(style)) tokenNames(block, out);
   return out;
@@ -1624,7 +1661,7 @@ export function stripTokens(style) {
     if (key === 'animation' && animationBlocks(style).some(styleUsesTokens)) {
       continue;
     }
-    out[key] = key.charCodeAt(0) === 58 && v ? stripTokens(v) : v;
+    out[key] = holdsStyle(key) && v ? stripTokens(v) : v;
   }
   return out;
 }
@@ -1691,7 +1728,7 @@ export function resolveTokens(
       else if (strict) {
         found.push(unknownToken(unknown, theme, `${where} ${key}`));
       }
-    } else if (key.charCodeAt(0) === 58 && v) {
+    } else if (holdsStyle(key) && v) {
       out[key] = resolveTokens(v, theme, `${where} ${key}`, strict, found);
     } else if (key === 'animation' && v && typeof v === 'object') {
       const loops = {};
@@ -2011,9 +2048,22 @@ const NO_STYLE = Object.freeze({});
  * name of both styles was most of the cost of a node that mounts — a
  * virtualized list replaces its rows at input rate.
  *
+ * `problems` is for a caller React is not under — a query block that
+ * starts matching mid-frame — where a throw would leave the frame and take
+ * the process with it. A value the layout cannot take is then dropped, the
+ * property going back to its default as CSS drops a declaration it cannot
+ * parse, and `{ key, value, error }` is pushed for the caller to report.
+ * Without it the value throws, which is what a commit wants: React routes
+ * it to a boundary.
+ *
  * @returns true if any layout-affecting prop changed
  */
-export function applyLayoutStyle(yogaNode, props, oldProps = NO_STYLE) {
+export function applyLayoutStyle(
+  yogaNode,
+  props,
+  oldProps = NO_STYLE,
+  problems = null,
+) {
   let changed = false;
   // A placed node's insets — sticky's thresholds, or whatever a registered
   // position reads them as — are the placement's, never offsets: yoga gets
@@ -2030,7 +2080,12 @@ export function applyLayoutStyle(yogaNode, props, oldProps = NO_STYLE) {
         ? !samePosition(props.position, oldProps.position)
         : props[key] !== oldProps[key];
     if (!moved && !(flipped && inset)) continue;
-    applier(yogaNode, placed && inset ? undefined : props[key]);
+    const value = placed && inset ? undefined : props[key];
+    // `null` is unset, the way a conditional writes it — `wide ? 240 :
+    // null` — and as it is for every other property in this vocabulary;
+    // yoga's own setters throw on it
+    if (problems === null) applier(yogaNode, value ?? undefined);
+    else applyOrDrop(applier, yogaNode, key, value ?? undefined, problems);
     changed = true;
   }
   // …and the ones the new style dropped, which go back to yoga's default
@@ -2051,6 +2106,72 @@ export function applyLayoutStyle(yogaNode, props, oldProps = NO_STYLE) {
   return changed;
 }
 
+/**
+ * One layout property set on its own — a width put back after the content
+ * floors pinned it, a minimum restored under a floor — by the rules
+ * `applyLayoutStyle` sets it by: `null` is unset, and a value the layout
+ * refuses is dropped. A refused one was reported where it was first
+ * applied, and throwing here would throw from inside a layout pass.
+ */
+export function setLayoutValue(yogaNode, key, value) {
+  const applier = LAYOUT_APPLIER_OF.get(key);
+  try {
+    applier(yogaNode, value ?? undefined);
+  } catch {
+    applier(yogaNode, undefined);
+  }
+}
+
+/** One declaration, dropped rather than thrown when the layout refuses it
+ *  (`applyLayoutStyle`'s `problems`). */
+function applyOrDrop(applier, yogaNode, key, value, problems) {
+  try {
+    applier(yogaNode, value);
+  } catch (error) {
+    applier(yogaNode, undefined);
+    problems.push({ key, value, error });
+  }
+}
+
+// A yoga node no layout runs on, for development to ask whether a value is
+// one the layout can take: the question the frame asks, so the two cannot
+// disagree about what a length is.
+let scratchNode = null;
+
+// What the layout has already taken, per property, so development asks
+// yoga once per spelling rather than once per style it checks: a list of a
+// thousand rows checks the same six values a thousand times, and a setter
+// is a call into WebAssembly. A property that takes one number takes them
+// all — a length, a factor — and one that refuses them is an enum, so
+// numbers are remembered as one entry.
+const takenValues = new Map(
+  [...LAYOUT_APPLIER_OF.keys()].map((key) => [key, new Set()]),
+);
+const NUMBERS = Symbol('numbers');
+const TAKEN_MAX = 256;
+
+/** What applying `value` to `key` throws, or null when the layout takes
+ *  it — and for a key that is not a layout property. */
+function layoutRefusal(key, value) {
+  const taken = takenValues.get(key);
+  if (taken === undefined || value == null) return null;
+  if (taken.has(typeof value === 'number' ? NUMBERS : value)) return null;
+  if (scratchNode === null) {
+    // `createStyles` validates at module scope, before `createRoot` has
+    // loaded the engine — and the commit validates the same style again
+    if (!layoutLoaded()) return null;
+    scratchNode = Yoga.Node.create();
+  }
+  try {
+    LAYOUT_APPLIER_OF.get(key)(scratchNode, value);
+  } catch (error) {
+    return error;
+  }
+  if (typeof value === 'number') taken.add(NUMBERS);
+  else if (taken.size < TAKEN_MAX) taken.add(value);
+  return null;
+}
+
 /** Two `position` values asking for the same thing. A registered one written
  *  with its options is an object, and an inline object is a new one every
  *  render — which must not cost a layout pass per commit. */
@@ -2098,16 +2219,81 @@ export function paintPropsChanged(props, oldProps = {}) {
   );
 }
 
+// The text values a style can get wrong in a way the engines do not survive:
+// a `fontStyle` of `7` threw from inside ntk's face matching, a `lineHeight`
+// of `'24px'` made a paragraph NaN pixels tall — thrown from the layout
+// pass, where nothing catches it — and a `fontSize` of `'20px'` set no text
+// at all. A number is a number or a numeric string, the way the coercion
+// these always went through read one; anything else is not the property,
+// and text inherits past it, as CSS inherits past a declaration it cannot
+// parse. Development says so where the style is written (`validateValue`).
+const NUMERIC_TEXT = /^\s*[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?\s*$/i;
+const numericOf = (v) =>
+  typeof v === 'number'
+    ? v
+    : typeof v === 'string' && NUMERIC_TEXT.test(v)
+      ? Number(v)
+      : NaN;
+const FONT_WEIGHT_WORDS = new Set(['normal', 'bold', 'bolder', 'lighter']);
+const FONT_STYLE = /^(?:normal|italic|oblique)\b/;
+
+const isFontSize = (v) => {
+  const n = numericOf(v);
+  return n >= 0 && n < Infinity;
+};
+const isFontWeight = (v) => {
+  if (FONT_WEIGHT_WORDS.has(v)) return true;
+  const n = numericOf(v);
+  return n >= 1 && n <= 1000;
+};
+const isFontStyle = (v) => typeof v === 'string' && FONT_STYLE.test(v);
+const isFontFamily = (v) => typeof v === 'string' && v.trim() !== '';
+
+/** A `lineHeight` a layout can multiply by, or undefined for the font's own. */
+export function lineHeightOf(value) {
+  const n = numericOf(value);
+  return n >= 0 && n < Infinity ? n : undefined;
+}
+
+/** What each of them is, for development's message. */
+const TEXT_VALUE_CHECKS = new Map([
+  ['fontSize', [isFontSize, 'a number of pixels, like fontSize: 14']],
+  [
+    'fontWeight',
+    [
+      isFontWeight,
+      "a weight from 1 to 1000, like 600, or 'normal', 'bold', 'bolder' or " +
+        "'lighter'",
+    ],
+  ],
+  ['fontStyle', [isFontStyle, "'normal', 'italic' or 'oblique'"]],
+  [
+    'fontFamily',
+    [isFontFamily, "a family's name, like 'Inter' or 'monospace'"],
+  ],
+  [
+    'lineHeight',
+    [
+      (v) => lineHeightOf(v) !== undefined,
+      "a multiple of the font's own line height, like lineHeight: 1.5",
+    ],
+  ],
+]);
+
 /** Resolved text style (TextLayout base style) from props + inherited. */
 export function textStyleFrom(props, inherited) {
   const variantNumeric = props.fontVariantNumeric ?? inherited.variantNumeric;
   const featureSettings =
     props.fontFeatureSettings ?? inherited.featureSettings;
   return {
-    family: props.fontFamily ?? inherited.family,
-    size: props.fontSize ?? inherited.size,
-    weight: props.fontWeight ?? inherited.weight,
-    style: props.fontStyle ?? inherited.style,
+    family: isFontFamily(props.fontFamily)
+      ? props.fontFamily
+      : inherited.family,
+    size: isFontSize(props.fontSize) ? props.fontSize : inherited.size,
+    weight: isFontWeight(props.fontWeight)
+      ? props.fontWeight
+      : inherited.weight,
+    style: isFontStyle(props.fontStyle) ? props.fontStyle : inherited.style,
     // ntk's name for it is `variations`; the prop is spelled after the CSS
     // property, like every other name in this vocabulary
     variations: props.fontVariationSettings ?? inherited.variations,

package/src/types/nodes.d.ts

@@ -148,7 +148,8 @@ export interface ScrollableNode extends DrawnNode {
   canScroll(dx: number, dy: number): boolean;
   /**
    * Scroll the minimum amount on both axes that makes a descendant fully
-   * visible. Safe to call right after that node mounts — the request is
+   * visible; one larger than the viewport is left where it covers it and
+   * otherwise brought in by its nearer edge (CSSOM View's `nearest`). Safe to call right after that node mounts — the request is
    * resolved on the next layout pass, when it has geometry, and `onScroll`
    * reports the move once that pass is over.
    */