@pgcorp/ui-kit 0.3.1 → 0.4.0

package/README.md

@@ -113,6 +113,42 @@ TypeScript показывают доступные subpaths при импорт
 The complete machine-readable catalog is declared in `package.json#exports`.
 IDEs and TypeScript expose the available subpaths during import.
 
+### Реестры и свободный ввод / Registries and custom values
+
+`STable` владеет служебными колонками выбора и раскрытия. Consumer передаёт
+controlled keys и доменный контент, не копирует checkbox, disclosure или CSS:
+
+`STable` owns selection and disclosure columns. Consumers provide controlled
+keys and domain content instead of copying checkboxes, disclosures, or CSS:
+
+```vue
+<STable
+  v-model:selected-row-keys="selectedRowKeys"
+  v-model:expanded-row-keys="expandedRowKeys"
+  :columns="columns"
+  :data="rows"
+  :get-row-key="(row) => row.id"
+  :get-row-label="(row) => row.name"
+  selection-mode="multiple"
+  aria-label="Поставщики"
+  @row-contextmenu="openRowMenu"
+>
+  <template #row-details="{ row }">
+    <SupplierDetails :supplier="row" />
+  </template>
+</STable>
+```
+
+Для служебных столбцов доступны `headerPresentation: 'assistive'`,
+`width: '2xs'` и `width: 'content'`. `SCombobox` принимает новое строковое
+значение через `allow-custom-value`; `SPageHeader` сочетает `appearance="bare"`
+с `title-presentation="assistive"` для доступного заголовка без визуальной полосы.
+
+Utility columns support `headerPresentation: 'assistive'`, `width: '2xs'`, and
+`width: 'content'`. `SCombobox` accepts a new string value with
+`allow-custom-value`; `SPageHeader` combines `appearance="bare"` with
+`title-presentation="assistive"` for an accessible zero-chrome heading.
+
 ## Темы и стили / Themes and styles
 
 Для обычного приложения подключайте полный style entrypoint один раз:

package/package.json

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

package/src/components/shared/containers/SPageHeader.css

@@ -19,6 +19,11 @@
   @apply px-0 pt-0;
 }
 
+.s-page-header[data-appearance='bare'] {
+  @apply border-0 bg-transparent p-0 shadow-none dark:bg-transparent;
+  border-radius: 0;
+}
+
 .s-page-header__copy {
   @apply min-w-0;
 }

package/src/components/shared/containers/SPageHeader.vue

@@ -8,7 +8,7 @@ withDefaults(defineProps<{
   description?: string
   eyebrow?: string
   headingLevel?: 1 | 2 | 3
-  appearance?: 'plain' | 'panel'
+  appearance?: 'bare' | 'plain' | 'panel'
   size?: 'compact' | 'default'
   actionsLayout?: 'responsive' | 'inline' | 'stacked'
   titlePresentation?: 'visible' | 'assistive'

package/src/components/shared/controls/SCombobox.vue

@@ -62,7 +62,7 @@ export type SComboboxOptionGroup<TKey extends PublicSelectionKey = PublicSelecti
 export type SComboboxEntry<TKey extends PublicSelectionKey = PublicSelectionKey> = PublicSelectionEntry<TKey>
 export type SComboboxFilterMode = 'local' | 'manual'
 
-export interface Props<TKey extends PublicSelectionKey = PublicSelectionKey> {
+interface SharedProps<TKey extends PublicSelectionKey> {
   modelValue: TKey | null
   search: string
   options: readonly SComboboxEntry<TKey>[]
@@ -79,6 +79,18 @@ export interface Props<TKey extends PublicSelectionKey = PublicSelectionKey> {
   id?: string
   size?: 'sm' | 'md' | 'lg'
 }
+
+/**
+ * Custom values require a string-compatible model because the editable text is the committed identity.
+ * Свободные значения требуют string-compatible model, потому что введённый текст становится identity.
+ */
+export type Props<TKey extends PublicSelectionKey = PublicSelectionKey> = SharedProps<TKey> & {
+  allowCustomValue?: string extends TKey ? boolean : false
+}
+
+type ComponentProps<TKey extends PublicSelectionKey> = SharedProps<TKey> & {
+  allowCustomValue?: boolean
+}
 </script>
 
 <script setup lang="ts" generic="TKey extends SelectionKey = string">
@@ -106,7 +118,7 @@ import SListbox, { type SListboxMoveIntent } from './SListbox.vue'
 
 defineOptions({ inheritAttrs: false })
 
-const props = withDefaults(defineProps<Props<TKey>>(), {
+const props = withDefaults(defineProps<ComponentProps<TKey>>(), {
   filterMode: 'local',
   label: undefined,
   placeholder: 'Начните вводить для поиска',
@@ -119,6 +131,7 @@ const props = withDefaults(defineProps<Props<TKey>>(), {
   emptyLabel: 'Нет доступных вариантов',
   id: undefined,
   size: 'md',
+  allowCustomValue: false,
 })
 const emit = defineEmits<{
   'update:modelValue': [value: TKey | null]
@@ -156,13 +169,18 @@ const contract = computed(() => ({
   invalid: validateBoolean('SCombobox', 'invalid', props.invalid),
   emptyLabel: validateNonEmptyString('SCombobox', 'emptyLabel', props.emptyLabel),
   size: validateExactString('SCombobox', 'size', props.size, ['sm', 'md', 'lg'] as const),
+  allowCustomValue: validateBoolean('SCombobox', 'allowCustomValue', props.allowCustomValue),
   label: validateOptionalSelectionString('SCombobox', 'label', props.label),
   helpText: validateOptionalSelectionString('SCombobox', 'helpText', props.helpText),
   errorMessage: validateOptionalSelectionString('SCombobox', 'errorMessage', props.errorMessage),
 }))
 const inventory = computed(() => {
   const resolved = resolveSelectionInventory<TKey>('SCombobox', props.options)
-  validateSelectionModel('SCombobox', 'single', props.modelValue, resolved)
+  if (contract.value.allowCustomValue && typeof props.modelValue === 'string') {
+    selectionKeyToken('SCombobox', props.modelValue, 'modelValue')
+  } else {
+    validateSelectionModel('SCombobox', 'single', props.modelValue, resolved)
+  }
   return resolved
 })
 
@@ -231,6 +249,29 @@ const { anchorRef, panelRef, floatingStyle } = useFloatingPosition({
 
 type CloseReason = 'selection' | 'escape' | 'tab' | 'outside'
 
+function customValueFromSearch(): TKey | null {
+  if (!contract.value.allowCustomValue) return null
+  const value = validatedSearch.value.trim()
+  if (value.length === 0) return null
+
+  if (props.modelValue !== null) {
+    const currentToken = selectionKeyToken('SCombobox', props.modelValue, 'modelValue')
+    const currentOption = inventory.value.optionsByToken.get(currentToken)
+    if (currentOption?.option.label.trim() === value) return null
+    if (typeof props.modelValue === 'string' && props.modelValue === value) return null
+  }
+
+  return value as TKey
+}
+
+function commitCustomValue(): boolean {
+  const value = customValueFromSearch()
+  if (value === null) return false
+  emit('update:modelValue', value)
+  emit('update:search', String(value))
+  return true
+}
+
 function inputElement(): HTMLInputElement {
   const api = inputRef.value
   if (!api) throw new Error('SCombobox: SInputText API is unavailable')
@@ -239,7 +280,7 @@ function inputElement(): HTMLInputElement {
 
 function close(reason: CloseReason): void {
   if (!isOpen.value) return
-  void reason
+  if (reason === 'tab' || reason === 'outside') commitCustomValue()
   isOpen.value = false
   activeValue.value = null
   layerRegistration?.unregister({ restoreFocus: false })
@@ -305,7 +346,8 @@ async function onInputKeydown(event: KeyboardEvent): Promise<void> {
   }
   if (event.key === 'Enter' && isOpen.value) {
     event.preventDefault()
-    listboxRef.value?.selectActive()
+    if (activeValue.value !== null) listboxRef.value?.selectActive()
+    else if (commitCustomValue()) close('selection')
     return
   }
   if (event.key === 'Escape' && isOpen.value) {

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

@@ -34,12 +34,15 @@
 }
 
 .s-table-header th[data-width="auto"] { inline-size: auto; }
+.s-table-header th[data-width="content"] { inline-size: 1%; white-space: nowrap; }
+.s-table-header th[data-width="2xs"] { inline-size: var(--s-table-column-inline-size-2xs); }
 .s-table-header th[data-width="xs"] { inline-size: var(--s-table-column-inline-size-xs); }
 .s-table-header th[data-width="sm"] { inline-size: var(--s-table-column-inline-size-sm); }
 .s-table-header th[data-width="md"] { inline-size: var(--s-table-column-inline-size-md); }
 .s-table-header th[data-width="lg"] { inline-size: var(--s-table-column-inline-size-lg); }
 .s-table-header th[data-width="xl"] { inline-size: var(--s-table-column-inline-size-xl); }
 .s-table-header th[data-width="fill"] { inline-size: 100%; }
+.s-table-header th[data-min-width="2xs"] { min-inline-size: var(--s-table-column-inline-size-2xs); }
 .s-table-header th[data-min-width="xs"] { min-inline-size: var(--s-table-column-inline-size-xs); }
 .s-table-header th[data-min-width="sm"] { min-inline-size: var(--s-table-column-inline-size-sm); }
 .s-table-header th[data-min-width="md"] { min-inline-size: var(--s-table-column-inline-size-md); }
@@ -58,6 +61,10 @@
   @apply bg-surface-50/50 dark:bg-surface-800/20;
 }
 
+.s-table-body tr[data-selected="true"] td {
+  @apply bg-primary-50 dark:bg-primary-950/30;
+}
+
 .s-table-body td {
   @apply px-4 py-3 align-middle text-surface-700 dark:text-surface-300;
   height: var(--s-density-row-comfortable);
@@ -66,6 +73,38 @@
 .s-table[data-density="compact"] th { @apply px-3 py-2; }
 .s-table[data-density="compact"] td { @apply px-2 py-1.5; height: var(--s-density-row-compact); }
 
+.s-table th.s-table__control-cell,
+.s-table td.s-table__control-cell {
+  @apply px-2 text-center;
+  inline-size: var(--s-table-column-inline-size-2xs);
+  min-inline-size: var(--s-table-column-inline-size-2xs);
+}
+
+.s-table__control-cell > * {
+  @apply mx-auto;
+}
+
+.s-table__header-content[data-header-presentation="assistive"],
+.s-table__assistive {
+  @apply sr-only;
+}
+
+.s-table-body tr[data-row-details] {
+  @apply bg-surface-50/40 dark:bg-surface-900/40;
+}
+
+.s-table-body tr[data-row-details]:hover {
+  @apply bg-surface-50/40 dark:bg-surface-900/40;
+}
+
+.s-table-body tr[data-row-details] > td {
+  @apply h-auto p-0;
+}
+
+.s-table__row-details {
+  @apply px-4 py-3 text-surface-700 dark:text-surface-300;
+}
+
 .s-table [data-align="center"] { text-align: center; }
 .s-table [data-align="right"] { text-align: right; }
 

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

@@ -16,6 +16,28 @@
     >
       <thead class="s-table-header">
         <tr>
+          <th
+            v-if="validatedSelectionMode === 'multiple'"
+            class="s-table__control-cell"
+            scope="col"
+            data-width="2xs"
+          >
+            <SCheckbox
+              :model-value="allCurrentRowsSelected"
+              :indeterminate="someCurrentRowsSelected && !allCurrentRowsSelected"
+              :disabled="selectableRows.length === 0"
+              :aria-label="allCurrentRowsSelected ? 'Снять выбор со всех строк' : 'Выбрать все строки'"
+              @update:model-value="updateAllRowsSelection"
+            />
+          </th>
+          <th
+            v-if="hasRowDetails"
+            class="s-table__control-cell"
+            scope="col"
+            data-width="2xs"
+          >
+            <span class="s-table__assistive">Детали строки</span>
+          </th>
           <th
             v-for="column in validatedColumns"
             :key="column.field"
@@ -38,15 +60,24 @@
               :trailing-icon="sortIcon(column)"
               @click="requestSort(column)"
             >
-              <slot name="column" :column="column">
-                <slot :name="`header-${column.field}`" :column="column">{{ column.header }}</slot>
-              </slot>
+              <span
+                class="s-table__header-content"
+                :data-header-presentation="column.headerPresentation ?? 'visible'"
+              >
+                <slot name="column" :column="column">
+                  <slot :name="`header-${column.field}`" :column="column">{{ column.header }}</slot>
+                </slot>
+              </span>
             </SButton>
-            <template v-else>
+            <span
+              v-else
+              class="s-table__header-content"
+              :data-header-presentation="column.headerPresentation ?? 'visible'"
+            >
               <slot name="column" :column="column">
                 <slot :name="`header-${column.field}`" :column="column">{{ column.header }}</slot>
               </slot>
-            </template>
+            </span>
           </th>
         </tr>
       </thead>
@@ -59,44 +90,90 @@
               ? { status: 'error', message: errorMessage }
               : { status: 'empty', message: emptyMessage }"
           presentation="table-row"
-          :colspan="validatedColumns.length || 1"
+          :colspan="renderedColumnCount"
         />
         <template v-else>
-          <tr
+          <template
             v-for="(row, rowIndex) in validatedRows"
-            :key="resolvedRowKeys.get(row)"
-            :data-state="resolveRowState(row)"
-            :aria-selected="resolvedRowKeys.get(row) === validatedSelectedRowKey ? 'true' : undefined"
-            tabindex="0"
-            @click="onRowClick($event, row, rowIndex)"
-            @keydown.enter="onRowKeydown($event, row, rowIndex)"
-            @keydown.space.prevent="onRowKeydown($event, row, rowIndex)"
+            :key="rowDomToken(row)"
           >
-            <td
-              v-for="column in validatedColumns"
-              :key="column.field"
-              :data-align="column.align ?? 'left'"
-              :data-state="resolveCellState(row, column)"
+            <tr
+              :data-state="resolveRowState(row)"
+              :data-selected="rowIsSelected(row) || undefined"
+              :aria-selected="rowAriaSelected(row)"
+              tabindex="0"
+              @click="onRowClick($event, row, rowIndex)"
+              @contextmenu="onRowContextMenu($event, row, rowIndex)"
+              @keydown.enter="onRowKeydown($event, row, rowIndex)"
+              @keydown.space="onRowKeydown($event, row, rowIndex)"
             >
-              <slot
-                :name="`cell-${column.field}`"
-                :value="resolveCellValue(row, column)"
-                :row="row"
-                :column="column"
-                :row-index="rowIndex"
+              <td
+                v-if="validatedSelectionMode === 'multiple'"
+                class="s-table__control-cell"
+              >
+                <SCheckbox
+                  :model-value="rowIsSelected(row)"
+                  :disabled="!rowIsSelectable(row)"
+                  :aria-label="rowSelectionLabel(row, rowIndex)"
+                  @update:model-value="updateRowSelection(row, rowIndex, $event)"
+                />
+              </td>
+              <td v-if="hasRowDetails" class="s-table__control-cell">
+                <SButton
+                  v-if="rowIsExpandable(row)"
+                  :aria-label="rowExpansionLabel(row, rowIndex)"
+                  appearance="text"
+                  severity="secondary"
+                  size="xs"
+                  density="compact"
+                  shape="square"
+                  icon-only
+                  :disclosure="{
+                    expanded: rowIsExpanded(row),
+                    controls: rowDetailsId(row),
+                    iconPlacement: 'leading',
+                  }"
+                  @click="toggleRowExpansion(row, rowIndex)"
+                />
+              </td>
+              <td
+                v-for="column in validatedColumns"
+                :key="column.field"
+                :data-align="column.align ?? 'left'"
+                :data-state="resolveCellState(row, column)"
               >
                 <slot
-                  name="cell"
+                  :name="`cell-${column.field}`"
                   :value="resolveCellValue(row, column)"
                   :row="row"
                   :column="column"
                   :row-index="rowIndex"
                 >
-                  {{ resolveCellValue(row, column) }}
+                  <slot
+                    name="cell"
+                    :value="resolveCellValue(row, column)"
+                    :row="row"
+                    :column="column"
+                    :row-index="rowIndex"
+                  >
+                    {{ resolveCellValue(row, column) }}
+                  </slot>
                 </slot>
-              </slot>
-            </td>
-          </tr>
+              </td>
+            </tr>
+            <tr v-if="rowIsExpandable(row) && rowIsExpanded(row)" data-row-details>
+              <td :colspan="renderedColumnCount">
+                <div
+                  :id="rowDetailsId(row)"
+                  class="s-table__row-details"
+                  role="region"
+                  :aria-label="`Детали: ${resolveRowLabel(row, rowIndex)}`"
+                >
+                  <slot name="row-details" :row="row" :row-index="rowIndex" />
+                </div>
+              </td>
+            </tr>
+          </template>
         </template>
       </tbody>
     </table>
@@ -109,10 +186,12 @@ import type {
   STableCellState,
   STableColumn,
   STableColumnContent,
+  STableColumnHeaderPresentation,
   STableDensity,
   STableMinWidth,
   STableRowKey,
   STableRowState,
+  STableSelectionMode,
   STableSort,
   STableSurface,
 } from './table'
@@ -122,10 +201,12 @@ export type {
   STableCellState,
   STableColumn,
   STableColumnContent,
+  STableColumnHeaderPresentation,
   STableDensity,
   STableMinWidth,
   STableRowKey,
   STableRowState,
+  STableSelectionMode,
   STableSort,
   STableSortDirection,
   STableSurface,
@@ -145,6 +226,12 @@ export interface STableProps<
   errorMessage?: string
   emptyMessage?: string
   selectedRowKey?: RowKey
+  selectionMode?: STableSelectionMode
+  selectedRowKeys?: readonly RowKey[]
+  isRowSelectable?: (row: Row, index: number) => boolean
+  expandedRowKeys?: readonly RowKey[]
+  isRowExpandable?: (row: Row, index: number) => boolean
+  getRowLabel?: (row: Row, index: number) => string
   sort?: STableSort<Field> | null
   maxHeight?: ScrollableViewportMaxBlockSize
   density?: STableDensity
@@ -162,7 +249,7 @@ export interface STableProps<
 </script>
 
 <script setup lang="ts" generic="Row extends object = Record<string, unknown>, RowKey extends STableRowKey = STableRowKey, Field extends string = Extract<keyof Row, string>">
-import { computed, useSlots } from 'vue'
+import { computed, useId, useSlots } from 'vue'
 import { ChevronDown, ChevronsUpDown, ChevronUp } from '../../icons/sputnigUiIcons'
 import { hasOwn } from '../../../internal/es2020'
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
@@ -180,6 +267,7 @@ import {
 } from '../../../internal/runtimeContract'
 import SAsyncState from '../feedback/SAsyncState.vue'
 import SButton from '../controls/SButton.vue'
+import SCheckbox from '../controls/SCheckbox.vue'
 defineOptions({ inheritAttrs: false })
 
 const props = withDefaults(defineProps<STableProps<Row, RowKey, Field>>(), {
@@ -188,6 +276,12 @@ const props = withDefaults(defineProps<STableProps<Row, RowKey, Field>>(), {
   errorMessage: '',
   emptyMessage: 'Нет данных для отображения',
   selectedRowKey: undefined,
+  selectionMode: 'none',
+  selectedRowKeys: () => [],
+  isRowSelectable: undefined,
+  expandedRowKeys: () => [],
+  isRowExpandable: undefined,
+  getRowLabel: undefined,
   sort: null,
   maxHeight: 'none',
   density: 'default',
@@ -201,6 +295,10 @@ const props = withDefaults(defineProps<STableProps<Row, RowKey, Field>>(), {
 })
 const emit = defineEmits<{
   'row-click': [row: Row, index: number]
+  'row-contextmenu': [row: Row, index: number, event: MouseEvent]
+  'update:selectedRowKeys': [value: readonly RowKey[]]
+  'update:expandedRowKeys': [value: readonly RowKey[]]
+  'row-expand': [row: Row, index: number, expanded: boolean]
   'update:sort': [value: STableSort<Field> | null]
   sort: [value: STableSort<Field> | null]
 }>()
@@ -213,9 +311,13 @@ const TABLE_ALIGNMENTS = ['left', 'center', 'right'] as const
 const TABLE_ROW_STATES = ['default', 'inserted', 'updated', 'deleted'] as const
 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 ownedAttrs = useOwnedAttrs({ component: 'STable', owner: 'table scroll surface' })
 useInteractiveLeafRegistration({ owner: 'STable' })
+const tableInstanceId = `s-table-${useId()}`
+const hasRowDetails = typeof slots['row-details'] === 'function'
 
 function eventBelongsToNestedControl(event: Event): boolean {
   const owner = event.currentTarget
@@ -228,8 +330,14 @@ function onRowClick(event: MouseEvent, row: Row, rowIndex: number): void {
   if (!eventBelongsToNestedControl(event)) emit('row-click', row, rowIndex)
 }
 
+function onRowContextMenu(event: MouseEvent, row: Row, rowIndex: number): void {
+  if (!eventBelongsToNestedControl(event)) emit('row-contextmenu', row, rowIndex, event)
+}
+
 function onRowKeydown(event: KeyboardEvent, row: Row, rowIndex: number): void {
-  if (event.target === event.currentTarget) emit('row-click', row, rowIndex)
+  if (event.target !== event.currentTarget) return
+  event.preventDefault()
+  emit('row-click', row, rowIndex)
 }
 const validatedLoading = computed(() => validateBoolean('STable', 'loading', props.loading))
 const resolvedAccessibleName = computed(() => {
@@ -275,12 +383,24 @@ const validatedMaxHeight = computed(() => validateScrollableViewportMaxBlockSize
   'maxHeight',
   props.maxHeight,
 ))
+const validatedSelectionMode = computed(() => validateExactString(
+  'STable',
+  'selectionMode',
+  props.selectionMode,
+  TABLE_SELECTION_MODES,
+))
 
 const validatedColumns = computed<readonly STableColumn<Row, Field>[]>(() => {
   const fields = new Set<string>()
   for (const column of props.columns) {
     const field = validateNonEmptyString('STable', 'columns[].field', column.field)
     validateNonEmptyString('STable', `column ${JSON.stringify(field)}.header`, column.header)
+    const headerPresentation: STableColumnHeaderPresentation = validateExactString(
+      'STable',
+      `column ${JSON.stringify(field)}.headerPresentation`,
+      column.headerPresentation ?? 'visible',
+      TABLE_HEADER_PRESENTATIONS,
+    )
     if (fields.has(field)) {
       throw new TypeError(
         `STable: columns содержит duplicate field ${JSON.stringify(field)}. `
@@ -294,6 +414,12 @@ const validatedColumns = computed<readonly STableColumn<Row, Field>[]>(() => {
     if (column.sortable !== undefined) {
       validateBoolean('STable', `column ${JSON.stringify(field)}.sortable`, column.sortable)
     }
+    if (headerPresentation === 'assistive' && column.sortable) {
+      throw new TypeError(
+        `STable: assistive header column ${JSON.stringify(field)} не может быть sortable без visible action. `
+        + `/ STable: assistive header column ${JSON.stringify(field)} cannot be sortable without a visible action.`,
+      )
+    }
     if (column.width !== undefined) {
       validateTableColumnInlineSize('STable', `column ${JSON.stringify(field)}.width`, column.width)
     }
@@ -380,47 +506,178 @@ function describeRowKey(key: STableRowKey): string {
   return typeof key === 'string' ? JSON.stringify(key) : String(key)
 }
 
-function validateRowKey(value: unknown): RowKey {
+function diagnosticOwner(): string {
+  return resolvedAccessibleName.value.ariaLabel === undefined
+    ? `STable [aria-labelledby=${JSON.stringify(resolvedAccessibleName.value.ariaLabelledby)}]`
+    : `STable ${JSON.stringify(resolvedAccessibleName.value.ariaLabel)}`
+}
+
+function describeThrownError(error: unknown): string {
+  return error instanceof Error ? `${error.name}: ${error.message}` : String(error)
+}
+
+function validateRowKey(value: unknown, coordinate: string): RowKey {
   if (
     (typeof value === 'string' && value.trim().length > 0)
     || (typeof value === 'number' && Number.isFinite(value))
   ) return value as RowKey
 
   throw new TypeError(
-    `STable: getRowKey должен вернуть non-empty string | finite number. `
-    + '/ STable: getRowKey must return a non-empty string | finite number.',
+    `${diagnosticOwner()}: ${coordinate} должен вернуть non-empty string | finite number. `
+    + `/ ${diagnosticOwner()}: ${coordinate} must return a non-empty string | finite number.`,
   )
 }
 
 const resolvedRowKeys = computed<ReadonlyMap<Row, RowKey>>(() => {
   if (typeof props.getRowKey !== 'function') {
     throw new TypeError(
-      'STable: getRowKey должен быть обязательным function resolver. '
-      + '/ STable: getRowKey must be a required function resolver.',
+      `${diagnosticOwner()}: getRowKey должен быть обязательным function resolver. `
+      + `/ ${diagnosticOwner()}: getRowKey must be a required function resolver.`,
     )
   }
 
-  const keys = new Set<STableRowKey>()
+  const firstIndexByKey = new Map<STableRowKey, number>()
   const rowKeys = new Map<Row, RowKey>()
-  for (const row of props.data) {
-    const key = validateRowKey(props.getRowKey(row))
-    if (keys.has(key)) {
+  for (const [rowIndex, row] of props.data.entries()) {
+    let value: unknown
+    try {
+      value = props.getRowKey(row)
+    } catch (error: unknown) {
       throw new TypeError(
-        `STable: getRowKey вернул duplicate key ${describeRowKey(key)}. `
-        + `/ STable: getRowKey returned duplicate key ${describeRowKey(key)}.`,
+        `${diagnosticOwner()}: getRowKey failed at data[${rowIndex}]: ${describeThrownError(error)}.`,
       )
     }
-    keys.add(key)
+    const key = validateRowKey(value, `getRowKey at data[${rowIndex}]`)
+    const firstIndex = firstIndexByKey.get(key)
+    if (firstIndex !== undefined) {
+      throw new TypeError(
+        `${diagnosticOwner()}: getRowKey вернул duplicate key ${describeRowKey(key)} at data[${rowIndex}]; `
+        + `first returned at data[${firstIndex}]. / ${diagnosticOwner()}: getRowKey returned duplicate key `
+        + `${describeRowKey(key)} at data[${rowIndex}]; first returned at data[${firstIndex}].`,
+      )
+    }
+    firstIndexByKey.set(key, rowIndex)
     rowKeys.set(row, key)
   }
   return rowKeys
 })
 
+function validateControlledKeys(coordinate: string, value: unknown): readonly RowKey[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(
+      `${diagnosticOwner()}: ${coordinate} должен быть readonly array. `
+      + `/ ${diagnosticOwner()}: ${coordinate} must be a readonly array.`,
+    )
+  }
+  const validated: RowKey[] = []
+  const seen = new Set<STableRowKey>()
+  for (const [index, candidate] of value.entries()) {
+    const key = validateRowKey(candidate, `${coordinate}[${index}]`)
+    if (seen.has(key)) {
+      throw new TypeError(
+        `${diagnosticOwner()}: ${coordinate} содержит duplicate key ${describeRowKey(key)}. `
+        + `/ ${diagnosticOwner()}: ${coordinate} contains duplicate key ${describeRowKey(key)}.`,
+      )
+    }
+    seen.add(key)
+    validated.push(key)
+  }
+  return validated
+}
+
+const validatedSelectedRowKey = computed<RowKey | undefined>(() => {
+  if (props.selectedRowKey === undefined) return undefined
+  if (validatedSelectionMode.value === 'multiple') {
+    throw new TypeError(
+      `${diagnosticOwner()}: selectedRowKey несовместим с selectionMode="multiple"; используйте selectedRowKeys. `
+      + `/ ${diagnosticOwner()}: selectedRowKey is incompatible with selectionMode="multiple"; use selectedRowKeys.`,
+    )
+  }
+  const selectedKey = validateRowKey(props.selectedRowKey, 'selectedRowKey')
+  const rowKeys = new Set(resolvedRowKeys.value.values())
+  if (!rowKeys.has(selectedKey)) {
+    throw new TypeError(
+      `${diagnosticOwner()}: selectedRowKey ${describeRowKey(selectedKey)} отсутствует в resolved row keys. `
+      + `/ ${diagnosticOwner()}: selectedRowKey ${describeRowKey(selectedKey)} is absent from resolved row keys.`,
+    )
+  }
+  return selectedKey
+})
+
+const validatedSelectedRowKeys = computed<readonly RowKey[]>(() => {
+  const keys = validateControlledKeys('selectedRowKeys', props.selectedRowKeys)
+  if (validatedSelectionMode.value === 'none' && keys.length > 0) {
+    throw new TypeError(
+      `${diagnosticOwner()}: selectedRowKeys требует selectionMode="multiple". `
+      + `/ ${diagnosticOwner()}: selectedRowKeys requires selectionMode="multiple".`,
+    )
+  }
+  if (props.isRowSelectable !== undefined && validatedSelectionMode.value !== 'multiple') {
+    throw new TypeError(
+      `${diagnosticOwner()}: isRowSelectable требует selectionMode="multiple". `
+      + `/ ${diagnosticOwner()}: isRowSelectable requires selectionMode="multiple".`,
+    )
+  }
+  if (props.isRowSelectable !== undefined && typeof props.isRowSelectable !== 'function') {
+    throw new TypeError(`${diagnosticOwner()}: isRowSelectable must be a function.`)
+  }
+  return keys
+})
+
+const rowSelectableByRow = computed<ReadonlyMap<Row, boolean>>(() => {
+  const result = new Map<Row, boolean>()
+  for (const [index, row] of props.data.entries()) {
+    const selectable = validatedSelectionMode.value === 'multiple'
+      ? validateBoolean('STable', `isRowSelectable at data[${index}]`, props.isRowSelectable?.(row, index) ?? true)
+      : false
+    result.set(row, selectable)
+  }
+  return result
+})
+
+const validatedExpandedRowKeys = computed<readonly RowKey[]>(() => {
+  const keys = validateControlledKeys('expandedRowKeys', props.expandedRowKeys)
+  if (!hasRowDetails && (keys.length > 0 || props.isRowExpandable !== undefined)) {
+    throw new TypeError(
+      `${diagnosticOwner()}: expandedRowKeys/isRowExpandable требует slot row-details. `
+      + `/ ${diagnosticOwner()}: expandedRowKeys/isRowExpandable requires the row-details slot.`,
+    )
+  }
+  if (props.isRowExpandable !== undefined && typeof props.isRowExpandable !== 'function') {
+    throw new TypeError(`${diagnosticOwner()}: isRowExpandable must be a function.`)
+  }
+  return keys
+})
+
+const rowExpandableByRow = computed<ReadonlyMap<Row, boolean>>(() => {
+  const result = new Map<Row, boolean>()
+  for (const [index, row] of props.data.entries()) {
+    const expandable = hasRowDetails
+      ? validateBoolean('STable', `isRowExpandable at data[${index}]`, props.isRowExpandable?.(row, index) ?? true)
+      : false
+    result.set(row, expandable)
+  }
+  const expanded = new Set(validatedExpandedRowKeys.value)
+  for (const row of props.data) {
+    if (expanded.has(rowKey(row)) && !result.get(row)) {
+      throw new TypeError(
+        `${diagnosticOwner()}: expandedRowKeys содержит current row, для которой isRowExpandable вернул false. `
+        + `/ ${diagnosticOwner()}: expandedRowKeys contains a current row for which isRowExpandable returned false.`,
+      )
+    }
+  }
+  return result
+})
+
 const validatedRows = computed<readonly Row[]>(() => {
   const columns = validatedColumns.value
   void validatedSort.value
   void resolvedRowKeys.value
   void validatedSelectedRowKey.value
+  void validatedSelectedRowKeys.value
+  void rowSelectableByRow.value
+  void validatedExpandedRowKeys.value
+  void rowExpandableByRow.value
   for (const row of props.data) {
     for (const column of columns) {
       const content = column.content ?? (column.value === undefined ? 'field' : 'value')
@@ -435,18 +692,116 @@ const validatedRows = computed<readonly Row[]>(() => {
   return props.data
 })
 
-const validatedSelectedRowKey = computed<RowKey | undefined>(() => {
-  if (props.selectedRowKey === undefined) return undefined
-  const selectedKey = validateRowKey(props.selectedRowKey)
-  const rowKeys = new Set(resolvedRowKeys.value.values())
-  if (!rowKeys.has(selectedKey)) {
-    throw new TypeError(
-      `STable: selectedRowKey ${describeRowKey(selectedKey)} отсутствует в resolved row keys. `
-      + `/ STable: selectedRowKey ${describeRowKey(selectedKey)} is absent from resolved row keys.`,
-    )
+function rowKey(row: Row): RowKey {
+  const key = resolvedRowKeys.value.get(row)
+  if (key === undefined) throw new Error(`${diagnosticOwner()}: row identity is unavailable`)
+  return key
+}
+
+function rowKeyToken(key: RowKey): string {
+  return `${typeof key === 'number' ? 'number' : 'string'}:${String(key)}`
+}
+
+function rowDomToken(row: Row): string {
+  return rowKeyToken(rowKey(row))
+}
+
+function rowDetailsId(row: Row): string {
+  return `${tableInstanceId}-details-${encodeURIComponent(rowDomToken(row))}`
+}
+
+function resolveRowLabel(row: Row, index: number): string {
+  if (props.getRowLabel === undefined) return `Строка ${index + 1}`
+  if (typeof props.getRowLabel !== 'function') {
+    throw new TypeError(`${diagnosticOwner()}: getRowLabel must be a function.`)
   }
-  return selectedKey
-})
+  return validateNonEmptyString('STable', `getRowLabel at data[${index}]`, props.getRowLabel(row, index))
+}
+
+const selectedKeySet = computed(() => new Set(validatedSelectedRowKeys.value))
+const expandedKeySet = computed(() => new Set(validatedExpandedRowKeys.value))
+const selectableRows = computed(() => props.data.filter((row) => rowSelectableByRow.value.get(row) === true))
+const selectedCurrentRowCount = computed(() => selectableRows.value.filter(
+  (row) => selectedKeySet.value.has(rowKey(row)),
+).length)
+const someCurrentRowsSelected = computed(() => selectedCurrentRowCount.value > 0)
+const allCurrentRowsSelected = computed(() => (
+  selectableRows.value.length > 0 && selectedCurrentRowCount.value === selectableRows.value.length
+))
+const renderedColumnCount = computed(() => Math.max(
+  validatedColumns.value.length
+    + (validatedSelectionMode.value === 'multiple' ? 1 : 0)
+    + (hasRowDetails ? 1 : 0),
+  1,
+))
+
+function rowIsSelectable(row: Row): boolean {
+  return rowSelectableByRow.value.get(row) === true
+}
+
+function rowIsSelected(row: Row): boolean {
+  return validatedSelectionMode.value === 'multiple' && selectedKeySet.value.has(rowKey(row))
+}
+
+function rowAriaSelected(row: Row): 'true' | 'false' | undefined {
+  if (validatedSelectionMode.value === 'multiple') return rowIsSelected(row) ? 'true' : 'false'
+  return rowKey(row) === validatedSelectedRowKey.value ? 'true' : undefined
+}
+
+function rowSelectionLabel(row: Row, index: number): string {
+  const label = resolveRowLabel(row, index)
+  if (!rowIsSelectable(row)) return `Выбор недоступен: ${label}`
+  return rowIsSelected(row) ? `Снять выбор: ${label}` : `Выбрать: ${label}`
+}
+
+function updateRowSelection(row: Row, index: number, selected: boolean): void {
+  void index
+  if (!rowIsSelectable(row)) return
+  const key = rowKey(row)
+  const current = validatedSelectedRowKeys.value
+  if (selected && !selectedKeySet.value.has(key)) emit('update:selectedRowKeys', [...current, key])
+  if (!selected && selectedKeySet.value.has(key)) {
+    emit('update:selectedRowKeys', current.filter((candidate) => candidate !== key))
+  }
+}
+
+function updateAllRowsSelection(selected: boolean): void {
+  const current = validatedSelectedRowKeys.value
+  const currentSelectableKeys = new Set(selectableRows.value.map((row) => rowKey(row)))
+  if (!selected) {
+    emit('update:selectedRowKeys', current.filter((key) => !currentSelectableKeys.has(key)))
+    return
+  }
+  const next = [...current]
+  const nextKeys = new Set(current)
+  for (const key of currentSelectableKeys) {
+    if (!nextKeys.has(key)) next.push(key)
+  }
+  emit('update:selectedRowKeys', next)
+}
+
+function rowIsExpandable(row: Row): boolean {
+  return rowExpandableByRow.value.get(row) === true
+}
+
+function rowIsExpanded(row: Row): boolean {
+  return expandedKeySet.value.has(rowKey(row))
+}
+
+function rowExpansionLabel(row: Row, index: number): string {
+  return `${rowIsExpanded(row) ? 'Свернуть' : 'Раскрыть'}: ${resolveRowLabel(row, index)}`
+}
+
+function toggleRowExpansion(row: Row, index: number): void {
+  if (!rowIsExpandable(row)) return
+  const key = rowKey(row)
+  const expanded = !expandedKeySet.value.has(key)
+  const next = expanded
+    ? [...validatedExpandedRowKeys.value, key]
+    : validatedExpandedRowKeys.value.filter((candidate) => candidate !== key)
+  emit('update:expandedRowKeys', next)
+  emit('row-expand', row, index, expanded)
+}
 
 const resolveCellValue = (row: Row, column: STableColumn<Row, Field>): unknown => column.value
   ? column.value(row)

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

@@ -11,6 +11,8 @@ export type STableSurface = 'bordered' | 'plain'
 export type STableMinWidth = 'content' | 'md' | 'lg'
 export type STableDensity = 'default' | 'compact'
 export type STableColumnContent = 'field' | 'value' | 'slot'
+export type STableColumnHeaderPresentation = 'visible' | 'assistive'
+export type STableSelectionMode = 'none' | 'multiple'
 export type STableSortDirection = 'ascending' | 'descending'
 
 /** Controlled sort state; consumer owns data ordering. / Управляемое состояние сортировки; порядок данных принадлежит consumer. */
@@ -22,6 +24,7 @@ export interface STableSort<Field extends string = string> {
 interface STableColumnBase<Field extends string> {
   field: Field
   header: string
+  headerPresentation?: STableColumnHeaderPresentation
   width?: TableColumnInlineSize
   minWidth?: TableColumnMinInlineSize
   align?: STableAlignment

package/src/internal/semanticSizing.ts

@@ -2,8 +2,8 @@ import { validateExactString } from './runtimeContract'
 
 const SCROLLABLE_VIEWPORT_MAX_BLOCK_SIZES = ['none', 'sm', 'md', 'lg'] as const
 const EXPANDED_CONTENT_MAX_BLOCK_SIZES = ['sm', 'md', 'lg'] as const
-const TABLE_COLUMN_INLINE_SIZES = ['auto', 'xs', 'sm', 'md', 'lg', 'xl', 'fill'] as const
-const TABLE_COLUMN_MIN_INLINE_SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const
+const TABLE_COLUMN_INLINE_SIZES = ['auto', 'content', '2xs', 'xs', 'sm', 'md', 'lg', 'xl', 'fill'] as const
+const TABLE_COLUMN_MIN_INLINE_SIZES = ['2xs', 'xs', 'sm', 'md', 'lg', 'xl'] as const
 
 /**
  * Максимальный block-size прокручиваемого viewport; none сохраняет естественный flow.

package/src/styles/tokens.css

@@ -212,6 +212,7 @@
   --s-expanded-content-max-block-size-lg: 28rem;
   --s-table-inline-size-md: 32rem;
   --s-table-inline-size-lg: 42rem;
+  --s-table-column-inline-size-2xs: 3rem;
   --s-table-column-inline-size-xs: 6rem;
   --s-table-column-inline-size-sm: 9rem;
   --s-table-column-inline-size-md: 12rem;