morphico 0.3.0 → 0.4.0

package/README.md

@@ -91,12 +91,14 @@ photo.to('shield', { rotation: 360, x: 30, size: '120px' }); // morph + turn + m
 photo.to({ x: 70, y: '150px' });                          // move only, the shape stays
 photo.set({ rotation: 15 });                              // jump, no animation (e.g. while dragging a slider)
 photo.set({ outline: { width: 16 } });                    // only a 16 px band along the edge shows
+photo.set({ inverted: true });                            // the other way round: the shape is a hole
 photo.destroy();                                          // the element is whole again
 ```
 
 Shapes (based on [Lucide](https://lucide.dev)): `circle`, `ellipse`, `heart`, `sparkle`, `astroid`, `bookmark`,
 `shield`, `moon`, `tag`, `square`, `badge`, `triangle`, `droplet`, `pentagon`, `hexagon`, `octagon`, `squircle`,
-`star`, `rectangle-horizontal`, `rectangle-vertical`, `message-circle`, `message-square`, `diamond`, `cloud`, `puzzle`.
+`star`, `rectangle-horizontal`, `message-circle`, `message-square`, `cloud`, `puzzle`, `club`. A diamond is the `square`
+turned 45°, a portrait rectangle `rectangle-horizontal` turned 90° (`rotation`).
 
 | Option | Default | |
 | --- | --- | --- |
@@ -106,13 +108,51 @@ Shapes (based on [Lucide](https://lucide.dev)): `circle`, `ellipse`, `heart`, `s
 | `rotation` | `0` | Degrees, clockwise, **absolute**: `rotation: 360` ends one full turn from 0. The shape turns rigidly, also in a wide or tall element |
 | `roundness` | `1` | Corners: `0` = sharp … `1` = the shape's own (the maximum) |
 | `outline` | `false` | `{ width, band }`: only a band of `width` px along the edge shows; `band`: `'inside'` (default), `'centre'` or `'outside'` the edge. Not animated |
+| `inverted` | `false` | `true`: the other way round — the shape (or band) is a hole, the rest of the element shows. Not animated |
 | `duration`, `easing` | `400`, `'easeInOutCubic'` | As for icons; also per `to()` call |
 
-Everything except `outline` animates together in `to()`. How it works: a filled shape uses CSS `clip-path: url(#…)`,
+Everything except `outline` and `inverted` animates together in `to()`. How it works: a filled shape uses CSS `clip-path: url(#…)`,
 an outlined one `mask: url(#…)` (clip-path has no line width); the `<clipPath>` / `<mask>` sit in a small hidden
 `<svg>` that `clip()` adds to the page. It follows the element's size (`ResizeObserver`). Overflow beyond the element is
 cut off, as with any clip-path.
 
+## A face: `face(element, options)`
+
+A face of 7 soft pieces — 2 brows, 2 eyes, 2 pupils and a mouth — that morphs between feelings and blinks.
+
+```html
+<div id="robot" style="width: 160px; height: 160px; border-radius: 50%; background: #e4e2d6; color: #8b8e8e"></div>
+```
+
+```ts
+import { face } from 'morphico';
+
+const robot = face(document.querySelector('#robot'), { state: 'normal' });
+
+await robot.to('smiling');                    // morph
+robot.to('angry', { duration: 300, onEnd: (result) => console.log(result) });
+robot.blink();                                // close and open the eyes once, on top of any expression
+robot.state;                                  // 'angry'
+robot.destroy();                              // removes the face, stops blinking
+```
+
+Expressions: `normal`, `smiling`, `pleading`, `wonder`, `focused`, `fright`, `angry`, `asleep`, `sad`,
+`surprised`, `laughing`, `tired`, `wink-left`, `wink-right`, `suspicious`, `confused`, `smug`, `irritated`,
+`bored`, `curious`, `empathetic`, `guilty`, `worried`, `disappointed`, `ashamed`, `embarrassed`, `yearning`,
+`triumphant`, `proud`, `excited`, `scornful`, `disgusted` (also exported as `faceExpressionNames`). Any one
+morphs into any other. `wink-left` / `wink-right` = the eye that closes, as seen.
+
+| Option | Default | |
+| --- | --- | --- |
+| `state` | `'normal'` | The expression shown first |
+| `pupilColor` | `'white'` | Colour of the pupils. Brows, eyes and mouth take the CSS `color` |
+| `blink` | `true` | Blink by itself every few seconds |
+| `size` | `'100%'` | CSS width and height of the face (by default it fills the element) |
+| `duration`, `easing` | `500`, `'easeInOutCubic'` | As for icons; also per `to()` call |
+
+The face draws no background: a disc, card or anything else behind it is the element's own CSS. The pupils only show
+inside the eyes (an eyelid covers them). With reduced motion the face changes without animation and doesn't blink.
+
 ## Options
 
 | Option | For | Default | |
@@ -140,7 +180,7 @@ cut off, as with any clip-path.
   The earlier promise resolves with `{ interrupted: true }`; promises never stay pending.
 - **Reduced motion:** when the user's system asks for reduced motion, shapes change without animation.
 - **Accessibility:** the icon / line has `role="img"` and an `aria-label` with the current value.
-- **Server-side rendering:** importing does not touch the DOM; only `icon()` / `text()` / `clip()` do.
+- **Server-side rendering:** importing does not touch the DOM; only `icon()` / `text()` / `clip()` / `face()` do.
 
 ## Development