@graphty/graph-io 0.3.42 → 0.3.44

package/dist/src/styles/io/block.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The `graphty.styles` block: the rules of a graph's styles written into a file so that importing the file back into
+ * graphty rebuilds the same rules. The block is JSON; the per-element values its rules read are written beside it as
+ * element attributes named `graphty.style.<target>.<key>` (or, in a format with no per-element attributes, inside
+ * the block). A block is file input like any other: it is size-limited, validated member by member, never keyed into
+ * a plain object, and a block that fails any check is ignored with a reason code, never thrown.
+ */
+import type { GraphSnapshot } from "@graphty/graph-format";
+import type { LossNote } from "../../types.js";
+import type { ExtractedStyles, FileStyles, StyleBlockIgnoredReason, StyleColumn, StyleFingerprint, StyleNote, StyleRule, StyleTarget, StyleTool } from "../types.js";
+/**
+ * The name of the block in every format: a graph attribute, a key, an aspect or an archive entry.
+ * @category Styles
+ */
+export declare const STYLE_BLOCK_NAME = "graphty.styles";
+/**
+ * The longest block graph-io reads, in characters; a longer one is ignored (`TOO_LARGE`).
+ * @category Styles
+ */
+export declare const MAX_STYLE_BLOCK_LENGTH: number;
+/**
+ * The name of the element attribute holding one style column: `graphty.style.<target>.<key>`.
+ * @param target - nodes or edges
+ * @param key - the style column's key (`class`, `member.3`, `exceptions.fill`)
+ * @returns the attribute name
+ * @category Styles
+ */
+export declare function styleTag(target: StyleTarget, key: string): string;
+/**
+ * The content of a `graphty.styles` block.
+ * @category Styles
+ */
+export interface StyleBlock {
+    /** The block's version: 1. */
+    readonly version: 1;
+    /** The format, dialect and tool the styles were described with. */
+    readonly source: FileStyles["source"];
+    /** The unit of every length. */
+    readonly units: FileStyles["units"];
+    /** The graph's own style. */
+    readonly graph: FileStyles["graph"];
+    /** The rules, bottom to top, with their `ext` members. */
+    readonly rules: readonly StyleRule[];
+    /** The keys of the style columns the rules read, per target. */
+    readonly columns: {
+        /** Node style column keys. */
+        readonly node: readonly string[];
+        /** Edge style column keys. */
+        readonly edge: readonly string[];
+    };
+    /**
+     * The text of each node's id, in the order the inline style columns list the nodes, so they are matched to a graph
+     * read back in another order; absent without inline columns.
+     */
+    readonly order?: readonly string[];
+    /**
+     * The keys of the style columns that hold booleans, per target, so a format that has no booleans (GML writes 0
+     * and 1) reads them back as booleans; absent when none does.
+     */
+    readonly booleans?: {
+        /** Node style column keys. */
+        readonly node: readonly string[];
+        /** Edge style column keys. */
+        readonly edge: readonly string[];
+    };
+    /** The style columns themselves, for a format with no per-element attributes; absent otherwise. */
+    readonly values?: {
+        /** Node style columns by key. */
+        readonly node: ReadonlyMap<string, StyleColumn>;
+        /** Edge style columns by key. */
+        readonly edge: ReadonlyMap<string, StyleColumn>;
+    };
+    /**
+     * A hash of the values of every data column the rules read, per target, by the column's name when the block was
+     * written; absent in a block written without its graph. A column the file reads back under another name (a
+     * format writes its label column as its own `label`) is found again by its values.
+     */
+    readonly data?: {
+        /** Node data column hashes by column name. */
+        readonly node: ReadonlyMap<string, string>;
+        /** Edge data column hashes by column name. */
+        readonly edge: ReadonlyMap<string, string>;
+    };
+    /** The graph the block describes. */
+    readonly fingerprint: StyleFingerprint;
+}
+/**
+ * Options of `writeStyleBlock()`.
+ * @category Styles
+ */
+export interface WriteStyleBlockOptions {
+    /** Write the style columns inside the block, for a format with no per-element attributes; defaults to false. */
+    readonly inlineColumns?: boolean;
+    /**
+     * The graph being written: with it, the block records a hash of each data column the rules read, so the rules
+     * still find their columns in a file that renames them.
+     */
+    readonly snapshot?: GraphSnapshot;
+}
+/**
+ * Writes a graph's styles as a `graphty.styles` block. Notes are not written. The output is deterministic: the same
+ * styles always give the same text. A backslash, newline or tab inside a string is written as a `\u` escape, so a
+ * format that decodes `\n` and `\t` in attribute values (Cytoscape's convention) reads the block back unchanged.
+ * @param extracted - the styles
+ * @param options - whether to write the style columns inside the block
+ * @returns the block's JSON text
+ * @category Styles
+ */
+export declare function writeStyleBlock(extracted: ExtractedStyles, options?: WriteStyleBlockOptions): string;
+/**
+ * The loss when graph-io would ignore a block it has just written: one longer than `MAX_STYLE_BLOCK_LENGTH`, or one
+ * past another limit the reader enforces (too many rules, a name too long). The format's own styles are still
+ * written, so importing the file back infers the rules again from them.
+ * @param text - the block's text, as `writeStyleBlock()` wrote it
+ * @param rules - how many rules the block holds
+ * @param check - "size" to check only the length: a block rewritten with its columns inline, whose rules were
+ * checked already
+ * @returns one `W_STYLE_RULES_NOT_KEPT` note naming the reason, or none when the block reads back
+ * @category Styles
+ */
+export declare function styleBlockLosses(text: string, rules: number, check?: "all" | "size"): LossNote[];
+/**
+ * What `parseStyleBlock()` found: a valid block, or the reason it is ignored.
+ * @category Styles
+ */
+export type ParsedStyleBlock = {
+    /** The block is valid and describes this graph. */
+    readonly ok: true;
+    /** The block. */
+    readonly block: StyleBlock;
+} | {
+    /** The block is ignored. */
+    readonly ok: false;
+    /** Why. */
+    readonly reason: StyleBlockIgnoredReason;
+};
+/**
+ * Reads a `graphty.styles` block as untrusted input. It never throws: a block that is not text, too large, not JSON,
+ * of another version, nested too deep, holding a key that reaches a prototype (`__proto__`), shaped wrongly or
+ * written for a different graph is ignored with the reason.
+ * @param text - the block's text, as the file holds it
+ * @param fingerprint - the graph being imported (`styleFingerprint(snapshot)`)
+ * @returns the block, or why it is ignored
+ * @category Styles
+ */
+export declare function parseStyleBlock(text: unknown, fingerprint: StyleFingerprint): ParsedStyleBlock;
+/**
+ * The styles a valid block describes, read against the graph it was imported into. The block's rules are the
+ * file's declared rules and read the tagged per-element values. Where the file's own native values are given, they
+ * are the truth: an element whose value differs from what the rules give (another program edited it) is written
+ * into one exceptions rule on top, so the styles stay exact and, with no edit, are the block's rules unchanged.
+ * @param block - a block `parseStyleBlock()` accepted for this graph
+ * @param snapshot - the graph
+ * @param format - the format the file was read as
+ * @param truth - the native per-element values per target and property, when the format has any
+ * @param notes - notes to carry (the reader's own)
+ * @param tool - the program whose drawing the native values describe: where the rules give an element no value and
+ * the file holds only what that program draws for an unset property (a font written with "plain" style), it is not
+ * an edit
+ * @param opacityInColor - whether the format writes a fill's and an edge's opacity as its color's alpha: a native
+ * color with no native opacity then states opacity 1 where the rules give a translucent one
+ * @returns the styles, or null when a style column the rules read is missing from the file
+ * @category Styles
+ */
+export declare function blockStyles(block: StyleBlock, snapshot: GraphSnapshot, format: string, truth?: Partial<Record<StyleTarget, Partial<Record<string, StyleColumn>>>>, notes?: readonly StyleNote[], tool?: StyleTool | null, opacityInColor?: boolean): ExtractedStyles | null;
+//# sourceMappingURL=block.d.ts.map

package/dist/src/styles/io/block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../../../../src/styles/io/block.ts"],"names":[],"mappings":"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"}