# CLAUDE.md — @malio/layer-ui

## Projet

Bibliothèque de composants UI sous forme de **Nuxt 4 Layer**. Le package `@malio/layer-ui` est consommé par les autres applications Malio via `extends` dans leur `nuxt.config.ts`.

## Commandes

```bash
npm run dev            # Lance le playground (.playground/)
npm run dev:prepare    # Génère les types Nuxt (à lancer après un clone)
npm run test           # Vitest (run mode)
npm run lint           # ESLint
npm run story:dev      # Histoire (documentation composants)
```

## Architecture

```
app/
  components/malio/    # Composants (auto-importés comme <MalioXxx>)
  story/               # Fichiers .story.vue (Histoire)
  assets/css/malio.css # Design tokens (CSS custom properties)
.playground/           # App Nuxt pour tester les composants en dev
```

## Conventions composants

- **Nommage fichier** : PascalCase (`InputText.vue`). Le préfixe `Malio` est ajouté automatiquement par le dossier `malio/`.
- **`defineOptions({ name: 'MalioXxx', inheritAttrs: false })`** en tête de chaque composant.
- **Props communes** : `id`, `label`, `modelValue`, `inputClass`, `labelClass`, `groupClass`, `disabled`, `readonly`, `hint`, `error`, `success`.
- **Pattern contrôlé/non-contrôlé** : `isControlled = computed(() => props.modelValue !== undefined)` avec `localValue` en fallback.
- **Classes CSS** : fusionnées avec `twMerge()` pour permettre l'override par le consommateur via les props `*Class`.
- **Accessibilité** : `aria-invalid`, `aria-describedby`, labels liés par `for/id`.
- **Icônes** : via `@iconify/vue` (Icon component), pas `@nuxt/icon` dans les composants.

## Stack technique

- **Nuxt 4** (layer), **Vue 3** Composition API (`<script setup lang="ts">`)
- **TypeScript** strict (`defineProps<T>()` + `withDefaults`)
- **Tailwind CSS** avec palette custom `m-*` (primary, secondary, error, etc.) basée sur des CSS variables RGB
- **tailwind-merge** pour la fusion intelligente des classes
- **maska** pour le masquage d'input (InputText)
- **Vitest** + `@vue/test-utils` pour les tests unitaires (pattern `*.test.ts` colocalisé)
- **Histoire** pour la documentation visuelle des composants

## Design tokens

Définis dans `app/assets/css/malio.css` comme CSS custom properties RGB :
- `--m-primary`, `--m-secondary`, `--m-tertiary`, `--m-border`, `--m-text`, `--m-muted`, `--m-bg`, `--m-error`, `--m-success`, `--m-radius`
- Utilisés via Tailwind : `text-m-primary`, `border-m-error`, `bg-m-bg`, `rounded-malio`, etc.

## Tests

- Fichiers colocalisés : `ComponentName.test.ts` à côté du `.vue`
- Pattern : `mountComponent(props)` helper, tests de rendu, props, emits, états, accessibilité
- Environnement : jsdom

## Git & CI

- **Conventional Commits** obligatoires (hooks pre-commit + commit-msg)
- Branches : `develop` → `main`
- **semantic-release** sur push main (Gitea Actions)
- Registry privé Gitea (`@malio` scope)