@docsector/docsector-reader 3.2.0 → 3.2.2

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.