@uniai-fe/uds-primitives 0.12.14 → 0.13.0

package/README.md

@@ -46,6 +46,74 @@ Button은 기존 priority 범위를 유지한다.
 `Input.Time.Template`과 standalone `TimePicker.Template`, `TimePickerUtils`도 root public
 entry에서 제공한다.
 
+`Fab.Button`은 아이콘 전용 주요 액션, `Fab.Expand`는 아이콘과 라벨을 표시한다.
+필수 `icon`은 ReactNode이며 `size`는 `small | medium | large`다. Button과 같은
+`fill="solid" | "outlined"`와 `priority`를 독립적으로 조합한다. 두 fill 모두 `priority`가
+필수이며 Button.Default와 같은 `primary`, `secondary`, `tertiary`, `green`, `yellow`,
+`orange`, `teal`, `pink`, `red`, `darkGray`, `lightGray`를 지원한다. 색상과 상태별 배경은
+Button 토큰을 재사용하며 outlined의 기본 면은 불투명 흰색이다.
+아이콘 전용 Button에는 행동 이름인 `aria-label`도 필수다. 화면 고정 배치는 소비자가 정한다.
+`Fab.Default`, `Fab.Extended`, `Fab.Label`은 기존 사용처와의 호환을 유지한다.
+
+```tsx
+import { Fab } from "@uniai-fe/uds-primitives";
+
+<Fab.Button
+  icon={<span aria-hidden="true">+</span>}
+  aria-label="항목 추가"
+  fill="solid"
+  priority="primary"
+  size="medium"
+/>;
+```
+
+관련 액션을 원형 버튼으로 펼치는 구성은 `Fab.Template`으로 시작하거나
+`Fab.Root` 안에 `Fab.Trigger`, `Fab.Menu.List`, `Fab.Menu.Item`을 직접 조립한다.
+`Fab.Expand`는 라벨 확장형이고, 메뉴를 펼치는 동작은 `Fab.Trigger`가 담당한다.
+`Root`는 hover·focus·click·keyboard, 메뉴 ID·ARIA 연결, 닫기와 focus 복귀를 소유한다.
+`direction`은 `up | down | left | right`이며 기본값은 `up`이다. 열림 상태는
+`open`과 `onOpenChange`로 제어하거나 `defaultOpen`으로 초기화한다.
+
+```tsx
+<Fab.Template
+  triggerProps={{
+    icon: <span aria-hidden="true">+</span>,
+    "aria-label": "콘텐츠 추가 방법",
+    fill: "solid",
+    priority: "primary",
+    size: "medium",
+  }}
+  items={[
+    {
+      id: "write",
+      icon: <span aria-hidden="true">✎</span>,
+      "aria-label": "새 글 작성",
+      fill: "solid",
+      priority: "secondary",
+      size: "small",
+      onClick: () => console.info("새 글 작성"),
+    },
+  ]}
+/>
+```
+
+`Root` 하나에 `Trigger` 하나와 `Menu.List` 하나를 두고 그 안에 `Menu.Item`을 조립한다.
+이 부품들은 Root 밖에서 사용하면 오류를 발생시킨다. `Menu.Item`의
+`aria-label`은 행동 이름과 Tooltip 문구이며 `persistentTooltips`로 열린 메뉴의
+문구를 계속 표시할 수 있다. 항목은 native `onClick`을 실행한 뒤 닫고 trigger로
+focus를 돌려준다. 소비자가 `event.preventDefault()`를 호출하면 이 자동 처리를 막는다.
+`Fab.Menu.Label`은 기존 `Tooltip.Text`를 재사용하는 메뉴명 표현 부품이며 Tooltip의
+스타일 문맥에서 사용한다. Speed Dial은 이 조합의 사용 사례 이름이며 별도 namespace가 아니다.
+Template 항목의 `id`는 DOM ID로도 쓰이므로 같은 화면에서 고유하게 지정한다.
+Template의 `className`, `style`, ref는 Root 하나에만 적용한다. 내부 버튼의
+`className`은 입력에서 제외하며 런타임 입력도 무시한다. 내부 스타일은 최상위
+`className` 아래 nested selector 또는 data attribute로 조정한다. 직접 조립하는
+Trigger·Menu.Item의 `className`은 유지한다.
+
+Hover로 열린 메뉴의 첫 포인터 클릭은 열림을 유지하고 이후 클릭·Enter·Space는
+토글한다. 닫힌 Trigger에서는 모든 방향키로 첫 액션에 진입하며, 열린 메뉴의
+반대 방향키는 Trigger에서 멈춘다.
+
 Select와 Dropdown이 함께 사용하는 `SelectedValue`, `toSelectedValueKey`,
 `isSameSelectedValue`, `isSameSelectedValueList`, `normalizeSingleSelectedValue`,
 `normalizeSelectedValuesByMode`도 root public entry에서 제공한다.

package/dist/styles.css

@@ -417,6 +417,28 @@
   --dropdown-option-padding-block-xsmall: 0px;
   --dropdown-option-radius-xsmall: 4px;
   --dropdown-text-weight-selected-xsmall: var(--dropdown-text-weight);
+  --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);
+  --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);
   --form-field-width: auto;
   --form-field-flex: 0 0 auto;
   --form-field-gap-x: var(--spacing-gap-5);
@@ -3770,6 +3792,314 @@ figure.chip {
   padding: 0;
 }
 
+.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;
+}
+.fab:where([data-fill="solid"][data-priority="primary"]) {
+  --fab-background: var(--button-default-primary-solid-bg);
+  --fab-foreground: var(--button-default-primary-solid-foreground);
+  --fab-hover-background: var(--button-default-primary-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-primary-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="primary"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-primary-outline-foreground);
+  --fab-hover-background: var(--button-default-primary-outline-hover-bg);
+  border: 1px solid var(--button-default-primary-outline-border);
+}
+.fab:where([data-fill="solid"][data-priority="secondary"]) {
+  --fab-background: var(--button-default-secondary-solid-bg);
+  --fab-foreground: var(--button-default-secondary-solid-foreground);
+  --fab-hover-background: var(--button-default-secondary-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-secondary-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="secondary"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-secondary-outline-foreground);
+  --fab-hover-background: var(--button-default-secondary-outline-hover-bg);
+  border: 1px solid var(--button-default-secondary-outline-border);
+}
+.fab:where([data-fill="solid"][data-priority="tertiary"]) {
+  --fab-background: var(--button-default-tertiary-solid-bg);
+  --fab-foreground: var(--button-default-tertiary-solid-foreground);
+  --fab-hover-background: var(--button-default-tertiary-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-tertiary-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="tertiary"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-tertiary-outline-foreground);
+  --fab-hover-background: var(--button-default-tertiary-outline-hover-bg);
+  border: 1px solid var(--button-default-tertiary-outline-border);
+}
+.fab:where([data-fill="solid"][data-priority="green"]) {
+  --fab-background: var(--button-default-green-solid-bg);
+  --fab-foreground: var(--button-default-green-solid-foreground);
+  --fab-hover-background: var(--button-default-green-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-green-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="green"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-green-outline-foreground);
+  --fab-hover-background: var(--button-default-green-outline-hover-bg);
+  --fab-pressed-background: var(--button-default-green-outline-active-bg);
+  border: 1px solid var(--button-default-green-outline-border);
+}
+.fab:where([data-fill="solid"][data-priority="yellow"]) {
+  --fab-background: var(--button-default-yellow-solid-bg);
+  --fab-foreground: var(--button-default-yellow-solid-foreground);
+  --fab-hover-background: var(--button-default-yellow-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-yellow-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="yellow"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-yellow-outline-foreground);
+  --fab-hover-background: var(--button-default-yellow-outline-hover-bg);
+  --fab-pressed-background: var(--button-default-yellow-outline-active-bg);
+  border: 1px solid var(--button-default-yellow-outline-border);
+}
+.fab:where([data-fill="solid"][data-priority="orange"]) {
+  --fab-background: var(--button-default-orange-solid-bg);
+  --fab-foreground: var(--button-default-orange-solid-foreground);
+  --fab-hover-background: var(--button-default-orange-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-orange-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="orange"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-orange-outline-foreground);
+  --fab-hover-background: var(--button-default-orange-outline-hover-bg);
+  --fab-pressed-background: var(--button-default-orange-outline-active-bg);
+  border: 1px solid var(--button-default-orange-outline-border);
+}
+.fab:where([data-fill="solid"][data-priority="teal"]) {
+  --fab-background: var(--button-default-teal-solid-bg);
+  --fab-foreground: var(--button-default-teal-solid-foreground);
+  --fab-hover-background: var(--button-default-teal-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-teal-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="teal"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-teal-outline-foreground);
+  --fab-hover-background: var(--button-default-teal-outline-hover-bg);
+  --fab-pressed-background: var(--button-default-teal-outline-active-bg);
+  border: 1px solid var(--button-default-teal-outline-border);
+}
+.fab:where([data-fill="solid"][data-priority="pink"]) {
+  --fab-background: var(--button-default-pink-solid-bg);
+  --fab-foreground: var(--button-default-pink-solid-foreground);
+  --fab-hover-background: var(--button-default-pink-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-pink-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="pink"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-pink-outline-foreground);
+  --fab-hover-background: var(--button-default-pink-outline-hover-bg);
+  --fab-pressed-background: var(--button-default-pink-outline-active-bg);
+  border: 1px solid var(--button-default-pink-outline-border);
+}
+.fab:where([data-fill="solid"][data-priority="red"]) {
+  --fab-background: var(--button-default-red-solid-bg);
+  --fab-foreground: var(--button-default-red-solid-foreground);
+  --fab-hover-background: var(--button-default-red-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-red-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="red"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-red-outline-foreground);
+  --fab-hover-background: var(--button-default-red-outline-hover-bg);
+  --fab-pressed-background: var(--button-default-red-outline-active-bg);
+  border: 1px solid var(--button-default-red-outline-border);
+}
+.fab:where([data-fill="solid"][data-priority="darkGray"]) {
+  --fab-background: var(--button-default-dark-gray-solid-bg);
+  --fab-foreground: var(--button-default-dark-gray-solid-foreground);
+  --fab-hover-background: var(--button-default-dark-gray-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-dark-gray-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="darkGray"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-dark-gray-outline-foreground);
+  --fab-hover-background: var(--button-default-dark-gray-outline-hover-bg);
+  --fab-pressed-background: var(--button-default-dark-gray-outline-active-bg);
+  border: 1px solid var(--button-default-dark-gray-outline-border);
+}
+.fab:where([data-fill="solid"][data-priority="lightGray"]) {
+  --fab-background: var(--button-default-light-gray-solid-bg);
+  --fab-foreground: var(--button-default-light-gray-solid-foreground);
+  --fab-hover-background: var(--button-default-light-gray-solid-hover-bg);
+  --fab-pressed-background: var(--button-default-light-gray-solid-active-bg);
+}
+.fab:where([data-fill="outlined"][data-priority="lightGray"]) {
+  --fab-background: var(--fab-outlined-background);
+  --fab-foreground: var(--button-default-light-gray-outline-foreground);
+  --fab-hover-background: var(--button-default-light-gray-outline-hover-bg);
+  --fab-pressed-background: var(--button-default-light-gray-outline-active-bg);
+  border: 1px solid var(--button-default-light-gray-outline-border);
+}
+.fab:where([data-fill="outlined"][data-priority="primary"]) {
+  --fab-hover-background: var(--button-default-primary-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);
+}
+.fab:where([data-fill="outlined"][data-priority="secondary"]) {
+  --fab-hover-background: var(--button-default-secondary-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);
+}
+.fab:where([data-fill="outlined"][data-priority="tertiary"]) {
+  --fab-hover-background: var(--button-default-tertiary-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);
+}
+.fab: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);
+}
+.fab:where(:enabled:hover) {
+  background-color: var(--fab-hover-background);
+  box-shadow: var(--fab-hover-shadow);
+}
+.fab:where(:enabled:active) {
+  background-color: var(--fab-pressed-background);
+  box-shadow: var(--fab-pressed-shadow);
+}
+.fab:where(:focus-visible) {
+  outline: 2px solid var(--fab-focus-color);
+  outline-offset: 2px;
+}
+.fab:where(:disabled) {
+  background-color: var(--fab-disabled-background);
+  border-color: var(--fab-disabled-background);
+  --fab-foreground: var(--fab-disabled-foreground);
+  cursor: not-allowed;
+}
+.fab:where([data-size="small"]) {
+  --fab-height: var(--fab-height-small);
+  --fab-content-size: var(--fab-content-size-small);
+  --fab-font-size: var(--fab-font-size-small);
+}
+.fab:where([data-size="medium"]) {
+  --fab-height: var(--fab-height-medium);
+  --fab-content-size: var(--fab-content-size-medium);
+  --fab-font-size: var(--fab-font-size-medium);
+}
+.fab:where([data-size="large"]) {
+  --fab-height: var(--fab-height-large);
+  --fab-content-size: var(--fab-content-size-large);
+  --fab-font-size: var(--fab-font-size-large);
+}
+.fab:where([data-extended="true"]) {
+  width: fit-content;
+  min-width: var(--fab-height);
+  max-width: none;
+  gap: var(--fab-gap);
+  padding-inline: var(--fab-extended-padding-inline);
+}
+.fab :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);
+}
+.fab :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;
+}
+
+.fab-root,
+.fab-menu-list {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+}
+
+.fab-menu-list[data-open="false"] {
+  visibility: hidden;
+}
+
+.fab-root {
+  direction: ltr;
+}
+.fab-root[data-open="false"] {
+  pointer-events: none;
+}
+.fab-root[data-open="false"] .fab-trigger {
+  pointer-events: auto;
+}
+.fab-root[data-direction="up"],
+.fab-root[data-direction="up"] .fab-menu-list {
+  flex-direction: column-reverse;
+}
+.fab-root[data-direction="down"],
+.fab-root[data-direction="down"] .fab-menu-list {
+  flex-direction: column;
+}
+.fab-root[data-direction="left"],
+.fab-root[data-direction="left"] .fab-menu-list {
+  flex-direction: row-reverse;
+}
+.fab-root[data-direction="right"],
+.fab-root[data-direction="right"] .fab-menu-list {
+  flex-direction: row;
+}
+.fab-root[data-open="true"] .fab-trigger .fab-content {
+  transform: rotate(45deg);
+}
+
+.fab-trigger .fab-content {
+  transition: transform 150ms ease;
+}
+
+.fab-root[data-open="true"] .fab-menu-item {
+  animation: fab-menu-enter 150ms ease-out;
+}
+
+@keyframes fab-menu-enter {
+  from {
+    opacity: 0;
+    transform: scale(0.75);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .fab-trigger .fab-content {
+    transition: none;
+  }
+  .fab-root[data-open="true"] .fab-menu-item {
+    animation: none;
+  }
+}
+
 .form-field-container {
   display: block;
   width: var(--form-field-width);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.12.14",
+  "version": "0.13.0",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,

package/src/components/fab/index.scss

@@ -0,0 +1 @@
+@use "./styles";

package/src/components/fab/index.tsx

@@ -0,0 +1,34 @@
+import "./index.scss";
+
+import { Tooltip } from "../tooltip";
+
+import {
+  FabDefault,
+  FabExtended,
+  FabLabel,
+  FabRoot,
+  FabTrigger,
+  FabMenuList,
+  FabMenuItem,
+  FabTemplate,
+} from "./markup";
+
+export const Fab = {
+  Button: FabDefault,
+  Trigger: FabTrigger,
+  Expand: FabExtended,
+  Menu: {
+    List: FabMenuList,
+    Item: FabMenuItem,
+    Label: Tooltip.Text,
+  },
+  Root: FabRoot,
+  Template: FabTemplate,
+  Default: FabDefault,
+  Extended: FabExtended,
+  Label: FabLabel,
+};
+
+export * from "./types/options";
+export type * from "./types";
+export { FabContext, ARROW_KEYS, useFabContext } from "./markup";

package/src/components/fab/markup/Base.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import clsx from "clsx";
+import { forwardRef } from "react";
+import type { FabButtonProps } from "../types";
+import { FabLabel } from "./Label";
+
+/**
+ * Fab Component; 공통 native 액션 마크업
+ * @component
+ * @property {ReactNode} props.icon 필수 장식용 콘텐츠. fab-content 안에서 aria-hidden으로 표시한다.
+ * @property {"small" | "medium" | "large"} props.size 필수 크기. 높이 40/48/56px와 아이콘 영역 16/20/24px를 적용한다.
+ * @property {"solid" | "outlined"} props.fill 필수 채움 방식. outlined의 기본 면은 불투명 흰색이다.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} props.priority 두 fill 모두에서 사용하는 필수 색상.
+ * @property {boolean} [props.extended=false] 라벨과 자연 너비를 표시할지 여부. Button/Expand가 각각 false/true로 고정한다.
+ * @property {ReactNode} [props.children] extended가 true일 때 표시할 라벨. 문자열·숫자는 Fab.Label로 감싼다.
+ * @property {"button" | "submit" | "reset"} [props.type="button"] native 버튼 동작.
+ * @property {boolean} [props.disabled=false] native 비활성화. 클릭·키보드 실행과 Tab 진입을 차단한다.
+ * @property {string} [props.aria-label] native 접근 가능한 이름. 아이콘 전용 공개 Button에서는 필수다.
+ * @property {React.MouseEventHandler<HTMLButtonElement>} [props.onClick] native 버튼의 실행 이벤트.
+ * @property {string} [props.className] 최상위 button에 fab 클래스와 병합할 추가 클래스.
+ * @property {CSSProperties} [props.style] 최상위 button의 inline style.
+ * @property {React.Ref<HTMLButtonElement>} [ref] 실제 native button의 ref.
+ * @see FabButtonProps
+ * @desc Button/Expand가 공유하는 내부 마크업이다. 크기·색상·라벨 표현만 적용하며 클릭·키보드·disabled는 native button에 맡긴다. 나머지 native button 속성·이벤트를 전달한다.
+ */
+const FabButton = forwardRef<HTMLButtonElement, FabButtonProps>(
+  (
+    {
+      icon,
+      children,
+      size,
+      fill,
+      priority,
+      extended = false,
+      className,
+      type = "button",
+      ...rest
+    },
+    ref,
+  ) => (
+    <button
+      {...rest}
+      ref={ref}
+      type={type}
+      className={clsx("fab", className)}
+      data-size={size}
+      data-fill={fill}
+      data-priority={priority}
+      data-extended={extended || undefined}
+    >
+      <span className="fab-content" aria-hidden="true">
+        {icon}
+      </span>
+      {extended && <FabLabel>{children}</FabLabel>}
+    </button>
+  ),
+);
+
+FabButton.displayName = "FabButton";
+
+export { FabButton };

package/src/components/fab/markup/Default.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import { forwardRef } from "react";
+import type { FabDefaultProps } from "../types";
+import { FabButton } from "./Base";
+
+/**
+ * Fab Component; 단독으로 사용하는 아이콘 버튼
+ * @component
+ * @property {ReactNode} props.icon 필수 장식용 콘텐츠. 내부는 aria-hidden이므로 행동 이름을 별도로 제공한다.
+ * @property {"small" | "medium" | "large"} props.size 필수 크기. 버튼 높이는 각각 40/48/56px, 아이콘 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} props.fill 필수 채움 방식. outlined의 기본 면은 불투명 흰색이다.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} props.priority 필수 색상. 두 fill 모두에서 같은 목록을 지원한다.
+ * @property {string} props.aria-label 필수 접근 가능한 행동 이름. 아이콘의 모양보다 실행할 작업을 설명한다.
+ * @property {"button" | "submit" | "reset"} [props.type="button"] native 버튼 동작. 폼 제출·초기화는 명시적으로 선택한다.
+ * @property {boolean} [props.disabled=false] native 비활성화. 클릭·키보드 실행과 Tab 진입을 차단한다.
+ * @property {React.MouseEventHandler<HTMLButtonElement>} [props.onClick] 클릭·Enter·Space의 native 실행 이벤트.
+ * @property {string} [props.className] 최상위 button에 fab 클래스와 병합할 추가 클래스.
+ * @property {CSSProperties} [props.style] 최상위 button의 inline style.
+ * @property {React.Ref<HTMLButtonElement>} [ref] 실제 native button에 전달하는 object/callback ref.
+ * @see FabDefaultProps
+ * @desc Fab.Button과 호환 이름 Fab.Default로 공개한다. children을 받지 않는 아이콘 전용 버튼이며 나머지 native button 속성·이벤트는 그대로 전달한다. 메뉴 상태와 viewport 배치는 소비자가 정한다.
+ * @example
+ * <Fab.Button icon={<span>+</span>} aria-label="새 항목 추가"
+ *   size="large" fill="solid" priority="primary" />
+ */
+const FabDefault = forwardRef<HTMLButtonElement, FabDefaultProps>(
+  (props, ref) => <FabButton {...props} ref={ref} extended={false} />,
+);
+
+FabDefault.displayName = "FabDefault";
+
+export { FabDefault };

package/src/components/fab/markup/Extended.tsx

@@ -0,0 +1,35 @@
+"use client";
+
+import { forwardRef } from "react";
+import type { FabExtendedProps } from "../types";
+import { FabButton } from "./Base";
+
+/**
+ * Fab Component; 아이콘과 라벨을 표시하는 주요 액션
+ * @component
+ * @property {ReactNode} props.icon 필수 장식용 콘텐츠. 내부는 aria-hidden이므로 행동 이름은 라벨로 제공한다.
+ * @property {ReactNode} props.children 필수 행동 라벨. 문자열·숫자는 Fab.Label로 감싸고 복합 JSX는 그대로 표시한다.
+ * @property {"small" | "medium" | "large"} props.size 필수 크기. 버튼 높이는 각각 40/48/56px, 아이콘 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} props.fill 필수 채움 방식. outlined의 기본 면은 불투명 흰색이다.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} props.priority 필수 색상. 두 fill 모두에서 같은 목록을 지원한다.
+ * @property {string} [props.aria-label] 라벨과 별도의 접근 가능한 이름. 생략하면 표시한 라벨을 사용한다.
+ * @property {"button" | "submit" | "reset"} [props.type="button"] native 버튼 동작. 폼 제출·초기화는 명시적으로 선택한다.
+ * @property {boolean} [props.disabled=false] native 비활성화. 클릭·키보드 실행과 Tab 진입을 차단한다.
+ * @property {React.MouseEventHandler<HTMLButtonElement>} [props.onClick] 클릭·Enter·Space의 native 실행 이벤트.
+ * @property {string} [props.className] 최상위 button에 fab 클래스와 병합할 추가 클래스.
+ * @property {CSSProperties} [props.style] 최상위 button의 inline style.
+ * @property {React.Ref<HTMLButtonElement>} [ref] 실제 native button에 전달하는 object/callback ref.
+ * @see FabExtendedProps
+ * @desc Fab.Expand와 호환 이름 Fab.Extended로 공개한다. 콘텐츠 너비에 좌우 16px padding을 더하는 라벨 확장형이며 액션 메뉴를 여는 기능은 갖지 않는다. 나머지 native button 속성·이벤트를 전달한다. 복합 라벨에도 접근 가능한 이름을 유지한다.
+ * @example
+ * <Fab.Expand icon={<span>+</span>} size="large" fill="solid" priority="primary">
+ *   새 항목 추가
+ * </Fab.Expand>
+ */
+const FabExtended = forwardRef<HTMLButtonElement, FabExtendedProps>(
+  (props, ref) => <FabButton {...props} ref={ref} extended />,
+);
+
+FabExtended.displayName = "FabExtended";
+
+export { FabExtended };

package/src/components/fab/markup/Label.tsx

@@ -0,0 +1,16 @@
+import { Slot } from "../../slot";
+import type { SlotTextProps } from "../../slot/types";
+
+/**
+ * Fab Component; 라벨의 고정 타이포그래피
+ * @component
+ * @property {ReactNode} [props.children] 문자열·숫자는 span으로 감싸고 다른 ReactNode는 그대로 반환한다.
+ * @property {string} [props.title] 문자열·숫자 라벨의 native title. 생략하면 children의 문자열 값을 사용한다.
+ * @property {string} [props.id] 문자열·숫자 라벨을 감싼 span의 DOM ID.
+ * @property {CSSProperties} [props.style] 문자열·숫자 라벨을 감싼 span의 inline style.
+ * @see SlotTextProps
+ * @desc Expand의 문자열·숫자 라벨을 fab-label 클래스로 표시한다. SlotTextProps에서 className·as를 제외하며, ComponentPropsWithoutRef<"span">을 사용하므로 ref도 받지 않는다. 나머지 native span 속성은 래핑한 텍스트에만 전달한다. 복합 JSX는 wrapper와 속성 주입 없이 반환한다. 스타일 조정은 최상위 FAB의 nested selector로 한다.
+ */
+export function FabLabel(props: Omit<SlotTextProps, "className" | "as">) {
+  return <Slot.Text {...props} className="fab-label" />;
+}