diff --git a/docs/components/parts/tables/script-setup.md b/docs/components/parts/tables/script-setup.md new file mode 100644 index 0000000000..a0519b6c7d --- /dev/null +++ b/docs/components/parts/tables/script-setup.md @@ -0,0 +1,500 @@ + + + + diff --git a/docs/components/parts/tables/shared-events.md b/docs/components/parts/tables/shared-events.md new file mode 100644 index 0000000000..8108f3fb5c --- /dev/null +++ b/docs/components/parts/tables/shared-events.md @@ -0,0 +1,83 @@ +### Row Events + +`@row:{event}` - returns the `Event`, the row item, and the type. `row-click` event is emitted whenever a row is clicked and the row click event handler is emitted, returns the row `data`. + +To avoid firing row clicks by accident, the row click handler ignores events coming from `a`, `button`, `label`, `input`, and `select` elements (unless they have the `disabled` attribute). As such click handlers attached to these element types do not require stopping propagation via `@click.stop`. + +The table in the example below contains buttons, inputs and links to demonstrate how KTableView handles clicks on different interactive elements within the table as well as clicks on its rows. + +Try clicking below on the table row, and then within elements inside the table cells. + + +
+ + + + + + +
+ + +```html + +``` + +### Cell Events + +`@cell:{event}` - returns the `Event`, the cell value, and the type. `cell-click` event is emitted whenever a cell is clicked and the cell click event handler is emitted, returns the cell `data`. + +The table in the example below contains buttons, inputs and links to demonstrate how KTableView handles clicks on different interactive elements within the table as well as clicks on its cells. + + +
+ + + + + + +
+ + +```html + +``` diff --git a/docs/components/parts/tables/shared-props.md b/docs/components/parts/tables/shared-props.md new file mode 100644 index 0000000000..1411e11b8f --- /dev/null +++ b/docs/components/parts/tables/shared-props.md @@ -0,0 +1,1023 @@ +### headers + +Array of objects that represent table columns along with some configurations that should apply to each of the columns (whether a column is sortable, hidable, etc). + +```ts +interface TableViewHeader { + /** Must be unique for each column, see Reserved Header Keys section for more information about 'actions' key value */ + key: string + /** Visible column header text */ + label: string + /** This property defines whether sort icon should be displayed next to the column header and whether the column header will emit sort event upon clicking on it */ + sortable?: boolean + /** Allow toggling column visibility */ + hidable?: boolean + /** When provided, an info icon will be rendered next to the column label, upon hovering on which the tooltip will be revealed */ + tooltip?: string + /** Whether column header text should be hidden (only visible to screen readers) */ + hideLabel?: boolean + /** Only supported in KTableData */ + /** Whether KTableData should use function passed through sortHandlerFunction prop to apply sorting logic to this column */ + useSortHandlerFunction?: boolean +} +``` + + + +```vue + + + +``` + +:::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. +::: + +#### Reserved Header Keys + +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 +::: + + + + + +```vue + + + +``` + +##### 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. +::: + + + + + +```vue + + + +``` + +### data + +Data to be rendered in the table. Accepted interface is an array of objects where each property key should have a corresponding `key` in the [`headers` prop](#headers). + +```ts +type TableViewData = Record[] +``` + + + + + +```vue + + + +``` + +:::tip NOTE +Notice that in the example above the _Username_ column is `sortable` and the _Email_ column is `hidable`. +::: + +### loading + +Boolean to control whether the component should display the loading state. Defaults to `false`. + + + +```html + +``` + +### error + +Boolean to control whether the component should display the error state. Defaults to `false`. See [error state](#error-1) section for more customization options. + + + +```html + +``` + +### resizeColumns + +Allow table column width to be resizable (defaults to `false`). Adjusting a column's width will trigger an [`update:table-preferences` event](#updatetable-preferences). + + + +```html + +``` + +### rowHover + +Boolean to control whether table should display hover state upon hovering rows. Defaults to `true`. + +### tablePreferences + +Can be used to pass object with locally stored preferences for different table configuration options. For example, when user resizes a column in a given table, `update:table-preferences` event will be emitted - you can then save the value and re-apply it next time user encounters this table. + +```ts +interface TablePreferences { + /** the number of items to display per page */ + pageSize?: number + /** the column to sort by's `key` defined in the table headers */ + sortColumnKey?: string + /** the order by which to sort the column, one of `asc` or `desc` */ + sortColumnOrder?: SortColumnOrder + /** the customized column widths, if resizing is allowed */ + columnWidths?: Record + /** column visibility, if visibility is toggleable */ + columnVisibility?: Record +} +``` + + + +```html + +``` + +### rowAttrs + +Function for adding custom attributes to each row. The function should return an object with `key: value` pairs for each attribute. + +The passed function receives row value object as an argument. + + + +```html + +``` + +### rowLink + +Function for turning row into a link. The function receives row value object as an argument and should return an object with two optional parameters: + +```ts +interface RowLink { + /** RouteLocationRaw or url string for row link */ + to?: RouteLocationRaw | string + /** Target for row link */ + target?: '_self' | '_blank' | '_parent' | '_top' +} +``` + + + +```vue + + + + +``` + +### 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)`. + +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 + + + +``` + +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 + +``` + +:::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: + +```ts +type RowBulkAction = boolean | { enabled: boolean, disabledTooltip?: string } +``` + +When the function returns a boolean value of `true`, bulk action selection will be enabled for the row. + +When `false` is returned, the bulk action checkbox will be disabled. + +If an object is returned, the `enabled` property determines if the row can be selected. The `disabledTooltip` value, if provided, will show the string as a tooltip message if the user hovers over the disabled checkbox. + +Default value is `() => true`. + + + + + +```vue + + + +``` + +### cellAttrs + +Function for adding custom attributes to each table cell. The function should return an object with `key: value` pairs for each attribute. + +The passed function receives an object with these parameters as an argument: +```ts +{ + headerKey: string // header key + row: object // row value + rowIndex: number // row index + colIndex: index // column index +} +``` + + + +```html + +``` + +### maxHeight + +Limit the table height by passing a number, in pixels. If the table height exceeds the specified number, it will be scrollable. Table header is a `position: sticky;` element and will always be visible. + + + +```html + +``` + +### paginationAttributes + +Object to be passed to underlying pagination component. See [KPagination props](/components/pagination#props) for more details. Expects an object of type `TablePaginationAttributes`: + +```ts +interface TablePaginationAttributes { + totalCount?: number + pageSizes?: number[] + initialPageSize?: number + currentPage?: number + offset?: boolean + disablePageJump?: boolean + offsetPreviousButtonDisabled?: boolean + offsetNextButtonDisabled?: boolean +} +``` + + + +```html + +``` + +### hidePagination + +A boolean to hide pagination element (defaults to `false`). + +### hidePaginationWhenOptional + +Set this to `true` to hide pagination when the table record count is less than or equal to the page size. Defaults to `false`. + +### rowExpandable + +Function for making a row expandable. The function receives row value object as an argument and should return a boolean value. Default value is `() => false`. + + + + + +```html + + + +``` + +### rowExpanded + +Use this prop to specify the initial expanded / collapsed state for each data row. The function receives the row value object as an argument and should return a boolean value. Default value is `() => false`. When returned value is `true`, a row is rendered expanded. + + + + + +```html + + + +``` + +### hideHeaders + +A boolean to hide table headers. Only recomended when used in nested table. Refer to [Expandable Rows](#expandable-rows) section documentation for more details. Defaults to `false`. + +### nested + +A boolean to disable some of the table features like column visibility, column resizing, bulk actions and hide toolbar element in nested tables. Refer to [Expandable Rows](#expandable-rows) section documentation for more details. Defaults to `false`. + +### hideToolbar + +Prop for hiding toolbar. Useful when elements provided in the toolbar are not actionable (for example, when toolbar contains filter controls, however the fetcher returns no results as there are no records to filter by). + +## States + +### Empty + + + +```html + +``` + +Set the following props to handle empty state: + +- `emptyStateTitle` - Title text for empty state +- `emptyStateMessage` - Message for empty state +- `emptyStateIconVariant` - Icon variant for empty state (see [KEmptyState component props](/components/empty-state#iconvariant)) +- `emptyStateActionMessage` - Button text for empty state action +- `emptyStateActionRoute` - Route for empty state action +- `emptyStateButtonAppearance` - Appearance of empty state action button. See [KButton `appearance` prop](/components/button#appearance) for details + +:::tip +To display an icon inside of action button, you can use the `empty-state-action-icon` slot. +::: + +When the empty state action button is clicked, KTableView emits the `empty-state-action-click` event. + + + + + +```html + + + +``` + +### Error + +Set the `error` prop to `true` to enable the error state. + + + +```html + +``` + +Set the following properties to customize the error state: + +- `errorStateTitle` - Title text for the error state +- `errorStateMessage` - Message for the error state +- `errorStateActionMessage` - Button text for the error state action +- `errorStateActionRoute` - Route for the error state action + +A `error-action-click` event is emitted when error state action button is clicked. + + + +```html + +``` + +## Expandable Rows + +Data presented in a table often requires futher clarification or specification. The [`rowExpandable` prop](#rowexpandable) allows some rows to be toggled, revealing or hiding additional information without the need to navigate away from the current view. Any content can be passed using the [`row-expanded` slot](#row-expanded). However, when displaying a nested table in expanded rows, there are a few important considerations to be aware of. + +### Nested Table With Different Columns + +A nested table represents data that differs from the parent table but is loosely related. This type of nested table does not require any special handling other than setting the [`nested` prop](#nested) to `true`. + +Notice that column visibility, column resizing and bulk actions features, as well as `toolbar` slot, are disabled in nested tables. + + + + + +```html + + + +``` + +:::tip NOTE +Both parent and nested tables in this example contain static data for demonstration purposes. +::: + +### Nested Table With Same Columns + +A nested table that complements the parent table requires some special handling: + +* The `nested` prop must be set to `true` +* Table headers can be hidden using the [`hideHeaders` prop](#hideHeaders). Value still need to be passed through the `headers` prop, and this is where the `nestedHeaders` slot prop becomes useful. It returns an array of header objects, simplifying the synchronization of column visibility when it is enabled in the parent table +* To better align the columns of the parent and nested tables, the `columnWidths` slot prop can be utilized. It returns an object that can be passed to the nested table through the [`tablePreferences` prop](#tablepreferences). Each time a column is resized in the parent table, the nested table will be updated accordingly + +:::warning NOTE +If bulk actions is enabled in parent table, it will be disabled in the nested table. +::: + + + + + + +```html + + + +``` + +:::tip NOTE +Both parent and nested tables in this example contain static data for demonstration purposes. +::: diff --git a/docs/components/parts/tables/shared-slots.md b/docs/components/parts/tables/shared-slots.md new file mode 100644 index 0000000000..d377910b2e --- /dev/null +++ b/docs/components/parts/tables/shared-slots.md @@ -0,0 +1,381 @@ +### Column Header + +You can slot in your custom content into each column header. For that, use column `key` value prefixed with `column-*` like in the example below. + +Slot props: + +* `column` - column header object + + + + + +```html + + + +``` + +### Cell + +You can provide each individual cell's content via slot. Each cell slot is named after the header `key` it corresponds to. + +Slot props: + +* `row` - table row object +* `rowKey` - table row index +* `rowValue` - the cell value + +:::warning NOTE +This slot is not supported for the [`actions` column](#reserved-header-keys). +::: + + + + + +```html + + + +``` + +### Header Tooltip + +Utilize HTML in the column header's tooltip by utilizing this slot. Similar to the column header slot, it uses the column `key` value prefixed with `tooltip-*` as shown in the example below. + +Slot props: + +* `column` - column header object + + + + + +```html + + + +``` + +### toolbar + +The toolbar is rendered directly above the table and is useful for providing table controls like search or filter fields. + + + + + +```html + + + +``` + +:::tip NOTE +If `toolbar` slot is not empty, the column visibility and/or bulk actions (whichever is enabled) dropdowns in the toolbar will be **disabled** when not actionable. +If it is empty, the column visibility and/or bulk actions dropdowns will be **hidden** when not actionable. +::: + +### empty-state + +Slot content to be displayed when empty. + +### empty-state-action-icon + +Slot for icon to be displayed in front of action button text in empty state. See [empty state](#empty) section for example of usage of this slot. + +### error-state + +Slot content to be displayed when in error state. + +### action-items + +Slot for passing action dropdown items. See [KDropdownItem component docs](/components/dropdown#kdropdownitem) for details. + +Slot props: + +* `row` - table row object + +:::tip NOTE +This slot is only available when the `actions` header key is present in [`headers`](#reserved-header-keys). +::: + + + + + +```html + + + +``` + +### bulk-action-items + +Slot for passing bulk action dropdown items. + +Slot props: + +- `selectedRows` - array of selected table row objects + +See also: [`row-select` event](#row-select). + + + + + +```vue + + + +``` + +### bulk-actions + +Slot for passing custom bulk actions trigger element. Content provided through this slot will replace default bulk actions dropdown. + +Slot props: + +- `selectedRows` - array of selected table row objects + + + + + +```html + + + +``` + +### row-expanded + +Slot for passing custom content that will be revealed once user expands one of the table rows when [`rowExpandable` prop](#rowexpandable) is `true`. + +Slot props: + +* `row` - table row object +* `headers` - array of table headers objects to be passed to the nested table. See [Expandable Rows](#expandable-rows) section documentation for more details +* `columnWidths` - an object where each key represents a table column, and its corresponding value specifies the width to be used for that column in a nested table. Refer to [Expandable Rows](#expandable-rows) section documentation for more details + + + + + +```html + + + +``` diff --git a/docs/components/table-data.md b/docs/components/table-data.md index 075a3e6559..7b656121cb 100644 --- a/docs/components/table-data.md +++ b/docs/components/table-data.md @@ -1,3 +1,5 @@ + + # Table Data A table component that wraps [KTableView](/components/table-view) with built-in data fetching functionality. @@ -18,37 +20,8 @@ If you are looking for a simpler table component that does not integrate data fe /> ``` -## Base KTableView Component - -KTableData wraps the KTableView component, adding data fetching functionality. - -KTableData supports all [KTableView props](/components/table-view#props), except for the `data` prop, which is replaced by the [`fetcher` prop](#fetcher). It also supports [slots](/components/table-view#slots) and [events](/components/table-view#events), except for [pagination events](/components/table-view#pagination-events), which KTableData does not emit. Additionally, the `headers` prop and the `update:table-preferences` event are handled differently in KTableData. See the sections below for more details. - ## Props -### headers - -In addition to all header object properties supported by KTableView, KTableData also allows specifying whether a column should be sortable by providing a [`sortHandlerFunction` prop](#sorthandlerfunction). - -```ts -interface TableDataHeader { - /** must be unique for each column, see Reserved Header Keys section for more information about 'actions' key value */ - key: string - /** visible column header text */ - label: string - /** this property defines whether sort icon should be displayed next to the column header and whether the column header will emit sort event upon clicking on it */ - sortable?: boolean - /** allow toggling column visibility */ - hidable?: boolean - /** when provided, an info icon will be rendered next to the column label, upon hovering on which the tooltip will be revealed */ - tooltip?: string - /** whether column header text should be hidden (only visible to screen readers) */ - hideLabel?: boolean - /** Whether KTableData should use function passed through sortHandlerFunction prop to apply sorting logic to this column */ - useSortHandlerFunction?: boolean -} -``` - For an example of `headers` prop usage please refer to [`fetcher` prop documentation](#fetcher) below. ### fetcher @@ -271,7 +244,7 @@ An alternate implementation is to apply a `key` attribute to the KTableData in c Since the `fetcher` function will handle the initial fetch of the data, we want the cache key for the `revalidate` function to be a falsey value on page load (to avoid an unnecessary duplicate call), and will manually call `revalidate()` and increment the `key` to trigger a refetch and redraw of the table. -```html +```vue @@ -315,6 +288,18 @@ A string that will passed to fetcher function and can be used to modify the API Set this to `false` to disable ability to sort. +## KTableView Props + +Since KTableData is a wrapper component around KTableView, it supports all KTableView props, except for the `data` prop, which is replaced by the [`fetcher` prop](#fetcher). For ease of reference, this section includes all KTableView props that KTableData supports. + + + +## Slots + +Since KTableData is a wrapper component around KTableView, it supports all KTableView slots. For ease of reference, this section includes all KTableView slots that KTableData supports. + + + ## Events ### state @@ -334,158 +319,8 @@ type TableState = 'loading' | 'error' | 'success' | 'empty' This event only fires when KTableData is in `success` state (see [`state` event](#state) for details). - + diff --git a/docs/components/table-view.md b/docs/components/table-view.md index 535d2cc68c..bc9f4e548b 100644 --- a/docs/components/table-view.md +++ b/docs/components/table-view.md @@ -1,1517 +1,38 @@ -# Table View - -Component for displaying data in table format. - -:::tip NOTE -KTableView does not handle data management capabilities like data fetching, functional pagination, sorting or searching. If you are looking for a component that integrates with the data layer, check out [KTableData](/components/table-data). -::: - - - -```html - -``` - -## Props - -### headers - -Array of objects that represent table columns along with some configurations that should apply to each of the columns (whether a column is sortable, hidable, etc). - -```ts -interface TableViewHeader { - /** must be unique for each column, see Reserved Header Keys section for more information about 'actions' key value */ - key: string - /** visible column header text */ - label: string - /** this property defines whether sort icon should be displayed next to the column header and whether the column header will emit sort event upon clicking on it */ - sortable?: boolean - /** allow toggling column visibility */ - hidable?: boolean - /** when provided, an info icon will be rendered next to the column label, upon hovering on which the tooltip will be revealed */ - tooltip?: string - /** whether column header text should be hidden (only visible to screen readers) */ - hideLabel?: boolean -} -``` - - - -```vue - - - -``` - -:::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. -::: - -#### Reserved Header Keys - -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 -::: - - - - - -```vue - - - -``` - -##### 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. -::: - - - - - -```vue - - - -``` - -### data - -Data to be rendered in the table. Accepted interface is an array of objects where each property key should have a corresponding `key` in the [`headers` prop](#headers). - -```ts -type TableViewData = Record[] -``` - - - - - -```vue - - - -``` - -:::tip NOTE -Notice that in the example above the _Username_ column is `sortable` and the _Email_ column is `hidable`. -::: - -### loading - -Boolean to control whether the component should display the loading state. Defaults to `false`. - - - -```html - -``` - -### error - -Boolean to control whether the component should display the error state. Defaults to `false`. See [error state](#error-1) section for more customization options. - - - -```html - -``` - -### resizeColumns - -Allow table column width to be resizable (defaults to `false`). Adjusting a column's width will trigger an [`update:table-preferences` event](#updatetable-preferences). - - - -```html - -``` - -### rowHover - -Boolean to control whether table should display hover state upon hovering rows. Defaults to `true`. - -### tablePreferences - -Can be used to pass object with locally stored preferences for different table configuration options. For example, when user resizes a column in a given table, `update:table-preferences` event will be emitted - you can then save the value and re-apply it next time user encounters this table. - -```ts -interface TablePreferences { - /** the number of items to display per page */ - pageSize?: number - /** the column to sort by's `key` defined in the table headers */ - sortColumnKey?: string - /** the order by which to sort the column, one of `asc` or `desc` */ - sortColumnOrder?: SortColumnOrder - /** the customized column widths, if resizing is allowed */ - columnWidths?: Record - /** column visibility, if visibility is toggleable */ - columnVisibility?: Record -} -``` - - - -```html - -``` - -### rowAttrs - -Function for adding custom attributes to each row. The function should return an object with `key: value` pairs for each attribute. - -The passed function receives row value object as an argument. - - - -```html - -``` - -### rowLink - -Function for turning row into a link. The function receives row value object as an argument and should return an object with two optional parameters: - -```ts -interface RowLink { - /** RouteLocationRaw or url string for row link */ - to?: RouteLocationRaw | string - /** Target for row link */ - target?: '_self' | '_blank' | '_parent' | '_top' -} -``` - - - -```vue - - - - -``` - -### 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)`. - -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 - - - -``` - -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 - -``` - -:::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: - -```ts -type RowBulkAction = boolean | { enabled: boolean, disabledTooltip?: string } -``` - -When the function returns a boolean value of `true`, bulk action selection will be enabled for the row. - -When `false` is returned, the bulk action checkbox will be disabled. - -If an object is returned, the `enabled` property determines if the row can be selected. The `disabledTooltip` value, if provided, will show the string as a tooltip message if the user hovers over the disabled checkbox. - -Default value is `() => true`. - - - - - -```vue - - - -``` - -### cellAttrs - -Function for adding custom attributes to each table cell. The function should return an object with `key: value` pairs for each attribute. - -The passed function receives an object with these parameters as an argument: -```ts -{ - headerKey: string // header key - row: object // row value - rowIndex: number // row index - colIndex: index // column index -} -``` - - - -```html - -``` - -### maxHeight - -Limit the table height by passing a number, in pixels. If the table height exceeds the specified number, it will be scrollable. Table header is a `position: sticky;` element and will always be visible. - - - -```html - -``` - -### paginationAttributes - -Object to be passed to underlying pagination component. See [KPagination props](/components/pagination#props) for more details. Expects an object of type `TablePaginationAttributes`: - -```ts -interface TablePaginationAttributes { - totalCount?: number - pageSizes?: number[] - initialPageSize?: number - currentPage?: number - offset?: boolean - disablePageJump?: boolean - offsetPreviousButtonDisabled?: boolean - offsetNextButtonDisabled?: boolean -} -``` - - - -```html - -``` - -### hidePagination - -A boolean to hide pagination element (defaults to `false`). - -### hidePaginationWhenOptional - -Set this to `true` to hide pagination when the table record count is less than or equal to the page size. Defaults to `false`. - -### rowExpandable - -Function for making a row expandable. The function receives row value object as an argument and should return a boolean value. Default value is `() => false`. - - - - - -```html - - - -``` - -### rowExpanded - -Use this prop to specify the initial expanded / collapsed state for each data row. The function receives the row value object as an argument and should return a boolean value. Default value is `() => false`. When returned value is `true`, a row is rendered expanded. - - - - - -```html - - - -``` - -### hideHeaders - -A boolean to hide table headers. Only recomended when used in nested table. Refer to [Expandable Rows](#expandable-rows) section documentation for more details. Defaults to `false`. - -### nested - -A boolean to disable some of the table features like column visibility, column resizing, bulk actions and hide toolbar element in nested tables. Refer to [Expandable Rows](#expandable-rows) section documentation for more details. Defaults to `false`. - -### hideToolbar - -Prop for hiding toolbar. Useful when elements provided in the toolbar are not actionable (for example, when toolbar contains filter controls, however the fetcher returns no results as there are no records to filter by). - -## States - -### Empty - - - -```html - -``` - -Set the following props to handle empty state: - -- `emptyStateTitle` - Title text for empty state -- `emptyStateMessage` - Message for empty state -- `emptyStateIconVariant` - Icon variant for empty state (see [KEmptyState component props](/components/empty-state#iconvariant)) -- `emptyStateActionMessage` - Button text for empty state action -- `emptyStateActionRoute` - Route for empty state action -- `emptyStateButtonAppearance` - Appearance of empty state action button. See [KButton `appearance` prop](/components/button#appearance) for details - -:::tip -To display an icon inside of action button, you can use the `empty-state-action-icon` slot. -::: - -When the empty state action button is clicked, KTableView emits the `empty-state-action-click` event. - - - - - -```html - - - -``` - -### Error - -Set the `error` prop to `true` to enable the error state. - - - -```html - -``` - -Set the following properties to customize the error state: - -- `errorStateTitle` - Title text for the error state -- `errorStateMessage` - Message for the error state -- `errorStateActionMessage` - Button text for the error state action -- `errorStateActionRoute` - Route for the error state action - -A `error-action-click` event is emitted when error state action button is clicked. - - - -```html - -``` + -## Expandable Rows - -Data presented in a table often requires futher clarification or specification. The [`rowExpandable` prop](#rowexpandable) allows some rows to be toggled, revealing or hiding additional information without the need to navigate away from the current view. Any content can be passed using the [`row-expanded` slot](#row-expanded). However, when displaying a nested table in expanded rows, there are a few important considerations to be aware of. - -### Nested Table With Different Columns - -A nested table represents data that differs from the parent table but is loosely related. This type of nested table does not require any special handling other than setting the [`nested` prop](#nested) to `true`. - -Notice that column visibility, column resizing and bulk actions features, as well as `toolbar` slot, are disabled in nested tables. - - - - - -```html - - - -``` - -:::tip NOTE -Both parent and nested tables in this example contain static data for demonstration purposes. -::: - -### Nested Table With Same Columns - -A nested table that complements the parent table requires some special handling: - -* The `nested` prop must be set to `true` -* Table headers can be hidden using the [`hideHeaders` prop](#hideHeaders). Value still need to be passed through the `headers` prop, and this is where the `nestedHeaders` slot prop becomes useful. It returns an array of header objects, simplifying the synchronization of column visibility when it is enabled in the parent table -* To better align the columns of the parent and nested tables, the `columnWidths` slot prop can be utilized. It returns an object that can be passed to the nested table through the [`tablePreferences` prop](#tablepreferences). Each time a column is resized in the parent table, the nested table will be updated accordingly - -:::warning NOTE -If bulk actions is enabled in parent table, it will be disabled in the nested table. -::: - - - - - +# Table View -```html - - - -``` +Component for displaying data in table format. :::tip NOTE -Both parent and nested tables in this example contain static data for demonstration purposes. -::: - -## Slots - -### Column Header - -You can slot in your custom content into each column header. For that, use column `key` value prefixed with `column-*` like in the example below. - -Slot props: - -* `column` - column header object - - - - - -```html - - - -``` - -### Cell - -You can provide each individual cell's content via slot. Each cell slot is named after the header `key` it corresponds to. - -Slot props: - -* `row` - table row object -* `rowKey` - table row index -* `rowValue` - the cell value - -:::warning NOTE -This slot is not supported for the [`actions` column](#reserved-header-keys). +KTableView does not handle data management capabilities like data fetching, functional pagination, sorting or searching. If you are looking for a component that integrates with the data layer, check out [KTableData](/components/table-data). ::: - - - -```html - - - -``` - -### Header Tooltip - -Utilize HTML in the column header's tooltip by utilizing this slot. Similar to the column header slot, it uses the column `key` value prefixed with `tooltip-*` as shown in the example below. - -Slot props: - -* `column` - column header object - - - - - -```html - - - -``` - -### toolbar - -The toolbar is rendered directly above the table and is useful for providing table controls like search or filter fields. - - - - - -```html - - - -``` - -:::tip NOTE -If `toolbar` slot is not empty, the column visibility and/or bulk actions (whichever is enabled) dropdowns in the toolbar will be **disabled** when not actionable. -If it is empty, the column visibility and/or bulk actions dropdowns will be **hidden** when not actionable. -::: - -### empty-state - -Slot content to be displayed when empty. - -### empty-state-action-icon - -Slot for icon to be displayed in front of action button text in empty state. See [empty state](#empty) section for example of usage of this slot. - -### error-state - -Slot content to be displayed when in error state. - -### action-items - -Slot for passing action dropdown items. See [KDropdownItem component docs](/components/dropdown#kdropdownitem) for details. - -Slot props: - -* `row` - table row object - -:::tip NOTE -This slot is only available when the `actions` header key is present in [`headers`](#reserved-header-keys). -::: - - - - - -```html - - - -``` - -### bulk-action-items - -Slot for passing bulk action dropdown items. - -Slot props: - -- `selectedRows` - array of selected table row objects - -See also: [`row-select` event](#row-select). - - - - - -```vue - - - -``` - -### bulk-actions - -Slot for passing custom bulk actions trigger element. Content provided through this slot will replace default bulk actions dropdown. - -Slot props: - -- `selectedRows` - array of selected table row objects - - - - +/> ```html - - +/> ``` -### row-expanded - -Slot for passing custom content that will be revealed once user expands one of the table rows when [`rowExpandable` prop](#rowexpandable) is `true`. - -Slot props: +## Props -* `row` - table row object -* `headers` - array of table headers objects to be passed to the nested table. See [Expandable Rows](#expandable-rows) section documentation for more details -* `columnWidths` - an object where each key represents a table column, and its corresponding value specifies the width to be used for that column in a nested table. Refer to [Expandable Rows](#expandable-rows) section documentation for more details + - - - +## Slots -```html - - - -``` + ## Events -### Row Events - -`@row:{event}` - returns the `Event`, the row item, and the type. `row-click` event is emitted whenever a row is clicked and the row click event handler is emitted, returns the row `data`. - -To avoid firing row clicks by accident, the row click handler ignores events coming from `a`, `button`, `label`, `input`, and `select` elements (unless they have the `disabled` attribute). As such click handlers attached to these element types do not require stopping propagation via `@click.stop`. - -The table in the example below contains buttons, inputs and links to demonstrate how KTableView handles clicks on different interactive elements within the table as well as clicks on its rows. - -Try clicking below on the table row, and then within elements inside the table cells. - - -
- - - - - - -
- - -```html - -``` - -### Cell Events - -`@cell:{event}` - returns the `Event`, the cell value, and the type. `cell-click` event is emitted whenever a cell is clicked and the cell click event handler is emitted, returns the cell `data`. - -The table in the example below contains buttons, inputs and links to demonstrate how KTableView handles clicks on different interactive elements within the table as well as clicks on its cells. - - -
- - - - - - -
- - -```html - -``` + ### Pagination Events @@ -1558,398 +79,14 @@ interface RowExpandPayload { } ``` - - -