@micazoyolli/foundation 0.3.0 → 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

@@ -1,91 +1,81 @@
 # @micazoyolli/foundation
 
-Fundamentos compartidos no visuales para los proyectos de Micazoyolli.
+[![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)
 
-`@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.
+Fundamentos frontend no visuales para construir repos independientes con una base técnica consistente.
 
-## Instalacion
+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.
+
+## Documentation
+
+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.
+
+## Features
+
+- 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
 ```
 
-## Entrypoints
-
-TypeScript:
+## TypeScript
 
 ```ts
 import { cx, getCanonicalUrl } from '@micazoyolli/foundation';
+
+const className = cx('card', isActive && 'card--active');
+const canonical = getCanonicalUrl('https://example.com', '/contacto');
 ```
 
-SCSS:
+## SCSS
 
 ```scss
 @use '@micazoyolli/foundation/scss' as foundation;
-```
-
-## Documentacion
-
-### Primeros pasos
-
-- [Getting Started](./docs/getting-started.md)
-- [Installation](./docs/installation.md)
 
-### SCSS
+.section {
+  padding-block: foundation.$space-6;
 
-- [Breakpoints](./docs/scss/breakpoints.md)
-- [Spacing](./docs/scss/spacing.md)
-- [Motion](./docs/scss/motion.md)
-- [Mixins](./docs/scss/mixins.md)
-
-### TypeScript
-
-- [DOM y accesibilidad](./docs/typescript/dom.md)
-- [SEO y build](./docs/typescript/seo.md)
-- [Utils](./docs/typescript/utils.md)
+  @include foundation.down(foundation.$breakpoint-md) {
+    padding-block: foundation.$space-4;
+  }
+}
+```
 
-### Proyecto
+## Compatibilidad
 
-- [Changelog](./docs/changelog.md)
-- [Roadmap](./docs/roadmap.md)
+Foundation es framework agnostic y puede usarse con React, Next.js, Vue, Angular, Astro, Vite y Node según el helper utilizado.
 
-## Que incluye
+## Resources
 
-- 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.
+- 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)
 
-## Que NO incluye
+## Ecosistema
 
-- 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.
+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
 
 ```bash
-yarn install
 yarn build
-yarn clean
-yarn prepack
+yarn test
+yarn docs:build
 ```
 
-## Proyectos que ya lo consumen
+## Autoría
 
-- TeInvitaASu Invitaciones
-- TeInvitaASu.Party
-- Micazoyolli
-- Estilo Natura
-- OhMamaMXX
-- WTFashion
+Una creación de [`<micazoyolli />`](https://nadia.dev)
 
-## Autora
+## 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.0",
-  "description": "Fundamentos compartidos no visuales para los proyectos de Micazoyolli.",
+  "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": {
@@ -25,11 +45,16 @@
     "build": "tsc -p tsconfig.json && yarn copy-scss",
     "clean": "rm -rf dist",
     "copy-scss": "rsync -av --include='*/' --include='*.scss' --exclude='*' src/scss/ dist/scss/",
+    "docs:build": "vitepress build docs",
+    "docs:dev": "vitepress dev docs --host 0.0.0.0",
+    "docs:preview": "vitepress preview docs --host 0.0.0.0",
     "prepack": "yarn build",
     "test": "yarn build && node --test tests/*.test.mjs"
   },
   "devDependencies": {
-    "typescript": "6.0.3"
+    "sass-embedded": "^1.100.0",
+    "typescript": "6.0.3",
+    "vitepress": "^1.6.4"
   },
   "packageManager": "yarn@1.22.22"
 }