@designfever/web-review-kit 0.5.0 → 0.7.0

package/docs/release-notes-0.6.0.md

@@ -0,0 +1,108 @@
+# 릴리즈 노트: 0.6.0
+
+0.5.0 release 이후 변경 사항 정리.
+
+비교 기준: `0.5.0`
+검토 기준: 0.6.0 dogfood working tree (`Source Tree` metadata, docked QA composer, Lexus mobile/WebKit flow 포함)
+
+## 주요 변경
+
+- DOM/area draft composer를 QA panel 하단 dock 방식으로 바꿔 mobile viewport/keyboard resize 영향을 줄였다.
+- Source Tree를 component inspection tool로 확장했다.
+- Source Tree box/text/font/media/class metadata 표시를 추가했다.
+- Source Tree, QA panel, QA status filter 상태를 browser localStorage에 유지한다.
+- QA list ID capsule click-to-copy, toolbar/header spacing, icon button density를 정리했다.
+- Lexus dogfood에서 local package 연결, 540x1080 mobile viewport, LAN preview 흐름을 확인했다.
+
+## 변경
+
+### Docked QA Composer
+
+React shell mode에서 DOM/area draft composer는 target 위 floating layer 대신 QA list 하단에 붙는다.
+
+- mobile Safari input focus/viewport resize에 덜 흔들리는 구조
+- DOM selection adjustment controls 유지
+- area selection draft도 같은 host 영역 사용
+- draft composer가 열리면 QA panel로 focus 이동
+
+Core standalone overlay mode는 기존처럼 target overlay 안에서 composer를 렌더링한다.
+
+### Source Tree Metadata
+
+Source Tree row에 inspection metadata를 표시할 수 있게 했다.
+
+- box: target iframe 기준 `top / left / width / height`
+- text: PlacerTextInline 등 text node 값
+- font: font size/weight summary
+- media: image/poster/video URL, desktop/mobile asset label
+- class: className tag list
+
+Box 값은 render 시점의 iframe element rect를 다시 읽어서 viewport/resolution 변경 후에도 최신 값에 맞춘다.
+
+### Source Tree Controls
+
+Source Tree header/filter layout을 QA sheet와 맞췄고, metadata option은 icon-only toggle로 정리했다.
+
+- filter input을 최상단에 배치
+- root count와 metadata toggles를 같은 header row에 배치
+- Source Tree를 켤 때 parent tree nodes는 기본 collapsed 상태로 시작
+- row hover 영역은 metadata block까지 포함
+- row의 DOM select action은 QA panel로 전환한 뒤 draft 작성 흐름을 시작
+
+### QA List
+
+- `DRAFT-1`, `#102` 같은 QA ID capsule을 누르면 ID가 copy된다.
+- Local QA title case/color와 list/header spacing을 정리했다.
+- QA status filter 선택값을 새로고침 후에도 유지한다.
+- side panel mode와 panel open/close 상태를 새로고침/페이지 이동 후에도 유지한다.
+
+## Persistence
+
+0.6.0에서 shell UI state는 browser-local localStorage에 저장된다.
+
+- `df-review-side-panel`
+- `df-review-side-panel-visible`
+- `df-review-source-tree-filter`
+- `df-review-source-tree-meta-visibility`
+- `df-review-qa-status-filter`
+
+이 값들은 QA item data가 아니며, adapter나 backend로 sync되지 않는다.
+
+## Host 적용 메모
+
+### Lexus dogfood integration
+
+- `lexus_official_v2026`에서 `@designfever/web-review-kit`을 `file:../df-web-review-kit`로 연결해 검증했다.
+- review dev server는 LAN 접근을 위해 `--host 0.0.0.0`로 띄워 mobile device에서 확인했다.
+- 540x1080 mobile preset에서 DOM QA composer 입력/저장/취소, Source Tree metadata toggles, QA status filter persistence를 확인했다.
+
+## 문서
+
+- README에 0.6.0 release note link와 Source Tree metadata/persistence 설명을 추가했다.
+- Installation docs에 docked composer, Source Tree metadata, localStorage persistence 설명을 추가했다.
+- Architecture docs에 React shell composer host boundary를 추가했다.
+- 오래된 internal handoff note를 삭제했다.
+
+## 검증
+
+아래 명령을 확인했다.
+
+- `pnpm typecheck`
+- `pnpm typecheck:dev`
+- `pnpm build`
+- `pnpm build:dev`
+- `git diff --check`
+- `npm pack --dry-run --json`
+
+수동 확인:
+
+- Lexus dogfood review page DOM QA create/cancel
+- Source Tree filter/meta toggle persistence
+- QA status filter persistence
+- mobile/LAN preview
+
+## 메모
+
+- `package.json` version은 `0.6.0`이다.
+- npm publish 전에는 registry login 상태를 확인해야 한다.
+- Lexus target app에서 React SVG prop warning(`fill-rule`, `clip-rule`)이 보일 수 있으나 review-kit package warning은 아니다.

package/docs/release-notes-0.7.0.md

@@ -0,0 +1,128 @@
+# 릴리즈 노트: 0.7.0
+
+0.6.0 release 이후 변경 사항 정리.
+
+비교 기준: `0.6.0`
+검토 기준: `main` release candidate
+
+## 주요 변경
+
+- Figma reference image workflow를 review shell 안으로 옮겼다.
+- Figma image local cache와 Vite plugin helper를 추가했다.
+- QA 작성 필드를 `fields` option으로 확장해 title을 선택적으로 받을 수 있게 했다.
+- QA item에 optional assignee 표시/변경 flow를 추가했다.
+- 느린 remote adapter, 특히 df-sheet 연동에서 list/create/update/delete pending 상태를 UI로 표시한다.
+- deep link item restore와 QA list focus 위치 보정을 개선했다.
+- right rail Figma icon stroke를 다른 rail icon과 분리해 맞췄다.
+- 릴리즈 직전 QA mutation failure feedback과 Figma image target key 보정을 반영했다.
+- Sitemap modal에 페이지 검색 필터를 추가했다.
+- Sitemap tree row를 ASCII prefix 대신 접기/펼치기 가능한 folder explorer 형태로 바꿨다.
+- Sitemap tree depth를 더 빨리 읽을 수 있게 indent 영역에 subtle guide line을 추가했다.
+- Sitemap tree guide line을 folder caret 중앙축에 맞추고 body row divider 대신 hover/active block highlight를 사용하도록 정리했다.
+- Sitemap body row 높이를 줄이고 상태 컬럼을 Todo/Review/Hold count 중심으로 정리했다.
+
+## 변경
+
+### Figma Image Workflow
+
+review shell에서 Figma reference image를 등록하고 target page 위에 overlay로 올릴 수 있게 했다.
+
+- dev server plugin이 Figma API 호출과 local asset cache를 담당한다.
+- Figma token은 server env의 `FIGMA_TOKEN`을 사용하고 browser bundle로 노출하지 않는다.
+- metadata는 `.df-review/figma-images.json`, asset은 `.df-review/figma-assets/`에 저장한다.
+- review shell에서는 image manager panel과 layer controls를 제공한다.
+- 일반 route에서는 host가 연결한 overlay control만 사용할 수 있게 boundary를 분리했다.
+
+### QA Fields
+
+adapter option에 `fields`를 추가했다.
+
+- `fields.title`이 true일 때만 QA 작성/수정 화면에 title input을 표시한다.
+- title은 optional field이며 없으면 기존 comment-only 작성 흐름을 유지한다.
+- local fallback에는 assignee sample을 넣지 않고 host adapter가 필요한 field만 선언한다.
+
+### Assignee
+
+status와 분리된 optional assignee flow를 추가했다.
+
+- `assigneeTitle`로 select label을 host가 지정할 수 있다.
+- `assigneeOptions`로 담당자 목록을 넣는다.
+- `updateAssignee`가 있는 adapter에서만 list item assignee 변경을 허용한다.
+- edit modal에서는 assignee를 수정하지 않는다.
+
+### Remote Adapter Pending UI
+
+remote adapter가 느릴 때 빈 상태처럼 보이지 않도록 loading/pending feedback을 추가했다.
+
+- QA list 로딩 중 spinner와 loading text를 표시한다.
+- refresh 중에는 refresh button을 disabled + spinner 상태로 둔다.
+- QA 등록/수정/삭제/status/assignee 변경 중에는 item/form 단위 pending 상태를 표시한다.
+- create 실패 시 작성 form에 error message를 표시한다.
+
+### Deep Link Restore
+
+remote list가 늦게 도착하는 경우에도 URL의 `item` query를 복원할 수 있게 보정했다.
+
+- initial item restore를 list loading 이후 한 번 더 시도한다.
+- focus scroll 후 layout/animation 때문에 위치가 틀어지는 케이스를 다시 보정한다.
+- df-sheet처럼 list 응답이 느린 adapter에서 deep link item focus 실패를 줄였다.
+
+### Release Candidate Fixes
+
+- QA status/assignee/submit/delete 실패 시 unhandled rejection으로 남기지 않고 toast로 feedback을 표시한다.
+- QA edit 실패는 toast와 edit modal inline error를 함께 유지한다.
+- Figma image target key가 review shell과 dev overlay에서 query/hash를 포함한 normalized target을 사용하도록 보정했다.
+- Sitemap modal에서 페이지 이름/경로를 검색할 수 있고, 일치하는 하위 page의 상위 folder context를 유지한다.
+- Sitemap folder row는 caret으로 접고 펼칠 수 있으며, 검색 중에는 일치 항목의 상위 folder를 자동으로 펼친다.
+- Sitemap folder depth는 세로 guide line으로 보강해 깊은 경로도 한눈에 구분되게 했다.
+- Sitemap body row divider를 제거하고 hover/active block highlight로 행 구분을 처리한다.
+- Sitemap list는 Total 대신 Todo/Review/Hold state count를 직접 보여준다.
+
+## Host 적용 메모
+
+### Lexus dogfood integration
+
+- Lexus host에서 df-sheet adapter로 title/assignee/status update flow를 확인했다.
+- df-sheet list loading 동안 empty state 대신 loading state가 뜨는지 확인했다.
+- direct URL item restore가 list load 이후 active item을 잡는지 확인했다.
+- Lexus 배포 전에는 `link:../df-web-review-kit`를 published package version으로 바꿔야 한다.
+
+### Vite plugin
+
+Figma image local cache를 쓰는 host는 Vite config에 review-kit plugin helper를 연결해야 한다.
+
+- `reviewFigmaImageStore()`는 dev/local cache endpoint를 제공한다.
+- `FIGMA_TOKEN`은 server env로만 둔다.
+- image format 변환이 필요하면 host가 `sharp` 같은 변환기를 plugin option으로 연결한다.
+
+## 문서
+
+- README quick start에 `fields`, `assigneeTitle`, `assigneeOptions`, `updateAssignee` 예시를 추가했다.
+- custom adapter sample에 optional title/assignee field와 update flow를 추가했다.
+- QA adapter와 Figma image store boundary 문서를 추가했다.
+- Figma image MVP 구조 note를 추가했다.
+
+## 검증
+
+아래 명령을 확인했다.
+
+- `pnpm run typecheck`
+- `pnpm run typecheck:dev`
+- `pnpm run lint:dead-code`
+- `pnpm run build`
+- `pnpm run build:dev`
+- `npm pack --dry-run --json`
+
+수동 확인:
+
+- Lexus dogfood review page에서 df-sheet QA list loading state
+- df-sheet QA create form title field
+- QA list item status/assignee pending state
+- direct URL item restore and focus
+- Figma rail/menu icon stroke
+
+## 메모
+
+- `package.json` version은 `0.7.0`이다.
+- npm publish 전에는 registry login 상태와 latest published version을 확인해야 한다.
+- Lexus target app의 React SVG prop warning(`fill-rule`, `clip-rule`)은 review-kit package warning이 아니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designfever/web-review-kit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Designfever web page review overlay toolkit.",
   "license": "Apache-2.0",
@@ -41,13 +41,15 @@
   "files": [
     "dist",
     "docs",
-    "README.md"
+    "README.md",
+    ".env.sample"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/react-shell.tsx src/vite.ts --format esm,cjs --dts --sourcemap --clean --external react --external react-dom --external react/jsx-runtime",
     "dev": "tsup src/index.ts src/react-shell.tsx src/vite.ts --format esm,cjs --dts --sourcemap --watch --external react --external react-dom --external react/jsx-runtime",
     "dev:review": "vite --config dev/vite.config.ts",
     "build:dev": "vite build --config dev/vite.config.ts",
+    "lint:dead-code": "knip",
     "prepare": "pnpm build",
     "typecheck": "tsc --noEmit",
     "typecheck:dev": "tsc --noEmit -p tsconfig.dev.json"
@@ -64,8 +66,10 @@
   },
   "devDependencies": {
     "@supabase/supabase-js": "^2.108.2",
+    "@types/node": "^26.0.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
+    "knip": "^6.20.0",
     "lucide-react": "^1.20.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",