@micazoyolli/foundation 0.1.2 → 0.3.0

package/README.md

@@ -1,92 +1,91 @@
 # @micazoyolli/foundation
 
-Paquete público de fundamentos compartidos no visuales para los proyectos de Micazoyolli. Centraliza utilidades pequeñas y estables para mantener consistencia entre repos independientes sin introducir componentes visuales ni decisiones de marca.
-
-## Características
-
-- Tokens SCSS base para spacing, radius, z-index y motion
-- Breakpoints y mixins responsive reutilizables
-- 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
-- Exports separados para TypeScript y SCSS
-- Consumo desde npm sin credenciales especiales
-
-## Tecnologías
-
-- TypeScript
-- SCSS
-- Yarn 1
-- npm
-
-## Estructura
-
-```txt
-src/
-├── a11y/
-├── scss/
-│   ├── mixins/
-│   └── tokens/
-├── utils/
-└── index.ts
-
-examples/
-dist/
-```
-
-## Scripts
+Fundamentos compartidos no visuales para los proyectos de Micazoyolli.
 
-```bash
-yarn install
-yarn build
-yarn clean
-yarn prepack
-```
+`@micazoyolli/foundation` centraliza utilidades pequenas y estables que ya se repiten entre repos independientes: tokens SCSS base, mixins responsive, helpers TypeScript, accesibilidad ligera y utilidades SEO/build. No incluye React, componentes visuales, tokens de marca, layouts ni metadata especifica de ningun proyecto.
 
-## Instalación
+## Instalacion
 
 ```bash
 yarn add @micazoyolli/foundation
 ```
 
-## Uso
+## Entrypoints
 
 TypeScript:
 
 ```ts
-import { cx, isElement } from '@micazoyolli/foundation';
-
-const className = cx('button', isActive && 'button--active');
-
-if (isElement(event.target)) {
-  event.target.closest('[data-protected-media]');
-}
+import { cx, getCanonicalUrl } from '@micazoyolli/foundation';
 ```
 
 SCSS:
 
 ```scss
 @use '@micazoyolli/foundation/scss' as foundation;
+```
+
+## Documentacion
+
+### Primeros pasos
+
+- [Getting Started](./docs/getting-started.md)
+- [Installation](./docs/installation.md)
+
+### SCSS
 
-.section {
-  padding: foundation.$space-6;
-  border-radius: foundation.$radius-md;
+- [Breakpoints](./docs/scss/breakpoints.md)
+- [Spacing](./docs/scss/spacing.md)
+- [Motion](./docs/scss/motion.md)
+- [Mixins](./docs/scss/mixins.md)
 
-  @include foundation.down(foundation.$breakpoint-md) {
-    padding: foundation.$space-4;
-  }
-}
+### TypeScript
+
+- [DOM y accesibilidad](./docs/typescript/dom.md)
+- [SEO y build](./docs/typescript/seo.md)
+- [Utils](./docs/typescript/utils.md)
+
+### Proyecto
+
+- [Changelog](./docs/changelog.md)
+- [Roadmap](./docs/roadmap.md)
+
+## Que incluye
+
+- Tokens SCSS base para spacing, radius, z-index, motion y breakpoints.
+- Mixins SCSS para responsive y reduced motion.
+- `cx` para composicion simple de clases.
+- Guards TypeScript pequenos.
+- Helpers DOM/a11y para targets, teclado y media protegida.
+- Helpers DOM/a11y para foco, scroll lock, Escape y focus trap.
+- Helpers SEO/build para escaping, canonical, sitemap, metadata DOM y HTML estatico.
+
+## Que NO incluye
+
+- Componentes React.
+- Botones, cards, layouts o grids visuales.
+- Tokens finales de marca, color o tipografia.
+- Metadata especifica de proyectos.
+- Logica de negocio.
+- Dependencias UI pesadas.
+
+## Scripts
+
+```bash
+yarn install
+yarn build
+yarn clean
+yarn prepack
 ```
 
-## Buenas prácticas
+## Proyectos que ya lo consumen
 
-- Mantener el paquete pequeño y estrictamente no visual
-- Evitar tokens de marca, layouts, componentes React, SEO o tipografías finales
-- Publicar cambios mediante versiones semánticas
-- Exportar solo utilidades compartibles entre repos independientes
-- Evitar dependencias UI pesadas
-- Adoptar el paquete gradualmente en cada proyecto
+- TeInvitaASu Invitaciones
+- TeInvitaASu.Party
+- Micazoyolli
+- Estilo Natura
+- OhMamaMXX
+- WTFashion
 
 ## Autora
 
-Una creación de [`<micazoyolli />✨`](https://nadia.dev)
+Una creacion de [`<micazoyolli />`](https://nadia.dev)

package/dist/a11y/focus.d.ts

@@ -0,0 +1,15 @@
+export declare const FOCUSABLE_SELECTOR: string;
+export type BodyScrollLock = {
+    document: Document;
+    previousOverflow: string;
+};
+type FocusableElement = HTMLElement & {
+    disabled?: boolean;
+};
+export declare const getFocusableElements: (container: Pick<ParentNode, "querySelectorAll">) => FocusableElement[];
+export declare const lockBodyScroll: (documentRef?: Document) => BodyScrollLock;
+export declare const unlockBodyScroll: (lock: BodyScrollLock) => void;
+export declare const restoreFocus: (element: Element | null | undefined, documentRef?: Document) => void;
+export declare const trapTabKey: (event: Pick<KeyboardEvent, "key" | "shiftKey" | "preventDefault">, container: Pick<ParentNode, "querySelectorAll">, activeElement?: Element | null | undefined) => boolean;
+export declare const createEscapeKeyHandler: (onEscape: () => void) => (event: Pick<KeyboardEvent, "key">) => void;
+export {};

package/dist/a11y/focus.js

@@ -0,0 +1,57 @@
+import { KEYBOARD_KEYS } from './keyboard.js';
+export const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+const canReceiveFocus = (element) => !element.disabled
+    && element.getAttribute('aria-hidden') !== 'true'
+    && element.tabIndex !== -1;
+export const getFocusableElements = (container) => Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter(canReceiveFocus);
+export const lockBodyScroll = (documentRef = document) => {
+    const previousOverflow = documentRef.body.style.overflow;
+    documentRef.body.style.overflow = 'hidden';
+    return {
+        document: documentRef,
+        previousOverflow,
+    };
+};
+export const unlockBodyScroll = (lock) => {
+    lock.document.body.style.overflow = lock.previousOverflow;
+};
+export const restoreFocus = (element, documentRef = document) => {
+    if (!element || !documentRef.body.contains(element))
+        return;
+    const focusable = element;
+    if (typeof focusable.focus === 'function') {
+        focusable.focus();
+    }
+};
+export const trapTabKey = (event, container, activeElement = document.activeElement) => {
+    if (event.key !== 'Tab')
+        return false;
+    const focusableElements = getFocusableElements(container);
+    const firstElement = focusableElements[0];
+    const lastElement = focusableElements[focusableElements.length - 1];
+    if (!firstElement || !lastElement)
+        return false;
+    if (event.shiftKey && activeElement === firstElement) {
+        event.preventDefault();
+        lastElement.focus();
+        return true;
+    }
+    if (!event.shiftKey && activeElement === lastElement) {
+        event.preventDefault();
+        firstElement.focus();
+        return true;
+    }
+    return false;
+};
+export const createEscapeKeyHandler = (onEscape) => (event) => {
+    if (event.key === KEYBOARD_KEYS.escape) {
+        onEscape();
+    }
+};

package/dist/a11y/index.d.ts

@@ -1,3 +1,5 @@
-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';
+export { FOCUSABLE_SELECTOR, createEscapeKeyHandler, getFocusableElements, lockBodyScroll, restoreFocus, trapTabKey, unlockBodyScroll, } from './focus.js';
+export type { BodyScrollLock } from './focus.js';

package/dist/a11y/index.js

@@ -1,3 +1,4 @@
-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';
+export { FOCUSABLE_SELECTOR, createEscapeKeyHandler, getFocusableElements, lockBodyScroll, restoreFocus, trapTabKey, unlockBodyScroll, } from './focus.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,6 @@
-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 { FOCUSABLE_SELECTOR, KEYBOARD_KEYS, PROTECTED_MEDIA_SELECTOR, createEscapeKeyHandler, getFocusableElements, isElement, isHTMLElement, isKeyboardActivation, isProtectedMediaTarget, lockBodyScroll, restoreFocus, trapTabKey, unlockBodyScroll, } from './a11y/index.js';
+export type { BodyScrollLock } 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 { FOCUSABLE_SELECTOR, KEYBOARD_KEYS, PROTECTED_MEDIA_SELECTOR, createEscapeKeyHandler, getFocusableElements, isElement, isHTMLElement, isKeyboardActivation, isProtectedMediaTarget, lockBodyScroll, restoreFocus, trapTabKey, unlockBodyScroll, } from './a11y/index.js';
+export { cx } from './utils/cx.js';
+export { isNonEmptyString } from './utils/guards.js';
+export * from './seo/index.js';

package/dist/seo/dom.d.ts

@@ -0,0 +1,9 @@
+export type MetaAttributes = {
+    content: string;
+    name?: string;
+    property?: string;
+};
+export declare const updateDocumentTitle: (title: string, documentRef?: Document) => void;
+export declare const upsertMeta: (selector: string, attributes: MetaAttributes, documentRef?: Document) => HTMLMetaElement;
+export declare const upsertCanonical: (href: string, documentRef?: Document) => HTMLLinkElement;
+export declare const upsertAlternate: (hreflang: string, href: string, documentRef?: Document) => HTMLLinkElement;

package/dist/seo/dom.js

@@ -0,0 +1,35 @@
+export const updateDocumentTitle = (title, documentRef = document) => {
+    documentRef.title = title;
+};
+export const upsertMeta = (selector, attributes, documentRef = document) => {
+    let element = documentRef.head.querySelector(selector);
+    if (!element) {
+        element = documentRef.createElement('meta');
+        documentRef.head.appendChild(element);
+    }
+    Object.entries(attributes).forEach(([name, value]) => {
+        element?.setAttribute(name, value);
+    });
+    return element;
+};
+export const upsertCanonical = (href, documentRef = document) => {
+    let element = documentRef.head.querySelector('link[rel="canonical"]');
+    if (!element) {
+        element = documentRef.createElement('link');
+        element.rel = 'canonical';
+        documentRef.head.appendChild(element);
+    }
+    element.href = href;
+    return element;
+};
+export const upsertAlternate = (hreflang, href, documentRef = document) => {
+    let element = documentRef.head.querySelector(`link[rel="alternate"][hreflang="${hreflang}"]`);
+    if (!element) {
+        element = documentRef.createElement('link');
+        element.rel = 'alternate';
+        element.hreflang = hreflang;
+        documentRef.head.appendChild(element);
+    }
+    element.href = href;
+    return element;
+};

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,9 @@
+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';
+export { updateDocumentTitle, upsertAlternate, upsertCanonical, upsertMeta, } from './dom.js';
+export type { MetaAttributes } from './dom.js';

package/dist/seo/index.js

@@ -0,0 +1,5 @@
+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';
+export { updateDocumentTitle, upsertAlternate, upsertCanonical, upsertMeta, } from './dom.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.3.0",
   "description": "Fundamentos compartidos no visuales para los proyectos de Micazoyolli.",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,8 @@
     "build": "tsc -p tsconfig.json && yarn copy-scss",
     "clean": "rm -rf dist",
     "copy-scss": "rsync -av --include='*/' --include='*.scss' --exclude='*' src/scss/ dist/scss/",
-    "prepack": "yarn build"
+    "prepack": "yarn build",
+    "test": "yarn build && node --test tests/*.test.mjs"
   },
   "devDependencies": {
     "typescript": "6.0.3"