@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/content/media-card.en.md

@@ -0,0 +1,137 @@
+---
+component: MediaCard
+exports: [MediaCard]
+category: content
+status: stable
+source: src/components/content/MediaCard.tsx
+story: src/components/content/MediaCard.stories.tsx
+sourceHash: 456beacc1187
+---
+
+# MediaCard
+
+## Summary for AI
+
+An image tile: a preview in a set aspect ratio, actions over it, badges and
+selection. Domain-specific behavior — favorites, duplicates, navigation — stays outside, in
+slots.
+
+## When to use
+
+- A grid or feed of previews: images, documents, covers.
+- You need to select tiles and act on the selection.
+- You need badges over the preview: a status, a mark, a duration.
+
+## When not to use
+
+- For a content block without a picture — that is `Card`. The boundary follows
+  what matters most: for a tile it is the preview, for a card — the content.
+- For a list row with a thumbnail — that is `UploadQueue` or a custom row: a
+  tile takes a column, not a row.
+- For a single image without actions — that is `Image` in `AspectRatio`.
+
+## Minimal example
+
+```tsx
+import { MediaCard, Image } from "@olddevs/ui";
+
+<MediaCard
+  preview={<Image src={url} alt="" className="h-full w-full" />}
+  ratio={16 / 9}
+  title="photo-0042.png"
+  selected={selected}
+  onSelectedChange={setSelected}
+/>;
+```
+
+## Props
+
+| Prop               | Default                  | Purpose                                                                                                                             |
+| ------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `preview`          | —                        | The preview. Usually `Image`.                                                                                                       |
+| `ratio`            | `1`                      | The aspect ratio as a number: `16 / 9`, `1`, `9 / 16`.                                                                              |
+| `title`            | —                        | The title under the preview.                                                                                                        |
+| `subtitle`         | —                        | The second line, already formatted.                                                                                                 |
+| `badges`           | —                        | Badges over the preview.                                                                                                            |
+| `actions`          | —                        | Actions over the preview.                                                                                                           |
+| `selected`         | —                        | The tile is selected.                                                                                                               |
+| `onSelectedChange` | —                        | Toggle the selection. Without it there is no selection axis. Not passed inside `VirtualGrid` — there the grid manages selection.    |
+| `selectLabel`      | from the message catalog | A custom label for the select button; the default (`mediaCard.select`) is "Select" without a provider, "Выбрать" with `locales/ru`. |
+
+## The selection axis is turned on explicitly
+
+Without `onSelectedChange` there is no selection button in the markup, without
+`selected` there is no border. A tile with every axis at once would add buttons
+and borders to the markup that do nothing: this is the kit's general rule for
+axes. `selected` alone, without a handler, only displays a selection that the
+grid controls: that is how the card is used in `VirtualGrid` (below).
+
+**Selection is announced as a state, not as a border.** `aria-pressed` tells a
+screen reader whether the tile is selected; the border is a signal for the eyes,
+and a person who cannot see it would not learn about the selection at all.
+
+The button label does **not repeat** the state: `aria-pressed` is already
+announced, and "Selected, deselect" would be announced twice.
+
+### Inside `VirtualGrid`, selection belongs to the grid
+
+`onSelectedChange` is **not passed** here: the card would get its own axis next to
+the grid's, and the two selections would drift apart.
+
+In the grid, the axis is turned on in the grid itself — with the `selectionMode`
+prop, see
+[VirtualGrid](virtual-grid.md#выбор--у-сетки-а-не-у-ячейки). The card gets
+`selected`: it renders the border and keeps the actions panel open, and the grid toggles the
+selection. The selection checkbox is `<Checkbox slot="selection" />` in `actions`: the
+grid wires it to its axis itself.
+
+```tsx
+<VirtualGrid selectionMode="multiple" selectedKeys={keys} onSelectionChange={setKeys}>
+  {/* cell content */}
+  <MediaCard
+    preview={preview}
+    title={name}
+    selected={keys.has(id)}
+    actions={<Checkbox slot="selection" label={`Select ${name}`} />}
+  />
+</VirtualGrid>
+```
+
+Before 3.47.0 the card rendered the border only with its own axis, and a selected tile in
+the grid had no visible indicator at all.
+
+Before 3.1.0 the documentation advised the opposite. The advice could not be
+followed — the analysis is in the [CHANGELOG](../../../CHANGELOG.md) and on the
+grid page.
+
+## Actions are reachable from the keyboard
+
+The actions panel is **always in the markup**; it is hidden only with opacity,
+and it appears on hover, when focus is inside it, when the tile is selected, and
+always on devices without hover (`hover: none`).
+
+A panel that is `display: none` and shown only on `:hover` is unreachable for the
+keyboard altogether: it cannot be used.
+
+## Domain-specific behavior stays outside
+
+The generalization was modeled on the source app's card, 212
+lines. Favorites, duplicates, long press and navigation on the tile
+did not make it into the kit: nodes come in here (`badges`, `actions`), and what
+they mean is known to the app
+(ADR-0027).
+
+The preview is built on the existing `Image` and `AspectRatio`: the tile implements
+no loading, fallback or skeleton of its own.
+
+## Anti-patterns
+
+- Marking selection with a border alone.
+- Hiding actions so that the keyboard cannot reach them.
+- Adding an `isFavorite` prop: that is the consumer's `badges` or `actions`.
+
+## Related sources and tests
+
+- Source: `src/components/content/MediaCard.tsx`
+- Tests: `tests/media-card.test.tsx`
+- Showcase: `src/components/content/MediaCard.stories.tsx`

package/docs/components/content/media-card.md

@@ -0,0 +1,132 @@
+---
+component: MediaCard
+exports: [MediaCard]
+category: content
+status: stable
+source: src/components/content/MediaCard.tsx
+story: src/components/content/MediaCard.stories.tsx
+---
+
+# MediaCard
+
+## Кратко для AI
+
+Плитка с изображением: превью в заданной пропорции, действия поверх него, бейджи
+и выбор. Доменное — избранное, дубликаты, переход — остаётся снаружи слотами.
+
+## Когда использовать
+
+- Сетка или лента превью: картинки, документы, обложки.
+- Нужно выбирать плитки и действовать над выбранным.
+- Нужны бейджи поверх превью: статус, пометка, длительность.
+
+## Когда не использовать
+
+- Для блока содержимого без картинки — это `Card`. Граница по главному: у
+  плитки главное превью, у карточки — содержимое.
+- Для строки списка с миниатюрой — это `UploadQueue` или своя строка: плитка
+  занимает столбец, а не строку.
+- Для одной картинки без действий — это `Image` в `AspectRatio`.
+
+## Минимальный пример
+
+```tsx
+import { MediaCard, Image } from "@olddevs/ui";
+
+<MediaCard
+  preview={<Image src={url} alt="" className="h-full w-full" />}
+  ratio={16 / 9}
+  title="photo-0042.png"
+  selected={selected}
+  onSelectedChange={setSelected}
+/>;
+```
+
+## Пропы
+
+| Проп               | Умолчание   | Назначение                                                                                                      |
+| ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------- |
+| `preview`          | —           | Превью. Обычно `Image`.                                                                                         |
+| `ratio`            | `1`         | Пропорция числом: `16 / 9`, `1`, `9 / 16`.                                                                      |
+| `title`            | —           | Название плитки под превью.                                                                                     |
+| `subtitle`         | —           | Вторая строка, уже отформатированная.                                                                           |
+| `badges`           | —           | Бейджи поверх превью.                                                                                           |
+| `actions`          | —           | Действия поверх превью.                                                                                         |
+| `selected`         | —           | Плитка выбрана.                                                                                                 |
+| `onSelectedChange` | —           | Переключить выбор. Без него оси выбора нет. Внутри `VirtualGrid` не передаётся — там выбор у сетки.             |
+| `selectLabel`      | из каталога | Своя подпись кнопки выбора; умолчание (`mediaCard.select`) — «Выбрать» в `locales/ru`, «Select» без провайдера. |
+
+## Ось выбора включается явно
+
+Без `onSelectedChange` кнопки выбора в разметке нет, без `selected` — рамки.
+Плитка со всеми осями сразу добавляла бы в разметку кнопки и рамки, которые
+ничего не делают: это общее правило осей кита. Один `selected` без обработчика
+только показывает выбор, которым управляет сетка: так карточка используется в
+`VirtualGrid` (ниже).
+
+**Выбор объявляется состоянием, а не рамкой.** `aria-pressed` говорит
+скринридеру, выбрана плитка или нет; рамка — сигнал для глаз, и человек, который
+её не видит, иначе о выборе не узнает вовсе.
+
+Подпись кнопки состояние **не повторяет**: `aria-pressed` уже объявлен, и
+«Выбрано, снять выбор» прозвучало бы дважды.
+
+### Внутри `VirtualGrid` выбор принадлежит сетке
+
+`onSelectedChange` здесь **не передаётся**: у карточки была бы своя ось рядом
+с осью сетки, и два выбора разошлись бы.
+
+В сетке ось включается у неё самой — пропом `selectionMode`, см.
+[VirtualGrid](virtual-grid.md#выбор--у-сетки-а-не-у-ячейки). Карточке передают
+`selected`: она рисует рамку и держит панель действий открытой, а переключает выбор
+сетка. Флажок выбора — `<Checkbox slot="selection" />` в `actions`: сетка
+связывает его со своей осью сама.
+
+```tsx
+<VirtualGrid selectionMode="multiple" selectedKeys={keys} onSelectionChange={setKeys}>
+  {/* content ячейки */}
+  <MediaCard
+    preview={preview}
+    title={name}
+    selected={keys.has(id)}
+    actions={<Checkbox slot="selection" label={`Выбрать ${name}`} />}
+  />
+</VirtualGrid>
+```
+
+До 3.47.0 рамку карточка рисовала только при своей оси, и выбранная плитка в
+сетке оставалась без знака.
+
+До 3.1.0 документация советовала обратное. Совет был неисполним — разбор в
+[CHANGELOG](../../../CHANGELOG.md) и на странице сетки.
+
+## Действия достижимы с клавиатуры
+
+Панель действий **всегда в разметке**; прячется она только прозрачностью, а показывается
+при наведении, при фокусе внутри, когда плитка выбрана и всегда на устройствах
+без наведения (`hover: none`).
+
+Панель на `display: none` под `:hover` для клавиатуры недостижима вовсе:
+пользоваться ею нельзя.
+
+## Доменное остаётся снаружи
+
+Обобщали по образцу карточки приложения-источника, 212
+строк. Избранное, дубликаты, длинное нажатие и переход по плитке в кит не вошли:
+сюда приходят узлы (`badges`, `actions`), а что они значат, знает приложение
+(ADR-0027).
+
+Превью стоит на существующих `Image` и `AspectRatio`: своей загрузки, своего
+фолбэка и своего скелетона плитка не пишет.
+
+## Антипаттерны
+
+- Отмечать выбор только рамкой.
+- Прятать действия так, чтобы до них нельзя было дотянуться с клавиатуры.
+- Заводить проп `isFavorite`: это `badges` или `actions` потребителя.
+
+## Связанные исходники и проверка
+
+- Исходник: `src/components/content/MediaCard.tsx`
+- Тесты: `tests/media-card.test.tsx`
+- Витрина: `src/components/content/MediaCard.stories.tsx`

package/docs/components/content/notifications.en.md

@@ -0,0 +1,216 @@
+---
+component: Notifications
+exports: [NotificationItem, NotificationList, NotificationGroup, NotificationCenter]
+category: content
+status: stable
+source: src/components/content/NotificationList.tsx
+story: src/components/content/NotificationList.stories.tsx
+sourceHash: 56acbfce3b46
+---
+
+# NotificationItem, NotificationList and NotificationCenter
+
+## Summary for AI
+
+A list of events: what happened, when, and whether it has been read. The kit
+knows no event types — the icon, tone and text come in as props. Groups
+("Today", "Earlier") come already assembled.
+
+## When to use
+
+- A notification feed in a popover, a drawer (`Drawer`) or on a separate page.
+- You need to tell read from unread and to mark items as read.
+
+## When not to use
+
+- For a temporary message about an event — that is `toast`: it pops up and goes
+  away.
+- For a persistent page state — that is `Alert`, for an app state — `Banner`.
+- For the steps of one process — that is `Timeline`: there the process sets the
+  order, not time, and a step has no actions.
+
+## Minimal example
+
+```tsx
+import { NotificationList, NotificationItem } from "@olddevs/ui";
+
+<NotificationList
+  groups={[
+    {
+      id: "today",
+      label: "Today",
+      children: <NotificationItem title="Publication failed" unread time="5 minutes ago" />,
+    },
+  ]}
+  empty={<EmptyState title="All quiet for now" />}
+/>;
+```
+
+## Props
+
+`NotificationItem`: `title`, `description`, `time`, `icon`, `media`, `tone`,
+`unread` and **one of** `actions` / `onAction`.
+
+`NotificationList`: `groups` **or** `children`, `empty`, `aria-label`.
+
+`NotificationCenter`: `title`, `level`, `titleId`, `unreadCount`,
+`filters`, `actions`, `selectedCount`, `onClearSelection`, `selectionActions`,
+`footer`, `children`.
+
+## Preview and icon — two independent slots
+
+`icon` says **what** happened (the event type, the tone), `media` — **to what**
+(a preview of the object the event is about). The row shows both: the icon on
+the left, the preview next, then the text. The element itself sets the preview
+size (`Image` at 36px, `Avatar`); the slot only keeps it from shrinking. If the
+title already names the object, the preview is decorative and gets `alt=""`.
+
+```tsx
+<NotificationItem
+  title="Moderation finished"
+  icon={<InfoIcon size={16} />}
+  media={<Image src={item.previewUrl} alt="" className="size-9 rounded-md" />}
+/>
+```
+
+## The whole row is one button (`onAction`)
+
+`onAction` turns the row into **one button that covers the whole row**: a click, Enter
+and Space call the handler. The row is still the list's `<li>`; the button sits
+inside it. The unread background stays on the `li`, while the hover and the focus
+ring are on the button; the ring is rendered inside the row because the center's
+scrolling would clip it on the outside.
+
+- **The button name is the title** and the word "Unread" (`aria-labelledby` on
+  both nodes), not the whole text: with the full content the name would run to
+  half a page. **The time and details are the button description**
+  (`aria-describedby`), so they are not lost.
+- There are no nested interactive elements inside the button, and the row blocks
+  are `span` elements: a `button` allows only phrasing content.
+- **The row padding and layout sit on the button**, while `className` goes to
+  the `<li>`: the background and border change through it, `px-*`, `py-*` and
+  `gap-*` do not. Without `onAction` they sit on the `li` itself.
+- **Only the title, the word "Unread", the time and the details go into the name
+  and description.** The preview `alt` and the icon text are not included: write
+  what matters about the object ("photo of Anna K.") in the title, and keep the
+  preview decorative.
+- **`onAction` is a button, not a link.** If a click navigates to a URL and you
+  need to open it in a new tab or with the middle mouse button, wrap the row in a
+  link or navigate through `actions` with a link; a button with `router.push`
+  does not support these.
+- On hover, an unread row darkens the accent background, a read one fills with a
+  neutral color.
+- A row without `onAction` contains no button — the markup is as before, with no
+  extra `id` attributes.
+
+```tsx
+<NotificationItem title="Publication failed" unread onAction={() => markRead(id)} />
+```
+
+**It does not combine with `actions`**, and the type says so: buttons inside a
+button are invalid markup. If you need both a click on the row and separate
+actions, pick one: an action on the whole row or buttons on the right.
+
+A consumer on JS could pass both props: the types do not stop them. The kit
+does not crash the page: **`actions` wins, `onAction` is ignored.** Of the two
+losses the smaller is chosen: `actions` may be the only path to an action
+("delete", "open"), while a click on the whole row is a convenience. The failure
+is visible at once: the row does not respond to a click. In development mode the
+console also reports it: a `console.warn` with English text once per module load:
+what was passed, what won and how to fix it. In a production build the kit is
+silent. The rules for such warnings are in
+[conventions.md](../../conventions.md#предупреждения-в-режиме-разработки).
+
+## Center title: level and `id`
+
+By default the `NotificationCenter` title is plain text (a `span`): it is not
+part of the page's heading structure. `level` (`2`, `3` or `4`; the name is the
+same as on `SectionHeader`) makes it a real `<h2>`–`<h4>`: the level depends on
+where the center is placed, and the consumer knows that. `titleId` sets an `id`
+on the title element so that the popover's or drawer's `aria-labelledby` can
+point to it:
+
+```tsx
+<PopoverContent aria-labelledby="bell-title">
+  <NotificationCenter level={2} titleId="bell-title" unreadCount={12}>
+    …
+  </NotificationCenter>
+</PopoverContent>
+```
+
+`titleId` works without `level` too (the `id` lands on the `span`): the container
+name comes from the title, and the center does not touch the page structure.
+With neither prop, the markup and behavior are as before.
+
+## The center has no container
+
+`NotificationCenter` is not a popover, a drawer or a page: it is their
+**content**. The consumer places it inside an existing `Popover` or `Drawer`, or
+straight on a page, and the center neither opens nor closes itself — the
+container state lives outside.
+
+Otherwise the kit would have to pick one container for all apps at once, while in
+an admin panel the feed is more often a page, and in a client app more often a
+popover.
+
+Bulk actions are the existing `SelectionBar`, not a bar of its own: it already
+carries a counter, selection clearing, two action slots and the rule "at zero
+there is no bar at all". Stickiness is off here: in a popover there is nothing
+to stick to.
+
+**The unread counter comes as a prop**, and is not computed from the rows: a
+list can be a page of a collection, and "3" instead of "300" is a lie.
+Visually, `Badge` truncates a large number to "99+", but the name for a
+screen reader stays exact.
+
+## Unread is heard, not only seen
+
+The dot and the background are a signal for the eyes. Next to the title of an
+unread event there is a word from the message catalog: without it, a person who
+cannot see color would not tell a new event from an old one at all. The dot
+itself is `aria-hidden` — otherwise a screen reader would announce a nameless
+node next to the word.
+
+## Groups come ready-made
+
+The consumer's locale and time zone decide what "yesterday" is: an app with night
+shifts has its own day boundary, and computing it in the kit would impose
+the kit's calendar on the app.
+
+A group is announced as a **labeled group** (`role="group"`), not as a heading.
+The heading level (`h2`, `h3`) depends on where the list is placed (in a
+popover, a drawer or on a page), and the kit does not know that. A group conveys
+structure without taking up a level.
+
+## The row decides nothing on its own
+
+It neither navigates nor marks itself as read: both navigating and marking as read
+are app actions. The app passes them in `actions` or `onAction` (the whole row is a
+button), or wraps the row from the outside.
+
+The time comes **already formatted**: "5 minutes ago" and "yesterday at 2:03 PM"
+are put together by the app with `Intl.RelativeTimeFormat` and the consumer's time zone.
+
+## Anti-patterns
+
+- Adding `type: "publication_failed"` instead of `icon` and `tone`: domain event
+  types do not move into the kit.
+- Marking unread by color alone.
+- Computing grouping inside the component.
+- Computing the unread counter from the visible rows.
+- Wrapping the center in your own popover inside the kit: the consumer chooses
+  the container.
+- Passing `onAction` together with `actions`: the types forbid it, and on JS
+  `actions` wins (and in development the console warns).
+- Putting interactive elements into `media` or `title` of a button row: they end
+  up inside the button.
+- Giving the popover an `aria-label` next to a real title instead of `titleId`:
+  the name drifts from the visible title when it is edited.
+
+## Related sources and tests
+
+- Source: `src/components/content/NotificationList.tsx`
+- Tests: `tests/notification-list.test.tsx`
+- Showcase: `src/components/content/NotificationList.stories.tsx`, `src/components/content/NotificationCenter.stories.tsx`
+- Center tests: `tests/notification-center.test.tsx`
+- Decision: ADR-0027