@rohal12/spindle 0.52.4 → 0.52.6

package/src/components/macros/WidgetInvocation.tsx

@@ -1,28 +1,12 @@
-import {
-  useContext,
-  useState,
-  useCallback,
-  useRef,
-  useMemo,
-} from 'preact/hooks';
-import {
-  LocalsValuesContext,
-  LocalsUpdateContext,
-  NobrContext,
-  InlineContext,
-  WidgetChildrenContext,
-  RawTextContext,
-  renderNodes,
-} from '../../markup/render';
+import { useMemo } from 'preact/hooks';
+import { WidgetChildrenContext, renderNodes } from '../../markup/render';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
 import { evaluate } from '../../expression';
 import type { ASTNode } from '../../markup/ast';
 import { splitArgs } from './arg-utils';
-import {
-  checkVariableName,
-  createNamespace,
-  withEntry,
-} from '../../utils/namespace';
+import { createNamespace } from '../../utils/namespace';
+import { useRenderOptions } from '../../hooks/use-render-options';
+import { LocalsScope } from './locals-scope';
 
 export { splitArgs };
 
@@ -33,60 +17,14 @@ interface WidgetInvocationProps {
   invocationChildren?: ASTNode[];
 }
 
-function WidgetBody({
-  body,
-  parentValues,
-  ownKeys,
-}: {
-  body: ASTNode[];
-  parentValues: Record<string, unknown>;
-  ownKeys: Record<string, unknown>;
-}) {
-  const nobr = useContext(NobrContext);
-  const inline = useContext(InlineContext);
-  const raw = useContext(RawTextContext);
-  const [localMutations, setLocalMutations] = useState<Record<string, unknown>>(
-    {},
-  );
-
-  const localState = useMemo(
-    () => createNamespace(parentValues, ownKeys, localMutations),
-    [parentValues, ownKeys, localMutations],
-  );
-
-  const valuesRef = useRef(localState);
-  valuesRef.current = localState;
-
-  const getValues = useCallback(() => valuesRef.current, []);
-  const update = useCallback((key: string, value: unknown) => {
-    // Apply synchronously so later macros in the same render pass (e.g. a
-    // second {set}) read the new value via getValues(); the state update
-    // then re-renders consumers of LocalsValuesContext.
-    checkVariableName(key, `@${key}`);
-    valuesRef.current = withEntry(valuesRef.current, key, value);
-    setLocalMutations((prev) => ({ ...prev, [key]: value }));
-  }, []);
-  const updater = useMemo(() => ({ update, getValues }), [update, getValues]);
-
-  return (
-    <LocalsUpdateContext.Provider value={updater}>
-      <LocalsValuesContext.Provider value={localState}>
-        {renderNodes(body, { nobr, inline, raw, locals: localState })}
-      </LocalsValuesContext.Provider>
-    </LocalsUpdateContext.Provider>
-  );
-}
-
 export function WidgetInvocation({
   body,
   params,
   rawArgs,
   invocationChildren,
 }: WidgetInvocationProps) {
-  const parentValues = useContext(LocalsValuesContext);
-  const nobr = useContext(NobrContext);
-  const inline = useContext(InlineContext);
-  const raw = useContext(RawTextContext);
+  const renderOptions = useRenderOptions();
+  const parentValues = renderOptions.locals;
   const [mergedVars, mergedTemps, mergedLocals, mergedTrans] =
     useMergedLocals();
 
@@ -97,7 +35,7 @@ export function WidgetInvocation({
   if (params.length === 0) {
     return (
       <WidgetChildrenContext.Provider value={childrenValue}>
-        {renderNodes(body, { nobr, inline, raw, locals: parentValues })}
+        {renderNodes(body, renderOptions)}
       </WidgetChildrenContext.Provider>
     );
   }
@@ -137,7 +75,7 @@ export function WidgetInvocation({
 
   return (
     <WidgetChildrenContext.Provider value={childrenValue}>
-      <WidgetBody
+      <LocalsScope
         body={body}
         parentValues={parentValues}
         ownKeys={ownKeys}

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

@@ -9,6 +9,7 @@ import {
   WidgetChildrenContext,
 } from '../../markup/render';
 import type { ASTNode } from '../../markup/ast';
+import { useRenderOptions } from '../../hooks/use-render-options';
 import { liveLocalsView } from '../../utils/live-locals';
 import { runWithCommittedMutations } from '../../execute-mutation';
 import { RepeatContext } from './Repeat';
@@ -35,8 +36,7 @@ import { DialogCloseContext } from '../PassageDialog';
  */
 export function useDetachedBody(): (children: ASTNode[]) => void {
   const updater = useContext(LocalsUpdateContext);
-  const nobr = useContext(NobrContext);
-  const inline = useContext(InlineContext);
+  const { nobr, inline } = useRenderOptions();
   const widgetChildren = useContext(WidgetChildrenContext);
   const repeat = useContext(RepeatContext);
   const closeDialog = useContext(DialogCloseContext);

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

@@ -0,0 +1,48 @@
+import { h } from 'preact';
+import { defineMacro } from '../../define-macro';
+
+/**
+ * Define a text input macro, `{name $var "placeholder"}`: an `<input>` of
+ * `type` (or, without one, a `<textarea>`) bound to the story variable.
+ * `toValue` turns what the reader types, or an automation action's value
+ * (`undefined` when it has none), into the variable's value: by default,
+ * the text.
+ */
+export function defineInputMacro(
+  name: 'textbox' | 'numberbox' | 'textarea',
+  type?: 'text' | 'number',
+  toValue = (input: unknown): unknown =>
+    input !== undefined ? String(input) : '',
+): void {
+  defineMacro({
+    name,
+    storeVar: true,
+    parameters: [
+      { name: 'variable', type: 'variable', required: true },
+      { name: 'placeholder', type: 'string' },
+    ],
+    render(_props, ctx) {
+      const placeholder = ctx.args.placeholder ?? '';
+
+      ctx.useAction({
+        type: name,
+        key: `$${ctx.varName}`,
+        authorId: ctx.id,
+        label: placeholder || ctx.varName!,
+        variable: ctx.varName,
+        value: ctx.value,
+        perform: (v) => ctx.setValue!(toValue(v)),
+      });
+
+      return h(type ? 'input' : 'textarea', {
+        type,
+        id: ctx.id,
+        class: ctx.cls,
+        value: ctx.value == null ? '' : String(ctx.value),
+        placeholder,
+        onInput: (e: Event) =>
+          ctx.setValue!(toValue((e.target as HTMLInputElement).value)),
+      });
+    },
+  });
+}

package/src/components/macros/locals-scope.tsx

@@ -0,0 +1,60 @@
+import { useState, useCallback, useRef, useMemo } from 'preact/hooks';
+import {
+  LocalsValuesContext,
+  LocalsUpdateContext,
+  renderNodes,
+} from '../../markup/render';
+import type { ASTNode } from '../../markup/ast';
+import { useRenderOptions } from '../../hooks/use-render-options';
+import {
+  checkVariableName,
+  createNamespace,
+  withEntry,
+} from '../../utils/namespace';
+
+/**
+ * Render `body` in a new locals scope: the locals of `parentValues`, with
+ * `ownKeys` (an iteration's loop variables, a widget's parameters) on top.
+ * Locals the body assigns are kept in this scope.
+ */
+export function LocalsScope({
+  body,
+  parentValues,
+  ownKeys,
+}: {
+  body: ASTNode[];
+  parentValues: Record<string, unknown>;
+  ownKeys: Record<string, unknown>;
+}) {
+  const options = useRenderOptions();
+  const [localMutations, setLocalMutations] = useState<Record<string, unknown>>(
+    {},
+  );
+
+  const localState = useMemo(
+    () => createNamespace(parentValues, ownKeys, localMutations),
+    [parentValues, ownKeys, localMutations],
+  );
+
+  const valuesRef = useRef(localState);
+  valuesRef.current = localState;
+
+  const getValues = useCallback(() => valuesRef.current, []);
+  const update = useCallback((key: string, value: unknown) => {
+    // Apply synchronously so later macros in the same render pass (e.g. a
+    // second {set}) read the new value via getValues(); the state update
+    // then re-renders consumers of LocalsValuesContext.
+    checkVariableName(key, `@${key}`);
+    valuesRef.current = withEntry(valuesRef.current, key, value);
+    setLocalMutations((prev) => ({ ...prev, [key]: value }));
+  }, []);
+  const updater = useMemo(() => ({ update, getValues }), [update, getValues]);
+
+  return (
+    <LocalsUpdateContext.Provider value={updater}>
+      <LocalsValuesContext.Provider value={localState}>
+        {renderNodes(body, { ...options, locals: localState })}
+      </LocalsValuesContext.Provider>
+    </LocalsUpdateContext.Provider>
+  );
+}

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

@@ -0,0 +1,280 @@
+/**
+ * The macro argument layer: reads a macro's raw argument text into the
+ * parameters its definition declares (see ParameterDef), so every macro
+ * splits and unquotes its arguments the same way. defineMacro() passes the
+ * result to the macro as `ctx.args`.
+ *
+ * Arguments are read in groups, split at `separator` parameters. A group's
+ * `flag` parameters are taken off its start or end first. Its last
+ * `expression` or `text` parameter (without one, its last parameter) reads
+ * the text the others leave; each parameter before it reads one term from
+ * the start, and each after it one term from the end. Terms are separated by
+ * whitespace outside literals and brackets (see arg-utils.ts), and a term
+ * that follows an operator belongs to the expression before it. A parameter
+ * with nothing to read is unset (a flag or separator is false, options are
+ * empty).
+ */
+import { parseDelay } from '../../utils/parse-delay';
+import type { MacroArgs, ParameterDef } from '../../registry';
+import {
+  endsWithOperator,
+  isWhitespace,
+  readQuoted,
+  readWholeQuoted,
+  stripLooseQuotes,
+  topLevelIndices,
+} from './arg-utils';
+
+type Span = [start: number, end: number];
+
+/** The terms of `src`: the runs of text between its depth-0 whitespace. */
+function terms(src: string): Span[] {
+  const spans: Span[] = [];
+  let start = 0;
+  for (const i of [...topLevelIndices(src, isWhitespace), src.length]) {
+    if (i > start) spans.push([start, i]);
+    start = i + 1;
+  }
+  return spans;
+}
+
+const slice = (src: string, [start, end]: Span) => src.slice(start, end);
+
+/**
+ * The value of a `text` argument: one quoted string, or the text with any
+ * loose quotes stripped (`"Red` → `Red`).
+ */
+export function readText(src: string): string {
+  return readWholeQuoted(src) ?? stripLooseQuotes(src);
+}
+
+function readValue(param: ParameterDef, src: string): unknown {
+  switch (param.type) {
+    case 'string':
+      return readWholeQuoted(src) ?? undefined;
+    case 'text':
+      return readText(src);
+    case 'names':
+      return src.split(',').map((name) => name.trim());
+    case 'delay':
+      return parseDelay(src);
+    case 'number':
+      return Number(src);
+    case 'options':
+      return readOptions(param.parameters ?? [], src);
+    default:
+      return src;
+  }
+}
+
+function unset(param: ParameterDef): unknown {
+  if (param.type === 'flag' || param.type === 'separator') return false;
+  return param.type === 'options' ? {} : undefined;
+}
+
+const WORD_RE = /\w+/y;
+const DIGITS_RE = /\d+/y;
+
+/** Match the sticky regex `re` at `pos`, returning the matched text. */
+function matchAt(re: RegExp, src: string, pos: number): string | null {
+  re.lastIndex = pos;
+  return re.exec(src)?.[0] ?? null;
+}
+
+/**
+ * Read keyword options (`goto "X" priority 5 once`). A keyword takes the
+ * quoted string or digit run after it as its value; keywords that aren't
+ * declared, and their values, are skipped.
+ */
+function readOptions(
+  params: readonly ParameterDef[],
+  src: string,
+): Record<string, unknown> {
+  const options: Record<string, unknown> = {};
+  let i = 0;
+  while (i < src.length) {
+    const key = matchAt(WORD_RE, src, i);
+    if (!key) {
+      // Skip whitespace and stray characters, or a stray quoted string.
+      i = readQuoted(src, i)?.end ?? i + 1;
+      continue;
+    }
+    i += key.length;
+
+    // A value is a quoted string or a digit run, after whitespace.
+    let val: string | undefined;
+    let j = i;
+    while (j < src.length && isWhitespace(src[j]!)) j++;
+    if (j > i) {
+      const quoted = readQuoted(src, j);
+      const digits = quoted ? null : matchAt(DIGITS_RE, src, j);
+      if (quoted) {
+        val = quoted.value;
+        i = quoted.end;
+      } else if (digits) {
+        val = digits;
+        i = j + digits.length;
+      }
+    }
+
+    const param = params.find((p) => p.name === key);
+    if (param?.type === 'flag') options[key] = true;
+    else if (param?.type === 'number') options[key] = Number(val ?? 0);
+    else if (param) options[key] = val;
+  }
+  return options;
+}
+
+/** `inline %name` reads a transient variable; `inline % 2` is modulo. */
+const LEADING_OPERATOR_RE = /^(?:[-+*/&|^=<>?:,.]|%(?![A-Za-z_]))/;
+
+/**
+ * The rest of `src` without the flag `word` as its last or first term, or
+ * `null` if it has no such flag. Next to a binary operator the word is an
+ * operand (`"a" + inline`), not a flag; the closing `/` of a regex literal
+ * is not one.
+ */
+function takeFlag(src: string, word: string): string | null {
+  const spans = terms(src);
+  if (spans.length < 2) return null;
+  if (slice(src, spans[spans.length - 1]!) === word) {
+    const rest = src.slice(0, spans[spans.length - 2]![1]);
+    if (!endsWithOperator(rest)) return rest;
+  }
+  if (slice(src, spans[0]!) === word) {
+    const rest = src.slice(spans[1]![0]);
+    if (!LEADING_OPERATOR_RE.test(rest)) return rest;
+  }
+  return null;
+}
+
+/**
+ * Where the separator `word` splits `src`, as the end of the text before it
+ * and the start of the text after it, or `null` if it doesn't. A word is a
+ * term with terms on both sides; `=` is an assignment at depth 0, not part
+ * of `==` or `!=`.
+ */
+function findSeparator(src: string, word: string): Span | null {
+  if (word === '=') {
+    const indices = topLevelIndices(src, (ch) => ch === '=');
+    for (let k = 0; k < indices.length; k++) {
+      const i = indices[k]!;
+      if (src[i + 1] === '=') {
+        k++;
+        continue;
+      }
+      if (src[i - 1] !== '!') return [i, i + 1];
+    }
+    return null;
+  }
+  const spans = terms(src);
+  for (let k = 1; k < spans.length - 1; k++) {
+    if (slice(src, spans[k]!) === word) {
+      return [spans[k - 1]![1], spans[k + 1]![0]];
+    }
+  }
+  return null;
+}
+
+const takesRest = (param: ParameterDef) =>
+  param.type === undefined ||
+  param.type === 'expression' ||
+  param.type === 'text';
+
+/** Read the parameters of one group from `src` (`null`: no text) into `args`. */
+function readGroup(
+  params: readonly ParameterDef[],
+  src: string | null,
+  args: Record<string, unknown>,
+): void {
+  let text = src?.trim() ?? '';
+  for (const flag of params.filter((p) => p.type === 'flag')) {
+    const rest = src === null ? null : takeFlag(text, flag.name);
+    args[flag.name] = rest !== null;
+    text = rest ?? text;
+  }
+  const positional = params.filter((p) => p.type !== 'flag');
+  if (positional.length === 0) return;
+
+  // The last expression or text parameter, else the last one, reads the rest.
+  const lastText = positional.findIndex(
+    (p, i) => takesRest(p) && !positional.slice(i + 1).some(takesRest),
+  );
+  const restIndex = lastText < 0 ? positional.length - 1 : lastText;
+  const read = (param: ParameterDef, value: string) =>
+    value === '' ? unset(param) : readValue(param, value);
+
+  // One parameter reads the whole text: no need to split it.
+  if (positional.length === 1) {
+    args[positional[0]!.name] = read(positional[0]!, text);
+    return;
+  }
+
+  const spans = terms(text);
+  let from = 0;
+  let to = spans.length;
+  for (const param of positional.slice(0, restIndex)) {
+    args[param.name] =
+      from < to ? read(param, slice(text, spans[from++]!)) : unset(param);
+  }
+  for (const param of positional.slice(restIndex + 1).reverse()) {
+    const value =
+      from < to && !endsWithOperator(text.slice(0, spans[to - 1]![0]))
+        ? read(param, slice(text, spans[to - 1]!))
+        : undefined;
+    args[param.name] = value ?? unset(param);
+    if (value !== undefined) to--;
+  }
+  const rest = positional[restIndex]!;
+  args[rest.name] =
+    from < to
+      ? read(rest, text.slice(spans[from]![0], spans[to - 1]![1]))
+      : unset(rest);
+}
+
+/** Read `rawArgs` into the declared `parameters` (see above). */
+export function parseMacroArgs<const P extends readonly ParameterDef[]>(
+  rawArgs: string,
+  parameters: P,
+): MacroArgs<P> {
+  const args: Record<string, unknown> = {};
+  // The text after the last separator read, null once one is missing
+  let rest: string | null = rawArgs.trim();
+  let groupStart = 0;
+  parameters.forEach((separator, i) => {
+    if (separator.type !== 'separator') return;
+    const at = rest === null ? null : findSeparator(rest, separator.name);
+    args[separator.name] = at !== null;
+    const before = at ? rest!.slice(0, at[0]) : rest;
+    readGroup(parameters.slice(groupStart, i), before, args);
+    rest = at ? rest!.slice(at[1]) : null;
+    groupStart = i + 1;
+  });
+  readGroup(parameters.slice(groupStart), rest, args);
+  return args as MacroArgs<P>;
+}
+
+/**
+ * The passage a passage-name argument names: the value of its expression
+ * or, when that can't be evaluated (`{goto Bob's room}`), its text.
+ */
+export function evaluatePassageName(
+  expr: string | undefined,
+  evaluate: (expr: string) => unknown,
+): string {
+  try {
+    return String(evaluate(expr ?? ''));
+  } catch {
+    return readText(expr ?? '');
+  }
+}
+
+/**
+ * The variable a `storeVar` macro binds: its first term, as written. Custom
+ * macros may bind one without declaring parameters.
+ */
+export function readBoundVariable(rawArgs: string): string {
+  const src = rawArgs.trim();
+  const first = terms(src)[0];
+  return first ? slice(src, first) : '';
+}

package/src/components/macros/option-utils.ts

@@ -1,22 +1,17 @@
 import type { ASTNode } from '../../markup/ast';
 import { readWholeQuoted } from './arg-utils';
+import { parseMacroArgs } from './macro-args';
 
+/** `$var "placeholder"`, the arguments of the input macros. */
 export function parseVarArgs(rawArgs: string): {
   varName: string;
   placeholder: string;
 } {
-  // `s`: a quoted placeholder may span lines.
-  const match = rawArgs.match(/^\s*(["']?\$[\w.]+["']?)\s*(["'].*["'])?\s*$/s);
-  if (!match) {
-    return { varName: rawArgs.trim(), placeholder: '' };
-  }
-  const varName = match[1]!.replace(/["']/g, '');
-  // A quoted placeholder accepts \" \' and \\ escapes.
-  const quoted = match[2];
-  const placeholder = quoted
-    ? (readWholeQuoted(quoted) ?? quoted.slice(1, -1))
-    : '';
-  return { varName, placeholder };
+  const { variable = '', placeholder = '' } = parseMacroArgs(rawArgs, [
+    { name: 'variable', type: 'variable' },
+    { name: 'placeholder', type: 'string' },
+  ]);
+  return { varName: variable.replace(/["']/g, ''), placeholder };
 }
 
 /**