Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

22.6 KB
Raw Blame
//! The document model: what a node is and looks like, independent of the
//! kiwi encoding.
//!
//! A [`Props`] holds every property a node change can carry, each optional:
//! nodes, instance overrides, and the layout Figma derived for instance
//! sublayers are all partial descriptions of a node, merged with
//! [`Props::merge`].

use serde::Serialize;
use std::fmt;
use std::sync::Arc;

pub mod geom;
pub mod handoff;
pub mod library;
pub mod paint;
pub mod prototype;
pub mod text;
pub mod variables;

pub use geom::{Affine, Rect, Vec2};
pub use handoff::{
    Axis, ExportConstraint, ExportFormat, ExportSetting, GridAlign, GridPattern, Guide, LayoutGrid,
};
pub use library::LibraryLink;
pub use paint::{
    BlendMode, Color, ColorStop, Effect, EffectKind, GradientKind, ImageFilters, ImagePaint,
    ImageScaleMode, Paint, PaintKind, PatternAlign, PatternLayout, PatternPaint,
};
pub use prototype::{Action, FlowStart, Interaction, OverlaySettings};
pub use text::{Baseline, Decoration, Glyph, StyleRun, TextContent, TextLayout, TextStyle};
pub use variables::{Variable, VariableMode, VariableType, VariableValue};

/// A node id, written `session:local` (Figma's node ids).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Guid {
    pub session: u32,
    pub local: u32,
}

impl fmt::Display for Guid {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}:{}", self.session, self.local)
    }
}

impl Guid {
    pub fn parse(s: &str) -> Option<Guid> {
        let (a, b) = s.split_once(':').or_else(|| s.split_once('-'))?;
        Some(Guid {
            session: a.parse().ok()?,
            local: b.parse().ok()?,
        })
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum NodeType {
    Document,
    Canvas,
    Group,
    Frame,
    BooleanOperation,
    Vector,
    Star,
    Line,
    Ellipse,
    Rectangle,
    RegularPolygon,
    RoundedRectangle,
    Text,
    Slice,
    Symbol,
    Instance,
    Sticky,
    ShapeWithText,
    Connector,
    CodeBlock,
    Widget,
    Stamp,
    Media,
    Highlight,
    Section,
    SectionOverlay,
    WashiTape,
    Table,
    TableCell,
    Slide,
    TextPath,
    Other,
}

impl NodeType {
    pub fn parse(s: &str) -> NodeType {
        use NodeType::*;
        match s {
            "DOCUMENT" => Document,
            "CANVAS" => Canvas,
            "GROUP" => Group,
            "FRAME" => Frame,
            "BOOLEAN_OPERATION" => BooleanOperation,
            "VECTOR" => Vector,
            "STAR" => Star,
            "LINE" => Line,
            "ELLIPSE" => Ellipse,
            "RECTANGLE" => Rectangle,
            "REGULAR_POLYGON" => RegularPolygon,
            "ROUNDED_RECTANGLE" => RoundedRectangle,
            "TEXT" => Text,
            "SLICE" => Slice,
            "SYMBOL" => Symbol,
            "INSTANCE" => Instance,
            "STICKY" => Sticky,
            "SHAPE_WITH_TEXT" => ShapeWithText,
            "CONNECTOR" => Connector,
            "CODE_BLOCK" => CodeBlock,
            "WIDGET" => Widget,
            "STAMP" => Stamp,
            "MEDIA" => Media,
            "HIGHLIGHT" => Highlight,
            "SECTION" => Section,
            "SECTION_OVERLAY" => SectionOverlay,
            "WASHI_TAPE" => WashiTape,
            "TABLE" => Table,
            "TABLE_CELL" => TableCell,
            "SLIDE" => Slide,
            "TEXT_PATH" => TextPath,
            _ => Other,
        }
    }

    /// Frame-like containers: they have their own fills and strokes, may
    /// clip their children, and are selected directly on the canvas.
    pub fn is_frame_like(self) -> bool {
        matches!(
            self,
            NodeType::Frame
                | NodeType::Symbol
                | NodeType::Instance
                | NodeType::Section
                | NodeType::Table
                | NodeType::TableCell
                | NodeType::Slide
                | NodeType::Sticky
                | NodeType::ShapeWithText
        )
    }

    /// Text, laid out in lines or along a path.
    pub fn is_text(self) -> bool {
        matches!(self, NodeType::Text | NodeType::TextPath)
    }

    /// Nodes whose children are drawn (boolean operations draw only their
    /// combined geometry; their children are operands).
    pub fn draws_children(self) -> bool {
        !matches!(self, NodeType::BooleanOperation)
    }

    /// The label the layers panel and inspector use.
    pub fn label(self) -> &'static str {
        use NodeType::*;
        match self {
            Document => "Document",
            Canvas => "Page",
            Group => "Group",
            Frame => "Frame",
            BooleanOperation => "Boolean",
            Vector => "Vector",
            Star => "Star",
            Line => "Line",
            Ellipse => "Ellipse",
            Rectangle | RoundedRectangle => "Rectangle",
            RegularPolygon => "Polygon",
            Text => "Text",
            Slice => "Slice",
            Symbol => "Component",
            Instance => "Instance",
            Sticky => "Sticky",
            ShapeWithText => "Shape",
            Connector => "Connector",
            CodeBlock => "Code block",
            Widget => "Widget",
            Stamp => "Stamp",
            Media => "Media",
            Highlight => "Highlight",
            Section => "Section",
            SectionOverlay => "Section",
            WashiTape => "Washi tape",
            Table => "Table",
            TableCell => "Cell",
            Slide => "Slide",
            TextPath => "Text",
            Other => "Layer",
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, Serialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum StrokeAlign {
    #[default]
    Center,
    Inside,
    Outside,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, Serialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum WindingRule {
    #[default]
    NonZero,
    EvenOdd,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, Serialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum MaskType {
    #[default]
    Alpha,
    Outline,
    Luminance,
}

/// One geometry path of a node: an index into the file's blobs.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct PathRef {
    pub winding: WindingRule,
    pub blob: u32,
    /// The vector region style it is filled with (an id in
    /// [`Props::vector_styles`]); 0 for the node's own fills.
    pub style: u32,
}

/// Per-corner radii, clockwise from the top left.
#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize)]
pub struct CornerRadii {
    pub top_left: f32,
    pub top_right: f32,
    pub bottom_right: f32,
    pub bottom_left: f32,
}

impl CornerRadii {
    pub fn uniform(r: f32) -> Self {
        Self {
            top_left: r,
            top_right: r,
            bottom_right: r,
            bottom_left: r,
        }
    }

    pub fn is_zero(&self) -> bool {
        self.top_left <= 0.0
            && self.top_right <= 0.0
            && self.bottom_right <= 0.0
            && self.bottom_left <= 0.0
    }
}

/// Auto layout, for the inspector.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AutoLayout {
    pub mode: String,
    pub spacing: f32,
    pub padding_top: f32,
    pub padding_right: f32,
    pub padding_bottom: f32,
    pub padding_left: f32,
    pub primary_align: Option<String>,
    pub counter_align: Option<String>,
    pub wrap: bool,
    /// `FIXED`, or the frame hugs its content (`RESIZE_TO_FIT…`; the
    /// default along the primary axis).
    pub primary_sizing: Option<String>,
    /// Along the counter axis the default is `FIXED`.
    pub counter_sizing: Option<String>,
    pub counter_spacing: f32,
    /// Earlier children draw on top.
    pub reverse_z: bool,
    /// Strokes take up space: the frame's own pad its content, and its
    /// children's outer strokes count in their size.
    pub strokes_in_layout: bool,
}

impl AutoLayout {
    pub fn horizontal(&self) -> bool {
        self.mode == "HORIZONTAL"
    }

    /// Whether children are placed in a single row or column (the layouts
    /// the engine reflows; wrapping and grids keep Figma's positions).
    pub fn is_stack(&self) -> bool {
        (self.mode == "HORIZONTAL" || self.mode == "VERTICAL") && !self.wrap
    }

    pub fn hugs_primary(&self) -> bool {
        self.primary_sizing.as_deref() != Some("FIXED")
    }

    pub fn hugs_counter(&self) -> bool {
        self.counter_sizing
            .as_deref()
            .is_some_and(|s| s.starts_with("RESIZE_TO_FIT"))
    }
}

/// How a layer sits in its auto layout parent.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct LayoutChild {
    /// Share of the free space along the primary axis ("fill"); 0 is fixed.
    pub grow: Option<f32>,
    /// `STRETCH` fills the counter axis; `MIN`, `CENTER`, `MAX` override the
    /// parent's alignment; `AUTO` follows it.
    pub align: Option<Arc<str>>,
    /// Positioned freely, outside the flow.
    pub absolute: Option<bool>,
    /// Size limits (0 means none), kept when the layout sizes the layer.
    pub min_size: Option<Vec2>,
    pub max_size: Option<Vec2>,
}

impl LayoutChild {
    pub fn fills_primary(&self) -> bool {
        self.grow.unwrap_or(0.0) > 0.0
    }

    pub fn stretches(&self) -> bool {
        self.align.as_deref() == Some("STRETCH")
    }

    pub fn is_absolute(&self) -> bool {
        self.absolute.unwrap_or(false)
    }

    /// `v` within the limits on one axis (`x` or not).
    pub fn clamp(&self, v: f64, x: bool) -> f64 {
        let pick = |s: Option<Vec2>| s.map(|s| if x { s.x } else { s.y }).filter(|&l| l > 0.0);
        let v = match pick(self.max_size) {
            Some(max) => v.min(max),
            None => v,
        };
        match pick(self.min_size) {
            Some(min) => v.max(min),
            None => v,
        }
    }
}

/// A reference from a component's sublayer to one of the component's
/// properties: the sublayer's `field` follows the property's value.
#[derive(Clone, Debug, PartialEq)]
pub struct PropRef {
    pub def_id: Guid,
    pub field: PropField,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PropField {
    Visible,
    Text,
    SwappedSymbol,
    Other,
}

/// A value assigned to a component property by an instance.
#[derive(Clone, Debug, PartialEq)]
pub struct PropAssignment {
    pub def_id: Guid,
    pub value: PropValue,
}

#[derive(Clone, Debug, PartialEq)]
pub enum PropValue {
    Bool(bool),
    Text(Arc<str>),
    Symbol(Guid),
    Other,
}

/// A component property definition (on a component or component set).
#[derive(Clone, Debug, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct PropDef {
    #[serde(skip)]
    pub id: Guid,
    pub name: String,
    /// `BOOL`, `TEXT`, `INSTANCE_SWAP`, `VARIANT`, …
    pub kind: String,
    /// The value instances show unless they assign another.
    #[serde(skip)]
    pub initial: Option<PropValue>,
    /// For instance swap properties: keys of the components (or component
    /// sets) offered first.
    #[serde(skip)]
    pub preferred: Arc<[Arc<str>]>,
}

/// A variant's value for one of its component set's variant properties.
#[derive(Clone, Debug, PartialEq)]
pub struct VariantSpec {
    pub def_id: Guid,
    pub value: Arc<str>,
}

/// The order a component set lists a variant property's values in.
#[derive(Clone, Debug, PartialEq)]
pub struct VariantOrder {
    pub property: Arc<str>,
    pub values: Arc<[Arc<str>]>,
}

/// What a shared style node styles.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum StyleType {
    Fill,
    Text,
    Effect,
    Grid,
    Other,
}

impl StyleType {
    pub fn parse(s: &str) -> StyleType {
        match s {
            "FILL" => StyleType::Fill,
            "TEXT" => StyleType::Text,
            "EFFECT" => StyleType::Effect,
            "GRID" => StyleType::Grid,
            _ => StyleType::Other,
        }
    }

    pub fn name(self) -> &'static str {
        match self {
            StyleType::Fill => "FILL",
            StyleType::Text => "TEXT",
            StyleType::Effect => "EFFECT",
            StyleType::Grid => "GRID",
            StyleType::Other => "NONE",
        }
    }
}

/// What makes a node an instance.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct SymbolData {
    pub symbol_id: Option<Guid>,
    pub overrides: Arc<[Props]>,
    pub uniform_scale: Option<f32>,
}

/// A vector layer's editable geometry (`vectorData`): its network blob,
/// whose coordinates the layer's size scales from `normalized_size`.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct VectorData {
    pub network_blob: Option<u32>,
    pub normalized_size: Option<Vec2>,
}

/// Every property of a node change; `None` means "not set here".
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Props {
    pub guid: Option<Guid>,
    pub parent: Option<Guid>,
    pub position: Option<Arc<str>>,
    pub node_type: Option<NodeType>,
    pub name: Option<Arc<str>>,
    pub visible: Option<bool>,
    pub locked: Option<bool>,
    pub opacity: Option<f32>,
    pub blend_mode: Option<BlendMode>,
    pub size: Option<Vec2>,
    pub transform: Option<Affine>,
    pub mask: Option<bool>,
    pub mask_type: Option<MaskType>,
    pub fills: Option<Arc<[Paint]>>,
    pub strokes: Option<Arc<[Paint]>>,
    pub stroke_weight: Option<f32>,
    /// Stroke weights per side (top, right, bottom, left) when they are
    /// set independently.
    pub stroke_sides: Option<[f32; 4]>,
    pub stroke_align: Option<StrokeAlign>,
    pub stroke_cap: Option<Arc<str>>,
    pub stroke_join: Option<Arc<str>>,
    pub dash_pattern: Option<Arc<[f32]>>,
    pub fill_geometry: Option<Arc<[PathRef]>>,
    pub stroke_geometry: Option<Arc<[PathRef]>>,
    pub effects: Option<Arc<[Effect]>>,
    pub corner_radius: Option<f32>,
    pub corner_radii: Option<CornerRadii>,
    pub corner_smoothing: Option<f32>,
    /// Ellipse start angle, end angle (radians), and inner radius ratio.
    pub arc_data: Option<[f32; 3]>,
    /// `frameMaskDisabled`: frames clip their content unless this is set.
    pub clip_disabled: Option<bool>,
    pub background_color: Option<Color>,
    pub internal_only: Option<bool>,
    pub text_content: Option<Arc<TextContent>>,
    pub text_layout: Option<Arc<TextLayout>>,
    pub text_style: Option<Arc<TextStyle>>,
    pub symbol: Option<Arc<SymbolData>>,
    pub derived: Option<Arc<[Props]>>,
    pub swapped_symbol: Option<Guid>,
    pub prop_assignments: Option<Arc<[PropAssignment]>>,
    pub prop_refs: Option<Arc<[PropRef]>>,
    pub prop_defs: Option<Arc<[PropDef]>>,
    pub guid_path: Option<Arc<[Guid]>>,
    pub override_key: Option<Guid>,
    pub auto_layout: Option<Arc<AutoLayout>>,
    pub layout_child: Option<LayoutChild>,
    pub export_settings: Option<Arc<[ExportSetting]>>,
    pub boolean_operation: Option<Arc<str>>,
    pub vector_data: Option<Arc<VectorData>>,
    pub constraints: Option<(Arc<str>, Arc<str>)>,
    pub description: Option<Arc<str>>,
    pub is_state_group: Option<bool>,
    /// Shared styles the fills, strokes, and effects come from.
    pub fill_style: Option<Guid>,
    pub stroke_style: Option<Guid>,
    pub effect_style: Option<Guid>,
    /// The shared text style a text layer's type comes from.
    pub text_style_id: Option<Guid>,
    /// A component's (or style's, or variable's) library key: set when it
    /// is published, and on copies of library assets (`key`, or
    /// `componentKey` on Figma's copies of library components).
    pub key: Option<Arc<str>>,
    /// On shared style nodes: what they style, their place in the styles
    /// list, and whether they were deleted (kept for layers using them).
    pub style_type: Option<StyleType>,
    pub sort_position: Option<Arc<str>>,
    pub soft_deleted: Option<bool>,
    /// On a variant: its value for each of its set's variant properties.
    pub variant_specs: Option<Arc<[VariantSpec]>>,
    /// On a component set: the order of each variant property's values.
    pub variant_orders: Option<Arc<[VariantOrder]>>,
    /// On an instance in a component: its properties show on the
    /// component's instances ("exposed" nested instances).
    pub props_bubbled: Option<bool>,
    /// On variable nodes: the variable's collection, kind, and values.
    pub variable: Option<Arc<Variable>>,
    /// On variable collections: their modes, in order (the first is the
    /// default).
    pub variable_modes: Option<Arc<[VariableMode]>>,
    /// The mode a frame (or page) picks per collection: `(collection, mode)`.
    pub mode_by_set: Option<Arc<[(Guid, Guid)]>>,
    /// The layers Figma generates for FigJam objects (a sticky's or shape's
    /// background and text, a connector's line and label): paints and text
    /// from `nodeGenerationData` merged with the layout Figma derived for
    /// them (`derivedImmutableFrameData`), each with its guid path.
    pub generated: Option<Arc<[Props]>>,
    /// Fills of a vector network's regions that have their own
    /// (`vectorData.styleOverrideTable`), by the style id their geometry
    /// carries.
    pub vector_styles: Option<Arc<[StyleRun]>>,
    /// A frame's layout grids (drawn over the canvas, never exported).
    pub layout_grids: Option<Arc<[LayoutGrid]>>,
    /// Ruler guides of a page or frame.
    pub guides: Option<Arc<[Guide]>>,
    /// Prototype interactions on the layer.
    pub interactions: Option<Arc<[Interaction]>>,
    /// A flow starting point on a top-level frame.
    pub flow_start: Option<Arc<FlowStart>>,
    /// How the frame shows as an overlay.
    pub overlay: Option<Arc<OverlaySettings>>,
    /// A page's prototype start frame, in files from before flows.
    pub prototype_start: Option<Guid>,
    /// Being published from a library, or coming from one.
    pub library: Option<Arc<LibraryLink>>,
    /// Macro's own data on the node (`pluginData` under
    /// [`library::MACRO_PLUGIN`]): key and value.
    pub macro_data: Option<library::MacroData>,
    /// On an instance's override or derived layout entry: made by the
    /// editor (and written when saving); the file's own are kept as they
    /// are.
    pub recomputed: bool,
}

macro_rules! merge_fields {
    ($dst:ident, $src:ident; $($f:ident),* $(,)?) => {
        $(
            if $src.$f.is_some() {
                $dst.$f = $src.$f.clone();
            }
        )*
    };
}

impl Props {
    /// Sets every field `other` sets, leaving identity (guid, parent, and
    /// position) alone.
    pub fn merge(&mut self, other: &Props) {
        merge_fields!(self, other;
            node_type, name, visible, locked, opacity, blend_mode, size, transform, mask,
            mask_type, fills, strokes, stroke_weight, stroke_sides, stroke_align, stroke_cap,
            stroke_join,
            dash_pattern, fill_geometry, stroke_geometry, effects, corner_radius, corner_radii,
            corner_smoothing, arc_data, clip_disabled, background_color, internal_only, text_content,
            text_layout, text_style,
            symbol, derived, swapped_symbol, prop_assignments, prop_refs, prop_defs,
            override_key, auto_layout, layout_child, export_settings, boolean_operation, vector_data, constraints,
            description, is_state_group, fill_style, stroke_style, effect_style, generated,
            vector_styles,
            text_style_id, key, style_type, sort_position, soft_deleted, variant_specs,
            variant_orders, props_bubbled, variable, variable_modes, mode_by_set,
            layout_grids, guides,
            interactions, flow_start, overlay, prototype_start, library, macro_data,
        );
    }

    pub fn node_type(&self) -> NodeType {
        self.node_type.unwrap_or(NodeType::Other)
    }

    pub fn name(&self) -> &str {
        self.name.as_deref().unwrap_or("")
    }

    pub fn visible(&self) -> bool {
        self.visible.unwrap_or(true)
    }

    pub fn opacity(&self) -> f32 {
        self.opacity.unwrap_or(1.0).clamp(0.0, 1.0)
    }

    pub fn blend_mode(&self) -> BlendMode {
        self.blend_mode.unwrap_or(BlendMode::PassThrough)
    }

    pub fn size(&self) -> Vec2 {
        self.size.unwrap_or_default()
    }

    pub fn transform(&self) -> Affine {
        self.transform.unwrap_or_default()
    }

    pub fn is_mask(&self) -> bool {
        self.mask.unwrap_or(false)
    }

    pub fn fills(&self) -> &[Paint] {
        self.fills.as_deref().unwrap_or(&[])
    }

    pub fn strokes(&self) -> &[Paint] {
        self.strokes.as_deref().unwrap_or(&[])
    }

    pub fn effects(&self) -> &[Effect] {
        self.effects.as_deref().unwrap_or(&[])
    }

    pub fn fill_geometry(&self) -> &[PathRef] {
        self.fill_geometry.as_deref().unwrap_or(&[])
    }

    pub fn stroke_geometry(&self) -> &[PathRef] {
        self.stroke_geometry.as_deref().unwrap_or(&[])
    }

    pub fn stroke_weight(&self) -> f32 {
        self.stroke_weight.unwrap_or(1.0)
    }

    pub fn stroke_align(&self) -> StrokeAlign {
        self.stroke_align.unwrap_or_default()
    }

    /// The radii of a rectangle-like node.
    pub fn radii(&self) -> CornerRadii {
        self.corner_radii
            .unwrap_or_else(|| CornerRadii::uniform(self.corner_radius.unwrap_or(0.0)))
    }

    /// Whether the node clips its children to its shape.
    pub fn clips_content(&self) -> bool {
        self.node_type().is_frame_like() && !self.clip_disabled.unwrap_or(false)
    }

    /// Whether any paint is visible.
    pub fn has_visible_fills(&self) -> bool {
        self.fills().iter().any(Paint::is_visible)
    }

    /// Figma ignores stored shadow spread on open arcs and arbitrary paths.
    /// Containers support it only when their filled shape clips the contents.
    pub fn supports_shadow_spread(&self) -> bool {
        match self.node_type() {
            NodeType::Rectangle | NodeType::RoundedRectangle => true,
            NodeType::Ellipse => self.arc_data.is_none_or(|[start, end, inner]| {
                inner == 0.0 && (end - start).abs() >= std::f32::consts::TAU - 1e-5
            }),
            NodeType::Frame | NodeType::Symbol | NodeType::Instance => {
                self.clips_content() && self.has_visible_fills()
            }
            _ => false,
        }
    }

    /// The library this node is a copy of an asset from.
    pub fn library_source(&self) -> Option<&str> {
        self.library.as_ref()?.source.as_deref()
    }

    /// One of Macro's values on the node (see [`Props::macro_data`]).
    pub fn macro_value(&self, key: &str) -> Option<&str> {
        self.macro_data
            .as_deref()?
            .iter()
            .find(|(k, _)| k.as_ref() == key)
            .map(|(_, v)| v.as_ref())
    }

    pub fn has_visible_strokes(&self) -> bool {
        self.strokes().iter().any(Paint::is_visible) && self.stroke_weight() > 0.0
    }
}