desy-html 15.0.2 → 16.0.0

package/AGENTS.md

@@ -0,0 +1,180 @@
+# AGENTS.md - Developer Guide for desy-html
+
+This file provides guidance for AI agents working on the desy-html codebase.
+
+## Project Overview
+
+desy-html is a design system library for Government of Aragón web applications. It uses:
+- **Vite** - Build tool and dev server
+- **Tailwind CSS v4** - Utility-first CSS framework
+- **Nunjucks** - Templating engine for HTML components
+- **JavaScript** - Vanilla ES modules for ARIA components
+
+## Build Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server with HMR |
+| `npm run build` | Build for production (outputs to `/dist`) |
+| `npm run preview` | Preview production build locally |
+
+### Running a Single Test
+
+**There are no test commands configured** in this project. The codebase does not currently have a test framework (Jest, Vitest, etc.) set up.
+
+## Code Style Guidelines
+
+### JavaScript
+
+- **Use ES Modules**: All JavaScript uses `import`/`export` syntax
+  ```js
+  import { accordion } from './aria/accordion.js';
+  export function accordionComponent(aria) { ... }
+  ```
+
+- **Prefer `const`/`let` over `var`**: Newer code should use `const` by default, `let` for mutable variables
+
+- **Naming Conventions**:
+  - Functions: `camelCase` (e.g., `accordionComponent`, `createFloatingElement`)
+  - Classes/Constructor functions: `PascalCase` (e.g., `TreeGrid`, `MenubarAction`)
+  - Constants: `SCREAMING_SNAKE_CASE`
+  - Files: `kebab-case.js`
+
+- **Component Pattern**: Components follow a factory pattern accepting an `aria` namespace
+  ```js
+  export function accordionComponent(aria) {
+    accordion(aria);
+    // Initialize modules
+  }
+  ```
+
+- **Use strict mode**: Include `'use strict';` in new ARIA/component files
+
+- **Event handling**: Use modern event listeners
+  ```js
+  element.addEventListener('click', (event) => { ... });
+  ```
+
+### Nunjucks Templates
+
+- **File naming**: Use kebab-case with descriptive prefixes
+  - Macros: `_macro.{component}.njk`
+  - Templates: `_template.{component}.njk`
+  - Examples: `_examples.{component}.njk`
+  - Params: `params.{component}.yaml`
+
+- **Macro structure**:
+  ```njk
+  {% macro componentName(params) %}
+  {% include "./_template.component.njk" %}
+  {% endmacro %}
+  ```
+
+- **Parameters**: Define all component parameters in `params.{component}.yaml` files
+
+### CSS / Tailwind CSS
+
+- **Tailwind v4**: Uses `@import "tailwindcss"` and `@theme` for custom properties
+- **Component styles**: Each component has its own `_styles.{component}.css` file
+- **CSS Variables**: Use custom properties for theming
+  ```css
+  :root {
+    --color-primary-base: #00607a;
+    --color-success-base: #24d14c;
+  }
+  ```
+
+- **Class naming**: Follow BEM-like pattern with component prefix `c-`
+  - `.c-accordion__trigger`
+  - `.c-accordion__panel`
+
+### Accessibility (ARIA)
+
+- All components must follow WAI-ARIA patterns
+- Include proper ARIA attributes: `role`, `aria-expanded`, `aria-controls`, `aria-label`, etc.
+- Ensure keyboard navigation support
+- Reference W3C ARIA Authoring Practices when implementing complex components
+
+### Import Conventions
+
+- **Absolute imports** for internal modules (handled by Vite aliases):
+  ```js
+  import { utils } from '@ds/components/utils';
+  ```
+- **Relative imports** for local files:
+  ```js
+  import { accordion } from './aria/accordion.js';
+  ```
+- **External packages**:
+  ```js
+  import "cally";
+  import * as computePosition from '@floating-ui/dom';
+  ```
+
+### Error Handling
+
+- Use `try/catch` for async operations
+- Log meaningful error messages
+- Provide fallback behavior when possible
+
+### Vite Configuration
+
+- **Aliases** defined in `vite.config.js`:
+  - `@` → `src`
+  - `/src` → `src`
+  - `@css` → `src/css`
+  - `@components` → `src/templates/components`
+  - `@ds` → `docs/ds`
+  - `@images` → `public/images`
+
+## Project Structure
+
+```
+desy-html/
+├── src/
+│   ├── css/                    # Global stylesheets
+│   ├── js/                     # JavaScript files
+│   │   ├── aria/               # ARIA component implementations
+│   │   ├── desy-html.js        # Main component exports
+│   │   ├── headroom.min.js    # Headroom.js library
+│   │   └── index.js            # Entry point
+│   ├── templates/
+│   │   ├── components/          # Nunjucks component macros
+│   │   ├── includes/            # Reusable partials
+│   │   └── pages/              # Page templates
+│   ├── main.js                  # Main entry point
+│   └── EUPL-1.2.txt            # License file
+├── docs/                       # Documentation (built to /dist)
+├── public/                     # Static assets
+├── branding/                   # Branding assets
+├── vite.config.js              # Vite configuration
+└── package.json
+```
+
+## Branding
+
+To customize for different organizations:
+1. Edit `branding/branding.config.js` or create `branding/branding.config.{name}.js`
+2. Replace logos in `branding/logos/`
+3. Run `BRANDING_CONFIG={name} npm run build`
+
+## Common Patterns
+
+### Creating a New Component
+
+1. Create `src/templates/components/{name}/_macro.{name}.njk`
+2. Create `src/templates/components/{name}/_template.{name}.njk`
+3. Create `src/templates/components/{name}/_styles.{name}.css`
+4. Create `src/templates/components/{name}/params.{name}.yaml`
+5. Add import to `src/css/styles.css`
+6. Add JS initialization in `src/js/desy-html.js` if needed
+
+### Adding a New ARIA Component
+
+1. Create `src/js/aria/{component}.js` with WAI-ARIA implementation
+2. Export function that accepts `aria` namespace
+3. Register in `src/js/desy-html.js`
+
+## License
+
+This project uses EUPL-1.2 license. See EUPL-1.2.txt for details.

package/README.md

@@ -85,16 +85,34 @@ desy-html/
 ├── src/
 │   ├── css/                   # Stylesheets
 │   ├── js/                    # JavaScript files
-│   └── templates/
-│       ├── components/        # UI component macros
-│       ├── includes/          # Reusable template partials
-│       └── pages/             # Page templates
+│   │   ├── aria/              # ARIA component implementations
+│   │   ├── desy-html.js      # Main component exports
+│   │   ├── headroom.min.js   # Headroom.js library
+│   │   └── index.js          # Entry point
+│   ├── templates/
+│   │   ├── components/        # UI component macros
+│   │   ├── includes/          # Reusable template partials
+│   │   └── pages/             # Page templates
+│   ├── main.js                # Main entry point
+│   └── EUPL-1.2.txt          # License file
 ├── docs/                      # Documentation files
+├── branding/                  # Branding assets and configuration
 ├── vite.config.js             # Vite configuration
 ├── package.json
 └── README.md
 ```
 
+## Branding Customization
+
+desy-html can be customized for different government organizations.
+
+To customize:
+1. Edit `branding/branding.config.js` with your organization's information
+2. Replace logos in `/branding/logos/`
+3. Run `npm run build`
+
+See [branding/BRANDING.md](branding/BRANDING.md) for complete documentation.
+
 ## Styling
 
 ### Using Tailwind CSS

package/TESTING_PLAN.md

@@ -0,0 +1,369 @@
+# Testing Plan for npm Publishing - desy-html
+
+This document defines the complete testing plan to execute before publishing the `desy-html` project to npm. The goal is to verify that all components, the branding system, the build, and interaction work correctly.
+
+---
+
+## 1. Pre-Build Checks
+
+### 1.1. File and Structure Review
+
+- [ ] Verify all required files exist:
+  - `package.json` with correct version, name, exports
+  - `vite.config.js` exists with proper configuration
+  - `branding/branding.config.js` exists with default configuration
+  - `branding/vite-branding-plugin.js` exists
+  - `src/js/index.js` JS entry point
+  - `src/css/styles.css` main stylesheet
+- [ ] Verify logo files exist:
+  - `branding/logos/aragon-compact.svg`
+  - `branding/logos/aragon-expanded.svg`
+  - `branding/logos/aragon-mini.svg`
+  - `branding/logos/eu/logo-eu.svg`
+  - `branding/logos/eu/logo-feder.svg`
+  - `branding/logos/eu/logo-fse.svg`
+  - `branding/logos/eu/logo-feader.svg`
+  - `branding/logos/eu/logo-plurifondo.svg`
+- [ ] Verify background images exist:
+  - `branding/images/header-background.svg`
+  - `branding/images/header-background-lg.svg`
+
+### 1.2. package.json Exports Review
+
+- [ ] Verify `exports["./branding"]` points to `./branding/branding.config.js`
+- [ ] Verify `exports["./branding/plugin"]` points to `./branding/vite-branding-plugin.js`
+- [ ] Verify version in `package.json` is correct
+
+---
+
+## 2. Production Build
+
+### 2.1. Build Execution
+
+- [ ] Run `npm run build` without errors
+- [ ] Verify `dist/` folder is generated
+- [ ] Verify no errors in console output
+
+### 2.2. Generated Files Verification
+
+- [ ] Verify `dist/index.html` exists
+- [ ] Verify `dist/css/styles.css` exists
+- [ ] Verify `dist/js/index.js` (or similar) exists
+- [ ] Verify `dist/images/` contains copied images:
+  - Organization logos (aragon-*.svg)
+  - EU logos (*.svg in subfolder or root)
+  - Background images (header-background*.svg)
+
+### 2.3. Production Paths Verification
+
+- [ ] Verify CSS paths correctly point to `../images/`
+- [ ] Verify HTML image paths correctly point to `../images/`
+- [ ] Verify no references to `/src/` remain in generated files
+- [ ] Verify scripts have correct relative paths
+
+---
+
+## 3. Default Branding Tests
+
+### 3.1. Browser Visual Verification
+
+Using the browser agent, test the following pages:
+
+#### Homepage
+
+- [ ] Load `docs/index.html` (or after build, `dist/index.html`)
+- [ ] Verify organization logo displays (not broken, no 404)
+- [ ] Verify primary colors are Aragón's (#00607a)
+- [ ] Verify typography is correct (Open Sans)
+
+#### Header
+
+- [ ] `docs/examples-header.html` - Verify logo visible
+- [ ] `docs/examples-header.html` - Verify navigation menu
+- [ ] `docs/examples-header-advanced.html` - Verify advanced header
+- [ ] `docs/examples-header-mini.html` - Verify mini header
+
+#### Footer
+
+- [ ] `docs/examples-footer.html` - Verify EU logos visible
+- [ ] `docs/examples-footer.html` - Verify license information
+- [ ] `docs/examples-footer.html` - Verify correct colors
+
+#### Background Images
+
+- [ ] Verify `header-background.svg` displays in header
+- [ ] Verify `header-background-lg.svg` displays on desktop
+
+### 3.2. JavaScript Verification
+
+- [ ] Verify `index.js` loads correctly (no 404 errors)
+- [ ] Verify no JavaScript errors in console
+- [ ] Verify JS modules resolve correctly
+
+### 3.3. Interactive Components
+
+Test each interactive component:
+
+#### Navigation
+
+- [ ] Accordion: `docs/examples-accordion.html` - Open/close items
+- [ ] Tabs: `docs/examples-tabs.html` - Switch between tabs
+- [ ] Modal: `docs/examples-modal.html` - Open/close modal
+- [ ] Dialog: `docs/examples-dialog.html` - Interact with dialog
+- [ ] Tooltip: `docs/examples-tooltip.html` - Show tooltip
+- [ ] Dropdown: `docs/examples-dropdown.html` - Open/close dropdown
+
+#### Forms
+
+- [ ] Input: `docs/examples-input.html` - Write in inputs
+- [ ] Select: `docs/examples-select.html` - Select options
+- [ ] Checkboxes: `docs/examples-checkboxes.html` - Check/uncheck
+- [ ] Radios: `docs/examples-radios.html` - Select option
+- [ ] Toggle: `docs/examples-toggle.html` - Change state
+- [ ] Datepicker: `docs/examples-datepicker.html` - Select date
+
+#### Other Interactive
+
+- [ ] Details/Collapsible: `docs/examples-details.html` / `examples-collapsible.html` - Open/close
+- [ ] Notification: `docs/examples-notification.html` - Close notifications
+- [ ] Pagination: `docs/examples-pagination.html` - Change pages
+- [ ] Menu Horizontal: `docs/examples-menu-horizontal.html` - Navigate menus
+- [ ] Menu Vertical: `docs/examples-menu-vertical.html` - Navigate menus
+- [ ] Menubar: `docs/examples-menubar.html` - Navigate with keyboard
+
+---
+
+## 4. yourorganization Branding Tests
+
+### 4.1. Alternative Configuration Build
+
+- [ ] Run `BRANDING_CONFIG=yourorganization npm run build`
+- [ ] Verify no errors
+
+### 4.2. Visual Verification
+
+- [ ] Verify organization name changes (YourOrganization)
+- [ ] Verify logo changes (yourlogo-*.svg)
+- [ ] Verify typography changes (Inter/Nunito)
+- [ ] Verify color changes (if configured)
+
+### 4.3. EU Logos Verification
+
+- [ ] Verify EU logos display correctly
+- [ ] Verify EU logo paths are correct
+
+---
+
+## 5. Responsive Tests
+
+### 5.1. Mobile Viewport
+
+- [ ] Test with 375px wide viewport
+- [ ] Verify hamburger menu works
+- [ ] Verify compact logo displays
+- [ ] Verify correct background images (header-background.svg)
+
+### 5.2. Tablet Viewport
+
+- [ ] Test with 768px wide viewport
+- [ ] Verify layout changes
+
+### 5.3. Desktop Viewport
+
+- [ ] Test with 1280px wide viewport
+- [ ] Verify expanded logo displays
+- [ ] Verify correct background images (header-background-lg.svg)
+
+---
+
+## 6. Accessibility Tests
+
+### 6.1. Automated Checks
+
+- [ ] No critical accessibility errors in console
+- [ ] Images have alt attribute
+- [ ] Forms have associated labels
+- [ ] Buttons have text or aria-label
+
+### 6.2. Keyboard Navigation
+
+- [ ] Can navigate with Tab through elements
+- [ ] Modals can be closed with Escape
+- [ ] Dropdowns can be opened with Enter/Space
+- [ ] Accordions can be expanded with Enter/Space
+
+---
+
+## 7. Performance Tests
+
+### 7.1. Page Load
+
+- [ ] Page loads without 404 errors
+- [ ] Images exist and load
+- [ ] CSS loads correctly
+- [ ] JS loads correctly
+
+### 7.2. Build Size
+
+- [ ] Minified CSS has no syntax errors
+- [ ] Minified JS has no syntax errors
+
+---
+
+## 8. Plugins and Exports Tests
+
+### 8.1. Exports Verification
+
+- [ ] `branding/branding.config.js` file can be imported
+- [ ] `branding/vite-branding-plugin.js` file can be imported
+- [ ] `brandingPlugin` and `loadBrandingConfig` functions are correctly exported
+
+### 8.2. External Usage Verification
+
+- [ ] Verify plugin can load a configuration
+- [ ] Verify plugin can inject CSS variables
+
+---
+
+## 9. Pages to Test List
+
+### Main Pages
+
+| Page | File | Priority |
+|------|------|----------|
+| Homepage | `index.html` | High |
+| Catalog | `catalogo.html` | High |
+| Components | `componentes.html` | High |
+| Styles | `estilos.html` | Medium |
+
+### Component Examples
+
+| Component | File | Interactive |
+|-----------|------|-------------|
+| Header | `examples-header.html` | No |
+| Header Advanced | `examples-header-advanced.html` | No |
+| Header Mini | `examples-header-mini.html` | No |
+| Footer | `examples-footer.html` | No |
+| Accordion | `examples-accordion.html` | Yes |
+| Alert | `examples-alert.html` | Yes |
+| Breadcrumbs | `examples-breadcrumbs.html` | No |
+| Button | `examples-button.html` | No |
+| Card | `examples-card.html` | No |
+| Checkboxes | `examples-checkboxes.html` | Yes |
+| Collapsible | `examples-collapsible.html` | Yes |
+| Date Input | `examples-date-input.html` | Yes |
+| Datepicker | `examples-datepicker.html` | Yes |
+| Description List | `examples-description-list.html` | No |
+| Details | `examples-details.html` | Yes |
+| Dialog | `examples-dialog.html` | Yes |
+| Dropdown | `examples-dropdown.html` | Yes |
+| Error Message | `examples-error-message.html` | No |
+| Error Summary | `examples-error-summary.html` | Yes |
+| Fieldset | `examples-fieldset.html` | No |
+| File Upload | `examples-file-upload.html` | Yes |
+| Hint | `examples-hint.html` | No |
+| Input | `examples-input.html` | Yes |
+| Input Group | `examples-input-group.html` | Yes |
+| Item | `examples-item.html` | No |
+| Label | `examples-label.html` | No |
+| Links List | `examples-links-list.html` | Yes |
+| Listbox | `examples-listbox.html` | Yes |
+| Media Object | `examples-media-object.html` | No |
+| Menu Horizontal | `examples-menu-horizontal.html` | Yes |
+| Menu Navigation | `examples-menu-navigation.html` | Yes |
+| Menu Vertical | `examples-menu-vertical.html` | Yes |
+| Menubar | `examples-menubar.html` | Yes |
+| Modal | `examples-modal.html` | Yes |
+| Nav | `examples-nav.html` | No |
+| Notification | `examples-notification.html` | Yes |
+| Pagination | `examples-pagination.html` | Yes |
+| Pill | `examples-pill.html` | No |
+| Radios | `examples-radios.html` | Yes |
+| Searchbar | `examples-searchbar.html` | Yes |
+| Select | `examples-select.html` | Yes |
+| Skip Link | `examples-skip-link.html` | No |
+| Spinner | `examples-spinner.html` | No |
+| Status | `examples-status.html` | No |
+| Status Item | `examples-status-item.html` | No |
+| Table | `examples-table.html` | No |
+| Table Advanced | `examples-table-advanced.html` | No |
+| Tabs | `examples-tabs.html` | Yes |
+| Textarea | `examples-textarea.html` | Yes |
+| Toggle | `examples-toggle.html` | Yes |
+| Tooltip | `examples-tooltip.html` | Yes |
+| Tree | `examples-tree.html` | Yes |
+| Treegrid | `examples-treegrid.html` | Yes |
+
+### Templates
+
+| Template | File |
+|----------|------|
+| Logged with fixed header | `plantilla-logueado-con-cabecera-fija.html` |
+| Logged with app selector | `plantilla-logueado-con-selector-de-app.html` |
+| Logged with app title | `plantilla-logueado-con-titulo-de-app.html` |
+| Not logged in | `plantilla-sin-loguear.html` |
+| With advanced header | `plantilla-con-header-advanced.html` |
+
+---
+
+## 10. Execution Commands
+
+### Environment Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Production build with default branding
+npm run build
+
+# Production build with yourorganization branding
+BRANDING_CONFIG=yourorganization npm run build
+
+# Start preview server
+npm run preview
+
+# Start development server
+npm run dev
+
+# Start development server with yourorganization branding
+npm run dev:yourorganization
+```
+
+### Browser Agent Test Execution
+
+1. Build the project: `npm run build`
+2. Start preview: `npm run preview`
+3. Use browser agent to navigate through listed pages
+4. Verify visual elements, images, and console errors
+
+---
+
+## 11. Success Criteria
+
+The project is ready for npm publishing when:
+
+- [ ] Build runs without errors
+- [ ] All required files are in `dist/`
+- [ ] Production paths are correct
+- [ ] Default branding works correctly
+- [ ] yourorganization branding works correctly
+- [ ] Organization logos display correctly
+- [ ] EU logos display correctly
+- [ ] Header background images display correctly
+- [ ] All interactive components work correctly
+- [ ] No 404 errors in console
+- [ ] No JavaScript errors in console
+- [ ] Responsive design works correctly
+- [ ] npm exports work correctly
+- [ ] Keyboard navigation works on interactive components
+
+---
+
+## 12. Additional Notes
+
+- This testing plan covers 50+ example pages
+- Tests 20+ interactive components
+- Verifies complete branding system (default and yourorganization)
+- Verifies all resource paths (images, CSS, JS)
+- Verifies basic accessibility and keyboard navigation