@acorex/components 22.4.15 → 22.4.17

package/comment/README.md

@@ -1,3 +1,468 @@
-# @acorex/components/comment
+# Comment (`@acorex/components/comment`)
 
-Secondary entry point of `@acorex/components`. It can be used by importing from `@acorex/components/comment`.
+کامپوننت ترد کامنت برای Angular. داده را به‌صورت درخت (`AXCommentItem`) می‌گیرد، لایک/ریپلای/اکشن را مدیریت می‌کند، و ادیتور را در فوتر نگه می‌دارد.
+
+## نصب و import
+
+```ts
+import {
+  AXCommentModule,
+  AXCommentViewComponent,
+  AXCommentReplyComponent,
+  AXCommentItemTemplateDirective,
+  type AXCommentItem,
+  type AXCommentCallback,
+  type AXCommentActionEvent,
+  type AXCommentReplyEvent,
+} from '@acorex/components/comment';
+import { AXTextEditorModule } from '@acorex/components/text-editor';
+import { AXDialogService } from '@acorex/components/dialog';
+```
+
+Standalone:
+
+```ts
+imports: [AXCommentModule, AXTextEditorModule, FormsModule]
+```
+
+---
+
+## معماری
+
+| قطعه | سلکتور | نقش |
+| --- | --- | --- |
+| `AXCommentContainerComponent` | `ax-comment-container` | شِل با اسلات `ax-header` / `ax-footer` |
+| `AXCommentViewComponent` | `ax-comment-view` | درخت داده، lazy load، متدهای mutate |
+| `AXCommentItemComponent` | `ax-comment-item` | یک کامنت (لی‌آوت پیش‌فرض یا تمپلیت) |
+| `AXCommentReplyComponent` | `ax-comment-reply` | نوار «در حال پاسخ به» بالای ادیتور |
+| `AXCommentItemTemplateDirective` | `ng-template[axCommentItem]` | سفارشی‌سازی بدنه آیتم |
+
+بدون `datasource` می‌توان آیتم‌ها را به‌صورت declarative داخل `ax-comment-view` پروجکت کرد.
+
+---
+
+## مدل داده `AXCommentItem`
+
+```ts
+interface AXCommentItem {
+  id: string | number;
+  author: string;
+  avatar?: string;
+  initials?: string;
+  color?: AXStyleColorType;
+  date?: string;
+  edited?: boolean;          // برچسب «ویرایش‌شده» قبل از زمان
+  editedAt?: string;         // tooltip روی برچسب (اختیاری)
+  content?: string;          // HTML مجاز است؛ در UI پیش‌فرض با innerHTML رندر می‌شود
+  likes?: number;
+  liked?: boolean;
+  isYou?: boolean;           // کنار نام، badge «You»
+  repliesExpanded?: boolean;
+  replies?: AXCommentItem[]; // eager
+  replyCount?: number;       // برای lazy؛ اگر replies خالی باشد از این استفاده می‌شود
+  actions?: AXMenuItem[];    // منوی ... فقط در UI پیش‌فرض
+  data?: unknown;
+}
+```
+
+`actions` همان `AXMenuItem` است:
+
+```ts
+const actions: AXMenuItem[] = [
+  { name: 'edit', text: 'Edit', icon: 'ax-icon ax-icon-pen', break: true },
+  { name: 'delete', text: 'Delete', icon: 'ax-icon ax-icon-trash', color: 'danger' },
+];
+```
+
+---
+
+## ۱) استفاده پیش‌فرض (بدون تمپلیت)
+
+Like و Reply داخل خود آیتم کار می‌کنند. رویدادها اختیاری‌اند.
+
+```html
+<ax-comment-container>
+  <ax-comment-view
+    #commentsView
+    [datasource]="comments"
+    (onReply)="onReply($event)"
+    (onLikeChange)="onLikeChange($event)"
+    (onRepliesToggle)="onRepliesToggle($event)"
+    (onAction)="onAction($event)"
+  />
+
+  <ax-footer>
+    <ax-comment-reply [item]="replyingTo()" (onClose)="cancelReply()">
+      <ax-text-editor
+        #commentEditor
+        look="solid"
+        outputFormat="html"
+        [initialLine]="3"
+        [ngModel]="draft()"
+        (ngModelChange)="draft.set($event)"
+        [placeHolder]="replyingTo() ? 'Write your content...' : 'Write a comment...'"
+      >
+        <ax-footer>
+          <ax-button class="ax-sm" look="solid" color="primary" text="Send" (onClick)="send()" />
+        </ax-footer>
+        <ax-text-editor-toolbar>
+          <ax-text-editor-history />
+          <ax-text-editor-font-style />
+          <ax-text-editor-colors />
+          <ax-text-editor-list />
+          <ax-text-editor-alignment />
+          <ax-text-editor-media />
+        </ax-text-editor-toolbar>
+      </ax-text-editor>
+    </ax-comment-reply>
+  </ax-footer>
+</ax-comment-container>
+```
+
+```ts
+comments = signal<AXCommentItem[]>([
+  {
+    id: 1,
+    author: 'Heidi Thonig',
+    initials: 'H',
+    color: 'success',
+    date: '18 hours ago',
+    content: 'The new layout looks great!',
+    likes: 1,
+    liked: true,
+    repliesExpanded: true,
+    actions,
+    replies: [
+      {
+        id: 2,
+        author: 'You',
+        initials: 'Y',
+        isYou: true,
+        date: 'Just now',
+        content: 'Agreed.',
+        likes: 0,
+        actions,
+      },
+    ],
+  },
+]);
+```
+
+سه نقطه (`...`) فقط در لی‌آوت پیش‌فرض است، روی هاور همان کامنت ظاهر می‌شود، و از `item.actions` می‌آید.
+
+---
+
+## ۲) Lazy loading
+
+`datasource` می‌تواند تابع باشد:
+
+- بدون `id` → ریشه‌ها
+- با `id` → پاسخ‌های همان کامنت
+
+برای ریشه، `replies` را نفرستید و `replyCount` بگذارید. وقتی کاربر ترد را باز کند، view دوباره callback را با id والد صدا می‌زند.
+
+```ts
+readonly loadComments: AXCommentCallback = (id) => {
+  if (!id) {
+    return this.api.listRoots().then((rows) =>
+      rows.map((row) => ({
+        ...row,
+        replyCount: row.replyCount ?? 0,
+        // replies را حذف کنید تا lazy بماند
+      })),
+    );
+  }
+  return this.api.listReplies(id);
+};
+```
+
+```html
+<ax-comment-view [datasource]="loadComments" (onReply)="onReply($event)" />
+```
+
+اسکلتون تا لود ریشه نشان داده می‌شود. باز/بسته کردن پاسخ‌ها `(onRepliesToggle)` می‌دهد.
+
+برنامه می‌تواند از بیرون هم باز کند:
+
+```ts
+this.commentsView()?.setExpanded('1', true);
+```
+
+---
+
+## ۳) تمپلیت سفارشی
+
+بدنه آیتم عوض می‌شود؛ ردیف Like / Reply / تعداد پاسخ‌ها همان chrome پیش‌فرض می‌ماند. منوی `...` در تمپلیت سفارشی نشان داده نمی‌شود.
+
+```html
+<ax-comment-view [datasource]="comments()" (onReply)="onReply($event)" (onLikeChange)="onLike($event)">
+  <ng-template axCommentItem let-item let-level="level" let-reply="reply">
+    <div class="my-card" [class.is-reply]="level > 0">
+      <ax-avatar [color]="item.color" [size]="48" look="solid" shape="soft">
+        <ax-text>{{ item.initials }}</ax-text>
+      </ax-avatar>
+      <ax-title>{{ item.author }}</ax-title>
+      <ax-content>
+        <div [innerHTML]="item.content"></div>
+      </ax-content>
+    </div>
+  </ng-template>
+</ax-comment-view>
+```
+
+کانتکست تمپلیت (`AXCommentItemTemplateContext`):
+
+| فیلد | معنی |
+| --- | --- |
+| `$implicit` / `item` | خود `AXCommentItem` |
+| `level` | عمق (۰ = ریشه) |
+| `repliesExpanded` | باز بودن پاسخ‌ها |
+| `replyCount` | تعداد پاسخ |
+| `loading` | در حال لود lazy |
+| `liked` / `likes` | وضعیت لایک |
+| `toggleReplies()` | باز/بسته کردن |
+| `toggleLike()` | لایک |
+| `reply(event?)` | شروع ریپلای |
+
+---
+
+## ۴) Composer: ارسال، ریپلای، ویرایش
+
+`ax-comment-reply` ادیتور را پروجکت می‌کند. اگر `item` ست باشد نوار «Replying to [نام]» با excerpt متن‌ساده بالای ادیتور می‌آید. کلیک روی نوار به همان کامنت اسکرول و highlight می‌کند. X فقط target را می‌بندد؛ پیش‌نویس پاک نمی‌شود.
+
+### Reply
+
+```ts
+replyingTo = signal<AXCommentItem | null>(null);
+
+onReply(event: AXCommentReplyEvent) {
+  this.replyingTo.set(event.item);
+  setTimeout(() => this.editor()?.focus());
+}
+
+cancelReply() {
+  this.replyingTo.set(null); // draft باقی می‌ماند
+}
+```
+
+عوض کردن هدف ریپلای draft را نگه می‌دارد.
+
+### Send
+
+```ts
+send() {
+  const html = this.draft();
+  if (this.isEmpty(html)) return; // fail: draft و target می‌مانند
+
+  const item: AXCommentItem = {
+    id: crypto.randomUUID(),
+    author: 'You',
+    initials: 'Y',
+    isYou: true,
+    date: 'Just now',
+    content: html,
+    likes: 0,
+    actions,
+  };
+
+  const parent = this.replyingTo();
+  const view = this.commentsView();
+
+  if (parent) {
+    const parentId = String(parent.id);
+    if (view && !view.findItem(parentId)) return;
+    void view?.appendReply(parentId, item);
+    this.replyingTo.set(null);
+  } else {
+    view?.appendItem(item);
+  }
+
+  this.draft.set('');
+  this.editor()?.setContent('', false);
+}
+```
+
+`ax-text-editor` برای ارتفاع از `[initialLine]="3"` استفاده می‌کند. برای ست کردن محتوا و فوکوس:
+
+```ts
+this.editor()?.setContent(html, true);
+```
+
+### Edit / Delete (از منوی ...)
+
+```ts
+onAction(event: AXCommentActionEvent) {
+  if (event.action.name === 'edit') this.edit(event.item);
+  if (event.action.name === 'delete') void this.remove(event.item);
+}
+
+edit(item: AXCommentItem) {
+  this.replyingTo.set(null);
+  this.editing.set(item);
+  this.editor()?.setContent(item.content ?? '', true);
+}
+
+saveEdit() {
+  const html = this.draft();
+  const current = this.editing();
+  if (!current || this.isEmpty(html)) return;
+  const updated = this.commentsView()?.updateItem(String(current.id), { content: html, edited: true });
+  if (!updated) return;
+  this.editing.set(null);
+  this.draft.set('');
+}
+
+async remove(item: AXCommentItem) {
+  const { result } = await this.dialog.confirm(
+    'Delete comment',
+    'This comment will be permanently removed.',
+    'danger',
+  );
+  if (!result) return;
+  this.commentsView()?.removeItem(String(item.id));
+}
+```
+
+اگر datasource تابع lazy است، بعد از `appendItem` / `removeItem` / `updateItem` منبع خودتان (mock API / سیگنال) را هم همگام کنید تا reload بعدی درست باشد.
+
+---
+
+## ۵) APIی `ax-comment-view`
+
+### Inputs / model
+
+| نام | نوع | توضیح |
+| --- | --- | --- |
+| `datasource` | `AXCommentItem[] \| AXCommentCallback \| null` | آرایه یا callback تنبل |
+| `itemTemplate` | `TemplateRef<AXCommentItemTemplateContext>` | جایگزین `ng-template axCommentItem` |
+
+### Events
+
+| نام | payload | کی |
+| --- | --- | --- |
+| `onReply` | `AXCommentReplyEvent` | کلیک Reply |
+| `onLikeChange` | `AXCommentLikeChangeEvent` | تغییر لایک (view خودش liked/likes را آپدیت می‌کند) |
+| `onRepliesToggle` | `AXCommentRepliesToggleEvent` | باز/بسته شدن پاسخ‌ها |
+| `onAction` | `AXCommentActionEvent` | انتخاب آیتم منوی `...` — `event.action` از نوع `AXMenuItem` |
+
+### Methods
+
+| متد | کار |
+| --- | --- |
+| `reloadData()` | ریشه‌ها را دوباره از datasource می‌گیرد |
+| `appendItem(item)` | کامنت ریشه اضافه می‌کند |
+| `appendReply(parentId, item)` | پاسخ می‌گذارد؛ اگر لازم باشد اول lazy load می‌کند و والد را باز می‌کند |
+| `findItem(id)` | جستجو در درخت لودشده |
+| `updateItem(id, patch)` | پچ آیتم؛ `id` اصلی حفظ می‌شود |
+| `removeItem(id)` | حذف آیتم و پاسخ‌های تو در تو |
+| `setExpanded(id, expanded)` | باز/بسته + lazy load |
+
+```ts
+const view = viewChild('commentsView', { read: AXCommentViewComponent });
+```
+
+---
+
+## ۶) `ax-comment-reply`
+
+| | |
+| --- | --- |
+| `[item]` | `AXCommentItem \| null` — نوار فقط وقتی مقدار دارد دیده می‌شود |
+| `(onClose)` | کلیک X |
+| `(onTargetClick)` | کلیک روی نوار؛ خود کامپوننت هم اسکرول/highlight می‌کند |
+
+Excerpt HTML را strip می‌کند و متن ساده نشان می‌دهد.
+
+---
+
+## ۷) `ax-comment-container`
+
+اسلات‌ها: `ax-header`، محتوا، `ax-footer`.
+
+```ts
+scrollToReply(id: string): void
+```
+
+هر دو سلکتور را امتحان می‌کند: `ax-comment-item[id="…"]` و `comment-${id}`. view برای آیتم‌ها `id="comment-${id}"` می‌گذارد.
+
+---
+
+## ۸) حالت declarative (بدون datasource)
+
+```html
+<ax-comment-view>
+  <ax-comment-item [replyCount]="1" [(repliesExpanded)]="open">
+    <ax-avatar color="success" look="twotone" shape="rounded">
+      <ax-text>H</ax-text>
+    </ax-avatar>
+    <ax-title>Heidi Thonig</ax-title>
+    <ax-comment-date>18 hours ago</ax-comment-date>
+    <ax-content>Hello</ax-content>
+    <ax-comment-like [like]="true">1</ax-comment-like>
+    <ax-comment-reply-text (click)="onReply($event)" />
+
+    <ax-comment-item>
+      <ax-avatar color="primary" look="twotone" shape="rounded">
+        <ax-text>A</ax-text>
+      </ax-avatar>
+      <ax-title>Alex</ax-title>
+      <ax-content>Hi</ax-content>
+      <ax-comment-like [like]="false">0</ax-comment-like>
+      <ax-comment-reply-text />
+    </ax-comment-item>
+  </ax-comment-item>
+</ax-comment-view>
+```
+
+---
+
+## ۹) i18n
+
+کلیدها در `@acorex/core` (`comment.*`):
+
+| کلید | en-US |
+| --- | --- |
+| `comment.reply` | Reply |
+| `comment.replies` | Replies |
+| `comment.replying-to` | Replying to |
+| `comment.you` | You |
+| `comment.edited` | Edited |
+| `comment.view` | View |
+| `comment.hide` | Hide |
+
+---
+
+## ۱۰) توکن‌های CSS
+
+روی `ax-comment-container`:
+
+| توکن | پیش‌فرض |
+| --- | --- |
+| `--ax-comp-comment-padding-y` | `8px` |
+| `--ax-comp-comment-gap` | `8px` |
+| `--ax-comp-comment-avatar-size` | `32px` |
+| `--ax-comp-comment-reply-avatar-size` | `28px` |
+
+لی‌آوت پیش‌فرض آیتم avatar را `48px` می‌گذارد. فاصله داخلی آیتم از `--ax-comp-comment-gap` (پیش‌فرض `0.5rem` روی خود آیتم) است.
+
+نوار ریپلای:
+
+| توکن | نقش |
+| --- | --- |
+| `--ax-comp-comment-reply-bar-bg-color` | پس‌زمینه |
+| `--ax-comp-comment-reply-bar-border-color` | حاشیه |
+| `--ax-comp-comment-reply-bar-accent-color` | نوار تأکیدی اینلاین‌استارت |
+| `--ax-comp-comment-reply-bar-radius` | `6px` |
+| `--ax-comp-comment-reply-bar-gap` | فاصله تا ادیتور (`8px`) |
+
+Highlight اسکرول: کلاس `ax-state-highlight` روی `ax-comment-item`.
+
+---
+
+## نکات
+
+- `content` می‌تواند HTML باشد (`<ul>`، mention و …). نوار ریپلای آن را به متن ساده تبدیل می‌کند.
+- منوی `...` فقط UI پیش‌فرض است، نه تمپلیت سفارشی.
+- روی دستگاه‌های touch، سه نقطه همیشه دیده می‌شود.
+- `appendReply` / `updateItem` / `removeItem` درخت **لودشده** را عوض می‌کنند؛ منبع lazy را خودتان هم به‌روز کنید.
+- ارتفاع ادیتور: `[initialLine]="n"` روی `ax-text-editor`.