ColorPicker

눈으로 고르는 색입니다. 채도 사각형과 그 옆의 색상 레일, 선택적인 불투명도 레일, 값을 직접 입력하는 필드, 그리고 미리 준비된 스와치 묶음으로 이루어져 있습니다. hex와 rgb(), hsl()을 읽고 쓰며, 번들에 의존성을 더하지 않습니다.

import { ColorPicker } from 'neba';

const [color, setColor] = useState('#1a58d1');

<ColorPicker value={color} onValueChange={setColor} />;

Props

Prop	타입	기본값	설명
value	string	—	CSS 색상 문자열. 직접 제어할 때 씁니다
defaultValue	string	'#1a58d1'	제어하지 않을 때의 시작 색
onValueChange	(value: string) => void	—	format이 정한 표기로 새 색을 전달합니다
format	'hex' | 'rgb' | 'hsl'	'hex'	값을 내보낼 때의 표기법
alpha	boolean	false	불투명도 레일을 추가하고 값에 네 번째 채널을 싣습니다
swatches	readonly string[] | false	—	패널 아래의 기본 색들. false면 그리지 않고, 배열이면 내장 세트를 대체합니다
inline	boolean	false	팝업 대신 페이지에 패널을 직접 그립니다. 트리거는 없습니다
editable	boolean	true	패널 아래에 값을 직접 입력할 수 있는 필드
clearable	boolean	false	값을 비우는 ×를 답니다
open	boolean	—	팝업이 열려 있는지. onOpenChange와 함께 제어 컴포넌트로 씁니다
defaultOpen	boolean	false	처음에 열린 채로 시작
onOpenChange	(open: boolean) => void	—	열리거나 닫힐 때
locale	string	'en'	접근성 이름들의 언어. BCP 47 태그(ko, pt-BR, zh-Hant). 모르는 태그는 영어로 돌아갑니다
labels	Partial<ColorPickerLabels>	—	그 이름들을 하나씩 덮어씁니다. 색 사각형, 두 레일, 입력란, 스와치 묶음, 글자가 없는 부분들의 이름입니다
name	string	—	폼과 함께 전송될 이름
fullWidth	boolean	false	컨테이너 너비만큼 확장
label	ReactNode	—	컨트롤과 연결되는 라벨. Base UI Field가 묶어 줍니다
description	ReactNode	—	보조 설명
error	ReactNode	—	오류 메시지. 값이 있으면 invalid 상태도 함께 켜지고 색 계열이 danger로 넘어갑니다
invalid	boolean	!!error	메시지 없이 invalid만 켭니다. 외부 폼 라이브러리가 유효성을 가질 때
readOnly	boolean	false	값은 보이지만 바꿀 수 없음. 색과 가장자리는 유지한 채 채도만 빠집니다
disabled	boolean	false	사용 불가. 색 계열을 버리고 중립 회색이 됩니다
variant공통	'solid' | 'outline' | 'text'	'outline'	표면의 무게. 채움 / 하이라인 / 없음
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	트리거의 높이, 그리고 패널과 그 안 사각형의 크기
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	테두리와 focus ring의 색 역할입니다. 고르는 색과는 무관합니다
density공통	'default' | 'compact'	'default'	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 0은 그림자 없음
required	boolean	—	폼을 제출하기 전에 값이 있어야 하는지

나머지 <div> 속성은 모두 루트로 전달됩니다. 예외는 onChange 하나로, 여기서 들을 만한 변화는 onValueChange입니다.

공통 축(variant size color density elevation)의 의미는 Prop 규약에 있습니다. 다만 color는 컨트롤 자신의 테두리와 focus ring의 색 역할이며, 고르는 색과는 아무 관계가 없습니다.

예시

inline

기본값은 트리거에 매달린 popup 안에 패널을 두는 것이고, 폼에서는 그쪽이 맞습니다. inline은 트리거 없이 패널을 페이지에 그대로 그립니다. 설정 화면이나 toolbar처럼 picker가 화면의 한 필드가 아니라 화면 그 자체일 때 씁니다.

import { ColorPicker } from 'neba';

export default function ColorPickerInline() {
  return <ColorPicker inline defaultValue="#22c55e" />;
}

format

format은 값이 나올 때의 표기를 정합니다. hex(기본값), rgb, hsl 중 하나입니다. 내보내는 쪽에만 영향을 주므로, 세 표기 중 무엇으로 value를 넘겨도 format과 관계없이 올바르게 읽힙니다.

import { useState } from 'react';
import { ColorPicker, Segment, SegmentedButton, Typography } from 'neba';

const FORMATS = ['hex', 'rgb', 'hsl'] as const;

export default function ColorPickerFormat() {
  const [format, setFormat] = useState<(typeof FORMATS)[number]>('hex');
  const [color, setColor] = useState('#f97316');

  return (
    <div className="flex flex-col items-center gap-3">
      <SegmentedButton
        value={format}
        onValueChange={(next) => setFormat(next as (typeof FORMATS)[number])}
        size="sm"
      >
        {FORMATS.map((name) => (
          <Segment key={name} value={name}>
            {name}
          </Segment>
        ))}
      </SegmentedButton>

      <ColorPicker format={format} value={color} onValueChange={setColor} />

      <Typography level="caption">{color}</Typography>
    </div>
  );
}

alpha

alpha는 색상 레일 아래에 불투명도 레일을 더하고, 값이 네 번째 채널을 싣게 합니다. #rrggbbaa, rgba(), hsla()입니다. 켜지 않으면 값은 언제나 불투명하므로, 불투명도를 요청한 적 없는 쪽에서 네 번째 인자를 보게 되는 일이 없습니다.

import { useState } from 'react';
import { ColorPicker, Typography } from 'neba';

export default function ColorPickerAlpha() {
  const [color, setColor] = useState('rgba(217, 70, 239, 0.65)');

  return (
    <div className="flex flex-col items-center gap-3">
      <ColorPicker alpha format="rgb" value={color} onValueChange={setColor} />
      <Typography level="caption">{color}</Typography>
    </div>
  );
}

swatches

swatches는 CSS 색상 문자열의 배열을 받아 내장 세트를 대체합니다. 제품이 실제로 쓰는 몇 가지 색을 놓아 두는 자리입니다. swatches={false}면 아무것도 그리지 않고, editable={false}는 입력 필드를 없앱니다. 둘을 함께 쓰면 패널에는 사각형과 레일만 남습니다.

import { ColorPicker } from 'neba';

/* The colours a product actually uses, one press away. */
const BRAND = ['#0f172a', '#1a58d1', '#0891b2', '#16a34a', '#ca8a04', '#dc2626'];

export default function ColorPickerSwatches() {
  return (
    <div className="flex flex-wrap items-start justify-center gap-6">
      <ColorPicker inline size="sm" swatches={BRAND} defaultValue="#1a58d1" editable={false} />
      <ColorPicker inline size="sm" swatches={false} defaultValue="#dc2626" />
    </div>
  );
}

폼 안에서

label, description, error는 라이브러리의 모든 필드가 갖는 그 세 슬롯이고, name은 값을 폼과 함께 전송합니다. clearable은 값을 비우는 ×를 답니다. 비운 뒤의 값은 빈 문자열입니다.

import { ColorPicker } from 'neba';

export default function ColorPickerField() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      <ColorPicker
        label="Label colour"
        description="Shown on the project card and in the calendar."
        name="labelColour"
        clearable
        fullWidth
        defaultValue="#8b5cf6"
      />

      <ColorPicker
        label="Brand colour"
        error="This colour fails contrast against white."
        defaultValue="#fef08a"
        fullWidth
      />
    </div>
  );
}

size

size는 공통 사다리 위에서 트리거의 높이를 정하고, 패널의 너비도 함께 정합니다. 어느 단계에서든 옆의 필드들과 같은 줄에 놓입니다.

import { ColorPicker } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function ColorPickerSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {SIZES.map((size) => (
        <ColorPicker key={size} size={size} defaultValue="#06b6d4" />
      ))}
    </div>
  );
}

제어하기

value를 넘기면 picker는 자체 상태를 갖지 않습니다. open과 onOpenChange가 popup에 대해 같은 일을 합니다.

const [color, setColor] = useState('#1a58d1');

<ColorPicker value={color} onValueChange={setColor} />;

읽고 쓰는 색 표기

네 가지 길이의 hex(#abc, #abcd, #aabbcc, #aabbccdd), 그리고 rgb()/rgba()와 hsl()/hsla()를 쉼표 문법과 공백 문법 모두로 읽습니다. 이름 있는 색과 color()는 읽지 않습니다. picker는 읽을 수 있는 값을 모두 되돌려 쓸 수 있어야 하는데, 패널 위에 rebeccapurple을 뜻하는 지점은 없기 때문입니다. 읽지 못한 문자열은 패널을 그대로 둡니다.

접근성

• 사각형과 각 레일은 접근 가능한 이름과 값, 방향키 지원을 갖춘 role="slider"입니다. 방향키는 한 단계씩, shift와 함께 누르면 열 단계씩 움직입니다.
• 사각형은 두 축을 aria-valuetext로 알립니다. aria-valuenow 하나로는 2차원의 한 점을 설명할 수 없기 때문입니다.
• 모든 스와치는 자기 색으로 이름 붙은 진짜 버튼이고, 선택된 것은 aria-pressed를 갖습니다. 그 위의 체크 표시는 해당 색 위에서 읽히는 쪽을 골라 검정이나 흰색으로 그려집니다.
• 사각형과 레일, 필드의 이름이 페이지의 언어로 읽히도록 locale을 지정하거나, labels로 직접 쓰세요.
• disabled와 readOnly는 둘 다 패널을 tab 순서에서 빼고 포인터와 키보드에 반응하지 않게 합니다.