@micazoyolli/foundation 0.3.1 → 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nadia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,17 +3,25 @@
 [![npm version](https://img.shields.io/npm/v/@micazoyolli/foundation.svg)](https://www.npmjs.com/package/@micazoyolli/foundation)
 [![license](https://img.shields.io/npm/l/@micazoyolli/foundation.svg)](./LICENSE)
 
-Fundamentos frontend no visuales para construir repos independientes con una base tecnica consistente.
+Fundamentos frontend no visuales para construir repos independientes con una base técnica consistente.
 
-Foundation centraliza mecanicas pequenas que se repiten entre proyectos: tokens SCSS base, mixins responsive, helpers TypeScript, primitivas DOM de accesibilidad y utilidades SEO/build. No incluye React, componentes visuales, tokens de marca, layouts ni metadata especifica.
+Foundation centraliza mecánicas pequeñas que se repiten entre proyectos: tokens SCSS base, mixins responsive, helpers TypeScript, primitivas DOM de accesibilidad y utilidades SEO/build. No incluye React, componentes visuales, tokens de marca, layouts ni metadata específica.
 
-## Documentacion
+## Documentation
 
-La documentacion completa esta en:
+La documentación principal vive en [foundation.nadia.dev](https://foundation.nadia.dev). Ahí está la guía completa, arquitectura, ejemplos, compatibilidad y referencia de la API.
 
-[https://foundation.nadia.dev](https://foundation.nadia.dev)
+## Features
 
-## Instalacion
+- Tokens SCSS base: spacing, radius, z-index, motion y breakpoints.
+- Mixins SCSS para responsive y reduced motion.
+- `cx` y guards TypeScript pequeños.
+- Helpers DOM para metadata client-side.
+- Primitivas de accesibilidad para focus, Escape, scroll lock y media protegida.
+- Helpers SEO/build para canonical, sitemap, HTML estático y escaping.
+- Sin dependencias runtime pesadas y sin React.
+
+## Instalación
 
 ```bash
 yarn add @micazoyolli/foundation
@@ -42,19 +50,19 @@ const canonical = getCanonicalUrl('https://example.com', '/contacto');
 }
 ```
 
-## Caracteristicas
+## Compatibilidad
 
-- Tokens SCSS base: spacing, radius, z-index, motion y breakpoints.
-- Mixins SCSS para responsive y reduced motion.
-- `cx` y guards TypeScript pequenos.
-- Helpers DOM para metadata client-side.
-- Primitivas de accesibilidad para focus, Escape, scroll lock y media protegida.
-- Helpers SEO/build para canonical, sitemap, HTML estatico y escaping.
-- Sin dependencias runtime pesadas y sin React.
+Foundation es framework agnostic y puede usarse con React, Next.js, Vue, Angular, Astro, Vite y Node según el helper utilizado.
 
-## Compatibilidad
+## Resources
 
-Foundation puede usarse con React, Next.js, Vue, Angular, Astro, Vite y scripts Node segun el tipo de helper. Los helpers DOM deben ejecutarse solo en navegador.
+- Documentation: [foundation.nadia.dev](https://foundation.nadia.dev)
+- GitHub: [github.com/micazoyolli/foundation](https://github.com/micazoyolli/foundation)
+- npm: [npmjs.com/package/@micazoyolli/foundation](https://www.npmjs.com/package/@micazoyolli/foundation)
+
+## Ecosistema
+
+Foundation forma parte del ecosistema técnico de [`<micazoyolli />`](https://nadia.dev). La librería sostiene las piezas repetibles para que cada proyecto pueda conservar su propia identidad visual, contenido y experiencia.
 
 ## Scripts
 
@@ -64,6 +72,10 @@ yarn test
 yarn docs:build
 ```
 
-## Autoria
+## Autoría
+
+Una creación de [`<micazoyolli />`](https://nadia.dev)
+
+## Licencia
 
-Una creacion de [`<micazoyolli />`](https://nadia.dev)
+MIT

package/dist/a11y/focus.js

@@ -7,30 +7,40 @@ export const FOCUSABLE_SELECTOR = [
     'textarea:not([disabled])',
     '[tabindex]:not([tabindex="-1"])',
 ].join(',');
+const getDocumentRef = (documentRef) => {
+    if (documentRef)
+        return documentRef;
+    if (typeof document !== 'undefined')
+        return document;
+    throw new ReferenceError('A document reference is required outside the browser.');
+};
+const getActiveElement = () => typeof document !== 'undefined' ? document.activeElement : undefined;
 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';
+export const lockBodyScroll = (documentRef) => {
+    const currentDocument = getDocumentRef(documentRef);
+    const previousOverflow = currentDocument.body.style.overflow;
+    currentDocument.body.style.overflow = 'hidden';
     return {
-        document: documentRef,
+        document: currentDocument,
         previousOverflow,
     };
 };
 export const unlockBodyScroll = (lock) => {
     lock.document.body.style.overflow = lock.previousOverflow;
 };
-export const restoreFocus = (element, documentRef = document) => {
-    if (!element || !documentRef.body.contains(element))
+export const restoreFocus = (element, documentRef) => {
+    const currentDocument = getDocumentRef(documentRef);
+    if (!element || !currentDocument.body.contains(element))
         return;
     const focusable = element;
     if (typeof focusable.focus === 'function') {
         focusable.focus();
     }
 };
-export const trapTabKey = (event, container, activeElement = document.activeElement) => {
+export const trapTabKey = (event, container, activeElement = getActiveElement()) => {
     if (event.key !== 'Tab')
         return false;
     const focusableElements = getFocusableElements(container);

package/dist/a11y/targets.js

@@ -1,2 +1,2 @@
-export const isElement = (target) => target instanceof Element;
-export const isHTMLElement = (target) => target instanceof HTMLElement;
+export const isElement = (target) => typeof Element !== 'undefined' && target instanceof Element;
+export const isHTMLElement = (target) => typeof HTMLElement !== 'undefined' && target instanceof HTMLElement;

package/dist/seo/dom.js

@@ -1,34 +1,44 @@
-export const updateDocumentTitle = (title, documentRef = document) => {
-    documentRef.title = title;
+const getDocumentRef = (documentRef) => {
+    if (documentRef)
+        return documentRef;
+    if (typeof document !== 'undefined')
+        return document;
+    throw new ReferenceError('A document reference is required outside the browser.');
 };
-export const upsertMeta = (selector, attributes, documentRef = document) => {
-    let element = documentRef.head.querySelector(selector);
+export const updateDocumentTitle = (title, documentRef) => {
+    getDocumentRef(documentRef).title = title;
+};
+export const upsertMeta = (selector, attributes, documentRef) => {
+    const currentDocument = getDocumentRef(documentRef);
+    let element = currentDocument.head.querySelector(selector);
     if (!element) {
-        element = documentRef.createElement('meta');
-        documentRef.head.appendChild(element);
+        element = currentDocument.createElement('meta');
+        currentDocument.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"]');
+export const upsertCanonical = (href, documentRef) => {
+    const currentDocument = getDocumentRef(documentRef);
+    let element = currentDocument.head.querySelector('link[rel="canonical"]');
     if (!element) {
-        element = documentRef.createElement('link');
+        element = currentDocument.createElement('link');
         element.rel = 'canonical';
-        documentRef.head.appendChild(element);
+        currentDocument.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}"]`);
+export const upsertAlternate = (hreflang, href, documentRef) => {
+    const currentDocument = getDocumentRef(documentRef);
+    let element = currentDocument.head.querySelector(`link[rel="alternate"][hreflang="${hreflang}"]`);
     if (!element) {
-        element = documentRef.createElement('link');
+        element = currentDocument.createElement('link');
         element.rel = 'alternate';
         element.hreflang = hreflang;
-        documentRef.head.appendChild(element);
+        currentDocument.head.appendChild(element);
     }
     element.href = href;
     return element;

package/dist/seo/html.js

@@ -1,5 +1,9 @@
+import { escapeHtml } from './text.js';
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 const insertBeforeHeadEnd = (html, tag) => html.includes('</head>') ? html.replace('</head>', `    ${tag}\n  </head>`) : html;
+const getMetaTag = (name, content) => `<meta name="${name}" content="${escapeHtml(content)}" />`;
+const getPropertyMetaTag = (property, content) => `<meta property="${property}" content="${escapeHtml(content)}" />`;
+const getLinkTag = (rel, href, attributes = '') => `<link rel="${rel}"${attributes} href="${escapeHtml(href)}" />`;
 export const upsertMetaTag = (html, selector, tag) => {
     const pattern = new RegExp(`<meta\\s+${escapeRegExp(selector)}[^>]*>`);
     if (pattern.test(html)) {
@@ -16,46 +20,46 @@ export const upsertLinkTag = (html, selector, 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}" />`)
+    .map(({ href, hreflang }) => getLinkTag('alternate', href, ` hreflang="${escapeHtml(hreflang)}"`))
     .join('\n    ');
 export const applyHtmlMetadata = (html, metadata, alternates = []) => {
     let next = html;
     if (metadata.lang) {
-        next = next.replace(/<html\s+lang="[^"]*">/, `<html lang="${metadata.lang}">`);
+        next = next.replace(/<html\s+lang="[^"]*">/, `<html lang="${escapeHtml(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}" />`);
+        next = next.replace(/<title>[\s\S]*?<\/title>/, `<title>${escapeHtml(metadata.title)}</title>`);
+        next = upsertMetaTag(next, 'name="title"', getMetaTag('title', metadata.title));
+        next = upsertMetaTag(next, 'property="og:title"', getPropertyMetaTag('og:title', metadata.title));
+        next = upsertMetaTag(next, 'name="twitter:title"', getMetaTag('twitter:title', 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}" />`);
+        next = upsertMetaTag(next, 'name="description"', getMetaTag('description', metadata.description));
+        next = upsertMetaTag(next, 'property="og:description"', getPropertyMetaTag('og:description', metadata.description));
+        next = upsertMetaTag(next, 'name="twitter:description"', getMetaTag('twitter:description', 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}" />`);
+        next = upsertMetaTag(next, 'property="og:url"', getPropertyMetaTag('og:url', metadata.canonical));
+        next = upsertLinkTag(next, 'rel="canonical"', getLinkTag('canonical', 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}" />`);
+        next = upsertMetaTag(next, 'property="og:image"', getPropertyMetaTag('og:image', metadata.image));
+        next = upsertMetaTag(next, 'name="twitter:image"', getMetaTag('twitter:image', metadata.image));
     }
     if (metadata.robots) {
-        next = upsertMetaTag(next, 'name="robots"', `<meta name="robots" content="${metadata.robots}" />`);
+        next = upsertMetaTag(next, 'name="robots"', getMetaTag('robots', metadata.robots));
     }
     if (metadata.siteName) {
-        next = upsertMetaTag(next, 'property="og:site_name"', `<meta property="og:site_name" content="${metadata.siteName}" />`);
+        next = upsertMetaTag(next, 'property="og:site_name"', getPropertyMetaTag('og:site_name', metadata.siteName));
     }
     if (metadata.ogImageWidth) {
-        next = upsertMetaTag(next, 'property="og:image:width"', `<meta property="og:image:width" content="${metadata.ogImageWidth}" />`);
+        next = upsertMetaTag(next, 'property="og:image:width"', getPropertyMetaTag('og:image:width', String(metadata.ogImageWidth)));
     }
     if (metadata.ogImageHeight) {
-        next = upsertMetaTag(next, 'property="og:image:height"', `<meta property="og:image:height" content="${metadata.ogImageHeight}" />`);
+        next = upsertMetaTag(next, 'property="og:image:height"', getPropertyMetaTag('og:image:height', String(metadata.ogImageHeight)));
     }
     if (metadata.twitterCard) {
-        next = upsertMetaTag(next, 'name="twitter:card"', `<meta name="twitter:card" content="${metadata.twitterCard}" />`);
+        next = upsertMetaTag(next, 'name="twitter:card"', getMetaTag('twitter:card', metadata.twitterCard));
     }
     if (alternates.length > 0) {
         next = removeAlternateLinks(next);

package/package.json

@@ -1,9 +1,29 @@
 {
   "name": "@micazoyolli/foundation",
-  "version": "0.3.1",
-  "description": "Fundamentos frontend no visuales para el ecosistema tecnico de Nad.",
+  "version": "0.3.2",
+  "description": "Fundamentos frontend no visuales para el ecosistema técnico de Nad.",
   "license": "MIT",
   "type": "module",
+  "homepage": "https://foundation.nadia.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/micazoyolli/foundation.git"
+  },
+  "bugs": {
+    "url": "https://github.com/micazoyolli/foundation/issues"
+  },
+  "keywords": [
+    "frontend",
+    "design-tokens",
+    "scss",
+    "accessibility",
+    "seo",
+    "typescript",
+    "vitepress"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -32,6 +52,7 @@
     "test": "yarn build && node --test tests/*.test.mjs"
   },
   "devDependencies": {
+    "sass-embedded": "^1.100.0",
     "typescript": "6.0.3",
     "vitepress": "^1.6.4"
   },