insystem-atoms 0.1.0

package/README.md

@@ -0,0 +1,366 @@
+# insystem-atoms
+
+사내 React 아토믹 디자인 컴포넌트 라이브러리.
+SI 프로젝트 간 UI 일관성과 유지보수성 향상을 위해 설계되었습니다.
+
+[![npm version](https://img.shields.io/npm/v/insystem-atoms)](https://www.npmjs.com/package/insystem-atoms)
+[![license](https://img.shields.io/npm/l/insystem-atoms)](LICENSE)
+
+---
+
+## 설치
+
+```bash
+npm install insystem-atoms styled-components
+```
+
+> **peerDependencies**: `react >= 18`, `react-dom >= 18`, `styled-components >= 6`
+
+---
+
+## 빠른 시작
+
+```tsx
+import { Button, Input, Checkbox } from 'insystem-atoms';
+
+function App() {
+  return (
+    <>
+      <Button variant="primary" onClick={handleSave}>저장</Button>
+      <Input label="이름" required placeholder="홍길동" />
+      <Checkbox label="동의합니다" checked={agreed} onChange={setAgreed} />
+    </>
+  );
+}
+```
+
+---
+
+## 브랜드 색상 / 폰트 오버라이드
+
+앱 진입점(`main.tsx`) 최상단에서 **렌더링 전** 한 번만 호출합니다.
+
+```ts
+import { configureTokens } from 'insystem-atoms';
+
+configureTokens({
+  color: {
+    primary:      '#a44945',
+    primaryHover: '#8a3d3a',
+    primaryLight: '#fff0ef',
+  },
+  font: {
+    family: "'NanumSquareNeo', 'Apple SD Gothic Neo', sans-serif",
+  },
+  radius: {
+    md: '10px',
+  },
+});
+```
+
+---
+
+## 컴포넌트
+
+### Button
+
+```tsx
+import { Button } from 'insystem-atoms';
+
+<Button variant="primary">저장</Button>
+<Button variant="secondary" size="sm">취소</Button>
+<Button variant="danger" loading>삭제 중...</Button>
+<Button variant="primary" fullWidth>전체 너비</Button>
+<Button leftIcon={<PlusIcon />}>추가</Button>
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `variant` | `primary` \| `secondary` \| `success` \| `warning` \| `danger` \| `ghost` \| `admin` \| `neutral` \| `conversion` \| `icon` | `primary` | 버튼 스타일 |
+| `size` | `xs` \| `sm` \| `md` \| `lg` | `md` | 크기 |
+| `loading` | `boolean` | `false` | 로딩 스피너 표시 |
+| `fullWidth` | `boolean` | `false` | 컨테이너 전체 너비 |
+| `width` | `string \| number` | — | 고정 너비 |
+| `leftIcon` | `ReactNode` | — | 좌측 아이콘 슬롯 |
+| `rightIcon` | `ReactNode` | — | 우측 아이콘 슬롯 |
+| `iconOnly` | `boolean` | `false` | 아이콘 전용 (텍스트 숨김) |
+
+---
+
+### Input
+
+```tsx
+import { Input } from 'insystem-atoms';
+
+<Input label="이메일" required placeholder="example@email.com" />
+<Input label="검색" prefix={<SearchIcon />} clearable />
+<Input error="필수 입력값입니다" />
+<Input hint="8자 이상 입력해주세요" />
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `label` | `string` | — | 레이블 |
+| `required` | `boolean` | — | 필수 표시(`*`) |
+| `error` | `string` | — | 에러 메시지 (빨간 테두리) |
+| `hint` | `string` | — | 힌트 텍스트 |
+| `size` | `sm` \| `md` \| `lg` | `md` | 크기 |
+| `prefix` | `ReactNode` | — | 좌측 장식 슬롯 |
+| `suffix` | `ReactNode` | — | 우측 장식 슬롯 |
+| `clearable` | `boolean` | `false` | X 버튼으로 초기화 |
+| `fullWidth` | `boolean` | `true` | 전체 너비 |
+| `width` | `string \| number` | — | 고정 너비 |
+
+---
+
+### Checkbox
+
+```tsx
+import { Checkbox } from 'insystem-atoms';
+
+<Checkbox label="전체 동의" checked={all} onChange={handleAll} />
+<Checkbox label="항목 1" indeterminate />
+<Checkbox label="비활성" disabled />
+```
+
+| Prop | 타입 | 설명 |
+|------|------|------|
+| `label` | `ReactNode` | 레이블 |
+| `size` | `sm` \| `md` \| `lg` | 크기 |
+| `indeterminate` | `boolean` | 중간 선택 상태 |
+| `error` | `boolean` | 에러 테두리 |
+| `checkColor` | `string` | 체크 활성 색상 오버라이드 |
+
+---
+
+### Radio / RadioGroup
+
+```tsx
+import { RadioGroup } from 'insystem-atoms';
+
+<RadioGroup
+  name="gender"
+  options={[
+    { value: 'male', label: '남성' },
+    { value: 'female', label: '여성' },
+  ]}
+  value={value}
+  onChange={setValue}
+/>
+
+// 격자 배치
+<RadioGroup
+  name="plan"
+  options={plans}
+  direction="grid"
+  gridColumns={3}
+  value={value}
+  onChange={setValue}
+/>
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `options` | `{ value, label, disabled? }[]` | — | 선택 항목 |
+| `value` | `string` | — | 선택된 값 |
+| `onChange` | `(value: string) => void` | — | 변경 콜백 |
+| `direction` | `row` \| `column` \| `grid` | `row` | 배치 방향 |
+| `gridColumns` | `number` | `3` | grid 열 수 |
+
+---
+
+### Select
+
+```tsx
+import { Select } from 'insystem-atoms';
+
+<Select
+  label="지역"
+  options={[
+    { value: 'seoul', label: '서울' },
+    { value: 'busan', label: '부산' },
+  ]}
+  placeholder="선택해주세요"
+/>
+<Select variant="filled" options={options} />
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `options` | `{ value, label, disabled? }[]` | — | 선택 항목 |
+| `placeholder` | `string` | — | 플레이스홀더 |
+| `variant` | `default` \| `outlined` \| `filled` | `default` | 배경 스타일 |
+| `label` | `string` | — | 레이블 |
+| `error` | `string` | — | 에러 메시지 |
+
+---
+
+### TextArea
+
+```tsx
+import { TextArea } from 'insystem-atoms';
+
+<TextArea label="내용" required maxLength={500} />
+<TextArea resize="none" rows={6} />
+```
+
+---
+
+### Label
+
+```tsx
+import { Label } from 'insystem-atoms';
+
+<Label required htmlFor="name">이름</Label>
+<Label optional>설명</Label>
+<Label disabled>비활성</Label>
+```
+
+---
+
+### Badge
+
+```tsx
+import { Badge } from 'insystem-atoms';
+
+<Badge variant="success">활성</Badge>
+<Badge variant="danger" outline>오류</Badge>
+<Badge variant="primary" dot />   {/* 점 뱃지 */}
+```
+
+---
+
+### Chip
+
+```tsx
+import { Chip } from 'insystem-atoms';
+
+// 필터 그룹 예시
+const [selected, setSelected] = useState('all');
+
+<Chip label="전체" active={selected === 'all'} count={24} onClick={() => setSelected('all')} />
+<Chip label="진행중" active={selected === 'active'} count={8} onClick={() => setSelected('active')} />
+```
+
+---
+
+### Loading
+
+```tsx
+import { Loading } from 'insystem-atoms';
+
+<Loading size="md" />
+<Loading size="lg" text="데이터를 불러오는 중..." />
+<Loading fullscreen text="처리 중..." />   {/* 전체 화면 오버레이 */}
+```
+
+---
+
+### Pagination
+
+```tsx
+import { Pagination } from 'insystem-atoms';
+
+const [page, setPage] = useState(1);
+
+<Pagination
+  currentPage={page}
+  totalPages={20}
+  onPageChange={setPage}
+/>
+```
+
+---
+
+### Toast
+
+```tsx
+import { Toast } from 'insystem-atoms';
+
+const [visible, setVisible] = useState(false);
+
+{visible && (
+  <Toast
+    type="success"
+    message="저장되었습니다."
+    onClose={() => setVisible(false)}
+  />
+)}
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `message` | `string` | — | 표시할 메시지 |
+| `type` | `info` \| `success` \| `error` \| `warning` | `info` | 타입 |
+| `duration` | `number` | `3000` | 자동 닫힘 ms (0 = 수동) |
+| `position` | `top-center` \| `top-right` \| `bottom-center` \| `bottom-right` | `bottom-center` | 위치 |
+| `onClose` | `() => void` | — | 닫기 콜백 |
+
+---
+
+## 스타일 오버라이드 Props
+
+모든 컴포넌트에 아래 props를 사용해 인라인으로 스타일을 변경할 수 있습니다.
+
+```tsx
+<Button borderRadius="20px">둥근 버튼</Button>
+<Button backgroundColor="#7C3AED" textColor="#fff">보라 버튼</Button>
+<Input borderColor="#7C3AED" borderRadius="8px" />
+<Badge backgroundColor="#f0fdf4" textColor="#166534">커스텀</Badge>
+```
+
+| Prop | 컴포넌트 | 설명 |
+|------|----------|------|
+| `borderRadius` | 전체 | 모서리 반경 |
+| `borderColor` | 전체 | 테두리 색상 |
+| `textColor` | 전체 | 텍스트/전경 색상 |
+| `backgroundColor` | 전체 | 배경색 |
+| `padding` | Button, Input, TextArea | 내부 여백 |
+| `checkColor` | Checkbox, Radio | 체크/선택 활성 색상 |
+| `activeColor` | Chip, Pagination | 활성 상태 색상 |
+
+---
+
+## 디자인 토큰 전체 오버라이드
+
+```ts
+import { configureTokens, resetTokens } from 'insystem-atoms';
+import type { Tokens } from 'insystem-atoms';
+
+// 오버라이드 (부분 적용 가능)
+configureTokens({
+  color: {
+    primary:      '#0f766e',
+    primaryHover: '#0d6b63',
+    primaryLight: '#f0fdfa',
+    danger:       '#dc2626',
+  },
+  font: {
+    family: "'Noto Sans KR', sans-serif",
+    size: { md: '15px' },
+  },
+  radius: {
+    md:   '8px',
+    full: '50px',
+  },
+});
+
+// 기본값 복원
+resetTokens();
+```
+
+---
+
+## TypeScript
+
+모든 컴포넌트는 완전한 타입을 지원합니다.
+
+```ts
+import type { ButtonProps, InputProps, Size, Variant } from 'insystem-atoms';
+```
+
+---
+
+## 라이선스
+
+MIT