Search: Add docs headings to search results

code/core/src/core-server/utils/StoryIndexGenerator.ts

@@ -491,6 +491,7 @@ export class StoryIndexGenerator {
       const entry = storyEntries[0];
       const id = toId(metaId ?? entry.title, name);
       const tags = combineTags(...projectTags, ...(indexInputs[0].tags ?? []));
+      const headings = indexInputs.map((input) => input.name).filter(Boolean) as string[];
 
       const docsEntry: DocsCacheEntry & { tags: Tag[] } = {
         id,
@@ -500,6 +501,7 @@ export class StoryIndexGenerator {
         type: 'docs',
         tags,
         storiesImports: [],
+        headings,
       };
 
       return {
@@ -623,6 +625,7 @@ export class StoryIndexGenerator {
         storiesImports: sortedDependencies.map((dep) => dep.entries[0].importPath),
         type: 'docs',
         tags,
+        headings: result.headings || [],
       };
       return docsEntry;
     } catch (err) {

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

@@ -69,6 +69,7 @@ export const transformSetStoriesStoryDataToPreparedStoryIndex = (
           type: 'docs',
           tags: ['stories-mdx'],
           storiesImports: [],
+          headings: [],
           ...base,
         };
       } else {
@@ -125,7 +126,7 @@ export const transformStoryIndexV3toV4 = (index: StoryIndexV3): API_PreparedStor
         }
         acc[entry.id] = {
           type,
-          ...(type === 'docs' && { tags: ['stories-mdx'], storiesImports: [] }),
+          ...(type === 'docs' && { tags: ['stories-mdx'], storiesImports: [], headings: [] }),
           ...entry,
         } as API_PreparedIndexEntry;
 

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

@@ -143,7 +143,7 @@ export interface SubAPI {
   selectStory: (
     kindOrId?: string,
     story?: StoryId,
-    obj?: { ref?: string; viewMode?: API_ViewMode }
+    obj?: { ref?: string; viewMode?: API_ViewMode; scrollTo?: string }
   ) => void;
   /**
    * Returns the current story's data, including its ID, kind, name, and parameters.
@@ -631,14 +631,14 @@ export const init: ModuleFn<SubAPI, SubState> = ({
       navigateWithQueryParams('/');
     },
     selectStory: (titleOrId = undefined, name = undefined, options = {}) => {
-      const { ref } = options;
+      const { ref, scrollTo } = options;
       const { storyId, index, filteredIndex, refs, settings } = store.getState();
 
       const gotoStory = (entry?: API_HashEntry) => {
         if (entry?.type === 'docs' || entry?.type === 'story') {
           store.setState({ settings: { ...settings, lastTrackedStoryId: entry.id } });
           navigateWithQueryParams(
-            `/${entry.type}/${entry.refId ? `${entry.refId}_${entry.id}` : entry.id}`
+            `/${entry.type}/${entry.refId ? `${entry.refId}_${entry.id}` : entry.id}${scrollTo ? `#${scrollTo}` : ''}`
           );
           return true;
         }

code/core/src/manager/components/sidebar/Search.tsx

@@ -43,8 +43,9 @@ const options = {
   maxPatternLength: 32,
   minMatchCharLength: 1,
   keys: [
-    { name: 'name', weight: 0.7 },
+    { name: 'name', weight: 0.6 },
     { name: 'path', weight: 0.3 },
+    { name: 'headings', weight: 0.1 },
   ],
 } as FuseOptions<SearchItem>;
 
@@ -161,6 +162,7 @@ export type SearchProps = {
   dataset: CombinedDataset;
   enableShortcuts?: boolean;
   getLastViewed: () => Selection[];
+  updateLastViewed?: (story: { storyId: string; refId: string; anchor?: string }) => void;
   initialQuery?: string;
   searchBarContent?: ReactNode;
   searchFieldContent?: ReactNode;
@@ -172,6 +174,7 @@ export const Search = React.memo<SearchProps>(function Search({
   dataset,
   enableShortcuts = true,
   getLastViewed,
+  updateLastViewed,
   initialQuery = '',
   searchBarContent,
   searchFieldContent,
@@ -184,25 +187,52 @@ export const Search = React.memo<SearchProps>(function Search({
   const searchShortcut = api ? shortcutToHumanString(api.getShortcutKeys().search) : '/';
 
   const makeFuse = useCallback(() => {
-    const list = dataset.entries.reduce<SearchItem[]>((acc, [refId, { index, allStatuses }]) => {
+    const list: SearchItem[] = [];
+
+    for (const [refId, { index, allStatuses }] of dataset.entries) {
+      if (!index) {
+        continue;
+      }
+
       const groupStatus = getGroupStatus(index || {}, allStatuses ?? {});
+      const datasetValues = Object.values(index);
 
-      if (index) {
-        acc.push(
-          ...Object.values(index).map((item) => {
-            const storyStatuses = allStatuses?.[item.id];
-            const mostCriticalStatusValue = storyStatuses
-              ? getMostCriticalStatusValue(Object.values(storyStatuses).map((s) => s.value))
-              : null;
-            return {
-              ...searchItem(item, dataset.hash[refId]),
-              status: mostCriticalStatusValue ?? groupStatus[item.id] ?? null,
-            };
-          })
-        );
+      for (const datasetValue of datasetValues) {
+        const storyStatuses = allStatuses?.[datasetValue.id];
+        const mostCriticalStatusValue = storyStatuses
+          ? getMostCriticalStatusValue(Object.values(storyStatuses).map((s) => s.value))
+          : null;
+
+        list.push({
+          ...searchItem(datasetValue, dataset.hash[refId]),
+          status: mostCriticalStatusValue ?? groupStatus[datasetValue.id] ?? null,
+        });
+
+        // Narrow down type to more specific API_DocsEntry with headings
+        if (datasetValue.type !== 'docs') {
+          continue;
+        }
+
+        if (!globalThis?.FEATURES?.experimentalSearchDocsHeadings) {
+          continue;
+        }
+
+        const headings = datasetValue.headings ?? [];
+        headings.forEach((heading: string) => {
+          const searchItemRef = searchItem(datasetValue, dataset.hash[refId]);
+          const namePostfix = searchItemRef.path?.[0] === heading ? '' : ` / ${heading}`;
+
+          list.push({
+            ...searchItemRef,
+            // TODO add comment about why -> fuse breaks if id is not unique
+            id: `${datasetValue.id}#${heading.replaceAll(' ', '-').toLowerCase()}`,
+            name: `${datasetValue.name}${namePostfix}`,
+            status: mostCriticalStatusValue || groupStatus[datasetValue.id] || null,
+          });
+        });
       }
-      return acc;
-    }, []);
+    }
+
     return new Fuse(list, options);
   }, [dataset]);
 
@@ -247,9 +277,17 @@ export const Search = React.memo<SearchProps>(function Search({
   const onSelect = useCallback(
     (selectedItem: DownshiftItem) => {
       if (isSearchResult(selectedItem)) {
-        const { id, refId } = selectedItem.item;
-        // @ts-expect-error (non strict)
-        api?.selectStory(id, undefined, { ref: refId !== DEFAULT_REF_ID && refId });
+        const { id: rawId, refId } = selectedItem.item;
+        const [storyId, anchor] = rawId.split('#');
+
+        updateLastViewed?.({ storyId, refId, anchor });
+
+        api?.selectStory(storyId, undefined, {
+          // @ts-expect-error (non strict)
+          ref: refId !== DEFAULT_REF_ID && refId,
+          scrollTo: anchor,
+        });
+
         // @ts-expect-error (non strict)
         inputRef.current.blur();
         showAllComponents(false);
@@ -348,16 +386,33 @@ export const Search = React.memo<SearchProps>(function Search({
         const lastViewed = !input && getLastViewed();
         if (lastViewed && lastViewed.length) {
           // @ts-expect-error (non strict)
-          results = lastViewed.reduce((acc, { storyId, refId }) => {
+          results = lastViewed.reduce((acc, { storyId, refId, anchor }) => {
             const data = dataset.hash[refId];
             if (data && data.index && data.index[storyId]) {
               const story = data.index[storyId];
               const item = story.type === 'story' ? data.index[story.parent] : story;
+              const entryId = anchor ? `${item.id}#${anchor}` : item.id;
               // prevent duplicates
               // @ts-expect-error (non strict)
-              if (!acc.some((res) => res.item.refId === refId && res.item.id === item.id)) {
+              if (!acc.some((res) => res.item.refId === refId && res.item.id === entryId)) {
+                const baseItem = searchItem(item, dataset.hash[refId]);
+                let resultItem = baseItem;
+                if (anchor && item.type === 'docs') {
+                  const matchingHeading = item.headings?.find(
+                    (h: string) => h.replaceAll(' ', '-').toLowerCase() === anchor
+                  );
+                  if (matchingHeading) {
+                    const namePostfix =
+                      baseItem.path?.[0] === matchingHeading ? '' : ` / ${matchingHeading}`;
+                    resultItem = {
+                      ...baseItem,
+                      id: entryId,
+                      name: `${item.name}${namePostfix}`,
+                    };
+                  }
+                }
                 // @ts-expect-error (non strict)
-                acc.push({ item: searchItem(item, dataset.hash[refId]), matches: [], score: 0 });
+                acc.push({ item: resultItem, matches: [], score: 0 });
               }
             }
             return acc;

code/core/src/manager/components/sidebar/TreeNode.tsx

@@ -6,36 +6,40 @@ import { type FunctionInterpolation, styled } from 'storybook/theming';
 import { UseSymbol } from './IconSymbols.tsx';
 import { CollapseIcon } from './components/CollapseIcon.tsx';
 
-export const TypeIcon = styled.svg<{ type: 'component' | 'story' | 'test' | 'group' | 'document' }>(
-  ({ theme, type }) => ({
-    width: 14,
-    height: 14,
-    flex: '0 0 auto',
-    color: (() => {
-      if (type === 'group') {
-        return theme.base === 'dark' ? theme.color.primary : theme.color.ultraviolet;
-      }
-
-      if (type === 'component') {
-        return theme.color.secondary;
-      }
-
-      if (type === 'document') {
-        return theme.base === 'dark' ? theme.color.gold : '#ff8300';
-      }
-
-      if (type === 'story') {
-        return theme.color.seafoam;
-      }
-
-      if (type === 'test') {
-        return theme.color.green;
-      }
-
-      return 'currentColor';
-    })(),
-  })
-);
+export const TypeIcon = styled.svg<{
+  type: 'component' | 'story' | 'test' | 'group' | 'document' | 'heading';
+}>(({ theme, type }) => ({
+  width: 14,
+  height: 14,
+  flex: '0 0 auto',
+  color: (() => {
+    if (type === 'group') {
+      return theme.base === 'dark' ? theme.color.primary : theme.color.ultraviolet;
+    }
+
+    if (type === 'component') {
+      return theme.color.secondary;
+    }
+
+    if (type === 'document') {
+      return theme.base === 'dark' ? theme.color.gold : '#ff8300';
+    }
+
+    if (type === 'story') {
+      return theme.color.seafoam;
+    }
+
+    if (type === 'heading') {
+      return theme.color.secondary;
+    }
+
+    if (type === 'test') {
+      return theme.color.green;
+    }
+
+    return 'currentColor';
+  })(),
+}));
 
 const commonNodeStyles: FunctionInterpolation<{ depth?: number; isExpandable?: boolean }> = ({
   theme,

code/core/src/manager/components/sidebar/types.ts

@@ -20,6 +20,7 @@ export interface ItemRef {
 export interface StoryRef {
   storyId: string;
   refId: string;
+  anchor?: string;
 }
 
 export type Highlight = ItemRef | null;

code/core/src/manager/components/sidebar/useLastViewed.ts

@@ -27,7 +27,8 @@ export const useLastViewed = (selection: Selection) => {
     (story: StoryRef) => {
       const items = lastViewedRef.current;
       const index = items.findIndex(
-        ({ storyId, refId }) => storyId === story.storyId && refId === story.refId
+        ({ storyId, refId, anchor }) =>
+          storyId === story.storyId && refId === story.refId && anchor === story.anchor
       );
 
       if (index === 0) {
@@ -51,6 +52,7 @@ export const useLastViewed = (selection: Selection) => {
 
   return {
     getLastViewed: useCallback(() => lastViewedRef.current, [lastViewedRef]),
+    updateLastViewed,
     clearLastViewed: useCallback(() => {
       lastViewedRef.current = lastViewedRef.current.slice(0, 1);
       save(lastViewedRef.current);

code/core/src/manager/utils/tree.ts

@@ -65,7 +65,7 @@ export function getPath(item: Item, ref: Pick<RefType, 'id' | 'title' | 'index'>
 }
 
 export const searchItem = (item: Item, ref: Parameters<typeof getPath>[1]): SearchItem => {
-  return { ...item, refId: ref.id, path: getPath(item, ref) };
+  return { ...item, refId: ref.id, name: item.name, path: getPath(item, ref) };
 };
 
 export function cycle<T>(array: T[], index: number, delta: number): number {

code/core/src/preview/runtime.ts

@@ -1,4 +1,8 @@
-import { MANAGER_INERT_ATTRIBUTE_CHANGED, TELEMETRY_ERROR } from 'storybook/internal/core-events';
+import {
+  MANAGER_INERT_ATTRIBUTE_CHANGED,
+  NAVIGATE_URL,
+  TELEMETRY_ERROR,
+} from 'storybook/internal/core-events';
 
 import { global } from '@storybook/global';
 
@@ -47,6 +51,10 @@ export function setup() {
         document.body.removeAttribute('inert');
       }
     });
+
+    channel.on(NAVIGATE_URL, (hash: string) => {
+      document.querySelector(hash)?.scrollIntoView({ behavior: 'smooth' });
+    });
   });
 
   // handle all uncaught StorybookError at the root of the application and log to telemetry if applicable

code/core/src/router/router.tsx

@@ -7,6 +7,8 @@ import * as R from 'react-router-dom';
 
 import type { LinkProps, NavigateOptions, RenderData } from './types.ts';
 import { getMatch, parsePath, queryFromLocation } from './utils.ts';
+import { addons } from '../manager-api/index.ts';
+import { NAVIGATE_URL } from '../core-events/index.ts';
 
 const { document } = global;
 
@@ -56,6 +58,14 @@ export const useNavigate = () => {
     }
     if (typeof to === 'string') {
       const target = plain ? to : `?path=${to}`;
+      const [search, hash] = target.split('#');
+
+      if (search === document.location.search && hash) {
+        addons.getChannel().emit(NAVIGATE_URL, `#${hash}`);
+
+        return undefined;
+      }
+
       return navigate(target, options);
     }
     if (typeof to === 'number') {

code/core/src/types/modules/api-stories.ts

@@ -40,6 +40,7 @@ export interface API_DocsEntry extends API_BaseEntry {
   parameters?: {
     [parameterName: string]: any;
   };
+  headings?: string[];
 }
 
 export interface API_StoryEntry extends API_BaseEntry {

code/core/src/types/modules/core-common.ts

@@ -532,6 +532,13 @@ export interface StorybookConfigRaw {
      */
     experimentalRSC?: boolean;
 
+    /**
+     * Adds docs story subheadings to the search index.
+     *
+     * @experimental This feature is in early development and may change significantly in future releases.
+     */
+    experimentalSearchDocsHeadings?: boolean;
+
     /**
      * @temporary This feature flag is a migration assistant, and is scheduled to be removed.
      *