docusaurus-plugin-album 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kywk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# docusaurus-plugin-album
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pinterest-style masonry photo album plugin for [Docusaurus](https://docusaurus.io) with a Google Photos timeline scrubber, immersive hero header, and zero-dependency full-screen lightbox.
+
+- **Pinterest Masonry Grid**: Responsive multi-column layout with hover overlays for titles, locations, and series badges.
+- **Google Photos Timeline Scrubber**: Floating year/month indicator on scroll with one-click smooth jumping across years.
+- **Immersive Post Hero Header**: Full-width cover image, caption, location badge (`📍`), and album series badge (`📁`).
+- **Zero-Dependency Lightbox**: Keyboard navigation (`←` / `→` / `Escape`), background preload of adjacent photos, scroll locking, and automatic author avatar exclusion.
+- **Drop-In Blog Wrapper**: Wraps `@docusaurus/plugin-content-blog` with build-time lazy image injection and lightweight route props for fast page loads even with hundreds of albums.
+
+## Requirements
+
+| Dependency | Version |
+| --- | --- |
+| Docusaurus | 3.8 or newer (tested with 3.10) |
+| React | 18 or 19 (tested with 19.2) |
+| Node.js | 20.19 or newer |
+
+## Install
+
+```bash
+npm install docusaurus-plugin-album
+```
+
+## Usage
+
+Register `docusaurus-plugin-album` in `docusaurus.config.ts`:
+
+```ts
+// docusaurus.config.ts
+import type { Config } from '@docusaurus/types';
+import type { AlbumPluginOptions } from 'docusaurus-plugin-album';
+
+const config: Config = {
+  // ...
+  plugins: [
+    [
+      'docusaurus-plugin-album',
+      {
+        id: 'album',
+        path: 'blog.album',
+        routeBasePath: 'album',
+        blogTitle: 'Photo Album',
+        blogDescription: 'Travel and photography archive.',
+      } satisfies AlbumPluginOptions,
+    ],
+  ],
+};
+
+export default config;
+```
+
+## Album Post Frontmatter
+
+Create Markdown files under your configured `path` (default: `blog.album/`):
+
+```markdown
+---
+title: Autumn in Hokkaido Biei
+date: 2025-09-05
+cover: /img/album/biei-cover.jpg
+cover_caption: Morning light over the Blue Pond in Biei
+location: Biei, Hokkaido
+album_series: 2025 Northern Autumn
+tags:
+  - Japan
+  - Photography
+---
+
+Introductory notes for the album...
+
+<!--truncate-->
+
+![Blue Pond Panorama](/img/album/biei-01.jpg)
+
+![White Birch Reflections](/img/album/biei-02.jpg)
+```
+
+### Supported Frontmatter Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | Album title |
+| `date` | `string \| Date` | Album date (`YYYY-MM-DD`) |
+| `cover` | `string` | Cover image URL. Posts without `cover` are hidden from the masonry index |
+| `cover_caption` | `string` | Optional caption displayed over the hero cover image |
+| `location` | `string` | Optional location badge (`📍`) |
+| `album_series` | `string` | Optional series/collection badge (`📁`) |
+| `tags` | `string[]` | Standard Docusaurus blog tags |
+
+All standard [`@docusaurus/plugin-content-blog` options](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog) are supported.
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter docusaurus-plugin-album build
+pnpm --filter docusaurus-plugin-album test
+pnpm playground
+```
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,26 @@
+import type { BlogContent, PluginOptions as BlogPluginOptions } from '@docusaurus/plugin-content-blog';
+import type { LoadContext, OptionValidationContext, Plugin } from '@docusaurus/types';
+import type { AlbumPluginOptions } from './types';
+export type { AlbumFrontMatter, AlbumPluginOptions, AlbumPostMeta, LightboxImage } from './types';
+type HastNode = {
+    type?: string;
+    tagName?: string;
+    properties?: Record<string, unknown>;
+    children?: HastNode[];
+};
+/**
+ * Build-time Rehype plugin that injects `loading="lazy"` and `decoding="async"`
+ * into markdown body `<img>` elements so static HTML does not trigger eager
+ * preload requests for every photo in an album post.
+ */
+export declare function rehypeAlbumLazyImages(): (tree: HastNode) => void;
+/**
+ * Pre-parses year, month, and display label from permalink or post date.
+ */
+export declare function parsePostDate(permalink: string, date: Date | string | undefined): {
+    year: string;
+    month: string;
+    displayDate: string;
+};
+export declare function validateOptions({ validate, options, }: OptionValidationContext<AlbumPluginOptions | undefined, BlogPluginOptions>): BlogPluginOptions;
+export default function pluginAlbum(context: LoadContext, options: BlogPluginOptions): Promise<Plugin<BlogContent>>;

package/lib/index.js

@@ -0,0 +1,186 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rehypeAlbumLazyImages = rehypeAlbumLazyImages;
+exports.parsePostDate = parsePostDate;
+exports.validateOptions = validateOptions;
+exports.default = pluginAlbum;
+const node_path_1 = __importDefault(require("node:path"));
+const plugin_content_blog_1 = __importStar(require("@docusaurus/plugin-content-blog"));
+const PERMALINK_DATE_REGEX = /\/(\d{4})\/(\d{2})\//;
+/**
+ * Build-time Rehype plugin that injects `loading="lazy"` and `decoding="async"`
+ * into markdown body `<img>` elements so static HTML does not trigger eager
+ * preload requests for every photo in an album post.
+ */
+function rehypeAlbumLazyImages() {
+    function visitNode(node) {
+        if (!node || typeof node !== 'object') {
+            return;
+        }
+        if (node.type === 'element' && node.tagName === 'img') {
+            node.properties = node.properties ?? {};
+            if (!node.properties.loading) {
+                node.properties.loading = 'lazy';
+            }
+            if (!node.properties.decoding) {
+                node.properties.decoding = 'async';
+            }
+        }
+        if (Array.isArray(node.children)) {
+            for (const child of node.children) {
+                visitNode(child);
+            }
+        }
+    }
+    return (tree) => {
+        visitNode(tree);
+    };
+}
+/**
+ * Pre-parses year, month, and display label from permalink or post date.
+ */
+function parsePostDate(permalink, date) {
+    if (typeof permalink === 'string') {
+        const permalinkMatch = permalink.match(PERMALINK_DATE_REGEX);
+        if (permalinkMatch) {
+            const year = permalinkMatch[1];
+            const month = String(Number(permalinkMatch[2]));
+            return { year, month, displayDate: `${year}年 ${month}月` };
+        }
+    }
+    if (date) {
+        const parsed = date instanceof Date ? date : new Date(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 validateOptions({ validate, options = {}, }) {
+    const userRehypePlugins = Array.isArray(options.rehypePlugins) ? options.rehypePlugins : [];
+    const mergedOptions = {
+        id: 'album',
+        path: 'blog.album',
+        routeBasePath: 'album',
+        blogTitle: 'Album 相簿',
+        blogDescription: '用快門記錄旅途風光與生活剪影，在光影與時間軸中重溫每一刻感動。',
+        blogSidebarTitle: 'All albums',
+        blogSidebarCount: 'ALL',
+        postsPerPage: 'ALL',
+        blogListComponent: node_path_1.default.resolve(__dirname, 'theme/AlbumListPage'),
+        blogPostComponent: node_path_1.default.resolve(__dirname, 'theme/AlbumPostPage'),
+        onUntruncatedBlogPosts: 'ignore',
+        showReadingTime: true,
+        ...options,
+        rehypePlugins: [rehypeAlbumLazyImages, ...userRehypePlugins],
+    };
+    return (0, plugin_content_blog_1.validateOptions)({ validate, options: mergedOptions });
+}
+async function pluginAlbum(context, options) {
+    const blogPluginInstance = await (0, plugin_content_blog_1.default)(context, options);
+    return {
+        ...blogPluginInstance,
+        // Keep blogPluginInstance.name ('docusaurus-plugin-content-blog') because
+        // Docusaurus namespaces createData() by plugin.name and @docusaurus/plugin-content-blog
+        // hardcodes 'docusaurus-plugin-content-blog' in its MDX loader rules.
+        async contentLoaded({ content, actions }) {
+            const albumPosts = (content?.blogPosts ?? [])
+                .filter((post) => {
+                const fm = post?.metadata?.frontMatter;
+                return Boolean(fm?.cover);
+            })
+                .map((post) => {
+                const { permalink, title, date } = post.metadata;
+                const frontMatter = post.metadata.frontMatter;
+                const dateStr = date instanceof Date ? date.toISOString() : String(date);
+                const { year, month, displayDate } = parsePostDate(permalink, date);
+                return {
+                    permalink,
+                    title,
+                    date: dateStr,
+                    year,
+                    month,
+                    displayDate,
+                    frontMatter: {
+                        cover: frontMatter.cover,
+                        cover_caption: frontMatter.cover_caption,
+                        location: frontMatter.location,
+                        album_series: frontMatter.album_series,
+                        tags: Array.isArray(frontMatter.tags) ? frontMatter.tags : undefined,
+                    },
+                };
+            });
+            const wrappedActions = {
+                ...actions,
+                addRoute(routeConfig) {
+                    const isAlbumListRoute = routeConfig.component === options.blogListComponent ||
+                        (typeof routeConfig.component === 'string' &&
+                            routeConfig.component.endsWith('AlbumListPage'));
+                    if (isAlbumListRoute) {
+                        actions.addRoute({
+                            ...routeConfig,
+                            modules: {},
+                            props: {
+                                ...routeConfig.props,
+                                posts: albumPosts,
+                            },
+                        });
+                        return;
+                    }
+                    actions.addRoute(routeConfig);
+                },
+            };
+            if (blogPluginInstance.contentLoaded) {
+                await blogPluginInstance.contentLoaded({
+                    content,
+                    actions: wrappedActions,
+                });
+            }
+        },
+        getThemePath() {
+            return node_path_1.default.resolve(__dirname, 'theme');
+        },
+        getTypeScriptThemePath() {
+            return node_path_1.default.resolve(__dirname, '../src/theme');
+        },
+    };
+}
+Object.assign(pluginAlbum, { validateOptions });

package/lib/theme/AlbumHeroHeader.tsx

@@ -0,0 +1,91 @@
+import type React from 'react';
+import { memo, useCallback, useMemo } from 'react';
+import styles from './styles.module.css';
+
+type Props = {
+  title: string;
+  date: string;
+  cover?: string;
+  coverCaption?: string;
+  location?: string;
+  albumSeries?: string;
+  onCoverClick?: () => void;
+};
+
+function AlbumHeroHeader({
+  title,
+  date,
+  cover,
+  coverCaption,
+  location,
+  albumSeries,
+  onCoverClick,
+}: Props) {
+  const displayDate = useMemo(() => {
+    if (!date) {
+      return '';
+    }
+    const parsed = new Date(date);
+    if (!Number.isNaN(parsed.getTime())) {
+      return `${parsed.getUTCFullYear()}年 ${parsed.getUTCMonth() + 1}月 ${parsed.getUTCDate()}日`;
+    }
+    return date;
+  }, [date]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      if (!onCoverClick) {
+        return;
+      }
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        onCoverClick();
+      }
+    },
+    [onCoverClick],
+  );
+
+  return (
+    <header className={styles.postHero}>
+      {cover && (
+        // biome-ignore lint/a11y/useSemanticElements: div container wraps block-level caption and cover image
+        <div
+          className={styles.heroImageContainer}
+          onClick={onCoverClick}
+          onKeyDown={handleKeyDown}
+          title="點擊檢視封面大圖"
+          role="button"
+          tabIndex={0}
+        >
+          <img
+            src={cover}
+            alt={title}
+            className={styles.heroCoverImage}
+            loading="eager"
+            fetchPriority="high"
+            decoding="async"
+          />
+          {coverCaption && <div className={styles.heroCaption}>{coverCaption}</div>}
+        </div>
+      )}
+
+      <div className={styles.heroMetaBody}>
+        <h1 className={styles.heroTitle}>{title}</h1>
+
+        <div className={styles.heroBadgesRow}>
+          {location && (
+            <span className={`${styles.heroBadge} ${styles.locationBadge}`}>📍 {location}</span>
+          )}
+          {albumSeries && (
+            <span className={`${styles.heroBadge} ${styles.seriesBadge}`}>📁 {albumSeries}</span>
+          )}
+          {displayDate && (
+            <span className={`${styles.heroBadge} ${styles.heroDateBadge}`}>📅 {displayDate}</span>
+          )}
+        </div>
+      </div>
+    </header>
+  );
+}
+
+export default memo(AlbumHeroHeader);

package/lib/theme/AlbumListPage.tsx

@@ -0,0 +1,107 @@
+import { PageMetadata } from '@docusaurus/theme-common';
+import Layout from '@theme/Layout';
+import SearchMetadata from '@theme/SearchMetadata';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import AlbumMasonryGrid, { type AlbumPostMeta, parseDate } from './AlbumMasonryGrid';
+import styles from './styles.module.css';
+import TimelineScrubber from './TimelineScrubber';
+
+type Props = {
+  metadata: {
+    blogTitle: string;
+    blogDescription: string;
+    permalink: string;
+    [key: string]: unknown;
+  };
+  posts?: readonly AlbumPostMeta[];
+  items?: readonly {
+    content: {
+      metadata: AlbumPostMeta;
+    };
+  }[];
+  sidebar?: unknown;
+};
+
+const DEFAULT_TITLE = 'Album 相簿';
+const DEFAULT_DESCRIPTION = '用快門記錄旅途風光與生活剪影，在光影與時間軸中重溫每一刻感動。';
+
+export default function AlbumListPage(props: Props) {
+  const { metadata, posts: directPosts, items } = props;
+  const pageTitle = metadata.blogTitle || DEFAULT_TITLE;
+  const pageDescription = metadata.blogDescription || DEFAULT_DESCRIPTION;
+
+  const posts: AlbumPostMeta[] = useMemo(() => {
+    if (directPosts) {
+      return [...directPosts];
+    }
+    return (items ?? []).map(({ content }) => content.metadata);
+  }, [directPosts, items]);
+
+  // Extract unique years for TimelineScrubber in descending order
+  const years = useMemo(() => {
+    const yearSet = new Set<string>();
+    for (const post of posts) {
+      if (post.frontMatter?.cover) {
+        const year = post.year || parseDate(post).year;
+        if (year) {
+          yearSet.add(year);
+        }
+      }
+    }
+    return Array.from(yearSet).sort((a, b) => Number(b) - Number(a));
+  }, [posts]);
+
+  const [activeYear, setActiveYear] = useState<string>(() => years[0] || '2026');
+  const [activeMonth, setActiveMonth] = useState<string>('');
+  const [scrubberVisible, setScrubberVisible] = useState(false);
+  const scrollToYearRef = useRef<((year: string) => void) | null>(null);
+
+  const handleCurrentDateChange = useCallback((year: string, month: string) => {
+    setActiveYear(year);
+    setActiveMonth(month);
+  }, []);
+
+  const handleScrubberVisibleChange = useCallback((visible: boolean) => {
+    setScrubberVisible(visible);
+  }, []);
+
+  const handleSelectYear = useCallback((year: string) => {
+    if (scrollToYearRef.current) {
+      scrollToYearRef.current(year);
+      return;
+    }
+    const targetCard = document.querySelector<HTMLElement>(`[data-year="${year}"]`);
+    if (targetCard) {
+      targetCard.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }
+  }, []);
+
+  return (
+    <Layout title={pageTitle} description={pageDescription}>
+      <PageMetadata title={pageTitle} description={pageDescription} />
+      <SearchMetadata tag="blog_posts_list" />
+
+      <main className={styles.albumContainer}>
+        <header className={styles.albumHeader}>
+          <h1 className={styles.albumTitle}>{pageTitle}</h1>
+          <p className={styles.albumDescription}>{pageDescription}</p>
+        </header>
+
+        <AlbumMasonryGrid
+          posts={posts}
+          onCurrentDateChange={handleCurrentDateChange}
+          onScrubberVisibleChange={handleScrubberVisibleChange}
+          scrollToYearRef={scrollToYearRef}
+        />
+
+        <TimelineScrubber
+          years={years}
+          activeYear={activeYear}
+          activeMonth={activeMonth}
+          visible={scrubberVisible}
+          onSelectYear={handleSelectYear}
+        />
+      </main>
+    </Layout>
+  );
+}