import { ArgTypes, Meta, Canvas} from '@storybook/addon-docs/blocks';
import * as LayoutStories from './Layout.stories';
import { stackblitzPrefillConfig } from '../../../previewer/codePreviewer';

<Meta isTemplate />

# Layout

[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Layout)

{/* <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> */}

## Table of Contents

- [Overview](#overview)
  - [LayoutConstraint](#layoutconstraint)
- [Component API](#component-api)
- [Feedback](#feedback)

{/* <!-- END doctoc generated TOC please keep comment here to allow auto update --> */}

## Overview

The `Layout` component provides a way to set layout contexts for specific parts
of a web application. It uses Carbon's experimental `layout` sass module
(exported from `@carbon/styles`) to control layout-related settings like size
and density of all components within a layout context.

All children components that support it will react to the `size` and `density`
you pass in the `Layout` props. Note that not all components support the entire
spectrum of options available. In these cases, a component will typically cap
out at the maximum or minimum size it supports in order to still best suit the
layout context's intent.

If a component is outside a layout context or `props.size` / `props.density`
isn't set, it will fall back to its default rendering.

Components that are explicitly passed a `size` to are unaffected by the layout
context. Example:

```jsx
<div>
  {/* This text input is always lg */}
  <TextInput size="lg" />

  {/* This text input will render with its default size (md) */}
  <TextInput />

  <Layout size="sm">
    {/* This text input will still be lg */}
    <TextInput size="lg" />

    {/* This text input will be sm */}
    <TextInput />
  </Layout>
</div>
```

<Canvas
  of={LayoutStories.Default}
  additionalActions={[
    {
      title: 'Open in Stackblitz',
      onClick: () => stackblitzPrefillConfig(LayoutStories.Default),
    },
  ]}
/>

### LayoutConstraint

In order to apply specific constraints to children components that might differ
from their own preference, the `<LayoutConstraint>` utility component can be
used.

An example of this use case is the icon-only content switcher. It uses
`IconButton` under the hood which supports all sizes and defaults to `lg`. The
`ContentSwitcher` though only supports `sm`->`lg` and defaults to `md`.

```jsx
<div>
  <LayoutConstraint size={{ default: 'md', min: 'sm', max: 'lg' }}>
    {/* IconButton is now locked to the sizes sm->lg and defaults to md */}
    <IconButton … />
  </LayoutConstraint>
</div>
```

The constraints for a group (`size` and `density`) must be passed as an object
with any of these keys:

- `min`
- `default`
- `max`

Example: `size={{ min: 'sm', max: 'lg }}`<br /> Example:
`density={{ default: 'condensed' }}`

## Component API

<ArgTypes />

## Feedback

Help us improve this component by providing feedback, asking questions on Slack,
or updating this file on
[GitHub](https://github.com/carbon-design-system/carbon/edit/main/packages/react/src/components/Layout/Layout.mdx).
