@docsector/docsector-reader 4.3.1 → 4.3.2

package/README.md

@@ -52,7 +52,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🌍 **Internationalization (i18n)** — Multi-language support with HJSON locale files and per-page translations
 - 🌗 **Dark/Light Mode** — Automatic theme switching with Quasar Dark Plugin
 - 🧰 **Docsector CLI Skill Installer** — Install the built-in authoring skill into older scaffolds with `docsector install-skill`
-- 🔗 **Anchor Navigation** — Right-side Table of Contents tree with stable scroll tracking, auto-scroll to the active section, and active-heading resolution based on the last heading that crossed the content threshold
+- 🔗 **Anchor Navigation** — Right-side source-ordered Table of Contents tree with stable scroll tracking, auto-scroll to the active section, and active-heading resolution based on the last heading that crossed the content threshold
 - 🖱️ **Active Menu Item UX** — Active menu entries keep pointer cursor, clear URL hash without redundant navigation, and prevent accidental label text selection
 - 🔎 **Search** — Menu search across all documentation content and tags
 - 📱 **Responsive** — Mobile-friendly with collapsible sidebar and drawers

package/bin/docsector.js

@@ -24,7 +24,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '4.3.1'
+const VERSION = '4.3.2'
 const AUTHORING_SKILL_NAME = 'docsector-documentation-authoring'
 const AUTHORING_SKILL_DESCRIPTION = 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.'
 const AUTHORING_SKILL_PUBLIC_PATH = `/.well-known/agent-skills/${AUTHORING_SKILL_NAME}/SKILL.md`

package/package.json

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

@@ -1,10 +1,11 @@
 <script setup>
-import { computed } from 'vue'
+import { computed, watch } from 'vue'
 import { useStore } from 'vuex'
 import { useI18n } from "vue-i18n"
 
 import DPageTokens from './DPageTokens.vue'
 import { pageValueI18nPath } from '../i18n/path'
+import { buildPageAnchorTree } from './page-anchor-tree'
 import { tokenizePageSectionSource } from './page-section-tokens'
 
 defineProps({
@@ -30,6 +31,10 @@ const tokenized = computed(() => {
 
   return tokenizePageSectionSource(t(pageValueI18nPath(absolute, 'source')))
 })
+
+watch(tokenized, (tokens) => {
+  store.commit('page/setAnchorTree', buildPageAnchorTree(tokens))
+}, { immediate: true })
 </script>
 
 <template>

package/src/components/page-anchor-tree.js

@@ -0,0 +1,45 @@
+const isTreeHeadingToken = (token) => token?.tag === 'h2' || token?.tag === 'h3'
+
+const hasAnchorId = (value) => value !== null && value !== undefined && value !== false && value !== ''
+
+const createRootNode = (children = []) => ({
+  id: 0,
+  children
+})
+
+const createTreeNode = (token) => ({
+  id: token.anchorId,
+  label: token.content,
+  children: []
+})
+
+export const buildPageAnchorTree = (tokens = []) => {
+  const anchors = []
+  const rootNode = createRootNode()
+  const seenAnchors = new Set()
+  let currentParentNode = null
+
+  for (const token of Array.isArray(tokens) ? tokens : []) {
+    if (!isTreeHeadingToken(token) || !hasAnchorId(token.anchorId) || seenAnchors.has(token.anchorId)) {
+      continue
+    }
+
+    seenAnchors.add(token.anchorId)
+    anchors.push(token.anchorId)
+
+    const node = createTreeNode(token)
+
+    if (token.tag === 'h3' && currentParentNode !== null) {
+      currentParentNode.children.push(node)
+      continue
+    }
+
+    rootNode.children.push(node)
+    currentParentNode = token.tag === 'h2' ? node : null
+  }
+
+  return {
+    anchors,
+    nodes: [rootNode]
+  }
+}

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

@@ -6,7 +6,7 @@ Under the hood, this behavior is powered by `DPageAnchor`.
 
 ## How It Works
 
-1. As each heading component (DH1–DH6) mounts, it registers itself in the `page/nodes` store via `useNavigator`
+1. `DPageSection` tokenizes the current subpage and rebuilds the heading tree in source order
 2. `DPageAnchor` reads the `page/nodes` getter to render the tree
 3. When the user scrolls, the scroll observer in `DPage` updates the selected anchor
 4. Clicking a tree node navigates to the corresponding heading
@@ -22,7 +22,7 @@ The implementation interacts with these store state/getters:
 
 ## Tree Rendering
 
-Uses Quasar's `QTree` component with `default-expand-all`. The node key is the heading's numeric `id`, and the label is the heading text.
+Uses Quasar's `QTree` component with `default-expand-all`. The node key is the heading `id`, and the label is the heading text. H2 tokens become top-level tree entries, and H3 tokens nest under the nearest preceding H2.
 
 The root node (from DH1) shows the page title from i18n when no label is set:
 

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

@@ -6,7 +6,7 @@ Na implementação, esse comportamento é sustentado por `DPageAnchor`.
 
 ## Como Funciona
 
-1. Conforme cada componente de título (DH1–DH6) é montado, ele se registra no store `page/nodes` via `useNavigator`
+1. `DPageSection` tokeniza a subpágina atual e reconstrói a árvore de títulos na ordem do conteúdo
 2. `DPageAnchor` lê o getter `page/nodes` para renderizar a árvore
 3. Quando o usuário faz scroll, o observador de scroll no `DPage` atualiza a âncora selecionada
 4. Clicar em um nó da árvore navega até o título correspondente
@@ -22,7 +22,7 @@ A implementação interage com estes estados/getters da store:
 
 ## Renderização da Árvore
 
-Usa o componente `QTree` do Quasar com `default-expand-all`. A chave do nó é o `id` numérico do título, e o label é o texto do título.
+Usa o componente `QTree` do Quasar com `default-expand-all`. A chave do nó é o `id` do título, e o label é o texto do título. Tokens H2 viram entradas de primeiro nível, e tokens H3 ficam aninhados no H2 anterior mais próximo.
 
 O nó raiz (do DH1) mostra o título da página do i18n quando nenhum label é definido:
 

package/src/store/Page.js

@@ -1,3 +1,50 @@
+const createDefaultNodes = () => [
+  {
+    id: 0,
+    children: []
+  }
+]
+
+const cloneNode = (node) => {
+  const clonedNode = {
+    id: node.id,
+    children: Array.isArray(node.children) ? node.children.map(cloneNode) : []
+  }
+
+  if (node.label !== undefined) {
+    clonedNode.label = node.label
+  }
+
+  return clonedNode
+}
+
+const normalizeNodes = (nodes) => {
+  if (!Array.isArray(nodes) || nodes.length === 0) {
+    return createDefaultNodes()
+  }
+
+  const [rootNode] = nodes
+
+  if (rootNode?.id !== 0) {
+    return createDefaultNodes()
+  }
+
+  return [cloneNode(rootNode)]
+}
+
+const uniqueAnchors = (anchors) => {
+  const seenAnchors = new Set()
+
+  return (Array.isArray(anchors) ? anchors : []).filter((anchorId) => {
+    if (anchorId === null || anchorId === undefined || anchorId === false || seenAnchors.has(anchorId)) {
+      return false
+    }
+
+    seenAnchors.add(anchorId)
+    return true
+  })
+}
+
 const getNodePath = (nodes, targetId, ancestry = []) => {
   for (const node of nodes) {
     const nextAncestry = [...ancestry, node.id]
@@ -18,6 +65,24 @@ const getNodePath = (nodes, targetId, ancestry = []) => {
   return null
 }
 
+const findNode = (nodes, targetId) => {
+  for (const node of nodes) {
+    if (node.id === targetId) {
+      return node
+    }
+
+    if (Array.isArray(node.children) && node.children.length > 0) {
+      const found = findNode(node.children, targetId)
+
+      if (found !== null) {
+        return found
+      }
+    }
+  }
+
+  return null
+}
+
 export default {
   namespaced: true,
 
@@ -26,12 +91,7 @@ export default {
 
     anchors: [],
 
-    nodes: [
-      {
-        id: 0,
-        children: []
-      }
-    ],
+    nodes: createDefaultNodes(),
     nodesExpanded: [0],
 
     scrolling: false,
@@ -73,29 +133,36 @@ export default {
     },
 
     resetNodes (state) {
-      state.nodes = [
-        {
-          id: 0,
-          children: []
-        }
-      ]
+      state.nodes = createDefaultNodes()
     },
     pushNodes (state, node) {
-      const found = state.nodes[0].children.find(x => x.id === node.id)
+      const found = findNode(state.nodes, node.id)
 
-      if (!found) {
-        const value = {
-          id: node.id,
-          label: node.label,
-          children: node.children
-        }
+      if (found) {
+        found.label = node.label
+        return
+      }
 
-        const children = state.nodes[0].children
-        if (node.child && children.length) {
-          children.at(-1).children.push(value)
-        } else {
-          state.nodes[0].children.push(value)
-        }
+      const value = {
+        id: node.id,
+        label: node.label,
+        children: node.children
+      }
+
+      const children = state.nodes[0].children
+      if (node.child && children.length) {
+        children.at(-1).children.push(value)
+      } else {
+        state.nodes[0].children.push(value)
+      }
+    },
+    setAnchorTree (state, { anchors = [], nodes = createDefaultNodes() } = {}) {
+      state.anchors = uniqueAnchors(anchors)
+      state.nodes = normalizeNodes(nodes)
+      state.nodesExpanded = [0]
+
+      if (state.anchor !== 0 && !state.anchors.includes(state.anchor)) {
+        state.anchor = 0
       }
     },
     resetNodesExpanded (state) {