@jjlmoya/utils-developer 1.2.0

package/src/pages/[locale]/[slug].astro

@@ -0,0 +1,146 @@
+---
+import PreviewLayout from "../../layouts/PreviewLayout.astro";
+import PreviewNavSidebar from "../../components/PreviewNavSidebar.astro";
+import { ALL_TOOLS } from "../../index";
+import {
+  UtilityHeader,
+  FAQSection,
+  Bibliography,
+  SEORenderer,
+} from "@jjlmoya/utils-shared";
+import type { KnownLocale, ToolLocaleContent } from "../../types";
+import type { UtilitySEOContent } from "@jjlmoya/utils-shared";
+
+export async function getStaticPaths() {
+  const paths = [];
+
+  for (const { entry, Component } of ALL_TOOLS) {
+    const localeEntries = Object.entries(entry.i18n) as [
+      KnownLocale,
+      () => Promise<ToolLocaleContent>,
+    ][];
+    const localeContents = await Promise.all(
+      localeEntries.map(async ([locale, loader]) => ({
+        locale,
+        content: await loader(),
+      })),
+    );
+
+    const localeUrls = Object.fromEntries(
+      localeContents.map(({ locale, content }) => [
+        locale,
+        `/${locale}/${content.slug}`,
+      ]),
+    ) as Partial<Record<KnownLocale, string>>;
+
+    for (const { locale, content } of localeContents) {
+      const allToolsNav = await Promise.all(
+        ALL_TOOLS.map(async ({ entry: navEntry }) => ({
+          id: navEntry.id,
+          title: (await navEntry.i18n[locale]!()).title,
+          href: `/${locale}/${(await navEntry.i18n[locale]!()).slug}`,
+          isActive: navEntry.id === entry.id,
+        })),
+      );
+      paths.push({
+        params: { locale, slug: content.slug },
+        props: { Component, locale, content, localeUrls, allToolsNav },
+      });
+    }
+  }
+
+  return paths;
+}
+
+type ToolComponent = (props: { ui: Record<string, string> }) => unknown;
+
+interface NavItem {
+  id: string;
+  title: string;
+  href: string;
+  isActive?: boolean;
+}
+
+interface Props {
+  Component: ToolComponent;
+  locale: KnownLocale;
+  content: ToolLocaleContent;
+  localeUrls: Partial<Record<KnownLocale, string>>;
+  allToolsNav: NavItem[];
+}
+
+const { Component, locale, content, localeUrls, allToolsNav } = Astro.props;
+
+const seoContent: UtilitySEOContent = { locale, sections: content.seo };
+
+const words = content.title.split(" ");
+const titleHighlight = words[0] || "";
+const titleBase = words.slice(1).join(" ") || "";
+---
+
+<PreviewLayout
+  title={content.title}
+  currentLocale={locale}
+  localeUrls={localeUrls}
+  hasSidebar={true}
+>
+  <PreviewNavSidebar
+    slot="sidebar"
+    categoryTitle="Tools"
+    tools={allToolsNav}
+  />
+  <Fragment slot="head">
+    {
+      content.schemas.map((schema: unknown) => (
+        <script
+          is:inline
+          type="application/ld+json"
+          set:html={JSON.stringify(schema)}
+        />
+      ))
+    }
+  </Fragment>
+
+  <div class="tool-page">
+    <UtilityHeader
+      titleHighlight={titleHighlight}
+      titleBase={titleBase}
+      description={content.description}
+    />
+
+    <section class="section-tool">
+      <Component ui={content.ui} />
+    </section>
+
+    <section class="section-seo">
+      <SEORenderer content={seoContent} />
+    </section>
+
+    <section class="section-faq">
+      <FAQSection items={content.faq} title={content.ui.faqTitle} inLanguage={locale} />
+    </section>
+
+    <section class="section-bibliography">
+      <Bibliography links={content.bibliography} title={content.ui.bibliographyTitle} />
+    </section>
+  </div>
+</PreviewLayout>
+
+<style>
+  .tool-page {
+    display: flex;
+    flex-direction: column;
+    gap: 2rem;
+  }
+  .section-tool {
+    max-width: 1200px;
+    margin: 0 auto;
+    width: 100%;
+  }
+  .section-seo,
+  .section-faq,
+  .section-bibliography {
+    padding-top: 2rem;
+    border-top: 1px solid var(--border-color);
+  }
+</style>

package/src/pages/[locale].astro

@@ -0,0 +1,251 @@
+---
+import PreviewLayout from '../layouts/PreviewLayout.astro';
+import PreviewNavSidebar from '../components/PreviewNavSidebar.astro';
+import { developerCategory, ALL_TOOLS } from '../index';
+import { Icon } from 'astro-icon/components';
+import type { KnownLocale, ToolLocaleContent } from '../types';
+
+export async function getStaticPaths() {
+  const locales = ['en', 'es', 'fr'] as KnownLocale[];
+  return locales.map(locale => ({ params: { locale } }));
+}
+
+const { locale: currentLocale } = Astro.params as { locale: KnownLocale };
+
+const categoryContent = await developerCategory.i18n[currentLocale]!();
+
+const tools = ALL_TOOLS || [];
+
+const toolsWithContent = tools.length > 0
+  ? await Promise.all(
+      tools.map(async ({ entry, Component }) => {
+        const languages = Object.keys(entry.i18n);
+        const localeEntries = await Promise.all(
+          languages.map(async (l) => {
+            const content = await entry.i18n[l as KnownLocale]!();
+            return [l, content];
+          })
+        );
+
+        const localeContents = Object.fromEntries(localeEntries) as Record<string, ToolLocaleContent<Record<string, string>>>;
+
+        const currentLocaleContent = localeContents[currentLocale] || localeContents['en'] || localeContents['es'];
+        const availableLocales: Record<string, string> = {};
+
+        for (const l of languages) {
+          const lCont = localeContents[l];
+          if (lCont) {
+            availableLocales[l] = `/${l}/${lCont.slug}`;
+          }
+        }
+
+        return { entry, Component, locale: currentLocaleContent, availableLocales };
+      })
+    )
+  : [];
+---
+
+<PreviewLayout
+  title={categoryContent.title}
+  currentLocale={currentLocale}
+  hasSidebar={true}
+>
+  <PreviewNavSidebar
+    slot="sidebar"
+    categoryTitle={categoryContent.title}
+    tools={toolsWithContent.map(({ entry, locale, availableLocales }) => {
+      const href = availableLocales[currentLocale] || (locale ? `/${currentLocale}/${locale.slug}` : '#');
+      return {
+        id: entry.id,
+        title: locale?.title || entry.id,
+        href: href,
+      };
+    })}
+  />
+  <div class="dashboard">
+    <header class="preview-header">
+      <span class="badge">preview · @jjlmoya/utils-template</span>
+      <h1>{categoryContent.title}</h1>
+      <p>{categoryContent.description}</p>
+    </header>
+
+    <div class="tool-list">
+      {toolsWithContent?.map(({ entry, locale, availableLocales }) => (
+        <article class="tool-card">
+          <a href={availableLocales?.[currentLocale] || (locale ? `/${currentLocale}/${locale.slug}` : '#')} class="tool-card-link">
+            <div class="tool-icons">
+               <div class="icon-wrapper bg">
+                  <Icon name={entry.icons.bg} />
+               </div>
+               <div class="icon-wrapper fg">
+                  <Icon name={entry.icons.fg} />
+               </div>
+            </div>
+            <div class="tool-card-content">
+              <h2 class="tool-title">{locale?.title}</h2>
+              <p class="tool-description">{locale?.description}</p>
+            </div>
+            <div class="tool-card-meta">
+              <span class="tool-id">{entry.id}</span>
+            </div>
+          </a>
+
+          {availableLocales && Object.keys(availableLocales).length > 1 && (
+            <div class="tool-locales">
+              {Object.entries(availableLocales).map(([l, url]) => (
+                <a href={url} class="locale-badge" title={`Ver en ${l.toUpperCase()}`} class:list={{ active: l === currentLocale }}>
+                  {l.toUpperCase()}
+                </a>
+              ))}
+            </div>
+          )}
+        </article>
+      ))}
+    </div>
+  </div>
+</PreviewLayout>
+
+<style>
+  .dashboard {
+    display: flex;
+    flex-direction: column;
+    gap: 5rem;
+  }
+  .preview-header {
+    text-align: center;
+    padding-bottom: 3rem;
+    border-bottom: 1px solid var(--border-color);
+  }
+  .badge {
+    display: inline-block;
+    padding: 0.25rem 0.75rem;
+    background: var(--accent);
+    border-radius: 99px;
+    font-size: 0.7rem;
+    font-weight: 800;
+    margin-bottom: 1.5rem;
+    color: var(--text-base);
+    letter-spacing: 0.05em;
+  }
+  h1 {
+    font-size: clamp(2rem, 6vw, 3.5rem);
+    font-weight: 900;
+    margin: 0 0 1rem;
+    background: linear-gradient(to bottom, var(--text-base), var(--text-muted));
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+  }
+  .preview-header p {
+    color: var(--text-muted);
+    font-size: 1.1rem;
+    margin: 0;
+  }
+  .tool-list {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
+    gap: 2rem;
+  }
+  .tool-card {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+  }
+  .tool-card-link {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    padding: 1.5rem;
+    background: var(--bg-surface);
+    border: 1px solid var(--border-color);
+    border-radius: 0.75rem;
+    text-decoration: none;
+    transition: all 0.2s ease;
+  }
+  .tool-card-link:hover {
+    border-color: var(--accent);
+    background: rgba(244, 63, 94, 0.05);
+    transform: translateY(-2px);
+  }
+  .tool-icons {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    margin-bottom: 1.25rem;
+  }
+  .icon-wrapper {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 3rem;
+    height: 3rem;
+    border-radius: 0.5rem;
+    font-size: 1.5rem;
+  }
+  .icon-wrapper.bg {
+    background: var(--accent);
+    color: var(--text-base);
+  }
+  .icon-wrapper.fg {
+    background: var(--bg-page);
+    border: 1px solid var(--border-color);
+    color: var(--accent);
+  }
+  .tool-card-content {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+  }
+  .tool-title {
+    font-size: 1.25rem;
+    font-weight: 700;
+    margin: 0 0 0.5rem;
+    color: var(--text-base);
+  }
+  .tool-description {
+    font-size: 0.9375rem;
+    color: var(--text-muted);
+    line-height: 1.5;
+    margin: 0;
+  }
+  .tool-card-meta {
+    padding-top: 1rem;
+    border-top: 1px solid var(--border-color);
+    margin-top: 1.5rem;
+  }
+  .tool-id {
+    display: inline-block;
+    font-size: 0.7rem;
+    background: var(--bg-page);
+    border: 1px solid var(--border-color);
+    padding: 0.35rem 0.75rem;
+    border-radius: 0.4rem;
+    color: var(--accent);
+    font-weight: 600;
+  }
+  .tool-locales {
+    display: flex;
+    gap: 0.5rem;
+    flex-wrap: wrap;
+  }
+  .locale-badge {
+    display: inline-block;
+    padding: 0.4rem 0.85rem;
+    background: var(--bg-page);
+    border: 1px solid var(--border-color);
+    border-radius: 0.4rem;
+    color: var(--text-muted);
+    text-decoration: none;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    transition: all 0.15s ease;
+  }
+  .locale-badge:hover,
+  .locale-badge.active {
+    color: var(--accent);
+    border-color: var(--accent);
+    background: rgba(244, 63, 94, 0.1);
+  }
+</style>

package/src/pages/index.astro

@@ -0,0 +1,4 @@
+---
+---
+<meta http-equiv="refresh" content="0;url=/es" />
+

package/src/tests/css_specificity_logic.test.ts

@@ -0,0 +1,39 @@
+import { expect, test, describe } from 'vitest';
+import { calculateSpecificity } from '../tool/cssSpecificityCalculator/logic';
+
+describe('CSS Specificity Calculator Logic', () => {
+  test('handles simple selectors', () => {
+    expect(calculateSpecificity('div')).toEqual([0, 0, 1]);
+    expect(calculateSpecificity('.card')).toEqual([0, 1, 0]);
+    expect(calculateSpecificity('#header')).toEqual([1, 0, 0]);
+  });
+
+  test('handles :where() - should be zero specificity', () => {
+    expect(calculateSpecificity(':where(#header) p')).toEqual([0, 0, 1]);
+    expect(calculateSpecificity(':where(.a, .b, #c)')).toEqual([0, 0, 0]);
+  });
+
+  test('handles :is() - should take max specificity', () => {
+    expect(calculateSpecificity(':is(.card, #header) p')).toEqual([1, 0, 1]);
+    expect(calculateSpecificity(':is(div, span)')).toEqual([0, 0, 1]);
+  });
+
+  test('handles :not() - should take specificity of argument', () => {
+    expect(calculateSpecificity('div:not(.active)')).toEqual([0, 1, 1]);
+    expect(calculateSpecificity(':not(#id, .class)')).toEqual([1, 0, 0]);
+  });
+
+  test('handles :has() - should take max specificity', () => {
+    expect(calculateSpecificity('div:has(p)')).toEqual([0, 0, 2]);
+    expect(calculateSpecificity('section:has(.important)')).toEqual([0, 1, 1]);
+  });
+
+  test('handles nested functional pseudos', () => {
+    expect(calculateSpecificity(':is(div, :is(.a))')).toEqual([0, 1, 0]);
+    expect(calculateSpecificity(':not(:where(#id))')).toEqual([0, 0, 0]);
+  });
+
+  test('handles complex combinations', () => {
+    expect(calculateSpecificity('header#main-header.nav:hover > div::before')).toEqual([1, 2, 3]);
+  });
+});

package/src/tests/faq_count.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import type * as DATA from '../data';
+
+const TOOLS: typeof DATA.developerCategory[] = [];
+
+describe('FAQ Content Validation', () => {
+  TOOLS.forEach((entry) => {
+    describe(`Tool: ${entry.icon}`, () => {
+      it('placeholder', () => {
+        expect(true).toBe(true);
+      });
+    });
+  });
+
+  it('no tools registered yet', () => {
+    expect(TOOLS.length).toBe(0);
+  });
+});
+

package/src/tests/locale_completeness.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import type { ToolLocaleContent } from '../types';
+
+describe('Locale Completeness Validation', () => {
+  ALL_TOOLS.forEach((tool) => {
+    describe(`Tool: ${tool.entry.id}`, () => {
+      Object.keys(tool.entry.i18n).forEach((locale) => {
+        describe(`Locale: ${locale}`, () => {
+          it('faqTitle should be defined when faq items exist', async () => {
+            const loader = tool.entry.i18n[locale as keyof typeof tool.entry.i18n];
+            const content = (await loader?.()) as ToolLocaleContent;
+
+            if (content.faq.length > 0) {
+              expect(
+                content.faqTitle,
+                `Tool "${tool.entry.id}" locale "${locale}" has ${content.faq.length} FAQ items but is missing faqTitle`,
+              ).toBeTruthy();
+            }
+          });
+
+          it('bibliographyTitle should be defined when bibliography items exist', async () => {
+            const loader = tool.entry.i18n[locale as keyof typeof tool.entry.i18n];
+            const content = (await loader?.()) as ToolLocaleContent;
+
+            if (content.bibliography.length > 0) {
+              expect(
+                content.bibliographyTitle,
+                `Tool "${tool.entry.id}" locale "${locale}" has ${content.bibliography.length} bibliography items but is missing bibliographyTitle`,
+              ).toBeTruthy();
+            }
+          });
+        });
+      });
+    });
+  });
+
+  it('should have at least 1 tool registered', () => {
+    expect(ALL_TOOLS.length).toBeGreaterThan(0);
+  });
+});
+

package/src/tests/mocks/astro_mock.js

@@ -0,0 +1,2 @@
+export default function () { return null; }
+

package/src/tests/no_h1_in_components.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const EXCLUDED_DIRS = ['node_modules', 'pages', 'layouts'];
+
+function findAstroFiles(dir: string): string[] {
+  const files: string[] = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory() && !EXCLUDED_DIRS.includes(entry.name)) {
+      files.push(...findAstroFiles(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith('.astro')) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function hasH1(content: string): boolean {
+  return /<h1[\s>]/i.test(content);
+}
+
+const srcDir = join(process.cwd(), 'src');
+const astroFiles = findAstroFiles(srcDir);
+
+describe('No H1 in Components', () => {
+  if (astroFiles.length === 0) {
+    it('no astro components found', () => {
+      expect(true).toBe(true);
+    });
+  }
+
+  astroFiles.forEach((file) => {
+    const relativePath = file.replace(process.cwd(), '');
+    it(`${relativePath} should not contain <h1>`, () => {
+      const content = readFileSync(file, 'utf-8');
+      expect(
+        hasH1(content),
+        `File "${relativePath}" contains a <h1> element. Use <h2> or lower inside components — h1 belongs to the page layout.`,
+      ).toBe(false);
+    });
+  });
+});
+

package/src/tests/schemas_fulfillment.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import type { ToolLocaleContent } from '../types';
+
+describe('Schemas Fulfillment Validation', () => {
+  ALL_TOOLS.forEach((tool) => {
+    describe(`Tool: ${tool.entry.id}`, () => {
+      Object.keys(tool.entry.i18n).forEach((locale) => {
+        it(`Locale: ${locale} should have faqSchema, appSchema and howToSchema`, async () => {
+          const loader = tool.entry.i18n[locale as keyof typeof tool.entry.i18n];
+          if (!loader) return;
+          const content = (await loader()) as ToolLocaleContent;
+
+          const schemaTypes = content.schemas.map((s: any) => s['@type']);
+
+          expect(schemaTypes, `Tool "${tool.entry.id}" locale "${locale}" is missing FAQPage schema`).toContain('FAQPage');
+          expect(schemaTypes, `Tool "${tool.entry.id}" locale "${locale}" is missing SoftwareApplication schema`).toContain('SoftwareApplication');
+          expect(schemaTypes, `Tool "${tool.entry.id}" locale "${locale}" is missing HowTo schema`).toContain('HowTo');
+        });
+      });
+    });
+  });
+});

package/src/tests/seo_length.test.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest';
+import * as DATA from '../data';
+
+const ENTRIES = [
+  { id: 'developerCategory', i18n: DATA.developerCategory.i18n },
+];
+
+describe('SEO Content Length Validation', () => {
+  ENTRIES.forEach((entry) => {
+    describe(`Tool: ${entry.id}`, () => {
+      Object.keys(entry.i18n).forEach((locale) => {
+        it(`${locale}: SEO section should exist`, async () => {
+          const loader = (entry.i18n as Record<string, () => Promise<{ seo?: unknown[] }>>)[locale];
+          const content = await loader();
+          if (!content.seo) return;
+          expect(Array.isArray(content.seo)).toBe(true);
+        });
+      });
+    });
+  });
+});
+

package/src/tests/title_quality.test.ts

@@ -0,0 +1,55 @@
+import { describe, it } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function getFiles(dir: string, ext: string[]): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+  const list = fs.readdirSync(dir);
+  for (const file of list) {
+    const fullPath = path.join(dir, file);
+    const stat = fs.statSync(fullPath);
+    if (stat && stat.isDirectory()) {
+      results.push(...getFiles(fullPath, ext));
+    } else if (ext.some((e) => file.endsWith(e))) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+const SRC_DIR = path.join(process.cwd(), 'src');
+
+describe('Project Titles - Separator Validation', () => {
+  const files = [
+    ...getFiles(path.join(SRC_DIR, 'tool'), ['.ts']),
+    ...getFiles(path.join(SRC_DIR, 'category'), ['.ts']),
+  ].filter(f => f.includes('i18n'));
+
+  it.each(files)('Verify that titles in %s do not contain | or -', (filePath) => {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const relativePath = path.relative(process.cwd(), filePath);
+
+    const titlePatterns = [
+      /const\s+title\s*=\s*['"]([^'"]+)['"]/g,
+      /title\s*:\s*['"]([^'"]+)['"]/g,
+    ];
+
+    const findings: string[] = [];
+
+    for (const pattern of titlePatterns) {
+      let match;
+      while ((match = pattern.exec(content)) !== null) {
+        const title = match[1];
+        if (title.includes('|') || title.includes('-')) {
+          findings.push(title);
+        }
+      }
+    }
+
+    if (findings.length > 0) {
+      const list = findings.map((f) => `  - "${f}"`).join('\n');
+      throw new Error(`Forbidden separators (| or -) found in titles in ${relativePath}:\n${list}`);
+    }
+  });
+});

package/src/tests/tool_validation.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import { developerCategory } from '../data';
+
+describe('Tool Validation Suite', () => {
+  describe('Library Registration', () => {
+    it('should have 24 tools in ALL_TOOLS', () => {
+      expect(ALL_TOOLS.length).toBe(24);
+    });
+
+    it('developerCategory should be defined', () => {
+      expect(developerCategory).toBeDefined();
+      expect(developerCategory.i18n).toBeDefined();
+    });
+  });
+});
+

package/src/tool/aspectRatio/bibliography.astro

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