diff --git a/code/lib/manager-api/src/modules/addons.ts b/code/lib/manager-api/src/modules/addons.ts index 74c4bb7afb96..fad78ddf8aa9 100644 --- a/code/lib/manager-api/src/modules/addons.ts +++ b/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: (type: Addon_Types) => API_Collection; + /** + * 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} - A collection of elements of the specified type. + */ + getElements: (type: Addon_Types) => API_Collection; + /** + * 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} 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} - A promise that resolves with the new state after it has been set. + */ setAddonState( addonId: string, newStateOrMerger: S | API_StateMerger, options?: Options ): Promise; + /** + * 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(addonId: string): S; } @@ -40,7 +91,7 @@ export const init: ModuleFn = ({ 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 = ({ 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 = ({ provider, store, fullAPI }) = return { api, state: { - selectedPanel: ensurePanel(api.getPanels(), store.getState().selectedPanel), + selectedPanel: ensurePanel( + api.getElements(Addon_TypesEnum.PANEL), + store.getState().selectedPanel + ), addons: {}, }, }; diff --git a/code/lib/manager-api/src/modules/channel.ts b/code/lib/manager-api/src/modules/channel.ts index da85ebd6a7f2..01b67a003d15 100644 --- a/code/lib/manager-api/src/modules/channel.ts +++ b/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['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; export const init: ModuleFn = ({ 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 = ({ provider }) => { }, collapseAll: () => { - provider.channel.emit(STORIES_COLLAPSE_ALL, {}); + api.emit(STORIES_COLLAPSE_ALL, {}); }, expandAll: () => { api.emit(STORIES_EXPAND_ALL); diff --git a/code/lib/manager-api/src/modules/globals.ts b/code/lib/manager-api/src/modules/globals.ts index 14d68f8cbaa7..9b8d47069564 100644 --- a/code/lib/manager-api/src/modules/globals.ts +++ b/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; } diff --git a/code/lib/manager-api/src/modules/layout.ts b/code/lib/manager-api/src/modules/layout.ts index 8c23956e7380..bbe43af9863d 100644 --- a/code/lib/manager-api/src/modules/layout.ts +++ b/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; } diff --git a/code/lib/manager-api/src/modules/notifications.ts b/code/lib/manager-api/src/modules/notifications.ts index 7ef95a3862bf..b75d8879317d 100644 --- a/code/lib/manager-api/src/modules/notifications.ts +++ b/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; } diff --git a/code/lib/manager-api/src/modules/provider.ts b/code/lib/manager-api/src/modules/provider.ts index edcfc16a2ce3..272fc0d1839c 100644 --- a/code/lib/manager-api/src/modules/provider.ts +++ b/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['renderPreview']; + renderPreview?: API_IframeRenderer; } export const init: ModuleFn = ({ provider, fullAPI }) => { diff --git a/code/lib/manager-api/src/modules/refs.ts b/code/lib/manager-api/src/modules/refs.ts index 4d74127c9fe1..5fe2462dfbb3 100644 --- a/code/lib/manager-api/src/modules/refs.ts +++ b/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} - A promise that resolves when the check is complete. + */ checkRef: (ref: API_SetRefData) => Promise; + /** + * 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; } diff --git a/code/lib/manager-api/src/modules/release-notes.ts b/code/lib/manager-api/src/modules/release-notes.ts index d1546a6f47ce..2beccdc312a0 100644 --- a/code/lib/manager-api/src/modules/release-notes.ts +++ b/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; } diff --git a/code/lib/manager-api/src/modules/settings.ts b/code/lib/manager-api/src/modules/settings.ts index 452b216d8153..228640df9748 100644 --- a/code/lib/manager-api/src/modules/settings.ts +++ b/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; } @@ -29,8 +47,8 @@ export const init: ModuleFn = ({ store, navigate, fullAPI }) = fullAPI.selectFirstStory(); } }, - changeSettingsTab: (tab: string) => { - navigate(`/settings/${tab}`); + changeSettingsTab: (path: string) => { + navigate(`/settings/${path}`); }, isSettingsScreenActive, navigateToSettingsPage: async (path) => { diff --git a/code/lib/manager-api/src/modules/shortcuts.ts b/code/lib/manager-api/src/modules/shortcuts.ts index 8c7af4f146ce..8dcf942f4bc7 100644 --- a/code/lib/manager-api/src/modules/shortcuts.ts +++ b/code/lib/manager-api/src/modules/shortcuts.ts @@ -23,19 +23,69 @@ export interface SubState { } export interface SubAPI { + /** + * Returns the current shortcuts. + */ getShortcutKeys(): API_Shortcuts; + /** + * Returns the default shortcuts. + */ getDefaultShortcuts(): API_Shortcuts | API_AddonShortcutDefaults; + /** + * Returns the shortcuts for addons. + */ getAddonsShortcuts(): API_AddonShortcuts; + /** + * Returns the labels for addon shortcuts. + */ getAddonsShortcutLabels(): API_AddonShortcutLabels; + /** + * Returns the default shortcuts for addons. + */ getAddonsShortcutDefaults(): API_AddonShortcutDefaults; + /** + * Sets the shortcuts to the given value. + * @param shortcuts The new shortcuts to set. + * @returns A promise that resolves to the new shortcuts. + */ setShortcuts(shortcuts: API_Shortcuts): Promise; + /** + * Sets the shortcut for the given action to the given value. + * @param action The action to set the shortcut for. + * @param value The new shortcut to set. + * @returns A promise that resolves to the new shortcut. + */ setShortcut(action: API_Action, value: API_KeyCollection): Promise; + /** + * Sets the shortcut for the given addon to the given value. + * @param addon The addon to set the shortcut for. + * @param shortcut The new shortcut to set. + * @returns A promise that resolves to the new addon shortcut. + */ setAddonShortcut(addon: string, shortcut: API_AddonShortcut): Promise; + /** + * Restores all default shortcuts. + * @returns A promise that resolves to the new shortcuts. + */ restoreAllDefaultShortcuts(): Promise; + /** + * Restores the default shortcut for the given action. + * @param action The action to restore the default shortcut for. + * @returns A promise that resolves to the new shortcut. + */ restoreDefaultShortcut(action: API_Action): Promise; + /** + * Handles a keydown event. + * @param event The event to handle. + */ handleKeydownEvent(event: KeyboardEventLike): void; + /** + * Handles a shortcut feature. + * @param feature The feature to handle. + */ handleShortcutFeature(feature: API_Action): void; } + export type API_KeyCollection = string[]; export interface API_Shortcuts { diff --git a/code/lib/manager-api/src/modules/stories.ts b/code/lib/manager-api/src/modules/stories.ts index af1bb21faafb..1b66dfbb4525 100644 --- a/code/lib/manager-api/src/modules/stories.ts +++ b/code/lib/manager-api/src/modules/stories.ts @@ -81,38 +81,182 @@ export interface SubState extends API_LoadedRefData { } export interface SubAPI { + /** + * The `storyId` method is a reference to the `toId` function from `@storybook/csf`, which is used to generate a unique ID for a story. + * This ID is used to identify a specific story in the Storybook index. + * + * @type {typeof toId} + */ storyId: typeof toId; + /** + * Resolves a story, docs, component or group ID to its corresponding hash entry in the index. + * + * @param {StoryId} storyId - The ID of the story to resolve. + * @param {string} [refsId] - The ID of the refs to use for resolving the story. + * @returns {API_HashEntry} - The hash entry corresponding to the given story ID. + */ resolveStory: (storyId: StoryId, refsId?: string) => API_HashEntry; + /** + * Selects the first story to display in the Storybook UI. + * + * @returns {void} + */ selectFirstStory: () => void; + /** + * Selects a story to display in the Storybook UI. + * + * @param {string} [kindOrId] - The kind or ID of the story to select. + * @param {StoryId} [story] - The ID of the story to select. + * @param {Object} [obj] - An optional object containing additional options. + * @param {string} [obj.ref] - The ref ID of the story to select. + * @param {ViewMode} [obj.viewMode] - The view mode to display the story in. + * @returns {void} + */ selectStory: ( kindOrId?: string, - story?: string, + story?: StoryId, obj?: { ref?: string; viewMode?: ViewMode } ) => void; + /** + * Returns the current story's data, including its ID, kind, name, and parameters. + * + * @returns {API_LeafEntry} The current story's data. + */ getCurrentStoryData: () => API_LeafEntry; + /** + * Sets the prepared story index to the given value. + * + * @param {API_PreparedStoryIndex} index - The prepared story index to set. + * @returns {Promise} A promise that resolves when the prepared story index has been set. + */ setIndex: (index: API_PreparedStoryIndex) => Promise; + + /** + * Jumps to the next or previous component in the index. + * + * @param {Direction} direction - The direction to jump. Use -1 to jump to the previous component, and 1 to jump to the next component. + * @returns {void} + */ jumpToComponent: (direction: Direction) => void; + /** + * Jumps to the next or previous story in the story index. + * + * @param {Direction} direction - The direction to jump. Use -1 to jump to the previous story, and 1 to jump to the next story. + * @returns {void} + */ jumpToStory: (direction: Direction) => void; + /** + * Returns the data for the given story ID and optional ref ID. + * + * @param {StoryId} storyId - The ID of the story to retrieve data for. + * @param {string} [refId] - The ID of the ref to retrieve data for. If not provided, retrieves data for the default ref. + * @returns {API_LeafEntry} The data for the given story ID and optional ref ID. + */ getData: (storyId: StoryId, refId?: string) => API_LeafEntry; + /** + * Returns a boolean indicating whether the given story ID and optional ref ID have been prepared. + * + * @param {StoryId} storyId - The ID of the story to check. + * @param {string} [refId] - The ID of the ref to check. If not provided, checks all refs for the given story ID. + * @returns {boolean} A boolean indicating whether the given story ID and optional ref ID have been prepared. + */ isPrepared: (storyId: StoryId, refId?: string) => boolean; + /** + * Returns the parameters for the given story ID and optional ref ID. + * + * @param {StoryId | { storyId: StoryId; refId: string }} storyId - The ID of the story to retrieve parameters for, or an object containing the story ID and ref ID. + * @param {ParameterName} [parameterName] - The name of the parameter to retrieve. If not provided, returns all parameters. + * @returns {API_StoryEntry['parameters'] | any} The parameters for the given story ID and optional ref ID. + */ getParameters: ( storyId: StoryId | { storyId: StoryId; refId: string }, parameterName?: ParameterName ) => API_StoryEntry['parameters'] | any; + /** + * Returns the current value of the specified parameter for the currently selected story. + * + * @template S - The type of the parameter value. + * @param {ParameterName} [parameterName] - The name of the parameter to retrieve. If not provided, returns all parameters. + * @returns {S} The value of the specified parameter for the currently selected story. + */ getCurrentParameter(parameterName?: ParameterName): S; + /** + * Updates the arguments for the given story with the provided new arguments. + * + * @param {API_StoryEntry} story - The story to update the arguments for. + * @param {Args} newArgs - The new arguments to set for the story. + * @returns {void} + */ updateStoryArgs(story: API_StoryEntry, newArgs: Args): void; + /** + * Resets the arguments for the given story to their initial values. + * + * @param {API_StoryEntry} story - The story to reset the arguments for. + * @param {string[]} [argNames] - An optional array of argument names to reset. If not provided, all arguments will be reset. + * @returns {void} + */ resetStoryArgs: (story: API_StoryEntry, argNames?: string[]) => void; + /** + * Finds the leaf entry for the given story ID in the given story index. + * + * @param {API_IndexHash} index - The story index to search for the leaf entry in. + * @param {StoryId} storyId - The ID of the story to find the leaf entry for. + * @returns {API_LeafEntry} The leaf entry for the given story ID, or null if no leaf entry was found. + */ findLeafEntry(index: API_IndexHash, storyId: StoryId): API_LeafEntry; + /** + * Finds the leaf story ID for the given component or group ID in the given index. + * + * @param {API_IndexHash} index - The story index to search for the leaf story ID in. + * @param {StoryId} storyId - The ID of the story to find the leaf story ID for. + * @returns {StoryId} The ID of the leaf story, or null if no leaf story was found. + */ findLeafStoryId(index: API_IndexHash, storyId: StoryId): StoryId; + /** + * Finds the ID of the sibling story in the given direction for the given story ID in the given story index. + * + * @param {StoryId} storyId - The ID of the story to find the sibling of. + * @param {API_IndexHash} index - The story index to search for the sibling in. + * @param {Direction} direction - The direction to search for the sibling in. + * @param {boolean} toSiblingGroup - When true, skips over leafs within the same group. + * @returns {StoryId} The ID of the sibling story, or null if no sibling was found. + */ findSiblingStoryId( storyId: StoryId, index: API_IndexHash, direction: Direction, toSiblingGroup: boolean // when true, skip over leafs within the same group ): StoryId; + /** + * Fetches the story index from the server. + * + * @returns {Promise} A promise that resolves when the index has been fetched. + */ fetchIndex: () => Promise; + /** + * Updates the story with the given ID with the provided update object. + * + * @param {StoryId} storyId - The ID of the story to update. + * @param {StoryUpdate} update - An object containing the updated story information. + * @param {API_ComposedRef} [ref] - The composed ref of the story to update. + * @returns {Promise} A promise that resolves when the story has been updated. + */ updateStory: (storyId: StoryId, update: StoryUpdate, ref?: API_ComposedRef) => Promise; + /** + * Updates the documentation for the given story ID with the given update object. + * + * @param {StoryId} storyId - The ID of the story to update. + * @param {DocsUpdate} update - An object containing the updated documentation information. + * @param {API_ComposedRef} [ref] - The composed ref of the story to update. + * @returns {Promise} A promise that resolves when the documentation has been updated. + */ updateDocs: (storyId: StoryId, update: DocsUpdate, ref?: API_ComposedRef) => Promise; + /** + * Sets the preview as initialized. + * + * @param {ComposedRef} [ref] - The composed ref of the story to set as initialized. + * @returns {Promise} A promise that resolves when the preview has been set as initialized. + */ setPreviewInitialized: (ref?: ComposedRef) => Promise; /** * Updates the status of a collection of stories. diff --git a/code/lib/manager-api/src/modules/url.ts b/code/lib/manager-api/src/modules/url.ts index 7dc77ecec077..7e83f7a76993 100644 --- a/code/lib/manager-api/src/modules/url.ts +++ b/code/lib/manager-api/src/modules/url.ts @@ -74,9 +74,33 @@ export interface QueryParams { [key: string]: string | null; } +/** + * SubAPI for managing URL navigation and state. + */ export interface SubAPI { + /** + * Navigate to a new URL. + * @param {string} url - The URL to navigate to. + * @param {NavigateOptions} options - Options for the navigation. + * @returns {void} + */ navigateUrl: (url: string, options: NavigateOptions) => void; + /** + * Get the value of a query parameter from the current URL. + * @param {string} key - The key of the query parameter to get. + * @returns {string | undefined} The value of the query parameter, or undefined if it does not exist. + */ getQueryParam: (key: string) => string | undefined; + /** + * Returns an object containing the current state of the URL. + * @returns {{ + * queryParams: QueryParams, + * path: string, + * viewMode?: string, + * storyId?: string, + * url: string + * }} An object containing the current state of the URL. + */ getUrlState: () => { queryParams: QueryParams; path: string; @@ -84,6 +108,11 @@ export interface SubAPI { storyId?: string; url: string; }; + /** + * Set the query parameters for the current URL. + * @param {QueryParams} input - An object containing the query parameters to set. + * @returns {void} + */ setQueryParams: (input: QueryParams) => void; } diff --git a/code/lib/manager-api/src/modules/versions.ts b/code/lib/manager-api/src/modules/versions.ts index 0ea85ae6d919..232fcfe9fbfb 100644 --- a/code/lib/manager-api/src/modules/versions.ts +++ b/code/lib/manager-api/src/modules/versions.ts @@ -24,8 +24,23 @@ const getVersionCheckData = memoize(1)((): API_Versions => { }); export interface SubAPI { + /** + * Returns the current version of the Storybook Manager. + * + * @returns {API_Version} The current version of the Storybook Manager. + */ getCurrentVersion: () => API_Version; + /** + * Returns the latest version of the Storybook Manager. + * + * @returns {API_Version} The latest version of the Storybook Manager. + */ getLatestVersion: () => API_Version; + /** + * Checks if an update is available for the Storybook Manager. + * + * @returns {boolean} True if an update is available, false otherwise. + */ versionUpdateAvailable: () => boolean; }