mochikao 0.2.0 → 0.2.1

package/README.fr.md

@@ -16,7 +16,7 @@ Un visage pour chaque nom. `mochikao` transforme n'importe quelle chaîne (pseud
 - 5 yeux, 6 bouches, 11 accessoires (joues, taches, antenne, pousse, reflet, lunettes, lunettes noires, nœud, couronne, chapeau de fête).
 - **10 axes continus** réglables (taille et proportion du corps, carrure, ondulation, taille/écart/inclinaison des yeux, regard x/y, taille de la bouche) et 6 préréglages de couleur.
 - **8 expressions** : `idle`, `happy`, `sad`, `mad`, `love`, `shy`, `sick`, `thinking`.
-- **Contraste visage/corps ≥ 4.5:1** pour toute teinte et tout ton (vérifié par les tests).
+- **Contraste visage/corps ≥ 4.5:1** pour toute teinte et tout ton (vérifié par les tests). L'avatar contre *ta* page n'est pas garanti : voir [Contraste](docs/editor.fr.md#8-contraste--ce-qui-est-garanti-et-ce-qui-ne-lest-pas).
 - **Animations CSS** (respiration, clignement, coups d'œil), **transition animée entre expressions** et **regard qui suit le pointeur**.
 - Fonction, composants **React / Vue / Svelte / Solid**, web component, API HTTP et CLI.
 
@@ -156,6 +156,69 @@ Dans les URL, attributs HTML et la CLI, on joint les noms avec `+` (`?family=blo
 
 Une famille, c'est un objet `ShapeFamily` (`name`, `shapes`, `silhouette`, et en option `decorate` et `hue`) : `src/families/` montre comment en écrire une.
 
+### Laisser les utilisateurs personnaliser leur avatar
+
+mochikao n'embarque pas de sélecteur : un avatar, c'est `nom + options épinglées`. Ton appli enregistre ce que l'utilisateur a touché et le repasse. Ne stocke que les clés épinglées ; supprimer une clé remet ce trait en « auto » (tiré du nom).
+
+```tsx
+import { useState } from 'react';
+import { Mochikao } from 'mochikao/react';
+import { EYES, MOUTHS, EXTRAS, resolve, mix, blobs, type MochikaoOptions } from 'mochikao';
+import { animals } from 'mochikao/animals';
+
+const family = mix(blobs, animals);               // les formes que tu proposes
+type Prefs = Omit<MochikaoOptions, 'name' | 'family'>;
+
+const CHOICES = { shape: family.shapes, eyes: EYES, mouth: MOUTHS, extra: EXTRAS } as const;
+
+export function AvatarEditor({ userId, saved, onSave }: {
+  userId: string;                                  // un id stable, pas un pseudo modifiable
+  saved: Prefs;                                    // lu en base
+  onSave: (prefs: Prefs) => void;
+}) {
+  const [prefs, setPrefs] = useState<Prefs>(saved);
+  const auto = resolve({ name: userId, family });  // ce que donne le nom quand rien n'est épinglé
+
+  // value === undefined remet le trait en « auto »
+  const pin = (key: keyof typeof CHOICES, value?: string) =>
+    setPrefs(({ [key]: _, ...rest }) => (value ? { ...rest, [key]: value } : rest));
+
+  return (
+    <div>
+      <Mochikao name={userId} family={family} size={128} {...prefs} />
+
+      {(Object.keys(CHOICES) as (keyof typeof CHOICES)[]).map((key) => (
+        <label key={key}>
+          {key}
+          <select value={prefs[key] ?? ''} onChange={(e) => pin(key, e.target.value || undefined)}>
+            <option value="">auto ({auto[key]})</option>
+            {CHOICES[key].map((v) => <option key={v}>{v}</option>)}
+          </select>
+        </label>
+      ))}
+
+      <label>
+        teinte
+        <input type="range" min={0} max={360} value={prefs.hue ?? auto.hue}
+               onChange={(e) => setPrefs({ ...prefs, hue: +e.target.value })} />
+      </label>
+
+      <button onClick={() => onSave(prefs)}>Enregistrer</button>
+      <button onClick={() => setPrefs({})}>Réinitialiser</button>
+    </div>
+  );
+}
+```
+
+Partout ailleurs dans l'appli, on l'affiche pareil : `<Mochikao name={user.id} family={family} {...user.avatarPrefs} />`.
+
+- **Stocker du texte** : `toParams(prefs).toString()` donne une chaîne compacte (`shape=frog&eyes=sleepy&hue=140`) et `parseParams(userId, new URLSearchParams(str), [animals])` la relit. Les valeurs invalides sont ignorées : c'est la bonne façon de valider ce qui vient du client.
+- **Même avatar ailleurs** : construis `/api/<id>.svg?family=animals+blob&<prefs>` pour les e-mails, les images OG ou les clients sans JS.
+- **Aperçus** : une tuile, c'est `mochikao({ name, family, ...prefs, eyes: 'wide' })`.
+- **Rester sobre** : plus on laisse épingler de traits, moins deux utilisateurs se distinguent.
+
+Le guide complet (modèle, pièges, référence sans framework, aperçus, validation côté serveur) est dans [docs/editor.fr.md](docs/editor.fr.md), avec aussi une version Vue 3. Un exemple Vue complet, proche de l'éditeur du site, est dans [examples/vue/AvatarEditor.vue](examples/vue/AvatarEditor.vue).
+
 ### Transition entre expressions
 
 En SVG en ligne (`animate`, `inline` ou `gaze`), changer `expression` déclenche une petite transition : les yeux clignent, la bouche se referme, le visage change pendant qu'ils sont fermés, puis tout se rouvre avec un rebond (~450 ms). Les composants et le web component le font tout seuls. Un `<img>` ne peut pas s'animer : en mode image, le changement est immédiat.
@@ -252,6 +315,44 @@ La CI (`.github/workflows/ci.yml`) vérifie types, tests et builds sur Node 22 e
 
 Une fois publié, le rendu des avatars est un contrat : voir Stabilité.
 
+## Crédit
+
+mochikao est sous licence MIT : tu l'utilises librement, la mention n'est pas obligatoire. Si tu l'embarques, une citation aide beaucoup, et j'aimerais voir où il atterrit :
+
+- **Dans ton appli** : une ligne en pied de page ou sur la page « à propos », par exemple `Avatars par <a href="https://mochikao.alexvolkihar.ovh">mochikao</a>`.
+- **Dans ton dépôt** : un lien vers <https://github.com/Alexvolkihar/mochikao> dans ton README (section crédits ou remerciements).
+- **Dis-le-moi** : [ouvre une issue](https://github.com/Alexvolkihar/mochikao/issues/new) avec un lien vers ton projet et j'envisagerai de le lister.
+
+### Badge
+
+Un petit badge SVG pour un README ou une page « à propos », en version **sombre** et **claire** (texte au-dessus de 4.5:1 dans les deux, et une bordure qui tient sur une page blanche ou sombre) :
+
+| Sombre | Clair |
+| --- | --- |
+| [![avatars by mochikao](https://mochikao.alexvolkihar.ovh/badge-dark.svg)](https://mochikao.alexvolkihar.ovh) | [![avatars by mochikao](https://mochikao.alexvolkihar.ovh/badge-light.svg)](https://mochikao.alexvolkihar.ovh) |
+| `badge-dark.svg` | `badge-light.svg` |
+
+```md
+[![avatars by mochikao](https://mochikao.alexvolkihar.ovh/badge-dark.svg)](https://mochikao.alexvolkihar.ovh)
+```
+
+```html
+<a href="https://mochikao.alexvolkihar.ovh"><img src="https://mochikao.alexvolkihar.ovh/badge-dark.svg" alt="avatars by mochikao" height="24"></a>
+```
+
+Pour suivre automatiquement le thème du lecteur (README GitHub et toute page qui gère `<picture>`) :
+
+```html
+<a href="https://mochikao.alexvolkihar.ovh">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://mochikao.alexvolkihar.ovh/badge-light.svg">
+    <img src="https://mochikao.alexvolkihar.ovh/badge-dark.svg" alt="avatars by mochikao" height="24">
+  </picture>
+</a>
+```
+
+`badge.svg` reste un alias de la version sombre. Les fichiers sont dans [`site/public/`](site/public/) si tu préfères en héberger une copie.
+
 ## Licence
 
 MIT

package/README.md

@@ -16,7 +16,7 @@ A face for every name. `mochikao` turns any string (username, email, ID) into a
 - 5 eyes, 6 mouths, 11 accessories (blush, freckles, antenna, sprout, shine, glasses, sunglasses, bow, crown, party hat).
 - **10 continuous axes** you can tune (body size and proportion, squareness, wobble, eye size/spacing/lean, gaze x/y, mouth size) and 6 color presets.
 - **8 expressions**: `idle`, `happy`, `sad`, `mad`, `love`, `shy`, `sick`, `thinking`.
-- **Face-to-body contrast ≥ 4.5:1** for every hue and tone (checked by the tests).
+- **Face-to-body contrast ≥ 4.5:1** for every hue and tone (checked by the tests). The avatar against *your* page is not guaranteed: see [Contrast](docs/editor.md#8-contrast-what-is-guaranteed-and-what-is-not).
 - **CSS animations** (breathing, blinking, glances), **animated transitions between expressions** and **eyes that follow the pointer**.
 - A function, **React / Vue / Svelte / Solid** components, a web component, an HTTP API and a CLI.
 
@@ -156,6 +156,69 @@ In URLs, HTML attributes and the CLI, join names with `+` (`?family=blob+animals
 
 A family is a `ShapeFamily` object (`name`, `shapes`, `silhouette`, and optionally `decorate` and `hue`): `src/families/` shows how to write one.
 
+### Letting users customize their avatar
+
+mochikao has no built-in picker: an avatar is `name + pinned options`, so your app stores what the user touched and passes it back. Store only the pinned keys; removing a key puts that trait back on "auto" (drawn from the name).
+
+```tsx
+import { useState } from 'react';
+import { Mochikao } from 'mochikao/react';
+import { EYES, MOUTHS, EXTRAS, resolve, mix, blobs, type MochikaoOptions } from 'mochikao';
+import { animals } from 'mochikao/animals';
+
+const family = mix(blobs, animals);               // the shapes you offer
+type Prefs = Omit<MochikaoOptions, 'name' | 'family'>;
+
+const CHOICES = { shape: family.shapes, eyes: EYES, mouth: MOUTHS, extra: EXTRAS } as const;
+
+export function AvatarEditor({ userId, saved, onSave }: {
+  userId: string;                                  // a stable ID, not a renamable pseudonym
+  saved: Prefs;                                    // loaded from your database
+  onSave: (prefs: Prefs) => void;
+}) {
+  const [prefs, setPrefs] = useState<Prefs>(saved);
+  const auto = resolve({ name: userId, family });  // what the name gives when nothing is pinned
+
+  // value === undefined puts the trait back to "auto"
+  const pin = (key: keyof typeof CHOICES, value?: string) =>
+    setPrefs(({ [key]: _, ...rest }) => (value ? { ...rest, [key]: value } : rest));
+
+  return (
+    <div>
+      <Mochikao name={userId} family={family} size={128} {...prefs} />
+
+      {(Object.keys(CHOICES) as (keyof typeof CHOICES)[]).map((key) => (
+        <label key={key}>
+          {key}
+          <select value={prefs[key] ?? ''} onChange={(e) => pin(key, e.target.value || undefined)}>
+            <option value="">auto ({auto[key]})</option>
+            {CHOICES[key].map((v) => <option key={v}>{v}</option>)}
+          </select>
+        </label>
+      ))}
+
+      <label>
+        hue
+        <input type="range" min={0} max={360} value={prefs.hue ?? auto.hue}
+               onChange={(e) => setPrefs({ ...prefs, hue: +e.target.value })} />
+      </label>
+
+      <button onClick={() => onSave(prefs)}>Save</button>
+      <button onClick={() => setPrefs({})}>Reset</button>
+    </div>
+  );
+}
+```
+
+Anywhere else in your app, display it the same way: `<Mochikao name={user.id} family={family} {...user.avatarPrefs} />`.
+
+- **Store text**: `toParams(prefs).toString()` gives a compact string (`shape=frog&eyes=sleepy&hue=140`) and `parseParams(userId, new URLSearchParams(str), [animals])` reads it back. Invalid values are ignored, which makes it the right way to validate what comes from the client.
+- **Same avatar elsewhere**: build `/api/<id>.svg?family=animals+blob&<prefs>` for emails, OG images or non-JS clients.
+- **Previews**: a tile is just `mochikao({ name, family, ...prefs, eyes: 'wide' })`.
+- **Keep it small**: the more traits you let people pin, the less two users differ.
+
+The full guide (model, pitfalls, a framework-free reference, previews, server-side validation) is in [docs/editor.md](docs/editor.md), with a Vue 3 version as well. A complete Vue example, close to the site's editor, is in [examples/vue/AvatarEditor.vue](examples/vue/AvatarEditor.vue).
+
 ### Transitions between expressions
 
 With inline SVG (`animate`, `inline` or `gaze`), changing `expression` plays a short transition: the eyes blink, the mouth closes, the face changes while they are shut, then everything reopens with a little bounce (~450 ms). The components and the web component do it on their own. An `<img>` cannot animate: in image mode the change is immediate.
@@ -252,6 +315,44 @@ CI (`.github/workflows/ci.yml`) checks types, tests and builds on Node 22 and 24
 
 Once published, the avatars' rendering is a contract: see Stability.
 
+## Credit
+
+mochikao is MIT: you can use it freely, credit is not required. If you ship it, though, a mention helps a lot, and I'd love to see where it ends up:
+
+- **In your app**: a line in the footer or the "about" page, such as `Avatars by <a href="https://mochikao.alexvolkihar.ovh">mochikao</a>`.
+- **In your repo**: a link to <https://github.com/Alexvolkihar/mochikao> in your README (credits or acknowledgements section).
+- **Tell me**: [open an issue](https://github.com/Alexvolkihar/mochikao/issues/new) with a link to your project and I'll consider listing it.
+
+### Badge
+
+A small SVG badge for a README or an "about" page, in a **dark** and a **light** version (text above 4.5:1 in both, and a border that holds on a white or a dark page):
+
+| Dark | Light |
+| --- | --- |
+| [![avatars by mochikao](https://mochikao.alexvolkihar.ovh/badge-dark.svg)](https://mochikao.alexvolkihar.ovh) | [![avatars by mochikao](https://mochikao.alexvolkihar.ovh/badge-light.svg)](https://mochikao.alexvolkihar.ovh) |
+| `badge-dark.svg` | `badge-light.svg` |
+
+```md
+[![avatars by mochikao](https://mochikao.alexvolkihar.ovh/badge-dark.svg)](https://mochikao.alexvolkihar.ovh)
+```
+
+```html
+<a href="https://mochikao.alexvolkihar.ovh"><img src="https://mochikao.alexvolkihar.ovh/badge-dark.svg" alt="avatars by mochikao" height="24"></a>
+```
+
+To follow the reader's theme automatically (GitHub READMEs and any page that supports `<picture>`):
+
+```html
+<a href="https://mochikao.alexvolkihar.ovh">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://mochikao.alexvolkihar.ovh/badge-light.svg">
+    <img src="https://mochikao.alexvolkihar.ovh/badge-dark.svg" alt="avatars by mochikao" height="24">
+  </picture>
+</a>
+```
+
+`badge.svg` is kept as an alias of the dark one. The files live in [`site/public/`](site/public/) if you prefer to host a copy.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mochikao",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Deterministic avatars: any string becomes a cute, unique SVG character. Zero dependencies, React / Vue / Svelte / Solid / web component.",
   "keywords": [
     "avatar",