@rohal12/spindle 0.59.12 → 0.59.14

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,
@@ -52,7 +53,7 @@ export const InlineContext = createContext(false);
 /**
  * True while rendering inside an element whose content is not markdown: SVG
  * (whose namespace `<p>` wrappers would break) and the preformatted `<pre>`
- * and `<textarea>`, whose text (indentation, `#`, `*`, ...) is literal.
+ * `<textarea>` and `<style>`, whose text (indentation, `#`, `*`, ...) is literal.
  * Macro and widget bodies read it so their content stays literal too.
  */
 export const RawTextContext = createContext(false);
@@ -66,8 +67,8 @@ const SvgContext = createContext(false);
 const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
 
 /** Elements whose content is literal text, not markdown. */
-const PREFORMATTED_ELEMENTS = new Set(['pre', 'textarea']);
-export const WidgetChildrenContext = createContext<ASTNode[] | null>(null);
+const PREFORMATTED_ELEMENTS = new Set(['pre', 'textarea', 'style']);
+export const WidgetChildrenContext = createContext<WidgetChildren | null>(null);
 
 /**
  * Components rendered for the non-text nodes of one renderNodes() call. Each
@@ -392,6 +393,7 @@ const INLINE_ELEMENTS = new Set([
   'span',
   'strong',
   'sub',
+  'summary',
   'sup',
   'time',
   'u',
@@ -632,6 +634,15 @@ function resolveAttributeValue(
   return result.text;
 }
 
+/** The index of the summary element opening `nodes`, or -1 when none does. */
+function leadingSummaryIndex(nodes: ASTNode[]): number {
+  const at = nodes.findIndex((n) => n.type !== 'text' || n.value.trim() !== '');
+  const first = nodes[at];
+  return first?.type === 'html' && first.tag.toLowerCase() === 'summary'
+    ? at
+    : -1;
+}
+
 function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
   const scope = useTextScope();
   const { nobr, locals, raw: inRaw, inline: parentInline } = useRenderOptions();
@@ -658,7 +669,22 @@ function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
     if (inRaw || isRawRoot) {
       children = renderInlineNodes(node.children);
     } else {
-      children = renderNodes(node.children, { nobr, locals, inline: isInline });
+      // A details element's summary stays its direct child: it is rendered
+      // apart from the markdown of the rest of the content.
+      const summaryAt =
+        tag === 'details' ? leadingSummaryIndex(node.children) : -1;
+      const body = (nodes: ASTNode[]) =>
+        renderNodes(nodes, { nobr, locals, inline: isInline });
+      children =
+        summaryAt === -1 ? (
+          body(node.children)
+        ) : (
+          <>
+            {body(node.children.slice(0, summaryAt))}
+            {renderSingleNode(node.children[summaryAt]!)}
+            {body(node.children.slice(summaryAt + 1))}
+          </>
+        );
       if (isInline !== parentInline) {
         children = (
           <InlineContext.Provider value={isInline}>
@@ -683,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>
+  );
 }
 
 /**

package/src/story-api.ts

@@ -23,6 +23,7 @@ import { getBackendType } from './saves/storage';
 import { registerClass } from './class-registry';
 import {
   frozenCopy,
+  readOnlyValue,
   getActiveMutationScope,
   mutateState,
 } from './execute-mutation';
@@ -286,7 +287,7 @@ function createStoryAPI(): StoryAPI {
       const value = key.includes('.')
         ? getByPath(namespace, key.split('.'))
         : ownValue(namespace, key);
-      return scope ? frozenCopy(value) : value;
+      return scope ? frozenCopy(value) : readOnlyValue(value);
     },
 
     set(nameOrVars: string | Record<string, unknown>, value?: unknown): void {

package/src/story-variables.ts

@@ -32,7 +32,13 @@ function tokensOf(text: string, textMode: boolean): Token[] {
   }
 }
 
-export type VarType = 'number' | 'string' | 'boolean' | 'array' | 'object';
+export type VarType =
+  | 'number'
+  | 'string'
+  | 'boolean'
+  | 'array'
+  | 'object'
+  | 'null';
 
 export interface FieldSchema {
   type: VarType;
@@ -66,7 +72,9 @@ function inferSchema(value: unknown): FieldSchema {
   if (Array.isArray(value)) {
     return { type: 'array' };
   }
-  if (value !== null && typeof value === 'object') {
+  // A default of null means "nothing yet"; the value may later be anything
+  if (value === null) return { type: 'null' };
+  if (typeof value === 'object') {
     const fields = new Map<string, FieldSchema>();
     for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
       fields.set(key, inferSchema(val));
@@ -156,6 +164,8 @@ function validateRef(
     // Arrays have built-in methods/properties (push, find, length, etc.)
     // so any field access on an array is allowed.
     if (current.type === 'array') return null;
+    // A null default may later hold a value of any shape
+    if (current.type === 'null') return null;
 
     // Primitives expose their wrapper's built-ins (length, toUpperCase,
     // toFixed, etc.). Keep validating past properties of primitive type.

package/src/structural.ts

@@ -12,7 +12,7 @@
 import { registeredClassName } from './class-registry';
 import { hasOwn, setOwn } from './utils/namespace';
 import { deleteByPath, getByPath, setByPath } from './utils/object-path';
-import { isAtomic, isBoxed, isTemporal } from './utils/value-kinds';
+import { extraKeys, isAtomic, isBoxed, isTemporal } from './utils/value-kinds';
 
 export { isAtomic };
 
@@ -24,6 +24,26 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return proto === Object.prototype || proto === null;
 }
 
+/**
+ * `empty`, a new collection (Array, Map or Set) standing for `obj`, made
+ * like it: an instance of a registered subclass keeps its class and its
+ * extra keys (#391), with the values `value` gives for them; other
+ * collections are plain. `made` gets it before its keys are filled, so
+ * that cycles through it find it.
+ */
+function collectionLike<C extends object>(
+  obj: object,
+  empty: C,
+  made: (copy: C) => void,
+  value: (key: string) => unknown,
+): C {
+  made(empty);
+  if (registeredClassName(obj) === undefined) return empty;
+  Object.setPrototypeOf(empty, Object.getPrototypeOf(obj) as object);
+  for (const key of extraKeys(obj)) setOwn(empty, key, value(key));
+  return empty;
+}
+
 /** Own keys of an error that are not enumerable but are data. */
 const ERROR_HIDDEN_KEYS = ['message', 'cause', 'errors'] as const;
 
@@ -131,6 +151,15 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
       : copy;
   }
 
+  /** `empty`, made the copy of the collection `obj` (see collectionLike). */
+  const collection = <C extends object>(obj: object, empty: C): C =>
+    collectionLike(
+      obj,
+      empty,
+      (copy) => keep(obj, copy),
+      (key) => clone((obj as Record<string, unknown>)[key]),
+    );
+
   function clone(val: unknown): unknown {
     if (val === null || typeof val !== 'object') return val;
 
@@ -139,22 +168,25 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
 
     if (Array.isArray(val)) {
       // Holes stay holes
-      const arr = keep(obj, new Array(val.length) as unknown[]);
+      const arr = collection(obj, new Array(val.length) as unknown[]);
       for (let i = 0; i < val.length; i++) {
         if (i in val) arr[i] = clone(val[i]);
       }
       return arr;
     }
 
+    // Filled with the built-in methods: a subclass may override them
     if (val instanceof Map) {
-      const copy = keep(obj, new Map());
-      for (const [k, v] of val) copy.set(settled(clone(k), k), clone(v));
+      const copy = collection(obj, new Map());
+      for (const [k, v] of val) {
+        Map.prototype.set.call(copy, settled(clone(k), k), clone(v));
+      }
       return copy;
     }
 
     if (val instanceof Set) {
-      const copy = keep(obj, new Set());
-      for (const v of val) copy.add(settled(clone(v), v));
+      const copy = collection(obj, new Set());
+      for (const v of val) Set.prototype.add.call(copy, settled(clone(v), v));
       return copy;
     }
 
@@ -295,15 +327,23 @@ export function shareEqual<T>(prev: unknown, curr: T): T {
     if (placed !== undefined) return placed;
     if (!isObjectValue(p)) return fresh(c);
     if (reuse(p, c)) return p;
+    const pr = p as Record<string, unknown>;
+    const cr = c as Record<string, unknown>;
+    /** What the result holds at `key` of `c`. */
+    const shareKey = (key: string) =>
+      share(hasOwn(pr, key) ? pr[key] : undefined, cr[key]);
+    /** `empty`, made the result for the collection `c` (see collectionLike). */
+    const collection = <C extends object>(empty: C): C =>
+      collectionLike(c, empty, (out) => done.set(c, out), shareKey);
     if (c instanceof Map && p instanceof Map) {
-      const out = new Map();
-      done.set(c, out);
-      for (const [k, v] of c) out.set(fresh(k), share(p.get(k), v));
+      const out = collection(new Map());
+      for (const [k, v] of c) {
+        Map.prototype.set.call(out, fresh(k), share(p.get(k), v));
+      }
       return out;
     }
     if (Array.isArray(c) && Array.isArray(p)) {
-      const out = new Array(c.length) as unknown[];
-      done.set(c, out);
+      const out = collection(new Array(c.length) as unknown[]);
       for (let i = 0; i < c.length; i++) {
         if (i in c) out[i] = share(p[i], c[i]);
       }
@@ -312,10 +352,7 @@ export function shareEqual<T>(prev: unknown, curr: T): T {
     if (mergesWith(p, c, false)) {
       const out = Object.create(Object.getPrototypeOf(c) as object | null);
       done.set(c, out);
-      const cr = c as Record<string, unknown>;
-      for (const key of Object.keys(cr)) {
-        setOwn(out, key, share(hasOwn(p, key) ? p[key] : undefined, cr[key]));
-      }
+      for (const key of Object.keys(cr)) setOwn(out, key, shareKey(key));
       return out;
     }
     return fresh(c);
@@ -382,17 +419,40 @@ function equalBuiltin(
   return undefined;
 }
 
-function equalKeys(a: object, b: object, assumed: Pairs): boolean {
+function equalKeys(
+  a: object,
+  b: object,
+  assumed: Pairs,
+  keysOf: (o: object) => string[] = Object.keys,
+): boolean {
   const ao = a as Record<string, unknown>;
   const bo = b as Record<string, unknown>;
-  const keys = Object.keys(ao);
-  if (keys.length !== Object.keys(bo).length) return false;
+  const keys = keysOf(ao);
+  if (keys.length !== keysOf(bo).length) return false;
   for (const key of keys) {
     if (!hasOwn(bo, key) || !equal(ao[key], bo[key], assumed)) return false;
   }
   return true;
 }
 
+/** Built-in collection prototypes, whose instances hold no extra keys. */
+const COLLECTION_PROTOS: ReadonlySet<object | null> = new Set([
+  Array.prototype,
+  Map.prototype,
+  Set.prototype,
+]);
+
+/**
+ * Equality of the extra keys (see extraKeys) of two collections of one
+ * class: those of a subclass instance are part of its value.
+ */
+function equalExtraKeys(a: object, b: object, assumed: Pairs): boolean {
+  return (
+    COLLECTION_PROTOS.has(Object.getPrototypeOf(a) as object | null) ||
+    equalKeys(a, b, assumed, extraKeys)
+  );
+}
+
 /** `assumed` tracks the pairs of objects met (see Pairs). */
 function equal(a: unknown, b: unknown, assumed: Pairs): boolean {
   if (Object.is(a, b) && !(assumed.strict && isObjectValue(a))) return true;
@@ -420,7 +480,7 @@ function equal(a: unknown, b: unknown, assumed: Pairs): boolean {
     ) {
       if (!equal(x.value, y.value, assumed)) return false;
     }
-    return true;
+    return equalExtraKeys(a, b, assumed);
   }
 
   const builtin = equalBuiltin(a, b, assumed);
@@ -432,7 +492,7 @@ function equal(a: unknown, b: unknown, assumed: Pairs): boolean {
     for (let i = 0; i < a.length; i++) {
       if (i in a !== i in bc || !equal(a[i], bc[i], assumed)) return false;
     }
-    return true;
+    return equalExtraKeys(a, b, assumed);
   }
 
   return equalKeys(a, b, assumed);
@@ -466,7 +526,11 @@ export function mergesWith(
   arrays: boolean,
 ): a is Record<string, unknown> {
   if (arrays && (Array.isArray(a) || Array.isArray(b))) {
-    return Array.isArray(a) && Array.isArray(b);
+    return (
+      Array.isArray(a) &&
+      Array.isArray(b) &&
+      Object.getPrototypeOf(a) === Object.getPrototypeOf(b)
+    );
   }
   return (
     isMergeable(a) &&

package/src/utils/control-edits.ts

@@ -1,15 +1,48 @@
+import { getByPath } from './object-path';
+
 /**
- * Counts the edits a reader made through a control bound to a story
+ * Records the edits a reader made through a control bound to a story
  * variable (`{textbox}`, `{checkbox}`, ...). {for} tells these apart from a
  * list that is replaced: typing into a control inside an iteration changes
  * its item, but must not remount the iteration and drop the control's focus.
+ * An edit is attributed to the variable path it wrote, so a replacement made
+ * elsewhere (a watcher reacting to the edit) still remounts.
  */
 let version = 0;
+const MAX_LOG = 256;
+const log: { version: number; segments: readonly string[] }[] = [];
 
-export function noteControlEdit(): void {
-  version++;
+export function noteControlEdit(segments: readonly string[]): void {
+  log.push({ version: ++version, segments });
+  if (log.length > MAX_LOG) log.shift();
 }
 
 export function controlEditVersion(): number {
   return version;
 }
+
+/**
+ * Whether an edit since `since` wrote inside `item`, element `index` of
+ * `list`: the path leads through the item (compared by reference in
+ * `variables`), or, for a primitive item, ends at its slot in the list.
+ */
+export function editedItem(
+  since: number,
+  variables: object,
+  list: readonly unknown[],
+  item: unknown,
+  index: number,
+): boolean {
+  return log.some(({ version: v, segments }) => {
+    if (v <= since) return false;
+    if (typeof item === 'object' && item !== null) {
+      return segments.some(
+        (_, n) => getByPath(variables, segments.slice(0, n + 1)) === item,
+      );
+    }
+    return (
+      segments[segments.length - 1] === String(index) &&
+      getByPath(variables, segments.slice(0, -1)) === list
+    );
+  });
+}

package/src/utils/value-kinds.ts

@@ -43,3 +43,17 @@ export function atomicName(value: object): string | undefined {
   const tag = value instanceof Error ? 'Error' : toStringTag(value);
   return `${/^[AEIOU]/.test(tag) ? 'an' : 'a'} ${tag}`;
 }
+
+/** Whether `key` is an index of an array element. */
+const isIndexKey = (key: string): boolean =>
+  key !== '4294967295' && String(Number(key) >>> 0) === key;
+
+/**
+ * The own enumerable string keys of a collection (an Array, Map or Set) that
+ * are not its elements: what an instance of a subclass may hold besides
+ * them.
+ */
+export function extraKeys(collection: object): string[] {
+  const keys = Object.keys(collection);
+  return Array.isArray(collection) ? keys.filter((k) => !isIndexKey(k)) : keys;
+}

package/src/widgets/widget-def.ts

@@ -4,6 +4,7 @@
  */
 import { parseMacroArgs } from '../components/macros/macro-args';
 import type { MacroArgs } from '../registry';
+import { tokenizeMarkupTolerant } from '../markup/parse';
 
 /** A {widget} definition's name, then its `@` parameters. */
 export const WIDGET_PARAMETERS = [
@@ -36,20 +37,15 @@ export function parseWidgetDef(rawArgs: string): WidgetDef {
   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.
- */
-const WIDGET_DEFINITION = /\{widget\s+([^}]*)\}([\s\S]*?)\{\/widget\}/gi;
-
-/** `{@children}`, also with selectors such as `{.highlight @children}`. */
-const 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).
  */
 export function blockWidgetNames(
   passages: Iterable<{ name: string; tags?: string[]; content: string }>,
@@ -59,12 +55,28 @@ export function blockWidgetNames(
     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;
-      try {
-        names.push(parseWidgetDef(match[1]!).name);
-      } catch {
-        // The {widget} macro reports a definition it cannot read
+    // The open definitions: their arguments, and whether a slot was seen
+    const open: { rawArgs: string; isBlock: boolean }[] = [];
+    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(def.rawArgs).name);
+        } catch {
+          // The {widget} macro reports a definition it cannot read
+        }
+      } else if (
+        token.type === 'variable' &&
+        token.scope === 'local' &&
+        token.name === 'children' &&
+        open.length > 0
+      ) {
+        open[open.length - 1]!.isBlock = true;
       }
     }
   }

package/types/tooling.d.ts

@@ -100,7 +100,13 @@ export declare function defineMacro(config: MacroDefinition): void;
 export declare function getMacroRegistry(): MacroMetadata[];
 
 /** Variable type inferred from a StoryVariables/StoryTransients default value. */
-export type VarType = 'number' | 'string' | 'boolean' | 'array' | 'object';
+export type VarType =
+  | 'number'
+  | 'string'
+  | 'boolean'
+  | 'array'
+  | 'object'
+  | 'null';
 
 /** Inferred shape of a declared variable (or one of its object fields). */
 export interface FieldSchema {