executable-stories-react 0.8.0 → 0.9.0

package/dist/interactive.d.cts

@@ -372,12 +372,29 @@ interface ReportSearchProps {
 }
 declare const ReportSearch: react.ForwardRefExoticComponent<ReportSearchProps & react.RefAttributes<HTMLInputElement>>;
 
+/**
+ * View state in the URL, so a filtered report survives a refresh and can be
+ * shared as a link.
+ *
+ * It lives in the HASH, not the query string, because the flagship surface is a
+ * single HTML file opened from disk. A `file://` document has an opaque origin,
+ * and Chrome refuses `history.pushState`/`replaceState` when the URL argument
+ * changes anything but the fragment there. The fragment is the one part every
+ * browser lets us rewrite in place.
+ *
+ * Format: `#<anchor>?<params>` — the anchor half stays exactly what it has
+ * always been, a scenario id deep link, so existing permalinks keep working and
+ * a link with no filters is unchanged.
+ */
+type UrlStatusFilter = "all" | "passed" | "failed" | "skipped" | "pending";
+
 /**
  * Pure functions for filtering a StoryReport by a search query.
  * Used by <ReportInteractive>. Kept side-effect-free so it can be unit-tested.
  */
 
-type StatusFilter = "all" | "passed" | "failed" | "skipped" | "pending";
+/** Defined with the URL codec that has to validate it, so the two can't drift. */
+type StatusFilter = UrlStatusFilter;
 interface FilterCriteria {
     query?: string;
     status?: StatusFilter;
@@ -443,8 +460,13 @@ interface KeyboardShortcutHandlers {
 declare function useKeyboardShortcuts(handlers: KeyboardShortcutHandlers): void;
 
 /**
- * Scrolls to a scenario by URL hash on mount and whenever the hash changes.
- * No-op in SSR (only runs in useEffect). Honours `prefers-reduced-motion`.
+ * Scrolls to a scenario by URL hash on mount and whenever the deep link
+ * changes. No-op in SSR (only runs in useEffect). Honours
+ * `prefers-reduced-motion`.
+ *
+ * The fragment also carries filter state (`#<anchor>?q=...`), so only the
+ * anchor half is read — and a hashchange that merely rewrote the filters must
+ * not yank the page back to the last anchor, hence the last-anchor guard.
  */
 declare function useDeepLinkScroll(): void;
 

package/dist/interactive.d.ts

@@ -372,12 +372,29 @@ interface ReportSearchProps {
 }
 declare const ReportSearch: react.ForwardRefExoticComponent<ReportSearchProps & react.RefAttributes<HTMLInputElement>>;
 
+/**
+ * View state in the URL, so a filtered report survives a refresh and can be
+ * shared as a link.
+ *
+ * It lives in the HASH, not the query string, because the flagship surface is a
+ * single HTML file opened from disk. A `file://` document has an opaque origin,
+ * and Chrome refuses `history.pushState`/`replaceState` when the URL argument
+ * changes anything but the fragment there. The fragment is the one part every
+ * browser lets us rewrite in place.
+ *
+ * Format: `#<anchor>?<params>` — the anchor half stays exactly what it has
+ * always been, a scenario id deep link, so existing permalinks keep working and
+ * a link with no filters is unchanged.
+ */
+type UrlStatusFilter = "all" | "passed" | "failed" | "skipped" | "pending";
+
 /**
  * Pure functions for filtering a StoryReport by a search query.
  * Used by <ReportInteractive>. Kept side-effect-free so it can be unit-tested.
  */
 
-type StatusFilter = "all" | "passed" | "failed" | "skipped" | "pending";
+/** Defined with the URL codec that has to validate it, so the two can't drift. */
+type StatusFilter = UrlStatusFilter;
 interface FilterCriteria {
     query?: string;
     status?: StatusFilter;
@@ -443,8 +460,13 @@ interface KeyboardShortcutHandlers {
 declare function useKeyboardShortcuts(handlers: KeyboardShortcutHandlers): void;
 
 /**
- * Scrolls to a scenario by URL hash on mount and whenever the hash changes.
- * No-op in SSR (only runs in useEffect). Honours `prefers-reduced-motion`.
+ * Scrolls to a scenario by URL hash on mount and whenever the deep link
+ * changes. No-op in SSR (only runs in useEffect). Honours
+ * `prefers-reduced-motion`.
+ *
+ * The fragment also carries filter state (`#<anchor>?q=...`), so only the
+ * anchor half is read — and a hashchange that merely rewrote the filters must
+ * not yank the page back to the last anchor, hence the last-anchor guard.
  */
 declare function useDeepLinkScroll(): void;
 

package/dist/interactive.js

@@ -2,12 +2,12 @@
 
 // src/interactive/ReportInteractive.tsx
 import {
-  useCallback as useCallback4,
+  useCallback as useCallback5,
   useDeferredValue,
   useId as useId2,
   useMemo as useMemo3,
-  useRef as useRef3,
-  useState as useState7
+  useRef as useRef5,
+  useState as useState8
 } from "react";
 
 // src/result.ts
@@ -973,11 +973,11 @@ function flakinessOf(entries) {
   if (transitionScore > 0.2 || failureRate > 0.3) return "unstable";
   return "stable";
 }
-function diffSinceLastRun(history2, scenarios) {
+function diffSinceLastRun(history, scenarios) {
   let hasPreviousRun = false;
   const delta = { newlyFailing: [], newlyPassing: [], added: [] };
   for (const scenario of scenarios) {
-    const entries = history2[scenario.id];
+    const entries = history[scenario.id];
     if (!entries || entries.length === 0) continue;
     const last = entries[entries.length - 1];
     const prev = entries[entries.length - 2];
@@ -1007,8 +1007,8 @@ function dotTitle(e) {
   return parts.join(" \xB7 ");
 }
 function ScenarioRunHistory({ scenarioId }) {
-  const history2 = useScenarioHistory();
-  const entries = history2?.[scenarioId];
+  const history = useScenarioHistory();
+  const entries = history?.[scenarioId];
   if (!entries || entries.length < 2) return null;
   const recent = entries.slice(-MAX_DOTS);
   const flaky = flakinessOf(recent) === "flaky";
@@ -1975,6 +1975,54 @@ var ReportSearch = forwardRef(
 // src/interactive/ReportFailureBanner.tsx
 import { useCallback as useCallback2 } from "react";
 
+// src/lib/hash-state.ts
+var DEFAULT_URL_STATE = {
+  query: "",
+  status: "all",
+  tags: [],
+  detail: "full"
+};
+var STATUSES = ["all", "passed", "failed", "skipped", "pending"];
+function splitHash(hash) {
+  const raw = hash.replace(/^#/, "");
+  const split = raw.indexOf("?");
+  if (split === -1) return { anchor: raw, params: new URLSearchParams() };
+  return { anchor: raw.slice(0, split), params: new URLSearchParams(raw.slice(split + 1)) };
+}
+function decodeUrlState(params) {
+  const status = params.get("status");
+  const tags = params.get("tags");
+  return {
+    query: params.get("q") ?? DEFAULT_URL_STATE.query,
+    status: STATUSES.includes(status) ? status : DEFAULT_URL_STATE.status,
+    tags: tags ? tags.split(",").filter(Boolean) : [],
+    detail: params.get("docs") === "0" ? "minimal" : "full"
+  };
+}
+function encodeUrlState(state) {
+  const params = new URLSearchParams();
+  if (state.query) params.set("q", state.query);
+  if (state.status !== "all") params.set("status", state.status);
+  if (state.tags.length > 0) params.set("tags", state.tags.join(","));
+  if (state.detail === "minimal") params.set("docs", "0");
+  return params.toString();
+}
+function formatHash(anchor, params) {
+  if (params) return `#${anchor}?${params}`;
+  return anchor ? `#${anchor}` : "";
+}
+function writeHash(anchor, params) {
+  if (typeof window === "undefined") return;
+  const next = formatHash(anchor, params);
+  if (next === window.location.hash) return;
+  const url = next || window.location.href.split("#")[0];
+  try {
+    window.history.replaceState(window.history.state, "", url);
+  } catch {
+    window.location.hash = next.slice(1);
+  }
+}
+
 // src/lib/scroll.ts
 function prefersReducedMotion() {
   if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
@@ -1990,8 +2038,8 @@ function scrollToScenarioId(scenarioId, options = {}) {
     behavior: prefersReducedMotion() ? "auto" : "smooth",
     block: "start"
   });
-  if (options.updateHash !== false && typeof history !== "undefined") {
-    history.replaceState(null, "", `#${scenarioId}`);
+  if (options.updateHash !== false) {
+    writeHash(scenarioId, splitHash(window.location.hash).params.toString());
   }
 }
 
@@ -2093,12 +2141,12 @@ function ScenarioLinks({ scenarios, tone }) {
   ] });
 }
 function ReportLastRunDelta({
-  history: history2,
+  history,
   report
 }) {
-  if (!history2) return null;
+  if (!history) return null;
   const scenarios = report.features.flatMap((f) => f.scenarios.map((s) => ({ id: s.id, title: s.title })));
-  const delta = diffSinceLastRun(history2, scenarios);
+  const delta = diffSinceLastRun(history, scenarios);
   if (!delta) return null;
   const { newlyFailing, newlyPassing, added } = delta;
   if (newlyFailing.length === 0 && newlyPassing.length === 0 && added.length === 0) {
@@ -2282,14 +2330,16 @@ function useKeyboardShortcuts(handlers) {
 }
 
 // src/interactive/use-deep-link-scroll.ts
-import { useEffect as useEffect4 } from "react";
+import { useEffect as useEffect4, useRef as useRef3 } from "react";
 function useDeepLinkScroll() {
+  const lastAnchor = useRef3(null);
   useEffect4(() => {
     function scrollToHash() {
-      const hash = window.location.hash.replace(/^#/, "");
-      if (!hash) return;
+      const { anchor } = splitHash(window.location.hash);
+      if (!anchor || anchor === lastAnchor.current) return;
+      lastAnchor.current = anchor;
       requestAnimationFrame(() => {
-        scrollToScenarioId(hash, { updateHash: false });
+        scrollToScenarioId(anchor, { updateHash: false });
       });
     }
     scrollToHash();
@@ -2655,6 +2705,34 @@ function useTheme() {
   return { pref, setPref };
 }
 
+// src/interactive/use-url-state.ts
+import { useCallback as useCallback4, useEffect as useEffect7, useRef as useRef4, useState as useState7 } from "react";
+var WRITE_DELAY_MS = 250;
+function useUrlState() {
+  const [state, setState] = useState7(DEFAULT_URL_STATE);
+  const ready = useRef4(false);
+  useEffect7(() => {
+    const read = () => setState(decodeUrlState(splitHash(window.location.hash).params));
+    read();
+    ready.current = true;
+    window.addEventListener("hashchange", read);
+    return () => window.removeEventListener("hashchange", read);
+  }, []);
+  useEffect7(() => {
+    if (!ready.current) return;
+    const timer = setTimeout(
+      () => writeHash(splitHash(window.location.hash).anchor, encodeUrlState(state)),
+      WRITE_DELAY_MS
+    );
+    return () => clearTimeout(timer);
+  }, [state]);
+  const update = useCallback4(
+    (patch) => setState((prev) => ({ ...prev, ...patch })),
+    []
+  );
+  return [state, update];
+}
+
 // src/interactive/ReportInteractive.tsx
 import { Fragment as Fragment13, jsx as jsx46, jsxs as jsxs30 } from "react/jsx-runtime";
 function ReportInteractive(props) {
@@ -2697,13 +2775,20 @@ function ReportInteractiveView({
   staleAfterDays = 7,
   scenarioHistory
 }) {
-  const [query, setQuery] = useState7("");
-  const [statusFilter, setStatusFilter] = useState7("all");
-  const [activeTags, setActiveTags] = useState7([]);
-  const [detail, setDetail] = useState7("full");
-  const [helpOpen, setHelpOpen] = useState7(false);
+  const [urlState, setUrlState] = useUrlState();
+  const { query, status: statusFilter, tags: activeTags, detail } = urlState;
+  const setQuery = useCallback5((next) => setUrlState({ query: next }), [setUrlState]);
+  const setStatusFilter = useCallback5(
+    (next) => setUrlState({ status: next }),
+    [setUrlState]
+  );
+  const setDetail = useCallback5(
+    (next) => setUrlState({ detail: next }),
+    [setUrlState]
+  );
+  const [helpOpen, setHelpOpen] = useState8(false);
   const { pref: themePref, setPref: setThemePref } = useTheme();
-  const searchRef = useRef3(null);
+  const searchRef = useRef5(null);
   const expandId = useId2();
   const docsId = useId2();
   const deferredQuery = useDeferredValue(query);
@@ -2727,18 +2812,20 @@ function ReportInteractiveView({
     return opts;
   }, [report]);
   const tagOptions = useMemo3(() => allTags(report), [report]);
-  const toggleTag = useCallback4(
-    (tag) => setActiveTags((prev) => prev.includes(tag) ? prev.filter((t) => t !== tag) : [...prev, tag]),
-    []
+  const toggleTag = useCallback5(
+    (tag) => setUrlState({
+      tags: activeTags.includes(tag) ? activeTags.filter((t) => t !== tag) : [...activeTags, tag]
+    }),
+    [activeTags, setUrlState]
   );
-  const [toast, setToast] = useState7(null);
-  const toastTimer = useRef3(null);
-  const showToast = useCallback4((msg) => {
+  const [toast, setToast] = useState8(null);
+  const toastTimer = useRef5(null);
+  const showToast = useCallback5((msg) => {
     setToast(msg);
     if (toastTimer.current) clearTimeout(toastTimer.current);
     toastTimer.current = setTimeout(() => setToast(null), 1800);
   }, []);
-  const copy = useCallback4(
+  const copy = useCallback5(
     (text, msg) => {
       if (typeof navigator !== "undefined" && navigator.clipboard) {
         navigator.clipboard.writeText(text).then(() => showToast(msg), () => showToast("Copy failed"));
@@ -2754,15 +2841,15 @@ function ReportInteractiveView({
     }),
     [copy]
   );
-  const failureIndexRef = useRef3(0);
+  const failureIndexRef = useRef5(0);
   const allCollapsibleIds = useMemo3(
     () => report.features.flatMap((f) => [f.id, ...f.scenarios.map((s) => s.id)]),
     [report]
   );
-  const collapse = useCollapseState(useCallback4(() => defaultCollapsedIds(report), [report]));
-  const collapseAll = useCallback4(() => collapse.collapseAll(allCollapsibleIds), [collapse, allCollapsibleIds]);
-  const [expandedAll, setExpandedAll] = useState7(() => report.summary.failed === 0);
-  const setExpanded = useCallback4(
+  const collapse = useCollapseState(useCallback5(() => defaultCollapsedIds(report), [report]));
+  const collapseAll = useCallback5(() => collapse.collapseAll(allCollapsibleIds), [collapse, allCollapsibleIds]);
+  const [expandedAll, setExpandedAll] = useState8(() => report.summary.failed === 0);
+  const setExpanded = useCallback5(
     (expanded) => {
       if (expanded) collapse.expandAll();
       else collapseAll();
@@ -2770,10 +2857,10 @@ function ReportInteractiveView({
     },
     [collapse, collapseAll]
   );
-  const focusSearch = useCallback4(() => {
+  const focusSearch = useCallback5(() => {
     searchRef.current?.focus();
   }, []);
-  const stepFailure = useCallback4(
+  const stepFailure = useCallback5(
     (direction) => {
       if (failures.length === 0) return;
       failureIndexRef.current = (failureIndexRef.current + direction + failures.length) % failures.length;
@@ -2782,10 +2869,10 @@ function ReportInteractiveView({
     },
     [failures]
   );
-  const toggleHelp = useCallback4(() => {
+  const toggleHelp = useCallback5(() => {
     setHelpOpen((v) => !v);
   }, []);
-  const escape = useCallback4(() => {
+  const escape = useCallback5(() => {
     if (helpOpen) setHelpOpen(false);
     else if (query !== "") setQuery("");
   }, [helpOpen, query]);
@@ -2925,11 +3012,11 @@ function ReportInteractiveView({
 import { useMemo as useMemo4 } from "react";
 
 // src/interactive/island-renderers.tsx
-import { createElement, useEffect as useEffect8, useState as useState9 } from "react";
+import { createElement, useEffect as useEffect9, useState as useState10 } from "react";
 
 // src/components/doc/MermaidView.tsx
-import { useEffect as useEffect7, useRef as useRef4, useState as useState8 } from "react";
-import { jsx as jsx47, jsxs as jsxs31 } from "react/jsx-runtime";
+import { useEffect as useEffect8, useRef as useRef6, useState as useState9 } from "react";
+import { Fragment as Fragment14, jsx as jsx47, jsxs as jsxs31 } from "react/jsx-runtime";
 function prefersDark(el) {
   const themed = el?.closest("[data-theme]");
   if (themed?.dataset.theme === "dark") return true;
@@ -2937,23 +3024,40 @@ function prefersDark(el) {
   return typeof window !== "undefined" && !!window.matchMedia?.("(prefers-color-scheme: dark)").matches;
 }
 function MermaidView({ entry, load }) {
-  const ref = useRef4(null);
-  const [svg, setSvg] = useState8(null);
-  useEffect7(() => {
+  const ref = useRef6(null);
+  const [svg, setSvg] = useState9(null);
+  const [error, setError] = useState9(null);
+  useEffect8(() => {
     let cancelled = false;
     const draw = async () => {
+      let mermaid;
+      try {
+        mermaid = await load();
+      } catch {
+        if (!cancelled) {
+          setSvg(null);
+          setError(null);
+        }
+        return;
+      }
       try {
-        const mermaid = await load();
         mermaid.initialize({
           startOnLoad: false,
           securityLevel: "strict",
           theme: prefersDark(ref.current) ? "dark" : "default"
         });
+        await mermaid.parse(entry.code);
         const id = `es-mermaid-${Math.random().toString(36).slice(2)}`;
         const { svg: rendered } = await mermaid.render(id, entry.code);
-        if (!cancelled) setSvg(rendered);
-      } catch {
-        if (!cancelled) setSvg(null);
+        if (!cancelled) {
+          setSvg(rendered);
+          setError(null);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setSvg(null);
+          setError(err instanceof Error ? err.message : String(err));
+        }
       }
     };
     void draw();
@@ -2979,7 +3083,21 @@ function MermaidView({ entry, load }) {
       )
     ] });
   }
-  return /* @__PURE__ */ jsx47(MermaidSource, { entry, ref });
+  return /* @__PURE__ */ jsxs31(Fragment14, { children: [
+    error ? /* @__PURE__ */ jsxs31(
+      "p",
+      {
+        role: "alert",
+        "data-es-mermaid-error": true,
+        className: "mt-3 rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2 text-xs text-destructive",
+        children: [
+          "Diagram failed to render: ",
+          error
+        ]
+      }
+    ) : null,
+    /* @__PURE__ */ jsx47(MermaidSource, { entry, ref })
+  ] });
 }
 
 // src/interactive/island-renderers.tsx
@@ -3000,8 +3118,8 @@ function cachedCdnModule(url) {
 var loadMermaidFromCdn = cachedCdnModule(MERMAID_ESM);
 var loadHljs = cachedCdnModule(HLJS_ESM);
 function CdnHighlightedCode({ entry }) {
-  const [html, setHtml] = useState9(null);
-  useEffect8(() => {
+  const [html, setHtml] = useState10(null);
+  useEffect9(() => {
     let cancelled = false;
     void (async () => {
       try {