storybook 9.0.0-alpha.6 → 9.0.0-alpha.8

package/dist/manager-api/index.d.ts

@@ -4,7 +4,7 @@ export { Listener as ChannelListener } from 'storybook/internal/channels';
 import { RouterData, NavigateOptions } from 'storybook/internal/router';
 import { Addon_Types, Addon_TypesEnum, Addon_Collection, Addon_TypesMapping, Addon_BaseType, Addon_SidebarTopType, Addon_SidebarBottomType, Addon_TestProviderType, Addon_PageType, Addon_WrapperType, Addon_Config, API_ProviderData, API_StateMerger, API_Provider, StoryId, Globals, GlobalTypes, API_PanelPositions, API_Layout, API_UI, API_Notification, API_IframeRenderer, API_ComposedRef, API_SetRefData, API_ComposedRefUpdate, API_Refs, API_Settings, API_HashEntry, API_ViewMode, API_LeafEntry, API_PreparedStoryIndex, API_StoryEntry, Args, API_IndexHash, API_DocsEntry, API_FilterFunction, API_LoadedRefData, API_Version, API_Versions, API_UnknownEntries, NormalizedProjectAnnotations, ProjectAnnotations, ComposedStoryFn, API_OptionsData, Parameters, ArgTypes } from 'storybook/internal/types';
 export { Addon_Type as Addon, API_ComponentEntry as ComponentEntry, API_ComposedRef as ComposedRef, API_DocsEntry as DocsEntry, API_GroupEntry as GroupEntry, API_HashEntry as HashEntry, API_IndexHash as IndexHash, API_LeafEntry as LeafEntry, API_Refs as Refs, API_RootEntry as RootEntry, API_IndexHash as StoriesHash, API_StoryEntry as StoryEntry } from 'storybook/internal/types';
-import { TestProviderState, TestProviderId, TestProviders, WhatsNewData } from 'storybook/internal/core-events';
+import { TestProviderState as TestProviderState$1, TestProviderId as TestProviderId$1, TestProviders, WhatsNewData } from 'storybook/internal/core-events';
 import { ThemeVars } from 'storybook/theming';
 import { toId, StoryId as StoryId$1 } from 'storybook/internal/csf';
 
@@ -178,11 +178,11 @@ interface RunOptions {
     entryId?: StoryId;
 }
 type SubAPI$b = {
-    getTestProviderState(id: string): TestProviderState | undefined;
-    updateTestProviderState(id: TestProviderId, update: Partial<TestProviderState>): void;
-    clearTestProviderState(id: TestProviderId): void;
-    runTestProvider(id: TestProviderId, options?: RunOptions): () => void;
-    cancelTestProvider(id: TestProviderId): void;
+    getTestProviderState(id: string): TestProviderState$1 | undefined;
+    updateTestProviderState(id: TestProviderId$1, update: Partial<TestProviderState$1>): void;
+    clearTestProviderState(id: TestProviderId$1): void;
+    runTestProvider(id: TestProviderId$1, options?: RunOptions): () => void;
+    cancelTestProvider(id: TestProviderId$1): void;
 };
 
 interface SubState$9 {
@@ -1171,6 +1171,254 @@ type StatusStoreByTypeId = StatusStore & {
 };
 type UseStatusStore = <T = StatusesByStoryIdAndTypeId>(selector?: (statuses: StatusesByStoryIdAndTypeId) => T) => T;
 
+type TestProviderState = 'test-provider-state:pending' | 'test-provider-state:running' | 'test-provider-state:succeeded' | 'test-provider-state:crashed';
+type TestProviderId = string;
+type TestProviderStateByProviderId = Record<TestProviderId, TestProviderState>;
+type TestProviderStoreEventType = 'run-all' | 'clear-all' | 'settings-changed';
+type TestProviderStoreEvent = BaseEvent & {
+    type: TestProviderStoreEventType;
+};
+type BaseTestProviderStore = {
+    /**
+     * Notifies all listeners that settings have changed for test providers. The Storybook UI will
+     * highlight the test providers to tell the user that settings has changed.
+     */
+    settingsChanged: () => void;
+    /**
+     * Subscribe to clicks on the "Run All" button, that is supposed to trigger all test providers to
+     * run. Your test provider should do the "main thing" when this happens, similar to when the user
+     * triggers your test provider specifically.
+     *
+     * @example
+     *
+     * ```typescript
+     * // Subscribe to run-all events
+     * const unsubscribe = myTestProviderStore.onRunAll(() => {
+     *   await runAllMyTests();
+     * });
+     * ```
+     */
+    onRunAll: (listener: () => void) => () => void;
+    /**
+     * Subscribe to clicks on the "Clear All" button, that is supposed to clear all state from test
+     * providers. Storybook already clears all statuses, but if your test provider has more
+     * non-status-based state, you can use this to clear that here.
+     *
+     * @remarks
+     * The purpose of this is _not_ to clear your test provider's settings, only the test results.
+     * @example
+     *
+     * ```typescript
+     * // Subscribe to clear-all events
+     * const unsubscribe = myTestProviderStore.onClearAll(() => {
+     *   clearMyTestResults();
+     * });
+     *
+     * // Later, when no longer needed
+     * unsubscribe();
+     * ```
+     */
+    onClearAll: (listener: () => void) => () => void;
+};
+/**
+ * Represents a store for a specific test provider, identified by its unique ID. This store provides
+ * methods to manage the state of an individual test provider, including getting and setting its
+ * state, running operations with automatic state management, and accessing its unique identifier.
+ *
+ * Each test provider has its own instance of this store, allowing for independent state management
+ * across different test providers in the application.
+ *
+ * @example
+ *
+ * ```typescript
+ * // Get a store for a specific test provider
+ * const grammarStore = getTestProviderStoreById('addon-grammar');
+ *
+ * // Check the current state
+ * if (grammarStore.getState() === 'test-provider-state:pending') {
+ *   console.log('Grammar tests are ready to run');
+ * }
+ *
+ * // Run tests with automatic state management
+ * grammarStore.runWithState(async () => {
+ *   await runGrammarTests();
+ * });
+ * ```
+ *
+ * @see {@link TestProviderState} for possible state values
+ * @see {@link BaseTestProviderStore} for methods inherited from the base store
+ */
+type TestProviderStoreById = BaseTestProviderStore & {
+    /**
+     * Gets the current state of this specific test provider
+     *
+     * The state represents the current execution status of the test provider, which can be one of the
+     * following:
+     *
+     * - 'test-provider-state:pending': Tests have not been run yet
+     * - 'test-provider-state:running': Tests are currently running
+     * - 'test-provider-state:succeeded': Tests completed successfully
+     * - 'test-provider-state:crashed': Running tests failed or encountered an error
+     *
+     * Storybook UI will use this state to determine what to show in the UI.
+     *
+     * @remarks
+     * The 'test-provider-state:crashed' is meant to signify that the test run as a whole failed to
+     * execute for some reason. It should _not_ be set just because a number of tests failed, use
+     * statuses and the status store for that. See {@link TestStatusStore} for managing individual test
+     * statuses.
+     * @example
+     *
+     * ```typescript
+     * // Get the current state of a specific test provider
+     * const state = testProviderStore.getState();
+     *
+     * // Conditionally render UI based on the state
+     * const TestStatus = () => {
+     *   const state = testProviderStore.getState();
+     *
+     *   if (state === 'test-provider-state:running') {
+     *     return <Spinner />;
+     *   } else if (state === 'test-provider-state:succeeded') {
+     *     return <SuccessIcon />;
+     *   } else if (state === 'test-provider-state:crashed') {
+     *     return <ErrorIcon />;
+     *   }
+     *
+     *   return <PendingIcon />;
+     * };
+     * ```
+     */
+    getState: () => TestProviderState;
+    /**
+     * Sets the state of this specific test provider
+     *
+     * This method allows you to manually update the execution state of the test provider. It's
+     * typically used when you need to reflect the current status of test execution in the UI or when
+     * you want to programmatically control the test provider's state.
+     *
+     * Common use cases include:
+     *
+     * - Setting to 'running' when tests start
+     * - Setting to 'succeeded' when tests complete successfully
+     * - Setting to 'crashed' when tests fail or encounter errors
+     * - Setting to 'pending' to reset the state
+     *
+     * The state represents the current execution status of the test provider, which can be one of the
+     * following:
+     *
+     * - 'test-provider-state:pending': Tests have not been run yet
+     * - 'test-provider-state:running': Tests are currently running
+     * - 'test-provider-state:succeeded': Tests completed successfully
+     * - 'test-provider-state:crashed': Running tests failed or encountered an error
+     *
+     * Storybook UI will use this state to determine what to show in the UI.
+     *
+     * @remarks
+     * The 'test-provider-state:crashed' is meant to signify that the test run as a whole failed to
+     * execute for some reason. It should _not_ be set just because a number of tests failed, use
+     * statuses and the status store for that. See {@link TestStatusStore} for managing individual test
+     * statuses.
+     *
+     * For most use cases, consider using {@link runWithState} instead, which provides automatic state
+     * management and error handling during test execution.
+     * @example
+     *
+     * ```typescript
+     * // Update the state when tests start running
+     * const startTests = async () => {
+     *   testProviderStore.setState('test-provider-state:running');
+     *   ... run tests ...
+     * };
+     * ```
+     */
+    setState: (state: TestProviderState) => void;
+    /**
+     * Runs a callback and automatically updates the test provider's state with running, succeeded or
+     * crashed, depending on the end result.
+     *
+     * - Immediately changes the state to 'running'
+     * - If the callback returns/resolves, change the state to 'succeeded'.
+     * - If the callback throws an error/rejects, change the state to 'crashed'.
+     *
+     * This approach helps prevent state inconsistencies that might occur if exceptions are thrown
+     * during test execution.
+     *
+     * @example
+     *
+     * ```typescript
+     * // Run tests with automatic state management
+     * const runTests = () => {
+     *   testProviderStore.runWithState(async () => {
+     *     // The state is automatically set to 'running' before this callback
+     *
+     *     // Run tests here...
+     *     const results = await executeTests();
+     *   });
+     * };
+     * ```
+     */
+    runWithState: (callback: () => void | Promise<void>) => Promise<void>;
+    /** The unique identifier for this test provider */
+    testProviderId: TestProviderId;
+};
+/**
+ * React OR preview hook for accessing the state of _all_ test providers. This hook will only
+ * trigger a re-render when the state changes. It is recommended to pass the optional selector, to
+ * get more fine-grained control of re-renders.
+ *
+ * @example
+ *
+ * ```typescript
+ * const TestStatus = () => {
+ *   const state = useTestProviderStore((state) => state['my-test-provider']);
+ * };
+ * ```
+ */
+type UseTestProviderStore = <T = TestProviderStateByProviderId>(
+/**
+ * Optional selector function to extract or transform specific parts of the state
+ *
+ * @example
+ *
+ * ```typescript
+ * // Use the entire state
+ * const allProviderStates = useTestProviderStore();
+ *
+ * // Get state for a specific provider
+ * const myProviderState = useTestProviderStore((state) => state['my-test-provider']);
+ *
+ * // Get a count of providers in each state
+ * const statusCounts = useTestProviderStore((state) => {
+ *   const counts = {
+ *     pending: 0,
+ *     running: 0,
+ *     succeeded: 0,
+ *     crashed: 0,
+ *   };
+ *
+ *   Object.values(state).forEach((status) => {
+ *     if (status === 'test-provider-state:pending') counts.pending++;
+ *     else if (status === 'test-provider-state:running') counts.running++;
+ *     else if (status === 'test-provider-state:succeeded') counts.succeeded++;
+ *     else if (status === 'test-provider-state:crashed') counts.crashed++;
+ *   });
+ *
+ *   return counts;
+ * });
+ *
+ * // Check if all tests have completed
+ * const allTestsCompleted = useTestProviderStore((state) => {
+ *   return Object.values(state).every(
+ *     (status) =>
+ *       status === 'test-provider-state:succeeded' ||
+ *       status === 'test-provider-state:crashed'
+ *   );
+ * });
+ * ```
+ */
+selector?: (state: TestProviderStateByProviderId) => T) => T;
+
 declare const fullStatusStore: StatusStore & {
     selectStatuses: (statuses: Status[]) => void;
     typeId: undefined;
@@ -1178,6 +1426,20 @@ declare const fullStatusStore: StatusStore & {
 declare const getStatusStoreByTypeId: (typeId: StatusTypeId) => StatusStoreByTypeId;
 declare const useStatusStore: UseStatusStore;
 
+declare const fullTestProviderStore: {
+    settingsChanged: () => void;
+    onRunAll: (listener: () => void) => () => void;
+    onClearAll: (listener: () => void) => () => void;
+} & {
+    getFullState: UniversalStore<TestProviderStateByProviderId, TestProviderStoreEvent>["getState"];
+    setFullState: UniversalStore<TestProviderStateByProviderId, TestProviderStoreEvent>["setState"];
+    onSettingsChanged: (listener: (testProviderId: TestProviderId) => void) => () => void;
+    runAll: () => void;
+    clearAll: () => void;
+};
+declare const getTestProviderStoreById: (testProviderId: TestProviderId) => TestProviderStoreById;
+declare const useTestProviderStore: UseTestProviderStore;
+
 declare const ActiveTabs: {
     SIDEBAR: "sidebar";
     CANVAS: "canvas";
@@ -1247,4 +1509,4 @@ declare function useArgTypes(): ArgTypes;
 
 declare const typesX: typeof Addon_TypesEnum;
 
-export { type API, type API_EventMap, ActiveTabs, AddonStore, type Combo, ManagerConsumer as Consumer, type KeyboardEventLike, ManagerContext, type ManagerProviderProps, ManagerProvider as Provider, RequestResponseError, type State, type Options as StoreOptions, addons, combineParameters, controlOrMetaKey, controlOrMetaSymbol, eventMatchesShortcut, eventToShortcut, MockUniversalStore as experimental_MockUniversalStore, UniversalStore as experimental_UniversalStore, getStatusStoreByTypeId as experimental_getStatusStore, experimental_requestResponse, useStatusStore as experimental_useStatusStore, useUniversalStore as experimental_useUniversalStore, fullStatusStore as internal_fullStatusStore, isMacLike, isShortcutTaken, keyToSymbol, _default as merge, mockChannel, optionOrAltSymbol, shortcutMatchesShortcut, shortcutToHumanString, typesX as types, useAddonState, useArgTypes, useArgs, useChannel, useGlobalTypes, useGlobals, useParameter, useSharedState, useStoryPrepared, useStorybookApi, useStorybookState };
+export { type API, type API_EventMap, ActiveTabs, AddonStore, type Combo, ManagerConsumer as Consumer, type KeyboardEventLike, ManagerContext, type ManagerProviderProps, ManagerProvider as Provider, RequestResponseError, type State, type Options as StoreOptions, addons, combineParameters, controlOrMetaKey, controlOrMetaSymbol, eventMatchesShortcut, eventToShortcut, MockUniversalStore as experimental_MockUniversalStore, UniversalStore as experimental_UniversalStore, getStatusStoreByTypeId as experimental_getStatusStore, getTestProviderStoreById as experimental_getTestProviderStore, experimental_requestResponse, useStatusStore as experimental_useStatusStore, useTestProviderStore as experimental_useTestProviderStore, useUniversalStore as experimental_useUniversalStore, fullStatusStore as internal_fullStatusStore, fullTestProviderStore as internal_fullTestProviderStore, isMacLike, isShortcutTaken, keyToSymbol, _default as merge, mockChannel, optionOrAltSymbol, shortcutMatchesShortcut, shortcutToHumanString, typesX as types, useAddonState, useArgTypes, useArgs, useChannel, useGlobalTypes, useGlobals, useParameter, useSharedState, useStoryPrepared, useStorybookApi, useStorybookState };