@hanology/cham-browser 0.3.4 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanology/cham-browser",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "CHAM — browser-compatible parser, serializer, and site generator for Classical Han Annotated Markdown",
   "type": "module",
   "main": "dist/index.js",

package/template/src/components/PartBlock.vue

@@ -8,6 +8,7 @@ const props = defineProps<{
   annotations: Annotation[]
   vertical?: boolean
   source?: PieceSource
+  annotationText?: string
 }>()
 
 const emit = defineEmits<{
@@ -55,6 +56,9 @@ const sourceLabel = (() => {
         v-html="verseHtml(i)"
       />
     </div>
+    <div v-if="annotationText" class="part-annotations">
+      <div v-for="line in annotationText.split('\n')" :key="line" class="part-ann-line">{{ line }}</div>
+    </div>
   </div>
 </template>
 
@@ -90,6 +94,20 @@ const sourceLabel = (() => {
   line-height: 1;
 }
 
+.part-annotations {
+  margin-top: 16px;
+  padding-top: 12px;
+  border-top: 1px dashed var(--border-light);
+}
+
+.part-ann-line {
+  font-family: var(--sans);
+  font-size: 14px;
+  line-height: 2;
+  color: var(--ink-mid);
+  letter-spacing: 0.5px;
+}
+
 .part-line-h {
   font-size: var(--main-font-size, 22px);
   line-height: 2.4;
@@ -134,7 +152,6 @@ const sourceLabel = (() => {
   background: rgba(58, 107, 94, 0.08);
 }
 
-/* Vertical mode overrides */
 .part-block--vertical :deep(.ann-target) {
   border-bottom: none;
   border-left: 2px solid var(--vermillion);
@@ -157,4 +174,13 @@ const sourceLabel = (() => {
   margin-bottom: 0;
   margin-left: 8px;
 }
+
+.part-block--vertical .part-annotations {
+  margin-top: 0;
+  margin-left: 12px;
+  padding-top: 0;
+  padding-left: 12px;
+  border-top: none;
+  border-left: 1px dashed var(--border-light);
+}
 </style>

package/template/src/components/PartGroup.vue

@@ -24,6 +24,7 @@ const emit = defineEmits<{
       :num="part.num"
       :verses="part.verses"
       :annotations="part.annotations"
+      :annotation-text="part.annotationText"
       :vertical="vertical"
       :source="part.source"
       @annotation-hover="(e, a) => emit('annotationHover', e, a)"

package/template/src/components/ReadingProgress.vue

@@ -0,0 +1,83 @@
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted, watch } from 'vue'
+
+const props = defineProps<{
+  vertical?: boolean
+  scrollContainer?: HTMLElement | null
+}>()
+
+const progress = ref(0)
+let raf = 0
+
+function updateProgress() {
+  if (props.vertical && props.scrollContainer) {
+    const el = props.scrollContainer
+    const max = el.scrollWidth - el.clientWidth
+    progress.value = max > 0 ? Math.min((el.scrollLeft / max) * 100, 100) : 0
+  } else if (!props.vertical) {
+    const max = document.documentElement.scrollHeight - window.innerHeight
+    progress.value = max > 0 ? Math.min((window.scrollY / max) * 100, 100) : 0
+  }
+}
+
+function onScroll() {
+  cancelAnimationFrame(raf)
+  raf = requestAnimationFrame(updateProgress)
+}
+
+function attach() {
+  if (props.vertical && props.scrollContainer) {
+    props.scrollContainer.addEventListener('scroll', onScroll, { passive: true })
+  } else if (!props.vertical) {
+    window.addEventListener('scroll', onScroll, { passive: true })
+  }
+  updateProgress()
+}
+
+function detach() {
+  if (props.vertical && props.scrollContainer) {
+    props.scrollContainer.removeEventListener('scroll', onScroll)
+  } else {
+    window.removeEventListener('scroll', onScroll)
+  }
+  cancelAnimationFrame(raf)
+}
+
+watch(() => props.scrollContainer, (el, old) => {
+  detach()
+  if (old) old.removeEventListener('scroll', onScroll)
+  attach()
+})
+
+onMounted(attach)
+onUnmounted(detach)
+</script>
+
+<template>
+  <div
+    class="rp"
+    :class="{ 'rp-v': vertical }"
+    :style="vertical
+      ? { height: progress + '%' }
+      : { width: progress + '%' }"
+  />
+</template>
+
+<style scoped>
+.rp {
+  position: fixed;
+  z-index: 1001;
+  background: linear-gradient(90deg, var(--vermillion), var(--vermillion-light));
+  pointer-events: none;
+  will-change: width, height;
+}
+.rp:not(.rp-v) {
+  top: 0; left: 0;
+  height: 2px;
+}
+.rp-v {
+  top: 0; left: 0;
+  width: 2px;
+  background: linear-gradient(180deg, var(--vermillion), var(--vermillion-light));
+}
+</style>

package/template/src/components/ReadingToolbar.vue

@@ -74,6 +74,11 @@ function close() { open.value = false }
           >{{ localeLabels[loc] }}</button>
         </div>
       </div>
+      <div class="rt-shortcuts">
+        <div class="rt-sc"><kbd>V</kbd> 直/橫</div>
+        <div class="rt-sc"><kbd>T</kbd> 主題</div>
+        <div class="rt-sc"><kbd>Esc</kbd> 首頁</div>
+      </div>
     </div>
     <div v-if="open" class="rt-backdrop" @click="close" />
   </div>
@@ -182,4 +187,35 @@ function close() { open.value = false }
   position: fixed; inset: 0;
   z-index: -1;
 }
+.rt-shortcuts {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding-top: 10px;
+  border-top: 1px solid var(--border-light);
+  margin-top: 2px;
+}
+.rt-sc {
+  font-family: var(--sans);
+  font-size: 10px;
+  color: var(--ink-faint);
+  letter-spacing: 1px;
+  display: flex;
+  align-items: center;
+  gap: 3px;
+}
+.rt-sc kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 16px;
+  padding: 0 3px;
+  border: 1px solid var(--border);
+  border-radius: 2px;
+  font-family: var(--sans);
+  font-size: 9px;
+  color: var(--ink-light);
+  background: var(--surface);
+}
 </style>

package/template/src/components/SectionBlock.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed } from 'vue'
+import { computed, ref, onMounted, onUnmounted } from 'vue'
 import { parseAnnotationBlock } from '../utils/annotationParser'
 import PronunciationGroup from './PronunciationGroup.vue'
 
@@ -12,6 +12,27 @@ const props = defineProps<{
   vertical?: boolean
 }>()
 
+const rootRef = ref<HTMLElement | null>(null)
+const visible = ref(false)
+
+onMounted(() => {
+  if (props.vertical || !rootRef.value) {
+    visible.value = true
+    return
+  }
+  const observer = new IntersectionObserver(
+    ([entry]) => {
+      if (entry.isIntersecting) {
+        visible.value = true
+        observer.disconnect()
+      }
+    },
+    { rootMargin: '0px 0px -40px 0px', threshold: 0 }
+  )
+  observer.observe(rootRef.value)
+  onUnmounted(() => observer.disconnect())
+})
+
 function esc(str: string): string {
   return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
 }
@@ -40,7 +61,7 @@ const paragraphsHtml = computed(() => {
 </script>
 
 <template>
-  <div v-if="text" class="sb-root" :class="{ 'sb-vertical': vertical }">
+  <div v-if="text" ref="rootRef" class="sb-root" :class="{ 'sb-vertical': vertical, 'sb-visible': visible }">
     <div class="sb-header">
       <span v-if="displayNum" class="sb-num" :class="{ special }">{{ displayNum }}</span>
       <h3>{{ special ? '【' + label + '】' : label }}</h3>
@@ -64,11 +85,13 @@ const paragraphsHtml = computed(() => {
 <style scoped>
 .sb-root {
   margin-bottom: 40px;
-  animation: sb-fade-up 0.5s ease forwards;
+  opacity: 0;
+  transform: translateY(12px);
+  transition: opacity 0.5s ease, transform 0.5s var(--ease-out-expo, cubic-bezier(0.16, 1, 0.3, 1));
 }
-@keyframes sb-fade-up {
-  from { opacity: 0; transform: translateY(16px); }
-  to { opacity: 1; transform: translateY(0); }
+.sb-root.sb-visible {
+  opacity: 1;
+  transform: translateY(0);
 }
 .sb-header {
   display: flex; align-items: center; gap: 12px;
@@ -107,7 +130,9 @@ const paragraphsHtml = computed(() => {
   border-right: 1px solid var(--border);
   overflow-x: auto;
   overflow-y: hidden;
-  animation: none;
+  opacity: 1;
+  transform: none;
+  transition: none;
 }
 .sb-vertical .sb-header {
   flex-direction: column;

package/template/src/components/SideNav.vue

@@ -113,6 +113,11 @@ function toggleSettings() { settingsOpen.value = !settingsOpen.value }
             >{{ localeLabels[loc] }}</button>
           </div>
         </div>
+        <div class="ss-shortcuts">
+          <span class="ss-sc"><kbd>V</kbd> 直/橫</span>
+          <span class="ss-sc"><kbd>T</kbd> 主題</span>
+          <span class="ss-sc"><kbd>Esc</kbd> 首頁</span>
+        </div>
       </div>
     </Transition>
 
@@ -308,6 +313,37 @@ function toggleSettings() { settingsOpen.value = !settingsOpen.value }
   position: fixed; inset: 0;
   z-index: -1;
 }
+.ss-shortcuts {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px 8px;
+  padding-top: 10px;
+  border-top: 1px solid var(--border-light);
+  margin-top: 2px;
+}
+.ss-sc {
+  font-family: var(--sans);
+  font-size: 10px;
+  color: var(--ink-faint);
+  letter-spacing: 1px;
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+}
+.ss-sc kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 16px;
+  padding: 0 3px;
+  border: 1px solid var(--border);
+  border-radius: 2px;
+  font-family: var(--sans);
+  font-size: 9px;
+  color: var(--ink-light);
+  background: var(--surface);
+}
 
 @media (max-width: 768px) {
   .sidenav { width: 44px; padding: 8px 0; gap: 6px; }

package/template/src/types.ts

@@ -108,11 +108,12 @@ export interface PieceContributor {
   title?: string
 }
 
-export interface PieceSource {  text?: string
+export interface PieceSource {
+  text?: string
   textRef?: string
   pieceRef?: number
   relation: 'section' | 'excerpt' | 'standalone'
-  range?: { start: string; end: string }
+  range?: { start?: string; end?: string; chapter?: string; [key: string]: string | undefined }
 }
 
 export interface ProseSection {
@@ -130,6 +131,7 @@ export interface Part {
   source?: PieceSource
   verses: VerseLine[]
   annotations: Annotation[]
+  annotationText?: string
 }
 
 export interface Piece {

package/template/src/views/AboutView.vue

@@ -80,6 +80,7 @@ function goHome() { router.push('/') }
   background: var(--paper);
   scrollbar-width: thin;
   scrollbar-color: var(--gold) transparent;
+  scroll-snap-type: x proximity;
 }
 .v-page::-webkit-scrollbar { height: 4px; }
 .v-page::-webkit-scrollbar-thumb { background: var(--gold); border-radius: 2px; }
@@ -161,6 +162,11 @@ function goHome() { router.push('/') }
   background: var(--surface);
   border: 1px solid var(--border-light);
   border-radius: 8px;
+  animation: cardEnter 0.5s var(--ease-out-expo, ease) both;
+}
+@keyframes cardEnter {
+  from { opacity: 0; transform: translateY(12px); }
+  to { opacity: 1; transform: translateY(0); }
 }
 .h-about-block:last-child { margin-bottom: 0; }
 .h-about-block h2 {

package/template/src/views/BookHome.vue

@@ -154,6 +154,7 @@ function scrollToCatalog() {
   background: linear-gradient(90deg, var(--paper) 0%, var(--paper-warm) 100%);
   scrollbar-width: thin;
   scrollbar-color: var(--gold) transparent;
+  scroll-snap-type: x proximity;
 }
 .v-page::-webkit-scrollbar { height: 4px; }
 .v-page::-webkit-scrollbar-thumb { background: var(--gold); border-radius: 2px; }

package/template/src/views/LibraryHome.vue

@@ -125,9 +125,10 @@ function openBook(bookId: string) {
         <h2 class="lib-group-title">{{ group.category }}</h2>
         <div class="lib-grid">
           <div
-            v-for="book in group.books"
+            v-for="(book, bi) in group.books"
             :key="book.id"
             class="lib-card"
+            :style="{ animationDelay: bi * 0.06 + 's' }"
             @click="openBook(book.id)"
           >
             <div class="lib-card-accent"></div>
@@ -163,6 +164,7 @@ function openBook(bookId: string) {
   background: linear-gradient(90deg, var(--paper) 0%, var(--paper-warm) 100%);
   scrollbar-width: thin;
   scrollbar-color: var(--gold) transparent;
+  scroll-snap-type: x proximity;
 }
 .v-page::-webkit-scrollbar { height: 4px; }
 .v-page::-webkit-scrollbar-thumb { background: var(--gold); border-radius: 2px; }
@@ -391,9 +393,14 @@ function openBook(bookId: string) {
   border: 1px solid var(--border-light);
   border-radius: 8px;
   cursor: pointer;
-  transition: all 0.3s ease;
+  transition: all 0.3s var(--ease-out-expo, ease);
   position: relative;
   background: var(--surface);
+  animation: cardEnter 0.5s var(--ease-out-expo, ease) both;
+}
+@keyframes cardEnter {
+  from { opacity: 0; transform: translateY(12px); }
+  to { opacity: 1; transform: translateY(0); }
 }
 .lib-card:hover { border-color: var(--gold); box-shadow: 0 4px 20px rgba(var(--shadow-rgb), 0.1); }
 .lib-card-accent {

package/template/src/views/PieceView.vue

@@ -14,6 +14,7 @@ import AnnotationTooltip from '../components/AnnotationTooltip.vue'
 import AnnotationControlBar from '../components/AnnotationControlBar.vue'
 import SideNav from '../components/SideNav.vue'
 import PartGroup from '../components/PartGroup.vue'
+import ReadingProgress from '../components/ReadingProgress.vue'
 import type { Piece, Annotation, AnnotationLayer, Part } from '../types'
 
 const props = defineProps<{ bookId: string; num: string | number }>()
@@ -59,6 +60,17 @@ useTitle(pageTitle.value)
 
 const isVertical = computed(() => layout.value === 'vertical')
 
+const totalAnnotationCount = computed(() => {
+  if (!piece.value) return 0
+  let count = piece.value.annotations.length
+  if (piece.value.annotationLayers) {
+    for (const layer of piece.value.annotationLayers) {
+      count += layer.annotations.length
+    }
+  }
+  return count
+})
+
 const annotationLayers = computed<AnnotationLayer[]>(() => piece.value?.annotationLayers || [])
 const hasLayers = computed(() => annotationLayers.value.length > 1)
 const activeLayerIds = ref<string[]>([])
@@ -242,6 +254,7 @@ function tcy(n: number): string {
         @back="goBack"
         @home="goHome"
       />
+      <ReadingProgress vertical :scroll-container="vPageRef" />
       <div ref="vPageRef" class="v-page">
         <section ref="vTitleRef" class="v-title-col">
           <h1 class="v-poem-title">{{ piece.title }}</h1>
@@ -262,7 +275,7 @@ function tcy(n: number): string {
             </template>
             <template v-else>
               <span class="v-meta-item" v-html="tcy(piece.verses.length) + ' 段'" />
-              <span class="v-meta-item" v-html="piece.annotations.length > 0 ? tcy(piece.annotations.length) + ' 注' : '無注'" />
+              <span class="v-meta-item" v-html="totalAnnotationCount > 0 ? tcy(totalAnnotationCount) + ' 注' : '無注'" />
             </template>
           </div>
         </section>
@@ -392,6 +405,7 @@ function tcy(n: number): string {
 
     <!-- ═══════ 橫排模式 ═══════ -->
     <div v-else class="h-root">
+      <ReadingProgress />
       <div class="h-page">
         <nav class="h-nav">
           <div class="h-nav-inner">
@@ -419,7 +433,7 @@ function tcy(n: number): string {
               </template>
               <template v-else>
                 <span class="h-tag">{{ piece.verses.length }} 段</span>
-                <span class="h-tag">{{ piece.annotations.length > 0 ? piece.annotations.length + ' 注' : '無注' }}</span>
+                <span class="h-tag">{{ totalAnnotationCount > 0 ? totalAnnotationCount + ' 注' : '無注' }}</span>
               </template>
             </div>
           </div>
@@ -537,8 +551,8 @@ function tcy(n: number): string {
     </div>
   </div>
 
-  <div v-else style="text-align:center;padding-top:120px">
-    <p style="font-size:18px;color:var(--ink-faint)">載入中…</p>
+  <div v-else class="loading">
+    <div class="loading-seal">詩</div>
   </div>
 </template>
 
@@ -556,6 +570,7 @@ function tcy(n: number): string {
   background: var(--paper);
   scrollbar-width: thin;
   scrollbar-color: var(--gold) transparent;
+  scroll-snap-type: x proximity;
 }
 .v-page::-webkit-scrollbar { height: 4px; }
 .v-page::-webkit-scrollbar-thumb { background: var(--gold); border-radius: 2px; }
@@ -571,6 +586,7 @@ function tcy(n: number): string {
   gap: 16px;
   padding: 40px 24px;
   border-right: 1px solid var(--border);
+  scroll-snap-align: start;
 }
 .v-poem-title {
   font-size: 40px; font-weight: 900;
@@ -659,6 +675,7 @@ function tcy(n: number): string {
   justify-content: center;
   padding: 24px 12px;
   gap: 32px;
+  scroll-snap-align: start;
 }
 .v-nav-spacer { flex: 1; }
 .v-nav-btn {
@@ -790,7 +807,9 @@ function tcy(n: number): string {
 
 .h-overlay {
   position: fixed; inset: 0;
-  background: rgba(var(--shadow-rgb), 0.3);
+  background: rgba(var(--shadow-rgb), 0.2);
+  backdrop-filter: blur(8px);
+  -webkit-backdrop-filter: blur(8px);
   z-index: 200;
   display: flex; justify-content: flex-end;
   animation: fadeIn 0.2s ease;
@@ -837,7 +856,9 @@ function tcy(n: number): string {
 
 .v-overlay {
   position: fixed; inset: 0;
-  background: rgba(var(--shadow-rgb), 0.3);
+  background: rgba(var(--shadow-rgb), 0.2);
+  backdrop-filter: blur(8px);
+  -webkit-backdrop-filter: blur(8px);
   z-index: 200;
   display: flex; justify-content: flex-start;
   animation: fadeIn 0.2s ease;
@@ -894,6 +915,25 @@ function tcy(n: number): string {
   margin-left: 12px;
 }
 
+.loading {
+  display: flex; flex-direction: column;
+  align-items: center; justify-content: center;
+  height: 100vh;
+}
+.loading-seal {
+  width: 56px; height: 56px;
+  border: 2px solid var(--vermillion);
+  border-radius: 4px;
+  display: flex; align-items: center; justify-content: center;
+  font-size: 28px; font-weight: 900;
+  color: var(--vermillion);
+  animation: pulse 1.2s ease-in-out infinite;
+}
+@keyframes pulse {
+  0%, 100% { opacity: 0.3; }
+  50% { opacity: 1; }
+}
+
 @media (max-width: 768px) {
   .h-content { padding: 30px 20px; }
 }