@cj-tech-master/excelts 6.0.0 → 6.1.0

package/dist/types/modules/excel/stream/workbook-writer.browser.d.ts

@@ -71,6 +71,13 @@ export interface WorksheetWriterLike {
     committed?: boolean;
     stream: any;
     commit(): void;
+    /** Drawing model — populated after commit if images were added */
+    drawing?: {
+        rId: string;
+        name: string;
+        anchors: any[];
+        rels: any[];
+    };
 }
 export interface WorksheetWriterConstructor<T extends WorksheetWriterLike> {
     new (options: {
@@ -129,6 +136,12 @@ export declare abstract class WorkbookWriterBase<TWorksheetWriter extends Worksh
      * Add media files - can be overridden by Node.js for file system support
      */
     addMedia(): Promise<void[]>;
+    /**
+     * Generate drawing XML and drawing relationship files for worksheets that have images.
+     * Must be called after _commitWorksheets() so that each WorksheetWriter has built its
+     * drawing model, and after addMedia() so that media files are already in the ZIP.
+     */
+    protected addDrawings(): void;
     addApp(): Promise<void>;
     addCore(): Promise<void>;
     addSharedStrings(): Promise<void>;

package/dist/types/modules/excel/stream/worksheet-writer.d.ts

@@ -3,7 +3,7 @@ import { Row } from "../row.js";
 import type { Cell } from "../cell.js";
 import { Column } from "../column.js";
 import { DataValidations } from "../data-validations.js";
-import type { RowBreak, ColBreak, PageSetup, HeaderFooter, WorksheetProperties, WorksheetView, WorksheetState, AutoFilter, WorksheetProtection, ConditionalFormattingOptions } from "../types.js";
+import type { RowBreak, ColBreak, PageSetup, HeaderFooter, WorksheetProperties, WorksheetView, WorksheetState, AutoFilter, WorksheetProtection, ConditionalFormattingOptions, AddImageRange } from "../types.js";
 interface WorksheetWriterOptions {
     id: number;
     name?: string;
@@ -16,6 +16,34 @@ interface WorksheetWriterOptions {
     autoFilter?: AutoFilter;
     headerFooter?: Partial<HeaderFooter>;
 }
+/** Internal model for an image added via addImage(). */
+interface WriterImageModel {
+    type: "image";
+    imageId: string;
+    range: {
+        tl: {
+            nativeCol: number;
+            nativeColOff: number;
+            nativeRow: number;
+            nativeRowOff: number;
+        };
+        br?: {
+            nativeCol: number;
+            nativeColOff: number;
+            nativeRow: number;
+            nativeRowOff: number;
+        };
+        ext?: {
+            width: number;
+            height: number;
+        };
+        editAs?: string;
+    };
+    hyperlinks?: {
+        hyperlink?: string;
+        tooltip?: string;
+    };
+}
 declare class WorksheetWriter {
     id: number;
     name: string;
@@ -69,6 +97,8 @@ declare class WorksheetWriter {
     startedData: boolean;
     private _background?;
     private _headerRowCount?;
+    /** Drawing model — populated during commit if images were added */
+    private _drawing?;
     /** Relationship Id - assigned by WorkbookWriter */
     rId?: string;
     constructor(options: WorksheetWriterOptions);
@@ -99,8 +129,23 @@ declare class WorksheetWriter {
     mergeCells(...cells: (string | number)[]): void;
     addConditionalFormatting(cf: ConditionalFormattingOptions): void;
     removeConditionalFormatting(filter?: number | ((cf: ConditionalFormattingOptions) => boolean)): void;
-    addBackgroundImage(imageId: number): void;
+    addBackgroundImage(imageId: string | number): void;
     getBackgroundImageId(): number | undefined;
+    /**
+     * Using the image id from `WorkbookWriter.addImage`,
+     * embed an image within the worksheet to cover a range.
+     */
+    addImage(imageId: string | number, range: AddImageRange): void;
+    /**
+     * Return the images that have been added to this worksheet.
+     * Each entry contains imageId and the normalised range (with native anchors).
+     */
+    getImages(): ReadonlyArray<WriterImageModel>;
+    /**
+     * Parse the user-supplied range into a normalised internal model
+     * mirroring what the regular Worksheet / Image class does.
+     */
+    private _parseImageRange;
     protect(password?: string, options?: Partial<WorksheetProtection>): Promise<void>;
     unprotect(): void;
     private _write;
@@ -122,9 +167,18 @@ declare class WorksheetWriter {
     private _writePageSetup;
     private _writeHeaderFooter;
     private _writeAutoFilter;
+    private _writeDrawing;
+    /** Returns the drawing model if images were added, for the workbook writer. */
+    get drawing(): {
+        rId: string;
+        name: string;
+        anchors: any[];
+        rels: any[];
+    } | undefined;
     private _writeBackground;
     private _writeLegacyData;
     private _writeDimensions;
     private _writeCloseWorksheet;
 }
 export { WorksheetWriter };
+export type { WriterImageModel };

package/dist/types/modules/excel/utils/drawing-utils.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared utilities for building drawing models (anchors + relationships)
+ * used by both the streaming WorksheetWriter and the non-streaming WorkSheetXform.
+ *
+ * This eliminates the duplicated anchor/rel building logic and provides
+ * a single, correct image-rel deduplication strategy.
+ */
+interface DrawingAnchor {
+    picture: {
+        rId: string;
+        hyperlinks?: {
+            tooltip?: string;
+            rId: string;
+        };
+    };
+    range: any;
+}
+interface DrawingRel {
+    Id: string;
+    Type: string;
+    Target: string;
+    TargetMode?: string;
+}
+interface DrawingModel {
+    anchors: DrawingAnchor[];
+    rels: DrawingRel[];
+}
+interface ImageMedium {
+    imageId: string | number;
+    range: any;
+    hyperlinks?: {
+        hyperlink?: string;
+        tooltip?: string;
+    };
+}
+/**
+ * Resolves a media filename into the drawing-level relative target path.
+ *
+ * In the non-streaming path, media entries have separate `name` and `extension`
+ * fields (e.g. name="image0", extension="png").
+ * In the streaming path, `name` already includes the extension (e.g. "image0.png").
+ *
+ * This function accepts both forms and returns e.g. `"../media/image0.png"`.
+ */
+export declare function resolveMediaTarget(medium: {
+    name?: string;
+    extension?: string;
+}): string;
+/** Options for {@link buildDrawingAnchorsAndRels}. */
+interface BuildDrawingOptions {
+    /** Look up a book-level image by its id. Return `undefined` if not found. */
+    getBookImage: (imageId: string | number) => {
+        name?: string;
+        extension?: string;
+    } | undefined;
+    /** Generate the next unique rId string for the drawing rels. */
+    nextRId: (rels: DrawingRel[]) => string;
+}
+/**
+ * Build the drawing anchors and relationships from a list of image media entries.
+ *
+ * This is the core logic shared between:
+ * - `WorksheetWriter._writeDrawing()` (streaming)
+ * - `WorkSheetXform.prepare()` (non-streaming)
+ *
+ * It correctly deduplicates image rels: if the same `imageId` is used for
+ * multiple anchors, only one image relationship is created and shared.
+ */
+export declare function buildDrawingAnchorsAndRels(media: ImageMedium[], existingRels: DrawingRel[], options: BuildDrawingOptions): DrawingModel;
+/**
+ * Filter drawing anchors to remove invalid entries before XML generation.
+ *
+ * Shared between streaming `WorkbookWriterBase.addDrawings()` and
+ * non-streaming `XLSX.addDrawings()`.
+ */
+export declare function filterDrawingAnchors(anchors: any[]): any[];
+export {};

package/dist/types/modules/excel/xlsx/xform/sheet/worksheet-xform.d.ts

@@ -5,7 +5,6 @@ declare class WorkSheetXform extends BaseXform {
     };
     private ignoreNodes;
     parser: any;
-    private preImageId;
     static WORKSHEET_ATTRIBUTES: {
         xmlns: string;
         "xmlns:r": string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cj-tech-master/excelts",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "TypeScript Excel Workbook Manager - Read and Write xlsx and csv Files.",
   "type": "module",
   "main": "./dist/cjs/index.js",