제품 콘텐츠의 Interaction Grammar를 정본화한다

[developer-1px]

요약

제품마다 흩어져 있던 콘텐츠 선택·활성·드래그·삽입 피드백을 하나의 정본 상태 모델과 React/DOM 시각 문법으로 통일합니다.

변경 사항

• json-document-affordance에 contentInteractionAffordance 상태 모델 추가
• json-document-ui-primitives-react에 contentInteractionAttributes와 공개 CSS 추가
• SelectableItem, GridCell이 공통 상태를 자동 투영하도록 확장
• Calendar, Board, Canvas, Kanban, Database와 정적 Artifact preview를 정본 문법으로 전환
• 선택/active/dragging/drop target/insertion/focus-visible/reduced motion을 서로 구분
• UI Catalog Usage, API reference, source registration 및 재발 방지 guard 추가

시각 원칙

• 선택: 제품 데이터 색과 충돌하지 않는 중립 inset contour + tonal fill
• active: 레이아웃 변화 없는 강한 내부 피드백
• dragging: 실제 이동 중에만 elevation
• drop target: dashed acceptance boundary
• insertion: 콘텐츠 선택이 아닌 위치 caret
• focus-visible: 상태와 독립된 outer ring

검증

• npm run verify -w @interactive-os/json-document-affordance
• npm run verify -w @interactive-os/json-document-ui-primitives-react
• npm run verify -w @interactive-os/json-document-calendar
• npm run verify -w @interactive-os/json-document-database
• npm run docs:api:check
• npm run typecheck -w @interactive-os/json-document-site
• npm run test -w @interactive-os/json-document-site (118 tests)
• npm run build -w @interactive-os/json-document-site
• 실제 Calendar/UI Catalog 스크린샷과 reduced-motion 계산 스타일 확인

Closes #705

[developer-1px]

시각 재검토에서 브랜치 기반 문제를 확인해 수정했습니다. 기존 구현이 main 기반이라 앞서 완성한 PR #704의 캘린더 레이아웃·플로팅 툴바·시간 그리드가 누락되어 있었습니다.

• PR #704의 캘린더 디자인 고도화 전체 통합
• 충돌한 selected slot은 로컬 배경/보더를 복원하지 않고 정본 insertion 문법을 유지
• 통합 화면을 인앱 브라우저에서 다시 캡처하고 기본/선택/Inspector 상태 확인
• site 118 tests, production build, pre-push root build 통과

현재 http://127.0.0.1:18778/applications/calendar?view=week&date=2026-05-25에서 개선된 버전을 확인할 수 있습니다.

[developer-1px]

캘린더 시각 고도화 및 주 시작 순서 반영

트렌디한 미니멀 캘린더 레퍼런스와 동일 뷰포트 스크린샷을 반복 비교하며 다음을 반영했습니다.

• 빈 그리드 대비를 낮추고 일정 카드는 배경과 얇은 색상 큐로 분리했습니다.
• 선택 윤곽을 절제하고 active/dragging 의미는 기존 공통 인터랙션 문법을 유지했습니다.
• 상단 보기 전환을 컴팩트한 floating popup으로 바꾸고, 바깥 제품 표면을 누르면 닫히도록 정본 Choice에 outside-click 동작을 추가했습니다.
• 주간·월간·연간·미니 캘린더의 요일 순서를 일→월→화→수→목→금→토로 통일했습니다.
• ISO week 파싱은 보존하고, 화면용 startOfCalendarWeek를 별도 정본으로 두어 날짜 열·이벤트·드래그 좌표가 함께 이동하도록 했습니다.

검증:

• npm run verify -w @interactive-os/json-document-calendar — 40 tests 통과
• npm run verify -w @interactive-os/json-document-ui-primitives-react — 24 tests 통과
• npm run typecheck -w @interactive-os/json-document-site — 통과
• npm run test -w @interactive-os/json-document-site — 118 tests 통과
• npm run build -w @interactive-os/json-document-site — 통과
• 캘린더 Playwright 전체 — 13 tests 통과
• pre-push root build — 통과

커밋: f354a84a

[developer-1px]

레퍼런스 컨셉 재정렬

첫 패스가 단순히 선과 채도만 줄여 레퍼런스의 오브젝트성이 부족했던 점을 다시 수정했습니다.

• 캔버스를 옅은 중립 면으로 분리하고, 일정은 저채도 카드 면 + 얇은 경계 + 색상 레일로 또렷하게 만들었습니다.
• 시간·열 그리드는 정보 구조만 남도록 더 후퇴시켰습니다.
• 날짜 제목을 제품 헤더 위계로 강화하고, 상단 툴바와 AI Composer는 실제 floating 레이어에만 surface shadow를 사용했습니다.
• 30분 일정의 텍스트 밀도와 내부 여백을 보정했습니다.
• 월간 일정도 주간과 동일한 카드 문법으로 통일했습니다.
• 월간·연간 뷰에 헤더 안전영역을 추가해 제목·요일·첫 주·플로팅 툴바가 겹치지 않게 했습니다.
• 주간 기본/선택, 색상 일정 주간, 월간, 연간을 각각 인앱 스크린샷으로 비교했습니다.

검증:

• site typecheck 통과
• site unit 118개 통과(병렬 부하로 1회 timeout된 docs-route는 단독 3/3 통과)
• Calendar Playwright 13/13 통과
• site production build 통과
• pre-push root build 통과

커밋: 8c178434

[developer-1px]

5회 레퍼런스 수렴 개선 완료

외부 수렴 신호를 제품에 그대로 복제하지 않고 웹 성능과 고밀도 Calendar 제약에 맞춰 정본화했습니다.

• 1/5: floating toolbar를 ProductShell 공용 presentation으로 승격
• 2/5: capsule/rounded rectangle을 역할과 크기에 따라 분리
• 3/5: 콘텐츠·제어·패널·scroll edge surface role 일원화
• 4/5: active/dragging/reduced-motion 공통 마이크로 인터랙션
• 5/5: ISO 로그형 범위를 named 제품 헤더로 개선

검증:

• Calendar package: 40/40
• UI primitives: 25/25
• site unit: 118/118
• Calendar Playwright: 13/13
• site typecheck/build 통과
• pre-push root build 통과

커밋: 8893f248

[developer-1px]

30분 일정 내부 배분 수정

스크린샷에서 30분 카드(36px)에 제목과 시간이 잘려 보이던 원인을 수정했습니다.

• 원인: 제목과 시간이 모두 공용 meta의 20px line-height를 상속해 내부 콘텐츠만 40px였음
• 수정: 일정 제목 16px line-height, 시간 12px line-height의 일정 전용 타이포 배분으로 분리
• 결과: 텍스트 28px + padding/border 6px = 34px로 36px 카드 안에 안정적으로 수용
• 긴 제목의 수평 말줄임과 세로 글리프 잘림을 분리해 처리

검증:

• 캘린더 제품 디자인 단위 테스트 8/8
• Calendar Playwright 13/13
• site production build 통과
• pre-push root build 통과

커밋: c613277e

[developer-1px]

제어 가능한 콘텐츠의 상태 문법을 한 단계 더 분리했습니다.

• 선택 집합(selected)과 현재 조작 대상(primary)을 정본 content-interaction API에서 구분했습니다.
• 일반 선택 카드는 조용한 윤곽만 유지하고, primary 카드만 낮은 elevation과 1px lift로 제어 준비 상태를 드러냅니다.
• primary 카드의 resize handle은 평상시 60%, hover/focus 시 100%, active 시 강한 피드백으로 이어집니다.
• Calendar의 week/month event가 route-local 속성 대신 정본 primitive API를 사용하도록 전환했습니다.
• 30분 카드 시간 텍스트는 디자인 토큰 규칙을 지키면서 한 칸 안에 유지했습니다.

검증:

• affordance 69 tests
• ui-primitives-react 25 tests
• calendar 40 tests
• site 118 tests
• Calendar browser 13/13
• site typecheck 및 production build 통과

커밋: 76f74afd

[developer-1px]

콘텐츠 rail과 리사이즈 컨트롤의 시각 역할을 분리했습니다.

• 일정 분류 rail은 카드 높이 전체를 잇는 연속선으로 변경했습니다.
• 리사이즈 핸들은 선택/primary 상태에서도 상시 노출하지 않고 hover·focus 시에만 나타납니다.
• 핸들은 분류 rail의 muted 톤과 구분되는 action accent 톤을 사용하며, active 시 배경 피드백까지 이어집니다.
• 관련 typecheck와 선택/primary/resize 브라우저 회귀 테스트를 통과했습니다.

커밋: f289d35d

[developer-1px]

일정 이동 중에는 계산과 시야에 필요한 그리드만 남기도록 정리했습니다.

• 포인터 제스처 시작 시 상단 Calendar toolbar, Event Inspector, AI Composer를 즉시 제거합니다.
• 드래그가 끝나거나 취소되면 컨트롤을 복원합니다.
• 이동 좌표는 플로팅 UI나 event.target이 아니라 등록된 캘린더 그리드의 getBoundingClientRect()를 기준으로 계속 계산합니다.
• 드래그 중 세 플로팅 컨트롤이 사라지고 종료 후 복원되는 브라우저 회귀 테스트를 추가했습니다.

검증: site typecheck, 관련 브라우저 테스트 3/3, production build 통과
커밋: 6acf3240

[developer-1px]

기준 스크린샷을 들고 시각 비평·디자인 시스템 검토·외부 트렌드 리서치를 병렬로 진행한 뒤 1차 수렴 루프를 반영했습니다.

수렴 판단:

• 구조는 유지하고 이벤트 카드와 하단 AI surface의 시각 처리량을 감산
• AI 입력 축소/접기는 기존 제품 원칙과 충돌하므로 채택하지 않고 폭을 보존

변경:

• 기본 이벤트는 카드 형태와 category rail을 유지하면서 border를 제거하고 fill 강도를 낮춤
• AI Composer는 폭을 유지하되 shadow를 제거하고 border/padding을 낮춰 상단 toolbar보다 한 단계 낮은 위계로 조정
• 날짜 헤더를 8px 상향해 기간 제목 → 날짜축 → 시간축의 수직 리듬 정돈

재비평 결과: 개선으로 판정했으며, 여기서 더 감산하면 이벤트 영역 구분과 AI 기능 의도성이 약해질 수 있어 이번 루프는 중단점에 도달했습니다.

검증: site typecheck, 118 unit tests, Calendar browser 14/14, production build 통과
커밋: c9d5b366

[developer-1px]

드래그 위치 보정이 어긋나 보이던 원인을 확인해 수정했습니다.

원인:

• 그리드 좌표는 15분 단위로 정상 계산됐지만 카드 컨테이너의 2px inset 위에 primary translateY(-1px), dragging translateY(-2px) scale(1.005)가 추가되어 시각 위치가 논리 위치와 달랐습니다.
• 드래그 순간 카드가 셀 경계로 올라가고 놓을 때 다시 안쪽으로 내려오면서 보정 오차처럼 보였습니다.

수정:

• 정본 content interaction의 primary offset을 CSS 변수로 열었습니다.
• Calendar timed card는 primary/dragging offset 0, dragging scale 1로 설정하고 elevation·윤곽·opacity 피드백만 유지합니다.
• 브라우저 테스트에서 드래그 중 transform의 x/y=0, scale=1을 검증합니다.

검증: ui-primitives 25 tests, Calendar design 8 tests, drag browser test, site typecheck/build 통과
커밋: 2494fa00

[developer-1px]

마지막 CI 실패 원인을 수정해 반영했습니다.

• 패키지 설치 환경에서도 CSS를 찾도록 @interactive-os/json-document-ui-primitives-react/content-interaction.css 공개 서브패스로 연결
• 사이트 소스 별칭에 동일한 CSS 서브패스를 명시해 Vite가 src/index.ts 아래로 잘못 해석하지 않도록 수정
• 변경된 affordance, calendar, UI primitives 공개 API 문서를 재생성

로컬 검증: docs:evaluate, 사이트 빌드, 외부 kit 18개 tarball 설치·typecheck·build·database browser 검증 통과

[developer-1px]

Site 브라우저 검증 실패 13건을 새 제품 문법에 맞춰 정리했습니다.

• radio 기반 뷰 선택 계약을 View 팝업 선택 계약으로 전환
• 중복 레이블 대신 canonical contextual-controls surface를 지정
• 일요일 시작 월 그리드의 주간 분할 span 기대값 동기화
• 정확한 시간 그리드 보정에 따라 72px 이동을 +1시간으로 검증
• 선택 inset affordance와 borderless 상태 문법의 시각 계약 갱신

영향 범위 39개 브라우저 테스트를 재실행했고, 최종 잔여 2개도 개별 재검증해 통과했습니다.