Skip to content

Commit

Permalink
fix: removed StoryHeading from documentation folder
Browse files Browse the repository at this point in the history
  • Loading branch information
Powerplex committed Mar 31, 2023
1 parent ba86f8f commit 7d196b4
Show file tree
Hide file tree
Showing 7 changed files with 78 additions and 93 deletions.
9 changes: 4 additions & 5 deletions documentation/build/Build.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
import { Meta } from '@storybook/blocks'
import { StoryHeading } from '@docs/helpers/StoryHeading'

<Meta title="Build/Build" />

Expand All @@ -8,19 +7,19 @@ import { StoryHeading } from '@docs/helpers/StoryHeading'
- [How it works](#how-it-works)
- [Configuration](#configuration)

<StoryHeading label="How it works" />
## How it works

Vite manages the build task of each package. Among other things, Vite offers "a build command that bundles your code with Rollup, pre-configured to output highly optimized static assets for production."

When it is time to deploy your app for production, simply run the `vite build` command.

<StoryHeading label="Configuration" />
## Configuration

Each package must include a `vite.config.ts` that will allow custom configurations about the final result of the artifact. You can find the list of possible settings on the [Vite documentation website](https://vitejs.dev/config/build-options.html#build-target).

Spark has a base configuration located in the `/config` directory with some default settings shared between all the packages. Including:

<StoryHeading label="build.target" as="h3" />
### build.target

Definition: Browser compatibility target for the final bundle.

Expand All @@ -30,7 +29,7 @@ Definition: Browser compatibility target for the final bundle.
build.target: 'es2015'
```

<StoryHeading label="build.lib" as="h3" />
### build.lib

```json
build.lib: {
Expand Down
11 changes: 5 additions & 6 deletions documentation/contributing/CommitStrategy.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
import { Meta } from '@storybook/blocks'
import { StoryHeading } from '@docs/helpers/StoryHeading'

<Meta title="Contributing/Commit" />

Expand All @@ -11,7 +10,7 @@ import { StoryHeading } from '@docs/helpers/StoryHeading'
- [Lerna Integration](#lerna-integration)
- [Further reading](#further-reading)

<StoryHeading label="How it works" />
## How it works

- Stage changes `git add .`
- Commit `npm run commit`
Expand All @@ -22,7 +21,7 @@ import { StoryHeading } from '@docs/helpers/StoryHeading'
- Select if are there any **breaking changes** (y/N)
- Select if the change affects any open issues (y/N)

<StoryHeading label="Commit Convention" />
## Commit Convention

Spark ✨ adheres to a commit convention called [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0).

Expand All @@ -45,15 +44,15 @@ In general, the pattern mostly looks like this:

Checkout [specification docs](https://www.conventionalcommits.org/en/v1.0.0/#specification) for deeper information.

<StoryHeading label="Enforcing Convention" />
## Enforcing Convention

In order to enforce the convention, [commitlint](https://github.com/conventional-changelog/commitlint) checks if your commit messages meet the conventional commit format using [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional).

<StoryHeading label="Lerna Integration" />
## Lerna Integration

In order to automatically detect and enforce the lerna package and workspace names as scopes, we are using [@commitlint/config-lerna-scopes](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-lerna-scopes)

<StoryHeading label="Further reading" />
## Further reading

- [Why Use Conventional Commits?](https://www.conventionalcommits.org/en/v1.0.0/#why-use-conventional-commits)
- ["The perks of committing with conventions" (Talk slides)](https://slides.com/marionebl/the-perks-of-committing-with-conventions)
21 changes: 10 additions & 11 deletions documentation/contributing/TestingStrategy.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
import { Meta } from '@storybook/blocks'
import { StoryHeading } from '@docs/helpers/StoryHeading'
import { StoryStatus } from '@docs/helpers/StoryStatus'

<Meta title="Contributing/Testing" />
Expand All @@ -19,7 +18,7 @@ import { StoryStatus } from '@docs/helpers/StoryStatus'
- [Triggering user events](#triggering-user-events)
- [Testing utilities (methods, hooks)](#testing-utilities)

<StoryHeading label="Scripts" />
## Scripts

**`npm run test`**: run tests in watch mode (in your terminal)

Expand All @@ -29,15 +28,15 @@ import { StoryStatus } from '@docs/helpers/StoryStatus'

**`npm run test:coverage`**: run tests with coverage. Output is visible in the terminal, or in the `coverage` folder that is generated (html reporter).

<StoryHeading label="Vitest" />
## Vitest

[Vitest](https://vitest.dev/guide/why.html) is the test runner used by Spark.

It allows everything a test runner is known for: test suites, mocking, coverage, test filtering, etc.

We highly recommend installing [the official plugin](https://vitest.dev/guide/ide.html) that matches your IDE (it supports VSCode and IntelliJ).

<StoryHeading label="Testing Library" />
## Testing Library

[Testing Library](https://testing-library.com/docs/) is our main... testing library :3

Expand All @@ -49,7 +48,7 @@ We want to check the interface we provide to users, not their technical implemen
> The more your tests resemble the way your software is used,
> the more confidence they can give you.
<StoryHeading label="user-event" />
## user-event

[user-event](https://testing-library.com/docs/ecosystem-user-event/) is a companion library that is part
of the Testing Library ecosystem.
Expand All @@ -58,11 +57,11 @@ It provides a cleaner way to simulate user events. It is closer to the browser b

You can read [here](https://testing-library.com/docs/user-event/intro#differences-from-fireevent) in detail why it is better than `fireEvent`.

<StoryHeading label="Testing components" />
## Testing components

Spark component packages are scaffolded with a default test file using `Vitest` + `Testing Library` + `user-event`.

<StoryHeading label="Grouping tests" as="h3" />
### Grouping tests

Group tests in logical blocks using the `describe()` method from `vitest`.

Expand All @@ -73,7 +72,7 @@ describe('MenuBar behaviour', () => { ... }) // first block
describe('BurgerMenu behaviour', () => { ... }) // second block
```

<StoryHeading label="Naming your tests" as="h3" />
### Naming your tests

Each test description must start with `should`

Expand All @@ -87,7 +86,7 @@ describe('MenuBar behaviour', () => {
})
```

<StoryHeading label="Given/When/Then and test assertions" as="h3" />
### Given/When/Then and test assertions

Inside a test, we recommend you stick with the [Given/When/Then pattern](https://martinfowler.com/bliki/GivenWhenThen.html).
Following this same pattern across tests makes them easier to read and understand.
Expand All @@ -110,7 +109,7 @@ it('should trigger click event', async () => {
})
```

<StoryHeading label="Triggering user events" as="h3" />
### Triggering user events

[User events](https://testing-library.com/docs/user-event/intro#writing-tests-with-userevent) are simulated using `user-event`, as seen in the previous example.

Expand All @@ -129,7 +128,7 @@ A few things to note:
- It is recommended that you set up the `user` independently in each test, doing `const user = userEvent.setup()`. That way, you can pass different options at the test level if necessary.
- Calls to events (`user.click, user.keyboard, user.scroll`, etc.) are asynchronous, so you MUST use `async/await` on your tests.

<StoryHeading label="Testing utilities" />
## Testing utilities

Hooks, methods, and other types of utilities that are not user interfaces are simply tested using unit testing.
So for most of them, you won't require Testing Library.
Expand Down
51 changes: 22 additions & 29 deletions documentation/contributing/WritingStories.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
import { Meta } from '@storybook/blocks'
import { StoryHeading } from '@docs/helpers/StoryHeading'
import { Callout } from '@docs/helpers/Callout'

import ArgstableImg from '@docs/assets/argstable.png'
Expand All @@ -10,7 +9,7 @@ import ArgstableImg from '@docs/assets/argstable.png'

The following guide is showing you how to structure your components documentation.

<StoryHeading label="Docs VS Stories" />
## Docs VS Stories

Each component must have a `doc` and a `stories` file. For example:

Expand All @@ -20,14 +19,14 @@ Each component must have a `doc` and a `stories` file. For example:
- This file contains every example (story) for your component.
- It is using the CSF format.

<StoryHeading label="Docs" />
## Docs

<StoryHeading label="Docs guidelines" as="h3" />
### Docs guidelines

- Every Docs file must have the following extension: `*.doc.mdx`.
- You must write the following sections in the same order for every component.

<StoryHeading label="1. Referencing the Meta" as="h3" />
### 1. Referencing the Meta

The meta is the semantic information about the documented component.
It must be located in the `*stories.tsx` file, but must be referenced in this one to link both files.
Expand All @@ -42,65 +41,61 @@ import * as RadioStories from './Radio.stories'
<Meta of={RadioStories} />
```

<StoryHeading label="2. Install" as="h3" />
### 2. Install

Add a section to show developers how to install this component on their repository.

````
// Radio.doc.mdx
import { StoryHeading } from '@docs/helpers/StoryHeading'
<StoryHeading label="Install" />
## Install
\```sh
npm install @spark-ui/radio
\```
````

<StoryHeading label="3. Import" as="h3" />
### 3. Import

Add a section to show developers how to import this component from their repository.

````
// Radio.doc.mdx
import { StoryHeading } from '@docs/helpers/StoryHeading'
<StoryHeading label="Import" />
## Import
\```ts
import { RadioGroup, Radio } from '@spark-ui/radio'
\```
````

<StoryHeading label="4. Props" as="h3" />
### 4. Props

<StoryHeading label="Props for single components" as="h4" />
#### Props for single components

For prop, we rely on `ArgsTable` to read TS files and generate them automatically.

```
// Radio.doc.mdx
import { ArgsTable } from '@storybook/addon-docs'
import { StoryHeading } from '@docs/helpers/StoryHeading'
import { Radio } from '.'
<StoryHeading label="Props" />
## Props
<ArgsTable of={Radio} />
```

**Here is what the ArgsTable looks like for a simple component:**

<img width={800} src={ArgstableImg} alt="Argstable shows a table of the component's props" />

<StoryHeading label="Props for compound components" as="h4" />
#### Props for compound components

TODO

<StoryHeading label="5. Linking stories" as="h3" />
### 5. Linking stories

Stories are imported from the associated `*.stories.tsx` file, which is written with CSF format.

Expand All @@ -115,9 +110,8 @@ Stories are imported from the associated `*.stories.tsx` file, which is written
// Radio.doc.mdx
import { Canvas, Story } from '@storybook/addon-docs'
import { StoryHeading } from '@docs/helpers/StoryHeading'
<StoryHeading label="Default" />
## Default
Compound `RadioGroup` and `Radio` components to create a radio group.
Expand All @@ -126,19 +120,18 @@ Compound `RadioGroup` and `Radio` components to create a radio group.
</Canvas>
```

<StoryHeading label="6. Accessibility" as="h3" />
### 6. Accessibility

It is nice to add an `Accessibility` section at the end to summarize keyboard interactions and important a11y requirements of the component.

```
// Radio.doc.mdx
<StoryHeading label="Accessibility" />
## Accessibility
Adheres to the Radio Group WAI-ARIA design pattern and uses roving tabindex to manage focus movement among radio items.
<StoryHeading as="h3" label="Keyboard Interactions" />
### Keyboard Interactions
- `Tab`: Moves focus to either the checked radio item or the first radio item in the group.
- `Space`: When focus is on an unchecked radio item, checks it.
Expand All @@ -149,14 +142,14 @@ Adheres to the Radio Group WAI-ARIA design pattern and uses roving tabindex to m
```

<StoryHeading label="Stories" />
## Stories

<StoryHeading label="Guidelines" as="h3" />
### Guidelines

- Every stories file must have the following extension: `*.stories.tsx`.
- You should write one story per prop. Avoid compolicated stories mixing many props.

<StoryHeading label="1. Define the Meta" as="h3" />
### 1. Define the Meta

Component must be using a `Components/*` meta. This meta must be the default export of the file.

Expand All @@ -178,7 +171,7 @@ const meta: Meta<typeof RadioGroup> = {
export default meta
```

<StoryHeading label="2. Write down your stories" as="h3" />
### 2. Write down your stories

Please refer to [official Storybook documentation](https://storybook.js.org/docs/7.0/react/writing-stories/introduction#defining-stories) to see how you can write stories

Expand Down
9 changes: 4 additions & 5 deletions documentation/getting-started/GettingStarted.mdx
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
import { Meta } from '@storybook/blocks'
import { StoryHeading } from '@docs/helpers/StoryHeading'
import { Callout } from '@docs/helpers/Callout'

<Meta title="Getting Started" />

<StoryHeading label="Getting started" as="h1" />
# Getting started

<Callout marginBottom="medium">
**The Spark Design System** is built using the **Tailwind CSS** framework.
</Callout>

<StoryHeading label="Set up TailwindCSS" as="h2" />
## Set up TailwindCSS

If you haven't installed **TailwindCSS** yet, you can follow the [TailwindCSS installation guide](https://tailwindcss.com/docs/installation).

To benefit from Tailwind CSS **IntelliSense**, be sure to visit this [link](https://tailwindcss.com/docs/editor-setup#intelli-sense-for-vs-code)

<StoryHeading label="Installation" as="h2" />
## Installation

After setting up Tailwind for your application, install the following packages via your command line:

Expand Down Expand Up @@ -92,7 +91,7 @@ However, if your application uses a different base font size, such as **10 pixel
](?path=/docs/utils-tailwind-plugins--docs) for more information.
</Callout>

<StoryHeading label="Extending Spark config" as="h2" />
## Extending Spark config

In cases where you need to tackle uncommon situations, it's important to note that our theme configuration can be extended or overridden using the standard Tailwind approach, as illustrated in the example below:

Expand Down
Loading

0 comments on commit 7d196b4

Please sign in to comment.