@xexr/blog-platform 1.0.6 → 1.0.8

package/dist/app/blog/page.tsx

@@ -3,6 +3,7 @@ import Link from "next/link";
 import Image from "next/image";
 import {
   type PublishedArticle,
+  type PublishedAuthor,
   type PublishedSite,
 } from "../../types/contracts";
 import { cn } from "../../lib/utils";
@@ -198,7 +199,10 @@ function ArticlePreview({
             <div className="text-muted-foreground flex flex-wrap items-center gap-x-3 gap-y-1 text-sm">
               {article.author && (
                 <>
-                  <span className="font-medium">{article.author.name}</span>
+                  <span className="inline-flex items-center gap-2 font-medium">
+                    <AuthorAvatar author={article.author} size="sm" />
+                    {article.author.name}
+                  </span>
                   <span className="text-border">•</span>
                 </>
               )}
@@ -218,6 +222,19 @@ function ArticlePreview({
                 {article.excerpt}
               </p>
             )}
+
+            {(article.topics ?? []).length > 0 && (
+              <div className="flex flex-wrap gap-2">
+                {(article.topics ?? []).map((topic) => (
+                  <span
+                    key={topic.id}
+                    className="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>
+                ))}
+              </div>
+            )}
           </div>
         </div>
 
@@ -249,12 +266,28 @@ function ArticlePreview({
                   {article.excerpt}
                 </p>
               )}
+
+              {(article.topics ?? []).length > 0 && (
+                <div className="flex flex-wrap gap-2">
+                  {(article.topics ?? []).map((topic) => (
+                    <span
+                      key={topic.id}
+                      className="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>
+                  ))}
+                </div>
+              )}
             </div>
 
             <div className="text-muted-foreground flex flex-wrap items-center gap-x-3 gap-y-1 text-sm">
               {article.author && (
                 <>
-                  <span className="font-medium">{article.author.name}</span>
+                  <span className="inline-flex items-center gap-2 font-medium">
+                    <AuthorAvatar author={article.author} size="sm" />
+                    {article.author.name}
+                  </span>
                   <span className="text-border">•</span>
                 </>
               )}
@@ -275,6 +308,54 @@ function ArticlePreview({
   );
 }
 
+function AuthorAvatar({
+  author,
+  size,
+}: {
+  author: PublishedAuthor;
+  size: "sm" | "md";
+}) {
+  const sizeClass = size === "md" ? "h-9 w-9 text-sm" : "h-6 w-6 text-xs";
+  const initials = getAuthorInitials(author.name);
+
+  if (author.avatarUrl) {
+    return (
+      <Image
+        src={author.avatarUrl}
+        alt={author.name}
+        width={size === "md" ? 36 : 24}
+        height={size === "md" ? 36 : 24}
+        className={cn("shrink-0 rounded-full object-cover", sizeClass)}
+        loading="lazy"
+      />
+    );
+  }
+
+  return (
+    <span
+      className={cn(
+        "bg-muted inline-flex shrink-0 items-center justify-center rounded-full font-medium",
+        sizeClass,
+      )}
+      aria-hidden="true"
+    >
+      {initials}
+    </span>
+  );
+}
+
+function getAuthorInitials(name: string): string {
+  const initials = name
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase())
+    .join("");
+
+  return initials || "?";
+}
+
 /**
  * Generate metadata for the blog home page for SEO optimization.
  * This function should be used in the Next.js metadata API.

package/dist/components/ArticleReadingProgress.tsx

@@ -0,0 +1,208 @@
+import {
+  formatTableOfContentsSummary,
+  getTocItemState,
+  type TocItem,
+} from "../lib/article-ui";
+
+interface ArticleReadingProgressProps {
+  items: TocItem[];
+  contentId: string;
+  variant: "mobile" | "desktop";
+  showProgress?: boolean;
+}
+
+export function ArticleReadingProgress({
+  items,
+  contentId,
+  variant,
+  showProgress = true,
+}: ArticleReadingProgressProps) {
+  const activeItemId = items[0]?.id ?? null;
+
+  return (
+    <>
+      {showProgress && (
+        <div
+          data-blog-reading-progress={contentId}
+          className="fixed inset-x-0 top-0 z-50 h-1 origin-left bg-[var(--blog-accent)] motion-safe:transition-transform"
+          style={{ transform: "scaleX(0)" }}
+          role="progressbar"
+          aria-label="Reading progress"
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-valuenow={0}
+          suppressHydrationWarning
+        />
+      )}
+
+      <ArticleTableOfContents
+        items={items}
+        activeItemId={activeItemId}
+        variant={variant}
+      />
+
+      {showProgress && (
+        <script
+          dangerouslySetInnerHTML={{
+            __html: getReadingProgressScript(contentId, items),
+          }}
+        />
+      )}
+    </>
+  );
+}
+
+function ArticleTableOfContents({
+  items,
+  activeItemId,
+  variant,
+}: {
+  items: TocItem[];
+  activeItemId: string | null;
+  variant: "mobile" | "desktop";
+}) {
+  if (items.length === 0) {
+    return null;
+  }
+
+  const list = (
+    <ul className="space-y-2 text-sm">
+      {items.map((item) => {
+        const itemState = getTocItemState(item.id, activeItemId);
+
+        return (
+          <li key={item.id} className={item.level === 3 ? "pl-4" : undefined}>
+            <a
+              href={`#${item.id}`}
+              aria-current={itemState.ariaCurrent}
+              data-blog-toc-link={item.id}
+              data-active={itemState.isActive ? "true" : "false"}
+              suppressHydrationWarning
+              className="text-muted-foreground hover:text-[var(--blog-text-accent)] data-[active=true]:border-[var(--blog-accent)] data-[active=true]:text-[var(--blog-text-accent)] block border-l-2 border-transparent pl-3 leading-snug transition-colors"
+            >
+              {item.text}
+            </a>
+          </li>
+        );
+      })}
+    </ul>
+  );
+
+  if (variant === "mobile") {
+    return (
+      <details className="group mb-6 rounded-2xl border border-[var(--blog-accent-border)] bg-[var(--blog-accent-bg)] lg:hidden">
+        <summary className="text-foreground flex cursor-pointer list-none items-center justify-between gap-3 px-4 py-3 text-sm font-semibold [&::-webkit-details-marker]:hidden">
+          <span>On this page</span>
+          <span className="text-muted-foreground flex items-center gap-2 text-xs font-medium">
+            {formatTableOfContentsSummary(items.length)}
+            <span
+              className="text-[var(--blog-text-accent)] transition-transform group-open:rotate-180"
+              aria-hidden="true"
+            >
+              ↓
+            </span>
+          </span>
+        </summary>
+        <nav
+          aria-label="Table of contents"
+          className="border-t border-[var(--blog-accent-border)] px-4 py-4"
+        >
+          {list}
+        </nav>
+      </details>
+    );
+  }
+
+  return (
+    <aside className="hidden lg:block">
+      <nav
+        aria-label="Table of contents"
+        className="sticky top-24 max-h-[calc(100vh-8rem)] overflow-y-auto border-l border-border pl-5"
+      >
+        <p className="text-muted-foreground mb-3 text-xs font-semibold tracking-wider uppercase">
+          On this page
+        </p>
+        {list}
+      </nav>
+    </aside>
+  );
+}
+
+function getReadingProgressScript(contentId: string, items: TocItem[]): string {
+  return `
+(() => {
+  const contentId = ${JSON.stringify(contentId)};
+  const itemIds = ${JSON.stringify(items.map((item) => item.id))};
+  const progressElement = document.querySelector('[data-blog-reading-progress="' + contentId + '"]');
+  let animationFrameId = 0;
+  let pendingHashItemId = decodeURIComponent(window.location.hash.replace(/^#/, ''));
+
+  const normalizeProgress = (value) => {
+    if (!Number.isFinite(value)) return 0;
+    return Math.min(100, Math.max(0, value));
+  };
+
+  const setActiveItem = (activeItemId) => {
+    const tocLinks = Array.from(document.querySelectorAll('[data-blog-toc-link]'));
+
+    for (const link of tocLinks) {
+      const isActive = link.getAttribute('data-blog-toc-link') === activeItemId;
+      link.setAttribute('data-active', isActive ? 'true' : 'false');
+      if (isActive) {
+        link.setAttribute('aria-current', 'location');
+      } else {
+        link.removeAttribute('aria-current');
+      }
+    }
+  };
+
+  const updateScrollState = () => {
+    const contentElement = document.getElementById(contentId);
+    if (!contentElement) return;
+
+    const contentRect = contentElement.getBoundingClientRect();
+    const scrollTop = window.scrollY;
+    const contentTop = contentRect.top + scrollTop;
+    const readableDistance = contentElement.offsetHeight - window.innerHeight;
+    const nextProgress = readableDistance <= 0
+      ? scrollTop >= contentTop ? 100 : 0
+      : ((scrollTop - contentTop) / readableDistance) * 100;
+    const progress = normalizeProgress(nextProgress);
+
+    if (progressElement) {
+      progressElement.style.transform = 'scaleX(' + progress / 100 + ')';
+      progressElement.setAttribute('aria-valuenow', String(Math.round(progress)));
+    }
+
+    const headings = itemIds
+      .map((id) => document.getElementById(id))
+      .filter(Boolean);
+    if (pendingHashItemId && itemIds.includes(pendingHashItemId)) {
+      setActiveItem(pendingHashItemId);
+      pendingHashItemId = '';
+      return;
+    }
+
+    const activeOffset = Math.max(160, Math.round(window.innerHeight * 0.33));
+    const activeHeading = headings
+      .filter((heading) => heading.getBoundingClientRect().top <= activeOffset)
+      .at(-1) || headings[0] || null;
+
+    setActiveItem(activeHeading ? activeHeading.id : null);
+  };
+
+  const scheduleUpdate = () => {
+    window.cancelAnimationFrame(animationFrameId);
+    animationFrameId = window.requestAnimationFrame(updateScrollState);
+  };
+
+  scheduleUpdate();
+  window.addEventListener('scroll', scheduleUpdate, { passive: true });
+  window.addEventListener('resize', scheduleUpdate);
+  window.addEventListener('hashchange', () => {
+    pendingHashItemId = decodeURIComponent(window.location.hash.replace(/^#/, ''));
+    scheduleUpdate();
+  });
+})();
+`;
+}

package/dist/components/ArticleTopActions.tsx

@@ -0,0 +1,179 @@
+"use client";
+
+import React from "react";
+import { Check, Copy, Share2 } from "lucide-react";
+
+import { cn } from "../lib/utils";
+
+type ClipboardLike = Pick<Clipboard, "writeText">;
+
+interface CopyFallbackDocument {
+  body: Pick<HTMLElement, "appendChild">;
+  createElement: (tagName: "textarea") => HTMLTextAreaElement;
+  execCommand: (commandId: "copy") => boolean;
+}
+
+interface NavigatorLike {
+  clipboard?: ClipboardLike;
+  share?: (data: ShareData) => Promise<void>;
+}
+
+interface ArticleTopActionsProps {
+  title: string;
+  url: string;
+  className?: string;
+  size?: "sm" | "md";
+}
+
+export function resolveShareUrl(url: string, currentHref?: string): string {
+  try {
+    return new URL(url).href;
+  } catch {
+    if (!currentHref) return url;
+  }
+
+  try {
+    return new URL(url, currentHref).href;
+  } catch {
+    return url;
+  }
+}
+
+export async function copyArticleLink(
+  url: string,
+  clipboard: ClipboardLike | undefined = globalThis.navigator?.clipboard,
+  fallbackDocument: CopyFallbackDocument | undefined =
+    typeof document === "undefined" ? undefined : document,
+): Promise<void> {
+  if (clipboard) {
+    try {
+      await clipboard.writeText(url);
+      return;
+    } catch {
+      // Fall back below for browser contexts that expose clipboard but deny it.
+    }
+  }
+
+  if (!fallbackDocument) {
+    throw new Error("Clipboard API is unavailable");
+  }
+
+  const textarea = fallbackDocument.createElement("textarea");
+  textarea.value = url;
+  textarea.setAttribute("readonly", "");
+  textarea.style.position = "fixed";
+  textarea.style.left = "-9999px";
+
+  fallbackDocument.body.appendChild(textarea);
+  textarea.select();
+
+  try {
+    const copied = fallbackDocument.execCommand("copy");
+    if (!copied) {
+      throw new Error("Copy command failed");
+    }
+  } finally {
+    textarea.remove();
+  }
+}
+
+export async function shareArticle(
+  article: { title: string; url: string },
+  navigatorLike: NavigatorLike | undefined = globalThis.navigator,
+): Promise<"shared" | "copied"> {
+  if (navigatorLike?.share) {
+    await navigatorLike.share({
+      title: article.title,
+      url: article.url,
+    });
+    return "shared";
+  }
+
+  await copyArticleLink(article.url, navigatorLike?.clipboard);
+  return "copied";
+}
+
+export default function ArticleTopActions({
+  title,
+  url,
+  className,
+  size = "md",
+}: ArticleTopActionsProps) {
+  const [copied, setCopied] = React.useState(false);
+  const [sharing, setSharing] = React.useState(false);
+  const resolvedUrl = React.useMemo(
+    () =>
+      resolveShareUrl(
+        url,
+        typeof window === "undefined" ? undefined : window.location.href,
+      ),
+    [url],
+  );
+
+  React.useEffect(() => {
+    if (!copied) return;
+
+    const timeout = window.setTimeout(() => setCopied(false), 2000);
+    return () => window.clearTimeout(timeout);
+  }, [copied]);
+
+  async function handleCopy() {
+    await copyArticleLink(resolvedUrl);
+    setCopied(true);
+  }
+
+  async function handleShare() {
+    setSharing(true);
+    try {
+      const result = await shareArticle({ title, url: resolvedUrl });
+      if (result === "copied") setCopied(true);
+    } finally {
+      setSharing(false);
+    }
+  }
+
+  const buttonClassName =
+    size === "sm"
+      ? "h-8 gap-1.5 px-2.5 text-xs"
+      : "h-9 gap-2 px-3 text-sm";
+  const iconClassName = size === "sm" ? "size-3.5" : "size-4";
+
+  return (
+    <div
+      className={cn(
+        "article-top-actions flex flex-wrap items-center justify-center gap-2",
+        className,
+      )}
+    >
+      <button
+        type="button"
+        aria-label="Copy article link"
+        onClick={handleCopy}
+        className={cn(
+          "text-muted-foreground hover:text-foreground border-border inline-flex items-center justify-center rounded-full border font-medium transition-colors hover:border-[var(--blog-accent-border)] hover:bg-[var(--blog-accent-bg)]",
+          buttonClassName,
+        )}
+      >
+        {copied ? (
+          <Check className={iconClassName} aria-hidden="true" />
+        ) : (
+          <Copy className={iconClassName} aria-hidden="true" />
+        )}
+        <span>{copied ? "Copied" : "Copy link"}</span>
+      </button>
+      <button
+        type="button"
+        aria-label="Share article"
+        onClick={handleShare}
+        disabled={sharing}
+        className={cn(
+          "text-muted-foreground hover:text-foreground border-border inline-flex items-center justify-center rounded-full border font-medium transition-colors hover:border-[var(--blog-accent-border)] hover:bg-[var(--blog-accent-bg)] disabled:cursor-wait disabled:opacity-60",
+          buttonClassName,
+        )}
+      >
+        <Share2 className={iconClassName} aria-hidden="true" />
+        <span>Share</span>
+      </button>
+    </div>
+  );
+}