figkit 0.1.1__tar.gz → 0.2.0__tar.gz

{figkit-0.1.1 → figkit-0.2.0}/AI_MANUAL.md

@@ -34,9 +34,12 @@ problem with coordinates, and `no issues` when the figure is clean.
 
 * **Units are px. `y` grows downward** (SVG convention): `n` is the top edge,
   `s` the bottom.
-* **Nothing is auto-laid-out.** You place things; figkit measures them
-  accurately (real font metrics from the font file) so relative placement is
-  exact.
+* **Place things relative to each other, not at coordinates.** figkit measures
+  text from the real font file, so `right_of`, `hstack`, `grid` and `fit` land
+  exactly. Typing absolute numbers works but it is the slow path: a redesign
+  then means editing every number by hand, which is the single biggest source
+  of pain reported by people using this library. Reach for §3 and §9 first and
+  drop to coordinates only for the few things that genuinely need them.
 * **Anchors are live references.** `box.e` is not a coordinate — it resolves
   when read. Move the box afterwards and every arrow pointing at it follows.
 * **Every placement call returns `self`**, so it chains:
@@ -55,6 +58,25 @@ problem with coordinates, and `no issues` when the figure is clean.
 
 ---
 
+### Use the layout engine
+
+Most figures are rows, columns, grids and enclosures. Say that, and a later
+change to one label re-flows the rest:
+
+```python
+row = hstack([enc, mid, dec], gap=60, align="center")      # a Group
+col = vstack([row, caption], gap=18, align="center")
+grid(cells, cols=4, gap=(12, 12))
+fit(enc, mid, pad=20, label="Encoder stack")               # boxed cluster
+align([a, b, c], "top"); distribute_h([a, b, c], gap=24)
+```
+
+The full list is §9. `Matrix`, `LabelledMatrix`, `Table`, `Brace`, `Bracket`,
+`Legend`, `ColorBar` and `Panel` (§5, §8) already exist — check before building
+your own.
+
+---
+
 ## 2. Cheat sheet
 
 | Need | Call |
@@ -175,6 +197,55 @@ Common kwargs: `w, h, min_w, min_h, max_w, padding, wrap, align, valign,
 radius, fill, stroke, stroke_width, stroke_dash, opacity, shadow, rotate, z,
 name, style, theme`.
 
+**Every style property, and the aliases that reach it.** A name outside this
+table raises `UnknownProperty` with a suggestion rather than being accepted
+and ignored, so a typo costs you a traceback instead of a wrong figure. The
+booleans `bold=`, `italic=`, `underline=` and `monospace=` expand into these.
+
+| Property | Also accepted as |
+|---|---|
+| **Paint** | |
+| `fill` | `background`, `background_color`, `bg`, `facecolor`, `fill_color` |
+| `fill_opacity` | — |
+| `stroke` | `border`, `border_color`, `edgecolor`, `line_color`, `stroke_color` |
+| `stroke_width` | `border_width`, `linewidth`, `lw`, `stroke_w` |
+| `stroke_opacity` | — |
+| `stroke_dash` | `dash`, `dasharray`, `dashes`, `linestyle`, `ls`, `stroke_dasharray` |
+| `stroke_dashoffset` | — |
+| `stroke_linecap` | `cap`, `linecap` |
+| `stroke_linejoin` | `join`, `linejoin` |
+| `opacity` | `alpha` |
+| `shadow` | — |
+| `background` | — |
+| `image_opacity` | — |
+| **Geometry** | |
+| `radius` | `border_radius`, `corner_radius`, `rounding` |
+| `padding` | — |
+| **Type** | |
+| `font_family` | `family`, `font`, `fontfamily`, `typeface` |
+| `font_size` | `fontsize`, `size` |
+| `font_weight` | `fontweight`, `weight` |
+| `font_style` | `fontstyle` |
+| `color` | `fg`, `foreground`, `text_color` |
+| `line_height` | `leading`, `linespacing` |
+| `letter_spacing` | `tracking` |
+| `word_spacing` | Extra space between words, in figure units |
+| `text_align` | `align`, `ha`, `halign` |
+| `valign` | `va`, `vertical_align` |
+| `text_transform` | `none`, `uppercase`, `lowercase`, or `capitalize` |
+| `text_decoration` | — |
+| **Math** | |
+| `math_backend` | — |
+| `math_color` | — |
+| `math_scale` | — |
+| **Connectors** | |
+| `head` | `arrowhead` |
+| `head_size` | `headsize` |
+| `tail` | `arrowtail` |
+| `tail_size` | `tailsize` |
+
+`register_props("my_prop")` declares extras for a component of your own.
+
 **Geometry** — `Line(a, b)`, `Polyline(points)`, `Polygon(points)`,
 `Path("M0 0 L10 10 …")`, `Dot(center, r)`, `Marker(center, size, "diamond")`.
 `Line`/`Polyline`/`Polygon` accept **live anchors** as points, so they track
@@ -468,6 +539,11 @@ PNG/PDF need a converter: `pip install "figkit[export]"` (cairosvg), or
 `rsvg-convert` / `resvg` / `inkscape` / headless chromium on `PATH`.
 PNG and PDF outline text automatically, so they always match the SVG.
 
+On macOS, cairosvg often fails to import with `dlopen ... libcairo.2.dylib`
+even with Homebrew's cairo installed, because the loader does not look in
+`/opt/homebrew`. Either export `DYLD_FALLBACK_LIBRARY_PATH=$(brew --prefix
+cairo)/lib` or use `rsvg-convert` instead. SVG export needs nothing.
+
 Install: `pip install figkit` · `figkit[latex]` (math) · `figkit[export]`
 (PNG/PDF) · `figkit[all]`.
 
@@ -544,6 +620,24 @@ fig.audit(min_contrast=4.5)                     # WCAG AA for body text
     SVG and HTML but not in a cairosvg-rendered PNG/PDF; figkit warns when
     that happens. Use `rsvg-convert`/`resvg`/chromium, or skip shadows for
     figures headed to PNG.
+13. **A misspelled property raises.** `Text("hi", sizee=8)` is an error, not a
+    silent default. `size` and `font_size` are the same thing, and match
+    `measure_text(..., size=)`.
+14. **`rotate=` turns the block about `(x, y)`,** so a rotated label lands in
+    the same place whatever its length. `rotate_about=` picks another pivot;
+    `el.rotate(deg)` after construction still turns about the centre.
+15. **A missing glyph warns.** If the font has no glyph for a character, it
+    renders as an empty box and its measured width is `.notdef`'s, so figkit
+    says so and names the codepoint. `register_font` makes text export as
+    outlines, which also removes the viewer's fallback chain — a character
+    the registered font lacks becomes a guaranteed empty box.
+16. **A tiny `Box` looks like a circle,** because the theme's `radius=6` is
+    clamped to half the shorter side. Pass `radius=0` for small swatches and
+    data cells.
+17. **Arrow heads shrink to fit short connectors.** Below roughly 15pt the
+    head would swallow the shaft, so figkit scales it down and warns when the
+    result is much smaller than you asked for. Give short links more room, or
+    set `head_size=`.
 
 ---
 

figkit-0.2.0/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+All notable changes to figkit are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and figkit uses
+[semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — 2026-08-24
+
+### Changed
+
+- **A style property figkit does not read now raises `UnknownProperty`**
+  instead of being stored and ignored. `Text("hi", sizee=8)` used to render at
+  the theme default with no complaint; it now fails with a suggestion. This is
+  a breaking change for code passing properties that never did anything.
+  Components with properties of their own declare them with
+  `register_props(...)`, and `PROPS` is the full list.
+- **`rotate=` on `Text` turns the block about `(x, y)`**, not about its own
+  centre. Pivoting on the centre displaced the text by half its own length, so
+  where a rotated label landed depended on how many characters it had — a
+  50pt label drifted 25pt. `rotate_about=` takes an explicit pivot, and
+  `el.rotate(deg)` after construction is unchanged.
+- Arrow heads shrink to fit connectors too short to hold them. A head larger
+  than the connector used to consume the whole shaft and overshoot its start,
+  drawing a stray triangle with no line.
+- String options such as connector routes, marker shapes, grid order/alignment,
+  vector orientation, frame scales/sides and image fit now reject invalid
+  values with a suggestion instead of silently choosing another rendering.
+- Raster export now rejects `.jpg`, `.jpeg` and `.webp`; these extensions were
+  accepted even though the bytes written were always PNG.
+
+### Added
+
+- `size=` is an alias for `font_size=`, matching `measure_text(..., size=)`.
+  Measuring at one size and rendering at another was silent before.
+- `fill=` set directly on a `Text` means its colour. Text has no fill of its
+  own, so the property was being dropped.
+- A warning when the font has no glyph for a character: it renders as an empty
+  box and its measured width is `.notdef`'s, not the character's, so layout
+  computed from it is wrong. Names the codepoint, warns once per font and
+  character.
+- `Dot` accepts `Dot(x, y, r=...)` as well as `Dot(center, r)`, matching
+  `Circle` and every other element's `x, y` front door.
+- `word_spacing=` participates in both measurement and SVG/path rendering, and
+  `text_transform=` supports `none`, `uppercase`, `lowercase` and `capitalize`.
+  The advertised but unimplemented `font_variant` property is now rejected
+  instead of being accepted as a silent no-op.
+- `rotate=` and `rotate_about=` are common element constructor options, as the
+  manual already claimed, rather than Text-only constructor options. The
+  rotation is applied on first measurement rather than in `Element.__init__`,
+  because a subclass has not sized itself yet at that point: pivoting there
+  used the placeholder box, so a label-sized element landed somewhere that
+  depended on how long its text was.
+- `Figure.to_html(embed=False)` isolates the SVG in an image data URI;
+  `embed=True` keeps the SVG inline and styleable.
+
+### Documentation
+
+- The manual led with "nothing is auto-laid-out", which read as an instruction
+  to place everything by hand. It now points at `hstack`/`vstack`/`grid`/`fit`
+  and the existing `Matrix`, `Table`, `Brace` and `Legend` components first.
+- Every style property and its aliases are tabulated, so valid names no longer
+  have to be discovered by reading theme reprs.
+- Gotchas for the rotation pivot, missing glyphs, small-`Box` corner radius,
+  short-connector heads, and the macOS `DYLD_FALLBACK_LIBRARY_PATH` fix for
+  cairosvg.
+
+### Fixed
+
+- `figkit.__version__` reported `0.1.0` from the 0.1.1 release. The number
+  lived in both `pyproject.toml` and `figkit/__init__.py`, and a release only
+  bumped the first. `pyproject.toml` now reads the version from the package,
+  so there is one number to change and it cannot drift again.
+- macOS `.ttc`/`.otc` system fonts failed to load because the collection
+  loader received a TTFont-only argument. Collections now select the closest
+  family/weight/style face, restoring accurate metrics and text outlines.
+- `hstack(..., at=...)` and `vstack(..., at=...)` now place the north-west
+  corner of the completed result at `at`, including an optional panel.
+- `max_w=` now constrains and reflows a shape's label, including long tokens,
+  instead of shrinking only the container and leaving its text outside.
+- `self_loop()` keeps live anchors for its feet and apex, so it follows an
+  element after movement or resizing.
+- `Frame(clip_data=True)` clips only data marks; axes, ticks and titles remain
+  visible outside the plot area.
+- `Matrix.highlight()` keeps the highlighted cell's value label in front.
+- Contrast audit uses the same resolved text colour as rendering, including
+  `Text(fill=...)` and per-Span colours.
+- `ColorBar` segments stay within the declared strip bounds.
+- Dict-valued theme fills such as gradients are no longer mistaken for roles.
+- Math glyph left overhang is included in measurement and normalized in the
+  generated path.
+- Rich `Text` content has a safe repr, and outlined missing glyphs now draw the
+  `.notdef` box described by their warning instead of leaving a blank gap.
+
+## [0.1.1] — 2026-08-21
+
+### Connectors
+
+- `start_handle=` and `end_handle=` place either end's Bezier handle — the
+  "whisker" a vector editor lets you drag. The direction is the asymptote the
+  curve leaves along, the length is how long it clings to it, given as a
+  fraction of the endpoint separation so the shape survives the layout
+  moving. Takes a bare fraction, a tuple, or a `Handle` (which also offers
+  `px=` for an absolute reach). An end given a handle ignores `bend`/`bow`.
+- Handles also give curves between bare points a direction to leave in, which
+  previously only anchors could supply.
+- `tension=` (default 0.5) loosens the spline threaded through `waypoints=`.
+
+### Fixed
+
+- A curve with waypoints threw its endpoint normals away, so `curve(a.e, b.w,
+  waypoints=[p])` left the box diagonally instead of along the face it was
+  attached to. The outer tangents are now pinned to the attachment normals.
+
+## [0.1.0] — 2026-08-21
+
+First public release.
+
+### Layout and geometry
+
+- Elements with live anchors (`box.e` re-resolves on read, so arrows follow
+  the things they connect), exact bounding boxes, and chainable relative
+  placement: `at`, `right_of`, `left_of`, `above_of`, `below_of`, `inside`,
+  `align_to`, `span_x`, `resize`, `rotate`, `scale_by`.
+- Batch arrangement: `align`, `distribute_h/v`, `spread_h/v`, `hstack`,
+  `vstack`, `grid`, `fit`, `circular`, `same_size`, `brace_around`.
+- `hstack(align="baseline")` sets mixed text and matrices like an equation.
+- Groups that own their children and report live bounds, with `z`-ordering.
+
+### Text
+
+- Text measured from real glyph advances via fontTools, with font resolution
+  through registered fonts, the usual system directories and `fc-match`, and a
+  fallback to the PostScript core-font metrics.
+- Multi-line text, word wrapping, optical (cap-height) centring inside shapes.
+- Inline `$math$` anywhere, typeset to vector outlines through matplotlib's
+  mathtext, or a real `latex` + `dvisvgm` toolchain when one is installed.
+- `Span` for per-word colour, weight, style, size, family, strike-through and
+  underline. Decorations are drawn as geometry, so they survive rasterising
+  and outlining.
+
+### Drawing
+
+- Shapes: `Box`, `Pill`, `Ellipse`, `Circle`, `Diamond`, `Triangle`,
+  `Hexagon`, `Parallelogram`, `Chevron`, `Star`, `Cylinder`, `Note`,
+  `Callout`; geometry primitives `Line`, `Polyline`, `Polygon`, `Path`,
+  `Dot`, `Marker`.
+- Connectors: straight, orthogonal (`elbow`), curved, arcs, explicit
+  waypoints, nine arrow-head shapes, path labels, and `self_loop`.
+- Composites: `Matrix`, `LabelledMatrix`, `Vector`, `ColorBar`, `Table`,
+  `Legend`, `Brace`, `Bracket`, `Panel`.
+- `Component` for reusable units that publish named anchors.
+- `Image` embeds rasters as data URIs and inlines SVGs as vectors, rewriting
+  internal ids so repeated copies never collide.
+
+### Style
+
+- A cascading theme: base tokens, per-role overrides, CSS-style classes and a
+  colour palette, resolved kwargs → style → classes → inherited → theme →
+  default.
+- Seven built-in themes: default, `PAPER`, `SLIDE`, `DARK`, `BLUEPRINT`,
+  `MINIMAL`, `SOFT`.
+- Colour helpers: `mix`, `lighten`, `darken`, `alpha`, `saturate`,
+  `contrast_color`, `colormap`, `palette`.
+
+### Data
+
+- `Frame` maps a data domain onto figure coordinates; `line`, `scatter`,
+  `bars`, `area_fill`, `region`, `axes`, `gridlines`, log scales and
+  `nice_ticks`. Every mark is an ordinary element you can anchor to.
+
+### Checking and output
+
+- `fig.audit()` reports overlapping elements, labels escaping their shapes,
+  unreadable colour combinations, connectors crossing unrelated elements,
+  degenerate geometry and content outside a pinned canvas — and is built to
+  stay quiet about deliberate overlap, so a clean report means something.
+- Export to SVG and HTML with no dependencies; PNG and PDF through cairosvg,
+  `rsvg-convert`, `resvg`, `inkscape` or headless Chromium. Raster and PDF
+  output outlines text so it cannot depend on the renderer's fonts.
+- `AI_MANUAL.md`, a system-prompt-sized guide for driving figkit from an
+  agent.

{figkit-0.1.1 → figkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: figkit
-Version: 0.1.1
+Version: 0.2.0
 Summary: Design figures with Python code — boxes, arrows, LaTeX and data, exported to SVG/PNG/PDF/HTML
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/philippspohn/figkit
@@ -263,7 +263,7 @@ Anchors on every element: `n s e w ne nw se sw center`, plus `at_angle(deg)`,
 
 ```bash
 pip install -e ".[dev]"
-pytest                       # 277 tests; every example must audit clean
+pytest                       # full suite; every example must audit clean
 python -m pyflakes figkit
 python examples/01_pipeline.py
 ```

{figkit-0.1.1 → figkit-0.2.0}/README.md

@@ -218,7 +218,7 @@ Anchors on every element: `n s e w ne nw se sw center`, plus `at_angle(deg)`,
 
 ```bash
 pip install -e ".[dev]"
-pytest                       # 277 tests; every example must audit clean
+pytest                       # full suite; every example must audit clean
 python -m pyflakes figkit
 python examples/01_pipeline.py
 ```

{figkit-0.1.1 → figkit-0.2.0}/examples/05_rich_text_and_components.py

@@ -42,13 +42,13 @@ with Figure(pad=26, background="#ffffff") as fig:
     Text([Span("Rich text", bold=True), " — one line, several styles"],
          font_size=16, align="left").at(0, 0)
     Text(["accuracy ", Span("76.1", strike=True, color="@muted"), " → ",
-          Span("94.6", color="@good", bold=True), " after ",
+          Span("94.6", color="#4b965c", bold=True), " after ",
           Span("pretraining", italic=True), ", measured on ",
           Span("held-out data", underline=True)],
          font_size=14, align="left").at(0, 30)
 
     # ---- 2. a matrix expression, set like an equation -------------------
-    lhs = Text("$\\Pi_{\\mathcal{NM}} \;=\;$", font_size=19)
+    lhs = Text(r"$\Pi_{\mathcal{NM}} \;=\;$", font_size=19)
     left = LabelledMatrix([[rng.random() for _ in range(4)] for _ in range(5)],
                           cell=17, cmap="grays", stroke="#ffffff",
                           row_label="seq len", col_label="$d$",

{figkit-0.1.1 → figkit-0.2.0}/figkit/__init__.py

@@ -16,7 +16,7 @@ Everything is explicit: you place things, figkit measures them accurately
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 # -- geometry ---------------------------------------------------------------
 from .geom import Affine, BBox, Point, to_point

{figkit-0.1.1 → figkit-0.2.0}/figkit/audit.py

@@ -531,8 +531,19 @@ def _check_contrast(figure, min_contrast: float) -> list:
             continue
         if not getattr(el, "audit_enabled", True):
             continue
-        colour = label.prop("color")
-        if colour is None:
+        colours = [label.text_color()]
+        try:
+            colours.extend(label._resolve_value(run.color)
+                           for line in label.layout.lines for run in line.runs
+                           if run.color is not None)
+        except Exception:
+            pass
+        unique = []
+        for candidate in colours:
+            if candidate is not None and candidate not in unique:
+                unique.append(candidate)
+        colours = unique
+        if not colours:
             continue
         lb = label.bbox
         pos = index.get(id(el), 0)
@@ -544,18 +555,20 @@ def _check_contrast(figure, min_contrast: float) -> list:
             # box's own fill, which is the commonest backdrop of all.
             if _contains(other.bbox, lb, tol=-0.5):
                 backdrop = _solid_fill(other)
-        try:
-            ratio = _contrast_ratio(colour, backdrop)
-        except ValueError:
-            continue
-        if ratio < min_contrast - 1e-9:
-            out.append(Finding(
-                "contrast",
-                f"{describe(el)}: text {colour} on {backdrop} has contrast "
-                f"{_floor2(ratio)}:1 (want {min_contrast:.2f}:1)",
-                severity="error" if ratio < 1.6 else "warning",
-                where=lb.center, elements=(el,),
-                detail={"ratio": ratio, "color": colour, "background": backdrop}))
+        for colour in colours:
+            try:
+                ratio = _contrast_ratio(colour, backdrop)
+            except (TypeError, ValueError):
+                continue
+            if ratio < min_contrast - 1e-9:
+                out.append(Finding(
+                    "contrast",
+                    f"{describe(el)}: text {colour} on {backdrop} has contrast "
+                    f"{_floor2(ratio)}:1 (want {min_contrast:.2f}:1)",
+                    severity="error" if ratio < 1.6 else "warning",
+                    where=lb.center, elements=(el,),
+                    detail={"ratio": ratio, "color": colour,
+                            "background": backdrop}))
     return out
 
 

{figkit-0.1.1 → figkit-0.2.0}/figkit/components.py

@@ -7,7 +7,7 @@ import math
 from .colors import colormap, contrast_color, to_hex
 from .component import Component
 from .core import Element, Group
-from .style import Style
+from .style import Style, enum_value
 from .geom import BBox, Point, _expand_spec, to_point
 from .paint import paint_attrs
 from .shapes import Box, Marker
@@ -171,6 +171,7 @@ class Matrix(Group):
         self.cmap = cmap
         self._cells: list = []
         self._value_labels: list = []
+        self._value_label_map: dict = {}
         # Paint properties passed to Matrix(...) style the *cells*, which is
         # what people mean by `Matrix(vals, stroke="#333")`.
         group_kw = {k: v for k, v in kw.items() if k in _GROUP_KEYS}
@@ -211,6 +212,7 @@ class Matrix(Group):
                     self.add(lbl)
                     lbl.center_at(cell_el.bbox.cx, cell_el.bbox.cy)
                     self._value_labels.append(lbl)
+                    self._value_label_map[(i, j)] = lbl
             self._cells.append(row_cells)
 
         if border:
@@ -263,6 +265,9 @@ class Matrix(Group):
         c = self.cell(i, j)
         c.restyle(**style)
         c.to_front()
+        label = self._value_label_map.get((i % self.n_rows, j % self.n_cols))
+        if label is not None:
+            label.to_front()
         return c
 
 
@@ -271,13 +276,16 @@ def Vector(values=None, *, orient: str = "v", **kw) -> Matrix:
     if values is None:
         values = []
     flat = list(values)
-    if str(orient).lower().startswith("v"):
+    orient = enum_value(orient, "orient", {
+        "v": "v", "vertical": "v", "h": "h", "horizontal": "h",
+    })
+    if orient == "v":
         grid = [[v] for v in flat]
     else:
         grid = [flat]
     colors = kw.pop("colors", None)
     if colors is not None:
-        colors = [[c] for c in colors] if str(orient).lower().startswith("v") \
+        colors = [[c] for c in colors] if orient == "v" \
             else [list(colors)]
         return Matrix(None, colors=colors, **kw)
     return Matrix(grid, **kw)
@@ -296,16 +304,21 @@ class ColorBar(Group):
                  labels=True, label_fmt="{:.2g}", x: float = 0.0,
                  y: float = 0.0, **kw):
         super().__init__(**kw)
-        vertical = str(orient).lower().startswith("v")
+        orient = enum_value(orient, "orient", {
+            "v": "v", "vertical": "v", "h": "h", "horizontal": "h",
+        })
+        vertical = orient == "v"
         n = max(2, int(steps))
         for i in range(n):
             t = i / (n - 1)
+            pos = i / n
+            span = (1.0 - pos) if i == n - 1 else (1.0 / n + 0.001)
             col = colormap(cmap, 1.0 - t if vertical else t)
             if vertical:
-                seg = Box(None, x, y + t * h, w, h / n + 0.6, fill=col,
+                seg = Box(None, x, y + pos * h, w, span * h, fill=col,
                           stroke="none", padding=0, radius=0, add=False)
             else:
-                seg = Box(None, x + t * w, y, w / n + 0.6, h, fill=col,
+                seg = Box(None, x + pos * w, y, span * w, h, fill=col,
                           stroke="none", padding=0, radius=0, add=False)
             self.add(seg)
         frame = Box(None, x, y, w, h, fill="none", stroke="#6b7280",

{figkit-0.1.1 → figkit-0.2.0}/figkit/connectors.py

@@ -12,9 +12,10 @@ from dataclasses import dataclass
 from .core import Anchor, Element
 from .geom import BBox, Point, polyline_length, to_point
 from .paint import paint_attrs
+from .style import enum_value
 from .svgdoc import Node, RenderContext
 from .svgpath import (fmt, flatten_path, path_bbox, path_from_points,
-                      point_at, rounded_polyline)
+                      path_length, point_at, rounded_polyline)
 from .text import Text
 
 __all__ = [
@@ -25,6 +26,13 @@ __all__ = [
 HEADS = ("triangle", "stealth", "open", "vee", "circle", "dot", "diamond",
          "square", "bar", "tee", "cross", "none")
 
+_ROUTES = {
+    "straight": "straight", "line": "straight",
+    "elbow": "elbow", "orth": "orth", "orthogonal": "orthogonal",
+    "hv": "hv", "vh": "vh", "manhattan": "manhattan",
+    "curve": "curve", "bezier": "bezier", "spline": "spline", "arc": "arc",
+}
+
 _SIDE_NORMAL = {"n": Point(0, -1), "s": Point(0, 1),
                 "e": Point(1, 0), "w": Point(-1, 0)}
 
@@ -202,7 +210,7 @@ class Connector(Element):
                  label_rotate: bool = False, **kw):
         self.start_ref = start
         self.end_ref = end
-        self.route = str(route).lower()
+        self.route = enum_value(route, "route", _ROUTES)
         self.waypoints = list(waypoints or [])
         self.stub = float(stub)
         self.bend = float(bend)
@@ -416,6 +424,19 @@ class Connector(Element):
         # How far back the stroke has to stop for each head to cover its end.
         trim_end = _head_inset(head_kind, head_size) if has_head else 0.0
         trim_start = _head_inset(tail_kind, tail_size) if has_tail else 0.0
+        shrink = _head_budget(trim_start + trim_end, path_length(d))
+        if shrink < 1.0:
+            # The heads wanted more room than the connector has. Left alone
+            # they eat the whole shaft and overshoot its ends, which reads as
+            # a stray triangle rather than an arrow.
+            if shrink < 0.5:
+                ctx.warn(f"connector is {path_length(d):.0f}pt long but its "
+                         f"heads need {trim_start + trim_end:.0f}pt; shrinking "
+                         f"them to fit (set head_size= to choose)")
+            head_size *= shrink
+            tail_size *= shrink
+            trim_end = _head_inset(head_kind, head_size) if has_head else 0.0
+            trim_start = _head_inset(tail_kind, tail_size) if has_tail else 0.0
         if trim_start or trim_end:
             d = _trim_path(d, trim_start, trim_end)
 
@@ -449,6 +470,17 @@ class Connector(Element):
         return nodes
 
 
+#: Most of a short connector should still be line rather than arrow head.
+_MAX_HEAD_SHARE = 0.6
+
+
+def _head_budget(inset: float, length: float) -> float:
+    """How much the heads must shrink by to leave a visible shaft."""
+    if inset <= 0 or length <= 0:
+        return 1.0
+    return min(1.0, _MAX_HEAD_SHARE * length / inset)
+
+
 def _head_inset(kind: str, size: float) -> float:
     """How far short of the tip the stroke must stop for this head shape."""
     _d, _meta, inset = _head_geometry(kind, Point(0, 0), Point(1, 0), size)
@@ -774,21 +806,20 @@ def self_loop(element, side: str = "top", size: float = 36.0,
 
     >>> self_loop(state, side="top", label="retry")
     """
-    box = element.bbox
     half = max(0.02, min(0.9, float(spread))) / 2.0
     s = str(side).lower()
     if s in ("top", "n", "up"):
-        start, end = box.uv(0.5 - half, 0.0), box.uv(0.5 + half, 0.0)
-        apex = Point(box.cx, box.y0 - size)
+        start, end = element.uv(0.5 - half, 0.0), element.uv(0.5 + half, 0.0)
+        apex = element.n + (0, -size)
     elif s in ("bottom", "s", "down"):
-        start, end = box.uv(0.5 + half, 1.0), box.uv(0.5 - half, 1.0)
-        apex = Point(box.cx, box.y1 + size)
+        start, end = element.uv(0.5 + half, 1.0), element.uv(0.5 - half, 1.0)
+        apex = element.s + (0, size)
     elif s in ("left", "w"):
-        start, end = box.uv(0.0, 0.5 + half), box.uv(0.0, 0.5 - half)
-        apex = Point(box.x0 - size, box.cy)
+        start, end = element.uv(0.0, 0.5 + half), element.uv(0.0, 0.5 - half)
+        apex = element.w + (-size, 0)
     elif s in ("right", "e"):
-        start, end = box.uv(1.0, 0.5 - half), box.uv(1.0, 0.5 + half)
-        apex = Point(box.x1 + size, box.cy)
+        start, end = element.uv(1.0, 0.5 - half), element.uv(1.0, 0.5 + half)
+        apex = element.e + (size, 0)
     else:
         raise ValueError(f"side={side!r}; use top/bottom/left/right")
     kw.setdefault("route", "curve")