@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/table/data-table.en.md

@@ -0,0 +1,137 @@
+---
+component: DataTable
+exports: [DataTable]
+category: table
+status: stable
+source: src/components/table/DataTable.tsx
+story: src/components/app-shell/AppShell.stories.tsx
+sourceHash: a5e9fc1a0c10
+---
+
+# DataTable
+
+## Summary for AI
+
+An application-level table with ready-made behavior on top of the low-level `Table`:
+column visibility and order, density, loading and error states, a table bar slot
+(`toolbar`). It keeps no state of its own: it accepts `state` and reports changes as a
+patch, usually to `useTableState`.
+
+## When to use
+
+- A list of entities in an admin panel: filters, column preferences, bulk actions.
+- Anywhere a table needs a table bar and user preferences.
+
+## When not to use
+
+- For a simple table without settings — that is `Table`: it stays low-level and
+  puts nothing extra into the markup.
+- For "property — value" pairs — that is `DescriptionList`.
+
+## Minimal example
+
+```tsx
+import { DataTable, TableToolbar, useTableState } from "@olddevs/ui";
+
+const { state, set } = useTableState();
+
+<DataTable
+  aria-label="Documents"
+  columns={columns}
+  items={rows}
+  state={state}
+  onStateChange={set}
+  selectable
+  loading={isFetching}
+  error={error ? <ErrorState title="Failed to load" /> : undefined}
+  toolbar={<TableToolbar title="Documents" count={total} />}
+/>;
+```
+
+## Props
+
+| Prop            | Default | Purpose                                                              |
+| --------------- | ------- | -------------------------------------------------------------------- |
+| `state`         | —       | The whole state. Usually from `useTableState`.                       |
+| `onStateChange` | —       | Changes as a single patch: invariants live in the hook, not here.    |
+| `selectable`    | `false` | The checkbox column. A separate prop — see below.                    |
+| `loading`       | `false` | Loading is in progress. The behavior depends on whether data exists. |
+| `error`         | —       | **Always** replaces the body, even when there is data.               |
+| `toolbar`       | —       | The table bar — usually `TableToolbar`.                              |
+
+The other props go to `Table` — including `renderDetail`, `rowLabel` and
+`onRowAction`.
+
+**A row action next to selection.** `onRowAction(item)` together with
+`selectable`: a click on a row and Enter open the record, while the checkboxes
+mark it. While nothing is selected, a click on a row is the action; once a
+selection exists, a click on a row toggles it (react-aria's rule), and the action
+stays on Enter. A link in a cell with a manual `stopPropagation` is not needed
+for this: a manual `stopPropagation` is an anti-pattern, it breaks the row's keyboard model. Details
+and the anti-pattern are in [Data display](../content/data-display.md).
+
+**Hydration.** `aria-sort` is set by react-aria, and only after hydration: on
+Android it is absent altogether, on other platforms every sortable column has
+it, and the server does not know the platform. So the server markup of a table
+with sorting matches the client's, and React does not report a mismatch.
+
+## The boundary with `Table`
+
+**An add-on, not a replacement.** Inside is the same `Table` as outside: column
+visibility and order, density and states are expressed by its props. Only the
+expansion axis had to be added to `Table` itself: the detail
+row lives inside `<tbody>`, between the react-aria collection rows, and an
+add-on cannot insert it
+(ADR-0022).
+
+A boundary violation has a verifiable sign: **if something could have been
+done with props from outside and it ended up inside `Table`, the boundary has
+already shifted.**
+
+**`selectable` is a separate prop, not "since there is state, it is needed".**
+`selectedKeys` is always in the state, and if the add-on passed it
+unconditionally, the checkbox column would appear on tables that do not need
+selection. The add-on does not override the `Table` rule "an axis is enabled by the
+presence of a prop".
+
+**A hidden column does not make it into the markup**; it is not hidden with a
+class: a hidden column would stay in the accessibility tree as a header without
+cells, and a screen reader would read a table with a column that is not on screen.
+
+## The table does not own the data
+
+**`items` are not split into pages.** `state.page` and `state.pageSize` are part
+of the state and are carried into the URL, but slicing is the consumer's job: in
+an app these are the server request parameters, not an array slice in the
+component. The kit knows neither the total number of records nor where they come
+from.
+
+The same goes for sorting and filters: `DataTable` reports them as a state patch
+and shows what it is given. Filtered and sorted data arrives from outside.
+
+## Loading, empty and error
+
+**The first load and a refetch** are told apart — a single priority order (error, loading, empty) is wrong here:
+
+| State                    | What is on screen                                       |
+| ------------------------ | ------------------------------------------------------- |
+| Error                    | Instead of the body, **always**, even when data exists  |
+| Loading **without** data | A skeleton instead of the body, the column headers stay |
+| Loading **with** data    | The data stays under `aria-busy`, dimmed                |
+| Empty                    | Only when loading has finished and there is no error    |
+
+Data shown alongside an error lies: the user cannot tell stale from current. And
+collapsing the table into a skeleton on every page change is a layout jump on
+every step, and that jump is why the rule was rewritten.
+
+## Related sources and tests
+
+- Implementation: `src/components/table/DataTable.tsx`.
+- Tests: `tests/data-table.test.tsx` — column preferences, the four states and
+  telling the first load from a refetch, no checkbox column without
+  `selectable`, expansion through state.
+- `tests/table-row-action.test.tsx` — `onRowAction` next to selection;
+  `tests/table-hydration.test.tsx` — server markup and hydration of sortable
+  columns, including on Android.
+- Story: `AdminEntityList` in
+  `src/components/app-shell/AppShell.stories.tsx`.

package/docs/components/table/data-table.md

@@ -0,0 +1,133 @@
+---
+component: DataTable
+exports: [DataTable]
+category: table
+status: stable
+source: src/components/table/DataTable.tsx
+story: src/components/app-shell/AppShell.stories.tsx
+---
+
+# DataTable
+
+## Кратко для AI
+
+Прикладная таблица с готовым поведением поверх низкоуровневой `Table`: видимость
+и порядок колонок, плотность, состояния загрузки и ошибки, слот полосы над
+таблицей (`toolbar`). Своего состояния не хранит: принимает `state` и отдаёт
+изменения патчем, обычно в `useTableState`.
+
+## Когда использовать
+
+- Список сущностей в админке: фильтры, настройки колонок, массовые действия.
+- Везде, где нужны полоса над таблицей и настройки пользователя.
+
+## Когда не использовать
+
+- Для простой таблицы без настроек — это `Table`: она остаётся низкоуровневой и
+  ничего лишнего в разметку не кладёт.
+- Для пар «свойство — значение» — это `DescriptionList`.
+
+## Минимальный пример
+
+```tsx
+import { DataTable, TableToolbar, useTableState } from "@olddevs/ui";
+
+const { state, set } = useTableState();
+
+<DataTable
+  aria-label="Документы"
+  columns={columns}
+  items={rows}
+  state={state}
+  onStateChange={set}
+  selectable
+  loading={isFetching}
+  error={error ? <ErrorState title="Не удалось загрузить" /> : undefined}
+  toolbar={<TableToolbar title="Документы" count={total} />}
+/>;
+```
+
+## Пропы
+
+| Проп            | Умолчание | Назначение                                                   |
+| --------------- | --------- | ------------------------------------------------------------ |
+| `state`         | —         | Состояние целиком. Обычно из `useTableState`.                |
+| `onStateChange` | —         | Изменения одним патчем: инварианты живут в хуке, а не здесь. |
+| `selectable`    | `false`   | Колонка флажков. Отдельный проп — см. ниже.                  |
+| `loading`       | `false`   | Идёт загрузка. Поведение зависит от наличия данных.          |
+| `error`         | —         | Замещает тело **всегда**, даже когда данные есть.            |
+| `toolbar`       | —         | Полоса над таблицей — обычно `TableToolbar`.                 |
+
+Остальные пропы уходят в `Table` — включая `renderDetail`, `rowLabel` и
+`onRowAction`.
+
+**Действие по строке рядом с выделением.** `onRowAction(item)` вместе с
+`selectable`: клик по строке и Enter открывают запись, а отмечают её флажки.
+Пока ничего не выделено, клик по строке — действие; когда выделение появилось,
+клик по строке его переключает (правило react-aria), а действие остаётся на
+Enter. Ссылка в ячейке с ручным `stopPropagation` для этого не нужна: ручной
+`stopPropagation` — антипаттерн, он ломает клавиатурную модель строки. Подробности и антипаттерн —
+в [Data display](../content/data-display.md).
+
+**Гидратация.** `aria-sort` ставит react-aria, и только после гидратации: на
+Android его нет вовсе, на остальных платформах он есть у каждой сортируемой
+колонки, а сервер платформы не знает. Поэтому серверная разметка таблицы с
+сортировкой совпадает с клиентской, и React не пишет о расхождении.
+
+## Граница с `Table`
+
+**Надстройка, а не замена.** Внутри — та же `Table`, что снаружи: видимость и
+порядок колонок, плотность и состояния выражаются её пропами. В саму `Table`
+пришлось добавить только ось раскрытия: детальная строка живёт
+внутри `<tbody>`, между строками коллекции react-aria, и вставить её надстройкой
+невозможно (ADR-0022).
+
+Признак нарушения границы проверяемый: **если что-то можно было сделать пропами
+снаружи, а оно оказалось внутри `Table`, — граница уже сдвинулась.**
+
+**`selectable` — отдельный проп, а не «раз состояние есть, значит нужно».** В
+состоянии `selectedKeys` лежит всегда, и передавай надстройка его безусловно,
+колонка флажков появлялась бы у таблиц, которым выделение не нужно. Правило
+`Table` «ось включается наличием пропа» надстройка не отменяет.
+
+**Скрытая колонка не попадает в разметку**, а не прячется классом: спрятанная
+колонка остаётся в дереве доступности заголовком без ячеек, и скринридер читает
+таблицу с колонкой, которой на экране нет.
+
+## Данными таблица не владеет
+
+**`items` не режутся на страницы.** `state.page` и `state.pageSize` — часть
+состояния и переносятся в адрес страницы, но нарезка — работа потребителя: в приложении
+это параметры запроса к серверу, а не срез массива в компоненте. Кит не знает ни
+про общее число записей, ни про то, откуда они приходят.
+
+То же про сортировку и фильтры: `DataTable` сообщает о них патчем состояния и
+показывает то, что ему дали. Отфильтрованные и отсортированные данные приходят
+снаружи.
+
+## Загрузка, пустота и ошибка
+
+Различаются **первая загрузка и перезапрос** — единый порядок приоритетов (ошибка, загрузка, пусто) тут неверен:
+
+| Состояние               | Что на экране                                  |
+| ----------------------- | ---------------------------------------------- |
+| Ошибка                  | Вместо тела **всегда**, даже когда данные есть |
+| Загрузка **без** данных | Скелет вместо тела, заголовки колонок на месте |
+| Загрузка **с** данными  | Данные остаются под `aria-busy`, приглушённые  |
+| Пусто                   | Только когда загрузка кончилась и ошибки нет   |
+
+Данные, показанные при ошибке, врут: отличить устаревшие от актуальных
+пользователь не может. А схлопывать таблицу в скелет на каждой смене страницы —
+скачок раскладки на каждом шаге, из-за которого правило переписано.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/table/DataTable.tsx`.
+- Тесты: `tests/data-table.test.tsx` — настройки колонок, четыре состояния и
+  отличие первой загрузки от перезапроса, отсутствие колонки флажков без
+  `selectable`, раскрытие через состояние.
+- `tests/table-row-action.test.tsx` — `onRowAction` рядом с выделением;
+  `tests/table-hydration.test.tsx` — серверная разметка и гидратация сортируемых
+  колонок, в том числе под Android.
+- История: `AdminEntityList` в
+  `src/components/app-shell/AppShell.stories.tsx`.

package/docs/components/table/filter-bar.en.md

@@ -0,0 +1,161 @@
+---
+component: FilterBar
+exports: [FilterBar, FilterBarAdd]
+category: table
+status: stable
+source: src/components/table/FilterBar.tsx, src/components/table/FilterBarAdd.tsx
+story: src/components/table/FilterBar.stories.tsx
+sourceHash: 8dfb10955692
+---
+
+# FilterBar and FilterBarAdd
+
+## Summary for AI
+
+`FilterBar` shows the applied filters as removable tokens; `FilterBarAdd` is an
+add button with a choice of field and value, or of range bounds (amount, date).
+Neither **knows which filters exist**: the list is passed as a prop, and the
+kit has no domain vocabulary.
+
+## When to use
+
+- Above a list with more than one filter, where the set of filters changes.
+- In the `filters` slot of `TableToolbar`.
+
+## When not to use
+
+- For toggling a single attribute ("favorites only") — that is a `Chip` or
+  `Segmented`: there it is a toggle, not a removal.
+- For entering arbitrary text — that is `SearchControl`.
+- For a "contains" or "one of" filter — apart from equality and a range there
+  are no operators in the model (see below).
+
+## Minimal example
+
+```tsx
+import { FilterBar, FilterBarAdd, useTableState } from "@olddevs/ui";
+
+const { state, set } = useTableState();
+
+<FilterBar filters={state.filters} onFiltersChange={(filters) => set({ filters })}>
+  <FilterBarAdd
+    fields={FIELDS}
+    filters={state.filters}
+    onAdd={(f) => set({ filters: [...state.filters, f] })}
+  />
+</FilterBar>;
+```
+
+## `FilterField` — a field description
+
+```ts
+interface FilterField {
+  id: string;
+  /** The field label. A string: it also ends up in the token label. */
+  label: string;
+  /** The field kind. Defaults to "values". */
+  kind?: "values" | "number-range" | "date-range";
+  /** Allowed values for "values". With an empty list the field does not appear in the field list; for ranges pass []. */
+  values: { id: string; label: string }[];
+}
+```
+
+The list of fields is passed as a prop in full: the kit does not know which
+filters exist in your product, and no domain vocabulary appears in it.
+
+## Ranges
+
+`kind: "number-range"` and `kind: "date-range"` (ADR-0063)
+replace the choice of a value with two inputs, "From" and "To": a `NumberInput`
+for numbers and a `DatePicker` for dates. The field is described with an empty `values`:
+
+```tsx
+const FIELDS: FilterField[] = [
+  { id: "amount", label: "Amount", kind: "number-range", values: [] },
+  { id: "created", label: "Created", kind: "date-range", values: [] },
+  { id: "status", label: "Status", values: STATUSES },
+];
+```
+
+The filter that gets built is an ordinary `TableFilter` with an optional `to`:
+
+| What was entered   | `value` | `to`           | Token label                  |
+| ------------------ | ------- | -------------- | ---------------------------- |
+| 50 and 100         | `"50"`  | `"100"`        | "Amount: 50–100"             |
+| only "from" 50     | `"50"`  | `""`           | "Amount: from 50"            |
+| only "to" 100      | `""`    | `"100"`        | "Amount: to 100"             |
+| only "to" March 12 | `""`    | `"2026-03-12"` | "Created: to March 12, 2026" |
+
+- **`to` present — a range, `to` absent — equality.** An empty string in `to`
+  is not the same as a missing key: it is an open bound, and check it
+  with `to !== undefined`. Numbers are passed as strings, dates as ISO `YYYY-MM-DD`,
+  as everywhere in the kit.
+- **"Apply" is enabled once at least one bound is set.** An inverted range
+  ("from 100 to 50") cannot be applied: it would select nothing, and the user
+  would read an empty result as "no data". In the "To" calendar the dates before
+  "From" are unavailable, and vice versa.
+- **The kit builds the label** through the message catalog: the labels of the "From"
+  and "To" inputs are `fromField` and `toField`, the token label templates are
+  `rangeBetween`, `rangeFrom`, `rangeTo`. Numbers and dates in the label are
+  formatted in the `UiProvider` locale; a date always includes the year: the
+  label is stored in the page URL and in a saved view, and a link labeled "to
+  March 12" would mean a different date when it is opened a year later. The label
+  is stored in the filter's `label` and in the page URL. If a filter has `to` but
+  no `label`, `FilterBar` labels it with the same templates, but the bounds in
+  the label stay raw, unformatted.
+- **A field with an already applied range is not offered again.** Two ranges on
+  one field are an intersection, not an addition, and the tokens could not be
+  told apart. The token identifier is `<field>:range`.
+- **The consumer computes the result set.** The kit describes the shape of the
+  filter, it does not filter data
+  (ADR-0023):
+  how to treat the bounds (inclusive, in which time zone) is the application's
+  decision.
+- **In the page URL** (`tableStateToParams`) `to` is written as the fifth part of
+  the filter entry; links of three and four parts are read as before. The fifth part is
+  written even when empty, otherwise "from 50" would turn into equality.
+
+## Decisions visible in the API
+
+**The tokens are built on react-aria's `TagGroup`, not on `Chip`.** A chip cannot be
+removed; it is for toggling. Keyboard support comes without extra work: Delete and
+Backspace on a token remove it.
+
+**A token has its own `id`, and the label is not an identifier.** Two filters on
+the same field produce tokens that look identical, and removing the right one by
+label would be impossible; the label is also localized and truncated. A token is
+removed by `filter.id`.
+
+**There are no operators in the model.** Without `to` a token means equality, with
+`to` — a range: `gte` and `lte` are the same range with an empty bound and do not
+deserve an axis of their own
+(ADR-0063).
+`contains` and `in` still wait for a requesting screen
+(ADR-0023).
+
+**The remove button's label is generic, without the filter's name.** react-aria
+appends its tag's label to the button's name by itself; adding the filter name by hand produced
+"Remove filter Section: Contracts Section: Contracts". The screen reader still
+reads the filter — the library adds it. This is checked against the computed
+accessible name, not the markup.
+
+**"Clear all" appears once there are two filters.** With one filter the button does
+exactly what the token's remove button does and only lengthens keyboard navigation.
+
+**An already applied value is not offered again.** Otherwise the user adds a
+second identical token, the result does not change, and they are left with two
+filters that look the same. When there is nothing to add, the button is disabled.
+
+**Focus returns to the button after adding.** If focus is lost, it falls back to the start of
+the document and keyboard navigation of the page starts over.
+
+## Related sources and tests
+
+- Implementation: `src/components/table/FilterBar.tsx`, `src/components/table/FilterBarAdd.tsx`.
+- Tests: `tests/filter-bar.test.tsx` — removal by mouse and keyboard, the
+  composite button name, duplicate prevention, focus return, the two components
+  working together; `tests/filter-bar-ranges.test.tsx` — ranges (bounds, the
+  localized label, an inverted range); `tests/table-state.test.tsx` — `to` in the
+  page URL.
+- Story: `Ranges` and `RangesFromScratch` in `FilterBar.stories.tsx`.
+- State: [`useTableState`](../../api/utilities.md).

package/docs/components/table/filter-bar.md

@@ -0,0 +1,155 @@
+---
+component: FilterBar
+exports: [FilterBar, FilterBarAdd]
+category: table
+status: stable
+source: src/components/table/FilterBar.tsx, src/components/table/FilterBarAdd.tsx
+story: src/components/table/FilterBar.stories.tsx
+---
+
+# FilterBar и FilterBarAdd
+
+## Кратко для AI
+
+`FilterBar` показывает применённые фильтры снимаемыми токенами; `FilterBarAdd` —
+кнопка добавления с выбором поля и значения либо границ диапазона (сумма,
+дата). Оба **не знают, какие бывают фильтры**: список приходит пропом,
+доменного словаря в ките нет.
+
+## Когда использовать
+
+- Над списком, где фильтров больше одного и их состав меняется.
+- В слоте `filters` у `TableToolbar`.
+
+## Когда не использовать
+
+- Для переключения одного признака («только избранное») — это `Chip` или
+  `Segmented`: там переключение, а не снятие.
+- Для ввода произвольного текста — это `SearchControl`.
+- Для фильтра «содержит» или «одно из» — операторов, кроме равенства и
+  диапазона, в модели нет (см. ниже).
+
+## Минимальный пример
+
+```tsx
+import { FilterBar, FilterBarAdd, useTableState } from "@olddevs/ui";
+
+const { state, set } = useTableState();
+
+<FilterBar filters={state.filters} onFiltersChange={(filters) => set({ filters })}>
+  <FilterBarAdd
+    fields={FIELDS}
+    filters={state.filters}
+    onAdd={(f) => set({ filters: [...state.filters, f] })}
+  />
+</FilterBar>;
+```
+
+## `FilterField` — описание поля
+
+```ts
+interface FilterField {
+  id: string;
+  /** Подпись поля. Строка: она же попадает в подпись токена. */
+  label: string;
+  /** Вид поля. Не задан — "values". */
+  kind?: "values" | "number-range" | "date-range";
+  /** Допустимые значения для "values". Пустой список — поле не появится в списке полей; у диапазонов — []. */
+  values: { id: string; label: string }[];
+}
+```
+
+Список полей приходит пропом целиком: кит не знает, какие фильтры бывают в
+вашем продукте, и доменного словаря в нём не появляется.
+
+## Диапазоны
+
+`kind: "number-range"` и `kind: "date-range"` (ADR-0063)
+заменяют выбор значения двумя полями ввода «От» и «До»: `NumberInput` для чисел и
+`DatePicker` для дат. Поле описывается с пустым `values`:
+
+```tsx
+const FIELDS: FilterField[] = [
+  { id: "amount", label: "Сумма", kind: "number-range", values: [] },
+  { id: "created", label: "Создан", kind: "date-range", values: [] },
+  { id: "status", label: "Статус", values: STATUSES },
+];
+```
+
+Собранный фильтр — обычный `TableFilter` с необязательным `to`:
+
+| Что ввели            | `value` | `to`           | Подпись токена                |
+| -------------------- | ------- | -------------- | ----------------------------- |
+| 50 и 100             | `"50"`  | `"100"`        | «Сумма: 50–100»               |
+| только «от» 50       | `"50"`  | `""`           | «Сумма: от 50»                |
+| только «до» 100      | `""`    | `"100"`        | «Сумма: до 100»               |
+| только «до» 12 марта | `""`    | `"2026-03-12"` | «Создан: до 12 марта 2026 г.» |
+
+- **`to` есть — диапазон, `to` нет — равенство.** Пустая строка в `to` не то же
+  самое, что отсутствие ключа: это открытая граница, проверяйте её через
+  `to !== undefined`. Числа передаются строками, даты — ISO `ГГГГ-ММ-ДД`, как везде в
+  ките.
+- **«Применить» доступно, когда задана хотя бы одна граница.** Перевёрнутый
+  диапазон («от 100 до 50») применить нельзя: он ничего не выберет, а пустоту
+  пользователь прочтёт как «данных нет». В календаре «До» недоступны даты раньше
+  «От», и наоборот.
+- **Подпись собирает кит** через каталог сообщений: подписи полей ввода «От» и «До» —
+  `fromField` и `toField`, шаблоны подписи токена — `rangeBetween`, `rangeFrom`,
+  `rangeTo`. Числа и даты в подписи форматируются по локали `UiProvider`; год в
+  дате пишется всегда: подпись хранится в адресе страницы и в сохранённом виде,
+  и ссылка «до 12 марта», открытая через год, означала бы другую дату. Подпись
+  записывается в `label` фильтра и в адрес страницы. Если у фильтра есть `to`,
+  но нет `label`, `FilterBar` подпишет его теми же шаблонами, но границы в
+  подписи останутся сырыми, без форматирования.
+- **Поле с уже применённым диапазоном повторно не предлагается.** Два диапазона
+  по одному полю — пересечение, а не добавление, и токены нельзя было бы
+  различить. Идентификатор токена — `<поле>:range`.
+- **Выборку считает потребитель.** Кит описывает форму фильтра, а не фильтрует
+  данные (ADR-0023):
+  как трактовать границы (включительно, в каком часовом поясе) — решение
+  приложения.
+- **В адресе страницы** (`tableStateToParams`) `to` записывается пятой частью
+  записи фильтра; ссылки из
+  трёх и четырёх частей читаются как раньше. Пятая часть пишется и пустой,
+  иначе «от 50» превратилось бы в равенство.
+
+## Решения, которые видно в API
+
+**Токены стоят на `TagGroup` из react-aria, а не на `Chip`.** У чипа нет
+снятия: он предназначен для переключения. Клавиатура при этом достаётся без
+доработки: Delete и Backspace на токене снимают его.
+
+**У токена свой `id`, а подпись — не идентификатор.** Два фильтра по одному
+полю дают одинаковые на вид токены, и нельзя было бы снять нужный по подписи;
+подпись к тому же локализуется и обрезается. Токен снимается по `filter.id`.
+
+**Операторов в модели нет.** Без `to` токен означает равенство, с `to` —
+диапазон: `gte` и `lte` — тот же диапазон с пустой границей, отдельной оси они
+не заслуживают (ADR-0063).
+`contains` и `in` по-прежнему ждут заказчика
+(ADR-0023).
+
+**Подпись кнопки снятия — общая, без имени фильтра.** react-aria дописывает к
+имени кнопки подпись своего тега сам; когда имя фильтра дописывали в подпись вручную,
+получалось «Снять фильтр Раздел: Договоры Раздел: Договоры». Скринридер всё равно читает фильтр — его добавляет
+библиотека. Проверяется вычисленным доступным именем, а не разметкой.
+
+**«Снять все» появляется со второго фильтра.** При одном кнопка делает ровно то
+же, что кнопка снятия на самом токене, и только удлиняет обход с клавиатуры.
+
+**Уже применённое значение повторно не предлагается.** Иначе пользователь
+добавляет второй такой же токен, выборка не меняется, и пользователь остаётся с двумя
+одинаковыми на вид фильтрами. Когда добавлять нечего, кнопка недоступна.
+
+**Фокус после добавления возвращается на кнопку.** Потерянный фокус возвращается в
+начало документа, и обход страницы начинается заново.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/table/FilterBar.tsx`, `src/components/table/FilterBarAdd.tsx`.
+- Тесты: `tests/filter-bar.test.tsx` — снятие мышью и клавиатурой, составное имя
+  кнопки, запрет дублей, возврат фокуса, совместная работа обоих компонентов;
+  `tests/filter-bar-ranges.test.tsx` — диапазоны (границы, подпись по локали,
+  перевёрнутый диапазон); `tests/table-state.test.tsx` — `to` в адресе страницы.
+- История: `Ranges` и `RangesFromScratch` в `FilterBar.stories.tsx`.
+- Состояние: [`useTableState`](../../api/utilities.md).