@deliverup/ui

Bibliothèque de composants Vue 3 à destination des applications web Deliver Up.

Pré-requis minimal

• Node.js 18.13
• NPM 8.9.3

Installation

Pour installer ce package, vous devez ajouter dans le fichier .npmrc situé à la racine de votre projet les lignes suivantes:

.npmrc

@deliver-up:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=<PERSONAL_ACCESS_TOKEN>

PERSONAL_ACCESS_TOKEN Token à générer depuis l’interface Github avec à minima le scope read:packages

Puis lancer la commande:

yarn add @deliver-up/ui

Documentation

Accès

Le package dispose d’un Storybook comme documentation afin d’exposer des exemples de composant et leurs usage.

Cette documentation est disponible sur https://ui.deliverup.tech.

Local

Pour construire, ou mettre à jour la documentation la commandes suivantes sont à utiliser:

yarn storybook

Une fois le build terminé, le site sera disponible sur http://localhost:6006

Développement

L’ajout, ou la modification de composant doit passer par le Storybook afin de tester le composant sous différentes configurations (props, mode sombre, …)

Ce package utilise semantic-release afin d’automatiser le versionning avec les principes Semver

Migration depuis le registre Gitlab

Pour les projets utilisant le précédent registre avec Gitlab

Changement de package

Dans le fichier .npmrc, ajouter les champs suivants:

@deliver-up:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=<PERSONAL_ACCESS_TOKEN>

PERSONAL_ACCESS_TOKEN Token à générer depuis l’interface Github avec à minima le scope read:packages

Et supprimer les champs relatifs à Gitlab

@deliverup:registry=https://gitlab.com/api/v4/packages/npm/
//gitlab.com/api/v4/packages/npm/:_authToken=glpat-ye95xhxZy1mt1bQuyV6Z
//gitlab.com/api/v4/projects/16101686/packages/npm/:_authToken=glpat-ye95xhxZy1mt1bQuyV6Z

Dans un terminal lancer les commandes:

yarn remove @deliverup/ui
yarn add @deliver-up/ui

Puis modifier tous les chemins d'import @deliverup/ui en @deliver-up/ui

Usage

Styles

Le fichier CSS du package doit être importé dans le fichier CSS du projet, ex: /resouces/css/app.css

@import '@deliver-up/ui/dist/style.css';

Composants

Chaque composant doit être chargés individuellement afin de réduire au maximum la taille du front transpilé

Exemple: pour utiliser le composant DButton

<template>
  <DButton label="Hello world" />
</template>

<script setup>
  import { DButton } from '@deliver-up/ui'
</script>

Migration v3 => v4

🔧 Changements globaux

| Type de changement | Description | |--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Migration | Passage complet en TypeScript | | Storybook | Utilisation des actions Storybook | | Corrections | Fix de plusieurs stories | | Styles | Adoption de tailwind-variants | | Normalisation | - Toutes les props contenant less deviennent Less (headerless → headerLess);- Les composants ont tous la même taille, définie par la même props 'size'. | | Traductions | Support i18n avec override possible dans le projet parent |

Exemple d’override :

{
  "ui": {
    "pagination": {
      "previous": "précédent du projet parent"
    }
  }
}

🧩 Changements par composant

🎛️ Button

⚙️ Modifications majeures

| Avant | Après | |-----------------------------------------------------|------------------------------------------------| | primary, secondary, gray, danger, ghost, outlined | → remplacés par variant | | <d-button primary /> | <d-button :variant="primary" /> | | noHorizontalPadding, static, light | ❌ supprimés | | full | ❌ supprimé (utiliser w-full) | | reverse | ❌ supprimé (utiliser flex-row-reverse) | | dot | ❌ supprimé (dot visible si dotConfig existe) |

🧠 useHandleButtonState

useHandleButtonState permet de gérer automatiquement l’état d’un DButton pour une action async (loading / success / error) sans logique manuelle.

🧩 Exemple

<script setup lang="ts">
  const downloadHandler = useHandleButtonState({
    props: {
      variant: 'primary',
      size: 'sm',
      icon: faDownload
    },
    action: async () => {
      return new Promise < boolean > ((resolve) => {
        setTimeout(() => resolve(true), 1500)
      })
    },
    loading: {
      label: 'Chargement'
    },
    success: {
      label: t('common.downloaded'),
      duration: 2000
    },
    error: {
      label: t('common.error_occurred')
    }
  })
</script>

<template>
  <DButton :handler="downloadHandler" @click="showFile(row.id, true)" />
</template>

⚙️ Options

• props : props passées au DButton
• action (obligatoire) : fonction async exécutée au clic
• loading : état pendant l’exécution
• success : état après succès (duration optionnel)
• error : état en cas d’erreur (duration optionnel)

✅ Comportement

• Le bouton se met en loading automatiquement
• Le label change selon l’état
• Le bouton est désactivé pendant l’action
• Reset auto après un succès si duration est défini

🔴 Dot

| Avant | Après | | | | |-----------------------|-----------------------------|-----------|-------------|---------------| | small, large | → size: sm | md | lg | | | bottom, left | → position: top_left | top_right | bottom_left | bottom_right | | close | ❌ supprimé | | | | | color | → variant: primary | success | danger | | | ring (configurable) | → devient un simple booléen | | | |

🆕 Nouvelles props

• wrapperClass
• dotClass
• pingClass

👤 Avatar

| Avant | Après | | | | |------------------------|-----------------------|----|----|-----| | small, large, larger | → size: sm | md | lg | xl | | ghost, secondary | → variant | | | | | iconType, icon | → icon unique | | | | | dot | → devient dotConfig | | | | | pointerLess | ❌ supprimé | | | |

🆕

• Prop class

⚠️ Alert

| Avant | Après | |-------------------|---------------------------------------------------------| | danger, caution | → variant (danger, caution, primary, success) |

🆕

• Prop class
• trailingAction accepte toutes les props d’un <a> + label

🏷️ Badge

🆕 Nouvelles options

• icon
• iconClass
• disabled
• variant
• class
• dotClass
• dismissClass

❌ Props supprimées

• backgroundColor, contentColor, dotColor, dismissColor

🔄 Modifications

| Avant | Après | | |-------------------------------------------|-------------------|-----| | rounded inversé (false = moins arrondi) | true par défaut | | | large | → size: md | lg |

🔗 Link

| Avant | Après | |-----------|-----------------------------------------| | classes | → class | | small | ❌ supprimé (utiliser class="text-sm") |

🆕

• Prop variant

🃏 Card

Très nombreuses modifications. Résumé :

❌ Props supprimées

• borderless (→ border)
• headerless (auto-détection)
• contentless
• collapse, defaultCollapsed (→ collapsed)
• defaultContentPadding
• customContent (→ slot default)
• auto (→ class w-full)
• divide
• paddingless (→ p-0)

🔄 Modifications

• background → class
• collapsed devient la seule prop liée au collapse

⬇️ Dropdown

Regroupement

| Avant | Après | |-----------------------------|------------------------------| | buttonLabel, buttonIcon | → button (props de Button) |

❌ Props supprimées + remplacements via classes

| Ancienne prop | Solution | |-----------------------------|-----------------------| | relativeless | class="static" | | relativeWidth | class="w-auto" | | noButtonHorizontalPadding | button.class="px-0" |

🆕

• disabled
• actions: tableau d’actions (event + label obligatoires)
• Emit actionClick → retourne l’event
• sections pour organiser les actions

📭 Empty

| Avant | Après | |-----------------------------|------------------------------| | actionType, actionColor | → action (props de Button) | | iconColor | → iconClass | | borderless, slim | → class | | iconLess | supprimé (auto-détection) |

📄 List

• classes → class

🔢 Paginate

• Emit change → ne retourne plus la différence mais la page sélectionnée

🪟 Modal

• dismiss → dismissible

🔄 ListChanger

| Avant | Après | | |-------------|-----------------|------------------------| | spaceless | → class="m-0" | | | small | → size: sm | md (md par défaut) |

🧱 Placeholder

• Prop row supprimée
• Ajout class

🔍 Search & Sort

Changements

• Search → supprimé (fusion)
• Sort → renommé SearchAndSort

Props modifiées

| Avant | Après | |------------------|------------------------| | backgroundless | → class="bg-inherit" | | sortless | → sortLess |

Actions & Sections

Nouveau format :

{
  actions: [
    { id: 'action', label: 'Action', sectionId: 'section_1' }
  ],
    sections
:
  [{ id: 'section_1', label: 'Section 1' }]
}

📤 SlideOut

| Avant | Après | |---------------|--------------------------------------------------| | paddingLess | → footerClass="mt-6 px-4 sm:px-6" | | wide | → size="2xl" | | size | valeurs limitées (sm, md, lg, xl, 2xl) |

🪜 Steps

| Avant | Après | |---------------------------------|-------------------------------------------| | indexless | → indexLess | | panels, bullets, progress | → type: panel ou bullet ou progress | | circles | ❌ supprimé |

📊 Table

• paginationless → paginationLess

Nouvelles options

• columnGroups -> pour avoir plusieurs niveaux de colonnes
• rowVariant -> permet de sélectionner un variant pour la ligne

🗂️ Tabs

| Avant | Après | |-------------|--------------------------| | spaceless | → navClass="space-x-0" | | full | → buttonClass="flex-1" | | (nouveau) | disabled |

🏷️ Label

• noMarginBottom → class="mb-0"
• sublabel → subLabel

📅 DatePicker

• Format français par défaut
• subLabel mis à jour comme le composant Label
• Composant non totalement type-safe (props Vue Datepicker non complétées)
• Mise à jour de la librairie v3 -> v12

Nouvelles options

• timeConfig
• enableTimePicker
• cancelText
• selectText

📁 File

🆕

• accept
• errors.limitExceed
• errorsText.typeMismatch

🔄

• limit bloque maintenant aussi l’upload selon la taille

Mise à jour naming

• limitExceededLabel → errors.limitExceed
• subLabel comme Label

🔤 Input

• Nouvelle props size (mêmes valeurs que Button)

📱 PhoneInput

• Tous les codes pays doivent être en MAJUSCULES

🔁 useHandleSuccessButtonState (ex HandleSuccessButtonState)

Devient un composable

• Accepte une fonction sync ou async
• Gestion du loading automatique en async

Options déplacées

| Avant | Après | |----------------------------------------------|-------------| | successLabel, successIcon, defaultIcon | → options |

Nouvelles options

• loadingLabel
• duration

🧩 Select

❌ Props supprimées

• customClasses
• classes

Options modifiées

| Avant | Après | |-------------------------|-------------------------------------------------------| | innerLabel → string | innerLabel → string \| (option: object) => string |

🆕 Props individuelles

containerClass
wrapperClass
singleLabelClass
singleLabelTextClass
multipleLabelClass
searchClass
tagsClass
tagClass
tagRemoveClass
caretClass
dropdownClass
optionsClass
optionClass

🆕 🧩 Tooltip

• Utilisation de la libraire Reka-UI

Props individuelles

placement
open
disabled
showArrow
class
contentClass
arrowClass
duration
variant
+ props venant de Reka-UI

🆕 🧩 Popover

• Utilisation de la libraire Reka-UI

🆕 🧩 TreeView

nodes
loadingIcon
loadingText
disableLines?