Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Slide transitions: reading `p:transition` (also inside the
//! `mc:AlternateContent` PowerPoint writes for newer effects and exact
//! durations) and writing it at its schema position in `p:sld`
//! (`cSld`, `clrMapOvr`, `transition`, `timing`, `extLst`).
//!
//! Effects from ECMA-376 with a duration PowerPoint 2007 can express (fast,
//! medium, slow) are written as a plain `p:transition`. Other durations and
//! the PowerPoint 2010+ effects (`reveal`, `flash`; `morph` from 2016) are
//! written as `mc:AlternateContent`: a `p14` (or `p159`) choice with the
//! exact duration and effect, and a plain fallback (a fade for newer effects).
use crate::error::{Error, Result};
use crate::inspect::TransitionOutline;
use crate::model::presentation::Presentation;
use crate::model::shape::alternate_content_choice;
use crate::xml::{NodeId, Ns, XmlDoc};
/// The PowerPoint 2015 namespace of the morph transition.
const P159: &str = "http://schemas.microsoft.com/office/powerpoint/2015/09/main";
const P14: &str = "http://schemas.microsoft.com/office/powerpoint/2010/main";
const PML: &str = "http://schemas.openxmlformats.org/presentationml/2006/main";
const MC: &str = "http://schemas.openxmlformats.org/markup-compatibility/2006";
/// Longest transition PowerPoint accepts (59.99 s), rounded up.
const MAX_DURATION_MS: u32 = 60_000;
/// Durations of the `spd` presets (fast, medium, slow).
const PRESET_DURATIONS: [(u32, &str); 3] = [(500, "fast"), (750, "med"), (1000, "slow")];
/// Directions of effects that move along an edge or a corner.
const EIGHT_WAYS: &[&str] = &["l", "r", "u", "d", "lu", "ru", "ld", "rd"];
/// Effects `setTransition` writes, with their options (the first is the default).
const EFFECTS: &[(&str, &[&str])] = &[
("none", &[]),
("cut", &[]),
("fade", &["smooth", "black"]),
("push", &["l", "r", "u", "d"]),
("wipe", &["l", "r", "u", "d"]),
("split", &["horzOut", "horzIn", "vertOut", "vertIn"]),
("reveal", &["l", "r"]),
("randomBar", &["horz", "vert"]),
("shape", &["circle", "diamond", "plus"]),
("uncover", EIGHT_WAYS),
("cover", EIGHT_WAYS),
("zoom", &["in", "out"]),
("dissolve", &[]),
("flash", &[]),
("morph", &["byObject", "byWord", "byChar"]),
];
/// The extension namespace an effect needs.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Extension {
P14,
P159,
}
/// The requested changes of a `setTransition` operation.
pub(super) struct TransitionPatch<'a> {
pub kind: &'a str,
pub duration_ms: Option<u32>,
pub direction: Option<&'a str>,
pub advance_on_click: Option<bool>,
pub advance_after_ms: Option<Option<u32>>,
}
/// The transition of a slide part, if it has one.
pub(crate) fn read(doc: &XmlDoc) -> Option<TransitionOutline> {
let root = doc.root();
doc.children(root).find_map(|c| {
let t = transition_in(doc, c)?;
Some(parse(doc, t))
})
}
/// The `p:transition` a root child is or wraps (the branch the engine understands).
fn transition_in(doc: &XmlDoc, child: NodeId) -> Option<NodeId> {
if doc.is(child, Ns::P, "transition") {
return Some(child);
}
if doc.is(child, Ns::MC, "AlternateContent") {
let branch = alternate_content_choice(doc, child)?;
return doc
.children(branch)
.find(|&n| doc.is(n, Ns::P, "transition"));
}
None
}
/// Whether a root child is (or wraps) a transition, in any branch.
fn holds_transition(doc: &XmlDoc, child: NodeId) -> bool {
doc.is(child, Ns::P, "transition")
|| doc.is(child, Ns::MC, "AlternateContent")
&& doc
.children(child)
.any(|b| doc.children(b).any(|n| doc.is(n, Ns::P, "transition")))
}
fn parse(doc: &XmlDoc, t: NodeId) -> TransitionOutline {
let duration_ms = doc
.attr_ns(t, Ns::P14, "dur")
.and_then(|v| v.trim().parse::<u32>().ok())
.unwrap_or_else(|| match doc.attr(t, "spd") {
Some("slow") => 1000,
Some("med") => 750,
_ => 500,
});
let effect = doc
.children(t)
.find(|&c| !matches!(doc.local(c), "sndAc" | "extLst"));
let (kind, direction) = match effect {
Some(e) => describe(doc, e),
None => ("none".to_owned(), None),
};
TransitionOutline {
kind,
duration_ms,
direction,
advance_on_click: doc.attr_bool(t, "advClick").unwrap_or(true),
advance_after_ms: doc.attr_i64(t, "advTm").and_then(|v| u32::try_from(v).ok()),
}
}
/// The kind and option of an effect element.
fn describe(doc: &XmlDoc, e: NodeId) -> (String, Option<String>) {
let attr = |name: &str, default: &str| Some(doc.attr(e, name).unwrap_or(default).to_owned());
let local = doc.local(e);
let p159 = doc.ns_uri(doc.ns(e)) == Some(P159);
let (kind, direction) = match (doc.ns(e), local) {
(Ns::P, "cut") => ("cut", None),
(Ns::P, "fade") => {
let black = doc.attr_bool(e, "thruBlk").unwrap_or(false);
(
"fade",
Some(if black { "black" } else { "smooth" }.to_owned()),
)
}
(Ns::P, "push") => ("push", attr("dir", "l")),
(Ns::P, "wipe") => ("wipe", attr("dir", "l")),
(Ns::P, "split") => {
let orient = doc.attr(e, "orient").unwrap_or("horz");
let dir = match doc.attr(e, "dir").unwrap_or("out") {
"in" => "In",
_ => "Out",
};
("split", Some(format!("{orient}{dir}")))
}
(Ns::P14, "reveal") => ("reveal", attr("dir", "l")),
(Ns::P, "randomBar") => ("randomBar", attr("dir", "horz")),
(Ns::P, "circle" | "diamond" | "plus") => ("shape", Some(local.to_owned())),
(Ns::P, "pull") => ("uncover", attr("dir", "l")),
(Ns::P, "cover") => ("cover", attr("dir", "l")),
(Ns::P, "zoom") => ("zoom", attr("dir", "in")),
(Ns::P, "dissolve") => ("dissolve", None),
(Ns::P14, "flash") => ("flash", None),
(_, "morph") if p159 => ("morph", attr("option", "byObject")),
_ => (local, doc.attr(e, "dir").map(str::to_owned)),
};
(kind.to_owned(), direction)
}
/// The duration PowerPoint gives a new transition of this kind.
fn default_duration(kind: &str) -> u32 {
match kind {
"fade" => 700,
"morph" => 2000,
_ => 1000,
}
}
/// The full transition a patch asks for, given the slide's current one.
fn resolve(
patch: &TransitionPatch<'_>,
current: Option<&TransitionOutline>,
) -> Result<TransitionOutline> {
let kind = patch.kind.trim();
let Some(&(kind, options)) = EFFECTS.iter().find(|(k, _)| *k == kind) else {
let names: Vec<&str> = EFFECTS.iter().map(|(k, _)| *k).collect();
return Err(Error::InvalidEdit(format!(
"unknown transition `{kind}` (use one of {})",
names.join(", ")
)));
};
let same_kind = current.is_some_and(|c| c.kind == kind);
let direction = match patch.direction.map(str::trim).filter(|d| !d.is_empty()) {
Some(d) if options.is_empty() => {
return Err(Error::InvalidEdit(format!(
"the `{kind}` transition has no option `{d}`"
)));
}
Some(d) => {
if !options.contains(&d) {
return Err(Error::InvalidEdit(format!(
"unknown `{kind}` option `{d}` (use one of {})",
options.join(", ")
)));
}
Some(d.to_owned())
}
None if options.is_empty() => None,
None => current
.filter(|_| same_kind)
.and_then(|c| c.direction.clone())
.filter(|d| options.contains(&d.as_str()))
.or_else(|| options.first().map(|d| (*d).to_owned())),
};
let duration_ms = patch
.duration_ms
.or_else(|| current.filter(|c| c.kind != "none").map(|c| c.duration_ms))
.unwrap_or_else(|| default_duration(kind));
if duration_ms > MAX_DURATION_MS {
return Err(Error::InvalidEdit(format!(
"transition duration {duration_ms} ms is too long (at most {MAX_DURATION_MS})"
)));
}
Ok(TransitionOutline {
kind: kind.to_owned(),
duration_ms,
direction,
advance_on_click: patch
.advance_on_click
.or_else(|| current.map(|c| c.advance_on_click))
.unwrap_or(true),
advance_after_ms: match patch.advance_after_ms {
Some(v) => v,
None => current.and_then(|c| c.advance_after_ms),
},
})
}
/// Sets the transition of a slide (or, with `apply_to_all`, of every slide).
pub(super) fn set_transition(
pres: &mut Presentation,
slide: u32,
patch: &TransitionPatch<'_>,
apply_to_all: bool,
) -> Result<()> {
let part = pres.slide_part(slide)?;
let current = read(&*pres.xml(&part)?);
let transition = resolve(patch, current.as_ref())?;
let targets: Vec<String> = if apply_to_all {
pres.slides.iter().map(|s| s.part.clone()).collect()
} else {
vec![part]
};
for target in targets {
write(pres.xml_mut(&target)?, &transition)?;
}
Ok(())
}
/// The effect element (and the extension it needs) of a resolved transition.
fn effect_xml(t: &TransitionOutline) -> (String, Option<Extension>) {
let dir = t.direction.as_deref().unwrap_or("");
let directed = |name: &str| format!("<p:{name} dir=\"{dir}\"/>");
match t.kind.as_str() {
"cut" => ("<p:cut/>".into(), None),
"fade" if dir == "black" => ("<p:fade thruBlk=\"1\"/>".into(), None),
"fade" => ("<p:fade/>".into(), None),
"push" | "wipe" | "cover" | "randomBar" | "zoom" => (directed(&t.kind), None),
"uncover" => (directed("pull"), None),
"split" => {
let (orient, way) = dir.split_at(4);
(
format!(
"<p:split orient=\"{orient}\" dir=\"{}\"/>",
way.to_ascii_lowercase()
),
None,
)
}
"reveal" => (format!("<p14:reveal dir=\"{dir}\"/>"), Some(Extension::P14)),
"shape" => (format!("<p:{dir}/>"), None),
"dissolve" => ("<p:dissolve/>".into(), None),
"flash" => ("<p14:flash/>".into(), Some(Extension::P14)),
"morph" => (
format!("<p159:morph option=\"{dir}\"/>"),
Some(Extension::P159),
),
_ => (String::new(), None),
}
}
/// The markup of a resolved transition (`None` when the slide needs none).
fn transition_xml(t: &TransitionOutline) -> Option<String> {
let mut advance = String::new();
if !t.advance_on_click {
advance.push_str(" advClick=\"0\"");
}
if let Some(ms) = t.advance_after_ms {
advance.push_str(&format!(" advTm=\"{ms}\""));
}
if t.kind == "none" {
return (!advance.is_empty())
.then(|| format!("<p:transition xmlns:p=\"{PML}\"{advance}/>"));
}
let (effect, extension) = effect_xml(t);
let preset = PRESET_DURATIONS
.iter()
.find(|(ms, _)| *ms == t.duration_ms)
.map(|(_, spd)| *spd);
let spd = preset.unwrap_or(match t.duration_ms {
0..=625 => "fast",
626..=875 => "med",
_ => "slow",
});
if extension.is_none() && preset.is_some() {
return Some(format!(
"<p:transition xmlns:p=\"{PML}\" spd=\"{spd}\"{advance}>{effect}</p:transition>"
));
}
let (requires, declarations) = match extension {
Some(Extension::P159) => (
"p159",
format!(" xmlns:p14=\"{P14}\" xmlns:p159=\"{P159}\""),
),
_ => ("p14", format!(" xmlns:p14=\"{P14}\"")),
};
let fallback = if extension.is_some() {
"<p:fade/>"
} else {
effect.as_str()
};
Some(format!(
"<mc:AlternateContent xmlns:mc=\"{MC}\" xmlns:p=\"{PML}\"><mc:Choice{declarations} Requires=\"{requires}\"><p:transition spd=\"{spd}\" p14:dur=\"{}\"{advance}>{effect}</p:transition></mc:Choice><mc:Fallback><p:transition spd=\"{spd}\"{advance}>{fallback}</p:transition></mc:Fallback></mc:AlternateContent>",
t.duration_ms
))
}
/// The local name of a root child, looking inside `mc:AlternateContent`.
pub(super) fn wrapped_local(doc: &XmlDoc, child: NodeId) -> &str {
if doc.is(child, Ns::MC, "AlternateContent") {
return doc
.first_child(child)
.and_then(|b| doc.first_child(b))
.map_or("", |n| doc.local(n));
}
doc.local(child)
}
/// Replaces a slide's transition with `t` (removing it for `none`).
fn write(doc: &mut XmlDoc, t: &TransitionOutline) -> Result<()> {
let root = doc.root();
let old: Vec<NodeId> = doc
.children(root)
.filter(|&c| holds_transition(doc, c))
.collect();
for o in old {
doc.detach(o);
}
let Some(xml) = transition_xml(t) else {
return Ok(());
};
let fragment = XmlDoc::parse(xml.as_bytes(), "transition")?;
let node = doc.import_verbatim(&fragment, fragment.root());
let before = doc
.children(root)
.find(|&c| matches!(wrapped_local(doc, c), "timing" | "extLst"));
match before {
Some(b) => doc.insert_before(b, node),
None => doc.append_child(root, node),
}
let mut scoped = vec![node];
scoped.extend(doc.children(node));
for n in scoped {
doc.drop_redundant_ns_decls(n);
}
Ok(())
}
#[cfg(test)]
mod test;