@rohal12/spindle 0.47.0 → 0.49.0

package/package.json

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

package/src/components/Passage.tsx

@@ -1,10 +1,17 @@
-import { useMemo, useEffect, useState } from 'preact/hooks';
+import {
+  useMemo,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'preact/hooks';
 import { tokenize } from '../markup/tokenizer';
 import { buildAST } from '../markup/ast';
 import { renderNodes, NobrContext } from '../markup/render';
 import { useStoryStore } from '../store';
 import type { Passage as PassageData } from '../parser';
 import { sourceLocationOf } from '../utils/source-location';
+import { emitFromRender } from '../event-emitter';
 
 export function renderPassageContent(passage: PassageData) {
   const tokens = tokenize(passage.content);
@@ -90,10 +97,21 @@ export function Passage({ passage, dataTransition }: PassageProps) {
     }
   }, [doneReady, donePassage?.content]);
 
+  // Signal that this passage's DOM is committed (after descendants' layout
+  // effects, before paint). Runs once per mount: PassageDisplay keys the
+  // Passage so every navigation that shows a passage mounts a new one.
+  const elRef = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    if (elRef.current) {
+      emitFromRender('passagerender', passage.name, elRef.current);
+    }
+  }, [passage.name]);
+
   const nobr = passage.tags.includes('nobr');
 
   const inner = (
     <div
+      ref={elRef}
       class="passage"
       data-passage={passage.name}
       data-tags={passage.tags.join(' ')}

package/src/components/PassageDialog.tsx

@@ -1,9 +1,11 @@
 import { createContext } from 'preact';
-import { useCallback, useMemo, useRef } from 'preact/hooks';
+import { useCallback, useLayoutEffect, useMemo, useRef } from 'preact/hooks';
 import { tokenize } from '../markup/tokenizer';
 import { buildAST } from '../markup/ast';
 import { renderNodes } from '../markup/render';
 import { useStoryStore } from '../store';
+import { emitFromRender } from '../event-emitter';
+import { useModalFocus } from '../hooks/use-modal-focus';
 
 export const DialogCloseContext = createContext<(() => void) | null>(null);
 
@@ -59,6 +61,19 @@ export function PassageDialog({
     }
   }, [markup]);
 
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  // Focus into the dialog, trap Tab, Escape to close, restore focus on close.
+  // Declared before the dialogrender effect so handlers can move focus.
+  useModalFocus(panelRef, '.dialog-body', dismissible, stableOnClose);
+
+  // Signal that the dialog's DOM is committed (once per open).
+  useLayoutEffect(() => {
+    if (panelRef.current) {
+      emitFromRender('dialogrender', passageName ?? '', panelRef.current);
+    }
+  }, []);
+
   const handleBackdrop = (e: MouseEvent) => {
     if (!dismissible) return;
     if ((e.target as HTMLElement).classList.contains('dialog-overlay')) {
@@ -74,10 +89,17 @@ export function PassageDialog({
         class="dialog-overlay"
         onClick={handleBackdrop}
       >
-        <div class={cls}>
+        <div
+          ref={panelRef}
+          class={cls}
+          role="dialog"
+          aria-modal="true"
+          tabIndex={-1}
+        >
           {showCloseButton && (
             <button
               class="dialog-close"
+              aria-label="Close"
               onClick={stableOnClose}
             >
               ✕

package/src/event-emitter.ts

@@ -14,6 +14,8 @@ type EventMap = {
   afterload: (slot: string | undefined) => void;
   beforenavigate: (passageName: string) => void;
   afternavigate: (to: string, from: string) => void;
+  passagerender: (passage: string, element: HTMLElement) => void;
+  dialogrender: (passage: string, element: HTMLElement) => void;
 };
 
 export type StoryEvent = keyof EventMap;
@@ -30,6 +32,8 @@ const VALID_EVENTS = new Set<string>([
   'afterload',
   'beforenavigate',
   'afternavigate',
+  'passagerender',
+  'dialogrender',
 ]);
 
 // Each event key maps to a Set of callbacks.
@@ -65,6 +69,26 @@ export function emit<E extends StoryEvent>(
   }
 }
 
+/**
+ * Emit an event from inside a render commit (layout effect). A throwing
+ * handler is logged instead of propagating into Preact and breaking the
+ * render; the remaining handlers still run.
+ */
+export function emitFromRender<E extends StoryEvent>(
+  event: E,
+  ...args: Parameters<EventMap[E]>
+): void {
+  const set = listeners.get(event);
+  if (!set) return;
+  for (const cb of [...set]) {
+    try {
+      (cb as Function)(...args);
+    } catch (err) {
+      console.error(`spindle: Error in ${event} handler:`, err);
+    }
+  }
+}
+
 /** Test-only: clear all listeners. */
 export function resetEmitter(): void {
   listeners = new Map();

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

@@ -0,0 +1,110 @@
+import { useLayoutEffect } from 'preact/hooks';
+import type { RefObject } from 'preact';
+
+const FOCUSABLE = [
+  'a[href]',
+  'area[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  'iframe',
+  '[contenteditable="true"]',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+function focusables(root: HTMLElement): HTMLElement[] {
+  return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
+    (el) => !el.hidden && !el.closest('[hidden], [inert]'),
+  );
+}
+
+interface ModalEntry {
+  panel: HTMLElement;
+}
+
+/** Open modal dialogs, innermost last. Only the topmost handles keys. */
+const openModals: ModalEntry[] = [];
+
+/**
+ * Modal focus management for a dialog panel:
+ * - moves focus into the panel on open (an `[autofocus]` element, else the
+ *   first focusable element of the body, else the panel itself);
+ * - keeps Tab / Shift+Tab inside the topmost dialog;
+ * - closes the topmost dialog on Escape when it is dismissible;
+ * - returns focus to the previously focused element on close.
+ */
+export function useModalFocus(
+  panelRef: RefObject<HTMLElement>,
+  bodySelector: string,
+  dismissible: boolean,
+  onClose: () => void,
+): void {
+  useLayoutEffect(() => {
+    const panel = panelRef.current;
+    if (!panel) return;
+
+    const opener =
+      document.activeElement instanceof HTMLElement
+        ? document.activeElement
+        : null;
+    const entry: ModalEntry = { panel };
+    openModals.push(entry);
+
+    const body = panel.querySelector<HTMLElement>(bodySelector) ?? panel;
+    const initial =
+      panel.querySelector<HTMLElement>('[autofocus]') ??
+      focusables(body)[0] ??
+      panel;
+    initial.focus();
+
+    return () => {
+      const i = openModals.indexOf(entry);
+      if (i !== -1) openModals.splice(i, 1);
+      // Restore focus only if it was inside this dialog (or lost to <body>);
+      // don't steal it from somewhere author code moved it on purpose.
+      const active = document.activeElement;
+      const focusWasHere =
+        !active || active === document.body || panel.contains(active);
+      if (focusWasHere && opener?.isConnected) opener.focus();
+    };
+  }, []);
+
+  useLayoutEffect(() => {
+    const panel = panelRef.current;
+    if (!panel) return;
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (openModals[openModals.length - 1]?.panel !== panel) return;
+
+      if (e.key === 'Escape') {
+        if (!dismissible) return;
+        e.preventDefault();
+        e.stopPropagation();
+        onClose();
+        return;
+      }
+
+      if (e.key !== 'Tab') return;
+      const items = focusables(panel);
+      const first = items[0];
+      const last = items[items.length - 1];
+      const active = document.activeElement;
+      // The panel itself (tabindex=-1) counts as outside the tab sequence.
+      const inside = active !== panel && panel.contains(active);
+      if (!first || !last) {
+        e.preventDefault();
+        panel.focus();
+      } else if (e.shiftKey && (active === first || !inside)) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && (active === last || !inside)) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [dismissible, onClose]);
+}

package/src/styles.css

@@ -203,6 +203,11 @@ tw-storydata {
   position: relative;
 }
 
+/* Focused programmatically when the dialog has no focusable content */
+.dialog-panel:focus {
+  outline: none;
+}
+
 .dialog-saves {
   max-width: 550px;
 }

package/types/index.d.ts

@@ -138,6 +138,18 @@ export interface StoryEventMap {
   afterload: (slot: string | undefined) => void;
   beforenavigate: (passageName: string) => void;
   afternavigate: (to: string, from: string) => void;
+  /**
+   * A passage's `.passage` element was committed to the DOM (first render,
+   * navigation, back/forward, restart, load). Fires after the transition
+   * mounts the new passage, before paint.
+   */
+  passagerender: (passage: string, element: HTMLElement) => void;
+  /**
+   * A dialog was opened and its `.dialog-panel` element committed to the DOM.
+   * `passage` is the dialog's passage name (empty for built-in dialogs
+   * without one).
+   */
+  dialogrender: (passage: string, element: HTMLElement) => void;
 }
 
 /** Event name that can be passed to `Story.on()`. */