@docsector/docsector-reader 4.0.1 → 4.2.0

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/code-block-highlighting.js

@@ -0,0 +1,16 @@
+import Prism from 'prismjs'
+
+import 'prismjs/components/prism-markup'
+import 'prismjs/components/prism-markup-templating'
+import 'prismjs/components/prism-javascript'
+import 'prismjs/components/prism-css'
+import 'prismjs/components/prism-php'
+import 'prismjs/components/prism-bash'
+
+if (!Prism.languages.vue && Prism.languages.markup?.tag?.addInlined) {
+	Prism.languages.markup.tag.addInlined('script', 'javascript')
+	Prism.languages.markup.tag.addInlined('style', 'css')
+	Prism.languages.vue = Prism.languages.markup
+}
+
+export default Prism

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

@@ -0,0 +1,363 @@
+const PART_LABELS = Object.freeze({
+  template: 'Template',
+  script: 'Script',
+  style: 'Style'
+})
+
+const PART_ORDER = ['Template', 'Script', 'Style']
+const ALLOWED_CODEPEN_IMPORTS = new Set(['vue', 'quasar'])
+
+const createSfcOpeningTagPattern = () => /<(template|script|style)\b((?:"[^"]*"|'[^']*'|[^'">])*)>/gi
+
+const createSameTagPattern = (tag) => new RegExp(`</?${tag}\\b((?:"[^"]*"|'[^']*'|[^'">])*)>`, 'gi')
+
+const findSfcBlockRange = (source = '', tag = '', searchStart = 0) => {
+  const pattern = createSameTagPattern(tag)
+  pattern.lastIndex = searchStart
+
+  let depth = 1
+  let match = pattern.exec(source)
+
+  while (match !== null) {
+    const token = match[0]
+    const isClosing = token.startsWith('</')
+    const isSelfClosing = /\/\s*>$/.test(token)
+
+    if (isClosing) {
+      depth--
+    } else if (!isSelfClosing) {
+      depth++
+    }
+
+    if (depth === 0) {
+      return {
+        closingStart: match.index,
+        blockEnd: pattern.lastIndex
+      }
+    }
+
+    match = pattern.exec(source)
+  }
+
+  return null
+}
+
+const parseVueSfcBlocks = (source = '') => {
+  const blocks = {
+    template: [],
+    script: [],
+    style: []
+  }
+  const content = String(source)
+  const openingPattern = createSfcOpeningTagPattern()
+
+  let cursor = 0
+  while (cursor < content.length) {
+    openingPattern.lastIndex = cursor
+
+    const match = openingPattern.exec(content)
+    if (!match) {
+      break
+    }
+
+    const tag = match[1].toLowerCase()
+    const openingStart = match.index
+    const openingEnd = openingPattern.lastIndex
+    const range = findSfcBlockRange(content, tag, openingEnd)
+
+    if (!range) {
+      cursor = openingEnd
+      continue
+    }
+
+    blocks[tag].push({
+      tag,
+      attrs: match[2] || '',
+      content: content.slice(openingEnd, range.closingStart).trim(),
+      raw: content.slice(openingStart, range.blockEnd).trim()
+    })
+
+    cursor = range.blockEnd
+  }
+
+  return blocks
+}
+
+const hasAttribute = (rawAttrs = '', name = '') => {
+  const pattern = new RegExp(`(?:^|\\s)${name}(?:\\s|=|$)`, 'i')
+  return pattern.test(String(rawAttrs || ''))
+}
+
+const getLangAttribute = (rawAttrs = '') => {
+  const match = String(rawAttrs || '').match(/(?:^|\s)lang\s*=\s*(?:"([^"]+)"|'([^']+)'|([^\s>]+))/i)
+  return (match?.[1] || match?.[2] || match?.[3] || '').trim().toLowerCase()
+}
+
+const normalizeNamedImport = (rawName = '') => {
+  const trimmed = rawName.trim()
+  const aliasMatch = trimmed.match(/^(.+?)\s+as\s+(.+)$/i)
+
+  if (aliasMatch) {
+    return `${aliasMatch[1].trim()}: ${aliasMatch[2].trim()}`
+  }
+
+  return trimmed
+}
+
+const createGlobalDestructure = (globalName, rawNames = '') => {
+  const names = String(rawNames)
+    .split(',')
+    .map((name) => normalizeNamedImport(name))
+    .filter(Boolean)
+
+  if (names.length === 0) {
+    return ''
+  }
+
+  return `const { ${names.join(', ')} } = ${globalName}`
+}
+
+const findUnsupportedImport = (script = '') => {
+  const importsWithSourcePattern = /^\s*import\s+(.+?)\s+from\s+["']([^"']+)["'];?\s*$/gm
+  const sideEffectImportPattern = /^\s*import\s+["']([^"']+)["'];?\s*$/gm
+
+  let match = importsWithSourcePattern.exec(script)
+  while (match !== null) {
+    const importSpecifiers = match[1].trim()
+    const importSource = match[2].trim()
+
+    if (!ALLOWED_CODEPEN_IMPORTS.has(importSource) || !importSpecifiers.startsWith('{')) {
+      return importSource
+    }
+
+    match = importsWithSourcePattern.exec(script)
+  }
+
+  match = sideEffectImportPattern.exec(script)
+  if (match !== null) {
+    return match[1].trim()
+  }
+
+  return ''
+}
+
+const transformAllowedImports = (script = '') => {
+  return String(script)
+    .replace(/^\s*import\s+\{([^}]+)\}\s+from\s+["']vue["'];?\s*$/gm, (_, imports) => createGlobalDestructure('Vue', imports))
+    .replace(/^\s*import\s+\{([^}]+)\}\s+from\s+["']quasar["'];?\s*$/gm, (_, imports) => createGlobalDestructure('Quasar', imports))
+}
+
+const getScriptForValidation = (script = '') => {
+  return transformAllowedImports(script).trim()
+}
+
+const stripSfcTags = (blocks = []) => {
+  return blocks
+    .map((block) => block.content)
+    .filter(Boolean)
+    .join('\n\n')
+    .trim()
+}
+
+const getStylePreprocessor = (styleBlock) => {
+  const lang = getLangAttribute(styleBlock?.attrs || '')
+  return lang || 'none'
+}
+
+const getPartLanguage = (label, text = '') => {
+  if (label === 'Template') return 'html'
+  if (label === 'Script') return getLangAttribute(text.match(/^<script\b([^>]*)>/i)?.[1] || '') || 'javascript'
+  if (label === 'Style') return getLangAttribute(text.match(/^<style\b([^>]*)>/i)?.[1] || '') || 'css'
+  if (label === 'All') return 'vue'
+  return 'text'
+}
+
+const createEditorsFlag = ({ html, css, js }) => {
+  const flag = (html ? 0b100 : 0) | (css ? 0b010 : 0) | (js ? 0b001 : 0)
+  return flag.toString(2)
+}
+
+const createCodepenResources = (quasarVersion = 'latest') => {
+  const version = String(quasarVersion || 'latest').trim() || 'latest'
+
+  return {
+    cssExternal: [
+      'https://fonts.googleapis.com/css?family=Roboto:100,300,400,500,700,900|Material+Icons',
+      `https://cdn.jsdelivr.net/npm/quasar@${version}/dist/quasar.min.css`
+    ].join(';'),
+    jsExternal: [
+      'https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js',
+      `https://cdn.jsdelivr.net/npm/quasar@${version}/dist/quasar.umd.prod.js`
+    ].join(';')
+  }
+}
+
+const normalizeRepositoryFilePath = (filePath = '') => {
+  return String(filePath || '')
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '')
+    .trim()
+}
+
+const createCodepenJs = (script = '') => {
+  const transformedScript = transformAllowedImports(script).trim()
+  const componentScript = transformedScript
+    ? transformedScript.replace(/\bexport\s+default\b/, 'const __CodeExample =')
+    : 'const __CodeExample = {}'
+
+  return `${componentScript}
+
+const app = Vue.createApp(__CodeExample)
+
+app.use(Quasar, { config: {} })
+app.mount('#q-app')
+`
+}
+
+export const parseVueSfcParts = (source = '') => {
+  const blocks = parseVueSfcBlocks(source)
+  const parts = {}
+
+  Object.entries(blocks).forEach(([tag, tagBlocks]) => {
+    const label = PART_LABELS[tag]
+    const raw = tagBlocks
+      .map((block) => block.raw)
+      .filter(Boolean)
+      .join('\n\n')
+      .trim()
+
+    if (label && raw) {
+      parts[label] = raw
+    }
+  })
+
+  return parts
+}
+
+export const createCodeExampleTabs = (source = '') => {
+  const trimmedSource = String(source || '').trim()
+  const parts = parseVueSfcParts(trimmedSource)
+  const tabs = PART_ORDER
+    .filter((label) => parts[label])
+    .map((label) => ({
+      label,
+      language: getPartLanguage(label, parts[label]),
+      text: parts[label]
+    }))
+
+  if (tabs.length > 1) {
+    tabs.push({
+      label: 'All',
+      language: getPartLanguage('All'),
+      text: trimmedSource
+    })
+  }
+
+  if (tabs.length === 0 && trimmedSource) {
+    tabs.push({
+      label: 'Source',
+      language: 'text',
+      text: trimmedSource
+    })
+  }
+
+  return tabs
+}
+
+export const getCodepenUnsupportedReason = (source = '') => {
+  const blocks = parseVueSfcBlocks(source)
+
+  if (blocks.template.length === 0 || !stripSfcTags(blocks.template)) {
+    return 'CodePen export requires a Vue SFC template section.'
+  }
+
+  if (blocks.script.length > 1) {
+    return 'CodePen export supports a single script section in this version.'
+  }
+
+  const scriptBlock = blocks.script[0]
+  if (!scriptBlock) {
+    return ''
+  }
+
+  if (hasAttribute(scriptBlock.attrs, 'setup')) {
+    return 'CodePen export does not support script setup examples yet.'
+  }
+
+  if (getLangAttribute(scriptBlock.attrs) === 'ts') {
+    return 'CodePen export does not support TypeScript script sections yet.'
+  }
+
+  const unsupportedImport = findUnsupportedImport(scriptBlock.content)
+  if (unsupportedImport) {
+    return `CodePen export does not support local or external imports (${unsupportedImport}).`
+  }
+
+  const validationScript = getScriptForValidation(scriptBlock.content)
+  if (validationScript && !/\bexport\s+default\b/.test(validationScript)) {
+    return 'CodePen export requires an Options API default export in this version.'
+  }
+
+  return ''
+}
+
+export const canCreateCodepenPayload = (source = '') => {
+  return getCodepenUnsupportedReason(source) === ''
+}
+
+export const createCodepenPayload = (source = '', options = {}) => {
+  const unsupportedReason = getCodepenUnsupportedReason(source)
+  if (unsupportedReason) {
+    throw new Error(unsupportedReason)
+  }
+
+  const blocks = parseVueSfcBlocks(source)
+  const html = stripSfcTags(blocks.template)
+  const css = stripSfcTags(blocks.style)
+  const script = blocks.script[0]?.content || ''
+  const js = createCodepenJs(script)
+  const resources = createCodepenResources(options.quasarVersion)
+  const sourceUrl = String(options.sourceUrl || '').trim()
+  const sourceComment = sourceUrl
+    ? `<!--\nGenerated from:\n${sourceUrl}\n-->\n`
+    : ''
+
+  return {
+    title: String(options.title || 'Docsector code example').trim() || 'Docsector code example',
+    html: `${sourceComment}<div id="q-app" style="min-height: 100vh;">
+${html}
+</div>`,
+    head: '',
+    html_pre_processor: 'none',
+    css,
+    css_pre_processor: getStylePreprocessor(blocks.style[0]),
+    css_external: resources.cssExternal,
+    js,
+    js_pre_processor: 'babel',
+    js_external: resources.jsExternal,
+    editors: createEditorsFlag({ html, css, js })
+  }
+}
+
+export const createCodeExampleGitHubUrl = (filePath = '', config = {}) => {
+  const normalizedFilePath = normalizeRepositoryFilePath(filePath)
+
+  if (!normalizedFilePath) {
+    return ''
+  }
+
+  const editBaseUrl = String(config.github?.editBaseUrl || '').trim()
+  const editMatch = editBaseUrl.match(/^(https:\/\/github\.com\/[^/]+\/[^/]+)\/(?:edit|blob|tree)\/([^/]+)(?:\/.*)?$/)
+
+  if (editMatch) {
+    return `${editMatch[1]}/blob/${editMatch[2]}/${normalizedFilePath}`
+  }
+
+  const githubUrl = String(config.links?.github || '').trim().replace(/\/+$/, '')
+
+  if (/^https:\/\/github\.com\/[^/]+\/[^/]+$/.test(githubUrl)) {
+    return `${githubUrl}/blob/main/${normalizedFilePath}`
+  }
+
+  return ''
+}