@usenavii/react 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,119 @@
+# @usenavii/react
+
+**React binding for [Navii](https://navii.uxderrick.com) — deterministic mascot avatars.**
+Drop a `<Navii seed={user.id} />` and every user has a face, no uploads.
+
+<p align="center">
+  <img src="https://navii-api.uxderrick.com/group?seeds=aria,milo,nova,kai,sage,eden,luna,rio,pip,wren,zane,iris&size=72&overlap=0.32&ring=%230a0a0b&tileBg=%23ffffff" alt="Navii cast" />
+</p>
+
+- [Live demo](https://navii.uxderrick.com)
+- [Docs](https://navii.uxderrick.com/docs)
+- [GitHub](https://github.com/uxderrick/navii)
+
+## Install
+
+```sh
+npm  add @usenavii/react
+pnpm add @usenavii/react
+yarn add @usenavii/react
+bun  add @usenavii/react
+```
+
+React `>=17` is a peer dep. `@usenavii/core` is auto-installed.
+
+## Usage
+
+```tsx
+import { Navii } from '@usenavii/react';
+
+<Navii
+  seed={user.id}
+  size={64}
+  title={user.name}
+  animated
+/>
+```
+
+Renders as a memoized `<img src="data:image/svg+xml;...">` so the SVG is treated as opaque by the browser — no inline scripting surface.
+
+## Props
+
+| Prop         | Type                                                  | Default      |
+| ------------ | ----------------------------------------------------- | ------------ |
+| `seed`       | `string` — **required**                               | —            |
+| `size`       | `number` (px)                                         | `96`         |
+| `paletteId`  | known palette id (e.g. `'mint'`)                      | seed-derived |
+| `background` | `'none' \| 'solid' \| 'ring'` or `{ color }`          | seed-derived |
+| `tileBg`     | CSS color or `'auto'` (palette accent)                | none         |
+| `title`      | accessible label                                      | none         |
+| `animated`   | `boolean` — idle float / blink / sway / twinkle       | `false`      |
+| `alt`        | image alt text (falls back to `title`)                | `''`         |
+| `className`  | passed through to `<img>`                             | —            |
+| `style`      | passed through to `<img>`                             | —            |
+
+## The seed: read this once
+
+Same seed always produces the same avatar — that's the contract.
+
+| Pass                       | Result                                                  |
+| -------------------------- | ------------------------------------------------------- |
+| `user.id` / UUID           | ✅ Best. Stable and globally unique.                    |
+| `user.email`               | ✅ Good. Stable, unique per user.                       |
+| `user.name` alone          | ⚠️ Names collide. Two "Alice"s get the same avatar.    |
+| `${name}-${createdAt}`     | ✅ Fine fallback if no ID exists. Bake at signup.       |
+| `Date.now()` at render     | ❌ **Don't.** Breaks determinism — changes on reload.   |
+
+Need a helper that picks the right field automatically?
+
+```ts
+import { seed } from '@usenavii/core';
+
+const s = seed({ id: user.id, email: user.email, name: user.name });
+<Navii seed={s} />
+```
+
+## Example use cases
+
+### Profile card
+
+```tsx
+function UserCard({ user }) {
+  return (
+    <div className="user-card">
+      <Navii seed={user.id} size={64} title={user.name} />
+      <div>
+        <strong>{user.name}</strong>
+        <span>{user.email}</span>
+      </div>
+    </div>
+  );
+}
+```
+
+### Team list
+
+```tsx
+{team.map(u => (
+  <Navii key={u.id} seed={u.id} size={48} title={u.name} />
+))}
+```
+
+### Photo fallback
+
+```tsx
+<img
+  src={user.photoUrl}
+  onError={(e) => { e.currentTarget.src = `https://navii-api.uxderrick.com/avatar/${encodeURIComponent(user.id)}`; }}
+/>
+```
+
+Or render `<Navii>` directly when `photoUrl` is null — no fetch needed, deterministic.
+
+## Determinism guarantee
+
+Same seed + same options → byte-identical SVG. Memoized on `seed + size + paletteId + background + tileBg + title + animated`. Re-renders with same props don't re-run the engine.
+
+## License
+
+MIT. See [LICENSE](https://github.com/uxderrick/navii/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usenavii/react",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React binding for Navii deterministic avatars — <Navii seed=\"...\" />.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@usenavii/core": "^0.2.0"
+    "@usenavii/core": "^0.3.0"
   },
   "peerDependencies": {
     "react": ">=17"