Doc Blocks: Add support for of prop to Primary block

MIGRATION.md

@@ -73,6 +73,7 @@
     - [Unattached docs files](#unattached-docs-files)
     - [Doc Blocks](#doc-blocks)
       - [Meta block](#meta-block)
+      - [Primary block](#primary-block)
       - [Description block, `parameters.notes` and `parameters.info`](#description-block-parametersnotes-and-parametersinfo)
       - [Story block](#story-block)
       - [Source block](#source-block)
@@ -1429,6 +1430,10 @@ Additionally to changing the docs information architecture, we've updated the AP
 
 The primary change of the `Meta` block is the ability to attach to CSF files with `<Meta of={}>` as described above.
 
+##### Primary block
+
+The `Primary` block now also accepts an `of` prop as described above. It still accepts being passed `name` or no props at all.
+
 ##### Description block, `parameters.notes` and `parameters.info`
 
 In 6.5 the Description doc block accepted a range of different props, `markdown`, `type` and `children` as a way to customize the content.

code/ui/blocks/src/blocks/Primary.stories.tsx

@@ -1,13 +1,16 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { Primary } from './Primary';
+import * as DefaultButtonStories from '../examples/Button.stories';
+import * as StoriesParametersStories from '../examples/StoriesParameters.stories';
 
-const meta = {
+const meta: Meta<typeof Primary> = {
   component: Primary,
   parameters: {
+    // workaround for https://github.com/storybookjs/storybook/issues/20505
+    docs: { source: { type: 'code' } },
     docsStyles: true,
   },
-} satisfies Meta<typeof Primary>;
-
+};
 export default meta;
 
 type Story = StoryObj<typeof meta>;
@@ -22,3 +25,55 @@ export const WithoutToolbar: Story = {
     relativeCsfPaths: ['../examples/StoriesParameters.stories'],
   },
 };
+
+export const DefaultWithName: Story = {
+  name: 'Name',
+  args: {
+    name: 'Primary',
+  },
+  parameters: {
+    relativeCsfPaths: ['../examples/Button.stories'],
+  },
+};
+
+export const WithoutToolbarWithName: Story = {
+  name: 'Name Without Toolbar',
+  args: {
+    name: 'Without Toolbar',
+  },
+  parameters: {
+    relativeCsfPaths: ['../examples/StoriesParameters.stories'],
+  },
+};
+
+export const DefaultWithOf: Story = {
+  name: 'Of',
+  args: {
+    of: DefaultButtonStories,
+  },
+  parameters: { relativeCsfPaths: ['../examples/Button.stories'] },
+};
+
+export const WithoutToolbarWithOf: Story = {
+  name: 'Of Without Toolbar',
+  args: {
+    of: StoriesParametersStories,
+  },
+  parameters: { relativeCsfPaths: ['../examples/StoriesParameters.stories'] },
+};
+
+export const DefaultOfStringMetaAttached: Story = {
+  name: 'Of Attached "meta"',
+  args: {
+    of: 'meta',
+  },
+  parameters: { relativeCsfPaths: ['../examples/Button.stories'] },
+};
+
+export const WithoutToolbarOfStringMetaAttached: Story = {
+  name: 'Of Attached "meta" Without Toolbar',
+  args: {
+    of: 'meta',
+  },
+  parameters: { relativeCsfPaths: ['../examples/StoriesParameters.stories'] },
+};

code/ui/blocks/src/blocks/Primary.tsx

@@ -2,7 +2,8 @@ import type { FC } from 'react';
 import React, { useContext } from 'react';
 import dedent from 'ts-dedent';
 import { deprecate } from '@storybook/client-logger';
-
+import type { Of } from './useOf';
+import { useOf } from './useOf';
 import { DocsContext } from './DocsContext';
 import { DocsStory } from './DocsStory';
 
@@ -11,17 +12,58 @@ interface PrimaryProps {
    * @deprecated Primary block should only be used to render the primary story, which is automatically found.
    */
   name?: string;
+  /**
+   * Specify where to get the primary story from.
+   */
+  of?: Of;
 }
 
-export const Primary: FC<PrimaryProps> = ({ name }) => {
+const getPrimaryFromResolvedOf = (resolvedOf: ReturnType<typeof useOf>) => {
+  switch (resolvedOf.type) {
+    case 'meta': {
+      return resolvedOf.csfFile.stories[0] || null;
+    }
+    case 'component': {
+      throw new Error(
+        `Unsupported module type. Primary's \`of\` prop only supports \`meta\`, got: ${
+          (resolvedOf as any).type
+        }`
+      );
+    }
+    default: {
+      throw new Error(
+        `Unrecognized module type resolved from 'useOf', got: ${(resolvedOf as any).type}`
+      );
+    }
+  }
+};
+
+export const Primary: FC<PrimaryProps> = (props) => {
+  const { name, of } = props;
+
+  if ('of' in props && of === undefined) {
+    throw new Error('Unexpected `of={undefined}`, did you mistype a CSF file reference?');
+  }
+
   const docsContext = useContext(DocsContext);
+
+  let story;
+  if (of) {
+    const resolvedOf = useOf(of || 'meta');
+    story = getPrimaryFromResolvedOf(resolvedOf);
+  }
+
+  if (!story) {
+    const storyId = name && docsContext.storyIdByName(name);
+    story = docsContext.storyById(storyId);
+  }
+
   if (name) {
     deprecate(dedent`\`name\` prop is deprecated on the Primary block.
     The Primary block should only be used to render the primary story, which is automatically found.
     `);
   }
-  const storyId = name && docsContext.storyIdByName(name);
-  const story = docsContext.storyById(storyId);
+
   return story ? (
     <DocsStory of={story.moduleExport} expanded={false} __primary withToolbar />
   ) : null;

docs/api/doc-block-primary.md

@@ -29,6 +29,12 @@ import { Primary } from '@storybook/blocks';
 
 `Primary` is configured with the following props:
 
+### `of`
+
+Type: CSF file exports
+
+Specifies the primary (first) story to be rendered.
+
 ### `name`
 
 (⛔️ **Deprecated**)