@xexr/blog-platform 1.0.7 → 1.0.8

package/dist/components/Pagination.tsx

@@ -0,0 +1,236 @@
+import React from "react";
+import { ChevronsLeft, ChevronsRight } from "lucide-react";
+import {
+  Pagination as ShadcnPagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+  PaginationEllipsis,
+} from "./ui/pagination";
+
+export interface PaginationProps {
+  /** Current page number (1-indexed) */
+  currentPage: number;
+  
+  /** Total number of pages */
+  totalPages: number;
+  
+  /** Base URL for pagination links (e.g., "/blog") */
+  baseUrl: string;
+  
+  /** Additional CSS classes */
+  className?: string;
+  
+  /** Maximum number of page links to show around current page */
+  maxVisiblePages?: number;
+  
+  /** Show/hide previous and next buttons */
+  showPrevNext?: boolean;
+  
+  /** Show/hide first and last page links */
+  showFirstLast?: boolean;
+  
+  /** Custom labels for navigation */
+  labels?: {
+    previous?: string;
+    next?: string;
+    first?: string;
+    last?: string;
+  };
+}
+
+/**
+ * Pagination component for blog articles listing.
+ * 
+ * Provides SEO-friendly pagination with proper URL structure,
+ * keyboard navigation, and accessibility features.
+ */
+export default function Pagination({
+  currentPage,
+  totalPages,
+  baseUrl,
+  className,
+  maxVisiblePages = 5,
+  showPrevNext = true,
+  showFirstLast = true,
+}: PaginationProps) {
+  // Don't render pagination if there's only one page or no pages
+  if (totalPages <= 1) {
+    return null;
+  }
+
+  // Calculate visible page range
+  const getVisiblePages = () => {
+    const half = Math.floor(maxVisiblePages / 2);
+    let start = Math.max(1, currentPage - half);
+    const end = Math.min(totalPages, start + maxVisiblePages - 1);
+    
+    // Adjust start if we're near the end
+    if (end - start + 1 < maxVisiblePages) {
+      start = Math.max(1, end - maxVisiblePages + 1);
+    }
+    
+    return { start, end };
+  };
+
+  const { start, end } = getVisiblePages();
+  const pages = Array.from({ length: end - start + 1 }, (_, i) => start + i);
+
+  // Generate URL for a specific page
+  const getPageUrl = (page: number) => {
+    if (page === 1) {
+      return baseUrl;
+    }
+    return `${baseUrl}?page=${page}`;
+  };
+
+  const hasPrevious = currentPage > 1;
+  const hasNext = currentPage < totalPages;
+
+  return (
+    <ShadcnPagination className={className}>
+      <PaginationContent>
+        {/* First Page Link */}
+        {showFirstLast && currentPage > 2 && (
+          <>
+            <PaginationItem>
+              <PaginationLink href={getPageUrl(1)} aria-label="Go to first page">
+                <ChevronsLeft className="h-4 w-4" />
+              </PaginationLink>
+            </PaginationItem>
+            {start > 2 && (
+              <PaginationItem>
+                <PaginationEllipsis />
+              </PaginationItem>
+            )}
+          </>
+        )}
+
+        {/* Previous Page Link */}
+        {showPrevNext && (
+          <PaginationItem>
+            {hasPrevious ? (
+              <PaginationPrevious href={getPageUrl(currentPage - 1)} />
+            ) : (
+              <span className="flex h-9 items-center justify-center gap-1 px-2.5 text-muted-foreground sm:pl-2.5">
+                <span className="hidden sm:block">Previous</span>
+              </span>
+            )}
+          </PaginationItem>
+        )}
+
+        {/* Page Number Links */}
+        {pages.map((page) => (
+          <PaginationItem key={page}>
+            <PaginationLink 
+              href={getPageUrl(page)}
+              isActive={page === currentPage}
+            >
+              {page}
+            </PaginationLink>
+          </PaginationItem>
+        ))}
+
+        {/* Next Page Link */}
+        {showPrevNext && (
+          <PaginationItem>
+            {hasNext ? (
+              <PaginationNext href={getPageUrl(currentPage + 1)} />
+            ) : (
+              <span className="flex h-9 items-center justify-center gap-1 px-2.5 text-muted-foreground sm:pr-2.5">
+                <span className="hidden sm:block">Next</span>
+              </span>
+            )}
+          </PaginationItem>
+        )}
+
+        {/* Last Page Link */}
+        {showFirstLast && currentPage < totalPages - 1 && (
+          <>
+            {end < totalPages - 1 && (
+              <PaginationItem>
+                <PaginationEllipsis />
+              </PaginationItem>
+            )}
+            <PaginationItem>
+              <PaginationLink href={getPageUrl(totalPages)} aria-label="Go to last page">
+                <ChevronsRight className="h-4 w-4" />
+              </PaginationLink>
+            </PaginationItem>
+          </>
+        )}
+      </PaginationContent>
+
+      {/* Screen Reader Info */}
+      <div className="sr-only" aria-live="polite">
+        Page {currentPage} of {totalPages}
+      </div>
+    </ShadcnPagination>
+  );
+}
+
+
+/**
+ * Hook to calculate pagination metadata from URL parameters.
+ * Useful for extracting current page from Next.js searchParams.
+ */
+export function usePagination(
+  searchParams: Record<string, string | string[] | undefined>,
+  itemsPerPage = 10
+) {
+  const pageParam = searchParams.page;
+  const pageString = Array.isArray(pageParam) ? pageParam[0] : pageParam;
+  const currentPage = Math.max(1, parseInt(pageString ?? "1", 10));
+
+  const offset = (currentPage - 1) * itemsPerPage;
+
+  const calculateTotalPages = (totalItems: number) => {
+    return Math.ceil(totalItems / itemsPerPage);
+  };
+
+  return {
+    currentPage,
+    itemsPerPage,
+    offset,
+    calculateTotalPages
+  };
+}
+
+/**
+ * Generate pagination metadata for SEO.
+ * Provides canonical URLs, next/prev relationships for search engines.
+ */
+export function generatePaginationMetadata(
+  currentPage: number,
+  totalPages: number,
+  baseUrl: string,
+  siteUrl?: string
+) {
+  const canonicalUrl = siteUrl 
+    ? `${siteUrl}${currentPage === 1 ? baseUrl : `${baseUrl}?page=${currentPage}`}`
+    : undefined;
+
+  const prevUrl = currentPage > 1 
+    ? siteUrl 
+      ? `${siteUrl}${currentPage === 2 ? baseUrl : `${baseUrl}?page=${currentPage - 1}`}`
+      : undefined
+    : undefined;
+
+  const nextUrl = currentPage < totalPages 
+    ? siteUrl 
+      ? `${siteUrl}${baseUrl}?page=${currentPage + 1}`
+      : undefined
+    : undefined;
+
+  return {
+    alternates: {
+      ...(canonicalUrl && { canonical: canonicalUrl }),
+    },
+    other: {
+      ...(prevUrl && { prev: prevUrl }),
+      ...(nextUrl && { next: nextUrl }),
+    },
+  };
+}

package/dist/components/TopicArchivePages.tsx

@@ -0,0 +1,204 @@
+import React from "react";
+import Link from "next/link";
+import Image from "next/image";
+import { formatDistanceToNow } from "date-fns";
+
+import type { PublishedArticle, PublishedTopic } from "../types/contracts";
+import type { BlogTheme } from "../lib/article-ui";
+import { getBlogThemeStyle } from "../lib/article-ui";
+import { buildBlogPath, normalizeBlogBasePath } from "../lib/urls";
+import { cn } from "../lib/utils";
+import { getAllTopics, getTopicArchive } from "../lib/topics";
+
+interface BlogTopicsIndexPageProps {
+  articles: PublishedArticle[];
+  basePath?: string;
+  title?: string;
+  description?: string;
+  className?: string;
+  theme?: BlogTheme;
+}
+
+interface BlogTopicArchivePageProps {
+  articles: PublishedArticle[];
+  topicSlug: string;
+  basePath?: string;
+  className?: string;
+  theme?: BlogTheme;
+}
+
+export function BlogTopicsIndexPage({
+  articles,
+  basePath = "/blog",
+  title = "Topics",
+  description = "Browse articles by topic.",
+  className,
+  theme,
+}: BlogTopicsIndexPageProps) {
+  const normalizedBasePath = normalizeBlogBasePath(basePath) || "/";
+  const topics = getAllTopics(articles);
+
+  return (
+    <main
+      style={getBlogThemeStyle(theme)}
+      className={cn(
+        "blog-topics-page container mx-auto max-w-5xl px-4 py-8 sm:px-6 sm:py-12 lg:px-8 lg:py-16",
+        className,
+      )}
+    >
+      <header className="mb-10 space-y-3 text-center">
+        <Link
+          href={normalizedBasePath}
+          className="text-muted-foreground hover:text-[var(--blog-accent)] text-sm font-medium transition-colors"
+        >
+          Back to all articles
+        </Link>
+        <h1 className="text-4xl font-semibold tracking-tight text-balance sm:text-5xl">
+          {title}
+        </h1>
+        <p className="text-muted-foreground mx-auto max-w-2xl text-lg text-pretty">
+          {description}
+        </p>
+      </header>
+
+      {topics.length === 0 ? (
+        <p className="text-muted-foreground rounded-2xl border p-8 text-center">
+          No topics have published articles yet.
+        </p>
+      ) : (
+        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {topics.map((topic) => {
+            const count = articles.filter((article) =>
+              (article.topics ?? []).some(
+                (articleTopic) => articleTopic.slug === topic.slug,
+              ),
+            ).length;
+
+            return (
+              <Link
+                key={topic.slug}
+                href={buildBlogPath(normalizedBasePath, `topics/${topic.slug}`)}
+                className="group rounded-2xl border border-[var(--blog-accent-border)] bg-[var(--blog-card-bg)] p-5 transition hover:border-[var(--blog-accent)] hover:no-underline"
+              >
+                <h2 className="group-hover:text-[var(--blog-accent)] text-xl font-semibold transition-colors">
+                  {topic.name}
+                </h2>
+                {topic.description && (
+                  <p className="text-muted-foreground mt-2 line-clamp-3 text-sm leading-relaxed">
+                    {topic.description}
+                  </p>
+                )}
+                <p className="text-muted-foreground mt-4 text-sm">
+                  {count} {count === 1 ? "article" : "articles"}
+                </p>
+              </Link>
+            );
+          })}
+        </div>
+      )}
+    </main>
+  );
+}
+
+export function BlogTopicArchivePage({
+  articles,
+  topicSlug,
+  basePath = "/blog",
+  className,
+  theme,
+}: BlogTopicArchivePageProps) {
+  const normalizedBasePath = normalizeBlogBasePath(basePath) || "/";
+  const archive = getTopicArchive(articles, topicSlug);
+
+  return (
+    <main
+      style={getBlogThemeStyle(theme)}
+      className={cn(
+        "blog-topic-archive-page container mx-auto max-w-5xl px-4 py-8 sm:px-6 sm:py-12 lg:px-8 lg:py-16",
+        className,
+      )}
+    >
+      <header className="mb-10 space-y-3 text-center">
+        <Link
+          href={buildBlogPath(normalizedBasePath, "topics")}
+          className="text-muted-foreground hover:text-[var(--blog-accent)] text-sm font-medium transition-colors"
+        >
+          Back to all topics
+        </Link>
+        <h1 className="text-4xl font-semibold tracking-tight text-balance sm:text-5xl">
+          {archive?.topic.name ?? "Topic not found"}
+        </h1>
+        {archive?.topic.description && (
+          <p className="text-muted-foreground mx-auto max-w-2xl text-lg text-pretty">
+            {archive.topic.description}
+          </p>
+        )}
+      </header>
+
+      {!archive ? (
+        <p className="text-muted-foreground rounded-2xl border p-8 text-center">
+          No published articles were found for this topic.
+        </p>
+      ) : (
+        <div className="grid gap-5 md:grid-cols-2">
+          {archive.articles.map((article) => (
+            <TopicArticleCard
+              key={article.id}
+              article={article}
+              topic={archive.topic}
+              basePath={normalizedBasePath}
+            />
+          ))}
+        </div>
+      )}
+    </main>
+  );
+}
+
+function TopicArticleCard({
+  article,
+  topic,
+  basePath,
+}: {
+  article: PublishedArticle;
+  topic: PublishedTopic;
+  basePath: string;
+}) {
+  const articleUrl = buildBlogPath(basePath, article.slug);
+  const publishedAgo = formatDistanceToNow(new Date(article.publishedAt), {
+    addSuffix: true,
+  });
+
+  return (
+    <Link
+      href={articleUrl}
+      className="group overflow-hidden rounded-2xl border border-[var(--blog-accent-border)] bg-[var(--blog-card-bg)] transition hover:border-[var(--blog-accent)] hover:no-underline"
+    >
+      {article.featuredImage && (
+        <div className="relative aspect-[16/9] overflow-hidden">
+          <Image
+            src={article.featuredImage}
+            alt={article.featuredImageAlt ?? article.title}
+            width={640}
+            height={360}
+            className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
+          />
+        </div>
+      )}
+      <div className="space-y-3 p-5">
+        <span className="inline-flex rounded-full border border-[var(--blog-accent-border)] px-2.5 py-1 text-xs font-medium text-[var(--blog-text-accent)]">
+          {topic.name}
+        </span>
+        <h2 className="group-hover:text-[var(--blog-accent)] text-xl font-semibold text-balance transition-colors">
+          {article.title}
+        </h2>
+        {article.excerpt && (
+          <p className="text-muted-foreground line-clamp-3 text-sm leading-relaxed">
+            {article.excerpt}
+          </p>
+        )}
+        <p className="text-muted-foreground text-sm">{publishedAgo}</p>
+      </div>
+    </Link>
+  );
+}

package/dist/components/ui/badge.tsx

@@ -0,0 +1,36 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "../../lib/utils"
+
+const badgeVariants = cva(
+  "inline-flex items-center rounded-md border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
+  {
+    variants: {
+      variant: {
+        default:
+          "border-transparent bg-primary text-primary-foreground shadow hover:bg-primary/80",
+        secondary:
+          "border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        destructive:
+          "border-transparent bg-destructive text-destructive-foreground shadow hover:bg-destructive/80",
+        outline: "text-foreground",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+export interface BadgeProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof badgeVariants> {}
+
+function Badge({ className, variant, ...props }: BadgeProps) {
+  return (
+    <div className={cn(badgeVariants({ variant }), className)} {...props} />
+  )
+}
+
+export { Badge, badgeVariants }

package/dist/components/ui/button.tsx

@@ -0,0 +1,59 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "../../lib/utils"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
+        outline:
+          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
+        secondary:
+          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",
+        ghost:
+          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2 has-[>svg]:px-3",
+        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
+        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
+        icon: "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function Button({
+  className,
+  variant,
+  size,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"button"> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean
+  }) {
+  const Comp = asChild ? Slot : "button"
+
+  return (
+    <Comp
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Button, buttonVariants }

package/dist/components/ui/card.tsx

@@ -0,0 +1,92 @@
+import * as React from "react"
+
+import { cn } from "../../lib/utils"
+
+function Card({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card"
+      className={cn(
+        "bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-1.5 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn("leading-none font-semibold", className)}
+      {...props}
+    />
+  )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-6", className)}
+      {...props}
+    />
+  )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn("flex items-center px-6 [.border-t]:pt-6", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+}