Core: Add JSDoc comments to manager-api APIs

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

@@ -1,4 +1,10 @@
-import type { Addon_Types, API_Collection, API_Panels, API_StateMerger } from '@storybook/types';
+import type {
+  Addon_Type,
+  Addon_Types,
+  API_Collection,
+  API_Panels,
+  API_StateMerger,
+} from '@storybook/types';
 import { Addon_TypesEnum } from '@storybook/types';
 import type { ModuleFn } from '../index';
 import type { Options } from '../store';
@@ -9,16 +15,61 @@ export interface SubState {
 }
 
 export interface SubAPI {
-  getElements: <T>(type: Addon_Types) => API_Collection<T>;
+  /**
+   * Returns a collection of elements of a specific type.
+   * @protected This is used internally in storybook's manager.
+   * @template T - The type of the elements in the collection.
+   * @param {Addon_Types} type - The type of the elements to retrieve.
+   * @returns {API_Collection<T>} - A collection of elements of the specified type.
+   */
+  getElements: <T = Addon_Type>(type: Addon_Types) => API_Collection<T>;
+  /**
+   * Returns a collection of all panels.
+   * This is the same as calling getElements('panel')
+   * @protected This is used internally in storybook's manager.
+   * @deprecated please use getElements('panel') instead. This API will be removed in storybook 8.0.
+   * @returns {API_Panels} - A collection of all panels.
+   */
   getPanels: () => API_Panels;
+  /**
+   * Returns a collection of panels currently enabled for the selected story.
+   * @protected This is used internally in storybook's manager.
+   * @deprecated please use getElements('panel') instead, and do the filtering manually. This API will be removed in storybook 8.0.
+   * @returns {API_Panels} - A collection of all panels.
+   */
   getStoryPanels: () => API_Panels;
+  /**
+   * Returns the id of the currently selected panel.
+   * @returns {string} - The ID of the currently selected panel.
+   */
   getSelectedPanel: () => string;
+  /**
+   * Sets the currently selected panel via it's ID.
+   * @param {string} panelName - The ID of the panel to select.
+   * @returns {void}
+   */
   setSelectedPanel: (panelName: string) => void;
+  /**
+   * Sets the state of an addon with the given ID.
+   * @template S - The type of the addon state.
+   * @param {string} addonId - The ID of the addon to set the state for.
+   * @param {S | API_StateMerger<S>} newStateOrMerger - The new state to set, or a function that merges the current state with the new state.
+   * @param {Options} [options] - Optional options for the state update.
+   * @deprecated This API might get dropped, if you are using this, please file an issue.
+   * @returns {Promise<S>} - A promise that resolves with the new state after it has been set.
+   */
   setAddonState<S>(
     addonId: string,
     newStateOrMerger: S | API_StateMerger<S>,
     options?: Options
   ): Promise<S>;
+  /**
+   * Returns the state of an addon with the given ID.
+   * @template S - The type of the addon state.
+   * @param {string} addonId - The ID of the addon to get the state for.
+   * @deprecated This API might get dropped, if you are using this, please file an issue.
+   * @returns {S} - The state of the addon with the given ID.
+   */
   getAddonState<S>(addonId: string): S;
 }
 
@@ -40,7 +91,7 @@ export const init: ModuleFn<SubAPI, SubState> = ({ provider, store, fullAPI }) =
     getElements: (type) => provider.getElements(type),
     getPanels: () => api.getElements(Addon_TypesEnum.PANEL),
     getStoryPanels: () => {
-      const allPanels = api.getPanels();
+      const allPanels = api.getElements(Addon_TypesEnum.PANEL);
       const { storyId } = store.getState();
       const story = fullAPI.getData(storyId);
 
@@ -63,7 +114,7 @@ export const init: ModuleFn<SubAPI, SubState> = ({ provider, store, fullAPI }) =
     },
     getSelectedPanel: () => {
       const { selectedPanel } = store.getState();
-      return ensurePanel(api.getPanels(), selectedPanel, selectedPanel);
+      return ensurePanel(api.getElements(Addon_TypesEnum.PANEL), selectedPanel, selectedPanel);
     },
     setSelectedPanel: (panelName) => {
       store.setState({ selectedPanel: panelName }, { persistence: 'session' });
@@ -93,7 +144,10 @@ export const init: ModuleFn<SubAPI, SubState> = ({ provider, store, fullAPI }) =
   return {
     api,
     state: {
-      selectedPanel: ensurePanel(api.getPanels(), store.getState().selectedPanel),
+      selectedPanel: ensurePanel(
+        api.getElements(Addon_TypesEnum.PANEL),
+        store.getState().selectedPanel
+      ),
       addons: {},
     },
   };

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

@@ -6,12 +6,46 @@ import type { API_Provider } from '@storybook/types';
 import type { API, ModuleFn } from '../index';
 
 export interface SubAPI {
+  /**
+   * Returns the channel object.
+   * @protected Please do not use, it's for internal use only.
+   */
   getChannel: () => API_Provider<API>['channel'];
-  on: (type: string, cb: Listener) => () => void;
-  off: (type: string, cb: Listener) => void;
+  /**
+   * Adds a listener to the channel for the given event type.
+   * Returns a function that can be called to remove the listener.
+   * @param type - The event type to listen for. If using a core event, import it from `@storybook/core-events`.
+   * @param handler - The callback function to be called when the event is emitted.
+   * @returns A function that can be called to remove the listener.
+   */
+  on: (type: string, handler: Listener) => () => void;
+  /**
+   * Removes a listener from the channel for the given event type.
+   * @param type - The event type to remove the listener from. If using a core event, import it from `@storybook/core-events`.
+   * @param handler - The callback function to be removed.
+   */
+  off: (type: string, handler: Listener) => void;
+  /**
+   * Emits an event on the channel for the given event type.
+   * @param type - The event type to emit. If using a core event, import it from `@storybook/core-events`.
+   * @param args - The arguments to pass to the event listener.
+   */
   emit: (type: string, ...args: any[]) => void;
-  once: (type: string, cb: Listener) => void;
+  /**
+   * Adds a one-time listener to the channel for the given event type.
+   * @param type - The event type to listen for. If using a core event, import it from `@storybook/core-events`.
+   * @param handler - The callback function to be called when the event is emitted.
+   */
+  once: (type: string, handler: Listener) => void;
+  /**
+   * Emits an event to collapse all stories in the UI.
+   * @deprecated Use `emit(STORIES_COLLAPSE_ALL)` instead. This API will be removed in Storybook 8.0.
+   */
   collapseAll: () => void;
+  /**
+   * Emits an event to expand all stories in the UI.
+   * @deprecated Use `emit(STORIES_EXPAND_ALL)` instead. This API will be removed in Storybook 8.0.
+   */
   expandAll: () => void;
 }
 
@@ -20,13 +54,13 @@ export type SubState = Record<string, never>;
 export const init: ModuleFn<SubAPI, SubState> = ({ provider }) => {
   const api: SubAPI = {
     getChannel: () => provider.channel,
-    on: (type, cb) => {
-      provider.channel.addListener(type, cb);
+    on: (type, handler) => {
+      provider.channel.on(type, handler);
 
-      return () => provider.channel.removeListener(type, cb);
+      return () => provider.channel.off(type, handler);
     },
-    off: (type, cb) => provider.channel.removeListener(type, cb),
-    once: (type, cb) => provider.channel.once(type, cb),
+    off: (type, handler) => provider.channel.off(type, handler),
+    once: (type, handler) => provider.channel.once(type, handler),
     emit: (type, data, ...args) => {
       if (
         data?.options?.target &&
@@ -42,7 +76,7 @@ export const init: ModuleFn<SubAPI, SubState> = ({ provider }) => {
     },
 
     collapseAll: () => {
-      provider.channel.emit(STORIES_COLLAPSE_ALL, {});
+      api.emit(STORIES_COLLAPSE_ALL, {});
     },
     expandAll: () => {
       api.emit(STORIES_EXPAND_ALL);

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

@@ -14,8 +14,21 @@ export interface SubState {
 }
 
 export interface SubAPI {
+  /**
+   * Returns the current global data object.
+   * @returns {Globals} The current global data object.
+   */
   getGlobals: () => Globals;
+  /**
+   * Returns the current global types object.
+   * @returns {GlobalTypes} The current global types object.
+   */
   getGlobalTypes: () => GlobalTypes;
+  /**
+   * Updates the current global data object with the provided new global data object.
+   * @param {Globals} newGlobals - The new global data object to update with.
+   * @returns {void}
+   */
   updateGlobals: (newGlobals: Globals) => void;
 }
 

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

@@ -25,11 +25,35 @@ export interface SubState {
 }
 
 export interface SubAPI {
+  /**
+   * Toggles the fullscreen mode of the Storybook UI.
+   * @param toggled - Optional boolean value to set the fullscreen mode to. If not provided, it will toggle the current state.
+   */
   toggleFullscreen: (toggled?: boolean) => void;
+  /**
+   * Toggles the visibility of the panel in the Storybook UI.
+   * @param toggled - Optional boolean value to set the panel visibility to. If not provided, it will toggle the current state.
+   */
   togglePanel: (toggled?: boolean) => void;
+  /**
+   * Toggles the position of the panel in the Storybook UI.
+   * @param position - Optional string value to set the panel position to. If not provided, it will toggle between 'bottom' and 'right'.
+   */
   togglePanelPosition: (position?: API_PanelPositions) => void;
+  /**
+   * Toggles the visibility of the navigation bar in the Storybook UI.
+   * @param toggled - Optional boolean value to set the navigation bar visibility to. If not provided, it will toggle the current state.
+   */
   toggleNav: (toggled?: boolean) => void;
+  /**
+   * Toggles the visibility of the toolbar in the Storybook UI.
+   * @param toggled - Optional boolean value to set the toolbar visibility to. If not provided, it will toggle the current state.
+   */
   toggleToolbar: (toggled?: boolean) => void;
+  /**
+   * Sets the options for the Storybook UI.
+   * @param options - An object containing the options to set.
+   */
   setOptions: (options: any) => void;
 }
 

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

@@ -5,8 +5,20 @@ export interface SubState {
   notifications: API_Notification[];
 }
 
+/**
+ * The API for managing notifications.
+ */
 export interface SubAPI {
+  /**
+   * Adds a new notification to the list of notifications.
+   * If a notification with the same ID already exists, it will be replaced.
+   * @param notification - The notification to add.
+   */
   addNotification: (notification: API_Notification) => void;
+  /**
+   * Removes a notification from the list of notifications.
+   * @param id - The ID of the notification to remove.
+   */
   clearNotification: (id: string) => void;
 }
 

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

@@ -1,8 +1,8 @@
-import type { API_Provider } from '@storybook/types';
-import type { API, ModuleFn } from '../index';
+import type { API_IframeRenderer } from '@storybook/types';
+import type { ModuleFn } from '../index';
 
 export interface SubAPI {
-  renderPreview?: API_Provider<API>['renderPreview'];
+  renderPreview?: API_IframeRenderer;
 }
 
 export const init: ModuleFn<SubAPI, {}, true> = ({ provider, fullAPI }) => {

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

@@ -27,12 +27,47 @@ export interface SubState {
 }
 
 export interface SubAPI {
+  /**
+   * Finds a composed ref by its source.
+   * @param {string} source - The source/URL of the composed ref.
+   * @returns {API_ComposedRef} - The composed ref object.
+   */
   findRef: (source: string) => API_ComposedRef;
+  /**
+   * Sets a composed ref by its ID and data.
+   * @param {string} id - The ID of the composed ref.
+   * @param {API_SetRefData} data - The data to set for the composed ref.
+   * @param {boolean} [ready] - Whether the composed ref is ready.
+   */
   setRef: (id: string, data: API_SetRefData, ready?: boolean) => void;
+  /**
+   * Updates a composed ref by its ID and update object.
+   * @param {string} id - The ID of the composed ref.
+   * @param {API_ComposedRefUpdate} ref - The update object for the composed ref.
+   */
   updateRef: (id: string, ref: API_ComposedRefUpdate) => void;
+  /**
+   * Gets all composed refs.
+   * @returns {API_Refs} - The composed refs object.
+   */
   getRefs: () => API_Refs;
+  /**
+   * Checks if a composed ref is valid.
+   * @param {API_SetRefData} ref - The composed ref to check.
+   * @returns {Promise<void>} - A promise that resolves when the check is complete.
+   */
   checkRef: (ref: API_SetRefData) => Promise<void>;
+  /**
+   * Changes the version of a composed ref by its ID and URL.
+   * @param {string} id - The ID of the composed ref.
+   * @param {string} url - The new URL for the composed ref.
+   */
   changeRefVersion: (id: string, url: string) => void;
+  /**
+   * Changes the state of a composed ref by its ID and previewInitialized flag.
+   * @param {string} id - The ID of the composed ref.
+   * @param {boolean} previewInitialized - The new previewInitialized flag for the composed ref.
+   */
   changeRefState: (id: string, previewInitialized: boolean) => void;
 }
 

code/lib/manager-api/src/modules/release-notes.ts

@@ -15,8 +15,20 @@ const getReleaseNotesData = memoize(1)((): API_ReleaseNotes => {
 });
 
 export interface SubAPI {
+  /**
+   * Returns the current version of the release notes.
+   * @returns {string} The current version of the release notes.
+   */
   releaseNotesVersion: () => string;
+  /**
+   * Sets the release notes as viewed.
+   * @returns {void}
+   */
   setDidViewReleaseNotes: () => void;
+  /**
+   * Determines whether to show the release notes on launch.
+   * @returns {boolean} Whether to show the release notes on launch.
+   */
   showReleaseNotesOnLaunch: () => boolean;
 }
 

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

@@ -2,9 +2,27 @@ import type { API_Settings } from '@storybook/types';
 import type { ModuleFn } from '../index';
 
 export interface SubAPI {
-  changeSettingsTab: (tab: string) => void;
+  /**
+   * Changes the active settings tab.
+   * @param path - The path of the settings page to navigate to. The path NOT should include the `/settings` prefix.
+   * @example  changeSettingsTab(`about`).
+   */
+  changeSettingsTab: (path: string) => void;
+  /**
+   * Closes the settings screen and returns to the last tracked story or the first story.
+   */
   closeSettings: () => void;
+  /**
+   * Checks if the settings screen is currently active.
+   * @returns A boolean indicating whether the settings screen is active.
+   */
   isSettingsScreenActive: () => boolean;
+  /**
+   * Navigates to the specified settings page.
+   * @param path - The path of the settings page to navigate to. The path should include the `/settings` prefix.
+   * @example  navigateToSettingsPage(`/settings/about`).
+   * @deprecated Use `changeSettingsTab` instead.
+   */
   navigateToSettingsPage: (path: string) => Promise<void>;
 }
 
@@ -29,8 +47,8 @@ export const init: ModuleFn<SubAPI, SubState> = ({ store, navigate, fullAPI }) =
         fullAPI.selectFirstStory();
       }
     },
-    changeSettingsTab: (tab: string) => {
-      navigate(`/settings/${tab}`);
+    changeSettingsTab: (path: string) => {
+      navigate(`/settings/${path}`);
     },
     isSettingsScreenActive,
     navigateToSettingsPage: async (path) => {