@kasuvia/sdk 0.0.8 → 0.0.9

package/src/components/shared/SmartImage.tsx

@@ -0,0 +1,311 @@
+"use client";
+
+import { useState, useEffect, forwardRef, type CSSProperties } from "react";
+import { motion, type HTMLMotionProps } from "framer-motion";
+import Image from "next/image";
+import { ImageIcon } from "lucide-react";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+type ObjectFit = "cover" | "contain" | "fill" | "none" | "scale-down";
+
+interface BaseSmartImageProps {
+  src: string | null | undefined;
+  alt: string;
+  className?: string;
+  imageClassName?: string;
+  priority?: boolean;
+  isRelative?: boolean;
+  sizes?: string;
+  objectFit?: ObjectFit;
+  /**
+   * Optional fallback image src rendered instead of the broken-image
+   * placeholder if the primary src fails to load.
+   */
+  fallbackSrc?: string;
+  /**
+   * Passed-through to the underlying Next.js <Image> to suppress
+   * hydration warnings on SSR-rendered images.
+   */
+  suppressHydrationWarning?: boolean;
+}
+
+/**
+ * SmartImageProps for the standard (non-motion) variant.
+ * Adds optional `style` for container sizing (e.g. explicit width/height).
+ */
+export type SmartImageProps = BaseSmartImageProps & {
+  style?: CSSProperties;
+  draggable?: boolean;
+};
+
+/**
+ * SmartMotionImageProps for the Framer Motion variant.
+ * Extends SmartImageProps with all `motion.div` props (initial, animate, etc.)
+ */
+export type SmartMotionImageProps = BaseSmartImageProps &
+  Omit<HTMLMotionProps<"div">, "draggable"> & {
+    style?: CSSProperties;
+    draggable?: boolean;
+  };
+
+// ─── Source Validator ─────────────────────────────────────────────────────────
+
+/**
+ * Strictly validates that a source is a viable image path/URL.
+ * Rejects empty strings, the literal strings "null"/"undefined", and anything
+ * that doesn't start with a recognised URL scheme or path prefix.
+ */
+const isValidSrc = (url: unknown): url is string => {
+  if (!url || typeof url !== "string") return false;
+  const s = url.trim();
+  if (s === "" || s === "null" || s === "undefined") return false;
+  return (
+    s.startsWith("/") ||
+    s.startsWith("http://") ||
+    s.startsWith("https://") ||
+    s.startsWith("data:image/") ||
+    s.startsWith("blob:")
+  );
+};
+
+// ─── Shared State Hook ────────────────────────────────────────────────────────
+
+/**
+ * Tracks mount, load, and error state for a given `src`.
+ * Centralised here so both SmartImage and SmartMotionImage stay in sync.
+ */
+function useImageState(src: string | null | undefined) {
+  const [isMounted, setIsMounted] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+  const [hasError, setHasError] = useState(false);
+
+  useEffect(() => {
+    setIsMounted(true);
+  }, []);
+
+  // Reset when src changes so a freshly swapped-in URL doesn't inherit
+  // the previous URL's stale loaded/failed state.
+  useEffect(() => {
+    setIsLoading(true);
+    setHasError(false);
+  }, [src]);
+
+  const handleLoad = () => setIsLoading(false);
+  const handleError = () => {
+    setIsLoading(false);
+    setHasError(true);
+  };
+
+  return { isMounted, isLoading, hasError, handleLoad, handleError };
+}
+
+// ─── Placeholder ──────────────────────────────────────────────────────────────
+
+interface ImagePlaceholderProps {
+  className: string;
+  /** When true, renders a visually distinct "failed to load" state. */
+  failed?: boolean;
+}
+
+/**
+ * "No image" / "Failed to load" placeholder.
+ * Uses lucide-react's ImageIcon (same dep already required by consumers).
+ */
+function ImagePlaceholder({ className, failed }: ImagePlaceholderProps) {
+  return (
+    <div
+      className={`relative overflow-hidden flex flex-col items-center justify-center gap-1 bg-muted/40 ${className}`}
+    >
+      <ImageIcon className="w-4 h-4 text-muted-foreground/50 shrink-0" />
+      <span className="text-[10px] text-muted-foreground/70 text-center leading-tight px-1">
+        {failed ? "Failed to load" : "No image"}
+      </span>
+    </div>
+  );
+}
+
+// ─── Shimmer Skeleton ─────────────────────────────────────────────────────────
+
+/** Full-bleed sweep shimmer shown while the image is in-flight. */
+function ImageShimmer() {
+  return (
+    <div className="absolute inset-0 z-10 bg-muted/60 overflow-hidden">
+      <div className="absolute inset-0 -translate-x-full animate-shimmer bg-linear-to-r from-transparent via-white/10 to-transparent" />
+    </div>
+  );
+}
+
+// ─── SmartImage ───────────────────────────────────────────────────────────────
+
+/**
+ * Standard smart image component for Kasuvia storefronts and dashboards.
+ *
+ * Wraps Next.js `<Image fill>` with:
+ * - Strict src validation (rejects null / empty / "null" strings)
+ * - A shimmer skeleton shown while the image loads
+ * - A labelled placeholder shown when there is no valid src
+ * - A distinct failed-to-load placeholder (or optional `fallbackSrc`)
+ * - An `objectFit` prop (defaults to "cover") for flexibility
+ *
+ * Peer dependencies: next, framer-motion, lucide-react
+ */
+export const SmartImage = forwardRef<HTMLImageElement, SmartImageProps>(function SmartImage(
+  {
+    src,
+    alt,
+    className = "",
+    imageClassName = "",
+    priority = false,
+    isRelative = true,
+    sizes = "100vw",
+    objectFit = "cover",
+    fallbackSrc,
+    suppressHydrationWarning = false,
+    style,
+    draggable,
+  },
+  ref
+) {
+  const { isMounted, isLoading, hasError, handleLoad, handleError } =
+    useImageState(src);
+
+  const resolvedSrc = isValidSrc(src) ? src.trim() : null;
+  const fallback = isValidSrc(fallbackSrc) ? fallbackSrc!.trim() : null;
+
+  if (!isMounted || (!resolvedSrc && !fallback)) {
+    return <ImagePlaceholder className={className} />;
+  }
+
+  if (hasError) {
+    if (fallback) {
+      return (
+        <div
+          className={`${isRelative ? "relative" : ""} overflow-hidden ${className}`}
+          style={style}
+        >
+          <Image
+            ref={ref}
+            src={fallback}
+            alt={alt}
+            fill
+            unoptimized
+            sizes={sizes}
+            className={`object-${objectFit} ${imageClassName}`}
+            draggable={draggable}
+          />
+        </div>
+      );
+    }
+    return <ImagePlaceholder className={className} failed />;
+  }
+
+  return (
+    <div
+      className={`${isRelative ? "relative" : ""} overflow-hidden ${className}`}
+      style={style}
+    >
+      {isLoading && <ImageShimmer />}
+      <Image
+        ref={ref}
+        src={resolvedSrc!}
+        alt={alt}
+        fill
+        priority={priority}
+        sizes={sizes}
+        unoptimized
+        suppressHydrationWarning={suppressHydrationWarning}
+        className={`object-${objectFit} ${imageClassName} transition-opacity duration-300 ${isLoading ? "opacity-0" : "opacity-100"}`}
+        onLoad={handleLoad}
+        onError={handleError}
+        draggable={draggable}
+      />
+    </div>
+  );
+});
+
+// ─── SmartMotionImage ─────────────────────────────────────────────────────────
+
+/**
+ * Framer Motion variant of SmartImage.
+ * Accepts all `motion.div` props (e.g. `initial`, `animate`, `whileHover`)
+ * alongside the standard SmartImage props.
+ *
+ * Peer dependencies: next, framer-motion, lucide-react
+ */
+export const SmartMotionImage = forwardRef<HTMLDivElement, SmartMotionImageProps>(function SmartMotionImage(
+  {
+    src,
+    alt,
+    className = "",
+    imageClassName = "",
+    priority = false,
+    isRelative = true,
+    sizes = "100vw",
+    objectFit = "cover",
+    fallbackSrc,
+    style,
+    draggable,
+    ...motionProps
+  },
+  ref
+) {
+  const { isMounted, isLoading, hasError, handleLoad, handleError } =
+    useImageState(src);
+
+  const resolvedSrc = isValidSrc(src) ? src.trim() : null;
+  const fallback = isValidSrc(fallbackSrc) ? fallbackSrc!.trim() : null;
+
+  if (!isMounted || (!resolvedSrc && !fallback)) {
+    return <ImagePlaceholder className={className} />;
+  }
+
+  if (hasError) {
+    if (fallback) {
+      return (
+        <motion.div
+          ref={ref}
+          className={`${isRelative ? "relative" : ""} overflow-hidden ${className}`}
+          style={style}
+          {...motionProps}
+        >
+          <Image
+            src={fallback}
+            alt={alt}
+            fill
+            unoptimized
+            sizes={sizes}
+            className={`object-${objectFit} ${imageClassName}`}
+            draggable={draggable}
+          />
+        </motion.div>
+      );
+    }
+    return <ImagePlaceholder className={className} failed />;
+  }
+
+  return (
+    <motion.div
+      ref={ref}
+      className={`${isRelative ? "relative" : ""} overflow-hidden ${className}`}
+      style={style}
+      {...motionProps}
+    >
+      {isLoading && <ImageShimmer />}
+      <Image
+        src={resolvedSrc!}
+        alt={alt}
+        fill
+        priority={priority}
+        sizes={sizes}
+        unoptimized
+        className={`object-${objectFit} ${imageClassName} transition-opacity duration-300 ${isLoading ? "opacity-0" : "opacity-100"}`}
+        onLoad={handleLoad}
+        onError={handleError}
+        draggable={draggable}
+      />
+    </motion.div>
+  );
+});
+
+export default SmartImage;

package/src/components/shared/TruncatedValue.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+
+export interface TruncatedValueProps {
+  /** The (possibly visually truncated, or compact/abbreviated) displayed value. */
+  value: ReactNode;
+  /** The full, untruncated/unabbreviated value shown on hover/title. */
+  fullValue?: ReactNode;
+  className?: string;
+  triggerClassName?: string;
+}
+
+/**
+ * TruncatedValue
+ * Wraps a string or numeric value so the full value is accessible on hover or title.
+ */
+export function TruncatedValue({ value, fullValue, className = "", triggerClassName = "" }: TruncatedValueProps) {
+  const tooltipText = typeof fullValue === "string" ? fullValue : typeof value === "string" ? value : undefined;
+
+  return (
+    <span
+      title={tooltipText}
+      className={`truncate tabular-nums cursor-default inline-block max-w-full ${triggerClassName} ${className}`.trim()}
+    >
+      {value}
+    </span>
+  );
+}

package/src/components/shared/UnsavedChangesGuard.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import React, { useState, useEffect, useCallback, useRef } from "react";
+import { AlertTriangle } from "lucide-react";
+
+export interface UseUnsavedChangesOptions {
+  browserMessage?: string;
+  dialogTitle?: string;
+  dialogBody?: string;
+}
+
+export interface UnsavedChangesDialogProps {
+  open: boolean;
+  onStay: () => void;
+  onLeave: () => void;
+  title?: string;
+  body?: string;
+}
+
+export interface UseUnsavedChangesReturn {
+  isDirty: boolean;
+  markDirty: () => void;
+  resetDirty: () => void;
+  guardedNavigate: (action: () => void) => void;
+  dialogProps: UnsavedChangesDialogProps;
+}
+
+export function useUnsavedChanges(
+  options: UseUnsavedChangesOptions = {}
+): UseUnsavedChangesReturn {
+  const {
+    browserMessage = "You have unsaved changes. If you leave, your work will be lost.",
+    dialogTitle = "Unsaved Changes",
+    dialogBody = "You have unsaved changes. If you leave now, all your progress will be lost.",
+  } = options;
+
+  const [isDirty, setIsDirty] = useState(false);
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const pendingActionRef = useRef<(() => void) | null>(null);
+
+  useEffect(() => {
+    if (!isDirty) return;
+    const handler = (e: BeforeUnloadEvent) => {
+      e.preventDefault();
+      e.returnValue = browserMessage;
+      return browserMessage;
+    };
+    window.addEventListener("beforeunload", handler);
+    return () => window.removeEventListener("beforeunload", handler);
+  }, [isDirty, browserMessage]);
+
+  const markDirty = useCallback(() => setIsDirty(true), []);
+
+  const resetDirty = useCallback(() => {
+    setIsDirty(false);
+    setDialogOpen(false);
+    pendingActionRef.current = null;
+  }, []);
+
+  const guardedNavigate = useCallback(
+    (action: () => void) => {
+      if (!isDirty) {
+        action();
+        return;
+      }
+      pendingActionRef.current = action;
+      setDialogOpen(true);
+    },
+    [isDirty]
+  );
+
+  const handleStay = useCallback(() => {
+    setDialogOpen(false);
+    pendingActionRef.current = null;
+  }, []);
+
+  const handleLeave = useCallback(() => {
+    setDialogOpen(false);
+    setIsDirty(false);
+    const action = pendingActionRef.current;
+    pendingActionRef.current = null;
+    action?.();
+  }, []);
+
+  return {
+    isDirty,
+    markDirty,
+    resetDirty,
+    guardedNavigate,
+    dialogProps: {
+      open: dialogOpen,
+      onStay: handleStay,
+      onLeave: handleLeave,
+      title: dialogTitle,
+      body: dialogBody,
+    },
+  };
+}
+
+export function UnsavedChangesDialog({
+  open,
+  onStay,
+  onLeave,
+  title = "Unsaved Changes",
+  body = "You have unsaved changes. If you leave now, all your progress will be lost.",
+}: UnsavedChangesDialogProps): React.JSX.Element | null {
+  if (!open) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/50 backdrop-blur-sm animate-in fade-in duration-200">
+      <div className="w-full max-w-md bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-800 rounded-2xl p-6 shadow-2xl space-y-4">
+        <div className="flex flex-col items-center text-center">
+          <div className="w-12 h-12 rounded-xl bg-amber-500/10 flex items-center justify-center mb-3 text-amber-500">
+            <AlertTriangle className="w-6 h-6" />
+          </div>
+          <h3 className="text-lg font-bold text-gray-900 dark:text-gray-100">{title}</h3>
+          <p className="text-xs text-gray-500 dark:text-gray-400 mt-1 leading-relaxed">{body}</p>
+        </div>
+        <div className="flex flex-col sm:flex-row gap-2 pt-2">
+          <button
+            type="button"
+            onClick={onStay}
+            className="flex-1 h-10 px-4 text-xs font-semibold rounded-xl border border-gray-300 dark:border-gray-700 bg-white dark:bg-gray-800 text-gray-800 dark:text-gray-200 hover:bg-gray-50"
+          >
+            Stay &amp; Keep Editing
+          </button>
+          <button
+            type="button"
+            onClick={onLeave}
+            className="flex-1 h-10 px-4 text-xs font-semibold rounded-xl bg-red-600 text-white hover:bg-red-700"
+          >
+            Leave Without Saving
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/shared/index.ts

@@ -0,0 +1,15 @@
+export * from "./TruncatedValue";
+export * from "./AddressAutocomplete";
+export * from "./OfflineBanner";
+export * from "./MapPinDrop";
+export * from "./SearchableInput";
+export * from "./SearchablePopover";
+export * from "./LucideReactIcon";
+export * from "./UnsavedChangesGuard";
+export * from "./MultiSelectPicker";
+export * from "./SmartImage";
+export * from "./ImageEditorModal";
+export * from "./ImageViewerModal";
+export * from "./AnalyticsScripts";
+export * from "./CookieConsentBanner";
+

package/src/components/skeletons/CardSkeleton.tsx

@@ -0,0 +1,26 @@
+import React from 'react'
+
+export interface CardSkeletonProps {
+  count?: number
+  containerClassName?: string
+  cardClassName?: string
+}
+
+export function CardSkeleton({
+  count = 4,
+  containerClassName = "grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-6",
+  cardClassName = "rounded-xl border p-4 space-y-3 animate-pulse bg-card"
+}: CardSkeletonProps) {
+  return (
+    <div className={containerClassName}>
+      {Array.from({ length: count }).map((_, i) => (
+        <div key={i} className={cardClassName}>
+          <div className="w-full aspect-square bg-muted rounded-lg" />
+          <div className="h-4 bg-muted rounded w-3/4" />
+          <div className="h-4 bg-muted rounded w-1/2" />
+          <div className="h-8 bg-muted rounded w-full mt-2" />
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/components/skeletons/CartItemSkeleton.tsx

@@ -0,0 +1,26 @@
+import React from 'react'
+
+export interface CartItemSkeletonProps {
+  count?: number
+  className?: string
+}
+
+export function CartItemSkeleton({
+  count = 3,
+  className = "space-y-4"
+}: CartItemSkeletonProps) {
+  return (
+    <div className={className}>
+      {Array.from({ length: count }).map((_, i) => (
+        <div key={i} className="flex items-center gap-4 p-3 border-b animate-pulse">
+          <div className="w-16 h-16 bg-muted rounded-md shrink-0" />
+          <div className="flex-1 space-y-2">
+            <div className="h-4 bg-muted rounded w-2/3" />
+            <div className="h-3 bg-muted rounded w-1/3" />
+          </div>
+          <div className="h-6 w-16 bg-muted rounded shrink-0" />
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/components/skeletons/OrderItemSkeleton.tsx

@@ -0,0 +1,26 @@
+import React from 'react'
+
+export interface OrderItemSkeletonProps {
+  count?: number
+  className?: string
+}
+
+export function OrderItemSkeleton({
+  count = 3,
+  className = "space-y-4"
+}: OrderItemSkeletonProps) {
+  return (
+    <div className={className}>
+      {Array.from({ length: count }).map((_, i) => (
+        <div key={i} className="p-4 border rounded-lg animate-pulse space-y-3">
+          <div className="flex justify-between items-center">
+            <div className="h-4 bg-muted rounded w-1/3" />
+            <div className="h-5 w-20 bg-muted rounded-full" />
+          </div>
+          <div className="h-3 bg-muted rounded w-1/4" />
+          <div className="h-4 bg-muted rounded w-1/2" />
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/components/skeletons/ProductCardSkeleton.tsx

@@ -0,0 +1,26 @@
+import React from 'react'
+
+export interface ProductCardSkeletonProps {
+  className?: string
+  imageClassName?: string
+}
+
+export function ProductCardSkeleton({
+  className = "flex flex-col h-full rounded-xl border bg-card overflow-hidden shadow-sm animate-pulse",
+  imageClassName = "w-full aspect-square bg-muted",
+}: ProductCardSkeletonProps) {
+  return (
+    <div className={className}>
+      <div className={imageClassName} />
+      <div className="p-4 flex flex-col flex-1 space-y-3">
+        <div className="h-5 bg-muted rounded w-3/4" />
+        <div className="h-3 bg-muted rounded w-full" />
+        <div className="h-3 bg-muted rounded w-2/3" />
+        <div className="flex items-center justify-between pt-2 mt-auto">
+          <div className="h-6 bg-muted rounded w-20" />
+        </div>
+        <div className="w-full h-10 bg-muted rounded-lg mt-auto" />
+      </div>
+    </div>
+  )
+}

package/src/components/skeletons/TableSkeleton.tsx

@@ -0,0 +1,42 @@
+import React from 'react'
+
+export interface TableSkeletonProps {
+  rows?: number
+  columns?: number
+  className?: string
+  rowClassName?: string
+}
+
+export function TableSkeleton({
+  rows = 5,
+  columns = 4,
+  className = "w-full border-collapse",
+  rowClassName = "border-b"
+}: TableSkeletonProps) {
+  return (
+    <div className="w-full overflow-x-auto">
+      <table className={className}>
+        <thead>
+          <tr className={rowClassName}>
+            {Array.from({ length: columns }).map((_, c) => (
+              <th key={c} className="p-3 text-left">
+                <div className="h-4 bg-muted rounded animate-pulse w-20" />
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {Array.from({ length: rows }).map((_, r) => (
+            <tr key={r} className={rowClassName}>
+              {Array.from({ length: columns }).map((_, c) => (
+                <td key={c} className="p-3">
+                  <div className="h-4 bg-muted rounded animate-pulse w-full max-w-[120px]" />
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}

package/src/components/skeletons/index.ts

@@ -0,0 +1,5 @@
+export * from './TableSkeleton'
+export * from './CardSkeleton'
+export * from './CartItemSkeleton'
+export * from './OrderItemSkeleton'
+export * from './ProductCardSkeleton'