morphico 0.2.0 → 0.3.0

package/README.md

@@ -19,7 +19,7 @@ Or from a CDN, as a classic script with the global `morphico`:
 ```html
 <script src="https://cdn.jsdelivr.net/npm/morphico"></script>
 <script>
-  const { icon, text } = morphico;
+  const { icon, text, clip } = morphico;
 </script>
 ```
 
@@ -79,6 +79,40 @@ clock.destroy();
   (`5` ↔ `:`). Pad counters with spaces to keep them morphing: `counter.set(String(count).padStart(3, ' '))`.
 - Digits sit on the text baseline, and every cell has the same width, so clocks don't jiggle.
 
+## A cut-out: `clip(element, options)`
+
+Cuts any element (an `<img>`, a `<div>`, a `<main>` …) out by a shape, and morphs, moves, resizes and turns it.
+
+```ts
+const photo = clip(document.querySelector('#photo'), { state: 'star', x: 50, y: 50, size: '80%' });
+
+await photo.to('heart');                                  // morph
+photo.to('shield', { rotation: 360, x: 30, size: '120px' }); // morph + turn + move together
+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.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`.
+
+| Option | Default | |
+| --- | --- | --- |
+| `state` | `'circle'` | The shape |
+| `x`, `y` | `50` | The shape's **centre**. A number is %, or a string `'40%'` / `'120px'` (% of the element's width for `x`, height for `y`) |
+| `size` | fits | The side of the shape's square (% of the element's width, or px). The shape keeps its own proportions inside that square. Default: the largest square that fits the element |
+| `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 |
+| `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(#…)`,
+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.
+
 ## Options
 
 | Option | For | Default | |
@@ -106,7 +140,7 @@ clock.destroy();
   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()` do.
+- **Server-side rendering:** importing does not touch the DOM; only `icon()` / `text()` / `clip()` do.
 
 ## Development
 
@@ -121,5 +155,5 @@ npm run build      # src/ → dist/
 
 ## License
 
-[MIT](LICENSE). The icon sets are based on [Lucide](https://lucide.dev) icons (ISC; some from Feather, MIT):
+[MIT](LICENSE). The icon sets and clip shapes are based on [Lucide](https://lucide.dev) icons (ISC; some from Feather, MIT):
 see [LICENSE-lucide](LICENSE-lucide).