@pgcorp/ui-kit 0.4.0 → 0.5.0

package/README.md

@@ -149,6 +149,27 @@ Utility columns support `headerPresentation: 'assistive'`, `width: '2xs'`, and
 `allow-custom-value`; `SPageHeader` combines `appearance="bare"` with
 `title-presentation="assistive"` for an accessible zero-chrome heading.
 
+Составная сортировка использует controlled `v-model:sorts`: consumer задаёт
+`sort-mode="multiple"` и передаёт ordered `STableSort[]`. Клик по
+заголовку добавляет критерий, меняет направление или удаляет его; номер возле
+заголовка показывает приоритет. Таблица не переставляет строки самостоятельно.
+
+Multi-column sorting uses controlled `v-model:sorts`: the consumer sets
+`sort-mode="multiple"` and provides an ordered `STableSort[]`. Header activation
+adds a descriptor, changes its direction, or removes it; the visible number is
+the priority. The table never reorders rows on its own.
+
+```vue
+<STable
+  v-model:sorts="sorts"
+  :columns="columns"
+  :data="sortedRows"
+  :get-row-key="(row) => row.id"
+  sort-mode="multiple"
+  aria-label="Позиции прайс-листа"
+/>
+```
+
 ## Темы и стили / Themes and styles
 
 Для обычного приложения подключайте полный style entrypoint один раз:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgcorp/ui-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Typed Vue 3 design system with accessible components, semantic themes, and workbench patterns.",
   "type": "module",
   "types": "./index.ts",

package/src/components/shared/data-display/STable.vue

@@ -58,6 +58,8 @@
               width="full"
               :content-align="column.align === 'right' ? 'end' : column.align === 'center' ? 'center' : 'start'"
               :trailing-icon="sortIcon(column)"
+              :badge="sortPriority(column) ?? undefined"
+              badge-severity="primary"
               @click="requestSort(column)"
             >
               <span
@@ -193,6 +195,7 @@ import type {
   STableRowState,
   STableSelectionMode,
   STableSort,
+  STableSortMode,
   STableSurface,
 } from './table'
 
@@ -209,6 +212,7 @@ export type {
   STableSelectionMode,
   STableSort,
   STableSortDirection,
+  STableSortMode,
   STableSurface,
 } from './table'
 
@@ -232,7 +236,9 @@ export interface STableProps<
   expandedRowKeys?: readonly RowKey[]
   isRowExpandable?: (row: Row, index: number) => boolean
   getRowLabel?: (row: Row, index: number) => string
+  sortMode?: STableSortMode
   sort?: STableSort<Field> | null
+  sorts?: readonly STableSort<Field>[]
   maxHeight?: ScrollableViewportMaxBlockSize
   density?: STableDensity
   surface?: STableSurface
@@ -282,7 +288,9 @@ const props = withDefaults(defineProps<STableProps<Row, RowKey, Field>>(), {
   expandedRowKeys: () => [],
   isRowExpandable: undefined,
   getRowLabel: undefined,
+  sortMode: 'single',
   sort: null,
+  sorts: () => [],
   maxHeight: 'none',
   density: 'default',
   surface: 'bordered',
@@ -301,6 +309,8 @@ const emit = defineEmits<{
   'row-expand': [row: Row, index: number, expanded: boolean]
   'update:sort': [value: STableSort<Field> | null]
   sort: [value: STableSort<Field> | null]
+  'update:sorts': [value: readonly STableSort<Field>[]]
+  'multi-sort': [value: readonly STableSort<Field>[]]
 }>()
 const slots = useSlots()
 
@@ -313,6 +323,8 @@ const TABLE_CELL_STATES = ['default', 'pending'] as const
 const TABLE_COLUMN_CONTENT = ['field', 'value', 'slot'] as const
 const TABLE_HEADER_PRESENTATIONS = ['visible', 'assistive'] as const
 const TABLE_SELECTION_MODES = ['none', 'multiple'] as const
+const TABLE_SORT_MODES = ['single', 'multiple'] as const
+const TABLE_SORT_DIRECTIONS = ['ascending', 'descending'] as const
 
 const ownedAttrs = useOwnedAttrs({ component: 'STable', owner: 'table scroll surface' })
 useInteractiveLeafRegistration({ owner: 'STable' })
@@ -389,6 +401,12 @@ const validatedSelectionMode = computed(() => validateExactString(
   props.selectionMode,
   TABLE_SELECTION_MODES,
 ))
+const validatedSortMode = computed(() => validateExactString(
+  'STable',
+  'sortMode',
+  props.sortMode,
+  TABLE_SORT_MODES,
+))
 
 const validatedColumns = computed<readonly STableColumn<Row, Field>[]>(() => {
   const fields = new Set<string>()
@@ -454,9 +472,15 @@ const validatedColumns = computed<readonly STableColumn<Row, Field>[]>(() => {
   return props.columns
 })
 
-const validatedSort = computed<STableSort<Field> | null>(() => {
-  if (props.sort === null || props.sort === undefined) return null
-  const key = validateNonEmptyString('STable', 'sort.key', props.sort.key) as Field
+function validateSortEntry(value: unknown, coordinate: string): STableSort<Field> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(
+      `STable: ${coordinate} должен быть STableSort object. `
+      + `/ STable: ${coordinate} must be an STableSort object.`,
+    )
+  }
+  const entry = value as Record<string, unknown>
+  const key = validateNonEmptyString('STable', `${coordinate}.key`, entry.key) as Field
   const column = validatedColumns.value.find((candidate) => candidate.field === key)
   if (!column?.sortable) {
     throw new TypeError(`STable: sort key ${JSON.stringify(key)} должен ссылаться на sortable column. / STable: sort key ${JSON.stringify(key)} must reference a sortable column.`)
@@ -465,25 +489,100 @@ const validatedSort = computed<STableSort<Field> | null>(() => {
     key,
     direction: validateExactString(
       'STable',
-      'sort.direction',
-      props.sort.direction,
-      ['ascending', 'descending'] as const,
+      `${coordinate}.direction`,
+      entry.direction,
+      TABLE_SORT_DIRECTIONS,
     ),
   }
+}
+
+const validatedSingleSort = computed<STableSort<Field> | null>(() => {
+  if (validatedSortMode.value === 'multiple') {
+    if (props.sort !== null && props.sort !== undefined) {
+      throw new TypeError(
+        'STable: sortMode="multiple" несовместим с sort; используйте v-model:sorts. '
+        + '/ STable: sortMode="multiple" is incompatible with sort; use v-model:sorts.',
+      )
+    }
+    return null
+  }
+  if (props.sort === null || props.sort === undefined) return null
+  return validateSortEntry(props.sort, 'sort')
+})
+
+const validatedMultipleSort = computed<readonly STableSort<Field>[]>(() => {
+  const sorts: unknown = props.sorts
+  if (!Array.isArray(sorts)) {
+    throw new TypeError(
+      'STable: sorts должен быть ordered STableSort array. '
+      + '/ STable: sorts must be an ordered STableSort array.',
+    )
+  }
+  if (validatedSortMode.value === 'single') {
+    if (sorts.length > 0) {
+      throw new TypeError(
+        'STable: sortMode="single" несовместим с непустым sorts; используйте v-model:sort. '
+        + '/ STable: sortMode="single" is incompatible with non-empty sorts; use v-model:sort.',
+      )
+    }
+    return []
+  }
+  const keys = new Set<Field>()
+  return sorts.map((entry, index) => {
+    const validated = validateSortEntry(entry, `sorts[${index}]`)
+    if (keys.has(validated.key)) {
+      throw new TypeError(
+        `STable: sorts содержит duplicate key ${JSON.stringify(validated.key)}. `
+        + `/ STable: sorts contains duplicate key ${JSON.stringify(validated.key)}.`,
+      )
+    }
+    keys.add(validated.key)
+    return validated
+  })
 })
 
+const activeSorts = computed<readonly STableSort<Field>[]>(() => {
+  const singleSort = validatedSingleSort.value
+  const multipleSort = validatedMultipleSort.value
+  if (validatedSortMode.value === 'multiple') return multipleSort
+  return singleSort === null ? [] : [singleSort]
+})
+
+function sortIndex(column: STableColumn<Row, Field>): number {
+  return activeSorts.value.findIndex((candidate) => candidate.key === column.field)
+}
+
+function sortPriority(column: STableColumn<Row, Field>): number | null {
+  if (validatedSortMode.value !== 'multiple') return null
+  const index = sortIndex(column)
+  return index === -1 ? null : index + 1
+}
+
 const columnAriaSort = (column: STableColumn<Row, Field>): 'none' | 'ascending' | 'descending' | undefined => {
   if (!column.sortable) return undefined
-  return validatedSort.value?.key === column.field ? validatedSort.value.direction : 'none'
+  if (validatedSortMode.value === 'multiple') {
+    const primary = activeSorts.value[0]
+    return primary?.key === column.field ? primary.direction : undefined
+  }
+  const current = activeSorts.value[0]
+  return current?.key === column.field ? current.direction : 'none'
 }
 
 const sortIcon = (column: STableColumn<Row, Field>) => {
-  const direction = columnAriaSort(column)
+  const direction = activeSorts.value.find((candidate) => candidate.key === column.field)?.direction
   return direction === 'ascending' ? ChevronUp : direction === 'descending' ? ChevronDown : ChevronsUpDown
 }
 
 const sortActionLabel = (column: STableColumn<Row, Field>): string => {
-  const direction = columnAriaSort(column)
+  const index = sortIndex(column)
+  const current = index === -1 ? undefined : activeSorts.value[index]
+  if (validatedSortMode.value === 'multiple') {
+    if (!current) return `${column.header}: добавить в сортировку по возрастанию`
+    const state = current.direction === 'ascending' ? 'по возрастанию' : 'по убыванию'
+    const action = current.direction === 'ascending' ? 'сортировать по убыванию' : 'убрать из сортировки'
+    return `${column.header}: приоритет ${index + 1} из ${activeSorts.value.length}, ${state}; ${action}`
+  }
+  const direction = current?.direction
   if (direction === 'ascending') return `${column.header}: сортировать по убыванию`
   if (direction === 'descending') return `${column.header}: сбросить сортировку`
   return `${column.header}: сортировать по возрастанию`
@@ -491,15 +590,29 @@ const sortActionLabel = (column: STableColumn<Row, Field>): string => {
 
 function requestSort(column: STableColumn<Row, Field>): void {
   if (!column.sortable) return
-  const current = validatedSort.value
   const key = column.field as Field
-  const next: STableSort<Field> | null = current?.key !== key
-    ? { key, direction: 'ascending' }
-    : current.direction === 'ascending'
-      ? { key, direction: 'descending' }
-      : null
-  emit('update:sort', next)
-  emit('sort', next)
+  if (validatedSortMode.value === 'multiple') {
+    const current = activeSorts.value
+    const index = sortIndex(column)
+    let next: readonly STableSort<Field>[]
+    if (index === -1) next = [...current, { key, direction: 'ascending' }]
+    else if (current[index]!.direction === 'ascending') {
+      next = current.map((entry, candidateIndex) => candidateIndex === index
+        ? { key: entry.key, direction: 'descending' }
+        : entry)
+    } else next = current.filter((_entry, candidateIndex) => candidateIndex !== index)
+    emit('update:sorts', next)
+    emit('multi-sort', next)
+  } else {
+    const current = activeSorts.value[0]
+    const next: STableSort<Field> | null = current?.key !== key
+      ? { key, direction: 'ascending' }
+      : current.direction === 'ascending'
+        ? { key, direction: 'descending' }
+        : null
+    emit('update:sort', next)
+    emit('sort', next)
+  }
 }
 
 function describeRowKey(key: STableRowKey): string {
@@ -671,7 +784,7 @@ const rowExpandableByRow = computed<ReadonlyMap<Row, boolean>>(() => {
 
 const validatedRows = computed<readonly Row[]>(() => {
   const columns = validatedColumns.value
-  void validatedSort.value
+  void activeSorts.value
   void resolvedRowKeys.value
   void validatedSelectedRowKey.value
   void validatedSelectedRowKeys.value

package/src/components/shared/data-display/table.ts

@@ -14,6 +14,7 @@ export type STableColumnContent = 'field' | 'value' | 'slot'
 export type STableColumnHeaderPresentation = 'visible' | 'assistive'
 export type STableSelectionMode = 'none' | 'multiple'
 export type STableSortDirection = 'ascending' | 'descending'
+export type STableSortMode = 'single' | 'multiple'
 
 /** Controlled sort state; consumer owns data ordering. / Управляемое состояние сортировки; порядок данных принадлежит consumer. */
 export interface STableSort<Field extends string = string> {