vibe-spec-overlay 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +138 -59
  2. package/dist/index.es.js +554 -555
  3. package/dist/index.umd.js +2 -2
  4. package/package.json +11 -1
package/README.md CHANGED
@@ -1,73 +1,152 @@
1
- # React + TypeScript + Vite
1
+ # vibe-spec-overlay-lib
2
2
 
3
- This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
3
+ React 애플리케이션의 UI 컴포넌트 위에 기획/스펙 명세(Feature Spec)를 오버레이로 띄워주고, 상세 스펙을 패널로 확인할 수 있게 해주는 라이브러리입니다.
4
4
 
5
- Currently, two official plugins are available:
5
+ 기획서나 명세서를 따로 찾아보지 않고도 화면에 구현된 컴포넌트의 요구사항, 입력/출력값, 검증 로직, 예외 케이스 등을 개발 중 직관적으로 확인할 수 있도록 도와줍니다.
6
6
 
7
- - [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
8
- - [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
7
+ ## 주요 기능
8
+ - **스펙 오버레이**: `SpecAnchor`로 컴포넌트를 감싸면, 마우스 호버 시 툴팁과 팝오버를 통해 간단한 스펙 정보를 보여줍니다.
9
+ - **상세 스펙 패널**: 앵커를 클릭하면 `SpecPanel`이 열리며, 계층 구조(상위-하위 스펙)를 포함한 상세 명세(입출력, 검증, 예외 상황)를 보여줍니다.
10
+ - **전역 On/Off**: `SpecProvider`에서 제공하는 컨텍스트를 통해 오버레이 기능을 전체적으로 켜거나 끌 수 있습니다.
11
+ - **계층형 스펙 관리**: `parentId`를 통해 상위 스펙과 하위 스펙을 연결하여, 상위 스펙의 속성까지 한 번에 조회할 수 있습니다.
9
12
 
10
- ## React Compiler
13
+ ## 설치
11
14
 
12
- The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
15
+ ```bash
16
+ npm install vibe-spec-overlay-lib
17
+ # 또는
18
+ yarn add vibe-spec-overlay-lib
19
+ ```
20
+
21
+ > **참고**: 이 라이브러리는 `@mui/material`과 `@mui/icons-material`에 의존성이 있습니다. 프로젝트에 Material UI가 설치되어 있어야 정상 작동합니다.
13
22
 
14
- ## Expanding the ESLint configuration
23
+ ## 사용법
15
24
 
16
- If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
25
+ ### 1. Spec 데이터 정의 (`FeatureSpec`)
17
26
 
18
- ```js
19
- export default defineConfig([
20
- globalIgnores(['dist']),
21
- {
22
- files: ['**/*.{ts,tsx}'],
23
- extends: [
24
- // Other configs...
27
+ 먼저 화면에 표시할 기능 명세 데이터를 정의합니다. `id`와 `title`, `description`은 필수입니다.
25
28
 
26
- // Remove tseslint.configs.recommended and replace with this
27
- tseslint.configs.recommendedTypeChecked,
28
- // Alternatively, use this for stricter rules
29
- tseslint.configs.strictTypeChecked,
30
- // Optionally, add this for stylistic rules
31
- tseslint.configs.stylisticTypeChecked,
29
+ ```typescript
30
+ import { FeatureSpec } from 'vibe-spec-overlay-lib';
32
31
 
33
- // Other configs...
34
- ],
35
- languageOptions: {
36
- parserOptions: {
37
- project: ['./tsconfig.node.json', './tsconfig.app.json'],
38
- tsconfigRootDir: import.meta.dirname,
39
- },
40
- // other options...
41
- },
32
+ export const mySpecs: Record<string, FeatureSpec> = {
33
+ login_form: {
34
+ id: 'login_form',
35
+ title: '로그인 폼',
36
+ description: '사용자 로그인을 처리하는 폼 컴포넌트입니다.',
37
+ inputs: ['이메일', '비밀번호'],
38
+ outputs: ['로그인 성공 여부 및 토큰'],
39
+ edgeCases: ['네트워크 지연 시 로딩 표시'],
40
+ priority: 'high',
42
41
  },
43
- ])
42
+ email_input: {
43
+ id: 'email_input',
44
+ parentId: 'login_form', // 상위 스펙과 연결
45
+ title: '이메일 입력 필드',
46
+ description: '이메일 형식을 검증받는 입력란입니다.',
47
+ validation: ['이메일 형식 정규식 통과 필요'],
48
+ priority: 'medium',
49
+ }
50
+ };
44
51
  ```
45
52
 
46
- You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
47
-
48
- ```js
49
- // eslint.config.js
50
- import reactX from 'eslint-plugin-react-x'
51
- import reactDom from 'eslint-plugin-react-dom'
52
-
53
- export default defineConfig([
54
- globalIgnores(['dist']),
55
- {
56
- files: ['**/*.{ts,tsx}'],
57
- extends: [
58
- // Other configs...
59
- // Enable lint rules for React
60
- reactX.configs['recommended-typescript'],
61
- // Enable lint rules for React DOM
62
- reactDom.configs.recommended,
63
- ],
64
- languageOptions: {
65
- parserOptions: {
66
- project: ['./tsconfig.node.json', './tsconfig.app.json'],
67
- tsconfigRootDir: import.meta.dirname,
68
- },
69
- // other options...
70
- },
71
- },
72
- ])
53
+ ### 2. Provider와 Panel 설정
54
+
55
+ 앱의 최상단(혹은 스펙을 오버레이할 영역의 최상단)에 `SpecProvider`를 감싸고 `specsMap` 데이터를 주입합니다.
56
+ 화면에 스펙 상세를 보여줄 `SpecPanel` 컴포넌트도 렌더링해 줍니다.
57
+
58
+ ```tsx
59
+ import React from 'react';
60
+ import { SpecProvider, SpecPanel } from 'vibe-spec-overlay-lib';
61
+ import { mySpecs } from './specs';
62
+ import AppContent from './AppContent';
63
+
64
+ function App() {
65
+ return (
66
+ <SpecProvider specsMap={mySpecs}>
67
+ {/* 실제 앱 콘텐츠 */}
68
+ <AppContent />
69
+
70
+ {/* 상세 스펙을 보여주는 사이드 패널 */}
71
+ <SpecPanel />
72
+ </SpecProvider>
73
+ );
74
+ }
75
+
76
+ export default App;
77
+ ```
78
+
79
+ ### 3. 화면 컴포넌트에 SpecAnchor 적용
80
+
81
+ 스펙 명세를 연결할 UI 요소에 `SpecAnchor`를 감싸고 `spec` 객체를 전달합니다.
82
+
83
+ ```tsx
84
+ import React from 'react';
85
+ import { SpecAnchor } from 'vibe-spec-overlay-lib';
86
+ import { mySpecs } from './specs';
87
+
88
+ function AppContent() {
89
+ return (
90
+ <div style={{ padding: '20px' }}>
91
+ <SpecAnchor spec={mySpecs.login_form}>
92
+ <form style={{ border: '1px solid #ccc', padding: '20px' }}>
93
+ <h2>로그인</h2>
94
+
95
+ <SpecAnchor spec={mySpecs.email_input}>
96
+ <div>
97
+ <label>이메일</label>
98
+ <input type="email" placeholder="이메일 입력" />
99
+ </div>
100
+ </SpecAnchor>
101
+
102
+ {/* ... */}
103
+ </form>
104
+ </SpecAnchor>
105
+ </div>
106
+ );
107
+ }
108
+
109
+ export default AppContent;
110
+ ```
111
+
112
+ ## API 명세
113
+
114
+ ### `SpecProvider`
115
+
116
+ - `specsMap`: 전체 스펙 데이터를 가지고 있는 객체 (`Record<string, FeatureSpec>`)
117
+
118
+ ### `SpecAnchor`
119
+
120
+ - `spec`: 감싸고 있는 요소에 해당하는 `FeatureSpec` 객체
121
+
122
+ ### `useSpecContext`
123
+
124
+ 훅을 통해 스펙 오버레이 상태를 제어할 수 있습니다.
125
+
126
+ ```typescript
127
+ const {
128
+ enabled, // 오버레이 활성화 여부
129
+ toggleEnabled, // 활성화 여부 토글 함수
130
+ selected, // 현재 선택된 스펙 (SpecPanel에 표시 중인 스펙)
131
+ setSelected, // 특정 스펙 선택 (또는 undefined로 패널 닫기)
132
+ specsMap // 주입된 전체 스펙 맵
133
+ } = useSpecContext();
134
+ ```
135
+
136
+ ### `FeatureSpec` 인터페이스
137
+
138
+ ```typescript
139
+ export type Priority = 'low' | 'medium' | 'high'
140
+
141
+ export interface FeatureSpec {
142
+ id: string
143
+ parentId?: string
144
+ title: string
145
+ description: string
146
+ inputs?: string[]
147
+ outputs?: string[]
148
+ validation?: string[]
149
+ edgeCases?: string[]
150
+ priority?: Priority
151
+ }
73
152
  ```