feat(admin): enhance editor UI (links, image captions) & fix categories

Added animated auto-opening link modal, custom image node with isolated caption deletion, fixed single-select category data binding, improved featured image layout, and updated README.
2026-09-15 11:33:04 +03:30
parent 35c03ef35e
commit 049291c109
40 changed files with 55736 additions and 440 deletions
@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
+import { Controller, useController, useForm } from 'react-hook-form'
 import { Link, Navigate, useNavigate, useParams } from 'react-router-dom'
 import { ArrowRightIcon, CheckIcon, EyeIcon, Trash2Icon } from 'lucide-react'
 import Swal from 'sweetalert2'
@@ -9,8 +10,11 @@ import { ArticleEditor } from '../components/admin/ArticleEditor'
 import { SeoChecklist } from '../components/admin/SeoChecklist'
 import { ImageField } from '../components/admin/ImageField'
 import { JalaliDatePicker } from '../components/admin/JalaliDatePicker'
-import { LuxeSelect, LuxeTagsSelect } from '../components/admin/LuxeSelect'
+import { CategorySelect, LuxeTagsSelect } from '../components/admin/LuxeSelect'
+import type { CategoryOption } from '../components/admin/LuxeSelect'
 import { ARTICLE_CATEGORIES } from './entities'
+import { FEATURED_IMAGE_ALT_SUFFIX } from '../data/constants'
+import { formatReadingTime } from '../utils/readingTime'
 import type { Article, ArticleBodyDoc } from '../data/site'

 const EMPTY_DOC = { type: 'doc', content: [{ type: 'paragraph' }] } as unknown as ArticleBodyDoc
@@ -18,6 +22,30 @@ const EMPTY_DOC = { type: 'doc', content: [{ type: 'paragraph' }] } as unknown a
 /** پیش‌نویس صفحه نوشتن — همان شکل Article با بدنه ساختاریافته */
 type Draft = Omit<Article, 'body'> & { body: ArticleBodyDoc }

+/**
+ * فیلدهای متادیتای مقاله که با React Hook Form مدیریت می‌شوند:
+ * عنوان (مبنای Alt پویا)، دسته‌بندی و متادیتای تصویر شاخص.
+ * `category` در فرم یک شیء تک‌مقداری {value,label} یا null است
+ * که هنگام ذخیره به رشته (ستون category در بک‌اند) نگاشت می‌شود.
+ */
+type ArticleMetaForm = {
+  title: string
+  category: CategoryOption | null
+  image_alt: string
+  image_title: string
+}
+
+/** مقدار رشته‌ای ذخیره‌شده → گزینه react-select (یا null وقتی خالی است) */
+function toCategoryOption(value: string): CategoryOption | null {
+  const category = (value ?? '').trim()
+  return category ? { label: category, value: category } : null
+}
+
+/** گزینه react-select → مقدار رشته‌ای ذخیره‌سازی در بک‌اند */
+function categoryValue(option: CategoryOption | null): string {
+  return option?.value.trim() ?? ''
+}
+
 /** داده‌های قدیمی ممکن است هشتگ را رشته کاماشده داشته باشند */
 function normalizeTags(value: unknown): string[] {
  if (Array.isArray(value)) return value.map((t) => String(t).trim()).filter(Boolean)
@@ -54,6 +82,7 @@ export function ArticleWritePage() {
    tags: [],
    image: '',
    image_alt: '',
+    image_title: '',
    author: '',
    meta_description: '',
    read: '۵ دقیقه',
@@ -62,6 +91,25 @@ export function ArticleWritePage() {
    status: 'draft',
    seo_keyphrase: '',
  })
+
+  /**
+   * فرم متادیتا با React Hook Form — منبع نمایش فیلدها.
+   * هر تغییر، هم فرم و هم draft (مبنای ذخیره‌سازی خودکار) را به‌روز می‌کند.
+   */
+  const { control, watch, reset } = useForm<ArticleMetaForm>({
+    defaultValues: {
+      title: '',
+      category: toCategoryOption(ARTICLE_CATEGORIES[0]),
+      image_alt: '',
+      image_title: '',
+    },
+    mode: 'onChange',
+  })
+  /** عنوان زنده مقاله — مبنای متن جایگزین (Alt) تصویر شاخص */
+  const watchedTitle = watch('title')
+  const { field: imageAltField } = useController({ name: 'image_alt', control })
+  const { field: imageTitleField } = useController({ name: 'image_title', control })
+
  const [createdId, setCreatedId] = useState<number | null>(null)
  const [deleting, setDeleting] = useState(false)
  const draftRef = useRef(draft)
@@ -99,6 +147,13 @@ export function ArticleWritePage() {
      body: (Array.isArray(article.body) ? EMPTY_DOC : article.body) as ArticleBodyDoc,
    })
    setCreatedId(article.id)
+    // فرم متادیتا هم با مقادیر مقاله بارگذاری‌شده همگام می‌شود
+    reset({
+      title: article.title ?? '',
+      category: toCategoryOption(article.category ?? ''),
+      image_alt: article.image_alt ?? '',
+      image_title: article.image_title ?? '',
+    })
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [article?.id])

@@ -196,6 +251,11 @@ export function ArticleWritePage() {

  const metaLength = (draft.meta_description ?? '').trim().length

+  // متن جایگزین تصویر شاخص — با watch('title') به‌صورت زنده ساخته می‌شود
+  const imageAltFallback = [watchedTitle.trim(), FEATURED_IMAGE_ALT_SUFFIX]
+    .filter(Boolean)
+    .join(' - ')
+
  return (
    <div dir="rtl" className="min-h-screen bg-ink font-pinar text-ivory">
      {/* نوار بالا */}
@@ -276,31 +336,48 @@ export function ArticleWritePage() {
              : 'مقاله منتشرشده — تغییرها همان لحظه در سایت اعمال می‌شود'}
        </p>

-        {/* عنوان */}
-        <input
-          type="text"
-          {...textField('title')}
-          placeholder="عنوان مقاله…"
-          aria-label="عنوان مقاله"
-          className="mt-4 w-full bg-transparent text-4xl font-bold leading-[1.6] text-ivory placeholder:text-ivory/25 focus:outline-none"
+        {/* عنوان — با Controller به فرم وصل است تا watch('title') زنده بماند */}
+        <Controller
+          name="title"
+          control={control}
+          render={({ field }) => (
+            <input
+              type="text"
+              {...field}
+              onChange={(event) => {
+                field.onChange(event.target.value)
+                queueSave({ title: event.target.value })
+              }}
+              placeholder="عنوان مقاله…"
+              aria-label="عنوان مقاله"
+              className="mt-4 w-full bg-transparent text-4xl font-bold leading-[1.6] text-ivory placeholder:text-ivory/25 focus:outline-none"
+            />
+          )}
        />
        <div className="mt-4 h-px w-28 bg-copper" />

-        {/* تصویر شاخص + متن جایگزین */}
+        {/* تصویر شاخص + متن جایگزین و عنوان (هر دو به فرم وصل‌اند) */}
        <div className="mt-8">
          <ImageField
            label="تصویر شاخص مقاله"
            value={draft.image}
-            alt={draft.image_alt ?? ''}
-            altFallback={draft.title}
+            alt={imageAltField.value}
+            altFallback={imageAltFallback}
+            title={imageTitleField.value}
            onSave={async (url) => {
              queueSave({ image: url })
              return true
            }}
            onSaveAlt={async (alt) => {
+              imageAltField.onChange(alt)
              queueSave({ image_alt: alt })
              return true
            }}
+            onSaveTitle={async (imageTitle) => {
+              imageTitleField.onChange(imageTitle)
+              queueSave({ image_title: imageTitle })
+              return true
+            }}
          />
        </div>

@@ -309,11 +386,8 @@ export function ArticleWritePage() {
          <ArticleEditor
            doc={draft.body as unknown as Record<string, unknown>}
            onChange={(json) => {
-              // محاسبه خودکار زمان مطالعه بر اساس تعداد کلمات متن
-              const textContent = JSON.stringify(json)
-              const wordCount = textContent.split(/\s+/).length
-              const calculatedReadTime = Math.max(1, Math.ceil(wordCount / 200)) + ' دقیقه'
-              queueSave({ body: json, read: calculatedReadTime })
+              // زمان مطالعه بهصورت پویا از متن سند محاسبه میشود (۲۰۰ واژه در دقیقه)
+              queueSave({ body: json, read: formatReadingTime(json) })
            }}
          />
        </div>
@@ -394,11 +468,20 @@ export function ArticleWritePage() {
              <div>
                <label className="text-xs font-light text-ivory/50">دسته‌بندی مقاله (Category)</label>
                <div className="mt-2">
-                  <LuxeSelect
-                    value={draft.category}
-                    options={ARTICLE_CATEGORIES}
-                    onChange={(category) => queueSave({ category })}
-                    isClearable={false}
+                  {/* تک‌انتخابی: ورودی/خروجی Controller یک {value,label} یا null است */}
+                  <Controller
+                    name="category"
+                    control={control}
+                    render={({ field }) => (
+                      <CategorySelect
+                        value={field.value}
+                        options={ARTICLE_CATEGORIES}
+                        onChange={(option) => {
+                          field.onChange(option)
+                          queueSave({ category: categoryValue(option) })
+                        }}
+                      />
+                    )}
                  />
                </div>
              </div>
@@ -8,7 +8,7 @@ import { adminApi } from './adminClient'
 import type { EntityConfig, FieldConfig } from './entities'
 import { ImageField } from '../components/admin/ImageField'
 import { JalaliDatePicker } from '../components/admin/JalaliDatePicker'
-import { LuxeSelect, LuxeTagsSelect } from '../components/admin/LuxeSelect'
+import { LuxeCreatableSelect, LuxeSelect, LuxeTagsSelect } from '../components/admin/LuxeSelect'
 import { ArticleEditor } from '../components/admin/ArticleEditor'

 type EntityDrawerProps = {
@@ -114,22 +114,34 @@ export function EntityDrawer({ config, item, onClose, deletable = false }: Entit
        <div className="flex-1 overflow-y-auto px-6 py-6">
          <div className="grid gap-6">
            {config.fields.map((field) => {
+              const isImage = field.type === 'image'
              // فیلد Alt تصویر: برای گالری همان ستون alt و برای بقیه <نام فیلد>_alt
-              const altKey =
-                field.type === 'image'
-                  ? field.name === 'src' && 'alt' in item
-                    ? 'alt'
-                    : `${field.name}_alt`
-                  : ''
+              const altKey = isImage
+                ? field.name === 'src' && 'alt' in item
+                  ? 'alt'
+                  : `${field.name}_alt`
+                : ''
+              const imageTitleKey = isImage ? `${field.name}_title` : ''
+              // پیشنهاد Alt از عنوان رکورد ساخته می‌شود (هرگز از URL)
+              const imageAltFallback = [
+                String(item[config.titleKey] ?? '').trim(),
+                field.altFallbackSuffix,
+              ]
+                .filter(Boolean)
+                .join(' - ')
              return (
                <FieldControl
                  key={field.name}
                  field={field}
                  value={item[field.name]}
                  altValue={altKey ? String(item[altKey] ?? '') : undefined}
-                  altFallback={String(item[config.titleKey] ?? '')}
+                  altFallback={imageAltFallback}
+                  imageTitleValue={imageTitleKey ? String(item[imageTitleKey] ?? '') : undefined}
                  onSave={(value) => saveField(field.name, value)}
                  onSaveAlt={altKey ? (alt) => saveField(altKey, alt) : undefined}
+                  onSaveImageTitle={
+                    imageTitleKey ? (title) => saveField(imageTitleKey, title) : undefined
+                  }
                  registerFlush={
                    field.type === 'wysiwyg'
                      ? (fn) => {
@@ -166,8 +178,10 @@ function FieldControl({
  value,
  altValue,
  altFallback,
+  imageTitleValue,
  onSave,
  onSaveAlt,
+  onSaveImageTitle,
  registerFlush,
 }: {
  field: FieldConfig
@@ -175,12 +189,20 @@ function FieldControl({
  /** مقدار Alt تصویر — فقط برای فیلدهای image */
  altValue?: string
  altFallback?: string
+  /** مقدار Title تصویر — فقط برای فیلدهای image */
+  imageTitleValue?: string
  onSave: (value: unknown) => Promise<boolean>
  onSaveAlt?: (alt: string) => Promise<boolean>
+  onSaveImageTitle?: (title: string) => Promise<boolean>
  registerFlush?: (fn: () => void) => void
 }) {
  const [text, setText] = useState<string>(String(value ?? ''))

+  // همگام‌سازی مقدار محلی با داده‌ای که از بیرون می‌آید (بارگذاری/به‌روزرسانی خوش‌بینانه)
+  useEffect(() => {
+    setText(String(value ?? ''))
+  }, [value])
+
  const commitText = async () => {
    const next = field.type === 'number' ? Number(text) || 0 : text
    if (String(value ?? '') === String(next)) return
@@ -194,26 +216,34 @@ function FieldControl({
        value={String(value ?? '')}
        alt={altValue}
        altFallback={altFallback}
+        title={imageTitleValue}
        onSave={(url) => onSave(url)}
        onSaveAlt={onSaveAlt}
+        onSaveTitle={onSaveImageTitle}
      />
    )
  }

  if (field.type === 'select') {
+    // مقدار نمایشی از وضعیت محلی می‌آید تا افزودن/حذف گزینه فوراً دیده شود
+    const selectProps = {
+      value: text,
+      options: field.options ?? [],
+      onChange: (next: string) => {
+        setText(next)
+        void onSave(next)
+      },
+    }
    return (
      <div>
        <p className="text-xs font-bold text-ivory/80">{field.label}</p>
        {field.hint && <p className="mt-1 text-[10px] font-light text-ivory/40">{field.hint}</p>}
        <div className="mt-2">
-          <LuxeSelect
-            value={String(value ?? '')}
-            options={field.options ?? []}
-            onChange={(next) => {
-              setText(next)
-              void onSave(next)
-            }}
-          />
+          {field.creatable ? (
+            <LuxeCreatableSelect {...selectProps} />
+          ) : (
+            <LuxeSelect {...selectProps} />
+          )}
        </div>
      </div>
    )
@@ -1,4 +1,5 @@
 import type { SiteData } from '../api'
+import { FEATURED_IMAGE_ALT_SUFFIX } from '../data/constants'

 export type FieldType = 'text' | 'textarea' | 'number' | 'image' | 'list' | 'wysiwyg' | 'select' | 'date'

@@ -9,8 +10,12 @@ export type FieldConfig = {
  hint?: string
  /** فقط برای type === 'select' — گزینه‌های ثابت react-select */
  options?: string[]
+  /** فقط برای type === 'select' — امکان ساخت گزینه جدید توسط کاربر */
+  creatable?: boolean
  /** ویجت سفارشی نوع list — 'tags' یعنی react-select قابل ساخت (Creatable) */
  ui?: 'lines' | 'tags'
+  /** پسوند پیشنهاد Alt تصویر — مثل «تصویر شاخص» در کنار عنوان رکورد */
+  altFallbackSuffix?: string
 }

 export type EntityConfig = {
@@ -73,8 +78,8 @@ export const ENTITIES: Record<string, EntityConfig> = {
      F('body', 'متن مقاله', 'wysiwyg'),
      F('excerpt', 'چکیده (روی کارت مقاله)'),
      F('meta_description', 'توضیحات سئو (Meta Description)', 'textarea', '۱۵۰ تا ۱۶۰ کاراکتر — زیر عنوان در نتایج گوگل نمایش داده می‌شود'),
-      F('image', 'تصویر شاخص', 'image'),
-      F('category', 'دسته‌بندی (Category)', 'select', undefined, { options: ARTICLE_CATEGORIES }),
+      F('image', 'تصویر شاخص', 'image', undefined, { altFallbackSuffix: FEATURED_IMAGE_ALT_SUFFIX }),
+      F('category', 'دسته‌بندی (Category)', 'select', 'می‌توانید دسته جدید هم بسازید', { options: ARTICLE_CATEGORIES, creatable: true }),
      F('tags', 'هشتگ‌ها / برچسب‌ها', 'list', 'با Enter هر هشتگ جدید را اضافه کنید', { ui: 'tags' }),
      F('author', 'نویسنده'),
      F('date', 'تاریخ انتشار (شمسی)', 'date'),
@@ -89,6 +94,7 @@ export const ENTITIES: Record<string, EntityConfig> = {
      tags: ['مدیریت پروژه', 'ساخت‌وساز'], 
      image: '', 
      image_alt: '',
+      image_title: '',
      author: '',
      meta_description: '',
      read: '۵ دقیقه',