StatusBanner
먼저 보고, 그다음 계약을 읽습니다
폼/영역 옆에 고정되는 동적 상태 전이 알림 — SR 자동 발화.
Component intent의도와 경계 읽기
저장됨·차단됨·분할 중·에러 같은 *동적* 상태 전이를 inline 한 자리에 알린다. Callout(정적 안내, role="note")과 달리 <output> 루트에 role="status"/"alert" 를 부여해 스크린리더가 자동 발화한다 — error/blocked 는 assertive(alert), 나머지는 polite(status). variant 가 좌측 4px accent bar 색과 기본 아이콘(✓/⊘/⋯/ⓘ/⚠/✕)을 정하고, autoHideMs 로 N ms 후 자동 unmount, dismissible 로 수동 닫기를 켠다. Toast(우상단 floating 스택)와 달리 폼 바로 아래 등 제자리에 머문다.
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
import { StatusBanner } from "@axe/ui";<StatusBanner variant="saved" title="저장됨" autoHideMs={2000} />import { StatusBanner } from "@axe/ui";<StatusBanner variant="error" title="차단됨" description="tail-mass 가 책 P90 을 초과합니다." dismissible onDismiss={clearError}/><output class="axe-status-banner axe-status-banner--error" role="alert"> <span class="axe-status-banner__icon" aria-hidden="true">✕</span> <div class="axe-status-banner__body"> <div class="axe-status-banner__title">차단됨</div> <div class="axe-status-banner__description">tail-mass 가 책 P90 을 초과합니다.</div> </div></output>Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
variant | "saved" | "blocked" | "splitting" | "info" | "success" | "warning" | "error" | 필수 | — | 상태 종류 — 좌측 bar 색·기본 아이콘·발화 강도를 결정. error/blocked 는 assertive(alert), 그 외 polite(status). |
title | React.ReactNode | — | — | 굵은 제목 줄(.axe-status-banner__title). 있을 때만 렌더. HTMLAttributes 의 title 은 이 prop 으로 대체. |
description | React.ReactNode | — | — | 보조 설명(.axe-status-banner__description). 있을 때만 렌더. |
dismissible | boolean | — | — | true 면 우측에 닫기(✕) 버튼을 표시 — 클릭 시 unmount + onDismiss 호출. |
onDismiss | () => void | — | — | 수동 닫기(✕) 클릭 시 호출. |
autoHideMs | number | — | — | 지정 시 N ms 후 자동 unmount(+ onAutoHide). 미지정이면 영구 표시. |
onAutoHide | () => void | — | — | autoHideMs 로 자동 사라질 때 호출. |
children | React.ReactNode | — | — | title/description 아래 body 안에 추가로 렌더(예: 액션 버튼). |
...rest | Omit<React.HTMLAttributes<HTMLOutputElement>, "title"> | — | — | className 병합, 나머지는 루트 <output> 으로 전파. |
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-status-banner | stable | 루트 <output> — flex row·subtle 배경·좌측 4px bar·enter 애니메이션. |
.axe-status-banner__icon | stable | 좌측 아이콘 박스(20px, aria-hidden). variant 색 상속. |
.axe-status-banner__body | stable | 제목+설명+children 컨테이너(flex 1). |
.axe-status-banner__title | stable | 굵은 제목 줄(semibold). |
.axe-status-banner__description | stable | 설명 문단(secondary). |
.axe-status-banner__dismiss | stable | 우측 닫기(✕) 버튼 — focus-visible outline. |
.axe-status-banner--saved | stable | saved 변형 — success bar + success-soft 배경. |
.axe-status-banner--success | stable | success 변형 — success bar + success-soft 배경. |
.axe-status-banner--splitting | stable | splitting 변형 — warning bar + 아이콘 회전(spin). |
.axe-status-banner--warning | stable | warning 변형 — warning bar + warning-soft 배경. |
.axe-status-banner--blocked | stable | blocked 변형 — danger bar + danger-soft 배경. |
.axe-status-banner--error | stable | error 변형 — danger bar + danger-soft 배경. |
.axe-status-banner--info | stable | info 변형 — accent bar + accent-soft 배경. |
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
- dismissible 버튼은 네이티브 <button> — Enter/Space 로 닫기
루트가 <output> 이며 error/blocked 는 role="alert"(암묵적 aria-live="assertive"+atomic), 그 외는 role="status"(암묵적 polite). aria-live 를 명시로 중복 부여하지 않는다(일부 SR 이중 발화 방지). 아이콘은 aria-hidden, 닫기 버튼 aria-label="닫기".
prefers-reduced-motion 시 등장 애니메이션과 splitting 아이콘 회전이 정지. autoHideMs 는 setTimeout 기반이라 언마운트로만 사라지며(가시성 토글 아님), 되돌리려면 재마운트.