# `Mob.Share`
[🔗](https://github.com/genericjam/mob/blob/master/lib/mob/share.ex#L1)

System share sheet. Opens the OS share dialog with text or a local file.
Fire-and-forget — `text/2` and `file/3` always return the socket unchanged.

## Usage

    def handle_event("share", _params, socket) do
      {:noreply, Mob.Share.text(socket, "Check out Mob: https://github.com/genericjam/mob")}
    end

    def handle_info({:tap, :export}, socket) do
      path = Path.join(Mob.Storage.dir(:cache), "exports/report.pdf")
      {:noreply, Mob.Share.file(socket, path, title: "Quarterly Report")}
    end

    def handle_info({:mob_share, :error, reason}, socket) do
      {:noreply, Mob.Alert.toast(socket, "Share failed: #{reason}")}
    end

## Message contract

`file/3` delivers setup failures asynchronously (or immediately from Elixir
when the file is missing) to the calling process (`self()`) as
`{:mob_share, :error, reason}` where `reason` is one of:

- `:not_found` — the path does not exist, is a directory, or is unreadable
- `:no_activity` — no foreground activity (Android) or active window scene presenter (iOS)
- `:no_app` — no target app can handle the share intent (Android)
- `:failed` — FileProvider URI or native share setup threw an error
- `:unsupported` — the Android host `MobBridge` predates `shareFile`

Success, completion, and user cancellation of the share sheet are never reported.

## Platform notes

- **Android** shares via `Intent.ACTION_SEND` wrapped in `Intent.createChooser`,
  backed by `androidx.core.content.FileProvider`. The file MUST live under a root
  declared in the host's `res/xml/file_provider_paths.xml`. Generated `mob_new`
  apps cover the whole app cache directory (`Mob.Storage.dir(:cache)`), so write
  shared exports under the cache directory; sharing a path outside any configured
  root delivers `{:mob_share, :error, :failed}`. Older `mob_new` hosts without
  `MobBridge.shareFile` deliver `{:mob_share, :error, :unsupported}`.
- **iOS** shares a `file://` `NSURL` through `UIActivityViewController` (with a
  `UIActivityItemSource` item supplying the file URL, subject title, and UTI
  type identifier derived from `:mime`), presented with a centered popover
  anchor on iPad.

# `error_reason`

```elixir
@type error_reason() :: :not_found | :no_activity | :no_app | :failed | :unsupported
```

# `file`

```elixir
@spec file(Mob.Socket.t(), Path.t(), keyword()) :: Mob.Socket.t()
```

Open the share sheet with a local file. Always returns the socket unchanged.

`path` may be a binary or chardata and is resolved with `Path.absname/1`.
Setup errors are sent to `self()` as `{:mob_share, :error, reason}`.

## Options

- `:mime` — non-empty MIME type string containing `"/"`. Defaults to a type
  derived case-insensitively from the file extension, falling back to
  `"application/octet-stream"`.
- `:title` — non-empty share title string. Defaults to `Path.basename(path)`.
  It titles the Android chooser and becomes the subject where the target
  has one (Mail, Gmail). It does not rename the file: what the recipient
  sees, and what the iOS share sheet shows, is the file's own name, so
  name the file for the reader before sharing it.

# `text`

```elixir
@spec text(Mob.Socket.t(), binary()) :: Mob.Socket.t()
```

Open the share sheet with plain text. Returns the socket unchanged.

---

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