Update documentation for all @compiled/ packages (#1689)

* Update Atomic CSS page to use object styles, not tagged template strings * Update @compiled/react documentation * Update fonts * Update remainder of @compiled/* documentation * Change Installation page to recommend Parcel * Update title of 'Media queries and other at rules' to more easily fit the sidebar * Address PR feedback
atlassian-labs · Jul 17, 2024 · 18024be · 18024be
1 parent c807221
commit 18024be
Show file tree

Hide file tree

Showing 16 changed files with 458 additions and 305 deletions.
diff --git a/website/packages/docs/src/index.html b/website/packages/docs/src/index.html
@@ -1,11 +1,7 @@
 <html lang="en">
   <head>
     <meta name="viewport" content="width=device-width" />
-    <link rel="preconnect" href="https://fonts.gstatic.com/" crossorigin="" />
     <title>Docs | Compiled CSS-in-JS</title>
-    <link
-      href="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@400&family=Roboto:wght@300;500&display=swap"
-      rel="stylesheet" />
     <script async src="https://cdn.splitbee.io/sb.js"></script>
   </head>
   <body></body>

diff --git a/website/packages/docs/src/pages/atomic-css.mdx b/website/packages/docs/src/pages/atomic-css.mdx
@@ -104,29 +104,29 @@ but they share the same atomic rule,
 what happens?
 
 ```jsx
-<div
-  css={css`
-    :hover {
-      color: blue;
-    }
-    :active {
-      color: red;
-    }
-  `}
-/>
+const styles = css({
+  '&:hover': {
+    color: 'blue',
+  },
+  '&:active': {
+    color: 'red',
+  },
+});
+
+<div css={styles} />;
 ```
 
 ```jsx
-<div
-  css={css`
-    :active {
-      color: red;
-    }
-    :hover {
-      color: blue;
-    }
-  `}
-/>
+const styles = css({
+  '&:active': {
+    color: 'red',
+  },
+  '&:hover': {
+    color: 'blue',
+  },
+});
+
+<div css={styles} />;
 ```
 
 The simple answer is it depends which component renders first!

diff --git a/website/packages/docs/src/pages/installation.mdx b/website/packages/docs/src/pages/installation.mdx
@@ -16,8 +16,28 @@ Then configure your bundler of choice or use [Babel](https://babeljs.io) directl
 
 ## Installation methods
 
+### (Recommended) Parcel
+
+Install the [Parcel v2](https://v2.parceljs.org) configuration.
+
+```bash
+npm install @compiled/parcel-config --save-dev
+```
+
+Add the compiled preset to your [Parcel config](https://parceljs.org/features/plugins/).
+
+```json
+{
+  "extends": ["@parcel/config-default", "@compiled/parcel-config"]
+}
+```
+
+See the [configuration package docs](/pkg-parcel-config) for configuration options.
+
 ### Webpack
 
+> We recommend Parcel, as this will be more performant, and it aligns with the Atlassian recommended tech stack.
+
 Install the [Webpack](https://webpack.js.org/) loader.
 
 ```bash
@@ -52,24 +72,6 @@ Read the [Webpack CSS extraction](/css-extraction-webpack) for a step-by-step gu
 
 See the [loader package docs](/pkg-webpack-loader) for configuration options.
 
-### Parcel
-
-Install the [Parcel v2](https://v2.parceljs.org) configuration.
-
-```bash
-npm install @compiled/parcel-config --save-dev
-```
-
-Add the compiled preset to your [Parcel config](https://parceljs.org/features/plugins/).
-
-```json
-{
-  "extends": ["@parcel/config-default", "@compiled/parcel-config"]
-}
-```
-
-See the [configuration package docs](/pkg-parcel-config) for configuration options.
-
 ### Babel
 
 > **Local development** <br />

diff --git a/website/packages/docs/src/pages/media-queries-and-other-at-rules.mdx b/website/packages/docs/src/pages/media-queries-and-other-at-rules.mdx
@@ -1,9 +1,9 @@
 ---
 section: 50-Guides
-name: Media queries and other at-rules
+name: Media queries, other at-rules
 ---
 
-# Media queries and other at-rules
+# Media queries, other at-rules
 
 Media queries and other at-rules (e.g. `@layer` and `@supports`) are sorted based on a simplified version of the mobile-first sorting algorithm used by the [`sort-css-media-queries`](https://github.com/olehdutchenko/sort-css-media-queries/) library.
 

diff --git a/website/packages/docs/src/pages/pkg-babel-plugin-strip-runtime.mdx b/website/packages/docs/src/pages/pkg-babel-plugin-strip-runtime.mdx
@@ -29,29 +29,26 @@ Configure in your Babel config.
 }
 ```
 
-### onFoundStyleRules: (rules: string[]) => void
-
-Will callback at the end of a file pass with all found style rules.
-
-### compiledRequireExclude: boolean
+#### compiledRequireExclude
 
 When set will prevent additional require (one import per rule) in the bundle and add style rules to meta data.
 This could be used when enabling style sheet extraction in a different configuration for SSR.
 
-Defaults to `false`.
-
-### extractStylesToDirectory
+- Type: `boolean`
+- Default: `false`
 
-extractStylesToDirectory?: \{ source: string; dest: string \};
+#### extractStylesToDirectory
 
 When set, extracts styles to an external CSS file. This is beneficial for building platform components that are to be published on NPM.
 
-Example of useage:
+Example of usage:
 
 Given the below folder structure:
 
+```
 - src
   - index.jsx
+```
 
 ```js
 // src/index.jsx
@@ -72,9 +69,11 @@ Set the source folder and output folder relative to the root project path.
 
 It extracts the CSS sheet to a seperate file.
 
+```
 - dist
   - index.js
   - index.compiled.css
+```
 
 ```js
 // src/index.jsx
@@ -91,10 +90,18 @@ const Component = () =>
   );
 ```
 
-### sortAtRules: boolean
+- Type: `{ source: string; dest: string }`
+- Default: `undefined`
+
+#### styleSheetPath
+
+An internal option used by other Compiled plugins. Don't use this!
+
+#### sortAtRules
 
 Whether to sort at-rules, including media queries.
 
 See [here](/media-queries-and-other-at-rules) for more information.
 
-Defaults to `true`.
+- Type: `boolean`
+- Default: `true`
diff --git a/website/packages/docs/src/pages/pkg-babel-plugin.mdx b/website/packages/docs/src/pages/pkg-babel-plugin.mdx
@@ -41,41 +41,118 @@ Configure in your Babel config.
 }
 ```
 
-### importReact: boolean
+If you choose to configure Compiled through Webpack or Parcel (recommended), you can pass options for `@compiled/babel-plugin` through those configurations. See [`@compiled/webpack-loader`](/pkg-webpack-loader) and [`@compiled/parcel-config`](/pkg-parcel-config) for more information.
 
-Will import React into the module if it is not found.
-When using `@babel/preset-react` with the [automatic runtime](https://babeljs.io/docs/en/babel-preset-react#react-automatic-runtime) this is not needed and can be set to `false`.
+`@compiled/babel-plugin` supports the following options:
+
+- `addComponentName`
+- `cache`
+- `classNameCompressionMap`
+- `extensions`
+- `importReact`
+- `importSources`
+- `increaseSpecificity`
+- `nonce`
+- `onIncludedFiles`
+- `optimizeCss`
+- `parserBabelPlugins`
+- `processXcss`
+- `resolver`
+- `sortAtRules`
+
+#### addComponentName
 
-Defaults to `true`.
+Add the component name as a class name to the DOM in non-production environments, if `styled` is used.
 
-### cache: boolean | 'single-pass'
+- Type: `boolean`
+- Default: `false`
+
+#### cache
 
 Will cache the result of statically evaluated imports.
 
 - `true` will cache for the duration of the node process
 - `'single-pass'` will cache for a single pass of a file
 - `false` turns caching off
 
-Defaults to `true`.
+* Type: `boolean | 'single-pass'`
+* Default: `true`
+
+#### classNameCompressionMap
 
-### optimizeCss: boolean
+Don't use this!
 
-Will run additional cssnano plugins to normalize CSS during build.
+An internal and experimental option used to compress class names.
 
-Defaults to `true`.
+Note that in `@compiled/webpack-loader` and `@compiled/parcel-config`, `classNameCompressionMap` requires `extract` to be true as well.
 
-### onIncludedFiles: (files: string[]) => void
+#### extensions
 
-Will callback at the end of a file pass with all imported files that were statically evaluated into the file.
+Extensions that we should consider code. We use these to identify if a file should be parsed.
 
-### addComponentName: boolean
+- Type: `string[]`
+- Default: `['.js', '.jsx', '.ts', '.tsx']`
 
-Add the component name as class name to DOM in non-production environment if styled is used.
+#### importReact
+
+Will import React into the module if it is not found.
+When using `@babel/preset-react` with the [automatic runtime](https://babeljs.io/docs/en/babel-preset-react#react-automatic-runtime) this is not needed and can be set to `false`.
 
-Default to `false`
+- Type: `boolean`
+- Default: `true`
 
-### importSources: string[]
+#### importSources
 
 Additional libraries that should be parsed as though they were `@compiled/react` imports.
 
 Specifying this is important if you are using Compiled APIs through another package using the `createStrictAPI` function.
+
+- Type: `string[]`
+- Default: `undefined`
+
+#### increaseSpecificity
+
+An experimental option that increases the specificity of all generated Compiled classes. Don't use this!
+
+#### nonce
+
+[Security nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) that will be applied to inline style elements if defined.
+
+- Type: `string`
+- Default: `false`
+
+#### onIncludedFiles
+
+An internal option. Callback fired at the end of the file pass when files have been included in the transformation.
+
+- Type: `(files: string[]) => void`
+- Default: `undefined`
+
+#### optimizeCss
+
+Will run additional `cssnano` plugins to normalize CSS during the build.
+
+- Type: `boolean`
+- Default: `true`
+
+#### parserBabelPlugins
+
+Babel parser plugins to be used when parsing the source code. Define these to enable extra babel parsers (for example, typescript).
+See the [babel docs](https://babeljs.io/docs/en/plugins/#syntax-plugins) for more context.
+
+Usually, you will set this option through [`@compiled/parcel-config`] or [`@compiled/webpack-loader`](/webpack-loader) -- see there for examples.
+
+#### processXcss
+
+An option we are only using internally. Don't use!
+
+#### resolver
+
+A custom resolver used to statically evaluate import declarations, specified as either an object or module path. If this is an object, it should contain a `resolveSync` function with the following type signature: `(context: string, request: string) => string`.
+
+- Type: `string | Resolver`
+- Default: `undefined`
+
+#### sortAtRules
+
+Unused.
diff --git a/website/packages/docs/src/pages/pkg-eslint-plugin.mdx b/website/packages/docs/src/pages/pkg-eslint-plugin.mdx
@@ -32,4 +32,4 @@ export default [
 
 ## Rules
 
-See [here](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin) for a list of rules in `@compiled/eslint-plugin`.
+See [here](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin) for a non-exhaustive list of rules in `@compiled/eslint-plugin`.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -32,4 +32,4 @@ export default [

		## Rules

		See [here](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin) for a list of rules in `@compiled/eslint-plugin`.
		See [here](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin) for a non-exhaustive list of rules in `@compiled/eslint-plugin`.