# React · useSurface

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

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/ko/docs/react/use-surface/

<a id="use-surface"></a>

## useSurface(options?)

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

```tsx
const ref = useSurface<HTMLElement>(options);
```

```tsx
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의 조명보다 우선합니다.

| 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`를 사용하세요.