xpict 0.4.1 → 1.0.1

package/README.md

@@ -1,35 +1,290 @@
 # Xpict
 
-Xpict é uma biblioteca para a geração de imagens padronizadas a partir de modelos declarativos.
+**Xpict** is a library built on top of `@napi-rs/canvas` designed to create templates for generating standardized images with data—which can be static or dynamic. It features support for conditional rendering, runtime-generated position axes, and dynamic text.
 
-## Instalação 
+## 📦 Installation
+
+Installation is straightforward; just use your preferred package manager. Here is an example using NPM:
 
 ```bash
-npm install xpict
+npm i xpict
+
+```
+
+## 🚀 Usage
+
+<a href="https://www.buymeacoffee.com/marcuth">
+  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="200">
+</a>
+
+### Template
+
+The foundation for creating images in Xpict is the `Template`. This is where you define your image layers and encapsulate all assembly logic. There are two ways to define an initial `Template`.
+
+**Using the config property (width, height, and fill):**
+
+```ts
+import xpict from "xpict"
+
+type RenderData = {} // Your data structure used in layer logic
+
+const template = xpict.template<RenderData>({
+    config: {
+        width: 1280,
+        height: 720,
+        fill: "#020817" // optional
+    },
+    layers: [...]
+})
+
+```
+
+**Using an image as a background:**
+
+```ts
+import xpict from "xpict"
+
+type RenderData = {} // Your data structure used in layer logic
+
+const template = xpict.template<RenderData>({
+    imagePath: "path/to/background.png",
+    layers: [...]
+})
+
+```
+
+---
+
+### Layers
+
+Layers are another fundamental component of Xpict. They act as building blocks—sometimes functional, sometimes just wrappers—that organize code declaratively and provide instructions to `@napi-rs/canvas` on how to perform operations within our canvas context.
+
+All axes (x, y) across all layer types support dynamic values:
+
+```ts
+x: ({ data, index /* index is useful if you are inside a `RepeatLayer` loop */ }) => index * 110,
+y: ({ data, index /* index is useful if you are inside a `RepeatLayer` loop */ }) => index * 50,
+
+```
+
+Every layer also supports conditional rendering via the `when` property. If not defined, the layer renders by default.
+
+```ts
+when: ({ data, index }) => false // must return a boolean
+
 ```
 
-## Uso
+#### TextLayer
 
-```typescript
+To insert text into the canvas, use `TextLayer`:
+
+```ts
 import xpict from "xpict"
 
-const template = xpict.template({ // para criar um template
+const myFont = xpict.utils.font({
+    name: "curse-casual",
+    filePath: "path/to/font.ttf",
+    color: "#ffffff",
+})
+
+type RenderData = {} 
+
+const template = xpict.template<RenderData>({
     config: {
-        width: 100, // para definir a largura da imagem
-        height: 100, // para definir a altura da imagem
-        fill: "#fff" // para definir a cor de fundo da imagem
+        width: 1280,
+        height: 720,
+        fill: "#020817"
     },
     layers: [
-        xpict.rectangle({...}), // para inserir um retângulo
-        xpict.circle({...}), // para inserir um círculo
-        xpict.line({...}), // para inserir uma linha
-        xpict.text({...}), // para inserir texto
-        xpict.image({...}), // para inserir uma imagem
-        xpict.repeat({...}), // para repetir um tipo de camada com base em itens de um array
-        xpict.group({...}) // para agrupar camadas que compoem algo maior
+        xpict.text({
+            x: 640,
+            y: 360,
+            font: myFont({
+                size: 60,
+                color: "#ffffff" // optional, as it was previously defined in font config
+            }),
+            text: "Hello World",
+            align: "center", // optional
+            baseline: "middle", // optional
+            stroke: {
+                width: 4,
+                fill: "#000000"
+            } // optional
+        })
     ]
 })
 
-const image = await template.render({...}) // para renderizar a imagem passando os dados de entrada
 ```
 
+**Using dynamic text:**
+
+```ts
+text: ({ data, index }) => data.myText
+
+```
+
+---
+
+#### ImageLayer
+
+To insert images into the canvas, use `ImageLayer`:
+
+```ts
+import xpict from "xpict"
+
+const template = xpict.template<RenderData>({
+    config: {
+        width: 1280,
+        height: 720,
+        fill: "#020817"
+    },
+    layers: [
+        xpict.image({
+            src: "path/to/image.png",
+            x: 0,
+            y: 0,
+        }),
+    ]
+})
+
+```
+
+**Using a dynamic image:**
+
+```ts
+src: ({ data, index }) => data.myImagePath
+
+```
+
+---
+
+#### RectangleLayer
+
+To insert rectangles into the canvas, use `RectangleLayer`:
+
+```ts
+xpict.rectangle({
+    x: 0,
+    y: 0,
+    fill: "#ffffff",
+    width: 150,
+    height: 50,
+    borderRadius: 5 // optional
+})
+
+```
+
+---
+
+#### CircleLayer
+
+To insert circles into the canvas, use `CircleLayer`:
+
+```ts
+xpict.circle({
+    x: 0,
+    y: 0,
+    fill: "#ffffff",
+    radius: 50,
+})
+
+```
+
+---
+
+#### LineLayer
+
+To insert lines into the canvas, use `LineLayer`:
+
+```ts
+xpict.line({
+    from: { x: 0, y: 0 },
+    to: { x: 0, y: 50 },
+    color: "#ffffff",
+    width: 1
+})
+
+```
+
+---
+
+#### GroupLayer
+
+If you want to group layers that share a common context, you can use `GroupLayer` to keep your code organized and apply an offset if desired:
+
+```ts
+xpict.group({
+    x: 50,
+    y: 50,
+    layers: [...]
+})
+
+```
+
+---
+
+#### RepeatLayer
+
+If you need to handle arrays to generate layers, use `RepeatLayer` to organize your code and loop logic:
+
+```ts
+xpict.repeat({
+    each: ({ data }) => data.images,
+    x: ({ index }) => index * 50,
+    y: ({ index }) => index * 50,
+    layer: (image, { index, length }) => xpict.image({
+        x: 0,
+        y: 0,
+        src: image
+    })
+})
+
+```
+
+---
+
+### Image Transformations and Effects
+
+If you want to manipulate an image or apply effects, you can do so using the `transform` property of `ImageLayer`, or via `flipX`, `flipY`, and `rotate`.
+
+**Using transform:**
+
+```ts
+xpict.image({
+    x: 0,
+    y: 0,
+    src: "...",
+    transform: [
+        xpict.effects.blur(2.5),
+        ({ canvas, ctx, data, index }) => {
+            // manipulate the `ctx` directly here to apply custom logic
+        }
+    ]
+})
+
+```
+
+---
+
+## 🧪 Tests (Not included yet, CONTRIBUTE! :D)
+
+Automated tests are located in `__tests__`. To run them:
+
+```bash
+npm run test
+
+```
+
+## 🤝 Contributing
+
+Want to contribute? Follow these steps:
+
+1. Fork the repository.
+2. Create a new branch (`git checkout -b feature-new`).
+3. Commit your changes (`git commit -m 'Add new feature'`).
+4. Push to the branch (`git push origin feature-new`).
+5. Open a Pull Request.
+
+## 📝 License
+
+This project is licensed under the MIT License.

package/dist/effects/blur.d.ts

@@ -1,3 +1,2 @@
-import sharp from "sharp";
-import { ImageTransformFunction } from "../layers";
-export declare function blurEffect(sigma: number | boolean | sharp.BlurOptions): ImageTransformFunction<any>;
+import { TransformOptions } from "../layers/image-layer";
+export declare function blur<Data>(radius: number): ({ canvas, ctx }: TransformOptions<Data>) => void;

package/dist/effects/blur.js

@@ -1,8 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.blurEffect = blurEffect;
-function blurEffect(sigma) {
-    return ({ image }) => {
-        return image.blur(sigma);
+exports.blur = blur;
+const canvas_1 = require("@napi-rs/canvas");
+function blur(radius) {
+    return ({ canvas, ctx }) => {
+        if (radius <= 0)
+            return;
+        const tempCanvas = (0, canvas_1.createCanvas)(canvas.width, canvas.height);
+        const tempCtx = tempCanvas.getContext("2d");
+        tempCtx.drawImage(canvas, 0, 0);
+        ctx.save();
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        ctx.filter = `blur(${radius}px)`;
+        ctx.drawImage(tempCanvas, 0, 0);
+        ctx.restore();
     };
 }

package/dist/effects/box-blur.d.ts

@@ -0,0 +1,2 @@
+import { TransformOptions } from "../layers/image-layer";
+export declare function boxBlur<Data>(radius: number): ({ canvas, ctx }: TransformOptions<Data>) => void;

package/dist/effects/box-blur.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boxBlur = boxBlur;
+function boxBlur(radius) {
+    return ({ canvas, ctx }) => {
+        const r = Math.floor(radius);
+        if (r <= 0)
+            return;
+        const width = canvas.width;
+        const height = canvas.height;
+        const imageData = ctx.getImageData(0, 0, width, height);
+        const data = imageData.data;
+        const sourceData = new Uint8ClampedArray(data);
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                let red = 0, green = 0, blue = 0, alpha = 0;
+                let count = 0;
+                for (let i = -r; i <= r; i++) {
+                    const nx = x + i;
+                    if (nx >= 0 && nx < width) {
+                        const sourceIndex = (y * width + nx) * 4;
+                        red += sourceData[sourceIndex];
+                        green += sourceData[sourceIndex + 1];
+                        blue += sourceData[sourceIndex + 2];
+                        alpha += sourceData[sourceIndex + 3];
+                        count++;
+                    }
+                }
+                const targetIndex = (y * width + x) * 4;
+                data[targetIndex] = red / count;
+                data[targetIndex + 1] = green / count;
+                data[targetIndex + 2] = blue / count;
+                data[targetIndex + 3] = alpha / count;
+            }
+        }
+        sourceData.set(data);
+        for (let x = 0; x < width; x++) {
+            for (let y = 0; y < height; y++) {
+                let red = 0, green = 0, blue = 0, alpha = 0;
+                let count = 0;
+                for (let i = -r; i <= r; i++) {
+                    const ny = y + i;
+                    if (ny >= 0 && ny < height) {
+                        const sourceIndex = (ny * width + x) * 4;
+                        red += sourceData[sourceIndex];
+                        green += sourceData[sourceIndex + 1];
+                        blue += sourceData[sourceIndex + 2];
+                        alpha += sourceData[sourceIndex + 3];
+                        count++;
+                    }
+                }
+                const targetIndex = (y * width + x) * 4;
+                data[targetIndex] = red / count;
+                data[targetIndex + 1] = green / count;
+                data[targetIndex + 2] = blue / count;
+                data[targetIndex + 3] = alpha / count;
+            }
+        }
+        ctx.putImageData(imageData, 0, 0);
+    };
+}

package/dist/effects/grayscale.d.ts

@@ -1,2 +1,2 @@
-import { ImageTransformFunction } from "../layers";
-export declare function grayscaleEffect(): ImageTransformFunction<any>;
+import { TransformOptions } from "../layers/image-layer";
+export declare function grayscale<Data>(amount?: number): ({ canvas, ctx }: TransformOptions<Data>) => void;

package/dist/effects/grayscale.js

@@ -1,8 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.grayscaleEffect = grayscaleEffect;
-function grayscaleEffect() {
-    return ({ image }) => {
-        return image.grayscale();
+exports.grayscale = grayscale;
+const canvas_1 = require("@napi-rs/canvas");
+function grayscale(amount = 100) {
+    return ({ canvas, ctx }) => {
+        if (amount <= 0)
+            return;
+        const tempCanvas = (0, canvas_1.createCanvas)(canvas.width, canvas.height);
+        const tempCtx = tempCanvas.getContext("2d");
+        tempCtx.drawImage(canvas, 0, 0);
+        ctx.save();
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        ctx.filter = `grayscale(${amount}%)`;
+        ctx.drawImage(tempCanvas, 0, 0);
+        ctx.restore();
     };
 }

package/dist/effects/index.d.ts

@@ -1,3 +1,3 @@
 export * from "./blur";
 export * from "./grayscale";
-export * from "./negative";
+export * from "./box-blur";

package/dist/effects/index.js

@@ -16,4 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./blur"), exports);
 __exportStar(require("./grayscale"), exports);
-__exportStar(require("./negative"), exports);
+__exportStar(require("./box-blur"), exports);

package/dist/enums/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./text-align";
+export * from "./text-baseline";

package/dist/enums/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./text-align"), exports);
+__exportStar(require("./text-baseline"), exports);

package/dist/enums/text-align.d.ts

@@ -0,0 +1,5 @@
+export declare enum TextAlign {
+    Left = "left",
+    Center = "center",
+    Right = "right"
+}

package/dist/enums/text-align.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TextAlign = void 0;
+var TextAlign;
+(function (TextAlign) {
+    TextAlign["Left"] = "left";
+    TextAlign["Center"] = "center";
+    TextAlign["Right"] = "right";
+})(TextAlign || (exports.TextAlign = TextAlign = {}));

package/dist/enums/text-baseline.d.ts

@@ -0,0 +1,8 @@
+export declare enum TextBaseline {
+    Top = "top",
+    Hanging = "hanging",
+    Middle = "middle",
+    Alphabetic = "alphabetic",
+    Ideographic = "ideographic",
+    Bottom = "bottom"
+}

package/dist/enums/text-baseline.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TextBaseline = void 0;
+var TextBaseline;
+(function (TextBaseline) {
+    TextBaseline["Top"] = "top";
+    TextBaseline["Hanging"] = "hanging";
+    TextBaseline["Middle"] = "middle";
+    TextBaseline["Alphabetic"] = "alphabetic";
+    TextBaseline["Ideographic"] = "ideographic";
+    TextBaseline["Bottom"] = "bottom";
+})(TextBaseline || (exports.TextBaseline = TextBaseline = {}));

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { GroupLayer, RepeatLayer, GroupLayerOptions, ImageLayer, ImageLayerOptions, LineLayer, LineLayerOptions, RectangleLayer, RectangleLayerOptions, RepeatLayerOptions, TextLayer, TextLayerOptions, CircleLayerOptions, CircleLayer } from "./layers";
-import { negativeEffect, blurEffect, grayscaleEffect } from "./effects";
 import { Template, InputTemplateOptions } from "./template";
-export * from "./layers";
+import * as utils from "./utils";
+import * as effects from "./effects";
 export * from "./effects";
+export * from "./layers";
 export * from "./template";
 export * from "./utils";
 export * from "./error";
@@ -15,10 +16,7 @@ declare const xpict: {
     group<Data>(options: GroupLayerOptions<Data>): GroupLayer<Data>;
     line<Data>(options: LineLayerOptions<Data>): LineLayer<Data>;
     template<Data>(options: InputTemplateOptions<Data>): Template<Data>;
-    effects: {
-        negative: typeof negativeEffect;
-        blur: typeof blurEffect;
-        grayscale: typeof grayscaleEffect;
-    };
+    effects: typeof effects;
+    utils: typeof utils;
 };
 export default xpict;

package/dist/index.js

@@ -10,15 +10,38 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
 }));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const layers_1 = require("./layers");
-const effects_1 = require("./effects");
 const template_1 = require("./template");
-__exportStar(require("./layers"), exports);
+const utils = __importStar(require("./utils"));
+const effects = __importStar(require("./effects"));
 __exportStar(require("./effects"), exports);
+__exportStar(require("./layers"), exports);
 __exportStar(require("./template"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./error"), exports);
@@ -47,10 +70,7 @@ const xpict = {
     template(options) {
         return new template_1.Template(options);
     },
-    effects: {
-        negative: effects_1.negativeEffect,
-        blur: effects_1.blurEffect,
-        grayscale: effects_1.grayscaleEffect,
-    },
+    effects: effects,
+    utils: utils,
 };
 exports.default = xpict;

package/dist/layers/circle-layer.d.ts

@@ -10,5 +10,5 @@ export type CircleLayerOptions<Data> = {
 export declare class CircleLayer<Data> extends Layer<Data> {
     private readonly options;
     constructor(options: CircleLayerOptions<Data>);
-    render({ context: ctx, data, index, templateConfig }: RenderOptions<Data>): Promise<void>;
+    render({ context: renderContext, data, index, templateConfig }: RenderOptions<Data>): Promise<void>;
 }

package/dist/layers/circle-layer.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CircleLayer = void 0;
-const canvas_1 = require("canvas");
 const layer_1 = require("./layer");
 const resolve_axis_1 = require("../utils/resolve-axis");
 class CircleLayer extends layer_1.Layer {
@@ -9,41 +8,28 @@ class CircleLayer extends layer_1.Layer {
         super(options.when);
         this.options = options;
     }
-    async render({ context: ctx, data, index = 0, templateConfig }) {
-        const image = ctx.image;
-        const metadata = await image.metadata();
-        const canvasWidth = metadata.width;
-        const canvasHeight = metadata.height;
-        const x = ctx.offsetX +
+    async render({ context: renderContext, data, index = 0, templateConfig }) {
+        const x = renderContext.offsetX +
             (0, resolve_axis_1.resolveAxis)({
                 axis: this.options.x,
                 data: data,
                 index: index,
-                templateConfig: templateConfig,
+                templateSize: templateConfig,
             });
-        const y = ctx.offsetY +
+        const y = renderContext.offsetY +
             (0, resolve_axis_1.resolveAxis)({
                 axis: this.options.y,
                 data: data,
                 index: index,
-                templateConfig: templateConfig,
+                templateSize: templateConfig,
             });
         const { radius, fill } = this.options;
-        const canvas = (0, canvas_1.createCanvas)(canvasWidth, canvasHeight);
-        const context = canvas.getContext("2d");
+        const context = renderContext.ctx;
         context.beginPath();
         context.arc(x, y, radius, 0, Math.PI * 2);
         context.closePath();
         context.fillStyle = fill;
         context.fill();
-        const circleBuffer = canvas.toBuffer();
-        ctx.image = image.composite([
-            {
-                input: circleBuffer,
-                top: 0,
-                left: 0,
-            },
-        ]);
     }
 }
 exports.CircleLayer = CircleLayer;