@stylexjs/babel-plugin 0.2.0-beta.9 → 0.4.0

package/lib/index.js.flow

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import type { PluginObj } from '../flow_modules/@babel/core';
+import type { StyleXOptions } from './utils/state-manager';
+export type Options = StyleXOptions;
+
+/**
+ * Entry point for the StyleX babel plugin.
+ */
+declare function styleXTransform(): PluginObj<>;
+
+declare function stylexPluginWithOptions(
+  options: Partial<StyleXOptions>,
+): [typeof styleXTransform, Partial<StyleXOptions>];
+/**
+ *
+ * @param rules An array of CSS rules that has been generated and collected from all JS files
+ * in a project
+ * @returns A string that represents the final CSS file.
+ *
+ * This function take an Array of CSS rules, de-duplicates them, sorts them priority and generates
+ * a final CSS file.
+ *
+ * When Stylex is correctly configured, the babel plugin will return an array of CSS rule objects.
+ * You're expected to concatenate all the Rules into a single Array and use this function to convert
+ * that into the final CSS file.
+ *
+ * End-users can choose to not use this function and use their own logic instead.
+ */
+export type Rule = [string, { ltr: string, rtl?: null | string }, number];
+declare function processStylexRules(
+  rules: Array<Rule>,
+  useLayers: boolean,
+): string;
+
+export type StyleXTransformObj = $ReadOnly<{
+  (): PluginObj<>,
+  withOptions: typeof stylexPluginWithOptions,
+  processStylexRules: typeof processStylexRules,
+  ...
+}>;
+
+declare export default StyleXTransformObj;

package/lib/utils/dev-classname.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+import type { CompiledNamespaces } from '@stylexjs/shared';
+import StateManager from './state-manager';
+export declare function namespaceToDevClassName(
+  namespace: string,
+  varName: null | string,
+  filename: string,
+): string;
+export declare function injectDevClassNames(
+  obj: CompiledNamespaces,
+  varName: null | string,
+  state: StateManager,
+): CompiledNamespaces;
+export declare function convertToTestStyles(
+  obj: CompiledNamespaces,
+  varName: null | string,
+  state: StateManager,
+): CompiledNamespaces;

package/lib/utils/dev-classname.js.flow

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import type { CompiledNamespaces } from '@stylexjs/shared';
+import StateManager from './state-manager';
+
+// TODO: We will need to maintain the full path to the file eventually
+// Perhaps this can be an option that is passed in.
+declare export function namespaceToDevClassName(
+  namespace: string,
+  varName: null | string,
+  filename: string,
+): string;
+
+declare export function injectDevClassNames(
+  obj: CompiledNamespaces,
+  varName: null | string,
+  state: StateManager,
+): CompiledNamespaces;
+
+declare export function convertToTestStyles(
+  obj: CompiledNamespaces,
+  varName: null | string,
+  state: StateManager,
+): CompiledNamespaces;

package/lib/utils/evaluate-path.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+import type { NodePath } from '@babel/traverse';
+import StateManager from './state-manager';
+export type FunctionConfig = {
+  identifiers: {
+    [fnName: string]: { fn: (...args: any[]) => any; takesPath?: boolean };
+  };
+  memberExpressions: {
+    [key: string]: {
+      [memberName: string]: {
+        fn: (...args: any[]) => any;
+        takesPath?: boolean;
+      };
+    };
+  };
+};
+export declare function evaluate(
+  path: NodePath,
+  traversalState: StateManager,
+  functions: FunctionConfig,
+): Readonly<{ confident: boolean; value: any; deopt?: null | NodePath }>;

package/lib/utils/evaluate-path.js.flow

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import type { NodePath } from '../../flow_modules/@babel/traverse';
+import StateManager from './state-manager';
+export type FunctionConfig = {
+  identifiers: {
+    [fnName: string]: {
+      fn: (...args: any[]) => any,
+      takesPath?: boolean,
+    },
+  },
+  memberExpressions: {
+    [key: string]: {
+      [memberName: string]: {
+        fn: (...args: any[]) => any,
+        takesPath?: boolean,
+      },
+    },
+  },
+};
+
+declare export function evaluate(
+  path: NodePath<>,
+  traversalState: StateManager,
+  functions: FunctionConfig,
+): $ReadOnly<{
+  confident: boolean,
+  value: any,
+  deopt?: null | NodePath<>,
+}>;

package/lib/utils/helpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+export declare function removeNulls<T>(
+  arr: Array<null | undefined | T>,
+): Array<T>;

package/lib/utils/helpers.js.flow

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+declare export function removeNulls<T>(arr: Array<?T>): Array<T>;

package/lib/utils/js-to-ast.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+import * as t from '@babel/types';
+import { IncludedStyles } from '@stylexjs/shared';
+type NestedStringObject = Readonly<{
+  [key: string]:
+    | string
+    | number
+    | null
+    | boolean
+    | NestedStringObject
+    | IncludedStyles;
+}>;
+export declare function convertObjectToAST(
+  obj: NestedStringObject,
+): t.ObjectExpression;

package/lib/utils/js-to-ast.js.flow

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import * as t from '../../flow_modules/@babel/types';
+import { IncludedStyles } from '@stylexjs/shared';
+
+type NestedStringObject = $ReadOnly<{
+  [key: string]:
+    | string
+    | number
+    | null
+    | boolean
+    | NestedStringObject
+    | IncludedStyles,
+}>;
+
+declare export function convertObjectToAST(
+  obj: NestedStringObject,
+): t.ObjectExpression;

package/lib/utils/state-manager.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+import * as t from '@babel/types';
+import type { PluginPass } from '@babel/core';
+import type { NodePath } from '@babel/traverse';
+import type {
+  CompiledNamespaces,
+  StyleXOptions as RuntimeOptions,
+} from '@stylexjs/shared';
+export type ImportPathResolution =
+  | false
+  | ['themeNameRef' | 'filePath', string];
+type ModuleResolution =
+  | { type: 'commonJS'; rootDir: string; themeFileExtension?: string }
+  | { type: 'haste'; themeFileExtension?: string }
+  | {
+      type: 'experimental_crossFileParsing';
+      rootDir: string;
+      themeFileExtension?: string;
+    };
+export type StyleXOptions = Readonly<
+  Omit<
+    RuntimeOptions,
+    keyof ({
+      importSources: ReadonlyArray<
+        string | Readonly<{ from: string; as: string }>
+      >;
+      runtimeInjection:
+        | boolean
+        | (null | undefined | string)
+        | Readonly<{ from: string; as: string }>;
+      treeshakeCompensation?: boolean;
+      genConditionalClasses: boolean;
+      unstable_moduleResolution: void | ModuleResolution;
+    })
+  > & {
+    importSources: ReadonlyArray<
+      string | Readonly<{ from: string; as: string }>
+    >;
+    runtimeInjection:
+      | boolean
+      | (null | undefined | string)
+      | Readonly<{ from: string; as: string }>;
+    treeshakeCompensation?: boolean;
+    genConditionalClasses: boolean;
+    unstable_moduleResolution: void | ModuleResolution;
+  }
+>;
+type StyleXStateOptions = Readonly<
+  Omit<
+    StyleXOptions,
+    keyof ({
+      runtimeInjection:
+        | (null | undefined | string)
+        | Readonly<{ from: string; as: string }>;
+    })
+  > & {
+    runtimeInjection:
+      | (null | undefined | string)
+      | Readonly<{ from: string; as: string }>;
+  }
+>;
+declare class StateManager {
+  readonly _state: PluginPass;
+  readonly importPaths: Set<string>;
+  readonly stylexImport: Set<string>;
+  readonly stylexPropsImport: Set<string>;
+  readonly stylexCreateImport: Set<string>;
+  readonly stylexIncludeImport: Set<string>;
+  readonly stylexFirstThatWorksImport: Set<string>;
+  readonly stylexKeyframesImport: Set<string>;
+  readonly stylexDefineVarsImport: Set<string>;
+  readonly stylexCreateThemeImport: Set<string>;
+  readonly stylexTypesImport: Set<string>;
+  injectImportInserted: null | undefined | t.Identifier;
+  readonly styleMap: Map<string, CompiledNamespaces>;
+  readonly styleVars: Map<string, NodePath>;
+  readonly styleVarsToKeep: Set<[string, true | string, true | Array<string>]>;
+  inStyleXCreate: boolean;
+  constructor(state: PluginPass);
+  get options(): StyleXStateOptions;
+  get importPathString(): string;
+  get importSources(): ReadonlyArray<string>;
+  importAs(source: string): null | string;
+  get canReferenceTheme(): boolean;
+  get metadata(): { [key: string]: any };
+  get runtimeInjection():
+    | null
+    | undefined
+    | Readonly<{ from: string; as?: string }>;
+  get isDev(): boolean;
+  get isTest(): boolean;
+  get filename(): string | void;
+  get cssVars(): any;
+  get treeshakeCompensation(): boolean;
+  get fileNameForHashing(): null | string;
+  importPathResolver(importPath: string): ImportPathResolution;
+  addStyle(style: [string, { ltr: string; rtl?: string | null }, number]): void;
+  markComposedNamespace(
+    memberExpression: [string, true | string, true | Array<string>],
+  ): void;
+}
+export default StateManager;

package/lib/utils/state-manager.js.flow

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import * as t from '../../flow_modules/@babel/types';
+import type { PluginPass } from '../../flow_modules/@babel/core';
+import type { NodePath } from '../../flow_modules/@babel/traverse';
+import type {
+  CompiledNamespaces,
+  StyleXOptions as RuntimeOptions,
+} from '@stylexjs/shared';
+export type ImportPathResolution =
+  | false
+  | ['themeNameRef' | 'filePath', string];
+
+type ModuleResolution =
+  | {
+      type: 'commonJS',
+      rootDir: string,
+      themeFileExtension?: string,
+    }
+  | {
+      type: 'haste',
+      themeFileExtension?: string,
+    }
+  | {
+      type: 'experimental_crossFileParsing',
+      rootDir: string,
+      themeFileExtension?: string,
+    };
+
+export type StyleXOptions = $ReadOnly<{
+  ...RuntimeOptions,
+  importSources: $ReadOnlyArray<
+    string | $ReadOnly<{ from: string, as: string }>,
+  >,
+  runtimeInjection: boolean | ?string | $ReadOnly<{ from: string, as: string }>,
+  treeshakeCompensation?: boolean,
+  genConditionalClasses: boolean,
+  unstable_moduleResolution: void | ModuleResolution,
+  ...
+}>;
+
+type StyleXStateOptions = $ReadOnly<{
+  ...StyleXOptions,
+  runtimeInjection: ?string | $ReadOnly<{ from: string, as: string }>,
+  ...
+}>;
+
+declare export default class StateManager {
+  +_state: PluginPass;
+  +importPaths: Set<string>;
+  +stylexImport: Set<string>;
+  +stylexPropsImport: Set<string>;
+  +stylexCreateImport: Set<string>;
+  +stylexIncludeImport: Set<string>;
+  +stylexFirstThatWorksImport: Set<string>;
+  +stylexKeyframesImport: Set<string>;
+  +stylexDefineVarsImport: Set<string>;
+  +stylexCreateThemeImport: Set<string>;
+  +stylexTypesImport: Set<string>;
+  injectImportInserted: ?t.Identifier;
+  +styleMap: Map<string, CompiledNamespaces>;
+  +styleVars: Map<string, NodePath<>>;
+  +styleVarsToKeep: Set<[string, true | string, true | Array<string>]>;
+  inStyleXCreate: boolean;
+  constructor(state: PluginPass): void;
+  get options(): StyleXStateOptions;
+  get importPathString(): string;
+  get importSources(): $ReadOnlyArray<string>;
+  importAs(source: string): null | string;
+  get canReferenceTheme(): boolean;
+  get metadata(): { [key: string]: any };
+  get runtimeInjection(): ?$ReadOnly<{ from: string, as?: string }>;
+  get isDev(): boolean;
+  get isTest(): boolean;
+  get filename(): string | void;
+  get cssVars(): any;
+  get treeshakeCompensation(): boolean;
+  get fileNameForHashing(): null | string;
+  importPathResolver(importPath: string): ImportPathResolution;
+  addStyle(style: [string, { ltr: string, rtl?: string | null }, number]): void;
+  markComposedNamespace(
+    memberExpression: [string, true | string, true | Array<string>],
+  ): void;
+}

package/lib/visitors/imports.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+import * as t from '@babel/types';
+import type { NodePath } from '@babel/traverse';
+import StateManager from '../utils/state-manager';
+export declare function readImportDeclarations(
+  path: NodePath<t.ImportDeclaration>,
+  state: StateManager,
+): void;
+export declare function readRequires(
+  path: NodePath<t.VariableDeclarator>,
+  state: StateManager,
+): void;

package/lib/visitors/imports.js.flow

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import * as t from '../../flow_modules/@babel/types';
+import type { NodePath } from '../../flow_modules/@babel/traverse';
+import StateManager from '../utils/state-manager';
+
+// Read imports of react and remember the name of the local varsiables for later
+declare export function readImportDeclarations(
+  path: NodePath<t.ImportDeclaration>,
+  state: StateManager,
+): void;
+
+// Read require calls and remember the names of the variables for later
+declare export function readRequires(
+  path: NodePath<t.VariableDeclarator>,
+  state: StateManager,
+): void;

package/lib/visitors/stylex-create/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+import * as t from '@babel/types';
+import type { NodePath } from '@babel/traverse';
+import StateManager from '../../utils/state-manager';
+declare function transformStyleXCreate(
+  path: NodePath<t.CallExpression>,
+  state: StateManager,
+): void;
+export default transformStyleXCreate;

package/lib/visitors/stylex-create/index.js.flow

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import * as t from '../../../flow_modules/@babel/types';
+import type { NodePath } from '../../../flow_modules/@babel/traverse';
+import StateManager from '../../utils/state-manager';
+/// This function looks for `stylex.create` calls and transforms them.
+//. 1. It finds the first argument to `stylex.create` and validates it.
+/// 2. It pre-processes valid-dynamic parts of style object such as custom presets (spreads)
+/// 3. It envalues the style object to get a JS object. This also handles local constants automatically.
+/// 4. It uses the `stylexCreate` from `@stylexjs/shared` to transform the JS
+///    object and to get a list of injected styles.
+/// 5. It converts the resulting Object back into an AST and replaces the call with it.
+/// 6. It also inserts `stylex.inject` calls above the current statement as needed.
+declare export default function transformStyleXCreate(
+  path: NodePath<t.CallExpression>,
+  state: StateManager,
+): void;

package/lib/visitors/stylex-create/parse-stylex-create-arg.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import StateManager from '../../utils/state-manager';
+import { type FunctionConfig } from '../../utils/evaluate-path';
+export declare function evaluateStyleXCreateArg(
+  path: NodePath,
+  traversalState: StateManager,
+  functions: FunctionConfig,
+): Readonly<{
+  confident: boolean;
+  value: any;
+  deopt?: null | NodePath;
+  fns?: {
+    [$$Key$$: string]: [
+      Array<t.Identifier>,
+      { readonly [$$Key$$: string]: t.Expression | t.PatternLike },
+    ];
+  };
+}>;

package/lib/visitors/stylex-create/parse-stylex-create-arg.js.flow

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+/* eslint-disable no-unused-vars */
+import type { NodePath } from '../../../flow_modules/@babel/traverse';
+import * as t from '../../../flow_modules/@babel/types';
+import StateManager from '../../utils/state-manager';
+import { type FunctionConfig } from '../../utils/evaluate-path';
+// This
+declare export function evaluateStyleXCreateArg(
+  path: NodePath<>,
+  traversalState: StateManager,
+  functions: FunctionConfig,
+): $ReadOnly<{
+  confident: boolean,
+  value: any,
+  deopt?: null | NodePath<>,
+  fns?: {
+    [string]: [
+      Array<t.Identifier>,
+      { +[string]: t.Expression | t.PatternLike },
+    ],
+  },
+}>;

package/lib/visitors/stylex-create-theme.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+import * as t from '@babel/types';
+import type { NodePath } from '@babel/traverse';
+import StateManager from '../utils/state-manager';
+declare function transformStyleXCreateTheme(
+  callExpressionPath: NodePath<t.CallExpression>,
+  state: StateManager,
+): void;
+export default transformStyleXCreateTheme;

package/lib/visitors/stylex-create-theme.js.flow

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import * as t from '../../flow_modules/@babel/types';
+import type { NodePath } from '../../flow_modules/@babel/traverse';
+import StateManager from '../utils/state-manager';
+/// This function looks for `stylex.createTheme` calls and transforms them.
+//. 1. It finds the first two arguments to `stylex.createTheme` and validates those.
+/// 2. This handles local constants automatically.
+/// 4. It uses the `stylexCreateTheme` from `@stylexjs/shared` to transform the JS
+///    object and to get a list of injected styles.
+/// 5. It converts the resulting Object back into an AST and replaces the call with it.
+/// 6. It also inserts `stylex.inject` calls above the current statement as needed.
+declare export default function transformStyleXCreateTheme(
+  callExpressionPath: NodePath<t.CallExpression>,
+  state: StateManager,
+): void;

package/lib/visitors/stylex-define-vars.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ *
+ */
+
+import * as t from '@babel/types';
+import type { NodePath } from '@babel/traverse';
+import StateManager from '../utils/state-manager';
+declare function transformStyleXDefineVars(
+  callExpressionPath: NodePath<t.CallExpression>,
+  state: StateManager,
+): void;
+export default transformStyleXDefineVars;