Skip to main content

materialize

Function materialize 

Source
pub fn materialize(
    target: &mut Document,
    packs: &[LibraryPack],
    pkg_id: &str,
    item: &str,
    page_id: &str,
    id_base: &str,
    at: (f64, f64),
) -> Result<AddOutcome, AddError>
Expand description

Materialize the pack item pkg_id#item into target at (at_x, at_y) on the page page_id, returning the AddOutcome describing what was added.

This is the PURE core of library add: it mutates the parsed target Document in place and performs NO filesystem or process I/O (the caller resolves the pack set, reads files, formats, and writes). Steps:

  1. Resolve the FIRST pack in packs whose id == pkg_id (project shadows preset); load its full Document and find the ComponentDef == item.
  2. Copy that component into target under a namespaced id (lib.<sanitized-pkg>.<item>), REUSING an existing copy if present (dedup). Child ids are left untouched (instance expansion prefixes them at compile).
  3. Copy ALL of the pack’s tokens/styles/assets into target, deduping by id; a same-id-but-different-definition collision keeps the target’s existing one and records a library.dependency_conflict warning.
  4. Generate a unique instance id (base = id_base) against ALL target ids, insert an InstanceNode referencing the copied component onto the page.
  5. Record a libraries entry for pkg_id (if absent) and a unique provenance record linking the instance to the item.

§Errors

Returns AddError when the package or item is unknown (the message lists the available options), or the page id is not found.