feat(ktableview): add row-key prop [KHCP-13502] (#2427)

* feat(ktableview): add row-key prop [KHCP-13502] * fix(ktableview): do not use indexes as loop keys [KHCP-13404] * test(ktableview): add row-key prop test [KHCP-13502] * test(ktableview): minor tweak [KHCP-13502] * docs(table-view): update docs [KHCP-13502] * fix: address pr feedback * fix: apply pr feedback Co-authored-by: Adam DeHaven <[email protected]> * fix: address pr feedback * fix: address pr feedback * fix: address pr feedback * fix: address pr feedback * fix: address pr feedback --------- Co-authored-by: Adam DeHaven <[email protected]>
Kong · Oct 10, 2024 · 4d3208a · 4d3208a
1 parent cc83ed3
commit 4d3208a
Show file tree

Hide file tree

Showing 5 changed files with 368 additions and 82 deletions.
diff --git a/docs/components/table-view.md b/docs/components/table-view.md
@@ -43,20 +43,169 @@ interface TableViewHeader {
 }
 ```
 
+<KTableView
+  :data="basicData"
+  :headers="basicHeaders(false, null, 'email')"
+  :pagination-attributes="{ totalCount: basicData.length }"
+/>
+
+```vue
+<template>
+  <KTableView
+    :data="tableData"
+    :headers="headers"
+    :pagination-attributes="{ totalCount: tableData.length }"
+  />
+</template>
+
+<script setup lang="ts">
+import type { TableViewHeader, TableViewData } from '@kong/kongponents'
+
+const headers: Array<TableViewHeader> = [
+  {
+    key: 'name', 
+    label: 'Full Name', 
+  },
+  {
+    key: 'username',
+    label: 'Username',
+    tooltip: 'Unique for each user.',
+  },
+  {
+    key: 'email',
+    label: 'Email',
+    hidable: true,
+  },
+]
+
+const tableData = ref<TableViewData>([...])
+</script>
+```
+
 :::tip NOTE
 If at least one column is `hidable` in the table, KTableView will render a dropdown on the right of the table toolbar directly above the table, which will provide an interface for showing/hiding columns to the user.
 :::
 
-For an example of `headers` prop usage please refer to [`data` prop documentation](#data) below.
-
 #### Reserved Header Keys
 
-- `bulkActions` - the column displays individual checkboxes to allow selecting individual rows, while the column header displays a checkbox will check or uncheck all visible table rows. KTableView will render a dropdown on the right of the table toolbar directly above the table and you simply need to provide dropdown items via the [`bulk-action-items` slot](#bulk-action-items). Refer to the [`bulk-action-items` slot](#bulk-action-items) for the example.
-- `actions` - the column displays an actions [KDropdown](/components/dropdown) button for each row and displays no label (as if `hideLabel` was `true`; you can set `hideLabel` parameter to `false` to show the label). KTableView will automatically render the actions dropdown and you simply need to provide dropdown items via the [`action-items` slot](#action-items).
+Some header key values are treated specially.
+
+##### bulkActions
+
+The column displays individual checkboxes to allow selecting individual rows, while the column header displays a checkbox will check or uncheck all visible table rows. KTableView will render a dropdown on the right of the table toolbar directly above the table and you simply need to provide dropdown items via the [`bulk-action-items` slot](#bulk-action-items).
+
+:::warning IMPORTANT
+Bulk actions column won't be rendered in case if:
+
+- neither [`bulk-action-items`](#bulk-action-items), nor [`bulk-actions`](#bulk-actions) slots are provided
+- [`rowKey` prop](#rowkey) prop is not provided
+:::
+
+<KTableView
+  :data="basicData"
+  :headers="basicHeaders(false, null, null, true)"
+  :row-key="({ id }: Record<string, any>) => String(id)"
+  :pagination-attributes="{ totalCount: basicData.length }"
+>
+  <template #bulk-action-items="{ selectedRows }">
+    <KDropdownItem danger>
+      Delete ({{ selectedRows.length }} items)
+    </KDropdownItem>
+  </template>
+</KTableView>
+
+```vue
+<template>
+  <KTableView
+    :data="tableData"
+    :headers="headers"
+    row-key="id"
+    :pagination-attributes="{ totalCount: tableData.length }"
+  >
+    <template #bulk-action-items="{ selectedRows }">
+      <KDropdownItem danger>
+        Delete ({{ selectedRows.length }} items)
+      </KDropdownItem>
+    </template>
+  </KTableView>
+</template>
+
+<script setup lang="ts">
+import type { TableViewHeader, TableViewData } from '@kong/kongponents'
+
+const headers: Array<TableViewHeader> = [
+  {
+    key: 'bulkActions', 
+    label: 'Bulk actions', 
+  },
+  ...
+]
+
+const tableData = ref<TableViewData>([ ... ])
+</script>
+```
+
+##### actions
+
+The column displays an actions [KDropdown](/components/dropdown) button for each row and displays no label (as if `hideLabel` was `true`; you can set `hideLabel` parameter to `false` to show the label). KTableView will automatically render the actions dropdown and you simply need to provide dropdown items via the [`action-items` slot](#action-items).
 
 :::tip NOTE
 KTableView automatically displays the bulk action checkbox as the first column, and the `actions` menu in the last column, when enabled.
-::: 
+:::
+
+<KTableView
+  :data="basicData"
+  :headers="basicHeaders(true)"
+  :pagination-attributes="{ totalCount: basicData.length }"
+>
+  <template #action-items>
+    <KDropdownItem>
+      Edit
+    </KDropdownItem>
+    <KDropdownItem
+      danger
+      has-divider
+    >
+      Delete
+    </KDropdownItem>
+  </template>
+</KTableView>
+
+```vue
+<template>
+  <KTableView
+    :data="tableData"
+    :headers="headers"
+    :pagination-attributes="{ totalCount: tableData.length }"
+  >
+    <template #action-items>
+      <KDropdownItem>
+        Edit
+      </KDropdownItem>
+      <KDropdownItem
+        danger
+        has-divider
+      >
+        Delete
+      </KDropdownItem>
+    </template>
+  </KTableView>
+</template>
+
+<script setup lang="ts">
+import type { TableViewHeader, TableViewData } from '@kong/kongponents'
+
+const headers: Array<TableViewHeader> = [
+  {
+    key: 'actions',
+    label: 'Row actions',
+  },
+  ...
+]
+
+const tableData = ref<TableViewData>([...])
+</script>
+```
 
 ### data
 
@@ -352,6 +501,44 @@ const getRowLink = (row: Record<string, any>): RowLink => ({
 </script>
 ```
 
+### rowKey
+
+Certain features of KTableView require a unique identifier to utilize for each row of table data.
+
+The `rowKey` prop provides a way to define which property of the `row` object should serve as this unique identifier, or to generate a custom unique identifier for each row.
+
+:::tip NOTE
+`rowKey` is required for these KTableView features:
+
+* [bulk actions](#bulkactions)
+:::
+
+The `rowKey` prop accepts either a unique string or a function that returns a unique string: `string | ((row: Record<string, any>) => string)`.
+
+If a string is provided which corresponds to a property of the `row`, the unique identifier will utilize the `row[rowKey]` as the unique identifier.
+
+```html
+<KTableView
+  row-key="id"
+  :data="tableData"
+  :headers="headers"
+/>
+```
+
+Alternatively, if a function is passed, it allows for the creation of a custom identifier based on the row data passed to the function.
+
+```html
+<KTableView
+  :row-key="({ id, username }: Record<string, any>) => username + id"
+  :data="tableData"
+  :headers="headers"
+/>
+```
+
+:::warning IMPORTANT
+The value provided through the `rowKey` prop must be unique for each `row` of data, even for paginated data.
+:::
+
 ### rowBulkActionEnabled
 
 Function for enabling or disabling row selection when `bulkActions` are enabled for the table. Helpful for making some rows unavailable for bulk actions selection. The function receives the row data object as a parameter and must return a `boolean` or an object that matches the following interface:
@@ -370,6 +557,7 @@ Default value is `() => true`.
 
 <KTableView
   :row-bulk-action-enabled="getRowBulkAction"
+  :row-key="({ id }: Record<string, any>) => String(id)"
   :data="basicData"
   :headers="basicHeaders(false, null, null, true)"
   :pagination-attributes="{ totalCount: basicData.length }"
@@ -385,6 +573,7 @@ Default value is `() => true`.
 <template>
   <KTableView
     :row-bulk-action-enabled="getRowBulkActionEnabled"
+    row-key="id"
     :data="tableData"
     :headers="headers"
     :pagination-attributes="{ totalCount: tableData.length }"
@@ -1002,10 +1191,6 @@ This slot is only available when the `actions` header key is present in [`header
 
 Slot for passing bulk action dropdown items.
 
-:::warning IMPORTANT
-Content must be provided through either this or [`bulk-actions` slot](#bulk-actions) when bulk actions is enabled for the table, otherwise bulk actions column won't be rendered.
-:::
-
 Slot props:
 
 - `selectedRows` - array of selected table row objects
@@ -1015,6 +1200,7 @@ See also: [`row-select` event](#row-select).
 <KTableView
   :data="paginatedData1"
   :headers="basicHeaders(false, null, null, true)"
+  :row-key="({ id }: Record<string, any>) => String(id)"
   :pagination-attributes="{ totalCount: basicPaginatedData.length, pageSizes: [5, 10] }"
   @page-change="onPageChange1"
   @page-size-change="onPageSizeChange1"
@@ -1031,6 +1217,7 @@ See also: [`row-select` event](#row-select).
   <KTableView
     :data="paginatedData"
     :headers="headers"
+    row-key="id"
     :pagination-attributes="{ totalCount: tableData.length, pageSizes: [5, 10] }"
   >
     <template #bulk-action-items="{ selectedRows }">
@@ -1068,6 +1255,7 @@ Slot props:
 <KTableView
   :data="basicData"
   :headers="basicHeaders(false, null, null, true)"
+  :row-key="({ id }: Record<string, any>) => String(id)"
   :pagination-attributes="{ totalCount: basicData.length }"
 >
   <template #bulk-actions="{ selectedRows }">
@@ -1084,6 +1272,7 @@ Slot props:
 <KTableView
   :data="tableData"
   :headers="headers"
+  row-key="id"
   :pagination-attributes="{ totalCount: tableData.length }"
 >
   <template #bulk-actions="{ selectedRows }">

diff --git a/sandbox/pages/SandboxTableView/SandboxTableView.vue b/sandbox/pages/SandboxTableView/SandboxTableView.vue
@@ -251,6 +251,7 @@
           :data="paginatedData"
           :headers="headers(false, false, true)"
           :pagination-attributes="{ totalCount: basicPaginatedData.length, pageSizes: [5, 10] }"
+          :row-key="({ id }: Record<string, any>) => String(id)"
           @page-change="onPageChange"
         >
           <template #bulk-actions="{ selectedRows }">
@@ -306,6 +307,7 @@
             :pagination-attributes="{ totalCount: basicPaginatedData.length, pageSizes: [5, 10] }"
             resize-columns
             :row-bulk-action-enabled="getRowBulkAction"
+            :row-key="({ id }: Record<string, any>) => String(id)"
             @page-change="onPageChange"
             @page-size-change="onPageSizeChange"
             @row-select="onBulkActionsSelect"