@cloud-ru/ds-bottom-sheet 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/LICENSE +201 -0
  3. package/README.md +997 -0
  4. package/dist/cjs/components/BottomSheet/BottomSheet.d.ts +3 -0
  5. package/dist/cjs/components/BottomSheet/BottomSheet.js +39 -0
  6. package/dist/cjs/components/BottomSheet/index.d.ts +1 -0
  7. package/dist/cjs/components/BottomSheet/index.js +17 -0
  8. package/dist/cjs/components/BottomSheet/styles.module.css +27 -0
  9. package/dist/cjs/components/BottomSheetCustom/BottomSheetCustom.d.ts +19 -0
  10. package/dist/cjs/components/BottomSheetCustom/BottomSheetCustom.js +121 -0
  11. package/dist/cjs/components/BottomSheetCustom/constants.d.ts +30 -0
  12. package/dist/cjs/components/BottomSheetCustom/constants.js +33 -0
  13. package/dist/cjs/components/BottomSheetCustom/hooks/index.d.ts +3 -0
  14. package/dist/cjs/components/BottomSheetCustom/hooks/index.js +19 -0
  15. package/dist/cjs/components/BottomSheetCustom/hooks/useDragEngine.d.ts +44 -0
  16. package/dist/cjs/components/BottomSheetCustom/hooks/useDragEngine.js +312 -0
  17. package/dist/cjs/components/BottomSheetCustom/hooks/useFocusTrap.d.ts +7 -0
  18. package/dist/cjs/components/BottomSheetCustom/hooks/useFocusTrap.js +77 -0
  19. package/dist/cjs/components/BottomSheetCustom/hooks/useTransitionPhase.d.ts +22 -0
  20. package/dist/cjs/components/BottomSheetCustom/hooks/useTransitionPhase.js +51 -0
  21. package/dist/cjs/components/BottomSheetCustom/index.d.ts +1 -0
  22. package/dist/cjs/components/BottomSheetCustom/index.js +17 -0
  23. package/dist/cjs/components/BottomSheetCustom/styles.module.css +98 -0
  24. package/dist/cjs/components/BottomSheetCustom/utils/scroll.d.ts +17 -0
  25. package/dist/cjs/components/BottomSheetCustom/utils/scroll.js +39 -0
  26. package/dist/cjs/components/BottomSheetCustom/utils/snapPoints.d.ts +38 -0
  27. package/dist/cjs/components/BottomSheetCustom/utils/snapPoints.js +102 -0
  28. package/dist/cjs/components/index.d.ts +2 -0
  29. package/dist/cjs/components/index.js +18 -0
  30. package/dist/cjs/constants.d.ts +11 -0
  31. package/dist/cjs/constants.js +19 -0
  32. package/dist/cjs/helperComponents/Handle/Handle.d.ts +2 -0
  33. package/dist/cjs/helperComponents/Handle/Handle.js +13 -0
  34. package/dist/cjs/helperComponents/Handle/index.d.ts +1 -0
  35. package/dist/cjs/helperComponents/Handle/index.js +17 -0
  36. package/dist/cjs/helperComponents/Handle/styles.module.css +18 -0
  37. package/dist/cjs/helperComponents/index.d.ts +1 -0
  38. package/dist/cjs/helperComponents/index.js +17 -0
  39. package/dist/cjs/index.d.ts +9 -0
  40. package/dist/cjs/index.js +39 -0
  41. package/dist/cjs/package.json +3 -0
  42. package/dist/cjs/style.css +143 -0
  43. package/dist/cjs/types.d.ts +172 -0
  44. package/dist/cjs/types.js +2 -0
  45. package/dist/esm/components/BottomSheet/BottomSheet.d.ts +3 -0
  46. package/dist/esm/components/BottomSheet/BottomSheet.js +33 -0
  47. package/dist/esm/components/BottomSheet/index.d.ts +1 -0
  48. package/dist/esm/components/BottomSheet/index.js +1 -0
  49. package/dist/esm/components/BottomSheet/styles.module.css +27 -0
  50. package/dist/esm/components/BottomSheetCustom/BottomSheetCustom.d.ts +19 -0
  51. package/dist/esm/components/BottomSheetCustom/BottomSheetCustom.js +115 -0
  52. package/dist/esm/components/BottomSheetCustom/constants.d.ts +30 -0
  53. package/dist/esm/components/BottomSheetCustom/constants.js +30 -0
  54. package/dist/esm/components/BottomSheetCustom/hooks/index.d.ts +3 -0
  55. package/dist/esm/components/BottomSheetCustom/hooks/index.js +3 -0
  56. package/dist/esm/components/BottomSheetCustom/hooks/useDragEngine.d.ts +44 -0
  57. package/dist/esm/components/BottomSheetCustom/hooks/useDragEngine.js +309 -0
  58. package/dist/esm/components/BottomSheetCustom/hooks/useFocusTrap.d.ts +7 -0
  59. package/dist/esm/components/BottomSheetCustom/hooks/useFocusTrap.js +74 -0
  60. package/dist/esm/components/BottomSheetCustom/hooks/useTransitionPhase.d.ts +22 -0
  61. package/dist/esm/components/BottomSheetCustom/hooks/useTransitionPhase.js +48 -0
  62. package/dist/esm/components/BottomSheetCustom/index.d.ts +1 -0
  63. package/dist/esm/components/BottomSheetCustom/index.js +1 -0
  64. package/dist/esm/components/BottomSheetCustom/styles.module.css +98 -0
  65. package/dist/esm/components/BottomSheetCustom/utils/scroll.d.ts +17 -0
  66. package/dist/esm/components/BottomSheetCustom/utils/scroll.js +34 -0
  67. package/dist/esm/components/BottomSheetCustom/utils/snapPoints.d.ts +38 -0
  68. package/dist/esm/components/BottomSheetCustom/utils/snapPoints.js +96 -0
  69. package/dist/esm/components/index.d.ts +2 -0
  70. package/dist/esm/components/index.js +2 -0
  71. package/dist/esm/constants.d.ts +11 -0
  72. package/dist/esm/constants.js +13 -0
  73. package/dist/esm/helperComponents/Handle/Handle.d.ts +2 -0
  74. package/dist/esm/helperComponents/Handle/Handle.js +7 -0
  75. package/dist/esm/helperComponents/Handle/index.d.ts +1 -0
  76. package/dist/esm/helperComponents/Handle/index.js +1 -0
  77. package/dist/esm/helperComponents/Handle/styles.module.css +18 -0
  78. package/dist/esm/helperComponents/index.d.ts +1 -0
  79. package/dist/esm/helperComponents/index.js +1 -0
  80. package/dist/esm/index.d.ts +9 -0
  81. package/dist/esm/index.js +13 -0
  82. package/dist/esm/style.css +143 -0
  83. package/dist/esm/types.d.ts +172 -0
  84. package/dist/esm/types.js +1 -0
  85. package/dist/tsconfig.cjs.tsbuildinfo +1 -0
  86. package/dist/tsconfig.esm.tsbuildinfo +1 -0
  87. package/package.json +47 -0
  88. package/src/components/BottomSheet/BottomSheet.tsx +116 -0
  89. package/src/components/BottomSheet/index.ts +1 -0
  90. package/src/components/BottomSheet/styles.module.scss +38 -0
  91. package/src/components/BottomSheetCustom/BottomSheetCustom.tsx +221 -0
  92. package/src/components/BottomSheetCustom/constants.ts +33 -0
  93. package/src/components/BottomSheetCustom/hooks/index.ts +3 -0
  94. package/src/components/BottomSheetCustom/hooks/useDragEngine.ts +373 -0
  95. package/src/components/BottomSheetCustom/hooks/useFocusTrap.ts +80 -0
  96. package/src/components/BottomSheetCustom/hooks/useTransitionPhase.ts +52 -0
  97. package/src/components/BottomSheetCustom/index.ts +1 -0
  98. package/src/components/BottomSheetCustom/styles.module.scss +146 -0
  99. package/src/components/BottomSheetCustom/utils/scroll.ts +39 -0
  100. package/src/components/BottomSheetCustom/utils/snapPoints.ts +109 -0
  101. package/src/components/index.ts +2 -0
  102. package/src/constants.ts +14 -0
  103. package/src/helperComponents/Handle/Handle.tsx +11 -0
  104. package/src/helperComponents/Handle/index.ts +1 -0
  105. package/src/helperComponents/Handle/styles.module.scss +26 -0
  106. package/src/helperComponents/index.ts +1 -0
  107. package/src/index.ts +30 -0
  108. package/src/types.ts +185 -0
package/README.md ADDED
@@ -0,0 +1,997 @@
1
+ # BottomSheet
2
+
3
+ `@cloud-ru/ds-bottom-sheet` — Mobile-first overlay-контейнер с drag-handle и swipe-down для диалогов, выпадающих списков и фильтров. Поддерживает snap-points (раскрытие на половину → full).
4
+
5
+ Mobile-first bottom-sheet — overlay-контейнер, выезжающий снизу. Используется как базовый layer для диалогов, выпадающих списков, фильтров и любых полу-полно-экранных UI на мобильных устройствах.
6
+
7
+ ## Когда использовать
8
+
9
+ - Полу-полно-экранный диалог на мобильном устройстве.
10
+ - Action-sheet («Выбрать действие»: фото, удалить, отменить).
11
+ - Multi-step flow с back-кнопкой в шапке.
12
+ - Контейнер для выпадающего списка / фильтров на мобильном.
13
+
14
+ ## Анатомия
15
+
16
+ ### Handle
17
+ Drag-индикатор 32×4px сверху — визуальная подсказка для swipe-down. Показывается, когда включён свайп; при `swipeEnabled={false}` его нет (нет жеста — нет намёка на него).
18
+
19
+ ### Backdrop (default `showBackdrop=true`)
20
+ Полупрозрачная подложка. Click по backdrop'у вызывает `onClose`. При `showBackdrop={false}` фон не затемняется и click-outside не закрывает sheet.
21
+
22
+ ### Non-modal (default `lockScroll=true`)
23
+ По умолчанию sheet — модальный: фон затемнён и заблокирован для скролла. Для non-modal сценария (sheet поверх контента, с которым продолжают работать) передайте `lockScroll={false}` (страница под sheet'ом скроллится) — обычно вместе с `showBackdrop={false}`.
24
+
25
+ ### Header
26
+ - `title` — заголовок.
27
+ - `slotAfterTitle` — slot справа от title (QuestionTooltip, badge).
28
+ - `onBackButtonClick` — авто-рендерит back-кнопку слева.
29
+ - `actionButton` — кастомный slot справа.
30
+ - `subtitle` — текстовая строка-подзаголовок под title.
31
+ - `slotSecondTitle` — slot под подзаголовком (SearchBar / SegmentControl).
32
+
33
+ ### Media
34
+ - `kind='image'` — full-bleed image, min-height 184px; прижато к шапке (убирает верхний отступ контент-блока). Горизонтальные паддинги body не меняются — для edge-to-edge body передайте `bodyPadding={false}`.
35
+ - `kind='icon'` — иконка с `padding-top: 24px`.
36
+ - Произвольный `ReactNode` — если нужен свой media-блок (видео, карта, кастомная разметка).
37
+
38
+ ### Body padding (default `bodyPadding=true`)
39
+ Горизонтальные паддинги тела. При `bodyPadding={false}` контент идёт во всю ширину (edge-to-edge) —
40
+ для карт, изображений, списков без отступов. Соответствует Figma-оси `padding=false`.
41
+
42
+ ### Footer actions (default orientation `horizontal`)
43
+ Высокоуровневый footer собирается из объектов пропсов `Button` — кнопки рендерятся через `ButtonGroup`:
44
+
45
+ - `approveButton` — основное действие (по умолчанию `view='filled'`, `appearance='primary'`).
46
+ - `cancelButton` — отмена (по умолчанию `view='outline'`, `appearance='neutral'`).
47
+ - `additionalButton` — третье действие (по умолчанию `view='simple'`, `appearance='neutral'`).
48
+ - `disclaimer` — мелкий центрированный текст под кнопками.
49
+
50
+ `footerActionsOrientation` управляет раскладкой **пары** cancel/confirm:
51
+
52
+ - `'horizontal'` — ряд через space-between (secondary слева, primary справа), ширина по контенту.
53
+ Дефолт — точное соответствие Figma `bottomBar.buttonGroup`.
54
+ - `'vertical'` — кнопки в столбик, full-width.
55
+
56
+ Одна кнопка всегда рендерится full-width (одиночный CTA); три кнопки не помещаются в ряд на
57
+ mobile-вьюпорте и всегда идут в столбик.
58
+
59
+ Для произвольной разметки — `footer: ReactNode` (имеет приоритет над `approveButton` / `cancelButton`
60
+ / `additionalButton` / `disclaimer`).
61
+
62
+ ### Dividers (default `withDividers=true`)
63
+ Тонкие линии между topBar↔body и body↔footer. Разграничивают закреплённые шапку и подвал от
64
+ прокручиваемого под ними содержимого. Передайте `withDividers={false}`, чтобы убрать обе линии.
65
+
66
+ ### SafeArea (default `safeArea=true`)
67
+ Блоки сверху/снизу, резервирующие место под iOS notch / home-indicator и Android nav-bar через
68
+ `env(safe-area-inset-*)` (с 32px-фолбэком для embedded webview, который не отдаёт inset'ы). Figma-артборд
69
+ эти блоки скрывает; на реальном устройстве они нужны, чтобы футер не уходил под home-indicator. Передайте
70
+ `safeArea={false}`, если рамку safe-area обеспечивает окружение (например, нативная оболочка webview).
71
+
72
+ ### Snap points (default `undefined` → height auto)
73
+ По дефолту sheet `height: auto` (один snap по высоте контента). Когда задан `snapPoints`-массив, sheet поддерживает несколько фиксированных позиций (iOS-detents-аналог):
74
+
75
+ ```tsx
76
+ <BottomSheet
77
+ open={open}
78
+ onClose={onClose}
79
+ snapPoints={[0.5, 1]}
80
+ defaultSnapIndex={0}
81
+ title='Меню'
82
+ content={<List />}
83
+ />
84
+ ```
85
+
86
+ **Формат** — `number ∈ (0, 1] | 'Npx' | 'N%' | 'Ndvh' | 'Nsvh' | 'Nlvh' | 'fit-content'`. Порядок массива — от меньшей позиции к большей. Drag вверх → следующий snap; drag вниз ниже первого snap'а — закрытие.
87
+
88
+ - **Controlled snap** — задайте `snapIndex` + `onSnapIndexChange`. В этом режиме swipe вызывает `onSnapIndexChange`, но позицию не двигает: потребитель сам передаёт новое значение обратно.
89
+ - **`swipeEnabled` (default `true`)** — `false` отключает swipe-жесты; переключить snap можно только программно через `snapIndex`.
90
+ - **`closeOnPopstate` (default `true`)** — закрытие по browser-back (`popstate`). Полезно на mobile, чтобы аппаратная кнопка «назад» закрывала sheet вместо ухода со страницы.
91
+
92
+ ## Установка
93
+
94
+ ```bash
95
+ pnpm add @cloud-ru/ds-bottom-sheet
96
+ ```
97
+
98
+ ```ts
99
+ import { BottomSheet, BottomSheetCustom, TEST_IDS } from '@cloud-ru/ds-bottom-sheet'
100
+ ```
101
+
102
+ ## Примеры использования
103
+
104
+ ### Базовый сценарий
105
+
106
+ title + content + одиночная full-width кнопка
107
+
108
+ ```tsx
109
+ import { BottomSheet } from '@cloud-ru/ds-bottom-sheet';
110
+ import { Button } from '@cloud-ru/ds-button';
111
+ import { useState } from 'react';
112
+
113
+ import { MobilePreview } from '../MobilePreview';
114
+
115
+ export function Basic() {
116
+ const [open, setOpen] = useState(false);
117
+
118
+ return (
119
+ <MobilePreview>
120
+ <Button label='Открыть BottomSheet' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
121
+ <BottomSheet
122
+ open={open}
123
+ onClose={() => setOpen(false)}
124
+ title='Bottom-sheet headline'
125
+ content={
126
+ <p>
127
+ Bottom-sheet — мобильный overlay-контейнер, выезжающий снизу. Используйте его как базовый layer для
128
+ диалогов, выпадающих списков, фильтров и любых полу-полно-экранных UI.
129
+ </p>
130
+ }
131
+ approveButton={{ label: 'Подтвердить', onClick: () => setOpen(false) }}
132
+ />
133
+ </MobilePreview>
134
+ );
135
+ }
136
+ ```
137
+
138
+ ### Кнопки футера + дисклеймер
139
+
140
+ approve + cancel + additional + disclaimer — три действия собираются в вертикальный full-width ButtonGroup
141
+
142
+ ```tsx
143
+ import { BottomSheet } from '@cloud-ru/ds-bottom-sheet';
144
+ import { Button } from '@cloud-ru/ds-button';
145
+ import { useState } from 'react';
146
+
147
+ import { MobilePreview } from '../MobilePreview';
148
+
149
+ export function FooterActions() {
150
+ const [open, setOpen] = useState(false);
151
+
152
+ return (
153
+ <MobilePreview>
154
+ <Button label='Удалить ресурс' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
155
+ <BottomSheet
156
+ open={open}
157
+ onClose={() => setOpen(false)}
158
+ title='Удалить ресурс?'
159
+ content={<p>Действие необратимо. Все связанные данные будут удалены без возможности восстановления.</p>}
160
+ // Три действия: не помещаются в ряд на mobile-вьюпорте, поэтому собираются
161
+ // в вертикальный full-width ButtonGroup (primary сверху). Для пары cancel/confirm футер
162
+ // по умолчанию горизонтальный (space-between) — управляется `footerActionsOrientation`.
163
+ approveButton={{ label: 'Удалить', appearance: 'critical', onClick: () => setOpen(false) }}
164
+ cancelButton={{ label: 'Отмена', onClick: () => setOpen(false) }}
165
+ additionalButton={{ label: 'Подробнее', onClick: () => undefined }}
166
+ />
167
+ </MobilePreview>
168
+ );
169
+ }
170
+ ```
171
+
172
+ ### С media-блоком
173
+
174
+ kind=image — full-bleed картинка над контентом
175
+
176
+ ```tsx
177
+ import { BottomSheet, MEDIA_KIND } from '@cloud-ru/ds-bottom-sheet';
178
+ import { Button } from '@cloud-ru/ds-button';
179
+ import { useState } from 'react';
180
+
181
+ import { MobilePreview } from '../MobilePreview';
182
+
183
+ export function WithMedia() {
184
+ const [open, setOpen] = useState(false);
185
+
186
+ return (
187
+ <MobilePreview>
188
+ <Button label='Открыть с media' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
189
+ <BottomSheet
190
+ open={open}
191
+ onClose={() => setOpen(false)}
192
+ title='Bottom-sheet with media'
193
+ media={{
194
+ src: 'https://placehold.co/360x184?text=Media',
195
+ alt: 'Media',
196
+ kind: MEDIA_KIND.Image,
197
+ }}
198
+ content={<p>Media-блок full-bleed, прижат к шапке. bodyPadding управляет паддингами body отдельно.</p>}
199
+ approveButton={{ label: 'Подтвердить', onClick: () => setOpen(false) }}
200
+ />
201
+ </MobilePreview>
202
+ );
203
+ }
204
+ ```
205
+
206
+ ### С subtitle
207
+
208
+ SearchBar / SegmentControl под строкой заголовка
209
+
210
+ ```tsx
211
+ import { BottomSheet } from '@cloud-ru/ds-bottom-sheet';
212
+ import { Button } from '@cloud-ru/ds-button';
213
+ import { useState } from 'react';
214
+
215
+ import { MobilePreview } from '../MobilePreview';
216
+
217
+ export function WithSubtitle() {
218
+ const [open, setOpen] = useState(false);
219
+
220
+ return (
221
+ <MobilePreview>
222
+ <Button label='Открыть с subtitle' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
223
+ <BottomSheet
224
+ open={open}
225
+ onClose={() => setOpen(false)}
226
+ title='Filters'
227
+ // В продакшене сюда — `@cloud-ru/ds-search::SearchBar` или `@cloud-ru/ds-segment-control::SegmentControl`.
228
+ slotSecondTitle={<div>SearchBar / SegmentControl placeholder</div>}
229
+ content={<p>Subtitle располагается под заголовком — sticky-зона для поиска/фильтров.</p>}
230
+ approveButton={{ label: 'Применить', onClick: () => setOpen(false) }}
231
+ />
232
+ </MobilePreview>
233
+ );
234
+ }
235
+ ```
236
+
237
+ ### С back- и action-кнопкой
238
+
239
+ onBackButtonClick авто-рендерит back-кнопку; actionButton — справа в шапке
240
+
241
+ ```tsx
242
+ import { BottomSheet } from '@cloud-ru/ds-bottom-sheet';
243
+ import { Button } from '@cloud-ru/ds-button';
244
+ import { Dropdown } from '@cloud-ru/ds-dropdown';
245
+ import { KebabSVG } from '@cloud-ru/ds-icons/interface/system';
246
+ import { useState } from 'react';
247
+
248
+ import { MobilePreview } from '../MobilePreview';
249
+ import styles from './styles.module.scss';
250
+
251
+ const MENU_ACTIONS = ['Поделиться', 'Дублировать', 'Удалить'];
252
+
253
+ /**
254
+ * `actionButton` — слот в правом верхнем углу header'а. Здесь это kebab-кнопка, открывающая
255
+ * Dropdown со списком действий; выбранное действие отражается в теле sheet'а. Back-button слева
256
+ * появляется автоматически по `onBackButtonClick`.
257
+ */
258
+ export function WithActionButton() {
259
+ const [open, setOpen] = useState(false);
260
+ const [menuOpen, setMenuOpen] = useState(false);
261
+ const [lastAction, setLastAction] = useState<string | null>(null);
262
+
263
+ return (
264
+ <MobilePreview>
265
+ <Button label='Открыть с действиями' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
266
+ <BottomSheet
267
+ open={open}
268
+ onClose={() => setOpen(false)}
269
+ title='Detail view'
270
+ onBackButtonClick={() => setOpen(false)}
271
+ actionButton={
272
+ // TODO: заменить на дроплист
273
+ <Dropdown
274
+ open={menuOpen}
275
+ onOpenChange={setMenuOpen}
276
+ placement='bottom-end'
277
+ content={
278
+ <div className={styles.menu}>
279
+ {MENU_ACTIONS.map(action => (
280
+ <button
281
+ key={action}
282
+ type='button'
283
+ className={styles.menuItem}
284
+ onClick={() => {
285
+ setLastAction(action);
286
+ setMenuOpen(false);
287
+ }}
288
+ >
289
+ {action}
290
+ </button>
291
+ ))}
292
+ </div>
293
+ }
294
+ >
295
+ <Button view='function' appearance='neutral' icon={<KebabSVG />} aria-label='Действия' />
296
+ </Dropdown>
297
+ }
298
+ content={
299
+ <p>
300
+ Кнопка-меню в правом верхнем углу открывает список действий.
301
+ {lastAction ? ` Выбрано: «${lastAction}».` : ''}
302
+ </p>
303
+ }
304
+ approveButton={{ label: 'Готово', onClick: () => setOpen(false) }}
305
+ />
306
+ </MobilePreview>
307
+ );
308
+ }
309
+ ```
310
+
311
+ ### Scrollable + dividers
312
+
313
+ Длинный контент: тонкие линии разделяют header / footer от плывущего тела
314
+
315
+ ```tsx
316
+ import { BottomSheet } from '@cloud-ru/ds-bottom-sheet';
317
+ import { Button } from '@cloud-ru/ds-button';
318
+ import { useState } from 'react';
319
+
320
+ import { MobilePreview } from '../MobilePreview';
321
+
322
+ export function Scrollable() {
323
+ const [open, setOpen] = useState(false);
324
+
325
+ return (
326
+ <MobilePreview>
327
+ <Button label='Открыть scrollable' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
328
+ <BottomSheet
329
+ open={open}
330
+ onClose={() => setOpen(false)}
331
+ title='Scrollable content'
332
+ withDividers
333
+ content={
334
+ <div>
335
+ {Array.from({ length: 30 }).map((_, i) => (
336
+ <p key={i}>Параграф {i + 1}. Body скроллится, header и footer остаются sticky.</p>
337
+ ))}
338
+ </div>
339
+ }
340
+ approveButton={{ label: 'Закрыть', onClick: () => setOpen(false) }}
341
+ />
342
+ </MobilePreview>
343
+ );
344
+ }
345
+ ```
346
+
347
+ ### Expandable: половина → full
348
+
349
+ snapPoints={[0.5, 1]} — drag вверх раскрывает
350
+
351
+ ```tsx
352
+ import { BottomSheet } from '@cloud-ru/ds-bottom-sheet';
353
+ import { Button } from '@cloud-ru/ds-button';
354
+ import { useState } from 'react';
355
+
356
+ import { MobilePreview } from '../MobilePreview';
357
+
358
+ /**
359
+ * Expandable bottom-sheet: открывается на первом snap'е, drag за handle вверх раскрывает на следующий,
360
+ * drag вниз ниже первого — закрывает.
361
+ *
362
+ * В демо-рамке телефона snap-точки заданы в пикселях под её высоту, чтобы «половина» и «полный»
363
+ * визуально различались. На реальном устройстве для тех же состояний используйте доли вьюпорта —
364
+ * `snapPoints={[0.5, 1]}` (резолвятся относительно высоты вьюпорта, а не контейнера).
365
+ */
366
+ export function Expandable() {
367
+ const [open, setOpen] = useState(false);
368
+
369
+ return (
370
+ <MobilePreview>
371
+ <Button label='Открыть Expandable' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
372
+ <BottomSheet
373
+ open={open}
374
+ onClose={() => setOpen(false)}
375
+ snapPoints={['220px', '430px']}
376
+ defaultSnapIndex={0}
377
+ title='Expandable bottom-sheet'
378
+ content={
379
+ <div>
380
+ {Array.from({ length: 20 }).map((_, i) => (
381
+ <p key={i}>Параграф {i + 1}. Контент для демонстрации snap-points поведения.</p>
382
+ ))}
383
+ </div>
384
+ }
385
+ approveButton={{ label: 'Закрыть', onClick: () => setOpen(false) }}
386
+ />
387
+ </MobilePreview>
388
+ );
389
+ }
390
+ ```
391
+
392
+ ### Фильтры
393
+
394
+ Back-кнопка + подсказка, chips в subtitle, SegmentControl и переключатели, «Применить / Сбросить»
395
+
396
+ ```tsx
397
+ import { BottomSheet } from '@cloud-ru/ds-bottom-sheet';
398
+ import { Button } from '@cloud-ru/ds-button';
399
+ import { SegmentControl } from '@cloud-ru/ds-segment-control';
400
+ import { Tag } from '@cloud-ru/ds-tag';
401
+ import { Switch } from '@cloud-ru/ds-toggles';
402
+ import { QuestionTooltip } from '@cloud-ru/ds-tooltip';
403
+ import { useState } from 'react';
404
+
405
+ import { MobilePreview } from '../MobilePreview';
406
+ import styles from './styles.module.scss';
407
+
408
+ const PERIOD_ITEMS = [
409
+ { value: 'day', label: 'День' },
410
+ { value: 'week', label: 'Неделя' },
411
+ { value: 'month', label: 'Месяц' },
412
+ ];
413
+
414
+ /**
415
+ * Реальный сценарий «Фильтры»: back-кнопка + заголовок с подсказкой, sticky-зона chips
416
+ * над контентом (subtitle), форма с SegmentControl и переключателями в теле и пара
417
+ * действий «Применить / Сбросить» в футере.
418
+ */
419
+ export function Filters() {
420
+ const [open, setOpen] = useState(false);
421
+ const [period, setPeriod] = useState('week');
422
+ const [onlyFavourite, setOnlyFavourite] = useState(true);
423
+ const [withArchived, setWithArchived] = useState(false);
424
+ const [chips, setChips] = useState(['Активные', 'За месяц']);
425
+
426
+ return (
427
+ <MobilePreview>
428
+ <Button label='Открыть фильтры' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
429
+ <BottomSheet
430
+ open={open}
431
+ onClose={() => setOpen(false)}
432
+ title='Фильтры'
433
+ onBackButtonClick={() => setOpen(false)}
434
+ slotAfterTitle={<QuestionTooltip tip='Настройте параметры выборки' />}
435
+ slotSecondTitle={
436
+ <div className={styles.chipRow}>
437
+ {chips.map(chip => (
438
+ <Tag
439
+ key={chip}
440
+ label={chip}
441
+ appearance='primary'
442
+ size='s'
443
+ onDelete={() => setChips(prev => prev.filter(c => c !== chip))}
444
+ />
445
+ ))}
446
+ </div>
447
+ }
448
+ content={
449
+ <div className={styles.column}>
450
+ <SegmentControl items={PERIOD_ITEMS} value={period} onChange={setPeriod} width='full' />
451
+ <div className={styles.switchRow}>
452
+ <span>Только избранное</span>
453
+ <Switch checked={onlyFavourite} onChange={setOnlyFavourite} />
454
+ </div>
455
+ <div className={styles.switchRow}>
456
+ <span>Показывать архив</span>
457
+ <Switch checked={withArchived} onChange={setWithArchived} />
458
+ </div>
459
+ </div>
460
+ }
461
+ approveButton={{ label: 'Применить', onClick: () => setOpen(false) }}
462
+ cancelButton={{
463
+ label: 'Сбросить',
464
+ onClick: () => {
465
+ setPeriod('week');
466
+ setOnlyFavourite(false);
467
+ setWithArchived(false);
468
+ setChips([]);
469
+ },
470
+ }}
471
+ />
472
+ </MobilePreview>
473
+ );
474
+ }
475
+ ```
476
+
477
+ ### Выбор из списка
478
+
479
+ Чекбоксы с «Выбрать все» (indeterminate) и счётчиком выбранного в действии
480
+
481
+ ```tsx
482
+ import { BottomSheet } from '@cloud-ru/ds-bottom-sheet';
483
+ import { Button } from '@cloud-ru/ds-button';
484
+ import { Checkbox } from '@cloud-ru/ds-toggles';
485
+ import { useState } from 'react';
486
+
487
+ import { MobilePreview } from '../MobilePreview';
488
+ import styles from './styles.module.scss';
489
+
490
+ const OPTIONS = [
491
+ { id: 'compute', label: 'Compute' },
492
+ { id: 'storage', label: 'Object Storage' },
493
+ { id: 'network', label: 'Networking' },
494
+ { id: 'database', label: 'Managed Databases' },
495
+ ];
496
+
497
+ /**
498
+ * Сценарий выбора из списка: заголовок, чекбокс «Выбрать все» c indeterminate-состоянием
499
+ * для частичного выбора, список строк-опций и действие «Готово» в футере.
500
+ */
501
+ export function SelectionList() {
502
+ const [open, setOpen] = useState(false);
503
+ const [selected, setSelected] = useState<string[]>(['compute']);
504
+
505
+ const allChecked = selected.length === OPTIONS.length;
506
+ const someChecked = selected.length > 0 && !allChecked;
507
+
508
+ const toggle = (id: string) => setSelected(prev => (prev.includes(id) ? prev.filter(x => x !== id) : [...prev, id]));
509
+
510
+ const toggleAll = () => setSelected(allChecked ? [] : OPTIONS.map(o => o.id));
511
+
512
+ return (
513
+ <MobilePreview>
514
+ <Button label='Выбрать сервисы' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
515
+ <BottomSheet
516
+ open={open}
517
+ onClose={() => setOpen(false)}
518
+ title='Сервисы'
519
+ withDividers
520
+ content={
521
+ <div className={styles.column}>
522
+ {/* htmlFor связывает подпись с нативным input'ом внутри Checkbox — клик по тексту переключает чекбокс. */}
523
+ <label className={styles.checkRow} htmlFor='sel-all'>
524
+ <Checkbox id='sel-all' checked={allChecked} indeterminate={someChecked} onChange={toggleAll} />
525
+ <span>Выбрать все</span>
526
+ </label>
527
+ {OPTIONS.map(option => (
528
+ <label key={option.id} className={styles.checkRow} htmlFor={`sel-${option.id}`}>
529
+ <Checkbox
530
+ id={`sel-${option.id}`}
531
+ checked={selected.includes(option.id)}
532
+ onChange={() => toggle(option.id)}
533
+ />
534
+ <span>{option.label}</span>
535
+ </label>
536
+ ))}
537
+ </div>
538
+ }
539
+ approveButton={{ label: `Готово (${selected.length})`, onClick: () => setOpen(false) }}
540
+ />
541
+ </MobilePreview>
542
+ );
543
+ }
544
+ ```
545
+
546
+ ### Picker тегов
547
+
548
+ Поиск в subtitle фильтрует сетку тегов; клик переключает выбор
549
+
550
+ ```tsx
551
+ import { BottomSheet } from '@cloud-ru/ds-bottom-sheet';
552
+ import { Button } from '@cloud-ru/ds-button';
553
+ import { Search } from '@cloud-ru/ds-search';
554
+ import { Tag } from '@cloud-ru/ds-tag';
555
+ import { QuestionTooltip } from '@cloud-ru/ds-tooltip';
556
+ import { useState } from 'react';
557
+
558
+ import { MobilePreview } from '../MobilePreview';
559
+ import styles from './styles.module.scss';
560
+
561
+ const ALL_TAGS = ['Production', 'Staging', 'Dev', 'Backend', 'Frontend', 'Database', 'Network', 'Critical', 'Billing'];
562
+
563
+ /**
564
+ * Picker тегов: заголовок с подсказкой, поиск в sticky-зоне (subtitle) фильтрует список,
565
+ * сетка тегов в теле переключает выбор по клику, футер подтверждает выбор.
566
+ */
567
+ export function TagPicker() {
568
+ const [open, setOpen] = useState(false);
569
+ const [query, setQuery] = useState('');
570
+ const [selected, setSelected] = useState<string[]>(['Production']);
571
+
572
+ const visible = ALL_TAGS.filter(tag => tag.toLowerCase().includes(query.toLowerCase()));
573
+
574
+ const toggle = (tag: string) =>
575
+ setSelected(prev => (prev.includes(tag) ? prev.filter(x => x !== tag) : [...prev, tag]));
576
+
577
+ return (
578
+ <MobilePreview>
579
+ <Button label='Выбрать теги' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
580
+ <BottomSheet
581
+ open={open}
582
+ onClose={() => setOpen(false)}
583
+ title='Теги'
584
+ slotAfterTitle={<QuestionTooltip tip='Отметьте теги, по которым нужно отфильтровать' />}
585
+ slotSecondTitle={<Search value={query} onChange={setQuery} placeholder='Поиск тега' />}
586
+ content={
587
+ <div className={styles.tagGrid}>
588
+ {visible.map(tag => (
589
+ <Tag
590
+ key={tag}
591
+ label={tag}
592
+ size='s'
593
+ appearance={selected.includes(tag) ? 'primary' : 'neutral'}
594
+ onClick={() => toggle(tag)}
595
+ />
596
+ ))}
597
+ </div>
598
+ }
599
+ approveButton={{ label: `Применить (${selected.length})`, onClick: () => setOpen(false) }}
600
+ cancelButton={{ label: 'Отмена', onClick: () => setOpen(false) }}
601
+ />
602
+ </MobilePreview>
603
+ );
604
+ }
605
+ ```
606
+
607
+ ### Non-modal
608
+
609
+ showBackdrop={false} + lockScroll={false} — фон не затемнён и остаётся прокручиваемым
610
+
611
+ ```tsx
612
+ import { BottomSheet } from '@cloud-ru/ds-bottom-sheet';
613
+ import { Button } from '@cloud-ru/ds-button';
614
+ import { useState } from 'react';
615
+
616
+ import { MobilePreview } from '../MobilePreview';
617
+ import styles from './styles.module.scss';
618
+
619
+ const RESOURCES = Array.from({ length: 14 }, (_, i) => `vm-${String(i + 1).padStart(2, '0')} — ru-moscow-1a`);
620
+
621
+ /**
622
+ * Non-modal sheet: фон не затемняется (`showBackdrop={false}`) и не блокируется
623
+ * (`lockScroll={false}`) — страница под подсказкой остаётся видимой, скроллится и кликается.
624
+ * Свайп отключён (`swipeEnabled={false}`), потому что подсказку закрывают кнопкой, а не жестом.
625
+ */
626
+ export function NonModal() {
627
+ const [open, setOpen] = useState(true);
628
+
629
+ return (
630
+ <MobilePreview>
631
+ {/* Контент «страницы» под подсказкой. Список длиннее экрана — фон под non-modal sheet'ом
632
+ можно прокручивать, пока окно открыто (он не затемнён и не заблокирован). */}
633
+ <div className={styles.nonModalPage}>
634
+ <p>Регион: ru-moscow-1 — список виртуальных машин. Прокрутите его, пока подсказка открыта.</p>
635
+ <Button label='Показать подсказку' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
636
+ {RESOURCES.map(name => (
637
+ <p key={name}>{name}</p>
638
+ ))}
639
+ </div>
640
+
641
+ <BottomSheet
642
+ open={open}
643
+ onClose={() => setOpen(false)}
644
+ showBackdrop={false}
645
+ lockScroll={false}
646
+ swipeEnabled={false}
647
+ title='Совет'
648
+ content={<p>Откройте «Расширенные настройки», чтобы выбрать зону доступности вручную.</p>}
649
+ approveButton={{ label: 'Понятно', onClick: () => setOpen(false) }}
650
+ />
651
+ </MobilePreview>
652
+ );
653
+ }
654
+ ```
655
+
656
+ Для ручной сборки разметки из `Header / Body / Footer` — см. **BottomSheetCustom**.
657
+
658
+ ## Props
659
+
660
+ **BottomSheetProps**
661
+
662
+ | Prop | Type | Default | Description |
663
+ |------|------|---------|-------------|
664
+ | `actionButton` | `ReactNode` | — | Action-кнопка справа в шапке (любой ReactNode — обычно `Button view='function'`). |
665
+ | `additionalButton` | `BottomSheetActionButton` | — | Дополнительная (третья) кнопка — объект пропсов `Button` (по умолчанию `view='simple'`, <br/> `appearance='neutral'`). |
666
+ | `approveButton` | `BottomSheetActionButton` | — | Основная кнопка действия — объект пропсов `Button` (по умолчанию `view='filled'`, <br/> `appearance='primary'`). Ширина зависит от `footerActionsOrientation` и числа кнопок. |
667
+ | `bodyPadding` | `boolean` | `true` | Горизонтальные паддинги body. При `false` контент идёт во всю ширину (edge-to-edge) — для карт, <br/> изображений, списков без отступов. Соответствует Figma-оси `padding=false`. |
668
+ | `cancelButton` | `BottomSheetActionButton` | — | Кнопка отмены — объект пропсов `Button` (по умолчанию `view='outline'`, `appearance='neutral'`). |
669
+ | `className` | `string` | — | CSS-класс самого sheet-контейнера. |
670
+ | `closeOnPopstate` | `boolean` | `true` | Закрывать sheet при `popstate` (browser-back на mobile). |
671
+ | `container` | `string \| HTMLElement` | — | Контейнер для портала. По дефолту — `body` либо контекст-провайдер `@cloud-ru/ds-portal-context`. |
672
+ | `content` | `ReactNode` | — | Основное содержимое (рендерится в `BottomSheetCustom.Body`). |
673
+ | `data-test-id` | `string` | — | |
674
+ | `defaultSnapIndex` | `number` | `0` | Индекс snap'а, на котором sheet открывается по дефолту. Игнорируется при controlled `snapIndex`. |
675
+ | `footer` | `ReactNode` | — | Произвольный футер. Если задан — имеет приоритет над <br/> `approveButton` / `cancelButton` / `additionalButton`. |
676
+ | `footerActionsOrientation` | `"horizontal"` \| `"vertical"` | `'horizontal'` | Ориентация кнопок футера, собранных из `approveButton` / `cancelButton` / `additionalButton`. <br/> Применяется **только при ровно двух** кнопках (canonical cancel/confirm): <br/> - `'horizontal'` — кнопки в ряд через space-between: secondary слева, primary справа, <br/> ширина по контенту. Точное соответствие Figma `bottomBar.buttonGroup`. <br/> - `'vertical'` — кнопки в столбик, full-width (primary сверху). <br/> Одна кнопка всегда рендерится full-width (одиночный CTA); три кнопки не помещаются в ряд на <br/> mobile-вьюпорте и всегда идут в столбик — для них значение игнорируется. <br/> Игнорируется при заданном `footer` (произвольная разметка футера). |
677
+ | `footerTestIds` | `{ approve?: string; cancel?: string; additional?: string \| undefined; } \| undefined` | — | Переопределение `data-test-id` собранных слотов футера (approve/cancel/additional). <br/> По умолчанию — собственные id `BottomSheet`. Адаптивные `Modal`/`Drawer` передают сюда свои <br/> `TEST_IDS.footer*`, чтобы футер метился одинаково на desktop-поверхности и в mobile-sheet'е. |
678
+ | `lockScroll` | `boolean` | `true` | Блокировать ли скролл фона на время открытия (`react-remove-scroll`). При `false` страница <br/> под sheet'ом остаётся прокручиваемой — для non-modal сценариев (sheet поверх контента, с <br/> которым продолжают взаимодействовать). Обычно используется вместе с `showBackdrop={false}`. |
679
+ | `media` | `PopupMediaProps` | — | Media-блок над шапкой: изображение / иконка либо произвольный `ReactNode`. |
680
+ | `onBackButtonClick` | `(() => void)` | — | Callback клика на back-кнопку (слева в шапке). <br/> Наличие callback'а рендерит ArrowLeft-кнопку. |
681
+ | `onClose` | `() => void` | — | Колбэк закрытия (вызывается при click outside, Esc, swipe-down, browser-back). |
682
+ | `onSnapIndexChange` | `((snapIndex: number) => void)` | — | Callback изменения активного snap'а (пересечение swipe-границы или click по UI). <br/> Не вызывается при программной смене controlled `snapIndex`. |
683
+ | `open` | `boolean` | — | Управление состоянием показан / не показан. |
684
+ | `rootClassName` | `string` | — | CSS-класс корневого элемента portal'а. |
685
+ | `safeArea` | `boolean` | `true` | Резервировать ли место под iOS notch / home-indicator и Android nav-bar. Реализовано паддингом <br/> на `.content` через `env(safe-area-inset-*)`: на устройстве без выреза/индикатора (и на desktop) <br/> inset = 0, поэтому никакого «лишнего» отступа не появляется; на notched-устройстве — ровно нужный. <br/> Верхний отступ добавляется только когда sheet раскрыт на полный вьюпорт (его верх под notch). |
686
+ | `showBackdrop` | `boolean` | `true` | Отображение тёмной подложки за sheet'ом. При `false` фон не затемняется и click-outside <br/> не закрывает sheet (нет backdrop-узла, по которому ловится клик). |
687
+ | `slotAfterTitle` | `ReactNode` | — | Slot справа от title (внутри той же строки) — типично `QuestionTooltip`, status badge. |
688
+ | `slotSecondTitle` | `ReactNode` | — | Slot под подзаголовком — типично `SearchBar`, `SegmentControl`, `Filter`. |
689
+ | `snapIndex` | `number` | — | Controlled-индекс активного snap'а. Если задан, sheet всегда находится на этом snap'е; <br/> swipe-up/down вызывают `onSnapIndexChange`, но не меняют позицию сами — consumer должен <br/> передать новое значение. |
690
+ | `snapPoints` | `SnapPoint` | — | Массив фиксированных позиций sheet'а от меньшей к большей. По дефолту `undefined` — <br/> sheet `height: auto` с одним snap'ом по высоте контента. <br/> Пример: `[0.5, 1]` — sheet открывается на половину экрана, drag вверх раскрывает <br/> до full-viewport; drag вниз ниже `0.5` ведёт к закрытию. <br/> Контракт массива (движок не сортирует и не дедуплицирует — порядок и различимость на <br/> стороне потребителя): <br/> - строго по возрастанию: индекс `0` — самая компактная позиция, последний — top / expanded; <br/> - значения должны резолвиться в различные высоты (`['50%', 0.5]` на типичном вьюпорте дадут <br/> одну высоту → дубль-индекс будет недостижим свайпом); <br/> - `'fit-content'` имеет смысл только как ЕДИНСТВЕННЫЙ snap (без `snapPoints`); внутри массива <br/> фиксированных позиций его «контентная» высота не определена. |
691
+ | `subtitle` | `ReactNode` | — | Текстовая строка-подзаголовок под title. |
692
+ | `swipeEnabled` | `boolean` | `true` | Включает swipe-down для закрытия / swipe-up для раскрытия на следующий snap-point. <br/> При `swipeEnabled=false` snap-point по-прежнему можно переключить через controlled `snapIndex` prop'ом. |
693
+ | `title` | `ReactNode` | — | Заголовок в шапке. |
694
+ | `withDividers` | `boolean` | `true` | Тонкие линии между topBar↔body и body↔footer: разграничивают закреплённые шапку и подвал <br/> от прокручиваемого под ними содержимого. Передайте `false`, чтобы убрать обе линии. |
695
+
696
+ #### Related types
697
+
698
+ - `SnapPoint` = `number | `${number}px` | `${number}%` | `${number}dvh` | `${number}svh` | `${number}lvh` | "fit-content"`
699
+
700
+ ## Смотри также
701
+
702
+ - **BottomSheetCustom** — низкоуровневая ручная композиция.
703
+ - **Drawer** — выезжающая боковая панель (desktop / мульти-position).
704
+ - **Modal** — модальное окно по центру.
705
+ - **Toaster** — короткие mobile-уведомления.
706
+ - **Popover** — компактный поповер у триггера.
707
+ ## Когда не нужен
708
+
709
+ - На desktop'е — используйте **Modal** или **Drawer**.
710
+ - Для коротких подтверждений на одну строку — Toaster.
711
+ - Для контента, который должен перекрыть весь экран без возможности dismiss — это новый screen, не bottom-sheet.
712
+
713
+ ## Доступность
714
+
715
+ - **Роль и имя.** Sheet — `role='dialog'` + `aria-modal='true'`. Высокоуровневый `BottomSheet`
716
+ автоматически связывает `title` с dialog'ом через `aria-labelledby` (accessible name). Если `title`
717
+ нет (icon-/media-only sheet) или вы используете низкоуровневый `BottomSheetCustom` — задайте
718
+ `aria-label` сами (прокидывается на dialog).
719
+ - **Клавиатура.** `Esc` закрывает sheet (верхний слой при вложенных). Фокус переносится внутрь при
720
+ открытии, зациклен по `Tab` / `Shift+Tab` и возвращается на триггер после закрытия.
721
+ - **Motion.** Slide / fade / height-анимации гасятся при `prefers-reduced-motion: reduce`.
722
+ - **Media.** Для `media` всегда задавайте осмысленный `alt` (он обязателен в типе `BottomSheetMediaProps`).
723
+ - **Non-modal.** При `showBackdrop={false}` + `lockScroll={false}` sheet немодальный: `aria-modal` не выставляется, фокус не запирается (Tab уходит на фон), Esc закрывает даже когда фокус снаружи.
724
+ - **Dismiss-контрол.** Своей кнопки «закрыть» у sheet'а нет (dismiss — Esc / клик по backdrop / swipe-down). Если у sheet'а нет ни back-кнопки, ни footer-«Отмена», добавьте явный in-sheet dismiss для keyboard/SR-пользователей.
725
+ - **Snap-точки и клавиатура.** Переключение detent'ов (`snapPoints`) — это pointer-жест (swipe); клавиатурой detent не меняется. Контент ниже фолда доступен через скролл body + Tab. Для клавиатурного управления detent'ом используйте controlled `snapIndex` со своим контролом.
726
+ - **Pinch-zoom.** В модальном режиме фон-скролл лочится `react-remove-scroll` — на iOS это также блокирует pinch-to-zoom, пока sheet открыт (DS-wide, как у Modal/Drawer).
727
+
728
+ ## BottomSheetCustom
729
+
730
+ Низкоуровневая сборка bottom-sheet — полный контроль над разметкой через Header / Body / Footer субкомпоненты.
731
+
732
+ `BottomSheetCustom` — низкоуровневая версия `BottomSheet`, которая не диктует структуру содержимого. Потребитель сам компонует шапку, тело и футер из субкомпонентов `BottomSheetCustom.Header`, `.Body`, `.Footer` или собственной разметки.
733
+
734
+ Сам компонент берёт на себя portal, backdrop, slide-up-motion, focus-trap и swipe / snap-движок. Готовая анатомия (media-блок, dividers, авто-рендер back-кнопки) есть только у высокоуровневого `BottomSheet`.
735
+
736
+ ### Когда использовать
737
+
738
+ - Стандартной шапки / футера из `BottomSheet` недостаточно — нужна своя разметка.
739
+ - Сложная раскладка нескольких секций внутри одного sheet'а.
740
+ - Кастомные слоты (например, фиксированный поиск между шапкой и телом).
741
+
742
+ Во всех остальных случаях предпочтительнее `BottomSheet` — он дешевле в поддержке и даёт консистентные отступы.
743
+
744
+ ### Анатомия
745
+
746
+ #### Header
747
+ Слот `BottomSheetCustom.Header` — `title`, `slotAfterTitle`, `subtitle`, `slotSecondTitle`, `onBackButtonClick`, `actionButton`.
748
+
749
+ > **Accessible name.** В отличие от высокоуровневого `BottomSheet`, низкоуровневый `BottomSheetCustom` не связывает `Header.title` с dialog'ом автоматически — задайте имя сами: `aria-label` (или `aria-labelledby` на узел заголовка) прямо на `BottomSheetCustom`. Без него screen reader озвучит просто «dialog».
750
+
751
+ #### Non-modal / dismissal
752
+ `showBackdrop={false}` + `lockScroll={false}` дают non-modal sheet — фон не затемнён и остаётся прокручиваемым (sheet поверх живого контента). `closeOnPopstate` (default `true`) закрывает sheet по browser-back на mobile.
753
+
754
+ #### Body
755
+ Слот `BottomSheetCustom.Body` — основное содержимое (через `children` или `content`). Скроллится независимо от sheet'а.
756
+
757
+ #### Footer
758
+ Слот `BottomSheetCustom.Footer` — нижняя action-зона (обычно `Button` или их композиция).
759
+
760
+ #### Snap points (default `undefined` → height auto)
761
+ `snapPoints` принимает массив фиксированных позиций (`number ∈ (0, 1] | 'Npx' | 'N%' | 'Ndvh' | 'Nsvh' | 'Nlvh' | 'fit-content'`) от меньшей к большей. Активный snap управляется через `defaultSnapIndex` (uncontrolled) либо `snapIndex` + `onSnapIndexChange` (controlled). В controlled-режиме swipe вызывает `onSnapIndexChange`, но позицию не двигает — потребитель сам передаёт новое значение.
762
+
763
+ ### Примеры использования
764
+
765
+ #### Ручная композиция
766
+
767
+ Header + Body + Footer собираются вручную.
768
+
769
+ ```tsx
770
+ import { BottomSheetCustom } from '@cloud-ru/ds-bottom-sheet';
771
+ import { Button } from '@cloud-ru/ds-button';
772
+ import { useState } from 'react';
773
+
774
+ import { MobilePreview } from '../MobilePreview';
775
+
776
+ /**
777
+ * BottomSheetCustom — низкоуровневая обёртка. Backdrop, scroll-lock, focus-trap и slide-up-motion
778
+ * даёт сам компонент; анатомию (header / media / body / footer и их порядок) потребитель
779
+ * собирает из namespace-слотов `BottomSheetCustom.Handle / .Header / .Media / .Body / .Footer`.
780
+ */
781
+ export function CustomComposition() {
782
+ const [open, setOpen] = useState(false);
783
+
784
+ return (
785
+ <MobilePreview>
786
+ <Button label='Открыть Custom' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
787
+ <BottomSheetCustom open={open} onClose={() => setOpen(false)} aria-label='Custom composition'>
788
+ <BottomSheetCustom.Header title='Custom composition' slotAfterTitle={<span>NEW</span>} />
789
+ <BottomSheetCustom.Body>
790
+ <p>Свободный JSX внутри Body. Можно вставить любой контент между Header и Footer.</p>
791
+ </BottomSheetCustom.Body>
792
+ <BottomSheetCustom.Footer>
793
+ <Button fullWidth view='filled' appearance='primary' label='Готово' onClick={() => setOpen(false)} />
794
+ </BottomSheetCustom.Footer>
795
+ </BottomSheetCustom>
796
+ </MobilePreview>
797
+ );
798
+ }
799
+ ```
800
+
801
+ #### Snap points: половина → full
802
+
803
+ snapPoints={[0.5, 1]} + controlled snapIndex
804
+
805
+ ```tsx
806
+ import { BottomSheetCustom } from '@cloud-ru/ds-bottom-sheet';
807
+ import { Button } from '@cloud-ru/ds-button';
808
+ import { useState } from 'react';
809
+
810
+ import { MobilePreview } from '../MobilePreview';
811
+
812
+ /**
813
+ * Custom-слой полностью управляет snap-движком. `snapPoints={[0.5, 1]}` открывает sheet на
814
+ * половину экрана; drag вверх (или контролируемый `snapIndex`) раскрывает до full-viewport.
815
+ * Активный snap отслеживается через `onSnapIndexChange`.
816
+ */
817
+ export function CustomSnapPoints() {
818
+ const [open, setOpen] = useState(false);
819
+ const [snapIndex, setSnapIndex] = useState(0);
820
+
821
+ return (
822
+ <MobilePreview>
823
+ <Button label='Открыть expandable' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
824
+ <BottomSheetCustom
825
+ open={open}
826
+ onClose={() => setOpen(false)}
827
+ snapPoints={[0.5, 1]}
828
+ snapIndex={snapIndex}
829
+ onSnapIndexChange={setSnapIndex}
830
+ aria-label='Snap points sheet'
831
+ >
832
+ <BottomSheetCustom.Header title={snapIndex === 0 ? 'Половина экрана' : 'Full-screen'} />
833
+ <BottomSheetCustom.Body>
834
+ <p>Текущий snap-индекс: {snapIndex}. Потяните вверх, чтобы раскрыть.</p>
835
+ </BottomSheetCustom.Body>
836
+ <BottomSheetCustom.Footer>
837
+ <Button
838
+ fullWidth
839
+ view='filled'
840
+ appearance='primary'
841
+ label={snapIndex === 0 ? 'Раскрыть' : 'Свернуть'}
842
+ onClick={() => setSnapIndex(snapIndex === 0 ? 1 : 0)}
843
+ />
844
+ </BottomSheetCustom.Footer>
845
+ </BottomSheetCustom>
846
+ </MobilePreview>
847
+ );
848
+ }
849
+ ```
850
+
851
+ #### Scrollable body
852
+
853
+ Длинный список скроллится внутри Body, header / footer фиксированы
854
+
855
+ ```tsx
856
+ import { BottomSheetCustom } from '@cloud-ru/ds-bottom-sheet';
857
+ import { Button } from '@cloud-ru/ds-button';
858
+ import { useState } from 'react';
859
+
860
+ import { MobilePreview } from '../MobilePreview';
861
+
862
+ /**
863
+ * Длинный контент в `BottomSheetCustom.Body` скроллится независимо: drag-движок отдаёт жест
864
+ * нативному скроллу, пока тело не упёрлось в край, и только тогда перехватывает swipe-down sheet'а.
865
+ * Header и Footer остаются на месте.
866
+ */
867
+ export function CustomScrollable() {
868
+ const [open, setOpen] = useState(false);
869
+ const rows = Array.from({ length: 30 }, (_, i) => i + 1);
870
+
871
+ return (
872
+ <MobilePreview>
873
+ <Button label='Открыть scrollable' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
874
+ <BottomSheetCustom open={open} onClose={() => setOpen(false)} snapPoints={['60dvh']} aria-label='Длинный список'>
875
+ <BottomSheetCustom.Header title='Длинный список' />
876
+ <BottomSheetCustom.Body>
877
+ {rows.map(n => (
878
+ <p key={n}>Строка №{n}</p>
879
+ ))}
880
+ </BottomSheetCustom.Body>
881
+ <BottomSheetCustom.Footer>
882
+ <Button fullWidth view='filled' appearance='primary' label='Готово' onClick={() => setOpen(false)} />
883
+ </BottomSheetCustom.Footer>
884
+ </BottomSheetCustom>
885
+ </MobilePreview>
886
+ );
887
+ }
888
+ ```
889
+
890
+ #### Без анимации
891
+
892
+ disableMotions — мгновенное открытие / закрытие без slide-up
893
+
894
+ ```tsx
895
+ import { BottomSheetCustom } from '@cloud-ru/ds-bottom-sheet';
896
+ import { Button } from '@cloud-ru/ds-button';
897
+ import { useState } from 'react';
898
+
899
+ import { MobilePreview } from '../MobilePreview';
900
+
901
+ /**
902
+ * `disableMotions` отключает slide-up / slide-down и анимации перехода между snap-точками:
903
+ * sheet появляется и исчезает мгновенно. Удобно для reduced-motion, тестов и сценариев,
904
+ * где анимация мешает.
905
+ */
906
+ export function CustomDisableMotions() {
907
+ const [open, setOpen] = useState(false);
908
+
909
+ return (
910
+ <MobilePreview>
911
+ <Button label='Открыть без анимации' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
912
+ <BottomSheetCustom open={open} onClose={() => setOpen(false)} disableMotions aria-label='Sheet без анимации'>
913
+ <BottomSheetCustom.Header title='Без анимации' />
914
+ <BottomSheetCustom.Body>
915
+ <p>Открытие и закрытие мгновенные — slide-up / slide-down отключены через disableMotions.</p>
916
+ </BottomSheetCustom.Body>
917
+ <BottomSheetCustom.Footer>
918
+ <Button fullWidth view='filled' appearance='primary' label='Закрыть' onClick={() => setOpen(false)} />
919
+ </BottomSheetCustom.Footer>
920
+ </BottomSheetCustom>
921
+ </MobilePreview>
922
+ );
923
+ }
924
+ ```
925
+
926
+ ### Props
927
+
928
+ **BottomSheetCustomProps**
929
+
930
+ | Prop | Type | Default | Description |
931
+ |------|------|---------|-------------|
932
+ | `children` | `string \| number \| boolean \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| null \| undefined` | — | |
933
+ | `className` | `string` | — | CSS-класс самого sheet-контейнера. |
934
+ | `closeOnPopstate` | `boolean` | `true` | Закрывать sheet при `popstate` (browser-back на mobile). |
935
+ | `container` | `string \| HTMLElement` | — | Контейнер для портала. По дефолту — `body` либо контекст-провайдер `@cloud-ru/ds-portal-context`. |
936
+ | `data-test-id` | `string` | — | |
937
+ | `defaultSnapIndex` | `number` | `0` | Индекс snap'а, на котором sheet открывается по дефолту. Игнорируется при controlled `snapIndex`. |
938
+ | `disableMotions` | `boolean` | `false` | Отключить анимации открытия / закрытия и перехода между snap-точками. |
939
+ | `lockScroll` | `boolean` | `true` | Блокировать ли скролл фона на время открытия (`react-remove-scroll`). При `false` страница <br/> под sheet'ом остаётся прокручиваемой — для non-modal сценариев (sheet поверх контента, с <br/> которым продолжают взаимодействовать). Обычно используется вместе с `showBackdrop={false}`. |
940
+ | `onClose` | `() => void` | — | Колбэк закрытия (вызывается при click outside, Esc, swipe-down, browser-back). |
941
+ | `onSnapIndexChange` | `((snapIndex: number) => void)` | — | Callback изменения активного snap'а (пересечение swipe-границы или click по UI). <br/> Не вызывается при программной смене controlled `snapIndex`. |
942
+ | `open` | `boolean` | — | Управление состоянием показан / не показан. |
943
+ | `rootClassName` | `string` | — | CSS-класс корневого элемента portal'а. |
944
+ | `safeArea` | `boolean` | `true` | Резервировать ли место под iOS notch / home-indicator и Android nav-bar. Реализовано паддингом <br/> на `.content` через `env(safe-area-inset-*)`: на устройстве без выреза/индикатора (и на desktop) <br/> inset = 0, поэтому никакого «лишнего» отступа не появляется; на notched-устройстве — ровно нужный. <br/> Верхний отступ добавляется только когда sheet раскрыт на полный вьюпорт (его верх под notch). |
945
+ | `showBackdrop` | `boolean` | `true` | Отображение тёмной подложки за sheet'ом. При `false` фон не затемняется и click-outside <br/> не закрывает sheet (нет backdrop-узла, по которому ловится клик). |
946
+ | `snapIndex` | `number` | — | Controlled-индекс активного snap'а. Если задан, sheet всегда находится на этом snap'е; <br/> swipe-up/down вызывают `onSnapIndexChange`, но не меняют позицию сами — consumer должен <br/> передать новое значение. |
947
+ | `snapPoints` | `SnapPoint` | — | Массив фиксированных позиций sheet'а от меньшей к большей. По дефолту `undefined` — <br/> sheet `height: auto` с одним snap'ом по высоте контента. <br/> Пример: `[0.5, 1]` — sheet открывается на половину экрана, drag вверх раскрывает <br/> до full-viewport; drag вниз ниже `0.5` ведёт к закрытию. <br/> Контракт массива (движок не сортирует и не дедуплицирует — порядок и различимость на <br/> стороне потребителя): <br/> - строго по возрастанию: индекс `0` — самая компактная позиция, последний — top / expanded; <br/> - значения должны резолвиться в различные высоты (`['50%', 0.5]` на типичном вьюпорте дадут <br/> одну высоту → дубль-индекс будет недостижим свайпом); <br/> - `'fit-content'` имеет смысл только как ЕДИНСТВЕННЫЙ snap (без `snapPoints`); внутри массива <br/> фиксированных позиций его «контентная» высота не определена. |
948
+ | `swipeEnabled` | `boolean` | `true` | Включает swipe-down для закрытия / swipe-up для раскрытия на следующий snap-point. <br/> При `swipeEnabled=false` snap-point по-прежнему можно переключить через controlled `snapIndex` prop'ом. |
949
+
950
+ ##### Related types
951
+
952
+ - `SnapPoint` = `number | `${number}px` | `${number}%` | `${number}dvh` | `${number}svh` | `${number}lvh` | "fit-content"`
953
+
954
+ ### Смотри также
955
+
956
+ - **BottomSheet** — высокоуровневая обёртка с готовой анатомией.
957
+ - **Drawer** — выезжающая боковая панель (desktop / мульти-position).
958
+ - **Modal** — модальное окно по центру.
959
+
960
+ ## Handle
961
+
962
+ ```tsx
963
+ import { BottomSheetCustom } from '@cloud-ru/ds-bottom-sheet';
964
+ import { Button } from '@cloud-ru/ds-button';
965
+ import { useState } from 'react';
966
+
967
+ import { MobilePreview } from '../MobilePreview';
968
+
969
+ /**
970
+ * BottomSheetCustom — низкоуровневая обёртка. Backdrop, scroll-lock, focus-trap и slide-up-motion
971
+ * даёт сам компонент; анатомию (header / media / body / footer и их порядок) потребитель
972
+ * собирает из namespace-слотов `BottomSheetCustom.Handle / .Header / .Media / .Body / .Footer`.
973
+ */
974
+ export function CustomComposition() {
975
+ const [open, setOpen] = useState(false);
976
+
977
+ return (
978
+ <MobilePreview>
979
+ <Button label='Открыть Custom' view='outline' appearance='neutral' onClick={() => setOpen(true)} />
980
+ <BottomSheetCustom open={open} onClose={() => setOpen(false)} aria-label='Custom composition'>
981
+ <BottomSheetCustom.Header title='Custom composition' slotAfterTitle={<span>NEW</span>} />
982
+ <BottomSheetCustom.Body>
983
+ <p>Свободный JSX внутри Body. Можно вставить любой контент между Header и Footer.</p>
984
+ </BottomSheetCustom.Body>
985
+ <BottomSheetCustom.Footer>
986
+ <Button fullWidth view='filled' appearance='primary' label='Готово' onClick={() => setOpen(false)} />
987
+ </BottomSheetCustom.Footer>
988
+ </BottomSheetCustom>
989
+ </MobilePreview>
990
+ );
991
+ }
992
+ ```
993
+
994
+ ### Props
995
+
996
+ | Prop | Type | Default | Description |
997
+ |------|------|---------|-------------|