# `LivePanels.Canvas.Region`
[🔗](https://github.com/livepanels/livepanels/blob/v0.1.0/lib/livepanels/canvas/region.ex#L1)

Headless named region helpers for shared canvas partitioning.

A region is an ordinary persistent canvas item with a `:region` capability.
Region-scoped participants carry a `region_id`; projection and viewport
enforcement then use the region item's world-space bounds as the structural
boundary. The runtime does not assign product meaning to a region.

# `bounds`

```elixir
@type bounds() :: %{
  optional(:x) => number(),
  optional(:y) => number(),
  optional(:w) => number(),
  optional(:h) => number(),
  optional(:left) => number(),
  optional(:top) => number(),
  optional(:width) => number(),
  optional(:height) => number()
}
```

# `command`

```elixir
@type command() :: {:add_item, :region, map()}
```

# `command_result`

```elixir
@type command_result() :: LivePanels.Canvas.Command.result()
```

# `resolved_bounds`

```elixir
@type resolved_bounds() :: %{
  left: number(),
  top: number(),
  right: number(),
  bottom: number(),
  width: number(),
  height: number()
}
```

# `socket`

```elixir
@type socket() :: Phoenix.LiveView.Socket.t()
```

# `target`

```elixir
@type target() :: LivePanels.Canvas.command_target()
```

First argument accepted by region command helpers.

Pass a LiveView socket for a standalone command, or a
`LivePanels.Canvas.Transaction` context inside `LivePanels.Canvas.transaction/2`.

# `viewport_tile`

```elixir
@type viewport_tile() :: LivePanels.Item.t()
```

# `bounds`

```elixir
@spec bounds(LivePanels.Item.t() | nil) :: resolved_bounds() | nil
```

Returns the world-space bounds for a region item.

# `contains_item?`

```elixir
@spec contains_item?(resolved_bounds(), LivePanels.Item.t()) :: boolean()
```

Returns true when an item is fully inside the given region bounds.

# `define`

```elixir
@spec define(target(), String.t() | atom(), bounds(), keyword() | map()) ::
  command_result()
```

Defines a persistent named region and returns the command result.

# `define!`

```elixir
@spec define!(target(), String.t() | atom(), bounds(), keyword() | map()) :: target()
```

Defines a persistent named region through the canvas command path.

# `define_commands`

```elixir
@spec define_commands(String.t() | atom(), bounds(), keyword() | map()) :: [command()]
```

Returns command tuples that define a persistent named region item.

# `find`

```elixir
@spec find(map(), String.t() | atom() | nil) :: LivePanels.Item.t() | nil
```

Finds a region item by item id or by its region capability name.

# `participant_session`

```elixir
@spec participant_session(LivePanels.Item.ref(), keyword() | map()) :: map()
```

Returns a LiveView session map for entering a scoped shared region.

---

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