Anchor

지금 읽고 있는 페이지의 제목 목록이고, 독자가 있는 위치가 표시됩니다. 진짜 fragment 링크라서 추적이 동작하든 말든 해당 제목으로 이동합니다.

import { Anchor } from 'neba';

<Anchor
  items={[
    { href: '#install', label: 'Install' },
    { href: '#setup', label: 'Setup', depth: 1 }
  ]}
/>;

Props

Prop	타입	기본값	설명
items *	readonly AnchorItem[]	—	제목들. 페이지에 나타나는 순서대로
activeHref	string | null	—	표시할 행의 href. 주면 스크롤 추적을 멈추고 지시받은 대로 표시합니다
onActiveChange	(href: string | null) => void	—	독자가 있는 행이 바뀔 때마다 호출됩니다
offset	number	0	scrollport 상단에서 얼마나 내려온 지점을 제목에 도달한 것으로 볼지 (px). sticky header의 높이를 넣으세요
container	RefObject<HTMLElement | null>	—	문서가 아닌 다른 것이 스크롤될 때 그 요소
rail	boolean	true	앞쪽 가장자리를 따라 선을 그리고 현재 행에 불을 켭니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	행의 타입 스케일과 들여쓰기 폭
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	현재 행과 레일이 띠는 색 역할
density공통	'default' | 'compact'	'default'	행의 세로 여백만 바꿉니다
locale	string	—	BCP 47 태그. nav의 이름을 이 언어로 씁니다. 지원하지 않는 태그는 영어로
label	string	—	nav의 접근성 이름. 기본값은 locale의 표현입니다

<nav>의 모든 속성이 color와 children을 제외하고 그대로 전달됩니다.

AnchorItem

Prop	타입	기본값	설명
href *	string	—	가리키는 fragment, #getting-started. 여기 적힌 id를 목록이 지켜봅니다
label *	ReactNode	—	행에 쓰이는 말
depth	number	0	제목의 깊이. 들여쓰기에만 쓰이며 목록 자체는 평평합니다

제목은 문서에서 긁어오는 대신 직접 전달합니다. 이 목록을 만들어내는 쪽(MDX 파이프라인, CMS, 라우트의 frontmatter)은 이미 id를 알고 있고, 컴포넌트가 직접 찾아 나선다면 어느 제목이 본문이고 어느 것이 chrome인지 추측해야 합니다.

예시

activeHref와 onActiveChange

그냥 두면 목록이 스크롤을 추적합니다. 표시되는 행은 상단선을 지나간 마지막 제목이며, 이 규칙은 아래로 내려갈 때만큼 위로 올라갈 때도 올바르게 읽힙니다. 스크롤이 맨 아래에 닿으면 마지막 제목이 표시됩니다. activeHref를 주면 추적을 멈추고 지시받은 대로 표시합니다.

첫 제목에 닿기 전, 즉 독자가 아직 그 위에 있는 동안에는 아무것도 표시되지 않습니다.

offset

scrollport 상단에서 얼마나 내려온 지점을 "제목에 도달했다"고 볼지 정합니다. sticky header의 높이를 넣으세요. 그러지 않으면 바에 가려진 제목이 표시되는 일이 없습니다.

container

문서가 아닌 다른 것이 스크롤될 때 그 요소입니다. 예를 들어 scroll="content"인 PageLayout이 페이지를 담는 요소입니다.

rail

앞쪽 가장자리를 따라 내려가는 선이고, 현재 행에 불이 들어옵니다. 이동하는 마커가 아니라 행의 border입니다. 이미 움직이고 있는 독자 아래에서 무언가가 미끄러지지 않게 하기 위해서입니다.

import { Anchor } from 'neba';

const ITEMS = [
  { href: '#anchor-a', label: 'Overview' },
  { href: '#anchor-b', label: 'Installation' },
  { href: '#anchor-c', label: 'Configuration', depth: 1 },
  { href: '#anchor-d', label: 'Deployment' }
];

export default function AnchorRail() {
  return (
    <div className="flex items-start gap-10">
      <Anchor size="sm" items={ITEMS} activeHref="#anchor-b" label="With rail" />
      <Anchor size="sm" rail={false} items={ITEMS} activeHref="#anchor-b" label="Without rail" />
    </div>
  );
}

size

import { Anchor } from 'neba';

const ITEMS = [
  { href: '#size-a', label: 'Overview' },
  { href: '#size-b', label: 'Installation' },
  { href: '#size-c', label: 'Deployment' }
];

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

export default function AnchorSizes() {
  return (
    <div className="flex items-start gap-8">
      {sizes.map((size) => (
        <Anchor key={size} size={size} items={ITEMS} activeHref="#size-b" label={size} />
      ))}
    </div>
  );
}

접근성

• 진짜 <a href="#…">로 이루어진 진짜 <nav>입니다. JavaScript가 꺼져 있어도 동작하고, 스크린 리더가 불러오는 링크 목록에 들어갑니다. 추적은 그 위에 얹힌 것이지 없으면 안 되는 부분이 아닙니다.
• 표시된 행에는 aria-current="location"이 붙습니다. 링크 묶음 안에서 독자가 있는 위치를 뜻하는 값입니다.
• <nav>의 이름은 locale이나 label에서 옵니다.
• id가 없는 제목은 추적할 수 없고, 그 행은 아무 데도 가지 않는 링크가 됩니다.