Sortable#

드래그 앤 드롭으로 항목의 순서를 변경할 수 있는 정렬 가능한 리스트 컴포넌트입니다.

Live Preview#

class SortableDefaultExample extends StatefulComponent {
  const SortableDefaultExample({super.key});

  @override
  State<SortableDefaultExample> createState() => _SortableDefaultExampleState();
}

class _SortableDefaultExampleState extends State<SortableDefaultExample> {
  List<String> _items = const ['Item 1', 'Item 2', 'Item 3'];

  void handleReorder(int oldIndex, int newIndex) {
    setState(() {
      final newItems = [..._items];
      final item = newItems.removeAt(oldIndex);
      newItems.insert(newIndex, item);
      _items = newItems;
    });
  }

  @override
  Component build(BuildContext context) {
    return Sortable(
      itemCount: _items.length,
      onReorder: handleReorder,
      itemBuilder: (index, dragHandle, removeButton) => div(
        [
          dragHandle,
          span([Text(_items[index])]),
        ],
        classes: 'flex items-center flex-1 gap-${CoreSpace.scale.space8}',
      ),
    );
  }
}

class SortableDefaultExample extends StatefulWidget {
  const SortableDefaultExample({super.key});

  @override
  State<SortableDefaultExample> createState() => _SortableDefaultExampleState();
}

class _SortableDefaultExampleState extends State<SortableDefaultExample> {
  List<String> _items = const ['Item 1', 'Item 2', 'Item 3'];

  void handleReorder(int oldIndex, int newIndex) {
    setState(() {
      final newItems = [..._items];
      final item = newItems.removeAt(oldIndex);
      newItems.insert(newIndex, item);
      _items = newItems;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Sortable(
      itemCount: _items.length,
      onReorder: handleReorder,
      itemBuilder: (context, index, dragHandle, removeButton) {
        return Row(
          mainAxisSize: MainAxisSize.min,
          spacing: CoreSpace.space8,
          children: [
            dragHandle,
            Text(_items[index]),
          ],
        );
      },
    );
  }
}

class SortableChainExample extends StatefulComponent {
  const SortableChainExample({super.key});

  @override
  State<SortableChainExample> createState() => _SortableChainExampleState();
}

class _SortableChainExampleState extends State<SortableChainExample> {
  List<String> _items = const ['Item 1', 'Item 2', 'Item 3'];

  void handleReorder(int oldIndex, int newIndex) {
    setState(() {
      final newItems = [..._items];
      final item = newItems.removeAt(oldIndex);
      newItems.insert(newIndex, item);
      _items = newItems;
    });
  }

  @override
  Component build(BuildContext context) {
    return Sortable(
      itemCount: _items.length,
      onReorder: handleReorder,
      itemBuilder: (index, dragHandle, removeButton) => div(
        [
          dragHandle,
          span([Text(_items[index])]),
        ],
        classes: 'flex items-center flex-1 gap-${CoreSpace.scale.space8}',
      ),
    ).withStyle(
      const CoreSortableStyle(
        itemBackgroundColor: CoreColor.token(CoreColors.surfaceContainerHigh),
        itemBorderRadius: CoreBorderRadius.all(CoreRadius.radius16),
        itemPadding: CoreEdgeInsets.symmetric(
          horizontal: CoreSpace.space16,
          vertical: CoreSpace.space12,
        ),
        handleColor: CoreColor.token(CoreColors.primary),
      ),
    );
  }
}

class SortableChainExample extends StatefulWidget {
  const SortableChainExample({super.key});

  @override
  State<SortableChainExample> createState() => _SortableChainExampleState();
}

class _SortableChainExampleState extends State<SortableChainExample> {
  List<String> _items = const ['Item 1', 'Item 2', 'Item 3'];

  void handleReorder(int oldIndex, int newIndex) {
    setState(() {
      final newItems = [..._items];
      final item = newItems.removeAt(oldIndex);
      newItems.insert(newIndex, item);
      _items = newItems;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Sortable(
      itemCount: _items.length,
      onReorder: handleReorder,
      itemBuilder: (context, index, dragHandle, removeButton) {
        return Row(
          mainAxisSize: MainAxisSize.min,
          spacing: CoreSpace.space8,
          children: [
            dragHandle,
            Text(_items[index]),
          ],
        );
      },
    ).withStyle(
      const CoreSortableStyle(
        itemBackgroundColor: CoreColor.token(CoreColors.surfaceContainerHigh),
        itemBorderRadius: CoreBorderRadius.all(CoreRadius.radius16),
        itemPadding: CoreEdgeInsets.symmetric(
          horizontal: CoreSpace.space16,
          vertical: CoreSpace.space12,
        ),
        handleColor: CoreColor.token(CoreColors.primary),
      ),
    );
  }
}

사용 시기 (When to Use)#

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

• 사용자가 항목의 우선순위나 순서를 직접 지정해야 하는 경우 (할 일 목록, 메뉴 순서 등)
• 대시보드 위젯, 사이드바 메뉴 순서를 사용자가 커스터마이즈할 수 있어야 하는 경우
• 카테고리나 태그의 노출 순서를 관리자가 직접 설정해야 하는 경우

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

• Table: 정렬이 필요 없는 단순 데이터 표시 테이블
• Tree: 항목 간 계층 구조(부모-자식)가 있는 경우

기본 사용법 (Basic Usage)#

Sortable(
  itemCount: items.length,
  onReorder: (oldIndex, newIndex) {
    setState(() {
      final newItems = [...items];
      final item = newItems.removeAt(oldIndex);
      newItems.insert(newIndex, item);
      items = newItems;
    });
  },
  itemBuilder: (context, index, dragHandle, removeButton) {
    return Row(
      children: [
        dragHandle,
        Expanded(child: Text(items[index])),
        if (removeButton != null) removeButton,
      ],
    );
  },
)

Sortable(
  itemCount: items.length,
  onReorder: (oldIndex, newIndex) => reorderItems(oldIndex, newIndex),
  itemBuilder: (index, dragHandle, removeButton) => div(
    [
      dragHandle,
      Text(items[index]).bodyMedium.onSurface,
      if (removeButton != null) removeButton,
    ],
    classes: 'flex items-center flex-1',
  ),
)

빠른 오버라이드 (Chain)#

이미 만든 Sortable 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다.

class SortableChainExample extends StatefulWidget {
  const SortableChainExample({super.key});

  @override
  State<SortableChainExample> createState() => _SortableChainExampleState();
}

class _SortableChainExampleState extends State<SortableChainExample> {
  List<String> _items = const ['Item 1', 'Item 2', 'Item 3'];

  void handleReorder(int oldIndex, int newIndex) {
    setState(() {
      final newItems = [..._items];
      final item = newItems.removeAt(oldIndex);
      newItems.insert(newIndex, item);
      _items = newItems;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Sortable(
      itemCount: _items.length,
      onReorder: handleReorder,
      itemBuilder: (context, index, dragHandle, removeButton) {
        return Row(
          mainAxisSize: MainAxisSize.min,
          spacing: CoreSpace.space8,
          children: [
            dragHandle,
            Text(_items[index]),
          ],
        );
      },
    ).withStyle(
      const CoreSortableStyle(
        itemBackgroundColor: CoreColor.token(CoreColors.surfaceContainerHigh),
        itemBorderRadius: CoreBorderRadius.all(CoreRadius.radius16),
        itemPadding: CoreEdgeInsets.symmetric(
          horizontal: CoreSpace.space16,
          vertical: CoreSpace.space12,
        ),
        handleColor: CoreColor.token(CoreColors.primary),
      ),
    );
  }
}

class SortableChainExample extends StatefulComponent {
  const SortableChainExample({super.key});

  @override
  State<SortableChainExample> createState() => _SortableChainExampleState();
}

class _SortableChainExampleState extends State<SortableChainExample> {
  List<String> _items = const ['Item 1', 'Item 2', 'Item 3'];

  void handleReorder(int oldIndex, int newIndex) {
    setState(() {
      final newItems = [..._items];
      final item = newItems.removeAt(oldIndex);
      newItems.insert(newIndex, item);
      _items = newItems;
    });
  }

  @override
  Component build(BuildContext context) {
    return Sortable(
      itemCount: _items.length,
      onReorder: handleReorder,
      itemBuilder: (index, dragHandle, removeButton) => div(
        [
          dragHandle,
          span([Text(_items[index])]),
        ],
        classes: 'flex items-center flex-1 gap-${CoreSpace.scale.space8}',
      ),
    ).withStyle(
      const CoreSortableStyle(
        itemBackgroundColor: CoreColor.token(CoreColors.surfaceContainerHigh),
        itemBorderRadius: CoreBorderRadius.all(CoreRadius.radius16),
        itemPadding: CoreEdgeInsets.symmetric(
          horizontal: CoreSpace.space16,
          vertical: CoreSpace.space12,
        ),
        handleColor: CoreColor.token(CoreColors.primary),
      ),
    );
  }
}

Props / Parameters#

Web 은 위 파라미터에 더해 id / classes / css / attributes 와 DOM 이벤트 슬롯(onClick / onKeyDown 등)을 받아 루트 <div> 로 통과시킵니다.

CoreSortableStyle 필드#

제거 가능한 항목 (Removable Items)#

Sortable(
  itemCount: items.length,
  onReorder: handleReorder,
  onRemove: (index) {
    setState(() {
      items = [
        ...items.sublist(0, index),
        ...items.sublist(index + 1),
      ];
    });
  },
  removable: true,
  itemBuilder: (context, index, dragHandle, removeButton) {
    return Row(
      children: [
        dragHandle,
        Expanded(child: Text(items[index])),
        if (removeButton != null) removeButton,
      ],
    );
  },
)

테마 커스터마이징 (Theme Customization)#

CoreComponentTheme.sortable을 통해 프로젝트 레벨에서 스타일을 오버라이드할 수 있습니다.

CoreComponentTheme(
  sortable: CoreSortableTheme(
    style: CoreSortableStyle(
      itemBackgroundColor: CoreColor.token(CoreColors.surfaceContainer),
      itemBorderRadius: CoreBorderRadius.all(CoreRadius.radius8),
      handleColor: CoreColor.token(CoreColors.onSurfaceVariant),
      itemSpacing: CoreSpace.space12,
    ),
  ),
)

동작 스펙 (Behavior)#

인터랙션#

• 드래그 핸들을 잡아 끌면 순서가 바뀝니다. 충돌 판정과 재정렬 계산은 양 플랫폼이 같은 coui_core 엔진(CoreSortable.resolve)을 쓰므로 결과가 동일합니다.
• 드래그 중 나머지 항목은 animationDuration 동안 실시간으로 밀려납니다.
• axis: CoreSortableAxis.grid 면 주축 하나로 환원할 수 없으므로 2D 근접도로 착지 위치를 정합니다.

커서#

• 드래그 핸들은 Web 에서 cursor: grab / cursor: grabbing 을 표시합니다. 역할 · 키보드 · 포커스는 아래 접근성 절에 정리되어 있습니다 (양 플랫폼이 비대칭입니다).

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

✅ Do#

Sortable(
  itemCount: items.length,
  itemBuilder: itemBuilder,
  removable: true,
  onRemove: (index) => handleRemove(index),
)

❌ Don't#

// ❌ 제거 버튼은 보이지만 클릭해도 아무 동작 없음
Sortable(
  itemCount: items.length,
  itemBuilder: itemBuilder,
  removable: true,
)

✅ Do#

itemBuilder: (context, index, dragHandle, removeButton) => Row(
  children: [
    dragHandle,
    Expanded(child: Text(items[index]).bodyMedium),
    if (removeButton != null) removeButton,
  ],
),

❌ Don't#

// ❌ 텍스트 라벨 없이 아이콘만
itemBuilder: (context, index, dragHandle, removeButton) => Row(
  children: [dragHandle, Icon(LucideIcons.file), if (removeButton != null) removeButton],
),

접근성 (Accessibility)#

역할 (Semantics)#

두 플랫폼이 비대칭입니다.

• Web: 루트 <div> 에 role="list", 각 행에 role="listitem" 이 붙습니다. 재정렬이 가능한 경우(enabled && onReorder != null) 각 행은 합성된 DragItem 이 한 겹 더 감싸며, 그 래퍼가 role="application" · aria-grabbed · aria-disabled 를 내보냅니다. Sortable 은 DragItem 에 label / hint 를 넘기지 않으므로 aria-label · aria-description 은 생략됩니다. 제거 버튼은 native <button type="button"> 입니다.
• Flutter: 역할이 하나도 없습니다. DragItem 은 Semantics(enabled:) 만 내보내고 (label / hint 미전달), 제거 버튼은 Clickable 이 주는 Semantics(button: true) 를 받습니다. list / listitem 에 해당하는 시맨틱은 존재하지 않습니다.

키보드#

재정렬 키보드 조작은 양 플랫폼에 있으며, enabled 가 true 이고 onReorder 가 있을 때만 그리고 행 래퍼에 포커스가 있을 때만 동작합니다.

Tab / Shift+Tab 은 행과 제거 버튼 사이를 오갑니다. 드래그 핸들 자체는 어떤 키도 처리하지 않습니다.

포커스#

• Flutter: DragItem 이 FocusNode 를 소유하고 canRequestFocus 를 enabled 에 묶으므로 재정렬 가능한 행이 탭으로 도달됩니다. 제거 버튼은 Clickable 의 FocusableActionDetector 로 포커스되며 디자인 시스템 포커스 링(FocusOutline)을 그립니다.
• Web: DragItem 이 활성 시 tabindex="0", 비활성 시 "-1" 을 붙입니다 — 이 컴포넌트에서 tabindex 를 만드는 곳은 여기뿐입니다. 제거 버튼은 native <button> 으로 포커스됩니다. Web 은 자체 포커스 링 CSS 를 내보내지 않아 브라우저 기본 outline 에 의존합니다.
• 드래그 핸들은 양 플랫폼 모두 포커스를 받지 않습니다 — cursor: grab 만 있는 표시용 요소입니다.
• 재정렬이나 제거 이후 포커스를 복원하지 않으며, 포커스를 가두지도 않습니다.

스크린 리더#

• Web: 컨테이너는 리스트로, 행은 리스트 항목으로 안내되지만, 재정렬 경로에서는 role="application" 래퍼가 사이에 끼어 list > application > listitem 구조가 되므로 리스트–항목 관계가 끊깁니다. 포커스된 행은 이름 없는 application 영역과 aria-grabbed 상태로 읽힙니다. 제거 버튼의 이름은 본문 글리프 ✕ 가 전부입니다.
• Flutter: 행에는 이름도 힌트도 역할도 없고 enabled 만 실립니다. 제거 버튼은 이름 없는 버튼으로 읽힙니다(아이콘에 semanticLabel 이 없음).
• 양 플랫폼 모두 위치(전체 몇 개 중 몇 번째) · 현재 드롭 대상 · 재정렬 결과를 안내하지 않습니다. live region 이나 안내 훅이 코드에 존재하지 않습니다.

알려진 제약#

• 이름이 없습니다. Sortable 은 DragItem 에 label / hint 를 전달하지 않고, 제거 버튼도 라벨이 없습니다(Web ✕ 글리프, Flutter 무명). 항목을 소리로 구분해야 한다면 소비자가 itemBuilder 안에서 직접 라벨 있는 콘텐츠를 넣어야 합니다.
• 키보드로 재정렬해도 결과가 들리지 않습니다 — aria-posinset · aria-setsize · live region 이 없어 항목이 어디에 놓였는지 알 수 없습니다. 순서가 중요한 데이터라면 소비자가 별도의 상태 안내를 붙여야 합니다.
• 눈에 보이는 어포던스(드래그 핸들)가 포커스를 받지 못합니다. 키보드 드래그는 행 래퍼에서 시작해야 하는데 그 사실을 알리는 힌트가 없어, 기능이 있어도 발견되지 않습니다.
• Web 의 행별 role="application" 은 그 안에서 브라우저 읽기 모드를 억제하고 listitem 을 한 단계 깊게 중첩시킵니다.
• Flutter 에는 list / listitem 시맨틱이 아예 없어 같은 코드가 두 플랫폼에서 다르게 읽힙니다.
• enabled: false 이거나 onReorder 가 없으면 Flutter 는 포커스도 키 처리도 없는 껍데기를 렌더하고, Web 은 role="list" / "listitem" 은 유지하되 tabindex 와 모든 키 조작을 잃습니다.

reduced motion · 고대비 · 최소 터치 타겟 등 컴포넌트를 가로지르는 축은 전역 접근성 축에서 다룹니다.

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

관련 컴포넌트 (Related Components)#

• Table: 데이터를 표 형태로 표시하며 컬럼 정렬이 필요한 경우
• Tree: 계층 구조로 된 항목의 순서를 변경해야 하는 경우