@ceed/ads 1.13.4 → 1.15.0-next.2

package/dist/Overview.md

@@ -0,0 +1,11 @@
+# ADS (Admin Design System)
+
+ADS는 Admin Design System의 약자로, 컴포넌트 기반의 UI 디자인 시스템입니다. 이 시스템은 일관된 사용자 경험을 제공하고, 개발 및 디자인 프로세스를 효율화하기 위해 제작되었습니다.
+
+이 디자인시스템은 [JoyUI](https://mui.com/joy-ui/getting-started/)를 기반으로 하므로 대부분 [JoyUI](https://mui.com/joy-ui/getting-started/)의 문서를 참고할 수 있지만, 일부 컴포넌트는 추상화 레이어가 추가되어 인터페이스가 다를 수 있습니다.
+
+데이터가 중요한 관리 대시보드와 애플리케이션을 위한 UI를 목적으로 이름이 지어졌으며 내부 서비스 외에도 고객이 사용하는 UI에도 적용될 수 있습니다.
+
+## 문서 및 가이드
+
+ADS에 대한 자세한 내용은 [Design System 문서](https://ecubelabs.atlassian.net/wiki/spaces/HP/pages/3256123430/Design+System)를 참조하세요.

package/dist/components/Menu/Menu.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { MenuProps, MenuItemProps } from '@mui/joy';
+import { MenuProps } from '@mui/joy';
 import { MotionProps } from 'framer-motion';
 /**
  * @todo [v1.0.0] Restructure menu component to:
@@ -17,8 +17,5 @@ declare const Menu: {
     displayName: string;
 };
 export { Menu };
-declare const MenuItem: {
-    (props: MenuItemProps & MotionProps): React.JSX.Element;
-    displayName: string;
-};
+declare const MenuItem: import("@mui/joy").ExtendMenuItem<import("@mui/joy").MenuItemTypeMap<{}, "div">>;
 export { MenuItem };

package/dist/components/Stepper/Stepper.d.ts

@@ -32,6 +32,12 @@ interface StepperProps {
     inactiveColor?: TextColor;
     inactiveLineColor?: TextColor;
     activeStep: number;
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * The orientation of each step. When orientation is set to 'vertical',
+     * stepOrientation is forcibly set to 'horizontal'.
+     */
+    stepOrientation?: 'horizontal' | 'vertical';
 }
 declare function Stepper(props: StepperProps): React.JSX.Element;
 declare namespace Stepper {

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

@@ -0,0 +1,428 @@
+# Avatar
+
+## Introduction
+
+Avatar 컴포넌트는 사용자의 프로필 이미지, 이니셜 또는 아이콘을 표시하는 컴포넌트입니다. Joy UI의 Avatar를 기반으로 하며, 다양한 크기, 색상, 변형을 지원합니다. 사용자 인터페이스에서 개인을 시각적으로 나타내거나 그룹, 브랜드를 표현하는 데 사용됩니다.
+
+```tsx
+<Avatar alt="User avatar" />
+```
+
+| Field    | Description | Default       |
+| -------- | ----------- | ------------- |
+| variant  | —           | —             |
+| color    | —           | —             |
+| size     | —           | —             |
+| src      | —           | —             |
+| alt      | —           | "User avatar" |
+| children | —           | —             |
+
+## Usage
+
+```tsx
+import { Avatar } from '@ceed/ads';
+
+function MyComponent() {
+  return (
+    <div>
+      {/* 이미지가 있는 아바타 */}
+      <Avatar src="/path/to/image.jpg" alt="사용자 이름" />
+
+      {/* 이니셜 아바타 */}
+      <Avatar>김철수</Avatar>
+
+      {/* 단일 문자 아바타 */}
+      <Avatar>김</Avatar>
+    </div>
+  );
+}
+```
+
+## Examples
+
+### Basic Usage
+
+가장 기본적인 Avatar 사용법입니다.
+
+```tsx
+<Avatar alt="User avatar" />
+```
+
+### With Image
+
+이미지를 사용한 아바타입니다.
+
+```tsx
+<Stack direction="row" spacing={2} alignItems="center">
+  <Avatar {...args} />
+</Stack>
+```
+
+### With Text
+
+텍스트나 이니셜을 사용한 아바타입니다.
+
+```tsx
+<Stack direction="row" spacing={2} alignItems="center">
+  <Avatar {...args} />
+</Stack>
+```
+
+## Customization
+
+### Variants
+
+다양한 시각적 스타일을 적용할 수 있습니다.
+
+```tsx
+<Stack direction="row" spacing={2} alignItems="center">
+  {variants.map(variant => <Avatar key={variant} {...args} variant={variant} />)}
+</Stack>
+```
+
+- **solid**: 배경색이 채워진 스타일
+- **soft**: 부드러운 배경색 스타일
+- **outlined**: 테두리만 있는 스타일
+- **plain**: 최소한의 스타일
+
+### Sizes
+
+다양한 크기의 아바타를 사용할 수 있습니다.
+
+```tsx
+<Stack direction="row" spacing={2} alignItems="center">
+  {sizesWithXs.map(size => <Avatar key={size} {...args} size={size}>
+  {getSizeContent(size)}
+</Avatar>)}
+</Stack>
+```
+
+- **xs**: 매우 작은 크기 (16px)
+- **sm**: 작은 크기 (24px)
+- **md**: 중간 크기 (32px, 기본값)
+- **lg**: 큰 크기 (40px)
+
+### Colors
+
+다양한 색상 테마를 적용할 수 있습니다.
+
+```tsx
+<Stack direction="row" spacing={2} alignItems="center">
+  {colors.map(color => <Avatar key={color} {...args} color={color} />)}
+</Stack>
+```
+
+- **primary**: 주요 브랜드 색상
+- **neutral**: 중립적인 회색톤
+- **danger**: 경고나 오류를 나타내는 빨간색
+- **success**: 성공을 나타내는 녹색
+- **warning**: 주의를 나타내는 주황색
+
+### All Combinations
+
+모든 변형, 크기, 색상 조합을 확인할 수 있습니다.
+
+```tsx
+<Stack gap={8}>
+  {variants.map(variant => <Stack key={variant} gap={2}>
+  <Typography level="title-md">
+    {variant.slice(0, 1).toLocaleUpperCase()}
+    {variant.slice(1)} Variant
+  </Typography>
+  {colors.map(color => <Stack key={color} direction="row" gap={2} alignItems="center">
+  {sizesWithXs.map(size => <Stack key={size} alignItems="center" gap={1}>
+  <Avatar {...args} size={size} color={color} variant={variant}>
+    {getSizeContent(size)}
+  </Avatar>
+  <Typography level="body-sm">{size}</Typography>
+</Stack>)}
+{/* With image */}
+<Stack alignItems="center" gap={1}>
+  <Avatar {...args} size="md" color={color} variant={variant} />
+  <Typography level="body-sm">image</Typography>
+</Stack>
+</Stack>)}
+</Stack>)}
+</Stack>
+```
+
+## Common Use Cases
+
+### User Profile
+
+사용자 프로필에서 아바타를 사용하는 경우입니다.
+
+```tsx
+<Stack direction="row" spacing={2} alignItems="center">
+  <Avatar
+    src="/user-profile.jpg"
+    alt="김철수"
+    size="lg"
+  />
+  <Stack>
+    <Typography level="title-md">김철수</Typography>
+    <Typography level="body-sm" color="neutral">
+      kim@example.com
+    </Typography>
+  </Stack>
+</Stack>
+```
+
+### Navigation Bar
+
+네비게이션 바에서 현재 사용자를 표시할 때 사용합니다.
+
+```tsx
+<Stack direction="row" spacing={2} alignItems="center" sx={{ ml: 'auto' }}>
+  <Avatar size="sm" variant="soft" color="primary">
+    김
+  </Avatar>
+  <Typography level="body-sm">김철수</Typography>
+  <IconButton variant="plain" size="sm">
+    <ExpandMoreIcon />
+  </IconButton>
+</Stack>
+```
+
+### Comment System
+
+댓글이나 피드에서 사용자를 나타낼 때 사용합니다.
+
+```tsx
+<Stack direction="row" spacing={2}>
+  <Avatar size="md" variant="soft" color="primary">
+    김
+  </Avatar>
+  <Stack flex={1}>
+    <Stack direction="row" spacing={1} alignItems="center">
+      <Typography level="title-sm">김철수</Typography>
+      <Typography level="body-xs" color="neutral">
+        2시간 전
+      </Typography>
+    </Stack>
+    <Typography level="body-md">
+      이것은 사용자의 댓글 내용입니다.
+    </Typography>
+  </Stack>
+</Stack>
+```
+
+### Team Members
+
+팀 구성원 목록을 표시할 때 사용합니다.
+
+```tsx
+<Stack spacing={3}>
+  <Typography level="title-lg">팀 구성원</Typography>
+
+  {teamMembers.map((member) => (
+    <Stack key={member.id} direction="row" spacing={2} alignItems="center">
+      <Avatar
+        src={member.avatar}
+        alt={member.name}
+        size="md"
+        variant="soft"
+        color="primary"
+      >
+        {member.name.charAt(0)}
+      </Avatar>
+      <Stack flex={1}>
+        <Typography level="title-sm">{member.name}</Typography>
+        <Typography level="body-sm" color="neutral">
+          {member.role}
+        </Typography>
+      </Stack>
+      <Chip variant="soft" size="sm" color="success">
+        온라인
+      </Chip>
+    </Stack>
+  ))}
+</Stack>
+```
+
+### Avatar Groups
+
+여러 사용자를 그룹으로 표시할 때 사용합니다.
+
+```tsx
+<Stack direction="row" spacing={-1}>
+  <Avatar size="sm" variant="solid" color="primary">김</Avatar>
+  <Avatar size="sm" variant="solid" color="success">이</Avatar>
+  <Avatar size="sm" variant="solid" color="warning">박</Avatar>
+  <Avatar size="sm" variant="outlined" color="neutral">
+    <Typography level="body-xs">+3</Typography>
+  </Avatar>
+</Stack>
+```
+
+### Status Indicators
+
+사용자 상태를 함께 표시할 때 사용합니다.
+
+```tsx
+<Box sx={{ position: 'relative', display: 'inline-block' }}>
+  <Avatar src="/user-avatar.jpg" alt="사용자" size="lg" />
+  <Box
+    sx={{
+      position: 'absolute',
+      bottom: 0,
+      right: 0,
+      width: 12,
+      height: 12,
+      bgcolor: 'success.500',
+      borderRadius: '50%',
+      border: '2px solid',
+      borderColor: 'background.body',
+    }}
+  />
+</Box>
+```
+
+### Empty State
+
+데이터가 없을 때 플레이스홀더로 사용합니다.
+
+```tsx
+<Stack alignItems="center" spacing={2}>
+  <Avatar size="lg" variant="outlined" color="neutral">
+    <PersonIcon />
+  </Avatar>
+  <Typography level="body-md" color="neutral">
+    프로필 이미지를 업로드하세요
+  </Typography>
+  <Button variant="outlined" size="sm">
+    이미지 선택
+  </Button>
+</Stack>
+```
+
+### List Items
+
+리스트 아이템에서 사용자나 항목을 표현할 때 사용합니다.
+
+```tsx
+<List>
+  {users.map((user) => (
+    <ListItem key={user.id}>
+      <ListItemDecorator>
+        <Avatar src={user.avatar} alt={user.name} size="sm">
+          {user.name.charAt(0)}
+        </Avatar>
+      </ListItemDecorator>
+      <ListItemContent>
+        <Typography level="title-sm">{user.name}</Typography>
+        <Typography level="body-sm" color="neutral">
+          {user.email}
+        </Typography>
+      </ListItemContent>
+    </ListItem>
+  ))}
+</List>
+```
+
+## Image Handling
+
+### Fallback Behavior
+
+이미지 로드가 실패했을 때 자동으로 이니셜이나 아이콘으로 대체됩니다.
+
+```tsx
+<Avatar
+  src="/broken-image-url.jpg"
+  alt="김철수"
+  color="primary"
+  variant="soft"
+>
+  김
+</Avatar>
+```
+
+### Loading States
+
+이미지 로딩 중에는 children이 표시되다가 이미지 로드 완료 후 이미지로 전환됩니다.
+
+```tsx
+<Avatar
+  src="/slow-loading-image.jpg"
+  alt="사용자"
+  color="neutral"
+  variant="soft"
+>
+  <PersonIcon />
+</Avatar>
+```
+
+## Accessibility
+
+Avatar 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
+
+### Image Alt Text
+
+이미지 아바타의 경우 적절한 alt 텍스트를 제공해야 합니다.
+
+```tsx
+<Avatar
+  src="/user-profile.jpg"
+  alt="김철수의 프로필 사진"
+/>
+```
+
+### Semantic Meaning
+
+아바타가 단순히 장식적 목적이 아닌 의미를 가질 때는 적절한 역할을 제공하세요.
+
+```tsx
+<Avatar
+  src="/user-avatar.jpg"
+  alt="현재 사용자"
+  role="img"
+  aria-label="현재 로그인한 사용자의 프로필 이미지"
+/>
+```
+
+### Color Contrast
+
+텍스트 아바타의 경우 충분한 색상 대비를 유지하세요.
+
+```tsx
+// 좋은 대비를 제공하는 색상 조합
+<Avatar variant="solid" color="primary">김</Avatar>
+<Avatar variant="soft" color="neutral">이</Avatar>
+```
+
+## Best Practices
+
+1. **적절한 크기 선택**: 사용 맥락에 맞는 적절한 크기를 선택하세요.
+
+```tsx
+// ✅ 적절한 크기 사용
+<Avatar size="sm">김</Avatar>  // 리스트 아이템에서
+<Avatar size="lg">김</Avatar>  // 프로필 페이지에서
+
+// ❌ 부적절한 크기 사용
+<Avatar size="lg">김</Avatar>  // 네비게이션 바에서 (너무 큼)
+```
+
+2. **일관된 스타일**: 같은 컨텍스트에서는 일관된 변형과 색상을 사용하세요.
+
+3. **이미지 최적화**: 아바타 이미지는 적절한 크기로 최적화하여 사용하세요.
+
+4. **폴백 제공**: 이미지가 없거나 로드 실패 시를 대비해 적절한 폴백을 제공하세요.
+
+```tsx
+<Avatar src={user.avatar} alt={user.name} color="primary" variant="soft">
+  {user.name?.charAt(0) || '?'}
+</Avatar>
+```
+
+5. **의미적 사용**: 아바타가 누구를 나타내는지 명확하게 식별할 수 있어야 합니다.
+
+## Performance Considerations
+
+1. **이미지 최적화**: 아바타 이미지는 작은 크기로 최적화하여 로딩 속도를 향상시키세요.
+
+2. **Lazy Loading**: 많은 아바타가 있는 페이지에서는 지연 로딩을 고려하세요.
+
+3. **캐싱**: 자주 사용되는 아바타 이미지는 적절히 캐싱하세요.
+
+Avatar는 사용자 인터페이스에서 개인을 시각적으로 나타내는 중요한 컴포넌트입니다. 적절한 크기, 색상, 변형을 선택하여 일관되고 접근 가능한 사용자 경험을 제공할 수 있습니다.