desy-html 15.0.0-beta.1 → 15.0.0

package/README.md

@@ -1,30 +1,185 @@
-# README #
+# desy-html
 
-desy-html is the NPM library you need to start building a user interface for Gobierno de Aragón webapps. It uses Vite, Tailwindcss and Nunjucks to render html+css+js components. It's useful to create lightweight webapps or html mockups.
+![Node Version](https://img.shields.io/badge/node-%3E%3D20.19.2%20%3C23.0.0-blue.svg)
+![npm Version](https://img.shields.io/badge/npm-%3E%3D10.0.0-blue.svg)
+[![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-yellow.svg)](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12)
 
-If you need a more powerful library based on this, use it's Angular port instead: [desy-angular](https://bitbucket.org/sdaragon/desy-angular)
+An NPM library for building user interfaces for Government of Aragón web applications. It uses Vite, Tailwind CSS and Nunjucks to render HTML+CSS+JS components. It's useful to create lightweight webapps or HTML mockups.
 
-See live examples of desy-html components: [https://desy.aragon.es/](https://desy.aragon.es/)
+## Overview
 
-### How to set up? ###
+**desy-html** is the core design system library that provides:
 
-* Run `npm install` first.
-* Use `npm run dev` to listen to changes in njk, css and html, and browser-sync reload.
-* Use `npm run build` to generate static files.
-* Dependencies: Node.js v22, Tailwind CSS
+- **Vite** - Fast build tool and development server with hot module replacement
+- **Tailwind CSS v4** - Utility-first CSS framework
+- **Nunjucks** - Powerful templating engine for generating HTML
+- **Sharp** - Image optimization for production builds
+- **Accessible Components** - Pre-built UI components following ARIA patterns
 
-### How do I start a project that uses desy-html components? ###
+If you need a more powerful library based on this, use its Angular port instead: [desy-angular](https://bitbucket.org/sdaragon/desy-angular)
 
-To start a new project that uses desy-html as dependency, don't use this repo, use **desy-html-starter** repo instead.
+## Quick Links
 
-  * Download the desy-html-starter project from here: [https://bitbucket.org/sdaragon/desy-html-starter](https://bitbucket.org/sdaragon/desy-html-starter)
-  * Personalize the downloaded project for your needings.
-  * You'll be able to use any desy-html component in that project. Copy any macro example code from here and paste it inside any page, include or component in your project.
+- **Documentation:** [https://desy.aragon.es/](https://desy.aragon.es/)
+- **Repository:** [https://bitbucket.org/sdaragon/desy-html/](https://bitbucket.org/sdaragon/desy-html/)
+- **Starter Project:** [https://bitbucket.org/sdaragon/desy-html-starter/](https://bitbucket.org/sdaragon/desy-html-starter/)
 
-### Contact the team ###
+## How do I start a project that uses desy-html components?
 
-* desy-html is maintained by a team at SDA Servicios Digitales de Aragón (Spain). If you want to know more about desy-html, please email any of the commiters.
+To start a new project that uses desy-html as dependency, **don't use this repo**, use the **desy-html-starter** repo instead:
 
-### Software license ###
-Unless stated otherwise, the codebase is released under the [EUPL-1.2 License](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12). This covers both the codebase and any sample code in the documentation.
+1. Download the desy-html-starter project from [https://bitbucket.org/sdaragon/desy-html-starter](https://bitbucket.org/sdaragon/desy-html-starter)
+2. Personalize the downloaded project for your needs
+3. You'll be able to use any desy-html component in that project
 
+## Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+- **Node.js** >=20.19.2 <23.0.0
+- **npm** >=10.0.0
+
+## Getting Started
+
+### 1. Clone the Repository
+
+```sh
+git clone https://bitbucket.org/sdaragon/desy-html.git
+cd desy-html
+```
+
+### 2. Install Dependencies
+
+```sh
+npm install
+```
+
+### 3. Start Development Server
+
+```sh
+npm run dev
+```
+
+This starts the Vite development server with hot module replacement. Open your browser at the URL displayed in the terminal output.
+
+### 4. Build for Production
+
+```sh
+npm run build
+```
+
+This compiles HTML, purges and minifies CSS, and optimizes JavaScript into the `/dist` folder.
+
+### 5. Preview Production Build
+
+```sh
+npm run preview
+```
+
+## Project Structure
+
+```
+desy-html/
+├── public/
+│   └── images/                # Library images
+├── src/
+│   ├── css/                   # Stylesheets
+│   ├── js/                    # JavaScript files
+│   └── templates/
+│       ├── components/        # UI component macros
+│       ├── includes/          # Reusable template partials
+│       └── pages/             # Page templates
+├── docs/                      # Documentation files
+├── vite.config.js             # Vite configuration
+├── package.json
+└── README.md
+```
+
+## Styling
+
+### Using Tailwind CSS
+
+The project uses Tailwind CSS v4. All Tailwind utility classes are available in your templates:
+
+```html
+<div class="flex items-center gap-4 p-6 bg-white rounded-lg shadow">
+  <h1 class="text-2xl font-bold text-gray-900">Hello World</h1>
+</div>
+```
+
+### Theme Variables
+
+desy-html provides CSS custom properties (variables) for consistent theming. These are included in the main [stylesheet](https://bitbucket.org/sdaragon/desy-html/src/master/src/css/styles.css).
+
+## Images
+
+### Image Structure
+
+Images are stored in `public/images/` and can be referenced in templates using the `/images/` path:
+
+```html
+<img src="/images/my-image.png" alt="Description">
+```
+
+### Image Optimization
+
+During production builds, images are automatically optimized using Sharp:
+
+- Supported formats: jpg, png, webp, avif
+- File sizes are optimized for production
+
+## Development Tips
+
+### Hot Module Replacement
+
+The development server supports HMR. Changes to CSS, JavaScript, and templates will automatically refresh in the browser.
+
+### Debugging
+
+- Check the browser console for JavaScript errors
+- Use the Vite terminal output for build errors
+- Inspect generated HTML in browser developer tools
+
+## Scripts Reference
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server with HMR |
+| `npm run build` | Build for production |
+| `npm run preview` | Preview production build locally |
+
+## Accessibility
+
+All desy-html components are built with accessibility in mind:
+
+- Proper ARIA attributes and roles
+- Keyboard navigation support
+- Screen reader compatibility
+- Focus management
+
+## Browser Support
+
+The project targets modern browsers. For specific compatibility information, refer to the [desy documentation](https://desy.aragon.es/).
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Contact the Team
+
+desy-html is maintained by a team at SDA Servicios Digitales de Aragón (Spain). If you want to know more about desy-html, please email any of the commiters.
+
+## Author
+
+**SDA Servicios Digitales de Aragón**
+
+## License
+
+This project is licensed under the [EUPL-1.2](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12) license.
+
+---
+
+For more information and detailed component documentation, visit [https://desy.aragon.es/](https://desy.aragon.es/)

package/attached_assets/Pasted--desy-html-starter-Node-Version-https-img-shields-io-ba_1765448923362.txt

@@ -0,0 +1,431 @@
+# desy-html-starter
+
+![Node Version](https://img.shields.io/badge/node-%5E22.0.0-blue.svg)
+![npm Version](https://img.shields.io/badge/npm-%5E10.0.0-blue.svg)
+[![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-yellow.svg)](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12)
+
+A starter project for building user interfaces for Government of Aragón web applications using the **desy-html** design system library.
+
+## Overview
+
+**desy-html-starter** provides a pre-configured environment with all the dependencies needed to build accessible, consistent web applications using the desy-html component library. It includes:
+
+- **Vite** - Fast build tool and development server with hot module replacement
+- **Tailwind CSS v4** - Utility-first CSS framework
+- **Nunjucks** - Powerful templating engine for generating HTML
+- **Sharp** - Image optimization for production builds
+- **Accessible Components** - Pre-built UI components following ARIA patterns
+
+## Quick Links
+
+- **Documentation:** [https://desy.aragon.es/](https://desy.aragon.es/)
+- **Repository:** [https://bitbucket.org/sdaragon/desy-html-starter/](https://bitbucket.org/sdaragon/desy-html-starter/)
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+- **Node.js** ^22.0.0
+- **npm** ^10.0.0
+
+## Getting Started
+
+### 1. Clone or Fork the Repository
+
+```sh
+git clone https://bitbucket.org/sdaragon/desy-html-starter.git my-project
+cd my-project
+```
+
+### 2. Install Dependencies
+
+```sh
+npm install
+```
+
+### 3. Start Development Server
+
+```sh
+npm run dev
+```
+
+This starts the Vite development server with hot module replacement. Open your browser at the URL displayed in the terminal output.
+
+### 4. Build for Production
+
+```sh
+npm run build
+```
+
+This compiles HTML, purges and minifies CSS, and optimizes JavaScript into the `/dist` folder.
+
+### 5. Preview Production Build
+
+```sh
+npm run preview
+```
+
+## Project Structure
+
+```
+desy-html-starter/
+├── public/
+│   └── images/                # Project images (override desy-html images here)
+├── src/
+│   ├── css/
+│   │   ├── styles.css         # Main stylesheet (imports desy-html styles)
+│   │   └── custom.css         # Your custom project styles
+│   ├── js/
+│   │   └── index.js           # JavaScript entry point (component initialization)
+│   └── templates/
+│       ├── components/        # Custom project components
+│       ├── includes/          # Reusable template partials
+│       └── pages/             # Page templates
+├── vite.config.js             # Vite configuration
+├── package.json
+└── README.md
+```
+
+## Working with Components
+
+### Using desy-html Components
+
+Find component examples on [desy.aragon.es](https://desy.aragon.es) such as [this button component](https://desy.aragon.es/componente-botones-codigo.html). Copy the Nunjucks code and paste it into your template's content area.
+
+Components are available as Nunjucks macros. Import and use them in your templates:
+
+```njk
+{% from "components/button/_macro.button.njk" import componentButton %}
+
+{{ componentButton({
+  "text": "Transparent",
+  "classes": "c-button--transparent"
+}) }}
+```
+
+### Available Components
+
+The desy-html library includes many [accessible components](https://desy.aragon.es/componentes.html):
+
+- **Navigation:** Menu, Menubar, Nav, Tabs
+- **Forms:** Checkbox, Radio Button, Listbox, Datepicker, Toggle
+- **Feedback:** Alert, Notification, Dialog, Tooltip
+- **Layout:** Accordion, Collapsible, Tree, Treegrid
+- **Data:** Table Advanced, Dropdown
+
+## Styling
+
+### Using Tailwind CSS
+
+The project uses Tailwind CSS v4. All Tailwind utility classes are available in your templates:
+
+```html
+<div class="flex items-center gap-4 p-6 bg-white rounded-lg shadow">
+  <h1 class="text-2xl font-bold text-gray-900">Hello World</h1>
+</div>
+```
+
+### Adding Custom Styles
+
+Add your project-specific styles in `src/css/custom.css`:
+
+```css
+/* src/css/custom.css */
+.my-custom-class {
+  /* Your custom styles */
+}
+```
+
+### Theme Variables
+
+desy-html provides CSS custom properties (variables) for consistent theming. These are automatically included when you import the main [stylesheet](https://bitbucket.org/sdaragon/desy-html/src/master/src/css/styles.css).
+
+## Templates
+
+### Page Templates
+
+Create new pages by extending the base layouts. Several templates are provided:
+
+| Template | Description |
+|----------|-------------|
+| `plantilla-sin-loguear.html` | Public pages (not logged in) |
+| `plantilla-logueado-con-cabecera-fija.html` | Logged-in pages with fixed header |
+| `plantilla-logueado-con-selector-de-app.html` | Logged-in with app selector |
+| `plantilla-con-header-advanced.html` | Advanced header layout |
+
+### Creating Custom Components
+
+Custom components follow a consistent file structure. Create a new folder in `src/templates/components/` with the following files:
+
+```
+src/templates/components/my-component/
+├── _macro.my-component.njk        # Exports the macro (entry point)
+├── _template.my-component.njk     # HTML template with the component markup
+├── _examples.my-component.njk     # Example data for testing/documentation
+└── params.my-component.yaml       # Parameter documentation
+```
+
+#### Step 1: Create the Macro File
+
+The macro file exports your component and includes the template:
+
+```njk
+{# _macro.my-component.njk #}
+{% macro componentMyComponent(params) %}
+{% include "./_template.my-component.njk" %}
+{% endmacro %}
+```
+
+#### Step 2: Create the Template File
+
+The template contains the actual HTML markup. Use the `params` object to access component properties:
+
+```njk
+{# _template.my-component.njk #}
+<div {%- if params.classes %} class="{{ params.classes }}"{% endif %}
+{%- for attribute, value in params.attributes %} {{attribute}}="{{value}}"{% endfor %}>
+  {{ params.html | safe if params.html else params.text }}
+</div>
+```
+
+#### Step 3: Define Examples (Optional)
+
+Examples help document component usage and can be used for testing:
+
+```njk
+{# _examples.my-component.njk #}
+{% set exampleComponent = "my-component" %}
+{% set examples = [
+  {
+    "name": "default",
+    "data": {
+      "text": "This is my component"
+    }
+  },
+  {
+    "name": "with html",
+    "data": {
+      "html": "This is <strong class=\"font-bold\">my component</strong>"
+    }
+  }
+] %}
+```
+
+#### Step 4: Document Parameters (Optional)
+
+The YAML file documents available parameters for the component:
+
+```yaml
+# params.my-component.yaml
+params:
+- name: text
+  type: string
+  required: true
+  description: Text content for the component. Ignored if `html` is provided.
+- name: html
+  type: string
+  required: false
+  description: HTML content for the component. Takes priority over `text`.
+- name: classes
+  type: string
+  required: false
+  description: CSS classes to add to the component.
+- name: attributes
+  type: object
+  required: false
+  description: HTML attributes (e.g., data attributes) to add to the component.
+```
+
+#### Using Your Component
+
+Import and use your component in any template. The project configures Nunjucks to resolve paths from `src/templates/`, so use the `components/` prefix:
+
+```njk
+{% from "components/my-component/_macro.my-component.njk" import componentMyComponent %}
+
+{{ componentMyComponent({
+  text: "Hello world",
+  classes: "text-lg text-gray-700"
+}) }}
+```
+
+#### Components with Nested Content (Caller)
+
+For components that need to accept nested content, use Nunjucks' `call` block pattern:
+
+```njk
+{# _template.my-container.njk #}
+<div class="container">
+  <p>{{ params.text }}</p>
+  {% if caller %}
+    {{ caller() }}
+  {% elseif params.caller %}
+    {{ params.caller | safe }}
+  {% endif %}
+</div>
+```
+
+Usage with `call` block:
+
+```njk
+{% call componentMyContainer({ text: "Container title" }) %}
+  <p>This nested content appears inside the container.</p>
+  <button>Click me</button>
+{% endcall %}
+```
+
+### Using Includes
+
+Includes are reusable template fragments that can be inserted into multiple pages. Unlike components (which receive parameters), includes are static snippets that can import and use components internally.
+
+#### Creating an Include
+
+Create include files in `src/templates/includes/` with names starting with underscore:
+
+```
+src/templates/includes/
+└── _my-include.njk
+```
+
+Example include file:
+
+```njk
+{# _my-include.njk #}
+{% from "components/test-component/_macro.test-component.njk" import componentTestComponent %}
+
+<div class="p-base border border-neutral-base">
+  <p>This is reusable content</p>
+  {{ componentTestComponent({
+    "text": "A component inside the include"
+  }) }}
+</div>
+```
+
+#### Using an Include
+
+Insert an include into any page or template with the `{% include %}` tag:
+
+```njk
+{% include "includes/_my-include.njk" %}
+```
+
+#### When to Use Includes vs Components
+
+| Use Case | Includes | Components |
+|----------|----------|------------|
+| Static, repeated content | Yes | No |
+| Configurable, reusable UI elements | No | Yes |
+| Content that needs parameters | No | Yes |
+| Quick content reuse without configuration | Yes | No |
+
+## Images
+
+### Image Inheritance System
+
+This project uses an image inheritance system that allows you to use images from the desy-html library while also being able to override them with your own:
+
+1. **Base images** come from `node_modules/desy-html/public/images/`
+2. **Project images** in `public/images/` override base images with the same name
+
+### Adding Project Images
+
+Place your images in `public/images/`. Reference them in templates using the `/images/` path:
+
+```html
+<img src="/images/my-image.png" alt="Description">
+```
+
+### Overriding desy-html Images
+
+To replace a desy-html image with your own version, simply place a file with the same name in `public/images/`. Your image will take priority.
+
+### Using Images in CSS
+
+For background images in your custom CSS, use the `/images/` path:
+
+```css
+.my-element {
+  background-image: url('/images/my-background.png');
+}
+```
+
+### Image Optimization
+
+During production builds, images are automatically optimized using Sharp:
+
+- Images from both desy-html and your project are processed
+- Supported formats: jpg, png, webp, avif
+- File sizes are optimized for production
+- Paths are automatically adjusted for the dist folder
+
+## Development Tips
+
+### Hot Module Replacement
+
+The development server supports HMR. Changes to CSS, JavaScript, and templates will automatically refresh in the browser.
+
+### Nunjucks Template Syntax
+
+```njk
+{# Comments #}
+{% set variable = "value" %}
+{{ variable }}
+
+{% if condition %}
+  ...
+{% endif %}
+
+{% for item in items %}
+  {{ item }}
+{% endfor %}
+
+{% include "includes/_partial.njk" %}
+```
+
+### Debugging
+
+- Check the browser console for JavaScript errors
+- Use the Vite terminal output for build errors
+- Inspect generated HTML in browser developer tools
+
+## Scripts Reference
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server with HMR |
+| `npm run build` | Build for production |
+| `npm run preview` | Preview production build locally |
+
+## Accessibility
+
+All desy-html components are built with accessibility in mind:
+
+- Proper ARIA attributes and roles
+- Keyboard navigation support
+- Screen reader compatibility
+- Focus management
+
+When creating custom components, follow the same accessibility patterns.
+
+## Browser Support
+
+The project targets modern browsers. For specific compatibility information, refer to the [desy documentation](https://desy.aragon.es/).
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Author
+
+**SDA Servicios Digitales de Aragón**
+
+## License
+
+This project is licensed under the [EUPL-1.2](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12) license.
+
+---
+
+For more information and detailed component documentation, visit [https://desy.aragon.es/](https://desy.aragon.es/)

package/docs/index.html

@@ -5,37 +5,145 @@
 {% block contentBlock %}
 
 <div class="prose pb-xl">
-<div class="pb-lg"></div>
+<div class="pb-lg"> </div>
   <h1>desy-html</h1>
   <p>Versión: {{ '' | filterversion }}</p>
-  <p>desy-html es una librería NPM que sirve para construir la interfaz de usuario de las aplicaciones web del Gobierno de Aragón. Utiliza <a href="https://vite.dev/">Vite</a>, <a href="https://tailwindcss.com/">Tailwind CSS</a> y <a href="https://mozilla.github.io/nunjucks/">Nunjucks</a> para renderizar componentes HTML+CSS+JS. Es útil para crear aplicaciones web ligeras o maquetas html.</p>
-  <p>Si necesitas una librería con más potencia para construir tu aplicación web, te recomendamos mejor, que uses su versión traducida a Angular: <a href="https://bitbucket.org/sdaragon/desy-angular">desy-angular librería NPM</a>, <a href="https://desy.aragon.es/desy-angular">Ejemplos de desy-angular</a></p>
-  <p>Mira ejemplos de componentes y plantillas de página en la documentación: <a href="https://desy.aragon.es/">https://desy.aragon.es/</a></p>
+  <p>Una librería NPM para construir interfaces de usuario para aplicaciones web del Gobierno de Aragón. Utiliza <a href="https://vite.dev/">Vite</a>, <a href="https://tailwindcss.com/">Tailwind CSS</a> y <a href="https://mozilla.github.io/nunjucks/">Nunjucks</a> para renderizar componentes HTML+CSS+JS. Es útil para crear aplicaciones web ligeras o maquetas HTML.</p>
 
-  <h2>¿Cómo comenzar?</h2>
+  <h2>Descripción general</h2>
+  <p><strong>desy-html</strong> es la librería del sistema de diseño principal que proporciona:</p>
   <ul>
-    <li>Ejecuta primero <code>npm install</code></li>
-    <li>Ejecuta <code>npm run dev</code> para escuchar cambios en los archivos njk, css y html, para renderizarlos y recargar el servidor local.</li>
-    <li>Usa <code>npm run build</code> para generar los archivos html estáticos, el CSS y minificarlo.</li>
-    <li>Dependencias: Node.js v22, Vite y Tailwind CSS. Versión y lista de dependencias completa en: <a href="package.json">Ver package.json</a></li>
+    <li><strong>Vite</strong> - Herramienta de compilación rápida y servidor de desarrollo con reemplazo de módulo en caliente</li>
+    <li><strong>Tailwind CSS v4</strong> - Framework CSS basado en utilidades</li>
+    <li><strong>Nunjucks</strong> - Motor de plantillas potente para generar HTML</li>
+    <li><strong>Sharp</strong> - Optimización de imágenes para compilaciones de producción</li>
+    <li><strong>Componentes Accesibles</strong> - Componentes UI preconstruidos siguiendo patrones ARIA</li>
+  </ul>
+  <p>Si necesitas una librería más potente basada en esta, usa su versión de Angular en su lugar: <a href="https://bitbucket.org/sdaragon/desy-angular">desy-angular</a></p>
+
+  <h2>Enlaces rápidos</h2>
+  <ul>
+    <li><strong>Documentación:</strong> <a href="https://desy.aragon.es/">https://desy.aragon.es/</a></li>
+    <li><strong>Repositorio:</strong> <a href="https://bitbucket.org/sdaragon/desy-html/">https://bitbucket.org/sdaragon/desy-html/</a></li>
+    <li><strong>Proyecto Starter:</strong> <a href="https://bitbucket.org/sdaragon/desy-html-starter/">https://bitbucket.org/sdaragon/desy-html-starter/</a></li>
   </ul>
 
   <h2>¿Cómo comienzo un proyecto que usa los componentes de desy-html?</h2>
-  <p>Para comenzar un nuevo proyecto que usa desy-html como dependencia, no uses este repositorio, usa mejor <strong>desy-html-starter</strong>.</p>
+  <p>Para comenzar un nuevo proyecto que usa desy-html como dependencia, <strong>no uses este repositorio</strong>, usa el repositorio <strong>desy-html-starter</strong> en su lugar:</p>
+  <ol>
+    <li>Descarga el proyecto desy-html-starter desde <a href="https://bitbucket.org/sdaragon/desy-html-starter">https://bitbucket.org/sdaragon/desy-html-starter</a></li>
+    <li>Personaliza el proyecto descargado según tus necesidades</li>
+    <li>Podrás usar cualquier componente de desy-html en ese proyecto</li>
+  </ol>
+
+  <h2>Requisitos previos</h2>
+  <p>Antes de comenzar, asegúrate de tener instalado lo siguiente:</p>
   <ul>
-    <li>Descarga el proyecto desy-html-starter desde su repositorio: <a href="https://bitbucket.org/sdaragon/desy-html-starter">https://bitbucket.org/sdaragon/desy-html-starter</a></li>
-    <li>Personaliza el proyecto descargado según tus necesidades (cambia el nombre y rutas).</li>
-    <li>Podrás usar cualquier componente de desy-html en ese proyecto. Copia cualquier ejemplo de macro desde la <a href="https://desy.aragon.es/desy-html">documentación de desy-html</a> y pégalo dentro de tu página, include o componente del nuevo proyecto.</li>
+    <li><strong>Node.js</strong> >=20.19.2 <23.0.0</li>
+    <li><strong>npm</strong> >=10.0.0</li>
   </ul>
 
+  <h2>Primeros pasos</h2>
+  <h3>1. Clonar el repositorio</h3>
+  <pre><code>git clone https://bitbucket.org/sdaragon/desy-html.git
+cd desy-html</code></pre>
+
+  <h3>2. Instalar dependencias</h3>
+  <pre><code>npm install</code></pre>
+
+  <h3>3. Iniciar el servidor de desarrollo</h3>
+  <pre><code>npm run dev</code></pre>
+  <p>Esto inicia el servidor de desarrollo de Vite con reemplazo de módulo en caliente. Abre tu navegador en la URL mostrada en la salida del terminal.</p>
+
+  <h3>4. Compilar para producción</h3>
+  <pre><code>npm run build</code></pre>
+  <p>Esto compila HTML, purga y minifica CSS, y optimiza JavaScript en la carpeta `/dist`.</p>
+
+  <h3>5. Previsualizar la compilación de producción</h3>
+  <pre><code>npm run preview</code></pre>
+
+  <h2>Estilos</h2>
+  <h3>Usando Tailwind CSS</h3>
+  <p>El proyecto utiliza Tailwind CSS v4. Todas las clases de utilidad de Tailwind están disponibles en tus plantillas.</p>
+
+  <h3>Variables de tema</h3>
+  <p>desy-html proporciona propiedades CSS personalizadas (variables) para una temática consistente. Estos se incluyen en la <a href="https://bitbucket.org/sdaragon/desy-html/src/master/src/css/styles.css">hoja de estilos principal</a>.</p>
+
+  <h2>Imágenes</h2>
+  <h3>Estructura de imágenes</h3>
+  <p>Las imágenes se almacenan en `public/images/` y se pueden referenciar en plantillas usando la ruta `/images/`:</p>
+  <pre><code>&lt;img src="/images/my-image.png" alt="Description"&gt;</code></pre>
+
+  <h3>Optimización de imágenes</h3>
+  <p>Durante las compilaciones de producción, las imágenes se optimizan automáticamente usando Sharp:</p>
+  <ul>
+    <li>Formatos compatibles: jpg, png, webp, avif</li>
+    <li>Los tamaños de archivo se optimizan para producción</li>
+  </ul>
+
+  <h2>Consejos de desarrollo</h2>
+  <h3>Reemplazo de módulo en caliente</h3>
+  <p>El servidor de desarrollo admite HMR. Los cambios en CSS, JavaScript y plantillas se actualizarán automáticamente en el navegador.</p>
+
+  <h3>Depuración</h3>
+  <ul>
+    <li>Comprueba la consola del navegador para ver errores de JavaScript</li>
+    <li>Usa la salida del terminal de Vite para errores de compilación</li>
+    <li>Inspecciona el HTML generado en las herramientas de desarrollo del navegador</li>
+  </ul>
+
+  <h2>Referencia de scripts</h2>
+  <table>
+    <thead>
+      <tr>
+        <th>Comando</th>
+        <th>Descripción</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>npm run dev</code></td>
+        <td>Inicia el servidor de desarrollo con HMR</td>
+      </tr>
+      <tr>
+        <td><code>npm run build</code></td>
+        <td>Compila para producción</td>
+      </tr>
+      <tr>
+        <td><code>npm run preview</code></td>
+        <td>Previsualiza la compilación de producción localmente</td>
+      </tr>
+    </tbody>
+  </table>
+
+  <h2>Accesibilidad</h2>
+  <p>Todos los componentes de desy-html están construidos teniendo en cuenta la accesibilidad:</p>
+  <ul>
+    <li>Atributos y roles ARIA adecuados</li>
+    <li>Soporte de navegación por teclado</li>
+    <li>Compatibilidad con lectores de pantalla</li>
+    <li>Gestión del enfoque</li>
+  </ul>
+
+  <h2>Soporte de navegadores</h2>
+  <p>El proyecto está dirigido a navegadores modernos. Para obtener información específica sobre compatibilidad, consulta la <a href="https://desy.aragon.es/">documentación de desy</a>.</p>
+
+  <h2>Contribuciones</h2>
+  <ol>
+    <li>Haz un fork del repositorio</li>
+    <li>Crea una rama de características</li>
+    <li>Realiza tus cambios</li>
+    <li>Envía una solicitud de extracción</li>
+  </ol>
+
   <h2>Contacta con el equipo</h2>
   <p>desy-html está mantenido por un equipo de SDA Servicios Digitales de Aragón (España). Si quieres saber más acerca de desy-html, puedes escribir por email a alguno de los commiters.</p>
 
-  <h2>Licencia del software</h2>
-  <p>A no ser que se indique lo contrario, la base de código está liberada bajo la licencia abierta <a href="https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12">EUPL-1.2 License</a>. Esto cubre tanto la base de código como cualquier ejemplo en la documentación. <a href="EUPL-1.2.txt">Lee la licencia</a>.</p>
+  <h2>Autor</h2>
+  <p><strong>SDA Servicios Digitales de Aragón</strong></p>
 
-  <h2>Descarga el código fuente</h2>
-  <p>El código de este proyecto está publicado en un repositorio público de Bitbucket. Puedes hacer un fork o descargarlo desde aqui: <a href="https://bitbucket.org/sdaragon/desy-html">https://bitbucket.org/sdaragon/desy-html/</a></p>
+  <h2>Licencia del software</h2>
+  <p>Este proyecto está licenciado bajo la licencia <a href="https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12">EUPL-1.2</a>. <a href="EUPL-1.2.txt">Lee la licencia</a>.</p>
 
   <h2>Changelog (English)</h2>
   <p>What's new in the latest version of desy-html</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "desy-html",
-  "version": "15.0.0-beta.1",
+  "version": "15.0.0",
   "description": "desy-html contains the code you need to start building a user interface for Gobierno de Aragón government webapps.",
   "type": "module",
   "author": {
@@ -21,8 +21,8 @@
   },
   "homepage": "https://desy.aragon.es/",
   "engines": {
-    "node": "^22.0.0",
-    "npm": "^10.0.0"
+    "node": ">=20.19.2 <23.0.0",
+    "npm": ">=10.0.0"
   },
   "scripts": {
     "dev": "vite",

package/replit.md

@@ -0,0 +1,75 @@
+# desy-html
+
+## Overview
+
+desy-html is an NPM library that provides a design system for building user interfaces for Government of Aragón (Spain) web applications. It delivers pre-built, accessible UI components using Vite as the build tool, Tailwind CSS v4 for styling, and Nunjucks as the templating engine. The library is designed to be consumed as a dependency through a separate starter project (desy-html-starter) rather than used directly.
+
+The project serves as the core component library and documentation site, providing reusable HTML+CSS+JS components that follow ARIA accessibility patterns for government web applications.
+
+## User Preferences
+
+Preferred communication style: Simple, everyday language.
+
+## System Architecture
+
+### Build System
+- **Vite** serves as the primary build tool and development server, providing fast hot module replacement during development
+- Build configuration in `vite.config.js` includes custom Nunjucks environment setup, HTML beautification with js-beautify, YAML parsing for component parameters, and image optimization with Sharp
+- Three npm scripts: `dev` (development server), `build` (production build), `preview` (preview production build)
+
+### Templating Architecture
+- **Nunjucks** templating engine generates HTML components with a macro-based component system
+- Components follow a consistent file structure pattern: `src/templates/components/{component-name}/` containing macros, examples, and YAML parameter definitions
+- Page templates use inheritance with base templates in `src/templates/pages/` for different layout configurations (logged-in, logged-out, with sidebar, fixed header, etc.)
+- Documentation pages in `docs/` directory extend templates and import component examples
+
+### Styling System
+- **Tailwind CSS v4** with `@tailwindcss/vite` plugin integration
+- Custom theme configuration in `src/css/styles.css` defining colors, breakpoints, and spacing tokens aligned with government branding
+- Component-specific CSS files using Tailwind's `@layer components` directive (e.g., `component.text.css`, `component.form-group.css`)
+- Typography plugin (`@tailwindcss/typography`) and forms plugin (`@tailwindcss/forms`) for enhanced styling
+
+### JavaScript Architecture
+- ES modules architecture with component-specific ARIA implementations in `src/js/aria/`
+- Central initialization in `src/js/index.js` that imports and initializes all interactive components
+- Components implement W3C ARIA Authoring Practices for accessibility (accordion, dialog, listbox, menubar, tabs, tree, etc.)
+- Uses `@floating-ui/dom` for tooltip and dropdown positioning
+- Includes `cally` library for calendar/datepicker functionality
+- Optional `headroom.js` integration for auto-hiding headers on scroll
+
+### Component Library
+- 50+ pre-built accessible components including: accordion, alert, button, card, checkboxes, datepicker, dialog, dropdown, fieldset, file-upload, header/footer, input variants, menus, modal, notification, pagination, select, tabs, table, tooltip, tree, and more
+- Each component has a Nunjucks macro for rendering, YAML file for parameter documentation, and example file
+- Components are designed to be copied from documentation and used in projects via the starter template
+
+## External Dependencies
+
+### Runtime Dependencies
+- `@floating-ui/dom` - Positioning library for tooltips and dropdowns
+- `@tailwindcss/vite` - Vite plugin for Tailwind CSS v4
+- `tailwindcss` - Utility-first CSS framework (v4)
+- `autoprefixer` - CSS vendor prefixing
+- `cally` - Calendar/datepicker web component
+- `chokidar` - File watching for development
+- `hex-rgb` - Color conversion utility
+- `js-yaml` - YAML parsing for component parameters
+
+### Development Dependencies
+- `vite` - Build tool and dev server
+- `nunjucks` - Templating engine
+- `sharp` - Image optimization for production builds
+- `highlight.js` - Code syntax highlighting in documentation
+- `js-beautify` - HTML formatting for documentation examples
+- `glob` - File pattern matching
+- `outdent` - Template literal dedenting
+- `@tailwindcss/forms` - Form element styling plugin
+- `@tailwindcss/typography` - Prose content styling plugin
+
+### External Resources
+- Documentation hosted at https://desy.aragon.es/
+- Starter project available at https://bitbucket.org/sdaragon/desy-html-starter/
+- Angular port available at https://bitbucket.org/sdaragon/desy-angular
+
+### System Requirements
+- Node.js ^22.0.0
+- npm ^10.0.0

package/src/templates/components/tree/_examples.tree.njk

@@ -981,93 +981,6 @@
       ]
     }
   },
-  {
-    "name": "con un texto de item muy largo",
-    "data": {
-      "name": "with-very-long-option-text",
-      "classes": "mt-base",
-      "fieldset": {
-        "legend": {
-          "text": "Selecciona organismo"
-        }
-      },
-      "hint": {
-        "text": "Selecciona el organismo al que perteneces."
-      },
-      "idPrefix": "with-very-long-option-text",
-      "items": [
-        {
-          "text": "Nullam id dolor id nibh ultricies vehicula ut id elit. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Maecenas faucibus mollis interdum. Donec id elit non mi porta gravida at eget metus.",
-          "id": "with-very-long-option-text-example-item-1",
-          "sub": {
-            "items": [
-              {
-                "text": "Nullam id dolor id nibh ultricies vehicula ut id elit. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Maecenas faucibus mollis interdum. Donec id elit non mi porta gravida at eget metus.",
-                "value": "subitem-1"
-              },
-              {
-                "text": "Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Donec sed odio dui. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Cras mattis consectetur purus sit amet fermentum.",
-                "value": "subitem-2"
-              },
-              {
-                "text": "Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Etiam porta sem malesuada magna mollis euismod. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Etiam porta sem malesuada magna mollis euismod. Etiam porta sem malesuada magna mollis euismod. Donec sed odio dui. Sed posuere consectetur est at lobortis.",
-                "value": "subitem-3"
-              }
-            ],
-            "attributes": {
-              "aria-labelledby": "with-very-long-option-text-example-item-1"
-            }
-          }
-        },
-        {
-          "text": "Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Donec sed odio dui. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Cras mattis consectetur purus sit amet fermentum.",
-          "id": "with-very-long-option-text-example-item-2",
-          "sub": {
-            "items": [
-              {
-                "text": "Nullam id dolor id nibh ultricies vehicula ut id elit. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Maecenas faucibus mollis interdum. Donec id elit non mi porta gravida at eget metus.",
-                "value": "subitem-1"
-              },
-              {
-                "text": "Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Donec sed odio dui. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Cras mattis consectetur purus sit amet fermentum.",
-                "value": "subitem-2"
-              },
-              {
-                "text": "Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Etiam porta sem malesuada magna mollis euismod. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Etiam porta sem malesuada magna mollis euismod. Etiam porta sem malesuada magna mollis euismod. Donec sed odio dui. Sed posuere consectetur est at lobortis.",
-                "value": "subitem-3"
-              }
-            ],
-            "attributes": {
-              "aria-labelledby": "with-very-long-option-text-example-item-2"
-            }
-          }
-        },
-        {
-          "text": "Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Etiam porta sem malesuada magna mollis euismod. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Etiam porta sem malesuada magna mollis euismod. Etiam porta sem malesuada magna mollis euismod. Donec sed odio dui. Sed posuere consectetur est at lobortis.",
-          "id": "with-very-long-option-text-example-item-3",
-          "sub": {
-            "items": [
-              {
-                "text": "Nullam id dolor id nibh ultricies vehicula ut id elit. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Maecenas faucibus mollis interdum. Donec id elit non mi porta gravida at eget metus.",
-                "value": "subitem-1"
-              },
-              {
-                "text": "Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Donec sed odio dui. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Cras mattis consectetur purus sit amet fermentum.",
-                "value": "subitem-2"
-              },
-              {
-                "text": "Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Etiam porta sem malesuada magna mollis euismod. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Etiam porta sem malesuada magna mollis euismod. Etiam porta sem malesuada magna mollis euismod. Donec sed odio dui. Sed posuere consectetur est at lobortis.",
-                "value": "subitem-3"
-              }
-            ],
-            "attributes": {
-              "aria-labelledby": "with-very-long-option-text-example-item-3"
-            }
-          }
-        }
-      ]
-    }
-  },
   {
     "name": "con un legend como encabezado",
     "data": {
@@ -1232,94 +1145,6 @@
       ]
     }
   },
-  {
-    "name": "con todo items padres",
-    "data": {
-      "name": "with-all-parent-items",
-      "classes": "mt-base",
-      "type": "checkbox",
-      "fieldset": {
-        "legend": {
-          "text": "Selecciona organismo"
-        }
-      },
-      "hint": {
-        "text": "Selecciona el organismo al que perteneces."
-      },
-      "idPrefix": "parent-example",
-      "items": [
-        {
-          "text": "Item 1",
-          "id": "parent-example-item-1",
-          "sub": {
-            "items": [
-              {
-                "text": "Subitem 1",
-                "value": "subitem-1"
-              },
-              {
-                "text": "Subitem 2",
-                "value": "subitem-2"
-              },
-              {
-                "text": "Subitem 3",
-                "value": "subitem-3"
-              }
-            ],
-            "attributes": {
-              "aria-labelledby": "parent-example-item-1"
-            }
-          }
-        },
-        {
-          "text": "Item 2",
-          "id": "parent-example-item-2",
-          "sub": {
-            "items": [
-              {
-                "text": "Subitem 1",
-                "value": "subitem-1"
-              },
-              {
-                "text": "Subitem 2",
-                "value": "subitem-2"
-              },
-              {
-                "text": "Subitem 3",
-                "value": "subitem-3"
-              }
-            ],
-            "attributes": {
-              "aria-labelledby": "parent-example-item-2"
-            }
-          }
-        },
-        {
-          "text": "Item 3",
-          "id": "parent-example-item-3",
-          "sub": {
-            "items": [
-              {
-                "text": "Subitem 1",
-                "value": "subitem-1"
-              },
-              {
-                "text": "Subitem 2",
-                "value": "subitem-2"
-              },
-              {
-                "text": "Subitem 3",
-                "value": "subitem-3"
-              }
-            ],
-            "attributes": {
-              "aria-labelledby": "parent-example-item-3"
-            }
-          }
-        }
-      ]
-    }
-  },
   {
     "name": "con un item padre abierto",
     "description": "Usa <code>'expanded': true</code>",
@@ -2099,142 +1924,6 @@
       ]
     }
   },
-  {
-    "name": "con ids individuales",
-    "description": "Mostrar código para ver los <code>id</code> aplicados",
-    "data": {
-      "name": "with-individual-ids",
-      "classes": "mt-base",
-      "fieldset": {
-        "legend": {
-          "text": "Selecciona organismo"
-        }
-      },
-      "hint": {
-        "text": "Selecciona el organismo al que perteneces."
-      },
-      "items": [
-        {
-          "text": "Opción 1",
-          "value": "option-1",
-          "id": "option-A"
-        },
-        {
-          "text": "Opción 2",
-          "value": "option-2",
-          "id": "option-B"
-        },
-        {
-          "text": "Opción 3",
-          "value": "option-3",
-          "id": "option-C"
-        },
-        {
-          "text": "Opción 4",
-          "value": "option-4",
-          "id": "option-D"
-        },
-        {
-          "text": "Opción 5",
-          "value": "option-5",
-          "id": "option-E"
-        }
-      ]
-    }
-  },
-  {
-    "name": "con atributos",
-    "description": "Muestra el código para ver cómo se aplican los atributos",
-    "data": {
-      "name": "with-attributes",
-      "classes": "mt-base",
-      "fieldset": {
-        "legend": {
-          "text": "Selecciona organismo"
-        }
-      },
-      "hint": {
-        "text": "Selecciona el organismo al que perteneces."
-      },
-      "attributes": {
-        "data-attribute-1": "tree-id-example-attribute"
-      },
-      "items": [
-        {
-          "text": "Opción 1",
-          "value": "option-1",
-          "attributes": {
-            "data-attribute-1": "value-A",
-            "data-attribute-2": "value-B",
-            "data-attribute-3": "value-C"
-          }
-        },
-        {
-          "text": "Opción 2",
-          "value": "option-2",
-          "attributes": {
-            "data-attribute-1": "value-A",
-            "data-attribute-2": "value-B",
-            "data-attribute-3": "value-C"
-          }
-        },
-        {
-          "text": "Opción 3",
-          "value": "option-3",
-          "attributes": {
-            "data-attribute-1": "value-A",
-            "data-attribute-2": "value-B",
-            "data-attribute-3": "value-C"
-          },
-          "expanded": true,
-          "sub": {
-            "attributes": {
-              "data-sub-attribute-1": "sub-value-A",
-              "data-sub-attribute-2": "sub-value-B",
-              "data-sub-attribute-3": "sub-value-C"
-            },
-            "items": [
-              {
-                "text": "Item",
-                "value": "item",
-                "attributes": {
-                  "data-item-attribute-1": "item-value-A",
-                  "data-item-attribute-2": "item-value-B",
-                  "data-item-attribute-3": "item-value-C"
-                }
-              },
-              {
-                "text": "Item",
-                "value": "item"
-              },
-              {
-                "text": "Item",
-                "value": "item"
-              }
-            ]
-          }
-        },
-        {
-          "text": "Opción 4",
-          "value": "option-4",
-          "attributes": {
-            "data-attribute-1": "value-A",
-            "data-attribute-2": "value-B",
-            "data-attribute-3": "value-C"
-          }
-        },
-        {
-          "text": "Opción 5",
-          "value": "option-5",
-          "attributes": {
-            "data-attribute-1": "value-A",
-            "data-attribute-2": "value-B",
-            "data-attribute-3": "value-C"
-          }
-        }
-      ]
-    }
-  },
   {
     "name": "Mostrar u ocultar un item con JavaScript",
     "description": "Puedes usar con javascript la función global <code>activateItemsTree(tree, element, show)</code>, para mostrar u ocultar todos los items, usando el id del elemento, el parámetro <code>show</code> admite <code>true</code> o <code>false</code>, si le pasamos true se se mostrará el item expandido, y si le pasamos false se mostrará cerrado. Ej: Abre la consola del navegador y escribe <code>activateItemsTree('tree-item-js', 'tree-item-js-example-item-1', true)</code> para mostrar todos los items expandidos.",

package/vite.config.js

@@ -719,7 +719,7 @@ export default defineConfig({
     },
     host: '0.0.0.0',
     allowedHosts: [
-      '02e9a10f-2a7a-4ded-a5d9-e1be69f26153-00-15tqpn9sli2c2.worf.replit.dev',
+      '82c7d68c-1131-4db5-bf36-165d8f8b1d98-00-2b55tnaqky432.worf.replit.dev',
       'localhost'
     ]
   },