@docsector/docsector-reader 2.3.0 → 3.1.0

package/README.md

@@ -54,6 +54,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 📚 **Book Tabs with Per-State Colors** — Define `*.book.js` tabs with icons, order, and `color.active` / `color.inactive`
 - 🔀 **Internal Shortcut Pages** — Route entries can redirect with `config.link.to`, keeping localized titles while inheriting icon/status from the destination page
 - 📐 **Responsive Subpage Toolbar** — Subpage actions align with the content column on desktop and dock to the bottom on mobile
+- ⬆️ **Reading Progress Back to Top** — Documentation subpages can show a floating back-to-top control with circular reading progress that stays above the mobile subpage toolbar
 - 🏷️ **Status Badges** — Mark pages as `done`, `draft`, `empty`, or `new` with visual indicators
 - ✏️ **Edit on GitHub** — Direct links to edit pages on your repository
 - 🧭 **Robust Edit Link Mapping** — Normalizes route paths (including trailing slashes) into `page.subpage.locale.md` source files for reliable GitHub edit URLs
@@ -66,6 +67,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🏠 **Markdown Home at Root** — Homepage is rendered from `src/pages/Homepage.{lang}.md` directly at `/`
 - 🌍 **Remote README as Home** — Optional build-time remote README source for homepage with automatic local fallback
 - 🧬 **Scaffolded Homepage Override Wiring** — New consumer projects automatically wire `virtual:docsector-homepage-override` into i18n message building
+- 📖 **Expandable Markdown Sections** — Use `<d-expandable title="...">...</d-expandable>` to collapse secondary content while keeping rich Markdown support inside the body
 - 🧭 **Quick Links Custom Element** — Use `<d-quick-links>` and `<d-quick-link>` in Markdown to render rich home navigation cards
 - 🗂️ **API Catalog Well-Known** — Auto-generates `/.well-known/api-catalog` as Linkset JSON for machine-readable API discovery
 - 🗃️ **Multi-Version History** — Archive older major versions under `src/pages/.old/<version>/` and expose them at prefixed routes (e.g. `/v0.x/guide/...`) while keeping the current docs at unprefixed routes
@@ -668,7 +670,6 @@ export default configure(() => {
 | `pages` | project `src/pages/` | consumer `src/pages/` |
 | `src/i18n` | project `src/i18n/` | consumer `src/i18n/` |
 | `docsector.config.js` | project root | consumer root |
-| `@docsector/tags` | project `src/i18n/tags.hjson` | consumer `src/i18n/tags.hjson` |
 
 ---
 
@@ -810,17 +811,29 @@ src/i18n/languages/en-US.hjson
 src/i18n/languages/pt-BR.hjson
 ```
 
-### Search tags (`src/i18n/tags.hjson`)
+### Search tags (`src/pages/*.index.js`)
 
-Provide search keywords per route and locale for menu search:
+Define search keywords per page using `metadata.tags` in each book registry file:
 
-```hjson
-{
-  "en-US": {
-    "/manual/my-section/my-page": "keyword1 keyword2 keyword3"
-  }
-  "pt-BR": {
-    "/manual/my-section/my-page": "palavra1 palavra2 palavra3"
+```javascript
+export default {
+  '/my-section/my-page': {
+    config: {
+      icon: 'description',
+      book: 'manual',
+      status: 'done',
+      subpages: { showcase: false }
+    },
+    data: {
+      'en-US': { title: 'My Page' },
+      'pt-BR': { title: 'Minha Página' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'keyword1 keyword2 keyword3',
+        'pt-BR': 'palavra1 palavra2 palavra3'
+      }
+    }
   }
 }
 ```
@@ -845,28 +858,19 @@ my-docs/
 │   │   └── manual/            # Manual pages (.md files)
 │   ├── i18n/
 │   │   ├── index.js           # Uses buildMessages() from engine
-│   │   ├── tags.hjson         # Search keywords per route/locale
 │   │   └── languages/         # HJSON locale files
 │   ├── css/
 │   │   └── app.sass           # Optional overrides (imports engine CSS)
 │   └── boot/                  # Consumer-specific boot files
 │       └── qmediaplayer.js    # Example: custom Quasar extension
 └── public/
-    ├── images/logo/           # Project logo
-    ├── images/flags/          # Locale flag images
+    ├── images/logo.png        # Project logo
+    ├── flags/                 # Locale flag images
     └── icons/                 # PWA icons
 ```
 
 ---
 
-## ⚠️ Migrating from 1.x to 2.0
-
-- Split the legacy `src/pages/index.js` registry into per-book files such as `src/pages/manual.book.js`, `src/pages/manual.index.js`, `src/pages/guide.book.js`, and `src/pages/guide.index.js`.
-- Update i18n wiring to import `books` from `virtual:docsector-books` and pass it to `buildMessages({ ... })`.
-- Rename `config.type` to `config.book` in page definitions. Legacy fallback still works, but `config.book` is the supported API moving forward.
-
----
-
 ## 📚 Defining Books (Tabs)
 
 Each documentation tab is defined by a `*.book.js` file paired with a matching `*.index.js` registry.
@@ -886,6 +890,31 @@ export default defineBook({
 })
 ```
 
+Declare menu search tags in each page entry under `metadata.tags`:
+
+```javascript
+export default {
+  '/getting-started': {
+    config: {
+      icon: 'flag',
+      book: 'guide',
+      status: 'done',
+      subpages: { showcase: false }
+    },
+    data: {
+      'en-US': { title: 'Getting Started' },
+      'pt-BR': { title: 'Começando' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'install setup start begin quick project structure',
+        'pt-BR': 'instalar configurar iniciar começar rápido projeto estrutura'
+      }
+    }
+  }
+}
+```
+
 Notes:
 
 - `color.active` and `color.inactive` control the tab text color for each state.

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '2.3.0'
+const VERSION = '3.1.0'
 
 const HELP = `
   Docsector Reader v${VERSION}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "2.3.0",
+  "version": "3.1.0",
   "description": "A documentation rendering engine built with Vue 3, Quasar v2 and Vite. Transform Markdown into beautiful, navigable documentation sites.",
   "productName": "Docsector Reader",
   "author": "Rodrigo de Araujo Vieira",
@@ -60,7 +60,8 @@
     "build": "quasar build",
     "lint": "eslint --ext .js,.vue ./",
     "format": "prettier --write \"**/*.{js,vue,scss,html,md,json}\" --ignore-path .gitignore",
-    "test": "echo \"No test specified\" && exit 0"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@quasar/app-vite": "^2.1.0",
@@ -96,7 +97,8 @@
     "eslint-plugin-n": "^15.0.0",
     "eslint-plugin-promise": "^6.0.0",
     "eslint-plugin-vue": "^9.0.0",
-    "prettier": "^2.5.1"
+    "prettier": "^2.5.1",
+    "vitest": "^2.1.8"
   },
   "browserslist": [
     "last 10 Chrome versions",

package/src/components/DMenu.vue

@@ -4,11 +4,11 @@ import { useRoute, useRouter } from 'vue-router'
 import { useQuasar, scroll, openURL } from 'quasar'
 import { useI18n } from 'vue-i18n'
 
-import tags from '@docsector/tags'
 import DMenuItem from './DMenuItem.vue'
 import docsectorConfig from 'docsector.config.js'
-import { allBooks, booksByVersion, versions } from 'virtual:docsector-books'
+import { allBooks, booksByVersion, bookTagsByVersion, versions } from 'virtual:docsector-books'
 import { namespacedLabelI18nPath, routeSubpageSourceI18nPath } from '../i18n/path'
+import { matchesBookSearchTerm } from '../search/book-search'
 
 const $q = useQuasar()
 const $route = useRoute()
@@ -42,6 +42,14 @@ const activeBooks = computed(() => {
   return allBooks || []
 })
 
+const activeBookTags = computed(() => {
+  if (activeVersionId.value && bookTagsByVersion?.[activeVersionId.value]) {
+    return bookTagsByVersion[activeVersionId.value]
+  }
+
+  return {}
+})
+
 const draftReleaseStatuses = new Set(['draft', 'unreleased', 'preview', 'next'])
 
 const versionStatusLabel = (label, releaseStatus) => {
@@ -249,15 +257,14 @@ const searchTermIterate = (items, term, locale) => {
   } else if (typeof items === 'object') {
     const item = items
     const path = item.path
+    const routeBook = item.meta?.book ?? item.meta?.type ?? null
     const tagPath = item.meta?.unversionedPath || path
     founds.value[path] = false
 
-    // @ search in i18n/tags.hjson
-    if (tags[locale] && Object.keys(tags[locale]).length > 0) {
-      founds.value[path] = tags[locale][tagPath]?.indexOf(term) !== -1
-      if (founds.value[path] === false && locale !== 'en-US') {
-        founds.value[path] = tags['en-US'][tagPath]?.indexOf(term) !== -1
-      }
+    // @ search in tags declared by active book index
+    if (routeBook) {
+      const tagsByLocale = activeBookTags.value?.[routeBook] || {}
+      founds.value[path] = matchesBookSearchTerm(tagsByLocale, locale, tagPath, term)
     }
 
     // @ search in Page content

package/src/components/DPage.vue

@@ -5,6 +5,7 @@ import { useRoute, useRouter } from 'vue-router'
 import { useQuasar } from 'quasar'
 
 import useNavigator from '../composables/useNavigator'
+import { getReadingProgressState } from '../composables/useReadingProgress'
 
 import DPageAnchor from './DPageAnchor.vue'
 import DPageMeta from './DPageMeta.vue'
@@ -20,6 +21,10 @@ const props = defineProps({
   disableNav: {
     type: Boolean,
     default: false
+  },
+  showBackToTopControl: {
+    type: Boolean,
+    default: false
   }
 })
 
@@ -29,6 +34,26 @@ const submenu = ref(null)
 const pageMinHeight = ref('calc(100vh - 86px)')
 const submenuHeight = ref('36px')
 const pageBottomInset = ref('0px')
+const readingProgress = ref(getReadingProgressState())
+
+const getPageScrollContainer = () => {
+  return pageScrollArea.value?.$el?.querySelector('.q-scrollarea__container') || null
+}
+
+const syncReadingProgress = (scrollTop = null) => {
+  const container = getPageScrollContainer()
+
+  if (!container) {
+    readingProgress.value = getReadingProgressState()
+    return
+  }
+
+  readingProgress.value = getReadingProgressState({
+    scrollTop: scrollTop ?? container.scrollTop,
+    scrollHeight: container.scrollHeight,
+    clientHeight: container.clientHeight
+  })
+}
 
 const updatePageMinHeight = () => {
   const pageContainerEl = pageContainer.value?.$el || pageContainer.value
@@ -47,6 +72,7 @@ const updatePageMinHeight = () => {
   pageMinHeight.value = `calc(100vh - ${totalOffset}px)`
   submenuHeight.value = `${Math.max(36, Math.round(measuredSubmenuHeight))}px`
   pageBottomInset.value = isMobile ? submenuHeight.value : '0px'
+  syncReadingProgress()
 }
 
 const schedulePageMinHeightUpdate = () => {
@@ -80,6 +106,12 @@ const main = computed(() => {
       return 'overview'
   }
 })
+const shouldShowBackToTopControl = computed(() => {
+  return props.showBackToTopControl && readingProgress.value.hasOverflow && readingProgress.value.isVisible
+})
+const backToTopRightOffset = computed(() => {
+  return layoutMeta.value && !$q.screen.lt.md ? '332px' : '24px'
+})
 
 const toggleSectionsTree = () => {
   layoutMeta.value = !layoutMeta.value
@@ -133,10 +165,7 @@ const resetPageScroll = () => {
   if (pageScrollArea.value !== null) {
     pageScrollArea.value.setScrollPosition('vertical', 0, 0)
   }
-}
-
-const getPageScrollContainer = () => {
-  return pageScrollArea.value?.$el?.querySelector('.q-scrollarea__container') || null
+  syncReadingProgress(0)
 }
 
 const isEditableTarget = (target) => {
@@ -208,6 +237,15 @@ const handleMainScrollKeys = (event) => {
   container.scrollTop = nextTop
 }
 
+const handlePageScroll = (scrollState) => {
+  scrolling(scrollState)
+  syncReadingProgress(scrollState?.position?.top)
+}
+
+const scrollToTop = () => {
+  navigate(0)
+}
+
 onMounted(() => {
   window.addEventListener('keydown', handleMainScrollKeys)
   window.addEventListener('resize', schedulePageMinHeightUpdate)
@@ -236,6 +274,7 @@ onBeforeUnmount(() => {
 watch(() => route.fullPath, () => {
   nextTick(() => {
     schedulePageMinHeightUpdate()
+    syncReadingProgress(0)
   })
 })
 </script>
@@ -292,10 +331,38 @@ watch(() => route.fullPath, () => {
         <slot />
       </div>
       <d-page-meta v-if="!disableNav" />
-      <q-scroll-observer @scroll="scrolling" :debounce="300" />
+      <q-scroll-observer @scroll="handlePageScroll" :debounce="300" />
     </q-scroll-area>
   </q-page>
 
+  <div
+    v-if="shouldShowBackToTopControl"
+    class="d-back-to-top"
+    :style="{ '--d-back-to-top-right': backToTopRightOffset }"
+  >
+    <q-circular-progress
+      class="d-back-to-top__progress"
+      :value="readingProgress.progressPercent"
+      size="58px"
+      :thickness="0.16"
+      color="primary"
+      track-color="grey-5"
+    />
+    <q-btn
+      class="d-back-to-top__button"
+      round
+      dense
+      unelevated
+      color="dark"
+      text-color="white"
+      icon="north"
+      :aria-label="$t('system.backToTop')"
+      @click="scrollToTop"
+    >
+      <q-tooltip anchor="top middle" self="bottom middle" :offset="[10, 10]">{{ $t('system.backToTop') }}</q-tooltip>
+    </q-btn>
+  </div>
+
   <q-drawer elevated show-if-above side="right" v-model="layoutMeta">
     <d-page-anchor id="anchor" />
   </q-drawer>
@@ -321,6 +388,25 @@ watch(() => route.fullPath, () => {
 #page
   min-height: var(--d-page-min-height, calc(100vh - 86px)) !important
 
+.d-back-to-top
+  position: fixed
+  right: var(--d-back-to-top-right, 24px)
+  bottom: calc(24px + var(--d-page-bottom-inset, 0px) + env(safe-area-inset-bottom, 0px))
+  width: 58px
+  height: 58px
+  z-index: 1200
+  filter: drop-shadow(0 8px 18px rgba(0,0,0,0.2))
+
+  .d-back-to-top__progress,
+  .d-back-to-top__button
+    position: absolute
+    inset: 0
+
+  .d-back-to-top__button
+    margin: auto
+    width: 40px
+    height: 40px
+
 #scroll-container
   width: 100%
   max-width: 1200px
@@ -425,4 +511,12 @@ body.mobile.body--dark
 body.mobile
   .q-drawer--right
     background: rgba(255, 255, 255, 0.7)
+
+body.body--light
+  .d-back-to-top__progress
+    color: var(--q-primary)
+
+body.body--dark
+  .d-back-to-top__progress
+    color: #58d1a8
 </style>

package/src/components/DPageExpandable.vue

@@ -0,0 +1,78 @@
+<script setup>
+defineProps({
+  title: {
+    type: String,
+    default: ''
+  },
+  open: {
+    type: Boolean,
+    default: false
+  }
+})
+</script>
+
+<template>
+<q-expansion-item
+  class="d-page-expandable"
+  switch-toggle-side
+  :default-opened="open"
+  header-class="d-page-expandable__header"
+  content-class="d-page-expandable__content"
+>
+  <template #header>
+    <q-item-section>
+      <div class="d-page-expandable__title">{{ title }}</div>
+    </q-item-section>
+  </template>
+
+  <div class="d-page-expandable__body">
+    <slot />
+  </div>
+</q-expansion-item>
+</template>
+
+<style lang="sass">
+body.body--light
+  --d-page-expandable-bg: #faf8f2
+  --d-page-expandable-border: rgba(116, 92, 46, 0.18)
+  --d-page-expandable-divider: rgba(116, 92, 46, 0.12)
+  --d-page-expandable-shadow: rgba(116, 92, 46, 0.08)
+
+body.body--dark
+  --d-page-expandable-bg: rgba(255, 248, 235, 0.035)
+  --d-page-expandable-border: rgba(255, 235, 194, 0.14)
+  --d-page-expandable-divider: rgba(255, 235, 194, 0.08)
+  --d-page-expandable-shadow: rgba(0, 0, 0, 0.28)
+
+.d-page-expandable
+  margin: 1.5rem 0
+  border: 1px solid var(--d-page-expandable-border)
+  border-radius: 16px
+  overflow: hidden
+  background: var(--d-page-expandable-bg)
+  box-shadow: 0 14px 32px var(--d-page-expandable-shadow)
+
+  .q-item
+    min-height: 0
+    padding: 0
+
+  .q-item__section--side
+    padding-left: 0.55rem
+
+.d-page-expandable__header
+  padding: 0.95rem 1rem
+
+.d-page-expandable__title
+  font-size: 1rem
+  font-weight: 700
+  line-height: 1.45
+
+.d-page-expandable__body
+  padding: 1rem 1rem 1.1rem
+
+  > :first-child
+    margin-top: 0
+
+  > :last-child
+    margin-bottom: 0
+</style>