storybook 9.0.0-alpha.2 → 9.0.0-alpha.21

package/dist/core-server/index.d.ts

@@ -1,9 +1,10 @@
 import { loadAllPresets } from 'storybook/internal/common';
 export { getPreviewBodyTemplate, getPreviewHeadTemplate } from 'storybook/internal/common';
 import * as storybook_internal_types from 'storybook/internal/types';
-import { CLIOptions, LoadOptions, BuilderOptions, StorybookConfigRaw, IndexInputStats, NormalizedStoriesSpecifier, Path, Indexer, DocsOptions, StoryIndexEntry, DocsIndexEntry, Tag, IndexEntry, StoryIndex, Options } from 'storybook/internal/types';
+import { CLIOptions, LoadOptions, BuilderOptions, StorybookConfigRaw, IndexInputStats, NormalizedStoriesSpecifier, Path, Indexer, DocsOptions, StoryIndexEntry, DocsIndexEntry, Tag, IndexEntry, StoryIndex, Options, NormalizedProjectAnnotations, ProjectAnnotations, ComposedStoryFn } from 'storybook/internal/types';
 import { EventType } from 'storybook/internal/telemetry';
 import { Channel } from 'storybook/internal/channels';
+import { StoryId } from 'storybook/internal/csf';
 
 type BuildStaticStandaloneOptions = CLIOptions & LoadOptions & BuilderOptions & {
     outputDir: string;
@@ -423,7 +424,7 @@ declare class UniversalStore<State, CustomEvent extends {
  * @example
  *
  * ```ts
- * import * as testUtils from '@storybook/test'; // in stories
+ * import * as testUtils from 'storybook/test'; // in stories
  * import { vi as testUtils } from 'vitest'; // ... or in Vitest tests
  *
  * const initialState = { ... };
@@ -459,4 +460,270 @@ declare class MockUniversalStore<State, CustomEvent extends {
     unsubscribeAll(): void;
 }
 
-export { type BuildIndexOptions, type BuildStaticStandaloneOptions, StoryIndexGenerator, build, buildDevStandalone, buildIndex, buildIndexStandalone, buildStaticStandalone, MockUniversalStore as experimental_MockUniversalStore, UniversalStore as experimental_UniversalStore, loadStorybook as experimental_loadStorybook, getErrorLevel, mapStaticDir, sendTelemetryError, withTelemetry };
+type StatusValue = 'status-value:pending' | 'status-value:success' | 'status-value:error' | 'status-value:warning' | 'status-value:unknown';
+type StatusTypeId = string;
+type StatusByTypeId = Record<StatusTypeId, Status>;
+type StatusesByStoryIdAndTypeId = Record<StoryId, StatusByTypeId>;
+interface Status {
+    value: StatusValue;
+    typeId: StatusTypeId;
+    storyId: StoryId;
+    title: string;
+    description: string;
+    data?: any;
+    sidebarContextMenu?: boolean;
+}
+declare const StatusStoreEventType: {
+    readonly SELECT: "select";
+};
+type StatusStoreEvent = {
+    type: typeof StatusStoreEventType.SELECT;
+    payload: Status[];
+};
+type StatusStore = {
+    getAll: () => StatusesByStoryIdAndTypeId;
+    set: (statuses: Status[]) => void;
+    onAllStatusChange: (listener: (statuses: StatusesByStoryIdAndTypeId, previousStatuses: StatusesByStoryIdAndTypeId) => void) => () => void;
+    onSelect: (listener: (selectedStatuses: Status[]) => void) => () => void;
+    unset: (storyIds?: StoryId[]) => void;
+};
+type StatusStoreByTypeId = StatusStore & {
+    typeId: StatusTypeId;
+};
+
+declare global {
+	interface SymbolConstructor {
+		readonly observable: symbol;
+	}
+}
+
+declare global {
+    var globalProjectAnnotations: NormalizedProjectAnnotations<any>;
+    var defaultProjectAnnotations: ProjectAnnotations<any>;
+}
+type WrappedStoryRef = {
+    __pw_type: 'jsx' | 'importRef';
+};
+type UnwrappedJSXStoryRef = {
+    __pw_type: 'jsx';
+    type: UnwrappedImportStoryRef;
+};
+type UnwrappedImportStoryRef = ComposedStoryFn;
+declare global {
+    function __pwUnwrapObject(storyRef: WrappedStoryRef): Promise<UnwrappedJSXStoryRef | UnwrappedImportStoryRef>;
+}
+
+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;
+};
+
+declare const fullStatusStore: StatusStore & {
+    selectStatuses: (statuses: Status[]) => void;
+    typeId: undefined;
+};
+declare const getStatusStoreByTypeId: (typeId: StatusTypeId) => StatusStoreByTypeId;
+declare const universalStatusStore: UniversalStore<StatusesByStoryIdAndTypeId, StatusStoreEvent>;
+
+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 universalTestProviderStore: UniversalStore<TestProviderStateByProviderId, TestProviderStoreEvent>;
+
+export { type BuildIndexOptions, type BuildStaticStandaloneOptions, StoryIndexGenerator, build, buildDevStandalone, buildIndex, buildIndexStandalone, buildStaticStandalone, MockUniversalStore as experimental_MockUniversalStore, UniversalStore as experimental_UniversalStore, getStatusStoreByTypeId as experimental_getStatusStore, getTestProviderStoreById as experimental_getTestProviderStore, loadStorybook as experimental_loadStorybook, getErrorLevel, fullStatusStore as internal_fullStatusStore, fullTestProviderStore as internal_fullTestProviderStore, universalStatusStore as internal_universalStatusStore, universalTestProviderStore as internal_universalTestProviderStore, mapStaticDir, sendTelemetryError, withTelemetry };