Tree#

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

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'),
      ],
    );
  }
}

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

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

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

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

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;
  }
}

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;
  }
}

사용 시기 (When to Use)#

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

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

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

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

기본 사용법 (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}'),
)

Props / Parameters#

스타일 시스템 (Style System)#

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

시맨틱 vs 스타일#

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

Resolve chain#

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

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

CoreTreeStyle 필드#

동작 스펙 (Behavior)#

인터랙션#

• 자식이 있는 노드 클릭: 펼침/접힘 토글. onNodeToggle 호출
• 자식이 없는 노드(leaf) 클릭: onNodeSelect가 제공된 경우 호출
• 아이콘: 자식 있음 → folder + chevron, 없음 → file

애니메이션#

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

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

✅ 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-expanded·aria-selected.
• Flutter — tree role 없음. Flutter 에는 대응 role 이 없어 계층은 각 노드의 확장 상태로 전달됩니다(설계상 의도된 비대칭).

키보드#

WAI-ARIA 트리 탐색이 구현돼 있지 않습니다. 확장·축소는 Enter/Space 로만 가능하고 화살표로는 되지 않습니다.

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

스크린 리더#

Web 은 라벨·treeitem·확장 상태·선택 상태를 읽습니다. 단 aria-selected 가 인터랙티브 행 전부에 무조건 붙습니다 — 선택이 하나도 없는 트리에서도 리더가 모든 행마다 "선택 안 됨"을 읽습니다.

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

포커스 관리#

• 진입 / 트랩 — 없음. Tab 은 트리 밖으로 그대로 빠져나갑니다.
• 노드를 접으면 포커스를 잃습니다 — 사라진 행에 포커스가 있었다면 Flutter 는 상위 스코프로, Web 은 <body> 로 떨어집니다. 부모 노드로 옮겨주는 코드가 없습니다.

알려진 제약#

• 노드 수만큼 tab stop 이 생깁니다. 깊고 넓은 트리는 키보드로 지나가는 비용이 노드 수에 비례합니다.
• 단일 선택 트리에서도 모든 행에 aria-selected="false" 가 붙습니다.

크로스 플랫폼 차이점 (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;
  }
}