@cashdoc/cashdoc-cms-design-system 2.0.2 → 2.2.0

package/dist/src/components/Table/Table.d.ts

@@ -177,13 +177,9 @@ export type TableHeadProps = {
     sortDirection?: "asc" | "desc" | null;
     /** 정렬 클릭 핸들러 */
     onSort?: () => void;
-} & React.ThHTMLAttributes<HTMLTableCellElement>;
-/**
- * 테이블의 헤더 셀을 정의하는 컴포넌트입니다.
- *
- * `<th>` 태그를 렌더링하며, 열의 제목을 표시합니다.
- * 정렬 기능(`sortable`)을 지원하며, 정렬 방향에 따라 아이콘을 표시할 수 있습니다.
- */
+    /** 텍스트 정렬 방식 (default: "left") */
+    align?: "left" | "center" | "right";
+} & Omit<React.ThHTMLAttributes<HTMLTableCellElement>, "align">;
 export declare const TableHead: React.ForwardRefExoticComponent<{
     /** 정렬 가능 여부 */
     sortable?: boolean;
@@ -191,7 +187,9 @@ export declare const TableHead: React.ForwardRefExoticComponent<{
     sortDirection?: "asc" | "desc" | null;
     /** 정렬 클릭 핸들러 */
     onSort?: () => void;
-} & React.ThHTMLAttributes<HTMLTableCellElement> & React.RefAttributes<HTMLTableCellElement>>;
+    /** 텍스트 정렬 방식 (default: "left") */
+    align?: "left" | "center" | "right";
+} & Omit<React.ThHTMLAttributes<HTMLTableCellElement>, "align"> & React.RefAttributes<HTMLTableCellElement>>;
 declare const tableCellVariants: (props?: ({
     align?: "left" | "center" | "right" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;

package/dist/src/components/Tag/Tag.d.ts

@@ -0,0 +1,79 @@
+import { default as React } from 'react';
+import { VariantProps } from 'class-variance-authority';
+import { tagVariants } from './variants';
+
+export type TagColor = NonNullable<VariantProps<typeof tagVariants>["color"]>;
+export type TagSize = NonNullable<VariantProps<typeof tagVariants>["size"]>;
+type TagOwnProps = {
+    /** 태그 색상. 디자인 시스템 팔레트 기반. */
+    color?: TagColor;
+    /** 태그 크기. */
+    size?: TagSize;
+    /** 좌측 아이콘 — 12~14px 권장. */
+    leftIcon?: React.ReactNode;
+    /** 제거 버튼 노출 여부. true이면 우측에 X 버튼이 추가됩니다. */
+    removable?: boolean;
+    /** 제거 버튼 클릭 핸들러. removable과 함께 사용합니다. */
+    onRemove?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    /** 제거 버튼의 aria-label (기본: "제거"). */
+    removeLabel?: string;
+};
+export type TagProps = TagOwnProps & Omit<React.HTMLAttributes<HTMLSpanElement>, "color" | "prefix">;
+/**
+ * 짧은 메타데이터(상태, 분류, 라벨)를 시각적으로 표시하는 컴포넌트입니다.
+ *
+ * {@link Tag}는 비인터랙티브 라벨이 기본이며, `onClick`이 지정되면 자동으로
+ * 키보드 접근 가능한 버튼 의미를 가집니다. `removable={true}`로 우측에 제거
+ * 버튼을 노출할 수 있고, `leftIcon`으로 아이콘 prefix를 받을 수 있습니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * **사용해야 하는 경우:**
+ * - **상태 라벨**: "신규", "완료", "보류" 등 짧은 상태 표시
+ * - **카테고리/태그**: 컨텐츠 분류, 필터 키워드
+ * - **메타 정보**: 사용자 역할, 권한, 그룹 등 컴팩트한 정보 표시
+ *
+ * **사용하지 말아야 하는 경우:**
+ * - **주요 액션**: 클릭이 주요 액션이라면 `Button`을 사용하세요.
+ * - **선택 가능한 옵션**: 다중 선택이 필요하면 `FilterToggleGroup`/`CountFilterChips`를 검토하세요.
+ *
+ * ## Layout behavior
+ *
+ * - `inline-flex` 기반이므로 텍스트 흐름 안에 자연스럽게 배치됩니다.
+ * - 기본 size는 `sm`(h-5)로, table cell이나 list row 내부에 적합합니다.
+ * - `removable`이면 좌측 라벨 우측에 size-3 X 버튼이 붙고, 클릭 시 `onRemove`가 호출됩니다.
+ *
+ * ## Example
+ *
+ * {@tool snippet}
+ * 기본 사용:
+ *
+ * ```tsx
+ * <Tag>대기</Tag>
+ * <Tag color="blue">신규</Tag>
+ * <Tag color="green" size="md">완료</Tag>
+ * ```
+ * {@end-tool}
+ *
+ * {@tool snippet}
+ * 제거 가능한 태그:
+ *
+ * ```tsx
+ * <Tag
+ *   color="red"
+ *   removable
+ *   onRemove={() => removeTag("VIP")}
+ * >
+ *   VIP
+ * </Tag>
+ * ```
+ * {@end-tool}
+ *
+ * See also:
+ *
+ * - {@link Button}, 주요 액션이 필요한 경우
+ * - {@link CountFilterChips}, 카운트가 함께 보이는 선택형 칩
+ * - {@link FilterToggleGroup}, 토글 가능한 필터 그룹
+ */
+export declare const Tag: React.ForwardRefExoticComponent<TagOwnProps & Omit<React.HTMLAttributes<HTMLSpanElement>, "prefix" | "color"> & React.RefAttributes<HTMLSpanElement>>;
+export {};

package/dist/src/components/Tag/index.d.ts

@@ -0,0 +1,2 @@
+export { Tag } from './Tag';
+export type { TagProps, TagColor, TagSize } from './Tag';

package/dist/src/components/Tag/variants.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tag 컴포넌트의 색상/크기 variant 정의.
+ *
+ * 스타일은 subtle(옅은 배경 + 짙은 텍스트) 단일 톤으로 통일합니다.
+ * 색상 팔레트의 명도 차이는 디자인 토큰 자체에서 흡수되며, 각 컬러는
+ * 같은 의미 가중치(label 톤)를 가지도록 매핑됩니다.
+ *
+ * @color gray   - 기본 (중립 라벨)
+ * @color blue   - 정보/신규
+ * @color green  - 성공/완료
+ * @color red    - 위험/오류/강조
+ * @color orange - 주의/경고
+ * @color yellow - 브랜드 강조 (내부적으로 cms-primary 토큰 사용)
+ * @color pink   - 강조 라벨
+ *
+ * @size sm - 컴팩트 (h-5, 11px)
+ * @size md - 일반 (h-6, 12px)
+ */
+export declare const tagVariants: (props?: ({
+    color?: "green" | "blue" | "red" | "gray" | "orange" | "pink" | "yellow" | null | undefined;
+    size?: "sm" | "md" | null | undefined;
+    interactive?: boolean | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;

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

@@ -0,0 +1,85 @@
+import { default as React } from 'react';
+import { VariantProps } from 'class-variance-authority';
+
+/**
+ * Toast 컴포넌트의 톤/intent variant 정의.
+ *
+ * 두 축으로 구성:
+ * - **intent**: 의미 (success / info / warning / error) — 좌측 아이콘 색만 결정
+ * - **theme**: light(기본) / dark — 배경·텍스트 톤 결정
+ *
+ * 두 축은 독립적이므로 `intent="warning" theme="light"` 같은 조합이 자유롭게 가능합니다.
+ */
+declare const toastVariants: (props?: ({
+    theme?: "dark" | "light" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare const intentIcon: {
+    readonly success: React.ForwardRefExoticComponent<Omit<import('..').IconProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly info: React.ForwardRefExoticComponent<Omit<import('..').IconProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly warning: React.ForwardRefExoticComponent<Omit<import('..').IconProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    readonly error: React.ForwardRefExoticComponent<Omit<import('..').IconProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+};
+export type ToastIntent = keyof typeof intentIcon;
+type ToastVariantProps = VariantProps<typeof toastVariants>;
+export type ToastTheme = NonNullable<ToastVariantProps["theme"]>;
+export type ToastProps = {
+    /** intent — 좌측 아이콘 모양/컬러 결정. 생략 시 아이콘 미노출 */
+    intent?: ToastIntent;
+    /** 라이트/다크 톤 (default: "light") */
+    theme?: ToastTheme;
+    /** 헤더 라인 */
+    title: React.ReactNode;
+    /** 보조 설명 */
+    description?: React.ReactNode;
+    /** 우측 X 버튼 핸들러 — 제공 시에만 X 노출 */
+    onClose?: () => void;
+    /** 우측 X 버튼 aria-label (default: "닫기") */
+    closeLabel?: string;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "title">;
+/**
+ * 정적으로 렌더링되는 토스트 카드 컴포넌트입니다.
+ *
+ * 런타임 알림은 {@link Toaster} + `toast()`를 사용하고, 이 컴포넌트는 디자인
+ * 시스템 문서(스토리), 인라인 알림 배너, 또는 sonner의 `toast.custom`과 함께
+ * 정적 마크업이 필요한 곳에서 사용합니다.
+ *
+ * ## When (언제 사용해야 하는가)
+ *
+ * - **디자인 문서**: 다양한 intent/theme을 한 화면에 시각화할 때
+ * - **인라인 배너**: 페이지 본문에 토스트 톤의 메시지가 필요할 때
+ * - **`toast.custom`**: sonner를 통해 띄우되 마크업을 완전 제어하고 싶을 때
+ *
+ * ## Example
+ *
+ * ```tsx
+ * <Toast
+ *   intent="success"
+ *   title="캠페인이 발행되었습니다"
+ *   description="4분 전 · 12,481명에게 알림 전송"
+ *   onClose={() => dismiss()}
+ * />
+ *
+ * <Toast
+ *   intent="warning"
+ *   theme="light"
+ *   title="발송 시간이 야간(22:00 이후)입니다"
+ *   description="예약 시간을 다시 확인해 주세요."
+ *   onClose={() => dismiss()}
+ * />
+ * ```
+ */
+export declare const Toast: React.ForwardRefExoticComponent<{
+    /** intent — 좌측 아이콘 모양/컬러 결정. 생략 시 아이콘 미노출 */
+    intent?: ToastIntent;
+    /** 라이트/다크 톤 (default: "light") */
+    theme?: ToastTheme;
+    /** 헤더 라인 */
+    title: React.ReactNode;
+    /** 보조 설명 */
+    description?: React.ReactNode;
+    /** 우측 X 버튼 핸들러 — 제공 시에만 X 노출 */
+    onClose?: () => void;
+    /** 우측 X 버튼 aria-label (default: "닫기") */
+    closeLabel?: string;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/src/components/Toast/createToast.d.ts

@@ -0,0 +1,38 @@
+import { default as React } from 'react';
+import { ExternalToast } from 'sonner';
+import { ToastTheme } from './Toast';
+
+/**
+ * 정적 {@link Toast} 컴포넌트와 sonner를 연결하는 래퍼.
+ *
+ * sonner의 자체 스타일/아이콘 시스템 대신 디자인 시스템의 `Toast`를
+ * `toast.custom`을 통해 렌더링합니다. 호출 시그니처는 sonner와 유사하지만
+ * `description`/`theme`/`closeButton` 옵션을 디자인 시스템 의도에 맞춰
+ * 좁혔습니다. `action`/`cancel` 등 sonner 고유 슬롯은 현재 미지원입니다.
+ */
+export type ToastInput = {
+    /** 보조 설명 */
+    description?: React.ReactNode;
+    /** 배경 톤 (default: "light") */
+    theme?: ToastTheme;
+    /** 우측 X 닫기 버튼 노출 여부 (default: true) */
+    closeButton?: boolean;
+} & Omit<ExternalToast, "description" | "icon" | "action" | "cancel" | "actionButtonStyle">;
+/**
+ * CCDS 디자인 시스템에 맞춰 sonner를 감싼 toast 함수.
+ *
+ * - `toast(title, opts?)` — intent 없는 plain 토스트
+ * - `toast.success/info/warning/error(title, opts?)` — intent별 컬러 아이콘
+ * - `toast.dismiss(id?)` / `toast.promise(...)` / `toast.custom(...)` — sonner passthrough
+ *
+ * 모든 호출은 내부적으로 `sonner.toast.custom(<Toast />)`을 사용하므로
+ * 디자인 시스템의 `Toast` 마크업이 실제 런타임에서도 그대로 보입니다.
+ */
+export declare const toast: ((title: React.ReactNode, opts?: ToastInput) => string | number) & {
+    success: (title: React.ReactNode, opts?: ToastInput) => string | number;
+    info: (title: React.ReactNode, opts?: ToastInput) => string | number;
+    warning: (title: React.ReactNode, opts?: ToastInput) => string | number;
+    error: (title: React.ReactNode, opts?: ToastInput) => string | number;
+    dismiss: (id?: number | string) => string | number;
+    custom: (jsx: (id: number | string) => React.ReactElement, data?: ExternalToast) => string | number;
+};

package/dist/src/components/Toast/index.d.ts

@@ -1,4 +1,5 @@
-import { toast } from 'sonner';
-
 export { Toaster } from './Toaster';
-export { toast };
+export { Toast } from './Toast';
+export type { ToastProps, ToastIntent, ToastTheme } from './Toast';
+export { toast } from './createToast';
+export type { ToastInput } from './createToast';

package/dist/src/components/index.d.ts

@@ -29,6 +29,7 @@ export * from './SegmentedControls';
 export * from './Tabs';
 export * from './FilterToggleGroup';
 export * from './CountFilterChips';
+export * from './Tag';
 export * from './BarChart';
 export * from './Layout';
 export * from './ContentArea';