[#3279] VaDataTable docs improvement (#3412)

* fix(#3279): update block api in docs

* fix(#3279): fix types and styles in VaDataTable component

* fix(#3279): update VaDataTable docs examples

* fix(#3279): update locales

* fix(#3279): style fixing block components

* fix(#3279): tweak VaValue prop type

* #3279: fix block api component

* #3279: tweak data-table api-options

* #3279: review suggestions

* #3279: review suggestions

packages/docs/modules/page-config/blocks/alert/index.vue

@@ -21,7 +21,7 @@ const { t } = useI18n()
 
 <template>
  <va-alert
- class="page-config-alert my-2"
+ class="page-config-alert"
  :color="color"
  :outline="!solid"
  >
@@ -31,8 +31,13 @@ const { t } = useI18n()
 
 <style lang="scss">
 .page-config-alert {
- p {
- margin: 0;
+ margin-top: 1rem;
+ margin-bottom: 1rem;
+
+ .MarkdownView {
+ p {
+ margin: 0;
+ }
  }
 }
 </style>

packages/docs/modules/page-config/blocks/api/components/api-table.vue

@@ -3,22 +3,29 @@
 import { type PropType } from 'vue'
 import { MarkdownView } from '../../shared/markdown'
 import { Anchor } from '../../shared/anchor'
+import { CodeView } from '../../shared/code';
 
 defineProps({
  data: {
- type: Array as PropType<Record<string, any>[]>
+ type: Array as PropType<Record<string, any>[]>,
+ default: () => ([]),
  },
  columns: {
- type: Array as PropType<string[]>
+ type: Array as PropType<string[]>,
+ default: () => ([]),
  },
  title: {
  type: String,
+ default: '',
  }
 })
 </script>
 
 <template>
- <h4 v-if="title" class="ApiDocs__header">
+ <h4
+ v-if="title"
+ class="ApiDocs__header"
+ >
  {{ title }}
  <Anchor :text="title" />
  </h4>
@@ -37,22 +44,33 @@ defineProps({
  </thead>
  <tbody>
  <tr
- v-for="(row, key) in data"
- :key="key"
+ v-for="(row, index) in data"
+ :key="index"
  class="ApiDocs__table__row"
  >
  <td
- v-for="(data, key) in row"
- :key="data"
+ v-for="(value, key) in row"
+ :key="key"
  >
  <slot
  :name="key"
- v-bind="{ key, data }"
+ v-bind="{ key, data: value }"
  >
  <MarkdownView
- v-if="data"
- :content="data.toString()"
+ v-if="typeof value === 'string'"
+ :content="value.toString()"
  />
+ <div v-if="typeof value === 'object'">
+ <MarkdownView
+ v-if="value.text"
+ :content="value.text.toString()"
+ />
+ <CodeView
+ v-if="value.code"
+ :code="value.code"
+ language="typescript"
+ />
+ </div>
  </slot>
  </td>
  </tr>

packages/docs/modules/page-config/blocks/api/index.vue

@@ -34,7 +34,7 @@ const props = defineProps({
 
 const withManual = computed(() => {
  return merge(props.meta, props.manual as ManualApiOptions)
-}) 
+})
 
 const { t, te, fallbackLocale } = useI18n()
 
@@ -94,7 +94,12 @@ const eventsOptions = computed(() => Object
  .filter(([key, prop]) => !prop.hidden)
  .map(([key, prop]) => ({
  name: key,
- description: t(getTranslation('events', key)),
+ description: prop.types && typeof prop.types === 'string'
+ ? {
+ text: t(getTranslation('events', key)) + '. ' + t(getTranslation('events', 'eventArgument')),
+ code: prop.types
+ }
+ : t(getTranslation('events', key))
  }))
  .sort((a, b) => {
  return a.name.localeCompare(b.name)
@@ -105,7 +110,12 @@ const slotsOptions = computed(() => Object
  .entries(withManual.value.slots || {})
  .map(([key, prop]) => ({
  name: key,
- description: t(getTranslation('slots', key)),
+ description: prop.types
+ ? {
+ text: t(getTranslation('slots', key)) + '. ' + t(getTranslation('slots', 'scopeAvailable')),
+ code: prop.types
+ }
+ : t(getTranslation('slots', key))
  }))
  .sort((a, b) => {
  return a.name.localeCompare(b.name)

packages/docs/modules/page-config/blocks/api/types.ts

@@ -31,13 +31,14 @@ export type ManualMethodApiOptions = ManualApiOptionsItem & {
 }
 
 export type ManualEventApiOptions = ManualApiOptionsItem & {
- types: string;
+ types?: string;
  hidden?: boolean; // Won't appear in documentation. Intended for internal usage events.
  isDOMEvent?: boolean;
  // add more here
 }
 
 export type ManualSlotApiOptions = ManualApiOptionsItem & {
+ types?: string;
  // add more here
 }
 
@@ -65,4 +66,4 @@ export type VisualOptions = {
  hideSlotsTitle?: boolean
  hideCssVariables?: boolean
  hideCssVariablesTitle?: boolean
-}
+}

packages/docs/modules/page-config/blocks/example/index.vue

@@ -76,7 +76,7 @@ const description = computed(() => {
  />
  </template>
 
- <div class="page-config-example mb-3">
+ <div class="page-config-example">
  <va-card
  outlined
  class="page-config-example__card"
@@ -116,6 +116,8 @@ const description = computed(() => {
 
 <style lang="scss" scoped>
 .page-config-example {
+ margin-bottom: 2rem;
+
  &__card {
  border-bottom-left-radius: 0;
  border-bottom-right-radius: 0;

packages/docs/page-config/ui-elements/data-table/api-options.ts

@@ -1,3 +1,96 @@
+const headerScope = `
+{
+ key: string,
+ label: string,
+}`
+
+const cellScope = `
+{
+ cell: DataTableCellScope,
+ row: DataTableRowScope,
+}
+
+// types description
+
+type DataTableCellScope {
+ rowIndex: number, // the same as "initialIndex" in "DataTableRowScope" type
+ rowKey: any,
+ rowData: DataTableItem,
+ column: DataTableColumnScope,
+ source: any,
+ value: string,
+}
+
+type DataTableRowScope {
+ initialIndex: number,
+ itemKey: any,
+ cells: DataTableCellScope[],
+ /** Same rowData as in DataTableCellScope */
+ rowData: DataTableItem,
+}
+
+type DataTableColumnScope {
+ source: DataTableColumn | string,
+ initialIndex: number,
+ key: string,
+ name: string,
+ label: string,
+}
+
+type DataTableItem = Record<string, any>
+`
+
+const cellKeyScope = `
+{
+ rowIndex: number,
+ rowKey: any,
+ rowData: DataTableItem, // the same as in the "cell" slot
+ column: DataTableColumnScope, // the same as in the "cell" slot
+ source: any,
+ value: string,
+ row: DataTableRowScope, // the same as in the "cell" slot
+ isExpanded: boolean,
+}`
+
+const expandableRowScope = `
+{
+ initialIndex: number,
+ itemKey: any,
+ cells: DataTableRowScope[], // the same as in the "cell" slot
+ /** Same rowData as in DataTableRowScope */
+ rowData: DataTableItem, // the same as in the "cell" slot
+ toggleRowDetails: (show?: boolean) => void,
+ isExpandableRowVisible: boolean,
+}`
+
+const filteredEvent = `
+{
+ items: DataTableItem[],
+ itemsIndexes: number[],
+}`
+
+const rowClickEvent = `
+// type RowClickEvent
+{
+ event: Event, // native mouse event
+ item: DataTableItem,
+ itemIndex: number,
+}`
+
+const selectionChangeEvent = `
+{
+ currentSelectedItems: (DataTableItem | DataTableItemKey)[],
+ previousSelectedItems: (DataTableItem | DataTableItemKey)[],
+}`
+
+const sortedEvent = `
+{
+ sortBy: string,
+ sortingOrder: DataTableSortingOrder,
+ items: DataTableItem[],
+ itemsIndexes: number[],
+}`
+
 export default defineManualApi({
  props: {
  columns: {
@@ -21,49 +114,62 @@ export default defineManualApi({
  },
  events: {
  filtered: {
- types: "`() => FilteredEmit`",
+ types: filteredEvent,
  },
  selectionChange: {
- types: "`() => SelectionChangeEmit`",
+ types: selectionChangeEvent,
  },
  sorted: {
- types: "`() => SortedEmit`",
+ types: sortedEvent,
  },
  "update:sortBy": {
- types: "`() => String`",
+ types: 'type String',
  },
  "update:sortingOrder": {
- types: "`() => DataTableSortingOrder`",
+ types: 'type DataTableSortingOrder',
  },
  "row:click": {
- types: "`() => RowClickEmit`",
+ types: rowClickEvent,
  },
  "row:contextmenu": {
- types: "`() => RowClickEmit`",
+ types: 'type RowClickEvent',
  },
  "row:dblclick": {
- types: "`() => RowClickEmit`",
- },
- "scroll:bottom": {
- types: "`() => Event`",
- },
- "scroll:top": {
- types: "`() => Event`",
+ types: 'type RowClickEvent',
  },
+ "scroll:bottom": {},
+ "scroll:top": {},
  },
  slots: {
- colgroup: {},
+ colgroup: {
+ types: 'type DataTableColumnScope[]',
+ },
  headerPrepend: {},
- header: {},
- "header(key)": {},
+ header: {
+ types: headerScope,
+ },
+ "header(key)": {
+ types: headerScope,
+ },
  headerAppend: {},
  bodyPrepend: {},
- cell: {},
- "cell(key)": {},
+ cell: {
+ types: cellScope,
+ },
+ "cell(key)": {
+ types: cellKeyScope,
+ },
  bodyAppend: {},
  footerPrepend: {},
- footer: {},
- "footer(key)": {},
+ footer: {
+ types: headerScope,
+ },
+ "footer(key)": {
+ types: headerScope,
+ },
  footerAppend: {},
+ expandableRow: {
+ types: expandableRowScope,
+ },
  },
 });