@jjlmoya/utils-home 1.1.0

package/src/tool/solarCalculator/i18n/es.ts

@@ -0,0 +1,176 @@
+import type { WithContext, FAQPage, HowTo, SoftwareApplication } from 'schema-dts';
+import type { ToolLocaleContent } from '../../../types';
+import type { SolarCalculatorUI } from '../ui';
+
+const slug = 'calculadora-solar';
+const title = 'Calculadora de Inclinación de Paneles Solares';
+const description =
+  'Calcula el ángulo óptimo de inclinación para tus paneles solares según tu latitud geográfica. Obtén los valores para instalación fija y ajustes estacionales.';
+
+const faqData = [
+  {
+    question: '¿Qué pasa si mi tejado no tiene la inclinación perfecta?',
+    answer:
+      'No es un problema grave. Las pérdidas por desviaciones pequeñas (5-10°) son menores al 3% de la producción anual. Es más importante evitar sombras parciales que obsesionarse con el ángulo exacto.',
+  },
+  {
+    question: '¿El ángulo óptimo es el mismo en todo el mundo?',
+    answer:
+      'No. Depende directamente de tu latitud. Un usuario en Madrid (~40°N) tiene un ángulo óptimo distinto a uno en Noruega (~60°N) o en Argentina (~34°S).',
+  },
+  {
+    question: '¿Hacia dónde deben mirar los paneles?',
+    answer:
+      'En el Hemisferio Norte, siempre hacia el Sur (azimut 180°). En el Hemisferio Sur, hacia el Norte. Una orientación Este-Oeste puede causar pérdidas del 15-20% respecto al óptimo.',
+  },
+  {
+    question: '¿Sirve también para colectores de agua caliente solar?',
+    answer:
+      'Sí. Las fórmulas de inclinación son las mismas para colectores térmicos y para paneles fotovoltaicos, ya que ambos dependen del mismo principio geométrico.',
+  },
+];
+
+const howToData = [
+  {
+    name: 'Introduce tu latitud',
+    text: 'Escribe la latitud de tu ubicación en grados decimales, o usa el botón de geolocalización para detectarla automáticamente.',
+  },
+  {
+    name: 'Consulta el ángulo óptimo',
+    text: 'El ángulo óptimo anual es el valor principal para instalaciones fijas. Úsalo como referencia al programar tu instalador.',
+  },
+  {
+    name: 'Ajusta por estación (opcional)',
+    text: 'Si tu soporte lo permite, usa los ángulos de invierno y verano para maximizar la producción en cada estación.',
+  },
+  {
+    name: 'Verifica la orientación',
+    text: 'Comprueba el indicador de hemisferio: tus paneles deben apuntar al Sur si estás en el Hemisferio Norte, y al Norte si estás en el Sur.',
+  },
+];
+
+const faqSchema: WithContext<FAQPage> = {
+  '@context': 'https://schema.org',
+  '@type': 'FAQPage',
+  mainEntity: faqData.map((item) => ({
+    '@type': 'Question',
+    name: item.question,
+    acceptedAnswer: { '@type': 'Answer', text: item.answer },
+  })),
+};
+
+const howToSchema: WithContext<HowTo> = {
+  '@context': 'https://schema.org',
+  '@type': 'HowTo',
+  name: title,
+  description,
+  step: howToData.map((step) => ({
+    '@type': 'HowToStep',
+    name: step.name,
+    text: step.text,
+  })),
+};
+
+const appSchema: WithContext<SoftwareApplication> = {
+  '@context': 'https://schema.org',
+  '@type': 'SoftwareApplication',
+  name: title,
+  description,
+  applicationCategory: 'UtilityApplication',
+  operatingSystem: 'All',
+  offers: { '@type': 'Offer', price: '0', priceCurrency: 'EUR' },
+  inLanguage: 'es',
+};
+
+export const content: ToolLocaleContent<SolarCalculatorUI> = {
+  slug,
+  title,
+  description,
+  faqTitle: 'Preguntas Frecuentes',
+  faq: faqData,
+  bibliographyTitle: 'Bibliografía',
+  bibliography: [
+    { name: 'NREL PVWatts Calculator', url: 'https://pvwatts.nrel.gov/' },
+    { name: 'PVGIS — European Commission Solar Tool', url: 'https://re.jrc.ec.europa.eu/pvgis/' },
+    { name: 'SEIA — Solar Energy Industry Research Data', url: 'https://www.seia.org/solar-industry-research-data' },
+  ],
+  howTo: howToData,
+  schemas: [faqSchema, howToSchema, appSchema],
+  seo: [
+    {
+      type: 'title',
+      text: 'La Ciencia de la Inclinación Solar',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'La diferencia entre una factura eléctrica de cero euros y una inversión que no rinde está, literalmente, en los ángulos. La <strong>radiación solar</strong> no es uniforme: es un flujo dinámico que cambia con la hora, el día y la estación. Comprender la geometría celeste es el primer paso para convertir tu tejado en una central eléctrica de alto rendimiento.',
+    },
+    {
+      type: 'stats',
+      items: [
+        { value: 'Lat × 0.87', label: 'Fórmula General', icon: 'mdi:angle-acute' },
+        { value: 'Lat × 0.76 + 3.1', label: 'Latitudes 25°–50°', icon: 'mdi:map-marker' },
+        { value: '± 15°', label: 'Ajuste Estacional', icon: 'mdi:calendar-sync' },
+      ],
+      columns: 3,
+    },
+    {
+      type: 'comparative',
+      items: [
+        {
+          title: 'El Principio de Perpendicularidad',
+          description: 'Un panel solar funciona como una red que atrapa fotones. Es máximamente efectiva cuando se enfrenta a 90° respecto a los rayos solares. Cualquier desviación reduce la superficie efectiva de captación.',
+          icon: 'mdi:solar-panel',
+          points: ['Maximiza la superficie efectiva de captación', 'Base de todos los cálculos de inclinación'],
+        },
+        {
+          title: 'La Importancia de la Latitud',
+          description: 'Tu ubicación en el globo dicta la altura máxima del sol. Cuanto más lejos del ecuador, más bajo viaja el sol y más vertical debe ser el panel para interceptarlo.',
+          icon: 'mdi:earth',
+          points: ['A mayor latitud, mayor inclinación necesaria', 'El ecuador requiere paneles casi planos'],
+        },
+      ],
+      columns: 2,
+    },
+    {
+      type: 'title',
+      text: 'Estrategias Estacionales',
+      level: 3,
+    },
+    {
+      type: 'paragraph',
+      html: '<strong>Verano:</strong> El sol alcanza su cenit. Los paneles deben estar casi planos, restando ~15° a tu latitud. Aprovecha los días largos y la radiación directa intensa. <strong>Invierno:</strong> El sol viaja bajo, cerca del horizonte. Inclina más los paneles sumando ~15° a tu latitud. La mayor inclinación también ayuda a que la nieve se deslice sin tapar las células.',
+    },
+    {
+      type: 'diagnostic',
+      variant: 'info',
+      title: '¿Instalación Fija o Ajuste Estacional?',
+      icon: 'mdi:wrench',
+      badge: 'Consejo Pro',
+      html: '<p><strong>Fija (estándar):</strong> Configura al ángulo óptimo anual. Menor mantenimiento y mayor resistencia al viento, con una pérdida de apenas el 5-10% frente al seguimiento solar. <strong>Ajuste estacional (pro):</strong> Modifica el ángulo 2-4 veces al año para ganar hasta un +15% de rendimiento en los meses de invierno.</p>',
+    },
+    {
+      type: 'summary',
+      title: 'Claves para una Instalación Eficiente',
+      items: [
+        'El ángulo óptimo anual es tu referencia principal para instalaciones fijas.',
+        'Las pérdidas por desviaciones de ±5° son menores al 3% de la producción anual.',
+        'Prioriza evitar sombras parciales sobre buscar el ángulo exacto.',
+        'En el Hemisferio Norte, orienta siempre los paneles hacia el Sur.',
+        'Un ajuste estacional de 2-4 veces al año puede mejorar el rendimiento invernal en un +15%.',
+      ],
+    },
+  ],
+  ui: {
+    labelLatitude: 'Latitud Geográfica',
+    btnLocate: 'Detectar mi ubicación',
+    labelOptimal: 'Ángulo Óptimo Anual',
+    labelEfficiency: 'Eficiencia Máxima',
+    labelWinter: 'Invierno',
+    labelSummer: 'Verano',
+    hemisphereNorth: 'Hemisferio Norte — Orientar al SUR',
+    hemisphereSouth: 'Hemisferio Sur — Orientar al NORTE',
+    geoNotAvailable: 'Geolocalización no disponible en este navegador.',
+  },
+};

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

@@ -0,0 +1,176 @@
+import type { WithContext, FAQPage, HowTo, SoftwareApplication } from 'schema-dts';
+import type { ToolLocaleContent } from '../../../types';
+import type { SolarCalculatorUI } from '../ui';
+
+const slug = 'calculateur-solaire';
+const title = "Calculateur d'Inclinaison de Panneaux Solaires";
+const description =
+  "Calculez l'angle d'inclinaison optimal pour vos panneaux solaires en fonction de votre latitude géographique. Obtenez les valeurs pour une installation fixe et les ajustements saisonniers.";
+
+const faqData = [
+  {
+    question: "Que se passe-t-il si mon toit n'a pas l'inclinaison parfaite ?",
+    answer:
+      "Ce n'est pas un problème majeur. Les pertes dues à de petits écarts (5-10°) représentent moins de 3 % de la production annuelle. Éviter les ombrages partiels est bien plus important que d'obtenir l'angle exact.",
+  },
+  {
+    question: "L'angle optimal est-il le même partout dans le monde ?",
+    answer:
+      "Non. Il dépend directement de votre latitude. Un utilisateur à Madrid (~40°N) a un angle optimal différent de celui en Norvège (~60°N) ou en Argentine (~34°S).",
+  },
+  {
+    question: 'Dans quelle direction mes panneaux doivent-ils être orientés ?',
+    answer:
+      "Dans l'hémisphère nord, toujours vers le Sud (azimut 180°). Dans l'hémisphère sud, vers le Nord. Une orientation Est-Ouest peut entraîner des pertes de 15 à 20 % par rapport à l'optimum.",
+  },
+  {
+    question: "Cela fonctionne-t-il aussi pour les chauffe-eaux solaires ?",
+    answer:
+      "Oui. Les formules d'inclinaison sont identiques pour les capteurs thermiques et les panneaux photovoltaïques, car les deux reposent sur le même principe géométrique.",
+  },
+];
+
+const howToData = [
+  {
+    name: 'Entrez votre latitude',
+    text: 'Saisissez votre latitude en degrés décimaux, ou utilisez le bouton de géolocalisation pour la détecter automatiquement.',
+  },
+  {
+    name: "Consultez l'angle optimal",
+    text: "L'angle optimal annuel est la valeur principale pour les installations fixes. Utilisez-le comme référence lors de la programmation avec votre installateur.",
+  },
+  {
+    name: 'Ajustez par saison (facultatif)',
+    text: "Si votre support le permet, utilisez les angles d'hiver et d'été pour maximiser la production à chaque saison.",
+  },
+  {
+    name: "Vérifiez l'orientation",
+    text: "Consultez l'indicateur d'hémisphère : vos panneaux doivent être orientés vers le Sud si vous êtes dans l'hémisphère nord, et vers le Nord dans l'hémisphère sud.",
+  },
+];
+
+const faqSchema: WithContext<FAQPage> = {
+  '@context': 'https://schema.org',
+  '@type': 'FAQPage',
+  mainEntity: faqData.map((item) => ({
+    '@type': 'Question',
+    name: item.question,
+    acceptedAnswer: { '@type': 'Answer', text: item.answer },
+  })),
+};
+
+const howToSchema: WithContext<HowTo> = {
+  '@context': 'https://schema.org',
+  '@type': 'HowTo',
+  name: title,
+  description,
+  step: howToData.map((step) => ({
+    '@type': 'HowToStep',
+    name: step.name,
+    text: step.text,
+  })),
+};
+
+const appSchema: WithContext<SoftwareApplication> = {
+  '@context': 'https://schema.org',
+  '@type': 'SoftwareApplication',
+  name: title,
+  description,
+  applicationCategory: 'UtilityApplication',
+  operatingSystem: 'All',
+  offers: { '@type': 'Offer', price: '0', priceCurrency: 'EUR' },
+  inLanguage: 'fr',
+};
+
+export const content: ToolLocaleContent<SolarCalculatorUI> = {
+  slug,
+  title,
+  description,
+  faqTitle: 'Questions Fréquentes',
+  faq: faqData,
+  bibliographyTitle: 'Bibliographie',
+  bibliography: [
+    { name: 'NREL PVWatts Calculator', url: 'https://pvwatts.nrel.gov/' },
+    { name: 'PVGIS — Outil Solaire de la Commission Européenne', url: 'https://re.jrc.ec.europa.eu/pvgis/' },
+    { name: "SEIA — Données de Recherche sur l'Énergie Solaire", url: 'https://www.seia.org/solar-industry-research-data' },
+  ],
+  howTo: howToData,
+  schemas: [faqSchema, howToSchema, appSchema],
+  seo: [
+    {
+      type: 'title',
+      text: "La Science de l'Inclinaison Solaire",
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: "La différence entre une facture d'électricité nulle et un investissement qui ne porte pas ses fruits se mesure, littéralement, en degrés. Le <strong>rayonnement solaire</strong> n'est pas uniforme : c'est un flux dynamique qui varie selon l'heure, le jour et la saison. Comprendre la géométrie céleste est la première étape pour transformer votre toit en centrale électrique haute performance.",
+    },
+    {
+      type: 'stats',
+      items: [
+        { value: 'Lat × 0.87', label: 'Formule Générale', icon: 'mdi:angle-acute' },
+        { value: 'Lat × 0.76 + 3.1', label: 'Latitudes 25°–50°', icon: 'mdi:map-marker' },
+        { value: '± 15°', label: 'Ajustement Saisonnier', icon: 'mdi:calendar-sync' },
+      ],
+      columns: 3,
+    },
+    {
+      type: 'comparative',
+      items: [
+        {
+          title: 'Le Principe de Perpendicularité',
+          description: "Un panneau solaire fonctionne comme un filet qui capture des photons. Il est le plus efficace lorsqu'il fait face au flux à 90° par rapport aux rayons solaires. Tout écart réduit la surface de captation effective.",
+          icon: 'mdi:solar-panel',
+          points: ['Maximise la surface de captation effective', 'Base de tous les calculs d\'inclinaison'],
+        },
+        {
+          title: "L'Importance de la Latitude",
+          description: "Votre position sur le globe détermine la hauteur maximale du soleil. Plus vous êtes éloigné de l'équateur, plus le soleil voyage bas et plus le panneau doit être incliné pour l'intercepter.",
+          icon: 'mdi:earth',
+          points: ['Plus la latitude est élevée, plus l\'inclinaison est nécessaire', "Près de l'équateur, les panneaux sont presque plats"],
+        },
+      ],
+      columns: 2,
+    },
+    {
+      type: 'title',
+      text: 'Stratégies Saisonnières',
+      level: 3,
+    },
+    {
+      type: 'paragraph',
+      html: "<strong>Été :</strong> Le soleil atteint son zénith. Les panneaux doivent être presque plats — soustrayez ~15° à votre latitude. Profitez des longues journées et d'un rayonnement direct intense. <strong>Hiver :</strong> Le soleil voyage bas près de l'horizon. Inclinez davantage les panneaux en ajoutant ~15° à votre latitude. Une inclinaison plus forte aide aussi la neige à glisser sans bloquer les cellules.",
+    },
+    {
+      type: 'diagnostic',
+      variant: 'info',
+      title: 'Installation Fixe ou Ajustement Saisonnier ?',
+      icon: 'mdi:wrench',
+      badge: 'Conseil Pro',
+      html: "<p><strong>Fixe (standard) :</strong> Réglez à l'angle optimal annuel. Moins d'entretien et meilleure résistance au vent, avec seulement 5-10 % de perte par rapport au suivi solaire. <strong>Ajustement saisonnier (pro) :</strong> Modifiez l'angle 2-4 fois par an pour gagner jusqu'à +15 % de performance pendant les mois d'hiver.</p>",
+    },
+    {
+      type: 'summary',
+      title: "Clés pour une Installation Efficace",
+      items: [
+        "L'angle optimal annuel est votre référence principale pour les installations fixes.",
+        'Les pertes dues à des écarts de ±5° représentent moins de 3 % de la production annuelle.',
+        "Privilégiez l'évitement des ombrages partiels plutôt que la recherche de l'angle exact.",
+        "Dans l'hémisphère nord, orientez toujours les panneaux vers le Sud.",
+        "Un ajustement saisonnier 2-4 fois par an peut améliorer les performances hivernales de +15 %.",
+      ],
+    },
+  ],
+  ui: {
+    labelLatitude: 'Latitude Géographique',
+    btnLocate: 'Détecter ma position',
+    labelOptimal: 'Angle Optimal Annuel',
+    labelEfficiency: 'Efficacité Maximale',
+    labelWinter: 'Hiver',
+    labelSummer: 'Été',
+    hemisphereNorth: 'Hémisphère Nord — Orienter vers le SUD',
+    hemisphereSouth: 'Hémisphère Sud — Orienter vers le NORD',
+    geoNotAvailable: "La géolocalisation n'est pas disponible dans ce navigateur.",
+  },
+};

package/src/tool/solarCalculator/index.ts

@@ -0,0 +1,34 @@
+import type { HomeToolEntry, ToolLocaleContent, ToolDefinition } from '../../types';
+import SolarCalculatorComponent from './component.astro';
+import SolarCalculatorSEO from './seo.astro';
+import SolarCalculatorBibliography from './bibliography.astro';
+
+import type { SolarCalculatorUI } from './ui';
+
+export type SolarCalculatorLocaleContent = ToolLocaleContent<SolarCalculatorUI>;
+
+import { content as es } from './i18n/es';
+import { content as en } from './i18n/en';
+import { content as fr } from './i18n/fr';
+
+export const solarCalculator: HomeToolEntry<SolarCalculatorUI> = {
+  id: 'solar-calculator',
+  icons: {
+    bg: 'mdi:solar-panel',
+    fg: 'mdi:weather-sunny',
+  },
+  i18n: {
+    es: async () => es,
+    en: async () => en,
+    fr: async () => fr,
+  },
+};
+
+export { SolarCalculatorComponent, SolarCalculatorSEO, SolarCalculatorBibliography };
+
+export const SOLAR_CALCULATOR_TOOL: ToolDefinition = {
+  entry: solarCalculator,
+  Component: SolarCalculatorComponent,
+  SEOComponent: SolarCalculatorSEO,
+  BibliographyComponent: SolarCalculatorBibliography,
+};

package/src/tool/solarCalculator/logic.ts

@@ -0,0 +1,31 @@
+export interface TiltResult {
+  optimal: number;
+  winter: number;
+  summer: number;
+  isNorth: boolean;
+}
+
+export function toRad(deg: number): number {
+  return (deg * Math.PI) / 180;
+}
+
+export function calculateTilt(lat: number): TiltResult {
+  const absLat = Math.abs(lat);
+
+  let optimal = absLat * 0.87;
+  if (absLat > 25 && absLat < 50) {
+    optimal = absLat * 0.76 + 3.1;
+  }
+
+  const winter = absLat * 0.9 + 29;
+  const summer = absLat * 0.9 - 23.5;
+
+  const clamp = (n: number) => Math.min(Math.max(n, 0), 90);
+
+  return {
+    optimal: parseFloat(clamp(optimal).toFixed(1)),
+    winter: parseFloat(clamp(winter).toFixed(1)),
+    summer: parseFloat(clamp(summer).toFixed(1)),
+    isNorth: lat >= 0,
+  };
+}

package/src/tool/solarCalculator/seo.astro

@@ -0,0 +1,14 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { solarCalculator } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'es' } = Astro.props;
+const content = await solarCalculator.i18n[locale]?.();
+if (!content) return null;
+---
+<SEORenderer content={{ locale: locale as string, sections: content.seo }} />

package/src/tool/solarCalculator/ui.ts

@@ -0,0 +1,11 @@
+export interface SolarCalculatorUI extends Record<string, string> {
+  labelLatitude: string;
+  btnLocate: string;
+  labelOptimal: string;
+  labelEfficiency: string;
+  labelWinter: string;
+  labelSummer: string;
+  hemisphereNorth: string;
+  hemisphereSouth: string;
+  geoNotAvailable: string;
+}

package/src/tool/tariffComparator/bibliography.astro

@@ -0,0 +1,14 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { tariffComparator } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'es' } = Astro.props;
+const content = await tariffComparator.i18n[locale]?.();
+---
+
+{content && <SharedBibliography links={content.bibliography} />}