Tree

파일 탐색기나 조직도처럼 계층적 데이터를 트리 구조로 표시하는 컴포넌트입니다.

기본 사용법 (Basic Usage)#

Tree(
  nodes: [
    CoreTreeNode(
      label: 'Documents',
      expanded: true,
      children: [
        CoreTreeNode(label: 'Resume.pdf'),
        CoreTreeNode(label: 'Cover Letter.pdf'),
      ],
    ),
    CoreTreeNode(
      label: 'Images',
      children: [
        CoreTreeNode(label: 'photo.png'),
      ],
    ),
    CoreTreeNode(label: 'README.md'),
  ],
  onNodeSelect: (node) => print('selected: ${node.label}'),
  onNodeToggle: (node) => print('toggled: ${node.label}'),
)

Live Preview#

class TreeDefaultExample extends StatelessComponent {
  const TreeDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return const Tree(
      nodes: [
        CoreTreeNode(
          label: 'Documents',
          expanded: true,
          children: [
            CoreTreeNode(label: 'Resume.pdf'),
            CoreTreeNode(label: 'Cover Letter.pdf'),
          ],
        ),
        CoreTreeNode(
          label: 'Images',
          children: [
            CoreTreeNode(label: 'photo.png'),
            CoreTreeNode(label: 'banner.jpg'),
          ],
        ),
        CoreTreeNode(label: 'README.md'),
      ],
    );
  }
}

class TreeDefaultExample extends StatelessWidget {
  const TreeDefaultExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Tree(
      nodes: [
        CoreTreeNode(
          label: 'Documents',
          expanded: true,
          children: [
            CoreTreeNode(label: 'Resume.pdf'),
            CoreTreeNode(label: 'Cover Letter.pdf'),
          ],
        ),
        CoreTreeNode(
          label: 'Images',
          children: [
            CoreTreeNode(label: 'photo.png'),
            CoreTreeNode(label: 'banner.jpg'),
          ],
        ),
        CoreTreeNode(label: 'README.md'),
      ],
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 파일 탐색기처럼 폴더/파일 계층 구조를 표시할 때
• 조직도, 카테고리 분류처럼 부모-자식 관계의 데이터를 탐색할 때

대신 다른 컴포넌트를 사용하세요:

• Accordion: 고정된 수의 섹션을 접기/펼치기로 표시할 때
• Menu: 계층 없이 평면적인 메뉴 목록에
• Collapsible: 단일 섹션의 접기/펼치기에

Props / Parameters#

노드 데이터는 CoreTreeNode로 공유합니다. 커스텀 빌더의 반환 콘텐츠 타입 W는 Flutter의 Widget, Web의 Component입니다. virtualRowHeight/virtualViewportHeight와 들여쓰기 치수는 논리 px 단위이며 노드 id와 화면 인덱스는 구분합니다.

스타일 시스템 (Style System)#

Tree 의 모든 chrome / dimensional / nested-slot 오버라이드는 CoreTreeStyle 단일 슬롯으로 흐릅니다. 시맨틱 (onNodeSelect, onNodeToggle, nodes) 은 위젯 파라미터로 직접 전달합니다.

시맨틱 vs 스타일#

• 시맨틱 / behaviour: 위젯 파라미터로 직접 (nodes, onNodeSelect, onNodeToggle)
• chrome / dimensional / 슬롯 스타일: CoreTreeStyle 한 곳으로 (nodeBackgroundColor / nodeSelectedColor / nodeHoverColor / nodePadding / nodeMinHeight / indent / indentLineColor / indentLineThickness / nodeTextStyle / iconStyle / leafIconStyle / chevronIconStyle)

Resolve chain#

design system default for tree
  → CoreTreeTheme.style                        // 프로젝트 공통
  → parent component slot override
  → widget.treeStyle                           // 인스턴스별

각 nested 슬롯 스타일 (nodeTextStyle / iconStyle / leafIconStyle / chevronIconStyle) 은 자기 컴포넌트 (CoreTextStyle / CoreIconStyle) 자체 resolve chain 으로 다시 한 번 머지됩니다.

CoreTreeStyle 필드#

동작 스펙 (Behavior)#

인터랙션#

• 자식이 있는 노드 클릭: 펼침/접힘 토글. onNodeToggle 호출
• 자식이 없는 노드(leaf) 클릭: onNodeSelect가 제공된 경우 호출
• 폴더 선택 (selectFolders): 폴더 행 클릭은 onNodeSelect 만 부르고 펼침/접힘은 셰브론이 맡습니다. toggleFoldersOnSelect: true 를 함께 주면 행 어디를 눌러도 선택과 펼침/접힘이 함께 일어나고, 셰브론은 여전히 펼침/접힘만 합니다 — 폴더를 위임 대상으로 고르면서 행 전체로 여닫는 IDE 파일 트리 관례입니다.
• 이름 바꾸기 (onNodeRename): 행을 더블클릭하거나 행에 포커스가 있을 때 F2 를 누르면 라벨 자리가 현재 이름이 든 입력칸으로 바뀝니다. leaf 는 마지막 점 앞까지(main.dart → main), 가지는 전체가 선택된 채 열립니다. Enter 를 누르거나 입력칸 밖을 누르면(또는 포커스가 빠지면) 확정, Esc 는 취소입니다. 앞뒤 공백을 다듬은 이름이 비었거나 그대로면 보고하지 않습니다(CoreTreeRenameRules.committedLabel). 디스크·데이터 반영과 새 노드 전달은 드롭과 같이 소비자가 맡습니다.
• 더블클릭과 단일 클릭: 더블클릭의 첫 클릭은 기다리지 않고 평소대로 동작하고(선택·펼침), 두 번째 클릭만 이름 바꾸기로 갑니다 — 단일 클릭이 느려지지 않습니다. 이름을 바꾸는 동안 그 행은 누름·드래그를 받지 않고, 입력칸의 키 입력은 트리 키보드 처리로 새지 않습니다.
• 밖에서 시작 (controller): 키보드 모델이 행 밖에 있는 소비자(자기 커서를 움직이고 행에는 포커스를 주지 않는 IDE 탐색기 등)는 행 단위 F2 에 닿지 못합니다. CoreTreeController 를 넘기고 startRename(노드 id) 를 부르면 그 행이 더블클릭·F2 와 똑같이 열립니다. 보이지 않는 행(조상이 접힘·없는 id)과 canRenameNode 가 거부한 행은 무시합니다. 끝나면 포커스가 트리로 돌아옵니다 — Flutter 는 시작 전 포커스(바깥 Focus)로, Web 은 그 행(로빙 탭 스톱)으로.
• 노드 맥락 메뉴 (nodeContextMenu): 행을 우클릭(터치는 길게 누르기)하면 그 노드의 항목이 포인터 위치 메뉴로 열립니다(ContextMenu). 우클릭은 행을 선택하지도 펼치지도 않습니다. 빈 목록을 돌려준 노드와 이름을 바꾸는 행에는 메뉴가 없습니다. 「이름 바꾸기」 항목은 CoreTreeController.startRename(node.id) 로 이으면 됩니다.
• 아이콘: 자식 있음 → 펼침 folderOpen / 접힘 folderClosed + chevron, 없음 → file. leadingBuilder 를 주면 그쪽이 우선합니다.
• 색: chevron 은 행이 선택됐는지와 상관없이 항상 onSurfaceSubtle 입니다(chevronIconStyle.color 로 덮음). 파일(leaf) 아이콘은 onSurfaceSubtle(leafIconStyle.color 로 덮음), 폴더 아이콘은 onSurfaceVariant 로 한 단계 진하게 그려져 폴더와 파일이 구분됩니다. 이름 글자만 선택 상태에 따라 onSurfaceVariant / onSurface 로 바뀝니다.
• 줄 크기: 행 최소 높이 28px(nodeMinHeight), 세로 패딩 0, 깊이당 들여쓰기 18px(indent)입니다. 기본 행 높이는 패딩이 아니라 nodeMinHeight 가 정하며, 라벨 줄 상자에 세로 패딩을 더한 높이가 이를 넘으면 그 높이로 커집니다.
• 줄 끝 요소 (trailingBuilder): 이름이 남은 폭을 모두 차지해(길면 말줄임) trailing 이 줄 끝에 맞춰지고, 이름과 trailing 사이에는 labelGapStyle 간격이 놓입니다. 깃 변경 표시(M·A·D)처럼 어떤 색·글자를 쓸지는 제품 내용이라 Core 스타일에 두지 않고, 호출 쪽이 Text(...) 체인으로 직접 그립니다.
• 미적재 폴더: canHaveChildren: true 로 선언합니다. children: [] 만으로는 파일과 빈 폴더를 구분할 수 없습니다. loadChildren 성공 후 빈 결과도 캐시하며, 오류 후 행의 재시도 동작을 제공합니다.
• 노드 정체성: id가 있으면 폴더 확장 상태와 행 Key가 형제의 추가·정렬에도 유지됩니다. 없으면 종전 인덱스·라벨 기준입니다. 파일 작업·데이터 갱신은 소비자가 소유합니다.
• 드롭: onNodeDrop을 주면 안정적인 id가 있는 노드만 드래그할 수 있습니다. 폴더(canHaveChildren 또는 이미 적재된 자식)만 대상이며 자신·적재된 자손 대상은 거부합니다. CoUI의 DragScope·DragItem·DropZone이 포인터/키보드 입력과 표시를 맡고, 파일 이동·권한·충돌 검사와 새 노드 전달은 소비자가 맡습니다. 소비자의 canDrop으로 작업 중인 항목 같은 추가 제약을 설정하세요.

Tree(
  nodes: const [CoreTreeNode(id: 'src', label: 'src', canHaveChildren: true)],
  loadChildren: (node) => repository.children(node.id!),
  selectFolders: true,
  onNodeSelect: (node) => select(node.id!),
  leadingBuilder: (context, node, {required expanded}) =>
      Icon(expanded ? LucideIcons.folderOpen : LucideIcons.folderClosed),
  virtualRowHeight: 36,
  virtualViewportHeight: 300,
)

애니메이션#

• 자식이 있는 노드의 chevron 회전: Duration(milliseconds: CoreDuration.fast) (150ms)
• Flutter AnimatedRotation, Web transition-transform 동일 duration

사용 가이드라인 (Usage Guidelines)#

부모·자식 노드의 펼침·선택·지연 적재·이름 바꾸기가 필요하면 Tree를 사용합니다. 고정 콘텐츠 섹션의 접기/펼치기는 Accordion, 단일 영역은 Collapsible, 명령·이동 항목을 담는 메뉴는 Menu를 선택합니다. Tree는 파일 이동·이름 저장을 직접 수행하지 않고 소비자 콜백에 의도를 전달합니다.

✅ Do#

Tree(
  nodes: nodes, // CoreTreeNode.expanded 는 최초 펼침 상태만 지정
  onNodeToggle: (node) {
    // 펼침/접힘 결과를 앱 상태에도 반영하고 싶다면 여기서 받는다
    trackExpanded(node);
  },
)

❌ Don't#

// ❌ 이미 마운트된 Tree는 새 expanded 값을 다시 읽지 않는다
setState(() {
  nodes = [
    CoreTreeNode(label: 'Documents', expanded: false, children: [...]),
  ];
});

✅ Do#

Tree(
  nodes: [CoreTreeNode(label: 'README.md')], // leaf
  onNodeSelect: (node) => openFile(node.label),
)

❌ Don't#

// ❌ onNodeSelect 를 안 주면 leaf 행은 애초에 Clickable로 감싸지지 않는다
Tree(nodes: nodes)

접근성 (Accessibility)#

역할#

• Web — role="tree" / role="treeitem" 과 aria-level·aria-posinset· aria-setsize(DOM 이 평평하므로 계층을 행마다 적습니다), 부모 행의 aria-expanded, 선택 가능한 행의 aria-selected.
• Flutter — tree role 없음. Flutter 에는 대응 role 이 없어 계층은 각 노드의 확장 상태로 전달됩니다(설계상 의도된 비대칭).

키보드#

Web 은 WAI-ARIA 트리 패턴을 따릅니다. 표시 전용 leaf(onNodeSelect 없음)도 treeitem 으로 순회에 포함됩니다 — 키보드가 닿지 못하는 행은 스크린 리더도 읽지 못합니다. 폴더 chevron(selectFolders: true)은 포인터 전용이라 별도 tab stop 이 아닙니다.

Flutter 의 화살표 이동은 이 컴포넌트가 아니라 프레임워크의 방향성 포커스 순회입니다 — 트리에 스코프되지 않아 트리 밖 요소로도 넘어가고, 확장·축소도 하지 않습니다.

브라우저 검증 — 이 컴포넌트의 Web 키보드 이동은 야간 파리티 스윕의 키보드 프로브(tool/parity/keyboard_probe.dart)가 하이드레이션된 문서 사이트에서 실제로 키를 눌러, 포커스가 기대한 항목으로 옮겨 갔는지 확인합니다. 핸들러가 달렸는지가 아니라 포커스가 어디에 있는지를 봅니다.

스크린 리더#

Web 은 라벨·treeitem·깊이·형제 중 위치·확장 상태를 읽습니다. aria-selected 는 선택이 의미 있는 행(선택 가능하거나 선택된 행)에만 붙습니다 — 아무도 선택하지 않는 트리에서 모든 행마다 "선택 안 됨"을 읽지 않습니다.

노드를 펼치거나 접은 결과를 알리는 live region 은 없습니다.

포커스 관리#

• 진입 / 트랩 — 트랩 없음. Tab 은 트리에 한 번 들어와 마지막으로 머문 행에 멈추고, 다음 Tab 은 트리 밖으로 나갑니다(Web).
• 노드를 접을 때 — Web 은 tab stop 이 접힌 하위에 있었다면 접힌 부모로 옮깁니다. Flutter 는 사라진 행에 포커스가 있었다면 상위 스코프로 떨어집니다.

알려진 제약#

• Flutter 는 노드 수만큼 tab stop 이 생기고 화살표 확장/축소가 없습니다(Web 과 비대칭).

크로스 플랫폼 차이점 (Platform Differences)#

관련 컴포넌트 (Related Components)#

• Accordion: 고정된 수의 섹션을 그룹으로 접기/펼치기
• Menu: 계층 없는 평면 메뉴 목록
• Collapsible: 단일 섹션의 접기/펼치기

빠른 오버라이드 (Chain)#

이미 만든 Tree 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다. .radius4처럼 Core 토큰 상수 이름과 똑같은 이름의 getter도 있습니다 — withStyle을 한 번 더 줄인 sugar로, 이름이 곧 값이라(radius4 == CoreRadius.radius4) 어느 컴포넌트에서 써도 뜻이 갈리지 않습니다.

class TreeChainExample extends StatelessWidget {
  const TreeChainExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Tree(
          nodes: [
            CoreTreeNode(
              label: 'Documents',
              expanded: true,
              children: [
                CoreTreeNode(label: 'Resume.pdf'),
                CoreTreeNode(label: 'Cover Letter.pdf'),
              ],
            ),
            CoreTreeNode(
              label: 'Images',
              children: [
                CoreTreeNode(label: 'photo.png'),
                CoreTreeNode(label: 'banner.jpg'),
              ],
            ),
            CoreTreeNode(label: 'README.md'),
          ],
        )
        .withStyle(
          const CoreTreeStyle(
            nodeBackgroundColor: CoreColor.token(CoreColors.surfaceContainer),
            nodePadding: CoreEdgeInsets.symmetric(
              horizontal: CoreSpace.space12,
              vertical: CoreSpace.space8,
            ),
            indent: CoreSpace.space24,
          ),
        )
        .radius16;
  }
}

class TreeChainExample extends StatelessComponent {
  const TreeChainExample({super.key});

  @override
  Component build(BuildContext context) {
    return const Tree(
          nodes: [
            CoreTreeNode(
              label: 'Documents',
              expanded: true,
              children: [
                CoreTreeNode(label: 'Resume.pdf'),
                CoreTreeNode(label: 'Cover Letter.pdf'),
              ],
            ),
            CoreTreeNode(
              label: 'Images',
              children: [
                CoreTreeNode(label: 'photo.png'),
                CoreTreeNode(label: 'banner.jpg'),
              ],
            ),
            CoreTreeNode(label: 'README.md'),
          ],
        )
        .withStyle(
          const CoreTreeStyle(
            nodeBackgroundColor: CoreColor.token(CoreColors.surfaceContainer),
            nodePadding: CoreEdgeInsets.symmetric(
              horizontal: CoreSpace.space12,
              vertical: CoreSpace.space8,
            ),
            indent: CoreSpace.space24,
          ),
        )
        .radius16;
  }
}