@pharos-ds/build 0.1.9

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Caio Silvestre
+
+Copyright (c) 2026 Meta Platforms, Inc.
+(portions derived from Astryx — https://github.com/facebook/astryx)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# @pharos-ds/build
+
+Build plugins for XDS source builds. Provides babel, PostCSS, and Vite integrations that compile XDS library and product code with separate class name prefixes, which enables independent CSS layers:
+
+```
+reset < pharos-base (library, pharos prefix) < pharos-theme < product (app, x prefix)
+```
+
+## Why?
+
+StyleX generates atomic CSS: same declaration = same class name. Without separate prefixes, library and product classes collide and can't be placed in independent CSS layers, which breaks theme overrides.
+
+`@pharos-ds/build` solves this by:
+
+1. Compiling XDS library code with `pharos` prefix (`.pharos78zum5`)
+2. Compiling product code with default `x` prefix (`.x78zum5`)
+3. Placing each group in its own CSS `@layer`
+
+## Packages
+
+| Export                     | Purpose                                      | Platform                    |
+| -------------------------- | -------------------------------------------- | --------------------------- |
+| `@pharos-ds/build/babel`   | Babel plugin: splits class prefixes per file | Next.js, any babel pipeline |
+| `@pharos-ds/build/postcss` | PostCSS plugin: compiles + splits CSS layers | Next.js                     |
+| `@pharos-ds/build/vite`    | Vite plugin: wraps unplugin + splits layers  | Vite, Storybook             |
+
+## Install
+
+```bash
+npm install -D @pharos-ds/build @stylexjs/babel-plugin @babel/core
+```
+
+For Vite, also install:
+
+```bash
+npm install -D @stylexjs/unplugin
+```
+
+---
+
+## Next.js Setup
+
+### 1. babel.config.js
+
+```js
+const path = require('path');
+
+module.exports = {
+  presets: ['next/babel'],
+  plugins: [
+    [
+      '@pharos-ds/build/babel',
+      {
+        dev: process.env.NODE_ENV !== 'production',
+        runtimeInjection: false,
+        treeshakeCompensation: true,
+        enableInlinedConditionalMerge: true,
+        aliases: {
+          '@pharos-ds/core/*': [
+            path.join(__dirname, 'node_modules/@pharos-ds/core/*'),
+          ],
+          '@pharos-ds/core': [
+            path.join(__dirname, 'node_modules/@pharos-ds/core'),
+          ],
+        },
+        unstable_moduleResolution: {type: 'commonJS'},
+      },
+    ],
+  ],
+};
+```
+
+### 2. postcss.config.js
+
+```js
+const path = require('path');
+
+module.exports = {
+  plugins: {
+    '@pharos-ds/build/postcss': {
+      appDir: 'src',
+      babelPlugins: [
+        [
+          '@stylexjs/babel-plugin',
+          {
+            dev: process.env.NODE_ENV !== 'production',
+            runtimeInjection: false,
+            treeshakeCompensation: true,
+            enableInlinedConditionalMerge: true,
+            aliases: {
+              '@pharos-ds/core/*': [
+                path.join(__dirname, 'node_modules/@pharos-ds/core/*'),
+              ],
+              '@pharos-ds/core': [
+                path.join(__dirname, 'node_modules/@pharos-ds/core'),
+              ],
+            },
+            unstable_moduleResolution: {type: 'commonJS'},
+          },
+        ],
+      ],
+    },
+  },
+};
+```
+
+### 3. next.config.mjs
+
+```js
+const nextConfig = {
+  transpilePackages: ['@pharos-ds/core', '@pharos-ds/theme-pharos'],
+  webpack: config => {
+    // Resolve to source TypeScript instead of dist
+    config.resolve.conditionNames = ['source', 'import', 'require', 'default'];
+    return config;
+  },
+};
+
+export default nextConfig;
+```
+
+### 4. CSS files
+
+`src/app/layers.css`:
+
+```css
+@layer reset, pharos-base, pharos-theme, product;
+```
+
+`src/app/globals.css`:
+
+```css
+@import './layers.css';
+@import '@pharos-ds/core/reset.css';
+@import '@pharos-ds/theme-pharos/theme.css';
+
+@stylex;
+```
+
+> `layers.css` must be a separate file because webpack hoists `@import` content above inline CSS.
+
+### 5. Browserslist
+
+```json
+{
+  "browserslist": ["last 1 Chrome version"]
+}
+```
+
+---
+
+## Vite Setup
+
+```ts
+import {pharosStylex} from '@pharos-ds/build/vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [
+    ...pharosStylex({
+      stylexOptions: {
+        dev: process.env.NODE_ENV === 'development',
+        runtimeInjection: false,
+        treeshakeCompensation: true,
+        unstable_moduleResolution: {
+          type: 'commonJS',
+          rootDir: __dirname,
+        },
+      },
+    }),
+    react(),
+  ],
+  resolve: {
+    alias: {
+      '@pharos-ds/core': path.resolve(
+        __dirname,
+        'node_modules/@pharos-ds/core/src',
+      ),
+    },
+  },
+  optimizeDeps: {
+    exclude: ['@pharos-ds/core', '@pharos-ds/theme-pharos'],
+  },
+});
+```
+
+---
+
+## How it works
+
+### Babel plugin (`@pharos-ds/build/babel`)
+
+Wraps `@stylexjs/babel-plugin` with two internal instances: one with `classNamePrefix: 'pharos'` for library files, one with default `'x'` for product files. Routes each file to the correct instance based on its path.
+
+Library patterns (configurable):
+
+- `packages/core/`
+- `packages/themes/`
+- `node_modules/@pharos-ds/`
+
+### PostCSS plugin (`@pharos-ds/build/postcss`)
+
+Compiles StyleX from both library and product source files in two separate passes with different prefixes. Wraps the results in named `@layer` blocks:
+
+- Library rules → `@layer pharos-base`
+- Product rules → `@layer product`
+
+### Vite plugin (`@pharos-ds/build/vite`)
+
+Wraps `@stylexjs/unplugin` and intercepts the dev CSS endpoint (`/virtual:stylex.css`). Partitions the collected rules by file path and serves split-layer CSS.
+
+---
+
+## Advanced Options
+
+### Babel plugin
+
+```js
+[
+  '@pharos-ds/build/babel',
+  {
+    // Patterns to identify library files (default shown)
+    libraryPatterns: [
+      'packages/core/',
+      'packages/themes/',
+      'node_modules/@pharos-ds/',
+    ],
+
+    // Class name prefix for library styles (default: 'pharos')
+    libraryPrefix: 'pharos',
+
+    // Class name prefix for product styles (default: 'x')
+    classNamePrefix: 'x',
+
+    // ... all @stylexjs/babel-plugin options
+  },
+];
+```
+
+### PostCSS plugin
+
+```js
+'@pharos-ds/build/postcss': {
+  appDir: 'src',           // Your app source directory
+  babelPlugins: [...],     // StyleX babel plugin config
+  libraryPrefix: 'pharos',   // Prefix for library CSS (default: 'pharos')
+  extraInclude: [...],     // Additional glob patterns
+  layers: {                // Layer names (defaults shown)
+    library: 'pharos-base',
+    product: 'product',
+  },
+}
+```
+
+## Related
+
+- [example-nextjs-source](../../apps/example-nextjs-source/): full Next.js source build example
+- [`@stylexjs/babel-plugin`](https://github.com/facebook/stylex): the underlying StyleX compiler

package/dist/vite.d.ts

@@ -0,0 +1,91 @@
+import type { Plugin } from 'vite';
+import stylex from '@stylexjs/unplugin';
+/**
+ * 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 declare const LIGHTNINGCSS_TARGETS: {
+    chrome: number;
+    firefox: number;
+    safari: number;
+};
+/**
+ * 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 declare function pharosStylex(options?: PharosVitePluginOptions | PharosVitePluginLegacyOptions): Plugin[];

package/dist/vite.mjs

@@ -0,0 +1,287 @@
+// Built from src/vite.ts — do not edit directly
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/vite.ts
+import stylexBabelPlugin from "@stylexjs/babel-plugin";
+import stylex from "@stylexjs/unplugin";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var LIBRARY_PATTERN = "node_modules/@pharos-ds/";
+var STYLEX_CSS_PATH = "/virtual:stylex.css";
+var LIGHTNINGCSS_TARGETS = {
+  chrome: 123 << 16,
+  firefox: 120 << 16,
+  safari: 17 << 16 | 5 << 8
+};
+function pharosStylex(options = {}) {
+  if ("stylexOptions" in options && options.stylexOptions) {
+    return pharosStylexLegacy(options);
+  }
+  const opts = options;
+  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";
+  const stylexOptions = {
+    dev,
+    runtimeInjection: false,
+    treeshakeCompensation: true,
+    unstable_moduleResolution: {
+      type: "commonJS",
+      rootDir
+    },
+    ...lightningcssTargets && {
+      lightningcssOptions: { targets: lightningcssTargets }
+    },
+    ...stylexOverrides
+  };
+  const pharosBabelPlugin = path.resolve(__dirname, "../src/babel.js");
+  const basePlugin = stylex.vite({
+    ...stylexOptions,
+    useCSSLayers: true,
+    babelConfig: {
+      plugins: [
+        [
+          pharosBabelPlugin,
+          {
+            ...stylexOptions,
+            libraryPrefix: stylexPrefix,
+            babelConfig: void 0
+          }
+        ]
+      ]
+    }
+  });
+  const layerOrderPlugin = {
+    name: "pharos-css-layer-order",
+    transformIndexHtml() {
+      return [
+        {
+          tag: "style",
+          children: `@layer reset, ${libraryLayer}, pharos-theme, ${productLayer};`,
+          injectTo: "head-prepend"
+        }
+      ];
+    }
+  };
+  const configPlugin = {
+    name: "pharos-config",
+    config() {
+      let xdsPackages = ["@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) => !name.startsWith(".")).map((name) => `@pharos-ds/${name}`);
+        }
+      } catch {
+      }
+      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
+        }
+      };
+    }
+  };
+  const splitLayerPlugin = {
+    name: "pharos-split-layers",
+    configureServer(server) {
+      let stylexPlugin = null;
+      return () => {
+        for (const p of server.config.plugins.flat()) {
+          if (p?.__stylexGetSharedStore) {
+            stylexPlugin = p;
+            break;
+          }
+        }
+        server.middlewares.stack.unshift({
+          route: "",
+          handle: (req, res, next) => {
+            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 = [];
+            const productRules = [];
+            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 = [];
+            if (libraryCss)
+              parts.push(`@layer ${libraryLayer} {
+${libraryCss}
+}`);
+            if (productCss)
+              parts.push(`@layer ${productLayer} {
+${productCss}
+}`);
+            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];
+}
+function pharosStylexLegacy(options) {
+  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, "../src/babel.js");
+  const existingPlugins = stylexOptions.babelConfig?.plugins ?? [];
+  const basePlugin = stylex.vite({
+    ...stylexOptions,
+    useCSSLayers: true,
+    babelConfig: {
+      ...stylexOptions.babelConfig,
+      plugins: [
+        [
+          pharosBabelPlugin,
+          {
+            ...stylexOptions,
+            libraryPrefix: stylexPrefix,
+            babelConfig: void 0
+          }
+        ],
+        ...existingPlugins
+      ]
+    }
+  });
+  const layerOrderPlugin = {
+    name: "pharos-css-layer-order",
+    transformIndexHtml() {
+      return [
+        {
+          tag: "style",
+          children: `@layer reset, ${libraryLayer}, pharos-theme, ${productLayer};`,
+          injectTo: "head-prepend"
+        }
+      ];
+    }
+  };
+  const splitLayerPlugin = {
+    name: "pharos-split-layers",
+    configureServer(server) {
+      let stylexPlugin = null;
+      return () => {
+        for (const p of server.config.plugins.flat()) {
+          if (p?.__stylexGetSharedStore) {
+            stylexPlugin = p;
+            break;
+          }
+        }
+        server.middlewares.stack.unshift({
+          route: "",
+          handle: (req, res, next) => {
+            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 = [];
+            const productRules = [];
+            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 = [];
+            if (libraryCss)
+              parts.push(`@layer ${libraryLayer} {
+${libraryCss}
+}`);
+            if (productCss)
+              parts.push(`@layer ${productLayer} {
+${productCss}
+}`);
+            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];
+}
+export {
+  LIGHTNINGCSS_TARGETS,
+  pharosStylex
+};