npm package: @highlight-ui/layout
Description: A collection of layout helper components.
Author: Personio GmbH & Co. KG
Latest version: 0.6.8

[![npm](https://img.shields.io/npm/v/@highlight-ui/layout)](https://www.npmjs.com/package/@highlight-ui/layout)
[![storybook.personio.design](https://img.shields.io/static/v1?label=Personio&message=Storybook&color=red)](https://storybook.personio.design/?path=/story/foundations-layout)

# @highlight-ui/layout

Layout components are used to manage the white space between components and other elements. They produce visual consistency across Personio products by using a limited set of standardised spacing tokens. This also removes the hassle of space-management from the user.

## Features

- Vertical spacing
  - Controlled by `spacing` tokens
- Horizontal spacing
  - Controlled by `spacing` tokens
  - Horizontal and vertical alignment based on `flex` values
  - Toggle to allow wrapping

## Installation

Using npm:

```bash
npm install @highlight-ui/layout
```

Using yarn:

```bash
yarn add @highlight-ui/layout
```

Using pnpm:

```bash
pnpm install @highlight-ui/layout
```

Remember to import the styles in your (S)CSS file, like so:

```scss
@import url('@highlight-ui/layout');
```

## Usage

### Stack

The `Stack` component manages the **vertical** spacing between elements.

In your TypeScript file:

```ts
import { Stack, StackProps } from '@highlight-ui/layout';
```

```jsx
<Stack space="spacing-4">
  <Placeholder>Item 1</Placeholder>
  <Placeholder>Item 2</Placeholder>
  <Placeholder>Item 3</Placeholder>
</Stack>
```

#### **Props** 📜

| Prop        | Type                | Required | Default     | Description                                              |
| :---------- | :------------------ | :------- | :---------- | :------------------------------------------------------- |
| `space`     | `SpacingType`       | No       | `spacing-0` | The spacing applied to the children.                     |
| `className` | `string`            | No       | `null`      | Classname to apply to the element.                       |
| `metadata`  | `ComponentMetadata` | No       | `null`      | Object used for testing. Contains testId and actionName. |
| `children`  | `React.ReactNode`   | No       | `null`      | Components to apply spacing between.                     |

### Inline

The `Inline` component manages the **horizontal** spacing between elements. In addition to this, this component can also control the alignment of the items (both vertically and horizontally).

In your TypeScript file:

```ts
import { Inline, InlineProps } from '@highlight-ui/layout';
```

```jsx
<Inline space="spacing-4" align="center">
  <Placeholder>Item 1</Placeholder>
  <Placeholder>Item 2</Placeholder>
  <Placeholder>Item 3</Placeholder>
  <Placeholder>Item 4</Placeholder>
  <Placeholder>Item 5</Placeholder>
</Inline>
```

#### **Props** 📜

| Prop            | Type                | Required | Default     | Description                                                             |
| :-------------- | :------------------ | :------- | :---------- | :---------------------------------------------------------------------- |
| `space`         | `SpacingType`       | No       | `spacing-0` | The spacing applied to the children.                                    |
| `align`         | `HorizontalAlignmentType` | No       | `start`     | Horizontal alignment of the items.                                      |
| `alignVertical` | `VerticalAlignmentType`   | No       | `start`     | Vertical alignment of the items.                                        |
| `wrap`          | `boolean`           | No       | `false`     | Whether to wrap the items when their width exceeds the container width. |
| `className`     | `string`            | No       | `null`      | Classname to apply to the element.                                      |
| `metadata`      | `ComponentMetadata` | No       | `null`      | Object used for testing. Contains testId and actionName.                |
| `children`      | `React.ReactNode`   | No       | `null`      | Components to apply spacing between.                                    |

### Shared types

| Type            | Values                                                                                                                                                                                                    |
| :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SpacingType`   | `spacing-0`, `spacing-0-5`, `spacing-1`, `spacing-2`, `spacing-3`, `spacing-4`, `spacing-5`, `spacing-6`, `spacing-8`, `spacing-10`, `spacing-12`, `spacing-16`, `spacing-20`, `spacing-24`, `spacing-32` |
| `HorizontalAlignmentType` | `start`, `center`, `end`, `space-between`, `space-around`, `space-evenly`                                                                                                                       |
| `VerticalAlignmentType`   | `start`, `center`, `end`, `baseline`, `stretch`                                                                                                                                                 |

## Testing

This example serves as starting point on how you can use these layout components as part of your tests.

Certain props are already defined in the `renderInline` (or `renderStack`) method, to reuse through individual tests. Any props can be overriden by passing these to the above function.

```
const testId = 'test-inline';
const metadata = { testId };

function renderInline(props?: Partial<InlineProps>) {
  render(
    <Inline {...props} metadata={metadata}>
      <p>Item 1</p>
      <p>Item 2</p>
    </Inline>,
  );
  return screen.getByTestId(testId);
}
```

## Place in design system 💻

These layout components are not yet used within the `highlight-ui` library. They are still being develiped to be initially used within the following organisms:

- [select](https://www.npmjs.com/package/@highlight-ui/select)

## Contributing 🖌️

If you're interested in contributing, please visit our [contribution page](https://www.personio.design/40d648a47/v/0/p/138faf-about-the-process).