공통 컴포넌트 사용 가이드

[aahreum]

Taskify의 공통 컴포넌트 사용 가이드를 정리하는 페이지입니다.

사용 가이드를 코멘트로 남겨주세요!

📘 Dropdown 컴포넌트 사용 방법 >
📘 Combobox 컴포넌트 사용 방법 >
📘 Input 컴포넌트 사용 방법 >
📘 Title 컴포넌트 사용 방법 >

[aahreum]

📘 Dropdown 컴포넌트 사용 방법

Dropdown은 더보기 메뉴, 카드 옵션 메뉴 등

사용자가 여러 액션 중 하나를 선택할 수 있도록 제공하는 컴포넌트입니다.

아래의 구성 요소를 조합하여 사용할 수 있습니다.

---

🔧 구성 요소 설명

1. <Dropdown />

• 드롭다운 전체 컴포넌트를 감싸는 컨테이너입니다.
• 내부에서 Trigger와 List의 열림/닫힘 상태를 관리합니다.

<Dropdown> ... </Dropdown>

---

2. <Dropdown.Trigger />

• 드롭다운을 열고 닫는 트리거 버튼입니다.

• ariaLabel을 통해 접근성용 레이블을 설정할 수 있습니다.

• 자식 요소로는 자유롭게 컴포넌트를 전달할 수 있습니다.

  (예: KebabMore 아이콘, 혹은 아바타 + 이름 조합 등)

<Dropdown.Trigger ariaLabel="더보기 버튼">
  <Icons.KebabMore />
</Dropdown.Trigger>

---

3. <Dropdown.List />

• 드롭다운 메뉴 항목들을 렌더링하는 리스트 컨테이너입니다.
• Trigger 버튼 하단 8px 위치에 표시되도록 설정되어 있습니다.

<Dropdown.List> ... </Dropdown.List>

---

4. <Dropdown.Item />

• 실제 선택 가능한 액션 아이템입니다.

• onClick에서 실행할 함수를 연결합니다.

  (예: "삭제" → 카드 삭제 함수 전달)

• children으로 화면에 표시할 텍스트를 입력합니다.

<Dropdown.Item onClick={handleDelete}>삭제하기</Dropdown.Item>

---

📄 예제 코드

<Dropdown>
  <Dropdown.Trigger ariaLabel="더보기 버튼">
    <Icons.KebabMore />   {/* 렌더링할 컴포넌트 전달 */}
  </Dropdown.Trigger>

  <Dropdown.List>
    {/* console.log는 예시입니다. 실제 동작할 함수를 전달하세요! */}
    <Dropdown.Item onClick={() => console.log('수정')}>
      수정하기
    </Dropdown.Item>
    <Dropdown.Item onClick={() => console.log('삭제')}>
      삭제하기
    </Dropdown.Item>
  </Dropdown.List>
</Dropdown>

📺 예제 코드 적용 시 (보라색 영역은 hover 효과)

---

✅ 요약

1. Dropdown으로 전체를 감싸서 구성
2. Trigger를 클릭하면 List가 열리고, 다시 클릭하면 닫힘
3. List 내부에는 여러 개의 Dropdown.Item을 배치
4. Item을 클릭하면 전달된 onClick 함수가 실행
5. Trigger 하단 8px 지점에 List가 표시되어 UI 일관성 유지

[aahreum]

📘 Combobox 컴포넌트 사용 방법

Combobox는 담당자 선택 / 상태 선택 등

사용자가 목록에서 값을 검색·선택할 수 있도록 제공하는 컴포넌트입니다.

아래 가이드에 따라 구성 요소를 조합해 사용할 수 있습니다.

---

🔧 구성 요소 설명

1. <Combobox />

• 전체 컴포넌트를 감싸는 컨테이너 및 Context Provider입니다.
• value, setValue에 부모 컴포넌트의 useState를 연결합니다.

<Combobox value={value} setValue={setValue}>...</Combobox>

---

2. <Combobox.Trigger />

• 입력창(Trigger) 역할을 하는 컴포넌트입니다.
• name, placeholder를 설정해 주세요.
• 클릭 시 Combobox.List가 열리고, input 영역에서 Combobox.Item의 value 값을 검색할 수 있습니다.

<Combobox.Trigger name="담당자" placeholder="이름을 입력해 주세요" />

---

3. <Combobox.List />

• Combobox.Item들을 감싸는 리스트 컨테이너입니다.
• Trigger를 클릭하면 이 리스트가 화면에 나타납니다.

<Combobox.List> ... </Combobox.List>

---

4. <Combobox.Item />

• 실제 선택 가능한 항목입니다.
• value에 선택될 값을 전달합니다.
• 자식 요소에는 표시할 UI(아이콘, 텍스트 등)를 자유롭게 넣을 수 있습니다.

<Combobox.Item value={user.name}>
  <span>{user.avatar}</span>
  <span>{user.name}</span>
</Combobox.Item>

---

📄 예제 코드

const users = [
  { name: '배유철', avatar: '👨' },
  { name: '배동석', avatar: '👨‍💼' },
  { name: '캬캬캬', avatar: '👨‍🎤' },
];

const [selectedUser, setSelectedUser] = useState<string>('');
console.log(selectedUser); // 예: "배유철"

return (
  <Combobox value={selectedUser} setValue={setSelectedUser}>
    <Combobox.Trigger name="담당자" placeholder="이름을 입력해 주세요" />

    <Combobox.List>
      {users.map((user) => (
        <Combobox.Item key={user.name} value={user.name}>
          <span className="text-2xl">{user.avatar}</span>
          <span className="font-medium">{user.name}</span>
        </Combobox.Item>
      ))}
    </Combobox.List>
  </Combobox>
);

---

✅ 요약

1. Combobox로 전체를 감싸고 value, setValue를 연결
2. Trigger로 검색 + 열기 기능을 제공
3. List는 선택 가능한 항목들의 영역
4. Item을 클릭하면 setValue로 선택된 값이 전달

---

📺 UI 예시

선택X

선택

클릭 시

• 선택된 값이 있으면 check 아이콘이 보여집니다
• 트리거는 리스트 검색을 위해 Input으로 전환됩니다.

검색결과 O

검색결과 없음

[aahreum]

📘 Input 컴포넌트 사용 방법

Input은 라벨, 입력 필드, 날짜 입력, 우측 버튼, 에러 메시지 등

입력에 필요한 구성 요소를 조합하여 사용할 수 있는 컴파운드 패턴 기반 컴포넌트입니다.

Input은 내부에서 Context를 사용하여

id, value, onChange, disabled, hasError 등을 하위 컴포넌트에 자동으로 전달합니다.

아래의 구성 요소들을 조합하여 다양한 입력 UI를 만들 수 있습니다.

---

🔧 구성 요소 설명

1. <Input />

입력 컴포넌트를 감싸는 가장 바깥 컨테이너입니다.

모든 하위 컴포넌트에 input 상태를 전달합니다.

값(value)과 이벤트(onChange, onBlur)는 Input에서만 관리합니다.

<Input value={text} onChange={setText} error={!!errorMessage}>
  ...
</Input>

---

2. <Input.Label />

인풋 필드를 설명하는 라벨 컴포넌트입니다.

부모 Input에서 넘겨준 ID와 자동으로 연결됩니다.

• required를 설정하면 표시가 붙습니다.

<Input.Label required>이메일</Input.Label>

---

3. <Input.Group />

필드들을 감싸는 컨테이너입니다.

다음과 같은 UI 상태를 관리합니다

• border, padding
• focus-within 스타일링
• 에러 상태(border-error)
• disabled 상태

또한 내부에 <Input.SuffixButton />이 있으면

<Input.Field /> 에 자동으로 padding-right를 추가합니다.

<Input.Group>
  <Input.Field placeholder="이메일을 입력하세요" />
</Input.Group>

---

4. <Input.Field />

일반 input(text, email, password…) 필드입니다.

InputContext로부터 value, onChange, disabled를 자동으로 받아옵니다.

<Input.Field type="email" placeholder="이메일" />

Suffix 버튼이 있으면 자동으로 오른쪽 패딩(pr-[36px])이 추가됩니다.

---

5. <Input.FieldDate />

날짜/시간 입력 전용 필드입니다.

• 캘린더 아이콘 자동 렌더링
• placeholder + formatted value 표시
• 실제 input[type=datetime-local]은 투명 처리하여 클릭 시 기본 달력 UI 표시

<Input.FieldDate placeholder="마감일을 선택하세요" />

---

6. <Input.SuffixButton />

인풋 우측에 들어가는 보조 버튼입니다.

예시) 비밀번호 보기 토글, 검색 지우기 버튼

<Input.SuffixButton ariaLabel="비밀번호 보기" onClick={toggle}>
  <Icons.PasswordShow />
</Input.SuffixButton>

Input.Group 내부에서만 정상적으로 우측에 배치됩니다.

---

7. <Input.PrefixIcon />

인풋 좌측에 들어가는 아이콘 컴포넌트입니다.

예시) 검색 아이콘

<Input.PrefixIcon>
  <Icons.Search />
</Input.PrefixIcon>

Input.Group 내부에서만 정상적으로 좌측에 배치됩니다.

---

8. <Input.ErrorMessage />

에러 메시지 표시 컴포넌트입니다.

메시지가 없으면 렌더링되지 않습니다.

<Input.ErrorMessage>{errors.email}</Input.ErrorMessage>

---

📄 예제 코드

✔ 이메일

<Input value={email} onChange={setEmail} error={!!errors.email}>
  <Input.Label required>이메일</Input.Label>

  <Input.Group>
    <Input.Field placeholder="이메일을 입력하세요" type="email" />
  </Input.Group>

  <Input.ErrorMessage>{errors.email}</Input.ErrorMessage>
</Input>

---

✔ 비밀번호 + suffix 버튼

<Input value={password} onChange={setPassword}>
  <Input.Label required>비밀번호</Input.Label>

  <Input.Group>
    <Input.Fieldtype={isVisible ? 'text' : 'password'}
      placeholder="비밀번호를 입력하세요"
    />
    <Input.SuffixButton ariaLabel="비밀번호 보기" onClick={toggleVisible}>
      {isVisible ? <Icons.PasswordHide /> : <Icons.PasswordShow />}
    </Input.SuffixButton>
  </Input.Group>
</Input>

---

✔ 날짜

<Input value={dueDate} onChange={setDueDate}>
  <Input.Label>마감일</Input.Label>

  <Input.Group>
    <Input.FieldDate placeholder="마감일을 선택해주세요" />
  </Input.Group>
</Input>

✔ 검색

<Input value={search} onChange={setSearch}>
  <Input.Group>
    <Input.PrefixIcon><Icons.Search /></Input.PrefixIcon>
    <Input.FieldDate placeholder="검색" />
  </Input.Group>
</Input>

---

✅ 요약

• Input: 전체 입력 구성 컨테이너
• Label: Input의 id와 연결되어 접근성 개선
• Group: 필드 + 버튼을 감싸고 border/focus/error 상태 담당
• Field: 텍스트 입력
• FieldDate: 날짜 입력 전용
• PrefixIcon: 좌측 아이콘
• SuffixButton: 우측 버튼
• ErrorMessage: 검증 메시지 표시

[jung518]

📘 Title 컴포넌트 사용 가이드

Title 컴포넌트는 Tailwind CSS 기반의 스타일링을 적용한 공통 타이틀 컴포넌트입니다.

• as prop을 통해 원하는 HTML 제목 태그(h2부터 h6까지)를 지정할 수 있습니다.
• size와 weight prop을 사용하여 미리 정의된 텍스트 크기와 글꼴 두께를 적용할 수 있습니다.
• 기본 스타일 이외의 추가 스타일링은 className prop을 통해 적용할 수 있습니다.

import Title from '@/components/Title'; // 예시 경로

// 기본 사용
<Title>기본 타이틀</Title>

// 모든 prop 사용
<Title as="h3" size="2xl" weight="medium" className="text-violet-500">
  커스터마이징된 타이틀
</Title>

🔧 구성 요소 설명

1. as

• 타입: 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
• 렌더링할 HTML 제목 태그를 지정합니다.

2.children

• 타입: React.ReactNode
• 타이틀로 표시될 내용입니다.

3. className

• 타입: string
• Tailwind CSS를 이용한 추가 스타일을 적용합니다.

4. size

• 타입: TitleSize
• 텍스트 크기를 지정합니다.

5. weight

• 타입: TitleWeight
• 글꼴 두께를 지정합니다.

📄 예제코드

import Title from '@/components/Title';

function ExampleComponent() {
  return (
    <div>
      {/* 1. 기본 사용: as="h2", size="2xl", weight="regular", color="text-gray-700" */}
      <Title>
        메인 페이지 제목 (기본)
      </Title>

      {/* 2. 섹션 제목: as="h3", size="xl", weight="semibold" */}
      <Title as="h3" size="xl" weight="semibold" className="mt-6 mb-2">
        섹션 제목입니다
      </Title>

      {/* 3. 리스트 항목 제목: as="h4", size="lg", weight="bold" */}
      <Title as="h4" size="lg" weight="bold">
        📢 알림 제목
      </Title>

      {/* 4. 커스텀 스타일 적용: size="3xl", color="text-red-500", weight="medium" */}
      <Title as="h2" size="3xl" weight="medium" className="text-red-500 hover:text-red-700 transition">
        강조해야 할 매우 큰 타이틀
      </Title>
    </div>
  );
}

export default ExampleComponent;

요약

1. Tailwind 기반의 공통 타이틀 스타일링 제공
2. as prop으로 h2 ~ h6 태그 선택 가능
3. size (크기) 및 weight (두께) Variants 제공
4. text-gray-700, size='2xl', weight='regular'
5. className을 통해 모든 기본 스타일 재정의 및 추가 스타일 적용 가능