@pgcorp/ui-kit 0.1.0

package/src/components/shared/database/SDataGrid.vue

@@ -0,0 +1,464 @@
+<template>
+  <SPanel
+    v-bind="ownedAttrs.bindings()"
+    :title="validatedTitle"
+    :title-id="validatedTitle ? generatedTitleId : undefined"
+    :footer-id="hasStatus ? generatedStatusId : undefined"
+    :heading-level="3"
+    no-content-padding
+    content-layout="block"
+    surface-overflow="clip"
+  >
+    <template v-if="$slots.actions" #actions>
+      <slot
+        name="actions"
+        :pending-count="pendingCount"
+        :readonly="validatedReadOnly"
+        :disabled="validatedDisabled"
+      />
+    </template>
+
+    <STable
+      :columns="tableColumns"
+      :data="validatedGrid.rows"
+      :get-row-key="getRowKey"
+      :loading="validatedLoading"
+      loading-message="Загрузка данных..."
+      :error-message="errorMessage"
+      :empty-message="emptyMessage"
+      :selected-row-key="selectedRowId"
+      :max-height="validatedMaxHeight"
+      density="compact"
+      :row-state="rowState"
+      :cell-state="cellState"
+      surface="plain"
+      :aria-label="resolvedAccessibleName.ariaLabel"
+      :aria-labelledby="resolvedAccessibleName.ariaLabelledby"
+      :aria-describedby="hasStatus ? generatedStatusId : undefined"
+    >
+      <template #column="{ column }">
+        <slot name="column" :column="resolveColumn(column.field)">{{ column.header }}</slot>
+      </template>
+      <template #cell="{ row, column: tableColumn }">
+        <slot
+          name="cell"
+          :row="row"
+          :column="resolveColumn(tableColumn.field)"
+          :cell="resolveCell(row, tableColumn.field)"
+          :editable="isEditable(row, resolveColumn(tableColumn.field))"
+          :edit="(value: string) => editCell(row, resolveColumn(tableColumn.field), value)"
+          :commit="(input: SDataGridCommitInput) => commitCell(row, resolveColumn(tableColumn.field), input)"
+          :cancel="() => cancelCell(row, resolveColumn(tableColumn.field))"
+        >
+          <SInputText
+            v-if="isEditable(row, resolveColumn(tableColumn.field))"
+            :model-value="draftValue(row, resolveColumn(tableColumn.field))"
+            appearance="grid-cell"
+            size="sm"
+            :disabled="validatedDisabled"
+            :aria-label="`${resolveColumn(tableColumn.field).label}: ${row.id}`"
+            @update:model-value="editCell(row, resolveColumn(tableColumn.field), $event)"
+            @blur="commitCell(row, resolveColumn(tableColumn.field), { source: 'draft' })"
+            @keydown.enter.prevent="commitCell(row, resolveColumn(tableColumn.field), { source: 'draft' })"
+            @keydown.escape.prevent="cancelCell(row, resolveColumn(tableColumn.field))"
+          />
+          <span v-else class="s-data-grid__value" :title="resolveCell(row, tableColumn.field).display">
+            {{ resolveCell(row, tableColumn.field).display }}
+          </span>
+        </slot>
+      </template>
+    </STable>
+
+    <template v-if="hasStatus" #footer>
+      <slot name="status" :pending-count="pendingCount">
+        <SStatus
+          :label="`Ожидают применения: ${pendingCount}`"
+          tone="warn"
+          size="sm"
+          live="polite"
+        />
+      </slot>
+    </template>
+  </SPanel>
+</template>
+
+<script lang="ts">
+export type {
+  SDataGridCell,
+  SDataGridCellKind,
+  SDataGridColumn,
+  SDataGridColumnKey,
+  SDataGridCommitInput,
+  SDataGridEditPayload,
+  SDataGridProps,
+  SDataGridRow,
+  SDataGridRowState,
+} from './dataGrid'
+</script>
+
+<script setup lang="ts" generic="ColumnKey extends string = string">
+import { computed, reactive, useId, useSlots, watch } from 'vue'
+import { useOwnedAttrs } from '../../../internal/ownedAttrs'
+import {
+  validateScrollableViewportMaxBlockSize,
+  validateTableColumnInlineSize,
+  validateTableColumnMinInlineSize,
+} from '../../../internal/semanticSizing'
+import {
+  validateBoolean,
+  validateDomId,
+  validateExactString,
+  validateNonEmptyString,
+} from '../../../internal/runtimeContract'
+import SInputText from '../controls/SInputText.vue'
+import SPanel from '../containers/SPanel.vue'
+import SStatus from '../data-display/SStatus.vue'
+import STable from '../data-display/STable.vue'
+import type {
+  STableCellState,
+  STableColumn,
+  STableRowState,
+} from '../data-display/table'
+import type {
+  SDataGridCell,
+  SDataGridColumn,
+  SDataGridColumnKey,
+  SDataGridCommitInput,
+  SDataGridEditPayload,
+  SDataGridProps,
+  SDataGridRow,
+} from './dataGrid'
+
+defineOptions({ inheritAttrs: false })
+
+interface ValidatedGrid<Key extends SDataGridColumnKey> {
+  columns: readonly SDataGridColumn<Key>[]
+  rows: readonly SDataGridRow<Key>[]
+  columnByKey: ReadonlyMap<Key, SDataGridColumn<Key>>
+  rowById: ReadonlyMap<string, SDataGridRow<Key>>
+}
+
+const props = withDefaults(defineProps<SDataGridProps<ColumnKey>>(), {
+  title: undefined,
+  loading: false,
+  disabled: false,
+  readOnly: false,
+  errorMessage: '',
+  emptyMessage: 'Нет строк для отображения',
+  selectedRowId: undefined,
+  maxHeight: 'none',
+  ariaLabel: undefined,
+  ariaLabelledby: undefined,
+})
+
+const ownedAttrs = useOwnedAttrs({ component: 'SDataGrid', owner: 'data grid adapter root' })
+const slots = useSlots()
+
+const emit = defineEmits<{
+  'cell-edit': [payload: SDataGridEditPayload<ColumnKey>]
+  'cell-commit': [payload: SDataGridEditPayload<ColumnKey>]
+  'cell-cancel': [payload: Omit<SDataGridEditPayload<ColumnKey>, 'value'>]
+}>()
+
+const CELL_KINDS = ['text', 'number', 'boolean', 'json', 'datetime', 'binary'] as const
+const COLUMN_ALIGNMENTS = ['left', 'center', 'right'] as const
+const ROW_STATES = ['clean', 'inserted', 'updated', 'deleted'] as const
+const COMMIT_SOURCES = ['draft', 'value'] as const
+
+function assertReadonlyArray(value: unknown, coordinate: string): asserts value is readonly unknown[] {
+  if (Array.isArray(value)) return
+  throw new TypeError(
+    `SDataGrid: ${coordinate} должен быть array. / SDataGrid: ${coordinate} must be an array.`,
+  )
+}
+
+function assertRecord(value: unknown, coordinate: string): asserts value is Record<string, unknown> {
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) return
+  throw new TypeError(
+    `SDataGrid: ${coordinate} должен быть object. / SDataGrid: ${coordinate} must be an object.`,
+  )
+}
+
+function validateOptionalBoolean(coordinate: string, value: unknown): void {
+  if (value !== undefined) validateBoolean('SDataGrid', coordinate, value)
+}
+
+function validateCell(
+  rowId: string,
+  column: SDataGridColumn<ColumnKey>,
+  value: unknown,
+): asserts value is SDataGridCell {
+  const coordinate = `rows[${JSON.stringify(rowId)}].cells[${JSON.stringify(column.key)}]`
+  assertRecord(value, coordinate)
+  if (typeof value.display !== 'string') {
+    throw new TypeError(
+      `SDataGrid: ${coordinate}.display должен быть string. `
+      + `/ SDataGrid: ${coordinate}.display must be a string.`,
+    )
+  }
+  if (value.kind !== undefined) {
+    const kind = validateExactString('SDataGrid', `${coordinate}.kind`, value.kind, CELL_KINDS)
+    if (column.type !== undefined && kind !== column.type) {
+      throw new TypeError(
+        `SDataGrid: ${coordinate}.kind ${JSON.stringify(kind)} не совпадает с column.type ${JSON.stringify(column.type)}. `
+        + `/ SDataGrid: ${coordinate}.kind ${JSON.stringify(kind)} does not match column.type ${JSON.stringify(column.type)}.`,
+      )
+    }
+  }
+  validateOptionalBoolean(`${coordinate}.pending`, value.pending)
+  validateOptionalBoolean(`${coordinate}.readonly`, value.readonly)
+}
+
+const validatedGrid = computed<ValidatedGrid<ColumnKey>>(() => {
+  assertReadonlyArray(props.columns, 'columns')
+  assertReadonlyArray(props.rows, 'rows')
+
+  const columnByKey = new Map<ColumnKey, SDataGridColumn<ColumnKey>>()
+  for (const columnValue of props.columns) {
+    assertRecord(columnValue, 'columns[]')
+    const column = columnValue as unknown as SDataGridColumn<ColumnKey>
+    const key = validateNonEmptyString('SDataGrid', 'columns[].key', column.key) as ColumnKey
+    validateNonEmptyString('SDataGrid', `columns[${JSON.stringify(key)}].label`, column.label)
+    if (columnByKey.has(key)) {
+      throw new TypeError(
+        `SDataGrid: columns содержит duplicate key ${JSON.stringify(key)}. `
+        + `/ SDataGrid: columns contains duplicate key ${JSON.stringify(key)}.`,
+      )
+    }
+    if (column.type !== undefined) {
+      validateExactString('SDataGrid', `columns[${JSON.stringify(key)}].type`, column.type, CELL_KINDS)
+    }
+    if (column.width !== undefined) {
+      validateTableColumnInlineSize('SDataGrid', `columns[${JSON.stringify(key)}].width`, column.width)
+    }
+    if (column.minWidth !== undefined) {
+      validateTableColumnMinInlineSize('SDataGrid', `columns[${JSON.stringify(key)}].minWidth`, column.minWidth)
+    }
+    if (column.align !== undefined) {
+      validateExactString('SDataGrid', `columns[${JSON.stringify(key)}].align`, column.align, COLUMN_ALIGNMENTS)
+    }
+    validateOptionalBoolean(`columns[${JSON.stringify(key)}].editable`, column.editable)
+    columnByKey.set(key, column)
+  }
+
+  const rowById = new Map<string, SDataGridRow<ColumnKey>>()
+  for (const rowValue of props.rows) {
+    assertRecord(rowValue, 'rows[]')
+    const row = rowValue as unknown as SDataGridRow<ColumnKey>
+    const rowId = validateNonEmptyString('SDataGrid', 'rows[].id', row.id)
+    if (rowById.has(rowId)) {
+      throw new TypeError(
+        `SDataGrid: rows содержит duplicate id ${JSON.stringify(rowId)}. `
+        + `/ SDataGrid: rows contains duplicate id ${JSON.stringify(rowId)}.`,
+      )
+    }
+    if (row.state !== undefined) {
+      validateExactString('SDataGrid', `rows[${JSON.stringify(rowId)}].state`, row.state, ROW_STATES)
+    }
+    assertRecord(row.cells, `rows[${JSON.stringify(rowId)}].cells`)
+    const actualKeys = Object.keys(row.cells)
+    for (const actualKey of actualKeys) {
+      if (!columnByKey.has(actualKey as ColumnKey)) {
+        throw new TypeError(
+          `SDataGrid: row ${JSON.stringify(rowId)} содержит unknown cell ${JSON.stringify(actualKey)}. `
+          + `/ SDataGrid: row ${JSON.stringify(rowId)} contains unknown cell ${JSON.stringify(actualKey)}.`,
+        )
+      }
+    }
+    for (const [key, column] of columnByKey) {
+      if (!Object.hasOwn(row.cells, key)) {
+        throw new TypeError(
+          `SDataGrid: row ${JSON.stringify(rowId)} не содержит cell ${JSON.stringify(key)}. `
+          + `/ SDataGrid: row ${JSON.stringify(rowId)} is missing cell ${JSON.stringify(key)}.`,
+        )
+      }
+      validateCell(rowId, column, row.cells[key])
+    }
+    rowById.set(rowId, row)
+  }
+
+  return { columns: props.columns, rows: props.rows, columnByKey, rowById }
+})
+
+const validatedTitle = computed(() => props.title === undefined
+  ? undefined
+  : validateNonEmptyString('SDataGrid', 'title', props.title))
+const generatedTitleId = `s-data-grid-title-${useId()}`
+const generatedStatusId = `s-data-grid-status-${useId()}`
+const resolvedAccessibleName = computed(() => {
+  if (validatedTitle.value !== undefined) {
+    if (props.ariaLabel !== undefined || props.ariaLabelledby !== undefined) {
+      throw new TypeError(
+        'SDataGrid: title уже задаёт accessible name; не передавайте ariaLabel/ariaLabelledby. '
+        + '/ SDataGrid: title already provides the accessible name; do not provide ariaLabel/ariaLabelledby.',
+      )
+    }
+    return { ariaLabel: undefined, ariaLabelledby: generatedTitleId }
+  }
+  if (props.ariaLabel !== undefined && props.ariaLabelledby !== undefined) {
+    throw new TypeError('SDataGrid: задайте только ariaLabel или ariaLabelledby. / SDataGrid: provide only ariaLabel or ariaLabelledby.')
+  }
+  if (props.ariaLabelledby !== undefined) {
+    return {
+      ariaLabel: undefined,
+      ariaLabelledby: validateDomId('SDataGrid', 'ariaLabelledby', props.ariaLabelledby),
+    }
+  }
+  return {
+    ariaLabel: props.ariaLabel === undefined
+      ? 'Таблица данных'
+      : validateNonEmptyString('SDataGrid', 'ariaLabel', props.ariaLabel),
+    ariaLabelledby: undefined,
+  }
+})
+const validatedLoading = computed(() => validateBoolean('SDataGrid', 'loading', props.loading))
+const validatedDisabled = computed(() => validateBoolean('SDataGrid', 'disabled', props.disabled))
+const validatedReadOnly = computed(() => validateBoolean('SDataGrid', 'readOnly', props.readOnly))
+const validatedMaxHeight = computed(() => validateScrollableViewportMaxBlockSize(
+  'SDataGrid',
+  'maxHeight',
+  props.maxHeight,
+))
+
+const tableColumns = computed<readonly STableColumn<SDataGridRow<ColumnKey>, string>[]>(() => (
+  validatedGrid.value.columns.map((column) => ({
+    field: column.key,
+    header: column.label,
+    width: column.width,
+    minWidth: column.minWidth,
+    align: column.align,
+    value: (row: SDataGridRow<ColumnKey>) => resolveCell(row, column.key),
+  }))
+))
+
+const drafts = reactive(new Map<string, Map<ColumnKey, string>>())
+watch(
+  () => [props.columns, props.rows] as const,
+  () => drafts.clear(),
+  { flush: 'sync' },
+)
+
+const pendingCount = computed(() => validatedGrid.value.rows.filter((row) => (
+  row.state !== undefined && row.state !== 'clean'
+)).length)
+const hasStatus = computed(() => Boolean(slots.status) || pendingCount.value > 0)
+
+function getRowKey(row: SDataGridRow<ColumnKey>): string {
+  return row.id
+}
+
+function resolveColumn(key: string): SDataGridColumn<ColumnKey> {
+  const column = validatedGrid.value.columnByKey.get(key as ColumnKey)
+  if (column) return column
+  throw new TypeError(
+    `SDataGrid: table adapter получил unknown column ${JSON.stringify(key)}. `
+    + `/ SDataGrid: table adapter received unknown column ${JSON.stringify(key)}.`,
+  )
+}
+
+function resolveCell(row: SDataGridRow<ColumnKey>, columnKeyValue: string): SDataGridCell {
+  const columnKey = resolveColumn(columnKeyValue).key
+  if (Object.hasOwn(row.cells, columnKey)) return row.cells[columnKey]
+  throw new TypeError(
+    `SDataGrid: row ${JSON.stringify(row.id)} не содержит cell ${JSON.stringify(columnKey)}. `
+    + `/ SDataGrid: row ${JSON.stringify(row.id)} is missing cell ${JSON.stringify(columnKey)}.`,
+  )
+}
+
+function draftRow(rowId: string): Map<ColumnKey, string> | undefined {
+  return drafts.get(rowId)
+}
+
+function draftValue(row: SDataGridRow<ColumnKey>, column: SDataGridColumn<ColumnKey>): string {
+  const rowDrafts = draftRow(row.id)
+  if (rowDrafts?.has(column.key)) {
+    const value = rowDrafts.get(column.key)
+    if (value !== undefined) return value
+    throw new Error(
+      `SDataGrid: draft ${JSON.stringify(row.id)}/${JSON.stringify(column.key)} нарушил string invariant. `
+      + `/ SDataGrid: draft ${JSON.stringify(row.id)}/${JSON.stringify(column.key)} violated the string invariant.`,
+    )
+  }
+  return resolveCell(row, column.key).display
+}
+
+function isEditable(row: SDataGridRow<ColumnKey>, column: SDataGridColumn<ColumnKey>): boolean {
+  return !validatedDisabled.value
+    && !validatedReadOnly.value
+    && row.state !== 'deleted'
+    && column.editable === true
+    && resolveCell(row, column.key).readonly !== true
+}
+
+function editCell(row: SDataGridRow<ColumnKey>, column: SDataGridColumn<ColumnKey>, value: string): void {
+  if (!isEditable(row, column)) return
+  let rowDrafts = draftRow(row.id)
+  if (!rowDrafts) {
+    rowDrafts = new Map<ColumnKey, string>()
+    drafts.set(row.id, rowDrafts)
+  }
+  rowDrafts.set(column.key, value)
+  emit('cell-edit', { rowId: row.id, columnKey: column.key, value })
+}
+
+function validateCommitInput(input: unknown): SDataGridCommitInput {
+  assertRecord(input, 'commit input')
+  const source = validateExactString('SDataGrid', 'commit input.source', input.source, COMMIT_SOURCES)
+  const hasValue = Object.hasOwn(input, 'value')
+  if (source === 'draft' && hasValue) {
+    throw new TypeError(
+      'SDataGrid: draft commit не должен содержать value. / SDataGrid: draft commit must not contain value.',
+    )
+  }
+  if (source === 'value' && !hasValue) {
+    throw new TypeError(
+      'SDataGrid: value commit должен содержать value. / SDataGrid: value commit must contain value.',
+    )
+  }
+  return source === 'draft' ? { source } : { source, value: input.value }
+}
+
+function clearDraft(rowId: string, columnKey: ColumnKey): void {
+  const rowDrafts = draftRow(rowId)
+  if (!rowDrafts) return
+  rowDrafts.delete(columnKey)
+  if (rowDrafts.size === 0) drafts.delete(rowId)
+}
+
+function commitCell(
+  row: SDataGridRow<ColumnKey>,
+  column: SDataGridColumn<ColumnKey>,
+  inputValue: SDataGridCommitInput,
+): void {
+  if (!isEditable(row, column)) return
+  const input = validateCommitInput(inputValue)
+  const rowDrafts = draftRow(row.id)
+  if (input.source === 'draft' && !rowDrafts?.has(column.key)) return
+  const committed = input.source === 'value' ? input.value : rowDrafts?.get(column.key)
+  if (input.source === 'draft' && committed === undefined) {
+    throw new Error(
+      `SDataGrid: draft ${JSON.stringify(row.id)}/${JSON.stringify(column.key)} исчез до commit. `
+      + `/ SDataGrid: draft ${JSON.stringify(row.id)}/${JSON.stringify(column.key)} disappeared before commit.`,
+    )
+  }
+  clearDraft(row.id, column.key)
+  emit('cell-commit', { rowId: row.id, columnKey: column.key, value: committed })
+}
+
+function cancelCell(row: SDataGridRow<ColumnKey>, column: SDataGridColumn<ColumnKey>): void {
+  if (!isEditable(row, column)) return
+  if (!draftRow(row.id)?.has(column.key)) return
+  clearDraft(row.id, column.key)
+  emit('cell-cancel', { rowId: row.id, columnKey: column.key })
+}
+
+function rowState(row: SDataGridRow<ColumnKey>): STableRowState {
+  return row.state === undefined || row.state === 'clean' ? 'default' : row.state
+}
+
+function cellState(row: SDataGridRow<ColumnKey>, column: STableColumn<SDataGridRow<ColumnKey>, string>): STableCellState {
+  return resolveCell(row, column.field).pending === true ? 'pending' : 'default'
+}
+</script>
+
+<style lang="postcss" src="./SDataGrid.css" scoped></style>