HoverCard

포인터가 어떤 대상 위에 머무를 때 열려, 그 너머에 있는 것을 미리 보여주는 카드입니다. 멘션 뒤의 사람, 링크 뒤의 저장소, id 뒤의 배포.

import { HoverCard, TextLink } from 'neba';

<HoverCard trigger={<TextLink href="/people/nadiarowan">@nadiarowan</TextLink>} title="Nadia Rowan">
  Maintainer · 214 commits
</HoverCard>;

Props

Prop	타입	기본값	설명
trigger *	ReactElement	—	카드가 매달리는 요소. ref를 받고 props를 펼치는 요소 하나여야 하며, 카드는 감싸지 않고 그 요소에 병합됩니다
title	ReactNode	—	카드의 제목
description	ReactNode	—	제목 아래 한 줄
children	ReactNode	—	카드의 본문
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	타입 스케일과 여백, 그리고 카드가 넓어질 수 있는 한계까지 함께 정합니다
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 시트는 물들지 않으므로 가장자리에만 나타납니다
density공통	'default' | 'compact'	'default'	카드 안쪽 여백만 바꿉니다
side공통	'top' | 'right' | 'bottom' | 'left'	'bottom'	카드가 나타나는 trigger의 모서리. 공간이 없으면 반대편으로 뒤집힙니다
align공통	'start' | 'center' | 'end'	'center'	그 모서리 위에서의 위치
sideOffset	number	6	trigger와의 거리 (px)
alignOffset	number	0	그 모서리를 따라 미는 양 (px)
arrow	boolean	false	trigger를 가리키는 꼭지를 그립니다. 반투명한 표면의 꼭지는 흐려진 배경을 함께 가져갈 수 없어 기본은 꺼짐입니다
open	boolean	—	열림 여부. onOpenChange와 함께 쓰면 controlled 컴포넌트가 됩니다
defaultOpen	boolean	—	열린 채로 시작할지 여부 (uncontrolled)
onOpenChange	(open: boolean) => void	—	열리고 닫힐 때마다 호출됩니다
delay	number	—	카드가 열리기까지 포인터가 머물러야 하는 시간 (ms)
closeDelay	number	—	포인터가 떠난 뒤 카드가 남아 있는 시간 (ms). trigger와 카드 사이의 빈틈을 건널 수 있게 합니다
width	number | string	—	size가 정한 최대 너비를 덮어씁니다. 숫자는 px입니다

<div>의 기본 속성은 popup으로 전달됩니다. 컴포넌트가 직접 소유하는 color, title, children만 예외입니다. Popover와 같은 이유로 variant도 elevation도 없습니다. hover를 거쳐야 나타나는 표면은 이미 자기 존재를 주장한 것이고, 페이지 위에 떠 있는 카드를 평평하게 눕힐 수는 없습니다.

이 컴포넌트는 라이브러리의 다른 두 popup 사이에 있습니다. Tooltip은 한 줄짜리 라벨이고 포인터가 그 안까지 닿지 않습니다. Popover는 누름으로써 요청된 패널이라 폼도 담을 수 있습니다. HoverCard는 tooltip처럼 요청되지 않았고 popover처럼 닿을 수 있습니다. 포인터가 안으로 들어올 수 있고, 안에 있는 링크를 따라갈 수 있습니다.

예시

trigger

trigger는 children이 아니라 요소이며, 카드는 그 요소에 병합됩니다. 감싸는 요소가 없으므로 레이아웃은 그대로이고 링크는 링크로 남습니다. 보통 TextLink나 Avatar입니다.

delay · closeDelay

delay는 카드가 열리기까지 포인터가 머물러야 하는 시간이고, closeDelay는 포인터가 떠난 뒤 카드가 남아 있는 시간입니다. 후자가 trigger와 카드 사이의 빈틈을 건널 수 있게 만듭니다.

import { HoverCard, TextLink, Typography } from 'neba';

export default function HoverCardDelay() {
  return (
    <div className="flex flex-col items-center gap-4">
      <Typography level="body">
        <HoverCard
          delay={0}
          trigger={<TextLink href="#now">Opens at once</TextLink>}
          title="delay 0"
        >
          The card is up on the first frame the pointer is over the link.
        </HoverCard>
      </Typography>
      <Typography level="body">
        <HoverCard
          delay={700}
          closeDelay={400}
          trigger={<TextLink href="#later">Waits 700ms</TextLink>}
          title="delay 700"
        >
          Long enough that crossing a paragraph of links opens none of them.
        </HoverCard>
      </Typography>
    </div>
  );
}

side · align · arrow

side는 카드가 나타나는 trigger의 모서리이고 공간이 없으면 반대편으로 뒤집힙니다. align은 그 모서리 위에서의 위치입니다. arrow는 꼭지를 그리며, 반투명한 표면의 꼭지는 흐려진 배경을 함께 가져갈 수 없기 때문에 기본값은 꺼짐입니다.

import { HoverCard, Button } from 'neba';

const sides = ['top', 'right', 'bottom', 'left'] as const;

export default function HoverCardPlacement() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {sides.map((side) => (
        <HoverCard
          key={side}
          side={side}
          arrow
          size="sm"
          trigger={
            <Button size="sm" variant="outline">
              {side}
            </Button>
          }
          title="Deploy 4f21c8"
        >
          Built in 42s, shipped to production.
        </HoverCard>
      ))}
    </div>
  );
}

size

size는 타입 스케일과 안쪽 여백, 그리고 카드가 넓어질 수 있는 한계를 정합니다. width는 마지막 항목만 따로 덮어씁니다.

import { Button, HoverCard } from 'neba';

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

export default function HoverCardSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {sizes.map((size) => (
        <HoverCard
          key={size}
          size={size}
          trigger={
            <Button size={size} variant="outline">
              {size}
            </Button>
          }
          title="Frankfurt"
          description="eu-central-1"
        >
          Four instances, all healthy.
        </HoverCard>
      ))}
    </div>
  );
}

접근성

• 카드 안의 내용은 trigger가 향하는 페이지에도 반드시 존재해야 합니다. hover가 없는 키보드, 포인터가 없는 터치스크린, 스크린 리더는 모두 그 경로로 도달하므로 이 카드가 유일한 통로가 되어서는 안 됩니다.
• 포인터로 카드 안까지 들어갈 수 있어 안의 링크를 따라갈 수 있고, 포인터가 안에 있는 동안에는 열린 채로 유지됩니다.
• Escape로 닫힙니다.