mochikao 0.1.2 → 0.2.0

package/README.fr.md

@@ -2,6 +2,8 @@
 
 [English](README.md) · **Français**
 
+[Site](https://mochikao.alexvolkihar.ovh) · [npm](https://www.npmjs.com/package/mochikao) · [GitHub](https://github.com/Alexvolkihar/mochikao)
+
 Un visage pour chaque nom. `mochikao` transforme n'importe quelle chaîne (pseudo, e-mail, id) en un petit personnage SVG. Le même nom donne toujours le même mochikao.
 
 ![Page d'accueil de mochikao : un nom tapé, l'avatar généré et le choix d'expression](docs/home.png)
@@ -130,6 +132,28 @@ mochikao({ name: 'alex', family: produce, shape: 'lemon' });
 
 Choisir une famille ne change que la forme : yeux, bouche, accessoire et réglages restent ceux du nom. Là où les options arrivent en texte (attributs HTML, URL, CLI), on déclare les familles disponibles une fois : `defineMochikao({ families: [animals] })` puis `<mochikao-avatar family="animals">`, ou `parseParams(nom, params, [animals, produce])`. L'API et la CLI fournies acceptent les deux.
 
+**Mélanger des familles.** `mix()` combine plusieurs familles : le nom choisit alors parmi toutes leurs formes, chacune avec la même chance.
+
+```ts
+import { mochikao, blobs, mix } from 'mochikao';
+
+mochikao({ name: 'alex', family: mix(blobs, animals) });            // blobs + animaux
+mochikao({ name: 'alex', family: mix(animals, produce) });          // animaux + fruits & légumes
+mochikao({ name: 'alex', family: mix(blobs, animals, produce) });   // tout
+```
+
+| Mode | `family=` | Formes |
+| --- | --- | --- |
+| Blobs (défaut) | `blob` | 10 |
+| Animaux | `animals` | 6 |
+| Fruits & légumes | `produce` | 6 |
+| Blobs + animaux | `animals+blob` | 16 |
+| Blobs + fruits & légumes | `blob+produce` | 16 |
+| Animaux + fruits & légumes | `animals+produce` | 12 |
+| Tout | `all` (ou `animals+blob+produce`) | 22 |
+
+Dans les URL, attributs HTML et la CLI, on joint les noms avec `+` (`?family=blob+animals`) ; `all` prend toutes les familles déclarées plus les blobs. L'ordre n'a pas d'importance, et un mélange des mêmes familles donne toujours le même avatar pour un nom.
+
 Une famille, c'est un objet `ShapeFamily` (`name`, `shapes`, `silhouette`, et en option `decorate` et `hue`) : `src/families/` montre comment en écrire une.
 
 ### Transition entre expressions
@@ -157,6 +181,8 @@ Mêmes attributs que les options ; `gaze` fait suivre le pointeur aux yeux.
 GET /api/<nom>.svg?size=&bg=&hue=&tone=&color=&expression=&animate=&family=&shape=&eyes=&mouth=&extra=
 ```
 
+Instance hébergée : `https://mochikao.alexvolkihar.ovh/api/<nom>.svg`. À essayer dans l'[éditeur](https://mochikao.alexvolkihar.ovh/editor.html).
+
 Réponse `image/svg+xml` avec `Cache-Control: immutable` (même entrée → même sortie). Les paramètres invalides sont ignorés. Le handler (`api/handler.ts`) est une simple fonction `(req, res)` de `node:http`, à brancher où tu veux.
 
 ### CLI

package/README.md

@@ -2,6 +2,8 @@
 
 **English** · [Français](README.fr.md)
 
+[Website](https://mochikao.alexvolkihar.ovh) · [npm](https://www.npmjs.com/package/mochikao) · [GitHub](https://github.com/Alexvolkihar/mochikao)
+
 A face for every name. `mochikao` turns any string (username, email, ID) into a little SVG character. The same name always gives the same mochikao.
 
 ![mochikao home page: a typed name, the generated avatar and the expression picker](docs/home.png)
@@ -130,6 +132,28 @@ mochikao({ name: 'alex', family: produce, shape: 'lemon' });
 
 Picking a family only changes the shape: eyes, mouth, accessory and settings still come from the name. Where options arrive as text (HTML attributes, URLs, CLI), declare the available families once: `defineMochikao({ families: [animals] })` then `<mochikao-avatar family="animals">`, or `parseParams(name, params, [animals, produce])`. The bundled API and CLI accept both.
 
+**Mixing families.** `mix()` combines several families: the name then picks among all their shapes, each shape equally likely.
+
+```ts
+import { mochikao, blobs, mix } from 'mochikao';
+
+mochikao({ name: 'alex', family: mix(blobs, animals) });            // blobs + animals
+mochikao({ name: 'alex', family: mix(animals, produce) });          // animals + fruits & veggies
+mochikao({ name: 'alex', family: mix(blobs, animals, produce) });   // everything
+```
+
+| Mode | `family=` | Shapes |
+| --- | --- | --- |
+| Blobs (default) | `blob` | 10 |
+| Animals | `animals` | 6 |
+| Fruits & veggies | `produce` | 6 |
+| Blobs + animals | `animals+blob` | 16 |
+| Blobs + fruits & veggies | `blob+produce` | 16 |
+| Animals + fruits & veggies | `animals+produce` | 12 |
+| Everything | `all` (or `animals+blob+produce`) | 22 |
+
+In URLs, HTML attributes and the CLI, join names with `+` (`?family=blob+animals`); `all` takes every family you declared plus the blobs. The order doesn't matter, and a mix with the same families always gives the same avatar for a given name.
+
 A family is a `ShapeFamily` object (`name`, `shapes`, `silhouette`, and optionally `decorate` and `hue`): `src/families/` shows how to write one.
 
 ### Transitions between expressions
@@ -157,6 +181,8 @@ Same attributes as the options; `gaze` makes the eyes follow the pointer.
 GET /api/<name>.svg?size=&bg=&hue=&tone=&color=&expression=&animate=&family=&shape=&eyes=&mouth=&extra=
 ```
 
+Hosted instance: `https://mochikao.alexvolkihar.ovh/api/<name>.svg`. Try it in the [editor](https://mochikao.alexvolkihar.ovh/editor.html).
+
 Responds with `image/svg+xml` and `Cache-Control: immutable` (same input → same output). Invalid parameters are ignored. The handler (`api/handler.ts`) is a plain `node:http` `(req, res)` function you can mount anywhere.
 
 ### CLI

package/dist/bin/mochikao.js

@@ -14,7 +14,7 @@ const USAGE = `usage : mochikao <nom> [options]
   --tone <0-1>           luminosité
   --expression <e>       idle | happy | sad | mad | love | shy | sick | thinking
   --animate <a>          none | hover | always
-  --family <f>           blob | animals | produce
+  --family <f>           blob | animals | produce | all, ou un mélange : blob+animals, animals+produce...
   --color <c>            pastel | pale | mid | deep | bright | ink
   --shape --eyes --mouth --extra   épingle un trait
   --info                 affiche les traits au lieu du SVG`;

package/dist/src/family.d.ts

@@ -49,3 +49,16 @@ export interface ShapeFamily<S extends string = string> {
     hue?(shape: S): number | undefined;
 }
 export declare function isFamily(value: unknown): value is ShapeFamily;
+/**
+ * Combine plusieurs familles en une : le nom choisit parmi toutes leurs formes.
+ *
+ *   mix(blobs, animals)            // blobs et animaux
+ *   mix(blobs, animals, produce)   // tout
+ *
+ * Chaque forme a la même chance d'être tirée, donc une famille pèse selon son
+ * nombre de formes. L'ordre des arguments ne compte pas : les familles sont
+ * triées par nom (le résultat s'appelle `animals+blob`), ce qui fixe la liste
+ * des formes et donc quel avatar sort pour quel nom. Si deux familles ont une
+ * forme du même nom, la première (dans l'ordre trié) l'emporte.
+ */
+export declare function mix(...families: ShapeFamily[]): ShapeFamily;

package/dist/src/family.js

@@ -3,3 +3,36 @@ export function isFamily(value) {
     return typeof f === 'object' && f !== null && typeof f.name === 'string' &&
         Array.isArray(f.shapes) && f.shapes.length > 0 && typeof f.silhouette === 'function';
 }
+/**
+ * Combine plusieurs familles en une : le nom choisit parmi toutes leurs formes.
+ *
+ *   mix(blobs, animals)            // blobs et animaux
+ *   mix(blobs, animals, produce)   // tout
+ *
+ * Chaque forme a la même chance d'être tirée, donc une famille pèse selon son
+ * nombre de formes. L'ordre des arguments ne compte pas : les familles sont
+ * triées par nom (le résultat s'appelle `animals+blob`), ce qui fixe la liste
+ * des formes et donc quel avatar sort pour quel nom. Si deux familles ont une
+ * forme du même nom, la première (dans l'ordre trié) l'emporte.
+ */
+export function mix(...families) {
+    const unique = [...new Map(families.filter(isFamily).map((f) => [f.name, f])).values()]
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    if (unique.length === 0)
+        throw new TypeError('mix() attend au moins une famille');
+    if (unique.length === 1)
+        return unique[0];
+    const owner = new Map();
+    for (const f of unique)
+        for (const s of f.shapes)
+            if (!owner.has(s))
+                owner.set(s, f);
+    const of = (shape) => owner.get(shape) ?? unique[0];
+    return {
+        name: unique.map((f) => f.name).join('+'),
+        shapes: [...owner.keys()],
+        silhouette: (shape, traits) => of(shape).silhouette(shape, traits),
+        decorate: (shape, body, colors, eyeY) => of(shape).decorate?.(shape, body, colors, eyeY) ?? {},
+        hue: (shape) => of(shape).hue?.(shape),
+    };
+}

package/dist/src/index.d.ts

@@ -3,7 +3,7 @@ import { type ShapeFamily } from './family.ts';
 import { type Animation, type Background, type ColorPreset, type Expression, type ExtraName, type EyesName, type MouthName, type Traits } from './traits.ts';
 export * from './traits.ts';
 export { blobs } from './shape.ts';
-export { isFamily } from './family.ts';
+export { isFamily, mix } from './family.ts';
 export type { Decoration, ShapeDef, ShapeFamily } from './family.ts';
 export { palette, contrast, hslToRgb } from './color.ts';
 export type { Palette } from './color.ts';

package/dist/src/index.js

@@ -6,7 +6,7 @@ import { blobs, buildBody, superellipsePath } from "./shape.js";
 import { ANIMATIONS, BACKGROUNDS, COLORS, EXPRESSIONS, EXTRAS, EYES, MOUTHS, deriveTraits, pick, positionOf, } from "./traits.js";
 export * from "./traits.js";
 export { blobs } from "./shape.js";
-export { isFamily } from "./family.js";
+export { isFamily, mix } from "./family.js";
 export { palette, contrast, hslToRgb } from "./color.js";
 /** Ce que le nom donne, sans dessiner. */
 export function resolve(options) {

package/dist/src/params.d.ts

@@ -1,5 +1,5 @@
 import type { MochikaoOptions } from './index.ts';
-import type { ShapeFamily } from './family.ts';
+import { type ShapeFamily } from './family.ts';
 type Source = {
     get(key: string): string | null | undefined;
 };
@@ -8,6 +8,8 @@ type Source = {
  * Les valeurs invalides sont ignorées plutôt que de faire échouer le rendu.
  * `families` liste les familles qu'on accepte de désigner par leur nom
  * (`?family=animals`) ; sans elles, seuls les blobs sont disponibles.
+ * Plusieurs familles se combinent avec « + » (`?family=blob+animals`), et
+ * `family=all` prend toutes celles qu'on fournit.
  */
 export declare function parseParams(name: string, src: Source, families?: readonly ShapeFamily[]): MochikaoOptions;
 /**

package/dist/src/params.js

@@ -1,3 +1,4 @@
+import { mix } from "./family.js";
 import { blobs } from "./shape.js";
 import { ANIMATIONS, BACKGROUNDS, COLORS, CONTINUOUS_AXES, EXPRESSIONS, EXTRAS, EYES, MOUTHS } from "./traits.js";
 const oneOf = (list, v) => v != null && list.includes(v) ? v : undefined;
@@ -7,11 +8,27 @@ const num = (v, min, max) => {
     const n = Number(v);
     return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : undefined;
 };
+/**
+ * `animals`, `blob`, ou un mode combiné : `blob+animals`, `animals+produce`...
+ * `all` prend les blobs et toutes les familles fournies. Les noms inconnus
+ * sont ignorés ; sans aucun nom valide, on n'a pas de famille.
+ */
+function findFamily(value, families) {
+    if (!value)
+        return undefined;
+    const known = [blobs, ...families];
+    if (value === 'all')
+        return mix(...known);
+    const found = value.split(/[+ ]/).map((n) => known.find((f) => f.name === n)).filter((f) => f !== undefined);
+    return found.length ? mix(...found) : undefined;
+}
 /**
  * Options depuis des paramètres texte (query string, attributs HTML, flags CLI).
  * Les valeurs invalides sont ignorées plutôt que de faire échouer le rendu.
  * `families` liste les familles qu'on accepte de désigner par leur nom
  * (`?family=animals`) ; sans elles, seuls les blobs sont disponibles.
+ * Plusieurs familles se combinent avec « + » (`?family=blob+animals`), et
+ * `family=all` prend toutes celles qu'on fournit.
  */
 export function parseParams(name, src, families = []) {
     const options = { name };
@@ -26,7 +43,7 @@ export function parseParams(name, src, families = []) {
     set('expression', oneOf(EXPRESSIONS, src.get('expression')));
     set('animate', oneOf(ANIMATIONS, src.get('animate')));
     // `family` désigne une famille par son nom, parmi celles qu'on nous a confiées.
-    const family = families.find((fam) => fam.name === src.get('family'));
+    const family = findFamily(src.get('family'), families);
     set('family', family);
     set('shape', oneOf((family ?? blobs).shapes, src.get('shape')));
     set('eyes', oneOf(EYES, src.get('eyes')));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mochikao",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Deterministic avatars: any string becomes a cute, unique SVG character. Zero dependencies, React / Vue / Svelte / Solid / web component.",
   "keywords": [
     "avatar",
@@ -22,7 +22,7 @@
     "type": "git",
     "url": "git+https://github.com/Alexvolkihar/mochikao.git"
   },
-  "homepage": "https://github.com/Alexvolkihar/mochikao#readme",
+  "homepage": "https://mochikao.alexvolkihar.ovh",
   "bugs": {
     "url": "https://github.com/Alexvolkihar/mochikao/issues"
   },