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

Socket-first item lifecycle, frame, visibility, props, and relationship commands.

These functions are the app-facing canvas item verbs. They enter the same
command, authorization, event, reducer, persistence, and projection path used
by browser events and shared canvases.

Canvas items are public structs. Applications that receive assigned item maps can
read and pattern match on `%LivePanels.Item{}` values directly.

Derived placement helpers such as `move_by/3`, `move_to/3`, `resize_by/3`,
and `resize_to/3` read the target's current canvas state, then submit a
placement command. In a transaction this reads the transaction preview; on a
shared socket it reads the participant's last synced state and the coordinator
resolves concurrent commands by normal command ordering.

# `command_opts`

```elixir
@type command_opts() :: keyword()
```

# `command_result`

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

# `group_ref`

```elixir
@type group_ref() :: {:group, String.t()} | String.t() | LivePanels.Item.t()
```

# `item_or_group_ref`

```elixir
@type item_or_group_ref() :: item_ref() | {:group, String.t()}
```

# `item_ref`

```elixir
@type item_ref() :: LivePanels.Item.ref()
```

# `item_scope`

```elixir
@type item_scope() :: item_or_group_ref() | :selection | [item_ref()]
```

# `socket`

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

# `target`

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

First argument accepted by canvas item command helpers.

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

# `vector`

```elixir
@type vector() :: {number(), number()}
```

# `add`

```elixir
@spec add(target(), LivePanels.Item.item_type(), command_opts()) :: command_result()
```

Adds an item to the canvas and returns the command result.

# `add!`

```elixir
@spec add!(target(), LivePanels.Item.item_type(), command_opts()) :: target()
```

Adds an item to the canvas.

# `add_attached`

```elixir
@spec add_attached(target(), item_ref(), LivePanels.Item.item_type(), command_opts()) ::
  command_result()
```

Adds an attached item and returns the command result.

# `add_attached!`

```elixir
@spec add_attached!(target(), item_ref(), LivePanels.Item.item_type(), command_opts()) ::
  target()
```

Adds an item attached to an existing parent item.

# `attach`

```elixir
@spec attach(target(), item_ref(), item_ref(), command_opts()) :: command_result()
```

Attaches an item and returns the command result.

# `attach!`

```elixir
@spec attach!(target(), item_ref(), item_ref(), command_opts()) :: target()
```

Attaches an existing child item to an existing parent item.

# `clear_props`

```elixir
@spec clear_props(target(), item_ref()) :: command_result()
```

Clears an item's host-owned props map and returns the command result.

# `clear_props!`

```elixir
@spec clear_props!(target(), item_ref()) :: target()
```

Clears an item's host-owned props map.

# `copy_to`

```elixir
@spec copy_to(target(), item_ref(), LivePanels.Canvas.Placement.frame() | map()) ::
  command_result()
```

Copies an item and returns the command result.

# `copy_to!`

```elixir
@spec copy_to!(target(), item_ref(), LivePanels.Canvas.Placement.frame() | map()) ::
  target()
```

Copies an item to an application placement frame.

# `delete_prop`

```elixir
@spec delete_prop(target(), item_ref(), atom() | String.t()) :: command_result()
```

Deletes one key from an item's host-owned props map and returns the command result.

# `delete_prop!`

```elixir
@spec delete_prop!(target(), item_ref(), atom() | String.t()) :: target()
```

Deletes one key from an item's host-owned props map.

# `detach`

```elixir
@spec detach(target(), item_ref()) :: command_result()
```

Detaches an item and returns the command result.

# `detach!`

```elixir
@spec detach!(target(), item_ref()) :: target()
```

Detaches an item from its current parent.

# `edit`

```elixir
@spec edit(target(), item_scope(), map() | keyword()) :: command_result()
```

Edits LivePanels-owned item metadata and returns the command result.

# `edit!`

```elixir
@spec edit!(target(), item_scope(), map() | keyword()) :: target()
```

Edits LivePanels-owned item metadata.

# `focus`

```elixir
@spec focus(target(), item_ref()) :: command_result()
```

Focuses an item and returns the command result.

# `focus!`

```elixir
@spec focus!(target(), item_ref()) :: target()
```

Focuses an item and promotes it in the canvas z-order.

# `group`

```elixir
@spec group(target(), [item_ref()], command_opts()) :: command_result()
```

Groups items and returns the command result.

# `group!`

```elixir
@spec group!(target(), [item_ref()], command_opts()) :: target()
```

Groups items by assigning one group id to every item.

# `hide`

```elixir
@spec hide(target(), item_ref()) :: command_result()
```

Hides an item and returns the command result.

# `hide!`

```elixir
@spec hide!(target(), item_ref()) :: target()
```

Hides an existing item without removing it from canonical state.

# `merge_props`

```elixir
@spec merge_props(target(), item_ref(), map()) :: command_result()
```

Merges keys into an item's host-owned props map and returns the command result.

# `merge_props!`

```elixir
@spec merge_props!(target(), item_ref(), map()) :: target()
```

Merges keys into an item's host-owned props map.

# `move_by`

```elixir
@spec move_by(target(), item_or_group_ref(), vector()) :: command_result()
```

Moves an item by a delta and returns the command result.

# `move_by!`

```elixir
@spec move_by!(target(), item_or_group_ref(), vector()) :: target()
```

Moves an item by a delta.

# `move_to`

```elixir
@spec move_to(target(), item_or_group_ref(), vector()) :: command_result()
```

Moves an item to an absolute position and returns the command result.

# `move_to!`

```elixir
@spec move_to!(target(), item_or_group_ref(), vector()) :: target()
```

Moves an item to an absolute `{x, y}` world or viewport coordinate.

# `place`

```elixir
@spec place(
  target(),
  item_or_group_ref(),
  LivePanels.Canvas.Placement.frame() | map()
) ::
  command_result()
```

Places an item and returns the command result.

# `place!`

```elixir
@spec place!(
  target(),
  item_or_group_ref(),
  LivePanels.Canvas.Placement.frame() | map()
) :: target()
```

Places an item at an application placement frame.

Application frames require `:x`, `:y`, `:w`, and `:h`. Omitted `:space` and
`:anchor` default to `:world` and `:top_left`; explicit malformed values
raise.

# `present`

```elixir
@spec present(target(), item_ref(), command_opts()) :: command_result()
```

Presents an item and returns the command result.

# `present!`

```elixir
@spec present!(target(), item_ref(), command_opts()) :: target()
```

Presents an existing item by showing it, optionally placing and focusing it.

# `put_props`

```elixir
@spec put_props(target(), item_ref(), map()) :: command_result()
```

Replaces an item's host-owned props map and returns the command result.

# `put_props!`

```elixir
@spec put_props!(target(), item_ref(), map()) :: target()
```

Replaces an item's host-owned props map.

# `remove`

```elixir
@spec remove(target(), item_scope()) :: command_result()
```

Removes an item, selected items, or grouped items and returns the command result.

# `remove!`

```elixir
@spec remove!(target(), item_scope()) :: target()
```

Removes an item, selected items, or grouped items from the canvas.

# `resize_by`

```elixir
@spec resize_by(target(), item_or_group_ref(), vector()) :: command_result()
```

Resizes an item by a delta and returns the command result.

# `resize_by!`

```elixir
@spec resize_by!(target(), item_or_group_ref(), vector()) :: target()
```

Resizes an item by a width/height delta.

# `resize_to`

```elixir
@spec resize_to(target(), item_or_group_ref(), vector()) :: command_result()
```

Resizes an item to an absolute size and returns the command result.

# `resize_to!`

```elixir
@spec resize_to!(target(), item_or_group_ref(), vector()) :: target()
```

Resizes an item to an absolute `{w, h}` frame size.

# `restrict`

```elixir
@spec restrict(target(), item_scope(), [String.t()] | String.t()) :: command_result()
```

Restricts items and returns the command result.

# `restrict!`

```elixir
@spec restrict!(target(), item_scope(), [String.t()] | String.t()) :: target()
```

Restricts an item, grouped items, or selected items to participant client ids.

# `share`

```elixir
@spec share(target(), item_scope(), [String.t()] | String.t()) :: command_result()
```

Shares items and returns the command result.

# `share!`

```elixir
@spec share!(target(), item_scope(), [String.t()] | String.t()) :: target()
```

Shares an item, grouped items, or selected items with participant client ids.

# `share_with_all`

```elixir
@spec share_with_all(target(), item_scope()) :: command_result()
```

Makes items visible to every participant and returns the command result.

# `share_with_all!`

```elixir
@spec share_with_all!(target(), item_scope()) :: target()
```

Makes an item, grouped items, or selected items visible to every participant.

# `show`

```elixir
@spec show(target(), item_ref()) :: command_result()
```

Shows an item and returns the command result.

# `show!`

```elixir
@spec show!(target(), item_ref()) :: target()
```

Shows an existing item without changing its identity or layout.

# `toggle_visibility`

```elixir
@spec toggle_visibility(target(), item_ref()) :: command_result()
```

Toggles an item's visibility and returns the command result.

# `toggle_visibility!`

```elixir
@spec toggle_visibility!(target(), item_ref()) :: target()
```

Toggles an existing item's visibility.

# `ungroup`

```elixir
@spec ungroup(target(), group_ref()) :: command_result()
```

Ungroups items and returns the command result.

# `ungroup!`

```elixir
@spec ungroup!(target(), group_ref()) :: target()
```

Clears a group id from every item in the group.

# `unshare`

```elixir
@spec unshare(target(), item_scope(), [String.t()] | String.t()) :: command_result()
```

Unshares items and returns the command result.

# `unshare!`

```elixir
@spec unshare!(target(), item_scope(), [String.t()] | String.t()) :: target()
```

Removes participant client ids from an item visibility list.

---

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