@storybook/types 7.2.3 → 7.3.0

package/README.md

@@ -3,6 +3,6 @@
 Storybook types exports only typescript types for storybook usage.
 
 It exports typescript enums, which do have a runtime implementation.
-But it should not export any implementation such as classes, method, function or constants.
+But it should not export any implementation such as classes, methods, functions or constants.
 
 It also has no dependencies, all the types it exports are bundled in.

package/dist/index.d.ts

@@ -1430,6 +1430,8 @@ interface ThemeVarsColors {
     gridCellSize?: number;
 }
 
+type ExportName = string;
+type MetaId = string;
 interface StoriesSpecifier {
     /**
      * When auto-titling, what to prefix all generated titles with (default: '')
@@ -1467,10 +1469,40 @@ interface IndexedCSFFile {
     };
     stories: IndexedStory[];
 }
-interface StoryIndexer {
+/**
+ * FIXME: This is a temporary type to allow us to deprecate the old indexer API.
+ * We should remove this type and the deprecated indexer API in 8.0.
+ */
+type BaseIndexer = {
+    /**
+     * A regular expression that should match all files to be handled by this indexer
+     */
     test: RegExp;
+};
+/**
+ * An indexer describes which filenames it handles, and how to index each individual file - turning it into an entry in the index.
+ */
+type Indexer = BaseIndexer & {
+    /**
+     * Indexes a file containing stories or docs.
+     * @param fileName The name of the file to index.
+     * @param options {@link IndexerOptions} for indexing the file.
+     * @returns A promise that resolves to an array of {@link IndexInput} objects.
+     */
+    index: (fileName: string, options: IndexerOptions) => Promise<IndexInput[]>;
+    /**
+     * @soonDeprecated Use {@link index} instead
+     */
+    indexer?: never;
+};
+type DeprecatedIndexer = BaseIndexer & {
     indexer: (fileName: string, options: IndexerOptions) => Promise<IndexedCSFFile>;
-}
+    index?: never;
+};
+/**
+ * @soonDeprecated Use {@link Indexer} instead
+ */
+type StoryIndexer = Indexer | DeprecatedIndexer;
 interface BaseIndexEntry {
     id: StoryId;
     name: StoryName;
@@ -1486,6 +1518,48 @@ type DocsIndexEntry = BaseIndexEntry & {
     type: 'docs';
 };
 type IndexEntry = StoryIndexEntry | DocsIndexEntry;
+/**
+ * The base input for indexing a story or docs entry.
+ */
+type BaseIndexInput = {
+    /** The file to import from e.g. the story file. */
+    importPath: Path;
+    /** The name of the export to import. */
+    exportName: ExportName;
+    /** The name of the entry, auto-generated from {@link exportName} if unspecified. */
+    name?: StoryName;
+    /** The location in the sidebar, auto-generated from {@link importPath} if unspecified. */
+    title?: ComponentTitle;
+    /**
+     * The custom id optionally set at `meta.id` if it needs to differ from the id generated via {@link title}.
+     * If unspecified, the meta id will be auto-generated from {@link title}.
+     * If specified, the meta in the CSF file _must_ have a matching id set at `meta.id`, to be correctly matched.
+     */
+    metaId?: MetaId;
+    /** Tags for filtering entries in Storybook and its tools. */
+    tags?: Tag[];
+    /**
+     * The id of the entry, auto-generated from {@link title}/{@link metaId} and {@link exportName} if unspecified.
+     * If specified, the story in the CSF file _must_ have a matching id set at `parameters.__id`, to be correctly matched.
+     * Only use this if you need to override the auto-generated id.
+     */
+    __id?: StoryId;
+};
+/**
+ * The input for indexing a story entry.
+ */
+type StoryIndexInput = BaseIndexInput & {
+    type: 'story';
+};
+/**
+ * The input for indexing a docs entry.
+ */
+type DocsIndexInput = BaseIndexInput & {
+    type: 'docs';
+    /** Paths to story files that must be pre-loaded for this docs entry. */
+    storiesImports?: Path[];
+};
+type IndexInput = StoryIndexInput | DocsIndexInput;
 interface V3CompatIndexEntry extends Omit<StoryIndexEntry, 'type' | 'tags'> {
     kind: ComponentTitle;
     story: StoryName;
@@ -1708,7 +1782,11 @@ type Addon_BaseStoryFn<TArgs, StoryFnReturnType> = {
 type BaseStory<TArgs, StoryFnReturnType> = Addon_BaseStoryFn<TArgs, StoryFnReturnType> | Addon_BaseStoryObject<TArgs, StoryFnReturnType>;
 interface Addon_RenderOptions {
     active: boolean;
-    key: string;
+    /**
+     * @deprecated You should not use key anymore as of Storybook 7.2 this render method is invoked as a React component.
+     * This property will be removed in 8.0.
+     * */
+    key?: unknown;
 }
 /**
  * @deprecated This type is deprecated and will be removed in 8.0.
@@ -2294,8 +2372,13 @@ interface StorybookConfig {
     previewAnnotations?: PresetValue<Entry[]>;
     /**
      * Process CSF files for the story index.
+     * @soonDeprecated use {@link experimental_indexers} instead
      */
     storyIndexers?: PresetValue<StoryIndexer[]>;
+    /**
+     * Process CSF files for the story index.
+     */
+    experimental_indexers?: PresetValue<Indexer[]>;
     /**
      * Docs related features in index generation
      */
@@ -2833,31 +2916,45 @@ type Store_CSFExports<TRenderer extends Renderer = Renderer, TArgs extends Args
     __esModule?: boolean;
     __namedExportsOrder?: string[];
 };
+/**
+ * Type for the play function returned by a composed story, which will contain everything needed in the context,
+ * except the canvasElement, which should be passed by the user.
+ * It's useful for scenarios where the user wants to execute the play function in test environments, e.g.
+ *
+ * const { PrimaryButton } = composeStories(stories)
+ * const { container } = render(<PrimaryButton />) // or PrimaryButton()
+ * PrimaryButton.play({ canvasElement: container })
+ */
 type ComposedStoryPlayContext<TRenderer extends Renderer = Renderer, TArgs = Args> = Partial<StoryContext<TRenderer, TArgs> & Pick<StoryContext<TRenderer, TArgs>, 'canvasElement'>>;
 type ComposedStoryPlayFn<TRenderer extends Renderer = Renderer, TArgs = Args> = (context: ComposedStoryPlayContext<TRenderer, TArgs>) => Promise<void> | void;
-type PreparedStoryFn<TRenderer extends Renderer = Renderer, TArgs = Args> = AnnotatedStoryFn<TRenderer, TArgs> & {
+/**
+ * A story function with partial args, used internally by composeStory
+ */
+type PartialArgsStoryFn<TRenderer extends Renderer = Renderer, TArgs = Args> = (args?: TArgs) => (TRenderer & {
+    T: TArgs;
+})['storyResult'];
+/**
+ * A story that got recomposed for portable stories, containing all the necessary data to be rendered in external environments
+ */
+type ComposedStoryFn<TRenderer extends Renderer = Renderer, TArgs = Args> = PartialArgsStoryFn<TRenderer, TArgs> & {
     play: ComposedStoryPlayFn<TRenderer, TArgs>;
     args: TArgs;
     id: StoryId;
+    storyName: string;
+    parameters: Parameters;
 };
-type ComposedStory<TRenderer extends Renderer = Renderer, TArgs = Args> = StoryFn<TRenderer, TArgs> | StoryAnnotations<TRenderer, TArgs>;
 /**
- * T represents the whole ES module of a stories file. K of T means named exports (basically the Story type)
- * 1. pick the keys K of T that have properties that are Story<AnyProps>
- * 2. infer the actual prop type for each Story
- * 3. reconstruct Story with Partial. Story<Props> -> Story<Partial<Props>>
+ * Based on a module of stories, it returns all stories within it, filtering non-stories
+ * Each story will have partial props, as their props should be handled when composing stories
  */
 type StoriesWithPartialProps<TRenderer extends Renderer, TModule> = {
-    [K in keyof TModule]: TModule[K] extends ComposedStory<infer _, infer TProps> ? PreparedStoryFn<TRenderer, Partial<TProps>> : unknown;
+    [K in keyof TModule as TModule[K] extends StoryAnnotationsOrFn<infer _, infer _TProps> ? K : never]: TModule[K] extends StoryAnnotationsOrFn<infer _, infer TProps> ? ComposedStoryFn<TRenderer, Partial<TProps>> : unknown;
 };
+/**
+ * Type used for integrators of portable stories, as reference when creating their own composeStory function
+ */
 interface ComposeStoryFn<TRenderer extends Renderer = Renderer, TArgs extends Args = Args> {
-    (storyAnnotations: AnnotatedStoryFn<TRenderer, TArgs> | StoryAnnotations<TRenderer, TArgs>, componentAnnotations: ComponentAnnotations<TRenderer, TArgs>, projectAnnotations: ProjectAnnotations<TRenderer>, exportsName?: string): {
-        (extraArgs: Partial<TArgs>): TRenderer['storyResult'];
-        storyName: string;
-        args: Args;
-        play: ComposedStoryPlayFn<TRenderer, TArgs>;
-        parameters: Parameters;
-    };
+    (storyAnnotations: AnnotatedStoryFn<TRenderer, TArgs> | StoryAnnotations<TRenderer, TArgs>, componentAnnotations: ComponentAnnotations<TRenderer, TArgs>, projectAnnotations: ProjectAnnotations<TRenderer>, exportsName?: string): ComposedStoryFn;
 }
 
-export { API_ActiveTabsType, API_Addon, API_BaseEntry, API_Collection, API_ComponentEntry, API_ComposedRef, API_ComposedRefUpdate, API_DocsEntry, API_Group, API_GroupEntry, API_HashEntry, API_IframeRenderer, API_IndexHash, API_Layout, API_LeafEntry, API_LoadedRefData, API_MatchOptions, API_Notification, API_OptionsData, API_PanelPositions, API_Panels, API_PreparedStoryIndex, API_Provider, API_ProviderData, API_RefId, API_RefUrl, API_Refs, API_ReleaseNotes, API_RenderOptions, API_Root, API_RootEntry, API_RouteOptions, API_SetRefData, API_Settings, API_SidebarOptions, API_StateMerger, API_StatusObject, API_StatusState, API_StatusUpdate, API_StatusValue, API_Story, API_StoryEntry, API_StoryMapper, API_UI, API_UIOptions, API_UnknownEntries, API_Version, API_Versions$1 as API_Versions, API_ViewMode, Addon_AddStoryArgs, Addon_Annotations, Addon_ArgType, Addon_ArgsStoryFn, Addon_BaseAnnotations, Addon_BaseDecorators, Addon_BaseMeta, Addon_BaseStoryFn, Addon_BaseStoryObject, Addon_BaseType, Addon_ClientApiAddon, Addon_ClientApiAddons, Addon_ClientApiReturnFn, Addon_ClientStoryApi, Addon_Collection, Addon_Comparator, Addon_Config, Addon_DecoratorFunction, Addon_Elements, Addon_LegacyStoryFn, Addon_LoadFn, Addon_Loadable, Addon_Loader, Addon_LoaderFunction, Addon_Loaders, Addon_MakeDecoratorResult, Addon_OptionsParameter, Addon_OptionsParameterV7, Addon_PageType, Addon_PartialStoryFn, Addon_RenderOptions, Addon_RequireContext, Addon_StoryApi, Addon_StoryContext, Addon_StoryContextUpdate, Addon_StoryFn, Addon_StorySortComparator, Addon_StorySortComparatorV7, Addon_StorySortMethod, Addon_StorySortObjectParameter, Addon_StorySortParameter, Addon_StorySortParameterV7, Addon_StoryWrapper, Addon_ToolbarConfig, Addon_Type, Addon_Types, Addon_TypesEnum, Addon_TypesMapping, Addon_WrapperSettings, Addon_WrapperType, Addons_ArgTypes, AnnotatedStoryFn, ArgTypes, ArgTypesEnhancer, Args, ArgsEnhancer, ArgsFromMeta, ArgsStoryFn, BaseAnnotations, BaseIndexEntry, BaseStory, BoundStory, Builder, BuilderName, BuilderOptions, BuilderResult, BuilderStats, Builder_EnvsRaw, Builder_Unpromise, Builder_WithRequiredProperty, CLIOptions, CSFFile, ComponentAnnotations, ComponentId, ComponentTitle, ComposeStoryFn, ComposedStory, ComposedStoryPlayContext, ComposedStoryPlayFn, Conditional, CoreCommon_AddonEntry, CoreCommon_AddonInfo, CoreCommon_OptionsEntry, CoreCommon_ResolvedAddonPreset, CoreCommon_ResolvedAddonVirtual, CoreCommon_StorybookInfo, CoreConfig, DecoratorApplicator, DecoratorFunction, DocsContextProps, DocsIndexEntry, DocsOptions, DocsPreparedPayload, DocsRenderFunction, Entry, GlobalTypes, Globals, IncludeExcludeOptions, IndexEntry, IndexEntryLegacy, IndexedCSFFile, IndexedStory, IndexerOptions, InputType, LegacyAnnotatedStoryFn, LegacyStoryAnnotationsOrFn, LegacyStoryFn, LoadOptions, LoadedPreset, LoaderFunction, ModuleExport, ModuleExports, ModuleImportFn, NormalizedComponentAnnotations, NormalizedProjectAnnotations, NormalizedStoriesSpecifier, NormalizedStoryAnnotations, Options, PackageJson, Parameters, PartialStoryFn, Path, PlayFunction, PlayFunctionContext, PreparedMeta, PreparedStory, PreparedStoryFn, Preset, PresetConfig, PresetProperty, PresetPropertyFn, PresetValue, Presets, PreviewAnnotation, ProjectAnnotations, ReactJSXElement, Ref, RenderContext, RenderContextCallbacks, RenderToCanvas, Renderer, RendererName, ResolvedModuleExport, ResolvedModuleExportFromType, ResolvedModuleExportType, SBArrayType, SBEnumType, SBIntersectionType, SBObjectType, SBOtherType, SBScalarType, SBType, SBUnionType, SeparatorOptions, SetGlobalsPayload, SetStoriesPayload, SetStoriesStory, SetStoriesStoryData, Stats, StepFunction, StepLabel, StepRunner, Store_CSFExports, StoriesEntry, StoriesWithPartialProps, StoryAnnotations, StoryAnnotationsOrFn, StoryContext, StoryContextForEnhancers, StoryContextForLoaders, StoryContextUpdate, StoryFn, StoryId, StoryIdentifier, StoryIndex, StoryIndexEntry, StoryIndexV2, StoryIndexV3, StoryIndexer, StoryKind, StoryName, StoryPreparedPayload, StoryRenderOptions, StorybookConfig, StorybookConfigOptions, StorybookInternalParameters, StorybookParameters, StrictArgTypes, StrictArgs, StrictGlobalTypes, StrictInputType, Tag, TeardownRenderToCanvas, TypescriptOptions, V3CompatIndexEntry, VersionCheck, ViewMode, WebRenderer };
+export { API_ActiveTabsType, API_Addon, API_BaseEntry, API_Collection, API_ComponentEntry, API_ComposedRef, API_ComposedRefUpdate, API_DocsEntry, API_Group, API_GroupEntry, API_HashEntry, API_IframeRenderer, API_IndexHash, API_Layout, API_LeafEntry, API_LoadedRefData, API_MatchOptions, API_Notification, API_OptionsData, API_PanelPositions, API_Panels, API_PreparedStoryIndex, API_Provider, API_ProviderData, API_RefId, API_RefUrl, API_Refs, API_ReleaseNotes, API_RenderOptions, API_Root, API_RootEntry, API_RouteOptions, API_SetRefData, API_Settings, API_SidebarOptions, API_StateMerger, API_StatusObject, API_StatusState, API_StatusUpdate, API_StatusValue, API_Story, API_StoryEntry, API_StoryMapper, API_UI, API_UIOptions, API_UnknownEntries, API_Version, API_Versions$1 as API_Versions, API_ViewMode, Addon_AddStoryArgs, Addon_Annotations, Addon_ArgType, Addon_ArgsStoryFn, Addon_BaseAnnotations, Addon_BaseDecorators, Addon_BaseMeta, Addon_BaseStoryFn, Addon_BaseStoryObject, Addon_BaseType, Addon_ClientApiAddon, Addon_ClientApiAddons, Addon_ClientApiReturnFn, Addon_ClientStoryApi, Addon_Collection, Addon_Comparator, Addon_Config, Addon_DecoratorFunction, Addon_Elements, Addon_LegacyStoryFn, Addon_LoadFn, Addon_Loadable, Addon_Loader, Addon_LoaderFunction, Addon_Loaders, Addon_MakeDecoratorResult, Addon_OptionsParameter, Addon_OptionsParameterV7, Addon_PageType, Addon_PartialStoryFn, Addon_RenderOptions, Addon_RequireContext, Addon_StoryApi, Addon_StoryContext, Addon_StoryContextUpdate, Addon_StoryFn, Addon_StorySortComparator, Addon_StorySortComparatorV7, Addon_StorySortMethod, Addon_StorySortObjectParameter, Addon_StorySortParameter, Addon_StorySortParameterV7, Addon_StoryWrapper, Addon_ToolbarConfig, Addon_Type, Addon_Types, Addon_TypesEnum, Addon_TypesMapping, Addon_WrapperSettings, Addon_WrapperType, Addons_ArgTypes, AnnotatedStoryFn, ArgTypes, ArgTypesEnhancer, Args, ArgsEnhancer, ArgsFromMeta, ArgsStoryFn, BaseAnnotations, BaseIndexEntry, BaseIndexInput, BaseStory, BoundStory, Builder, BuilderName, BuilderOptions, BuilderResult, BuilderStats, Builder_EnvsRaw, Builder_Unpromise, Builder_WithRequiredProperty, CLIOptions, CSFFile, ComponentAnnotations, ComponentId, ComponentTitle, ComposeStoryFn, ComposedStoryFn, ComposedStoryPlayContext, ComposedStoryPlayFn, Conditional, CoreCommon_AddonEntry, CoreCommon_AddonInfo, CoreCommon_OptionsEntry, CoreCommon_ResolvedAddonPreset, CoreCommon_ResolvedAddonVirtual, CoreCommon_StorybookInfo, CoreConfig, DecoratorApplicator, DecoratorFunction, DeprecatedIndexer, DocsContextProps, DocsIndexEntry, DocsIndexInput, DocsOptions, DocsPreparedPayload, DocsRenderFunction, Entry, GlobalTypes, Globals, IncludeExcludeOptions, IndexEntry, IndexEntryLegacy, IndexInput, IndexedCSFFile, IndexedStory, Indexer, IndexerOptions, InputType, LegacyAnnotatedStoryFn, LegacyStoryAnnotationsOrFn, LegacyStoryFn, LoadOptions, LoadedPreset, LoaderFunction, ModuleExport, ModuleExports, ModuleImportFn, NormalizedComponentAnnotations, NormalizedProjectAnnotations, NormalizedStoriesSpecifier, NormalizedStoryAnnotations, Options, PackageJson, Parameters, PartialArgsStoryFn, PartialStoryFn, Path, PlayFunction, PlayFunctionContext, PreparedMeta, PreparedStory, Preset, PresetConfig, PresetProperty, PresetPropertyFn, PresetValue, Presets, PreviewAnnotation, ProjectAnnotations, ReactJSXElement, Ref, RenderContext, RenderContextCallbacks, RenderToCanvas, Renderer, RendererName, ResolvedModuleExport, ResolvedModuleExportFromType, ResolvedModuleExportType, SBArrayType, SBEnumType, SBIntersectionType, SBObjectType, SBOtherType, SBScalarType, SBType, SBUnionType, SeparatorOptions, SetGlobalsPayload, SetStoriesPayload, SetStoriesStory, SetStoriesStoryData, Stats, StepFunction, StepLabel, StepRunner, Store_CSFExports, StoriesEntry, StoriesWithPartialProps, StoryAnnotations, StoryAnnotationsOrFn, StoryContext, StoryContextForEnhancers, StoryContextForLoaders, StoryContextUpdate, StoryFn, StoryId, StoryIdentifier, StoryIndex, StoryIndexEntry, StoryIndexInput, StoryIndexV2, StoryIndexV3, StoryIndexer, StoryKind, StoryName, StoryPreparedPayload, StoryRenderOptions, StorybookConfig, StorybookConfigOptions, StorybookInternalParameters, StorybookParameters, StrictArgTypes, StrictArgs, StrictGlobalTypes, StrictInputType, Tag, TeardownRenderToCanvas, TypescriptOptions, V3CompatIndexEntry, VersionCheck, ViewMode, WebRenderer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storybook/types",
-  "version": "7.2.3",
+  "version": "7.3.0",
   "description": "Core Storybook TS Types",
   "keywords": [
     "storybook"
@@ -43,7 +43,7 @@
     "prep": "../../../scripts/prepare/bundle.ts"
   },
   "dependencies": {
-    "@storybook/channels": "7.2.3",
+    "@storybook/channels": "7.3.0",
     "@types/babel__core": "^7.0.0",
     "@types/express": "^4.7.0",
     "file-system-cache": "2.3.0"