bootstrap-vue-next · VividLemon · Apr 22, 2025 · Apr 14, 2025 · Apr 16, 2025 · Apr 17, 2025
diff --git a/apps/docs/src/docs/components/demo/TableProvider.ts b/apps/docs/src/docs/components/demo/TableProvider.ts
@@ -0,0 +1,14 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import type {BTableSortBy, MaybePromise} from 'bootstrap-vue-next'
+// #region snippet
+type BTableProviderContext<T = unknown> = {
+  sortBy: BTableSortBy<T>[] | undefined
+  filter: string | undefined
+  currentPage: number
+  perPage: number
+}
+
+type BTableProvider<T> = (
+  context: Readonly<BTableProviderContext<T>>
+) => MaybePromise<T[] | undefined>
+// #endregion snippet
diff --git 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
+`<BTable>` 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 [`<BPagination>`](/docs/components/pagination) component in conjunction with
+`<BTable>` 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<T>[] \| 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 `<BTable>` 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 `<BTable>` 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
@@ -647,6 +647,20 @@ The `filtered` event has a single argument `Items[]` rather than two arguments w
 
 <NotYetImplemented/> Heading and data row accessibility
 
+### Items Provider Functions
+
+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 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 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 items provider no longer includes an optional 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
@@ -296,6 +296,16 @@ type LinkTarget = '_self' | '_blank' | '_parent' | '_top'
 
 </BCard>
 
+## MaybePromise
+
+<BCard class="bg-body-tertiary">
+
+```ts
+type MaybePromise<T> = Promise<T> | T
+```
+
+</BCard>
+
 ## Placement
 
 <BCard class="bg-body-tertiary">
@@ -495,6 +505,21 @@ type TableItem<T = Record<string, unknown>> = T & {
 
 </BCard>
 
+## TableProvider
+
+```ts
+type BTableProviderContext<T = unknown> = {
+  sortBy: BTableSortBy<T>[] | undefined
+  filter: string | undefined
+  currentPage: number
+  perPage: number
+}
+
+type BTableProvider<T> = (
+  context: Readonly<BTableProviderContext<T>>
+) => MaybePromise<T[] | undefined>
+```
+
 ## TableSortBy
 
 <BCard class="bg-body-tertiary">

diff --git 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'