@bestow-ui/react 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,361 @@
+import * as react from 'react';
+import { HTMLAttributes, ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, ElementType, ReactElement } from 'react';
+import * as Dialog from '@radix-ui/react-dialog';
+import { space } from '@bestow-ui/tokens';
+
+/** 컴포넌트 스타일은 반드시 vars 를 통해 토큰을 참조한다. */
+declare const vars: {
+    color: {
+        bg: {
+            default: `var(--${string})`;
+            subtle: `var(--${string})`;
+            muted: `var(--${string})`;
+            inverse: `var(--${string})`;
+            overlay: `var(--${string})`;
+        };
+        fg: {
+            default: `var(--${string})`;
+            muted: `var(--${string})`;
+            subtle: `var(--${string})`;
+            inverse: `var(--${string})`;
+        };
+        border: {
+            default: `var(--${string})`;
+            strong: `var(--${string})`;
+            focus: `var(--${string})`;
+        };
+        primary: {
+            solid: `var(--${string})`;
+            solidHover: `var(--${string})`;
+            contrast: `var(--${string})`;
+            subtle: `var(--${string})`;
+            subtleHover: `var(--${string})`;
+            text: `var(--${string})`;
+        };
+        neutral: {
+            solid: `var(--${string})`;
+            solidHover: `var(--${string})`;
+            contrast: `var(--${string})`;
+            subtle: `var(--${string})`;
+            subtleHover: `var(--${string})`;
+            text: `var(--${string})`;
+        };
+        danger: {
+            solid: `var(--${string})`;
+            solidHover: `var(--${string})`;
+            contrast: `var(--${string})`;
+            subtle: `var(--${string})`;
+            subtleHover: `var(--${string})`;
+            text: `var(--${string})`;
+        };
+        success: {
+            solid: `var(--${string})`;
+            solidHover: `var(--${string})`;
+            contrast: `var(--${string})`;
+            subtle: `var(--${string})`;
+            subtleHover: `var(--${string})`;
+            text: `var(--${string})`;
+        };
+    };
+    space: {
+        readonly 0: `var(--${string})`;
+        readonly 1: `var(--${string})`;
+        readonly 2: `var(--${string})`;
+        readonly 3: `var(--${string})`;
+        readonly 4: `var(--${string})`;
+        readonly 5: `var(--${string})`;
+        readonly 6: `var(--${string})`;
+        readonly 8: `var(--${string})`;
+        readonly 10: `var(--${string})`;
+        readonly 12: `var(--${string})`;
+        readonly 16: `var(--${string})`;
+    };
+    radius: {
+        readonly none: `var(--${string})`;
+        readonly sm: `var(--${string})`;
+        readonly md: `var(--${string})`;
+        readonly lg: `var(--${string})`;
+        readonly xl: `var(--${string})`;
+        readonly full: `var(--${string})`;
+    };
+    font: {
+        family: {
+            readonly sans: `var(--${string})`;
+            readonly mono: `var(--${string})`;
+        };
+        size: {
+            readonly xs: `var(--${string})`;
+            readonly sm: `var(--${string})`;
+            readonly md: `var(--${string})`;
+            readonly lg: `var(--${string})`;
+            readonly xl: `var(--${string})`;
+            readonly '2xl': `var(--${string})`;
+            readonly '3xl': `var(--${string})`;
+            readonly '4xl': `var(--${string})`;
+        };
+        weight: {
+            readonly regular: `var(--${string})`;
+            readonly medium: `var(--${string})`;
+            readonly semibold: `var(--${string})`;
+            readonly bold: `var(--${string})`;
+        };
+        lineHeight: {
+            readonly tight: `var(--${string})`;
+            readonly normal: `var(--${string})`;
+            readonly relaxed: `var(--${string})`;
+        };
+    };
+    shadow: {
+        readonly sm: `var(--${string})`;
+        readonly md: `var(--${string})`;
+        readonly lg: `var(--${string})`;
+    };
+    duration: {
+        readonly fast: `var(--${string})`;
+        readonly normal: `var(--${string})`;
+        readonly slow: `var(--${string})`;
+    };
+    zIndex: {
+        readonly dropdown: `var(--${string})`;
+        readonly overlay: `var(--${string})`;
+        readonly modal: `var(--${string})`;
+        readonly toast: `var(--${string})`;
+        readonly tooltip: `var(--${string})`;
+    };
+};
+declare const themeClass: {
+    light: string;
+    dark: string;
+};
+type ThemeName = keyof typeof themeClass;
+
+interface ThemeProviderProps extends HTMLAttributes<HTMLDivElement> {
+    /** 적용할 테마. 중첩해서 일부 영역만 다른 테마를 적용할 수도 있다. */
+    theme?: ThemeName;
+}
+declare const ThemeProvider: react.ForwardRefExoticComponent<ThemeProviderProps & react.RefAttributes<HTMLDivElement>>;
+/** 현재 적용 중인 테마 이름을 반환한다. */
+declare function useTheme(): ThemeName;
+/**
+ * Portal 로 ThemeProvider 바깥(body)에 렌더링되는 요소에 붙일 className.
+ * 현재 테마의 CSS 변수와 기본 글꼴을 다시 적용한다.
+ */
+declare function usePortalClassName(): string;
+
+interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'color'> {
+    /** 시각적 스타일 */
+    variant?: 'solid' | 'soft' | 'outline' | 'ghost';
+    /** 의미 색상 */
+    color?: 'primary' | 'neutral' | 'danger';
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 부모 너비를 꽉 채운다 */
+    fullWidth?: boolean;
+    /** 레이블 앞에 표시할 아이콘 */
+    startIcon?: ReactNode;
+    /** 레이블 뒤에 표시할 아이콘 */
+    endIcon?: ReactNode;
+}
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
+    /** 체크박스 옆에 표시할 레이블 */
+    label?: ReactNode;
+    /** 크기 */
+    size?: 'sm' | 'md';
+    /** 일부 선택 상태 (전체 선택 체크박스 등) */
+    indeterminate?: boolean;
+    /** 에러 상태 */
+    invalid?: boolean;
+}
+declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
+
+interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 에러 상태 표시 (aria-invalid 도 함께 설정된다) */
+    invalid?: boolean;
+    /** 부모 너비를 꽉 채운다 */
+    fullWidth?: boolean;
+    /** 입력창 앞에 표시할 요소 (아이콘, 단위 등) */
+    startAdornment?: ReactNode;
+    /** 입력창 뒤에 표시할 요소 */
+    endAdornment?: ReactNode;
+    /** 바깥 래퍼에 적용할 className. className 은 input 요소에 적용된다 */
+    rootClassName?: string;
+}
+declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
+
+interface TextFieldProps extends Omit<InputProps, 'invalid'> {
+    /** 입력창 위에 표시할 레이블 */
+    label?: ReactNode;
+    /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
+    helperText?: ReactNode;
+    /** 에러 상태 */
+    error?: boolean;
+}
+declare const TextField: react.ForwardRefExoticComponent<TextFieldProps & react.RefAttributes<HTMLInputElement>>;
+
+interface ModalProps {
+    /** 열림 상태 (제어 모드) */
+    open?: boolean;
+    /** 처음 열림 상태 (비제어 모드) */
+    defaultOpen?: boolean;
+    /** 열림 상태가 바뀔 때 호출된다 */
+    onOpenChange?: (open: boolean) => void;
+    /** 클릭하면 모달을 여는 요소. 버튼 등 포커스 가능한 요소 하나여야 한다 */
+    trigger?: ReactNode;
+    /** 제목 (스크린리더가 모달 이름으로 읽는다) */
+    title: ReactNode;
+    /** 제목 아래 설명 */
+    description?: ReactNode;
+    /** 본문 */
+    children?: ReactNode;
+    /** 하단 버튼 영역. 닫기 버튼은 ModalClose 로 감싼다 */
+    footer?: ReactNode;
+    /** 너비 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 오른쪽 위 닫기(X) 버튼 숨기기 */
+    hideCloseButton?: boolean;
+    /** 바깥 영역 클릭으로 닫기 (기본 true) */
+    closeOnOverlayClick?: boolean;
+    /** 내용 영역 className */
+    className?: string;
+}
+declare function Modal({ open, defaultOpen, onOpenChange, trigger, title, description, children, footer, size, hideCloseButton, closeOnOverlayClick, className, }: ModalProps): react.JSX.Element;
+/**
+ * 감싼 요소를 클릭하면 모달이 닫힌다.
+ * @example <ModalClose asChild><Button>취소</Button></ModalClose>
+ */
+declare const ModalClose: react.ForwardRefExoticComponent<Dialog.DialogCloseProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface SelectOption {
+    value: string;
+    label: ReactNode;
+    disabled?: boolean;
+}
+interface SelectProps {
+    /** 선택지 목록 */
+    options: SelectOption[];
+    /** 선택된 값 (제어 모드) */
+    value?: string;
+    /** 처음 선택된 값 (비제어 모드) */
+    defaultValue?: string;
+    /** 값이 바뀔 때 호출된다 */
+    onValueChange?: (value: string) => void;
+    /** 선택 전 표시할 문구 */
+    placeholder?: ReactNode;
+    /** 위에 표시할 레이블 */
+    label?: ReactNode;
+    /** 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
+    helperText?: ReactNode;
+    /** 에러 상태 */
+    error?: boolean;
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 부모 너비를 꽉 채운다 */
+    fullWidth?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    /** form 제출 시 사용할 이름 */
+    name?: string;
+    id?: string;
+    /** label 이 없을 때 스크린리더용 이름 */
+    'aria-label'?: string;
+    /** 트리거 className */
+    className?: string;
+}
+declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface StackProps extends HTMLAttributes<HTMLElement> {
+    /** 렌더링할 요소 */
+    as?: ElementType;
+    /** 배치 방향 */
+    direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
+    /** 자식 사이 간격 (space 토큰 키) */
+    gap?: keyof typeof space;
+    /** 교차축 정렬 (align-items) */
+    align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+    /** 주축 정렬 (justify-content) */
+    justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+    /** 줄바꿈 허용 */
+    wrap?: boolean;
+}
+declare const Stack: react.ForwardRefExoticComponent<StackProps & react.RefAttributes<HTMLElement>>;
+
+interface ToastOptions {
+    /** 제목 */
+    title: ReactNode;
+    /** 설명 */
+    description?: ReactNode;
+    /** 의미 색상 */
+    variant?: 'default' | 'success' | 'danger';
+    /** 자동으로 닫히기까지 시간(ms). Infinity 면 자동으로 닫히지 않는다 */
+    duration?: number;
+    /** 실행 버튼 */
+    action?: {
+        label: string;
+        onClick: () => void;
+        /** 스크린리더용 대체 설명 (예: "실행 취소하려면 Ctrl+Z") */
+        altText?: string;
+    };
+}
+interface ToastContextValue {
+    /** 토스트를 띄우고 id 를 반환한다 */
+    toast: (options: ToastOptions) => number;
+    /** id 의 토스트를 닫는다. id 가 없으면 모두 닫는다 */
+    dismiss: (id?: number) => void;
+}
+interface ToastProviderProps {
+    children: ReactNode;
+    /** 기본 표시 시간(ms) */
+    duration?: number;
+    /** 스크린리더가 토스트 영역을 읽을 때 쓰는 이름 */
+    label?: string;
+}
+/** 앱 최상단(ThemeProvider 안쪽)에 한 번 감싸고, 하위에서 useToast() 로 토스트를 띄운다. */
+declare function ToastProvider({ children, duration, label }: ToastProviderProps): react.JSX.Element;
+declare function useToast(): ToastContextValue;
+
+interface TooltipProps {
+    /** 툴팁 내용 */
+    content: ReactNode;
+    /** 툴팁을 띄울 요소. ref 를 받을 수 있는 요소 하나여야 한다 */
+    children: ReactElement;
+    /** 표시 방향 */
+    side?: 'top' | 'right' | 'bottom' | 'left';
+    /** 정렬 */
+    align?: 'start' | 'center' | 'end';
+    /** 마우스를 올린 뒤 표시까지 지연 시간(ms) */
+    delay?: number;
+    /** 열림 상태 (제어 모드) */
+    open?: boolean;
+    /** 처음 열림 상태 (비제어 모드) */
+    defaultOpen?: boolean;
+    /** 열림 상태가 바뀔 때 호출된다 */
+    onOpenChange?: (open: boolean) => void;
+    /** true 이면 툴팁을 띄우지 않고 children 만 렌더링한다 */
+    disabled?: boolean;
+    /** 툴팁 className */
+    className?: string;
+}
+declare function Tooltip({ content, children, side, align, delay, open, defaultOpen, onOpenChange, disabled, className, }: TooltipProps): react.JSX.Element;
+
+type TypographyVariant = 'display' | 'h1' | 'h2' | 'h3' | 'h4' | 'body-lg' | 'body' | 'body-sm' | 'caption';
+interface TypographyProps extends Omit<HTMLAttributes<HTMLElement>, 'color'> {
+    /** 텍스트 스타일 */
+    variant?: TypographyVariant;
+    /** 렌더링할 요소. 기본값은 variant 에 따라 결정된다 (h1, p, span 등) */
+    as?: ElementType;
+    /** 글자 색상 */
+    color?: 'default' | 'muted' | 'subtle' | 'primary' | 'danger' | 'success' | 'inherit';
+    /** variant 의 기본 굵기를 덮어쓴다 */
+    weight?: 'regular' | 'medium' | 'semibold' | 'bold';
+    /** 정렬 */
+    align?: 'start' | 'center' | 'end';
+    /** 한 줄로 자르고 말줄임표를 표시한다 */
+    truncate?: boolean;
+}
+declare const Typography: react.ForwardRefExoticComponent<TypographyProps & react.RefAttributes<HTMLElement>>;
+
+export { Button, type ButtonProps, Checkbox, type CheckboxProps, Input, type InputProps, Modal, ModalClose, type ModalProps, Select, type SelectOption, type SelectProps, Stack, type StackProps, TextField, type TextFieldProps, type ThemeName, ThemeProvider, type ThemeProviderProps, type ToastOptions, ToastProvider, type ToastProviderProps, Tooltip, type TooltipProps, Typography, type TypographyProps, type TypographyVariant, themeClass, usePortalClassName, useTheme, useToast, vars };