Telemetry: Disambiguate traffic coming from error/upgrade links

code/addons/docs/src/blocks/components/ArgsTable/ArgControl.tsx

@@ -72,7 +72,11 @@ export const ArgControl: FC<ArgControlProps> = ({ row, arg, updateArgs, isHovere
   if (!control || control.disable) {
     const canBeSetup = control?.disable !== true && row?.type?.name !== 'function';
     return isHovered && canBeSetup ? (
-      <Link href="https://storybook.js.org/docs/essentials/controls" target="_blank" withArrow>
+      <Link
+        href="https://storybook.js.org/docs/essentials/controls?ref=ui"
+        target="_blank"
+        withArrow
+      >
         Setup controls
       </Link>
     ) : (

code/addons/docs/src/blocks/components/ArgsTable/ArgsTable.tsx

@@ -331,7 +331,7 @@ export const ArgsTable: FC<ArgsTableProps> = (props) => {
     return (
       <EmptyBlock>
         {error}&nbsp;
-        <Link href="http://storybook.js.org/docs/" target="_blank" withArrow>
+        <Link href="http://storybook.js.org/docs/?ref=ui" target="_blank" withArrow>
           <DocumentIcon /> Read the docs
         </Link>
       </EmptyBlock>

code/addons/docs/src/blocks/components/ArgsTable/Empty.tsx

@@ -67,7 +67,7 @@ export const Empty: FC<EmptyProps> = ({ inAddonPanel }) => {
             {inAddonPanel && (
               <>
                 <Link
-                  href="https://storybook.js.org/docs/essentials/controls"
+                  href="https://storybook.js.org/docs/essentials/controls?ref=ui"
                   target="_blank"
                   withArrow
                 >
@@ -77,7 +77,7 @@ export const Empty: FC<EmptyProps> = ({ inAddonPanel }) => {
             )}
             {!inAddonPanel && (
               <Link
-                href="https://storybook.js.org/docs/essentials/controls"
+                href="https://storybook.js.org/docs/essentials/controls?ref=ui"
                 target="_blank"
                 withArrow
               >

code/addons/docs/src/blocks/components/Story.tsx

@@ -126,7 +126,9 @@ const Story: FunctionComponent<StoryProps> = (props) => {
     return (
       <ErrorMessage>
         This story mounts inside of play. Set{' '}
-        <a href="https://storybook.js.org/docs/api/doc-blocks/doc-block-story#autoplay">autoplay</a>{' '}
+        <a href="https://storybook.js.org/docs/api/doc-blocks/doc-block-story?ref=ui#autoplay">
+          autoplay
+        </a>{' '}
         to true to view this story.
       </ErrorMessage>
     );

code/addons/vitest/src/preset.ts

@@ -66,7 +66,7 @@ export const experimental_serverChannel = async (channel: Channel, options: Opti
       log(dedent`
         You're using ${framework}, which is a Webpack-based builder. In order to use Storybook Test, with your project, you need to use '@storybook/nextjs-vite', a high performance Vite-based equivalent.
 
-        Information on how to upgrade here: ${picocolors.yellow('https://storybook.js.org/docs/get-started/frameworks/nextjs#with-vite')}\n
+        Information on how to upgrade here: ${picocolors.yellow('https://storybook.js.org/docs/get-started/frameworks/nextjs?ref=upgrade#with-vite')}\n
       `);
     }
     return channel;

code/core/src/__tests/storybook-error.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { StorybookError } from '../storybook-error';
+import { StorybookError, appendErrorRef } from '../storybook-error';
 
 describe('StorybookError', () => {
   class TestError extends StorybookError {
@@ -28,7 +28,7 @@ describe('StorybookError', () => {
   it('should generate the correct message with internal documentation link', () => {
     const error = new TestError(true);
     const expectedMessage =
-      'This is a test error.\n\nMore info: https://storybook.js.org/error/SB_TEST_CATEGORY_0123\n';
+      'This is a test error.\n\nMore info: https://storybook.js.org/error/SB_TEST_CATEGORY_0123?ref=error\n';
     expect(error.message).toBe(expectedMessage);
   });
 
@@ -45,14 +45,14 @@ describe('StorybookError', () => {
   it('should generate the correct message with multiple external documentation links', () => {
     const error = new TestError([
       'https://example.com/docs/first-error',
-      'https://example.com/docs/second-error',
+      'https://storybook.js.org/docs/second-error',
     ]);
     expect(error.message).toMatchInlineSnapshot(`
       "This is a test error.
 
       More info: 
       	- https://example.com/docs/first-error
-      	- https://example.com/docs/second-error
+      	- https://storybook.js.org/docs/second-error?ref=error
       "
     `);
   });
@@ -62,3 +62,83 @@ describe('StorybookError', () => {
     expect(error.documentation).toBe(false);
   });
 });
+
+describe('appendErrorRef', () => {
+  it('should append ref=error to storybook.js.org URLs without query parameters', () => {
+    const url = 'https://storybook.js.org/docs/example';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://storybook.js.org/docs/example?ref=error');
+  });
+
+  it('should append ref=error to storybook.js.org URLs with existing query parameters', () => {
+    const url = 'https://storybook.js.org/docs/example?foo=bar';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://storybook.js.org/docs/example?foo=bar&ref=error');
+  });
+
+  it('should append ref=error to storybook.js.org URLs with multiple existing query parameters', () => {
+    const url = 'https://storybook.js.org/docs/example?foo=bar&baz=qux';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://storybook.js.org/docs/example?foo=bar&baz=qux&ref=error');
+  });
+
+  it('should handle storybook.js.org URLs with hash fragments', () => {
+    const url = 'https://storybook.js.org/docs/example#section';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://storybook.js.org/docs/example?ref=error#section');
+  });
+
+  it('should handle storybook.js.org URLs with query parameters and hash fragments', () => {
+    const url = 'https://storybook.js.org/docs/example?foo=bar#section';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://storybook.js.org/docs/example?foo=bar&ref=error#section');
+  });
+
+  it('should not modify non-storybook.js.org URLs', () => {
+    const url = 'https://example.com/docs/test-error';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://example.com/docs/test-error');
+  });
+
+  it('should not modify relative URLs', () => {
+    const url = '/docs/example';
+    const result = appendErrorRef(url);
+    expect(result).toBe('/docs/example');
+  });
+
+  it('should not modify empty string URLs', () => {
+    const url = '';
+    const result = appendErrorRef(url);
+    expect(result).toBe('');
+  });
+
+  it('should not modify other domain URLs', () => {
+    const url = 'https://github.com/storybookjs/storybook/issues/123';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://github.com/storybookjs/storybook/issues/123');
+  });
+
+  it('should not append ref=error if it already exists in the URL', () => {
+    const url = 'https://storybook.js.org/docs/example?ref=error';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://storybook.js.org/docs/example?ref=error');
+  });
+
+  it('should not append ref=error if it already exists with other parameters', () => {
+    const url = 'https://storybook.js.org/docs/example?foo=bar&ref=error&baz=qux';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://storybook.js.org/docs/example?foo=bar&ref=error&baz=qux');
+  });
+
+  it('should not append ref=error if it already exists in URL with hash fragment', () => {
+    const url = 'https://storybook.js.org/docs/example?ref=error#target';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://storybook.js.org/docs/example?ref=error#target');
+  });
+
+  it('should append ref=error before hash fragment when no existing ref parameter', () => {
+    const url = 'https://storybook.js.org/docs/example#target';
+    const result = appendErrorRef(url);
+    expect(result).toBe('https://storybook.js.org/docs/example?ref=error#target');
+  });
+});

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

@@ -593,7 +593,7 @@ export class StoryIndexGenerator {
       if (err && (err as { source: any }).source?.match(/mdast-util-mdx-jsx/g)) {
         logger.warn(
           `💡 This seems to be an MDX2 syntax error. Please refer to the MDX section in the following resource for assistance on how to fix this: ${picocolors.yellow(
-            'https://storybook.js.org/migration-guides/7.0'
+            'https://storybook.js.org/docs/7/migration-guide?ref=error'
           )}`
         );
       }

code/core/src/core-server/utils/__tests__/remove-mdx-stories.test.ts

@@ -56,7 +56,7 @@ Your main configuration somehow does not contain a 'stories' field, or it resolv
 
 Please check your main configuration file and make sure it exports a 'stories' field that is not an empty array.
 
-More info: https://storybook.js.org/docs/faq#can-i-have-a-storybook-with-no-local-stories
+More info: https://storybook.js.org/docs/faq?ref=error#can-i-have-a-storybook-with-no-local-stories
 ]
 `);
   });

code/core/src/csf-tools/CsfFile.test.ts

@@ -2513,7 +2513,7 @@ describe('CsfFile', () => {
         ).toThrowErrorMatchingInlineSnapshot(`
           [MultipleMetaError: CSF: multiple meta objects (line 4, col 24)
 
-          More info: https://storybook.js.org/docs/writing-stories#default-export]
+          More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error]
         `);
       });
 
@@ -2531,7 +2531,7 @@ describe('CsfFile', () => {
         ).toThrowErrorMatchingInlineSnapshot(`
           [MultipleMetaError: CSF: multiple meta objects (line 3, col 25)
 
-          More info: https://storybook.js.org/docs/writing-stories#default-export]
+          More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error]
         `);
       });
 
@@ -2549,7 +2549,7 @@ describe('CsfFile', () => {
         ).toThrowErrorMatchingInlineSnapshot(`
           [MultipleMetaError: CSF: multiple meta objects 
 
-          More info: https://storybook.js.org/docs/writing-stories#default-export]
+          More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error]
         `);
       });
 
@@ -2565,7 +2565,7 @@ describe('CsfFile', () => {
         ).toThrowErrorMatchingInlineSnapshot(`
           [BadMetaError: CSF: meta() factory must be imported from .storybook/preview configuration (line 1, col 0)
 
-          More info: https://storybook.js.org/docs/writing-stories#default-export]
+          More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error]
         `);
       });
 
@@ -2582,7 +2582,7 @@ describe('CsfFile', () => {
         ).toThrowErrorMatchingInlineSnapshot(`
           [BadMetaError: CSF: meta() factory must be imported from .storybook/preview configuration (line 4, col 28)
 
-          More info: https://storybook.js.org/docs/writing-stories#default-export]
+          More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error]
         `);
       });
 
@@ -2599,7 +2599,7 @@ describe('CsfFile', () => {
         ).toThrowErrorMatchingInlineSnapshot(`
           [MixedFactoryError: CSF: expected factory story (line 4, col 17)
 
-          More info: https://storybook.js.org/docs/writing-stories#default-export]
+          More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error]
         `);
       });
 
@@ -2616,7 +2616,7 @@ describe('CsfFile', () => {
         ).toThrowErrorMatchingInlineSnapshot(`
           [MixedFactoryError: CSF: expected non-factory story (line 4, col 28)
 
-          More info: https://storybook.js.org/docs/writing-stories#default-export]
+          More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error]
         `);
       });
     });

code/core/src/csf-tools/CsfFile.ts

@@ -181,7 +181,7 @@ export class NoMetaError extends Error {
     super(dedent`
       CSF: ${msg} ${formatLocation(ast, fileName)}
 
-      More info: https://storybook.js.org/docs/writing-stories#default-export
+      More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error
     `);
     this.name = this.constructor.name;
   }
@@ -193,7 +193,7 @@ export class MultipleMetaError extends Error {
     super(dedent`
       CSF: ${message} ${formatLocation(ast, fileName)}
 
-      More info: https://storybook.js.org/docs/writing-stories#default-export
+      More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error
     `);
     this.name = this.constructor.name;
   }
@@ -205,7 +205,7 @@ export class MixedFactoryError extends Error {
     super(dedent`
       CSF: ${message} ${formatLocation(ast, fileName)}
 
-      More info: https://storybook.js.org/docs/writing-stories#default-export
+      More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error
     `);
     this.name = this.constructor.name;
   }
@@ -217,7 +217,7 @@ export class BadMetaError extends Error {
     super(dedent`
       CSF: ${message} ${formatLocation(ast, fileName)}
 
-      More info: https://storybook.js.org/docs/writing-stories#default-export
+      More info: https://storybook.js.org/docs/writing-stories#default-export?ref=error
     `);
     this.name = this.constructor.name;
   }

code/core/src/manager/components/mobile/about/MobileAbout.tsx

@@ -40,7 +40,7 @@ export const MobileAbout: FC = () => {
               <ShareAltIcon width={12} />
             </LinkLine>
             <LinkLine
-              href="https://storybook.js.org/docs/react/get-started/install/"
+              href="https://storybook.js.org/docs/get-started/install/?ref=ui"
               target="_blank"
             >
               <LinkLeft>

code/core/src/manager/components/panel/Panel.tsx

@@ -75,7 +75,7 @@ export const AddonPanel = React.memo<{
               </>
             }
             footer={
-              <Link href={'https://storybook.js.org/integrations'} target="_blank" withArrow>
+              <Link href={'https://storybook.js.org/addons?ref=ui'} target="_blank" withArrow>
                 <DocumentIcon /> Explore integrations catalog
               </Link>
             }

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

@@ -120,7 +120,7 @@ export const ErrorBlock: FC<{ error: Error }> = ({ error }) => (
             View error <ChevronDownIcon />
           </Link>
         </WithTooltip>{' '}
-        <Link withArrow href="https://storybook.js.org/docs" cancel={false} target="_blank">
+        <Link withArrow href="https://storybook.js.org/docs?ref=ui" cancel={false} target="_blank">
           View docs
         </Link>
       </TextStyle>

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

@@ -308,7 +308,10 @@ const ReadDocsMessage: FC = () => {
   const theme = useTheme();
 
   return (
-    <Message href="https://storybook.js.org/docs/sharing/storybook-composition" target="_blank">
+    <Message
+      href="https://storybook.js.org/docs/sharing/storybook-composition?ref=ui"
+      target="_blank"
+    >
       <DocumentIcon color={theme.color.green} />
       <div>
         <MessageTitle>Read Composition docs</MessageTitle>
@@ -351,7 +354,10 @@ const PerformanceDegradedMessage: FC = () => {
   const theme = useTheme();
 
   return (
-    <Message href="https://storybook.js.org/docs/sharing/storybook-composition" target="_blank">
+    <Message
+      href="https://storybook.js.org/docs/sharing/storybook-composition?ref=ui"
+      target="_blank"
+    >
       <LightningIcon color={theme.color.gold} />
       <div>
         <MessageTitle>Reduce lag</MessageTitle>

code/core/src/manager/settings/About.tsx

@@ -73,7 +73,7 @@ const AboutScreen: FC<{ onNavigateToWhatsNew?: () => void }> = ({ onNavigateToWh
             </a>
           </Button>
           <Button asChild>
-            <a href="https://storybook.js.org/docs">
+            <a href="https://storybook.js.org/docs?ref=ui">
               <DocumentIcon style={{ display: 'inline', marginRight: 5 }} />
               Documentation
             </a>

code/core/src/manager/settings/SettingsFooter.tsx

@@ -18,15 +18,15 @@ const Footer = styled.div(({ theme }) => ({
 }));
 const SettingsFooter: FC<any> = (props) => (
   <Footer {...props}>
-    <Link secondary href="https://storybook.js.org" cancel={false} target="_blank">
+    <Link secondary href="https://storybook.js.org?ref=ui" cancel={false} target="_blank">
       Docs
     </Link>
     <Link secondary href="https://github.com/storybookjs/storybook" cancel={false} target="_blank">
       GitHub
     </Link>
     <Link
       secondary
-      href="https://storybook.js.org/community#support"
+      href="https://storybook.js.org/community?ref=ui#support"
       cancel={false}
       target="_blank"
     >

code/core/src/preview-api/modules/preview-web/parseArgsParam.ts

@@ -114,7 +114,7 @@ export const parseArgsParam = (argsString: string): Args => {
     once.warn(dedent`
       Omitted potentially unsafe URL args.
 
-      More info: https://storybook.js.org/docs/writing-stories/args#setting-args-through-the-url
+      More info: https://storybook.js.org/docs/writing-stories/args#setting-args-through-the-url?ref=error
     `);
     return acc;
   }, {} as Args);

code/core/src/preview-api/modules/store/args.ts

@@ -119,7 +119,7 @@ export const validateOptions = (args: Args, argTypes: ArgTypes): Args => {
       once.error(dedent`
         Invalid argType: '${key}.options' should be an array.
 
-        More info: https://storybook.js.org/docs/api/arg-types
+        More info: https://storybook.js.org/docs/api/arg-types?ref=error
       `);
       return allowArg();
     }
@@ -128,7 +128,7 @@ export const validateOptions = (args: Args, argTypes: ArgTypes): Args => {
       once.error(dedent`
         Invalid argType: '${key}.options' should only contain primitives. Use a 'mapping' for complex values.
 
-        More info: https://storybook.js.org/docs/writing-stories/args#mapping-to-complex-arg-values
+        More info: https://storybook.js.org/docs/writing-stories/args?ref=error#mapping-to-complex-arg-values
       `);
       return allowArg();
     }