cranpose_services/
share_sheet.rs

1//! System share sheet: hand a file (and optional text) to the OS share UI so
2//! the user can send it to another app.
3//!
4//! Like [`crate::uri_handler`], the compiled-in default is a no-op that reports
5//! [`ShareError::Unsupported`]; platform backends install a real implementation
6//! through [`set_platform_share_sheet`] (iOS `UIActivityViewController`, Android
7//! `ACTION_SEND`, the Web Share API). Desktop has no system share sheet — apps
8//! export through a save dialog instead — so `is_supported` is `false` there and
9//! the UI can offer "Save…" rather than "Share".
10
11use std::rc::Rc;
12
13use cranpose_core::{CompositionLocal, CompositionLocalProvider, compositionLocalOfWithPolicy};
14use cranpose_macros::composable;
15
16#[derive(thiserror::Error, Debug)]
17pub enum ShareError {
18    #[error("sharing is not supported on this platform")]
19    Unsupported,
20    #[error("failed to present the share sheet: {0}")]
21    Failed(String),
22}
23
24/// A single file to share, with an optional accompanying message/subject.
25#[derive(Clone, Debug, PartialEq, Eq)]
26pub struct ShareContent {
27    /// Suggested file name shown to the user and used by the receiving app.
28    pub file_name: String,
29    /// MIME type of `bytes` (e.g. `application/pdf`, `image/jpeg`).
30    pub mime_type: String,
31    /// File payload. Backends stage it to a temporary URL to share.
32    pub bytes: Vec<u8>,
33    /// Optional text/subject shared alongside the file.
34    pub text: Option<String>,
35}
36
37impl ShareContent {
38    /// A file to share, identified by name and MIME type.
39    pub fn file(
40        file_name: impl Into<String>,
41        mime_type: impl Into<String>,
42        bytes: Vec<u8>,
43    ) -> Self {
44        Self {
45            file_name: file_name.into(),
46            mime_type: mime_type.into(),
47            bytes,
48            text: None,
49        }
50    }
51
52    /// Attach accompanying text (subject / message) to the shared file.
53    pub fn with_text(mut self, text: impl Into<String>) -> Self {
54        self.text = Some(text.into());
55        self
56    }
57}
58
59/// The OS share sheet. Installed by the platform backend; the default is a
60/// no-op that reports [`ShareError::Unsupported`].
61pub trait ShareSheet {
62    /// Present the system share sheet for `content`. Fire-and-forget: it
63    /// resolves once presented and does not report the user's choice.
64    fn share(&self, content: ShareContent) -> Result<(), ShareError>;
65
66    /// Whether a real system share sheet is available (so UI can choose between
67    /// "Share" and "Save…").
68    fn is_supported(&self) -> bool;
69}
70
71pub type ShareSheetRef = Rc<dyn ShareSheet>;
72
73/// Installs a platform share sheet, replacing any previously installed one.
74/// Backends with main-thread UIKit / Activity access register here.
75pub fn set_platform_share_sheet(share_sheet: ShareSheetRef) {
76    crate::thread_state::with(|state| *state.share_sheet.borrow_mut() = Some(share_sheet));
77}
78
79/// Removes any registered platform share sheet (tests and teardown).
80pub fn clear_platform_share_sheet() {
81    crate::thread_state::with(|state| *state.share_sheet.borrow_mut() = None);
82}
83
84fn registered_platform_share_sheet() -> Option<ShareSheetRef> {
85    crate::thread_state::with(|state| state.share_sheet.borrow().clone())
86}
87
88struct PlatformShareSheet;
89
90impl ShareSheet for PlatformShareSheet {
91    fn share(&self, content: ShareContent) -> Result<(), ShareError> {
92        match registered_platform_share_sheet() {
93            Some(handler) => handler.share(content),
94            None => Err(ShareError::Unsupported),
95        }
96    }
97
98    fn is_supported(&self) -> bool {
99        registered_platform_share_sheet().is_some_and(|handler| handler.is_supported())
100    }
101}
102
103pub fn default_share_sheet() -> ShareSheetRef {
104    Rc::new(PlatformShareSheet)
105}
106
107pub fn local_share_sheet() -> CompositionLocal<ShareSheetRef> {
108    crate::composition_locals::cached_local(
109        |locals| &locals.share_sheet,
110        || compositionLocalOfWithPolicy(default_share_sheet, Rc::ptr_eq),
111    )
112}
113
114#[composable]
115pub fn ProvideShareSheet(content: impl FnOnce()) {
116    let share_sheet = cranpose_core::remember(default_share_sheet).with(|state| state.clone());
117    let local = local_share_sheet();
118
119    CompositionLocalProvider([local.provides(share_sheet)], move || {
120        content();
121    });
122}
123
124#[cfg(test)]
125#[path = "tests/share_sheet_tests.rs"]
126mod tests;
cranpose_services/share_sheet.rs

cranpose_services/
share_sheet.rs
