SegmentedControl의 option ID 타입을 정본 contract로 보존한다

[developer-1px]

Goal Anchor

• Outcome: UI Primitives SegmentedControl이 option ID union을 public generic contract로 보존하여 Calendar와 모든 ecosystem 소비자가 unchecked type cast 없이 값을 받는다.
• Done: generic SegmentedControlOption<Id>와 SegmentedControl<Id>가 value/options/onValueChange를 같은 ID 타입으로 연결하고, Calendar 2곳·Date controls 1곳·Selection/Topology/Artifact 3곳의 총 6개 cast가 제거되며, owner tests·API reference·UI Primitives Usage·source registration·guard·실제 Calendar flow가 계약을 증명한다.
• Don't: SegmentedControl의 DOM/ARIA/keyboard/focus/visual 동작, option labels/disabled semantics, Calendar view/scope 값, 다른 제품 상태는 변경하지 않는다.

현재 근거

• owner: @interactive-os/json-document-ui-primitives-react의 SegmentedControl
• API gap: value, option.id, onValueChange가 모두 string으로 고정되어 option ID union을 소실한다.
• 중복 보정 6곳: Calendar view/scope, Date controls grain, Selection mode, Topology order, Artifact kind가 callback에서 as cast를 수행한다.
• 같은 package의 Tabs<T>는 이미 generic ID contract를 제공하므로 canonical UI primitive 방향이 확인된다.
• UI Primitives Usage는 SegmentedControl을 실행하지만 source registration에는 현재 symbol이 빠져 있다.

작업 범위

1. SegmentedControlOption과 SegmentedControl을 string-constrained generic으로 확장한다.
2. owner contract test가 literal union callback을 보존하고 keyboard/click 동작을 유지함을 증명한다.
3. 총 6개 consumer cast를 제거한다.
4. generated API reference와 UI Primitives Usage 설명을 갱신하고 source registration에 SegmentedControl을 연결한다.
5. guard가 generic owner, consumer cast 제거, Usage/source closure를 검증하도록 추가한다.
6. package/Site/Calendar 실제 browser flow를 검증한다.

제외

• calendar-search URL validation
• Select, Tabs, 다른 control API 변경
• option registry나 새 package 도입
• 선행 stacked PR merge

[developer-1px]

작업 계획입니다.

SegmentedControl<Id extends string>
  ├─ value: Id
  ├─ options: SegmentedControlOption<Id>[]
  └─ onValueChange(value: Id)
      ├─ Calendar view / occurrence scope
      ├─ Date controls grain
      ├─ Selection mode
      ├─ Topology order
      └─ Artifact kind

• owner generic contract와 compile/runtime tests를 먼저 닫습니다.
• 동일 root cause의 6개 cast를 모두 제거합니다.
• 기존 UI Primitives Usage에 contract 설명을 추가하고 누락된 source registration을 연결합니다.
• DOM/ARIA/keyboard 동작은 기존 tests와 실제 Calendar view/scope 전환으로 검증합니다.

[developer-1px]

구현과 로컬 검증을 완료했습니다.

완료된 책임 집합:

• owner: SegmentedControlOption<Id extends string> / SegmentedControl<Id extends string>
• cast-free consumers 6곳: Calendar view/scope, Date controls grain, Selection mode, Topology order, Artifact kind
• public closure: generated API reference, UI Primitives Usage 설명, SegmentedControl source registration
• recurrence guard: generic owner·typed test·6개 direct callback·Usage/source를 검사하고 callback cast 재발 금지

검증:

• UI Primitives typecheck 및 28 tests 통과
• Site 전체 guard/typecheck 통과
• Site unit 62 tests 통과
• Segmented consumer Chrome suite 15/15 통과
• Calendar Chrome suite 20/20 clean pass (1 worker)
• root build 통과
• API reference 26 packages / 854 exports 및 docs evaluation 통과
• 실제 Chrome: view Month→ArrowRight→Year, scope Following→ArrowRight→All, checked/focus/URL 일치, console error 0

2-worker Calendar 실행에서는 기존 hotkey test가 n 입력을 놓쳐 19/20이었고, 같은 커밋의 1-worker 재실행은 20/20 clean exit였습니다.

[developer-1px]

PR을 열었습니다: #644

• 커밋: c532817f7621e5faff7d0d5faa7a2df5e92908f6
• 완료: generic owner + 6개 cast-free consumer + public closure + guard + 실제 Calendar flow
• 남은 작업: 원격 CI 확인
• 승인되지 않은 merge나 calendar-search 변경은 없습니다.

[developer-1px]

원격 CI까지 완료했습니다.

• Plan: 통과
• Package: 통과
• External kit: 통과
• Site: 통과
• 검증 커밋: c532817f7621e5faff7d0d5faa7a2df5e92908f6

PR #644는 병합하지 않고 열어 둡니다.