ImageBuilder.java

package com.demcha.compose.document.dsl;

import com.demcha.compose.document.image.DocumentImageData;
import com.demcha.compose.document.image.DocumentImageFitMode;
import com.demcha.compose.document.node.DocumentBookmarkOptions;
import com.demcha.compose.document.node.DocumentLinkOptions;
import com.demcha.compose.document.node.DocumentLinkTarget;
import com.demcha.compose.document.node.ExternalLinkTarget;
import com.demcha.compose.document.node.InternalLinkTarget;
import com.demcha.compose.document.node.ImageNode;
import com.demcha.compose.document.style.DocumentInsets;
import com.demcha.compose.document.style.DocumentTransform;

import java.nio.file.Path;
import java.util.Objects;

/**
 * Builder for semantic image nodes.
 *
 * @author Artem Demchyshyn
 * @since 1.0.0
 */
public final class ImageBuilder implements Transformable<ImageBuilder> {
    private String name = "";
    private DocumentImageData imageData;
    private Double width;
    private Double height;
    private Double scale;
    private DocumentImageFitMode fitMode = DocumentImageFitMode.STRETCH;
    private DocumentLinkTarget linkTarget;
    private String anchor;
    private DocumentBookmarkOptions bookmarkOptions;
    private DocumentInsets padding = DocumentInsets.zero();
    private DocumentInsets margin = DocumentInsets.zero();
    private DocumentTransform transform = DocumentTransform.NONE;

    /**
     * Creates an image builder.
     */
    public ImageBuilder() {
    }

    /**
     * Sets the image node name.
     *
     * @param name name used in snapshots and layout graph paths
     * @return this builder
     */
    public ImageBuilder name(String name) {
        this.name = name == null ? "" : name;
        return this;
    }

    /**
     * Sets image source data.
     *
     * @param imageData image data
     * @return this builder
     */
    public ImageBuilder source(DocumentImageData imageData) {
        this.imageData = Objects.requireNonNull(imageData, "imageData");
        return this;
    }

    /**
     * Sets image source from an in-memory byte array.
     *
     * @param bytes image bytes
     * @return this builder
     */
    public ImageBuilder source(byte[] bytes) {
        return source(DocumentImageData.fromBytes(bytes));
    }

    /**
     * Sets image source from a filesystem path.
     *
     * @param path image path
     * @return this builder
     */
    public ImageBuilder source(Path path) {
        return source(DocumentImageData.fromPath(path));
    }

    /**
     * Sets image source from a filesystem path string.
     *
     * @param path image path
     * @return this builder
     */
    public ImageBuilder source(String path) {
        return source(DocumentImageData.fromPath(path));
    }

    /**
     * Sets image width.
     *
     * @param width width in points
     * @return this builder
     */
    public ImageBuilder width(double width) {
        this.width = width;
        return this;
    }

    /**
     * Sets image height.
     *
     * @param height height in points
     * @return this builder
     */
    public ImageBuilder height(double height) {
        this.height = height;
        return this;
    }

    /**
     * Sets image width and height.
     *
     * @param width  width in points
     * @param height height in points
     * @return this builder
     */
    public ImageBuilder size(double width, double height) {
        this.width = width;
        this.height = height;
        return this;
    }

    /**
     * Applies a uniform image scale when explicit width and height are omitted.
     *
     * @param scale scale factor
     * @return this builder
     */
    public ImageBuilder scale(double scale) {
        this.scale = scale;
        return this;
    }

    /**
     * Sets the image bounds and preserves aspect ratio by default.
     *
     * @param width  maximum drawing width in points
     * @param height maximum drawing height in points
     * @return this builder
     */
    public ImageBuilder fitToBounds(double width, double height) {
        this.width = width;
        this.height = height;
        this.fitMode = DocumentImageFitMode.CONTAIN;
        return this;
    }

    /**
     * Sets how the image is drawn inside explicit bounds.
     *
     * @param fitMode image fit mode
     * @return this builder
     */
    public ImageBuilder fitMode(DocumentImageFitMode fitMode) {
        this.fitMode = fitMode == null ? DocumentImageFitMode.STRETCH : fitMode;
        return this;
    }

    /**
     * Attaches image-level link metadata.
     *
     * @param linkOptions link metadata
     * @return this builder
     */
    public ImageBuilder link(DocumentLinkOptions linkOptions) {
        this.linkTarget = linkOptions == null ? null : new ExternalLinkTarget(linkOptions);
        return this;
    }

    /**
     * Attaches an image-level link target (external URI or internal anchor).
     *
     * @param linkTarget link target, or {@code null} to clear
     * @return this builder
     * @since 1.9.0
     */
    public ImageBuilder linkTarget(DocumentLinkTarget linkTarget) {
        this.linkTarget = linkTarget;
        return this;
    }

    /**
     * Makes the image an internal link to a named {@code anchor(...)} elsewhere
     * in the document.
     *
     * @param anchor target anchor name
     * @return this builder
     * @throws IllegalArgumentException if {@code anchor} is blank
     * @since 1.9.0
     */
    public ImageBuilder linkTo(String anchor) {
        this.linkTarget = new InternalLinkTarget(anchor);
        return this;
    }

    /**
     * Declares a named in-document navigation anchor at this image's top-left.
     *
     * @param anchor anchor name, or {@code null}/blank to clear
     * @return this builder
     * @since 1.9.0
     */
    public ImageBuilder anchor(String anchor) {
        this.anchor = anchor == null || anchor.isBlank() ? null : anchor.trim();
        return this;
    }

    /**
     * Attaches image-level bookmark metadata.
     *
     * @param bookmarkOptions bookmark metadata
     * @return this builder
     */
    public ImageBuilder bookmark(DocumentBookmarkOptions bookmarkOptions) {
        this.bookmarkOptions = bookmarkOptions;
        return this;
    }

    /**
     * Sets image padding with the public canonical spacing value.
     *
     * @param padding padding in points
     * @return this builder
     */
    public ImageBuilder padding(DocumentInsets padding) {
        this.padding = padding == null ? DocumentInsets.zero() : padding;
        return this;
    }

    /**
     * Sets image margin with the public canonical spacing value.
     *
     * @param margin margin in points
     * @return this builder
     */
    public ImageBuilder margin(DocumentInsets margin) {
        this.margin = margin == null ? DocumentInsets.zero() : margin;
        return this;
    }

    /**
     * Sets the render-time affine transform (rotation around the placement
     * centre and/or scaling).
     */
    @Override
    public ImageBuilder transform(DocumentTransform transform) {
        this.transform = transform == null ? DocumentTransform.NONE : transform;
        return this;
    }

    @Override
    public DocumentTransform currentTransform() {
        return transform;
    }

    /**
     * Builds the semantic image node.
     *
     * @return image node
     */
    public ImageNode build() {
        return new ImageNode(
                name,
                Objects.requireNonNull(imageData, "imageData"),
                width,
                height,
                scale,
                fitMode,
                linkTarget,
                bookmarkOptions,
                padding,
                margin,
                transform,
                anchor);
    }
}