Lesstime/docs/superpowers/specs/2026-06-25-malio-sidebar-migration-design.md

Migration de la sidebar vers MalioSidebar (@malio/layer-ui)

Date : 2026-06-25 Statut : Design validé Scope : Frontend (layout) + backend (config sidebar) + assets

Contexte

La sidebar actuelle de Lesstime est un <aside> fait main dans frontend/app/layouts/default.vue, qui itère sur les sections renvoyées par /api/sidebar et rend chaque item via le composant maison SidebarLink. Le timer et la version sont empilés en bas du <aside>, le toggle collapse et l'overlay mobile sont gérés manuellement.

La librairie @malio/layer-ui (mise à jour) fournit désormais un composant MalioSidebar. Le projet Starseed a déjà effectué cette migration sur une architecture identique (config/sidebar.php → SidebarProvider → composable useSidebar → layout). Cette spec applique la même migration à Lesstime, avec trois spécificités Lesstime : footer (timer + version), re-catégorisation des onglets, et plusieurs items contextuels rendus côté client.

On ne modifie pas la lib @malio/layer-ui (règle CLAUDE.md).

Objectifs

1. Remplacer le <aside> maison par <MalioSidebar>.
2. Préserver le filtrage des permissions/rôles/modules côté serveur.
3. Re-catégoriser la navigation en 3 groupes : Général / Outils / Administration.
4. Mettre le timer et la version dans le footer du composant.
5. Reprendre le logo Malio de Starseed.

Décisions validées

• Catégorisation : 3 groupes (option B).
• Badge mail : le compteur de non-lus devient un suffixe sur le label (Messagerie (3)), faute de slot badge/icône par item dans MalioSidebar.

Contraintes du composant MalioSidebar

Source : frontend/node_modules/@malio/layer-ui/app/components/malio/sidebar/Sidebar.vue.

• Props : sections (requis), modelValue (v-model collapse, bool), id, sidebarClass, toggleClass.
• Types :
  • SidebarItem = { label: string; to: string; exact?: boolean }
  • SidebarSection = { label?: string; icon?: string; items: SidebarItem[] }
• Slots : #logo, #logo-collapsed, #footer, #footer-collapsed.
• Events : update:modelValue(boolean).
• Item : pas d'icône par item ni de badge — uniquement l'icône de section. Route active = match exact ou par préfixe (exact: true pour exact strict).
• Largeurs fixes : 232px (déplié) / 72px (replié). Toggle interne.

Conséquences (compromis assumés)

• Perte de l'icône par item (design malioUI = texte + icône de section). Starseed fonctionne ainsi.
• Le badge mail ne peut pas être une pastille → suffixe (N) dans le label.

Architecture cible

Modèle backend-driven conservé (sécurité serveur intacte). Le frontend mappe les sections renvoyées par /api/sidebar vers le format MalioSidebar et fusionne les items contextuels (qui dépendent d'un état runtime non connu du backend).

1. Backend — config/sidebar.php

Re-catégorisation en 3 sections (gates inchangés, juste réorganisés) :

GÉNÉRAL  (sidebar.general.section, icon mdi:view-dashboard-outline)
  Tableau de bord   /              —
  Mes tâches        /my-tasks      module project-management, perm tasks.view
  Projets           /projects      module project-management, perm projects.view
  Suivi de temps    /time-tracking module time-tracking,      perm entries.view

OUTILS   (sidebar.tools.section, icon mdi:tools)
  Messagerie        /mail          module mail
                    (filtré du rendu backend côté front, ré-injecté avec badge)

ADMINISTRATION (sidebar.admin.section, icon mdi:cog-outline, roles [ROLE_ADMIN])
  Absences équipe   /team-absences module absence
  Répertoire        /directory     module directory
  Rapports          /reporting     module reporting, perm reporting.view
  Administration    /admin         perm core.users.view

/mail reste déclaré pour le gating module (disabledRoutes), mais est filtré des sections rendues et ré-injecté côté client avec son badge, comme aujourd'hui.

2. i18n — frontend/i18n/locales/fr.json

• Renommer sidebar.general.section : « Gestion de projet » → « Général ».
• Ajouter sidebar.tools.section : « Outils ».
• Conserver les clés d'items existantes. Items client : réutiliser les clés existantes quand elles existent (sharedFiles.sidebar.title pour Documents, mail.sidebar.title/sidebar.general.mail pour Messagerie) ; ajouter une clé pour « Mes absences » (aujourd'hui en dur) et pour les contextuels (Kanban/Groupes/Archives, aujourd'hui en dur) si on souhaite les traduire, sinon conserver les libellés en dur actuels.

3. Frontend — frontend/app/layouts/default.vue

Réécriture du template autour de <MalioSidebar> :

<MalioSidebar v-model="ui.sidebarCollapsed" :sections="mergedSections"
              :sidebar-class="ui.sidebarCollapsed ? '' : 'w-[232px]'">
  <template #logo>           <img src="/LOGO_MALIO.png" alt="Malio"/></template>
  <template #logo-collapsed> <img src="/LOGO_MALIO_COLLAPSED.png" alt="Malio"/></template>
  <template #footer>
    <SidebarTimer :collapsed="false" />
    <p class="font-bold">v {{ version }}</p>
  </template>
  <template #footer-collapsed>
    <SidebarTimer :collapsed="true" />
  </template>
</MalioSidebar>

Computed mergedSections : construit les sections finales dans l'ordre canonique [général, outils, administration].

Logique de fusion :

1. Partir des sections backend (déjà filtrées), mappées en { label: t(label), icon, items: items.filter(to !== '/mail').map({label: t, to}) }.
2. Définir une table clientItems indexée par clé de section :
   • sidebar.general.section → (si currentProjectId) Kanban (exact), Groupes, Archives ; puis (si isEmployee) Mes absences.
   • sidebar.tools.section → (si isMailVisible) Messagerie avec label Messagerie + suffixe (N) quand mailStore.globalUnreadCount > 0 (99+ au-delà) ; puis (si shareEnabled) Documents.
3. Pour chaque section backend, append ses items client.
4. Si une clé de clientItems produit des items mais que la section correspondante n'est pas présente dans la réponse backend (ex. module mail off mais partage on → pas de section « Outils » côté backend), créer la section côté front (label + icône depuis une table locale).
5. Supprimer les sections finales sans items.
6. Trier selon l'ordre canonique des clés.

Le reste du <script> (timer title watchers, refData/TimeEntryDrawer, polling mail, ensureShareStatus, currentProjectId, isEmployee, isMailVisible, shareEnabled) est conservé tel quel.

4. Mobile

Starseed a supprimé l'overlay mobile custom et ne garde que watch(route) → ui.closeMobileSidebar(). On s'aligne : suppression du markup overlay (ui.sidebarOpen, .sidebar-overlay) si MalioSidebar gère le responsive. À vérifier à l'implémentation : comportement mobile réel du composant ; si l'ouverture mobile n'est pas couverte, adapter a minima sans modifier la lib.

5. Assets — logo

Copier depuis Starseed vers frontend/public/ :

• LOGO_MALIO.png (128×44)
• LOGO_MALIO_COLLAPSED.png (34×40)

Les anciens /malio.png et /LOGO_CARRE.png ne sont plus référencés par le layout (les laisser ou les retirer si plus aucun usage — à vérifier).

Composants / éléments réutilisés

• SidebarTimer (components/ui/SidebarTimer.vue) : inchangé, déjà piloté par :collapsed.
• useAppVersion() : inchangé.
• useSidebar() : inchangé.
• usePermissions() : inchangé (le filtrage permission reste backend ; les flags client isEmployee/isMailVisible/shareEnabled restent locaux).

Éléments supprimés

• Le <aside> manuel et son markup (logo, nav, toggle, overlay) dans default.vue.
• L'usage de SidebarLink dans le layout (le composant peut rester s'il est utilisé ailleurs — à vérifier ; sinon suppression possible).

Critères d'acceptation

1. La sidebar est rendue par <MalioSidebar>.
2. 3 groupes : Général, Outils, Administration (Administration visible uniquement pour ROLE_ADMIN / permissions, comme avant).
3. Toutes les permissions/rôles/modules sont respectés à l'identique (aucune régression de visibilité pour user/admin).
4. Items contextuels présents : Kanban/Groupes/Archives (dans un projet), Documents (partage activé), Mes absences (employé).
5. Messagerie affiche (N) quand il y a des non-lus.
6. Footer : timer fonctionnel + version (version masquée en replié).
7. Logo Malio de Starseed affiché (déplié + replié).
8. Collapse/expand et route active fonctionnent.
9. Pas de doublon /mail. Pas de section vide affichée.
10. Build Nuxt OK, pas d'erreur TS.

Hors scope

• Refonte du SiteSelector (n'existe pas dans Lesstime).
• Modification de la lib @malio/layer-ui.
• Changement du modèle de permissions backend.