@spec assign_color(term()) :: String.t()

Generates a deterministic color from a replica ID.

The same replica ID always produces the same color, providing consistent visual identification across sessions.

Example

iex> Grove.Presence.assign_color("user_123")
"#4CAF50"

iex> Grove.Presence.assign_color("user_456")
"#2196F3"

@spec get_replica(String.t(), term()) :: map()

Gets presence for a specific replica.

Returns %{metas: [meta]} or an empty map if not found.

Example

case Grove.Presence.get_replica("doc_123", "replica_1") do
  %{metas: [meta | _]} -> meta.cursor
  _ -> nil
end

@spec list_replicas(String.t()) :: map()

Lists all presences for a document.

Returns a map of %{replica_id => %{metas: [meta]}}.

Example

presences = Grove.Presence.list_replicas("doc_123")
# %{
#   "replica_1" => %{metas: [%{cursor: %{node_id: "f1", offset: 10}, ...}]},
#   "replica_2" => %{metas: [%{cursor: nil, ...}]}
# }

Starts the Presence tracker.

Options

• :pubsub - The PubSub server to use. Defaults to configured value.
• :name - The name to register the presence server. Defaults to Grove.Presence.

Example

children = [
  {Phoenix.PubSub, name: MyApp.PubSub},
  {Grove.Presence, pubsub: MyApp.PubSub}
]

@spec subscribe(String.t()) :: :ok | {:error, term()}

Subscribes the current process to presence updates for a document.

After subscribing, the process will receive presence messages:

def handle_info({Grove.Presence, {:join, key, meta}}, socket) do
  # Handle user join
  {:noreply, socket}
end

def handle_info({Grove.Presence, {:leave, key, meta}}, socket) do
  # Handle user leave
  {:noreply, socket}
end

@spec sync_diff(map(), map()) :: map()

Synchronizes local presence state with a diff received from PubSub.

Call this in your handle_info when receiving presence_diff events.

Example

def handle_info(%Phoenix.Socket.Broadcast{event: "presence_diff", payload: diff}, socket) do
  presences = Grove.Presence.sync_diff(socket.assigns.presences, diff)
  {:noreply, assign(socket, :presences, presences)}
end

@spec sync_state(map(), map()) :: map()

Synchronizes local presence state with a full state message.

Useful for initial presence state synchronization.

@spec topic(String.t()) :: String.t()

Returns the PubSub topic for presence tracking on a document.

Uses a separate topic namespace from document sync for clean separation.

Example

iex> Grove.Presence.topic("doc_123")
"grove:presence:doc_123"

@spec track_replica(pid(), String.t(), term(), map()) ::
  {:ok, binary()} | {:error, term()}

Tracks a replica's presence in a document.

Parameters

• pid - The process to track
• doc_id - Document identifier
• replica_id - Unique replica identifier (e.g., socket.id)
• meta - Metadata map (cursor, selection, user info, etc.)

Example

Grove.Presence.track_replica(self(), "doc_123", "replica_1", %{
  user_name: "Alice",
  color: Grove.Presence.assign_color("replica_1"),
  cursor: nil,
  selection: nil,
  focus: nil
})

@spec unsubscribe(String.t()) :: :ok

Unsubscribes the current process from presence updates.

@spec update_replica(pid(), String.t(), term(), (map() -> map()) | map()) ::
  {:ok, binary()} | {:error, term()}

Updates a replica's presence metadata.

Accepts either a function that transforms the metadata or a map to merge.

Examples

# With update function
Grove.Presence.update_replica(self(), "doc_123", "replica_1", fn meta ->
  Map.put(meta, :cursor, %{node_id: "field_1", offset: 42})
end)

# With map (merges with existing metadata)
Grove.Presence.update_replica(self(), "doc_123", "replica_1", %{
  cursor: %{node_id: "field_1", offset: 42}
})