pne-ui 4.3.0-rc.2 → 4.3.0-rc.20

package/README.md

@@ -10,25 +10,399 @@
 Установите `pne-ui` вместе с peer-зависимостями:
 
 ```bash
-yarn add pne-ui @emotion/react@^11 @emotion/styled@^11 @mui/material@^7 @mui/system@^7 @mui/x-date-pickers-pro@^7 @mui/icons-material@^7 i18next@^23 react@^18 react-dom@^18 react-i18next@^11
+yarn add pne-ui @emotion/react@^11 @emotion/styled@^11 @mui/material@^9.0.1 @mui/system@^9.0.1 @mui/x-date-pickers-pro@^9 @mui/icons-material@^9.0.1 i18next@^23 react@^19 react-dom@^19 react-i18next@^11
 ```
 
-Подбирайте версии React и React DOM (`^18` или `^19`) в зависимости от вашего приложения.  
-Пакеты MUI поддерживают `^6` и `^7`, установите major-версию, которая совпадает с версией хост-приложения.
+`pne-ui` требует React 19 и MUI 9.0.1 или новее в пределах major 9. React 18, MUI 9.0.0 и предыдущие
+major-версии MUI не входят в поддерживаемый peer contract.
 
 Необходимые peer-зависимости и минимальные версии:
 
 - `@emotion/react@^11`
 - `@emotion/styled@^11`
-- `@mui/material@^6 || ^7`
-- `@mui/system@^6 || ^7`
-- `@mui/x-date-pickers-pro@^6 || ^7`
-- `@mui/icons-material@^6 || ^7`
+- `@mui/material@>=9.0.1 <10`
+- `@mui/system@>=9.0.1 <10`
+- `@mui/x-date-pickers-pro@^9`
+- `@mui/icons-material@>=9.0.1 <10`
 - `i18next@^23`
-- `react@^18 || ^19`
-- `react-dom@^18 || ^19`
+- `react@^19`
+- `react-dom@^19`
 - `react-i18next@^11`
 
+## PneButton
+
+`pneStyle` — единственный публичный способ выбрать PNE-вариант кнопки. Низкоуровневые MUI props `variant` и
+`color` намеренно исключены из TypeScript API, чтобы они не конфликтовали с design-system preset.
+
+| `pneStyle` | Эквивалент прежнего MUI API |
+|---|---|
+| `contained` или prop не задан | `variant="contained" color="primary"` |
+| `outlined` | `variant="outlined" color="primary"` |
+| `error` | `variant="outlined" color="error"` |
+| `text` | `variant="text" color="primary"` |
+| `neutral` | `variant="contained" color="pneNeutral"` |
+| `neutralText` | `variant="text" color="pneNeutral"` |
+| `primaryLight` | `variant="contained" color="pnePrimaryLight"` |
+| `warning` | `variant="contained" color="pneWarningLight"` |
+| `white` | `variant="contained" color="pneWhite"` |
+
+Компонент сохраняет polymorphic MUI-контракт для `component` и `href`; типы DOM props, событий и `ref`
+выводятся из фактического root element. Это поведение рассчитано на React 19 ref-as-prop.
+
+`PneButtonGroup` удалён из публичного API. Для группировки используйте `ButtonGroup` напрямую из
+`@mui/material`; расстояние между независимыми действиями задавайте на layout-контейнере.
+
+## PneField
+
+`PneField` задаёт общий семантический контракт для одного поля: label, helper text, error/disabled/required state и
+их ARIA-связи с единственным логическим control или control group. `PneTextField`, `PneSelect`,
+`PneAutocomplete`, `PneAsyncAutocomplete`, `PneCheckbox` и `PneSwitch` читают этот контракт автоматически.
+Внутри `PneField` должен быть ровно один логический control; для группы передавайте один group component, а не
+несколько соседних controls. `PneField` не принимает ID произвольной layout-обёртки за ID самого control.
+
+`id` принадлежит root `FormControl` и служит namespace для сгенерированных ID. `controlId` принадлежит самому
+интерактивному control и используется в `label[for]`; эти ID должны различаться. Указанный на child `id` не
+переопределяет field-owned ID, поэтому при миграции переносите его в `controlId`. Prop `htmlFor` оставлен только
+как deprecated alias `controlId` и не должен использоваться в новом коде. ID обрезаются по краям; пустые ID и
+ID с внутренними пробельными символами считаются невалидными, игнорируются и заменяются сгенерированными.
+
+```tsx
+<PneField
+    id="delivery-field"
+    controlId="delivery-control"
+    label="Delivery server"
+    helperText="Select one server"
+    slotProps={{
+        label: {id: "delivery-label", "data-autotest": "delivery-label"},
+        helperText: {id: "delivery-help", "data-autotest": "delivery-help"},
+    }}
+>
+    <PneSelect options={servers} value={server} onChange={setServer}/>
+</PneField>
+```
+
+Для произвольного control используйте render prop и передайте результат `getControlProps` на фактический
+focusable control или group root. Adapter сохраняет дополнительные props, объединяет consumer
+`aria-labelledby`/`aria-describedby` с ID label/helper text и дедуплицирует ссылки. Явный `aria-label`
+остаётся самостоятельным naming override и не смешивается с `aria-labelledby`. При disabled field adapter
+возвращает одновременно `disabled` и `aria-disabled`; это сохраняет нативную/MUI блокировку и корректно
+описывает composite control с group-role.
+
+```tsx
+<PneField label="Period" helperText="Choose a unit" error={Boolean(error)} required>
+    {({getControlProps, fullWidth}) => (
+        <ToggleButtonGroup
+            {...getControlProps({"aria-describedby": "period-format"})}
+            exclusive
+            sx={{width: fullWidth ? "100%" : "auto"}}
+            value={period}
+            onChange={(_event, value) => setPeriod(value)}
+        >
+            <ToggleButton value="day">Day</ToggleButton>
+            <ToggleButton value="week">Week</ToggleButton>
+        </ToggleButtonGroup>
+    )}
+</PneField>
+```
+
+Если adapter нужен внутри отдельного descendant component, вызовите `usePneFieldControl()` там; вне
+`PneField` hook возвращает `undefined`. Render prop предпочтительнее для прямой композиции, потому что явно
+показывает место применения DOM-контракта.
+
+`PneField` владеет ID и связями label/helper text. Значения `true` у field-level `disabled`, `error` и
+`required` нельзя ослабить props дочернего control; его дополнительные ARIA ID при этом не теряются. Явный
+`fullWidth` у встроенного PNE control может переопределить field default. `required` на `PneField` добавляет
+asterisk и `aria-required`, но намеренно не устанавливает нативный `required`: browser constraint validation
+включается только `required` на самом input/select/checkbox/switch.
+
+`slotProps.label` и `slotProps.helperText` предназначены для `id`, `className`, `sx`, `ref`, ARIA и `data-*`
+соответствующих slots. Старые `labelSx` и `helperTextSx` deprecated. Split-state props MUI FormControl
+(`color`, `focused`, `hiddenLabel`, `size`, `variant`) не входят в публичный API `PneField`; внешний вид control
+настраивается на самом control, а label/helper — через `slotProps`. Root остаётся polymorphic через `component`,
+и тип `ref` выводится из выбранного root element. `margin` остаётся исключительно layout-prop root
+`FormControl` и не передаётся дочернему control.
+
+## PneTextField
+
+`PneTextField` сохраняет API MUI `TextField` и по умолчанию использует `size="small"`. Его `ref` указывает на
+root `HTMLDivElement`; в text/multiline-режимах для focus, selection и интеграции с form-библиотеками передавайте
+`inputRef`, который получает нативный `input` или `textarea`. В режиме `select` и при custom input slots семантика
+`inputRef` остаётся контрактом MUI. В text/multiline-режимах нативные атрибуты (`maxLength`, `min`, `inputMode`) и
+привязанные к input test/ARIA anchors передавайте через object или functional `slotProps.htmlInput`; для
+интерактивного combobox в режиме `select` используйте `slotProps.select.SelectDisplayProps`. Обычные `data-*`
+props самого `PneTextField` остаются на root. Компонент сохраняет результат slot callback и объединяет consumer
+`aria-describedby` со связью собственного или внешнего helper text.
+
+В композиции с `PneField` текстовое поле получает control ID, `disabled`, `error`, `fullWidth`, helper-связь и
+`aria-required`. `required` внешнего `PneField` намеренно не включает нативный атрибут `required`: если нужна
+browser constraint validation, передайте `required` непосредственно в `PneTextField`.
+
+```tsx
+const { ref, ...field } = controllerField
+
+<PneField label="Customer reference" required helperText={error?.message}>
+    <PneTextField
+        {...field}
+        inputRef={ref}
+        slotProps={{htmlInput: {maxLength: 64}}}
+    />
+</PneField>
+```
+
+## PneCheckbox, PneSwitch и PneLabeledCheckbox
+
+`PneCheckbox` и `PneSwitch` сохраняют MUI-контракт `checked` / `defaultChecked` / `onChange`, а также нативные
+`name`, `value`, `required` и `disabled`. Основной `ref` указывает на фактический root `HTMLSpanElement`; для
+focus, form-библиотек и доступа к нативным свойствам используйте `inputRef: Ref<HTMLInputElement>`. Верхнеуровневые
+`aria-*` применяются к нативному input, а `data-*`, включая существующие `data-autotest`, остаются на root.
+Object и functional `slotProps.input` сохраняются и объединяются с обоими refs и управляемой семантикой.
+Это же объединение применяется к `MuiCheckbox` / `MuiSwitch` theme `defaultProps`, включая их input slots.
+
+`PneSwitch` всегда сохраняет `role="switch"`. `PneCheckbox indeterminate` синхронизирует одновременно
+`input.indeterminate` и mixed accessibility state. `readOnly` у обоих компонентов действительно блокирует
+pointer, label и keyboard activation, но не делает input disabled: он остаётся focusable и участвует в
+`FormData`; состояние также объявляется через `aria-readonly`.
+
+Внешний `PneField` передаёт control ID, label/helper-связь, `disabled`, `error` и `aria-required`. Как и у
+`PneTextField`, `required` на `PneField` не включает browser constraint validation; для неё задайте `required`
+самому checkbox или switch. `PneLabeledCheckbox` добавляет локальные `label`, `helperText` и `error`, генерирует
+ID helper text, сохраняет явный `helperTextProps.id` и объединяет все `aria-describedby`.
+
+```tsx
+<PneField label="Notifications" helperText={error?.message} error={Boolean(error)} required>
+    <PneSwitch
+        checked={enabled}
+        inputRef={controllerRef}
+        name="notifications"
+        onChange={(_event, checked) => setEnabled(checked)}
+    />
+</PneField>
+```
+
+## PneTableSwitchCell
+
+Для status-колонки `PneTable` используйте `PneTableSwitchCell`: он размещает `PneSwitch size="small"` в
+компактной ячейке шириной `40px` без vertical padding и не передаёт click в интерактивную строку. Один из
+`aria-label` / `aria-labelledby` обязателен. Интерактивному варианту нужен `onChange(checked, event)`;
+display-only вариант задаётся через `readOnly` без пустого callback.
+
+Props самой ячейки передаются напрямую, а props переключателя — через `switchProps`. В частности, `id`,
+`inputRef`, `name`, `slotProps` и существующие верхнеуровневые `PneSwitch` `data-*` селекторы относятся к
+`switchProps`; селектор сохраняется на том же Switch DOM anchor, что и при прямом использовании `PneSwitch`,
+но это не обязательно внешний wrapper. Размер, controlled state и accessible name принадлежат
+`PneTableSwitchCell`. `autoTestId` создаёт отдельный locator на нативном input и имеет приоритет над одноимённым
+атрибутом в `switchProps.slotProps.input`, не удаляя верхнеуровневый `PneSwitch` locator из `switchProps`.
+
+```tsx
+<PneTableSwitchCell
+    aria-label="Enable endpoint"
+    checked={enabled}
+    onChange={setEnabled}
+    switchProps={{
+        inputRef: controllerRef,
+        name: "enabled",
+        "data-autotest": "endpoint-status",
+    }}
+/>
+```
+
+## PneModal и PneModalActions
+
+`PneModal` владеет структурой dialog, focus trap и ARIA-связями. Передайте видимый `title`; для модалок без
+визуального заголовка используйте `ariaLabel`. Если компонент внутри `title` сам возвращает `null`, передайте
+`title={null}` и `ariaLabel` явно: содержимое произвольного React-компонента нельзя определить до его рендера.
+`title` и `subtitle` принимают `ReactNode`. `ref` указывает на
+`HTMLDivElement` с `role="dialog"`. Структурные `role`, `aria-modal`, `aria-labelledby` и `aria-describedby`
+нельзя переопределить через container slot; дополнительное описание подключается через `ariaDescribedBy`.
+
+`onClose(event, reason)` различает `closeButtonClick`, `escapeKeyDown` и `backdropClick`. Существующие callbacks
+без аргументов остаются совместимыми. `closeLabel` необязателен и по умолчанию равен `Close`; передавайте перевод
+только там, где он доступен consumer-у. `hideCloseButton` скрывает icon button без дополнительных обязательных
+props.
+
+```tsx
+<PneModal
+    actions={<PneModalActions
+        secondary={<PneButton pneStyle="outlined">Cancel</PneButton>}
+        primary={<PneButton>Save</PneButton>}
+    />}
+    closeLabel="Close"
+    onClose={(_event, reason) => {
+        if (reason !== "backdropClick") setOpen(false)
+    }}
+    open={open}
+    title={<span>Edit account</span>}
+    slotProps={{
+        container: {"data-autotest": "account-dialog"},
+        title: {component: "h2"},
+    }}
+>
+    Account form
+</PneModal>
+```
+
+`blockingOverlay` предназначен для loading-состояния всей модалки. Пока slot присутствует, dialog получает
+`aria-busy`, header/body/footer становятся inert, focus остаётся на границе dialog, а Escape, backdrop и close
+button не вызывают `onClose`. После снятия overlay прежний focused control восстанавливается, если он всё ещё
+существует. Старый `overlay` оставлен как deprecated alias.
+
+Внутренние части настраиваются через `slotProps`, но их element type, owned content и dialog semantics остаются
+фиксированными. `modalProps` содержит только безопасные настройки MUI root и не позволяет подменять root/backdrop
+slots. Прежние `containerProps` и `closeButtonProps` оставлены deprecated на период миграции.
+
+Частые тестовые маркеры `data-*` передаются прямо в `PneModal` и попадают на семантический dialog container:
+`<PneModal data-testattribute="edit-modal" ... />`. Для них не требуется обёртка `slotProps.container`;
+этот slot остаётся для остальных безопасных атрибутов и `sx` контейнера.
+
+`PneModalActions` сохраняет одни и те же keyed action nodes, но синхронизирует DOM/focus order с layout:
+`leading → secondary → primary` на desktop и `primary → secondary → leading` на экране до 480 px. При смене
+breakpoint существующие controls только перемещаются внутри дерева, не перемонтируются и не теряют focus/state.
+Root фиксирован как `div`, поддерживает `ref`, `sx`, обычные HTML/ARIA/data attributes.
+
+## PneSelect
+
+`PneSelect` — controlled single-select для произвольного типа option. `value` имеет тип `T | null`, а `onChange`
+получает выбранный `T`. Для строк и чисел key и label выводятся автоматически; объектам нужны явные
+`getOptionKey` и `getOptionLabel`. Все option callbacks получают исходный объект, поэтому дополнительные поля не
+нужно переносить во вспомогательную форму `{value, label}`.
+
+`getOptionLabel` всегда возвращает plain `string`: он служит также accessible name для option. Rich JSX
+передавайте отдельно через `renderOption`, сохраняя в `getOptionLabel` текстовый эквивалент.
+
+Для HOC сначала зафиксируйте generic явным публичным props-типом: стандартный `ComponentProps<typeof PneSelect>`
+не может представить сразу primitive и object overloads без потери точности.
+
+```tsx
+const RegionSelect = (props: PneSelectObjectProps<Region, string>) => <PneSelect {...props}/>
+const MemoRegionSelect = memo(RegionSelect)
+```
+
+```tsx
+type Region = {
+    code: string
+    disabled: boolean
+    title: string
+}
+
+const [region, setRegion] = useState<Region | null>(null)
+
+<PneSelect
+    options={regions}
+    value={region}
+    onChange={setRegion}
+    getOptionKey={option => option.code}
+    getOptionLabel={option => option.title}
+    getOptionDisabled={option => option.disabled}
+    getOptionProps={option => ({'data-region': option.code})}
+    placeholder="Please select"
+/>
+```
+
+Компонент намеренно не публикует MUI-режимы `native`, `multiple`, `defaultValue`, custom input и input/slot escape
+hatches: его контракт controlled, single и non-native. `ref` указывает на корневой `HTMLDivElement` внутреннего
+MUI Select; `sx` и `fullWidth` применяются к внешнему FormControl. Для композиции
+label/helper/error/required/fullWidth оборачивайте select в `PneField`.
+`SelectDisplayProps` и `MenuProps` сохраняют styling/data/ARIA-настройки, но не позволяют заменить управляемые
+combobox/listbox roles, keyboard/pointer handlers, identity или open/close lifecycle.
+`getOptionProps` предназначен для неинтерактивных DOM-метаданных, ARIA, styling и `data-*`; содержимое option
+задавайте через `renderOption`, disabled-состояние — через `getOptionDisabled`, а выбор обрабатывайте в `onChange`.
+
+`null` обозначает только пустое состояние и не может входить в `options`; `undefined` также не является option.
+Ключи сериализуются в строки, поэтому после сериализации они должны быть уникальны; например, `1` и `"1"`
+конфликтуют. Пустая строка зарезервирована для `null`. Если key текущего `value` отсутствует в `options`, select
+показывает empty/placeholder state без MUI `out-of-range` warning и снова отображает значение после появления
+совпадающей option.
+
+При миграции object options передавайте в `value` сам выбранный объект или `null`, а не замаскированный через cast
+numeric/string ID. `getOptionLabel`, `getOptionProps`, `getOptionDisabled`, `renderOption` и `renderValue` теперь
+работают с исходным `T`, а не с нормализованным `{value, label}`.
+
+## PneAutocomplete
+
+`PneAutocomplete` сохраняет MUI-контракт single/multiple, `disableClearable` и `freeSolo`, но не ограничивает
+данные Paynet DTO. Для строк, чисел и структур `{id, displayName}` / `{choiceId, displayName}` key, label и
+сравнение выводятся автоматически. `id` и `choiceId` могут быть строками или числами; восстановленный из API
+объект считается выбранным по key, а не по ссылке. Значения разных форм (например, freeSolo-строка и объект)
+всегда считаются различными и не приводят к исключению.
+
+Для произвольного объекта обязательны `getOptionKey` и `getOptionLabel`. Явный key также становится default
+правилом сравнения, если caller не передал `isOptionEqualToValue`:
+
+```tsx
+type Region = {code: string; title: string; disabled: boolean}
+
+<PneAutocomplete
+    options={regions}
+    value={selectedRegion}
+    onChange={(_event, value) => setSelectedRegion(value)}
+    getOptionKey={region => region.code}
+    getOptionLabel={region => region.title}
+    getOptionDisabled={region => region.disabled}
+    label="Region"
+/>
+```
+
+Обычный `ref` указывает на фиксированный root `HTMLDivElement`, `inputRef` — на нативный `HTMLInputElement`.
+`htmlInputProps` принимает только безопасные native metadata: `data-*`, name/ARIA и ограниченный набор
+текстовых input-атрибутов. Lifecycle handlers, `value`, `id`, `role`, `disabled`, `readOnly` и другие управляемые
+свойства задаются через API Autocomplete. Имя input автоматически переносится на portal listbox; это работает
+для собственного `label`, внешнего `PneField`, `aria-label` и `aria-labelledby`.
+
+## PneAsyncAutocomplete
+
+`PneAsyncAutocomplete` владеет remote options, loading и отключением локальной MUI-фильтрации. Loader получает
+plain query и контекст запроса:
+
+```tsx
+<PneAsyncAutocomplete
+    value={merchant}
+    onChange={(_event, value) => setMerchant(value)}
+    loadOptions={(query, {signal}) => api.searchMerchants({query, signal})}
+    reloadKey={manager?.id}
+    minQueryLength={2}
+    onLoadError={(error, {query, reason}) => reportAutocompleteError(error, query, reason)}
+    label="Merchant"
+/>
+```
+
+```ts
+type PneLoadOptions<T> = (
+    query: string,
+    context: {
+        signal: AbortSignal
+        reason: 'open' | 'input' | 'clear' | 'reload'
+    },
+) => Promise<readonly T[]>
+```
+
+Новый запрос отменяет предыдущий через `AbortSignal` и дополнительно защищён request ID на случай, если loader
+игнорирует signal. Закрытие и unmount также отменяют активный запрос. Sync throw и rejected Promise переходят в
+одно error-состояние; `AbortError` не вызывает `onLoadError`. `loadErrorText`, `minQueryLengthText`, MUI
+`loadingText` и `noOptionsText` разделяют error/min-query/loading/empty состояния и объявляются assistive
+technology. `keepPreviousOptions` по умолчанию выключен.
+
+`open` и `inputValue` поддерживают controlled и uncontrolled режимы с исходными MUI callbacks/reasons.
+Изменение identity `loadOptions` не перезапускает открытый поиск: для реальной зависимости результата от
+manager/status/currency передавайте стабильный primitive `reloadKey`.
+
+Компонент намеренно не делает debounce и вызывает loader сразу для `open`, пользовательского `input`, `clear`
+и изменения `reloadKey`. Если сервисный метод уже обёрнут React/service debounce-декоратором, дополнительного
+слоя в компоненте нет и конфликтовать с ним нечему.
+
+Breaking migration со старого API выполняется напрямую:
+
+```tsx
+// было
+<PneAsyncAutocomplete searchChoices={({searchString}) => search(searchString ?? '')}/>
+
+// стало
+<PneAsyncAutocomplete loadOptions={query => search(query)}/>
+```
+
+`searchChoices` и `onSearchError` удалены; используйте `loadOptions` и `onLoadError`. Props `options`, `loading`
+и `filterOptions` также не входят в async API, потому что ими владеет компонент. Debounce в эту миграцию не
+входит.
+
 ## Якоря для автотестов
 
 Для нового кода добавляйте якорь непосредственно на существующий DOM-элемент или нужный MUI slot через
@@ -96,6 +470,152 @@ DOM-позиции или пользовательских/секретных д
 - пустой результат: существующая строка `data-autotest="empty-state"`;
 - disabled/checked/selected состояния: только нативные DOM/ARIA-свойства, без test-only копий.
 
+#### Выбор строк
+
+`useTableSelection` хранит выбор в одной из двух взаимоисключающих форм:
+
+- `explicit` — явно выбранные стабильные ID;
+- `allMatching` — все selectable-строки текущей применённой выдачи, кроме `excludedIds`.
+
+Header checkbox управляет только загруженной страницей. Выбор всей выдачи является отдельным действием:
+consumer получает точное число selectable-результатов от своего API и передаёт его в
+`selectAllMatching(matchingCount)`. `matchingCount`, `excludedIds`, `isRowSelectable` и backend query обязаны
+описывать один и тот же applied-result scope. Сериализацию `Set` и domain request выполняйте только на границе
+приложения.
+
+```tsx
+const selection = useTableSelection({
+    rows: orders,
+    getRowId: order => order.id,
+    maxSelected: 20_000,
+    scopeKey: appliedSearchFingerprint,
+})
+
+<PneTable<Order>
+    autoTestId="orders"
+    tableAriaLabel="Orders"
+    data={orders}
+    createTableHeader={() => <PneTableRow>
+        <PneTableSelectionHeaderCell
+            aria-label="Select current page"
+            state={selection.pageState}
+            disabled={selection.interactionDisabled || selection.pageSelectableCount === 0}
+            onChange={selection.setPageSelected}
+        />
+        {/* business headers */}
+    </PneTableRow>}
+    createRow={order => <PneTableRow
+        key={order.id}
+        selected={selection.isRowSelected(order)}
+        aria-selected={selection.isRowSelected(order)}
+    >
+        <PneTableSelectionCell
+            aria-label={`Select order ${order.id}`}
+            checked={selection.isRowSelected(order)}
+            disabled={selection.interactionDisabled || !selection.isRowSelectable(order)}
+            onChange={checked => selection.setRowSelected(order, checked)}
+        />
+        {/* business cells */}
+    </PneTableRow>}
+    feedback={consumerOwnedLimitWarning}
+    toolbar={<PneTableToolbar
+        aria-label="Table controls"
+        contextual={<PneTableSelectionControls
+            summary={`${selection.selectedCount} selected`}
+            actions={consumerOwnedBulkActions}
+        />}
+        persistent={optionalViewSelector}
+    />}
+    /* остальные props */
+/>
+```
+
+`maxSelected` отклоняет всю row/page/all-matching операцию атомарно: возвращённый
+`TableSelectionUpdate.limitExceeded` равен `true`, а модель не меняется. Смена primitive `scopeKey` очищает
+выбор; pagination, sort и refresh не должны входить в этот ключ. В controlled-режиме consumer обязан принять
+scope-reset и вернуть canonical empty-модель `{mode: 'explicit', selectedIds: new Set()}`.
+
+`PneTableToolbar` объединяет contextual selection controls и persistent View controls в существующей верхней
+полосе таблицы. Он измеряет фактическое содержимое и сохраняет DOM/keyboard-порядок Selection → View →
+Pagination при переходе на несколько строк, включая поддерживаемую ширину viewport 360px.
+
+`PneTable.feedback` — отдельный full-width slot над всей верхней полосой. Warning, error и informational alert
+нужно передавать туда, а не внутрь toolbar: feedback не входит в измерения `PneTableToolbar` и пагинации и
+поэтому не меняет их inline/stacked layout даже при переносе текста на несколько строк.
+
+#### Выбор строк в SearchUI
+
+`SearchUI.tableSelection` добавляет тот же controller к consumer-owned header/row factories и автоматически
+связывает его scope с применёнными критериями поиска. Draft-фильтры manual search, page, page size, sort и
+value-equivalent refresh сохраняют выбор. Новые применённые критерии очищают его. При настроенных Views в scope
+по умолчанию входит фактически выбранный View; `preserveAcrossViews` включайте только для Views с одинаковой
+семантикой строк и совместимыми ID.
+
+```tsx
+<SearchUI<Order, OrderViewId, number>
+    /* search props */
+    tableSelection={{
+        selection,
+        onSelectionChange: setSelection,
+        getRowId: order => order.id,
+        maxSelected: knownClientLimit,
+        resolveAllMatchingCount: async ({appliedSearchCriteria, viewId}) => {
+            const summary = await getSelectionSummary(appliedSearchCriteria, viewId)
+            if (summary.limitExceeded) {
+                showConsumerOwnedLimitWarning(summary.selectionLimit)
+                throw new Error('Selection limit exceeded')
+            }
+            return summary.matchingCount
+        },
+        renderControls: ({selection: controller}) => (
+            <PneTableSelectionControls
+                summary={`${controller.selectedCount} selected`}
+                actions={<button
+                    disabled={controller.interactionDisabled}
+                    onClick={() => controller.selectAllMatchingResults?.().catch(handleSelectionError)}
+                >
+                    Select all results
+                </button>}
+            />
+        ),
+        renderFeedback: ({selection: controller}) => (
+            controller.selectingAllMatching ? 'Selecting…' : selectionFeedback
+        ),
+        toolbarAriaLabel: 'Order table controls',
+    }}
+    createTableHeader={(params, context) => {
+        const controller = context?.selection
+        if (!controller) throw new Error('Table selection context is required')
+        return <>{/* explicit selection cell + headers */}</>
+    }}
+    createTableRow={(row, index, data, setData, context) => {
+        const controller = context?.selection
+        if (!controller) throw new Error('Table selection context is required')
+        return <>{/* explicit selection cell + business cells */}</>
+    }}
+/>
+```
+
+Factory context optional только для source compatibility с прежними прямыми вызовами фабрик; сам `SearchUI`
+всегда передаёт context, а `selection` присутствует при настроенном `tableSelection`. Selection-aware consumer
+всё равно должен сделать явный guard/assertion, чтобы его callback оставался корректным вне вызова из `SearchUI`.
+
+`resolveAllMatchingCount` получает snapshot применённых критериев и resolved View. На один SearchUI допускается
+один in-flight запрос: повторный вызов возвращает тот же Promise, controller временно блокирует selection, а
+ответ применяется только к той же occurrence scope. Старые ответы после `A → B → A`, unmount, смены
+`maxSelected` или consumer `disabled` игнорируются. Активная ошибка возвращается caller-коду, после чего controller
+снова доступен. Same-scope refresh/pagination/sort не отменяют запрос. Уже начатый запрос детерминированно
+завершается тем resolver, с которым он был запущен: замена callback действует со следующего запроса, а удаление
+resolver отменяет pending work.
+
+Если backend возвращает typed summary, consumer должен обработать server `limitExceeded` до возврата count.
+`maxSelected` — синхронный client-side guard, а не замена повторной серверной проверке при batch operation.
+
+Selection не записывается в SearchUI retention/profile/browser storage. Uncontrolled selection исчезает при
+remount. В controlled-режиме lifetime принадлежит consumer: если state намеренно расположен выше размонтируемого
+экрана, consumer сам должен очистить его при navigation/remount. Строковое представление applied scope остаётся
+в памяти библиотеки и не выводится в DOM/storage.
+
 ### SearchUI и SearchUIFilters
 
 Передавайте стабильный несекретный `autoTestId` как Selenium scope поискового интерфейса. Если prop не задан,
@@ -267,6 +787,11 @@ assertEquals("true", enabled.getAttribute("aria-pressed"));
 |---|---|---|
 | Верхняя пагинация | `[data-autotest="pagination"][data-autotest-value="top"]` | Native button `disabled`; `current-page` внутри |
 | Нижняя пагинация | `[data-autotest="pagination"][data-autotest-value="bottom"]` | Native button `disabled`; `current-page` внутри |
+| Feedback над таблицей | `[data-autotest="table-feedback"]` | Full-width slot перед верхней полосой; alert/status semantics задаёт consumer |
+| Общая полоса контролов | `[data-autotest="table-control-bar"]` | `data-autotest-value="inline|stacked"` |
+| Выбор текущей страницы | `input[data-autotest="page-selection"]` | Native `checked`, `disabled`, `aria-checked="mixed"` |
+| Выбор строки | `input[data-autotest="row-selection"]` | Native `checked`, `disabled`; consumer может задать `autoTestId`/`autoTestValue` |
+| Selection summary/actions | `[data-autotest="selection-summary"]`, `[data-autotest="selection-actions"]` | Summary является polite live status |
 | Пустой результат | `[data-autotest="empty-state"]` | Наличие существующей empty row |
 | Загрузка | Semantic `table` | `aria-busy="true|false"` |
 | Активная сортировка | `th[aria-sort="ascending"], th[aria-sort="descending"]` | Значение `aria-sort` |
@@ -812,9 +1337,64 @@ export const App = () => (
 ```
 
 Важные правила интеграции:
+
 - если `overlayActions.*` вызываются без смонтированного `OverlayHost`, библиотека пишет явный `console.error`, а snackbar не будет виден пользователю;
 - если в DOM смонтировано больше одного `OverlayHost`, библиотека пишет явный `console.error`, потому что такая конфигурация дублирует snackbar-ы и может рассинхронизировать их таймеры;
 - `OverlayHost` должен подключаться в приложении-хосте, а не внутри отдельных виджетов библиотеки.
+- stacks и permanent overlays по умолчанию уходят одним React portal в `document.body`, не добавляя overlay-wrapper в DOM приложения; для изолированного harness можно передать `container` (или `null` для inline render);
+- `maxSnack` является жёсткой границей: при переполнении самые старые snackbar удаляются, а не остаются скрытой очередью;
+- повторный enqueue с тем же явным `id` игнорируется, пока первый snackbar присутствует. Для замены сначала вызовите `removeSnackbar(id)`.
+
+## PneConfirmProvider
+
+Компоненты вызывают подтверждение через Promise API `usePneConfirm`. Подключайте
+`PneConfirmProvider` ровно один раз рядом с корнем приложения и вызывайте исходное действие только после
+результата `true`:
+
+```tsx
+import { PneConfirmProvider, usePneConfirm } from 'pne-ui'
+
+const DeleteButton = () => {
+    const { confirm } = usePneConfirm()
+
+    const handleDelete = async () => {
+        const accepted = await confirm({
+            danger: true,
+            title: 'Delete item?',
+            message: 'This action cannot be undone.',
+            confirmLabel: 'Delete',
+        })
+
+        if (accepted) {
+            await deleteItem()
+        }
+    }
+
+    return <button onClick={handleDelete}>Delete</button>
+}
+
+export const App = () => (
+    <PneConfirmProvider>
+        <ApplicationRoutes />
+    </PneConfirmProvider>
+)
+```
+
+`danger: true` задаёт destructive/error оформление primary action. Для dismissible acknowledgement-flow без
+Cancel используйте `showCancel: false`: Close, Escape и backdrop по-прежнему возвращают `false`. Параллельные
+вызовы обслуживаются по FIFO; повторное событие от action предыдущего dialog не подтверждает следующий запрос.
+При размонтировании provider текущий и ожидающие Promise завершаются значением `false`.
+
+Поддерживаемые Selenium-якоря размещены на существующих интерактивных/смысловых DOM nodes без
+дополнительных wrapper-элементов:
+
+| Якорь | Назначение |
+|-------|------------|
+| `alert.container` | контейнер confirm modal |
+| `alert.message` | содержимое сообщения |
+| `alert.button.close` | кнопка закрытия |
+| `alert.button.cancel` | cancel action; отсутствует при `showCancel: false` |
+| `alert.button.submit` | confirm action |
 
 ## Интеграция SearchUI
 
@@ -1216,8 +1796,11 @@ const AppShell = () => (
 ```
 
 - Для уведомлений используйте `overlayActions.showSuccess/showError/showWarning/showInfo`, `showSnackbar` или `showUndoSnackbar`.
+- `showError` принимает как готовый UI-текст (`{ message }`), так и исходную Paynet/transport ошибку (`{ error }`). Во втором случае библиотека сама разворачивает Paynet v1, Axios/Fetch/Blob payload, переводит `messageId`, показывает `errorId`, `errorI18N` и доступный пользователю `details`.
 - `showUndoSnackbar` возвращает `id` snackbar и добавляет встроенную action-кнопку `Undo` (или ваш `undoLabel`).
 - Любой snackbar с конечным `autoHideMs` показывает progress bar вверху карточки; если `autoHideMs` не задан, progress bar не рендерится.
+- По умолчанию UI рендерится portal-ом в `document.body`; `container` позволяет задать другой `Element` или callback (в том числе через `ref.current`). Layer берётся из `theme.zIndex.snackbar`/`theme.zIndex.modal`.
+- `maxSnack` удаляет самые старые overflow entries. Явный `id` дедуплицирует pending snackbar по правилу first-wins.
 - `PermanentOverlay` можно размещать на любом уровне дерева под хостом; последний зарегистрированный в слоте заменяет предыдущий.
 - Слоты фиксированы четырьмя углами; сместить позицию можно через `offset`/`zIndex` пропы на `PermanentOverlay`.