반응형 내비게이션

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

• 현재 영역의 목적지를 한 모델로 정의하세요. 같은 링크를 데스크톱 사이드바와 모바일 시트에 렌더링합니다.
• 모바일 시트는 카탈로그 자체의 바텀 시트 메뉴와 일치합니다. 아래쪽 가장자리에서 올라오고, 현재 목적지에서 열리며, 엄지가 닿는 범위 안에 전체 너비 Close menu 버튼으로 끝납니다.
• 열린 시트는 AppShell의 760px 브레이크포인트와 같은 matchMedia 조건에서 닫히고 포커스가 이동합니다.
• 카탈로그 자체는 전역 상단 레일과 접을 수 있는 문맥 사이드바를 사용합니다. 제품 화면에 맞는 구조를 고르세요.
• 앱의 주요 목적지가 3~5개라면 BottomNavigation이 같은 브레이크포인트에서 이를 아래쪽 가장자리에 두어 한 번에 닿게 하고, 나머지는 Sheet에 둘 수 있습니다.
• 예시는 App shell 모듈을 재사용합니다. Long navigation labels 또는 Read-only navigation 을 켜서 확인해 보세요.

• 좁은 화면에서 중요한 목적지를 빼지 마세요. 시트에 렌더링하세요.
• 외부 링크, 계정 컨트롤, 테마 컨트롤을 목적지 목록에 섞지 마세요. 폰 머리글에 계정 메뉴를 둘 자리가 없으면 목록과 떨어진 메뉴 바닥글에 두세요.
• 포커스가 사라진 링크에 남아 있는 동안 CSS로 데스크톱 링크를 숨기지 마세요. 포커스를 모바일 메뉴 버튼으로 옮기세요.
• 목적지에 앱 메뉴 화살표 키 규칙을 추가하지 마세요. 네이티브 a 엘리먼트로 유지하세요.
• 예시의 읽기 전용 체크박스를 권한 확인으로 취급하지 마세요. 로컬 표시 조건이며, 실제 권한 확인은 서버와 제품 라우터에서 일어납니다.

구성

Shared destination model → desktop nav(AppShell.Sidebar + ScrollArea) / mobile trigger → bottom Sheet(Header(Title, Description), Body(native nav links), Footer(Close menu)) → workspace heading

키보드와 접근성

• Tab은 메뉴 버튼에 도달하고, Enter나 Space는 메뉴 버튼을 활성화합니다. 모바일 시트는 현재 목적지에 포커스를 두고 열립니다.
• 목적지를 고르면 포커스가 콘텐츠 제목으로 이동합니다.
• Base UI가 포커스 트래핑과 Escape를 관리합니다. 취소하면 포커스가 메뉴 버튼으로 돌아갑니다.
• 시트가 열린 채로 데스크톱으로 넓히면 포커스가 현재 데스크톱 링크로 이동합니다. 데스크톱 링크에 포커스가 있는 채로 모바일로 좁히면 포커스가 모바일 메뉴 버튼으로 이동합니다.
• 모바일 시트에는 의미 있는 제목과 설명이 있습니다. 긴 이름은 시각적으로 잘려도 전체 접근 가능 이름을 유지합니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { AppShell, Sheet, Button, ScrollArea } from '@surflane/ui'

const navigation = destinations
  .filter(canAccess)
  .map((item) => (
    <AppShell.Link
      key={item.id}
      href={item.href}
      label={item.label}
      icon={item.icon}
      aria-current={isCurrent(item) ? 'page' : undefined}
    />
  ))

<AppShell.Sidebar>
  <ScrollArea orientation='vertical' label='Destinations'>
    <nav aria-label='Workspace navigation'>{navigation}</nav>
  </ScrollArea>
</AppShell.Sidebar>

<Sheet.Root side='bottom' open={open} onOpenChange={setOpen}>
  <Sheet.Trigger render={<Button aria-label='Open navigation' />}>
    Menu
  </Sheet.Trigger>
  <Sheet.Content initialFocus={currentLink} finalFocus={resolveReturnFocus}>
    <Sheet.Header>
      <Sheet.Title>Workspace navigation</Sheet.Title>
      <Sheet.Description>Choose a workspace page.</Sheet.Description>
    </Sheet.Header>
    <Sheet.Body>
      <nav aria-label='Mobile workspace navigation'>{navigation}</nav>
    </Sheet.Body>
    <Sheet.Footer>
      <Button variant='secondary' onClick={() => setOpen(false)}>
        Close menu
      </Button>
    </Sheet.Footer>
  </Sheet.Content>
</Sheet.Root>

// Match AppShell's <=760px CSS breakpoint. Close the Sheet on desktop resize.
// Resolve return focus: cancel -> trigger; navigation -> heading; desktop resize -> current link.
// Revalidate routes and permissions in the product, including browser back/forward.

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰