CodeDiff

코드 변경 사항을 라인 단위로 비교해서 보여주는 read-only viewer입니다. 추가된 라인은 success 톤으로, 삭제된 라인은 error 톤으로 강조하며 변경 없는 라인은 그대로 둡니다. PR 리뷰, 변경 이력 표시, 마이그레이션 가이드 등에 사용합니다.

이미지나 텍스트 두 가지를 좌우로 비교하는 split-view UI 가 필요하다면 Diff 컴포넌트를 사용하세요.

Live Preview#

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

  @override
  Component build(BuildContext context) {
    return const CodeDiff(
      lines: [
        CoreCodeDiffLine(
          text: "import 'package:coui_web/coui_web.dart';",
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 1,
        ),
        CoreCodeDiffLine(
          text: '',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 2,
        ),
        CoreCodeDiffLine(
          text: 'class MyWidget extends StatelessComponent {',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 3,
        ),
        CoreCodeDiffLine(
          text: '  Component build(BuildContext context) {',
          type: CoreCodeDiffLineType.removed,
          lineNumber: 4,
        ),
        CoreCodeDiffLine(
          text: '  Component build(BuildContext context) {',
          type: CoreCodeDiffLineType.added,
          lineNumber: 4,
        ),
        CoreCodeDiffLine(
          text: "    return text('Hello');",
          type: CoreCodeDiffLineType.removed,
          lineNumber: 5,
        ),
        CoreCodeDiffLine(
          text: "    return Text('Hello').bodyMedium;",
          type: CoreCodeDiffLineType.added,
          lineNumber: 5,
        ),
        CoreCodeDiffLine(
          text: '  }',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 6,
        ),
        CoreCodeDiffLine(
          text: '}',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 7,
        ),
      ],
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return const CodeDiff(
      lines: [
        CoreCodeDiffLine(
          text: "import 'package:coui_flutter/coui_flutter.dart';",
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 1,
        ),
        CoreCodeDiffLine(
          text: '',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 2,
        ),
        CoreCodeDiffLine(
          text: 'class MyWidget extends StatelessWidget {',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 3,
        ),
        CoreCodeDiffLine(
          text: '  Widget build(BuildContext context) {',
          type: CoreCodeDiffLineType.removed,
          lineNumber: 4,
        ),
        CoreCodeDiffLine(
          text: '  Widget build(BuildContext context) {',
          type: CoreCodeDiffLineType.added,
          lineNumber: 4,
        ),
        CoreCodeDiffLine(
          text: "    return Text('Hello');",
          type: CoreCodeDiffLineType.removed,
          lineNumber: 5,
        ),
        CoreCodeDiffLine(
          text: "    return Text('Hello').bodyMedium;",
          type: CoreCodeDiffLineType.added,
          lineNumber: 5,
        ),
        CoreCodeDiffLine(
          text: '  }',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 6,
        ),
        CoreCodeDiffLine(
          text: '}',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 7,
        ),
      ],
    );
  }
}

사용 시기 (When to Use)#

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

• PR / 커밋 변경 사항을 라인 단위로 보여줄 때
• 마이그레이션 가이드에서 "이전 → 이후" 코드를 강조할 때
• 변경 이력(audit log)을 코드 형태로 보여줄 때

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

• CodeSnippet: 단일 코드 블록을 보여줄 때 (변경 표시 없음)
• Diff: 코드 행 데이터의 추가/삭제 대신 두 콘텐츠 층을 분할선으로 비교할 때

빠른 오버라이드 (Chain)#

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

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

  @override
  Widget build(BuildContext context) {
    return const CodeDiff(
      lines: [
        CoreCodeDiffLine(
          text: "import 'package:coui_flutter/coui_flutter.dart';",
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 1,
        ),
        CoreCodeDiffLine(
          text: '',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 2,
        ),
        CoreCodeDiffLine(
          text: 'class MyWidget extends StatelessWidget {',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 3,
        ),
        CoreCodeDiffLine(
          text: '  Widget build(BuildContext context) {',
          type: CoreCodeDiffLineType.removed,
          lineNumber: 4,
        ),
        CoreCodeDiffLine(
          text: '  Widget build(BuildContext context) {',
          type: CoreCodeDiffLineType.added,
          lineNumber: 4,
        ),
        CoreCodeDiffLine(
          text: "    return Text('Hello');",
          type: CoreCodeDiffLineType.removed,
          lineNumber: 5,
        ),
        CoreCodeDiffLine(
          text: "    return Text('Hello').bodyMedium;",
          type: CoreCodeDiffLineType.added,
          lineNumber: 5,
        ),
        CoreCodeDiffLine(
          text: '  }',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 6,
        ),
        CoreCodeDiffLine(
          text: '}',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 7,
        ),
      ],
    ).withStyle(
      const CoreCodeDiffStyle(
        cornerRadius: CoreBorderRadius.all(CoreRadius.radius4),
        borderWidth: CoreStrokeWidth.stroke2,
        outlineColor: CoreColor.token(CoreColors.primary),
        addedBackgroundColor: CoreColor.token(CoreColors.infoContainer),
        addedForegroundColor: CoreColor.token(CoreColors.onInfoContainer),
        removedBackgroundColor: CoreColor.token(CoreColors.warningContainer),
        removedForegroundColor: CoreColor.token(CoreColors.onWarningContainer),
        linePadding: CoreEdgeInsets.symmetric(
          horizontal: CoreSpace.space16,
          vertical: CoreSpace.space4,
        ),
      ),
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return const CodeDiff(
      lines: [
        CoreCodeDiffLine(
          text: "import 'package:coui_web/coui_web.dart';",
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 1,
        ),
        CoreCodeDiffLine(
          text: '',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 2,
        ),
        CoreCodeDiffLine(
          text: 'class MyWidget extends StatelessComponent {',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 3,
        ),
        CoreCodeDiffLine(
          text: '  Component build(BuildContext context) {',
          type: CoreCodeDiffLineType.removed,
          lineNumber: 4,
        ),
        CoreCodeDiffLine(
          text: '  Component build(BuildContext context) {',
          type: CoreCodeDiffLineType.added,
          lineNumber: 4,
        ),
        CoreCodeDiffLine(
          text: "    return text('Hello');",
          type: CoreCodeDiffLineType.removed,
          lineNumber: 5,
        ),
        CoreCodeDiffLine(
          text: "    return Text('Hello').bodyMedium;",
          type: CoreCodeDiffLineType.added,
          lineNumber: 5,
        ),
        CoreCodeDiffLine(
          text: '  }',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 6,
        ),
        CoreCodeDiffLine(
          text: '}',
          type: CoreCodeDiffLineType.unchanged,
          lineNumber: 7,
        ),
      ],
    ).withStyle(
      const CoreCodeDiffStyle(
        cornerRadius: CoreBorderRadius.all(CoreRadius.radius4),
        borderWidth: CoreStrokeWidth.stroke2,
        outlineColor: CoreColor.token(CoreColors.primary),
        addedBackgroundColor: CoreColor.token(CoreColors.infoContainer),
        addedForegroundColor: CoreColor.token(CoreColors.onInfoContainer),
        removedBackgroundColor: CoreColor.token(CoreColors.warningContainer),
        removedForegroundColor: CoreColor.token(CoreColors.onWarningContainer),
        linePadding: CoreEdgeInsets.symmetric(
          horizontal: CoreSpace.space16,
          vertical: CoreSpace.space4,
        ),
      ),
    );
  }
}

Props / Parameters#

본문은 codeMd, 라인 번호 거터는 codeSm 코드 역할로 렌더링되어 고정폭입니다. + / - / prefix 정렬은 고정폭 라인 번호 거터와 두 글자 prefix span 으로 보장됩니다. 추가·삭제 행은 불투명 컨테이너 토큰 밴드에 앉고, 본문 글자는 모든 행에서 onSurface 입니다.

CoreCodeDiffLine — 라인 데이터#

위젯 파라미터가 아니라 lines 에 담아 넘기는 plain Dart 데이터 클래스입니다 (양 플랫폼 동일 모양).

CoreCodeDiffStyle 필드#

예제#

CodeDiff(
  lines: [
    CoreCodeDiffLine(
      text: 'class MyWidget extends StatelessWidget {',
      type: CoreCodeDiffLineType.unchanged,
      lineNumber: 1,
    ),
    CoreCodeDiffLine(
      text: "  return Text('Hello');",
      type: CoreCodeDiffLineType.removed,
      lineNumber: 2,
    ),
    CoreCodeDiffLine(
      text: "  return Text('Hello').bodyMedium;",
      type: CoreCodeDiffLineType.added,
      lineNumber: 2,
    ),
  ],
)

동작 스펙 (Behavior)#

• lines 를 받은 순서대로 렌더합니다. added는 + , removed는 - , unchanged는 공백 prefix이며 두 파일의 diff를 자동 계산하지 않습니다.
• 줄 번호는 showLineNumbers 가 참이고 각 행의 lineNumber 가 있을 때만 표시합니다. 번호를 새로 생성하거나 재정렬하지 않습니다.
• onLineTap 이 있으면 행을 Clickable 로 감싸 탭 · Enter · Space에서 그 행을 전달하고, 없으면 표시 전용입니다. 선택·편집·비활성·복사 기능은 없습니다.

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

✅ Do#

CodeDiff(
  lines: [
    CoreCodeDiffLine(
      text: "  return Text('Hello');",
      type: CoreCodeDiffLineType.removed,
      lineNumber: 5,
    ),
    CoreCodeDiffLine(
      text: "  return Text('Hello').bodyMedium;",
      type: CoreCodeDiffLineType.added,
      lineNumber: 5,
    ),
  ],
)

❌ Don't#

// ❌ 변경 사항 없이 unchanged 라인만 나열
CodeDiff(
  lines: [
    CoreCodeDiffLine(
      text: 'final x = 1;',
      type: CoreCodeDiffLineType.unchanged,
      lineNumber: 1,
    ),
  ],
)

// ✅ 단일 코드 블록은 CodeSnippet
CodeSnippet(code: 'final x = 1;', mode: 'dart')

접근성 (Accessibility)#

CodeDiff 는 편집 없는 뷰어입니다. onLineTap 이 없으면 표시용이고, 제공하면 행별 Clickable 활성화·포커스 표면이 추가됩니다.

역할#

루트에 diff 전용 역할은 없습니다. 표시용 행은 일반 텍스트이며 onLineTap 행은 Flutter button 시맨틱 / Web role="button" 을 합성된 Clickable 에서 받습니다. <pre> · <code> · <table> · <ins> / <del> 의미는 자동으로 붙이지 않습니다.

즉 리더는 이 블록을 일반 텍스트 흐름으로 지나가며, diff 를 하나의 단위로 찾거나 건너뛸 수 없습니다.

키보드#

표시용 행에는 키 처리가 없습니다. onLineTap 을 제공한 행은 Tab으로 도달하고 Enter / Space로 해당 라인을 활성화합니다.

포커스 관리#

표시용 경로에는 포커스 가능한 요소가 없습니다. 활성 행은 Clickable의 포커스·링을 사용하며 루트에서 포커스를 가두거나 이동하지 않습니다. Web 루트는 overflow-hidden 이고 행이 줄바꿈되므로(whitespace-pre-wrap), 포커스 가능한 래퍼가 필요한 스크롤 컨테이너도 생기지 않습니다.

스크린 리더#

각 행은 순서대로 평평한 텍스트로 읽힙니다 — 라인 번호(showLineNumbers 가 켜져 있고 line.lineNumber 가 있을 때만), 그다음 '+ ' / '- ' / ' ' prefix, 그다음 라인 텍스트.

이 prefix 는 CSS 가 아니라 실제 텍스트 콘텐츠입니다(양 플랫폼 동일). 덕분에 추가/삭제 구분이 색상에만 실려 있지는 않습니다. 다만 그 이상은 없어서, 나머지는 구분되지 않는 산문처럼 읽힙니다.

알려진 제약#

• Web 에 코드 시맨틱이 없습니다 (<pre> / <code> 미사용). 리더가 코드 읽기 모드로 진입하지 않으므로 공백과 고정폭의 의미가 전달되지 않습니다.
• diff 전용 시맨틱이 없습니다 — <ins> / <del> 도, "추가된 줄" 같은 행 단위 aria-label 도 없습니다. 유일한 신호는 리터럴 + / - 문자이고, 이 문자를 읽어줄지는 리더와 상세도(verbosity) 설정에 따라 달라집니다. 변경 없는 행의 공백 두 칸 prefix 는 대개 통째로 무시됩니다.
• 라인 번호가 해당 라인과 연결되어 있지 않습니다 — 형제 텍스트 노드일 뿐이라 "5번째 줄의 내용" 이라는 관계가 전달되지 않습니다.
• diff 전체에 이름도 역할도 없습니다. 랜드마크나 영역으로 찾아갈 수 없으므로, 이름 붙은 영역이 필요하면 감싸는 쪽에서 직접 역할과 이름을 부여해야 합니다.

전역으로 적용되는 축(동작 줄이기·고대비·색 강제 모드·최소 터치 타겟)은 전역 접근성 축에 있습니다.

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

관련 컴포넌트 (Related Components)#

• CodeSnippet: 단일 코드 블록 표시
• Diff: 이미지/텍스트 split-view 비교