executable-stories-react 0.1.16 → 0.2.0

package/dist/interactive.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { ReportDocCustom, ReportDocMermaid, ReportDocCode, ReportDocSection, StoryReport } from 'executable-stories-formatters';
+import { ReportDocCustom, ReportDocMermaid, ReportDocCode, ReportDocSection, StoryReport } from 'executable-stories-core';
 
 /**
  * Result<T> — explicit success/error type matching the cookbook convention.
@@ -8,6 +8,7 @@ import { ReportDocCustom, ReportDocMermaid, ReportDocCode, ReportDocSection, Sto
  * Used at the boundary where a StoryReport is parsed: the consumer hands us
  * an unknown value (file contents, fetch body, prop) and we return a Result.
  */
+
 type Result<T, E = ReportParseError> = {
     ok: true;
     data: T;
@@ -52,9 +53,50 @@ interface ReportInteractiveProps {
     className?: string;
     title?: string;
     dataTheme?: "light" | "dark";
+    /**
+     * Drop the report's own title block (`<h1>` + summary + meta) while keeping
+     * the search and filter controls. Use when the surrounding page already shows
+     * the report title as its heading — e.g. the Astro stories index embedded in
+     * Starlight, where Starlight renders the page `<h1>`.
+     */
+    hideHeader?: boolean;
 }
 declare function ReportInteractive(props: ReportInteractiveProps): react.JSX.Element;
 
+interface ReportInteractiveIslandProps {
+    report: StoryReport | Result<StoryReport>;
+    title?: string;
+    className?: string;
+    hideHeader?: boolean;
+    /** Render code blocks with CDN highlight.js (default true). */
+    syntaxHighlighting?: boolean;
+    /** Render `story.mermaid(...)` blocks as CDN-loaded SVG diagrams (default true). */
+    mermaid?: boolean;
+}
+/**
+ * Self-contained interactive island for host frameworks that hydrate this as a
+ * client island (e.g. Astro `<ReportInteractiveIsland client:load/>`).
+ *
+ * Frameworks like Astro serialize island props as JSON, so they CANNOT pass the
+ * `renderers` functions to <ReportInteractive> directly — which is why a host
+ * would otherwise fall back to a separate post-hydration script that mutates the
+ * island's DOM (and gets clobbered when the island re-renders). This wrapper
+ * builds the React-OWNED highlighting + mermaid renderers internally, so the
+ * enhancements live inside the React tree and survive every re-render. The
+ * heavy libraries load from a CDN at runtime, so the host bundle stays lean.
+ */
+declare function ReportInteractiveIsland({ report, title, className, hideHeader, syntaxHighlighting, mermaid, }: ReportInteractiveIslandProps): react.JSX.Element;
+
+interface IslandRendererOptions {
+    syntaxHighlighting: boolean;
+    mermaid: boolean;
+}
+/**
+ * Build the BuiltinRenderers map the island passes to <ReportInteractive>.
+ * Created once at mount so the renderer functions stay referentially stable.
+ */
+declare function buildIslandRenderers(opts: IslandRendererOptions): BuiltinRenderers;
+
 interface ReportSearchProps {
     value: string;
     onChange: (next: string) => void;
@@ -70,8 +112,15 @@ declare const ReportSearch: react.ForwardRefExoticComponent<ReportSearchProps &
  * Used by <ReportInteractive>. Kept side-effect-free so it can be unit-tested.
  */
 
+type StatusFilter = "all" | "passed" | "failed" | "skipped" | "pending";
+interface FilterCriteria {
+    query?: string;
+    status?: StatusFilter;
+    /** Scenario matches if it carries ANY of these tags (empty = no tag filter). */
+    tags?: string[];
+}
 declare function normalizeQuery(query: string): string;
-declare function filterReport(report: StoryReport, query: string): StoryReport;
+declare function filterReport(report: StoryReport, criteria: string | FilterCriteria): StoryReport;
 interface FailureRef {
     featureId: string;
     scenarioId: string;
@@ -97,6 +146,8 @@ interface KeyboardShortcutHandlers {
     onPrevFailure?: () => void;
     onToggleHelp?: () => void;
     onEscape?: () => void;
+    onExpandAll?: () => void;
+    onCollapseAll?: () => void;
 }
 /**
  * Attaches one keydown listener for the lifetime of the component, regardless
@@ -108,8 +159,8 @@ 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).
+ * No-op in SSR (only runs in useEffect). Honours `prefers-reduced-motion`.
  */
 declare function useDeepLinkScroll(): void;
 
-export { type FailureRef, type KeyboardShortcutHandlers, ReportFailureBanner, type ReportFailureBannerProps, ReportInteractive, type ReportInteractiveProps, ReportSearch, type ReportSearchProps, ReportShortcutsHelp, type ReportShortcutsHelpProps, filterReport, listFailures, normalizeQuery, useDeepLinkScroll, useKeyboardShortcuts };
+export { type FailureRef, type IslandRendererOptions, type KeyboardShortcutHandlers, ReportFailureBanner, type ReportFailureBannerProps, ReportInteractive, ReportInteractiveIsland, type ReportInteractiveIslandProps, type ReportInteractiveProps, ReportSearch, type ReportSearchProps, ReportShortcutsHelp, type ReportShortcutsHelpProps, buildIslandRenderers, filterReport, listFailures, normalizeQuery, useDeepLinkScroll, useKeyboardShortcuts };

package/dist/interactive.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { ReportDocCustom, ReportDocMermaid, ReportDocCode, ReportDocSection, StoryReport } from 'executable-stories-formatters';
+import { ReportDocCustom, ReportDocMermaid, ReportDocCode, ReportDocSection, StoryReport } from 'executable-stories-core';
 
 /**
  * Result<T> — explicit success/error type matching the cookbook convention.
@@ -8,6 +8,7 @@ import { ReportDocCustom, ReportDocMermaid, ReportDocCode, ReportDocSection, Sto
  * Used at the boundary where a StoryReport is parsed: the consumer hands us
  * an unknown value (file contents, fetch body, prop) and we return a Result.
  */
+
 type Result<T, E = ReportParseError> = {
     ok: true;
     data: T;
@@ -52,9 +53,50 @@ interface ReportInteractiveProps {
     className?: string;
     title?: string;
     dataTheme?: "light" | "dark";
+    /**
+     * Drop the report's own title block (`<h1>` + summary + meta) while keeping
+     * the search and filter controls. Use when the surrounding page already shows
+     * the report title as its heading — e.g. the Astro stories index embedded in
+     * Starlight, where Starlight renders the page `<h1>`.
+     */
+    hideHeader?: boolean;
 }
 declare function ReportInteractive(props: ReportInteractiveProps): react.JSX.Element;
 
+interface ReportInteractiveIslandProps {
+    report: StoryReport | Result<StoryReport>;
+    title?: string;
+    className?: string;
+    hideHeader?: boolean;
+    /** Render code blocks with CDN highlight.js (default true). */
+    syntaxHighlighting?: boolean;
+    /** Render `story.mermaid(...)` blocks as CDN-loaded SVG diagrams (default true). */
+    mermaid?: boolean;
+}
+/**
+ * Self-contained interactive island for host frameworks that hydrate this as a
+ * client island (e.g. Astro `<ReportInteractiveIsland client:load/>`).
+ *
+ * Frameworks like Astro serialize island props as JSON, so they CANNOT pass the
+ * `renderers` functions to <ReportInteractive> directly — which is why a host
+ * would otherwise fall back to a separate post-hydration script that mutates the
+ * island's DOM (and gets clobbered when the island re-renders). This wrapper
+ * builds the React-OWNED highlighting + mermaid renderers internally, so the
+ * enhancements live inside the React tree and survive every re-render. The
+ * heavy libraries load from a CDN at runtime, so the host bundle stays lean.
+ */
+declare function ReportInteractiveIsland({ report, title, className, hideHeader, syntaxHighlighting, mermaid, }: ReportInteractiveIslandProps): react.JSX.Element;
+
+interface IslandRendererOptions {
+    syntaxHighlighting: boolean;
+    mermaid: boolean;
+}
+/**
+ * Build the BuiltinRenderers map the island passes to <ReportInteractive>.
+ * Created once at mount so the renderer functions stay referentially stable.
+ */
+declare function buildIslandRenderers(opts: IslandRendererOptions): BuiltinRenderers;
+
 interface ReportSearchProps {
     value: string;
     onChange: (next: string) => void;
@@ -70,8 +112,15 @@ declare const ReportSearch: react.ForwardRefExoticComponent<ReportSearchProps &
  * Used by <ReportInteractive>. Kept side-effect-free so it can be unit-tested.
  */
 
+type StatusFilter = "all" | "passed" | "failed" | "skipped" | "pending";
+interface FilterCriteria {
+    query?: string;
+    status?: StatusFilter;
+    /** Scenario matches if it carries ANY of these tags (empty = no tag filter). */
+    tags?: string[];
+}
 declare function normalizeQuery(query: string): string;
-declare function filterReport(report: StoryReport, query: string): StoryReport;
+declare function filterReport(report: StoryReport, criteria: string | FilterCriteria): StoryReport;
 interface FailureRef {
     featureId: string;
     scenarioId: string;
@@ -97,6 +146,8 @@ interface KeyboardShortcutHandlers {
     onPrevFailure?: () => void;
     onToggleHelp?: () => void;
     onEscape?: () => void;
+    onExpandAll?: () => void;
+    onCollapseAll?: () => void;
 }
 /**
  * Attaches one keydown listener for the lifetime of the component, regardless
@@ -108,8 +159,8 @@ 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).
+ * No-op in SSR (only runs in useEffect). Honours `prefers-reduced-motion`.
  */
 declare function useDeepLinkScroll(): void;
 
-export { type FailureRef, type KeyboardShortcutHandlers, ReportFailureBanner, type ReportFailureBannerProps, ReportInteractive, type ReportInteractiveProps, ReportSearch, type ReportSearchProps, ReportShortcutsHelp, type ReportShortcutsHelpProps, filterReport, listFailures, normalizeQuery, useDeepLinkScroll, useKeyboardShortcuts };
+export { type FailureRef, type IslandRendererOptions, type KeyboardShortcutHandlers, ReportFailureBanner, type ReportFailureBannerProps, ReportInteractive, ReportInteractiveIsland, type ReportInteractiveIslandProps, type ReportInteractiveProps, ReportSearch, type ReportSearchProps, ReportShortcutsHelp, type ReportShortcutsHelpProps, buildIslandRenderers, filterReport, listFailures, normalizeQuery, useDeepLinkScroll, useKeyboardShortcuts };