@hjmds/design-contracts 1.7.0 → 1.8.0

package/docs/virtual-list.md

@@ -1,70 +1,13 @@
-# VirtualList — 계약을 만들지 않는다
+# VirtualList
 
-## 제약
+2026-09-29: 사용자의 미구현 기능 완성 요청으로 고정 높이 행의 가상화 렌더러를 추가했다.
+Web은 보이는 범위와 overscan만 마운트하고, Native는 FlatList에 위임한다. `rowHeight`와
+`height`는 필수이며 가변 높이·페이지 가져오기를 이 API에 섞지 않는다. 콘텐츠와 글자
+배율에 맞는 행 높이는 호스트가 지정하고, 높이를 확정할 수 없으면 기존 List를 사용한다.
 
-`docs/ant-design-coverage.md`의 lifecycle 절이 이미 선언했다 — Ant Design 6.6.1이 기존
-`List`를 deprecated로 두고 `Listy`를 successor로 추가했지만, **HJM은 기존 비가상
-`List`와 planned `VirtualList`를 서로 다른 사용 문제로 유지한다.** 이 문서는 그 선언을
-뒤집지 않는다. 두 catalog row(`List` beta, `VirtualList` planned + `aliases: ["Listy"]`)를
-합치자는 이야기가 아니라, **`VirtualList`가 소유할 계약이 실제로 있는지**를 판정한다.
+Web은 ArrowUp/Down/Home/End로 행을 탐색하고 실제 포커스를 옮긴다. 포커스된 항목은
+스크롤로 가시 범위를 벗어나도 마운트를 유지한다. 필터 결과가 줄면 스크롤 위치를
+새 범위로 제한한다. 전체 개수와 위치는 현재 전달된 배열 기준으로 표시한다.
 
-## 판정: 지금은 아무것도 소유하지 않는다
-
-가상화가 계약이 되려면 "Web과 Native가 각자 다른 구현 기법으로 같은 결과를 낸다"는
-공통 semantic이 있어야 한다(`docs/architecture.md`의 `adaptive` 정의 그대로). 후보를
-셋으로 나눠 각각 판정했다.
-
-### 1. 항목 높이 추정(고정/가변) — 렌더러 기법이다
-
-Web windowing 라이브러리(react-window/virtua류)와 RN `FlatList`는 각자의 windowing
-파라미터(`itemSize`/`overscan` vs `getItemLayout`/`windowSize`/`initialNumToRender`)를
-갖지만 이름도, 단위도, 의미도 서로 대응하지 않는다. Slider의 `min`/`max`/`step`처럼
-두 플랫폼이 같은 사용자 의미를 공유하는 것이 아니라, 각 플랫폼의 렌더링 성능 엔진이
-내부적으로 요구하는 힌트일 뿐이다 — 공유할 semantic이 없다.
-
-### 2. 스크롤 위치 복원 — 가상화 전용 문제가 아니다
-
-가상화하지 않은 평범한 긴 목록도 스크롤 위치 복원이 필요하다(뒤로가기 후 원래 보던
-위치로). 이 문제는 "가상화됐는가"와 독립이고, 스크롤을 소유한 컨테이너/렌더러의 몫이다
-— `VirtualList`라는 이름 아래 있어야 할 이유가 없다.
-
-### 3. 총 개수의 낭독 — 실제로는 이미 있거나, 아직 없다
-
-가상화된 목록은 DOM/네이티브 뷰 트리에 일부만 마운트되므로 스크린 리더가 전체 개수를
-잘못 알 수 있다는 우려는 진짜다. 그런데 이 문제를 나눠보면:
-
-- 전체 데이터가 이미 메모리에 있는 경우(`items.length`를 제품이 이미 안다) — 총
-  개수는 이미 알려진 값이고, `aria-setsize`/`aria-posinset`류를 실제 배열 길이로
-  채우는 것은 렌더러가 창을 마운트할 때 하는 일이다. 이걸 계산하거나 유도할 판단이
-  없다 — Steps/Timeline/Carousel의 `position`/`total`처럼 커서 위치나 유효하지 않은
-  조합을 막는 로직이 있는 게 아니라, 그냥 `.length`를 읽는 일이다.
-- 전체 데이터가 아직 로딩 중인 경우(페이지네이션) — 이건 `src/load-more.ts`가 이미
-  소유한 문제다. `LoadMoreState`는 의도적으로 `totalCount`를 갖지 않는다 — 모르는
-  총합을 지어내는 것이 아무것도 말하지 않는 것보다 나쁘기 때문이다(`idle|loading|
-  loadingMore|error|complete` 중 어느 것도 총 개수를 전제하지 않는다). `VirtualList`가
-  이 자리에 총 개수 축을 새로 만들면 LoadMore가 이미 내린 판단과 충돌한다.
-
-즉 이 문제는 이미 있는 계약(`LoadMore`) 또는 렌더러가 이미 아는 값(`items.length`) 중
-하나로 항상 환원된다 — `VirtualList`가 따로 소유할 몫이 남지 않는다.
-
-## 결론
-
-측정된 제품 요구도 없다 — 로드맵·메모리 어디에도 "List+LoadMore로는 렌더링 성능이
-부족했다"는 vertical slice 기록이 없다. 야잘알의 긴 목록(팀 순위, 선수 검색 결과)은
-이미 List/ListRow + LoadMore 조합으로 충분히 설계돼 있다.
-
-`src/virtual-list.ts`, `test/virtual-list.test.ts`는 만들지 않는다. catalog row(`{ name:
-"VirtualList", category: "data-display", platform: "adaptive", status: "planned",
-aliases: ["Listy"] }`)는 건드리지 않는다 — 이름 자리를 지우자는 것이 아니라, 지금
-채울 계약이 없다는 것이다.
-
-## 뒤집힐 조건
-
-다음 중 하나가 실제로 측정되면 이 판정을 다시 연다.
-
-1. 실제 제품에서 List+LoadMore로 렌더링 성능(프레임 드랍, 초기 마운트 시간)이 측정
-   가능하게 부족한 vertical slice가 나온다.
-2. Web과 Native 렌더러가 **같은 이름의 파라미터**로 반응하는 windowing 설정이 두
-   플랫폼 모두에서 검증돼, 진짜 공유 semantic이 있다고 판단된다.
-3. 총 개수를 알 수 없는 채로 가상화해야 하는 화면이 나와, `LoadMore`의 "총합을 지어내지
-   않는다"는 원칙과 다른 새 발화 규칙이 필요해진다.
+진입점: `@hjmds/react/virtual-list`, `@hjmds/react-native/virtual-list`.
+네트워크 로딩은 기존 LoadMore를 조합한다. Native 재활용·보조기술 스크롤은 FlatList가 소유한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hjmds/design-contracts",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Renderer-neutral design contracts, tokens, recipes, and behaviors shared by HJM products.",
   "license": "MIT",
   "repository": {
@@ -133,6 +133,12 @@
     "./consumer-policy.md": {
       "default": "./docs/consumer-policy.md"
     },
+    "./components/thinking-orb": {
+      "types": "./dist/thinking-orb.d.ts",
+      "react-native": "./dist/thinking-orb.js",
+      "import": "./dist/thinking-orb.js",
+      "default": "./dist/thinking-orb.js"
+    },
     "./components/agreement": {
       "types": "./dist/agreement.d.ts",
       "react-native": "./dist/agreement.js",
@@ -522,21 +528,42 @@
       "react-native": "./dist/showcase.js",
       "import": "./dist/showcase.js",
       "default": "./dist/showcase.js"
+    },
+    "./components/masonry": {
+      "types": "./dist/masonry.d.ts",
+      "react-native": "./dist/masonry.js",
+      "import": "./dist/masonry.js",
+      "default": "./dist/masonry.js"
+    },
+    "./components/virtual-list": {
+      "types": "./dist/virtual-list.d.ts",
+      "react-native": "./dist/virtual-list.js",
+      "import": "./dist/virtual-list.js",
+      "default": "./dist/virtual-list.js"
+    },
+    "./components/qr-code": {
+      "types": "./dist/qr-code.d.ts",
+      "react-native": "./dist/qr-code.js",
+      "import": "./dist/qr-code.js",
+      "default": "./dist/qr-code.js"
     }
   },
   "files": [
     "dist",
     "docs",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "engines": {
     "node": ">=20"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
+    "jsqr": "1.4.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "qrcode-generator": "2.0.4"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/docs/app-provider.md

@@ -1,50 +0,0 @@
-# AppProvider — 새 컴포넌트를 만들지 않는다
-
-## 문제로 제기된 것
-
-antd `App`은 `message`/`notification`/`Modal`을 **명령형 훅**(`App.useApp()`)으로
-어디서든 부를 수 있게 context를 심어 주는 컴포넌트다 — 정적 `Modal.confirm()` 같은
-호출이 실제로는 테마·locale context에 접근할 수 있도록 antd가 마련한 배선이다.
-
-## 판정: 런타임을 걷어내면 아무것도 남지 않는다
-
-`App`이 명령형으로 여는 세 가지는 이미 전부 다른 HJM 계약에 배정돼 있다.
-
-| antd `App`이 여는 것 | HJM 대응 | 상태 |
-| --- | --- | --- |
-| `message` | `Toast` | 이미 계약, `beta` |
-| `notification` | `Toast`(`docs/notification.md`가 이미 alias로 흡수) | 이미 계약 |
-| `Modal.confirm`/`Modal.info` 등 | `Dialog`/`AlertDialog`(`decomposed`, crosswalk 확정) | 이미 계약 |
-
-즉 `message`/`notification`/`modal`이 **무엇을 보여주는지**는 이미 다 계약돼 있다.
-`App`이 실제로 더하는 것은 오직 하나 — "이미 계약된 그 표면을, 컴포넌트 트리 아무 곳에서나
-`useApp()`으로 명령형 호출할 수 있게 context에 인스턴스를 심어 둔다"는 **배선**이다. 그건
-정의상 React Context + 특정 프레임워크의 훅 API이고, 이 패키지는 React도 RN도 import하지
-않는다(`docs/architecture.md`). 새로운 상태 축도, 새로운 접근성 개념도, 새로운 시각
-recipe도 없다 — Toast/Dialog/AlertDialog가 이미 가진 것 이상으로 계약할 것이 없다.
-
-`DesignSystemProvider`(`docs/design-system-provider.md`)와 비교하면 차이가 분명하다:
-그쪽은 런타임을 걷어내도 "테마·방향·배율·모션 선호"라는 **값 타입**이 남았다. `App`은
-걷어내면 **값 타입조차 남지 않는다** — 남는 셋(Toast/Dialog/AlertDialog)이 이미 각자의
-파일에서 완결된 계약이기 때문이다.
-
-## 결론
-
-`src/app-provider.ts`, `test/app-provider.test.ts`는 만들지 않는다. 제품이 "어디서든
-Toast/AlertDialog를 부르고 싶다"는 요구를 실제로 갖게 되면, 그건 새 HJM 계약이 아니라
-**각 제품 renderer가 자기 프레임워크(React Context, RN 동등물)로 만드는 명령형 wrapper**
-다 — Toast의 `createToastStore`/`createToastSession`이 이미 큐·타이머·중복 처리를
-소유하고 있으므로 renderer는 그 세션에 접근하는 hook만 얹으면 된다.
-
-## 판정이 뒤집힐 조건
-
-Toast/Dialog/AlertDialog 중 무엇으로도 표현할 수 없는 넷째 표면이 `App`에 새로 필요하다는
-것이 확인되면(예: 화면 밖 push나 시스템 알림함처럼 `docs/notification.md`가 이미 배제
-조건으로 남긴 것), 그때는 그 표면부터 별도로 계약하고 `App`의 배선 문제는 그 이후에
-다시 본다.
-
-## 배선 명세 (리드 참고)
-
-catalog의 `{ name: "AppProvider", category: "provider", platform: "adaptive", status:
-"planned", aliases: ["App"] }`(`src/catalog.ts:124`)는 그대로 둔다 — recipe/behavior가
-없었고 지금도 없다. crosswalk의 `App → AppProvider`(`adapted`)도 바꿀 필요 없다.

package/docs/border-beam.md

@@ -1,66 +0,0 @@
-# BorderBeam — 새 컴포넌트를 만들지 않는다
-
-## 정정
-
-이 문서의 이전 판은 `BorderBeam`이 Ant Design 컴포넌트가 아니라 Magic UI/Aceternity
-계열의 장식 컴포넌트가 crosswalk에 잘못 섞여 들어온 것이라고 주장했다. **그 주장은
-사실이 아니었다** — antd의 실제 Components Overview를 직접 확인하지 않고 일반
-웹검색만으로 판단한 결과였고, 검색 결과가 더 대중적인 Magic UI/Aceternity 쪽으로
-쏠려 있어 antd가 별도로 같은 이름의 컴포넌트를 추가했을 가능성을 놓쳤다.
-
-리드가 공식 Overview를 직접 확인해 정정했다: `BorderBeam`은 antd "Other" 섹션에
-실재하는 컴포넌트다. `Watermark`도 crosswalk에서 빠지지 않았다 —
-`src/component-references.ts:123`에 `category: "feedback"`으로 이미 정확히 잡혀
-있다(antd에서 Watermark는 Other가 아니라 Feedback 섹션이다). 섹션별 수(general 4 /
-layout 7 / navigation 7 / data-entry 18 / data-display 21 / feedback 11 / other 5 =
-73)도 저장소 테스트의 단정과 전부 일치한다. `component-references.ts:127`의
-`BorderBeam` 행은 **정확하다** — 제거하지 않는다.
-
-## 판정: 그럼에도 만들지 않는다
-
-crosswalk이 맞다는 것과 이 컴포넌트를 지금 만들 것인가는 별개 질문이다. `BorderBeam`이
-실제로 antd에 있다 해도, 그 실체 — 사용자 행동에 반응하지 않는 **상시 반복 이동
-애니메이션**(컨테이너 테두리를 따라 빛줄기가 도는 효과) — 은 `docs/identity.md`와
-정면으로 충돌한다.
-
-- 첫 문장부터 "HJM은 장식으로 브랜드를 증명하지 않습니다."
-- Motion 원칙: "Reduce Motion에서는 이동과 반복을 제거하고 즉시 전환 또는 짧은 opacity로
-  대체합니다", "bounce와 spring은 공간 관계를 설명할 때만 사용합니다."
-- HJM답지 않은 패턴: "브랜드색을 장식 배경처럼 넓게 사용."
-
-두 질문으로 검증했다:
-
-1. **Reduce Motion에서 무엇이 남는가?** 이동 자체가 이 컴포넌트의 전부이므로, 이동을
-   제거하면 정적인 테두리 선(또는 아무것도) 만 남는다 — "즉시 전환"으로 대체할 상태
-   변화가 애초에 없다(열림/닫힘/포커스 같은 원인이 없다).
-2. **장식이 없어도 화면이 같은 뜻을 전하는가?** 그렇다 — 이 컴포넌트는 어떤 상태·값·
-   선택도 표현하지 않는다. 있으나 없으나 화면이 말하는 내용은 똑같고, 차이는 순전히
-   "화려함"뿐이다.
-
-두 질문 모두 "이 장식은 정보를 나르지 않는다"로 귀결됐다 — identity가 정확히 배제하는
-자리(장식으로 증명하는 브랜드, 원인 없는 반복 모션)다. 이 세 근거는 crosswalk 출처
-문제와 무관하게 그대로 성립한다.
-
-## 결론
-
-`src/border-beam.ts`, `test/border-beam.test.ts`는 만들지 않는다.
-
-## 판정이 뒤집힐 조건
-
-BurnTok/Yajalal 중 하나가 실제로 "강조해야 하는 순간"(예: 실시간 방송 중임을 알리는
-라이브 표시, 당첨/축하 모멘트)에 은은한 강조 테두리가 필요하다고 판단하면, 그건
-`BorderBeam`(상시 반복 장식)이 아니라 그 순간에 한정된 **의미 있는 강조 recipe**(예:
-`feedback.attention` 톤의 짧은 1회성 pulse, Toast의 `priority: high`처럼 특정 상태에만
-묶인 것)로 다시 계약해야 한다.
-
-## 배선 명세 (리드 적용)
-
-`src/component-references.ts:127`의 `BorderBeam` crosswalk 행은 **정확하므로 바꾸지
-않는다.** `src/catalog.ts`의 `{ name: "BorderBeam", category: "utility", platform:
-"web", status: "planned" }` 행만 대상이다 — 이 행은 "만들 계획"을 뜻하는 `planned`인데
-실제로는 "만들지 않기로 확정"이라 상태가 거짓말을 하고 있다. 이 불일치를 어떻게
-표현할지는 `docs/catalog-decision-status.md`에서 별도로 다룬다.
-
-## 출처
-
-- [Ant Design — Components Overview](https://ant.design/components/overview/)

package/docs/chart.md

@@ -1,33 +0,0 @@
-# Chart — 렌더러를 만들지 않는다
-
-**결정.** 막대·선·원 차트 렌더러를 HJM에 두지 않는다. 대신 **색·축·격자·범례 토큰**만
-`dataviz` 계약으로 고정하고, 그리는 일은 제품이 고른 라이브러리(Recharts·victory-native·
-d3 등)에 맡긴다.
-
-**왜.** 차트를 하나 그리기 시작하면 축 눈금, 툴팁, 애니메이션, 반응형 재계산, 키보드
-탐색, 데이터 테이블 대체 표현까지 전부 따라온다. 그 전부를 이 패키지가 두 표면에서
-유지하는 비용이 제품이 라이브러리 하나를 붙이는 비용보다 크다. 게다가 반쯤 만든 차트는
-제품이 **우리 차트와 자기 차트 두 벌**을 갖게 만든다.
-
-**실제로 어긋난 것은 색이었다.** Spint 열지도와 Yajalal 통계가 각자 색을 골랐고, 같은
-포트폴리오의 두 화면이 다른 파랑을 썼다. 그건 렌더러가 없어서가 아니라 **팔레트가 없어서**
-생긴 문제다. 그래서 그 자리만 계약으로 막는다.
-
-## 계약이 정하는 것
-
-- `datavizSeriesPalette` — light/dark 각 8색의 계열 팔레트. 상태색(info/success/warning/
-  attention)은 **쓰지 않는다**: 뜻을 가진 색이라 "3번 계열"에 쓰면 사용자가 경고로 읽는다.
-- `resolveDatavizSeriesColor(theme, index)` — 8을 넘으면 **순환**한다. 색을 자동 생성하지
-  않는다. 생성색은 대비를 보장할 수 없고, 9번째 계열이 필요한 화면은 대개 표가 맞다.
-- `datavizChromeTokens` — 축선·축라벨·격자·범례·툴팁은 본문 토큰(`border`·`textMuted`·
-  `textBody`·`surface`)을 그대로 쓴다. 차트 전용 회색을 따로 두면 같은 화면의 표·캡션과
-  어긋난다.
-- `datavizRedundantEncodings` / `validateDatavizEncoding` — 색만으로 계열을 구분하지
-  않는다(WCAG 1.4.1). 직접 라벨·패턴·마커 모양 중 **하나 이상**을 색과 함께 쓴다. 색각
-  이상과 흑백 인쇄에서 차트가 남는 조건이다.
-
-## 계약이 정하지 않는 것
-
-축 스케일, 보간, 툴팁 동작, 데이터 정렬, 빈 상태 문구. 전부 제품과 라이브러리의 몫이다.
-이 결정을 뒤집으려면 "제품 두 곳 이상이 같은 차트 종류를 필요로 하고, 라이브러리 위임으로
-해결되지 않는 접근성 문제가 실측으로 확인됐다"가 먼저 있어야 한다.

package/docs/utility.md

@@ -1,53 +0,0 @@
-# Utility — 새 컴포넌트를 만들지 않는다
-
-## 이름이 이미 경고였다
-
-"유틸"은 컴포넌트가 아니다. 먼저 antd의 실제 `Util` 페이지가 무엇인지 확인했다(공식
-문서 확인, 아래 출처). antd `Util`은 UI 컴포넌트가 아니라 **`theme.useToken()` 훅으로
-현재 테마의 design token 값을 자신의 커스텀 컴포넌트에서 읽는 방법**을 설명하는 문서
-페이지다.
-
-## 판정: 이 패키지 자체가 이미 그 역할이다
-
-`useToken()`이 제공하는 것 — 현재 테마의 색·간격·타이포 값을 코드에서 직접 읽는 것 —
-은 이 저장소에서는 **훅이 아니라 이미 export된 상수**로 존재한다: `spacing`, `radius`,
-`typography`, `glyph`, `stroke`, `semanticColors`, `THEMES`(`foundations.ts`,
-`semantic-colors.ts`, `colors.ts`). antd는 이 값들을 Context에 넣고 훅으로 꺼내야 하지만
-(런타임 테마 스위칭이 Context 기반이므로), 이 패키지는 애초에 런타임 의존성이 없어 그
-값들을 정적 module import로 바로 쓴다 — **"컴포넌트에서 토큰 값을 읽는 방법"이라는 antd
-`Util` 페이지의 문제 자체가 이 패키지 구조에서는 발생하지 않는다.**
-
-즉 `Utility`라는 이름 아래 모일 실체가 없다:
-
-- 새 값 타입 없음 — 토큰은 이미 `foundations.ts`/`semantic-colors.ts`/`colors.ts`에 있다.
-- 새 접근 패턴 없음 — `import { spacing } from "@hjmds/design-contracts"`가 이미 `useToken()`이
-  하는 일과 같은 결과를 낸다(테마별 실제 색 resolve는 `resolveColorReference`가 이미
-  한다).
-- 새 접근성·상태 축 없음 — 컴포넌트가 아니므로 애초에 대상이 아니다.
-
-`ContextPanel`(`docs/context-panel.md`)과 같은 자리다 — crosswalk에 실체가 없는 이름이
-목록에 먼저 올라간 경우.
-
-## 결론
-
-`src/utility.ts`, `test/utility.test.ts`는 만들지 않는다.
-
-## 판정이 뒤집힐 조건
-
-antd `Util` 페이지가 이후 실제 유틸리티 함수(단순 토큰 읽기를 넘어서는, 예를 들어 이
-패키지가 아직 갖지 않은 계산 헬퍼)를 추가하고 그중 플랫폼 중립적으로 유용한 것이
-확인되면, 그건 `Utility`라는 이름의 새 컴포넌트가 아니라 **그 헬퍼가 속한 기존 모듈**
-(예: 숫자 관련이면 `number-field.ts`의 `clampToRange`류)에 함수로 추가하는 쪽을 권한다.
-
-## 배선 명세 제안 (리드 적용)
-
-`ContextPanel`과 같은 방식을 권한다.
-
-**(a) 권고: catalog에서 제거.** `src/catalog.ts`의 `{ name: "Utility", category:
-"utility", platform: "web", status: "planned", aliases: ["Util"] }`(`src/catalog.ts:127`)
-행을 지운다. `component-definitions.ts`의 예약 ID는 무해하니 남겨도 된다.
-
-**(b) 대안: catalog row 유지 + 이 문서만 링크.**
-
-이 저작자 판단은 (a)다 — 대응할 실체가 없는 `planned` 행이 "곧 만들 컴포넌트"로
-오인되는 비용이 검색 편의보다 크다고 봤다(`ContextPanel`과 같은 이유).