hexo-bb-channel 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.2 - 2026-07-20
+
+### Fixed
+
+- Prevented multi-image expand/collapse from shifting the page scroll position.
+- Improved mobile card auto-selection so the card nearest the reading position is selected instead of a taller partially visible card.
+- Restored the mobile active-card placeholder outline while keeping the selected card offset visible.
+- Made bb title and content typography theme-driven through CSS variables, avoiding hard-coded theme font assumptions.
+
+### Changed
+
+- Mobile card active styling now works without hover and keeps the original dashed placeholder visible.
+- Image carousel positioning uses non-smooth initial placement to avoid jumpy first-open behavior.
+

package/README.md

@@ -11,8 +11,6 @@ English | [Chinese](./README.zh-CN.md)
 
 `hexo-bb-channel` is a small Hexo plugin that creates a `/bb/` page shell and loads posts from a separate API at runtime. Your blog stays static, while Telegram updates can appear without rebuilding the whole site.
 
-Live sample: [https://www.kaaaaai.cn/bb/](https://www.kaaaaai.cn/bb/)
-
 ## Preview
 
 Live demo: [https://www.kaaaaai.cn/bb/](https://www.kaaaaai.cn/bb/)
@@ -25,7 +23,7 @@ Live demo: [https://www.kaaaaai.cn/bb/](https://www.kaaaaai.cn/bb/)
 - **Dynamic content on static blogs**: Telegram posts are fetched in the browser from the API backend.
 - **No Telegram token in the blog**: the Hexo side only needs a public API URL.
 - **Media-friendly timeline**: supports text, real Telegram hashtag entities, images, files, pagination, and image preview interactions.
-- **Comments still work**: the generated page is a normal Hexo page and keeps `comments: true`.
+- **Theme comments remain available**: the generated page is a standard Hexo page with `comments: true`; whether comments render depends on your theme and comment system.
 
 ## Quick Start
 
@@ -40,6 +38,8 @@ Deploy the companion API first:
 Backend repo: [Kaaaaai/kaaaaai.tools.channel-api](https://github.com/Kaaaaai/kaaaaai.tools.channel-api)
 See the API README for detailed Telegram channel creation steps.
 
+For production, set `ALLOWED_ORIGINS` to your blog's exact origin, for example `https://www.example.com`, so the API accepts requests from the generated page.
+
 ### 2. Install the Hexo plugin
 
 Install the latest stable release from npm:
@@ -94,7 +94,7 @@ http://localhost:4000/bb/
 | `route` | `bb/` | Output route, for example `moments/`. |
 | `title` | `moments` | Page title inside the content area. |
 | `description` | empty | Subtitle under the title. |
-| `api_base` | empty | Base URL of `kaaaaai.tools.channel-api`. |
+| `api_base` | empty | Required in client mode. Base URL of `kaaaaai.tools.channel-api`; when omitted, the page shows `Missing bb_channel.api_base`. |
 | `page_size` | `20` | Posts requested per page. |
 
 ## How It Works
@@ -198,7 +198,6 @@ npm test
 ## Related
 
 - API backend: [Kaaaaai/kaaaaai.tools.channel-api](https://github.com/Kaaaaai/kaaaaai.tools.channel-api)
-- Live sample: [https://www.kaaaaai.cn/bb/](https://www.kaaaaai.cn/bb/)
 
 ## License
 

package/README.zh-CN.md

@@ -11,8 +11,6 @@
 
 `hexo-bb-channel` 是一个轻量 Hexo 插件：它只生成 `/bb/` 页面壳，内容在浏览器端从独立 API 拉取。这样博客仍然是静态站，但 Telegram Channel 更新后不需要重新 `hexo generate`。
 
-在线示例：[https://www.kaaaaai.cn/bb/](https://www.kaaaaai.cn/bb/)
-
 ## 效果预览
 
 在线示例：[https://www.kaaaaai.cn/bb/](https://www.kaaaaai.cn/bb/)
@@ -25,7 +23,7 @@
 - **静态博客里的动态内容**：页面访问时从 API 拉取 Telegram 内容。
 - **博客侧不放 Telegram 凭证**：Hexo 只需要配置一个 API 地址。
 - **适合碎片流展示**：支持正文、Telegram 原生 hashtag entity、图片、文件、分页、图片预览交互。
-- **保留评论能力**：生成的是标准 Hexo page，默认开启 `comments: true`。
+- **保留主题评论能力**：生成的是标准 Hexo page，并设置 `comments: true`；最终是否显示评论取决于主题和评论系统。
 
 ## 快速开始
 
@@ -40,6 +38,8 @@
 后端仓库：[Kaaaaai/kaaaaai.tools.channel-api](https://github.com/Kaaaaai/kaaaaai.tools.channel-api)
 详细的 Telegram 频道创建步骤见 API 仓库 README。
 
+生产环境请将 `ALLOWED_ORIGINS` 设置为博客的完整 Origin，例如 `https://www.example.com`，确保生成页面能够请求 API。
+
 ### 2. 安装 Hexo 插件
 
 从 npm 安装最新稳定版：
@@ -94,7 +94,7 @@ http://localhost:4000/bb/
 | `route` | `bb/` | 页面路由，例如 `moments/`。 |
 | `title` | `moments` | 页面内容区标题。 |
 | `description` | 空 | 页面描述。 |
-| `api_base` | 空 | `kaaaaai.tools.channel-api` 的 API 根地址。 |
+| `api_base` | 空 | client 模式必填。`kaaaaai.tools.channel-api` 的 API 根地址；未配置时页面会显示 `Missing bb_channel.api_base`。 |
 | `page_size` | `20` | 每页拉取数量。 |
 
 ## 工作原理
@@ -198,7 +198,6 @@ npm test
 ## 相关项目
 
 - API 后端：[Kaaaaai/kaaaaai.tools.channel-api](https://github.com/Kaaaaai/kaaaaai.tools.channel-api)
-- 在线示例：[https://www.kaaaaai.cn/bb/](https://www.kaaaaai.cn/bb/)
 
 ## License
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "hexo-bb-channel",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Render Telegram channel microblog timelines in Hexo using a dynamic API backend.",
   "main": "index.js",
   "files": [
     "index.js",
     "src",
+    "CHANGELOG.md",
     "README.md",
     "README.zh-CN.md",
     "LICENSE"

package/src/render-client.js

@@ -26,6 +26,10 @@ function renderClientScript() {
           const feed = root.querySelector('[data-bb-channel-feed]');
           const pager = root.querySelector('[data-bb-channel-pagination]');
           const status = root.querySelector('[data-bb-channel-status]');
+          let bbActiveCardObserver = null;
+          let bbActiveCardRaf = 0;
+          let bbActiveCardListening = false;
+          const bbActiveCardQuery = window.matchMedia ? window.matchMedia('(max-width: 640px)') : null;
 
         const escapeHtml = (value = '') => String(value)
           .replace(/&/g, '&')
@@ -114,6 +118,121 @@ function renderClientScript() {
           });
         };
 
+        const positionImageTrack = (track, index, useSmoothScroll) => {
+          const left = track.clientWidth * index;
+          track.scrollTo({ left, behavior: useSmoothScroll ? 'smooth' : 'auto' });
+          if (!useSmoothScroll) track.scrollLeft = left;
+        };
+
+        const clearMobileActiveCards = () => {
+          feed.querySelectorAll('.bb-channel-card[data-bb-card-active]').forEach((card) => {
+            delete card.dataset.bbCardActive;
+          });
+        };
+
+        const calculateCardVisibleArea = (card) => {
+          const surface = card.querySelector('.bb-channel-card-surface') || card;
+          const rect = surface.getBoundingClientRect();
+          const viewportWidth = window.innerWidth || document.documentElement.clientWidth || 0;
+          const viewportHeight = window.innerHeight || document.documentElement.clientHeight || 0;
+          const width = Math.max(0, Math.min(rect.right, viewportWidth) - Math.max(rect.left, 0));
+          const height = Math.max(0, Math.min(rect.bottom, viewportHeight) - Math.max(rect.top, 0));
+          return width * height;
+        };
+
+        const calculateCardVisibleRatio = (card) => {
+          const surface = card.querySelector('.bb-channel-card-surface') || card;
+          const rect = surface.getBoundingClientRect();
+          const area = calculateCardVisibleArea(card);
+          const total = Math.max(1, rect.width * rect.height);
+          return area / total;
+        };
+
+        const calculateCardActiveDistance = (card) => {
+          const surface = card.querySelector('.bb-channel-card-surface') || card;
+          const rect = surface.getBoundingClientRect();
+          const viewportHeight = window.innerHeight || document.documentElement.clientHeight || 0;
+          const viewportActiveLine = viewportHeight * .52;
+          const visibleTop = Math.max(rect.top, 0);
+          const visibleBottom = Math.min(rect.bottom, viewportHeight);
+          const visibleCenter = (visibleTop + visibleBottom) / 2;
+          return Math.abs(visibleCenter - viewportActiveLine);
+        };
+
+        const activateLargestVisibleCard = () => {
+          bbActiveCardRaf = 0;
+          if (!bbActiveCardQuery || !bbActiveCardQuery.matches) {
+            clearMobileActiveCards();
+            return;
+          }
+          let activeCard = null;
+          let bestDistance = Infinity;
+          let bestRatio = 0;
+          feed.querySelectorAll('.bb-channel-card').forEach((card) => {
+            if (card.dataset.bbViewerOpen === 'true') return;
+            const visibleArea = calculateCardVisibleArea(card);
+            const visibleRatio = calculateCardVisibleRatio(card);
+            if (visibleArea <= 0 || visibleRatio < .08) return;
+            const distance = calculateCardActiveDistance(card);
+            if (distance < bestDistance || (Math.abs(distance - bestDistance) < 1 && visibleRatio > bestRatio)) {
+              bestDistance = distance;
+              bestRatio = visibleRatio;
+              activeCard = card;
+            }
+          });
+          feed.querySelectorAll('.bb-channel-card').forEach((card) => {
+            if (card === activeCard) {
+              card.dataset.bbCardActive = 'true';
+            } else {
+              delete card.dataset.bbCardActive;
+            }
+          });
+        };
+
+        const scheduleMobileActiveCardUpdate = () => {
+          if (bbActiveCardRaf) return;
+          bbActiveCardRaf = window.requestAnimationFrame(activateLargestVisibleCard);
+        };
+
+        const stopMobileActiveCardTracking = () => {
+          if (bbActiveCardObserver) {
+            bbActiveCardObserver.disconnect();
+            bbActiveCardObserver = null;
+          }
+          if (bbActiveCardRaf) {
+            window.cancelAnimationFrame(bbActiveCardRaf);
+            bbActiveCardRaf = 0;
+          }
+          if (bbActiveCardListening) {
+            window.removeEventListener('scroll', scheduleMobileActiveCardUpdate);
+            window.removeEventListener('resize', scheduleMobileActiveCardUpdate);
+            bbActiveCardListening = false;
+          }
+        };
+
+        const setupMobileActiveCard = () => {
+          stopMobileActiveCardTracking();
+          clearMobileActiveCards();
+          if (!bbActiveCardQuery || !bbActiveCardQuery.matches) return;
+          window.addEventListener('scroll', scheduleMobileActiveCardUpdate, { passive: true });
+          window.addEventListener('resize', scheduleMobileActiveCardUpdate);
+          bbActiveCardListening = true;
+          if ('IntersectionObserver' in window) {
+            bbActiveCardObserver = new IntersectionObserver(scheduleMobileActiveCardUpdate, { threshold: [0, .15, .3, .45, .6, .75, .9, 1] });
+            feed.querySelectorAll('.bb-channel-card').forEach((card) => bbActiveCardObserver.observe(card));
+          }
+          scheduleMobileActiveCardUpdate();
+        };
+
+        if (bbActiveCardQuery) {
+          const handleActiveCardQueryChange = () => setupMobileActiveCard();
+          if (typeof bbActiveCardQuery.addEventListener === 'function') {
+            bbActiveCardQuery.addEventListener('change', handleActiveCardQueryChange);
+          } else if (typeof bbActiveCardQuery.addListener === 'function') {
+            bbActiveCardQuery.addListener(handleActiveCardQueryChange);
+          }
+        }
+
         const openImageViewer = (card, index) => {
           const viewer = card.querySelector('[data-bb-image-viewer]');
           const track = card.querySelector('[data-bb-image-track]');
@@ -121,6 +240,7 @@ function renderClientScript() {
           const count = card.querySelector('[data-bb-image-count]');
           if (!viewer || !track || !slides.length) return;
           const safeIndex = (Number(index) + slides.length) % slides.length;
+          const useSmoothScroll = card.dataset.bbViewerOpen === 'true';
           card.dataset.bbImageIndex = String(safeIndex);
           if (count) count.textContent = slides.length > 1 ? (safeIndex + 1) + ' / ' + slides.length : '';
           preserveCardViewportPosition(card, () => {
@@ -130,7 +250,7 @@ function renderClientScript() {
             hydrateImages(slides[safeIndex]);
             requestAnimationFrame(() => {
               card.dataset.bbViewerOpen = 'true';
-              track.scrollTo({ left: track.clientWidth * safeIndex, behavior: 'smooth' });
+              positionImageTrack(track, safeIndex, useSmoothScroll);
               focusWithoutScroll(track);
             });
           });
@@ -199,6 +319,7 @@ function renderClientScript() {
           const data = await response.json();
           feed.innerHTML = (data.posts || []).map(renderCard).join('');
           hydrateImages(feed);
+          setupMobileActiveCard();
           status.textContent = '';
           pager.innerHTML = '';
           if (data.pagination && data.pagination.total > 1) {
@@ -271,7 +392,7 @@ function renderClientContent(config) {
       .bb-channel-portable{max-width:100%;margin:0 auto;color:#242424}
       .bb-channel-portable *{box-sizing:border-box}
       .bb-channel-portable .bb-channel-intro{position:relative;margin:0 0 1.55rem;padding:0;border-bottom:0}
-      .bb-channel-portable .bb-channel-title{margin:0 0 .45rem;color:#202020;font-family:inherit;font-size:1.72rem;font-weight:700;line-height:1.2;letter-spacing:-.02em}
+      .bb-channel-portable .bb-channel-title{margin:0 0 .45rem;color:#202020;font-family:var(--bb-channel-title-font,inherit);font-size:1.72rem;font-weight:700;line-height:1.2;letter-spacing:0}
       .bb-channel-portable .bb-channel-intro-text{margin:0;color:#777;font-size:1rem;line-height:1.6;text-align:left}
       .bb-channel-portable .bb-channel-status{min-height:1.2rem;margin:.4rem 0 .8rem;color:#999}
       .bb-channel-portable .bb-channel-feed{position:relative;display:flex;flex-direction:column;gap:1.05rem;padding-left:2.1rem}
@@ -286,8 +407,8 @@ function renderClientContent(config) {
       .bb-channel-portable .bb-channel-time{color:inherit;text-decoration:none;border-bottom:0;font-size:.96rem;line-height:1.3}
       .bb-channel-portable .bb-channel-body-with-media{display:grid;grid-template-columns:minmax(0,1fr) minmax(10rem,13.5rem);gap:1.25rem;align-items:start}
       .bb-channel-portable .bb-channel-main{min-width:0}
-      .bb-channel-portable .bb-channel-content{font-size:1rem;line-height:1.78;overflow-wrap:anywhere}
-      .bb-channel-portable .bb-channel-content p{margin:0 0 .9em}
+      .bb-channel-portable .bb-channel-content{font-family:var(--bb-channel-content-font,inherit);font-size:1.02rem;line-height:1.82;letter-spacing:.01em;text-rendering:optimizeLegibility;overflow-wrap:anywhere}
+      .bb-channel-portable .bb-channel-content p{margin:0 0 .82em}
       .bb-channel-portable .bb-channel-content a{color:#e46f0a;border-bottom:1px solid rgba(228,111,10,.35);text-decoration:none}
       .bb-channel-portable .bb-channel-media-rail{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:.32rem;justify-self:end;width:min(13.5rem,100%);max-height:24rem;opacity:1;overflow:hidden;transform:translateY(0);filter:blur(0);transition:max-height 420ms cubic-bezier(.22,1,.36,1),opacity 420ms cubic-bezier(.22,1,.36,1),transform 420ms cubic-bezier(.22,1,.36,1),filter 420ms cubic-bezier(.22,1,.36,1);will-change:max-height,opacity,transform}
       .bb-channel-portable .bb-channel-media-thumb{position:relative;display:grid;min-height:0;aspect-ratio:1/1;place-items:center;border:1px solid #e7e7e7;border-radius:8px;background:#f8f8f8;padding:0;overflow:hidden;cursor:pointer}
@@ -327,8 +448,8 @@ function renderClientContent(config) {
       .bb-channel-portable .bb-channel-pagination span{min-width:2.15rem;background:#333;color:#fff;border-color:#333}
       @media(max-width:720px){.bb-channel-portable .bb-channel-body-with-media{grid-template-columns:1fr}.bb-channel-portable .bb-channel-media-rail{justify-self:start;width:min(18rem,100%)}}
       @keyframes bb-channel-shimmer{0%{background-position:180% 0}100%{background-position:-80% 0}}
-      @media(max-width:640px){.bb-channel-portable .bb-channel-intro{margin-bottom:1.2rem}.bb-channel-portable .bb-channel-title{font-size:1.45rem}.bb-channel-portable .bb-channel-intro-text{font-size:.94rem}.bb-channel-portable .bb-channel-feed{gap:.9rem;padding-left:1.15rem}.bb-channel-portable .bb-channel-feed::before{left:.06rem}.bb-channel-portable .bb-channel-dot{left:-1.32rem;top:1.42rem}.bb-channel-portable .bb-channel-card-surface{padding:1.05rem .95rem;border-radius:12px}.bb-channel-portable .bb-channel-card-placeholder{border-radius:12px}.bb-channel-portable .bb-channel-card:hover .bb-channel-card-surface{transform:none}.bb-channel-portable .bb-channel-meta{margin-bottom:.85rem}.bb-channel-portable .bb-channel-content{font-size:.96rem;line-height:1.72}.bb-channel-portable .bb-channel-media-rail{width:100%;max-width:20rem;grid-template-columns:repeat(3,minmax(0,1fr));justify-self:center;margin-top:.15rem}.bb-channel-portable .bb-channel-media-thumb{min-height:4.1rem}.bb-channel-portable .bb-channel-image-viewer{margin-top:.95rem;max-width:100%}.bb-channel-portable .bb-channel-image-slide{min-height:10rem}.bb-channel-portable .bb-channel-image-large{max-width:100%!important;max-height:68vh!important}.bb-channel-portable .bb-channel-image-nav{width:2.55rem;height:2.55rem}.bb-channel-portable .bb-channel-image-prev{left:.45rem}.bb-channel-portable .bb-channel-image-next{right:.45rem}.bb-channel-portable .bb-channel-attachment{align-items:flex-start;padding:.78rem .82rem}.bb-channel-portable .bb-channel-attachment-title{white-space:normal;overflow-wrap:anywhere}.bb-channel-portable .bb-channel-tags{gap:.42rem}.bb-channel-portable .bb-channel-pagination{gap:1rem}}
-      @media(prefers-reduced-motion:reduce){.bb-channel-portable .bb-channel-card-placeholder,.bb-channel-portable .bb-channel-card-surface,.bb-channel-portable .bb-channel-media-rail,.bb-channel-portable .bb-channel-image-viewer,.bb-channel-portable .bb-channel-image-large,.bb-channel-portable .bb-channel-attachment{transition:none}.bb-channel-portable .bb-channel-card:hover .bb-channel-card-surface{transform:none}}
+      @media(max-width:640px){.bb-channel-portable .bb-channel-intro{margin-bottom:1.2rem}.bb-channel-portable .bb-channel-title{font-size:1.45rem}.bb-channel-portable .bb-channel-intro-text{font-size:.94rem}.bb-channel-portable .bb-channel-feed{gap:.9rem;padding-left:1.15rem}.bb-channel-portable .bb-channel-feed::before{left:.06rem}.bb-channel-portable .bb-channel-dot{left:-1.32rem;top:1.42rem}.bb-channel-portable .bb-channel-card-surface{padding:1.05rem .95rem;border-radius:12px}.bb-channel-portable .bb-channel-card-placeholder{border-radius:12px}.bb-channel-portable .bb-channel-card:hover .bb-channel-card-surface{transform:none}.bb-channel-portable .bb-channel-card[data-bb-card-active="true"] .bb-channel-card-placeholder{opacity:1}.bb-channel-portable .bb-channel-card[data-bb-card-active="true"] .bb-channel-card-surface{transform:translate(4px,-5px);border-style:solid;border-color:#e7b99d;background:rgba(255,255,255,.86);box-shadow:0 12px 26px -24px rgba(15,23,42,.32)}.bb-channel-portable .bb-channel-card[data-bb-viewer-open="true"] .bb-channel-card-placeholder{opacity:0}.bb-channel-portable .bb-channel-card[data-bb-viewer-open="true"] .bb-channel-card-surface{transform:none}.bb-channel-portable .bb-channel-meta{margin-bottom:.85rem}.bb-channel-portable .bb-channel-content{font-size:.96rem;line-height:1.72}.bb-channel-portable .bb-channel-media-rail{width:100%;max-width:20rem;grid-template-columns:repeat(3,minmax(0,1fr));justify-self:center;margin-top:.15rem}.bb-channel-portable .bb-channel-media-thumb{min-height:4.1rem}.bb-channel-portable .bb-channel-image-viewer{margin-top:.95rem;max-width:100%}.bb-channel-portable .bb-channel-image-slide{min-height:10rem}.bb-channel-portable .bb-channel-image-large{max-width:100%!important;max-height:68vh!important}.bb-channel-portable .bb-channel-image-nav{width:2.55rem;height:2.55rem}.bb-channel-portable .bb-channel-image-prev{left:.45rem}.bb-channel-portable .bb-channel-image-next{right:.45rem}.bb-channel-portable .bb-channel-attachment{align-items:flex-start;padding:.78rem .82rem}.bb-channel-portable .bb-channel-attachment-title{white-space:normal;overflow-wrap:anywhere}.bb-channel-portable .bb-channel-tags{gap:.42rem}.bb-channel-portable .bb-channel-pagination{gap:1rem}}
+      @media(prefers-reduced-motion:reduce){.bb-channel-portable .bb-channel-card-placeholder,.bb-channel-portable .bb-channel-card-surface,.bb-channel-portable .bb-channel-media-rail,.bb-channel-portable .bb-channel-image-viewer,.bb-channel-portable .bb-channel-image-large,.bb-channel-portable .bb-channel-attachment{transition:none}.bb-channel-portable .bb-channel-card:hover .bb-channel-card-surface,.bb-channel-portable .bb-channel-card[data-bb-card-active="true"] .bb-channel-card-surface{transform:none}}
     </style>
     <div class="bb-channel-portable" data-bb-channel-root data-api-base="${escapeHtml(config.apiBase)}" data-page-size="${escapeHtml(config.pageSize)}">
       <header class="bb-channel-intro">