@mohasinac/appkit 2.3.0 → 2.3.1

package/dist/features/loyalty/messages/en.json

@@ -0,0 +1,19 @@
+{
+    "loyalty": {
+        "title": "HC Coins",
+        "balance": "Your Coin Balance",
+        "earn": "Earn Coins",
+        "redeem": "Redeem Coins",
+        "history": "Coin History",
+        "noHistory": "No coin transactions yet.",
+        "earnedFor": "Earned for order",
+        "redeemedFor": "Redeemed on order",
+        "adminGrant": "Admin grant",
+        "refund": "Refund",
+        "coinsEarned": "{coins} coins earned",
+        "coinsRedeemed": "{coins} coins redeemed",
+        "worthRupees": "Worth ₹{amount}",
+        "minRequired": "Minimum {min} coins required to redeem",
+        "notActive": "Loyalty program is currently inactive"
+    }
+}

package/dist/features/loyalty/repository/loyalty.repository.d.ts

@@ -0,0 +1,8 @@
+import type { IRepository } from "../../../contracts";
+import type { LoyaltyBalance, CoinHistoryEntry } from "../types";
+export declare class LoyaltyRepository {
+    private readonly repo;
+    constructor(repo: IRepository<LoyaltyBalance>);
+    getBalance(uid: string): Promise<LoyaltyBalance | null>;
+    addCoins(uid: string, delta: number, entry: Omit<CoinHistoryEntry, "timestamp">): Promise<void>;
+}

package/dist/features/loyalty/repository/loyalty.repository.js

@@ -0,0 +1,22 @@
+export class LoyaltyRepository {
+    constructor(repo) {
+        this.repo = repo;
+    }
+    async getBalance(uid) {
+        return this.repo.findById(uid);
+    }
+    async addCoins(uid, delta, entry) {
+        const user = await this.repo.findById(uid);
+        if (!user)
+            return;
+        const current = user.hcCoins ?? 0;
+        const history = user.coinHistory ?? [];
+        await this.repo.update(uid, {
+            hcCoins: current + delta,
+            coinHistory: [
+                ...history,
+                { ...entry, delta, timestamp: new Date().toISOString() },
+            ],
+        });
+    }
+}

package/dist/features/loyalty/schemas/index.d.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+/**
+ * Reason categories for loyalty coin transactions.
+ */
+export declare const coinReasonSchema: z.ZodEnum<["order_reward", "referral", "review_reward", "manual_credit", "manual_debit", "redemption", "expiry"]>;
+export declare const coinHistoryEntrySchema: z.ZodObject<{
+    delta: z.ZodNumber;
+    reason: z.ZodEnum<["order_reward", "referral", "review_reward", "manual_credit", "manual_debit", "redemption", "expiry"]>;
+    orderId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    reason: "expiry" | "redemption" | "order_reward" | "referral" | "review_reward" | "manual_credit" | "manual_debit";
+    delta: number;
+    orderId?: string | undefined;
+    timestamp?: string | undefined;
+}, {
+    reason: "expiry" | "redemption" | "order_reward" | "referral" | "review_reward" | "manual_credit" | "manual_debit";
+    delta: number;
+    orderId?: string | undefined;
+    timestamp?: string | undefined;
+}>;
+/**
+ * Base Zod schema for a loyalty balance record.
+ *
+ * @example
+ * import { loyaltyBalanceSchema } from "@mohasinac/feat-loyalty";
+ *
+ * const mySchema = loyaltyBalanceSchema.extend({
+ *   tier: z.enum(["bronze", "silver", "gold"]),
+ * });
+ */
+export declare const loyaltyBalanceSchema: z.ZodObject<{
+    uid: z.ZodString;
+    hcCoins: z.ZodDefault<z.ZodNumber>;
+    coinHistory: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        delta: z.ZodNumber;
+        reason: z.ZodEnum<["order_reward", "referral", "review_reward", "manual_credit", "manual_debit", "redemption", "expiry"]>;
+        orderId: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        reason: "expiry" | "redemption" | "order_reward" | "referral" | "review_reward" | "manual_credit" | "manual_debit";
+        delta: number;
+        orderId?: string | undefined;
+        timestamp?: string | undefined;
+    }, {
+        reason: "expiry" | "redemption" | "order_reward" | "referral" | "review_reward" | "manual_credit" | "manual_debit";
+        delta: number;
+        orderId?: string | undefined;
+        timestamp?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    uid: string;
+    hcCoins: number;
+    coinHistory?: {
+        reason: "expiry" | "redemption" | "order_reward" | "referral" | "review_reward" | "manual_credit" | "manual_debit";
+        delta: number;
+        orderId?: string | undefined;
+        timestamp?: string | undefined;
+    }[] | undefined;
+}, {
+    uid: string;
+    hcCoins?: number | undefined;
+    coinHistory?: {
+        reason: "expiry" | "redemption" | "order_reward" | "referral" | "review_reward" | "manual_credit" | "manual_debit";
+        delta: number;
+        orderId?: string | undefined;
+        timestamp?: string | undefined;
+    }[] | undefined;
+}>;
+export declare const loyaltyConfigSchema: z.ZodObject<{
+    coinsPerOrderUnit: z.ZodNumber;
+    minRedeemableCoins: z.ZodNumber;
+    maxRedemptionPercentPerOrder: z.ZodNumber;
+    coinExpiryDays: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    coinsPerOrderUnit: number;
+    minRedeemableCoins: number;
+    maxRedemptionPercentPerOrder: number;
+    coinExpiryDays?: number | undefined;
+}, {
+    coinsPerOrderUnit: number;
+    minRedeemableCoins: number;
+    maxRedemptionPercentPerOrder: number;
+    coinExpiryDays?: number | undefined;
+}>;

package/dist/features/loyalty/schemas/index.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+/**
+ * Reason categories for loyalty coin transactions.
+ */
+export const coinReasonSchema = z.enum([
+    "order_reward",
+    "referral",
+    "review_reward",
+    "manual_credit",
+    "manual_debit",
+    "redemption",
+    "expiry",
+]);
+export const coinHistoryEntrySchema = z.object({
+    delta: z.number(),
+    reason: coinReasonSchema,
+    orderId: z.string().optional(),
+    timestamp: z.string().optional(),
+});
+/**
+ * Base Zod schema for a loyalty balance record.
+ *
+ * @example
+ * import { loyaltyBalanceSchema } from "@mohasinac/feat-loyalty";
+ *
+ * const mySchema = loyaltyBalanceSchema.extend({
+ *   tier: z.enum(["bronze", "silver", "gold"]),
+ * });
+ */
+export const loyaltyBalanceSchema = z.object({
+    uid: z.string(),
+    hcCoins: z.number().default(0),
+    coinHistory: z.array(coinHistoryEntrySchema).optional(),
+});
+export const loyaltyConfigSchema = z.object({
+    coinsPerOrderUnit: z.number(),
+    minRedeemableCoins: z.number(),
+    maxRedemptionPercentPerOrder: z.number(),
+    coinExpiryDays: z.number().optional(),
+});

package/dist/features/loyalty/server.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @mohasinac/appkit/features/loyalty/server
+ *
+ * Server-only entry point for loyalty repositories.
+ */
+export { LoyaltyRepository } from "./repository/loyalty.repository";

package/dist/features/loyalty/server.js

@@ -0,0 +1,6 @@
+/**
+ * @mohasinac/appkit/features/loyalty/server
+ *
+ * Server-only entry point for loyalty repositories.
+ */
+export { LoyaltyRepository } from "./repository/loyalty.repository";

package/dist/features/loyalty/types/index.d.ts

@@ -0,0 +1,31 @@
+import type { LoyaltyConfig } from "./loyalty-config";
+export type { LoyaltyConfig } from "./loyalty-config";
+export type CoinReason = "purchase" | "redemption" | "admin-grant" | "refund";
+export interface CoinHistoryEntry {
+    delta: number;
+    reason: CoinReason;
+    orderId?: string;
+    timestamp: string;
+}
+export interface LoyaltyBalance {
+    uid: string;
+    hcCoins: number;
+    coinHistory: CoinHistoryEntry[];
+}
+export interface EarnCoinsInput {
+    uid: string;
+    orderTotal: number;
+    orderId: string;
+    config: LoyaltyConfig;
+}
+export interface RedeemCoinsInput {
+    uid: string;
+    coinsToRedeem: number;
+    orderId: string;
+    config: LoyaltyConfig;
+}
+export interface RedeemCoinsResult {
+    coinsRedeemed: number;
+    discountAmount: number;
+}
+export { calculateCoinsEarned, calculateMaxRedeemable, coinsToRupees, applyCoinsToOrder, } from "./loyalty-math";

package/dist/features/loyalty/types/index.js

@@ -0,0 +1 @@
+export { calculateCoinsEarned, calculateMaxRedeemable, coinsToRupees, applyCoinsToOrder, } from "./loyalty-math";

package/dist/features/loyalty/types/loyalty-config.d.ts

@@ -0,0 +1,7 @@
+export interface LoyaltyConfig {
+    coinsPerRupee: number;
+    rupeePerCoin: number;
+    minCoinsToRedeem: number;
+    maxRedeemPercent: number;
+    active: boolean;
+}

package/dist/features/loyalty/types/loyalty-config.js

@@ -0,0 +1 @@
+export {};

package/dist/features/loyalty/types/loyalty-math.d.ts

@@ -0,0 +1,9 @@
+import type { LoyaltyConfig } from "./loyalty-config";
+export declare function calculateCoinsEarned(orderTotal: number, config: LoyaltyConfig): number;
+export declare function calculateMaxRedeemable(userCoins: number, orderTotal: number, config: LoyaltyConfig): number;
+export declare function coinsToRupees(coins: number, config: LoyaltyConfig): number;
+/**
+ * Calculate the INR discount for a given coin redemption.
+ * Ensures the discount never exceeds the order total.
+ */
+export declare function applyCoinsToOrder(coinsToRedeem: number, orderTotal: number, config: LoyaltyConfig): number;

package/dist/features/loyalty/types/loyalty-math.js

@@ -0,0 +1,27 @@
+export function calculateCoinsEarned(orderTotal, config) {
+    if (!config.active || orderTotal <= 0)
+        return 0;
+    return Math.floor(orderTotal * config.coinsPerRupee);
+}
+export function calculateMaxRedeemable(userCoins, orderTotal, config) {
+    if (!config.active || userCoins < config.minCoinsToRedeem || orderTotal <= 0)
+        return 0;
+    const maxDiscountRupees = Math.floor((orderTotal * config.maxRedeemPercent) / 100);
+    const maxCoinsByPercent = Math.floor(maxDiscountRupees / config.rupeePerCoin);
+    return Math.min(userCoins, maxCoinsByPercent);
+}
+export function coinsToRupees(coins, config) {
+    if (coins <= 0)
+        return 0;
+    return Math.floor(coins * config.rupeePerCoin);
+}
+/**
+ * Calculate the INR discount for a given coin redemption.
+ * Ensures the discount never exceeds the order total.
+ */
+export function applyCoinsToOrder(coinsToRedeem, orderTotal, config) {
+    if (!config.active || coinsToRedeem <= 0 || orderTotal <= 0)
+        return 0;
+    const discount = coinsToRupees(coinsToRedeem, config);
+    return Math.min(discount, orderTotal);
+}

package/dist/features/media/AvatarUpload.d.ts

@@ -0,0 +1,22 @@
+import { type ImageCropData } from "./modals/ImageCropModal";
+export interface AvatarUploadProps {
+    currentPhotoURL?: string | null;
+    currentCropData?: ImageCropData | null;
+    userId: string;
+    displayName?: string;
+    onUploadSuccess?: (photoURL: string, cropData: ImageCropData) => Promise<void> | void;
+    onUploadError?: (error: string) => void;
+    onSaveComplete?: () => void;
+    onPendingStateChange?: (hasPending: boolean) => void;
+    labels?: {
+        chooseImage?: string;
+        changePhoto?: string;
+        removePhoto?: string;
+        saveAvatar?: string;
+        cancelChange?: string;
+        uploading?: string;
+        readyToSave?: string;
+    };
+}
+export declare function AvatarUpload({ currentPhotoURL, currentCropData, userId, displayName, onUploadSuccess, onUploadError, onSaveComplete, onPendingStateChange, labels, }: AvatarUploadProps): import("react/jsx-runtime").JSX.Element;
+export default AvatarUpload;

package/dist/features/media/AvatarUpload.js

@@ -0,0 +1,133 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { Alert, Button, Input, Progress, Text, useToast } from "../../ui";
+import { useMediaUpload } from "./hooks/useMedia";
+import { ImageCropModal } from "./modals/ImageCropModal";
+import { AvatarDisplay } from "../../ui/components/AvatarDisplay";
+export function AvatarUpload({ currentPhotoURL, currentCropData, userId, displayName, onUploadSuccess, onUploadError, onSaveComplete, onPendingStateChange, labels, }) {
+    const t = {
+        chooseImage: labels?.chooseImage ?? "Choose image",
+        changePhoto: labels?.changePhoto ?? "Change photo",
+        removePhoto: labels?.removePhoto ?? "Remove photo",
+        saveAvatar: labels?.saveAvatar ?? "Save avatar",
+        cancelChange: labels?.cancelChange ?? "Cancel",
+        uploading: labels?.uploading ?? "Uploading",
+        readyToSave: labels?.readyToSave ?? "Ready to save",
+    };
+    const [previewUrl, setPreviewUrl] = useState(currentPhotoURL || null);
+    const [cropData, setCropData] = useState(currentCropData || null);
+    const [tempImageUrl, setTempImageUrl] = useState(null);
+    const [showCropModal, setShowCropModal] = useState(false);
+    const [pendingFile, setPendingFile] = useState(null);
+    const [pendingCropData, setPendingCropData] = useState(null);
+    const [pendingUploadFile, setPendingUploadFile] = useState(null);
+    const fileInputRef = useRef(null);
+    const { showToast } = useToast();
+    const { mutateAsync: uploadMedia, isPending: isUploading, error: uploadApiError, } = useMediaUpload();
+    useEffect(() => {
+        const hasPending = pendingCropData !== null && pendingUploadFile !== null;
+        onPendingStateChange?.(hasPending);
+    }, [pendingCropData, pendingUploadFile, onPendingStateChange]);
+    const handleFileSelect = async (event) => {
+        const file = event.target.files?.[0];
+        if (!file)
+            return;
+        const reader = new FileReader();
+        reader.onloadend = () => {
+            setTempImageUrl(reader.result);
+            setPendingFile(file);
+            setShowCropModal(true);
+        };
+        reader.readAsDataURL(file);
+    };
+    const handleCropSave = (newCropData) => {
+        if (!pendingFile)
+            return;
+        setPendingCropData(newCropData);
+        setPendingUploadFile(pendingFile);
+        setTempImageUrl(null);
+        setPendingFile(null);
+        setShowCropModal(false);
+    };
+    const handleConfirmSave = async () => {
+        if (!pendingUploadFile || !pendingCropData)
+            return;
+        const formData = new FormData();
+        formData.append("file", pendingUploadFile);
+        const nameParts = (displayName ?? "").trim().split(/\s+/).filter(Boolean);
+        const firstName = nameParts[0] || userId;
+        const lastName = nameParts.slice(1).join("-") || firstName;
+        formData.append("context", JSON.stringify({
+            type: "user-avatar",
+            firstName,
+            lastName,
+        }));
+        formData.append("folder", "users");
+        formData.append("public", "true");
+        formData.append("metadata", JSON.stringify({
+            cropX: 0,
+            cropY: 0,
+            cropWidth: 400,
+            cropHeight: 400,
+            zoom: pendingCropData.zoom ?? 1,
+            focalX: (pendingCropData.position?.x ?? 50) / 100,
+            focalY: (pendingCropData.position?.y ?? 50) / 100,
+            aspectRatio: "1:1",
+            objectFit: "cover",
+            displayMode: "avatar",
+            originalWidth: 400,
+            originalHeight: 400,
+            mimeType: pendingUploadFile.type,
+            fileSize: pendingUploadFile.size,
+        }));
+        try {
+            const result = await uploadMedia(formData);
+            const downloadURL = result.url;
+            await onUploadSuccess?.(downloadURL, pendingCropData);
+            setPreviewUrl(downloadURL);
+            setCropData(pendingCropData);
+            setPendingCropData(null);
+            setPendingUploadFile(null);
+            showToast("Avatar uploaded", "success");
+            onSaveComplete?.();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Upload failed";
+            onUploadError?.(message);
+            showToast(message, "error");
+        }
+    };
+    const handleCancelPending = () => {
+        setPendingCropData(null);
+        setPendingUploadFile(null);
+    };
+    const handleCropCancel = () => {
+        setShowCropModal(false);
+        setTempImageUrl(null);
+        setPendingFile(null);
+    };
+    const handleRemovePhoto = async () => {
+        try {
+            await onUploadSuccess?.("", {
+                url: "",
+                position: { x: 50, y: 50 },
+                zoom: 1,
+            });
+            setPreviewUrl(null);
+            setCropData(null);
+            setPendingCropData(null);
+            setPendingUploadFile(null);
+            onSaveComplete?.();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to remove photo";
+            onUploadError?.(message);
+        }
+        if (fileInputRef.current)
+            fileInputRef.current.value = "";
+    };
+    const hasPending = pendingCropData !== null && pendingUploadFile !== null;
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "space-y-4", "data-section": "avatarupload-div-404", children: [_jsxs("div", { className: "flex items-start gap-6", "data-section": "avatarupload-div-405", children: [_jsx("div", { className: "shrink-0", "data-section": "avatarupload-div-406", children: _jsx(AvatarDisplay, { cropData: hasPending ? pendingCropData : cropData, size: "2xl", className: `border-4 ${hasPending ? "border-primary/60 ring-2 ring-primary/20" : "border-zinc-200 dark:border-slate-700"}`, displayName: displayName }) }), _jsxs("div", { className: "flex-1 space-y-3", "data-section": "avatarupload-div-407", children: [_jsx(Text, { variant: "secondary", className: "text-xs", children: "JPG, PNG, WEBP or GIF up to 10MB." }), isUploading ? (_jsx(Progress, { value: 50, variant: "primary", size: "sm", label: t.uploading })) : null, hasPending && !isUploading ? (_jsxs("div", { className: "space-y-2", "data-section": "avatarupload-div-408", children: [_jsx(Text, { variant: "secondary", className: "text-xs text-primary", children: t.readyToSave }), _jsxs("div", { className: "flex gap-3", "data-section": "avatarupload-div-409", children: [_jsx(Button, { type: "button", onClick: handleConfirmSave, size: "sm", children: t.saveAvatar }), _jsx(Button, { type: "button", variant: "secondary", size: "sm", onClick: handleCancelPending, children: t.cancelChange })] })] })) : null, !hasPending && !isUploading ? (_jsxs("div", { className: "flex gap-3", "data-section": "avatarupload-div-410", children: [_jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), size: "sm", children: previewUrl ? t.changePhoto : t.chooseImage }), previewUrl ? (_jsx(Button, { type: "button", variant: "secondary", size: "sm", onClick: handleRemovePhoto, children: t.removePhoto })) : null] })) : null, _jsx(Input, { ref: fileInputRef, bare: true, type: "file", accept: "image/jpeg,image/png,image/webp,image/gif", onChange: handleFileSelect, className: "hidden", "aria-label": t.changePhoto })] })] }), uploadApiError ? (_jsx(Alert, { variant: "error", children: uploadApiError.message })) : null] }), showCropModal && tempImageUrl ? (_jsx(ImageCropModal, { isOpen: showCropModal, imageUrl: tempImageUrl, onClose: handleCropCancel, onSave: handleCropSave, initialCropData: cropData || undefined })) : null] }));
+}
+export default AvatarUpload;

package/dist/features/media/MediaAvatar.d.ts

@@ -0,0 +1,12 @@
+export interface MediaAvatarProps {
+    /** Avatar image URL. Shows a 👤 fallback when undefined. */
+    src: string | undefined;
+    /** Descriptive alt text — required for accessibility. */
+    alt: string;
+    /** Circular size preset. Defaults to `'md'`. */
+    size?: "sm" | "md" | "lg" | "xl";
+    /** Additional classes applied to the outer circle wrapper. */
+    className?: string;
+}
+export declare function MediaAvatar({ src, alt, size, className, }: MediaAvatarProps): import("react/jsx-runtime").JSX.Element;
+export default MediaAvatar;

package/dist/features/media/MediaAvatar.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MediaImage } from "./MediaImage";
+import { Div } from "../../ui";
+const sizeClasses = {
+    sm: "w-8 h-8",
+    md: "w-10 h-10",
+    lg: "w-14 h-14",
+    xl: "w-20 h-20",
+};
+export function MediaAvatar({ src, alt, size = "md", className = "", }) {
+    return (_jsx(Div, { className: `relative ${sizeClasses[size]} rounded-full overflow-hidden flex-shrink-0 ${className}`, children: _jsx(MediaImage, { src: src, alt: alt, size: "avatar" }) }));
+}
+export default MediaAvatar;

package/dist/features/media/MediaImage.d.ts

@@ -0,0 +1,30 @@
+export type MediaImageSize = "thumbnail" | "card" | "hero" | "banner" | "gallery" | "avatar";
+export interface MediaImageProps {
+    /** Image URL. When undefined the fallback icon is rendered instead. */
+    src: string | undefined;
+    /** Descriptive alt text — required for accessibility and SEO. */
+    alt: string;
+    /**
+     * Sizing preset — controls the `sizes` attribute passed to Next.js Image.
+     * Defaults to `'card'`.
+     */
+    size?: MediaImageSize;
+    /** Pass `true` for above-the-fold hero / banner images to skip lazy loading. */
+    priority?: boolean;
+    /** Override browser loading strategy when needed (`eager` for LCP images). */
+    loading?: "lazy" | "eager";
+    /** CSS object-fit applied to the underlying img element. Defaults to `'cover'`. */
+    objectFit?: "cover" | "contain";
+    /**
+     * Emoji or text to show when `src` is undefined.
+     * Falls back to the per-size default icon.
+     */
+    fallback?: string;
+    /**
+     * Extra Tailwind classes applied to the absolute-fill wrapper div.
+     * Use for hover animations, e.g. `group-hover:scale-110 transition-transform duration-300`.
+     */
+    className?: string;
+}
+export declare function MediaImage({ src, alt, size, priority, loading, objectFit, fallback, className, }: MediaImageProps): import("react/jsx-runtime").JSX.Element;
+export default MediaImage;

package/dist/features/media/MediaImage.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Image from "next/image";
+import { useState } from "react";
+import { Div, Span } from "../../ui";
+const SIZE_HINTS = {
+    thumbnail: "(max-width: 640px) 80px, (max-width: 1024px) 96px, 112px",
+    card: "(max-width: 640px) 50vw, (max-width: 1024px) 33vw, 25vw",
+    // Use a constrained fallback instead of unconditional 100vw to avoid
+    // the Next.js runtime warning when `fill` is used inside non-viewport
+    // width containers (cards, sliders). This still provides a helpful
+    // responsive hint while avoiding false-positive perf warnings.
+    hero: "(max-width: 768px) 100vw, 1200px",
+    banner: "(max-width: 768px) 100vw, 1200px",
+    gallery: "(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw",
+    avatar: "(max-width: 640px) 48px, 56px",
+};
+const FALLBACK_ICONS = {
+    thumbnail: "📦",
+    card: "📦",
+    hero: "🖼️",
+    banner: "🖼️",
+    gallery: "📦",
+    avatar: "👤",
+};
+export function MediaImage({ src, alt, size = "card", priority = false, loading, objectFit = "cover", fallback, className, }) {
+    const [hasError, setHasError] = useState(false);
+    const [isLoaded, setIsLoaded] = useState(false);
+    const icon = fallback ?? FALLBACK_ICONS[size];
+    const fitClass = objectFit === "contain" ? "object-contain" : "object-cover";
+    if (!src || hasError) {
+        return (_jsx(Div, { className: `relative w-full h-full overflow-hidden flex items-center justify-center bg-zinc-100 dark:bg-slate-800 text-zinc-400 text-4xl${className ? ` ${className}` : ""}`, role: "img", "aria-label": alt, children: _jsx(Span, { "aria-hidden": "true", children: icon }) }));
+    }
+    const isSvg = src.toLowerCase().endsWith(".svg") ||
+        src.includes("image/svg") ||
+        /[./]svg(\?|$)/i.test(src);
+    return (_jsxs(Div, { className: `relative w-full h-full overflow-hidden${className ? ` ${className}` : ""}`, children: [!isLoaded && (_jsx(Div, { className: "absolute inset-0 bg-zinc-200 dark:bg-slate-700 animate-pulse", "aria-hidden": "true" })), _jsx(Image, { src: src, alt: alt, fill: true, priority: priority, loading: loading ?? (priority ? "eager" : "lazy"), className: fitClass, sizes: SIZE_HINTS[size], onLoad: () => setIsLoaded(true), onError: () => setHasError(true), unoptimized: isSvg })] }));
+}
+export default MediaImage;

package/dist/features/media/MediaLightbox.d.ts

@@ -0,0 +1,31 @@
+export interface LightboxItem {
+    src: string;
+    alt: string;
+}
+export interface LightboxLabels {
+    prevImage?: string;
+    nextImage?: string;
+    zoomIn?: string;
+    zoomOut?: string;
+    resetZoom?: string;
+    enterFullscreen?: string;
+    exitFullscreen?: string;
+    close?: string;
+    /** Called with 1-based index: e.g. "Image 3" */
+    imageThumbnail?: (n: number) => string;
+    lightboxTitle?: string;
+}
+export interface MediaLightboxProps {
+    /** Array of image items to display in the viewer. */
+    items: LightboxItem[];
+    /** Index of the initially visible image. */
+    initialIndex?: number;
+    /** Whether the lightbox is open. */
+    isOpen: boolean;
+    /** Called when the user dismisses the lightbox. */
+    onClose: () => void;
+    /** Optional label overrides (for i18n integration). */
+    labels?: LightboxLabels;
+}
+export declare function MediaLightbox({ items, initialIndex, isOpen, onClose, labels, }: MediaLightboxProps): import("react/jsx-runtime").JSX.Element | null;
+export default MediaLightbox;