Import sap-architecture skill
This commit is contained in:
@@ -0,0 +1,123 @@
|
||||
# draw.io / mxGraph authoring gotchas
|
||||
|
||||
Encoding and alignment rules that apply whenever this skill **writes or edits
|
||||
mxCell XML directly** — i.e. during surgical relabels (step 4), when adding
|
||||
cards/edges next to template cells, and in `render_semantic.py`-derived output.
|
||||
Violations are silent at write time and only visible when the user opens the
|
||||
file: blank icons, "duplicate id" rejections, or connectors cutting through
|
||||
artwork. `validate.py` mechanically checks §§1–2 and the structural parts of §7.
|
||||
|
||||
Scaffolded SAP templates already satisfy all of this — these rules matter for
|
||||
the cells **you** add or change.
|
||||
|
||||
## 1. Embedded-image data URIs must OMIT `;base64`
|
||||
|
||||
draw.io style strings are `;`-delimited key=value lists. A standard data URI
|
||||
(`data:image/svg+xml;base64,PHN2...`) contains a `;` — draw.io truncates the
|
||||
`image=` value at that semicolon and starts parsing `base64,PHN2...` as a new
|
||||
style key. Result: every icon renders blank, with no error.
|
||||
|
||||
- **Correct (draw.io style):** `image=data:image/svg+xml,PHN2Zy8+;`
|
||||
(payload IS still base64-encoded; only the `;base64` marker is dropped —
|
||||
draw.io's own convention, and what the bundled SAP libraries ship.)
|
||||
- **Incorrect:** `image=data:image/svg+xml;base64,PHN2Zy8+;`
|
||||
- Plain SVG/HTML is the opposite: an `<image href>` **requires** the standard
|
||||
`;base64` form. If you generate both a `.drawio` and an SVG preview from the
|
||||
same data, the two encodings must differ.
|
||||
|
||||
`extract_icon.py` / `extract_asset.py` emit the correct form — this rule bites
|
||||
only when embedding a third-party logo or UI5 icon-font SVG by hand.
|
||||
|
||||
## 2. Root-cell skeleton and reserved ids
|
||||
|
||||
Every diagram page must begin with a **parentless root cell**, then a **layer
|
||||
cell parented to it**, before any content:
|
||||
```xml
|
||||
<mxCell id="0" />
|
||||
<mxCell id="1" parent="0" />
|
||||
```
|
||||
`0`/`1` are mxGraph's defaults, but the SAP corpus frequently uses namespaced
|
||||
equivalents (`<prefix>-0`, `<prefix>-1`) — the *structure* is what matters, and
|
||||
`validate.py` checks it. Two failure modes for hand-authored pages:
|
||||
|
||||
- Omitting the two root cells entirely → draw.io rejects the file.
|
||||
- A content cell reusing the page's root/layer id (easy when deriving ids from
|
||||
numeric counters, colliding with literal `0`/`1`) → "duplicate id", whole
|
||||
file rejected. Namespace generated ids (`n-<id>`, `edge-3`, `pill-2`).
|
||||
|
||||
Ids must be unique within a page; each `<diagram>` page has its own id space.
|
||||
|
||||
## 3. Z-order is document order
|
||||
|
||||
Later cells render on top. Emit **edges before vertices** so connectors sit
|
||||
behind nodes/icons (SAP's files do this; they never rely on opaque icon
|
||||
backings). draw.io resolves an edge's `source`/`target` by id even when those
|
||||
cells are declared later — forward references are fine. When inserting new
|
||||
cards into a template, insert them **after** the edges that touch them.
|
||||
|
||||
## 4. Connectors must attach to facing connection points
|
||||
|
||||
Without fixed connection points, draw.io anchors edges center-to-center and a
|
||||
line can cut straight through nodes that sit between endpoints. Give every
|
||||
added edge directional exit/entry on the border side facing the counterpart:
|
||||
|
||||
```
|
||||
exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;
|
||||
```
|
||||
(source's right edge → target's left edge, for a left-to-right flow; use
|
||||
Y 0/1 with X 0.5 for vertical). Combine with `edgeStyle=orthogonalEdgeStyle;
|
||||
rounded=0;orthogonalLoop=1;jettySize=auto;` so the router runs segments through
|
||||
the gaps between columns. Z-order alone is never the fix for edges crossing
|
||||
icons. This complements the center-alignment rule in `shapes-and-edges.md`:
|
||||
aligned centers make the edge *straight*; facing anchors make it *dock* on the
|
||||
correct sides.
|
||||
|
||||
## 5. Explicit waypoints
|
||||
|
||||
To force a route (e.g. through a routing channel between zones), put bend
|
||||
points inside the edge geometry — intermediate points only; endpoints come
|
||||
from the cells:
|
||||
|
||||
```xml
|
||||
<mxGeometry relative="1" as="geometry">
|
||||
<Array as="points"><mxPoint x="520" y="140"/><mxPoint x="520" y="260"/></Array>
|
||||
</mxGeometry>
|
||||
```
|
||||
|
||||
Keep waypoint coordinates on the 10-px grid like everything else.
|
||||
|
||||
## 6. Image aspect ratio & inscription
|
||||
|
||||
`imageAspect=1` preserves proportions (`0` stretches to the cell box — wide
|
||||
wordmark logos become distorted). The SAP corpus itself uses `imageAspect=0`
|
||||
on cells whose geometry was hand-sized to the artwork, so this is **not** a
|
||||
validator check — it's a rule for logos *you* embed, where the cell box rarely
|
||||
matches the source aspect exactly. In SVG the equivalent is
|
||||
`preserveAspectRatio="xMidYMid meet"`. Square logos placed on a circular tile
|
||||
must be inscribed: icon side ≤ tile diameter / √2, or the corners poke past
|
||||
the circle (e.g. a 52-px tile fits at most a ~36-px square icon).
|
||||
|
||||
## 7. Structure & page setup
|
||||
|
||||
- Skeleton: `<mxfile><diagram id="..." name="..."><mxGraphModel ...><root>` +
|
||||
the two reserved cells, then content. Emit uncompressed XML — never the
|
||||
base64-deflate `<diagram>` payload form.
|
||||
- Every vertex needs `vertex="1"` + `<mxGeometry x y width height as="geometry"/>`;
|
||||
every edge `edge="1"` + resolvable `source`/`target` (or explicit
|
||||
`sourcePoint`/`targetPoint` for floating edges); every cell (except `0`) a
|
||||
valid `parent`.
|
||||
- Children of a container (`container=1` or any parented vertex) use
|
||||
coordinates **relative to the parent**, not the canvas. When re-parenting an
|
||||
icon into a card (the "tucked inside a card" pattern), convert its x/y to
|
||||
card-local values.
|
||||
- Escape XML in labels/attrs: `&` `<` `>` → `&` `<` `>`; `html=1`
|
||||
when the label carries HTML.
|
||||
|
||||
## 8. Edge routing extras seen in the SAP corpus
|
||||
|
||||
- `entityRelationEdgeStyle` — perpendicular jetty stubs; SAP uses it for
|
||||
*indirect* flows where orthogonal elbows would read as a direct chain.
|
||||
- `targetPerimeterSpacing=15` — leaves a visual gap before the target border so
|
||||
arrowheads don't kiss the stroke.
|
||||
- `jumpStyle=none` — edge crossings drawn flat, no hop arcs. Don't enable
|
||||
jumps; SAP's published files never use them.
|
||||
Reference in New Issue
Block a user