@docsector/docsector-reader 1.7.1 → 2.0.1

package/src/components/DPage.vue

@@ -1,5 +1,5 @@
 <script setup>
-import { ref, computed, onMounted, onBeforeUnmount } from 'vue'
+import { ref, computed, onMounted, onBeforeUnmount, nextTick, watch } from 'vue'
 import { useStore } from 'vuex'
 import { useRoute, useRouter } from 'vue-router'
 import { useQuasar } from 'quasar'
@@ -24,6 +24,38 @@ const props = defineProps({
 })
 
 const pageScrollArea = ref(null)
+const pageContainer = ref(null)
+const submenu = ref(null)
+const pageMinHeight = ref('calc(100vh - 86px)')
+const submenuHeight = ref('36px')
+const pageBottomInset = ref('0px')
+
+const updatePageMinHeight = () => {
+  const pageContainerEl = pageContainer.value?.$el || pageContainer.value
+  const submenuEl = submenu.value?.$el || submenu.value
+
+  if (!pageContainerEl || !submenuEl) {
+    return
+  }
+
+  const pageContainerStyles = window.getComputedStyle(pageContainerEl)
+  const headerHeight = Number.parseFloat(pageContainerStyles.paddingTop) || 0
+  const measuredSubmenuHeight = submenuEl.offsetHeight || 0
+  const isMobile = $q.screen.lt.md
+  const totalOffset = Math.max(0, Math.round(headerHeight + (isMobile ? 0 : measuredSubmenuHeight)))
+
+  pageMinHeight.value = `calc(100vh - ${totalOffset}px)`
+  submenuHeight.value = `${Math.max(36, Math.round(measuredSubmenuHeight))}px`
+  pageBottomInset.value = isMobile ? submenuHeight.value : '0px'
+}
+
+const schedulePageMinHeightUpdate = () => {
+  window.requestAnimationFrame(() => {
+    window.requestAnimationFrame(() => {
+      updatePageMinHeight()
+    })
+  })
+}
 
 const overview = computed(() => route.matched[0].path)
 const showcase = computed(() => {
@@ -164,6 +196,10 @@ const handleMainScrollKeys = (event) => {
 
 onMounted(() => {
   window.addEventListener('keydown', handleMainScrollKeys)
+  window.addEventListener('resize', schedulePageMinHeightUpdate)
+  nextTick(() => {
+    schedulePageMinHeightUpdate()
+  })
 
   router.beforeEach((to, from, next) => {
     resetPageScroll()
@@ -180,38 +216,60 @@ onMounted(() => {
 
 onBeforeUnmount(() => {
   window.removeEventListener('keydown', handleMainScrollKeys)
+  window.removeEventListener('resize', schedulePageMinHeightUpdate)
+})
+
+watch(() => route.fullPath, () => {
+  nextTick(() => {
+    schedulePageMinHeightUpdate()
+  })
 })
 </script>
 
 <template>
-<q-page-container id="page-container">
-  <q-toolbar id="submenu" class="bg-grey-8 text-white">
-    <q-toolbar-title class="toolbar-container">
-      <q-btn-group :class="$q.screen.lt.md ? 'mobile' : null">
-        <q-btn
-          v-if="overview && (showcase || vs)"
-          no-caps flat
-          :class="pActive('/overview')"
-          :label="$t('submenu.overview')" icon="pageview"
-          @click="subroute('/overview')"
-        />
-        <q-btn
-          v-if="showcase"
-          no-caps flat
-          :class="pActive('/showcase')"
-          :label="$t('submenu.showcase')" icon="play_circle_filled"
-          @click="subroute('/showcase')"
-        />
-        <q-btn
-          v-if="vs"
-          no-caps flat
-          :class="pActive('/vs')"
-          :label="$t('submenu.versus')" icon="compare"
-          @click="subroute('/vs')"
-        />
-      </q-btn-group>
-    </q-toolbar-title>
-    <q-btn @click="toggleSectionsTree" icon="account_tree" />
+<q-page-container
+  id="page-container"
+  ref="pageContainer"
+  :style="{
+    '--d-page-min-height': pageMinHeight,
+    '--d-submenu-height': submenuHeight,
+    '--d-page-bottom-inset': pageBottomInset
+  }"
+>
+  <q-toolbar
+    id="submenu"
+    ref="submenu"
+    class="bg-grey-8 text-white"
+    :class="$q.screen.lt.md ? 'd-submenu--mobile' : 'd-submenu--desktop'"
+  >
+    <div class="d-submenu__content">
+      <q-toolbar-title class="toolbar-container">
+        <q-btn-group :class="$q.screen.lt.md ? 'mobile' : null">
+          <q-btn
+            v-if="overview && (showcase || vs)"
+            no-caps flat
+            :class="pActive('/overview')"
+            :label="$t('submenu.overview')" icon="pageview"
+            @click="subroute('/overview')"
+          />
+          <q-btn
+            v-if="showcase"
+            no-caps flat
+            :class="pActive('/showcase')"
+            :label="$t('submenu.showcase')" icon="play_circle_filled"
+            @click="subroute('/showcase')"
+          />
+          <q-btn
+            v-if="vs"
+            no-caps flat
+            :class="pActive('/vs')"
+            :label="$t('submenu.versus')" icon="compare"
+            @click="subroute('/vs')"
+          />
+        </q-btn-group>
+      </q-toolbar-title>
+      <q-btn class="d-submenu__toggle" @click="toggleSectionsTree" icon="account_tree" />
+    </div>
   </q-toolbar>
 
   <q-page id="page">
@@ -236,7 +294,7 @@ onBeforeUnmount(() => {
 
 .content,
 .content > div.scroll
-  min-height: calc(100vh - 86px)
+  min-height: var(--d-page-min-height, calc(100vh - 86px))
 
 .content > div.scroll > div.q-scrollarea__content
   max-width: 100%
@@ -244,9 +302,10 @@ onBeforeUnmount(() => {
 
 .content:not(.no-padding) > div.scroll > div.q-scrollarea__content
   padding: 15px
+  padding-bottom: calc(15px + var(--d-page-bottom-inset, 0px) + env(safe-area-inset-bottom, 0px))
 
 #page
-  min-height: calc(100vh - 86px) !important
+  min-height: var(--d-page-min-height, calc(100vh - 86px)) !important
 
 #scroll-container
   width: 100%
@@ -259,10 +318,23 @@ onBeforeUnmount(() => {
   box-shadow: 0 2px 4px -1px rgba(0,0,0,0.2), 0 4px 5px rgba(0,0,0,0.14), 0 1px 6px rgba(0,0,0,0.12)
   overflow: visible
 
+  .d-submenu__content
+    width: calc(100% - 30px)
+    max-width: 1200px
+    min-height: inherit
+    margin: 0 auto
+    display: flex
+    align-items: center
+    align-self: stretch
+
+  .d-submenu__toggle
+    flex: 0 0 auto
+
   .on-left
     margin-right: 5px
   .toolbar-container
     overflow: visible
+    padding: 0
   .q-btn-group
     box-shadow: none
     &.mobile
@@ -276,6 +348,19 @@ onBeforeUnmount(() => {
       &:not(.focus-helper)
         margin-left: 6px
 
+#submenu.d-submenu--mobile
+  position: fixed
+  left: 0
+  right: 0
+  bottom: 0
+  z-index: 1500
+  min-height: 40px
+  padding-bottom: env(safe-area-inset-bottom, 0px)
+  box-shadow: 0 -1px 2px rgba(0,0,0,0.12), 0 -2px 6px rgba(0,0,0,0.08)
+
+  .d-submenu__content
+    align-items: flex-end
+
 #submenu a,
 #submenu button
   border-radius: 0
@@ -289,6 +374,10 @@ body.body--light
     background-color: #fff !important
     color: #000
     box-shadow: 0 10px 0 0 #fff
+
+  #submenu.d-submenu--mobile a.active,
+  #submenu.d-submenu--mobile button.active
+    box-shadow: 0 -10px 0 0 #fff
 // Dark
 body.body--dark
   #submenu a.active,
@@ -297,6 +386,10 @@ body.body--dark
     color: #fff
     box-shadow: 0 10px 0 0 var(--q-dark-page)
 
+  #submenu.d-submenu--mobile a.active,
+  #submenu.d-submenu--mobile button.active
+    box-shadow: 0 -10px 0 0 var(--q-dark-page)
+
 body.mobile.body--dark
   .q-drawer--right
     background: rgba(18, 0, 0, 0.7)

package/src/components/DPageAnchor.vue

@@ -2,13 +2,16 @@
 import { computed, ref, watch, onMounted, onBeforeUnmount } from 'vue'
 import { useStore } from 'vuex'
 import { useQuasar } from 'quasar'
+import { useI18n } from 'vue-i18n'
 import { useRoute } from "vue-router";
 
 import useNavigator from '../composables/useNavigator'
+import { pageTitleI18nPath } from '../i18n/path'
 
 const store = useStore()
 const $q = useQuasar()
 const route = useRoute()
+const { t } = useI18n()
 const { navigate, anchor, selected: navigatorSelected } = useNavigator()
 
 const scrolling = ref(null)
@@ -47,6 +50,15 @@ const stylize = computed(() => {
   }
 })
 
+const fallbackNodeLabel = computed(() => {
+  const base = store.state.i18n.base
+  if (!base) {
+    return ''
+  }
+
+  return t(pageTitleI18nPath(base))
+})
+
 const scrollToActiveAnchor = () => {
   if (scrolling.value) {
     clearTimeout(scrolling.value)
@@ -109,7 +121,7 @@ onBeforeUnmount(() => {
 >
   <template v-slot:default-header="props">
     <b v-if="props.node.label" v-html="props.node.label"></b>
-    <b v-else>{{ $t(`_.${$store.state.i18n.base}._`) }}</b>
+    <b v-else>{{ fallbackNodeLabel }}</b>
   </template>
 </q-tree>
 </template>

package/src/components/DPageBar.vue

@@ -7,6 +7,7 @@ import { copyToClipboard, useQuasar } from 'quasar'
 
 import docsectorConfig from 'docsector.config.js'
 import gitDates from 'virtual:docsector-git-dates'
+import { pageValueI18nPath } from '../i18n/path'
 
 const $q = useQuasar()
 const store = useStore()
@@ -59,7 +60,7 @@ const rawMarkdown = computed(() => {
   const absolute = store.state.i18n.absolute
   if (!absolute) return ''
 
-  const source = t(`_.${absolute}.source`)
+  const source = t(pageValueI18nPath(absolute, 'source'))
   if (!source) return ''
 
   return String(source)

package/src/components/DPageMeta.vue

@@ -6,6 +6,7 @@ import { openURL } from 'quasar'
 import { useI18n } from 'vue-i18n'
 
 import docsectorConfig from 'docsector.config.js'
+import { pageValueI18nPath, routeTitleI18nPath } from '../i18n/path'
 
 const store = useStore()
 const route = useRoute()
@@ -72,7 +73,7 @@ const progress = computed(() => {
   const currentLang = locale.value
 
   // Count headers (## and ###) in the default language source
-  const defaultSourcePath = `_.${i18nPathAbsolute}.source`
+  const defaultSourcePath = pageValueI18nPath(i18nPathAbsolute, 'source')
   const defaultSource = te(defaultSourcePath, defaultLang) ? tm(defaultSourcePath, defaultLang) : ''
 
   if (!defaultSource || typeof defaultSource !== 'string') {
@@ -106,7 +107,7 @@ const progress = computed(() => {
 
 const languages = computed(() => {
   const i18nPathAbsolute = store.state.i18n.absolute
-  const translations = `_.${i18nPathAbsolute}._translations`
+  const translations = pageValueI18nPath(i18nPathAbsolute, '_translations')
   const i18nLocales = availableLocales
   let fallbackLastUpdated = null
 
@@ -165,6 +166,10 @@ const hideRemoteHomeFooterMeta = computed(() => {
 
   return isRemoteHome && isHomePage
 })
+
+const getRouteTitle = (path) => {
+  return t(routeTitleI18nPath(path))
+}
 </script>
 
 <template>
@@ -197,11 +202,11 @@ const hideRemoteHomeFooterMeta = computed(() => {
     <router-link class="link col" v-if="prev" :to="`${prev}/overview/`">
       <div class="text-caption">{{ $t('page.nav.prev') }}</div>
       <q-icon name="navigate_before" />
-      <span>{{ $t(`_${prev.replace(/_$/, '').replace(/\//g, '.')}._`) }}</span>
+      <span>{{ getRouteTitle(prev) }}</span>
     </router-link>
     <router-link class="link col" v-if="next" :to="`${next}/overview/`">
       <div class="text-caption">{{ $t('page.nav.next') }}</div>
-      <span>{{ $t(`_${next.replace(/_$/, '').replace(/\//g, '.')}._`) }}</span>
+      <span>{{ getRouteTitle(next) }}</span>
       <q-icon name="navigate_next" />
     </router-link>
   </nav>

package/src/components/DPageSection.vue

@@ -14,6 +14,7 @@ import DPageSourceCode from './DPageSourceCode.vue'
 import DMermaidDiagram from './DMermaidDiagram.vue'
 import DPageBlockquote from './DPageBlockquote.vue'
 import DQuickLinks from './DQuickLinks.vue'
+import { pageValueI18nPath } from '../i18n/path'
 
 const props = defineProps({
   id: {
@@ -122,7 +123,7 @@ const tokenized = computed(() => {
     return []
   }
 
-  const source = t(`_.${absolute}.source`)
+  const source = t(pageValueI18nPath(absolute, 'source'))
   const normalizedSource = String(source)
     .replace(/{/g, '{')
     .replace(/}/g, '}')

package/src/composables/useWebMcp.js

@@ -1,4 +1,5 @@
 import docsectorConfig from 'docsector.config.js'
+import { pageValueI18nPath } from '../i18n/path'
 
 let activeCleanup = null
 
@@ -253,7 +254,7 @@ function createToolDefinitions ({
 
         let content = ''
         if (includeContent && absolute) {
-          const source = translate(`_.${absolute}.source`)
+          const source = translate(pageValueI18nPath(absolute, 'source'))
           if (source) {
             content = decodeMarkdownSource(source)
           }

package/src/i18n/helpers.js

@@ -8,10 +8,10 @@
  *
  *   import { buildMessages } from '@docsector/docsector-reader/i18n'
  *   import boot from 'pages/boot'
- *   import pages from 'pages'
+ *   import { allPages as pages } from 'virtual:docsector-books'
  *
  *   const langModules = import.meta.glob('./languages/*.hjson', { eager: true })
- *   const mdModules = import.meta.glob('../pages/⁣**​/⁣*.md', { eager: true, query: '?raw', import: 'default' })
+ *   const mdModules = import.meta.glob('all markdown files under ../pages recursively', { eager: true, query: '?raw', import: 'default' })
  *
  *   export default buildMessages({ langModules, mdModules, pages, boot })
  */
@@ -113,14 +113,15 @@ export function filter (source) {
  *
  * @param {Object} options
  * @param {Object} options.langModules - Result of import.meta.glob('./languages/*.hjson', { eager: true })
- * @param {Object} options.mdModules - Result of import.meta.glob('../pages/**​/*.md', { eager: true, query: '?raw', import: 'default' })
- * @param {Object} options.pages - Page registry from pages/index.js
+ * @param {Object} options.mdModules - Result of recursively globbing markdown files under ../pages with eager raw imports
+ * @param {Object} [options.pages] - Legacy merged page registry from virtual:docsector-books (allPages)
+ * @param {Object} [options.books] - Book registry from virtual:docsector-books (preferred, avoids path collisions)
  * @param {Object} options.boot - Boot meta from pages/boot.js
  * @param {string[]} [options.langs] - Language codes to process (auto-detected from langModules if omitted)
  * @param {Object<string,string>} [options.homePageOverride] - Optional per-language Home markdown override
  * @returns {Object} Complete i18n messages object keyed by locale
  */
-export function buildMessages ({ langModules, mdModules, pages, boot, langs, homePageOverride = {} }) {
+export function buildMessages ({ langModules, mdModules, pages, books, boot, langs, homePageOverride = {} }) {
   // Auto-detect languages from HJSON files if not provided
   if (!langs) {
     langs = Object.keys(langModules).map(key => {
@@ -199,6 +200,23 @@ export function buildMessages ({ langModules, mdModules, pages, boot, langs, hom
     return match[1].trim()
   }
 
+  const pageEntries = []
+
+  if (books && typeof books === 'object' && Object.keys(books).length > 0) {
+    for (const [bookId, book] of Object.entries(books)) {
+      const routes = book?.routes || {}
+      const fallbackBook = book?.config?.id || bookId || 'manual'
+
+      for (const [key, page] of Object.entries(routes)) {
+        pageEntries.push({ key, page, fallbackBook })
+      }
+    }
+  } else {
+    for (const [key, page] of Object.entries(pages || {})) {
+      pageEntries.push({ key, page, fallbackBook: null })
+    }
+  }
+
   // @ Iterate langs
   for (const lang of langs) {
     // Load HJSON language file
@@ -231,14 +249,18 @@ export function buildMessages ({ langModules, mdModules, pages, boot, langs, hom
     i18n[lang]._.home.overview.source = loadHomepage(lang)
 
     // @ Iterate pages
-    for (const [key, page] of Object.entries(pages)) {
-      const path = key.slice(1)
+    for (const entry of pageEntries) {
+      const { key, page, fallbackBook } = entry
+      const path = key.startsWith('/') ? key.slice(1) : key
 
       const config = page.config
       const data = page.data
       const meta = page.meta || boot.meta
 
-      const topPage = config?.type ?? 'manual'
+      const topPage = config?.book ?? config?.type ?? fallbackBook ?? 'manual'
+      if (i18n[lang]._[topPage] === undefined) {
+        i18n[lang]._[topPage] = {}
+      }
 
       // ---
 
@@ -254,7 +276,7 @@ export function buildMessages ({ langModules, mdModules, pages, boot, langs, hom
         // @ Set metadata
         // title
         if (node._ === undefined) {
-          node._ = data[lang]?.title || data['*']?.title
+          node._ = data?.[lang]?.title || data?.['*']?.title || data?.['en-US']?.title || ''
         }
 
         if (config === null) {
@@ -293,6 +315,11 @@ export function buildMessages ({ langModules, mdModules, pages, boot, langs, hom
         continue
       }
 
+      const hasInternalLink = typeof config?.link?.to === 'string' && config.link.to.trim().length > 0
+      if (hasInternalLink) {
+        continue
+      }
+
       // @ Subpages
       // Overview
       _.overview.source = load(topPage, path, 'overview', lang)

package/src/i18n/index.js

@@ -9,6 +9,6 @@ const mdModules = import.meta.glob('../pages/**/*.md', { eager: true, query: '?r
 
 // @ Import pages
 import boot from 'pages/boot'
-import pages from 'pages'
+import { books } from 'virtual:docsector-books'
 
-export default buildMessages({ langModules, mdModules, pages, boot, homePageOverride })
+export default buildMessages({ langModules, mdModules, books, boot, homePageOverride })

package/src/i18n/path.js

@@ -0,0 +1,101 @@
+const IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+function escapeSegment (segment) {
+  return String(segment)
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+}
+
+function normalizeSegments (segmentsInput, accumulator = []) {
+  for (const segment of segmentsInput) {
+    if (Array.isArray(segment)) {
+      normalizeSegments(segment, accumulator)
+      continue
+    }
+
+    if (segment === undefined || segment === null) {
+      continue
+    }
+
+    const normalized = String(segment).trim()
+    if (normalized.length === 0) {
+      continue
+    }
+
+    accumulator.push(normalized)
+  }
+
+  return accumulator
+}
+
+export function buildI18nPath (...segmentsInput) {
+  const segments = normalizeSegments(segmentsInput)
+  if (segments.length === 0) {
+    return ''
+  }
+
+  let path = ''
+
+  for (const [index, segment] of segments.entries()) {
+    if (index === 0) {
+      path += IDENTIFIER_PATTERN.test(segment)
+        ? segment
+        : `['${escapeSegment(segment)}']`
+      continue
+    }
+
+    path += IDENTIFIER_PATTERN.test(segment)
+      ? `.${segment}`
+      : `['${escapeSegment(segment)}']`
+  }
+
+  return path
+}
+
+export function splitRoutePathSegments (routePath) {
+  const normalized = String(routePath || '')
+    .replace(/\/+$/, '')
+    .replace(/^\//, '')
+
+  if (normalized.length === 0) {
+    return []
+  }
+
+  return normalized.split('/').filter(Boolean)
+}
+
+export function splitDotPathSegments (dotPath) {
+  const normalized = String(dotPath || '').trim()
+  if (normalized.length === 0) {
+    return []
+  }
+
+  return normalized.split('.').filter(Boolean)
+}
+
+export function routeTitleI18nPath (routePath) {
+  return buildI18nPath('_', ...splitRoutePathSegments(routePath), '_')
+}
+
+export function routeSubpageSourceI18nPath (routePath, subpage = 'overview') {
+  return buildI18nPath('_', ...splitRoutePathSegments(routePath), subpage, 'source')
+}
+
+export function pageTitleI18nPath (basePath) {
+  return buildI18nPath('_', ...splitDotPathSegments(basePath), '_')
+}
+
+export function pageValueI18nPath (absolutePath, key = 'source') {
+  return buildI18nPath('_', ...splitDotPathSegments(absolutePath), key)
+}
+
+export function namespacedLabelI18nPath (book, nodePath) {
+  const normalizedNodePath = String(nodePath || '').replace(/^\./, '')
+
+  return buildI18nPath(
+    '_',
+    String(book || 'manual'),
+    ...splitDotPathSegments(normalizedNodePath),
+    '_'
+  )
+}

package/src/index.js

@@ -234,11 +234,34 @@ export function createDocsector (config = {}) {
   }
 }
 
+/**
+ * Define a Docsector book entry for the pages registry.
+ *
+ * @param {Object} config - Book configuration (id, label, icon, order, color)
+ * @param {Object|string} [config.color] - Tab text color settings
+ * @param {string} [config.color.active] - Active tab text color token (Quasar color key, CSS var, or CSS color)
+ * @param {string} [config.color.inactive] - Inactive tab text color token (Quasar color key, CSS var, or CSS color)
+ * @returns {Object} Normalized book definition
+ */
+export function defineBook (config = {}) {
+  const resolvedId = typeof config.id === 'string' ? config.id : ''
+  const resolvedLabel = config.label
+    || (resolvedId ? `${resolvedId.charAt(0).toUpperCase()}${resolvedId.slice(1)}` : '')
+
+  return {
+    ...config,
+    ...(resolvedId ? { id: resolvedId } : {}),
+    ...(resolvedLabel ? { label: resolvedLabel } : {})
+  }
+}
+
 /**
  * Define a Docsector page entry for the pages registry.
  *
  * @param {Object} options - Page options
- * @param {Object} options.config - Page configuration (icon, status, type, menu, subpages)
+ * @param {Object} options.config - Page configuration (icon, status, book, menu, subpages, link)
+ * @param {Object} [options.config.link] - Optional internal navigation link (menu shortcut)
+ * @param {string} options.config.link.to - Internal destination path (e.g. '/guide/getting-started/overview/')
  * @param {Object} options.data - Per-language titles { 'en-US': { title: '...' } }
  * @returns {Object} Page definition
  */
@@ -249,4 +272,4 @@ export function definePage (options) {
   }
 }
 
-export default { createDocsector, definePage }
+export default { createDocsector, defineBook, definePage }