Skip to content

Commit

Permalink
πŸ“ Switch documentation (#2280)
Browse files Browse the repository at this point in the history
* πŸ“ Add docs file

* πŸ“  Add Introduction

* πŸ“  Add Usage

* Add Examples

* πŸ“ Update Default states example

* πŸ“ Update example

* Update label value in DefaultStates
  • Loading branch information
martalalik authored Jun 15, 2022
1 parent f8fa7bf commit 0ab5a7a
Show file tree
Hide file tree
Showing 3 changed files with 127 additions and 115 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,6 @@ export const SimpleSliderWithSteps: Story<SliderProps> = () => {
</>
)
}

SimpleSliderWithSteps.storyName = 'Simple slider with steps'
SimpleSliderWithSteps.decorators = [
(Story) => (
Expand Down
66 changes: 66 additions & 0 deletions packages/eds-core-react/src/components/Switch/Switch.docs.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
import { Links, PropsTable, Story } from './../../../.storybook/components'
import { Switch } from '.'

# Switch

Selection controls allow users to select options, make decisions and set preferences.

<Links
ariaUrl="https://www.w3.org/WAI/ARIA/apg/patterns/switch/"
figmaUrl="https://www.figma.com/file/0bGXR2sCwMVSDNyyzu5BXrO5/UI%E2%80%94User-Interface?node-id=18442%3A38197"
documentationUrl="https://eds.equinor.com/0b0c666ab/p/028476-selection-controls/b/86826a"
sourceUrl="https://github.com/equinor/design-system/blob/develop/packages/eds-core-react/src/components/Switch/Switch.tsx"
npmUrl="https://www.npmjs.com/package/@equinor/eds-core-react"
/>

<Story id="inputs-selection-controls-switch--introduction" />
<PropsTable />

## Usage

**Selection controls**

<ul>
<li>Allow users to select options, make decisions and set preferences.</li>
<li>Are to be visible and understandable at a quick glance.</li>
<li>Are always accompanied with a clear label.</li>
</ul>

**Switch**

<ul>
<li>Toggle a single item on or off.</li>
<li>Immediately activate or deactivate something.</li>
<li>Switches make it easy to compare available options.</li>
</ul>

```tsx
import { Switch } from '@equinor/eds-core-react'

<Switch label="Label text" />
```

## Examples

### Default states

<Story id="inputs-selection-controls-switch--default-states" />

### Alternative to label

To comply with accessibility, a `label` is always required on inputs. In some cases though, a visual label is not desirable. <br />
In such cases `aria-label` or `aria-labelledby` should be used.

<Story id="inputs-selection-controls-switch--alternative-to-label" />

### Compact

Compact `Switch` using `EdsProvider`.

<Story id="inputs-selection-controls-switch--compact" />

### Table switch

Example of usage with `Switch` and `aria-label` in tables for accessibility.

<Story id="inputs-selection-controls-switch--table-switch" />
175 changes: 61 additions & 114 deletions packages/eds-core-react/src/components/Switch/Switch.stories.tsx
Original file line number Diff line number Diff line change
@@ -1,67 +1,65 @@
import { useState, useEffect } from 'react'
import { useState, useEffect, ChangeEvent } from 'react'
import { Switch, SwitchProps, EdsProvider, Table, Density } from '../..'
import styled from 'styled-components'
import { Meta, Story } from '@storybook/react'
import { ComponentMeta, Story } from '@storybook/react'
import { data } from '../../stories/data'
import page from './Switch.docs.mdx'

type WrapperStyleProps = {
darkMode?: boolean
}
const Wrapper = styled.div<WrapperStyleProps>`
display: grid;
grid-template-rows: min-width;
padding: 32px;
padding-bottom: 8rem;
grid-gap: 2rem;
position: relative;
background-color: ${({ darkMode }) => (darkMode ? '#0A0310' : 'white')};
color: ${({ darkMode }) => (darkMode ? 'white' : 'black')};
transition: all 0.36s;
const UnstyledList = styled.ul`
margin: 0;
padding: 0;
list-style-type: none;
`

export default {
title: 'Inputs/Selection Controls/Switch',
component: Switch,
parameters: {
docs: {
description: {
component: `Selection controls allow users to select options, make decisions and set preferences.
`,
},
page,
},
},
} as Meta
} as ComponentMeta<typeof Switch>

export const Default: Story<SwitchProps> = (args) => (
export const Introduction: Story<SwitchProps> = (args) => (
<Switch label="Play with me" {...args} />
)

export const DefaultStates: Story<SwitchProps> = () => {
const UnstyledList = styled.ul`
list-style-type: none;
li {
margin-bottom: 8px;
}
`
const [check, setCheck] = useState(false)

return (
<Wrapper>
<UnstyledList>
<li>
<Switch label="I'm default off" />
</li>
<li>
<Switch label="I'm default on" defaultChecked />
</li>
<li>
<Switch disabled label="You can't turn me on!" />
</li>
<li>
<Switch disabled defaultChecked label="You can't turn me off!" />
</li>
</UnstyledList>
</Wrapper>
<UnstyledList>
<li>
<Switch label="I'm default off" />
</li>
<li>
<Switch label="I'm default on" defaultChecked />
</li>
<li>
<Switch disabled label="You can't turn me on!" />
</li>
<li>
<Switch disabled defaultChecked label="You can't turn me off!" />
</li>
<li>
<Switch
onChange={(e: ChangeEvent<HTMLInputElement>) => {
setCheck(e.target.checked)
}}
checked={check}
label={`Slider is ${check ? 'checked' : 'unchecked'}`}
/>
</li>
</UnstyledList>
)
}
DefaultStates.storyName = 'Default states'

export const AlternativeToLabel: Story<SwitchProps> = () => (
<Switch aria-label="This label is invisible, but read by screen-readers" />
)
AlternativeToLabel.storyName = 'Alternative to label'

export const Compact: Story<SwitchProps> = () => {
const [density, setDensity] = useState<Density>('comfortable')
Expand All @@ -71,75 +69,31 @@ export const Compact: Story<SwitchProps> = () => {
setDensity('compact')
}, [density])

const UnstyledList = styled.ul`
list-style-type: none;
li {
margin-bottom: 4px;
}
`
return (
<EdsProvider density={density}>
<Wrapper>
<UnstyledList>
<li>
<Switch label="I'm default off" size="small" />
</li>
<li>
<Switch label="I'm default on" defaultChecked size="small" />
</li>
<li>
<Switch disabled label="You can't turn me on!" size="small" />
</li>
<li>
<Switch
disabled
defaultChecked
label="You can't turn me off!"
size="small"
/>
</li>
</UnstyledList>
</Wrapper>
<UnstyledList>
<li>
<Switch label="I'm default off" size="small" />
</li>
<li>
<Switch label="I'm default on" defaultChecked size="small" />
</li>
<li>
<Switch disabled label="You can't turn me on!" size="small" />
</li>
<li>
<Switch
disabled
defaultChecked
label="You can't turn me off!"
size="small"
/>
</li>
</UnstyledList>
</EdsProvider>
)
}

Compact.parameters = {
docs: {
description: {
story: 'Compact `Switch` using `EdsProvider` ',
},
},
}

export const ControlledSwitchControl: Story<SwitchProps> = () => {
const [darkMode, setDarkMode] = useState(false)
return (
<Wrapper darkMode={darkMode}>
<Switch
checked={darkMode}
onChange={() => setDarkMode(!darkMode)}
label="Dark mode"
/>
</Wrapper>
)
}

ControlledSwitchControl.storyName = 'Use case with controlled component'

export const alternativeToLabel: Story<SwitchProps> = () => (
<Switch aria-label="This label is invisible, but read by screen-readers" />
)

alternativeToLabel.parameters = {
docs: {
description: {
story:
'To comply with accessibility, a `label` is always required on inputs. In some cases though, a visual label is not desirable. In such cases `aria-label` or `aria-labelledby` should be used',
},
},
}

export const TableSwitch: Story<SwitchProps> = () => {
return (
<Table>
Expand All @@ -160,11 +114,4 @@ export const TableSwitch: Story<SwitchProps> = () => {
</Table>
)
}
TableSwitch.parameters = {
docs: {
description: {
story:
'Example of usage with `Switch` and `aria-label` in tables for accessibility',
},
},
}
TableSwitch.storyName = 'Table switch'

0 comments on commit 0ab5a7a

Please sign in to comment.