Skip to content

Commit

Permalink
feat: move docusaurus website to packages directory (#7815)
Browse files Browse the repository at this point in the history
  • Loading branch information
tkajtoch authored Jun 7, 2024
1 parent 3e22cc5 commit 1cabbd2
Show file tree
Hide file tree
Showing 163 changed files with 12,258 additions and 48 deletions.
20 changes: 20 additions & 0 deletions packages/website/.gitignore
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*
41 changes: 41 additions & 0 deletions packages/website/README.md
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.
11 changes: 11 additions & 0 deletions packages/website/babel.config.js
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')],
};
2 changes: 2 additions & 0 deletions packages/website/docs/01_guidelines/_category_.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
label: Guidelines
collapsed: false
309 changes: 309 additions & 0 deletions packages/website/docs/01_guidelines/getting_started.mdx
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&apos;s theme sizes are string pixel values that are
calculated off the theme&apos;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>
```
3 changes: 3 additions & 0 deletions packages/website/docs/01_guidelines/testing/_category_.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
link:
type: doc
id: testing-introduction
Loading

0 comments on commit 1cabbd2

Please sign in to comment.