@docsector/docsector-reader 0.1.0

package/src/pages/index.js

@@ -0,0 +1,385 @@
+/**
+ * Docsector Reader - Pages Registry
+ *
+ * Define your documentation pages here. Each entry maps a URL path
+ * to its configuration, data (titles per language), and optional metadata.
+ *
+ * config.type: determines the top-level route prefix (e.g., 'manual', 'guide', 'API')
+ * config.status: 'done' | 'draft' | 'empty'
+ * config.icon: Material Design icon name
+ * config.menu: menu display options (header, subheader, separator)
+ * config.subpages: { showcase: bool, vs: bool }
+ * data: per-language titles (use '*' for all languages)
+ * meta: per-language section/translation counts
+ *
+ * Set config to null for category nodes (non-navigable groupings).
+ */
+export default {
+  // =========================================================================
+  // Guides
+  // =========================================================================
+  '/getting-started': {
+    config: {
+      icon: 'flag',
+      status: 'done',
+      type: 'guide',
+      menu: {
+        header: {
+          icon: 'school',
+          label: 'Guides'
+        }
+      },
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Getting Started' },
+      'pt-BR': { title: 'Começando' }
+    }
+  },
+
+  '/configuration': {
+    config: {
+      icon: 'tune',
+      status: 'done',
+      type: 'guide',
+      menu: {
+        separator: ' page'
+      },
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Configuration' },
+      'pt-BR': { title: 'Configuração' }
+    }
+  },
+
+  '/pages-and-routing': {
+    config: {
+      icon: 'route',
+      status: 'done',
+      type: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Pages & Routing' },
+      'pt-BR': { title: 'Páginas & Rotas' }
+    }
+  },
+
+  '/i18n-and-markdown': {
+    config: {
+      icon: 'translate',
+      status: 'done',
+      type: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'i18n & Markdown' },
+      'pt-BR': { title: 'i18n & Markdown' }
+    }
+  },
+
+  '/theming': {
+    config: {
+      icon: 'palette',
+      status: 'done',
+      type: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Theming' },
+      'pt-BR': { title: 'Temas' }
+    }
+  },
+
+  '/deployment': {
+    config: {
+      icon: 'cloud_upload',
+      status: 'draft',
+      type: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Deployment' },
+      'pt-BR': { title: 'Deploy' }
+    }
+  },
+
+  '/plugins': {
+    config: {
+      icon: 'extension',
+      status: 'empty',
+      type: 'guide',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Plugins' },
+      'pt-BR': { title: 'Plugins' }
+    }
+  },
+
+  // =========================================================================
+  // Components — Layout
+  // =========================================================================
+  '/components': {
+    config: null,
+    data: {
+      'en-US': { title: 'Components' },
+      'pt-BR': { title: 'Componentes' }
+    }
+  },
+
+  '/components/d-page': {
+    config: {
+      icon: 'web',
+      status: 'done',
+      type: 'manual',
+      menu: {
+        header: {
+          icon: 'widgets',
+          label: 'Components'
+        },
+        subheader: '.components'
+      },
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'DPage' },
+      'pt-BR': { title: 'DPage' }
+    }
+  },
+
+  '/components/d-subpage': {
+    config: {
+      icon: 'layers',
+      status: 'done',
+      type: 'manual',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'DSubpage' },
+      'pt-BR': { title: 'DSubpage' }
+    }
+  },
+
+  '/components/d-page-section': {
+    config: {
+      icon: 'article',
+      status: 'done',
+      type: 'manual',
+      menu: {
+        separator: ' page'
+      },
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'DPageSection' },
+      'pt-BR': { title: 'DPageSection' }
+    }
+  },
+
+  // =========================================================================
+  // Components — Content
+  // =========================================================================
+  '/components/d-headings': {
+    config: {
+      icon: 'title',
+      status: 'done',
+      type: 'manual',
+      menu: {},
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'DH1 – DH6 (Headings)' },
+      'pt-BR': { title: 'DH1 – DH6 (Títulos)' }
+    }
+  },
+
+  '/components/d-page-source-code': {
+    config: {
+      icon: 'code',
+      status: 'done',
+      type: 'manual',
+      menu: {},
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'DPageSourceCode' },
+      'pt-BR': { title: 'DPageSourceCode' }
+    }
+  },
+
+  '/components/d-page-blockquote': {
+    config: {
+      icon: 'format_quote',
+      status: 'done',
+      type: 'manual',
+      menu: {
+        separator: ' page'
+      },
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'DPageBlockquote' },
+      'pt-BR': { title: 'DPageBlockquote' }
+    }
+  },
+
+  // =========================================================================
+  // Components — Navigation
+  // =========================================================================
+  '/components/d-menu': {
+    config: {
+      icon: 'menu_open',
+      status: 'done',
+      type: 'manual',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'DMenu' },
+      'pt-BR': { title: 'DMenu' }
+    }
+  },
+
+  '/components/d-page-anchor': {
+    config: {
+      icon: 'account_tree',
+      status: 'done',
+      type: 'manual',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'DPageAnchor' },
+      'pt-BR': { title: 'DPageAnchor' }
+    }
+  },
+
+  '/components/d-page-meta': {
+    config: {
+      icon: 'info',
+      status: 'done',
+      type: 'manual',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'DPageMeta' },
+      'pt-BR': { title: 'DPageMeta' }
+    }
+  },
+
+  // =========================================================================
+  // Components — Utility
+  // =========================================================================
+  '/components/q-zoom': {
+    config: {
+      icon: 'zoom_in',
+      status: 'done',
+      type: 'manual',
+      menu: {
+        separator: ' page'
+      },
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'QZoom' },
+      'pt-BR': { title: 'QZoom' }
+    }
+  },
+
+  // =========================================================================
+  // Composables
+  // =========================================================================
+  '/composables': {
+    config: null,
+    data: {
+      'en-US': { title: 'Composables' },
+      'pt-BR': { title: 'Composables' }
+    }
+  },
+
+  '/composables/use-navigator': {
+    config: {
+      icon: 'navigation',
+      status: 'done',
+      type: 'manual',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'useNavigator' },
+      'pt-BR': { title: 'useNavigator' }
+    }
+  },
+
+  // =========================================================================
+  // Store
+  // =========================================================================
+  '/store': {
+    config: null,
+    data: {
+      'en-US': { title: 'Store' },
+      'pt-BR': { title: 'Store' }
+    }
+  },
+
+  '/store/modules': {
+    config: {
+      icon: 'storage',
+      status: 'done',
+      type: 'manual',
+      menu: {},
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Vuex Modules' },
+      'pt-BR': { title: 'Módulos Vuex' }
+    }
+  }
+}

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

@@ -0,0 +1,54 @@
+## Overview
+
+`DH1` through `DH6` are **heading components** that render section titles with anchor navigation support. Each heading level corresponds to a Markdown heading (`##` through `######`).
+
+## Component Hierarchy
+
+| Component | Markdown | HTML | Usage |
+|-----------|----------|------|-------|
+| `DH1` | `#` (implicit) | `<h1>` | Page title, auto-generated from i18n |
+| `DH2` | `##` | `<h2>` | Main sections |
+| `DH3` | `###` | `<h3>` | Sub-sections |
+| `DH4` | `####` | `<h4>` | Detail sections |
+| `DH5` | `#####` | `<h5>` | Minor sections |
+| `DH6` | `######` | `<h6>` | Micro sections |
+
+## DH1 — Page Title
+
+DH1 is special — it doesn't receive content via props. Instead, it reads the page title from the i18n store:
+
+```javascript
+const heading = computed(() => &#123;
+  const base = store.state.i18n.base
+  return t('_.' + base + '._')
+&#125;)
+```
+
+DH1 also **registers** itself as anchor `0` in the `useNavigator` composable, enabling the ToC tree to show the page title as the root node.
+
+## DH2–DH6 — Section Titles
+
+These components receive their content via the `value` prop (already rendered as HTML by `DPageSection`):
+
+## Props (DH2–DH6)
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `Number` | Yes | Anchor ID for navigation |
+| `value` | `String` | Yes | HTML content of the heading |
+
+## Anchor Navigation
+
+Clicking any heading triggers the `navigate(id)` function from `useNavigator`, which:
+
+1. Updates the URL hash to `#&#123;id&#125;`
+2. Scrolls the viewport to the heading element
+3. Highlights the heading in the ToC tree
+
+## Node Registration
+
+Each heading component (DH2+) calls `useNavigator().index(id)` on mount and update, which pushes a node into the `page/nodes` store, building the ToC tree dynamically as the page renders.
+
+## Styling
+
+Headings use standard HTML heading elements with `v-html` rendering. Custom styling can be applied through the global `app.sass` file or by targeting the heading tags directly.

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

@@ -0,0 +1,54 @@
+## Visão Geral
+
+`DH1` até `DH6` são **componentes de título** que renderizam títulos de seção com suporte a navegação por âncora. Cada nível de título corresponde a um heading Markdown (`##` até `######`).
+
+## Hierarquia de Componentes
+
+| Componente | Markdown | HTML | Uso |
+|------------|----------|------|-----|
+| `DH1` | `#` (implícito) | `<h1>` | Título da página, gerado automaticamente do i18n |
+| `DH2` | `##` | `<h2>` | Seções principais |
+| `DH3` | `###` | `<h3>` | Sub-seções |
+| `DH4` | `####` | `<h4>` | Seções de detalhe |
+| `DH5` | `#####` | `<h5>` | Seções menores |
+| `DH6` | `######` | `<h6>` | Micro seções |
+
+## DH1 — Título da Página
+
+DH1 é especial — não recebe conteúdo via props. Em vez disso, lê o título da página da store i18n:
+
+```javascript
+const heading = computed(() => &#123;
+  const base = store.state.i18n.base
+  return t('_.' + base + '._')
+&#125;)
+```
+
+DH1 também se **registra** como âncora `0` no composable `useNavigator`, permitindo que a árvore de ToC mostre o título da página como nó raiz.
+
+## DH2–DH6 — Títulos de Seção
+
+Esses componentes recebem seu conteúdo via prop `value` (já renderizado como HTML pelo `DPageSection`):
+
+## Props (DH2–DH6)
+
+| Prop | Tipo | Obrigatório | Descrição |
+|------|------|-------------|-----------|
+| `id` | `Number` | Sim | ID da âncora para navegação |
+| `value` | `String` | Sim | Conteúdo HTML do título |
+
+## Navegação por Âncora
+
+Clicar em qualquer título dispara a função `navigate(id)` do `useNavigator`, que:
+
+1. Atualiza o hash da URL para `#&#123;id&#125;`
+2. Faz scroll do viewport até o elemento do título
+3. Destaca o título na árvore de ToC
+
+## Registro de Nós
+
+Cada componente de título (DH2+) chama `useNavigator().index(id)` no mount e update, que insere um nó no store `page/nodes`, construindo a árvore de ToC dinamicamente conforme a página renderiza.
+
+## Estilização
+
+Os títulos usam elementos HTML de heading padrão com renderização `v-html`. Estilos customizados podem ser aplicados através do arquivo global `app.sass` ou direcionando as tags de heading diretamente.

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

@@ -0,0 +1,32 @@
+## Showcase
+
+Here is how headings appear when rendered from Markdown:
+
+## This is an H2
+
+### This is an H3
+
+#### This is an H4
+
+##### This is an H5
+
+###### This is an H6
+
+Each heading above creates an anchor in the right-side ToC tree. Click on any heading to navigate directly to it. Notice how the URL hash updates and the ToC tree highlights the selected heading.
+
+## Usage in Markdown
+
+Simply use standard Markdown heading syntax in your `.md` content files:
+
+```
+## Main Section
+Content here...
+
+### Sub-Section
+More content...
+
+#### Detail
+Even more content...
+```
+
+DPageSection automatically maps each heading level to the corresponding DH component.

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

@@ -0,0 +1,32 @@
+## Demonstração
+
+Veja como os títulos aparecem quando renderizados a partir do Markdown:
+
+## Este é um H2
+
+### Este é um H3
+
+#### Este é um H4
+
+##### Este é um H5
+
+###### Este é um H6
+
+Cada título acima cria uma âncora na árvore de ToC à direita. Clique em qualquer título para navegar diretamente até ele. Note como o hash da URL atualiza e a árvore de ToC destaca o título selecionado.
+
+## Uso no Markdown
+
+Simplesmente use a sintaxe padrão de heading Markdown nos seus arquivos de conteúdo `.md`:
+
+```
+## Seção Principal
+Conteúdo aqui...
+
+### Sub-Seção
+Mais conteúdo...
+
+#### Detalhe
+Ainda mais conteúdo...
+```
+
+DPageSection automaticamente mapeia cada nível de heading ao componente DH correspondente.

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

@@ -0,0 +1,59 @@
+## Overview
+
+`DMenu` is the **left sidebar navigation** component. It renders the project branding, external links, search functionality, and the documentation page tree.
+
+## Features
+
+- **Search** — Filter pages by searching content, titles, and tags
+- **Branding section** — Logo, project name, version selector
+- **External links** — GitHub, discussions, chat, email, changelog, roadmap, sponsor
+- **Explore section** — Custom external links
+- **Page tree** — Auto-generated from the page registry with expansion panels
+
+## Search
+
+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`
+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.
+
+## Branding Section
+
+Reads from `docsector.config.js`:
+
+- `branding.logo` — Project logo image
+- `branding.name` — Project name text
+- `branding.version` — Current version
+- `branding.versions` — Version dropdown options
+
+## External Links
+
+Each link is conditionally rendered — set to `null` in the config to hide:
+
+- **GitHub** — Repository link
+- **Discussions** — GitHub Discussions
+- **Chat** — Discord/Slack/etc.
+- **Email** — Opens mailto link
+- **Changelog** — External or internal page
+- **Roadmap** — Project roadmap
+- **Sponsor** — Sponsorship page
+- **Explore** — Array of custom external links
+
+## Page Tree
+
+The page tree is built from the router's routes at component creation time. Routes are grouped by their basepath (second URL segment). Groups with a `menu.header` configuration get an expansion panel with a sticky header.
+
+## Menu Item Grouping
+
+Items are grouped when:
+
+1. The first item in a basepath group has `meta.menu.header` defined
+2. All subsequent items sharing the same basepath are collected into the same group
+
+Items without a header are displayed as standalone entries.
+
+## Auto-Scroll
+
+On mount and after navigation, DMenu automatically scrolls to the currently active menu item, centering it in the viewport with a smooth 300ms animation.

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

@@ -0,0 +1,59 @@
+## Visão Geral
+
+`DMenu` é o componente de **navegação lateral esquerda**. Ele renderiza o branding do projeto, links externos, funcionalidade de busca e a árvore de páginas de documentação.
+
+## Funcionalidades
+
+- **Busca** — Filtra páginas pesquisando conteúdo, títulos e tags
+- **Seção de branding** — Logo, nome do projeto, seletor de versão
+- **Links externos** — GitHub, discussões, chat, email, changelog, roadmap, sponsor
+- **Seção explore** — Links externos customizados
+- **Árvore de páginas** — Gerada automaticamente do registro de páginas com painéis de expansão
+
+## Busca
+
+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`
+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.
+
+## Seção de Branding
+
+Lê do `docsector.config.js`:
+
+- `branding.logo` — Imagem do logo do projeto
+- `branding.name` — Texto do nome do projeto
+- `branding.version` — Versão atual
+- `branding.versions` — Opções do dropdown de versão
+
+## Links Externos
+
+Cada link é renderizado condicionalmente — defina como `null` no config para ocultar:
+
+- **GitHub** — Link do repositório
+- **Discussions** — GitHub Discussions
+- **Chat** — Discord/Slack/etc.
+- **Email** — Abre link mailto
+- **Changelog** — Página externa ou interna
+- **Roadmap** — Roadmap do projeto
+- **Sponsor** — Página de patrocínio
+- **Explore** — Array de links externos customizados
+
+## Árvore de Páginas
+
+A árvore de páginas é construída a partir das rotas do roteador no momento de criação do componente. Rotas são agrupadas pelo seu basepath (segundo segmento da URL). Grupos com configuração `menu.header` recebem um painel de expansão com header sticky.
+
+## Agrupamento de Itens
+
+Itens são agrupados quando:
+
+1. O primeiro item de um grupo de basepath tem `meta.menu.header` definido
+2. Todos os itens subsequentes compartilhando o mesmo basepath são coletados no mesmo grupo
+
+Itens sem header são exibidos como entradas independentes.
+
+## Auto-Scroll
+
+No mount e após navegação, DMenu automaticamente faz scroll até o item de menu ativo, centralizando-o no viewport com uma animação suave de 300ms.