Molecule List

Introduction

Le module @framework/ui/experimental/List est une brique de prsentation nouvelle gnration, greffe sur la « molecule » frappe-ui/list. Il introduit une approche compose de trois lments : List, ListFooter et ListBulkBar, conus pour remplacer terme le module ListView actuel avec une exprience utilisateur plus fluide.

:::dokos Nouveaut exprimentale Ce module est marqu comme exprimental. Son API peut voluer sans priode de dprciation jusqu' ce que la page de liste principale du Desk l'ait intgr. Le module ListView existant reste inchang et utilisable en parallle. :::

      
flowchart LR
    A[Hte: Page de liste] --> B[List]
    B --> C[Affichage des lignes]
    B --> D[Tris colonnes]
    B --> E[Slection lignes]
    A --> F[ListFooter]
    F --> G[Taille de page]
    F --> H[Charger plus]
    A --> I[ListBulkBar]
    I --> J[Compteur & Actions]
    I --> K[Effacer slection]

    

Composants

List

Le composant List est purement prsentationnel : il ne rcupre ni ne stocke de donnes. Son rle est d'afficher des colonnes et des lignes partir de donnes fournies par l'hte.

Props principales

Modles (« v-model »)

Le tri respecte le mme format Sort[] que celui manipul par le composant SortBy, garantissant une cohrence avec le reste de l'cosystme.

vnements mis (« emits »)

• column-resize : dclench lors du redimensionnement d'une colonne.
• column-reset : dclench lors de la rinitialisation de la largeur d'une colonne.

Slots

• #cell : personnalisation du rendu d'une cellule.
• #empty : affich lorsqu'aucune ligne n'est disponible.

ListFooter

Le composant ListFooter gre la navigation l'intrieur d'une liste pagine.

      
sequenceDiagram
    participant U as Utilisateur
    participant F as ListFooter
    participant H as Hte
    U->>F: Clic sur un onglet de taille de page
    F->>H: Emet `page-size` (clic utilisateur)
    H->>F: Met  jour `v-model:pageSize`
    F->>U: Affiche « N sur M »
    U->>F: Clic sur « Charger plus »
    F->>H: Emet `load-more`
    H->>F: Ajoute les lignes suivantes

    

Fonctionnalits

• Onglets de taille de page : l'utilisateur choisit le nombre de lignes afficher par page (ex. 20, 50, 100). Le v-model:pageSize synchronise la valeur, tandis que l'vnement page-size ne se dclenche que lors d'un clic, permettant l'hte de distinguer un choix utilisateur d'une valeur restaure.
• Charger plus : un bouton apparat tant que des lignes restent charger.
• Compteur « N sur M » : affiche le nombre de lignes charges par rapport au total. Un emplacement (« placeholder ») est affich tant que les compteurs ne sont pas connus.

ListBulkBar

Le composant ListBulkBar est une barre flottante qui apparat au-dessus de la liste lorsqu'une ou plusieurs lignes sont slectionnes.

Fonctionnalits

• Compteur de slection : affiche immdiatement le nombre de lignes slectionnes.
• Actions group es : dclenche des actions sur l'ensemble des lignes slectionnes.
• Bouton d'effacement : dselectionne toutes les lignes en un clic.

Le composant doit tre positionn au-dessus d'un conteneur position: relative.

Architecture et statut

Coexistence avec ListView

Le module ListView existant et son sous-chemin ./ListView ne sont pas modifis. Le nouveau module List est plac ct, dans src/experimental/List/, permettant une migration progressive des pages de liste vers le nouveau composant.

      
flowchart TB
    subgraph Avant
        A1[ListView - Module existant]
    end
    subgraph Maintenant
        B1[ListView - Toujours l]
        B2[List - Exprimental]
    end
    subgraph Futur
        C1[List - Stable]
    end
    A1 --> B1
    B2 --> C1

    

ADR 0002

Une note dans l'ADR (« Architecture Decision Record ») 0002 du paquet ui documente la coexistence des deux modules. Le fichier CONTEXT.md liste galement les deux modules pour guider les dveloppeurs.

Limitations actuelles

Stories non disponibles

Le module est livr avec des tests uniquement. Les « stories » (« dmonstrations interactives ») du composant reviendront ultrieurement, une fois rsolue la question de l'affichage des stories dans le paquet.

Gaps remonts en amont

Deux limitations de la « molecule » frappe-ui sous-jacente ont t identifies et des contournements (« workarounds ») ont t mis en place dans cette implmentation :

1. Slection et lien de ligne : la proprit selectable transforme un clic de ligne en bascule de slection, mais la ligne doit rester un lien fonctionnel. La colonne de cases cocher est donc dessine ici, avec « select-all » dans l'en-tte (frappe/frappe-ui#1131).
2. Fentrage virtuel : <ListRows virtual> recherche son conteneur de dfilement une seule fois, avant qu'un viewport ScrollArea ne signale son dbordement. Une liste qui monte avec des lignes dj disponibles n'affiche donc rien. Le fentrage utilise ici useVirtualRows export par la molecule, avec le viewport fourni explicitement (frappe/frappe-ui#1132).

Bonnes pratiques d'intgration

Fournir les colonnes partir de ColumnSettings

Le composant List est conu pour recevoir les colonnes dans le format Column[] mis par le composant ColumnSettings. L'hte peut enrichir chaque colonne avec une proprit align drive des mtadonnes (« Meta ») du DocType.

Grer le tri avec Sort

Le modle sort utilise le mme format que le composant SortBy. Lier ce modle active automatiquement le tri sur les en-ttes :

• Premier clic : dfinit la colonne comme tri principal.
• Second clic : inverse l'ordre de tri.

Scuriser les liens de ligne

La prop rowLink(row) doit retourner un objet RouteLocation valide. Cela garantit que le clic-milieu ouvre la fiche dans un nouvel onglet et que « Copier le lien » fonctionne.

Distinction clic vs. restauration

Pour ListFooter, couter l'vnement page-size plutt que v-model:pageSize permet de dclencher une action uniquement lors d'un choix utilisateur, et non lors d'une restauration de valeur (par exemple au chargement initial de la page).

Mise en pratique

Voici un exemple de composition des trois composants sur une page de liste :

      
flowchart LR
    subgraph Hte
        H1[Donnes: rows, columns]
        H2[Modles: selection, sort, pageSize]
        H3[Vnements: column-resize, load-more, page-size]
    end
    subgraph Composition
        C1[List]
        C2[ListBulkBar]
        C3[ListFooter]
    end
    H1 --> C1
    H2 --> C1
    H2 --> C2
    H2 --> C3
    C1 --> H3
    C3 --> H3

    

1. L'hte rcupre les donnes et les passe List via rows et columns.
2. L'hte lie selection et sort List pour activer respectivement la slection et le tri.
3. ListBulkBar ragit automatiquement selection pour afficher le compteur et les actions.
4. ListFooter gre la pagination via v-model:pageSize et met load-more pour demander les lignes suivantes.

Sources

• Merge Request Dodos : !10900
• Pull Request amont Frappe : #42661
• ADR 0002 : Agencement du module ListView