소스 뷰어 레이아웃 개발 가이드라인(리포지터리 blob 뷰어)
GitLab v19.6요약
app/assets/javascripts/blob/components/source_viewer/의 소스 뷰어는 CSS Grid를 사용하여 리포지터리 파일을 70줄 단위 청크로 렌더링하므로, JavaScript로 크기를 측정하지 않고도 블레임 거터, 줄 번호, 코드...
app/assets/javascripts/blob/components/source_viewer/의 소스 뷰어는
CSS Grid를 사용하여 리포지터리 파일을 70줄 단위 청크로 렌더링하므로, JavaScript로 크기를 측정하지 않고도
블레임 거터, 줄 번호, 코드의 정렬을 유지합니다. 청킹, 단계별 렌더링, 구문 강조는
구문 강조 개발 가이드라인을 참고합니다.
3열 그리드#
그리드는 이름이 비슷한 두 개의 중첩된 컨테이너 안에 있습니다. 템플릿에서 fileContent로
참조하는 바깥쪽 격리 래퍼는 z-index 스케일의 범위를 정하고 블레임 열 크기 조절 핸들을 고정합니다.
안쪽 .file-content 그리드는 3열 그리드를 선언하며 가로로 스크롤되는 요소입니다.
fileContent ref는 .file-content 요소를 가리키지 않습니다.
source_viewer.vue는 blameGridStyling 계산된 속성을 통해 .file-content 컨테이너에
최상위 그리드를 선언합니다.
grid-template-columns: <blameWidth> auto 1fr
세 개의 열은 다음과 같습니다.
| 열 | 트랙 크기 | 내용 |
|---|---|---|
| 1 | 고정 픽셀 값 | 블레임 거터 |
| 2 | auto |
줄 번호 |
| 3 | 1fr |
코드 |
**1열(블레임 거터)**은 사용자가 크기를 조절할 수 있는 고정 픽셀 트랙입니다. BlameColumnResizer는
스크롤되는 그리드가 아니라 격리 래퍼에 고정된 절대 위치 핸들이므로, 가로 스크롤 중에도
거터 가장자리에 정렬된 상태를 유지합니다. 핸들은 v-model을 통해 너비 값을 제어하고,
blameGridStyling은 이 값을 트랙 크기로 바꾸어 --blame-column-width 사용자 지정 속성으로 게시합니다.
블레임을 숨기면 너비가 '0'으로 설정되므로 이 열은 항상 그리드에 존재하지만 공간을 차지하지 않습니다.
너비가 바뀌면 source_viewer가 다시 렌더링되지만 청크 컴포넌트의 props는 바뀌지 않으므로,
청크는 다시 렌더링하지 않고 CSS만으로 위치를 조정합니다.
**2열(줄 번호)**은 콘텐츠에 맞게 트랙 크기를 정하는 auto를 사용합니다. 이 열은
가장 넓은 줄 번호가 필요로 하는 너비가 되며, highlight.scss에서 .line-numbers가 설정하는
6rem min-width 하한이 적용됩니다.
**3열(코드)**은 minmax(auto, 1fr)인 1fr을 사용합니다. auto 최솟값은
white-space: pre 텍스트의 min-content, 즉 파일에서 가장 넓은 줄로 결정됩니다. 모든 청크가
이 하나의 트랙을 공유하므로 어느 청크에 있든 가장 넓은 줄이 모든 청크의 너비를 정합니다. 따라서
선택한 줄은 어느 청크에 있든 전체 콘텐츠 너비에 걸칩니다.
서브그리드#
각 청크 루트는 세 열 모두에 걸쳐 있으며 부모의 열 트랙을 상속합니다.
<div class="gl-col-span-3 gl-grid gl-grid-cols-subgrid" :style="chunkGridStyling">
gl-grid-cols-subgrid는 grid-template-columns: subgrid를 적용합니다. 이 속성 덕분에
공유 측정 없이도 모든 청크 컴포넌트에 걸쳐 블레임 거터, 줄 번호, 코드가 정렬된 상태를 유지합니다.
명시적 행#
각 청크는 소스 줄마다 하나의 그리드 행을 선언합니다.
// chunk.vue: chunkGridStyling computed property
{ gridTemplateRows: `repeat(${this.totalLines}, var(--source-line-height))` }
행은 명시적이어야 합니다. 전체 높이 레이어는 grid-row: 1 / -1로 컴파일되는
gl-row-span-full을 사용합니다. -1 줄 인덱스는 명시적 그리드에 대해서만 해석됩니다.
암시적 행만 있으면 이 레이어는 한 줄 높이로 줄어듭니다.
chunk.vue는 app/assets/stylesheets/framework/highlight.scss의 .blob-viewer에 정의된 사용자 지정 속성
--source-line-height로 이 명시적 행을 만듭니다. chunkGridStyling
계산된 속성은 이 값을 gridTemplateRows로 반복하고, rawCodeStyling 계산된 속성은
같은 토큰에서 원시 코드 레이어의 min-height를 도출하므로, 행 높이를 변경할 때는
두 곳을 모두 고려해야 합니다.
데이터로서의 블레임 배치#
블레임 셀은 rowStart 및 rowSpan 값으로 그리드 위치를 설정합니다. 이 값은 source_viewer.vue가
한 번 만들고 normalizeBlameGroups에서 입력을 받는 블레임 슬라이스 빌더(utils.js의 createBlameSliceBuilder)가
청크별로 생성합니다. 셀은 이 값을 그대로 그리드 배치에 읽어 들입니다.
// chunk.vue: blameCellStyling method
{
gridRowStart: group.rowStart,
gridRowEnd: group.rowStart + group.rowSpan,
// ...
}
블레임 위치는 전적으로 이 데이터에서 도출되므로, 한 청크에 도착한 블레임 데이터가
다른 청크의 레이아웃에 영향을 줄 수 없습니다. createBlameSliceBuilder는 각 청크의 이전 슬라이스도 캐시하고,
새 슬라이스가 동등하면 새로 계산한 배열 대신 같은 배열 참조를 반환합니다.
이 참조 안정성 덕분에 블레임이 바뀌지 않은 청크의 blameGroups prop 식별자가 그대로 유지되며,
블레임이 실제로 바뀐 청크만 다시 렌더링됩니다.
전체 높이 레이어#
다음 항목은 각각 gl-row-span-full로 청크 전체 높이에 걸칩니다. 각 항목은 줄마다 하나의 요소가 아니라
하나의 그리드 항목입니다.
| 레이어 | 열 | 용도 |
|---|---|---|
| 거터 배경 패널 | 1 | 블레임 셀의 배경이 되고, 블레임이 아직 로드되지 않은 줄을 덮으며, 아래에서 스크롤되는 코드를 가립니다 |
| 블레임 스켈레톤 로더 | 1 | 청크의 블레임 요청이 진행 중이고 아직 그룹이 도착하지 않은 동안 표시됩니다 |
| 줄 번호 플레이스홀더 | 2 | 청크가 강조되기 전에 줄 번호 열을 열어 둡니다 |
코드 영역(GlIntersectionObserver + <pre>) |
3 | 청크 전체의 코드를 하나의 항목으로 렌더링합니다 |
쌓임 레이어#
여러 그리드 항목이 같은 셀을 차지하며 z-index로 쌓입니다. 격리 래퍼는
gl-isolate(isolation: isolate)를 설정하여 이 z-index 스케일의 범위를 정하므로, 스티키 파일 헤더 같은
페이지 크롬과 동률이 되지 않습니다.
| z-index | 레이어 |
|---|---|
gl-z-1 |
원시 코드 레이어(<pre> 안의 원시 <code> 요소) |
gl-z-2 |
블레임 거터: 배경 패널, 스켈레톤 로더, 블레임 셀 |
gl-z-3 |
줄 번호, 블레임 열 크기 조절 핸들 |
gl-z-4 |
블레임 그룹 구분 테두리 |
gl-z-1 계층은 <pre> 안의 2층 코드 스택 중 절반입니다. 원시 <code> 요소는
gl-text-transparent로 일반 텍스트를 렌더링하며, 절대 위치이고 inert인 강조된 <code>
오버레이 위에 놓입니다. 원시 레이어가 텍스트 선택과 포인터 이벤트를 담당하고,
같은 좌표에 있는 강조된 span으로 마우스 이벤트를 전달하므로
코드 탐색처럼 호버로 동작하는 기능이 계속 작동합니다. 원시 텍스트를 DOM에 유지하면
청크가 강조되기 전에도 브라우저 기본 찾기가 동작합니다.
같은 z-index 계층 안에서는 DOM 순서가 페인트 순서를 결정합니다. 서로 다른 z-index 값은 DOM 순서만으로는 필요한 쌓임을 표현할 수 없는, 컴포넌트 트리의 서로 다른 부분에 있는 항목을 위해 예약되어 있습니다.
가로 스크롤#
블레임 거터 레이어(배경 패널, 스켈레톤, 블레임 셀)는 left: 0에서 position: sticky입니다.
줄 번호는 left: var(--blame-column-width)에서 스티키입니다. 3열의 코드는
두 열 아래에서 스크롤됩니다. 불투명한 거터 배경이 스티키 열 아래에서 스크롤되는 코드를 가립니다.
스티키 위치 지정은 그리드 배치와 함께 작동합니다. 그리드는 항목이 트랙 레이아웃에서 어디에 있을지 결정하고, 스티키는 스크롤 중 항목의 동작을 제어합니다.
그룹 구분선#
경계는 블레임 그룹에 hasSeparator가 설정된 경우에만 구분선을 렌더링합니다. hasSeparator는
이전 청크에서 이어지는 그룹과 1번 줄에서 시작하는 그룹에는 false입니다
(utils.js의 blameGroupsForChunk를 참고하며, chunk.vue의 blameSeparatorRows가 이 플래그를 읽습니다).
블레임 그룹 사이의 각 경계는 하나가 아니라 두 개의 요소로 렌더링됩니다. 거터 절반은
1열을 덮고 기본 테두리 토큰(gl-border-t)을 사용하며, 코드 절반은 2열과 3열을 덮고
gl-border-t-gray-500을 사용합니다. 거터는 페이지 UI 테마를 따르고 코드 영역은 사용자의 구문 강조 테마를 따르므로
이렇게 나누어야 하며, 하나의 테두리 색으로는 두 영역에서 모두 제대로 보이지 않습니다.
두 절반 모두 gl-z-4에 있으므로 맞닿은 블레임 셀과 코드 위에 그려집니다. 코드 절반은
스티키가 아니므로 가로 스크롤 중에 거터 열 아래로 밀려 들어가며, 이때 두 절반은 겹칩니다.
템플릿은 코드 절반을 먼저, 스티키 거터 절반을 나중에 렌더링하므로
두 절반이 만나는 곳에서는 거터 절반이 코드 절반을 덮습니다.
주의 사항#
청크 목록을 중간 요소로 감싸지 않기#
grid-template-columns: subgrid는 직접적인 그리드 부모에서만 트랙을 상속합니다. .file-content와
<chunk> 컴포넌트 사이에 래퍼가 하나라도 있으면 정렬이 조용히 깨집니다. 서브그리드가
none으로 대체되어 모든 청크가 독립적인 열 트랙을 따로 만듭니다.
청크 행을 명시적으로 유지하기#
grid-row: 1 / -1은 -1을 명시적 그리드에 대해서만 해석합니다. chunkGridStyling의
grid-template-rows를 제거하거나 바꾸면 모든 전체 높이 레이어(gl-row-span-full)가 한 행으로 줄어들며,
새 전체 높이 레이어가 제대로 동작하려면 청크에 명시적 행이 필요합니다.
z-index 계층 안에서 DOM 순서 유지하기#
두 계층은 각 계층의 요소가 같은 z-index를 공유하므로 올바른 페인트 순서를 위해 DOM 순서에만 의존합니다.
gl-z-2 거터 계층에서는 거터 배경 패널이 블레임 셀보다 앞에 있어야 합니다.
gl-z-4 구분선 계층에서는 그룹 구분선의 코드 절반이 거터 절반보다 앞에 있어야 합니다
(그룹 구분선 참고). 어느 쪽이든 순서를 바꾸면 z-index 값을 바꾸지 않아도 해당 레이어가 깨집니다.
캐시된 블레임 슬라이스를 불변으로 취급하기#
블레임 그룹이나 슬라이스 빌더가 반환하는 배열을 변경하지 않습니다. Vue는 이 객체를 추적하지 않으므로 변경해도 셀이 다시 렌더링되지 않습니다. 다음 재빌드는 비교하는 필드가 일치하면 캐시된 슬라이스를 유지하므로, 다른 필드를 변경하면 그 변경이 무기한 남을 수 있습니다.
동등성 검사 자체인 isSameBlameSlice는 rowStart, rowSpan,
hasSeparator, commit?.sha만 비교합니다. 고정된 rowStart가 아니라 그룹의 원래 lineno에서 도출한 값처럼
블레임 셀의 렌더링 방식을 바꾸는 필드를 추가한다면 이 비교도 확장해야 합니다. 그렇지 않으면
기반 데이터가 바뀐 후에도 셀이 오래된 렌더링을 유지합니다.