@gringow/gringow-react 0.0.8 → 0.2.0

package/README.md

@@ -1,90 +1,278 @@
 # @gringow/gringow-react
 
-React bindings for the Gringow AI powered translation engine. This package exposes a tiny React friendly wrapper on top of the core `@gringow/gringow` library so you can render translated template strings, consume cached translations, and switch languages at runtime.
+[![npm version](https://img.shields.io/npm/v/@gringow/gringow-react)](https://www.npmjs.com/package/@gringow/gringow-react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## Highlights
-- Declarative template strings via the `g` helper and a lightweight custom element
-- Client side cache bootstrap through `GringowStore` with either a static JSON URL or a Gringow IO token
-- Runtime language switching by dispatching the built in `LanguageChangeEvent`
-- Ships typed exports (`.d.ts`) and tree shakeable modules ready for modern bundlers
+React bindings for Gringow AI-powered translations. Provides declarative template string translations with runtime language switching and smart caching. Built on [@gringow/gringow-shadow](https://www.npmjs.com/package/@gringow/gringow-shadow) Web Components.
+
+## Features
+
+- ⚛️ **React 19+ Support** - Uses modern React features and hooks
+- 🏷️ **Template Literal Syntax** - Translate with \`g\`Hello ${name}\`\`
+- 🔄 **Runtime Language Switching** - Change languages without reload
+- 💾 **Smart Caching** - Automatic cache lookup and fallback
+- 🌐 **SSR Compatible** - Server-side rendering support
+- 🎯 **Type-Safe** - Full TypeScript definitions included
 
 ## Installation
+
 ```bash
+# Using pnpm
 pnpm add @gringow/gringow @gringow/gringow-react
-# npm install @gringow/gringow @gringow/gringow-react
-# yarn add @gringow/gringow @gringow/gringow-react
+
+# Using npm
+npm install @gringow/gringow @gringow/gringow-react
+
+# Using yarn
+yarn add @gringow/gringow @gringow/gringow-react
 ```
 
-### Peer requirements
-- React 19 or newer
-- A cache produced by the core Gringow tooling (CLI, Vite plugin, or direct API usage)
+### Requirements
+
+- **React 19+**
+- **A Gringow cache file** (generated by [@gringow/cli](https://www.npmjs.com/package/@gringow/gringow-cli) or [@gringow/gringow-vite](https://www.npmjs.com/package/@gringow/gringow-vite))
+
+## Quick Start
 
-## Quick start
-Register the custom element once on the client, configure the store, and then render translated strings with the `g`
-helper.
+### 1. Initialize Gringow (Client-Side)
 
 ```tsx
-// app-bootstrap.ts (client-only)
+// app-bootstrap.tsx (client-only)
 import '@gringow/gringow-react/browser'
 import { GringowStore } from '@gringow/gringow-react/store'
 
+// Configure store
 GringowStore.language = 'en-US'
 GringowStore.cacheUrl = '/gringow/gringow.json'
+
+// Fetch cache once
 await GringowStore.fetchCache()
 ```
 
+### 2. Use Translations in Components
+
 ```tsx
 // Welcome.tsx
 import { g } from '@gringow/gringow-react'
 
 export function Welcome({ name }: { name: string }) {
-  return <>{g`Hello ${name}, welcome back!`}</>
+  return (
+    <div>
+      <h1>{g`Hello ${name}, welcome back!`}</h1>
+      <p>{g`You have new messages`}</p>
+    </div>
+  )
 }
 ```
 
-The helper flattens the template string, looks up the cached translation by ID, and renders a `<g-gringow>` custom element wrapped in `React.Suspense`. Until the cache is available the original template literal is used as a fallback.
+### 3. Add Language Switcher
+
+```tsx
+// LanguageSwitcher.tsx
+import { changeLanguage } from '@gringow/gringow-react'
+
+export function LanguageSwitcher() {
+  return (
+    <div>
+      <button onClick={() => changeLanguage('en-US')}>English</button>
+      <button onClick={() => changeLanguage('pt-BR')}>Português</button>
+      <button onClick={() => changeLanguage('fr-CA')}>Français</button>
+    </div>
+  )
+}
+```
 
-> The `browser` entry registers the `<g-gringow>` element and wires it to `GringowStore`. Import it once per
-> application (typically in your client bootstrap).
+## Usage Examples
 
-## Managing the translation cache
-The store can be fed from a static file or from a hosted endpoint. When not set programmatically, `cacheUrl` falls back
-to `<meta name="gringow-cache-url">` or `data-gringow-cache-url` on `<html>`, and `language` defaults to
-`document.documentElement.lang`.
+### Basic Translation
 
 ```tsx
-import { GringowStore } from '@gringow/gringow-react'
+import { g } from '@gringow/gringow-react'
 
-// Static JSON generated by the CLI or Vite plugin
-GringowStore.cacheUrl = '/gringow/gringow.json'
+function Greeting() {
+  return <h1>{g`Welcome to Gringow`}</h1>
+}
+```
+
+### Dynamic Content
+
+```tsx
+import { g } from '@gringow/gringow-react'
 
-// Or fetch from Gringow IO using a short lived token
-GringowStore.gringowIoToken = process.env.GRINGOW_IO_TOKEN!
+function UserProfile({ user }: { user: { name: string; role: string } }) {
+  return (
+    <div>
+      {g`Hello ${user.name}!`}
+      {g`Your role: ${user.role}`}
+    </div>
+  )
+}
 ```
 
-Call `GringowStore.fetchCache()` to force a refresh whenever you invalidate the cache.
+### Full Application Example
+
+```tsx
+// main.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import '@gringow/gringow-react/browser'
+import { GringowStore } from '@gringow/gringow-react/store'
+import App from './App'
+
+// Bootstrap Gringow
+async function init() {
+  GringowStore.cacheUrl = '/gringow/gringow.json'
+  GringowStore.language = document.documentElement.lang || 'en-US'
+  await GringowStore.fetchCache()
 
-## Switching languages at runtime
-Dispatch the `LanguageChangeEvent` from anywhere in your app. All mounted Gringow translations react to the global event.
+  ReactDOM.createRoot(document.getElementById('root')!).render(
+    <React.StrictMode>
+      <App />
+    </React.StrictMode>
+  )
+}
+
+init()
+```
 
 ```tsx
-import { LanguageChangeEvent } from '@gringow/gringow-react'
+// App.tsx
+import { g, changeLanguage } from '@gringow/gringow-react'
+
+export default function App() {
+  const [user] = React.useState({ name: 'Alice', unread: 5 })
 
-function changeLanguage(lang: string) {
-  window.dispatchEvent(LanguageChangeEvent.create(lang))
+  return (
+    <div>
+      <nav>
+        <button onClick={() => changeLanguage('en-US')}>EN</button>
+        <button onClick={() => changeLanguage('pt-BR')}>PT</button>
+        <button onClick={() => changeLanguage('es-ES')}>ES</button>
+      </nav>
+
+      <main>
+        <h1>{g`Welcome ${user.name}!`}</h1>
+        <p>{g`You have ${user.unread} unread messages`}</p>
+        <button>{g`Mark all as read`}</button>
+      </main>
+    </div>
+  )
 }
 ```
 
-## API reference
-- `g(strings, ...values)` returns a `<g-gringow>` element keyed by the flattened template string.
-- `GringowStore` singleton exposes:
-  - `language` getter/setter (defaults to `<html lang>`)
-  - `cacheUrl` setter (fallback to `<meta name="gringow-cache-url">` or `data-gringow-cache-url`)
-  - `fetchCache()` to load the cache once (throws if URL or language are missing)
-  - `getCacheItem(cacheId)` to resolve a translation for the current language, falling back to the original string
-  - `cache` getter with the resolved cache object (`Record<cacheId, GringowCacheItem>`)
-- `LanguageChangeEvent` class with `EVENT_NAME` constant and `create(lang)` helper
-- `changeLanguage(lang)` dispatches the language change event for convenience
+### With Vite
+
+```tsx
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { GringowVitePlugin } from '@gringow/gringow-vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    GringowVitePlugin()
+  ]
+})
+```
+
+## API Reference
+
+### `g` Template Tag
+
+Main translation function using tagged template literals.
+
+```typescript
+function g(strings: TemplateStringsArray, ...values: unknown[]): ReactNode
+```
+
+**Example:**
+```tsx
+{g`Hello ${name}!`}
+{g`You have ${count} messages`}
+```
+
+The `g` helper:
+1. Flattens the template string
+2. Creates a cache ID via content hashing
+3. Returns a `<g-gringow>` custom element
+4. Falls back to original string if cache unavailable
+
+### GringowStore
+
+Singleton store for managing translation cache and language state.
+
+#### Properties
+
+```typescript
+// Active language (defaults to document.documentElement.lang)
+GringowStore.language: string | null
+
+// Cache file URL
+GringowStore.cacheUrl: string | null
+
+// Loaded cache object
+GringowStore.cache: GringowCache | null
+```
+
+#### Methods
+
+```typescript
+// Fetch and cache translations
+await GringowStore.fetchCache(): Promise<void>
+
+// Get translation for specific cache ID
+GringowStore.getCacheItem(cacheId: string): string | null
+
+// Manually set cache
+GringowStore.setCache(cache: GringowCache): void
+```
+
+#### Configuration Fallbacks
+
+`cacheUrl` resolution order:
+1. `GringowStore.cacheUrl` (programmatic)
+2. `<meta name="gringow-cache-url" content="/path">`
+3. `<html data-gringow-cache-url="/path">`
+
+### changeLanguage()
+
+Convenience function for language switching.
+
+```typescript
+function changeLanguage(lang: string): void
+```
+
+**Example:**
+```tsx
+<button onClick={() => changeLanguage('pt-BR')}>Português</button>
+```
+
+Dispatches a global `LanguageChangeEvent` that updates all mounted components.
+
+### LanguageChangeEvent
+
+Custom event for language changes.
+
+```typescript
+class LanguageChangeEvent extends CustomEvent<{ lang: string }>
+
+// Constants
+LanguageChangeEvent.EVENT_NAME: 'gringow:language-change'
+
+// Factory method
+LanguageChangeEvent.create(lang: string): LanguageChangeEvent
+```
+
+**Manual usage:**
+```tsx
+window.dispatchEvent(LanguageChangeEvent.create('fr-CA'))
+
+// Listen for changes
+window.addEventListener(LanguageChangeEvent.EVENT_NAME, (event) => {
+  console.log('Language changed to:', event.detail.lang)
+})
+```
 
 ## Development scripts
 ```bash
@@ -94,3 +282,81 @@ pnpm run watch   # Rebuild on changes during local development
 
 ## License
 MIT © Renato Gaspar
+
+## How It Works
+
+1. **Template Literal** - `g` tag flattens strings and generates cache IDs
+2. **Custom Element** - Returns `<g-gringow>` Web Component (from shadow package)
+3. **Cache Lookup** - Component queries `GringowStore` for translations
+4. **Fallback** - Shows original text if cache unavailable or SSR
+5. **Reactivity** - Updates automatically on `LanguageChangeEvent`
+
+## SSR Support
+
+The package handles server-side rendering gracefully:
+
+```tsx
+// Server renders original text
+{g`Hello ${name}`} // Outputs: "Hello Alice"
+
+// Client hydrates and replaces with translation
+{g`Hello ${name}`} // Outputs: "Olá Alice" (if pt-BR)
+```
+
+The `<g-gringow>` element only translates on the client after cache loads.
+
+## Module Exports
+
+```typescript
+// Main export
+import { g, changeLanguage, LanguageChangeEvent } from '@gringow/gringow-react'
+
+// Store export
+import { GringowStore } from '@gringow/gringow-react/store'
+
+// Browser initialization (import once)
+import '@gringow/gringow-react/browser'
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm run build
+
+# Watch mode
+pnpm run watch
+```
+
+## Best Practices
+
+1. **Import browser module once** - Do it in your app's entry point
+2. **Fetch cache early** - Call `GringowStore.fetchCache()` before rendering
+3. **Use Vite plugin** - Automatically extracts translations during build
+4. **Keep fallbacks** - Original strings serve as loading state
+5. **Cache versioning** - Bust cache when translations update
+
+## Related Packages
+
+- **[@gringow/gringow](https://www.npmjs.com/package/@gringow/gringow)** - Core translation library
+- **[@gringow/gringow-shadow](https://www.npmjs.com/package/@gringow/gringow-shadow)** - Web Component layer (this package depends on it)
+- **[@gringow/gringow-vite](https://www.npmjs.com/package/@gringow/gringow-vite)** - Vite plugin for build-time extraction
+- **[@gringow/cli](https://www.npmjs.com/package/@gringow/gringow-cli)** - CLI for translation management
+- **[@gringow/gringow-nextjs](https://www.npmjs.com/package/@gringow/gringow-nextjs)** - Next.js plugin (experimental)
+
+## Resources
+
+- [Documentation](https://gringow.dev)
+- [GitHub Repository](https://github.com/rntgspr/gringow)
+- [Example: React + Vite](https://github.com/rntgspr/gringow/tree/main/example-gringow-vite)
+
+## License
+
+MIT © [Renato Gaspar](https://github.com/rntgspr)
+
+---
+
+**Need Help?** Open an issue on [GitHub](https://github.com/rntgspr/gringow/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gringow/gringow-react",
-  "version": "0.0.8",
+  "version": "0.2.0",
   "description": "React bindings for Gringow AI-powered translation tool",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -35,8 +35,8 @@
     "@types/react": "^19.2.7",
     "react": "19.1.0",
     "react-dom": "19.1.0",
-    "@gringow/gringow": "0.1.3",
-    "@gringow/gringow-shadow": "0.0.3"
+    "@gringow/gringow": "0.2.0",
+    "@gringow/gringow-shadow": "0.2.0"
   },
   "scripts": {
     "build": "rm -rf ./dist/* ./tsconfig.tsbuildinfo && tsup",