import { Meta, Canvas } from '@storybook/addon-docs/blocks'
import * as ReferenceMenuStories from './ReferenceMenu.stories'

<Meta of={ReferenceMenuStories} />

# ReferenceMenu

What a link in a document offers whoever is writing it: **Open**, and — when
it is alone on its line — **Show as** Row or Card. Card puts its card in the
row's place; Row puts the row back. A link in a sentence, and a person or a
Folder alone on its line (which stay chips), offer Open only.

<Canvas of={ReferenceMenuStories.InAnEditor} />

## When

- **An editor of a document**: pair it with **ReferenceNode**, which draws the
  link, and **LinkPlaces**, which tells it where it sits. With **LinkChips**, a
  pasted URL that becomes its chip opens the menu too. **DocumentEditor** has
  all of them.

## When not

- A document that is only read → **RichText**: a click on a link follows it.
- A message's box, where every link is a chip and its card goes under the
  message → **CardUnder**; leave this out, and a click on a chip follows it.

## How

```tsx
import { EditorContent, useEditor } from '@tiptap/react'
import { LinkPlaces, ReferenceMenu, ReferenceMenuView, ReferenceNode, isReferenceMenuOpen } from '@estiva-app/ui/editor'

const editor = useEditor({
  extensions: [/* … */ ReferenceNode.configure({ view: Chip }), LinkPlaces, ReferenceMenu],
  editorProps: {
    handleKeyDown: (view, event) => {
      // While the menu is open, Escape is its own: it closes the menu.
      if (event.key === 'Escape' && isReferenceMenuOpen(view.state)) return false
      // …
    },
  },
})

<EditorContent editor={editor} />
<ReferenceMenuView editor={editor} />
```

- **A click on a link while editing** — its chip, row or card — opens the menu
  under it, instead of following it. Not editing, the click follows it. A
  card's own controls (its status, its owner) take their click while editing
  too.
- **A link just put in alone on its line** — pasted, picked with `[`, or a
  pasted URL becoming its chip — opens the menu by itself. It takes no focus:
  typing on closes it, and nothing is written. In a sentence it does not open:
  Open would be all it offers.
- **What it writes:** Card writes `embed` `detailed`; Row removes `embed`.
  Nothing writes `compact`; an older writer's is kept until Row or Card is
  chosen, and draws, and reads in the menu, as Row.
- **Open** does what a click on the link does when reading: the app's link gets
  the click. A link with nothing to click opens its URL in a new tab.
- Open is offered only when there is something to open: the link's own
  control, or its URL. A link in a sentence with neither has no menu, and a
  click goes on to it.
- The menu closes when the editor loses focus, so a card is never chosen after
  the editor has saved on leaving.
- Choosing Row or Card is an undo step; the menu closes.

## What it owns

Nothing. Its box is the Popover; it holds which link the menu is open on, and its keys.

## Keys

| Key | Does |
| --- | --- |
| Enter, on a selected link | Opens the menu, its first row highlighted |
| ↓ / ↑ | Moves through the rows; nothing is highlighted until then |
| Enter | Chooses the highlighted row; with none, the editor's own Enter |
| Escape | Closes the menu |

The panel takes no focus, so it is reached only through these keys. A key with
Shift, Ctrl, Alt or Cmd stays the editor's: Shift+↓ extends the selection.