@micazoyolli/foundation 0.2.0 → 0.3.1

package/README.md

@@ -1,112 +1,69 @@
 # @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
-- Helpers SEO/build puros para HTML estático, canonical y sitemap
-- 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/
-├── seo/
-├── utils/
-└── index.ts
-
-examples/
-dist/
-```
+[![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)
 
-## Scripts
+Fundamentos frontend no visuales para construir repos independientes con una base tecnica consistente.
 
-```bash
-yarn install
-yarn build
-yarn clean
-yarn prepack
-```
+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.
 
-## Instalación
+## Documentacion
 
-```bash
-yarn add @micazoyolli/foundation
-```
-
-## Uso
+La documentacion completa esta en:
 
-TypeScript:
-
-```ts
-import { cx, isElement } from '@micazoyolli/foundation';
+[https://foundation.nadia.dev](https://foundation.nadia.dev)
 
-const className = cx('button', isActive && 'button--active');
+## Instalacion
 
-if (isElement(event.target)) {
-  event.target.closest('[data-protected-media]');
-}
+```bash
+yarn add @micazoyolli/foundation
 ```
 
-SEO/build:
+## TypeScript
 
 ```ts
-import {
-  applyHtmlMetadata,
-  buildSitemapXml,
-  getCanonicalUrl,
-} from '@micazoyolli/foundation';
+import { cx, getCanonicalUrl } from '@micazoyolli/foundation';
 
+const className = cx('card', isActive && 'card--active');
 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
 
 ```scss
 @use '@micazoyolli/foundation/scss' as foundation;
 
 .section {
-  padding: foundation.$space-6;
-  border-radius: foundation.$radius-md;
+  padding-block: foundation.$space-6;
 
   @include foundation.down(foundation.$breakpoint-md) {
-    padding: foundation.$space-4;
+    padding-block: foundation.$space-4;
   }
 }
 ```
 
-## Buenas prácticas
+## Caracteristicas
+
+- 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.
+
+## Compatibilidad
+
+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.
 
-- Mantener el paquete pequeño y estrictamente no visual
-- 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
-- Adoptar el paquete gradualmente en cada proyecto
+## Scripts
+
+```bash
+yarn build
+yarn test
+yarn docs:build
+```
 
-## Autora
+## Autoria
 
-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.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.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/index.d.ts

@@ -1,4 +1,5 @@
-export { KEYBOARD_KEYS, PROTECTED_MEDIA_SELECTOR, isElement, isHTMLElement, isKeyboardActivation, isProtectedMediaTarget, } from './a11y/index.js';
+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';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { KEYBOARD_KEYS, PROTECTED_MEDIA_SELECTOR, isElement, isHTMLElement, isKeyboardActivation, isProtectedMediaTarget, } from './a11y/index.js';
+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/index.d.ts

@@ -5,3 +5,5 @@ 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

@@ -2,3 +2,4 @@ export { applyHtmlMetadata, getAlternateLinkTags, getStaticRouteOutputPath, remo
 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@micazoyolli/foundation",
-  "version": "0.2.0",
-  "description": "Fundamentos compartidos no visuales para los proyectos de Micazoyolli.",
+  "version": "0.3.1",
+  "description": "Fundamentos frontend no visuales para el ecosistema tecnico de Nad.",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -25,10 +25,15 @@
     "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"
+    "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"
+    "typescript": "6.0.3",
+    "vitepress": "^1.6.4"
   },
   "packageManager": "yarn@1.22.22"
 }