@jjlmoya/utils-developer 1.2.0

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

@@ -0,0 +1,168 @@
+import type { WithContext, FAQPage, HowToThing, SoftwareApplication } from 'schema-dts';
+import type { ToolLocaleContent } from '../../../types';
+import type { CssSpecificityCalculatorUI } from '../ui';
+
+const slug = 'calculateur-specificite-css';
+const title = 'Calculateur de Spécificité CSS en Ligne. Visualiseur de Poids';
+const description =
+  'Calculez la spécificité et le poids exact de n\'importe quel sélecteur CSS. Outil visuel pour comprendre quelle règle CSS gagne la cascade et éviter l\'utilisation de !important.';
+
+const faqData = [
+  {
+    question: 'Qu\'est-ce que la spécificité CSS ?',
+    answer:
+      'La spécificité est l\'algorithme que les navigateurs utilisent pour décider quelle règle CSS s\'applique à un élément quand plusieurs règles sont en compétition. Elle est représentée par un score à trois colonnes (A, B, C) indiquant les IDs, les classes/attributs/pseudo-classes et les éléments/pseudo-éléments.',
+  },
+  {
+    question: 'Une classe peut-elle jamais battre un ID en spécificité ?',
+    answer:
+      'Pas directement. Un ID (1,0,0) bat toujours n\'importe quel nombre de classes (0,N,0) car la spécificité n\'a pas de retenue entre les colonnes. Cent classes (0,100,0) ne battront jamais un seul ID (1,0,0).',
+  },
+  {
+    question: 'Que se passe-t-il quand deux sélecteurs ont la même spécificité ?',
+    answer:
+      'Quand deux sélecteurs ont exactement le même poids, celui déclaré en dernier dans le fichier CSS gagne. C\'est ce qu\'on appelle l\'ordre naturel de la cascade. Cette calculatrice vous avertit visuellement quand une égalité se produit.',
+  },
+  {
+    question: 'Pourquoi l\'utilisation de !important est-elle considérée comme mauvaise pratique ?',
+    answer:
+      'La directive !important brise la cascade CSS naturelle en forçant une déclaration sur toute autre règle. Cela crée des conflits difficiles à déboguer dans les grands projets. Des méthodologies comme BEM préconisent de garder une spécificité plate pour éviter d\'avoir besoin de !important.',
+  },
+];
+
+const howToData = [
+  {
+    name: 'Saisissez le premier sélecteur',
+    text: 'Tapez le Sélecteur A dans le champ texte de gauche, par exemple : #header .nav-item > a. Les compteurs d\'IDs, Classes et Éléments se mettront à jour instantanément.',
+  },
+  {
+    name: 'Saisissez le deuxième sélecteur',
+    text: 'Tapez le Sélecteur B dans le champ texte de droite, par exemple : ul li.active a:hover. Observez comment les poids changent en temps réel.',
+  },
+  {
+    name: 'Lisez le résultat',
+    text: 'La calculatrice mettra en évidence le bloc du sélecteur gagnant avec une bannière verte. En cas d\'égalité, un message apparaîtra expliquant l\'ordre de cascade comme critère de départage.',
+  },
+];
+
+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<HowToThing> = {
+  '@context': 'https://schema.org',
+  '@type': 'HowTo',
+  name: title,
+  description,
+  step: howToData.map((step, i) => ({
+    '@type': 'HowToStep',
+    position: i + 1,
+    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',
+};
+
+const ui: CssSpecificityCalculatorUI = {
+  labelA: 'Sélecteur A',
+  labelB: 'Sélecteur B',
+  placeholderA: 'ex. #header .nav-item > a',
+  placeholderB: 'ex. ul li.active a:hover',
+  cardIds: 'IDs',
+  cardClasses: 'Classes / Pseudos',
+  cardElements: 'Éléments',
+  bannerWinner: 'Ce sélecteur gagne !',
+  msgTie: 'Les deux sélecteurs ont le même poids. S\'ils sont en compétition pour le même élément, celui écrit en <strong>dernier</strong> dans le CSS gagne.',
+};
+
+export const content: ToolLocaleContent<CssSpecificityCalculatorUI> = {
+  slug,
+  title,
+  description,
+  ui,
+  faqTitle: 'Questions Fréquentes',
+  faq: faqData,
+  bibliographyTitle: 'Références et Documentation',
+  bibliography: [
+    {
+      name: 'MDN Web Docs: Spécificité CSS',
+      url: 'https://developer.mozilla.org/fr/docs/Web/CSS/Specificity',
+    },
+    {
+      name: 'W3C: Selectors Level 3 - Spécificité',
+      url: 'https://www.w3.org/TR/selectors-3/#specificity',
+    },
+  ],
+  howTo: howToData,
+  schemas: [faqSchema, howToSchema, appSchema],
+  seo: [
+    {
+      type: 'title',
+      text: 'Qu\'est-ce que la Spécificité CSS ?',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'La spécificité CSS est l\'algorithme par lequel les navigateurs décident quelles valeurs de propriétés appliquer à un élément particulier. C\'est essentiellement un score mathématique qui indique au navigateur "à quel point" une règle est spécifique.',
+    },
+    {
+      type: 'paragraph',
+      html: 'Si deux règles ont des niveaux de spécificité différents, celle avec le poids le plus élevé gagnera, quel que soit l\'ordre dans lequel elles ont été écrites. Si les deux ont le même poids, la dernière déclarée dans le code source gagne.',
+    },
+    {
+      type: 'title',
+      text: 'Comment calculer la Spécificité CSS',
+      level: 3,
+    },
+    {
+      type: 'paragraph',
+      html: 'La spécificité est calculée sur trois catégories formant un poids à trois colonnes, exprimé comme <strong>(A, B, C)</strong> :',
+    },
+    {
+      type: 'list',
+      items: [
+        '<strong>Colonne A (IDs) :</strong> Compte le nombre d\'identifiants uniques. Exemple : <code>#header</code> compte comme 1 dans la colonne A.',
+        '<strong>Colonne B (Classes, Attributs et Pseudo-classes) :</strong> Compte toutes les classes (<code>.button</code>), attributs (<code>[type="text"]</code>) et pseudo-classes (<code>:hover</code>).',
+        '<strong>Colonne C (Éléments et Pseudo-éléments) :</strong> Compte tous les éléments HTML (<code>div</code>, <code>h1</code>) et pseudo-éléments (<code>::before</code>).',
+      ],
+    },
+    {
+      type: 'title',
+      text: 'La règle d\'or: pas de report numérique',
+      level: 3,
+    },
+    {
+      type: 'tip',
+      html: 'Une règle avec la spécificité (0,50,0) ne sera <strong>jamais</strong> plus spécifique qu\'une règle (1,0,0). <strong>Un seul ID bat infiniment de classes.</strong> Les colonnes ne se déversent jamais les unes dans les autres.',
+    },
+    {
+      type: 'title',
+      text: 'Le problème de !important et l\'architecture BEM',
+      level: 3,
+    },
+    {
+      type: 'paragraph',
+      html: 'La directive <code>!important</code> est une exception aux règles de spécificité. Quand elle est utilisée, cette déclaration écrase automatiquement toute autre. Elle est considérée comme une mauvaise pratique car elle détruit la cascade naturelle.',
+    },
+    {
+      type: 'paragraph',
+      html: 'Pour éviter les guerres de spécificité dans les grands projets, des méthodologies comme <strong>BEM</strong> préconisent d\'utiliser uniquement des sélecteurs de classe à un seul niveau de profondeur, maintenant artificiellement la spécificité plate à (0,1,0).',
+    },
+  ],
+};

package/src/tool/cssSpecificityCalculator/index.ts

@@ -0,0 +1,34 @@
+import type { DeveloperToolEntry, ToolLocaleContent, ToolDefinition } from '../../types';
+import CssSpecificityCalculatorComponent from './component.astro';
+import CssSpecificityCalculatorSEO from './seo.astro';
+import CssSpecificityCalculatorBibliography from './bibliography.astro';
+
+import type { CssSpecificityCalculatorUI } from './ui';
+
+export type CssSpecificityCalculatorLocaleContent = ToolLocaleContent<CssSpecificityCalculatorUI>;
+
+import { content as es } from './i18n/es';
+import { content as en } from './i18n/en';
+import { content as fr } from './i18n/fr';
+
+export const cssSpecificityCalculator: DeveloperToolEntry<CssSpecificityCalculatorUI> = {
+  id: 'css-specificity-calculator',
+  icons: {
+    bg: 'mdi:scale-balance',
+    fg: 'mdi:language-css3',
+  },
+  i18n: {
+    es: async () => es,
+    en: async () => en,
+    fr: async () => fr,
+  },
+};
+
+export { CssSpecificityCalculatorComponent, CssSpecificityCalculatorSEO, CssSpecificityCalculatorBibliography };
+
+export const CSS_SPECIFICITY_CALCULATOR_TOOL: ToolDefinition = {
+  entry: cssSpecificityCalculator,
+  Component: CssSpecificityCalculatorComponent,
+  SEOComponent: CssSpecificityCalculatorSEO,
+  BibliographyComponent: CssSpecificityCalculatorBibliography,
+};

package/src/tool/cssSpecificityCalculator/logic.ts

@@ -0,0 +1,100 @@
+export type Specificity = [number, number, number];
+
+export function compareSpecificity(a: Specificity, b: Specificity): number {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return 1;
+    if (a[i] < b[i]) return -1;
+  }
+  return 0;
+}
+
+function getFunctionalPseudoContent(s: string, start: number): { content: string; endIndex: number } | null {
+  let level = 1;
+  let i = start;
+  while (i < s.length && level > 0) {
+    if (s[i] === '(') level++;
+    else if (s[i] === ')') level--;
+    i++;
+  }
+  if (level === 0) return { content: s.substring(start, i - 1), endIndex: i };
+  return null;
+}
+
+function splitByComma(s: string): string[] {
+  const result: string[] = [];
+  let current = '';
+  let level = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') level++;
+    else if (s[i] === ')') level--;
+    if (s[i] === ',' && level === 0) {
+      result.push(current.trim());
+      current = '';
+    } else {
+      current += s[i];
+    }
+  }
+  if (current.trim()) result.push(current.trim());
+  return result;
+}
+
+function addSubSpecificity(content: string, total: Specificity): void {
+  const subs = splitByComma(content);
+  let max: Specificity = [0, 0, 0];
+  for (const sub of subs) {
+    const s = calculateSpecificity(sub);
+    if (compareSpecificity(s, max) > 0) max = s;
+  }
+  total[0] += max[0];
+  total[1] += max[1];
+  total[2] += max[2];
+}
+
+function processPseudo(s: string, pseudo: string, total: Specificity): string | null {
+  const idx = s.indexOf(pseudo);
+  if (idx === -1) return null;
+  const res = getFunctionalPseudoContent(s, idx + pseudo.length);
+  if (!res) return null;
+  if (pseudo !== ':where(') addSubSpecificity(res.content, total);
+  return s.substring(0, idx) + ' ' + s.substring(res.endIndex);
+}
+
+function applyFunctionalPseudos(s: string, total: Specificity): string {
+  const pseudos = [':is(', ':not(', ':where(', ':has('];
+  let found = true;
+  while (found) {
+    found = false;
+    for (const pseudo of pseudos) {
+      const result = processPseudo(s, pseudo, total);
+      if (result !== null) { s = result; found = true; }
+    }
+  }
+  return s;
+}
+
+function countMatches(s: string, regex: RegExp): number {
+  return (s.match(regex) ?? []).length;
+}
+
+function countParts(s: string): number {
+  const parts = s.replace(/[*+>~,]/g, ' ').trim().split(/\s+/);
+  return parts[0] ? parts.length : 0;
+}
+
+export function calculateSpecificity(selector: string): Specificity {
+  if (!selector.trim()) return [0, 0, 0];
+  const total: Specificity = [0, 0, 0];
+  let s = applyFunctionalPseudos(selector, total);
+  total[0] += countMatches(s, /#[\w-]+/g);
+  s = s.replace(/#[\w-]+/g, ' ');
+  total[1] += countMatches(s, /\.[\w-]+/g);
+  s = s.replace(/\.[\w-]+/g, ' ');
+  total[1] += countMatches(s, /\[[^\]]+\]/g);
+  s = s.replace(/\[[^\]]+\]/g, ' ');
+  total[2] += countMatches(s, /::[\w-]+/g);
+  s = s.replace(/::[\w-]+/g, ' ');
+  total[1] += countMatches(s, /:[\w-]+(\([^)]*\))?/g);
+  s = s.replace(/:[\w-]+(\([^)]*\))?/g, ' ');
+  total[2] += countParts(s);
+  return total;
+}

package/src/tool/cssSpecificityCalculator/seo.astro

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

package/src/tool/cssSpecificityCalculator/ui-controller.ts

@@ -0,0 +1,57 @@
+import { calculateSpecificity, compareSpecificity } from './logic';
+
+type SpecDisp = { ids: HTMLElement; cls: HTMLElement; els: HTMLElement };
+type SpecBlocks = { a: HTMLElement; b: HTMLElement; tie: HTMLElement };
+
+function renderSpec(disp: SpecDisp, spec: [number, number, number]): void {
+  disp.ids.textContent = spec[0].toString();
+  disp.cls.textContent = spec[1].toString();
+  disp.els.textContent = spec[2].toString();
+}
+
+function setBlockWinner(block: HTMLElement, isWinner: boolean): void {
+  block.style.borderColor = isWinner ? 'var(--spec-success)' : '';
+  block.style.paddingTop = isWinner ? '2.5rem' : '';
+  block.style.boxShadow = isWinner ? '0 0 0 2px var(--spec-success)' : '';
+  const banner = block.querySelector('.spec-winner-banner') as HTMLElement | null;
+  if (banner) banner.style.transform = isWinner ? 'translateY(0)' : 'translateY(-100%)';
+}
+
+function updateResult(ins: [HTMLInputElement, HTMLInputElement], disps: [SpecDisp, SpecDisp], blocks: SpecBlocks): void {
+  const vA = ins[0].value.trim();
+  const vB = ins[1].value.trim();
+  const specA = calculateSpecificity(vA);
+  const specB = calculateSpecificity(vB);
+  renderSpec(disps[0], specA);
+  renderSpec(disps[1], specB);
+  const win = compareSpecificity(specA, specB);
+  setBlockWinner(blocks.a, win === 1 && !!vA);
+  setBlockWinner(blocks.b, win === -1 && !!vB);
+  const isTie = win === 0 && !!vA && !!vB;
+  blocks.tie.style.opacity = isTie ? '1' : '0';
+  blocks.tie.style.transform = isTie ? 'translateY(0)' : 'translateY(6px)';
+}
+
+export function setupCalculator(): void {
+  const inputA = document.getElementById('spec-input-a') as HTMLInputElement | null;
+  const inputB = document.getElementById('spec-input-b') as HTMLInputElement | null;
+  const blockA = document.getElementById('spec-block-a');
+  const blockB = document.getElementById('spec-block-b');
+  const tieMsg = document.getElementById('spec-tie-msg');
+  if (!inputA || !inputB || !blockA || !blockB || !tieMsg) return;
+  const dispA: SpecDisp = {
+    ids: document.getElementById('spec-res-a-ids')!,
+    cls: document.getElementById('spec-res-a-cls')!,
+    els: document.getElementById('spec-res-a-els')!,
+  };
+  const dispB: SpecDisp = {
+    ids: document.getElementById('spec-res-b-ids')!,
+    cls: document.getElementById('spec-res-b-cls')!,
+    els: document.getElementById('spec-res-b-els')!,
+  };
+  const blocks: SpecBlocks = { a: blockA, b: blockB, tie: tieMsg };
+  const ins: [HTMLInputElement, HTMLInputElement] = [inputA, inputB];
+  const compare = () => updateResult(ins, [dispA, dispB], blocks);
+  inputA.addEventListener('input', compare);
+  inputB.addEventListener('input', compare);
+}

package/src/tool/cssSpecificityCalculator/ui.ts

@@ -0,0 +1,11 @@
+export interface CssSpecificityCalculatorUI extends Record<string, string> {
+  labelA: string;
+  labelB: string;
+  placeholderA: string;
+  placeholderB: string;
+  cardIds: string;
+  cardClasses: string;
+  cardElements: string;
+  bannerWinner: string;
+  msgTie: string;
+}

package/src/tool/cssToInlineConverter/bibliography.astro

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