@docsector/docsector-reader 4.0.1 → 4.1.0

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.
  */
@@ -2919,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,
 
@@ -82,8 +102,12 @@ export default {
       state.nodesExpanded = [0]
     },
     pushNodesExpanded (state, nodeId) {
-      if (!state.nodesExpanded.includes(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)
+        }
       }
     },