화면, 레이아웃, 내비게이션

플러그인 UI는 “어디에 나타나는가”를 정하는 extension point와 “무엇을 그리는가”를 정하는 Runtime tree로 나뉩니다. 먼저 사용자 흐름을 화면 단위로 나눈 뒤 각 화면의 JSON을 작성하세요.

화면 역할부터 정하기

surface는 기존 패키지 호환용 일반 화면 point입니다. 새 독립 화면에는 역할이 더 명확한 screen을 사용합니다.

권장 화면 흐름

Home card/action
  → Overview screen
      ├─ List/filter state
      ├─ Detail screen
      └─ Edit dialog 또는 sheet

Plugin detail
  → Settings screen
      ├─ Account connections
      ├─ Notifications
      └─ Display preferences

첫 화면은 사용자가 현재 상태와 다음 행동을 5초 안에 파악할 수 있어야 합니다. 원시 JSON, capability ID, package ID, 디버그 상태는 사용자 화면에 두지 않습니다.

레이아웃 선택

• column: 기본 읽기 흐름. 모바일에서 가장 안전한 시작점입니다.
• row: 짧은 상태와 행동을 나란히 놓을 때 사용합니다. 좁은 폭에서는 stack_at으로 세로 전환합니다.
• wrap: chip이나 짧은 필터처럼 항목 너비가 다른 반복 요소에 사용합니다.
• grid: 같은 중요도의 카드·metric을 반복할 때 사용합니다. min_item_width로 열 수를 줄입니다.
• section: 제목이 있는 정보 그룹입니다. 한 화면에 section이 너무 많아지면 화면을 분리합니다.
• card: 배경과 경계가 필요한 독립 정보나 누를 수 있는 요약에 사용합니다.

중첩 card와 section을 장식 목적으로 반복하지 마세요. 부모 하나로 관계가 설명되면 추가 surface는 정보 계층을 흐립니다.

내비게이션

같은 플러그인의 다른 UI extension으로 이동할 때 navigate를 사용합니다.

{
  "type": "button",
  "props": {"label": "전체 시간표 보기", "style": "tonal"},
  "action": {"type": "navigate", "target": "school_life.week"}
}

target은 같은 manifest에 선언된 UI extension ID여야 합니다. 현재 화면을 닫고 이전 Host 화면으로 돌아갈 때는 back을 사용합니다.

{"type": "back"}

탭처럼 보여야 하는 단순 필터는 새 화면을 만들지 말고 chip과 set_state로 처리합니다. 반대로 목록과 상세처럼 제목, 스크롤 위치, 뒤로가기 의미가 달라지는 정보는 별도 screen으로 나눕니다.

상단 메뉴와 설정

Host가 화면 제목, 뒤로가기, 플러그인 메뉴를 담당합니다. JSON tree에서 별도 앱 바를 흉내 내지 않습니다. 화면의 overflow 메뉴는 해당 화면에서 자주 쓰지 않는 보조 행동만 담습니다. 계정 연결은 settings 화면의 Connection 관리로 제공하며 동일 패키지 root Instance를 복제하는 “계정 추가” 동작을 만들지 않습니다.

상태별 화면

한 data source에는 적어도 다음 상태를 고려합니다.

전체 화면을 한 data source의 오류로 교체하지 않습니다. 오류는 영향을 받은 section에 격리합니다.

다음은 기본·커스텀 컴포넌트입니다.