@docsector/docsector-reader 4.0.0 → 4.1.0

package/src/examples/manual/code-examples/InlineNotice.vue

@@ -0,0 +1,60 @@
+<template>
+  <div class="inline-notice-example q-pa-md">
+    <q-banner rounded class="inline-notice-example__banner">
+      <template #avatar>
+        <q-icon name="tips_and_updates" color="primary"></q-icon>
+      </template>
+
+      <div class="text-weight-medium">{{ title }}</div>
+      <div class="text-body2">{{ message }}</div>
+
+      <template #action>
+        <q-btn flat color="primary" label="Dismiss" @click="dismiss"></q-btn>
+      </template>
+    </q-banner>
+
+    <div v-if="dismissed" class="inline-notice-example__status text-caption">
+      The notice was dismissed.
+    </div>
+  </div>
+</template>
+
+<script>
+import { ref } from 'vue'
+
+export default {
+  setup () {
+    const title = 'Documentation tip'
+    const message = 'Use expanded examples when the source code is part of the lesson.'
+    const dismissed = ref(false)
+
+    function dismiss () {
+      dismissed.value = true
+    }
+
+    return {
+      dismissed,
+      dismiss,
+      message,
+      title
+    }
+  }
+}
+</script>
+
+<style scoped>
+.inline-notice-example {
+  display: grid;
+  gap: 10px;
+}
+
+.inline-notice-example__banner {
+  background: rgba(25, 118, 210, 0.08);
+  border: 1px solid rgba(25, 118, 210, 0.18);
+}
+
+.inline-notice-example__status {
+  color: #607d68;
+  padding-left: 8px;
+}
+</style>

package/src/home-page-mode.js

@@ -0,0 +1,5 @@
+export const REMOTE_README_HOME_PAGE_MODE = 'remote-readme'
+
+export function usesRemoteReadmeHomeContent ({ pageBase = '', homePageSourceMode = 'local' } = {}) {
+  return pageBase === 'home' && homePageSourceMode === REMOTE_README_HOME_PAGE_MODE
+}

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

@@ -39,7 +39,7 @@ The root node (from DH1) shows the page title from i18n when no label is set:
 
 ## Scroll Synchronization
 
-When the user scrolls the page content, the `DPage` scroll observer calls `useNavigator().scrolling()`, which iterates over registered anchors and selects the one closest to the current scroll position. This keeps the table of contents in sync with the visible content.
+When the user scrolls the page content, the `DPage` scroll observer calls `useNavigator().scrolling()`, which selects the last registered heading that crossed the content threshold. Missing or stale anchors are ignored so the table of contents stays in sync with the visible section instead of jumping ahead.
 
 ## Lifecycle
 

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

@@ -39,7 +39,7 @@ O nó raiz (do DH1) mostra o título da página do i18n quando nenhum label é d
 
 ## Sincronização de Scroll
 
-Quando o usuário faz scroll no conteúdo da página, o observador de scroll do `DPage` chama `useNavigator().scrolling()`, que itera sobre as âncoras registradas e seleciona a mais próxima da posição de scroll atual. Isso mantém o índice sincronizado com o conteúdo visível.
+Quando o usuário faz scroll no conteúdo da página, o observador de scroll do `DPage` chama `useNavigator().scrolling()`, que seleciona o último heading registrado que cruzou o limite superior da área de conteúdo. Âncoras ausentes ou obsoletas são ignoradas para manter o índice sincronizado com a seção realmente visível, sem saltar adiante.
 
 ## Ciclo de Vida
 

package/src/pages/manual/content/blocks/code-examples.overview.en-US.md

@@ -0,0 +1,56 @@
+## Overview
+
+Code example blocks render project Vue SFCs as live previews inside Markdown pages.
+
+They are useful when documentation needs to show the real behavior of a component and still let readers inspect the exact source behind the preview.
+
+The block is authored with the custom Markdown element `<d-block-code-example>`.
+
+## Example Files
+
+Place example components under `src/examples/**/*.vue` in the project using Docsector.
+
+Docsector discovers those files at build time through Vite. The `src` value is normalized to kebab-case, so this block:
+
+```html
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter" />
+```
+
+resolves this file:
+
+```text
+src/examples/manual/code-examples/BasicCounter.vue
+```
+
+You can also use `file` instead of `src` when migrating examples from Quasar Docs patterns.
+
+## Attributes
+
+| Attribute | Purpose |
+|-----------|---------|
+| `src` | Example id under `src/examples/**/*.vue` |
+| `file` | Alias for `src` |
+| `title` | Header title shown above the preview |
+| `expanded` | Opens the source panel by default when set to `true` |
+| `codepen` | Shows the CodePen action unless set to `false` |
+| `scrollable` | Gives the preview a fixed scrollable height |
+| `overflow` | Allows both horizontal and vertical overflow in the preview |
+| `height` | Sets a custom preview height, such as `360` or `420px` |
+
+## Source Panel
+
+The source button opens the Vue SFC split into Template, Script, Style, and All tabs when those sections are present.
+
+The source panel reuses the standard Docsector code block renderer, so readers get syntax highlighting, copy support, and the same dark/light treatment as regular code blocks.
+
+## GitHub Source Link
+
+The GitHub button opens the example SFC in the project repository when Docsector can derive a repository URL from `github.editBaseUrl` or `links.github` in `docsector.config.js`.
+
+## CodePen Export
+
+The CodePen button is available when the source can be transformed safely for a browser-only demo.
+
+The first implementation supports plain Vue SFCs with a template, optional style, and an Options API `export default` script. Named imports from `vue` and `quasar` are converted to browser globals. Examples that use `<script setup>`, TypeScript scripts, or local imports still render in Docsector, but the CodePen action is disabled.
+
+Set `codepen="false"` when an example is intentionally not meant to be exported.

package/src/pages/manual/content/blocks/code-examples.overview.pt-BR.md

@@ -0,0 +1,56 @@
+## Visão geral
+
+Blocos de exemplos de código renderizam SFCs Vue do projeto como previews ao vivo dentro das páginas Markdown.
+
+Eles são úteis quando a documentação precisa mostrar o comportamento real de um componente e ainda permitir que leitores inspecionem o código fonte exato por trás do preview.
+
+O bloco é escrito com o elemento Markdown customizado `<d-block-code-example>`.
+
+## Arquivos de exemplo
+
+Coloque os componentes de exemplo em `src/examples/**/*.vue` no projeto que usa o Docsector.
+
+O Docsector descobre esses arquivos durante o build com Vite. O valor de `src` é normalizado para kebab-case, então este bloco:
+
+```html
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter" />
+```
+
+resolve este arquivo:
+
+```text
+src/examples/manual/code-examples/BasicCounter.vue
+```
+
+Também é possível usar `file` no lugar de `src` ao migrar exemplos inspirados nos padrões do Quasar Docs.
+
+## Atributos
+
+| Atributo | Finalidade |
+|----------|------------|
+| `src` | Id do exemplo dentro de `src/examples/**/*.vue` |
+| `file` | Alias de `src` |
+| `title` | Título exibido acima do preview |
+| `expanded` | Abre o painel de fonte por padrão quando definido como `true` |
+| `codepen` | Mostra a ação do CodePen, exceto quando definido como `false` |
+| `scrollable` | Dá ao preview uma altura fixa com rolagem |
+| `overflow` | Permite overflow horizontal e vertical no preview |
+| `height` | Define uma altura customizada para o preview, como `360` ou `420px` |
+
+## Painel de fonte
+
+O botão de fonte abre o SFC Vue dividido em abas Template, Script, Style e All quando essas seções existem.
+
+O painel reutiliza o renderizador padrão de blocos de código do Docsector, então leitores recebem syntax highlighting, suporte a cópia e o mesmo tratamento visual em temas claro e escuro.
+
+## Link de fonte no GitHub
+
+O botão do GitHub abre o SFC do exemplo no repositório do projeto quando o Docsector consegue derivar a URL a partir de `github.editBaseUrl` ou `links.github` em `docsector.config.js`.
+
+## Exportação para CodePen
+
+O botão do CodePen fica disponível quando o código pode ser transformado com segurança para uma demo somente no navegador.
+
+A primeira implementação suporta SFCs Vue simples com template, style opcional e script Options API com `export default`. Imports nomeados de `vue` e `quasar` são convertidos para globais do navegador. Exemplos que usam `<script setup>`, scripts TypeScript ou imports locais continuam renderizando no Docsector, mas a ação do CodePen fica desativada.
+
+Use `codepen="false"` quando um exemplo intencionalmente não deve ser exportado.

package/src/pages/manual/content/blocks/code-examples.showcase.en-US.md

@@ -0,0 +1,38 @@
+## Showcase
+
+### Basic Counter
+
+This example is rendered from a real Vue SFC under `src/examples/manual/code-examples/BasicCounter.vue`.
+
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter">
+Use the source button to inspect the SFC sections, or open the compatible demo in CodePen.
+</d-block-code-example>
+
+### Expanded Source by Default
+
+Use `expanded="true"` when the source code is part of the lesson and should be visible as soon as the reader reaches the example.
+
+<d-block-code-example src="manual/code-examples/inline-notice" title="Expanded source example" expanded="true">
+This example intentionally starts with the source panel open.
+</d-block-code-example>
+
+## Authoring Syntax
+
+```html
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter">
+Optional caption rendered as inline Markdown.
+</d-block-code-example>
+
+<d-block-code-example src="manual/code-examples/inline-notice" title="Expanded source example" expanded="true">
+The source panel starts open.
+</d-block-code-example>
+```
+
+## Features Visible Above
+
+- **Live preview** rendered from the bundled Vue component
+- **Source toggle** with Template, Script, Style, and All tabs
+- **CodePen action** for compatible examples
+- **GitHub action** pointing to the example SFC
+- **Expanded source state** with `expanded="true"`
+- **Inline Markdown caption** below the preview

package/src/pages/manual/content/blocks/code-examples.showcase.pt-BR.md

@@ -0,0 +1,38 @@
+## Showcase
+
+### Contador básico
+
+Este exemplo é renderizado a partir de um SFC Vue real em `src/examples/manual/code-examples/BasicCounter.vue`.
+
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter">
+Use o botão de fonte para inspecionar as seções do SFC, ou abra a demo compatível no CodePen.
+</d-block-code-example>
+
+### Fonte expandida por padrão
+
+Use `expanded="true"` quando o código fonte faz parte da explicação e deve aparecer assim que o leitor chegar ao exemplo.
+
+<d-block-code-example src="manual/code-examples/inline-notice" title="Expanded source example" expanded="true">
+Este exemplo intencionalmente começa com o painel de fonte aberto.
+</d-block-code-example>
+
+## Sintaxe de autoria
+
+```html
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter">
+Legenda opcional renderizada como Markdown inline.
+</d-block-code-example>
+
+<d-block-code-example src="manual/code-examples/inline-notice" title="Expanded source example" expanded="true">
+O painel de fonte começa aberto.
+</d-block-code-example>
+```
+
+## Recursos visíveis acima
+
+- **Preview ao vivo** renderizado a partir do componente Vue empacotado
+- **Alternância de fonte** com abas Template, Script, Style e All
+- **Ação do CodePen** para exemplos compatíveis
+- **Ação do GitHub** apontando para o SFC do exemplo
+- **Estado de fonte expandida** com `expanded="true"`
+- **Legenda em Markdown inline** abaixo do preview

package/src/pages/manual.index.js

@@ -514,6 +514,34 @@ export default {
     }
   },
 
+  '/content/blocks/code-examples': {
+    config: {
+      icon: 'integration_instructions',
+      status: 'new',
+      meta: {
+        description: {
+          'en-US': 'Code examples — Documentation of Docsector Reader',
+          'pt-BR': 'Exemplos de código — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'manual',
+      menu: {},
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'Code examples' },
+      'pt-BR': { title: 'Exemplos de código' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'code examples live preview vue sfc source codepen component demo',
+        'pt-BR': 'exemplos código preview ao vivo vue sfc fonte codepen componente demo'
+      }
+    }
+  },
+
   '/content/blocks/mermaid-diagrams': {
     config: {
       icon: 'account_tree',

package/src/quasar.factory.js

@@ -1144,6 +1144,82 @@ function createBooksPlugin (projectRoot) {
   }
 }
 
+function buildVirtualCodeExamplesModule () {
+  return `const componentModules = import.meta.glob('/src/examples/**/*.vue')
+const sourceModules = import.meta.glob('/src/examples/**/*.vue', { query: '?raw', import: 'default' })
+
+const trimSlashes = (value) => String(value || '').replace(/\\\\/g, '/').replace(/^\\/+|\\/+$/g, '')
+const toKebabSegment = (value) => String(value || '')
+  .replace(/\\.vue$/i, '')
+  .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+  .replace(/[\\s_]+/g, '-')
+  .replace(/-+/g, '-')
+  .toLowerCase()
+
+export const normalizeCodeExampleId = (value) => trimSlashes(value)
+  .replace(/^src\\/examples\\//i, '')
+  .replace(/^examples\\//i, '')
+  .replace(/\\.vue$/i, '')
+  .split('/')
+  .filter(Boolean)
+  .map(toKebabSegment)
+  .join('/')
+
+export const codeExamples = Object.keys(componentModules).reduce((examples, filePath) => {
+  const id = normalizeCodeExampleId(filePath)
+
+  examples[id] = {
+    id,
+    filePath,
+    loadComponent: componentModules[filePath],
+    loadSource: sourceModules[filePath]
+  }
+
+  return examples
+}, {})
+
+export const codeExampleIds = Object.keys(codeExamples).sort()
+
+export const resolveCodeExample = (value) => {
+  const id = normalizeCodeExampleId(value)
+  const entry = codeExamples[id]
+
+  if (!entry) {
+    return {
+      id,
+      filePath: '',
+      exists: false,
+      loadComponent: null,
+      loadSource: null
+    }
+  }
+
+  return {
+    ...entry,
+    exists: true
+  }
+}
+
+export default codeExamples
+`
+}
+
+function createCodeExamplesPlugin () {
+  const virtualId = 'virtual:docsector-code-examples'
+  const resolvedId = '\0' + virtualId
+
+  return {
+    name: 'docsector-code-examples',
+    resolveId (id) {
+      if (id === virtualId) return resolvedId
+    },
+    load (id) {
+      if (id !== resolvedId) return null
+      return buildVirtualCodeExamplesModule()
+    }
+  }
+}
+
 /**
  * Create the HJSON Vite plugin for loading .hjson files as ES modules.
  */
@@ -1504,7 +1580,7 @@ async function fetchRemoteMarkdown (url, timeoutMs = 8000) {
   }
 }
 
-async function resolveHomePageSources (projectRoot, config = {}, options = {}) {
+export async function resolveHomePageSources (projectRoot, config = {}, options = {}) {
   const { logPrefix = '[docsector]' } = options
   const pagesDir = resolve(projectRoot, 'src', 'pages')
   const { defaultLang, langs } = getConfiguredLanguages(config)
@@ -1551,18 +1627,17 @@ async function resolveHomePageSources (projectRoot, config = {}, options = {}) {
 function createHomePageOverridePlugin (projectRoot) {
   const virtualId = 'virtual:docsector-homepage-override'
   const resolvedId = '\0' + virtualId
-  let byLang = null
+  let homePageSources = null
   let loadPromise = null
 
   const ensureSources = async () => {
-    if (byLang) return byLang
+    if (homePageSources) return homePageSources
     if (!loadPromise) {
       loadPromise = (async () => {
         const configUrl = pathToFileURL(resolve(projectRoot, 'docsector.config.js')).href
         const { default: config } = await import(configUrl)
-        const sources = await resolveHomePageSources(projectRoot, config, { logPrefix: '[docsector]' })
-        byLang = sources.byLang
-        return byLang
+        homePageSources = await resolveHomePageSources(projectRoot, config, { logPrefix: '[docsector]' })
+        return homePageSources
       })().finally(() => {
         loadPromise = null
       })
@@ -1586,18 +1661,21 @@ function createHomePageOverridePlugin (projectRoot) {
     },
     async load (id) {
       if (id === resolvedId) {
-        await ensureSources()
-        return `export default ${JSON.stringify(byLang || {})}`
+        const sources = await ensureSources()
+        return [
+          `export const homePageSourceMode = ${JSON.stringify(sources?.mode || 'local')}`,
+          `export default ${JSON.stringify(sources?.byLang || {})}`
+        ].join('\n')
       }
 
-      await ensureSources()
-      if (!byLang) return null
+      const sources = await ensureSources()
+      if (!sources?.byLang) return null
 
       const match = id.match(/Homepage\.([A-Za-z0-9-]+)\.md\?raw(?:$|&)/)
       if (!match) return null
 
       const lang = match[1]
-      const content = byLang[lang]
+      const content = sources.byLang[lang]
       if (typeof content !== 'string') return null
 
       return `export default ${JSON.stringify(content)}`
@@ -2917,6 +2995,7 @@ export function createQuasarConfig (options = {}) {
 
       vitePlugins: [
         createBooksPlugin(projectRoot),
+        createCodeExamplesPlugin(),
         createHjsonPlugin(),
         createHomePageOverridePlugin(projectRoot),
         createGitDatesPlugin(projectRoot),

package/src/store/Page.js

@@ -1,3 +1,23 @@
+const getNodePath = (nodes, targetId, ancestry = []) => {
+  for (const node of nodes) {
+    const nextAncestry = [...ancestry, node.id]
+
+    if (node.id === targetId) {
+      return nextAncestry
+    }
+
+    if (Array.isArray(node.children) && node.children.length > 0) {
+      const childPath = getNodePath(node.children, targetId, nextAncestry)
+
+      if (childPath !== null) {
+        return childPath
+      }
+    }
+  }
+
+  return null
+}
+
 export default {
   namespaced: true,
 
@@ -46,7 +66,7 @@ export default {
     pushAnchors (state, value) {
       if (value === false) {
         state.anchors = []
-      } else {
+      } else if (!state.anchors.includes(value)) {
         // index: id
         state.anchors.push(value)
       }
@@ -82,7 +102,13 @@ export default {
       state.nodesExpanded = [0]
     },
     pushNodesExpanded (state, nodeId) {
-      state.nodesExpanded.push(nodeId)
+      const nodePath = getNodePath(state.nodes, nodeId) || [nodeId]
+
+      for (const pathNodeId of nodePath) {
+        if (!state.nodesExpanded.includes(pathNodeId)) {
+          state.nodesExpanded.push(pathNodeId)
+        }
+      }
     },
 
     setScrolling (state, val) {