feat: source editor that supports multiple files

.flowconfig

@@ -1,5 +1,5 @@
 [version]
-0.245.2
+0.249.0
 
 [ignore]
 .*/build/.*

.github/CONTRIBUTING.md

@@ -37,24 +37,24 @@ To run flow:
 npm run flow
 ```
 
-To run all the unit tests:
+## Compile and build
+
+To compile the source code:
 
 ```
-npm run test
+npm run build
 ```
 
-…in watch mode:
+To run all the unit tests (will build automatically):
 
 ```
-npm run test -- --watch
+npm run test
 ```
 
-## Compile and build
-
-To compile the source code:
+…in watch mode (will build only once):
 
 ```
-npm run build
+npm run test -- --watch
 ```
 
 ## Documentation
@@ -92,3 +92,30 @@ After you have submitted your pull request, we'll try to get back to you as soon
 as possible. We may suggest some changes or improvements.
 
 Thank you for contributing!
+
+## Typical Editor setup
+
+### VS Code
+
+If you're using Visual Studio Code, we recommend the following setup for the
+best experience.
+
+#### Extensions
+
+We recommend you have the following extensions installed:
+
+- [Flow Language Support](https://marketplace.visualstudio.com/items?itemName=flowtype.flow-for-vscode)
+- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
+- [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+
+#### Turn off Typescript within JS files
+
+Additionally, since StyleX is authored with the
+[Flow typesystem](https://flow.org), it is helpful to turn off Typescript
+type-checking within Javascript files:
+
+```json
+{
+  "javascript.validate.enable": false
+}
+```

apps/cli-example/.stylex.json5

@@ -4,7 +4,7 @@
   cssBundleName: 'stylex_bundle.css',
   babelPresets: [
     ['@babel/preset-typescript', { allExtensions: true, isTSX: true }],
-    '@babel/preset-react',
+    // '@babel/preset-react',
   ],
   modules_EXPERIMENTAL: [
     ['@stylexjs/open-props', { ignore: ['src', '__tests__'] }],

apps/cli-example/package.json

@@ -1,21 +1,21 @@
 {
   "name": "stylex-cli-example",
-  "version": "0.8.0",
+  "version": "0.9.3",
   "private": true,
   "scripts": {
     "transform": "stylex --config .stylex.json5"
   },
   "dependencies": {
-    "@stylexjs/open-props": "0.8.0",
+    "@stylexjs/open-props": "0.9.3",
     "react": "^18",
     "react-dom": "^18"
   },
   "devDependencies": {
-    "@babel/preset-react": "^7.24.1",
-    "@babel/preset-typescript": "^7.24.1",
-    "@stylexjs/cli": "0.8.0",
-    "@types/react": "^18",
-    "@types/react-dom": "^18",
+    "@babel/preset-react": "^7.25.7",
+    "@babel/preset-typescript": "^7.25.7",
+    "@stylexjs/cli": "0.9.3",
+    "@types/react": "^18.3.11",
+    "@types/react-dom": "^18.3.1",
     "typescript": "^5"
   }
 }

apps/cli-example/source/app/CardThemes.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ *
+ * @format
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import { tokens } from './CardTokens.stylex';
+
+export const minorOffset = stylex.createTheme(tokens, {
+  arrowTransform: 'translateX(5px)',
+});
+
+export const majorOffset = stylex.createTheme(tokens, {
+  arrowTransform: 'translateX(10px)',
+});
+
+export const reset = stylex.createTheme(tokens, {});

apps/docs/.eslintrc.js

@@ -13,6 +13,7 @@ module.exports = {
     // The Eslint rule still needs work, but you can
     // enable it to test things out.
     '@stylexjs/valid-styles': 'error',
+    // '@stylexjs/no-unused': 'warn',
     // 'ft-flow/space-after-type-colon': 0,
     // 'ft-flow/no-types-missing-file-annotation': 0,
     // 'ft-flow/generic-spacing': 0,

apps/docs/blog/2024-11-01-Release-v0.9.3.mdx

@@ -0,0 +1,182 @@
+---
+# 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.
+slug: v0.9.3
+title: Release 0.9.3
+authors: 
+  - nmn
+tags: 
+  - release
+---
+
+StyleX v0.9.3 is now available with some big improvements and bug-fixes.
+
+## Improvements to Theming APIs
+
+There are some big improvements to the predictability and reliability of our
+theming APIs — `stylex.defineVars` and `stylex.createTheme`.
+
+### Breaking Change: Themes are now exclusive
+
+When you create a `VarGroup` with `stylex.defineVars`, you are able to theme
+any subset of the variables within using the `stylex.createTheme` API. These
+themes can then be applied like any other StyleX styles using `stylex.props`
+(or `stylex.attrs`). If you try to apply multiple themes for the same `VarGroup`,
+on the same element, *the last applied theme wins*, just as you might expect.
+
+However, previously, if you instead applied one theme on a parent element,
+and another theme on a child element, the themes would end up being merged.
+
+```tsx
+// tokens.stylex.ts
+import * as stylex from '@stylexjs/stylex';
+
+export const varGroup = stylex.defineVars({
+  primary: 'black',
+  secondary: 'grey',
+});
+```
+
+```tsx
+import * as stylex from '@stylexjs/stylex';
+import {varGroup} from './tokens.stylex.ts';
+
+const red = stylex.createTheme(varGroup, {
+  primary: 'red',
+});
+
+const blue = stylex.createTheme(varGroup, {
+  secondary: 'blue',
+});
+
+const styles = stylex.create({
+  primary: {color: varGroup.primary},
+  secondary: {color: varGroup.secondary},
+});
+
+function App() {
+  return (
+    <div {...stylex.props(red)}>
+      <div {...stylex.props(blue)}>
+        <span {...stylex.props(styles.primary)}>Hello </span>
+        <span {...stylex.props(styles.secondary)}>World!</span>
+      </div>
+    </div>
+  );
+}
+```
+
+Previously this would have resulted in the text "Hello World!" being styled
+with a red primary color and a blue secondary color. Now, the text will be
+styled with a black primary color and a blue secondary color.
+
+You can think of themes conceptually as *re-applying* the default values for any
+variables that are not explicitly overridden by the theme. This change simplifies
+the mental model for how themes work, and has the added benefit of making it
+easy to create "reset" themes:
+
+```tsx
+const reset = stylex.createTheme(varGroup, {});
+```
+
+:::tip
+You can define this "reset" theme multiple times within your app and they
+will all be de-duplicated by the compiler. We encourage you to "repeat yourself"!
+:::
+
+
+### `rootDir` is now optional!
+
+Previously, when configuring the StyleX Babel plugin, you had to explicitly
+specify a `rootDir` value. Internally, this path was used to generate a canonical
+file path for every `.stylex.js` file in your project.
+
+However, this was not only cumbersome, but it also resulted in errors when importing
+`VarGroup`s from `node_modules`. Different package managers deal with packages differently,
+and this can be particularly consequential for mono-repos.
+
+Now, the `rootDir` option is optional, and StyleX will use the nearest `package.json` file
+to determine the canonical path, automatically. This should make theming APIs work more
+reliably.
+
+:::note
+When determining the canonical path, StyleX will use the `name` field from the nearest
+`package.json` file and the relative path to the `.stylex.js` file. We intentionally
+ignore the `version` number.
+
+This means that your project happens to contain multiple versions of the same package,
+StyleX will only generate a single set of variables for them. This will usually be
+the desired behavior, but you may see some unexpected results if the variables within
+the two versions are different.
+
+We will be making further improvements to minimize any such edge-cases.
+:::
+
+### More reliable ESM resolution
+
+The StyleX Babel plugin now uses the `esm-resolve` package to resolve ESM imports.
+This should fix most situations where the compiler would fail to resolve `VarGroup`
+imports in result in the compilation of `stylex.create` to fail.
+
+Thanks [hipstersmoothie](https://github.com/hipstersmoothie)!
+
+## Dynamic style improvements
+
+Dynamic Styles within StyleX have been improved to be more reliable and efficient.
+Previously, if the dynamic value of a style resolved to `null` at runtime, StyleX
+would represent that with the `revert` keyword in CSS. This did not always work as
+expected, ran into certain browser bugs and resulted in styles that were unnecessarily
+bloated.
+
+In v0.9.3, `null` values for Dynamic styles work exactly the same as using `null`
+as a static value within `stylex.create`. This means any previously applied value
+for the given property will be removed and no className will be applied for that
+property.
+
+
+## `@stylexjs/dev-runtime` overhaul
+
+The `@stylexjs/dev-runtime` package is a development-only package that lets you use
+a *much slower* version of StyleX that runs entirely at runtime. Previously, it worked
+by patching the main `@stylexjs/stylex` package at runtime. However, this did not always
+work reliably. 
+
+**Breaking Change**: The `@stylexjs/dev-runtime` package now *returns* the StyleX API.
+
+```tsx
+import makeStyleX from '@stylexjs/dev-runtime';
+
+const stylex = makeStyleX({
+  // configuration options
+  classNamePrefix: 'x',
+  dev: true,
+  test: false,
+});
+
+const styles = stylex.create({
+  color: 'red',
+});
+```
+
+:::warning
+The `@stylexjs/dev-runtime` only exists as a convenience for development purposes.
+It does not completely match the behavior of the StyleX compiler and will always
+lack certain features.
+
+**DO NOT** use it in production.
+:::
+
+## Improved handling of nested pseudo-elements and pseudo-classes
+
+Fixed a bug where using Pseudo Classes (such as `:hover`) within Pseudo Elements (such as `::before`)
+(or vice-versa) would sometimes result in surprising behavior. StyleX now handles such cases, with
+an arbitrary level of nesting, correctly.
+
+## Miscellaneous
+
+- Added support for additional Pseudo Elements and Pseudo Classes to our ESLint rule and type definitions.
+  - Thanks [aspizu](https://github.com/aspizu) and [nikeee](https://github.com/nikeee)!
+- Slightly better compiler error messages.
+  - Thanks [EvanBacon](https://github.com/EvanBacon)!