feat(web-components): generate SSR templates and stylesheets into src/

change/@fluentui-web-components-39809c10-c214-4e43-b550-a3f303e597d0.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat(web-components): generate SSR templates and stylesheets into src/ and copy into dist during compile",
+  "packageName": "@fluentui/web-components",
+  "email": "863023+radium-v@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

package.json

@@ -72,10 +72,10 @@
     "@microsoft/api-extractor": "7.51.0",
     "@microsoft/api-extractor-model": "7.31.2",
     "@microsoft/eslint-plugin-sdl": "1.0.1",
-    "@microsoft/fast-build": "0.6.0",
+    "@microsoft/fast-build": "0.7.0",
     "@microsoft/fast-element": "2.10.4",
-    "@microsoft/fast-html": "1.0.0-alpha.53",
-    "@microsoft/fast-test-harness": "0.3.0",
+    "@microsoft/fast-html": "1.0.0-alpha.54",
+    "@microsoft/fast-test-harness": "0.3.1",
     "@microsoft/focusgroup-polyfill": "1.5.0",
     "@microsoft/load-themed-styles": "1.10.26",
     "@microsoft/loader-load-themed-styles": "2.0.17",

packages/web-components/README.md

@@ -88,6 +88,24 @@ import CEM from '@fluentui/custom-elements.json' with { type: 'json' };
 
 To start the component development environment, run `yarn start`.
 
+### SSR templates and stylesheets
+
+Each component ships a declarative-shadow-DOM template (`*.template.html`) and an extracted stylesheet (`*.styles.css`) next to its `*.template.ts` and `*.styles.ts` sources. These files are generated from the TypeScript sources and committed to the repo so the DSD output is visible without running a build.
+
+After editing a `*.template.ts` or `*.styles.ts`, regenerate the matching HTML and CSS with:
+
+```sh
+yarn generate:ssr
+```
+
+To check that the committed files match what the generators would produce (for example, before opening a PR), run:
+
+```sh
+yarn check:ssr
+```
+
+`yarn compile` does not regenerate these files; it copies them from `src/` into `dist/esm/` alongside the compiled JS.
+
 ### Known issue with Storybook site hot-reloading during development
 
 Storybook will watch modules for changes and hot-reload the module when necessary. This is usually great but poses a problem when the module being hot-reloaded defines a custom element. A custom element name can only be defined by the `CustomElementsRegistry` once, so reloading a module that defines a custom element will attempt to re-register the custom element name, throwing an error because the name has already been defined. This error will manifest with the following message:

packages/web-components/package.json

@@ -79,11 +79,10 @@
     "compile:benchmark": "rollup -c rollup.bench.js",
     "clean": "node ./scripts/clean dist",
     "generate-api": "api-extractor run --local",
-    "build": "yarn compile && yarn build:rollup && yarn build:ssr && yarn generate-api && yarn analyze",
-    "build:ssr:templates": "fast-test-harness generate-templates --tag-prefix=fluent",
-    "build:ssr:styles": "fast-test-harness generate-stylesheets",
-    "build:ssr": "yarn build:ssr:templates && yarn build:ssr:styles",
+    "build": "yarn compile && yarn build:rollup && yarn generate-api && yarn analyze",
     "build:rollup": "rollup -c",
+    "generate:ssr": "node ./scripts/generate-ssr.js",
+    "check:ssr": "node ./scripts/generate-ssr.js --check",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "format": "prettier -w src/**/*.{ts,html} src/*.{ts,html} --ignore-path ../../.prettierignore",

packages/web-components/scripts/compile.js

@@ -1,27 +1,47 @@
 /* eslint-disable no-undef */
 
-import { execSync } from 'child_process';
-import chalk from 'chalk';
-
-main();
+import { execSync } from 'node:child_process';
+import { cp, glob, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 
-function compile() {
-  try {
-    console.log(chalk.bold(`🎬 compile:start`));
+import chalk from 'chalk';
 
-    console.log(chalk.blueBright(`compile: generating design tokens`));
-    execSync(`node ./scripts/generate-tokens`, { stdio: 'inherit' });
+const SRC = 'src';
+const OUT = 'dist/esm';
 
-    console.log(chalk.blueBright(`compile: running tsc`));
-    execSync(`tsc -p tsconfig.lib.json --rootDir ./src --baseUrl .`, { stdio: 'inherit' });
+async function copySsrAssets() {
+  const patterns = ['**/*.template.html', '**/*.styles.css'];
+  let count = 0;
 
-    console.log(chalk.bold(`🏁 compile:end`));
-  } catch (err) {
-    console.error(err);
-    process.exit(1);
+  for (const pattern of patterns) {
+    for await (const file of glob(pattern, { cwd: SRC })) {
+      const from = join(SRC, file);
+      const to = join(OUT, file);
+      await mkdir(dirname(to), { recursive: true });
+      await cp(from, to);
+      count++;
+    }
   }
+
+  console.log(chalk.dim(`compile: copied ${count} SSR asset${count === 1 ? '' : 's'} from ${SRC}/ → ${OUT}/`));
 }
 
-function main() {
-  compile();
+async function compile() {
+  console.log(chalk.bold(`🎬 compile:start`));
+
+  console.log(chalk.blueBright(`compile: generating design tokens`));
+  execSync(`node ./scripts/generate-tokens`, { stdio: 'inherit' });
+
+  console.log(chalk.blueBright(`compile: running tsc`));
+  execSync(`tsc -p tsconfig.lib.json --rootDir ./src --baseUrl .`, { stdio: 'inherit' });
+
+  console.log(chalk.blueBright(`compile: copying SSR assets`));
+  await copySsrAssets();
+
+  console.log(chalk.bold(`🏁 compile:end`));
 }
+
+compile().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

packages/web-components/scripts/generate-ssr.js

@@ -0,0 +1,219 @@
+/* eslint-disable no-undef */
+
+/**
+ * Regenerates SSR template HTML and stylesheet CSS files next to their
+ * source `.template.ts` / `.styles.ts` counterparts in `src/`.
+ *
+ * Flow:
+ *   1. Compile `src/` to a throwaway temp dir so we have JS modules with
+ *      runtime metadata for the generators to walk.
+ *   2. Run `generate-templates` and `generate-stylesheets` from the
+ *      `@microsoft/fast-test-harness` library, writing back into `src/`
+ *      while preserving the per-component subdirectory structure.
+ *
+ * The generated files should be committed to the repo; the normal `compile` script
+ * copies them into `dist/esm/`.
+ *
+ * Running this script is only necessary when making changes to the source `.template.ts` or `.styles.ts` files,
+ * and should be part of the development workflow when working on those files. The generated files can then
+ * be modified as needed for SSR purposes, and those modifications should also be committed to the repo.
+ *
+ * Pass `--check` to compare what regeneration would produce against the
+ * current working tree without writing. Each output file is classified
+ * against the matrix of (TS@HEAD vs TS@working) × (HTML@HEAD vs
+ * HTML@working) × (regen output vs disk). Exits non-zero when any
+ * stale, hand-edited, or conflicting files are detected.
+ */
+
+import { execSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { glob, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+import chalk from 'chalk';
+import prettier from 'prettier';
+
+import { generateStylesheets } from '@microsoft/fast-test-harness/build/generate-stylesheets.js';
+import { generateFTemplates } from '@microsoft/fast-test-harness/build/generate-templates.js';
+
+const cwd = process.cwd();
+const TEMP_PARENT = join(cwd, 'temp');
+const checkMode = process.argv.includes('--check');
+const label = checkMode ? 'generate:ssr:check' : 'generate:ssr';
+
+async function main() {
+  mkdirSync(TEMP_PARENT, { recursive: true });
+  const tempDir = mkdtempSync(join(TEMP_PARENT, 'ssr-'));
+  const stagingDir = checkMode ? mkdtempSync(join(TEMP_PARENT, 'ssr-staging-')) : null;
+  const prettierConfig = (await prettier.resolveConfig(cwd)) ?? {};
+  const outDir = stagingDir ? relative(cwd, stagingDir) : 'src';
+  let exitCode = 0;
+
+  try {
+    console.log(chalk.bold(`🎬 ${label} start`));
+
+    console.log(chalk.blueBright(`${label}: compiling src → ${tempDir}`));
+    execSync(`tsc -p tsconfig.lib.json --rootDir ./src --baseUrl . --outDir ${tempDir} --declaration false`, {
+      stdio: 'inherit',
+    });
+
+    console.log(chalk.blueBright(`${label}: writing *.template.html → ${outDir}/`));
+    await generateFTemplates({
+      cwd,
+      distDir: tempDir,
+      outDir,
+      tagPrefix: 'fluent',
+      format: content =>
+        prettier.format(content, { ...prettierConfig, parser: 'html', htmlWhitespaceSensitivity: 'ignore' }),
+    });
+
+    console.log(chalk.blueBright(`${label}: writing *.styles.css → ${outDir}/`));
+    await generateStylesheets({
+      cwd,
+      distDir: tempDir,
+      outDir,
+      format: content => prettier.format(content, { ...prettierConfig, parser: 'css' }),
+    });
+
+    if (checkMode) {
+      const result = await classify(stagingDir);
+      printSummary(result);
+      if (result.stale.length || result.handEdited.length || result.conflicts.length) {
+        exitCode = 1;
+      }
+    }
+
+    console.log(chalk.bold(`🏁 ${label} end`));
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+    if (stagingDir) rmSync(stagingDir, { recursive: true, force: true });
+  }
+
+  if (exitCode) process.exit(exitCode);
+}
+
+/**
+ * Classify each staged file against the working tree using the
+ * four-state matrix. Returns counts plus per-bucket file lists.
+ *
+ * - `unchanged`  — regen produces the file already on disk
+ * - `created`    — no committed baseline for this HTML/CSS
+ * - `updated`    — TS changed; regen produces new HTML/CSS (normal flow)
+ * - `stale`      — TS and HTML both at HEAD, but regen disagrees with disk
+ *                  (committed state is out of sync — CI failure signal)
+ * - `handEdited` — HTML differs from HEAD with no TS change; regen would clobber
+ * - `conflicts`  — both TS and HTML differ from HEAD, and regen disagrees with disk
+ */
+async function classify(stagingDir) {
+  const dirtyMap = buildDirtyMap();
+  // git status --porcelain paths are relative to the repo root; lookups
+  // need to be prefixed with the path from repo root to cwd.
+  const repoPrefix = execSync('git rev-parse --show-prefix', { cwd, encoding: 'utf8' }).trim();
+  const dirtyStatus = path => statusOf(dirtyMap.get(repoPrefix + path));
+  const result = {
+    unchanged: [],
+    created: [],
+    updated: [],
+    stale: [],
+    handEdited: [],
+    conflicts: [],
+  };
+
+  for (const pattern of ['**/*.template.html', '**/*.styles.css']) {
+    for await (const file of glob(pattern, { cwd: stagingDir })) {
+      const stagedAbs = join(stagingDir, file);
+      const srcHtmlAbs = join(cwd, 'src', file);
+      const srcHtmlRel = join('src', file);
+
+      let srcTsRel;
+      if (file.endsWith('.template.html')) {
+        srcTsRel = join('src', file.replace(/\.template\.html$/, '.template.ts'));
+      } else if (file.endsWith('.styles.css')) {
+        srcTsRel = join('src', file.replace(/\.styles\.css$/, '.styles.ts'));
+      } else {
+        continue;
+      }
+
+      const tsStatus = dirtyStatus(srcTsRel);
+      const htmlStatus = dirtyStatus(srcHtmlRel);
+      const newHtml = await readFile(stagedAbs, 'utf8');
+      const onDiskHtml = await readFile(srcHtmlAbs, 'utf8').catch(() => null);
+
+      if (newHtml === onDiskHtml) {
+        result.unchanged.push(file);
+        continue;
+      }
+
+      if (htmlStatus === 'new') {
+        result.created.push(file);
+        continue;
+      }
+
+      if (htmlStatus === 'same') {
+        if (tsStatus === 'same') {
+          result.stale.push(file);
+        } else {
+          result.updated.push(file);
+        }
+        continue;
+      }
+
+      // htmlStatus === 'changed'
+      if (tsStatus === 'same') {
+        result.handEdited.push(file);
+      } else {
+        result.conflicts.push(file);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * One git invocation that returns a map of {pathRelativeToCwd → status code}
+ * for every file that differs from HEAD (modified, added, untracked, etc.).
+ * Tracked files in sync with HEAD are absent from the map.
+ */
+function buildDirtyMap() {
+  const map = new Map();
+  const output = execSync('git status --porcelain=v1 -uall', { cwd, encoding: 'utf8' });
+  for (const line of output.split('\n')) {
+    if (!line) continue;
+    const code = line.slice(0, 2);
+    let path = line.slice(3);
+    if (path.startsWith('"')) path = JSON.parse(path);
+    const arrow = path.indexOf(' -> '); // rename: "old -> new"
+    if (arrow !== -1) path = path.slice(arrow + 4);
+    map.set(path, code);
+  }
+  return map;
+}
+
+function statusOf(code) {
+  if (!code) return 'same';
+  if (code[0] === '?' || code[0] === 'A') return 'new';
+  return 'changed';
+}
+
+function printSummary({ unchanged, created, updated, stale, handEdited, conflicts }) {
+  console.log(chalk.bold(`\n${label} summary:`));
+  console.log(chalk.green(`  ✓ ${unchanged.length} unchanged`));
+  printBucket(chalk.cyan, '+', created, 'new (no committed baseline)');
+  printBucket(chalk.blue, '✎', updated, 'would update (TS changed)');
+  printBucket(chalk.yellow, '!', stale, 'stale (committed HTML out of sync with committed TS)');
+  printBucket(chalk.yellow, '⚠', handEdited, 'hand-edited (HTML differs from HEAD, TS unchanged)');
+  printBucket(chalk.red, '✘', conflicts, 'conflicts (TS and HTML both differ from HEAD, regen disagrees with disk)');
+  console.log('');
+}
+
+function printBucket(color, glyph, files, description) {
+  if (files.length === 0) return;
+  console.log(color(`  ${glyph} ${files.length} ${description}`));
+  for (const f of files) console.log(chalk.dim(`      ${f}`));
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});