@t3q-ui/design-system 0.0.0-stage → 1.56.0

package/skills/tds/examples/list-page.tsx

@@ -0,0 +1,275 @@
+/**
+ * TDS 목록 화면 예제 — "검색·필터 → 표 → 행 클릭으로 오른쪽 상세 패널 → 삭제 확인" 흐름.
+ * 이 파일은 TDS 저장소의 타입 검사(`pnpm typecheck`)와 렌더 테스트를 통과한 코드다. 새 목록 화면은 이 구조에서 시작한다.
+ *
+ * 이 예제가 보여 주는 것 (자주 틀리는 곳):
+ * - ListPage 가 헤더·필터 줄·표·페이지네이션·빈 결과·로딩·오류를 그린다. 표·헤더를 직접 만들지 않는다
+ * - 주요 행동 버튼은 `actions` → 제목 오른쪽에 놓인다
+ * - 상태처럼 선택지가 3~6개인 다중 선택 필터는 `quickFilter` → 표 왼쪽 위에 세그먼트로 항상 보이고, 항목마다 건수가 붙는다
+ *   (드롭다운에 숨기지 않는다). 선택지가 많거나 검색이 필요한 축만 `TableFilterMultiSelect title='…'` 로 `filters` 에 둔다
+ * - `onResetFilters` 는 **항상** 넘기고 `filtersActive` 로 비활성을 표현한다 → 빈 결과 가운데에 "필터 초기화" 가 나온다
+ * - 행 클릭 → `detail` 슬롯이 목록 **오른쪽에 나란히** 상세 패널을 그린다(표가 좁아지고 목록은 계속 보인다, 닫기 버튼·Esc).
+ *   `activeRowId` 로 열린 행을 표시하고, 상세 필드는 `MetaList` + `MetaRow` 로 세로로 쌓는다
+ *   (`Stack` 은 기본 방향이 가로라 MetaRow 를 감싸면 옆으로 늘어서 잘린다). 표를 좁히면 안 될 때만 `<Drawer modal={false}>`
+ * - 빈 결과는 `emptyState={{ title, description }}` 만 넘긴다 → 패턴이 아이콘·제목·설명·초기화 버튼 상자로 그린다
+ * - 비활성 버튼(실행 중이 아닐 때의 '중지')에는 왜 못 하는지를 `detail.note` 로 버튼 줄에 한 줄 적는다 — 비활성 버튼에는 tooltip 이 뜨지 않는다
+ * - 삭제는 `AlertDialog`(variant danger)로 확인받는다
+ * - 정렬할 수 있는 열은 `sortable: true` 를 명시한다 → 정렬 전에도 아이콘이 보이고 누르면 방향이 바뀐다
+ * - 상태는 `Badge` 에 아이콘 + 글자(`<Badge variant='primary'><LucideIcon iconComponentName='play' />실행 중</Badge>` — 아이콘은 자식으로 바로, 크기는 기본). 별도 상태 컴포넌트를 만들지 않는다.
+ *   실행 중·활성처럼 건강하게 돌아가는 상태는 `primary`(▶), 학습 중·배포 중처럼 끝이 있는 진행은 `info` + `loader-circle`, 완료·준비됨만 `success`(✓) — 실행 중에 ✓ 를 붙이면 끝난 것으로 읽힌다(2026-10-20 17차)
+ * - 숫자 열(개수·크기·비율)은 `type: 'number'` → 셀·제목이 오른쪽 정렬된다
+ * - 상세 패널의 필드는 `MetaRow align='start'` → 값이 라벨 옆에 붙는다(넓은 패널에서 라벨과 값 사이가 비지 않는다)
+ * - 열 폭: 이름 열 `flex: 2, minWidth: 200, maxWidth: 480`, 글자가 들어가는 열은 **모두** `flex: 1, minWidth: 120`(여기서는 소유자 하나지만 팀·프레임워크·설명이 있으면 전부) — 남는 폭이 여러 열로 흩어져야 이름 열만 넓어지지 않는다(2026-10-20 17차·18차). 글자 열이 하나도 없으면 maxWidth 를 뺀다(표 오른쪽이 빈다). 숫자·날짜·상태·진행률 열은 `width`(제목이 들어가는 최소 폭은 표가 보정하고 넘치는 글자는 말줄임표).
+ *   보조 정보(이미지·id·경로)는 열을 늘리지 않고 `secondaryField` 로 이름 아래 줄에 — 열이 6~7개를 넘으면 잘린다
+ * - 빠른 필터의 건수 뱃지는 표의 상태 뱃지와 같은 색(`countVariant: STATUS[s].tone`)
+ * - 목 데이터는 소비 앱(App.tsx)이 `fetchEnvs` 로 넘긴다 — **20행 이상**(페이지 크기 20 이면 두 페이지). 10행이면 표 아래가 비어 보인다
+ */
+import { type ReactNode, useEffect, useMemo, useState } from 'react'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  Button,
+  LucideIcon,
+  MetaList,
+  MetaRow,
+  Progress,
+  Badge,
+  type BadgeProps,
+  TextField,
+} from '@t3q-ui/design-system'
+import { ListPage } from '@t3q-ui/design-system/patterns'
+import type { ColDef, ICellRendererParams } from 'ag-grid-community'
+
+type Status = 'RUNNING' | 'STOPPED' | 'ERROR'
+type Env = {
+  id: string
+  name: string
+  image: string
+  status: Status
+  gpu: number
+  /** GPU 사용률 0~100 — 표의 진행률 열 예시 */
+  gpuUsage: number
+  owner: string
+  updatedAt: string
+}
+
+// 상태값 → 글자·variant·아이콘 매핑은 한 곳에(Badge 에 아이콘 + 글자).
+// 실행환경의 '실행 중' 은 컨테이너가 돌아가는 프로세스라 primary(▶). '사용 중·활성' 같은 켜진 상태라면 primary + circle-dot(파란 ●), 준비됨·완료는 success(✓) — 한 화면에 같은 tone 의 상태 둘 금지(19차: 둘 다 초록이라 "two different states look the same"). ▶ 는 상태에 붙이면 재생 버튼처럼, success 의 ✓ 는 끝난 상태로 읽힌다(17·18차)
+const STATUS: Record<
+  Status,
+  { label: string; variant: NonNullable<BadgeProps['variant']>; icon: ReactNode }
+> = {
+  RUNNING: { label: '실행 중', variant: 'primary', icon: <LucideIcon iconComponentName='play' /> },
+  STOPPED: {
+    label: '중지',
+    variant: 'secondary',
+    icon: <LucideIcon iconComponentName='circle-pause' />,
+  },
+  ERROR: { label: '오류', variant: 'danger', icon: <LucideIcon iconComponentName='circle-x' /> },
+}
+const STATUS_OPTIONS = (Object.keys(STATUS) as Status[]).map((s) => ({
+  value: s,
+  label: STATUS[s].label,
+}))
+const PAGE_SIZE = 20
+
+// 남는 폭은 이름 열(flex 2, 상한 480)과 글자 열 전부(flex 1)가 나눈다 — 글자 열이 하나뿐이면 2:1 로 나눠도 이름 열이 500px 라 비어 보인다(2026-10-20 17차·18차).
+// maxWidth 를 주면 넓은 화면에서 표 오른쪽이 빈다. 이미지는 열이 아니라 이름 아래 보조 줄(ListPage secondaryField='image')
+const COLUMNS: ColDef<Env>[] = [
+  { field: 'name', headerName: '이름', flex: 2, minWidth: 200, maxWidth: 480, sortable: true },
+  {
+    field: 'status',
+    headerName: '상태',
+    width: 120,
+    cellRenderer: (p: ICellRendererParams<Env>) =>
+      p.data ? (
+        <Badge variant={STATUS[p.data.status].variant}>
+          {STATUS[p.data.status].icon}
+          {STATUS[p.data.status].label}
+        </Badge>
+      ) : null,
+  },
+  // 숫자 열은 type: 'number' — 셀·제목 오른쪽 정렬, 숫자 폭 고정. width 는 제목 글자가 들어갈 만큼(모자라면 표가 올려 준다)
+  { field: 'gpu', headerName: 'GPU', width: 90, type: 'number', sortable: true },
+  // 표의 진행률 열: 고정 폭 막대(120px) + 오른쪽 % 글자 한 줄. 글자 아래 막대를 쌓거나 w-full 로 두면 행마다 막대 폭이 달라진다(2026-10-20 16차).
+  // 막대 이름은 aria-label 로 행마다 '무엇 몇 %' — 이름 없는 progressbar 는 행마다 axe serious(2026-10-20 17차)
+  {
+    field: 'gpuUsage',
+    headerName: 'GPU 사용률',
+    width: 190,
+    sortable: true,
+    cellRenderer: (p: ICellRendererParams<Env>) =>
+      p.data ? (
+        <div className='flex items-center gap-[8px]'>
+          <Progress
+            value={p.data.gpuUsage}
+            className='w-[120px]'
+            aria-label={`GPU 사용률 ${p.data.gpuUsage}%`}
+          />
+          <span className='text-small-regular tabular-nums text-sys-text-main'>
+            {p.data.gpuUsage}%
+          </span>
+        </div>
+      ) : null,
+  },
+  { field: 'owner', headerName: '소유자', flex: 1, minWidth: 120 },
+  { field: 'updatedAt', headerName: '수정일', width: 170, sortable: true },
+]
+
+export function ExecutionEnvironmentListPage({ fetchEnvs }: { fetchEnvs: () => Promise<Env[]> }) {
+  const [all, setAll] = useState<Env[] | undefined>()
+  const [error, setError] = useState<string | null>(null)
+  const [search, setSearch] = useState('')
+  const [statuses, setStatuses] = useState<string[]>([])
+  const [page, setPage] = useState(1)
+  const [selected, setSelected] = useState<Env | null>(null)
+  const [confirmDelete, setConfirmDelete] = useState(false)
+
+  useEffect(() => {
+    fetchEnvs().then(setAll, () => setError('실행환경 목록을 불러오지 못했습니다.'))
+  }, [fetchEnvs])
+
+  const filtered = useMemo(
+    () =>
+      (all ?? []).filter(
+        (e) => e.name.includes(search) && (statuses.length === 0 || statuses.includes(e.status)),
+      ),
+    [all, search, statuses],
+  )
+  // 빠른 필터의 건수: 검색은 적용하고 상태 필터는 적용하지 않은 목록 기준 — 선택지마다 "몇 건이 있나"
+  const statusCounts = useMemo(() => {
+    const out: Partial<Record<Status, number>> = {}
+    for (const e of all ?? []) if (e.name.includes(search)) out[e.status] = (out[e.status] ?? 0) + 1
+    return out
+  }, [all, search])
+  const filtersActive = search !== '' || statuses.length > 0
+  const resetFilters = () => {
+    setSearch('')
+    setStatuses([])
+    setPage(1)
+  }
+
+  return (
+    <>
+      <ListPage<Env>
+        title='실행환경'
+        description='모델 학습·추론에 쓰는 컨테이너 실행환경을 관리합니다.'
+        actions={<Button variant='primaryBold'>실행환경 생성</Button>}
+        filters={
+          <TextField
+            aria-label='이름으로 검색'
+            placeholder='이름으로 검색'
+            value={search}
+            onChange={(e) => {
+              setSearch(e.target.value)
+              setPage(1)
+            }}
+          />
+        }
+        onResetFilters={resetFilters}
+        filtersActive={filtersActive}
+        quickFilter={{
+          label: '상태',
+          // 건수 뱃지 색은 표의 상태 뱃지와 같은 variant — 칩과 표가 같은 색 언어
+          options: STATUS_OPTIONS.map((o) => ({
+            ...o,
+            count: statusCounts[o.value] ?? 0,
+            countVariant: STATUS[o.value].variant,
+          })),
+          value: statuses,
+          onChange: (v) => {
+            setStatuses(v)
+            setPage(1)
+          },
+        }}
+        columns={COLUMNS}
+        // 이름 아래 보조 줄(이미지) — 열을 하나 줄이고 행은 56 으로 그려진다
+        secondaryField='image'
+        rows={filtered.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE)}
+        loading={all === undefined && !error}
+        error={error}
+        emptyState={
+          filtersActive
+            ? {
+                title: '검색 조건에 맞는 실행환경이 없습니다',
+                description: '검색어나 상태 필터를 바꾸거나, 아래 버튼으로 필터를 초기화해 보세요.',
+              }
+            : {
+                title: '등록된 실행환경이 없습니다',
+                description: '오른쪽 위 "실행환경 생성" 버튼으로 첫 실행환경을 만드세요.',
+              }
+        }
+        pagination={{ total: filtered.length, page, pageSize: PAGE_SIZE, onChange: setPage }}
+        onRowClick={setSelected}
+        activeRowId={selected?.id ?? null}
+        // 상세는 목록 오른쪽에 나란한 패널: 표가 좁아지고 목록은 계속 보인다. 닫기 버튼·Esc 로 닫는다
+        detail={
+          selected
+            ? {
+                title: selected.name,
+                description: selected.id,
+                onClose: () => setSelected(null),
+                children: (
+                  <MetaList>
+                    <MetaRow align='start' label='이미지' value={selected.image} />
+                    <MetaRow
+                      align='start'
+                      label='상태'
+                      value={
+                        <Badge variant={STATUS[selected.status].variant}>
+                          {STATUS[selected.status].icon}
+                          {STATUS[selected.status].label}
+                        </Badge>
+                      }
+                    />
+                    <MetaRow align='start' label='GPU' value={`${selected.gpu}개`} />
+                    <MetaRow align='start' label='소유자' value={selected.owner} />
+                    <MetaRow align='start' label='수정일' value={selected.updatedAt} />
+                  </MetaList>
+                ),
+                // 비활성 버튼에는 tooltip 이 뜨지 않으므로 이유를 note 로 적는다
+                note:
+                  selected.status !== 'RUNNING' ? '실행 중인 환경만 중지할 수 있습니다' : undefined,
+                footer: (
+                  <>
+                    <Button variant='dangerOutline' onClick={() => setConfirmDelete(true)}>
+                      삭제
+                    </Button>
+                    <Button variant='primaryBold' disabled={selected.status !== 'RUNNING'}>
+                      중지
+                    </Button>
+                  </>
+                ),
+              }
+            : undefined
+        }
+      />
+
+      <AlertDialog open={confirmDelete} onOpenChange={setConfirmDelete}>
+        <AlertDialogContent variant='danger'>
+          <AlertDialogHeader>
+            <AlertDialogTitle>{selected?.name} 을(를) 삭제할까요?</AlertDialogTitle>
+            <AlertDialogDescription>삭제하면 되돌릴 수 없습니다.</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>취소</AlertDialogCancel>
+            <AlertDialogAction
+              onClick={() => {
+                setAll((prev) => prev?.filter((e) => e.id !== selected?.id))
+                setSelected(null)
+              }}
+            >
+              삭제
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  )
+}