@gringow/gringow-react 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,87 @@
+# @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.
+
+## 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
+
+## Installation
+```bash
+pnpm add @gringow/gringow @gringow/gringow-react
+# npm install @gringow/gringow @gringow/gringow-react
+# 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)
+
+## Quick start
+Configure the store once when your application boots and then render translated strings with the `g` helper.
+
+```tsx
+// app-bootstrap.ts
+import { GringowStore } from '@gringow/gringow-react'
+
+GringowStore.defaultLanguage = 'en-US'
+GringowStore.cacheUrl = '/gringow/gringow.json'
+await GringowStore.fetchCache()
+```
+
+```tsx
+// Welcome.tsx
+import { g } from '@gringow/gringow-react'
+
+export function Welcome({ name }: { name: string }) {
+  return <>{g`Hello ${name}, welcome back!`}</>
+}
+```
+
+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.
+
+## Managing the translation cache
+The store can be fed from a static file or from the hosted Gringow IO endpoint.
+
+```tsx
+import { GringowStore } from '@gringow/gringow-react'
+
+// Static JSON generated by the CLI or Vite plugin
+GringowStore.cacheUrl = '/gringow/gringow.json'
+
+// Or fetch from Gringow IO using a short lived token
+GringowStore.gringowIoToken = process.env.GRINGOW_IO_TOKEN!
+```
+
+Call `GringowStore.fetchCache()` to force a refresh whenever you invalidate the cache.
+
+## Switching languages at runtime
+Dispatch the `LanguageChangeEvent` from anywhere in your app. All mounted Gringow translations react to the global event.
+
+```tsx
+import { LanguageChangeEvent } from '@gringow/gringow-react'
+
+function changeLanguage(lang: string) {
+  window.dispatchEvent(LanguageChangeEvent.create(lang))
+}
+```
+
+## API reference
+- `g(strings, ...values)` returns a `React.ReactNode` bound to the Gringow cache
+- `GringowStore` singleton exposes:
+  - `defaultLanguage` getter/setter
+  - `cacheUrl` and `gringowIoToken` setters (auto trigger cache fetch)
+  - `fetchCache(force?: boolean)` to load or refresh the cache
+  - `cache` getter with the resolved cache object (`Record<cacheId, GringowCacheItem>`)
+- `LanguageChangeEvent` class with `EVENT_NAME` constant and `create(lang)` helper
+
+## Development scripts
+```bash
+pnpm run build   # Compile TypeScript to dist/
+pnpm run watch   # Rebuild on changes during local development
+```
+
+## License
+MIT © Renato Gaspar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gringow/gringow-react",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "React bindings for Gringow AI-powered translation tool",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -21,9 +21,9 @@
     "typescript": "5.8.3"
   },
   "dependencies": {
-    "@gringow/gringow": "0.0.9",
     "react": "19.1.0",
-    "react-dom": "19.1.0"
+    "react-dom": "19.1.0",
+    "@gringow/gringow": "0.1.1"
   },
   "scripts": {
     "build": "rm -rf ./dist/* ./tsconfig.tsbuildinfo && tsup",