-
Notifications
You must be signed in to change notification settings - Fork 843
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: move docusaurus website to packages directory (#7815)
- Loading branch information
Showing
163 changed files
with
12,258 additions
and
48 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Dependencies | ||
/node_modules | ||
|
||
# Production | ||
/build | ||
|
||
# Generated files | ||
.docusaurus | ||
.cache-loader | ||
|
||
# Misc | ||
.DS_Store | ||
.env.local | ||
.env.development.local | ||
.env.test.local | ||
.env.production.local | ||
|
||
npm-debug.log* | ||
yarn-debug.log* | ||
yarn-error.log* |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
# Website | ||
|
||
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. | ||
|
||
### Installation | ||
|
||
``` | ||
$ yarn | ||
``` | ||
|
||
### Local Development | ||
|
||
``` | ||
$ yarn start | ||
``` | ||
|
||
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. | ||
|
||
### Build | ||
|
||
``` | ||
$ yarn build | ||
``` | ||
|
||
This command generates static content into the `build` directory and can be served using any static contents hosting service. | ||
|
||
### Deployment | ||
|
||
Using SSH: | ||
|
||
``` | ||
$ USE_SSH=true yarn deploy | ||
``` | ||
|
||
Not using SSH: | ||
|
||
``` | ||
$ GIT_USER=<Your GitHub username> yarn deploy | ||
``` | ||
|
||
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
/* | ||
* Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one | ||
* or more contributor license agreements. Licensed under the Elastic License | ||
* 2.0 and the Server Side Public License, v 1; you may not use this file except | ||
* in compliance with, at your election, the Elastic License 2.0 or the Server | ||
* Side Public License, v 1. | ||
*/ | ||
|
||
module.exports = { | ||
presets: [require.resolve('@docusaurus/core/lib/babel/preset')], | ||
}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
label: Guidelines | ||
collapsed: false |
309 changes: 309 additions & 0 deletions
309
packages/website/docs/01_guidelines/getting_started.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,309 @@ | ||
--- | ||
title: Getting started | ||
slug: getting-started | ||
--- | ||
|
||
import Tabs from '@theme/Tabs'; | ||
import TabItem from '@theme/TabItem'; | ||
|
||
## Installation | ||
|
||
EUI is published through [NPM](https://www.npmjs.com/package/@elastic/eui) as a dependency. To install EUI into | ||
an existing project, use the `yarn` CLI (`npm` is not supported). | ||
|
||
<Tabs> | ||
<TabItem value="yarn" label="Yarn" default> | ||
```shell | ||
yarn add @elastic/eui | ||
``` | ||
</TabItem> | ||
<TabItem value="pnpm"> | ||
```shell | ||
pnpm add @elastic/eui | ||
``` | ||
</TabItem> | ||
</Tabs> | ||
|
||
Note that EUI has [several `peerDependencies` requirements](https://github.com/elastic/eui/blob/main/package.json) | ||
that will also need to be installed when starting with a blank project. | ||
|
||
<Tabs> | ||
<TabItem value="yarn" label="Yarn" default> | ||
```shell | ||
yarn add @elastic/eui @elastic/datemath @emotion/react @emotion/css moment prop-types | ||
``` | ||
</TabItem> | ||
<TabItem value="pnpm"> | ||
```shell | ||
pnpm add @elastic/eui @elastic/datemath @emotion/react @emotion/css moment prop-types | ||
``` | ||
</TabItem> | ||
</Tabs> | ||
|
||
You can read more about other ways to consume EUI in our wiki. | ||
|
||
## Setting up your application | ||
|
||
:::warning | ||
While EUI is in the process of converting from a Sass based theme to CSS-in-JS via Emotion. We require that both | ||
the [EuiProvider](https://eui.elastic.co/#/utilities/provider) **and** the compiled CSS (or raw Sass) files be imported | ||
during this transition. | ||
::: | ||
|
||
|
||
EUI provides a general context provider to handle global aspects like light and dark theme. You can import these | ||
default themes through their respective compiled CSS files. Use the `.min.css` file extension for the minified version. | ||
|
||
```jsx | ||
import React from 'react'; | ||
import '@elastic/eui/dist/eui_theme_light.css'; | ||
|
||
import { EuiProvider, EuiText } from '@elastic/eui'; | ||
|
||
const MyApp = () => ( | ||
<EuiProvider colorMode="light"> | ||
<EuiText><p>Hello World!</p></EuiText> | ||
</EuiProvider> | ||
); | ||
|
||
export default MyApp; | ||
``` | ||
|
||
For the dark theme, you can swap the words `light` for `dark`. | ||
For more configuration options of the provider, see the | ||
[EuiProvider documentation](https://eui.elastic.co/#/utilities/provider). | ||
|
||
## Styling your application | ||
|
||
To build your custom components using EUI theme variables, functions, and mixins, you will need to consume them | ||
through one of the [Sass](https://eui.elastic.co/#/theming/sass), | ||
[Emotion](https://eui.elastic.co/#/theming/theme-provider), | ||
or [JSON import](https://github.com/elastic/eui/blob/main/wiki/consuming-eui/README.md#a-not-recommended-legacy-method-to-consume-theming-variables-from-sass) methods. | ||
|
||
<Tabs> | ||
<TabItem value="sass" label="Sass"> | ||
```scss title="This will require style, css, postcss, and sass loaders." | ||
// index.scss | ||
@import '@elastic/eui/src/themes/amsterdam/colors_light'; | ||
@import '@elastic/eui/src/themes/amsterdam/globals'; | ||
|
||
@import 'your/custom/styles'; | ||
``` | ||
</TabItem> | ||
<TabItem value="css-in-js" label="CSS-in-JS"> | ||
```jsx title="As long as you have wrapped your application with EuiProvider, you have access to the JS theme tokens via useEuiTheme() and Emotion's css prop." | ||
import React from 'react'; | ||
import { EuiIcon, EuiCode, EuiText, useEuiTheme } from '@elastic/eui'; | ||
import { css } from '@emotion/react'; | ||
|
||
export default () => { | ||
const { euiTheme } = useEuiTheme(); | ||
return ( | ||
<EuiText> | ||
<p> | ||
<EuiIcon | ||
type="stopFilled" | ||
size="xxl" | ||
css={{ color: euiTheme.colors.primary }} | ||
/>{' '} | ||
This primary color will adjust based on the light or dark theme value | ||
</p> | ||
|
||
<p | ||
css={css` | ||
background: ${euiTheme.colors.lightShade}; | ||
padding: calc(${euiTheme.size.base} * 2); | ||
`} | ||
> | ||
The padding of this box is created using <EuiCode>calc()</EuiCode>{' '} | ||
because EUI's theme sizes are string pixel values that are | ||
calculated off the theme's <EuiCode>base</EuiCode> | ||
</p> | ||
</EuiText> | ||
); | ||
}; | ||
``` | ||
</TabItem> | ||
</Tabs> | ||
|
||
### Customizing the style tokens | ||
|
||
EUI can be slightly customized to fit your branding needs by altering the base tokens like color and typography. | ||
Simply declare your token overrides before importing the whole EUI theme. This will re-compile | ||
all of the EUI components with your colors. | ||
|
||
For a full list of global tokens visit Customizing theme. | ||
|
||
:::warning Partial component support | ||
EUI is transitioning to a CSS-in-JS solution for theming and requires consuming/customizing global variables | ||
in **both the Sass and CSS-in-JS** methods. To track this effort, | ||
subscribe to the [Meta ticket](https://github.com/elastic/eui/issues/3912). | ||
::: | ||
|
||
<Tabs> | ||
<TabItem value="sass" label="Sass"> | ||
```scss title="This will require style, css, postcss, and sass loaders and a full re-compile of all EUI component styles." | ||
$euiColorPrimary: #7B61FF; | ||
|
||
// The following rebuilds the entire EUI component styles | ||
@import '@elastic/eui/src/themes/amsterdam/theme_light'; | ||
|
||
@import 'your/custom/styles'; | ||
``` | ||
</TabItem> | ||
<TabItem value="css-in-js" label="CSS-in-JS"> | ||
```jsx title="You can pass along a full or partial list of global overrides to the EuiProvider which will update the EUI components that are currently using the Emotion method of theming." | ||
import React, { FunctionComponent, ReactNode } from 'react'; | ||
import { EuiCode, EuiText, EuiThemeProvider, useEuiTheme } from '@elastic/eui'; | ||
|
||
const Box: FunctionComponent<{ children: ReactNode }> = ({ children }) => { | ||
const { euiTheme } = useEuiTheme(); | ||
|
||
return ( | ||
<EuiText | ||
css={{ | ||
background: euiTheme.colors.lightShade, | ||
padding: euiTheme.size.xl, | ||
}} | ||
> | ||
<p>{children}</p> | ||
</EuiText> | ||
); | ||
}; | ||
|
||
export default () => { | ||
const overrides = { | ||
colors: { | ||
LIGHT: { lightShade: '#d3e6df' }, | ||
DARK: { lightShade: '#394c4b' }, | ||
}, | ||
}; | ||
|
||
return ( | ||
<div> | ||
<EuiThemeProvider modify={overrides}> | ||
<Box> | ||
The background of this box is using the locally overridden value of{' '} | ||
<EuiCode>euiTheme.colors.lightShade</EuiCode> | ||
</Box> | ||
</EuiThemeProvider> | ||
</div> | ||
); | ||
}; | ||
``` | ||
</TabItem> | ||
</Tabs> | ||
|
||
#### Do not use in conjunction with the compiled CSS. | ||
|
||
If you provide both, it will duplicate the imported styles. | ||
|
||
#### Touch the least amount of variables possible. | ||
|
||
By nature EUI is very rigid. You shouldn't need much to make drastic changes to color. Most themes are less then a dozen variable overwrites in total. | ||
|
||
#### Do not overwrite individual component variables or .eui class names. | ||
|
||
Although this may be possible, components are much more prone to change and you'll risk breaking your theme. All EUI components accept custom a className which you can use to append your custom styles. | ||
|
||
## Fonts | ||
|
||
By default, EUI ships with a font stack that includes some outside, open source fonts. If your system is internet | ||
available you can include these by adding the following imports to your SCSS/CSS files, otherwise you'll need | ||
to bundle the physical fonts in your build. EUI will drop to System Fonts (which you may prefer) in their absence. | ||
|
||
```jsx | ||
<link | ||
href="https://fonts.googleapis.com/css2?family=Inter:ital,wght@300;400;500;600;700&family=Roboto+Mono:ital,wght@0,400;0,700;1,400;1,700&display=swap" | ||
rel="stylesheet" | ||
/> | ||
``` | ||
|
||
Or grab all weights, including italics, between 400 and 700 as a variable font. | ||
|
||
```jsx | ||
<link | ||
href="https://fonts.googleapis.com/css2?family=Inter:slnt,wght@-10,300..700;0,300..700&family=Roboto+Mono:ital,wght@0,400..700;1,400..700&display=swap" | ||
rel="stylesheet" | ||
/> | ||
``` | ||
|
||
|
||
### Embedding with @font-face | ||
|
||
If your application doesn't allow grabbing the font assets from a CDN, you'll need to download and locally provide | ||
the font files. You can download the files directly from their source site [rsms.me/inter/](https://rsms.me/inter), | ||
then follow the instructions in the provided CSS file for importing. | ||
We recommend using the single variable font file and importing with the following settings: | ||
|
||
```scss | ||
@font-face { | ||
font-family: 'Inter'; | ||
font-weight: 300 900; | ||
font-display: swap; | ||
font-style: oblique 0deg 10deg; | ||
src: url("Inter.var.woff2") format("woff2"); | ||
} | ||
``` | ||
|
||
## Components, Services and Testing imports | ||
|
||
You can import React components from the top-level EUI module. | ||
|
||
```jsx | ||
import { | ||
EuiButton, | ||
EuiCallOut, | ||
EuiPanel, | ||
} from '@elastic/eui'; | ||
``` | ||
|
||
Most services are published from the lib/services directory. | ||
Some are published from their module directories in this directory. | ||
|
||
```jsx | ||
import { keys } from '@elastic/eui/lib/services'; | ||
import { Timer } from '@elastic/eui/lib/services/time'; | ||
``` | ||
|
||
Test utilities are published from the lib/test directory. | ||
|
||
```jsx | ||
import { findTestSubject } from '@elastic/eui/lib/test'; // Enzyme | ||
import { findByTestSubject, render, screen } from '@elastic/eui/lib/test/rtl'; // React Testing Library | ||
``` | ||
|
||
## Customizing with classes | ||
|
||
We do not recommend customizing EUI components by applying styles directly to EUI classes, eg. `.euiButton`. | ||
All components allow you to pass a custom `className` prop directly to the component which will then append this | ||
to the class list. Utilizing the cascade feature of CSS, you can then customize by overriding styles | ||
so long as your styles are imported `after` the EUI import. | ||
|
||
```jsx | ||
<EuiButton className="myCustomClass__button" /> | ||
``` | ||
|
||
Renders as: | ||
|
||
```jsx | ||
<button class="euiButton myCustomClass__button" /> | ||
``` | ||
|
||
## Customizing component defaults | ||
|
||
While all props can be individually customized via props, some components can have their default props customized | ||
globally via **EuiProvider's** `componentDefaults` API. | ||
[Read more in EuiProvider's documentation](https://eui.elastic.co/#/utilities/provider#component-defaults). | ||
|
||
```jsx | ||
<EuiProvider | ||
componentDefaults={{ | ||
EuiTablePagination: { itemsPerPage: 20, }, | ||
EuiFocusTrap: { crossFrame: true }, | ||
EuiPortal: { insert }, | ||
}} | ||
> | ||
<App /> | ||
</EuiProvider> | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
link: | ||
type: doc | ||
id: testing-introduction |
Oops, something went wrong.