feat(mosaic): render compound components from Server Components

.changeset/mosaic-rsc-compound-components.md

@@ -0,0 +1,5 @@
+---
+'@clerk/mosaic': patch
+---
+
+Compound components such as `Avatar`, `Banner`, `DataList`, `EmptyState`, `Entity`, `Item` and `Table` can now be rendered from React Server Components, e.g. `<Avatar.Root>` in a Next.js App Router page. Each compound export is now a module namespace object instead of a plain object, so `X.Part` usage is unchanged, but its parts are read-only: assigning to `X.Part` no longer replaces it.

packages/mosaic/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
   "files": [
-    { "path": "./dist/index.js", "maxSize": "95KB" },
+    { "path": "./dist/.bundlewatch/index.js", "maxSize": "95KB" },
     { "path": "./dist/styles.css", "maxSize": "18KB" }
   ]
 }

packages/mosaic/package.json

@@ -117,14 +117,15 @@
     "dist",
     "!dist/**/*.d.ts.map",
     "!dist/**/*.d.mts.map",
+    "!dist/.bundlewatch",
     "styles.css.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
     "build": "pnpm build:js && pnpm build:css && pnpm check:bundle && pnpm typecheck",
     "build:css": "tsdown --config tsdown.css.config.mts",
     "build:js": "tsdown --config tsdown.config.mts",
-    "bundlewatch": "FORCE_COLOR=1 bundlewatch --config bundlewatch.config.json",
+    "bundlewatch": "node ./scripts/bundle-for-size.mjs && FORCE_COLOR=1 bundlewatch --config bundlewatch.config.json",
     "check:bundle": "node ./scripts/check-bundle.mjs",
     "clean": "rimraf ./dist ./dist-css",
     "dev": "tsdown --config tsdown.config.mts --watch",

packages/mosaic/scripts/bundle-for-size.mjs

@@ -0,0 +1,16 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { build } from 'rolldown';
+
+const packageDir = resolve(import.meta.dirname, '..');
+const packageJson = JSON.parse(await readFile(resolve(packageDir, 'package.json'), 'utf8'));
+const externals = Object.keys({ ...packageJson.dependencies, ...packageJson.peerDependencies });
+
+await build({
+  input: resolve(packageDir, 'dist/index.js'),
+  platform: 'browser',
+  external: id => externals.some(name => id === name || id.startsWith(`${name}/`)),
+  output: { dir: resolve(packageDir, 'dist/.bundlewatch'), entryFileNames: '[name].js', format: 'esm' },
+  logLevel: 'warn',
+});

packages/mosaic/scripts/check-bundle.mjs

@@ -1,17 +1,64 @@
 import { readdir, readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { dirname, relative, resolve } from 'node:path';
 
 const distDir = resolve(import.meta.dirname, '../dist');
 const jsFiles = (await readdir(distDir, { recursive: true })).filter(file => file.endsWith('.js'));
 const sources = await Promise.all(jsFiles.map(file => readFile(resolve(distDir, file), 'utf8')));
-const componentEntries = (await readdir(resolve(distDir, 'components')))
-  .filter(file => file.endsWith('.js'))
-  .map(file => `components/${file}`);
-
-for (const entryFile of ['index.js', ...componentEntries]) {
-  const entry = await readFile(resolve(distDir, entryFile), 'utf8');
-  if (!entry.startsWith("'use client';") && !entry.startsWith('"use client";')) {
-    throw new Error(`Published Mosaic JS entry ${entryFile} is missing a top-level 'use client' boundary.`);
+const packageJson = JSON.parse(await readFile(resolve(import.meta.dirname, '../package.json'), 'utf8'));
+const entryFiles = Object.entries(packageJson.exports)
+  .filter(([subpath]) => subpath === '.' || /^\.\/(components|primitives)\//.test(subpath))
+  .map(([, target]) => target)
+  .map(target => (typeof target === 'string' ? target : target.import))
+  .filter(file => file?.endsWith('.js'))
+  .map(file => resolve(import.meta.dirname, '..', file));
+
+const isClientModule = source => source.startsWith("'use client';") || source.startsWith('"use client";');
+const importsOf = source =>
+  [...source.matchAll(/^import\s+(?:[^'"]*?\s+from\s+)?["']([^"']+)["'];?$/gm)].map(m => m[1]);
+const importsReact = source =>
+  importsOf(source).some(specifier => specifier === 'react' || specifier.startsWith('react/'));
+const code = source =>
+  source
+    .replace(/\/\/.*$/gm, '')
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean);
+
+const checkNamespaceEntry = async (entryFile, source) => {
+  const display = relative(distDir, entryFile);
+  const lines = code(source);
+  const namespaceImport = /^import \{ (\w+) \} from "(\.[^"]+)";$/;
+  const namespaceExport = /^export \{ (\w+ as \w+(?:, \w+ as \w+)*) \};$/;
+  if (!lines.every(line => namespaceImport.test(line) || namespaceExport.test(line))) {
+    throw new Error(
+      `Published Mosaic JS entry ${display} must start with 'use client' or contain only \`export * as\` namespace re-exports.`,
+    );
+  }
+  for (const line of lines.filter(line => namespaceImport.test(line))) {
+    const [, binding, specifier] = line.match(namespaceImport);
+    const partsFile = resolve(dirname(entryFile), specifier);
+    const parts = await readFile(partsFile, 'utf8');
+    if (isClientModule(parts) || !new RegExp(`^var ${binding} = /\\* @__PURE__ \\*/ __exportAll\\(`, 'm').test(parts)) {
+      throw new Error(
+        `${display} imports ${binding} from ${relative(distDir, partsFile)}, which must be a namespace object with no directive.`,
+      );
+    }
+    for (const leafSpecifier of importsOf(parts).filter(specifier => specifier.startsWith('.'))) {
+      const leafFile = resolve(dirname(partsFile), leafSpecifier);
+      const leaf = await readFile(leafFile, 'utf8');
+      if (importsReact(leaf) && !isClientModule(leaf)) {
+        throw new Error(
+          `${relative(distDir, leafFile)}, re-exported by the namespace ${relative(distDir, partsFile)}, imports React but is missing a top-level 'use client' boundary.`,
+        );
+      }
+    }
+  }
+};
+
+for (const entryFile of entryFiles) {
+  const source = await readFile(entryFile, 'utf8');
+  if (!isClientModule(source)) {
+    await checkNamespaceEntry(entryFile, source);
   }
 }
 

packages/mosaic/src/components/avatar/index.ts

@@ -1,5 +1,3 @@
-'use client';
-
 /**
  * Compound avatar. `Avatar.Root` positions and sizes the box; `Avatar.Image` renders
  * once its source loads; `Avatar.Fallback` holds the space until then, as a blank

packages/mosaic/src/components/banner/index.ts

@@ -1,5 +1,3 @@
-'use client';
-
 /**
  * A tinted strip that annotates the surface it sits on with a status message. Composed through
  * `Banner.Root`, `Banner.Label`, and `Banner.Description`; every part accepts the Mosaic `render`

packages/mosaic/src/components/data-list/index.ts

@@ -1,5 +1,3 @@
-'use client';
-
 /**
  * Mosaic `DataList` — label/value pairs for read-only detail, such as the fields describing a
  * device or a payment method. Composed via dot syntax: `DataList.Root`, `DataList.Item`,

packages/mosaic/src/components/empty-state/index.ts

@@ -1,5 +1,3 @@
-'use client';
-
 export * as EmptyState from './empty-state.parts';
 export type {
   EmptyStateActionsProps,

packages/mosaic/src/components/entity/index.ts

@@ -1,3 +1 @@
-'use client';
-
 export * as Entity from './entity.parts';

packages/mosaic/src/components/item/index.ts

@@ -1,5 +1,3 @@
-'use client';
-
 /**
  * Mosaic `Item` — a row for lists of accounts, organizations, and settings.
  * Composed via dot syntax: `Item.Root`, `Item.Media`, `Item.Content`,

packages/mosaic/src/components/table/index.ts

@@ -1,5 +1,3 @@
-'use client';
-
 export * as Table from './table.parts';
 export type {
   TableAlign,

packages/mosaic/tsdown.config.mts

@@ -38,6 +38,7 @@ export default defineConfig({
     tsgo: { path: getTypeScriptExecutablePath() },
   },
   clean: true,
+  unbundle: true,
   target: 'es2022',
   platform: 'browser',
   minify: false,