88f5a00e389b
captions.rs
//! Object › Captions › Generate Static Caption: a text frame beside each selected object, filled
//! from its metadata.
use designcraft_doc::{Document, Item, ItemId, ParaFormat, Selection};
use designcraft_geom::Rect;
use serde_json::{Value, json};
use super::{CommandSpec, bad, cmd, has_selection, str_param, targets};
use crate::{Result, Session};
pub fn specs() -> Vec<CommandSpec> {
vec![cmd!(
"object.caption",
"Generate Static Caption",
["Object", "Captions"],
None,
"{text?: template (default \"{name}\"; variables {name} {path} {altText} {label} {ppi} {dimensions} {format}), position?: below|above|left|right, offset? (pt, 0), height? (pt, 24), style?: paragraph style, live?: bool (kept current as the source changes), ids?} → {ids}",
has_selection,
caption
)]
}
/// The metadata variables of `it`.
fn variable(d: &Document, it: &Item, xf: designcraft_geom::Affine, name: &str) -> String {
let g = it.graphic();
let asset = g.and_then(|g| d.assets.get(&g.asset));
match name {
"name" => asset.map(|a| a.name.clone()).unwrap_or_default(),
"path" => asset.and_then(|a| a.link.clone()).unwrap_or_default(),
"altText" => it.alt_text.clone(),
"label" => it.label.clone(),
"format" => asset.map(|a| a.mime.rsplit('/').next().unwrap_or("").to_uppercase()).unwrap_or_default(),
"dimensions" => asset.and_then(|a| a.pixels).map(|(w, h)| format!("{w} × {h}")).unwrap_or_default(),
"ppi" => match (g, asset.and_then(|a| a.pixels)) {
(Some(g), Some((w, _))) if g.size.0 > 0.0 => {
let m = (xf * g.xf).as_coeffs();
let scale = m[0].hypot(m[1]);
let inches = g.size.0 * scale / 72.0;
if inches > 0.0 { format!("{}", (w as f64 / inches).round()) } else { String::new() }
}
_ => String::new(),
},
_ => String::new(),
}
}
pub(crate) fn fill(d: &Document, it: &Item, xf: designcraft_geom::Affine, template: &str) -> String {
let mut out = String::new();
let mut rest = template;
while let Some(i) = rest.find('{') {
out.push_str(&rest[..i]);
match rest[i..].find('}') {
Some(j) => {
out.push_str(&variable(d, it, xf, &rest[i + 1..i + j]));
rest = &rest[i + j + 1..];
}
None => {
out.push_str(&rest[i..]);
rest = "";
}
}
}
out.push_str(rest);
out
}
fn caption(s: &mut Session, p: &Value) -> Result<Value> {
const ID: &str = "object.caption";
let ids = targets(s, p)?;
let template = str_param(p, "text").unwrap_or("{name}").to_string();
let pos = str_param(p, "position").unwrap_or("below").to_string();
if !["below", "above", "left", "right"].contains(&pos.as_str()) {
return Err(bad(ID, format!("unknown position `{pos}`")));
}
let offset = p.get("offset").and_then(Value::as_f64).unwrap_or(0.0);
let height = p.get("height").and_then(Value::as_f64).unwrap_or(24.0).max(1.0);
let style = str_param(p, "style").map(str::to_string);
let live = p.get("live").and_then(Value::as_bool).unwrap_or(false);
if let Some(st) = &style
&& s.doc()?.doc.styles.para(st).is_none()
{
return Err(bad(ID, format!("no paragraph style `{st}`")));
}
let lid = s.doc()?.active_layer;
s.edit(|d, sel| {
let mut made = Vec::new();
for id in &ids {
let Some(loc) = d.find(*id) else { continue };
let Some(it) = d.item_at(&loc) else { continue };
let xf = d.parent_xf(&loc) * it.xf;
let b = xf.transform_rect_bbox(it.inner_bounds());
let text = fill(d, it, xf, &template);
let r = match pos.as_str() {
"above" => Rect::new(b.x0, b.y0 - offset - height, b.x1, b.y0 - offset),
"left" => Rect::new(b.x0 - offset - 144.0, b.y0, b.x0 - offset, b.y1),
"right" => Rect::new(b.x1 + offset, b.y0, b.x1 + offset + 144.0, b.y1),
_ => Rect::new(b.x0, b.y1 + offset, b.x1, b.y1 + offset + height),
};
let para = ParaFormat { style: style.clone().unwrap_or_else(|| d.styles.default_paragraph.clone()), ..Default::default() };
let source = *id;
let (cid, _) = d.add_text_frame(loc.spread, r, lid, &text, para)?;
if live && let Some(c) = d.item_mut(cid) {
c.live_caption = Some(designcraft_doc::LiveCaption { source, template: template.clone() });
}
made.push(cid);
}
if made.is_empty() {
return Err(bad(ID, "nothing to caption"));
}
*sel = Selection::items(made.clone());
Ok(json!({"ids": made.iter().map(|i: &ItemId| i.0).collect::<Vec<_>>()}))
})
}
/// Whether any item on the document spreads, inside groups included, is a live caption: the
/// items [`refresh_live`] visits.
pub(crate) fn has_live(d: &Document) -> bool {
let mut found = false;
for it in d.spreads.iter().flat_map(|sp| &sp.items) {
it.walk(&mut |i| found |= i.live_caption.is_some());
if found {
return true;
}
}
false
}
/// Bring live captions up to date with their source objects (the text frame's story is
/// replaced when its text changed; a caption whose source is gone keeps its last text).
pub(crate) fn refresh_live(d: &mut Document) -> bool {
let mut todo = Vec::new();
for id in d.all_items() {
let Some(c) = d.item(id) else { continue };
let (Some(lc), Some(tf)) = (&c.live_caption, c.text_frame()) else { continue };
let (Some(loc), Some(src)) = (d.find(lc.source), d.item(lc.source)) else { continue };
let text = fill(d, src, d.parent_xf(&loc) * src.xf, &lc.template);
if d.story(tf.story).is_some_and(|st| st.text != text) {
todo.push((tf.story, text));
}
}
let changed = !todo.is_empty();
for (sid, text) in todo {
if let Some(st) = d.story_mut(sid) {
let len = st.len();
st.replace(0..len, &text);
}
d.prune_story_text_ranges(sid);
}
changed
}
/// Keep a text selection inside its story after `refresh_live` replaced the story's text.
pub(crate) fn clamp_text_selection(d: &Document, sel: &mut Selection) {
if let Some(ts) = sel.text.as_mut()
&& ts.cell.is_none()
&& let Some(st) = d.story(ts.story)
{
ts.anchor = designcraft_doc::floor_char_boundary(&st.text, ts.anchor);
ts.focus = designcraft_doc::floor_char_boundary(&st.text, ts.focus);
}
}
#[cfg(test)]
mod tests {
use serde_json::json;
use crate::Session;
#[test]
fn static_caption_from_metadata() {
let mut s = Session::new();
s.execute("file.new", &json!({})).unwrap();
let a = s.execute("frame.create", &json!({"rect": [72, 72, 272, 172]})).unwrap()["id"].as_u64().unwrap();
s.execute("object.altText", &json!({"text": "Harbour at dawn", "ids": [a]})).unwrap();
s.execute("object.label", &json!({"label": "fig-1", "ids": [a]})).unwrap();
let r = s.execute("object.caption", &json!({"ids": [a], "text": "Figure {label}: {altText}", "offset": 6})).unwrap();
let cid = designcraft_doc::ItemId(r["ids"][0].as_u64().unwrap());
let d = &s.doc().unwrap().doc;
let c = d.item(cid).unwrap();
let b = c.bounds();
assert_eq!((b.x0, b.y0, b.x1), (72.0, 178.0, 272.0));
let sid = c.text_frame().unwrap().story;
assert_eq!(d.stories[&sid].text, "Figure fig-1: Harbour at dawn");
assert!(s.execute("object.caption", &json!({"ids": [a], "position": "sideways"})).is_err());
}
#[test]
fn live_caption_follows_its_source() {
let mut s = Session::new();
s.execute("file.new", &json!({})).unwrap();
let a = s.execute("frame.create", &json!({"rect": [72, 72, 272, 172]})).unwrap()["id"].as_u64().unwrap();
s.execute("object.altText", &json!({"text": "First", "ids": [a]})).unwrap();
let r = s.execute("object.caption", &json!({"ids": [a], "text": "Photo: {altText}", "live": true})).unwrap();
let cid = designcraft_doc::ItemId(r["ids"][0].as_u64().unwrap());
let text = |s: &Session| {
let d = &s.doc().unwrap().doc;
d.stories[&d.item(cid).unwrap().text_frame().unwrap().story].text.clone()
};
assert_eq!(text(&s), "Photo: First");
s.execute("object.altText", &json!({"text": "Second", "ids": [a]})).unwrap();
assert_eq!(text(&s), "Photo: Second", "updated with the source");
s.execute("edit.undo", &json!({})).unwrap();
assert_eq!(text(&s), "Photo: First", "one undo step for both");
}
#[test]
fn live_caption_follows_a_committed_gesture() {
let mut s = Session::new();
s.execute("file.new", &json!({})).unwrap();
let a = s.execute("frame.create", &json!({"rect": [72, 72, 272, 172]})).unwrap()["id"].as_u64().unwrap();
s.execute("object.altText", &json!({"text": "First", "ids": [a]})).unwrap();
let r = s.execute("object.caption", &json!({"ids": [a], "text": "Photo: {altText}", "live": true})).unwrap();
let cid = designcraft_doc::ItemId(r["ids"][0].as_u64().unwrap());
let text = |s: &Session| {
let d = &s.doc().unwrap().doc;
d.stories[&d.item(cid).unwrap().text_frame().unwrap().story].text.clone()
};
s.begin_interaction("Alt Text").unwrap();
s.preview("object.altText", json!({"text": "Second", "ids": [a]})).unwrap();
let revision = s.doc().unwrap().revision;
s.commit_interaction().unwrap();
assert_eq!(text(&s), "Photo: Second", "updated when the gesture commits");
assert_ne!(s.doc().unwrap().revision, revision, "caches keyed by the revision draw the new caption");
s.execute("edit.undo", &json!({})).unwrap();
assert_eq!(text(&s), "Photo: First", "one undo step for both");
}
#[test]
fn auto_sized_live_caption_fits_a_committed_gesture() {
let mut s = Session::new();
s.execute("file.new", &json!({})).unwrap();
let a = s.execute("frame.create", &json!({"rect": [72, 72, 272, 172]})).unwrap()["id"].as_u64().unwrap();
s.execute("object.altText", &json!({"text": "First", "ids": [a]})).unwrap();
let r = s.execute("object.caption", &json!({"ids": [a], "text": "Photo: {altText}", "live": true})).unwrap();
let cid = r["ids"][0].as_u64().unwrap();
s.execute("object.textFrameOptions", &json!({"ids": [cid], "autoSize": "heightOnly"})).unwrap();
let height = |s: &Session| s.doc().unwrap().doc.item(designcraft_doc::ItemId(cid)).unwrap().bounds().height();
let short = height(&s);
let long = "A harbour at dawn, with the fishing boats coming in one after another past the lighthouse and the long stone pier";
s.begin_interaction("Alt Text").unwrap();
s.preview("object.altText", json!({"text": long, "ids": [a]})).unwrap();
s.commit_interaction().unwrap();
assert!(height(&s) > short + 5.0, "the caption frame grows with its text: {short} -> {}", height(&s));
}
#[test]
fn grouped_live_caption_follows_its_source() {
let mut s = Session::new();
s.execute("file.new", &json!({})).unwrap();
let a = s.execute("frame.create", &json!({"rect": [72, 72, 272, 172]})).unwrap()["id"].as_u64().unwrap();
let b = s.execute("frame.create", &json!({"rect": [300, 72, 400, 172]})).unwrap()["id"].as_u64().unwrap();
s.execute("object.altText", &json!({"text": "First", "ids": [a]})).unwrap();
let r = s.execute("object.caption", &json!({"ids": [a], "text": "Photo: {altText}", "live": true})).unwrap();
let cid = designcraft_doc::ItemId(r["ids"][0].as_u64().unwrap());
// The only live caption sits inside a group, not at the top of the spread.
s.execute("object.group", &json!({"ids": [cid.0, b]})).unwrap();
let text = |s: &Session| {
let d = &s.doc().unwrap().doc;
d.stories[&d.item(cid).unwrap().text_frame().unwrap().story].text.clone()
};
s.execute("object.altText", &json!({"text": "Second", "ids": [a]})).unwrap();
assert_eq!(text(&s), "Photo: Second", "updated by a command");
s.begin_interaction("Alt Text").unwrap();
s.preview("object.altText", json!({"text": "Third", "ids": [a]})).unwrap();
s.commit_interaction().unwrap();
assert_eq!(text(&s), "Photo: Third", "updated when the gesture commits");
}
/// A session with a live caption reading "Photo: First" and the caret at its end.
fn caret_at_end_of_live_caption() -> (Session, designcraft_doc::StoryId) {
let mut s = Session::new();
s.execute("file.new", &json!({})).unwrap();
let a = s.execute("frame.create", &json!({"rect": [72, 72, 272, 172]})).unwrap()["id"].as_u64().unwrap();
s.execute("object.altText", &json!({"text": "First", "ids": [a]})).unwrap();
let r = s.execute("object.caption", &json!({"ids": [a], "text": "Photo: {altText}", "live": true})).unwrap();
let cid = designcraft_doc::ItemId(r["ids"][0].as_u64().unwrap());
let sid = s.doc().unwrap().doc.item(cid).unwrap().text_frame().unwrap().story;
let len = "Photo: First".len();
s.execute("text.select", &json!({"story": sid.0, "anchor": len, "focus": len})).unwrap();
(s, sid)
}
fn assert_caret_inside(s: &Session, sid: designcraft_doc::StoryId) {
let st = s.doc().unwrap();
let len = st.doc.stories[&sid].text.len();
let ts = st.selection.text.unwrap();
assert!(ts.anchor <= len && ts.focus <= len, "caret {}..{} past the end of {len} bytes", ts.anchor, ts.focus);
assert!(s.ime_text_context().is_some(), "the caret still describes its text");
}
#[test]
fn caret_stays_inside_a_live_caption_that_discards_typing() {
let (mut s, sid) = caret_at_end_of_live_caption();
s.execute("text.insert", &json!({"text": " and more"})).unwrap();
assert_eq!(s.doc().unwrap().doc.stories[&sid].text, "Photo: First");
assert_caret_inside(&s, sid);
}
#[test]
fn caret_stays_inside_a_live_caption_after_a_committed_gesture() {
let (mut s, sid) = caret_at_end_of_live_caption();
s.begin_interaction("Typing").unwrap();
s.preview("text.insert", json!({"text": " and more"})).unwrap();
s.commit_interaction().unwrap();
assert_eq!(s.doc().unwrap().doc.stories[&sid].text, "Photo: First");
assert_caret_inside(&s, sid);
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.