@micazoyolli/foundation 0.1.2 → 0.2.0

package/README.md

@@ -9,6 +9,7 @@ Paquete público de fundamentos compartidos no visuales para los proyectos de Mi
 - Helper `cx` para composición segura de clases
 - Guards TypeScript pequeños para validaciones comunes
 - Utilidades básicas de accesibilidad y protección selectiva de media
+- Helpers SEO/build puros para HTML estático, canonical y sitemap
 - Exports separados para TypeScript y SCSS
 - Consumo desde npm sin credenciales especiales
 
@@ -27,6 +28,7 @@ src/
 ├── scss/
 │   ├── mixins/
 │   └── tokens/
+├── seo/
 ├── utils/
 └── index.ts
 
@@ -63,6 +65,24 @@ if (isElement(event.target)) {
 }
 ```
 
+SEO/build:
+
+```ts
+import {
+  applyHtmlMetadata,
+  buildSitemapXml,
+  getCanonicalUrl,
+} from '@micazoyolli/foundation';
+
+const canonical = getCanonicalUrl('https://example.com', '/contacto');
+const html = applyHtmlMetadata(template, {
+  canonical,
+  title: 'Contacto',
+  description: 'Hablemos de tu proyecto.',
+});
+const sitemap = buildSitemapXml([{ loc: canonical, priority: '0.8' }]);
+```
+
 SCSS:
 
 ```scss
@@ -81,7 +101,7 @@ SCSS:
 ## Buenas prácticas
 
 - Mantener el paquete pequeño y estrictamente no visual
-- Evitar tokens de marca, layouts, componentes React, SEO o tipografías finales
+- Evitar tokens de marca, layouts, componentes React, metadata específica o tipografías finales
 - Publicar cambios mediante versiones semánticas
 - Exportar solo utilidades compartibles entre repos independientes
 - Evitar dependencias UI pesadas

package/dist/a11y/index.d.ts

@@ -1,3 +1,3 @@
-export { isElement, isHTMLElement } from './targets';
-export { KEYBOARD_KEYS, isKeyboardActivation } from './keyboard';
-export { PROTECTED_MEDIA_SELECTOR, isProtectedMediaTarget, } from './protectedMedia';
+export { isElement, isHTMLElement } from './targets.js';
+export { KEYBOARD_KEYS, isKeyboardActivation } from './keyboard.js';
+export { PROTECTED_MEDIA_SELECTOR, isProtectedMediaTarget, } from './protectedMedia.js';

package/dist/a11y/index.js

@@ -1,3 +1,3 @@
-export { isElement, isHTMLElement } from './targets';
-export { KEYBOARD_KEYS, isKeyboardActivation } from './keyboard';
-export { PROTECTED_MEDIA_SELECTOR, isProtectedMediaTarget, } from './protectedMedia';
+export { isElement, isHTMLElement } from './targets.js';
+export { KEYBOARD_KEYS, isKeyboardActivation } from './keyboard.js';
+export { PROTECTED_MEDIA_SELECTOR, isProtectedMediaTarget, } from './protectedMedia.js';

package/dist/a11y/protectedMedia.js

@@ -1,4 +1,4 @@
-import { isElement } from './targets';
+import { isElement } from './targets.js';
 export const PROTECTED_MEDIA_SELECTOR = [
     'img',
     'svg',

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { KEYBOARD_KEYS, PROTECTED_MEDIA_SELECTOR, isElement, isHTMLElement, isKeyboardActivation, isProtectedMediaTarget, } from './a11y';
-export { cx } from './utils/cx';
-export type { ClassValue } from './utils/cx';
-export { isNonEmptyString } from './utils/guards';
+export { KEYBOARD_KEYS, PROTECTED_MEDIA_SELECTOR, isElement, isHTMLElement, isKeyboardActivation, isProtectedMediaTarget, } from './a11y/index.js';
+export { cx } from './utils/cx.js';
+export type { ClassValue } from './utils/cx.js';
+export { isNonEmptyString } from './utils/guards.js';
+export * from './seo/index.js';

package/dist/index.js

@@ -1,3 +1,4 @@
-export { KEYBOARD_KEYS, PROTECTED_MEDIA_SELECTOR, isElement, isHTMLElement, isKeyboardActivation, isProtectedMediaTarget, } from './a11y';
-export { cx } from './utils/cx';
-export { isNonEmptyString } from './utils/guards';
+export { KEYBOARD_KEYS, PROTECTED_MEDIA_SELECTOR, isElement, isHTMLElement, isKeyboardActivation, isProtectedMediaTarget, } from './a11y/index.js';
+export { cx } from './utils/cx.js';
+export { isNonEmptyString } from './utils/guards.js';
+export * from './seo/index.js';

package/dist/seo/html.d.ts

@@ -0,0 +1,22 @@
+export type HtmlMetadata = {
+    canonical?: string;
+    description?: string;
+    image?: string;
+    lang?: string;
+    ogImageHeight?: number | string;
+    ogImageWidth?: number | string;
+    robots?: string;
+    siteName?: string;
+    title?: string;
+    twitterCard?: string;
+};
+export type AlternateLink = {
+    href: string;
+    hreflang: string;
+};
+export declare const upsertMetaTag: (html: string, selector: string, tag: string) => string;
+export declare const upsertLinkTag: (html: string, selector: string, tag: string) => string;
+export declare const removeAlternateLinks: (html: string) => string;
+export declare const getAlternateLinkTags: (alternates: readonly AlternateLink[]) => string;
+export declare const applyHtmlMetadata: (html: string, metadata: HtmlMetadata, alternates?: readonly AlternateLink[]) => string;
+export declare const getStaticRouteOutputPath: (routePath: string) => string;

package/dist/seo/html.js

@@ -0,0 +1,71 @@
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const insertBeforeHeadEnd = (html, tag) => html.includes('</head>') ? html.replace('</head>', `    ${tag}\n  </head>`) : html;
+export const upsertMetaTag = (html, selector, tag) => {
+    const pattern = new RegExp(`<meta\\s+${escapeRegExp(selector)}[^>]*>`);
+    if (pattern.test(html)) {
+        return html.replace(pattern, tag);
+    }
+    return insertBeforeHeadEnd(html, tag);
+};
+export const upsertLinkTag = (html, selector, tag) => {
+    const pattern = new RegExp(`<link\\s+${escapeRegExp(selector)}[^>]*>`);
+    if (pattern.test(html)) {
+        return html.replace(pattern, tag);
+    }
+    return insertBeforeHeadEnd(html, tag);
+};
+export const removeAlternateLinks = (html) => html.replace(/\s*<link\s+rel="alternate"\s+hreflang="[^"]+"\s+href="[^"]+"\s*\/?>\n?/g, '');
+export const getAlternateLinkTags = (alternates) => alternates
+    .map(({ href, hreflang }) => `<link rel="alternate" hreflang="${hreflang}" href="${href}" />`)
+    .join('\n    ');
+export const applyHtmlMetadata = (html, metadata, alternates = []) => {
+    let next = html;
+    if (metadata.lang) {
+        next = next.replace(/<html\s+lang="[^"]*">/, `<html lang="${metadata.lang}">`);
+    }
+    if (metadata.title) {
+        next = next.replace(/<title>[\s\S]*?<\/title>/, `<title>${metadata.title}</title>`);
+        next = upsertMetaTag(next, 'name="title"', `<meta name="title" content="${metadata.title}" />`);
+        next = upsertMetaTag(next, 'property="og:title"', `<meta property="og:title" content="${metadata.title}" />`);
+        next = upsertMetaTag(next, 'name="twitter:title"', `<meta name="twitter:title" content="${metadata.title}" />`);
+    }
+    if (metadata.description) {
+        next = upsertMetaTag(next, 'name="description"', `<meta name="description" content="${metadata.description}" />`);
+        next = upsertMetaTag(next, 'property="og:description"', `<meta property="og:description" content="${metadata.description}" />`);
+        next = upsertMetaTag(next, 'name="twitter:description"', `<meta name="twitter:description" content="${metadata.description}" />`);
+    }
+    if (metadata.canonical) {
+        next = upsertMetaTag(next, 'property="og:url"', `<meta property="og:url" content="${metadata.canonical}" />`);
+        next = upsertLinkTag(next, 'rel="canonical"', `<link rel="canonical" href="${metadata.canonical}" />`);
+    }
+    if (metadata.image) {
+        next = upsertMetaTag(next, 'property="og:image"', `<meta property="og:image" content="${metadata.image}" />`);
+        next = upsertMetaTag(next, 'name="twitter:image"', `<meta name="twitter:image" content="${metadata.image}" />`);
+    }
+    if (metadata.robots) {
+        next = upsertMetaTag(next, 'name="robots"', `<meta name="robots" content="${metadata.robots}" />`);
+    }
+    if (metadata.siteName) {
+        next = upsertMetaTag(next, 'property="og:site_name"', `<meta property="og:site_name" content="${metadata.siteName}" />`);
+    }
+    if (metadata.ogImageWidth) {
+        next = upsertMetaTag(next, 'property="og:image:width"', `<meta property="og:image:width" content="${metadata.ogImageWidth}" />`);
+    }
+    if (metadata.ogImageHeight) {
+        next = upsertMetaTag(next, 'property="og:image:height"', `<meta property="og:image:height" content="${metadata.ogImageHeight}" />`);
+    }
+    if (metadata.twitterCard) {
+        next = upsertMetaTag(next, 'name="twitter:card"', `<meta name="twitter:card" content="${metadata.twitterCard}" />`);
+    }
+    if (alternates.length > 0) {
+        next = removeAlternateLinks(next);
+        next = insertBeforeHeadEnd(next, getAlternateLinkTags(alternates));
+    }
+    return next;
+};
+export const getStaticRouteOutputPath = (routePath) => {
+    const normalized = routePath === '' ? '/' : routePath;
+    if (normalized === '/')
+        return 'index.html';
+    return `${normalized.replace(/^\/+/, '').replace(/\/+$/, '')}/index.html`;
+};

package/dist/seo/index.d.ts

@@ -0,0 +1,7 @@
+export { applyHtmlMetadata, getAlternateLinkTags, getStaticRouteOutputPath, removeAlternateLinks, upsertLinkTag, upsertMetaTag, } from './html.js';
+export type { AlternateLink, HtmlMetadata } from './html.js';
+export { buildSitemapXml } from './sitemap.js';
+export type { SitemapEntry, SitemapOptions } from './sitemap.js';
+export { escapeHtml, escapeXml } from './text.js';
+export { getAbsoluteUrl, getCanonicalUrl, isAbsoluteUrl, normalizeBaseUrl, normalizeRoutePath, } from './url.js';
+export type { CanonicalUrlOptions } from './url.js';

package/dist/seo/index.js

@@ -0,0 +1,4 @@
+export { applyHtmlMetadata, getAlternateLinkTags, getStaticRouteOutputPath, removeAlternateLinks, upsertLinkTag, upsertMetaTag, } from './html.js';
+export { buildSitemapXml } from './sitemap.js';
+export { escapeHtml, escapeXml } from './text.js';
+export { getAbsoluteUrl, getCanonicalUrl, isAbsoluteUrl, normalizeBaseUrl, normalizeRoutePath, } from './url.js';

package/dist/seo/sitemap.d.ts

@@ -0,0 +1,10 @@
+export type SitemapEntry = {
+    changefreq?: string;
+    lastmod?: string;
+    loc: string;
+    priority?: string;
+};
+export type SitemapOptions = {
+    lastmod?: string;
+};
+export declare const buildSitemapXml: (entries: readonly SitemapEntry[], options?: SitemapOptions) => string;

package/dist/seo/sitemap.js

@@ -0,0 +1,21 @@
+import { escapeXml } from './text.js';
+export const buildSitemapXml = (entries, options = {}) => {
+    const body = entries
+        .map((entry) => {
+        const lastmod = entry.lastmod ?? options.lastmod;
+        const parts = [
+            '  <url>',
+            `    <loc>${escapeXml(entry.loc)}</loc>`,
+        ];
+        if (lastmod)
+            parts.push(`    <lastmod>${escapeXml(lastmod)}</lastmod>`);
+        if (entry.changefreq)
+            parts.push(`    <changefreq>${escapeXml(entry.changefreq)}</changefreq>`);
+        if (entry.priority)
+            parts.push(`    <priority>${escapeXml(entry.priority)}</priority>`);
+        parts.push('  </url>');
+        return parts.join('\n');
+    })
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${body}\n</urlset>\n`;
+};

package/dist/seo/text.d.ts

@@ -0,0 +1,2 @@
+export declare const escapeHtml: (value: unknown) => string;
+export declare const escapeXml: (value: unknown) => string;

package/dist/seo/text.js

@@ -0,0 +1,6 @@
+export const escapeHtml = (value) => String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+export const escapeXml = (value) => escapeHtml(value).replaceAll("'", '&apos;');

package/dist/seo/url.d.ts

@@ -0,0 +1,9 @@
+export type CanonicalUrlOptions = {
+    rootTrailingSlash?: boolean;
+    trailingSlash?: boolean;
+};
+export declare const normalizeBaseUrl: (baseUrl: string) => string;
+export declare const normalizeRoutePath: (routePath: string) => string;
+export declare const isAbsoluteUrl: (value: string) => boolean;
+export declare const getCanonicalUrl: (baseUrl: string, routePath: string, options?: CanonicalUrlOptions) => string;
+export declare const getAbsoluteUrl: (value: string, baseUrl: string, options?: CanonicalUrlOptions) => string;

package/dist/seo/url.js

@@ -0,0 +1,18 @@
+export const normalizeBaseUrl = (baseUrl) => baseUrl.replace(/\/+$/, '');
+export const normalizeRoutePath = (routePath) => {
+    const path = routePath.trim();
+    if (!path || path === '/')
+        return '/';
+    return `/${path.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+};
+export const isAbsoluteUrl = (value) => /^https?:\/\//i.test(value);
+export const getCanonicalUrl = (baseUrl, routePath, options = {}) => {
+    const base = normalizeBaseUrl(baseUrl);
+    const path = normalizeRoutePath(routePath);
+    if (path === '/') {
+        return options.rootTrailingSlash ? `${base}/` : base;
+    }
+    const canonical = `${base}${path}`;
+    return options.trailingSlash ? `${canonical}/` : canonical;
+};
+export const getAbsoluteUrl = (value, baseUrl, options = {}) => (isAbsoluteUrl(value) ? value : getCanonicalUrl(baseUrl, value, options));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micazoyolli/foundation",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Fundamentos compartidos no visuales para los proyectos de Micazoyolli.",
   "license": "MIT",
   "type": "module",