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

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

@@ -0,0 +1,460 @@
+/**
+ * TDS 생성 폼 예제 — "PageHeader → 섹션 4개(구분선) → 누르면 검증 → 취소 확인 → 성공 toast" 흐름.
+ * 이 파일은 TDS 저장소의 타입 검사(`pnpm typecheck`)와 렌더 테스트를 통과한 코드다. 전용 URL 을 가진 생성·수정 화면은 이 구조에서 시작한다.
+ *
+ * 이 예제가 보여 주는 것 (자주 틀리는 곳):
+ * - FormPage 가 머리(PageHeader)·푸터 버튼·전체 오류를 그린다. 제목·버튼 줄을 직접 만들지 않는다
+ * - 저장(생성) 버튼은 기본(`submitMode='always'`)으로 **항상 눌리고**, 누르면 react-hook-form 이 검증해 틀린 항목마다 `FormMessage` 를 보인다.
+ *   `useForm({ mode: 'onSubmit', reValidateMode: 'onChange' })` + 필드 `rules` 로 충분하다 — 유효해질 때까지 잠그고 싶을 때만 `submitMode='whenValid'`
+ * - 필수 항목은 `FormLabel required` + `requiredLegend` 안내 한 줄
+ * - 숫자 입력의 단위는 `TextField elemAfterInput='개'` → 입력 칸 오른쪽에 한 줄로 붙는다. 라벨에 "(GB)" 를 넣지 않는다
+ * - 선택지 목록(실행환경)을 못 불러왔으면 **폼을 지우지 말고** 그 섹션 안에 `Alert variant='danger'` 한 줄(제목 + 설명 + `AlertActions` 의 다시 시도 링크)을 둔다. 화면 전체 실패가 아니라 `ErrorState` 상자는 쓰지 않는다. 불러오는 동안은 `Skeleton`
+ * - 조건부 필드(주기 → cron, 알림 켬 → 이메일)는 `form.watch` 로 보이고, 숨길 때 값·오류를 지운다
+ * - 입력한 내용이 있을 때(`formState.isDirty`) 취소는 `AlertDialog`(variant warning)로 확인받는다.
+ *   `isDirty` 는 **렌더 중에 읽어 둔다**(`const { isDirty } = form.formState`) — react-hook-form 은 렌더에서 읽은 값만 구독해 갱신하므로,
+ *   콜백 안에서만 `form.formState.isDirty` 를 읽으면 입력해도 false 그대로라 확인창이 뜨지 않는다
+ * - 제출 중 상태는 앱이 `submitting` 으로 갖고 `FormPage submitting` 에 넘긴다(try/finally) → 저장·취소가 잠기고 스피너가 보여 중복 제출을 막는다
+ * - 서버 오류는 FormPage `error` (푸터 위 Alert), 성공은 `toast`
+ * - 검토·요약 패널은 `FormPage aside` 로 폼 옆에 둔다(패턴이 세로선·sticky 로 그린다). FormPage 를 flex 로 감싸 옆에 `<aside>` 를 두면
+ *   헤더가 화면 폭을 다 못 써 구분선이 끊긴다
+ * - 도움말(`FormDescription`)은 **규칙·전제·추천값**을 적는다 — placeholder 와 같은 말("1~32")을 되풀이하지 않는다. placeholder 는 "예: 4" 같은 보기.
+ *   검토 패널의 빈 값은 "—" 하나(단위는 값이 있을 때만 — "—코어" 금지), 항목은 한 행에 하나(여러 값을 "·" 로 이어 붙이지 않는다)
+ * - 검토 패널(`aside`)이 있으면 취소·제출 버튼은 FormPage 가 **패널 바닥**에 그린다 — 폼 끝에 버튼을 따로 두지 않는다(2026-10-20 16차 D1: 긴 폼 옆 패널 아래 빈 공간·먼 제출 버튼 감점)
+ */
+import { useCallback, useEffect, useState } from 'react'
+import { useForm } from 'react-hook-form'
+import {
+  Alert,
+  AlertActions,
+  AlertDescription,
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertTitle,
+  Button,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+  FormSection,
+  LucideIcon,
+  MetaList,
+  MetaRow,
+  RadioSection,
+  RadioSectionGroup,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Skeleton,
+  SwitchSection,
+  Textarea,
+  TextField,
+  toast,
+} from '@t3q-ui/design-system'
+import { FormPage } from '@t3q-ui/design-system/patterns'
+
+export type Runtime = { id: string; name: string; description?: string }
+type Values = {
+  name: string
+  description: string
+  runtimeId: string
+  schedule: 'manual' | 'cron'
+  cron: string
+  cpu: string
+  memoryGb: string
+  gpu: string
+  notifyOnFailure: boolean
+  email: string
+}
+const DEFAULTS: Values = {
+  name: '',
+  description: '',
+  runtimeId: '',
+  schedule: 'manual',
+  cron: '',
+  cpu: '',
+  memoryGb: '',
+  gpu: '0',
+  notifyOnFailure: false,
+  email: '',
+}
+const intInRange = (min: number, max: number, label: string) => (v: string) =>
+  /^\d+$/.test(v) && Number(v) >= min && Number(v) <= max
+    ? true
+    : `${label}은(는) ${min}~${max} 사이 정수여야 합니다.`
+
+type RuntimeState =
+  | { status: 'loading' }
+  | { status: 'error' }
+  | { status: 'ready'; runtimes: Runtime[] }
+
+export function PipelineCreatePage({
+  fetchRuntimes,
+  createPipeline,
+  onLeave,
+}: {
+  fetchRuntimes: () => Promise<Runtime[]>
+  createPipeline: (values: Values) => Promise<void>
+  onLeave: () => void
+}) {
+  const form = useForm<Values>({
+    defaultValues: DEFAULTS,
+    mode: 'onSubmit',
+    reValidateMode: 'onChange',
+  })
+  const schedule = form.watch('schedule')
+  const notifyOnFailure = form.watch('notifyOnFailure')
+  // 검토 패널에 보일 입력값 — watch() 는 렌더마다 최신 값을 준다
+  const values = form.watch()
+  const [runtimes, setRuntimes] = useState<RuntimeState>({ status: 'loading' })
+  const [serverError, setServerError] = useState<string | null>(null)
+  const [confirmCancel, setConfirmCancel] = useState(false)
+  // 제출 중 상태를 앱 상태로 드러낸다 — FormPage 가 이 동안 저장·취소 버튼을 잠그고 스피너를 보인다(중복 제출 방지)
+  const [submitting, setSubmitting] = useState(false)
+  const { isDirty } = form.formState // 렌더에서 읽어야 RHF 가 구독해 갱신한다
+
+  const loadRuntimes = useCallback(() => {
+    setRuntimes({ status: 'loading' })
+    fetchRuntimes().then(
+      (list) => setRuntimes({ status: 'ready', runtimes: list }),
+      () => setRuntimes({ status: 'error' }),
+    )
+  }, [fetchRuntimes])
+  useEffect(loadRuntimes, [loadRuntimes])
+
+  const handleSubmit = async (values: Values) => {
+    setServerError(null)
+    setSubmitting(true)
+    try {
+      await createPipeline(values)
+      toast({
+        title: '파이프라인을 생성했습니다',
+        description: `${values.name} 을(를) 만들었습니다.`,
+        variant: 'success',
+      })
+      onLeave()
+    } catch {
+      setServerError('파이프라인을 생성하지 못했습니다. 잠시 후 다시 시도해 주세요.')
+    } finally {
+      setSubmitting(false)
+    }
+  }
+
+  return (
+    <>
+      <FormPage
+        title='파이프라인 생성'
+        description='실행환경과 리소스, 스케줄을 정해 새 파이프라인을 만듭니다.'
+        form={form}
+        onSubmit={handleSubmit}
+        onCancel={() => (isDirty ? setConfirmCancel(true) : onLeave())}
+        submitLabel='생성'
+        submitting={submitting}
+        error={serverError}
+        requiredLegend
+        asideTitle='검토'
+        aside={
+          <MetaList>
+            <MetaRow align='start' label='이름' value={values.name || '—'} />
+            <MetaRow
+              align='start'
+              label='실행환경'
+              value={
+                (runtimes.status === 'ready' &&
+                  runtimes.runtimes.find((r) => r.id === values.runtimeId)?.name) ||
+                '—'
+              }
+            />
+            <MetaRow
+              align='start'
+              label='스케줄'
+              value={values.schedule === 'cron' ? values.cron || '—' : '수동 실행'}
+            />
+            {/* 빈 값은 "—" 하나 — 단위는 값이 있을 때만 붙인다("—코어" 는 어색하다). 값마다 한 행 */}
+            <MetaRow align='start' label='CPU' value={values.cpu ? `${values.cpu} 코어` : '—'} />
+            <MetaRow
+              align='start'
+              label='메모리'
+              value={values.memoryGb ? `${values.memoryGb} GB` : '—'}
+            />
+            <MetaRow align='start' label='GPU' value={values.gpu ? `${values.gpu}개` : '—'} />
+            <MetaRow
+              align='start'
+              label='실패 알림'
+              value={values.notifyOnFailure ? values.email || '—' : '끔'}
+            />
+          </MetaList>
+        }
+      >
+        <FormSection title='기본 정보'>
+          <FormField
+            control={form.control}
+            name='name'
+            rules={{
+              required: '이름을 입력하세요.',
+              pattern: {
+                value: /^[a-z0-9-]{3,40}$/,
+                message: '영문 소문자·숫자·하이픈으로 3~40자여야 합니다.',
+              },
+            }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel required>이름</FormLabel>
+                <FormControl>
+                  <TextField {...field} placeholder='예: daily-sales-etl' />
+                </FormControl>
+                {/* 도움말은 규칙 + 전제(왜 바꿀 수 없는지) — placeholder 를 되풀이하지 않는다 */}
+                <FormDescription>
+                  실행 경로에 쓰여 만든 뒤에는 바꿀 수 없습니다. 영문 소문자·숫자·하이픈 3~40자
+                </FormDescription>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name='description'
+            rules={{ maxLength: { value: 200, message: '200자 이하로 적어 주세요.' } }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>설명</FormLabel>
+                <FormControl>
+                  <Textarea
+                    {...field}
+                    placeholder='파이프라인이 하는 일을 적어 주세요.'
+                    minRows={3}
+                  />
+                </FormControl>
+                <FormDescription>{field.value.length} / 200자</FormDescription>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        </FormSection>
+
+        <FormSection title='실행 설정'>
+          <FormField
+            control={form.control}
+            name='runtimeId'
+            rules={{ required: '실행환경을 선택하세요.' }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel required>실행환경</FormLabel>
+                {runtimes.status === 'loading' ? <Skeleton className='h-[36px] w-full' /> : null}
+                {/* 선택지를 못 불러와도 폼은 그대로 두고 이 섹션 안에만 Alert(danger) 한 줄 + 다시 시도 링크. 화면 전체 실패가 아니라서 ErrorState 상자는 쓰지 않는다 */}
+                {runtimes.status === 'error' ? (
+                  <Alert variant='danger'>
+                    <LucideIcon iconComponentName='CircleAlert' size={20} />
+                    <AlertTitle>실행환경 목록을 불러오지 못했습니다</AlertTitle>
+                    <AlertDescription>
+                      네트워크 상태를 확인한 뒤 다시 시도해 주세요.
+                    </AlertDescription>
+                    <AlertActions>
+                      <Button type='button' variant='secondaryLink' onClick={loadRuntimes}>
+                        다시 시도
+                      </Button>
+                    </AlertActions>
+                  </Alert>
+                ) : null}
+                {runtimes.status === 'ready' ? (
+                  <FormControl>
+                    <Select value={field.value} onValueChange={field.onChange}>
+                      <SelectTrigger>
+                        <SelectValue placeholder='실행환경 선택' />
+                      </SelectTrigger>
+                      <SelectContent>
+                        {runtimes.runtimes.map((rt) => (
+                          <SelectItem key={rt.id} value={rt.id} description={rt.description}>
+                            {rt.name}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                  </FormControl>
+                ) : null}
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name='schedule'
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel id='schedule-label'>스케줄</FormLabel>
+                {/* 유형·방식 선택은 카드형 RadioSectionGroup — 선택지마다 제목·설명 (dl-ui-v3 관례). 설명 없는 짧은 선택만 RadioGroup */}
+                <FormControl>
+                  <RadioSectionGroup
+                    aria-labelledby='schedule-label'
+                    value={field.value}
+                    onValueChange={(v) => {
+                      field.onChange(v)
+                      if (v === 'manual') {
+                        form.setValue('cron', '')
+                        form.clearErrors('cron')
+                      }
+                    }}
+                  >
+                    <RadioSection
+                      value='manual'
+                      title='수동'
+                      description='필요할 때 직접 실행합니다'
+                    />
+                    <RadioSection
+                      value='cron'
+                      title='주기'
+                      description='cron 식에 따라 반복 실행합니다'
+                    />
+                  </RadioSectionGroup>
+                </FormControl>
+              </FormItem>
+            )}
+          />
+          {schedule === 'cron' ? (
+            <FormField
+              control={form.control}
+              name='cron'
+              rules={{ required: 'cron 식을 입력하세요.' }}
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel required>cron 식</FormLabel>
+                  <FormControl>
+                    <TextField {...field} placeholder='예: 0 3 * * *' />
+                  </FormControl>
+                  <FormDescription>
+                    분 시 일 월 요일 순서. 예: 매일 03:00 은 0 3 * * *
+                  </FormDescription>
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+          ) : null}
+        </FormSection>
+
+        <FormSection title='리소스'>
+          <FormField
+            control={form.control}
+            name='cpu'
+            rules={{
+              required: 'CPU 코어 수를 입력하세요.',
+              validate: intInRange(1, 32, 'CPU 코어'),
+            }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel required>CPU</FormLabel>
+                <FormControl>
+                  <TextField {...field} inputMode='numeric' placeholder='예: 4' elemAfterInput='코어' />
+                </FormControl>
+                {/* 범위 + 추천값. placeholder 는 보기 하나 */}
+                <FormDescription>1~32 코어. 전처리는 2~4, 모델 학습은 8 이상을 권합니다</FormDescription>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name='memoryGb'
+            rules={{ required: '메모리를 입력하세요.', validate: intInRange(1, 256, '메모리') }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel required>메모리</FormLabel>
+                <FormControl>
+                  <TextField {...field} inputMode='numeric' placeholder='예: 16' elemAfterInput='GB' />
+                </FormControl>
+                <FormDescription>1~256 GB. 입력 데이터 크기의 2배 이상을 권합니다</FormDescription>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name='gpu'
+            rules={{ validate: intInRange(0, 8, 'GPU 수') }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>GPU</FormLabel>
+                <FormControl>
+                  <TextField {...field} inputMode='numeric' placeholder='예: 1' elemAfterInput='개' />
+                </FormControl>
+                <FormDescription>0~8개. GPU 가 필요 없으면 0 — 학습 작업은 1개 이상</FormDescription>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        </FormSection>
+
+        <FormSection title='알림'>
+          <FormField
+            control={form.control}
+            name='notifyOnFailure'
+            render={({ field }) => (
+              <FormItem>
+                {/* 켜기/끄기 하나의 설정은 SwitchSection(박스 + 제목·설명 + Switch) — dl-ui-v3 ToggleField 관례. 폼 제출값이어도 Checkbox 가 아니다 */}
+                <FormControl>
+                  <SwitchSection
+                    title='실패 시 이메일 알림 받기'
+                    description='켜면 실행이 실패했을 때 아래 주소로 메일을 보냅니다'
+                    checked={field.value}
+                    onCheckedChange={(checked) => {
+                      field.onChange(checked)
+                      if (!checked) {
+                        form.setValue('email', '')
+                        form.clearErrors('email')
+                      }
+                    }}
+                  />
+                </FormControl>
+              </FormItem>
+            )}
+          />
+          {notifyOnFailure ? (
+            <FormField
+              control={form.control}
+              name='email'
+              rules={{
+                required: '받을 이메일을 입력하세요.',
+                pattern: {
+                  value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+                  message: '이메일 형식이 아닙니다.',
+                },
+              }}
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel required>받을 이메일</FormLabel>
+                  <FormControl>
+                    <TextField {...field} type='email' placeholder='name@example.com' />
+                  </FormControl>
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+          ) : null}
+        </FormSection>
+      </FormPage>
+
+      <AlertDialog open={confirmCancel} onOpenChange={setConfirmCancel}>
+        <AlertDialogContent variant='warning'>
+          <AlertDialogHeader>
+            <AlertDialogTitle>파이프라인 생성을 취소할까요?</AlertDialogTitle>
+            <AlertDialogDescription>입력한 내용은 저장되지 않고 사라집니다.</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>계속 작성</AlertDialogCancel>
+            <AlertDialogAction variant='warningBold' onClick={onLeave}>
+              취소하고 나가기
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  )
+}