# `PhiaUi.Components.Collab.Presence`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/collab/presence.ex#L1)

Collaborative presence components for real-time multi-user interfaces.

Provides avatar stacks, typing indicators, status bars, and user lists
designed for collaborative editing, whiteboarding, and shared workspace
applications. All components are pure function components with no JS hooks
required — state is managed server-side via Phoenix Presence or similar.

## Components

| Component              | Purpose                                               |
|------------------------|-------------------------------------------------------|
| `collab_avatar_stack/1`| Overlapping avatar circles with status dots + tooltips |
| `who_is_typing/1`      | Animated "X is typing..." indicator                   |
| `collab_status_bar/1`  | Combined bar: connection + avatars + typing + extras   |
| `collab_user_list/1`   | Full vertical user panel with roles and status         |

## User map shape

Components that accept a `:users` list expect maps with these keys:

    %{
      id: "user-1",
      name: "Alice Adams",
      color: "#3B82F6",
      avatar_url: "/avatars/alice.jpg",  # optional
      status: :online,                    # :online | :idle | :offline
      role: "Editor",                     # optional, for collab_user_list
      idle_since: ~U[2026-03-19 10:00:00Z] # optional
    }

# `collab_avatar_stack`

Renders an overlapping stack of user avatars with status dots and tooltips.

Users beyond `max_visible` are collapsed into a "+N more" overflow badge.
Each avatar shows a colored status dot (green = online, amber = idle,
gray = offline).

## Example

    <.collab_avatar_stack
      id="editor-presence"
      users={@online_users}
      max_visible={4}
      size={:md}
    />

## Attributes

* `id` (`:string`) (required)
* `users` (`:list`) - Defaults to `[]`.
* `max_visible` (`:integer`) - Defaults to `5`.
* `size` (`:atom`) - Defaults to `:md`. Must be one of `:sm`, `:md`, or `:lg`.
* `show_tooltip` (`:boolean`) - Defaults to `true`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.

# `collab_status_bar`

Renders a combined status bar with connection indicator, avatar stack,
typing indicator, and optional extra content.

## Example

    <.collab_status_bar
      id="collab-bar"
      connection_status={@conn_status}
      users={@users}
      typing_users={@typing}
    >
      <:extra>
        <button>Share</button>
      </:extra>
    </.collab_status_bar>

## Attributes

* `id` (`:string`) (required)
* `connection_status` (`:atom`) - Defaults to `:connected`. Must be one of `:connected`, `:reconnecting`, or `:offline`.
* `users` (`:list`) - Defaults to `[]`.
* `typing_users` (`:list`) - Defaults to `[]`.
* `class` (`:string`) - Defaults to `nil`.
## Slots

* `extra` - Custom toolbar items rendered at the end of the status bar.

# `collab_user_list`

Renders a vertical user list panel showing each user with avatar, name,
role badge, and status indicator. The current user is annotated with "(You)".

## Example

    <.collab_user_list
      id="user-panel"
      users={@users}
      current_user_id={@current_user.id}
    />

## Attributes

* `id` (`:string`) (required)
* `users` (`:list`) - Defaults to `[]`.
* `current_user_id` (`:string`) - Defaults to `nil`.
* `class` (`:string`) - Defaults to `nil`.

# `who_is_typing`

Renders an animated "X is typing..." indicator.

Shows the appropriate message based on number of typing users:
- 0 users: renders an empty hidden div
- 1 user: "Alice is typing..."
- 2 users: "Alice, Bob are typing..."
- 3+ users: "Several people are typing..."

## Example

    <.who_is_typing id="typing-indicator" typing_users={@typing_users} />

## Attributes

* `id` (`:string`) (required)
* `typing_users` (`:list`) - Defaults to `[]`.
* `class` (`:string`) - Defaults to `nil`.

---

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