# Folio

A long-form reading surface: sidenotes sit in the margin beside their marks and fold into the text on narrow screens, while a contents rail keeps your place.

- Family: Signature, imported from `mizu-ui` or `mizu-ui/signature`
- Docs: https://mizu.user64bit.world/components/folio
- Source: https://github.com/0xuser64bit/mizu/blob/main/packages/mizu/src/signature/Folio.tsx

## Usage

```tsx
import { Folio, Sidenote } from "mizu-ui";

export function Example() {
  return (
    <Folio label="Field notes">
      <h2 id="usage-rivers">Rivers</h2>
      <p>
        Water finds the lowest path through any landscape
        <Sidenote>Unless it freezes first.</Sidenote> and keeps to it until
        something moves it.
      </p>
    </Folio>
  );
}
```

## Copy it with the shadcn CLI

```sh
npx shadcn@latest init 0xuser64bit/mizu/preset # once, where there is no components.json
npx shadcn@latest add 0xuser64bit/mizu/folio
```

## Props

- `label / children`: `string / ReactNode`. The article's name and its prose: paragraphs, h2 and h3 headings, blockquotes, with Sidenotes inside the text.
- `contents`: `boolean` (default `true`). A contents rail from the headings that have an id, shown from 1040px wide.
- `Sidenote children`: `ReactNode`. The note: phrasing content, numbered automatically in reading order.
- `--mizu-folio-offset / --mizu-folio-note`: `CSS length`. Clearance for a sticky header (24px) and the margin note width (232px).

## Keyboard

- Tab: Move between note marks and contents
- Enter Space: Unfold a note, or point to it in the margin

## Accessibility

Folio is a labelled article; its contents rail is a named navigation whose current section is marked with aria-current, and choosing one moves focus to that heading. Each mark is a button named with its number; on narrow screens it reports whether its note is expanded. Notes keep their place in the reading order right after their mark, with the note role.

## Motion

Notes that would collide step down beside each other and glide when the text reflows; on narrow screens a note unfolds beneath its line. The contents marker springs to the section in view, the progress line fills as you read, and choosing a mark whose note is already in the margin makes the note glow. Reduced motion keeps the layout and drops the travel.