From 9acf1cdbbe9ce44acfd21f56c5fd6837024c0929 Mon Sep 17 00:00:00 2001 From: "David W. Gray" Date: Mon, 14 Apr 2025 15:46:13 -0700 Subject: [PATCH 1/3] docs(BTable): complete documentation for table items provider --- .../src/docs/components/demo/TableProvider.ts | 15 ++++++ apps/docs/src/docs/components/table.md | 48 +++++++++++++------ apps/docs/src/docs/migration-guide.md | 14 ++++++ apps/docs/src/docs/types.md | 17 +++++++ 4 files changed, 79 insertions(+), 15 deletions(-) create mode 100644 apps/docs/src/docs/components/demo/TableProvider.ts diff --git a/apps/docs/src/docs/components/demo/TableProvider.ts b/apps/docs/src/docs/components/demo/TableProvider.ts new file mode 100644 index 000000000..99a10aea6 --- /dev/null +++ b/apps/docs/src/docs/components/demo/TableProvider.ts @@ -0,0 +1,15 @@ +/* eslint-disable @typescript-eslint/no-unused-vars */ +import type {BTableSortBy} from 'bootstrap-vue-next' +type MaybePromise = Promise | T +// #region snippet +type BTableProviderContext = { + sortBy: BTableSortBy[] | undefined + filter: string | undefined + currentPage: number + perPage: number +} + +type BTableProvider = ( + context: Readonly> +) => MaybePromise +// #endregion snippet diff --git a/apps/docs/src/docs/components/table.md b/apps/docs/src/docs/components/table.md index ae8bcbbd5..653452c7c 100644 --- a/apps/docs/src/docs/components/table.md +++ b/apps/docs/src/docs/components/table.md @@ -53,15 +53,8 @@ defines the supported optional item record modifier properties <<< DEMO ./demo/TableCellVariants.vue -`items` can also be a reference to a _provider_ function, which returns an `Array` of items data. -Provider functions can also be asynchronous: - -- By returning `null` (or `undefined`) and calling a callback, when the data is ready, with the data - array as the only argument to the callback, -- By returning a `Promise` that resolves to an array. - -See the ["Using Items Provider functions"](#using-items-provider-functions) section below for more -details. +A provider function can be provided instead of setting `items` to return items syncronously or asyncronously. +See the ["Using Items Provider functions"](#using-items-provider-functions) section below for more details. ### Table item notes and warnings @@ -836,22 +829,47 @@ Setting the prop `filter` to null or an empty string will clear local items filt ## Pagination -To Be Completed +`` supports built in pagination of item data. You can control how many rows are displayed +at a time by setting the `per-page` prop to the maximum number of rows you would like displayed, and +use the `current-page` prop to specify which page to display (starting from page `1`). If you set +`current-page` to a value larger than the computed number of pages, then no rows will be shown. + +You can use the [``](/docs/components/pagination) component in conjunction with +`` for providing control over pagination. ## Using items provider functions -To Be Completed +As mentioned under the [Items](#items-record-data) prop section, it is possible to use a function to +provide the row data (items) by specifying a function reference via the `provider` prop and leaving +the `items` prop undefined. + +::: info NOTE +If both the `provider` and `items` props are set, the `provider` will be used and `items` will be ignored. +::: + +The provider function is called with the following signature: + +<<< FRAGMENT ./demo/TableProvider.ts#snippet{ts} + +The `ctx` is the context object associated with the table state, and contains the following +properties: + +| Property | Type | Description | +| ------------- | -------------------------------- | --------------------------------------------------------------------------------- | +| `currentPage` | `number` | The current page number (starting from 1, the value of the `current-page` prop) | +| `perPage` | `number` | The maximum number of rows per page to display (the value of the `per-page` prop) | +| `filter` | `string \| undefined` | The value of the `filter` prop | +| `sortBy` | `BTableSortBy[] \| undefined` | The current column key being sorted, or an empty string if not sorting | -Below are trimmed down versions of the [complete example](#complete-example) as a starting place for using provider functions until docs for the provider function are completed. They use local provider functions that implement -sorting and filtering. Note that sorting is done in cooperation with `` by having the +Below are trimmed down versions of the [complete example](#complete-example) as a starting place for using provider functions. They use local provider functions that implement sorting and filtering. Note that sorting is done in cooperation with `` by having the provider function react to the `context.sortBy` array that it is passed, while filtering is done entirely by the provider, which manually forces a refresh of the table when the filter is changed. -This version uses a syncronous provider funtion: +Example using a syncronous provider function: <<< DEMO ./demo/TableProvider.vue -This version uses an asyncronous provider function that simulates latency by sleeping for a second: +Example using an asyncronous provider function that simulates latency by sleeping for a second: <<< DEMO ./demo/TableProviderAsync.vue diff --git a/apps/docs/src/docs/migration-guide.md b/apps/docs/src/docs/migration-guide.md index 0a52fcbf7..a24a3be5b 100644 --- a/apps/docs/src/docs/migration-guide.md +++ b/apps/docs/src/docs/migration-guide.md @@ -647,6 +647,20 @@ The `filtered` event has a single argument `Items[]` rather than two arguments w Heading and data row accessibility +### Items Provider Functions + +In order to use an items provider, set the `provider` prop to a provider function and leave the +`items` prop undefined (unlike in BootstrapVue, where the `items` prop was overloaded). See +our [documentation](/docs/components/table#using-items-provider-functions) for details. + +The item provider function `ctx` parameter now contains `sortBy` array rather than `sortBy` and `sortDesc` fields - +see the [sorting docs](/docs/components/table#sorting) for details + +The table prop `api-url` and the item provider function `ctx` parameter `apiUrl` field are both deperecdated +as they are easily replaced by direct management of the api call by the user. + +The item provider no longer includes an optionnal callback parameter, use the async method of calling instead. + ### Field Definitions `formatter` Only the callback function value for this field is implemented, adding the name diff --git a/apps/docs/src/docs/types.md b/apps/docs/src/docs/types.md index f0a07b297..17cb4bc2a 100644 --- a/apps/docs/src/docs/types.md +++ b/apps/docs/src/docs/types.md @@ -495,6 +495,23 @@ type TableItem> = T & { +## TableProvider + +```ts +type MaybePromise = Promise | T + +type BTableProviderContext = { + sortBy: BTableSortBy[] | undefined + filter: string | undefined + currentPage: number + perPage: number +} + +type BTableProvider = ( + context: Readonly> +) => MaybePromise +``` + ## TableSortBy From f2c5f4d9ef226c5cdd2e72710d70fc5e2dce6d6c Mon Sep 17 00:00:00 2001 From: "David W. Gray" Date: Wed, 16 Apr 2025 08:21:47 -0700 Subject: [PATCH 2/3] Update apps/docs/src/docs/migration-guide.md Co-authored-by: Issayah --- apps/docs/src/docs/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/src/docs/migration-guide.md b/apps/docs/src/docs/migration-guide.md index a24a3be5b..f8b3b10bf 100644 --- a/apps/docs/src/docs/migration-guide.md +++ b/apps/docs/src/docs/migration-guide.md @@ -659,7 +659,7 @@ see the [sorting docs](/docs/components/table#sorting) for details The table prop `api-url` and the item provider function `ctx` parameter `apiUrl` field are both deperecdated as they are easily replaced by direct management of the api call by the user. -The item provider no longer includes an optionnal callback parameter, use the async method of calling instead. +The item provider no longer includes an optional callback parameter, use the async method of calling instead. ### Field Definitions From 43fcdfc14fd988a94d07f08e5a7ad08531c7e512 Mon Sep 17 00:00:00 2001 From: "David W. Gray" Date: Thu, 17 Apr 2025 10:15:50 -0700 Subject: [PATCH 3/3] fix(BTable): export MaybePromise --- apps/docs/src/docs/components/demo/TableProvider.ts | 3 +-- apps/docs/src/docs/migration-guide.md | 8 ++++---- apps/docs/src/docs/types.md | 12 ++++++++++-- packages/bootstrap-vue-next/src/types/index.ts | 1 + 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/apps/docs/src/docs/components/demo/TableProvider.ts b/apps/docs/src/docs/components/demo/TableProvider.ts index 99a10aea6..7361b0a6d 100644 --- a/apps/docs/src/docs/components/demo/TableProvider.ts +++ b/apps/docs/src/docs/components/demo/TableProvider.ts @@ -1,6 +1,5 @@ /* eslint-disable @typescript-eslint/no-unused-vars */ -import type {BTableSortBy} from 'bootstrap-vue-next' -type MaybePromise = Promise | T +import type {BTableSortBy, MaybePromise} from 'bootstrap-vue-next' // #region snippet type BTableProviderContext = { sortBy: BTableSortBy[] | undefined diff --git a/apps/docs/src/docs/migration-guide.md b/apps/docs/src/docs/migration-guide.md index f8b3b10bf..9dba2b8fe 100644 --- a/apps/docs/src/docs/migration-guide.md +++ b/apps/docs/src/docs/migration-guide.md @@ -649,17 +649,17 @@ The `filtered` event has a single argument `Items[]` rather than two arguments w ### Items Provider Functions -In order to use an items provider, set the `provider` prop to a provider function and leave the +To use an items provider, set the `provider` prop to a provider function and leave the `items` prop undefined (unlike in BootstrapVue, where the `items` prop was overloaded). See our [documentation](/docs/components/table#using-items-provider-functions) for details. -The item provider function `ctx` parameter now contains `sortBy` array rather than `sortBy` and `sortDesc` fields - +The items provider function `ctx` parameter now contains `sortBy` array rather than `sortBy` and `sortDesc` fields - see the [sorting docs](/docs/components/table#sorting) for details -The table prop `api-url` and the item provider function `ctx` parameter `apiUrl` field are both deperecdated +The table prop `api-url` and the items provider function `ctx` parameter `apiUrl` field are both deperecdated as they are easily replaced by direct management of the api call by the user. -The item provider no longer includes an optional callback parameter, use the async method of calling instead. +The items provider no longer includes an optional callback parameter, use the async method of calling instead. ### Field Definitions diff --git a/apps/docs/src/docs/types.md b/apps/docs/src/docs/types.md index 17cb4bc2a..9cc310641 100644 --- a/apps/docs/src/docs/types.md +++ b/apps/docs/src/docs/types.md @@ -296,6 +296,16 @@ type LinkTarget = '_self' | '_blank' | '_parent' | '_top' +## MaybePromise + + + +```ts +type MaybePromise = Promise | T +``` + + + ## Placement @@ -498,8 +508,6 @@ type TableItem> = T & { ## TableProvider ```ts -type MaybePromise = Promise | T - type BTableProviderContext = { sortBy: BTableSortBy[] | undefined filter: string | undefined diff --git a/packages/bootstrap-vue-next/src/types/index.ts b/packages/bootstrap-vue-next/src/types/index.ts index df3236fae..174020eb2 100644 --- a/packages/bootstrap-vue-next/src/types/index.ts +++ b/packages/bootstrap-vue-next/src/types/index.ts @@ -85,3 +85,4 @@ export { type DirectiveType, } from './BootstrapVueOptions' export type {ValidationState} from './CommonTypes' +export type {MaybePromise} from './MaybePromise'