@docsector/docsector-reader 4.0.1 → 4.1.0

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 ''
+}

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

@@ -20,6 +20,7 @@ const STEPPER_MARKER_PREFIX = '@@DOCSECTOR_STEPPER_'
 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 CODE_SEGMENT_MARKER_PREFIX = '@@DOCSECTOR_CODE_SEGMENT_'
 const MATH_KATEX_OPTIONS = {
   throwOnError: false,
@@ -246,6 +247,24 @@ const parseExpandableOpenState = (raw = '') => {
   return ['1', 'true', 'yes', 'on'].includes(String(raw).trim().toLowerCase())
 }
 
+const parseBooleanAttribute = (raw, fallback = false) => {
+  if (raw === undefined || raw === null || raw === '') {
+    return fallback
+  }
+
+  const normalized = String(raw).trim().toLowerCase()
+
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+    return true
+  }
+
+  if (['0', 'false', 'no', 'off'].includes(normalized)) {
+    return false
+  }
+
+  return fallback
+}
+
 const parseTimelineTags = (raw = '') => {
   return decodeHtmlEntities(raw)
     .split(',')
@@ -517,6 +536,46 @@ const extractEmbeddedUrlBlocks = (source = '') => {
   }
 }
 
+const extractCodeExampleBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const replaceBlock = (match, rawAttrs, rawCaption = '') => {
+    const attrs = parseCustomTagAttributes(rawAttrs)
+    const src = decodeHtmlEntities(attrs.src || attrs.file || '').trim()
+
+    if (!src) {
+      return match
+    }
+
+    const marker = `${CODE_EXAMPLE_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      src,
+      title: decodeHtmlEntities(attrs.title || '').trim(),
+      expanded: parseBooleanAttribute(attrs.expanded, false),
+      codepen: parseBooleanAttribute(attrs.codepen, true),
+      scrollable: parseBooleanAttribute(attrs.scrollable, false),
+      overflow: parseBooleanAttribute(attrs.overflow, false),
+      height: decodeHtmlEntities(attrs.height || '').trim(),
+      caption: String(rawCaption).trim()
+    })
+
+    return `\n${marker}\n`
+  }
+
+  const replacedSelfClosing = String(source).replace(/<d-block-code-example\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
+    return replaceBlock(match, rawAttrs)
+  })
+  const replaced = replacedSelfClosing.replace(/<d-block-code-example\b([^>]*)>([\s\S]*?)<\/d-block-code-example>/gi, replaceBlock)
+
+  return {
+    source: replaced,
+    codeExampleMap: map
+  }
+}
+
 const parseFenceAttributes = (raw = '') => {
   const parsed = {}
   const pattern = /([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s;]+))/g
@@ -871,6 +930,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
   const { source: sourceWithQuickLinks, quickLinksMap } = extractQuickLinksBlocks(sourceWithCards)
   const { source: sourceWithFiles, fileMap } = extractFileBlocks(sourceWithQuickLinks)
   const { source: sourceWithEmbeddedUrls, embeddedUrlMap } = extractEmbeddedUrlBlocks(sourceWithFiles)
+  const { source: sourceWithCodeExamples, codeExampleMap } = extractCodeExampleBlocks(sourceWithEmbeddedUrls)
 
   fileMap.forEach((data, marker) => {
     fileMap.set(marker, {
@@ -886,10 +946,17 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
     })
   })
 
+  codeExampleMap.forEach((data, marker) => {
+    codeExampleMap.set(marker, {
+      ...data,
+      caption: restoreShieldedCodeSegments(data.caption, codeSegmentsMap)
+    })
+  })
+
   const markdown = createMarkdownBlockParser()
   const markdownInline = createMarkdownInlineParser()
   const markdownEnv = {}
-  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithEmbeddedUrls, codeSegmentsMap), markdownEnv)
+  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithCodeExamples, codeSegmentsMap), markdownEnv)
   const tokens = []
 
   let level = 0
@@ -1146,6 +1213,27 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
             break
           }
 
+          if (codeExampleMap.has(element.content.trim())) {
+            const data = codeExampleMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'code-example',
+              map: element.map,
+              codeIndex: parserState.codeIndex++,
+              src: data.src,
+              title: data.title,
+              expanded: data.expanded,
+              codepen: data.codepen,
+              scrollable: data.scrollable,
+              overflow: data.overflow,
+              height: data.height,
+              caption: data.caption !== ''
+                ? markdownInline.renderInline(data.caption, markdownEnv)
+                : ''
+            })
+            break
+          }
+
           if (tag === 'p') {
             const imageToken = parseStandaloneImageToken(element.content)
 

package/src/examples/manual/code-examples/BasicCounter.vue

@@ -0,0 +1,63 @@
+<template>
+  <div class="basic-counter-example q-pa-md">
+    <q-card class="basic-counter-example__card" flat bordered>
+      <q-card-section>
+        <div class="text-subtitle2 text-grey-7">Interactive preview</div>
+        <div class="basic-counter-example__value">{{ count }}</div>
+        <div class="text-body2 text-grey-7">{{ countLabel }}</div>
+      </q-card-section>
+
+      <q-separator></q-separator>
+
+      <q-card-actions align="right">
+        <q-btn flat color="primary" label="Reset" @click="reset"></q-btn>
+        <q-btn unelevated color="primary" label="Increment" @click="increment"></q-btn>
+      </q-card-actions>
+    </q-card>
+  </div>
+</template>
+
+<script>
+import { computed, ref } from 'vue'
+
+export default {
+  setup () {
+    const count = ref(0)
+    const countLabel = computed(() => count.value === 1 ? 'click recorded' : 'clicks recorded')
+
+    function increment () {
+      count.value++
+    }
+
+    function reset () {
+      count.value = 0
+    }
+
+    return {
+      count,
+      countLabel,
+      increment,
+      reset
+    }
+  }
+}
+</script>
+
+<style scoped>
+.basic-counter-example {
+  display: flex;
+  justify-content: center;
+}
+
+.basic-counter-example__card {
+  max-width: 360px;
+  width: 100%;
+}
+
+.basic-counter-example__value {
+  font-size: 48px;
+  font-weight: 700;
+  line-height: 1;
+  margin: 12px 0 6px;
+}
+</style>

package/src/examples/manual/code-examples/InlineNotice.vue

@@ -0,0 +1,60 @@
+<template>
+  <div class="inline-notice-example q-pa-md">
+    <q-banner rounded class="inline-notice-example__banner">
+      <template #avatar>
+        <q-icon name="tips_and_updates" color="primary"></q-icon>
+      </template>
+
+      <div class="text-weight-medium">{{ title }}</div>
+      <div class="text-body2">{{ message }}</div>
+
+      <template #action>
+        <q-btn flat color="primary" label="Dismiss" @click="dismiss"></q-btn>
+      </template>
+    </q-banner>
+
+    <div v-if="dismissed" class="inline-notice-example__status text-caption">
+      The notice was dismissed.
+    </div>
+  </div>
+</template>
+
+<script>
+import { ref } from 'vue'
+
+export default {
+  setup () {
+    const title = 'Documentation tip'
+    const message = 'Use expanded examples when the source code is part of the lesson.'
+    const dismissed = ref(false)
+
+    function dismiss () {
+      dismissed.value = true
+    }
+
+    return {
+      dismissed,
+      dismiss,
+      message,
+      title
+    }
+  }
+}
+</script>
+
+<style scoped>
+.inline-notice-example {
+  display: grid;
+  gap: 10px;
+}
+
+.inline-notice-example__banner {
+  background: rgba(25, 118, 210, 0.08);
+  border: 1px solid rgba(25, 118, 210, 0.18);
+}
+
+.inline-notice-example__status {
+  color: #607d68;
+  padding-left: 8px;
+}
+</style>

package/src/pages/manual/content/blocks/code-examples.overview.en-US.md

@@ -0,0 +1,56 @@
+## Overview
+
+Code example blocks render project Vue SFCs as live previews inside Markdown pages.
+
+They are useful when documentation needs to show the real behavior of a component and still let readers inspect the exact source behind the preview.
+
+The block is authored with the custom Markdown element `<d-block-code-example>`.
+
+## Example Files
+
+Place example components under `src/examples/**/*.vue` in the project using Docsector.
+
+Docsector discovers those files at build time through Vite. The `src` value is normalized to kebab-case, so this block:
+
+```html
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter" />
+```
+
+resolves this file:
+
+```text
+src/examples/manual/code-examples/BasicCounter.vue
+```
+
+You can also use `file` instead of `src` when migrating examples from Quasar Docs patterns.
+
+## Attributes
+
+| Attribute | Purpose |
+|-----------|---------|
+| `src` | Example id under `src/examples/**/*.vue` |
+| `file` | Alias for `src` |
+| `title` | Header title shown above the preview |
+| `expanded` | Opens the source panel by default when set to `true` |
+| `codepen` | Shows the CodePen action unless set to `false` |
+| `scrollable` | Gives the preview a fixed scrollable height |
+| `overflow` | Allows both horizontal and vertical overflow in the preview |
+| `height` | Sets a custom preview height, such as `360` or `420px` |
+
+## Source Panel
+
+The source button opens the Vue SFC split into Template, Script, Style, and All tabs when those sections are present.
+
+The source panel reuses the standard Docsector code block renderer, so readers get syntax highlighting, copy support, and the same dark/light treatment as regular code blocks.
+
+## GitHub Source Link
+
+The GitHub button opens the example SFC in the project repository when Docsector can derive a repository URL from `github.editBaseUrl` or `links.github` in `docsector.config.js`.
+
+## CodePen Export
+
+The CodePen button is available when the source can be transformed safely for a browser-only demo.
+
+The first implementation supports plain Vue SFCs with a template, optional style, and an Options API `export default` script. Named imports from `vue` and `quasar` are converted to browser globals. Examples that use `<script setup>`, TypeScript scripts, or local imports still render in Docsector, but the CodePen action is disabled.
+
+Set `codepen="false"` when an example is intentionally not meant to be exported.