피드백
빈 상태(Empty)와 오류 메시지(ErrorText)를 표시하는 컴포넌트입니다. 둘 다 한 문장으로 씁니다.
빈 상태에는 일러스트나 버튼을 넣지 않습니다. 오류는 붉은 틴트 배경 위에 한 줄로 표시하며, 폼에서는 FormField 가 버튼 위에 같은 스타일로 표시합니다. 문구는 합니다체로 씁니다.
- 쓰는 경우
- 목록이나 표에 표시할 항목이 없을 때 Empty 를, 폼 밖에서 작업 실패를 알릴 때 ErrorText 를 씁니다.
- 쓰지 않는 경우
- 폼 제출 오류는 ErrorText 를 따로 두지 않고 FormField 의 error 로 넘깁니다. 빈 상태에 일러스트나 버튼을 넣지 않습니다.
Empty
표시할 항목이 없을 때 목록 자리에 한 문장을 가운데 정렬로 표시합니다.
아직 프로젝트가 없습니다.
ErrorText
오류 메시지 한 줄입니다. children 이 없으면 렌더링하지 않습니다.
이름은 2자 이상이어야 합니다.
(두 번째 ErrorText 는 children 이 없어 렌더링되지 않았습니다.)
Toast
방금 일어난 일을 한 문장으로 알리는 쪽지입니다. 화면에는 한 번에 하나만 서고, 급한 것(오류)이 먼저 섭니다.
읽는 동안(손 올림 · 포커스) · 탭이 숨은 동안에는 시계가 멈춥니다. 기본 시간은 정보 · 성공 6초(되돌리기가 있으면 10초) · 경고 10초 · 오류와 진행은 닫을 때까지입니다. 같은 id 로 다시 부르면 새로 쌓지 않고 바꿉니다. 종류는 색 띠가 아니라 모양이 다른 아이콘과 글자로 말합니다.
- import
- import { ToastRegion, Toast, toast } from "@uyoolabs/ui/feedback";
- 쓰는 경우
- 방금 한 일의 결과(보관 · 공유 · 저장), 되돌릴 수 있는 동작 뒤의 [되돌리기], 화면 밖에서 끝난 일(내보내기 완료 · 업로드 실패)에 씁니다.
- 쓰지 않는 경우
- 읽고 판단해야 하는 긴 내용 · 여러 버튼(대화상자 · 알림 띠), 폼 검증 오류(칸 옆 오류 문장)에는 쓰지 않습니다. 오류를 저절로 사라지게 하지 않고, 되돌릴 수 없는 동작을 되돌리기 토스트로 감추지 않습니다. 동작은 토스트 밖에서도 할 수 있어야 합니다(altText).
| 키 | 동작 |
|---|---|
| F8 | 토스트 영역으로 간다(시계가 멈춘다). 다시 누르면 원래 자리로 |
| Tab·Shift+Tab | 동작 · 닫기 |
| Esc | 포커스된 토스트를 닫는다. F8 로 들어왔으면 원래 자리로 |
| 손 올림 · 포커스 · 숨은 탭 | 시계가 멈춘다. 다시 이어 갈 때 최소 0.8초 |
Alert
카드 · 폼 · 표 바로 위, 그 내용을 쓰는 동안 계속 알아야 하는 사실입니다. 톤 틴트 면 + 모양이 다른 아이콘이고 왼쪽 세로 강조선을 쓰지 않습니다.
- import
- import { Alert, AlertAction, Banner } from "@uyoolabs/ui/ui";
- 쓰는 경우
- 보기 전용 문서, 필터로 숨겨진 항목, 연동 실패, 곧 바뀌는 기본값. 무엇이 문제인지 + 어떻게 고치나 + 동작 하나를 함께 둡니다.
- 쓰지 않는 경우
- 방금 한 동작의 결과(Toast), 지금 답해야 하는 질문(Dialog), 칸 하나의 검증 오류(Field 오류)에는 쓰지 않습니다. 같은 화면에 알림을 셋 이상 두지 않고, 되돌릴 수 있는 일에 빨강 톤을 쓰지 않습니다. 틴트 위에서는 muted 글자와 secondary 버튼을 쓰지 않습니다(대비 미달).
웹훅 3개가 실패하고 있습니다
게스트 2명의 초대가 7일 뒤 만료됩니다
| 키 | 동작 |
|---|---|
| Tab | 안의 동작 · 닫기를 문서 순서로. 알림 자체는 포커스를 받지 않는다 |
| Enter·Space | 동작 · 닫기. 닫으면 포커스가 알림 다음 요소로 간다 |
Banner
워크스페이스 전체에 걸린 상황(결제 실패 · 점검 · 오프라인)을 셸 맨 위 한 줄로 알립니다. 겹치지 않고 내용을 아래로 밉니다.
props
소스의 타입과 JSDoc 에서 생성한 표입니다. 컴포넌트를 고치면 pnpm gen 으로 다시 만듭니다.
ToastRegion
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| position | "bottom-end" | "bottom-center" | "bottom-end" | 640 미만에서는 언제나 아래 가운데(양옆 16) |
| offset | number | string | — | 바닥에서 더 띄울 거리. 작성창 · 입력칸 높이. CSS 길이도 받는다("var(--doc-input-h)") |
| container | HTMLElement | null | — | 포털 대상. 기본 document.body |
| hotkey | string[] | ["F8"] | 영역으로 들어가는 키. 다시 누르면 원래 자리로 돌아간다 |
| lang | "ko" | "en" | "ja" | — | 내장 문구(영역 이름 · 닫기 · 진행률)의 언어 |
| labels | Partial<ToastLabels> | — | 내장 문구 중 바꿀 것 |
| children | ReactNode | — | 선언형 <Toast> 를 여기 둘 수 있다 |
이 밖에 Radix Toast.Viewport props(label · hotkey 제외)를 그대로 받습니다.
Toast · toast(options)
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| id | string | — | 같은 id 로 다시 부르면 새로 쌓지 않고 내용을 바꾼다 |
| tone | "info" | "ok" | "warn" | "bad" | "progress" | — | 종류. 모양이 다른 아이콘과 글자로 말한다(색 띠 없음) |
| title필수 | ReactNode | — | 한 문장, 합니다체("작업 3개를 보관했습니다") |
| description | ReactNode | — | |
| action | { label: string; altText: string; onAction: () => void } | — | 동작은 하나까지. altText 는 토스트 밖에서 같은 일을 하는 길("⌘Z 로 되돌립니다") |
| duration | number | null | — | ms. null 이면 닫을 때까지. 기본: info · ok 6000(action 이 있으면 10000) · warn 10000 · bad · progress null |
| rank | number | — | 작을수록 먼저. 기본 bad 0 · warn 1 · progress 1 · info 2 · ok 2 |
| progress | number | — | tone="progress" 일 때 0–100. 없으면 막대 없이 스피너만 |
| onSeen | () => void | — | 처음 실제로 보인 순간 한 번(차례이고 탭이 보일 때) |
| onDismiss | (reason: ToastDismissReason) => void | — | 닫혔을 때(시간 · 닫기 · 동작) |
| closable | boolean | — | 닫기 버튼. 기본 true, progress 는 false |
| open | boolean | — | |
| defaultOpen | boolean | true | |
| onOpenChange | (open: boolean) => void | — |
Alert
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| tone | "info" | "ok" | "warn" | "bad" | "info" | 기본 "info". 빨강(bad)은 오류와 되돌릴 수 없는 일에만 |
| size | "md" | "sm" | "md" | sm 은 한 줄(표 · 폼 · 편집기 위) |
| title | ReactNode | — | 제목(14/600). 종류를 글자로 말하는 자리다 |
| icon | ReactNode | false | — | 기본은 톤 아이콘(원 i · 원 체크 · 삼각 · 팔각). false 면 없음 |
| actions | ReactNode | — | 주 동작은 <Button variant="primary" size="sm"> 하나, 그 밖은 <AlertAction> |
| onDismiss | () => void | — | 있으면 닫기 버튼을 그린다. 닫힌 상태는 소비자가 든다. 오류는 고칠 때까지 남기고 닫기를 두지 않는다 |
| live | "off" | "polite" | "assertive" | "off" | 라이브 영역. 기본 "off" — 처음부터 있던 알림은 읽는 순서대로 읽힌다. 나중에 나타나는 알림만 "assertive"(role=alert, 오류) · "polite"(role=status) |
| lang | "ko" | "en" | "ja" | — | 내장 문구(닫기)의 언어 |
| labels | Partial<AlertLabels> | — | 내장 문구 중 바꿀 것 |
이 밖에 <div> props(title 제외)를 그대로 받습니다.
AlertAction
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| asChild | boolean | — | 링크면 asChild 로 <a> · 라우터 Link 를 감싼다 |
이 밖에 <button> props를 그대로 받습니다. 기본값을 바꾼 것은 type="button" 입니다.
Banner
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| tone | "info" | "ok" | "warn" | "bad" | "info" | |
| label | string | — | 셸 맨 위 띠의 이름(role=region). 예: "결제 알림". live 가 polite 이면 role=status 가 이긴다 |
| live | "off" | "polite" | "off" | 오프라인 · 재연결은 "polite"(role=status)로 한 번 알린다 |
| busy | boolean | false | 아이콘 대신 스피너(재연결 중) |
| actions | ReactNode | — | 주 동작은 primary sm 하나. 결제 권한이 없는 사람에게는 버튼을 빼고 문장으로 |
| onDismiss | () => void | — | 있으면 닫기 버튼. 결제 실패처럼 고칠 때까지 남는 띠에는 두지 않는다 |
| lang | "ko" | "en" | "ja" | — | 내장 문구(닫기)의 언어 |
| labels | Partial<AlertLabels> | — | 내장 문구 중 바꿀 것 |
| children필수 | ReactNode | — | 한두 문장. 앞부분을 <b> 로. 시각은 UTC 를 받아 보는 사람의 시간대로 쓰고 시간대를 글로 적는다 |
이 밖에 <div> props(title 제외)를 그대로 받습니다.