add v2 documentation

Author: g-harel

CHANGELOG.md

@@ -1,33 +1,33 @@
 # 1.1.0
 
-- Add support for editable output
+-   Add support for editable output
 
 # 1.0.5
 
-- Fix assets in README on npmjs.com
+-   Fix assets in README on npmjs.com
 
 # 1.0.4
 
-- Use snapshot tests to verify consistency
-- Ignore unnecessary files in npm tarball
-- Output sourcemap file
-- Add project logo
-- README content updates
+-   Use snapshot tests to verify consistency
+-   Ignore unnecessary files in npm tarball
+-   Output sourcemap file
+-   Add project logo
+-   README content updates
 
 # 1.0.3
 
-- Add link to demo page in the README
+-   Add link to demo page in the README
 
 # 1.0.2
 
-- Make transpiled output minified
-- Minor changes to the README
+-   Make transpiled output minified
+-   Minor changes to the README
 
 # 1.0.1
 
-- Remove accidental dependency
-- Minor changes to the README
+-   Remove accidental dependency
+-   Minor changes to the README
 
 # 1.0.0
 
-- Initial release
+-   Initial release

README.md

@@ -1,7 +1,6 @@
 <!--
 
 TODO rewrite v1 docs in separate doc
-TODO update docs for v2
 
  -->
 
@@ -46,23 +45,22 @@ _Options are **not** [sanitized](https://en.wikipedia.org/wiki/HTML_sanitization
 
 #### Required
 
-Name           | Type       | Description
--------------- | ---------- | ---------------------------------------------
-`size`         | `number`   | Bounding box dimensions (in pixels)
-`complexity`   | `number`   | Blob complexity (number of points)
-`contrast`     | `number`   | Blob contrast (randomness of point position)
-
+| Name         | Type     | Description                                  |
+| ------------ | -------- | -------------------------------------------- |
+| `size`       | `number` | Bounding box dimensions (in pixels)          |
+| `complexity` | `number` | Blob complexity (number of points)           |
+| `contrast`   | `number` | Blob contrast (randomness of point position) |
 
 #### Optional
 
-Name           | Type       | Default    | Description
--------------- | ---------- | ---------- | -------------------------------------
-`color`        | `string?`  | `"none"`   | Fill color
-`stroke`       | `object?`  | `...`      | Stroke options
-`stroke.color` | `string`   | `"none"`   | Stroke color
-`stroke.width` | `number`   | `0`        | Stroke width (in pixels)
-`seed`         | `string?`  | _`random`_ | Value to seed random number generator
-`guides`       | `boolean?` | `false`    | Render points, handles and stroke
+| Name           | Type       | Default    | Description                           |
+| -------------- | ---------- | ---------- | ------------------------------------- |
+| `color`        | `string?`  | `"none"`   | Fill color                            |
+| `stroke`       | `object?`  | `...`      | Stroke options                        |
+| `stroke.color` | `string`   | `"none"`   | Stroke color                          |
+| `stroke.width` | `number`   | `0`        | Stroke width (in pixels)              |
+| `seed`         | `string?`  | _`random`_ | Value to seed random number generator |
+| `guides`       | `boolean?` | `false`    | Render points, handles and stroke     |
 
 _Either `stroke` or `color` must be defined._
 
@@ -72,16 +70,16 @@ _Guides will use stroke color and width if defined. Otherwise, they default to `
 
 ```typescript
 const options = {
-   size: 600,
-   complexity: 0.2,
-   contrast: 0.4,
-   color: "#ec576b",
-   stroke: {
-      width: 0,
-      color: "black",
-   },
-   guides: false,
-   seed: "1234",
+    size: 600,
+    complexity: 0.2,
+    contrast: 0.4,
+    color: "#ec576b",
+    stroke: {
+        width: 0,
+        color: "black",
+    },
+    guides: false,
+    seed: "1234",
 };
 ```
 

README.v2.md

@@ -0,0 +1,109 @@
+<a href="https://blobs.dev">
+    <img align="left" width="360" height="300" src="./assets/logo-color.svg?sanitize=true">
+</a>
+
+<br>
+<br>
+
+[![](https://img.shields.io/npm/v/blobs.svg)](https://www.npmjs.com/package/blobs)
+
+```ts
+// $ npm install blobs
+import * as blobs2 from "blobs/v2";
+```
+
+```html
+<script src="https://unpkg.com/blobs/v2"></script>
+```
+
+<br>
+<br>
+<br>
+<br>
+
+## SVG Path
+
+```js
+const svgPath = blobs2.svg({
+    seed: Date.now(),
+    extraPoints: 8,
+    randomness: 4,
+    size: 256,
+});
+doSomething(svgPath);
+```
+
+## SVG
+
+```js
+const svgString = blobs2.svg(
+    {
+        seed: Date.now(),
+        extraPoints: 8,
+        randomness: 4,
+        size: 256,
+    },
+    {
+        fill: "white", // 🚨 NOT SANITIZED
+        stroke: "black", // 🚨 NOT SANITIZED
+        strokeWidth: 4,
+    },
+);
+container.innerHTML = svgString;
+```
+
+## Canvas
+
+```js
+const path = blobs2.canvas(
+    {
+        seed: Date.now(),
+        extraPoints: 16,
+        randomness: 2,
+        size: 128,
+    },
+    {
+        offsetX: 16,
+        offsetY: 32,
+    },
+);
+ctx.stroke(path);
+```
+
+## Complete API
+
+```ts
+export interface BlobOptions {
+    // A given seed will always produce the same blob.
+    // Use `Date.now()` for pseudorandom behavior.
+    seed: string | number;
+    // Actual number of points will be `3 + extraPoints`.
+    extraPoints: number;
+    // Increases the amount of variation in point position.
+    randomness: number;
+    // Size of bounding box.
+    size: number;
+}
+export interface CanvasOptions {
+    // Coordinates of top-left corner of blob.
+    offsetX?: number;
+    offsetY?: number;
+}
+export interface SvgOptions {
+    fill?: string; // Default: "#ec576b".
+    stroke?: string; // Default: "none".
+    strokeWidth?: number; // Default: 0.
+}
+export const canvas: (blobOptions: BlobOptions, canvasOptions?: CanvasOptions) => Path2D;
+export const svg: (blobOptions: BlobOptions, svgOptions?: SvgOptions) => string;
+export const svgPath: (blobOptions: BlobOptions) => string;
+```
+
+## License
+
+[MIT](./LICENSE)
+
+<p align="center">
+    <br><br>
+    <img width="100" src="./assets/logo-grey.svg?sanitize=true" />
+</p>

package.json

@@ -11,7 +11,7 @@
     "postpublish": "npm run clean",
     "build": "npm run clean && rollup -c rollup.config.js",
     "clean": "trash '**/*.js' '**/*.js.map' '**/*.d.ts' '!**/node_modules/**/*' '!rollup.config.js'",
-    "fmt": "prettier --list-different --write --ignore-path .gitignore '**/*.{js,ts}'",
+    "fmt": "prettier --list-different --write --ignore-path .gitignore '**/*.{js,ts,md}'",
     "anim": "parcel internal/animate/testing/index.html --open",
     "test": "jest"
   },

public/blobs.ts

@@ -30,7 +30,7 @@ const typeCheck = (name: string, val: any, expected: string[]) => {
     }
 };
 
-export const raw = (blobOptions: BlobOptions): Point[] => {
+const raw = (blobOptions: BlobOptions): Point[] => {
     const rgen = rand(String(blobOptions.seed));
 
     typeCheck("seed", blobOptions.seed, ["string", "number"]);
@@ -63,7 +63,7 @@ export const raw = (blobOptions: BlobOptions): Point[] => {
     });
 };
 
-export const canvas = (blobOptions: BlobOptions, canvasOptions: CanvasOptions): Path2D => {
+export const canvas = (blobOptions: BlobOptions, canvasOptions: CanvasOptions = {}): Path2D => {
     return renderPath2D(
         mapPoints(raw(blobOptions), ({curr}) => {
             curr.x += canvasOptions.offsetX || 0;
@@ -73,12 +73,12 @@ export const canvas = (blobOptions: BlobOptions, canvasOptions: CanvasOptions):
     );
 };
 
-export const svg = (blobOptions: BlobOptions, svgOptions: SvgOptions): string => {
+export const svg = (blobOptions: BlobOptions, svgOptions: SvgOptions = {}): string => {
     const path = svgPath(blobOptions);
     const size = Math.floor(blobOptions.size);
     const fill = svgOptions.fill === undefined ? "#ec576b" : svgOptions.fill;
     const stroke = svgOptions.stroke === undefined ? "none" : svgOptions.stroke;
-    const strokeWidth = svgOptions.strokeWidth === undefined ? 1 : svgOptions.strokeWidth;
+    const strokeWidth = svgOptions.strokeWidth === undefined ? 0 : svgOptions.strokeWidth;
     return `
 <svg width="${size}" height="${size}" viewBox="0 0 ${size} ${size}" xmlns="http://www.w3.org/2000/svg">
     <path stroke="${stroke}" stroke-width="${strokeWidth}" fill="${fill}" d="${path}"/>