pne-ui 4.3.0-rc.4 → 4.3.0-rc.41

package/README.md

@@ -10,25 +10,450 @@
 Установите `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`
 
+## PneBreadcrumbs
+
+`PneBreadcrumbs` — общий визуальный компонент хлебных крошек для host-приложения и микрофронтов. Он не
+зависит от роутера, i18next, меню или permissions: consumer передаёт уже локализованные `label`, формирует
+доступные ему элементы и при необходимости подключает bridge-aware ссылку через `linkComponent`.
+Такой link adapter должен принимать `href`, передавать `className` и прочие DOM props и через `forwardRef`
+возвращать ref фактического `<a>` — это нужно для клавиатурного фокуса в overflow-меню.
+
+Элементы имеют стабильный `id` и один из трёх взаимоисключающих типов: `link` с `href`, `action` с `onClick`
+или неинтерактивный `text`. Последний `text` автоматически получает `aria-current="page"`. При нехватке места
+середина цепочки сворачивается в доступное меню, а `ResizeObserver` следит только за собственным контейнером
+компонента. Для корректного измерения родитель должен разрешать сжатие через `min-width: 0`.
+
+```tsx
+<PneBreadcrumbs
+    ariaLabel={t("navigation.breadcrumbs")}
+    moreLabel={t("navigation.more")}
+    linkComponent={PneLink}
+    items={[
+        {
+            id: "orders",
+            label: t("main.nav.orders"),
+            icon: <PneOrdersIcon/>,
+            type: "text",
+        },
+        {
+            id: "orders-search",
+            label: t("sidebar.menu.orders"),
+            href: "/paynet-ui/react-orders",
+            type: "link",
+        },
+        {
+            id: `order-${orderId}`,
+            label: `${t("orders.order.history.order")} ${orderId}`,
+            type: "text",
+        },
+    ]}
+/>
+```
+
+## 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`.
+
+Если `PneSwitch.onChange` возвращает Promise/thenable, компонент автоматически включает optimistic lifecycle
+без отдельного `pending` prop: сразу показывает запрошенное состояние, помечает input через `aria-busy` и
+`aria-disabled`, показывает progress-индикатор и игнорирует повторную активацию до settlement. При reject
+переключатель откатывается, при resolve сохраняет подтверждённое состояние. Синхронные callbacks работают как
+раньше. Для controlled usage возвращаемый Promise должен завершаться после обновления внешнего `checked`;
+для `defaultChecked` commit и rollback полностью принадлежат самому `PneSwitch`. Нативный input во время
+запроса не становится `disabled`, поэтому не теряет focus и сохраняет текущее ON/OFF-состояние.
+
+Внешний `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) => updateNotifications(checked)
+            .then(() => 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. Возвращённый из табличного `onChange`
+Promise передаётся в `PneSwitch`, поэтому optimistic/pending/rollback lifecycle работает в status-колонке без
+дополнительных props ячейки.
+
+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 +521,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 +838,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 +1388,68 @@ 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 удаляются, а не остаются скрытой очередью;
+- для обычного уведомления о завершившемся действии не передавайте `id`: каждый вызов получит собственную внутреннюю
+  identity, поэтому даже одинаковые сообщения будут показаны отдельными элементами стека;
+- явный `id` нужен только для управляемого lifecycle, когда вызывающий код должен позднее адресно удалить или заменить
+  конкретный snackbar (например, после Undo);
+- повторный 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
 
@@ -1062,123 +1697,6 @@ export const App = () => (
 тему MUI (тип `ThemeOptions`). Обёрнутые компоненты получают как базовые цвета skin, так и кастомные
 color overrides (`pneNeutral`, `pnePrimaryLight`, `pneAccentuated` и др.), объявленные в `src/index.ts`.
 
-## WidgetBoard и работа с лейаутами
-
-`WidgetBoard` — дашборд с драгабл-виджетами и встраиваемой панелью лейаутов. Компонент инкапсулирует состояние:
-выбор лейаута, CRUD кастомных схем и сохранение/загрузку лежат внутри `WidgetBoard`; снаружи достаточно передать
-источники данных. Для связи `WidgetBoard` с `WidgetLayoutsPanel`/`WidgetBoardFab` используйте
-`WidgetBoardScopeProvider` и `useWidgetBoardScopeStore`.
-
-Основные пропсы:
-- `widgets`: список `{ id, title, render }` — содержимое виджетов.
-- `layoutByBreakpoint`: базовый пресет для дефолтного лейаута.
-- `loadLayouts(): Promise<{ options; selectedId? } | null>`: обязательная функция загрузки пользовательских схем (вызывается при маунте). `WidgetBoard` сам добавляет и блокирует встроенный `default`-лейаут.
-- `saveLayouts(options, selectedId?)`: обязательная функция сохранения пользовательских схем (вызывается при select/add/delete и автосохранении изменений в выбранном пользовательском лейауте).
-
-Панель `WidgetLayoutsPanel` — презентационный компонент. Передавайте `items/selectedId/onSelect/onAdd/onDelete`
-и прочие данные из scoped store (`useWidgetBoardScopeStore`).
-
-### Структура данных для лейаутов
-
-`loadLayouts` и `saveLayouts` работают с массивом `WidgetBoardLayoutOption`:
-
-- `id: string`: уникальный идентификатор лейаута (можно `uuid` или любое значение бэка).
-- `name: string`: отображаемое имя пресета.
-- `layoutByBreakpoint: Record<number | string, BreakpointLayoutConfig>`: карта брейкпоинтов (ключ — число или строка, обычно `12`, `1280`, `1600` и т.д.).
-  - `BreakpointLayoutConfig`: `{ widgets: Record<widgetId, WidgetLayoutConfig> }`.
-  - `WidgetLayoutConfig`: `{ defaultSize: { columnSpan; rowSpan; columnOffset? }; limits?; initialState?; heightMode? }`.
-    - `initialState` поддерживает `isHidden` и `isCollapsed`.
-
-Формат функции `loadLayouts`:
-
-```ts
-type LoadLayoutsResult = {
-    options: WidgetBoardLayoutOption[]
-    selectedId?: string // id активного лейаута, если его нет в options — упадет на первый элемент
-} | null
-```
-
-`saveLayouts` получает тот же `options` (уже с последними изменениями) и `selectedId`.
-
-### Пример использования
-
-```tsx
-import React from 'react'
-import { Box, Stack } from '@mui/material'
-import {
-    WidgetBoard,
-    WidgetLayoutsPanel,
-    WidgetBoardScopeProvider,
-    useWidgetBoardScopeStore,
-    type WidgetDefinition,
-    type WidgetBoardLayoutOption,
-} from 'pne-ui'
-
-const widgets: WidgetDefinition[] = [
-    { id: 'traffic', title: 'Traffic', render: () => <div>Traffic content</div> },
-    { id: 'sales', title: 'Sales', render: () => <div>Sales content</div> },
-]
-
-const baseLayoutByBreakpoint = {
-    12: {
-        widgets: {
-            traffic: { defaultSize: { columnSpan: 6, rowSpan: 2 } },
-            sales: { defaultSize: { columnSpan: 6, rowSpan: 2 } },
-        },
-    },
-}
-
-// Загрузка/сохранение пресетов
-const loadLayouts = async (): Promise<{ options: WidgetBoardLayoutOption[]; selectedId?: string }> => {
-    const response = await api.getUserLayouts() // верните { options, selectedId }
-    // Если API пустой, вернем пустой набор: WidgetBoard добавит встроенный default сам
-    return response ?? { options: [], selectedId: 'default' }
-}
-const saveLayouts = async (options: WidgetBoardLayoutOption[], selectedId?: string) => {
-    await api.saveUserLayouts({ options, selectedId })
-}
-
-const DashboardContent = () => {
-    const boardStore = useWidgetBoardScopeStore()
-    const panelProps = boardStore(state => ({
-        items: state.items,
-        selectedId: state.selectedId,
-        onSelect: state.onSelect,
-        onDelete: state.onDelete,
-        onAdd: state.onAdd,
-        addInfo: state.addInfo,
-        lockedIds: state.lockedIds,
-    }))
-
-    return (
-        <Box sx={{ p: 2 }}>
-            <Stack direction={{ xs: 'column', md: 'row' }} spacing={2} alignItems={{ xs: 'stretch', md: 'flex-start' }}>
-                <Box sx={{ minWidth: 260 }}>
-                    <WidgetLayoutsPanel {...panelProps} />
-                </Box>
-                <Box sx={{ flex: 1 }}>
-                    <WidgetBoard
-                        widgets={widgets}
-                        layoutByBreakpoint={baseLayoutByBreakpoint}
-                        loadLayouts={loadLayouts}
-                        saveLayouts={saveLayouts}
-                    />
-                </Box>
-            </Box>
-        </Box>
-    )
-}
-
-export const Dashboard = () => (
-    <WidgetBoardScopeProvider>
-        <DashboardContent />
-    </WidgetBoardScopeProvider>
-)
-```
-
-`WidgetBoard` сам обновляет выбранный лейаут, следит за состоянием виджетов и при изменениях дергает `saveLayouts`
-с актуальным набором опций.
-
 ## OverlayHost и уведомления
 
 `OverlayHost` рендерит snackbars из `overlayActions` и принимает декларативные постоянные оверлеи через `PermanentOverlay`
@@ -1216,8 +1734,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`.
 
@@ -1241,7 +1762,7 @@ const AppShell = () => (
 import { PneFloatingActionButtons, overlayActions } from 'pne-ui'
 
 const actions = [
-    { id: 'reset', label: 'Reset layout', onClick: () => overlayActions.showInfo({ message: 'Reset' }) },
+    { id: 'refresh', label: 'Refresh data', onClick: () => overlayActions.showInfo({ message: 'Refreshed' }) },
     { id: 'save', label: 'Save', onClick: () => overlayActions.showSuccess({ message: 'Saved' }) },
     { id: 'divider', kind: 'divider' as const },
     { id: 'custom', kind: 'content' as const, node: <div style={{ padding: 8 }}>Any JSX here</div> },
@@ -1251,7 +1772,7 @@ export const FabDemo = () => (
     <PneFloatingActionButtons
         actions={actions}
         fabLabel='Actions'
-        bannerText='Edit widgets'
+        bannerText='Page actions'
         position={{ bottom: 24, right: 24 }}
         mobileBreakpoint={900} // считать мобильным до 900px, иначе поведение как на десктопе
     />