@uniai-fe/uds-primitives 0.7.5 → 0.8.1

package/dist/styles.css

@@ -843,6 +843,30 @@
   0px 2px 8px rgba(0, 0, 0, 0.08), 0px 0px 4px rgba(0, 0, 0, 0.12);
   --switch-focus-ring: var(--color-primary-focus);
   --switch-disabled-opacity: 0.4;
+  --switch-text-width: fit-content;
+  --switch-text-height-medium: 32px;
+  --switch-text-height-large: 40px;
+  --switch-text-padding: 2px;
+  --switch-text-radius-medium: 6px;
+  --switch-text-radius-large: 10px;
+  --switch-text-item-radius-medium: 4px;
+  --switch-text-item-radius-large: 8px;
+  --switch-text-item-min-width: 64px;
+  --switch-text-item-width: auto;
+  --switch-text-item-padding-x: 12px;
+  --switch-text-background: var(--color-background-alternative-cool-gray);
+  --switch-text-item-background-selected: var(--color-surface-static-white);
+  --switch-text-label-color: var(--color-label-standard);
+  --switch-text-label-font-size-medium: var(--font-body-xxsmall-size);
+  --switch-text-label-font-size-large: var(--font-body-xsmall-size);
+  --switch-text-label-line-height-medium: 1em;
+  --switch-text-label-line-height-large: 1em;
+  --switch-text-label-letter-spacing-medium: 0px;
+  --switch-text-label-letter-spacing-large: 0.2px;
+  --switch-text-label-font-weight: var(--font-body-xxsmall-weight);
+  --switch-text-label-font-weight-selected: 600;
+  --switch-text-item-shadow-selected:
+  0px 2px 8px rgba(0, 0, 0, 0.04), 0px 0px 2px rgba(0, 0, 0, 0.04);
   --tab-height-small: 40px;
   --tab-height-medium: 48px;
   --tab-height-large: 56px;
@@ -5319,6 +5343,118 @@ figure.chip {
   transform: translateX(calc(var(--switch-track-width) - var(--switch-handle-size) - var(--switch-track-padding) * 2));
 }
 
+.switch-text {
+  --switch-text-height: var(--switch-text-height-medium);
+  --switch-text-radius: var(--switch-text-radius-medium);
+  --switch-text-item-radius: var(--switch-text-item-radius-medium);
+  --switch-text-label-font-size: var(--switch-text-label-font-size-medium);
+  --switch-text-label-line-height: var(--switch-text-label-line-height-medium);
+  --switch-text-label-letter-spacing: var(
+    --switch-text-label-letter-spacing-medium
+  );
+  display: flex;
+  box-sizing: border-box;
+  width: var(--switch-text-width);
+  max-width: 100%;
+  min-height: var(--switch-text-height);
+  padding: var(--switch-text-padding);
+  border-radius: var(--switch-text-radius);
+  background-color: var(--switch-text-background);
+  overflow: auto hidden;
+}
+
+.switch-text:where([data-size=large]) {
+  --switch-text-height: var(--switch-text-height-large);
+  --switch-text-radius: var(--switch-text-radius-large);
+  --switch-text-item-radius: var(--switch-text-item-radius-large);
+  --switch-text-label-font-size: var(--switch-text-label-font-size-large);
+  --switch-text-label-line-height: var(--switch-text-label-line-height-large);
+  --switch-text-label-letter-spacing: var(
+    --switch-text-label-letter-spacing-large
+  );
+}
+
+.switch-text:where([data-disabled=true]) {
+  opacity: var(--switch-disabled-opacity);
+}
+
+.switch-text-list {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  width: auto;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.switch-text-item {
+  flex: 0 0 auto;
+  min-width: var(--switch-text-item-min-width);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.switch-text:where([data-width=custom]) .switch-text-list {
+  width: 100%;
+}
+
+.switch-text:where([data-width=custom]) .switch-text-item {
+  flex: 1 1 0;
+}
+
+.switch-text:where([data-item-width=custom]) .switch-text-item {
+  flex: 0 0 var(--switch-text-item-width);
+  width: var(--switch-text-item-width);
+}
+
+.switch-text-button {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  min-width: var(--switch-text-item-min-width);
+  min-height: calc(var(--switch-text-height) - var(--switch-text-padding) * 2);
+  padding: 0 var(--switch-text-item-padding-x);
+  border: none;
+  border-radius: var(--switch-text-item-radius);
+  background-color: transparent;
+  color: var(--switch-text-label-color);
+  cursor: pointer;
+  font-size: var(--switch-text-label-font-size);
+  font-weight: var(--switch-text-label-font-weight);
+  line-height: var(--switch-text-label-line-height);
+  letter-spacing: var(--switch-text-label-letter-spacing);
+  text-align: center;
+  transition: background-color 0.2s ease, box-shadow 0.2s ease, opacity 0.2s ease;
+}
+
+.switch-text-button:where([data-state=on]) {
+  background-color: var(--switch-text-item-background-selected);
+  box-shadow: var(--switch-text-item-shadow-selected);
+  font-weight: var(--switch-text-label-font-weight-selected);
+}
+
+.switch-text-button:where([data-disabled=true]) {
+  cursor: not-allowed;
+}
+
+.switch-text-button:where(:focus-visible) {
+  outline: 2px solid var(--switch-focus-ring);
+  outline-offset: 2px;
+}
+
+.switch-text-label {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font: inherit;
+  color: inherit;
+  white-space: nowrap;
+}
+
 
 
 .tab-root {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.7.5",
+  "version": "0.8.1",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,
@@ -62,8 +62,8 @@
     "@mantine/core": "^8",
     "@mantine/dates": "^8",
     "@mantine/hooks": "^8",
-    "@uniai-fe/uds-foundation": "^0.4.2",
-    "@uniai-fe/util-functions": "^0.2.3",
+    "@uniai-fe/uds-foundation": "^0.4.8",
+    "@uniai-fe/util-functions": "^0.3.0",
     "react": "^19",
     "react-daum-postcode": "^4.0.0",
     "react-dom": "^19",
@@ -96,7 +96,7 @@
     "@mantine/hooks": "^8.3.18",
     "@svgr/webpack": "^8.1.0",
     "@types/node": "^24.12.3",
-    "@types/react": "^19.2.16",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@uniai-fe/eslint-config": "workspace:*",
     "@uniai-fe/next-devkit": "workspace:*",
@@ -104,9 +104,9 @@
     "@uniai-fe/uds-foundation": "workspace:*",
     "@uniai-fe/util-functions": "workspace:*",
     "eslint": "^9.39.2",
-    "prettier": "^3.8.3",
-    "react-hook-form": "^7.77.0",
-    "sass": "^1.100.0",
+    "prettier": "^3.8.4",
+    "react-hook-form": "^7.80.0",
+    "sass": "^1.101.0",
     "typescript": "5.9.3"
   }
 }

package/src/components/switch/index.tsx

@@ -1,10 +1,17 @@
 /**
- * Switch; standard toggle leaf 카테고리 배럴
+ * Switch; namespace 배럴 export
  * @desc
- * - `Switch`: on/off 전환만 담당하는 leaf switch 컴포넌트다.
- * - `SwitchProps`, `SwitchSize`: public 계약 타입이다.
+ * - `Switch`: on/off 전환만 담당하는 callable standard toggle 컴포넌트다.
+ * - `Switch.Text`: options 배열 기반 단일 선택 text switch다.
+ * - hooks/types/utils/img/styles 도구 레이어 외 raw component name은 root public surface로 열지 않는다.
  */
 import "./index.scss";
 
-export * from "./markup";
+import { Switch as SwitchBase } from "./markup";
+import { SwitchText } from "./markup/text-type";
+
+export const Switch = Object.assign(SwitchBase, {
+  Text: SwitchText,
+});
+
 export type * from "./types";

package/src/components/switch/markup/text-type/Label.tsx

@@ -0,0 +1,22 @@
+import clsx from "clsx";
+import { Slot } from "../../../slot";
+import type { SwitchTextLabelProps } from "../../types";
+
+/**
+ * Switch.Text Label; 옵션 라벨 텍스트 슬롯.
+ * @component
+ * @param {SwitchTextLabelProps} props
+ * @param {React.ReactNode} [props.children] 라벨 콘텐츠.
+ * @param {string} [props.className] 라벨 className.
+ */
+export default function SwitchTextLabel({
+  className,
+  ...restProps
+}: SwitchTextLabelProps) {
+  return (
+    <Slot.Text
+      className={clsx("switch-text-label", className)}
+      {...restProps}
+    />
+  );
+}

package/src/components/switch/markup/text-type/List.tsx

@@ -0,0 +1,132 @@
+import type { KeyboardEvent } from "react";
+import type { SwitchTextButtonEvent, SwitchTextListProps } from "../../types";
+import SwitchTextLabel from "./Label";
+
+/**
+ * Switch.Text List; radio 성격의 option item 리스트.
+ * @component
+ * @param {SwitchTextListProps} props 리스트 렌더링에 사용되는 props.
+ * @param {SwitchTextOption[]} props.options 렌더링할 옵션 배열.
+ * @param {boolean} props.disabled 전체 비활성 여부.
+ * @param {SwitchTextValue | undefined} props.selectedValue 현재 선택된 값.
+ * @param {number} props.focusableIndex 포커스를 받을 기본 index.
+ * @param {number} props.fallbackIndex 첫 번째 활성화 index.
+ * @param {RefObject<Array<HTMLButtonElement | null>>} props.itemRefs 버튼 ref 목록.
+ * @param {(value: SwitchTextValue) => void} props.onSelect 값 변경 콜백.
+ * @param {(index: number) => void} props.onFocusItemAt index 포커스 함수.
+ * @param {(event: KeyboardEvent<HTMLButtonElement>, currentIndex: number) => void} props.onArrowNavigate 화살표 키 처리 콜백.
+ */
+const SwitchTextList = ({
+  options,
+  disabled,
+  selectedValue,
+  focusableIndex,
+  fallbackIndex,
+  itemRefs,
+  onSelect,
+  onFocusItemAt,
+  onArrowNavigate,
+}: SwitchTextListProps) => (
+  <ul className="switch-text-list">
+    {options.map((option, index) => {
+      const isDisabled = disabled || Boolean(option.disabled);
+      const isSelected = selectedValue === option.value;
+      const tabIndex =
+        isDisabled || focusableIndex === -1
+          ? -1
+          : index === focusableIndex
+            ? 0
+            : -1;
+
+      /**
+       * disabled item의 pointer/key 이벤트를 같은 기준으로 차단한다.
+       * @param {SwitchTextButtonEvent} event button interaction event.
+       * @returns {boolean} 차단 여부.
+       */
+      const onStopIfDisabled = (event: SwitchTextButtonEvent): boolean => {
+        if (!isDisabled) {
+          return false;
+        }
+
+        event.preventDefault();
+        event.stopPropagation();
+        return true;
+      };
+
+      /**
+       * item click 선택 처리. 이미 선택된 항목은 해제하지 않는다.
+       * @param {SwitchTextButtonEvent} event button interaction event.
+       */
+      const onClick = (event: SwitchTextButtonEvent) => {
+        if (onStopIfDisabled(event) || isSelected) {
+          return;
+        }
+
+        onSelect(option.value);
+      };
+
+      /**
+       * Home/End는 첫/마지막 enabled item으로 이동하고, arrow key는 root 로직에 위임한다.
+       * @param {KeyboardEvent<HTMLButtonElement>} event keyboard event.
+       */
+      const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
+        if (onStopIfDisabled(event)) {
+          return;
+        }
+
+        if (event.key === "Home") {
+          event.preventDefault();
+          if (fallbackIndex >= 0) {
+            const fallbackOption = options[fallbackIndex];
+            onFocusItemAt(fallbackIndex);
+            if (fallbackOption) {
+              onSelect(fallbackOption.value);
+            }
+          }
+          return;
+        }
+
+        if (event.key === "End") {
+          event.preventDefault();
+          for (let i = options.length - 1; i >= 0; i -= 1) {
+            const candidate = options[i];
+            if (candidate && !disabled && !candidate.disabled) {
+              onFocusItemAt(i);
+              onSelect(candidate.value);
+              break;
+            }
+          }
+          return;
+        }
+
+        onArrowNavigate(event, index);
+      };
+
+      return (
+        <li className="switch-text-item" key={option.value}>
+          <button
+            ref={node => {
+              itemRefs.current[index] = node;
+            }}
+            type="button"
+            role="radio"
+            aria-checked={isSelected}
+            aria-disabled={isDisabled ? "true" : undefined}
+            tabIndex={tabIndex}
+            className="switch-text-button"
+            data-state={isSelected ? "on" : "off"}
+            data-disabled={isDisabled ? "true" : undefined}
+            onPointerDown={onStopIfDisabled}
+            onKeyDown={onKeyDown}
+            onClick={onClick}
+            disabled={isDisabled}
+          >
+            <SwitchTextLabel>{option.label}</SwitchTextLabel>
+          </button>
+        </li>
+      );
+    })}
+  </ul>
+);
+
+export { SwitchTextList };

package/src/components/switch/markup/text-type/SwitchText.tsx

@@ -0,0 +1,237 @@
+import { styleBaseSize } from "@uniai-fe/util-functions";
+import clsx from "clsx";
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type KeyboardEvent,
+} from "react";
+import type {
+  SwitchTextOption,
+  SwitchTextProps,
+  SwitchTextValue,
+} from "../../types";
+import { SwitchTextList } from "./List";
+
+/**
+ * 첫 enabled option value를 찾는다.
+ * @function
+ * @param {SwitchTextOption[]} options 선택 가능한 option 배열.
+ * @returns {SwitchTextValue | undefined} 첫 enabled option value.
+ */
+const findFirstEnabledValue = (
+  options: SwitchTextOption[],
+): SwitchTextValue | undefined => {
+  return options.find(option => !option.disabled)?.value;
+};
+
+/**
+ * Switch.Text; options 배열 기반 단일 선택 text switch.
+ * @component
+ * @param {SwitchTextProps} props
+ * @param {SwitchTextOption[]} props.options 렌더할 옵션 배열.
+ * @param {string} props.ariaLabel 접근성 라벨.
+ * @param {"medium" | "large"} [props.size="medium"] Figma text switch scale.
+ * @param {number | string} [props.width] container width.
+ * @param {number | string} [props.itemWidth] item width.
+ * @param {SwitchTextValue} [props.value] 제어형 선택값.
+ * @param {SwitchTextValue} [props.defaultValue] 비제어 초기 선택값.
+ * @param {(value: SwitchTextValue) => void} [props.onValueChange] 선택값 변경 콜백.
+ * @param {boolean} [props.disabled=false] 전체 비활성 여부.
+ * @example
+ * <Switch.Text ariaLabel="기간 선택" options={options} defaultValue="daily" />
+ */
+const SwitchText = forwardRef<HTMLDivElement, SwitchTextProps>(
+  (
+    {
+      options,
+      ariaLabel,
+      size = "medium",
+      width,
+      itemWidth,
+      value,
+      defaultValue,
+      onValueChange,
+      disabled = false,
+      className,
+      style,
+      ...restProps
+    },
+    forwardedRef,
+  ) => {
+    // value prop 제공 여부로 제어형/비제어형을 구분한다.
+    const isControlled = value !== undefined;
+    // defaultValue가 없으면 첫 enabled option을 기본 선택해 선택 해제 불가 정책을 유지한다.
+    const initialValue = defaultValue ?? findFirstEnabledValue(options);
+    const [uncontrolledValue, setUncontrolledValue] = useState<
+      SwitchTextValue | undefined
+    >(initialValue);
+    const selectedValue = isControlled ? value : uncontrolledValue;
+    // itemRefs는 roving tabindex focus 이동에만 사용한다.
+    const itemRefs = useRef<Array<HTMLButtonElement | null>>([]);
+    // fallbackIndex는 선택값이 없거나 사라졌을 때 포커스 가능한 첫 item이다.
+    const fallbackIndex = useMemo(
+      () => options.findIndex(option => !option.disabled),
+      [options],
+    );
+    const selectedIndex = useMemo(
+      () => options.findIndex(option => option.value === selectedValue),
+      [options, selectedValue],
+    );
+    const focusableIndex =
+      selectedIndex >= 0
+        ? selectedIndex
+        : fallbackIndex >= 0
+          ? fallbackIndex
+          : -1;
+
+    useEffect(() => {
+      if (isControlled) {
+        return;
+      }
+
+      // options 변경으로 현재 비제어 선택값이 사라지면 첫 enabled option으로 복구한다.
+      const hasSelectedOption = options.some(
+        option => option.value === uncontrolledValue && !option.disabled,
+      );
+      if (hasSelectedOption) {
+        return;
+      }
+
+      setUncontrolledValue(findFirstEnabledValue(options));
+    }, [isControlled, options, uncontrolledValue]);
+
+    /**
+     * 선택값 변경을 제어형/비제어형 공통 경로로 처리한다.
+     * @param {SwitchTextValue} nextValue 다음 선택값.
+     */
+    const onSelect = useCallback(
+      (nextValue: SwitchTextValue) => {
+        if (!isControlled) {
+          setUncontrolledValue(nextValue);
+        }
+        onValueChange?.(nextValue);
+      },
+      [isControlled, onValueChange],
+    );
+
+    /**
+     * index에 해당하는 item button으로 focus를 이동한다.
+     * @param {number} index focus 대상 option index.
+     */
+    const onFocusItemAt = useCallback((index: number) => {
+      itemRefs.current[index]?.focus();
+    }, []);
+
+    /**
+     * 현재 index 기준 다음 enabled option index를 계산한다.
+     * @param {number} currentIndex 현재 option index.
+     * @param {1 | -1} direction 탐색 방향.
+     * @returns {number} 다음 enabled option index.
+     */
+    const getNextEnabledIndex = useCallback(
+      (currentIndex: number, direction: 1 | -1): number => {
+        if (options.length === 0) {
+          return -1;
+        }
+
+        let index = currentIndex;
+        for (let i = 0; i < options.length; i += 1) {
+          index = (index + direction + options.length) % options.length;
+          const option = options[index];
+          if (option && !option.disabled) {
+            return index;
+          }
+        }
+
+        return currentIndex;
+      },
+      [options],
+    );
+
+    /**
+     * Arrow key 입력 시 focus와 선택값을 다음 enabled item으로 함께 이동한다.
+     * @param {KeyboardEvent<HTMLButtonElement>} event keyboard event.
+     * @param {number} currentIndex 현재 option index.
+     */
+    const onArrowNavigate = useCallback(
+      (event: KeyboardEvent<HTMLButtonElement>, currentIndex: number) => {
+        if (
+          event.key !== "ArrowRight" &&
+          event.key !== "ArrowLeft" &&
+          event.key !== "ArrowUp" &&
+          event.key !== "ArrowDown"
+        ) {
+          return;
+        }
+
+        event.preventDefault();
+        const direction =
+          event.key === "ArrowRight" || event.key === "ArrowDown" ? 1 : -1;
+        const nextIndex = getNextEnabledIndex(currentIndex, direction);
+        if (nextIndex === currentIndex) {
+          return;
+        }
+
+        const nextOption = options[nextIndex];
+        if (nextOption) {
+          onFocusItemAt(nextIndex);
+          onSelect(nextOption.value);
+        }
+      },
+      [getNextEnabledIndex, onFocusItemAt, onSelect, options],
+    );
+
+    const resolvedWidth =
+      width !== undefined ? styleBaseSize("px", width) : undefined;
+    const resolvedItemWidth =
+      itemWidth !== undefined ? styleBaseSize("px", itemWidth) : undefined;
+    const rootStyle =
+      resolvedWidth || resolvedItemWidth
+        ? ({
+            ...(style ?? {}),
+            ...(resolvedWidth
+              ? { ["--switch-text-width" as const]: resolvedWidth }
+              : {}),
+            ...(resolvedItemWidth
+              ? { ["--switch-text-item-width" as const]: resolvedItemWidth }
+              : {}),
+          } as CSSProperties)
+        : style;
+
+    return (
+      <div
+        {...restProps}
+        ref={forwardedRef}
+        role="radiogroup"
+        aria-label={ariaLabel}
+        className={clsx("switch-text", className)}
+        data-size={size}
+        data-width={resolvedWidth ? "custom" : undefined}
+        data-disabled={disabled ? "true" : undefined}
+        data-item-width={resolvedItemWidth ? "custom" : undefined}
+        style={rootStyle}
+      >
+        <SwitchTextList
+          options={options}
+          disabled={disabled}
+          selectedValue={selectedValue}
+          focusableIndex={focusableIndex}
+          fallbackIndex={fallbackIndex}
+          itemRefs={itemRefs}
+          onSelect={onSelect}
+          onFocusItemAt={onFocusItemAt}
+          onArrowNavigate={onArrowNavigate}
+        />
+      </div>
+    );
+  },
+);
+
+SwitchText.displayName = "Switch.Text";
+
+export { SwitchText };

package/src/components/switch/markup/text-type/index.ts

@@ -0,0 +1 @@
+export { SwitchText } from "./SwitchText";

package/src/components/switch/styles/switch.scss

@@ -61,3 +61,120 @@
     )
   );
 }
+
+.switch-text {
+  --switch-text-height: var(--switch-text-height-medium);
+  --switch-text-radius: var(--switch-text-radius-medium);
+  --switch-text-item-radius: var(--switch-text-item-radius-medium);
+  --switch-text-label-font-size: var(--switch-text-label-font-size-medium);
+  --switch-text-label-line-height: var(--switch-text-label-line-height-medium);
+  --switch-text-label-letter-spacing: var(
+    --switch-text-label-letter-spacing-medium
+  );
+  display: flex;
+  box-sizing: border-box;
+  width: var(--switch-text-width);
+  max-width: 100%;
+  min-height: var(--switch-text-height);
+  padding: var(--switch-text-padding);
+  border-radius: var(--switch-text-radius);
+  background-color: var(--switch-text-background);
+  overflow: auto hidden;
+}
+
+.switch-text:where([data-size="large"]) {
+  --switch-text-height: var(--switch-text-height-large);
+  --switch-text-radius: var(--switch-text-radius-large);
+  --switch-text-item-radius: var(--switch-text-item-radius-large);
+  --switch-text-label-font-size: var(--switch-text-label-font-size-large);
+  --switch-text-label-line-height: var(--switch-text-label-line-height-large);
+  --switch-text-label-letter-spacing: var(
+    --switch-text-label-letter-spacing-large
+  );
+}
+
+.switch-text:where([data-disabled="true"]) {
+  opacity: var(--switch-disabled-opacity);
+}
+
+.switch-text-list {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  width: auto;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.switch-text-item {
+  flex: 0 0 auto;
+  min-width: var(--switch-text-item-min-width);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.switch-text:where([data-width="custom"]) .switch-text-list {
+  width: 100%;
+}
+
+.switch-text:where([data-width="custom"]) .switch-text-item {
+  flex: 1 1 0;
+}
+
+.switch-text:where([data-item-width="custom"]) .switch-text-item {
+  flex: 0 0 var(--switch-text-item-width);
+  width: var(--switch-text-item-width);
+}
+
+.switch-text-button {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  min-width: var(--switch-text-item-min-width);
+  min-height: calc(
+    var(--switch-text-height) - (var(--switch-text-padding) * 2)
+  );
+  padding: 0 var(--switch-text-item-padding-x);
+  border: none;
+  border-radius: var(--switch-text-item-radius);
+  background-color: transparent;
+  color: var(--switch-text-label-color);
+  cursor: pointer;
+  font-size: var(--switch-text-label-font-size);
+  font-weight: var(--switch-text-label-font-weight);
+  line-height: var(--switch-text-label-line-height);
+  letter-spacing: var(--switch-text-label-letter-spacing);
+  text-align: center;
+  transition:
+    background-color 0.2s ease,
+    box-shadow 0.2s ease,
+    opacity 0.2s ease;
+}
+
+.switch-text-button:where([data-state="on"]) {
+  background-color: var(--switch-text-item-background-selected);
+  box-shadow: var(--switch-text-item-shadow-selected);
+  font-weight: var(--switch-text-label-font-weight-selected);
+}
+
+.switch-text-button:where([data-disabled="true"]) {
+  cursor: not-allowed;
+}
+
+.switch-text-button:where(:focus-visible) {
+  outline: 2px solid var(--switch-focus-ring);
+  outline-offset: 2px;
+}
+
+.switch-text-label {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font: inherit;
+  color: inherit;
+  white-space: nowrap;
+}

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

@@ -18,4 +18,29 @@
     0px 2px 8px rgba(0, 0, 0, 0.08), 0px 0px 4px rgba(0, 0, 0, 0.12);
   --switch-focus-ring: var(--color-primary-focus);
   --switch-disabled-opacity: 0.4;
+
+  --switch-text-width: fit-content;
+  --switch-text-height-medium: 32px;
+  --switch-text-height-large: 40px;
+  --switch-text-padding: 2px;
+  --switch-text-radius-medium: 6px;
+  --switch-text-radius-large: 10px;
+  --switch-text-item-radius-medium: 4px;
+  --switch-text-item-radius-large: 8px;
+  --switch-text-item-min-width: 64px;
+  --switch-text-item-width: auto;
+  --switch-text-item-padding-x: 12px;
+  --switch-text-background: var(--color-background-alternative-cool-gray);
+  --switch-text-item-background-selected: var(--color-surface-static-white);
+  --switch-text-label-color: var(--color-label-standard);
+  --switch-text-label-font-size-medium: var(--font-body-xxsmall-size);
+  --switch-text-label-font-size-large: var(--font-body-xsmall-size);
+  --switch-text-label-line-height-medium: 1em;
+  --switch-text-label-line-height-large: 1em;
+  --switch-text-label-letter-spacing-medium: 0px;
+  --switch-text-label-letter-spacing-large: 0.2px;
+  --switch-text-label-font-weight: var(--font-body-xxsmall-weight);
+  --switch-text-label-font-weight-selected: 600;
+  --switch-text-item-shadow-selected:
+    0px 2px 8px rgba(0, 0, 0, 0.04), 0px 0px 2px rgba(0, 0, 0, 0.04);
 }

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

@@ -1 +1,2 @@
 export type * from "./switch";
+export type * from "./text";

package/src/components/switch/types/text.ts

@@ -0,0 +1,128 @@
+import type {
+  ComponentPropsWithoutRef,
+  KeyboardEvent,
+  MouseEvent,
+  PointerEvent,
+  ReactNode,
+  RefObject,
+} from "react";
+import type { SlotTextProps } from "../../slot";
+
+/**
+ * Switch.Text value 타입. 문자열 value를 사용한다.
+ */
+export type SwitchTextValue = string;
+
+/**
+ * Switch.Text size; Figma text switch height/typography 축
+ * @typedef {"medium" | "large"} SwitchTextSize
+ */
+export type SwitchTextSize = "medium" | "large";
+
+/**
+ * Switch.Text width; number는 px로 변환하고, string은 그대로 사용한다.
+ * @typedef {number | string} SwitchTextWidth
+ */
+export type SwitchTextWidth = number | string;
+
+/**
+ * Switch.Text option 정의.
+ * @property {SwitchTextValue} value 고유 value.
+ * @property {ReactNode} label 표시 라벨.
+ * @property {boolean} [disabled] 비활성화 여부.
+ */
+export interface SwitchTextOption {
+  /**
+   * 고유 value.
+   */
+  value: SwitchTextValue;
+  /**
+   * 표시 라벨.
+   */
+  label: ReactNode;
+  /**
+   * 비활성화 여부.
+   */
+  disabled?: boolean;
+}
+
+type SwitchTextRootProps = Omit<
+  ComponentPropsWithoutRef<"div">,
+  "children" | "onChange" | "role"
+>;
+
+/**
+ * Switch.Text props; options 배열 기반 단일 선택 public props.
+ * @property {SwitchTextOption[]} options 렌더할 옵션 배열.
+ * @property {string} ariaLabel 접근성 라벨.
+ * @property {"medium" | "large"} [size] Figma text switch scale.
+ * @property {number | string} [width] container width.
+ * @property {number | string} [itemWidth] item width.
+ * @property {SwitchTextValue} [value] 제어형 선택값.
+ * @property {SwitchTextValue} [defaultValue] 비제어 초기 선택값.
+ * @property {(value: SwitchTextValue) => void} [onValueChange] 선택값 변경 콜백.
+ * @property {boolean} [disabled] 전체 비활성 여부.
+ */
+export interface SwitchTextProps extends SwitchTextRootProps {
+  /**
+   * 렌더할 옵션 배열.
+   */
+  options: SwitchTextOption[];
+  /**
+   * 접근성 라벨.
+   */
+  ariaLabel: string;
+  /**
+   * Figma text switch scale.
+   */
+  size?: SwitchTextSize;
+  /**
+   * container width.
+   */
+  width?: SwitchTextWidth;
+  /**
+   * item width.
+   */
+  itemWidth?: SwitchTextWidth;
+  /**
+   * 제어형 선택값.
+   */
+  value?: SwitchTextValue;
+  /**
+   * 비제어 초기 선택값.
+   */
+  defaultValue?: SwitchTextValue;
+  /**
+   * 선택값 변경 콜백.
+   */
+  onValueChange?: (value: SwitchTextValue) => void;
+  /**
+   * 전체 비활성 여부.
+   */
+  disabled?: boolean;
+}
+
+export type SwitchTextButtonEvent =
+  | MouseEvent<HTMLButtonElement>
+  | PointerEvent<HTMLButtonElement>
+  | KeyboardEvent<HTMLButtonElement>;
+
+export interface SwitchTextListProps {
+  options: SwitchTextOption[];
+  disabled: boolean;
+  selectedValue?: SwitchTextValue;
+  focusableIndex: number;
+  fallbackIndex: number;
+  itemRefs: RefObject<Array<HTMLButtonElement | null>>;
+  onSelect: (value: SwitchTextValue) => void;
+  onFocusItemAt: (index: number) => void;
+  onArrowNavigate: (
+    event: KeyboardEvent<HTMLButtonElement>,
+    currentIndex: number,
+  ) => void;
+}
+
+/**
+ * Switch.Text Label props.
+ */
+export type SwitchTextLabelProps = SlotTextProps;