docusaurus-plugin-album 0.0.0-stage → 0.1.0

package/lib/theme/AlbumMasonryGrid.tsx

@@ -0,0 +1,345 @@
+import Link from '@docusaurus/Link';
+import type React from 'react';
+import { memo, useEffect, useMemo, useRef, useState } from 'react';
+import type { AlbumPostMeta } from '../types';
+import styles from './styles.module.css';
+
+export type { AlbumPostMeta } from '../types';
+
+type Props = {
+  posts: AlbumPostMeta[];
+  onCurrentDateChange?: (year: string, month: string) => void;
+  onScrubberVisibleChange?: (visible: boolean) => void;
+  scrollToYearRef?: React.MutableRefObject<((year: string) => void) | null>;
+};
+
+const BATCH_SIZE = 12;
+
+export function parseDate(post: AlbumPostMeta): {
+  year: string;
+  month: string;
+  displayDate: string;
+} {
+  if (post.year && post.month) {
+    return {
+      year: post.year,
+      month: post.month,
+      displayDate: post.displayDate ?? `${post.year}年 ${post.month}月`,
+    };
+  }
+
+  const permalinkMatch = post.permalink.match(/\/(\d{4})\/(\d{2})\//);
+  if (permalinkMatch) {
+    const year = permalinkMatch[1];
+    const month = String(Number(permalinkMatch[2]));
+    return { year, month, displayDate: `${year}年 ${month}月` };
+  }
+
+  if (post.date) {
+    const parsed = new Date(post.date);
+    if (!Number.isNaN(parsed.getTime())) {
+      const year = `${parsed.getUTCFullYear()}`;
+      const month = `${parsed.getUTCMonth() + 1}`;
+      return { year, month, displayDate: `${year}年 ${month}月` };
+    }
+  }
+
+  return { year: '2026', month: '1', displayDate: '' };
+}
+
+function AlbumMasonryGrid({
+  posts,
+  onCurrentDateChange,
+  onScrubberVisibleChange,
+  scrollToYearRef,
+}: Props) {
+  // 1. Filter out posts without cover and pre-normalize date metadata once
+  const validPosts = useMemo(() => {
+    return posts
+      .filter((p) => Boolean(p.frontMatter?.cover))
+      .map((p) => {
+        if (p.year && p.month && p.displayDate !== undefined) {
+          return p;
+        }
+        const { year, month, displayDate } = parseDate(p);
+        return { ...p, year, month, displayDate };
+      });
+  }, [posts]);
+
+  // 2. Infinite scroll state
+  const [visibleCount, setVisibleCount] = useState(BATCH_SIZE);
+  const sentinelRef = useRef<HTMLDivElement>(null);
+  const gridRef = useRef<HTMLDivElement>(null);
+  const pendingScrollYearRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    const sentinel = sentinelRef.current;
+    if (!sentinel || visibleCount >= validPosts.length) {
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries[0]?.isIntersecting) {
+          setVisibleCount((prev) => Math.min(prev + BATCH_SIZE, validPosts.length));
+        }
+      },
+      { rootMargin: '350px' },
+    );
+
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  }, [validPosts.length, visibleCount]);
+
+  // Handle year jump from TimelineScrubber (auto-expands visibleCount if target year is not yet rendered)
+  useEffect(() => {
+    if (!scrollToYearRef) {
+      return;
+    }
+
+    scrollToYearRef.current = (year: string) => {
+      const targetIdx = validPosts.findIndex((p) => p.year === year);
+      if (targetIdx === -1) {
+        return;
+      }
+
+      const targetPost = validPosts[targetIdx];
+      onCurrentDateChange?.(targetPost.year || year, targetPost.month || '');
+
+      if (targetIdx < visibleCount) {
+        const targetCard = gridRef.current?.querySelector<HTMLElement>(`[data-year="${year}"]`);
+        targetCard?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      } else {
+        pendingScrollYearRef.current = year;
+        setVisibleCount((prev) =>
+          Math.min(validPosts.length, Math.max(prev, targetIdx + BATCH_SIZE)),
+        );
+      }
+    };
+
+    return () => {
+      scrollToYearRef.current = null;
+    };
+  }, [validPosts, visibleCount, onCurrentDateChange, scrollToYearRef]);
+
+  useEffect(() => {
+    if (visibleCount === 0) {
+      return;
+    }
+    const pendingYear = pendingScrollYearRef.current;
+    if (!pendingYear) {
+      return;
+    }
+
+    const targetCard = gridRef.current?.querySelector<HTMLElement>(`[data-year="${pendingYear}"]`);
+    if (targetCard) {
+      pendingScrollYearRef.current = null;
+      requestAnimationFrame(() => {
+        targetCard.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      });
+    }
+  }, [visibleCount]);
+
+  // 3. Responsive column count calculation via matchMedia breakpoints
+  const [columnCount, setColumnCount] = useState(4);
+  useEffect(() => {
+    const mq1200 = window.matchMedia('(min-width: 1200px)');
+    const mq850 = window.matchMedia('(min-width: 850px)');
+    const mq560 = window.matchMedia('(min-width: 560px)');
+
+    const updateCols = () => {
+      if (mq1200.matches) {
+        setColumnCount(4);
+      } else if (mq850.matches) {
+        setColumnCount(3);
+      } else if (mq560.matches) {
+        setColumnCount(2);
+      } else {
+        setColumnCount(1);
+      }
+    };
+
+    updateCols();
+    mq1200.addEventListener('change', updateCols);
+    mq850.addEventListener('change', updateCols);
+    mq560.addEventListener('change', updateCols);
+
+    return () => {
+      mq1200.removeEventListener('change', updateCols);
+      mq850.removeEventListener('change', updateCols);
+      mq560.removeEventListener('change', updateCols);
+    };
+  }, []);
+
+  // 4. Distribute visible items into columns round-robin
+  const currentPosts = useMemo(() => {
+    return validPosts.slice(0, visibleCount);
+  }, [validPosts, visibleCount]);
+
+  const columns = useMemo(() => {
+    const cols: AlbumPostMeta[][] = Array.from({ length: columnCount }, () => []);
+    currentPosts.forEach((post, idx) => {
+      cols[idx % columnCount].push(post);
+    });
+    return cols;
+  }, [currentPosts, columnCount]);
+
+  // 5. Unified scroll listener using per-column O(log N) binary search
+  const lastReportedRef = useRef<{ year: string; month: string; visible: boolean }>({
+    year: '',
+    month: '',
+    visible: false,
+  });
+
+  useEffect(() => {
+    if (!onCurrentDateChange && !onScrubberVisibleChange) {
+      return;
+    }
+
+    let ticking = false;
+    const evaluateScroll = () => {
+      const isVisible = window.scrollY > 120;
+      if (onScrubberVisibleChange && isVisible !== lastReportedRef.current.visible) {
+        lastReportedRef.current.visible = isVisible;
+        onScrubberVisibleChange(isVisible);
+      }
+
+      if (onCurrentDateChange && gridRef.current && currentPosts.length > 0 && columnCount > 0) {
+        const colElements = gridRef.current.children;
+        const viewportCenter = window.innerHeight * 0.35;
+        let bestCard: HTMLElement | null = null;
+        let minDistance = Number.POSITIVE_INFINITY;
+
+        // Within each column, cards are ordered top-to-bottom monotonically, enabling binary search
+        for (let c = 0; c < colElements.length; c += 1) {
+          const cards = colElements[c].children;
+          let low = 0;
+          let high = cards.length - 1;
+
+          while (low <= high) {
+            const mid = (low + high) >> 1;
+            const card = cards[mid] as HTMLElement;
+            const top = card.getBoundingClientRect().top;
+            const distance = Math.abs(top - viewportCenter);
+
+            if (distance < minDistance) {
+              minDistance = distance;
+              bestCard = card;
+            }
+
+            if (top < viewportCenter) {
+              low = mid + 1;
+            } else {
+              high = mid - 1;
+            }
+          }
+        }
+
+        if (bestCard) {
+          const year = bestCard.dataset.year || '';
+          const month = bestCard.dataset.month || '';
+          if (
+            year &&
+            (year !== lastReportedRef.current.year || month !== lastReportedRef.current.month)
+          ) {
+            lastReportedRef.current.year = year;
+            lastReportedRef.current.month = month;
+            onCurrentDateChange(year, month);
+          }
+        }
+      }
+
+      ticking = false;
+    };
+
+    const handleScroll = () => {
+      if (!ticking) {
+        window.requestAnimationFrame(evaluateScroll);
+        ticking = true;
+      }
+    };
+
+    window.addEventListener('scroll', handleScroll, { passive: true });
+    evaluateScroll();
+
+    return () => window.removeEventListener('scroll', handleScroll);
+  }, [currentPosts.length, columnCount, onCurrentDateChange, onScrubberVisibleChange]);
+
+  if (validPosts.length === 0) {
+    return (
+      <div className={styles.endMessage}>
+        <p>目前尚無相簿文章，請新增帶有 cover 封面的相簿 Markdown 筆記。</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.masonryWrapper}>
+      <div ref={gridRef} className={styles.masonryGrid}>
+        {columns.map((colPosts, colIdx) => (
+          <div key={`col-${colPosts[0]?.permalink ?? colIdx}`} className={styles.masonryColumn}>
+            {colPosts.map((post, rowIdx) => {
+              const isAboveFold = rowIdx === 0;
+              return (
+                <Link
+                  key={post.permalink}
+                  to={post.permalink}
+                  className={styles.albumCard}
+                  data-album-card="true"
+                  data-year={post.year}
+                  data-month={post.month}
+                >
+                  <div className={styles.cardImageWrapper}>
+                    <img
+                      src={post.frontMatter.cover}
+                      alt={post.title}
+                      className={styles.cardImage}
+                      loading={isAboveFold ? 'eager' : 'lazy'}
+                      fetchPriority={isAboveFold && colIdx === 0 ? 'high' : undefined}
+                      decoding="async"
+                    />
+
+                    {/* Pinterest Style Hover Overlay */}
+                    <div className={styles.cardOverlay}>
+                      <div className={styles.cardOverlayContent}>
+                        <h2 className={styles.cardTitle}>{post.title}</h2>
+
+                        <div className={styles.cardMetaRow}>
+                          {post.frontMatter.location && (
+                            <span className={styles.pillBadge} title="拍攝地點">
+                              📍 {post.frontMatter.location}
+                            </span>
+                          )}
+                          {post.frontMatter.album_series && (
+                            <span
+                              className={`${styles.pillBadge} ${styles.seriesBadge}`}
+                              title="相簿系列"
+                            >
+                              📁 {post.frontMatter.album_series}
+                            </span>
+                          )}
+                          <span className={styles.cardDate}>{post.displayDate}</span>
+                        </div>
+                      </div>
+                    </div>
+                  </div>
+                </Link>
+              );
+            })}
+          </div>
+        ))}
+      </div>
+
+      {/* Infinite Scroll Sentinel */}
+      {visibleCount < validPosts.length && <div ref={sentinelRef} className={styles.sentinel} />}
+
+      {visibleCount >= validPosts.length && (
+        <div className={styles.endMessage}>
+          <span>✨ 已經瀏覽完所有相簿囉 ✨</span>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default memo(AlbumMasonryGrid);

package/lib/theme/AlbumPostPage.tsx

@@ -0,0 +1,205 @@
+import type { BlogSidebar } from '@docusaurus/plugin-content-blog';
+import { BlogPostProvider, useBlogPost } from '@docusaurus/plugin-content-blog/client';
+import { HtmlClassNameProvider, ThemeClassNames } from '@docusaurus/theme-common';
+import BlogLayout from '@theme/BlogLayout';
+import BlogPostItem from '@theme/BlogPostItem';
+import type { Props } from '@theme/BlogPostPage';
+import BlogPostPageMetadata from '@theme/BlogPostPage/Metadata';
+import BlogPostPageStructuredData from '@theme/BlogPostPage/StructuredData';
+import BlogPostPaginator from '@theme/BlogPostPaginator';
+import ContentVisibility from '@theme/ContentVisibility';
+import TOC from '@theme/TOC';
+import clsx from 'clsx';
+import type React from 'react';
+import { type ReactNode, useCallback, useEffect, useRef, useState } from 'react';
+import type { AlbumFrontMatter } from '../types';
+import AlbumHeroHeader from './AlbumHeroHeader';
+import ImageLightbox, { type LightboxImage } from './ImageLightbox';
+import styles from './styles.module.css';
+
+function AlbumPostPageContent({
+  sidebar,
+  children,
+}: {
+  sidebar: BlogSidebar;
+  children: ReactNode;
+}): ReactNode {
+  const { metadata, toc } = useBlogPost();
+  const { nextItem, prevItem, frontMatter, title, date, permalink } = metadata;
+  const {
+    hide_table_of_contents: hideTableOfContents,
+    toc_min_heading_level: tocMinHeadingLevel,
+    toc_max_heading_level: tocMaxHeadingLevel,
+    cover,
+    cover_caption: coverCaption,
+    location,
+    album_series: albumSeries,
+  } = frontMatter as AlbumFrontMatter;
+
+  // Lightbox state & image collection
+  const articleRef = useRef<HTMLDivElement>(null);
+  const [lightboxImages, setLightboxImages] = useState<LightboxImage[]>([]);
+  const [lightboxIndex, setLightboxIndex] = useState(0);
+  const [lightboxOpen, setLightboxOpen] = useState(false);
+
+  useEffect(() => {
+    if (!articleRef.current || !permalink) {
+      return;
+    }
+
+    const collectedImages: LightboxImage[] = [];
+
+    // 1. Add cover image first if available
+    if (cover) {
+      collectedImages.push({
+        src: cover,
+        alt: title,
+        caption: coverCaption,
+      });
+    }
+
+    // 2. Collect all images in the markdown body (strictly exclude author avatars and header elements)
+    const domImages = articleRef.current.querySelectorAll<HTMLImageElement>(
+      '.markdown img, [class*="markdown"] img',
+    );
+    const candidateImages =
+      domImages.length > 0
+        ? Array.from(domImages)
+        : Array.from(articleRef.current.querySelectorAll<HTMLImageElement>('img')).filter(
+            (img) =>
+              !img.closest('.avatar') &&
+              !img.classList.contains('avatar__photo') &&
+              !img.closest('header'),
+          );
+
+    for (const img of candidateImages) {
+      if (
+        img.closest('.avatar') ||
+        img.classList.contains('avatar__photo') ||
+        img.closest('header')
+      ) {
+        continue;
+      }
+
+      if (!img.getAttribute('loading')) {
+        img.loading = 'lazy';
+      }
+      if (!img.getAttribute('decoding')) {
+        img.decoding = 'async';
+      }
+
+      if (img.src !== cover) {
+        const imageIndex = collectedImages.length;
+        collectedImages.push({
+          src: img.src,
+          alt: img.alt,
+          caption: img.title || img.alt,
+        });
+        img.dataset.lightboxIndex = String(imageIndex);
+      } else {
+        img.dataset.lightboxIndex = '0';
+      }
+    }
+
+    setLightboxImages(collectedImages);
+  }, [cover, coverCaption, title, permalink]);
+
+  // Event delegation on article container instead of per-image onclick closures
+  const handleArticleClick = useCallback((e: React.MouseEvent<HTMLDivElement>) => {
+    const target = (e.target as HTMLElement | null)?.closest?.(
+      'img[data-lightbox-index]',
+    ) as HTMLImageElement | null;
+    if (!target) {
+      return;
+    }
+
+    const idx = Number(target.dataset.lightboxIndex);
+    if (!Number.isNaN(idx)) {
+      setLightboxIndex(idx);
+      setLightboxOpen(true);
+    }
+  }, []);
+
+  const handleOpenCoverLightbox = useCallback(() => {
+    if (cover) {
+      setLightboxIndex(0);
+      setLightboxOpen(true);
+    }
+  }, [cover]);
+
+  const handleCloseLightbox = useCallback(() => {
+    setLightboxOpen(false);
+  }, []);
+
+  return (
+    <BlogLayout
+      sidebar={sidebar}
+      toc={
+        !hideTableOfContents && toc.length > 0 ? (
+          <TOC
+            toc={toc}
+            minHeadingLevel={tocMinHeadingLevel}
+            maxHeadingLevel={tocMaxHeadingLevel}
+          />
+        ) : undefined
+      }
+    >
+      <ContentVisibility metadata={metadata} />
+
+      {/* Album Hero Header */}
+      <AlbumHeroHeader
+        title={title}
+        date={date}
+        cover={cover}
+        coverCaption={coverCaption}
+        location={location}
+        albumSeries={albumSeries}
+        onCoverClick={handleOpenCoverLightbox}
+      />
+
+      {/* Main article content with lazy-loading and zoomable images */}
+      {/* biome-ignore lint/a11y/useKeyWithClickEvents: delegated click handler for markdown images */}
+      {/* biome-ignore lint/a11y/noStaticElementInteractions: delegated click handler for markdown images */}
+      <div
+        ref={articleRef}
+        className={clsx('album-post-article', styles.albumPostArticle)}
+        onClick={handleArticleClick}
+      >
+        <BlogPostItem>{children}</BlogPostItem>
+      </div>
+
+      {/* Paginator */}
+      {(nextItem || prevItem) && <BlogPostPaginator nextItem={nextItem} prevItem={prevItem} />}
+
+      {/* Full-screen Lightbox */}
+      <ImageLightbox
+        images={lightboxImages}
+        currentIndex={lightboxIndex}
+        isOpen={lightboxOpen}
+        onClose={handleCloseLightbox}
+        onIndexChange={setLightboxIndex}
+      />
+    </BlogLayout>
+  );
+}
+
+export default function AlbumPostPage(props: Props): ReactNode {
+  const BlogPostContent = props.content;
+  return (
+    <BlogPostProvider content={props.content} isBlogPostPage>
+      <HtmlClassNameProvider
+        className={clsx(
+          ThemeClassNames.wrapper.blogPages,
+          ThemeClassNames.page.blogPostPage,
+          'album-post-page',
+        )}
+      >
+        <BlogPostPageMetadata />
+        <BlogPostPageStructuredData />
+        <AlbumPostPageContent sidebar={props.sidebar}>
+          <BlogPostContent />
+        </AlbumPostPageContent>
+      </HtmlClassNameProvider>
+    </BlogPostProvider>
+  );
+}

package/lib/theme/ImageLightbox.tsx

@@ -0,0 +1,161 @@
+import type React from 'react';
+import { memo, useCallback, useEffect } from 'react';
+import type { LightboxImage } from '../types';
+import styles from './styles.module.css';
+
+export type { LightboxImage } from '../types';
+
+type Props = {
+  images: LightboxImage[];
+  currentIndex: number;
+  isOpen: boolean;
+  onClose: () => void;
+  onIndexChange: (index: number) => void;
+};
+
+function ImageLightbox({ images, currentIndex, isOpen, onClose, onIndexChange }: Props) {
+  const total = images.length;
+  const currentImage = images[currentIndex];
+
+  const handlePrev = useCallback(
+    (e?: React.MouseEvent) => {
+      e?.stopPropagation();
+      if (total <= 1) {
+        return;
+      }
+      onIndexChange((currentIndex - 1 + total) % total);
+    },
+    [currentIndex, total, onIndexChange],
+  );
+
+  const handleNext = useCallback(
+    (e?: React.MouseEvent) => {
+      e?.stopPropagation();
+      if (total <= 1) {
+        return;
+      }
+      onIndexChange((currentIndex + 1) % total);
+    },
+    [currentIndex, total, onIndexChange],
+  );
+
+  // Preload adjacent images while lightbox is open for instant prev/next switching
+  useEffect(() => {
+    if (!isOpen || total <= 1) {
+      return;
+    }
+
+    const nextIdx = (currentIndex + 1) % total;
+    const prevIdx = (currentIndex - 1 + total) % total;
+    const preloadIndices = nextIdx === prevIdx ? [nextIdx] : [nextIdx, prevIdx];
+
+    for (const idx of preloadIndices) {
+      const targetSrc = images[idx]?.src;
+      if (targetSrc) {
+        const img = new Image();
+        img.decoding = 'async';
+        img.src = targetSrc;
+      }
+    }
+  }, [isOpen, currentIndex, total, images]);
+
+  // Keyboard navigation
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        onClose();
+      } else if (e.key === 'ArrowLeft') {
+        handlePrev();
+      } else if (e.key === 'ArrowRight') {
+        handleNext();
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    const originalOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+      document.body.style.overflow = originalOverflow;
+    };
+  }, [isOpen, onClose, handlePrev, handleNext]);
+
+  if (!isOpen || !currentImage) {
+    return null;
+  }
+
+  return (
+    // biome-ignore lint/a11y/useKeyWithClickEvents: Escape key is handled globally on document in useEffect
+    <div
+      className={styles.lightboxOverlay}
+      onClick={onClose}
+      role="dialog"
+      aria-modal="true"
+      aria-label="相片檢視燈箱"
+    >
+      {/* Photo counter */}
+      {total > 1 && (
+        <div className={styles.lightboxCounter}>
+          {currentIndex + 1} / {total}
+        </div>
+      )}
+
+      {/* Close button */}
+      <button
+        type="button"
+        className={styles.lightboxCloseBtn}
+        onClick={onClose}
+        title="關閉 (ESC)"
+        aria-label="關閉燈箱"
+      >
+        ✕
+      </button>
+
+      {/* Prev / Next buttons */}
+      {total > 1 && (
+        <>
+          <button
+            type="button"
+            className={`${styles.lightboxNavBtn} ${styles.lightboxPrevBtn}`}
+            onClick={handlePrev}
+            title="上一張 (←)"
+            aria-label="上一張相片"
+          >
+            ‹
+          </button>
+          <button
+            type="button"
+            className={`${styles.lightboxNavBtn} ${styles.lightboxNextBtn}`}
+            onClick={handleNext}
+            title="下一張 (→)"
+            aria-label="下一張相片"
+          >
+            ›
+          </button>
+        </>
+      )}
+
+      {/* Main Image content */}
+      {/* biome-ignore lint/a11y/useKeyWithClickEvents: stopPropagation container only */}
+      {/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation container only */}
+      <div className={styles.lightboxContent} onClick={(e) => e.stopPropagation()}>
+        <img
+          src={currentImage.src}
+          alt={currentImage.alt || '相簿圖片'}
+          className={styles.lightboxImage}
+          decoding="async"
+        />
+        {(currentImage.caption || currentImage.alt) && (
+          <div className={styles.lightboxCaption}>{currentImage.caption || currentImage.alt}</div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default memo(ImageLightbox);