pne-ui 4.3.0-rc.8 → 4.3.0

package/README.md

@@ -1,7 +1,7 @@
 # pne-ui
 
 [![NPM version][npm-image]][npm-url]
-[![Build][github-build]][github-build-url]
+[![npm release][github-publish]][github-publish-url]
 
 Мега обертка над MUI
 
@@ -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 через
@@ -143,12 +568,12 @@ const selection = useTableSelection({
         />
         {/* business cells */}
     </PneTableRow>}
+    feedback={consumerOwnedLimitWarning}
     toolbar={<PneTableToolbar
         aria-label="Table controls"
         contextual={<PneTableSelectionControls
             summary={`${selection.selectedCount} selected`}
             actions={consumerOwnedBulkActions}
-            status={consumerOwnedLimitWarning}
         />}
         persistent={optionalViewSelector}
     />}
@@ -165,6 +590,10 @@ scope-reset и вернуть canonical empty-модель `{mode: 'explicit', s
 полосе таблицы. Он измеряет фактическое содержимое и сохраняет 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 и автоматически
@@ -198,9 +627,11 @@ value-equivalent refresh сохраняют выбор. Новые примен
                 >
                     Select all results
                 </button>}
-                status={controller.selectingAllMatching ? 'Selecting…' : selectionStatus}
             />
         ),
+        renderFeedback: ({selection: controller}) => (
+            controller.selectingAllMatching ? 'Selecting…' : selectionFeedback
+        ),
         toolbarAriaLabel: 'Order table controls',
     }}
     createTableHeader={(params, context) => {
@@ -407,10 +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/status | `[data-autotest="selection-summary"]`, `[data-autotest="selection-actions"]`, `[data-autotest="selection-status"]` | Summary является polite live status |
+| 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` |
@@ -956,9 +1388,74 @@ 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({
+            autoTestValue: item.id,
+            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`.
+
+Для повторяемого или бизнес-специфичного действия передавайте стабильный не-секретный
+`autoTestValue` (raw entity ID, enum или caller-owned scope). Portal-root получает это значение, поэтому dialog
+однозначно связывается с инициировавшим control даже вне его DOM-поддерева. Очередь хранит scope каждого
+запроса независимо и меняет его вместе с текущим confirm.
+
+Поддерживаемые Selenium-якоря размещены на существующих интерактивных/смысловых DOM nodes без
+дополнительных wrapper-элементов:
+
+| Якорь | Назначение |
+|-------|------------|
+| `alert.container/<autoTestValue?>` | контейнер confirm modal и опциональный owner scope |
+| `alert.message` | содержимое сообщения |
+| `alert.button.close` | кнопка закрытия |
+| `alert.button.cancel` | cancel action; отсутствует при `showCancel: false` |
+| `alert.button.submit` | confirm action |
 
 ## Интеграция SearchUI
 
@@ -1034,6 +1531,190 @@ const config = {
 />
 ```
 
+Параметр `maxRangeSpanInDays` задаёт включительную верхнюю границу диапазона.
+Он проверяет уже разрешённые границы всех режимов даты; для date-only `EXACTLY`
+пользовательская конечная дата считается включительной. Значение должно быть
+положительным целым числом.
+
+### Критерии отчёта по транзакциям
+
+Для экранов полного и краткого отчётов специализированная конфигурация включает
+шесть критериев: диапазон дат и пять новых критериев отчёта. Имена их полей в
+`SearchCriteria` совместимы с контрактом API: `scope` вместе с
+`transactionIds`, `datesType`, `recurrentFilter`, `timeZoneOffsetHours` и
+`csvCharset`. Поддерживаемые библиотекой значения местами намеренно уже полного
+backend-контракта; различия перечислены ниже.
+
+Все шесть специализированных критериев следует передавать в
+`predefinedCriteria`, чтобы их нельзя было удалить. Их необходимо объединить с
+уже существующими обязательными критериями конкретного отчёта. В примере ниже
+использован базовый набор Wicket-страниц: типы транзакций, статусы транзакций и
+типы карт. Дополнительные доступные критерии, например валюты, можно добавить
+только в `possibleCriteria`.
+
+```tsx
+import {useState} from 'react'
+import {
+    CriterionTypeEnum,
+    DATE_RANGE_SPEC_TYPES,
+    OverlayHost,
+    PneButton,
+    type SearchCriteria,
+    SearchUIFilters,
+    SearchUIProvider,
+    type SearchUIValidationResult,
+} from 'pne-ui'
+
+const BASE_REQUIRED_REPORT_CRITERIA: CriterionTypeEnum[] = [
+    CriterionTypeEnum.TRANSACTION_TYPES,
+    CriterionTypeEnum.TRANSACTION_STATUS,
+    CriterionTypeEnum.CARD_TYPES,
+]
+
+const SPECIALIZED_TRANSACTION_REPORT_CRITERIA: CriterionTypeEnum[] = [
+    CriterionTypeEnum.DATE_RANGE,
+    CriterionTypeEnum.TRANSACTION_REPORT_SCOPE,
+    CriterionTypeEnum.TRANSACTION_DATE_TYPE,
+    CriterionTypeEnum.TRANSACTION_RECURRENT_FILTER,
+    CriterionTypeEnum.TIME_ZONE,
+    CriterionTypeEnum.CSV_CHARSET,
+]
+
+const REQUIRED_TRANSACTION_REPORT_CRITERIA: CriterionTypeEnum[] = [
+    ...BASE_REQUIRED_REPORT_CRITERIA,
+    ...SPECIALIZED_TRANSACTION_REPORT_CRITERIA,
+]
+
+type TransactionReportFiltersExampleProps = {
+    onGenerate: (criteria: SearchCriteria) => void
+}
+
+export const TransactionReportFiltersExample = ({
+    onGenerate,
+}: TransactionReportFiltersExampleProps) => {
+    const [searchCriteria, setSearchCriteria] = useState<SearchCriteria | null>(null)
+    const [validation, setValidation] = useState<SearchUIValidationResult | null>(null)
+
+    const generateReport = () => {
+        if (searchCriteria !== null) {
+            onGenerate(searchCriteria)
+        }
+    }
+
+    return <OverlayHost>
+        <SearchUIProvider>
+            <SearchUIFilters
+                settingsContextName="transaction-report"
+                possibleCriteria={REQUIRED_TRANSACTION_REPORT_CRITERIA}
+                predefinedCriteria={REQUIRED_TRANSACTION_REPORT_CRITERIA}
+                initialSearchConditions={{
+                    dateRangeSpec: {
+                        dateRangeSpecType: 'EXACTLY',
+                        dateFrom: new Date(2026, 0, 1),
+                        dateTo: new Date(2026, 0, 31),
+                    },
+                    scope: 'ALL',
+                    transactionIds: '',
+                    datesType: 'CREATED',
+                    recurrentFilter: 'ALL',
+                    timeZoneOffsetHours: null,
+                    csvCharset: null,
+                }}
+                onFiltersUpdate={criteria => setSearchCriteria(criteria)}
+                onValidationChange={setValidation}
+                config={{
+                    dateRange: {
+                        dateRangeSpecTypes: DATE_RANGE_SPEC_TYPES.filter(
+                            type => type !== 'DATE_INDEPENDENT',
+                        ),
+                        maxRangeSpanInDays: 93,
+                    },
+                }}
+            />
+
+            <PneButton
+                disabled={searchCriteria === null || !validation?.isValid}
+                onClick={generateReport}
+            >
+                Generate report
+            </PneButton>
+        </SearchUIProvider>
+    </OverlayHost>
+}
+```
+
+У высокоуровневого `SearchUI` используются те же `possibleCriteria`,
+`predefinedCriteria`, `initialSearchConditions`, `config` и
+`onValidationChange`; результат для бэкенда передаётся в `searchData` как часть
+`SearchParams`.
+
+Поддерживаемые значения специализированных полей:
+
+- `scope`: `ALL`, `SELECTED_BY_SESS_ID`, `SELECTED_BY_PROCESSOR_TX_ID`,
+  `SELECTED_BY_MOTHER_SESS_ID`, `SELECTED_BY_MOTHER_PROCESSOR_TX_ID`,
+  `SELECTED_BY_TX_RRN`;
+- `datesType`: библиотека поддерживает только `CREATED`. Backend enum и Wicket
+  также принимают deprecated-вариант `BANK`, который сейчас обрабатывается как
+  тот же диапазон created dates; библиотека намеренно его не показывает;
+- `recurrentFilter`: `ALL`, `RECURRENTS_ONLY`, `NON_RECURRENTS_ONLY`;
+- `timeZoneOffsetHours`: `null` либо целое число от `-12` до `12`;
+- `csvCharset`: `null`, `UTF-8`, `UTF-8-SIG` или `windows-1251`.
+
+`transactionIds` — необязательная строка, которая показывается только при
+`scope !== 'ALL'` и передаётся библиотекой без преобразования и UI-валидации.
+Backend заменяет каждую непрерывную группу whitespace, запятых, точек с запятой,
+одинарных/двойных кавычек и NUL одним разделителем-запятой. Для scope с числовыми
+order ID он затем молча отбрасывает фрагменты с недесятичными символами. Проверка,
+отключающая период при непустых ID, выполняется backend по исходной строке до
+этой нормализации.
+
+`timeZoneOffsetHours: null` включает backend fallback на серверный сдвиг
+таймзоны, а `csvCharset: null` — выбор кодировки на сервере по данным браузера.
+Wicket сразу показывает эти вычисленные значения в обязательных dropdown; React
+для `null` показывает `Default`. Если нужна точная визуальная parity с Wicket,
+передайте вычисленные конкретные значения вместо `null`.
+
+`UTF-8-SIG` экспонируется библиотекой в соответствии с UI-контрактом, но в
+текущем endpoint отчётов ещё нет обязательного backend mapping строки
+`UTF-8-SIG` на custom charset с BOM. До появления такого mapping выбор этого
+значения не является end-to-end поддержанным и не должен отправляться в
+production-запросе.
+
+Если диапазон невалиден, встроенная кнопка Search/Refresh блокируется и
+`onFiltersUpdate` не публикует невалидный черновик. При валидном изменении пример
+выше сразу синхронизирует актуальные критерии, а внешнюю кнопку Generate блокирует
+через `onValidationChange`.
+
+Если отдельно включить `manualSearch: true`, пользователь должен сначала применить
+изменения встроенной кнопкой Search и только затем запускать Generate: до Search в
+`onFiltersUpdate` остаются последние применённые критерии.
+
+### Ограничение типов транзакций
+
+Чтобы показать в `TRANSACTION_TYPES` только часть общего справочника, передайте
+точные системные имена в `config.transactionTypes.allowedNames`. Имена сравниваются
+с полем `displayName`, а числовые ID берутся из справочника текущего инстанса.
+
+```tsx
+<SearchUIFilters
+    settingsContextName="fraud-chargeback-report"
+    possibleCriteria={[CriterionTypeEnum.TRANSACTION_TYPES]}
+    predefinedCriteria={[CriterionTypeEnum.TRANSACTION_TYPES]}
+    onFiltersUpdate={handleFiltersUpdate}
+    config={{
+        transactionTypes: {
+            allowedNames: ['chargeback', 'fraud'],
+        },
+    }}
+/>
+```
+
+При таком ограничении значение `All` соответствует всем разрешённым типам и
+передаёт их фактические ID в `SearchCriteria.transactionTypes`. Пока справочник
+не загружен, фильтры не инициализируются и промежуточный неограниченный запрос не
+отправляется. Без `config.transactionTypes` сохраняется прежний контракт:
+`All` сериализуется как пустой массив.
+
 ### Динамическая доступность критериев
 
 Если критерий должен быть доступен только при определённом состоянии фильтров,
@@ -1070,6 +1751,25 @@ const config = {
 />
 ```
 
+### Первичная загрузка и сохранённые шаблоны
+
+При монтировании `SearchUIFilters` определяет источник начальных условий до
+первого связанного с шаблонами вызова `onFiltersUpdate`. Источники имеют
+следующий приоритет: внешние `searchConditions`, восстановленное in-memory
+состояние, последний сохранённый шаблон, затем `initialSearchConditions` и
+значения по умолчанию.
+
+Если имя последнего шаблона сохранено, фильтры дожидаются `getSearchTemplates`,
+применяют найденный шаблон и только после этого выполняют первый поиск. Если
+шаблон отсутствует или загрузка завершилась ошибкой, выполняется один fallback-
+поиск с начальными значениями. Когда сохранённого имени нет, начальный поиск не
+ждёт фоновой загрузки списка шаблонов.
+
+Поэтому отдельный признак готовности шаблонов потребителю не требуется: загрузка
+шаблонов не публикует промежуточные критерии. Компонент `SearchUI` соблюдает тот
+же контракт и не вызывает `searchData` сначала с начальными значениями, а затем
+повторно с автоматически восстановленным шаблоном.
+
 ### Ручной режим поиска (manual search)
 
 По умолчанию любое изменение фильтра немедленно запускает новый запрос.
@@ -1097,15 +1797,48 @@ const config = {
 />
 ```
 
-При первой загрузке запрос всё равно отправляется автоматически, чтобы
-пользователь сразу видел данные. Кнопка Search становится активной только
+При первой загрузке итоговый запрос всё равно отправляется автоматически, чтобы
+пользователь сразу видел данные. Если сохранён последний шаблон, не выполняется
+предварительный запрос с начальными значениями: первый связанный с шаблонами
+запрос сразу использует его условия. Кнопка Search становится активной только
 после того, как фильтры были изменены.
 
 Исключения из этого правила тоже остаются автоматическими:
-- применение сохранённого шаблона, включая автозагрузку последнего шаблона;
+
+- применение пользователем сохранённого шаблона после инициализации;
 - внешняя синхронизация через проп `searchConditions` (например, клик по
   значению вне панели SearchUI).
 
+### Относительные диапазоны дат
+
+Относительные календарные и скользящие диапазоны (`TODAY`, `DAYS_BEFORE`,
+`HOURS_BEFORE` и аналогичные) являются декларативными пресетами. Хост должен
+передавать тип диапазона и его параметры, а вычисление конкретных `dateFrom` и
+`dateTo` оставлять `SearchUI`:
+
+```tsx
+import {SearchUIDateRangeSpec} from 'pne-ui'
+
+const last30Days = {
+    dateRangeSpecType: 'DAYS_BEFORE',
+    beforeCount: 30,
+} satisfies SearchUIDateRangeSpec
+```
+
+`SearchUI` пересчитывает такой диапазон при применении внешних `searchConditions`,
+восстановлении шаблона или сохранённого состояния и перед выполнением повторного
+Search. Поэтому не вычисляйте относительные даты заранее в хосте:
+иначе сохранённый `dateTo` со временем превращается в устаревшую верхнюю границу.
+Для `EXACTLY`, напротив, `dateFrom` и `dateTo` задаются явно и не пересчитываются;
+`DATE_INDEPENDENT` конкретного диапазона вообще не имеет.
+
+Публичные props `SearchUI` и `SearchUIFilters` проверяют эту форму и на этапе
+компиляции, и в runtime. Поэтому относительные пресеты не принимают `dateFrom` /
+`dateTo`, `EXACTLY` требует обе даты и не принимает `beforeCount`, а
+`DAYS_BEFORE` / `HOURS_BEFORE` требуют положительный целый `beforeCount`.
+Формат уже сохранённых пользовательских шаблонов не меняется: он остаётся
+обратно совместимым внутренним resolved-state форматом.
+
 ### Автоматическое восстановление состояния
 
 `SearchUI` и `SearchUIFilters` автоматически сохраняют текущее состояние фильтров
@@ -1167,10 +1900,13 @@ export default i18n
 
 ## Темизация компонентов MUI
 
-`pne-ui` поставляет вспомогательную функцию `createPneTheme` и тип `Skin`.  
+`pne-ui` поставляет `createPneTheme`, `PneThemeProvider` и тип `Skin`.
 `Skin` описывает корпоративные цвета Paynet (цвета хедера, меню и т.д.),
 а `createPneTheme(skin)` на их основе строит расширенную MUI-тему с дополнительными палитрами:
 `pnePrimary`, `pneNeutral`, `pnePrimaryLight`, `pneAccentuated`, `pneWhite`, `pneWarningLight`.
+По умолчанию тема остаётся светлой. Для тёмной схемы передайте `{colorMode: 'dark'}`; нейтральные
+surface/text/action-токены при этом меняются, а skin accent автоматически получает контрастный вариант для
+текста и отдельный исходный fill для contained-кнопок.
 
 ### Быстрый старт
 
@@ -1206,122 +1942,31 @@ 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`.
-
-### Пример использования
+Для управляемого режима используйте `PneThemeProvider`. Он создаёт один MUI `ThemeProvider` и публикует
+`usePneColorMode()` для переключателя внутри выбранной области. Компонент намеренно ничего не читает и не пишет
+в `localStorage`: загрузка, optimistic update, rollback и сохранение пользовательской настройки принадлежат
+приложению. Вложенный provider позволяет сначала включить dark mode только для одной страницы; React portals
+этой страницы сохраняют её theme context.
 
 ```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 })
-}
+import {PneThemeProvider, type PneColorMode} from 'pne-ui'
 
-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>
-    )
-}
+const [mode, setMode] = useState<PneColorMode>('light')
 
-export const Dashboard = () => (
-    <WidgetBoardScopeProvider>
-        <DashboardContent />
-    </WidgetBoardScopeProvider>
+return (
+    <PneThemeProvider skin={skin} mode={mode} onModeChange={setMode}>
+        <OrderDetails />
+    </PneThemeProvider>
 )
 ```
 
-`WidgetBoard` сам обновляет выбранный лейаут, следит за состоянием виджетов и при изменениях дергает `saveLayouts`
-с актуальным набором опций.
+Новые роли доступны в `theme.palette.pne`: `surface.sunken/subtle/raised`,
+`border.default/control`, `text.muted` и `brand`. В `brand` исходный `seed/fill` отделён от автоматически
+адаптированного `foreground`; используйте `foreground` для ссылок, иконок и заголовков на тёмных surfaces,
+а `fill/onFill/fillBorder` — для залитых controls. `createPneThemeOptions` возвращает те же чистые MUI
+`ThemeOptions`, если consumer должен сам вызвать свою `createTheme`.
 
 ## OverlayHost и уведомления
 
@@ -1360,8 +2005,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`.
 
@@ -1385,7 +2033,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> },
@@ -1395,7 +2043,7 @@ export const FabDemo = () => (
     <PneFloatingActionButtons
         actions={actions}
         fabLabel='Actions'
-        bannerText='Edit widgets'
+        bannerText='Page actions'
         position={{ bottom: 24, right: 24 }}
         mobileBreakpoint={900} // считать мобильным до 900px, иначе поведение как на десктопе
     />
@@ -1408,41 +2056,28 @@ export const FabDemo = () => (
 
 ## Публикация пакета
 
-Перед публикацией выполните `yarn npmLogin`. Release-команды проверяют npm-сессию, запускают тесты, линтер, сборку и
-`npm pack --dry-run` перед `npm publish`.
-
-Стабильные версии публикуются под npm dist-tag `latest`:
+Релиз запускается явной отправкой тега `npm/v<version>` через `yarn release:send`. Обычный push ветки не
+запускает проверки или публикацию. Единственный workflow `publish.yml` собирает, проверяет и упаковывает
+библиотеку, затем публикует проверенный архив через npm Trusted Publishing / OIDC.
 
 | Команда | Результат |
 | --- | --- |
-| `yarn release` / `yarn release:patch` | Для стабильной версии поднять patch; для RC снять `-rc.N`. Затем опубликовать. Это команда по умолчанию, если отдельный bump был забыт. |
-| `yarn release:minor` | Поднять minor и опубликовать. |
-| `yarn release:major` | Поднять major и опубликовать. |
-| `yarn release:stable` | Снять текущий `-rc.N` и опубликовать стабильную версию; для уже стабильной версии работает как patch release. |
-| `yarn release:current` / `yarn publish:stable` | Опубликовать уже выставленную стабильную версию без изменения номера. |
-
-RC-версии публикуются под dist-tag `next`, поэтому не заменяют стабильную версию для обычной установки:
-
-| Команда | Результат |
-| --- | --- |
-| `yarn release:rc:current` | Опубликовать уже выставленную RC-версию без изменения номера. |
-| `yarn release:rc:next` | Например, `4.3.0-rc.0` → `4.3.0-rc.1`, затем опубликовать. |
-| `yarn release:rc:patch` | Начать следующую patch RC-линейку и опубликовать. |
-| `yarn release:rc:minor` | Начать следующую minor RC-линейку и опубликовать. |
-| `yarn release:rc:major` | Начать следующую major RC-линейку и опубликовать. |
-
-Версию можно изменить отдельно, без публикации: `yarn version:patch`, `yarn version:minor`, `yarn version:major`,
-`yarn version:rc:patch`, `yarn version:rc:minor`, `yarn version:rc:major` или `yarn version:rc:next`. После ручного bump
-используйте `yarn publish:stable` либо `yarn publish:rc`; команда должна соответствовать типу версии в `package.json`.
-Повторный запуск составной `release:*`-команды поднимет версию ещё раз.
-
-Если публикация завершилась ошибкой уже после bump, исправьте причину и повторите только `yarn publish:stable` или
-`yarn publish:rc`. Скрипты меняют `package.json`, но не создают git commit и tag — их следует оформить отдельно.
+| `yarn release:prepare --channel next --bump prerelease` | Подготовить следующую RC-версию, локальный version commit и annotated tag; ничего не отправлять. |
+| `yarn release:prepare --channel latest --bump patch` | Подготовить стабильную версию из `master`. Доступны также `minor` / `major`. |
+| `yarn release:prepare --channel next --version <точная-rc-версия>` | Выбрать номер явно; `--version current` использует текущий номер из `package.json`. |
+| `yarn release:send --dry-run` | Проверить подготовленный релиз и показать адресную отправку ветки и одного тега без push. |
+| `yarn release:send` | Атомарно отправить подготовленную ветку и один релизный тег в `origin`, запуская публикацию. |
+| `yarn release:status` | Прочитать состояние релиза без изменения git refs и npm-пакета. |
+
+RC публикуются под `next`; стабильные версии — под `latest` и только из истории `master`.
+Сначала требуется однократная настройка доверия npm/GitHub и доставка нового workflow на релизные ветки.
+Подробные команды, ограничения и порядок внедрения описаны в [docs/releasing.md](docs/releasing.md).
+Локальный Storybook остаётся доступен через `yarn storybook` и `yarn build-storybook`; Chromatic не используется.
 
 [npm-url]: https://www.npmjs.com/package/pne-ui
 
 [npm-image]: https://img.shields.io/npm/v/pne-ui
 
-[github-build]: https://github.com/alcovp/pne-ui/actions/workflows/publish.yml/badge.svg
+[github-publish]: https://github.com/alcovp/pne-ui/actions/workflows/publish.yml/badge.svg
 
-[github-build-url]: https://github.com/alcovp/pne-ui/actions/workflows/publish.yml
+[github-publish-url]: https://github.com/alcovp/pne-ui/actions/workflows/publish.yml