Add native support for css.defineConsts

Author: necolas

apps/website/docs/api/02-css/03-defineConsts.md

@@ -1,21 +1,41 @@
----
-draft: true
----
-
 # css.defineConsts
 
-<p className="text-xl">How to define constants.</p>
+<p className="text-xl">How to define constants for use in styles and themes.</p>
 
 :::warning
 
-`css.defineConsts()` is currently only supported on web.
-
-:::
+Constants must be defined as named exports in files with a `*.stylex.js` (or `*.stylex.ts`) extension. This limitation is currently imposed due to constraints on how styles are compiled on web.
 
 ## Overview
 
-...
+This API creates style variables that can be imported and used within `css.create()` and `css.createTheme()` calls anywhere within a codebase. These values are inlined at build time and do not generate variables.
+
+```js title="constants.stylex.js"
+import { css } from 'react-strict-dom';
+
+export const breakpoints = css.defineConsts({
+  small: '@media (max-width: 600px)',
+  medium: '@media (min-width: 601px) and (max-width: 1024px)',
+  large: '@media (min-width: 1025px)',
+});
+```
 
 ## API
 
-...
+### Named variables
+
+The `defineConsts` function accepts an object of named constants. These constants can be referenced elsewhere by their key name.
+
+```js title="component.js"
+import { breakpoints } from './constants.stylex.js';
+
+const styles = css.create({
+  box: {
+    padding: {
+      default: '10px',,
+      [breakpoints.medium]: '15px',
+      [breakpoints.large]: '20px',
+    },
+  },
+});
+```

apps/website/docs/api/index.md

@@ -15,7 +15,7 @@ sidebar_position: -1
 * [**css**](/api/css/) - An overview of working with styles.
 * [css.create](/api/css/create) - How to create styles.
 * [css.createTheme](/api/css/createTheme) - How to create themes.
-<!-- * [css.defineConsts](/api/css/defineConsts) - How to define constants. -->
+* [css.defineConsts](/api/css/defineConsts) - How to define constants.
 * [css.defineVars](/api/css/defineVars) - How to define variables.
 * [css.firstThatWorks](/api/css/firstThatWorks) - How to declare fallback values.
 <!-- * [css.keyframes](/api/css/keyframes) - How to declare animation keyframes. -->

apps/website/docs/learn/05-theming-components.md

@@ -8,13 +8,13 @@ slug: /learn/themes
 
 :::info[Requirements]
 
-Variables must be defined in a file that matches the following file extension pattern: `.stylex.{js,jsx,mjs,ts,tsx}`. Only CSS variables can be defined in these files. And every `css.defineVars` call must be a named export.
+Variables and constants must be defined in a file that matches the following file extension pattern: `.stylex.{js,jsx,mjs,ts,tsx}`. Only CSS variables can be defined in these files. Every `css.defineConsts` and `css.defineVars` call must be a named export.
 
 :::
 
 ## Defining variables
 
-CSS variables are defined with a call to `css.defineVars`. This defines global variables which can then be imported as constants for use in any style rules. These variables and their values are essentially a "default theme".
+CSS variables are defined with a call to `css.defineVars`. This defines global variables which can then be imported for use in any style rules. These variables and their values are essentially a "default theme". If you don't need to override these values in themes, use `css.defineConsts` instead.
 
 ```js title="tokens.stylex.js"
 import { css } from 'react-strict-dom';
@@ -59,9 +59,9 @@ export const colors = css.defineVars({
 });
 ```
 
-## Using variables in styles
+## Using variables or constants in styles
 
-Once variables have been defined, they can be imported and used directly in style rules created with `css.create`.
+Once variables or constants have been defined, they can be imported and used directly in style rules created with `css.create`.
 
 ```js title="Component.js"
 import { css } from 'react-strict-dom';

packages/react-strict-dom/src/native/stylex/index.js

@@ -454,13 +454,10 @@ export const createTheme = (
   return result;
 };
 
-export const defineConsts = (tokens: {
+export const defineConsts = (constants: {
   [string]: string
 }): { [string]: string } => {
-  if (__DEV__) {
-    errorMsg('css.defineConsts() is not supported.');
-  }
-  return tokens;
+  return Object.freeze(constants);
 };
 
 type Tokens = { [string]: string };

packages/react-strict-dom/tests/__snapshots__/css-test.native.js.snap-native

@@ -18,6 +18,13 @@ exports[`properties: custom property css.createTheme: theme 1`] = `
 }
 `;
 
+exports[`properties: custom property css.defineConsts: constants 1`] = `
+{
+  "blueColor": "blue",
+  "redColor": "red",
+}
+`;
+
 exports[`properties: custom property css.defineVars: css.__customProperties 1`] = `
 {
   "rootColor__id__1": "red",

packages/react-strict-dom/tests/css-test.native.js

@@ -1165,6 +1165,17 @@ describe('properties: custom property', () => {
     ).toEqual('red');
   });
 
+  test('css.defineConsts', () => {
+    const constants = css.defineConsts({
+      redColor: 'red',
+      blueColor: 'blue'
+    });
+    expect(constants).toMatchSnapshot('constants');
+    expect(() => {
+      constants.redColor = 'black';
+    }).toThrow();
+  });
+
   test('css.defineVars', () => {
     const options = {};
     const tokens = css.defineVars({