@docsector/docsector-reader 0.1.0

package/src/pages/manual/composables/use-navigator.overview.pt-BR.md

@@ -0,0 +1,89 @@
+## Visão Geral
+
+`useNavigator` é o **composable central** que gerencia navegação por âncora, registro de títulos, rastreamento de scroll e construção da árvore de ToC. É usado por DH1–DH6, DPage e DPageAnchor.
+
+## API Retornada
+
+```javascript
+const {
+  register,   // Registrar ID de âncora
+  index,       // Adicionar nó à árvore de ToC
+  select,      // Selecionar uma âncora
+  anchor,      // Fazer scroll até uma âncora
+  scrolling,   // Handler de evento de scroll
+  navigate,    // Navegar para uma âncora (URL + scroll)
+  selected     // Ref para âncora atualmente selecionada
+} = useNavigator()
+```
+
+## Funções
+
+### register(id)
+
+Registra um ID de âncora no array `page/anchors` do store. Chamado por componentes de título no mount.
+
+```javascript
+onMounted(() => {
+  register(props.id)
+})
+```
+
+### index(id, child)
+
+Insere um nó no store `page/nodes` para construir a árvore de ToC. Chamado por DH2–DH6 após renderização.
+
+### select(id)
+
+Atualiza o estado `page/anchor` e expande o nó correspondente na árvore.
+
+### anchor(id, toSelect)
+
+Faz scroll do viewport até o elemento DOM com o ID fornecido usando o utilitário `scroll` do Quasar. Opcionalmente chama `select()` para destacar o nó na árvore de ToC.
+
+### scrolling(scroll)
+
+O handler de evento de scroll attached ao QScrollObserver do DPage. Itera sobre todas as âncoras registradas, encontra a mais próxima da posição de scroll atual e a seleciona. Só está ativo quando `page/scrolling` é `true`.
+
+### navigate(value, toAnchor)
+
+Função de navegação completa que:
+
+1. Atualiza o hash da URL via `router.push()`
+2. Faz scroll até o elemento da âncora
+3. Trata diferenças de timing entre desktop e mobile
+
+## Padrão de Uso
+
+Componentes de título usam register + index:
+
+```javascript
+const { register, index, navigate, selected } = useNavigator()
+
+onMounted(() => {
+  register(props.id)
+  selected.value = props.value
+  index(props.id)
+})
+```
+
+DPage usa scrolling:
+
+```javascript
+const { scrolling, navigate } = useNavigator()
+// scrolling é passado ao QScrollObserver
+```
+
+DPageAnchor usa navigate + anchor:
+
+```javascript
+const { navigate, anchor, selected } = useNavigator()
+// navigate é disparado pela seleção do QTree
+```
+
+## Dependências de Store
+
+- `page/anchors` — Array de IDs de âncora registrados
+- `page/nodes` — Estrutura em árvore do ToC
+- `page/nodesExpanded` — Nós expandidos da árvore
+- `page/anchor` — Âncora atualmente selecionada
+- `page/scrolling` — Se o rastreamento de scroll está ativo

package/src/pages/manual/store/modules.overview.en-US.md

@@ -0,0 +1,96 @@
+## Overview
+
+Docsector Reader uses **Vuex 4** for state management with 5 namespaced modules. Because `@quasar/app-vite` v2 dropped built-in Vuex support, the store is manually registered via `src/boot/store.js`.
+
+## Modules
+
+### App (`src/store/App.js`)
+
+Handles route-to-i18n path mapping.
+
+**Actions:**
+
+| Action | Description |
+|--------|-------------|
+| `configureLanguage(routeMatched)` | Converts route paths to i18n paths and commits to page/i18n modules |
+
+### I18n (`src/store/I18n.js`)
+
+Tracks the current i18n namespace paths.
+
+**State:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `base` | `String` | Base i18n path (e.g., `'guide.getting-started'`) |
+| `relative` | `String` | Relative i18n path (e.g., `'overview'`) |
+| `absolute` | `String` | Full i18n path (e.g., `'guide.getting-started.overview'`) |
+
+### Page (`src/store/Page.js`)
+
+Manages page navigation state, anchors, and ToC tree.
+
+**Key State:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `base` | `String` | Route base path |
+| `relative` | `String` | Subpage relative path |
+| `anchor` | `Number` | Currently selected anchor ID |
+| `anchors` | `Array` | Registered anchor IDs |
+| `scrolling` | `Boolean` | Whether scroll tracking is active |
+
+**Key Getters:**
+
+| Getter | Description |
+|--------|-------------|
+| `nodes` | ToC tree structure for DPageAnchor |
+| `nodesExpanded` | Array of expanded node IDs |
+
+### Layout (`src/store/Layout.js`)
+
+Controls layout visibility states.
+
+**Key State:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `meta` | `Boolean` | Right drawer (anchor panel) visibility |
+| `metaToggle` | `Boolean` | Whether meta toggle button is active |
+| Grid positions | `Object` | Position state for layout grid elements |
+
+### Settings (`src/store/Settings.js`)
+
+Manages the settings dialog state.
+
+**State:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dialog` | `Boolean` | Settings dialog open/close state |
+
+**Getter/Mutation:**
+
+| Name | Description |
+|------|-------------|
+| `dialog` (getter) | Returns dialog state |
+| `dialog` (mutation) | Sets dialog state |
+
+## Boot File
+
+The store is registered in `src/boot/store.js`:
+
+```javascript
+import { boot } from 'quasar/wrappers'
+import store from '../store'
+
+export default boot(async ({ app }) => {
+  app.use(store)
+})
+```
+
+This boot file **must** be listed first in `quasar.config.js`:
+
+```javascript
+boot: ['store', 'QZoom', 'i18n', 'axios']
+```

package/src/pages/manual/store/modules.overview.pt-BR.md

@@ -0,0 +1,96 @@
+## Visão Geral
+
+O Docsector Reader usa **Vuex 4** para gerenciamento de estado com 5 módulos namespaced. Como o `@quasar/app-vite` v2 removeu o suporte embutido ao Vuex, a store é registrada manualmente via `src/boot/store.js`.
+
+## Módulos
+
+### App (`src/store/App.js`)
+
+Trata o mapeamento de rota para caminho i18n.
+
+**Actions:**
+
+| Action | Descrição |
+|--------|-----------|
+| `configureLanguage(routeMatched)` | Converte caminhos de rota para caminhos i18n e faz commit nos módulos page/i18n |
+
+### I18n (`src/store/I18n.js`)
+
+Rastreia os caminhos de namespace i18n atuais.
+
+**State:**
+
+| Propriedade | Tipo | Descrição |
+|-------------|------|-----------|
+| `base` | `String` | Caminho base i18n (ex: `'guide.getting-started'`) |
+| `relative` | `String` | Caminho relativo i18n (ex: `'overview'`) |
+| `absolute` | `String` | Caminho completo i18n (ex: `'guide.getting-started.overview'`) |
+
+### Page (`src/store/Page.js`)
+
+Gerencia estado de navegação de página, âncoras e árvore de ToC.
+
+**State Principal:**
+
+| Propriedade | Tipo | Descrição |
+|-------------|------|-----------|
+| `base` | `String` | Caminho base da rota |
+| `relative` | `String` | Caminho relativo da sub-página |
+| `anchor` | `Number` | ID da âncora atualmente selecionada |
+| `anchors` | `Array` | IDs de âncora registrados |
+| `scrolling` | `Boolean` | Se o rastreamento de scroll está ativo |
+
+**Getters Principais:**
+
+| Getter | Descrição |
+|--------|-----------|
+| `nodes` | Estrutura em árvore do ToC para DPageAnchor |
+| `nodesExpanded` | Array de IDs de nós expandidos |
+
+### Layout (`src/store/Layout.js`)
+
+Controla estados de visibilidade do layout.
+
+**State Principal:**
+
+| Propriedade | Tipo | Descrição |
+|-------------|------|-----------|
+| `meta` | `Boolean` | Visibilidade do drawer direito (painel de âncoras) |
+| `metaToggle` | `Boolean` | Se o botão toggle de meta está ativo |
+| Posições grid | `Object` | Estado de posição para elementos grid do layout |
+
+### Settings (`src/store/Settings.js`)
+
+Gerencia o estado do diálogo de configurações.
+
+**State:**
+
+| Propriedade | Tipo | Descrição |
+|-------------|------|-----------|
+| `dialog` | `Boolean` | Estado aberto/fechado do diálogo de configurações |
+
+**Getter/Mutation:**
+
+| Nome | Descrição |
+|------|-----------|
+| `dialog` (getter) | Retorna estado do diálogo |
+| `dialog` (mutation) | Define estado do diálogo |
+
+## Boot File
+
+A store é registrada em `src/boot/store.js`:
+
+```javascript
+import { boot } from 'quasar/wrappers'
+import store from '../store'
+
+export default boot(async ({ app }) => {
+  app.use(store)
+})
+```
+
+Este boot file **deve** ser listado primeiro em `quasar.config.js`:
+
+```javascript
+boot: ['store', 'QZoom', 'i18n', 'axios']
+```

package/src/router/index.js

@@ -0,0 +1,30 @@
+import { route } from 'quasar/wrappers'
+import { createRouter, createMemoryHistory, createWebHistory, createWebHashHistory } from 'vue-router'
+import routes from './routes'
+
+/*
+ * If not building with SSR mode, you can
+ * directly export the Router instantiation;
+ *
+ * The function below can be async too; either use
+ * async/await or return a Promise which resolves
+ * with the Router instance.
+ */
+
+export default route(function (/* { store, ssrContext } */) {
+  const createHistory = process.env.SERVER
+    ? createMemoryHistory
+    : (process.env.VUE_ROUTER_MODE === 'history' ? createWebHistory : createWebHashHistory)
+
+  const Router = createRouter({
+    scrollBehavior: () => ({ left: 0, top: 0 }),
+    routes,
+
+    // Leave this as is and make changes in quasar.config.js instead!
+    // quasar.config.js -> build -> vueRouterMode
+    // quasar.config.js -> build -> publicPath
+    history: createHistory(process.env.MODE === 'ssr' ? void 0 : process.env.VUE_ROUTER_BASE)
+  })
+
+  return Router
+})

package/src/router/routes.js

@@ -0,0 +1,93 @@
+import pages from 'pages'
+
+const pagesRoutes = []
+for (const [path, page] of Object.entries(pages)) {
+  const config = page.config
+  if (config === null) {
+    continue
+  }
+
+  const topPage = config.type ?? 'manual'
+
+  // @ Construct children
+  const children = [
+    {
+      path: 'overview',
+      component: () => import('components/DSubpage.vue'),
+      meta: {
+        status: config.status
+      }
+    }
+  ]
+  if (config?.subpages?.showcase === true) {
+    children.push({
+      path: 'showcase',
+      component: () => import('components/DSubpage.vue'),
+      meta: {
+        status: config.status
+      }
+    })
+  }
+  if (config?.subpages?.vs === true) {
+    children.push({
+      path: 'vs',
+      component: () => import('components/DSubpage.vue'),
+      meta: {
+        status: config.status
+      }
+    })
+  }
+
+  // @ Push route to pageRoutes
+  pagesRoutes.push({
+    path: '/' + topPage + path,
+    component: () => import('layouts/DefaultLayout.vue'),
+    meta: {
+      ...config,
+      type: topPage
+    },
+    children
+  })
+}
+
+const routes = [
+  ...pagesRoutes,
+
+  {
+    path: '/',
+    component: () => import('layouts/DefaultLayout.vue'),
+    meta: {
+      layouts: {
+        footer: false,
+        submenu: false
+      },
+      pages: {}
+    },
+    children: [
+      {
+        path: '',
+        component: () => import('pages/@/BootPage.vue'),
+        meta: {
+          icon: 'home',
+          menu: 'home'
+        }
+      }
+    ]
+  },
+
+  {
+    path: '/(.*)*',
+    component: () => import('layouts/SystemLayout.vue'),
+    meta: {
+      menu: {}
+    },
+    children: [
+      {
+        path: '',
+        component: () => import('pages/@/404Page.vue')
+      }
+    ]
+  }
+]
+
+export default routes

package/src/store/App.js

@@ -0,0 +1,43 @@
+export default {
+  namespaced: true,
+
+  state: {},
+  getters: {},
+  mutations: {},
+  actions: {
+    configureLanguage ({ commit, state }, routeMatched) {
+      // Reset stale nodes before configuring new language state
+      commit('page/resetAnchor', null, { root: true })
+      commit('page/resetAnchors', null, { root: true })
+      commit('page/resetNodes', null, { root: true })
+
+      // Route
+      const firstRoutePath = routeMatched[0].path
+      const secondRoutePath = routeMatched[1].path
+
+      const base = firstRoutePath.substr(1)
+      let relative = secondRoutePath.substr(firstRoutePath.length)
+
+      commit('page/setBase', base, { root: true })
+      commit('page/setRelative', relative, { root: true })
+      commit('page/setAbsolute', base + relative, { root: true })
+
+      if (relative === '/' || relative === '') {
+        relative = '/overview'
+      }
+
+      if (firstRoutePath) {
+        const i18nBase = base.replace(/_$/, '').replace(/\//g, '.')
+        const i18nRelative = relative.replace(/_$/, '').replace(/\//g, '.')
+
+        commit('i18n/setBase', i18nBase, { root: true })
+        commit('i18n/setRelative', i18nRelative.substr(1), { root: true })
+        commit('i18n/setAbsolute', i18nBase + i18nRelative, { root: true })
+      } else {
+        commit('i18n/setBase', '', { root: true })
+        commit('i18n/setRelative', '', { root: true })
+        commit('i18n/setAbsolute', '', { root: true })
+      }
+    }
+  }
+}

package/src/store/I18n.js

@@ -0,0 +1,22 @@
+export default {
+  namespaced: true,
+
+  state: {
+    base: '',
+    relative: '',
+    absolute: ''
+  },
+  getters: {},
+  mutations: {
+    setBase (state, val) {
+      state.base = val
+    },
+    setRelative (state, val) {
+      state.relative = val
+    },
+    setAbsolute (state, val) {
+      state.absolute = val
+    }
+  },
+  actions: {}
+}

package/src/store/Layout.js

@@ -0,0 +1,124 @@
+export default {
+  namespaced: true,
+
+  state: {
+    header: true,
+    footer: true,
+    left: false,
+    right: false,
+
+    headerReveal: false,
+    footerReveal: false,
+    leftOverlay: false,
+    rightOverlay: false,
+    leftBehavior: 'default',
+    rightBehavior: 'default',
+    leftBreakpoint: 992,
+    rightBreakpoint: 992,
+
+    topleft: 'h',
+    topcenter: 'H',
+    topright: 'h',
+    middleleft: 'L',
+    middlecenter: 'p',
+    middleright: 'r',
+    bottomleft: 'l',
+    bottomcenter: 'F',
+    bottomright: 'f',
+
+    // Main
+    scrolling: true,
+    meta: true,
+    metaToggle: false
+  },
+  getters: {
+    view (state) {
+      const
+        top = `${state.topleft}${state.topcenter}${state.topright}`,
+        middle = `${state.middleleft}${state.middlecenter}${state.middleright}`,
+        bottom = `${state.bottomleft}${state.bottomcenter}${state.bottomright}`
+
+      return `${top} ${middle} ${bottom}`
+    }
+  },
+  mutations: {
+    setHeader (state, val) {
+      state.header = val
+    },
+    setHeaderReveal (state, val) {
+      state.headerReveal = val
+    },
+
+    setFooter (state, val) {
+      state.footer = val
+    },
+    setFooterReveal (state, val) {
+      state.footerReveal = val
+    },
+
+    setLeft (state, val) {
+      state.left = val
+    },
+    setLeftOverlay (state, val) {
+      state.leftOverlay = val
+    },
+    setLeftBehavior (state, val) {
+      state.leftBehavior = val
+    },
+    setLeftBreakpoint (state, val) {
+      state.leftBreakpoint = val
+    },
+
+    setRight (state, val) {
+      state.right = val
+    },
+    setRightOverlay (state, val) {
+      state.rightOverlay = val
+    },
+    setRightBehavior (state, val) {
+      state.rightBehavior = val
+    },
+    setRightBreakpoint (state, val) {
+      state.rightBreakpoint = val
+    },
+
+    setTopLeft (state, val) {
+      state.topleft = val
+    },
+    setTopCenter (state, val) {
+      state.topcenter = val
+    },
+    setTopRight (state, val) {
+      state.topright = val
+    },
+    setMiddleLeft (state, val) {
+      state.middleleft = val
+    },
+    setMiddleCenter (state, val) {
+      state.middleleft = val
+    },
+    setMiddleRight (state, val) {
+      state.middleright = val
+    },
+    setBottomLeft (state, val) {
+      state.bottomleft = val
+    },
+    setBottomCenter (state, val) {
+      state.bottomcenter = val
+    },
+    setBottomRight (state, val) {
+      state.bottomright = val
+    },
+
+    setScrolling (state, val) {
+      state.scrolling = val
+    },
+    setMeta (state, val) {
+      state.meta = val
+    },
+    setMetaToggle (state, val) {
+      state.metaToggle = val
+    }
+  },
+  actions: {}
+}

package/src/store/Page.js

@@ -0,0 +1,103 @@
+export default {
+  namespaced: true,
+
+  state: {
+    anchor: 0,
+
+    anchors: [],
+
+    nodes: [
+      {
+        id: 0,
+        children: []
+      }
+    ],
+    nodesExpanded: [0],
+
+    scrolling: false,
+
+    base: '',
+    relative: '',
+    absolute: ''
+  },
+  getters: {
+    anchors (state) {
+      return state.anchors
+    },
+
+    nodes (state) {
+      return state.nodes
+    },
+    nodesExpanded (state) {
+      return state.nodesExpanded
+    }
+  },
+  mutations: {
+    resetAnchor (state) {
+      state.anchor = 0
+    },
+    setAnchor (state, val) {
+      state.anchor = val
+    },
+
+    resetAnchors (state) {
+      state.anchors = []
+    },
+    pushAnchors (state, value) {
+      if (value === false) {
+        state.anchors = []
+      } else {
+        // index: id
+        state.anchors.push(value)
+      }
+    },
+
+    resetNodes (state) {
+      state.nodes = [
+        {
+          id: 0,
+          children: []
+        }
+      ]
+    },
+    pushNodes (state, node) {
+      const found = state.nodes[0].children.find(x => x.id === node.id)
+
+      if (!found) {
+        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)
+        }
+      }
+    },
+    resetNodesExpanded (state) {
+      state.nodesExpanded = [0]
+    },
+    pushNodesExpanded (state, nodeId) {
+      state.nodesExpanded.push(nodeId)
+    },
+
+    setScrolling (state, val) {
+      state.scrolling = val
+    },
+
+    setBase (state, val) {
+      state.base = val
+    },
+    setRelative (state, val) {
+      state.relative = val
+    },
+    setAbsolute (state, val) {
+      state.absolute = val
+    }
+  },
+  actions: {}
+}