drawingml 1.0.0

//! In-memory model for the shared DrawingML content this crate covers — shape geometry, colors,
//! fills, and line/stroke properties. Structurally, this is `CT_ShapeProperties` (`dml-main.xsd`,
//! ECMA-376/ISO-IEC 29500-1), the type behind `<a:spPr>` wherever it appears (`<xdr:spPr>` in
//! SpreadsheetML, `<wps:spPr>`/`<pic:spPr>` in WordprocessingML, `<p:spPr>` in PresentationML) —
//! see the crate-level doc comment in `lib.rs` for why only this content is modeled here, never the
//! surrounding anchor/container, which stays host-specific.
//!
//! Covers geometry, colors, fills, lines, text-in-shape, and image fills (`blipFill`) — see
//! `lib.rs`'s crate-level doc comment for exactly what is/isn't modeled.

/// A shape's visual properties (`<a:spPr>`, `CT_ShapeProperties`): local position/size, geometry,
/// fill, and line. Everything about how a shape *looks*, independent of where it is anchored in its
/// host document (that part is never modeled here — see the crate-level doc comment).
///
/// Not modeled: 3D (`a:scene3d`/`a:sp3d`) — `EG_EffectProperties`'s `<a:effectLst>` choice
/// (shadow/glow/reflection/soft edge) *is* modeled, see [`EffectList`], point 10; its sibling
/// choice `<a:effectDag>` (an effect *graph*, letting effects reference each other's output — a
/// materially more complex, rarely-authored mechanism) is not. `bwMode` (black-and-white print
/// override) is not modeled either — a rarely-used printing hint.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct ShapeProperties {
    /// `<a:xfrm>` — position, size, rotation, flipping.
    pub transform: Option<Transform2D>,
    /// `EG_Geometry` (`<a:prstGeom>`/`<a:custGeom>`) — the shape's outline.
    pub geometry: Option<Geometry>,
    /// `EG_FillProperties` (`<a:noFill>`/`<a:solidFill>`/`<a:gradFill>`/
    /// `<a:pattFill>`/`<a:blipFill>`/`<a:grpFill>`) — how the shape's interior is painted.
    pub fill: Option<Fill>,
    /// `<a:ln>` — the shape's outline stroke.
    pub line: Option<Line>,
    /// `<a:effectLst>` — shadow/glow/reflection/soft-edge effects.
    pub effects: Option<EffectList>,
    /// `<a:prstGeom>`'s own `<a:avLst>` (`CT_GeomGuideList`) — adjustment handle values for a
    /// preset shape (a rounded rectangle's corner radius, an arrow's head size.). Only meaningful,
    /// and only ever written, when `geometry` is `Some(Geometry::Preset(_))` — kept as a sibling
    /// field here (rather than inside [`Geometry::Preset`] itself) to avoid a breaking change to
    /// that enum's existing tuple-variant shape, used at dozens of call sites across every host
    /// crate. Empty (the default) omits `<a:avLst>` entirely for a preset shape — schema- valid,
    /// meaning "use this preset's own built-in default handles". Grounded against a real fixture (a
    /// smiley-face preset with an explicit `adj` guide).
    pub geometry_adjustments: Vec<GeometryAdjustment>,
}

impl ShapeProperties {
    /// Creates an empty set of shape properties (every field unset — a shape that inherits
    /// everything from its host's defaults).
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets the shape's position/size/rotation (`<a:xfrm>`).
    pub fn with_transform(mut self, transform: Transform2D) -> Self {
        self.transform = Some(transform);
        self
    }

    /// Sets the shape's outline (`EG_Geometry`).
    pub fn with_geometry(mut self, geometry: Geometry) -> Self {
        self.geometry = Some(geometry);
        self
    }

    /// Sets the shape's interior fill (`EG_FillProperties`).
    pub fn with_fill(mut self, fill: Fill) -> Self {
        self.fill = Some(fill);
        self
    }

    /// Sets the shape's outline stroke (`<a:ln>`).
    pub fn with_line(mut self, line: Line) -> Self {
        self.line = Some(line);
        self
    }

    /// Sets the shape's visual effects (`<a:effectLst>`).
    pub fn with_effects(mut self, effects: EffectList) -> Self {
        self.effects = Some(effects);
        self
    }

    /// Sets a preset shape's adjustment handle values (`<a:avLst>`); no effect unless `geometry` is
    /// also `Some(Geometry::Preset(_))`.
    pub fn with_geometry_adjustments(mut self, adjustments: Vec<GeometryAdjustment>) -> Self {
        self.geometry_adjustments = adjustments;
        self
    }
}

/// One `<a:gd name=".." fmla=".."/>` (`CT_GeomGuide`) inside a preset shape's `<a:avLst>` — an
/// adjustment handle's current value. `name` is the handle's identifier (`"adj"` for a shape with a
/// single handle, `"adj1"`/`"adj2"`/. for shapes with several); `formula` is the raw guide formula
/// string PowerPoint itself writes (almost always `"val N"` for a literal value — the small
/// expression language `CT_GeomGuide` otherwise allows, e.g. referencing other guides, is not
/// interpreted here, only stored/round-tripped verbatim).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GeometryAdjustment {
    pub name: String,
    pub formula: String,
}

impl GeometryAdjustment {
    pub fn new(name: impl Into<String>, formula: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            formula: formula.into(),
        }
    }
}

/// `<a:effectLst>` (`CT_EffectList`). Only the four effects real-world decks overwhelmingly use are
/// modeled (outer shadow, glow, reflection, soft edge); `CT_EffectList`'s other choices
/// (`innerShdw`/`prstShdw`, `blur`, `fillOverlay`, alpha/color/duotone/ luminance-modulation effect
/// *filters* rather than genuine visual effects) are not, matching the "common case first" posture
/// already used for e.g. `Geometry::Custom`'s draw-command subset. Grounded against real fixtures
/// covering `outerShdw`, `glow`/`softEdge`, and `reflection`.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct EffectList {
    pub outer_shadow: Option<OuterShadow>,
    pub glow: Option<Glow>,
    pub reflection: Option<Reflection>,
    pub soft_edge: Option<SoftEdge>,
}

impl EffectList {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_outer_shadow(mut self, shadow: OuterShadow) -> Self {
        self.outer_shadow = Some(shadow);
        self
    }

    pub fn with_glow(mut self, glow: Glow) -> Self {
        self.glow = Some(glow);
        self
    }

    pub fn with_reflection(mut self, reflection: Reflection) -> Self {
        self.reflection = Some(reflection);
        self
    }

    pub fn with_soft_edge(mut self, soft_edge: SoftEdge) -> Self {
        self.soft_edge = Some(soft_edge);
        self
    }
}

/// `<a:outerShdw>` (`CT_OuterShadowEffect`) — a drop shadow cast outward from the shape.
/// `algn`/`rotWithShape`/`kx`/`ky`/`sx`/`sy` (fine-grained skew/scale/anchor controls) are not
/// modeled — a scope reduction, not a fixture gap (all `CT_OuterShadowEffect`'s own attributes
/// beyond the ones here are optional). `color`'s own alpha modifier (`<a:alpha val="..">`, seen
/// alongside `<a:srgbClr>`/`<a:schemeClr>` in real fixtures, e.g. `60810.pptx`'s `<a:srgbClr
/// val="000000"><a:alpha val="41000"/></a:srgbClr>`) is not preserved either — [`Color`] itself has
/// never modeled color transforms (see its own doc comment), not a new limitation.
#[derive(Debug, Clone, PartialEq)]
pub struct OuterShadow {
    /// `blurRad`, in EMUs.
    pub blur_radius_emu: Option<i64>,
    /// `dist`, in EMUs — how far the shadow is offset from the shape.
    pub distance_emu: Option<i64>,
    /// `dir` — the offset direction, in 60,000ths of a degree.
    pub direction_60000ths: Option<i32>,
    pub color: Color,
}

impl OuterShadow {
    /// Creates a shadow with the given color and no other attribute set.
    pub fn new(color: Color) -> Self {
        Self {
            blur_radius_emu: None,
            distance_emu: None,
            direction_60000ths: None,
            color,
        }
    }

    pub fn with_blur_radius_emu(mut self, blur_radius_emu: i64) -> Self {
        self.blur_radius_emu = Some(blur_radius_emu);
        self
    }

    pub fn with_distance_emu(mut self, distance_emu: i64) -> Self {
        self.distance_emu = Some(distance_emu);
        self
    }

    /// Sets the shadow's offset direction, given in ordinary degrees.
    pub fn with_direction_degrees(mut self, degrees: f64) -> Self {
        self.direction_60000ths = Some((degrees * 60_000.0).round() as i32);
        self
    }
}

/// `<a:glow rad="..">{color}</a:glow>` (`CT_GlowEffect`) — a soft colored halo around the shape's
/// outline. Unlike [`OuterShadow`], `rad` is required (`CT_GlowEffect`'s only attribute).
#[derive(Debug, Clone, PartialEq)]
pub struct Glow {
    /// `rad`, in EMUs.
    pub radius_emu: i64,
    pub color: Color,
}

impl Glow {
    pub fn new(radius_emu: i64, color: Color) -> Self {
        Self { radius_emu, color }
    }
}

/// `<a:reflection>` (`CT_ReflectionEffect`) — a faded mirror image below the shape.
/// `endPos`/`sx`/`sy`/`kx`/`ky`/`algn`/`fadeDir`/`rotWithShape` (fine- grained
/// scale/skew/anchor/fade-direction controls) are not modeled — the same scope-reduction posture as
/// [`OuterShadow`]; only the four attributes that dominate real-world usage (blur, distance,
/// direction, and the start/end fade transparency) are kept. Grounded against a real fixture
/// (`<a:reflection blurRad="12700" stA="48000" endA="300" endPos="55000" dir="5400000" sy="-90000"
/// algn="bl" rotWithShape="0"/>`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Reflection {
    /// `blurRad`, in EMUs.
    pub blur_radius_emu: Option<i64>,
    /// `dist`, in EMUs.
    pub distance_emu: Option<i64>,
    /// `dir`, in 60,000ths of a degree.
    pub direction_60000ths: Option<i32>,
    /// `stA` — the reflection's own starting transparency, in thousandths of a percent (`100000` =
    /// fully opaque). Defaults to `100000` per the schema when unset.
    pub start_alpha_1000ths_percent: Option<i32>,
    /// `endA` — the reflection's ending transparency (it fades out toward its far edge in
    /// real-world usage). Defaults to `0` per the schema when unset.
    pub end_alpha_1000ths_percent: Option<i32>,
}

impl Reflection {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_blur_radius_emu(mut self, blur_radius_emu: i64) -> Self {
        self.blur_radius_emu = Some(blur_radius_emu);
        self
    }

    pub fn with_distance_emu(mut self, distance_emu: i64) -> Self {
        self.distance_emu = Some(distance_emu);
        self
    }

    /// Sets the reflection's offset direction, given in ordinary degrees.
    pub fn with_direction_degrees(mut self, degrees: f64) -> Self {
        self.direction_60000ths = Some((degrees * 60_000.0).round() as i32);
        self
    }

    /// Sets the reflection's starting transparency, given as an ordinary percentage (`0.0.=100.0`).
    pub fn with_start_alpha_percent(mut self, percent: f64) -> Self {
        self.start_alpha_1000ths_percent = Some((percent * 1000.0).round() as i32);
        self
    }

    /// Sets the reflection's ending transparency, given as an ordinary percentage.
    pub fn with_end_alpha_percent(mut self, percent: f64) -> Self {
        self.end_alpha_1000ths_percent = Some((percent * 1000.0).round() as i32);
        self
    }
}

/// `<a:softEdge rad=".."/>` (`CT_SoftEdgesEffect`) — blurs the shape's own outline edge. `rad` is
/// required (its only attribute).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SoftEdge {
    /// `rad`, in EMUs.
    pub radius_emu: i64,
}

impl SoftEdge {
    pub fn new(radius_emu: i64) -> Self {
        Self { radius_emu }
    }
}

/// Position, size, rotation, and flipping (`<a:xfrm>`, `CT_Transform2D`). Both `offset`/`extent`
/// are optional in the schema (a shape can rely entirely on its host anchor for placement, e.g. a
/// picture inside a `xdr:twoCellAnchor` with no local `xfrm` at all) — `None` here means the
/// element itself is either absent or written with only the attributes present, matching that
/// flexibility rather than forcing a fixed size.
#[derive(Debug, Clone, Copy, PartialEq, Default)]
pub struct Transform2D {
    /// `<a:off x=".." y="..">`, in EMUs (English Metric Units; 914,400 EMU per inch — same unit
    /// `word-ooxml::Image` already uses).
    pub offset: Option<(i64, i64)>,
    /// `<a:ext cx=".." cy="..">`, in EMUs.
    pub extent: Option<(i64, i64)>,
    /// `<a:xfrm rot="..">` — `ST_Angle`, in 60,000ths of a degree, positive clockwise. Defaults to
    /// `0` (no rotation) when unset, matching the schema's own default.
    pub rotation_60000ths: i32,
    /// `<a:xfrm flipH="..">` — mirrors the shape horizontally before rotation is applied.
    pub flip_horizontal: bool,
    /// `<a:xfrm flipV="..">` — mirrors the shape vertically before rotation is applied.
    pub flip_vertical: bool,
}

impl Transform2D {
    /// Creates a transform with every field at its schema default (no offset/extent, no rotation,
    /// no flipping).
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets the shape's position, in EMUs.
    pub fn with_offset(mut self, x_emu: i64, y_emu: i64) -> Self {
        self.offset = Some((x_emu, y_emu));
        self
    }

    /// Sets the shape's size, in EMUs.
    pub fn with_extent(mut self, width_emu: i64, height_emu: i64) -> Self {
        self.extent = Some((width_emu, height_emu));
        self
    }

    /// Sets the shape's rotation, given in ordinary degrees (converted to the schema's
    /// 60,000ths-of-a-degree unit internally).
    pub fn with_rotation_degrees(mut self, degrees: f64) -> Self {
        self.rotation_60000ths = (degrees * 60_000.0).round() as i32;
        self
    }

    /// Mirrors the shape horizontally.
    pub fn with_flip_horizontal(mut self, flip: bool) -> Self {
        self.flip_horizontal = flip;
        self
    }

    /// Mirrors the shape vertically.
    pub fn with_flip_vertical(mut self, flip: bool) -> Self {
        self.flip_vertical = flip;
        self
    }
}

/// A shape's outline (`EG_Geometry`, the choice between `<a:custGeom>` and `<a:prstGeom>`).
///
/// [`Geometry::Custom`] only models `<a:custGeom>`'s own required `<a:pathLst>` — a single
/// `<a:path>`'s `moveTo`/`lnTo`/`cubicBezTo`/`close` draw commands, the vocabulary explicitly asked
/// for by plan. Not modeled: guides (`<a:avLst>`/`<a:gdLst>`, formula-driven adjust-handle values),
/// adjust handles (`<a:ahLst>`), connection sites (`<a:cxnLst>`), the optional bounding `<a:rect>`,
/// `quadBezTo`/`arcTo` draw commands, and multiple `<a:path>` elements within one `<a:pathLst>`
/// (`CT_Path2DList` allows several — e.g. for a shape made of disjoint outlines — only the first is
/// read back, matching the single-path case every real custom shape this crate has been asked to
/// support so far actually needs). All of the above are `minOccurs="0"` on `CT_CustomGeometry`
/// except `pathLst` itself, so omitting them entirely still produces a schema-valid element.
///
/// Grounded against a real fixture (`ppt/slides/slide6.xml`), which confirmed the assumed element
/// order and nesting exactly. That same fixture also revealed a real reading gap: its `<a:pt>`
/// coordinates are guide-name references (`<a:pt x="f2" y="f2"/>`, resolved via `<a:gd name="f2"
/// fmla=".."/>` entries in the `<a:gdLst>` this crate doesn't model) rather than literal integers —
/// `ST_AdjCoordinate` allows either. Since [`crate::reader`]'s path-point parser expects a literal
/// integer, a shape using formula-referenced coordinates currently round-trips its points back as
/// `(0, 0)` instead of erroring loudly. This crate's own writer is unaffected (it only ever emits
/// literal integers), so the gap only bites when *reading* a complex shape authored by real
/// PowerPoint with adjustable guides — accepted as an out-of-scope corner of the
/// "literal-coordinate common case" this crate targets, rather than implementing a formula
/// evaluator for `<a:gdLst>`.
#[derive(Debug, Clone, PartialEq)]
pub enum Geometry {
    Preset(PresetShape),
    Custom(CustomGeometry),
}

/// `<a:custGeom><a:pathLst><a:path w=".." h="..">`'s own draw commands (`CT_Path2D`) — see
/// [`Geometry::Custom`]'s doc comment for scope.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct CustomGeometry {
    /// `<a:path w="..">` — the path's own coordinate space width. Distinct from the shape's actual
    /// on-slide size (`ShapeProperties::transform`'s own `extent`) — real PowerPoint scales the
    /// path's coordinates to fit whatever size the shape is actually drawn at, exactly like a
    /// group's `chExt` scaling its children (see `ShapeGroup`'s own doc comment in
    /// `powerpoint-ooxml` for the same underlying idea).
    pub width_emu: i64,
    /// `<a:path h="..">`.
    pub height_emu: i64,
    /// The path's draw commands, in order. The schema requires at least a `moveTo` before any
    /// `lnTo`/`cubicBezTo`/`close` — not enforced at the model level, same best-effort posture used
    /// elsewhere in this crate.
    pub commands: Vec<PathCommand>,
}

impl CustomGeometry {
    /// Creates an empty custom path (no commands) with the given coordinate space size.
    pub fn new(width_emu: i64, height_emu: i64) -> Self {
        Self {
            width_emu,
            height_emu,
            commands: Vec::new(),
        }
    }

    /// Appends one draw command.
    pub fn with_command(mut self, command: PathCommand) -> Self {
        self.commands.push(command);
        self
    }
}

/// One draw command inside a custom path (`EG_Path2DList`'s children within a single `<a:path>` —
/// `moveTo`/`lnTo`/`cubicBezTo`/`close` only, see [`Geometry::Custom`]'s doc comment for what else
/// exists but isn't modeled). Coordinates are in the enclosing `<a:path>`'s own coordinate space
/// (`0.=width_emu`/`0.=height_emu`), not absolute EMUs.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PathCommand {
    /// `<a:moveTo><a:pt x=".." y=".."/></a:moveTo>` — starts a new subpath at `(x, y)` without
    /// drawing.
    MoveTo { x: i64, y: i64 },
    /// `<a:lnTo><a:pt x=".." y=".."/></a:lnTo>` — a straight line to `(x, y)`.
    LineTo { x: i64, y: i64 },
    /// `<a:cubicBezTo>` — a cubic Bézier curve to `(x, y)`, via the two control points `(x1,
    /// y1)`/`(x2, y2)`.
    CubicBezierTo {
        x1: i64,
        y1: i64,
        x2: i64,
        y2: i64,
        x: i64,
        y: i64,
    },
    /// `<a:close/>` — closes the current subpath back to its own `moveTo`.
    Close,
}

/// A useful subset of `ST_ShapeType`'s ~185 preset shape names — the ones most commonly authored by
/// real tools (basic shapes, arrows, a handful of callouts/symbols). [`PresetShape::Other`]
/// preserves round-trip fidelity for any preset name not explicitly modeled here, the same "closed
/// enum + escape hatch" posture this workspace already uses for open-ended, large-but-finite value
/// sets (e.g. font family names) rather than exhaustively enumerating every value up front for a
/// feature not yet needed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PresetShape {
    Rectangle,
    RoundedRectangle,
    Ellipse,
    Triangle,
    RightTriangle,
    Diamond,
    Parallelogram,
    Trapezoid,
    Pentagon,
    Hexagon,
    Heptagon,
    Octagon,
    Decagon,
    Dodecagon,
    Star4,
    Star5,
    Star6,
    Star8,
    Star10,
    Star12,
    Line,
    Plaque,
    Teardrop,
    HomePlate,
    Chevron,
    Pie,
    Donut,
    BlockArc,
    NoSmoking,
    RightArrow,
    LeftArrow,
    UpArrow,
    DownArrow,
    LeftRightArrow,
    UpDownArrow,
    BentArrow,
    UturnArrow,
    Heart,
    Sun,
    Moon,
    SmileyFace,
    Cube,
    Can,
    LightningBolt,
    FoldedCorner,
    Bevel,
    Frame,
    Arc,
    Chord,
    LeftBrace,
    RightBrace,
    BracePair,
    /// Any `ST_ShapeType` token not covered by the variants above, kept verbatim (e.g.
    /// `"irregularSeal1"`, `"mathDivide"`, `"gear9"`..).
    Other(String),
}

impl PresetShape {
    /// The exact `ST_ShapeType` token this variant writes as `<a:prstGeom prst="..">`.
    pub(crate) fn xml_token(&self) -> &str {
        match self {
            PresetShape::Rectangle => "rect",
            PresetShape::RoundedRectangle => "roundRect",
            PresetShape::Ellipse => "ellipse",
            PresetShape::Triangle => "triangle",
            PresetShape::RightTriangle => "rtTriangle",
            PresetShape::Diamond => "diamond",
            PresetShape::Parallelogram => "parallelogram",
            PresetShape::Trapezoid => "trapezoid",
            PresetShape::Pentagon => "pentagon",
            PresetShape::Hexagon => "hexagon",
            PresetShape::Heptagon => "heptagon",
            PresetShape::Octagon => "octagon",
            PresetShape::Decagon => "decagon",
            PresetShape::Dodecagon => "dodecagon",
            PresetShape::Star4 => "star4",
            PresetShape::Star5 => "star5",
            PresetShape::Star6 => "star6",
            PresetShape::Star8 => "star8",
            PresetShape::Star10 => "star10",
            PresetShape::Star12 => "star12",
            PresetShape::Line => "line",
            PresetShape::Plaque => "plaque",
            PresetShape::Teardrop => "teardrop",
            PresetShape::HomePlate => "homePlate",
            PresetShape::Chevron => "chevron",
            PresetShape::Pie => "pie",
            PresetShape::Donut => "donut",
            PresetShape::BlockArc => "blockArc",
            PresetShape::NoSmoking => "noSmoking",
            PresetShape::RightArrow => "rightArrow",
            PresetShape::LeftArrow => "leftArrow",
            PresetShape::UpArrow => "upArrow",
            PresetShape::DownArrow => "downArrow",
            PresetShape::LeftRightArrow => "leftRightArrow",
            PresetShape::UpDownArrow => "upDownArrow",
            PresetShape::BentArrow => "bentArrow",
            PresetShape::UturnArrow => "uturnArrow",
            PresetShape::Heart => "heart",
            PresetShape::Sun => "sun",
            PresetShape::Moon => "moon",
            PresetShape::SmileyFace => "smileyFace",
            PresetShape::Cube => "cube",
            PresetShape::Can => "can",
            PresetShape::LightningBolt => "lightningBolt",
            PresetShape::FoldedCorner => "foldedCorner",
            PresetShape::Bevel => "bevel",
            PresetShape::Frame => "frame",
            PresetShape::Arc => "arc",
            PresetShape::Chord => "chord",
            PresetShape::LeftBrace => "leftBrace",
            PresetShape::RightBrace => "rightBrace",
            PresetShape::BracePair => "bracePair",
            PresetShape::Other(token) => token,
        }
    }

    /// Resolves an `ST_ShapeType` token read from `<a:prstGeom prst="..">` back to a
    /// [`PresetShape`], falling back to [`PresetShape::Other`] for anything not explicitly modeled.
    pub(crate) fn from_xml_token(token: &str) -> Self {
        match token {
            "rect" => PresetShape::Rectangle,
            "roundRect" => PresetShape::RoundedRectangle,
            "ellipse" => PresetShape::Ellipse,
            "triangle" => PresetShape::Triangle,
            "rtTriangle" => PresetShape::RightTriangle,
            "diamond" => PresetShape::Diamond,
            "parallelogram" => PresetShape::Parallelogram,
            "trapezoid" => PresetShape::Trapezoid,
            "pentagon" => PresetShape::Pentagon,
            "hexagon" => PresetShape::Hexagon,
            "heptagon" => PresetShape::Heptagon,
            "octagon" => PresetShape::Octagon,
            "decagon" => PresetShape::Decagon,
            "dodecagon" => PresetShape::Dodecagon,
            "star4" => PresetShape::Star4,
            "star5" => PresetShape::Star5,
            "star6" => PresetShape::Star6,
            "star8" => PresetShape::Star8,
            "star10" => PresetShape::Star10,
            "star12" => PresetShape::Star12,
            "line" => PresetShape::Line,
            "plaque" => PresetShape::Plaque,
            "teardrop" => PresetShape::Teardrop,
            "homePlate" => PresetShape::HomePlate,
            "chevron" => PresetShape::Chevron,
            "pie" => PresetShape::Pie,
            "donut" => PresetShape::Donut,
            "blockArc" => PresetShape::BlockArc,
            "noSmoking" => PresetShape::NoSmoking,
            "rightArrow" => PresetShape::RightArrow,
            "leftArrow" => PresetShape::LeftArrow,
            "upArrow" => PresetShape::UpArrow,
            "downArrow" => PresetShape::DownArrow,
            "leftRightArrow" => PresetShape::LeftRightArrow,
            "upDownArrow" => PresetShape::UpDownArrow,
            "bentArrow" => PresetShape::BentArrow,
            "uturnArrow" => PresetShape::UturnArrow,
            "heart" => PresetShape::Heart,
            "sun" => PresetShape::Sun,
            "moon" => PresetShape::Moon,
            "smileyFace" => PresetShape::SmileyFace,
            "cube" => PresetShape::Cube,
            "can" => PresetShape::Can,
            "lightningBolt" => PresetShape::LightningBolt,
            "foldedCorner" => PresetShape::FoldedCorner,
            "bevel" => PresetShape::Bevel,
            "frame" => PresetShape::Frame,
            "arc" => PresetShape::Arc,
            "chord" => PresetShape::Chord,
            "leftBrace" => PresetShape::LeftBrace,
            "rightBrace" => PresetShape::RightBrace,
            "bracePair" => PresetShape::BracePair,
            other => PresetShape::Other(other.to_string()),
        }
    }
}

/// A color (`EG_ColorChoice`): the choice DrawingML offers wherever a color is needed (fills,
/// lines, gradient stops..).
///
/// Not modeled: scheme-relative colors (`<a:schemeClr>`, `ST_SchemeColorVal` — a reference into a
/// theme's 12-color palette) — deferred until a host crate can resolve a theme (see the project
/// notes plan,: `excel-ooxml` has no configurable `Theme` model at all yet, and `word-ooxml`'s own
/// `Theme`/`Style`/`Run` never reference a theme slot either — `drawing` has nothing to resolve
/// against today). Color transforms (`EG_ColorTransform` — `alpha`/`lumMod`/`lumOff`/`shade`/
/// `tint`/., applicable to every variant below) are not modeled either — each variant here is
/// always a literal, unmodified color.
#[derive(Debug, Clone, PartialEq)]
pub enum Color {
    /// `<a:srgbClr val="RRGGBB">` — a literal RGB color, hex-encoded with no leading `#`. The
    /// overwhelmingly common case, same representation `excel-ooxml`/`word-ooxml` already use for
    /// their own literal colors.
    Rgb(String),
    /// `<a:scrgbClr r=".." g=".." b="..">` — a literal RGB color given as percentages, each in
    /// thousandths of a percent (`ST_Percentage`; `100000` = 100%).
    RgbPercent { red: i64, green: i64, blue: i64 },
    /// `<a:hslClr hue=".." sat=".." lum="..">`. `hue` is `ST_PositiveFixedAngle` (60,000ths of a
    /// degree, `0.=21_600_000`); `saturation`/`luminance` are `ST_Percentage` (thousandths of a
    /// percent).
    Hsl {
        hue_60000ths: i32,
        saturation_1000ths_percent: i64,
        luminance_1000ths_percent: i64,
    },
    /// `<a:sysClr val=".." lastClr="..">` — one of the ~30 legacy Windows UI colors
    /// (`ST_SystemColorVal`, e.g. `"windowText"`, `"btnFace"`). `value` is kept as the raw token
    /// rather than a closed enum (rarely used in real documents, same "not enumerated" posture as
    /// `Preset` below); `last_color` is the RGB fallback Office itself resolved it to at authoring
    /// time.
    System {
        value: String,
        last_color: Option<String>,
    },
    /// `<a:prstClr val="..">` — one of `ST_PresetColorVal`'s ~140 CSS-like named colors (e.g.
    /// `"aliceBlue"`, `"tomato"`). Kept as the raw token rather than a closed enum, for the same
    /// reason as [`Color::System`] — see [`Color::Rgb`] for the common, literal-hex case.
    Preset(String),
}

/// How a shape's (or a line's) interior is painted (`EG_FillProperties`).
///
/// Not modeled: `<a:grpFill>` (inherit the parent group's fill — only meaningful for a shape inside
/// a group, which this crate doesn't model).
#[derive(Debug, Clone, PartialEq)]
pub enum Fill {
    /// `<a:noFill/>` — an explicitly transparent interior (distinct from `None` at the Rust level
    /// on [`ShapeProperties::fill`], which means "inherit from the host's shape defaults" instead).
    None,
    /// `<a:solidFill>` — a single flat color.
    Solid(Color),
    /// `<a:gradFill>` — a multi-stop gradient.
    Gradient(GradientFill),
    /// `<a:pattFill>` — a two-color repeating pattern.
    Pattern(PatternFill),
    /// `<a:blipFill>` — an image fill. The same `CT_BlipFillProperties` type also appears, always
    /// present rather than optional, as `<pic:pic>`'s own dedicated fill (`dml-picture.xsd`'s
    /// `CT_Picture`, alongside `spPr` — a real picture shape, not just a shape textured with an
    /// image) — see [`BlipFill`]'s doc comment.
    Image(BlipFill),
}

/// A gradient fill (`<a:gradFill>`, `CT_GradientFillProperties`).
///
/// Only linear shading (`<a:lin ang="..">`) is modeled — `EG_ShadeProperties`'s other choice,
/// path-based shading (`<a:path path="circle"/"rect"/"shape">`, radiating from a point or rectangle
/// rather than along a straight line), is deferred; `tileRect`/`flip`/`rotWithShape` (fine-grained
/// tiling controls) are not modeled either.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct GradientFill {
    /// `<a:gsLst><a:gs>..` — the gradient's color stops. The schema requires at least 2; not
    /// enforced at the model level (same best-effort posture as e.g.
    /// `ExcelTable::table_style_name`).
    pub stops: Vec<GradientStop>,
    /// `<a:lin ang="..">` — the gradient's direction, in 60,000ths of a degree. `None` omits
    /// `<a:lin>` entirely (an unspecified/default direction).
    pub angle_60000ths: Option<i32>,
}

impl GradientFill {
    /// Creates an empty gradient (no stops, no angle).
    pub fn new() -> Self {
        Self::default()
    }

    /// Appends one color stop.
    pub fn with_stop(mut self, stop: GradientStop) -> Self {
        self.stops.push(stop);
        self
    }

    /// Sets the gradient's linear direction, given in ordinary degrees.
    pub fn with_angle_degrees(mut self, degrees: f64) -> Self {
        self.angle_60000ths = Some((degrees * 60_000.0).round() as i32);
        self
    }
}

/// One color stop in a gradient (`<a:gs pos="..">`, `CT_GradientStop`).
#[derive(Debug, Clone, PartialEq)]
pub struct GradientStop {
    /// `pos` — the stop's position along the gradient, in thousandths of a percent
    /// (`ST_PositiveFixedPercentage`, `0.=100_000`).
    pub position_1000ths_percent: i64,
    pub color: Color,
}

impl GradientStop {
    /// Creates a stop at the given position, given as an ordinary percentage (`0.0.=100.0`).
    pub fn new(position_percent: f64, color: Color) -> Self {
        Self {
            position_1000ths_percent: (position_percent * 1000.0).round() as i64,
            color,
        }
    }
}

/// A two-color repeating pattern fill (`<a:pattFill>`, `CT_PatternFillProperties`).
#[derive(Debug, Clone, PartialEq)]
pub struct PatternFill {
    pub preset: PresetPattern,
    /// `<a:fgClr>` — the pattern's foreground (the color the pattern's "on" pixels are drawn in).
    pub foreground: Option<Color>,
    /// `<a:bgClr>` — the pattern's background (the color showing through its "off" pixels).
    pub background: Option<Color>,
}

impl PatternFill {
    pub fn new(preset: PresetPattern) -> Self {
        Self {
            preset,
            foreground: None,
            background: None,
        }
    }

    pub fn with_foreground(mut self, color: Color) -> Self {
        self.foreground = Some(color);
        self
    }

    pub fn with_background(mut self, color: Color) -> Self {
        self.background = Some(color);
        self
    }
}

/// `ST_PresetPatternVal`'s full, finite set of 54 named patterns — unlike
/// [`PresetShape`]/[`Color::Preset`], small enough to enumerate exhaustively (no `Other` escape
/// hatch needed).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PresetPattern {
    Percent5,
    Percent10,
    Percent20,
    Percent25,
    Percent30,
    Percent40,
    Percent50,
    Percent60,
    Percent70,
    Percent75,
    Percent80,
    Percent90,
    Horizontal,
    Vertical,
    LightHorizontal,
    LightVertical,
    DarkHorizontal,
    DarkVertical,
    NarrowHorizontal,
    NarrowVertical,
    DashedHorizontal,
    DashedVertical,
    Cross,
    DiagonalDown,
    DiagonalUp,
    LightDiagonalDown,
    LightDiagonalUp,
    DarkDiagonalDown,
    DarkDiagonalUp,
    WideDiagonalDown,
    WideDiagonalUp,
    DashedDiagonalDown,
    DashedDiagonalUp,
    DiagonalCross,
    SmallCheckerBoard,
    LargeCheckerBoard,
    SmallGrid,
    LargeGrid,
    DottedGrid,
    SmallConfetti,
    LargeConfetti,
    HorizontalBrick,
    DiagonalBrick,
    SolidDiamond,
    OpenDiamond,
    DottedDiamond,
    Plaid,
    Sphere,
    Weave,
    Divot,
    Shingle,
    Wave,
    Trellis,
    ZigZag,
}

impl PresetPattern {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            PresetPattern::Percent5 => "pct5",
            PresetPattern::Percent10 => "pct10",
            PresetPattern::Percent20 => "pct20",
            PresetPattern::Percent25 => "pct25",
            PresetPattern::Percent30 => "pct30",
            PresetPattern::Percent40 => "pct40",
            PresetPattern::Percent50 => "pct50",
            PresetPattern::Percent60 => "pct60",
            PresetPattern::Percent70 => "pct70",
            PresetPattern::Percent75 => "pct75",
            PresetPattern::Percent80 => "pct80",
            PresetPattern::Percent90 => "pct90",
            PresetPattern::Horizontal => "horz",
            PresetPattern::Vertical => "vert",
            PresetPattern::LightHorizontal => "ltHorz",
            PresetPattern::LightVertical => "ltVert",
            PresetPattern::DarkHorizontal => "dkHorz",
            PresetPattern::DarkVertical => "dkVert",
            PresetPattern::NarrowHorizontal => "narHorz",
            PresetPattern::NarrowVertical => "narVert",
            PresetPattern::DashedHorizontal => "dashHorz",
            PresetPattern::DashedVertical => "dashVert",
            PresetPattern::Cross => "cross",
            PresetPattern::DiagonalDown => "dnDiag",
            PresetPattern::DiagonalUp => "upDiag",
            PresetPattern::LightDiagonalDown => "ltDnDiag",
            PresetPattern::LightDiagonalUp => "ltUpDiag",
            PresetPattern::DarkDiagonalDown => "dkDnDiag",
            PresetPattern::DarkDiagonalUp => "dkUpDiag",
            PresetPattern::WideDiagonalDown => "wdDnDiag",
            PresetPattern::WideDiagonalUp => "wdUpDiag",
            PresetPattern::DashedDiagonalDown => "dashDnDiag",
            PresetPattern::DashedDiagonalUp => "dashUpDiag",
            PresetPattern::DiagonalCross => "diagCross",
            PresetPattern::SmallCheckerBoard => "smCheck",
            PresetPattern::LargeCheckerBoard => "lgCheck",
            PresetPattern::SmallGrid => "smGrid",
            PresetPattern::LargeGrid => "lgGrid",
            PresetPattern::DottedGrid => "dotGrid",
            PresetPattern::SmallConfetti => "smConfetti",
            PresetPattern::LargeConfetti => "lgConfetti",
            PresetPattern::HorizontalBrick => "horzBrick",
            PresetPattern::DiagonalBrick => "diagBrick",
            PresetPattern::SolidDiamond => "solidDmnd",
            PresetPattern::OpenDiamond => "openDmnd",
            PresetPattern::DottedDiamond => "dotDmnd",
            PresetPattern::Plaid => "plaid",
            PresetPattern::Sphere => "sphere",
            PresetPattern::Weave => "weave",
            PresetPattern::Divot => "divot",
            PresetPattern::Shingle => "shingle",
            PresetPattern::Wave => "wave",
            PresetPattern::Trellis => "trellis",
            PresetPattern::ZigZag => "zigZag",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "pct5" => PresetPattern::Percent5,
            "pct10" => PresetPattern::Percent10,
            "pct20" => PresetPattern::Percent20,
            "pct25" => PresetPattern::Percent25,
            "pct30" => PresetPattern::Percent30,
            "pct40" => PresetPattern::Percent40,
            "pct50" => PresetPattern::Percent50,
            "pct60" => PresetPattern::Percent60,
            "pct70" => PresetPattern::Percent70,
            "pct75" => PresetPattern::Percent75,
            "pct80" => PresetPattern::Percent80,
            "pct90" => PresetPattern::Percent90,
            "horz" => PresetPattern::Horizontal,
            "vert" => PresetPattern::Vertical,
            "ltHorz" => PresetPattern::LightHorizontal,
            "ltVert" => PresetPattern::LightVertical,
            "dkHorz" => PresetPattern::DarkHorizontal,
            "dkVert" => PresetPattern::DarkVertical,
            "narHorz" => PresetPattern::NarrowHorizontal,
            "narVert" => PresetPattern::NarrowVertical,
            "dashHorz" => PresetPattern::DashedHorizontal,
            "dashVert" => PresetPattern::DashedVertical,
            "cross" => PresetPattern::Cross,
            "dnDiag" => PresetPattern::DiagonalDown,
            "upDiag" => PresetPattern::DiagonalUp,
            "ltDnDiag" => PresetPattern::LightDiagonalDown,
            "ltUpDiag" => PresetPattern::LightDiagonalUp,
            "dkDnDiag" => PresetPattern::DarkDiagonalDown,
            "dkUpDiag" => PresetPattern::DarkDiagonalUp,
            "wdDnDiag" => PresetPattern::WideDiagonalDown,
            "wdUpDiag" => PresetPattern::WideDiagonalUp,
            "dashDnDiag" => PresetPattern::DashedDiagonalDown,
            "dashUpDiag" => PresetPattern::DashedDiagonalUp,
            "diagCross" => PresetPattern::DiagonalCross,
            "smCheck" => PresetPattern::SmallCheckerBoard,
            "lgCheck" => PresetPattern::LargeCheckerBoard,
            "smGrid" => PresetPattern::SmallGrid,
            "lgGrid" => PresetPattern::LargeGrid,
            "dotGrid" => PresetPattern::DottedGrid,
            "smConfetti" => PresetPattern::SmallConfetti,
            "lgConfetti" => PresetPattern::LargeConfetti,
            "horzBrick" => PresetPattern::HorizontalBrick,
            "diagBrick" => PresetPattern::DiagonalBrick,
            "solidDmnd" => PresetPattern::SolidDiamond,
            "openDmnd" => PresetPattern::OpenDiamond,
            "dotDmnd" => PresetPattern::DottedDiamond,
            "plaid" => PresetPattern::Plaid,
            "sphere" => PresetPattern::Sphere,
            "weave" => PresetPattern::Weave,
            "divot" => PresetPattern::Divot,
            "shingle" => PresetPattern::Shingle,
            "wave" => PresetPattern::Wave,
            "trellis" => PresetPattern::Trellis,
            "zigZag" => PresetPattern::ZigZag,
            _ => return None,
        })
    }
}

/// A shape's outline stroke (`<a:ln>`, `CT_LineProperties`).
///
/// Not modeled: `<a:extLst>` (extension list) and the pen-alignment (`algn` — center/inset)
/// attribute — a rare, cosmetic refinement. The compound-line attribute (`cmpd`) *is* modeled, see
/// [`LineCompound`].
#[derive(Debug, Clone, PartialEq, Default)]
pub struct Line {
    /// `w` — the stroke's width, in EMUs.
    pub width_emu: Option<i64>,
    /// `EG_LineFillProperties` — how the stroke itself is painted (the same fill choices as a
    /// shape's interior, minus image/group fills, which aren't valid here per the schema).
    pub fill: Option<Fill>,
    /// `<a:prstDash val="..">` — one of the 11 preset dash patterns. Custom dash patterns
    /// (`<a:custDash>`, an explicit dash/space stop list) are deferred.
    pub dash: Option<PresetLineDash>,
    /// `cap` — the stroke's end-cap style.
    pub cap: Option<LineCap>,
    /// `EG_LineJoinProperties` — how the stroke's corners are drawn.
    pub join: Option<LineJoin>,
    /// `<a:headEnd>` — the arrowhead (or other decoration) at the line's start.
    pub head_end: Option<LineEnd>,
    /// `<a:tailEnd>` — the arrowhead (or other decoration) at the line's end.
    pub tail_end: Option<LineEnd>,
    /// `cmpd` — the stroke's compound-line style (single/double/thick-thin/ thin-thick/triple).
    /// `None` omits the attribute (`ST_CompoundLine`'s own schema default, `"sng"`, applies).
    /// Grounded against a real fixture's slide master border (`cmpd="sng"`).
    pub compound: Option<LineCompound>,
}

impl Line {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_compound(mut self, compound: LineCompound) -> Self {
        self.compound = Some(compound);
        self
    }

    pub fn with_width_emu(mut self, width_emu: i64) -> Self {
        self.width_emu = Some(width_emu);
        self
    }

    pub fn with_fill(mut self, fill: Fill) -> Self {
        self.fill = Some(fill);
        self
    }

    pub fn with_dash(mut self, dash: PresetLineDash) -> Self {
        self.dash = Some(dash);
        self
    }

    pub fn with_cap(mut self, cap: LineCap) -> Self {
        self.cap = Some(cap);
        self
    }

    pub fn with_join(mut self, join: LineJoin) -> Self {
        self.join = Some(join);
        self
    }

    pub fn with_head_end(mut self, end: LineEnd) -> Self {
        self.head_end = Some(end);
        self
    }

    pub fn with_tail_end(mut self, end: LineEnd) -> Self {
        self.tail_end = Some(end);
        self
    }
}

/// `ST_PresetLineDashVal`'s full set of 11 named dash patterns.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PresetLineDash {
    Solid,
    Dot,
    Dash,
    LargeDash,
    DashDot,
    LargeDashDot,
    LargeDashDotDot,
    SystemDash,
    SystemDot,
    SystemDashDot,
    SystemDashDotDot,
}

impl PresetLineDash {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            PresetLineDash::Solid => "solid",
            PresetLineDash::Dot => "dot",
            PresetLineDash::Dash => "dash",
            PresetLineDash::LargeDash => "lgDash",
            PresetLineDash::DashDot => "dashDot",
            PresetLineDash::LargeDashDot => "lgDashDot",
            PresetLineDash::LargeDashDotDot => "lgDashDotDot",
            PresetLineDash::SystemDash => "sysDash",
            PresetLineDash::SystemDot => "sysDot",
            PresetLineDash::SystemDashDot => "sysDashDot",
            PresetLineDash::SystemDashDotDot => "sysDashDotDot",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "solid" => PresetLineDash::Solid,
            "dot" => PresetLineDash::Dot,
            "dash" => PresetLineDash::Dash,
            "lgDash" => PresetLineDash::LargeDash,
            "dashDot" => PresetLineDash::DashDot,
            "lgDashDot" => PresetLineDash::LargeDashDot,
            "lgDashDotDot" => PresetLineDash::LargeDashDotDot,
            "sysDash" => PresetLineDash::SystemDash,
            "sysDot" => PresetLineDash::SystemDot,
            "sysDashDot" => PresetLineDash::SystemDashDot,
            "sysDashDotDot" => PresetLineDash::SystemDashDotDot,
            _ => return None,
        })
    }
}

/// `ST_LineCap` — a stroke's end-cap style.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LineCap {
    Round,
    Square,
    Flat,
}

impl LineCap {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            LineCap::Round => "rnd",
            LineCap::Square => "sq",
            LineCap::Flat => "flat",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "rnd" => LineCap::Round,
            "sq" => LineCap::Square,
            "flat" => LineCap::Flat,
            _ => return None,
        })
    }
}

/// `ST_CompoundLine` — a stroke's compound-line style.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LineCompound {
    Simple,
    Double,
    /// `"thickThin"` — a thick line above a thin one.
    ThickThin,
    /// `"thinThick"` — a thin line above a thick one.
    ThinThick,
    Triple,
}

impl LineCompound {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            LineCompound::Simple => "sng",
            LineCompound::Double => "dbl",
            LineCompound::ThickThin => "thickThin",
            LineCompound::ThinThick => "thinThick",
            LineCompound::Triple => "tri",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "sng" => LineCompound::Simple,
            "dbl" => LineCompound::Double,
            "thickThin" => LineCompound::ThickThin,
            "thinThick" => LineCompound::ThinThick,
            "tri" => LineCompound::Triple,
            _ => return None,
        })
    }
}

/// `EG_LineJoinProperties` — how a stroke's corners are drawn.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum LineJoin {
    Round,
    Bevel,
    /// `<a:miter lim="..">` — `lim` is the miter limit, in thousandths of a percent
    /// (`ST_PositivePercentage`).
    Miter {
        limit_1000ths_percent: Option<i64>,
    },
}

/// One end of a line/connector (`<a:headEnd>`/`<a:tailEnd>`, `CT_LineEndProperties`) — e.g. an
/// arrowhead.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct LineEnd {
    pub kind: Option<LineEndType>,
    pub width: Option<LineEndSize>,
    pub length: Option<LineEndSize>,
}

impl LineEnd {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_kind(mut self, kind: LineEndType) -> Self {
        self.kind = Some(kind);
        self
    }

    pub fn with_width(mut self, width: LineEndSize) -> Self {
        self.width = Some(width);
        self
    }

    pub fn with_length(mut self, length: LineEndSize) -> Self {
        self.length = Some(length);
        self
    }
}

/// `ST_LineEndType` — the shape of a line end decoration.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LineEndType {
    None,
    Triangle,
    Stealth,
    Diamond,
    Oval,
    Arrow,
}

impl LineEndType {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            LineEndType::None => "none",
            LineEndType::Triangle => "triangle",
            LineEndType::Stealth => "stealth",
            LineEndType::Diamond => "diamond",
            LineEndType::Oval => "oval",
            LineEndType::Arrow => "arrow",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "none" => LineEndType::None,
            "triangle" => LineEndType::Triangle,
            "stealth" => LineEndType::Stealth,
            "diamond" => LineEndType::Diamond,
            "oval" => LineEndType::Oval,
            "arrow" => LineEndType::Arrow,
            _ => return None,
        })
    }
}

/// `ST_LineEndWidth`/`ST_LineEndLength` — both share the same three-value small/medium/large scale.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LineEndSize {
    Small,
    Medium,
    Large,
}

impl LineEndSize {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            LineEndSize::Small => "sm",
            LineEndSize::Medium => "med",
            LineEndSize::Large => "lg",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "sm" => LineEndSize::Small,
            "med" => LineEndSize::Medium,
            "lg" => LineEndSize::Large,
            _ => return None,
        })
    }
}

// ================================================================================================
// Text-in-shape and image fills
// ================================================================================================

/// An image fill (`<a:blipFill>`, `CT_BlipFillProperties`). Confirmed against `dml-picture.xsd`'s
/// `CT_Picture` (`nvPicPr`/ `blipFill`/`spPr`) that this is the same type PowerPoint/Word/Excel all
/// use both for a real picture shape's own always-present fill *and* for texturing an ordinary
/// shape with an image (`EG_FillProperties`'s `blipFill` choice, alongside `noFill`/`solidFill`/..)
/// — one model, [`Fill::Image`], covers both uses.
///
/// The embedded-image reference, the stretch/tile choice, and cropping (`<a:srcRect>`, point 6) are
/// modeled. Not modeled: `<a:duotone>`/`<a:lum>`/other `<a:blip>` image effects, `dpi`/
/// `rotWithShape` attributes, and `EG_FillModeProperties`'s own fine-grained tiling/stretching
/// sub-rects (`<a:tile>`'s `tx`/`ty`/`sx`/ `sy`/`flip`/`algn`, `<a:stretch>`'s `<a:fillRect>`) —
/// all cosmetic refinements on top of "which image, does it stretch or tile, and is it cropped".
///
/// Resolving the embedded image's actual bytes is deliberately **not** this crate's job: `<a:blip
/// r:embed="..">`'s value is a bare relationship id (`AG_Blob`, confirmed in `dml-main.xsd`) —
/// `drawing` carries that id as a plain string, the same way it carries every other host-specific
/// reference (none, so far), and leaves resolving it through an actual OPC package/relationship set
/// to whichever host crate ends up consuming this (see `word-ooxml::Image`'s own `r:embed` handling
/// for the precedent this will eventually be generalized from).
#[derive(Debug, Clone, PartialEq, Default)]
pub struct BlipFill {
    /// `<a:blip r:embed="..">` — the embedded image's relationship id. `None` omits `<a:blip>`
    /// entirely (a `blipFill` with no image set — unusual, but not schema-invalid, `blip` being
    /// `minOccurs="0"`).
    pub relationship_id: Option<String>,
    /// `EG_FillModeProperties` — `<a:stretch/>` or `<a:tile/>`. `None` omits the choice entirely
    /// (Office's own default is an implicit stretch-to-fill).
    pub mode: Option<BlipFillMode>,
    /// `<a:srcRect>` (`CT_RelativeRect`) — crops the source image before it's stretched/tiled into
    /// the shape. `None` omits the element entirely (no cropping — the whole image is used), the
    /// common case.
    pub crop: Option<CropRect>,
}

impl BlipFill {
    /// Creates an image fill referencing the given relationship id.
    pub fn new(relationship_id: impl Into<String>) -> Self {
        Self {
            relationship_id: Some(relationship_id.into()),
            mode: None,
            crop: None,
        }
    }

    pub fn with_mode(mut self, mode: BlipFillMode) -> Self {
        self.mode = Some(mode);
        self
    }

    /// Crops the source image before it's stretched/tiled into the shape.
    pub fn with_crop(mut self, crop: CropRect) -> Self {
        self.crop = Some(crop);
        self
    }
}

/// `<a:srcRect l=".." t=".." r=".." b=".."/>` (`CT_RelativeRect`) — how much of a [`BlipFill`]'s
/// source image to crop from each edge, before stretching/tiling the remainder into the shape. Each
/// side is independently optional (`ST_Percentage`, thousandths of a percent of the image's own
/// width/height; can be negative, which *zooms out* rather than cropping — real PowerPoint uses
/// this for "fill the shape, source image too small" cases). Grounded against a real fixture (e.g.
/// `<a:srcRect l="2878" t="2522" r="21582" b="46217"/>`, and `<a:srcRect t="52941" b="-17647"/>`
/// for the negative case).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct CropRect {
    pub left_1000ths_percent: Option<i32>,
    pub top_1000ths_percent: Option<i32>,
    pub right_1000ths_percent: Option<i32>,
    pub bottom_1000ths_percent: Option<i32>,
}

impl CropRect {
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets each side's crop, given as ordinary percentages of the image's own width/height
    /// (`0.0.=100.0` for a normal crop; negative values zoom out instead).
    pub fn with_percent(mut self, left: f64, top: f64, right: f64, bottom: f64) -> Self {
        self.left_1000ths_percent = Some((left * 1000.0).round() as i32);
        self.top_1000ths_percent = Some((top * 1000.0).round() as i32);
        self.right_1000ths_percent = Some((right * 1000.0).round() as i32);
        self.bottom_1000ths_percent = Some((bottom * 1000.0).round() as i32);
        self
    }
}

/// `EG_FillModeProperties` — how an image fill is fitted to its shape.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BlipFillMode {
    /// `<a:stretch/>` — the image is scaled to exactly fill the shape.
    Stretch,
    /// `<a:tile/>` — the image is repeated at its natural size.
    Tile,
}

/// The text content of a shape (`<a:txBody>`, `CT_TextBody`). Structurally a **sibling** of
/// [`ShapeProperties`], not a field on it: confirmed against `dml-spreadsheetDrawing.xsd`'s
/// `CT_Shape` (`nvSpPr`/`spPr`/`style?`/`txBody?`, `txBody` a sibling of `spPr`, both direct
/// children of the host's own `<*:sp>` wrapper) — a future host crate combines the two itself,
/// `drawing` never nests one inside the other.
///
/// Not modeled: `<a:lstStyle>` (per-outline-level default paragraph properties, the mechanism
/// PowerPoint's placeholder text boxes use to inherit formatting from a slide layout — a materially
/// larger feature, same "deferred" posture as bullets below, which `lstStyle` also configures per
/// level) and `EG_TextAutofit`/`<a:scene3d>`/text-3D (shrink-to-fit/WordArt-style effects).
#[derive(Debug, Clone, PartialEq, Default)]
pub struct TextBody {
    /// `<a:bodyPr>` — always present in the schema (`minOccurs="1"`), even if empty
    /// (`<a:bodyPr/>`); this struct mirrors that by never being `Option` itself, only its own
    /// fields are.
    pub properties: TextBodyProperties,
    /// `<a:p>` — one or more paragraphs (schema requires at least one; not enforced at the model
    /// level, same best-effort posture used elsewhere in this crate).
    pub paragraphs: Vec<TextParagraph>,
}

impl TextBody {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_properties(mut self, properties: TextBodyProperties) -> Self {
        self.properties = properties;
        self
    }

    pub fn with_paragraph(mut self, paragraph: TextParagraph) -> Self {
        self.paragraphs.push(paragraph);
        self
    }
}

/// `<a:bodyPr>`'s attributes (`CT_TextBodyProperties`) — text wrapping, vertical anchor, horizontal
/// centering, inset margins, and autofit. See [`TextBody`]'s doc comment for what else
/// `CT_TextBodyProperties` allows but isn't modeled here (3D, preset text warp/WordArt).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct TextBodyProperties {
    /// `wrap` — whether text wraps at the shape's edge.
    pub wrap: Option<TextWrap>,
    /// `anchor` — vertical alignment of the text block within the shape.
    pub anchor: Option<TextAnchor>,
    /// `anchorCtr` — additionally centers the text block horizontally within the shape (on top of
    /// whatever `anchor` does vertically). Grounded against a real fixture.
    pub anchor_center: bool,
    /// `lIns`, in EMUs.
    pub inset_left_emu: Option<i64>,
    /// `tIns`, in EMUs.
    pub inset_top_emu: Option<i64>,
    /// `rIns`, in EMUs.
    pub inset_right_emu: Option<i64>,
    /// `bIns`, in EMUs.
    pub inset_bottom_emu: Option<i64>,
    /// `EG_TextAutofit` (`<a:noAutofit/>`/`<a:normAutofit/>`/ `<a:spAutoFit/>`) — how the text body
    /// reacts to content that doesn't fit its shape. `None` omits the choice entirely (Office's own
    /// implicit default, which real PowerPoint UI actually treats as equivalent to
    /// `TextAutofit::None`).
    pub autofit: Option<TextAutofit>,
    /// `vert` (`ST_TextVerticalType`) — the text's reading direction within its shape (horizontal,
    /// stacked vertically, rotated 270°.). `None` omits the attribute (`"horz"`, ordinary
    /// left-to-right text, is the schema default). Grounded against a real fixture's placeholder
    /// (`vert="eaVert"`).
    pub vertical_direction: Option<TextVerticalType>,
    /// `rot` (`ST_Angle`, 60,000ths of a degree) — rotates the text *within* its shape, independent
    /// of the shape's own rotation (`Transform2D::rotation_degrees`, on the surrounding
    /// `<a:xfrm>`). `0` (the default) omits the attribute. Grounded against a real fixture's
    /// `<a:bodyPr rot="0".>`.
    pub rotation_60000ths: i32,
}

impl TextBodyProperties {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_wrap(mut self, wrap: TextWrap) -> Self {
        self.wrap = Some(wrap);
        self
    }

    pub fn with_anchor(mut self, anchor: TextAnchor) -> Self {
        self.anchor = Some(anchor);
        self
    }

    /// Additionally centers the text block horizontally (`anchorCtr="1"`).
    pub fn with_anchor_center(mut self, anchor_center: bool) -> Self {
        self.anchor_center = anchor_center;
        self
    }

    /// Sets all four insets at once, in EMUs.
    pub fn with_insets_emu(mut self, left: i64, top: i64, right: i64, bottom: i64) -> Self {
        self.inset_left_emu = Some(left);
        self.inset_top_emu = Some(top);
        self.inset_right_emu = Some(right);
        self.inset_bottom_emu = Some(bottom);
        self
    }

    /// Sets how this text body reacts to overflowing content.
    pub fn with_autofit(mut self, autofit: TextAutofit) -> Self {
        self.autofit = Some(autofit);
        self
    }

    /// Sets the text's reading direction within its shape.
    pub fn with_vertical_direction(mut self, direction: TextVerticalType) -> Self {
        self.vertical_direction = Some(direction);
        self
    }

    /// Rotates the text within its shape, given in ordinary degrees (converted to the schema's
    /// 60,000ths-of-a-degree unit internally).
    pub fn with_rotation_degrees(mut self, degrees: f64) -> Self {
        self.rotation_60000ths = (degrees * 60_000.0).round() as i32;
        self
    }
}

/// `ST_TextVerticalType`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextVerticalType {
    Horizontal,
    /// `"vert"` — stacked top-to-bottom, each line reading top-to-bottom.
    Vertical,
    /// `"vert270"` — text rotated 270°, still stacked.
    Vertical270,
    /// `"wordArtVert"` — WordArt-style vertical stacking (one letter per line, upright).
    WordArtVertical,
    /// `"eaVert"` — East Asian vertical text layout.
    EastAsianVertical,
    /// `"mongolianVert"` — Mongolian vertical text layout.
    MongolianVertical,
    /// `"wordArtVertRtl"` — WordArt-style vertical stacking, right-to-left.
    WordArtVerticalRightToLeft,
}

impl TextVerticalType {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            TextVerticalType::Horizontal => "horz",
            TextVerticalType::Vertical => "vert",
            TextVerticalType::Vertical270 => "vert270",
            TextVerticalType::WordArtVertical => "wordArtVert",
            TextVerticalType::EastAsianVertical => "eaVert",
            TextVerticalType::MongolianVertical => "mongolianVert",
            TextVerticalType::WordArtVerticalRightToLeft => "wordArtVertRtl",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "horz" => TextVerticalType::Horizontal,
            "vert" => TextVerticalType::Vertical,
            "vert270" => TextVerticalType::Vertical270,
            "wordArtVert" => TextVerticalType::WordArtVertical,
            "eaVert" => TextVerticalType::EastAsianVertical,
            "mongolianVert" => TextVerticalType::MongolianVertical,
            "wordArtVertRtl" => TextVerticalType::WordArtVerticalRightToLeft,
            _ => return None,
        })
    }
}

/// `EG_TextAutofit` — how a text body reacts to content that doesn't fit its shape. Grounded
/// against real fixtures exercising all three variants.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextAutofit {
    /// `<a:noAutofit/>` — text overflows the shape rather than being resized (explicitly opts out,
    /// distinct from the field itself being `None`, which omits the element and inherits instead).
    None,
    /// `<a:spAutoFit/>` — the shape itself resizes to fit its text (a text box's own common
    /// default).
    Shape,
    /// `<a:normAutofit fontScale=".." lnSpcReduction=".."/>` — the text itself shrinks (font size
    /// scaled down, line spacing reduced) to fit the shape. Both attributes are
    /// `ST_TextFontScalePercentOrPercentString`/ `ST_TextSpacingPercentOrPercentString` in
    /// thousandths of a percent; `None` on either omits that attribute (a bare `<a:normAutofit/>`,
    /// also valid and commonly seen, meaning "shrink as needed, exact amount left to the
    /// renderer").
    Normal {
        font_scale_1000ths_percent: Option<i32>,
        line_spacing_reduction_1000ths_percent: Option<i32>,
    },
}

/// `ST_TextWrappingType`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextWrap {
    None,
    Square,
}

impl TextWrap {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            TextWrap::None => "none",
            TextWrap::Square => "square",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "none" => TextWrap::None,
            "square" => TextWrap::Square,
            _ => return None,
        })
    }
}

/// `ST_TextAnchoringType` — vertical anchor of a text body within its shape.
/// `Justified`/`Distributed` (`just`/`dist`) stretch line spacing to fill the shape's height rather
/// than anchoring to one edge.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextAnchor {
    Top,
    Center,
    Bottom,
    Justified,
    Distributed,
}

impl TextAnchor {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            TextAnchor::Top => "t",
            TextAnchor::Center => "ctr",
            TextAnchor::Bottom => "b",
            TextAnchor::Justified => "just",
            TextAnchor::Distributed => "dist",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "t" => TextAnchor::Top,
            "ctr" => TextAnchor::Center,
            "b" => TextAnchor::Bottom,
            "just" => TextAnchor::Justified,
            "dist" => TextAnchor::Distributed,
            _ => return None,
        })
    }
}

/// One paragraph of text (`<a:p>`, `CT_TextParagraph`).
///
/// Not modeled: `<a:endParaRPr>` (the formatting a UI would apply to text typed at this paragraph's
/// very end — a cosmetic authoring aid with no effect on existing content).
#[derive(Debug, Clone, PartialEq, Default)]
pub struct TextParagraph {
    /// `<a:pPr>`.
    pub properties: Option<TextParagraphProperties>,
    /// `EG_TextRun` — this crate only models the `r`/`br` choices (regular text and line breaks);
    /// `fld` (a field, e.g. a slide-number placeholder) is deferred — see [`TextRun`]'s doc
    /// comment.
    pub runs: Vec<TextRun>,
}

impl TextParagraph {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_properties(mut self, properties: TextParagraphProperties) -> Self {
        self.properties = Some(properties);
        self
    }

    pub fn with_run(mut self, run: TextRun) -> Self {
        self.runs.push(run);
        self
    }
}

/// `<a:pPr>`'s attributes (`CT_TextParagraphProperties`) — alignment, margins/indent, tab stops
/// (`tabLst`), paragraph spacing, indent/outline level, default run formatting, and bullets.
///
/// Not modeled: `<a:lstStyle>` (a text body's own per-level default paragraph styles, distinct from
/// any individual paragraph's own `pPr` modeled here — see [`TextBody`]'s doc comment).
#[derive(Debug, Clone, PartialEq, Default)]
pub struct TextParagraphProperties {
    /// `algn`.
    pub alignment: Option<TextAlign>,
    /// `marL`, in EMUs.
    pub margin_left_emu: Option<i64>,
    /// `marR`, in EMUs.
    pub margin_right_emu: Option<i64>,
    /// `indent` (first-line indent, can be negative for a hanging indent), in EMUs.
    pub indent_emu: Option<i64>,
    /// `lvl` (`ST_TextIndentLevelType`, `0.=8`) — this paragraph's indent/outline level, the
    /// mechanism real PowerPoint uses for multi-level bulleted/numbered lists (each level typically
    /// resolves its own bullet/indent/font size from the placeholder's `<a:lstStyle>` when not
    /// overridden directly on the paragraph, as here). `None` omits the attribute, equivalent to
    /// level `0`. Grounded against a real fixture.
    pub level: Option<u8>,
    /// `<a:tabLst><a:tab pos=".." algn=".."/>*</a:tabLst>` — this paragraph's own explicit tab
    /// stops, overriding whatever default tab spacing the host application would otherwise use. An
    /// empty `Vec` (the default) omits `<a:tabLst>` entirely, same "only write what was actually
    /// set" convention as every other optional child in this crate.
    pub tab_stops: Vec<TabStop>,
    /// `<a:lnSpc>` — line spacing. `None` inherits the host application's default.
    pub line_spacing: Option<TextSpacing>,
    /// `<a:spcBef>` — space before the paragraph.
    pub space_before: Option<TextSpacing>,
    /// `<a:spcAft>` — space after the paragraph.
    pub space_after: Option<TextSpacing>,
    /// `<a:buClrTx/>`/`<a:buClr>` — this paragraph's bullet color. `None` omits the element
    /// entirely (the bullet's color follows whatever the list style/master otherwise resolves,
    /// PowerPoint's actual default), distinct from `Some(BulletColor::FollowText)` (`<a:buClrTx/>`,
    /// explicitly "follow the text run's own color").
    pub bullet_color: Option<BulletColor>,
    /// `<a:buSzTx/>`/`<a:buSzPct>`/`<a:buSzPts>` — this paragraph's bullet size. Same
    /// `None`-omits-the-element posture as `bullet_color`.
    pub bullet_size: Option<BulletSize>,
    /// `<a:buFontTx/>`/`<a:buFont typeface=".">` — this paragraph's bullet font. Same
    /// `None`-omits-the-element posture as `bullet_color`. Only `typeface` is modeled (not
    /// `panose`/ `pitchFamily`/`charset`, all optional cosmetic hints).
    pub bullet_font: Option<BulletFont>,
    /// `<a:buNone/>`/`<a:buChar char=".">`/`<a:buAutoNum type=".">` — this paragraph's own
    /// bullet/numbering marker. `None` omits the element entirely (inherits from the list
    /// style/master, PowerPoint's actual default — usually a bullet for body text). Grounded
    /// against real fixtures covering both `buChar` and `buAutoNum`.
    pub bullet: Option<BulletKind>,
    /// `<a:defRPr>` — this paragraph's own default run formatting, used by any run that doesn't set
    /// the matching property itself, and by an empty paragraph's own end-of-paragraph mark. `None`
    /// omits the element entirely. Reuses [`TextRunProperties`] verbatim, the same vocabulary an
    /// individual run's own `<a:rPr>` uses.
    pub default_run_properties: Option<Box<TextRunProperties>>,
}

impl TextParagraphProperties {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_alignment(mut self, alignment: TextAlign) -> Self {
        self.alignment = Some(alignment);
        self
    }

    pub fn with_margins_emu(mut self, left: i64, right: i64) -> Self {
        self.margin_left_emu = Some(left);
        self.margin_right_emu = Some(right);
        self
    }

    pub fn with_indent_emu(mut self, indent: i64) -> Self {
        self.indent_emu = Some(indent);
        self
    }

    /// Sets the indent/outline level (`0.=8`).
    pub fn with_level(mut self, level: u8) -> Self {
        self.level = Some(level);
        self
    }

    /// Appends one explicit tab stop.
    pub fn with_tab_stop(mut self, tab_stop: TabStop) -> Self {
        self.tab_stops.push(tab_stop);
        self
    }

    pub fn with_line_spacing(mut self, spacing: TextSpacing) -> Self {
        self.line_spacing = Some(spacing);
        self
    }

    pub fn with_space_before(mut self, spacing: TextSpacing) -> Self {
        self.space_before = Some(spacing);
        self
    }

    pub fn with_space_after(mut self, spacing: TextSpacing) -> Self {
        self.space_after = Some(spacing);
        self
    }

    pub fn with_bullet_color(mut self, color: BulletColor) -> Self {
        self.bullet_color = Some(color);
        self
    }

    pub fn with_bullet_size(mut self, size: BulletSize) -> Self {
        self.bullet_size = Some(size);
        self
    }

    pub fn with_bullet_font(mut self, font: BulletFont) -> Self {
        self.bullet_font = Some(font);
        self
    }

    pub fn with_bullet(mut self, bullet: BulletKind) -> Self {
        self.bullet = Some(bullet);
        self
    }

    pub fn with_default_run_properties(mut self, properties: TextRunProperties) -> Self {
        self.default_run_properties = Some(Box::new(properties));
        self
    }
}

/// Paragraph-level spacing (`CT_TextSpacing`, the choice behind `<a:lnSpc>`/
/// `<a:spcBef>`/`<a:spcAft>`). Grounded against a real fixture exercising both variants side by
/// side (`<a:lnSpc><a:spcPct val="100000"/></a:lnSpc>`, `<a:spcBef><a:spcPts
/// val="0"/></a:spcBef>`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextSpacing {
    /// `<a:spcPct val="..">` — a percentage of a single line's height, in thousandths of a percent
    /// (`100000` = 100%).
    Percent(i32),
    /// `<a:spcPts val="..">` — an absolute size in hundredths of a point (`1200` = 12pt).
    Points(i32),
}

/// This paragraph's bullet color (`EG_TextBulletColor`).
#[derive(Debug, Clone, PartialEq)]
pub enum BulletColor {
    /// `<a:buClrTx/>` — follows the text run's own color.
    FollowText,
    /// `<a:buClr>{color}</a:buClr>` — an explicit color, reusing [`Color`] verbatim. Like the rest
    /// of this crate's own `Color` usage, a theme-relative `<a:schemeClr>` reference isn't modeled
    /// — only literal colors (see [`Color`]'s own doc comment).
    Explicit(Color),
}

/// This paragraph's bullet size (`EG_TextBulletSize`).
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum BulletSize {
    /// `<a:buSzTx/>` — follows the text run's own size.
    FollowText,
    /// `<a:buSzPct val="..">` — a percentage of the text's own size, in thousandths of a percent
    /// (`100000` = 100%).
    Percent(i32),
    /// `<a:buSzPts val="..">` — an absolute size in hundredths of a point.
    Points(i32),
}

/// This paragraph's bullet font (`EG_TextBulletTypeface`).
#[derive(Debug, Clone, PartialEq)]
pub enum BulletFont {
    /// `<a:buFontTx/>` — follows the text run's own font.
    FollowText,
    /// `<a:buFont typeface="..">` — an explicit font family name. Only `typeface` is modeled (not
    /// `panose`/`pitchFamily`/`charset`, all optional cosmetic hints real PowerPoint sets but
    /// doesn't require).
    Typeface(String),
}

/// This paragraph's bullet/numbering marker (`EG_TextBullet`).
#[derive(Debug, Clone, PartialEq)]
pub enum BulletKind {
    /// `<a:buNone/>` — explicitly no bullet (distinct from the field itself being `None`, which
    /// omits the element and inherits instead).
    None,
    /// `<a:buChar char="..">` — a literal bullet character (often from a symbol font like
    /// Wingdings, e.g. `"•"`/`"–"`/`"»"`).
    Character(String),
    /// `<a:buAutoNum type=".." startAt="..">` — an automatically incrementing number/letter.
    /// `scheme` is kept as the raw `ST_TextAutonumberScheme` token (e.g. `"arabicPeriod"`,
    /// `"romanUcPeriod"`, `"alphaLcParenR"` — ~20 values) rather than a closed enum, the same
    /// "large but finite token set, not enumerated" posture as [`Color::Preset`]. `start_at`
    /// (`None` defaults to `1` per the schema) overrides the starting number.
    AutoNumber {
        scheme: String,
        start_at: Option<i32>,
    },
}

/// One explicit tab stop (`<a:tab pos="." algn=".">`, `CT_TextTabStop`). Grounded against a real
/// fixture, which confirmed the `tabLst`/`tab` element shape and attribute names exactly as modeled
/// here.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TabStop {
    /// `pos`, in EMUs, measured from the paragraph's left edge.
    pub position_emu: i64,
    /// `algn` — how text aligns to this stop. `None` omits the attribute, matching
    /// `ST_TextTabAlignType`'s own default (`"l"`, left).
    pub alignment: Option<TabAlignment>,
}

impl TabStop {
    /// Creates a left-aligned tab stop at the given position.
    pub fn new(position_emu: i64) -> Self {
        Self {
            position_emu,
            alignment: None,
        }
    }

    pub fn with_alignment(mut self, alignment: TabAlignment) -> Self {
        self.alignment = Some(alignment);
        self
    }
}

/// `ST_TextTabAlignType`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TabAlignment {
    Left,
    Center,
    Right,
    Decimal,
}

impl TabAlignment {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            TabAlignment::Left => "l",
            TabAlignment::Center => "ctr",
            TabAlignment::Right => "r",
            TabAlignment::Decimal => "dec",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "l" => TabAlignment::Left,
            "ctr" => TabAlignment::Center,
            "r" => TabAlignment::Right,
            "dec" => TabAlignment::Decimal,
            _ => return None,
        })
    }
}

/// `ST_TextAlignType`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextAlign {
    Left,
    Center,
    Right,
    Justified,
    JustifiedLow,
    Distributed,
    ThaiDistributed,
}

impl TextAlign {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            TextAlign::Left => "l",
            TextAlign::Center => "ctr",
            TextAlign::Right => "r",
            TextAlign::Justified => "just",
            TextAlign::JustifiedLow => "justLow",
            TextAlign::Distributed => "dist",
            TextAlign::ThaiDistributed => "thaiDist",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "l" => TextAlign::Left,
            "ctr" => TextAlign::Center,
            "r" => TextAlign::Right,
            "just" => TextAlign::Justified,
            "justLow" => TextAlign::JustifiedLow,
            "dist" => TextAlign::Distributed,
            "thaiDist" => TextAlign::ThaiDistributed,
            _ => return None,
        })
    }
}

/// One run of text within a paragraph (`EG_TextRun`'s `r`/`br`/`fld` choices — see
/// [`TextRun::Field`]).
#[derive(Debug, Clone, PartialEq)]
pub enum TextRun {
    /// `<a:r><a:rPr../><a:t>..</a:t></a:r>`, `CT_RegularTextRun`.
    Regular {
        text: String,
        properties: TextRunProperties,
    },
    /// `<a:br><a:rPr../></a:br>`, `CT_TextLineBreak` — an explicit line break within a paragraph
    /// (distinct from starting a new `<a:p>`, which also resets paragraph-level properties).
    LineBreak {
        properties: Option<TextRunProperties>,
    },
    /// `<a:fld id="{GUID}" type=".."><a:rPr../><a:t>..</a:t></a:fld>`, `CT_TextField` — a dynamic,
    /// PowerPoint-updated value (slide number, current date..) rendered inline with a run's own
    /// text. Grounded against a real fixture's slide-number/date placeholders
    /// (`type="slidenum"`/`"datetimeFigureOut"`). `CT_TextField`'s own `pPr` child (paragraph
    /// properties duplicated onto the field, rarely populated in practice) is not modeled.
    Field {
        /// `id` — a GUID (`ST_Guid`, e.g. `"{5C4A1234-..}"`) uniquely identifying this field
        /// *within its host part*; real PowerPoint generates and preserves these itself.
        /// Stored/round-tripped verbatim, never generated or validated here.
        id: String,
        /// `type` — a free-form hint of what this field represents (real PowerPoint writes e.g.
        /// `"slidenum"`, `"datetime1"` through `"datetime13"`, `"datetimeFigureOut"` — this crate
        /// neither enumerates nor computes any of these, only stores whatever string is present).
        /// `None` omits the attribute (schema-valid, `type` is optional).
        field_type: Option<String>,
        /// `<a:t>` — the field's *cached* rendered text, exactly as PowerPoint last computed it
        /// (e.g. an actual date string, or `"‹N°›"` as a slide-number placeholder). Real PowerPoint
        /// recomputes and rewrites this text itself whenever the presentation is opened/printed;
        /// this crate never recomputes it.
        cached_text: String,
        properties: TextRunProperties,
    },
}

impl TextRun {
    /// A plain run of text with default (unset) formatting.
    pub fn text(text: impl Into<String>) -> Self {
        TextRun::Regular {
            text: text.into(),
            properties: TextRunProperties::new(),
        }
    }

    /// A run of text with explicit formatting.
    pub fn text_with_properties(text: impl Into<String>, properties: TextRunProperties) -> Self {
        TextRun::Regular {
            text: text.into(),
            properties,
        }
    }

    /// An explicit line break, inheriting the surrounding text's formatting.
    pub fn line_break() -> Self {
        TextRun::LineBreak { properties: None }
    }

    /// A dynamic field (slide number, date..), given its id, optional type hint, and current cached
    /// text, with default (unset) formatting.
    pub fn field(
        id: impl Into<String>,
        field_type: Option<String>,
        cached_text: impl Into<String>,
    ) -> Self {
        TextRun::Field {
            id: id.into(),
            field_type,
            cached_text: cached_text.into(),
            properties: TextRunProperties::new(),
        }
    }
}

/// A run's character formatting (`<a:rPr>`/`<a:defRPr>`/`<a:endParaRPr>`,
/// `CT_TextCharacterProperties`) — this crate only ever writes/reads it as `<a:rPr>` (on
/// `<a:r>`/`<a:br>`), not the other two contexts.
///
/// Not modeled: `lang`/`altLang` (spell-check locale), `kern`/`normalizeH` (kerning threshold,
/// auto-condensing East Asian punctuation — narrow cosmetic refinements; `spc`/`cap` *are* modeled,
/// see [`TextRunProperties::character_spacing_100ths_point`]/[`TextRunProperties::text_caps`];
/// `baseline`/`highlight` are also modeled, see
/// [`TextRunProperties::baseline_1000ths_percent`]/[`TextRunProperties::highlight`]),
/// `hlinkMouseOver` (a separate, rarely-authored hover-only link — only `hlinkClick` is modeled,
/// see [`Hyperlink`]), underline's own independent line/fill overrides (`EG_TextUnderlineLine`/
/// `Fill` — `u`'s color here always follows the text's own `fill`, matching most real-world usage),
/// and `ea`/`cs`/`sym` (East Asian/complex-script/ symbol font overrides — `latin` alone is
/// modeled, same "one font, not a per-script set" simplification `word-ooxml::Run::font_family`
/// already makes).
#[derive(Debug, Clone, PartialEq, Default)]
pub struct TextRunProperties {
    /// `b` (`<a:rPr b="1">`).
    pub bold: bool,
    /// `i`.
    pub italic: bool,
    /// `u`.
    pub underline: Option<TextUnderline>,
    /// `strike`.
    pub strike: Option<TextStrike>,
    /// `EG_FillProperties` — the run's text color (or gradient/pattern/ image, though a flat
    /// [`Fill::Solid`] color covers the overwhelming majority of real documents). Reuses [`Fill`]
    /// directly rather than a narrower color-only field, since the schema itself allows the full
    /// fill choice here, not just `<a:solidFill>`.
    pub fill: Option<Fill>,
    /// `sz`, in hundredths of a point (`ST_TextFontSize`, `100.=400000` — i.e. 1pt to 4,000pt).
    pub font_size_100ths_point: Option<i32>,
    /// `<a:latin typeface="..">` — the run's font family/typeface, e.g. `"Calibri"`. Mirrors
    /// `word-ooxml::Run::font_family` by name for cross-crate consistency (same real-world
    /// concept).
    pub font_family: Option<String>,
    /// `<a:hlinkClick r:id="..">` (`CT_Hyperlink`, point 3) — a clickable hyperlink on this run.
    /// See [`Hyperlink`]'s own doc comment for why this carries an already-resolved relationship id
    /// rather than a raw URL.
    pub hyperlink: Option<Hyperlink>,
    /// `baseline` (`ST_Percentage`, thousandths of a percent) — raises (positive) or lowers
    /// (negative) the run's glyphs relative to the baseline, real PowerPoint's own
    /// superscript/subscript mechanism (its UI writes `30000` for superscript, `-25000` for
    /// subscript). `None` omits the attribute (no offset). Grounded against a real fixture
    /// exercising both signs.
    pub baseline_1000ths_percent: Option<i32>,
    /// `<a:highlight>{color}</a:highlight>` — the run's text-highlight color (like a highlighter
    /// pen), distinct from `fill`, which colors the glyphs themselves. `None` omits the element (no
    /// highlight). Grounded against a real fixture.
    pub highlight: Option<Color>,
    /// `cap` (`ST_TextCapsType`) — forces the run's glyphs to render as small caps or all caps,
    /// independent of the text actually typed (unlike literally typing uppercase letters, the
    /// underlying text stays whatever case it was entered in). `None` omits the attribute (no
    /// forced case). Grounded against a real fixture's slide text (`cap="none"`, PowerPoint's own
    /// explicit "no caps override" — distinct from omitting the attribute, though both render
    /// identically).
    pub text_caps: Option<TextCaps>,
    /// `spc` (`ST_TextSpacingPoint`, hundredths of a, may be negative to tighten spacing) — extra
    /// space inserted between characters. `None` omits the attribute (no adjustment). Grounded
    /// against a real fixture (`spc="70"`, 0.7pt extra tracking).
    pub character_spacing_100ths_point: Option<i32>,
}

impl TextRunProperties {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_bold(mut self, bold: bool) -> Self {
        self.bold = bold;
        self
    }

    pub fn with_italic(mut self, italic: bool) -> Self {
        self.italic = italic;
        self
    }

    pub fn with_underline(mut self, underline: TextUnderline) -> Self {
        self.underline = Some(underline);
        self
    }

    pub fn with_strike(mut self, strike: TextStrike) -> Self {
        self.strike = Some(strike);
        self
    }

    pub fn with_fill(mut self, fill: Fill) -> Self {
        self.fill = Some(fill);
        self
    }

    /// Sets the font size, given in ordinary points (converted to the schema's
    /// hundredths-of-a-point unit internally).
    pub fn with_font_size_points(mut self, points: f64) -> Self {
        self.font_size_100ths_point = Some((points * 100.0).round() as i32);
        self
    }

    pub fn with_font_family(mut self, font_family: impl Into<String>) -> Self {
        self.font_family = Some(font_family.into());
        self
    }

    /// Attaches a hyperlink to this run.
    pub fn with_hyperlink(mut self, hyperlink: Hyperlink) -> Self {
        self.hyperlink = Some(hyperlink);
        self
    }

    /// Sets the run's baseline offset (superscript/subscript), given as an ordinary percentage
    /// (e.g. `30.0` for real PowerPoint's own superscript, `-25.0` for its subscript).
    pub fn with_baseline_percent(mut self, percent: f64) -> Self {
        self.baseline_1000ths_percent = Some((percent * 1000.0).round() as i32);
        self
    }

    /// Sets the run's text-highlight color.
    pub fn with_highlight(mut self, color: Color) -> Self {
        self.highlight = Some(color);
        self
    }

    /// Sets the run's forced letter case (small caps/all caps).
    pub fn with_text_caps(mut self, caps: TextCaps) -> Self {
        self.text_caps = Some(caps);
        self
    }

    /// Sets the run's extra inter-character spacing, given in ordinary points (converted to the
    /// schema's hundredths-of-a-point unit internally; negative tightens spacing).
    pub fn with_character_spacing_points(mut self, points: f64) -> Self {
        self.character_spacing_100ths_point = Some((points * 100.0).round() as i32);
        self
    }
}

/// `ST_TextCapsType`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextCaps {
    /// `"none"` — no forced case (explicitly written, distinct from the field itself being `None`,
    /// which omits the attribute entirely).
    None,
    /// `"small"` — small capital letters.
    Small,
    /// `"all"` — full-size capital letters.
    All,
}

impl TextCaps {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            TextCaps::None => "none",
            TextCaps::Small => "small",
            TextCaps::All => "all",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "none" => TextCaps::None,
            "small" => TextCaps::Small,
            "all" => TextCaps::All,
            _ => return None,
        })
    }
}

/// A clickable hyperlink (`<a:hlinkClick>`, `CT_Hyperlink`).
///
/// Unlike `word_ooxml::Hyperlink` (which stores the actual target URL, or bookmark anchor, and lets
/// its own writer create the relationship at write time), this crate has no access to a
/// host-specific relationship accumulator from within a plain data model or from
/// [`crate::writer::write_text_run`] — resolving `r:id` against an actual OPC package/relationship
/// set is host-specific, the same posture already established for [`BlipFill::relationship_id`]
/// (see that field's own doc comment for the full rationale). `relationship_id` here is therefore
/// an **already-resolved** relationship id (e.g. `"rId4"`), which the host crate must obtain by
/// registering an external relationship (target mode external, pointing at the real URL) itself
/// before constructing this value — see `powerpoint-ooxml::AutoShape::hyperlink` for the
/// shape-level equivalent, which — being entirely host-owned — *does* take a plain URL directly,
/// since that crate's own writer controls relationship registration end to end for that field.
///
/// Grounded against real fixtures confirming `<a:hlinkClick r:id=".."/>` living directly inside
/// `<p:cNvPr>` (the shape-level placement this crate's own writer uses) as well as inside `<a:rPr>`
/// for run-level links.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Hyperlink {
    /// `r:id` — `None` omits the attribute (schema-valid: `CT_Hyperlink` allows a bare
    /// `<a:hlinkClick/>` with only `action`/other attributes set, though this crate has no use for
    /// that case today).
    pub relationship_id: Option<String>,
    /// `tooltip` — text shown in a tooltip when hovering the link.
    pub tooltip: Option<String>,
}

impl Hyperlink {
    /// Creates a hyperlink referencing the given (already-resolved) relationship id.
    pub fn new(relationship_id: impl Into<String>) -> Self {
        Self {
            relationship_id: Some(relationship_id.into()),
            tooltip: None,
        }
    }

    pub fn with_tooltip(mut self, tooltip: impl Into<String>) -> Self {
        self.tooltip = Some(tooltip.into());
        self
    }
}

/// `ST_TextUnderlineType`'s full set of 18 named underline styles.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextUnderline {
    None,
    Words,
    Single,
    Double,
    Heavy,
    Dotted,
    DottedHeavy,
    Dash,
    DashHeavy,
    DashLong,
    DashLongHeavy,
    DotDash,
    DotDashHeavy,
    DotDotDash,
    DotDotDashHeavy,
    Wavy,
    WavyHeavy,
    WavyDouble,
}

impl TextUnderline {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            TextUnderline::None => "none",
            TextUnderline::Words => "words",
            TextUnderline::Single => "sng",
            TextUnderline::Double => "dbl",
            TextUnderline::Heavy => "heavy",
            TextUnderline::Dotted => "dotted",
            TextUnderline::DottedHeavy => "dottedHeavy",
            TextUnderline::Dash => "dash",
            TextUnderline::DashHeavy => "dashHeavy",
            TextUnderline::DashLong => "dashLong",
            TextUnderline::DashLongHeavy => "dashLongHeavy",
            TextUnderline::DotDash => "dotDash",
            TextUnderline::DotDashHeavy => "dotDashHeavy",
            TextUnderline::DotDotDash => "dotDotDash",
            TextUnderline::DotDotDashHeavy => "dotDotDashHeavy",
            TextUnderline::Wavy => "wavy",
            TextUnderline::WavyHeavy => "wavyHeavy",
            TextUnderline::WavyDouble => "wavyDbl",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "none" => TextUnderline::None,
            "words" => TextUnderline::Words,
            "sng" => TextUnderline::Single,
            "dbl" => TextUnderline::Double,
            "heavy" => TextUnderline::Heavy,
            "dotted" => TextUnderline::Dotted,
            "dottedHeavy" => TextUnderline::DottedHeavy,
            "dash" => TextUnderline::Dash,
            "dashHeavy" => TextUnderline::DashHeavy,
            "dashLong" => TextUnderline::DashLong,
            "dashLongHeavy" => TextUnderline::DashLongHeavy,
            "dotDash" => TextUnderline::DotDash,
            "dotDashHeavy" => TextUnderline::DotDashHeavy,
            "dotDotDash" => TextUnderline::DotDotDash,
            "dotDotDashHeavy" => TextUnderline::DotDotDashHeavy,
            "wavy" => TextUnderline::Wavy,
            "wavyHeavy" => TextUnderline::WavyHeavy,
            "wavyDbl" => TextUnderline::WavyDouble,
            _ => return None,
        })
    }
}

/// `ST_TextStrikeType`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextStrike {
    None,
    Single,
    Double,
}

impl TextStrike {
    pub(crate) fn xml_token(&self) -> &'static str {
        match self {
            TextStrike::None => "noStrike",
            TextStrike::Single => "sngStrike",
            TextStrike::Double => "dblStrike",
        }
    }

    pub(crate) fn from_xml_token(token: &str) -> Option<Self> {
        Some(match token {
            "noStrike" => TextStrike::None,
            "sngStrike" => TextStrike::Single,
            "dblStrike" => TextStrike::Double,
            _ => return None,
        })
    }
}