@hanology/cham-browser 0.4.71 → 0.4.73

package/package.json

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

package/template/__tests__/appStructure.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'fs'
+import { resolve } from 'path'
+
+const appVue = readFileSync(
+  resolve(__dirname, '../src/App.vue'),
+  'utf-8',
+)
+
+describe('App.vue structure', () => {
+  it('wraps router-view in Suspense', () => {
+    expect(appVue).toContain('<Suspense')
+  })
+
+  it('Suspense has a fallback slot with route-loading', () => {
+    expect(appVue).toContain('#fallback')
+    expect(appVue).toContain('route-loading')
+  })
+
+  it('component uses route.fullPath as key', () => {
+    expect(appVue).toMatch(/:key="route\.fullPath"/)
+  })
+
+  it('renders <component :is="Component" /> inside Suspense', () => {
+    expect(appVue).toContain(':is="Component"')
+  })
+
+  it('has page-fade CSS transition classes', () => {
+    expect(appVue).toContain('.page-fade-enter-active')
+    expect(appVue).toContain('.page-fade-leave-active')
+  })
+
+  it('does NOT wrap Suspense in Transition (causes async nav failures)', () => {
+    // Transition + Suspense combination breaks async component navigation
+    expect(appVue).not.toMatch(/<Transition[^>]*>[\s\S]*<Suspense/)
+  })
+})

package/template/__tests__/useBook.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { BookMeta, Piece } from '../src/types'
+
+function makePiece(overrides: Partial<Piece> & { num: number }): Piece {
+  return {
+    bookId: 'test',
+    title: 'Test Piece',
+    author: 'Tester',
+    authorId: 'tester',
+    era: 'Tang',
+    genre: 'poetry',
+    verses: [{ text: '床前明月光' }],
+    sections: {},
+    annotations: [],
+    ...overrides,
+  }
+}
+
+function makeMeta(overrides: Partial<BookMeta> = {}): BookMeta {
+  return {
+    id: 'test',
+    title: 'Test Book',
+    genre: 'poetry',
+    count: 2,
+    ...overrides,
+  }
+}
+
+describe('useBook', () => {
+  beforeEach(() => {
+    vi.resetModules()
+  })
+
+  it('getPiece returns piece by num after load', async () => {
+    const pieces = [
+      makePiece({ num: 1, title: 'First' }),
+      makePiece({ num: 2, title: 'Second' }),
+    ]
+    vi.stubGlobal('fetch', () =>
+      Promise.resolve({ json: () => Promise.resolve({ meta: makeMeta(), pieces }) })
+    )
+    vi.stubGlobal('import.meta', { env: { SSR: false } })
+
+    const { useBook } = await import('../src/composables/useBook')
+    const { load, getPiece, loaded } = useBook()
+    expect(loaded.value).toBe(false)
+    await load('test')
+    expect(loaded.value).toBe(true)
+    expect(getPiece(1)?.title).toBe('First')
+    expect(getPiece(2)?.title).toBe('Second')
+    expect(getPiece(3)).toBeUndefined()
+  })
+
+  it('getAdjacentNums returns prev and next', async () => {
+    const pieces = [
+      makePiece({ num: 1 }),
+      makePiece({ num: 3 }),
+      makePiece({ num: 7 }),
+    ]
+    vi.stubGlobal('fetch', () =>
+      Promise.resolve({ json: () => Promise.resolve({ meta: makeMeta(), pieces }) })
+    )
+    vi.stubGlobal('import.meta', { env: { SSR: false } })
+
+    const { useBook } = await import('../src/composables/useBook')
+    const { load, getAdjacentNums } = useBook()
+    await load('test')
+
+    expect(getAdjacentNums(1)).toEqual({ prev: null, next: 3 })
+    expect(getAdjacentNums(3)).toEqual({ prev: 1, next: 7 })
+    expect(getAdjacentNums(7)).toEqual({ prev: 3, next: null })
+  })
+
+  it('getPiecesByAuthor filters by author name', async () => {
+    const pieces = [
+      makePiece({ num: 1, author: '李白' }),
+      makePiece({ num: 2, author: '杜甫' }),
+      makePiece({ num: 3, author: '李白' }),
+    ]
+    vi.stubGlobal('fetch', () =>
+      Promise.resolve({ json: () => Promise.resolve({ meta: makeMeta(), pieces }) })
+    )
+    vi.stubGlobal('import.meta', { env: { SSR: false } })
+
+    const { useBook } = await import('../src/composables/useBook')
+    const { load, getPiecesByAuthor } = useBook()
+    await load('test')
+
+    const byLi = getPiecesByAuthor('李白')
+    expect(byLi).toHaveLength(2)
+    expect(byLi.every(p => p.author === '李白')).toBe(true)
+  })
+
+  it('cleans hard wraps in piece sections', async () => {
+    const pieces = [
+      makePiece({
+        num: 1,
+        sections: { body: '第一行\n第二行\n\n第三段\n第四段' },
+      }),
+    ]
+    vi.stubGlobal('fetch', () =>
+      Promise.resolve({ json: () => Promise.resolve({ meta: makeMeta(), pieces }) })
+    )
+    vi.stubGlobal('import.meta', { env: { SSR: false } })
+
+    const { useBook } = await import('../src/composables/useBook')
+    const { load, getPiece } = useBook()
+    await load('test')
+
+    const p = getPiece(1)!
+    // Single newlines within paragraphs should be removed, double newlines preserved
+    expect(p.sections.body).toBe('第一行第二行\n\n第三段第四段')
+  })
+})

package/template/__tests__/useReadingMode.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { nextTick } from 'vue'
+
+// useReadingMode accesses localStorage and document at module level,
+// so we must mock them before importing.
+const localStorageStore: Record<string, string> = {}
+const attributeStore: Record<string, string> = {}
+
+vi.stubGlobal('localStorage', {
+  getItem: (k: string) => localStorageStore[k] ?? null,
+  setItem: (k: string, v: string) => { localStorageStore[k] = v },
+  removeItem: (k: string) => { delete localStorageStore[k] },
+  clear: () => Object.keys(localStorageStore).forEach(k => delete localStorageStore[k]),
+})
+
+vi.stubGlobal('document', {
+  documentElement: {
+    setAttribute: (k: string, v: string) => { attributeStore[k] = v },
+    getAttribute: (k: string) => attributeStore[k] ?? null,
+    style: {
+      setProperty: vi.fn(),
+    },
+  },
+})
+
+describe('useReadingMode', () => {
+  let useReadingMode: typeof import('../src/composables/useReadingMode').useReadingMode
+
+  beforeEach(() => {
+    // Clear stores
+    Object.keys(localStorageStore).forEach(k => delete localStorageStore[k])
+    Object.keys(attributeStore).forEach(k => delete attributeStore[k])
+    // Import fresh each time to exercise module-level init
+    vi.resetModules()
+  })
+
+  it('defaults to vertical layout when no saved preference', async () => {
+    const mod = await import('../src/composables/useReadingMode')
+    useReadingMode = mod.useReadingMode
+    const { layout } = useReadingMode()
+    expect(layout.value).toBe('vertical')
+  })
+
+  it('restores saved horizontal layout after nextTick', async () => {
+    localStorageStore.layout = 'horizontal'
+    const mod = await import('../src/composables/useReadingMode')
+    useReadingMode = mod.useReadingMode
+    const { layout } = useReadingMode()
+    // Module-level nextTick runs during import, so by now layout is restored
+    await nextTick()
+    expect(layout.value).toBe('horizontal')
+  })
+
+  it('toggleLayout switches between horizontal and vertical', async () => {
+    const mod = await import('../src/composables/useReadingMode')
+    useReadingMode = mod.useReadingMode
+    const { layout, toggleLayout } = useReadingMode()
+    expect(layout.value).toBe('vertical')
+    toggleLayout()
+    expect(layout.value).toBe('horizontal')
+    toggleLayout()
+    expect(layout.value).toBe('vertical')
+  })
+
+  it('cycleTheme rotates through themes', async () => {
+    const mod = await import('../src/composables/useReadingMode')
+    useReadingMode = mod.useReadingMode
+    const { theme, cycleTheme } = useReadingMode()
+    const themes = ['light', 'sepia', 'dark', 'oled']
+    expect(theme.value).toBe('light')
+    for (let i = 1; i <= 4; i++) {
+      cycleTheme()
+      expect(theme.value).toBe(themes[i % 4])
+    }
+  })
+
+  it('layout watcher writes to localStorage (not immediate)', async () => {
+    localStorageStore.layout = 'horizontal'
+    const mod = await import('../src/composables/useReadingMode')
+    useReadingMode = mod.useReadingMode
+    const { layout, setLayout } = useReadingMode()
+    // Layout watcher should NOT have overwritten saved value immediately
+    expect(localStorageStore.layout).toBe('horizontal')
+    await nextTick()
+    expect(localStorageStore.layout).toBe('horizontal')
+    // Now change layout — watcher should fire
+    setLayout('vertical')
+    await nextTick()
+    expect(localStorageStore.layout).toBe('vertical')
+  })
+
+  it('exposes all expected reactive refs and setters', async () => {
+    const mod = await import('../src/composables/useReadingMode')
+    useReadingMode = mod.useReadingMode
+    const r = useReadingMode()
+    expect(r.theme).toBeDefined()
+    expect(r.layout).toBeDefined()
+    expect(r.mainFontSize).toBeDefined()
+    expect(r.bodyFontSize).toBeDefined()
+    expect(r.annotationsVisible).toBeDefined()
+    expect(r.annotationPane).toBeDefined()
+    expect(r.setTheme).toBeTypeOf('function')
+    expect(r.cycleTheme).toBeTypeOf('function')
+    expect(r.setLayout).toBeTypeOf('function')
+    expect(r.toggleLayout).toBeTypeOf('function')
+    expect(r.setMainFontSize).toBeTypeOf('function')
+    expect(r.setBodyFontSize).toBeTypeOf('function')
+    expect(r.setAnnotationsVisible).toBeTypeOf('function')
+    expect(r.toggleAnnotationsVisible).toBeTypeOf('function')
+    expect(r.setAnnotationPane).toBeTypeOf('function')
+    expect(r.toggleAnnotationPane).toBeTypeOf('function')
+  })
+})

package/template/src/App.vue

@@ -52,17 +52,15 @@ function onKey(event: KeyboardEvent) {
 <template>
   <div @keydown="onKey">
     <router-view v-slot="{ Component, route }">
-      <Transition name="page-fade" mode="out-in">
-        <Suspense :key="route.fullPath">
-          <component :is="Component" />
-          <template #fallback>
-            <div class="route-loading">
-              <img v-if="logoUrl" :src="logoUrl" alt="" class="route-loading-logo" />
-              <div v-else class="route-loading-seal">文</div>
-            </div>
-          </template>
-        </Suspense>
-      </Transition>
+      <Suspense>
+        <component :is="Component" :key="route.fullPath" />
+        <template #fallback>
+          <div class="route-loading">
+            <img v-if="logoUrl" :src="logoUrl" alt="" class="route-loading-logo" />
+            <div v-else class="route-loading-seal">文</div>
+          </div>
+        </template>
+      </Suspense>
     </router-view>
     <!-- 橫排模式才顯示浮動設定鈕 -->
     <ReadingToolbar v-if="!isVertical" />

package/template/src/components/PartBlock.vue

@@ -2,6 +2,8 @@
 import { computed } from 'vue'
 import type { Annotation, VerseLine, PieceSource } from '../types'
 import { buildVerseAnnotations, renderAnnotatedText, resolveHoveredAnnotations } from '../composables/useAnnotationRenderer'
+import { parseAnnotationBlock } from '../utils/annotationParser'
+import PronunciationGroup from './PronunciationGroup.vue'
 
 const props = defineProps<{
   num: number
@@ -54,6 +56,10 @@ const sourceLabel = (() => {
   const r = props.source?.range as Record<string, string> | undefined
   return r?.chapter || ''
 })()
+
+const annotationEntries = computed(() =>
+  props.annotationText ? parseAnnotationBlock(props.annotationText) : []
+)
 </script>
 
 <template>
@@ -69,7 +75,22 @@ const sourceLabel = (() => {
         v-html="verseHtml(i)"
       />
     </div>
-    <div v-if="annotationText" class="part-annotations">
+    <div v-if="annotationText && annotationEntries.length > 0" class="part-annotations">
+      <div v-for="entry in annotationEntries" :key="entry.num" class="part-ann-entry">
+        <div class="part-ann-head">
+          <span class="part-ann-num">{{ entry.numDisplay }}</span>
+          <span class="part-ann-term">{{ entry.term }}</span>
+          <PronunciationGroup
+            v-for="seg in entry.pronSegments"
+            :key="seg.lang"
+            :segment="seg"
+            class="part-ann-pron"
+          />
+        </div>
+        <div v-if="entry.definition" class="part-ann-def">{{ entry.definition }}</div>
+      </div>
+    </div>
+    <div v-else-if="annotationText" class="part-annotations">
       <div v-for="line in annotationText.split('\n')" :key="line" class="part-ann-line">{{ line }}</div>
     </div>
   </div>
@@ -114,6 +135,59 @@ const sourceLabel = (() => {
   margin-top: 16px;
   padding-top: 12px;
   border-top: 1px dashed var(--border-light);
+  text-align: start;
+}
+
+.part-ann-entry {
+  padding: 12px 0;
+  border-bottom: 1px solid var(--border-light);
+}
+.part-ann-entry:last-child {
+  border-bottom: none;
+  padding-bottom: 0;
+}
+
+.part-ann-head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: 6px 10px;
+  margin-bottom: 4px;
+}
+
+.part-ann-num {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  border-radius: 4px;
+  background: var(--vermillion);
+  color: var(--paper);
+  font-family: var(--sans);
+  font-size: 12px;
+  font-weight: 700;
+  flex-shrink: 0;
+}
+
+.part-ann-term {
+  font-weight: 700;
+  font-size: 1.05em;
+  color: var(--ink);
+  padding: 2px 8px;
+  background: var(--surface-warm);
+  border-radius: 3px;
+}
+
+.part-ann-pron {
+  margin-left: 2px;
+}
+
+.part-ann-def {
+  color: var(--ink-mid);
+  line-height: 2;
+  white-space: pre-line;
+  padding-left: 32px;
 }
 
 .part-ann-line {
@@ -188,4 +262,36 @@ const sourceLabel = (() => {
   border-top: none;
   border-left: 1px dashed var(--border-light);
 }
+
+.part-block--vertical .part-ann-entry {
+  margin-bottom: 0;
+  margin-left: 16px;
+  padding: 0;
+  border-bottom: none;
+}
+
+.part-block--vertical .part-ann-head {
+  align-items: flex-start;
+  gap: 4px;
+}
+
+.part-block--vertical .part-ann-num {
+  width: auto;
+  height: auto;
+  border-radius: 0;
+  background: none;
+  color: var(--vermillion);
+  font-size: inherit;
+}
+
+.part-block--vertical .part-ann-term {
+  background: none;
+  padding: 0;
+  font-size: inherit;
+}
+
+.part-block--vertical .part-ann-def {
+  padding-left: 0;
+  margin-left: 12px;
+}
 </style>