apexify.js 4.9.26 → 4.9.27

package/lib/Canvas/utils/types.ts

@@ -9,20 +9,61 @@ export interface OutputFormat {
     type?: 'buffer'  | 'url' | 'blob' | 'base64' | 'dataURL' | 'arraybuffer';
 }
 
+export type AlignMode =
+  | 'center' | 'top' | 'bottom' | 'left' | 'right'
+  | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 
-type gradient =  {
-    type: 'linear' | 'radial';
-    rotate?: number;
-    startX?: number;
-    startY?: number;
-    endX?: number;
-    endY?: number;
-    startRadius?: number;
-    endRadius?: number;
-    colors: { stop: number; color: string }[];
-};
+export type FitMode = 'fill' | 'contain' | 'cover';
+
+export interface StrokeOptions {
+  color?: string;
+  gradient?: gradient;
+  width?: number;        // px
+  position?: number;     // px (+out/-in)
+  blur?: number;         // px
+  opacity?: number;      // 0..1
+  borderRadius?: number | 'circular';
+  borderPosition?: string;
+}
+
+export interface ShadowOptions {
+  color?: string;          // e.g. 'rgba(0,0,0,1)'
+  gradient?: gradient;     // <— gradient-capable shadow
+  offsetX?: number;        // px
+  offsetY?: number;        // px
+  blur?: number;           // px
+  opacity?: number;        // 0..1
+  borderRadius?: number | "circular";
+  borderPosition?: borderPosition;
+}
+
+export interface BoxBackground {
+  color?: string;
+  gradient?: gradient;
+}
+export type GradientStop = { stop: number; color: string };
+
+export type gradient =
+  | {
+      type: 'linear';
+      // line from (startX,startY) to (endX,endY)
+      startX?: number; startY?: number;
+      endX?: number;   endY?: number;
+      rotate?: number;           // degrees, rotation around pivot (default: canvas center)
+      pivotX?: number; pivotY?: number; // optional pivot for rotation
+      colors: GradientStop[];
+    }
+  | {
+      type: 'radial';
+      // two circles (default to center-based radial if not supplied)
+      startX?: number; startY?: number; startRadius?: number; // inner circle
+      endX?: number;   endY?: number;   endRadius?: number;   // outer circle
+      // rotation is NOP for perfectly concentric radial, but supported if centers aren't equal
+      rotate?: number; pivotX?: number; pivotY?: number;
+      colors: GradientStop[];
+    };
 
-type borderPosition = 'all' | 'top' | 'left' | 'right' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | string;
+export type borderPosition = 'all' | 'top' | 'left' | 'right' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | string;
 
 /**
  * Configuration options for the canvas.
@@ -38,16 +79,42 @@ export interface CanvasConfig {
     height?: number;
     x?: number;
     y?: number;
-    customBg?: string;
+
+    customBg?: {
+      source: string
+      inherit?: boolean;
+      fit?: 'fill' | 'contain' | 'cover';
+      align?: 'center' | 'top' | 'bottom' | 'left' | 'right'
+      | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    };
+
     colorBg?: string;
     gradientBg?: gradient; 
+    patternBg?: PatternOptions;
+    noiseBg?: { intensity?: number };
+    bgLayers?: Array<
+      { type: "color"; value: string } |
+      { type: "gradient"; value: gradient } |
+      { type: "image"; source: string; opacity?: number } |
+      { type: "pattern"; source: string; repeat?: string; opacity?: number } |
+      { type: "noise"; intensity?: number }
+    >;
+    blendMode?: GlobalCompositeOperation;
+
     opacity?: number;
     blur?: number;
+
+    rotation?: number;
+    borderRadius?: number | "circular";
+    borderPosition?: borderPosition;
+  
     zoom?: {
-        scale?: number;
-        x?: number;
-        y?: number;
-    };
+      scale?: number;          // optional, defaults to 1
+      centerX?: number;
+      centerY?: number;
+   };
+
+  
     stroke?: {
         color?: string;
         blur?: number;
@@ -66,9 +133,6 @@ export interface CanvasConfig {
         borderRadius?: number | "circular";
         gradient?: gradient;
     };
-    rotation?: number;
-    borderRadius?: number | "circular";
-    borderPosition?: borderPosition;
 };
 
 /**
@@ -96,95 +160,185 @@ export interface CanvasConfig {
  * @param {number} shadow.opacity - The opacity of the shadow.
  * @param {number | string} shadow.borderRadius - The border radius of the shadow.
  */
+export type ShapeType = 'rectangle' | 'square' | 'circle' | 'triangle' | 'trapezium' | 'star' | 'heart' | 'polygon';
+
+export interface ShapeProperties {
+  fill?: boolean;
+  color?: string;
+  gradient?: gradient;
+  points?: { x: number; y: number }[]; // for polygon
+  radius?: number; // for circle
+  sides?: number; // for polygon
+  innerRadius?: number; // for star
+  outerRadius?: number; // for star
+}
+
 export interface ImageProperties {
-    source: string; 
-    width?: number; 
-    height?: number; 
-    x?: number;
-    y?: number;
-    isFilled?: boolean;
-    filling?: { percentage?: number, rotation?: number }
-    color?: string; 
+  // required
+  source: string | Buffer | ShapeType;
+  x: number;
+  y: number;
+
+  // size (if omitted and inherit=true -> use intrinsic)
+  width?: number;
+  height?: number;
+  inherit?: boolean;
+
+  // fitting
+  fit?: FitMode;           // default 'fill'
+  align?: AlignMode;       // default 'center'
+
+  // visuals
+  rotation?: number;       // deg around box center
+  opacity?: number;        // bitmap alpha
+  blur?: number;           // bitmap blur px
+  borderRadius?: number | 'circular';
+  borderPosition?: string;
+
+  // image filters
+  filters?: ImageFilter[];
+
+  // shape properties (when source is a shape)
+  shape?: ShapeProperties;
+
+  // independent passes
+  shadow?: ShadowOptions;
+  stroke?: StrokeOptions;
+  boxBackground?: BoxBackground; // under bitmap, inside clip
+}
+
+export interface ImageFilter {
+  type: 'gaussianBlur' | 'motionBlur' | 'radialBlur' | 'sharpen' | 'noise' | 'grain' | 
+        'edgeDetection' | 'emboss' | 'invert' | 'grayscale' | 'sepia' | 'pixelate' | 
+        'brightness' | 'contrast' | 'saturation' | 'hueShift' | 'posterize';
+  intensity?: number;
+  radius?: number;
+  angle?: number;        // for motion blur
+  centerX?: number;      // for radial blur
+  centerY?: number;      // for radial blur
+  value?: number;        // for brightness, contrast, saturation, hue shift
+  levels?: number;       // for posterize
+  size?: number;         // for pixelate
+}
+
+
+
+/**
+ * Enhanced text properties interface with comprehensive styling options
+ */
+export interface TextProperties {
+  // === CORE TEXT PROPERTIES ===
+  /** Text content to render */
+  text: string;
+  /** X position on canvas */
+  x: number;
+  /** Y position on canvas */
+  y: number;
+
+  // === FONT MANAGEMENT ===
+  /** Path to custom font file (.ttf, .otf, .woff, etc.) */
+  fontPath?: string;
+  /** Custom font name (used with fontPath) */
+  fontName?: string;
+  /** Font size in pixels (default: 16) */
+  fontSize?: number;
+  /** Font family name (e.g., 'Arial', 'Helvetica', 'Times New Roman') */
+  fontFamily?: string;
+
+  // === TEXT DECORATION ===
+  /** Make text bold */
+  bold?: boolean;
+  /** Make text italic */
+  italic?: boolean;
+  /** Add underline decoration */
+  underline?: boolean;
+  /** Add overline decoration */
+  overline?: boolean;
+  /** Add strikethrough decoration */
+  strikethrough?: boolean;
+  /** Highlight text with background color */
+  highlight?: {
+    /** Highlight color (hex, rgb, rgba, hsl, etc.) */
+    color?: string;
+    /** Highlight opacity (0-1, default: 0.3) */
     opacity?: number;
-    blur?: number;
-    zoom?: {
-        scale?: number;
-        x?: number;
-        y?: number;
-    };
-    gradient?: gradient;
-    rotation?: number; 
-    borderRadius?: number | "circular";
-    borderPosition?: borderPosition;
-    perspective?: {
-        topLeft: { x: number, y: number };
-        topRight: { x: number, y: number };
-        bottomRight: { x: number, y: number };
-        bottomLeft: { x: number, y: number };
-    }
-    stroke?: {
-        color?: string;
-        width?: number;
-        opacity?: number;
-        blur?: number;
-        position?: number;
-        borderRadius?:  number | "circular";
-        borderPosition?: borderPosition;
-        gradient?: gradient;
-    };
-    shadow?: {
-        color?: string; 
-        offsetX?: number;
-        offsetY?: number; 
-        blur?: number; 
-        opacity?: number; 
-        borderRadius?: number | "circular",
-        gradient?: gradient;        
-        
-        flip?: { horizontal?: boolean; vertical?: boolean };
-        clip?: { type: 'rect' | 'circle' | 'polygon' | 'custom'; points?: { x: number, y: number }[] };
-        tint?: { color: string; opacity?: number };
-        noise?: { intensity: number };
-        vignette?: { strength: number; radius?: number };
-        duotone?: { shadows: string; highlights: string };
-        pixelate?: { size: number };
-        bloom?: { intensity: number; threshold?: number; radius?: number };
-        warp?: { type: 'arc' | 'bulge' | 'pinch' | 'wave' | 'twist'; intensity: number };
-        halftone?: { dotSize: number; contrast?: number };
-    };
-};
+  };
 
-export interface TextObject {
-    text?: string;
-    x?: number;
-    y?: number;
-    fontPath?: string;
-    fontName?: string;
-    fontSize?: number;
-    isBold?: boolean;
+  // === SPACING & POSITIONING ===
+  /** Line height multiplier (default: 1.4) */
+  lineHeight?: number;
+  /** Space between letters in pixels */
+  letterSpacing?: number;
+  /** Space between words in pixels */
+  wordSpacing?: number;
+  /** Maximum width for text wrapping */
+  maxWidth?: number;
+  /** Maximum height for text (truncates with ellipsis) */
+  maxHeight?: number;
+
+  // === TEXT ALIGNMENT ===
+  /** Horizontal text alignment */
+  textAlign?: 'left' | 'center' | 'right' | 'start' | 'end';
+  /** Vertical text baseline */
+  textBaseline?: 'alphabetic' | 'bottom' | 'hanging' | 'ideographic' | 'middle' | 'top';
+
+  // === TEXT COLORING ===
+  /** Text color (hex, rgb, rgba, hsl, etc.) */
+  color?: string;
+  /** Gradient fill for text */
+  gradient?: gradient;
+  /** Text opacity (0-1, default: 1) */
+  opacity?: number;
+
+  // === TEXT EFFECTS ===
+  /** Text glow effect */
+  glow?: {
+    /** Glow color */
     color?: string;
-    maxWidth?: number;
-    lineHeight?: number;
-    maxHeight?: number;
-    textAlign?: "end" | "center" | "left" | "right" | "start" ;
-    textBaseline?: "alphabetic" | "bottom" | "hanging" | "ideographic" | "middle" | "top";
-    outlined?: boolean;
+    /** Glow intensity/blur radius */
+    intensity?: number;
+    /** Glow opacity (0-1) */
+    opacity?: number;
+  };
+  /** Text shadow effect */
+  shadow?: {
+    /** Shadow color */
+    color?: string;
+    /** Horizontal shadow offset */
+    offsetX?: number;
+    /** Vertical shadow offset */
+    offsetY?: number;
+    /** Shadow blur radius */
+    blur?: number;
+    /** Shadow opacity (0-1) */
+    opacity?: number;
+  };
+  /** Text stroke/outline */
+  stroke?: {
+    /** Stroke color */
+    color?: string;
+    /** Stroke width in pixels */
+    width?: number;
+    /** Gradient stroke */
     gradient?: gradient;
-    shadow?: {
-        color?: string;
-        offsetX?: number;
-        offsetY?: number;
-        blur?: number;
-        opacity?: number;
-    };
-    stroke?: {
-        color?: string;
-        blur?: number;
-        width?: number;
-        gradient?: gradient;
-    };
-    rotation?: number;
+    /** Stroke opacity (0-1) */
     opacity?: number;
+  };
+
+  // === TRANSFORMATIONS ===
+  /** Text rotation in degrees */
+  rotation?: number;
+}
+
+/**
+ * Legacy TextObject interface for backward compatibility
+ * @deprecated Use TextProperties instead
+ */
+export interface TextObject extends TextProperties {
+  /** @deprecated Use bold instead */
+  isBold?: boolean;
+  /** @deprecated Use outlined instead of stroke */
+  outlined?: boolean;
 }
 
 /**
@@ -522,21 +676,51 @@ export interface GradientConfig{
   };
   
   
+  /**
+   * Enhanced pattern options supporting all pattern types
+   */
   export interface PatternOptions {
-      type: 'dots' | 'stripes' | 'grid' | 'checkerboard' | 'noise' | 'waves' | 'diagonal-checkerboard' | 'custom';
-      color?: string;
-      secondaryColor?: string;
-      x?: number;
-      y?: number;
-      width?: number;
-      height?: number;
-      size?: number;
-      spacing?: number;
-      angle?: number; 
-      customPatternImage?: string; 
-      backgroundColor?: string;
-      gradient?: GradientConfig;
-    }
+    // === PATTERN TYPE ===
+    /** Pattern type: built-in patterns or custom image */
+    type: 'grid' | 'dots' | 'diagonal' | 'stripes' | 'waves' | 'crosses' | 
+          'hexagons' | 'checkerboard' | 'diamonds' | 'triangles' | 'stars' | 'polka' | 'custom';
+    
+    // === PATTERN COLORS ===
+    /** Primary pattern color (default: '#ffffff') */
+    color?: string;
+    /** Secondary pattern color for two-color patterns (default: 'transparent') */
+    secondaryColor?: string;
+    /** Pattern opacity (0-1, default: 0.3) */
+    opacity?: number;
+    
+    // === PATTERN SIZING ===
+    /** Pattern element size in pixels (default: 20) */
+    size?: number;
+    /** Spacing between pattern elements in pixels (default: 10) */
+    spacing?: number;
+    /** Pattern rotation angle in degrees (default: 0) */
+    rotation?: number;
+    
+    // === CUSTOM PATTERN ===
+    /** Custom pattern image path/URL (for type: 'custom') */
+    customPatternImage?: string;
+    /** Custom pattern repeat mode (default: 'repeat') */
+    repeat?: 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat';
+    /** Custom pattern scale multiplier (default: 1) */
+    scale?: number;
+    
+    // === PATTERN POSITIONING ===
+    /** Pattern offset X position (default: 0) */
+    offsetX?: number;
+    /** Pattern offset Y position (default: 0) */
+    offsetY?: number;
+    
+    // === ADVANCED OPTIONS ===
+    /** Pattern blend mode (default: 'overlay') */
+    blendMode?: GlobalCompositeOperation;
+    /** Pattern gradient (overrides color) */
+    gradient?: GradientConfig;
+  }
     
     
   export interface ExtractFramesOptions {

package/lib/Canvas/utils/utils.ts

@@ -1,72 +1,85 @@
-/**
- * Exported utilities for handling canvas configurations and drawing operations.
- * @param CanvasConfig The configuration options for the canvas.
- * @param radiusBorder The function for applying a radius border to the canvas.
- * @param circularBorder The function for applying a circular border to the canvas.
- * @param drawBackgroundColor The function for drawing a solid background color on the canvas.
- * @param drawBackgroundGradient The function for drawing a gradient background on the canvas.
- * @param customBackground The function for drawing a custom background image on the canvas.
- */
-
-
-
-import { OutputFormat, CanvasConfig, ImageProperties, TextObject, GIFOptions, GIFResults, CustomOptions, cropOptions, GradientConfig, Frame, PatternOptions, ExtractFramesOptions, ResizeOptions, CropOptions, MaskOptions, BlendOptions } from "./types";
-import { drawBackgroundColor, drawBackgroundGradient, customBackground, backgroundRadius } from "./Background/bg";
-import { applyRotation, imageRadius, applyStroke, applyZoom, applyShadow, objectRadius, drawShape, applyPerspective } from './Image/imageProperties'
-import { drawText, WrappedText } from "./Texts/textProperties";
-import { loadImages, resizingImg, converter, applyColorFilters, imgEffects, cropOuter, cropInner, detectColors, removeColor, bgRemoval } from './General/general functions';
-import { customLines } from "./Custom/customLines";
-import { verticalBarChart, pieChart, lineChart } from './Charts/charts'
-import { url, arrayBuffer, base64, dataURL, blob  } from "./General/conversion";
-
-export {
-    url,
-    OutputFormat,
-    arrayBuffer,
-    base64,
-    dataURL,
-    blob,
-    CanvasConfig,
-    ImageProperties,
-    TextObject,
-    GIFOptions,
-    GIFResults,
-    CustomOptions,
-    cropOptions,
-    customLines,
-    drawBackgroundColor,
-    drawBackgroundGradient,
-    customBackground,
-    applyRotation,
-    imageRadius,
-    applyStroke,
-    applyZoom,
-    applyShadow,
-    objectRadius,
-    backgroundRadius,
-    drawShape,
-    drawText,
-    WrappedText,
-    loadImages,
-    resizingImg,
-    converter,
-    applyColorFilters,
-    imgEffects,
-    verticalBarChart,
-    pieChart,
-    lineChart,
-    cropInner,
-    cropOuter,
-    detectColors,
-    removeColor,
-    bgRemoval,
-    GradientConfig,
-    Frame,
-    PatternOptions,
-    ExtractFramesOptions,
-    ResizeOptions,
-    CropOptions,
-    applyPerspective,
-    MaskOptions,
-    BlendOptions
-};
+/**
+ * Exported utilities for handling canvas configurations and drawing operations.
+ * @param CanvasConfig The configuration options for the canvas.
+ * @param radiusBorder The function for applying a radius border to the canvas.
+ * @param circularBorder The function for applying a circular border to the canvas.
+ * @param drawBackgroundColor The function for drawing a solid background color on the canvas.
+ * @param drawBackgroundGradient The function for drawing a gradient background on the canvas.
+ * @param customBackground The function for drawing a custom background image on the canvas.
+ */
+
+
+
+import { OutputFormat, CanvasConfig, ImageProperties, TextObject, TextProperties, GIFOptions, GIFResults, CustomOptions, cropOptions, GradientConfig, Frame, PatternOptions, ExtractFramesOptions, ResizeOptions, CropOptions, MaskOptions, BlendOptions, ShapeType, ShapeProperties, ImageFilter } from "./types";
+import { drawBackgroundColor, drawBackgroundGradient, customBackground, applyCanvasZoom, drawPattern, applyNoise } from "./Background/bg";
+import { buildPath, applyRotation, createGradientFill, fitInto, loadImageCached, applyStroke, drawBoxBackground, applyShadow } from './Image/imageProperties'
+import { applyImageFilters } from './Image/imageFilters'
+import { applySimpleProfessionalFilters } from './Image/simpleProfessionalFilters'
+import { drawText, WrappedText } from "./Texts/textProperties";
+import { loadImages, resizingImg, converter, applyColorFilters, imgEffects, cropOuter, cropInner, detectColors, removeColor, bgRemoval } from './General/general functions';
+import { customLines } from "./Custom/customLines";
+import { verticalBarChart, pieChart, lineChart } from './Charts/charts'
+import { url, arrayBuffer, base64, dataURL, blob  } from "./General/conversion";
+import { drawShape, isShapeSource, createShapePath } from "./Shapes/shapes";
+
+export {
+    url,
+    OutputFormat,
+    arrayBuffer,
+    base64,
+    dataURL,
+    blob,
+    CanvasConfig,
+    ImageProperties,
+    TextObject,
+    TextProperties,
+    GIFOptions,
+    GIFResults,
+    CustomOptions,
+    cropOptions,
+    customLines,
+    drawBackgroundColor,
+    drawBackgroundGradient,
+    customBackground,
+    drawText,
+    WrappedText,
+    loadImages,
+    resizingImg,
+    converter,
+    applyColorFilters,
+    imgEffects,
+    verticalBarChart,
+    pieChart,
+    lineChart,
+    cropInner,
+    cropOuter,
+    detectColors,
+    removeColor,
+    bgRemoval,
+    GradientConfig,
+    Frame,
+    PatternOptions,
+    ExtractFramesOptions,
+    ResizeOptions,
+    CropOptions,
+    buildPath,
+    applyRotation,
+    createGradientFill,
+    fitInto, loadImageCached, 
+    applyStroke,
+    applyShadow,
+    drawBoxBackground,
+    MaskOptions,
+    BlendOptions,
+    applyCanvasZoom,
+    drawPattern,
+    applyNoise,
+    ShapeType,
+    ShapeProperties,
+    ImageFilter,
+    drawShape,
+    isShapeSource,
+    createShapePath,
+    applyImageFilters,
+    applySimpleProfessionalFilters
+};