craft-library 0.1.3 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Craft Library
 
-Interface pieces by [Sara Lobo](https://www.saralobodesign.com/), designed, tested and polished one detail at a time: a liquid glass nav bar, a bursting heart and a magnetic icon. Each one is the exact piece from the library, with its own CSS and motion, no dependencies, for React 18+ or plain HTML.
+Interface pieces by [Sara Lobo](https://www.saralobodesign.com/), designed, tested and polished one detail at a time: a liquid glass nav bar, a bursting heart, a magnetic icon, an iridescent 3D card and a glass piggy bank. Each one is the exact piece from the library, with its own CSS and motion, for React 18+ or plain HTML. The only dependency is three.js, for the two 3D pieces, and it loads only when one of them is on the page.
 
 ```bash
 npm install craft-library
@@ -58,9 +58,52 @@ import { MagneticIcon } from 'craft-library';
 | `label` | `string` | The accessible name. Default `"Search"`. |
 | `onClick` | `(event) => void` | |
 
+## Iridescent card
+
+A 3D metal credit card: a brushed iridescent plate, a fine struck frame along the edge, a chip and the Visa mark. It arrives showing its back and makes a slow half turn to its face; a tap or a drag turns it over to show the numbers, heavy and without bounce. At rest it breathes slowly, and the light slides across the metal with its angle.
+
+```jsx
+import { IridescentCard } from 'craft-library';
+
+<IridescentCard height={480} onTurn={(face) => console.log(face)} />
+```
+
+| Prop | | |
+|---|---|---|
+| `height` | `number \| string` | The box the card fills: 100% wide (at least 300px) and this tall, the card centred in it. Default `480`. |
+| `size` | `0–1` | The card's height as a share of the box's. Default `0.72`. |
+| `onTurn` | `(face) => void` | After every turn: `"front"` or `"back"`. |
+| `name`, `number`, `expiry`, `cvv` | `string` | What the back shows. `number` as `"4532 8890 1274 3306"`. |
+| `entrance` | `boolean` | `false` skips the half turn on mount. Default `true`. |
+| `logo` | `string` | An image URL for the mark on the face, printed in white. Default: the Visa mark. |
+| `label` | `string` | The accessible name. |
+
+It is WebGL (three.js 0.169, which comes with the package and loads the first time a card mounts), so one card per screen is best. It is made for a dark background; black is best. The Visa mark is a trademark of Visa Inc., there to show a card: pass your own `logo` for anything real.
+
+## Glass piggy bank
+
+A congratulations moment in 3D, made for a phone screen: a frosted glass piggy bank hops in from the right with a full turn, lands on its hind feet, nearly tips over and clacks back down, rocking like the rigid glass it is. Coins pop into the air above it and drop in through the slot; each one knocks the glass, and its eyes close a little more until they curve, happy. It plays the first time it comes into view; a tap plays it again.
+
+```jsx
+import { PiggyBank } from 'craft-library';
+
+<PiggyBank height={560} onDone={() => console.log('saved!')} />
+```
+
+| Prop | | |
+|---|---|---|
+| `height` | `number \| string` | The box the moment fills: 100% wide (at least 280px) and this tall. Default `560`. |
+| `autoplay` | `boolean` | `false` waits instead of playing when it comes into view. Default `true`. |
+| `replay` | `any` | Change it (a counter, say) to play the moment again. |
+| `interactive` | `boolean` | `false` turns off tap-to-replay and the drag that turns it once it is still. Default `true`. |
+| `onDone` | `() => void` | After each play, when its eyes open again. |
+| `label` | `string` | The accessible name. |
+
+It is WebGL (three.js 0.169, which comes with the package and loads the first time it mounts), so one per screen is best. It is made for a dark background; black is best.
+
 ## Plain HTML
 
-One script registers three tags. Same pieces, same props as attributes.
+One script registers five tags. Same pieces, same props as attributes.
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/craft-library@0/dist/craft.js"></script>
@@ -68,12 +111,14 @@ One script registers three tags. Same pieces, same props as attributes.
 <glass-nav active="0"></glass-nav>        <!-- "select" event: e.detail.index -->
 <like-button></like-button>               <!-- "change" event: e.detail.liked -->
 <magnetic-icon size="40"></magnetic-icon>
+<iridescent-card></iridescent-card>       <!-- "cardturn" event: e.detail.face; 100% wide, 480px tall unless you size it -->
+<piggy-bank></piggy-bank>                 <!-- "piggydone" event after each play; el.play() replays; 100% wide, 560px tall unless you size it -->
 ```
 
 With a bundler and no React: `import 'craft-library/elements'`.
 
 ## Motion and access
 
-Every item is a real `<button>` with an accessible name; the nav marks the chosen one with `aria-current` and moves with the arrow keys. With `prefers-reduced-motion`, the heart only changes colour, the nav only slides and the magnet stays still.
+Every item is a real `<button>` with an accessible name; the nav marks the chosen one with `aria-current` and moves with the arrow keys. The card is a `role="button"` that Enter, Space and the arrow keys turn over; the piggy bank is a labelled image. With `prefers-reduced-motion`, the heart only changes colour, the nav only slides, the magnet stays still the card swaps faces with a fade, with no entrance and no breathing, and the piggy bank stays in place while the coins appear inside it and its eyes close.
 
 MIT · [Craft Library](https://claude.ai/artifact/LBBWCfEHJGvfBSynV3wDuR)

package/dist/card-load.js

@@ -0,0 +1,2 @@
+// where the card comes from: for bundlers, the package's card.js (it imports the `three` dependency)
+export const loadCard = () => import('./card.js');

package/dist/card-mount.js

@@ -0,0 +1,32 @@
+// Iridescent card: the mount around the library's card.js. card.js, and three.js with it, loads only when a card is
+// mounted, so the other pieces stay light.
+import { loadCard } from './card-load.js';
+
+const LABEL = 'Credit card. Press to turn it over and see the back.';
+const KEYS = ['name', 'number', 'expiry', 'cvv', 'logo', 'size', 'entrance', 'interactive'];
+
+// host: the element the card fills (give it a size; the card sits centred at `size` of its height).
+// o: { name, number ('4532 8890 1274 3306' or four groups), expiry, cvv, logo (an image URL), size (0–1, default 0.72),
+//      entrance (false: no half turn on mount), interactive (false: no tap or drag), label, onTurn(face) }
+export function mountIridescentCard(host, o = {}) {
+  let card = null, gone = false;
+  const opts = { label: o.label || LABEL };
+  for (const k of KEYS) if (o[k] !== undefined && o[k] !== null) opts[k] = o[k];
+  if (typeof opts.number === 'string') opts.number = opts.number.trim().split(/\s+/);
+  const turned = (e) => { if (o.onTurn) o.onTurn(e.detail.face); };
+  host.addEventListener('cardturn', turned);
+  const ready = loadCard().then((m) => {
+    if (gone) return null;
+    if (!opts.logo && m.LOGO) opts.logo = m.LOGO;              // the Visa mark, carried in the module
+    card = m.mountCard(host, opts);
+    return card.ready.then(() => card);
+  });
+  return {
+    ready,
+    turn: (dir) => { if (card) card.turn(dir); },
+    show: (face) => { if (card) card.show(face); },
+    play: () => { if (card) card.play(); },
+    get face() { return card ? card.face : 'front'; },
+    destroy() { gone = true; host.removeEventListener('cardturn', turned); if (card) card.destroy(); card = null; }
+  };
+}