@rohal12/spindle 0.2.0 → 0.3.0

package/src/hooks/use-action.ts

@@ -0,0 +1,49 @@
+import { useLayoutEffect, useRef } from 'preact/hooks';
+import {
+  registerAction,
+  generateActionId,
+  type ActionType,
+  type StoryAction,
+} from '../action-registry';
+
+export interface UseActionOptions {
+  type: ActionType;
+  key: string;
+  authorId?: string;
+  label: string;
+  target?: string;
+  variable?: string;
+  options?: string[];
+  value?: unknown;
+  disabled?: boolean;
+  perform: (value?: unknown) => void;
+}
+
+export function useAction(opts: UseActionOptions): string {
+  const idRef = useRef<string>('');
+
+  // Generate ID only once on first call
+  if (!idRef.current) {
+    idRef.current = generateActionId(opts.type, opts.key, opts.authorId);
+  }
+
+  const id = idRef.current;
+
+  useLayoutEffect(() => {
+    const action: StoryAction = {
+      id,
+      type: opts.type,
+      label: opts.label,
+      perform: opts.perform,
+    };
+    if (opts.target !== undefined) action.target = opts.target;
+    if (opts.variable !== undefined) action.variable = opts.variable;
+    if (opts.options !== undefined) action.options = opts.options;
+    if (opts.value !== undefined) action.value = opts.value;
+    if (opts.disabled !== undefined) action.disabled = opts.disabled;
+
+    return registerAction(action);
+  });
+
+  return id;
+}

package/src/index.tsx

@@ -3,6 +3,7 @@ import { App } from './components/App';
 import { parseStoryData } from './parser';
 import { useStoryStore } from './store';
 import { installStoryAPI } from './story-api';
+import { resetIdCounters } from './action-registry';
 import { executeStoryInit } from './story-init';
 import {
   parseStoryVariables,
@@ -101,6 +102,15 @@ function boot() {
     }
   }
 
+  // Reset action ID counters on passage change
+  let prevPassage = '';
+  useStoryStore.subscribe((state) => {
+    if (state.currentPassage !== prevPassage) {
+      prevPassage = state.currentPassage;
+      resetIdCounters();
+    }
+  });
+
   const root = document.getElementById('root');
   if (!root) {
     throw new Error('spindle: No <div id="root"> element found.');

package/src/story-api.ts

@@ -3,6 +3,20 @@ import { settings } from './settings';
 import type { SavePayload } from './saves/types';
 import { setTitleGenerator } from './saves/save-manager';
 import { registerClass } from './class-registry';
+import {
+  getActions,
+  getAction,
+  onActionsChanged,
+  type StoryAction,
+} from './action-registry';
+
+export type { StoryAction };
+
+type NavigateCallback = (to: string, from: string) => void;
+type ActionsChangedCallback = () => void;
+type VariableChangedCallback = (
+  changed: Record<string, { from: unknown; to: unknown }>,
+) => void;
 
 export interface StoryAPI {
   get(name: string): unknown;
@@ -24,11 +38,18 @@ export interface StoryAPI {
   hasRenderedAny(...names: string[]): boolean;
   hasRenderedAll(...names: string[]): boolean;
   readonly title: string;
+  readonly passage: string;
   readonly settings: typeof settings;
   registerClass(name: string, ctor: new (...args: any[]) => any): void;
   readonly saves: {
     setTitleGenerator(fn: (payload: SavePayload) => string): void;
   };
+  getActions(): StoryAction[];
+  performAction(id: string, value?: unknown): void;
+  on(event: 'navigate', callback: NavigateCallback): () => void;
+  on(event: 'actionsChanged', callback: ActionsChangedCallback): () => void;
+  on(event: 'variableChanged', callback: VariableChangedCallback): () => void;
+  waitForActions(): Promise<StoryAction[]>;
 }
 
 function createStoryAPI(): StoryAPI {
@@ -116,6 +137,10 @@ function createStoryAPI(): StoryAPI {
       return useStoryStore.getState().storyData?.name || '';
     },
 
+    get passage(): string {
+      return useStoryStore.getState().currentPassage;
+    },
+
     settings,
 
     registerClass(name: string, ctor: new (...args: any[]) => any): void {
@@ -127,6 +152,72 @@ function createStoryAPI(): StoryAPI {
         setTitleGenerator(fn);
       },
     },
+
+    getActions(): StoryAction[] {
+      return getActions();
+    },
+
+    performAction(id: string, value?: unknown): void {
+      const action = getAction(id);
+      if (!action) {
+        throw new Error(`spindle: Action "${id}" not found.`);
+      }
+      if (action.disabled) {
+        throw new Error(`spindle: Action "${id}" is disabled.`);
+      }
+      action.perform(value);
+    },
+
+    on(event: string, callback: (...args: any[]) => void): () => void {
+      if (event === 'navigate') {
+        let prev = useStoryStore.getState().currentPassage;
+        return useStoryStore.subscribe((state) => {
+          if (state.currentPassage !== prev) {
+            const from = prev;
+            prev = state.currentPassage;
+            (callback as NavigateCallback)(state.currentPassage, from);
+          }
+        });
+      }
+
+      if (event === 'actionsChanged') {
+        return onActionsChanged(callback as ActionsChangedCallback);
+      }
+
+      if (event === 'variableChanged') {
+        let prevVars = { ...useStoryStore.getState().variables };
+        return useStoryStore.subscribe((state) => {
+          const changed: Record<string, { from: unknown; to: unknown }> = {};
+          let hasChanges = false;
+          const allKeys = new Set([
+            ...Object.keys(prevVars),
+            ...Object.keys(state.variables),
+          ]);
+          for (const key of allKeys) {
+            if (state.variables[key] !== prevVars[key]) {
+              changed[key] = { from: prevVars[key], to: state.variables[key] };
+              hasChanges = true;
+            }
+          }
+          prevVars = { ...state.variables };
+          if (hasChanges) {
+            (callback as VariableChangedCallback)(changed);
+          }
+        });
+      }
+
+      throw new Error(`spindle: Unknown event "${event}".`);
+    },
+
+    waitForActions(): Promise<StoryAction[]> {
+      return new Promise((resolve) => {
+        requestAnimationFrame(() => {
+          requestAnimationFrame(() => {
+            resolve(getActions());
+          });
+        });
+      });
+    },
   };
 }
 

package/src/story-variables.ts

@@ -114,7 +114,9 @@ function validateRef(
     }
     const fieldSchema = current.fields.get(parts[i]);
     if (!fieldSchema) {
-      return `Undeclared field: $${parts.slice(0, i + 1).join('.')}`;
+      // Unknown fields on objects are allowed — classes registered via
+      // Story.registerClass() can add methods/getters not in the defaults.
+      return null;
     }
     current = fieldSchema;
   }

package/src/utils/extract-text.ts

@@ -0,0 +1,8 @@
+import type { ASTNode } from '../markup/ast';
+
+/**
+ * Collect plain text from AST nodes, ignoring non-text nodes.
+ */
+export function collectText(nodes: ASTNode[]): string {
+  return nodes.map((n) => (n.type === 'text' ? n.value : '')).join('');
+}