vibe-spec-overlay 0.1.0 → 0.1.2

package/README.md

@@ -1,73 +1,152 @@
-# React + TypeScript + Vite
+# vibe-spec-overlay-lib
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+React 애플리케이션의 UI 컴포넌트 위에 기획/스펙 명세(Feature Spec)를 오버레이로 띄워주고, 상세 스펙을 패널로 확인할 수 있게 해주는 라이브러리입니다.
 
-Currently, two official plugins are available:
+기획서나 명세서를 따로 찾아보지 않고도 화면에 구현된 컴포넌트의 요구사항, 입력/출력값, 검증 로직, 예외 케이스 등을 개발 중 직관적으로 확인할 수 있도록 도와줍니다.
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+## 주요 기능
+- **스펙 오버레이**: `SpecAnchor`로 컴포넌트를 감싸면, 마우스 호버 시 툴팁과 팝오버를 통해 간단한 스펙 정보를 보여줍니다.
+- **상세 스펙 패널**: 앵커를 클릭하면 `SpecPanel`이 열리며, 계층 구조(상위-하위 스펙)를 포함한 상세 명세(입출력, 검증, 예외 상황)를 보여줍니다.
+- **전역 On/Off**: `SpecProvider`에서 제공하는 컨텍스트를 통해 오버레이 기능을 전체적으로 켜거나 끌 수 있습니다.
+- **계층형 스펙 관리**: `parentId`를 통해 상위 스펙과 하위 스펙을 연결하여, 상위 스펙의 속성까지 한 번에 조회할 수 있습니다.
 
-## React Compiler
+## 설치
 
-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).
+```bash
+npm install vibe-spec-overlay-lib
+# 또는
+yarn add vibe-spec-overlay-lib
+```
+
+> **참고**: 이 라이브러리는 `@mui/material`과 `@mui/icons-material`에 의존성이 있습니다. 프로젝트에 Material UI가 설치되어 있어야 정상 작동합니다.
 
-## Expanding the ESLint configuration
+## 사용법
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+### 1. Spec 데이터 정의 (`FeatureSpec`)
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+먼저 화면에 표시할 기능 명세 데이터를 정의합니다. `id`와 `title`, `description`은 필수입니다.
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+```typescript
+import { FeatureSpec } from 'vibe-spec-overlay-lib';
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
+export const mySpecs: Record<string, FeatureSpec> = {
+  login_form: {
+    id: 'login_form',
+    title: '로그인 폼',
+    description: '사용자 로그인을 처리하는 폼 컴포넌트입니다.',
+    inputs: ['이메일', '비밀번호'],
+    outputs: ['로그인 성공 여부 및 토큰'],
+    edgeCases: ['네트워크 지연 시 로딩 표시'],
+    priority: 'high',
   },
-])
+  email_input: {
+    id: 'email_input',
+    parentId: 'login_form', // 상위 스펙과 연결
+    title: '이메일 입력 필드',
+    description: '이메일 형식을 검증받는 입력란입니다.',
+    validation: ['이메일 형식 정규식 통과 필요'],
+    priority: 'medium',
+  }
+};
 ```
 
-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:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+### 2. Provider와 Panel 설정
+
+앱의 최상단(혹은 스펙을 오버레이할 영역의 최상단)에 `SpecProvider`를 감싸고 `specsMap` 데이터를 주입합니다.
+화면에 스펙 상세를 보여줄 `SpecPanel` 컴포넌트도 렌더링해 줍니다.
+
+```tsx
+import React from 'react';
+import { SpecProvider, SpecPanel } from 'vibe-spec-overlay-lib';
+import { mySpecs } from './specs';
+import AppContent from './AppContent';
+
+function App() {
+  return (
+    <SpecProvider specsMap={mySpecs}>
+      {/* 실제 앱 콘텐츠 */}
+      <AppContent />
+      
+      {/* 상세 스펙을 보여주는 사이드 패널 */}
+      <SpecPanel />
+    </SpecProvider>
+  );
+}
+
+export default App;
+```
+
+### 3. 화면 컴포넌트에 SpecAnchor 적용
+
+스펙 명세를 연결할 UI 요소에 `SpecAnchor`를 감싸고 `spec` 객체를 전달합니다.
+
+```tsx
+import React from 'react';
+import { SpecAnchor } from 'vibe-spec-overlay-lib';
+import { mySpecs } from './specs';
+
+function AppContent() {
+  return (
+    <div style={{ padding: '20px' }}>
+      <SpecAnchor spec={mySpecs.login_form}>
+        <form style={{ border: '1px solid #ccc', padding: '20px' }}>
+          <h2>로그인</h2>
+          
+          <SpecAnchor spec={mySpecs.email_input}>
+            <div>
+              <label>이메일</label>
+              <input type="email" placeholder="이메일 입력" />
+            </div>
+          </SpecAnchor>
+
+          {/* ... */}
+        </form>
+      </SpecAnchor>
+    </div>
+  );
+}
+
+export default AppContent;
+```
+
+## API 명세
+
+### `SpecProvider`
+
+- `specsMap`: 전체 스펙 데이터를 가지고 있는 객체 (`Record<string, FeatureSpec>`)
+
+### `SpecAnchor`
+
+- `spec`: 감싸고 있는 요소에 해당하는 `FeatureSpec` 객체
+
+### `useSpecContext`
+
+훅을 통해 스펙 오버레이 상태를 제어할 수 있습니다.
+
+```typescript
+const { 
+  enabled,          // 오버레이 활성화 여부
+  toggleEnabled,    // 활성화 여부 토글 함수
+  selected,         // 현재 선택된 스펙 (SpecPanel에 표시 중인 스펙)
+  setSelected,      // 특정 스펙 선택 (또는 undefined로 패널 닫기)
+  specsMap          // 주입된 전체 스펙 맵
+} = useSpecContext();
+```
+
+### `FeatureSpec` 인터페이스
+
+```typescript
+export type Priority = 'low' | 'medium' | 'high'
+
+export interface FeatureSpec {
+  id: string
+  parentId?: string
+  title: string
+  description: string
+  inputs?: string[]
+  outputs?: string[]
+  validation?: string[]
+  edgeCases?: string[]
+  priority?: Priority
+}
 ```

package/dist/index.d.ts

@@ -1 +1,93 @@
-export {}
+import { JSX } from 'react/jsx-runtime';
+import { PropsWithChildren } from 'react';
+
+/**
+ * 기능 스펙을 정의하는 핵심 인터페이스입니다.
+ * UI의 특정 부분에 대한 요구사항, 입력/출력, 예외 케이스 등을 포함합니다.
+ */
+export declare interface FeatureSpec {
+    /** 스펙의 고유 식별자 (예: 'user-profile-01') */
+    id: string;
+    /** 부모 스펙의 ID. 스펙 체인(계층 구조)을 형성할 때 사용합니다. */
+    parentId?: string;
+    /** 사용자 또는 개발자에게 표시될 기능의 제목 */
+    title: string;
+    /** 기능에 대한 상세 설명 */
+    description: string;
+    /** 해당 기능에 필요한 입력값 목록 (예: ['username', 'password']) */
+    inputs?: string[];
+    /** 해당 기능의 결과로 발생하는 출력값 또는 상태 변화 (예: ['login-success', 'auth-token']) */
+    outputs?: string[];
+    /** 데이터 유효성 검사 규칙 (예: ['비밀번호 8자 이상', '특수문자 포함']) */
+    validation?: string[];
+    /** 발생 가능한 예외 상황 또는 엣지 케이스 (예: ['네트워크 단절', '중복 아이디']) */
+    edgeCases?: string[];
+    /** 기능의 우선순위 */
+    priority?: Priority;
+}
+
+/**
+ * 기능의 중요도 또는 우선순위를 나타냅니다.
+ * AI가 UI 요소를 렌더링하거나 필터링할 때 참고할 수 있습니다.
+ */
+export declare type Priority = 'low' | 'medium' | 'high';
+
+/**
+ * 특정 UI 요소에 스펙 정보를 시각적으로 연결하는 래퍼 컴포넌트입니다.
+ * 마우스 호버 시 외곽선과 툴팁을 표시하고, 클릭 시 상세 스펙 정보를 Drawer로 엽니다.
+ *
+ * @example
+ * <SpecAnchor spec={{ id: 'submit-01', title: '전송 버튼', description: '데이터를 서버로 전송합니다.' }}>
+ *   <Button>저장</Button>
+ * </SpecAnchor>
+ */
+export declare function SpecAnchor({ spec, children }: SpecAnchorProps): JSX.Element;
+
+/**
+ * SpecAnchor의 Props 인터페이스입니다.
+ */
+declare interface SpecAnchorProps extends PropsWithChildren {
+    /**
+     * 앵커가 나타내는 기능의 스펙 정보입니다.
+     * 이 정보를 기반으로 툴팁과 상세 패널이 구성됩니다.
+     */
+    spec: FeatureSpec;
+}
+
+export declare function SpecPanel(): JSX.Element;
+
+/**
+ * 프로젝트 전체 또는 특정 범위 내의 스펙 상태를 관리하는 컨텍스트 프로바이더입니다.
+ * 활성화 여부, 현재 선택된 스펙, 호버 상태 등을 관리합니다.
+ *
+ * @example
+ * <SpecProvider specsMap={{ 'login-btn': { title: '로그인 버튼', ... } }}>
+ *   <App />
+ * </SpecProvider>
+ */
+export declare function SpecProvider({ children, specsMap }: SpecProviderProps): JSX.Element;
+
+/**
+ * SpecProvider의 Props 인터페이스입니다.
+ */
+declare interface SpecProviderProps extends PropsWithChildren {
+    /**
+     * 스펙 ID를 키로, FeatureSpec 객체를 값으로 가지는 매핑 정보입니다.
+     * SpecAnchor에서 전달받은 스펙 정보를 보완하거나 계층 구조를 관리할 때 사용됩니다.
+     */
+    specsMap?: Record<string, FeatureSpec>;
+}
+
+declare interface SpecState {
+    enabled: boolean;
+    toggleEnabled: () => void;
+    selected?: FeatureSpec;
+    setSelected: (spec?: FeatureSpec) => void;
+    specsMap: Record<string, FeatureSpec>;
+    hoveredSpecId: string | null;
+    setHoveredSpecId: (id: string | null) => void;
+}
+
+export declare function useSpecContext(): SpecState;
+
+export { }