@uniai-fe/uds-primitives 0.12.14 → 0.13.0

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

@@ -0,0 +1,114 @@
+"use client";
+
+import clsx from "clsx";
+import { forwardRef, useImperativeHandle } from "react";
+import { Tooltip } from "../../tooltip";
+import type { FabMenuItemProps, FabMenuListProps } from "../types";
+import { FabDefault } from "./Default";
+import { useFabContext } from "./Root";
+
+/**
+ * Fab Component; 닫힌 상태에서도 원점을 유지하는 액션 목록
+ * @component
+ * @property {ReactNode} [props.children] 같은 Root에 속한 Menu.Item 조합. DOM의 첫 항목이 Trigger에 가장 가깝다.
+ * @property {string} [props.aria-label] 메뉴의 별도 접근 가능한 이름. 생략하거나 빈 문자열이면 Trigger의 이름을 aria-labelledby로 연결한다.
+ * @property {string} [props.className] 최상위 목록 div에 fab-menu-list 클래스와 병합할 추가 클래스.
+ * @property {CSSProperties} [props.style] 최상위 목록 div의 inline style. 닫힌 목록의 배치 공간을 제거하지 않는다.
+ * @property {React.MouseEventHandler<HTMLDivElement>} [props.onClick] 액션의 실행·닫힘 처리 뒤 목록으로 버블링되는 native 클릭 이벤트.
+ * @property {React.KeyboardEventHandler<HTMLDivElement>} [props.onKeyDown] Root 탐색으로 버블링되는 native 키 이벤트. preventDefault하면 Root의 해당 기본 처리를 생략하지만 Tooltip의 document capture Escape는 취소하지 못한다.
+ * @property {React.Ref<HTMLDivElement>} [ref] 실제 목록 div에 전달하는 object/callback ref.
+ * @see FabMenuListProps
+ * @see FabRoot
+ * @desc Root가 ID·role=menu·orientation·aria-labelledby와 닫힘을 연결한다. 닫히면 visibility로 배치 공간을 유지하고 aria-hidden·inert로 접근성·focus 탐색에서 제외한다. 이 속성과 hidden은 public 입력으로 받지 않으며 나머지 native div 속성·이벤트는 목록에 전달한다. Root 밖에서 사용하면 오류를 발생시킨다.
+ */
+const FabMenuList = forwardRef<HTMLDivElement, FabMenuListProps>(
+  ({ className, ...props }, ref) => {
+    const { open, direction, menuId, triggerId, menuRef } =
+      useFabContext("Fab.Menu.List");
+    // DOM ref를 공유하고 소비자 callback ref의 React cleanup 계약은 React에 맡긴다.
+    useImperativeHandle(ref, () => menuRef.current!, [menuRef]);
+    return (
+      <div
+        {...props}
+        ref={menuRef}
+        id={menuId}
+        className={clsx("fab-menu-list", className)}
+        role="menu"
+        aria-labelledby={props["aria-label"] ? undefined : triggerId}
+        aria-orientation={
+          direction === "up" || direction === "down" ? "vertical" : "horizontal"
+        }
+        data-open={open}
+        aria-hidden={!open || undefined}
+        inert={!open}
+      />
+    );
+  },
+);
+
+FabMenuList.displayName = "FabMenuList";
+
+/**
+ * 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 필수 행동 이름이자 Tooltip 문구. persistentTooltips는 Root에서 지정한다.
+ * @property {"top" | "right" | "bottom" | "left"} [props.tooltipSide] 툴팁 방향. up/down 메뉴는 left, left/right 메뉴는 top이 기본이다.
+ * @property {"button" | "submit" | "reset"} [props.type="button"] native 버튼 동작. 폼 제출·초기화는 소비자가 명시한다.
+ * @property {boolean} [props.disabled=false] native 실행을 차단하고 Root의 방향키 탐색에서 제외한다.
+ * @property {React.MouseEventHandler<HTMLButtonElement>} [props.onClick] 소비자의 액션을 먼저 호출한 뒤 닫고 Trigger로 focus를 복귀한다. preventDefault하면 자동 닫기·focus 복귀를 생략한다.
+ * @property {React.FocusEventHandler<HTMLButtonElement>} [props.onFocus] native 액션 button의 focus 이벤트. Root의 열림 제어는 Root 입력으로 설정한다.
+ * @property {React.KeyboardEventHandler<HTMLButtonElement>} [props.onKeyDown] Root 탐색으로 버블링되는 native 키 이벤트. preventDefault하면 Root의 해당 기본 처리를 생략하지만 Tooltip의 document capture Escape는 취소하지 못한다.
+ * @property {string} [props.id] 액션 button의 DOM ID. 같은 화면에서 고유하게 지정한다.
+ * @property {string} [props.className] wrapper·Tooltip이 아닌 액션 button에 fab 클래스와 병합할 추가 클래스.
+ * @property {CSSProperties} [props.style] 액션 button의 inline style.
+ * @property {React.Ref<HTMLButtonElement>} [ref] wrapper가 아닌 실제 액션 button에 전달하는 object/callback ref.
+ * @see FabMenuItemProps
+ * @see FabRoot
+ * @desc FabDefaultProps에서 role·tabIndex를 제외하고 tooltipSide를 더한 계약으로 Button과 기존 Tooltip을 조립한다. children을 받지 않는 아이콘 버튼이다. 같은 Root의 Menu.List 안에서 사용하며 role=menuitem·tabIndex=-1은 모듈이 소유한다. 나머지 native button 속성·이벤트는 액션 button에 전달한다. Tooltip의 document capture Escape도 전체 닫힘·Trigger focus 복귀를 요청하며 Tooltip 자체 dismiss도 유지한다. Root가 닫히면 Tooltip 문구의 portal도 제거하고 버튼과 ref는 유지한다. Root 밖에서 사용하면 오류를 발생시킨다.
+ */
+const FabMenuItem = forwardRef<HTMLButtonElement, FabMenuItemProps>(
+  ({ tooltipSide, onClick, ...props }, ref) => {
+    const { open, direction, persistentTooltips, onClose } =
+      useFabContext("Fab.Menu.Item");
+    return (
+      <div className="fab-menu-item" role="none">
+        <Tooltip.Root open={persistentTooltips ? open : undefined}>
+          <Tooltip.Trigger asChild>
+            <FabDefault
+              {...props}
+              ref={ref}
+              role="menuitem"
+              tabIndex={-1}
+              onClick={event => {
+                onClick?.(event);
+                if (!event.defaultPrevented) onClose(true);
+              }}
+            />
+          </Tooltip.Trigger>
+          {/* 닫힌 목록의 Tooltip portal만 제거하고 버튼·ref·Tooltip 상태는 유지한다. */}
+          {open && (
+            <Tooltip.Message
+              // Tooltip의 document capture Escape는 전체 닫힘·focus 복귀를 먼저 처리한다.
+              // 이벤트를 취소하지 않아 비제어형 Tooltip의 기본 dismiss도 실행한다.
+              onEscapeKeyDown={() => onClose(true)}
+              side={
+                tooltipSide ??
+                (direction === "up" || direction === "down" ? "left" : "top")
+              }
+            >
+              {props["aria-label"]}
+            </Tooltip.Message>
+          )}
+        </Tooltip.Root>
+      </div>
+    );
+  },
+);
+
+FabMenuItem.displayName = "FabMenuItem";
+
+export { FabMenuList, FabMenuItem };

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

@@ -0,0 +1,263 @@
+"use client";
+
+import clsx from "clsx";
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import type {
+  FocusEventHandler,
+  KeyboardEventHandler,
+  MouseEventHandler,
+} from "react";
+import type { FabContextValue, FabRootProps } from "../types";
+
+/**
+ * Fab Context; Root와 조립 부품의 상태·ARIA·interaction 연결
+ * @see FabContextValue
+ * @see useFabContext
+ * @desc FabRoot가 Provider로 열림 상태·물리 방향·Tooltip 정책·ID·DOM ref·공통 handler를 제공한다. Trigger와 Menu 부품은 useFabContext로 가장 가까운 Root의 값을 읽는다. 기본값 null은 Provider 부재를 나타내며 Hook이 Root 밖의 부품 사용을 오류로 알린다.
+ */
+export const FabContext = createContext<FabContextValue | null>(null);
+
+/**
+ * Fab Constants; 물리 펼침 방향별 메뉴 탐색 키
+ * @property {readonly ["ArrowUp", "ArrowDown"]} up 위쪽 메뉴의 다음·이전 탐색 키.
+ * @property {readonly ["ArrowDown", "ArrowUp"]} down 아래쪽 메뉴의 다음·이전 탐색 키.
+ * @property {readonly ["ArrowLeft", "ArrowRight"]} left 왼쪽 메뉴의 다음·이전 탐색 키.
+ * @property {readonly ["ArrowRight", "ArrowLeft"]} right 오른쪽 메뉴의 다음·이전 탐색 키.
+ * @desc 열린 메뉴의 물리 펼침 방향별로 [다음 액션으로 이동하는 키, 이전 액션 또는 Trigger로 돌아가는 키]를 제공한다. RTL에서도 방향을 반전하지 않는다. 닫힌 Trigger는 이 순서와 관계없이 모든 방향키로 첫 액션에 진입한다. TypeScript에서 각 배열은 readonly tuple이다.
+ */
+export const ARROW_KEYS = {
+  up: ["ArrowUp", "ArrowDown"],
+  down: ["ArrowDown", "ArrowUp"],
+  left: ["ArrowLeft", "ArrowRight"],
+  right: ["ArrowRight", "ArrowLeft"],
+} as const;
+
+/**
+ * Fab Hook; 조립 부품의 공통 상태 조회
+ * @hook
+ * @param {string} component 호출 부품 이름.
+ * @desc Root의 열림 상태·ref·interaction을 읽는다. Root 밖의 부품 사용은 오류로 알린다.
+ */
+export function useFabContext(component: string): FabContextValue {
+  const context = useContext(FabContext);
+  if (!context) throw new Error(`${component} must be used within Fab.Root.`);
+  return context;
+}
+
+/**
+ * Fab Component; 공통 상태와 액션 탐색
+ * @component
+ * @property {ReactNode} props.children 필수 조합. Trigger 하나와 Menu.List 하나를 두고 List 안에 Menu.Item을 배치한다.
+ * @property {"up" | "down" | "left" | "right"} [props.direction="up"] 액션의 물리 펼침 방향. RTL에서도 좌우를 반전하지 않는다.
+ * @property {boolean} [props.persistentTooltips=false] 열린 메뉴의 행동 이름을 hover 여부와 관계없이 계속 표시한다.
+ * @property {boolean} [props.open] 제어형 열림 상태. 지정하면 onOpenChange 요청을 소비자가 반영해야 한다.
+ * @property {boolean} [props.defaultOpen=false] 비제어형 초기 열림 상태. open이 지정되면 사용하지 않는다.
+ * @property {(open: boolean) => void} [props.onOpenChange] hover·focus·토글·키보드·선택·외부 focus 이탈의 열림 변경 요청. 현재 상태와 같은 요청은 통지하지 않는다.
+ * @property {React.FocusEventHandler<HTMLDivElement>} [props.onBlur] 기본 처리보다 먼저 호출한다. preventDefault하면 외부 focus 이탈에 따른 닫힘을 생략한다.
+ * @property {React.KeyboardEventHandler<HTMLDivElement>} [props.onKeyDown] 기본 메뉴 탐색보다 먼저 호출한다. preventDefault하면 이 경로의 탐색·닫힘을 생략하지만 Tooltip의 document capture Escape 경로는 취소하지 못한다.
+ * @property {React.PointerEventHandler<HTMLDivElement>} [props.onPointerEnter] 기본 처리보다 먼저 호출한다. 닫힌 상태의 포인터 진입 대상은 Trigger다. preventDefault하면 mouse hover 열기를 생략하며 disabled Trigger는 hover로 열지 않는다.
+ * @property {React.PointerEventHandler<HTMLDivElement>} [props.onPointerLeave] 기본 처리보다 먼저 호출한다. preventDefault하면 pointer 이탈 닫힘을 생략한다. 내부 focus가 있으면 기본 닫힘도 생략한다.
+ * @property {React.MouseEventHandler<HTMLDivElement>} [props.onClick] 부품의 실행·토글 처리 뒤 Root로 버블링되는 native 클릭 이벤트.
+ * @property {string} [props.className] 최상위 div에 fab-root 클래스와 병합할 추가 클래스. 내부 요소는 nested selector로 조정한다.
+ * @property {CSSProperties} [props.style] 최상위 div의 inline style. 화면 고정 위치는 소비자가 정한다.
+ * @property {React.Ref<HTMLDivElement>} [ref] 최상위 Root div에 전달하는 object/callback ref.
+ * @see FabRootProps
+ * @desc 부품에 상태·ID·ARIA·ref와 공통 interaction을 제공한다. 닫힌 Trigger의 모든 방향키는 첫 액션을 열고, 열린 메뉴에서는 펼침 방향 키가 다음 액션으로 이동하며 반대 키는 Trigger에서 멈춘다. Home/End는 첫/마지막 액션으로 이동한다. 첫 액션은 Trigger에 가장 가깝고 disabled 항목은 탐색에서 제외한다. Escape·선택은 닫고 Trigger로 복귀하며 외부 Tab은 focus를 빼앗지 않는다. 닫힌 목록도 배치 영역을 유지한다. FabRootProps가 상속한 나머지 native div 속성은 Root에 전달하며 viewport 배치·서비스 실행은 소비자가 맡는다.
+ * @example
+ * <Fab.Root direction="up">
+ *   <Fab.Trigger icon={<span>+</span>} aria-label="관련 작업"
+ *     size="large" fill="solid" priority="primary" />
+ *   <Fab.Menu.List>
+ *     <Fab.Menu.Item icon={<span>⧉</span>} aria-label="복사"
+ *       size="small" fill="outlined" priority="primary" />
+ *   </Fab.Menu.List>
+ * </Fab.Root>
+ */
+const FabRoot = forwardRef<HTMLDivElement, FabRootProps>(
+  (
+    {
+      children,
+      direction = "up",
+      persistentTooltips = false,
+      open: controlledOpen,
+      defaultOpen = false,
+      onOpenChange: onOpenChangeProp,
+      className,
+      onBlur,
+      onKeyDown,
+      onPointerEnter,
+      onPointerLeave,
+      ...rest
+    },
+    ref,
+  ) => {
+    const id = useId();
+    const [uncontrolledOpen, setUncontrolledOpen] =
+      useState<boolean>(defaultOpen);
+    const open: boolean = controlledOpen ?? uncontrolledOpen;
+    const triggerRef = useRef<HTMLButtonElement | null>(null);
+    const menuRef = useRef<HTMLDivElement | null>(null);
+    const pendingFocusRef = useRef<HTMLButtonElement | null>(null);
+    const hoverOpenedRef = useRef<boolean>(false);
+
+    // 닫힌 목록의 focus 요청은 소비자가 열림을 반영한 commit 뒤에 실행한다.
+    useLayoutEffect(() => {
+      if (open) {
+        pendingFocusRef.current?.focus();
+        pendingFocusRef.current = null;
+      } else {
+        // 제어형 소비자가 외부에서 닫아도 이전 hover 진입을 다음 토글에 남기지 않는다.
+        hoverOpenedRef.current = false;
+      }
+    }, [open]);
+
+    const onOpenChange: (next: boolean) => void = next => {
+      if (next === open) return;
+      if (controlledOpen === undefined) setUncontrolledOpen(next);
+      onOpenChangeProp?.(next);
+    };
+
+    const onClose: (restoreFocus: boolean) => void = restoreFocus => {
+      pendingFocusRef.current = null;
+      hoverOpenedRef.current = false;
+      onOpenChange(false);
+      if (restoreFocus) triggerRef.current?.focus();
+    };
+
+    const onTriggerClick: MouseEventHandler<HTMLButtonElement> = event => {
+      // Hover로 먼저 열린 첫 포인터 클릭은 진입을 유지하고 이후 클릭은 다시 토글한다.
+      const keepOpen = event.detail > 0 && hoverOpenedRef.current;
+      hoverOpenedRef.current = false;
+      onOpenChange(keepOpen || !open);
+    };
+
+    const onTriggerFocus: FocusEventHandler<HTMLButtonElement> = event => {
+      // Escape·선택 뒤의 내부 focus 복귀는 메뉴를 다시 열지 않는다.
+      if (
+        event.relatedTarget &&
+        menuRef.current?.contains(event.relatedTarget)
+      ) {
+        return;
+      }
+      // Pointer는 hover/click이 담당하고 키보드 진입은 focus로 연다.
+      if (event.currentTarget.matches(":focus-visible")) onOpenChange(true);
+    };
+
+    const onNavigate: KeyboardEventHandler<HTMLDivElement> = event => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        onClose(true);
+        return;
+      }
+      const actions = Array.from(
+        menuRef.current?.querySelectorAll<HTMLButtonElement>(
+          'button[role="menuitem"]:not(:disabled)',
+        ) ?? [],
+      );
+      const current = actions.indexOf(event.target as HTMLButtonElement);
+      const [forwardKey, backwardKey] = ARROW_KEYS[direction];
+      const forward = event.key === forwardKey;
+      const backward = event.key === backwardKey;
+      if (!(
+        (current === -1 && event.key.startsWith("Arrow")) ||
+        forward ||
+        backward ||
+        event.key === "Home" ||
+        event.key === "End"
+      ))
+        return;
+      event.preventDefault();
+      hoverOpenedRef.current = false;
+      // 열린 Trigger는 반대 방향 탐색의 끝이며 닫힌 Trigger는 모든 방향키로 진입한다.
+      if (open && current === -1 && backward) return;
+      // DOM 순서의 첫 액션이 Trigger에 가장 가깝다.
+      const next =
+        event.key === "End"
+          ? actions.length - 1
+          : event.key === "Home" || current === -1
+            ? 0
+            : forward
+              ? Math.min(current + 1, actions.length - 1)
+              : current - 1;
+      const target = next < 0 ? triggerRef.current : actions[next];
+      if (open) target?.focus();
+      else {
+        pendingFocusRef.current = target ?? null;
+        onOpenChange(true);
+      }
+    };
+
+    return (
+      <FabContext.Provider
+        value={{
+          open,
+          direction,
+          persistentTooltips,
+          triggerId: `${id}-trigger`,
+          menuId: `${id}-menu`,
+          triggerRef,
+          menuRef,
+          onClose,
+          onTriggerClick,
+          onTriggerFocus,
+        }}
+      >
+        <div
+          {...rest}
+          ref={ref}
+          className={clsx("fab-root", className)}
+          data-direction={direction}
+          data-open={open}
+          onBlur={event => {
+            onBlur?.(event);
+            if (
+              !event.defaultPrevented &&
+              !event.currentTarget.contains(event.relatedTarget)
+            )
+              onClose(false);
+          }}
+          onKeyDown={event => {
+            onKeyDown?.(event);
+            if (!event.defaultPrevented) onNavigate(event);
+          }}
+          onPointerEnter={event => {
+            onPointerEnter?.(event);
+            if (
+              !event.defaultPrevented &&
+              event.pointerType === "mouse" &&
+              !triggerRef.current?.disabled
+            ) {
+              if (!open) hoverOpenedRef.current = true;
+              onOpenChange(true);
+            }
+          }}
+          onPointerLeave={event => {
+            onPointerLeave?.(event);
+            // 키보드 탐색 중인 목록은 포인터가 벗어나도 유지한다.
+            if (
+              !event.defaultPrevented &&
+              !event.currentTarget.contains(
+                event.currentTarget.ownerDocument.activeElement,
+              )
+            )
+              onClose(false);
+          }}
+        >
+          {children}
+        </div>
+      </FabContext.Provider>
+    );
+  },
+);
+
+FabRoot.displayName = "FabRoot";
+
+export { FabRoot };

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

@@ -0,0 +1,79 @@
+"use client";
+
+import { forwardRef } from "react";
+import type { FabTemplateProps } from "../types";
+import { FabRoot } from "./Root";
+import { FabTrigger } from "./Trigger";
+import { FabMenuItem, FabMenuList } from "./Menu";
+
+/**
+ * Fab Component; 바로 사용하는 기본 액션 조합
+ * @component
+ * @property {Omit<FabTriggerProps, "className">} props.triggerProps 필수 Trigger 입력. 아래 필수 필드와 native button 입력을 전달한다.
+ * @property {ReactNode} props.triggerProps.icon 필수 장식용 콘텐츠. 열리면 45도 회전한다.
+ * @property {string} props.triggerProps.aria-label 필수 Trigger 행동 이름이자 기본 메뉴 이름.
+ * @property {"small" | "medium" | "large"} props.triggerProps.size 필수 Trigger 높이 40/48/56px. 아이콘 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} props.triggerProps.fill 필수 Trigger 채움 방식. outlined의 기본 면은 불투명 흰색이다.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} props.triggerProps.priority 두 fill 모두에서 사용하는 필수 Trigger 색상.
+ * @property {boolean} [props.triggerProps.disabled=false] Trigger의 native 실행·Tab 진입과 Root의 mouse hover 열기를 차단한다.
+ * @property {React.MouseEventHandler<HTMLButtonElement>} [props.triggerProps.onClick] 기본 클릭 처리 전에 호출한다. preventDefault하면 처리를 생략한다. hover로 열린 첫 pointer 클릭은 열림을 유지하고 이후 클릭과 Enter·Space는 토글한다.
+ * @property {React.FocusEventHandler<HTMLButtonElement>} [props.triggerProps.onFocus] focus 처리 전에 호출한다. preventDefault하면 해당 focus의 열기를 생략한다.
+ * @property {React.KeyboardEventHandler<HTMLButtonElement>} [props.triggerProps.onKeyDown] Root 탐색으로 버블링되는 native 키 이벤트. preventDefault하면 Root의 해당 처리를 생략하지만 Tooltip의 document capture Escape는 취소하지 못한다.
+ * @property {CSSProperties} [props.triggerProps.style] Trigger button의 inline style.
+ * @property {"button" | "submit" | "reset"} [props.triggerProps.type="button"] Trigger의 native 버튼 동작.
+ * @property {FabTemplateItem[]} props.items 필수 액션 목록. 빈 배열도 허용하며 배열 순서의 첫 항목이 Trigger에 가장 가깝다.
+ * @property {string} props.items[].id 필수 액션 DOM ID이자 React key. 같은 화면에서 고유하게 지정한다.
+ * @property {ReactNode} props.items[].icon 필수 장식용 액션 콘텐츠.
+ * @property {string} props.items[].aria-label 필수 행동 이름이자 Tooltip 문구.
+ * @property {"small" | "medium" | "large"} props.items[].size 필수 액션 높이 40/48/56px. 아이콘 영역은 16/20/24px다.
+ * @property {"solid" | "outlined"} props.items[].fill 필수 액션 채움 방식. outlined의 기본 면은 불투명 흰색이다.
+ * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} props.items[].priority 두 fill 모두에서 사용하는 필수 액션 색상.
+ * @property {"top" | "right" | "bottom" | "left"} [props.items[].tooltipSide] 툴팁 방향. up/down 메뉴는 left, left/right 메뉴는 top이 기본이다.
+ * @property {boolean} [props.items[].disabled=false] 해당 액션의 실행과 방향키 탐색을 차단한다.
+ * @property {React.MouseEventHandler<HTMLButtonElement>} [props.items[].onClick] 소비자 액션을 먼저 실행한 뒤 닫고 Trigger로 focus를 복귀한다. preventDefault하면 자동 처리를 생략한다.
+ * @property {React.FocusEventHandler<HTMLButtonElement>} [props.items[].onFocus] 해당 native 액션 button의 focus 이벤트.
+ * @property {React.KeyboardEventHandler<HTMLButtonElement>} [props.items[].onKeyDown] Root 탐색으로 버블링되는 native 키 이벤트. preventDefault하면 Root의 해당 처리를 생략하지만 Tooltip의 document capture Escape는 취소하지 못한다.
+ * @property {CSSProperties} [props.items[].style] 해당 액션 button의 inline style.
+ * @property {"button" | "submit" | "reset"} [props.items[].type="button"] 액션의 native 버튼 동작.
+ * @property {"up" | "down" | "left" | "right"} [props.direction="up"] 액션의 물리 펼침 방향. RTL에서도 반전하지 않는다.
+ * @property {boolean} [props.persistentTooltips=false] 열린 액션의 Tooltip을 계속 표시한다.
+ * @property {boolean} [props.open] 제어형 열림 상태. onOpenChange 요청을 소비자가 반영해야 한다.
+ * @property {boolean} [props.defaultOpen=false] 비제어형 초기 열림 상태. open이 지정되면 무시한다.
+ * @property {(open: boolean) => void} [props.onOpenChange] 현재 상태와 다른 열림 변경 요청을 전달한다.
+ * @property {React.FocusEventHandler<HTMLDivElement>} [props.onBlur] Root의 외부 focus 이탈 닫힘 전에 호출한다. preventDefault하면 해당 기본 닫힘을 생략한다.
+ * @property {React.KeyboardEventHandler<HTMLDivElement>} [props.onKeyDown] Root의 탐색 전에 호출한다. preventDefault하면 이 경로의 기본 동작을 생략하지만 Tooltip의 document capture Escape는 취소하지 못한다.
+ * @property {React.PointerEventHandler<HTMLDivElement>} [props.onPointerEnter] Root의 mouse hover 열기 전에 호출한다. 닫힌 상태의 포인터 진입 대상은 Trigger다. preventDefault하면 해당 기본 열기를 생략한다.
+ * @property {React.PointerEventHandler<HTMLDivElement>} [props.onPointerLeave] Root의 pointer 이탈 닫힘 전에 호출한다. preventDefault하면 해당 기본 닫힘을 생략한다. 내부 focus가 있으면 기본 닫힘도 생략한다.
+ * @property {React.MouseEventHandler<HTMLDivElement>} [props.onClick] 부품의 실행·토글 처리 뒤 Root로 버블링되는 native 클릭 이벤트.
+ * @property {string} [props.className] 최상위 Root div 하나에만 적용하는 추가 클래스. 내부 스타일은 nested selector로 조정한다.
+ * @property {CSSProperties} [props.style] 최상위 Root div 하나의 inline style.
+ * @property {React.Ref<HTMLDivElement>} [ref] 최상위 Root div의 ref. Trigger·액션의 ref 입력은 제공하지 않는다.
+ * @see FabTemplateProps
+ * @see FabTrigger
+ * @see FabMenuItem
+ * @desc 공개 Root·Trigger·Menu.List·Menu.Item과 같은 구현을 조립한다. children과 내부 버튼의 className을 받지 않으며 런타임에 전달된 내부 className도 무시한다. 내부 스타일은 Root className의 nested selector 또는 data attribute로 조정한다. Trigger는 id·aria-haspopup·aria-expanded·aria-controls를, 각 액션은 role·tabIndex를 모듈이 소유하며 children·ref는 nested 입력에 포함하지 않는다. 액션마다 나머지 native button 입력을 전달하고 나머지 native div 입력은 Root에 전달한다. 열림·탐색·닫힘·원점 유지·focus 복귀는 모듈이, 실행 결과와 viewport 배치는 소비자가 맡는다.
+ * @example
+ * <Fab.Template
+ *   triggerProps={{ icon: <span>+</span>, "aria-label": "관련 작업",
+ *     size: "large", fill: "solid", priority: "primary" }}
+ *   items={[{ id: "copy-action", icon: <span>⧉</span>, "aria-label": "복사",
+ *     size: "small", fill: "outlined", priority: "primary" }]}
+ * />
+ */
+const FabTemplate = forwardRef<HTMLDivElement, FabTemplateProps>(
+  ({ triggerProps, items, ...rootProps }, ref) => (
+    <FabRoot {...rootProps} ref={ref}>
+      {/* Template의 내부 클래스는 소비자가 전달한 객체의 추가 필드로도 덮어쓰지 않는다. */}
+      <FabTrigger {...triggerProps} className={undefined} />
+      <FabMenuList>
+        {items.map(item => (
+          <FabMenuItem key={item.id} {...item} className={undefined} />
+        ))}
+      </FabMenuList>
+    </FabRoot>
+  ),
+);
+
+FabTemplate.displayName = "FabTemplate";
+
+export { FabTemplate };

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

@@ -0,0 +1,65 @@
+"use client";
+
+import clsx from "clsx";
+import { forwardRef, useImperativeHandle } from "react";
+import type { FabTriggerProps } from "../types";
+import { FabDefault } from "./Default";
+import { useFabContext } from "./Root";
+
+/**
+ * Fab Component; 공통 버튼에 연결한 메뉴 Trigger
+ * @component
+ * @property {ReactNode} props.icon 필수 장식용 콘텐츠. 열리면 콘텐츠 영역이 45도 회전하며 reduced motion에서는 전환을 생략한다.
+ * @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 필수 행동 이름. Menu.List가 이름을 따로 지정하지 않으면 메뉴 이름으로도 사용한다.
+ * @property {"button" | "submit" | "reset"} [props.type="button"] native 버튼 동작. 메뉴 열기에 폼 제출·초기화가 필요하면 소비자가 명시한다.
+ * @property {boolean} [props.disabled=false] native 실행·Tab 진입을 차단하고 Root의 mouse hover 열기도 차단한다.
+ * @property {React.MouseEventHandler<HTMLButtonElement>} [props.onClick] 기본 처리 전에 호출한다. preventDefault하면 해당 클릭의 열림 처리를 생략한다. hover로 먼저 열린 첫 포인터 클릭은 열림을 유지하고 이후 클릭·Enter·Space는 토글한다.
+ * @property {React.FocusEventHandler<HTMLButtonElement>} [props.onFocus] focus 처리 전에 호출한다. preventDefault하면 해당 focus의 열기를 생략한다. 선택·Escape 뒤 내부 focus 복귀는 다시 열지 않는다.
+ * @property {React.KeyboardEventHandler<HTMLButtonElement>} [props.onKeyDown] Root 탐색으로 버블링되는 native 키 이벤트. preventDefault하면 Root의 해당 기본 처리를 생략하지만 Tooltip의 document capture Escape는 취소하지 못한다.
+ * @property {string} [props.className] 최상위 button에 fab·fab-trigger 클래스와 병합할 추가 클래스.
+ * @property {CSSProperties} [props.style] 최상위 button의 inline style.
+ * @property {React.Ref<HTMLButtonElement>} [ref] 실제 Trigger button에 전달하는 object/callback ref.
+ * @see FabTriggerProps
+ * @see FabRoot
+ * @desc 같은 Root에 속한 액션 목록을 여는 Button이다. FabTriggerProps는 FabDefaultProps에서 id·aria-haspopup·aria-expanded·aria-controls를 제외하며 Root가 이 속성을 소유한다. Button과 마찬가지로 children을 받지 않는 아이콘 전용 버튼이고 나머지 native button 속성·이벤트는 전달한다. Root 밖에서 사용하면 오류를 발생시킨다.
+ */
+const FabTrigger = forwardRef<HTMLButtonElement, FabTriggerProps>(
+  ({ className, onClick, onFocus, ...props }, ref) => {
+    const {
+      open,
+      triggerId,
+      menuId,
+      triggerRef,
+      onTriggerClick,
+      onTriggerFocus,
+    } = useFabContext("Fab.Trigger");
+    // DOM ref를 공유하고 소비자 callback ref의 React cleanup 계약은 React에 맡긴다.
+    useImperativeHandle(ref, () => triggerRef.current!, [triggerRef]);
+    return (
+      <FabDefault
+        {...props}
+        ref={triggerRef}
+        id={triggerId}
+        className={clsx("fab-trigger", className)}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={menuId}
+        onClick={event => {
+          onClick?.(event);
+          if (!event.defaultPrevented) onTriggerClick(event);
+        }}
+        onFocus={event => {
+          onFocus?.(event);
+          if (!event.defaultPrevented) onTriggerFocus(event);
+        }}
+      />
+    );
+  },
+);
+
+FabTrigger.displayName = "FabTrigger";
+
+export { FabTrigger };

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

@@ -0,0 +1,7 @@
+export { FabDefault } from "./Default";
+export { FabExtended } from "./Extended";
+export { FabLabel } from "./Label";
+export { FabRoot, FabContext, ARROW_KEYS, useFabContext } from "./Root";
+export { FabTrigger } from "./Trigger";
+export { FabMenuList, FabMenuItem } from "./Menu";
+export { FabTemplate } from "./Template";

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

@@ -0,0 +1,80 @@
+.fab-root,
+.fab-menu-list {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+}
+
+.fab-menu-list[data-open="false"] {
+  // 전역 hidden reset의 display 제거를 피하고 닫힌 목록의 배치 공간을 유지한다.
+  // 접근성·focus 제외는 같은 상태의 aria-hidden·inert가 담당한다.
+  visibility: hidden;
+}
+
+.fab-root {
+  // 물리 좌우 방향과 방향키는 문서의 RTL 여부에 따라 반전되지 않는다.
+  direction: ltr;
+
+  &[data-open="false"] {
+    // 원점을 위한 예약 공간은 포인터 대상에서 제외하고 실제 Trigger로만 진입한다.
+    pointer-events: none;
+
+    .fab-trigger {
+      pointer-events: auto;
+    }
+  }
+
+  &[data-direction="up"],
+  &[data-direction="up"] .fab-menu-list {
+    flex-direction: column-reverse;
+  }
+
+  &[data-direction="down"],
+  &[data-direction="down"] .fab-menu-list {
+    flex-direction: column;
+  }
+
+  &[data-direction="left"],
+  &[data-direction="left"] .fab-menu-list {
+    flex-direction: row-reverse;
+  }
+
+  &[data-direction="right"],
+  &[data-direction="right"] .fab-menu-list {
+    flex-direction: row;
+  }
+
+  &[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;
+  }
+}