@jchat/addon-sdk 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/index.mjs

@@ -1,5 +1,12 @@
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+import * as fs$1 from "node:fs";
+import * as path$1 from "node:path";
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 //#region package.json
-var version = "1.0.0-alpha.6";
+var version = "1.0.0-alpha.8";
+//#endregion
+//#region ../icon/dist/types.mjs
+const e = `Activity.ArrowLeft.ArrowRight.Ban.Bell.BookOpen.Brush.Calendar.Camera.ChartBar.Check.CheckCheck.CheckCircle2.ChevronDown.ChevronLeft.ChevronRight.ChevronUp.CircleAlert.CircleCheck.CircleOff.CirclePlay.CirclePlus.Clock.Coffee.Contact.Cpu.Database.Dices.Ellipsis.Eraser.ExternalLink.Eye.EyeOff.Flag.Flame.FolderPlus.Footprints.Gamepad2.Gift.Globe.HardDrive.Headphones.Heart.Image.Info.Key.KeyRound.Layers.LayoutDashboard.LayoutList.LayoutTemplate.Link2.ListOrdered.Loader.LoaderCircle.Lock.LogOut.Mail.Maximize.Megaphone.MemoryStick.Menu.MessageCircle.MessageSquare.Mic.Minimize.Minus.Monitor.Moon.MoreHorizontal.Music.Music2.Newspaper.Palette.Paperclip.PartyPopper.Pause.PenLine.Play.Plus.Radio.Reply.RotateCcw.RotateCw.Search.Send.Server.Settings.Shield.ShieldAlert.ShieldCheck.SkipForward.SlidersHorizontal.Smartphone.Smile.Sparkles.Square.SquarePen.Star.Sun.ThumbsDown.ThumbsUp.Timer.Trash.Trash2.Trophy.Upload.User.UserCheck.UserCog.UserMinus.UserPen.UserPlus.UserRoundPlus.Users.UserX.Utensils.Video.VideoOff.Volume.Volume2.VolumeX.X.Youtube.Zap`.split(`.`);
 //#endregion
 //#region src/contracts.ts
 /** Valid locations where an addon can be rendered within the Jchat layout. */
@@ -28,6 +35,8 @@ const MOUNT_POINTS = {
 	CHAT_PLUS_MENU: "chat-plus-menu",
 	/** Custom tab in the emoji/gif selection panel */
 	EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab",
+	/** Custom tab in the emoji/sticker selection panel */
+	EMOJI_PICKER_STICKER_TAB: "emoji-picker-sticker-tab",
 	/** Full-screen or modal dialog specifically for TubeScan */
 	TUBESCAN_DIALOG: "tubescan-dialog",
 	/** Dedicated settings panel rendered in the Owner Dashboard */
@@ -36,6 +45,369 @@ const MOUNT_POINTS = {
 	ADDON_SETTINGS: "addon-settings"
 };
 //#endregion
+//#region src/i18n.ts
+function checkIsRtl(code) {
+	if (!code) return false;
+	const normalized = code.toLowerCase().split("-")[0];
+	return normalized === "ar" || normalized === "he" || normalized === "ur";
+}
+function getLanguageDirection(code) {
+	return checkIsRtl(code) ? "rtl" : "ltr";
+}
+function interpolate(text, params) {
+	if (!params) return text;
+	return text.replace(/\{\{\s*(\w+)\s*\}\}|\{\s*(\w+)\s*\}/g, (match, key1, key2) => {
+		const key = key1 || key2;
+		return key in params ? String(params[key]) : match;
+	});
+}
+const HOST_LANGUAGES = [
+	"ar",
+	"bg",
+	"hr",
+	"de",
+	"el",
+	"en",
+	"es",
+	"fr",
+	"he",
+	"hi",
+	"kn",
+	"ml",
+	"nl",
+	"pt",
+	"ro",
+	"ru",
+	"ta",
+	"te",
+	"tr",
+	"ur"
+];
+function extractNestedKeys(obj, prefix = "") {
+	if (!obj || typeof obj !== "object") return [];
+	const keys = [];
+	for (const [key, value] of Object.entries(obj)) {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+		if (value && typeof value === "object" && !Array.isArray(value)) keys.push(...extractNestedKeys(value, fullKey));
+		else keys.push(fullKey);
+	}
+	return keys;
+}
+/**
+* Validates that an addon's `locales/` directory contains valid translation files for all 11 host
+* languages with 100% key parity against `en.json`.
+*
+* @param dirPath - Path to the addon's locales directory.
+* @param domainName - Optional label for error messages (defaults to "Addon").
+*/
+function validateAddonLocales(dirPath, domainName = "Addon") {
+	const errors = [];
+	const missingFiles = [];
+	const missingKeys = {};
+	const extraKeys = {};
+	const enPath = path$1.join(dirPath, "en.json");
+	if (!fs$1.existsSync(enPath)) {
+		const errorMsg = `[${domainName}] Missing base locale file: en.json`;
+		errors.push(errorMsg);
+		missingFiles.push("en.json");
+		return {
+			valid: false,
+			errors,
+			missingFiles,
+			missingKeys,
+			extraKeys
+		};
+	}
+	let enContent;
+	try {
+		enContent = JSON.parse(fs$1.readFileSync(enPath, "utf-8"));
+	} catch (err) {
+		const errorMsg = `[${domainName}] Invalid JSON in en.json: ${err instanceof Error ? err.message : String(err)}`;
+		errors.push(errorMsg);
+		return {
+			valid: false,
+			errors,
+			missingFiles,
+			missingKeys,
+			extraKeys
+		};
+	}
+	const enKeys = new Set(extractNestedKeys(enContent));
+	for (const lang of HOST_LANGUAGES) {
+		if (lang === "en") continue;
+		const langFileName = `${lang}.json`;
+		const langPath = path$1.join(dirPath, langFileName);
+		if (!fs$1.existsSync(langPath)) {
+			errors.push(`[${domainName}] Missing locale file: ${langFileName}`);
+			missingFiles.push(langFileName);
+			continue;
+		}
+		try {
+			const langContent = JSON.parse(fs$1.readFileSync(langPath, "utf-8"));
+			const langKeys = new Set(extractNestedKeys(langContent));
+			for (const key of enKeys) if (!langKeys.has(key)) {
+				errors.push(`[${domainName}] Missing key in ${langFileName}: "${key}"`);
+				if (!missingKeys[lang]) missingKeys[lang] = [];
+				missingKeys[lang].push(key);
+			}
+			for (const key of langKeys) if (!enKeys.has(key)) {
+				errors.push(`[${domainName}] Extra key in ${langFileName} (not in en.json): "${key}"`);
+				if (!extraKeys[lang]) extraKeys[lang] = [];
+				extraKeys[lang].push(key);
+			}
+		} catch (err) {
+			errors.push(`[${domainName}] Invalid JSON in ${langFileName}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		missingFiles,
+		missingKeys,
+		extraKeys
+	};
+}
+const LocaleContext = createContext({
+	locale: "en",
+	dir: "ltr"
+});
+/** Resolves a nested key in an object dictionary using dot-notation (e.g. "buttons.submit") */
+function resolveNestedKey(obj, keyPath) {
+	if (!obj || typeof obj !== "object") return void 0;
+	const segments = keyPath.split(".");
+	let current = obj;
+	for (const seg of segments) if (current && typeof current === "object" && seg in current) current = current[seg];
+	else return;
+	return current;
+}
+/**
+* Creates a standalone translation function for backend server routes (`src/api.ts`) or utilities.
+*
+* @param resources - Dictionary of translation resources (e.g., `{ en: enJson, ta: taJson }`).
+* @param defaultLocale - Default locale to use if not specified per call (defaults to "en").
+* @param fallbackLocale - Fallback locale if a key is missing in the target language (defaults to
+*   "en").
+*/
+function createTranslator(resources = {}, defaultLocale = "en", fallbackLocale = "en") {
+	return (key, paramsOrLang, maybeLang) => {
+		let params;
+		let lang = defaultLocale;
+		if (typeof paramsOrLang === "string") lang = paramsOrLang;
+		else if (paramsOrLang && typeof paramsOrLang === "object") {
+			params = paramsOrLang;
+			if (typeof maybeLang === "string") lang = maybeLang;
+		}
+		const normalizedLang = (lang || defaultLocale).toLowerCase().split("-")[0];
+		const normalizedFallback = fallbackLocale.toLowerCase().split("-")[0];
+		const langDict = resources[normalizedLang];
+		let resolved = resolveNestedKey(langDict, key);
+		if (resolved === void 0 && normalizedLang !== normalizedFallback) {
+			const fallbackDict = resources[normalizedFallback];
+			resolved = resolveNestedKey(fallbackDict, key);
+		}
+		if (typeof resolved === "string") return interpolate(resolved, params);
+		return typeof resolved === "number" || typeof resolved === "boolean" ? String(resolved) : interpolate(key, params);
+	};
+}
+/**
+* Hook to access the current active host locale and text direction in an addon component.
+*
+* @example
+*   ;```tsx
+*   import { useLocale } from "@jchat/addon-sdk"
+*
+*   export default function MyAddon() {
+*     const { locale, dir, isRtl } = useLocale()
+*     return <div dir={dir}>Current language: {locale}</div>
+*   }
+*   ```
+*/
+function useLocale() {
+	const context = useContext(LocaleContext);
+	const locale = context?.locale || "en";
+	const dir = context?.dir || getLanguageDirection(locale);
+	return {
+		locale,
+		dir,
+		isRtl: dir === "rtl" || checkIsRtl(locale)
+	};
+}
+const loadedChunkCache = {};
+/**
+* Hook to access translation function and locale metadata inside addon components. Automatically
+* synchronizes with host language switches and falls back to English. Supports static dictionary
+* resources or dynamic async locale loaders.
+*
+* @example
+*   ;```tsx
+*   import { useTranslation } from "@jchat/addon-sdk"
+*   import locales from "./locales"
+*
+*   export default function MyAddon() {
+*     const { t, locale, dir } = useTranslation(locales)
+*     return (
+*       <div dir={dir}>
+*         <h1>{t("welcome", { name: "Guest" })}</h1>
+*       </div>
+*     )
+*   }
+*   ```
+*
+* @param resourcesOrLoader - Addon-scoped translation dictionaries or async chunk loader.
+* @param fallbackLocale - Fallback language code when a string is missing (default: "en").
+*/
+function useTranslation(resourcesOrLoader = {}, fallbackLocale = "en") {
+	const { locale, dir, isRtl } = useLocale();
+	const isLoader = typeof resourcesOrLoader === "function";
+	const [dynamicResources, setDynamicResources] = useState(() => {
+		return isLoader ? loadedChunkCache : resourcesOrLoader;
+	});
+	const [isReady, setIsReady] = useState(!isLoader);
+	useEffect(() => {
+		if (!isLoader) {
+			setDynamicResources(resourcesOrLoader);
+			setIsReady(true);
+			return;
+		}
+		const loader = resourcesOrLoader;
+		const normLocale = locale.toLowerCase().split("-")[0];
+		if (loadedChunkCache[normLocale]) {
+			setDynamicResources((prev) => ({
+				...prev,
+				[normLocale]: loadedChunkCache[normLocale]
+			}));
+			setIsReady(true);
+			return;
+		}
+		let isMounted = true;
+		Promise.resolve(loader(normLocale)).then((dict) => {
+			if (!isMounted || !dict) return;
+			loadedChunkCache[normLocale] = dict;
+			setDynamicResources((prev) => ({
+				...prev,
+				[normLocale]: dict
+			}));
+			setIsReady(true);
+		}).catch((err) => {
+			console.warn(`[addon-sdk] Failed to dynamically load locale chunk "${normLocale}":`, err);
+			if (isMounted) setIsReady(true);
+		});
+		return () => {
+			isMounted = false;
+		};
+	}, [
+		isLoader,
+		resourcesOrLoader,
+		locale
+	]);
+	const translator = useMemo(() => {
+		return createTranslator(dynamicResources, locale, fallbackLocale);
+	}, [
+		dynamicResources,
+		locale,
+		fallbackLocale
+	]);
+	return {
+		t: useMemo(() => {
+			return (key, params) => translator(key, params, locale);
+		}, [translator, locale]),
+		locale,
+		dir,
+		isRtl,
+		isReady
+	};
+}
+//#endregion
+//#region src/query.ts
+/**
+* Perform a declarative, cached GET request using the host's shared React Query instance.
+* Automatically injects authentication headers and prefixes addon paths.
+*
+* @example
+*   ;```tsx
+*   const { data, isLoading } = useAddonQuery<{ polls: Poll[] }>({
+*     path: "/polls",
+*     queryKey: [siteId]
+*   })
+*   ```
+*/
+function useAddonQuery(options) {
+	const sdk = useAddonSDK();
+	const { path, queryKey = [], queryFn, ...queryOptions } = options;
+	const effectiveKey = path !== void 0 ? [path, ...queryKey] : queryKey;
+	const effectiveFn = queryFn ?? (() => {
+		if (!path) throw new Error("useAddonQuery requires either a `path` or a custom `queryFn`");
+		return sdk.api.get(path);
+	});
+	return useQuery({
+		...queryOptions,
+		queryKey: effectiveKey,
+		queryFn: effectiveFn
+	});
+}
+/**
+* Perform a paginated or infinite scrolling request using the host's shared React Query instance.
+*
+* @example
+*   ;```tsx
+*   const { data, fetchNextPage, hasNextPage } = useAddonInfiniteQuery<GifResponse, Error, number>({
+*   path: (page) => `/trending?offset=${page * 20}`,
+*   initialPageParam: 0,
+*   getNextPageParam: (lastPage, allPages) => (lastPage.hasMore ? allPages.length : undefined)
+*   })
+*   ```
+*/
+function useAddonInfiniteQuery(options) {
+	const sdk = useAddonSDK();
+	const { path, queryKey = [], queryFn, ...infiniteOptions } = options;
+	const effectiveKey = [typeof path === "string" ? path : "infinite", ...queryKey];
+	const effectiveFn = queryFn ?? (async (context) => {
+		const pageParam = context.pageParam;
+		const resolvedPath = typeof path === "function" ? path(pageParam) : path;
+		if (!resolvedPath) throw new Error("useAddonInfiniteQuery requires either a `path` or a custom `queryFn`");
+		return sdk.api.get(resolvedPath);
+	});
+	return useInfiniteQuery({
+		...infiniteOptions,
+		queryKey: effectiveKey,
+		queryFn: effectiveFn
+	});
+}
+/**
+* Perform a declarative mutation using the host's shared React Query instance. Automatically
+* executes the request and can invalidate specified query keys upon success.
+*
+* @example
+*   ;```tsx
+*   const { mutate, isPending } = useAddonMutation<Poll, CreatePollInput>({
+*     path: "/polls",
+*     method: "POST",
+*     invalidateQueries: [["/polls"]],
+*     onSuccess: () => sdk.toast("Poll created!", "success")
+*   })
+*   ```
+*/
+function useAddonMutation(options) {
+	const sdk = useAddonSDK();
+	const queryClient = useQueryClient();
+	const { path, method = "POST", invalidateQueries = [], mutationFn, onSuccess, ...mutationOptions } = options;
+	const effectiveFn = mutationFn ?? (async (variables) => {
+		const resolvedPath = typeof path === "function" ? path(variables) : path ?? "";
+		if (!resolvedPath) throw new Error("useAddonMutation requires a valid 'path' or 'mutationFn'.");
+		if (method === "PUT") return sdk.api.put(resolvedPath, variables);
+		if (method === "DELETE") return sdk.api.delete(resolvedPath);
+		return sdk.api.post(resolvedPath, variables);
+	});
+	return useMutation({
+		...mutationOptions,
+		mutationFn: effectiveFn,
+		onSuccess: async (...args) => {
+			if (invalidateQueries.length > 0) await Promise.all(invalidateQueries.map((key) => queryClient.invalidateQueries({ queryKey: key })));
+			if (onSuccess) await onSuccess(...args);
+		}
+	});
+}
+//#endregion
 //#region src/index.ts
 /** Define a manifest with full validation-friendly typing while preserving literal values. */
 function defineAddonManifest(manifest) {
@@ -106,4 +478,4 @@ function getAddonSdkVersion() {
 	return version;
 }
 //#endregion
-export { MOUNT_POINTS, defineAddonManifest, defineAddonServer, getAddonSdkVersion, useAddonSDK, useIcons };
+export { HOST_LANGUAGES, e as ICON_NAMES, LocaleContext, MOUNT_POINTS, createTranslator, defineAddonManifest, defineAddonServer, getAddonSdkVersion, useAddonInfiniteQuery, useAddonMutation, useAddonQuery, useAddonSDK, useIcons, useLocale, useQueryClient, useTranslation, validateAddonLocales };