Autodocs: Fix docs pages ignoring meta.id when calculating their ID

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

@@ -748,6 +748,47 @@ describe('StoryIndexGenerator', () => {
           }
         `);
       });
+
+      it('prioritizes using the component id over meta.title for generating its id, if provided. (autodocs)', async () => {
+        const csfSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './docs-id-generation/A.stories.jsx',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([csfSpecifier], autodocsOptions);
+        await generator.initialize();
+
+        expect(await generator.getIndex()).toMatchInlineSnapshot(`
+          Object {
+            "entries": Object {
+              "my-component-a--docs": Object {
+                "id": "my-component-a--docs",
+                "importPath": "./docs-id-generation/A.stories.jsx",
+                "name": "docs",
+                "storiesImports": Array [],
+                "tags": Array [
+                  "autodocs",
+                  "docs",
+                ],
+                "title": "A",
+                "type": "docs",
+              },
+              "my-component-a--story-one": Object {
+                "id": "my-component-a--story-one",
+                "importPath": "./docs-id-generation/A.stories.jsx",
+                "name": "Story One",
+                "tags": Array [
+                  "autodocs",
+                  "story",
+                ],
+                "title": "A",
+                "type": "story",
+              },
+            },
+            "v": 4,
+          }
+        `);
+      });
     });
 
     describe('docs specifier', () => {
@@ -1016,6 +1057,53 @@ describe('StoryIndexGenerator', () => {
           }
         `);
       });
+
+      it('prioritizes using the component id over meta.title for generating its id, if provided. (mdx docs)', async () => {
+        const csfSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './docs-id-generation/B.stories.jsx',
+          options
+        );
+
+        const docsSpecifier: NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './docs-id-generation/B.docs.mdx',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([csfSpecifier, docsSpecifier], options);
+        await generator.initialize();
+
+        expect(await generator.getIndex()).toMatchInlineSnapshot(`
+          Object {
+            "entries": Object {
+              "my-component-b--docs": Object {
+                "id": "my-component-b--docs",
+                "importPath": "./docs-id-generation/B.docs.mdx",
+                "name": "docs",
+                "storiesImports": Array [
+                  "./docs-id-generation/B.stories.jsx",
+                ],
+                "tags": Array [
+                  "attached-mdx",
+                  "docs",
+                ],
+                "title": "B",
+                "type": "docs",
+              },
+              "my-component-b--story-one": Object {
+                "id": "my-component-b--story-one",
+                "importPath": "./docs-id-generation/B.stories.jsx",
+                "name": "Story One",
+                "tags": Array [
+                  "story",
+                ],
+                "title": "B",
+                "type": "story",
+              },
+            },
+            "v": 4,
+          }
+        `);
+      });
     });
 
     describe('errors', () => {

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

@@ -44,6 +44,8 @@ type ErrorEntry = {
 };
 type CacheEntry = false | StoriesCacheEntry | DocsCacheEntry | ErrorEntry;
 type SpecifierStoriesCache = Record<Path, CacheEntry>;
+// Extended type to keep track of the csf meta so we know the component id when referencing docs in `extractDocs`
+type StoryIndexEntryWithMeta = StoryIndexEntry & { meta?: any };
 
 export const AUTODOCS_TAG = 'autodocs';
 export const STORIES_MDX_TAG = 'stories-mdx';
@@ -217,7 +219,13 @@ export class StoryIndexGenerator {
         if (!entry) return [];
         if (entry.type === 'docs') return [entry];
         if (entry.type === 'error') return [entry];
-        return entry.entries;
+
+        return entry.entries.map((item) => {
+          if (item.type === 'docs') return item;
+          // Drop the meta as it isn't part of the index, we just used it for record keeping in `extractDocs`
+          const { meta, ...existing } = item as StoryIndexEntryWithMeta;
+          return existing;
+        });
       });
     });
   }
@@ -260,7 +268,16 @@ export class StoryIndexGenerator {
     csf.stories.forEach(({ id, name, tags: storyTags, parameters }) => {
       if (!parameters?.docsOnly) {
         const tags = [...(storyTags || componentTags), 'story'];
-        entries.push({ id, title: csf.meta.title, name, importPath, tags, type: 'story' });
+        entries.push({
+          id,
+          title: csf.meta.title,
+          name,
+          importPath,
+          tags,
+          type: 'story',
+          // We need to keep track of the csf meta so we know the component id when referencing docs below in `extractDocs`
+          meta: csf.meta,
+        } as StoryIndexEntryWithMeta);
       }
     });
 
@@ -273,7 +290,7 @@ export class StoryIndexGenerator {
       //  b) we have docs page enabled for this file
       if (componentTags.includes(STORIES_MDX_TAG) || autodocsOptedIn) {
         const name = this.options.docs.defaultName;
-        const id = toId(csf.meta.title, name);
+        const id = toId(csf.meta.id || csf.meta.title, name);
         entries.unshift({
           id,
           title: csf.meta.title,
@@ -332,7 +349,7 @@ export class StoryIndexGenerator {
 
       // Also, if `result.of` is set, it means that we're using the `<Meta of={XStories} />` syntax,
       // so find the `title` defined the file that `meta` points to.
-      let csfEntry: StoryIndexEntry;
+      let csfEntry: StoryIndexEntryWithMeta;
       if (result.of) {
         const absoluteOf = makeAbsolute(result.of, normalizedPath, this.options.workingDir);
         dependencies.forEach((dep) => {
@@ -373,7 +390,7 @@ export class StoryIndexGenerator {
       const name =
         result.name ||
         (csfEntry ? autoName(importPath, csfEntry.importPath, defaultName) : defaultName);
-      const id = toId(title, name);
+      const id = toId(csfEntry?.meta?.id || title, name);
 
       const docsEntry: DocsCacheEntry = {
         id,

code/lib/core-server/src/utils/__mockdata__/docs-id-generation/A.stories.jsx

@@ -0,0 +1,9 @@
+// Stories for a component with meta.id
+const component = {};
+export default {
+  id: 'my-component-A',
+  component,
+  tags: ['autodocs'],
+};
+
+export const StoryOne = {};

code/lib/core-server/src/utils/__mockdata__/docs-id-generation/B.docs.mdx

@@ -0,0 +1,7 @@
+import * as Stories from './B.stories';
+
+<Meta of={Stories} />
+
+# Docs with of
+
+hello docs

code/lib/core-server/src/utils/__mockdata__/docs-id-generation/B.stories.jsx

@@ -0,0 +1,8 @@
+// Stories for a component with meta.id
+const component = {};
+export default {
+  id: 'my-component-B',
+  component,
+};
+
+export const StoryOne = {};

code/lib/types/src/modules/storyIndex.ts

@@ -38,7 +38,7 @@ export interface IndexedStory {
   parameters?: Parameters;
 }
 export interface IndexedCSFFile {
-  meta: { title?: string; tags?: Tag[] };
+  meta: { id?: string; title?: string; tags?: Tag[] };
   stories: IndexedStory[];
 }