Drawer

@cloud-ru/ds-drawer — Пакет выезжающих панелей — компоненты Drawer и DrawerCustom с едиными токенами позиции и ширины.

Пакет @cloud-ru/ds-drawer предоставляет два компонента для боковых/нижних панелей: готовую сборку Drawer с пресетной шапкой, телом и футером и низкоуровневый DrawerCustom для ручной композиции.

• Drawer — готовая панель с шапкой, прокручиваемым телом и опциональным футером. Покрывает 90% сценариев.
• DrawerCustom — низкоуровневая версия без предопределённой структуры: собирайте из DrawerCustom.Header, .Body, .Footer или собственной разметки.

Установка

pnpm add @cloud-ru/ds-drawer

import { Drawer, DrawerCustom, POSITION, WIDTH } from '@cloud-ru/ds-drawer'

Смотри также

• Modal — центрированное модальное окно для блокирующих подтверждений.
• Popover — всплывающий слой рядом с триггером.

Drawer

Панель, выезжающая со стороны экрана — пресетная шапка, прокручиваемое тело и опциональный футер.

Панель, выезжающая со стороны экрана — для дополнительного контекста, фильтров, форм и пошаговых сценариев. Drawer собирает шапку (медиа, заголовок, подзаголовок, back-button, слот после заголовка), прокручиваемое тело и опциональный футер. Для ручной композиции используйте DrawerCustom.

Когда использовать

• Форма, фильтры или детали, которые не помещаются в основной поток и требуют отдельного контекста.
• Пошаговый сценарий с кнопкой «назад» в шапке — возвращение между экранами без потери контекста.
• Нижний лист (bottom sheet) для компактных действий и подтверждений на мобильных устройствах.
• Стек из двух-трёх связанных панелей через nestedDrawer.

Когда не нужен: критическое подтверждение, блокирующее остальной интерфейс (берите Modal), всплывающий поповер рядом с элементом (Popover), тост-уведомление (не блокирует UI).

Примеры использования

Базовое использование

Контролируемое open/onClose, footer из ButtonGroup.

import { Button, ButtonGroup } from '@cloud-ru/ds-button';
import { Drawer } from '@cloud-ru/ds-drawer';
import { useState } from 'react';

export function Basic() {
  const [open, setOpen] = useState(false);
  const close = () => setOpen(false);

  return (
    <>
      <Button label='Открыть' appearance='primary' view='filled' onClick={() => setOpen(true)} />
      <Drawer
        open={open}
        position='right'
        onClose={close}
        title='Заголовок'
        subtitle='Короткое пояснение сценария'
        content='Основной контент тела. Сюда помещается форма, предупреждение или подробный текст.'
        footer={
          <ButtonGroup
            primaryAction={{ label: 'Продолжить', view: 'filled', onClick: close }}
            secondaryAction={{ label: 'Отмена', appearance: 'neutral', view: 'outline', onClick: close }}
          />
        }
      />
    </>
  );
}

Критическое действие

Critical primary, neutral outline secondary.

import { Button, ButtonGroup } from '@cloud-ru/ds-button';
import { Drawer } from '@cloud-ru/ds-drawer';
import { useState } from 'react';

export function WithFooter() {
  const [open, setOpen] = useState(false);
  const close = () => setOpen(false);

  return (
    <>
      <Button label='Удалить…' appearance='critical' view='outline' onClick={() => setOpen(true)} />
      <Drawer
        open={open}
        position='right'
        onClose={close}
        title='Удалить запись'
        subtitle='Действие необратимо.'
        content='После подтверждения запись и все её ссылки исчезнут из списка.'
        footer={
          <ButtonGroup
            primaryAction={{
              label: 'Удалить',
              appearance: 'critical',
              view: 'filled',
              onClick: close,
            }}
            secondaryAction={{
              label: 'Отмена',
              appearance: 'neutral',
              view: 'outline',
              onClick: close,
            }}
          />
        }
      />
    </>
  );
}

С медиа-слотом

media рендерится над шапкой на всю ширину панели.

import { Button } from '@cloud-ru/ds-button';
import { Drawer } from '@cloud-ru/ds-drawer';
import { useState } from 'react';

export function WithMedia() {
  const [open, setOpen] = useState(false);
  const close = () => setOpen(false);

  return (
    <>
      <Button label='Открыть онбординг' appearance='primary' view='filled' onClick={() => setOpen(true)} />
      <Drawer
        open={open}
        position='right'
        width='m'
        onClose={close}
        media={
          <div
            style={{
              height: 200,
              background: 'linear-gradient(135deg, rgb(102 126 234), rgb(118 75 162))',
            }}
          />
        }
        title='Добро пожаловать'
        subtitle='Кратко о том, что изменилось в этой версии.'
        content='Список ключевых улучшений и ссылки на подробности могут размещаться в теле.'
      />
    </>
  );
}

Bottom sheet

position="bottom" + heightAuto — высота по контенту.

import { Button } from '@cloud-ru/ds-button';
import { Drawer } from '@cloud-ru/ds-drawer';
import { useState } from 'react';

export function HeightAuto() {
  const [open, setOpen] = useState(false);
  const close = () => setOpen(false);

  return (
    <>
      <Button label='Открыть bottom sheet' appearance='primary' view='filled' onClick={() => setOpen(true)} />
      <Drawer
        open={open}
        position='bottom'
        heightAuto
        onClose={close}
        title='Bottom sheet'
        subtitle='Высота рассчитывается по контенту'
        content='Подходит для компактных подтверждений на мобильных устройствах.'
      />
    </>
  );
}

Вложенный Drawer

Родитель сдвигается влево при открытии дочернего.

import { Button } from '@cloud-ru/ds-button';
import { Drawer } from '@cloud-ru/ds-drawer';
import { useState } from 'react';

export function NestedDrawer() {
  const [outerOpen, setOuterOpen] = useState(false);
  const [innerOpen, setInnerOpen] = useState(false);

  const closeAll = () => {
    setInnerOpen(false);
    setOuterOpen(false);
  };

  return (
    <>
      <Button label='Открыть родительский' appearance='primary' view='filled' onClick={() => setOuterOpen(true)} />
      <Drawer
        open={outerOpen}
        position='right'
        width='m'
        onClose={closeAll}
        title='Родительский Drawer'
        subtitle='При открытии вложенного — родитель сдвигается влево.'
        content={
          <Button label='Открыть вложенный' appearance='primary' view='outline' onClick={() => setInnerOpen(true)} />
        }
        nestedDrawer={
          <Drawer
            open={innerOpen}
            position='right'
            width='s'
            onClose={() => setInnerOpen(false)}
            title='Вложенный Drawer'
            subtitle='Кнопка «назад» возвращает к родителю'
            onBackButtonClick={() => setInnerOpen(false)}
            content='Вложенный Drawer рендерится через проп nestedDrawer родителя.'
          />
        }
      />
    </>
  );
}

Props

DrawerProps

Related types

DrawerProps

• Position = "bottom" | "left" | "right" | "top"

• Width = "l" | "m" | "s"

Адаптивность

Drawer — адаптивный компонент с переключением поверхности (surface-swap). Раскладку он берёт из AdaptiveProvider (контекст @cloud-ru/ds-adaptive); публичный API единый для обеих платформ:

• desktop (по умолчанию) — панель, выезжающая со стороны экрана (left/right/top/bottom).
• mobile — контент рендерится в BottomSheet из @cloud-ru/ds-bottom-sheet (панель снизу со свайпом для закрытия).

Верстайте под desktop и поставьте один <AdaptiveProvider> в корне приложения — mobile-поверхность включается автоматически (desktop-first). Пропа layoutType у компонента нет: источник раскладки — только контекст.

Как форсировать платформу

Форс — только контекстом, не пропом:

• Поддерево — вложенный провайдер:

  import { AdaptiveProvider } from '@cloud-ru/ds-adaptive'
  
  <AdaptiveProvider layoutType='mobile'>
    <Drawer open={open} onClose={close} content={…} />
  </AdaptiveProvider>
  

• Отдельный компонент — withLayoutType (module-scope, сахар над провайдером):

  import { withLayoutType } from '@cloud-ru/ds-adaptive'
  import { Drawer } from '@cloud-ru/ds-drawer'
  
  const MobileDrawer = withLayoutType(Drawer, 'mobile')
  

Платформенные пропы

Часть пропов управляет геометрией desktop-панели и на mobile молча игнорируется (у BottomSheet своя поверхность снизу). Таблица синхронизирована с type-level JSDoc у DrawerProps.

Подробнее о модели адаптивности — Adaptive.

DrawerCustom

Низкоуровневая сборка Drawer — полный контроль над разметкой через Header / Body / Footer субкомпоненты.

DrawerCustom — низкоуровневая версия Drawer, которая не диктует структуру содержимого. Вы сами компонуете шапку, тело и футер из субкомпонентов DrawerCustom.Header, .Body, .Footer или собственной разметки.

Используйте DrawerCustom, когда стандартной шапки из Drawer недостаточно — например, нужна своя раскладка заголовка с несколькими действиями, кастомный футер с группами кнопок или нестандартный порядок секций.

Когда использовать

• Стандартная шапка / футер из Drawer не подходят — нужна своя разметка.
• Сложная раскладка нескольких секций внутри одной панели.
• Кастомные слоты (например, фиксированный поиск между шапкой и телом).

Во всех остальных случаях предпочтительнее Drawer — он дешевле в поддержке и даёт консистентные отступы.

Анатомия

Position

Сторона, с которой выезжает панель: right — стандартный side-panel (по умолчанию), left — для навигации и фильтров, top/bottom — для уведомлений и bottom-sheets на мобильных.

Width

Предустановленная ширина панели для position: left | right: s — для узких форм и фильтров, m — дефолт, l — для сложных форм и просмотрщиков. Также принимает число или строку CSS для точного контроля.

Примеры использования

Ручная композиция

Header + Body + Footer собираются вручную.

import { Button } from '@cloud-ru/ds-button';
import { DrawerCustom } from '@cloud-ru/ds-drawer';
import { useState } from 'react';

export function CustomComposition() {
  const [open, setOpen] = useState(false);
  const close = () => setOpen(false);

  return (
    <>
      <Button label='Открыть custom drawer' appearance='primary' view='filled' onClick={() => setOpen(true)} />
      <DrawerCustom open={open} position='right' width='s' onClose={close}>
        <DrawerCustom.Header title='Ручная композиция' subtitle='Header + Body + Footer собираются вручную.' />
        <DrawerCustom.Body
          content={
            <div style={{ padding: 24 }}>
              <p>Тело Drawer собирается из произвольной разметки.</p>
              <p>Скролл включается автоматически при большом содержимом.</p>
            </div>
          }
        />
        <DrawerCustom.Footer>
          <div style={{ display: 'flex', gap: 8, justifyContent: 'flex-end' }}>
            <Button label='Закрыть' appearance='neutral' view='outline' onClick={close} />
            <Button label='Подтвердить' appearance='primary' view='filled' onClick={close} />
          </div>
        </DrawerCustom.Footer>
      </DrawerCustom>
    </>
  );
}

Props

DrawerCustomProps

Related types

DrawerCustomProps

• Position = "bottom" | "left" | "right" | "top"

• ResizableMax = number | "full"

• Width = "l" | "m" | "s"