# `Hakushi.Paper`
[🔗](https://github.com/hattoriai/hakushi/blob/v0.6.0/lib/hakushi/paper.ex#L1)

The paper of a canvas: its pattern (`background`) and the size of its
squares (`grid`), which nodes snap to.

A canvas's paper is its `background` and `grid` attributes (or its first
kit's, see `c:Hakushi.Kit.canvas/0`), unless its graph has one of its
own (`Hakushi.Graph`'s `paper`): the paper people chose, with the
canvas's paper picker (`papers`), or the app (`Hakushi.Change.paper/1`).
It is a change as any other: it goes through `on_change`, ⌘Z takes it
back, and on a shared canvas everyone sees it.

    %{background: "lines", grid: 24}

## The papers people choose from

The canvas's `papers` attribute turns the picker on, in its controls:
`true` for Hakushi's papers (`builtin/0`), or a list of the papers it
offers, Hakushi's by their atom and the app's own by their name and
label:

    <.canvas id="board" graph={@graph} papers={[:dots, :lines, %{name: "iso", label: "Isometric"}]} />

## A paper of the app's own

A paper is a pattern of CSS, drawn on the paper of the canvas
(`.hakushi[data-background="iso"] .hakushi-background`) and on its
swatch in the picker (`.hakushi-paper-swatch[data-background="iso"]`).
The canvas moves the pattern with the view, and sets its custom
properties: `--hakushi-grid-size`, a square on the screen (the grid at
the zoom); `--hakushi-pattern` and `--hakushi-pattern-strong`, the colours
of the paper's lines (see the Theming guide).

    .hakushi[data-background="iso"] .hakushi-background,
    .hakushi-paper-swatch[data-background="iso"] {
      background-image:
        linear-gradient(30deg, var(--hakushi-pattern) 1px, transparent 1px),
        linear-gradient(150deg, var(--hakushi-pattern) 1px, transparent 1px);
      background-size: var(--hakushi-grid-size) calc(var(--hakushi-grid-size) * 0.577);
    }

Give it to the canvas as its `background` (`background="iso"`), or in
its `papers`.

# `offer`

```elixir
@type offer() :: %{name: String.t(), label: String.t() | nil}
```

A paper offered in the picker: its name, and its label (`nil` for Hakushi's words).

# `t`

```elixir
@type t() :: %{background: String.t() | nil, grid: pos_integer() | nil}
```

A paper: its pattern's name and its squares' size, each `nil` for the canvas's own.

# `builtin`

```elixir
@spec builtin() :: [String.t()]
```

The names of Hakushi's papers: dots, graph paper, crosses and none.

# `grids`

```elixir
@spec grids() :: [pos_integer()]
```

The sizes of the squares the picker offers, in pixels at 100%.

# `new`

```elixir
@spec new(nil | map() | keyword()) :: t() | nil
```

A paper of a map or a keyword list with `:background` (an atom or a
string) and `:grid`, or `nil` for none. Raises on a name that is not one
(letters, digits and dashes) or a grid that is not a whole number from 4
to 200.

---

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