@docsector/docsector-reader 3.1.0 → 3.2.1

package/src/pages/manual/content/blocks/unordered-lists.overview.pt-BR.md

@@ -0,0 +1,21 @@
+## Visão Geral
+
+Use listas não ordenadas quando a sequência dos itens não importa.
+
+Elas funcionam bem para conjuntos de recursos, requisitos, notas agrupadas e coleções curtas de pontos relacionados.
+
+## Sintaxe em Markdown
+
+```markdown
+- Primeiro item
+- Segundo item
+  - Item aninhado
+  - Outro item aninhado
+- Terceiro item
+```
+
+## Observações
+
+- `-`, `*` e `+` são marcadores válidos.
+- Indente itens aninhados para criar sublistas.
+- Use listas não ordenadas para coleções, não para procedimentos passo a passo.

package/src/pages/manual/content/blocks/unordered-lists.showcase.en-US.md

@@ -0,0 +1,24 @@
+## Showcase
+
+### Simple Bullets
+
+- Install dependencies
+- Start the development server
+- Open the project in the browser
+
+### Nested Bullets
+
+- Documentation workflow
+  - Write the overview page
+  - Add the showcase page
+  - Review links and wording
+- Release workflow
+  - Run tests
+  - Build the site
+  - Publish the update
+
+### Mixed Content
+
+- **Important:** keep each item focused on one action.
+- `npm run build` works well as a literal command inside a list.
+- Lists are useful when order does not matter as much as scanability.

package/src/pages/manual/content/blocks/unordered-lists.showcase.pt-BR.md

@@ -0,0 +1,24 @@
+## Demonstração
+
+### Marcadores Simples
+
+- Instale as dependências
+- Inicie o servidor de desenvolvimento
+- Abra o projeto no navegador
+
+### Marcadores Aninhados
+
+- Fluxo de documentação
+  - Escreva a página de overview
+  - Adicione a página de showcase
+  - Revise links e texto
+- Fluxo de release
+  - Rode os testes
+  - Gere o build do site
+  - Publique a atualização
+
+### Conteúdo Misto
+
+- **Importante:** mantenha cada item focado em uma ação.
+- `npm run build` funciona bem como comando literal dentro de uma lista.
+- Listas são úteis quando a ordem importa menos do que a facilidade de leitura.

package/src/pages/manual/content/structures/books.overview.en-US.md

@@ -0,0 +1,36 @@
+## Overview
+
+Books define the top-level documentation sections that appear as primary tabs, such as Manual and Guide.
+
+A book is configured in a `*.book.js` file. It is not a Vue component and it does not render page content by itself.
+
+## Example
+
+```javascript
+import { defineBook } from '../index.js'
+
+export default defineBook({
+  id: 'manual',
+  label: 'Manual',
+  icon: 'menu_book',
+  order: 1,
+  color: {
+    active: 'white',
+    inactive: 'white'
+  }
+})
+```
+
+## What a Book Controls
+
+- The tab label shown in the main navigation
+- The icon used for that tab
+- The order of the top-level sections
+- Active and inactive tab colors
+- The stable id referenced by page registries
+
+## Notes
+
+- Use one `*.book.js` file per top-level section.
+- Page registries such as `manual.index.js` and `guide.index.js` attach entries to a book with the `book` field.
+- A book groups pages under a common tab and route prefix.

package/src/pages/manual/content/structures/books.overview.pt-BR.md

@@ -0,0 +1,36 @@
+## Visão Geral
+
+Books definem as seções principais da documentação exibidas como abas de primeiro nível, como Manual e Guide.
+
+Um book é configurado em um arquivo `*.book.js`. Ele não é um componente Vue e não renderiza conteúdo de página por conta própria.
+
+## Exemplo
+
+```javascript
+import { defineBook } from '../index.js'
+
+export default defineBook({
+  id: 'manual',
+  label: 'Manual',
+  icon: 'menu_book',
+  order: 1,
+  color: {
+    active: 'white',
+    inactive: 'white'
+  }
+})
+```
+
+## O Que um Book Controla
+
+- O rótulo da aba exibida na navegação principal
+- O ícone usado nessa aba
+- A ordem das seções de primeiro nível
+- As cores ativa e inativa da aba
+- O id estável referenciado pelos registries de páginas
+
+## Observações
+
+- Use um arquivo `*.book.js` para cada seção de primeiro nível.
+- Registries como `manual.index.js` e `guide.index.js` associam entradas a um book com o campo `book`.
+- Um book agrupa páginas sob a mesma aba e o mesmo prefixo de rota.

package/src/pages/manual/content/structures/page.overview.en-US.md

@@ -0,0 +1,61 @@
+## Overview
+
+Page is the main documentation screen container.
+
+It provides the scroll area, the subpage toolbar, the right-side table of contents drawer, and the footer navigation area. Under the hood, this is powered by `DPage`.
+
+This manual entry intentionally stays overview-only because the container behavior is easier to explain than to demonstrate in isolation.
+
+## Props
+
+| 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 |
+
+## Layout Structure
+
+A page provides the following layout pieces:
+
+- **QPageContainer** — Quasar page container
+- **QToolbar** (submenu) — Tab navigation: Overview, Showcase, Vs
+- **QPage** with **QScrollArea** — Scrollable content area with slot
+- **QDrawer** (right) — Anchor/ToC navigation tree
+
+## Content Slot
+
+The default slot receives the page content. In routed documentation, a Subpage typically places the title and rendered sections inside this slot:
+
+```html
+<d-page>
+  <header>
+    <d-h1 :id="0" />
+  </header>
+  <main>
+    <d-page-section :id="sectionId" />
+  </main>
+</d-page>
+```
+
+## Subpage Tabs
+
+The page container reads the route's `meta.subpages` configuration to determine which tabs to display:
+
+- **Overview** — Always shown when other tabs exist
+- **Showcase** — Shown when `subpages.showcase: true`
+- **Vs** — Shown when `subpages.vs: true`
+
+## Scroll Behavior
+
+The page container resets scroll position on route changes via `router.beforeEach`. The scroll observer monitors vertical position and updates the selected anchor via the `useNavigator` composable.
+
+When `showBackToTopControl` is enabled, the page 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
+
+The implementation reads from and writes to several Vuex store modules:
+
+- `layout/meta` — Controls the right-side anchor drawer visibility
+- `page/base` — Current page base path
+- `page/relative` — Current subpage path (`/overview`, `/showcase`, `/vs`)
+- `page/anchor` — Resets anchors on navigation

package/src/pages/manual/content/structures/page.overview.pt-BR.md

@@ -0,0 +1,61 @@
+## Visão Geral
+
+Page é o container principal da tela de documentação.
+
+Ele fornece a área de scroll, a barra de subpáginas, o drawer lateral de índice e a área de navegação do rodapé. Na implementação, isso é sustentado por `DPage`.
+
+Esta entrada do manual fica intencionalmente só com overview, porque o comportamento do container é mais fácil de explicar do que de demonstrar isoladamente.
+
+## Props
+
+| 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 Layout
+
+Uma page fornece as seguintes partes de layout:
+
+- **QPageContainer** — Container de página Quasar
+- **QToolbar** (submenu) — Navegação por abas: Overview, Showcase, Vs
+- **QPage** com **QScrollArea** — Área de conteúdo com scroll e slot
+- **QDrawer** (direita) — Árvore de navegação por âncoras/ToC
+
+## Slot de Conteúdo
+
+O slot padrão recebe o conteúdo da página. Na documentação roteada, uma subpage normalmente coloca o título e as seções renderizadas dentro desse slot:
+
+```html
+<d-page>
+  <header>
+    <d-h1 :id="0" />
+  </header>
+  <main>
+    <d-page-section :id="sectionId" />
+  </main>
+</d-page>
+```
+
+## Abas de Subpágina
+
+O container de page lê a configuração `meta.subpages` da rota para determinar quais abas exibir:
+
+- **Overview** — Sempre exibida quando outras abas existem
+- **Showcase** — Exibida quando `subpages.showcase: true`
+- **Vs** — Exibida quando `subpages.vs: true`
+
+## Comportamento de Scroll
+
+O container de page 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, a page 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
+
+A implementação lê e escreve em vários módulos da Vuex store:
+
+- `layout/meta` — Controla a visibilidade do drawer de âncoras
+- `page/base` — Caminho base da página atual
+- `page/relative` — Caminho da sub-página (`/overview`, `/showcase`, `/vs`)
+- `page/anchor` — Reseta âncoras na navegação

package/src/pages/manual/content/structures/subpage.overview.en-US.md

@@ -0,0 +1,62 @@
+## Overview
+
+Subpage is the standard routed documentation screen that composes a page container, the page title, and the rendered sections.
+
+Under the hood, routed documentation uses `DSubpage` for this composition.
+
+## How It Works
+
+The implementation generates a deterministic numeric ID from the current route path using a hash function. This ID is passed to `DPageSection` to keep per-page renderer indexes stable across page navigations.
+
+## Template
+
+```html
+<d-page show-back-to-top-control>
+  <header>
+    <d-h1 :id="0" />
+  </header>
+  <main>
+    <d-page-section :id="id" />
+  </main>
+</d-page>
+```
+
+## ID Generation
+
+The `id` computed property creates a consistent hash from the route path:
+
+```javascript
+const id = computed(() => &#123;
+  const path = route.path
+  let hash = 5381
+  for (let i = 0; i < path.length; i++) &#123;
+    hash = (hash * 33) ^ path.charCodeAt(i)
+  &#125;
+  return hash >>> 0
+&#125;)
+```
+
+This keeps per-page renderer state isolated when switching between pages. Markdown section headings themselves use GitHub-compatible slugs derived from the heading text, so README-style Table of Contents links keep working.
+
+## When to Use
+
+Subpage is automatically used by the router for standard documentation routes. You usually do not need to wire it manually unless creating a custom layout.
+
+```javascript
+// In routes.js - this happens automatically
+&#123;
+  path: 'overview',
+  component: () => import('components/DSubpage.vue'),
+  meta: &#123; status: config.status &#125;
+&#125;
+```
+
+## Relationship with Page
+
+- Subpage uses the Page container as its layout shell
+- Page handles scroll, toolbar, and drawer behavior
+- Subpage handles title and section composition
+
+## Built-in Back to Top Control
+
+Routed documentation subpages enable the 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/content/structures/subpage.overview.pt-BR.md

@@ -0,0 +1,62 @@
+## Visão Geral
+
+Subpage é a tela roteada padrão da documentação que compõe o container de page, o título da página e as seções renderizadas.
+
+Na implementação, a documentação roteada usa `DSubpage` para essa composição.
+
+## Como Funciona
+
+A implementação gera um ID numérico determinístico a partir do caminho da rota atual usando uma função hash. Esse ID é passado ao `DPageSection` para manter estáveis os índices internos do renderer em cada página.
+
+## Template
+
+```html
+<d-page show-back-to-top-control>
+  <header>
+    <d-h1 :id="0" />
+  </header>
+  <main>
+    <d-page-section :id="id" />
+  </main>
+</d-page>
+```
+
+## Geração de ID
+
+A propriedade computada `id` cria um hash consistente a partir do caminho da rota:
+
+```javascript
+const id = computed(() => &#123;
+  const path = route.path
+  let hash = 5381
+  for (let i = 0; i < path.length; i++) &#123;
+    hash = (hash * 33) ^ path.charCodeAt(i)
+  &#125;
+  return hash >>> 0
+&#125;)
+```
+
+Isso mantém o estado interno do renderer isolado ao navegar entre páginas. Os headings Markdown em si usam slugs compatíveis com GitHub derivados do texto do título, então links de Table of Contents no estilo README continuam funcionando.
+
+## Quando Usar
+
+Subpage é usada automaticamente pelo roteador nas rotas padrão de documentação. Você normalmente não precisa montá-la manualmente, a menos que esteja criando um layout customizado.
+
+```javascript
+// Em routes.js - isso acontece automaticamente
+&#123;
+  path: 'overview',
+  component: () => import('components/DSubpage.vue'),
+  meta: &#123; status: config.status &#125;
+&#125;
+```
+
+## Relação com Page
+
+- Subpage usa o container de page como casca de layout
+- Page cuida do comportamento de scroll, toolbar e drawer
+- Subpage cuida da composição de título e seções
+
+## Controle Integrado de Voltar ao Topo
+
+As subpáginas roteadas habilitam automaticamente o controle flutuante de voltar ao topo. 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.