@uniai-fe/uds-primitives 0.12.14 → 0.13.0

package/src/components/fab/styles/fab.scss

@@ -0,0 +1,140 @@
+.fab {
+  --fab-hover-shadow: none;
+  --fab-pressed-shadow: none;
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  width: var(--fab-height);
+  height: var(--fab-height);
+  padding: var(--fab-padding-block) var(--fab-padding-inline);
+  border: 0;
+  border-radius: var(--fab-radius);
+  background-color: var(--fab-background);
+  color: var(--fab-foreground);
+  box-shadow: none;
+  cursor: pointer;
+
+  // Button의 색상 토큰을 재사용하며 camelCase preset만 CSS token 이름으로 연결한다.
+  @each $priority,
+    $token
+      in (
+        "primary": "primary",
+        "secondary": "secondary",
+        "tertiary": "tertiary",
+        "green": "green",
+        "yellow": "yellow",
+        "orange": "orange",
+        "teal": "teal",
+        "pink": "pink",
+        "red": "red",
+        "darkGray": "dark-gray",
+        "lightGray": "light-gray"
+      )
+  {
+    &:where([data-fill="solid"][data-priority="#{$priority}"]) {
+      --fab-background: var(--button-default-#{$token}-solid-bg);
+      --fab-foreground: var(--button-default-#{$token}-solid-foreground);
+      --fab-hover-background: var(--button-default-#{$token}-solid-hover-bg);
+      --fab-pressed-background: var(--button-default-#{$token}-solid-active-bg);
+    }
+
+    &:where([data-fill="outlined"][data-priority="#{$priority}"]) {
+      --fab-background: var(--fab-outlined-background);
+      --fab-foreground: var(--button-default-#{$token}-outline-foreground);
+      --fab-hover-background: var(--button-default-#{$token}-outline-hover-bg);
+      // Semantic outlined의 pressed 색상은 아래 overlay에서 결정한다.
+      @if $priority !=
+        primary and
+        $priority !=
+        secondary and
+        $priority !=
+        tertiary
+      {
+        --fab-pressed-background: var(
+          --button-default-#{$token}-outline-active-bg
+        );
+      }
+      border: 1px solid var(--button-default-#{$token}-outline-border);
+    }
+  }
+
+  // Button의 semantic outlined와 solid tertiary는 동일한 흰색 inset overlay를 사용한다.
+  @each $priority in (primary, secondary, tertiary) {
+    &:where([data-fill="outlined"][data-priority="#{$priority}"]) {
+      --fab-hover-background: var(
+        --button-default-#{$priority}-overlay-outlined-bg
+      );
+      --fab-pressed-background: var(--fab-hover-background);
+      --fab-hover-shadow: inset 0 0 0 999px rgba(255, 255, 255, 0.68);
+      --fab-pressed-shadow: inset 0 0 0 999px rgba(255, 255, 255, 0.28);
+    }
+  }
+
+  &:where([data-fill="solid"][data-priority="tertiary"]) {
+    --fab-hover-background: var(--button-default-tertiary-overlay-solid-bg);
+    --fab-pressed-background: var(--fab-hover-background);
+    --fab-hover-shadow: inset 0 0 0 999px rgba(255, 255, 255, 0.68);
+    --fab-pressed-shadow: inset 0 0 0 999px rgba(255, 255, 255, 0.48);
+  }
+
+  &:where(:enabled:hover) {
+    background-color: var(--fab-hover-background);
+    box-shadow: var(--fab-hover-shadow);
+  }
+
+  &:where(:enabled:active) {
+    background-color: var(--fab-pressed-background);
+    box-shadow: var(--fab-pressed-shadow);
+  }
+
+  &:where(:focus-visible) {
+    outline: 2px solid var(--fab-focus-color);
+    outline-offset: 2px;
+  }
+
+  &:where(:disabled) {
+    background-color: var(--fab-disabled-background);
+    border-color: var(--fab-disabled-background);
+    --fab-foreground: var(--fab-disabled-foreground);
+    cursor: not-allowed;
+  }
+
+  @each $size in (small, medium, large) {
+    &:where([data-size="#{$size}"]) {
+      --fab-height: var(--fab-height-#{$size});
+      --fab-content-size: var(--fab-content-size-#{$size});
+      --fab-font-size: var(--fab-font-size-#{$size});
+    }
+  }
+
+  &:where([data-extended="true"]) {
+    width: fit-content;
+    min-width: var(--fab-height);
+    // 전역 button max-width가 줄바꿈 없는 라벨의 자연 너비를 제한하지 않게 한다.
+    max-width: none;
+    gap: var(--fab-gap);
+    padding-inline: var(--fab-extended-padding-inline);
+  }
+
+  :where(.fab-content) {
+    display: flex;
+    flex: 0 0 var(--fab-content-size);
+    align-items: center;
+    justify-content: center;
+    width: var(--fab-content-size);
+    height: var(--fab-content-size);
+    color: var(--fab-foreground);
+  }
+
+  :where(.fab-label) {
+    color: var(--fab-foreground);
+    font-family: var(--fab-font-family);
+    font-size: var(--fab-font-size);
+    font-weight: var(--fab-font-weight);
+    line-height: var(--fab-line-height);
+    letter-spacing: var(--fab-letter-spacing);
+    white-space: nowrap;
+  }
+}

package/src/components/fab/styles/index.scss

@@ -0,0 +1,4 @@
+@use "../../button/styles/variables" as button-variables;
+@use "./variables";
+@use "./fab";
+@use "./composition";

package/src/components/fab/styles/variables.scss

@@ -0,0 +1,25 @@
+:root {
+  --fab-height-small: var(--theme-size-medium-1);
+  --fab-height-medium: var(--theme-size-medium-2);
+  --fab-height-large: var(--theme-size-medium-3);
+  --fab-content-size-small: var(--theme-size-xsmall-3);
+  --fab-content-size-medium: var(--theme-size-small-1);
+  --fab-content-size-large: var(--theme-size-small-2);
+  // Figma의 60px radius는 Foundation에 동일한 token이 없다.
+  --fab-radius: 60px;
+  --fab-padding-inline: var(--spacing-padding-5);
+  --fab-padding-block: var(--spacing-padding-2);
+  --fab-extended-padding-inline: var(--spacing-padding-6);
+  --fab-gap: var(--spacing-gap-4);
+  --fab-font-family: var(--font-family-sans);
+  --fab-font-size-small: var(--font-body-xxsmall-size);
+  --fab-font-size-medium: var(--font-body-xsmall-size);
+  --fab-font-size-large: var(--font-body-small-size);
+  --fab-font-weight: var(--font-body-small-weight);
+  --fab-line-height: var(--font-body-small-line-height);
+  --fab-letter-spacing: var(--font-body-small-letter-spacing);
+  --fab-outlined-background: var(--button-default-outline-bg);
+  --fab-focus-color: var(--color-primary-default);
+  --fab-disabled-background: var(--button-default-neutral-disabled-bg);
+  --fab-disabled-foreground: var(--button-default-neutral-disabled-foreground);
+}

package/src/components/fab/types/composition.ts

@@ -0,0 +1,288 @@
+import type {
+  ComponentPropsWithoutRef,
+  FocusEventHandler,
+  MouseEventHandler,
+  ReactNode,
+  RefObject,
+} from "react";
+import type { FabDefaultProps } from "./props";
+
+/**
+ * Fab Types; 액션이 펼쳐지는 물리 방향
+ * @desc "up" | "down" | "left" | "right"를 지원하며 RTL에서도 물리 방향을 유지한다.
+ */
+export type FabDirection = "up" | "down" | "left" | "right";
+
+/**
+ * Fab Types; Root가 조립 부품에 제공하는 컨텍스트 값
+ * @property {boolean} open 현재 열림 상태. 제어형 open 또는 비제어형 내부 상태에서 계산한다.
+ * @property {"up" | "down" | "left" | "right"} direction 액션의 물리 펼침 방향. RTL에서도 좌우를 반전하지 않는다.
+ * @property {boolean} persistentTooltips 열린 액션의 이름을 hover 여부와 관계없이 계속 표시할지 결정한다.
+ * @property {string} triggerId Root가 생성한 Trigger ID. 별도 메뉴 이름이 없으면 목록의 aria-labelledby에 연결한다.
+ * @property {string} menuId Root가 생성한 목록 ID. Trigger의 aria-controls에 연결한다.
+ * @property {React.RefObject<HTMLButtonElement | null>} triggerRef Trigger DOM ref. 메뉴 탐색과 닫힘 뒤 focus 복귀에 사용한다.
+ * @property {React.RefObject<HTMLDivElement | null>} menuRef 목록 DOM ref. 액션 조회와 내부 focus 판별에 사용한다.
+ * @property {(restoreFocus: boolean) => void} onClose 닫힘을 요청하고 대기 중인 focus와 hover 진입을 초기화한다. true이면 Trigger로 focus를 복귀한다.
+ * @property {React.MouseEventHandler<HTMLButtonElement>} onTriggerClick Trigger 클릭의 열림 처리를 수행한다. hover로 열린 첫 포인터 클릭은 열림을 유지하고 이후 클릭·Enter·Space는 토글한다.
+ * @property {React.FocusEventHandler<HTMLButtonElement>} onTriggerFocus 키보드 focus 진입이면 열림을 요청한다. 메뉴에서 Trigger로 복귀하는 내부 focus 이동은 다시 열지 않는다.
+ * @desc FabRoot의 Provider가 값을 소유하고 Trigger·Menu 부품이 useFabContext로 조회한다. Provider 밖의 기본값 null은 이 값 타입에 포함하지 않으며 Hook이 오류로 처리한다. 제어형 상태에서 handler는 변경을 요청하고 소비자가 open에 반영한다.
+ */
+export interface FabContextValue {
+  /**
+   * 제어형 open 또는 비제어형 내부 상태에서 계산한 현재 열림 상태.
+   */
+  open: boolean;
+  /**
+   * 허용 값: "up" | "down" | "left" | "right". RTL에서도 물리 방향을 유지한다.
+   */
+  direction: FabDirection;
+  /**
+   * true이면 열린 액션의 이름을 hover 여부와 관계없이 계속 표시한다.
+   */
+  persistentTooltips: boolean;
+  /**
+   * Root가 생성한 Trigger ID. 별도 메뉴 이름이 없으면 목록의 aria-labelledby에 연결한다.
+   */
+  triggerId: string;
+  /**
+   * Root가 생성한 목록 ID. Trigger의 aria-controls에 연결한다.
+   */
+  menuId: string;
+  /**
+   * 실제 Trigger 버튼의 DOM ref. 메뉴 탐색과 닫힘 뒤 focus 복귀에 사용한다.
+   */
+  triggerRef: RefObject<HTMLButtonElement | null>;
+  /**
+   * 실제 목록 div의 DOM ref. 액션 조회와 내부 focus 판별에 사용한다.
+   */
+  menuRef: RefObject<HTMLDivElement | null>;
+  /**
+   * 닫힘을 요청하고 대기 중인 focus와 hover 진입을 초기화한다.
+   * restoreFocus가 true이면 Trigger로 focus를 복귀한다. 제어형 open은 소비자가 반영한다.
+   */
+  onClose: (restoreFocus: boolean) => void;
+  /**
+   * hover로 열린 첫 포인터 클릭은 열림을 유지하고 이후 클릭·Enter·Space는 토글한다.
+   * Trigger가 소비자 onClick을 먼저 호출하고 preventDefault하지 않은 이벤트를 전달한다.
+   */
+  onTriggerClick: MouseEventHandler<HTMLButtonElement>;
+  /**
+   * 키보드 focus 진입이면 열림을 요청하며 메뉴에서 Trigger로 돌아오는 내부 이동은 생략한다.
+   * Trigger가 소비자 onFocus를 먼저 호출하고 preventDefault하지 않은 이벤트를 전달한다.
+   */
+  onTriggerFocus: FocusEventHandler<HTMLButtonElement>;
+}
+
+/**
+ * Fab Props; 공통 액션 조합과 열림 상태
+ * @property {ReactNode} children Trigger 하나와 Menu.List 하나의 조합.
+ * @property {"up" | "down" | "left" | "right"} [direction="up"] 액션의 물리 펼침 방향. RTL에서도 물리 좌우를 유지한다.
+ * @property {boolean} [persistentTooltips=false] 열린 액션의 이름을 hover 여부와 관계없이 계속 표시한다.
+ * @property {boolean} [open] 제어형 열림 상태. 지정하면 소비자가 onOpenChange의 요청을 반영한다.
+ * @property {boolean} [defaultOpen=false] 비제어형 최초 열림 상태. open이 지정되면 사용하지 않는다.
+ * @property {(open: boolean) => void} [onOpenChange] 현재 open과 다른 열림 변경 요청을 전달한다. 제어형·비제어형 모두에서 호출한다.
+ * @property {string} [className] 최상위 Root div에 병합하는 추가 클래스.
+ * @property {React.CSSProperties} [style] 최상위 Root div에 전달하는 inline style.
+ * @property {(event: React.FocusEvent<HTMLDivElement>) => void} [onBlur] Root의 닫힘 처리 전에 호출한다. preventDefault하면 외부 focus 이동에 따른 닫힘만 생략한다.
+ * @property {(event: React.KeyboardEvent<HTMLDivElement>) => void} [onKeyDown] Root의 방향키·Home·End·Escape 처리 전에 호출한다. preventDefault하면 Root의 해당 처리를 생략한다. 열린 Tooltip의 Escape는 document capture에서 먼저 닫는다.
+ * @property {(event: React.PointerEvent<HTMLDivElement>) => void} [onPointerEnter] Root의 mouse hover 열림 전에 호출한다. 닫힌 상태의 포인터 진입 대상은 Trigger다. preventDefault하거나 Trigger가 disabled이면 hover로 열지 않는다.
+ * @property {(event: React.PointerEvent<HTMLDivElement>) => void} [onPointerLeave] Root의 포인터 이탈 닫힘 전에 호출한다. preventDefault하거나 focus가 Root 안에 있으면 닫지 않는다.
+ * @property {(event: React.MouseEvent<HTMLDivElement>) => void} [onClick] Root div의 native 클릭 handler. Trigger·Menu.Item의 클릭이 버블링되며 해당 부품의 처리는 먼저 실행된다.
+ * @desc native div 입력과 컴포넌트의 Root DOM ref를 유지한다. Root 하나에 Trigger 하나와 Menu.List 하나를 조립한다. Escape·항목 선택은 닫고 Trigger로 focus를 복귀하며 외부 Tab은 이동한 focus를 유지한다. 열린 Tooltip의 Escape는 document capture에서 먼저 처리하므로 onKeyDown 취소보다 앞선다. 화면 배치와 액션 실행은 소비자의 책임이다.
+ */
+export interface FabRootProps extends ComponentPropsWithoutRef<"div"> {
+  /**
+   * Root의 상태를 공유하는 Trigger 하나와 Menu.List 하나의 조합.
+   */
+  children: ReactNode;
+  /**
+   * 허용 값: "up" | "down" | "left" | "right". 기본값은 "up"이다.
+   */
+  direction?: FabDirection;
+  /**
+   * 기본값 false. true이면 열린 액션의 툴팁을 hover 여부와 관계없이 계속 표시한다.
+   */
+  persistentTooltips?: boolean;
+  /**
+   * 제어형 상태. onOpenChange의 변경 요청을 소비자가 반영한다.
+   */
+  open?: boolean;
+  /**
+   * 기본값 false인 비제어형 최초 열림 상태. open이 지정되면 사용하지 않는다.
+   */
+  defaultOpen?: boolean;
+  /**
+   * 현재 open과 다른 열림 변경 요청을 제어형·비제어형 모두에서 전달한다.
+   * 제어형에서는 소비자가 요청한 값을 open에 반영한다.
+   */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Fab Props; Root와 연결하는 아이콘 버튼
+ * @property {"small" | "medium" | "large"} size 필수 크기. small/medium/large의 높이는 40/48/56px, icon 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} fill 모든 priority에서 선택하는 필수 채움 스타일.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} priority solid와 outlined 모두에서 필수인 색상.
+ * @property {ReactNode} icon 필수 장식용 콘텐츠. icon 영역은 aria-hidden이므로 행동 이름을 대신하지 않는다.
+ * @property {string} aria-label 필수 행동 이름. icon 콘텐츠는 접근 가능한 이름에서 제외된다.
+ * @property {"button" | "submit" | "reset"} [type="button"] native 버튼 종류. submit과 reset은 소비자가 명시한다.
+ * @property {boolean} [disabled] native 클릭·키보드 실행을 차단한다.
+ * @property {string} [className] 최상위 native 버튼에 병합하는 추가 클래스.
+ * @property {React.CSSProperties} [style] 최상위 native 버튼에 전달하는 inline style.
+ * @property {(event: React.MouseEvent<HTMLButtonElement>) => void} [onClick] 기본 클릭 처리 전에 호출한다. preventDefault하면 처리를 생략한다. hover로 열린 첫 pointer 클릭은 열림을 유지하고 이후 클릭과 Enter·Space는 토글한다.
+ * @property {(event: React.FocusEvent<HTMLButtonElement>) => void} [onFocus] 키보드 focus 진입에 따른 열림 전에 호출한다. preventDefault하면 해당 열림을 생략한다.
+ * @property {(event: React.KeyboardEvent<HTMLButtonElement>) => void} [onKeyDown] native 버튼 handler. Root로 버블링되는 메뉴 탐색을 preventDefault로 취소할 수 있다. 열린 Tooltip의 Escape는 document capture에서 먼저 처리한다.
+ * @desc FabDefaultProps의 native 버튼 계약에서 id·aria-haspopup·aria-expanded·aria-controls를 제외한다. 해당 ID와 menu ARIA는 Root가 생성하며 DOM ref도 Root와 공유한다. Root 밖에서 사용하면 오류를 발생시킨다.
+ * @see FabDefaultProps
+ */
+export type FabTriggerProps = Omit<
+  FabDefaultProps,
+  "id" | "aria-haspopup" | "aria-expanded" | "aria-controls"
+>;
+
+/**
+ * Fab Props; 원점을 유지하는 액션 목록
+ * @property {ReactNode} [children] 공개 Menu.Item의 조합.
+ * @property {string} [aria-label] 별도 메뉴 이름. 없거나 빈 문자열이면 Root가 Trigger의 ID로 aria-labelledby를 연결한다.
+ * @property {string} [className] 메뉴 목록 div에 병합하는 추가 클래스.
+ * @property {React.CSSProperties} [style] 메뉴 목록 div에 전달하는 inline style.
+ * @property {(event: React.MouseEvent<HTMLDivElement>) => void} [onClick] 목록 div의 native 클릭 handler. Menu.Item의 클릭 처리 뒤 버블링된다.
+ * @property {(event: React.KeyboardEvent<HTMLDivElement>) => void} [onKeyDown] 목록 div의 native handler. Root로 버블링되는 메뉴 탐색을 preventDefault로 취소할 수 있다. 열린 Tooltip의 Escape는 먼저 처리한다.
+ * @desc native div 입력에서 id·role·hidden·inert·aria-hidden·aria-orientation·aria-labelledby를 제외한다. Root가 ID·menu role·orientation과 Trigger 이름을 연결한다. 닫히면 배치 공간을 유지하고 aria-hidden=true·inert=true로 접근성·focus 탐색에서 제외한다. ref는 실제 목록 div에 연결한다. Root 밖에서 사용하면 오류를 발생시킨다.
+ */
+export type FabMenuListProps = Omit<
+  ComponentPropsWithoutRef<"div">,
+  | "id"
+  | "role"
+  | "hidden"
+  | "inert"
+  | "aria-hidden"
+  | "aria-orientation"
+  | "aria-labelledby"
+>;
+
+/**
+ * Fab Props; 이름과 선택 동작을 가진 액션 버튼
+ * @property {"small" | "medium" | "large"} size 필수 크기. small/medium/large의 높이는 40/48/56px, icon 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} fill 모든 priority에서 선택하는 필수 채움 스타일.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} priority solid와 outlined 모두에서 필수인 색상.
+ * @property {ReactNode} icon 필수 장식용 콘텐츠. icon 영역은 aria-hidden이므로 행동 이름을 대신하지 않는다.
+ * @property {string} aria-label 필수 행동 이름. icon 콘텐츠는 접근 가능한 이름에서 제외된다.
+ * @property {"button" | "submit" | "reset"} [type="button"] native 버튼 종류. submit과 reset은 소비자가 명시한다.
+ * @property {boolean} [disabled] native 클릭·키보드 실행을 차단한다. 방향키 탐색에서도 제외한다.
+ * @property {string} [className] 최상위 native 버튼에 병합하는 추가 클래스.
+ * @property {React.CSSProperties} [style] 최상위 native 버튼에 전달하는 inline style.
+ * @property {(event: React.MouseEvent<HTMLButtonElement>) => void} [onClick] 선택 시 먼저 호출한다. preventDefault하지 않으면 닫고 Trigger로 focus를 복귀한다. 서비스 실행과 결과 상태는 소비자가 처리한다.
+ * @property {string} [id] native 버튼의 DOM ID.
+ * @property {"top" | "right" | "bottom" | "left"} [tooltipSide] Tooltip 방향. 세로 메뉴는 left, 가로 메뉴는 top이 기본이다.
+ * @property {(event: React.FocusEvent<HTMLButtonElement>) => void} [onFocus] native 액션 버튼 focus handler.
+ * @property {(event: React.KeyboardEvent<HTMLButtonElement>) => void} [onKeyDown] native 액션 버튼 handler. Root로 버블링되는 탐색을 preventDefault로 취소할 수 있다. 열린 Tooltip의 Escape는 document capture에서 먼저 닫는다.
+ * @desc FabDefaultProps에서 role·tabIndex를 제외하고 tooltipSide를 추가한다. aria-label은 버튼 이름과 Tooltip 문구로 사용한다. role=menuitem과 tabIndex=-1은 메뉴 탐색이 소유한다. DOM ref는 실제 액션 버튼에 연결한다. Root 밖에서 사용하면 오류를 발생시킨다.
+ * @see FabDefaultProps
+ */
+export type FabMenuItemProps = Omit<FabDefaultProps, "role" | "tabIndex"> & {
+  /**
+   * 허용 값: "top" | "right" | "bottom" | "left".
+   * 생략하면 세로 메뉴는 "left", 가로 메뉴는 "top"을 사용한다.
+   */
+  tooltipSide?: "top" | "right" | "bottom" | "left";
+};
+
+/**
+ * Fab Types; 기본 조합에 전달하는 액션 항목
+ * @property {string} id 필수 고유 DOM ID와 React 조합 key. 같은 화면에서 중복하지 않는다.
+ * @property {"small" | "medium" | "large"} size 필수 크기. small/medium/large의 높이는 40/48/56px, icon 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} fill 모든 priority에서 선택하는 필수 채움 스타일.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} priority solid와 outlined 모두에서 필수인 색상.
+ * @property {ReactNode} icon 필수 장식용 콘텐츠. icon 영역은 aria-hidden이므로 행동 이름을 대신하지 않는다.
+ * @property {string} aria-label 필수 행동 이름. icon 콘텐츠는 접근 가능한 이름에서 제외된다.
+ * @property {"button" | "submit" | "reset"} [type="button"] native 버튼 종류. submit과 reset은 소비자가 명시한다.
+ * @property {boolean} [disabled] native 클릭·키보드 실행을 차단한다. 방향키 탐색에서도 제외한다.
+ * @property {React.CSSProperties} [style] 최상위 native 버튼에 전달하는 inline style.
+ * @property {(event: React.MouseEvent<HTMLButtonElement>) => void} [onClick] 선택 시 먼저 호출한다. preventDefault하지 않으면 닫고 Trigger로 focus를 복귀한다. 서비스 실행과 결과 상태는 소비자가 처리한다.
+ * @property {"top" | "right" | "bottom" | "left"} [tooltipSide] Tooltip 방향. 세로 메뉴는 left, 가로 메뉴는 top이 기본이다.
+ * @property {(event: React.FocusEvent<HTMLButtonElement>) => void} [onFocus] native 액션 버튼 focus handler.
+ * @property {(event: React.KeyboardEvent<HTMLButtonElement>) => void} [onKeyDown] native 액션 버튼 handler. Root로 버블링되는 탐색을 preventDefault로 취소할 수 있다. 열린 Tooltip의 Escape는 document capture에서 먼저 닫는다.
+ * @desc FabMenuItemProps에서 className을 제외하고 필수 id를 추가한다. 내부 스타일은 Template 최상위 className의 nested selector 또는 data attribute로 조정한다. Template이 id를 버튼 DOM ID와 조합 key로 사용하며 필수 icon·size·fill·priority·aria-label과 native 버튼 callback을 각 Menu.Item에 전달한다. 액션 실행과 결과 상태는 소비자의 책임이다.
+ * @see FabMenuItemProps
+ */
+export type FabTemplateItem = Omit<FabMenuItemProps, "className"> & {
+  /**
+   * 버튼의 고유 DOM ID와 목록 key로 사용한다. 같은 화면에서 중복하지 않는다.
+   */
+  id: string;
+};
+
+/**
+ * Fab Props; 공개 부품으로 구성한 기본 액션 조합
+ * @property {"up" | "down" | "left" | "right"} [direction="up"] 액션의 물리 펼침 방향. RTL에서도 물리 좌우를 유지한다.
+ * @property {boolean} [persistentTooltips=false] 열린 액션의 이름을 hover 여부와 관계없이 계속 표시한다.
+ * @property {boolean} [open] 제어형 열림 상태. 지정하면 소비자가 onOpenChange의 요청을 반영한다.
+ * @property {boolean} [defaultOpen=false] 비제어형 최초 열림 상태. open이 지정되면 사용하지 않는다.
+ * @property {(open: boolean) => void} [onOpenChange] 현재 open과 다른 열림 변경 요청을 전달한다. 제어형·비제어형 모두에서 호출한다.
+ * @property {string} [className] 최상위 Root div에 병합하는 추가 클래스.
+ * @property {React.CSSProperties} [style] 최상위 Root div에 전달하는 inline style.
+ * @property {(event: React.FocusEvent<HTMLDivElement>) => void} [onBlur] Root의 닫힘 처리 전에 호출한다. preventDefault하면 외부 focus 이동에 따른 닫힘만 생략한다.
+ * @property {(event: React.KeyboardEvent<HTMLDivElement>) => void} [onKeyDown] Root의 방향키·Home·End·Escape 처리 전에 호출한다. preventDefault하면 Root의 해당 처리를 생략한다. 열린 Tooltip의 Escape는 document capture에서 먼저 닫는다.
+ * @property {(event: React.PointerEvent<HTMLDivElement>) => void} [onPointerEnter] Root의 mouse hover 열림 전에 호출한다. 닫힌 상태의 포인터 진입 대상은 Trigger다. preventDefault하거나 Trigger가 disabled이면 hover로 열지 않는다.
+ * @property {(event: React.PointerEvent<HTMLDivElement>) => void} [onPointerLeave] Root의 포인터 이탈 닫힘 전에 호출한다. preventDefault하거나 focus가 Root 안에 있으면 닫지 않는다.
+ * @property {(event: React.MouseEvent<HTMLDivElement>) => void} [onClick] Root div의 native 클릭 handler. Trigger·Menu.Item의 클릭이 버블링되며 해당 부품의 처리는 먼저 실행된다.
+ * @property {Omit<FabTriggerProps, "className">} triggerProps 필수 Trigger 입력. id와 menu ARIA는 Root가 생성한다.
+ * @property {ReactNode} triggerProps.icon Trigger의 필수 장식용 콘텐츠.
+ * @property {"small" | "medium" | "large"} triggerProps.size Trigger의 필수 크기. 높이는 40/48/56px, icon 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} triggerProps.fill Trigger의 필수 채움 스타일.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} triggerProps.priority Trigger의 필수 색상.
+ * @property {string} triggerProps.aria-label Trigger와 기본 메뉴 이름으로 쓰는 필수 행동 이름.
+ * @property {"button" | "submit" | "reset"} [triggerProps.type="button"] Trigger의 native 버튼 종류.
+ * @property {boolean} [triggerProps.disabled] Trigger의 native 실행과 Root mouse hover 열림을 차단한다.
+ * @property {React.CSSProperties} [triggerProps.style] Trigger 버튼에 전달하는 inline style.
+ * @property {(event: React.MouseEvent<HTMLButtonElement>) => void} [triggerProps.onClick] 기본 클릭 처리 전에 호출한다. preventDefault하면 처리를 생략한다. hover로 열린 첫 pointer 클릭은 열림을 유지하고 이후 클릭과 Enter·Space는 토글한다.
+ * @property {(event: React.FocusEvent<HTMLButtonElement>) => void} [triggerProps.onFocus] 키보드 focus 진입 열림 전에 호출한다. preventDefault하면 해당 열림을 생략한다.
+ * @property {(event: React.KeyboardEvent<HTMLButtonElement>) => void} [triggerProps.onKeyDown] Trigger의 native handler. Root 탐색 취소 범위와 Tooltip Escape 선처리 제한은 FabTriggerProps와 같다.
+ * @property {FabTemplateItem[]} items 필수 액션 배열. 빈 배열도 허용한다.
+ * @property {string} items[].id 각 항목의 필수 고유 DOM ID와 React 조합 key. 같은 화면에서 중복하지 않는다.
+ * @property {ReactNode} items[].icon 각 액션의 필수 장식용 콘텐츠.
+ * @property {"small" | "medium" | "large"} items[].size 각 액션의 필수 크기. 높이는 40/48/56px, icon 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} items[].fill 각 액션의 필수 채움 스타일.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} items[].priority 각 액션의 필수 색상.
+ * @property {string} items[].aria-label 각 액션의 필수 행동 이름과 Tooltip 문구.
+ * @property {"button" | "submit" | "reset"} [items[].type="button"] 각 액션의 native 버튼 종류.
+ * @property {boolean} [items[].disabled] 해당 액션의 native 실행과 방향키 탐색을 차단한다.
+ * @property {React.CSSProperties} [items[].style] 해당 액션 버튼에 전달하는 inline style.
+ * @property {"top" | "right" | "bottom" | "left"} [items[].tooltipSide] Tooltip 방향. 생략하면 세로 메뉴 left, 가로 메뉴 top을 사용한다.
+ * @property {(event: React.MouseEvent<HTMLButtonElement>) => void} [items[].onClick] 해당 액션 선택 callback. preventDefault하지 않으면 닫고 Trigger로 focus를 복귀한다.
+ * @property {(event: React.FocusEvent<HTMLButtonElement>) => void} [items[].onFocus] 해당 액션 버튼의 native focus handler.
+ * @property {(event: React.KeyboardEvent<HTMLButtonElement>) => void} [items[].onKeyDown] 해당 액션의 native handler. Root 탐색 취소 범위와 Tooltip Escape 선처리 제한은 FabMenuItemProps와 같다.
+ * @desc FabRootProps에서 children을 제외하고 triggerProps와 items를 추가한다. 공개 Root·Trigger·Menu.List·Menu.Item으로 조립하며 상속받은 상태·이벤트·className·style과 컴포넌트 ref는 최상위 Root에만 적용한다. Trigger와 각 액션의 native 입력은 nested props로 전달하되 className은 받지 않는다. 내부 스타일은 최상위 className의 nested selector 또는 data attribute로 조정한다. 서비스 실행·선택 결과는 items의 callback을 통해 소비자가 처리한다.
+ * @see FabRootProps
+ * @see FabTriggerProps
+ * @see FabTemplateItem
+ */
+export interface FabTemplateProps extends Omit<FabRootProps, "children"> {
+  /**
+   * Root의 메뉴를 여는 필수 아이콘 버튼 입력.
+   * icon: ReactNode와 aria-label: string이 필수다.
+   * size는 필수이며 허용 값은 "small" | "medium" | "large"다.
+   * fill은 필수이며 허용 값은 "solid" | "outlined"다.
+   * priority는 필수이며 허용 값은 "primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"다.
+   * type 허용 값: "button" | "submit" | "reset". 기본값은 "button"이다.
+   * disabled, style과 native 이벤트를 Trigger에 전달한다. className은 받지 않으며 런타임 입력도 무시한다.
+   * onClick/onFocus가 preventDefault하면 해당 기본 클릭/열림을 생략한다.
+   * hover로 열린 첫 pointer 클릭은 열림을 유지하고 이후 클릭과 Enter·Space는 토글한다.
+   * id와 menu ARIA는 Root가 생성하며 이 object로 override하지 않는다.
+   */
+  triggerProps: Omit<FabTriggerProps, "className">;
+  /**
+   * 필수 액션 배열. 빈 배열도 허용한다.
+   * 각 항목의 id: string, icon: ReactNode, aria-label: string이 필수다.
+   * id는 버튼 DOM ID와 React 조합 key이며 같은 화면에서 중복하지 않는다.
+   * size는 필수이며 허용 값은 "small" | "medium" | "large"다.
+   * fill은 필수이며 허용 값은 "solid" | "outlined"다.
+   * priority는 필수이며 허용 값은 "primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"다.
+   * type 허용 값: "button" | "submit" | "reset". 기본값은 "button"이다.
+   * tooltipSide 허용 값: "top" | "right" | "bottom" | "left". 생략하면 세로 메뉴 left, 가로 메뉴 top을 사용한다.
+   * disabled, style과 native 이벤트를 각 Menu.Item에 전달한다. className은 받지 않으며 런타임 입력도 무시한다.
+   * onClick 뒤 preventDefault가 없으면 닫고 Trigger로 focus를 복귀한다.
+   */
+  items: FabTemplateItem[];
+}

package/src/components/fab/types/index.ts

@@ -0,0 +1,3 @@
+export type * from "./options";
+export type * from "./props";
+export type * from "./composition";

package/src/components/fab/types/options.ts

@@ -0,0 +1,39 @@
+import { BUTTON_FILLS, BUTTON_PRIORITIES } from "../../button/types/options";
+import type { ButtonFill, ButtonPriority } from "../../button/types/props";
+
+/**
+ * Fab Types; 크기 옵션
+ * @desc Figma small 40px, medium 48px, large 56px에 대응한다.
+ */
+export type FabSize = "small" | "medium" | "large";
+
+/**
+ * Fab Types; 채움 스타일
+ * @desc Button과 같은 "solid" | "outlined" 축이며 모든 priority에 적용한다.
+ */
+export type FabFill = ButtonFill;
+
+/**
+ * Fab Types; 색상 priority
+ * @desc Button과 같은 "primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"를 두 fill 모두에 적용한다.
+ * @see ButtonPriority
+ */
+export type FabPriority = ButtonPriority;
+
+/**
+ * Fab Options; 공개 크기 목록
+ * @desc Controls와 소비 예시에서 Figma 크기 축을 공유한다.
+ */
+export const FAB_SIZES = ["small", "medium", "large"] as const;
+
+/**
+ * Fab Options; 공개 채움 스타일 목록
+ * @desc 채움과 외곽선을 독립된 시각 옵션으로 선택한다.
+ */
+export const FAB_FILLS = [...BUTTON_FILLS] as const;
+
+/**
+ * Fab Options; 공개 색상 priority 목록
+ * @desc Button의 semantic priority와 고정 색상 preset 목록을 공유한다.
+ */
+export const FAB_PRIORITIES = [...BUTTON_PRIORITIES] as const;

package/src/components/fab/types/props.ts

@@ -0,0 +1,124 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { FabFill, FabPriority, FabSize } from "./options";
+
+/**
+ * Fab Types; 시각 옵션의 조합 계약
+ * @property {"solid" | "outlined"} fill 모든 priority에서 선택하는 필수 채움 스타일.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} priority 두 fill 모두에서 필수인 색상.
+ * @desc Button의 색상 계약을 재사용하며 priority와 fill을 독립적으로 조합한다. outlined의 기본 면은 불투명 흰색이다.
+ */
+export type FabStyleOptions = {
+  /**
+   * 허용 값: "solid" | "outlined". 모든 priority에서 필수다.
+   */
+  fill: FabFill;
+  /**
+   * 허용 값: "primary" | "secondary" | "tertiary" | "green" | "yellow" |
+   * "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray".
+   * 두 fill 모두에서 필수이며 배경·외곽선·콘텐츠 색상을 결정한다.
+   */
+  priority: FabPriority;
+};
+
+/**
+ * Fab Props; 공통 native 버튼 계약
+ * @property {"small" | "medium" | "large"} size 필수 크기. small/medium/large의 높이는 40/48/56px, icon 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} fill 모든 priority에서 선택하는 필수 채움 스타일.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} priority solid와 outlined 모두에서 필수인 색상.
+ * @property {ReactNode} icon 필수 장식용 콘텐츠. icon 영역은 aria-hidden이므로 행동 이름을 대신하지 않는다.
+ * @property {string} [aria-label] native 접근 가능한 이름. 표시 라벨과 별도 이름이 필요할 때 제공한다.
+ * @property {"button" | "submit" | "reset"} [type="button"] native 버튼 종류. submit과 reset은 소비자가 명시한다.
+ * @property {boolean} [disabled] native 클릭·키보드 실행을 차단한다.
+ * @property {string} [className] 최상위 native 버튼에 병합하는 추가 클래스.
+ * @property {React.CSSProperties} [style] 최상위 native 버튼에 전달하는 inline style.
+ * @property {(event: React.MouseEvent<HTMLButtonElement>) => void} [onClick] native 클릭 handler. Enter·Space의 native 버튼 실행에서도 호출한다.
+ * @desc FabStyleOptions와 children을 제외한 native button 입력을 조합한다. size·fill·priority·icon은 필수이며 나머지 native button 이벤트와 aria attribute를 유지한다. ref는 각 컴포넌트의 forwardRef로 native 버튼에 연결한다. viewport 배치는 소비자의 책임이다.
+ * @see FabStyleOptions
+ */
+export type FabProps = Omit<ComponentPropsWithoutRef<"button">, "children"> &
+  FabStyleOptions & {
+    /**
+     * 필수 크기. 허용 값: "small" | "medium" | "large".
+     * 높이는 각각 40/48/56px, icon 영역은 16/20/24px다.
+     */
+    size: FabSize;
+    /**
+     * 필수 ReactNode 영역. 아이콘 외에도 비인터랙티브 콘텐츠를 받을 수 있다.
+     * 내부 콘텐츠는 aria-hidden으로 처리하므로 행동 이름은 버튼 라벨로 제공한다.
+     */
+    icon: ReactNode;
+  };
+
+/**
+ * Fab Props; 아이콘 전용 액션
+ * @property {"small" | "medium" | "large"} size 필수 크기. small/medium/large의 높이는 40/48/56px, icon 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} fill 모든 priority에서 선택하는 필수 채움 스타일.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} priority solid와 outlined 모두에서 필수인 색상.
+ * @property {ReactNode} icon 필수 장식용 콘텐츠. icon 영역은 aria-hidden이므로 행동 이름을 대신하지 않는다.
+ * @property {string} aria-label 필수 행동 이름. icon 콘텐츠는 접근 가능한 이름에서 제외된다.
+ * @property {"button" | "submit" | "reset"} [type="button"] native 버튼 종류. submit과 reset은 소비자가 명시한다.
+ * @property {boolean} [disabled] native 클릭·키보드 실행을 차단한다.
+ * @property {string} [className] 최상위 native 버튼에 병합하는 추가 클래스.
+ * @property {React.CSSProperties} [style] 최상위 native 버튼에 전달하는 inline style.
+ * @property {(event: React.MouseEvent<HTMLButtonElement>) => void} [onClick] native 클릭 handler. Enter·Space의 native 버튼 실행에서도 호출한다.
+ * @desc FabProps에 필수 aria-label을 추가한 Fab.Button과 호환 이름 Fab.Default의 계약이다. children을 받지 않으며 icon은 장식용으로 처리한다. 다른 native button 입력과 컴포넌트의 DOM ref를 유지한다.
+ * @see FabProps
+ */
+export type FabDefaultProps = FabProps & {
+  /**
+   * 아이콘이 실행하는 행동을 설명하는 필수 접근 가능한 이름.
+   */
+  "aria-label": string;
+};
+
+/**
+ * Fab Props; 아이콘과 라벨을 나란히 표시하는 확장형 액션
+ * @property {"small" | "medium" | "large"} size 필수 크기. small/medium/large의 높이는 40/48/56px, icon 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} fill 모든 priority에서 선택하는 필수 채움 스타일.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} priority solid와 outlined 모두에서 필수인 색상.
+ * @property {ReactNode} icon 필수 장식용 콘텐츠. icon 영역은 aria-hidden이므로 행동 이름을 대신하지 않는다.
+ * @property {string} [aria-label] native 접근 가능한 이름. 표시 라벨과 별도 이름이 필요할 때 제공한다.
+ * @property {"button" | "submit" | "reset"} [type="button"] native 버튼 종류. submit과 reset은 소비자가 명시한다.
+ * @property {boolean} [disabled] native 클릭·키보드 실행을 차단한다.
+ * @property {string} [className] 최상위 native 버튼에 병합하는 추가 클래스.
+ * @property {React.CSSProperties} [style] 최상위 native 버튼에 전달하는 inline style.
+ * @property {(event: React.MouseEvent<HTMLButtonElement>) => void} [onClick] native 클릭 handler. Enter·Space의 native 버튼 실행에서도 호출한다.
+ * @property {ReactNode} children 필수 행동 라벨. 문자열·숫자는 Fab.Label로 감싸고 다른 ReactNode는 그대로 표시한다.
+ * @desc FabProps에 필수 children을 추가한 Fab.Expand와 호환 이름 Fab.Extended의 계약이다. icon과 행동 라벨을 나란히 표시하며 다른 native button 입력과 컴포넌트의 DOM ref를 유지한다. 액션 목록의 열림을 담당하지 않는다.
+ * @see FabProps
+ */
+export type FabExtendedProps = FabProps & {
+  /**
+   * 필수 행동 라벨. 문자열·숫자는 Fab.Label로 감싸고 복합 JSX는 그대로 표시한다.
+   * 복합 JSX에도 접근 가능한 이름과 필요한 라벨 스타일을 제공한다.
+   */
+  children: ReactNode;
+};
+
+/**
+ * Fab Props; 내부 공통 마크업 입력
+ * @property {"small" | "medium" | "large"} size 필수 크기. small/medium/large의 높이는 40/48/56px, icon 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} fill 모든 priority에서 선택하는 필수 채움 스타일.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} priority solid와 outlined 모두에서 필수인 색상.
+ * @property {ReactNode} icon 필수 장식용 콘텐츠. icon 영역은 aria-hidden이므로 행동 이름을 대신하지 않는다.
+ * @property {string} [aria-label] native 접근 가능한 이름. 표시 라벨과 별도 이름이 필요할 때 제공한다.
+ * @property {"button" | "submit" | "reset"} [type="button"] native 버튼 종류. submit과 reset은 소비자가 명시한다.
+ * @property {boolean} [disabled] native 클릭·키보드 실행을 차단한다.
+ * @property {string} [className] 최상위 native 버튼에 병합하는 추가 클래스.
+ * @property {React.CSSProperties} [style] 최상위 native 버튼에 전달하는 inline style.
+ * @property {(event: React.MouseEvent<HTMLButtonElement>) => void} [onClick] native 클릭 handler. Enter·Space의 native 버튼 실행에서도 호출한다.
+ * @property {ReactNode} [children] extended가 true일 때 표시하는 행동 라벨.
+ * @property {boolean} [extended=false] true이면 라벨과 자연 너비 규격을 적용한다. false이면 원형 icon 버튼 규격을 적용한다.
+ * @desc FabProps를 상속한 내부 마크업 계약이다. Fab.Button/Fab.Default는 extended=false, Fab.Expand/Fab.Extended는 extended=true로 같은 native button을 사용한다. 다른 native button 입력과 컴포넌트의 DOM ref를 유지한다.
+ * @see FabProps
+ */
+export type FabButtonProps = FabProps & {
+  /**
+   * 확장형에서 사용하는 라벨.
+   */
+  children?: ReactNode;
+  /**
+   * 기본값 false. true이면 라벨과 자연 너비 규격을, false이면 원형 아이콘 규격을 적용한다.
+   */
+  extended?: boolean;
+};