` 내부 요소는 사용자가 선택(user-select)할 수 있습니다. ```tsx import { IconExclamationmarkCircleFill } from "@karrotmarket/react-monochrome-icon"; import { Article, Divider, Icon, Text, VStack } from "@seed-design/react"; import { PageBanner } from "seed-design/ui/page-banner"; export default function ArticleSelectable() { return ( } description="상위 요소에 `user-select: none;` 스타일 적용됨" tone="warning" variant="solid" /> Article 밖은 선택할 수 없습니다. 상위 요소에 `user-select: none;` 스타일이 적용되어 있어 이 영역의 텍스트는 선택할 수 없습니다. 길게 탭하거나 더블 클릭해보세요.

Article 안 상위 요소에 `user-select: none;` 스타일이 적용되었지만 Article 내부는 선택할 수 있습니다. 길게 탭하거나 더블 클릭해서 텍스트를 선택해보세요.

Article 밖은 선택할 수 없습니다. 길게 탭하거나 더블 클릭해보세요. ); } ``` #### Disable User Selection Text 컴포넌트의 [`userSelect="none"` prop](/react/components/typography/text#user-select)을 사용하여 `

` 내부 요소를 선택 불가능하게 만들 수 있습니다. Text 컴포넌트에 대해 자세히 알아봅니다. ```tsx import { IconExclamationmarkCircleFill } from "@karrotmarket/react-monochrome-icon"; import { Article, Divider, Icon, Text, VStack } from "@seed-design/react"; import { PageBanner } from "seed-design/ui/page-banner"; export default function ArticleSelectable() { return ( } description="상위 요소에 `user-select: none;` 스타일 적용됨" tone="warning" variant="solid" /> Article 밖은 선택할 수 없습니다. 상위 요소에 `user-select: none;` 스타일이 적용되어 있어 이 영역의 텍스트는 선택할 수 없습니다. 길게 탭하거나 더블 클릭해보세요.

Article 안 상위 요소에 `user-select: none;` 스타일이 적용되었지만 Article 내부는 선택할 수 있습니다. 길게 탭하거나 더블 클릭해서 텍스트를 선택해보세요. 이 요소는 Article 내부에 있지만 선택할 수 없습니다.

Article 밖은 선택할 수 없습니다. 길게 탭하거나 더블 클릭해보세요. ); } ``` #### Prevent `PullToRefresh` or `TabsCarousel` Gestures `

` 내부 요소는 사용자 선택이 가능합니다. 따라서, 드래그 동작을 통해 내부 요소를 선택 시 의도하지 않은 PTR(당겨서 새로고침) 또는 탭 스와이프 제스처가 발생할 수 있습니다. `PullToRefresh.preventPull` 또는 `Tabs.carouselPreventDrag`를 `

`에 전달하여 Article에서 발생한 이벤트가 제스처를 트리거하지 않도록 할 수 있습니다. PullToRefresh 컴포넌트에서 제스처를 방지할 영역을 지정하는 방법에 대해 알아봅니다. TabsCarousel 컴포넌트에서 제스처를 방지할 영역을 지정하는 방법에 대해 알아봅니다. ```tsx import { VStack, Icon, Text, Article, Divider, PullToRefresh } from "@seed-design/react"; import { type StaticActivityComponentType } from "@stackflow/react/future"; import { AppBar, AppBarMain } from "seed-design/ui/app-bar"; import { AppScreen, AppScreenContent } from "seed-design/ui/app-screen"; import { PullToRefreshContent, PullToRefreshIndicator, PullToRefreshRoot, } from "seed-design/ui/pull-to-refresh"; import { IconExclamationmarkCircleFill } from "@karrotmarket/react-monochrome-icon"; import { PageBanner } from "seed-design/ui/page-banner"; declare module "@stackflow/config" { interface Register { ActivityArticlePreventPull: {}; } } const ActivityArticlePreventPull: StaticActivityComponentType< "ActivityArticlePreventPull" > = () => { return ( Pull To Refresh {}} onPtrRefresh={async () => { await new Promise((resolve) => setTimeout(resolve, 1000)); }} > } description="상위 요소에 `user-select: none;` 스타일 적용됨" tone="warning" variant="solid" />

Article 이 요소는 Article 내부에 있으므로 텍스트 선택이 가능합니다. 이 Article은 PTR 제스처를 호출하지 않도록 설정되어 있습니다. 여기를 아래로 끌어 당기면 PTR이 작동하는 대신 텍스트가 선택됩니다.

Article 외부 이 요소는 Article 외부에 있으므로 텍스트 선택이 불가능합니다. 이 요소는 PTR을 호출할 수 있습니다. 여기를 아래로 끌어 당겨보세요. ); }; export default ActivityArticlePreventPull; ``` ```tsx import { VStack, Icon, Text, Article, Divider, Tabs } from "@seed-design/react"; import { type StaticActivityComponentType } from "@stackflow/react/future"; import { AppBar, AppBarMain } from "seed-design/ui/app-bar"; import { AppScreen, AppScreenContent } from "seed-design/ui/app-screen"; import { TabsCarousel, TabsContent, TabsList, TabsRoot, TabsTrigger } from "seed-design/ui/tabs"; import { IconExclamationmarkCircleFill } from "@karrotmarket/react-monochrome-icon"; import { PageBanner } from "seed-design/ui/page-banner"; declare module "@stackflow/config" { interface Register { ActivityArticlePreventDrag: {}; } } const ActivityArticlePreventDrag: StaticActivityComponentType< "ActivityArticlePreventDrag" > = () => { return ( Tabs Tab 1 Tab 2 } description="상위 요소에 `user-select: none;` 스타일 적용됨" tone="warning" variant="solid" />

Article 이 요소는 Article 내부에 있으므로 텍스트 선택이 가능합니다. 이 Article은 Tabs 제스처를 호출하지 않도록 설정되어 있습니다. 여기를 왼쪽으로 스와이프하면 탭이 전환되는 대신 텍스트가 선택됩니다.

Article 외부 이 요소는 Article 외부에 있으므로 텍스트 선택이 불가능합니다. 이 요소는 탭 스와이프를 호출할 수 있습니다. 여기를 왼쪽으로 스와이프해보세요. 안녕하세요! ); }; export default ActivityArticlePreventDrag; ``` ### Using `asChild` or `as` prop `

`은 기본적으로 `

`로 렌더링되지만, `asChild` 또는 `as` prop을 사용하여 다른 요소로 변경할 수 있습니다. `asChild` prop에 대해 자세히 알아봅니다. ```tsx import { Article, Divider, VStack, Text } from "@seed-design/react"; export default function ArticleAs() { return (

`as` prop으로 Article을 section으로 변경 Nulla exercitation quis aliqua nostrud.

`asChild` prop으로 Article을 section으로 변경 Elit fugiat elit exercitation laborum id veniam consequat ipsum sit voluptate velit.

); } ``` --- file: components/aspect-ratio.mdx # Aspect Ratio 가로(width)가 정해지면 비율에 따라 세로(height)가 자동으로 결정되는 레이아웃 컨테이너입니다. 사용 가능 버전: @seed-design/react@1.2.0, @seed-design/css@1.2.0 ## Preview ```tsx import { AspectRatio, Text, VStack } from "@seed-design/react"; export default function AspectRatioPreview() { return ( 4 / 3 1:1 16 / 9 ); } ``` ## Usage ```tsx import { AspectRatio } from "@seed-design/react"; ``` ```tsx

``` ## Props ## Examples ### Ratio 다양한 비율을 지정할 수 있습니다. `1`은 정사각형, `4/3`은 일반적인 사진 비율, `16/9`는 와이드스크린 비율입니다. ```tsx import { AspectRatio, Box, HStack } from "@seed-design/react"; export default function AspectRatioRatio() { return ( 1:1 Square

); } ``` --- file: components/attachment-display-field.mdx # Attachment Display Field 외부 소스에서 제공된 미디어를 URL 기반으로 표시하고 관리하는 컴포넌트입니다. 사용 가능 버전: @seed-design/react@2.0.0, @seed-design/css@2.0.0 ## Preview ```tsx import { VStack, type AttachmentDisplayItemEntry } from "@seed-design/react"; import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; const sampleEntries: AttachmentDisplayItemEntry[] = [ { id: "1", thumbnailUrl: "https://picsum.photos/seed/seed1/200/200", status: "success", }, { id: "2", thumbnailUrl: "https://picsum.photos/seed/seed2/200/200", status: "success", }, ]; // 외부 미디어 피커 모킹. 실제 환경에서는 네이티브 브릿지/모달/서버 호출 등으로 교체하세요. async function openMediaPicker(): Promise { const id = crypto.randomUUID(); return [ { id, thumbnailUrl: `https://picsum.photos/seed/${id}/200/200`, status: "success", }, ]; } export default function AttachmentDisplayPreview() { return ( { addEntries(await openMediaPicker()); }} /> ); } ``` ## Installation ### Default 순서 변경이 불필요한 경우 사용할 수 있는 컴포넌트를 포함합니다. - npm: npx @seed-design/cli@latest add ui:attachment-display-field - pnpm: pnpm dlx @seed-design/cli@latest add ui:attachment-display-field - yarn: yarn dlx @seed-design/cli@latest add ui:attachment-display-field - bun: bun x @seed-design/cli@latest add ui:attachment-display-field ### Reorderable 드래그 앤 드롭을 통한 항목 순서 변경이 필요한 경우 활용할 수 있는 컴포넌트를 포함합니다. 프로젝트에 [dnd-kit](https://dndkit.com/overview) 의존성이 추가됩니다. - npm: npx @seed-design/cli@latest add ui:attachment-display-field-reorderable - pnpm: pnpm dlx @seed-design/cli@latest add ui:attachment-display-field-reorderable - yarn: yarn dlx @seed-design/cli@latest add ui:attachment-display-field-reorderable - bun: bun x @seed-design/cli@latest add ui:attachment-display-field-reorderable ## Props ### `AttachmentDisplayField` ### `AttachmentDisplay` ### `AttachmentDisplayItem` ## Usage ### 기본 사용법 `AttachmentDisplayField` 안에 `AttachmentDisplay` 또는 `AttachmentDisplayReorderable`을 조합하여 사용합니다. `AttachmentDisplay`는 HTML ``을 사용하지 않습니다. `onTriggerClick`으로 외부 미디어 피커를 호출하고, 콜백 인자로 전달되는 `addEntries`에 그 결과를 넘겨 표시하세요. `addEntries`는 `maxEntries` 상한과 single-mode(`maxEntries={1}`) 치환을 내부에서 처리하므로, `entries`를 직접 펼쳐 넣는 것보다 안전합니다. [`AttachmentField`](/react/components/attachment-field)와 달리 `AttachmentDisplayField`는 파일의 유효성을 검증하거나 파일 객체를 직접 다루지 않습니다. ```tsx import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; { const pickedEntries = await openMediaPicker(); addEntries(pickedEntries); }} /> ; ``` `entries`와 `onEntriesChange`로 목록을 직접 제어하는 controlled 방식도 지원합니다. 이 경우에도 `addEntries`는 동일하게 동작합니다([Controlled](#controlled) 참고). ### Item 직접 구성하기 `AttachmentDisplay`, `AttachmentDisplayReorderable`은 `children`을 render prop으로 사용합니다. `entries`를 활용하여 `AttachmentDisplayItem`을 직접 렌더링할 수 있습니다. 이때 `DisplayItemEntry` 타입이 제공하는 `id`를 `key`로 활용하는 것을 권장합니다. `children`을 제공하지 않는 경우 자동으로 `entries`를 `AttachmentDisplayItem`으로 렌더링합니다. ```tsx import { AttachmentDisplay, AttachmentDisplayField, AttachmentDisplayItem, } from "seed-design/ui/attachment-display-field"; { addEntries(await openMediaPicker()); }} > {({ entries }) => entries.map((entry) => ( )) } ; ``` ## Adding Entries ### Trigger `AttachmentDisplay`는 trigger(업로드 버튼)가 포함된 레이아웃을 제공합니다. trigger 클릭 시 `onTriggerClick` 콜백이 실행됩니다. 일반적으로 외부 미디어 피커 호출을 수행합니다. 콜백은 `{ addEntries, updateEntryStatus }`를 인자로 받아, 피커 결과를 추가하고 곧바로 업로드 상태를 갱신할 수 있습니다. ```tsx import type { AttachmentDisplayItemEntry } from "@seed-design/react"; import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; const defaultEntries: AttachmentDisplayItemEntry[] = [ { id: "1", thumbnailUrl: "https://picsum.photos/seed/trigger1/200/200", status: "success", }, ]; // 외부 미디어 피커 모킹. 실제 환경에서는 네이티브 브릿지/모달/서버 호출 등으로 교체하세요. async function openMediaPicker(): Promise { const id = crypto.randomUUID(); return [ { id, thumbnailUrl: `https://picsum.photos/seed/${id}/200/200`, status: "success", }, ]; } export default function AttachmentDisplayTrigger() { return ( { addEntries(await openMediaPicker()); }} /> ); } ``` ### Listening to Entry Changes `entries`는 현재 표시되고 있는 항목의 목록입니다. `onEntriesChange` 콜백으로 `entries`에 등록된 파일 변경 이벤트를 감지할 수 있습니다. ```tsx "use client"; import { Text, VStack, type AttachmentDisplayItemEntry } from "@seed-design/react"; import { useRef, useState } from "react"; import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; // 외부 미디어 피커 모킹. 실제 환경에서는 네이티브 브릿지/모달/서버 호출 등으로 교체하세요. async function openMediaPicker(): Promise { const id = crypto.randomUUID(); return [ { id, thumbnailUrl: `https://picsum.photos/seed/${id}/200/200`, status: "success", }, ]; } export default function AttachmentDisplayValueChanges() { const [entries, setEntries] = useState([]); const entriesRef = useRef(entries); const [logs, setLogs] = useState([]); entriesRef.current = entries; const addLog = (message: string) => { setLogs((prev) => [...prev, `[${new Date().toLocaleTimeString()}] ${message}`]); }; // addEntries로 추가하든 제거 버튼으로 지우든 변경은 항상 onEntriesChange로 흐르므로, // 추가/삭제 감지를 여기 한 곳에서 처리합니다. const handleEntriesChange = (next: AttachmentDisplayItemEntry[]) => { const prev = entriesRef.current; const added = next.filter((n) => !prev.some((p) => p.id === n.id)); const removed = prev.filter((p) => !next.some((n) => n.id === p.id)); if (added.length > 0) addLog(`added: ${added.map((a) => a.id).join(", ")}`); if (removed.length > 0) addLog(`removed: ${removed.map((r) => r.id).join(", ")}`); setEntries(next); }; return ( {logs.length === 0 ? ( 아이템을 추가하거나 삭제하면 로그가 표시됩니다. ) : ( logs.map((log, index) => ( {log} )) )} { addEntries(await openMediaPicker()); }} /> ); } ``` ## Managing Item Status `entries`의 각 항목은 `pending`, `uploading`, `success`, `error`의 status를 가질 수 있습니다. 새로 추가되는 항목의 status 기본값은 의도에 맞게 자유롭게 지정할 수 있습니다(외부 피커가 막 던진 항목이라면 `uploading`, 이미 업로드 완료된 미디어를 hydrate한다면 `success`). 외부 업로드 API와 연동하는 경우, `onTriggerClick`·`onRetry` 콜백으로 함께 전달되는 `updateEntryStatus` 헬퍼를 사용하여 각 항목의 status를 업데이트합니다. ```tsx "use client"; import { VStack, type AttachmentDisplayItemEntry, type AttachmentDisplayItemStatusDetails, } from "@seed-design/react"; import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; const defaultEntries: AttachmentDisplayItemEntry[] = [ { id: "1", thumbnailUrl: "https://picsum.photos/seed/upload1/200/200", status: "uploading", progress: 30, }, { id: "2", thumbnailUrl: "https://picsum.photos/seed/upload2/200/200", status: "success", }, { id: "3", thumbnailUrl: "https://picsum.photos/seed/upload3/200/200", status: "error", }, ]; // 외부 미디어 피커 모킹. 실제 환경에서는 네이티브 브릿지/모달/서버 호출 등으로 교체하세요. async function openMediaPicker(): Promise { const id = crypto.randomUUID(); return [ { id, thumbnailUrl: `https://picsum.photos/seed/${id}/200/200`, status: "uploading", }, ]; } // 실제 환경에서는 네이티브 브릿지 또는 외부 업로드 API와 연동하세요. // status는 컴포넌트가 콜백으로 전달하는 updateEntryStatus 헬퍼로만 갱신합니다. function simulateUpload( id: string, updateEntryStatus: (id: string, details: AttachmentDisplayItemStatusDetails) => void, ) { updateEntryStatus(id, { status: "uploading", progress: 0 }); let progress = 0; const interval = setInterval(() => { progress += 20; if (progress >= 100) { clearInterval(interval); updateEntryStatus(id, Math.random() > 0.5 ? { status: "success" } : { status: "error" }); } else { updateEntryStatus(id, { status: "uploading", progress }); } }, 300); } export default function AttachmentDisplayStatus() { return ( { const pickedEntries = await openMediaPicker(); addEntries(pickedEntries); for (const entry of pickedEntries) { simulateUpload(entry.id, updateEntryStatus); } }} onRetry={(entry, { updateEntryStatus }) => simulateUpload(entry.id, updateEntryStatus)} /> ); } ``` - `uploading`: [ProgressCircle](/react/components/progress-circle)이 표시됩니다. - `progress`를 설정하여 업로드 진행률을 표시할 수 있습니다. - `progress`를 지정하지 않는 경우 [indeterminate](/react/components/progress-circle#indeterminate) 상태로 표시됩니다. - `error`: 재시도 버튼이 표시됩니다. - 클릭 시 `AttachmentDisplay`에 지정한 `onRetry` 콜백이 `(entry, { updateEntryStatus })` 인자로 실행됩니다. `updateEntryStatus`로 해당 항목을 다시 `uploading` 상태로 되돌려 업로드를 재시도하세요. ## Reordering Entries `AttachmentDisplayReorderable`을 사용하면 드래그로 항목의 순서를 변경할 수 있습니다. 해당 컴포넌트는 `dnd-kit` 의존성 분리를 위해 별도 snippet [`ui:attachment-display-field-reorderable`](#reorderable)로 제공됩니다. Context를 통해 `reorderEntry`가 제공되므로, 필요한 경우 원하는 드래그 앤 드롭 동작을 직접 구현하거나, 이미 프로젝트에서 사용 중인 드래그 앤 드롭 라이브러리와 연동하여 사용할 수 있습니다. ```tsx "use client"; import type { AttachmentDisplayItemEntry } from "@seed-design/react"; import { useState } from "react"; import { AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; import { AttachmentDisplayReorderable } from "seed-design/ui/attachment-display-field-reorderable"; const defaultEntries: AttachmentDisplayItemEntry[] = [ { id: "1", thumbnailUrl: "https://picsum.photos/seed/reorder1/200/200", status: "success" }, { id: "2", thumbnailUrl: "https://picsum.photos/seed/reorder2/200/200", status: "success" }, { id: "3", thumbnailUrl: "https://picsum.photos/seed/reorder3/200/200", status: "success" }, ]; // 외부 미디어 피커 모킹. 실제 환경에서는 네이티브 브릿지/모달/서버 호출 등으로 교체하세요. async function openMediaPicker(): Promise { const id = crypto.randomUUID(); return [ { id, thumbnailUrl: `https://picsum.photos/seed/${id}/200/200`, status: "success", }, ]; } export default function AttachmentDisplayReorderableExample() { const [entries, setEntries] = useState(defaultEntries); return ( { addEntries(await openMediaPicker()); }} /> ); } ``` ## Examples ### Disabled `disabled` prop으로 trigger 버튼을 비활성화할 수 있습니다. ```tsx import { VStack, type AttachmentDisplayItemEntry } from "@seed-design/react"; import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; const sampleEntries: AttachmentDisplayItemEntry[] = [ { id: "1", thumbnailUrl: "https://picsum.photos/seed/disabled1/200/200", status: "success", }, ]; export default function AttachmentDisplayDisabled() { return ( {}} /> ); } ``` ### Read Only `readOnly` prop으로 읽기 전용 상태를 표현할 수 있습니다. trigger, 파일 제거 버튼, 순서 변경 모두 비활성화됩니다. ```tsx import { VStack, type AttachmentDisplayItemEntry } from "@seed-design/react"; import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; const sampleEntries: AttachmentDisplayItemEntry[] = [ { id: "1", thumbnailUrl: "https://picsum.photos/seed/readonly1/200/200", status: "success", }, { id: "2", thumbnailUrl: "https://picsum.photos/seed/readonly2/200/200", status: "success", }, ]; export default function AttachmentDisplayReadOnly() { return ( {}} /> ); } ``` ### Controlled `entries`와 `onEntriesChange`를 사용하여 외부에서 아이템 목록을 제어할 수 있습니다. ```tsx "use client"; import { HStack, Text, VStack, type AttachmentDisplayItemEntry } from "@seed-design/react"; import { useState } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; // 외부 미디어 피커 모킹. 실제 환경에서는 네이티브 브릿지/모달/서버 호출 등으로 교체하세요. async function openMediaPicker(): Promise { const id = crypto.randomUUID(); return [ { id, thumbnailUrl: `https://picsum.photos/seed/${id}/200/200`, status: "success", }, ]; } export default function AttachmentDisplayControlled() { const [entries, setEntries] = useState([]); return ( { addEntries(await openMediaPicker()); }} /> 현재 아이템: {entries.length}개 setEntries([])}> 전체 삭제 ); } ``` ### Custom Inset `--seed-attachment-input-extend-x` CSS 변수를 사용하여 스크롤되는 아이템 목록이 레이아웃 바깥으로 빠져나오도록 구성할 수 있습니다. ```tsx import { vars } from "@seed-design/css/vars"; import { VStack, type AttachmentDisplayItemEntry } from "@seed-design/react"; import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; import { TextField, TextFieldInput } from "seed-design/ui/text-field"; const defaultEntries: AttachmentDisplayItemEntry[] = Array.from({ length: 8 }, (_, i) => ({ id: String(i + 1), thumbnailUrl: `https://picsum.photos/seed/inset${i + 1}/200/200`, status: "success", })); export default function AttachmentDisplayCustomInset() { return ( { // 외부 미디어 피커 호출 자리 }} /> ); } ``` `controlProps`에 `extendSafeAreaX`를 함께 지정하면 목록이 `--seed-attachment-input-extend-x`에 좌우 safe area inset을 더한 만큼 넓어져 화면 끝까지 스크롤되고, 첫 항목과 마지막 항목은 safe area 안에 남습니다. `AppScreenContent`처럼 inset을 반영한 컨테이너 안에서 사용하세요. 화면 끝까지 채우는 다른 방법은 [Safe Area 구현 가이드](/react/components/concepts/safe-area#화면-끝까지-채우기)를 참고하세요. ### Field Integration `label`, `description`, `errorMessage` 등 Field 관련 prop을 전달할 수 있습니다. ```tsx "use client"; import { VStack, type AttachmentDisplayItemEntry } from "@seed-design/react"; import { useState } from "react"; import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; const defaultEntries: AttachmentDisplayItemEntry[] = [ { id: "1", thumbnailUrl: "https://picsum.photos/seed/field1/200/200", status: "success" }, ]; // 외부 미디어 피커 모킹. 실제 환경에서는 네이티브 브릿지/모달/서버 호출 등으로 교체하세요. async function openMediaPicker(): Promise { const id = crypto.randomUUID(); return [ { id, thumbnailUrl: `https://picsum.photos/seed/${id}/200/200`, status: "success", }, ]; } export default function AttachmentDisplayFieldExample() { const [entries, setEntries] = useState(defaultEntries); const invalid = entries.length < 1; return ( { addEntries(await openMediaPicker()); }} /> ); } ``` ### Customizing Items Snippet이 제공하는 기본 아이템 구성 외에 추가적인 커스터마이징이 필요한 경우, `@seed-design/react`에서 제공하는 `AttachmentDisplay.ItemBadge` 등의 요소를 활용하여 직접 아이템을 구성할 수 있습니다. 아래 예시에서는 `AttachmentDisplay.ItemBadge`를 사용하여 첫 번째 이미지에 "대표사진" 배지를 표시합니다. ```tsx "use client"; import { IconArrowClockwiseCircularFill, IconXmarkFill } from "@karrotmarket/react-monochrome-icon"; import { AttachmentDisplay as SeedAttachmentDisplay, Icon, VStack, type AttachmentDisplayItemEntry, } from "@seed-design/react"; import { AttachmentDisplay, AttachmentDisplayField } from "seed-design/ui/attachment-display-field"; import { ProgressCircle } from "seed-design/ui/progress-circle"; const LABEL_REMOVE = "삭제"; const LABEL_RETRY = "재시도"; function CustomImageItem({ entry, isCover, onRetry, }: { entry: AttachmentDisplayItemEntry; isCover?: boolean; onRetry?: () => void; }) { return ( {isCover && 대표사진} {(e) => ( )} {onRetry && ( } /> {LABEL_RETRY} )} } /> ); } const defaultEntries: AttachmentDisplayItemEntry[] = [ { id: "1", thumbnailUrl: "https://picsum.photos/seed/customizing1/200/200", status: "success" }, { id: "2", thumbnailUrl: "https://picsum.photos/seed/customizing2/200/200", status: "success" }, { id: "3", thumbnailUrl: "https://picsum.photos/seed/customizing3/200/200", status: "success" }, ]; export default function AttachmentDisplayCustomizingItems() { return ( { // 외부 미디어 피커 호출 자리 }} > {({ entries }) => entries.map((entry, index) => ( )) } ); } ``` ## Attachment Display Field vs. Attachment Field HTML ``을 사용해야 하는 경우 `AttachmentField`를, 외부 소스와 연동하여 URL 기반으로 미디어를 표시해야 하는 경우 `AttachmentDisplayField`를 사용하세요. | | Attachment Field | Attachment Display | | -------------- | -------------------------- | ---------------------------- | | 미디어 소스 | HTML `` | 이미지 URL | | 데이터 모델 | `File` 기반 `FileEntry` | URL 기반 `DisplayItemEntry` | | 파일 선택 | `` | 다루지 않음 (`onTriggerClick` 위임) | | 드래그 앤 드롭으로 업로드 | `AttachmentDropzone` | 다루지 않음 | | 파일 검증 | accept, maxFileSize 등 | 다루지 않음 | | Form 연동 | `` 동기화 | 다루지 않음 | --- file: components/attachment-field.mdx # Attachment Field 파일을 선택하거나 드래그 앤 드롭으로 업로드할 수 있는 컴포넌트입니다. 사용 가능 버전: @seed-design/react@2.0.0, @seed-design/css@2.0.0 ## Preview ```tsx import { VStack } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; export default function AttachmentFieldPreview() { return ( ); } ``` ## Installation ### Default 파일 순서 변경이 불필요한 경우 사용할 수 있는 컴포넌트를 포함합니다. - npm: npx @seed-design/cli@latest add ui:attachment-field - pnpm: pnpm dlx @seed-design/cli@latest add ui:attachment-field - yarn: yarn dlx @seed-design/cli@latest add ui:attachment-field - bun: bun x @seed-design/cli@latest add ui:attachment-field ### Reorderable 드래그 앤 드롭을 통한 파일 순서 변경이 필요한 경우 활용할 수 있는 컴포넌트를 포함합니다. 프로젝트에 [dnd-kit](https://dndkit.com/overview) 의존성이 추가됩니다. - npm: npx @seed-design/cli@latest add ui:attachment-field-reorderable - pnpm: pnpm dlx @seed-design/cli@latest add ui:attachment-field-reorderable - yarn: yarn dlx @seed-design/cli@latest add ui:attachment-field-reorderable - bun: bun x @seed-design/cli@latest add ui:attachment-field-reorderable ## Props ### `AttachmentField` ### `AttachmentInput` ### `AttachmentDropzone` ### `AttachmentInputItem` ## Usage ### 기본 사용법 `AttachmentField` 안에 `AttachmentInput`, `AttachmentDropzone`, `AttachmentInputReorderable`, `AttachmentDropzoneReorderable` 중 하나를 조합하여 사용합니다. ```tsx import { AttachmentField, AttachmentInput, AttachmentDropzone, } from "seed-design/ui/attachment-field"; ; ; ``` ```tsx import { AttachmentField } from "seed-design/ui/attachment-field"; import { AttachmentInputReorderable, AttachmentDropzoneReorderable, } from "seed-design/ui/attachment-field-reorderable"; ; ; ``` ### Item 직접 구성하기 `AttachmentInput`, `AttachmentDropzone`, `AttachmentInputReorderable`, `AttachmentDropzoneReorderable`은 `children`을 render prop으로 사용합니다. `acceptedFileEntries`을 활용하여 `AttachmentInputItem`을 직접 렌더링할 수 있습니다. 이때 `FileEntry` 타입이 제공하는 `id`를 `key`로 활용하는 것을 권장합니다. `children`을 제공하지 않는 경우 자동으로 `acceptedFileEntries`에 등록된 파일을 `AttachmentInputItem`으로 렌더링합니다. ```tsx import { AttachmentField, AttachmentInput, AttachmentInputItem, } from "seed-design/ui/attachment-field"; {({ acceptedFileEntries }) => acceptedFileEntries.map((entry) => ( )) } ; ``` ## Uploading Files ### Trigger `AttachmentInput`를 사용하면 trigger(업로드 버튼)가 포함된 레이아웃을 사용할 수 있습니다. ```tsx import type { AttachmentInputFileEntry } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; const defaultAcceptedFileEntries: AttachmentInputFileEntry[] = [ { id: "1", file: new File(["hello"], "document.pdf", { type: "application/pdf" }), status: "success", }, ]; export default function AttachmentFieldTriggerExample() { return ( ); } ``` ### Dropzone `AttachmentDropzone`을 사용하면 드래그 앤 드롭 영역이 포함된 레이아웃을 사용할 수 있습니다. ```tsx import { VStack, type AttachmentInputFileEntry } from "@seed-design/react"; import { AttachmentField, AttachmentDropzone } from "seed-design/ui/attachment-field"; const defaultAcceptedFileEntries: AttachmentInputFileEntry[] = [ { id: "1", file: new File(["hello"], "document.pdf", { type: "application/pdf" }), status: "success", }, ]; export default function AttachmentFieldDropzone() { return ( ); } ``` ### Listening to Accepted File Changes `acceptedFileEntries`는 유효성 검사를 마친 파일의 목록입니다. `onAcceptedFileEntriesChange` 콜백으로 `acceptedFileEntries`에 등록된 파일 변경 이벤트를 감지할 수 있습니다. ```tsx import { VStack, Text, type AttachmentInputFileStatusDetails } from "@seed-design/react"; import { useState } from "react"; import { AttachmentField, AttachmentInput, AttachmentInputItem, } from "seed-design/ui/attachment-field"; function simulateUpload( _file: File, id: string, updateFileEntryStatus: (id: string, details: AttachmentInputFileStatusDetails) => void, ) { updateFileEntryStatus(id, { status: "uploading", progress: 0 }); let progress = 0; const interval = setInterval(() => { progress += 25; if (progress >= 100) { clearInterval(interval); updateFileEntryStatus(id, { status: "success" }); } else { updateFileEntryStatus(id, { status: "uploading", progress }); } }, 500); } export default function AttachmentFieldValueChanges() { const [logs, setLogs] = useState([]); const addLog = (message: string) => { setLogs((prev) => [...prev, `[${new Date().toLocaleTimeString()}] ${message}`]); }; return ( {logs.length === 0 ? ( 파일을 추가하거나 삭제하면 로그가 표시됩니다. ) : ( logs.map((log, index) => ( {log} )) )} { addLog(`onFileAccept: ${entries.map((e) => e.file.name).join(", ")}`); for (const entry of entries) { simulateUpload(entry.file, entry.id, updateFileEntryStatus); } }} onAcceptedFileEntriesChange={(files) => { addLog( `onAcceptedFileEntriesChange: ${files.map((f) => `${f.file.name} (${f.status})`).join(", ")}`, ); }} onFileReject={(files) => { addLog( `onFileReject: ${files.map((f) => `${f.file.name} (${f.errors.join(", ")})`).join(", ")}`, ); }} > {({ acceptedFileEntries }) => acceptedFileEntries.map((fileEntry) => ( )) } ); } ``` ## Validating Files 사용자가 선택한 파일이 `acceptedFileEntries`에 등록되기 전 유효성을 확인할 수 있습니다. 유효하지 않은 파일에 대해 각각 `onFileReject` 콜백이 실행됩니다. 해당 콜백에서 파일과 에러 코드들을 확인하여 에러 메시지를 표시할 수 있습니다. ### Max Files `maxFiles`로 업로드 가능한 최대 파일 수를 제한할 수 있습니다. 기본값은 `1`입니다. 최대 수에 도달한 경우 trigger 및 dropzone이 비활성화됩니다. 업로드 가능한 파일의 수보다 많은 파일을 선택한 경우 업로드 가능한 파일까지 `acceptedFileEntries`에 등록됩니다. 나머지 파일에 대해서는 각각 `onFileReject` 콜백이 실행됩니다. 이때 reject된 파일의 에러는 `"TOO_MANY_FILES"`입니다. ```tsx import { VStack, type AttachmentInputFileEntry } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; const defaultAcceptedFileEntries: AttachmentInputFileEntry[] = [ { id: "1", file: new File(["hello"], "document.pdf", { type: "application/pdf" }), status: "success", }, ]; export default function AttachmentFieldMaxFiles() { return ( ); } ``` ### Invalid File Type `accept`로 업로드 가능한 파일의 종류를 제한할 수 있습니다. MIME type(`image/png`, `image/*`) 또는 확장자(`.png`, `.jpg, .jpeg`) 형식을 지정할 수 있으며, `string[]`을 전달하는 경우 각 `string` `,`로 join합니다. ``에 등록되는 `accept` 속성을 통해 사용자가 선택할 수 있는 파일의 종류를 제한하는 것은 브라우저 UI에서만 동작하는 편의 기능입니다. 따라서 사용자는 브라우저 파일 선택 다이얼로그의 `모든 파일 보기`와 같은 기능을 통해 제한된 종류의 파일도 선택할 수 있습니다. 이렇게 선택된 파일의 경우 `"INVALID_TYPE"` 에러와 함께 `onFileReject` 콜백이 실행됩니다. 파일 종류 검증이 필요한 경우 해당 검증은 서버에서도 수행되어야 합니다. ```tsx import { useState } from "react"; import { VStack } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; function getErrorMessage(errorCode: string): string { switch (errorCode) { case "INVALID_TYPE": return "지원하지 않는 파일 형식입니다"; default: return "업로드에 실패했습니다"; } } export default function AttachmentFieldInvalidFileType() { const [errorMessage, setErrorMessage] = useState(); return ( setErrorMessage(undefined)} onFileReject={(files) => { const messages = files.map( ({ file, errors }) => `"${file.name}": ${errors.map(getErrorMessage).join(", ")}`, ); setErrorMessage(messages.join("\n")); }} > ); } ``` ### File Size `minFileSize`, `maxFileSize` prop을 활용할 수 있습니다. - 사용자가 선택한 파일이 `minFileSize`보다 작은 경우 `"FILE_TOO_SMALL"` 에러와 함께 `onFileReject` 콜백이 실행됩니다. - 사용자가 선택한 파일이 `maxFileSize`보다 큰 경우 `"FILE_TOO_LARGE"` 에러와 함께 `onFileReject` 콜백이 실행됩니다. ```tsx import { useState } from "react"; import { VStack } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; import { formatBytes } from "seed-design/lib/format-bytes"; const MIN_FILE_SIZE = 1 * 1024; // 1KB const MAX_FILE_SIZE = 10 * 1024; // 10KB function getErrorMessage(errorCode: string): string { switch (errorCode) { case "FILE_TOO_LARGE": return `크기가 ${formatBytes(MAX_FILE_SIZE)}를 초과합니다`; case "FILE_TOO_SMALL": return `크기가 ${formatBytes(MIN_FILE_SIZE)} 미만입니다`; case "TOO_MANY_FILES": return "업로드 가능한 파일 개수를 초과했습니다"; default: return "업로드에 실패했습니다"; } } export default function AttachmentFieldValidation() { const [errorMessage, setErrorMessage] = useState(); return ( setErrorMessage(undefined)} onFileReject={(files) => { const messages = files.map( ({ file, errors }) => `"${file.name}": ${errors.map(getErrorMessage).join(", ")}`, ); setErrorMessage(messages.join("\n")); }} > ); } ``` ### Custom Validation `validate` prop으로 각 파일에 대한 유효성 검사를 직접 추가할 수 있습니다. 커스텀 에러 코드를 반환하여 `onFileReject`에서 에러 종류별로 메시지를 분기할 수 있습니다. ```tsx import { useState } from "react"; import { VStack } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; function validateFileName(file: File) { const nameWithoutExt = file.name.replace(/\.[^.]+$/, ""); if (nameWithoutExt.length > 8) { return ["FILENAME_TOO_LONG"]; } return null; } export default function AttachmentFieldCustomValidation() { const [errorMessage, setErrorMessage] = useState(); return ( setErrorMessage(undefined)} onFileReject={(files) => { if (files.every((f) => f.errors.includes("FILENAME_TOO_LONG")) === false) { return; } const names = files.map((f) => f.file.name).join(", "); setErrorMessage(`"${names}"은(는) 파일 이름이 8자를 초과합니다.`); }} > ); } ``` ## Managing File Status `acceptedFileEntries`의 각 항목은 `pending`, `uploading`, `success`, `error`의 status를 가질 수 있습니다. 새로 추가되는 항목의 status 기본값은 `pending`입니다. 파일 선택 직후 외부 업로드 API와 연동하는 경우, 사용자에게 각 파일 항목의 업로딩 상태를 보여줄 수 있습니다. `onFileAccept` 콜백에서 새로 추가된 파일을 받고, 함께 제공되는 `updateFileEntryStatus` 헬퍼를 사용하여 항목의 status를 업데이트합니다. ```tsx import { useCallback } from "react"; import { VStack, type AttachmentInputFileStatusDetails } from "@seed-design/react"; import { AttachmentField, AttachmentInput, AttachmentInputItem, } from "seed-design/ui/attachment-field"; // 실제 환경에서는 fetch 등으로 교체하세요. async function uploadFile( file: File, onProgress: (progress: number) => void, ): Promise<{ url: string }> { const totalChunks = 5; for (let i = 1; i <= totalChunks; i++) { await new Promise((r) => setTimeout(r, 200 + Math.random() * 300)); onProgress(Math.round((i / totalChunks) * 100)); } if (Math.random() > 0.5) { throw new Error("Network error"); } return { url: `https://example.com/uploads/${file.name}` }; } export default function AttachmentFieldStatus() { const startUpload = useCallback( ( file: File, id: string, updateFileEntryStatus: (id: string, details: AttachmentInputFileStatusDetails) => void, ) => { updateFileEntryStatus(id, { status: "uploading", progress: 0 }); uploadFile(file, (progress) => { updateFileEntryStatus(id, { status: "uploading", progress }); }) .then(() => updateFileEntryStatus(id, { status: "success" })) .catch(() => updateFileEntryStatus(id, { status: "error" })); }, [], ); return ( { for (const entry of entries) { startUpload(entry.file, entry.id, updateFileEntryStatus); } }} > {({ acceptedFileEntries, updateFileEntryStatus }) => acceptedFileEntries.map((fileEntry) => ( startUpload(fileEntry.file, fileEntry.id, updateFileEntryStatus)} /> )) } ); } ``` - `uploading`: [ProgressCircle](/react/components/progress-circle)이 표시됩니다. - `progress`를 설정하여 업로드 진행률을 표시할 수 있습니다. - `progress`를 지정하지 않는 경우 [indeterminate](/react/components/progress-circle#indeterminate) 상태로 표시됩니다. - `error`: 재시도 버튼이 표시됩니다. - 클릭 시 `AttachmentInputItem`에 지정한 `onRetry` 콜백이 실행됩니다. 유효성 검증에 성공한 파일 항목은 status와 관계없이 `acceptedFileEntries`에 유지되므로, 네이티브 form 제출 시 포함됩니다. ## Reordering Files `AttachmentInputReorderable` 또는 `AttachmentDropzoneReorderable`을 사용하면 드래그로 파일의 순서를 변경할 수 있습니다. 두 컴포넌트는 `dnd-kit` 의존성 분리를 위해 별도 snippet [`ui:attachment-field-reorderable`](#reorderable)로 제공됩니다. Context를 통해 `reorderFileEntry`가 제공되므로, 필요한 경우 원하는 드래그 앤 드롭 동작을 직접 구현하거나, 이미 프로젝트에서 사용 중인 드래그 앤 드롭 라이브러리와 연동하여 사용할 수 있습니다. ```tsx import type { AttachmentInputFileEntry } from "@seed-design/react"; import { AttachmentField } from "seed-design/ui/attachment-field"; import { AttachmentInputReorderable } from "seed-design/ui/attachment-field-reorderable"; function createMockImageFile(name: string, base64: string): File { const bytes = Uint8Array.from(atob(base64), (c) => c.charCodeAt(0)); return new File([bytes], name, { type: "image/png" }); } const defaultAcceptedFileEntries: AttachmentInputFileEntry[] = [ { id: "1", file: createMockImageFile( "sunset-landscape.png", "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGN4FcEDAAN+AU+hW/ICAAAAAElFTkSuQmCC", ), status: "success", }, { id: "2", file: createMockImageFile( "city-night.png", "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGOYbPwKAAMNAbHKe2UaAAAAAElFTkSuQmCC", ), status: "success", }, { id: "3", file: createMockImageFile( "morning-coffee.png", "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGN4tZkDAAQwAaYlKXDxAAAAAElFTkSuQmCC", ), status: "success", }, ]; export default function AttachmentFieldReorderableExample() { return ( ); } ``` ## Examples ### Showing Thumbnails 파일 이름 및 크기 대신 이미지 미리보기를 표시하려면 `accept`를 `"image/*"`, `["image/png", "image/jpeg"]` 등으로 설정하여 사용자가 이미지 파일만 선택할 수 있도록 제한합니다. ```tsx import { VStack } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; export default function AttachmentFieldAcceptImage() { return ( ); } ``` [`"image/heic"`](https://caniuse.com/heif) 등 일부 이미지 형식은 브라우저에 따라 이미지 미리보기가 표시되지 않을 수 있습니다. ### Disabled `disabled` prop으로 trigger 및 dropzone을 비활성화하여 신규 파일 선택을 차단하고, ``을 `disabled` 처리하여 폼 제출 시 값이 전송되지 않도록 합니다. ```tsx import { VStack, type AttachmentInputFileEntry } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; const defaultFiles: AttachmentInputFileEntry[] = [ { id: "mock-1", file: new File(["hello"], "document.pdf", { type: "application/pdf" }), status: "success", }, { id: "mock-2", file: new File(["world"], "image.png", { type: "image/png" }), status: "success", }, ]; export default function AttachmentFieldDisabled() { return ( ); } ``` ### Read Only `readOnly` prop으로 첨부된 파일을 읽기 전용 상태로 표시할 수 있습니다. trigger, dropzone, 파일 제거 버튼, 순서 변경 모두 비활성화되지만 ``의 값은 유지되어 form 제출 시 함께 전송됩니다. ```tsx import { VStack, type AttachmentInputFileEntry } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; const defaultFiles: AttachmentInputFileEntry[] = [ { id: "mock-1", file: new File(["hello"], "document.pdf", { type: "application/pdf" }), status: "success", }, { id: "mock-2", file: new File(["world"], "image.png", { type: "image/png" }), status: "success", }, ]; export default function AttachmentFieldReadOnly() { return ( ); } ``` ### Controlled `acceptedFileEntries`와 `onAcceptedFileEntriesChange`를 사용하여 외부에서 파일 목록을 제어할 수 있습니다. ```tsx import { VStack, HStack, Text, type AttachmentInputFileEntry } from "@seed-design/react"; import { useState } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; export default function AttachmentFieldControlled() { const [acceptedFileEntries, setAcceptedFileEntries] = useState([]); return ( 현재 파일: {JSON.stringify(acceptedFileEntries.map((f) => f.file.name))} setAcceptedFileEntries([])} > 전체 삭제 ); } ``` ### Custom Inset `--seed-attachment-input-extend-x` CSS 변수를 사용하여 스크롤되는 아이템 목록이 레이아웃 바깥으로 빠져나오도록 구성할 수 있습니다. ```tsx import { VStack } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; import { TextField, TextFieldInput } from "seed-design/ui/text-field"; import { vars } from "@seed-design/css/vars"; const mockedFiles = Array.from({ length: 8 }, (_, i) => { const file = new File(["file content"], `file${i + 1}.txt`, { type: "text/plain" }); Object.defineProperty(file, "size", { value: 1 }); return file; }); export default function AttachmentFieldCustomInset() { return ( ({ id: `${index}`, file, status: "pending", }))} rootProps={{ style: { "--seed-attachment-input-extend-x": vars.$dimension.spacingX.globalGutter, } as React.CSSProperties, }} > ); } ``` `extendSafeAreaX`를 함께 지정하면 목록이 `--seed-attachment-input-extend-x`에 좌우 safe area inset을 더한 만큼 넓어져 화면 끝까지 스크롤되고, 첫 항목과 마지막 항목은 safe area 안에 남습니다. `AppScreenContent`처럼 inset을 반영한 컨테이너 안에서 사용하세요. 화면 끝까지 채우는 다른 방법은 [Safe Area 구현 가이드](/react/components/concepts/safe-area#화면-끝까지-채우기)를 참고하세요. ### Field Integration `label`, `description`, `errorMessage` 등의 Field 관련 prop을 사용할 수 있습니다. ```tsx import { Divider, VStack } from "@seed-design/react"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; export default function AttachmentFieldField() { return ( ); } ``` ### Form (Uncontrolled) `acceptedFileEntries`에 등록된 파일이 ``의 `files`로 동기화되므로 `

`과 `name` prop을 사용하여 formData에 포함시킬 수 있습니다. ```tsx import { VStack } from "@seed-design/react"; import { useState, type FormEvent } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; type FieldErrors = { files?: string; }; export default function AttachmentFieldForm() { const [fieldErrors, setFieldErrors] = useState({}); const handleSubmit = (event: FormEvent) => { event.preventDefault(); const formData = new FormData(event.currentTarget); const files = formData.getAll("files") as File[]; if (files.length === 0) { setFieldErrors({ files: "최소 1개의 파일을 업로드해주세요" }); return; } window.alert(`제출된 파일: ${files.map((f) => f.name).join(", ")}`); }; return ( { if (files.length > 0) { setFieldErrors({}); } }} {...(fieldErrors.files && { invalid: true, errorMessage: fieldErrors.files })} > 제출 ); } ``` ### React Hook Form ```tsx import { HStack, VStack, type AttachmentInputFileEntry } from "@seed-design/react"; import { useCallback, type FormEvent } from "react"; import { useController, useForm } from "react-hook-form"; import { ActionButton } from "seed-design/ui/action-button"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; interface FormValues { files: AttachmentInputFileEntry[]; } export default function AttachmentFieldReactHookForm() { const { handleSubmit, reset, control } = useForm({ reValidateMode: "onSubmit", defaultValues: { files: [], }, }); const { field: { value, onChange, ...field }, fieldState, } = useController({ name: "files", control, rules: { validate: (value) => value.length > 0 || "최소 1개의 파일을 업로드해주세요", }, }); const onValid = useCallback( (data: FormValues) => window.alert(`제출된 파일: ${data.files.map((f) => f.file.name).join(", ")}`), [], ); const onReset = useCallback( (event: FormEvent) => { event.preventDefault(); reset(); }, [reset], ); return ( 초기화 제출 ); } ``` ### Customizing Items Snippet이 제공하는 기본 아이템 구성 외에 추가적인 커스터마이징이 필요한 경우, `@seed-design/react`에서 제공하는 `AttachmentInput.ItemBadge` 등의 요소를 활용하여 직접 아이템을 구성할 수 있습니다. 아래 예시에서는 `AttachmentInput.ItemBadge`를 사용하여 첫 번째 이미지에 "대표사진" 배지를 표시합니다. ```tsx "use client"; import { AttachmentInput as SeedAttachmentInput, Icon, VStack, type AttachmentInputFileEntry, } from "@seed-design/react"; import { IconArrowClockwiseCircularFill, IconXmarkFill } from "@karrotmarket/react-monochrome-icon"; import { AttachmentField, AttachmentInput } from "seed-design/ui/attachment-field"; import { ProgressCircle } from "seed-design/ui/progress-circle"; const LABEL_REMOVE_FILE = "파일 제거"; const LABEL_RETRY = "재시도"; function CustomImageItem({ fileEntry, isCover, onRetry, }: { fileEntry: AttachmentInputFileEntry; isCover?: boolean; onRetry?: () => void; }) { return ( {isCover && 대표사진} {(entry) => ( )} {onRetry && ( } /> {LABEL_RETRY} )} } /> ); } export default function AttachmentFieldCustomizingItems() { return ( {({ acceptedFileEntries }) => acceptedFileEntries.map((fileEntry, index) => ( )) } ); } ``` --- file: components/avatar.mdx # Avatar 사용자의 프로필 이미지를 표시하는 컴포넌트입니다. 사용 가능 버전: @seed-design/react@0.0.1, @seed-design/css@0.0.1 ## Preview ```tsx import { Box, Flex } from "@seed-design/react"; import { Avatar, AvatarBadge } from "seed-design/ui/avatar"; import { IdentityPlaceholder } from "seed-design/ui/identity-placeholder"; export default function AvatarPreview() { return ( } > } /> ); } ``` ## Installation - npm: npx @seed-design/cli@latest add ui:avatar - pnpm: pnpm dlx @seed-design/cli@latest add ui:avatar - yarn: yarn dlx @seed-design/cli@latest add ui:avatar - bun: bun x @seed-design/cli@latest add ui:avatar ## Props ### `Avatar` ### `AvatarBadge` ### `AvatarStack` ## Examples ### Size ```tsx import { Flex } from "@seed-design/react"; import { Avatar } from "seed-design/ui/avatar"; export default function AvatarSize() { return ( ); } ``` ### Badge & Badge Mask ```tsx import { IdentityPlaceholder } from "seed-design/ui/identity-placeholder"; import { Avatar, AvatarBadge } from "seed-design/ui/avatar"; import { Box, HStack } from "@seed-design/react"; export default function () { return ( } > } > 뱃지를 설명하는 대체 텍스트를 제공해야 합니다.

} >

); } ``` ### Stack ```tsx import { Avatar, AvatarStack } from "seed-design/ui/avatar"; import { IdentityPlaceholder } from "seed-design/ui/identity-placeholder"; export default function AvatarStackExample() { return ( } /> } /> } /> } /> ); } ``` ### Fallback Image `fallback` prop으로 이미지가 로드되지 않았을 때 보여질 요소를 지정할 수 있습니다. 주로 [IdentityPlaceholder](/react/components/identity-placeholder)를 사용합니다. ```tsx import { Flex } from "@seed-design/react"; import { Avatar } from "seed-design/ui/avatar"; import { IdentityPlaceholder } from "seed-design/ui/identity-placeholder"; export default function AvatarFallbackExample() { return ( } /> } /> ); } ``` --- file: components/badge.mdx # Badge 객체의 속성이나 상태를 시각적으로 표현하는 작은 텍스트 라벨입니다. 사용자의 주의를 끌고 콘텐츠의 빠른 인지와 탐색을 돕기 위해 사용됩니다. 사용 가능 버전: @seed-design/react@0.0.1, @seed-design/css@0.0.1 ## Preview ```tsx "use client"; import { Badge } from "seed-design/ui/badge"; export default function BadgePreview() { return 라벨; } ``` ## Installation - npm: npx @seed-design/cli@latest add ui:badge - pnpm: pnpm dlx @seed-design/cli@latest add ui:badge - yarn: yarn dlx @seed-design/cli@latest add ui:badge - bun: bun x @seed-design/cli@latest add ui:badge ## Props ## Usage ```tsx "use client"; import { Badge } from "seed-design/ui/badge"; export function Example() { return 라벨; } ``` ## Prefix and Action `prefix`에는 Label 앞에 표시할 아이콘 요소를 전달합니다. ```tsx "use client"; import { IconHeartFill } from "@karrotmarket/react-monochrome-icon"; import { Badge } from "seed-design/ui/badge"; export default function BadgePrefix() { return }>관심 등록; } ``` 정보 아이콘에는 안내의 양과 사용자가 해야 할 일에 맞는 UI를 연결하세요. 짧은 설명에는 `actionProps.render`로 Help Bubble을 연결할 수 있습니다. `actionProps`에는 정보 아이콘 버튼의 접근성 이름인 `aria-label`을 반드시 전달하세요. ```tsx "use client"; import { HelpBubbleTrigger } from "seed-design/ui/help-bubble"; import { Badge } from "seed-design/ui/badge"; export default function BadgeWithAction() { return ( ( {trigger} ), }} > 판매 완료 ); } ``` 설명이 길거나 사용자의 확인이 필요하면 Bottom Sheet를 연결할 수 있습니다. 다음 예시는 부동산 게시글의 `집주인` Badge에서 집주인 인증에 관한 설명을 제공합니다. ```tsx "use client"; import { useState } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { Badge } from "seed-design/ui/badge"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; export default function BadgeWithBottomSheet() { const [open, setOpen] = useState(false); return ( {trigger}, }} > 집주인 매물을 올린 사람이 집주인임을 확인할 수 있어, 중개소에서 등록한 매물과 구분할 수 있어요. setOpen(false)}> 확인 ); } ``` ## Examples ### Truncating Behavior 긴 라벨을 한 줄로 줄여 표시하려면 `style.maxWidth`로 최대 너비를 지정하세요. 지정한 너비를 넘는 내용은 말줄임표로 표시됩니다. ```tsx "use client"; import { Badge } from "seed-design/ui/badge"; export default function BadgeTruncating() { return ( In velit velit deserunt amet veniam incididunt consectetur incididunt Lorem. ); } ``` ### Tones and Variants #### Neutral ```tsx "use client"; import { HStack, VStack } from "@seed-design/react"; import { Badge } from "seed-design/ui/badge"; export default function BadgeNeutral() { return ( 라벨 라벨 라벨 라벨 라벨 라벨 ); } ``` #### Brand ```tsx "use client"; import { HStack, VStack } from "@seed-design/react"; import { Badge } from "seed-design/ui/badge"; export default function BadgeBrand() { return ( 라벨 라벨 라벨 라벨 라벨 라벨 ); } ``` #### Informative ```tsx "use client"; import { HStack, VStack } from "@seed-design/react"; import { Badge } from "seed-design/ui/badge"; export default function BadgeInformative() { return ( 라벨 라벨 라벨 라벨 라벨 라벨 ); } ``` #### Positive ```tsx "use client"; import { HStack, VStack } from "@seed-design/react"; import { Badge } from "seed-design/ui/badge"; export default function BadgePositive() { return ( 라벨 라벨 라벨 라벨 라벨 라벨 ); } ``` #### Warning ```tsx "use client"; import { HStack, VStack } from "@seed-design/react"; import { Badge } from "seed-design/ui/badge"; export default function BadgeWarning() { return ( 라벨 라벨 라벨 라벨 라벨 라벨 ); } ``` #### Critical ```tsx "use client"; import { HStack, VStack } from "@seed-design/react"; import { Badge } from "seed-design/ui/badge"; export default function BadgeCritical() { return ( 라벨 라벨 라벨 라벨 라벨 라벨 ); } ``` --- file: components/bottom-sheet.mdx # Bottom Sheet 화면 하단에서 올라오는 모달 컴포넌트입니다. 추가 정보나 액션 목록을 제공하면서도 현재 컨텍스트를 유지할 때 사용됩니다. 사용 가능 버전: @seed-design/react@0.0.1, @seed-design/css@0.0.1 ## Preview ```tsx import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const BottomSheetPreview = () => { return ( Open {/* If you need to omit padding, pass px={0}. */} Content 확인 ); }; export default BottomSheetPreview; ``` Stackflow와 Bottom Sheet를 함께 사용하는 방법에 대해 알아보세요. ## Installation - npm: npx @seed-design/cli@latest add ui:bottom-sheet - pnpm: pnpm dlx @seed-design/cli@latest add ui:bottom-sheet - yarn: yarn dlx @seed-design/cli@latest add ui:bottom-sheet - bun: bun x @seed-design/cli@latest add ui:bottom-sheet ## Props ### `BottomSheetRoot` ### `BottomSheetTrigger` ### `BottomSheetContent` ### `BottomSheetBody` ### `BottomSheetFooter` ## Examples ### Trigger ``는 `asChild` 패턴을 사용해 자식 요소가 BottomSheet를 열 수 있도록 합니다. ``는 `aria-haspopup="dialog"` 속성을 설정하고, `BottomSheet`의 `open` 상태에 따라 `aria-expanded` 속성을 자동으로 설정합니다. 이 속성은 스크린 리더와 같은 보조 기술에 유용합니다. ```tsx import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const BottomSheetTriggerExample = () => { return ( Open Content 확인 ); }; export default BottomSheetTriggerExample; ``` ### Controlled Trigger 외의 방식으로 BottomSheet를 열고 닫을 수 있습니다. 이 경우 `open` prop을 사용하여 BottomSheet의 상태를 제어합니다. ```tsx import { useState } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, } from "seed-design/ui/bottom-sheet"; const BottomSheetControlled = () => { const [open, setOpen] = useState(false); const scheduleOpen = () => { setTimeout(() => { setOpen(true); }, 1000); }; return ( <> 1초 후 열기 {/* If you need to omit padding, pass px={0}. */} Content 확인 ); }; export default BottomSheetControlled; ``` ### `onOpenChange` Details `onOpenChange` 두 번째 인자로 `details`가 제공됩니다. #### `reason` **열릴 때** (`open: true`) - `"trigger"`: `BottomSheetTrigger` (`BottomSheet.Trigger`)로 열림 **닫힐 때** (`open: false`) - `"closeButton"`: `BottomSheet.CloseButton`으로 닫힘 - `"escapeKeyDown"`: ESC 키 사용 - `"interactOutside"`: 외부 영역 클릭 - `"drag"`: 드래그로 닫힘 - `"handleClickOnLastSnapPoint"`: 마지막 스냅 포인트에서 핸들 클릭으로 닫힘 ```tsx import { HStack, Text, VStack } from "@seed-design/react"; import { useState } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const snapPoints = ["200px", "400px", 1]; export default function BottomSheetOnOpenChangeReason() { const [open, setOpen] = useState(false); const [snap, setSnap] = useState(snapPoints[0]); const [openReason, setOpenReason] = useState(null); const [closeReason, setCloseReason] = useState(null); return ( { setOpen(open); (open ? setOpenReason : setCloseReason)(details?.reason ?? null); }} snapPoints={snapPoints} activeSnapPoint={snap} setActiveSnapPoint={setSnap} > 열기 ESC 키를 누르거나, 외부 영역을 클릭하거나, 아래로 스와이프하거나, 핸들을 탭하여 snap point를 순환해보세요. 마지막 열림 이유: {openReason ?? "-"} 마지막 닫힘 이유: {closeReason ?? "-"} ); } ``` ### Header Align ``에 `headerAlign` prop을 설정하여 title과 description의 정렬을 설정할 수 있습니다. ```tsx import { HStack } from "@seed-design/react"; import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const BottomSheetHeaderAlign = () => { return ( Left (기본값) Content 확인 Center Content 확인 ); }; export default BottomSheetHeaderAlign; ``` ### Max Height ``에 `maxHeight` prop을 전달하여 BottomSheet의 최대 높이를 설정할 수 있습니다. ```tsx import { Box, VStack } from "@seed-design/react"; import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const BottomSheetMaxHeight = () => { return ( Open {/* If you need to omit padding, pass px={0}. */} 확인 ); }; export default BottomSheetMaxHeight; ``` ### Snap Points `snapPoints` prop을 사용하여 BottomSheet의 커스텀 스냅 포인트를 설정할 수 있습니다. ```tsx import { useState } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const snapPoints = ["300px", "500px", 1]; const BottomSheetSnapPoints = () => { const [snap, setSnap] = useState(snapPoints[0]); return ( Open Content 확인 ); }; export default BottomSheetSnapPoints; ``` ### Fade From Index ``에 `fadeFromIndex` prop을 전달하여 뒷 배경이 어두워지는 시작 인덱스를 설정할 수 있습니다. ```tsx import { useState } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const snapPoints = ["300px", "500px", 1]; const BottomSheetFadeFromIndex = () => { const [snap, setSnap] = useState(snapPoints[0]); return ( Open Content 확인 ); }; export default BottomSheetFadeFromIndex; ``` ### Show Handle ``에 `showHandle` prop을 전달하여 Handle을 표시할 수 있습니다. 기본 값은 `false`입니다. ```tsx import { useState } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const BottomSheetShowHandle = () => { const [isSheetOpen, setIsSheetOpen] = useState(false); return ( Open {/* If you need to omit padding, pass px={0}. */} Content setIsSheetOpen(false)}> 닫기 ); }; export default BottomSheetShowHandle; ``` ### Show Close Button ``에 `showCloseButton` prop을 전달하여 닫기 버튼을 표시할 수 있습니다. 기본 값은 `true`입니다. showCloseButton을 `false`로 설정하면 닫기 버튼이 표시되지 않습니다. 이 경우 유저가 BottomSheet를 닫을 수 있는 방법을 제공해야 합니다. ```tsx import { useState } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const BottomSheetShowCloseButton = () => { const [isSheetOpen, setIsSheetOpen] = useState(false); return ( Open {/* If you need to omit padding, pass px={0}. */} Content setIsSheetOpen(false)}> 닫기 ); }; export default BottomSheetShowCloseButton; ``` ### Dismissible `dismissible` prop을 `false`로 설정하면 closeOnEscape, closeOnInteractOutside, draggable 기능이 비활성화됩니다. 의도적으로 BottomSheet를 닫을 수 없게 하고 싶을 때 사용합니다. 이외에는 유저가 BottomSheet를 닫을 수 있는 방법을 제공해야 합니다. ```tsx import { useState } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const BottomSheetDismissible = () => { const [open, setOpen] = useState(false); return ( Open {/* If you need to omit padding, pass px={0}. */} Content setOpen(false)}> 닫기 ); }; export default BottomSheetDismissible; ``` ### With Scroll Fog ``에 [Scroll Fog](/react/components/scroll-fog)를 사용하여 스크롤 힌트 효과를 적용할 수 있습니다. ScrollFog는 항상 효과를 표시하므로, 충분한 padding을 제공해야 합니다. 권장 padding인 하단 `80px`, 상단 `20px`을 유지해야 합니다. ```tsx import { Box, ScrollFog, VStack } from "@seed-design/react"; import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const BottomSheetMaxHeight = () => { return ( Open {/* If you need to omit padding, pass px={0}. */} 확인 ); }; export default BottomSheetMaxHeight; ``` ### Handle Only ``에 `handleOnly` prop을 제공하는 경우 쓸어서(swipe) Bottom Sheet를 움직일 수 있는 영역이 핸들 부분으로 제한됩니다. 이 옵션은 ``와 함께 사용할 때만 작동합니다. ```tsx import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const BottomSheetHandleOnly = () => { return ( Open Content 확인 ); }; export default BottomSheetHandleOnly; ``` ### Skip Animation `skipAnimation` prop을 사용하여 BottomSheet의 enter/exit 애니메이션을 건너뛸 수 있습니다. ```tsx import { ActionButton } from "seed-design/ui/action-button"; import { BottomSheetBody, BottomSheetContent, BottomSheetFooter, BottomSheetRoot, BottomSheetTrigger, } from "seed-design/ui/bottom-sheet"; const BottomSheetSkipAnimation = () => { return ( Open Content 확인 ); }; export default BottomSheetSkipAnimation; ``` --- file: components/callout.mdx # Callout 사용자에게 중요한 정보나 팁을 시각적으로 강조하여 전달하는 메시지 컴포넌트입니다. 사용 가능 버전: @seed-design/react@0.0.1, @seed-design/css@0.0.1 ## Preview ```tsx import { VStack } from "@seed-design/react"; import { ActionableCallout, Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutPreview() { return ( ); } ``` ## 설치 - npm: npx @seed-design/cli@latest add ui:callout - pnpm: pnpm dlx @seed-design/cli@latest add ui:callout - yarn: yarn dlx @seed-design/cli@latest add ui:callout - bun: bun x @seed-design/cli@latest add ui:callout ## 속성 ### `Callout` ### `ActionableCallout` ### `DismissibleCallout` ## 예시 ### 콘텐츠 구성 #### 텍스트만 ```tsx import { VStack } from "@seed-design/react"; import { ActionableCallout, Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutTextOnly() { return ( ); } ``` #### 아이콘 포함 ```tsx import { IconCalendarFill } from "@karrotmarket/react-monochrome-icon"; import { VStack } from "@seed-design/react"; import { ActionableCallout, Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutWithIcon() { return ( } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> ); } ``` #### 제목 텍스트 포함 ```tsx import { VStack } from "@seed-design/react"; import { ActionableCallout, Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutWithTitleText() { return ( ); } ``` #### 링크 레이블 포함 `ActionableCallout`에서는 `linkProps`를 제공하지 않아요. ```tsx import { VStack } from "@seed-design/react"; import { Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutWithLinkLabel() { return ( ); } ``` #### 모든 요소 포함 ```tsx import { IconCalendarFill } from "@karrotmarket/react-monochrome-icon"; import { VStack } from "@seed-design/react"; import { Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutWithAll() { return ( } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." linkProps={{ children: "시도해 보기" }} /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." linkProps={{ children: "시도해 보기" }} /> ); } ``` ### 커스터마이징 가능한 요소 #### 링크 레이블을 자식 요소로 렌더링 ```tsx import { VStack } from "@seed-design/react"; import { Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutLinkLabelAsChild() { return ( 시도해 보기 ), }} /> 시도해 보기 ), }} /> ); } ``` ### 톤 #### 중립 (기본값) ```tsx import { IconCalendarFill } from "@karrotmarket/react-monochrome-icon"; import { VStack } from "@seed-design/react"; import { ActionableCallout, Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutNeutral() { return ( } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> ); } ``` #### 정보 ```tsx import { IconCalendarFill } from "@karrotmarket/react-monochrome-icon"; import { VStack } from "@seed-design/react"; import { ActionableCallout, Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutInformative() { return ( } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> ); } ``` #### 긍정 ```tsx import { IconCalendarFill } from "@karrotmarket/react-monochrome-icon"; import { VStack } from "@seed-design/react"; import { ActionableCallout, Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutPositive() { return ( } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> ); } ``` #### 경고 ```tsx import { IconCalendarFill } from "@karrotmarket/react-monochrome-icon"; import { VStack } from "@seed-design/react"; import { ActionableCallout, Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutWarning() { return ( } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> ); } ``` #### 위험 ```tsx import { IconCalendarFill } from "@karrotmarket/react-monochrome-icon"; import { VStack } from "@seed-design/react"; import { ActionableCallout, Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutCritical() { return ( } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> } description="기능에 대한 안내 또는 유익한 내용을 전달해요. 콜아웃은 꼭 필요한 경우에만 절제하여 사용해요." /> ); } ``` #### 매직 ```tsx import { IconSparkle2 } from "@karrotmarket/react-multicolor-icon"; import { VStack } from "@seed-design/react"; import { ActionableCallout, Callout, DismissibleCallout } from "seed-design/ui/callout"; export default function CalloutMagic() { return ( } /> } /> } /> ); } ``` --- file: components/checkbox.mdx # Checkbox 사용자가 하나 이상의 옵션을 선택할 수 있게 해주는 컴포넌트입니다. 목록에서 여러 항목을 선택하거나 약관 동의와 같은 선택적 작업에 사용됩니다. 사용 가능 버전: @seed-design/react@0.0.1, @seed-design/css@0.0.1 ## Preview ```tsx import { VStack } from "@seed-design/react"; import { Checkbox, CheckboxGroup } from "seed-design/ui/checkbox"; export default function CheckboxPreview() { return ( ); } ``` ## Installation - npm: npx @seed-design/cli@latest add ui:checkbox - pnpm: pnpm dlx @seed-design/cli@latest add ui:checkbox - yarn: yarn dlx @seed-design/cli@latest add ui:checkbox - bun: bun x @seed-design/cli@latest add ui:checkbox ## Props ### `CheckboxGroup` ### `Checkbox` ### `Checkmark` ## Examples ### Sizes ```tsx import { HStack } from "@seed-design/react"; import { Checkbox, CheckboxGroup } from "seed-design/ui/checkbox"; export default function CheckboxSize() { return ( ); } ``` ### Tones and Variants #### Brand ```tsx import { VStack } from "@seed-design/react"; import { Checkbox, CheckboxGroup } from "seed-design/ui/checkbox"; export default function CheckboxBrand() { return ( ); } ``` #### Neutral ```tsx import { VStack } from "@seed-design/react"; import { Checkbox, CheckboxGroup } from "seed-design/ui/checkbox"; export default function CheckboxNeutral() { return ( ); } ``` ### Indeterminate ```tsx import { VStack } from "@seed-design/react"; import { Checkbox } from "seed-design/ui/checkbox"; export default function CheckboxIndeterminate() { return ( ); } ``` ### Weights `weight="default"`와 `weight="stronger"`는 더 이상 사용되지 않습니다. 대신 `weight="regular"`와 `weight="bold"`를 사용하세요. ```tsx import { VStack } from "@seed-design/react"; import { Checkbox, CheckboxGroup } from "seed-design/ui/checkbox"; export default function CheckboxWeights() { return ( ); } ``` ### Long Label ```tsx import { VStack } from "@seed-design/react"; import { Checkbox, CheckboxGroup } from "seed-design/ui/checkbox"; export default function CheckboxLongLabel() { return ( ); } ``` ### Disabled ```tsx import { VStack } from "@seed-design/react"; import { Checkbox, CheckboxGroup } from "seed-design/ui/checkbox"; export default function CheckboxDisabled() { return ( ); } ``` ### Listening to Value Changes `onCheckedChange`를 사용하여 체크박스의 선택 상태 변경을 감지할 수 있습니다. 이벤트를 활용해야 하는 경우 `inputProps`를 통해 내부 `` 요소에 직접 이벤트 핸들러를 추가할 수 있습니다. ```tsx import { VStack, Text } from "@seed-design/react"; import { Checkbox } from "seed-design/ui/checkbox"; import { useState } from "react"; export default function CheckboxValueChanges() { const [count, setCount] = useState(0); const [lastValue, setLastValue] = useState(null); return ( { setCount((prev) => prev + 1); setLastValue(checked); }} /> onCheckedChange called: {count} times, last value: {`${lastValue ?? "-"}`} ); } ``` ### Use Cases #### React Hook Form ```tsx import { HStack, VStack } from "@seed-design/react"; import { useCallback, type FormEvent } from "react"; import { useController, useForm, type Control } from "react-hook-form"; import { ActionButton } from "seed-design/ui/action-button"; import { Checkbox, CheckboxGroup } from "seed-design/ui/checkbox"; const POSSIBLE_FRUIT_VALUES = ["apple", "melon", "mango"] as const; type FormValues = Record<(typeof POSSIBLE_FRUIT_VALUES)[number], boolean>; export default function CheckboxReactHookForm() { const { handleSubmit, reset, setValue, control } = useForm({ defaultValues: { apple: false, melon: true, mango: false, }, }); const onValid = useCallback((data: FormValues) => { window.alert(JSON.stringify(data, null, 2)); }, []); const onReset = useCallback( (event: FormEvent) => { event.preventDefault(); reset(); }, [reset], ); return ( {POSSIBLE_FRUIT_VALUES.map((name) => ( ))} 초기화 setValue("mango", true)} > mango 선택 제출 ); } interface CheckboxItemProps { name: keyof FormValues; control: Control; } function CheckboxItem({ name, control }: CheckboxItemProps) { const { field: { value, ...restProps }, fieldState: { invalid }, } = useController({ name, control }); return ( ); } ``` #### Using `Checkmark` `Checkmark`는 독립적인 체크 마크 컴포넌트로, Checkbox Primitive 컴포넌트와 조합하여 커스텀 레이아웃을 위해 사용할 수 있습니다. ```tsx import { HStack, Text, VStack, Checkbox } from "@seed-design/react"; import { Checkmark } from "seed-design/ui/checkbox"; function CustomCheckbox({ children, ...props }: Checkbox.RootPrimitiveProps) { return ( {children} ); } export default function CheckboxCheckmark() { return ( regular medium bold ); } ``` ### Fieldset Integration `CheckboxGroup`을 사용하여 여러 체크박스를 그룹화하고 `label`, `description`, `errorMessage` 등의 Fieldset 관련 prop을 사용할 수 있습니다. ```tsx import { ActionButton, HStack, VStack } from "@seed-design/react"; import { useState } from "react"; import { Checkbox, CheckboxGroup } from "seed-design/ui/checkbox"; export default function CheckboxFieldset() { const [firstErrors, setFirstErrors] = useState>({}); const [secondErrors, setSecondErrors] = useState>({}); const handleFirstSubmit = (e: React.FormEvent) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const fruits = formData.getAll("fruit"); if (fruits.includes("apple")) { setFirstErrors({ apple: "Apple은 선택할 수 없습니다." }); return; } setFirstErrors({}); alert(JSON.stringify(fruits, null, 2)); }; const handleSecondSubmit = (e: React.FormEvent) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const agreements = formData.getAll("agreement"); const hasTerms = agreements.includes("terms"); const hasPrivacy = agreements.includes("privacy"); if (!hasTerms || !hasPrivacy) { setSecondErrors({ ...(!hasTerms && { terms: "필수 항목에 동의해 주세요." }), ...(!hasPrivacy && { privacy: "필수 항목에 동의해 주세요." }), }); return; } setSecondErrors({}); alert(JSON.stringify(agreements, null, 2)); }; return ( ); } ``` ## Scale Feedback `Checkbox`는 눌렸을 때 `Checkmark`가 살짝 줄어드는 피드백을 제공합니다. `Checkmark`를 감싸는 요소에 [Scale Feedback](/react/components/concepts/scale-feedback)을 직접 적용하는 경우, 바깥 요소와 `Checkmark`가 함께 줄어들어 축소가 이중으로 나타납니다. `Checkmark`의 상위 요소에서 `--seed-checkmark-feedback-scale`을 `1`로 설정하면 `Checkmark`의 축소만 끌 수 있습니다. 이 변수는 상속되므로 `Checkbox` 전체를 감싸는 요소에 설정해도 됩니다. ```css title="MyRow.css" .my-row { --seed-checkmark-feedback-scale: 1; } ``` --- file: components/chip-tabs.mdx # Chip Tabs Chip 형태로 표현된 탭 컴포넌트입니다. 카테고리나 필터를 선택하여 콘텐츠를 전환할 때 사용됩니다. 사용 가능 버전: @seed-design/react@0.0.1, @seed-design/css@0.0.1 ## Preview ```tsx import { ChipTabsContent, ChipTabsList, ChipTabsRoot, ChipTabsTrigger, } from "seed-design/ui/chip-tabs"; export default function ChipTabsPreview() { return (

라벨1 라벨2 라벨3 Content 1 Content 2 Content 3