@hanology/cham-browser 0.2.2 → 0.3.0

package/template/__tests__/annotationTooltip.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { resolveHoveredAnnotations, useAnnotationTooltip } from '../src/composables/useAnnotationRenderer'
+import type { Annotation } from '../src/types'
+
+function makeAnn(overrides: Partial<Annotation> & { id: string; kind: Annotation['kind'] }): Annotation {
+  return {
+    text: 'test',
+    range: { scope: 'verse', verseIndex: 0, start: 0, end: 1 },
+    ...overrides,
+  }
+}
+
+function createMockEvent(target: HTMLElement): MouseEvent {
+  return { target } as MouseEvent
+}
+
+function createAnnTarget(ids: string[], kinds: string): HTMLElement {
+  const el = document.createElement('span')
+  el.className = `ann-target ${kinds}`
+  el.setAttribute('data-ann-ids', ids.join(','))
+  el.textContent = 'test text'
+  return el
+}
+
+describe('resolveHoveredAnnotations', () => {
+  const annotations: Annotation[] = [
+    makeAnn({ id: 'a1', kind: 'semantic' }),
+    makeAnn({ id: 'p1', kind: 'pronunciation' }),
+    makeAnn({ id: 'a2', kind: 'semantic' }),
+  ]
+
+  it('returns null when target is not an ann-target element', () => {
+    const plain = document.createElement('span')
+    const result = resolveHoveredAnnotations(createMockEvent(plain), annotations)
+    expect(result).toBeNull()
+  })
+
+  it('returns matched annotations by id', () => {
+    const target = createAnnTarget(['a1'], 'semantic')
+    // Mock closest to return itself
+    target.closest = vi.fn().mockReturnValue(target)
+    const result = resolveHoveredAnnotations(createMockEvent(target), annotations)
+    expect(result).toHaveLength(1)
+    expect(result![0].id).toBe('a1')
+  })
+
+  it('returns multiple annotations for overlapping targets', () => {
+    const target = createAnnTarget(['a1', 'p1'], 'semantic pronunciation')
+    target.closest = vi.fn().mockReturnValue(target)
+    const result = resolveHoveredAnnotations(createMockEvent(target), annotations)
+    expect(result).toHaveLength(2)
+    const ids = result!.map(a => a.id).sort()
+    expect(ids).toEqual(['a1', 'p1'])
+  })
+
+  it('returns null when no matching annotation found', () => {
+    const target = createAnnTarget(['unknown'], 'semantic')
+    target.closest = vi.fn().mockReturnValue(target)
+    const result = resolveHoveredAnnotations(createMockEvent(target), annotations)
+    expect(result).toBeNull()
+  })
+})
+
+describe('useAnnotationTooltip', () => {
+  beforeEach(() => {
+    // Mock window.innerWidth for desktop
+    Object.defineProperty(window, 'innerWidth', { value: 1024, writable: true, configurable: true })
+    Object.defineProperty(window, 'innerHeight', { value: 768, writable: true, configurable: true })
+  })
+
+  it('starts hidden', () => {
+    const { visible } = useAnnotationTooltip()
+    expect(visible.value).toBe(false)
+  })
+
+  it('shows tooltip on show()', () => {
+    const { visible, items, show } = useAnnotationTooltip()
+    const target = createAnnTarget(['a1'], 'semantic')
+    target.getBoundingClientRect = vi.fn().mockReturnValue({
+      left: 100, top: 200, bottom: 230, right: 150, width: 50, height: 30,
+    })
+    const anns = [makeAnn({ id: 'a1', kind: 'semantic' })]
+    show(createMockEvent(target), anns)
+    expect(visible.value).toBe(true)
+    expect(items.value).toEqual(anns)
+  })
+
+  it('hides tooltip on hide()', () => {
+    const { visible, show, hide } = useAnnotationTooltip()
+    const target = createAnnTarget(['a1'], 'semantic')
+    target.getBoundingClientRect = vi.fn().mockReturnValue({
+      left: 100, top: 200, bottom: 230, right: 150, width: 50, height: 30,
+    })
+    show(createMockEvent(target), [makeAnn({ id: 'a1', kind: 'semantic' })])
+    expect(visible.value).toBe(true)
+    hide()
+    expect(visible.value).toBe(false)
+  })
+
+  it('toggle shows when not visible', () => {
+    const { visible, toggle } = useAnnotationTooltip()
+    const target = createAnnTarget(['a1'], 'semantic')
+    target.getBoundingClientRect = vi.fn().mockReturnValue({
+      left: 100, top: 200, bottom: 230, right: 150, width: 50, height: 30,
+    })
+    expect(visible.value).toBe(false)
+    toggle(createMockEvent(target), [makeAnn({ id: 'a1', kind: 'semantic' })])
+    expect(visible.value).toBe(true)
+  })
+
+  describe('mobile toggle behavior', () => {
+    beforeEach(() => {
+      Object.defineProperty(window, 'innerWidth', { value: 375, writable: true, configurable: true })
+    })
+
+    it('dismisses on toggle when same annotation on mobile', () => {
+      const { visible, show, toggle } = useAnnotationTooltip()
+      const target = createAnnTarget(['a1'], 'semantic')
+      target.getBoundingClientRect = vi.fn().mockReturnValue({
+        left: 100, top: 200, bottom: 230, right: 150, width: 50, height: 30,
+      })
+      const anns = [makeAnn({ id: 'a1', kind: 'semantic' })]
+      show(createMockEvent(target), anns)
+      expect(visible.value).toBe(true)
+      toggle(createMockEvent(target), anns)
+      expect(visible.value).toBe(false)
+    })
+
+    it('shows new annotation on toggle when different on mobile', () => {
+      const { visible, show, toggle, items } = useAnnotationTooltip()
+      const target = createAnnTarget(['a1'], 'semantic')
+      target.getBoundingClientRect = vi.fn().mockReturnValue({
+        left: 100, top: 200, bottom: 230, right: 150, width: 50, height: 30,
+      })
+      const anns1 = [makeAnn({ id: 'a1', kind: 'semantic' })]
+      const anns2 = [makeAnn({ id: 'a2', kind: 'semantic' })]
+      show(createMockEvent(target), anns1)
+      toggle(createMockEvent(target), anns2)
+      expect(visible.value).toBe(true)
+      expect(items.value[0].id).toBe('a2')
+    })
+  })
+
+  describe('desktop toggle behavior', () => {
+    beforeEach(() => {
+      Object.defineProperty(window, 'innerWidth', { value: 1024, writable: true, configurable: true })
+    })
+
+    it('does NOT dismiss on toggle when same annotation on desktop', () => {
+      const { visible, show, toggle } = useAnnotationTooltip()
+      const target = createAnnTarget(['a1'], 'semantic')
+      target.getBoundingClientRect = vi.fn().mockReturnValue({
+        left: 100, top: 200, bottom: 230, right: 150, width: 50, height: 30,
+      })
+      const anns = [makeAnn({ id: 'a1', kind: 'semantic' })]
+      show(createMockEvent(target), anns)
+      expect(visible.value).toBe(true)
+      toggle(createMockEvent(target), anns)
+      // Desktop: same annotation stays open
+      expect(visible.value).toBe(true)
+    })
+  })
+
+  it('positions tooltip for vertical layout (default)', () => {
+    const { style, show } = useAnnotationTooltip()
+    const target = createAnnTarget(['a1'], 'semantic')
+    target.getBoundingClientRect = vi.fn().mockReturnValue({
+      left: 200, top: 300, bottom: 330, right: 250, width: 50, height: 30,
+    })
+    show(createMockEvent(target), [makeAnn({ id: 'a1', kind: 'semantic' })])
+    // Default layout is vertical — positioned via right + top
+    expect(style.value.right).toBeTruthy()
+    expect(style.value.top).toBe('50%')
+    expect(style.value.transform).toBe('translateY(-50%)')
+  })
+})

package/template/src/components/AnnotationControlBar.vue

@@ -0,0 +1,124 @@
+<script setup lang="ts">
+import type { AnnotationLayer } from '../types'
+
+const props = defineProps<{
+  layers: AnnotationLayer[]
+  hasAnnotations: boolean
+  activeIds: string[]
+}>()
+
+const emit = defineEmits<{
+  'update:activeIds': [ids: string[]]
+  'update:annotationsVisible': [visible: boolean]
+}>()
+
+const allIds = () => props.layers.map(l => l.id)
+const noneIds = () => [] as string[]
+
+function toggleAnnotations() {
+  if (props.activeIds.length > 0) {
+    emit('update:activeIds', noneIds())
+    emit('update:annotationsVisible', false)
+  } else {
+    emit('update:activeIds', allIds())
+    emit('update:annotationsVisible', true)
+  }
+}
+
+function toggleLayer(id: string) {
+  const current = props.activeIds
+  if (current.includes(id)) {
+    const next = current.filter(x => x !== id)
+    emit('update:activeIds', next)
+    if (next.length === 0) emit('update:annotationsVisible', false)
+  } else {
+    const next = [...current, id]
+    emit('update:activeIds', next)
+    emit('update:annotationsVisible', true)
+  }
+}
+</script>
+
+<template>
+  <div v-if="hasAnnotations" class="ann-control-bar">
+    <button
+      class="ann-toggle"
+      :class="{ active: activeIds.length > 0 }"
+      @click="toggleAnnotations"
+    >注</button>
+    <template v-if="layers.length > 1">
+      <span class="ann-bar-sep" />
+      <button
+        v-for="layer in layers"
+        :key="layer.id"
+        :class="['ann-layer-btn', { active: activeIds.includes(layer.id) }]"
+        :title="layer.label"
+        @click="toggleLayer(layer.id)"
+      >
+        {{ layer.shortLabel }}
+      </button>
+    </template>
+  </div>
+</template>
+
+<style scoped>
+.ann-control-bar {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.ann-toggle {
+  width: 28px;
+  height: 28px;
+  border: 1px solid var(--vermillion);
+  border-radius: 4px;
+  background: none;
+  color: var(--vermillion);
+  font-family: var(--serif);
+  font-size: 14px;
+  font-weight: 700;
+  cursor: pointer;
+  transition: all 0.15s;
+  letter-spacing: 0;
+}
+
+.ann-toggle.active {
+  background: var(--vermillion);
+  color: #fff;
+}
+
+.ann-toggle:hover {
+  border-color: var(--vermillion-light);
+}
+
+.ann-bar-sep {
+  width: 1px;
+  height: 16px;
+  background: var(--border);
+  margin: 0 2px;
+}
+
+.ann-layer-btn {
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 3px 10px;
+  font-size: 12px;
+  background: var(--surface);
+  color: var(--ink-mid);
+  cursor: pointer;
+  transition: all 0.15s;
+  font-family: var(--sans);
+  letter-spacing: 1px;
+}
+
+.ann-layer-btn:hover {
+  border-color: var(--gold);
+}
+
+.ann-layer-btn.active {
+  background: var(--ink);
+  color: var(--paper);
+  border-color: var(--ink);
+}
+</style>

package/template/src/components/AnnotationTooltip.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed } from 'vue'
+import { computed, watch, onMounted, onBeforeUnmount } from 'vue'
 import { useReadingMode } from '../composables/useReadingMode'
 import { annotationToPronSegment } from '../utils/annotationParser'
 import PronunciationGroup from './PronunciationGroup.vue'
@@ -12,9 +12,13 @@ const props = defineProps<{
   style?: Record<string, string>
 }>()
 
-const emit = defineEmits<{ close: [] }>()
+const emit = defineEmits<{
+  close: []
+  tooltipEnter: []
+  tooltipLeave: []
+}>()
 const { layout } = useReadingMode()
-const isMobile = computed(() => window.innerWidth < 768)
+const isMobile = computed(() => typeof window !== 'undefined' && window.innerWidth < 768)
 
 function getSegment(ann: Annotation) {
   return annotationToPronSegment(ann)
@@ -28,36 +32,55 @@ function layerLabel(ann: Annotation): string {
   return ''
 }
 
-function onBackdropTouchMove() {
+function onDocClick(e: MouseEvent) {
+  if (!props.visible) return
+  const tooltip = (e.target as HTMLElement).closest('.ann-tooltip')
+  if (tooltip) return
   emit('close')
 }
+
+function onDocTouchMove(e: TouchEvent) {
+  if (!props.visible || !isMobile.value) return
+  const tooltip = (e.target as HTMLElement).closest('.ann-tooltip')
+  if (tooltip) return
+  emit('close')
+}
+
+onMounted(() => {
+  document.addEventListener('click', onDocClick, true)
+  document.addEventListener('touchmove', onDocTouchMove, { passive: true })
+})
+
+onBeforeUnmount(() => {
+  document.removeEventListener('click', onDocClick, true)
+  document.removeEventListener('touchmove', onDocTouchMove)
+})
 </script>
 
 <template>
   <Teleport to="body">
     <Transition name="ann-fade">
-      <div v-if="visible && annotations.length" class="ann-backdrop" @click="emit('close')" @touchmove="onBackdropTouchMove">
+      <div
+        v-if="visible && annotations.length"
+        class="ann-tooltip"
+        :class="{ 'ann-vertical': layout === 'vertical', 'ann-mobile-bottom': isMobile }"
+        :style="style"
+        @mouseenter="emit('tooltipEnter')"
+        @mouseleave="emit('tooltipLeave')"
+      >
+        <button v-if="isMobile" class="ann-handle" @click="emit('close')">
+          <span class="ann-handle-bar" />
+        </button>
         <div
-          class="ann-tooltip"
-          :class="{ 'ann-vertical': layout === 'vertical', 'ann-mobile-bottom': isMobile }"
-          :style="style"
-          @click.stop
-          @touchmove.stop
+          v-for="ann in annotations"
+          :key="ann.id"
+          class="ann-entry"
+          :class="ann.kind"
         >
-          <button v-if="isMobile" class="ann-handle" @click="emit('close')">
-            <span class="ann-handle-bar" />
-          </button>
-          <div
-            v-for="ann in annotations"
-            :key="ann.id"
-            class="ann-entry"
-            :class="ann.kind"
-          >
-            <span class="ann-kind">{{ ann.kind === 'pronunciation' ? '音' : '義' }}</span>
-            <span v-if="layerLabel(ann)" class="ann-layer">{{ layerLabel(ann) }}</span>
-            <PronunciationGroup v-if="getSegment(ann)" :segment="getSegment(ann)!" />
-            <span v-else class="ann-body">{{ ann.text }}</span>
-          </div>
+          <span class="ann-kind">{{ ann.kind === 'pronunciation' ? '音' : '義' }}</span>
+          <span v-if="layerLabel(ann)" class="ann-layer">{{ layerLabel(ann) }}</span>
+          <PronunciationGroup v-if="getSegment(ann)" :segment="getSegment(ann)!" />
+          <span v-else class="ann-body">{{ ann.text }}</span>
         </div>
       </div>
     </Transition>
@@ -65,12 +88,6 @@ function onBackdropTouchMove() {
 </template>
 
 <style scoped>
-.ann-backdrop {
-  position: fixed;
-  inset: 0;
-  z-index: 999;
-}
-
 .ann-tooltip {
   position: fixed;
   padding: 12px 16px;

package/template/src/components/ReadingToolbar.vue

@@ -2,8 +2,10 @@
 import { ref } from 'vue'
 import { useReadingMode, THEMES, THEME_LABELS } from '../composables/useReadingMode'
 import type { LayoutMode } from '../composables/useReadingMode'
+import { useI18n, LOCALE_LABELS, type Locale } from '../composables/useI18n'
 
 const { theme, layout, setTheme, setLayout } = useReadingMode()
+const { t, setLocale, locale, availableLocales, localeLabels } = useI18n()
 const open = ref(false)
 
 function toggle() { open.value = !open.value }
@@ -18,22 +20,22 @@ function close() { open.value = false }
     </button>
     <div v-if="open" class="rt-panel" @click.stop>
       <div class="rt-group">
-        <div class="rt-label">版面</div>
+        <div class="rt-label">{{ t('settings.layout') }}</div>
         <div class="rt-options">
           <button
             class="rt-opt"
             :class="{ active: layout === 'horizontal' }"
             @click="setLayout('horizontal' as LayoutMode)"
-          >橫排</button>
+          >{{ t('settings.horizontal') }}</button>
           <button
             class="rt-opt"
             :class="{ active: layout === 'vertical' }"
             @click="setLayout('vertical' as LayoutMode)"
-          >直排</button>
+          >{{ t('settings.vertical') }}</button>
         </div>
       </div>
       <div class="rt-group">
-        <div class="rt-label">主題</div>
+        <div class="rt-label">{{ t('settings.theme') }}</div>
         <div class="rt-options">
           <button
             v-for="t in THEMES"
@@ -44,6 +46,18 @@ function close() { open.value = false }
           >{{ THEME_LABELS[t] }}</button>
         </div>
       </div>
+      <div class="rt-group">
+        <div class="rt-label">{{ t('settings.language') }}</div>
+        <div class="rt-options">
+          <button
+            v-for="loc in availableLocales"
+            :key="loc"
+            class="rt-opt"
+            :class="{ active: locale === loc }"
+            @click="setLocale(loc as Locale)"
+          >{{ localeLabels[loc] }}</button>
+        </div>
+      </div>
     </div>
     <div v-if="open" class="rt-backdrop" @click="close" />
   </div>

package/template/src/components/SideNav.vue

@@ -2,6 +2,7 @@
 import { ref } from 'vue'
 import { useReadingMode, THEMES, THEME_LABELS, FONT_SIZES } from '../composables/useReadingMode'
 import type { LayoutMode, FontSize } from '../composables/useReadingMode'
+import { useI18n, LOCALE_LABELS, type Locale } from '../composables/useI18n'
 
 defineProps<{
   context?: string
@@ -16,6 +17,7 @@ const emit = defineEmits<{
 }>()
 
 const { theme, layout, mainFontSize, bodyFontSize, setTheme, setLayout, setMainFontSize, setBodyFontSize } = useReadingMode()
+const { t, setLocale, locale, availableLocales, localeLabels } = useI18n()
 const settingsOpen = ref(false)
 
 function toggleSettings() { settingsOpen.value = !settingsOpen.value }
@@ -56,14 +58,14 @@ function toggleSettings() { settingsOpen.value = !settingsOpen.value }
     <Transition name="slide-left">
       <div v-if="settingsOpen" class="sn-settings" @click.stop>
         <div class="ss-group">
-          <div class="ss-label">版面</div>
+          <div class="ss-label">{{ t('settings.layout') }}</div>
           <div class="ss-options">
-            <button class="ss-opt" :class="{ active: layout === 'horizontal' }" @click="setLayout('horizontal' as LayoutMode)">橫排</button>
-            <button class="ss-opt" :class="{ active: layout === 'vertical' }" @click="setLayout('vertical' as LayoutMode)">直排</button>
+            <button class="ss-opt" :class="{ active: layout === 'horizontal' }" @click="setLayout('horizontal' as LayoutMode)">{{ t('settings.horizontal') }}</button>
+            <button class="ss-opt" :class="{ active: layout === 'vertical' }" @click="setLayout('vertical' as LayoutMode)">{{ t('settings.vertical') }}</button>
           </div>
         </div>
         <div class="ss-group">
-          <div class="ss-label">主題</div>
+          <div class="ss-label">{{ t('settings.theme') }}</div>
           <div class="ss-options">
             <button
               v-for="t in THEMES"
@@ -75,7 +77,7 @@ function toggleSettings() { settingsOpen.value = !settingsOpen.value }
           </div>
         </div>
         <div class="ss-group">
-          <div class="ss-label">正文字號</div>
+          <div class="ss-label">{{ t('settings.mainFontSize') }}</div>
           <div class="ss-size-row">
             <button class="ss-size-btn" @click="setMainFontSize(FONT_SIZES[Math.max(0, FONT_SIZES.indexOf(mainFontSize) - 1)] as FontSize)">−</button>
             <span class="ss-size-val">{{ mainFontSize }}</span>
@@ -83,13 +85,25 @@ function toggleSettings() { settingsOpen.value = !settingsOpen.value }
           </div>
         </div>
         <div class="ss-group">
-          <div class="ss-label">內文字號</div>
+          <div class="ss-label">{{ t('settings.bodyFontSize') }}</div>
           <div class="ss-size-row">
             <button class="ss-size-btn" @click="setBodyFontSize(FONT_SIZES[Math.max(0, FONT_SIZES.indexOf(bodyFontSize) - 1)] as FontSize)">−</button>
             <span class="ss-size-val">{{ bodyFontSize }}</span>
             <button class="ss-size-btn" @click="setBodyFontSize(FONT_SIZES[Math.min(FONT_SIZES.length - 1, FONT_SIZES.indexOf(bodyFontSize) + 1)] as FontSize)">+</button>
           </div>
         </div>
+        <div class="ss-group">
+          <div class="ss-label">{{ t('settings.language') }}</div>
+          <div class="ss-options">
+            <button
+              v-for="loc in availableLocales"
+              :key="loc"
+              class="ss-opt"
+              :class="{ active: locale === loc }"
+              @click="setLocale(loc as Locale)"
+            >{{ localeLabels[loc] }}</button>
+          </div>
+        </div>
       </div>
     </Transition>
 

package/template/src/composables/useAnnotationInteraction.ts

@@ -0,0 +1,60 @@
+import type { Annotation } from '../types'
+import { useAnnotationTooltip } from './useAnnotationRenderer'
+
+function isMobile(): boolean {
+  return typeof window !== 'undefined' && window.innerWidth < 768
+}
+
+export function useAnnotationInteraction() {
+  const tooltip = useAnnotationTooltip()
+  let hideTimer: ReturnType<typeof setTimeout> | null = null
+
+  function cancelHide() {
+    if (hideTimer) { clearTimeout(hideTimer); hideTimer = null }
+  }
+
+  function scheduleHide(delay = 300) {
+    cancelHide()
+    hideTimer = setTimeout(() => { tooltip.hide(); hideTimer = null }, delay)
+  }
+
+  function onHover(event: MouseEvent, annotations: Annotation[]) {
+    if (isMobile()) return
+    cancelHide()
+    tooltip.show(event, annotations)
+  }
+
+  function onLeave() {
+    if (!isMobile()) scheduleHide()
+  }
+
+  function onTap(event: MouseEvent, annotations: Annotation[]) {
+    cancelHide()
+    tooltip.toggle(event, annotations)
+  }
+
+  function onTooltipEnter() {
+    cancelHide()
+  }
+
+  function onTooltipLeave() {
+    if (!isMobile()) scheduleHide()
+  }
+
+  function dismiss() {
+    cancelHide()
+    tooltip.hide()
+  }
+
+  return {
+    visible: tooltip.visible,
+    items: tooltip.items,
+    style: tooltip.style,
+    onHover,
+    onLeave,
+    onTap,
+    onTooltipEnter,
+    onTooltipLeave,
+    dismiss,
+  }
+}