@docsector/docsector-reader 0.1.0

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

@@ -0,0 +1,50 @@
+## Showcase
+
+Here are code blocks in different languages demonstrating the DPageSourceCode component:
+
+### PHP Example
+
+```php
+class HelloWorld
+{
+    public function greet(string $name): string
+    {
+        return "Hello, {$name}!";
+    }
+}
+
+$hello = new HelloWorld();
+echo $hello->greet('Docsector');
+```
+
+### Bash Example
+
+```bash
+#!/bin/bash
+echo "Installing Docsector Reader..."
+npm install
+npx quasar dev
+echo "Server running at http://localhost:8181"
+```
+
+### HTML Example
+
+```html
+<template>
+  <d-page>
+    <header>
+      <d-h1 :id="0" />
+    </header>
+    <main>
+      <d-page-section :id="id" />
+    </main>
+  </d-page>
+</template>
+```
+
+## Features Visible Above
+
+- **Line numbers** on the left side of multi-line blocks
+- **Language label** in the top-right corner
+- **Copy button** next to the language label
+- **Syntax highlighting** with language-specific coloring

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

@@ -0,0 +1,50 @@
+## Demonstração
+
+Aqui estão blocos de código em diferentes linguagens demonstrando o componente DPageSourceCode:
+
+### Exemplo PHP
+
+```php
+class HelloWorld
+{
+    public function greet(string $name): string
+    {
+        return "Olá, {$name}!";
+    }
+}
+
+$hello = new HelloWorld();
+echo $hello->greet('Docsector');
+```
+
+### Exemplo Bash
+
+```bash
+#!/bin/bash
+echo "Instalando Docsector Reader..."
+npm install
+npx quasar dev
+echo "Servidor rodando em http://localhost:8181"
+```
+
+### Exemplo HTML
+
+```html
+<template>
+  <d-page>
+    <header>
+      <d-h1 :id="0" />
+    </header>
+    <main>
+      <d-page-section :id="id" />
+    </main>
+  </d-page>
+</template>
+```
+
+## Funcionalidades Visíveis Acima
+
+- **Números de linha** no lado esquerdo de blocos multi-linha
+- **Label de linguagem** no canto superior direito
+- **Botão de cópia** ao lado do label de linguagem
+- **Syntax highlighting** com coloração específica por linguagem

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

@@ -0,0 +1,56 @@
+## Overview
+
+`DPage` is the **main page container** component. It provides the scroll area, submenu toolbar (Overview/Showcase/Vs tabs), the right-side anchor drawer, and the `DPageMeta` footer.
+
+Every documentation page is rendered inside a `DPage` instance.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `disableNav` | `Boolean` | `false` | Hides the DPageMeta navigation footer |
+
+## Template Structure
+
+DPage renders the following layout:
+
+- **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
+
+## Slot
+
+The default slot receives the page content. Typically, `DSubpage` places `DH1` and `DPageSection` inside this slot:
+
+```html
+<d-page>
+  <header>
+    <d-h1 :id="0" />
+  </header>
+  <main>
+    <d-page-section :id="sectionId" />
+  </main>
+</d-page>
+```
+
+## Subpage Tabs
+
+DPage 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
+
+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.
+
+## Store Integration
+
+DPage 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/components/d-page.overview.pt-BR.md

@@ -0,0 +1,56 @@
+## Visão Geral
+
+`DPage` é o componente **container principal de página**. Ele fornece a área de scroll, a barra de submenu (abas Overview/Showcase/Vs), o drawer lateral de âncoras e o rodapé `DPageMeta`.
+
+Toda página de documentação é renderizada dentro de uma instância de `DPage`.
+
+## Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `disableNav` | `Boolean` | `false` | Oculta o rodapé de navegação DPageMeta |
+
+## Estrutura do Template
+
+DPage renderiza o seguinte 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
+
+O slot padrão recebe o conteúdo da página. Normalmente, `DSubpage` coloca `DH1` e `DPageSection` dentro deste slot:
+
+```html
+<d-page>
+  <header>
+    <d-h1 :id="0" />
+  </header>
+  <main>
+    <d-page-section :id="sectionId" />
+  </main>
+</d-page>
+```
+
+## Abas de Sub-página
+
+DPage 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
+
+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`.
+
+## Integração com Store
+
+DPage 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/components/d-page.showcase.en-US.md

@@ -0,0 +1,35 @@
+## Showcase
+
+Here is an example of how DPage is used inside DSubpage:
+
+```html
+<template>
+  <d-page>
+    <header>
+      <d-h1 :id="0" />
+    </header>
+    <main>
+      <d-page-section :id="id" />
+    </main>
+  </d-page>
+</template>
+```
+
+The submenu toolbar automatically adapts to the page configuration. If only Overview is configured, the toolbar shows a single tab. When Showcase or Vs tabs are enabled, the toolbar expands with labeled buttons.
+
+## Mobile Behavior
+
+On mobile devices (`$q.screen.lt.md`), the submenu button labels are hidden, showing only icons. The right-side anchor drawer becomes an overlay that can be toggled with the tree icon button.
+
+## Custom Content Example
+
+You can also use DPage with `disableNav` to create standalone pages without the bottom navigation:
+
+```html
+<d-page :disable-nav="true">
+  <div class="text-center q-pa-lg">
+    <h2>Custom Page Content</h2>
+    <p>No bottom nav, no prev/next links.</p>
+  </div>
+</d-page>
+```

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

@@ -0,0 +1,35 @@
+## Demonstração
+
+Veja como DPage é usado dentro do DSubpage:
+
+```html
+<template>
+  <d-page>
+    <header>
+      <d-h1 :id="0" />
+    </header>
+    <main>
+      <d-page-section :id="id" />
+    </main>
+  </d-page>
+</template>
+```
+
+A barra de submenu se adapta automaticamente à configuração da página. Se apenas Overview estiver configurado, a barra mostra uma única aba. Quando as abas Showcase ou Vs estão habilitadas, a barra expande com botões rotulados.
+
+## Comportamento Mobile
+
+Em dispositivos móveis (`$q.screen.lt.md`), os labels dos botões do submenu ficam ocultos, mostrando apenas ícones. O drawer de âncoras à direita se torna um overlay que pode ser alternado com o botão de ícone de árvore.
+
+## Exemplo de Conteúdo Customizado
+
+Você também pode usar DPage com `disableNav` para criar páginas standalone sem navegação inferior:
+
+```html
+<d-page :disable-nav="true">
+  <div class="text-center q-pa-lg">
+    <h2>Conteúdo Customizado</h2>
+    <p>Sem nav inferior, sem links prev/next.</p>
+  </div>
+</d-page>
+```

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

@@ -0,0 +1,56 @@
+## Overview
+
+`DSubpage` is a **convenience wrapper** that composes `DPage`, `DH1`, and `DPageSection` into a standard documentation page layout. It is the component loaded by the router for every subpage route.
+
+## How It Works
+
+DSubpage generates a deterministic numeric ID from the current route path using a hash function. This ID is passed to `DPageSection` to ensure unique component keys across page navigations.
+
+## Template
+
+```html
+<d-page>
+  <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 ensures that each page generates a unique set of anchor IDs, preventing collisions when switching between pages.
+
+## When to Use
+
+DSubpage is automatically used by the router for all documentation pages. You don't need to use it directly unless creating custom page layouts. For standard documentation, the router handles everything:
+
+```javascript
+// In routes.js - this happens automatically
+&#123;
+  path: 'overview',
+  component: () => import('components/DSubpage.vue'),
+  meta: &#123; status: config.status &#125;
+&#125;
+```
+
+## Relationship with DPage
+
+- `DSubpage` **uses** `DPage` as its container
+- `DPage` handles layout (scroll, toolbar, drawer)
+- `DSubpage` handles content composition (H1 + sections)

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

@@ -0,0 +1,56 @@
+## Visão Geral
+
+`DSubpage` é um **wrapper de conveniência** que compõe `DPage`, `DH1` e `DPageSection` em um layout de página de documentação padrão. É o componente carregado pelo roteador para cada rota de sub-página.
+
+## Como Funciona
+
+DSubpage 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 garantir chaves de componente únicas entre navegações de página.
+
+## Template
+
+```html
+<d-page>
+  <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 garante que cada página gere um conjunto único de IDs de âncora, prevenindo colisões ao navegar entre páginas.
+
+## Quando Usar
+
+DSubpage é usado automaticamente pelo roteador para todas as páginas de documentação. Você não precisa usá-lo diretamente, a menos que crie layouts de página customizados. Para documentação padrão, o roteador cuida de tudo:
+
+```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 DPage
+
+- `DSubpage` **usa** `DPage` como container
+- `DPage` cuida do layout (scroll, toolbar, drawer)
+- `DSubpage` cuida da composição de conteúdo (H1 + seções)

package/src/pages/manual/components/q-zoom.overview.en-US.md

@@ -0,0 +1,71 @@
+## Overview
+
+`QZoom` is a **zoom overlay** component forked from `quasarframework/app-extension-qzoom` and ported from Vue 2 to Vue 3. It enables any content to be zoomed into a fullscreen overlay with optional scaling.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `backgroundColor` | `String` | `'white'` | Background color of the overlay |
+| `restoreOnScroll` | `Boolean` | `false` | Close zoom when user scrolls |
+| `manual` | `Boolean` | `false` | Disable automatic click-to-zoom |
+| `scale` | `Boolean` | `false` | Enable mouse wheel scaling |
+| `initialScale` | `Number` | `1.0` | Initial scale (0.05–10) |
+| `scaleText` | `Boolean` | `false` | Enable font-size scaling instead of transform |
+| `initialScaleText` | `Number` | `100` | Initial font-size percentage (50–500) |
+| `noCenter` | `Boolean` | `false` | Don't center content in overlay |
+| `noWheelScale` | `Boolean` | `false` | Disable mouse wheel scaling |
+| `noEscClose` | `Boolean` | `false` | Disable Escape key to close |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `before-zoom` | — | Emitted before zoom animation starts |
+| `zoomed` | — | Emitted after zoom animation completes |
+| `before-restore` | — | Emitted before restore animation starts |
+| `restored` | — | Emitted after restore animation completes |
+| `scale` | `Number` | Emitted when scale value changes |
+| `scale-text` | `Number` | Emitted when text scale value changes |
+
+## Slot
+
+The default slot receives a `zoomed` Boolean indicating the current zoom state:
+
+```html
+<q-zoom>
+  <template v-slot:default="&#123; zoomed &#125;">
+    <img src="diagram.png" :class="zoomed ? 'zoomed' : ''" />
+  </template>
+</q-zoom>
+```
+
+## How It Works
+
+1. By default, clicking toggles between normal and fullscreen
+2. An overlay is created with a smooth transition (500ms zoom in, 400ms restore)
+3. During zoom, body scroll is disabled (unless `restoreOnScroll` is true)
+4. Press **Escape** to close (unless `noEscClose` is true)
+
+## Scaling Modes
+
+Two mutually exclusive scaling modes:
+
+- **Transform scale** (`scale` prop) — Scales the entire content using CSS `transform: scale()`
+- **Font-size scale** (`scaleText` prop) — Adjusts the content's `font-size` percentage
+
+Mouse wheel scrolling adjusts the scale value when zoomed (unless `noWheelScale` is true).
+
+## Boot Registration
+
+QZoom is registered globally via `src/boot/QZoom.js`:
+
+```javascript
+app.component('QZoom', QZoom)
+```
+
+This makes `<q-zoom>` available in all templates without explicit imports.
+
+## Dependencies
+
+QZoom requires the `q-colorize-mixin` package for background color handling, and `QZoom.styl` for its CSS styles.

package/src/pages/manual/components/q-zoom.overview.pt-BR.md

@@ -0,0 +1,71 @@
+## Visão Geral
+
+`QZoom` é um componente de **overlay de zoom** forked de `quasarframework/app-extension-qzoom` e portado de Vue 2 para Vue 3. Ele permite que qualquer conteúdo seja ampliado em um overlay fullscreen com escala opcional.
+
+## Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `backgroundColor` | `String` | `'white'` | Cor de fundo do overlay |
+| `restoreOnScroll` | `Boolean` | `false` | Fecha zoom quando o usuário faz scroll |
+| `manual` | `Boolean` | `false` | Desabilita click-to-zoom automático |
+| `scale` | `Boolean` | `false` | Habilita escala com roda do mouse |
+| `initialScale` | `Number` | `1.0` | Escala inicial (0.05–10) |
+| `scaleText` | `Boolean` | `false` | Habilita escala de font-size ao invés de transform |
+| `initialScaleText` | `Number` | `100` | Porcentagem inicial de font-size (50–500) |
+| `noCenter` | `Boolean` | `false` | Não centraliza conteúdo no overlay |
+| `noWheelScale` | `Boolean` | `false` | Desabilita escala com roda do mouse |
+| `noEscClose` | `Boolean` | `false` | Desabilita tecla Escape para fechar |
+
+## Eventos
+
+| Evento | Payload | Descrição |
+|--------|---------|-----------|
+| `before-zoom` | — | Emitido antes da animação de zoom iniciar |
+| `zoomed` | — | Emitido após a animação de zoom completar |
+| `before-restore` | — | Emitido antes da animação de restaurar iniciar |
+| `restored` | — | Emitido após a animação de restaurar completar |
+| `scale` | `Number` | Emitido quando o valor de escala muda |
+| `scale-text` | `Number` | Emitido quando o valor de escala de texto muda |
+
+## Slot
+
+O slot padrão recebe um Boolean `zoomed` indicando o estado de zoom atual:
+
+```html
+<q-zoom>
+  <template v-slot:default="&#123; zoomed &#125;">
+    <img src="diagrama.png" :class="zoomed ? 'zoomed' : ''" />
+  </template>
+</q-zoom>
+```
+
+## Como Funciona
+
+1. Por padrão, clicar alterna entre normal e fullscreen
+2. Um overlay é criado com transição suave (500ms zoom in, 400ms restore)
+3. Durante o zoom, o scroll do body é desabilitado (a menos que `restoreOnScroll` seja true)
+4. Pressione **Escape** para fechar (a menos que `noEscClose` seja true)
+
+## Modos de Escala
+
+Dois modos de escala mutuamente exclusivos:
+
+- **Transform scale** (prop `scale`) — Escala todo o conteúdo usando CSS `transform: scale()`
+- **Font-size scale** (prop `scaleText`) — Ajusta a porcentagem de `font-size` do conteúdo
+
+Scroll com roda do mouse ajusta o valor de escala quando ampliado (a menos que `noWheelScale` seja true).
+
+## Registro via Boot
+
+QZoom é registrado globalmente via `src/boot/QZoom.js`:
+
+```javascript
+app.component('QZoom', QZoom)
+```
+
+Isso torna `<q-zoom>` disponível em todos os templates sem imports explícitos.
+
+## Dependências
+
+QZoom requer o pacote `q-colorize-mixin` para tratamento de cor de fundo, e `QZoom.styl` para seus estilos CSS.

package/src/pages/manual/composables/use-navigator.overview.en-US.md

@@ -0,0 +1,89 @@
+## Overview
+
+`useNavigator` is the **core composable** that manages anchor navigation, heading registration, scroll tracking, and ToC tree construction. It is used by DH1–DH6, DPage, and DPageAnchor.
+
+## Returned API
+
+```javascript
+const {
+  register,   // Register an anchor ID
+  index,       // Add a node to the ToC tree
+  select,      // Select an anchor
+  anchor,      // Scroll to an anchor
+  scrolling,   // Scroll event handler
+  navigate,    // Navigate to an anchor (URL + scroll)
+  selected     // Ref to currently selected anchor
+} = useNavigator()
+```
+
+## Functions
+
+### register(id)
+
+Registers an anchor ID in the `page/anchors` store array. Called by heading components on mount.
+
+```javascript
+onMounted(() => {
+  register(props.id)
+})
+```
+
+### index(id, child)
+
+Pushes a node into the `page/nodes` store to build the ToC tree. Called by DH2–DH6 after rendering.
+
+### select(id)
+
+Updates `page/anchor` state and expands the corresponding tree node.
+
+### anchor(id, toSelect)
+
+Scrolls the viewport to the DOM element with the given ID using Quasar's `scroll` utility. Optionally calls `select()` to highlight the node in the ToC tree.
+
+### scrolling(scroll)
+
+The scroll event handler attached to DPage's QScrollObserver. It iterates all registered anchors, finds the one closest to the current scroll position, and selects it. Only active when `page/scrolling` is `true`.
+
+### navigate(value, toAnchor)
+
+Full navigation function that:
+
+1. Updates the URL hash via `router.push()`
+2. Scrolls to the anchor element
+3. Handles desktop vs mobile timing differences
+
+## Usage Pattern
+
+Heading components use register + index:
+
+```javascript
+const { register, index, navigate, selected } = useNavigator()
+
+onMounted(() => {
+  register(props.id)
+  selected.value = props.value
+  index(props.id)
+})
+```
+
+DPage uses scrolling:
+
+```javascript
+const { scrolling, navigate } = useNavigator()
+// scrolling is passed to QScrollObserver
+```
+
+DPageAnchor uses navigate + anchor:
+
+```javascript
+const { navigate, anchor, selected } = useNavigator()
+// navigate is triggered by QTree selection
+```
+
+## Store Dependencies
+
+- `page/anchors` — Array of registered anchor IDs
+- `page/nodes` — ToC tree structure
+- `page/nodesExpanded` — Expanded tree nodes
+- `page/anchor` — Currently selected anchor
+- `page/scrolling` — Whether scroll tracking is active