executable-stories-react 0.8.0 → 0.10.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;