@rohal12/spindle 0.59.11 → 0.59.12

package/package.json

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

package/src/components/macros/Computed.tsx

@@ -93,8 +93,6 @@ defineMacro({
     { name: 'expression', type: 'expression', required: true },
   ],
   render({ rawArgs }, ctx) {
-    const [mergedVars, mergedTemps, mergedLocals, mergedTrans] = ctx.merged!;
-
     let target: string;
     let expr: string;
     try {
@@ -133,13 +131,9 @@ defineMacro({
     }
 
     // The merged values only decide when to recompute; computeAndApply reads
-    // the current ones.
-    ctx.hooks.useLayoutEffect(compute, [
-      mergedVars,
-      mergedTemps,
-      mergedLocals,
-      mergedTrans,
-    ]);
+    // the current ones. The tuple is renewed with them and with the render
+    // counts, which rendered() / hasRendered() read.
+    ctx.hooks.useLayoutEffect(compute, [ctx.merged]);
 
     return null;
   },

package/src/components/macros/For.tsx

@@ -3,6 +3,7 @@ import { LocalsValuesContext } from '../../markup/render';
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
 import { stableKey } from '../../utils/stable-key';
+import { controlEditVersion } from '../../utils/control-edits';
 import type { ASTNode } from '../../markup/ast';
 import { checkVariableName } from '../../utils/namespace';
 import { LocalsScope } from './locals-scope';
@@ -76,6 +77,14 @@ function ForIteration({
   );
 }
 
+/** What {for} remembers of its iterations between renders. */
+interface IterationKeys {
+  contents: string[];
+  generations: number[];
+  next: number;
+  edits: number;
+}
+
 defineMacro({
   name: 'for',
   block: true,
@@ -88,6 +97,12 @@ defineMacro({
   ],
   render({ rawArgs, children = [] }, ctx) {
     const parentValues = useContext(LocalsValuesContext);
+    const keys = ctx.hooks.useRef<IterationKeys>({
+      contents: [],
+      generations: [],
+      next: 0,
+      edits: controlEditVersion(),
+    }).current;
 
     let loop: ReturnType<typeof loopArgs>;
     let list: unknown[];
@@ -112,9 +127,27 @@ defineMacro({
     }
 
     const { itemVar, indexVar } = loop;
+    // An iteration is remounted when its item's contents change, so mount-only
+    // macros run again for the new item (#45) -- unless the change is a
+    // reader editing the item through a control: remounting would drop the
+    // control's focus after the first keystroke.
+    const edited = controlEditVersion() !== keys.edits;
+    keys.edits = controlEditVersion();
+    const generations = list.map((item, i) => {
+      const contents = stableKey(item);
+      if (
+        keys.generations[i] === undefined ||
+        (contents !== keys.contents[i] && !edited)
+      ) {
+        keys.generations[i] = keys.next++;
+      }
+      keys.contents[i] = contents;
+      return keys.generations[i]!;
+    });
+    keys.contents.length = keys.generations.length = list.length;
     const content = list.map((item, i) => (
       <ForIteration
-        key={`${i}-${stableKey(item)}`}
+        key={`${i}-${generations[i]}`}
         parentValues={parentValues}
         itemVar={itemVar}
         itemValue={item}

package/src/components/macros/Widget.tsx

@@ -1,6 +1,4 @@
-import { registerWidget } from '../../widgets/widget-registry';
-import { astContainsChildren } from '../../widgets/ast-scanner';
-import { registerBlockMacro, type ASTNode } from '../../markup/ast';
+import { registerWidgetDef } from '../../widgets/register-widget-def';
 import { defineMacro } from '../../define-macro';
 import { checkVariableName } from '../../utils/namespace';
 import { MacroError } from './MacroError';
@@ -10,22 +8,6 @@ import {
   type WidgetDef,
 } from '../../widgets/widget-def';
 
-/**
- * Register the widget a definition declares, with its body. Widgets whose
- * body renders {@children} take a closing tag, so they are registered as
- * block macros too: passages parsed later nest their content. A parameter
- * that no namespace can hold throws (see registerWidget), registering
- * nothing.
- */
-export function registerWidgetDef(
-  { name, params }: WidgetDef,
-  body: ASTNode[],
-): void {
-  const isBlock = astContainsChildren(body);
-  registerWidget(name, body, params, isBlock);
-  if (isBlock) registerBlockMacro(name);
-}
-
 defineMacro({
   name: 'widget',
   block: true,

package/src/components/macros/WidgetInvocation.tsx

@@ -46,16 +46,9 @@ function WidgetContent({
 
   const childrenValue = invocationChildren?.length ? invocationChildren : null;
 
-  // Parameterized widgets always get their own local scope, even when invoked
-  // without arguments: missing parameters shadow outer locals as undefined.
-  if (params.length === 0) {
-    return (
-      <WidgetChildrenContext.Provider value={childrenValue}>
-        {renderNodes(body, renderOptions)}
-      </WidgetChildrenContext.Provider>
-    );
-  }
-
+  // Every widget gets its own local scope, even when it declares no
+  // parameters or is invoked without arguments: missing parameters shadow
+  // outer locals as undefined, and the body's own locals stay in the widget.
   const argExprs = rawArgs ? splitArgs(rawArgs) : [];
   const values: unknown[] = [];
 

package/src/define-macro.ts

@@ -10,6 +10,7 @@ import {
   useMemo,
 } from 'preact/hooks';
 import { useInterpolate } from './hooks/use-interpolate';
+import { noteControlEdit } from './utils/control-edits';
 import { useMergedLocals } from './hooks/use-merged-locals';
 import { useRenderOptions } from './hooks/use-render-options';
 import {
@@ -228,6 +229,7 @@ export function defineMacro<const P extends readonly ParameterDef[] = []>(
       // In program order, also when mutation code performs the input
       ctx.getValue = () => getByPath(readState().variables, segments);
       ctx.setValue = (value: unknown) => {
+        noteControlEdit();
         // The commit mutation code uses, which keeps the references among
         // variables: a write to a draft copies only the path written, and
         // other variables sharing the object would keep the old one.

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

@@ -10,7 +10,7 @@ const FOCUSABLE = [
   'textarea:not([disabled])',
   'iframe',
   '[contenteditable="true"]',
-  '[tabindex]:not([tabindex="-1"])',
+  '[tabindex]',
 ].join(',');
 
 /**
@@ -27,15 +27,57 @@ function isRendered(el: HTMLElement): boolean {
   return true;
 }
 
+/** The `tabindex` of `el` as an integer, or null when absent or invalid. */
+function tabIndexAttr(el: HTMLElement): number | null {
+  const raw = el.getAttribute('tabindex');
+  if (raw === null || !/^\s*[+-]?\d+\s*$/.test(raw)) return null;
+  return parseInt(raw, 10);
+}
+
+/**
+ * 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).
+ */
+function isTabStop(el: HTMLElement): boolean {
+  const tabIndex = tabIndexAttr(el);
+  if (tabIndex !== null && tabIndex < 0) return false;
+  if (el instanceof HTMLInputElement && el.type === 'radio' && el.name) {
+    const group = Array.from(
+      (
+        el.form ?? (el.getRootNode() as ParentNode)
+      ).querySelectorAll<HTMLInputElement>('input[type="radio"]'),
+    ).filter((r) => r.name === el.name && r.form === el.form && !r.disabled);
+    const stop = group.find((r) => r.checked) ?? group[0];
+    return el === stop;
+  }
+  return true;
+}
+
+/**
+ * The elements of `root` in the order Tab visits them: positive tabindexes
+ * first, ascending, then the others in document order.
+ */
 function focusables(root: HTMLElement): HTMLElement[] {
-  return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
+  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),
+      isRendered(el) &&
+      isTabStop(el),
   );
+  const positive = (el: HTMLElement) => Math.max(tabIndexAttr(el) ?? 0, 0);
+  // Array.prototype.sort is stable: equal tabindexes keep document order
+  return [
+    ...stops
+      .filter((el) => positive(el) > 0)
+      .sort((a, b) => positive(a) - positive(b)),
+    ...stops.filter((el) => positive(el) === 0),
+  ];
 }
 
 interface ModalEntry {

package/src/index.tsx

@@ -27,7 +27,7 @@ import {
 import { blockWidgetNames, parseWidgetDef } from './widgets/widget-def';
 import { parseMarkup } from './markup/parse';
 import { registerBlockMacro } from './markup/ast';
-import { registerWidgetDef } from './components/macros/Widget';
+import { registerWidgetDefinitions } from './widgets/register-widget-def';
 import { errorMessage } from './utils/error-message';
 import type { ASTNode } from './markup/ast';
 import './macros/register-builtins';
@@ -193,6 +193,14 @@ export function boot() {
   // Enter runtime phase — handlers registered from here on are cleaned on restart
   enterRuntimePhase();
 
+  // Pass 2: Full parse and register widgets from passages tagged "widget",
+  // before StoryInit runs so that it can invoke them
+  for (const [, passage] of storyData.passages) {
+    if (passage.tags.includes('widget')) {
+      registerWidgetDefinitions(parseMarkup(passage.content), passage.name);
+    }
+  }
+
   // Run StoryInit, restore the session if the page was refreshed, and fire
   // storyinit after all state is settled (defaults + StoryInit + session)
   initializeStory(loadSession(storyData.ifid));
@@ -205,27 +213,6 @@ export function boot() {
   ];
   if (markup.length > 0) stopWithErrors(markup);
 
-  // Pass 2: Full parse and register widgets from passages tagged "widget"
-  for (const [, passage] of storyData.passages) {
-    if (passage.tags.includes('widget')) {
-      const widgetAST = parseMarkup(passage.content);
-      for (const node of widgetAST) {
-        if (node.type === 'macro' && node.name === 'widget' && node.rawArgs) {
-          // Read and registered as the {widget} macro does
-          const def = parseWidgetDef(node.rawArgs);
-          try {
-            registerWidgetDef(def, node.children as ASTNode[]);
-          } catch (err) {
-            // As the {widget} macro refuses it: the others still register
-            console.error(
-              `spindle: widget "${def.name}" in passage "${passage.name}" was not registered: ${errorMessage(err)}`,
-            );
-          }
-        }
-      }
-    }
-  }
-
   // Reset action ID counters on every navigation (the passage remounts even
   // when its name is unchanged). Controls that stay mounted, e.g. in
   // StoryInterface, keep their IDs: allocation skips IDs still registered.

package/src/markup/render.tsx

@@ -348,7 +348,11 @@ function convertDomNode(
   return null;
 }
 
-/** Inline elements where block-level markdown (lists, headings) is invalid. */
+/**
+ * Elements whose content is phrasing content only, so block-level markdown
+ * (lists, headings, paragraphs) is invalid in them: inline elements, and
+ * block elements such as headings and buttons that only take inline children.
+ */
 const INLINE_ELEMENTS = new Set([
   'a',
   'abbr',
@@ -356,17 +360,27 @@ const INLINE_ELEMENTS = new Set([
   'bdi',
   'bdo',
   'br',
+  'button',
   'cite',
   'code',
   'data',
   'dfn',
   'em',
   'i',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
   'kbd',
   'label',
+  'legend',
   'mark',
   'meter',
+  'option',
   'output',
+  'p',
   'progress',
   'q',
   'rp',

package/src/saves/save-manager.ts

@@ -36,7 +36,16 @@ export function setSaveTitlePassage(content: string): void {
   saveTitlePassageContent = content;
 }
 
+/**
+ * The title of a save. The SaveTitle passage and title generators may draw
+ * random numbers; like the save hooks they must not advance the story's PRNG
+ * (see withoutDraws()).
+ */
 function generateTitle(payload: SavePayload): string {
+  return withoutDraws(() => generateTitleNow(payload));
+}
+
+function generateTitleNow(payload: SavePayload): string {
   // SaveTitle passage takes precedence
   if (saveTitlePassageContent) {
     try {

package/src/story-init.ts

@@ -1,6 +1,7 @@
 import { h, render } from 'preact';
 import { useStoryStore, recordStoryInitState, missingPassage } from './store';
 import { parseMarkup } from './markup/parse';
+import { registerWidgetDefinitions } from './widgets/register-widget-def';
 import { renderNodes } from './markup/render';
 import { setSaveTitlePassage } from './saves/save-manager';
 import { emit } from './event-emitter';
@@ -35,6 +36,9 @@ export function executeStoryInit() {
   const storyInit = state.storyData.passages.get('StoryInit');
   if (storyInit) {
     const ast = parseMarkup(storyInit.content);
+    // Its own widgets are usable from the passage itself: the macros render
+    // before the {widget} definitions' effects run.
+    registerWidgetDefinitions(ast, 'StoryInit');
 
     // Mount into a persistent hidden container. It stays mounted until the
     // next execution (restart) — this lets async effects (useEffect,

package/src/utils/control-edits.ts

@@ -0,0 +1,15 @@
+/**
+ * Counts 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.
+ */
+let version = 0;
+
+export function noteControlEdit(): void {
+  version++;
+}
+
+export function controlEditVersion(): number {
+  return version;
+}

package/src/widgets/register-widget-def.ts

@@ -0,0 +1,44 @@
+import { registerWidget } from './widget-registry';
+import { astContainsChildren } from './ast-scanner';
+import { registerBlockMacro, type ASTNode } from '../markup/ast';
+import { errorMessage } from '../utils/error-message';
+import { parseWidgetDef, type WidgetDef } from './widget-def';
+
+/**
+ * Register the widget a definition declares, with its body. Widgets whose
+ * body renders {@children} take a closing tag, so they are registered as
+ * block macros too: passages parsed later nest their content. A parameter
+ * that no namespace can hold throws (see registerWidget), registering
+ * nothing.
+ */
+export function registerWidgetDef(
+  { name, params }: WidgetDef,
+  body: ASTNode[],
+): void {
+  const isBlock = astContainsChildren(body);
+  registerWidget(name, body, params, isBlock);
+  if (isBlock) registerBlockMacro(name);
+}
+
+/**
+ * Register the widgets `nodes` (a passage's markup) define at its top level,
+ * as the {widget} macro does when it renders. A widget that fails to register
+ * is reported; the others still register.
+ */
+export function registerWidgetDefinitions(
+  nodes: ASTNode[],
+  passageName: string,
+): void {
+  for (const node of nodes) {
+    if (node.type === 'macro' && node.name === 'widget' && node.rawArgs) {
+      const def = parseWidgetDef(node.rawArgs);
+      try {
+        registerWidgetDef(def, node.children as ASTNode[]);
+      } catch (err) {
+        console.error(
+          `spindle: widget "${def.name}" in passage "${passageName}" was not registered: ${errorMessage(err)}`,
+        );
+      }
+    }
+  }
+}