useSurface

기존 DOM 요소를 조명에 연결할 ref를 반환합니다.

useSurface(options?)

기존 HTML 요소를 가장 가까운 Edge.Provider에 연결하는 콜백 ref를 반환합니다. 테두리가 표시되는 요소에 ref를 연결하세요. 기존 className과 style은 그대로 사용할 수 있습니다.

useSurface 시그니처

const ref = useSurface<HTMLElement>(options);

기존 컴포넌트에서 조명 공유하기

function Area() {
  return <Edge.Provider><ExistingCard /><ExistingCard /></Edge.Provider>;
}

function ExistingCard() {
  const ref = useSurface<HTMLDivElement>();
  return <Card ref={ref}>Your existing component</Card>;
}

React 18의 함수 컴포넌트는 forwardRef를 사용해 ref를 HTML 요소로 전달해야 합니다. React 19에서는 ref를 prop으로 받을 수도 있습니다.

조명을 직접 지정하지 않으면 Edge.Provider가 필요합니다. 조명을 직접 관리할 때는 useLight가 반환한 핸들을 useSurface(light, options)에 전달하세요. 직접 지정한 조명이 Edge.Provider의 조명보다 우선합니다.

useSurface options
Prop / 옵션	타입	기본값	설명
`pseudoElement`	`'after' \| 'before'`	`'after'`	하이라이트를 그릴 가상 요소입니다. 기존 ::after를 유지하려면 before를 선택하세요. 두 가상 요소를 모두 사용 중이거나 input 요소라면 바깥에 래퍼를 두세요. 잘못된 값은 RangeError를 발생시킵니다.
`edgeStyle`	`'raised' \| 'recessed' \| 'matte'`	`'raised'`	테두리가 조명에 반응하는 방식입니다. 어떤 값을 선택해도 컴포넌트의 기존 스타일은 유지됩니다.
`color`	`string`	`currentColor`	하이라이트 색상입니다. 기본값은 연결된 DOM 요소의 글자색입니다. CSS 변수를 포함한 모든 CSS 색상 문자열을 사용할 수 있습니다.
`shadowColor`	`string`	`#0008`	조명 반대쪽 테두리의 색상입니다. CSS 색상 문자열을 사용할 수 있습니다. 밝은 서피스에서 이 그림자를 없애려면 transparent를 지정하세요.
`borderWidth`	`number`	`1`	하이라이트의 두께를 픽셀 단위로 지정합니다. 실제 DOM 요소의 테두리는 바꾸지 않습니다. 음수는 0으로 제한하고, 유한하지 않은 값에는 기본값을 사용합니다.
`intensity`	`number`	`1`	공유 조명의 강도에 곱할 값입니다. 유한한 값은 0~1로 제한하고, 유한하지 않은 값에는 기본값을 사용합니다.

DOM 요소 하나에는 조명 하나만 연결할 수 있습니다. 크기가 다른 부모 요소에 ref를 연결하지 마세요.

옵션이 바뀌어도 요소는 교체되지 않습니다. 훅으로 연결한 하이라이트는 하이드레이션 이후에 적용됩니다. 서버 HTML에도 관련 클래스와 CSS 변수를 포함하려면 Edge.Surface를 사용하세요.