ChannelButton

채널(메일 등) 발송 팝업을 트리거하는 전용 버튼 컴포넌트

개요

Cals ChannelButton은 Foundation Button을 래핑하여 채널 발송(메일 등) 시나리오에 특화된 컴포넌트입니다.

주요 특징

• ✅ title/children: 선언적 버튼 콘텐츠 구성 (children 사용 시 title 대신 적용)
• ✅ 채널 유형: channelType prop으로 채널 유형 설정 (기본값 “mail”)
• ✅ 동적 색상 파생: backgroundColor만 지정하면 hover/active/disabled 색상 자동 계산
• ✅ 조건부 토큰 오버라이드: 해당 prop이 있을 때만 토큰 오버라이드 (기본값 보존)
• ✅ 가시성 제어: visible prop으로 선언적 표시/숨김
• ✅ 포커스 제어: ref.focus()/blur()/element로 프로그래밍 제어
• ✅ 비즈니스 로직 분리: 메일 팝업/템플릿/데이터 매핑은 프로젝트팀이 onClick에서 구현

기본 사용

title prop으로 버튼 텍스트를 지정합니다.

<ChannelButton title="메일 발송" />
<ChannelButton title="발송 취소" variant="secondary" />

children 사용

children을 지정하면 title 대신 직접 버튼 내용을 구성할 수 있습니다.

<ChannelButton>
  <span className="font-bold">커스텀</span> 발송 버튼
</ChannelButton>

채널 유형 설정

channelType prop으로 채널 유형을 설정합니다. 컴포넌트 내부에서는 사용하지 않으며, 프로젝트팀이 onClick 핸들러에서 참조합니다.

<ChannelButton
  title="메일 발송"
  channelType="mail"
  onClick={() => openMailPopup(channelType)}
/>

커스텀 색상 (backgroundColor)

backgroundColor prop을 지정하면 Foundation 토큰(--button-background-default-*)을 오버라이드하여 hover/active/disabled 색상을 자동 파생합니다.

• hover: 원본 색상에서 -20 어두워짐
• active: 원본 색상에서 -35 어두워짐
• disabled: 원본 색상에서 +60 밝아짐

<ChannelButton title="빨강" backgroundColor="#e8553d" />
<ChannelButton title="보라" backgroundColor="#7c3aed" />
<ChannelButton title="초록" backgroundColor="#16a34a" />
<ChannelButton title="회색" backgroundColor="#6b7280" color="#fff" />

커스텀 색상 + disabled

<ChannelButton title="빨강 비활성" backgroundColor="#e8553d" disabled />
<ChannelButton title="보라 비활성" backgroundColor="#7c3aed" disabled />
<ChannelButton title="초록 비활성" backgroundColor="#16a34a" disabled />

⚠️ 토큰 오버라이드 규칙: 해당 prop이 없으면 토큰을 오버라이드하지 않습니다. 예를 들어 backgroundColor만 지정하면 foreground 토큰은 기본값(variant 설정)을 유지합니다.

폰트 커스터마이징

fontSize, fontWeight, fontFamily, fontStyle prop으로 폰트를 개별 지정합니다.

<ChannelButton title="큰 글씨" fontSize="18px" />
<ChannelButton title="가는 글씨" fontWeight="300" />
<ChannelButton title="Bold" fontWeight="800" backgroundColor="#16a34a" />
<ChannelButton title="기울임" fontStyle="italic" variant="secondary" />

로딩 상태

loading prop이 true이면 Spinner가 표시되고 클릭이 차단됩니다. 메일 발송 팝업을 여는 동안 사용합니다.

<ChannelButton title="발송 중" loading />
<ChannelButton title="발송 중" loading variant="secondary" />

가시성 제어 (visible)

visible prop으로 선언적으로 표시/숨김을 제어합니다.

<ChannelButton title="보이는 버튼" visible={true} />
<ChannelButton title="숨겨진 버튼" visible={false} />

포커스 제어 (ref)

ref를 통해 focus()/blur()/element에 접근합니다.

import { useRef } from "react"
import { ChannelButton, type ChannelButtonRef } from "@vortex/ui-cals"
 
function Example() {
  const buttonRef = useRef<ChannelButtonRef>(null)
 
  return (
    <>
      <ChannelButton
        title="포커스 이동"
        variant="outline"
        onClick={() => buttonRef.current?.focus()}
      />
      <ChannelButton ref={buttonRef} title="포커스 대상" />
    </>
  )
}

API Reference

Props

Events

Ref (ChannelButtonRef)

기본 사용법

import { ChannelButton } from "@vortex/ui-cals"
 
// 기본
<ChannelButton title="메일 발송" />
 
// 커스텀 색상
<ChannelButton title="발송" backgroundColor="#16a34a" />
 
// 채널 유형 + onClick
<ChannelButton
  title="메일 발송"
  channelType="mail"
  onClick={() => openMailPopup()}
/>

색상 파생 로직

접근성

권장 사항

• ✅ 의미 있는 title 텍스트 사용
• ✅ disabled 상태에서 시각적 피드백 (색상 밝아짐)
• ✅ 네이티브 button 엘리먼트 사용으로 키보드 접근성 보장
• ❌ backgroundColor만으로 의미 전달 지양 (색맹 고려)

Button과의 차이

관련 컴포넌트

• Button: 범용 버튼 (ChannelButton의 상위 호환)
• Foundation Button: 기본 Button (ChannelButton의 베이스)