From 18024beb75499ab0c1d7fb72bd0f7d5ada4368ee Mon Sep 17 00:00:00 2001 From: Grant Wong <2908767+dddlr@users.noreply.github.com> Date: Wed, 17 Jul 2024 14:06:13 +1000 Subject: [PATCH] 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 --- website/packages/docs/src/index.html | 4 - .../packages/docs/src/pages/atomic-css.mdx | 40 ++-- .../packages/docs/src/pages/installation.mdx | 38 ++-- .../media-queries-and-other-at-rules.mdx | 4 +- .../pages/pkg-babel-plugin-strip-runtime.mdx | 31 +-- .../docs/src/pages/pkg-babel-plugin.mdx | 107 ++++++++-- .../docs/src/pages/pkg-eslint-plugin.mdx | 2 +- .../docs/src/pages/pkg-parcel-config.mdx | 176 ++++++++++------ website/packages/docs/src/pages/pkg-react.mdx | 133 +++++-------- .../docs/src/pages/pkg-webpack-loader.mdx | 188 ++++++++++++------ website/packages/landing/src/index.html | 4 - website/packages/ui/global.css | 2 +- website/packages/ui/src/components/anchor.tsx | 5 +- .../packages/ui/src/components/heading.tsx | 22 +- .../ui/src/components/mdx-components.tsx | 2 +- website/packages/ui/src/components/text.tsx | 5 +- 16 files changed, 458 insertions(+), 305 deletions(-) diff --git a/website/packages/docs/src/index.html b/website/packages/docs/src/index.html index 8c5edd4b9..480069612 100644 --- a/website/packages/docs/src/index.html +++ b/website/packages/docs/src/index.html @@ -1,11 +1,7 @@ - Docs | Compiled CSS-in-JS - diff --git a/website/packages/docs/src/pages/atomic-css.mdx b/website/packages/docs/src/pages/atomic-css.mdx index d2e563fd3..be661e88e 100644 --- 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 -
+const styles = css({ + '&:hover': { + color: 'blue', + }, + '&:active': { + color: 'red', + }, +}); + +
; ``` ```jsx -
+const styles = css({ + '&:active': { + color: 'red', + }, + '&:hover': { + color: 'blue', + }, +}); + +
; ``` 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 index d5e412e66..04c5cc245 100644 --- 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**
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 index fbc6e62cd..8f91eea6e 100644 --- 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 index d04ecc48d..0e566f11e 100644 --- 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 index 5111349de..53a9ada28 100644 --- a/website/packages/docs/src/pages/pkg-babel-plugin.mdx +++ b/website/packages/docs/src/pages/pkg-babel-plugin.mdx @@ -41,14 +41,33 @@ 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. @@ -56,26 +75,84 @@ Will cache the result of statically evaluated imports. - `'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 index 06d98cc13..d50cab14f 100644 --- 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`. diff --git a/website/packages/docs/src/pages/pkg-parcel-config.mdx b/website/packages/docs/src/pages/pkg-parcel-config.mdx index 6b6ff8afc..15bba2eef 100644 --- a/website/packages/docs/src/pages/pkg-parcel-config.mdx +++ b/website/packages/docs/src/pages/pkg-parcel-config.mdx @@ -35,91 +35,93 @@ Configure using any of the following at the root of your project. } ``` -### importReact: boolean +Through the Compiled configuration file (e.g. `.compiledcssrc`), you can set options for any of our Parcel plugins (`@compiled/parcel-transformer` and `@compiled/parcel-optimizer`), as well as for the underlying `@compiled/babel-plugin`. This page will focus on the options that are unique to `@compiled/parcel-transformer` and `@compiled/parcel-optimizer`. -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`. +### Options used by Compiled Parcel plugins -Defaults to `true`. +`@compiled/parcel-transformer` accepts the following options: -### transformerBabelPlugins: PluginItem[] +- `classNameCompressionMapFilePath` +- `extensions` +- `extract` +- `extractFromDistributedCode` +- `inlineCss` +- `parserBabelPlugins` +- `resolve` +- `sortAtRules` +- `ssr` +- `styleSheetPath` +- `transformerBabelPlugins` -Babel transformer plugins to be applied to transformed files before the Compiled evaluation. +#### classNameCompressionMapFilePath -Use this if you have some sort of babel plugin that should run before Compiled, -likely because you have some sort of non-standard syntax in your code. -See the [babel docs](https://babeljs.io/docs/en/plugins/#transform-plugins) for more context. +Don't use this! -Example usage: +This is an alternative to `classNameCompressionMap`, where instead of providing the compression map itself, you can provide a file path to the compression map. If both are provided, `classNameCompressionMap` will take precedence over `classNameCompressionMapFilePath`. -```json -// .compiledcssrc -{ - "transformerBabelPlugins": [ - [ - "@babel/plugin-proposal-decorators", - { - "legacy": true - } - ] - ] -} -``` +Note that this is enabled only if `extract` is set to `true`. -Defaults to none. +#### extensions -### parserBabelPlugins: ParserPlugin[] +Extensions that we should consider to be code. We use these to identify if a file should be parsed. -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. +If set, the value of `extensions` will be used in two places: -Example usage: +1. If `resolver` is not set, then `extensions` will be passed to the default resolver, `enhanced-resolver`. +2. This is also passed to `@compiled/babel-plugin` under the hood. -```json -// .compiledcssrc -{ - "parserBabelPlugins": ["typescript"] -} -``` +- Type: `string[]` +- Default: none, but note that `enhanced-resolver` and `@compiled/babel-plugin` have their own different defaults when the `extensions` option is not set. -Defaults to none. +#### extract -### extract: boolean +Enables `@compiled/babel-plugin-strip-runtime`, i.e. the stylesheet extraction feature. When enabled, Compiled react components will be removed and the css will be extracted into a single CSS stylesheet. -Enables the stylesheet extraction feature. When enabled, Compiled react components will be removed and the css will be extracted into a single CSS stylesheet. +The stylesheet extraction feature is disabled on local development due to a [known issue](https://github.com/atlassian-labs/compiled/issues/1306). -The stylesheet extraction feature is disabled on local development due to [known issue](https://github.com/atlassian-labs/compiled/issues/1306). +- Type: `boolean` +- Default: `false` -Defaults to `false`. +#### extractFromDistributedCode -### ssr: boolean +Unused. -To be used in conjunction with `extract: true` when having a different configuration for SSR. -When set will prevent additional require (one import per rule) in the bundle during style sheet extraction. +#### extractStylesToDirectory -Defaults to `false`. +When set, extracts styles to an external CSS file. Requires `extract` to be set to `true` as well. This is passed directly to `@compiled/babel-plugin-strip-runtime` -- see the [`@compiled/babel-plugin-strip-runtime` documentation](/pkg-babel-plugin-strip-runtime#extractstylestodirectory) for more information. -### nonce: string +- Type: `{ source: string; dest: string }` +- Default: `undefined` -[Security nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) that will be applied to inline style elements if defined. +#### inlineCss -Defaults to `false`. +Indicates whether CSS content is inlined in HTML or served as a external .css file when the stylesheet extraction is enabled. -### extensions: string[] +- Type: `boolean` +- Default: `false` -Extensions that we should consider code. We use these to identify if a file should be parsed. +#### 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. -Defaults to `['.js', '.jsx', '.ts', '.tsx']`. +Example usage: -### inlineCss: boolean +```json +// .compiledcssrc +{ + "parserBabelPlugins": ["typescript"] +} +``` -Indicates whether CSS content is inlined in HTML or served as a external .css file when the styleshset extraction is enabled. +This is also passed to `@compiled/babel-plugin` under the hood. -Defaults to `false`. +- Type: `ParserPlugin[]` +- Default: `undefined` -### resolve: ResolveOptions +#### \[Deprecated\] resolve -Override the default `resolve` used by @compiled/babel-plugin, which is used to statically evaluate import declarations. +If `resolver` is not provided, `resolve` specifies options that should be passed to the default resolver (`enhanced-resolver`). The resolver is used to statically evaluate import declarations. Example usage: @@ -134,28 +136,72 @@ Example usage: See [enhanced-resolver docs](https://github.com/webpack/enhanced-resolve#resolver-options) for more options. -Defaults to none. +- Type: `ResolveOptions` +- Default: `undefined` -### sortAtRules: boolean +#### 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` + +### \[Obsolete\] ssr + +> This is hardcoded to `true` now. + +To be used in conjunction with `extract: true` when having a different configuration for SSR. + +When set to true, `ssr` will prevent additional require (one import per rule) in the bundle during style sheet extraction. + +This is equivalent to setting `compiledRequireExclude` in `@compiled/babel-plugin-strip-runtime`. + +- Type: `boolean` + +#### \[Obsolete\] styleSheetPath + +Unused. In the past, this was an internal option passed to `@compiled/babel-plugin-strip-runtime`. Don't use this! + +### transformerBabelPlugins + +Babel transformer plugins to be applied to transformed files before the Compiled evaluation. + +Use this if you have some sort of babel plugin that should run before Compiled, +likely because you have some sort of non-standard syntax in your code. +See the [babel docs](https://babeljs.io/docs/en/plugins/#transform-plugins) for more context. -### addComponentName: boolean +Example usage: -Add the component name as class name to DOM in non-production environment if styled is used. +```json +// .compiledcssrc +{ + "transformerBabelPlugins": [ + [ + "@babel/plugin-proposal-decorators", + { + "legacy": true + } + ] + ] +} +``` -Default to `false` +- Type: `PluginItem[]` +- Default: `undefined` -### extractStylesToDirectory?: \{ source: string; dest: string \}; +### Options used by `@compiled/babel-plugin` -When set, extracts styles to an external CSS file. Read [babel-plugin-strip-runtime](/pkg-babel-plugin-strip-runtime#extractstylestodirectory) for more information. +The following options are passed directly to `@compiled/babel-plugin`: -### importSources: string[] +- `addComponentName` +- `classNameCompressionMap` +- `importReact` +- `importSources` +- `optimizeCss` +- `resolver` -Additional libraries that should be parsed as though they were `@compiled/react` imports. This is passed directly to `@compiled/babel-plugin`. +Passing other `@compiled/babel-plugin` options not listed above will also work, but have not been tested. -Specifying this is important if you are using Compiled APIs through another package using the `createStrictAPI` function. +To avoid repetition, we have not included the descriptions here. Please refer to the [`@compiled/babel-plugin` documentation](/pkg-babel-plugin) for more information. diff --git a/website/packages/docs/src/pages/pkg-react.mdx b/website/packages/docs/src/pages/pkg-react.mdx index ed41a816c..7731224b9 100644 --- a/website/packages/docs/src/pages/pkg-react.mdx +++ b/website/packages/docs/src/pages/pkg-react.mdx @@ -11,6 +11,7 @@ import { Lozenge, HorizontalStack } from '@compiled/website-ui'; React 16 React 17 + React 18 The primary entrypoint package for Compiled that provides familiar APIs to style your app. @@ -21,38 +22,62 @@ npm install @compiled/react ## CSS prop -Use [CSS prop](/api-css-prop) to style a JSX element. +Use the [CSS prop](/api-css-prop) in conjunction with our `css` function call to style a JSX element. ```jsx /** @jsxImportSource @compiled/react */ import { css } from '@compiled/react'; -
; - -
; - -
; +const baseStyles = css({ + fontSize: '12px', +}); + +const primaryStyles = css({ + color: 'blue', +}); + +const Component2 =
; + +const Component3 =
; ``` -## Styled +## CSS Map + +Use [`cssMap`](/api-cssmap) to define a map consisting of named CSS rules that can be statically typed and useable with other Compiled APIs. + +```jsx +import { cssMap } from '@compiled/react'; + +const borderStyleMap = cssMap({ + none: { borderStyle: 'none' }, + solid: { borderStyle: 'solid' }, +}); + +const Component = ({ appearance, children }) => ( +
{children}
+); +``` + +## Keyframes + +Use [`keyframes`](/api-keyframes) to define keyframes to be used in a [CSS animation](https://developer.mozilla.org/en-US/docs/Web/CSS/animation). + +```jsx +import { keyframes } from '@compiled/react'; + +const fadeOut = keyframes({ + from: { + opacity: 1, + }, + to: { + opacity: 0, + }, +}); +``` + +## Deprecated APIs + +### \[Deprecated\] Styled Use [styled](/api-styled) to create a component that styles a JSX element which comes with built-in behavior such as `ref` and `as` prop support. @@ -84,7 +109,7 @@ styled.div( ); ``` -## Class names +### \[Deprecated\] ClassNames Use [ClassNames](/api-class-names) for when styles are not necessarily used on a JSX element. @@ -125,59 +150,3 @@ import { css, ClassNames } from '@compiled/react'; } ; ``` - -## CSS - -Use [`css`](/api-css-prop) to define styles that can be statically typed and useable with other Compiled APIs. - -```jsx -import { css } from '@compiled/react'; - -const blackText = css({ - color: 'black', -}); - -const blackText = css` - color: black; -`; -``` - -## CSS Map - -Use [`css`](/api-cssmap) to define a map consisting of named CSS rules that can be statically typed and useable with other Compiled APIs. - -```jsx -import { cssMap } from '@compiled/react'; - -const borderStyleMap = cssMap({ - none: { borderStyle: 'none' }, - solid: { borderStyle: 'solid' }, -}); -``` - -## Keyframes - -Use [`keyframes`](/api-keyframes) to define keyframes to be used in a [CSS animation](https://developer.mozilla.org/en-US/docs/Web/CSS/animation). - -```jsx -import { keyframes } from '@compiled/react'; - -const fadeOut = keyframes({ - from: { - opacity: 1, - }, - to: { - opacity: 0, - }, -}); - -const fadeOut = keyframes` - from { - opacity: 1; - } - - to { - opacity: 0; - } -`; -``` diff --git a/website/packages/docs/src/pages/pkg-webpack-loader.mdx b/website/packages/docs/src/pages/pkg-webpack-loader.mdx index 1ee8fc14b..0816179ee 100644 --- a/website/packages/docs/src/pages/pkg-webpack-loader.mdx +++ b/website/packages/docs/src/pages/pkg-webpack-loader.mdx @@ -47,67 +47,58 @@ module.exports = { }; ``` -### importReact: boolean +### Options used by `@compiled/webpack-loader` -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/webpack-loader` accepts the following options: -Defaults to `true`. +- `bake` +- `extensions` +- `extract` +- `extractStylesToDirectory` +- `parserBabelPlugins` +- `resolve` +- `ssr` +- `transformerBabelPlugins` -### importSources: string[] +#### bake -Additional libraries that should be parsed as though they were `@compiled/react` imports. This is passed directly to `@compiled/babel-plugin`. +Turns on `@compiled/babel-plugin`. -Specifying this is important if you are using Compiled APIs through another package using the `createStrictAPI` function. +- Type: `boolean` +- Default: `true` -### extract: boolean +#### extensions -Enables extracting all styles to an atomic style sheet, -to be used in conjunction with `CompiledExtractPlugin`. -Read the [Webpack CSS extraction](/css-extraction-webpack) guide for help. +Extensions that we should consider to be code. We use these to identify if a file should be parsed. -Defaults to `false`. +If set, the value of `extensions` will be used in two places: -### bake: boolean +1. If `resolver` is not set, then `extensions` will be passed to the default resolver, `enhanced-resolver`. +2. This is also passed to `@compiled/babel-plugin` under the hood. -Enables baking your styles into JavaScript. +- Type: `string[]` +- Default: none, but note that `enhanced-resolver` and `@compiled/babel-plugin` have their own different defaults when the `extensions` option is not set. -Defaults to `true`. +#### extract -### optimizeCss: boolean +Enables extracting all styles to an atomic style sheet. This enables `@compiled/babel-plugin-strip-runtime` under the hood. -Will run additional cssnano plugins to normalize CSS during build. +You should use this in conjunction with `CompiledExtractPlugin`. Read the [Webpack CSS extraction](/css-extraction-webpack) guide for help. -Defaults to `true`. +- Type: `boolean` +- Default: `false` -### addComponentName: boolean +#### extractStylesToDirectory -Add the component name as class name to DOM in non-production environment if styled is used. - -Default to `false` - -### sortAtRules: boolean - -Whether to sort at-rules, including media queries. - -See [here](/media-queries-and-other-at-rules) for more information. - -Defaults to `true`. - -### ssr: boolean - -To be used in conjunction with `extract: true` when having a different configuration for SSR. -When set will prevent additional require (one import per rule) in the bundle during style sheet extraction. - -Defaults to `false`. +When set, extracts styles to an external CSS file. Read [babel-plugin-strip-runtime](/pkg-babel-plugin-strip-runtime) for more information. -### transformerBabelPlugins: PluginItem[] +- Type: `{ source: string; dest: string }` +- Default: `undefined` -Babel transformer plugins to be applied to transformed files before the Compiled evaluation. +#### parserBabelPlugins -Use this if you have some sort of babel plugin that should run before Compiled, -likely because you have some sort of non-standard syntax in your code. -See the [babel docs](https://babeljs.io/docs/en/plugins/#transform-plugins) for more context. +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. Example usage: @@ -124,14 +115,7 @@ module.exports = { { loader: '@compiled/webpack-loader', options: { - transformerBabelPlugins: [ - [ - '@babel/plugin-proposal-decorators', - { - legacy: true, - }, - ], - ], + parserBabelPlugins: ['typescript'], }, }, ], @@ -141,12 +125,51 @@ module.exports = { }; ``` -Defaults to none. +This is also passed to `@compiled/babel-plugin` under the hood. -### parserBabelPlugins: ParserPlugin[] +- Type: `ParserPlugin[]` +- Default: `['typescript', 'jsx']` -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. +#### \[Deprecated\] resolve + +If `resolver` is not provided, `resolve` specifies options that should be passed to the default resolver (`enhanced-resolver`). The resolver is used to statically evaluate import declarations. + +This has been superseded by `resolver`; you should use that instead! + +Example usage: + +```json +options: { + // ... + "resolve": { + "mainFields": ["module:es2019", "browser", "module", "main"] + } +} +``` + +See [enhanced-resolver docs](https://github.com/webpack/enhanced-resolve#resolver-options) for more options. + +- Type: `ResolveOptions` +- Default: `undefined` + +#### ssr + +To be used in conjunction with `extract: true` when having a different configuration for SSR. + +When set to true, `ssr` will prevent additional require (one import per rule) in the bundle during style sheet extraction. + +This is equivalent to setting `compiledRequireExclude` in `@compiled/babel-plugin-strip-runtime`. + +- Type: `boolean` +- Default: `false` + +#### transformerBabelPlugins + +Babel transformer plugins to be applied to transformed files before the Compiled evaluation. + +Use this if you have some sort of babel plugin that should run before Compiled, +likely because you have some sort of non-standard syntax in your code. +See the [babel docs](https://babeljs.io/docs/en/plugins/#transform-plugins) for more context. Example usage: @@ -163,7 +186,14 @@ module.exports = { { loader: '@compiled/webpack-loader', options: { - parserBabelPlugins: ['typescript'], + transformerBabelPlugins: [ + [ + '@babel/plugin-proposal-decorators', + { + legacy: true, + }, + ], + ], }, }, ], @@ -173,9 +203,22 @@ module.exports = { }; ``` -### extractStylesToDirectory?: \{ source: string; dest: string \}; +- Type: `PluginItem[]` +- Default: `[]` -When set, extracts styles to an external CSS file. Read [babel-plugin-strip-runtime](/pkg-babel-plugin-strip-runtime) for more information. +### Options passed to `@compiled/babel-plugin` + +`@compiled/webpack-loader` also accepts the following options. These are not used in the loader itself, but instead they are passed directly to the underlying `@compiled/babel-plugin`. + +- `addComponentName` +- `classNameCompressionMap` +- `importReact` +- `importSources` +- `nonce` +- `optimizeCss` +- `resolver` + +To avoid repetition, we have not included the descriptions here. Please refer to the [`@compiled/babel-plugin` documentation](/pkg-babel-plugin) for more information. ## CompiledExtractPlugin @@ -190,7 +233,9 @@ module.exports = { }; ``` -### nodeModulesTest: Condition +### Options + +#### nodeModulesTest As a performance optimization you can test paths to include by [passing a webpack condition](https://webpack.js.org/configuration/module/#condition) to the plugin. @@ -200,7 +245,10 @@ new CompiledExtractPlugin({ }); ``` -### nodeModulesInclude: Condition +- Type: `Condition` +- Default: `undefined` + +#### nodeModulesInclude As a performance optimization you can include paths by [passing a webpack condition](https://webpack.js.org/configuration/module/#condition) to the plugin. @@ -210,7 +258,10 @@ new CompiledExtractPlugin({ }); ``` -### nodeModulesExclude: Condition +- Type: `Condition` +- Default: `undefined` + +#### nodeModulesExclude As a performance optimization you can exclude paths by [passing a webpack condition](https://webpack.js.org/configuration/module/#condition) to the plugin. @@ -220,7 +271,10 @@ new CompiledExtractPlugin({ }); ``` -### cacheGroupExclude: boolean +- Type: `Condition` +- Default: `undefined` + +#### cacheGroupExclude: boolean To be used in conjunction with `extract: true` when having a different configuration for SSR. This will prevent the additional `cacheGroup` chunk to be created during style sheet extraction; compiled-css files should be only generated in the client-side. @@ -230,3 +284,15 @@ new CompiledExtractPlugin({ cacheGroupExclude: true, }); ``` + +- Type: `boolean` +- Default: `undefined` + +#### sortAtRules + +Whether to sort at-rules, including media queries. + +See [here](/media-queries-and-other-at-rules) for more information. + +- Type: `boolean` +- Default: `true` diff --git a/website/packages/landing/src/index.html b/website/packages/landing/src/index.html index 289ceecee..e082353f6 100644 --- a/website/packages/landing/src/index.html +++ b/website/packages/landing/src/index.html @@ -1,11 +1,7 @@ - Compiled | Compile time CSS-in-JS for React - diff --git a/website/packages/ui/global.css b/website/packages/ui/global.css index f749eb4a3..fc913bbc4 100644 --- a/website/packages/ui/global.css +++ b/website/packages/ui/global.css @@ -1,7 +1,7 @@ body { margin: 0; padding: 0; - font-size: 2.5rem; + font-size: 2rem; line-height: 1.4; min-height: 100vh; position: relative; diff --git a/website/packages/ui/src/components/anchor.tsx b/website/packages/ui/src/components/anchor.tsx index a2845458b..eec6b040f 100644 --- a/website/packages/ui/src/components/anchor.tsx +++ b/website/packages/ui/src/components/anchor.tsx @@ -40,10 +40,11 @@ export const Anchor = ({ children }: { children: string | string[] }): JSX.Eleme .toLowerCase(); useEffect(() => { - context.listen(ref.current); + const currentRef = ref.current; + context.listen(currentRef); return () => { - context.unlisten(ref.current); + context.unlisten(currentRef); }; }, [context, id]); diff --git a/website/packages/ui/src/components/heading.tsx b/website/packages/ui/src/components/heading.tsx index 8740af43c..e458c23cf 100644 --- a/website/packages/ui/src/components/heading.tsx +++ b/website/packages/ui/src/components/heading.tsx @@ -25,10 +25,10 @@ export const Heading = ({ children, style, ...props }: HeadingProps): JSX.Elemen className={props.className} style={style} css={` - font-family: 'Noto Sans', sans-serif; + font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, + 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; font-weight: 500; margin: 0; - opacity: 0.9; word-break: break-word; ::before { @@ -72,8 +72,7 @@ export const Heading = ({ children, style, ...props }: HeadingProps): JSX.Elemen } [data-look='h200']& { - font-size: 36px; - line-height: 44px; + font-size: 5rem; padding: 0.05px 0; ::before { @@ -86,8 +85,7 @@ export const Heading = ({ children, style, ...props }: HeadingProps): JSX.Elemen } [data-look='h300']& { - font-size: 24px; - line-height: 32px; + font-size: 3.5rem; padding: 0.05px 0; letter-spacing: 0.3px; @@ -101,8 +99,7 @@ export const Heading = ({ children, style, ...props }: HeadingProps): JSX.Elemen } [data-look='h600']& { - font-size: 20px; - line-height: 24px; + font-size: 2.75rem; padding: 0.05px 0; letter-spacing: 0.3px; @@ -116,11 +113,9 @@ export const Heading = ({ children, style, ...props }: HeadingProps): JSX.Elemen } [data-look='h400']& { - font-size: 14px; - line-height: 20px; + font-size: 2.5rem; padding: 0.05px 0; - text-transform: uppercase; - letter-spacing: 1px; + letter-spacing: 0.75px; color: #7a869a; ::before { @@ -133,8 +128,7 @@ export const Heading = ({ children, style, ...props }: HeadingProps): JSX.Elemen } [data-look='h500']& { - font-size: 12px; - line-height: 18px; + font-size: 1.5rem; padding: 0.05px 0; text-transform: uppercase; letter-spacing: 1px; diff --git a/website/packages/ui/src/components/mdx-components.tsx b/website/packages/ui/src/components/mdx-components.tsx index 17f730687..70d35dd01 100644 --- a/website/packages/ui/src/components/mdx-components.tsx +++ b/website/packages/ui/src/components/mdx-components.tsx @@ -39,7 +39,7 @@ const Code = styled.code` `; const P = styled.p` - margin: 4rem 0; + margin: 3rem 0; `; export const mdxComponents: MDXProviderComponentsProp = { diff --git a/website/packages/ui/src/components/text.tsx b/website/packages/ui/src/components/text.tsx index f878ee195..311a4e55b 100644 --- a/website/packages/ui/src/components/text.tsx +++ b/website/packages/ui/src/components/text.tsx @@ -27,7 +27,7 @@ export function Text({ weight === 'regular' && `font-weight: 300;`, weight === 'bold' && `font-weight: 500;`, ` - font-family: 'Roboto', sans-serif; + font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif; padding-top: 0.05px; padding-bottom: 0.05px; @@ -44,8 +44,7 @@ export function Text({ } &[data-variant='reading'] { - font-size: 20px; - line-height: 30px; + line-height: 1.6em; ::before { margin-top: -0.3834em;