Skip to content

Commit 492633a

Browse files
g-harelg-harel
committed
Move old docs to legacy readme
1 parent 73eec58 commit 492633a

File tree

4 files changed

+178
-202
lines changed

4 files changed

+178
-202
lines changed

‎README.legacy.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
## Install
2+
3+
```ts
4+
// $ npm install blobs
5+
const blobs = require("blobs");
6+
```
7+
8+
```html
9+
<script src="https://unpkg.com/blobs"></script>
10+
```
11+
12+
## Usage
13+
14+
```typescript
15+
const svg = blobs(options);
16+
```
17+
18+
![](https://svgsaur.us?t=&w=5&h=32&b=fdcc56)![](https://svgsaur.us/?t=WARNING&w=103&h=32&s=16&y=21&x=12&b=feefcd&f=arial&o=b) ![](https://svgsaur.us?t=&w=1&h=48&)
19+
20+
_Options are **not** [sanitized](https://en.wikipedia.org/wiki/HTML_sanitization). Never trust raw user-submitted values in the options._
21+
22+
## Options
23+
24+
#### Required
25+
26+
| Name | Type | Description |
27+
| ------------ | -------- | -------------------------------------------- |
28+
| `size` | `number` | Bounding box dimensions (in pixels) |
29+
| `complexity` | `number` | Blob complexity (number of points) |
30+
| `contrast` | `number` | Blob contrast (randomness of point position) |
31+
32+
#### Optional
33+
34+
| Name | Type | Default | Description |
35+
| -------------- | ---------- | ---------- | ------------------------------------- |
36+
| `color` | `string?` | `"none"` | Fill color |
37+
| `stroke` | `object?` | `...` | Stroke options |
38+
| `stroke.color` | `string` | `"none"` | Stroke color |
39+
| `stroke.width` | `number` | `0` | Stroke width (in pixels) |
40+
| `seed` | `string?` | _`random`_ | Value to seed random number generator |
41+
| `guides` | `boolean?` | `false` | Render points, handles and stroke |
42+
43+
_Either `stroke` or `color` must be defined._
44+
45+
_Guides will use stroke color and width if defined. Otherwise, they default to `black` stroke with width of `1`._
46+
47+
##### Example Options Object
48+
49+
```typescript
50+
const options = {
51+
size: 600,
52+
complexity: 0.2,
53+
contrast: 0.4,
54+
color: "#ec576b",
55+
stroke: {
56+
width: 0,
57+
color: "black",
58+
},
59+
guides: false,
60+
seed: "1234",
61+
};
62+
```
63+
64+
## Advanced
65+
66+
If you need to edit the output svg for your use case, blobs also allows for _editable_ output.
67+
68+
```typescript
69+
const editableSvg = blobs.editable(options);
70+
```
71+
72+
The output of this function is a data structure that represents a nested svg document. This structure can be changed and rendered to a string using its `render` function.
73+
74+
```typescript
75+
editableSvg.attributes.width = 1000;
76+
const svg = editableSvg.render();
77+
```
78+
79+
Utilities to create nodes in the editable output can be imported from `blobs/editable`.
80+
81+
```typescript
82+
const xmlChild = blobs.xml("path");
83+
xmlChild.attributes.stroke = "red";
84+
// ...
85+
editableSvg.children.push(xmlChild);
86+
```

‎README.md‎

Lines changed: 86 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,108 @@
1-
<!--
1+
<p align="center">
2+
<a href="https://github.com/g-harel/blobs/README.legacy.md"><b>Legacy documentation</b></a>
3+
</p>
24

3-
TODO rewrite v1 docs in separate doc
5+
<br>
46

5-
-->
7+
<a href="https://blobs.dev">
8+
<img align="left" width="360" height="300" src="./assets/logo-color.svg?sanitize=true">
9+
</a>
610

7-
<p align="center">
8-
<a href="https://blobs.dev">
9-
<img width="460" height="300" src="./assets/logo-color.svg?sanitize=true">
10-
</a>
11-
<br>
12-
<a href="https://www.npmjs.com/package/blobs">
13-
<img src="https://img.shields.io/npm/v/blobs.svg">
14-
</a>
15-
<a href="https://bundlephobia.com/result?p=blobs">
16-
<img src="https://img.shields.io/bundlephobia/minzip/blobs.svg">
17-
</a>
18-
<br>
19-
<a href="https://blobs.dev">
20-
<img src="https://svgsaur.us/?c=0366d6&t=PLAYGROUND&o=b&s=23&w=170&y=38&h=46" />
21-
</a>
22-
</p>
11+
<br>
12+
<br>
2313

24-
## Install
14+
[![](https://img.shields.io/npm/v/blobs.svg)](https://www.npmjs.com/package/blobs)
2515

26-
```shell
27-
$ npm install blobs
16+
```ts
17+
// $ npm install blobs
18+
import * as blobs2 from "blobs/v2";
2819
```
2920

3021
```html
31-
<script src="https://unpkg.com/blobs"></script>
22+
<script src="https://unpkg.com/blobs/v2"></script>
3223
```
3324

34-
## Usage
35-
36-
```typescript
37-
const svg = blobs(options);
25+
<br>
26+
<br>
27+
<br>
28+
<br>
29+
30+
## SVG Path
31+
32+
```js
33+
const svgPath = blobs2.svg({
34+
seed: Date.now(),
35+
extraPoints: 8,
36+
randomness: 4,
37+
size: 256,
38+
});
39+
doSomething(svgPath);
3840
```
3941

40-
![](https://svgsaur.us?t=&w=5&h=32&b=fdcc56)![](https://svgsaur.us/?t=WARNING&w=103&h=32&s=16&y=21&x=12&b=feefcd&f=arial&o=b) ![](https://svgsaur.us?t=&w=1&h=48&)
41-
42-
_Options are **not** [sanitized](https://en.wikipedia.org/wiki/HTML_sanitization). Never trust raw user-submitted values in the options._
43-
44-
## Options
45-
46-
#### Required
47-
48-
| Name | Type | Description |
49-
| ------------ | -------- | -------------------------------------------- |
50-
| `size` | `number` | Bounding box dimensions (in pixels) |
51-
| `complexity` | `number` | Blob complexity (number of points) |
52-
| `contrast` | `number` | Blob contrast (randomness of point position) |
53-
54-
#### Optional
55-
56-
| Name | Type | Default | Description |
57-
| -------------- | ---------- | ---------- | ------------------------------------- |
58-
| `color` | `string?` | `"none"` | Fill color |
59-
| `stroke` | `object?` | `...` | Stroke options |
60-
| `stroke.color` | `string` | `"none"` | Stroke color |
61-
| `stroke.width` | `number` | `0` | Stroke width (in pixels) |
62-
| `seed` | `string?` | _`random`_ | Value to seed random number generator |
63-
| `guides` | `boolean?` | `false` | Render points, handles and stroke |
64-
65-
_Either `stroke` or `color` must be defined._
42+
## SVG
6643

67-
_Guides will use stroke color and width if defined. Otherwise, they default to `black` stroke with width of `1`._
68-
69-
##### Example Options Object
70-
71-
```typescript
72-
const options = {
73-
size: 600,
74-
complexity: 0.2,
75-
contrast: 0.4,
76-
color: "#ec576b",
77-
stroke: {
78-
width: 0,
79-
color: "black",
44+
```js
45+
const svgString = blobs2.svg(
46+
{
47+
seed: Date.now(),
48+
extraPoints: 8,
49+
randomness: 4,
50+
size: 256,
8051
},
81-
guides: false,
82-
seed: "1234",
83-
};
84-
```
85-
86-
## Advanced
87-
88-
If you need to edit the output svg for your use case, blobs also allows for _editable_ output.
89-
90-
```typescript
91-
const editableSvg = blobs.editable(options);
52+
{
53+
fill: "white", // 🚨 NOT SANITIZED
54+
stroke: "black", // 🚨 NOT SANITIZED
55+
strokeWidth: 4,
56+
},
57+
);
58+
container.innerHTML = svgString;
9259
```
9360

94-
The output of this function is a data structure that represents a nested svg document. This structure can be changed and rendered to a string using its `render` function.
61+
## Canvas
9562

96-
```typescript
97-
editableSvg.attributes.width = 1000;
98-
const svg = editableSvg.render();
63+
```js
64+
const path = blobs2.canvas(
65+
{
66+
seed: Date.now(),
67+
extraPoints: 16,
68+
randomness: 2,
69+
size: 128,
70+
},
71+
{
72+
offsetX: 16,
73+
offsetY: 32,
74+
},
75+
);
76+
ctx.stroke(path);
9977
```
10078

101-
Utilities to create nodes in the editable output can be imported from `blobs/editable`.
102-
103-
```typescript
104-
import {xml} from "blobs/editable";
105-
106-
const xmlChild = xml("path");
107-
xmlChild.attributes.stroke = "red";
108-
// ...
109-
editableSvg.children.push(xmlChild);
79+
## Complete API
80+
81+
```ts
82+
export interface BlobOptions {
83+
// A given seed will always produce the same blob.
84+
// Use `Date.now()` for pseudorandom behavior.
85+
seed: string | number;
86+
// Actual number of points will be `3 + extraPoints`.
87+
extraPoints: number;
88+
// Increases the amount of variation in point position.
89+
randomness: number;
90+
// Size of bounding box.
91+
size: number;
92+
}
93+
export interface CanvasOptions {
94+
// Coordinates of top-left corner of blob.
95+
offsetX?: number;
96+
offsetY?: number;
97+
}
98+
export interface SvgOptions {
99+
fill?: string; // Default: "#ec576b".
100+
stroke?: string; // Default: "none".
101+
strokeWidth?: number; // Default: 0.
102+
}
103+
export const canvas: (blobOptions: BlobOptions, canvasOptions?: CanvasOptions) => Path2D;
104+
export const svg: (blobOptions: BlobOptions, svgOptions?: SvgOptions) => string;
105+
export const svgPath: (blobOptions: BlobOptions) => string;
110106
```
111107

112108
## License

‎README.v2.md‎

Lines changed: 0 additions & 109 deletions
This file was deleted.

0 commit comments

Comments
 (0)