desy-html 14.0.0 → 15.0.0-beta.2

package/.node-version

@@ -0,0 +1 @@
+22.21.1

package/.nvmrc

@@ -0,0 +1 @@
+22.21.1

package/README.md

@@ -1,36 +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 Gulp, Postcss, 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 generate CSS from `src/styles.css` to `/dist/styles.css`,  listen to changes in njk, css and html, and browser-sync reload.
-* Use `npm run prod` to generate CSS, Purge it and Minify it.
-* Dependencies: Node.js v20.14.0, Tailwind CSS and AutoPrefixer configed in PostCSS
+- **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
 
-### Thanks ###
+## Prerequisites
 
-This project started initially forked from: [https://github.com/saadeghi/tailwindcss-postcss-browsersync-boilerplate](https://github.com/saadeghi/tailwindcss-postcss-browsersync-boilerplate)
+Before you begin, ensure you have the following installed:
 
-This project is built upon the GOV.UK Frontend project: [https://github.com/alphagov/govuk-frontend](https://github.com/alphagov/govuk-frontend) 
-We would like to thank the Government Digital Service team for their fabulous work and for making it opensource for the community.
+- **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/_global.foot.njk

@@ -6,9 +6,6 @@
   "classes": "lg:mt-48"
 })  }}
 
-<script type="module" src="js/cally.js"></script>
-<script src="js/popper.min.js"></script>
-<script src="js/tippy-bundle.umd.min.js"></script>
 <script type="module" src="js/index.js"></script>
 </body>
 </html>