@hanology/cham-browser 0.2.1 → 0.2.3

package/README.md

@@ -0,0 +1,81 @@
+# @hanology/cham-browser
+
+[![npm version](https://img.shields.io/npm/v/@hanology/cham-browser.svg)](https://www.npmjs.com/package/@hanology/cham-browser)
+
+Site generator for [CHAM (Classical Han with Annotations Markup)](https://github.com/hanologyorg/cham-format) — generates a complete static website from CHAM content.
+
+Includes parser, serializer, transformation pipeline, Vue 3 frontend template, and CLI.
+
+## Install
+
+```bash
+npm install @hanology/cham-browser
+```
+
+## CLI
+
+```bash
+# Generate a static site from CHAM content
+npx cham-browser --config config.yaml
+```
+
+### config.yaml
+
+```yaml
+# Branding
+name: 漢流
+nameEn: Hanology
+subtitle: 古典詩文圖書館
+
+# Content paths (relative to config.yaml)
+libraryDir: library/content
+authorsFile: library/data/authors.yaml
+
+# Build options
+outputDir: dist
+pretty: true
+```
+
+## API
+
+### Parser & Serializer (browser-compatible)
+
+```typescript
+import { parse, serialize } from '@hanology/cham-browser'
+
+const doc = parse(chamSource)
+const output = serialize(doc)
+```
+
+### Pipeline (pure functions, no Node.js fs)
+
+```typescript
+import {
+  buildPieceFromCham,
+  buildBookData,
+  buildLibraryIndex,
+  buildAuthorsJson,
+  buildDynastiesJson,
+} from '@hanology/cham-browser'
+
+const piece = buildPieceFromCham(
+  chamSource, bookConfig, authors, bookId,
+  proseFiles, layerFiles,
+)
+```
+
+## Architecture
+
+| Layer | Description |
+|-------|-------------|
+| `pipeline.ts` | Pure transformation functions (CHAM → JSON) |
+| `cli.ts` | I/O adapter: reads files, calls pipeline, runs vite-ssg |
+| `template/` | Vue 3 + vite-ssg frontend (components, views, styles) |
+
+## Requirements
+
+Node.js 20+
+
+## License
+
+MIT

package/package.json

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

package/template/src/components/AnnotationTooltip.vue

@@ -12,7 +12,11 @@ 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)
 
@@ -27,17 +31,24 @@ function layerLabel(ann: Annotation): string {
   }
   return ''
 }
+
+function onBackdropTouchMove() {
+  emit('close')
+}
 </script>
 
 <template>
   <Teleport to="body">
     <Transition name="ann-fade">
-      <div v-if="visible && annotations.length" class="ann-backdrop" @click="emit('close')">
+      <div v-if="visible && annotations.length" class="ann-backdrop" @click="emit('close')" @touchmove="onBackdropTouchMove">
         <div
           class="ann-tooltip"
           :class="{ 'ann-vertical': layout === 'vertical', 'ann-mobile-bottom': isMobile }"
           :style="style"
           @click.stop
+          @touchmove.stop
+          @mouseenter="emit('tooltipEnter')"
+          @mouseleave="emit('tooltipLeave')"
         >
           <button v-if="isMobile" class="ann-handle" @click="emit('close')">
             <span class="ann-handle-bar" />
@@ -48,12 +59,10 @@ function layerLabel(ann: Annotation): string {
             class="ann-entry"
             :class="ann.kind"
           >
-            <div class="ann-header">
-              <span class="ann-kind">{{ ann.kind === 'pronunciation' ? '音' : '義' }}</span>
-              <span v-if="layerLabel(ann)" class="ann-layer">{{ layerLabel(ann) }}</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)!" />
-            <div v-else class="ann-body">{{ ann.text }}</div>
+            <span v-else class="ann-body">{{ ann.text }}</span>
           </div>
         </div>
       </div>
@@ -135,7 +144,6 @@ function layerLabel(ann: Annotation): string {
   display: inline-flex;
   align-items: center;
   gap: 6px;
-  margin-bottom: 2px;
 }
 .ann-layer {
   font-size: 11px;
@@ -153,7 +161,6 @@ function layerLabel(ann: Annotation): string {
 }
 
 .ann-body {
-  margin-top: 4px;
   line-height: 1.8;
 }
 
@@ -168,6 +175,7 @@ function layerLabel(ann: Annotation): string {
 .ann-vertical .ann-entry {
   margin-bottom: 0;
   margin-left: 12px;
+  display: inline;
 }
 .ann-vertical .ann-kind {
   margin-right: 0;
@@ -175,7 +183,6 @@ function layerLabel(ann: Annotation): string {
   vertical-align: baseline;
 }
 .ann-vertical .ann-body {
-  margin-top: 0;
   margin-left: 6px;
 }
 

package/template/src/components/VerticalScroll.vue

@@ -105,6 +105,10 @@ function onTap(event: MouseEvent) {
   text-align: end;
   letter-spacing: 0;
 }
+:deep(.ann-num-long) {
+  font-size: 0.38em;
+  letter-spacing: -1px;
+}
 :deep(.ann-target:hover) {
   background: rgba(194, 58, 43, 0.08);
 }

package/template/src/composables/useAnnotationRenderer.ts

@@ -56,7 +56,8 @@ export function renderAnnotatedText(text: string, spans: AnnSpan[], useRuby = fa
     const numText = toChineseNumber(annCounter)
     const body = esc(text.slice(span.start, span.end))
     if (useRuby) {
-      html += `<ruby class="ann-target ${kinds}" data-ann-ids="${ids}">${body}<rp></rp><rt class="ann-num">${numText}</rt><rp></rp></ruby>`
+      const rtCls = numText.length > 1 ? 'ann-num ann-num-long' : 'ann-num'
+      html += `<ruby class="ann-target ${kinds}" data-ann-ids="${ids}">${body}<rp></rp><rt class="${rtCls}">${numText}</rt><rp></rp></ruby>`
     } else {
       html += `<span class="ann-target ${kinds}" data-ann-ids="${ids}">${body}<sup class="ann-num">${numText}</sup></span>`
     }
@@ -151,7 +152,18 @@ export function useAnnotationTooltip() {
 
   function hide() { visible.value = false }
   function toggle(event: MouseEvent, annotations: Annotation[]) {
-    if (visible.value) { hide() } else { show(event, annotations) }
+    if (visible.value) {
+      const currentIds = items.value.map(a => a.id).sort().join(',')
+      const newIds = annotations.map(a => a.id).sort().join(',')
+      if (currentIds === newIds) {
+        // Same annotation: dismiss on mobile only (desktop uses hover to manage)
+        if (window.innerWidth < 768) hide()
+      } else {
+        show(event, annotations)
+      }
+    } else {
+      show(event, annotations)
+    }
   }
 
   return { visible, items, style, show, hide, toggle }

package/template/src/views/PieceView.vue

@@ -152,16 +152,33 @@ const proseSections = computed(() => {
   return result
 })
 
+let hideTimer: ReturnType<typeof setTimeout> | null = null
+function cancelHide() {
+  if (hideTimer) { clearTimeout(hideTimer); hideTimer = null }
+}
+function scheduleHide(delay = 150) {
+  cancelHide()
+  hideTimer = setTimeout(() => { tooltip.hide(); hideTimer = null }, delay)
+}
+
 function handleAnnotationHover(event: MouseEvent, annotations: Annotation[]) {
+  cancelHide()
   tooltip.show(event, annotations)
 }
 function handleAnnotationLeave() {
-  if (window.innerWidth >= 768) tooltip.hide()
+  if (window.innerWidth >= 768) scheduleHide()
 }
 function handleAnnotationTap(event: MouseEvent, annotations: Annotation[]) {
+  cancelHide()
   tooltip.toggle(event, annotations)
 }
-function dismissTooltip() { tooltip.hide() }
+function handleTooltipEnter() {
+  cancelHide()
+}
+function handleTooltipLeave() {
+  if (window.innerWidth >= 768) scheduleHide()
+}
+function dismissTooltip() { cancelHide(); tooltip.hide() }
 const { getAuthor, loadShared } = useData()
 await loadShared()
 
@@ -259,32 +276,33 @@ function tcy(n: number): string {
           />
         </section>
 
-        <SectionBlock
-          num=""
-          label="注釋"
-          :special="false"
-          :text="piece.sections.annotations || ''"
-          :is-annotations="true"
-          :vertical="true"
-          class="v-section"
-        />
-
-        <div v-if="hasLayers" class="v-layers-section">
-          <AnnotationLayerSelector
-            :layers="annotationLayers"
-            v-model:activeIds="activeLayerIds"
-          />
+        <div class="v-section">
           <SectionBlock
-            v-for="block in layerAnnotationBlocks"
-            :key="block.label"
             num=""
-            :label="block.label"
+            label="注釋"
             :special="false"
-            :text="block.text"
+            :text="piece.sections.annotations || ''"
             :is-annotations="true"
             :vertical="true"
-            class="v-section"
           />
+          <template v-if="hasLayers">
+            <div class="v-layers-inline">
+              <AnnotationLayerSelector
+                :layers="annotationLayers"
+                v-model:activeIds="activeLayerIds"
+              />
+            </div>
+            <SectionBlock
+              v-for="block in layerAnnotationBlocks"
+              :key="block.label"
+              num=""
+              :label="block.label"
+              :special="false"
+              :text="block.text"
+              :is-annotations="true"
+              :vertical="true"
+            />
+          </template>
         </div>
 
         <SectionBlock
@@ -320,6 +338,8 @@ function tcy(n: number): string {
         :layer-labels="layerLabels"
         :style="tooltip.style"
         @close="dismissTooltip"
+        @tooltip-enter="handleTooltipEnter"
+        @tooltip-leave="handleTooltipLeave"
       />
 
       <Teleport to="body">
@@ -382,20 +402,32 @@ function tcy(n: number): string {
           </div>
 
           <div class="h-sections">
-            <div v-if="hasLayers" class="h-layers-section">
-              <AnnotationLayerSelector
-                :layers="annotationLayers"
-                v-model:activeIds="activeLayerIds"
-              />
+            <div v-if="piece.sections.annotations || hasLayers" class="h-ann-section">
               <SectionBlock
-                v-for="block in layerAnnotationBlocks"
-                :key="block.label"
+                v-if="piece.sections.annotations"
                 num=""
-                :label="block.label"
+                label="注釋"
                 :special="false"
-                :text="block.text"
+                :text="piece.sections.annotations"
                 :is-annotations="true"
               />
+              <template v-if="hasLayers">
+                <div class="h-layers-inline">
+                  <AnnotationLayerSelector
+                    :layers="annotationLayers"
+                    v-model:activeIds="activeLayerIds"
+                  />
+                </div>
+                <SectionBlock
+                  v-for="block in layerAnnotationBlocks"
+                  :key="block.label"
+                  num=""
+                  :label="block.label"
+                  :special="false"
+                  :text="block.text"
+                  :is-annotations="true"
+                />
+              </template>
             </div>
 
             <SectionBlock
@@ -430,6 +462,8 @@ function tcy(n: number): string {
         :layer-labels="layerLabels"
         :style="tooltip.style"
         @close="dismissTooltip"
+        @tooltip-enter="handleTooltipEnter"
+        @tooltip-leave="handleTooltipLeave"
       />
 
       <Teleport to="body">
@@ -532,15 +566,11 @@ function tcy(n: number): string {
   flex-shrink: 0;
 }
 
-.v-layers-section {
-  flex-shrink: 0;
+.v-layers-inline {
   writing-mode: vertical-rl;
   text-orientation: mixed;
-  padding: 0 16px;
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  align-items: flex-start;
+  padding: 12px 0 4px;
+  border-top: 1px solid var(--border-light);
 }
 
 .v-source-link {
@@ -649,12 +679,13 @@ function tcy(n: number): string {
   margin: 0 auto; padding-bottom: 80px;
 }
 
-.h-layers-section {
+.h-ann-section {
   margin-bottom: 16px;
-  padding: 16px;
-  background: var(--surface);
-  border-radius: 8px;
-  border: 1px solid var(--border-light);
+}
+
+.h-layers-inline {
+  padding: 12px 0;
+  margin-bottom: 8px;
 }
 
 .h-source-link {