feat(storybook): add @fluentui/react-storybook-addon-playground with in-browser TSX playground (#36728)

apps/public-docsite-v9-headless/package.json

@@ -16,6 +16,7 @@
     "@fluentui/react-headless-components-preview": "*",
     "@fluentui/react-storybook-addon": "*",
     "@fluentui/react-storybook-addon-export-to-sandbox": "*",
+    "@fluentui/react-storybook-addon-playground": "*",
     "react": "19.2.0",
     "react-dom": "19.2.0",
     "tslib": "^2.1.0"

apps/public-docsite-v9-headless/project.json

@@ -8,15 +8,27 @@
     "build-storybook": {
       "dependsOn": [
         {
-          "projects": ["react-storybook-addon", "react-storybook-addon-export-to-sandbox", "storybook-llms-extractor"],
+          "projects": [
+            "react-headless-components-preview",
+            "react-storybook-addon",
+            "react-storybook-addon-export-to-sandbox",
+            "react-storybook-addon-playground",
+            "storybook-llms-extractor"
+          ],
           "target": "build"
         }
       ]
     },
     "build-storybook:docsite": {
       "dependsOn": [
         {
-          "projects": ["react-storybook-addon", "react-storybook-addon-export-to-sandbox", "storybook-llms-extractor"],
+          "projects": [
+            "react-headless-components-preview",
+            "react-storybook-addon",
+            "react-storybook-addon-export-to-sandbox",
+            "react-storybook-addon-playground",
+            "storybook-llms-extractor"
+          ],
           "target": "build"
         }
       ],

change/@fluentui-react-storybook-addon-export-to-sandbox-bfb6dbfb-a9e5-47e0-b04d-be8d1f1d4399.json

@@ -0,0 +1,6 @@
+{
+  "type": "minor",
+  "comment": "feat: support per-story full source generation and playground addon buttons",
+  "packageName": "@fluentui/react-storybook-addon-export-to-sandbox",
+  "email": "dmytrokirpa@microsoft.com"
+}

change/@fluentui-react-storybook-addon-playground-751293a3-5a89-42e3-8d5d-f2e4b6b20f94.json

@@ -0,0 +1,6 @@
+{
+  "type": "minor",
+  "comment": "feat: add initial playground implementation",
+  "packageName": "@fluentui/react-storybook-addon-playground",
+  "email": "dmytrokirpa@microsoft.com"
+}

change/@fluentui-react-storybook-addon-playground-99650265-91f2-458b-bfdb-cf5dda68c498.json

@@ -1,6 +1,6 @@
 {
-  "type": "patch",
-  "comment": "feat: add @fluentui/react-storybook-addon-playground package scaffold",
+  "type": "minor",
+  "comment": "feat: add an in-browser TSX playground for Storybook stories",
   "packageName": "@fluentui/react-storybook-addon-playground",
   "email": "dmytrokirpa@microsoft.com"
 }

packages/react-components/react-headless-components-preview/stories/.storybook/css.d.ts

@@ -0,0 +1 @@
+declare module '*.css';

packages/react-components/react-headless-components-preview/stories/.storybook/main.js

@@ -7,36 +7,79 @@ const {
   processBabelLoaderOptions,
 } = require('@fluentui/scripts-storybook');
 const { registerCssModuleRules } = require('./css-modules-webpack');
+const headlessPackageJson = require('../../library/package.json');
 
 const repoRoot = path.resolve(__dirname, '../../../../..');
 const tsConfigPath = path.resolve(repoRoot, 'tsconfig.base.json');
+const HEADLESS_PACKAGE_NAME = '@fluentui/react-headless-components-preview';
 
 /**
+ * Headless Storybook replaces the root sandbox addon with a CSS-modules-aware one, and registers
+ * the playground here only (not on the shared v9 Storybook).
+ *
  * @param {string | { name?: string }} addon
  */
-function isNotExportToSandboxAddon(addon) {
+function isNotRootSandboxOrPlaygroundAddon(addon) {
   const name = typeof addon === 'string' ? addon : addon?.name ?? '';
-  return !name.includes('react-storybook-addon-export-to-sandbox');
+  return (
+    !name.includes('react-storybook-addon-export-to-sandbox') && !name.includes('react-storybook-addon-playground')
+  );
+}
+
+/**
+ * Maps every published subpath of the headless package (plus react-icons) into the playground allowlist.
+ * Skips `.` — the barrel is empty, and Storybook only has a tsconfig path for `package/*` (source),
+ * not the package root (built `lib/index.js`, which CI `build-storybook` does not produce).
+ *
+ * @returns {Record<string, string>}
+ */
+function getHeadlessPlaygroundModules() {
+  /** @type {Record<string, string>} */
+  const modules = {
+    '@ctrl/tinycolor': '@ctrl/tinycolor',
+    '@fluentui/react-icons': '@fluentui/react-icons',
+  };
+
+  for (const exportPath of Object.keys(headlessPackageJson.exports ?? {})) {
+    if (exportPath === '.' || exportPath === './package.json') {
+      continue;
+    }
+
+    const specifier = `${HEADLESS_PACKAGE_NAME}${exportPath.slice(1)}`;
+    modules[specifier] = specifier;
+  }
+
+  return modules;
 }
 
 module.exports = /** @type {Omit<import('../../../../../.storybook/main'), 'typescript'|'babel'>} */ ({
   ...rootMain,
   stories: [...rootMain.stories, '../src/**/*.mdx', '../src/**/index.stories.@(ts|tsx)'],
   addons: [
-    ...rootMain.addons.filter(isNotExportToSandboxAddon),
+    ...rootMain.addons.filter(isNotRootSandboxOrPlaygroundAddon),
     loadWorkspaceAddon('@fluentui/react-storybook-addon-export-to-sandbox', {
       tsConfigPath,
       /** @type {import('../../../react-storybook-addon-export-to-sandbox/src/index').PresetConfig} */
       options: {
         importMappings: getImportMappingsForExportToSandboxAddon(),
         babelLoaderOptionsUpdater: processBabelLoaderOptions,
+        storyGranularity: 'story',
         cssModules: { tokensFilePath: path.resolve(__dirname, 'tokens.css') },
         webpackRule: {
           test: /\.stories\.tsx$/,
           include: /stories/,
         },
       },
     }),
+    /** {@link file://./../../../react-storybook-addon-playground/package.json} */
+    loadWorkspaceAddon('@fluentui/react-storybook-addon-playground', {
+      tsConfigPath,
+      /** @type {import('../../../react-storybook-addon-playground/src/index').PresetConfig} */
+      options: {
+        modules: getHeadlessPlaygroundModules(),
+        setup: path.resolve(__dirname, './playground.setup.tsx'),
+      },
+    }),
   ],
   webpackFinal: (config, options) => {
     const localConfig = /** @type {any} */ ({ ...rootMain.webpackFinal(config, options) });

packages/react-components/react-headless-components-preview/stories/.storybook/playground.setup.tsx

@@ -0,0 +1,52 @@
+import * as React from 'react';
+import { polyfillBodyAndObserve } from '@microsoft/focusgroup-polyfill/shadowless';
+import { Provider } from '@fluentui/react-headless-components-preview/provider';
+import { definePlaygroundSetup } from '@fluentui/react-storybook-addon-playground/setup';
+
+import './tokens.css';
+
+polyfillBodyAndObserve();
+
+type HeadlessPlaygroundTheme = 'light' | 'dark';
+
+const defaultCode = `import * as React from 'react';
+import { Button } from '@fluentui/react-headless-components-preview/button';
+
+export default () => {
+  const [count, setCount] = React.useState(0);
+
+  return (
+    <Button
+      onClick={() => setCount(count + 1)}
+      style={{
+        height: 32,
+        padding: '0 14px',
+        border: 0,
+        borderRadius: 999,
+        background: 'var(--accent)',
+        color: 'var(--accent-contrast)',
+        cursor: 'pointer',
+      }}
+    >
+      Clicked {count} times
+    </Button>
+  );
+};
+`;
+
+export default definePlaygroundSetup<HeadlessPlaygroundTheme>({
+  title: 'Fluent UI Playground',
+  subtitle: 'Headless',
+  defaultCode,
+  themes: [
+    { id: 'light', label: 'Light', value: 'light', dark: false },
+    { id: 'dark', label: 'Dark', value: 'dark', dark: true },
+  ],
+  render: ({ Component, theme }) => (
+    <Provider>
+      <div data-theme={theme ?? 'light'} style={{ minHeight: '100%', background: 'var(--bg)', color: 'var(--text)' }}>
+        <Component />
+      </div>
+    </Provider>
+  ),
+});

packages/react-components/react-headless-components-preview/stories/.storybook/preview.js

@@ -1,4 +1,5 @@
 import { polyfillBodyAndObserve } from '@microsoft/focusgroup-polyfill/shadowless';
+import '../../../react-storybook-addon-playground/src/styles.css';
 
 import * as rootPreview from '../../../../../.storybook/preview';
 

packages/react-components/react-headless-components-preview/stories/.storybook/tsconfig.json

@@ -7,5 +7,5 @@
     "moduleResolution": "bundler",
     "types": ["static-assets", "environment"]
   },
-  "include": ["*.js"]
+  "include": ["*.js", "*.tsx", "*.d.ts"]
 }

packages/react-components/react-headless-components-preview/stories/project.json

@@ -4,5 +4,23 @@
   "projectType": "library",
   "sourceRoot": "packages/react-components/react-headless-components-preview/stories/src",
   "tags": ["vNext", "platform:web", "type:stories", "react-headless"],
-  "implicitDependencies": []
+  "implicitDependencies": [],
+  "targets": {
+    "storybook": {
+      "dependsOn": [
+        {
+          "projects": ["react-headless-components-preview", "react-storybook-addon-playground"],
+          "target": "build"
+        }
+      ]
+    },
+    "build-storybook": {
+      "dependsOn": [
+        {
+          "projects": ["react-headless-components-preview", "react-storybook-addon-playground"],
+          "target": "build"
+        }
+      ]
+    }
+  }
 }

packages/react-components/react-headless-components-preview/stories/src/Concepts/Positioning/index.stories.tsx

@@ -17,6 +17,9 @@ export default {
   title: 'Concepts/Positioning',
   component: Positioning,
   parameters: {
+    playground: {
+      disable: true,
+    },
     docs: {
       description: {
         component: [descriptionMd, bestPracticesMd].join('\n'),

packages/react-components/react-headless-components-preview/stories/src/TagPicker/index.stories.tsx

@@ -25,6 +25,9 @@ export default {
   component: TagPicker,
   subcomponents: { TagPickerControl, TagPickerGroup, TagPickerInput, TagPickerButton, TagPickerList, TagPickerOption },
   parameters: {
+    playground: {
+      disable: true,
+    },
     docs: {
       description: {
         component: [descriptionMd, getBrowserSupportNotice('TagPicker')].join('\n'),

packages/react-components/react-storybook-addon-export-to-sandbox/etc/react-storybook-addon-export-to-sandbox.api.md

@@ -27,6 +27,8 @@ export interface PresetConfig {
     // (undocumented)
     importMappings: BabelPluginOptions['importMappings'];
     // (undocumented)
+    storyGranularity?: BabelPluginOptions['storyGranularity'];
+    // (undocumented)
     webpackRule?: RuleSetRule;
 }
 

packages/react-components/react-storybook-addon-export-to-sandbox/src/public-types.ts

@@ -38,6 +38,7 @@ export interface ParametersExtension {
 
 export interface PresetConfig {
   importMappings: import('@fluentui/babel-preset-storybook-full-source').BabelPluginOptions['importMappings'];
+  storyGranularity?: import('@fluentui/babel-preset-storybook-full-source').BabelPluginOptions['storyGranularity'];
   webpackRule?: import('webpack').RuleSetRule;
   babelLoaderOptionsUpdater?: (value: import('@babel/core').TransformOptions) => typeof value;
   /**

packages/react-components/react-storybook-addon-export-to-sandbox/src/sandbox-utils.ts

@@ -26,8 +26,9 @@ export function prepareSandboxContainers(context: StoryContext) {
   }
 
   return Array.from(rootElements).map(rootElement => {
+    // Exclude buttons added by this addon and by @fluentui/react-storybook-addon-playground
     const showCodeButton = rootElement.querySelector(
-      '.docblock-code-toggle:not(.with-code-sandbox-button):not(.with-open-in-new-tab-button)',
+      '.docblock-code-toggle:not(.with-code-sandbox-button):not(.with-open-in-new-tab-button):not(.with-open-in-playground-button)',
     );
     const container = showCodeButton?.parentElement;
 

packages/react-components/react-storybook-addon-export-to-sandbox/src/webpack.spec.ts

@@ -23,7 +23,7 @@ describe(`webpack`, () => {
             plugins: [
               [
                 expect.stringContaining('babel-preset-storybook-full-source'),
-                { importMappings: undefined, cssModules: false },
+                { importMappings: undefined, storyGranularity: 'file', cssModules: false },
               ],
             ],
           },
@@ -46,6 +46,7 @@ describe(`webpack`, () => {
             babelLoaderOptionsUpdater: value => {
               return Object.assign(value, { presets: ['babel-foo-bar-preset'] });
             },
+            storyGranularity: 'story',
           } as PresetConfig,
         },
       ],
@@ -65,6 +66,7 @@ describe(`webpack`, () => {
                 expect.stringContaining('babel-preset-storybook-full-source'),
                 {
                   importMappings: { '@proj/foo': { replace: '@proj/moo' } },
+                  storyGranularity: 'story',
                   cssModules: false,
                 },
               ],
@@ -101,7 +103,7 @@ describe(`webpack`, () => {
             plugins: [
               [
                 expect.stringContaining('babel-preset-storybook-full-source'),
-                { importMappings: undefined, cssModules },
+                { importMappings: undefined, storyGranularity: 'file', cssModules },
               ],
             ],
           },

packages/react-components/react-storybook-addon-export-to-sandbox/src/webpack.ts

@@ -20,6 +20,7 @@ const addonFilePattern = /react-storybook-addon-export-to-sandbox\/[a-z/]+.[jt]s
 const defaultOptions = {
   webpackRule: {},
   babelLoaderOptionsUpdater: identity,
+  storyGranularity: 'file' as const,
   cssModules: false,
 };
 
@@ -29,9 +30,9 @@ const PLUGIN_PATH =
     : '@fluentui/babel-preset-storybook-full-source';
 
 function createBabelLoaderRule(config: Required<PresetConfig>): import('webpack').RuleSetRule {
-  const { babelLoaderOptionsUpdater, importMappings, webpackRule, cssModules } = config;
+  const { babelLoaderOptionsUpdater, importMappings, webpackRule, storyGranularity, cssModules } = config;
 
-  const plugin = [require.resolve(PLUGIN_PATH), { importMappings, cssModules }];
+  const plugin = [require.resolve(PLUGIN_PATH), { importMappings, storyGranularity, cssModules }];
 
   return {
     test: /\.stories\.(jsx?$|tsx?$)/,

packages/react-components/react-storybook-addon-playground/.swcrc

@@ -7,7 +7,8 @@
     "/**/*.spec.ts",
     "/**/*.spec.tsx",
     "/**/*.test.ts",
-    "/**/*.test.tsx"
+    "/**/*.test.tsx",
+    "/**/src/playground/**"
   ],
   "jsc": {
     "baseUrl": ".",