# cherry-box

> A node-canvas package filled with utilities, manage text boxes easily and more

Latest version **1.4.0** (published 2022-07-22) · ISC license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install cherry-box
pnpm add cherry-box
yarn add cherry-box
bun add cherry-box
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2022-07-22 |
| First published | 2022-04-17 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 14.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | CheryX |
| Maintainers | cheryx |
| Keywords | canvas, textbox |

## Links

- npm: https://www.npmjs.com/package/cherry-box
- Repository: https://github.com/CheryX/cherry-box
- Homepage: https://github.com/CheryX/cherry-box#readme
- Issues: https://github.com/CheryX/cherry-box/issues
- npm.io page: https://npm.io/package/cherry-box

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 1.4.0 (latest) — 2022-07-22
- 1.3.0 — 2022-05-14
- 1.2.3 — 2022-05-11
- 1.2.1 — 2022-04-30
- 1.2.0 — 2022-04-30
- 1.1.1 — 2022-04-25
- 1.1.0 — 2022-04-19
- 1.0.2 — 2022-04-17
- 1.0.1 — 2022-04-17
- 1.0.0 — 2022-04-17

## README

# About

cherry-box is a [Node.js](https://nodejs.org/en/about/) package filled with utilities, which are useful for working with [node-canvas](https://github.com/Automattic/node-canvas).

# Example usage

```js
const cb = require("cherry-box")
const Canvas = require("canvas")
const fs = require("fs");

let canvas = Canvas.createCanvas(1000, 200);
let ctx = canvas.getContext('2d');

let text = [
    {
        text: "I like cookies!",
        color: "#ffffff",
        font: "monospace",
        modifier: "bold",
    }
]
cb.textBox(ctx, 0, 0, 1000, 200, text, 200, [1, 1]);

// Save canvas to file
let out = fs.createWriteStream("./out.png");
let stream = canvas.createPNGStream();
stream.pipe(out); 
```

Using modules:

```js
import { textBox } from "cherry-box";
import { createCanvas } from "canvas";
import fs from "fs";

let canvas = Canvas.createCanvas(1000, 200);
let ctx = canvas.getContext('2d');

let text = [
    {
        text: "I like cookies!",
        color: "#ffffff",
        font: "monospace",
        modifier: "bold",
    }
]
textBox(ctx, 0, 0, 1000, 200, text, 200, [1, 1]);

// Save canvas to file
let out = fs.createWriteStream("./out.png");
let stream = canvas.createPNGStream();
stream.pipe(out); 
```

# Using Typescript

When using textObject you also need to import `TextObject`

```ts
import { textObject } from "cherry-box";

...

let text: TextObject = [
    {
        text: "I like cookies!",
        color: "#ffffff",
        font: "monospace",
        modifier: "bold",
    }
]

...
```

# Documentation

## Popular functions

* [textBox](#textBox) - Align the text to specified width and height, adjust the size of the font so it fits.
* [textSchema](#textSchema) - An easy way to specify text color, font, shadow and more into a JSON object.

## TextObject
TextObject is made of multiple objects. These objects accepts the following values:

name | description | example | type | required
--- | --- | --- | --- | ---
text | Text to be displayed | `Hello world` | string | true
font | Font of the text | `Arial` | string | true
color | Color of the text | `#FFFFFF` | string | true
modifier | Modifier of the text | `bold` | string | false
shadow | Shadow of the text | | object| false

### Shadow schema
Shadow is a JSON object with the following values:

> `x` and `y` offsets are relative to the text size. For example use `x: 10, y: 10`

name | description | example | type | required
--- | --- | --- | --- | ---
color | Color of the shadow | `#FFFFFF` | string | true
blur | Blur of the shadow | `5` | number | true
offset | X and Y offset of the shadow | `[10, 5]` | array | true

Example text schema:
```js
[
    {
        text: "I like cookies!",
        color: "#ff8800",
        shadow: {
            offset: [10, 10], blur: 5, color: "red"
        },
        font: "Arial",
        modifier: "bold"
    }
]
```

## textBox

textBox is an easy way to align your text, decrease font size to fit in an area and more.
### textBox Schema

name | description | example | type | required
--- | --- | --- | --- | ---
ctx | Canvas context | | CanvasRenderingContext2D | true
x | X coordinate of the text box | `0` | number | true
y | Y coordinate of the text box | `0` | number | true
width | Width of the text box | `100` | number | true
height | Height of the text box | `100` | number | true
text | Text to be displayed in the text box | | TextObject | true
fontSize | Maximum font size of the text | `100` | number | true
align | Align of the text | `[1,1]` | array | true

### Align values

1. Horizontal: left `0`, center `1`, right `2`
2. Vertical: top `0`, middle `1`, bottom `2`

Example: `[1,1]`

Example use of textBox in your code: 
```js
textBox(ctx, 0, 0, canvas.width, canvas.height-20, upperText, 80, [2,1]);
```

## wrapText

wrapText is a function similar to textBox, but it doesn't just align the text. It also wraps the text to fit in the specified width.

### wrapText Schema

name | description | example | type | required
--- | --- | --- | --- | ---
ctx | Canvas context | | CanvasRenderingContext2D | true
x | X coordinate of the text box | `0` | number | true
y | Y coordinate of the text box | `0` | number | true
width | Width of the text box | `100` | number | true
text | Text to be displayed in the text box | | TextObject | true
fontSize | Maximum font size of the text | `100` | number | true
align | Align of the text | `3` | number | true

### Align values

* left `0`
* center `1`
* right `2`
* justify `3`

Example use of `wrapText` in your code: 
```js
wrapText(ctx, 0, 0, canvas.width, text, 20, 3);
```

---
_Source: https://npm.io/package/cherry-box · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._