@ilamanownuk/blog-kit 0.0.0-stage → 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,3 +1,504 @@
1
- # Temporary Holding Version
1
+ # @ilamanownuk/blog-kit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ ## نصب
39
+
40
+ ```bash
41
+ pnpm add @ilamanownuk/blog-kit
42
+ # یا: npm i @ilamanownuk/blog-kit | yarn add @ilamanownuk/blog-kit
43
+ ```
44
+
45
+ پیش‌نیازها: `react` و `react-dom` نسخه‌ی ۱۹ یا بالاتر (peer dependency). Tiptap، آیکن‌ها و sanitizer خودشان همراه پکیج نصب می‌شوند؛ **Tiptap را جداگانه نصب نکنید** تا نسخه‌ها دوتا نشوند.
46
+
47
+ پکیج چهار ورودی دارد:
48
+
49
+ | ورودی | کاربرد |
50
+ | --- | --- |
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` | استایل‌ها |
55
+
56
+ ## افزودن استایل
57
+
58
+ فایل استایل را فقط یک بار در لایه‌ی اصلی پروژه وارد کنید. در Next.js (App Router) در `app/layout.tsx`:
59
+
60
+ ```tsx
61
+ import "@ilamanownuk/blog-kit/styles.css";
62
+ ```
63
+
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.
76
+
77
+ ```tsx
78
+ "use client";
79
+
80
+ import { useState } from "react";
81
+ import { RichTextEditor } from "@ilamanownuk/blog-kit";
82
+
83
+ export function PostForm() {
84
+ const [html, setHtml] = useState("");
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
+ );
193
+ }
194
+ ```
195
+
196
+ `RichContent` قبل از نمایش، HTML را دوباره پاک‌سازی می‌کند. هرگز HTML پست را با `dangerouslySetInnerHTML` مستقیم رندر نکنید.
197
+
198
+ Props: `html` (الزامی)، `className`، `dir` (پیش‌فرض `"rtl"`)، `lang` (پیش‌فرض `"fa"`)، `allowedEmbeds`، `isAllowedImageSrc`. دو گزینه‌ی آخر باید با تنظیمات ذخیره‌سازی یکی باشند.
199
+
200
+ ## آپلود عکس
201
+
202
+ اگر `uploadImage` بدهید، در پنجره‌ی درج تصویر دکمه‌ی «آپلود تصویر» ظاهر می‌شود. این تابع فایل را می‌گیرد و باید `{ url, alt? }` برگرداند. اگر خطا پرتاب کند، پیام آن داخل پنجره نمایش داده می‌شود. فقط آدرس‌های `https://` پذیرفته می‌شوند.
203
+
204
+ ```ts
205
+ // app/admin/actions.ts
206
+ "use server";
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 باشد
213
+ }
214
+ ```
215
+
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
+ ```
227
+
228
+ با `resolveImageSrc` می‌توانید آدرس را قبل از درج تغییر دهید (مثلاً انتخاب نسخه‌ی ۹۶۰ پیکسلی):
229
+
230
+ ```tsx
231
+ resolveImageSrc={(url) => url.replace(/\.(\w+)$/, "-960.$1")}
232
+ ```
233
+
234
+ ## کتابخانه‌ی رسانه
235
+
236
+ برای انتخاب از تصاویر قبلی، `mediaApi` را بدهید. دو تابع دارد؛ بهتر است با Server Action پیاده شوند تا توکن‌ها در سرور بمانند:
237
+
238
+ ```tsx
239
+ <RichTextEditor
240
+ value={html}
241
+ onChange={setHtml}
242
+ mediaApi={{
243
+ list: ({ q, page }) => listMedia({ q, page }), // → { items, total, page, pageSize, error? }
244
+ upload: (formData) => uploadMedia(formData), // formData.get("file") → { items, error? }
245
+ }}
246
+ />
247
+ ```
248
+
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
+ ```
259
+
260
+ اگر کتابخانه‌ی رسانه‌ی خودتان رابط کاربری دارد، با `renderMediaPicker` آن را جایگزین کنید (در اولویت بالاتر از `mediaApi` است):
261
+
262
+ ```tsx
263
+ <RichTextEditor
264
+ value={html}
265
+ onChange={setHtml}
266
+ renderMediaPicker={({ onSelect, close }) => (
267
+ <MyMediaPicker
268
+ onPick={(m) => onSelect({ url: m.url, alt: m.alt ?? undefined })}
269
+ onCancel={close}
270
+ />
271
+ )}
272
+ />
273
+ ```
274
+
275
+ ## ویدیوی آپارات و یوتیوب
276
+
277
+ کاربر لینک صفحه‌ی ویدیو را می‌چسباند (مثلاً `https://www.aparat.com/v/xxxx` یا لینک یوتیوب) و پکیج آن را به آدرس embed امن تبدیل می‌کند. به‌طور پیش‌فرض هر دو مجاز هستند. برای محدود کردن:
278
+
279
+ ```tsx
280
+ // ادیتور
281
+ <RichTextEditor allowedEmbeds={["aparat"]} ... />
282
+
283
+ // سرور و نمایش، دقیقاً همان مقدار
284
+ sanitizeRichText(html, { allowedEmbeds: ["aparat"] });
285
+ <RichContent html={html} allowedEmbeds={["aparat"]} />
286
+ ```
287
+
288
+ اگر مقدار در ادیتور و سرور فرق کند، `iframe` در سرور حذف می‌شود. بهتر است مقدار را در یک ثابت مشترک بگذارید:
289
+
290
+ ```ts
291
+ export const EMBEDS = ["aparat", "youtube"] as const;
292
+ ```
293
+
294
+ ## شخصی‌سازی ظاهر
295
+
296
+ ظاهر پیش‌فرض همین است که می‌بینید، ولی هر چیزی قابل تغییر است.
297
+
298
+ ### ۱. متغیرهای CSS
299
+
300
+ متغیرها را روی `:root` یا هر عنصر والد بازنویسی کنید:
301
+
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
+ }
310
+ ```
311
+
312
+ متغیرهای اصلی:
313
+
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);
343
+ }
344
+ ```
345
+
346
+ ### ۳. classNames
347
+
348
+ با prop به نام `classNames` به هر بخش ادیتور کلاس اضافه کنید (کلاس‌های Tailwind هم می‌شود):
349
+
350
+ ```tsx
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
+ />
375
+ ```
376
+
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 است تا از روی آن کپی و ویرایش کنید. پنهان کردن یک دکمه، قابلیت را از ادیتور حذف نمی‌کند (فقط دکمه‌اش نیست).
378
+
379
+ ### ۵. اولویت CSS شما و Tailwind
380
+
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
+ ```
495
+
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.
497
+
498
+ ## توسعه
499
+
500
+ ```bash
501
+ pnpm install && pnpm typecheck && pnpm test && pnpm build
502
+ ```
503
+
504
+ MIT