@amandaghassaei/flat-svg/src/types-public.ts

A TypeScript library for converting nested SVGs into a flat list of elements, paths, or segments and applying style-based filters.

import {
	SVG_STYLE_DISPLAY,
	SVG_STYLE_FILL,
	SVG_STYLE_FILL_OPACITY,
	SVG_STYLE_OPACITY,
	SVG_STYLE_STROKE_COLOR,
	SVG_STYLE_STROKE_LINECAP,
	SVG_STYLE_STROKE_LINEJOIN,
	SVG_STYLE_STROKE_MITERLIMIT,
	SVG_STYLE_STROKE_OPACITY,
	SVG_STYLE_STROKE_WIDTH,
	SVG_STYLE_VISIBILITY,
	SVG_STYLE_COLOR,
	SVG_STYLE_STROKE_DASH_ARRAY,
} from './constants-private';
import {
	SVG_LINE,
	SVG_RECT,
	SVG_POLYLINE,
	SVG_POLYGON,
	SVG_CIRCLE,
	SVG_ELLIPSE,
	SVG_PATH,
	FLAT_SEGMENT_ARC,
	FLAT_SEGMENT_BEZIER,
	FLAT_SEGMENT_LINE,
	FLAT_SVG_STRAY_VERTEX_MOVETO_ONLY,
	FLAT_SVG_STRAY_VERTEX_POLYLINE_SINGLE_POINT,
	FLAT_SVG_STRAY_VERTEX_POLYGON_SINGLE_POINT,
} from './constants-public';
import { TextNode } from 'svg-parser';
import { Colord } from 'colord';

/**
 * SVG length units recognized by flat-svg.
 */
export type FlatSVGUnit = 'in' | 'cm' | 'mm' | 'px' | 'pt' | 'em' | 'ex' | 'pc';

/**
 * 2D [x, y] tuple. Treated as immutable — segments may share endpoints by
 * reference; copy via `[p[0], p[1]]` if you need to mutate.
 */
export type FlatSVGPoint = readonly [number, number];

/**
 * Histogram of fill or stroke colors. `none` counts elements with explicit
 * 'none' OR no attribute. `colors` keys are hex (`#RRGGBB`) for valid values,
 * raw string for unparseable. Alpha is not represented — colors with different
 * opacities collapse into the same hex bucket.
 */
export interface FlatSVGColorHistogram {
	readonly none: number,
	readonly colors: Readonly<{ [color: string]: number }>,
}

/**
 * 2D affine transform — SVG `matrix(a b c d e f)`, equivalent to the matrix
 * `[[a c e][b d f][0 0 1]]` applied to a column vector `[x y 1]`. Identity
 * is `{ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 }`.
 */
export interface FlatSVGTransform {
	a: number,
	b: number,
	c: number,
	d: number,
	e: number,
	f: number,
}

/**
 * Inheritable SVG/CSS style properties resolved during the cascade. Note that
 * `clip-path` / `mask` / `filter` are NOT here — they don't inherit; they're
 * surfaced as chains on `FlatElementBase`.
 */
export interface FlatSVGStyle {
	[SVG_STYLE_STROKE_WIDTH]?: number,
	[SVG_STYLE_STROKE_COLOR]?: string,
	[SVG_STYLE_STROKE_OPACITY]?: number,
	[SVG_STYLE_STROKE_LINECAP]?: string,
	[SVG_STYLE_STROKE_LINEJOIN]?: string,
	[SVG_STYLE_STROKE_MITERLIMIT]?: number,
	[SVG_STYLE_FILL]?: string,
	[SVG_STYLE_FILL_OPACITY]?: number,
	[SVG_STYLE_OPACITY]?: number,
	[SVG_STYLE_COLOR]?: string,
	[SVG_STYLE_STROKE_DASH_ARRAY]?: number | string,
	[SVG_STYLE_DISPLAY]?: string,
	[SVG_STYLE_VISIBILITY]?: string,
}

/** SVG attributes shared by every shape: style properties + `id` + `class`. */
export interface SVGBaseProperties extends FlatSVGStyle {
	id?: string,
	class?: string,
}

export interface SVGLineProperties extends SVGBaseProperties {
	x1: number,
	y1: number,
	x2: number,
	y2: number,
}
export interface SVGRectProperties extends SVGBaseProperties {
	x: number,
	y: number,
	width: number,
	height: number,
}
export interface SVGPolylineProperties extends SVGBaseProperties {
	points: string,
}
export interface SVGPolygonProperties extends SVGBaseProperties {
	points: string,
}
export interface SVGCircleProperties extends SVGBaseProperties {
	r: number,
	cx: number,
	cy: number,
}
export interface SVGEllipseProperties extends SVGBaseProperties {
	rx: number,
	ry: number,
	cx: number,
	cy: number,
}
export interface SVGPathProperties extends SVGBaseProperties {
	d: string,
}

/**
 * Catch-all attribute bag for any SVG element at parse time — superset of
 * `FlatSVGStyle` plus every geometry attribute. `clip-path`/`mask`/`filter`
 * appear here because they reach the parse tree, but they surface to consumers
 * as chains on `FlatElementBase` (not via this bag); `style` is expanded into
 * individual style properties during flattening.
 */
export interface SVGElementProperties extends FlatSVGStyle {
	viewBox?: string,
	id?: string,
	class?: string,
	x1?: number,
	y1?: number,
	x2?: number,
	y2?: number,
	x?: string,
	y?: string,
	width?: string,
	height?: string,
	points?: string,
	d?: string,
	cx?: number,
	cy?: number,
	rx?: number,
	ry?: number,
	r?: number,
	transform?: string,
	'clip-path'?: string,
	mask?: string,
	filter?: string,
	style?: string,
}

/** svg-parser's `ElementNode`, narrowed to exclude string children. */
export type SVGParserElementNode = {
    type: 'element';
    tagName?: string | undefined;
    properties?: SVGElementProperties;
    children: Array<SVGParserNode>;
    value?: string | undefined;
    metadata?: string | undefined;
}

/** A node in svg-parser's parse tree — text or element. */
export type SVGParserNode = TextNode | SVGParserElementNode;

/**
 * A flattened SVG element. IMPORTANT: `properties` coordinates (x/y/cx/cy/
 * points/...) are in source coordinates — ancestor transforms are NOT applied.
 * `transform` exposes the composed ancestor matrix for callers who want to
 * apply it themselves. For viewBox coordinates, use FlatSVG.paths (transform
 * baked into `properties.d`) or FlatSVG.segments (baked into p1/p2).
 */
export interface FlatElementBase {
	/**
	 * Ancestor-composed transform matrix (ancestor-first × self). Per SVG spec
	 * `transform` doesn't inherit as a property — each ancestor's matrix
	 * multiplies through; flat-svg collapses the composition onto each leaf.
	 * Immutable; siblings sharing an ancestor may share this matrix by reference.
	 */
	readonly transform?: Readonly<FlatSVGTransform>,
	/**
	 * `clip-path` attribute values from outermost ancestor to self (e.g.
	 * `"url(#mask1)"`). Per SVG spec clip-path doesn't inherit — every link in
	 * the chain clips the result below it, so all entries apply simultaneously.
	 * Immutable; siblings may share this array by reference.
	 */
	readonly clipPaths?: ReadonlyArray<string>,
	/** `mask` chain — same semantics as clipPaths. */
	readonly masks?: ReadonlyArray<string>,
	/** `filter` chain — same semantics as clipPaths. */
	readonly filters?: ReadonlyArray<string>,
	/**
	 * Space-joined chain of ancestor `<g>` ids, outermost first. Excludes this
	 * element's own id (on `properties.id`). flat-svg-internal lineage metadata
	 * — not a real SVG attribute. Resolve from a path/segment via
	 * sourceElementIndex.
	 */
	readonly ancestorIds?: string,
	/**
	 * Space-joined chain of ancestor `<g>` classes, outermost first. Excludes
	 * this element's own class. Multiple classes per ancestor concatenate; per-
	 * ancestor grouping is not preserved. Same rationale as ancestorIds.
	 */
	readonly ancestorClasses?: string,
}

export interface FlatLineElement extends FlatElementBase {
	readonly tagName: typeof SVG_LINE,
	readonly properties: Readonly<SVGLineProperties>,
}

export interface FlatRectElement extends FlatElementBase {
	readonly tagName: typeof SVG_RECT,
	readonly properties: Readonly<SVGRectProperties>,
}

export interface FlatPolylineElement extends FlatElementBase {
	readonly tagName: typeof SVG_POLYLINE,
	readonly properties: Readonly<SVGPolylineProperties>,
}

export interface FlatPolygonElement extends FlatElementBase {
	readonly tagName: typeof SVG_POLYGON,
	readonly properties: Readonly<SVGPolygonProperties>,
}

export interface FlatCircleElement extends FlatElementBase {
	readonly tagName: typeof SVG_CIRCLE,
	readonly properties: Readonly<SVGCircleProperties>,
}

export interface FlatEllipseElement extends FlatElementBase {
	readonly tagName: typeof SVG_ELLIPSE,
	readonly properties: Readonly<SVGEllipseProperties>,
}

export interface FlatPathElement extends FlatElementBase {
	readonly tagName: typeof SVG_PATH,
	readonly properties: Readonly<SVGPathProperties>,
}

/** Flattened SVG geometry element. Discriminated union — narrow by `tagName`. */
export type FlatElement =
	FlatLineElement | FlatRectElement | FlatPolylineElement | FlatPolygonElement |
	FlatCircleElement | FlatEllipseElement | FlatPathElement;

/**
 * SVG element whose tagName flat-svg can't convert to paths/segments — e.g.
 * `<use>`, `<text>`, `<image>`, `<foreignObject>`, nested `<svg>`, unknown
 * tags. Same `FlatElementBase` shape as `FlatElement` (transform / clip-path
 * chains, ancestor lineage), but `tagName` is open-ended and `properties`
 * carries only the inherited cascade styles — the element's own SVG attributes
 * (e.g. `<text>` x/y, `<use>` href) are NOT collected here.
 */
export interface FlatUnsupportedElement extends FlatElementBase {
	readonly tagName: string,
	readonly properties: Readonly<FlatSVGStyle>,
}


/**
 * Flattened SVG element re-encoded as a `<path>` — output of path conversion.
 * Distinct from `FlatPathElement`, which is the source-element shape when the
 * input SVG had a `<path>`. `properties.d` is in viewBox coordinates.
 */
export type FlatPath = {
    readonly properties: Readonly<SVGPathProperties>;
    /** Index of the source element in FlatSVG.elements. */
    readonly sourceElementIndex: number;
}

/** Straight line from p1 to p2. */
export type FlatLineSegment = {
	readonly type: typeof FLAT_SEGMENT_LINE,
	readonly p1: FlatSVGPoint,
	readonly p2: FlatSVGPoint,
    readonly properties: Readonly<SVGBaseProperties>;
    /** Index of the source element in FlatSVG.elements. */
    readonly sourceElementIndex: number;
}
/**
 * Quadratic (`controlPoints.length === 1`) or cubic (`controlPoints.length === 2`)
 * Bézier from p1 to p2. For cubic, `controlPoints[0]` is the control near p1
 * and `controlPoints[1]` is the control near p2 (matching SVG `C` argument order).
 */
export type FlatBezierSegment = {
	readonly type: typeof FLAT_SEGMENT_BEZIER,
	readonly p1: FlatSVGPoint,
	readonly p2: FlatSVGPoint,
	readonly controlPoints: ReadonlyArray<FlatSVGPoint>,
    readonly properties: Readonly<SVGBaseProperties>;
    /** Index of the source element in FlatSVG.elements. */
    readonly sourceElementIndex: number;
}
/**
 * Elliptical arc from p1 to p2 — semantics match the SVG path `A` command,
 * `xAxisRotation` in degrees. Only emitted when `FlatSVG` was constructed
 * with `preserveArcs: true`; otherwise arcs are approximated as cubic beziers.
 */
export type FlatArcSegment = {
	readonly type: typeof FLAT_SEGMENT_ARC,
	readonly p1: FlatSVGPoint,
	readonly p2: FlatSVGPoint,
	readonly rx: number,
	readonly ry: number,
	readonly xAxisRotation: number,
	readonly largeArcFlag: boolean,
	readonly sweepFlag: boolean,
    readonly properties: Readonly<SVGBaseProperties>;
    /** Index of the source element in FlatSVG.elements. */
    readonly sourceElementIndex: number;
}

/** Flattened path segment. Discriminated union — narrow by `type`. */
export type FlatSegment = FlatLineSegment | FlatBezierSegment | FlatArcSegment;

/**
 * Spec passed to `FlatSVG.filter*ByStyle`. Matches against the element's
 * resolved value for `key`; `tolerance` is permissible distance — Delta
 * E2000 in [0, 1] for colors, raw numeric distance for numbers.
 *
 * `value` type must match `key`:
 * - color keys (`stroke`, `fill`, `color`): `string | Colord`
 * - numeric keys (`stroke-width`, `opacity`, `stroke-opacity`, ...): `number`
 * - `stroke-dasharray`: `number[] | string`
 *
 * Mismatched pairs throw at runtime.
 */
export type FlatSVGStyleFilter = {
	key: string;
	value: string | number | number[] | Colord;
	tolerance?: number;
};

/** Which kind of degenerate SVG element produced a stray vertex. */
export type FlatSVGStrayVertexCause =
	| typeof FLAT_SVG_STRAY_VERTEX_MOVETO_ONLY
	| typeof FLAT_SVG_STRAY_VERTEX_POLYLINE_SINGLE_POINT
	| typeof FLAT_SVG_STRAY_VERTEX_POLYGON_SINGLE_POINT;

/**
 * Isolated point from a source element that collapsed (circle r=0, single-
 * point polyline, moveto-only path, ...). Position in viewBox coordinates.
 */
export interface FlatSVGStrayVertex {
	readonly position: FlatSVGPoint,
	readonly cause: FlatSVGStrayVertexCause,
	/** Index of the source element in FlatSVG.elements. */
	readonly sourceElementIndex: number,
}

/**
 * A <defs> child definition (clipPath, mask, gradient, symbol, marker, pattern,
 * ...). flat-svg records what's defined but does NOT resolve url(#id)
 * references — cross-reference by id yourself.
 */
export interface FlatSVGDef {
	/** Element tag, e.g. 'clipPath', 'mask', 'linearGradient', 'symbol'. */
	readonly tagName: string,
	/** id attribute, if present — what url(#id) references resolve against. */
	readonly id?: string,
}

/**
 * Aggregated diagnostic output from FlatSVG.analyze().
 * All fields are JSON-serializable — no class instances.
 */
export interface FlatSVGAnalysis {
	readonly viewBox: readonly [number, number, number, number],
	readonly units: FlatSVGUnit,
	readonly counts: Readonly<{
		elements: number,
		paths: number,
		segments: number,
		zeroLengthSegments: number,
		strayVertices: number,
		defs: number,
		unsupportedElements: number,
	}>,
	readonly strokeColors: FlatSVGColorHistogram,
	readonly fillColors: FlatSVGColorHistogram,
	readonly containsClipPaths: boolean,
	/** Indices into FlatSVG.segments of zero-length segments. */
	readonly zeroLengthSegmentIndices: ReadonlyArray<number>,
	readonly strayVertices: ReadonlyArray<FlatSVGStrayVertex>,
	/** Elements whose tagName flat-svg can't convert to paths/segments. */
	readonly unsupportedElements: ReadonlyArray<FlatUnsupportedElement>,
	readonly warnings: ReadonlyArray<string>,
}