Add support for multiple/nested element content

f2face · Nov 8, 2023 · 1692d27 · 1692d27
1 parent 3e82ee5
commit 1692d27
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 13 deletions.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "svg-artisan",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Simple SVG builder for Node.",
   "main": "./dist/index.js",
   "files": [

diff --git a/src/elements/BaseElement.ts b/src/elements/BaseElement.ts
@@ -12,6 +12,10 @@ export abstract class BaseElement implements SvgElement {
         this.content = this.normalizeContent(content);
     }
 
+    /**
+     * Normalizes content to a `string` for SVG element rendering.
+     * @param content The content to normalize.
+     */
     private normalizeContent(content?: ElementContent): string {
         if (typeof content === 'string') return content;
         if (typeof content === 'number') return String(content);
@@ -23,14 +27,19 @@ export abstract class BaseElement implements SvgElement {
         return '';
     }
 
+    /**
+     * Adds an attribute and its value to the attributes map.
+     * @param attribute The name of the attribute.
+     * @param value The value of the attribute.
+     */
     private addAttributeToMap(attribute: string, value: AttributeValue) {
         if (!this.attributesMap) this.attributesMap = new Map();
         this.attributesMap.set(attribute, this.escapeAttributeValue(value));
     }
 
     /**
-     * Escapes attribute value.
-     * @param value
+     * Escapes an attribute value to ensure proper rendering.
+     * @param value The attribute value to escape.
      */
     private escapeAttributeValue(value: AttributeValue): AttributeValue {
         if (typeof value === 'string') {
@@ -40,8 +49,8 @@ export abstract class BaseElement implements SvgElement {
     }
 
     /**
-     * Replaces double quote with single quote.
-     * @param value
+     * Replaces double quotes with single quotes
+     * @param value The value that may contain double quotes.
      */
     protected replaceDoubleQuote(value: string | number) {
         if (typeof value === 'string') {
@@ -50,20 +59,37 @@ export abstract class BaseElement implements SvgElement {
         return value;
     }
 
-    public getAttributes() {
+    /**
+     * Returns the attributes of this SVG element as a `Map`.
+     */
+    public getAttributes(): Map<string, AttributeValue> | undefined {
         return this.attributesMap;
     }
 
-    public getContent() {
+    /**
+     * Returns the content of this SVG element as a `string`.
+     */
+    public getContent(): string {
         return this.content;
     }
 
+    /**
+     * Sets an attribute on this element.
+     * @param attribute The name of the attribute.
+     * @param value The value of the attribute.
+     */
     public setAttribute(attribute: string, value: AttributeValue): this;
+
+    /**
+     * Sets attributes on this element.
+     * @param attributes An object containing multiple attribute-value pairs.
+     */
     public setAttribute(attributes: ElementAttributes): this;
+
     public setAttribute(
         attr: string | ElementAttributes,
         value?: AttributeValue
-    ) {
+    ): this {
         if (typeof attr === 'string' && typeof value !== 'undefined') {
             this.addAttributeToMap(attr, value);
         } else {
@@ -75,7 +101,13 @@ export abstract class BaseElement implements SvgElement {
         return this;
     }
 
-    public appendChild(...childElement: Array<SvgElement | string>) {
+    /**
+     * Appends child element(s) inside this element.
+     * @param childElement Child element(s) to append inside this element.
+     */
+    public appendChild(
+        ...childElement: Array<SvgElement | Array<SvgElement> | string>
+    ): this {
         for (const element of childElement) {
             this.content += this.normalizeContent(element);
         }
@@ -86,7 +118,7 @@ export abstract class BaseElement implements SvgElement {
      * Sets inline style for the element.
      * @param style An object representing the inline style properties and their values.
      */
-    public style(style: { [property: string]: string | number }) {
+    public style(style: { [property: string]: string | number }): this {
         const value = Object.entries(style)
             .map(([prop, value]) => {
                 const newProp = this.replaceDoubleQuote(prop);
@@ -98,6 +130,10 @@ export abstract class BaseElement implements SvgElement {
         return this;
     }
 
+    /**
+     * Renders this element as a `string` representation of an SVG element.
+     * @returns A `string` representing the SVG element.
+     */
     public render(): string {
         let attrs = '';
         if (this.attributesMap) {
@@ -121,7 +157,11 @@ export abstract class BaseElement implements SvgElement {
         return element;
     }
 
-    public buffer() {
+    /**
+     * Renders this element then converts it to a `Buffer`.
+     * @returns A `Buffer` containing the SVG element as binary data.
+     */
+    public buffer(): Buffer {
         return Buffer.from(this.render());
     }
 }
diff --git a/src/types.ts b/src/types.ts
@@ -1,5 +1,9 @@
 import type { SvgElement } from './interfaces';
 
 export type AttributeValue = string | number | null;
-export type ElementAttributes = { [key: string]: AttributeValue };
-export type ElementContent = string | number | SvgElement | Array<SvgElement>;
+export type ElementAttributes = { [attribute: string]: AttributeValue };
+export type ElementContent =
+    | string
+    | number
+    | SvgElement
+    | Array<string | number | SvgElement>;