@designbasekorea/ui-contracts 0.1.2

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @designbasekorea/ui-contracts
+ *
+ * 웹(ui-wc)과 React Native(ui-native)가 공유하는 컴포넌트 API 계약.
+ *
+ * 소스는 하나도 공유하지 않는다 — 웹은 커스텀 엘리먼트 + CSS, RN 은 View/StyleSheet 라
+ * 구현을 공유할 방법이 없다. 대신 "무엇을 받아들이는가"는 공유한다.
+ * 그래야 디자이너가 말하는 variant 이름이 양쪽에서 같은 것을 가리킨다.
+ *
+ * 사용법:
+ *   웹  — `import { BUTTON_VARIANTS } from '@designbasekorea/ui-contracts'`
+ *         attribute 문자열 검증에 배열을 그대로 쓴다.
+ *   RN  — `import type { ButtonVariant } from '@designbasekorea/ui-contracts'`
+ *         prop 타입으로 쓴다.
+ */
+
+export * from './primitives.js';
+export * from './components.js';

package/src/primitives.ts

@@ -0,0 +1,64 @@
+/**
+ * 여러 컴포넌트가 공유하는 기본 스케일.
+ *
+ * 개별 컴포넌트가 자기만의 s/m/l 을 따로 선언하면 한쪽에서 값이 추가될 때
+ * 다른 쪽이 조용히 뒤처진다. 스케일은 여기서만 정의한다.
+ */
+
+/** 표준 3단계 스케일 — 대부분의 컨트롤(Button, Input, Checkbox 등)이 사용한다 */
+export const SIZE_SML = ['s', 'm', 'l'] as const;
+export type SizeSML = (typeof SIZE_SML)[number];
+
+/** 확장 5단계 스케일 — Spinner, Skeleton 등 시각 요소가 사용한다 */
+export const SIZE_XS_XL = ['xs', 's', 'm', 'l', 'xl'] as const;
+export type SizeXsXl = (typeof SIZE_XS_XL)[number];
+
+/** Avatar 전용 6단계 스케일 */
+export const SIZE_XS_2XL = ['xs', 's', 'm', 'l', 'xl', '2xl'] as const;
+export type SizeXs2Xl = (typeof SIZE_XS_2XL)[number];
+
+/**
+ * 피드백 톤.
+ *
+ * ⚠️ `error` 가 아니라 `danger` 다. 디자인 토큰은 내부적으로 `feedback.error` 라는
+ * 키를 쓰지만, 컴포넌트 공개 API 는 danger 로 통일한다. 토큰 키와 API 이름이
+ * 다른 것은 의도된 것이며, 매핑은 각 구현체가 담당한다.
+ */
+export const FEEDBACK_TONES = ['info', 'success', 'warning', 'danger'] as const;
+export type FeedbackTone = (typeof FEEDBACK_TONES)[number];
+
+/** 둥글기 스케일 */
+export const RADIUS_SCALE = ['none', 's', 'm', 'l', 'pill'] as const;
+export type RadiusScale = (typeof RADIUS_SCALE)[number];
+
+/**
+ * 계약 위반을 런타임에 잡기 위한 헬퍼.
+ *
+ * 웹 커스텀 엘리먼트는 attribute 로 임의의 문자열을 받으므로, 계약에 없는 값이
+ * 들어오면 기본값으로 되돌린다. RN 은 타입으로 막히니 이 헬퍼가 필요 없다.
+ */
+export function coerceToContract<T extends readonly string[]>(
+    value: string | null | undefined,
+    allowed: T,
+    fallback: T[number],
+): T[number] {
+    return value && (allowed as readonly string[]).includes(value)
+        ? (value as T[number])
+        : fallback;
+}
+
+/**
+ * `coerceToContract` 와 같지만, 계약에서 빠진 구 이름을 별칭표로 한 번 접는다.
+ * 이름을 바꾼 뒤에도 이미 배포된 마크업이 계속 동작하게 하는 용도다.
+ */
+export function coerceWithAliases<T extends readonly string[]>(
+    value: string | null | undefined,
+    allowed: T,
+    aliases: Readonly<Record<string, T[number]>>,
+    fallback: T[number],
+): T[number] {
+    if (value && !(allowed as readonly string[]).includes(value) && value in aliases) {
+        return aliases[value];
+    }
+    return coerceToContract(value, allowed, fallback);
+}