facett-core/src/clip.rs
//! **Cross-facet typed copy/paste** (§16) — the trait + payload machinery so
//! copy/paste carries **full typed data** between facett components, not just
//! text. A process-wide transfer registry holds the last typed [`ClipPayload`] so
//! a paste target gets the richest representation the source offered; on copy we
//! also mirror Text/TSV to the OS clipboard for external apps.
//!
//! This is the typed realisation of the contract's COH-4 ("copy/paste of data is
//! identical everywhere"). The legacy text-only [`crate::clipboard`] route still
//! works; this adds the *typed* lane on top.
//!
//! M1 ships **Text** + **DataColumns** (zero-copy Arrow via `Arc`); M2 adds
//! **Image** + an OS image bridge (`arboard`).
use std::sync::{Arc, Mutex, OnceLock};
use arrow_array::ArrayRef;
/// The kinds a payload can take. `Custom` is the extension point.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ClipKind {
Text,
/// Typed columns (Arrow arrays), zero-copy via `Arc`.
DataColumns,
/// A rectangle of rows as TSV (Excel/Sheets-pasteable).
Rows,
/// An image (M2).
Image,
Custom(&'static str),
}
/// One named Arrow column, shared zero-copy. The `Arc<dyn Array>` is the same
/// buffer the source holds — copying a grid column never clones the data.
#[derive(Clone)]
pub struct ArrowColumnRef {
pub name: String,
pub array: ArrayRef,
}
impl std::fmt::Debug for ArrowColumnRef {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ArrowColumnRef")
.field("name", &self.name)
.field("len", &self.array.len())
.field("dtype", &self.array.data_type())
.finish()
}
}
/// A typed clipboard payload. The richest form a source can offer; a target picks
/// the best representation it accepts (negotiation in [`PasteTarget::paste`]).
#[derive(Clone, Debug)]
pub enum ClipPayload {
Text(String),
/// Arc-shared Arrow columns — zero-copy.
DataColumns(Vec<ArrowColumnRef>),
/// TSV rows (a tabular text mirror).
Rows(String),
/// An RGBA image (e.g. a video frame or a chart export) — M2 (CLIP-4).
Image(egui::ColorImage),
/// Raw custom bytes under a kind tag.
Custom { kind: &'static str, bytes: Arc<[u8]> },
}
impl ClipPayload {
/// Which kind this payload is.
pub fn kind(&self) -> ClipKind {
match self {
ClipPayload::Text(_) => ClipKind::Text,
ClipPayload::DataColumns(_) => ClipKind::DataColumns,
ClipPayload::Rows(_) => ClipKind::Rows,
ClipPayload::Image(_) => ClipKind::Image,
ClipPayload::Custom { kind, .. } => ClipKind::Custom(kind),
}
}
/// The **universal fallback** text view of any payload (CLIP-3). DataColumns
/// render as TSV; Rows/Text pass through; Custom yields a lossy length tag.
pub fn as_text(&self) -> String {
match self {
ClipPayload::Text(s) | ClipPayload::Rows(s) => s.clone(),
ClipPayload::DataColumns(cols) => columns_to_tsv(cols),
ClipPayload::Image(img) => format!("[image {}x{}]", img.size[0], img.size[1]),
ClipPayload::Custom { kind, bytes } => format!("[{kind}: {} bytes]", bytes.len()),
}
}
/// The image, if this payload is one.
pub fn as_image(&self) -> Option<&egui::ColorImage> {
match self {
ClipPayload::Image(img) => Some(img),
_ => None,
}
}
}
/// **OS image clipboard bridge** (CLIP-5). egui's OS clipboard is text-only; this
/// optionally uses `arboard` (feature `os-image`) to put/get an image on the real
/// OS clipboard. In-process typed transfer (the registry) works regardless, so
/// this is purely the cross-application lane.
#[cfg(feature = "os-image")]
pub mod os_image {
use super::*;
/// Place an egui [`egui::ColorImage`] on the OS clipboard via arboard.
pub fn put_image(img: &egui::ColorImage) -> Result<(), String> {
let mut cb = arboard::Clipboard::new().map_err(|e| e.to_string())?;
let bytes: Vec<u8> = img.pixels.iter().flat_map(|p| [p.r(), p.g(), p.b(), p.a()]).collect();
cb.set_image(arboard::ImageData {
width: img.size[0],
height: img.size[1],
bytes: bytes.into(),
})
.map_err(|e| e.to_string())
}
/// Read an image off the OS clipboard into an egui [`egui::ColorImage`].
pub fn get_image() -> Result<egui::ColorImage, String> {
let mut cb = arboard::Clipboard::new().map_err(|e| e.to_string())?;
let img = cb.get_image().map_err(|e| e.to_string())?;
let size = [img.width, img.height];
let pixels = img
.bytes
.chunks_exact(4)
.map(|c| egui::Color32::from_rgba_unmultiplied(c[0], c[1], c[2], c[3]))
.collect();
Ok(egui::ColorImage::new(size, pixels))
}
}
/// A component that can **produce** a typed payload from its current selection.
pub trait CopySource {
/// The kinds this source can offer, richest first.
fn copy_kinds(&self) -> &[ClipKind];
/// Produce the payload for the current selection (richest representation).
fn copy_payload(&self) -> Option<ClipPayload>;
}
/// A component that can **accept** a pasted payload.
pub trait PasteTarget {
/// Does this target accept kind `k`?
fn accepts(&self, k: ClipKind) -> bool;
/// Apply the payload. Text is the universal fallback (CLIP-3).
fn paste_payload(&mut self, p: &ClipPayload);
}
/// Process-wide transfer registry (CLIP-2): the last typed payload a copy
/// produced. A paste target reads this to get the richest representation, even
/// across components that never touch the OS clipboard.
fn registry() -> &'static Mutex<Option<ClipPayload>> {
static REG: OnceLock<Mutex<Option<ClipPayload>>> = OnceLock::new();
REG.get_or_init(|| Mutex::new(None))
}
/// Store the typed payload for the next paste, and mirror **Text/TSV** to the OS
/// clipboard via egui (CLIP-2) so external apps (Excel/editors) can paste too.
pub fn put_typed(ctx: &egui::Context, payload: ClipPayload) {
let text = payload.as_text();
ctx.copy_text(text);
*registry().lock().unwrap() = Some(payload);
}
/// Store the typed payload without an egui context (tests / headless in-process
/// transfer between facett components).
pub fn put_typed_inproc(payload: ClipPayload) {
*registry().lock().unwrap() = Some(payload);
}
/// The last typed payload, if any (CLIP-2 read side).
pub fn last_typed() -> Option<ClipPayload> {
registry().lock().unwrap().clone()
}
/// Clear the registry (tests).
pub fn clear_typed() {
*registry().lock().unwrap() = None;
}
/// **Negotiated paste** (CLIP-3): hand `target` the best kind it accepts from the
/// last typed payload. If the payload's own kind isn't accepted, fall back to a
/// Text view (the universal fallback). Returns true if a paste happened.
pub fn paste_into(target: &mut dyn PasteTarget) -> bool {
let Some(payload) = last_typed() else { return false };
if target.accepts(payload.kind()) {
target.paste_payload(&payload);
true
} else if target.accepts(ClipKind::Text) {
target.paste_payload(&ClipPayload::Text(payload.as_text()));
true
} else {
false
}
}
/// Render Arrow columns to TSV (header + tab-joined cells) — the spreadsheet
/// mirror used by [`ClipPayload::as_text`] and the OS-clipboard mirror.
pub fn columns_to_tsv(cols: &[ArrowColumnRef]) -> String {
if cols.is_empty() {
return String::new();
}
let nrows = cols.iter().map(|c| c.array.len()).max().unwrap_or(0);
let mut out = String::new();
out.push_str(&cols.iter().map(|c| c.name.as_str()).collect::<Vec<_>>().join("\t"));
for r in 0..nrows {
out.push('\n');
let line: Vec<String> = cols.iter().map(|c| arrow_cell_text(c.array.as_ref(), r)).collect();
out.push_str(&line.join("\t"));
}
out
}
/// Best-effort text of one Arrow cell (common primitive types).
fn arrow_cell_text(arr: &dyn arrow_array::Array, i: usize) -> String {
use arrow_array::{
BooleanArray, Float32Array, Float64Array, Int32Array, Int64Array, StringArray, UInt32Array, UInt64Array,
};
if i >= arr.len() || arr.is_null(i) {
return String::new();
}
macro_rules! tnum {
($($ty:ty),*) => {{ $(if let Some(a) = arr.as_any().downcast_ref::<$ty>() { return a.value(i).to_string(); })* }};
}
tnum!(Int64Array, Int32Array, UInt64Array, UInt32Array, Float64Array, Float32Array, BooleanArray);
if let Some(a) = arr.as_any().downcast_ref::<StringArray>() {
return a.value(i).to_string();
}
String::new()
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use arrow_array::{Int64Array, StringArray};
use super::*;
fn cols() -> Vec<ArrowColumnRef> {
vec![
ArrowColumnRef { name: "name".into(), array: Arc::new(StringArray::from(vec!["knut", "korp"])) },
ArrowColumnRef { name: "n".into(), array: Arc::new(Int64Array::from(vec![1, 2])) },
]
}
/// The typed-transfer [`registry`] is process-wide, so any test that
/// `put_typed_inproc`/`clear_typed`/`paste_into`s it must not run concurrently
/// with another that does — otherwise one test's put/clear races the other's
/// put→paste window. Each such test takes this guard first to serialize them
/// (poison from an unrelated panic is recovered, not propagated).
fn registry_guard() -> std::sync::MutexGuard<'static, ()> {
static LOCK: Mutex<()> = Mutex::new(());
LOCK.lock().unwrap_or_else(|e| e.into_inner())
}
#[test]
fn datacolumns_render_as_tsv_for_the_text_fallback() {
let p = ClipPayload::DataColumns(cols());
assert_eq!(p.kind(), ClipKind::DataColumns);
assert_eq!(p.as_text(), "name\tn\nknut\t1\nkorp\t2");
}
#[test]
fn datacolumns_are_zero_copy_arc_shared() {
let original = cols();
let arr_ptr = Arc::as_ptr(&original[0].array) as *const ();
let payload = ClipPayload::DataColumns(original);
// The payload holds the SAME Arc, not a clone of the buffer.
if let ClipPayload::DataColumns(c) = &payload {
assert_eq!(Arc::as_ptr(&c[0].array) as *const (), arr_ptr, "column array must be Arc-shared, not copied");
} else {
panic!("wrong kind");
}
}
struct ColTarget {
last: Option<usize>,
text: Option<String>,
}
impl PasteTarget for ColTarget {
fn accepts(&self, k: ClipKind) -> bool {
matches!(k, ClipKind::DataColumns | ClipKind::Text)
}
fn paste_payload(&mut self, p: &ClipPayload) {
match p {
ClipPayload::DataColumns(c) => self.last = Some(c.len()),
ClipPayload::Text(s) => self.text = Some(s.clone()),
_ => {}
}
}
}
#[test]
fn typed_transfer_between_components_in_process() {
let _guard = registry_guard();
clear_typed();
// Source "copies" two typed columns.
put_typed_inproc(ClipPayload::DataColumns(cols()));
// Target accepts DataColumns → gets the typed payload, not text.
let mut t = ColTarget { last: None, text: None };
assert!(paste_into(&mut t));
assert_eq!(t.last, Some(2), "target received 2 typed columns");
assert!(t.text.is_none(), "richest accepted kind used, not the text fallback");
clear_typed();
}
#[test]
fn image_payload_transfers_to_a_viewer_in_process() {
let _guard = registry_guard();
clear_typed();
// A "video frame": a 2x2 RGBA image.
let img = egui::ColorImage::new(
[2, 2],
vec![egui::Color32::RED, egui::Color32::GREEN, egui::Color32::BLUE, egui::Color32::WHITE],
);
put_typed_inproc(ClipPayload::Image(img));
struct Viewer(Option<[usize; 2]>);
impl PasteTarget for Viewer {
fn accepts(&self, k: ClipKind) -> bool {
matches!(k, ClipKind::Image | ClipKind::Text)
}
fn paste_payload(&mut self, p: &ClipPayload) {
if let Some(img) = p.as_image() {
self.0 = Some(img.size);
}
}
}
let mut v = Viewer(None);
assert!(paste_into(&mut v));
assert_eq!(v.0, Some([2, 2]), "viewer received the typed image (a copied frame)");
clear_typed();
}
#[test]
fn text_is_the_universal_fallback() {
let _guard = registry_guard();
clear_typed();
put_typed_inproc(ClipPayload::DataColumns(cols()));
// A target that only accepts Text still pastes (gets the TSV view).
struct TextOnly(String);
impl PasteTarget for TextOnly {
fn accepts(&self, k: ClipKind) -> bool {
matches!(k, ClipKind::Text)
}
fn paste_payload(&mut self, p: &ClipPayload) {
if let ClipPayload::Text(s) = p {
self.0 = s.clone();
}
}
}
let mut t = TextOnly(String::new());
assert!(paste_into(&mut t));
assert_eq!(t.0, "name\tn\nknut\t1\nkorp\t2", "fell back to the TSV text view");
clear_typed();
}
}