@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/AI_INSTALL_PROMPT.md +141 -0
- package/CHANGELOG.md +13 -0
- package/README.md +422 -67
- package/dist/index.cjs +92 -37
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +16 -3
- package/dist/index.d.ts +16 -3
- package/dist/index.js +92 -38
- package/dist/index.js.map +1 -1
- package/dist/styles.css +121 -38
- package/dist/styles.layered.css +301 -0
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -1,146 +1,501 @@
|
|
|
1
1
|
# @ilamanownuk/blog-kit
|
|
2
2
|
|
|
3
|
-
ویرایشگر متن غنی Tiptap برای بلاگ
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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
|
-
|
|
45
|
+
پیشنیازها: `react` و `react-dom` نسخهی ۱۹ یا بالاتر (peer dependency). Tiptap، آیکنها و sanitizer خودشان همراه پکیج نصب میشوند؛ **Tiptap را جداگانه نصب نکنید** تا نسخهها دوتا نشوند.
|
|
46
|
+
|
|
47
|
+
پکیج چهار ورودی دارد:
|
|
13
48
|
|
|
14
|
-
|
|
|
49
|
+
| ورودی | کاربرد |
|
|
15
50
|
| --- | --- |
|
|
16
|
-
| `@ilamanownuk/blog-kit` | `RichTextEditor` (
|
|
17
|
-
| `@ilamanownuk/blog-kit/renderer` | `RichContent` (
|
|
18
|
-
| `@ilamanownuk/blog-kit/server` | `sanitizeRichText
|
|
19
|
-
| `@ilamanownuk/blog-kit/styles.css` |
|
|
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
|
-
|
|
56
|
+
## افزودن استایل
|
|
22
57
|
|
|
23
|
-
|
|
58
|
+
فایل استایل را فقط یک بار در لایهی اصلی پروژه وارد کنید. در Next.js (App Router) در `app/layout.tsx`:
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
24
61
|
import "@ilamanownuk/blog-kit/styles.css";
|
|
25
62
|
```
|
|
26
63
|
|
|
27
|
-
|
|
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
|
-
|
|
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
|
-
|
|
41
|
-
Extensions are created once on mount, so `allowedEmbeds`/`placeholder` should be stable.
|
|
196
|
+
`RichContent` قبل از نمایش، HTML را دوباره پاکسازی میکند. هرگز HTML پست را با `dangerouslySetInnerHTML` مستقیم رندر نکنید.
|
|
42
197
|
|
|
43
|
-
|
|
198
|
+
Props: `html` (الزامی)، `className`، `dir` (پیشفرض `"rtl"`)، `lang` (پیشفرض `"fa"`)، `allowedEmbeds`، `isAllowedImageSrc`. دو گزینهی آخر باید با تنظیمات ذخیرهسازی یکی باشند.
|
|
44
199
|
|
|
45
|
-
|
|
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
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 }),
|
|
70
|
-
upload: (formData) => uploadMedia(formData),
|
|
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
|
-
|
|
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
|
-
|
|
260
|
+
اگر کتابخانهی رسانهی خودتان رابط کاربری دارد، با `renderMediaPicker` آن را جایگزین کنید (در اولویت بالاتر از `mediaApi` است):
|
|
79
261
|
|
|
80
262
|
```tsx
|
|
81
263
|
<RichTextEditor
|
|
264
|
+
value={html}
|
|
265
|
+
onChange={setHtml}
|
|
82
266
|
renderMediaPicker={({ onSelect, close }) => (
|
|
83
|
-
<
|
|
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
|
-
|
|
275
|
+
## ویدیوی آپارات و یوتیوب
|
|
90
276
|
|
|
91
|
-
|
|
277
|
+
کاربر لینک صفحهی ویدیو را میچسباند (مثلاً `https://www.aparat.com/v/xxxx` یا لینک یوتیوب) و پکیج آن را به آدرس embed امن تبدیل میکند. بهطور پیشفرض هر دو مجاز هستند. برای محدود کردن:
|
|
92
278
|
|
|
93
279
|
```tsx
|
|
94
|
-
|
|
280
|
+
// ادیتور
|
|
281
|
+
<RichTextEditor allowedEmbeds={["aparat"]} ... />
|
|
282
|
+
|
|
283
|
+
// سرور و نمایش، دقیقاً همان مقدار
|
|
284
|
+
sanitizeRichText(html, { allowedEmbeds: ["aparat"] });
|
|
285
|
+
<RichContent html={html} allowedEmbeds={["aparat"]} />
|
|
95
286
|
```
|
|
96
287
|
|
|
97
|
-
|
|
288
|
+
اگر مقدار در ادیتور و سرور فرق کند، `iframe` در سرور حذف میشود. بهتر است مقدار را در یک ثابت مشترک بگذارید:
|
|
98
289
|
|
|
99
|
-
|
|
290
|
+
```ts
|
|
291
|
+
export const EMBEDS = ["aparat", "youtube"] as const;
|
|
292
|
+
```
|
|
100
293
|
|
|
101
|
-
##
|
|
294
|
+
## شخصیسازی ظاهر
|
|
102
295
|
|
|
103
|
-
|
|
296
|
+
ظاهر پیشفرض همین است که میبینید، ولی هر چیزی قابل تغییر است.
|
|
104
297
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
298
|
+
### ۱. متغیرهای CSS
|
|
299
|
+
|
|
300
|
+
متغیرها را روی `:root` یا هر عنصر والد بازنویسی کنید:
|
|
108
301
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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
|
-
|
|
312
|
+
متغیرهای اصلی:
|
|
118
313
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
-
|
|
346
|
+
### ۳. classNames
|
|
347
|
+
|
|
348
|
+
با prop به نام `classNames` به هر بخش ادیتور کلاس اضافه کنید (کلاسهای Tailwind هم میشود):
|
|
129
349
|
|
|
130
350
|
```tsx
|
|
131
|
-
|
|
132
|
-
|
|
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
|
-
|
|
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
|
-
|
|
379
|
+
### ۵. اولویت CSS شما و Tailwind
|
|
138
380
|
|
|
139
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
498
|
+
## توسعه
|
|
144
499
|
|
|
145
500
|
```bash
|
|
146
501
|
pnpm install && pnpm typecheck && pnpm test && pnpm build
|