visionary-image 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# visionary-image
+
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/visionary-ux/visionary-image/.github%2Fworkflows%2Fci-cd-workflow.yml?branch=master&style=flat-square)
+
+> Visionary Image rapidly renders blurhash placeholders and boosts Core Web Vitals.
+
+**Features:**
+
+- Blurhash data encoded in the image URL via [visionary-url](https://github.com/visionary-ux/visionary-url) means zero latency image placeholders
+- Renders a true-to-size, responsive blurhash placeholder while the image loads, <u>eliminating Cumulative Layout Shift (CLS)</u>
+- Off-screen images are lazily loaded, reducing initial pageload size and request count, <u>improving Interaction to Next Paint (INP)</u>
+- Framework-tested (Remix, Next.js, Vite) with support for both client and server-side rendering (SSR, SSG) environments
+- Additional features: Prevent dragging, user-selection of image
+- Improves Core Web Vitals scores (CLS, and often INP and LCP) which are a primary ranking signal in Google Search
+
+> "We highly recommend site owners achieve good Core Web Vitals for success with Search", [Google Search Central](https://developers.google.com/search/docs/appearance/core-web-vitals)
+
+## Installation
+
+Install via npm, yarn, or pnpm.
+
+```bash
+npm install --save visionary-image
+```
+
+## Getting Started
+
+To render a Visionary Image, first create a Visionary URL.
+
+### Creating a Visionary Image URL
+
+To create a Visionary URL from a public image URL see [Visionary URL Generator](#).
+
+To generate Visionary data from a local file, use the [Drag-and-Drop Blurhash Generator](#).
+
+- Generate a Visionary URL at [https://visionary.cloud/url-generator](https://visionary.cloud/url-generator)
+- Copy a URL from your [Visionary Dashboard](https://visionary.cloud/dashboard)
+- Use this [sample URL]()
+
+### Render image component
+
+```tsx
+import { Image } from "visionary-image";
+
+const imageUrl = "<visionary url or code>";
+const altText = "Nighttime stroll in Tokyo, neon-lit with a purple glow";
+
+const App = () => {
+  <div>
+    <Image alt={altText} src={imageUrl} />
+  </div>;
+};
+```
+
+## Component Props
+
+| Name                              | Description                                                                                                                                                                              |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `alt` <br/> string                | Image `alt` tag. Adding alt text to images is highly recommended to accommodate accessible devices and improve discoverability.                                                          |
+| `bgColorAlpha` <br/> number       | Base layer (background color) alpha channel.<br /> Default: `0.7`                                                                                                                        |
+| `className` <br/> string          | Classname applied to the container `div` or the fallback `img` element.                                                                                                                  |
+| `debug` <br/> boolean             | Prints handy debug info to the console (Visionary URL data, render times).                                                                                                               |
+| `disableBlurLayer` <br/> boolean  | Disables rendering of the blur (canvas) layer.                                                                                                                                           |
+| `disableImageLayer` <br/> boolean | Disables rendering of the image layer.                                                                                                                                                   |
+| `hideImageLayer` <br/> boolean    | Hides the image layer, revealing the blur layer underneath.                                                                                                                              |
+| `lazy` <br/> boolean              | Should image lazily load. <br/> Default: `true`                                                                                                                                          |
+| `onClick` <br/> function          | Callback function to invoke when the image is clicked. function.                                                                                                                         |
+| `onError` <br/> function          | Error callback function.                                                                                                                                                                 |
+| `onLoad` <br/> function           | Image loaded callback function.                                                                                                                                                          |
+| `preventDrag` <br/>boolean        | Prevents user from dragging the image element.                                                                                                                                           |
+| `preventSelection` <br/>boolean   | Prevents user from highlighting the image element.                                                                                                                                       |
+| `punch` <br/>number               | Blurhash punch parameter.<br /> Default: `1`                                                                                                                                             |
+| `src` <br/>string                 | Visionary URL, Visionary Code, or ordinary image URL.<br/> If `src` contains Visionary data, placeholders will be rendered, otherwise falls back to an `img` element. <br/> **required** |
+
+### More Props
+
+|                   |                                                                                                                                                                          |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `height`, `width` | If set, will override internally computed image dimensions. By default, Visionary renders optimally sized images, using the aspect-ratio and max-width placeholder data. |

package/dist/visionary-image.d.ts

@@ -0,0 +1,79 @@
+import { CSSProperties } from 'react';
+import { ImageSizeToken } from 'visionary-url';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { VisionaryImageOptions } from 'visionary-url';
+
+declare const Image_2: ({ alt: altText, bgColorAlpha, className, debug, disableBlurLayer, disableImageLayer, endpoint, height: userHeight, hideImageLayer, lazy, onClick, onError, onLoad, preventDrag, preventSelection, punch, size, src, style: userStyles, width: userWidth, }: VisionaryImageProps) => JSX_2.Element;
+export { Image_2 as Image }
+
+export declare interface VisionaryImageProps {
+    /**
+     * Image `alt` tag; Adding alt text to images is *highly* recommended to accommodate accessible devices and improve discoverability.
+     */
+    alt?: string;
+    /**
+     * Base layer (background color) alpha channel (default: 0.7)
+     */
+    bgColorAlpha?: number;
+    /** Classname applied to the container `div` or the fallback `img` element. */
+    className?: string;
+    /**
+     * Print debug info (Visionary data, render times) to the console
+     */
+    debug?: boolean;
+    /**
+     * Disable rendering of blur layer
+     */
+    disableBlurLayer?: boolean;
+    /**
+     * Disable rendering of image layer
+     */
+    disableImageLayer?: boolean;
+    /** Custom endpoint for image URLs (when using `generateVisionaryUrl()`) */
+    endpoint?: string;
+    height?: number | string;
+    /**
+     * Hides the image layer via CSS
+     */
+    hideImageLayer?: boolean;
+    /**
+     * Should image load lazily (default: true)
+     */
+    lazy?: boolean;
+    /**
+     * Callback function to run after click
+     */
+    onClick?: () => void;
+    /**
+     * Callback function to run if image resource failed to load
+     */
+    onError?: () => void;
+    /**
+     * Callback function to run after image load
+     */
+    onLoad?: () => void;
+    options?: VisionaryImageOptions;
+    /**
+     * Prevents user from dragging the image element
+     */
+    preventDrag?: boolean;
+    /**
+     * Prevents user from highlighting the image element
+     */
+    preventSelection?: boolean;
+    /**
+     * Blurhash punch parameter (default: 1)
+     */
+    punch?: number;
+    /** If specified, overrides the size specified in a Visionary URL */
+    size?: ImageSizeToken;
+    /**
+     * Image `src` prop; if `src` contains a Visionary code, a Visionary image will be rendered, otherwise we fall back to a native `<img />` tag
+     */
+    src: string;
+    /** Styles are applied to the Visionary container (or the fallback <img> if a Visionary Image is not rendered) */
+    style?: CSSProperties;
+    width?: number | string;
+}
+
+export { }

package/dist/visionary-image.es.js

@@ -0,0 +1,505 @@
+(function(){"use strict";try{if(typeof document<"u"){var e=document.createElement("style");e.id="v7y-styles",e.appendChild(document.createTextNode('.v7y_7587:before{content:"";display:block;padding-top:var(--v-ar)}.v7y_f2b7{display:none}.v7y_b8c0{-webkit-user-drag:none;pointer-events:none}.v7y_e0dd{-webkit-user-select:none;user-select:none}')),document.head.appendChild(e)}}catch(n){console.error("vite-plugin-css-injected-by-js",n)}})();
+import { jsx as W, jsxs as yt } from "react/jsx-runtime";
+import { useRef as Y, useCallback as q, useState as wt, useEffect as xt, useLayoutEffect as Et, useMemo as It } from "react";
+function Rt(t) {
+  return t && t.__esModule && Object.prototype.hasOwnProperty.call(t, "default") ? t.default : t;
+}
+var et = { exports: {} };
+/*!
+	Copyright (c) 2018 Jed Watson.
+	Licensed under the MIT License (MIT), see
+	http://jedwatson.github.io/classnames
+*/
+(function(t) {
+  (function() {
+    var n = {}.hasOwnProperty;
+    function e() {
+      for (var r = "", s = 0; s < arguments.length; s++) {
+        var a = arguments[s];
+        a && (r = c(r, o(a)));
+      }
+      return r;
+    }
+    function o(r) {
+      if (typeof r == "string" || typeof r == "number")
+        return r;
+      if (typeof r != "object")
+        return "";
+      if (Array.isArray(r))
+        return e.apply(null, r);
+      if (r.toString !== Object.prototype.toString && !r.toString.toString().includes("[native code]"))
+        return r.toString();
+      var s = "";
+      for (var a in r)
+        n.call(r, a) && r[a] && (s = c(s, a));
+      return s;
+    }
+    function c(r, s) {
+      return s ? r ? r + " " + s : r + s : r;
+    }
+    t.exports ? (e.default = e, t.exports = e) : window.classNames = e;
+  })();
+})(et);
+var At = et.exports;
+const K = /* @__PURE__ */ Rt(At), Nt = (t, { root: n, rootMargin: e, threshold: o } = {}, c = []) => {
+  const r = Y(null), s = Y(null);
+  return q((i) => {
+    r.current && s.current && (s.current.unobserve(r.current), s.current.disconnect(), s.current = null), i && (s.current = new IntersectionObserver(t, { root: n, rootMargin: e, threshold: o }), s.current.observe(i), r.current = i);
+  }, [r, n, e, JSON.stringify(o), ...c]);
+}, Ot = ({ root: t, rootMargin: n, threshold: e, unobserveOnEnter: o, target: c, onEnter: r, onLeave: s, defaultInView: a } = {}, i = []) => {
+  const [d, h] = wt({
+    inView: a || !1,
+    entry: null,
+    observer: null
+  }), f = q(([p], l) => {
+    const b = l.thresholds.some((g) => p.intersectionRatio >= g) && p.isIntersecting;
+    h({
+      inView: b,
+      entry: p,
+      observer: l
+    }), b && o && (l.unobserve(p.target), l.disconnect()), b ? r == null || r(p, l) : s == null || s(p, l);
+  }, [r, s, o]), m = Nt(f, { root: t, rootMargin: n, threshold: e }, [o, ...i]);
+  return xt(() => {
+    c != null && c.current && m(c.current);
+  }, [c, m]), [m, d.inView, d.entry, d.observer];
+};
+var L = /* @__PURE__ */ ((t) => (t.AUTO = "auto", t.AVIF = "avif", t.JPEG = "jpeg", t.WEBP = "webp", t))(L || {}), y = /* @__PURE__ */ ((t) => (t.xs = "xs", t.sm = "sm", t.md = "md", t.lg = "lg", t.xl = "xl", t.xxl = "xxl", t["4k"] = "4k", t["5k"] = "5k", t.full = "full", t))(y || {}), C = /* @__PURE__ */ ((t) => (t.DEBUG = "debug", t.DOWNLOAD = "download", t))(C || {});
+const Ut = "https://link.visionary.cloud";
+L.AUTO, y.lg;
+const Z = {
+  [y.xs]: 160,
+  [y.sm]: 320,
+  [y.md]: 640,
+  [y.lg]: 1280,
+  [y.xl]: 1920,
+  [y.xxl]: 2560,
+  [y["4k"]]: 3840,
+  [y["5k"]]: 5120,
+  [y.full]: 0
+};
+Object.keys(Z).reduce(
+  (t, n) => {
+    const e = n, o = Z[e];
+    return o && (t[o] = e), t;
+  },
+  {}
+);
+const rt = "!";
+var St = Object.defineProperty, Tt = (t, n, e) => n in t ? St(t, n, { enumerable: !0, configurable: !0, writable: !0, value: e }) : t[n] = e, _t = (t, n, e) => Tt(t, typeof n != "symbol" ? n + "" : n, e), J = {}, j = {};
+Object.defineProperty(j, "__esModule", { value: !0 });
+function Ct(t) {
+  return String.fromCharCode(parseInt(t.slice(1), 16));
+}
+function Dt(t) {
+  return btoa(encodeURIComponent(t).replace(/%[0-9A-F]{2}/g, Ct));
+}
+j.encode = Dt;
+function Pt(t) {
+  return `%${`00${t.charCodeAt(0).toString(16)}`.slice(-2)}`;
+}
+function Vt(t) {
+  return decodeURIComponent(Array.from(atob(t), Pt).join(""));
+}
+j.decode = Vt;
+Object.defineProperty(J, "__esModule", { value: !0 });
+const ot = j;
+function $t(t) {
+  return ot.decode(t.replace(/\-/g, "+").replace(/_/g, "/"));
+}
+var Lt = J.decode = $t;
+function jt(t) {
+  return ot.encode(t).replace(/\//g, "_").replace(/\+/g, "-").replace(/=+$/, "");
+}
+var kt = J.encode = jt;
+const zt = (t) => t.filter(Boolean), Q = (t) => {
+  try {
+    return new URL(t);
+  } catch {
+    return null;
+  }
+}, k = (t = "") => /^[A-Za-z0-9_-]*$/.test(t), Bt = (t) => {
+  const { altText: n, bcc: e, blurhash: o, blurhashX: c, blurhashY: r, sourceHeight: s, sourceWidth: a, url: i } = t;
+  if (!i || !a || !s)
+    return new Error("Cannot construct visionary code: missing required url/width/height");
+  const d = [i, a, s];
+  return !e || (d.push(e), !o || !c || !r) || (d.push(o, c, r), n && n.length && d.push(n)), Mt(d);
+}, Mt = (t) => kt(t.join(rt)), st = (t) => {
+  if (typeof t != "string")
+    return null;
+  const n = t.trim();
+  if (!n.length || !k(n))
+    return null;
+  const e = Lt(n);
+  if (!e)
+    return null;
+  const o = e.split(rt);
+  if (o.length < 3)
+    return null;
+  const [c, r, s, a, i, d, h, f] = o, m = c.trim();
+  if (!m.length)
+    return console.error("Cannot parse code, empty file id"), null;
+  const p = Number(r.trim()), l = Number(s.trim());
+  if (isNaN(p) || isNaN(l) || !p || !l)
+    return console.error("Cannot parse Visionary Code: invalid image dimensions", r, s), null;
+  const v = Number(d) ?? 0, b = Number(h) ?? 0;
+  return v < 1 || b < 1 ? (console.error(
+    "Cannot parse Visionary Code: invalid blurhash x, y component dimensions",
+    v,
+    b
+  ), null) : {
+    altText: f,
+    bcc: a,
+    blurhash: i,
+    blurhashX: v,
+    blurhashY: b,
+    sourceHeight: l,
+    sourceWidth: p,
+    url: m
+  };
+};
+class Gt extends Error {
+  constructor() {
+    super(...arguments), _t(this, "message", "invalid endpoint URL (does it contain http/https?)");
+  }
+}
+const Wt = (t) => t === C.DEBUG, Ft = (t) => t === C.DOWNLOAD, Ht = (t) => Object.values(L).includes(t), ct = (t) => Object.values(y).includes(t), Xt = (t = []) => {
+  const n = {};
+  for (const e of t)
+    ct(e) ? n.size = y[e] : Wt(e) ? n.debug = !0 : Ft(e) ? n.download = !0 : Ht(e) && (n.format = e);
+  return n;
+}, Yt = (t) => {
+  if (!t || typeof t != "object")
+    return null;
+  const n = [];
+  return t.debug && n.push(C.DEBUG), t.download && n.push(C.DOWNLOAD), t.format && t.format !== L.AUTO && n.push(t.format), t.size && ct(t.size) && n.push(t.size), n.length ? n.sort().join(",") : null;
+}, Zt = (t) => {
+  if (k(t)) {
+    const n = st(t);
+    if (n)
+      return {
+        fields: n,
+        options: {}
+      };
+  }
+  return qt(t);
+}, qt = (t) => {
+  if (!t)
+    return null;
+  const n = t.trim();
+  if (!n)
+    return null;
+  try {
+    const e = Kt(n);
+    if (!e)
+      return null;
+    const { code: o, optionTokens: c } = e, r = st(o);
+    if (!r)
+      return null;
+    const s = Xt(c);
+    return {
+      fields: r,
+      options: s
+    };
+  } catch (e) {
+    e instanceof Error ? console.error(`Error parsing URL: ${e.message}`, e) : console.error("uncaught error", e);
+  }
+  return null;
+}, Jt = (t, n) => {
+  const e = Bt(t);
+  if (e instanceof Error)
+    return null;
+  let o = null;
+  if (n != null && n.endpoint && (o = Q(n == null ? void 0 : n.endpoint), !o))
+    throw new Gt(
+      "Cannot construct URL: bad endpoint. Ensure endpoint starts with http:// or https://"
+    );
+  o || (o = Q(Ut));
+  const c = [o.origin, "image", e], r = n ? Yt(n) : null;
+  return r && c.push(r), n != null && n.filename ? c.push(n.filename) : c.push("image.jpg"), c.join("/");
+}, Kt = (t) => {
+  try {
+    const n = new URL(t), e = zt(n.pathname.split("/"));
+    if (e[0] !== "image" || ![3, 4].includes(e.length))
+      throw new Error("Unrecognized URL");
+    const o = e[1].trim();
+    if (!o.length || !k(o))
+      throw new Error("URL is not formatted as base64url");
+    if (e.length === 4) {
+      const c = e[2].split(",");
+      return {
+        code: o,
+        optionTokens: c
+      };
+    }
+    if (e.length === 3)
+      return {
+        code: o,
+        optionTokens: []
+      };
+  } catch {
+    return null;
+  }
+  return null;
+}, it = 0.7, at = 1, O = 24, Qt = y.lg, lt = process.env.NODE_ENV, tn = lt === "development", ut = typeof document > "u", nn = lt === "test", en = ut ? () => {
+} : Et, rn = "<visionary>", N = (t, ...n) => {
+  !console || typeof console.log != "function" || console.log(`${rn} ${t}`, ...n);
+}, on = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz#$%*+,-.:;=?@[]^_{|}~", V = (t, n, e) => {
+  let o = 0;
+  for (; n < e; )
+    o *= 83, o += on.indexOf(t[n++]);
+  return o;
+}, dt = Math.pow, D = Math.PI, sn = D * 2, ft = 3294.6, pt = 269.025, cn = (t) => t > 10.31475 ? dt(t / pt + 0.052132, 2.4) : t / ft, F = (t) => ~~(t > 1227e-8 ? pt * dt(t, 0.416666) - 13.025 : t * ft + 1), _ = (t) => (t < 0 ? -1 : 1) * t * t, tt = (t) => {
+  for (t += D / 2; t > D; )
+    t -= sn;
+  const n = 1.27323954 * t - 0.405284735 * _(t);
+  return 0.225 * (_(n) - n) + n;
+};
+function an(t) {
+  const n = V(t, 2, 6);
+  return [n >> 16, n >> 8 & 255, n & 255];
+}
+function ln(t, n, e, o) {
+  const c = V(t, 0, 1), r = c % 9 + 1, s = ~~(c / 9) + 1, a = r * s;
+  let i = 0, d = 0, h = 0, f = 0, m = 0, p = 0, l = 0, v = 0, b = 0, g = 0, w = 0, E = 0, u = 0, I = 0;
+  const U = (V(t, 1, 2) + 1) / 13446 * (o | 1), x = new Float64Array(a * 3), z = an(t);
+  for (i = 0; i < 3; i++)
+    x[i] = cn(z[i]);
+  for (i = 1; i < a; i++)
+    I = V(t, 4 + i * 2, 6 + i * 2), x[i * 3] = _(~~(I / (19 * 19)) - 9) * U, x[i * 3 + 1] = _(~~(I / 19) % 19 - 9) * U, x[i * 3 + 2] = _(I % 19 - 9) * U;
+  const S = n * 4, R = new Uint8ClampedArray(S * e);
+  for (f = 0; f < e; f++)
+    for (E = D * f / e, h = 0; h < n; h++) {
+      for (m = 0, p = 0, l = 0, u = D * h / n, d = 0; d < s; d++)
+        for (b = tt(E * d), i = 0; i < r; i++)
+          v = tt(u * i) * b, g = (i + d * r) * 3, m += x[g] * v, p += x[g + 1] * v, l += x[g + 2] * v;
+      w = 4 * h + f * S, R[w] = F(m), R[w + 1] = F(p), R[w + 2] = F(l), R[w + 3] = 255;
+    }
+  return R;
+}
+const $ = (t) => {
+  try {
+    return new URL(t);
+  } catch {
+    return null;
+  }
+}, un = (t, n) => `rgba(${t.r},${t.g},${t.b},${n})`, H = (t) => tn || nn ? {
+  "data-testid": t
+} : {}, dn = (t, n) => n ? {
+  "data-fileid": t
+} : {}, nt = (t, n) => Math.min(t, n), fn = (t) => {
+  let n = t.replace(/^#/, "");
+  if (n.length !== 3 && n.length !== 6)
+    return null;
+  n.length === 3 && (n = `${n[0]}${n[0]}${n[1]}${n[1]}${n[2]}${n[2]}`);
+  const e = parseInt(n.slice(0, 2), 16), o = parseInt(n.slice(2, 4), 16);
+  return { b: parseInt(n.slice(4, 6), 16), g: o, r: e };
+}, A = (t, n = 0) => {
+  const e = Math.pow(10, n);
+  return Math.round(t * e) / e;
+}, pn = (t, n) => {
+  const e = $(t), o = $(n);
+  return !e || !o ? t : (o.pathname = e.pathname, o.search = e.search, o.toString());
+}, hn = (t, n = {}, e = it, o = at) => {
+  if (!t)
+    return null;
+  try {
+    n.debug && N("input imageSrc:", t);
+    const c = Zt(t);
+    if (n.debug && N("Visionary URL data: ", c), !c)
+      throw new Error("Could not parse Visionary URL");
+    const { fields: r, options: s } = c;
+    if (r.sourceWidth < 1 || r.sourceHeight < 1)
+      throw new Error("Invalid image dimensions");
+    const a = r.sourceWidth / r.sourceHeight, i = (n == null ? void 0 : n.size) ?? s.size ?? Qt, d = Z[i];
+    let h = 0, f = 0, m = 0;
+    if (a >= 1) {
+      f = h = nt(d, r.sourceWidth);
+      const g = A(f / a);
+      m = A(f / g, 6);
+    } else
+      h = nt(d, r.sourceHeight), f = A(h * a), m = A(f / h, 6);
+    const p = A(100 / m, 6), l = {
+      ...r,
+      arPaddingTop: `${p}%`,
+      aspectRatio: m,
+      maxWidth: f,
+      src: t
+    }, v = $(r.url);
+    if (v)
+      l.src = v.toString();
+    else if (!$(t) && k(r.url)) {
+      const g = Jt(r, {
+        endpoint: n.endpoint,
+        size: i
+      });
+      g && (l.src = g);
+    }
+    n.endpoint && (l.src = pn(l.src, n.endpoint));
+    const b = r.bcc ? fn(r.bcc) : null;
+    if (b && (l.backgroundColor = un(b, e)), !ut && r.blurhash && !n.disableBlurLayer) {
+      const g = performance.now(), w = ln(r.blurhash, O, O, o), E = performance.now() - g;
+      n.debug && N(`Blurhash decode time: ${A(E, 1)} ms`), w && (l.pixels = w);
+    }
+    return n.debug && N("Visionary Image state: ", l), l;
+  } catch {
+    return null;
+  }
+}, ht = {
+  bottom: 0,
+  left: 0,
+  position: "absolute",
+  right: 0,
+  top: 0
+}, mn = {
+  ...ht,
+  maxHeight: "100%",
+  maxWidth: "100%"
+}, gn = {
+  ...ht,
+  height: "100%",
+  width: "100%"
+}, X = {
+  CANVAS: "canvas",
+  CONTAINER: "container",
+  IMAGE: "image"
+}, bn = "v7y_7587", vn = "v7y_f2b7", yn = "v7y_b8c0", wn = "v7y_e0dd", P = {
+  container: bn,
+  hidden: vn,
+  preventDrag: yn,
+  preventSelection: wn
+}, An = ({
+  alt: t,
+  bgColorAlpha: n = it,
+  className: e,
+  debug: o = !1,
+  disableBlurLayer: c = !1,
+  disableImageLayer: r = !1,
+  endpoint: s,
+  height: a,
+  hideImageLayer: i,
+  lazy: d = !0,
+  onClick: h,
+  onError: f,
+  onLoad: m,
+  preventDrag: p = !1,
+  preventSelection: l = !1,
+  punch: v = at,
+  size: b,
+  src: g,
+  style: w,
+  width: E
+}) => {
+  const u = It(() => hn(g, {
+    debug: o,
+    disableBlurLayer: c,
+    endpoint: s,
+    size: b
+  }, n, v), [n, o, c, s, v, b, g]), I = Y(null), [U, x] = Ot();
+  en(
+    function() {
+      if (!I.current || !(u != null && u.blurhash))
+        return;
+      if (!u.pixels) {
+        console.warn("No pixel data passed in, skipping");
+        return;
+      }
+      const bt = performance.now(), M = I.current.getContext("2d");
+      if (!M) {
+        console.warn("Cannot access canvasRenderingContext, skipping");
+        return;
+      }
+      const G = M.createImageData(O, O);
+      if (!G) {
+        console.warn("Could not create ImageData on CanvasRenderingContext");
+        return;
+      }
+      if (G.data.set(u.pixels), M.putImageData(G, 0, 0), o) {
+        const vt = performance.now() - bt;
+        N(`Canvas render time: ${A(vt, 1)} ms`);
+      }
+    },
+    [u == null ? void 0 : u.blurhash, u == null ? void 0 : u.pixels, o]
+  );
+  const z = q(
+    (T) => {
+      o && N("Image load error ", T), f && f();
+    },
+    [o, f]
+  ), S = {
+    alt: t,
+    loading: !d || x ? "eager" : "lazy",
+    onLoad: m
+  };
+  if (!u) {
+    o && N("Not a Visionary URL, rendering fallback <img />");
+    const T = {
+      ...S,
+      className: e,
+      height: a,
+      onClick: h,
+      onError: f,
+      src: g,
+      style: w,
+      width: E
+    };
+    return /* @__PURE__ */ W("img", { ...T });
+  }
+  const R = K(P.container, e, {
+    [P.preventDrag]: !!p,
+    [P.preventSelection]: !!l
+  }), B = {
+    ...{
+      "--v-ar": u.arPaddingTop
+    },
+    aspectRatio: u.aspectRatio,
+    backgroundColor: (u == null ? void 0 : u.backgroundColor) ?? void 0,
+    maxWidth: u.maxWidth,
+    position: "relative",
+    width: "100%",
+    ...w
+  };
+  E && (B.width = E), a && (B.height = a);
+  const mt = {
+    onClick: h
+  }, gt = K({
+    [P.hidden]: !!i
+  });
+  return /* @__PURE__ */ yt(
+    "div",
+    {
+      className: R,
+      ref: U,
+      style: B,
+      ...dn(u.url, o),
+      ...H(X.CONTAINER),
+      ...mt,
+      children: [
+        !c && /* @__PURE__ */ W(
+          "canvas",
+          {
+            height: O,
+            ref: I,
+            style: gn,
+            width: O,
+            ...H(X.CANVAS)
+          }
+        ),
+        !r && // eslint-disable-next-line jsx-a11y/alt-text -- `sharedImgProps` includes alt tag
+        /* @__PURE__ */ W(
+          "img",
+          {
+            ...S,
+            ...H(X.IMAGE),
+            className: gt,
+            onError: z,
+            src: u.src,
+            style: mn
+          }
+        )
+      ]
+    }
+  );
+};
+export {
+  An as Image
+};

package/dist/visionary-image.umd.js

@@ -0,0 +1,6 @@
+(function(){"use strict";try{if(typeof document<"u"){var e=document.createElement("style");e.id="v7y-styles",e.appendChild(document.createTextNode('.v7y_7587:before{content:"";display:block;padding-top:var(--v-ar)}.v7y_f2b7{display:none}.v7y_b8c0{-webkit-user-drag:none;pointer-events:none}.v7y_e0dd{-webkit-user-select:none;user-select:none}')),document.head.appendChild(e)}}catch(n){console.error("vite-plugin-css-injected-by-js",n)}})();
+(function(E,R){typeof exports=="object"&&typeof module<"u"?R(exports,require("react/jsx-runtime"),require("react")):typeof define=="function"&&define.amd?define(["exports","react/jsx-runtime","react"],R):(E=typeof globalThis<"u"?globalThis:E||self,R(E.VisionaryImage={},E.jsxRuntime,E.React))})(this,function(E,R,x){"use strict";function me(e){return e&&e.__esModule&&Object.prototype.hasOwnProperty.call(e,"default")?e.default:e}var K={exports:{}};/*!
+	Copyright (c) 2018 Jed Watson.
+	Licensed under the MIT License (MIT), see
+	http://jedwatson.github.io/classnames
+*/(function(e){(function(){var t={}.hasOwnProperty;function n(){for(var r="",s=0;s<arguments.length;s++){var a=arguments[s];a&&(r=i(r,o(a)))}return r}function o(r){if(typeof r=="string"||typeof r=="number")return r;if(typeof r!="object")return"";if(Array.isArray(r))return n.apply(null,r);if(r.toString!==Object.prototype.toString&&!r.toString.toString().includes("[native code]"))return r.toString();var s="";for(var a in r)t.call(r,a)&&r[a]&&(s=i(s,a));return s}function i(r,s){return s?r?r+" "+s:r+s:r}e.exports?(n.default=n,e.exports=n):window.classNames=n})()})(K);var ge=K.exports;const Q=me(ge),be=(e,{root:t,rootMargin:n,threshold:o}={},i=[])=>{const r=x.useRef(null),s=x.useRef(null);return x.useCallback(c=>{r.current&&s.current&&(s.current.unobserve(r.current),s.current.disconnect(),s.current=null),c&&(s.current=new IntersectionObserver(e,{root:t,rootMargin:n,threshold:o}),s.current.observe(c),r.current=c)},[r,t,n,JSON.stringify(o),...i])},ve=({root:e,rootMargin:t,threshold:n,unobserveOnEnter:o,target:i,onEnter:r,onLeave:s,defaultInView:a}={},c=[])=>{const[d,h]=x.useState({inView:a||!1,entry:null,observer:null}),f=x.useCallback(([p],l)=>{const b=l.thresholds.some(g=>p.intersectionRatio>=g)&&p.isIntersecting;h({inView:b,entry:p,observer:l}),b&&o&&(l.unobserve(p.target),l.disconnect()),b?r==null||r(p,l):s==null||s(p,l)},[r,s,o]),m=be(f,{root:e,rootMargin:t,threshold:n},[o,...c]);return x.useEffect(()=>{i!=null&&i.current&&m(i.current)},[i,m]),[m,d.inView,d.entry,d.observer]};var $=(e=>(e.AUTO="auto",e.AVIF="avif",e.JPEG="jpeg",e.WEBP="webp",e))($||{}),y=(e=>(e.xs="xs",e.sm="sm",e.md="md",e.lg="lg",e.xl="xl",e.xxl="xxl",e["4k"]="4k",e["5k"]="5k",e.full="full",e))(y||{}),C=(e=>(e.DEBUG="debug",e.DOWNLOAD="download",e))(C||{});const ye="https://link.visionary.cloud";$.AUTO,y.lg;const G={[y.xs]:160,[y.sm]:320,[y.md]:640,[y.lg]:1280,[y.xl]:1920,[y.xxl]:2560,[y["4k"]]:3840,[y["5k"]]:5120,[y.full]:0};Object.keys(G).reduce((e,t)=>{const n=t,o=G[n];return o&&(e[o]=n),e},{});const ee="!";var we=Object.defineProperty,xe=(e,t,n)=>t in e?we(e,t,{enumerable:!0,configurable:!0,writable:!0,value:n}):e[t]=n,Ie=(e,t,n)=>xe(e,typeof t!="symbol"?t+"":t,n),W={},L={};Object.defineProperty(L,"__esModule",{value:!0});function Ee(e){return String.fromCharCode(parseInt(e.slice(1),16))}function Re(e){return btoa(encodeURIComponent(e).replace(/%[0-9A-F]{2}/g,Ee))}L.encode=Re;function Ae(e){return`%${`00${e.charCodeAt(0).toString(16)}`.slice(-2)}`}function Se(e){return decodeURIComponent(Array.from(atob(e),Ae).join(""))}L.decode=Se,Object.defineProperty(W,"__esModule",{value:!0});const te=L;function Te(e){return te.decode(e.replace(/\-/g,"+").replace(/_/g,"/"))}var Ne=W.decode=Te;function Oe(e){return te.encode(e).replace(/\//g,"_").replace(/\+/g,"-").replace(/=+$/,"")}var Ue=W.encode=Oe;const Ce=e=>e.filter(Boolean),ne=e=>{try{return new URL(e)}catch{return null}},k=(e="")=>/^[A-Za-z0-9_-]*$/.test(e),De=e=>{const{altText:t,bcc:n,blurhash:o,blurhashX:i,blurhashY:r,sourceHeight:s,sourceWidth:a,url:c}=e;if(!c||!a||!s)return new Error("Cannot construct visionary code: missing required url/width/height");const d=[c,a,s];return!n||(d.push(n),!o||!i||!r)||(d.push(o,i,r),t&&t.length&&d.push(t)),Pe(d)},Pe=e=>Ue(e.join(ee)),re=e=>{if(typeof e!="string")return null;const t=e.trim();if(!t.length||!k(t))return null;const n=Ne(t);if(!n)return null;const o=n.split(ee);if(o.length<3)return null;const[i,r,s,a,c,d,h,f]=o,m=i.trim();if(!m.length)return console.error("Cannot parse code, empty file id"),null;const p=Number(r.trim()),l=Number(s.trim());if(isNaN(p)||isNaN(l)||!p||!l)return console.error("Cannot parse Visionary Code: invalid image dimensions",r,s),null;const v=Number(d)??0,b=Number(h)??0;return v<1||b<1?(console.error("Cannot parse Visionary Code: invalid blurhash x, y component dimensions",v,b),null):{altText:f,bcc:a,blurhash:c,blurhashX:v,blurhashY:b,sourceHeight:l,sourceWidth:p,url:m}};class _e extends Error{constructor(){super(...arguments),Ie(this,"message","invalid endpoint URL (does it contain http/https?)")}}const je=e=>e===C.DEBUG,Ve=e=>e===C.DOWNLOAD,$e=e=>Object.values($).includes(e),oe=e=>Object.values(y).includes(e),Le=(e=[])=>{const t={};for(const n of e)oe(n)?t.size=y[n]:je(n)?t.debug=!0:Ve(n)?t.download=!0:$e(n)&&(t.format=n);return t},ke=e=>{if(!e||typeof e!="object")return null;const t=[];return e.debug&&t.push(C.DEBUG),e.download&&t.push(C.DOWNLOAD),e.format&&e.format!==$.AUTO&&t.push(e.format),e.size&&oe(e.size)&&t.push(e.size),t.length?t.sort().join(","):null},ze=e=>{if(k(e)){const t=re(e);if(t)return{fields:t,options:{}}}return Be(e)},Be=e=>{if(!e)return null;const t=e.trim();if(!t)return null;try{const n=Ge(t);if(!n)return null;const{code:o,optionTokens:i}=n,r=re(o);if(!r)return null;const s=Le(i);return{fields:r,options:s}}catch(n){n instanceof Error?console.error(`Error parsing URL: ${n.message}`,n):console.error("uncaught error",n)}return null},Me=(e,t)=>{const n=De(e);if(n instanceof Error)return null;let o=null;if(t!=null&&t.endpoint&&(o=ne(t==null?void 0:t.endpoint),!o))throw new _e("Cannot construct URL: bad endpoint. Ensure endpoint starts with http:// or https://");o||(o=ne(ye));const i=[o.origin,"image",n],r=t?ke(t):null;return r&&i.push(r),t!=null&&t.filename?i.push(t.filename):i.push("image.jpg"),i.join("/")},Ge=e=>{try{const t=new URL(e),n=Ce(t.pathname.split("/"));if(n[0]!=="image"||![3,4].includes(n.length))throw new Error("Unrecognized URL");const o=n[1].trim();if(!o.length||!k(o))throw new Error("URL is not formatted as base64url");if(n.length===4){const i=n[2].split(",");return{code:o,optionTokens:i}}if(n.length===3)return{code:o,optionTokens:[]}}catch{return null}return null},se=.7,ie=1,U=24,We=y.lg,ce=process.env.NODE_ENV,Fe=ce==="development",ae=typeof document>"u",He=ce==="test",qe=ae?()=>{}:x.useLayoutEffect,Xe="<visionary>",T=(e,...t)=>{!console||typeof console.log!="function"||console.log(`${Xe} ${e}`,...t)},Ye="0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz#$%*+,-.:;=?@[]^_{|}~",z=(e,t,n)=>{let o=0;for(;t<n;)o*=83,o+=Ye.indexOf(e[t++]);return o},le=Math.pow,D=Math.PI,Ze=D*2,ue=3294.6,de=269.025,Je=e=>e>10.31475?le(e/de+.052132,2.4):e/ue,F=e=>~~(e>1227e-8?de*le(e,.416666)-13.025:e*ue+1),P=e=>(e<0?-1:1)*e*e,fe=e=>{for(e+=D/2;e>D;)e-=Ze;const t=1.27323954*e-.405284735*P(e);return .225*(P(t)-t)+t};function Ke(e){const t=z(e,2,6);return[t>>16,t>>8&255,t&255]}function Qe(e,t,n,o){const i=z(e,0,1),r=i%9+1,s=~~(i/9)+1,a=r*s;let c=0,d=0,h=0,f=0,m=0,p=0,l=0,v=0,b=0,g=0,w=0,A=0,u=0,S=0;const _=(z(e,1,2)+1)/13446*(o|1),I=new Float64Array(a*3),X=Ke(e);for(c=0;c<3;c++)I[c]=Je(X[c]);for(c=1;c<a;c++)S=z(e,4+c*2,6+c*2),I[c*3]=P(~~(S/(19*19))-9)*_,I[c*3+1]=P(~~(S/19)%19-9)*_,I[c*3+2]=P(S%19-9)*_;const j=t*4,O=new Uint8ClampedArray(j*n);for(f=0;f<n;f++)for(A=D*f/n,h=0;h<t;h++){for(m=0,p=0,l=0,u=D*h/t,d=0;d<s;d++)for(b=fe(A*d),c=0;c<r;c++)v=fe(u*c)*b,g=(c+d*r)*3,m+=I[g]*v,p+=I[g+1]*v,l+=I[g+2]*v;w=4*h+f*j,O[w]=F(m),O[w+1]=F(p),O[w+2]=F(l),O[w+3]=255}return O}const B=e=>{try{return new URL(e)}catch{return null}},et=(e,t)=>`rgba(${e.r},${e.g},${e.b},${t})`,H=e=>Fe||He?{"data-testid":e}:{},tt=(e,t)=>t?{"data-fileid":e}:{},pe=(e,t)=>Math.min(e,t),nt=e=>{let t=e.replace(/^#/,"");if(t.length!==3&&t.length!==6)return null;t.length===3&&(t=`${t[0]}${t[0]}${t[1]}${t[1]}${t[2]}${t[2]}`);const n=parseInt(t.slice(0,2),16),o=parseInt(t.slice(2,4),16);return{b:parseInt(t.slice(4,6),16),g:o,r:n}},N=(e,t=0)=>{const n=Math.pow(10,t);return Math.round(e*n)/n},rt=(e,t)=>{const n=B(e),o=B(t);return!n||!o?e:(o.pathname=n.pathname,o.search=n.search,o.toString())},ot=(e,t={},n=se,o=ie)=>{if(!e)return null;try{t.debug&&T("input imageSrc:",e);const i=ze(e);if(t.debug&&T("Visionary URL data: ",i),!i)throw new Error("Could not parse Visionary URL");const{fields:r,options:s}=i;if(r.sourceWidth<1||r.sourceHeight<1)throw new Error("Invalid image dimensions");const a=r.sourceWidth/r.sourceHeight,c=(t==null?void 0:t.size)??s.size??We,d=G[c];let h=0,f=0,m=0;if(a>=1){f=h=pe(d,r.sourceWidth);const g=N(f/a);m=N(f/g,6)}else h=pe(d,r.sourceHeight),f=N(h*a),m=N(f/h,6);const p=N(100/m,6),l={...r,arPaddingTop:`${p}%`,aspectRatio:m,maxWidth:f,src:e},v=B(r.url);if(v)l.src=v.toString();else if(!B(e)&&k(r.url)){const g=Me(r,{endpoint:t.endpoint,size:c});g&&(l.src=g)}t.endpoint&&(l.src=rt(l.src,t.endpoint));const b=r.bcc?nt(r.bcc):null;if(b&&(l.backgroundColor=et(b,n)),!ae&&r.blurhash&&!t.disableBlurLayer){const g=performance.now(),w=Qe(r.blurhash,U,U,o),A=performance.now()-g;t.debug&&T(`Blurhash decode time: ${N(A,1)} ms`),w&&(l.pixels=w)}return t.debug&&T("Visionary Image state: ",l),l}catch{return null}},he={bottom:0,left:0,position:"absolute",right:0,top:0},st={...he,maxHeight:"100%",maxWidth:"100%"},it={...he,height:"100%",width:"100%"},q={CANVAS:"canvas",CONTAINER:"container",IMAGE:"image"},M={container:"v7y_7587",hidden:"v7y_f2b7",preventDrag:"v7y_b8c0",preventSelection:"v7y_e0dd"},ct=({alt:e,bgColorAlpha:t=se,className:n,debug:o=!1,disableBlurLayer:i=!1,disableImageLayer:r=!1,endpoint:s,height:a,hideImageLayer:c,lazy:d=!0,onClick:h,onError:f,onLoad:m,preventDrag:p=!1,preventSelection:l=!1,punch:v=ie,size:b,src:g,style:w,width:A})=>{const u=x.useMemo(()=>ot(g,{debug:o,disableBlurLayer:i,endpoint:s,size:b},t,v),[t,o,i,s,v,b,g]),S=x.useRef(null),[_,I]=ve();qe(function(){if(!S.current||!(u!=null&&u.blurhash))return;if(!u.pixels){console.warn("No pixel data passed in, skipping");return}const ut=performance.now(),Z=S.current.getContext("2d");if(!Z){console.warn("Cannot access canvasRenderingContext, skipping");return}const J=Z.createImageData(U,U);if(!J){console.warn("Could not create ImageData on CanvasRenderingContext");return}if(J.data.set(u.pixels),Z.putImageData(J,0,0),o){const dt=performance.now()-ut;T(`Canvas render time: ${N(dt,1)} ms`)}},[u==null?void 0:u.blurhash,u==null?void 0:u.pixels,o]);const X=x.useCallback(V=>{o&&T("Image load error ",V),f&&f()},[o,f]),j={alt:e,loading:!d||I?"eager":"lazy",onLoad:m};if(!u){o&&T("Not a Visionary URL, rendering fallback <img />");const V={...j,className:n,height:a,onClick:h,onError:f,src:g,style:w,width:A};return R.jsx("img",{...V})}const O=Q(M.container,n,{[M.preventDrag]:!!p,[M.preventSelection]:!!l}),Y={...{"--v-ar":u.arPaddingTop},aspectRatio:u.aspectRatio,backgroundColor:(u==null?void 0:u.backgroundColor)??void 0,maxWidth:u.maxWidth,position:"relative",width:"100%",...w};A&&(Y.width=A),a&&(Y.height=a);const at={onClick:h},lt=Q({[M.hidden]:!!c});return R.jsxs("div",{className:O,ref:_,style:Y,...tt(u.url,o),...H(q.CONTAINER),...at,children:[!i&&R.jsx("canvas",{height:U,ref:S,style:it,width:U,...H(q.CANVAS)}),!r&&R.jsx("img",{...j,...H(q.IMAGE),className:lt,onError:X,src:u.src,style:st})]})};E.Image=ct,Object.defineProperty(E,Symbol.toStringTag,{value:"Module"})});

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "visionary-image",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/visionary-image.umd.js",
+  "module": "./dist/visionary-image.es.js",
+  "source": "./src/index.ts",
+  "types": "./dist/visionary-image.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/visionary-image.es.js",
+      "require": "./dist/visionary-image.umd.js",
+      "types": "./dist/visionary-image.d.ts"
+    }
+  },
+  "license": "ISC",
+  "scripts": {
+    "build": "tsc && npm run clean && vite build",
+    "clean": "rimraf dist/",
+    "dev": "vite",
+    "lint": "tsc --noEmit; eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "build-storybook": "storybook build"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/visionary-ux/visionary-image.git"
+  },
+  "dependencies": {
+    "classnames": "2.5.1",
+    "fast-blurhash": "1.1.2",
+    "react-hook-inview": "4.5.1",
+    "visionary-url": "1.3.1"
+  },
+  "peerDependencies": {
+    "react": ">=16.9.0",
+    "react-dom": ">=16.9.0"
+  },
+  "devDependencies": {
+    "@storybook/addon-essentials": "8.2.7",
+    "@storybook/react": "8.2.7",
+    "@storybook/react-vite": "8.2.7",
+    "@testing-library/react": "14.3.1",
+    "@types/node": "18.19.1",
+    "@types/react": "18.3.1",
+    "@types/react-dom": "18.3.0",
+    "@typescript-eslint/eslint-plugin": "7.15.0",
+    "@typescript-eslint/parser": "7.15.0",
+    "@vitejs/plugin-legacy": "5.4.1",
+    "@vitejs/plugin-react-swc": "3.7.0",
+    "eslint": "8.57.0",
+    "eslint-plugin-jsx-a11y": "6.9.0",
+    "eslint-plugin-react": "7.35.0",
+    "eslint-plugin-react-hooks": "4.6.2",
+    "eslint-plugin-react-refresh": "0.4.9",
+    "eslint-plugin-sort-keys-fix": "1.1.2",
+    "eslint-plugin-storybook": "0.8.0",
+    "eslint-plugin-typescript-sort-keys": "3.2.0",
+    "jsdom": "24.1.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "rimraf": "5.0.8",
+    "sass": "1.69.5",
+    "storybook": "8.2.7",
+    "storybook-dark-mode": "4.0.2",
+    "typescript": "5.5.4",
+    "vite": "5.3.5",
+    "vite-plugin-css-injected-by-js": "3.5.1",
+    "vite-plugin-dts": "3.9.1",
+    "vitest": "2.0.5",
+    "vitest-canvas-mock": "0.3.3"
+  },
+  "keywords": [
+    "blurhash",
+    "cls",
+    "component",
+    "core-web-vitals",
+    "fid",
+    "image",
+    "lcp",
+    "performance",
+    "placeholder",
+    "react",
+    "seo",
+    "speed",
+    "visionary",
+    "web-vitals"
+  ]
+}