@t3q-ui/design-system 0.0.0-stage → 1.56.1

package/LICENSE.md

@@ -0,0 +1,88 @@
+T3Q 디자인 시스템 라이선스 (@t3q-ui/design-system)
+
+Copyright (c) 2025-present 티쓰리큐 주식회사 (T3Q Inc.)
+
+1. 사용 허락
+티쓰리큐 주식회사(이하 "T3Q")는 이 패키지에 포함된 코드, 스타일, 문서와 스킬 파일(이하 "본 소프트웨어")을
+2조의 범위 안에서 사용·복제·수정·병합·배포할 수 있도록 무상으로 허락합니다.
+
+2. 허락 범위
+본 소프트웨어는 다음 목적으로만 사용할 수 있습니다.
+  가. T3Q와 맺은 계약(그 하위 계약을 포함합니다)에 따라 수행하는 프로젝트의 산출물을 개발·운영·유지보수하는 일
+  나. 가.의 산출물을 발주하거나 소유한 기관·기업(이하 "발주자")과 발주자가 지정한 후속 유지보수 수행자가
+      그 산출물을 운영·기능개선·재개발·유지보수하는 일
+  다. 가.·나.의 산출물에 포함된 형태로 본 소프트웨어를 납품·배포하는 일, 그리고 법령이나 계약에 따라
+      소스코드를 제3의 기관에 임치하는 일
+  라. 가.~다.를 위해 도입 전에 검토·평가하는 일
+위 범위를 벗어난 사용, 그리고 본 소프트웨어나 그 일부를 별도의 디자인 시스템·UI 라이브러리로 재배포하거나
+판매하는 일에는 T3Q의 서면 동의가 필요합니다.
+
+3. 이름과 상표
+이 라이선스는 T3Q의 이름, 로고, 상표를 사용할 권리를 주지 않습니다. 본 소프트웨어의 출처를 밝히는 데 필요한
+범위는 예외로 합니다.
+
+4. 고지 유지
+본 소프트웨어를 복제하거나 배포할 때는 위 저작권 표시와 이 라이선스 전문을 함께 포함해야 합니다.
+
+5. 제3자 구성요소
+본 소프트웨어가 의존하는 제3자 구성요소는 각자의 라이선스를 따릅니다. Pretendard 글꼴은 SIL Open Font
+License 1.1, lucide 아이콘은 ISC 라이선스입니다. 이 라이선스는 그 조건을 바꾸지 않습니다.
+
+6. 보증의 부인과 책임의 제한
+본 소프트웨어는 "있는 그대로" 제공되며, 상품성, 특정 목적 적합성, 권리 비침해를 포함한 어떠한 명시적·묵시적
+보증도 하지 않습니다. 법이 허용하는 최대 범위에서 T3Q는 본 소프트웨어의 사용 또는 사용 불능으로 생긴 손해에
+책임지지 않습니다. 기술 지원·유지보수·하자보수는 별도 계약에서 정한 경우에만 제공합니다.
+
+7. 종료
+2조의 범위를 벗어나 사용한 자의 권리는 자동으로 종료됩니다. 이 종료는 위반한 자에게만 적용되며, 이미 적법하게
+납품된 산출물에 대한 발주자의 권리에는 영향을 주지 않습니다.
+
+8. 해석
+한국어본과 영어본의 내용이 다르면 한국어본을 따릅니다.
+
+---
+
+T3Q Design System License (@t3q-ui/design-system)
+
+Copyright (c) 2025-present T3Q Inc.
+
+1. Grant
+T3Q Inc. ("T3Q") grants you, free of charge, the right to use, copy, modify, merge and distribute the code,
+styles, documentation and skill files included in this package (the "Software"), within the scope of Section 2.
+
+2. Scope
+The Software may be used only for the following purposes:
+  (a) development, operation and maintenance of deliverables of a project performed under a contract with
+      T3Q (including any subcontract thereof);
+  (b) operation, improvement, redevelopment and maintenance of a deliverable under (a) by the organization
+      that ordered or owns it (the "Client") and by any subsequent maintainer designated by the Client;
+  (c) delivery and distribution of the Software as part of the deliverables under (a) and (b), and deposit
+      of source code with a third-party escrow agent as required by law or contract; and
+  (d) review and evaluation of the Software before adopting it for the purposes above.
+Any other use, including redistributing or selling the Software or any part of it as a separate design system
+or UI library, requires T3Q's prior written consent.
+
+3. Name and Trademarks
+This license does not grant any right to use T3Q's name, logos or trademarks, except as needed to identify
+the origin of the Software.
+
+4. Notice
+You must include the above copyright notice and this license in all copies or distributions of the Software.
+
+5. Third-Party Components
+Third-party components the Software depends on remain under their own licenses, including the Pretendard font
+(SIL Open Font License 1.1) and lucide icons (ISC License). This license does not change those terms.
+
+6. Disclaimer and Limitation of Liability
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY LAW, T3Q SHALL NOT BE
+LIABLE FOR ANY DAMAGES ARISING FROM THE USE OF OR INABILITY TO USE THE SOFTWARE. Technical support, maintenance
+and warranty service are provided only as agreed in a separate contract.
+
+7. Termination
+Your rights under this license terminate automatically if you use the Software outside the scope of Section 2.
+Termination applies only to the party in breach and does not affect the Client's rights in deliverables that
+were lawfully delivered.
+
+8. Interpretation
+If the Korean and English versions differ, the Korean version prevails.

package/README.md

@@ -1,3 +1,465 @@
-# Temporary Holding Version
+# T3Q-UI (Design System)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+T3Q 프로젝트를 위한 React 컴포넌트 라이브러리입니다.
+
+---
+
+## 빠른 시작
+
+공개 npm(npmjs.com)에서 받습니다. 별도 레지스트리·토큰 설정이 필요 없습니다.
+
+**사용 범위**: T3Q와 계약한 프로젝트와 그 유지보수에 한해 쓸 수 있습니다. 전문은 패키지의 [`LICENSE.md`](./LICENSE.md)를 보세요.
+
+**버전은 정확히 고정하세요.** 자동으로 게시되므로 `^` 범위로 두면 호환되지 않는 변경이 들어올 수 있습니다. 올릴 때는 변경 기록을 먼저 확인합니다.
+
+### Step 1. 설치하고 setup 실행
+
+```bash
+pnpm add --save-exact @t3q-ui/design-system
+pnpm exec t3q-design setup
+```
+
+npm 이면 `npm install --save-exact @t3q-ui/design-system` 뒤 `npx t3q-design setup`.
+
+`setup` 이 만들거나 갱신하는 것입니다. 이미 맞으면 건너뛰고, 패키지를 올린 뒤 다시 돌리면 최신으로 갱신됩니다.
+
+| 파일 | 내용 |
+|---|---|
+| 진입 CSS (`@import 'tailwindcss'` 가 있는 파일) | TDS `styles.css` import(새로 넣을 때는 `fonts.css` 도 함께). 이미 `styles.css` 를 쓰는 레포엔 `fonts.css` 를 넣지 않습니다. 후보가 둘 이상이면 손대지 않고 붙여넣을 줄을 알려 줍니다 |
+| `AGENTS.md` | TDS UI 규칙 블록(`<!-- tds:start -->` … `<!-- tds:end -->`). 블록 밖은 건드리지 않습니다 |
+| `CLAUDE.md` | `@AGENTS.md` 한 줄 (없을 때만 추가) |
+| `.claude/skills/tds/` | `/tds` Skill — 새 화면을 만드는 절차 |
+| `.agents/skills/tds/` | 같은 Skill 의 Codex 사본 (Codex 는 `.agents/skills/` 에서 Skill 을 찾습니다) |
+
+`.npmrc`·`.mcp.json`·`.codex/config.toml` 은 `--registry`·`--mcp-url` 을 줄 때만 씁니다. 공개 패키지에는 접속할 MCP 서버가 없으므로 AI 도구는 Skill 의 `reference/components.md` 로 컴포넌트와 props 를 읽습니다(아래 "참조 문서"). 사내 설치는 [docs/INTERNAL_SETUP.md](./docs/INTERNAL_SETUP.md) 를 보세요.
+
+> Tailwind v4 가 아직 없는 프로젝트는 setup 전에 아래 "Tailwind 설정" 을 먼저 합니다.
+
+막히면 점검합니다:
+
+```bash
+pnpm exec t3q-design doctor
+```
+
+Node·패키지와 peer·CSS·Skill·규칙을 검사하고, 실패 항목마다 할 일을 알려 줍니다. `.npmrc` 에 `@t3q-ui:registry` 줄이 있으면 토큰·레지스트리를, `.mcp.json` 에 항목이 있으면 MCP 도 점검합니다.
+
+**AI 도구별**: Claude Code 는 첫 실행 때 `.mcp.json` 의 서버 승인을 묻습니다(승인하면 됩니다). Cursor·Copilot 은 `AGENTS.md` 와 `.claude/skills/` 를 그대로 읽고, MCP 는 각 도구의 설정(`.cursor/mcp.json`, `.vscode/mcp.json`)에 같은 URL 을 등록합니다. Codex 는 `AGENTS.md`·`.agents/skills/tds/`·`.codex/config.toml` 을 읽습니다 — setup 이 셋 다 쓰며, Codex 에서 이 프로젝트를 trust 해야 `.codex/config.toml` 이 적용됩니다. 공개 설치에는 MCP 가 없어 모든 도구가 Skill 안의 `reference/components.md`(컴포넌트·패턴 참조, 생성물)로 컴포넌트를 읽습니다.
+
+### Tailwind 설정 (v4)
+
+T3Q-UI는 **Tailwind CSS v4**를 사용합니다.
+
+```bash
+pnpm add -D tailwindcss @tailwindcss/postcss postcss
+```
+
+프로젝트 루트에 `postcss.config.cjs` 파일을 생성합니다:
+
+```javascript
+module.exports = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+}
+```
+
+> **Note:** Tailwind v4는 `tailwind.config.js` 파일이 필요 없습니다. CSS에서 직접 설정합니다.
+
+### CSS 설정 — setup 이 넣는 줄
+
+`setup` 이 진입 CSS(예: **src/index.css**)를 아래처럼 만듭니다. 손으로 할 때도 같습니다 (Tailwind v4 문법):
+
+```css
+@import 'tailwindcss';
+@import '@t3q-ui/design-system/styles.css'; /* T3Q-UI 테마 (@theme 블록) */
+@import '@t3q-ui/design-system/fonts.css'; /* Pretendard 로드 */
+
+@source "../index.html";
+@source "./**/*.{js,jsx,ts,tsx}";
+```
+
+TDS 컴포넌트의 클래스는 패키지의 `styles.css` 가 스스로 `@source` 로 등록하므로, `node_modules` 를 가리키는 `@source` 줄은 필요 없습니다.
+
+`fonts.css` 는 TDS 가 Pretendard 를 로드하는 선택지입니다. `next/font` 등으로 직접 로드하는 앱은 생략해도 됩니다(`doctor` 는 경고만 냅니다).
+
+**src/main.jsx**에서는 index.css만 import:
+
+```jsx
+import './index.css'
+
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+// ... 나머지 코드
+```
+
+> **왜 index.css에서 T3Q-UI를 import 하나요?** T3Q-UI의 `@theme` 블록이 Tailwind 테마를 확장하려면 Tailwind 처리 파이프라인 내에서 import되어야 합니다.
+
+### 사용하기
+
+이제 T3Q-UI 컴포넌트를 import해서 사용할 수 있습니다!
+
+```jsx
+import { Button, Badge, Dialog } from '@t3q-ui/design-system'
+
+function MyPage() {
+  return (
+    <div>
+      <Button variant='primaryBold'>저장</Button>
+      <Button variant='secondary'>취소</Button>
+      <Badge variant='success'>완료</Badge>
+    </div>
+  )
+}
+```
+
+### 참조 문서와 변경 기록
+
+공개 문서 사이트는 없습니다. 패키지에 들어 있는 파일을 jsDelivr 로 바로 열 수 있습니다(`<버전>` 은 설치한 버전).
+
+- 컴포넌트·패턴 참조(언제 쓰나·props·예시): https://cdn.jsdelivr.net/npm/@t3q-ui/design-system@<버전>/skills/tds/reference/components.md
+- 변경 기록: https://cdn.jsdelivr.net/npm/@t3q-ui/design-system@<버전>/CHANGELOG.md
+
+설치한 뒤에는 `node_modules/@t3q-ui/design-system/` 아래 같은 경로에서도 읽을 수 있습니다. 타입은 패키지의 `.d.ts` 가 맡습니다.
+
+---
+
+## 컴포넌트 목록
+
+### 버튼/뱃지
+
+| 컴포넌트     | 설명        | 예시                                          |
+| ------------ | ----------- | --------------------------------------------- |
+| `Button`     | 버튼        | `<Button variant="primaryBold">저장</Button>` |
+| `IconButton` | 아이콘 버튼 | `<IconButton icon={Plus} />`                  |
+| `Badge`      | 상태 뱃지   | `<Badge variant="success">완료</Badge>`       |
+| `Tag`        | 태그        | `<Tag>React</Tag>`                            |
+
+### 폼
+
+| 컴포넌트   | 설명         | 예시                           |
+| ---------- | ------------ | ------------------------------ |
+| `TextField` | 텍스트 입력 (floating label — 컨테이너 div 구조라 `<input>` drop-in 아님) | `<TextField placeholder="이름" />` |
+| `Textarea`  | 여러 줄 입력 | `<Textarea rows={4} />` |
+| `Select`   | 드롭다운     | `<Select options={[...]} />`   |
+| `Checkbox` | 체크박스     | `<Checkbox label="동의" />`    |
+| `Switch`   | 토글         | `<Switch />`                   |
+| `Range`     | 슬라이더 (± 스테퍼·숫자 입력 포함 — 순수 슬라이더는 `RangeSlider`) | `<Range min={0} max={100} />` |
+
+> 레거시 로컬 DS에서 옮겨올 때 **이름이 바뀐 것은 `Input` → `TextField` 하나**입니다. 이름이 같은 나머지는 import 경로만 바꾸면 됩니다.
+
+### 팝업/오버레이
+
+| 컴포넌트       | 설명          |
+| -------------- | ------------- |
+| `Dialog`       | 모달 창       |
+| `Drawer`       | 사이드 패널   |
+| `Popover`      | 말풍선 팝업   |
+| `Tooltip`      | 툴팁          |
+| `DropdownMenu` | 드롭다운 메뉴 |
+| `toast` / `Toaster` | 토스트 알림 (`Toaster`를 앱 루트에 두고 `toast()` 호출) |
+
+### 테이블
+
+| 컴포넌트      | 설명                                  |
+| ------------- | ------------------------------------- |
+| `AgGridTable` | AG Grid 테이블 (T3Q-UI 스타일 적용됨) |
+| `Table`       | 기본 HTML 테이블 래퍼                 |
+
+### 기타
+
+| 컴포넌트     | 설명          |
+| ------------ | ------------- |
+| `Card`       | 카드 컨테이너 |
+| `Tabs`       | 탭            |
+| `Skeleton`   | 로딩 스켈레톤 |
+| `Spinner`    | 로딩 스피너   |
+| `Progress`   | 진행 바       |
+| `Calendar`   | 캘린더        |
+| `DatePicker` | 날짜 선택     |
+
+---
+
+## 자주 쓰는 예시
+
+### Button
+
+```jsx
+import { Button } from '@t3q-ui/design-system'
+
+// 기본 버튼들
+<Button variant="primaryBold">주요 액션</Button>
+<Button variant="primary">일반 액션</Button>
+<Button variant="secondary">보조 액션</Button>
+<Button variant="danger">삭제</Button>
+
+// 로딩 상태
+<Button variant="primaryBold" loading>저장 중...</Button>
+
+// 비활성화
+<Button disabled>비활성화</Button>
+```
+
+### Badge
+
+```jsx
+import { Badge } from '@t3q-ui/design-system'
+
+<Badge variant="success">성공</Badge>
+<Badge variant="danger">실패</Badge>
+<Badge variant="warning">주의</Badge>
+<Badge variant="info">정보</Badge>
+<Badge variant="primary">기본</Badge>
+```
+
+### Dialog (모달)
+
+```jsx
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from '@t3q-ui/design-system'
+
+;<Dialog>
+  <DialogTrigger asChild>
+    <Button>열기</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>제목</DialogTitle>
+    </DialogHeader>
+    <p>내용</p>
+  </DialogContent>
+</Dialog>
+```
+
+### AlertDialog
+
+`AlertDialogAction`의 `variant`를 생략하면 `AlertDialog`의 `variant`에 따라 아래 버튼 variant로 폴백됩니다.
+
+| `AlertDialog`의 variant  | `AlertDialogAction` 폴백 |
+| ------------------------ | ------------------------ |
+| `variant="success"`      | `primaryBold`            |
+| `variant="info"` (기본값) | `primaryBold`            |
+| `variant="warning"`      | `warningBold`            |
+| `variant="danger"`       | `dangerBold`             |
+
+폴백은 전부 Bold 계열이므로, `variant`를 직접 명시하면 폴백보다 한 톤 낮은 버튼이 됩니다(예: `variant="primary"`).
+
+### AgGridTable
+
+```jsx
+import { AgGridTable } from '@t3q-ui/design-system'
+
+const columns = [
+  { field: 'name', headerName: '이름' },
+  { field: 'status', headerName: '상태' },
+]
+
+const data = [
+  { name: 'Kafka', status: 'Running' },
+  { name: 'Spark', status: 'Stopped' },
+]
+
+<AgGridTable
+  columnDefs={columns}
+  rowData={data}
+  domLayout="autoHeight"
+/>
+
+// 주의: ag-theme-alpine 같은 legacy 테마 className을 직접 붙이지 마세요.
+// v33 Theming API를 내부 기본값으로 사용합니다.
+```
+
+---
+
+## 문제 해결
+
+먼저 `pnpm exec t3q-design doctor` 를 돌립니다. 실패 항목마다 조치가 같이 나옵니다.
+
+### "Cannot find module '@t3q-ui/design-system/styles.css'"
+
+T3Q-UI 버전이 오래됐을 수 있습니다.
+
+```bash
+npm update @t3q-ui/design-system
+```
+
+### AG Grid 스타일이 안 먹어요
+
+1. `@t3q-ui/design-system/styles.css`가 `index.css` **이후에** import 되는지 확인
+2. `@t3q-ui/design-system/fonts.css` import 여부 확인
+3. `AgGridReact` 대신 `AgGridTable` 사용
+4. `AgGridTable`에 `ag-theme-*` className을 직접 전달하지 않기
+
+```jsx
+// ❌
+import { AgGridReact } from 'ag-grid-react'
+
+// ✅
+import { AgGridTable } from '@t3q-ui/design-system'
+```
+
+---
+
+## 유틸리티 함수
+
+### cn()
+
+Tailwind 클래스를 조건부로 합치는 함수:
+
+```jsx
+import { cn } from '@t3q-ui/design-system'
+
+;<div className={cn('p-4 rounded', isActive && 'bg-blue-500', isDisabled && 'opacity-50')} />
+```
+
+---
+
+# 개발자 가이드
+
+> 아래 내용은 T3Q-UI를 **유지보수하거나 수정**하는 개발자를 위한 내용입니다.
+
+## 로컬 개발 (npm link)
+
+T3Q-UI 코드를 수정하면서 다른 프로젝트에서 바로 테스트하고 싶을 때:
+
+```bash
+# 1. T3Q-UI 폴더에서 link 생성
+cd /path/to/t3q-ui
+npm link
+
+# 2. 테스트할 프로젝트에서 link 연결
+cd /path/to/my-project
+npm link @t3q-ui/design-system
+
+# 3. T3Q-UI 폴더에서 watch 모드 실행
+cd /path/to/t3q-ui
+npm run dev
+```
+
+이제 T3Q-UI 코드 수정하면 프로젝트에 바로 반영됩니다.
+
+### link 해제
+
+```bash
+cd /path/to/my-project
+npm unlink @t3q-ui/design-system
+npm install @t3q-ui/design-system  # registry 버전으로 재설치
+```
+
+### link 상태 확인
+
+```bash
+ls -la node_modules/@t3q-ui/design-system
+# lrwxr-xr-x ... -> /path/to/t3q-ui  ← link 상태
+# drwxr-xr-x ...                   ← 일반 설치
+```
+
+---
+
+## 배포
+
+### 배포용 토큰 발급
+
+배포하려면 `write_registry` 권한이 필요합니다.
+
+GitLab → Preferences → Access Tokens에서:
+
+- Scopes: `api`, `write_registry` 체크
+
+### 스크립트로 배포 (권장)
+
+배포 스크립트를 사용하면 빌드, 버전 업데이트, 배포, Git push가 자동으로 처리됩니다.
+
+**macOS / Linux:**
+
+```bash
+# patch 버전 배포 (0.1.6 → 0.1.7)
+./publish.sh
+
+# minor 버전 배포 (0.1.6 → 0.2.0)
+./publish.sh minor
+
+# major 버전 배포 (0.1.6 → 1.0.0)
+./publish.sh major
+```
+
+**Windows:**
+
+```cmd
+# patch 버전 배포
+publish.bat
+
+# minor 버전 배포
+publish.bat minor
+
+# major 버전 배포
+publish.bat major
+```
+
+> **스크립트 동작 순서:**
+>
+> 1. 커밋되지 않은 변경사항 확인 → 커밋 유도
+> 2. 빌드 (`npm run build` + `npm run build:css`)
+> 3. 버전 업데이트 + 태그 생성
+> 4. GitLab npm 레지스트리에 배포
+> 5. Git push + 태그 push
+
+### 수동 배포
+
+스크립트 없이 수동으로 배포하려면:
+
+```bash
+# 버전 올리기
+npm version patch   # 0.1.1 → 0.1.2
+
+# 배포
+GITLAB_TOKEN="토큰" npm publish
+
+# Git push
+git push && git push --tags
+```
+
+### 배포 확인
+
+```bash
+npm view @t3q-ui/design-system version
+```
+
+---
+
+## Storybook
+
+컴포넌트 개발 및 문서화를 위한 Storybook을 제공합니다.
+
+```bash
+# Storybook 실행 (Local)
+npm run storybook
+```
+
+실행 후 `http://localhost:6006`에서 확인할 수 있습니다.
+
+---
+
+## 프로젝트 구조
+
+```
+t3q-ui/
+├── src/
+│   ├── index.ts           # 메인 export
+│   ├── components/        # 컴포넌트들
+│   ├── utils/cn.ts        # 유틸리티
+│   └── styles/tokens.css  # CSS 변수 (@theme 블록)
+├── dist/                  # 빌드 결과물
+├── postcss.config.cjs     # PostCSS 설정
+└── package.json
+```
+
+---
+
+## 라이선스
+
+T3Q와 계약한 프로젝트와 그 유지보수에 한해 사용할 수 있습니다. 전문은 [LICENSE.md](./LICENSE.md) 를 보세요.