@indielayer/ui 1.18.1 → 2.1.0

package/src/components/table/Table.vue

@@ -1,58 +1,97 @@
 <script lang="ts">
+import { optionalBooleanProp } from '../../common/props'
+
 const tableProps = {
   headers: {
     type: Array as PropType<TableHeader[]>,
     default: () => [],
+    description: 'Column definitions (text, value, sortable, align, width, etc.).',
   },
   items: {
     type: Array,
     default: () => [],
+    description: 'Row data array. Cell values resolve from each header `value` path.',
   },
   sort: {
     type: Array as PropType<string[]>,
     default: () => [],
+    description: 'Active sort entries as `column,-1|1` (use with `v-model:sort`).',
+  },
+  sortMultiple: optionalBooleanProp('Allow sorting by multiple columns at once.'),
+  loading: {
+    type: Boolean,
+    description: 'Shows loading rows (skeletons) and a spinner overlay.',
+  },
+  loadingSkeleton: {
+    type: Boolean,
+    description: 'When set, loading rows use skeleton placeholders.',
   },
-  loading: Boolean,
-  loadingSkeleton: Boolean,
   loadingLines: {
     type: [Number, String],
     default: 3,
+    description: 'Number of skeleton rows shown while loading.',
+  },
+  error: {
+    type: Boolean,
+    description: 'Shows the error slot instead of rows.',
   },
-  error: Boolean,
-  dense: Boolean,
-  fixed: Boolean,
-  striped: Boolean,
-  pointer: Boolean,
+  dense: optionalBooleanProp('Compact cell padding.'),
+  fixed: optionalBooleanProp('Fixed table layout for consistent column widths.'),
+  striped: optionalBooleanProp('Alternating row background colors.'),
+  pointer: optionalBooleanProp('Pointer cursor on rows (also set when `toFn` or `hrefFn` is used).'),
   scrollable: {
     type: Boolean,
     default: true,
+    description: 'Enables horizontal overflow scrolling for wide tables.',
   },
   stickyHeader: {
     type: Boolean,
     default: true,
+    description: 'Keeps the header row sticky while scrolling.',
+  },
+  expandable: optionalBooleanProp('Adds an expand control and `expanded-row` slot per row.'),
+  virtualList: optionalBooleanProp('Virtualizes rows for large datasets.'),
+  virtualListOffsetTop: {
+    type: Number,
+    description: 'Top spacer offset (px) when using virtual list.',
+  },
+  virtualListOffsetBottom: {
+    type: Number,
+    description: 'Bottom spacer offset (px) when using virtual list.',
   },
-  expandable: Boolean,
-  virtualList: Boolean,
-  virtualListOffsetTop: Number,
-  virtualListOffsetBottom: Number,
   virtualListItemHeight: {
     type: Number,
     default: 54,
+    description: 'Fixed row height (px) for virtual list measurement.',
   },
   virtualListOverscan: {
     type: Number,
     default: 10,
+    description: 'Extra rows rendered above/below the viewport when virtualized.',
   },
-  keyProp: String,
-  selectable: Boolean,
-  singleSelect: Boolean,
+  keyProp: {
+    type: String,
+    description: 'Item property used as the stable row key (falls back to index).',
+  },
+  selectable: optionalBooleanProp('Enables row selection (`v-model:selected`).'),
+  singleSelect: optionalBooleanProp('Select only one row at a time.'),
   autoClearSelected: {
     type: Boolean,
     default: true,
+    description: 'Clears selection entries that no longer exist in `items`.',
+  },
+  toFn: {
+    type: Function as PropType<(item: unknown) => string | Record<string, unknown> | undefined>,
+    description: 'Returns a Vue Router location to make each cell a link.',
+  },
+  hrefFn: {
+    type: Function as PropType<(item: unknown) => string>,
+    description: 'Returns an href to make each cell an anchor.',
+  },
+  hrefTarget: {
+    type: String as PropType<'_blank' | '_self' | '_parent' | '_top'>,
+    description: 'Target for links created by `hrefFn`.',
   },
-  toFn: Function as PropType<(item: unknown) => string | Record<string, unknown> | undefined>,
-  hrefFn: Function as PropType<(item: unknown) => string>,
-  hrefTarget: String as PropType<'_blank' | '_self' | '_parent' | '_top'>,
 }
 
 export type TableHeader = {
@@ -72,7 +111,28 @@ export type TableProps = ExtractPublicPropTypes<typeof tableProps>
 type InternalClasses = 'wrapper' | 'table' | 'loadingWrapper'
 export interface TableTheme extends ThemeComponent<TableProps, InternalClasses> {}
 
-export default { name: 'XTable' }
+export default {
+  name: 'XTable',
+  docs: {
+    slots: {
+      title: 'Optional title above the table.',
+      actions: 'Optional actions above the table.',
+      'header-[column]': 'Header cell content for a column (`header-{value}`).',
+      'item-[column]': 'Cell content for a column (`item-{value}`).',
+      'loading-[column]': 'Loading cell content for a column (`loading-{value}`).',
+      'footer-[column]': 'Footer cell content for a column (`footer-{value}`).',
+      footer: 'Custom footer (`tfoot`); overrides per-column footer slots when provided.',
+      empty: 'Content when there are no items.',
+      error: 'Content when `error` is true.',
+      'expanded-row': 'Expanded content for a row when `expandable` is set.',
+    },
+    emits: {
+      'update:sort': 'Emitted when sort changes (`v-model:sort`).',
+      'update:selected': 'Emitted when selection changes (`v-model:selected`).',
+      'click-row': 'Emitted when a row is clicked; payload is `(item, index)`.',
+    },
+  },
+}
 </script>
 
 <script setup lang="ts" generic="T">
@@ -174,7 +234,26 @@ function getSort(headerValue: string | undefined, sort: string[]): TableHeaderSo
 }
 
 function sortHeader(header: TableHeader) {
-  // update sort array
+  if (!header.value) return
+
+  if (!props.sortMultiple) {
+    const index = props.sort.findIndex((entry) => entry.split(',')[0] === header.value)
+
+    if (index >= 0) {
+      const order = props.sort[index].split(',')[1]
+
+      if (order === '-1') {
+        emit('update:sort', [`${header.value},1`])
+      } else {
+        emit('update:sort', [])
+      }
+    } else {
+      emit('update:sort', [`${header.value},-1`])
+    }
+
+    return
+  }
+
   const sort = props.sort.slice(0)
   let exists = false
 
@@ -185,11 +264,9 @@ function sortHeader(header: TableHeader) {
       exists = true
 
       if (order === '-1') {
-        // update position to 1
         sort.splice(i, 1, `${header.value},1`)
         break
       } else if (order === '1') {
-        // delete position
         sort.splice(i, 1)
         break
       }

package/src/components/table/TableCell.vue

@@ -1,4 +1,6 @@
 <script lang="ts">
+import { optionalBooleanProp } from '../../common/props'
+
 const validators = {
   textAlign: [null, 'left', 'center', 'right', 'justify'] as const,
   verticalAlign: [null, 'baseline', 'bottom', 'middle', 'text-bottom', 'text-top', 'top'] as const,
@@ -7,18 +9,32 @@ const tableCellProps = {
   textAlign: {
     type: String as PropType<TableCellTextAlign>,
     validator: (value: string) => validators.textAlign.includes(value as any),
+    description: 'Horizontal text alignment.',
+  },
+  truncate: optionalBooleanProp('Truncates overflowing cell content with an ellipsis.'),
+  dense: optionalBooleanProp('Compact cell padding.'),
+  width: {
+    type: [String, Number],
+    description: 'Fixed cell width (number is treated as px).',
   },
-  truncate: Boolean,
-  dense: Boolean,
-  width: [String, Number],
   verticalAlign: {
     type: String as PropType<TableCellVerticalAlign>,
     default: 'middle',
     validator: (value: string) => validators.verticalAlign.includes(value as any),
+    description: 'Vertical alignment of cell content.',
+  },
+  to: {
+    type: [String, Object],
+    description: 'Vue Router location; wraps cell content in a router-link.',
+  },
+  href: {
+    type: String,
+    description: 'Anchor href; wraps cell content in a link.',
+  },
+  target: {
+    type: String as PropType<'_blank' | '_self' | '_parent' | '_top'>,
+    description: 'Link target when `href` or `to` is set.',
   },
-  to: [String, Object],
-  href: String,
-  target: String as PropType<'_blank' | '_self' | '_parent' | '_top'>,
 }
 
 export type TableCellTextAlign = typeof validators.textAlign[number]
@@ -31,6 +47,11 @@ export interface TableCellTheme extends ThemeComponent<TableCellProps, InternalC
 export default {
   name: 'XTableCell',
   validators,
+  docs: {
+    slots: {
+      default: 'Cell content.',
+    },
+  },
 }
 </script>
 

package/src/components/table/TableHead.vue

@@ -1,6 +1,8 @@
 <script lang="ts">
+import { optionalBooleanProp } from '../../common/props'
+
 const tableHeadProps = {
-  stickyHeader: Boolean,
+  stickyHeader: optionalBooleanProp('Keeps the header row sticky while the table scrolls.'),
 }
 
 export type TableHeadProps = ExtractPublicPropTypes<typeof tableHeadProps>
@@ -8,7 +10,14 @@ export type TableHeadProps = ExtractPublicPropTypes<typeof tableHeadProps>
 type InternalClasses = 'thead' | 'row'
 export interface TableHeadTheme extends ThemeComponent<TableHeadProps, InternalClasses> {}
 
-export default { name: 'XTableHead' }
+export default {
+  name: 'XTableHead',
+  docs: {
+    slots: {
+      default: 'Header cells (`x-table-header` children).',
+    },
+  },
+}
 </script>
 
 <script setup lang="ts">

package/src/components/table/TableHeader.vue

@@ -1,4 +1,6 @@
 <script lang="ts">
+import { optionalBooleanProp } from '../../common/props'
+
 const validators = {
   sort: [1, -1, undefined] as const,
   textAlign: ['left', 'center', 'right'] as const,
@@ -8,14 +10,19 @@ const tableHeaderProps = {
   sort: {
     type: Number as PropType<TableHeaderSort>,
     validator: (value: number) => validators.sort.includes(value as any),
+    description: 'Current sort direction: `1` ascending, `-1` descending, or unset.',
   },
-  sortable: Boolean,
+  sortable: optionalBooleanProp('Shows the sort icon and enables sort interaction.'),
   textAlign: {
     type: String as PropType<TableHeaderAlign>,
     default: 'left',
     validator: (value: string) => validators.textAlign.includes(value as any),
+    description: 'Horizontal alignment of the header label.',
+  },
+  tooltip: {
+    type: String,
+    description: 'Optional tooltip shown next to the header label.',
   },
-  tooltip: String,
 }
 
 export type TableHeaderSort = typeof validators.sort[number]
@@ -25,7 +32,15 @@ export type TableHeaderProps = ExtractPublicPropTypes<typeof tableHeaderProps>
 type InternalClasses = 'th' | 'sortIcon' | 'header'
 export interface TableHeaderTheme extends ThemeComponent<TableHeaderProps, InternalClasses> {}
 
-export default { name: 'XTableHeader', validators }
+export default {
+  name: 'XTableHeader',
+  validators,
+  docs: {
+    slots: {
+      default: 'Header label content.',
+    },
+  },
+}
 </script>
 
 <script setup lang="ts">

package/src/components/table/TableRow.vue

@@ -1,17 +1,23 @@
 <script lang="ts">
+import { optionalBooleanProp } from '../../common/props'
+
 const validators = {
   verticalAlign: ['baseline', 'bottom', 'middle', 'text-bottom', 'text-top', 'top'],
 }
 
 const tableRowProps = {
-  pointer: Boolean,
-  striped: Boolean,
-  selected: Boolean,
-  singleSelect: Boolean,
+  pointer: optionalBooleanProp('Pointer cursor on the row.'),
+  striped: optionalBooleanProp('Applies striped row styling.'),
+  selected: {
+    type: Boolean,
+    description: 'Marks the row as selected.',
+  },
+  singleSelect: optionalBooleanProp('Single-select styling for the selected row.'),
   verticalAlign: {
     type: String as PropType<'baseline' | 'bottom' | 'middle' | 'text-bottom' | 'text-top' | 'top'>,
     default: 'top',
     validator: (value: string) => validators.verticalAlign.includes(value),
+    description: 'Vertical alignment for cells in the row.',
   },
 }
 
@@ -20,7 +26,15 @@ export type TableRowProps = ExtractPublicPropTypes<typeof tableRowProps>
 type InternalClasses = 'row'
 export interface TableRowTheme extends ThemeComponent<TableRowProps, InternalClasses> {}
 
-export default { name: 'XTableRow', validators }
+export default {
+  name: 'XTableRow',
+  validators,
+  docs: {
+    slots: {
+      default: 'Row cells (`x-table-cell` children).',
+    },
+  },
+}
 </script>
 
 <script setup lang="ts">

package/src/components/table/__tests__/Table.spec.ts

@@ -1,6 +1,29 @@
 import { describe, it, expect } from 'vitest'
 import { mount } from '@vue/test-utils'
 import Table from '../Table.vue'
+import type { TableHeader } from '../Table.vue'
+
+const sortableHeaders: TableHeader[] = [
+  { text: 'ID', value: 'id', sortable: true },
+  { text: 'Name', value: 'name', sortable: true },
+]
+
+function mountTable(props: Record<string, unknown> = {}) {
+  return mount(Table, {
+    props: {
+      headers: sortableHeaders,
+      items: [{ id: 1, name: 'A' }, { id: 2, name: 'B' }],
+      sort: [],
+      ...props,
+    },
+  })
+}
+
+function clickSortableHeader(wrapper: ReturnType<typeof mountTable>, index: number) {
+  const headers = wrapper.findAll('th')
+
+  return headers[index].trigger('click')
+}
 
 describe('Table', () => {
   it('renders without errors', () => {
@@ -8,4 +31,34 @@ describe('Table', () => {
 
     expect(wrapper.vm).toBeTruthy()
   })
+
+  describe('sort', () => {
+    it('defaults to single-column sort', async () => {
+      const wrapper = mountTable()
+
+      await clickSortableHeader(wrapper, 0)
+      expect(wrapper.emitted('update:sort')?.[0]).toEqual([['id,-1']])
+
+      await clickSortableHeader(wrapper, 1)
+      expect(wrapper.emitted('update:sort')?.[1]).toEqual([['name,-1']])
+    })
+
+    it('cycles sort order for the active column in single-column mode', async () => {
+      const wrapper = mountTable({ sort: ['id,-1'] })
+
+      await clickSortableHeader(wrapper, 0)
+      expect(wrapper.emitted('update:sort')?.[0]).toEqual([['id,1']])
+
+      await wrapper.setProps({ sort: ['id,1'] })
+      await clickSortableHeader(wrapper, 0)
+      expect(wrapper.emitted('update:sort')?.[1]).toEqual([[]])
+    })
+
+    it('appends columns when sortMultiple is enabled', async () => {
+      const wrapper = mountTable({ sortMultiple: true, sort: ['id,-1'] })
+
+      await clickSortableHeader(wrapper, 1)
+      expect(wrapper.emitted('update:sort')?.[0]).toEqual([['id,-1', 'name,-1']])
+    })
+  })
 })

package/src/components/table/theme/Table.carbon.theme.ts

@@ -2,7 +2,7 @@ import type { TableTheme } from '../Table.vue'
 
 const theme: TableTheme = {
   classes: {
-    wrapper: 'w-full h-full shadow-sm overflow-x-auto text-sm bg-white dark:bg-secondary-800',
+    wrapper: 'w-full h-full shadow-xs overflow-x-auto text-sm bg-white dark:bg-secondary-800',
 
     table: ({ props }) => {
       const classes = ['w-full relative']

package/src/components/tag/Tag.vue

@@ -1,17 +1,26 @@
 <script lang="ts">
+import { optionalBooleanProp } from '../../common/props'
+
 const tagProps = {
   ...useCommon.props(),
   ...useColors.props('secondary'),
   tag: {
     type: String,
     default: 'span',
+    description: 'Root element tag. Becomes an anchor or router-link when `href` or `to` is set.',
+  },
+  rounded: optionalBooleanProp('Fully rounded corners (pill shape).'),
+  removable: optionalBooleanProp('Shows a remove control that emits `remove`.'),
+  outlined: optionalBooleanProp('Outline style with a transparent fill.'),
+  filled: optionalBooleanProp('Filled style using the theme color.'),
+  disabled: {
+    type: Boolean,
+    description: 'Disables the remove control and applies disabled styling.',
+  },
+  to: {
+    type: [String, Object],
+    description: 'Vue Router location; renders as a link when set.',
   },
-  rounded: Boolean,
-  removable: Boolean,
-  outlined: Boolean,
-  filled: Boolean,
-  disabled: Boolean,
-  to: [String, Object],
 }
 
 export type TagProps = ExtractPublicPropTypes<typeof tagProps>
@@ -24,6 +33,15 @@ export default {
   validators: {
     ...useCommon.validators(),
   },
+  docs: {
+    slots: {
+      default: 'Tag label and content.',
+      prefix: 'Content shown before the label.',
+    },
+    emits: {
+      remove: 'Emitted when the remove icon is clicked.',
+    },
+  },
 }
 </script>
 
@@ -32,11 +50,13 @@ import { computed, useAttrs, type ExtractPublicPropTypes } from 'vue'
 import { useColors } from '../../composables/useColors'
 import { useCommon } from '../../composables/useCommon'
 import { useTheme, type ThemeComponent } from '../../composables/useTheme'
+import { useResolvedComponentProps } from '../../composables/resolveComponentDefaults'
 import { closeIcon } from '../../common/icons'
 
 import XIcon from '../icon/Icon.vue'
 
 const props = defineProps(tagProps)
+const resolvedProps = useResolvedComponentProps('Tag', props)
 
 defineEmits(['remove'])
 
@@ -65,15 +85,15 @@ const { styles, classes, className } = useTheme('Tag', {}, props)
       [
         className,
         classes.wrapper,
-        outlined ?
+        resolvedProps.outlined ?
           'border-[color:var(--x-tag-border)] dark:border-[color:var(--x-tag-dark-border)]' :
           '!border-transparent bg-[color:var(--x-tag-bg)] dark:bg-[color:var(--x-tag-dark-bg)]',
-        rounded ? 'rounded-full' : 'rounded'
+        resolvedProps.rounded ? 'rounded-full' : 'rounded'
       ]"
   >
     <span
       class="max-w-full"
-      :class="{'pr-4': removable }"
+      :class="{'pr-4': resolvedProps.removable }"
     >
       <div class="flex items-center gap-2">
         <slot name="prefix"></slot>
@@ -83,7 +103,7 @@ const { styles, classes, className } = useTheme('Tag', {}, props)
         </div>
       </div>
 
-      <div v-if="removable" class="absolute right-1.5 top-0 h-full flex items-center">
+      <div v-if="resolvedProps.removable" class="absolute right-1.5 top-0 h-full flex items-center">
         <x-icon
           :size="closeIconSize"
           :icon="closeIcon"