@docsector/docsector-reader 4.1.0 → 4.3.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/basic/agent-skills.overview.en-US.md

@@ -0,0 +1,77 @@
+## Overview
+
+Docsector Reader ships a public authoring skill for AI agents that need to understand how Docsector documentation works.
+
+The skill is a `SKILL.md` file with companion references. It explains Docsector Markdown conventions, every documented block, page structure, asset paths, authoring patterns, MCP lookup, and WebMCP browser tools.
+
+## Public URLs
+
+The built-in skill is published as a static artifact:
+
+```text
+/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md
+```
+
+The discovery index points agents to the same file and includes a SHA-256 digest:
+
+```text
+/.well-known/agent-skills/index.json
+```
+
+## What the Skill Contains
+
+<d-block-quick-links title="Skill references">
+  <d-block-quick-link
+    title="SKILL.md"
+    description="The compact workflow agents load first"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md"
+  />
+  <d-block-quick-link
+    title="Block catalog"
+    description="All Docsector blocks, syntax, and when-to-use guidance"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/references/block-catalog.md"
+  />
+  <d-block-quick-link
+    title="Page structure"
+    description="Page files, locales, assets, examples, and API JSON conventions"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/references/page-structure.md"
+  />
+  <d-block-quick-link
+    title="MCP and WebMCP"
+    description="How agents can search, fetch, navigate, and copy live docs"
+    href="/.well-known/agent-skills/docsector-documentation-authoring/references/mcp-webmcp.md"
+  />
+</d-block-quick-links>
+
+## Local and Published Copies
+
+Docsector keeps two synchronized copies of the same skill:
+
+- `.github/skills/docsector-documentation-authoring/` for repository-local assistants such as GitHub Copilot in VS Code.
+- `public/.well-known/agent-skills/docsector-documentation-authoring/` for the built documentation site.
+
+During build, Docsector copies the public artifact into `dist/spa/.well-known/agent-skills/` and generates the discovery index.
+
+## How Agents Should Use It
+
+Agents should load `SKILL.md` first, then open reference files only when a task needs more detail.
+
+For current page examples, agents can combine the skill with Docsector's MCP tools:
+
+```text
+search_docsector
+get_page_docsector
+```
+
+Browser agents can also use WebMCP tools when `navigator.modelContext` is available:
+
+- `docs.search_docs`
+- `docs.get_page`
+- `docs.navigate_to`
+- `docs.copy_current_page`
+
+## When to Publish Your Own Skill
+
+Publish a project-specific skill when your documentation has domain rules that are not covered by the built-in Docsector authoring skill.
+
+Use Docsector's `agentSkills` config to expose the skill through `/.well-known/agent-skills/index.json`, and keep the artifact under `public/.well-known/agent-skills/...` when you want Docsector to compute the digest automatically.