desy-html 16.0.3 → 17.0.0

package/.node-version

@@ -1 +1 @@
-22.21.1
+22.21.1

package/.nvmrc

@@ -1 +1 @@
-22.21.1
+22.21.1

package/AGENTS.md

@@ -1,181 +1,207 @@
-# 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. Add favicon files to `branding/logos/` (favicon.svg, favicon.ico, apple-touch-icon.png)
-3. Replace logos in `branding/logos/`
-4. 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.
+# 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. Add favicon files to `branding/logos/` (favicon.svg, favicon.ico, apple-touch-icon.png). The plugin automatically copies them to `/dist/images/` during build.
+3. Replace logos in `branding/logos/`
+4. 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`
+
+## Post-Implementation Documentation Review
+
+After making code changes, review if documentation needs updates:
+
+### Checklist
+
+- [ ] **AGENTS.md** - If adding new commands, patterns, or workflows
+- [ ] **README.md** - If changing project setup or usage
+- [ ] **TESTING_PLAN.md** - If adding new test scenarios
+- [ ] **branding/BRANDING.md** - If changing branding configuration
+- [ ] **Other .md files** - Check for relevant changes
+
+### When to Update
+
+| Change Type | Files to Review |
+| ----------- | --------------- |
+| New feature | AGENTS.md, README.md, possibly TESTING_PLAN.md |
+| Config change | BRANDING.md, AGENTS.md |
+| Bug fix | TESTING_PLAN.md if adding test scenarios |
+| Documentation only | Only the .md files being changed |
+
+**Tip**: After any technical change, run a quick grep to find relevant .md files:
+```bash
+grep -r "keyword" --include="*.md"
+```
+
+## License
+
+This project uses EUPL-1.2 license. See EUPL-1.2.txt for details.