@ceed/ads 1.23.2 → 1.23.4

package/dist/components/data-display/Badge.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-Badge 컴포넌트는 다른 UI 요소 위에 작은 카운트, 상태, 또는 레이블을 표시하는 데 사용됩니다. 주로 알림 수, 상태 표시기, 또는 새로운 콘텐츠를 나타내는 데 활용됩니다.
+Badge is a small visual indicator that overlays another UI element to display a count, status, or label. It is commonly used to show unread notification counts, online/offline status indicators, and "NEW" labels on menu items or navigation elements. The Badge wraps a child component (such as an icon button or avatar) and positions itself in the top-right corner by default.
+
+Badge supports multiple colors, variants, and sizes for flexible visual customization. It also provides utility features like a `max` prop for truncating large numbers (e.g., "99+"), a `showZero` prop for controlling zero-count visibility, and a dot-only mode when no `badgeContent` is provided.
 
 ```tsx
 <Badge {...args}>
@@ -26,7 +28,7 @@ Badge 컴포넌트는 다른 UI 요소 위에 작은 카운트, 상태, 또는
 
 ```tsx
 import { Badge, IconButton } from '@ceed/ads';
-import { NotificationsIcon } from '@mui/icons-material';
+import NotificationsIcon from '@mui/icons-material/Notifications';
 
 function MyComponent() {
   return (
@@ -39,11 +41,9 @@ function MyComponent() {
 }
 ```
 
-## Examples
-
-### Basic Usage
+## Basic
 
-기본적인 Badge 사용법입니다.
+Basic Badge usage showing numeric counts, max overflow, and text content.
 
 ```tsx
 <div style={{
@@ -70,9 +70,9 @@ function MyComponent() {
 </div>
 ```
 
-### Colors
+## Colors
 
-다양한 색상을 적용할 수 있습니다.
+Apply semantic colors to convey the badge's meaning: `primary` for general counts, `danger` for urgent notifications, `success` for online status, and `warning` for attention items.
 
 ```tsx
 <div style={{
@@ -111,9 +111,9 @@ function MyComponent() {
 </div>
 ```
 
-### Variants
+## Variants
 
-다양한 스타일 변형을 제공합니다.
+Four style variants are available: `solid` (filled), `soft` (subtle background), `outlined` (border only), and `plain` (minimal).
 
 ```tsx
 <div style={{
@@ -146,9 +146,9 @@ function MyComponent() {
 </div>
 ```
 
-### Sizes
+## Sizes
 
-크기를 조절할 수 있습니다.
+Three sizes -- `sm`, `md`, and `lg` -- allow the badge to scale proportionally with its wrapped element.
 
 ```tsx
 <div style={{
@@ -176,9 +176,9 @@ function MyComponent() {
 </div>
 ```
 
-### With Avatar
+## With Avatar
 
-아바타와 함께 사용할 수 있습니다.
+Badge pairs naturally with Avatar to indicate user status (e.g., notification count or online indicator).
 
 ```tsx
 <div style={{
@@ -195,9 +195,9 @@ function MyComponent() {
 </div>
 ```
 
-### Dot Badge
+## Dot Badge
 
-내용 없이 점으로만 표시할 수 있습니다.
+When no `badgeContent` is provided, Badge renders as a small dot. This is useful for simple presence or status indicators without a specific count.
 
 ```tsx
 <div style={{
@@ -216,9 +216,9 @@ function MyComponent() {
 </div>
 ```
 
-### Max Count
+## Max Count
 
-최대 카운트를 설정하여 숫자가 넘을 때 '+' 표시를 할 수 있습니다.
+Use the `max` prop to cap the displayed number. When `badgeContent` exceeds `max`, it renders as "max+" (e.g., "99+").
 
 ```tsx
 <div style={{
@@ -245,9 +245,9 @@ function MyComponent() {
 </div>
 ```
 
-### Show Zero
+## Show Zero
 
-기본적으로 0일 때는 숨겨지지만, showZero 옵션으로 표시할 수 있습니다.
+By default, Badge hides when `badgeContent` is `0`. Use the `showZero` prop to force it to remain visible.
 
 ```tsx
 <div style={{
@@ -276,40 +276,72 @@ function MyComponent() {
 
 ## Common Use Cases
 
-### Notification Count
+### Notification Bell
 
 ```tsx
-<Badge badgeContent={unreadCount} color="danger">
-  <IconButton>
-    <NotificationsIcon />
-  </IconButton>
-</Badge>
+import { Badge, IconButton } from '@ceed/ads';
+import NotificationsIcon from '@mui/icons-material/Notifications';
+
+function NotificationBell({ unreadCount }) {
+  return (
+    <Badge badgeContent={unreadCount} max={99} color="danger">
+      <IconButton aria-label={`${unreadCount} unread notifications`}>
+        <NotificationsIcon />
+      </IconButton>
+    </Badge>
+  );
+}
 ```
 
-### Status Indicator
+### Online Status on Avatar
 
 ```tsx
-<Badge color="success" variant="solid">
-  <Avatar src="/user-avatar.jpg" />
-</Badge>
+import { Badge, Avatar } from '@ceed/ads';
+
+function UserAvatar({ name, avatarUrl, isOnline }) {
+  return (
+    <Badge
+      color={isOnline ? 'success' : 'neutral'}
+      variant="solid"
+      anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+    >
+      <Avatar src={avatarUrl} alt={name} />
+    </Badge>
+  );
+}
 ```
 
-### New Items
+### New Feature Label
 
 ```tsx
-<Badge badgeContent="NEW" color="warning">
-  <Button>메뉴</Button>
-</Badge>
+import { Badge, Button } from '@ceed/ads';
+
+function FeatureButton() {
+  return (
+    <Badge badgeContent="NEW" color="warning" size="sm">
+      <Button variant="outlined">Analytics</Button>
+    </Badge>
+  );
+}
 ```
 
 ## Best Practices
 
-1. **의미 있는 색상**: 색상은 의미를 가지도록 사용하세요 (빨간색은 중요한 알림, 초록색은 성공 상태 등).
+- **Use semantic colors consistently.** Reserve `danger` for urgent notifications, `success` for positive status (e.g., online), `warning` for attention-needed items, and `primary` for neutral counts.
+  - ✔ `color="danger"` for unread message count
+  - ✘ `color="primary"` for critical alert count
+
+- **Set a `max` value for numeric badges.** Avoid displaying very large numbers like "1,247" in a tiny badge. Use `max={99}` or `max={999}` to keep the badge compact and readable.
+
+- **Keep badge content short.** Badges work best with numbers (1-3 digits) or very short text ("NEW", "HOT"). Long text will overflow and look broken.
 
-2. **적절한 콘텐츠**: 너무 긴 텍스트는 피하고, 숫자나 짧은 텍스트를 사용하세요.
+- **Use dot badges for binary states.** When the specific count does not matter (e.g., "has unread items" vs. "12 unread items"), use a dot badge by omitting `badgeContent`.
 
-3. **대비**: Badge의 색상이 배경과 충분한 대비를 가지도록 하세요.
+- **Do not badge everything.** Only add badges to elements where the count or status information is genuinely useful. Overuse diminishes their attention-grabbing effect.
 
-4. **접근성**: 시각적 정보만으로 의존하지 않고, 스크린 리더를 위한 적절한 레이블을 제공하세요.
+## Accessibility
 
-5. **일관성**: 애플리케이션 전체에서 Badge 사용 패턴을 일관되게 유지하세요.
+- Badge automatically applies `aria-label` or equivalent attributes so screen readers can announce the badge content alongside the wrapped element.
+- When using Badge on an IconButton, always provide an `aria-label` on the IconButton that includes the badge context (e.g., `aria-label="5 unread notifications"`).
+- Avoid relying solely on color to convey badge meaning. Pair colored badges with icons, text, or positional context so color-blind users can also interpret the status.
+- Dot badges (without `badgeContent`) should have an accessible label on the parent element that describes the status (e.g., "User is online").

package/dist/components/data-display/InfoSign.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-InfoSign 컴포넌트는 사용자에게 추가 정보를 제공하기 위한 툴팁 아이콘입니다. 물음표 아이콘을 클릭하거나 호버할 때 상세한 설명이나 도움말을 표시할 수 있습니다. 폼 필드, 설정 항목, 복잡한 기능에 대한 설명을 제공할 때 유용합니다.
+InfoSign is a compact tooltip-trigger component that displays a small question-mark icon. When users hover over or focus on the icon, a tooltip appears with supplementary information. It is designed to provide contextual help without cluttering the interface -- ideal for explaining form fields, settings options, table column headers, and complex metrics.
+
+The component accepts a `message` prop for the tooltip content and a `placement` prop to control where the tooltip appears relative to the icon. InfoSign keeps the main UI clean while ensuring that detailed guidance is always one interaction away.
 
 ```tsx
 <InfoSign
@@ -22,23 +24,19 @@ import { InfoSign } from '@ceed/ads';
 
 function MyComponent() {
   return (
-    <div>
-      <label>
-        복잡한 설정 항목
-        <InfoSign
-          message="이 설정은 시스템 전체 성능에 영향을 줄 수 있습니다. 변경하기 전에 관리자와 상의하세요."
-        />
-      </label>
-    </div>
+    <label>
+      Complex Setting
+      <InfoSign
+        message="This setting affects overall system performance. Consult an administrator before making changes."
+      />
+    </label>
   );
 }
 ```
 
-## Examples
-
-### Basic Usage
+## Basic
 
-가장 기본적인 InfoSign 사용법입니다.
+The default InfoSign displays a question-mark icon that reveals a tooltip on hover or focus.
 
 ```tsx
 <InfoSign
@@ -52,109 +50,87 @@ function MyComponent() {
 ### Form Field Help
 
 ```tsx
-<FormControl>
-  <FormLabel>
-    비밀번호 복잡도
-    <InfoSign
-      message="비밀번호는 최소 8자 이상이며, 대문자, 소문자, 숫자, 특수문자를 포함해야 합니다."
-      placement="top"
-    />
-  </FormLabel>
-  <Input type="password" />
-</FormControl>
-```
-
-### Settings Explanation
+import { InfoSign } from '@ceed/ads';
+import { FormControl, FormLabel, Input } from '@ceed/ads';
 
-```tsx
-<Stack spacing={2}>
-  <Box>
-    <Typography level="title-sm">
-      자동 저장
-      <InfoSign
-        message="이 기능을 활성화하면 5분마다 자동으로 작업 내용이 저장됩니다."
-        placement="right"
-      />
-    </Typography>
-    <Switch />
-  </Box>
-</Stack>
+function PasswordField() {
+  return (
+    <FormControl>
+      <FormLabel>
+        Password
+        <InfoSign
+          message="Must be at least 8 characters and include uppercase, lowercase, number, and special character."
+          placement="top"
+        />
+      </FormLabel>
+      <Input type="password" />
+    </FormControl>
+  );
+}
 ```
 
-### Complex Data Explanation
+### Table Column Header
 
 ```tsx
-<Card>
-  <CardContent>
-    <Typography level="title-md">
-      처리량 지표
-      <InfoSign
-        message="처리량은 최근 24시간 동안의 평균 요청 수를 나타냅니다. 이 값이 높을수록 시스템이 더 많은 작업을 처리하고 있다는 의미입니다."
-        placement="bottom"
-      />
-    </Typography>
-    <Typography level="h2">1,234 req/min</Typography>
-  </CardContent>
-</Card>
-```
-
-### Table Header Help
+import { InfoSign } from '@ceed/ads';
 
-```tsx
-<Table>
-  <thead>
-    <tr>
-      <th>
-        사용자 ID
-        <InfoSign message="시스템에서 자동 생성된 고유 식별자입니다." />
-      </th>
-      <th>
-        마지막 활동
-        <InfoSign message="사용자가 마지막으로 로그인하거나 활동한 시간입니다." />
-      </th>
-      <th>상태</th>
-    </tr>
-  </thead>
-</Table>
+function TableHeader() {
+  return (
+    <thead>
+      <tr>
+        <th>
+          User ID
+          <InfoSign message="Auto-generated unique identifier assigned by the system." />
+        </th>
+        <th>
+          Last Activity
+          <InfoSign message="The most recent login or action timestamp for this user." />
+        </th>
+        <th>Status</th>
+      </tr>
+    </thead>
+  );
+}
 ```
 
-## Props
-
-### placement
-
-툴팁이 나타나는 위치를 설정할 수 있습니다.
+### Dashboard Metric Explanation
 
 ```tsx
-<InfoSign placement="top" message="위쪽에 표시" />
-<InfoSign placement="bottom" message="아래쪽에 표시" />
-<InfoSign placement="left" message="왼쪽에 표시" />
-<InfoSign placement="right" message="오른쪽에 표시" />
-```
-
-### message
-
-표시할 메시지 내용입니다. 긴 텍스트도 지원합니다.
+import { InfoSign, Typography, Stack } from '@ceed/ads';
 
-```tsx
-<InfoSign
-  message="여러 줄로 된 긴 설명문도 표시할 수 있습니다.\n줄바꿈도 지원되므로 상세한 설명을 제공할 수 있습니다."
-/>
+function MetricCard() {
+  return (
+    <Stack spacing={1}>
+      <Typography level="title-md">
+        Throughput
+        <InfoSign
+          message="Average requests per minute over the last 24 hours. Higher values indicate greater system load."
+          placement="right"
+        />
+      </Typography>
+      <Typography level="h2">1,234 req/min</Typography>
+    </Stack>
+  );
+}
 ```
 
 ## Best Practices
 
-1. **간결한 메시지**: 핵심 정보만 포함하여 사용자가 빠르게 이해할 수 있도록 합니다.
+- **Keep messages concise.** Tooltip messages should be 1-2 sentences that quickly answer "what does this mean?" Avoid paragraphs of text.
+  - ✔ "Maximum file size per upload. Files exceeding this limit will be rejected."
+  - ✘ A multi-paragraph explanation with examples and edge cases
 
-2. **적절한 배치**: 설명하려는 요소 바로 옆에 배치하여 연관성을 명확히 합니다.
+- **Place InfoSign directly adjacent to the element it explains.** Position it immediately after a label or header text so users can easily associate the help icon with the relevant field.
 
-3. **일관된 사용**: 비슷한 성격의 정보에는 일관되게 InfoSign을 사용합니다.
+- **Do not overuse InfoSign.** Adding a help icon to every single field creates visual noise and suggests the interface itself is too confusing. Reserve it for genuinely complex or ambiguous items.
 
-4. **과도한 사용 금지**: 모든 요소에 InfoSign을 붙이면 인터페이스가 복잡해집니다.
+- **Choose placement that avoids overlap.** Use `placement="top"` or `placement="right"` for fields near the bottom of a viewport, and `placement="bottom"` for elements near the top.
 
-## Accessibility
+- **Use InfoSign for supplementary information only.** Critical instructions or warnings should be displayed inline (e.g., with FormHelperText or Alert), not hidden behind a tooltip.
 
-- InfoSign은 키보드 탐색이 가능합니다
-- 스크린 리더가 메시지 내용을 읽을 수 있습니다
-- ARIA 라벨이 자동으로 적용됩니다
+## Accessibility
 
-InfoSign은 사용자에게 필요한 추가 정보를 제공하면서도 인터페이스를 깔끔하게 유지하는 데 도움이 되는 유용한 컴포넌트입니다.
+- InfoSign is keyboard-focusable, allowing users to trigger the tooltip using **Tab** navigation without requiring a mouse.
+- The tooltip content is announced by screen readers when the InfoSign receives focus, thanks to built-in ARIA attributes.
+- The question-mark icon serves as a universally recognized visual cue for "more information," making it intuitive for all users.
+- Ensure that the `message` text provides the same information available through other channels -- do not make the tooltip the only way to learn critical information.