@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/table/saved-views.en.md

@@ -0,0 +1,117 @@
+---
+component: SavedViews
+exports: [SavedViews]
+category: table
+status: stable
+source: src/components/table/SavedViews.tsx
+story: src/components/table/SavedViews.stories.tsx
+sourceHash: ea63c1085acc
+---
+
+# SavedViews
+
+## Summary for AI
+
+`SavedViews` is a switcher of named state snapshots. The kit shows the list of
+views and announces the active one; **where the views are stored, it does not know
+and should not know**. The view type is parameterized by the state snapshot
+(`SavedView<T>`), not tied to `TableState`.
+
+## When to use
+
+- Above a list, a table or a grid where the user keeps returning to the same sets
+  of filters: "Mine", "Drafts", "With errors".
+- When the set of views is created by the user, not the developer.
+
+## When not to use
+
+- For toggling a single attribute or a display mode — that is `Segmented`: it has
+  a fixed set of modes, not user-defined sets.
+- For showing the applied filters with the ability to remove any of them — that is
+  `FilterBar`: there filters are removed one at a time, here a whole set is chosen.
+- For navigation between sections — that is `Tabs`.
+
+## Minimal example
+
+```tsx
+import { SavedViews, type SavedView } from "@olddevs/ui";
+
+const views: SavedView<Filters>[] = [
+  { id: "all", name: "All", state: { status: "" } },
+  { id: "drafts", name: "Drafts", state: { status: "draft" } },
+];
+
+<SavedViews
+  views={views}
+  activeId={activeId}
+  onSelect={(view) => {
+    // The state arrives whole: apply it in a single action.
+    setActiveId(view.id);
+    applyFilters(view.state);
+  }}
+/>;
+```
+
+## `SavedView<T>` — the shape of a view
+
+```ts
+interface SavedView<T = unknown> {
+  id: string;
+  /** The view's name — also its label. */
+  name: ReactNode;
+  /** A state snapshot. The kit neither reads nor interprets it. */
+  state: T;
+}
+```
+
+The parameter `T` is your state, in whatever form you keep it: a filters object,
+`TableState`, a query string. The kit does not read it and hands it
+back as is on selection.
+
+## Decisions visible in the API
+
+**The type is parameterized by the state snapshot, not tied to `TableState`.** The type
+is the way it is because of the only known consumer: its state lives in the page
+URL, and its screen is a grid of cards, not a table. Tying it to `TableState`
+would cut that consumer off from a component written for it
+(ADR-0033).
+
+**The kit has no storage at all.** The component writes nothing (not to
+`localStorage`, not to the page URL, not to the network) and subscribes to nothing.
+The choice between the page URL, local storage and a server stays with the app; sharing
+views between users is a job for the backend. The model is the same as in
+[`useTableState`](../../api/utilities.md): the kit describes the shape, and the
+consumer owns it.
+
+This is verified by a test that stubs the storage APIs, not by convention: any
+access to `localStorage`, `sessionStorage` or `history` fails the run.
+
+**`onSelect` hands over the whole view in one call, not its identifier.** If the
+state goes into the page URL, consecutive writes by key build the URL from the
+same copy of the URL parameters in the current render: the last one wins, and the
+previous edits are lost. That is exactly what happened to a consumer, who lost the
+lower bound of a period when picking a range on top of a preset.
+
+**The active view is announced, not just highlighted.** Each view is a chip
+(`Chip`); it carries `aria-pressed`, and color highlighting tells a screen reader
+nothing.
+
+**The kit has no notion of "reset".** `activeId={null}` means "there is no active
+view". Returning to the default is done with a view that you put into the list
+yourself — its state snapshot is your empty state. The kit does not know what is empty
+for your app.
+
+**Creating, renaming and deleting a view are up to your app.** They are inseparable from
+storage, and there is no storage here.
+
+**An empty list is not rendered at all.** An empty group would announce itself to
+a screen reader with nothing inside — the same technique as in `Timeline`.
+
+## Related sources and tests
+
+- Implementation: `src/components/table/SavedViews.tsx`.
+- Tests: `tests/saved-views.test.tsx` — announcing the active view, one call with
+  the whole state snapshot, the storage guard, an empty list, the group's accessible
+  name.
+- Related: [`useTableState`](../../api/utilities.md),
+  [`FilterBar`](filter-bar.md).

package/docs/components/table/saved-views.md

@@ -0,0 +1,115 @@
+---
+component: SavedViews
+exports: [SavedViews]
+category: table
+status: stable
+source: src/components/table/SavedViews.tsx
+story: src/components/table/SavedViews.stories.tsx
+---
+
+# SavedViews
+
+## Кратко для AI
+
+`SavedViews` — переключатель именованных снимков состояния. Кит показывает
+список видов и объявляет активный; **где виды лежат, он не знает и знать не
+должен**. Тип вида параметризован снимком состояния (`SavedView<T>`), а не привязан к
+`TableState`.
+
+## Когда использовать
+
+- Над списком, таблицей или сеткой, где пользователь возвращается к одним и тем
+  же наборам фильтров: «Мои», «Черновики», «С ошибкой».
+- Когда набор видов создаёт пользователь, а не разработчик.
+
+## Когда не использовать
+
+- Для переключения одного признака или режима отображения — это `Segmented`:
+  там фиксированный набор режимов, а не пользовательские наборы.
+- Для показа применённых фильтров с возможностью снять любой — это `FilterBar`:
+  там снятие по одному, здесь выбор целиком.
+- Для навигации между разделами — это `Tabs`.
+
+## Минимальный пример
+
+```tsx
+import { SavedViews, type SavedView } from "@olddevs/ui";
+
+const views: SavedView<Filters>[] = [
+  { id: "all", name: "Все", state: { status: "" } },
+  { id: "drafts", name: "Черновики", state: { status: "draft" } },
+];
+
+<SavedViews
+  views={views}
+  activeId={activeId}
+  onSelect={(view) => {
+    // Состояние приходит целиком: применяйте его одним действием.
+    setActiveId(view.id);
+    applyFilters(view.state);
+  }}
+/>;
+```
+
+## `SavedView<T>` — форма вида
+
+```ts
+interface SavedView<T = unknown> {
+  id: string;
+  /** Имя вида — оно же подпись. */
+  name: ReactNode;
+  /** Снимок состояния. Кит его не читает и не интерпретирует. */
+  state: T;
+}
+```
+
+Параметр `T` — ваше состояние, каким вы его держите: объект фильтров,
+`TableState`, строка запроса. Кит не читает его и при выборе отдаёт
+как есть.
+
+## Решения, которые видно в API
+
+**Тип параметризован снимком состояния, а не привязан к `TableState`.** Тип таков
+из-за единственного известного потребителя: у него состояние живёт в адресе
+страницы, а экран — сетка карточек, а не таблица. Привязка к `TableState`
+отрезала бы его от компонента, написанного ради него же
+(ADR-0033).
+
+**Хранения в ките нет вовсе.** Компонент ничего не пишет (ни в `localStorage`,
+ни в адрес страницы, ни в сеть) и ни на что не подписывается. Выбор между адресом
+страницы, локальным хранилищем и сервером остаётся приложению; общий доступ к
+видам для разных пользователей — задача бэкенда. Модель та же, что у
+[`useTableState`](../../api/utilities.md): кит описывает форму, а владеет
+потребитель.
+
+Проверяется тестом, который подменяет хранилища, а не соглашением: любое
+обращение к `localStorage`, `sessionStorage` или `history` проваливает прогон.
+
+**`onSelect` отдаёт вид целиком за один вызов, а не его идентификатор.** Если
+состояние попадает в адрес страницы, последовательные записи по ключу строят
+адрес из одной и той же копии параметров адреса текущего рендера: побеждает
+последняя, правки предыдущих пропадают. Так и было у потребителя: терялась
+нижняя граница периода при выборе диапазона поверх пресета.
+
+**Активный вид объявляется, а не только подсвечивается.** Каждый вид — чип
+(`Chip`); он несёт `aria-pressed`, а подсветка цветом скринридеру ничего не
+сообщает.
+
+**Понятия «сброс» у кита нет.** `activeId={null}` означает «активного вида
+нет». Возврат к умолчанию делается видом, который вы кладёте в список сами:
+его снимок состояния и есть ваше пустое состояние. Кит не знает, что для вашего приложения
+пусто.
+
+**Создание, переименование и удаление вида — ваши.** Они неразрывны с
+хранением, а хранения здесь нет.
+
+**Пустой список не рисуется вовсе.** Пустая группа объявила бы себя
+скринридеру, не имея внутри ничего, — тот же приём, что у `Timeline`.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/table/SavedViews.tsx`.
+- Тесты: `tests/saved-views.test.tsx` — объявление активного вида, один вызов со
+  всем снимком состояния, запрет на хранение, пустой список, доступное имя группы.
+- Связанное: [`useTableState`](../../api/utilities.md),
+  [`FilterBar`](filter-bar.md).

package/docs/components/table/toolbar.en.md

@@ -0,0 +1,100 @@
+---
+component: TableToolbar
+exports: [TableToolbar, TablePreferences]
+category: table
+status: stable
+source: src/components/table/TableToolbar.tsx, src/components/table/TablePreferences.tsx
+story: src/components/table/TableToolbar.stories.tsx
+sourceHash: 957697357a68
+---
+
+# TableToolbar and TablePreferences
+
+## Summary for AI
+
+`TableToolbar` is the table bar: a title, a counter, actions, a filters slot and a
+preferences slot. `TablePreferences` is the content behind the gear button: column
+visibility and order, density. Neither stores state: everything comes from above,
+usually from `useTableState`.
+
+## When to use
+
+- Above a list that has a title, a counter or actions on the whole list (for example, export).
+- It works without `DataTable` too — above a plain `Table`.
+
+## When not to use
+
+- For actions on **selected** rows — that is `SelectionBar`.
+- For a page title with a description — that is `PageHeader`.
+
+## Minimal example
+
+```tsx
+import { Popover, PopoverContent, PopoverTrigger } from "@olddevs/ui";
+import { TablePreferences, TableToolbar, useTableState } from "@olddevs/ui";
+
+const { state, set } = useTableState();
+
+<TableToolbar
+  title="Documents"
+  count={total}
+  actions={<Button tone="accent">Upload</Button>}
+  preferences={
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="ghost" iconOnly icon={<SettingsIcon />} aria-label="Preferences" />
+      </PopoverTrigger>
+      <PopoverContent className="p-3">
+        <TablePreferences
+          columns={columns}
+          hiddenColumns={state.hiddenColumns}
+          onHiddenColumnsChange={(hiddenColumns) => set({ hiddenColumns })}
+          columnOrder={state.columnOrder}
+          onColumnOrderChange={(columnOrder) => set({ columnOrder })}
+          density={state.density}
+          onDensityChange={(density) => set({ density })}
+        />
+      </PopoverContent>
+    </Popover>
+  }
+/>;
+```
+
+## Decisions visible in the API
+
+**The bar has no `toolbar` role.** The role requires arrow-key navigation
+between its elements, and ARIA does not provide it by itself: by declaring
+the role without implementing the behavior, the kit would promise the screen
+reader something that is not there.
+
+**The counter is a number, not a ready-made string.** Pluralization is done by the
+message catalog per locale; `countLabel` overrides the label when the entity needs
+naming ("12 documents"). The same technique as in `SelectionBar`.
+
+**`TablePreferences` is a panel, not a menu.** A menu item is not a container for
+buttons: "Up" and "Down" buttons nested in it break the keyboard semantics of a menu,
+where the arrow keys belong to the menu itself. The consumer chooses the container —
+`Popover`, `Drawer` or `Dialog`.
+
+**The order is changed with buttons, not by dragging.** Dragging without a
+keyboard alternative is not accessible at all, and the alternative to it is these
+same buttons; providing both for one screen is out of proportion. The button
+labels name the column: otherwise a list of ten columns would have ten "Up"
+buttons and ten "Down" buttons.
+
+**`PopoverTrigger` requires `asChild`.** Without it Radix renders its own button
+around yours, you get a button inside a button, and the audit fails the run as
+`nested-interactive` — axe caught this on the very first story.
+
+**The last visible column cannot be hidden.** A table without columns is not a
+UI state but a breakage: there is nothing left to hide, and the user cannot
+get out of it. The restriction is one-way — a hidden column can always be brought back.
+
+## Related sources and tests
+
+- Implementation: `src/components/table/TableToolbar.tsx`,
+  `src/components/table/TablePreferences.tsx`.
+- Tests: `tests/table-toolbar.test.tsx` (slots, counter pluralization, no
+  `toolbar` role), `tests/table-preferences.test.tsx` (the guard against hiding the last
+  column, ordering from the keyboard, density).
+- State: [`useTableState`](../../api/utilities.md).

package/docs/components/table/toolbar.md

@@ -0,0 +1,97 @@
+---
+component: TableToolbar
+exports: [TableToolbar, TablePreferences]
+category: table
+status: stable
+source: src/components/table/TableToolbar.tsx, src/components/table/TablePreferences.tsx
+story: src/components/table/TableToolbar.stories.tsx
+---
+
+# TableToolbar и TablePreferences
+
+## Кратко для AI
+
+`TableToolbar` — полоса над таблицей: заголовок, счётчик, действия, слот
+фильтров и слот настроек. `TablePreferences` — содержимое поповера у кнопки-шестерёнки: видимость
+и порядок колонок, плотность. Ни один из них состояния не хранит: всё приходит сверху,
+обычно из `useTableState`.
+
+## Когда использовать
+
+- Над списком, у которого есть заголовок, счётчик или действия над всем списком (например, экспорт).
+- Работает и без `DataTable` — над обычной `Table` тоже.
+
+## Когда не использовать
+
+- Для действий над **выбранными** строками — это `SelectionBar`.
+- Для заголовка страницы с описанием — это `PageHeader`.
+
+## Минимальный пример
+
+```tsx
+import { Popover, PopoverContent, PopoverTrigger } from "@olddevs/ui";
+import { TablePreferences, TableToolbar, useTableState } from "@olddevs/ui";
+
+const { state, set } = useTableState();
+
+<TableToolbar
+  title="Документы"
+  count={total}
+  actions={<Button tone="accent">Загрузить</Button>}
+  preferences={
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="ghost" iconOnly icon={<SettingsIcon />} aria-label="Настройки" />
+      </PopoverTrigger>
+      <PopoverContent className="p-3">
+        <TablePreferences
+          columns={columns}
+          hiddenColumns={state.hiddenColumns}
+          onHiddenColumnsChange={(hiddenColumns) => set({ hiddenColumns })}
+          columnOrder={state.columnOrder}
+          onColumnOrderChange={(columnOrder) => set({ columnOrder })}
+          density={state.density}
+          onDensityChange={(density) => set({ density })}
+        />
+      </PopoverContent>
+    </Popover>
+  }
+/>;
+```
+
+## Решения, которые видно в API
+
+**Роли `toolbar` у полосы нет.** Роль требует навигации по элементам
+стрелками, а ARIA сама её не даёт: объявив роль и не
+реализовав поведение, кит пообещал бы скринридеру то, чего нет.
+
+**Счётчик — число, а не готовая строка.** Склонение делает каталог по локали;
+`countLabel` переопределяет подпись, когда нужно назвать сущность
+(«12 документов»). Тот же приём, что у `SelectionBar`.
+
+**`TablePreferences` — панель, а не меню.** Пункт меню не контейнер для кнопок:
+вложенные в него кнопки «Выше» и «Ниже» ломают клавиатурную семантику меню, где
+стрелки принадлежат самому меню. Контейнер — `Popover`, `Drawer` или `Dialog` —
+выбирает потребитель.
+
+**Порядок меняется кнопками, а не перетаскиванием.** Перетаскивание без
+клавиатурной альтернативы недоступно вовсе, а альтернатива к нему — эти же
+кнопки; заводить оба способа ради одного экрана несоразмерно. Подписи кнопок
+называют колонку: иначе в списке из десяти колонок десять кнопок «Выше» и десять «Ниже».
+
+**`PopoverTrigger` требует `asChild`.** Без него Radix рисует свою кнопку вокруг
+вашей, получается кнопка в кнопке, и аудит проваливает прогон как `nested-interactive`
+— это поймал axe на первой же истории.
+
+**Последнюю видимую колонку скрыть нельзя.** Таблица без колонок — не состояние
+интерфейса, а поломка: скрывать станет нечего, и пользователю из неё не
+выбраться. Запрет односторонний — скрытую колонку вернуть можно всегда.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/table/TableToolbar.tsx`,
+  `src/components/table/TablePreferences.tsx`.
+- Тесты: `tests/table-toolbar.test.tsx` (слоты, склонение счётчика, отсутствие
+  роли `toolbar`), `tests/table-preferences.test.tsx` (запрет на последнюю
+  колонку, порядок с клавиатуры, плотность).
+- Состояние: [`useTableState`](../../api/utilities.md).