@stylexjs/stylex 0.1.0-beta.7 → 0.2.0-beta.11

package/README.md

@@ -0,0 +1,245 @@
+# @stylexjs/stylex
+
+## Installation
+
+To start playing with StyleX without having to set up any build settings you can install just two packages:
+
+```sh
+npm install --save @stylexjs/stylex
+```
+
+### Compiler
+
+StyleX is designed to extract styles to a static CSS style sheet during an app's build process. StyleX provides a Babel plugin along with plugin integrations for Webpack, Rollup and NextJS.
+
+```sh
+npm install --save-dev @stylexjs/babel-plugin
+```
+
+For more information on working with the compiler, please see the documentation for [`@stylexjs/babel-plugin`](https://www.npmjs.com/package/@stylexjs/babel-plugin).
+
+### Runtime compiler
+
+The runtime compiler should only be used for development and testing purposes.
+
+```sh
+npm install --save-dev @stylexjs/dev-runtime
+```
+
+Import `@stylexjs/dev-runtime` in your JS entry-point to set everything up.
+
+```ts
+import inject from '@stylexjs/dev-runtime';
+
+if (process.env.NODE_ENV !== 'production') {
+  inject({
+    // configuration options
+    classNamePrefix: 'x-',
+    dev: true,
+    test: false,
+  });
+}
+```
+
+For more information on working with the compiler, please see the documentation for [`@stylexjs/dev-runtime`](https://www.npmjs.com/package/@stylexjs/dev-runtime).
+
+## API
+
+### stylex.create()
+
+Styles are defined as a map of CSS rules using `stylex.create()`. In the example below, there are 2 different CSS rules. The names "root" and "highlighted" are arbitrary names given to the rules.
+
+```tsx
+import stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+  root: {
+    width: '100%',
+    color: 'rgb(60,60,60)',
+  },
+  highlighted: {
+    color: 'yellow',
+  }
+});
+```
+
+Pseudo-classes and Media Queries can be nested within style definitions:
+
+```tsx
+import stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+  root: {
+    width: '100%',
+    color: 'rgb(60,60,60)',
+    '@media (min-width: 800px)': {
+      maxWidth: '800px',
+    },
+  },
+  highlighted: {
+    color: 'yellow',
+    ':hover': {
+      opacity: '0.9',
+    }
+  }
+});
+```
+
+The compiler will extract the rules to CSS and replace the rules in the source code with a "compiled style" object.
+
+### stylex.spread()
+
+Applying style rules to specific elements is done using `stylex.spread`. Each argument to this function must be a reference to a compiled style object, or an array of compiled style objects. The function merges styles from left to right.
+
+```tsx
+<div {...stylex.spread(styles.root, styles.highlighted)} />
+```
+
+The `stylex.spread` function returns React props as required to render an element. StyleX styles can still be passed to other components via props, but only the components rendering host platform elements will use `stylex.spread()`. For example:
+
+```tsx
+const styles = stylex.create({
+  internalRoot: {
+    padding: 10
+  },
+  exportedRoot: {
+    position: 'relative'
+  }
+});
+
+function InternalComponent(props) {
+  return <div {...props} {...stylex.spread([ styles.internalRoot, props.style ])} />
+}
+
+export function ExportedComponent(props) {
+  return <InternalComponent style={[ styles.exportedRoot, props.style ]} />
+}
+```
+
+Styles can be conditionally included using standard JavaScript.
+
+```tsx
+<div {...stylex.spread(styles.root, isHighlighted && styles.highlighted)} />
+```
+
+And the local merging of styles can be used to control the relative priority of rules. For example, to allow a component's local styles to take priority over style property values passed in via props.
+
+```tsx
+<div {...stylex.spread(props.style, styles.root)} />
+```
+
+You can even mix compiled styles with inline styles
+
+```tsx
+<div {...stylex.spread(styles.root, { opacity })} />
+```
+
+### stylex.firstThatWorks()
+
+Defining fallback styles is done with `stylex.firstThatWorks()`. This is useful for engines that may not support a specific style property.
+
+```tsx
+import stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+  header: {
+    position: stylex.firstThatWorks('sticky', '-webkit-sticky', 'fixed'),
+  },
+});
+```
+
+This is equivalent to defining CSS as follows:
+
+```css
+.header {
+  position: fixed;
+  position: -webkit-sticky;
+  position: sticky;
+}
+```
+
+## Types
+
+StyleX comes with full support for Static Types.
+
+### `XStyle<>`
+
+The most common type you might need to use is `XStyle<>`. This lets you accept an object of arbitrary StyleX styles.
+
+```tsx
+type Props = {
+  ...
+  style?: XStyle<>,
+};
+
+function MyComponent({style, ...}: Props) {
+  return (
+    <div {...stylex.spread(localStyles.foo, localStyles.bar, style)} />
+  );
+}
+```
+
+### `XStyleWithout<>`
+
+To disallow specific style properties, use the `XStyleWithout<>` type.
+
+```tsx
+type Props = {
+  // ...
+  style?: XStyleWithout<{
+    postion: unknown,
+    display: unknown
+  }>
+};
+```
+
+### `XStyleValue<>`
+
+To accept specific style properties only, use the `XStyle<{...}>` and `XStyleValue` types. For example, to allow only color-related style props:
+
+```tsx
+type Props = {
+  // ...
+  style?: XStyle<{
+    color?: StyleXValue,
+    backgroundColor?: StyleXValue,
+    borderColor?: StyleXValue,
+    borderTopColor?: StyleXValue,
+    borderEndColor?: StyleXValue,
+    borderBottomColor?: StyleXValue,
+    borderStartColor?: StyleXValue,
+  }>,
+};
+```
+
+### `XStyleValueFor<>`
+
+To limit the possible values for style properties, use the `XStyleValueFor<>` type.  Pass in a type argument with a union of literal types that provide the set of possible values that the style property can have. For example, if a component should accept `marginTop` but only accept one of `0`, `4`, or `8` pixels as values.
+
+```tsx
+type Props = {
+  ...
+  style?: XStyle<{
+    marginTop: XStyleValueFor<0 | 4 | 8>
+  }>,
+};
+```
+
+## How StyleX works
+
+StyleX produces atomic styles, which means that each CSS rule contains only a single declaration and uses a unique class name. For example:
+
+```tsx
+import stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+  root: {
+    width: '100%',
+    color: 'red',
+  }
+}
+```
+
+From this code, StyleX will generate 2 classes. One for the `width: '100%'` declaration, and one for the `color: 'red'` declaration. If you use the declaration `width: '100%'` anywhere else in your application, it will *reuse the same CSS class* rather than creating a new one.
+
+One of the benefits of this approach is that the generated CSS file grows *logarithmically* as you add new styled components to your app. As more style declarations are added to components, they are more likely to already be in use elsehwere in the app. As a result of this CSS optimization, the generated CSS style sheet for an app is usually small enough to be contained in a single file and used across routes, avoiding style recalculation and layout thrashing as users navigate through your app.

package/lib/StyleXSheet.js

@@ -15,7 +15,8 @@ Object.defineProperty(exports, "__esModule", {
 exports.styleSheet = exports.StyleXSheet = void 0;
 var _invariant = _interopRequireDefault(require("invariant"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+// import rtlDetect from 'rtl-detect';
+
 const LIGHT_MODE_CLASS_NAME = '__fb-light-mode';
 const DARK_MODE_CLASS_NAME = '__fb-dark-mode';
 /**
@@ -62,6 +63,8 @@ const VARIABLE_MATCH = /var\(--(.*?)\)/g;
  * CSS rules.
  */
 class StyleXSheet {
+  static LIGHT_MODE_CLASS_NAME = LIGHT_MODE_CLASS_NAME;
+  static DARK_MODE_CLASS_NAME = DARK_MODE_CLASS_NAME;
   constructor(opts) {
     this.tag = null;
     this.injected = false;
@@ -265,8 +268,6 @@ class StyleXSheet {
  * Adds an ancestor selector in a media-query-aware way.
  */
 exports.StyleXSheet = StyleXSheet;
-_defineProperty(StyleXSheet, "LIGHT_MODE_CLASS_NAME", LIGHT_MODE_CLASS_NAME);
-_defineProperty(StyleXSheet, "DARK_MODE_CLASS_NAME", DARK_MODE_CLASS_NAME);
 function addAncestorSelector(selector, ancestorSelector) {
   if (!selector.startsWith('@')) {
     return `${ancestorSelector} ${selector}`;

package/lib/native/CSSCustomPropertyValue.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CSSCustomPropertyValue = void 0;
+exports.isCustomPropertyValue = isCustomPropertyValue;
+/**
+ * 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.
+ *
+ * 
+ */
+
+const CUSTOM_PROPERTY_REGEX = /^var\(--(.+)\)$/;
+function camelize(s) {
+  return s.replace(/-./g, x => x.toUpperCase()[1]);
+}
+function isCustomPropertyValue(value) {
+  return typeof value === 'string' && CUSTOM_PROPERTY_REGEX.test(value);
+}
+class CSSCustomPropertyValue {
+  constructor(value) {
+    const found = value.match(CUSTOM_PROPERTY_REGEX);
+    if (found == null) {
+      throw new Error('[stylex]: Unable to find custom property reference in input string');
+    }
+    const [, kebabCasePropName] = found;
+    this.name = camelize(kebabCasePropName);
+  }
+}
+exports.CSSCustomPropertyValue = CSSCustomPropertyValue;

package/lib/native/CSSLengthUnitValue.js

@@ -0,0 +1,78 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CSSLengthUnitValue = void 0;
+/**
+ * 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.
+ *
+ * 
+ */
+
+const LENGTH_REGEX = /^([0-9]*[.]?[0-9]+)(em|px|rem|vh|vmax|vmin|vw)$/;
+// TODO: this only works on simple values
+class CSSLengthUnitValue {
+  static parse(inp) {
+    const match = inp.match(LENGTH_REGEX);
+    if (match == null) {
+      return null;
+    }
+    const [, value, unit] = match;
+    const parsedValue = parseFloat(value);
+    // $FlowFixMe
+    return new CSSLengthUnitValue(parsedValue, unit);
+  }
+  constructor(value, unit) {
+    this.value = value;
+    this.unit = unit;
+  }
+  resolvePixelValue(viewportWidth, viewportHeight, fontScale, inheritedFontSize) {
+    const unit = this.unit;
+    const value = this.value;
+    const valuePercent = value / 100;
+    switch (unit) {
+      case 'em':
+        {
+          if (inheritedFontSize == null) {
+            return fontScale * 16 * value;
+          } else {
+            return inheritedFontSize * value;
+          }
+        }
+      case 'px':
+        {
+          return value;
+        }
+      case 'rem':
+        {
+          return fontScale * 16 * value;
+        }
+      case 'vh':
+        {
+          return viewportHeight * valuePercent;
+        }
+      case 'vmin':
+        {
+          return Math.min(viewportWidth, viewportHeight) * valuePercent;
+        }
+      case 'vmax':
+        {
+          return Math.max(viewportWidth, viewportHeight) * valuePercent;
+        }
+      case 'vw':
+        {
+          return viewportWidth * valuePercent;
+        }
+      default:
+        {
+          console.error(`[stylex]: Unsupported unit of "${unit}"`);
+          return 0;
+        }
+    }
+  }
+}
+exports.CSSLengthUnitValue = CSSLengthUnitValue;

package/lib/native/CSSMediaQuery.js

@@ -0,0 +1,69 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CSSMediaQuery = void 0;
+var _cssMediaquery = _interopRequireDefault(require("css-mediaquery"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/**
+ * 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.
+ *
+ * 
+ */
+
+const MQ_PREFIX = '@media';
+class CSSMediaQuery {
+  static isMediaQueryString(inp) {
+    return inp.startsWith(MQ_PREFIX);
+  }
+  static resolveMediaQueries(styleObj, matchObj) {
+    const mediaQueries = [];
+    const result = {};
+
+    // collect all the media queries
+    for (const [key, value] of Object.entries(styleObj)) {
+      if (value instanceof CSSMediaQuery) {
+        mediaQueries.push(value);
+      } else {
+        result[key] = value;
+      }
+    }
+
+    // check the media queries to see if any apply and if they do,
+    // merge their styles into the result
+    if (mediaQueries.length > 0) {
+      for (const mqInst of mediaQueries) {
+        const unresolvedMatchedStyle = mqInst.resolve(matchObj);
+        const resolvedMatchedStyle = this.resolveMediaQueries(unresolvedMatchedStyle, matchObj);
+        for (const propName in resolvedMatchedStyle) {
+          result[propName] = resolvedMatchedStyle[propName];
+        }
+      }
+    }
+    return result;
+  }
+  constructor(query, matchedStyle) {
+    this.query = query.replace(MQ_PREFIX, '');
+    this.matchedStyle = matchedStyle;
+  }
+  resolve(matchObject) {
+    const {
+      width,
+      height,
+      direction
+    } = matchObject;
+    const matches = _cssMediaquery.default.match(this.query, {
+      width,
+      height,
+      orientation: width > height ? 'landscape' : 'portrait',
+      'aspect-ratio': width / height,
+      direction: direction
+    });
+    return matches ? this.matchedStyle : {};
+  }
+}
+exports.CSSMediaQuery = CSSMediaQuery;