cashdoc-cms-design-system 1.0.0 → 1.0.1

package/dist/components/Switch/Switch.d.ts

@@ -7,5 +7,65 @@ declare const switchVariants: (props?: ({
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export interface SwitchProps extends React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>, VariantProps<typeof switchVariants> {
 }
+/**
+ * 두 가지 상반된 상태(On/Off, 활성/비활성)를 즉각적으로 전환할 때 사용하는 컴포넌트입니다.
+ *
+ * {@link Switch}는 실제 전등 스위치와 같은 직관적인 시각적 모델을 제공하며,
+ * 체크박스보다 더 '즉각적인 반영'의 의미를 가집니다.
+ *
+ * Radix UI의 Switch 컴포넌트를 기반으로 구현되어 접근성과 애니메이션이
+ * 자동으로 처리됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **즉각적 설정 반영**: 클릭 즉시 시스템 설정이 변경되거나 저장되어야 할 때 (예: 다크모드 켜기, 알림 수신 동의)
+ * - **상태 전환**: 특정 기능의 사용 여부를 결정할 때
+ * - **단순 토글**: 복잡한 입력 없이 켜고 끄는 행위만 필요할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **제출 버튼 필요**: 여러 정보를 입력하고 '확인' 버튼을 눌러야 결과가 반영되는 폼 내에서는 `Checkbox`를 사용하세요.
+ * - **다중 선택**: 여러 항목 중 일부를 골라야 할 때도 `Checkbox`가 더 적합합니다.
+ *
+ * ## Layout behavior
+ *
+ * - **Inline Component**: 주변 텍스트나 다른 요소와 자연스럽게 어우러지는 인라인 블록 형태입니다.
+ * - **Thumb Animation**: 클릭 시 스위치의 '손잡이(Thumb)'가 부드럽게 좌우로 이동하며 상태 변화를 시각화합니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **명확한 현재 상태 표시**: 색상 변화(회색 vs 색상)를 통해 켜져 있는지 꺼져 있는지 한눈에 알 수 있게 하세요.
+ * - **레이블과 함께 사용**: 스위치 옆에 무엇을 제어하는지 설명하는 텍스트를 반드시 배치하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **모호한 의미**: 상태 전환 후에 어떤 변화가 생길지 명확하지 않은 경우에는 사용을 지양하세요.
+ * - **긴 대기 시간**: 서버 통신 등으로 인해 상태 반영에 시간이 걸리는 경우, 로딩 인디케이터를 함께 보여주거나 즉시 반응을 우선 처리하세요.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Support**: `Space` 키를 사용하여 상태를 전환할 수 있습니다.
+ * - **Roles**: `role="switch"` 속성을 사용하여 스크린 리더에서 토글 상태를 읽어줍니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 레이블과 함께 사용하는 기본적인 스위치:
+ *
+ * ```tsx
+ * <div className="flex items-center gap-2">
+ *   <Switch id="airplane-mode" />
+ *   <label htmlFor="airplane-mode">비행기 모드</label>
+ * </div>
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Checkbox}, 제출 전까지 상태를 유지해야 하는 경우
+ * - {@link RadioButton}, 여러 선택지 중 하나를 고르는 경우
+ */
 declare const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;
 export { Switch };

package/dist/components/TagInput/TagInput.d.ts

@@ -17,6 +17,102 @@ export interface TagInputProps extends Omit<VariantProps<typeof tagInputContaine
     validateTag?: (tag: string, currentTags: string[]) => boolean | string | undefined;
     className?: string;
     id?: string;
+    labelLayout?: "vertical" | "horizontal";
+    labelWidth?: string;
 }
+/**
+ * 사용자가 텍스트를 입력하여 여러 개의 태그(키워드) 목록을 생성하고 관리할 수 있는 컴포넌트입니다.
+ *
+ * {@link TagInput}은 입력창 내부에 시각적인 태그를 표시하며,
+ * 엔터(Enter) 키를 통해 새로운 태그를 추가하고 'x' 버튼을 눌러 기존 태그를 제거할 수 있습니다.
+ * 주로 게시글의 태그, 검색 필터 조건, 수신자 목록 등을 입력받을 때 사용됩니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **키워드 입력**: 게시글의 해시태그나 카테고리를 입력받을 때
+ * - **다중 항목 수집**: 여러 개의 이메일 주소나 사용자 아이디를 한꺼번에 입력받아야 할 때
+ * - **제한된 개수의 항목 선택**: 최대 N개까지의 조건을 입력받아야 할 때 (`maxTags` 활용)
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **단일 텍스트 입력**: 하나의 값만 필요한 경우 일반 `TextInput`을 사용하세요.
+ * - **미리 정의된 옵션**: 고정된 목록에서만 선택해야 한다면 `Dropdown`이나 `Combobox`가 더 적합합니다.
+ *
+ * ## Layout behavior
+ *
+ * - **Flow Layout**: 태그들은 가로 방향으로 나열되며, 공간이 부족하면 자동으로 다음 줄로 넘어갑니다 (`layout="row"`).
+ * - **Column Layout**: 태그들을 수직으로 쌓고 싶을 경우 `layout="column"` 설정을 사용할 수 있습니다.
+ * - **Constraint**: `maxTags`에 도달하면 추가 입력이 차단되며 시각적으로 안내됩니다.
+ *
+ * 레이블 배치는 `labelLayout` prop으로 제어됩니다:
+ * - **vertical** (기본값): Label이 태그 입력 필드 위에 세로로 배치됩니다.
+ * - **horizontal**: Label과 태그 입력 필드가 가로로 나란히 배치됩니다. `labelWidth`로 Label 너비를 조정할 수 있습니다 (기본값: 120px).
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **유효성 검사 활용**: `validateTag`를 통해 이메일 형식 확인이나 글자 수 제한 등 비즈니스 로직을 적용하세요.
+ * - **중복 방지**: 동일한 태그가 입력되지 않도록 자동으로 처리되지만, 필요에 따라 사용자에게 알림을 줄 수 있습니다.
+ * - **가로 배치 활용**: 폼에서 여러 입력 필드를 정렬할 때는 `labelLayout="horizontal"`을 사용하여 일관된 레이아웃을 유지하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **너무 긴 태그**: 태그 하나에 너무 긴 문장이 들어가는 것은 피하세요. 가급적 단어나 짧은 구문으로 제한하는 것이 좋습니다.
+ * - **복잡한 인터페이스**: 태그 내부에 너무 많은 기능을 넣지 마세요. 태그는 가볍고 빠르게 훑어볼 수 있어야 합니다.
+ *
+ * ## Accessibility
+ *
+ * - **Keyboard Management**: `Enter`로 추가, `Backspace`(구현 예정) 또는 'x' 버튼 클릭으로 삭제가 가능합니다.
+ * - **Screen Reader**: 추가된 각 태그의 내용과 삭제 버튼의 역할을 음성으로 안내합니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본적인 태그 입력 예시:
+ *
+ * ```tsx
+ * <TagInput
+ *   label="게시글 태그"
+ *   maxTags={5}
+ *   placeholder="태그 입력 후 Enter"
+ *   value={['React', 'Next.js']}
+ *   onChange={(tags) => console.log(tags)}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 커스텀 유효성 검사가 포함된 태그 입력:
+ *
+ * ```tsx
+ * <TagInput
+ *   validateTag={(tag) => {
+ *     if (tag.length < 2) return "태그는 2글자 이상이어야 합니다.";
+ *     return true;
+ *   }}
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 가로 배치 레이아웃:
+ *
+ * ```tsx
+ * <TagInput
+ *   label="키워드"
+ *   required={true}
+ *   labelLayout="horizontal"
+ *   labelWidth="150px"
+ *   placeholder="태그 입력 후 Enter"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link TextInput}, 단순 텍스트 입력이 필요한 경우
+ * - {@link Combobox}, 목록에서 검색하여 태그를 추가하고 싶은 경우
+ */
 export declare const TagInput: React.ForwardRefExoticComponent<TagInputProps & React.RefAttributes<HTMLDivElement>>;
 export {};

package/dist/components/Text/Text.d.ts

@@ -10,5 +10,62 @@ export interface TextProps extends React.HTMLAttributes<HTMLElement>, VariantPro
     as?: "p" | "span" | "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "label";
     children: React.ReactNode;
 }
+/**
+ * 일관된 타이포그래피 시스템을 적용하기 위한 텍스트 컴포넌트입니다.
+ *
+ * {@link Text}는 제목(Heading), 본문(Body), 캡션(Caption) 등 미리 정의된 스타일을 제공하여
+ * 디자인 일관성을 유지하고 텍스트의 의미적 구조(Semantic Structure)를 쉽게 정의할 수 있게 합니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **페이지 제목 및 부제목**: 화면의 위계를 나누는 타이틀을 작성할 때
+ * - **본문 콘텐츠**: 일반적인 설명글이나 데이터를 표시할 때
+ * - **캡션 및 힌트**: 부가적인 설명이나 작은 크기의 정보가 필요할 때
+ * - **정형화된 스타일**: 특정 폰트 두께나 크기를 시스템 규칙에 맞춰 적용해야 할 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **복잡한 스타일링**: 시스템 정의 범위를 크게 벗어나는 특수 스타일은 별도 CSS 클래스를 활용하세요.
+ *
+ * ## Layout behavior
+ *
+ * - **Semantic Tag**: `as` prop을 통해 실제 HTML 태그(`h1`, `p`, `span` 등)를 결정할 수 있어 SEO와 접근성에 유리합니다.
+ * - **Alignment**: `align` 속성을 통해 왼쪽, 중앙, 오른쪽 정렬을 손쉽게 조절할 수 있습니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **의미론적 태그 사용**: 제목에는 `as="h1"`, 본문에는 `as="p"`를 사용하는 등 맥락에 맞는 태그를 선택하세요.
+ * - **계층 구조 준수**: 큰 제목(h1) 아래에 작은 제목(h2, h3)이 오도록 논리적인 흐름을 유지하세요.
+ * - **변형(Variant) 활용**: 폰트 크기와 두께를 직접 조절하기보다 제공되는 `variant`를 우선적으로 사용하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **과도한 폰트 크기 사용**: 가급적 시스템에서 정의한 크기를 벗어나지 않도록 주의하세요.
+ * - **의미와 맞지 않는 태그**: 시각적으로만 크게 보이기 위해 제목 태그를 남용하지 마세요.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 다양한 위계의 텍스트 구성:
+ *
+ * ```tsx
+ * <div className="space-y-4">
+ *   <Text variant="h1" as="h1">대시보드</Text>
+ *   <Text variant="subtitle">오늘의 요약 정보입니다.</Text>
+ *   <Text variant="body">
+ *     현재 활성화된 사용자는 총 1,234명이며, 어제 대비 5% 증가했습니다.
+ *   </Text>
+ *   <Text variant="caption" align="right">최근 업데이트: 2024-01-24</Text>
+ * </div>
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link TextInput}, 사용자의 입력을 받는 텍스트 필드
+ * - {@link Button}, 텍스트를 포함하는 액션 요소
+ */
 export declare const Text: React.ForwardRefExoticComponent<TextProps & React.RefAttributes<HTMLElement>>;
 export {};

package/dist/components/TextInput/TextInput.d.ts

@@ -7,10 +7,88 @@ declare const textInputVariants: (props?: ({
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export interface TextInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size">, VariantProps<typeof textInputVariants> {
     label?: string;
+    required?: boolean;
     error?: boolean;
     errorMessage?: string;
     helperText?: string;
     showCharCount?: boolean;
+    labelLayout?: "vertical" | "horizontal";
+    labelWidth?: string;
 }
+/**
+ * 사용자로부터 텍스트, 이메일, 숫자 등의 단일 라인 데이터를 입력받는 필드입니다.
+ *
+ * {@link TextInput}은 가장 기본적인 폼 입력 요소로, label, placeholder, 에러 메시지,
+ * helper 텍스트, 글자 수 카운터 등을 통합적으로 제공합니다. 일관된 스타일과 동작으로
+ * 사용자 경험을 향상시킵니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **단일 라인 텍스트 입력**: 이름, 이메일, 전화번호 등 한 줄로 입력 가능한 정보
+ * - **특정 타입 입력**: email, password, number, date 등 HTML input type을 활용
+ * - **글자 수 제한**: 최대 글자 수를 지정하고 실시간으로 카운터를 표시
+ * - **유효성 검증**: 에러 상태와 메시지를 통해 사용자에게 피드백 제공
+ * - **필수 입력**: `required` 속성을 사용하여 반드시 입력해야 함을 시각적으로 안내
+ *
+ * ## Layout behavior
+ *
+ * TextInput은 기본적으로 부모 요소의 전체 너비(`fullWidth={true}`)를 차지합니다.
+ * `fullWidth={false}`로 설정하면 내용에 맞춰 자동으로 조절됩니다.
+ *
+ * 레이블 배치는 `labelLayout` prop으로 제어됩니다:
+ * - **vertical** (기본값): Label이 입력 필드 위에 세로로 배치됩니다.
+ * - **horizontal**: Label과 입력 필드가 가로로 나란히 배치됩니다. `labelWidth`로 Label 너비를 조정할 수 있습니다 (기본값: 120px).
+ *
+ * 구조는 다음 순서로 배치됩니다:
+ * 1. **헤더 영역** (있는 경우): label (좌측, 필수 시 * 표시) + 글자 수 카운터 (우측)
+ * 2. **입력 필드**: 텍스트 입력 영역
+ * 3. **메시지 영역** (있는 경우): errorMessage 또는 helperText
+ *
+ * 높이는 `h-10` (2.5rem / 40px)로 고정되어 일관된 버튼 높이와 정렬됩니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **명확한 label 제공**: 무엇을 입력해야 하는지 명확하게 표시하세요
+ * - **필수 여부 명시**: 반드시 입력해야 하는 필드라면 `required` 속성을 활성화하세요.
+ * - **가로 배치 활용**: 폼에서 여러 입력 필드를 정렬할 때는 `labelLayout="horizontal"`을 사용하여 일관된 레이아웃을 유지하세요.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 레이블과 필수 표시가 포함된 입력 필드:
+ *
+ * ```tsx
+ * <TextInput
+ *   label="사용자 아이디"
+ *   required={true}
+ *   placeholder="아이디를 입력하세요"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 가로 배치 레이아웃:
+ *
+ * ```tsx
+ * <TextInput
+ *   label="상호(법인명)"
+ *   required={true}
+ *   labelLayout="horizontal"
+ *   labelWidth="150px"
+ *   placeholder="회사명을 입력하세요"
+ * />
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Textarea}, 여러 줄 텍스트 입력을 위한 컴포넌트
+ * - {@link TagInput}, 여러 태그를 입력받는 컴포넌트
+ * - {@link DatePicker}, 날짜 선택을 위한 컴포넌트
+ * - {@link Dropdown}, 옵션 선택을 위한 컴포넌트
+ */
 export declare const TextInput: React.ForwardRefExoticComponent<TextInputProps & React.RefAttributes<HTMLInputElement>>;
 export {};

package/dist/components/Toast/Toaster.d.ts

@@ -2,5 +2,83 @@ import { Toaster as Sonner } from 'sonner';
 import { ComponentProps } from 'react';
 
 type ToasterProps = ComponentProps<typeof Sonner>;
+/**
+ * 사용자의 액션에 대한 가벼운 피드백을 화면 구석에 일시적으로 표시하는 알림 컴포넌트입니다.
+ *
+ * {@link Toaster}는 시스템의 상태 변화(성공, 실패, 경고 등)를 비침습적인 방식으로 알립니다.
+ * `sonner` 라이브러리를 기반으로 하며, CMS 디자인 가이드에 맞춘 스타일링이 적용되어 있습니다.
+ * 어플리케이션 최상위 수준(App.tsx 등)에 한 번만 배치하면 어디서든 `toast()` 함수를 통해 알림을 띄울 수 있습니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **간단한 결과 알림**: "저장되었습니다", "복사 완료" 등 짧은 피드백
+ * - **비파괴적 액션 확인**: 사용자의 흐름을 방해하지 않고 알림만 주고 싶을 때
+ * - **백그라운드 작업 완료**: 서버 요청이 성공적으로 처리되었음을 알릴 때
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **중요한 의사 결정**: 사용자가 반드시 읽고 확인 버튼을 눌러야 하는 내용은 `Modal`을 사용하세요.
+ * - **긴 메시지**: 토스트는 수초 후 사라지므로, 읽는 데 시간이 걸리는 긴 텍스트는 부적절합니다.
+ * - **에러 세부 정보**: 복잡한 에러 로그나 해결 방법이 포함된 에러는 `Modal`이나 전용 에러 페이지에서 보여주세요.
+ *
+ * ## Layout behavior
+ *
+ * - **Floating**: 화면 최상단 레이어에 고정된 위치(기본값: 하단 중앙)에 나타납니다.
+ * - **Stacking**: 여러 개의 토스트가 동시에 발생하면 차례대로 쌓여서 표시됩니다.
+ * - **Auto-dismiss**: 일정 시간(기본 4초)이 지나면 자동으로 사라집니다.
+ *
+ * ## Usage guidelines
+ *
+ * ### ✅ Do (권장 사항)
+ *
+ * - **명확하고 간결하게**: 핵심만 담은 짧은 문장을 사용하세요. (예: "이미지가 업로드되었습니다")
+ * - **적절한 타입 사용**: `toast.success`, `toast.error` 등 상황에 맞는 메서드를 사용하여 색상과 아이콘으로 의미를 전달하세요.
+ *
+ * ### 🚫 Don't (주의/금지 사항)
+ *
+ * - **중요 정보 포함**: 토스트는 금방 사라지므로, 계좌번호나 비밀번호 같은 중요 정보를 여기에만 표시해서는 안 됩니다.
+ * - **과도한 사용**: 짧은 시간에 너무 많은 토스트가 발생하면 사용자에게 스트레스를 줄 수 있습니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 최상위 컴포넌트 설정:
+ *
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <>
+ *       <Router />
+ *       <Toaster />
+ *     </>
+ *   );
+ * }
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 다양한 토스트 호출 방법:
+ *
+ * ```tsx
+ * // 기본
+ * toast("환영합니다!");
+ *
+ * // 성공
+ * toast.success("저장에 성공했습니다.");
+ *
+ * // 에러
+ * toast.error("서버와의 연결이 원활하지 않습니다.");
+ *
+ * // 상세 설명 포함
+ * toast("알림", {
+ *   description: "새로운 메시지가 도착했습니다."
+ * });
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Modal}, 더 중요하거나 명시적 확인이 필요한 알림
+ */
 declare const Toaster: ({ position, ...props }: ToasterProps) => import("react/jsx-runtime").JSX.Element;
 export { Toaster };

package/dist/components/icons/ChevronRightIcon.d.ts

@@ -1,3 +1,14 @@
 import { SVGProps } from 'react';
 
+/**
+ * 오른쪽을 가리키는 쉐브론(V자형) 아이콘 컴포넌트입니다.
+ *
+ * 주로 내비게이션, 아코디언 확장, 또는 리스트 아이템의 상세 페이지 이동을 시각적으로 나타낼 때 사용됩니다.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * <ChevronRightIcon className="w-4 h-4 text-gray-500" />
+ * ```
+ */
 export declare function ChevronRightIcon(props: SVGProps<SVGSVGElement>): import("react/jsx-runtime").JSX.Element;

package/dist/components/index.d.ts

@@ -6,6 +6,7 @@ export * from './Popover';
 export * from './Text';
 export * from './TextInput';
 export * from './DatePicker';
+export * from './DateRangePicker';
 export * from './Switch';
 export * from './RadioButton';
 export * from './SideNavigation';