SEED API parity
seed-component-map이 찾은 실제 경로만 읽어 한 컴포넌트의 React와 Lynx 공개 표면을 비교한다. 파일을 만들거나 수정하지 않는다.
실행
저장소 안에서 컴포넌트 하나를 지정한다.
bun skills/seed-api-parity/scripts/api-parity.ts ProgressCircle
결과 JSON은 다음 순서로 읽는다.
sources에서 분석한 구현, 공개 API, Recipe, Registry, 문서 경로가 맞는지 확인한다. package 공개 API가 없는 Registry-only 컴포넌트는 docs/registry/{platform}/ui/<name>.tsx가 sources.<platform>.publicApi에 있어야 한다. 공개 Props가 참조하는 로컬 Registry 타입 파일은 referencedPublicApi와 해당 차원의 evidence에 남는다.dimensions에서 양쪽 관찰값, 공통 값, reactOnly, lynxOnly, 근거 경로를 확인한다. Registry snippet의 exported *Props, 직접 선언 prop, 포함된 공개 action props와 onClick·bindtap·main-thread:* 이벤트도 이 비교에 포함된다.platformDifferences.expected에서 현재 Lynx 구현이나 문서에 명시된 플랫폼 제약을 확인한다.platformDifferences.needsReview에서 한쪽에만 관찰된 값을 직접 검토한다. possiblyExplainedBy는 관련 있을 수 있는 expected ID와 그 규칙에 이름이 일치한 양쪽 값을 함께 반환한다.
dimensions는 원시 비교 결과를 유지한다. needsReview도 한쪽 관찰값을 빠뜨리지 않고 유지한다. possiblyExplainedBy가 있어도 검토 목록에서 제거하지 않는다. 브라우저 DOM과 Lynx 네이티브 환경의 차이로 설명할 수 있는지, 대체 동작이 같은 사용자 결과를 내는지 확인한 뒤 미구현 여부를 판정한다.
confidence는 다음처럼 읽는다.
confirmed: 현재 컴포넌트 맵에서 존재 여부를 직접 확인했다.partial: 양쪽 공개 API 원천에서 직접 선언된 값을 읽어 비교했다. extends, Omit 또는 다른 공개 타입을 참조해 전체 상속 표면을 풀지 못해도 직접 선언 prop과 event는 이 근거로 유지한다.unknown: 한쪽 공개 API 원천이 없거나, 컴포넌트를 정확히 찾지 못했거나, 양쪽의 직접 선언 prop 근거도 부족하다. 이때 reactOnly와 lynxOnly는 차이를 단정하지 않고 비워 둔다.
플랫폼 차이 판정
다음 차이는 같은 이름의 API가 없더라도 기능 부족으로 보지 않을 수 있다.
- React의
asChild와 DOM Slot 합성 대신 Lynx 네이티브 요소를 직접 렌더링하는 경우
- DOM
role과 aria-* 대신 accessibility-* 네이티브 접근성 속성으로 같은 의미와 상태를 전달하는 경우
- HTML heading level 대신
accessibility-heading으로 heading 의미를 전달하는 경우
- 브라우저의 키보드 focus와
focusVisible 대신 Lynx의 tap 및 네이티브 접근성 탐색을 사용하는 경우
- CSS media query 대신 viewport 단위, JavaScript 분기 또는 별도 Recipe 값으로 반응형 목적을 달성하는 경우
플랫폼 제약 후보가 있으면 세부 판정 기준은 React와 Lynx 플랫폼 차이 판정 기준을 따른다.
작업 연결
- 정확한 컴포넌트 이름이나 현재 표면이 불확실하면
seed-component-map으로 확인한다.
- React와 Lynx를 함께 다루면 이 스크립트를 실행한다.
- package 구현이 없는 Registry-only 컴포넌트는 양쪽 snippet 경로가
sources.publicApi와 해당 차원의 evidence에 포함됐는지 확인한다.
expected는 현재 컴포넌트의 Lynx 소스나 문서에서 제약을 명시적으로 확인했을 때만 사용한다. possiblyExplainedBy는 판정이 아니라 검토 단서다. 근거 경로와 대체 동작을 직접 읽는다.unknown과 needsReview를 누락으로 단정하지 않는다. 상속 타입과 대체 동작을 확인한 뒤 판정한다.- 확인한 차이를
seed-create-component의 플랫폼 및 배포 표면 결정에 입력한다.
스크립트는 TypeScript 컴파일러를 사용하지 않는다. extends, Omit, 외부 타입에서 상속한 prop 전체를 풀지 않는다. 대신 양쪽 공개 API에 직접 선언된 prop이 있으면 props, state, event, accessibility 차원을 partial로 비교하고 상속 표면이 미해석 상태임을 warnings에 남긴다.
1---2name: seed-api-parity3description: 한 SEED 컴포넌트의 React·Lynx 공개 API와 사용자 결과 차이를 읽기 전용으로 비교할 때 사용한다.4---5
6# SEED API parity
7
8`seed-component-map`이 찾은 실제 경로만 읽어 한 컴포넌트의 React와 Lynx 공개 표면을 비교한다. 파일을 만들거나 수정하지 않는다.
9
10## 실행
11
12저장소 안에서 컴포넌트 하나를 지정한다.
13
14```bash
15bun skills/seed-api-parity/scripts/api-parity.ts ProgressCircle
16```
17
18결과 JSON은 다음 순서로 읽는다.
19
201. `sources`에서 분석한 구현, 공개 API, Recipe, Registry, 문서 경로가 맞는지 확인한다. package 공개 API가 없는 Registry-only 컴포넌트는 `docs/registry/{platform}/ui/<name>.tsx`가 `sources.<platform>.publicApi`에 있어야 한다. 공개 Props가 참조하는 로컬 Registry 타입 파일은 `referencedPublicApi`와 해당 차원의 `evidence`에 남는다.
212. `dimensions`에서 양쪽 관찰값, 공통 값, `reactOnly`, `lynxOnly`, 근거 경로를 확인한다. Registry snippet의 exported `*Props`, 직접 선언 prop, 포함된 공개 action props와 `onClick`·`bindtap`·`main-thread:*` 이벤트도 이 비교에 포함된다.
223. `platformDifferences.expected`에서 현재 Lynx 구현이나 문서에 명시된 플랫폼 제약을 확인한다.
234. `platformDifferences.needsReview`에서 한쪽에만 관찰된 값을 직접 검토한다. `possiblyExplainedBy`는 관련 있을 수 있는 `expected` ID와 그 규칙에 이름이 일치한 양쪽 값을 함께 반환한다.
24
25`dimensions`는 원시 비교 결과를 유지한다. `needsReview`도 한쪽 관찰값을 빠뜨리지 않고 유지한다. `possiblyExplainedBy`가 있어도 검토 목록에서 제거하지 않는다. 브라우저 DOM과 Lynx 네이티브 환경의 차이로 설명할 수 있는지, 대체 동작이 같은 사용자 결과를 내는지 확인한 뒤 미구현 여부를 판정한다.
26
27`confidence`는 다음처럼 읽는다.
28
29- `confirmed`: 현재 컴포넌트 맵에서 존재 여부를 직접 확인했다.
30- `partial`: 양쪽 공개 API 원천에서 직접 선언된 값을 읽어 비교했다. `extends`, `Omit` 또는 다른 공개 타입을 참조해 전체 상속 표면을 풀지 못해도 직접 선언 prop과 event는 이 근거로 유지한다.
31- `unknown`: 한쪽 공개 API 원천이 없거나, 컴포넌트를 정확히 찾지 못했거나, 양쪽의 직접 선언 prop 근거도 부족하다. 이때 `reactOnly`와 `lynxOnly`는 차이를 단정하지 않고 비워 둔다.
32
33## 플랫폼 차이 판정
34
35다음 차이는 같은 이름의 API가 없더라도 기능 부족으로 보지 않을 수 있다.
36
37- React의 `asChild`와 DOM Slot 합성 대신 Lynx 네이티브 요소를 직접 렌더링하는 경우
38- DOM `role`과 `aria-*` 대신 `accessibility-*` 네이티브 접근성 속성으로 같은 의미와 상태를 전달하는 경우
39- HTML heading level 대신 `accessibility-heading`으로 heading 의미를 전달하는 경우
40- 브라우저의 키보드 focus와 `focusVisible` 대신 Lynx의 tap 및 네이티브 접근성 탐색을 사용하는 경우
41- CSS media query 대신 viewport 단위, JavaScript 분기 또는 별도 Recipe 값으로 반응형 목적을 달성하는 경우
42
43플랫폼 제약 후보가 있으면 세부 판정 기준은 [React와 Lynx 플랫폼 차이 판정 기준](references/platform-differences.md)을 따른다.
44
45## 작업 연결
46
471. 정확한 컴포넌트 이름이나 현재 표면이 불확실하면 [`seed-component-map`](../seed-component-map/SKILL.md)으로 확인한다.
482. React와 Lynx를 함께 다루면 이 스크립트를 실행한다.
493. package 구현이 없는 Registry-only 컴포넌트는 양쪽 snippet 경로가 `sources.publicApi`와 해당 차원의 `evidence`에 포함됐는지 확인한다.
504. `expected`는 현재 컴포넌트의 Lynx 소스나 문서에서 제약을 명시적으로 확인했을 때만 사용한다. `possiblyExplainedBy`는 판정이 아니라 검토 단서다. 근거 경로와 대체 동작을 직접 읽는다.
515. `unknown`과 `needsReview`를 누락으로 단정하지 않는다. 상속 타입과 대체 동작을 확인한 뒤 판정한다.
526. 확인한 차이를 [`seed-create-component`](../seed-create-component/SKILL.md)의 플랫폼 및 배포 표면 결정에 입력한다.
53
54스크립트는 TypeScript 컴파일러를 사용하지 않는다. `extends`, `Omit`, 외부 타입에서 상속한 prop 전체를 풀지 않는다. 대신 양쪽 공개 API에 직접 선언된 prop이 있으면 props, state, event, accessibility 차원을 `partial`로 비교하고 상속 표면이 미해석 상태임을 `warnings`에 남긴다.
daangn