# `ExRatatui.Widgets.Canvas`
[🔗](https://github.com/mcass19/ex_ratatui/blob/v0.8.2/lib/ex_ratatui/widgets/canvas.ex#L1)

A 2D drawing surface for plotting shapes in arbitrary coordinate space.

Wraps Ratatui's `Canvas` widget. Define the coordinate window with
`:x_bounds` and `:y_bounds` — both `{min, max}` tuples — and paint
into it by listing shape structs in `:shapes`. Each shape carries its
own color; the canvas only controls the marker resolution and the
optional background wash.

Supported shapes live under `ExRatatui.Widgets.Canvas.*`:

  * `Line`      - `%Line{x1, y1, x2, y2, color}`
  * `Rectangle` - `%Rectangle{x, y, width, height, color}` (bottom-left anchored, outline only)
  * `Circle`    - `%Circle{x, y, radius, color}` (center anchored, outline only)
  * `Points`    - `%Points{coords: [{x, y}], color}`
  * `Map`       - `%Map{resolution, color}` (world map; pair with `{-180, 180}` × `{-90, 90}` bounds)
  * `Label`     - `%Label{x, y, text, color}` (text annotation drawn on top of the canvas)

## Markers

The `:marker` controls how canvas coordinates map to cell pixels:

  * `:braille` (default) - 2×4 sub-cell pixels, best for lines/curves
  * `:dot`               - one glyph per cell
  * `:block`             - solid block, good for heatmaps
  * `:bar`               - half-height bar
  * `:half_block`        - 1×2 sub-cell pixels

## Fields

  * `:x_bounds` - `{min, max}` tuple bounding the X axis (required)
  * `:y_bounds` - `{min, max}` tuple bounding the Y axis (required)
  * `:marker` - one of `:braille`, `:dot`, `:block`, `:bar`, `:half_block`
    (default `:braille`)
  * `:background_color` - `ExRatatui.Style.color()` washed behind shapes; `nil`
    falls back to the terminal default
  * `:shapes` - list of shape structs (default `[]`)
  * `:block` - optional `%ExRatatui.Widgets.Block{}` container

## Examples

    iex> alias ExRatatui.Widgets.Canvas
    iex> alias ExRatatui.Widgets.Canvas.Line
    iex> %Canvas{
    ...>   x_bounds: {0.0, 10.0},
    ...>   y_bounds: {0.0, 10.0},
    ...>   shapes: [%Line{x1: 0.0, y1: 0.0, x2: 10.0, y2: 10.0, color: :red}]
    ...> }
    %ExRatatui.Widgets.Canvas{
      x_bounds: {0.0, 10.0},
      y_bounds: {0.0, 10.0},
      marker: :braille,
      background_color: nil,
      shapes: [
        %ExRatatui.Widgets.Canvas.Line{x1: 0.0, y1: 0.0, x2: 10.0, y2: 10.0, color: :red}
      ],
      block: nil
    }

# `marker`

```elixir
@type marker() :: :braille | :dot | :block | :bar | :half_block
```

# `shape`

```elixir
@type shape() ::
  ExRatatui.Widgets.Canvas.Line.t()
  | ExRatatui.Widgets.Canvas.Rectangle.t()
  | ExRatatui.Widgets.Canvas.Circle.t()
  | ExRatatui.Widgets.Canvas.Points.t()
  | ExRatatui.Widgets.Canvas.Map.t()
  | ExRatatui.Widgets.Canvas.Label.t()
```

# `t`

```elixir
@type t() :: %ExRatatui.Widgets.Canvas{
  background_color: ExRatatui.Style.color() | nil,
  block: ExRatatui.Widgets.Block.t() | nil,
  marker: marker(),
  shapes: [shape()],
  x_bounds: {number(), number()},
  y_bounds: {number(), number()}
}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*