@docsector/docsector-reader 1.7.1 → 2.0.0

package/src/layouts/DefaultLayout.vue

@@ -17,6 +17,27 @@
       </q-toolbar-title>
       <q-btn class="filled" square icon="settings" aria-label="Configuration" @click="openSettingsDialog" />
     </q-toolbar>
+
+    <q-tabs
+      v-if="sortedBooks.length > 0"
+      :model-value="activeBookTab"
+      dense
+      align="left"
+      narrow-indicator
+      class="bg-primary d-book-tabs"
+      @update:model-value="onBookTabChange"
+    >
+      <q-tab
+        v-for="book in sortedBooks"
+        :key="book.id"
+        :name="book.id"
+        :label="book.label"
+        :icon="book.icon"
+        class="d-book-tab"
+        :style="getBookTabStyle(book)"
+        no-caps
+      />
+    </q-tabs>
   </q-header>
 
   <q-drawer elevated show-if-above side="left" v-model="layout.menu">
@@ -32,10 +53,12 @@ import { ref, computed } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useStore } from 'vuex'
 import { useI18n } from 'vue-i18n'
-import { useMeta } from 'quasar'
+import { useMeta, colors } from 'quasar'
 
 import DMenu from '../components/DMenu.vue'
 import docsectorConfig from 'docsector.config.js'
+import { allBooks } from 'virtual:docsector-books'
+import { pageTitleI18nPath } from '../i18n/path'
 
 defineOptions({ name: 'LayoutDefault' })
 
@@ -56,12 +79,121 @@ const headerTitleIcon = computed(() => {
 
 const headerTitleText = computed(() => {
   if (store.state.i18n.base) {
-    return t(`_.${store.state.i18n.base}._`)
+    return t(pageTitleI18nPath(store.state.i18n.base))
   } else {
     return t(`menu.${route.matched[1].meta.menu}`)
   }
 })
 
+const defaultBookTabColors = Object.freeze({
+  active: 'white',
+  inactive: 'rgba(255, 255, 255, 0.72)'
+})
+
+const quasarBrandColorPattern = /^(primary|secondary|accent|dark|positive|negative|info|warning)$/
+const quasarUtilityColorPattern = /^(white|black|transparent|separator|dark-separator)$/
+const quasarPaletteColorPattern = /^(red|pink|purple|deep-purple|indigo|blue|light-blue|cyan|teal|green|light-green|lime|yellow|amber|orange|deep-orange|brown|grey|blue-grey)(-(?:[1-9]|1[0-4]))?$/
+
+const isQuasarColorToken = (token) => {
+  return quasarBrandColorPattern.test(token)
+    || quasarUtilityColorPattern.test(token)
+    || quasarPaletteColorPattern.test(token)
+}
+
+const normalizeBookTabColors = (book) => {
+  const color = book?.color
+
+  if (typeof color === 'object' && color !== null && !Array.isArray(color)) {
+    const active = typeof color.active === 'string' && color.active.trim().length > 0
+      ? color.active.trim()
+      : defaultBookTabColors.active
+
+    const inactive = typeof color.inactive === 'string' && color.inactive.trim().length > 0
+      ? color.inactive.trim()
+      : active
+
+    return { active, inactive }
+  }
+
+  if (typeof color === 'string' && color.trim().length > 0) {
+    const normalized = color.trim()
+    return {
+      active: normalized,
+      inactive: normalized
+    }
+  }
+
+  return { ...defaultBookTabColors }
+}
+
+const resolveBookTabColor = (token) => {
+  const normalized = String(token || '').trim()
+  if (normalized.length === 0) {
+    return ''
+  }
+
+  if (normalized.startsWith('var(')) {
+    return normalized
+  }
+
+  if (normalized.startsWith('--')) {
+    return `var(${normalized})`
+  }
+
+  if (/^(#|rgb\(|rgba\(|hsl\(|hsla\()/i.test(normalized)) {
+    return normalized
+  }
+
+  if (['inherit', 'currentColor', 'transparent', 'initial', 'unset', 'revert', 'revert-layer'].includes(normalized)) {
+    return normalized
+  }
+
+  if (isQuasarColorToken(normalized)) {
+    if (typeof document === 'undefined') {
+      return quasarBrandColorPattern.test(normalized)
+        ? `var(--q-${normalized})`
+        : normalized
+    }
+
+    try {
+      return colors.getPaletteColor(normalized)
+    } catch {
+      return normalized
+    }
+  }
+
+  return normalized
+}
+
+const getBookTabStyle = (book) => {
+  const colors = normalizeBookTabColors(book)
+  const active = resolveBookTabColor(colors.active) || resolveBookTabColor(defaultBookTabColors.active)
+  const inactive = resolveBookTabColor(colors.inactive) || resolveBookTabColor(defaultBookTabColors.inactive)
+
+  return {
+    '--d-book-tab-active-color': active,
+    '--d-book-tab-inactive-color': inactive
+  }
+}
+
+const sortedBooks = computed(() => {
+  return [...(allBooks || [])]
+    .filter(book => book && typeof book.id === 'string' && book.id.length > 0)
+    .sort((a, b) => {
+      const orderA = Number.isFinite(a.order) ? a.order : Number.MAX_SAFE_INTEGER
+      const orderB = Number.isFinite(b.order) ? b.order : Number.MAX_SAFE_INTEGER
+      return orderA - orderB
+    })
+})
+
+const activeBookTab = computed(() => {
+  const routeBook = route.matched?.[0]?.meta?.book ?? route.meta?.book ?? null
+  if (!routeBook || routeBook === 'home') return null
+
+  const exists = sortedBooks.value.some(book => book.id === routeBook)
+  return exists ? routeBook : null
+})
+
 const resolveLocalizedValue = (source) => {
   if (!source) return ''
   if (typeof source === 'string') return source
@@ -125,6 +257,43 @@ function openSettingsDialog () {
   store.commit('settings/dialog', true)
 }
 
+function getFirstRoutePathByBook (bookId) {
+  const routes = router.options?.routes || []
+  let fallbackPath = null
+
+  for (const topRoute of routes) {
+    if (!topRoute || typeof topRoute.path !== 'string') continue
+    if ((topRoute.meta?.book ?? topRoute.meta?.type) !== bookId) continue
+
+    const children = Array.isArray(topRoute.children) ? topRoute.children : []
+    const hasOverview = children.some(child => child.path === 'overview')
+    if (!hasOverview) continue
+
+    const candidatePath = `${topRoute.path.replace(/\/$/, '')}/overview/`
+    if (fallbackPath === null) {
+      fallbackPath = candidatePath
+    }
+
+    const hasInternalLink = typeof topRoute.meta?.link?.to === 'string' && topRoute.meta.link.to.trim().length > 0
+    if (hasInternalLink) {
+      continue
+    }
+
+    return candidatePath
+  }
+
+  return fallbackPath || '/'
+}
+
+function onBookTabChange (bookId) {
+  if (!bookId) return
+
+  const targetPath = getFirstRoutePathByBook(bookId)
+  if (route.path !== targetPath) {
+    router.push(targetPath)
+  }
+}
+
 // --- created logic (runs at setup time) ---
 store.dispatch('app/configureLanguage', route.matched)
 
@@ -143,6 +312,16 @@ store.commit('page/resetAnchors')
   &.left-btn
     .q-toolbar
       padding: 0
+  .q-tabs
+    margin-top: 2px
+  .d-book-tabs
+    .q-tab__indicator
+      background-color: currentColor
+  .d-book-tab
+    color: var(--d-book-tab-inactive-color, rgba(255, 255, 255, 0.72))
+    transition: color 0.2s ease
+  .d-book-tab.q-tab--active
+    color: var(--d-book-tab-active-color, #ffffff)
   .q-btn
     border-radius: 0
   .q-btn:before

package/src/pages/guide/getting-started.overview.en-US.md

@@ -59,7 +59,8 @@ After `init`, your project will have this structure:
 - `docsector.config.js` — Branding, links, languages, GitHub config
 - `quasar.config.js` — Thin wrapper using `createQuasarConfig()` from the package
 - `index.html` — HTML entry point with title and meta tags
-- `src/pages/index.js` — Page registry (routes and metadata)
+- `src/pages/guide.book.js` — Guide book metadata (tab)
+- `src/pages/guide.index.js` — Guide page registry (routes and metadata)
 - `src/pages/guide/` — Guide-type pages (Markdown files)
 - `src/pages/manual/` — Manual-type pages (Markdown files)
 - `src/i18n/index.js` — i18n loader using `buildMessages()` from the package
@@ -71,7 +72,7 @@ The rendering engine (components, layouts, router, store, composables) lives ins
 ## Next Steps
 
 - Configure your project branding in **docsector.config.js**
-- Define your pages in **src/pages/index.js**
+- Define your pages in **src/pages/guide.index.js** (and other `*.index.js` registries)
 - Write your documentation in **Markdown**
 - Add search keywords in **src/i18n/tags.hjson**
 - Customize themes and appearance

package/src/pages/guide/getting-started.overview.pt-BR.md

@@ -59,7 +59,8 @@ Após o `init`, seu projeto terá esta estrutura:
 - `docsector.config.js` — Branding, links, idiomas, config do GitHub
 - `quasar.config.js` — Wrapper fino usando `createQuasarConfig()` do pacote
 - `index.html` — Ponto de entrada HTML com título e meta tags
-- `src/pages/index.js` — Registro de páginas (rotas e metadata)
+- `src/pages/guide.book.js` — Metadata do book Guide (aba)
+- `src/pages/guide.index.js` — Registro de páginas do Guide (rotas e metadata)
 - `src/pages/guide/` — Páginas tipo guia (arquivos Markdown)
 - `src/pages/manual/` — Páginas tipo manual (arquivos Markdown)
 - `src/i18n/index.js` — Loader i18n usando `buildMessages()` do pacote
@@ -71,7 +72,7 @@ O motor de renderização (componentes, layouts, router, store, composables) fic
 ## Próximos Passos
 
 - Configure o branding do seu projeto em **docsector.config.js**
-- Defina suas páginas em **src/pages/index.js**
+- Defina suas páginas em **src/pages/guide.index.js** (e outros registros `*.index.js`)
 - Escreva sua documentação em **Markdown**
 - Adicione palavras-chave de busca em **src/i18n/tags.hjson**
 - Personalize temas e aparência

package/src/pages/guide/pages-and-routing.overview.en-US.md

@@ -1,6 +1,6 @@
 ## Page Registry
 
-All documentation pages are defined in `src/pages/index.js`. Each entry maps a URL path to its configuration, translatable data, and optional metadata.
+Documentation pages are defined in split registries such as `src/pages/guide.index.js` and `src/pages/manual.index.js`. Each entry maps a URL path to its configuration, translatable data, and optional metadata.
 
 ## Page Entry Structure
 
@@ -9,7 +9,7 @@ All documentation pages are defined in `src/pages/index.js`. Each entry maps a U
   config: {
     icon: 'description',
     status: 'done',
-    type: 'guide',
+    book: 'guide',
     menu: {},
     subpages: { showcase: false }
   },
@@ -22,7 +22,7 @@ All documentation pages are defined in `src/pages/index.js`. Each entry maps a U
 
 ## Config Properties
 
-- **type** — Route prefix: `'guide'`, `'manual'`, or `'API'`
+- **book** — Route prefix: `'guide'`, `'manual'`, or `'API'` (legacy `type` is still supported)
 - **status** — Page status: `'done'`, `'draft'`, or `'empty'`
 - **icon** — Material Design icon name shown in the sidebar
 - **menu** — Object controlling menu display (header, subheader, separator)
@@ -68,9 +68,9 @@ menu: {
 
 Each page requires Markdown files following this naming pattern:
 
-`src/pages/{type}/{path}.{subpage}.{lang}.md`
+`src/pages/{book}/{path}.{subpage}.{lang}.md`
 
-For example, a page at `/components/d-page` with type `manual`:
+For example, a page at `/components/d-page` with book `manual`:
 
 - `src/pages/manual/components/d-page.overview.en-US.md`
 - `src/pages/manual/components/d-page.overview.pt-BR.md`
@@ -78,7 +78,7 @@ For example, a page at `/components/d-page` with type `manual`:
 
 ## Route Generation
 
-Routes are automatically generated from the page registry. A page with path `/my-page` and type `guide` produces:
+Routes are automatically generated from the page registry. A page with path `/my-page` and book `guide` produces:
 
 - `/guide/my-page/overview` — Main content tab
 - `/guide/my-page/showcase` — Showcase tab (if enabled)

package/src/pages/guide/pages-and-routing.overview.pt-BR.md

@@ -1,6 +1,6 @@
 ## Registro de Páginas
 
-Todas as páginas de documentação são definidas em `src/pages/index.js`. Cada entrada mapeia um caminho URL para sua configuração, dados traduzíveis e metadata opcional.
+As páginas de documentação são definidas em registros separados, como `src/pages/guide.index.js` e `src/pages/manual.index.js`. Cada entrada mapeia um caminho URL para sua configuração, dados traduzíveis e metadata opcional.
 
 ## Estrutura de uma Entrada
 
@@ -9,7 +9,7 @@ Todas as páginas de documentação são definidas em `src/pages/index.js`. Cada
   config: {
     icon: 'description',
     status: 'done',
-    type: 'guide',
+    book: 'guide',
     menu: {},
     subpages: { showcase: false }
   },
@@ -22,7 +22,7 @@ Todas as páginas de documentação são definidas em `src/pages/index.js`. Cada
 
 ## Propriedades do Config
 
-- **type** — Prefixo da rota: `'guide'`, `'manual'` ou `'API'`
+- **book** — Prefixo da rota: `'guide'`, `'manual'` ou `'API'` (compatível com `type` legado)
 - **status** — Status da página: `'done'`, `'draft'` ou `'empty'`
 - **icon** — Nome do ícone Material Design exibido no menu lateral
 - **menu** — Objeto controlando exibição do menu (header, subheader, separator)
@@ -68,9 +68,9 @@ menu: {
 
 Cada página requer arquivos Markdown seguindo este padrão de nomenclatura:
 
-`src/pages/{type}/{path}.{subpage}.{lang}.md`
+`src/pages/{book}/{path}.{subpage}.{lang}.md`
 
-Por exemplo, uma página em `/components/d-page` com type `manual`:
+Por exemplo, uma página em `/components/d-page` com book `manual`:
 
 - `src/pages/manual/components/d-page.overview.en-US.md`
 - `src/pages/manual/components/d-page.overview.pt-BR.md`
@@ -78,7 +78,7 @@ Por exemplo, uma página em `/components/d-page` com type `manual`:
 
 ## Geração de Rotas
 
-Rotas são geradas automaticamente a partir do registro de páginas. Uma página com path `/my-page` e type `guide` produz:
+Rotas são geradas automaticamente a partir do registro de páginas. Uma página com path `/my-page` e book `guide` produz:
 
 - `/guide/my-page/overview` — Aba de conteúdo principal
 - `/guide/my-page/showcase` — Aba de demonstração (se habilitada)

package/src/pages/guide.book.js

@@ -0,0 +1,12 @@
+import { defineBook } from '../index.js'
+
+export default defineBook({
+  id: 'guide',
+  label: 'Guide',
+  icon: 'school',
+  order: 2,
+  color: {
+    active: 'white',
+    inactive: 'secondary'
+  }
+})

package/src/pages/guide.index.js

@@ -0,0 +1,184 @@
+export default {
+  '/getting-started': {
+    config: {
+      icon: 'flag',
+      status: 'done',
+      meta: {
+        description: {
+          'en-US': 'Getting Started — Documentation of Docsector Reader',
+          'pt-BR': 'Começando — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'guide',
+      menu: {
+        header: {
+          icon: 'school',
+          label: 'Guides'
+        }
+      },
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Getting Started' },
+      'pt-BR': { title: 'Começando' }
+    }
+  },
+
+  '/configuration': {
+    config: {
+      icon: 'tune',
+      status: 'done',
+      meta: {
+        description: {
+          'en-US': 'Configuration — Documentation of Docsector Reader',
+          'pt-BR': 'Configuração — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'guide',
+      menu: {
+        separator: ' page'
+      },
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Configuration' },
+      'pt-BR': { title: 'Configuração' }
+    }
+  },
+
+  '/pages-and-routing': {
+    config: {
+      icon: 'route',
+      status: 'done',
+      meta: {
+        description: {
+          'en-US': 'Pages & Routing — Documentation of Docsector Reader',
+          'pt-BR': 'Páginas & Rotas — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Pages & Routing' },
+      'pt-BR': { title: 'Páginas & Rotas' }
+    }
+  },
+
+  '/i18n-and-markdown': {
+    config: {
+      icon: 'translate',
+      status: 'done',
+      meta: {
+        description: {
+          'en-US': 'i18n & Markdown — Documentation of Docsector Reader',
+          'pt-BR': 'i18n & Markdown — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'i18n & Markdown' },
+      'pt-BR': { title: 'i18n & Markdown' }
+    }
+  },
+
+  '/alerts-and-blockquotes': {
+    config: {
+      icon: 'notification_important',
+      status: 'done',
+      meta: {
+        description: {
+          'en-US': 'Alerts & Blockquotes — Documentation of Docsector Reader',
+          'pt-BR': 'Alertas & Blockquotes — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Alerts & Blockquotes' },
+      'pt-BR': { title: 'Alertas & Blockquotes' }
+    }
+  },
+
+  '/theming': {
+    config: {
+      icon: 'palette',
+      status: 'done',
+      meta: {
+        description: {
+          'en-US': 'Theming — Documentation of Docsector Reader',
+          'pt-BR': 'Temas — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Theming' },
+      'pt-BR': { title: 'Temas' }
+    }
+  },
+
+  '/deployment': {
+    config: {
+      icon: 'cloud_upload',
+      status: 'draft',
+      meta: {
+        description: {
+          'en-US': 'Deployment — Documentation of Docsector Reader',
+          'pt-BR': 'Deploy — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Deployment' },
+      'pt-BR': { title: 'Deploy' }
+    }
+  },
+
+  '/plugins': {
+    config: {
+      icon: 'extension',
+      status: 'empty',
+      meta: {
+        description: {
+          'en-US': 'Plugins — Documentation of Docsector Reader',
+          'pt-BR': 'Plugins — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Plugins' },
+      'pt-BR': { title: 'Plugins' }
+    }
+  }
+}

package/src/pages/manual.book.js

@@ -0,0 +1,12 @@
+import { defineBook } from '../index.js'
+
+export default defineBook({
+  id: 'manual',
+  label: 'Manual',
+  icon: 'menu_book',
+  order: 1,
+  color: {
+    active: 'white',
+    inactive: 'primary'
+  }
+})