@micazoyolli/foundation 0.2.0 → 0.3.0

package/README.md

@@ -1,112 +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
-- 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/
-```
-
-## 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';
+import { cx, getCanonicalUrl } from '@micazoyolli/foundation';
+```
 
-const className = cx('button', isActive && 'button--active');
+SCSS:
 
-if (isElement(event.target)) {
-  event.target.closest('[data-protected-media]');
-}
+```scss
+@use '@micazoyolli/foundation/scss' as foundation;
 ```
 
-SEO/build:
+## Documentacion
 
-```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' }]);
-```
+### Primeros pasos
 
-SCSS:
+- [Getting Started](./docs/getting-started.md)
+- [Installation](./docs/installation.md)
 
-```scss
-@use '@micazoyolli/foundation/scss' as foundation;
+### SCSS
+
+- [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)
+
+### 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.
 
-.section {
-  padding: foundation.$space-6;
-  border-radius: foundation.$radius-md;
+## Que NO incluye
 
-  @include foundation.down(foundation.$breakpoint-md) {
-    padding: foundation.$space-4;
-  }
-}
+- 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, 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
+- 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.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,6 +1,6 @@
 {
   "name": "@micazoyolli/foundation",
-  "version": "0.2.0",
+  "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"