react-x11 2.2.0 → 2.2.1

package/package.json

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

package/src/Reconciler.js

@@ -34,7 +34,11 @@ import {
 } from './nodes.js';
 import { hasDropProps } from './dnd.js';
 import { AppProvider } from './appcontext.js';
-import { defaultRootHandlers, setErrorHandler } from './errors.js';
+import {
+  defaultRootHandlers,
+  setErrorHandler,
+  STRICT_TOKENS,
+} from './errors.js';
 import {
   registerApp,
   unregisterApp,
@@ -303,15 +307,29 @@ const HostConfig = {
     // and trapFocus need commitMount too — the node has to be in the tree
     // first, so it can find the EventManager that owns focus. Drop targets
     // likewise: registration needs the root, which insertion assigns.
+    //
+    // Under REACT_X11_STRICT_TOKENS every token-styled node asks for one as
+    // well, since a bad token is only *found* once the node is attached —
+    // which is after this ran — and commitMount is the first moment React
+    // holds that node's own fiber (nodes.js `_tokenProblem`). Gated on the
+    // flag so the default mount pays nothing for a debugging mode.
     return (
       type === 'popup' ||
       Boolean(props.autoFocus) ||
       Boolean(props.trapFocus) ||
-      hasDropProps(props)
+      hasDropProps(props) ||
+      (STRICT_TOKENS && instance._usesTokens)
     );
   },
 
   commitMount(instance, type, props) {
+    // first, and before any of the work below: the tree is on its way out.
+    // `false` afterwards marks this instance's one commitMount spent, so a
+    // later re-attach throws at once rather than deferring to a call that
+    // will never come (nodes.js `_tokenProblem`).
+    const tokenError = instance._tokenError;
+    instance._tokenError = false;
+    if (tokenError) throw tokenError;
     if (type === 'popup') {
       instance.realize(null);
     }

package/src/errors.js

@@ -59,6 +59,48 @@ export function reportHandlerError(node, handler, error) {
   markFailed();
 }
 
+/**
+ * `REACT_X11_STRICT_TOKENS=1` makes a `$token` the theme does not define
+ * fatal again, for a build that would rather stop than paint something
+ * wrong. The default reports and carries on — see `reportStyleError`.
+ *
+ * Guarded rather than a bare `process.env` because the playground bundle
+ * runs in a browser, where there is no `process` at all.
+ */
+export const STRICT_TOKENS =
+  (typeof process === 'undefined'
+    ? undefined
+    : process.env?.REACT_X11_STRICT_TOKENS) === '1';
+
+/** Messages already printed, so a shared misspelled style reports once per
+ *  (node, message) rather than once per restyle — a theme swap re-resolves
+ *  the whole subtree and would otherwise print the same line every time. */
+const reportedStyleErrors = new WeakMap();
+
+/**
+ * A style the node cannot resolve — today only an unknown `$token`.
+ *
+ * Not a throw, and deliberately: the mistake is one property in one style,
+ * and the tree it would take down is the whole GUI. The property is dropped
+ * (so the widget paints without it, visibly wrong), the message names the
+ * token and whose element wore it, and `process.exitCode` is set so a test
+ * run or a supervisor still counts this as a failure. `REACT_X11_STRICT_TOKENS=1`
+ * restores the throw.
+ */
+export function reportStyleError(node, message) {
+  const seen = reportedStyleErrors.get(node);
+  if (seen?.has(message)) return;
+  if (seen) seen.add(message);
+  else reportedStyleErrors.set(node, new Set([message]));
+  const owner = ownerName(node);
+  console.error(
+    `${message}${owner ? ` — in ${owner}` : ''}. ` +
+      'The property is dropped and the app carries on; set ' +
+      'REACT_X11_STRICT_TOKENS=1 to make this throw instead.',
+  );
+  markFailed();
+}
+
 /** Wrap a call to user code so a throw is reported instead of escaping. */
 export function callHandler(node, handler, fn, ev) {
   try {

package/src/nodes.js

@@ -109,7 +109,12 @@ import {
   windowOrigin,
 } from './anchor.js';
 import { baseTheme } from './palette.js';
-import { callHandler, ownerName } from './errors.js';
+import {
+  callHandler,
+  ownerName,
+  reportStyleError,
+  STRICT_TOKENS,
+} from './errors.js';
 import {
   hooks as a11yHooks,
   isFocusable as a11yFocusable,
@@ -1557,6 +1562,11 @@ export class Node {
     // subtree's hit reach, invalidated through _clearHitBounds()
     this._paintOrderCache = null;
     this._hitBoundsCache = null;
+    // a `$token` the theme does not define, held for `commitMount` to throw
+    // on this node's own fiber — see `_tokenProblem`. Strict mode only.
+    // `null` is "commitMount is still to come", `false` is "it has been and
+    // gone", and an Error is one waiting for it
+    this._tokenError = null;
     this._syncStyle(props);
     this.yoga = yoga ? createLayoutNode() : null;
     if (this.yoga) {
@@ -1588,7 +1598,7 @@ export class Node {
    * them. `baseStyle` is the flattened `style` prop; `style` is that with
    * the active state blocks overlaid.
    */
-  _syncStyle(props) {
+  _syncStyle(props, mounting = false) {
     if (DEV && this.stylable) {
       assertNoFlatStyleProps(props, this.kind, this.semanticNames);
       validateStyle(flattenStyle(props.style), `<${this.kind} style>`);
@@ -1597,12 +1607,16 @@ export class Node {
     this._usesTokens = this.stylable && styleUsesTokens(this._baseStyle);
     if (this._usesTokens) {
       const theme = this.theme;
+      const strict = this.placed;
+      const problems = strict ? [] : null;
       this._baseStyle = resolveTokens(
         this._baseStyle,
         theme,
         `<${this.kind} style>`,
-        this.placed,
+        strict,
+        problems,
       );
+      if (problems?.length) this._tokenProblem(problems, mounting);
     }
     // `disabled` is a prop, not something the pointer does, so it is read
     // straight off props rather than driven by the event manager
@@ -2241,6 +2255,46 @@ export class Node {
     return owner.isPopup ? owner.parent != null : true;
   }
 
+  /**
+   * A `$token` this node's completed ancestry does not define.
+   *
+   * The default is `reportStyleError`: say so loudly, set `process.exitCode`,
+   * and keep the property dropped. `REACT_X11_STRICT_TOKENS=1` makes it fatal
+   * again, and then *where* the throw lands is the whole question — an error
+   * boundary only catches what React invoked, on the fiber React thinks it
+   * is working on.
+   *
+   * `mounting` is the attach walk, which runs inside `appendInitialChild`
+   * while React is completing the nearest host *ancestor* — the `<window>`,
+   * for a whole tree rendered at once. A throw there is attributed to the
+   * window and sails past every boundary the app wrote inside it, which is
+   * the bug this deferral exists for (#420). Stashed instead, and thrown
+   * from `commitMount` on this node's own fiber, where the walk up finds a
+   * boundary at any depth.
+   *
+   * Every other caller already has the right fiber (`commitUpdate`) or has
+   * no React on the stack at all (`appearanceChanged`, from an X event) —
+   * for those, throwing here is both the earliest and the only option, and
+   * the second is the crash strict mode asked for.
+   *
+   * `commitMount` happens once per instance, so a node re-attached after it
+   * has been and gone has nothing left to defer *to*; stashing there would
+   * swallow the error instead of raising it late. Those throw at once, like
+   * the keyed reorder they resemble.
+   */
+  _tokenProblem(problems, mounting) {
+    if (!STRICT_TOKENS) {
+      // every one of them: two misspellings in a style are two things to
+      // fix, and a report that named only the first would send someone back
+      // for a second run to find the second
+      for (const message of problems) reportStyleError(this, message);
+      return;
+    }
+    const error = new Error(problems[0]);
+    if (mounting && this._tokenError === null) this._tokenError = error;
+    else throw error;
+  }
+
   /** The owning window resized: re-resolve, since a query block may now
    * match that did not, or the other way round. */
   _sizeQueriesChanged() {
@@ -2287,7 +2341,7 @@ export class Node {
       if (this.isWindow) this._syncWindowBackground();
       if (this._usesTokens) {
         const before = this.style;
-        this._syncStyle(this.props);
+        this._syncStyle(this.props, mounting);
         // a token change reaches the node without React re-rendering it, so
         // the invalidation a commit would have done has to happen here too
         if (localTextStyleChanged(this.style, before)) {

package/src/style.d.ts

@@ -43,12 +43,15 @@ export function tokenNames(
   style: StyleProperties,
   out?: Set<string>,
 ): Set<string>;
-/** Replace `$token` references with values from the theme. */
+/** Replace `$token` references with values from the theme. A token the theme
+ *  does not define is dropped either way; with `strict`, the message naming
+ *  it is pushed onto `problems` for the caller to report or throw. */
 export function resolveTokens(
   style: StyleProperties,
   theme: Record<string, unknown> | null | undefined,
   where?: string,
   strict?: boolean,
+  problems?: string[] | null,
 ): StyleProperties;
 
 export function styleHasSizeQueries(style: StyleProperties): boolean;

package/src/styles.js

@@ -1206,16 +1206,37 @@ export function stripTokens(style) {
  * `strict` says the node's ancestry is complete, so a token that does not
  * resolve is a mistake. While a subtree is still being built its nodes can
  * see only part of their ancestry — the theme two levels up does not exist
- * for them yet — so resolution there is provisional: unknown tokens are
- * dropped and the node restyles when it attaches.
+ * for them yet — so resolution there is provisional.
+ *
+ * Both cases drop the property, because a value is either resolved or absent
+ * and `'$textMuted1'` is not a colour. What `strict` changes is whether
+ * anyone hears about it: mistakes are pushed onto `problems` and the caller
+ * decides what one costs. Resolving itself never throws — it runs from a
+ * commit and from an X event alike, and only the caller knows whether React
+ * is on the stack to route a throw to a boundary (src/nodes.js).
+ *
+ * A cache hit replays the problems it recorded, so the second node to wear a
+ * misspelled shared style is reported like the first.
  */
-export function resolveTokens(style, theme, where = 'style', strict = true) {
+export function resolveTokens(
+  style,
+  theme,
+  where = 'style',
+  strict = true,
+  problems = null,
+) {
   if (!theme) return stripTokens(style);
   let byTheme = strict ? resolvedCache.get(style) : null;
   if (strict && !byTheme) resolvedCache.set(style, (byTheme = new WeakMap()));
   const hit = byTheme?.get(theme);
-  if (hit) return hit;
+  if (hit) {
+    if (problems && hit.problems) problems.push(...hit.problems);
+    return hit.out;
+  }
 
+  // collected here rather than pushed straight to `problems` so the cache
+  // entry can keep them: the caller that misses is not the only one to hear
+  const found = strict ? [] : null;
   const out = {};
   for (const key of Object.keys(style)) {
     const v = style[key];
@@ -1225,11 +1246,7 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
         out[key] = theme[name];
         continue;
       }
-      if (!strict) continue;
-      throw new Error(
-        `react-x11: unknown theme token "${v}" in ${where} ` +
-          `(theme has ${Object.keys(theme).join(', ') || 'nothing'})`,
-      );
+      if (strict) found.push(unknownToken(v, theme, where));
     } else if (mentionsToken(v)) {
       let unknown = null;
       const substituted = v.replace(TOKEN_IN_VALUE, (token) => {
@@ -1245,13 +1262,10 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
       // frame instead of at the style.
       if (!unknown) out[key] = substituted;
       else if (strict) {
-        throw new Error(
-          `react-x11: unknown theme token "${unknown}" in ${where} ${key} ` +
-            `(theme has ${Object.keys(theme).join(', ') || 'nothing'})`,
-        );
+        found.push(unknownToken(unknown, theme, `${where} ${key}`));
       }
     } else if (key.charCodeAt(0) === 58 && v) {
-      out[key] = resolveTokens(v, theme, `${where} ${key}`, strict);
+      out[key] = resolveTokens(v, theme, `${where} ${key}`, strict, found);
     } else if (key === 'animation' && v && typeof v === 'object') {
       const loops = {};
       let incomplete = false;
@@ -1266,11 +1280,11 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
           theme,
           `${where} animation ${prop}`,
           strict,
+          found,
         );
-        // A provisional resolution drops what it cannot resolve, which for
-        // an ordinary property means "not styled yet". A loop with one end
-        // missing is not a shorter loop, so the whole declaration waits for
-        // the ancestry to complete rather than throwing at a half of one.
+        // A loop with one end missing is not a shorter loop, so a
+        // declaration that lost a value is dropped whole rather than run
+        // between a colour and nothing.
         if (Object.keys(resolved).length !== Object.keys(entry).length) {
           incomplete = true;
         }
@@ -1281,10 +1295,20 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
       out[key] = v;
     }
   }
-  byTheme?.set(theme, out);
+  if (found?.length && problems) problems.push(...found);
+  byTheme?.set(theme, { out, problems: found?.length ? found : null });
   return out;
 }
 
+/** The one message, written once: what was named, and what the palette in
+ *  force actually has — listing the alternatives is most of the fix. */
+function unknownToken(token, theme, where) {
+  return (
+    `react-x11: unknown theme token "${token}" in ${where} ` +
+    `(theme has ${Object.keys(theme).join(', ') || 'nothing'})`
+  );
+}
+
 export { validateStyle };
 
 /**