@dtwojs/cloudinary 2.7.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dtwo Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @dtwojs/cloudinary
+
+[Cloudinary](https://cloudinary.com) integration with for [Dtwo](https://dtwojs.web.app)
+
+> This is a module for version 3.X of Dtwo.
+
+## Features
+
+- Dtwo 3 ready
+- Useful `CldImage`, `CldOgImage` & `CldVideoPlayer` components
+- Handy `useCldImageUrl` composable
+- Automatically optimize images and deliver in modern formats
+- Remove backgrounds from images
+- Dynamically add image and text overlays to images
+
+## Quick Setup
+
+1. Add `@dtwojs/cloudinary` dependency to your project
+
+```bash
+yarn add @dtwojs/cloudinary 
+npm install @dtwojs/cloudinary
+```
+
+2. Add `@dtwojs/cloudinary` to the `modules` section of `dtwo.config.ts`
+
+```js
+export default defineDtwoConfig({
+  modules: ['@dtwojs/cloudinary'],
+})
+```
+
+3. Create .env file with following `CLOUDINARY_CLOUD_NAME` variable:
+
+```bash
+CLOUDINARY_CLOUD_NAME=<YOUR_CLOUDINARY_CLOUD_NAME>
+```
+
+And that's it! You can now use Cloudinary in Dtwo ✨
+
+```html
+<template>
+  <CldImage
+    src="cld-sample-5"
+    width="987"
+    height="987"
+    alt="My Awesome Image"
+  />
+</template>
+```
+
+## License
+
+[MIT License](./LICENSE)

package/dist/module.cjs

@@ -0,0 +1,5 @@
+module.exports = function(...args) {
+  return import('./module.mjs').then(m => m.default.call(this, ...args))
+}
+const _meta = module.exports.meta = require('./module.json')
+module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.ts

@@ -0,0 +1,14 @@
+import * as _dtwo_schema from '@dtwo/schema';
+import { ConfigOptions } from '@cloudinary-util/url-loader';
+
+type ModuleOptions = {
+    cloudName?: string;
+    uploadPreset?: string;
+    apiKey?: string;
+    analytics?: boolean;
+    cloud?: ConfigOptions["cloud"];
+    url?: ConfigOptions["url"];
+};
+declare const _default: _dtwo_schema.DtwoModule<ModuleOptions>;
+
+export { ModuleOptions, _default as default };

package/dist/module.json

@@ -0,0 +1,5 @@
+{
+  "name": "@dtwojs/cloudinary",
+  "configKey": "cloudinary",
+  "version": "2.7.0"
+}

package/dist/module.mjs

@@ -0,0 +1,45 @@
+import { defineDtwoModule, createResolver, addImportsDir, addComponentsDir } from '@dtwo/kit';
+import { fileURLToPath } from 'url';
+import { defu } from 'defu';
+
+const module = defineDtwoModule({
+  meta: {
+    name: "@dtwojs/cloudinary",
+    configKey: "cloudinary"
+  },
+  defaults: {
+    cloudName: process.env.CLOUDINARY_CLOUD_NAME,
+    analytics: true
+  },
+  setup(options, dtwo) {
+    const resolver = createResolver(import.meta.url);
+    dtwo.options.runtimeConfig.public.cloudinary = defu(
+      dtwo.options.runtimeConfig.public.cloudinary,
+      {
+        cloudName: process.env.CLOUDINARY_CLOUD_NAME || options.cloudName,
+        uploadPreset: process.env.CLOUDINARY_UPLOAD_PRESET || options.uploadPreset,
+        apiKey: process.env.CLOUDINARY_API_KEY || options.apiKey,
+        analytics: options.analytics,
+        cloud: options.cloud,
+        url: options.url
+      }
+    );
+    if (!dtwo.options.runtimeConfig.public.cloudinary?.cloudName)
+      console.warn(
+        "`[@dtwojs/cloudinary]` Environment variable `CLOUDINARY_CLOUD_NAME` or property `cloudinary.cloudName` missing"
+      );
+    const runtimeDir = fileURLToPath(new URL("./runtime", import.meta.url));
+    dtwo.options.build.transpile.push(runtimeDir);
+    addImportsDir(resolver.resolve(runtimeDir, "composables"));
+    addComponentsDir({
+      path: resolver.resolve(runtimeDir, "components"),
+      pathPrefix: false,
+      prefix: "",
+      // @ts-ignore
+      level: 999,
+      global: true
+    });
+  }
+});
+
+export { module as default };

package/dist/runtime/components/CldImage.kdu

@@ -0,0 +1,202 @@
+<script setup lang="ts">
+// This is working in dev playground but does not work in the published package
+
+// import type { AssetOptions } from "@cloudinary-util/url-loader";
+// import type { ConfigOptions } from "@cloudinary-util/url-loader";
+import { useCldImageUrl } from "../composables/useCldImageUrl";
+import { ref } from "kdu";
+import { Image } from "unpic-kdu";
+
+interface AssetOptionsResize {
+  crop?: string;
+  width?: number | string;
+}
+
+interface ImageOptionsFillBackground {
+  crop?: string;
+  gravity?: string;
+  prompt?: string;
+}
+
+interface AssetOptions {
+  assetType?: string;
+  crop?: string;
+  deliveryType?: string;
+  effects?: Array<any>;
+  flags?: Array<string> | object;
+  format?: string;
+  gravity?: string;
+  height?: string | number;
+  overlays?: Array<any>;
+  quality?: number | string;
+  rawTransformations?: string[];
+  removeBackground?: boolean;
+  sanitize?: boolean;
+  resize?: AssetOptionsResize;
+  seoSuffix?: string;
+  src: string;
+  text?: any;
+  transformations?: Array<string>;
+  underlay?: string;
+  underlays?: Array<any>;
+  version?: number | string;
+  width?: string | number;
+  widthResize?: string | number;
+  zoom?: string;
+}
+
+type ImageOptionsRecolorPrompt = string | Array<string>;
+
+interface ImageOptionsRecolor {
+  prompt?: ImageOptionsRecolorPrompt;
+  to?: string;
+  multiple?: boolean;
+}
+
+interface ImageOptionsZoomPan {
+  loop: string | boolean;
+  options: string;
+}
+
+type ImageOptionsRemovePrompt = string | Array<string>;
+
+interface ImageOptionsRemove {
+  prompt?: ImageOptionsRemovePrompt;
+  region?: [300, 200, 1900, 3500];
+  multiple?: boolean;
+  removeShadow?: boolean;
+}
+
+interface ImageOptionsGenerativeReplace {
+  to: string;
+  from: string;
+  preserveGeometry?: boolean;
+}
+interface ImageOptions extends AssetOptions {
+  zoompan?: string | boolean | ImageOptionsZoomPan;
+  fillBackground?: boolean | ImageOptionsFillBackground;
+  recolor?: ImageOptionsRecolorPrompt | ImageOptionsRecolor;
+  remove?: ImageOptionsRemovePrompt | ImageOptionsRemove;
+  replace?: Array<string | boolean> | ImageOptionsGenerativeReplace;
+  restore?: boolean;
+}
+
+export interface CldImageProps extends ImageOptions {
+  loading?: "eager" | "lazy";
+  fetchPriority?: "high" | "low" | "auto";
+  // Adding below as required props to promote good patterns in developing images
+  alt: string;
+  width: string | number;
+  height: string | number;
+  // Cloudinary URL Loader props
+  // Cannot use `ConfigOptions` due to the same issue as mentioned at the top
+  config?: any;
+  // Unpic props
+  layout?: "constrained" | "fullWidth" | "fixed";
+  priority?: boolean;
+  background?: "auto" | string;
+  // Cloudinary missing effect props
+  blur?: string | number;
+  pixelate?: boolean;
+  grayscale?: boolean;
+  tint?: string | number;
+  opacity?: string | number;
+  shear?: string;
+  border?: string;
+  loaderOptions?: {
+    width: number | string;
+  };
+}
+
+const props = defineProps<CldImageProps>();
+
+// eslint-disable-next-line kdu/no-setup-props-destructure
+const { config, loaderOptions, ...options } = props;
+
+const { url } = useCldImageUrl({ options, config });
+
+const transformUrl = () => {
+  const options = {
+    ...props,
+  };
+
+  options.width =
+    typeof options.width === "string" ? parseInt(options.width) : options.width;
+  options.height =
+    typeof options.height === "string"
+      ? parseInt(options.height)
+      : options.height;
+
+  let widthResize;
+
+  if (
+    typeof loaderOptions?.width === "number" &&
+    typeof options.width === "number" &&
+    loaderOptions.width !== options.width
+  ) {
+    widthResize = loaderOptions.width;
+  } else if (
+    typeof loaderOptions?.width === "number" &&
+    typeof options?.width !== "number"
+  ) {
+    widthResize = loaderOptions.width;
+    options.width = widthResize;
+  }
+
+  // If we have a resize width that's smaller than the user-defined width, we want to give the
+  // ability to perform a final resize on the image without impacting any of the effects like text
+  // overlays that may depend on the size to work properly
+
+  if (options.width && widthResize && widthResize < options.width) {
+    options.widthResize = loaderOptions?.width;
+  }
+
+  const { url } = useCldImageUrl({ options, config });
+
+  return url;
+};
+
+const imgKey = ref("image-key");
+
+const handleError = async (payload: Event) => {
+  const result = await pollForProcessingImage(payload);
+
+  if (result) imgKey.value = `${imgKey.value}-${Math.random()}`;
+};
+
+const pollForProcessingImage = async (options: Event): Promise<boolean> => {
+  const { src } = options.target as EventTarget & { src: string };
+  try {
+    await new Promise((resolve, reject) => {
+      fetch(src).then((res) => {
+        if (!res.ok) {
+          reject(res);
+          return;
+        }
+        resolve(res);
+      });
+    });
+  } catch (e: any) {
+    if (e.status === 423) {
+      return await pollForProcessingImage(options);
+    }
+    return false;
+  }
+  return true;
+};
+</script>
+
+<template>
+  <Image
+    :key="imgKey"
+    :src="url"
+    :layout="layout || 'constrained'"
+    :width="width"
+    :height="height"
+    k-bind="$attrs"
+    :priority="priority"
+    cdn="cloudinary"
+    :transformer="transformUrl"
+    @error="handleError"
+  />
+</template>

package/dist/runtime/components/CldMediaLibrary.kdu

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { useHead } from "@kdhead/kdu";
+import { useRuntimeConfig } from "#imports";
+import { ref } from "kdu";
+
+const cloudinaryRef = ref();
+
+type MediaLibraryProps = {
+  cloudName?: string;
+  apiKey: string;
+  username?: string;
+  useSaml?: boolean;
+  buttonId: string;
+  params?: Record<string, any>;
+};
+
+const props = defineProps<MediaLibraryProps>();
+
+const emit = defineEmits(["onInsert"]);
+
+const handleOnLoad = () => {
+  if ("cloudinary" in window) {
+    cloudinaryRef.value = window.cloudinary;
+
+    const options = Object.fromEntries(
+      Object.entries(props).filter((elem) => Boolean(elem[1]))
+    );
+
+    cloudinaryRef.value.createMediaLibrary(
+      {
+        inline_container: "#widget_container",
+        cloud_name:
+          props.cloudName || useRuntimeConfig().public.cloudinary.cloudName,
+        api_key: props.apiKey || useRuntimeConfig().public.cloudinary.apiKey,
+        ...options,
+        ...props.params,
+      },
+      {
+        insertHandler: function (data: unknown) {
+          emit("onInsert", data);
+        },
+      },
+      document.getElementById(props.buttonId)
+    );
+  }
+};
+
+useHead({
+  script: [
+    {
+      id: `cloudinary-media-library-${Math.floor(Math.random() * 100)}`,
+      src: `https://media-library.cloudinary.com/global/all.js`,
+      onload: handleOnLoad,
+      onerror: (e) =>
+        console.error(
+          `Failed to load Cloudinary Media Library: ${(e as any).message}`
+        ),
+    },
+  ],
+});
+</script>
+
+<template>
+  <div id="widget_container" />
+</template>

package/dist/runtime/components/CldOgImage.kdu

@@ -0,0 +1,174 @@
+<script setup lang="ts">
+import { useCldImageUrl } from "../composables/useCldImageUrl";
+import { computed } from "kdu";
+import { useRouter } from "#imports";
+
+const TWITTER_CARD = "summary_large_image";
+const OG_IMAGE_WIDTH = 2400;
+const OG_IMAGE_WIDTH_RESIZE = 1200;
+const OG_IMAGE_HEIGHT = 1254;
+
+const { currentRoute } = useRouter();
+
+// Same story as with CldImage.kdu component. Cannot use imported types for props
+
+interface AssetOptionsResize {
+  crop?: string;
+  width?: number | string;
+}
+
+interface AssetOptions {
+  assetType?: string;
+  crop?: string;
+  deliveryType?: string;
+  effects?: Array<any>;
+  flags?: Array<string> | object;
+  format?: string;
+  gravity?: string;
+  height?: string | number;
+  overlays?: Array<any>;
+  quality?: number | string;
+  rawTransformations?: string[];
+  removeBackground?: boolean;
+  sanitize?: boolean;
+  resize?: AssetOptionsResize;
+  seoSuffix?: string;
+  src: string;
+  text?: any;
+  transformations?: Array<string>;
+  underlay?: string;
+  underlays?: Array<any>;
+  version?: number | string;
+  width?: string | number;
+  widthResize?: string | number;
+  zoom?: string;
+}
+
+interface ImageOptionsZoomPan {
+  loop: string | boolean;
+  options: string;
+}
+interface ImageOptions extends AssetOptions {
+  zoompan?: string | boolean | ImageOptionsZoomPan;
+}
+
+export interface CldImageProps extends ImageOptions {
+  loading?: "eager" | "lazy";
+  fetchPriority?: "high" | "low" | "auto";
+  // Adding below as required props to promote good patterns in developing images
+  alt: string;
+  width: string | number;
+  height: string | number;
+  // Cloudinary URL Loader props
+  // Cannot use `ConfigOptions` due to the same issue as mentioned at the top
+  config?: any;
+  // Unpic props
+  layout?: "constrained" | "fullWidth" | "fixed";
+  priority?: boolean;
+  background?: "auto" | string;
+}
+
+export type CldOgImageProps = CldImageProps & {
+  excludeTags?: Array<string>;
+  twitterTitle?: string;
+  alt?: string;
+  width?: string | number;
+  height?: string | number;
+};
+
+const props = defineProps<CldOgImageProps>();
+
+const options = {
+  ...props,
+  crop: props.crop || "fill",
+  gravity: props.gravity || "center",
+  height: props.height || OG_IMAGE_HEIGHT,
+  src: props.src,
+  width: props.width || OG_IMAGE_WIDTH,
+  widthResize: props.width || OG_IMAGE_WIDTH_RESIZE,
+};
+
+let width =
+  typeof options.width === "string" ? parseInt(options.width) : options.width;
+let height =
+  typeof options.height === "string"
+    ? parseInt(options.height)
+    : options.height;
+
+// Resize the height based on the widthResize property
+
+if (typeof height === "number" && typeof width === "number") {
+  height = (OG_IMAGE_WIDTH_RESIZE / width) * height;
+}
+
+width = OG_IMAGE_WIDTH_RESIZE;
+
+// Render the final URLs. We use two different format versions to deliver
+// webp for Twitter as it supports it (and we can control with tags) where
+// other platforms may not support webp, so we deliver jpg
+
+const { url: ogImageUrl } = useCldImageUrl({
+  options: {
+    ...options,
+    format: props.format || "jpg",
+  },
+});
+
+const { url: twitterImageUrl } = useCldImageUrl({
+  options: {
+    ...options,
+    format: props.format || "webp",
+  },
+});
+
+const computedTwitterTitle = computed(
+  () => props.twitterTitle || currentRoute.value.meta?.title as string || " "
+);
+</script>
+
+<template>
+  <Head>
+    <Meta
+      key="og-image"
+      property="og:image"
+      :content="ogImageUrl"
+    />
+    <Meta
+      key="og-image-secureurl"
+      property="og:image:secure_url"
+      :content="ogImageUrl"
+    />
+    <Meta
+      key="og-image-width"
+      property="og:image:width"
+      :content="width.toString()"
+    />
+    <Meta
+      key="og-image-height"
+      property="og:image:height"
+      :content="height.toString()"
+    />
+    <Meta
+      k-if="alt"
+      key="og-image-alt"
+      property="og:image:alt"
+      :content="alt"
+    />
+    <Meta
+      k-if="!excludeTags?.includes('twitter:title')"
+      key="twitter-title"
+      property="twitter:title"
+      :content="computedTwitterTitle"
+    />
+    <Meta
+      key="twitter-card"
+      property="twitter:card"
+      :content="TWITTER_CARD"
+    />
+    <Meta
+      key="twitter-image"
+      property="twitter:image"
+      :content="twitterImageUrl"
+    />
+  </Head>
+</template>

package/dist/runtime/components/CldProductGallery.kdu

@@ -0,0 +1,80 @@
+<script setup lang="ts">
+import { useHead } from "@kdhead/kdu";
+import { useRuntimeConfig } from "#imports";
+import { ref } from "kdu";
+
+const cloudinaryRef = ref();
+
+type MediaType = "image" | "video" | "spin";
+
+type ProductGalleryProps = {
+  cloudName?: string;
+  mediaAssets: {
+    tag: string;
+    mediaType?: MediaType;
+  }[];
+  displayProps?: {
+    mode: string;
+    columns: number;
+  }[];
+  aspectRatio?: string;
+  imageBreakpoint?: number;
+  carouselStyle?: string;
+  indicatorProps?: {
+    color?: string;
+  };
+  carouselLocation?: string;
+  borderColor?: string;
+  borderWidth?: number;
+  transition?: string;
+  zoom?: boolean;
+  // Other params listed https://cloudinary.com/documentation/product_gallery_reference#widget_parameters
+  params?: Record<string, any>;
+};
+
+const props = defineProps<ProductGalleryProps>();
+
+const handleOnLoad = () => {
+  if ("cloudinary" in window) {
+    cloudinaryRef.value = window.cloudinary;
+
+    const options = Object.fromEntries(
+      Object.entries(props).filter((elem) => {
+        if (typeof elem[1] === "object") {
+          return Object.keys(elem[1]).length ? elem : false;
+        }
+
+        return Boolean(elem[1]);
+      })
+    );
+
+    const myGallery = cloudinaryRef.value.galleryWidget({
+      container: "#product-gallery",
+      cloudName:
+        props.cloudName || useRuntimeConfig().public.cloudinary.cloudName,
+      ...options,
+      ...props.params,
+    });
+
+    myGallery.render();
+  }
+};
+
+useHead({
+  script: [
+    {
+      id: `cloudinary-product-gallery-${Math.floor(Math.random() * 100)}`,
+      src: `https://product-gallery.cloudinary.com/all.js`,
+      onload: handleOnLoad,
+      onerror: (e) =>
+        console.error(
+          `Failed to load Cloudinary Product Gallery: ${(e as any).message}`
+        ),
+    },
+  ],
+});
+</script>
+
+<template>
+  <div id="product-gallery" />
+</template>