@fecommunity/reactpress-theme-starter 1.0.0-beta.0

package/app/suggestions/page.tsx

@@ -0,0 +1,47 @@
+import CmsPageClient from '@/components/article/CmsPageClient'
+import { buildCmsPageMetadata, parseSiteSeoContext } from '@/lib/reactpress/contentSeo'
+import { coercePublishedPage } from '@/lib/reactpress/coercePublishedPage'
+import { buildListPageMetadata } from '@/lib/reactpress/siteMetadata'
+import { tServer } from '@/lib/reactpress/serverLocale'
+import {
+  fetchCmsPageProps,
+  fetchSiteMeta,
+  themeApi,
+  unwrapSetting,
+  withApiRetry,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+import type { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+
+export const revalidate = 60
+
+export async function generateMetadata(): Promise<Metadata> {
+  try {
+    const [{ page: rawPage }, siteMeta, settingRow] = await Promise.all([
+      withApiRetry(() => fetchCmsPageProps(themeApi, 'suggestions')),
+      withApiRetry(() => fetchSiteMeta(themeApi)),
+      withApiRetry(() => themeApi.setting.findAll()).then(unwrapSetting),
+    ])
+    const page = coercePublishedPage(rawPage)
+    if (page) {
+      return buildCmsPageMetadata(page, parseSiteSeoContext(settingRow, siteMeta))
+    }
+  } catch {
+    // fall through
+  }
+  return buildListPageMetadata(await tServer('suggestions'), undefined, '/suggestions')
+}
+
+export default async function SuggestionsPage() {
+  try {
+    const { page: rawPage } = await withApiRetry(() => fetchCmsPageProps(themeApi, 'suggestions'))
+    const page = coercePublishedPage(rawPage)
+    if (!page) {
+      notFound()
+    }
+    return <CmsPageClient page={page} />
+  } catch (error) {
+    console.error('[reactpress-theme-starter] suggestions page fetch failed', error)
+    notFound()
+  }
+}

package/app/tag/[tag]/page.tsx

@@ -0,0 +1,58 @@
+import TagArchiveClient from '@/components/views/TagArchiveClient'
+import { buildLocalizedListPageMetadata } from '@/lib/reactpress/siteMetadata'
+import { generateTagStaticParams } from '@/lib/reactpress/staticParams'
+import {
+  fetchTagArchivePageProps,
+  themeApi,
+  withApiRetry,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+import type { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+
+export const revalidate = 60
+
+export async function generateStaticParams() {
+  return generateTagStaticParams()
+}
+
+interface PageProps {
+  params: Promise<{ tag: string }>
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { tag } = await params
+  const tagValue = decodeURIComponent(tag)
+
+  try {
+    const data = await withApiRetry(() => fetchTagArchivePageProps(themeApi, tagValue))
+    const label = data.tag?.label || tagValue
+    return buildLocalizedListPageMetadata(
+      'pageTitleTag',
+      { label },
+      {
+        path: `/tag/${encodeURIComponent(tagValue)}`,
+      }
+    )
+  } catch {
+    return buildLocalizedListPageMetadata(
+      'pageTitleTag',
+      { label: tagValue },
+      {
+        path: `/tag/${encodeURIComponent(tagValue)}`,
+      }
+    )
+  }
+}
+
+export default async function TagArchivePage({ params }: PageProps) {
+  const { tag } = await params
+  const tagValue = decodeURIComponent(tag)
+
+  try {
+    const data = await withApiRetry(() => fetchTagArchivePageProps(themeApi, tagValue))
+    return <TagArchiveClient initialArticles={data.articles} total={data.total} tag={data.tag} />
+  } catch (error) {
+    console.error('[reactpress-theme-starter] tag archive fetch failed', error)
+    notFound()
+  }
+}

package/app/tags/page.tsx

@@ -0,0 +1,18 @@
+import TagsClient from '@/components/views/TagsClient'
+import { loadAppBootstrap } from '@/lib/reactpress/bootstrap'
+import { buildLocalizedListPageMetadata } from '@/lib/reactpress/siteMetadata'
+import type { ITag } from '@fecommunity/reactpress-toolkit/types'
+import type { Metadata } from 'next'
+
+export const revalidate = 60
+
+export async function generateMetadata(): Promise<Metadata> {
+  return buildLocalizedListPageMetadata('tagTitle', undefined, { path: '/tags' })
+}
+
+export default async function TagsPage() {
+  const bootstrap = await loadAppBootstrap('/tags')
+  const tags = (bootstrap.tags ?? []) as ITag[]
+
+  return <TagsClient tags={tags} />
+}

package/app/template.tsx

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react'
+
+/** Re-mounts on navigation — drives page enter animation. */
+export default function Template({ children }: { children: ReactNode }) {
+  return <div className="rp-page-enter">{children}</div>
+}

package/components/article/ArchiveBanner.tsx

@@ -0,0 +1,40 @@
+import ThemeImage from '@/components/shared/ThemeImage'
+import type { ReactNode } from 'react'
+
+interface ArchiveBannerProps {
+  title: ReactNode
+  subtitle: ReactNode
+  imageUrl: string
+  isBrandFallback?: boolean
+  className?: string
+}
+
+export default function ArchiveBanner({
+  title,
+  subtitle,
+  imageUrl,
+  isBrandFallback = false,
+  className = '',
+}: ArchiveBannerProps) {
+  return (
+    <div
+      className={`rp-archive-banner rp-cover-zoom-host mb-5 h-[200px] w-full overflow-hidden rounded-xl bg-[var(--bg-second)] text-center shadow-[var(--box-shadow)] ring-1 ring-black/5 md:h-[280px] dark:ring-white/5 ${className}`}
+    >
+      <ThemeImage
+        src={imageUrl}
+        alt=""
+        fill
+        sizes="100vw"
+        className={`rp-cover-zoom ${isBrandFallback ? 'object-contain' : 'object-cover'} object-center`}
+      />
+      <div className="rp-archive-banner__content">
+        <p className="m-0 mt-12 text-2xl font-medium text-[var(--font-color-base,#fff)] [text-shadow:0_1px_3px_rgba(0,0,0,0.45)] md:mt-20 md:text-[2rem]">
+          {title}
+        </p>
+        <p className="mt-3 mb-0 text-lg text-white/85 [text-shadow:0_1px_2px_rgba(0,0,0,0.4)] md:text-2xl">
+          {subtitle}
+        </p>
+      </div>
+    </div>
+  )
+}

package/components/article/ArticleActionsBar.tsx

@@ -0,0 +1,53 @@
+'use client'
+
+import BookmarkWidget from '@/components/widgets/BookmarkWidget'
+import LikesWidget from '@/components/widgets/LikesWidget'
+import { COMMENT_DOM_ID } from '@/lib/utils/comment'
+import { useLocale } from '@fecommunity/reactpress-toolkit/ui'
+
+interface ArticleActionsBarProps {
+  articleId: string
+  likes: number
+  likesApi: (id: string, type: 'like' | 'dislike') => Promise<number>
+  showCommentLink?: boolean
+}
+
+export default function ArticleActionsBar({
+  articleId,
+  likes,
+  likesApi,
+  showCommentLink = false,
+}: ArticleActionsBarProps) {
+  const { t } = useLocale()
+
+  return (
+    <div className="rp-article-actions-bar">
+      <LikesWidget defaultCount={likes} id={articleId} api={likesApi} variant="inline" />
+      <BookmarkWidget id={articleId} variant="inline" />
+      {showCommentLink ? (
+        <button
+          type="button"
+          className="rp-action-btn rp-action-btn--inline"
+          aria-label={t('comment')}
+          onClick={() => {
+            document.getElementById(COMMENT_DOM_ID)?.scrollIntoView({ behavior: 'smooth' })
+          }}
+        >
+          <span className="rp-action-btn__icon" aria-hidden>
+            <svg
+              viewBox="0 0 24 24"
+              width="20"
+              height="20"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.8"
+            >
+              <path d="M21 15a4 4 0 0 1-4 4H8l-5 3V7a4 4 0 0 1 4-4h10a4 4 0 0 1 4 4z" />
+            </svg>
+          </span>
+          <span className="rp-action-btn__label">{t('comment')}</span>
+        </button>
+      ) : null}
+    </div>
+  )
+}

package/components/article/ArticleCarousel.tsx

@@ -0,0 +1,237 @@
+'use client'
+
+import { resolveImageUrl, type CarouselArticle } from '@fecommunity/reactpress-toolkit/theme'
+import { useLocale } from '@fecommunity/reactpress-toolkit/ui'
+import { LocaleTime } from '@fecommunity/reactpress-toolkit/ui/content'
+import Link from '@/components/shared/Link'
+import ThemeImage from '@/components/shared/ThemeImage'
+import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties } from 'react'
+
+const AUTOPLAY_MS = 5000
+
+interface ArticleCarouselProps {
+  articles?: CarouselArticle[]
+}
+
+function ChevronIcon({ direction }: { direction: 'left' | 'right' }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={16}
+      height={16}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      {direction === 'left' ? <path d="m15 18-6-6 6-6" /> : <path d="m9 18 6-6-6-6" />}
+    </svg>
+  )
+}
+
+export default function ArticleCarousel({ articles = [] }: ArticleCarouselProps) {
+  const { t, locale } = useLocale()
+  const slides = useMemo(
+    () => (articles || []).filter((article) => article.cover).slice(0, 6),
+    [articles]
+  )
+  const slideIdsKey = useMemo(() => slides.map((article) => article.id).join(','), [slides])
+  const [active, setActive] = useState(0)
+  const [loadedSlides, setLoadedSlides] = useState<Set<number>>(() => new Set([0]))
+  const [paused, setPaused] = useState(false)
+  const [progressKey, setProgressKey] = useState(0)
+  const timerRef = useRef<number | null>(null)
+
+  const clearAutoplay = useCallback(() => {
+    if (timerRef.current !== null) {
+      window.clearInterval(timerRef.current)
+      timerRef.current = null
+    }
+  }, [])
+
+  const goTo = useCallback(
+    (index: number) => {
+      if (slides.length <= 1) return
+      const normalized = ((index % slides.length) + slides.length) % slides.length
+      setActive(normalized)
+      setProgressKey((k) => k + 1)
+    },
+    [slides.length]
+  )
+
+  const goPrev = useCallback(() => goTo(active - 1), [active, goTo])
+  const goNext = useCallback(() => goTo(active + 1), [active, goTo])
+
+  useEffect(() => {
+    setLoadedSlides((prev) => {
+      if (prev.has(active)) return prev
+      const next = new Set(prev)
+      next.add(active)
+      return next
+    })
+  }, [active])
+
+  useEffect(() => {
+    setActive(0)
+    setLoadedSlides(new Set([0]))
+    setProgressKey((k) => k + 1)
+  }, [slideIdsKey])
+
+  useEffect(() => {
+    clearAutoplay()
+    if (slides.length <= 1 || paused) return undefined
+
+    timerRef.current = window.setInterval(() => {
+      setActive((current) => (current + 1) % slides.length)
+      setProgressKey((k) => k + 1)
+    }, AUTOPLAY_MS)
+
+    return clearAutoplay
+  }, [clearAutoplay, paused, slideIdsKey, slides.length])
+
+  if (!slides.length) return null
+
+  const showControls = slides.length > 1
+  const navBtnClass =
+    'rp-carousel-nav absolute top-1/2 z-20 flex h-9 w-9 -translate-y-1/2 cursor-pointer items-center justify-center rounded-full p-0 text-white transition-all duration-300 hover:scale-105 hover:bg-white/22 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white/80 md:opacity-0 md:group-hover/carousel:opacity-100 md:group-focus-within/carousel:opacity-100'
+
+  return (
+    <section
+      className={`rp-carousel group/carousel relative isolate overflow-hidden rounded-xl bg-[var(--bg-second)] shadow-[var(--box-shadow)] ring-1 ring-black/5 dark:ring-white/5${paused ? 'is-paused' : ''}`}
+      aria-roledescription="carousel"
+      aria-label={t('recommendToReading')}
+      style={{ '--rp-autoplay-ms': `${AUTOPLAY_MS}ms` } as CSSProperties}
+      onMouseEnter={() => setPaused(true)}
+      onMouseLeave={() => setPaused(false)}
+      onFocusCapture={() => setPaused(true)}
+      onBlurCapture={(event) => {
+        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
+          setPaused(false)
+        }
+      }}
+    >
+      <div
+        className="relative h-[320px] min-[1360px]:h-[480px] sm:h-[340px] md:h-[300px] lg:h-[380px] xl:h-[420px]"
+        aria-live="polite"
+      >
+        {slides.map((article, index) => {
+          const coverSrc = resolveImageUrl(article.cover, index === 0 ? 'medium' : 'thumb')
+          const isActive = index === active
+          const shouldLoadImage = loadedSlides.has(index)
+
+          return (
+            <article
+              key={article.id}
+              className={`rp-carousel-slide absolute inset-0 overflow-hidden ${isActive ? 'is-active' : ''}`}
+              style={{ pointerEvents: isActive ? 'auto' : 'none' }}
+              aria-hidden={!isActive}
+            >
+              {shouldLoadImage ? (
+                <ThemeImage
+                  key={isActive ? `cover-${progressKey}` : article.id}
+                  src={coverSrc}
+                  alt=""
+                  fill
+                  sizes="(max-width: 768px) 100vw, 1200px"
+                  className="rp-cover-zoom rp-carousel-cover-motion bg-[var(--bg-second)] object-contain object-center"
+                  priority={index === 0}
+                  loading={index === 0 ? 'eager' : 'lazy'}
+                />
+              ) : (
+                <div className="absolute inset-0 bg-[var(--bg-second)]" aria-hidden />
+              )}
+
+              <div
+                className="rp-carousel-overlay pointer-events-none absolute inset-0"
+                aria-hidden
+              />
+
+              <Link
+                href={`/article/${article.id}`}
+                tabIndex={isActive ? 0 : -1}
+                className="absolute inset-0 z-10 flex flex-col justify-end no-underline"
+              >
+                <div
+                  key={isActive ? `${article.id}-content` : `${article.id}-hidden`}
+                  className={`rp-carousel-caption px-5 pt-16 pb-8 md:px-7 md:pb-9 lg:px-8 ${
+                    isActive ? 'rp-carousel-text-enter' : 'opacity-0'
+                  }`}
+                >
+                  <div className="min-w-0">
+                    <h2 className="m-0 mb-2 line-clamp-2 max-w-xl text-[1.05rem] leading-snug font-semibold tracking-tight text-white md:max-w-2xl md:text-xl lg:text-[1.3rem]">
+                      {article.title}
+                    </h2>
+                    <p className="m-0 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-white/75 md:text-[0.8125rem]">
+                      <LocaleTime date={article.publishAt} timeago locale={locale} />
+                      <span className="text-white/40" aria-hidden>
+                        ·
+                      </span>
+                      <span>
+                        {article.views} {t('readingCountTemplate')}
+                      </span>
+                    </p>
+                  </div>
+                </div>
+              </Link>
+            </article>
+          )
+        })}
+      </div>
+
+      {showControls ? (
+        <>
+          <button
+            type="button"
+            className={`${navBtnClass} left-3 opacity-90 max-md:left-2.5`}
+            aria-label={t('carouselPrev')
+              .replace('{current}', String(active + 1))
+              .replace('{total}', String(slides.length))}
+            onClick={goPrev}
+          >
+            <ChevronIcon direction="left" />
+          </button>
+          <button
+            type="button"
+            className={`${navBtnClass} right-3 opacity-90 max-md:right-2.5`}
+            aria-label={t('carouselNext')
+              .replace('{current}', String(active + 1))
+              .replace('{total}', String(slides.length))}
+            onClick={goNext}
+          >
+            <ChevronIcon direction="right" />
+          </button>
+
+          <div
+            className="absolute right-5 bottom-3.5 z-20 hidden items-center gap-1 md:bottom-9 md:flex lg:right-8"
+            role="tablist"
+            aria-label={t('recommendToReading')}
+          >
+            {slides.map((article, index) => {
+              const isDotActive = index === active
+              return (
+                <button
+                  key={article.id}
+                  type="button"
+                  role="tab"
+                  aria-selected={isDotActive}
+                  aria-label={`${index + 1} / ${slides.length}`}
+                  className="flex min-h-6 min-w-6 cursor-pointer items-center justify-center border-0 bg-transparent p-1"
+                  onClick={() => goTo(index)}
+                >
+                  <span className={`rp-carousel-dot ${isDotActive ? 'is-active h-1.5' : ''}`} />
+                </button>
+              )
+            })}
+          </div>
+
+          <div className="rp-carousel-progress-track absolute right-0 bottom-0 left-0 z-20">
+            <div key={progressKey} className="rp-carousel-progress-meteor" aria-hidden />
+          </div>
+        </>
+      ) : null}
+    </section>
+  )
+}

package/components/article/ArticleCopyrightBar.tsx

@@ -0,0 +1,128 @@
+'use client'
+
+import Link from '@/components/shared/Link'
+import ThemeImage from '@/components/shared/ThemeImage'
+import { getRandomColor } from '@/lib/utils/comment'
+import { useSiteCatalog } from '@fecommunity/reactpress-toolkit/theme'
+import { useLocale } from '@fecommunity/reactpress-toolkit/ui'
+import { LocaleTime } from '@fecommunity/reactpress-toolkit/ui/content'
+import { resolveImageUrl, useSiteSetting } from '@fecommunity/reactpress-toolkit/theme'
+
+const CC_LICENSE_URL = 'https://creativecommons.org/licenses/by-nc/3.0/cn/deed.zh'
+
+interface ArticleCopyrightBarProps {
+  publishAt: string
+  className?: string
+}
+
+function isImageLogo(logo: string) {
+  return (
+    logo.startsWith('http') ||
+    logo.startsWith('/') ||
+    /\.(svg|png|jpe?g|gif|webp)(\?.*)?$/i.test(logo)
+  )
+}
+
+function AuthorAvatar({ name, logo }: { name: string; logo?: string }) {
+  const initial = name.trim().charAt(0).toUpperCase() || 'A'
+
+  if (logo && logo.includes('<')) {
+    return (
+      <span
+        className="rp-article-author-avatar__brand"
+        dangerouslySetInnerHTML={{ __html: logo }}
+      />
+    )
+  }
+
+  if (logo && isImageLogo(logo)) {
+    return (
+      <ThemeImage
+        src={resolveImageUrl(logo, 'medium')}
+        alt=""
+        width={48}
+        height={48}
+        className="rp-article-author-avatar__img"
+      />
+    )
+  }
+
+  return (
+    <span
+      className="rp-article-author-avatar__fallback"
+      style={{ backgroundColor: getRandomColor(name) }}
+      aria-hidden
+    >
+      {initial}
+    </span>
+  )
+}
+
+export default function ArticleCopyrightBar({
+  publishAt,
+  className = '',
+}: ArticleCopyrightBarProps) {
+  const { t } = useLocale()
+  const { locale } = useSiteCatalog()
+  const setting = useSiteSetting()
+
+  const authorName = setting.systemTitle?.trim() || 'ReactPress'
+  const authorBio = setting.systemSubTitle?.trim()
+  const authorLogo = setting.systemLogo?.trim()
+
+  return (
+    <div className={`rp-article-author-footer ${className}`.trim()}>
+      <div className="rp-article-author-panel">
+        <div className="rp-article-author-main">
+          <Link href="/" className="rp-article-author-avatar" aria-label={authorName}>
+            <AuthorAvatar name={authorName} logo={authorLogo} />
+          </Link>
+
+          <div className="rp-article-author-info">
+            <span className="rp-article-author-label">{locale === 'zh' ? '作者' : 'Author'}</span>
+            <Link href="/" className="rp-article-author-name">
+              {authorName}
+            </Link>
+            {authorBio ? <p className="rp-article-author-bio">{authorBio}</p> : null}
+          </div>
+
+          <Link href="/" className="rp-article-author-cta">
+            {t('home')}
+            <svg
+              viewBox="0 0 24 24"
+              width="14"
+              height="14"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              aria-hidden
+            >
+              <path d="M5 12h14M13 6l6 6-6 6" strokeLinecap="round" strokeLinejoin="round" />
+            </svg>
+          </Link>
+        </div>
+
+        <div className="rp-article-author-meta">
+          <span>
+            {t('publishAt')}
+            <LocaleTime date={publishAt} locale={locale} />
+          </span>
+          <span className="rp-article-author-meta__sep" aria-hidden>
+            ·
+          </span>
+          <span>
+            {t('copyrightInfo')}
+            <a
+              href={CC_LICENSE_URL}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="rp-article-author-license"
+            >
+              {t('copyrightContent')}
+            </a>
+          </span>
+        </div>
+      </div>
+    </div>
+  )
+}

package/components/article/ArticleEndBar.tsx

@@ -0,0 +1,19 @@
+'use client'
+
+import BookmarkWidget from '@/components/widgets/BookmarkWidget'
+import LikesWidget from '@/components/widgets/LikesWidget'
+
+interface ArticleEndBarProps {
+  articleId: string
+  likes: number
+  likesApi: (id: string, type: 'like' | 'dislike') => Promise<number>
+}
+
+export default function ArticleEndBar({ articleId, likes, likesApi }: ArticleEndBarProps) {
+  return (
+    <div className="rp-article-end-bar">
+      <LikesWidget defaultCount={likes} id={articleId} api={likesApi} variant="inline" />
+      <BookmarkWidget id={articleId} variant="inline" />
+    </div>
+  )
+}

package/components/article/ArticleFeedSection.tsx

@@ -0,0 +1,59 @@
+'use client'
+
+import CategoryMenu from '@/components/article/CategoryMenu'
+import LoadMore from '@/components/article/LoadMore'
+import { useLocale } from '@fecommunity/reactpress-toolkit/ui'
+import { useSiteCatalog } from '@fecommunity/reactpress-toolkit/theme'
+import type { ReactNode } from 'react'
+
+interface ArticleFeedSectionProps {
+  children: ReactNode
+  pageStart?: number
+  loadMore: (page: number) => void | Promise<void>
+  hasMore: boolean
+  showCategoryMenu?: boolean
+}
+
+/** Shared home/category article list block — matches twentytwentyfive `leftWrap`. */
+export default function ArticleFeedSection({
+  children,
+  pageStart = 1,
+  loadMore,
+  hasMore,
+  showCategoryMenu = true,
+}: ArticleFeedSectionProps) {
+  const { t } = useLocale()
+  const { categories } = useSiteCatalog()
+
+  return (
+    <div className="rp-page-enter-delayed w-full overflow-hidden rounded-xl">
+      {showCategoryMenu ? (
+        <header className="overflow-hidden rounded-t-xl shadow-[var(--box-shadow)] ring-1 ring-black/5 dark:ring-white/5">
+          <CategoryMenu categories={categories as Array<{ value: string; label: string }>} />
+        </header>
+      ) : null}
+      <main className="mb-16 w-full pt-4 [&_.rp-article-list]:w-full [&_.rp-article-list]:rounded-none [&_.rp-article-list]:shadow-none">
+        <LoadMore
+          pageStart={pageStart}
+          loadMore={loadMore}
+          hasMore={hasMore}
+          loader={
+            <div
+              className="loading flex items-center justify-center gap-2 py-8 text-sm text-[var(--second-text-color)]"
+              key={0}
+            >
+              <span className="rp-load-indicator" aria-hidden>
+                <span />
+                <span />
+                <span />
+              </span>
+              {t('gettingArticle')}
+            </div>
+          }
+        >
+          {children}
+        </LoadMore>
+      </main>
+    </div>
+  )
+}