@jchat/addon-sdk 1.0.0-alpha.11 → 1.0.0-alpha.12

package/dist/diagnostics.d.mts

@@ -1,13 +1,13 @@
-import { t as AddonManifest } from "./contracts.mjs";
+import { AddonManifest } from "./contracts.mjs";
 //#region src/diagnostics.d.ts
 /**
  * Diagnostic result status indicator for addon validation checks. - `"pass"`: The diagnostic check
  * passed successfully. - `"warning"`: Non-critical warning (e.g. source maps present in
  * production). - `"error"`: Critical failure blocking addon installation or distribution.
  */
-type AddonDiagnosticStatus = "pass" | "warning" | "error";
+export type AddonDiagnosticStatus = "pass" | "warning" | "error";
 /** Represents an individual diagnostic check result for an addon package. */
-interface AddonPackageDiagnostic {
+export interface AddonPackageDiagnostic {
   /** Unique identifier for the diagnostic check (e.g. `"jchat"`, `"package-size"`). */
   id: string;
   /** Human-readable title for the diagnostic check. */
@@ -18,7 +18,7 @@ interface AddonPackageDiagnostic {
   message: string;
 }
 /** Options required to run diagnostic validation on an addon build package. */
-interface AddonPackageDiagnosticOptions {
+export interface AddonPackageDiagnosticOptions {
   /** Absolute path to the compiled addon build output directory (`build/`). */
   buildDir: string;
   /** Parsed addon manifest object (`manifest.json`). */
@@ -45,7 +45,7 @@ interface AddonPackageDiagnosticOptions {
  * @returns Semver range string matching the current major series (e.g. `">=1.2.0 <2.0.0"`).
  * @throws {@link Error} If the input is not a valid semantic version string.
  */
-declare function createCompatibleMajorRange(version: string): string;
+export declare function createCompatibleMajorRange(version: string): string;
 /**
  * Performs comprehensive diagnostic validation checks on an addon package build directory.
  *
@@ -57,13 +57,12 @@ declare function createCompatibleMajorRange(version: string): string;
  *   versions.
  * @returns Array of {@link AddonPackageDiagnostic} results.
  */
-declare function diagnoseAddonPackage(options: AddonPackageDiagnosticOptions): AddonPackageDiagnostic[];
+export declare function diagnoseAddonPackage(options: AddonPackageDiagnosticOptions): AddonPackageDiagnostic[];
 /**
  * Checks whether any diagnostic check in a diagnostic list returned a critical error.
  *
  * @param diagnostics - Array of diagnostic check results to evaluate.
  * @returns `true` if at least one check has `status === "error"`, otherwise `false`.
  */
-declare function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean;
-//#endregion
-export { AddonDiagnosticStatus, AddonPackageDiagnostic, AddonPackageDiagnosticOptions, createCompatibleMajorRange, diagnoseAddonPackage, hasAddonDiagnosticErrors };
+export declare function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean;
+//#endregion

package/dist/diagnostics.mjs

@@ -76,7 +76,7 @@ function diagnoseAddonPackage(options) {
 	const productionArchive = path$1.join(buildDir, `${manifest.id}-${manifest.version}.zip`);
 	const hasProductionArchive = fs$1.existsSync(productionArchive) && fs$1.statSync(productionArchive).isFile();
 	const totalBytes = options.productionPackage && hasProductionArchive ? fs$1.statSync(productionArchive).size : files.filter((file) => file !== productionArchive).reduce((total, file) => total + fs$1.statSync(file).size, 0);
-	const maxBytes = options.maxBytes ?? 25 * 1024 * 1024;
+	const maxBytes = options.maxBytes ?? 26214400;
 	diagnostics.push({
 		id: "package-size",
 		label: "Package size",

package/dist/i18n-validator.d.mts

@@ -0,0 +1,17 @@
+//#region src/i18n-validator.d.ts
+export interface AddonLocaleValidationResult {
+  valid: boolean;
+  errors: string[];
+  missingFiles: string[];
+  missingKeys: Record<string, string[]>;
+  extraKeys: Record<string, string[]>;
+}
+/**
+ * Validates that an addon's `locales/` directory contains valid translation files for all 20 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").
+ */
+export declare function validateAddonLocales(dirPath: string, domainName?: string): AddonLocaleValidationResult;
+//#endregion

package/dist/i18n-validator.mjs

@@ -0,0 +1,90 @@
+import { t as HOST_LANGUAGES } from "./i18n.mjs";
+import * as fs$1 from "node:fs";
+import * as path$1 from "node:path";
+//#region src/i18n-validator.ts
+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 20 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
+	};
+}
+//#endregion
+export { validateAddonLocales };

package/dist/i18n.mjs

@@ -0,0 +1,191 @@
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+//#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"
+];
+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
+export { useTranslation as a, useLocale as i, LocaleContext as n, createTranslator as r, HOST_LANGUAGES as t };

package/dist/icon.d.mts

@@ -0,0 +1,4 @@
+import { i as IconPack, n as IconComponent, r as IconName, t as ICON_NAMES } from "./types.mjs";
+import { a as getIconPack, c as lucidePack, i as fa6Pack, l as phosphorPack, n as Icons, o as heroPack, r as Youtube, s as isIconName, t as IconPackName, u as resolveIcon } from "./index.mjs";
+export * from "lucide-react";
+export { ICON_NAMES, type IconComponent, type IconName, type IconPack, IconPackName, Icons, Icons as default, Youtube, fa6Pack, getIconPack, heroPack, isIconName, lucidePack, phosphorPack, resolveIcon };

package/dist/icon.mjs

@@ -0,0 +1,4 @@
+import { i as IconPack, n as IconComponent, r as IconName, t as ICON_NAMES } from "./types.d.mts";
+import { a as getIconPack, c as lucidePack, i as fa6Pack, l as phosphorPack, n as Icons, o as heroPack, r as Youtube, s as isIconName, t as IconPackName, u as resolveIcon } from "./index.d.mts";
+export * from "lucide-react";
+export { ICON_NAMES, IconComponent, IconName, IconPack, IconPackName, Icons, Icons as default, Youtube, fa6Pack, getIconPack, heroPack, isIconName, lucidePack, phosphorPack, resolveIcon };