@pharos-ds/build 0.1.9

package/src/vite.test.ts

@@ -0,0 +1,48 @@
+// 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 `pharos-base`); the
+ *   theme layer name is fixed at `pharos-theme`.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {pharosStylex} from './vite';
+
+/** Pull the injected `@layer ...;` order statement out of the plugin set. */
+function getLayerOrder(plugins: ReturnType<typeof pharosStylex>): string {
+  const layerPlugin = plugins.find(p => p.name === 'pharos-css-layer-order');
+  expect(
+    layerPlugin,
+    'pharos-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('pharosStylex layer order (modern API)', () => {
+  it('uses the pharos-* layer names (theme layer is pharos-theme)', () => {
+    const order = getLayerOrder(pharosStylex());
+    expect(order).toBe('@layer reset, pharos-base, pharos-theme, product;');
+  });
+
+  it('honors configured library and product layer names', () => {
+    const order = getLayerOrder(
+      pharosStylex({layers: {library: 'custom-base', product: 'app'}}),
+    );
+    // The theme layer stays pharos-theme regardless of other layer config.
+    expect(order).toBe('@layer reset, custom-base, pharos-theme, app;');
+  });
+});
+
+describe('pharosStylex layer order (legacy API)', () => {
+  it('uses the pharos-* layer names (theme layer is pharos-theme)', () => {
+    const order = getLayerOrder(pharosStylex({stylexOptions: {}}));
+    expect(order).toBe('@layer reset, pharos-base, pharos-theme, product;');
+  });
+});

package/src/vite.ts

@@ -0,0 +1,429 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {Plugin, UserConfig} from 'vite';
+import stylexBabelPlugin from '@stylexjs/babel-plugin';
+import stylex from '@stylexjs/unplugin';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const LIBRARY_PATTERN = 'node_modules/@pharos-ds/';
+const STYLEX_CSS_PATH = '/virtual:stylex.css';
+
+/**
+ * Browser targets for lightningcss (opt-in).
+ * Only needed if your StyleX version lowers light-dark() without them.
+ * Exported for consumers who want to opt in explicitly.
+ */
+export const LIGHTNINGCSS_TARGETS = {
+  chrome: 123 << 16,
+  firefox: 120 << 16,
+  safari: (17 << 16) | (5 << 8),
+};
+
+/**
+ * Legacy options shape — kept for backward compatibility.
+ * Prefer the zero-config form: pharosStylex()
+ */
+export interface PharosVitePluginLegacyOptions {
+  stylexOptions: Parameters<typeof stylex.vite>[0];
+  libraryPattern?: string;
+  /** StyleX atomic class-name prefix for Pharos library styles. @default 'pharos' */
+  stylexPrefix?: string;
+  layers?: {
+    library?: string;
+    product?: string;
+  };
+}
+
+export interface PharosVitePluginOptions {
+  /**
+   * Whether to enable dev mode for StyleX.
+   * @default process.env.NODE_ENV !== 'production'
+   */
+  dev?: boolean;
+
+  /**
+   * Root directory for module resolution.
+   * @default process.cwd()
+   */
+  rootDir?: string;
+
+  /**
+   * Pattern to identify Pharos library files vs product files.
+   * @default 'node_modules/@pharos-ds/'
+   */
+  libraryPattern?: string;
+
+  /**
+   * CSS layer names for the split output.
+   */
+  layers?: {
+    /** Layer name for Pharos library styles @default 'pharos-base' */
+    library?: string;
+    /** Layer name for product styles @default 'product' */
+    product?: string;
+  };
+
+  /**
+   * LightningCSS browser targets. Only needed if your StyleX version
+   * lowers light-dark() without them. Most recent versions preserve
+   * light-dark() by default.
+   * @default undefined (no targets set)
+   */
+  lightningcssTargets?: Record<string, number>;
+
+  /**
+   * StyleX atomic class-name prefix for Pharos *library* styles. The product
+   * build uses a distinct prefix so library and product atoms never collide
+   * across layers.
+   *
+   * Configurable if a consumer needs a custom library atom prefix.
+   * Defaults to `pharos`.
+   *
+   * @default 'pharos'
+   */
+  stylexPrefix?: string;
+
+  /**
+   * Extra StyleX options to merge.
+   */
+  stylexOverrides?: Record<string, unknown>;
+}
+
+/**
+ * Pharos Vite plugin for source builds.
+ *
+ * Provides sensible defaults for StyleX compilation with Pharos.
+ * Just spread into your plugins array:
+ *
+ *   plugins: [...pharosStylex(), react()]
+ *
+ * Handles:
+ * - StyleX compilation with correct settings
+ * - CSS layer ordering (reset < pharos-base < pharos-theme < product)
+ * - resolve.alias for @pharos-ds/core source
+ * - optimizeDeps.exclude to prevent Vite pre-bundling Pharos
+ *
+ * @param options — optional overrides
+ */
+export function pharosStylex(
+  options: PharosVitePluginOptions | PharosVitePluginLegacyOptions = {},
+): Plugin[] {
+  // Detect legacy API: pharosStylex({stylexOptions: {...}})
+  if ('stylexOptions' in options && options.stylexOptions) {
+    return pharosStylexLegacy(options as PharosVitePluginLegacyOptions);
+  }
+
+  const opts = options as PharosVitePluginOptions;
+  const {
+    dev = process.env.NODE_ENV !== 'production',
+    rootDir = process.cwd(),
+    libraryPattern = LIBRARY_PATTERN,
+    layers = {},
+    lightningcssTargets,
+    stylexPrefix = 'pharos',
+    stylexOverrides = {},
+  } = opts;
+
+  const libraryLayer = layers.library ?? 'pharos-base';
+  const productLayer = layers.product ?? 'product';
+
+  // Build StyleX options with sensible defaults
+  const stylexOptions: Record<string, unknown> = {
+    dev,
+    runtimeInjection: false,
+    treeshakeCompensation: true,
+    unstable_moduleResolution: {
+      type: 'commonJS',
+      rootDir,
+    },
+    ...(lightningcssTargets && {
+      lightningcssOptions: {targets: lightningcssTargets},
+    }),
+    ...stylexOverrides,
+  };
+
+  // Inject our babel wrapper as a user plugin — it runs before the
+  // unplugin's hardcoded StyleX instance and handles prefix routing.
+  const pharosBabelPlugin = path.resolve(__dirname, 'babel.js');
+
+  const basePlugin = stylex.vite({
+    ...(stylexOptions as any),
+    useCSSLayers: true,
+    babelConfig: {
+      plugins: [
+        [
+          pharosBabelPlugin,
+          {
+            ...stylexOptions,
+            libraryPrefix: stylexPrefix,
+            babelConfig: undefined,
+          },
+        ],
+      ],
+    },
+  });
+
+  // Layer order declaration plugin
+  const layerOrderPlugin: Plugin = {
+    name: 'pharos-css-layer-order',
+    transformIndexHtml() {
+      return [
+        {
+          tag: 'style',
+          children: `@layer reset, ${libraryLayer}, pharos-theme, ${productLayer};`,
+          injectTo: 'head-prepend',
+        },
+      ];
+    },
+  };
+
+  // Config plugin — injects resolve.alias and optimizeDeps
+  const configPlugin: Plugin = {
+    name: 'pharos-config',
+    config(): UserConfig {
+      // Discover all @pharos-ds/* packages to exclude from pre-bundling.
+      // Pharos ships as source that must be compiled by StyleX — pre-bundling
+      // strips stylex.create/defineVars calls and causes runtime errors.
+      let xdsPackages: string[] = ['@pharos-ds/core'];
+      try {
+        const fs = require('node:fs');
+        const xdsDir = path.resolve(rootDir, 'node_modules/@pharos-ds');
+        if (fs.existsSync(xdsDir)) {
+          xdsPackages = fs
+            .readdirSync(xdsDir)
+            .filter((name: string) => !name.startsWith('.'))
+            .map((name: string) => `@pharos-ds/${name}`);
+        }
+      } catch {
+        // Fallback to just @pharos-ds/core if discovery fails
+      }
+
+      return {
+        resolve: {
+          alias: {
+            '@pharos-ds/core/theme/tokens.stylex': path.resolve(
+              rootDir,
+              'node_modules/@pharos-ds/core/src/theme/tokens.stylex.ts',
+            ),
+            '@pharos-ds/core': path.resolve(
+              rootDir,
+              'node_modules/@pharos-ds/core/src',
+            ),
+          },
+        },
+        optimizeDeps: {
+          exclude: xdsPackages,
+        },
+      };
+    },
+  };
+
+  // Split-layer interceptor plugin (dev server only)
+  const splitLayerPlugin: Plugin = {
+    name: 'pharos-split-layers',
+    configureServer(server) {
+      let stylexPlugin: any = null;
+
+      return () => {
+        for (const p of server.config.plugins.flat()) {
+          if ((p as any)?.__stylexGetSharedStore) {
+            stylexPlugin = p;
+            break;
+          }
+        }
+
+        server.middlewares.stack.unshift({
+          route: '',
+          handle: (req: any, res: any, next: any) => {
+            if (!req.url?.startsWith(STYLEX_CSS_PATH)) {
+              return next();
+            }
+
+            if (!stylexPlugin) {
+              res.statusCode = 200;
+              res.setHeader('Content-Type', 'text/css');
+              res.end('');
+              return;
+            }
+
+            const shared = stylexPlugin.__stylexGetSharedStore?.();
+            const rulesById = shared?.rulesById;
+
+            if (!rulesById || rulesById.size === 0) {
+              res.statusCode = 200;
+              res.setHeader('Content-Type', 'text/css');
+              res.end('');
+              return;
+            }
+
+            const libraryRules: any[] = [];
+            const productRules: any[] = [];
+
+            for (const [filePath, rules] of rulesById.entries()) {
+              if (filePath.includes(libraryPattern)) {
+                libraryRules.push(...rules);
+              } else {
+                productRules.push(...rules);
+              }
+            }
+
+            const libraryCss = libraryRules.length
+              ? stylexBabelPlugin.processStylexRules(libraryRules, {
+                  useLayers: true,
+                })
+              : '';
+            const productCss = productRules.length
+              ? stylexBabelPlugin.processStylexRules(productRules, {
+                  useLayers: true,
+                })
+              : '';
+
+            const parts: string[] = [];
+            if (libraryCss)
+              parts.push(`@layer ${libraryLayer} {\n${libraryCss}\n}`);
+            if (productCss)
+              parts.push(`@layer ${productLayer} {\n${productCss}\n}`);
+
+            res.statusCode = 200;
+            res.setHeader('Content-Type', 'text/css');
+            res.setHeader('Cache-Control', 'no-store');
+            res.end(parts.join('\n\n'));
+          },
+        });
+      };
+    },
+  };
+
+  return [configPlugin, layerOrderPlugin, basePlugin, splitLayerPlugin];
+}
+
+/**
+ * Legacy implementation — handles the old pharosStylex({stylexOptions: {...}}) API.
+ * Used by Storybook and other existing configs.
+ */
+function pharosStylexLegacy(options: PharosVitePluginLegacyOptions): Plugin[] {
+  const {
+    stylexOptions,
+    libraryPattern = LIBRARY_PATTERN,
+    stylexPrefix = 'pharos',
+    layers = {},
+  } = options;
+
+  const libraryLayer = layers.library ?? 'pharos-base';
+  const productLayer = layers.product ?? 'product';
+
+  const pharosBabelPlugin = path.resolve(__dirname, 'babel.js');
+  const existingPlugins = (stylexOptions as any).babelConfig?.plugins ?? [];
+
+  const basePlugin = stylex.vite({
+    ...(stylexOptions as any),
+    useCSSLayers: true,
+    babelConfig: {
+      ...(stylexOptions as any).babelConfig,
+      plugins: [
+        [
+          pharosBabelPlugin,
+          {
+            ...(stylexOptions as any),
+            libraryPrefix: stylexPrefix,
+            babelConfig: undefined,
+          },
+        ],
+        ...existingPlugins,
+      ],
+    },
+  });
+
+  const layerOrderPlugin: Plugin = {
+    name: 'pharos-css-layer-order',
+    transformIndexHtml() {
+      return [
+        {
+          tag: 'style',
+          children: `@layer reset, ${libraryLayer}, pharos-theme, ${productLayer};`,
+          injectTo: 'head-prepend',
+        },
+      ];
+    },
+  };
+
+  const splitLayerPlugin: Plugin = {
+    name: 'pharos-split-layers',
+    configureServer(server) {
+      let stylexPlugin: any = null;
+
+      return () => {
+        for (const p of server.config.plugins.flat()) {
+          if ((p as any)?.__stylexGetSharedStore) {
+            stylexPlugin = p;
+            break;
+          }
+        }
+
+        server.middlewares.stack.unshift({
+          route: '',
+          handle: (req: any, res: any, next: any) => {
+            if (!req.url?.startsWith(STYLEX_CSS_PATH)) {
+              return next();
+            }
+
+            if (!stylexPlugin) {
+              res.statusCode = 200;
+              res.setHeader('Content-Type', 'text/css');
+              res.end('');
+              return;
+            }
+
+            const shared = stylexPlugin.__stylexGetSharedStore?.();
+            const rulesById = shared?.rulesById;
+
+            if (!rulesById || rulesById.size === 0) {
+              res.statusCode = 200;
+              res.setHeader('Content-Type', 'text/css');
+              res.end('');
+              return;
+            }
+
+            const libraryRules: any[] = [];
+            const productRules: any[] = [];
+
+            for (const [filePath, rules] of rulesById.entries()) {
+              if (filePath.includes(libraryPattern)) {
+                libraryRules.push(...rules);
+              } else {
+                productRules.push(...rules);
+              }
+            }
+
+            const libraryCss = libraryRules.length
+              ? stylexBabelPlugin.processStylexRules(libraryRules, {
+                  useLayers: true,
+                })
+              : '';
+            const productCss = productRules.length
+              ? stylexBabelPlugin.processStylexRules(productRules, {
+                  useLayers: true,
+                })
+              : '';
+
+            const parts: string[] = [];
+            if (libraryCss)
+              parts.push(`@layer ${libraryLayer} {\n${libraryCss}\n}`);
+            if (productCss)
+              parts.push(`@layer ${productLayer} {\n${productCss}\n}`);
+
+            res.statusCode = 200;
+            res.setHeader('Content-Type', 'text/css');
+            res.setHeader('Cache-Control', 'no-store');
+            res.end(parts.join('\n\n'));
+          },
+        });
+      };
+    },
+  };
+
+  return [layerOrderPlugin, basePlugin, splitLayerPlugin];
+}