@mescius/dsimageviewer
Version:
Document Solutions Image Viewer
702 lines (701 loc) • 22.2 kB
TypeScript
import type { ImageFormatCode, ImageLayer, ImageViewerAPI, ImageViewerPluginAPI, PluginType, Size } from "./ImageViewer";
/** Style cap types for line and arrow endpoints. */
export type LineCapStyle = 'none' | 'openArrow' | 'closedArrow' | 'dot' | 'circle' | 'diamond' | 'square' | 'slash' | 'star' | 'bar';
/** Direction options for brackets objects. */
export type BracketDirection = 'outward' | 'inward' | 'left-out-right-in' | 'left-in-right-out';
/** Shape presets for brackets objects. */
export type BracketShape = 'curly' | 'round' | 'angle' | 'square' | 'custom';
/**
* Default style options for Text objects.
*/
export type TextObjectToolOptions = {
/**
* Font size in points.
* @default 14
*/
fontSize?: number;
/**
* Font family name.
* Must be one of the fonts listed in {@link PaintToolsPluginOptions.fontNames}.
* @default 'Verdana'
*/
fontName?: string;
/**
* Font color.
* @default '#000000'
*/
fontColor?: string;
/**
* Opacity of the text characters as a percentage (0–100).
* @default 100
*/
fontOpacity?: number;
/**
* Whether the text is italic.
* @default false
*/
fontItalic?: boolean;
/**
* Whether the text is bold.
* @default false
*/
fontBold?: boolean;
/**
* Object opacity as a percentage (0–100).
*/
opacity?: number;
/**
* Object rotation in degrees.
*/
rotation?: number;
};
/**
* Default style options for Rectangle objects.
*/
export type RectangleObjectToolOptions = {
/**
* Stroke width in pixels.
* When omitted, falls back to {@link ToolsOptions.lineWidth}.
*/
lineWidth?: number;
/**
* Stroke color.
* When omitted, falls back to {@link ToolsOptions.lineColor}.
*/
lineColor?: string;
/**
* Object opacity as a percentage (0–100).
*/
opacity?: number;
/**
* Object rotation in degrees.
*/
rotation?: number;
/**
* Fill color.
* Use `'transparent'` or a color with zero alpha for outline-only rectangles.
* When omitted, falls back to {@link ToolsOptions.fillColor}.
*/
fillColor?: string;
/**
* Corner radius in pixels. Use `0` for sharp corners.
*/
borderRadius?: number;
};
/**
* Default style options for Line objects.
*/
export type LineObjectToolOptions = {
/**
* Stroke width in pixels.
* When omitted, falls back to {@link ToolsOptions.lineWidth}.
*/
lineWidth?: number;
/**
* Stroke color.
* When omitted, falls back to {@link ToolsOptions.lineColor}.
*/
lineColor?: string;
/**
* Object opacity as a percentage (0–100).
*/
opacity?: number;
/**
* Object rotation in degrees.
*/
rotation?: number;
/**
* Cap style applied to the start endpoint of the line.
*/
startCapStyle?: LineCapStyle;
/**
* Cap style applied to the end endpoint of the line.
*/
endCapStyle?: LineCapStyle;
/**
* Size of the endpoint caps in pixels.
*/
capSize?: number;
/**
* Color of the endpoint caps.
* When omitted, matches the line color.
*/
capColor?: string;
};
/**
* Default style options for Arrow objects.
*/
export type ArrowObjectToolOptions = LineObjectToolOptions;
/**
* Default style options for Ellipse objects.
*/
export type EllipseObjectToolOptions = {
/**
* Stroke width in pixels.
* When omitted, falls back to {@link ToolsOptions.lineWidth}.
*/
lineWidth?: number;
/**
* Stroke color.
* When omitted, falls back to {@link ToolsOptions.lineColor}.
*/
lineColor?: string;
/**
* Object opacity as a percentage (0–100).
*/
opacity?: number;
/**
* Object rotation in degrees.
*/
rotation?: number;
/**
* Fill color.
* Use `'transparent'` or a color with zero alpha for outline-only ellipses.
* When omitted, falls back to {@link ToolsOptions.fillColor}.
*/
fillColor?: string;
};
/**
* Default style options for Brackets objects.
*/
export type BracketsObjectToolOptions = {
/**
* Stroke width in pixels.
* When omitted, falls back to {@link ToolsOptions.lineWidth}.
*/
lineWidth?: number;
/**
* Stroke color.
* When omitted, falls back to {@link ToolsOptions.lineColor}.
*/
lineColor?: string;
/**
* Object opacity as a percentage (0–100).
*/
opacity?: number;
/**
* Object rotation in degrees.
*/
rotation?: number;
/**
* Visual shape preset applied to both bracket arms.
*/
bracketsShape?: BracketShape;
/**
* Direction of the arrows on the bracket arms.
*/
arrowDirection?: BracketDirection;
/**
* Whether to render the left bracket arm.
*/
showLeftBracket?: boolean;
/**
* Whether to render the right bracket arm.
*/
showRightBracket?: boolean;
/**
* Width of each bracket arm in pixels.
*/
bracketWidth?: number;
/**
* Curve intensity for `'curly'` and `'round'` bracket shapes, as a percentage (0–100).
* Higher values produce more pronounced curves.
*/
curveIntensity?: number;
/**
* Arrow flare intensity for the bracket arms, as a percentage (0–100).
* Higher values produce more pronounced arrow tips.
*/
arrowIntensity?: number;
};
/**
* Default style overrides for all paint objects.
*/
export type ToolsObjectsOptions = {
/**
* Default style overrides for Text objects.
*/
text?: TextObjectToolOptions;
/**
* Default style overrides for Rectangle objects.
*/
rectangle?: RectangleObjectToolOptions;
/**
* Default style overrides for Line objects.
*/
line?: LineObjectToolOptions;
/**
* Default style overrides for Arrow objects.
*/
arrow?: ArrowObjectToolOptions;
/**
* Default style overrides for Ellipse objects.
*/
ellipse?: EllipseObjectToolOptions;
/**
* Default style overrides for Brackets objects.
*/
brackets?: BracketsObjectToolOptions;
};
/**
* Default visual properties applied to each paint and object tool when the toolbar opens.
*
* All values are optional, omitted properties fall back to the built-in defaults.
* User interactions during a session override these values and are persisted in `localStorage`.
*
* Shape properties (`lineWidth`, `lineColor`, `fillColor`) define the initial style for
* newly created Rectangle, Line, Arrow, Ellipse, and Brackets objects.
*
* @see {@link PaintToolsPluginOptions.toolsOptions}
*
* @example
* ```javascript
* viewer.addPlugin(new PaintToolsPlugin({
* tools: {
* penSize: 2,
* penColor: '#e03030',
* brushSize: 20,
* brushHardness: 50,
* eraserSize: 30,
* lineWidth: 2,
* lineColor: '#0055cc',
* objects: {
* text: { fontSize: 16, fontColor: '#222222', fontName: 'Arial', fontBold: true },
* rectangle: { fillColor: 'transparent', borderRadius: 4 },
* line: { endCapStyle: 'closedArrow', capSize: 12 },
* },
* }
* }));
* ```
*/
export type ToolsOptions = {
/**
* Pencil stroke width in pixels.
* @default 1
*/
penSize: number;
/**
* Pencil stroke color.
* @default '#000000'
*/
penColor: string;
/**
* Pencil stroke opacity as a percentage (0–100).
* @default 100
*/
penOpacity: number;
/**
* Brush stroke width in pixels.
* @default 12
*/
brushSize: number;
/**
* Brush stroke color.
* @default '#000000'
*/
brushColor: string;
/**
* Brush edge hardness as a percentage (0–100).
* Lower values produce a soft airbrush effect; higher values produce hard edges.
* @default 70
*/
brushHardness: number;
/**
* Brush stroke opacity as a percentage (0–100).
* @default 100
*/
brushOpacity: number;
/**
* Clone Stamp brush width in pixels.
* @default 60
*/
cloneStampSize: number;
/**
* Clone Stamp opacity as a percentage (0–100).
* @default 100
*/
cloneStampOpacity: number;
/**
* Clone Stamp edge hardness as a percentage (0–100).
* @default 70
*/
cloneStampHardness: number;
/**
* Eraser brush width in pixels.
* @default 12
*/
eraserSize: number;
/**
* Eraser opacity as a percentage (0–100).
* @default 100
*/
eraserOpacity: number;
/**
* Eraser edge hardness as a percentage (0–100).
* @default 70
*/
eraserHardness: number;
/**
* Default stroke width in pixels for shape objects (Rectangle, Line, Arrow, Ellipse, Brackets).
* @default 1
*/
lineWidth: number;
/**
* Default stroke color for shape objects.
* @default '#000000'
*/
lineColor: string;
/**
* Default fill color for shape objects.
* Use `'transparent'` or a color with zero alpha to draw unfilled (outline-only) shapes.
* @default 'transparent'
*/
fillColor: string;
/**
* Default style overrides for all paint objects.
* Allows control over the initial appearance of each object type.
* Values specified here override lineWidth, lineColor, and fillColor for that specific type.
*/
objects?: ToolsObjectsOptions;
};
/**
* Represents a single preset image item
*/
export type PresetImageItem = {
/**
* URL of the image
*/
url: string;
/**
* Display label for the image. If not specified, will be derived from the filename.
*/
label?: string;
/**
* Optional description for the image
*/
description?: string;
/**
* Preferred width when inserted. Uses defaultWidth from config if not specified.
*/
width?: number;
/**
* Preferred height when inserted. Uses defaultHeight from config if not specified.
*/
height?: number;
/**
* Optional tags for searching and filtering
*/
tags?: string[];
/**
* Optional aspect ratio lock (e.g., "1:1", "16:9", "4:3")
*/
aspectRatio?: string;
};
/**
* Represents a category of preset images
*/
export type PresetImageCategory = {
/**
* Display name for the category
*/
name: string;
/**
* Array of images in this category
*/
items: PresetImageItem[];
/**
* Optional icon URL for the category
*/
icon?: string;
};
/**
* Configuration for predefined images
*/
export type ImageGalleryConfig = {
/**
* Array of image categories for organized presentation.
* If not specified, all images will be shown in a single flat list.
*/
categories?: PresetImageCategory[];
/**
* Default width for preset images when inserted.
* Can be overridden per individual image.
*/
defaultWidth?: number;
/**
* Default height for preset images when inserted.
* Can be overridden per individual image.
*/
defaultHeight?: number;
/**
* Whether to maintain aspect ratio when resizing images.
* @default true
*/
maintainAspectRatio?: boolean;
};
/**
* Represents the types of items that can be used in the Paint, Text, and Effects toolbars.
*/
export type ToolbarItemType = "Selection" | "Pencil" | "Brush" | "Eraser" | "CloneStamp" | "Text" | "Pixelate" | "Blur" | "Brightness" | "Contrast" | "BrightnessContrast" | "Vibrance" | "Splitter" | "Size" | "Color" | "UseOriginalImage" | "Undo" | "Redo" | "Apply" | "Cancel" | "FontSize" | "FontName" | "FontBold" | "FontItalic" | "FontColor" | "Rectangle" | "Line" | "Ellipse" | "Arrow" | "Brackets" | "Image" | "ImageGallery" | "BackupObjects" | "RestoreObjects";
/**
* Options for the PaintToolsPlugin.
*/
export type PaintToolsPluginOptions = {
/**
* The position where the "Paint tools", "Text and Objects" and "Effects" buttons should be inserted in the main toolbar.
* Use `false` or `-1` to skip insertion.
* Undefined means the position will be determined automatically.
*/
buttonPosition?: number | false;
/**
* Array of available font names.
* @default ['Arial', 'Verdana', 'Helvetica', 'Tahoma', 'Trebuchet MS', 'Times New Roman', 'Georgia', 'Garamond', 'Courier New', 'Brush Script MT']
*/
fontNames?: string[];
/**
* Specifies default visual properties for each paint and object tool.
*
* These values override the built-in defaults when the toolbar opens for the first time.
* They are superseded by values the user adjusts interactively during the session.
* To change defaults after the viewer is initialized, set `plugin.toolsOptions` at runtime.
*
* @example
* ```javascript
* // Set default pencil and brush options
* viewer.addPlugin(new PaintToolsPlugin({
* tools: {
* penSize: 2,
* penColor: '#e03030',
* brushSize: 20,
* brushHardness: 50,
* brushOpacity: 80,
* eraserSize: 30,
* }
* }));
* ```
*
* @example
* ```javascript
* // Set default style for shape and text objects
* viewer.addPlugin(new PaintToolsPlugin({
* tools: {
* lineWidth: 2,
* lineColor: '#0055cc',
* objects: {
* text: { fontSize: 16, fontColor: '#222222', fontName: 'Arial', fontBold: true },
* rectangle: { fillColor: 'transparent' },
* },
* }
* }));
* ```
*/
tools?: Partial<ToolsOptions>;
/**
* Optional. Specifies the layout of the paint, effects and objects toolbar.
* Defaults:
* * paintTools: ["Apply", "Cancel", "Splitter", "Selection", "Pencil", "Brush", "CloneStamp", "Eraser", "Splitter", "Size", "Color", "UseOriginalImage", "Splitter", "Undo", "Redo"]
* * effectsTools: ["Apply", "Cancel", "Splitter", "Selection", "Splitter", "BrightnessContrast", "Vibrance", "Blur", "Pixelate", "Splitter", "Eraser", "Size", "UseOriginalImage", "Splitter", "Undo", "Redo"]
* * objectTools: ["Apply", "Cancel", "Text", "Rectangle", "Line", "Arrow", "Ellipse", "Brackets", "Image", "ImageGallery", "Splitter", "Splitter", "Undo", "Redo"]
* @example
* ```javascript
* // Modify paint tools toolbar
* viewer.addPlugin(new PaintToolsPlugin({
* toolbarLayout: {
* paintTools: ["Pencil", "Size", "Color", "Splitter", "Apply", "Cancel"]
* }
* }));
* ```
* @example
* ```javascript
* // Modify object tools toolbar
* viewer.addPlugin(new PaintToolsPlugin({
* toolbarLayout: {
* objectTools: ["Apply", "Cancel", "Rectangle", "Arrow"]
* }
* }));
* ```
* @example
* ```javascript
* // Modify effects tools toolbar
* viewer.addPlugin(new PaintToolsPlugin({
* toolbarLayout: {
* effectsTools: ["Apply", "Cancel", "Splitter", "Brightness", "Pixelate" ]
* }
* }));
* ```
*/
toolbarLayout?: {
/**
* Array of items for the effects tools toolbar.
* Set to `false` if you want to hide this toolbar item.
* @default ["Apply", "Cancel", "Splitter", "Selection", "Splitter", "BrightnessContrast", "Vibrance", "Blur", "Pixelate", "Splitter", "Eraser", "Size", "UseOriginalImage", "Splitter", "Undo", "Redo"]
*/
effectsTools: ToolbarItemType[] | boolean;
/**
* Array of items for the paint tools toolbar.
* Set to `false` if you want to hide this toolbar item.
* @default ["Apply", "Cancel", "Splitter", "Selection", "Pencil", "Brush", "CloneStamp", "Eraser", "Splitter", "Size", "Color", "UseOriginalImage", "Splitter", "Undo", "Redo"]
*/
paintTools: ToolbarItemType[] | boolean;
/**
* Array of items for the text tools toolbar.
* @default ["Apply", "Cancel" , "Splitter", "Text", "Splitter", "FontSize", "FontName", "FontBold", "FontItalic", "FontColor", "Splitter", "Undo", "Redo"]
* @deprecated This option is deprecated in favor of the "Text and Objects" toolbar where you can add text objects directly.
*/
textTools: ToolbarItemType[] | boolean;
/**
* Array of items for the insert objects toolbar.
* Set to `false` if you want to hide this toolbar item.
* @default ["Apply", "Cancel", "Text", "Rectangle", "Line", "Arrow", "Ellipse", "Brackets", "Image", "ImageGallery", "Splitter", "Undo", "Redo"]
*/
objectTools: ToolbarItemType[] | boolean;
};
/**
* Configuration for predefined images that can be inserted via the "ImageGallery" toolbar button.
*
* @example
* ```javascript
* // Simple array of image URLs
* viewer.addPlugin(new PaintToolsPlugin({
* imageGallery: [
* 'https://example.com/images/checkmark.png',
* 'https://example.com/images/cross.png',
* 'https://example.com/images/arrow-up.png'
* ]
* }));
* ```
*
* @example
* ```javascript
* // Advanced configuration with labels and categories
* viewer.addPlugin(new PaintToolsPlugin({
* imageGallery: {
* categories: [
* {
* name: "Annotations",
* items: [
* { url: 'images/checkmark.png', label: 'Checkmark', width: 32, height: 32 },
* { url: 'images/cross.png', label: 'Cross mark', width: 32, height: 32 }
* ]
* },
* {
* name: "Arrows",
* items: [
* { url: 'images/arrow-up.png', label: 'Up arrow' },
* { url: 'images/arrow-down.png', label: 'Down arrow' }
* ]
* }
* ]
* }
* }));
* ```
*/
imageGallery?: string[] | ImageGalleryConfig;
};
/**
* Defines Paint Tools Plugin API.
* @ignore exclude API interface from docs since it is documented by implementing class.
*/
export interface PaintToolsPluginAPI extends ImageViewerPluginAPI {
/**
* Plugin options passed at construction time.
*/
readonly options: PaintToolsPluginOptions;
/**
* Gets or sets the default visual properties for each paint and object tool at runtime.
*
* Reading this property returns the last value set either via the constructor option
* `toolsOptions` or by a previous assignment.
*
* Setting this property immediately:
* - updates the paint toolbar state (size, color, opacity, hardness for Pencil, Brush, Eraser, Clone Stamp, and Text),
* - updates the default style applied to **newly created** shape objects (Rectangle, Line, Arrow, Circle, Brackets, Image).
*
* Previously placed objects and the user's own interactive adjustments are not affected.
*
* @example
* ```javascript
* // Change arrow and pencil defaults after the viewer has opened
* const plugin = viewer.findPlugin('paintTools');
* plugin.toolsOptions = {
* lineWidth: 3,
* lineColor: '#cc0000',
* penSize: 5,
* penColor: '#333333',
* };
* ```
*/
get toolsOptions(): Required<ToolsOptions>;
set toolsOptions(options: Partial<ToolsOptions>);
/**
* Returns the resolved item layout for the Effects toolbar.
* Reflects `toolbarLayout.effectsTools` from plugin options:
* `true`/`undefined`/`null` → default layout; `false` → empty array; array → used as-is.
* @see {PaintToolsPluginOptions.toolbarLayout}
*/
readonly effectsToolbarLayout: ToolbarItemType[];
/**
* Returns the layout for the effects tools toolbar.
* If the value is `true`, `undefined`, or `null`, a default layout is returned.
* If the value is `false`, an empty layout is returned.
* Otherwise, the provided custom layout is used.
*
* @see {PaintToolsPluginOptions.toolbarLayouts}
*/
readonly paintToolbarLayout: ToolbarItemType[];
/**
* Returns the layout for the effects tools toolbar.
* If the value is `true`, `undefined`, or `null`, a default layout is returned.
* If the value is `false`, an empty layout is returned.
* Otherwise, the provided custom layout is used.
*
* @see {PaintToolsPluginOptions.toolbarLayouts}
*/
readonly textToolbarLayout: ToolbarItemType[];
/**
* Returns the layout for the effects tools toolbar.
* If the value is `true`, `undefined`, or `null`, a default layout is returned.
* If the value is `false`, an empty layout is returned.
* Otherwise, the provided custom layout is used.
*
* @see {PaintToolsPluginOptions.toolbarLayouts}
*/
readonly objectsToolbarLayout: ToolbarItemType[];
}
/**
* Paint Tools Plugin.
* Adds the "Paint tools", "Effects" and "Text and Objects" buttons.
* @example
* ```html
* <script src="dsimageviewer.js"></script></head>
* <script src="plugins/paintTools.js"></script>
* <script>
* const viewer = new DsImageViewer("#root");
* viewer.addPlugin(new PaintToolsPlugin());
* </script>
* ```
*/
export declare class PaintToolsPlugin implements PaintToolsPluginAPI {
constructor(options?: PaintToolsPluginOptions);
viewer: ImageViewerAPI;
options: PaintToolsPluginOptions;
toolsOptions: Required<ToolsOptions>;
effectsToolbarLayout: ToolbarItemType[];
paintToolbarLayout: ToolbarItemType[];
textToolbarLayout: ToolbarItemType[];
objectsToolbarLayout: ToolbarItemType[];
paintLayer: ImageLayer;
isReady: boolean;
naturalSize: Size;
isImageFormatSupported(imageFormat: string | ImageFormatCode, allowUnknown?: boolean): boolean;
dispose(): void;
removePaintLayer(): void;
id: PluginType;
initialize(viewer: ImageViewerAPI): void;
}
export type { HSLColor, Color } from '@dt/core-ui';
declare global {
interface Window {
PaintToolsPlugin: typeof PaintToolsPlugin;
}
}