@intl-party/react 1.1.3 → 1.1.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 IntlParty Team
+Copyright (c) 2025-2026 IntlParty Team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,31 +1,29 @@
 # @intl-party/react
 
-React integration for IntlParty - hooks, context, and components for type-safe internationalization in React applications.
+**React integration for IntlParty with perfect TypeScript support and developer experience.**
 
-## Features
+## ✨ Features
 
-- ⚛️ **React hooks** - `useTranslations`, `useLocale`, `useNamespace`
-- 🎯 **Context provider** - `I18nProvider` for app-wide i18n state
-- 🧩 **Components** - `Trans`, `LocaleSelector` for declarative translations
-- 🔄 **Real-time updates** - Automatic re-renders when locale changes
-- 📱 **SSR support** - Server-side rendering compatible
-- 🎨 **Type safety** - Full TypeScript support with typed hooks
+- **⚛️ React Hooks**: `useTranslations`, `useLocale`, `useNamespace`
+- **🎯 Context Provider**: `I18nProvider` for app-wide i18n state
+- **🧩 Components**: `Trans`, `LocaleSelector` for declarative translations
+- **🔄 Real-time Updates**: Automatic re-renders when locale changes
+- **🔒 Type-Safe**: Full TypeScript support with auto-completion
+- **⚡ Performance Optimized**: Minimal re-renders and efficient caching
 
-## Installation
+## 🚀 Quick Start
+
+### Installation
 
 ```bash
 npm install @intl-party/react @intl-party/core
-# or
-pnpm add @intl-party/react @intl-party/core
-# or
-yarn add @intl-party/react @intl-party/core
 ```
 
-## Quick Start
+### Basic Usage
 
 ```tsx
 import React from "react";
-import { I18nProvider, useTranslations, useLocale } from "@intl-party/react";
+import { I18nProvider, useTranslations } from "@intl-party/react";
 import { createI18n } from "@intl-party/core";
 
 // Create i18n instance
@@ -35,308 +33,441 @@ const i18n = createI18n({
   namespaces: ["common"],
 });
 
-// Add translations
-i18n.addTranslations("en", "common", {
-  welcome: "Welcome!",
-  greeting: "Hello, {{name}}!",
-});
-
-i18n.addTranslations("es", "common", {
-  welcome: "¡Bienvenido!",
-  greeting: "¡Hola, {{name}}!",
-});
-
 function App() {
   return (
     <I18nProvider i18n={i18n}>
-      <HomePage />
+      <Welcome />
     </I18nProvider>
   );
 }
 
-function HomePage() {
+function Welcome() {
   const t = useTranslations("common");
-  const { locale, setLocale } = useLocale();
 
   return (
     <div>
       <h1>{t("welcome")}</h1>
-      <p>{t("greeting", { interpolation: { name: "John" } })}</p>
-
-      <button onClick={() => setLocale("es")}>Español</button>
-      <button onClick={() => setLocale("en")}>English</button>
-
-      <p>Current locale: {locale}</p>
+      <p>{t("greeting", { interpolation: { name: "World" } })}</p>
     </div>
   );
 }
 ```
 
-## Hooks
+## 🎯 API Reference
 
-### useTranslations
+### `I18nProvider`
 
-Get a translation function for a specific namespace:
+Provides i18n context to the React component tree.
 
 ```tsx
-import { useTranslations } from "@intl-party/react";
-
-function MyComponent() {
-  const t = useTranslations("common");
-
-  return (
-    <div>
-      <h1>{t("title")}</h1>
-      <p>
-        {t("description", {
-          interpolation: { name: "User" },
-          count: 5,
-        })}
-      </p>
-    </div>
-  );
-}
+<I18nProvider
+  i18n={i18nInstance}
+  initialLocale="en"
+  initialNamespace="common"
+  loadingComponent={<Loading />}
+  fallbackComponent={<Error />}
+>
+  {children}
+</I18nProvider>
+```
 
-// With fallback namespace
-function MyComponent() {
-  const t = useTranslations(["common", "fallback"]);
-  return <h1>{t("title")}</h1>;
+#### Props
+
+```typescript
+interface I18nProviderProps {
+  children: ReactNode;
+  i18n?: I18nInstance; // I18n instance
+  config?: I18nConfig; // Config (creates instance if not provided)
+  initialLocale?: Locale; // Initial locale
+  initialNamespace?: Namespace; // Initial namespace
+  loadingComponent?: ReactNode; // Loading component
+  fallbackComponent?: ReactNode; // Error fallback component
+  onLocaleChange?: (locale: Locale) => void;
+  onNamespaceChange?: (namespace: Namespace) => void;
+  onError?: (error: Error) => void;
 }
 ```
 
-### useLocale
+### Hooks
+
+#### `useTranslations(namespace?)`
 
-Manage the current locale:
+Main hook for using translations.
 
 ```tsx
-import { useLocale } from "@intl-party/react";
+// Without namespace (uses default)
+const t = useTranslations();
+
+// With namespace
+const t = useTranslations("common");
+
+// Usage
+t("welcome"); // "Welcome!"
+t("greeting", { interpolation: { name: "John" } }); // "Hello John!"
+t("navigation.home"); // "Home"
+```
+
+#### `useLocale()`
 
-function LocaleSwitcher() {
-  const { locale, setLocale, availableLocales } = useLocale();
+Get and set the current locale.
+
+```tsx
+function LocaleComponent() {
+  const [locale, setLocale] = useLocale();
 
   return (
-    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
-      {availableLocales.map((loc) => (
-        <option key={loc} value={loc}>
-          {loc}
-        </option>
-      ))}
-    </select>
+    <div>
+      <p>Current locale: {locale}</p>
+      <button onClick={() => setLocale("es")}>Español</button>
+      <button onClick={() => setLocale("fr")}>Français</button>
+    </div>
   );
 }
 ```
 
-### useNamespace
+#### `useNamespace()`
 
-Manage the current namespace:
+Get and set the current namespace.
 
 ```tsx
-import { useNamespace } from "@intl-party/react";
-
-function NamespaceSwitcher() {
-  const { namespace, setNamespace, availableNamespaces } = useNamespace();
+function NamespaceComponent() {
+  const [namespace, setNamespace] = useNamespace();
 
   return (
     <div>
       <p>Current namespace: {namespace}</p>
-      {availableNamespaces.map((ns) => (
-        <button key={ns} onClick={() => setNamespace(ns)}>
-          {ns}
-        </button>
-      ))}
+      <button onClick={() => setNamespace("navigation")}>Navigation</button>
+      <button onClick={() => setNamespace("auth")}>Auth</button>
     </div>
   );
 }
 ```
 
-### useI18nContext
+#### `useI18nContext()`
 
-Access the full i18n context:
+Access the full i18n context.
 
 ```tsx
-import { useI18nContext } from "@intl-party/react";
-
 function AdvancedComponent() {
-  const { i18n, locale, namespace } = useI18nContext();
+  const { i18n, locale, namespace, t, setLocale, setNamespace } =
+    useI18nContext();
 
-  // Direct access to i18n instance
-  const hasTranslation = i18n.hasTranslation("some.key");
-
-  return <div>...</div>;
+  return (
+    <div>
+      <p>Locale: {locale}</p>
+      <p>Namespace: {namespace}</p>
+      <button
+        onClick={() => i18n.addTranslations("en", "common", { new: "Key" })}
+      >
+        Add Translation
+      </button>
+    </div>
+  );
 }
 ```
 
-## Components
+## 🧩 Components
 
-### Trans Component
+### `Trans`
 
-Declarative translation with JSX interpolation:
+Component for translations with rich text and interpolation.
 
 ```tsx
 import { Trans } from "@intl-party/react";
 
-function MyComponent() {
+function RichText() {
   return (
     <Trans
-      namespace="common"
-      i18nKey="welcome.message"
-      values={{ name: "John", count: 5 }}
+      i18nKey="rich.greeting"
+      interpolation={{ name: "John" }}
       components={{
         bold: <strong />,
-        link: <a href="/profile" />,
+        link: <a href="/about" />,
       }}
-    />
+    >
+      Hello <bold>{{ name }}</bold>! Learn more <link>about</link>.
+    </Trans>
   );
 }
 ```
 
-Translation file:
+### `LocaleSelector`
+
+Pre-built locale selector component.
 
-```json
-{
-  "welcome": {
-    "message": "Hello <bold>{{name}}</bold>! You have <link>{{count}} messages</link>."
-  }
+```tsx
+import { LocaleSelector } from "@intl-party/react";
+
+function Header() {
+  return (
+    <LocaleSelector
+      locales={[
+        { code: "en", name: "English", flag: "🇺🇸" },
+        { code: "es", name: "Español", flag: "🇪🇸" },
+        { code: "fr", name: "Français", flag: "🇫🇷" },
+      ]}
+      variant="flags" // or "dropdown" or "compact"
+    />
+  );
 }
 ```
 
-### LocaleSelector Component
+## 🎨 Advanced Usage
+
+### Typed Translations
 
-Pre-built locale selector:
+```typescript
+interface AppTranslations {
+  common: {
+    welcome: string;
+    navigation: {
+      home: string;
+      about: string;
+    };
+  };
+  auth: {
+    login: string;
+    register: string;
+  };
+}
+
+// Create typed i18n instance
+const i18n = createI18n<AppTranslations>({
+  locales: ["en", "es", "fr"],
+  defaultLocale: "en",
+  namespaces: ["common", "auth"],
+});
+
+// Use with full type safety
+function TypedComponent() {
+  const t = useTranslations<AppTranslations["common"]>("common");
+
+  return (
+    <div>
+      {t("welcome")} {/* ✅ Type-safe */}
+      {t("navigation.home")} {/* ✅ Type-safe */}
+      {t("invalid.key")} {/* ❌ TypeScript error */}
+    </div>
+  );
+}
+```
+
+### Multiple Namespaces
 
 ```tsx
-import { LocaleSelector } from "@intl-party/react";
+function MultiNamespaceComponent() {
+  const commonT = useTranslations("common");
+  const authT = useTranslations("auth");
 
-function Header() {
   return (
-    <header>
-      <h1>My App</h1>
-      <LocaleSelector
-        className="locale-selector"
-        showFlags={true}
-        onChange={(locale) => console.log("Locale changed to:", locale)}
-      />
-    </header>
+    <div>
+      <h1>{commonT("welcome")}</h1>
+      <button>{authT("login")}</button>
+    </div>
   );
 }
 ```
 
-## Provider Configuration
+### Server-Side Rendering
+
+```tsx
+// Server component (Next.js App Router)
+async function ServerPage() {
+  const t = await getServerTranslations("common");
+
+  return (
+    <div>
+      <h1>{t("welcome")}</h1>
+    </div>
+  );
+}
+```
 
-### I18nProvider
+### Dynamic Namespace Loading
 
 ```tsx
-import { I18nProvider } from "@intl-party/react";
+function DynamicComponent({ namespace }: { namespace: string }) {
+  const t = useTranslations(namespace);
 
-function App() {
   return (
-    <I18nProvider
-      i18n={i18nInstance}
-      fallback={<div>Loading translations...</div>}
-    >
-      <YourApp />
-    </I18nProvider>
+    <div>
+      <h2>Namespace: {namespace}</h2>
+      <p>{t("title")}</p>
+    </div>
   );
 }
 ```
 
-### Server-Side Rendering
+## 🔧 Utilities
+
+### `createNamespaceHOC(namespace)`
 
-For SSR compatibility, initialize with server-detected locale:
+Higher-order component for automatic namespacing.
 
 ```tsx
-// Server-side
-import { createI18n } from "@intl-party/core";
+import { createNamespaceHOC } from "@intl-party/react";
 
-function createServerI18n(locale: string) {
-  const i18n = createI18n({
-    locales: ["en", "es", "fr"],
-    defaultLocale: "en",
-    namespaces: ["common"],
-  });
+const withNavigation = createNamespaceHOC("navigation");
 
-  i18n.setLocale(locale);
-  return i18n;
+function NavigationComponent({ t }) {
+  return (
+    <nav>
+      <a href="/">{t("home")}</a>
+      <a href="/about">{t("about")}</a>
+    </nav>
+  );
 }
 
-// In your SSR setup
-const i18n = createServerI18n(detectedLocale);
+export default withNavigation(NavigationComponent);
 ```
 
-## TypeScript Support
+### `useMultipleTranslations(namespaces)`
 
-Create typed hooks for better developer experience:
+Use multiple namespaces at once.
 
 ```tsx
-interface MyTranslations {
-  common: {
-    welcome: string;
-    user: {
-      profile: string;
-      settings: string;
-    };
-  };
-  navigation: {
-    home: string;
-    about: string;
-  };
-}
-
-// Type the hooks
-const useTypedTranslations = useTranslations as <
-  T extends keyof MyTranslations,
->(
-  namespace: T,
-) => (key: string) => string;
+function MultiNamespaceComponent() {
+  const { common, auth, navigation } = useMultipleTranslations([
+    "common",
+    "auth",
+    "navigation",
+  ]);
 
-function TypedComponent() {
-  const t = useTypedTranslations("common");
-  // Now t() has autocomplete for keys in 'common' namespace
-  return <h1>{t("welcome")}</h1>;
+  return (
+    <div>
+      <h1>{common("welcome")}</h1>
+      <button>{auth("login")}</button>
+      <nav>{navigation("home")}</nav>
+    </div>
+  );
 }
 ```
 
-## Advanced Usage
+## 🎨 Styling
 
-### Dynamic namespace loading
+### Theme Support
 
 ```tsx
-import { useTranslations, useI18nContext } from "@intl-party/react";
-
-function DynamicComponent() {
-  const { i18n } = useI18nContext();
-  const t = useTranslations("dynamic");
-
-  useEffect(() => {
-    // Load translations dynamically
-    import(`./translations/${i18n.locale}/dynamic.json`).then(
-      (translations) => {
-        i18n.addTranslations(i18n.locale, "dynamic", translations.default);
-      },
-    );
-  }, [i18n.locale]);
-
-  return <div>{t("content")}</div>;
+import { I18nProvider } from "@intl-party/react";
+
+function ThemedApp() {
+  return (
+    <I18nProvider
+      i18n={i18n}
+      theme="dark" // or "light", "auto"
+    >
+      <App />
+    </I18nProvider>
+  );
 }
 ```
 
-### Custom hook for scoped translations
+### Custom Components
 
 ```tsx
-function usePageTranslations(page: string) {
-  const { i18n } = useI18nContext();
-  return useMemo(
-    () => i18n.createScopedTranslator(`pages.${page}`),
-    [i18n, page],
+// Custom translation component
+function CustomTrans({ i18nKey, interpolation, components }) {
+  const t = useTranslations();
+
+  return (
+    <span className="translation">
+      {t(i18nKey, { interpolation, components })}
+    </span>
   );
 }
+```
 
-function ContactPage() {
-  const t = usePageTranslations("contact");
-  return <h1>{t("title")}</h1>; // translates 'pages.contact.title'
-}
+## 🔄 Migration from react-i18next
+
+### Simple Migration
+
+```tsx
+// react-i18next
+import { useTranslation } from "react-i18next";
+const { t } = useTranslation();
+
+// intl-party/react
+import { useTranslations } from "@intl-party/react";
+const t = useTranslations();
 ```
 
-## License
+### Benefits of switching:
+
+- ✅ **Better TypeScript**: No more `t('key' as any)`
+- ✅ **Simpler API**: Less boilerplate code
+- ✅ **Performance**: Optimized re-rendering
+- ✅ **Modern**: Built for React 18+ and concurrent features
+
+## 📦 Exports
+
+```typescript
+// Provider and context
+export {
+  I18nProvider,
+  TypedI18nProvider,
+  ScopedI18nProvider,
+  useI18nContext,
+  useTypedI18nContext,
+  withI18n,
+  type I18nProviderProps,
+  type TypedI18nProviderProps,
+  type ScopedI18nProviderProps,
+  type I18nContextValue,
+  type TypedI18nContextValue,
+};
+
+// Hooks
+export {
+  useTranslations,
+  useTypedTranslations,
+  useT,
+  useTypedT,
+  useScopedTranslations,
+  useMultipleTranslations,
+  useOptionalTranslation,
+  useTranslationWithFallback,
+  useHasTranslation,
+  useTranslationValue,
+  useInterpolatedTranslation,
+  usePluralization,
+};
+
+// Locale and namespace hooks
+export {
+  useLocale,
+  useLocaleInfo,
+  useLocaleSwitch,
+  useBrowserLocale,
+  useLocalePreference,
+  useDirection,
+  useFormatting,
+  useNamespace,
+  useNamespaceInfo,
+  useNamespaceSwitch,
+  useMultipleNamespaces,
+  useNamespacePreloading,
+};
+
+// Components
+export {
+  Trans,
+  ConditionalTrans,
+  PluralTrans,
+  RichTrans,
+  LocaleSelector,
+  FlagLocaleSelector,
+  CompactLocaleSelector,
+  AccessibleLocaleSelector,
+};
+
+// Utilities
+export { createI18nHook, createNamespaceHOC, I18nErrorBoundary };
+```
+
+## 🤝 Contributing
+
+See the [main README](../../README.md) for contribution guidelines.
+
+## 📄 License
 
-MIT © IntlParty
+MIT

package/dist/index.js

@@ -852,6 +852,25 @@ function LocaleSelector({
       locale
     )) });
   }
+  if (variant === "dropdown") {
+    return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className, style, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+      "select",
+      {
+        value: currentLocale,
+        onChange: (e) => handleLocaleChange(e.target.value),
+        disabled,
+        style: {
+          padding: "8px 12px",
+          borderRadius: "4px",
+          border: "1px solid #ccc",
+          backgroundColor: "white",
+          fontSize: "14px",
+          minWidth: "120px"
+        },
+        children: filteredLocales.map((locale) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("option", { value: locale, children: formatLocaleDisplay(locale) }, locale))
+      }
+    ) });
+  }
   return null;
 }
 function FlagLocaleSelector({

package/dist/index.mjs

@@ -786,6 +786,25 @@ function LocaleSelector({
       locale
     )) });
   }
+  if (variant === "dropdown") {
+    return /* @__PURE__ */ jsx3("div", { className, style, children: /* @__PURE__ */ jsx3(
+      "select",
+      {
+        value: currentLocale,
+        onChange: (e) => handleLocaleChange(e.target.value),
+        disabled,
+        style: {
+          padding: "8px 12px",
+          borderRadius: "4px",
+          border: "1px solid #ccc",
+          backgroundColor: "white",
+          fontSize: "14px",
+          minWidth: "120px"
+        },
+        children: filteredLocales.map((locale) => /* @__PURE__ */ jsx3("option", { value: locale, children: formatLocaleDisplay(locale) }, locale))
+      }
+    ) });
+  }
   return null;
 }
 function FlagLocaleSelector({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intl-party/react",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "React integration for IntlParty - hooks, context, and components for type-safe i18n",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -24,10 +24,14 @@
     "hooks",
     "context"
   ],
-  "author": "IntlParty Team",
+  "author": "RodrigoEspinosa",
   "license": "MIT",
+  "homepage": "https://github.com/RodrigoEspinosa/intl-party#readme",
+  "bugs": {
+    "url": "https://github.com/RodrigoEspinosa/intl-party/issues"
+  },
   "dependencies": {
-    "@intl-party/core": "1.0.2"
+    "@intl-party/core": "1.2.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.1.4",
@@ -49,9 +53,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/intl-party/intl-party.git",
+    "url": "https://github.com/RodrigoEspinosa/intl-party.git",
     "directory": "packages/react"
   },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "scripts": {
     "build": "tsup src/index.tsx src/server.ts --format cjs,esm --dts --external react,react-dom",
     "dev": "tsup src/index.tsx --format cjs,esm --external react,react-dom --watch",