// lib/editor/canvas/editor_tool.dart
//
// The shared tool model for the pen-first editors (PDF, note, slide). Replaces
// the scattered per-editor booleans (`_selectTextMode`, `_placeLinkMode`, the
// old `CanvasTool` pen/highlighter/eraser triad) with ONE active-tool enum so
// every editor reasons about "which tool is active" the same way.
//
// [EditorToolKind] is the core, render-path-independent set shared by all three
// editors. The PDF editor layers TWO extra page-anchored tools on top
// (select-text and place-scratch-link) that the PenCanvas editors don't have —
// those remain editor-local because they ride pdfrx's text layer / the page
// overlay, not the ink capture path. See `selectTextOrLink` note below.
//
// TODO(toolbar-batch-2): bookmark-to-paragraph, search+OCR, templates — later
// batches add kinds here. (The typed-text tool now exists as [EditorToolKind.
// text], PDF-only for now; see the `text` doc below.)

/// The shared inking/editing tools available on every pen-first canvas.
enum EditorToolKind {
  /// Freehand drawing with the currently-selected [BrushKind] (fountain pen,
  /// ballpoint, or pencil). Each brush carries its own remembered color.
  brush,

  /// Freehand drawing with the highlighter brush (its own color + flat width).
  highlighter,

  /// Stroke eraser (partial / whole-stroke per PenConfig).
  eraser,

  /// Cursor / selection tool: tap a committed stroke to select it, drag the
  /// selection to translate it, delete to remove it.
  select,

  /// Shape tool: pen-drag previews a [ShapeKind] from start→current and commits
  /// it as a generated [PenStroke] on release.
  shape,

  /// Typed-text tool (PDF editor only for now): a pen-tap OR a mouse
  /// double-click on a page drops a text box at that normalized point and
  /// focuses a real Flutter text field for input (so the OS IME / Windows-Ink
  /// handwriting panel works). Committed boxes render glued to the page and are
  /// re-editable; an empty box deletes itself on blur.
  text,
}

/// The shapes the [EditorToolKind.shape] tool can draw. Each is generated as a
/// plain [PenStroke] (a polyline) so it reuses stroke rendering, persistence,
/// erase, and undo with no new model — see `shape_geometry.dart`.
enum ShapeKind {
  /// Straight line: 2 points (start → end).
  line,

  /// Axis-aligned rectangle: 5-point closed polyline (start corner → end corner).
  rectangle,

  /// Ellipse inscribed in the start→end bounding box: ~48 sampled points.
  ellipse,

  /// Arrow: shaft (start → end) plus two arrowhead segments at the end.
  arrow,
}
