isointerop

Documentation

Overview

Package isointerop is an OPTIONAL, SEPARATE interoperability layer for the isometric diagram widget (toolkit.IsoDiagram). It reads the PUBLIC JSON export of the third-party isoflow / FossFLOW isometric editor and TRANSLATES it into our own native document model (toolkit.IsoDoc).

It is deliberately not part of the toolkit's native schema and never alters it: importing the core toolkit pulls in nothing from here, and this package only ever CONSTRUCTS native entities and hands them to the root package's own codec (toolkit.MarshalIsoDocument) — it does not reimplement the native "#rrggbbaa"/enum encoding, and it copies no isoflow code. The structs under "external isoflow export format" below exist solely to DECODE isoflow's documented JSON; they mirror that public format, not our model, and are clearly fenced off from our native types.

The importer never panics: malformed JSON, a wrong-typed field or a missing required id is a returned error; anything that has no faithful native equivalent (a connector anchored to a free tile, a dangling reference, an icon with no counterpart in our registry, dropped metadata) is recorded in the returned ImportReport rather than silently lost.

Index

• type ImportReport
  • func ImportIsoflowJSON(data []byte) (*toolkit.IsoDoc, ImportReport, error)
• type UnmappedElement
• type UnresolvedIcon

Types

type ImportReport

type ImportReport struct {
	// Nodes, Connectors, Zones, Texts and Layers count the native entities the
	// import produced.
	Nodes, Connectors, Zones, Texts, Layers int
	// Unmapped lists isoflow elements dropped because our model has no faithful
	// equivalent (e.g. a connector anchored to a free tile), each with a reason.
	Unmapped []UnmappedElement
	// UnresolvedIcons lists nodes whose isoflow icon had no counterpart in our
	// icon registry; each such node imported with the fallback shape.
	UnresolvedIcons []UnresolvedIcon
	// Notes records lossy-but-acceptable mappings and ignored metadata (dropped
	// connector waypoints, approximate text sizes, ignored orientation, top-level
	// title/description, and so on).
	Notes []string
}

ImportReport is the accounting of one import: how many native entities of each family were produced, plus every isoflow element that could not be mapped faithfully, so nothing is lost silently.

func ImportIsoflowJSON

func ImportIsoflowJSON(data []byte) (*toolkit.IsoDoc, ImportReport, error)

ImportIsoflowJSON parses the public isoflow / FossFLOW JSON export in data and builds an equivalent native toolkit.IsoDoc, returning it alongside an ImportReport that accounts for every imported entity and every element that could not be mapped faithfully.

Mapping (family by family):

• view item -> IsoNode (tile -> X,Y; model item name -> Label; model item icon -> Icon via the registry, unresolved ones reported)
• connector -> IsoConnector (first/last anchor items -> From/To; style, width and palette colour carried over; intermediate waypoints dropped with a note; a free-tile or dangling anchor drops the connector)
• rectangle -> IsoZone (from/to corners -> X,Y,W,H; palette colour, an opaque one made translucent so it tints rather than hides the grid)
• text box -> IsoText (tile -> X,Y; content -> Text; fontSize -> Size approximately; orientation noted as dropped)
• view -> IsoLayer only when the export has more than one view; a single-view export lands on the implicit default layer

Top-level title/description/version/fitToScreen have no document equivalent and are noted as ignored. On malformed JSON, a wrong-typed field or a missing required id it returns a nil document and a clear error (never a panic).

type UnmappedElement

type UnmappedElement struct {
	// Kind is the isoflow element family ("connector", "view-item", ...).
	Kind string
	// ID is the element's isoflow id.
	ID string
	// Reason explains why it was dropped.
	Reason string
}

UnmappedElement is one isoflow element the import could not represent.

type UnresolvedIcon

type UnresolvedIcon struct {
	// NodeID is the native node that fell back to the default shape.
	NodeID string
	// IconID is the isoflow icon id the model item referenced.
	IconID string
	// IconName is the isoflow icon's human name, or empty when the icon id itself
	// was dangling (not present in the export's icons list).
	IconName string
}

UnresolvedIcon records a node whose isoflow icon had no registry counterpart.