@mlightcad/common 1.1.1 → 1.1.3

package/dist/common.js

@@ -422,15 +422,34 @@ function b(n, e, t) {
   return Math.max(e, Math.min(t, n));
 }
 const O = class O {
+  /**
+   * Constructs a new AcCmColor instance.
+   * Initializes the color to "ByLayer" (index 256) and null RGB values.
+   */
   constructor() {
     this._colorIndex = 256, this._color = null, this._colorName = null;
   }
+  /**
+   * Gets the current color value.
+   * 
+   * @returns {number | null} The color value (RGB or index).
+   */
   get color() {
     return this._color;
   }
+  /**
+   * Sets the color value.
+   * 
+   * @param {number | null} value - The color value to set (RGB or index).
+   */
   set color(e) {
     e == null ? this._color = null : (this._color = Math.round(b(e, 0, 256 * 256 * 256 - 1)), this._colorIndex = this.getColorIndexByValue(this._color), this._colorName = this.getColorNameByValue(this._color));
   }
+  /**
+   * Gets the hexadecimal representation of the current color.
+   * 
+   * @returns {string} The hexadecimal color string (e.g., "0xFFFFFF").
+   */
   get hexColor() {
     if (this._color && this._color > 0 && this._color <= 16777215) {
       let e = this._color.toString(16).toUpperCase();
@@ -440,35 +459,73 @@ const O = class O {
     }
     return "";
   }
+  /**
+   * Gets the CSS RGB color string representation.
+   * 
+   * @returns {string} The CSS RGB color string (e.g., "rgb(255,255,255)").
+   */
   get cssColor() {
     return `rgb(${this.red},${this.green},${this.blue})`;
   }
+  /**
+   * Gets the red component of the current color.
+   * 
+   * @returns {number | null} The red component (0-255).
+   */
   get red() {
     return this.color ? this.color >> 16 & 255 : null;
   }
+  /**
+   * Gets the green component of the current color.
+   * 
+   * @returns {number | null} The green component (0-255).
+   */
   get green() {
     return this.color ? this.color >> 8 & 255 : null;
   }
+  /**
+   * Gets the blue component of the current color.
+   * 
+   * @returns {number | null} The blue component (0-255).
+   */
   get blue() {
     return this.color ? this.color & 255 : null;
   }
   /**
-   * AutoCAD color index value. The index value will be in the range 0 to 256. 0 and 256 are special values.
-   * If value less than 0 is set, 0 will be used. If value greater than 256 is set, 256 will be used.
+   * Gets the AutoCAD color index value. The index value will be in the range 0 to 256.
+   * 0 and 256 are special values.
+   * 
+   * @returns {number | null} The color index.
+   */
+  get colorIndex() {
+    return this._colorIndex;
+  }
+  /**
+   * Sets the AutoCAD color index value. If value less than 0 is set, 0 will be used. If value greater than
+   * 256 is set, 256 will be used.
    * - 0 indicates that the entity uses the color of the BlockReference that's displaying it. If the entity
    * is not displayed through a block reference (for example, it is directly owned by the model space
    * block table record) and its color is 0, then it will display as though its color were 7.
    * - 256 indicates that the entity uses the color specified in the layer table record it references.
+   * 
+   * @param {number | null} value - The color index to set (0-256).
    */
-  get colorIndex() {
-    return this._colorIndex;
-  }
   set colorIndex(e) {
     e == null ? this._colorIndex = null : (this._colorIndex = b(e, 0, 256), this._color = T[e], this._colorName = this.getColorNameByValue(this._color));
   }
+  /**
+   * Gets the name of the current color.
+   * 
+   * @returns {string | null} The color name.
+   */
   get colorName() {
     return this._colorName;
   }
+  /**
+   * Sets the color by name.
+   * 
+   * @param {string | null} value - The color name to set.
+   */
   set colorName(e) {
     if (e) {
       const t = I[e.toLowerCase()];
@@ -476,54 +533,140 @@ const O = class O {
     } else
       this._colorName = null;
   }
+  /**
+   * Checks if the color has a name.
+   * 
+   * @returns {boolean} True if the color has no name, false otherwise.
+   */
   get hasColorName() {
     return this._colorName == null;
   }
+  /**
+   * Checks if the color has an index.
+   * 
+   * @returns {boolean} True if the color has no index, false otherwise.
+   */
   get hasColorIndex() {
     return this._colorIndex == null;
   }
+  /**
+   * Checks if the color is set to "ByLayer".
+   * 
+   * @returns {boolean} True if the color is "ByLayer", false otherwise.
+   */
   get isByLayer() {
     return this.colorIndex == 256;
   }
+  /**
+   * Sets the color to "ByLayer".
+   * 
+   * @returns {AcCmColor} The current instance.
+   */
   setByLayer() {
     return this.colorIndex = 256, this;
   }
+  /**
+   * Checks if the color is set to "ByBlock".
+   * 
+   * @returns {boolean} True if the color is "ByBlock", false otherwise.
+   */
   get isByBlock() {
     return this.colorIndex == 0;
   }
+  /**
+   * Sets the color to "ByBlock".
+   * 
+   * @returns {AcCmColor} The current instance.
+   */
   setByBlock() {
     return this.colorIndex = 0, this;
   }
+  /**
+   * Sets the color using a scalar value (RGB).
+   * 
+   * @param {number} scalar - The scalar value (0-255).
+   * @returns {AcCmColor} The current instance.
+   */
   setScalar(e) {
     return this.setRGB(e, e, e), this;
   }
+  /**
+   * Sets the color using RGB values.
+   * 
+   * @param {number} r - The red component (0-255).
+   * @param {number} g - The green component (0-255).
+   * @param {number} b - The blue component (0-255).
+   * @returns {AcCmColor} The current instance.
+   */
   setRGB(e, t, r) {
     const o = Math.round(b(e, 0, 255)), i = Math.round(b(t, 0, 255)), l = Math.round(b(r, 0, 255));
     return this.color = (o << 16) + (i << 8) + l, this;
   }
+  /**
+   * Sets the color by name.
+   * 
+   * @param {string} style - The color name to set.
+   * @returns {AcCmColor} The current instance.
+   */
   setColorName(e) {
     const t = I[e.toLowerCase()];
     return t !== void 0 ? this.color = t : console.warn("Unknown color " + e), this;
   }
+  /**
+   * Clones the current AcCmColor instance.
+   * 
+   * @returns {AcCmColor} A new AcCmColor instance with the same color and index.
+   */
   clone() {
     const e = new O();
     return e.colorIndex = this.colorIndex, e.color = this.color, e._colorName = this._colorName, this;
   }
+  /**
+   * Copies the color from another AcCmColor instance.
+   * 
+   * @param {AcCmColor} color - The color to copy from.
+   * @returns {AcCmColor} The current instance.
+   */
   copy(e) {
     return this.colorIndex = e.colorIndex, this.color = e.color, this._colorName = e._colorName, this;
   }
+  /**
+   * Checks if two AcCmColor instances are equal.
+   * 
+   * @param {AcCmColor} c - The color to compare with.
+   * @returns {boolean} True if the colors and their indices are the same.
+   */
   equals(e) {
     return e.color == this.color && e.colorIndex == this.colorIndex && e._colorName == this._colorName;
   }
+  /**
+   * Returns a string representation of the color.
+   * 
+   * @returns {string} The color name or hexadecimal string.
+   */
   toString() {
     return this.isByLayer ? "ByLayer" : this.isByBlock ? "ByBlock" : this.colorName ? this.colorName : this.hexColor;
   }
+  /**
+   * Finds the color name associated with a given RGB value.
+   * 
+   * @private
+   * @param {number} target - The RGB value to find a name for.
+   * @returns {string | null} The color name if found, null otherwise.
+   */
   getColorNameByValue(e) {
     for (const [t, r] of Object.entries(I))
       if (r === e)
         return t;
     return null;
   }
+  /**
+   * Finds the AutoCAD color index associated with a given RGB value.
+   * 
+   * @private
+   * @param {number} target - The RGB value to find an index for.
+   * @returns {number | null} The color index if found, null otherwise.
+   */
   getColorIndexByValue(e) {
     const t = T.length - 1;
     for (let r = 1; r < t; ++r)
@@ -872,11 +1015,30 @@ class F {
     t && Z(r, t), this.attributes = r, this.changed = {};
   }
   /**
-   * For strongly-typed access to attributes, use the `get` method only privately in public getter properties.
+   * Gets the value of an attribute.
+   * 
+   * For strongly-typed access to attributes, use the `get` method privately in public getter properties.
+   * 
+   * @template A - The key type extending string keys of T.
+   * @param {A} key - The attribute key to retrieve.
+   * @returns {T[A] | undefined} The attribute value or undefined if not set.
+   * 
    * @example
+   * ```typescript
+   * // Get a single attribute value
+   * const name = obj.get('name')
+   * const visible = obj.get('visible')
+   * 
+   * // Check if attribute exists
+   * if (obj.get('name') !== undefined) {
+   *   console.log('Name is set')
+   * }
+   * 
+   * // For strongly-typed subclasses
    * get name(): string {
-   *    return super.get("name")
+   *   return super.get("name")
    * }
+   * ```
    */
   get(e) {
     return this.attributes[e];
@@ -1016,11 +1178,26 @@ class _ {
 }
 class se {
   /**
-   * Converts a byte count to a human-readable string using KB, MB, or GB.
+   * Converts a byte count to a human-readable string using appropriate size units.
+   * 
+   * Automatically selects the most appropriate unit (B, KB, MB, GB, TB) based on the size
+   * and formats the result with the specified number of decimal places.
    *
-   * @param bytes - The number of bytes.
-   * @param decimals - Number of decimal places to include (default is 2).
-   * @returns A formatted string with the appropriate unit.
+   * @param {number} bytes - The number of bytes to format.
+   * @param {number} [decimals=2] - Number of decimal places to include in the result.
+   * @returns {string} A formatted string with the appropriate unit.
+   * 
+   * @example
+   * ```typescript
+   * import { AcTrStringUtil } from './AcCmStringUtil'
+   * 
+   * // Format different byte sizes
+   * AcTrStringUtil.formatBytes(0)          // "0 B"
+   * AcTrStringUtil.formatBytes(1024)       // "1 KB"  
+   * AcTrStringUtil.formatBytes(1024 * 1024) // "1 MB"
+   * AcTrStringUtil.formatBytes(1536, 1)    // "1.5 KB"
+   * AcTrStringUtil.formatBytes(2048000, 0) // "2 MB"
+   * ```
    */
   static formatBytes(e, t = 2) {
     if (e === 0) return "0 B";
@@ -1029,11 +1206,23 @@ class se {
   }
 }
 class ie {
+  /**
+   * Creates a new task with the specified name.
+   * 
+   * @param {string} name - The name identifier for this task.
+   */
   constructor(e) {
     this.name = e;
   }
   /**
-   * Executes the task.
+   * Executes the task with the given input.
+   * 
+   * This method must be implemented by subclasses to define the actual work
+   * performed by the task. Can return either a synchronous result or a Promise.
+   * 
+   * @param {TIn} _input - The input data for the task.
+   * @returns {TOut | Promise<TOut>} The task result, either synchronous or asynchronous.
+   * @throws {Error} When the method is not implemented by a subclass.
    */
   run(e) {
     throw new Error("run() must be implemented by subclass");

package/lib/AcCmColor.d.ts

@@ -1,42 +1,201 @@
+/**
+ * @fileoverview This module provides color handling functionality for AutoCAD files,
+ * including color representation, color name mapping, and color index conversion.
+ *
+ * The module supports various color formats including RGB values, named colors,
+ * AutoCAD color indices, and special values like "ByLayer" and "ByBlock".
+ *
+ * @module AcCmColor
+ * @version 1.0.0
+ */
+/**
+ * Represents a color in AutoCAD, supporting various color formats.
+ *
+ * @class AcCmColor
+ * @version 1.0.0
+ */
 export declare class AcCmColor {
     private _colorIndex;
     private _color;
     private _colorName;
     static NAMES: Record<string, number>;
+    /**
+     * Constructs a new AcCmColor instance.
+     * Initializes the color to "ByLayer" (index 256) and null RGB values.
+     */
     constructor();
+    /**
+     * Gets the current color value.
+     *
+     * @returns {number | null} The color value (RGB or index).
+     */
     get color(): number | null;
+    /**
+     * Sets the color value.
+     *
+     * @param {number | null} value - The color value to set (RGB or index).
+     */
     set color(value: number | null);
+    /**
+     * Gets the hexadecimal representation of the current color.
+     *
+     * @returns {string} The hexadecimal color string (e.g., "0xFFFFFF").
+     */
     get hexColor(): string;
+    /**
+     * Gets the CSS RGB color string representation.
+     *
+     * @returns {string} The CSS RGB color string (e.g., "rgb(255,255,255)").
+     */
     get cssColor(): string;
+    /**
+     * Gets the red component of the current color.
+     *
+     * @returns {number | null} The red component (0-255).
+     */
     get red(): number | null;
+    /**
+     * Gets the green component of the current color.
+     *
+     * @returns {number | null} The green component (0-255).
+     */
     get green(): number | null;
+    /**
+     * Gets the blue component of the current color.
+     *
+     * @returns {number | null} The blue component (0-255).
+     */
     get blue(): number | null;
     /**
-     * AutoCAD color index value. The index value will be in the range 0 to 256. 0 and 256 are special values.
-     * If value less than 0 is set, 0 will be used. If value greater than 256 is set, 256 will be used.
+     * Gets the AutoCAD color index value. The index value will be in the range 0 to 256.
+     * 0 and 256 are special values.
+     *
+     * @returns {number | null} The color index.
+     */
+    get colorIndex(): number | null;
+    /**
+     * Sets the AutoCAD color index value. If value less than 0 is set, 0 will be used. If value greater than
+     * 256 is set, 256 will be used.
      * - 0 indicates that the entity uses the color of the BlockReference that's displaying it. If the entity
      * is not displayed through a block reference (for example, it is directly owned by the model space
      * block table record) and its color is 0, then it will display as though its color were 7.
      * - 256 indicates that the entity uses the color specified in the layer table record it references.
+     *
+     * @param {number | null} value - The color index to set (0-256).
      */
-    get colorIndex(): number | null;
     set colorIndex(value: number | null);
+    /**
+     * Gets the name of the current color.
+     *
+     * @returns {string | null} The color name.
+     */
     get colorName(): string | null;
+    /**
+     * Sets the color by name.
+     *
+     * @param {string | null} value - The color name to set.
+     */
     set colorName(value: string | null);
+    /**
+     * Checks if the color has a name.
+     *
+     * @returns {boolean} True if the color has no name, false otherwise.
+     */
     get hasColorName(): boolean;
+    /**
+     * Checks if the color has an index.
+     *
+     * @returns {boolean} True if the color has no index, false otherwise.
+     */
     get hasColorIndex(): boolean;
+    /**
+     * Checks if the color is set to "ByLayer".
+     *
+     * @returns {boolean} True if the color is "ByLayer", false otherwise.
+     */
     get isByLayer(): boolean;
+    /**
+     * Sets the color to "ByLayer".
+     *
+     * @returns {AcCmColor} The current instance.
+     */
     setByLayer(): this;
+    /**
+     * Checks if the color is set to "ByBlock".
+     *
+     * @returns {boolean} True if the color is "ByBlock", false otherwise.
+     */
     get isByBlock(): boolean;
+    /**
+     * Sets the color to "ByBlock".
+     *
+     * @returns {AcCmColor} The current instance.
+     */
     setByBlock(): this;
+    /**
+     * Sets the color using a scalar value (RGB).
+     *
+     * @param {number} scalar - The scalar value (0-255).
+     * @returns {AcCmColor} The current instance.
+     */
     setScalar(scalar: number): this;
+    /**
+     * Sets the color using RGB values.
+     *
+     * @param {number} r - The red component (0-255).
+     * @param {number} g - The green component (0-255).
+     * @param {number} b - The blue component (0-255).
+     * @returns {AcCmColor} The current instance.
+     */
     setRGB(r: number, g: number, b: number): this;
+    /**
+     * Sets the color by name.
+     *
+     * @param {string} style - The color name to set.
+     * @returns {AcCmColor} The current instance.
+     */
     setColorName(style: string): this;
+    /**
+     * Clones the current AcCmColor instance.
+     *
+     * @returns {AcCmColor} A new AcCmColor instance with the same color and index.
+     */
     clone(): this;
+    /**
+     * Copies the color from another AcCmColor instance.
+     *
+     * @param {AcCmColor} color - The color to copy from.
+     * @returns {AcCmColor} The current instance.
+     */
     copy(color: AcCmColor): this;
+    /**
+     * Checks if two AcCmColor instances are equal.
+     *
+     * @param {AcCmColor} c - The color to compare with.
+     * @returns {boolean} True if the colors and their indices are the same.
+     */
     equals(c: AcCmColor): boolean;
+    /**
+     * Returns a string representation of the color.
+     *
+     * @returns {string} The color name or hexadecimal string.
+     */
     toString(): string;
+    /**
+     * Finds the color name associated with a given RGB value.
+     *
+     * @private
+     * @param {number} target - The RGB value to find a name for.
+     * @returns {string | null} The color name if found, null otherwise.
+     */
     private getColorNameByValue;
+    /**
+     * Finds the AutoCAD color index associated with a given RGB value.
+     *
+     * @private
+     * @param {number} target - The RGB value to find an index for.
+     * @returns {number | null} The color index if found, null otherwise.
+     */
     private getColorIndexByValue;
 }
 //# sourceMappingURL=AcCmColor.d.ts.map

package/lib/AcCmColor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AcCmColor.d.ts","sourceRoot":"","sources":["../src/AcCmColor.ts"],"names":[],"mappings":"AA+LA,qBAAa,SAAS;IACpB,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAe;IACjC,MAAM,CAAC,KAAK,yBAAiB;;IAQ7B,IAAI,KAAK,IAIQ,MAAM,GAAG,IAAI,CAF7B;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAQ7B;IAED,IAAI,QAAQ,WAWX;IAED,IAAI,QAAQ,WAEX;IAED,IAAI,GAAG,kBAEN;IAED,IAAI,KAAK,kBAER;IAED,IAAI,IAAI,kBAEP;IAED;;;;;;;OAOG;IACH,IAAI,UAAU,IAGQ,MAAM,GAAG,IAAI,CADlC;IACD,IAAI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAQlC;IAED,IAAI,SAAS,IAGQ,MAAM,GAAG,IAAI,CADjC;IACD,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAejC;IAED,IAAI,YAAY,YAEf;IAED,IAAI,aAAa,YAEhB;IAED,IAAI,SAAS,YAEZ;IACD,UAAU;IAKV,IAAI,SAAS,YAEZ;IACD,UAAU;IAKV,SAAS,CAAC,MAAM,EAAE,MAAM;IAKxB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAQtC,YAAY,CAAC,KAAK,EAAE,MAAM;IAY1B,KAAK;IAQL,IAAI,CAAC,KAAK,EAAE,SAAS;IAOrB,MAAM,CAAC,CAAC,EAAE,SAAS;IAQnB,QAAQ;IAYR,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,oBAAoB;CAS7B"}
+{"version":3,"file":"AcCmColor.d.ts","sourceRoot":"","sources":["../src/AcCmColor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAoNH;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAe;IACjC,MAAM,CAAC,KAAK,yBAAiB;IAE7B;;;OAGG;;IAOH;;;;OAIG;IACH,IAAI,KAAK,IASQ,MAAM,GAAG,IAAI,CAP7B;IAED;;;;OAIG;IACH,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAQ7B;IAED;;;;OAIG;IACH,IAAI,QAAQ,WAWX;IAED;;;;OAIG;IACH,IAAI,QAAQ,WAEX;IAED;;;;OAIG;IACH,IAAI,GAAG,kBAEN;IAED;;;;OAIG;IACH,IAAI,KAAK,kBAER;IAED;;;;OAIG;IACH,IAAI,IAAI,kBAEP;IAED;;;;;OAKG;IACH,IAAI,UAAU,IAaQ,MAAM,GAAG,IAAI,CAXlC;IACD;;;;;;;;;OASG;IACH,IAAI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAQlC;IAED;;;;OAIG;IACH,IAAI,SAAS,IAQQ,MAAM,GAAG,IAAI,CANjC;IACD;;;;OAIG;IACH,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAejC;IAED;;;;OAIG;IACH,IAAI,YAAY,YAEf;IAED;;;;OAIG;IACH,IAAI,aAAa,YAEhB;IAED;;;;OAIG;IACH,IAAI,SAAS,YAEZ;IACD;;;;OAIG;IACH,UAAU;IAKV;;;;OAIG;IACH,IAAI,SAAS,YAEZ;IACD;;;;OAIG;IACH,UAAU;IAKV;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM;IAKxB;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAQtC;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM;IAY1B;;;;OAIG;IACH,KAAK;IAQL;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS;IAOrB;;;;;OAKG;IACH,MAAM,CAAC,CAAC,EAAE,SAAS;IAQnB;;;;OAIG;IACH,QAAQ;IAYR;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;CAS7B"}