Add "learn" section to website and update homepage

apps/examples/postcss.config.js

@@ -8,10 +8,7 @@
 module.exports = {
   plugins: {
     'postcss-react-strict-dom': {
-      include: [
-        require.resolve('react-strict-dom'),
-        'src/**/*.{js,jsx,mjs,ts,tsx}'
-      ]
+      include: ['src/**/*.{js,jsx,mjs,ts,tsx}']
     },
     autoprefixer: {}
   }

apps/examples/src/app/index.js

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// Required to apply extracted on Expo Web
+// Required for CSS to work on Expo Web.
 import './stylex.css';
 // Required for Fast Refresh to work on Expo Web
 import '@expo/metro-runtime';

apps/examples/src/components/App.js

@@ -22,8 +22,7 @@ const egStyles = css.create({
   h1: { padding: 10, backgroundColor: '#eee' },
   content: { padding: 10 },
   div: {
-    paddingBottom: 50,
-    paddingTop: 50,
+    paddingBlock: 50,
     backgroundColor: 'white'
   }
 });

apps/website/docs/api/01-babel/01-preset.md

@@ -5,19 +5,13 @@ slug: /api/babel-preset
 
 # Babel preset
 
-<p className="text-xl">React Strict DOM includes a Babel preset to generate and optimize web app builds.</p>
-
-:::info[Web only]
-
-Configuring Babel to use this preset is required for web builds only. It should not be used for native builds.
-
-:::
+<p className="text-xl">React Strict DOM includes a Babel preset to optimize builds. This preset is required on web.</p>
 
 ## Overview
 
 The preset ensures that production builds have **no runtime performance overhead on web** relative to using [React DOM](https://react.dev/) with an advanced atomic CSS solution like [StyleX](https://stylexjs.com). The preset is required to extract styles to static CSS and optimize element rendering.
 
-Import the preset from the `'react-strict-dom/babel-preset'` package subpath. It must be used with an options object.
+Import the preset from the `react-strict-dom/babel-preset` package subpath. It must be used with an options object.
 
 
 ```js title="babel.config.dom.js"
@@ -26,7 +20,7 @@ import reactStrictBabelPreset from 'react-strict-dom/babel-preset';
 export default function babelConfig() {
   return {
     presets: [
-      [reactStrictBabelPreset, { rootDir: process.cwd() }]
+      [reactStrictBabelPreset, { debug: true }]
     ]
   }
 };
@@ -36,19 +30,13 @@ export default function babelConfig() {
 
 ### Preset options
 
-* `debug`: boolean (optional). Default is `false`. If set to `true` there will be debug information included in the generated code. For example, rendered elements include a `data-element-src` attribute containing sourceMap information about the filename and line-number responsible for rendering the element.
-* `dev`: boolean (optional). Default is `false`. If set to `true` there will be development logs included, and styles will not be extracted to static CSS (but injected at runtime.)
-* `rootDir`: boolean (required). The absolute path to the root directory of your project.
-
-### Extract styles on web
-
-:::warning[Under construction]
-
-React Strict DOM does not provide pre-made bundler integrations at this time. Please refer to the [StyleX Rollup Plugin](https://github.com/facebook/stylex/blob/main/packages/rollup-plugin/src/index.js) for an example of how to incorporate style extraction in a bundler plugin.
+* `debug: boolean` (optional). Default is `false`. If set to `true` there will be debug information included in the generated code. For example, rendered elements include a `data-element-src` attribute containing sourceMap information about the filename and line-number responsible for rendering the element.
+* `dev: boolean` (optional). Default is `false`. If set to `true` there will be development logs included, and styles will not be extracted to static CSS (but injected at runtime.)
+* `platform: 'web' | 'native'` (optional). Default is `web`. The target platform; this must be set to `native` for React Native builds.
 
-:::
+### Preset methods
 
-* `generateStyles`: Array of collected style rules. To generate a static CSS file, the styles must first be collected before being turned into a CSS string by this function, and written to a file by the build system. An illustrative example follows:
+* `generateStyles(rules)`: **Web only**. Accetps an array of collected style rules. To generate a static CSS file, the styles must first be collected before being turned into a CSS string by this function. Next, the result should be written to a file by the build system. An illustrative example follows:
 
 ```js
 import reactStrictBabelPreset from 'react-strict-dom/babel-preset';

apps/website/docs/api/02-css/01-create.md

@@ -1,10 +1,10 @@
 # css.create
 
-<p className="text-xl">How to create static and dynamic styles in React.</p>
+<p className="text-xl">How to create static and dynamic styles in React Strict DOM.</p>
 
 :::warning
 
-The constraints on which properties and values are supported (e.g., various short-form properties are disallowed) are not yet enforced by the style compiler or static types on web. This is a work in progress.
+On web the style compiler and static types do not yet enforce constraints on the properties and values that can be used (e.g., various short-form properties are disallowed). This is a work in progress that depends on improvements to StyleX.
 
 :::
 

apps/website/docs/api/02-css/02-createTheme.md

@@ -1,10 +1,12 @@
 # css.createTheme
 
-<p className="text-xl">How to create style themes from variables in React.</p>
+<p className="text-xl">How to create style themes from variables in React Strict DOM.</p>
 
 ## Overview
 
-This API creates themes that override the default values of style variables created with `defineVars()`. These themes can then be applied to specific element sub-trees. It returns an opaque style object that can be passed to the `style` prop of `html.*` elements. These theme objects can also be combined into an array style.
+This API creates themes that override the default values of style variables created with `defineVars()`. It returns an opaque style object that can be passed to the `style` prop of any `html.*` element. The theme will then apply to the entire sub-tree. Theme objects can be combined using an array style.
+
+Example:
 
 ```jsx
 import { css } from 'react-strict-dom';

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

@@ -4,7 +4,7 @@
 
 :::warning
 
-Variables must be defined as named exports in a `.stylex.js` (or `.stylex.ts`) file. This limitation is currently imposed due to constraints on how styles are compiled on web.
+Variables 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.
 
 :::
 

apps/website/docs/api/03-html/01-common.md

@@ -4,28 +4,28 @@ title: Common (e.g. <html.div>)
 
 # Common components (e.g., \<html.div>)
 
-<p className="text-xl">The majority of HTML components support the following common props and events.</p>
+<p className="text-xl">HTML components support the following common props and events.</p>
 
 ## Overview
 
-All supported HTML components are available on the `html` export (which can be aliased). For the full list of supported HTML components, please refer to the [HTML compatibility table](/api/html/#compatibility). Component props are strictly typed and will provide errors if invalid values are used.
+HTML components are available on the `html` export (which can be aliased). Component props are strictly typed and will provide errors if invalid values are used.
+
+For the full list of supported HTML components, please refer to the [HTML compatibility table](/api/html/#compatibility).
+
+Example:
 
 ```jsx
 import { html } from 'react-strict-dom';
 
 const Foo = () => {
   return (
     <html.main>
-      <html.section>
-        <html.article>
-          <html.h1>Title</html.h1>
-          <html.div>
-            <html.p>
-              Paragraph of <html.span>text</html.span> element
-            </html.p>
-          </html.div>
-        </html.article>
-      </html.section>
+      <html.h1>Title</html.h1>
+      <html.div>
+        <html.p>
+          Paragraph of <html.span>text</html.span> element
+        </html.p>
+      </html.div>
     </html.main>
   )
 }
@@ -55,7 +55,7 @@ Please refer to the [related React DOM docs](https://react.dev/reference/react-d
 
 ### Common
 
-* `aria-*` - Excludes all abstract roles that should not be used by authors.
+* `aria-*` - WAI-ARIA 1.2 non-deprecated properties.
 * `autoCapitalize`
 * `autoFocus`
 * `children`
@@ -69,7 +69,7 @@ Please refer to the [related React DOM docs](https://react.dev/reference/react-d
 * `inert`
 * `inputMode`
 * `lang`
-* `role` - The synonym `presentation` is not supported, use `none`.
+* `role` - The synonym `presentation` is not supported, use `none`. Excludes all abstract roles that should not be used by authors.
 * `ref`
 * `spellCheck`
 * `style` - Accepts a style or array of styles created using `css.create()` and `css.createTheme()`. Falsey values are ignored. Order matters, with later declarations overriding earlier ones.

apps/website/docs/api/04-other/02-compat.md

@@ -14,6 +14,8 @@ This is an experimental and unstable API intended to aid with incremental adopti
 
 A component that translates React Strict DOM props into React Native props, which can then be passed to a custom React Native element. A type annotation must be provided for `nativeProps`, which should match the props type of the React Native component being rendered.
 
+Example:
+
 ```jsx
 import { compat } from 'react-strict-dom';
 import { Text } from 'react-native';
@@ -33,6 +35,11 @@ export component Foo(...props: FooProps) {
 }
 ```
 
-The `children` prop must be a function, which receives `nativeProps` as the only argument.
+#### Props
 
-The `as` prop accepts values of `image`, `input`, `text`, `textarea`, and `view`.
+* `...reactStrictDOMProps`
+  * Any props accepted by `html.*` elements.
+* `children: (nativeProps) => React.Node`
+  * Must be a function, which receives the computed `nativeProps` as the only argument and returns a React Native element.
+* `as: 'image' | 'input' | 'text' | 'textarea' | 'view'`
+  * Tells the component how to translate the props for native. For example, if rendering to a multiline `TextInput`, use `textarea`. Defaults to `view`.

apps/website/docs/learn/01-installation.md

@@ -0,0 +1,37 @@
+---
+slug: /learn/installation
+---
+
+# Installation
+
+<p className="text-xl">Getting started with React Strict DOM. The following guide will explain which packages to install.</p>
+
+## How to install
+
+To install React Strict DOM, run the following command in a React project:
+
+```
+npm install react-strict-dom
+```
+
+### Web
+
+For web support, please make sure the following peer dependencies are installed:
+
+```
+npm install react react-dom
+```
+
+Extracting styles to static CSS requires the following PostCSS plugin:
+
+```
+npm install --save-dev postcss-react-strict-dom
+```
+
+### Native
+
+For native support, please make sure the following peer dependencies are installed (note that using the new React Native architecture is required):
+
+```
+npm install react react-native
+```

apps/website/docs/learn/02-environment-setup.md

@@ -0,0 +1,128 @@
+---
+slug: /learn/setup
+---
+
+# Environment setup
+
+<p className="text-xl">Learn how to configure the environment needed to use React Strict DOM.</p>
+
+## Expo framework
+
+[Expo](https://expo.dev/) is a production-grade, cross-platform React framework that is the recommended solution for creating apps with React Strict DOM. The instructions in the rest of this guide are tailored to Expo, but can be adapted by readers to work with other frameworks.
+
+Follow the Expo instructions on how to [create a new project](https://docs.expo.dev/get-started/create-a-project/). React Strict DOM requires use of the New React Native Architecture. Then follow the steps in the [Installation](/learn/installation) guide to install React Strict DOM.
+
+A working example of an Expo setup with React Strict DOM can be found in this [examples app](https://github.com/facebook/react-strict-dom/tree/main/apps/examples).
+
+## Babel configuration
+
+Create or modify the `babel.config.js` file as follows. This is used to optimize builds and enables static extraction of CSS for web. Learn how to configure the [babel-preset](/api/babel-preset/) in the API docs.
+
+```js title="babel.config.js"
+const reactStrictPreset = require('react-strict-dom/babel-preset');
+
+function getPlatform(caller) {
+  // This information is populated by Expo
+  return caller && caller.platform;
+}
+
+function getIsDev(caller) {
+  // This information is populated by Expo
+  if (caller?.isDev != null) return caller.isDev;
+  // https://babeljs.io/docs/options#envname
+  return (
+    process.env.BABEL_ENV === 'development' ||
+    process.env.NODE_ENV === 'development'
+  );
+}
+
+module.exports = function (api) {
+  const platform = api.caller(getPlatform);
+  const dev = api.caller(getIsDev);
+
+  return {
+    plugins: [],
+    presets: [
+      // Expo's babel preset
+      'babel-preset-expo',
+      // React Strict DOM's babel preset
+      [reactStrictPreset, {
+        debug: dev,
+        dev,
+        platform
+      }]
+    ]
+  };
+};
+```
+
+## PostCSS configuration
+
+[PostCSS](https://postcss.org/) is a tool for generating CSS. It's enabled by default in Expo and it's the recommended way to extract React Strict DOM styles to static CSS for web builds. Once the [postcss-react-strict-dom](https://github.com/javascripter/postcss-react-strict-dom) plugin is installed, it can be used to extract styles. Create a `postcss.config.js` file as follows.
+
+```js title="postcss.config.js"
+module.exports = {
+  plugins: {
+    'postcss-react-strict-dom': {
+      include: [
+        // Include source files to watch for style changes
+        'src/**/*.{js,jsx,mjs,ts,tsx}'
+        // List any installed node_modules that include UI built with React Strict DOM
+        'node_modules/<package-name>/*.js'
+      ]
+    },
+    autoprefixer: {}
+  }
+};
+```
+
+## Metro configuration
+
+[Metro](https://reactnative.dev/docs/metro) is the bundler used by Expo and React Native. It can bundle apps for native and web targets. Create or modify the `metro.config.js` file as follows to enable support for [package exports in React Native](https://reactnative.dev/blog/2023/06/21/package-exports-support). This step is not necessary for other packagers.
+
+```js title="metro.config.js"
+// Learn more https://docs.expo.dev/guides/monorepos
+const { getDefaultConfig } = require('expo/metro-config');
+
+// Find the project and workspace directories
+const projectRoot = __dirname;
+
+const config = getDefaultConfig(projectRoot);
+// 1. Enable Metro support for symlinks and package exports
+config.resolver.unstable_enablePackageExports = true;
+// 2. Force Metro to resolve (sub)dependencies only from the `nodeModulesPaths`
+config.resolver.disableHierarchicalLookup = true;
+
+module.exports = config;
+```
+
+## App files
+
+Your app needs to include a CSS file that contains a `@stylex` directive. This acts as a placeholder that is replaced by the generated CSS during builds.
+
+```css title="stylex.css"
+/* This directive is used by the react-strict-dom postcss plugin. */
+/* It is automatically replaced with generated CSS during builds. */
+@stylex;
+```
+
+Next, import the CSS file in the entry file of your app.
+
+
+```js title="index.js"
+// Required for CSS to work on Expo Web.
+import './stylex.css';
+// Required for Fast Refresh to work on Expo Web
+import '@expo/metro-runtime';
+
+import { registerRootComponent } from 'expo';
+import App from './App';
+
+registerRootComponent(App);
+```
+
+## Platform-specific files
+
+Expo supports [platform-specific extensions](https://docs.expo.dev/router/advanced/platform-specific-modules/#platform-specific-extensions) by default. This allows you to create platform-specific implementations of components, hooks, etc.
+
+Other frameworks will require bundler configuration when building for each platform, so as to resolve files based on their file extensions. For example, web bundles should package `*.web.js` file extensions but not `*.native.js` files. These specific file name suffixes are recommended conventions already used by the React Native ecosystem (see the Expo docs above.)