@fusion.dev/helix-graph 0.185.0 → 0.186.0

package/README.md

@@ -1,7 +1,8 @@
 # @fusion.dev/helix-graph
 
 Connects the Helix `Graph` frame to whatever draws the graph: Sigma.js, cosmos.gl,
-three.js, or a driver of your own, colored from your tokens.
+three.js, an isometric diagram in SVG, or a driver of your own, colored from
+your tokens.
 
 ```sh
 bun add @fusion.dev/helix @fusion.dev/helix-graph sigma graphology graphology-layout-forceatlas2
@@ -332,24 +333,76 @@ connectGraph(frame, threeDriver(box), {
   with every fold the field's cells are too coarse to hold.
 - **Without a stencil, a layout runs in three dimensions** with d3-force-3d.
 - **Dragging turns the graph, and the wheel and a pinch bring it nearer.** It
-  turns slowly by itself while nobody is handling it, and never for a reader
-  who asks for less motion.
+  turns slowly by itself for its first five seconds, stops for good the moment
+  the reader handles it, and never turns for a reader who asks for less
+  motion. Motion that starts by itself and runs longer than five seconds needs
+  a pause control, and this one ends first.
 - **The far side recedes.** Through a graph, its far notes are a little
   quieter than its near ones.
-- **Edges are smooth at any density.** The drawing has half as many pixels again as the screen, at least two for each of the page's, and links are lines of a set width with smooth edges, where WebGL draws its own a device pixel wide.
+- **Edges are smooth at any density.** On a screen worked with a mouse, the drawing has half as many pixels again as the screen, at least two for each of the page's. On a touch screen it has the screen's own, at most two, so a phone draws less than half the pixels it did. Links are lines of a set width with smooth edges, where WebGL draws its own a device pixel wide.
 - **Each group is named over its near side**, and a group's name moves a line
   where it would cover another's.
 - **It draws only while something moves**: the reader's hands, the turning, a
-  layout, or a glide. It draws nothing while its box is out of view.
+  layout, or a glide. At rest it asks the browser for no frames at all, and it
+  draws nothing while its box is out of view.
+- **Every graph on a page shares six WebGL contexts.** A browser holds only
+  about sixteen and drops the oldest past that. Past six, a graph far off
+  screen gives its context back, the one away longest first, and takes it
+  again within half a screen of coming into view. A graph whose context the
+  browser restores is drawn again at once.
 
 | `threeDriver` option | Default | What else it takes |
 |---|---|---|
-| `autoRotate` | `true` | `false` leaves the graph still until the reader turns it |
-| `density` | screen × 1.5, 2 to 3 | How many pixels the drawing has for each of the page's; fewer is faster on a slow GPU |
+| `autoRotate` | `true` | `false` leaves the graph still until the reader turns it. It turns for five seconds at most |
+| `density` | screen × 1.5, 2 to 3; on a touch screen, the screen's own, at most 2 | How many pixels the drawing has for each of the page's; fewer is faster on a slow GPU |
 | `shape` | `circle` | `square` or `diamond`, for every note that does not say; a `ring` is drawn as a circle |
 | `groupLabels` | `true` | `false` leaves each group unnamed |
 | `layoutLimit` | `10000` | The longest a layout runs, in milliseconds |
 
+## An isometric diagram
+
+**`isometricDriver(box)` draws the graph as an isometric diagram in SVG**, for
+architecture and flow diagrams. It needs no renderer:
+
+```js
+import { isometricDriver } from '@fusion.dev/helix-graph/isometric'
+
+connectGraph(frame, isometricDriver(frame.querySelector('div')))
+```
+
+- Each note is a solid standing on a cell of the floor at its `x` and `y`. A
+  diagram that gives no note a place is laid out in columns along its links,
+  and a note added without one goes to the nearest free cell beside the notes
+  it links to.
+- A note's `shape` picks its solid: `square` a block, `circle` or `ring` a
+  cylinder, and `diamond` a pyramid. Its size sets its height.
+- Each face is shaded from the note's color, and each edge is drawn in an ink
+  that contrasts with its face, so the darkest note still reads as a solid.
+- Each group stands on a plate in its color, with its name written along the
+  floor. Links run along the floor with an arrow halfway.
+- The view frames the whole diagram, and frames it again when the box changes
+  size until the reader pans or zooms. Drag to pan and use the wheel to zoom,
+  as the frame's `gestures` allows.
+
+- `turn` and `tilt` set where the diagram is seen from. `driver.turnBy(90)`
+  brings the next corner round, `driver.turnTo({ tilt: 90 })` looks from
+  straight above, and Shift with a drag turns and tilts it. The faces each
+  solid shows, and their shading, follow the camera.
+
+| `isometricDriver` option | Default | What else it takes |
+|---|---|---|
+| `flat` | `false` | `true` draws every note at no height |
+| `groupLabels` | `true` | `false` leaves each group's plate unnamed |
+| `shape` | `square` | `circle`, `ring` or `diamond`, for every note that does not say |
+| `tilt` | `35.26` | The camera's height above the floor in degrees, from `15` to `90`, a plan from straight above |
+| `turn` | `45` | The compass bearing the diagram is seen from, in degrees |
+
+| `isometricDriver` method | What it does |
+|---|---|
+| `camera()` | Where the diagram is seen from now: `{ turn, tilt }` |
+| `turnBy(degrees, animate)` | Turns the view by `degrees`. Animated unless `animate` is false or the reader asked for reduced motion |
+| `turnTo({ turn, tilt }, animate)` | Moves the camera to a bearing, a height, or both |
+
 ## What it exports
 
 | Import | What |
@@ -358,6 +411,7 @@ connectGraph(frame, threeDriver(box), {
 | `@fusion.dev/helix-graph/sigma` | `sigmaDriver(sigma, options)`, and the types `SigmaDriverOptions`, `SigmaGraph`, `SigmaLayout` and `SigmaRenderer` |
 | `@fusion.dev/helix-graph/cosmos` | `cosmosDriver(graph, box, options)`, and the types `CosmosDriverOptions` and `CosmosGraph` |
 | `@fusion.dev/helix-graph/three` | `threeDriver(box, options)`, and the type `ThreeDriverOptions` |
+| `@fusion.dev/helix-graph/isometric` | `isometricDriver(box, options)`, `ISOMETRIC`, the camera it starts from, and the types `Camera`, `IsometricDriver` and `IsometricDriverOptions` |
 | `@fusion.dev/helix-graph/shapes` | `shapeFromTriangles`, `shapeFromSvg`, `shapeFromImage`, `shapeFromPath`, `shapeFromInside`, `inflate`, `sphere`, `torus`, `cuboid`, `onSphere`, `surfaceOf`, and the types `ImageOptions`, `ShapeField` and `TriangleOptions` |
 | `@fusion.dev/helix-graph/model` | `shapeFromModel(source, options)`, which needs three.js |
 | `@fusion.dev/helix-graph/snapshot` | `graphSnapshot(nodes, links, options)`, an SVG of the graph to paint before the renderer loads, and the types `GraphSnapshotOptions`, `SnapshotLink` and `SnapshotNode` |

package/dist/isometric/geometry.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Where an isometric diagram puts each note, link, and group, as SVG path
+ * data, seen from a camera that can turn and tilt. Pure, so the arithmetic a
+ * picture hides is held by a spec: a solid painted in the wrong order is
+ * covered by the one it should cover, and a face turned away is drawn over
+ * the faces in front of it.
+ *
+ * **The floor is measured in cells.** A note at `x: 2, y: 1` stands two cells
+ * across and one back, and a solid's height is in the same unit. From the
+ * isometric camera, across runs down to the right on the page and back runs
+ * up to the right, as a plan is seen from its front left corner.
+ */
+/** A point on the page, in cells. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Where the diagram is seen from, in degrees: `turn`, the compass bearing
+ * the camera looks from, and `tilt`, its height above the floor, from a low
+ * angle to 90, a plan seen straight down.
+ */
+export interface Camera {
+    tilt: number;
+    turn: number;
+}
+/**
+ * The isometric camera: from the front left corner, at the height where the
+ * floor's two axes and the vertical are drawn the same length, 35.26 degrees.
+ */
+export declare const ISOMETRIC: Camera;
+/** The lowest a camera may tilt, below which the floor folds to a line. */
+export declare const LOWEST_TILT = 15;
+/** A camera's view of the floor. */
+export interface Projection {
+    /** A place on the floor and a height, on the page. */
+    at(x: number, y: number, z?: number): Point;
+    /** How near the camera a place on the floor stands: the larger, the nearer. */
+    depth(x: number, y: number): number;
+    /** The place on the floor drawn at a point on the page. */
+    floorAt(point: Point): Point;
+    /** Toward the camera from the floor, a unit length: across, back, and up. */
+    toward: readonly [number, number, number];
+    /** Across the page, in floor directions: how far a step across or back goes to the right. */
+    across: readonly [number, number];
+}
+/**
+ * The view from `camera`, an orthographic one: the floor turned by `turn`
+ * and seen from `tilt` above it, with no perspective, so a cell is the same
+ * size wherever it stands.
+ */
+export declare const projectionOf: (camera: Camera) => Projection;
+/** The solids a note can be drawn as, one for each of the frame's shapes. */
+export type Solid = 'block' | 'cylinder' | 'pyramid';
+/** A note's shape, as the frame names it, and the solid that stands for it. */
+export declare const solidOf: (shape: string | undefined) => Solid;
+/** One face of a solid, as path data, and how far it is darkened toward black. */
+export interface Face {
+    d: string;
+    /** From 0, the note's own color, as a top facing the light takes it. */
+    darken: number;
+}
+/** One note drawn as a solid: the faces the camera sees, in the order to paint them. */
+export interface Drawn {
+    /** How high the solid reaches on the page: the top of its outline, which its name is drawn above. */
+    crown: number;
+    /** The faces the camera sees, the sides first and the top last. */
+    faces: Face[];
+    /** The outline of the whole solid, which a ring is drawn along. */
+    outline: string;
+    /** The middle of the solid's top, which its name is centered over. */
+    peak: Point;
+}
+/**
+ * A note as a solid, standing on the floor at `x` and `y`, `width` cells
+ * across its footprint and `height` cells tall, as the camera sees it.
+ *
+ * **Each face is drawn only where it turns toward the camera**, so a block
+ * shows its top and the two sides that face the viewer from any turn, and a
+ * plan seen from straight above shows tops alone.
+ */
+export declare const solid: (projection: Projection, kind: Solid, x: number, y: number, width: number, height: number) => Drawn;
+/**
+ * The order to paint notes in, back to front: by how near the camera each
+ * stands on the floor, and the taller first where two stand level.
+ *
+ * Exact for notes on whole cells, which do not overlap on the floor; two
+ * notes placed inside one cell can still cross.
+ */
+export declare const depthOrder: <T extends {
+    height: number;
+    x: number;
+    y: number;
+}>(projection: Projection, notes: readonly T[]) => T[];
+/** A link drawn on the floor from the middle of one note's footprint to the other's. */
+export declare const floorLine: (projection: Projection, from: Point, to: Point) => string;
+/**
+ * A group's plate on the floor: the rectangle around its notes' cells,
+ * `margin` cells wider on every side, and where its name is written.
+ *
+ * **The name runs along the edge nearest the camera**, left to right on the
+ * page, laid on the floor: `transform` is the SVG matrix that writes text
+ * there, a font size in cells, from `start`, a cell of text running `along`
+ * on the page.
+ */
+export declare const plate: (projection: Projection, places: readonly Point[], margin: number) => {
+    along: Point;
+    d: string;
+    start: Point;
+    transform: string;
+} | undefined;
+/**
+ * Places each note in `unplaced` on the nearest whole cell that keeps
+ * `spacing` cells from every note already placed, starting from where it was
+ * seeded, so a diagram given no places is a tidy grid with each note beside
+ * the ones it links to. A note the page placed keeps its place.
+ */
+export declare const snapToCells: (seeded: ReadonlyMap<string, Point>, unplaced: ReadonlySet<string>, spacing?: number) => Map<string, Point>;
+/**
+ * Places a diagram that gives no note a place, in columns along the flow of
+ * its links, `spacing` cells apart.
+ *
+ * **A note's column is the longest run of links that leads to it**, so a
+ * source stands first and everything it feeds stands after it, as a pipeline
+ * or a request through a service is read. Within a column the notes sort by
+ * their group, so a group's plate covers one stretch, and then by where the
+ * notes leading to them stand, so links cross as little as one pass can
+ * make them. A loop is cut where it would carry a note past the last column.
+ */
+export declare const layered: (notes: readonly {
+    group?: string | undefined;
+    id: string;
+}[], links: readonly {
+    source: string;
+    target: string;
+}[], spacing?: number) => Map<string, Point>;

package/dist/isometric/geometry.js

@@ -0,0 +1,280 @@
+export const ISOMETRIC = { tilt: (Math.atan(Math.SQRT1_2) * 180) / Math.PI, turn: 45 };
+export const LOWEST_TILT = 15;
+const SCALE = Math.sqrt(1.5);
+export const projectionOf = (camera) => {
+    const turn = (camera.turn * Math.PI) / 180;
+    const tilt = (Math.min(Math.max(camera.tilt, LOWEST_TILT), 90) * Math.PI) / 180;
+    const [cos, sin] = [Math.cos(turn), Math.sin(turn)];
+    const [rise, fall] = [Math.sin(tilt), Math.cos(tilt)];
+    return {
+        across: [cos, sin],
+        at: (x, y, z = 0) => ({
+            x: (x * cos + y * sin) * SCALE,
+            y: ((x * sin - y * cos) * rise - z * fall) * SCALE,
+        }),
+        depth: (x, y) => x * sin - y * cos,
+        floorAt: (point) => {
+            const u = point.x / SCALE;
+            const v = point.y / SCALE / rise;
+            return { x: u * cos + v * sin, y: u * sin - v * cos };
+        },
+        toward: [sin * fall, -cos * fall, rise],
+    };
+};
+export const solidOf = (shape) => shape === 'circle' || shape === 'ring' ? 'cylinder' : shape === 'diamond' ? 'pyramid' : 'block';
+const short = (value) => String(Math.round(value * 1000) / 1000 || 0);
+const path = (points) => `M${points.map((point) => `${short(point.x)} ${short(point.y)}`).join('L')}Z`;
+const hullOf = (points) => {
+    const sorted = [...points].sort((one, other) => one.x - other.x || one.y - other.y);
+    if (sorted.length < 3) {
+        return sorted;
+    }
+    const cross = (o, a, b) => (a.x - o.x) * (b.y - o.y) - (a.y - o.y) * (b.x - o.x);
+    const half = (list) => {
+        const kept = [];
+        for (const point of list) {
+            while (kept.length >= 2 && cross(kept.at(-2), kept.at(-1), point) <= 0) {
+                kept.pop();
+            }
+            kept.push(point);
+        }
+        kept.pop();
+        return kept;
+    };
+    return [...half(sorted), ...half([...sorted].reverse())];
+};
+const darkenOf = (normal, projection) => {
+    const [x, y, z] = normal;
+    const length = Math.hypot(x, y, z) || 1;
+    const level = Math.hypot(x, y) || 1;
+    const right = (x * projection.across[0] + y * projection.across[1]) / level;
+    return Math.max(0, 0.28 + 0.113 * right) * (1 - z / length);
+};
+const facing = (normal, projection) => normal[0] * projection.toward[0] +
+    normal[1] * projection.toward[1] +
+    normal[2] * projection.toward[2] >
+    1e-6;
+const ARC = 12;
+export const solid = (projection, kind, x, y, width, height) => {
+    const half = width / 2;
+    const tall = Math.max(0, height);
+    const on = (corner) => projection.at(corner[0], corner[1], corner[2]);
+    if (kind === 'cylinder') {
+        const turn = Math.atan2(projection.across[1], projection.across[0]);
+        const rim = (z, from, to) => Array.from({ length: ARC + 1 }, (_, step) => {
+            const angle = from + ((to - from) * step) / ARC;
+            return projection.at(x + Math.cos(angle) * half, y + Math.sin(angle) * half, z);
+        });
+        const near = rim(0, turn + Math.PI, turn + 2 * Math.PI);
+        const nearTop = rim(tall, turn + Math.PI, turn + 2 * Math.PI);
+        const farTop = rim(tall, turn, turn + Math.PI);
+        const top = rim(tall, 0, 2 * Math.PI).slice(0, -1);
+        const side = projection.toward[2] < 0.9999 && tall > 0;
+        const outline = hullOf([...farTop, ...nearTop, ...near]);
+        return {
+            crown: Math.min(...outline.map((point) => point.y)),
+            faces: [
+                ...(side ? [{ d: path([...nearTop, ...[...near].reverse()]), darken: 0.28 }] : []),
+                { d: path(top), darken: 0 },
+            ],
+            outline: path(outline),
+            peak: projection.at(x, y, tall),
+        };
+    }
+    const floor = [
+        [x - half, y - half, 0],
+        [x + half, y - half, 0],
+        [x + half, y + half, 0],
+        [x - half, y + half, 0],
+    ];
+    const outward = [
+        [0, -1, 0],
+        [1, 0, 0],
+        [0, 1, 0],
+        [-1, 0, 0],
+    ];
+    const faces = [];
+    let corners;
+    let peak;
+    if (kind === 'pyramid') {
+        const apex = [x, y, Math.max(tall, width)];
+        corners = [...floor, apex];
+        peak = on(apex);
+        floor.forEach((corner, at) => {
+            const next = floor[(at + 1) % 4];
+            const [ox, oy] = outward[at];
+            const normal = [ox * apex[2], oy * apex[2], half];
+            if (facing(normal, projection)) {
+                faces.push({
+                    d: path([on(corner), on(next), on(apex)]),
+                    darken: darkenOf(normal, projection),
+                });
+            }
+        });
+    }
+    else {
+        const up = (corner) => [corner[0], corner[1], tall];
+        corners = [...floor, ...floor.map(up)];
+        peak = projection.at(x, y, tall);
+        if (tall > 0) {
+            floor.forEach((corner, at) => {
+                const next = floor[(at + 1) % 4];
+                const normal = outward[at];
+                if (facing(normal, projection)) {
+                    faces.push({
+                        d: path([on(up(corner)), on(up(next)), on(next), on(corner)]),
+                        darken: darkenOf(normal, projection),
+                    });
+                }
+            });
+        }
+        faces.push({ d: path(floor.map(up).map(on)), darken: 0 });
+    }
+    const outline = hullOf(corners.map(on));
+    return {
+        crown: Math.min(...outline.map((point) => point.y)),
+        faces,
+        outline: path(outline),
+        peak,
+    };
+};
+export const depthOrder = (projection, notes) => [...notes].sort((one, other) => {
+    const nearer = projection.depth(one.x, one.y) - projection.depth(other.x, other.y);
+    return Math.abs(nearer) > 1e-9 ? nearer : other.height - one.height;
+});
+export const floorLine = (projection, from, to) => {
+    const start = projection.at(from.x, from.y);
+    const end = projection.at(to.x, to.y);
+    return `M${short(start.x)} ${short(start.y)}L${short(end.x)} ${short(end.y)}`;
+};
+export const plate = (projection, places, margin) => {
+    if (places.length === 0) {
+        return undefined;
+    }
+    const xs = places.map((place) => place.x);
+    const ys = places.map((place) => place.y);
+    const low = { x: Math.min(...xs) - margin, y: Math.min(...ys) - margin };
+    const high = { x: Math.max(...xs) + margin, y: Math.max(...ys) + margin };
+    const corners = [
+        { x: low.x, y: low.y },
+        { x: high.x, y: low.y },
+        { x: high.x, y: high.y },
+        { x: low.x, y: high.y },
+    ];
+    const outward = [
+        { x: 0, y: -1 },
+        { x: 1, y: 0 },
+        { x: 0, y: 1 },
+        { x: -1, y: 0 },
+    ];
+    const facingOf = (normal) => normal.x * projection.toward[0] + normal.y * projection.toward[1];
+    const edge = [0, 1, 2, 3].reduce((best, at) => facingOf(outward[at]) > facingOf(outward[best]) ? at : best);
+    const normal = outward[edge];
+    let [from, to] = [corners[edge], corners[(edge + 1) % 4]];
+    if (projection.at(to.x, to.y).x < projection.at(from.x, from.y).x) {
+        ;
+        [from, to] = [to, from];
+    }
+    const length = Math.hypot(to.x - from.x, to.y - from.y) || 1;
+    const along = { x: (to.x - from.x) / length, y: (to.y - from.y) / length };
+    const origin = projection.at(0, 0);
+    const step = (direction) => {
+        const at = projection.at(direction.x, direction.y);
+        return { x: at.x - origin.x, y: at.y - origin.y };
+    };
+    const a = step(along);
+    const b = step(normal);
+    const start = projection.at(from.x + along.x * 0.15 - normal.x * 0.12, from.y + along.y * 0.15 - normal.y * 0.12);
+    return {
+        along: a,
+        d: path(corners.map((corner) => projection.at(corner.x, corner.y))),
+        start,
+        transform: `matrix(${[a.x, a.y, b.x, b.y, start.x, start.y].map(short).join(' ')})`,
+    };
+};
+export const snapToCells = (seeded, unplaced, spacing = 2) => {
+    const taken = [];
+    for (const [id, at] of seeded) {
+        if (!unplaced.has(id)) {
+            taken.push({ x: Math.round(at.x), y: Math.round(at.y) });
+        }
+    }
+    const free = (cell) => taken.every((other) => Math.max(Math.abs(other.x - cell.x), Math.abs(other.y - cell.y)) >= spacing);
+    const placed = new Map();
+    for (const id of unplaced) {
+        const at = seeded.get(id) ?? { x: 0, y: 0 };
+        const home = { x: Math.round(at.x), y: Math.round(at.y) };
+        for (let ring = 0;; ring++) {
+            const cells = [];
+            for (let dx = -ring; dx <= ring; dx++) {
+                for (let dy = -ring; dy <= ring; dy++) {
+                    if (Math.max(Math.abs(dx), Math.abs(dy)) === ring) {
+                        cells.push({ x: home.x + dx, y: home.y + dy });
+                    }
+                }
+            }
+            cells.sort((one, other) => Math.hypot(one.x - at.x, one.y - at.y) - Math.hypot(other.x - at.x, other.y - at.y));
+            const cell = cells.find(free);
+            if (cell) {
+                taken.push(cell);
+                placed.set(id, cell);
+                break;
+            }
+        }
+    }
+    return placed;
+};
+export const layered = (notes, links, spacing = 2) => {
+    const ids = notes.map((note) => note.id);
+    const known = new Set(ids);
+    const into = new Map(ids.map((id) => [id, []]));
+    for (const { source, target } of links) {
+        if (known.has(source) && known.has(target) && source !== target) {
+            into.get(target)?.push(source);
+        }
+    }
+    const column = new Map(ids.map((id) => [id, 0]));
+    for (let pass = 0; pass < ids.length; pass++) {
+        let moved = false;
+        for (const id of ids) {
+            for (const from of into.get(id) ?? []) {
+                const next = (column.get(from) ?? 0) + 1;
+                if (next > (column.get(id) ?? 0) && next < ids.length) {
+                    column.set(id, next);
+                    moved = true;
+                }
+            }
+        }
+        if (!moved) {
+            break;
+        }
+    }
+    const groupOf = new Map(notes.map((note) => [note.id, note.group ?? '']));
+    const columns = [];
+    for (const id of ids) {
+        const at = column.get(id) ?? 0;
+        columns[at] = [...(columns[at] ?? []), id];
+    }
+    const row = new Map();
+    const placed = new Map();
+    columns.forEach((members = [], at) => {
+        const pull = (id) => {
+            const rows = (into.get(id) ?? []).flatMap((from) => {
+                const one = row.get(from);
+                return one === undefined ? [] : [one];
+            });
+            return rows.length === 0
+                ? members.indexOf(id)
+                : rows.reduce((sum, one) => sum + one, 0) / rows.length;
+        };
+        const sorted = [...members].sort((one, other) => (groupOf.get(one) ?? '').localeCompare(groupOf.get(other) ?? '') || pull(one) - pull(other));
+        sorted.forEach((id, index) => {
+            row.set(id, index - (sorted.length - 1) / 2);
+            placed.set(id, {
+                x: at * spacing,
+                y: -Math.round((index - (sorted.length - 1) / 2) * spacing) || 0,
+            });
+        });
+    });
+    return placed;
+};

package/dist/isometric/index.d.ts

@@ -0,0 +1,2 @@
+export { type Camera, ISOMETRIC } from './geometry.js';
+export { type IsometricDriver, type IsometricDriverOptions, isometricDriver, } from './isometric-driver.js';

package/dist/isometric/index.js

@@ -0,0 +1,2 @@
+export { ISOMETRIC } from './geometry.js';
+export { isometricDriver, } from './isometric-driver.js';

package/dist/isometric/isometric-driver.d.ts

@@ -0,0 +1,75 @@
+import type { GraphDriver } from '../connect-graph/connect-graph.js';
+import { type NodeLook } from '../connect-graph/looks.js';
+import { type Camera } from './geometry.js';
+/** How the diagram is drawn where a note does not say. */
+export interface IsometricDriverOptions {
+    /** Draws every note at no height, which lays the diagram flat on its floor. */
+    flat?: boolean | undefined;
+    /** Whether each group's name is written on its plate. On by default. */
+    groupLabels?: boolean | undefined;
+    /**
+     * A note's solid where it gives no `shape`: `square`, a block, by default;
+     * `circle` or `ring`, a cylinder; `diamond`, a pyramid.
+     */
+    shape?: NodeLook['shape'];
+    /**
+     * How high above the floor the diagram is seen from, in degrees: 35.26,
+     * the isometric angle, by default, down to 15, and up to 90, a plan seen
+     * from straight above.
+     */
+    tilt?: number | undefined;
+    /**
+     * The compass bearing the diagram is seen from, in degrees: 45, its front
+     * left corner, by default. 135 is its front right, 225 its back right, and
+     * 315 its back left.
+     */
+    turn?: number | undefined;
+}
+/** The isometric driver, which a page can also turn. */
+export interface IsometricDriver extends GraphDriver {
+    /** Where the diagram is seen from now: its `turn` and `tilt`, in degrees. */
+    camera(): Camera;
+    /**
+     * Turns the view about the middle of the box by `degrees`: 90 brings the
+     * next corner round to the front. Animated unless `animate` is false or the
+     * reader asked for less motion.
+     */
+    turnBy(degrees: number, animate?: boolean): void;
+    /** Moves the camera to a `turn` or a `tilt`, or both, as `turnBy` moves it. */
+    turnTo(camera: Partial<Camera>, animate?: boolean): void;
+}
+/**
+ * Draws the graph of a `helix-graph` frame as an isometric diagram in SVG,
+ * for architecture and flow diagrams. Pass it to `connectGraph` with the
+ * element to draw in:
+ *
+ * ```js
+ * import { connectGraph } from '@fusion.dev/helix-graph'
+ * import { isometricDriver } from '@fusion.dev/helix-graph/isometric'
+ *
+ * connectGraph(frame, isometricDriver(frame.querySelector('.diagram')))
+ * ```
+ *
+ * **Each note is a solid on a floor of cells**, standing at its `x` and `y`:
+ * a note at `x: 2, y: 1` is two cells across and one back. Its `shape` picks
+ * the solid, a square a block, a circle a cylinder, and a diamond a pyramid,
+ * and its size sets its height. A diagram that gives no note a place is laid
+ * out in columns along its links, and a note added without one goes to the
+ * nearest free cell beside the notes it links to.
+ *
+ * **The faces are shaded from the note's own color**, its tone's or its
+ * group's, so the diagram takes the theme. Links run along the floor with an
+ * arrow halfway that points the way each runs, and each group stands on a
+ * plate of its color with its name written on the floor.
+ *
+ * **SVG and nothing else**: no renderer to install, no WebGL context, and
+ * text as crisp as the page's. The frame's list, search, and keys work as
+ * they do with every driver. Drag to pan and use the wheel to zoom, as the
+ * frame's `gestures` allows.
+ *
+ * **The view turns and tilts.** `turn` and `tilt` set where it is seen from,
+ * `turnBy(90)` brings the next corner round, and Shift with a drag turns it
+ * across and tilts it up and down. The faces a solid shows and how each is
+ * shaded follow the camera, with the light from the upper left of the page.
+ */
+export declare const isometricDriver: (container: HTMLElement, options?: IsometricDriverOptions) => IsometricDriver;