@breadstone-infrastructure/nx-tasks 0.0.256 → 0.0.258

package/src/executors/icon-collection-builder/svg.ts

@@ -0,0 +1,406 @@
+// #region Imports
+
+import svgpath from 'svgpath';
+import { parse, type INode } from 'svgson';
+
+// #endregion
+
+// #region Types
+
+/**
+ * Represents a parsed SVG node structure
+ * @public
+ */
+export type SvgNode = INode;
+
+// #endregion
+
+// #region Constants
+
+/**
+ * Magic number for circle approximation with cubic Bezier curves
+ * Derived from 4/3 * tan(PI/8) ≈ 0.5522847498
+ * This constant provides the optimal control point offset for approximating
+ * a circular arc with a cubic Bezier curve
+ * @internal
+ */
+const KAPPA = 0.5522847498;
+
+// #endregion
+
+// #region Helper Functions
+
+/**
+ * Safely parses a numeric attribute from an SVG node
+ * @param node - The SVG node
+ * @param attr - The attribute name to parse
+ * @param defaultValue - Default value if attribute is missing or invalid
+ * @returns The parsed numeric value or default
+ * @internal
+ */
+function parseAttr(node: SvgNode, attr: string, defaultValue = 0): number {
+    const value = node.attributes?.[attr];
+    if (value === undefined || value === null) {
+        return defaultValue;
+    }
+    const parsed = parseFloat(value as string);
+    return isNaN(parsed) ? defaultValue : parsed;
+}
+
+/**
+ * Converts a circle element to a path data string
+ * Uses 4 cubic Bezier curves to approximate the circle
+ * @param cx - Center X coordinate
+ * @param cy - Center Y coordinate
+ * @param r - Radius
+ * @returns SVG path data string
+ * @internal
+ */
+function circleToPath(cx: number, cy: number, r: number): string {
+    const offsetX = r * KAPPA;
+    const offsetY = r * KAPPA;
+
+    return [
+        `M ${cx - r} ${cy}`,
+        `C ${cx - r} ${cy - offsetY} ${cx - offsetX} ${cy - r} ${cx} ${cy - r}`,
+        `C ${cx + offsetX} ${cy - r} ${cx + r} ${cy - offsetY} ${cx + r} ${cy}`,
+        `C ${cx + r} ${cy + offsetY} ${cx + offsetX} ${cy + r} ${cx} ${cy + r}`,
+        `C ${cx - offsetX} ${cy + r} ${cx - r} ${cy + offsetY} ${cx - r} ${cy}`,
+        'Z'
+    ].join(' ');
+}
+
+/**
+ * Converts an ellipse element to a path data string
+ * Uses 4 cubic Bezier curves to approximate the ellipse
+ * @param cx - Center X coordinate
+ * @param cy - Center Y coordinate
+ * @param rx - Horizontal radius
+ * @param ry - Vertical radius
+ * @returns SVG path data string
+ * @internal
+ */
+function ellipseToPath(cx: number, cy: number, rx: number, ry: number): string {
+    const offsetX = rx * KAPPA;
+    const offsetY = ry * KAPPA;
+
+    return [
+        `M ${cx - rx} ${cy}`,
+        `C ${cx - rx} ${cy - offsetY} ${cx - offsetX} ${cy - ry} ${cx} ${cy - ry}`,
+        `C ${cx + offsetX} ${cy - ry} ${cx + rx} ${cy - offsetY} ${cx + rx} ${cy}`,
+        `C ${cx + rx} ${cy + offsetY} ${cx + offsetX} ${cy + ry} ${cx} ${cy + ry}`,
+        `C ${cx - offsetX} ${cy + ry} ${cx - rx} ${cy + offsetY} ${cx - rx} ${cy}`,
+        'Z'
+    ].join(' ');
+}
+
+/**
+ * Converts a rect element to a path data string
+ * Handles rounded corners via rx/ry parameters
+ * @param x - Top-left X coordinate
+ * @param y - Top-left Y coordinate
+ * @param width - Rectangle width
+ * @param height - Rectangle height
+ * @param rx - Horizontal corner radius (optional)
+ * @param ry - Vertical corner radius (optional)
+ * @returns SVG path data string
+ * @internal
+ */
+function rectToPath(x: number, y: number, width: number, height: number, rx = 0, ry = 0): string {
+    if (rx === 0 && ry === 0) {
+        return `M ${x} ${y} H ${x + width} V ${y + height} H ${x} Z`;
+    }
+
+    return [
+        `M ${x + rx} ${y}`,
+        `H ${x + width - rx}`,
+        `A ${rx} ${ry} 0 0 1 ${x + width} ${y + ry}`,
+        `V ${y + height - ry}`,
+        `A ${rx} ${ry} 0 0 1 ${x + width - rx} ${y + height}`,
+        `H ${x + rx}`,
+        `A ${rx} ${ry} 0 0 1 ${x} ${y + height - ry}`,
+        `V ${y + ry}`,
+        `A ${rx} ${ry} 0 0 1 ${x + rx} ${y}`,
+        'Z'
+    ].join(' ');
+}
+
+/**
+ * Converts a line element to a path data string
+ * @param x1 - Start X coordinate
+ * @param y1 - Start Y coordinate
+ * @param x2 - End X coordinate
+ * @param y2 - End Y coordinate
+ * @returns SVG path data string
+ * @internal
+ */
+function lineToPath(x1: number, y1: number, x2: number, y2: number): string {
+    return `M ${x1} ${y1} L ${x2} ${y2}`;
+}
+
+/**
+ * Converts a polyline element to a path data string
+ * @param points - Space or comma-separated list of point coordinates
+ * @returns SVG path data string
+ * @internal
+ */
+function polylineToPath(points: string): string {
+    const coords = points.trim().split(/[\s,]+/).map(Number);
+    if (coords.length < 2) {
+        return '';
+    }
+
+    const pathParts = [`M ${coords[0]} ${coords[1]}`];
+    for (let i = 2; i < coords.length; i += 2) {
+        pathParts.push(`L ${coords[i]} ${coords[i + 1]}`);
+    }
+
+    return pathParts.join(' ');
+}
+
+/**
+ * Converts a polygon element to a path data string
+ * Same as polyline but closes the path with Z
+ * @param points - Space or comma-separated list of point coordinates
+ * @returns SVG path data string
+ * @internal
+ */
+function polygonToPath(points: string): string {
+    const polylinePath = polylineToPath(points);
+    return polylinePath ? `${polylinePath} Z` : '';
+}
+
+/**
+ * Converts various SVG shape elements to path data
+ * @param node - The SVG node to convert
+ * @returns Path data string or empty string if conversion not possible
+ * @internal
+ */
+function elementToPath(node: SvgNode): string {
+    const { name, attributes } = node;
+
+    switch (name) {
+        case 'path':
+            return (attributes?.d as string) || '';
+
+        case 'circle': {
+            const cx = parseAttr(node, 'cx');
+            const cy = parseAttr(node, 'cy');
+            const r = parseAttr(node, 'r');
+            return circleToPath(cx, cy, r);
+        }
+
+        case 'ellipse': {
+            const cx = parseAttr(node, 'cx');
+            const cy = parseAttr(node, 'cy');
+            const rx = parseAttr(node, 'rx');
+            const ry = parseAttr(node, 'ry');
+            return ellipseToPath(cx, cy, rx, ry);
+        }
+
+        case 'rect': {
+            const x = parseAttr(node, 'x');
+            const y = parseAttr(node, 'y');
+            const width = parseAttr(node, 'width');
+            const height = parseAttr(node, 'height');
+            const rx = parseAttr(node, 'rx');
+            const ry = parseAttr(node, 'ry');
+            return rectToPath(x, y, width, height, rx, ry);
+        }
+
+        case 'line': {
+            const x1 = parseAttr(node, 'x1');
+            const y1 = parseAttr(node, 'y1');
+            const x2 = parseAttr(node, 'x2');
+            const y2 = parseAttr(node, 'y2');
+            return lineToPath(x1, y1, x2, y2);
+        }
+
+        case 'polyline': {
+            const points = (attributes?.points as string) || '';
+            return polylineToPath(points);
+        }
+
+        case 'polygon': {
+            const points = (attributes?.points as string) || '';
+            return polygonToPath(points);
+        }
+
+        default:
+            return '';
+    }
+}
+
+// #endregion
+
+// #region Public API
+
+/**
+ * Converts an SVG string to a single combined path data string
+ * Traverses the SVG AST and converts all shape elements to paths
+ * @param svgContent - The SVG content as a string
+ * @returns Combined path data string
+ * @public
+ */
+export async function svgToSinglePath(svgContent: string): Promise<string> {
+    const svg = await parse(svgContent);
+    const paths: string[] = [];
+
+    function traverse(node: SvgNode): void {
+        const pathData = elementToPath(node);
+        if (pathData) {
+            paths.push(pathData);
+        }
+
+        if (node.children && Array.isArray(node.children)) {
+            for (const child of node.children) {
+                traverse(child);
+            }
+        }
+    }
+
+    traverse(svg);
+    return paths.join(' ');
+}
+
+/**
+ * Result of a normalized SVG conversion
+ * @public
+ */
+export interface INormalizedSvgResult {
+    pathData: string;
+    sourceViewBox: string;
+    wasNormalized: boolean;
+}
+
+/**
+ * Parsed viewBox components
+ * @internal
+ */
+interface IViewBox {
+    minX: number;
+    minY: number;
+    width: number;
+    height: number;
+}
+
+/**
+ * Parses a viewBox attribute string into its components
+ * @param viewBox - The viewBox attribute value
+ * @returns Parsed viewBox or null if invalid
+ * @internal
+ */
+function parseViewBox(viewBox: string): IViewBox | null {
+    const parts = viewBox.split(/[\s,]+/).map(Number);
+
+    if (parts.length !== 4 || parts.some(isNaN)) {
+        return null;
+    }
+
+    return {
+        minX: parts[0],
+        minY: parts[1],
+        width: parts[2],
+        height: parts[3]
+    };
+}
+
+/**
+ * Computes a transform to map source viewBox coordinates to the target size.
+ * Scales uniformly and centers the content.
+ * @param source - Source viewBox
+ * @param targetSize - Target viewBox dimension (e.g. 24 for 0 0 24 24)
+ * @returns Scale, translate-x, and translate-y values
+ * @internal
+ */
+function computeNormalizationTransform(source: IViewBox, targetSize: number): { scale: number; tx: number; ty: number } {
+    const scale = Math.min(targetSize / source.width, targetSize / source.height);
+    const tx = (targetSize - source.width * scale) / 2 - source.minX * scale;
+    const ty = (targetSize - source.height * scale) / 2 - source.minY * scale;
+
+    return { scale, tx, ty };
+}
+
+/**
+ * Applies translate + scale transform to SVG path data
+ * @param pathData - Raw SVG path data string
+ * @param transform - Transform parameters
+ * @returns Transformed path data string
+ * @internal
+ */
+function transformPathData(pathData: string, transform: { scale: number; tx: number; ty: number }): string {
+    return svgpath(pathData)
+        .translate(transform.tx, transform.ty)
+        .scale(transform.scale)
+        .abs()
+        .round(3)
+        .toString();
+}
+
+/**
+ * Converts an SVG string to a single normalized path data string.
+ * If the SVG viewBox differs from the target size, all path coordinates
+ * are scaled and centered to fit the target viewBox.
+ * @param svgContent - The SVG content as a string
+ * @param targetSize - Target viewBox dimension (e.g. 24 for 0 0 24 24)
+ * @returns Normalized result with path data and metadata
+ * @public
+ */
+export async function svgToNormalizedSinglePath(svgContent: string, targetSize: number): Promise<INormalizedSvgResult> {
+    const svg = await parse(svgContent);
+
+    const viewBoxAttr = svg.attributes?.viewBox;
+    const sourceViewBox = viewBoxAttr ? parseViewBox(viewBoxAttr) : null;
+
+    const paths: string[] = [];
+
+    function traverse(node: SvgNode): void {
+        const pathData = elementToPath(node);
+        if (pathData) {
+            paths.push(pathData);
+        }
+
+        if (node.children && Array.isArray(node.children)) {
+            for (const child of node.children) {
+                traverse(child);
+            }
+        }
+    }
+
+    traverse(svg);
+
+    const combinedPath = paths.join(' ');
+    const sourceViewBoxStr = viewBoxAttr ?? 'none';
+
+    if (!sourceViewBox) {
+        return {
+            pathData: combinedPath,
+            sourceViewBox: sourceViewBoxStr,
+            wasNormalized: false
+        };
+    }
+
+    const isAlreadyTarget = sourceViewBox.minX === 0
+        && sourceViewBox.minY === 0
+        && sourceViewBox.width === targetSize
+        && sourceViewBox.height === targetSize;
+
+    if (isAlreadyTarget) {
+        return {
+            pathData: combinedPath,
+            sourceViewBox: sourceViewBoxStr,
+            wasNormalized: false
+        };
+    }
+
+    const transform = computeNormalizationTransform(sourceViewBox, targetSize);
+    const normalizedPath = transformPathData(combinedPath, transform);
+
+    return {
+        pathData: normalizedPath,
+        sourceViewBox: sourceViewBoxStr,
+        wasNormalized: true
+    };
+}
+
+// #endregion

package/src/executors/icon-collection-downloader/executor.options.ts

@@ -0,0 +1,10 @@
+// #region Imports
+
+import type { IconCollectionDownloaderTask } from './executor.task';
+
+// #endregion
+
+/**
+ * @private
+ */
+export type IconCollectionDownloaderExecutorOptions = Omit<IconCollectionDownloaderTask.IIconCollectionDownloaderTaskOptions, 'cwd' | 'packageJson' | 'tsConfigJson'>;