@rohal12/spindle 0.59.9 → 0.59.11

package/package.json

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

package/src/components/macros/If.tsx

@@ -1,8 +1,7 @@
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
 import type { Branch } from '../../markup/ast';
-import { selectBranch } from './branches';
-import { wrapContent } from './display';
+import { selectBranch, renderBranch } from './branches';
 
 /**
  * The {if}/{elseif}/{else} branch whose condition holds, else the {else}
@@ -37,11 +36,7 @@ defineMacro({
       );
     }
     if (!branch) return null;
-    return wrapContent(
-      ctx.resolve!(branch.className),
-      ctx.resolve!(branch.id),
-      ctx.renderNodes(branch.children),
-    );
+    return renderBranch(branch, ctx);
   },
   text({ branches = [] }, ctx) {
     const branch = selectIfBranch(branches, ctx.evaluate);

package/src/components/macros/PassageDisplay.tsx

@@ -1,6 +1,15 @@
-import { useRef, useEffect, useCallback, useState } from 'preact/hooks';
-import { useStoryStore } from '../../store';
-import { useStoryFields } from '../../hooks/use-story-fields';
+import {
+  useRef,
+  useEffect,
+  useLayoutEffect,
+  useCallback,
+  useState,
+} from 'preact/hooks';
+import { useStoryStore, type StoryState } from '../../store';
+import {
+  useStoryFields,
+  FrozenStateContext,
+} from '../../hooks/use-story-fields';
 import { Passage, renderPassageContent } from '../Passage';
 import { defineMacro } from '../../define-macro';
 import { resolveTransition, type ResolvedTransition } from '../../transition';
@@ -126,6 +135,13 @@ defineMacro({
     // Track previous history length to detect restart/load
     const prevHistoryLenRef = useRef(0);
 
+    const displayedId = displayed.id;
+    const isOutgoing = useCallback(
+      (state: StoryState) => state.navigationId !== displayedId,
+      [displayedId],
+    );
+    const lastElement = useRef<preact.VNode | null>(null);
+
     // Container ref for snapshot insertion
     const containerRef = useRef<HTMLDivElement>(null);
 
@@ -265,6 +281,22 @@ defineMacro({
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [navigationId]);
 
+    // A new passage opens at its beginning, not where the previous one was
+    // scrolled to (#354). The page keeps its position on first display
+    // (a refresh restores it) and when the beginning is already in view.
+    const shownId = displayedPassage && !renderDeferred ? displayed.id : null;
+    const lastShownId = useRef(shownId);
+    useLayoutEffect(() => {
+      if (shownId === null) return; // between passages of a transition
+      const previous = lastShownId.current;
+      lastShownId.current = shownId;
+      if (previous === null || previous === shownId) return;
+      const el = containerRef.current?.querySelector('.passage');
+      if (el && el.getBoundingClientRect().top < 0) {
+        el.scrollIntoView?.({ block: 'start' });
+      }
+    }, [shownId]);
+
     // When render is deferred, show StoryLoading passage or nothing
     const effectivePassage = renderDeferred
       ? (storyData?.passages.get('StoryLoading') ?? null)
@@ -282,6 +314,23 @@ defineMacro({
 
     const readyPassage = storyData?.passages.get('PassageReady');
 
+    // Between a navigation and the commit of its passage, the old passage is
+    // still mounted. It must not execute against the destination's state, so
+    // it keeps the element and the state it last rendered with (#352).
+    const outgoing = !renderDeferred && displayed.id !== navigationId;
+    const passageElement =
+      outgoing && lastElement.current
+        ? lastElement.current
+        : effectivePassage && (
+            <Passage
+              passage={effectivePassage}
+              key={renderDeferred ? 'loading' : `nav-${displayed.id}`}
+              dataTransition={renderDeferred ? 'none' : resolvedTypeRef.current}
+              navigationId={renderDeferred ? undefined : displayed.id}
+            />
+          );
+    lastElement.current = passageElement || null;
+
     return (
       <div
         id={ctx.id ?? 'story'}
@@ -299,13 +348,10 @@ defineMacro({
           class="passage-container"
           ref={containerRef}
         >
-          {effectivePassage && (
-            <Passage
-              passage={effectivePassage}
-              key={renderDeferred ? 'loading' : `nav-${displayed.id}`}
-              dataTransition={renderDeferred ? 'none' : resolvedTypeRef.current}
-              navigationId={renderDeferred ? undefined : displayed.id}
-            />
+          {passageElement && (
+            <FrozenStateContext.Provider value={isOutgoing}>
+              {passageElement}
+            </FrozenStateContext.Provider>
           )}
         </div>
       </div>

package/src/components/macros/SaveManager.tsx

@@ -345,12 +345,15 @@ export function SaveManagerContent() {
                 class="playthrough-group"
                 key={group.playthrough.id}
               >
-                <div
+                <button
+                  type="button"
                   class="playthrough-header"
+                  aria-expanded={!isCollapsed}
                   onClick={() => toggleCollapse(group.playthrough.id)}
                 >
                   <span
                     class={`playthrough-chevron ${isCollapsed ? '' : 'open'}`}
+                    aria-hidden="true"
                   >
                     ▶
                   </span>
@@ -361,7 +364,7 @@ export function SaveManagerContent() {
                   <span class="playthrough-date">
                     {formatDate(group.playthrough.createdAt)}
                   </span>
-                </div>
+                </button>
 
                 {!isCollapsed && (
                   <div class="playthrough-saves">

package/src/components/macros/Switch.tsx

@@ -1,7 +1,7 @@
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
 import type { Branch } from '../../markup/ast';
-import { selectBranch } from './branches';
+import { selectBranch, renderBranch } from './branches';
 
 /**
  * The first {case} branch whose value equals `value`, else the {default}
@@ -20,6 +20,7 @@ defineMacro({
   name: 'switch',
   subMacros: ['case', 'default'],
   parameters: [{ name: 'expression', type: 'expression', required: true }],
+  interpolate: true,
   merged: true,
   render({ rawArgs, branches = [] }, ctx) {
     let switchValue: unknown;
@@ -46,7 +47,8 @@ defineMacro({
       );
     }
 
-    return branch && <>{ctx.renderNodes(branch.children)}</>;
+    if (!branch) return null;
+    return renderBranch(branch, ctx);
   },
   text({ rawArgs, branches = [] }, ctx) {
     const branch = selectCase(ctx.evaluate(rawArgs), branches, ctx.evaluate);

package/src/components/macros/WidgetInvocation.tsx

@@ -7,6 +7,8 @@ import { splitArgs } from './arg-utils';
 import { createNamespace } from '../../utils/namespace';
 import { useRenderOptions } from '../../hooks/use-render-options';
 import { LocalsScope } from './locals-scope';
+import { useInterpolate } from '../../hooks/use-interpolate';
+import { wrapContent } from './display';
 
 export { splitArgs };
 
@@ -15,9 +17,23 @@ interface WidgetInvocationProps {
   params: string[];
   rawArgs?: string;
   invocationChildren?: ASTNode[];
+  className?: string;
+  id?: string;
 }
 
-export function WidgetInvocation({
+export function WidgetInvocation(props: WidgetInvocationProps) {
+  const resolve = useInterpolate();
+  // Invocation selectors (`{.badge#hero Stats}`) need an element to land on;
+  // dynamic ones (`{.{$theme} Stats}`) follow the state like a built-in
+  // macro's.
+  return wrapContent(
+    resolve(props.className),
+    resolve(props.id),
+    <WidgetContent {...props} />,
+  );
+}
+
+function WidgetContent({
   body,
   params,
   rawArgs,

package/src/components/macros/branches.ts

@@ -1,4 +1,7 @@
+import type { ComponentChildren, VNode } from 'preact';
 import type { Branch } from '../../markup/ast';
+import type { MacroContext } from '../../define-macro';
+import { wrapContent } from './display';
 
 /**
  * The branch a conditional block ({if}, {switch}) shows: the first of
@@ -16,3 +19,20 @@ export function selectBranch(
   }
   return fallback;
 }
+
+/**
+ * A selected branch's content, in a wrapper if the branch has CSS selectors
+ * (`{.hot#id case 1}`). The macro must be defined with `interpolate`.
+ */
+export function renderBranch(
+  branch: Branch,
+  ctx: Pick<MacroContext, 'resolve'> & {
+    renderNodes: (nodes: Branch['children']) => ComponentChildren;
+  },
+): VNode<any> {
+  return wrapContent(
+    ctx.resolve!(branch.className),
+    ctx.resolve!(branch.id),
+    ctx.renderNodes(branch.children),
+  );
+}

package/src/components/macros/detached-body.tsx

@@ -10,16 +10,20 @@ import {
 } from '../../markup/render';
 import type { ASTNode } from '../../markup/ast';
 import { useRenderOptions } from '../../hooks/use-render-options';
+import { FrozenStateContext } from '../../hooks/use-story-fields';
 import { liveLocalsView } from '../../utils/live-locals';
 import { runWithCommittedMutations } from '../../execute-mutation';
 import { RepeatContext } from './Repeat';
 import { DialogCloseContext } from '../PassageDialog';
 
+const frozenAlways = () => true;
+
 /**
  * Return a function that runs a macro body once, outside the passage tree:
  * it renders `children` into a detached node, so the body's macros ({set},
  * {if}, {goto}, ...) fire their side effects through the normal Preact
- * pipeline. Used by {button} and {link} on click. The body stays mounted
+ * pipeline. Used by {button} and {link} on click. The body's state is frozen
+ * once it has rendered, so it runs once per click. It stays mounted
  * until the owning macro unmounts (its passage changes, say), so work it
  * starts in an effect, such as the timer of a {timed} or {repeat}, can
  * finish; the passage leaving cancels it.
@@ -58,21 +62,23 @@ export function useDetachedBody(): (children: ASTNode[]) => void {
     const locals = liveLocalsView(updater.getValues);
     const container = document.createElement('div');
     render(
-      <LocalsUpdateContext.Provider value={updater}>
-        <LocalsValuesContext.Provider value={locals}>
-          <NobrContext.Provider value={nobr}>
-            <InlineContext.Provider value={inline}>
-              <WidgetChildrenContext.Provider value={widgetChildren}>
-                <RepeatContext.Provider value={repeat}>
-                  <DialogCloseContext.Provider value={closeDialog}>
-                    {renderNodes(children, { nobr, inline, locals })}
-                  </DialogCloseContext.Provider>
-                </RepeatContext.Provider>
-              </WidgetChildrenContext.Provider>
-            </InlineContext.Provider>
-          </NobrContext.Provider>
-        </LocalsValuesContext.Provider>
-      </LocalsUpdateContext.Provider>,
+      <FrozenStateContext.Provider value={frozenAlways}>
+        <LocalsUpdateContext.Provider value={updater}>
+          <LocalsValuesContext.Provider value={locals}>
+            <NobrContext.Provider value={nobr}>
+              <InlineContext.Provider value={inline}>
+                <WidgetChildrenContext.Provider value={widgetChildren}>
+                  <RepeatContext.Provider value={repeat}>
+                    <DialogCloseContext.Provider value={closeDialog}>
+                      {renderNodes(children, { nobr, inline, locals })}
+                    </DialogCloseContext.Provider>
+                  </RepeatContext.Provider>
+                </WidgetChildrenContext.Provider>
+              </InlineContext.Provider>
+            </NobrContext.Provider>
+          </LocalsValuesContext.Provider>
+        </LocalsUpdateContext.Provider>
+      </FrozenStateContext.Provider>,
       container,
     );
     mounted.current.push(container);

package/src/components/macros/input-macro.ts

@@ -59,14 +59,29 @@ export function defineInputMacro(
         perform: (v) => ctx.setValue!(toValue(v)),
       });
 
+      // What the reader last typed. A number input reports an unfinished
+      // number ("-", "2e") as an empty value, so the text is kept for as
+      // long as it still converts to the variable's value, instead of being
+      // replaced by that value on every keystroke (#353).
+      const typed = ctx.hooks.useRef<string | null>(null);
+      const shown =
+        typed.current !== null &&
+        toValue(typed.current) === ctx.value &&
+        type === 'number'
+          ? typed.current
+          : display(ctx.value);
+
       return h(type ? 'input' : 'textarea', {
         type,
         id: ctx.id,
         class: ctx.cls,
-        value: display(ctx.value),
+        value: shown,
         placeholder,
-        onInput: (e: Event) =>
-          ctx.setValue!(toValue((e.target as HTMLInputElement).value)),
+        onInput: (e: Event) => {
+          const text = (e.target as HTMLInputElement).value;
+          typed.current = text;
+          ctx.setValue!(toValue(text));
+        },
       });
     },
   });

package/src/hooks/use-merged-locals.ts

@@ -12,14 +12,17 @@ export function useMergedLocals(): readonly [
   Record<string, unknown>,
   Record<string, unknown>,
 ] {
-  const { variables, temporary, transient } = useStoryFields(
+  // renderCounts is read by rendered()/hasRendered() inside expressions, so
+  // it re-renders them (and renews the tuple) when an inclusion mounts.
+  const { variables, temporary, transient, renderCounts } = useStoryFields(
     'variables',
     'temporary',
     'transient',
+    'renderCounts',
   );
   const localsValues = useContext(LocalsValuesContext);
 
   return useMemo(() => {
     return [variables, temporary, localsValues, transient] as const;
-  }, [variables, temporary, localsValues, transient]);
+  }, [variables, temporary, localsValues, transient, renderCounts]);
 }

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

@@ -29,7 +29,12 @@ function isRendered(el: HTMLElement): boolean {
 
 function focusables(root: HTMLElement): HTMLElement[] {
   return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
-    (el) => !el.hidden && !el.closest('[hidden], [inert]') && isRendered(el),
+    (el) =>
+      !el.hidden &&
+      !el.closest('[hidden], [inert]') &&
+      // Also covers controls disabled by a <fieldset disabled> ancestor
+      !el.matches(':disabled') &&
+      isRendered(el),
   );
 }
 

package/src/hooks/use-story-fields.ts

@@ -1,7 +1,20 @@
-import { useRef } from 'preact/hooks';
+import { createContext } from 'preact';
+import { useContext, useRef } from 'preact/hooks';
 import { shallow } from 'zustand/vanilla/shallow';
 import { useStoryStore, type StoryState } from '../store';
 
+/**
+ * Tells the components below when to keep the state they last rendered with,
+ * given the store's current state: an owner (a click body, see
+ * useDetachedBody; a passage on its way out, see PassageDisplay) provides it
+ * so that a branch skipped earlier cannot run against later state (#351,
+ * #352). It runs inside the store's own notification, before the owner could
+ * re-render, which is why it is a predicate and not a flag.
+ */
+export const FrozenStateContext = createContext<
+  ((state: StoryState) => boolean) | null
+>(null);
+
 /**
  * Story state fields `keys`, re-rendering when any of them changes (as one
  * useStoryStore() selector per field would). The result keeps its identity
@@ -11,7 +24,9 @@ export function useStoryFields<K extends keyof StoryState>(
   ...keys: K[]
 ): Pick<StoryState, K> {
   const prev = useRef<Pick<StoryState, K>>();
+  const freeze = useContext(FrozenStateContext);
   return useStoryStore((s) => {
+    if (prev.current && freeze?.(s)) return prev.current;
     const next = {} as Pick<StoryState, K>;
     for (const key of keys) next[key] = s[key];
     return shallow(prev.current, next) ? prev.current! : (prev.current = next);

package/src/js-lexer.ts

@@ -128,7 +128,7 @@ const OPERAND_ENDS: ReadonlySet<TokenType> = new Set([
  * whether a `{` opens a block or an object literal, which decides whether a
  * `/` after its `}` opens a regex and a `%` a transient: after the `:` of a
  * conditional it opens an object literal (`a ? b : {} / 2`), not a block as
- * after a label; after a block's `}` it opens another block (`{}{} %n = 1`),
+ * after a label, and a `function` or `class` there is an expression; after a block's `}` it opens another block (`{}{} %n = 1`),
  * and so it does on a new line after a statement (`p⏎{} %n = 1`).
  */
 const SigilParser = class extends (Parser as unknown as Base) {
@@ -146,6 +146,8 @@ const SigilParser = class extends (Parser as unknown as Base) {
   closedBlock = false;
   /** The value of the token before the one being finished. */
   prevValue: unknown;
+  /** The type of the token before the last one. */
+  typeBeforeLast: TokenType = tt.eof;
   /** Look ahead after a `%name` starting a line (off in look-aheads). */
   lookahead = true;
   /**
@@ -222,6 +224,21 @@ const SigilParser = class extends (Parser as unknown as Base) {
         (prevType === tt.dot || prevType === tt.questionDot)) ||
       ((type === tt._function || type === tt._class) &&
         notABody(self.input, self.pos));
+    // acorn takes a `function` or `class` for a statement's (whose `}` a
+    // regex may follow) after the `:` of a conditional, and `async function`
+    // always. Both are expressions where an operand is (`a ? b : class {} / 2`,
+    // `x = async function () {} / 2`): read them as after what comes before.
+    if (!property && (type === tt._function || type === tt._class)) {
+      const afterAsync =
+        type === tt._function &&
+        prevType === tt.name &&
+        this.prevValue === 'async' &&
+        !this.breakHere;
+      const before = afterAsync ? this.typeBeforeLast : prevType;
+      self.type =
+        before === tt.colon && this.colonEndsTernary ? tt.parenL : before;
+    }
+    this.typeBeforeLast = prevType;
     // @ts-expect-error acorn internals
     super.finishToken(property ? tt.name : type, value);
     // A variable named `of` (`const of of list`): acorn takes it for the

package/src/markup/render.tsx

@@ -524,25 +524,43 @@ function useDirectAttributes(
   return direct.length > 0 ? elementRef : undefined;
 }
 
+const decodedText = new Map<string, string>();
 const decodedAttributeText = new Map<string, string>();
 
 /**
- * Decode character references (`&amp;`, `&#123;`) in attribute text the way
- * the HTML parser decodes an attribute value, by letting it parse one.
+ * Decode character references (`&amp;`, `&#123;`) in `text` the way the HTML
+ * parser decodes them, by letting it parse them: in an attribute value, or
+ * else in element text.
  */
-function decodeAttributeText(text: string): string {
+function decodeReferences(
+  text: string,
+  cache: Map<string, string>,
+  parse: (text: string) => string | null,
+): string {
   if (!text.includes('&')) return text;
-  let decoded = decodedAttributeText.get(text);
+  let decoded = cache.get(text);
   if (decoded === undefined) {
-    const html = `<i title="${text.replace(/"/g, '&quot;')}"></i>`;
-    decoded =
-      (parseHtmlInert(html).firstChild as Element).getAttribute('title') ??
-      text;
-    decodedAttributeText.set(text, decoded);
+    decoded = parse(text) ?? text;
+    cache.set(text, decoded);
   }
   return decoded;
 }
 
+function decodeAttributeText(text: string): string {
+  return decodeReferences(text, decodedAttributeText, (t) => {
+    const html = `<i title="${t.replace(/"/g, '&quot;')}"></i>`;
+    return (parseHtmlInert(html).firstChild as Element).getAttribute('title');
+  });
+}
+
+/** Literal text outside markdown (preformatted and SVG elements). */
+function decodeText(text: string): string {
+  return decodeReferences(text, decodedText, (t) => {
+    const html = `<i>${t.replace(/</g, '&lt;')}</i>`;
+    return parseHtmlInert(html).firstChild!.textContent;
+  });
+}
+
 /** A `{` and a sigil starting a reference, in a code attribute. */
 const SIGIL_REFERENCE = /\{[$_@%]\w/;
 
@@ -679,14 +697,21 @@ function nodeKey(node: ASTNode): string {
 function renderMacro(node: MacroNode, key: string) {
   if (isSubMacro(node.name)) return null;
 
+  // What an invocation passes on to a widget and to a built-in macro alike
+  const invocation = {
+    rawArgs: node.rawArgs,
+    className: node.className,
+    id: node.id,
+  };
+
   const widget = getWidget(node.name);
   if (widget) {
     return (
       <WidgetInvocation
         key={key}
+        {...invocation}
         body={widget.body}
         params={widget.params}
-        rawArgs={node.rawArgs}
         invocationChildren={node.children}
       />
     );
@@ -697,9 +722,7 @@ function renderMacro(node: MacroNode, key: string) {
     return (
       <Component
         key={key}
-        rawArgs={node.rawArgs}
-        className={node.className}
-        id={node.id}
+        {...invocation}
         children={node.children}
         branches={node.branches}
       />
@@ -720,7 +743,8 @@ function renderMacro(node: MacroNode, key: string) {
  * Render a non-text AST node to a Preact element.
  */
 function renderSingleNode(node: ASTNode): preact.ComponentChildren {
-  if (node.type === 'text') return node.value;
+  // Authored text outside markdown still has its character references decoded
+  if (node.type === 'text') return decodeText(node.value);
   const key = nodeKey(node);
   switch (node.type) {
     case 'variable':

package/src/markup/spindle.peggy

@@ -233,6 +233,7 @@ Content
 Item
   = TextRun
   / Escape
+  / Comment
   / LinkLexeme
   / HtmlElement
   / VoidCloser
@@ -291,6 +292,7 @@ Tokens
 TokenItem
   = TextRun
   / Escape
+  / Comment
   / LinkLexeme
   / &{ return !textMode; } tag:HtmlOpen { return tag; }
   / &{ return !textMode; } tag:HtmlClose { return VOID_TAGS.has(tag.lower) ? null : tag; }
@@ -317,6 +319,15 @@ Here
 TextRun
   = value:$[^\\{[<]+ { return lexeme('text', location(), { value }); }
 
+/**
+ * A closed HTML comment, opaque: its tags and macros are not markup, and
+ * rendering drops it. (An unclosed `<!--` is ordinary text.)
+ */
+Comment
+  = value:$("<!--" (">" / "->" / (!"-->" .)* "-->")) {
+      return lexeme('text', location(), { value });
+    }
+
 /**
  * A backslash run. Before a brace, an odd run escapes it; in text mode the
  * run is also paired up (`\\` is one backslash), in passage text markdown