From 6eac1d353dd5b1ade38f6c08b0ecc8935848e3a0 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 02:27:50 +0000 Subject: [PATCH 1/3] Add neutral XFL shape hint schema views --- crates/xfl/src/lib.rs | 2 + crates/xfl/src/shape_hints.rs | 127 ++++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+) create mode 100644 crates/xfl/src/shape_hints.rs diff --git a/crates/xfl/src/lib.rs b/crates/xfl/src/lib.rs index d4cfc73e1..283e10ef5 100644 --- a/crates/xfl/src/lib.rs +++ b/crates/xfl/src/lib.rs @@ -33,6 +33,8 @@ pub mod filters; pub mod media; /// Borrowed views of native XFL shape and style elements. pub mod shape; +/// Borrowed views of native XFL shape-hint records. +pub mod shape_hints; /// Largest single entry inflated (bytes). pub const MAX_ENTRY: usize = 256 * 1024 * 1024; diff --git a/crates/xfl/src/shape_hints.rs b/crates/xfl/src/shape_hints.rs new file mode 100644 index 000000000..0a9e99d42 --- /dev/null +++ b/crates/xfl/src/shape_hints.rs @@ -0,0 +1,127 @@ +//! Borrowed views of native XFL shape-hint records. +//! +//! These parse the native point encodings and hint ordering. Snapping points onto consumer +//! geometry and pairing start/end keyframes remain application responsibilities. + +use crate::shape::XflElement; + +/// A native XFL point in document coordinates. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Point { + pub x: f32, + pub y: f32, +} + +/// The optional `` wrapper on a keyframe. +#[derive(Clone, Copy, Debug)] +pub struct ShapeHints<'a, E: XflElement> { + wrapper: Option<&'a E>, +} + +impl<'a, E: XflElement> ShapeHints<'a, E> { + pub fn new(keyframe: &'a E) -> Self { + Self { wrapper: keyframe.child("shapeHints") } + } + + pub fn is_empty(&self) -> bool { + self.wrapper.is_none_or(|wrapper| wrapper.elements().next().is_none()) + } + + /// Records in source order; unrecognized child names are retained because the legacy reader + /// interpreted their point and ordering attributes too. + pub fn iter(&self) -> impl Iterator> + 'a { + let wrapper = self.wrapper; + wrapper.into_iter().flat_map(XflElement::elements).map(|element| ShapeHint { element }) + } +} + +/// One native shape-hint record. +#[derive(Clone, Copy, Debug)] +pub struct ShapeHint<'a, E: XflElement> { + element: &'a E, +} + +impl<'a, E: XflElement> ShapeHint<'a, E> { + /// Native numeric order, or its single-letter `name` fallback (`a` is zero). + pub fn index(&self) -> Option { + integer(self.element, "index").map(|value| value as usize).or_else(|| self.element.attr("name").and_then(letter_index)) + } + + /// The keyframe's point, in either joined or separate native coordinate attributes. + pub fn start_point(&self) -> Option { + read_point(self.element, "startPoint", "startX", "startY").or_else(|| read_point(self.element, "point", "x", "y")) + } + + /// The next keyframe's point, when the record contains one. + pub fn end_point(&self) -> Option { + read_point(self.element, "endPoint", "endX", "endY") + } +} + +fn letter_index(name: &str) -> Option { + let [byte] = name.as_bytes() else { return None }; + match byte.to_ascii_lowercase() { + b'a'..=b'z' => Some((byte.to_ascii_lowercase() - b'a') as usize), + _ => None, + } +} + +fn read_point(element: &impl XflElement, joined: &str, x: &str, y: &str) -> Option { + let point = match element.attr(joined) { + Some(value) => { + let mut values = value.split([',', ' ']).filter(|part| !part.trim().is_empty()).map(|part| part.trim().parse::().ok()); + Point { x: values.next()??, y: values.next()?? } + } + None => Point { x: number(element, x)?, y: number(element, y)? }, + }; + (point.x.is_finite() && point.y.is_finite()).then_some(point) +} + +fn number(element: &impl XflElement, name: &str) -> Option { + element.attr(name)?.trim().parse::().ok().filter(|value| value.is_finite()) +} + +fn integer(element: &impl XflElement, name: &str) -> Option { + element.attr(name)?.trim().parse::().ok() +} + +#[cfg(test)] +mod tests { + use super::*; + + fn parse(source: &[u8]) -> craft_xml::El { + craft_xml::parse(source).expect("well-formed test XML") + } + + #[test] + fn reads_joined_and_split_native_points_in_source_order() { + let keyframe = parse(br#""#); + let hints = ShapeHints::new(&keyframe); + assert!(!hints.is_empty()); + let records: Vec<_> = hints.iter().collect(); + assert_eq!(records[0].index(), Some(1)); + assert_eq!(records[0].start_point(), Some(Point { x: 12.5, y: -2.0 })); + assert_eq!(records[0].end_point(), Some(Point { x: 30.0, y: 40.0 })); + assert_eq!(records[1].index(), Some(0)); + assert_eq!(records[1].start_point(), Some(Point { x: 1.0, y: 2.0 })); + assert_eq!(records[1].end_point(), Some(Point { x: 3.0, y: 4.0 })); + } + + #[test] + fn malformed_joined_values_fall_back_to_the_other_native_point_field() { + let keyframe = parse(br#""#); + let hint = ShapeHints::new(&keyframe).iter().next().expect("hint record"); + assert_eq!(hint.index(), Some(25)); + assert_eq!(hint.start_point(), Some(Point { x: 7.0, y: 8.0 })); + assert_eq!(hint.end_point(), None); + } + + #[test] + fn missing_lists_and_non_letter_names_remain_optional() { + let keyframe = parse(b""); + assert!(ShapeHints::new(&keyframe).is_empty()); + let keyframe = parse(br#""#); + let hint = ShapeHints::new(&keyframe).iter().next().expect("hint record"); + assert_eq!(hint.index(), None); + } +} From bb0c1c52ce25c2e051717916b489912f5105833e Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 02:34:02 +0000 Subject: [PATCH 2/3] Add neutral XFL tween schema views --- crates/xfl/src/lib.rs | 2 + crates/xfl/src/tween.rs | 125 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+) create mode 100644 crates/xfl/src/tween.rs diff --git a/crates/xfl/src/lib.rs b/crates/xfl/src/lib.rs index 283e10ef5..6b43420e2 100644 --- a/crates/xfl/src/lib.rs +++ b/crates/xfl/src/lib.rs @@ -35,6 +35,8 @@ pub mod media; pub mod shape; /// Borrowed views of native XFL shape-hint records. pub mod shape_hints; +/// Borrowed views of native XFL tween and custom-ease records. +pub mod tween; /// Largest single entry inflated (bytes). pub const MAX_ENTRY: usize = 256 * 1024 * 1024; diff --git a/crates/xfl/src/tween.rs b/crates/xfl/src/tween.rs new file mode 100644 index 000000000..753be73d1 --- /dev/null +++ b/crates/xfl/src/tween.rs @@ -0,0 +1,125 @@ +//! Borrowed views of native XFL frame-tween and custom-ease records. +//! +//! This parses the native attributes and point lists. Interpreting easing curves and applying +//! them to an application's timeline model remain consumer responsibilities. + +use crate::shape::XflElement; + +/// Native motion/shape tween settings on a `DOMFrame`. +#[derive(Clone, Copy, Debug)] +pub struct FrameTween<'a, E: XflElement> { + frame: &'a E, +} + +impl<'a, E: XflElement> FrameTween<'a, E> { + pub fn new(frame: &'a E) -> Self { + Self { frame } + } + + /// The classic slider value, when present and finite. + pub fn acceleration(&self) -> Option { + number(self.frame, "acceleration") + } + + pub fn has_custom_ease(&self) -> Option { + boolean(self.frame, "hasCustomEase") + } + + /// Animate's default is a single curve unless this is explicitly false. + pub fn use_single_ease_curve(&self) -> Option { + boolean(self.frame, "useSingleEaseCurve") + } + + pub fn orient_to_path(&self) -> Option { + boolean(self.frame, "motionTweenOrientToPath") + } + + /// Raw native rotation setting; interpretation stays in the consuming application. + pub fn rotate(&self) -> Option<&'a str> { + self.frame.attr("motionTweenRotate") + } + + /// Custom ease curves in source order; unknown tween entries are skipped. + pub fn custom_eases(&self) -> impl Iterator> + 'a { + self.frame.child("tweens").into_iter().flat_map(|wrapper| wrapper.elements_named("CustomEase")).map(|element| CustomEase { element }) + } +} + +/// A native custom-ease curve. +#[derive(Clone, Copy, Debug)] +pub struct CustomEase<'a, E: XflElement> { + element: &'a E, +} + +impl<'a, E: XflElement> CustomEase<'a, E> { + /// The property-group name, defaulting to `all` in XFL. + pub fn target(&self) -> &'a str { + self.element.attr("target").map(str::trim).unwrap_or("all") + } + + pub fn points(&self) -> impl Iterator> + 'a { + self.element.elements_named("Point").map(|element| EasePoint { element }) + } +} + +/// One native custom-ease point. +#[derive(Clone, Copy, Debug)] +pub struct EasePoint<'a, E: XflElement> { + element: &'a E, +} + +impl EasePoint<'_, E> { + pub fn x(&self) -> Option { + number(self.element, "x") + } + + pub fn y(&self) -> Option { + number(self.element, "y") + } +} + +fn number(element: &impl XflElement, name: &str) -> Option { + element.attr(name)?.trim().parse::().ok().filter(|value| value.is_finite()) +} + +fn boolean(element: &impl XflElement, name: &str) -> Option { + element.attr(name).map(|value| value.trim() == "true") +} + +#[cfg(test)] +mod tests { + use super::*; + + fn parse(source: &[u8]) -> craft_xml::El { + craft_xml::parse(source).expect("well-formed test XML") + } + + #[test] + fn reads_frame_tween_settings_and_custom_eases_in_order() { + let frame = parse( + br#""#, + ); + let tween = FrameTween::new(&frame); + assert_eq!(tween.acceleration(), Some(-45.0)); + assert_eq!(tween.has_custom_ease(), Some(true)); + assert_eq!(tween.use_single_ease_curve(), Some(false)); + assert_eq!(tween.orient_to_path(), Some(true)); + assert_eq!(tween.rotate(), Some("clockwise")); + let curves: Vec<_> = tween.custom_eases().collect(); + assert_eq!(curves.len(), 2); + assert_eq!(curves[0].target(), "position"); + assert_eq!(curves[0].points().map(|point| (point.x(), point.y())).collect::>(), [(Some(0.0), Some(0.0)), (Some(0.5), Some(0.25))]); + assert_eq!(curves[1].target(), "all"); + assert_eq!(curves[1].points().next().map(|point| (point.x(), point.y())), Some((Some(1.0), Some(1.0)))); + } + + #[test] + fn absent_and_malformed_values_remain_optional() { + let frame = parse(br#""#); + let tween = FrameTween::new(&frame); + assert_eq!(tween.acceleration(), None); + assert_eq!(tween.has_custom_ease(), Some(false)); + assert_eq!(tween.use_single_ease_curve(), Some(false)); + assert!(tween.custom_eases().next().is_none()); + } +} From 01815214d62e9f45f9cd4883eb6590d4939ded62 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 02:46:16 +0000 Subject: [PATCH 3/3] Reuse XFL wire scalar parsers --- crates/xfl/src/shape.rs | 6 +++--- crates/xfl/src/shape_hints.rs | 10 +--------- crates/xfl/src/tween.rs | 10 +--------- 3 files changed, 5 insertions(+), 21 deletions(-) diff --git a/crates/xfl/src/shape.rs b/crates/xfl/src/shape.rs index bcd3e9373..6077b17a9 100644 --- a/crates/xfl/src/shape.rs +++ b/crates/xfl/src/shape.rs @@ -93,15 +93,15 @@ impl Matrix { pub const IDENTITY: Matrix = Matrix { a: 1.0, b: 0.0, c: 0.0, d: 1.0, tx: 0.0, ty: 0.0 }; } -fn number(element: &impl XflElement, name: &str) -> Option { +pub(crate) fn number(element: &impl XflElement, name: &str) -> Option { element.attr(name)?.trim().parse::().ok().filter(|value| value.is_finite()) } -fn integer(element: &impl XflElement, name: &str) -> Option { +pub(crate) fn integer(element: &impl XflElement, name: &str) -> Option { element.attr(name)?.trim().parse::().ok() } -fn boolean(element: &impl XflElement, name: &str) -> Option { +pub(crate) fn boolean(element: &impl XflElement, name: &str) -> Option { element.attr(name).map(|value| value.trim() == "true") } diff --git a/crates/xfl/src/shape_hints.rs b/crates/xfl/src/shape_hints.rs index 0a9e99d42..681e0c5a9 100644 --- a/crates/xfl/src/shape_hints.rs +++ b/crates/xfl/src/shape_hints.rs @@ -3,7 +3,7 @@ //! These parse the native point encodings and hint ordering. Snapping points onto consumer //! geometry and pairing start/end keyframes remain application responsibilities. -use crate::shape::XflElement; +use crate::shape::{XflElement, integer, number}; /// A native XFL point in document coordinates. #[derive(Clone, Copy, Debug, PartialEq)] @@ -77,14 +77,6 @@ fn read_point(element: &impl XflElement, joined: &str, x: &str, y: &str) -> Opti (point.x.is_finite() && point.y.is_finite()).then_some(point) } -fn number(element: &impl XflElement, name: &str) -> Option { - element.attr(name)?.trim().parse::().ok().filter(|value| value.is_finite()) -} - -fn integer(element: &impl XflElement, name: &str) -> Option { - element.attr(name)?.trim().parse::().ok() -} - #[cfg(test)] mod tests { use super::*; diff --git a/crates/xfl/src/tween.rs b/crates/xfl/src/tween.rs index 753be73d1..a894d5c29 100644 --- a/crates/xfl/src/tween.rs +++ b/crates/xfl/src/tween.rs @@ -3,7 +3,7 @@ //! This parses the native attributes and point lists. Interpreting easing curves and applying //! them to an application's timeline model remain consumer responsibilities. -use crate::shape::XflElement; +use crate::shape::{XflElement, boolean, number}; /// Native motion/shape tween settings on a `DOMFrame`. #[derive(Clone, Copy, Debug)] @@ -78,14 +78,6 @@ impl EasePoint<'_, E> { } } -fn number(element: &impl XflElement, name: &str) -> Option { - element.attr(name)?.trim().parse::().ok().filter(|value| value.is_finite()) -} - -fn boolean(element: &impl XflElement, name: &str) -> Option { - element.attr(name).map(|value| value.trim() == "true") -} - #[cfg(test)] mod tests { use super::*;