From 3fca66857d3616bf24a1b0579c90179a7883869d Mon Sep 17 00:00:00 2001
From: Neil Richter <me@neilrichter.com>
Date: Tue, 16 Apr 2024 16:39:52 +0200
Subject: [PATCH] feat(Table): allow providing a `<caption>` (#1680)

---
 .../examples/TableExampleCaptionSlot.vue      | 63 +++++++++++++++++++
 docs/content/2.components/table.md            | 13 ++++
 src/runtime/components/data/Table.vue         |  9 +++
 src/runtime/ui.config/data/table.ts           |  1 +
 4 files changed, 86 insertions(+)
 create mode 100644 docs/components/content/examples/TableExampleCaptionSlot.vue

diff --git a/docs/components/content/examples/TableExampleCaptionSlot.vue b/docs/components/content/examples/TableExampleCaptionSlot.vue
new file mode 100644
index 00000000..ead85e4c
--- /dev/null
+++ b/docs/components/content/examples/TableExampleCaptionSlot.vue
@@ -0,0 +1,63 @@
+<script setup lang="ts">
+const columns = [{
+  key: 'name',
+  label: 'Name'
+}, {
+  key: 'title',
+  label: 'Title'
+}, {
+  key: 'email',
+  label: 'Email'
+}, {
+  key: 'role',
+  label: 'Role'
+}, {
+  key: 'actions'
+}]
+
+const people = [{
+  id: 1,
+  name: 'Lindsay Walton',
+  title: 'Front-end Developer',
+  email: 'lindsay.walton@example.com',
+  role: 'Member'
+}, {
+  id: 2,
+  name: 'Courtney Henry',
+  title: 'Designer',
+  email: 'courtney.henry@example.com',
+  role: 'Admin'
+}, {
+  id: 3,
+  name: 'Tom Cook',
+  title: 'Director of Product',
+  email: 'tom.cook@example.com',
+  role: 'Member'
+}, {
+  id: 4,
+  name: 'Whitney Francis',
+  title: 'Copywriter',
+  email: 'whitney.francis@example.com',
+  role: 'Admin'
+}, {
+  id: 5,
+  name: 'Leonard Krasner',
+  title: 'Senior Designer',
+  email: 'leonard.krasner@example.com',
+  role: 'Owner'
+}, {
+  id: 6,
+  name: 'Floyd Miles',
+  title: 'Principal Designer',
+  email: 'floyd.miles@example.com',
+  role: 'Member'
+}]
+</script>
+
+<template>
+  <UTable :rows="people" :columns="columns">
+    <template #caption>
+      <caption>Employees of ACME</caption>
+    </template>
+  </UTable>
+</template>
diff --git a/docs/content/2.components/table.md b/docs/content/2.components/table.md
index f747feff..63068175 100644
--- a/docs/content/2.components/table.md
+++ b/docs/content/2.components/table.md
@@ -450,6 +450,19 @@ componentProps:
 ---
 ::
 
+### `caption`
+
+Use the `#caption` slot to customize the table's caption.
+
+::component-example
+---
+padding: false
+component: 'table-example-caption-slot'
+componentProps:
+  class: 'flex-1'
+---
+::
+
 ## Props
 
 :component-props
diff --git a/src/runtime/components/data/Table.vue b/src/runtime/components/data/Table.vue
index e85c0ecb..08b6eb9b 100644
--- a/src/runtime/components/data/Table.vue
+++ b/src/runtime/components/data/Table.vue
@@ -1,6 +1,11 @@
 <template>
   <div :class="ui.wrapper" v-bind="attrs">
     <table :class="[ui.base, ui.divide]">
+      <slot v-if="$slots.caption || caption" name="caption">
+        <caption :class="ui.caption">
+          {{ caption }}
+        </caption>
+      </slot>
       <thead :class="ui.thead">
         <tr :class="ui.tr.base">
           <th v-if="modelValue" scope="col" :class="ui.checkbox.padding">
@@ -183,6 +188,10 @@ export default defineComponent({
       type: Object as PropType<{ icon: string, label: string }>,
       default: () => config.default.emptyState
     },
+    caption: {
+      type: String,
+      default: null
+    },
     progress: {
       type: Object as PropType<{ color: ProgressColor, animation: ProgressAnimation }>,
       default: () => config.default.progress
diff --git a/src/runtime/ui.config/data/table.ts b/src/runtime/ui.config/data/table.ts
index 6bf7f4f0..87f989da 100644
--- a/src/runtime/ui.config/data/table.ts
+++ b/src/runtime/ui.config/data/table.ts
@@ -4,6 +4,7 @@ export default {
   divide: 'divide-y divide-gray-300 dark:divide-gray-700',
   thead: 'relative',
   tbody: 'divide-y divide-gray-200 dark:divide-gray-800',
+  caption: 'sr-only',
   tr: {
     base: '',
     selected: 'bg-gray-50 dark:bg-gray-800/50',