@pictogrammers/components 0.4.8 → 0.5.0

package/pg/inputPixelEditor/README.md

@@ -4,7 +4,10 @@ The `pg-input-pixel-editor` component is used to edit images. Tailored for pen o
 
 ```typescript
 import '@pictogrammers/components/pgInputPixelEditor';
-import { PgInputPixelEditor } from '@pictogrammers/components/pgInputPixelEditor';
+import PgInputPixelEditor, {
+  InputMode,
+  LayerType,
+} from '@pictogrammers/components/pgInputPixelEditor';
 ```
 
 ```html
@@ -23,10 +26,18 @@ import { PgInputPixelEditor } from '@pictogrammers/components/pgInputPixelEditor
 
 ## Events
 
-| Events     | Tested   | Description |
-| ---------- | -------- | ----------- |
-| `change`   |          | `{ detail: { value }` |
-| `input`    |          | `{ detail: { value }` |
+| Events      | Tested   | Description |
+| ----------- | -------- | ----------- |
+| `change`    |          | `{ detail: { value }` |
+| `reference` |          | `{ detail: { id, callback } }` |
+
+```typescript
+this.$input.addEventListener('reference', (e: any) => {
+  const { id, callback } = e.detail;
+  // async request
+  // callback(file: File)
+});
+```
 
 ## Methods
 
@@ -34,32 +45,61 @@ See usage for each method below.
 
 | Method     | Tested   | Description |
 | ---------- | -------- | ----------- |
-| `save(options)` | -        | Save file. |
-| `open(json)` | -        | Open file. |
+| `getJson(options)` | -        | Get JSON file. |
+| `getData()` | -           | Get layer data. |
+| `setJson(json)` | -        | Set JSON file. |
+| `reset()` | -  | Reset canvas and data. |
+| `getExportCanvas()` | -  | Get new canvas of export. |
+| `await getExportPng(options, meta)` | -  | Get image. |
 | `undo()` | -           | Undo. |
 | `hasUndo()` | -     | Has undo |
 | `hasRedo()` | -     | Has redo |
 | `redo()` | -           | Redo. |
-| `selectLayer()` | -    | Select layer. |
+| `getHistory()` | -  | History list. |
+| `inputModeSelectRectangle()` | -  | Input Mode Select Rectangle |
+| `inputModeSelectEllipse()` | -  | Input Mode Select Ellipse |
+| `inputModeSelectLasso()` | -  | Input Mode Lasso |
+| `inputModeSelectMagicWand()` | -  | Input Mode Magic Wand |
+| `inputModePixel()` | -  | Input Mode Pixel |
+| `inputModeStamp(stamp)` | -  | Input Mode Stamp |
+| `inputModeLine()` | -  | Input Mode Line |
+| `inputModeRectangle()` | -  | Input Mode Rectangle |
+| `inputModeRectangleOutline()` | -  | Input Mode Rectangle Outline |
+| `inputModeEllipse()` | -  | Input Mode Ellipse |
+| `inputModeEllipseOutline()` | -  | Input Mode Ellipse Outline |
+| `selectLayer(index)` | -    | Select layer. |
 | `getLayers()` | -    | Get layer array. |
 | `addLayer(option)` | -        | Add layer. |
 | `removeLayer(index)` | -      | Remove layer. |
 | `flattenLayers(layerIndexes)` | -      | Flatten layers. |
-| `moveLayer(startIndex, endIndex)` | -    | Move layer. |
+| `getColor()` | -     | Get selected color |
 | `getColors()` | -    | Get colors. |
+| `getLayerColorIndexes()` | -  | Get selected layer colors. |
+| `selectColor(index)` | -    | Select color. |
+| `setColor(index, r, g, b, a)` | -  | Set Color. |
 | `addColor(r, g, b, a)` | -    | Add color. |
 | `removeColor(index)` | -    | Remove color. |
 | `moveColor(startIndex, endIndex)` | -    | Move index. |
 | `rotateClockwise()` | -    | Rotate. |
 | `rotateCounterclockwise()` | -    | Rotate. |
 | `move(x, y[, layer])` | -  | Move. |
-| `flipHorizontal()` | -  | Flip horizontal. |
-| `flipVertical()` | -  | Flip vertical. |
+| `getSelection()` | -  | Get selection pixels. |
+| `clearSelection()` | -  | Clear selection. |
+| `moveSelection(x, y)` | -    | Move selection. |
+| `flipHorizontal()` | -  | Flip horizontal selection. |
+| `flipVertical()` | -  | Flip vertical selection. |
 | `invert()` | -  | Invert layer. |
+| `outline()` | -  | Outline layer with selected color. |
+| `glow()` | -  | Glow layer with selected color. |
+| `drawPixels([[x, y, color], ...])` | -  | Draw pixels. Color optional. |
+| `drawRectangle(x, y, width, height, isOutline)` | -  | Draw rectangle |
+| `drawEllipse(x, y, width, height, isOutline)` | -  | Draw ellipse. |
+| `drawLine()` | -  | Draw line. |
+| `flush()` | -  | Flush changes to history. |
 
-### `save(options)` Method
+### `getJson(options)` Method
 
-The save method allows getting the JSON representation of the current editor.
+The `getJson` method allows getting the JSON representation of the current editor. Optionally this can snapshot the entire undo history. To get only data by layer call `getData()`.
 
 ```typescript
 @Part() $editor: PgInputPixelEditor;
@@ -73,7 +113,7 @@ handleSave() {
 }
 ```
 
-### `open(json)` Method
+### `setJson(json)` Method
 
 The open method allows loading json for previously created images.
 
@@ -88,11 +128,26 @@ handleOpen() {
 }
 ```
 
+## Events
+
+### `change`
+
+### `selectLayer`
+
+Using `InputMode.Cursor` individual pixels can be clicked on to select the layer. Note, selecting a layer does not automatically select it. The event must be handled.
+
+```typescript
+this.$input.addEventListener('selectlayer', (e: any) => {
+  const { color, index } = e.detail;
+  this.selectLayers([index]);
+})
+```
+
 ## JSON Format
 
 - `width` - Image width.
 - `height` - Image width.
-- `transparent` - Render transparent background.
+- `transparent` - Override the transparent color. This has no impact on the exported background.
 
 A complete JSON storage for a 10x10 image.
 
@@ -100,33 +155,160 @@ A complete JSON storage for a 10x10 image.
 {
   "width": 10,
   "height": 10,
-  "transparent": true,
+  "gridSize": 10,
+  "transparent": null,
   "colors": [
     [0, 0, 0, 0],
-    [0, 0, 0, 1]
+    [0, 0, 0, 1],
+    [255, 255, 255, 1]
   ],
   "layers": [
     {
       "name": "Layer 1",
-      "export": true,
+      "exclude": false,
       "locked": false,
-      "visible": true,
+      "hidden": false,
+      "type": "pixel",
       "opacity": 1
     }
   ],
   "data": [
     [
-      [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
-      [0, 1, 1, 1, 1, 1, 1, 1, 1, 0],
-      [0, 1, 0, 0, 0, 0, 0, 0, 1, 0],
-      [0, 1, 0, 0, 0, 0, 0, 0, 1, 0],
-      [0, 1, 0, 0, 0, 0, 0, 0, 1, 0],
-      [0, 1, 0, 0, 0, 0, 0, 0, 1, 0],
-      [0, 1, 0, 0, 0, 0, 0, 0, 1, 0],
-      [0, 1, 0, 0, 0, 0, 0, 0, 1, 0],
-      [0, 1, 1, 1, 1, 1, 1, 1, 1, 0],
-      [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
+      [{ "color": 1, "path": "M...Z" }],
+      [{ "color": 2, "path": "M...Z" }]
     ]
+  ],
+  "history": []
+}
+```
+
+## Layer Type
+
+There are currently 6 differnet layer types.
+
+- `pixel` - Raster artboard of pixels.
+  - `color: 0` - colorIndex
+  - `path: ''` - pixels
+- `reference`
+  - `id: 'uuid'` - uuid of frame
+  - `position: [x, y]`
+- `pattern` - Repeat an existing frame
+  - `id: 'uuid'` - uuid of frame
+  - `position: [x, y]` - required
+  - `size: [x, y]` - optional, size to clip at
+  - `offset [x, y]` - optional, offset pattern
+- `linear` - Linear gradient.
+  - `start: [x, y]`
+  - `end: [x, y]`
+  - `path: ''` - optional, mask
+  - `stops: [[stop, colorIndex], [stop, colorIndex]]`
+  - `dither: 'bayer4' | 'bayer8', 'bayer16'`
+- `radial` - Radial gradients.
+  - `start: [x, y]`
+  - `end: [x, y]`
+  - `transform: [1, 0, 0, 0.5, 0, 0]` to create ellipses
+  - `stops: [[stop, colorIndex], [stop, colorIndex]]`
+  - `dither: 'bayer4' | 'bayer8' | 'bayer16'`
+- `text` - Text, maybe???
+  - `id: 'uuid'` - file uuid
+  - `value: ''` - string
+
+### Layer `pixel` Type
+
+The most common layer type.
+
+```json
+{
+  "data": [
+    [
+      { "color": 1, "path": "M...Z" },
+      { "color": 2, "path": "M...Z" }
+    ]
+  ]
+}
+```
+
+### Layer `reference` Type
+
+Using an existing canvas in a design can be done with a reference layer.
+
+```json
+{
+  "data": [
+    [{ "id": "uuid", "position": [0, 0] }]
+  ]
+}
+```
+
+### Layer `pattern` Type
+
+Using an existing canvas, but in a repeating pattern.
+
+```json
+{
+  "data": [
+    [{ "id": "uuid", "position": [0, 0], "size": [100, 100] }],
+    [{ "id": "uuid", "position": [0, 0], "offset": [0, -2] }]
+  ]
+}
+```
+
+### Layer `linear` / `radial` Type
+
+Linear and radial gradient between 2 points. Both allow a mask to be applied.
+
+```json
+{
+  "data": [
+    [{ "id": "uuid", "start": [0, 0], "end": [100, 100] }],
+    [{ "id": "uuid", "start": [0, 0], "end": [100, 0], "stops": [] }]
   ]
 }
 ```
+
+### Layer `text` Type
+
+Pull down a known font and use it as a reference.
+
+```json
+{
+  "data": [
+    [{ "id": "uuid", "value": "Hello World!", "position": [0, 0] }],
+    [{ "id": "uuid", "value": "Hello World!", "position": [0, 0], "wrap": 100 }]
+  ]
+}
+```
+
+If a `id` is not found in the current file it will call the `reference` event. This event will need to return the found file to the `callback`. This could slow down initial project load.
+
+```typescript
+this.$input.addEventListener('reference', (e: any) => {
+  const { id, callback } = e.detail;
+  if (id === 'uuid') {
+    callback(file);
+  }
+});
+```
+
+## History
+
+The history list contains every change made to the canvas. All feature insert an entry into history. Pens and pattern tools will group as to cut down history entries.
+
+Note: Calling the `draw*()` commands programatically will group into a single history item. To create multiple entries call `flush()`.
+
+- Undo a change
+- Redo an undo
+- Timeline - Commonly used to generate progression clips. `getHistoryGif({ delay: 0.05 })` for instance generates a gif with 0.05 second delay between each change.
+
+### History Format
+
+For plugins or tools generating timelines the `getHistory()` returns an array with all entries. Note the `getHistoryPng(index)` is very CPU intensive and will recreate every change up to the index.
+
+```json
+[       // history
+  [     // history item
+    {}, // group
+    {}
+  ]
+]
+```

package/pg/inputPixelEditor/__examples__/basic/basic.css

@@ -24,6 +24,14 @@ label {
 }
 
 h3 {
+  display: flex;
   margin: 0.25rem 0;
   font-size: 1.125rem;
+  align-items: center;
+}
+
+[part=addColor],
+[part=addLayer] {
+  vertical-align: middle;
+  margin-left: 0.5rem;
 }

package/pg/inputPixelEditor/__examples__/basic/basic.html

@@ -29,10 +29,23 @@
     <button part="reset">Reset</button>
     <button part="clear">Clear</button>
     <button part="invert">Invert</button>
+    <button part="outline">Outline</button>
+    <button part="glow">Glow</button>
+    |
+    <button part="undo">Undo</button>
+    <button part="redo">Redo</button>
     |
     <button part="save">Save</button>
     <button part="open">Open</button>
   </div>
+  <div>
+    <h3>Selection Tools</h3>
+    <button part="cursor">Cursor</button>
+    <button part="selectRectangle">Select Rectangle</button>
+    <button part="selectEllipse">Select Circle</button>
+    <button part="selectLasso">Select Lasso</button>
+    <button part="selectMagic">Select Magic Wand</button>
+  </div>
   <div>
     <h3>Drawing Tools</h3>
     <button part="modePixel">Pixel</button>
@@ -43,20 +56,29 @@
     <button part="modeEllipseOutline">Ellipse Outline</button>
   </div>
   <div>
-    <h3>Color Tools</h3>
-    <button part="addColor">Add Color</button>
-    <pre part="colors"></pre>
+    Stamps:
+    <button part="modeStamp1" data-stamp="1">1 Pixel</button>
+    <button part="modeStamp2" data-stamp="3-circle">3 Pixel Circle</button>
+    <button part="modeStamp3" data-stamp="3-square">3 Pixel Square</button>
+    <button part="modeStamp4" data-stamp="heart">Heart</button>
+  </div>
+  <div>
+    <h3>Color Tools <button part="addColor">Add Color</button></h3>
+    <pg-table part="colors"></pg-table>
   </div>
   <div>
-    <h3>Layer Tools</h3>
-    <button part="addLayer">Add Layer</button>
-    <pre part="layers"></pre>
+    <h3>Layer Tools&nbsp;<small>(inversed, lower index is a higher layer)</small></h3>
+    <div>
+      <button part="addLayer">Add Pixel Layer</button>
+      <button part="addLayerReference">Add Reference Layer</button>
+    </div>
+    <pg-table part="layers"></table>
   </div>
   <div>
     <h3>Example Tools</h3>
     <input part="file" type="file" />
     <button part="saveSvg">Save SVG</button>
-    <button part="savePng">Save Image</button>
+    <button part="savePng">Save PNG</button>
   </div>
   <div part="debug"></div>
   <pre part="output" contenteditable></pre>