@hanology/cham-browser 0.4.15 → 0.4.17

package/package.json

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

package/template/src/components/AnnotationPane.vue

@@ -0,0 +1,308 @@
+<script setup lang="ts">
+import { ref, watch, nextTick, onMounted, onBeforeUnmount } from 'vue'
+import { annotationToPronSegment } from '../utils/annotationParser'
+import { toChineseNumber } from '../utils/chineseNumber'
+import PronunciationGroup from './PronunciationGroup.vue'
+import type { Annotation } from '../types'
+
+const props = defineProps<{
+  visible: boolean
+  annotations: Annotation[]
+  headwords: Record<string, string>
+  layerLabels?: Record<string, string>
+  activeId: string
+}>()
+
+const emit = defineEmits<{
+  close: []
+  select: [ann: Annotation]
+}>()
+
+const bodyRef = ref<HTMLElement | null>(null)
+
+function getSegment(ann: Annotation) {
+  return annotationToPronSegment(ann)
+}
+
+function headword(ann: Annotation): string {
+  return props.headwords[ann.id] || ''
+}
+
+function kindLabel(ann: Annotation): string {
+  const map: Record<string, string> = {
+    pronunciation: '讀音',
+    semantic: '釋義',
+    etymology: '詞源',
+    note: '備注',
+    definition: '釋義',
+    commentary: '評註',
+    translation: '譯文',
+    person: '人名',
+    place: '地名',
+    event: '事件',
+    date: '紀年',
+    allusion: '典故',
+  }
+  return map[ann.kind] || ann.kind
+}
+
+function layerLabel(ann: Annotation): string {
+  if (!props.layerLabels || !ann.id) return ''
+  for (const [prefix, label] of Object.entries(props.layerLabels)) {
+    if (ann.id.startsWith(prefix)) return label
+  }
+  return ''
+}
+
+function onKeydown(e: KeyboardEvent) {
+  if (e.key === 'Escape' && props.visible) {
+    e.preventDefault()
+    emit('close')
+  }
+}
+
+watch(() => props.activeId, async (id) => {
+  if (!id || !props.visible) return
+  await nextTick()
+  const el = bodyRef.value?.querySelector(`[data-ann-id="${id}"]`)
+  if (el) el.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
+})
+
+onMounted(() => document.addEventListener('keydown', onKeydown))
+onBeforeUnmount(() => document.removeEventListener('keydown', onKeydown))
+</script>
+
+<template>
+  <Teleport to="body">
+    <Transition name="ann-pane">
+      <div v-if="visible && annotations.length" class="ann-pane">
+        <div class="ann-pane-header">
+          <span class="ann-pane-title">注釋</span>
+          <span class="ann-pane-count">{{ annotations.length }}</span>
+          <button class="ann-pane-close" @click="emit('close')" aria-label="關閉">
+            <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M18 6L6 18M6 6l12 12"/></svg>
+          </button>
+        </div>
+        <div ref="bodyRef" class="ann-pane-body">
+          <div
+            v-for="(ann, idx) in annotations"
+            :key="ann.id"
+            :data-ann-id="ann.id"
+            class="ann-pane-entry"
+            :class="{ active: activeId === ann.id, [ann.kind]: true }"
+            @click="emit('select', ann)"
+          >
+            <div class="ann-pane-entry-head">
+              <span class="ann-pane-idx">{{ toChineseNumber(idx + 1) }}</span>
+              <span v-if="headword(ann)" class="ann-pane-word">{{ headword(ann) }}</span>
+              <span class="ann-pane-kind" :class="ann.kind">{{ kindLabel(ann) }}</span>
+              <span v-if="layerLabel(ann)" class="ann-pane-layer">{{ layerLabel(ann) }}</span>
+            </div>
+            <div class="ann-pane-entry-body">
+              <PronunciationGroup v-if="getSegment(ann)" :segment="getSegment(ann)!" />
+              <div v-if="ann.text && ann.kind !== 'pronunciation'" class="ann-pane-text">{{ ann.text }}</div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </Transition>
+  </Teleport>
+</template>
+
+<style scoped>
+.ann-pane {
+  position: fixed;
+  left: 0;
+  top: 0;
+  width: 320px;
+  height: 100vh;
+  background: var(--surface-warm);
+  border-right: 1px solid var(--border);
+  z-index: 300;
+  display: flex;
+  flex-direction: column;
+  writing-mode: horizontal-tb;
+  box-shadow: 4px 0 24px rgba(var(--shadow-rgb), 0.06);
+}
+
+.ann-pane-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 16px 20px;
+  border-bottom: 1px solid var(--border-light);
+  background: var(--surface);
+  flex-shrink: 0;
+}
+
+.ann-pane-title {
+  font-family: var(--serif);
+  font-size: 18px;
+  font-weight: 900;
+  letter-spacing: 4px;
+  color: var(--ink);
+}
+
+.ann-pane-count {
+  font-family: var(--sans);
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--ink-faint);
+  background: var(--surface-warm);
+  border: 1px solid var(--border-light);
+  border-radius: 10px;
+  padding: 2px 8px;
+}
+
+.ann-pane-close {
+  margin-left: auto;
+  width: 24px;
+  height: 24px;
+  border: none;
+  border-radius: 4px;
+  background: transparent;
+  color: var(--ink-faint);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: all 0.15s;
+}
+
+.ann-pane-close:hover {
+  background: var(--ink);
+  color: var(--paper);
+}
+
+.ann-pane-body {
+  flex: 1;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding: 4px 0;
+}
+
+.ann-pane-entry {
+  padding: 12px 20px;
+  border-bottom: 1px solid var(--border-light);
+  border-left: 3px solid transparent;
+  cursor: pointer;
+  transition: all 0.15s;
+}
+
+.ann-pane-entry:hover {
+  background: var(--surface);
+}
+
+.ann-pane-entry.active {
+  border-left-color: var(--vermillion);
+  background: var(--surface);
+}
+
+.ann-pane-entry.active.pronunciation {
+  border-left-color: var(--jade);
+}
+
+.ann-pane-entry-head {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-bottom: 4px;
+  flex-wrap: wrap;
+}
+
+.ann-pane-idx {
+  font-family: var(--serif);
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--vermillion);
+  flex-shrink: 0;
+}
+
+.ann-pane-entry.active.pronunciation .ann-pane-idx {
+  color: var(--jade);
+}
+
+.ann-pane-word {
+  font-family: var(--serif);
+  font-size: 18px;
+  font-weight: 900;
+  letter-spacing: 2px;
+  color: var(--ink);
+}
+
+.ann-pane-kind {
+  display: inline-block;
+  padding: 1px 6px;
+  border-radius: 3px;
+  font-size: 10px;
+  font-family: var(--sans);
+  font-weight: 700;
+  letter-spacing: 1px;
+  line-height: 1.5;
+}
+
+.ann-pane-kind.pronunciation { background: var(--jade); color: #fff; }
+.ann-pane-kind.semantic { background: var(--vermillion); color: #fff; }
+.ann-pane-kind.etymology { background: #6b5b95; color: #fff; }
+.ann-pane-kind.note,
+.ann-pane-kind.definition { background: var(--ink); color: var(--paper); }
+.ann-pane-kind.commentary { background: #c0392b; color: #fff; }
+.ann-pane-kind.translation { background: #2c6e49; color: #fff; }
+.ann-pane-kind.person { background: var(--ann-person); color: #fff; }
+.ann-pane-kind.place { background: var(--ann-place); color: #fff; }
+.ann-pane-kind.event { background: var(--ann-event); color: #fff; }
+.ann-pane-kind.date { background: var(--ann-date); color: #fff; }
+.ann-pane-kind.allusion { background: var(--ann-allusion); color: #fff; }
+
+.ann-pane-layer {
+  font-size: 10px;
+  font-family: var(--sans);
+  color: var(--ink-faint);
+  padding: 1px 5px;
+  border: 1px solid var(--border-light);
+  border-radius: 2px;
+}
+
+.ann-pane-entry-body {
+  padding-left: 2px;
+}
+
+.ann-pane-text {
+  font-size: 14px;
+  color: var(--ink-mid);
+  line-height: 1.8;
+  letter-spacing: 0.5px;
+  white-space: pre-line;
+}
+
+/* Transition */
+.ann-pane-enter-active {
+  transition: transform 0.3s cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+.ann-pane-leave-active {
+  transition: transform 0.2s ease;
+}
+.ann-pane-enter-from,
+.ann-pane-leave-to {
+  transform: translateX(-100%);
+}
+
+@media (max-width: 768px) {
+  .ann-pane {
+    width: 100%;
+    height: auto;
+    max-height: 55vh;
+    top: auto;
+    bottom: 0;
+    left: 0;
+    border-right: none;
+    border-top: 1px solid var(--border);
+    border-radius: 14px 14px 0 0;
+    box-shadow: 0 -4px 24px rgba(var(--shadow-rgb), 0.08);
+  }
+  .ann-pane-enter-from,
+  .ann-pane-leave-to {
+    transform: translateY(100%);
+  }
+}
+</style>

package/template/src/components/AnnotationTooltip.vue

@@ -280,6 +280,7 @@ onBeforeUnmount(() => {
   overflow: hidden;
   backdrop-filter: blur(8px);
   -webkit-backdrop-filter: blur(8px);
+  writing-mode: horizontal-tb;
 }
 
 .ann-card-close {
@@ -347,6 +348,7 @@ onBeforeUnmount(() => {
   z-index: 1000;
   display: flex;
   flex-direction: column;
+  writing-mode: horizontal-tb;
 }
 
 .ann-sheet-handle {

package/template/src/components/ReadingToolbar.vue

@@ -4,7 +4,7 @@ import { useReadingMode, THEMES, THEME_LABELS, FONT_SIZES } from '../composables
 import type { LayoutMode, FontSize } from '../composables/useReadingMode'
 import { useI18n, LOCALE_LABELS, type Locale } from '../composables/useI18n'
 
-const { theme, layout, mainFontSize, bodyFontSize, annotationsVisible, setTheme, setLayout, setMainFontSize, setBodyFontSize, setAnnotationsVisible } = useReadingMode()
+const { theme, layout, mainFontSize, bodyFontSize, annotationsVisible, annotationPane, setTheme, setLayout, setMainFontSize, setBodyFontSize, setAnnotationsVisible, setAnnotationPane } = useReadingMode()
 const { t, setLocale, locale, availableLocales, localeLabels } = useI18n()
 const open = ref(false)
 
@@ -49,6 +49,21 @@ function close() { open.value = false }
           >{{ t('settings.hide') }}</button>
         </div>
       </div>
+      <div class="rt-group">
+        <div class="rt-label">{{ t('settings.annotationPane') }}</div>
+        <div class="rt-options">
+          <button
+            class="rt-opt"
+            :class="{ active: annotationPane }"
+            @click="setAnnotationPane(true)"
+          >{{ t('settings.show') }}</button>
+          <button
+            class="rt-opt"
+            :class="{ active: !annotationPane }"
+            @click="setAnnotationPane(false)"
+          >{{ t('settings.hide') }}</button>
+        </div>
+      </div>
       <div class="rt-group">
         <div class="rt-label">{{ t('settings.theme') }}</div>
         <div class="rt-options">

package/template/src/composables/useI18n.ts

@@ -27,6 +27,8 @@ const messages: Record<Locale, Record<string, string>> = {
     'settings.annotations': '注釋',
     'settings.show': '顯示',
     'settings.hide': '隱藏',
+    'settings.annotationPane': '注釋面板',
+    'annotation.all': '注釋',
     'piece.stanzas': '段',
     'piece.notes': '注',
     'piece.noNotes': '無注',
@@ -85,6 +87,8 @@ const messages: Record<Locale, Record<string, string>> = {
     'settings.annotations': '注释',
     'settings.show': '显示',
     'settings.hide': '隐藏',
+    'settings.annotationPane': '注释面板',
+    'annotation.all': '注释',
     'piece.stanzas': '段',
     'piece.notes': '注',
     'piece.noNotes': '无注',
@@ -143,6 +147,8 @@ const messages: Record<Locale, Record<string, string>> = {
     'settings.annotations': 'Annotations',
     'settings.show': 'Show',
     'settings.hide': 'Hide',
+    'settings.annotationPane': 'Annotation Panel',
+    'annotation.all': 'Annotations',
     'piece.stanzas': 'stanzas',
     'piece.notes': 'notes',
     'piece.noNotes': 'No notes',

package/template/src/composables/useReadingMode.ts

@@ -20,6 +20,7 @@ const layout = ref<LayoutMode>('vertical')
 const mainFontSize = ref<FontSize>(24)
 const bodyFontSize = ref<FontSize>(16)
 const annotationsVisible = ref(true)
+const annotationPane = ref(false)
 
 if (!import.meta.env.SSR) {
   // Theme and font sizes only affect CSS, safe to apply before hydration
@@ -35,6 +36,9 @@ if (!import.meta.env.SSR) {
   const savedAnnVis = localStorage.getItem('annotationsVisible')
   if (savedAnnVis === 'false') annotationsVisible.value = false
 
+  const savedAnnPane = localStorage.getItem('annotationPane')
+  if (savedAnnPane === 'true') annotationPane.value = true
+
   // Layout controls v-if/v-else DOM structure — must defer to after hydration
   // to avoid SSR/client mismatch (SSR always renders vertical)
   nextTick(() => {
@@ -65,6 +69,10 @@ if (!import.meta.env.SSR) {
   watch(annotationsVisible, v => {
     localStorage.setItem('annotationsVisible', String(v))
   })
+
+  watch(annotationPane, v => {
+    localStorage.setItem('annotationPane', String(v))
+  })
 }
 
 export function useReadingMode() {
@@ -81,5 +89,7 @@ export function useReadingMode() {
   function setBodyFontSize(s: FontSize) { bodyFontSize.value = s }
   function setAnnotationsVisible(v: boolean) { annotationsVisible.value = v }
   function toggleAnnotationsVisible() { annotationsVisible.value = !annotationsVisible.value }
-  return { theme, layout, mainFontSize, bodyFontSize, annotationsVisible, setTheme, cycleTheme, setLayout, toggleLayout, setMainFontSize, setBodyFontSize, setAnnotationsVisible, toggleAnnotationsVisible }
+  function setAnnotationPane(v: boolean) { annotationPane.value = v }
+  function toggleAnnotationPane() { annotationPane.value = !annotationPane.value }
+  return { theme, layout, mainFontSize, bodyFontSize, annotationsVisible, annotationPane, setTheme, cycleTheme, setLayout, toggleLayout, setMainFontSize, setBodyFontSize, setAnnotationsVisible, toggleAnnotationsVisible, setAnnotationPane, toggleAnnotationPane }
 }

package/template/src/views/PieceView.vue

@@ -12,6 +12,7 @@ import VerticalScroll from '../components/VerticalScroll.vue'
 import HorizontalDisplay from '../components/HorizontalDisplay.vue'
 import SectionBlock from '../components/SectionBlock.vue'
 import AnnotationTooltip from '../components/AnnotationTooltip.vue'
+import AnnotationPane from '../components/AnnotationPane.vue'
 import AnnotationControlBar from '../components/AnnotationControlBar.vue'
 import SideNav from '../components/SideNav.vue'
 import PartGroup from '../components/PartGroup.vue'
@@ -24,7 +25,7 @@ const router = useRouter()
 const { getPiece, pieces, meta, load, getAdjacentNums } = useBook()
 await load(props.bookId)
 
-const { layout, annotationsVisible: prefAnnotationsVisible } = useReadingMode()
+const { layout, annotationsVisible: prefAnnotationsVisible, annotationPane } = useReadingMode()
 const vPageRef = ref<HTMLElement | null>(null)
 const vScroll = useHorizontalScroll(vPageRef)
 const { t } = useI18n()
@@ -96,6 +97,51 @@ const annotationLayers = computed<AnnotationLayer[]>(() => piece.value?.annotati
 const hasLayers = computed(() => annotationLayers.value.length > 1)
 const activeLayerIds = ref<string[]>([])
 const annotationsVisible = prefAnnotationsVisible
+const paneVisible = ref(false)
+const paneActiveId = ref('')
+
+function onAnnotationHover(event: MouseEvent, annotations: Annotation[]) {
+  if (annotationPane.value && isVertical.value) {
+    paneActiveId.value = annotations[0]?.id || ''
+  } else {
+    interaction.onHover(event, annotations)
+  }
+}
+function onAnnotationLeave() {
+  if (annotationPane.value && isVertical.value) return
+  interaction.onLeave()
+}
+function onAnnotationTap(event: MouseEvent, annotations: Annotation[]) {
+  if (annotationPane.value && isVertical.value) {
+    if (!paneVisible.value) paneVisible.value = true
+    paneActiveId.value = annotations[0]?.id || ''
+  } else {
+    interaction.onTap(event, annotations)
+  }
+}
+function onPaneSelect(ann: Annotation) {
+  const el = document.querySelector(`[data-ann-ids*="${ann.id}"]`) as HTMLElement | null
+  if (el) {
+    el.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' })
+    el.classList.add('ann-flash')
+    setTimeout(() => el.classList.remove('ann-flash'), 1500)
+  }
+}
+const annotationHeadwords = computed(() => {
+  const result: Record<string, string> = {}
+  for (const ann of mergedAnnotations.value) {
+    result[ann.id] = getHeadword(ann)
+  }
+  return result
+})
+
+watch([annotationPane, isVertical], ([pane, vert]) => {
+  if (pane && vert) {
+    interaction.dismiss()
+  } else {
+    paneVisible.value = false
+  }
+})
 
 function initLayers() {
   if (hasLayers.value && activeLayerIds.value.length === 0) {
@@ -300,7 +346,8 @@ function tcy(n: number): string {
 </script>
 
 <template>
-  <div v-if="piece">
+  <template v-if="piece">
+  <div>
     <!-- ═══════ 直排模式 ═══════ -->
     <div v-if="isVertical" class="v-root">
       <SideNav
@@ -337,6 +384,16 @@ function tcy(n: number): string {
           </div>
         </section>
 
+        <div class="v-inline-nav">
+          <button v-if="adjacent.next !== null" class="v-inav" @click="navigate(1)" :title="t('piece.next')">
+            ▼
+          </button>
+          <span v-else class="v-inav-spacer" />
+          <button v-if="adjacent.prev !== null" class="v-inav" @click="navigate(-1)" :title="t('piece.previous')">
+            ▲
+          </button>
+        </div>
+
         <section v-if="isMultiPart" class="v-poem-col v-multipart">
           <PartGroup
             v-for="group in partGroups"
@@ -344,9 +401,9 @@ function tcy(n: number): string {
             :label="group.label"
             :parts="group.parts"
             :vertical="true"
-            @annotation-hover="interaction.onHover"
-            @annotation-leave="interaction.onLeave"
-            @annotation-tap="interaction.onTap"
+            @annotation-hover="onAnnotationHover"
+            @annotation-leave="onAnnotationLeave"
+            @annotation-tap="onAnnotationTap"
           />
         </section>
 
@@ -357,9 +414,9 @@ function tcy(n: number): string {
             :verses="piece.verses"
             :author-initial="piece.author?.charAt(0) || '詩'"
             :annotations="mergedAnnotations"
-            @annotation-hover="interaction.onHover"
-            @annotation-leave="interaction.onLeave"
-            @annotation-tap="interaction.onTap"
+            @annotation-hover="onAnnotationHover"
+            @annotation-leave="onAnnotationLeave"
+            @annotation-tap="onAnnotationTap"
             @open-author="openAuthorPane"
           />
         </section>
@@ -431,17 +488,20 @@ function tcy(n: number): string {
         </nav>
       </div>
 
-      <AnnotationTooltip
-        :visible="interaction.visible"
-        :annotations="interaction.items"
-        :headword="interaction.headword"
+      <AnnotationPane
+        v-if="annotationPane"
+        :visible="paneVisible"
+        :annotations="mergedAnnotations"
+        :headwords="annotationHeadwords"
         :layer-labels="layerLabels"
-        :style="interaction.style"
-        :vertical="true"
-        @close="interaction.dismiss"
-        @tooltip-enter="interaction.onTooltipEnter"
-        @tooltip-leave="interaction.onTooltipLeave"
+        :active-id="paneActiveId"
+        @close="paneVisible = false"
+        @select="onPaneSelect"
       />
+
+      <Teleport to="body">
+        <Transition name="overlay">
+          <div v-if="authorPaneOpen" class="v-overlay" @click="closeAuthorPane">
             <div class="v-author-pane" @click.stop>
               <button class="v-pane-close" @click="closeAuthorPane">✕</button>
               <div class="v-pane-header">
@@ -596,18 +656,6 @@ function tcy(n: number): string {
         </div>
       </div>
 
-      <AnnotationTooltip
-        :visible="interaction.visible"
-        :annotations="interaction.items"
-        :headword="interaction.headword"
-        :layer-labels="layerLabels"
-        :style="interaction.style"
-        :vertical="false"
-        @close="interaction.dismiss"
-        @tooltip-enter="interaction.onTooltipEnter"
-        @tooltip-leave="interaction.onTooltipLeave"
-      />
-
       <BackToTop />
 
       <Teleport to="body">
@@ -656,6 +704,19 @@ function tcy(n: number): string {
     </div>
   </div>
 
+  <AnnotationTooltip
+    v-if="piece && !(annotationPane && isVertical)"
+    :visible="interaction.visible"
+    :annotations="interaction.items"
+    :headword="interaction.headword"
+    :layer-labels="layerLabels"
+    :style="interaction.style"
+    @close="interaction.dismiss"
+    @tooltip-enter="interaction.onTooltipEnter"
+    @tooltip-leave="interaction.onTooltipLeave"
+  />
+  </template>
+
   <div v-else class="page-loading">
     <img v-if="CHAM_LOGO_URL" :src="CHAM_LOGO_URL" alt="" class="page-loading-logo" />
     <div v-else class="page-loading-seal">文</div>
@@ -1228,6 +1289,55 @@ function tcy(n: number): string {
 .v-poem-author:active { color: var(--vermillion); }
 .h-author-link:active { color: var(--vermillion); }
 
+/* ─── 直排行內導航 ─── */
+.v-inline-nav {
+  writing-mode: horizontal-tb;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  flex-shrink: 0;
+  height: 100vh;
+  align-items: center;
+  justify-content: center;
+  padding: 0 6px;
+}
+.v-inav {
+  width: 30px;
+  height: 44px;
+  border: 1px solid var(--border-light);
+  border-radius: 6px;
+  background: var(--surface);
+  color: var(--ink-faint);
+  font-size: 14px;
+  cursor: pointer;
+  transition: all 0.15s;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.v-inav:hover {
+  border-color: var(--vermillion);
+  color: var(--vermillion);
+  background: var(--surface-warm);
+  box-shadow: 0 2px 8px rgba(var(--shadow-rgb), 0.06);
+}
+.v-inav:active {
+  transform: scale(0.94);
+}
+.v-inav-spacer {
+  width: 30px;
+  height: 44px;
+}
+
+/* ─── 注釋閃爍 ─── */
+:deep(.ann-flash) {
+  animation: ann-flash-anim 1.2s ease-out;
+}
+@keyframes ann-flash-anim {
+  0% { background: rgba(194, 58, 43, 0.2); }
+  100% { background: transparent; }
+}
+
 /* ═══════ 行動裝置適配 ═══════ */
 
 @media (max-width: 768px) {