.each runtime

Author: mrginglymus

code/core/package.json

@@ -540,6 +540,7 @@
     "es-toolkit": "^1.36.0",
     "esbuild": "^0.18.0 || ^0.19.0 || ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.23.0 || ^0.24.0 || ^0.25.0",
     "execa": "^8.0.1",
+    "fast-printf": "^1.6.10",
     "fd-package-json": "^1.2.0",
     "fetch-retry": "^6.0.0",
     "find-cache-dir": "^5.0.0",

code/core/src/csf/csf-factories.ts

@@ -11,6 +11,8 @@ import type {
   TestFunction,
 } from 'storybook/internal/types';
 
+import { printf } from 'fast-printf';
+
 import {
   combineParameters,
   composeConfigs,
@@ -20,6 +22,7 @@ import {
 } from '../preview-api/index';
 import { mountDestructured } from '../preview-api/modules/preview-web/render/mount-utils';
 import { getCoreAnnotations } from './core-annotations';
+import type { EachAnnotationsFunction, EachTestFunction } from './story';
 
 export interface Preview<TRenderer extends Renderer = Renderer> {
   readonly _tag: 'Preview';
@@ -151,6 +154,18 @@ export interface Story<
     annotations: StoryAnnotations<TRenderer, TRenderer['args']>,
     fn: TestFunction<TRenderer>
   ): void;
+  each<T extends any[]>(
+    parameters: ReadonlyArray<T>
+  ): (name: string, fn: EachTestFunction<T, TRenderer>) => void;
+  each<T extends any[]>(
+    parameters: ReadonlyArray<T>
+  ): (
+    name: string,
+    annotations:
+      | StoryAnnotations<TRenderer, TRenderer['args']>
+      | EachAnnotationsFunction<T, TRenderer, TRenderer['args']>,
+    fn: EachTestFunction<T, TRenderer>
+  ) => void;
 }
 
 export function isStory<TRenderer extends Renderer>(input: unknown): input is Story<TRenderer> {
@@ -223,6 +238,36 @@ function defineStory<
 
       return test as unknown as void;
     },
+    each<T extends any[]>(
+      parameters: ReadonlyArray<T>
+    ): (
+      name: string,
+      overridesOrTestFn:
+        | EachTestFunction<T, TRenderer>
+        | StoryAnnotations<TRenderer, TRenderer['args']>
+        | EachAnnotationsFunction<T, TRenderer, TRenderer['args']>,
+      testFn?: EachTestFunction<T, TRenderer>
+    ) => void {
+      return (name, overridesOrTestFn, testFn) => {
+        parameters.forEach((parameter) => {
+          const testFunction: TestFunction<TRenderer, TRenderer['args']> = (context) =>
+            (testFn ?? (overridesOrTestFn as EachTestFunction<T, TRenderer>))(
+              context,
+              ...parameter
+            );
+          const annotations: StoryAnnotations<TRenderer, TRenderer['args']> =
+            testFn === undefined
+              ? {}
+              : typeof overridesOrTestFn === 'function'
+                ? (overridesOrTestFn as EachAnnotationsFunction<T, TRenderer, TRenderer['args']>)(
+                    ...parameter
+                  )
+                : overridesOrTestFn;
+
+          this.test(printf(name, ...parameter), annotations, testFunction);
+        });
+      };
+    },
     extend<TInput extends StoryAnnotations<TRenderer, TRenderer['args']>>(input: TInput) {
       return defineStory(
         {

code/core/src/csf/story.ts

@@ -288,6 +288,18 @@ export type TestFunction<TRenderer extends Renderer = Renderer, TArgs = TRendere
   context: StoryContext<TRenderer, TArgs>
 ) => Promise<void> | void;
 
+export type EachTestFunction<
+  Parameters extends any[],
+  TRenderer extends Renderer = Renderer,
+  TArgs = TRenderer['args'],
+> = (context: StoryContext<TRenderer, TArgs>, ...parameters: Parameters) => Promise<void> | void;
+
+export type EachAnnotationsFunction<
+  Parameters extends any[],
+  TRenderer extends Renderer = Renderer,
+  TArgs = TRenderer['args'],
+> = (...parameters: Parameters) => StoryAnnotations<TRenderer, TArgs>;
+
 // This is the type of story function passed to a decorator -- does not rely on being passed any context
 export type PartialStoryFn<TRenderer extends Renderer = Renderer, TArgs = Args> = (
   update?: StoryContextUpdate<Partial<TArgs>>

code/yarn.lock

@@ -14955,6 +14955,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"fast-printf@npm:^1.6.10":
+  version: 1.6.10
+  resolution: "fast-printf@npm:1.6.10"
+  checksum: 10c0/630cccbef8349a6eeada9958c9391e9d14b5bd9527dd28d9e7e9f295b006c640ddca8fc2470cff55ea5c6c92ca530488bbadbf7c24f4852ad8c34d9155da9d75
+  languageName: node
+  linkType: hard
+
 "fast-sourcemap-concat@npm:^2.1.0":
   version: 2.1.1
   resolution: "fast-sourcemap-concat@npm:2.1.1"
@@ -25040,6 +25047,7 @@ __metadata:
     esbuild: "npm:^0.18.0 || ^0.19.0 || ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.23.0 || ^0.24.0 || ^0.25.0"
     esbuild-register: "npm:^3.5.0"
     execa: "npm:^8.0.1"
+    fast-printf: "npm:^1.6.10"
     fd-package-json: "npm:^1.2.0"
     fetch-retry: "npm:^6.0.0"
     find-cache-dir: "npm:^5.0.0"