@idbrnd/design-system 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,276 @@
+# @idbrnd/design-system
+
+React 기반 IDB 디자인 시스템 컴포넌트 라이브러리입니다.
+
+## 설치
+
+```bash
+npm install @idbrnd/design-system
+```
+
+`peerDependencies`
+- `react@^18.3.1`
+- `react-dom@^18.3.1`
+
+## 시작하기
+
+엔트리 파일(예: `src/main.tsx`)에서 스타일을 먼저 로드한 뒤 컴포넌트를 사용합니다.
+
+```tsx
+import '@idbrnd/design-system/style.css';
+import { FillButton } from '@idbrnd/design-system';
+
+export default function App() {
+  return <FillButton>확인</FillButton>;
+}
+```
+
+## 제공 컴포넌트 / API
+
+- 버튼
+  - `FillButton`
+  - `OutlineButton`
+  - `TextButton`
+  - `WeakButton`
+  - `BasicIconButton`
+  - `FillIconButton`
+  - `OutlineIconButton`
+- 입력
+  - `Input`
+  - `SearchBar`
+- 피드백
+  - `showToast`, `dismissToast`
+  - `showSnackbar`, `dismissSnackbar`
+  - `Spinner`, `CustomSpinner`, `Clip`, `FadeSpinner`
+- 기타
+  - `PushBadge`
+
+## 사용 예시
+
+### 1. Fill / Outline / Text / Weak Button
+
+```tsx
+import {
+  FillButton,
+  OutlineButton,
+  TextButton,
+  WeakButton
+} from '@idbrnd/design-system';
+
+function ButtonExample() {
+  return (
+    <>
+      <FillButton variant="primary">저장</FillButton>
+      <OutlineButton variant="secondary">취소</OutlineButton>
+      <TextButton size="small" variant="assistive">텍스트 버튼</TextButton>
+      <WeakButton size="xsmall" variant="error">삭제</WeakButton>
+    </>
+  );
+}
+```
+
+### 2. Icon Button + PushBadge
+
+```tsx
+import {
+  BasicIconButton,
+  FillIconButton,
+  OutlineIconButton,
+  PushBadge
+} from '@idbrnd/design-system';
+
+function IconButtonExample() {
+  return (
+    <>
+      <div style={{ position: 'relative', width: 'fit-content' }}>
+        <BasicIconButton>+</BasicIconButton>
+        <PushBadge variant="dot" />
+      </div>
+
+      <FillIconButton variant="primary" size="large">
+        +
+      </FillIconButton>
+
+      <OutlineIconButton size="medium">
+        +
+      </OutlineIconButton>
+    </>
+  );
+}
+```
+
+`PushBadge` 단독 사용:
+
+```tsx
+import { PushBadge } from '@idbrnd/design-system';
+
+function PushBadgeExample() {
+  return (
+    <>
+      <PushBadge variant="number" count={32} />
+      <PushBadge variant="info" />
+      <PushBadge variant="dot" />
+    </>
+  );
+}
+```
+
+### 3. Input (Controlled)
+
+`Input`은 `value` + `onChange`를 받는 controlled 컴포넌트입니다.
+
+```tsx
+import { useState } from 'react';
+import { Input } from '@idbrnd/design-system';
+
+function InputExample() {
+  const [email, setEmail] = useState('');
+
+  return (
+    <Input
+      headingContent="이메일"
+      placeholder="이메일을 입력하세요"
+      value={email}
+      onChange={(event) => setEmail(event.target.value)}
+      description="가입 안내 메일을 받을 주소입니다."
+    />
+  );
+}
+```
+
+유의사항:
+
+- `heading={false}`이면 상단 라벨과 `required` 별표 표시는 렌더링되지 않습니다. 다만 실제 `<input>`의 `required` 속성은 그대로 적용됩니다.
+- `description`은 문자열뿐 아니라 JSX도 받을 수 있습니다. `variant="error"`일 때는 `description` 대신 `errorMessage`가 우선 노출됩니다.
+- `errorMessage`도 문자열뿐 아니라 JSX를 받을 수 있습니다.
+- `leadingIcon`, `headingContent`, `trailingContent`는 모두 JSX를 넣을 수 있습니다. 특히 `trailingContent`에는 버튼, 텍스트, 아이콘 조합 등 원하는 형태의 trailing UI를 구성할 수 있습니다.
+- `width`는 `number | string`을 지원하며, 지정하지 않으면 기본값은 `100%`입니다.
+- `variant`를 지정하지 않으면 값 존재 여부에 따라 내부적으로 `basic` 또는 `typed` 상태가 자동 적용됩니다.
+
+### 4. SearchBar
+
+`SearchBar`는 `Enter` 입력 또는 우측 검색 버튼 클릭 시 `onSearch`를 호출합니다.
+우측 삭제 버튼은 입력값이 있을 때만 표시되며, `onClear`를 전달하면 커스텀 삭제 동작을 사용할 수 있습니다.
+`variant="default"`는 내부 `Input`의 `basic`에 매핑되며, `onTyping`/`typed`/`error`도 각각 대응됩니다.
+
+```tsx
+import { useState } from 'react';
+import { SearchBar } from '@idbrnd/design-system';
+
+function SearchExample() {
+  const [keyword, setKeyword] = useState('');
+
+  return (
+    <SearchBar
+      value={keyword}
+      onChange={(event) => setKeyword(event.target.value)}
+      onSearch={(value) => {
+        console.log('search:', value);
+      }}
+      placeholder="검색어를 입력하세요"
+    />
+  );
+}
+```
+
+### 5. Spinner
+
+```tsx
+import {
+  Spinner,
+  CustomSpinner,
+  Clip,
+  FadeSpinner
+} from '@idbrnd/design-system';
+
+function SpinnerExample() {
+  return (
+    <div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>
+      <Spinner />
+      <CustomSpinner size={12} />
+      <Clip size={24} color="var(--semantic-primary-default)" />
+      <FadeSpinner width={4} height={12} />
+    </div>
+  );
+}
+```
+
+### 6. Toast
+
+```tsx
+import {
+  FillButton,
+  showToast,
+  dismissToast
+} from '@idbrnd/design-system';
+
+function ToastExample() {
+  return (
+    <>
+      <FillButton
+        onClick={() =>
+          showToast({
+            variant: 'positive',
+            message: '저장되었습니다.'
+          })
+        }
+      >
+        Toast 열기
+      </FillButton>
+
+      <FillButton variant="assistive" onClick={() => dismissToast()}>
+        Toast 닫기
+      </FillButton>
+    </>
+  );
+}
+```
+
+### 7. Snackbar
+
+```tsx
+import {
+  FillButton,
+  showSnackbar,
+  dismissSnackbar
+} from '@idbrnd/design-system';
+
+function SnackbarExample() {
+  return (
+    <>
+      <FillButton
+        onClick={() =>
+          showSnackbar({
+            variant: 'basic',
+            heading: 'Message deleted.',
+            description: 'You can undo this action.',
+            actionLabel: '실행 취소',
+            onActionClick: () => console.log('undo'),
+            closeButton: true
+          })
+        }
+      >
+        Snackbar 열기
+      </FillButton>
+
+      <FillButton variant="assistive" onClick={() => dismissSnackbar()}>
+        Snackbar 닫기
+      </FillButton>
+    </>
+  );
+}
+```
+
+## TypeScript
+
+모든 컴포넌트의 Props 타입을 패키지에서 직접 import 할 수 있습니다.
+
+```tsx
+import type { FillButtonProps, InputProps, ToastShowOptions } from '@idbrnd/design-system';
+```
+
+## 주의사항
+
+- `Input`, `SearchBar`는 controlled 방식으로 사용해야 합니다.
+- `showToast`, `showSnackbar`는 내부적으로 `document.body`에 포털을 생성하므로 브라우저 환경에서 호출해야 합니다.
+- CSS 변수/타이포그래피를 포함한 스타일을 위해 `@idbrnd/design-system/style.css` import를 권장합니다.

package/dist/components/Input/Input.d.ts

@@ -1,5 +1,5 @@
 import type { InputProps } from './Input.types';
-export type { InputProps, InputSize, InputVariant, InputType } from './Input.types';
+export type { InputProps, InputSize, InputVariant, DesignType } from './Input.types';
 declare function Input({ type, // input HTML 타입
 designType, // 인풋 외형 타입
 size, // 인풋 높이 크기

package/dist/components/Input/Input.types.d.ts

@@ -3,7 +3,7 @@ import type { CSSProperties, HTMLInputTypeAttribute, InputHTMLAttributes, ReactN
  * Input 컨테이너의 시각 스타일 타입.
  * @defaultValue `'outline'`
  */
-export type InputType = 'outline' | 'fill';
+export type DesignType = 'outline' | 'fill';
 /**
  * Input 높이 타입.
  * @defaultValue `'default'`
@@ -31,7 +31,7 @@ export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
      * Input 컨테이너 외형 타입.
      * @defaultValue `'outline'`
      */
-    designType?: InputType;
+    designType?: DesignType;
     /**
      * Input 높이.
      * - `default`: 44px
@@ -41,7 +41,8 @@ export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
     size?: InputSize;
     /**
      * Input 상태 variant.
-     * 미지정 시 내부 상호작용(포커스/입력/값 존재 여부)으로 자동 계산한다.
+     * 미지정 시 값 존재 여부에 따라 `basic`/`typed`를 자동 계산한다.
+     * 포커스 시각 상태는 CSS interaction으로 처리한다.
      */
     variant?: InputVariant;
     /**

package/dist/components/Input/useInputState.d.ts

@@ -1,4 +1,4 @@
-import { type ChangeEvent, type FocusEvent } from 'react';
+import type { ChangeEvent, FocusEvent } from 'react';
 import type { InputProps } from './Input.types';
 interface UseInputStateParams {
     value: InputProps['value'];
@@ -8,8 +8,6 @@ interface UseInputStateParams {
 }
 export interface UseInputStateResult {
     currentValue: InputProps['value'];
-    isFocused: boolean;
-    isTyping: boolean;
     handleFocus: (event: FocusEvent<HTMLInputElement>) => void;
     handleBlur: (event: FocusEvent<HTMLInputElement>) => void;
     handleChange: (event: ChangeEvent<HTMLInputElement>) => void;

package/dist/components/SearchBar/SearchBar.d.ts

@@ -1,19 +1,23 @@
 import type { InputProps, InputSize } from '../Input/Input';
 export type SearchBarSize = InputSize;
-export interface SearchBarProps extends Omit<InputProps, 'type' | 'value' | 'onChange'> {
+export type SearchBarVariant = 'default' | 'onTyping' | 'typed' | 'error';
+export interface SearchBarProps extends Omit<InputProps, 'type' | 'value' | 'onChange' | 'variant'> {
     value: string;
     onChange: NonNullable<InputProps['onChange']>;
     onSearch: (value: string) => void;
+    onClear?: () => void;
+    variant?: SearchBarVariant;
 }
 declare function SearchBar({ value, // 검색어 값
 onChange, // 입력 변경 핸들러
 onSearch, // 검색 실행 핸들러
+onClear, // 입력내용 전체 삭제 핸들러(미전달 시 기본 삭제 동작)
 size, // 인풋 크기
 width, // 컴포넌트 너비
 designType, // 인풋 외형 타입
 heading, // 라벨 표시 여부
 headingContent, // 라벨 내용
-variant, // 인풋 상태 variant
+variant, // SearchBar 상태 variant
 description, // 하단 안내 문구
 fixedDescriptionHeight, // 하단 문구 영역 높이 고정 여부
 disabled, // 전체 비활성화 여부
@@ -22,6 +26,7 @@ id, // input id
 name, // input name
 placeholder, // placeholder 텍스트
 leadingIcon, // 좌측 아이콘 슬롯
+trailingContent, // 우측 trailing 콘텐츠(미지정 시 검색 버튼 사용)
 maxLength, // 최대 입력 길이
 required, // 필수 입력 여부
 errorMessage, // 에러 상태 문구

package/dist/index.d.ts

@@ -16,9 +16,9 @@ export { default as WeakButton } from './components/Button/Weak/WeakButton';
 export type { BasicIconButtonProps, BasicIconButtonSize } from './components/Button/BasicIcon/BasicIconButton';
 export type { FillButtonProps, FillButtonSize, FillButtonVariant, FillButtonWidthType } from './components/Button/Fill/FillButton';
 export type { FillIconButtonProps, FillIconButtonSize, FillIconButtonVariant } from './components/Button/FillIcon/FillIconButton';
-export type { InputProps, InputSize, InputType, InputVariant } from './components/Input/Input';
+export type { InputProps, InputSize, DesignType, InputVariant } from './components/Input/Input';
 export type { PushBadgeProps, PushBadgeVariant } from './components/PushBadge/PushBadge';
-export type { SearchBarProps, SearchBarSize } from './components/SearchBar/SearchBar';
+export type { SearchBarProps, SearchBarSize, SearchBarVariant } from './components/SearchBar/SearchBar';
 export type { SnackbarShowOptions, SnackbarVariant } from './components/Snackbar/Snackbar';
 export type { ClipProps, CustomSpinnerProps, FadeSpinnerProps } from './components/Spinner/Spinner';
 export type { ToastShowOptions, ToastVariant } from './components/Toast/Toast';