Feature: Add experimental status API

code/lib/manager-api/src/index.tsx

@@ -57,6 +57,7 @@ import * as releaseNotes from './modules/release-notes';
 // eslint-disable-next-line import/no-cycle
 import * as stories from './modules/stories';
 
+// eslint-disable-next-line import/no-cycle
 import * as refs from './modules/refs';
 import * as layout from './modules/layout';
 import * as shortcuts from './modules/shortcuts';

code/lib/manager-api/src/modules/stories.ts

@@ -50,6 +50,7 @@ import {
 } from '../lib/stories';
 
 import type { ComposedRef, ModuleFn } from '../index';
+import { merge } from '../index';
 
 const { FEATURES, fetch } = global;
 const STORY_INDEX_PATH = './index.json';
@@ -61,11 +62,22 @@ type ViewMode = 'story' | 'info' | 'settings' | string | undefined;
 type StoryUpdate = Partial<
   Pick<API_StoryEntry, 'prepared' | 'parameters' | 'initialArgs' | 'argTypes' | 'args'>
 >;
+interface StatusObject {
+  status: 'pending' | 'success' | 'error' | 'warn' | 'unknown';
+  title: string;
+  description: string;
+  data?: any;
+}
+
+type StatusState = Record<StoryId, Record<string, StatusObject>>;
+type StatusUpdate = Record<StoryId, StatusObject>;
+
 type DocsUpdate = Partial<Pick<API_DocsEntry, 'prepared' | 'parameters'>>;
 
 export interface SubState extends API_LoadedRefData {
   storyId: StoryId;
   viewMode: ViewMode;
+  status: StatusState;
 }
 
 export interface SubAPI {
@@ -102,6 +114,14 @@ export interface SubAPI {
   updateStory: (storyId: StoryId, update: StoryUpdate, ref?: API_ComposedRef) => Promise<void>;
   updateDocs: (storyId: StoryId, update: DocsUpdate, ref?: API_ComposedRef) => Promise<void>;
   setPreviewInitialized: (ref?: ComposedRef) => Promise<void>;
+  /**
+   * Updates the status of a collection of stories.
+   *
+   * @param {string} addonId - The ID of the addon to update.
+   * @param {StatusUpdate} update - An object containing the updated status information.
+   * @returns {Promise<void>} A promise that resolves when the status has been updated.
+   */
+  experimental_updateStatus: (addonId: string, update: StatusUpdate) => Promise<void>;
 }
 
 const removedOptions = ['enableShortcuts', 'theme', 'showRoots'];
@@ -406,6 +426,18 @@ export const init: ModuleFn<SubAPI, SubState, true> = ({
         fullAPI.updateRef(ref.id, { previewInitialized: true });
       }
     },
+
+    /* EXPERIMENTAL APIs */
+    experimental_updateStatus: async (id, update) => {
+      const { status } = store.getState();
+      const addition = Object.entries(update).reduce<StatusState>((acc, [storyId, value]) => {
+        acc[storyId] = acc[storyId] || {};
+        acc[storyId][id] = value;
+
+        return acc;
+      }, {});
+      await store.setState({ status: merge(status, addition) }, { persistence: 'session' });
+    },
   };
 
   const initModule = async () => {
@@ -575,6 +607,7 @@ export const init: ModuleFn<SubAPI, SubState, true> = ({
       viewMode: initialViewMode,
       hasCalledSetOptions: false,
       previewInitialized: false,
+      status: {},
     },
     init: initModule,
   };

code/lib/manager-api/src/tests/stories.test.ts

@@ -21,6 +21,7 @@ import { Channel } from '@storybook/channels';
 import type { API_StoryEntry, StoryIndex, API_PreparedStoryIndex } from '@storybook/types';
 import { getEventMetadata } from '../lib/events';
 
+import type { SubAPI } from '../modules/stories';
 import { init as initStories } from '../modules/stories';
 import type Store from '../store';
 import type { ModuleArgs } from '..';
@@ -125,12 +126,14 @@ describe('stories API', () => {
       viewMode: 'story',
     } as ModuleArgs);
 
-    expect(state).toEqual({
-      previewInitialized: false,
-      storyId: 'id',
-      viewMode: 'story',
-      hasCalledSetOptions: false,
-    });
+    expect(state).toEqual(
+      expect.objectContaining({
+        previewInitialized: false,
+        storyId: 'id',
+        viewMode: 'story',
+        hasCalledSetOptions: false,
+      })
+    );
   });
 
   describe('setIndex', () => {
@@ -1629,4 +1632,103 @@ describe('stories API', () => {
       );
     });
   });
+
+  describe('experimental_updateStatus', () => {
+    it('is included in the initial state', () => {
+      const { state } = initStoriesAndSetState({
+        storyId: 'id',
+        viewMode: 'story',
+      } as ModuleArgs);
+
+      expect(state).toEqual(
+        expect.objectContaining({
+          status: {},
+        })
+      );
+    });
+
+    it('updates a story', async () => {
+      const fullAPI = Object.assign(new EventEmitter());
+      const navigate = jest.fn();
+      const store = createMockStore();
+
+      const { init, api } = initStoriesAndSetState({ store, navigate, provider, fullAPI } as any);
+
+      const API: SubAPI = Object.assign(fullAPI, api, {
+        setIndex: jest.fn(),
+        findRef: jest.fn(),
+        setRef: jest.fn(),
+      });
+
+      await init();
+
+      await expect(
+        API.experimental_updateStatus('a-addon-id', {
+          'a-story-id': {
+            status: 'pending',
+            title: 'an addon title',
+            description: 'an addon description',
+          },
+        })
+      ).resolves.not.toThrow();
+
+      expect(store.getState().status).toMatchInlineSnapshot(`
+        Object {
+          "a-story-id": Object {
+            "a-addon-id": Object {
+              "description": "an addon description",
+              "status": "pending",
+              "title": "an addon title",
+            },
+          },
+        }
+      `);
+    });
+
+    it('updates multiple stories', async () => {
+      const fullAPI = Object.assign(new EventEmitter());
+      const navigate = jest.fn();
+      const store = createMockStore();
+
+      const { init, api } = initStoriesAndSetState({ store, navigate, provider, fullAPI } as any);
+
+      const API: SubAPI = Object.assign(fullAPI, api, {
+        setIndex: jest.fn(),
+        findRef: jest.fn(),
+        setRef: jest.fn(),
+      });
+
+      await init();
+
+      await expect(
+        API.experimental_updateStatus('a-addon-id', {
+          'a-story-id': {
+            status: 'pending',
+            title: 'an addon title',
+            description: 'an addon description',
+          },
+          'another-story-id': { status: 'success', title: 'a addon title', description: '' },
+        })
+      ).resolves.not.toThrow();
+
+      expect(store.getState().status).toMatchInlineSnapshot(`
+        Object {
+          "a-story-id": Object {
+            "a-addon-id": Object {
+              "description": "an addon description",
+              "status": "pending",
+              "title": "an addon title",
+            },
+          },
+          "another-story-id": Object {
+            "a-addon-id": Object {
+              "description": "",
+              "status": "success",
+              "title": "a addon title",
+            },
+          },
+        }
+      `);
+    });
+  });
 });