Bottom Sheet Component Research

# Bottom Sheet — Component Research & Phương Án

Nghiên cứu: 2026-03-12 Sources: M3 Bottom Sheets, Apple HIG Sheets, shadcn/ui Sheet, UX best practices Status: PROPOSED

Cross-ref: knowledge/research/industry-benchmarking-report.md, design-system/components md/navigation-bar.md

1. Tổng Quan

Bottom Sheet là container nội dung phụ gắn ở đáy màn hình, trượt lên để hiển thị thêm thông tin hoặc actions mà không rời khỏi context hiện tại. Đây là pattern thiết yếu cho mobile-first apps (Maps, Payment, E-commerce, xPOS).

Tại sao Prisma cần Bottom Sheet?

2. Cross-Platform Research

2.1. Material Design 3 — Bottom Sheets

Specs:

Behavior:

• Header cố định, content scroll bên trong
• Drag handle (tùy chọn) cho phép kéo resize giữa các detent heights
• Modal sheets ban đầu max 50% screen height → kéo lên full
• Standard sheets có thể snap vào nhiều vị trí (detents)

2.2. Apple HIG — Sheets (iOS)

Key patterns:

• Progressive disclosure via medium detent: ban đầu hiện 50%, kéo lên để xem thêm
• Maps pattern: Persistent non-modal sheet với multiple detents (collapsed → half → full)
• Card-style: Rounded corners, slight shadow, background visible phía trên

2.3. shadcn/ui — Sheet Component

2.4. M3 Modal Bottom Sheet — Use Cases

M3 khuyến nghị dùng modal bottom sheet cho các tình huống sau:

Khi KHÔNG dùng modal bottom sheet:

• Content cần toàn bộ sự chú ý → dùng fullscreen hoặc new page
• Chỉ có 1-2 actions → dùng dialog hoặc menu
• Navigation between views → dùng navigation component
• Primary content → bottom sheet chỉ cho secondary content

2.5. Fullscreen Bottom Sheet

Fullscreen là trạng thái đặc biệt khi bottom sheet mở rộng chiếm toàn bộ màn hình:

Fullscreen Use Cases:

Transition pattern (M3 + iOS):

[Trigger tap] → Sheet slides up to detent:medium (50%)
              → User drags up → detent:large (90%)
              → User continues drag → detent:full (100%, radius→0)
              → OR: Direct open as fullscreen

2.6. UX Best Practices (Industry Consensus)

3. So Sánh Cross-Platform

4. Phương Án Prisma — Bottom Sheet Component

4.1. Variants

4.2. Anatomy (Sub-components / Slots)

┌─────────────────────────────────┐
│         Drag Handle             │ ← Optional, 32×4px chip
│─────────────────────────────────│
│ [Icon]  Header Title    [Close] │ ← Header slot
│         Subtitle                │
│─────────────────────────────────│ ← Optional divider
│                                 │
│       Scrollable Content        │ ← Content slot
│       (list / form / custom)    │
│                                 │
│─────────────────────────────────│ ← Optional divider
│    [Secondary]    [Primary]     │ ← Footer/Actions slot
│─────────────────────────────────│
│      safe area padding          │
└─────────────────────────────────┘

4.3. Height Standards (Min/Max)

Cross-platform height specs:

4.4. Detents (Height Stops)

Logic: Drag handle interaction cycles through detents. Swipe velocity determines snap target.

Không dùng fixed px cho height — luôn dùng % of container/viewport để responsive trên mọi device size.

4.5. CSS Naming Convention (Elevation-based)

Theo css-naming-convention.md:

• Bottom Sheet = Surface layer (overlays content)
• Modal variant adds Scrim (overlay layer)

.surface-sheet              ← Container (Surface layer)
.surface-sheet--modal       ← Modal variant
.surface-sheet--standard    ← Standard variant
.surface-sheet--persistent  ← Persistent variant
.surface-sheet--fullscreen  ← Fullscreen variant (radius:0, 100%)
.surface-sheet__handle      ← Drag handle
.surface-sheet__header      ← Header area
.surface-sheet__content     ← Scrollable body (SLOT injection point)
.surface-sheet__footer      ← Actions area
.surface-sheet__scrim       ← Background overlay (modal only)
.surface-sheet__close       ← Close button

Slot Architecture: .surface-sheet__content là injection point. JS switches content bằng slot name → inject HTML tương ứng. Mỗi slot define: title, subtitle, content (HTML), showFooter, footerButtons.

4.6. Token Mapping (Draft)

4.7. Props & API (Draft)

interface BottomSheetProps {
  /** Sheet type */
  variant?: 'modal' | 'standard' | 'persistent';
  /** Controlled open state */
  open: boolean;
  /** Close callback */
  onClose: () => void;
  /** Available detent heights */
  detents?: ('collapsed' | 'medium' | 'large' | 'full')[];
  /** Initial detent */
  initialDetent?: 'collapsed' | 'medium' | 'large';
  /** Show drag handle */
  showHandle?: boolean;
  /** Close on scrim tap (modal only) */
  closeOnOverlayClick?: boolean;
  /** Close on Escape key */
  closeOnEscape?: boolean;
  /** Swipe to dismiss */
  swipeToDismiss?: boolean;
  /** Lock backdrop scroll (modal only) */
  lockBackgroundScroll?: boolean;
  /** Custom max width */
  maxWidth?: string;
  /** Children content */
  children: ReactNode;
}

4.8. Accessibility

4.9. Interaction Patterns

5. Responsive Layout

Decision: Trên desktop (≥840px), bottom sheet nên tự động chuyển thành Dialog hoặc Side Panel (responsive pattern). Tương tự Google Maps desktop vs mobile.

6. Phương Án Thực Thi (Implementation Strategy)

Phase 1: Core Modal Bottom Sheet

• Token JSON cho bottom-sheet component
• CSS skeleton (.surface-sheet, .surface-sheet--modal)
• Scrim overlay
• Open/close animation (slide up/down)
• Close on scrim tap + Escape
• Accessibility (role, aria, focus trap)

Phase 2: Detents & Drag

• Drag handle component
• Multi-detent system (collapsed, medium, large)
• Swipe to dismiss
• Scroll-aware dismiss (content at top → swipe dismiss)
• Snap physics (velocity-based)

Phase 3: Standard & Persistent Variants

• Standard variant (no scrim, coexists)
• Persistent variant (always visible, detent-based)
• Map-style pattern example

Phase 4: Responsive

• Max-width 640px on medium/expanded
• Desktop: auto-switch to dialog/side-panel
• Tablet: centered positioning

7. Priority & Effort

8. References

• M3 Bottom Sheets — Guidelines
• M3 Bottom Sheets — Specs
• M3 Bottom Sheets — Overview
• Apple HIG — Sheets
• shadcn/ui — Sheet
• Mobbin — Bottom Sheet UX Patterns
• LogRocket — Bottom Sheet Best Practices