docusaurus-plugin-album 0.0.0-stage → 0.1.0

package/src/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/src/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);

package/src/theme/TimelineScrubber.tsx

@@ -0,0 +1,47 @@
+import clsx from 'clsx';
+import { memo } from 'react';
+import styles from './styles.module.css';
+
+type Props = {
+  years: string[];
+  activeYear: string;
+  activeMonth: string;
+  visible: boolean;
+  onSelectYear: (year: string) => void;
+};
+
+function TimelineScrubber({ years, activeYear, activeMonth, visible, onSelectYear }: Props) {
+  if (years.length === 0) {
+    return null;
+  }
+
+  return (
+    <nav
+      className={clsx(styles.scrubberContainer, visible && styles.scrubberVisible)}
+      aria-label="相簿時間軸"
+    >
+      {/* Floating active date bubble */}
+      <div className={styles.timelineBubble} aria-live="polite">
+        {activeYear ? `${activeYear}年 ${activeMonth ? `${activeMonth}月` : ''}` : '探索相簿'}
+      </div>
+
+      {/* Rail with clickable year ticks */}
+      <div className={styles.timelineRail}>
+        {years.map((year) => (
+          <button
+            key={year}
+            type="button"
+            className={clsx(styles.yearTick, year === activeYear && styles.yearTickActive)}
+            onClick={() => onSelectYear(year)}
+            title={`跳轉至 ${year} 年`}
+            aria-label={`${year} 年`}
+          >
+            {year}
+          </button>
+        ))}
+      </div>
+    </nav>
+  );
+}
+
+export default memo(TimelineScrubber);