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

<Meta of={EditorBlockHandleStories} />

# EditorBlockHandle

`BlockHandle` in a Tiptap editor: drag the handle to move the block, press it
for Turn into, Duplicate and Delete, then the app's rows.

<Canvas of={EditorBlockHandleStories.Default} />

## When

- **An editor of a block document** (SPEC §13.3) that someone reorganises —
  with `BlockNodes`' `BlockId` in its extensions, so every block has an id.
- **Not editable**: the same handle reads — no drag, the app's rows only.

## When not

- The document being read, with no editor → **BlockHandle**, from the main
  entry, which loads no Tiptap.
- Formatting a few words inside a block → **SelectionToolbar**. This acts on
  whole blocks.

## How

```tsx
import { EditorContent, useEditor } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { BlockId, Callout, Checklist, EditorBlockHandle } from '@estiva-app/ui/editor'
import { MenuItem, type HandleBlock } from '@estiva-app/ui'

const rows = (block: HandleBlock) => <MenuItem label="Copy link" onClick={() => navigator.clipboard.writeText(`#${block.id}`)} />

const editor = useEditor({ extensions: [StarterKit, BlockId, Checklist, Callout] })

<EditorBlockHandle editor={editor} actions={rows}>
  <EditorContent editor={editor} />
</EditorBlockHandle>
```

- **Turn into is the same in every app** (`turnIntoRows`): a block of text gets the `/` menu's formats, code as a block, and
  Checklist, Note and Warning; a list gets Bulleted list, Numbered list,
  Checklist and Text; a quote gets Quote, Note, Warning and Text. Checklist
  and the callouts appear only where the editor has `Checklist` and `Callout`.
- **A list or a quote turns whole**, and keeps its id and every item's, so a
  comment anchored to it stays: Checklist keeps the ticks there are, Bulleted
  and Numbered drop them, Text makes each item a paragraph under the item's
  id. `turnListInto` and `turnQuoteInto` are those rows' actions.
- `turnInto` takes other rows: a function of the block, or a list offered for
  a block of text only, its `run` getting the editor with the caret already in
  the block. `[]` offers none.
- **Every row leaves the editor focused**, as a drop does: Turn into in the
  block, Duplicate in the copy, Delete where the block was. An editor that
  saves when the person leaves it saves these the same way.
- `duplicateBlock`, `deleteBlock` and `startBlockDrag` are the rows' own
  actions, for a caller that offers them elsewhere (a shortcut, a test).

<Canvas of={EditorBlockHandleStories.NotEditable} />

## What it owns

It does these by itself. Write none of them around it.

| It does | So you never write | Refused when written by hand |
|---|---|---|
| Moves the block through ProseMirror's own drop, so it arrives with its id and its anchored comments still find it | a drop handler, or a delete and an insert | |
| Duplicates a block under a fresh id, the original keeping its own (`BlockId` decides) | an id for the copy | |
| Puts the caret in the block before a Turn into row runs | a selection before your `run` | |