orionplace-react 0.1.0 → 0.2.1

package/templates/components/orionplace/blog/BlogComments.README.md

@@ -0,0 +1,98 @@
+# BlogComments
+
+## English
+
+`BlogComments` renders one article's discussion from `roots`, `replies` and
+`localComments`. It orders each reply directly after its parent and limits the
+visual indent. A deeper reply names the author it answers. `replyPages` adds a
+More action after a loaded subtree when another reply page exists.
+
+On mount and after an authentication change, `onLoad` receives the public root
+request for `postId`. Discussion loads root comments newest first; reply pages
+load oldest first. Signed-in customers can switch to their unnested Mine list.
+Pagination changes the root-comment page and keeps the selected mode.
+
+Reply is available for published comments. Edit appears when the comment's
+`can_edit` is true and Delete when `can_remove` is true; the backend sets these
+flags only for the author, with the rules it applies to the requests (edit: no
+approved replies; delete: no replies in any status). The reader's own comment
+(`is_owner`) has the muted background of their own support messages, and
+screen readers hear «Your comment» after the name. Deletion requires
+confirmation. `onSubmit` receives the
+exact add or edit request and closes the form only when it returns a confirmed
+comment. A failed submit or deletion should reject and pass the server message
+through `error`; the draft is preserved. The component shows a failed send's
+error in the form and a failed deletion's inside that comment; only a failed
+load uses the notice above the list. Confirming a deletion closes the
+confirmation, and a successful deletion reloads the current page. Guests call
+`onRequireSignIn` from Write a comment or Reply so the host can preserve the
+article as the return destination.
+
+### Props
+
+| Prop                                                                                                    | Meaning                                                                                                |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `postId: number`                                                                                        | ID of the post handled by BlogComments.                                                                |
+| `roots?: readonly IBlogComment[]`                                                                       | Top-level comments before nested replies are attached.                                                 |
+| `replies?: Readonly<Record<number, readonly IBlogComment[]>>`                                           | Replies grouped under their owning record.                                                             |
+| `localComments?: readonly IBlogComment[]`                                                               | Own confirmed comments that await moderation and are missing from the public list.                     |
+| `replyPages?: Readonly<Record<number, BlogReplyPage>>`                                                  | Loaded reply pages keyed by the parent comment ID.                                                     |
+| `pagination?: Partial<IApiPagination>`                                                                  | Current API pagination values.                                                                         |
+| `loaded?: boolean`                                                                                      | Distinguishes a confirmed empty result from data that has not loaded yet.                              |
+| `pending?: boolean`                                                                                     | Shows the loading state and blocks duplicate actions.                                                  |
+| `error?: string`                                                                                        | Customer-visible error for the component request; omit it when no request failed.                      |
+| `onLoad?: (action: BlogCommentsLoadAction) => Promise<void> \| void`                                    | Called when the component needs its primary data. The callback payload is shown in its type.           |
+| `onSubmit?: (action: BlogCommentSubmitAction) => Promise<IBlogComment \| void> \| IBlogComment \| void` | Called when the visitor submits the confirmed form values. The callback payload is shown in its type.  |
+| `onSaved?: (comment: IBlogComment, action: BlogCommentSubmitAction) => void`                            | Called when the current record has been saved successfully. The callback payload is shown in its type. |
+| `onDelete?: (action: BlogCommentDeleteAction) => Promise<void> \| void`                                 | Called when the visitor requests deletion. The callback payload is shown in its type.                  |
+| `onDeleted?: (comment: IBlogComment) => void`                                                           | Called when deletion has completed successfully. The callback payload is shown in its type.            |
+| `onRequireSignIn?: (postId: number) => void`                                                            | Called when the visitor must sign in before continuing. The callback payload is shown in its type.     |
+
+## Русский
+
+`BlogComments` выводит обсуждение одной статьи из `roots`, `replies` и
+`localComments`. Каждый ответ располагается сразу после родительского
+комментария, а визуальный отступ ограничен. Более глубокий ответ дополнительно
+называет автора, которому он адресован. Если в `replyPages` указана следующая
+страница ответов, после загруженной ветки появляется действие «Ещё».
+
+После монтирования и смены авторизации `onLoad` получает запрос корневых
+комментариев для `postId`. Корневые комментарии запрашиваются от новых к старым,
+а ответы — от старых к новым. Вошедший покупатель может открыть отдельный список
+«Мои» без вложенности. Пагинация меняет страницу корневых комментариев и
+сохраняет выбранный режим.
+
+Ответ доступен для опубликованного комментария. «Изменить» показывается, когда
+у комментария `can_edit` равно true, а «Удалить» — когда `can_remove` равно
+true; бэкенд выставляет эти флаги только автору и по тем же правилам, что
+проверяет в запросах (изменение: нет одобренных ответов; удаление: нет ответов
+ни в каком статусе). Свой комментарий читателя (`is_owner`) выделен приглушённым
+фоном, как его сообщения в поддержке, а экранный диктор после имени произносит
+«Ваш комментарий». Удаление требует подтверждения. `onSubmit` получает точный запрос добавления или изменения и
+закрывает форму только после возврата подтверждённого комментария. Неудачные
+отправка или удаление должны отклонять промис и передавать сообщение сервера в
+`error`; черновик сохраняется. Ошибку отправки компонент показывает в форме, ошибку
+удаления — внутри этого комментария; над списком остаётся только ошибка загрузки. Подтверждение удаления закрывается сразу, а после
+успешного удаления текущая страница загружается снова. Для гостя действия
+написания и ответа вызывают `onRequireSignIn`, чтобы родитель сохранил статью
+для возврата после входа.
+
+### Свойства
+
+| Свойство                                                                                                | Назначение                                                                                                    |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `postId: number`                                                                                        | ID статьи, с которым работает BlogComments.                                                                   |
+| `roots?: readonly IBlogComment[]`                                                                       | Корневые комментарии до добавления вложенных ответов.                                                         |
+| `replies?: Readonly<Record<number, readonly IBlogComment[]>>`                                           | Ответы, сгруппированные под исходной записью.                                                                 |
+| `localComments?: readonly IBlogComment[]`                                                               | Свои подтверждённые комментарии на модерации, которых нет в публичном списке.                                 |
+| `replyPages?: Readonly<Record<number, BlogReplyPage>>`                                                  | Загруженные страницы ответов по ID родительского комментария.                                                 |
+| `pagination?: Partial<IApiPagination>`                                                                  | Текущие данные пагинации API.                                                                                 |
+| `loaded?: boolean`                                                                                      | Отличает подтверждённый пустой результат от ещё не загруженных данных.                                        |
+| `pending?: boolean`                                                                                     | Показывает загрузку и блокирует повторные действия.                                                           |
+| `error?: string`                                                                                        | Ошибка запроса для покупателя; не передавайте её, если запрос не завершился ошибкой.                          |
+| `onLoad?: (action: BlogCommentsLoadAction) => Promise<void> \| void`                                    | Вызывается, когда компоненту нужны основные данные. Данные обработчика указаны в его типе.                    |
+| `onSubmit?: (action: BlogCommentSubmitAction) => Promise<IBlogComment \| void> \| IBlogComment \| void` | Вызывается, когда покупатель отправляет подтверждённые значения формы. Данные обработчика указаны в его типе. |
+| `onSaved?: (comment: IBlogComment, action: BlogCommentSubmitAction) => void`                            | Вызывается, когда текущая запись успешно сохранена. Данные обработчика указаны в его типе.                    |
+| `onDelete?: (action: BlogCommentDeleteAction) => Promise<void> \| void`                                 | Вызывается, когда покупатель запрашивает удаление. Данные обработчика указаны в его типе.                     |
+| `onDeleted?: (comment: IBlogComment) => void`                                                           | Вызывается, когда удаление успешно завершено. Данные обработчика указаны в его типе.                          |
+| `onRequireSignIn?: (postId: number) => void`                                                            | Вызывается, когда покупателю нужно войти перед продолжением. Данные обработчика указаны в его типе.           |

package/templates/components/orionplace/blog/BlogComments.module.css

@@ -0,0 +1,151 @@
+/* The gaps of `op-feature-stack` (20px) and `op-feature-records` (12px)
+   in the other packages. */
+.section,
+.comment,
+.panel,
+.confirmation {
+  display: grid;
+  gap: 1.25rem;
+}
+
+.comments {
+  display: grid;
+  gap: 0.75rem;
+}
+
+.section {
+  color: var(--orionplace-text);
+  font-size: 0.875rem;
+  line-height: 1.5rem;
+  container: comments / inline-size;
+}
+
+.heading,
+.actions,
+.author {
+  display: flex;
+  align-items: center;
+}
+
+.heading {
+  flex-wrap: wrap;
+  justify-content: space-between;
+  gap: 0.75rem;
+}
+
+.heading h2,
+.panel p,
+.confirmation p {
+  margin: 0;
+}
+
+/* `op-feature-subtitle`. */
+.heading h2 {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.actions {
+  flex-wrap: wrap;
+  gap: 0.75rem;
+}
+
+/* The shared storefront button, as op-feature-button in Nuxt and Svelte:
+   uppercase 12px text, 44px tall, the accent for the chosen tab. */
+.button {
+  composes: button from '../shared/features.module.css';
+}
+
+.error {
+  composes: notice noticeError from '../account/account.module.css';
+}
+
+.comments {
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+.comment,
+.more {
+  margin-inline-start: var(--comment-indent-wide);
+}
+
+/* `op-feature-panel`. */
+.panel {
+  padding: 1.25rem;
+  background: var(--orionplace-surface);
+  border: 1px solid var(--orionplace-border);
+}
+
+.panel[data-blog-comment-own='true'] {
+  background: var(--orionplace-muted-surface);
+}
+
+/* A reply keeps the panel's border colour, only wider on the left. */
+.panel[data-reply='true'] {
+  padding-inline-start: 1rem;
+  border-inline-start-width: 2px;
+}
+
+.author {
+  min-width: 0;
+  gap: 0.75rem;
+}
+
+.author span:last-child,
+.text {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.time,
+.muted {
+  color: var(--orionplace-muted);
+  font-size: 0.75rem;
+  line-height: calc(1 / 0.75);
+}
+
+.text {
+  white-space: pre-wrap;
+}
+
+.write {
+  justify-self: start;
+}
+
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* Replies indent less until the comments are as wide as on a 640px screen
+   (592px in the /journal page), whatever the screen. */
+@container comments (max-width: 591px) {
+  .comment,
+  .more {
+    margin-inline-start: var(--comment-indent-narrow);
+  }
+}
+
+/* Read by screen readers only: marks the reader's own comment. */
+.hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}