@docsector/docsector-reader 2.3.0 → 3.1.0

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

@@ -94,6 +94,22 @@ echo "Exemplo"
 
 `filename` aparece na barra de info em blocos simples. Fences consecutivos com o mesmo `group` são renderizados como abas. `tab` define o rótulo da aba, então labels que parecem arquivo, como `exemplo.php`, recebem ícones na aba. `breadcrumb` define os segmentos acima do bloco ativo, e o segmento final que parece arquivo recebe o mesmo ícone.
 
+### Conteúdo Expansível
+
+Use `<d-expandable>` para esconder conteúdo secundário sem perder os recursos ricos de Markdown da página:
+
+```markdown
+<d-expandable title="Mais detalhes">
+
+Explicações opcionais, notas operacionais ou exemplos maiores.
+
+</d-expandable>
+```
+
+Defina `open="true"` quando o bloco precisar começar aberto.
+
+O corpo do expansível suporta parágrafos, listas, alertas, blocos de código, diagramas Mermaid, tabelas, HTML bruto e quick links. Nesta primeira versão, mantenha títulos fora do bloco expansível, porque títulos dentro do corpo viram parágrafos comuns para preservar o ToC da página.
+
 ## Adicionando um Novo Idioma
 
 1. Crie `src/i18n/languages/xx-XX.hjson` com todas as traduções de UI

package/src/pages/guide.index.js

@@ -23,6 +23,12 @@ export default {
     data: {
       'en-US': { title: 'Getting Started' },
       'pt-BR': { title: 'Começando' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'install setup start begin quick project structure',
+        'pt-BR': 'instalar configurar iniciar começar rápido projeto estrutura'
+      }
     }
   },
 
@@ -48,6 +54,12 @@ export default {
     data: {
       'en-US': { title: 'Configuration' },
       'pt-BR': { title: 'Configuração' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'config branding logo name version language links github docsector.config.js',
+        'pt-BR': 'config branding logo nome versão idioma links github docsector.config.js'
+      }
     }
   },
 
@@ -71,6 +83,12 @@ export default {
     data: {
       'en-US': { title: 'Pages & Routing' },
       'pt-BR': { title: 'Páginas & Rotas' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'pages routes routing registry menu navigation path type status subpages',
+        'pt-BR': 'páginas rotas roteamento registro menu navegação caminho tipo status subpages'
+      }
     }
   },
 
@@ -93,6 +111,12 @@ export default {
     data: {
       'en-US': { title: 'i18n & Markdown' },
       'pt-BR': { title: 'i18n & Markdown' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'i18n internationalization language locale hjson markdown content translation',
+        'pt-BR': 'i18n internacionalização idioma locale hjson markdown conteúdo tradução'
+      }
     }
   },
 
@@ -115,6 +139,12 @@ export default {
     data: {
       'en-US': { title: 'Alerts & Blockquotes' },
       'pt-BR': { title: 'Alertas & Blockquotes' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'alerts blockquotes github note tip important warning caution markdown quote admonition',
+        'pt-BR': 'alertas blockquotes github note tip important warning caution markdown citação admonition'
+      }
     }
   },
 
@@ -137,6 +167,12 @@ export default {
     data: {
       'en-US': { title: 'Theming' },
       'pt-BR': { title: 'Temas' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'theme dark light mode color css sass variables styling',
+        'pt-BR': 'tema escuro claro modo cor css sass variáveis estilização'
+      }
     }
   },
 
@@ -159,6 +195,12 @@ export default {
     data: {
       'en-US': { title: 'Deployment' },
       'pt-BR': { title: 'Deploy' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'deploy hosting production build static nginx netlify vercel github pages',
+        'pt-BR': 'deploy hospedagem produção build estático nginx netlify vercel github pages'
+      }
     }
   },
 
@@ -181,6 +223,12 @@ export default {
     data: {
       'en-US': { title: 'Plugins' },
       'pt-BR': { title: 'Plugins' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'plugins extensions addons customize',
+        'pt-BR': 'plugins extensões complementos customizar'
+      }
     }
   }
 }

package/src/pages/manual/components/d-menu.overview.en-US.md

@@ -14,7 +14,7 @@
 
 The search input at the top of the menu filters pages by matching the search term against:
 
-1. **Tags** — Defined in `src/i18n/tags.hjson`
+1. **Tags** — Defined per page in `src/pages/*.index.js` under `metadata.tags`
 2. **Page content** — The Markdown source of each page's overview, showcase, and vs subpages
 
 Search is debounced by 300ms and supports the current locale with en-US fallback.

package/src/pages/manual/components/d-menu.overview.pt-BR.md

@@ -14,7 +14,7 @@
 
 O input de busca no topo do menu filtra páginas comparando o termo de busca com:
 
-1. **Tags** — Definidas em `src/i18n/tags.hjson`
+1. **Tags** — Definidas por página em `src/pages/*.index.js` em `metadata.tags`
 2. **Conteúdo da página** — O source Markdown de cada sub-página overview, showcase e vs
 
 A busca tem debounce de 300ms e suporta o locale atual com fallback para en-US.

package/src/pages/manual/components/d-page-expandable.overview.en-US.md

@@ -0,0 +1,58 @@
+## Overview
+
+`DPageExpandable` renders a collapsible content section backed by the Markdown custom element `<d-expandable>`.
+
+It is designed for secondary content that should stay available without stretching the main reading flow. The body keeps the same rich Markdown features already available in page sections, including lists, blockquotes, code blocks, Mermaid diagrams, tables, raw HTML, and quick links.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `String` | `''` | Header label shown in the expandable trigger |
+| `open` | `Boolean` | `false` | Initial expanded state |
+
+## Slot
+
+The default slot receives the parsed content body.
+
+## HTML Example
+
+The custom element can be authored directly in page Markdown:
+
+````html
+<d-expandable title="Why hide this content?">
+
+Use expandable blocks when the main section should stay concise but readers may still need more detail.
+
+</d-expandable>
+
+### Open by Default
+
+<d-expandable title="Release checklist" open="true">
+
+- Review breaking changes
+- Update screenshots
+- Run smoke tests
+
+</d-expandable>
+
+### Rich Content
+
+<d-expandable title="Deployment appendix">
+
+> [!TIP]
+> Keep the primary flow in the main section and move optional details here.
+
+```bash
+npm install
+npm run build
+```
+
+</d-expandable>
+````
+
+## Notes
+
+- Use `open="true"` when the section should start expanded.
+- Keep page headings outside the expandable block. Headings inside the body are flattened to regular paragraphs so the page ToC stays stable.
+- Avoid nesting one `<d-expandable>` inside another in this first version.

package/src/pages/manual/components/d-page-expandable.overview.pt-BR.md

@@ -0,0 +1,58 @@
+## Visão Geral
+
+`DPageExpandable` renderiza uma seção recolhível baseada no elemento customizado de Markdown `<d-expandable>`.
+
+Ele foi criado para conteúdo secundário que deve continuar disponível sem alongar o fluxo principal de leitura. O corpo mantém os mesmos recursos ricos de Markdown já usados nas seções da página, incluindo listas, blockquotes, blocos de código, diagramas Mermaid, tabelas, HTML bruto e quick links.
+
+## Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `title` | `String` | `''` | Rótulo do cabeçalho exibido no gatilho do expansível |
+| `open` | `Boolean` | `false` | Estado inicial expandido |
+
+## Slot
+
+O slot padrão recebe o corpo de conteúdo já parseado.
+
+## Exemplo em HTML
+
+O custom element pode ser escrito diretamente no Markdown da página:
+
+````html
+<d-expandable title="Por que esconder este conteúdo?">
+
+Use blocos expansíveis quando a seção principal deve continuar concisa, mas o leitor ainda pode precisar de mais detalhes.
+
+</d-expandable>
+
+### Aberto por Padrão
+
+<d-expandable title="Checklist de release" open="true">
+
+- Revisar breaking changes
+- Atualizar screenshots
+- Rodar smoke tests
+
+</d-expandable>
+
+### Conteúdo Rico
+
+<d-expandable title="Apêndice de deploy">
+
+> [!TIP]
+> Mantenha o fluxo principal na seção principal e mova detalhes opcionais para cá.
+
+```bash
+npm install
+npm run build
+```
+
+</d-expandable>
+````
+
+## Observações
+
+- Use `open="true"` quando a seção precisar começar aberta.
+- Mantenha os títulos principais fora do bloco expansível. Títulos dentro do corpo viram parágrafos comuns para manter o ToC estável.
+- Evite aninhar um `<d-expandable>` dentro de outro nesta primeira versão.

package/src/pages/manual/components/d-page-expandable.showcase.en-US.md

@@ -0,0 +1,33 @@
+## Showcase
+
+### Basic
+
+<d-expandable title="Why hide this content?">
+
+Use expandable blocks when the main section should stay concise but readers may still need more detail.
+
+</d-expandable>
+
+### Open by Default
+
+<d-expandable title="Release checklist" open="true">
+
+- Review breaking changes
+- Update screenshots
+- Run smoke tests
+
+</d-expandable>
+
+### Rich Content
+
+<d-expandable title="Deployment appendix">
+
+> [!TIP]
+> Keep the primary flow in the main section and move optional details here.
+
+```bash
+npm install
+npm run build
+```
+
+</d-expandable>

package/src/pages/manual/components/d-page-expandable.showcase.pt-BR.md

@@ -0,0 +1,33 @@
+## Demonstração
+
+### Básico
+
+<d-expandable title="Por que esconder este conteúdo?">
+
+Use blocos expansíveis quando a seção principal deve continuar concisa, mas o leitor ainda pode precisar de mais detalhes.
+
+</d-expandable>
+
+### Aberto por Padrão
+
+<d-expandable title="Checklist de release" open="true">
+
+- Revisar breaking changes
+- Atualizar screenshots
+- Rodar smoke tests
+
+</d-expandable>
+
+### Conteúdo Rico
+
+<d-expandable title="Apêndice de deploy">
+
+> [!TIP]
+> Mantenha o fluxo principal na seção principal e mova detalhes opcionais para cá.
+
+```bash
+npm install
+npm run build
+```
+
+</d-expandable>

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

@@ -9,6 +9,7 @@ Every documentation page is rendered inside a `DPage` instance.
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `disableNav` | `Boolean` | `false` | Hides the DPageMeta navigation footer |
+| `showBackToTopControl` | `Boolean` | `false` | Enables the floating back-to-top control with circular reading progress |
 
 ## Template Structure
 
@@ -46,6 +47,8 @@ DPage reads the route's `meta.subpages` configuration to determine which tabs to
 
 DPage resets the scroll position on route changes via `router.beforeEach`. The scroll observer monitors vertical scroll position and updates the anchor selection via the `useNavigator` composable.
 
+When `showBackToTopControl` is enabled, DPage also derives reading progress from the same scroll container. The floating control stays hidden at the top, appears after a small amount of scroll, shows circular progress, and returns to anchor `0` when clicked.
+
 ## Store Integration
 
 DPage reads from and writes to several Vuex store modules:

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

@@ -9,6 +9,7 @@ Toda página de documentação é renderizada dentro de uma instância de `DPage
 | Prop | Tipo | Padrão | Descrição |
 |------|------|--------|-----------|
 | `disableNav` | `Boolean` | `false` | Oculta o rodapé de navegação DPageMeta |
+| `showBackToTopControl` | `Boolean` | `false` | Habilita o controle flutuante de voltar ao topo com progresso circular de leitura |
 
 ## Estrutura do Template
 
@@ -46,6 +47,8 @@ DPage lê a configuração `meta.subpages` da rota para determinar quais abas ex
 
 DPage reseta a posição de scroll nas mudanças de rota via `router.beforeEach`. O observador de scroll monitora a posição vertical e atualiza a seleção de âncora via composable `useNavigator`.
 
+Quando `showBackToTopControl` está habilitada, DPage também deriva o progresso de leitura a partir da mesma área de scroll. O controle flutuante fica oculto no topo, aparece após uma pequena rolagem, exibe progresso circular e retorna para a âncora `0` ao ser clicado.
+
 ## Integração com Store
 
 DPage lê e escreve em vários módulos da Vuex store:

package/src/pages/manual/components/d-subpage.overview.en-US.md

@@ -9,7 +9,7 @@ DSubpage generates a deterministic numeric ID from the current route path using
 ## Template
 
 ```html
-<d-page>
+<d-page show-back-to-top-control>
   <header>
     <d-h1 :id="0" />
   </header>
@@ -54,3 +54,7 @@ DSubpage is automatically used by the router for all documentation pages. You do
 - `DSubpage` **uses** `DPage` as its container
 - `DPage` handles layout (scroll, toolbar, drawer)
 - `DSubpage` handles content composition (H1 + sections)
+
+## Built-in Back to Top Control
+
+Routed documentation subpages enable DPage's floating back-to-top control automatically. The control is only shown when the content actually overflows, becomes visible after the reader scrolls a little, and visualizes the current reading progress with a circular indicator.

package/src/pages/manual/components/d-subpage.overview.pt-BR.md

@@ -9,7 +9,7 @@ DSubpage gera um ID numérico determinístico a partir do caminho da rota atual
 ## Template
 
 ```html
-<d-page>
+<d-page show-back-to-top-control>
   <header>
     <d-h1 :id="0" />
   </header>
@@ -54,3 +54,7 @@ DSubpage é usado automaticamente pelo roteador para todas as páginas de docume
 - `DSubpage` **usa** `DPage` como container
 - `DPage` cuida do layout (scroll, toolbar, drawer)
 - `DSubpage` cuida da composição de conteúdo (H1 + seções)
+
+## Controle Integrado de Voltar ao Topo
+
+As sub-páginas de documentação roteadas habilitam automaticamente o controle flutuante de voltar ao topo do DPage. O controle só é exibido quando o conteúdo realmente tem overflow, fica visível após uma pequena rolagem do leitor e mostra o progresso atual de leitura com um indicador circular.

package/src/pages/manual.index.js

@@ -35,6 +35,12 @@ export default {
     data: {
       'en-US': { title: 'DPage' },
       'pt-BR': { title: 'DPage' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'page container scroll toolbar drawer layout subpage tabs',
+        'pt-BR': 'página container scroll toolbar drawer layout subpágina abas'
+      }
     }
   },
 
@@ -57,6 +63,12 @@ export default {
     data: {
       'en-US': { title: 'DSubpage' },
       'pt-BR': { title: 'DSubpage' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'subpage wrapper composition dh1 section hash',
+        'pt-BR': 'subpágina wrapper composição dh1 seção hash'
+      }
     }
   },
 
@@ -81,6 +93,12 @@ export default {
     data: {
       'en-US': { title: 'DPageSection' },
       'pt-BR': { title: 'DPageSection' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'section markdown renderer tokenizer parser heading paragraph list table code',
+        'pt-BR': 'seção markdown renderizador tokenizador parser título parágrafo lista tabela código'
+      }
     }
   },
 
@@ -106,6 +124,12 @@ export default {
     data: {
       'en-US': { title: 'DH1 – DH6 (Headings)' },
       'pt-BR': { title: 'DH1 – DH6 (Títulos)' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'h1 h2 h3 h4 h5 h6 heading title anchor navigation toc',
+        'pt-BR': 'h1 h2 h3 h4 h5 h6 título heading âncora navegação toc'
+      }
     }
   },
 
@@ -128,6 +152,12 @@ export default {
     data: {
       'en-US': { title: 'DPageSourceCode' },
       'pt-BR': { title: 'DPageSourceCode' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'code syntax highlight prism php bash html copy clipboard line numbers',
+        'pt-BR': 'código sintaxe highlight prism php bash html copiar clipboard números linha'
+      }
     }
   },
 
@@ -174,6 +204,42 @@ export default {
     data: {
       'en-US': { title: 'DPageBlockquote' },
       'pt-BR': { title: 'DPageBlockquote' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'blockquote important warning note quote',
+        'pt-BR': 'blockquote importante aviso nota citação'
+      }
+    }
+  },
+
+  '/components/d-page-expandable': {
+    config: {
+      icon: 'unfold_more',
+      status: 'done',
+      meta: {
+        description: {
+          'en-US': 'DPageExpandable — Documentation of Docsector Reader',
+          'pt-BR': 'DPageExpandable — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'manual',
+      menu: {
+        separator: ' page'
+      },
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'DPageExpandable' },
+      'pt-BR': { title: 'DPageExpandable' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'expandable collapsible accordion disclosure details markdown toggle',
+        'pt-BR': 'expansível colapsável acordeão detalhes markdown alternância'
+      }
     }
   },
 
@@ -200,6 +266,12 @@ export default {
     data: {
       'en-US': { title: 'DMenu' },
       'pt-BR': { title: 'DMenu' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'menu sidebar navigation search branding links tree expansion',
+        'pt-BR': 'menu lateral navegação busca branding links árvore expansão'
+      }
     }
   },
 
@@ -222,6 +294,12 @@ export default {
     data: {
       'en-US': { title: 'DPageAnchor' },
       'pt-BR': { title: 'DPageAnchor' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'anchor toc table contents tree drawer navigation scroll',
+        'pt-BR': 'âncora toc índice conteúdo árvore drawer navegação scroll'
+      }
     }
   },
 
@@ -244,6 +322,12 @@ export default {
     data: {
       'en-US': { title: 'DPageMeta' },
       'pt-BR': { title: 'DPageMeta' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'meta footer edit github translation progress prev next navigation',
+        'pt-BR': 'meta rodapé editar github tradução progresso anterior próximo navegação'
+      }
     }
   },
 
@@ -271,6 +355,12 @@ export default {
     data: {
       'en-US': { title: 'QZoom' },
       'pt-BR': { title: 'QZoom' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'zoom overlay fullscreen scale mouse wheel escape',
+        'pt-BR': 'zoom overlay tela cheia escala roda mouse escape'
+      }
     }
   },
 
@@ -304,6 +394,12 @@ export default {
     data: {
       'en-US': { title: 'useNavigator' },
       'pt-BR': { title: 'useNavigator' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'navigator composable anchor scroll register navigate toc',
+        'pt-BR': 'navegador composable âncora scroll registro navegar toc'
+      }
     }
   },
 
@@ -337,6 +433,12 @@ export default {
     data: {
       'en-US': { title: 'Vuex Modules' },
       'pt-BR': { title: 'Módulos Vuex' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'vuex store state mutations getters actions app i18n page layout settings',
+        'pt-BR': 'vuex store estado mutations getters actions app i18n page layout settings'
+      }
     }
   }
 }