kist 0.0.0 → 0.1.30

package/ts/actions/StyleProcessingAction/StyleProcessingAction.ts

@@ -0,0 +1,142 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { promises as fs } from "fs";
+import path from "path";
+import postcss from "postcss";
+import * as sass from "sass";
+
+import { Action } from "../../core/pipeline/Action.js";
+import { ActionOptionsType } from "../../types/ActionOptionsType.js";
+
+// Assuming the PostCSS configurations are available at the given paths
+import postcssConfigCompressed from "./postcss.config.compressed.js";
+import postcssConfigExpanded from "./postcss.config.expanded.js";
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * StyleProcessingAction is a step action responsible for processing styles,
+ * including compiling SCSS and applying PostCSS transformations. It supports
+ * expanded and compressed output styles based on the provided configuration.
+ */
+export class StyleProcessingAction extends Action {
+    // Parameters
+    // ========================================================================
+
+    // Constructor
+    // ========================================================================
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Executes the style processing action.
+     * @param options - The options specific to style processing, including
+     * input/output file paths and style format.
+     * @returns A Promise that resolves when the styles are processed
+     * successfully, or rejects with an error if the action fails.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const inputFile = options.inputFile as string;
+        const outputFile = options.outputFile as string;
+        const styleOption = options.styleOption as "expanded" | "compressed";
+
+        if (!inputFile || !outputFile || !styleOption) {
+            throw new Error(
+                "Missing required options: inputFile, outputFile, or styleOption.",
+            );
+        }
+
+        this.logInfo(
+            `Processing styles from ${inputFile} to ${outputFile} with ${styleOption} style.`,
+        );
+
+        try {
+            // Ensure the output directory exists
+            const outputDir = path.dirname(outputFile);
+            await this.ensureDirectoryExists(outputDir);
+
+            // Compile SCSS to CSS
+            const result = await sass.compileAsync(inputFile, {
+                style: styleOption,
+                importers: [new sass.NodePackageImporter()],
+            });
+
+            // Process the compiled CSS with PostCSS
+            const processedCss = await this.processPostCSS(
+                result.css,
+                styleOption,
+            );
+
+            // Write the processed CSS to a file
+            await fs.writeFile(outputFile, processedCss, "utf-8");
+
+            this.logInfo(
+                `Styles processed successfully from ${inputFile} to ${outputFile}.`,
+            );
+        } catch (error) {
+            this.logError(
+                `Error processing styles from ${inputFile}: ${error}`,
+            );
+            throw error;
+        }
+    }
+
+    /**
+     * Processes the given CSS with PostCSS based on the provided style option.
+     * @param css - The CSS string to process.
+     * @param styleOption - The style option, either "expanded" or "compressed".
+     * @returns Processed CSS string.
+     */
+    private async processPostCSS(
+        css: string,
+        styleOption: "expanded" | "compressed",
+    ): Promise<string> {
+        const config =
+            styleOption === "expanded"
+                ? postcssConfigExpanded
+                : postcssConfigCompressed;
+        const result = await postcss(config.plugins).process(css, {
+            from: undefined,
+            map: { inline: false },
+        });
+        return result.css;
+    }
+
+    /**
+     * Ensures that the given directory exists, creating it if it does not.
+     * @param dirPath - The path of the directory to check and create.
+     */
+    private async ensureDirectoryExists(dirPath: string): Promise<void> {
+        try {
+            await fs.mkdir(dirPath, { recursive: true });
+        } catch (error) {
+            if (error instanceof Error) {
+                const nodeError = error as NodeJS.ErrnoException;
+                if (nodeError.code !== "EEXIST") {
+                    throw nodeError;
+                }
+            } else {
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Processes SCSS files into CSS, applying PostCSS transformations for expanded or compressed outputs.";
+    }
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+// export default StyleProcessingAction;

package/ts/actions/StyleProcessingAction/index.ts

@@ -0,0 +1,11 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { StyleProcessingAction } from "./StyleProcessingAction";
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export { StyleProcessingAction };

package/ts/actions/StyleProcessingAction/postcss.config.compressed.ts

@@ -0,0 +1,31 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import autoprefixer from "autoprefixer"; // Handles CSS vendor prefixing automatically
+import cssnano from "cssnano"; // A PostCSS plugin for CSS minimization
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Configuration object for PostCSS that includes plugins for optimization and compression
+ * of CSS. This setup is typically used for production builds where minimized CSS is preferred
+ * to reduce file size and improve loading times.
+ */
+const postcssConfigCompressed = {
+    plugins: [
+        autoprefixer, // Automatically adds vendor prefixes to CSS rules
+        cssnano({
+            // Compresses CSS output
+            preset: "default", // Uses the default settings for compression
+        }),
+    ],
+};
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export default postcssConfigCompressed;

package/ts/actions/StyleProcessingAction/postcss.config.expanded.ts

@@ -0,0 +1,47 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import autoprefixer from "autoprefixer"; // Automatically adds vendor prefixes to CSS rules
+import cssnano from "cssnano";
+// import postcssSimpleVars from 'postcss-simple-vars'; // Plugin to handle CSS variables
+// import postcssNested from 'postcss-nested'; // Plugin to allow nesting of CSS rules
+// import postcssImport from 'postcss-import'; // Plugin to inline import CSS files into a single CSS
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Configuration object for PostCSS that focuses on generating expanded, readable CSS
+ * for development environments. Includes plugins that enhance CSS handling like nesting,
+ * variable support, and import inlining, alongside autoprefixer for browser compatibility.
+ */
+const postcssConfigExpanded = {
+    plugins: [
+        autoprefixer,
+        // Include other plugins suited for the expanded output
+    ],
+    // plugins: [
+    //     postcssImport(),  // Allows importing of other CSS files within a CSS file
+    //     autoprefixer(),   // Adds vendor prefixes to CSS, using data from Can I Use
+    //     postcssSimpleVars(), // Enables the use of Sass-like variables in CSS
+    //     postcssNested(),  // Process nested rules, which is similar to how Sass handles nesting
+    //     // cssnano({
+    //     //     preset: 'default', // Optionally include for light compression or reformatting
+    //     // }),
+    // ]
+};
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export default postcssConfigExpanded;
+
+/**
+ * Note: This configuration is intended for development use where extended readability
+ * and ease of debugging are critical. The cssnano plugin is commented out by default
+ * to keep the output CSS as clean and readable as possible; it can be enabled for
+ * environments that require slightly more optimized output without full minification.
+ */

package/ts/actions/SvgPackagerAction/SvgPackagerAction.ts

@@ -0,0 +1,187 @@
+// ============================================================================
+// Imports
+// ============================================================================
+
+import * as fs from "fs/promises";
+import * as glob from "glob";
+import * as path from "path";
+import SVGO, { loadConfig } from "svgo";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * SvgPackagerAction is responsible for optimizing and packaging SVG files.
+ * It reads SVG files from a specified directory, optimizes them using SVGO,
+ * and then outputs them as TypeScript files and JSON indexes.
+ */
+export class SvgPackagerAction extends Action {
+    // Methods
+    // ========================================================================
+
+    /**
+     * Executes the SVG processing action.
+     * @param options - The options specifying input and output directories.
+     * @returns A Promise that resolves when the action completes successfully.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const {
+            svgoConfigPath = "./config/svgo.config.js",
+            inputDirectory = "src/icons",
+            outputDirectory = "dist/icons",
+            tsOutputDirectory = "dist/ts",
+            jsonOutputDirectory = "dist",
+        } = options;
+
+        this.logInfo(`Processing SVG files from ${inputDirectory}...`);
+        const iconNames: string[] = [];
+
+        try {
+            const svgFiles = glob.sync(`${inputDirectory}/**/*.svg`);
+
+            for (const file of svgFiles) {
+                const iconName = this.sanitizeFileName(
+                    path.basename(file, ".svg"),
+                );
+                iconNames.push(iconName);
+
+                const svgContent = await this.readSvgFile(file);
+                const optimizedSvg = await this.optimizeSvg(
+                    svgoConfigPath,
+                    svgContent,
+                );
+
+                await this.writeFiles(
+                    iconName,
+                    optimizedSvg,
+                    outputDirectory,
+                    tsOutputDirectory,
+                );
+            }
+
+            await this.writeIconsJson(iconNames, jsonOutputDirectory);
+            this.logInfo(
+                `Successfully processed ${svgFiles.length} SVG files.`,
+            );
+        } catch (error) {
+            this.logError("Error processing SVG files.", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Reads the content of an SVG file.
+     * @param filePath The path to the SVG file.
+     * @returns The content of the SVG file.
+     */
+    private async readSvgFile(filePath: string): Promise<string> {
+        return fs.readFile(filePath, "utf8");
+    }
+
+    /**
+     * Sanitizes a file name to be a valid TypeScript identifier.
+     * @param fileName The original file name.
+     * @returns A sanitized version of the file name.
+     */
+    private sanitizeFileName(fileName: string): string {
+        return fileName.replace(/[^a-zA-Z0-9_]/g, "_");
+    }
+
+    /**
+     * Optimizes SVG content using SVGO.
+     * @param svgoConfigPath Path to the SVGO configuration file.
+     * @param svgContent The raw SVG content.
+     * @returns The optimized SVG content.
+     */
+    private async optimizeSvg(
+        svgoConfigPath: string,
+        svgContent: string,
+    ): Promise<string> {
+        const config = await loadConfig(svgoConfigPath);
+        const result = await SVGO.optimize(svgContent, { ...config });
+        return result.data.trim();
+    }
+
+    /**
+     * Writes optimized SVG content to files (SVG & TypeScript).
+     * @param iconName The name of the icon.
+     * @param svgContent The optimized SVG content.
+     * @param outputDirectory The directory for SVG output.
+     * @param tsOutputDirectory The directory for TypeScript output.
+     */
+    private async writeFiles(
+        iconName: string,
+        svgContent: string,
+        outputDirectory: string,
+        tsOutputDirectory: string,
+    ): Promise<void> {
+        await this.writeSvgFile(iconName, svgContent, outputDirectory);
+        await this.writeTypeScriptFile(
+            iconName,
+            svgContent,
+            tsOutputDirectory,
+        );
+    }
+
+    /**
+     * Writes the optimized SVG content to an output file.
+     * @param iconName The name of the icon.
+     * @param svgContent The SVG content to be written.
+     * @param outputDirectory The directory to output the SVG file.
+     */
+    private async writeSvgFile(
+        iconName: string,
+        svgContent: string,
+        outputDirectory: string,
+    ): Promise<void> {
+        const outputPath = path.join(outputDirectory, `${iconName}.svg`);
+        await fs.writeFile(outputPath, svgContent);
+    }
+
+    /**
+     * Creates a TypeScript file from the optimized SVG content.
+     * @param iconName The name of the icon.
+     * @param svgContent The optimized SVG content.
+     * @param tsOutputDirectory The directory for TypeScript output.
+     */
+    private async writeTypeScriptFile(
+        iconName: string,
+        svgContent: string,
+        tsOutputDirectory: string,
+    ): Promise<void> {
+        const tsContent = `export const icon_${iconName} = \`${svgContent}\`;\n`;
+        const outputPath = path.join(tsOutputDirectory, `${iconName}.ts`);
+        await fs.writeFile(outputPath, tsContent);
+    }
+
+    /**
+     * Writes a JSON file containing the names of processed icons.
+     * @param iconNames An array of processed icon names.
+     * @param jsonOutputDirectory The directory to output the JSON file.
+     */
+    private async writeIconsJson(
+        iconNames: string[],
+        jsonOutputDirectory: string,
+    ): Promise<void> {
+        const jsonContent = JSON.stringify(iconNames, null, 2);
+        const outputPath = path.join(jsonOutputDirectory, "icons.json");
+        await fs.writeFile(outputPath, jsonContent);
+    }
+
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Optimizes and packages SVG files into multiple formats (SVG, TypeScript, JSON).";
+    }
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export default SvgPackagerAction;

package/ts/actions/SvgPackagerAction/index.ts

@@ -0,0 +1,11 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { SvgPackagerAction } from "./SvgPackagerAction";
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export { SvgPackagerAction };

package/ts/actions/SvgReaderAction/SvgReaderAction.ts

@@ -0,0 +1,77 @@
+// ============================================================================
+// Imports
+// ============================================================================
+
+import { promises as fs } from "fs";
+import path from "path";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * SvgReaderAction is responsible for reading SVG file contents and
+ * making them available for further processing in the pipeline.
+ */
+export class SvgReaderAction extends Action {
+    private svgContent: string = "";
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Executes the SVG reading action.
+     * @param options - The options specifying the SVG file path.
+     * @returns A Promise that resolves when the SVG file is successfully read.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const { filePath } = options;
+
+        if (!filePath) {
+            throw new Error("Missing required option: 'filePath'.");
+        }
+
+        this.logInfo(`Reading SVG file: ${filePath}`);
+
+        try {
+            this.svgContent = await this.readSvg(filePath);
+            this.logInfo(`Successfully read SVG file: ${filePath}`);
+        } catch (error) {
+            this.logError(`Error reading SVG file: ${filePath}`, error);
+            throw error;
+        }
+    }
+
+    /**
+     * Reads the content of an SVG file asynchronously.
+     * @param filePath The path to the SVG file.
+     * @returns A promise that resolves to the SVG file content.
+     */
+    private async readSvg(filePath: string): Promise<string> {
+        return fs.readFile(path.resolve(filePath), "utf-8");
+    }
+
+    /**
+     * Retrieves the last read SVG content.
+     * @returns The last read SVG content.
+     */
+    getSvgContent(): string {
+        return this.svgContent;
+    }
+
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Reads an SVG file and stores its content for further processing.";
+    }
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export default SvgReaderAction;

package/ts/actions/SvgReaderAction/index.ts

@@ -0,0 +1,11 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { SvgReaderAction } from "./SvgReaderAction";
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export { SvgReaderAction };

package/ts/actions/SvgSpriteAction/SvgSpriteAction.ts

@@ -0,0 +1,127 @@
+// ============================================================================
+// Imports
+// ============================================================================
+
+import fs from "fs";
+import path from "path";
+import svgSprite from "svg-sprite";
+import { Action } from "../../core/pipeline/Action";
+import { ActionOptionsType } from "../../types/ActionOptionsType";
+import svgspriteConfig from "./svgsprite.config.js";
+
+// ============================================================================
+// Classes
+// ============================================================================
+
+/**
+ * SvgSpriteAction compiles multiple SVG files into a single sprite sheet,
+ * making it more efficient to manage and use SVG assets in web applications.
+ */
+export class SvgSpriteAction extends Action {
+    // Parameters
+    // ========================================================================
+
+    private config: svgSprite.Config;
+
+    /**
+     * Default configuration for SVG sprite generation.
+     */
+    private static defaultConfig: svgSprite.Config = svgspriteConfig;
+
+    // Constructor
+    // ========================================================================
+
+    /**
+     * Constructs an instance with merged default and custom configurations.
+     * @param {svgSprite.Config} customConfig - Optional custom configuration
+     * for svg-sprite.
+     */
+    constructor(customConfig: svgSprite.Config = {}) {
+        super();
+        this.config = { ...SvgSpriteAction.defaultConfig, ...customConfig };
+    }
+
+    // Methods
+    // ========================================================================
+
+    /**
+     * Executes the SVG sprite generation process.
+     * @param options - Options including source directory and output directory.
+     */
+    async execute(options: ActionOptionsType): Promise<void> {
+        const { sourceDir, outputDir } = options;
+
+        if (!sourceDir || !outputDir) {
+            throw new Error(
+                "Both 'sourceDir' and 'outputDir' must be specified.",
+            );
+        }
+
+        this.logInfo(`Generating SVG sprite from: ${sourceDir}`);
+
+        try {
+            await this.generateSprite(sourceDir, outputDir);
+            this.logInfo(`SVG sprite successfully generated in: ${outputDir}`);
+        } catch (error) {
+            this.logError("Error generating SVG sprite:", error);
+            throw error;
+        }
+    }
+
+    /**
+     * Generates an SVG sprite from all SVG files in the specified directory.
+     * @param sourceDir - Directory containing source SVG files.
+     * @param outputDir - Directory where the generated sprite will be saved.
+     */
+    private async generateSprite(
+        sourceDir: string,
+        outputDir: string,
+    ): Promise<void> {
+        const files = fs.readdirSync(sourceDir);
+        const sprite = new svgSprite(this.config);
+
+        for (const file of files) {
+            if (path.extname(file) === ".svg") {
+                const svgPath = path.resolve(sourceDir, file);
+                const content = fs.readFileSync(svgPath, "utf8");
+                sprite.add(svgPath, null, content);
+            }
+        }
+
+        sprite.compile((error, result) => {
+            if (error) {
+                throw error;
+            }
+
+            for (const mode in result) {
+                for (const resource in result[mode]) {
+                    const outputPath = path.resolve(
+                        outputDir,
+                        result[mode][resource].path,
+                    );
+                    fs.mkdirSync(path.dirname(outputPath), {
+                        recursive: true,
+                    });
+                    fs.writeFileSync(
+                        outputPath,
+                        result[mode][resource].contents,
+                    );
+                }
+            }
+        });
+    }
+
+    /**
+     * Provides a description of the action.
+     * @returns A string description of the action.
+     */
+    describe(): string {
+        return "Generates an SVG sprite from a directory of SVG files.";
+    }
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export default SvgSpriteAction;

package/ts/actions/SvgSpriteAction/index.ts

@@ -0,0 +1,11 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { SvgSpriteAction } from "./SvgSpriteAction";
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export { SvgSpriteAction };