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 を選びます。両方が使用済み、またはネイティブ入力の場合はラッパーを使います。不正な値は RangeError を発生させます。
`edgeStyle`	`'raised' \| 'recessed' \| 'matte'`	`'raised'`	境界が光に反応する方法です。3 つのスタイルはいずれもコンポーネントの外観を維持します。
`color`	`string`	`currentColor`	ハイライトの色です。デフォルトでは DOM 要素の文字色に従います。CSS 変数を含む任意の CSS 色文字列を指定できます。
`shadowColor`	`string`	`#0008`	反対側の境界の色です。任意の CSS 色文字列を指定できます。明るいサーフェスの影を消すには transparent を使います。
`borderWidth`	`number`	`1`	装飾の太さをピクセルで指定します。 DOM 要素の境界線は変えません。負数は 0 に制限され、有限でない値はデフォルト値になります。
`intensity`	`number`	`1`	共有するライトの強度に掛ける値です。有限値は 0〜1 に制限され、有限でない値はデフォルト値になります。

1 つの DOM 要素に接続できるライトは 1 つだけです。サイズが異なる親要素に ref を渡さないでください。

オプションを更新しても要素は置き換わりません。フックで接続したハイライトはハイドレーション後に適用されます。サーバー HTML にもクラスと CSS 変数を含めるには、Edge.Surface を使います。