+# @fox — 포터블 디자인 시스템

+

+프로젝트에 종속되지 않는 디자인 시스템. **이 폴더를 통째로 복사하고 설정 몇 줄을 추가하면**

+다른 프로젝트에서 그대로 동작합니다.

+

+```

+@fox/

+  styles/                SCSS — 여기가 디자인의 전부입니다

+    index.scss           토큰 진입점 (앱이 한 번 @use)

+    components.scss      공용 컴포넌트 스타일 묶음 진입점

+    _fox-*.scss          컴포넌트별 스타일 (개별 @use 가능)

+    abstracts.scss       저작 진입점 — 함수·믹스인 (CSS 출력 0)

+    tokens/              토큰 map = 단일 진실 공급원 (자동 생성)

+    _root.scss           map → --fox-* 커스텀 프로퍼티

+    _functions.scss      fox.color() 등 토큰 접근 + 이름 검증

+    _mixins.scss         fox.pc / fox.mobile

+  core/

+    components/          React 래퍼 (선택 — 아래 "React 없이 쓰기" 참고)

+    utils/               cx() 등 의존성 없는 유틸

+  dev-test/              개발 전용 테스트·감사 화면

+  tools/build-tokens.py  Figma JSON → SCSS 변환기

+```

+

+## 이식하기

+

+1. `@fox/` 폴더를 대상 프로젝트에 복사합니다.

+

+2. `sass`를 설치합니다.

+

+   ```bash

+   npm install --save-dev sass

+   ```

+

+3. **SCSS 로드 경로**를 설정합니다. Next.js면 `next.config.ts`:

+

+   ```ts

+   sassOptions: { loadPaths: [path.join(process.cwd())] }

+   ```

+

+   다른 번들러면 그 도구의 Sass 옵션(`includePaths` / `loadPaths`)에 프로젝트 루트를

+   넣으면 됩니다. 이게 있어야 `@use "@fox/styles/..."` 같은 절대 표기가 해석되고, 없으면

+   컴포넌트마다 `../../../` 상대 경로를 써야 해서 폴더 복사가 불가능해집니다.

+

+4. 글로벌 스타일에서 진입점을 불러옵니다.

+

+   ```scss

+   @use "@fox/styles";              // 토큰

+   @use "@fox/styles/components";   // 공용 컴포넌트 스타일 (전부)

+   ```

+

+   골라 쓰려면 묶음 대신 개별 파티셜을 가져옵니다 — 안 쓰는 CSS가 번들에 실리지 않습니다.

+   둘을 같이 써도 Sass가 모듈을 한 번만 로드해 중복되지 않습니다.

+

+   ```scss

+   @use "@fox/styles/fox-button";

+   ```

+

+5. (TypeScript 프로젝트에서 React 래퍼도 쓸 경우) 경로 별칭을 추가합니다.

+

+   ```json

+   { "compilerOptions": { "paths": { "@fox/*": ["./@fox/*"] } } }

+   ```

+

+6. (선택) 폰트를 주입합니다 — 아래 "호스트 앱과의 계약" 참고.

+

+## React 없이 쓰기

+

+**디자인 레이어는 프레임워크에 의존하지 않습니다.** 토큰도 컴포넌트 스타일도 순수 SCSS이고,

+클래스명이 `fox-` 접두사 + BEM이라 전역에 풀어도 충돌하지 않습니다. Vue·Svelte·서버

+템플릿·순수 HTML 어디서든 위 2~4번만 하고 마크업 계약을 지키면 같은 결과가 나옵니다.

+

+각 컴포넌트의 **마크업 계약은 해당 스타일 파일 상단 주석**에 있습니다. 버튼 네 종류는 이렇습니다.

+

+```html

+<button class="fox-button fox-button--primary fox-button--md">

+  <span class="fox-button__icon"><!-- svg (선택) --></span>

+  <span class="fox-button__label">버튼</span>

+  <span class="fox-button__icon"><!-- svg (선택) --></span>

+</button>

+

+<button class="fox-text-button fox-text-button--primary fox-text-button--md">

+  <span class="fox-text-button__label">텍스트 버튼</span>

+</button>

+

+<a href="…" class="fox-link-button fox-link-button--primary fox-link-button--md">

+  <span class="fox-link-button__label">링크</span>

+  <span class="fox-link-button__icon"><!-- svg (선택, 항상 라벨 뒤) --></span>

+</a>

+

+<button class="fox-icon-button fox-icon-button--ghost fox-icon-button--md" aria-label="공유">

+  <span class="fox-icon-button__icon"><!-- svg --></span>

+</button>

+

+<div class="fox-button-group fox-button-group--horizontal fox-button-group--start">

+  <button class="fox-button fox-button--default fox-button--md">취소</button>

+  <button class="fox-button fox-button--primary fox-button--md">확인</button>

+</div>

+

+<div class="fox-button-panel fox-button-panel--offset">

+  <div class="fox-button-group fox-button-group--horizontal fox-button-group--start">…</div>

+  <div class="fox-button-group fox-button-group--horizontal fox-button-group--end">…</div>

+</div>

+

+<div class="fox-input fox-input--md">

+  <label class="fox-input__label" for="name">레이블</label>

+  <div class="fox-input__box">

+    <input class="fox-input__field" id="name" placeholder="내용을 입력하세요.">

+    <span class="fox-input__icon"><!-- svg (선택) --></span>

+  </div>

+  <p class="fox-input__message"><!-- 헬퍼 (선택) --></p>

+</div>

+

+<div class="fox-phone-number" role="group" aria-labelledby="phone-label">

+  <span class="fox-phone-number__label" id="phone-label">전화번호</span>

+  <div class="fox-phone-number__box">          <!-- combine -->

+    <input class="fox-phone-number__segment" aria-label="전화번호 앞자리">

+    <span class="fox-phone-number__separator">-</span>

+    <input class="fox-phone-number__segment" aria-label="전화번호 가운데자리">

+    <span class="fox-phone-number__separator">-</span>

+    <input class="fox-phone-number__segment" aria-label="전화번호 뒷자리">

+  </div>

+</div>

+

+<div class="fox-text-area">

+  <label class="fox-text-area__label" for="memo">레이블</label>

+  <div class="fox-text-area__box">

+    <textarea class="fox-text-area__field" id="memo" rows="5" placeholder="내용을 입력하세요."></textarea>

+  </div>

+  <div class="fox-text-area__footer">

+    <p class="fox-text-area__message"><!-- 헬퍼 (선택) --></p>

+    <p class="fox-text-area__counter">

+      <span class="fox-text-area__counter-current">0</span>/100

+    </p>

+  </div>

+</div>

+```

+

+- 비활성은 네이티브 `disabled` 속성으로 표현합니다(별도 클래스 없음). 앵커에는 `disabled`가

+  없으므로 `aria-disabled="true"`를 쓰고 `href`를 뺍니다.

+- 로딩은 앞 아이콘 자리에 `fox-button__spinner`를 두고 `disabled`를 함께 겁니다.

+- 토글은 `fox-icon-button`에 `aria-pressed="true|false"`를 더합니다.

+- 버튼 묶음은 간격·방향·정렬만 담당합니다. 자식 버튼의 크기 클래스를 그룹 크기로 맞추는 건

+  작성자 몫입니다(React 래퍼는 `size` prop으로 자동화합니다). 세로(`--vertical`)는 자식이

+  폭을 채웁니다.

+- 버튼 패널은 그룹이 여럿이면 양끝으로, 하나면 가운데로 둡니다 — 자식 수는 CSS `:only-child`가

+  판단하므로 따로 표시할 게 없습니다. 패널 안에서는 그룹 간격이 넓어지고 버튼에 최소 폭이

+  붙으며, 모바일에서는 패널·그룹이 모두 세로로 쌓입니다.

+- 입력과 여러 줄 입력의 상태는 기본적으로 브라우저가 판단합니다 — 포커스는 `:focus-within`,

+  비활성·읽기전용은 네이티브 속성, 오류는 `aria-invalid="true"`. 모양을 못박으려면 루트에

+  `data-state`를 줍니다 (`default` `focused` `completed` `error` `disabled` `view`).

+- 여러 줄 입력에는 크기 축이 없습니다. 높이는 `rows`가 정하고 시안은 5줄입니다.

+- 이메일은 값이 `아이디@도메인`이 합쳐진 문자열 하나입니다. 도메인을 드롭다운에서 고르면

+  옆 칸에 그 값이 채워지고 읽기 전용이 되며, `직접입력`을 고르면 풀립니다. 확인 버튼은

+  `onVerify`를 넘겼을 때만 생깁니다.

+- 주소는 우편번호와 주소가 검색 결과로만 채워지는 읽기 전용이고 상세주소만 입력합니다.

+  어떤 우편번호 서비스를 쓸지는 `@fox`가 모릅니다 — 호출부가 `onSearch`에서 결과를

+  `FoxAddressSearchResult`(`zipCode`·`address`·선택 `detail`)로 돌려주고, 취소는 `null`입니다.

+- 휴대폰 인증은 보내기·확인을 호출부가 `Promise`로 넘깁니다 — resolve면 성공, reject면

+  실패이고 결과는 이벤트로 올라옵니다. 보내기가 성공해야 인증번호 칸과 확인 버튼이 열리고,

+  인증에 성공하면 전부 잠깁니다. 남은 시간은 `remainingSeconds`를 주면 그 값을, 없으면

+  `expiresIn`부터 컴포넌트가 셉니다.

+- 전화번호는 화면만 세 칸이고 값은 숫자만 담긴 문자열 하나입니다 — 하이픈은 값에 들어가지

+  않습니다. `unit`은 앞자리가 드롭다운이라 조각을 select·input으로 조립하고, `combine`은

+  상자 하나에 세 칸을 둡니다.

+- 파일 첨부는 세 모드(`default`·`area`·`image`)를 한 컴포넌트로 둡니다. 업로드는 하지

+  않고 고른 원본 `File`만 넘기며, 진행률·서버 오류를 목록에 어떻게 비출지는 `files`로

+  정합니다. `area`는 끌어다 놓기가 항상 켜져 있고 `image`에는 목록이 없습니다.

+- 아이콘 SVG는 `currentColor`로 그려야 계열별 색이 적용됩니다. 크기는 슬롯이 정합니다.

+

+`core/`의 React 컴포넌트는 이 클래스를 조립해주는 **얇은 래퍼**일 뿐입니다 — 쓰지 않아도

+디자인은 그대로 얻습니다.

+

+토큰만 쓰는 것도 물론 됩니다.

+

+```scss

+@use "@fox/styles/abstracts" as fox;

+

+.whatever {

+  padding: fox.padding(6);

+  color: fox.color(font-neutral-default);

+  @include fox.pc { padding: fox.padding(8); }

+}

+```

+

+## 핵심 설계

+

+**토큰의 SSOT는 `tokens/`의 SCSS map 하나입니다.** 여기서 두 가지가 함께 파생됩니다 —

+`_root.scss`가 만드는 `--fox-*` 커스텀 프로퍼티와, `_functions.scss`가 검증에 쓰는 유효

+이름 목록. 값과 이름이 한 곳에만 있으므로 둘이 어긋날 수 없습니다.

+

+**토큰은 Figma에서 자동 생성됩니다. 손으로 고치지 않습니다.** Figma 변수를 재수출한 뒤

+변환기를 다시 돌리면 됩니다. 생성물이 재현 가능해서 재실행 diff가 곧 Figma 변경분입니다.

+

+```bash

+FOX_TOKENS_SRC=<export 폴더> python3 @fox/tools/build-tokens.py

+```

+

+**규율을 컴파일러가 강제합니다.** 화면 코드는 `color: #256EF4`를 쓸 수 없고

+`fox.color(...)`로 토큰을 지목해야 합니다. 없는 이름은 빌드가 실패하며 사용 가능한 목록을

+함께 출력합니다.

+

+```

+Error: [@fox] 알 수 없는 color 토큰: `primry` — 사용 가능한 값: background-default, ...

+```

+

+**1rem = 10px입니다.** `_root.scss`의 `html { font-size: 62.5% }`가 근거입니다.

+

+> ⚠️ **미디어 쿼리 안의 `rem`은 예외입니다.** 미디어 쿼리는 `html`의 `font-size` 영향을

+> 받지 않습니다. 그래서 브레이크포인트는 `768px`로 두었고, 미디어 쿼리는 `fox.pc` /

+> `fox.mobile` 믹스인으로만 씁니다 — 조건부는 `var()`를 해석하지 못합니다.

+

+**라이트/다크는 값이 한 곳에만 존재합니다.** `light-dark(라이트, 다크)`로 한 줄에 두 값을

+쓰고 전환은 `color-scheme`이 담당합니다. 다크 전용 오버라이드 블록이 없어 테마 불일치가

+구조적으로 불가능합니다. `<html data-theme="light"|"dark">`로 수동 선택을 덮어쓸 수 있고,

+속성이 없으면 OS 설정을 따릅니다.

+

+> `light-dark()` 자체는 Chrome 123 / Safari 17.5 / Firefox 120 이상이 필요하지만,

+> Lightning CSS(Next.js Turbopack)가 커스텀 프로퍼티 조합으로 폴리필해 출력하므로 구형

+> 브라우저에서도 동작합니다. browserslist 타깃을 좁히거나 다른 번들러로 옮길 때 재확인하세요.

+

+## 호스트 앱과의 계약

+

+`@fox`가 소유하지 않고 앱에서 받는 값입니다.

+

+| CSS 변수 | 용도 | 미주입 시 |

+| --- | --- | --- |

+| `--app-font-sans` | 기본 서체 | `system-ui`로 폴백 |

+| `--app-font-mono` | 고정폭 서체 | `ui-monospace`로 폴백 |

+

+폰트 파일은 앱이 소유합니다. `@fox`는 변수를 참조만 하므로, 복사해 간 프로젝트는 그

+프로젝트의 폰트를 그대로 씁니다.

+

+## 새 컴포넌트 추가

+

+`core/components/README.md`의 작성 규약을 따릅니다. 요점은 스타일을 `styles/_<name>.scss`에

+두고 `fox-` 접두사 + BEM으로 이름 짓는 것 — 그래야 React 밖에서도 쓸 수 있습니다.

+# 컴포넌트 작성 규약

+

+## 파일 배치

+

+컴포넌트 하나당 폴더 하나. **스타일은 여기에 두지 않는다** — `@fox/styles/_<name>.scss`가 소유한다.

+

+```

+core/components/

+  fox-button/

+    fox-button.tsx      컴포넌트 (React)

+    index.ts            export { FoxButton } from "./fox-button";

+  index.ts              배럴 — export * from "./fox-button";

+

+styles/

+  _fox-button.scss      모양 규칙 (프레임워크 무관)

+  components.scss       전부 묶음 진입점 — 새 컴포넌트를 여기에 @use로 추가

+```

+

+**스타일과 컴포넌트를 갈라 둔 이유**는 디자인이 React에 묶이면 안 되기 때문이다. SCSS만

+쓰는 프로젝트(Vue·Svelte·서버 템플릿 등)도 `@use "@fox/styles/fox-button"` 하나로 같은

+버튼을 얻어야 한다.

+

+## 작성 규칙

+

+**1. 클래스명은 `fox-` 접두사 + BEM.**

+

+```

+.fox-button                    블록

+.fox-button__label             엘리먼트

+.fox-button--primary           모디파이어

+```

+

+CSS Modules를 쓰지 않는다. 이름이 전역 유일해서 스코프가 필요 없고, 스코프가 없어야

+React 밖에서도 같은 이름으로 쓸 수 있다. **충돌 방지는 접두사 규율이 담당한다.**

+

+**2. 모양 값은 전부 `fox.*()` 토큰으로 지목한다.**

+

+```scss

+@use "abstracts" as fox;

+

+.fox-button {

+  padding-inline: fox.form(padding-md);

+  background: fox.color(button-primary-surface);

+  border-radius: fox.form(radius-md);

+}

+```

+

+원시 값(hex·px·rem 리터럴) 금지. 없는 토큰 이름은 빌드가 실패시킨다. 맞는 토큰이 없으면

+쓰지 말고 Figma에 먼저 추가한다 — 토큰 파일은 자동 생성물이다.

+

+토큰으로 표현할 수 없는 값(시안에 있으나 변수화되지 않은 것 등)이 나오면 **사용자와 상의한

+뒤** 넣고, 파일 상단 주석에 근거를 남긴다.

+

+**3. 상태는 네이티브 속성으로.**

+

+`disabled`·`aria-busy` 같은 표준 속성을 쓰고 `.is-disabled` 같은 클래스를 만들지 않는다.

+SCSS만 쓰는 소비자도 별도 규칙 없이 같은 결과를 얻는다.

+

+**4. 마크업 계약을 스타일 파일 상단에 적는다.**

+

+React 밖 소비자는 그 주석만 보고 DOM을 짜야 한다. 필수 구조와 선택 요소를 예시로 남긴다.

+

+**5. 기본은 Server Component.**

+

+`'use client'`는 상호작용(상태·이벤트 핸들러)이 실제로 필요할 때만 붙인다.

+

+**6. variant는 `Record`로 고정한다.**

+

+```tsx

+const TYPE_CLASS: Record<FoxButtonType, string> = {

+  primary: "fox-button--primary",

+  secondary: "fox-button--secondary",

+};

+```

+

+계열을 추가하면 맵 누락이 타입 에러가 된다.

+

+**7. `className` prop은 배치용으로만 연다.**

+

+호출부가 넘기는 것은 margin·grid 배치 같은 **위치** 조정이지 디자인 값이 아니다. 모양이

+달라져야 하면 모디파이어를 추가한다.

+

+**8. 호스트 앱에 의존하지 않는다.**

+

+`@fox/` 안에서 `@/lib/...` 같은 앱 경로를 import 하지 않는다. 앱이 주는 값은 prop이나

+CSS 변수로 받는다.

+

+**9. 만들면 테스트 페이지에 등록한다.**

+

+`@fox/dev-test/component-registry.tsx`의 `COMPONENT_EXAMPLES`에 항목 하나를 추가하면

+`/dev-test/design`에 나타난다.

+"use client";

+

+import { useId, useState, type ReactNode } from "react";

+import { cx } from "../../utils";

+import { FoxButton } from "../fox-button";

+import { FoxInput } from "../fox-input";

+

+/**

+ * 주소 검색 결과. 호출부가 어떤 우편번호 서비스를 쓰든 이 모양으로 바꿔서 돌려준다 —

+ * 그래야 `@fox`가 특정 API에 묶이지 않는다.

+ */

+export interface FoxAddressSearchResult {

+  /** 우편번호. 첫 칸에 그대로 들어간다. */

+  zipCode: string;

+  /** 도로명 또는 지번 주소. 둘째 칸에 그대로 들어간다. 어느 쪽을 쓸지는 호출부가 정한다. */

+  address: string;

+  /**

+   * 상세주소 칸에 미리 채울 값(건물명 같은 참고항목).

+   * 넘기지 않으면 사용자가 적어 둔 상세주소를 건드리지 않는다.

+   */

+  detail?: string;

+}

+

+/** 주소 한 벌. 화면의 세 칸을 그대로 담는다. */

+export interface FoxAddressValue {

+  zipCode: string;

+  address: string;

+  detail: string;

+}

+

+export const EMPTY_ADDRESS: FoxAddressValue = { zipCode: "", address: "", detail: "" };

+

+export interface FoxAddressProps {

+  value?: FoxAddressValue;

+  defaultValue?: FoxAddressValue;

+  onChange?: (value: FoxAddressValue) => void;

+

+  /**

+   * 주소 검색. 호출부가 우편번호 서비스를 띄우고 결과를 `FoxAddressSearchResult`로

+   * 돌려준다. 사용자가 고르지 않고 닫으면 `null`을 돌려주면 되고, 그때는 값이 그대로

+   * 남는다. throw·reject하면 `onSearchFail`을 부른다.

+   */

+  onSearch: () => Promise<FoxAddressSearchResult | null>;

+  onSearchSuccess?: (result: FoxAddressSearchResult) => void;

+  onSearchFail?: (error: unknown) => void;

+  searchLabel?: string;

+

+  label?: string;

+  /** 헬퍼 메시지. 오류일 때 색이 바뀐다. */

+  message?: string;

+  messageIcon?: ReactNode;

+  zipCodePlaceholder?: string;

+  addressPlaceholder?: string;

+  detailPlaceholder?: string;

+

+  invalid?: boolean;

+  disabled?: boolean;

+  /** 참이면 렌더하지 않는다(DOM에 남지 않는다). */

+  hidden?: boolean;

+  /** 배치 조정용. */

+  className?: string;

+}

+

+/**

+ * @fox 주소 입력. 우편번호와 주소는 검색 결과로만 채워지고, 상세주소만 손으로 적는다.

+ *

+ * 어떤 우편번호 서비스를 쓸지는 `@fox`가 알 필요가 없다 — 호출부가 `onSearch`에서 그

+ * 서비스를 띄우고 결과를 `FoxAddressSearchResult` 모양으로 바꿔서 돌려주면 된다.

+ *

+ * ⚠️ 스타일은 이 파일이 import하지 않는다 — 호스트 앱이 `@use "@fox/styles/components"`

+ * (또는 개별 파티셜)로 한 번 불러와야 한다.

+ */

+export function FoxAddress({

+  value,

+  defaultValue,

+  onChange,

+  onSearch,

+  onSearchSuccess,

+  onSearchFail,

+  searchLabel = "주소 검색",

+  label,

+  message,

+  messageIcon,

+  zipCodePlaceholder = "우편번호",

+  addressPlaceholder = "주소",

+  detailPlaceholder = "상세주소",

+  invalid = false,

+  disabled = false,

+  hidden = false,

+  className,

+}: FoxAddressProps) {

+  const autoId = useId();

+  const [inner, setInner] = useState<FoxAddressValue>(defaultValue ?? EMPTY_ADDRESS);

+  const [searching, setSearching] = useState(false);

+

+  if (hidden) {

+    return null;

+  }

+

+  const current = value ?? inner;

+  const messageId = `${autoId}-message`;

+

+  const commit = (next: FoxAddressValue) => {

+    if (value === undefined) {

+      setInner(next);

+    }

+    onChange?.(next);

+  };

+

+  const handleSearch = async () => {

+    if (searching) {

+      return;

+    }

+    setSearching(true);

+    try {

+      const result = await onSearch();

+      // 취소하면 `null`이 온다 — 그때는 값이 그대로 남는다.

+      if (result) {

+        commit({

+          zipCode: result.zipCode,

+          address: result.address,

+          detail: result.detail ?? current.detail,

+        });

+        onSearchSuccess?.(result);

+      }

+    } catch (error) {

+      onSearchFail?.(error);

+    } finally {

+      setSearching(false);

+    }

+  };

+

+  return (

+    <div className={cx("fox-address", className)}>

+      {label && (

+        <span className="fox-address__label" id={`${autoId}-label`}>

+          {label}

+        </span>

+      )}

+

+      <div className="fox-address__row">

+        <div className="fox-address__zip">

+          {/* 검색 결과로만 채워진다 — 손으로 고칠 수 없다. */}

+          <FoxInput

+            size="md"

+            aria-label={zipCodePlaceholder}

+            aria-describedby={message ? messageId : undefined}

+            value={current.zipCode}

+            placeholder={zipCodePlaceholder}

+            readOnly

+            invalid={invalid}

+            disabled={disabled}

+          />

+        </div>

+

+        <FoxButton

+          size="md"

+          type="secondary"

+          label={searchLabel}

+          loading={searching}

+          disabled={disabled}

+          onAction={handleSearch}

+        />

+      </div>

+

+      <FoxInput

+        size="md"

+        aria-label={addressPlaceholder}

+        value={current.address}

+        placeholder={addressPlaceholder}

+        readOnly

+        invalid={invalid}

+        disabled={disabled}

+      />

+

+      <FoxInput

+        size="md"

+        aria-label={detailPlaceholder}

+        value={current.detail}

+        onChange={(next) => commit({ ...current, detail: next })}

+        placeholder={detailPlaceholder}

+        invalid={invalid}

+        disabled={disabled}

+      />

+

+      {message && (

+        <p className="fox-address__message" id={messageId}>

+          {messageIcon && (

+            <span className="fox-address__message-icon" aria-hidden="true">

+              {messageIcon}

+            </span>

+          )}

+          {message}

+        </p>

+      )}

+    </div>

+  );

+}

+export {

+  FoxAddress,

+  EMPTY_ADDRESS,

+  type FoxAddressProps,

+  type FoxAddressValue,

+  type FoxAddressSearchResult,

+} from "./fox-address";

+"use client";

+

+import {

+  Children,

+  Fragment,

+  cloneElement,

+  isValidElement,

+  type ReactElement,

+  type ReactNode,

+} from "react";

+import { cx } from "../../utils";

+

+export type FoxButtonGroupOrientation = "horizontal" | "vertical";

+export type FoxButtonGroupAlign = "start" | "center" | "end";

+export type FoxButtonGroupSize = "lg" | "md" | "sm" | "xsm";

+

+export interface FoxButtonGroupProps {

+  orientation?: FoxButtonGroupOrientation;

+  /** 주축 정렬. 세로에서는 그룹 높이가 정해져 있을 때만 눈에 띈다. */

+  align?: FoxButtonGroupAlign;

+  /** 자식 버튼의 `size`를 전부 이 값으로 덮어쓴다. 자식이 따로 준 값은 무시된다. */

+  size: FoxButtonGroupSize;

+  wrap?: boolean;

+  /** 배치 조정용. */

+  className?: string;

+  children?: ReactNode;

+}

+

+const ORIENTATION_CLASS: Record<FoxButtonGroupOrientation, string> = {

+  horizontal: "fox-button-group--horizontal",

+  vertical: "fox-button-group--vertical",

+};

+

+const ALIGN_CLASS: Record<FoxButtonGroupAlign, string> = {

+  start: "fox-button-group--start",

+  center: "fox-button-group--center",

+  end: "fox-button-group--end",

+};

+

+type Overrides = { size: FoxButtonGroupSize; fullWidth?: true };

+

+/**

+ * 자식 버튼에 그룹 값을 강제로 덮어쓴다.

+ *

+ * - 호스트 요소(`div` 등)는 건드리지 않는다 — DOM에 없는 속성이 넘어가면 React가 경고한다.

+ * - `Children.map`은 프래그먼트 안으로 들어가지 않아 직접 내려간다. 그러지 않으면

+ *   `<>…</>`로 감싼 버튼들이 덮어쓰기를 피해 가고 Fragment에 `size`가 붙어 경고가 난다.

+ */

+function overrideChildren(children: ReactNode, overrides: Overrides): ReactNode {

+  return Children.map(children, (child) => {

+    if (!isValidElement(child)) {

+      return child;

+    }

+

+    if (child.type === Fragment) {

+      const fragment = child as ReactElement<{ children?: ReactNode }>;

+      return overrideChildren(fragment.props.children, overrides);

+    }

+

+    if (typeof child.type === "string") {

+      return child;

+    }

+

+    return cloneElement(child as ReactElement<Record<string, unknown>>, overrides);

+  });

+}

+

+/**

+ * @fox 버튼 묶음. 간격·방향·정렬만 책임지고 상태를 갖지 않는다.

+ *

+ * 크기는 **그룹이 단일 진실 공급원**이다 — 자식이 저마다 다른 `size`를 줘도 그룹 값으로

+ * 통일된다. 세로일 때는 자식이 항상 폭을 채운다.

+ *

+ * ⚠️ 스타일은 이 파일이 import하지 않는다 — 호스트 앱이 `@use "@fox/styles/components"`

+ * (또는 개별 파티셜)로 한 번 불러와야 한다.

+ */

+export function FoxButtonGroup({

+  orientation = "horizontal",

+  align = "start",

+  size,

+  wrap = false,

+  className,

+  children,

+}: FoxButtonGroupProps) {

+  const overrides: Overrides =

+    orientation === "vertical" ? { size, fullWidth: true } : { size };

+

+  return (

+    <div

+      className={cx(

+        "fox-button-group",

+        ORIENTATION_CLASS[orientation],

+        ALIGN_CLASS[align],

+        wrap && "fox-button-group--wrap",

+        className

+      )}

+    >

+      {overrideChildren(children, overrides)}

+    </div>

+  );

+}

+export {

+  FoxButtonGroup,

+  type FoxButtonGroupProps,

+  type FoxButtonGroupOrientation,

+  type FoxButtonGroupAlign,

+  type FoxButtonGroupSize,

+} from "./fox-button-group";

+"use client";

+

+import type { ReactNode } from "react";

+import { cx } from "../../utils";

+

+export interface FoxButtonPanelProps {

+  /** 시안의 상단 80px 여백. 페이지 하단이 아닌 곳에 놓을 땐 끈다. */

+  offset?: boolean;

+  /** 배치 조정용. */

+  className?: string;

+  /** 버튼 그룹들. 하나면 가운데, 여럿이면 양끝으로 벌어진다. */

+  children?: ReactNode;

+}

+

+/**

+ * @fox 페이지 하단 동작 영역. 배치만 책임지고 상태를 갖지 않는다.

+ *

+ * 자식 수를 세지 않는다 — 가운데 정렬은 CSS `:only-child`가 판단하므로 프래그먼트나

+ * 조건부 렌더로 자식이 갈려도 실제 DOM 기준으로 맞는다.

+ *

+ * ⚠️ 스타일은 이 파일이 import하지 않는다 — 호스트 앱이 `@use "@fox/styles/components"`

+ * (또는 개별 파티셜)로 한 번 불러와야 한다.

+ */

+export function FoxButtonPanel({

+  offset = true,

+  className,

+  children,

+}: FoxButtonPanelProps) {

+  return (

+    <div

+      className={cx("fox-button-panel", offset && "fox-button-panel--offset", className)}

+    >

+      {children}

+    </div>

+  );

+}

+export { FoxButtonPanel, type FoxButtonPanelProps } from "./fox-button-panel";

+"use client";

+

+import type { ReactNode, Ref } from "react";

+import { cx } from "../../utils";

+

+export type FoxButtonType = "primary" | "secondary" | "default" | "error";

+export type FoxButtonSize = "lg" | "md" | "sm" | "xsm";

+

+export interface FoxButtonProps {

+  type?: FoxButtonType;

+  size: FoxButtonSize;

+  /** 네이티브 `type` — prop의 `type`이 시각 계열을 쓰므로 분리했다. */

+  htmlType?: "button" | "submit" | "reset";

+  /** 배치 조정용. 모양이 달라야 하면 여기 말고 `type`을 추가한다. */

+  className?: string;

+  /** `currentColor`로 그린 SVG여야 계열별 색이 적용된다. 크기는 슬롯이 정한다. */

+  leadingIcon?: ReactNode;

+  trailingIcon?: ReactNode;

+  label: string;

+  disabled?: boolean;

+  /** 참이면 렌더하지 않는다(DOM에 남지 않는다). */

+  hidden?: boolean;

+  /** 호출부가 소유한다 — 버튼이 스스로 켜지 않는다. */

+  loading?: boolean;

+  fullWidth?: boolean;

+  onAction?: () => void;

+  /** 포인터가 올라오면 `true`, 벗어나면 `false`. */

+  onHoverChange?: (hovered: boolean) => void;

+  ref?: Ref<HTMLButtonElement>;

+}

+

+/** `Record`로 고정해 계열을 추가하면 항목 누락이 타입 에러가 되게 한다. */

+const TYPE_CLASS: Record<FoxButtonType, string> = {

+  primary: "fox-button--primary",

+  secondary: "fox-button--secondary",

+  default: "fox-button--default",

+  error: "fox-button--error",

+};

+

+const SIZE_CLASS: Record<FoxButtonSize, string> = {

+  lg: "fox-button--lg",

+  md: "fox-button--md",

+  sm: "fox-button--sm",

+  xsm: "fox-button--xsm",

+};

+

+/**

+ * @fox 공용 버튼. 상태를 갖지 않는다.

+ *

+ * ⚠️ 스타일은 이 파일이 import하지 않는다 — 호스트 앱이 `@use "@fox/styles/components"`

+ * (또는 개별 파티셜)로 한 번 불러와야 한다.

+ */

+export function FoxButton({

+  type = "default",

+  size,

+  htmlType = "button",

+  className,

+  leadingIcon,

+  trailingIcon,

+  label,

+  disabled = false,

+  hidden = false,

+  loading = false,

+  fullWidth = false,

+  onAction,

+  onHoverChange,

+  ref,

+}: FoxButtonProps) {

+  if (hidden) {

+    return null;

+  }

+

+  // 같은 요청이 두 번 나가지 않게 로딩 중에도 막는다.

+  const inactive = disabled || loading;

+

+  return (

+    <button

+      ref={ref}

+      type={htmlType}

+      className={cx(

+        "fox-button",

+        TYPE_CLASS[type],

+        SIZE_CLASS[size],

+        fullWidth && "fox-button--full-width",

+        className

+      )}

+      disabled={inactive}

+      aria-busy={loading || undefined}

+      onClick={inactive ? undefined : onAction}

+      onMouseEnter={onHoverChange ? () => onHoverChange(true) : undefined}

+      onMouseLeave={onHoverChange ? () => onHoverChange(false) : undefined}

+    >

+      {loading ? (

+        // 스피너 비주얼은 시안 미정. 아이콘과 같은 크기라 전환 시 폭이 흔들리지 않는다.

+        <span className="fox-button__spinner" aria-hidden="true" />

+      ) : (

+        leadingIcon && (

+          <span className="fox-button__icon" aria-hidden="true">

+            {leadingIcon}

+          </span>

+        )

+      )}

+

+      <span className="fox-button__label">{label}</span>

+

+      {trailingIcon && (

+        <span className="fox-button__icon" aria-hidden="true">

+          {trailingIcon}

+        </span>

+      )}

+    </button>

+  );

+}

+export {

+  FoxButton,

+  type FoxButtonProps,

+  type FoxButtonType,

+  type FoxButtonSize,

+} from "./fox-button";

+"use client";

+

+import { useEffect, useId, useRef, useState, type ChangeEvent } from "react";

+import { cx } from "../../utils";

+import { FoxButton } from "../fox-button";

+import { FoxPhoneNumber } from "../fox-phone-number";

+

+export interface FoxCertifiedProps {

+  /** 전화번호. 숫자만 담긴 문자열이다 — `FoxPhoneNumber`와 같다. */

+  phone?: string;

+  defaultPhone?: string;

+  onPhoneChange?: (phone: string) => void;

+  /** 전화번호 앞자리 목록. 밖에서 받은 값을 칸으로 나눌 때도 쓴다. */

+  prefixOptions?: string[];

+

+  /**

+   * 인증번호 받기. resolve하면 성공으로 보고 인증번호 칸과 확인 버튼을 연다.

+   * throw하거나 reject하면 실패로 보고 `onSendFail`을 부른다.

+   */

+  onSend: (phone: string) => Promise<unknown>;

+  /** 인증번호 확인. resolve하면 성공, throw·reject하면 실패다. */

+  onVerify: (phone: string, code: string) => Promise<unknown>;

+

+  onSendSuccess?: () => void;

+  onSendFail?: (error: unknown) => void;

+  onVerifySuccess?: () => void;

+  onVerifyFail?: (error: unknown) => void;

+  /** 남은 시간이 0이 됐을 때 한 번 부른다. */

+  onExpire?: () => void;

+

+  /**

+   * 제한 시간(초). 주면 인증번호를 보낸 시점부터 컴포넌트가 직접 센다.

+   * `remainingSeconds`를 함께 주면 그쪽이 이긴다.

+   */

+  expiresIn?: number;

+  /** 남은 시간(초)을 직접 셀 때. 주면 컴포넌트는 세지 않고 이 값만 그린다. */

+  remainingSeconds?: number;

+

+  label?: string;

+  sendLabel?: string;

+  verifyLabel?: string;

+  codePlaceholder?: string;

+  codeMaxLength?: number;

+  /** 전체 잠금. 인증에 성공하면 이 값과 무관하게 잠긴다. */

+  disabled?: boolean;

+  /** 참이면 렌더하지 않는다(DOM에 남지 않는다). */

+  hidden?: boolean;

+  /** 배치 조정용. */

+  className?: string;

+}

+