Merge pull request #1613 from LouisMazel/feat/maz-table-animated

feat(maz-ui): MazTable - add min-width to header items and animated rows

Author: LouisMazel

apps/docs/src/components/maz-table.md

@@ -19,6 +19,7 @@ description: MazTable is designed to be a reusable data table with advanced feat
 4. Row Selection (prop `select-value="key"`): There is a dedicated column for selection with a checkbox for each row. Users can individually or collectively select/deselect rows.
 5. Customizable Page Size: Users can choose the number of items to display per page using a dropdown list.
 6. Loading Indicator (prop `loading`): A loading indicator (MazLoadingBar) is displayed when data is being loaded.
+7. Animated rows (props `animated-rows` + `row-key`): rows slide to their new position when the order changes (FLIP animation). Respects `prefers-reduced-motion`.
 
 ## Available models
 
@@ -369,6 +370,67 @@ v-model:page-size="{{pageSize ?? 'undefined'}}"
 
 </ComponentDemo>
 
+## Animated rows
+
+Enable `animated-rows` to make rows slide to their new position when the order changes (FLIP animation) - perfect for live leaderboards or sortable lists. Provide a stable `row-key` (a field uniquely identifying each row) so every row keeps its identity across reorders. The animation is automatically disabled when the user prefers reduced motion.
+
+<ComponentDemo>
+  <MazBtn class="vp-raw" size="sm" @click="shuffleRows">Shuffle</MazBtn>
+  <br />
+  <br />
+  <MazTable
+    class="vp-raw"
+    size="sm"
+    animated-rows
+    row-key="id"
+    :headers="[
+      { label: '#', key: 'id', align: 'center', width: '3rem' },
+      { label: 'Name', key: 'name' },
+      { label: 'Score', key: 'score', align: 'center' },
+    ]"
+    :rows="players"
+  />
+
+  <template #code>
+
+  ```vue
+  <template>
+    <MazBtn @click="shuffleRows">
+      Shuffle
+    </MazBtn>
+    <MazTable
+      animated-rows
+      row-key="id"
+      :headers="[
+        { label: '#', key: 'id', align: 'center', width: '3rem' },
+        { label: 'Name', key: 'name' },
+        { label: 'Score', key: 'score', align: 'center' },
+      ]"
+      :rows="players"
+    />
+  </template>
+
+  <script lang="ts" setup>
+    import { MazTable } from 'maz-ui/components'
+    import { ref } from 'vue'
+
+    const players = ref([
+      { id: 1, name: 'John', score: 12 },
+      { id: 2, name: 'Jane', score: 24 },
+      { id: 3, name: 'Alice', score: 8 },
+      { id: 4, name: 'Bob', score: 31 },
+    ])
+
+    function shuffleRows() {
+      players.value = [...players.value].sort(() => Math.random() - 0.5)
+    }
+  </script>
+  ```
+
+  </template>
+
+</ComponentDemo>
+
 ## Loading
 
 Enable the loading state with the prop `loading`
@@ -516,6 +578,17 @@ Available sizes: `'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'`
   const searchQuery = ref<string>()
   const pageSize = ref<number>(10)
   const page = ref<number>(1)
+
+  const players = ref([
+    { id: 1, name: 'John', score: 12 },
+    { id: 2, name: 'Jane', score: 24 },
+    { id: 3, name: 'Alice', score: 8 },
+    { id: 4, name: 'Bob', score: 31 },
+  ])
+
+  function shuffleRows() {
+    players.value = [...players.value].sort(() => Math.random() - 0.5)
+  }
 </script>
 
 ## Types
@@ -545,6 +618,7 @@ export interface MazTableHeadersEnriched {
   srOnly?: boolean
   width?: string
   maxWidth?: string
+  minWidth?: string
   classes?: ThHTMLAttributes['class']
   scope?: ThHTMLAttributes['scope']
   align?: ThHTMLAttributes['align']

packages/lib/src/components/MazTable.vue

@@ -14,6 +14,7 @@ export interface MazTableHeadersEnriched {
   srOnly?: boolean
   width?: string
   maxWidth?: string
+  minWidth?: string
   classes?: NonRecursiveClassValue
   scope?: ThHTMLAttributes['scope']
   align?: ThHTMLAttributes['align']
@@ -242,6 +243,20 @@ export interface MazTableProps<T extends MazTableRow<T>> {
    * @default false
    */
   scrollable?: boolean
+  /**
+   * Field name used as a stable key for each row (e.g. an id). Gives every row a
+   * stable identity so reordering is tracked correctly - required for `animatedRows`
+   * to look right. Falls back to the row index when not provided.
+   * @type {string}
+   */
+  rowKey?: string
+  /**
+   * Animate row reordering with a FLIP transition (rows slide to their new position).
+   * Provide a stable `rowKey` for meaningful results. Respects `prefers-reduced-motion`.
+   * @type {boolean}
+   * @default false
+   */
+  animatedRows?: boolean
 }
 
 export interface MazTableProvide {
@@ -270,6 +285,7 @@ import {
   provide,
   ref,
   toRef,
+  TransitionGroup,
   useSlots,
   watch,
 } from 'vue'
@@ -310,6 +326,8 @@ const {
   color = 'primary',
   translations,
   scrollable = false,
+  rowKey,
+  animatedRows = false,
 } = defineProps<MazTableProps<T>>()
 
 const emits = defineEmits<{
@@ -575,6 +593,10 @@ function getNormalizedRows(): T[] {
   )
 }
 
+function getRowKey(row: T, index: number): string | number {
+  return rowKey && row[rowKey] != null ? row[rowKey] : index
+}
+
 function sortColumn(columnIndex: number) {
   if (columnIndex === sortedColumnIndex.value) {
     const sortTypeValue = sortType.value === 'DESC' ? 'ASC' : undefined
@@ -707,7 +729,7 @@ onBeforeMount(() => {
                 :rowspan="header.rowspan"
                 :colspan="header.colspan"
                 :headers="header.thHeaders"
-                :style="{ width: header.width, textAlign: header.align }"
+                :style="{ width: header.width, textAlign: header.align, maxWidth: header.maxWidth, minWidth: header.minWidth }"
                 class="maz:group"
                 :class="[
                   { '--hidden': header.hidden, '--sortable': header.sortable ?? sortable },
@@ -759,12 +781,16 @@ onBeforeMount(() => {
 
         <MazLoadingBar v-if="loading" :color class="maz:absolute!" />
 
-        <tbody :class="{ '--divider': hasDivider }">
+        <component
+          :is="animatedRows ? TransitionGroup : 'tbody'"
+          v-bind="animatedRows ? { tag: 'tbody', name: 'm-table-row', moveClass: 'm-table-row-move' } : {}"
+          :class="{ '--divider': hasDivider }"
+        >
           <slot>
             <template v-if="rowsFiltered.length > 0">
               <MazTableRowComponent
                 v-for="(row, rowIndex) in rowsFiltered"
-                :key="rowIndex"
+                :key="getRowKey(row, rowIndex)"
                 :class="row.classes"
                 @click="row.action && row.action(row)"
               >
@@ -837,7 +863,7 @@ onBeforeMount(() => {
               </MazTableRowComponent>
             </template>
           </slot>
-        </tbody>
+        </component>
       </table>
     </div>
 
@@ -1146,4 +1172,17 @@ onBeforeMount(() => {
     }
   }
 }
+
+/* Reordering animation (FLIP) when `animatedRows` is enabled. The class is set by
+   TransitionGroup on the child row element, hence `:deep`. Disabled when the user
+   prefers reduced motion. */
+:deep(.m-table-row-move) {
+  transition: transform 0.45s cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :deep(.m-table-row-move) {
+    transition: none;
+  }
+}
 </style>

packages/lib/tests/specs/components/MazTable.spec.ts

@@ -450,4 +450,65 @@ describe('given MazTable component', () => {
       })
     })
   })
+
+  describe('when animatedRows is enabled', () => {
+    const baseProps = {
+      animatedRows: true,
+      rowKey: 'id',
+      divider: true,
+      headers: [
+        { label: 'Id', key: 'id' },
+        { label: 'Firstname', key: 'firstname' },
+      ],
+      rows: [
+        { id: 1, firstname: 'John' },
+        { id: 2, firstname: 'Jane' },
+        { id: 3, firstname: 'Alice' },
+      ],
+    }
+
+    it('renders every row inside a tbody container', async () => {
+      const wrapper = mount(MazTable, { props: baseProps as any })
+
+      await vi.dynamicImportSettled()
+
+      const tbody = wrapper.find('tbody')
+      expect(tbody.exists()).toBe(true)
+      // The dynamic container keeps the divider class binding.
+      expect(tbody.classes()).toContain('--divider')
+      expect(wrapper.findAll('tbody tr')).toHaveLength(3)
+    })
+
+    it('reflects the new order when rows are reordered (stable rowKey path)', async () => {
+      const wrapper = mount(MazTable, {
+        props: {
+          animatedRows: true,
+          rowKey: 'id',
+          headers: [{ label: 'Id', key: 'id' }],
+          rows: [{ id: 1 }, { id: 2 }, { id: 3 }],
+        } as any,
+      })
+
+      await vi.dynamicImportSettled()
+      expect(wrapper.findAll('tbody tr td').map(td => td.text())).toStrictEqual(['1', '2', '3'])
+
+      await wrapper.setProps({ rows: [{ id: 3 }, { id: 1 }, { id: 2 }] })
+      await vi.dynamicImportSettled()
+
+      expect(wrapper.findAll('tbody tr td').map(td => td.text())).toStrictEqual(['3', '1', '2'])
+    })
+
+    it('still renders when no rowKey is provided (falls back to index)', async () => {
+      const wrapper = mount(MazTable, {
+        props: {
+          animatedRows: true,
+          headers: [{ label: 'Id', key: 'id' }],
+          rows: [{ id: 1 }, { id: 2 }],
+        } as any,
+      })
+
+      await vi.dynamicImportSettled()
+      expect(wrapper.findAll('tbody tr')).toHaveLength(2)
+    })
+  })
 })