import { Avatar } from '@preply/ds-web-lib';
import { Meta } from '@storybook/addon-docs/blocks';

import { PaddingDemo, ResponsiveDemo } from './components/ValueDemos';

<Meta
    title="Conventions/Responsive and shorthand values"
    summary="How to use responsive and shorthand props."
/>

# Responsive and shorthand values

Two value conventions apply across many component props: **responsive objects** let a prop change
with the viewport, and **shorthand arrays** let spacing props set multiple sides at once. They
compose with each other.

## Responsive values

Props that accept responsive values take either a single value or an object keyed by breakpoint:

```jsx
<Component prop={value} />
<Component prop={{ _: value, '<breakpoint>': value, ... }} />
```

Responsive objects are **mobile-first**: `_` sets the value for the smallest screens, and each
breakpoint key overrides it from that width upward.

| Key        | Applies from | Targets                                      |
| ---------- | ------------ | -------------------------------------------- |
| `_`        | `0px`        | Every screen; in practice, phones (portrait) |
| `narrow-l` | `400px`      | Large phones                                 |
| `medium-s` | `700px`      | Tablets (portrait), phones (landscape)       |
| `medium-l` | `880px`      | Tablets (landscape), small laptops           |
| `wide-s`   | `1200px`     | Laptops and desktops                         |
| `wide-l`   | `1900px`     | Large desktop monitors                       |

For example, the second avatar below starts at `24px`, grows to `48px` at `medium-l`, and to
`64px` at `wide-s`:

```jsx
<Avatar src={url} size="24" />
<Avatar src={url} size={{ _: '24', 'medium-l': '48', 'wide-s': '64' }} />
```

export const url = './assets/avatar-1.png';

<ResponsiveDemo>
    <Avatar src={url} size="24" />
    <Avatar src={url} size={{ _: '24', 'medium-l': '48', 'wide-s': '64' }} />
</ResponsiveDemo>

Resize the window — or use dev-tools responsive mode — and watch the second avatar and the badge
update.

Custom CSS should use the same breakpoints — see the
[Breakpoints utility](/docs/utilities-breakpoints--docs).

## Shorthand values

Spacing props like `padding` and `margin` accept one to four values, following the CSS shorthand
order. Every row below is the same `Box` — the pink area is the padding it produces:

| Value                               | Sides                                                 |                                                  |
| ----------------------------------- | ----------------------------------------------------- | ------------------------------------------------ |
| `padding="8"`                       | All four sides                                        | <PaddingDemo values="8" />                       |
| `padding={['8', '16']}`             | `[vertical, horizontal]`                              | <PaddingDemo values={['8', '16']} />             |
| `padding={['8', '16', '24']}`       | `[top, horizontal, bottom]`                           | <PaddingDemo values={['8', '16', '24']} />       |
| `padding={['8', '16', '24', '32']}` | `[top, right, bottom, left]` — clockwise from the top | <PaddingDemo values={['8', '16', '24', '32']} /> |

## Combining both

Shorthand arrays work inside responsive objects:

```jsx
<Box
    padding={{
        _: '8',
        'medium-l': ['16', '24'],
        'wide-s': ['16', '24', '32', '40'],
    }}
/>
```

When a combined value becomes hard to read, prefer several explicit props over one clever
expression.