@docsector/docsector-reader 3.0.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

package/bin/docsector.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "3.0.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",

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/DSubpage.vue

@@ -22,7 +22,7 @@ const id = computed(() => {
 </script>
 
 <template>
-<d-page>
+<d-page show-back-to-top-control>
   <header>
     <d-page-bar />
     <hr />

package/src/composables/useReadingProgress.js

@@ -0,0 +1,46 @@
+export const DEFAULT_READING_PROGRESS_THRESHOLD = 0.12
+
+const toFiniteNumber = (value) => {
+  const normalized = Number(value)
+  return Number.isFinite(normalized) ? normalized : 0
+}
+
+const clamp = (value, min, max) => {
+  return Math.min(max, Math.max(min, value))
+}
+
+export function getReadingProgressState({
+  scrollTop = 0,
+  scrollHeight = 0,
+  clientHeight = 0,
+  visibilityThreshold = DEFAULT_READING_PROGRESS_THRESHOLD
+} = {}) {
+  const normalizedClientHeight = Math.max(0, toFiniteNumber(clientHeight))
+  const normalizedScrollHeight = Math.max(0, toFiniteNumber(scrollHeight))
+  const maxScrollTop = Math.max(0, normalizedScrollHeight - normalizedClientHeight)
+
+  if (maxScrollTop === 0) {
+    return {
+      hasOverflow: false,
+      maxScrollTop: 0,
+      scrollTop: 0,
+      progressPercent: 0,
+      visibleOffset: 0,
+      isVisible: false
+    }
+  }
+
+  const normalizedScrollTop = clamp(toFiniteNumber(scrollTop), 0, maxScrollTop)
+  const normalizedThreshold = clamp(toFiniteNumber(visibilityThreshold), 0, 1)
+  const visibleOffset = Math.round(maxScrollTop * normalizedThreshold)
+  const progressPercent = Math.round((normalizedScrollTop / maxScrollTop) * 100)
+
+  return {
+    hasOverflow: true,
+    maxScrollTop,
+    scrollTop: normalizedScrollTop,
+    progressPercent,
+    visibleOffset,
+    isVisible: normalizedScrollTop >= visibleOffset && normalizedScrollTop > 0
+  }
+}

package/src/pages/manual/components/d-page.overview.en-US.md

@@ -9,6 +9,7 @@ Every documentation page is rendered inside a `DPage` instance.
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `disableNav` | `Boolean` | `false` | Hides the DPageMeta navigation footer |
+| `showBackToTopControl` | `Boolean` | `false` | Enables the floating back-to-top control with circular reading progress |
 
 ## Template Structure
 
@@ -46,6 +47,8 @@ DPage reads the route's `meta.subpages` configuration to determine which tabs to
 
 DPage resets the scroll position on route changes via `router.beforeEach`. The scroll observer monitors vertical scroll position and updates the anchor selection via the `useNavigator` composable.
 
+When `showBackToTopControl` is enabled, DPage also derives reading progress from the same scroll container. The floating control stays hidden at the top, appears after a small amount of scroll, shows circular progress, and returns to anchor `0` when clicked.
+
 ## Store Integration
 
 DPage reads from and writes to several Vuex store modules:

package/src/pages/manual/components/d-page.overview.pt-BR.md

@@ -9,6 +9,7 @@ Toda página de documentação é renderizada dentro de uma instância de `DPage
 | Prop | Tipo | Padrão | Descrição |
 |------|------|--------|-----------|
 | `disableNav` | `Boolean` | `false` | Oculta o rodapé de navegação DPageMeta |
+| `showBackToTopControl` | `Boolean` | `false` | Habilita o controle flutuante de voltar ao topo com progresso circular de leitura |
 
 ## Estrutura do Template
 
@@ -46,6 +47,8 @@ DPage lê a configuração `meta.subpages` da rota para determinar quais abas ex
 
 DPage reseta a posição de scroll nas mudanças de rota via `router.beforeEach`. O observador de scroll monitora a posição vertical e atualiza a seleção de âncora via composable `useNavigator`.
 
+Quando `showBackToTopControl` está habilitada, DPage também deriva o progresso de leitura a partir da mesma área de scroll. O controle flutuante fica oculto no topo, aparece após uma pequena rolagem, exibe progresso circular e retorna para a âncora `0` ao ser clicado.
+
 ## Integração com Store
 
 DPage lê e escreve em vários módulos da Vuex store:

package/src/pages/manual/components/d-subpage.overview.en-US.md

@@ -9,7 +9,7 @@ DSubpage generates a deterministic numeric ID from the current route path using
 ## Template
 
 ```html
-<d-page>
+<d-page show-back-to-top-control>
   <header>
     <d-h1 :id="0" />
   </header>
@@ -54,3 +54,7 @@ DSubpage is automatically used by the router for all documentation pages. You do
 - `DSubpage` **uses** `DPage` as its container
 - `DPage` handles layout (scroll, toolbar, drawer)
 - `DSubpage` handles content composition (H1 + sections)
+
+## Built-in Back to Top Control
+
+Routed documentation subpages enable DPage's floating back-to-top control automatically. The control is only shown when the content actually overflows, becomes visible after the reader scrolls a little, and visualizes the current reading progress with a circular indicator.

package/src/pages/manual/components/d-subpage.overview.pt-BR.md

@@ -9,7 +9,7 @@ DSubpage gera um ID numérico determinístico a partir do caminho da rota atual
 ## Template
 
 ```html
-<d-page>
+<d-page show-back-to-top-control>
   <header>
     <d-h1 :id="0" />
   </header>
@@ -54,3 +54,7 @@ DSubpage é usado automaticamente pelo roteador para todas as páginas de docume
 - `DSubpage` **usa** `DPage` como container
 - `DPage` cuida do layout (scroll, toolbar, drawer)
 - `DSubpage` cuida da composição de conteúdo (H1 + seções)
+
+## Controle Integrado de Voltar ao Topo
+
+As sub-páginas de documentação roteadas habilitam automaticamente o controle flutuante de voltar ao topo do DPage. O controle só é exibido quando o conteúdo realmente tem overflow, fica visível após uma pequena rolagem do leitor e mostra o progresso atual de leitura com um indicador circular.