@liggi/figkit 0.4.0 → 0.6.0

package/examples/charts/bars-ref.json

@@ -0,0 +1,6 @@
+{ "type": "bars", "title": "Two of the four new layouts beat the current page",
+  "note": "Share of visitors who finished checkout", "unit": "%",
+  "ref": { "label": "Current page", "value": 61 },
+  "bars": [ { "label": "One-page form", "value": 68 }, { "label": "Saved cards first", "value": 64 },
+            { "label": "Address lookup", "value": 60 }, { "label": "Guest by default", "value": 57 } ],
+  "source": "Invented data, for illustration." }

package/examples/charts/estimates.json

@@ -0,0 +1,7 @@
+{ "type": "estimates", "title": "Free delivery lifts orders in two regions; the north's range includes zero",
+  "note": "Change in orders per 100 visitors, free delivery minus paid", "range": "95% interval",
+  "sides": { "below": "Paid better", "above": "Free better" },
+  "rows": [ { "label": "South", "value": 2.4, "low": 1.1, "high": 3.7 },
+            { "label": "Midlands", "value": 1.8, "low": 0.6, "high": 3.0 },
+            { "label": "North", "value": 0.7, "low": -0.9, "high": 2.3 } ],
+  "source": "Invented data, for illustration." }

package/examples/charts/heatmap-signed.json

@@ -0,0 +1,5 @@
+{ "type": "heatmap", "title": "The new menu helped every region except the north",
+  "note": "Change in weekly orders per store after the new menu", "unit": "%",
+  "rows": ["South", "Midlands", "North"], "columns": ["Wk 1", "Wk 2", "Wk 3", "Wk 4"],
+  "values": [ [3.1, 4.4, 5.0, 4.8], [1.2, 2.6, 3.3, 3.9], [-2.4, -3.8, -1.9, -2.7] ],
+  "source": "Invented data, for illustration." }

package/examples/charts/map.json

@@ -0,0 +1,269 @@
+{
+  "type": "map",
+  "title": "Every grocery order passes through the order service before stores pick or vans deliver",
+  "subsystems": [
+    {
+      "id": "shop",
+      "name": "Storefront",
+      "kind": "web and mobile"
+    },
+    {
+      "id": "orders",
+      "name": "Orders",
+      "kind": "orders team"
+    },
+    {
+      "id": "stores",
+      "name": "Store fulfilment",
+      "kind": "stores team"
+    },
+    {
+      "id": "delivery",
+      "name": "Delivery",
+      "kind": "logistics team"
+    },
+    {
+      "id": "outside",
+      "name": "Outside services"
+    }
+  ],
+  "parts": [
+    {
+      "id": "web",
+      "name": "Shop website",
+      "kind": "Next.js app",
+      "in": "shop"
+    },
+    {
+      "id": "mobile",
+      "name": "Shop app",
+      "kind": "iOS and Android",
+      "in": "shop"
+    },
+    {
+      "id": "gateway",
+      "name": "API gateway",
+      "kind": "Envoy",
+      "in": "shop"
+    },
+    {
+      "id": "search",
+      "name": "Product search",
+      "kind": "OpenSearch",
+      "in": "shop"
+    },
+    {
+      "id": "basket",
+      "name": "Basket service",
+      "kind": "Go service",
+      "in": "shop"
+    },
+    {
+      "id": "order",
+      "name": "Order service",
+      "kind": "Go service",
+      "in": "orders",
+      "tone": "accent"
+    },
+    {
+      "id": "orderdb",
+      "name": "Orders database",
+      "kind": "Postgres",
+      "in": "orders"
+    },
+    {
+      "id": "payment",
+      "name": "Payment service",
+      "kind": "Go service",
+      "in": "orders"
+    },
+    {
+      "id": "fraud",
+      "name": "Fraud check",
+      "kind": "rules engine",
+      "in": "orders"
+    },
+    {
+      "id": "events",
+      "name": "Order events",
+      "kind": "Kafka topic",
+      "in": "orders"
+    },
+    {
+      "id": "planner",
+      "name": "Picking planner",
+      "kind": "nightly batch",
+      "in": "stores"
+    },
+    {
+      "id": "stock",
+      "name": "Store stock",
+      "kind": "per-store counts",
+      "in": "stores"
+    },
+    {
+      "id": "picker",
+      "name": "Picker app",
+      "kind": "handheld scanner",
+      "in": "stores"
+    },
+    {
+      "id": "subs",
+      "name": "Substitution rules",
+      "kind": "YAML in repo",
+      "in": "stores"
+    },
+    {
+      "id": "slots",
+      "name": "Van slots",
+      "kind": "1-hour windows",
+      "in": "delivery"
+    },
+    {
+      "id": "routes",
+      "name": "Route planner",
+      "kind": "OR-Tools job",
+      "in": "delivery"
+    },
+    {
+      "id": "driver",
+      "name": "Driver app",
+      "kind": "Android",
+      "in": "delivery"
+    },
+    {
+      "id": "tracking",
+      "name": "Live tracking",
+      "kind": "WebSocket service",
+      "in": "delivery"
+    },
+    {
+      "id": "cards",
+      "name": "Card processor",
+      "kind": "Stripe",
+      "in": "outside"
+    },
+    {
+      "id": "sms",
+      "name": "Text messages",
+      "kind": "Twilio",
+      "in": "outside"
+    },
+    {
+      "id": "maps",
+      "name": "Road map data",
+      "kind": "Mapbox",
+      "in": "outside"
+    }
+  ],
+  "links": [
+    {
+      "from": "web",
+      "to": "gateway",
+      "tone": "accent"
+    },
+    {
+      "from": "mobile",
+      "to": "gateway",
+      "tone": "accent"
+    },
+    {
+      "from": "gateway",
+      "to": "search",
+      "label": "queries"
+    },
+    {
+      "from": "gateway",
+      "to": "basket",
+      "tone": "accent"
+    },
+    {
+      "from": "search",
+      "to": "stock"
+    },
+    {
+      "from": "basket",
+      "to": "slots",
+      "label": "books a slot"
+    },
+    {
+      "from": "basket",
+      "to": "order",
+      "label": "checkout",
+      "tone": "accent"
+    },
+    {
+      "from": "order",
+      "to": "payment",
+      "label": "charge"
+    },
+    {
+      "from": "payment",
+      "to": "fraud"
+    },
+    {
+      "from": "payment",
+      "to": "cards"
+    },
+    {
+      "from": "order",
+      "to": "orderdb",
+      "label": "writes"
+    },
+    {
+      "from": "order",
+      "to": "events",
+      "label": "publishes",
+      "tone": "accent"
+    },
+    {
+      "from": "events",
+      "to": "planner",
+      "tone": "accent",
+      "label": "new order"
+    },
+    {
+      "from": "events",
+      "to": "routes",
+      "tone": "accent",
+      "label": "new order"
+    },
+    {
+      "from": "planner",
+      "to": "picker",
+      "label": "pick lists"
+    },
+    {
+      "from": "picker",
+      "to": "stock",
+      "label": "takes off stock"
+    },
+    {
+      "from": "picker",
+      "to": "subs"
+    },
+    {
+      "from": "routes",
+      "to": "maps"
+    },
+    {
+      "from": "routes",
+      "to": "driver",
+      "label": "route stops"
+    },
+    {
+      "from": "driver",
+      "to": "tracking",
+      "label": "location"
+    },
+    {
+      "from": "tracking",
+      "to": "sms",
+      "label": "ETA texts"
+    },
+    {
+      "from": "slots",
+      "to": "routes"
+    }
+  ]
+}

package/examples/charts/states.json

@@ -0,0 +1,71 @@
+{
+  "type": "states",
+  "title": "An order waits after a declined card until a new card is added",
+  "entry": "Shopper checks out",
+  "states": [
+    {
+      "id": "waiting",
+      "name": "Awaiting payment",
+      "start": true
+    },
+    {
+      "id": "declined",
+      "name": "Card declined",
+      "note": "Shopper emailed",
+      "tone": "accent"
+    },
+    {
+      "id": "paid",
+      "name": "Paid"
+    },
+    {
+      "id": "packed",
+      "name": "Packed"
+    },
+    {
+      "id": "shipped",
+      "name": "Shipped",
+      "end": true
+    },
+    {
+      "id": "cancelled",
+      "name": "Cancelled",
+      "end": true
+    }
+  ],
+  "moves": [
+    {
+      "from": "waiting",
+      "to": "paid",
+      "label": "Charge succeeds"
+    },
+    {
+      "from": "waiting",
+      "to": "declined",
+      "label": "Charge fails"
+    },
+    {
+      "from": "declined",
+      "to": "waiting",
+      "label": "New card added"
+    },
+    {
+      "from": "paid",
+      "to": "packed",
+      "label": "Warehouse picks"
+    },
+    {
+      "from": "packed",
+      "to": "shipped",
+      "label": "Carrier collects"
+    },
+    {
+      "from": [
+        "paid",
+        "packed"
+      ],
+      "to": "cancelled",
+      "label": "Shopper cancels"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liggi/figkit",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Explanatory figures for agents and people: write a little HTML or a chart spec, get a laid-out PNG and a list of what is wrong with it.",
   "license": "MIT",
   "type": "module",
@@ -34,6 +34,7 @@
     "agents"
   ],
   "dependencies": {
+    "@dagrejs/dagre": "^3.1.3",
     "@fontsource/geist-mono": "^5.3.0",
     "@fontsource/geist-sans": "^5.3.0",
     "@fontsource/newsreader": "^5.3.0",

package/runtime/fig.css

@@ -274,3 +274,59 @@ fig-bars .fb-label .fb-n { display: block; font-size: var(--small); color: var(-
 .fig.phone fig-bars { grid-template-columns: minmax(0, 1fr); row-gap: 4px; }
 .fig.phone fig-bars .fb-label { margin-top: 10px; }
 .fig.phone fig-bars .fb-label .fb-n { display: inline; margin-left: 8px; }
+
+/* estimates: signed values with ranges around a zero line; what each side of zero means under the axis */
+.fig .estimates { position: relative; }
+
+.fig .range-key i.est-dot { width: 14px; height: 14px; border-radius: 50%; border: 2.5px solid; box-sizing: border-box; }
+.fig .est-sides { position: relative; height: calc(var(--small) * 1.4); margin-top: -6px; font-size: var(--small); color: var(--muted); }
+.fig .est-sides span { position: absolute; top: 0; white-space: nowrap; }
+
+/* bars with a reference: its own first row in the second colour, and a dashed line from its end through the rest */
+fig-bars.has-ref { position: relative; }
+fig-bars .fb-label.ref { color: var(--second); }
+fig-bars .fb-refline { position: absolute; width: 0; border-left: 2px dashed var(--second); pointer-events: none; }
+.fig .range-key i.swatch { width: 18px; height: 14px; border-radius: 2px; background: var(--accent); }
+fig-bars.has-ref .fb-label.ref + .fb-track .fb-bar { opacity: .55; }
+/* on a phone the names sit above the bars, so the reference line stops at each name rather than crossing it */
+.fig.phone fig-bars.has-ref .fb-label { position: relative; z-index: 1; justify-self: start; background: var(--paper); padding-right: 8px; }
+.fig .hm-key i.hm-signed { position: relative; margin-bottom: calc(var(--small) * 1.3); }
+.fig .hm-key i.hm-signed b { font-style: normal; position: absolute; top: 100%; transform: translateX(-50%); font-weight: 400; color: var(--muted); padding-top: 2px; line-height: 1; }
+.fig .hm-key i.hm-signed b::before { content: ''; position: absolute; left: 50%; top: -14px; height: 14px; border-left: 2px solid var(--paper); }
+fig-bars.has-ref .fb-val:not(.lead) { color: var(--muted); }
+/* Against a reference, a bar that clears it is solid accent (a faded orange reads as brown on dark); its range is drawn in ink on top. */
+fig-bars.has-ref .fb-bar.dim.accent { opacity: 1; }
+fig-bars.has-ref .fb-range.accent { --tone: var(--ink); }
+
+/* ---------- states: what one thing moves through (a spec of type "states") ---------- */
+.fig .states { display: grid; column-gap: 120px; row-gap: 76px; align-items: stretch; justify-content: start; }
+.fig.phone .states { column-gap: 64px; row-gap: 68px; }
+.fig.phone .state { padding: 12px 10px; }
+.fig.phone .state > h3 { font-size: var(--body); }
+.fig .state { text-align: center; align-items: center; justify-content: center; justify-self: stretch; }
+.fig .state > p { margin-top: 4px; }
+.fig .state > .st-stayed { color: var(--ink); }
+.fig .node.bare.st-dot { width: 22px; height: 22px; padding: 0; border-radius: 50%; background: var(--line); justify-self: center; align-self: center; }
+.fig .fig-wire-label .fig-wire-sub { display: block; font-weight: 400; font-variant-numeric: tabular-nums; }
+.fig .st-key { font-size: var(--small); }
+.fig .state.mid { align-self: center; }
+/* the bracket beside the states that share one move, which leads to it with one arrow */
+.fig .node.bare.st-bracket { justify-self: end; width: 14px; margin-right: -30px; padding: 0; border: 1.5px solid var(--line); border-left: 0; border-radius: 0 4px 4px 0; background: none; }
+.fig.phone .node.bare.st-bracket { margin-right: -24px; width: 10px; }
+
+/* ---------- map: a whole system, parts in subsystem regions (a spec of type "map"), laid out by dagre and packed by figkit ---------- */
+.fig .map { position: relative; }
+.fig .map > .map-part, .fig .map-region > .map-part { position: absolute; max-width: 260px; min-width: 120px; padding: 10px 14px; gap: 2px; }
+.fig .map-part > h3 { font-size: var(--body); line-height: 1.2; }
+.fig .map-part > p { font-size: var(--small); white-space: nowrap; }
+.fig .map-region { position: absolute; display: block; padding: 0; border: 0; border-radius: 14px; background: color-mix(in srgb, var(--ink) 4%, var(--paper)); box-shadow: inset 0 0 0 1px var(--hair); }
+.fig .map-region > .mp-head { position: absolute; top: 14px; left: 20px; display: flex; flex-direction: column; gap: 2px; white-space: nowrap; }
+.fig .map-region > .mp-head > h2 { font-family: var(--serif); font-size: calc(var(--h) * 1.35); font-weight: 400; line-height: 1.1; color: var(--ink); }
+.fig .map > svg.map-wires { position: absolute; inset: 0; pointer-events: none; overflow: visible; }
+.fig .map .map-label { padding: 0 4px; line-height: 1.25; }
+.fig .map-overview > .map-sub { max-width: 230px; min-width: 150px; }
+.fig .map-sub > ul { list-style: none; margin: 6px 0 0; padding: 0; display: flex; flex-direction: column; gap: 1px; }
+.fig .map-sub > ul li { font-size: var(--small); color: var(--muted); }
+.fig .map-sub > .mp-count { color: var(--soft); }
+/* A map's link label outlined, so a line visibly runs into it rather than stopping short of a floating word. */
+.fig:has(.map) .fig-wire-label { box-shadow: inset 0 0 0 1px var(--hair); }