체크박스 컴포넌트 개발

.github/workflows/ci.yml

@@ -14,17 +14,17 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: 'pnpm'
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v3
-        with:
-          version: 9
-
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 

src/components/checkbox/CheckBox.tsx

@@ -0,0 +1,84 @@
+'use client';
+
+import clsx from 'clsx';
+import Image from 'next/image';
+import type { ChangeEvent, CSSProperties } from 'react';
+
+import styles from './styles/CheckBox.module.css';
+import { CHECKBOX_STYLE } from './constants/styleConstants';
+import type { CheckBoxProps } from './types/types';
+
+/**
+ * 체크박스 컴포넌트.
+ * @param checked 체크 여부
+ * @param onCheckedChange 체크 상태 변경 콜백
+ * @param size 체크박스 크기('large' | 'small')
+ * @param label 접근성 용도의 라벨(없으면 options.ariaLabel 필수)
+ * @param options 고급 옵션(ariaLabel/readOnly/icons)
+ */
+export default function CheckBox({
+  checked,
+  size = 'large',
+  label,
+  id,
+  name,
+  value,
+  disabled = false,
+  className,
+  options,
+  onCheckedChange,
+}: CheckBoxProps) {
+  const hasLabel =
+    label !== null && label !== undefined && (typeof label !== 'string' || label.trim().length > 0);
+  const isReadOnly = options?.readOnly || !onCheckedChange;
+  const isDisabled = disabled || isReadOnly;
+  const iconSrc = checked
+    ? CHECKBOX_STYLE.icons.checked[size]
+    : CHECKBOX_STYLE.icons.unchecked[size];
+  const boxSize = CHECKBOX_STYLE.boxSize[size];
+  const inputAriaLabel = hasLabel ? undefined : options?.ariaLabel;
+  const checkboxStyle = {
+    '--checkbox-box-size': `${boxSize}px`,
+  } as CSSProperties;
+  const iconNode = options?.icons ? (
+    checked ? (
+      options.icons.checked
+    ) : (
+      options.icons.unchecked
+    )
+  ) : (
+    <Image className={styles.icon} src={iconSrc} alt="" width={boxSize} height={boxSize} />
+  );
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    onCheckedChange?.(event.target.checked);
+  };
+
+  if (process.env.NODE_ENV !== 'production' && !hasLabel && !options?.ariaLabel) {
+    console.warn('CheckBox: label이 비어있다면 ariaLabel이 필요합니다.');
+  }
+
+  return (
+    <label
+      className={clsx(styles.checkbox, styles[size], isDisabled && styles.disabled, className)}
+      style={checkboxStyle}
+    >
+      <input
+        className={styles.input}
+        type="checkbox"
+        checked={checked}
+        aria-label={inputAriaLabel}
+        id={id}
+        name={name}
+        value={value}
+        disabled={isDisabled}
+        onChange={handleChange}
+        readOnly={isReadOnly}
+      />
+      <span className={styles.box} aria-hidden="true">
+        {iconNode}
+      </span>
+      {hasLabel ? <span className={styles.label}>{label}</span> : null}
+    </label>
+  );
+}

src/components/checkbox/constants/styleConstants.ts

@@ -0,0 +1,21 @@
+import checkedLarge from '@/assets/icons/check/checkedLarge.svg';
+import checkedSmall from '@/assets/icons/check/checkedSmall.svg';
+import nonCheckedLarge from '@/assets/icons/check/nonCheckedLarge.svg';
+import nonCheckedSmall from '@/assets/icons/check/nonCheckedSmall.svg';
+
+export const CHECKBOX_STYLE = {
+  icons: {
+    checked: {
+      large: checkedLarge,
+      small: checkedSmall,
+    },
+    unchecked: {
+      large: nonCheckedLarge,
+      small: nonCheckedSmall,
+    },
+  },
+  boxSize: {
+    large: 18,
+    small: 16,
+  },
+} as const;

src/components/checkbox/styles/CheckBox.module.css

@@ -0,0 +1,60 @@
+.checkbox {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+}
+
+.large {
+  font-size: 16px;
+}
+
+.small {
+  font-size: 14px;
+}
+
+.input {
+  position: absolute;
+  opacity: 0;
+  width: 1px;
+  height: 1px;
+  pointer-events: none;
+}
+
+.box {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--checkbox-box-size, 18px);
+  height: var(--checkbox-box-size, 18px);
+  flex-shrink: 0;
+}
+
+.icon {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+
+.label {
+  line-height: 1.4;
+}
+
+.disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+@media (max-width: 480px) {
+  .checkbox {
+    gap: 6px;
+  }
+
+  .large {
+    font-size: 15px;
+  }
+
+  .small {
+    font-size: 13px;
+  }
+}

src/components/checkbox/types/types.ts

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react';
+
+export type CheckBoxSize = 'large' | 'small';
+
+export type CheckBoxIconSet = {
+  checked: ReactNode;
+  unchecked: ReactNode;
+};
+
+export type CheckBoxOptions = {
+  ariaLabel?: string;
+  readOnly?: boolean;
+  icons?: CheckBoxIconSet;
+};
+
+export type CheckBoxOptionsWithAriaLabel = Omit<CheckBoxOptions, 'ariaLabel'> & {
+  ariaLabel: string;
+};
+
+interface CheckBoxBaseProps {
+  checked: boolean;
+  size?: CheckBoxSize;
+  id?: string;
+  name?: string;
+  value?: string;
+  disabled?: boolean;
+  className?: string;
+  onCheckedChange?: (checked: boolean) => void;
+}
+
+export type CheckBoxProps =
+  | (CheckBoxBaseProps & {
+      label: ReactNode;
+      options?: CheckBoxOptions;
+    })
+  | (CheckBoxBaseProps & {
+      label?: undefined;
+      options: CheckBoxOptionsWithAriaLabel;
+    });

src/components/dropdown/Dropdown.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import clsx from 'clsx';
+import { useEffect, useRef } from 'react';
 
 import DropdownItem from './DropdownItem';
 import useDropdown from './hooks/useDropdown';
@@ -18,6 +19,7 @@ export default function Dropdown({
   items,
   defaultValue,
   value,
+  placeholder,
   size = DEFAULT_SIZE,
   disabled = false,
   ariaLabel,
@@ -27,13 +29,40 @@ export default function Dropdown({
   itemClassName,
   onChange,
 }: DropdownProps) {
-  const { listboxId, isOpen, selectedItem, handleSelect, handleToggle, handleBlur, handleKeyDown } =
-    useDropdown({ items, defaultValue, value, disabled, onChange });
-  const triggerAriaLabel = selectedItem ? undefined : ariaLabel;
+  const {
+    listboxId,
+    isOpen,
+    selectedItem,
+    activeIndex,
+    openByKeyboard,
+    shouldRestoreFocus,
+    setActiveIndex,
+    clearRestoreFocus,
+    handleSelect,
+    handleToggle,
+    handleBlur,
+    handleKeyDown,
+  } = useDropdown({ items, defaultValue, value, disabled, onChange });
+  const triggerAriaLabel = selectedItem || placeholder ? undefined : ariaLabel;
+  const displayLabel = selectedItem?.label ?? placeholder;
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const optionRefs = useRef<Array<HTMLButtonElement | null>>([]);
+
+  useEffect(() => {
+    if (!isOpen || !openByKeyboard || activeIndex < 0) return;
+    optionRefs.current[activeIndex]?.focus();
+  }, [activeIndex, isOpen, openByKeyboard]);
+
+  useEffect(() => {
+    if (isOpen || !shouldRestoreFocus) return;
+    triggerRef.current?.focus();
+    clearRestoreFocus();
+  }, [clearRestoreFocus, isOpen, shouldRestoreFocus]);
 
   return (
     <div className={clsx(styles.dropdown, className)} onBlur={handleBlur} onKeyDown={handleKeyDown}>
       <button
+        ref={triggerRef}
         type="button"
         className={clsx(styles.button, disabled && styles.disabled, buttonClassName)}
         aria-haspopup="listbox"
@@ -43,7 +72,9 @@ export default function Dropdown({
         disabled={disabled}
         onClick={handleToggle}
       >
-        <span className={styles.label}>{selectedItem?.label}</span>
+        <span className={clsx(styles.label, !selectedItem && placeholder && styles.placeholder)}>
+          {displayLabel}
+        </span>
         <span className={clsx(styles.icon, isOpen && styles.iconOpen)} aria-hidden="true">
           <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
             <path d="M3.5 6L8 10.5L12.5 6" stroke="currentColor" strokeWidth="1.6" />
@@ -57,14 +88,19 @@ export default function Dropdown({
           role="listbox"
           aria-label={ariaLabel}
         >
-          {items.map((item) => (
+          {items.map((item, index) => (
             <DropdownItem
               key={item.value}
               label={item.label}
               isSelected={item.value === selectedItem?.value}
               size={size}
               className={itemClassName}
+              tabIndex={openByKeyboard && activeIndex === index ? 0 : -1}
+              onFocus={() => setActiveIndex(index)}
               onSelect={() => handleSelect(item.value)}
+              ref={(node) => {
+                optionRefs.current[index] = node;
+              }}
             />
           ))}
         </div>

src/components/dropdown/DropdownItem.tsx

@@ -1,24 +1,29 @@
 import clsx from 'clsx';
+import { forwardRef } from 'react';
 
 import styles from './styles/DropdownItem.module.css';
 import type { DropdownItemProps } from './types/types';
 
-export default function DropdownItem({
-  label,
-  isSelected,
-  size,
-  className,
-  onSelect,
-}: DropdownItemProps) {
+const DropdownItem = forwardRef<HTMLButtonElement, DropdownItemProps>(function DropdownItem(
+  { label, isSelected, size, className, onSelect, tabIndex, onFocus },
+  ref,
+) {
   return (
     <button
+      ref={ref}
       type="button"
       className={clsx(styles.item, styles[size], isSelected && styles.selected, className)}
       role="option"
       aria-selected={isSelected}
+      tabIndex={tabIndex}
       onClick={onSelect}
+      onFocus={onFocus}
     >
       {label}
     </button>
   );
-}
+});
+
+DropdownItem.displayName = 'DropdownItem';
+
+export default DropdownItem;