# react-boxl

> Layout primitives for the styled component age.

Latest version **0.12.0** (published 2018-11-20) · ISC license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install react-boxl
pnpm add react-boxl
yarn add react-boxl
bun add react-boxl
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.12.0 |
| Published | 2018-11-20 |
| First published | 2018-11-02 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 38 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Crema |
| Maintainers | blaketarter, roblafeve, rossbrown |

## Links

- npm: https://www.npmjs.com/package/react-boxl
- npm.io page: https://npm.io/package/react-boxl

## Recent versions

- 0.12.0 (latest) — 2018-11-20
- 0.7.2 (beta) — 2018-11-06
- 0.11.0 — 2018-11-20
- 0.10.0 — 2018-11-20
- 0.9.0 — 2018-11-20
- 0.8.0 — 2018-11-16
- 0.7.1 — 2018-11-06
- 0.7.0 — 2018-11-06
- 0.6.0 — 2018-11-06
- 0.5.0 — 2018-11-06
- 0.4.0 — 2018-11-04
- 0.3.0 — 2018-11-04
- 0.2.0 — 2018-11-02
- 0.1.0 — 2018-11-02

## README

# B ❐ X L

Layout primitives for the [styled component](https://www.styled-components.com) age.

## Installation

```shell
$ npm i react-boxl styled-components
```
>Built with [styled components](https://www.styled-components.com) which is required as a peer dependency

## Usage

Create components with the `boxl` function passing default props and styling.

```jsx
// Examples.tsx
import * as React from "react";
import { boxl } from "boxl";

const Container = boxl({
  spacing: "16px", // ⬅︎ adds spacing between children
  style: `
    background: white;
    border: 8px solid black;
    box-shadow: 12px -12px 0 0 black;
    margin: 12px 12px 0 0;
    padding: 24px;
  `,
});

/**
 * Additional props may be statically defined
 * using an optional type parameter.
 */

interface SectionProps {
  primary?: boolean;
}

const Section = boxl<SectionProps>({
  style: styled => styled` // ⬅︎ tagged template literal à la styled-components
    ${props => (props.primary ? `background: black;` : ``)};
    background: white;
    border: 8px solid black;
    padding: 32px;
  `,
});
```

#### Direction Vertical (default)
![Example 1](.loki/reference/example_example_01.png)
```jsx
const Vertical = () => (
  <Container>
    <Section primary={true} />
    <Section />
    <Section />
  </Container>
);
```

#### Direction Horizontal
![Example 2](.loki/reference/example_example_02.png)
```jsx
const Horizontal = () => (
  <Container direction="horizontal">
    <Section grow={1} primary={true} />
    <Section />
    <Section />
  </Container>
);
```


## API

### Box

<details>
  <summary>
    <code><strong>alignHorizontal?: "left" | "center" | "right"</strong></code>
  </summary>
  <br>
  
  Aligns children horizontally regardless of `direction` ***(default: "left")***

</details>

<details>
  <summary>
    <code><strong>alignVertical?: "top" | "center" | "bottom"</strong></code>
  </summary>
  <br>
  
  Aligns children vertically regardless of `direction` ***(default: "top")***

</details>

<details>
  <summary>
    <code><strong>childGrow?: number</strong></code>
  </summary>
  <br>
  
  Sets `grow` on all children. Useful in combination with `childWrap`.

  *Example:*
  
  ```tsx
  <Box childGrow={1}>
    <Box>1</Box> // grow: 1
    <Box>2</Box> // grow: 1
  </Box>
  ```

</details>

<details>
  <summary>
    <code><strong>childIdealWidth?: string (CSS length)</strong></code>
  </summary>
  <br>
  
  Sets `idealWith` on all children. Useful in combination with `childWrap`.

  *Example:*
  
  ```tsx
  <Box childIdealWidth="20%">
    <Box>1</Box> // idealWidth: 20%
    <Box>2</Box> // idealWidth: 20%
  </Box>
  ```

</details>

<details>
  <summary>
    <code><strong>childWrap?: "auto" | "even"</strong></code>
  </summary>
  <br>
  
  Allows children to wrap when available space is exceeded

  - **"auto":** children to wrap naturally
  - **"even":** children that wrap maintain any set `idealWidth` or `childIdealWidth` which is useful for achieving an even grid layout

  *Example:*
  
  ```tsx
  // Children wrap naturally
  <Box 
    childGrow={1}
    childWrap="auto"
    direction="horizontal" 
  >
    <Box>1</Box>
    <Box>2</Box>
    <Box>3</Box>
    <Box>4</Box>
  </Box>

  // Children wrap evenly (orphans maintain idealWidth)
  <Box 
    childGrow={1}
    childIdealWidth="200px"
    childWrap="even"
    direction="horizontal" 
  >
    <Box>1</Box>
    <Box>2</Box>
    <Box>3</Box>
    <Box>4</Box>
  </Box>
  ```

</details>

<details>
  <summary>
    <code><strong>direction?: "horizontal" | "vertical"</strong></code>
  </summary>
  <br>
  
  Direction children will flow—stacked or side-by-side. ***(default "vertical")***

  *Example:*
  
  ```tsx
    // Children are stacked
    <Box direction="vertical">
      <Box>1</Box>
      <Box>2</Box>
      <Box>3</Box>
      <Box>4</Box>
    </Box>

    // Children are side-by-side
    <Box direction="horizontal">
      <Box>1</Box>
      <Box>2</Box>
      <Box>3</Box>
      <Box>4</Box>
    </Box>
  ```

</details>

<details>
  <summary>
    <code><strong>element?: string (HTML element—"a", "h1", etc.)</strong></code>
  </summary>
  <br>
  
  HTML element to be rendered ***(default "div")***

  *Example:*
  
  ```tsx
    // Anchor element will be rendered
    <Box element="a" href="http://google.com">
      Take me to google...
    </Box>
  ```

</details>

<details>
  <summary>
    <code><strong>grow?: number</strong></code>
  </summary>
  <br>
  
  Amount that Box should grow in relation to available space or siblings ***(default: 0)***

  *Example:*
  
  ```tsx
    <Parent>
      <Box grow={1}>1</Box> // fills available space
      <Box>2</Box>
      <Box>3</Box>
    </Parent>
  ```

</details>

<details>
  <summary>
    <code><strong>idealWidth?: string (CSS length)</strong></code>
  </summary>
  <br>
  
  Optimal width considering content size and available space (i.e. flex-basis) ***(default: "left")***

  >Note: Use alongside width or max/min-width styles

</details>

<details>
  <summary>
    <code><strong>padding?: string (CSS length)</strong></code>
  </summary>
  <br>
  
  Adds padding and takes priority over padding set via `style`

</details>

<details>
  <summary>
    <code><strong>spacing?: string (CSS length)</strong></code>
  </summary>
  <br>
  
  Defines gap between children

</details>

<details>
  <summary>
    <code><strong>style?: string | template literal | (style) => style`tagged template literal` </strong></code>
  </summary>
  <br>
  
  Defines styling via plain string, template literal, or tagged template literal function. The last option allows interpolation of props including a theme if a `styled-components` theme provider is present.

  >Note: See [styled components docs](https://www.styled-components.com/docs/api#taggedtemplateliteral) for more info

  *Example:*

  ```tsx
    // string
    <Box style="background: red; color: white;" />
    
    // template literal
    <Box 
      style={`
        background: red; 
        color: white;
      `} 
    />
    
    // tagged template literal function
    <Box 
      style={style => style`
        background: ${props => props.theme.color.primary}; 
        color: white;
      `}
    />
  ```

</details>

## Develop

- `npm i` install project and test app deps
- `npm start` starts storybook
- `npm test:unit` runs unit tests
- `npm test:visual` runs visual tests (requires storybook to be running e.g. `npm start`)
- `npm test:visual:watch` runs visual tests in watch mode
- `npm run build` compiles `dist/`
- `npm pack` generates `.tgz` for local testing

---
_Source: https://npm.io/package/react-boxl · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._