@pharos-ds/build 0.1.9

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@pharos-ds/build",
+  "version": "0.1.9",
+  "description": "Build plugins for XDS source builds — babel, PostCSS, and Vite integrations",
+  "author": "Caio Silvestre",
+  "license": "MIT",
+  "homepage": "https://github.com/Caio-Silvestre/alexandria-ds#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Caio-Silvestre/alexandria-ds.git",
+    "directory": "packages/build"
+  },
+  "bugs": {
+    "url": "https://github.com/Caio-Silvestre/alexandria-ds/issues"
+  },
+  "keywords": [
+    "pharos",
+    "postcss",
+    "stylex",
+    "css-layers",
+    "design-system"
+  ],
+  "main": "./src/config.js",
+  "exports": {
+    ".": "./src/config.js",
+    "./babel": "./src/babel.js",
+    "./postcss": "./src/index.js",
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.mjs"
+    },
+    "./next": "./src/next.js"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "peerDependencies": {
+    "@stylexjs/babel-plugin": ">=0.18.0",
+    "@babel/core": ">=7.0.0",
+    "@stylexjs/unplugin": ">=0.18.0",
+    "vite": "^8.1.3"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.0",
+    "glob-parent": "^6.0.0",
+    "is-glob": "^4.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1"
+  },
+  "peerDependenciesMeta": {
+    "@stylexjs/unplugin": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs"
+  }
+}

package/src/babel.js

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+"use strict";
+
+/**
+ * @pharos-ds/build/babel
+ *
+ * Babel plugin that delegates to @stylexjs/babel-plugin with a
+ * different classNamePrefix for Pharos library files vs product files.
+ *
+ * Library files get 'pharos' prefix (.pharos78zum5), product files get 'x' (.x78zum5).
+ */
+
+const LIBRARY_PATTERNS = [
+  'packages/core/',
+  'packages/themes/',
+  'packages/lab/',
+  'node_modules/@pharos-ds/',
+];
+
+module.exports = function pharosBabelPlugin(api, options) {
+  const stylexPlugin = require('@stylexjs/babel-plugin');
+
+  const {
+    libraryPatterns = LIBRARY_PATTERNS,
+    libraryPrefix = 'pharos',
+    classNamePrefix = 'x',
+    ...stylexOptions
+  } = options;
+
+  // Build the two sets of options — only classNamePrefix differs
+  const libraryOpts = {...stylexOptions, classNamePrefix: libraryPrefix};
+  const productOpts = {...stylexOptions, classNamePrefix};
+
+  // Create two plugin instances
+  const libraryPlugin = stylexPlugin(api, libraryOpts);
+  const productPlugin = stylexPlugin(api, productOpts);
+
+  function getPluginAndOpts(filename) {
+    const isLibrary = libraryPatterns.some(p => filename.includes(p));
+    return isLibrary
+      ? {plugin: libraryPlugin, opts: libraryOpts}
+      : {plugin: productPlugin, opts: productOpts};
+  }
+
+  // Helper: call a visitor function with overridden state.opts
+  function callVisitor(visitor, key, path, state) {
+    const {plugin, opts} = getPluginAndOpts(state.filename || '');
+    const v = plugin.visitor[key];
+    if (!v) return;
+
+    // Override state.opts so StyleX reads the correct classNamePrefix
+    const originalOpts = state.opts;
+    state.opts = opts;
+
+    try {
+      if (typeof v === 'function') {
+        v.call(this, path, state);
+      } else if (typeof v === 'object') {
+        // enter/exit form — should not happen at top level for stylex
+        // but handle it anyway
+        if (visitor === 'enter' && v.enter) v.enter.call(this, path, state);
+        if (visitor === 'exit' && v.exit) v.exit.call(this, path, state);
+      }
+    } finally {
+      state.opts = originalOpts;
+    }
+  }
+
+  // Get all visitor keys
+  const allKeys = new Set([
+    ...Object.keys(libraryPlugin.visitor || {}),
+    ...Object.keys(productPlugin.visitor || {}),
+  ]);
+
+  const visitor = {};
+
+  for (const key of allKeys) {
+    const sample = libraryPlugin.visitor[key] || productPlugin.visitor[key];
+
+    if (typeof sample === 'object' && (sample.enter || sample.exit)) {
+      // enter/exit form (Program uses this)
+      visitor[key] = {};
+      if (sample.enter) {
+        visitor[key].enter = function(path, state) {
+          callVisitor.call(this, 'enter', key, path, state);
+        };
+      }
+      if (sample.exit) {
+        visitor[key].exit = function(path, state) {
+          callVisitor.call(this, 'exit', key, path, state);
+        };
+      }
+    } else {
+      // Simple function visitor
+      visitor[key] = function(path, state) {
+        callVisitor.call(this, 'enter', key, path, state);
+      };
+    }
+  }
+
+  return {
+    name: 'pharos-babel-plugin',
+    visitor,
+  };
+};

package/src/babel.test.mjs

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file babel.test.mjs
+ * @description Verifies that the XDS babel wrapper applies the configured
+ *   library StyleX class-name prefix to XDS library files. Part of the
+ *   the library atom prefix defaults to `pharos` and is configurable
+ *   before the final cutover.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {createRequire} from 'node:module';
+
+const require = createRequire(import.meta.url);
+const babel = require('@babel/core');
+const pharosBabelPlugin = require('./babel.js');
+
+const SOURCE = `
+import * as stylex from '@stylexjs/stylex';
+export const styles = stylex.create({
+  box: {color: 'red'},
+});
+`;
+
+/**
+ * Transform a StyleX source through the XDS babel wrapper as if it were a
+ * library file, returning the emitted code. `libraryPrefix` controls the
+ * atomic class-name prefix for library files.
+ */
+function transformLibraryFile(libraryPrefix) {
+  const result = babel.transformSync(SOURCE, {
+    // A path matching one of the library patterns so the wrapper routes it
+    // through the library plugin instance.
+    filename: 'node_modules/@pharos-ds/core/src/Box/XDSBox.tsx',
+    babelrc: false,
+    configFile: false,
+    plugins: [
+      [
+        pharosBabelPlugin,
+        {
+          ...(libraryPrefix ? {libraryPrefix} : {}),
+          unstable_moduleResolution: {type: 'commonJS', rootDir: process.cwd()},
+        },
+      ],
+    ],
+  });
+  return result?.code ?? '';
+}
+
+/** Extract the StyleX atomic class names referenced in the emitted code. */
+function atomicClasses(code) {
+  // StyleX emits atoms like "xds1a2b3c" / "pharos1a2b3c" in the compiled output.
+  return code.match(/\b(?:xds|pharos|lib)[a-z0-9]{4,}\b/g) ?? [];
+}
+
+describe('xds babel wrapper -- library StyleX prefix', () => {
+  it('defaults library atoms to the `pharos` prefix', () => {
+    const code = transformLibraryFile(undefined);
+    const atoms = atomicClasses(code);
+    expect(atoms.length).toBeGreaterThan(0);
+    expect(atoms.every(c => c.startsWith('pharos'))).toBe(true);
+    expect(
+      atoms.some(c => c.startsWith('xds') && !c.startsWith('pharos')),
+    ).toBe(false);
+  });
+
+  it('uses a configured custom prefix for library atoms', () => {
+    const code = transformLibraryFile('lib');
+    const atoms = atomicClasses(code);
+    expect(atoms.length).toBeGreaterThan(0);
+    expect(atoms.every(c => c.startsWith('lib'))).toBe(true);
+  });
+});

package/src/config.js

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+"use strict";
+
+/**
+ * @pharos-ds/build
+ *
+ * Unified build configuration for Pharos source builds.
+ * 
+ * Usage:
+ *   // babel.config.js
+ *   const {babel} = require('@pharos-ds/build');
+ *   module.exports = babel(__dirname);
+ * 
+ *   // postcss.config.js
+ *   const {postcss} = require('@pharos-ds/build');
+ *   module.exports = postcss(__dirname);
+ */
+
+const path = require('node:path');
+
+/**
+ * Resolve Pharos package aliases from a root directory.
+ * Handles both npm installs (node_modules/@pharos-ds/core) and
+ * monorepo layouts (packages/core).
+ */
+function resolveAliases(rootDir) {
+  const coreDir = path.join(rootDir, 'node_modules/@pharos-ds/core');
+  return {
+    '@pharos-ds/core/*': [path.join(coreDir, '*')],
+    '@pharos-ds/core': [coreDir],
+  };
+}
+
+/**
+ * Build shared StyleX babel plugin options from a root directory.
+ */
+function stylexOptions(rootDir, overrides = {}) {
+  return {
+    dev: process.env.NODE_ENV !== 'production',
+    runtimeInjection: false,
+    enableInlinedConditionalMerge: true,
+    treeshakeCompensation: true,
+    aliases: resolveAliases(rootDir),
+    unstable_moduleResolution: {
+      type: 'commonJS',
+    },
+    ...overrides,
+  };
+}
+
+/**
+ * Generate a complete babel.config.js for Pharos source builds.
+ * 
+ * @param {string} rootDir — __dirname of the project root
+ * @param {object} [overrides] — extra StyleX options to merge
+ * @returns {object} babel config object
+ */
+function babel(rootDir, overrides = {}) {
+  return {
+    presets: ['next/babel'],
+    plugins: [
+      [require.resolve('./babel.js'), stylexOptions(rootDir, overrides)],
+    ],
+  };
+}
+
+/**
+ * Generate a complete postcss.config.js for Pharos source builds.
+ * 
+ * @param {string} rootDir — __dirname of the project root
+ * @param {object} [overrides] — extra options (appDir, extraInclude, etc.)
+ * @returns {object} postcss config object
+ */
+function postcss(rootDir, overrides = {}) {
+  const {appDir = 'src', extraInclude = [], ...rest} = overrides;
+  return {
+    plugins: {
+      [require.resolve('./index.js')]: {
+        cwd: rootDir,
+        appDir,
+        babelPlugins: [
+          ['@stylexjs/babel-plugin', stylexOptions(rootDir, rest)],
+        ],
+        extraInclude,
+      },
+      autoprefixer: {},
+    },
+  };
+}
+
+module.exports = {babel, postcss, stylexOptions, resolveAliases};

package/src/index.js

@@ -0,0 +1,251 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+"use strict";
+
+/**
+ * @pharos-ds/postcss-plugin
+ *
+ * PostCSS plugin for Pharos source builds. Compiles StyleX from both
+ * Pharos library source and product code in two separate passes with
+ * different class name prefixes, then outputs them in separate layers:
+ *
+ *   reset < pharos-base (library, prefix: 'pharos') < pharos-theme < product (prefix: 'x')
+ *
+ * The separate prefixes ensure atomic classes don't collide between
+ * layers, which would break theme overrides.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const postcss = require('postcss');
+const babel = require('@babel/core');
+const stylexBabelPlugin = require('@stylexjs/babel-plugin');
+const {globSync} = require('fast-glob');
+const isGlob = require('is-glob');
+const globParent = require('glob-parent');
+
+const PLUGIN_NAME = '@pharos-ds/postcss-plugin';
+
+const LIBRARY_GLOB = 'node_modules/@pharos-ds/**/*.{ts,tsx}';
+const LIBRARY_PATTERNS = ['node_modules/@pharos-ds/', 'packages/core/', 'packages/themes/'];
+const STYLEX_IMPORT_SOURCE = '@stylexjs/stylex';
+
+function parseDependency(fileOrGlob, cwd) {
+  if (fileOrGlob.startsWith('!')) return null;
+  if (isGlob(fileOrGlob)) {
+    const base = globParent(fileOrGlob);
+    let glob = fileOrGlob.substring(base === '.' ? 0 : base.length);
+    if (glob.charAt(0) === '/') glob = glob.substring(1);
+    return {
+      type: 'dir-dependency',
+      dir: path.normalize(path.resolve(cwd, base)),
+      glob,
+    };
+  }
+  return {
+    type: 'dependency',
+    file: path.normalize(path.resolve(cwd, fileOrGlob)),
+  };
+}
+
+/**
+ * Clone a babel plugins array, overriding the classNamePrefix on the
+ * StyleX babel plugin entry.
+ */
+function withClassNamePrefix(plugins, prefix) {
+  return plugins.map(p => {
+    if (!Array.isArray(p)) return p;
+    const [pluginPath, opts] = p;
+    // Match @stylexjs/babel-plugin by name
+    const name = typeof pluginPath === 'string' ? pluginPath : '';
+    if (name.includes('@stylexjs/babel-plugin') || name.includes('stylex')) {
+      return [pluginPath, {...opts, classNamePrefix: prefix}];
+    }
+    return p;
+  });
+}
+
+function createPlugin() {
+  const isDev = process.env.NODE_ENV === 'development';
+
+  // Separate rule maps for library and product
+  const libraryRulesMap = new Map();
+  const productRulesMap = new Map();
+  const fileModifiedMap = new Map();
+
+  const plugin = ({
+    cwd = process.cwd(),
+    appDir = 'src',
+    babelPlugins = [],
+    layers = {
+      library: 'pharos-base',
+      product: 'product',
+    },
+    // Class name prefix for library styles (product keeps default 'x')
+    libraryPrefix = 'pharos',
+    extraInclude = [],
+    libraryPatterns = LIBRARY_PATTERNS,
+    exclude = [],
+  }) => {
+    const include = [
+      `${appDir}/**/*.{js,jsx,ts,tsx}`,
+      LIBRARY_GLOB,
+      ...extraInclude,
+    ];
+
+    const excludeWithDefaults = ['**/*.d.ts', '**/*.flow', ...exclude];
+
+    // Two babel configs — different classNamePrefix
+    const libraryBabelConfig = {
+      babelrc: false,
+      parserOpts: {plugins: ['typescript', 'jsx']},
+      plugins: withClassNamePrefix(babelPlugins, libraryPrefix),
+    };
+
+    const productBabelConfig = {
+      babelrc: false,
+      parserOpts: {plugins: ['typescript', 'jsx']},
+      plugins: babelPlugins, // keeps default 'x' prefix
+    };
+
+    let shouldSkipTransformError = false;
+
+    return {
+      postcssPlugin: PLUGIN_NAME,
+      plugins: [
+        async function (root, result) {
+          const fileName = result.opts.from;
+
+          let styleXAtRule = null;
+          root.walkAtRules((atRule) => {
+            if (atRule.name === 'stylex' && !atRule.params) {
+              styleXAtRule = atRule;
+            }
+          });
+          if (styleXAtRule == null) return;
+
+          // Discover files
+          const files = new Set();
+          for (const pattern of include) {
+            const matched = globSync(pattern, {
+              onlyFiles: true,
+              ignore: excludeWithDefaults,
+              cwd,
+            });
+            for (const f of matched) {
+              files.add(path.normalize(path.resolve(cwd, f)));
+            }
+          }
+
+          // Watch dependencies
+          for (const pattern of include) {
+            const dep = parseDependency(pattern, cwd);
+            if (dep) {
+              result.messages.push({
+                plugin: PLUGIN_NAME,
+                parent: fileName,
+                ...dep,
+              });
+            }
+          }
+
+          // Remove deleted files
+          for (const f of fileModifiedMap.keys()) {
+            if (!files.has(f)) {
+              fileModifiedMap.delete(f);
+              libraryRulesMap.delete(f);
+              productRulesMap.delete(f);
+            }
+          }
+
+          // Partition files into library vs product, then compile
+          // each group with its own babel config (different prefix)
+          const transforms = [];
+          for (const filePath of files) {
+            const mtimeMs = fs.existsSync(filePath)
+              ? fs.statSync(filePath).mtimeMs
+              : -Infinity;
+            if (
+              fileModifiedMap.has(filePath) &&
+              mtimeMs === fileModifiedMap.get(filePath)
+            ) {
+              continue;
+            }
+            fileModifiedMap.set(filePath, mtimeMs);
+
+            const contents = fs.readFileSync(filePath, 'utf-8');
+            if (!contents.includes(STYLEX_IMPORT_SOURCE)) continue;
+
+            const isLibrary = libraryPatterns.some(p => filePath.includes(p));
+            const config = isLibrary ? libraryBabelConfig : productBabelConfig;
+            const rulesMap = isLibrary ? libraryRulesMap : productRulesMap;
+
+            transforms.push(
+              babel
+                .transformAsync(contents, {
+                  filename: filePath,
+                  caller: {name: PLUGIN_NAME, platform: 'web', isDev},
+                  ...config,
+                })
+                .then(({metadata}) => {
+                  const stylex = metadata?.stylex;
+                  if (stylex != null && stylex.length > 0) {
+                    rulesMap.set(filePath, stylex);
+                  }
+                })
+                .catch((error) => {
+                  if (shouldSkipTransformError) {
+                    console.warn(
+                      `[${PLUGIN_NAME}] Failed to transform "${filePath}": ${error.message}`,
+                    );
+                  } else {
+                    throw error;
+                  }
+                }),
+            );
+          }
+          await Promise.all(transforms);
+
+          // Collect rules from each map
+          const libraryRules = Array.from(libraryRulesMap.values()).flat();
+          const productRules = Array.from(productRulesMap.values()).flat();
+
+          // Process each group separately
+          const libraryCss = libraryRules.length
+            ? stylexBabelPlugin.processStylexRules(libraryRules, {
+                useLayers: true,
+              })
+            : '';
+          const productCss = productRules.length
+            ? stylexBabelPlugin.processStylexRules(productRules, {
+                useLayers: true,
+              })
+            : '';
+
+          // Wrap in named layers
+          const parts = [];
+          if (libraryCss) {
+            parts.push(`@layer ${layers.library} {\n${libraryCss}\n}`);
+          }
+          if (productCss) {
+            parts.push(`@layer ${layers.product} {\n${productCss}\n}`);
+          }
+
+          const finalCss = parts.join('\n\n');
+          const parsed = await postcss.parse(finalCss, {from: fileName});
+          styleXAtRule.replaceWith(parsed);
+          result.root = root;
+
+          if (!shouldSkipTransformError) {
+            shouldSkipTransformError = true;
+          }
+        },
+      ],
+    };
+  };
+
+  plugin.postcss = true;
+  return plugin;
+}
+
+module.exports = createPlugin();

package/src/next.js

@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+"use strict";
+
+/**
+ * @pharos-ds/build/next
+ *
+ * Next.js configuration helper for Pharos source builds.
+ *
+ * Usage in next.config.mjs:
+ *   import {withPharos} from '@pharos-ds/build/next';
+ *   export default withPharos({
+ *     // your normal next config
+ *   });
+ */
+
+/**
+ * Wraps a Next.js config to enable Pharos source builds.
+ * - Adds transpilePackages for @pharos-ds/* packages
+ * - Sets conditionNames to resolve source exports
+ */
+function withPharos(nextConfig = {}) {
+  const pharosPackages = [
+    '@pharos-ds/core',
+    '@pharos-ds/theme-neutral',
+    '@pharos-ds/lab',
+  ];
+
+  const existingTranspile = nextConfig.transpilePackages || [];
+  const merged = Array.from(new Set([...existingTranspile, ...pharosPackages]));
+
+  const existingWebpack = nextConfig.webpack;
+
+  return {
+    ...nextConfig,
+    transpilePackages: merged,
+    webpack: (config, context) => {
+      // Pharos packages are consumed from their `source` export (raw TS) so
+      // the sandbox/docsite build straight from src without a prebuild step.
+      // Apply the `source` condition via a scoped, ALLOWLIST rule that only
+      // matches @pharos-ds packages — the global conditions stay as Next's
+      // defaults (webpack's `'...'` sentinel + react-server), which React JSX
+      // resolution depends on. Third-party deps (e.g. `lexical`, which also
+      // ships a `source` export) therefore resolve to their built output, not
+      // raw TS. This is robust to new third-party `source`-shipping deps.
+      config.module = config.module || {};
+      config.module.rules = config.module.rules || [];
+      config.module.rules.unshift({
+        test: /[\\/]node_modules[\\/]@pharos-ds[\\/]/,
+        resolve: {
+          conditionNames: ['source', '...'],
+        },
+      });
+
+      // Preserve the symlinked node_modules path so Next.js's
+      // transpilePackages matcher recognizes @pharos-ds/* packages under
+      // pnpm's symlinked layout. Without this, webpack dereferences
+      // the symlink to packages/<name>/... which doesn't contain
+      // "node_modules/@pharos-ds" and transpilation is silently skipped,
+      // breaking subpath imports like '@pharos-ds/core/AlertDialog'.
+      config.resolve.symlinks = false;
+
+      // Call user's webpack config if provided
+      if (existingWebpack) {
+        return existingWebpack(config, context);
+      }
+      return config;
+    },
+  };
+}
+
+module.exports = {withPharos};