@rohal12/spindle 0.59.13 → 0.59.14

package/dist/pkg/story-variables.js

@@ -10431,28 +10431,34 @@ function parseWidgetDef(rawArgs) {
 	return widgetDef(parseMacroArgs(rawArgs, WIDGET_PARAMETERS));
 }
 /**
-* A definition: its arguments (read like a {widget} macro's, see
-* parseWidgetDef) and its body. Macro names are not case-sensitive.
-*/
-var WIDGET_DEFINITION = /\{widget\s+([^}]*)\}([\s\S]*?)\{\/widget\}/gi;
-/** `{@children}`, also with selectors such as `{.highlight @children}`. */
-var CHILDREN_PLACEHOLDER = /\{[^{}]*@children\s*\}/;
-/**
 * The names of the block widgets (those whose body renders `{@children}`)
 * that StoryInit and the passages tagged `widget` define. They must be
 * known as block macros before any passage is parsed, so that passages
 * invoking them nest their content whatever the passage order.
+*
+* The passages are read as flat tokens, which need no block macros to be
+* known, so a `{@children}` in an HTML comment or in a `{do}` body is text
+* here as it is to the parser, and does not make a block widget (#387).
 */
 function blockWidgetNames(passages) {
 	const names = [];
 	for (const passage of passages) {
 		if (passage.name !== "StoryInit" && !passage.tags?.includes("widget")) continue;
-		for (const match of passage.content.matchAll(WIDGET_DEFINITION)) {
-			if (!CHILDREN_PLACEHOLDER.test(match[2])) continue;
+		const open = [];
+		for (const token of tokenizeMarkupTolerant(passage.content).tokens) if (token.type === "macro" && token.name.toLowerCase() === "widget") {
+			if (!token.isClose) {
+				open.push({
+					rawArgs: token.rawArgs,
+					isBlock: false
+				});
+				continue;
+			}
+			const def = open.pop();
+			if (!def?.isBlock) continue;
 			try {
-				names.push(parseWidgetDef(match[1]).name);
+				names.push(parseWidgetDef(def.rawArgs).name);
 			} catch {}
-		}
+		} else if (token.type === "variable" && token.scope === "local" && token.name === "children" && open.length > 0) open[open.length - 1].isBlock = true;
 	}
 	return names;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.59.13",
+  "version": "0.59.14",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/class-registry.ts

@@ -2,6 +2,7 @@
 
 import { parse, stringify } from 'devalue';
 import { hasOwn } from './utils/namespace';
+import { extraKeys } from './utils/value-kinds';
 
 type Constructor = new (...args: any[]) => any;
 
@@ -46,7 +47,10 @@ export function clearRegistry(): void {
 // values. Spindle adds, with reducers and revivers:
 //
 // - `c:<name>`: an instance of the class registered as <name>, with its own
-//   enumerable keys (and, for Error subclasses, its message and cause);
+//   enumerable keys (and, for Error subclasses, its message and cause); for
+//   a subclass of Array, Map or Set, `[kind, contents, keys]`: the kind of
+//   collection, its elements (Map entries as pairs) and its other own
+//   enumerable keys;
 // - `E:<name>`: a built-in error (Error, TypeError, ..., AggregateError),
 //   with its message, cause, errors and own enumerable keys (not its stack);
 // - `S`: a symbol from the global registry (Symbol.for);
@@ -103,6 +107,13 @@ const ERROR_HIDDEN_KEYS = ['message', 'cause', 'errors'] as const;
 const isObject = (v: unknown): v is object =>
   typeof v === 'object' && v !== null;
 
+/** Whether `v` is a plain object (as devalue revives one). */
+const isPlainData = (v: unknown): v is Record<string, unknown> =>
+  isObject(v) && Object.getPrototypeOf(v) === Object.prototype;
+
+const malformedClass = (name: string): TypeError =>
+  new TypeError(`spindle: Malformed data for class "${name}"`);
+
 const defineData = (target: object, key: string, value: unknown): void => {
   // Define, so that a "__proto__" key stays a key (devalue refuses it)
   Object.defineProperty(target, key, {
@@ -127,7 +138,10 @@ function refuseSymbolKeys(value: object): void {
  * Own enumerable keys of `value`, as a plain object; for an error also its
  * message, cause and (AggregateError) errors, which are not enumerable.
  */
-function ownData(value: object): Record<string, unknown> {
+function ownData(
+  value: object,
+  keys = Object.keys(value),
+): Record<string, unknown> {
   refuseSymbolKeys(value);
   const data: Record<string, unknown> = {};
   if (value instanceof Error) {
@@ -135,12 +149,44 @@ function ownData(value: object): Record<string, unknown> {
       if (hasOwn(value, key)) defineData(data, key, value[key as keyof Error]);
     }
   }
-  for (const key of Object.keys(value)) {
+  for (const key of keys) {
     defineData(data, key, (value as Record<string, unknown>)[key]);
   }
   return data;
 }
 
+/** The kinds of collection a registered class may extend. */
+const COLLECTION_KINDS = {
+  Array: Array as unknown as Constructor,
+  Map: Map as Constructor,
+  Set: Set as Constructor,
+};
+type CollectionKind = keyof typeof COLLECTION_KINDS;
+
+/**
+ * The saved form of a registered class instance: its own data (see
+ * ownData), or for a collection its kind, elements and extra keys, read
+ * with the built-in methods, which a subclass may override (#391).
+ */
+function classData(value: object): unknown {
+  const extra = () => ownData(value, extraKeys(value));
+  if (Array.isArray(value)) {
+    // Holes stay holes
+    const items = new Array(value.length) as unknown[];
+    for (let i = 0; i < value.length; i++) {
+      if (i in value) items[i] = value[i] as unknown;
+    }
+    return ['Array', items, extra()];
+  }
+  if (value instanceof Map) {
+    return ['Map', Array.from(Map.prototype.entries.call(value)), extra()];
+  }
+  if (value instanceof Set) {
+    return ['Set', Array.from(Set.prototype.values.call(value)), extra()];
+  }
+  return ownData(value);
+}
+
 /** Make an error's message, cause and errors non-enumerable again. */
 function hideErrorKeys(value: object): void {
   for (const key of ERROR_HIDDEN_KEYS) {
@@ -158,7 +204,9 @@ function reducers(): Record<string, (value: unknown) => unknown> {
   const out: Record<string, (value: unknown) => unknown> = {};
   for (const [name, ctor] of registry) {
     out[CLASS_PREFIX + name] = (v) =>
-      isObject(v) && Object.getPrototypeOf(v) === ctor.prototype && ownData(v);
+      isObject(v) &&
+      Object.getPrototypeOf(v) === ctor.prototype &&
+      classData(v);
   }
   for (const [proto, name] of BUILTIN_ERRORS) {
     out[ERROR_PREFIX + name] = (v) =>
@@ -175,7 +223,7 @@ function reducers(): Record<string, (value: unknown) => unknown> {
     v.lastIndex !== 0 && [v.source, v.flags, v.lastIndex];
   if (GUARD_V8_KEYS) {
     out[KEYS_TAG] = (v) => {
-      if (!isObject(v) || Object.getPrototypeOf(v) !== Object.prototype) {
+      if (!isPlainData(v)) {
         return false;
       }
       const keys = Object.keys(v);
@@ -192,19 +240,79 @@ function reducers(): Record<string, (value: unknown) => unknown> {
   return out;
 }
 
+/**
+ * The collection of a registered class that a `[kind, contents, keys]`
+ * list holds (see classData). A cycle through the collection revives it
+ * before its list is complete (devalue holds unread parts as holes), so the
+ * collection is kept per list and filled with what the list holds so far.
+ */
+const collections = new WeakMap<unknown[], object>();
+function reviveCollection(name: string, ctor: Constructor, list: unknown[]) {
+  const [kind, contents, keys] = list;
+  const base =
+    typeof kind === 'string' && hasOwn(COLLECTION_KINDS, kind)
+      ? COLLECTION_KINDS[kind as CollectionKind]
+      : undefined;
+  if (
+    list.length !== 3 ||
+    !base ||
+    !(ctor.prototype instanceof base) ||
+    (hasOwn(list, 1) && !Array.isArray(contents)) ||
+    (hasOwn(list, 2) && !isPlainData(keys))
+  ) {
+    throw malformedClass(name);
+  }
+  let made = collections.get(list);
+  if (!made) {
+    made = Object.setPrototypeOf(new base(), ctor.prototype) as object;
+    collections.set(list, made);
+  }
+  if (Array.isArray(contents)) fillCollection(made, contents);
+  if (isPlainData(keys)) {
+    for (const key of Object.keys(keys)) defineData(made, key, keys[key]);
+  }
+  return made;
+}
+
+/** Set the elements of a revived collection, with the built-in methods. */
+function fillCollection(made: object, contents: unknown[]): void {
+  if (Array.isArray(made)) {
+    made.length = contents.length;
+    for (let i = 0; i < contents.length; i++) {
+      if (hasOwn(contents, i)) made[i] = contents[i];
+      else delete made[i];
+    }
+  } else if (made instanceof Map) {
+    Map.prototype.clear.call(made);
+    for (const entry of contents) {
+      if (!Array.isArray(entry) || entry.length !== 2) {
+        throw new TypeError('spindle: Malformed map entries');
+      }
+      Map.prototype.set.call(made, entry[0], entry[1]);
+    }
+  } else {
+    Set.prototype.clear.call(made);
+    for (const member of contents) Set.prototype.add.call(made, member);
+  }
+}
+
 /** Restore a registered class instance in place, so cycles through it hold. */
 function reviveClass(name: string) {
-  return (data: Record<string, unknown>): unknown => {
-    if (!isObject(data) || Object.getPrototypeOf(data) !== Object.prototype) {
+  return (data: Record<string, unknown> | unknown[]): unknown => {
+    if (Array.isArray(data)) {
+      return reviveCollection(name, registeredCtor(name), data);
+    }
+    if (!isPlainData(data)) {
       // Already revived: a cycle through the instance revives it twice
       if (isObject(data) && registeredClassName(data) === name) return data;
-      throw new TypeError(`spindle: Malformed data for class "${name}"`);
+      throw malformedClass(name);
     }
-    const ctor = registry.get(name);
-    if (!ctor) {
-      throw new TypeError(
-        `spindle: The save holds an instance of class "${name}", which is not registered`,
-      );
+    const ctor = registeredCtor(name);
+    // A plain object cannot be made a collection (see classData)
+    if (
+      Object.values(COLLECTION_KINDS).some((c) => ctor.prototype instanceof c)
+    ) {
+      throw malformedClass(name);
     }
     Object.setPrototypeOf(data, ctor.prototype as object);
     if (data instanceof Error) hideErrorKeys(data);
@@ -212,13 +320,24 @@ function reviveClass(name: string) {
   };
 }
 
+/** The class registered as `name`; throws if there is none. */
+function registeredCtor(name: string): Constructor {
+  const ctor = registry.get(name);
+  if (!ctor) {
+    throw new TypeError(
+      `spindle: The save holds an instance of class "${name}", which is not registered`,
+    );
+  }
+  return ctor;
+}
+
 /** Restore a built-in error in place, like a class instance. */
 function reviveError(name: string) {
   const ctor = ERROR_CTORS.get(name);
   if (!ctor) return undefined;
   return (data: Record<string, unknown>): unknown => {
     if (Object.getPrototypeOf(data) === ctor.prototype) return data;
-    if (!isObject(data) || Object.getPrototypeOf(data) !== Object.prototype) {
+    if (!isPlainData(data)) {
       throw new TypeError(`spindle: Malformed data for "${name}"`);
     }
     Object.setPrototypeOf(data, ctor.prototype);

package/src/components/macros/WidgetInvocation.tsx

@@ -1,4 +1,4 @@
-import { useMemo } from 'preact/hooks';
+import { useContext, useMemo } from 'preact/hooks';
 import { WidgetChildrenContext, renderNodes } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
 import { evaluate } from '../../expression';
@@ -9,6 +9,7 @@ import { useRenderOptions } from '../../hooks/use-render-options';
 import { LocalsScope } from './locals-scope';
 import { useInterpolate } from '../../hooks/use-interpolate';
 import { wrapContent } from './display';
+import { widgetChildrenOf } from '../../interpolation';
 
 export { splitArgs };
 
@@ -44,7 +45,11 @@ function WidgetContent({
   const [mergedVars, mergedTemps, mergedLocals, mergedTrans] =
     useMergedLocals();
 
-  const childrenValue = invocationChildren?.length ? invocationChildren : null;
+  const outerChildren = useContext(WidgetChildrenContext);
+  const childrenValue = useMemo(
+    () => widgetChildrenOf(invocationChildren, outerChildren),
+    [invocationChildren, outerChildren],
+  );
 
   // Every widget gets its own local scope, even when it declares no
   // parameters or is invoked without arguments: missing parameters shadow

package/src/execute-mutation.ts

@@ -148,6 +148,16 @@ function deeplyFrozen(value: unknown, seen = new Set<object>()): boolean {
   if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return true;
   if (!Object.isFrozen(value)) return false;
   seen.add(value);
+  // What a Map or Set holds is not in its properties (#388)
+  if (value instanceof Map) {
+    for (const [key, entry] of value) {
+      if (!deeplyFrozen(key, seen) || !deeplyFrozen(entry, seen)) return false;
+    }
+  } else if (value instanceof Set) {
+    for (const member of value) {
+      if (!deeplyFrozen(member, seen)) return false;
+    }
+  }
   return Reflect.ownKeys(value).every((key) => {
     const desc = Object.getOwnPropertyDescriptor(value, key);
     return !desc || !('value' in desc) || deeplyFrozen(desc.value, seen);

package/src/hooks/use-modal-focus.ts

@@ -14,10 +14,26 @@ const FOCUSABLE = [
   '[tabindex]',
 ].join(',');
 
+/**
+ * Whether `el` is in a closed `<details>`, other than in the summary that
+ * toggles it: the browser renders none of that content (#389).
+ */
+function inClosedDetails(el: HTMLElement): boolean {
+  for (let e = el.parentElement; e; e = e.parentElement) {
+    if (e.localName !== 'details' || e.hasAttribute('open')) continue;
+    const summary = Array.from(e.children).find(
+      (c) => c.localName === 'summary',
+    );
+    if (!summary?.contains(el)) return true;
+  }
+  return false;
+}
+
 /**
  * Whether CSS leaves `el` in the tab sequence: not `visibility: hidden`
- * (inherited, so the computed value covers ancestors) and not inside a
- * `display: none` element.
+ * (inherited, so the computed value covers ancestors), not inside a
+ * `display: none` element and not in the hidden content of a closed
+ * `<details>`.
  */
 function isRendered(el: HTMLElement): boolean {
   const { visibility } = getComputedStyle(el);
@@ -25,7 +41,21 @@ function isRendered(el: HTMLElement): boolean {
   for (let e: HTMLElement | null = el; e; e = e.parentElement) {
     if (getComputedStyle(e).display === 'none') return false;
   }
-  return true;
+  return !inClosedDetails(el);
+}
+
+/**
+ * Whether `el` can be focused at all: shown, rendered, enabled (also by its
+ * fieldset) and not inert.
+ */
+function isAvailable(el: HTMLElement): boolean {
+  return (
+    !el.hidden &&
+    !el.closest('[hidden], [inert]') &&
+    // Also covers controls disabled by a <fieldset disabled> ancestor
+    !el.matches(':disabled') &&
+    isRendered(el)
+  );
 }
 
 /** The `tabindex` of `el` as an integer, or null when absent or invalid. */
@@ -36,9 +66,10 @@ function tabIndexAttr(el: HTMLElement): number | null {
 }
 
 /**
- * Whether the tab key can reach `el`: a negative tabindex only allows
- * scripted focus, and of a radio group the browser tabs to the checked
- * member only (the first one when none is checked).
+ * Whether the tab key can reach `el`, an available element (see
+ * isAvailable): a negative tabindex only allows scripted focus, and of a
+ * radio group the browser tabs to the checked member only (the first one
+ * when none is checked), of the members it can reach.
  */
 function isTabStop(el: HTMLElement): boolean {
   const tabIndex = tabIndexAttr(el);
@@ -67,7 +98,14 @@ function isTabStop(el: HTMLElement): boolean {
       (
         el.form ?? (el.getRootNode() as ParentNode)
       ).querySelectorAll<HTMLInputElement>('input[type="radio"]'),
-    ).filter((r) => r.name === el.name && r.form === el.form && !r.disabled);
+    ).filter(
+      (r) =>
+        r.name === el.name &&
+        r.form === el.form &&
+        // Of the members Tab can reach (#390)
+        (tabIndexAttr(r) ?? 0) >= 0 &&
+        isAvailable(r),
+    );
     const stop = group.find((r) => r.checked) ?? group[0];
     return el === stop;
   }
@@ -81,15 +119,7 @@ function isTabStop(el: HTMLElement): boolean {
 function focusables(root: HTMLElement): HTMLElement[] {
   const stops = Array.from(
     root.querySelectorAll<HTMLElement>(FOCUSABLE),
-  ).filter(
-    (el) =>
-      !el.hidden &&
-      !el.closest('[hidden], [inert]') &&
-      // Also covers controls disabled by a <fieldset disabled> ancestor
-      !el.matches(':disabled') &&
-      isRendered(el) &&
-      isTabStop(el),
-  );
+  ).filter((el) => isAvailable(el) && isTabStop(el));
   const positive = (el: HTMLElement) => Math.max(tabIndexAttr(el) ?? 0, 0);
   // Array.prototype.sort is stable: equal tabindexes keep document order
   return [

package/src/interpolation.ts

@@ -40,6 +40,25 @@ export function hasInterpolation(s: string): boolean {
   return s.includes('{') || s.includes('}');
 }
 
+/**
+ * The children an invocation passes to a block widget, for `{@children}`.
+ * `outer` is the children context the invocation itself was written in: a
+ * `{@children}` among `nodes` forwards the enclosing widget's children, so it
+ * resolves there, not against `nodes` again (#386).
+ */
+export interface WidgetChildren {
+  readonly nodes: ASTNode[];
+  readonly outer: WidgetChildren | null;
+}
+
+/** The children context for an invocation's `children`, or null if none. */
+export function widgetChildrenOf(
+  children: ASTNode[] | undefined,
+  outer: WidgetChildren | null | undefined,
+): WidgetChildren | null {
+  return children?.length ? { nodes: children, outer: outer ?? null } : null;
+}
+
 /** The scope text-only markup is evaluated in. */
 export interface TextScope {
   variables: Record<string, unknown>;
@@ -47,7 +66,7 @@ export interface TextScope {
   locals: Record<string, unknown>;
   transient: Record<string, unknown>;
   /** Invocation children of the enclosing block widget, for `{@children}`. */
-  widgetChildren?: ASTNode[] | null;
+  widgetChildren?: WidgetChildren | null;
 }
 
 /** A macro, expression or markup error met while evaluating text. */
@@ -177,11 +196,12 @@ class TextEvaluator {
       case 'variable':
         if (node.scope === 'local' && node.name === 'children') {
           // As {@children} in a widget body: the invocation's children, in
-          // the scope of the body.
+          // the scope of the body, and in the children context they were
+          // written in.
           const children = scope.widgetChildren;
           if (!children) return '';
-          return this.nested('children', children, scope, depth, {
-            widgetChildren: null,
+          return this.nested('children', children.nodes, scope, depth, {
+            widgetChildren: children.outer,
           });
         }
         return this.variable(node.scope, node.name, scope);
@@ -262,7 +282,7 @@ class TextEvaluator {
       }
       return this.nested(node.name, widget.body, scope, depth, {
         locals,
-        widgetChildren: node.children.length > 0 ? node.children : null,
+        widgetChildren: widgetChildrenOf(node.children, scope.widgetChildren),
       });
     }
 

package/src/markup/render.tsx

@@ -9,6 +9,7 @@ import { markdownToHtml } from './markdown';
 import { h } from 'preact';
 import type { ASTNode, HtmlNode, MacroNode } from './ast';
 import { useTextScope } from '../hooks/use-interpolate';
+import type { WidgetChildren } from '../interpolation';
 import { useRenderOptions } from '../hooks/use-render-options';
 import {
   hasInterpolation,
@@ -67,7 +68,7 @@ const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
 
 /** Elements whose content is literal text, not markdown. */
 const PREFORMATTED_ELEMENTS = new Set(['pre', 'textarea', 'style']);
-export const WidgetChildrenContext = createContext<ASTNode[] | null>(null);
+export const WidgetChildrenContext = createContext<WidgetChildren | null>(null);
 
 /**
  * Components rendered for the non-text nodes of one renderNodes() call. Each
@@ -708,10 +709,16 @@ function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
 }
 
 function ChildrenSlot() {
-  const childrenAST = useContext(WidgetChildrenContext);
+  const children = useContext(WidgetChildrenContext);
   const renderOptions = useRenderOptions();
-  if (!childrenAST || childrenAST.length === 0) return null;
-  return <>{renderNodes(childrenAST, renderOptions)}</>;
+  if (!children) return null;
+  // The children render with the widget's locals, but a {@children} among
+  // them forwards the enclosing widget's children (#386).
+  return (
+    <WidgetChildrenContext.Provider value={children.outer}>
+      {renderNodes(children.nodes, renderOptions)}
+    </WidgetChildrenContext.Provider>
+  );
 }
 
 /**