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

<Meta isTemplate />

# Layer

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

{/* <!-- 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)
- [With Background](#with-background)
- [Setting a custom level](#setting-a-custom-level)
- [Get the current layer](#get-the-current-layer)
- [Component API](#component-api)
  - [Layer as](#layer-as)
- [Feedback](#feedback)

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

## Overview

The `Layer` component is used to render components on different layers. Each
layer has a specific set of token values associated with it. You can use these
tokens directly, or use contextual tokens from our styles package like `$layer`
or `$field`.

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

The `Layer` component accepts `children` as a prop. Each child of a `Layer`
component is rendered using the layer tokens at that layer. `Layer` components
can be nested indefinitely, but the token sets typically end after 3 layers.

```jsx
<ChildComponent />
<Layer>
  <ChildComponent />
  <Layer>
    <ChildComponent />
  </Layer>
</Layer>
```

## With Background

The `Layer` component updates layer tokens at each level and theme. When you add the
`withBackground` prop, it automatically sets a background color using the
`$layer-background` token. Without it, you can manually set the background with
`background-color: $layer-background`.

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

## Setting a custom level

You can override the `level` of a `Layer` if you would like to change the
presentation of a layer in your application. This is particularly helpful if you
would like to reset the `Layer` level back to `0` or if you want to make sure a
part of a page always renders in a certain level.

To do this, you can use the `level` prop:

```jsx
<Layer>
  <ChildComponent />
  <Layer level={0}>
    <ChildComponent />
  </Layer>
</Layer>
```

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

## Get the current layer

If you are building a component and would like to know what layer the component
resides within, you can use the `useLayer` hook.

This hook returns an object with the current `level` of the layer:

```jsx
function ExampleComponent() {
  const { level } = useLayer();

  // ...
}
```

If the structure of `Layer` components in your app change, the hook will
automatically update with the new `level`.

The `level` value can be one of: `0`, `1`, or `2` and will correspond to the
level of the current layer. This value mirrors the `level` prop on the `Layer`
component.

## Component API

<ArgTypes />

### Layer as

You can configure the base element rendered by `Layer` using the `as` prop. For
example, if you would like the `Layer` component to render as a `section` you
could write the following:

```jsx
<Layer as="section">
  <ChildComponent />
</Layer>
```

Similarly, you can provide any custom component to the `as` prop which the
`Layer` component will use.

## 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/Layer/Layer.mdx).
