@jchat/addon-sdk 1.0.0-alpha.30 → 1.0.0-alpha.31

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @jchat/addon-sdk
 
+## 1.0.0-alpha.31
+
+### Minor Changes
+
+- Add receiverId to message mutable data and findUserByName to AddonServerContext
+
+### Patch Changes
+
+- Clarify mandatory English base localization policy and fix dependency catalog configuration
+
+- Add useAddonSettings hook and AddonSettingsLoading component
+
+- Allow optional host language translation files with automatic English fallback
+
+- Add generic return type to AddonServerContext getConfig
+
+- Add findUserByName mock to testing context
+
+- Upgrade package type-checking to native bun check for faster validation
+
+- Consolidate icons and Tailwind styles into @jchat/addon-sdk/ui
+
+- Bumped `@jchat/*` dependencies:
+  - [`ui@1.0.0-alpha.28`](https://github.com/jchatcloud/jchat/releases/tag/ui@v1.0.0-alpha.28)
+
 ## 1.0.0-alpha.30
 
 ### Minor Changes

package/README.md

@@ -14,10 +14,10 @@ Provides typed interfaces, manifest contracts, Vite bundler plugins, and CLI dev
 JChat addons are **sandboxed, modular extensions** designed to enhance real-time chats without modifying core database schemas or server code.
 
 - **Ultra-Lightweight Server Bundles**: Elysia and TypeBox are externalized and provided directly by the host server runtime via `ctx.t` and `app`. Server bundles (`build/api.js`) compile down to just **2–7 KB**.
-- **Zero Frontend Bundle Bloat**: Host externals (`react`, `react-dom`, `@jchat/ui`, `@jchat/icon`, `@tanstack/react-query`, `jotai`) are injected at runtime by the JChat host application.
+- **Zero Frontend Bundle Bloat**: Host externals (`react`, `react-dom`, `@jchat/ui`, `@tanstack/react-query`, `jotai`) are injected at runtime by the JChat host application.
 - **Isolated Database Schema**: Addon tables reside exclusively in the isolated `addons` PostgreSQL schema (e.g. `addons.GlimpseStories`), preventing collisions with core chat tables.
 - **Scoped Cache & Real-Time Events**: Addons receive namespaced Redis cache (`addon:<id>:<key>`) and real-time WebSocket event broadcasting scoped to sites, rooms, or users.
-- **20-Language i18n Standard**: First-class internationalization with 100% parity across all 20 supported host languages, including full RTL direction support.
+- **First-Class i18n & RTL Support**: English (`en.json`) is mandatory as the base localization; the other 19 host languages are optional with automatic runtime fallback to English and full RTL direction support.
 
 ---
 
@@ -121,7 +121,7 @@ Addon UI components receive typed `AddonProps` and access host services via the
 
 ```tsx
 import { useAddonSDK, useAddonQuery, useTranslation, type AddonProps } from "@jchat/addon-sdk"
-import Icons from "@jchat/addon-sdk/icon"
+import { Icons } from "@jchat/addon-sdk/ui"
 import locales from "./locales"
 
 export default function MyAddon({ mountPoint, roomId }: AddonProps) {
@@ -308,8 +308,7 @@ export const activeTabAtom = atom<"trending" | "search">("trending")
 
 ### 4. Localization: `useTranslation()` & `useLocale()`
 
-Addons must support all **20 host languages**:
-`ar`, `bg`, `de`, `el`, `en`, `es`, `fr`, `he`, `hi`, `hr`, `kn`, `ml`, `nl`, `pt`, `ro`, `ru`, `ta`, `te`, `tr`, `ur`.
+English (`en.json`) is strictly mandatory as the base localization. The other 19 host languages (`ar`, `bg`, `de`, `el`, `es`, `fr`, `he`, `hi`, `hr`, `kn`, `ml`, `nl`, `pt`, `ro`, `ru`, `ta`, `te`, `tr`, `ur`) are optional and automatically fall back to English at runtime.
 
 ```tsx
 import { useTranslation, useLocale } from "@jchat/addon-sdk"
@@ -325,12 +324,12 @@ For backend server routes (`src/api.ts`), use `createTranslator(locales, default
 
 ---
 
-### 5. Icons: `@jchat/addon-sdk/icon`
+### 5. Icons: `@jchat/addon-sdk/ui`
 
-Imports the site's active icon pack directly, ensuring visual consistency with the host theme:
+Imports the site's active icon pack directly from `@jchat/addon-sdk/ui`, ensuring visual consistency with the host theme:
 
 ```tsx
-import Icons from "@jchat/addon-sdk/icon"
+import { Icons } from "@jchat/addon-sdk/ui"
 
 ;<Icons.Heart className="size-4 text-red-500" />
 ```

package/dist/i18n-validator.d.mts

@@ -6,12 +6,18 @@ export interface AddonLocaleValidationResult {
   missingKeys: Record<string, string[]>;
   extraKeys: Record<string, string[]>;
 }
+export interface ValidateAddonLocalesOptions {
+  strict?: boolean;
+}
 /**
- * Validates that an addon's `locales/` directory contains valid translation files for all 20 host
- * languages with 100% key parity against `en.json`.
+ * Validates that an addon's `locales/` directory contains a valid `en.json` base file, and that any
+ * provided host language files contain valid JSON and matching keys. Missing translations
+ * automatically fall back to English at runtime.
  *
  * @param dirPath - Path to the addon's locales directory.
  * @param domainName - Optional label for error messages (defaults to "Addon").
+ * @param options - Optional configuration (e.g. `{ strict: true }` to enforce 100% presence of all
+ *   20 language files).
  */
-export declare function validateAddonLocales(dirPath: string, domainName?: string): AddonLocaleValidationResult;
+export declare function validateAddonLocales(dirPath: string, domainName?: string, options?: ValidateAddonLocalesOptions): AddonLocaleValidationResult;
 //#endregion

package/dist/i18n-validator.mjs

@@ -14,13 +14,17 @@ function extractNestedKeys(obj, prefix = "") {
 	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`.
+* Validates that an addon's `locales/` directory contains a valid `en.json` base file, and that any
+* provided host language files contain valid JSON and matching keys. Missing translations
+* automatically fall back to English at runtime.
 *
 * @param dirPath - Path to the addon's locales directory.
 * @param domainName - Optional label for error messages (defaults to "Addon").
+* @param options - Optional configuration (e.g. `{ strict: true }` to enforce 100% presence of all
+*   20 language files).
 */
-function validateAddonLocales(dirPath, domainName = "Addon") {
+function validateAddonLocales(dirPath, domainName = "Addon", options) {
+	const isStrict = Boolean(options?.strict);
 	const errors = [];
 	const missingFiles = [];
 	const missingKeys = {};
@@ -58,17 +62,17 @@ function validateAddonLocales(dirPath, domainName = "Addon") {
 		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);
+			if (isStrict) errors.push(`[${domainName}] Missing locale file: ${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);
+				if (isStrict) errors.push(`[${domainName}] Missing key in ${langFileName}: "${key}"`);
 			}
 			for (const key of langKeys) if (!enKeys.has(key)) {
 				errors.push(`[${domainName}] Extra key in ${langFileName} (not in en.json): "${key}"`);