@jjlmoya/utils-alcohol 1.1.0

package/src/tool/cocktailBalancer/i18n/fr.ts

@@ -0,0 +1,193 @@
+import type { WithContext, SoftwareApplication } from 'schema-dts';
+import type { CocktailBalancerUI, CocktailBalancerLocaleContent } from '../index';
+
+const slug = 'equilibre-cocktail';
+const title = 'Équilibreur de Cocktails - La Loi du Sour';
+const description = 'Calculez l\'équilibre parfait entre le sucré et l\'acide pour vos cocktails. Maîtrisez le nombre d\'or de la mixologie.';
+
+const ui: CocktailBalancerUI = {
+  title: 'Cocktail Balancer',
+  presetsBtn: 'Recettes',
+  saveBtn: 'Sauvegarder',
+  resetBtn: 'Reset',
+  emptyStateTitle: 'Votre Plan de Travail est Vide',
+  emptyStateDescription: 'Ajoutez des ingrédients pour analyser l\'équilibre de votre cocktail en temps réel.',
+  addBtn: 'Ajouter Ingrédient',
+  addMoreBtn: 'Ajouter un Autre Ingrédient',
+  flavorProfileTitle: 'Profil de Saveur',
+  volLabel: 'Volume',
+  sugarLabel: 'Sucre',
+  colorLabel: 'Couleur',
+  sourLawTitle: 'Loi du Sour',
+  acidDryLabel: 'Acide (Dry)',
+  balanceLabel: 'Équilibre',
+  sweetLabel: 'Sucré (Sweet)',
+  aiSuggestionTitle: 'Suggestion de l\'IA',
+  addIngredientTitle: 'Ajouter Ingrédient',
+  searchPlaceholder: 'Chercher rhum, citron, sirop...',
+  presetsTitle: 'Recettes & Presets',
+  savedSectionTitle: 'Mes Sauvegardes',
+  classicsSectionTitle: 'Classiques',
+  confirmDeleteTitle: 'Tout effacer ?',
+  confirmDeleteText: 'Cette action supprimera tous les ingrédients de votre plan de travail. Elle est irréversible.',
+  cancelBtn: 'Annuler',
+  deleteBtn: 'Effacer',
+  verdictSpiritSeco: 'Spiritueux / Sec',
+  verdictSoloDulce: 'Seulement Sucré (Old Fashioned)',
+  verdictMuyAcido: 'Trop Acide / Bone Dry',
+  verdictAcido: 'Acide / Tart',
+  verdictEquilibrado: 'Équilibré (Sour)',
+  verdictDulce: 'Sucré / Commercial',
+  verdictEmpalagoso: 'Écoeurant',
+  fixAddBitters: 'Manque d\'Amertume',
+  fixAddSugar: 'Trop Acide',
+  fixAddAcid: 'Trop Sucré'
+};
+
+const faqTitle = 'Foire Aux Questions';
+const bibliographyTitle = 'Bibliographie & Sources';
+
+const faq: CocktailBalancerLocaleContent['faq'] = [
+  {
+    question: "Qu'est-ce que la 'Loi du Sour' ?",
+    answer: "C'est le nombre d'or de la mixologie qui équilibre trois éléments : la base forte (spiritueux), l'acide (agrumes) et le sucré (sirops). Une recette classique suit généralement le ratio 2:1:1 (Fort:Acide:Sucré), bien que cela varie selon la force et la densité.",
+  },
+  {
+    question: "Comment la dilution affecte-t-elle l'équilibre du cocktail ?",
+    answer: "La glace ne fait pas que refroidir ; elle ajoute de l'eau (dilution) qui ouvre les arômes du spiritueux et adoucit les pics d'acidité et de douceur. Un cocktail équilibré dans le shaker peut se déséquilibrer s'il reste trop longtemps avec de la glace dans le verre.",
+  },
+  {
+    question: "Pourquoi mes cocktails maison n'ont-ils pas le même goût qu'au bar ?",
+    answer: "C'est généralement dû au manque d'équilibre entre le sucre et le pH de l'agrume. Les citrons varient en acidité selon la saison. Notre calculateur vous aide à ajuster la quantité exacte de sirop en fonction du volume de jus utilisé.",
+  },
+];
+
+const howTo: CocktailBalancerLocaleContent['howTo'] = [
+  {
+    name: "Sélectionner la base alcoolisée",
+    text: "Choisissez le spiritueux principal (Gin, Rhum, Whisky) dans notre base de données pour connaître son apport en corps et en alcool.",
+  },
+  {
+    name: "Entrer l'agent acide",
+    text: "Ajoutez le volume de jus de citron, citron vert ou pamplemousse. Le calculateur analysera l'impact du pH sur le mélange.",
+  },
+  {
+    name: "Ajuster le composant sucré",
+    text: "Entrez le type de sirop (simple, 2:1, agave) et observez l'indicateur d'équilibre bouger en temps réel.",
+  },
+];
+
+const bibliography: CocktailBalancerLocaleContent['bibliography'] = [
+  {
+    name: "Liquid Intelligence: The Art and Science of the Perfect Cocktail",
+    url: "http://www.cookingissues.com/index.html%3Fp=4587.html",
+  },
+  {
+    name: "The Bar Book: Elements of Cocktail Technique - Jeffrey Morgenthaler",
+    url: "https://jeffreymorgenthaler.com/the-bar-book/",
+  },
+  {
+    name: "Cocktail Balance - Difford's Guide",
+    url: "https://www.diffordsguide.com/encyclopedia/1066/cocktails/cocktail-balance",
+  },
+];
+
+const seo: CocktailBalancerLocaleContent['seo'] = [
+  {
+    type: 'title',
+    text: 'Ingénierie Moléculaire & Équilibre Liquide',
+    level: 2
+  },
+  {
+    type: 'paragraph',
+    html: 'Bienvenue dans le laboratoire numérique où l\'intuition rencontre les mathématiques. Cet outil n\'est pas un simple livre de recettes ; c\'est un <strong>simulateur physico-chimique avancé</strong> conçu pour déconstruire et analyser la structure moléculaire de vos cocktails en temps réel. Chaque goutte de citrus, chaque mesure de spiritueux, chaque gramme de sirop interagit selon des lois chimiques immuables qui déterminent si votre boisson sera un chef-d\'œuvre ou un échec décevant.'
+  },
+  {
+    type: 'stats',
+    items: [
+      { label: 'Citron Vert', value: '~6% Acide', icon: 'mdi:fruit-citrus' },
+      { label: 'Citron', value: '~6% Acide', icon: 'mdi:fruit-citrus' },
+      { label: 'Pamplemousse', value: '~1-2% Acide', icon: 'mdi:fruit-citrus' }
+    ],
+    columns: 3
+  },
+  {
+    type: 'card',
+    title: 'La Science de l\'Acide',
+    icon: 'mdi:fruit-citrus',
+    html: 'L\'acidité n\'est pas seulement une saveur ; c\'est la colonne vertébrale structurelle de tout cocktail équilibré. Sans la bonne acidité, une boisson devient plate, unidimensionnelle et oubliable. Notre algorithme distingue l\'acidité titrable d\'un citron vert persan par rapport à un citron Eureka, tenant compte des variations saisonnières du pH des agrumes qui peuvent décaler votre recette d\'un point entier d\'équilibre sur le palais.'
+  },
+  {
+    type: 'card',
+    title: 'Contrôle du Brix (Douceur)',
+    icon: 'mdi:spoon-sugar',
+    html: 'Le corps et la texture de votre cocktail dépendent entièrement du sucre dissous. Un Sirop Simple (1:1) se comporte très différemment d\'un Riche Sirop (2:1), du miel ou du nectar d\'agave. Chaque édulcorant a un degré Brix et une viscosité différents qui affectent la façon dont la boisson enrobe la langue. Notre calculateur calcule les grammes exacts de sucre dissous pour prédire la sensation en bouche finale.'
+  },
+  {
+    type: 'card',
+    title: 'Thermodynamique et Dilution',
+    icon: 'mdi:water-percent',
+    html: 'Un cocktail agité se dilue de 25 à 40 % selon la température de la glace, la technique et la durée. Cet ajout d\'eau n\'est pas un défaut ; c\'est un ingrédient essentiel qui ouvre les arômes et adoucit la sensation alcoolisée. Notre calculateur estime l\'ABV Final après dilution, permettant de concevoir des boissons avec la force et l\'équilibre voulus.'
+  },
+  {
+    type: 'title',
+    text: 'Au-delà du Ratio de Base',
+    level: 2
+  },
+  {
+    type: 'paragraph',
+    html: 'De nombreux bartenders apprennent la règle classique 2:1:1 (2 parts de spiritueux, 1 acide, 1 sucré) et la traitent comme une vérité universelle. Cependant, <strong>la chimie est bien plus nuancée</strong>. Un citron de Sicile contient une acidité différente d\'un citron vert du Mexique. Un triple sec comme le Cointreau se comporte radicalement différemment d\'un Curaçao bleu. La même recette peut être parfaitement équilibrée une semaine et brutalement acide la suivante, simplement en raison des variations saisonnières des fruits.'
+  },
+  {
+    type: 'paragraph',
+    html: 'Cet équilibreur brise ces barrières simplistes. En entrant vos ingrédients spécifiques, vous consultez une base de données vivante qui ajuste dynamiquement les vecteurs d\'acidité et de douceur pour offrir une carte sensorielle précise de votre création. Arrêtez de deviner et commencez à élaborer vos cocktails avec la même rigueur scientifique que les bartenders des établissements de classe mondiale.'
+  },
+  {
+    type: 'summary',
+    title: 'À qui s\'adresse cet outil ?',
+    items: [
+      'Bartenders Professionnels : Standardisez les recettes et créez des menus signature avec une cohérence reproductible.',
+      'Amateurs à la Maison : Arrêtez de deviner et comprenez pourquoi vos cocktails réussissent ou échouent.',
+      'Développeurs de Boissons : Prototypez rapidement de nouveaux concepts de saveurs avant les productions coûteuses.'
+    ]
+  },
+  {
+    type: 'diagnostic',
+    title: 'La Zone Dorée',
+    icon: 'mdi:star',
+    variant: 'success',
+    badge: 'Objectif',
+    html: 'C\'est l\'objectif ultime : un pH contrôlé où le sucre neutralise l\'agression de l\'acide sans masquer les huiles essentielles et les composés aromatiques du spiritueux de base. C\'est là que vivent les classiques immortels — le Daiquiri, la Margarita, le Sidecar — des boissons qui ont survécu des décennies parce qu\'elles obéissent aux lois fondamentales de la chimie des saveurs.'
+  },
+  {
+    type: 'tip',
+    title: 'Conseil Expert : Toujours Utiliser des Agrumes Frais',
+    html: 'Pressez toujours les agrumes au dernier moment. Le jus de citron et de citron vert s\'oxyde rapidement, perdant son acidité vive en 20 à 30 minutes après l\'extraction. Un cocktail réalisé avec un jus vraiment frais aura toujours une brillance et une vivacité en bouche qu\'aucun produit en bouteille ne peut reproduire.'
+  }
+];
+
+const schemas: CocktailBalancerLocaleContent['schemas'] = [
+  {
+    '@context': 'https://schema.org',
+    '@type': 'SoftwareApplication',
+    name: title,
+    description: description,
+    applicationCategory: 'UtilityApplication',
+    operatingSystem: 'Web',
+    offers: { '@type': 'Offer', price: '0', priceCurrency: 'EUR' },
+  } as WithContext<SoftwareApplication>,
+];
+
+export const content: CocktailBalancerLocaleContent = {
+  slug,
+  title,
+  description,
+  ui,
+  seo,
+  faqTitle,
+  faq,
+  bibliographyTitle,
+  bibliography,
+  howTo,
+  schemas,
+};

package/src/tool/cocktailBalancer/index.ts

@@ -0,0 +1,68 @@
+import type { AlcoholToolEntry, ToolLocaleContent, ToolDefinition } from '../../types';
+import CocktailBalancerCalculator from './component.astro';
+import CocktailBalancerSEO from './seo.astro';
+import CocktailBalancerBibliography from './bibliography.astro';
+
+export interface CocktailBalancerUI {
+  [key: string]: string;
+  title: string;
+  presetsBtn: string;
+  saveBtn: string;
+  resetBtn: string;
+  emptyStateTitle: string;
+  emptyStateDescription: string;
+  addBtn: string;
+  addMoreBtn: string;
+  flavorProfileTitle: string;
+  volLabel: string;
+  sugarLabel: string;
+  colorLabel: string;
+  sourLawTitle: string;
+  acidDryLabel: string;
+  balanceLabel: string;
+  sweetLabel: string;
+  aiSuggestionTitle: string;
+  addIngredientTitle: string;
+  searchPlaceholder: string;
+  presetsTitle: string;
+  savedSectionTitle: string;
+  classicsSectionTitle: string;
+  confirmDeleteTitle: string;
+  confirmDeleteText: string;
+  cancelBtn: string;
+  deleteBtn: string;
+  verdictSpiritSeco: string;
+  verdictSoloDulce: string;
+  verdictMuyAcido: string;
+  verdictAcido: string;
+  verdictEquilibrado: string;
+  verdictDulce: string;
+  verdictEmpalagoso: string;
+  fixAddBitters: string;
+  fixAddSugar: string;
+  fixAddAcid: string;
+}
+
+export type CocktailBalancerLocaleContent = ToolLocaleContent<CocktailBalancerUI>;
+
+export const cocktailBalancer: AlcoholToolEntry<CocktailBalancerUI> = {
+  id: 'cocktail-balancer',
+  icons: {
+    bg: 'mdi:glass-cocktail',
+    fg: 'mdi:fruit-citrus',
+  },
+  i18n: {
+    es: () => import('./i18n/es').then((m) => m.content),
+    en: () => import('./i18n/en').then((m) => m.content),
+    fr: () => import('./i18n/fr').then((m) => m.content),
+  },
+};
+
+export { CocktailBalancerCalculator, CocktailBalancerSEO, CocktailBalancerBibliography };
+
+export const COCKTAIL_BALANCER_TOOL: ToolDefinition = {
+  entry: cocktailBalancer as AlcoholToolEntry<Record<string, string>>,
+  Component: CocktailBalancerCalculator,
+  SEOComponent: CocktailBalancerSEO,
+  BibliographyComponent: CocktailBalancerBibliography,
+};

package/src/tool/cocktailBalancer/logic.ts

@@ -0,0 +1,118 @@
+import type { CocktailComponent, CocktailStats } from './domain/Ingredient';
+
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  const shorthandRegex = /^#?([a-f\d])([a-f\d])([a-f\d])$/i;
+  const fullHex = hex.replace(shorthandRegex, (_m, r: string, g: string, b: string) => r + r + g + g + b + b);
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(fullHex);
+
+  return result
+    ? {
+        r: parseInt(result[1] ?? '', 16),
+        g: parseInt(result[2] ?? '', 16),
+        b: parseInt(result[3] ?? '', 16),
+      }
+    : { r: 255, g: 255, b: 255 };
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  return '#' + ((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1);
+}
+
+function computeBalanceRatio(sugarGrams: number, acidGrams: number): number {
+  if (acidGrams > 0) return sugarGrams / acidGrams;
+  if (sugarGrams > 0) return 999;
+  return 0;
+}
+
+function accumulateComponents(components: CocktailComponent[]) {
+  let totalVol = 0, totalAlcoholVol = 0, totalSugarGrams = 0, totalAcidGrams = 0;
+  let weightedBitterness = 0, weightedComplexity = 0;
+  let weightedR = 0, weightedG = 0, weightedB = 0;
+
+  components.forEach((comp) => {
+    if (comp.volumeMl <= 0) return;
+    const vol = comp.volumeMl;
+    totalVol += vol;
+    totalAlcoholVol += vol * (comp.ingredient.abv / 100);
+    totalSugarGrams += vol * (comp.ingredient.sugar / 100);
+    totalAcidGrams += vol * (comp.ingredient.acid / 100);
+    weightedBitterness += vol * (comp.ingredient.bitterness || 0);
+    weightedComplexity += vol * (comp.ingredient.complexity || 0);
+    const rgb = hexToRgb(comp.ingredient.color || '#ffffff');
+    weightedR += vol * rgb.r;
+    weightedG += vol * rgb.g;
+    weightedB += vol * rgb.b;
+  });
+
+  return { totalVol, totalAlcoholVol, totalSugarGrams, totalAcidGrams, weightedBitterness, weightedComplexity, weightedR, weightedG, weightedB };
+}
+
+function emptyStats(): CocktailStats {
+  return {
+    totalVolumeMl: 0, finalAbv: 0, totalSugarGrams: 0, totalAcidGrams: 0,
+    sugarConcentration: 0, acidConcentration: 0, balanceRatio: 0,
+    bitternessIndex: 0, complexityIndex: 0, finalColor: '#ffffff',
+  };
+}
+
+export function calculateCocktail(components: CocktailComponent[]): CocktailStats {
+  const acc = accumulateComponents(components);
+  if (acc.totalVol === 0) return emptyStats();
+
+  const v = acc.totalVol;
+  return {
+    totalVolumeMl: v,
+    finalAbv: (acc.totalAlcoholVol / v) * 100,
+    totalSugarGrams: acc.totalSugarGrams,
+    totalAcidGrams: acc.totalAcidGrams,
+    sugarConcentration: (acc.totalSugarGrams / v) * 100,
+    acidConcentration: (acc.totalAcidGrams / v) * 100,
+    balanceRatio: computeBalanceRatio(acc.totalSugarGrams, acc.totalAcidGrams),
+    bitternessIndex: acc.weightedBitterness / v,
+    complexityIndex: acc.weightedComplexity / v,
+    finalColor: rgbToHex(Math.round(acc.weightedR / v), Math.round(acc.weightedG / v), Math.round(acc.weightedB / v)),
+  };
+}
+
+export function getBalanceVerdict(stats: CocktailStats): { labelKey: string; colorClass: string } {
+  const r = stats.balanceRatio;
+
+  if (stats.totalAcidGrams === 0 && stats.totalSugarGrams < 2) {
+    return { labelKey: 'verdictSpiritSeco', colorClass: 'text-indigo-400' };
+  }
+  if (stats.totalAcidGrams === 0) {
+    return { labelKey: 'verdictSoloDulce', colorClass: 'text-amber-400' };
+  }
+  if (r < 4) return { labelKey: 'verdictMuyAcido', colorClass: 'text-red-500' };
+  if (r < 6) return { labelKey: 'verdictAcido', colorClass: 'text-lime-400' };
+  if (r < 9) return { labelKey: 'verdictEquilibrado', colorClass: 'text-emerald-400' };
+  if (r < 12) return { labelKey: 'verdictDulce', colorClass: 'text-yellow-400' };
+  return { labelKey: 'verdictEmpalagoso', colorClass: 'text-red-500' };
+}
+
+function getSugarFix(stats: CocktailStats): { actionKey: string; amountValue: string } | null {
+  const TARGET_RATIO = 7.5;
+  const targetSugar = TARGET_RATIO * stats.totalAcidGrams;
+  const vol = ((targetSugar - stats.totalSugarGrams) * 100) / 61.5;
+  if (vol < 2.5) return null;
+  return { actionKey: 'fixAddSugar', amountValue: `+${Math.ceil(vol / 2.5) * 2.5}ml Jarabe` };
+}
+
+function getAcidFix(stats: CocktailStats): { actionKey: string; amountValue: string } | null {
+  const TARGET_RATIO = 7.5;
+  const targetAcid = stats.totalSugarGrams / TARGET_RATIO;
+  const vol = ((targetAcid - stats.totalAcidGrams) * 100) / 6.0;
+  if (vol < 2.5) return null;
+  return { actionKey: 'fixAddAcid', amountValue: `+${Math.ceil(vol / 2.5) * 2.5}ml Lima` };
+}
+
+export function getFixSuggestion(stats: CocktailStats): { actionKey: string; amountValue: string } | null {
+  if (stats.totalVolumeMl === 0) return null;
+  if (stats.totalAcidGrams === 0 && stats.totalSugarGrams < 2) return null;
+  if (stats.totalAcidGrams === 0) return { actionKey: 'fixAddBitters', amountValue: '+2 dashes Bitters' };
+
+  const currentRatio = stats.balanceRatio;
+  if (currentRatio >= 6.0 && currentRatio <= 9.0) return null;
+  if (currentRatio < 6.0) return getSugarFix(stats);
+  return getAcidFix(stats);
+}

package/src/tool/cocktailBalancer/seo.astro

@@ -0,0 +1,53 @@
+---
+import { 
+  SEOTitle, SEOTable, SEOTip, SEOCard, SEOStats,
+  SEOGlossary, SEOProsCons, SEOSummary, SEODiagnostic, SEOArticle
+} from '@jjlmoya/utils-shared';
+import { cocktailBalancer } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'es' } = Astro.props;
+const content = await cocktailBalancer.i18n[locale]?.();
+if (!content) return null;
+
+const { seo } = content;
+---
+
+<SEOArticle>
+  {seo.map((section: any) => {
+    switch (section.type) {
+      case 'summary':
+        return <SEOSummary title={section.title} items={section.items} />;
+      case 'title':
+        return <SEOTitle title={section.text} level={section.level || 2} />;
+      case 'paragraph':
+        return <p set:html={section.html} />;
+      case 'stats':
+        return <SEOStats stats={section.items} columns={section.columns} />;
+      case 'card':
+        return <SEOCard title={section.title} icon={section.icon}><Fragment set:html={section.html} /></SEOCard>;
+      case 'tip':
+        return <SEOTip title={section.title}><Fragment set:html={section.html} /></SEOTip>;
+      case 'table':
+        return (
+          <SEOTable headers={section.headers}>
+            {section.rows.map((row: string[]) => (
+              <tr>{row.map((cell: string) => <td set:html={cell} />)}</tr>
+            ))}
+          </SEOTable>
+        );
+      case 'proscons':
+        return <SEOProsCons title={section.title} items={section.items} />;
+      case 'diagnostic':
+        return <SEODiagnostic title={section.title} icon={section.icon} type={section.variant} badge={section.badge}><Fragment set:html={section.html} /></SEODiagnostic>;
+      case 'glossary':
+        return <SEOGlossary items={section.items} />;
+      default:
+        return null;
+    }
+  })}
+</SEOArticle>