@docsector/docsector-reader 4.1.0 → 4.2.0

package/src/components/DMenu.vue

@@ -22,6 +22,8 @@ const term = ref(null)
 const founds = ref(false)
 const items = ref([])
 const scrolling = ref(null)
+const isMenuHovered = ref(false)
+const pendingScroll = ref(false)
 
 const subpage = computed(() => {
   const parent = $route.matched[0]?.path
@@ -312,41 +314,79 @@ const getMenuItemHeaderLabel = (meta) => {
   return label // String raw
 }
 
+const executeScrollToActiveMenuItem = () => {
+  const menu = document.getElementById('menu')
+  if (!menu) {
+    return
+  }
+
+  const menuItemActive = (menu.getElementsByClassName('q-router-link--active'))[0]
+  if (!menuItemActive || typeof menuItemActive !== 'object') {
+    return
+  }
+
+  const offsetTop1 = menuItemActive.closest('.menu-list-expansion')?.offsetTop ?? 0
+  const offsetTop2 = menuItemActive.offsetTop
+
+  const innerHeightBy2 = window.innerHeight / 2
+
+  const searchBarHeight = 50
+  let expansionHeaderHeight = 0
+  if (offsetTop1 > 0) {
+    expansionHeaderHeight = 45
+  }
+  const fixedHeight = searchBarHeight + expansionHeaderHeight
+
+  const target = scroll.getScrollTarget(menuItemActive)
+  const offset = (offsetTop1 + offsetTop2) - innerHeightBy2 + fixedHeight
+  const duration = 300
+
+  if (offset > 0) {
+    scroll.setVerticalScrollPosition(target, offset, duration)
+  }
+}
+
+const flushPendingMenuScroll = () => {
+  if (!pendingScroll.value || isMenuHovered.value) {
+    return
+  }
+
+  if (scrolling.value) {
+    clearTimeout(scrolling.value)
+    scrolling.value = null
+  }
+
+  pendingScroll.value = false
+  executeScrollToActiveMenuItem()
+}
+
 const scrollToActiveMenuItem = () => {
+  pendingScroll.value = true
+
   if (scrolling.value) {
     clearTimeout(scrolling.value)
+    scrolling.value = null
+  }
+
+  if (isMenuHovered.value) {
+    return
   }
 
   scrolling.value = setTimeout(() => {
-    const menu = document.getElementById('menu')
-    if (menu) {
-      const menuItemActive = (menu.getElementsByClassName('q-router-link--active'))[0]
-      if (menuItemActive && typeof menuItemActive === 'object') {
-        const offsetTop1 = menuItemActive.closest('.menu-list-expansion')?.offsetTop ?? 0
-        const offsetTop2 = menuItemActive.offsetTop
-
-        const innerHeightBy2 = window.innerHeight / 2
-
-        const searchBarHeight = 50
-        let expansionHeaderHeight = 0
-        if (offsetTop1 > 0) {
-          expansionHeaderHeight = 45
-        }
-        const fixedHeight = searchBarHeight + expansionHeaderHeight
-
-        const target = scroll.getScrollTarget(menuItemActive)
-        const offset = (offsetTop1 + offsetTop2) - innerHeightBy2 + fixedHeight
-        const duration = 300
-
-        if (offset > 0) {
-          scroll.setVerticalScrollPosition(target, offset, duration)
-        }
-      }
-    }
     scrolling.value = null
+    flushPendingMenuScroll()
   }, 1500)
 }
 
+const handleMenuMouseEnter = () => {
+  isMenuHovered.value = true
+}
+
+const handleMenuMouseLeave = () => {
+  isMenuHovered.value = false
+  flushPendingMenuScroll()
+}
+
 onMounted(() => {
   scrollToActiveMenuItem()
 
@@ -361,6 +401,9 @@ onBeforeUnmount(() => {
   if (scrolling.value) {
     clearTimeout(scrolling.value)
   }
+
+  isMenuHovered.value = false
+  pendingScroll.value = false
 })
 
 const buildMenuItems = () => {
@@ -428,6 +471,8 @@ watch([currentBookId, activeVersionId], rebuildItems)
 </transition>
 
 <q-scroll-area id="menu"
+  @mouseenter="handleMenuMouseEnter"
+  @mouseleave="handleMenuMouseLeave"
   :visible="true"
   :class="$q.dark.isActive ? '' : 'bg-grey-2'"
 >

package/src/components/DPageTokens.vue

@@ -35,6 +35,7 @@ import DBlockTimeline from './DBlockTimeline.vue'
 import DBlockExpandable from './DBlockExpandable.vue'
 import DBlockStepper from './DBlockStepper.vue'
 import DBlockCodeExample from './DBlockCodeExample.vue'
+import DBlockApi from './DBlockApi.vue'
 </script>
 
 <template>
@@ -149,6 +150,13 @@ import DBlockCodeExample from './DBlockCodeExample.vue'
     :height="token.height"
   />
 
+  <d-block-api
+    v-else-if="token.tag === 'api'"
+    :src="token.src"
+    :title="token.title"
+    :page-link="token.pageLink"
+  />
+
   <d-block-mermaid-diagram
     v-else-if="token.tag === 'mermaid'"
     :content="token.content"

package/src/components/api-block-model.js

@@ -0,0 +1,326 @@
+const defaultInnerTabName = '__default'
+const fallbackCategoryName = 'general'
+
+const isPlainObject = (value) => {
+  return Object.prototype.toString.call(value) === '[object Object]'
+}
+
+const isSupportedTopLevelSection = (value) => {
+  return typeof value === 'string' || isPlainObject(value)
+}
+
+const getEntryCategories = (entry = {}) => {
+  const raw = String(entry?.category || '').trim()
+
+  if (raw === '') {
+    return [fallbackCategoryName]
+  }
+
+  const groups = raw
+    .split('|')
+    .map((value) => value.trim())
+    .filter(Boolean)
+
+  return groups.length === 0 ? [fallbackCategoryName] : groups
+}
+
+const pruneInternalEntries = (value) => {
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => pruneInternalEntries(entry))
+      .filter((entry) => entry !== undefined)
+  }
+
+  if (!isPlainObject(value)) {
+    return value
+  }
+
+  if (value.internal === true) {
+    return undefined
+  }
+
+  const acc = {}
+
+  Object.entries(value).forEach(([key, entryValue]) => {
+    if (key === 'internal') {
+      return
+    }
+
+    const nextValue = pruneInternalEntries(entryValue)
+
+    if (nextValue !== undefined) {
+      acc[key] = nextValue
+    }
+  })
+
+  return acc
+}
+
+const getApiSourceName = (sourceName = '') => {
+  const normalized = String(sourceName || '')
+    .split('?')[0]
+    .split('#')[0]
+    .replace(/\\/g, '/')
+  const fileName = normalized.split('/').filter(Boolean).pop() || ''
+
+  return fileName.replace(/\.json$/i, '') || 'API'
+}
+
+const isEmptySingleEntry = (value) => {
+  if (value === undefined || value === null) {
+    return true
+  }
+
+  if (typeof value === 'string') {
+    return value.trim() === ''
+  }
+
+  if (Array.isArray(value)) {
+    return value.length === 0
+  }
+
+  if (isPlainObject(value)) {
+    return Object.keys(value).length === 0
+  }
+
+  return false
+}
+
+export const normalizeApiDocsLink = (value = '') => {
+  const normalized = String(value || '').trim()
+
+  if (normalized === '') {
+    return ''
+  }
+
+  return normalized
+    .replace(/^https:\/\/v[\d]+\.quasar\.dev/i, '')
+    .replace(/^https:\/\/quasar\.dev/i, '')
+}
+
+export const getPropsCategories = (props = {}) => {
+  const acc = new Set()
+
+  Object.values(props || {}).forEach((value) => {
+    if (value !== undefined && value !== null) {
+      getEntryCategories(value).forEach((groupKey) => {
+        acc.add(groupKey)
+      })
+    }
+  })
+
+  return acc.size === 1 ? [defaultInnerTabName] : [...acc].sort()
+}
+
+export const getInnerTabs = (api = {}, tabs = []) => {
+  const acc = {}
+
+  tabs.forEach((tab) => {
+    acc[tab] = tab === 'props' && isPlainObject(api[tab])
+      ? getPropsCategories(api[tab])
+      : [defaultInnerTabName]
+  })
+
+  return acc
+}
+
+export const parseApi = (api = {}, tabs = [], innerTabs = {}) => {
+  const acc = {}
+
+  tabs.forEach((tab) => {
+    const apiValue = api[tab]
+
+    if (innerTabs[tab]?.length > 1 && isPlainObject(apiValue)) {
+      const inner = {}
+
+      innerTabs[tab].forEach((subTab) => {
+        inner[subTab] = {}
+      })
+
+      Object.entries(apiValue).forEach(([key, value]) => {
+        if (value === undefined || value === null) {
+          return
+        }
+
+        getEntryCategories(value).forEach((groupKey) => {
+          if (inner[groupKey] !== undefined) {
+            inner[groupKey][key] = value
+          }
+        })
+      })
+
+      acc[tab] = inner
+      return
+    }
+
+    acc[tab] = {
+      [defaultInnerTabName]: apiValue ?? {}
+    }
+  })
+
+  return acc
+}
+
+const passesFilter = (filter, name, desc) => {
+  const normalizedFilter = String(filter || '').trim().toLowerCase()
+
+  if (normalizedFilter === '') {
+    return true
+  }
+
+  return (
+    String(name || '').toLowerCase().includes(normalizedFilter) ||
+    String(desc || '').toLowerCase().includes(normalizedFilter)
+  )
+}
+
+export const getFilteredApi = (parsedApi = {}, filter = '', tabs = [], innerTabs = {}) => {
+  const normalizedFilter = String(filter || '').trim().toLowerCase()
+
+  if (normalizedFilter === '') {
+    return parsedApi
+  }
+
+  const acc = {}
+
+  tabs.forEach((tab) => {
+    if (tab === 'injection') {
+      const name = parsedApi?.[tab]?.[defaultInnerTabName]
+
+      acc[tab] = {
+        [defaultInnerTabName]: passesFilter(normalizedFilter, name, '') ? name : {}
+      }
+      return
+    }
+
+    if (tab === 'quasarConfOptions') {
+      const api = parsedApi?.[tab]?.[defaultInnerTabName] || {}
+      const result = {
+        ...api,
+        definition: {}
+      }
+
+      Object.entries(api.definition || {}).forEach(([name, entry]) => {
+        if (passesFilter(normalizedFilter, name, entry?.desc)) {
+          result.definition[name] = entry
+        }
+      })
+
+      acc[tab] = {
+        [defaultInnerTabName]: Object.keys(result.definition).length === 0 && !passesFilter(normalizedFilter, api.propName, '')
+          ? {}
+          : result
+      }
+      return
+    }
+
+    const tabApi = parsedApi?.[tab] || {}
+    const tabCategories = innerTabs[tab] || [defaultInnerTabName]
+
+    acc[tab] = {}
+
+    tabCategories.forEach((category) => {
+      const subTabs = {}
+      const categoryEntries = tabApi[category] || {}
+
+      Object.entries(categoryEntries).forEach(([name, entry]) => {
+        if (passesFilter(normalizedFilter, name, entry?.desc)) {
+          subTabs[name] = entry
+        }
+      })
+
+      acc[tab][category] = subTabs
+    })
+  })
+
+  return acc
+}
+
+export const getApiCount = (parsedApi = {}, tabs = [], innerTabs = {}) => {
+  const acc = {}
+
+  tabs.forEach((tab) => {
+    const tabApi = parsedApi?.[tab] || {}
+    const tabCategories = innerTabs[tab] || [defaultInnerTabName]
+
+    if (['value', 'arg', 'injection'].includes(tab)) {
+      const value = tabApi[tabCategories[0]]
+
+      acc[tab] = {
+        overall: isEmptySingleEntry(value) ? 0 : 1
+      }
+      return
+    }
+
+    if (tab === 'quasarConfOptions') {
+      const api = tabApi[tabCategories[0]] || {}
+
+      acc[tab] = {
+        overall: Object.keys(api).length === 0
+          ? 0
+          : api.definition === undefined
+            ? 1
+            : Object.keys(api.definition || {}).length
+      }
+      return
+    }
+
+    const nextValue = {
+      overall: 0,
+      category: {}
+    }
+
+    tabCategories.forEach((category) => {
+      const count = Object.keys(tabApi[category] || {}).length
+
+      nextValue.category[category] = count
+      nextValue.overall += count
+    })
+
+    acc[tab] = nextValue
+  })
+
+  return acc
+}
+
+export const createApiBlockModel = (sourceName = '', apiDocument = {}) => {
+  const rawDocument = isPlainObject(apiDocument) ? apiDocument : {}
+  const {
+    type: _type,
+    behavior: _behavior,
+    meta,
+    addedIn: _addedIn,
+    internal: _internalSection,
+    ...apiSectionsRaw
+  } = rawDocument
+  const apiSections = {}
+
+  Object.entries(apiSectionsRaw).forEach(([sectionName, sectionValue]) => {
+    const sanitizedValue = pruneInternalEntries(sectionValue)
+
+    if (sanitizedValue !== undefined && isSupportedTopLevelSection(sanitizedValue)) {
+      apiSections[sectionName] = sanitizedValue
+    }
+  })
+
+  const tabs = Object.keys(apiSections)
+  const innerTabs = getInnerTabs(apiSections, tabs)
+  const api = parseApi(apiSections, tabs, innerTabs)
+  const sourceLabel = getApiSourceName(sourceName)
+  const docsUrl = String(meta?.docsUrl || '').trim()
+
+  return {
+    sourceLabel,
+    title: `${sourceLabel} API`,
+    docsUrl,
+    docsLink: normalizeApiDocsLink(docsUrl),
+    tabs,
+    innerTabs,
+    api,
+    nothingToShow: tabs.length === 0
+  }
+}
+
+export {
+  defaultInnerTabName
+}

package/src/components/page-section-tokens.js

@@ -21,6 +21,7 @@ const EXPANDABLE_MARKER_PREFIX = '@@DOCSECTOR_EXPANDABLE_'
 const FILE_MARKER_PREFIX = '@@DOCSECTOR_FILE_'
 const EMBEDDED_URL_MARKER_PREFIX = '@@DOCSECTOR_EMBEDDED_URL_'
 const CODE_EXAMPLE_MARKER_PREFIX = '@@DOCSECTOR_CODE_EXAMPLE_'
+const API_BLOCK_MARKER_PREFIX = '@@DOCSECTOR_API_BLOCK_'
 const CODE_SEGMENT_MARKER_PREFIX = '@@DOCSECTOR_CODE_SEGMENT_'
 const MATH_KATEX_OPTIONS = {
   throwOnError: false,
@@ -576,6 +577,43 @@ const extractCodeExampleBlocks = (source = '') => {
   }
 }
 
+const extractApiBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const replaceBlock = (match, rawAttrs) => {
+    const attrs = parseCustomTagAttributes(rawAttrs)
+    const src = decodeHtmlEntities(attrs.src || '').trim()
+
+    if (!src) {
+      return match
+    }
+
+    const marker = `${API_BLOCK_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      src,
+      title: decodeHtmlEntities(attrs.title || '').trim(),
+      pageLink: parseBooleanAttribute(attrs['page-link'], false)
+    })
+
+    return `\n${marker}\n`
+  }
+
+  const replacedSelfClosing = String(source).replace(/<d-block-api\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
+    return replaceBlock(match, rawAttrs)
+  })
+  const replaced = replacedSelfClosing.replace(/<d-block-api\b([^>]*)>([\s\S]*?)<\/d-block-api>/gi, (match, rawAttrs) => {
+    return replaceBlock(match, rawAttrs)
+  })
+
+  return {
+    source: replaced,
+    apiBlockMap: map
+  }
+}
+
 const parseFenceAttributes = (raw = '') => {
   const parsed = {}
   const pattern = /([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s;]+))/g
@@ -931,6 +969,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
   const { source: sourceWithFiles, fileMap } = extractFileBlocks(sourceWithQuickLinks)
   const { source: sourceWithEmbeddedUrls, embeddedUrlMap } = extractEmbeddedUrlBlocks(sourceWithFiles)
   const { source: sourceWithCodeExamples, codeExampleMap } = extractCodeExampleBlocks(sourceWithEmbeddedUrls)
+  const { source: sourceWithApiBlocks, apiBlockMap } = extractApiBlocks(sourceWithCodeExamples)
 
   fileMap.forEach((data, marker) => {
     fileMap.set(marker, {
@@ -956,7 +995,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
   const markdown = createMarkdownBlockParser()
   const markdownInline = createMarkdownInlineParser()
   const markdownEnv = {}
-  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithCodeExamples, codeSegmentsMap), markdownEnv)
+  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithApiBlocks, codeSegmentsMap), markdownEnv)
   const tokens = []
 
   let level = 0
@@ -1234,6 +1273,19 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
             break
           }
 
+          if (apiBlockMap.has(element.content.trim())) {
+            const data = apiBlockMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'api',
+              map: element.map,
+              src: data.src,
+              title: data.title,
+              pageLink: data.pageLink
+            })
+            break
+          }
+
           if (tag === 'p') {
             const imageToken = parseStandaloneImageToken(element.content)
 

package/src/components/source-code-lines.js

@@ -0,0 +1,17 @@
+const normalizeLineBreaks = (text = '') => String(text || '').replace(/\r\n/g, '\n')
+
+export const countRenderedCodeLines = (text = '') => {
+  const normalized = normalizeLineBreaks(text)
+
+  if (normalized === '') {
+    return 0
+  }
+
+  const withoutTerminalBreak = normalized.replace(/\n$/, '')
+
+  if (withoutTerminalBreak === '') {
+    return 1
+  }
+
+  return withoutTerminalBreak.split('\n').length
+}

package/src/pages/manual/content/blocks/api-reference.overview.en-US.md

@@ -0,0 +1,40 @@
+## Overview
+
+API Reference blocks render a JSON document that follows the existing Quasar API schema directly inside Markdown.
+
+This keeps the viewer compatible with Quasar-style API files while still allowing non-Vue APIs to reuse the same section model for props, methods, events, values, arguments, and config shapes.
+
+The block is authored with the custom Markdown element `<d-block-api>`.
+
+## Markdown Syntax
+
+```html
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+## Attributes
+
+| Attribute | Purpose |
+|-----------|---------|
+| `src` | Same-origin JSON path to fetch in the browser |
+| `title` | Optional header override shown above the API card |
+| `page-link` | Shows the Docs button when the JSON has `meta.docsUrl` |
+
+## JSON Source Model
+
+- The first implementation follows the same delivery model as Quasar Docs: the JSON file is served as a public asset and fetched on demand.
+- No Docsector-specific schema is required. If your file already follows the Quasar API structure, it can be rendered as-is.
+- Non-Vue APIs can still use the same shape by filling the sections they need, such as `props`, `methods`, `events`, `value`, `arg`, or `quasarConfOptions`.
+
+## Notes
+
+- `props` are grouped into subtabs when more than one `category` is present.
+- Entries marked with `internal: true` are hidden from the rendered block.
+- The current version expects same-origin JSON assets so the browser can fetch them without CORS workarounds.
+- If the JSON exposes `meta.docsUrl`, `page-link="true"` can surface a Docs button without changing the schema.

package/src/pages/manual/content/blocks/api-reference.overview.pt-BR.md

@@ -0,0 +1,40 @@
+## Visão geral
+
+Os blocos de Referência de API renderizam um documento JSON que segue o schema de API já existente do Quasar diretamente dentro do Markdown.
+
+Isso mantém o viewer compatível com arquivos de API no estilo do Quasar e ainda permite que APIs não-Vue reutilizem o mesmo modelo de seções para props, methods, events, values, arguments e estruturas de configuração.
+
+O bloco é escrito com o elemento Markdown customizado `<d-block-api>`.
+
+## Sintaxe Markdown
+
+```html
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+## Atributos
+
+| Atributo | Finalidade |
+|----------|------------|
+| `src` | Caminho same-origin do JSON a ser buscado no navegador |
+| `title` | Sobrescreve opcionalmente o título exibido acima do card |
+| `page-link` | Exibe o botão Docs quando o JSON possui `meta.docsUrl` |
+
+## Modelo da Fonte JSON
+
+- A primeira implementação segue o mesmo modelo de entrega do Quasar Docs: o arquivo JSON é servido como asset público e carregado sob demanda.
+- Nenhum schema específico do Docsector é exigido. Se o arquivo já seguir a estrutura de API do Quasar, ele pode ser renderizado sem alterações.
+- APIs não-Vue ainda podem usar a mesma forma preenchendo apenas as seções necessárias, como `props`, `methods`, `events`, `value`, `arg` ou `quasarConfOptions`.
+
+## Notas
+
+- `props` são agrupadas em subtabs quando mais de uma `category` está presente.
+- Entradas marcadas com `internal: true` são ocultadas do bloco renderizado.
+- A versão atual espera assets JSON same-origin para que o navegador faça o fetch sem workarounds de CORS.
+- Se o JSON expuser `meta.docsUrl`, `page-link="true"` pode exibir um botão Docs sem alterar o schema.

package/src/pages/manual/content/blocks/api-reference.showcase.en-US.md

@@ -0,0 +1,33 @@
+## Showcase
+
+### Quasar JSON Without Refactoring
+
+This example renders a real Quasar API JSON file copied into `public/quasar-api/`.
+
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+### Generic SDK JSON With the Same Schema
+
+This example uses the same section model for a non-Vue HTTP client and also enables the optional Docs button.
+
+<d-block-api src="/api/manual/http-client.json" title="HTTP Client API" page-link="true" />
+
+## Authoring Syntax
+
+```html
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+## Features Visible Above
+
+- **Quasar JSON compatibility** with a real file served from `public/quasar-api/`
+- **Generic API support** without introducing a new schema
+- **Local filter** across names and descriptions inside the loaded API sections
+- **Grouped props subtabs** when multiple categories exist in the JSON
+- **Optional Docs link** when `meta.docsUrl` is present and `page-link="true"` is used