@ilamanownuk/blog-kit 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,146 +1,501 @@
1
1
  # @ilamanownuk/blog-kit
2
2
 
3
- ویرایشگر متن غنی Tiptap برای بلاگ (Next.js / NestJS) — درج ویدیو از **آپارات و یوتیوب**، آپلود تصویر، انتخاب از **کتابخانه‌ی رسانه**، و sanitizer سمت سرور.
4
- Reusable Tiptap blog editor with Aparat/YouTube embeds, image upload, a media-library picker, a server sanitizer and a renderer. RTL and Persian by default; no Tailwind required.
5
-
6
- ## Install / نصب
3
+ ویرایشگر متن غنی (مبتنی بر Tiptap) برای بلاگ و مجله‌ی آنلاین، با پشتیبانی کامل از فارسی و راست‌به‌چین. این پکیج همه‌ی کارهای لازم برای یک بلاگ را در یک بسته می‌دهد: ادیتور، آپلود عکس، کتابخانه‌ی رسانه، درج ویدیوی آپارات و یوتیوب، پاک‌سازی امن HTML در سرور، و کامپوننت نمایش پست.
4
+
5
+ > اگر می‌خواهید یک هوش مصنوعی (Claude، Cursor، Copilot و...) پکیج را برایتان نصب کند، فایل [`AI_INSTALL_PROMPT.md`](./AI_INSTALL_PROMPT.md) را باز کنید و متنش را به آن بدهید.
6
+
7
+ ## فهرست
8
+
9
+ - [امکانات](#امکانات)
10
+ - [نصب](#نصب)
11
+ - [افزودن استایل](#افزودن-استایل)
12
+ - [استفاده‌ی سریع (ادیتور)](#استفادهی-سریع-ادیتور)
13
+ - [ذخیره در سرور (Server Action و Prisma)](#ذخیره-در-سرور-server-action-و-prisma)
14
+ - [استفاده با NestJS](#استفاده-با-nestjs)
15
+ - [نمایش پست با RichContent](#نمایش-پست-با-richcontent)
16
+ - [آپلود عکس](#آپلود-عکس)
17
+ - [کتابخانه‌ی رسانه](#کتابخانهی-رسانه)
18
+ - [ویدیوی آپارات و یوتیوب](#ویدیوی-آپارات-و-یوتیوب)
19
+ - [شخصی‌سازی ظاهر](#شخصیسازی-ظاهر)
20
+ - [تغییر متن‌ها (labels)](#تغییر-متنها-labels)
21
+ - [سئو](#سئو)
22
+ - [جدول کامل props](#جدول-کامل-props)
23
+ - [به‌روزرسانی پکیج](#بهروزرسانی-پکیج)
24
+ - [عیب‌یابی](#عیبیابی)
25
+ - [English summary](#english-summary)
26
+
27
+ ## امکانات
28
+
29
+ - ادیتور Tiptap با نوار ابزار آماده: پررنگ، مورب، زیرخط، تیتر، تراز، لیست، نقل‌قول، کد، لینک، جدول، رنگ متن و هایلایت.
30
+ - راست‌به‌چین و فارسی به‌صورت پیش‌فرض (قابل تغییر به چپ‌به‌راست).
31
+ - آپلود تصویر و انتخاب از کتابخانه‌ی رسانه (با آداپتور؛ هر بک‌اندی را می‌شود وصل کرد).
32
+ - درج ویدیو از آپارات و یوتیوب (یوتیوب به `youtube-nocookie.com` تبدیل می‌شود).
33
+ - پاک‌سازی HTML در سرور با لیست مجاز (allowlist) و جلوگیری از XSS.
34
+ - کامپوننت `RichContent` برای نمایش پست، سازگار با Server Components.
35
+ - بدون نیاز به Tailwind؛ ظاهر با متغیرهای CSS با پیشوند `--bk-` کاملاً قابل تنظیم است، با تم تیره‌ی آماده.
36
+ - خروجی ادیتور یک رشته‌ی HTML ساده است؛ در هر دیتابیسی (مثلاً یک ستون `Text`) ذخیره می‌شود.
37
+
38
+ ## نصب
7
39
 
8
40
  ```bash
9
41
  pnpm add @ilamanownuk/blog-kit
42
+ # یا: npm i @ilamanownuk/blog-kit | yarn add @ilamanownuk/blog-kit
10
43
  ```
11
44
 
12
- Peer deps: `react` and `react-dom` >= 19.
45
+ پیش‌نیازها: `react` و `react-dom` نسخه‌ی ۱۹ یا بالاتر (peer dependency). Tiptap، آیکن‌ها و sanitizer خودشان همراه پکیج نصب می‌شوند؛ **Tiptap را جداگانه نصب نکنید** تا نسخه‌ها دوتا نشوند.
46
+
47
+ پکیج چهار ورودی دارد:
13
48
 
14
- | Entry | Use |
49
+ | ورودی | کاربرد |
15
50
  | --- | --- |
16
- | `@ilamanownuk/blog-kit` | `RichTextEditor` (client component, ships `"use client"`) |
17
- | `@ilamanownuk/blog-kit/renderer` | `RichContent` (works in Server Components) |
18
- | `@ilamanownuk/blog-kit/server` | `sanitizeRichText`, `hasRichContent`, `richTextToPlain` (no React) |
19
- | `@ilamanownuk/blog-kit/styles.css` | Styles (CSS variables `--bk-*`, logical properties for RTL) |
51
+ | `@ilamanownuk/blog-kit` | کامپوننت `RichTextEditor` (کلاینتی؛ خودش `"use client"` دارد) |
52
+ | `@ilamanownuk/blog-kit/renderer` | کامپوننت `RichContent` برای نمایش (در Server Component هم کار می‌کند) |
53
+ | `@ilamanownuk/blog-kit/server` | `sanitizeRichText`، `hasRichContent`، `richTextToPlain` (بدون React) |
54
+ | `@ilamanownuk/blog-kit/styles.css` | استایل‌ها |
20
55
 
21
- Import the CSS once (e.g. in `app/layout.tsx`):
56
+ ## افزودن استایل
22
57
 
23
- ```ts
58
+ فایل استایل را فقط یک بار در لایه‌ی اصلی پروژه وارد کنید. در Next.js (App Router) در `app/layout.tsx`:
59
+
60
+ ```tsx
24
61
  import "@ilamanownuk/blog-kit/styles.css";
25
62
  ```
26
63
 
27
- ## Editor
64
+ یا در فایل CSS اصلی (مثلاً با Tailwind v4 در `globals.css`):
65
+
66
+ ```css
67
+ @import "tailwindcss";
68
+ @import "@ilamanownuk/blog-kit/styles.css";
69
+ ```
70
+
71
+ با همین یک خط، ظاهر پیش‌فرض بدون هیچ تنظیم دیگری درست نمایش داده می‌شود (حتی کنار Tailwind). برای تغییر ظاهر، بخش [شخصی‌سازی ظاهر](#شخصیسازی-ظاهر).
72
+
73
+ ## استفاده‌ی سریع (ادیتور)
74
+
75
+ ادیتور یک کامپوننت کنترل‌شده است: `value` و `onChange` با رشته‌ی HTML.
28
76
 
29
77
  ```tsx
30
78
  "use client";
79
+
80
+ import { useState } from "react";
31
81
  import { RichTextEditor } from "@ilamanownuk/blog-kit";
32
- import { uploadPostImage } from "./actions";
33
82
 
34
83
  export function PostForm() {
35
84
  const [html, setHtml] = useState("");
36
- return <RichTextEditor value={html} onChange={setHtml} uploadImage={uploadPostImage} />;
85
+
86
+ return (
87
+ <RichTextEditor
88
+ value={html}
89
+ onChange={setHtml}
90
+ placeholder="متن مقاله را بنویسید…"
91
+ />
92
+ );
93
+ }
94
+ ```
95
+
96
+ نکته‌ها:
97
+
98
+ - اگر ادیتور خالی باشد `onChange` مقدار `""` می‌فرستد (نه `<p></p>`).
99
+ - با عوض شدن `value` از بیرون (مثلاً بارگذاری پست دیگر) محتوای ادیتور هم به‌روز می‌شود.
100
+ - افزونه‌های ادیتور فقط یک بار هنگام mount ساخته می‌شوند؛ پس `allowedEmbeds` و `placeholder` را ثابت نگه دارید.
101
+ - ادیتور باید داخل کامپوننت کلاینتی (`"use client"`) استفاده شود.
102
+
103
+ ## ذخیره در سرور (Server Action و Prisma)
104
+
105
+ HTML ادیتور ورودی غیرقابل‌اعتماد است. **همیشه** آن را هنگام ذخیره در سرور پاک‌سازی کنید (و هنگام نمایش دوباره، که `RichContent` خودش انجام می‌دهد). پاک‌سازی فقط در مرورگر کافی نیست.
106
+
107
+ نمونه‌ی مدل Prisma:
108
+
109
+ ```prisma
110
+ model Post {
111
+ id String @id @default(cuid())
112
+ title String
113
+ slug String @unique
114
+ excerpt String?
115
+ body String @db.Text // HTML پاک‌سازی‌شده
116
+ createdAt DateTime @default(now())
117
+ }
118
+ ```
119
+
120
+ نمونه‌ی Server Action:
121
+
122
+ ```ts
123
+ // app/admin/posts/actions.ts
124
+ "use server";
125
+
126
+ import { revalidatePath } from "next/cache";
127
+ import { hasRichContent, richTextToPlain, sanitizeRichText } from "@ilamanownuk/blog-kit/server";
128
+ import { prisma } from "@/lib/prisma";
129
+
130
+ export async function createPost(input: { title: string; slug: string; body: string }) {
131
+ // اینجا احراز هویت و بررسی دسترسی را هم انجام دهید.
132
+ const body = sanitizeRichText(input.body, {
133
+ allowedEmbeds: ["aparat", "youtube"], // باید با ادیتور یکسان باشد
134
+ isAllowedImageSrc: (src) => src.startsWith("https://cdn.example.com/"), // اختیاری
135
+ });
136
+
137
+ if (!hasRichContent(body)) return { error: "متن مقاله خالی است." };
138
+
139
+ await prisma.post.create({
140
+ data: {
141
+ title: input.title,
142
+ slug: input.slug,
143
+ body,
144
+ excerpt: richTextToPlain(body).slice(0, 160),
145
+ },
146
+ });
147
+ revalidatePath("/blog");
148
+ return { ok: true };
149
+ }
150
+ ```
151
+
152
+ ## استفاده با NestJS
153
+
154
+ `/server` هیچ وابستگی به React ندارد و در سرویس Nest به‌سادگی کار می‌کند:
155
+
156
+ ```ts
157
+ import { BadRequestException, Injectable } from "@nestjs/common";
158
+ import { hasRichContent, richTextToPlain, sanitizeRichText } from "@ilamanownuk/blog-kit/server";
159
+
160
+ @Injectable()
161
+ export class PostsService {
162
+ constructor(private readonly prisma: PrismaService) {}
163
+
164
+ create(dto: CreatePostDto) {
165
+ const body = sanitizeRichText(dto.body);
166
+ if (!hasRichContent(body)) throw new BadRequestException("متن مقاله خالی است");
167
+
168
+ return this.prisma.post.create({
169
+ data: { ...dto, body, excerpt: richTextToPlain(body).slice(0, 160) },
170
+ });
171
+ }
172
+ }
173
+ ```
174
+
175
+ در این حالت ادیتور در فرانت‌اند (Next.js) است و HTML را از طریق API به Nest می‌فرستد. خروجی CommonJS هم موجود است.
176
+
177
+ ## نمایش پست با RichContent
178
+
179
+ ```tsx
180
+ // app/blog/[slug]/page.tsx (Server Component)
181
+ import { RichContent } from "@ilamanownuk/blog-kit/renderer";
182
+
183
+ export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
184
+ const { slug } = await params;
185
+ const post = await getPost(slug);
186
+
187
+ return (
188
+ <article>
189
+ <h1>{post.title}</h1>
190
+ <RichContent html={post.body} />
191
+ </article>
192
+ );
37
193
  }
38
194
  ```
39
195
 
40
- Props: `value`, `onChange(html)` (empty editor emits `""`), `placeholder`, `invalid`, `id`, `className`, `uploadImage`, `mediaApi`, `renderMediaPicker`, `resolveImageSrc`, `allowedEmbeds` (default `["aparat","youtube"]`), `labels`, `dir` (default `"rtl"`).
41
- Extensions are created once on mount, so `allowedEmbeds`/`placeholder` should be stable.
196
+ `RichContent` قبل از نمایش، HTML را دوباره پاک‌سازی می‌کند. هرگز HTML پست را با `dangerouslySetInnerHTML` مستقیم رندر نکنید.
42
197
 
43
- ### Image upload via a Next.js server action
198
+ Props: `html` (الزامی)، `className`، `dir` (پیش‌فرض `"rtl"`)، `lang` (پیش‌فرض `"fa"`)، `allowedEmbeds`، `isAllowedImageSrc`. دو گزینه‌ی آخر باید با تنظیمات ذخیره‌سازی یکی باشند.
44
199
 
45
- `uploadImage(file) => Promise<{ url: string; alt?: string }>`; throwing shows the error message in the dialog. Only `https://` image URLs are accepted.
200
+ ## آپلود عکس
201
+
202
+ اگر `uploadImage` بدهید، در پنجره‌ی درج تصویر دکمه‌ی «آپلود تصویر» ظاهر می‌شود. این تابع فایل را می‌گیرد و باید `{ url, alt? }` برگرداند. اگر خطا پرتاب کند، پیام آن داخل پنجره نمایش داده می‌شود. فقط آدرس‌های `https://` پذیرفته می‌شوند.
46
203
 
47
204
  ```ts
48
- // actions.ts
205
+ // app/admin/actions.ts
49
206
  "use server";
50
- export async function uploadPostImage(file: File) {
51
- const body = new FormData();
52
- body.append("file", file);
53
- const res = await fetch(`${process.env.API_URL}/media`, { method: "POST", body, headers: { authorization: `Bearer ${await getToken()}` } });
54
- if (!res.ok) throw new Error("آپلود ناموفق بود");
55
- const { url } = await res.json();
56
- return { url };
207
+
208
+ export async function uploadPostImage(formData: FormData) {
209
+ const file = formData.get("file") as File;
210
+ // فایل را در S3 / دیسک / هر جای دیگر ذخیره کنید
211
+ const url = await saveToStorage(file);
212
+ return { url }; // باید https باشد
57
213
  }
58
214
  ```
59
215
 
60
- ### Media library
216
+ ```tsx
217
+ <RichTextEditor
218
+ value={html}
219
+ onChange={setHtml}
220
+ uploadImage={async (file) => {
221
+ const formData = new FormData();
222
+ formData.set("file", file);
223
+ return uploadPostImage(formData);
224
+ }}
225
+ />
226
+ ```
61
227
 
62
- Built-in picker driven by a `mediaApi` (implement with server actions so tokens stay on the server):
228
+ با `resolveImageSrc` می‌توانید آدرس را قبل از درج تغییر دهید (مثلاً انتخاب نسخه‌ی ۹۶۰ پیکسلی):
229
+
230
+ ```tsx
231
+ resolveImageSrc={(url) => url.replace(/\.(\w+)$/, "-960.$1")}
232
+ ```
233
+
234
+ ## کتابخانه‌ی رسانه
235
+
236
+ برای انتخاب از تصاویر قبلی، `mediaApi` را بدهید. دو تابع دارد؛ بهتر است با Server Action پیاده شوند تا توکن‌ها در سرور بمانند:
63
237
 
64
238
  ```tsx
65
239
  <RichTextEditor
66
240
  value={html}
67
241
  onChange={setHtml}
68
242
  mediaApi={{
69
- list: ({ q, page }) => listMedia({ q, page }), // -> { items, total, page, pageSize, error? }
70
- upload: (formData) => uploadMedia(formData), // formData.get("file") -> { items, error? }
243
+ list: ({ q, page }) => listMedia({ q, page }), // → { items, total, page, pageSize, error? }
244
+ upload: (formData) => uploadMedia(formData), // formData.get("file") → { items, error? }
71
245
  }}
72
- resolveImageSrc={(url) => url.replace(/\.(\w+)$/, "-960.$1")} // optional
73
246
  />
74
247
  ```
75
248
 
76
- `MediaItem`: `{ id, url, originalName, mimeType, sizeBytes, width, height, alt, variants: { "320": {url,width,height} }, createdAt }`. Grid thumbnails use `variants["320"]` when present.
249
+ شکل هر آیتم (`MediaItem`):
250
+
251
+ ```ts
252
+ {
253
+ id: string; url: string; originalName: string; mimeType: string; sizeBytes: number;
254
+ width: number; height: number; alt: string | null;
255
+ variants: Record<string, { url: string; width: number; height: number }>; // کلید "320" برای بندانگشتی
256
+ createdAt: string;
257
+ }
258
+ ```
77
259
 
78
- Or bring your own picker (takes precedence over `mediaApi`):
260
+ اگر کتابخانه‌ی رسانه‌ی خودتان رابط کاربری دارد، با `renderMediaPicker` آن را جایگزین کنید (در اولویت بالاتر از `mediaApi` است):
79
261
 
80
262
  ```tsx
81
263
  <RichTextEditor
264
+ value={html}
265
+ onChange={setHtml}
82
266
  renderMediaPicker={({ onSelect, close }) => (
83
- <MyPicker onPick={(m) => onSelect({ url: m.url, alt: m.alt })} onCancel={close} />
267
+ <MyMediaPicker
268
+ onPick={(m) => onSelect({ url: m.url, alt: m.alt ?? undefined })}
269
+ onCancel={close}
270
+ />
84
271
  )}
85
- ...
86
272
  />
87
273
  ```
88
274
 
89
- ### Labels
275
+ ## ویدیوی آپارات و یوتیوب
90
276
 
91
- All strings are Persian; override any with `labels` (see `defaultLabels` export for keys):
277
+ کاربر لینک صفحه‌ی ویدیو را می‌چسباند (مثلاً `https://www.aparat.com/v/xxxx` یا لینک یوتیوب) و پکیج آن را به آدرس embed امن تبدیل می‌کند. به‌طور پیش‌فرض هر دو مجاز هستند. برای محدود کردن:
92
278
 
93
279
  ```tsx
94
- <RichTextEditor labels={{ bold: "Bold", imageTitle: "Insert image", videoError: "Aparat or YouTube links only." }} dir="ltr" ... />
280
+ // ادیتور
281
+ <RichTextEditor allowedEmbeds={["aparat"]} ... />
282
+
283
+ // سرور و نمایش، دقیقاً همان مقدار
284
+ sanitizeRichText(html, { allowedEmbeds: ["aparat"] });
285
+ <RichContent html={html} allowedEmbeds={["aparat"]} />
95
286
  ```
96
287
 
97
- ### Embeds
288
+ اگر مقدار در ادیتور و سرور فرق کند، `iframe` در سرور حذف می‌شود. بهتر است مقدار را در یک ثابت مشترک بگذارید:
98
289
 
99
- `allowedEmbeds={["aparat"]}` limits the toolbar, the editor parser **and** (when passed identically) the sanitizer. YouTube links are converted to `youtube-nocookie.com`.
290
+ ```ts
291
+ export const EMBEDS = ["aparat", "youtube"] as const;
292
+ ```
100
293
 
101
- ## Server: always sanitize
294
+ ## شخصی‌سازی ظاهر
102
295
 
103
- Editor HTML is untrusted input. Sanitize when saving and again when rendering.
296
+ ظاهر پیش‌فرض همین است که می‌بینید، ولی هر چیزی قابل تغییر است.
104
297
 
105
- ```ts
106
- // Next.js server action / NestJS service
107
- import { sanitizeRichText, hasRichContent, richTextToPlain } from "@ilamanownuk/blog-kit/server";
298
+ ### ۱. متغیرهای CSS
299
+
300
+ متغیرها را روی `:root` یا هر عنصر والد بازنویسی کنید:
108
301
 
109
- const clean = sanitizeRichText(dto.content, {
110
- allowedEmbeds: ["aparat", "youtube"], // must match the editor
111
- isAllowedImageSrc: (src) => src.startsWith("https://cdn.example.com/"), // optional, https is always required
112
- });
113
- if (!hasRichContent(clean)) throw new BadRequestException("Empty content");
114
- const description = richTextToPlain(clean).slice(0, 160);
302
+ ```css
303
+ :root {
304
+ --bk-accent: #2563eb; /* رنگ اصلی: لینک، دکمه‌ی اصلی، فوکوس */
305
+ --bk-radius: 0.75rem; /* گردی گوشه‌ها */
306
+ --bk-font: "Vazirmatn", sans-serif;
307
+ --bk-line-height: 2;
308
+ --bk-editor-min-height: 480px;
309
+ }
115
310
  ```
116
311
 
117
- NestJS example:
312
+ متغیرهای اصلی:
118
313
 
119
- ```ts
120
- @Injectable()
121
- export class PostsService {
122
- create(dto: CreatePostDto) {
123
- return this.prisma.post.create({ data: { ...dto, content: sanitizeRichText(dto.content) } });
124
- }
314
+ | گروه | متغیرها |
315
+ | --- | --- |
316
+ | رنگ | `--bk-accent`، `--bk-accent-contrast`، `--bk-fg`، `--bk-muted-fg`، `--bk-bg`، `--bk-surface`، `--bk-muted`، `--bk-border`، `--bk-danger`، `--bk-code-bg`، `--bk-code-fg`، `--bk-code-inline-bg`، `--bk-mark-bg`، `--bk-hr-color`، `--bk-table-border`، `--bk-table-head-bg`، `--bk-backdrop` |
317
+ | تایپوگرافی | `--bk-font`، `--bk-code-font`، `--bk-font-size`، `--bk-line-height`، `--bk-h2-size`، `--bk-h3-size`، `--bk-h4-size`، `--bk-heading-weight` |
318
+ | شکل و فاصله | `--bk-radius`، `--bk-media-radius`، `--bk-block-gap`، `--bk-editor-min-height`، `--bk-editor-padding`، `--bk-toolbar-padding`، `--bk-toolbar-gap`، `--bk-control-size`، `--bk-dialog-width`، `--bk-dialog-wide-width` |
319
+ | سایه و لایه | `--bk-popover-shadow`، `--bk-dialog-shadow`، `--bk-z-toolbar`، `--bk-z-popover` |
320
+ | اختیاری (پیش‌فرض ندارند) | `--bk-link`، `--bk-heading-color`، `--bk-quote-border`، `--bk-radius-sm`، `--bk-radius-lg`، `--bk-focus-ring` |
321
+
322
+ ### ۲. تم تیره
323
+
324
+ برای تم تیره‌ی آماده، روی `<html>` (یا `<body>`) صفت `data-bk-theme="dark"` را بگذارید. اگر پروژه‌تان کلاس `.dark` (مثل Tailwind و shadcn) دارد، همان هم کار می‌کند. مقدار `auto` از تنظیم سیستم کاربر پیروی می‌کند:
325
+
326
+ ```html
327
+ <html data-bk-theme="dark"> … </html>
328
+ <html data-bk-theme="auto"> … </html>
329
+ ```
330
+
331
+ پنجره‌های گفتگو (dialog) داخل `<body>` رندر می‌شوند؛ پس صفت تم را روی `html` یا `body` بگذارید، نه فقط روی یک wrapper.
332
+
333
+ برای هماهنگی با تم خودتان (مثلاً shadcn) کافی است متغیرها را به رنگ‌های آن وصل کنید:
334
+
335
+ ```css
336
+ :root {
337
+ --bk-fg: var(--foreground);
338
+ --bk-bg: var(--background);
339
+ --bk-border: var(--border);
340
+ --bk-muted: var(--muted);
341
+ --bk-accent: var(--primary);
342
+ --bk-accent-contrast: var(--primary-foreground);
125
343
  }
126
344
  ```
127
345
 
128
- ## Render
346
+ ### ۳. classNames
347
+
348
+ با prop به نام `classNames` به هر بخش ادیتور کلاس اضافه کنید (کلاس‌های Tailwind هم می‌شود):
129
349
 
130
350
  ```tsx
131
- import { RichContent } from "@ilamanownuk/blog-kit/renderer";
132
- <RichContent html={post.content} /> // sanitizes again, dir="rtl" lang="fa"
351
+ <RichTextEditor
352
+ value={html}
353
+ onChange={setHtml}
354
+ classNames={{
355
+ root: "shadow-sm",
356
+ toolbar: "bg-white/80 backdrop-blur",
357
+ button: "hover:bg-amber-50",
358
+ content: "min-h-[500px]",
359
+ dialog: "rounded-2xl",
360
+ }}
361
+ />
362
+ ```
363
+
364
+ بخش‌های موجود: `root`، `toolbar`، `separator`، `button`، `content`، `tableTools`، `popover`، `dialog`، `input`، `label`. کلاس `content` فقط هنگام mount خوانده می‌شود. در `RichContent` هم `className` دارید.
365
+
366
+ ### ۴. نوار ابزار
367
+
368
+ با `toolbar` مشخص کنید کدام دکمه‌ها و با چه ترتیبی نمایش داده شوند. علامت `"|"` جداکننده است:
369
+
370
+ ```tsx
371
+ <RichTextEditor
372
+ toolbar={["bold", "italic", "link", "|", "h2", "h3", "|", "bullet", "ordered", "|", "image", "video"]}
373
+ ...
374
+ />
133
375
  ```
134
376
 
135
- ## Styling
377
+ کلیدها: `bold italic underline strike textColor highlight h2 h3 h4 right center left justify bullet ordered quote code hr link unlink image video table undo redo`. مقدار پیش‌فرض با `defaultToolbar` قابل import است تا از روی آن کپی و ویرایش کنید. پنهان کردن یک دکمه، قابلیت را از ادیتور حذف نمی‌کند (فقط دکمه‌اش نیست).
136
378
 
137
- Override variables: `--bk-accent`, `--bk-fg`, `--bk-bg`, `--bk-border`, `--bk-radius`, `--bk-editor-min-height`, ... (see `src/styles.css`). Content uses the `.bk-rich` class.
379
+ ### ۵. اولویت CSS شما و Tailwind
138
380
 
139
- ## Updating in your projects
381
+ فایل `styles.css` بدون لایه است تا ظاهر پیش‌فرض همیشه سالم بماند؛ برای تغییر ظاهر کافی است متغیرهای `--bk-*` را عوض کنید یا با `classNames` کلاس بدهید.
382
+
383
+ اگر می‌خواهید هر CSS یا کلاس Tailwind شما **بدون نیاز به انتخابگر قوی‌تر** روی استایل پکیج غلبه کند، به‌جای آن نسخه‌ی لایه‌دار را وارد کنید و ترتیب لایه‌ها را صریح بنویسید تا `blog-kit` بعد از `base` (preflight) و قبل از `utilities` بیاید:
384
+
385
+ ```css
386
+ @layer theme, base, blog-kit, components, utilities;
387
+ @import "tailwindcss";
388
+ @import "@ilamanownuk/blog-kit/styles.layered.css";
389
+ ```
390
+
391
+ برای بازنویسی کامل، با انتخابگرهای `.bk-*` (مثل `.bk-btn`، `.bk-toolbar`، `.bk-rich h2`) هر چیزی را عوض کنید. محتوای پست داخل کلاس `.bk-rich` است.
392
+
393
+ ## تغییر متن‌ها (labels)
394
+
395
+ همه‌ی متن‌ها فارسی هستند. هر کدام را با `labels` عوض کنید (کلیدها در `defaultLabels` هست):
396
+
397
+ ```tsx
398
+ import { RichTextEditor, defaultLabels } from "@ilamanownuk/blog-kit";
399
+
400
+ <RichTextEditor
401
+ dir="ltr"
402
+ labels={{ bold: "Bold", imageTitle: "Insert image", videoError: "Aparat or YouTube links only." }}
403
+ ...
404
+ />
405
+ ```
406
+
407
+ ## سئو
408
+
409
+ متن ساده‌ی پست را برای توضیح متا بسازید و آن را در `generateMetadata` بگذارید:
410
+
411
+ ```tsx
412
+ import type { Metadata } from "next";
413
+ import { richTextToPlain } from "@ilamanownuk/blog-kit/server";
414
+
415
+ export async function generateMetadata({ params }): Promise<Metadata> {
416
+ const post = await getPost((await params).slug);
417
+ const description = post.metaDescription ?? richTextToPlain(post.body).slice(0, 160);
418
+ return { title: post.metaTitle ?? post.title, description };
419
+ }
420
+ ```
421
+
422
+ نکته‌ها: لینک‌های بیرونی خودکار `rel="noopener noreferrer nofollow"` می‌گیرند، تصاویر `loading="lazy"` دارند، و برای سئوی بهتر همیشه متن جایگزین (alt) تصویر را پر کنید. تیترهای ادیتور از `h2` شروع می‌شوند، چون `h1` عنوان صفحه است.
423
+
424
+ ## جدول کامل props
425
+
426
+ ### `RichTextEditor`
427
+
428
+ | prop | نوع | توضیح |
429
+ | --- | --- | --- |
430
+ | `value` | `string` | HTML فعلی (الزامی) |
431
+ | `onChange` | `(html: string) => void` | با هر تغییر؛ ادیتور خالی `""` می‌فرستد (الزامی) |
432
+ | `placeholder` | `string` | متن راهنما؛ پیش‌فرض از `labels.placeholder` |
433
+ | `invalid` | `boolean` | کادر قرمز (رنگ `--bk-danger`) |
434
+ | `id` | `string` | `id` ناحیه‌ی نوشتن، برای `<label htmlFor>` |
435
+ | `className` | `string` | کلاس اضافه برای ریشه |
436
+ | `classNames` | `EditorClassNames` | کلاس اضافه به هر بخش |
437
+ | `toolbar` | `ToolbarItem[]` | انتخاب و ترتیب دکمه‌ها؛ پیش‌فرض `defaultToolbar` |
438
+ | `uploadImage` | `(file: File) => Promise<{url, alt?}>` | فعال‌کردن آپلود |
439
+ | `mediaApi` | `{ list, upload }` | کتابخانه‌ی رسانه‌ی داخلی |
440
+ | `renderMediaPicker` | `({ onSelect, close }) => ReactNode` | انتخابگر اختصاصی (اولویت با این است) |
441
+ | `resolveImageSrc` | `(url: string) => string` | تغییر آدرس تصویر پیش از درج |
442
+ | `allowedEmbeds` | `("aparat" \| "youtube")[]` | پیش‌فرض هر دو؛ با سرور یکی باشد |
443
+ | `labels` | `Partial<Labels>` | تغییر متن‌ها |
444
+ | `dir` | `"rtl" \| "ltr"` | پیش‌فرض `"rtl"` |
445
+
446
+ ### `RichContent`
447
+
448
+ | prop | نوع | توضیح |
449
+ | --- | --- | --- |
450
+ | `html` | `string` | HTML ذخیره‌شده (الزامی) |
451
+ | `className` | `string` | کلاس اضافه روی `.bk-rich` |
452
+ | `dir` / `lang` | `"rtl" \| "ltr"` / `string` | پیش‌فرض `"rtl"` و `"fa"` |
453
+ | `allowedEmbeds` | `EmbedProvider[]` | مثل سرور |
454
+ | `isAllowedImageSrc` | `(src: string) => boolean` | فیلتر اضافه‌ی تصویر |
455
+
456
+ ### توابع `/server`
457
+
458
+ - `sanitizeRichText(html, { allowedEmbeds?, isAllowedImageSrc? })` رشته‌ی پاک‌سازی‌شده برمی‌گرداند.
459
+ - `hasRichContent(html, options?)` اگر متن، تصویر، ویدیو یا جدول داشته باشد `true`.
460
+ - `richTextToPlain(html)` متن ساده بدون تگ.
461
+ - همچنین `toVideoEmbedUrl`، `normalizeLinkUrl`، `isAllowedEmbedSrc` و `ALL_EMBED_PROVIDERS`.
462
+
463
+ ## به‌روزرسانی پکیج
464
+
465
+ ```bash
466
+ pnpm up @ilamanownuk/blog-kit
467
+ pnpm up @ilamanownuk/blog-kit --latest
468
+ ```
469
+
470
+ برای خودکار شدن، Renovate یا Dependabot را فعال کنید تا برای هر نسخه‌ی جدید یک Pull Request باز شود. نسخه‌ها از semver پیروی می‌کنند و تغییرات در [`CHANGELOG.md`](./CHANGELOG.md) هستند. چون لیست مجاز HTML فقط در یک جا (`/server`) تعریف شده، وقتی ادیتور، بک‌اند و نمایش از یک نسخه استفاده کنند همیشه هماهنگ می‌مانند.
471
+
472
+ ## عیب‌یابی
473
+
474
+ | مشکل | علت و راه‌حل |
475
+ | --- | --- |
476
+ | خطای `window is not defined` یا `document is not defined` | ادیتور را در یک فایل `"use client"` استفاده کنید. اگر هنوز مشکل داشت، با `next/dynamic` و `{ ssr: false }` بارگذاری کنید. |
477
+ | ادیتور بدون ظاهر است (دکمه‌ها و کادر استایل ندارند) | `import "@ilamanownuk/blog-kit/styles.css"` را فراموش کرده‌اید؛ اگر نسخه‌ی لایه‌دار را استفاده می‌کنید، ترتیب لایه‌ها را طبق بخش «اولویت CSS» بنویسید. |
478
+ | استایل پیش‌فرض Tailwind (preflight) لیست‌ها و تیترها را خراب کرده | از `styles.css` (بدون لایه) استفاده کنید، یا در نسخه‌ی لایه‌دار ترتیب `@layer theme, base, blog-kit, components, utilities;` را بنویسید. |
479
+ | ویدیو بعد از ذخیره ناپدید می‌شود (`iframe` حذف شده) | `allowedEmbeds` در ادیتور و سرور یکی نیست، یا آدرس از آپارات/یوتیوب نیست. |
480
+ | عکس بعد از ذخیره حذف می‌شود | آدرس `https` نیست یا `isAllowedImageSrc` آن را رد می‌کند. |
481
+ | تم تیره در پنجره‌ها اعمال نمی‌شود | `data-bk-theme="dark"` را روی `html` یا `body` بگذارید، نه روی wrapper. |
482
+ | تغییر `placeholder` یا `allowedEmbeds` اثر ندارد | این مقادیر فقط هنگام mount خوانده می‌شوند؛ مقدار ثابت بدهید یا با `key` کامپوننت را دوباره بسازید. |
483
+ | دو نسخه‌ی Tiptap در پروژه | پکیج‌های `@tiptap/*` را از `package.json` پروژه حذف کنید (اگر جای دیگری استفاده نمی‌شوند). |
484
+
485
+ ## English summary
486
+
487
+ A Tiptap-based rich-text editor kit for blogs: RTL/Persian by default, image upload and media-library adapters, Aparat/YouTube embeds, a server-side allowlist sanitizer and a Server-Component-friendly renderer. Output is plain HTML. No Tailwind required.
488
+
489
+ ```tsx
490
+ import "@ilamanownuk/blog-kit/styles.css";
491
+ import { RichTextEditor } from "@ilamanownuk/blog-kit"; // client
492
+ import { RichContent } from "@ilamanownuk/blog-kit/renderer"; // server-safe
493
+ import { sanitizeRichText } from "@ilamanownuk/blog-kit/server"; // always sanitize on save
494
+ ```
140
495
 
141
- Bump the version (`pnpm up @ilamanownuk/blog-kit`) or let Renovate/Dependabot open the PR. Releases follow semver; the HTML allowlist lives in one place (`/server`), so editor, backend and renderer stay in sync when they share a version.
496
+ Theming: override `--bk-*` CSS variables, use `data-bk-theme="dark"`, pass `classNames` / `toolbar` props; `styles.css` is unlayered (default look always intact); import `styles.layered.css` to put everything in `@layer blog-kit`. See `AI_INSTALL_PROMPT.md` for an agent-ready installation prompt and the full API reference.
142
497
 
143
- ## Development
498
+ ## توسعه
144
499
 
145
500
  ```bash
146
501
  pnpm install && pnpm typecheck && pnpm test && pnpm build