# `Issho.Join`
[🔗](https://github.com/hattoriai/issho/blob/v0.4.0/lib/issho/join.ex#L1)

How a component joins Issho: the same `issho` option in every
component (Kotoba's editor, Hakushi's canvas, Masu's grid, yours), so an
app writes it once and it means the same everywhere.

    <.kotoba    issho={[instance: MyApp.Issho, document: "page:1/body"]} user={@user} />
    <.canvas    issho={[instance: MyApp.Issho, document: "page:2"]} user={@user} />
    <.data_grid issho={[instance: MyApp.Issho, document: "page:3/rows"]} user={@user} />

The keys:

  * `:instance` (required): your Issho instance, `MyApp.Issho`.
  * `:document` (required): the document the component shows. Its room
    is the part before the first `"/"` (`"page:1/body"` is in
    `"page:1"`), so the components of a page whose documents share a
    room share its people, and a pointer goes from one to the other.
  * `:can`: `:write` (the default) or `:read`, what the person may do
    here; your policy is asked as well.
  * `:people`: whether the component shows the room's people itself
    (`true`); `false` on a page that shows Issho's list
    (`Issho.Components.people/1`).
  * `:follow`: whether the component takes part in following (`true`);
    `false`, and it follows no one and shows no one followed, though the
    room's other components do.
  * `:on_behalf_of`: the person an actor acts for (an agent's person).
  * `:claims`: what your policy needs to know of the actor, signed in
    its grant.

A component takes its own options besides these (Kotoba's `:undo`), and
says which with `new!/2`'s `extra`; any other key is an error, so a
typo does not go unnoticed. The person is the component's `user`, as
`Issho.Actor` says them.

# `t`

```elixir
@type t() :: %Issho.Join{
  can: :write | :read,
  claims: map(),
  document: String.t(),
  extra: map(),
  follow: boolean(),
  instance: atom(),
  on_behalf_of: term(),
  people: boolean(),
  room: String.t()
}
```

# `grant_opts`

```elixir
@spec grant_opts(t()) :: keyword()
```

The options of `Issho.Live.grant/4` and `Issho.Live.join/4` for the
person: `:can`, `:claims` and `:on_behalf_of`.

# `new!`

```elixir
@spec new!(keyword() | map() | t(), [atom()]) :: t()
```

The options of a component's `issho`, checked: a keyword list (or a
map), and `extra`, the keys of the component's own options. Raises
`ArgumentError` for a missing, unknown or invalid key.

---

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