craft-library 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # Sara Lobo 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, a magnetic icon, an iridescent 3D card, a glass piggy bank, two "thinking" indicators, the Magic sphere and the Sweep, and the Panorama, a hero for moving pictures. 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 two of the 3D pieces, and it loads only when one of them is on the page.
+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, a glass piggy bank, two "thinking" indicators, the Magic sphere and the Sweep, the Panorama, a hero for moving pictures, and the Map pin, an address picker. 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 three of the 3D pieces, and it loads only when one of them is on the page.
 
 ```bash
 npm install craft-library
@@ -101,6 +101,29 @@ import { PiggyBank } from 'craft-library';
 
 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.
 
+## Map pin
+
+A 3D address picker: a hollow frosted-glass map pin over a dark city map in perspective. A click or a tap on a street sends the pin flying on springs to the nearest curb: it lifts, its head leans with the acceleration, it rises a touch to aim, falls under gravity and sticks its tip in, the glass vibrating about it. The map is sharp where it lands and soft further away, the streets carry their names, and a card along the bottom shows the address, with the number on the right side of the street, to confirm. With a mouse, hovering shows the address a click would give. The city and its names are invented, to show the gesture.
+
+```jsx
+import { MapPin } from 'craft-library';
+
+<MapPin height={560} onConfirm={(a) => saveAddress(a)} />   // saveAddress: your own handler
+```
+
+| Prop | | |
+|---|---|---|
+| `height` | `number \| string` | The box it fills: 100% wide and this tall. Default `560`. |
+| `onChange` | `(address) => void` | Each address the pin is sent to: `{ address, neighbourhood, place }`. |
+| `onConfirm` | `(address) => void` | When Confirm is pressed, with the same address. |
+| `labels` | `{ title, confirm, confirmed }` | The card's words. Defaults `"Delivery address"`, `"Confirm"`, `"Confirmed"`. |
+| `replay` | `any` | Change it (a counter, say) to fly the pin off and back in. |
+| `autoplay` | `boolean` | `false` keeps the pin out until `replay` changes. Default `true`. |
+| `fonts` | `boolean` | `false` doesn't load DM Sans from Google Fonts. Default `true`. |
+| `label` | `string` | The map's 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 paints its own dark ground.
+
 ## Magic sphere and Sweep
 
 Two "thinking" indicators for the wait while an answer is being written: a ball of dots, drawn on a canvas, with the word beside it. The **Magic sphere** is a Rubik's cube on a ball, one grey tone per face: its slices turn and scramble the pieces, retrace their steps until every piece is home, and the ball lights up for a moment while a light passes through the word. In the **Sweep**, a wave crosses a dotted globe from left to right, lifting the dots it passes, runs on through the word at the same speed, and rests.
@@ -145,7 +168,7 @@ It is WebGL with no dependencies, so one per screen is best. Your clip and pictu
 
 ## Plain HTML
 
-One script registers eight tags. Same pieces, same props as attributes.
+One script registers nine tags. Same pieces, same props as attributes.
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/craft-library@0/dist/craft.js"></script>
@@ -158,12 +181,13 @@ One script registers eight tags. Same pieces, same props as attributes.
 <magic-sphere></magic-sphere>             <!-- label="Thinking" (default; label="" for the ball alone), size="32" -->
 <sweep-sphere></sweep-sphere>
 <panorama-reel heading="Lorem ipsum"></panorama-reel>  <!-- text, text-italic; video and stills as JSON; el.replay(); 100% wide, 640px tall unless you size it -->
+<map-pin></map-pin>                       <!-- "pinchange" and "pinconfirm" events: e.detail { address, neighbourhood, place }; label-title, label-confirm, label-confirmed; el.replay(); 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. 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, the piggy bank stays in place while the coins appear inside it and its eyes close, the thinking balls hold still and only breathe, and the panorama skips its opening and starts settled. The panorama's title is a heading; its screens and cursor are decorative.
+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 and the map pin's map are labelled images; the pin's address is announced as it changes and Confirm is a real button. 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, the piggy bank stays in place while the coins appear inside it and its eyes close, the thinking balls hold still and only breathe, the panorama skips its opening and starts settled, and the map pin appears in place without its flight. The panorama's title is a heading; its screens and cursor are decorative.
 
 MIT · [Sara Lobo Library](https://saralobolibrary.com)

package/dist/cdn.js

@@ -1,4 +1,4 @@
-// the one-file build for a <script> tag: registers the eight tags and exposes the mount functions (the 3D pieces' scenes
+// the one-file build for a <script> tag: registers the nine tags and exposes the mount functions (the 3D pieces' scenes
 // are fetched from next to this file the first time one is mounted, and so are the Panorama's clip and pictures)
-import { mountLike, mountMagnet, mountGlassNav, mountIridescentCard, mountPiggyBank, mountThinking, mountPanoramaReel } from './elements.js';
-window.CraftLibrary = { mountLike, mountMagnet, mountGlassNav, mountIridescentCard, mountPiggyBank, mountThinking, mountPanoramaReel };
+import { mountLike, mountMagnet, mountGlassNav, mountIridescentCard, mountPiggyBank, mountThinking, mountPanoramaReel, mountMapPin } from './elements.js';
+window.CraftLibrary = { mountLike, mountMagnet, mountGlassNav, mountIridescentCard, mountPiggyBank, mountThinking, mountPanoramaReel, mountMapPin };

package/dist/craft.js

@@ -1,4 +1,4 @@
-/* Sara Lobo Library · liquid glass nav bar, bursting heart, magnetic icon, iridescent card, glass piggy bank, magic sphere, sweep, panorama · <glass-nav>, <like-button>, <magnetic-icon>, <iridescent-card>, <piggy-bank>, <magic-sphere>, <sweep-sphere>, <panorama-reel> */
+/* Sara Lobo Library · liquid glass nav bar, bursting heart, magnetic icon, iridescent card, glass piggy bank, magic sphere, sweep, panorama, map pin · <glass-nav>, <like-button>, <magnetic-icon>, <iridescent-card>, <piggy-bank>, <magic-sphere>, <sweep-sphere>, <panorama-reel>, <map-pin> */
 (() => {
   // dist/style.js
   var done = /* @__PURE__ */ new Set();
@@ -2469,6 +2469,56 @@ void main() {
     return mountPanorama(host, opts);
   }
 
+  // src/pin-load-cdn.js
+  var me4 = typeof document !== "undefined" && document.currentScript ? document.currentScript.src : "";
+  var base3 = me4 ? me4.slice(0, me4.lastIndexOf("/") + 1) : "https://cdn.jsdelivr.net/npm/craft-library@0/dist/";
+  var loadPin = () => import(base3 + "pin.cdn.js");
+
+  // dist/pin-mount.js
+  function mountMapPin(host, o = {}) {
+    let pin = null, gone = false, wantReplay = false;
+    const opts = { labels: o.labels, label: o.label, manual: o.manual };
+    if (o.autoplay === false) opts.autoplay = false;
+    if (o.fonts === false) opts.fonts = false;
+    const change = (e) => {
+      if (o.onChange) o.onChange(e.detail);
+    };
+    const confirm = (e) => {
+      if (o.onConfirm) o.onConfirm(e.detail);
+    };
+    host.addEventListener("pinchange", change);
+    host.addEventListener("pinconfirm", confirm);
+    const ready = loadPin().then((m) => {
+      if (gone) return null;
+      pin = m.mountPin(host, opts);
+      if (wantReplay) pin.replay();
+      return pin.ready.then(() => pin);
+    });
+    return {
+      ready,
+      replay: () => {
+        if (pin) pin.replay();
+        else wantReplay = true;
+      },
+      confirm: () => {
+        if (pin) pin.confirm();
+      },
+      tick: (dt, now) => {
+        if (pin) pin.tick(dt, now);
+      },
+      get address() {
+        return pin ? pin.address : null;
+      },
+      destroy() {
+        gone = true;
+        host.removeEventListener("pinchange", change);
+        host.removeEventListener("pinconfirm", confirm);
+        if (pin) pin.destroy();
+        pin = null;
+      }
+    };
+  }
+
   // dist/elements.js
   function define(name, mount, options) {
     if (typeof customElements === "undefined" || customElements.get(name)) return;
@@ -2560,7 +2610,18 @@ void main() {
     cursor: el.getAttribute("cursor") === "false" ? false : void 0,
     fonts: el.getAttribute("fonts") === "false" ? false : void 0
   }));
+  define("map-pin", (el, o) => {
+    css("craft-pin-host", ":where(map-pin){display:block;position:relative;width:100%;height:560px}");
+    const m = mountMapPin(el, o);
+    el.replay = m.replay;
+    return m;
+  }, (el) => ({
+    labels: { title: el.getAttribute("label-title") ?? void 0, confirm: el.getAttribute("label-confirm") ?? void 0, confirmed: el.getAttribute("label-confirmed") ?? void 0 },
+    label: el.getAttribute("label") || void 0,
+    autoplay: el.getAttribute("autoplay") === "false" ? false : void 0,
+    fonts: el.getAttribute("fonts") === "false" ? false : void 0
+  }));
 
   // dist/cdn.js
-  window.CraftLibrary = { mountLike, mountMagnet, mountGlassNav, mountIridescentCard, mountPiggyBank, mountThinking, mountPanoramaReel };
+  window.CraftLibrary = { mountLike, mountMagnet, mountGlassNav, mountIridescentCard, mountPiggyBank, mountThinking, mountPanoramaReel, mountMapPin };
 })();

package/dist/elements.js

@@ -1,4 +1,4 @@
-// <glass-nav>, <like-button>, <magnetic-icon>, <iridescent-card>, <piggy-bank>, <magic-sphere>, <sweep-sphere> and <panorama-reel>: the
+// <glass-nav>, <like-button>, <magnetic-icon>, <iridescent-card>, <piggy-bank>, <magic-sphere>, <sweep-sphere>, <panorama-reel> and <map-pin>: the
 // pieces as HTML tags, for pages without React. They render into the page itself (no shadow root), so the glass can
 // blend with what is behind it.
 import { mountLike } from './like.js';
@@ -8,6 +8,7 @@ import { mountIridescentCard } from './card-mount.js';
 import { mountPiggyBank } from './piggy-mount.js';
 import { mountThinking } from './thinking.js';
 import { mountPanoramaReel } from './panorama-mount.js';
+import { mountMapPin } from './pin-mount.js';
 import { css } from './style.js';
 
 function define(name, mount, options) {
@@ -101,4 +102,19 @@ define('panorama-reel', (el, o) => {
   fonts: el.getAttribute('fonts') === 'false' ? false : undefined
 }));
 
-export { mountLike, mountMagnet, mountGlassNav, mountIridescentCard, mountPiggyBank, mountThinking, mountPanoramaReel };
+// the map pin fills the tag: a block, 100% wide and 560px tall unless the page sizes it. Each address the pin is sent to
+// fires "pinchange" and a confirmation "pinconfirm", both with e.detail { address, neighbourhood, place }. The words:
+// label-title, label-confirm, label-confirmed. el.replay() flies the pin off and back in.
+define('map-pin', (el, o) => {
+  css('craft-pin-host', ':where(map-pin){display:block;position:relative;width:100%;height:560px}');
+  const m = mountMapPin(el, o);
+  el.replay = m.replay;
+  return m;
+}, (el) => ({
+  labels: { title: el.getAttribute('label-title') ?? undefined, confirm: el.getAttribute('label-confirm') ?? undefined, confirmed: el.getAttribute('label-confirmed') ?? undefined },
+  label: el.getAttribute('label') || undefined,
+  autoplay: el.getAttribute('autoplay') === 'false' ? false : undefined,
+  fonts: el.getAttribute('fonts') === 'false' ? false : undefined
+}));
+
+export { mountLike, mountMagnet, mountGlassNav, mountIridescentCard, mountPiggyBank, mountThinking, mountPanoramaReel, mountMapPin };

package/dist/index.js

@@ -8,6 +8,7 @@ import { mountIridescentCard } from './card-mount.js';
 import { mountPiggyBank } from './piggy-mount.js';
 import { mountThinking } from './thinking.js';
 import { mountPanoramaReel } from './panorama-mount.js';
+import { mountMapPin } from './pin-mount.js';
 
 const HOST = { display: 'inline-block', lineHeight: 0, verticalAlign: 'middle' };
 
@@ -102,4 +103,19 @@ export function PanoramaReel({ height = 640, title, text, textItalic, video, sti
   return createElement('div', { ref: host, className, style: { position: 'relative', width: '100%', height, ...style } });
 }
 
-export { mountLike, mountMagnet, mountGlassNav, mountIridescentCard, mountPiggyBank, mountThinking, mountPanoramaReel };
+// The map pin fills the box it renders (100% wide and `height` tall, 560px by default) with a city map and a glass pin:
+// a click on a street sends the pin to its curb, and the card under the map confirms the address. onChange and onConfirm
+// get { address, neighbourhood, place }. labels: { title, confirm, confirmed }, the card's words. replay: change it (a
+// counter) to fly the pin off and back in. It loads its 3D scene (three.js) the first time it mounts.
+export function MapPin({ height = 560, labels, label, autoplay, fonts, replay, onChange, onConfirm, className, style }) {
+  const host = useRef(null), pin = useRef(null), last = useRef(replay), change = useLatest(onChange), confirm = useLatest(onConfirm);
+  const key = JSON.stringify([labels, label, autoplay, fonts]);
+  useEffect(() => {
+    const m = pin.current = mountMapPin(host.current, { labels, label, autoplay, fonts, onChange: (a) => change.current && change.current(a), onConfirm: (a) => confirm.current && confirm.current(a) });
+    return () => { m.destroy(); pin.current = null; };
+  }, [key]);
+  useEffect(() => { if (last.current === replay) return; last.current = replay; if (pin.current) pin.current.replay(); }, [replay]);
+  return createElement('div', { ref: host, className, style: { position: 'relative', width: '100%', height, ...style } });
+}
+
+export { mountLike, mountMagnet, mountGlassNav, mountIridescentCard, mountPiggyBank, mountThinking, mountPanoramaReel, mountMapPin };

package/dist/panorama-assets.js

@@ -1,2 +1,2 @@
 // where the Panorama's own clip and pictures are: jsDelivr, at this version of the package
-export const ASSETS = 'https://cdn.jsdelivr.net/npm/craft-library@0.5.0/dist/panorama/';
+export const ASSETS = 'https://cdn.jsdelivr.net/npm/craft-library@0.6.0/dist/panorama/';

package/dist/pin-load.js

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

package/dist/pin-mount.js

@@ -0,0 +1,30 @@
+// Map pin: the mount around the library's pin.js. pin.js, and three.js with it, loads only when a map pin is mounted,
+// so the other pieces stay light.
+import { loadPin } from './pin-load.js';
+
+// host: the element the map fills (give it a size; it is made for about 560 × 560). o: { labels: { title, confirm,
+// confirmed }, label (the map's accessible name), autoplay (false: the pin waits for replay()), fonts (false: don't load
+// DM Sans), onChange(address), onConfirm(address) }; address: { address, neighbourhood, place }
+export function mountMapPin(host, o = {}) {
+  let pin = null, gone = false, wantReplay = false;
+  const opts = { labels: o.labels, label: o.label, manual: o.manual };
+  if (o.autoplay === false) opts.autoplay = false;
+  if (o.fonts === false) opts.fonts = false;
+  const change = (e) => { if (o.onChange) o.onChange(e.detail); };
+  const confirm = (e) => { if (o.onConfirm) o.onConfirm(e.detail); };
+  host.addEventListener('pinchange', change); host.addEventListener('pinconfirm', confirm);
+  const ready = loadPin().then((m) => {
+    if (gone) return null;
+    pin = m.mountPin(host, opts);
+    if (wantReplay) pin.replay();
+    return pin.ready.then(() => pin);
+  });
+  return {
+    ready,
+    replay: () => { if (pin) pin.replay(); else wantReplay = true; },
+    confirm: () => { if (pin) pin.confirm(); },
+    tick: (dt, now) => { if (pin) pin.tick(dt, now); },
+    get address() { return pin ? pin.address : null; },
+    destroy() { gone = true; host.removeEventListener('pinchange', change); host.removeEventListener('pinconfirm', confirm); if (pin) pin.destroy(); pin = null; }
+  };
+}