# SilkeBox

A flexible layout component that provides a consistent way to create layouts, spacing, and styling. SilkeBox is the foundation for most UI layouts in Silke, offering flexbox-based positioning with semantic spacing values.

## Features

- **Flexbox layout**: Row or column direction with gap spacing
- **Semantic sizing**: Consistent spacing scale (xs, s, m, l, xl)
- **Padding control**: Unified or separate vertical/horizontal padding
- **Background & colors**: Theme-aware color props with hover states
- **Border radius**: Multiple rounded corner presets
- **Polymorphic rendering**: Render as different HTML elements
- **Scroll handling**: Enable scrolling with optional visible scrollbars
- **Alignment**: Flexible content alignment for both axes

## Basic Usage

```js
<SilkeBox gap>
  <SilkeButton label="Button 1" />
  <SilkeButton label="Button 2" />
</SilkeBox>
```

## Column Layout

Stack items vertically:

```js
<SilkeBox column gap>
  <SilkeButton label="Top" />
  <SilkeButton label="Middle" />
  <SilkeButton label="Bottom" />
</SilkeBox>
```

## Gap Spacing

Control spacing between items with the `gap` prop:

```js
<SilkeBox gap="l">
  {['xxs', 'xs', 's', 'm', 'l', 'xl', 'xxl'].map((gapSize) => (
    <SilkeBox key={gapSize} column gap={gapSize} bg="neutral-10" pad="s" rounded>
      <SilkeText size="s" weight="medium">{gapSize}</SilkeText>
      <SilkeBox bg="accent-50" style={{ height: 20 }} rounded />
      <SilkeBox bg="accent-50" style={{ height: 20 }} rounded />
    </SilkeBox>
  ))}
</SilkeBox>
```

## Padding

Use `pad` for uniform padding, or `vPad`/`hPad` for axis-specific:

```js
<SilkeBox gap="m">
  <SilkeBox pad="m" bg="neutral-10" rounded>
    <SilkeText>pad="m"</SilkeText>
  </SilkeBox>
  <SilkeBox vPad="l" hPad="s" bg="neutral-10" rounded>
    <SilkeText>vPad="l" hPad="s"</SilkeText>
  </SilkeBox>
  <SilkeBox pad="xl" bg="neutral-10" rounded>
    <SilkeText>pad="xl"</SilkeText>
  </SilkeBox>
</SilkeBox>
```

## Size Props

Set dimensions using the semantic size scale:

```js
<SilkeBox gap="s" wrap>
  {['xs', 's', 'base', 'm', 'l', 'xl'].map((size) => (
    <SilkeBox key={size} size={size} bg="accent-40" rounded vAlign="center" hAlign="center">
      <SilkeText size="s" color="neutral-0">{size}</SilkeText>
    </SilkeBox>
  ))}
</SilkeBox>
```

## Alignment

Align content horizontally and vertically:

```js
<SilkeBox gap="m">
  <SilkeBox width="l" height="l" bg="neutral-10" rounded hAlign="start" vAlign="start">
    <SilkeBox size="s" bg="accent-50" rounded />
  </SilkeBox>
  <SilkeBox width="l" height="l" bg="neutral-10" rounded hAlign="center" vAlign="center">
    <SilkeBox size="s" bg="accent-50" rounded />
  </SilkeBox>
  <SilkeBox width="l" height="l" bg="neutral-10" rounded hAlign="end" vAlign="end">
    <SilkeBox size="s" bg="accent-50" rounded />
  </SilkeBox>
  <SilkeBox width="l" height="l" bg="neutral-10" rounded hAlign="spread">
    <SilkeBox size="xs" bg="accent-50" rounded />
    <SilkeBox size="xs" bg="accent-50" rounded />
  </SilkeBox>
</SilkeBox>
```

## Background Colors

Apply theme colors with optional hover states:

```js
<SilkeBox gap="s">
  <SilkeBox pad="m" bg="accent-50" rounded>
    <SilkeText color="neutral-0">accent-50</SilkeText>
  </SilkeBox>
  <SilkeBox pad="m" bg="success-50" rounded>
    <SilkeText color="neutral-0">success-50</SilkeText>
  </SilkeBox>
  <SilkeBox pad="m" bg="neutral-10" bgHover="neutral-20" rounded cursor="pointer">
    <SilkeText>Hover me</SilkeText>
  </SilkeBox>
  <SilkeBox pad="m" bg="blur" rounded>
    <SilkeText>blur background</SilkeText>
  </SilkeBox>
</SilkeBox>
```

## Border Radius

Multiple rounded corner presets:

```js
<SilkeBox gap="s">
  <SilkeBox size="l" bg="accent-50" rounded="tiny" />
  <SilkeBox size="l" bg="accent-50" rounded="small" />
  <SilkeBox size="l" bg="accent-50" rounded="medium" />
  <SilkeBox size="l" bg="accent-50" rounded="full" />
</SilkeBox>
```

## Shadow Levels

Apply shadow elevation:

```js
<SilkeBox gap="l" pad="m">
  {['level1', 'level2', 'level3', 'level4'].map((shadow) => (
    <SilkeBox key={shadow} pad="m" bg="neutral-0" rounded shadow={shadow}>
      <SilkeText>{shadow}</SilkeText>
    </SilkeBox>
  ))}
</SilkeBox>
```

## Fill Container

Make the box fill its parent:

```js
<SilkeBox style={{ height: 100 }} bg="neutral-10" rounded pad="s">
  <SilkeBox fill bg="accent-50" rounded vAlign="center" hAlign="center">
    <SilkeText color="neutral-0">Fills parent</SilkeText>
  </SilkeBox>
</SilkeBox>
```

## Flex Item

Mark as a flex item that grows:

```js
<SilkeBox gap="s">
  <SilkeBox pad="s" bg="neutral-20" rounded>
    <SilkeText>Fixed</SilkeText>
  </SilkeBox>
  <SilkeBox flex pad="s" bg="accent-50" rounded>
    <SilkeText color="neutral-0">Flex grows</SilkeText>
  </SilkeBox>
  <SilkeBox pad="s" bg="neutral-20" rounded>
    <SilkeText>Fixed</SilkeText>
  </SilkeBox>
</SilkeBox>
```

## Wrap Items

Allow items to wrap to new lines:

```js
<SilkeBox wrap gap="s" style={{ maxWidth: 300 }}>
  {Array.from({ length: 10 }, (_, i) => (
    <SilkeBox key={i} pad="s" bg="accent-40" rounded>
      <SilkeText color="neutral-0">Item {i + 1}</SilkeText>
    </SilkeBox>
  ))}
</SilkeBox>
```

## Scrollable Content

Enable scrolling with optional visible scrollbars:

```js
<SilkeBox column gap="m">
  <SilkeBox scroll style={{ height: 100 }} bg="neutral-10" rounded pad="s">
    <SilkeBox column gap="xs">
      {Array.from({ length: 10 }, (_, i) => (
        <SilkeText key={i}>Scrollable item {i + 1}</SilkeText>
      ))}
    </SilkeBox>
  </SilkeBox>
  <SilkeBox scroll="show" style={{ height: 100 }} bg="neutral-10" rounded pad="s">
    <SilkeBox column gap="xs">
      {Array.from({ length: 10 }, (_, i) => (
        <SilkeText key={i}>Visible scrollbar {i + 1}</SilkeText>
      ))}
    </SilkeBox>
  </SilkeBox>
</SilkeBox>
```

## Aspect Ratio

Maintain aspect ratio:

```js
<SilkeBox gap="m">
  <SilkeBox width="l" aspectRatio="16:9" bg="accent-50" rounded vAlign="center" hAlign="center">
    <SilkeText color="neutral-0" size="s">16:9</SilkeText>
  </SilkeBox>
  <SilkeBox width="l" aspectRatio="4:3" bg="success-50" rounded vAlign="center" hAlign="center">
    <SilkeText color="neutral-0" size="s">4:3</SilkeText>
  </SilkeBox>
  <SilkeBox width="l" aspectRatio="1:1" bg="warning-50" rounded vAlign="center" hAlign="center">
    <SilkeText color="neutral-0" size="s">1:1</SilkeText>
  </SilkeBox>
</SilkeBox>
```

## Polymorphic Rendering

Render as different HTML elements:

```js
<SilkeBox column gap="s">
  <SilkeBox tag="button" pad="s" bg="accent-50" rounded cursor="pointer" onClick={() => alert('clicked')}>
    <SilkeText color="neutral-0">Renders as button</SilkeText>
  </SilkeBox>
  <SilkeBox tag="a" href="#" pad="s" bg="neutral-10" rounded>
    <SilkeText>Renders as anchor</SilkeText>
  </SilkeBox>
  <SilkeBox tag="form" column gap="s" pad="s" bg="neutral-10" rounded>
    <SilkeText>Renders as form</SilkeText>
  </SilkeBox>
</SilkeBox>
```

## Debug Mode

Visualize box boundaries:

```js
<SilkeBox debug column gap="s" pad="s">
  <SilkeBox gap="s">
    <SilkeBox pad="s">Item 1</SilkeBox>
    <SilkeBox pad="s">Item 2</SilkeBox>
  </SilkeBox>
  <SilkeBox gap="s">
    <SilkeBox pad="s">Item 3</SilkeBox>
    <SilkeBox pad="s">Item 4</SilkeBox>
  </SilkeBox>
</SilkeBox>
```

## Props

| Prop          | Type                                           | Default | Description                                       |
| ------------- | ---------------------------------------------- | ------- | ------------------------------------------------- |
| `column`      | `boolean`                                      | `false` | Stack children vertically                         |
| `fill`        | `boolean`                                      | `false` | Fill parent container                             |
| `flex`        | `boolean`                                      | `false` | Mark as flex item that grows                      |
| `wrap`        | `boolean`                                      | `false` | Allow items to wrap                               |
| `gap`         | `BoxSpace`                                     | -       | Space between children                            |
| `pad`         | `BoxSpace`                                     | -       | Padding on all sides                              |
| `vPad`        | `BoxSpace`                                     | -       | Vertical padding only                             |
| `hPad`        | `BoxSpace`                                     | -       | Horizontal padding only                           |
| `size`        | `BoxSize`                                      | -       | Sets both width and height                        |
| `width`       | `BoxSize`                                      | -       | Width of the box                                  |
| `height`      | `BoxSize`                                      | -       | Height of the box                                 |
| `minWidth`    | `BoxSize`                                      | -       | Minimum width                                     |
| `minHeight`   | `BoxSize`                                      | -       | Minimum height                                    |
| `align`       | `BoxAlign \| [BoxAlign, BoxAlign]`             | -       | Align content (single or [horizontal, vertical]) |
| `vAlign`      | `BoxAlign`                                     | -       | Vertical alignment                                |
| `hAlign`      | `BoxAlign`                                     | -       | Horizontal alignment                              |
| `bg`          | `SilkeColor \| 'blur'`                         | -       | Background color                                  |
| `bgHover`     | `SilkeColor`                                   | -       | Background color on hover                         |
| `color`       | `SilkeColor`                                   | -       | Text color                                        |
| `colorHover`  | `SilkeColor`                                   | -       | Text color on hover                               |
| `rounded`     | `boolean \| 'tiny' \| 'small' \| 'medium' \| 'full'` | - | Border radius                                     |
| `shadow`      | `'level1' \| 'level2' \| 'level3' \| 'level4'` | -       | Shadow elevation                                  |
| `overflow`    | `'hidden' \| 'scroll-y'`                       | -       | Overflow behavior                                 |
| `scroll`      | `boolean \| 'show'`                            | -       | Enable scrolling                                  |
| `cursor`      | `'pointer' \| 'grab' \| 'text'`                | -       | Cursor style                                      |
| `userSelect`  | `'none' \| 'text'`                             | -       | User selection behavior                           |
| `aspectRatio` | `'16:9' \| '4:3' \| '1:1'`                     | -       | Maintain aspect ratio                             |
| `tag`         | `string`                                       | `'div'` | HTML element to render                            |
| `debug`       | `boolean`                                      | `false` | Show debug outlines                               |

## Types

```typescript
type BoxSpace = 'xxs' | 'xs' | 's' | 'sm' | 'm' | 'l' | 'xl' | 'xxl' | 'xxxl' | 'none' | boolean;

type BoxSize = 'xs' | 's' | 'base' | 'm' | 'l' | 'xl' | 'xxl' | '256' | '512';

type BoxAlign = 'center' | 'start' | 'end' | 'spread' | 'space' | boolean;
```

## Supported Tags

The `tag` prop supports: `div`, `a`, `button`, `input`, `label`, `form`, `ol`, `ul`, `li`, `header`, `dl`, `dt`, `dd`, `nav`, `link` (React Router Link).

## Flex Helper

Use the `Flex` component to create flexible spacers:

```js
<SilkeBox gap="s">
  <SilkeButton label="Left" />
  <Flex />
  <SilkeButton label="Right" />
</SilkeBox>
```