@issuegraph/viewer 0.1.0

package/dist/element.js

@@ -0,0 +1,174 @@
+/**
+ * One description of rendered structure, and the two renderers that consume it.
+ *
+ * A projection returns an {@link ElementSpec} tree. {@link renderMarkup} turns
+ * it into a string — server rendering, and every test in this package that
+ * asserts what is drawn. {@link materialize} builds the same tree out of real
+ * nodes for {@link ../mount.ts mountViewer}.
+ *
+ * THE POINT IS THAT THEY CANNOT DISAGREE. The obvious alternative — build
+ * markup, then set `innerHTML` — makes the string path and the node path one
+ * implementation but leaves the package unable to render without a parser; the
+ * other obvious alternative, writing the DOM path separately, makes them two
+ * implementations that drift. One spec with two total walks over it is the only
+ * arrangement where a test on the markup is evidence about the nodes.
+ *
+ * Nothing here reaches a global. {@link materialize} takes the document it
+ * builds into, which is what keeps this module importable on a runtime that has
+ * no DOM at all.
+ */
+export const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+/**
+ * HTML elements that may not carry children and must not be given a closing
+ * tag. An empty non-void element still renders `<div></div>`, because
+ * `<div/>` is not self-closing in HTML and browsers nest whatever follows it.
+ */
+const VOID_HTML_TAGS = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'source',
+    'track',
+    'wbr',
+]);
+function escapeText(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function escapeAttr(value) {
+    return escapeText(value).replace(/"/g, '&quot;');
+}
+function isSpec(child) {
+    return typeof child !== 'string';
+}
+function renderAttrs(attrs) {
+    if (attrs === undefined)
+        return '';
+    const parts = [];
+    for (const [name, value] of Object.entries(attrs)) {
+        if (value === undefined || value === null || value === false)
+            continue;
+        if (value === true) {
+            parts.push(` ${name}`);
+            continue;
+        }
+        parts.push(` ${name}="${escapeAttr(typeof value === 'number' ? String(value) : value)}"`);
+    }
+    return parts.join('');
+}
+/**
+ * Render a spec tree to markup.
+ *
+ * Pure and deterministic: attribute order follows the spec's own key order, so
+ * the same tree always produces the same bytes. That is what makes a
+ * two-themes-one-markup assertion possible.
+ *
+ * ITERATIVE, LIKE EVERY OTHER WALK IN THIS PACKAGE. A recursive renderer costs
+ * one call frame per level of nesting, and the tree projection's depth is the
+ * host's `decomposed-from` chain — which nothing bounds. `renderViewer`
+ * documents itself as TOTAL, so a document that makes it throw falsifies the
+ * claim whatever the depth was. This was the third stack-depth finding on this
+ * package; making the traversal iterative removes the class rather than
+ * capping the input, which would have invented a product rule the design does
+ * not have.
+ */
+export function renderMarkup(spec, inheritedNs) {
+    const out = [];
+    const stack = [{ kind: 'open', spec, ns: inheritedNs }];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame.kind === 'close') {
+            out.push(`</${frame.tag}>`);
+            continue;
+        }
+        if (frame.kind === 'text') {
+            out.push(escapeText(frame.text));
+            continue;
+        }
+        const ns = frame.spec.ns ?? frame.ns;
+        const open = `<${frame.spec.tag}${renderAttrs(frame.spec.attrs)}`;
+        const children = frame.spec.children ?? [];
+        if (children.length === 0) {
+            out.push(ns === 'svg' || VOID_HTML_TAGS.has(frame.spec.tag)
+                ? `${open} />`
+                : `${open}></${frame.spec.tag}>`);
+            continue;
+        }
+        out.push(`${open}>`);
+        stack.push({ kind: 'close', tag: frame.spec.tag });
+        // Pushed in reverse so they pop in document order.
+        for (let index = children.length - 1; index >= 0; index -= 1) {
+            const child = children[index];
+            stack.push(isSpec(child) ? { kind: 'open', spec: child, ns } : { kind: 'text', text: child });
+        }
+    }
+    return out.join('');
+}
+/**
+ * Build a spec tree as nodes in the supplied document.
+ *
+ * Attributes follow `renderMarkup`'s rules exactly — same omissions, same
+ * number coercion, same bare-attribute handling for `true` — because the two
+ * walks are only useful as one grammar.
+ */
+export function materialize(doc, spec, options = {}) {
+    // Iterative for the reason `renderMarkup` is: the two walks are only useful
+    // as one grammar, so they have to share the depth behaviour too.
+    const stack = [{ kind: 'element', spec, ns: options.ns, parent: null }];
+    let root = null;
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame.kind === 'text') {
+            frame.parent.appendChild(doc.createTextNode(frame.text));
+            continue;
+        }
+        const ns = frame.spec.ns ?? frame.ns;
+        const built = ns === 'svg'
+            ? doc.createElementNS(SVG_NAMESPACE, frame.spec.tag)
+            : doc.createElement(frame.spec.tag);
+        if (frame.spec.attrs !== undefined) {
+            for (const [name, value] of Object.entries(frame.spec.attrs)) {
+                if (value === undefined || value === null || value === false)
+                    continue;
+                built.setAttribute(name, value === true ? '' : String(value));
+            }
+        }
+        options.onElement?.(frame.spec, built);
+        // Appended on the way DOWN, so a node is in place before its own children
+        // are popped. That is what keeps sibling order right without holding the
+        // parent's frame open, which is the whole point of dropping the recursion.
+        if (frame.parent === null)
+            root = built;
+        else
+            frame.parent.appendChild(built);
+        const children = frame.spec.children ?? [];
+        // Pushed in reverse so they pop in document order.
+        for (let index = children.length - 1; index >= 0; index -= 1) {
+            const child = children[index];
+            stack.push(isSpec(child)
+                ? { kind: 'element', spec: child, ns, parent: built }
+                : { kind: 'text', text: child, parent: built });
+        }
+    }
+    // The seed frame always builds an element, so this is set by the first pass.
+    return root;
+}
+/** A spec, with `undefined` children dropped — the common conditional-child case. */
+export function element(tag, attrs, children = []) {
+    return {
+        tag,
+        attrs,
+        children: children.filter((child) => child !== null && child !== undefined && child !== false),
+    };
+}
+/** The same, in the SVG namespace. */
+export function svg(tag, attrs, children = []) {
+    return { ...element(tag, attrs, children), ns: 'svg' };
+}
+//# sourceMappingURL=element.js.map

package/dist/element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.js","sourceRoot":"","sources":["../src/element.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAeH,MAAM,CAAC,MAAM,aAAa,GAAG,4BAA4B,CAAC;AAE1D;;;;GAIG;AACH,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IAClD,MAAM;IACN,MAAM;IACN,IAAI;IACJ,KAAK;IACL,OAAO;IACP,IAAI;IACJ,KAAK;IACL,OAAO;IACP,MAAM;IACN,MAAM;IACN,QAAQ;IACR,OAAO;IACP,KAAK;CACN,CAAC,CAAC;AAEH,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAClF,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,MAAM,CAAC,KAAgB;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;AACnC,CAAC;AAED,SAAS,WAAW,CAAC,KAAsD;IACzE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK;YAAE,SAAS;QACvE,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;YACvB,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,UAAU,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,IAAiB,EAAE,WAA+B;IAM7E,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,KAAK,GAAY,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;IAEjE,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAW,CAAC;QACnC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YACjC,SAAS;QACX,CAAC;QAED,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAClE,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;QAC3C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,GAAG,CAAC,IAAI,CACN,EAAE,KAAK,KAAK,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;gBAChD,CAAC,CAAC,GAAG,IAAI,KAAK;gBACd,CAAC,CAAC,GAAG,IAAI,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,CACnC,CAAC;YACF,SAAS;QACX,CAAC;QAED,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACnD,mDAAmD;QACnD,KAAK,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAC7D,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAc,CAAC;YAC3C,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC;AAyCD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,GAAiB,EACjB,IAAiB,EACjB,UAA8B,EAAE;IAWhC,4EAA4E;IAC5E,iEAAiE;IACjE,MAAM,KAAK,GAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACjF,IAAI,IAAI,GAAuB,IAAI,CAAC;IAEpC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAW,CAAC;QACnC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YACzD,SAAS;QACX,CAAC;QAED,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,KAAK,GACT,EAAE,KAAK,KAAK;YACV,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,aAAa,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;YACpD,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAExC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACnC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK;oBAAE,SAAS;gBACvE,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;QAED,OAAO,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAEvC,0EAA0E;QAC1E,yEAAyE;QACzE,2EAA2E;QAC3E,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI;YAAE,IAAI,GAAG,KAAK,CAAC;;YACnC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAErC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;QAC3C,mDAAmD;QACnD,KAAK,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAC7D,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAc,CAAC;YAC3C,KAAK,CAAC,IAAI,CACR,MAAM,CAAC,KAAK,CAAC;gBACX,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;gBACrD,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CACjD,CAAC;QACJ,CAAC;IACH,CAAC;IACD,6EAA6E;IAC7E,OAAO,IAAmB,CAAC;AAC7B,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,OAAO,CACrB,GAAW,EACX,KAA0C,EAC1C,WAA8D,EAAE;IAEhE,OAAO;QACL,GAAG;QACH,KAAK;QACL,QAAQ,EAAE,QAAQ,CAAC,MAAM,CACvB,CAAC,KAAK,EAAsB,EAAE,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,KAAK,CACxF;KACF,CAAC;AACJ,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,GAAG,CACjB,GAAW,EACX,KAA0C,EAC1C,WAA8D,EAAE;IAEhE,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;AACzD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@issuegraph/viewer` — render an Issuegraph document as a work order.
+ *
+ * The innermost layer of the Issuegraph UI, and the whole of its contract:
+ *
+ *     in   {issues, edges, order} + a projection choice
+ *     out  onSelect, onHover
+ *     never  fetching, mutation, auth, persistence, or a host's vocabulary
+ *
+ * It owns the node, edge and badge grammar, the layout maths and the readiness
+ * stations. It derives no order — `@issuegraph/derive` does that, and a second
+ * implementation here would be a mirror whose input space drifts.
+ *
+ * Two entry points: {@link renderViewer} is pure and returns markup plus
+ * styles, which is what server rendering and every test in this package use;
+ * {@link mountViewer} builds the same tree as nodes and wires the two callbacks.
+ *
+ * THE SURFACE IS WHAT A CONSUMER CALLS, and no more. Internals stay internal
+ * because a published package can add an export later and can never take one
+ * back.
+ *
+ * @see https://github.com/autnmy/issuegraph/blob/main/SPEC.md
+ */
+export type { HoldFamily, NormalizeResult, NormalizedDocument, RankProvenance, ViewerDocument, ViewerEdge, ViewerExclusion, ViewerHold, ViewerIssue, ViewerOrder, ViewerSlot, } from './document.ts';
+export { normalizeDocument } from './document.ts';
+export type { Projection, Scene } from './scene.ts';
+export { KEY_ATTRIBUTE } from './scene.ts';
+export type { RenderOptions, RenderResult } from './render.ts';
+export { renderViewer } from './render.ts';
+export type { MountElement, MountEvent, MountOptions, ViewerHandle, } from './mount.ts';
+export { mountViewer } from './mount.ts';
+export type { NavigationCommand, NavigationResult, NavigationState } from './navigation.ts';
+export { initialNavigationState, navigate, reconcile } from './navigation.ts';
+export type { ColorToken, MetricToken, Theme, ThemeOverride, TypeToken, } from './theme.ts';
+export { COLOR_TOKENS, METRIC_TOKENS, THEME_TOKENS, TYPE_TOKENS, defaultTheme, extendTheme, themeCss, } from './theme.ts';
+export { viewerStylesheet } from './styles.ts';
+export type { EdgeDash, EdgeTerminal, EdgeTreatment, OrderingEffect } from './vocabulary.ts';
+export { EDGE_TREATMENTS, dashArrayFor, treatmentFor } from './vocabulary.ts';
+export { CLUSTER_ONLY_BUDGET, GRAPH_NODE_BUDGET } from './projections/graph.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,YAAY,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,UAAU,EACV,eAAe,EACf,UAAU,EACV,WAAW,EACX,WAAW,EACX,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,YAAY,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAAE,sBAAsB,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE9E,YAAY,EACV,UAAU,EACV,WAAW,EACX,KAAK,EACL,aAAa,EACb,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * `@issuegraph/viewer` — render an Issuegraph document as a work order.
+ *
+ * The innermost layer of the Issuegraph UI, and the whole of its contract:
+ *
+ *     in   {issues, edges, order} + a projection choice
+ *     out  onSelect, onHover
+ *     never  fetching, mutation, auth, persistence, or a host's vocabulary
+ *
+ * It owns the node, edge and badge grammar, the layout maths and the readiness
+ * stations. It derives no order — `@issuegraph/derive` does that, and a second
+ * implementation here would be a mirror whose input space drifts.
+ *
+ * Two entry points: {@link renderViewer} is pure and returns markup plus
+ * styles, which is what server rendering and every test in this package use;
+ * {@link mountViewer} builds the same tree as nodes and wires the two callbacks.
+ *
+ * THE SURFACE IS WHAT A CONSUMER CALLS, and no more. Internals stay internal
+ * because a published package can add an export later and can never take one
+ * back.
+ *
+ * @see https://github.com/autnmy/issuegraph/blob/main/SPEC.md
+ */
+export { normalizeDocument } from "./document.js";
+export { KEY_ATTRIBUTE } from "./scene.js";
+export { renderViewer } from "./render.js";
+export { mountViewer } from "./mount.js";
+export { initialNavigationState, navigate, reconcile } from "./navigation.js";
+export { COLOR_TOKENS, METRIC_TOKENS, THEME_TOKENS, TYPE_TOKENS, defaultTheme, extendTheme, themeCss, } from "./theme.js";
+export { viewerStylesheet } from "./styles.js";
+export { EDGE_TREATMENTS, dashArrayFor, treatmentFor } from "./vocabulary.js";
+export { CLUSTER_ONLY_BUDGET, GRAPH_NODE_BUDGET } from "./projections/graph.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAeH,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQ3C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAE,sBAAsB,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAS9E,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/layout.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Graph geometry, computed — never eyeballed.
+ *
+ * Three columns, three jobs: the LEFT GUTTER holds open issues outside the
+ * order that explain a hold, the CENTRE SPINE is the work order itself, and the
+ * RIGHT GUTTER holds issues the order never works. Sequence is vertical
+ * position on the spine; dependency is everything off it.
+ *
+ * Two rules carry most of the weight, and both come from the design's
+ * implementation note rather than from taste:
+ *
+ *  - **Every edge endpoint is derived from a node's computed bounds.** An edge
+ *    terminates ON a bound, never at a remembered offset, so a node that
+ *    changes size moves its edges with it.
+ *  - **Arcs stay out of the occupied x-ranges** and out of the station band.
+ *    The colour-blind-safety claim rests on four redundant channels, and the
+ *    terminal marker is the one that separates `decomposed-from` from
+ *    `duplicate-of` — a marker hidden under an opaque card silently drops the
+ *    encoding to three.
+ *
+ * Deterministic by construction: no measurement, no randomness, no clock. The
+ * same document always produces the same coordinates, which is what lets a
+ * panel whose job is to be authoritative be trusted between refreshes.
+ */
+import type { NormalizedDocument, ViewerEdge } from './document.ts';
+import type { Theme } from './theme.ts';
+/**
+ * Custom properties carrying LAYOUT OUTPUT rather than theme input.
+ *
+ * A theme token is a value a host chooses; these are values this module
+ * COMPUTES and writes onto individual elements, so the rail can sit on the node
+ * it names without either side hard-coding a coordinate. They are declared here
+ * so `styles.test.ts` can tell the two kinds apart — a `var()` naming neither a
+ * theme token nor one of these is still a defect, and still fails.
+ */
+export declare const LAYOUT_PROPERTIES: readonly string[];
+/** Which column a node sits in. */
+export type Column = 'left' | 'spine' | 'right';
+export interface NodeBox {
+    readonly key: string;
+    readonly column: Column;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    /** The slot this node belongs to, when it is on the spine. */
+    readonly rank: number | null;
+    readonly held: boolean;
+}
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+export interface GraphLayout {
+    readonly width: number;
+    readonly height: number;
+    readonly nodes: ReadonlyMap<string, NodeBox>;
+    /** Spine keys in RANK order — the order navigation walks. */
+    readonly spineOrder: readonly string[];
+    /** Slot lead -> the members drawn under it, in document order. */
+    readonly slotMembers: ReadonlyMap<string, readonly string[]>;
+    /** The free vertical channels arcs route through. */
+    readonly leftChannel: number;
+    readonly rightChannel: number;
+}
+/**
+ * A node's width follows its own contents rather than the column, so an edge
+ * terminating on its bound lands where the reader sees the box end. Clamped to
+ * the column so the channels stay free.
+ */
+/**
+ * The label as it fits the box the layout gave it.
+ *
+ * `boxWidth` CLAMPS to the column, so a title longer than the column gets a box
+ * narrower than its text — and an SVG `<text>` neither wraps nor clips, so the
+ * overflow ran straight across the routing channel and the neighbouring nodes,
+ * hiding the edges and labels the graph exists to show. Long issue titles are
+ * ordinary, so this was the common case rather than an edge one.
+ *
+ * IT MEASURES WITH THE SAME METRIC `boxWidth` SIZES WITH, which is the whole
+ * reason this belongs beside it rather than in the projection. Both read
+ * `--ig-char-width`, so the renderer's idea of what fits and the layout's cannot
+ * disagree — a separate estimate in the drawing code would be a second opinion
+ * about the same question, and the two would drift.
+ *
+ * THE ELLIPSIS IS THIS PACKAGE'S OWN TREATMENT, not a new convention: the rail's
+ * HTML rows already resolve an over-long title with `text-overflow: ellipsis`,
+ * so a canvas label that simply stopped mid-word would make the two surfaces
+ * disagree about what a truncated title looks like.
+ *
+ * NOTHING IS LOST TO A READER — the full title stays in the node's accessible
+ * name and its `<title>`, so this shortens what is DRAWN and never what is
+ * available.
+ */
+export declare function fitLabel(theme: Theme, label: string, width: number): string;
+/** Lay a document out. Pure: coordinates depend only on the document and the theme. */
+export declare function layoutGraph(document: NormalizedDocument, theme: Theme): GraphLayout;
+export interface EdgeGeometry {
+    /** The SVG path. Always a quadratic through one of the free channels. */
+    readonly d: string;
+    readonly start: Point;
+    readonly end: Point;
+    /** Radians. Orients the terminal marker along the path's own tangent. */
+    readonly endAngle: number;
+}
+/**
+ * The geometry for one edge, derived entirely from the two boxes' bounds.
+ *
+ * Returns `null` when either end has no box — which `normalizeDocument` has
+ * already made impossible for a kept edge, so a `null` here means a caller
+ * built a layout from a different document than the edge came from. Refusing is
+ * better than drawing at coordinates nobody computed.
+ */
+export declare function edgeGeometry(layout: GraphLayout, edge: ViewerEdge): EdgeGeometry | null;
+/** The box enclosing a together unit's members, padded clear of their bounds. */
+export declare function enclosureBounds(layout: GraphLayout, members: readonly string[], theme: Theme): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAe,KAAK,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAO7C,CAAC;AAEH,mCAAmC;AACnC,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEhD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAC7D,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAMD;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAS3E;AA8DD,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,QAAQ,EAAE,kBAAkB,EAAE,KAAK,EAAE,KAAK,GAAG,WAAW,CA8EnF;AAED,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC;IACpB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AA2CD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,UAAU,GACf,YAAY,GAAG,IAAI,CAyBrB;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,KAAK,GACX;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAWhE"}