@astryxdesign/build 0.0.0-bootstrap.0 → 0.0.15

package/src/babel.js

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+"use strict";
+
+/**
+ * @astryxdesign/build/babel
+ *
+ * Babel plugin that delegates to @stylexjs/babel-plugin with a
+ * different classNamePrefix for Astryx library files vs product files.
+ *
+ * Library files get 'astryx' prefix (.astryx78zum5), product files get 'x' (.x78zum5).
+ */
+
+const LIBRARY_PATTERNS = [
+  'packages/core/',
+  'packages/themes/',
+  'packages/lab/',
+  'node_modules/@astryxdesign/',
+];
+
+module.exports = function xdsBabelPlugin(api, options) {
+  const stylexPlugin = require('@stylexjs/babel-plugin');
+
+  const {
+    libraryPatterns = LIBRARY_PATTERNS,
+    libraryPrefix = 'astryx',
+    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: 'xds-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 `astryx` 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 xdsBabelPlugin = 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/@astryxdesign/core/src/Box/XDSBox.tsx',
+    babelrc: false,
+    configFile: false,
+    plugins: [
+      [
+        xdsBabelPlugin,
+        {
+          ...(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" / "astryx1a2b3c" in the compiled output.
+  return code.match(/\b(?:xds|astryx|lib)[a-z0-9]{4,}\b/g) ?? [];
+}
+
+describe('xds babel wrapper -- library StyleX prefix', () => {
+  it('defaults library atoms to the `astryx` prefix', () => {
+    const code = transformLibraryFile(undefined);
+    const atoms = atomicClasses(code);
+    expect(atoms.length).toBeGreaterThan(0);
+    expect(atoms.every(c => c.startsWith('astryx'))).toBe(true);
+    expect(
+      atoms.some(c => c.startsWith('xds') && !c.startsWith('astryx')),
+    ).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";
+
+/**
+ * @astryxdesign/build
+ *
+ * Unified build configuration for Astryx source builds.
+ * 
+ * Usage:
+ *   // babel.config.js
+ *   const {babel} = require('@astryxdesign/build');
+ *   module.exports = babel(__dirname);
+ * 
+ *   // postcss.config.js
+ *   const {postcss} = require('@astryxdesign/build');
+ *   module.exports = postcss(__dirname);
+ */
+
+const path = require('node:path');
+
+/**
+ * Resolve Astryx package aliases from a root directory.
+ * Handles both npm installs (node_modules/@astryxdesign/core) and
+ * monorepo layouts (packages/core).
+ */
+function resolveAliases(rootDir) {
+  const coreDir = path.join(rootDir, 'node_modules/@astryxdesign/core');
+  return {
+    '@astryxdesign/core/*': [path.join(coreDir, '*')],
+    '@astryxdesign/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 Astryx 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 Astryx 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";
+
+/**
+ * @astryxdesign/postcss-plugin
+ *
+ * PostCSS plugin for Astryx source builds. Compiles StyleX from both
+ * Astryx library source and product code in two separate passes with
+ * different class name prefixes, then outputs them in separate layers:
+ *
+ *   reset < astryx-base (library, prefix: 'astryx') < astryx-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 = '@astryxdesign/postcss-plugin';
+
+const LIBRARY_GLOB = 'node_modules/@astryxdesign/**/*.{ts,tsx}';
+const LIBRARY_PATTERNS = ['node_modules/@astryxdesign/', '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: 'astryx-base',
+      product: 'product',
+    },
+    // Class name prefix for library styles (product keeps default 'x')
+    libraryPrefix = 'astryx',
+    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,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+"use strict";
+
+/**
+ * @astryxdesign/build/next
+ *
+ * Next.js configuration helper for Astryx source builds.
+ *
+ * Usage in next.config.mjs:
+ *   import {withXDS} from '@astryxdesign/build/next';
+ *   export default withXDS({
+ *     // your normal next config
+ *   });
+ */
+
+/**
+ * Wraps a Next.js config to enable Astryx source builds.
+ * - Adds transpilePackages for @astryxdesign/* packages
+ * - Sets conditionNames to resolve source exports
+ */
+function withXDS(nextConfig = {}) {
+  const xdsPackages = [
+    '@astryxdesign/core',
+    '@astryxdesign/theme-default',
+    '@astryxdesign/theme-neutral',
+    '@astryxdesign/theme-brutalist',
+    '@astryxdesign/theme-daily',
+    '@astryxdesign/lab',
+  ];
+
+  const existingTranspile = nextConfig.transpilePackages || [];
+  const merged = Array.from(new Set([...existingTranspile, ...xdsPackages]));
+
+  const existingWebpack = nextConfig.webpack;
+
+  return {
+    ...nextConfig,
+    transpilePackages: merged,
+    webpack: (config, context) => {
+      // Resolve to source exports
+      config.resolve.conditionNames = [
+        'source',
+        'import',
+        'require',
+        'default',
+      ];
+
+      // Preserve the symlinked node_modules path so Next.js's
+      // transpilePackages matcher recognizes @astryxdesign/* packages under
+      // pnpm's symlinked layout. Without this, webpack dereferences
+      // the symlink to packages/<name>/... which doesn't contain
+      // "node_modules/@astryxdesign" and transpilation is silently skipped,
+      // breaking subpath imports like '@astryxdesign/core/AlertDialog'.
+      config.resolve.symlinks = false;
+
+      // Call user's webpack config if provided
+      if (existingWebpack) {
+        return existingWebpack(config, context);
+      }
+      return config;
+    },
+  };
+}
+
+module.exports = {withXDS};

package/src/vite.test.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file vite.test.ts
+ * @description Verifies CSS layer-order injection in the XDS Vite plugin.
+ *   The library layer name is configurable (default `astryx-base`); the
+ *   theme layer name is fixed at `astryx-theme`.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {xdsStylex} from './vite';
+
+/** Pull the injected `@layer ...;` order statement out of the plugin set. */
+function getLayerOrder(plugins: ReturnType<typeof xdsStylex>): string {
+  const layerPlugin = plugins.find(p => p.name === 'xds-css-layer-order');
+  expect(layerPlugin, 'xds-css-layer-order plugin should exist').toBeTruthy();
+  const transform = (layerPlugin as any).transformIndexHtml;
+  const tags =
+    typeof transform === 'function' ? transform() : transform.handler();
+  const styleTag = tags.find((t: any) => t.tag === 'style');
+  expect(styleTag, 'a <style> tag should be injected').toBeTruthy();
+  return styleTag.children as string;
+}
+
+describe('xdsStylex layer order (modern API)', () => {
+  it('uses the astryx-* layer names (theme layer is astryx-theme)', () => {
+    const order = getLayerOrder(xdsStylex());
+    expect(order).toBe('@layer reset, astryx-base, astryx-theme, product;');
+  });
+
+  it('honors configured library and product layer names', () => {
+    const order = getLayerOrder(
+      xdsStylex({layers: {library: 'custom-base', product: 'app'}}),
+    );
+    // The theme layer stays astryx-theme regardless of other layer config.
+    expect(order).toBe('@layer reset, custom-base, astryx-theme, app;');
+  });
+});
+
+describe('xdsStylex layer order (legacy API)', () => {
+  it('uses the astryx-* layer names (theme layer is astryx-theme)', () => {
+    const order = getLayerOrder(xdsStylex({stylexOptions: {}}));
+    expect(order).toBe('@layer reset, astryx-base, astryx-theme, product;');
+  });
+});