@graphty/graph-io 0.3.42 → 0.3.44

package/src/styles/canon/text.ts

@@ -0,0 +1,221 @@
+/**
+ * Canonical text: the text a tool draws. Text is copied whatever its length and never matched with a pattern that
+ * can backtrack; every pass here is linear in the text's length and spends one operation per character.
+ */
+
+import { STYLE_ISSUE } from "../codes.js";
+import { type CanonSite, noteAt, spendAt } from "./site.js";
+
+/**
+ * A text value: a string as it is, a finite number or a boolean as its text. Anything else is null with a
+ * `W_STYLE_BAD_VALUE` note; an absent value is null without one.
+ * @param raw - the file's value
+ * @param site - where it was read
+ * @returns the text, or null
+ * @category Styles
+ */
+export function canonText(raw: unknown, site: CanonSite): string | null {
+    spendAt(site, 1);
+    if (raw === null || raw === undefined) {
+        return null;
+    }
+    if (typeof raw === "string") {
+        spendAt(site, raw.length);
+        return raw;
+    }
+    if ((typeof raw === "number" && Number.isFinite(raw)) || typeof raw === "boolean") {
+        return String(raw);
+    }
+    noteAt(site, STYLE_ISSUE.BAD_VALUE, typeof raw === "number" ? String(raw) : typeof raw);
+    return null;
+}
+
+/**
+ * The names Graphviz substitutes for `\N`, `\G`, `\E`, `\T` and `\H` in a label; an absent name leaves its escape
+ * as written.
+ * @category Styles
+ */
+export interface DotEscapeNames {
+    /** The node's name, for `\N`. */
+    readonly node?: string;
+    /** The graph's name, for `\G`. */
+    readonly graph?: string;
+    /** The edge's name (`a->b` or `a--b`), for `\E`. */
+    readonly edge?: string;
+    /** The edge's tail node, for `\T`. */
+    readonly tail?: string;
+    /** The edge's head node, for `\H`. */
+    readonly head?: string;
+}
+
+/**
+ * The text a DOT label draws, in Graphviz's two passes: first `\N`, `\G`, `\E`, `\T` and `\H` are replaced by the
+ * names and every other backslash pair is kept; then `\n`, `\l` and `\r` end a line (a final one adds no empty line)
+ * and any other escaped character stands for itself. So a node name holding `\n` breaks the line.
+ * @param text - the label as the file gives it
+ * @param names - the names to substitute
+ * @param site - where it was read, for the budget
+ * @returns the label's text
+ * @category Styles
+ */
+export function dotLabelText(text: string, names: DotEscapeNames, site?: CanonSite): string {
+    if (site !== undefined) {
+        spendAt(site, text.length);
+    }
+    const subs: Readonly<Record<string, string | undefined>> = {
+        N: names.node,
+        G: names.graph,
+        E: names.edge,
+        T: names.tail,
+        H: names.head,
+    };
+    const first = replaceEscapes(text, (e) => (Object.hasOwn(subs, e) ? subs[e] : undefined) ?? `\\${e}`);
+    const out = replaceEscapes(first, (e) => (e === "n" || e === "l" || e === "r" ? "\n" : e));
+    return out.endsWith("\n") ? out.slice(0, -1) : out;
+}
+
+/**
+ * A text with every backslash escape (a backslash and the character after it) replaced; a backslash at the end stays.
+ * @param text - the text
+ * @param replace - the replacement of an escape, given the escaped character
+ * @returns the text
+ */
+function replaceEscapes(text: string, replace: (escaped: string) => string): string {
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (c === "\\" && i + 1 < text.length) {
+            out += replace(text[i + 1]);
+            i += 2;
+        } else {
+            out += c;
+            i++;
+        }
+    }
+    return out;
+}
+
+/** HTML entity names an HTML-like label may use. */
+const ENTITIES: ReadonlyMap<string, string> = new Map([
+    ["amp", "&"],
+    ["lt", "<"],
+    ["gt", ">"],
+    ["quot", '"'],
+    ["apos", "'"],
+    ["nbsp", " "],
+]);
+
+/**
+ * Decodes one entity body (`amp`, `#38`, `#x26`).
+ * @param body - the text between `&` and `;`
+ * @returns the character, or undefined when it is not an entity
+ */
+function entity(body: string): string | undefined {
+    if (body.startsWith("#")) {
+        const hex = body[1] === "x" || body[1] === "X";
+        const digits = body.slice(hex ? 2 : 1);
+        if (digits === "" || digits.length > 7 || !(hex ? /^[0-9a-f]+$/i : /^\d+$/).test(digits)) {
+            return undefined;
+        }
+        const cp = Number.parseInt(digits, hex ? 16 : 10);
+        return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : undefined;
+    }
+    return ENTITIES.get(body.toLowerCase());
+}
+
+/**
+ * The text an HTML-like label shows: tags dropped, `<br/>` as a line break, entities decoded, outer blanks trimmed.
+ * Notes `W_STYLE_HTML_LABEL` at the site, since the markup is lost.
+ * @param html - the label, with or without its outer `<` and `>`
+ * @param site - where it was read
+ * @returns the label's text
+ * @category Styles
+ */
+export function htmlLabelText(html: string, site: CanonSite): string {
+    spendAt(site, html.length);
+    noteAt(site, STYLE_ISSUE.HTML_LABEL, html);
+    const body = html.startsWith("<") && html.endsWith(">") ? html.slice(1, -1) : html;
+    let out = "";
+    let i = 0;
+    while (i < body.length) {
+        const c = body[i];
+        if (c === "<") {
+            const close = body.indexOf(">", i + 1);
+            if (close < 0) {
+                break;
+            }
+            if (/^<br\b/i.test(body.slice(i, i + 4))) {
+                out += "\n";
+            }
+            i = close + 1;
+        } else if (c === "&") {
+            const [text, next] = entityAt(body, i);
+            out += text;
+            i = next;
+        } else {
+            out += c;
+            i++;
+        }
+    }
+    return out.trim();
+}
+
+/**
+ * The entity starting at an `&`, decoded; an `&` that starts none is itself. An entity is at most 9 characters, so
+ * the search for its ";" stays short and the pass stays linear.
+ * @param body - the text
+ * @param i - the offset of the `&`
+ * @returns the text it stands for and the offset after it
+ */
+function entityAt(body: string, i: number): [string, number] {
+    const near = body.slice(i + 1, i + 10).indexOf(";");
+    const semi = near < 0 ? -1 : i + 1 + near;
+    const decoded = semi > i ? entity(body.slice(i + 1, semi)) : undefined;
+    return decoded === undefined ? ["&", i + 1] : [decoded, semi + 1];
+}
+
+/**
+ * The text a Graphviz record label shows: its fields (`<f0> left|<f1> mid|{a|b}`) without their port names, trimmed,
+ * empty ones left out, joined with " | ". Notes `W_STYLE_RECORD_LABEL` at the site, since the boxes are lost.
+ * @param label - the record label
+ * @param site - where it was read
+ * @returns the fields' text
+ * @category Styles
+ */
+export function recordLabelText(label: string, site: CanonSite): string {
+    spendAt(site, label.length);
+    noteAt(site, STYLE_ISSUE.RECORD_LABEL, label);
+    const fields: string[] = [];
+    let field = "";
+    const flush = (): void => {
+        const t = field.trim();
+        if (t !== "") {
+            fields.push(t);
+        }
+        field = "";
+    };
+    let i = 0;
+    while (i < label.length) {
+        const c = label[i];
+        if (c === "\\" && i + 1 < label.length && "|{}<> ".includes(label[i + 1])) {
+            field += label[i + 1];
+            i += 2;
+            continue;
+        }
+        if (c === "<") {
+            // a port name runs to its ">"
+            const close = label.indexOf(">", i + 1);
+            i = close < 0 ? label.length : close + 1;
+            continue;
+        }
+        if (c === "|" || c === "{" || c === "}") {
+            flush();
+        } else {
+            field += c;
+        }
+        i++;
+    }
+    flush();
+    return fields.join(" | ");
+}

package/src/styles/codes.ts

@@ -0,0 +1,104 @@
+/**
+ * The codes of every style condition graph-io reports: the notes attached to a file's styles (`W_STYLE_*`), the
+ * import and export report codes about styles as a whole (`W_STYLES_*`), and the one error (`E_STYLES_MISMATCH`).
+ */
+
+import { STYLES_NOT_IMPORTED_CODE } from "../common/codes.js";
+
+/**
+ * Every style code by name. A key is the code without its `E_` / `W_` and `STYLE_` / `STYLES_` prefixes. Every style
+ * condition is a warning except `MISMATCH`; none counts toward an import's `errorLimit`.
+ * @category Styles
+ */
+export const STYLE_ISSUE = Object.freeze({
+    // ------------------------------------------------ reading values
+    /** A value longer than 256 characters was not parsed. */
+    VALUE_TOO_LONG: "W_STYLE_VALUE_TOO_LONG",
+    /** A value does not parse in the file's dialect (an unknown color name, a non-number, a negative length). */
+    BAD_VALUE: "W_STYLE_BAD_VALUE",
+    /** An enumeration value the vocabulary has no name for; kept as `other:<value>`. */
+    UNKNOWN_VALUE: "W_STYLE_UNKNOWN_VALUE",
+    /** A color's alpha was dropped because the property has no opacity to carry it. */
+    ALPHA_DROPPED: "W_STYLE_ALPHA_DROPPED",
+    /** A list of colors where one color is expected; the tool draws it its own way and the first is not taken. */
+    COLOR_LIST: "W_STYLE_COLOR_LIST",
+    /** A gradient fill; its first color is kept. */
+    GRADIENT: "W_STYLE_GRADIENT",
+    /** A node the tool draws unfilled although the file gives it a fill color. */
+    UNFILLED: "W_STYLE_UNFILLED",
+    /** A node fill the file marks as transparent or absent. */
+    NO_FILL: "W_STYLE_NO_FILL",
+    /** An edge stroke the file marks as absent. */
+    NO_STROKE: "W_STYLE_NO_STROKE",
+    /** The tool grows a node to fit its label, so the stated size is a minimum. */
+    SIZE_MINIMUM: "W_STYLE_SIZE_MINIMUM",
+    /** An HTML-like label: its text is kept and its markup dropped. */
+    HTML_LABEL: "W_STYLE_HTML_LABEL",
+    /** A record label: its fields are joined with " | ". */
+    RECORD_LABEL: "W_STYLE_RECORD_LABEL",
+    /** An element carries more than one label; the first is kept. */
+    EXTRA_LABELS: "W_STYLE_EXTRA_LABELS",
+    /** A color that inherits from the edge's ends in a way the vocabulary cannot express. */
+    INHERIT_COLOR: "W_STYLE_INHERIT_COLOR",
+    /** A style property the vocabulary has no counterpart for was not carried. */
+    NOT_CARRIED: "W_STYLE_NOT_CARRIED",
+    // ------------------------------------------------ reading declared styles
+    /** A declared mapping that cannot be read. */
+    BAD_MAPPING: "W_STYLE_BAD_MAPPING",
+    /** A declared mapping reads a column the file does not have. */
+    MAPPING_COLUMN_MISSING: "W_STYLE_MAPPING_COLUMN_MISSING",
+    /** References between style records that are circular or too deep; the rest are read. */
+    REFERENCE_CYCLE: "W_STYLE_REFERENCE_CYCLE",
+    /** A style reference that names nothing in the file. */
+    UNRESOLVED: "W_STYLE_UNRESOLVED",
+    /** Style structures nested deeper than graph-io reads. */
+    NESTING: "W_STYLE_NESTING",
+    /** A style section that cannot be read at all. */
+    UNREADABLE: "W_STYLE_UNREADABLE",
+    /** A Cytoscape session without its visual styles; the tool's fallbacks apply. */
+    NO_VIZMAP: "W_STYLE_NO_VIZMAP",
+    /** The view names a visual style the file does not hold. */
+    VIEW_STYLE_MISSING: "W_STYLE_VIEW_STYLE_MISSING",
+    /** The file holds more visual styles than the one its view uses; the others are not read. */
+    OTHER_STYLES: "W_STYLE_OTHER_STYLES",
+    /** The file holds more views than one; only the first view's styles are read. */
+    OTHER_VIEWS: "W_STYLE_OTHER_VIEWS",
+    /** A selector the tool treats as invalid, which matches every element there. */
+    SELECTOR: "W_STYLE_SELECTOR",
+    /** A selector a short predicate cannot express; its members are marked on the elements instead. */
+    SELECTOR_AS_COLUMN: "W_STYLE_SELECTOR_AS_COLUMN",
+    /** A selector state that changes while the tool runs (selected, hovered), evaluated as at load. */
+    STATE_ASSUMED: "W_STYLE_STATE_ASSUMED",
+    // ------------------------------------------------ planning
+    /** A continuous mapping matches the file's values only within the tool's rounding. */
+    RAMP_ROUNDED: "W_STYLE_RAMP_ROUNDED",
+    /** Rules were folded into a copy to keep the number of rules per kind bounded. */
+    LAYER_CAP: "W_STYLE_LAYER_CAP",
+    /** The counted work budget ran out; the values not yet explained are copied per element. */
+    BUDGET: "W_STYLE_BUDGET",
+    // ------------------------------------------------ graphty's own block
+    /** A `graphty.styles` block was ignored, with a reason code; the file is read like any other. */
+    BLOCK_IGNORED: "W_STYLE_BLOCK_IGNORED",
+    // ------------------------------------------------ export
+    /** The format has no place for this property; it is not written. */
+    NOT_WRITTEN: "W_STYLE_NOT_WRITTEN",
+    /** Written as the nearest value the format allows. */
+    APPROXIMATED: "W_STYLE_APPROXIMATED",
+    /** Per-element values were written but not the rules; importing the file infers them again. */
+    RULES_NOT_KEPT: "W_STYLE_RULES_NOT_KEPT",
+    /** A style was written as its per-element values and lost its editable form, with a reason code. */
+    LAYER_FLATTENED: "W_STYLE_LAYER_FLATTENED",
+    // ------------------------------------------------ styles as a whole
+    /** The file holds styles that were not imported; import them with the `styles` option. */
+    NOT_IMPORTED: STYLES_NOT_IMPORTED_CODE,
+    /** The graph has styles that were not exported; export them with the `styles` option. */
+    NOT_EXPORTED: "W_STYLES_NOT_EXPORTED",
+    /** The styles were read from or built for a different graph; nothing is written. */
+    MISMATCH: "E_STYLES_MISMATCH",
+});
+
+/**
+ * Any style code.
+ * @category Styles
+ */
+export type StyleIssueCode = (typeof STYLE_ISSUE)[keyof typeof STYLE_ISSUE];