@docsector/docsector-reader 3.2.1 → 3.3.1

package/src/components/QZoom.js

@@ -6,15 +6,13 @@
 
 import {
   h,
+  Teleport,
   ref, computed,
   onMounted, onBeforeUnmount
 } from 'vue'
 
 import { useColorize } from 'q-colorize-mixin'
 
-import { dom } from 'quasar'
-const { offset } = dom
-
 import './QZoom.sass'
 
 // @
@@ -34,7 +32,12 @@ export default {
     initialScaleText: { type: Number, default: 100, validator: v => v >= 50 && v <= 500 },
     noCenter: Boolean,
     noWheelScale: Boolean,
-    noEscClose: Boolean
+    noEscClose: Boolean,
+    showCloseButton: Boolean,
+    closeButtonLabel: {
+      type: String,
+      default: 'Close zoom'
+    }
   },
 
   setup (props, { emit, slots }) {
@@ -183,13 +186,29 @@ export default {
       }
     }
 
+    const onOverlayClick = (e) => {
+      if (isZoomed.value) {
+        hide()
+
+        e.preventDefault()
+      }
+    }
+
+    const stopEvent = (e) => {
+      e.stopPropagation()
+    }
+
     const getPosition = () => {
-      const position = offset(vComponent.value)
+      const rect = vComponent.value.getBoundingClientRect()
+      const position = {
+        left: rect.left,
+        top: rect.top
+      }
 
       position.left = position.left + 'px'
       position.top = position.top + 'px'
-      position.width = vComponent.value.clientWidth + 'px'
-      position.height = vComponent.value.clientHeight + 'px'
+      position.width = rect.width + 'px'
+      position.height = rect.height + 'px'
 
       return position
     }
@@ -245,7 +264,34 @@ export default {
           fontSize: props.scaleText && !props.scale && `${scaleTextValue.value}%`
         }
       }), [
-        slot && slot({ zoomed: isZoomed.value })
+        h('div', {
+          class: 'q-zoom__content-inner',
+          onClick: stopEvent
+        }, [
+          slot && slot({ zoomed: isZoomed.value })
+        ])
+      ])
+    }
+
+    const __renderCloseButton = () => {
+      if (!props.showCloseButton) {
+        return null
+      }
+
+      return h('button', {
+        type: 'button',
+        class: 'q-zoom__close-button',
+        'aria-label': props.closeButtonLabel,
+        title: props.closeButtonLabel,
+        onClick: (e) => {
+          stopEvent(e)
+          hide()
+        }
+      }, [
+        h('span', {
+          class: 'q-zoom__close-icon',
+          'aria-hidden': 'true'
+        }, '×')
       ])
     }
 
@@ -256,13 +302,18 @@ export default {
 
       return h('div', Colorize.setBackgroundColor(bgColor.value, {
         class: 'q-zoom__overlay' +
-          (props.manual ? '' : ' q-zoom__zoom-out')
+          (props.manual ? '' : ' q-zoom__zoom-out'),
+        onClick: onOverlayClick
       }), [
+        __renderCloseButton(),
         __renderOverlayContent()
       ])
     }
 
-    return () => h('div', {
+    return () => {
+      const overlay = __renderOverlay()
+
+      return h('div', {
       class: 'q-zoom' +
         (props.manual ? '' : ' q-zoom__zoom-in'),
 
@@ -270,9 +321,12 @@ export default {
       onWheel: wheelEvent,
 
       ref: vComponent
-    }, [
-      slots.default && slots.default({ zoomed: isZoomed.value }),
-      __renderOverlay()
-    ])
+      }, [
+        slots.default && slots.default({ zoomed: isZoomed.value }),
+        overlay
+          ? h(Teleport, { to: 'body' }, overlay)
+          : null
+      ])
+    }
   }
 }

package/src/components/QZoom.sass

@@ -22,19 +22,54 @@ $box-shadow: 1px 1px 7px 1px rgba(0,0,0,.2) !default
     padding: 0
     margin: 0
     z-index: 6000
+    overflow: hidden
 
   &__content
-    position: relative
-    display: block
+    position: absolute
+    display: flex
+    align-items: center
+    justify-content: center
     transition: all .5s cubic-bezier(.2,0,.2,1)
     text-align: center
-    vertical-align: middle
     width: 100%
     height: 0
     max-width: 100%
     max-height: 100%
     overflow: hidden
 
+    & > *
+      max-width: 100%
+      max-height: 100%
+
+  &__content-inner
+    display: inline-flex
+    align-items: center
+    justify-content: center
+    max-width: 100%
+    max-height: 100%
+
+  &__close-button
+    position: absolute
+    top: 24px
+    right: 24px
+    width: 56px
+    height: 56px
+    display: inline-flex
+    align-items: center
+    justify-content: center
+    border: 0
+    border-radius: 999px
+    background: rgba(255,255,255,.12)
+    color: #fff
+    cursor: pointer
+    z-index: 6001
+    box-shadow: $box-shadow
+    backdrop-filter: blur(8px)
+
+  &__close-icon
+    font-size: 34px
+    line-height: 1
+
   &__no-center
     text-align: unset
     vertical-align: unset

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

@@ -14,6 +14,7 @@ const ALERT_MESSAGE_TYPES = new Set([
 
 const QUICK_LINKS_MARKER_PREFIX = '@@DOCSECTOR_QUICK_LINKS_'
 const EXPANDABLE_MARKER_PREFIX = '@@DOCSECTOR_EXPANDABLE_'
+const FILE_MARKER_PREFIX = '@@DOCSECTOR_FILE_'
 const CODE_SEGMENT_MARKER_PREFIX = '@@DOCSECTOR_CODE_SEGMENT_'
 const MATH_KATEX_OPTIONS = {
   throwOnError: false,
@@ -190,6 +191,62 @@ const extractExpandableBlocks = (source = '') => {
   }
 }
 
+const getFileTitleFromSrc = (src = '') => {
+  const normalized = String(src)
+    .split('#')[0]
+    .split('?')[0]
+  const rawSegment = normalized
+    .split('/')
+    .filter(Boolean)
+    .pop() || ''
+
+  if (!rawSegment) {
+    return 'Download file'
+  }
+
+  try {
+    return decodeURIComponent(rawSegment)
+  } catch {
+    return rawSegment
+  }
+}
+
+const extractFileBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const replaceBlock = (match, rawAttrs, rawCaption = '') => {
+    const attrs = parseCustomTagAttributes(rawAttrs)
+    const src = decodeHtmlEntities(attrs.src || attrs.href || '').trim()
+
+    if (!src) {
+      return match
+    }
+
+    const marker = `${FILE_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      src,
+      title: decodeHtmlEntities(attrs.title || attrs.name || '').trim(),
+      size: decodeHtmlEntities(attrs.size || '').trim(),
+      caption: String(rawCaption).trim()
+    })
+
+    return `\n${marker}\n`
+  }
+
+  const replacedSelfClosing = String(source).replace(/<d-file\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
+    return replaceBlock(match, rawAttrs)
+  })
+  const replaced = replacedSelfClosing.replace(/<d-file\b([^>]*)>([\s\S]*?)<\/d-file>/gi, replaceBlock)
+
+  return {
+    source: replaced,
+    fileMap: map
+  }
+}
+
 const parseFenceAttributes = (raw = '') => {
   const parsed = {}
   const pattern = /([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s;]+))/g
@@ -215,6 +272,97 @@ const parseTokenAttributes = (element) => {
   return parsed
 }
 
+const decodeHtmlEntities = (value = '') => {
+  return String(value)
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&apos;/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+}
+
+const escapeHtml = (value = '') => {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+const extractTagAttributes = (html = '', tagName = '') => {
+  const match = String(html).match(new RegExp(`<${tagName}\\b([^>]*)\\/?>(?![\\s\\S]*<${tagName}\\b)`, 'i'))
+
+  if (!match) {
+    return {}
+  }
+
+  return parseCustomTagAttributes(match[1])
+}
+
+const createImageTokenData = (mediaHtml = '', options = {}) => {
+  const {
+    captionHtml = '',
+    fallbackCaptionFromAlt = false
+  } = options
+  const attrs = extractTagAttributes(mediaHtml, 'img')
+  const alt = decodeHtmlEntities(attrs.alt || '')
+  const title = decodeHtmlEntities(attrs.title || '')
+
+  return {
+    tag: 'image',
+    content: String(mediaHtml).trim(),
+    alt,
+    title,
+    captionHtml: captionHtml !== ''
+      ? captionHtml
+      : (fallbackCaptionFromAlt ? escapeHtml(alt) : '')
+  }
+}
+
+const parseStandaloneImageToken = (content = '') => {
+  const trimmed = String(content).trim()
+
+  if (!trimmed.match(/^<img\b[^>]*\/?>(?:\s*)$/i)) {
+    return null
+  }
+
+  return createImageTokenData(trimmed, {
+    fallbackCaptionFromAlt: true
+  })
+}
+
+const parseFigureImageToken = (content = '') => {
+  const trimmed = String(content).trim()
+
+  if (!trimmed.match(/^<figure\b[\s\S]*<\/figure>$/i)) {
+    return null
+  }
+
+  const figureBody = trimmed
+    .replace(/^<figure\b[^>]*>/i, '')
+    .replace(/<\/figure>$/i, '')
+    .trim()
+  const figcaptionMatch = figureBody.match(/<figcaption\b[^>]*>([\s\S]*?)<\/figcaption>/i)
+  const mediaBody = figcaptionMatch
+    ? figureBody.replace(figcaptionMatch[0], '').trim()
+    : figureBody
+  const pictureMatch = mediaBody.match(/^<picture\b[\s\S]*?<\/picture>$/i)
+  const imgMatch = pictureMatch
+    ? pictureMatch[0].match(/<img\b[^>]*\/?>/i)
+    : mediaBody.match(/^<img\b[^>]*\/?>$/i)
+
+  if (!imgMatch) {
+    return null
+  }
+
+  const mediaHtml = pictureMatch ? pictureMatch[0] : imgMatch[0]
+
+  return createImageTokenData(mediaHtml, {
+    captionHtml: figcaptionMatch ? figcaptionMatch[1].trim() : ''
+  })
+}
+
 const parseFenceLanguage = (raw = '') => {
   const cleaned = String(raw)
     .replace(/:[^;]*;/g, ' ')
@@ -378,10 +526,19 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
   })
 
   const { source: sourceWithQuickLinks, quickLinksMap } = extractQuickLinksBlocks(sourceWithExpandables)
+  const { source: sourceWithFiles, fileMap } = extractFileBlocks(sourceWithQuickLinks)
+
+  fileMap.forEach((data, marker) => {
+    fileMap.set(marker, {
+      ...data,
+      caption: restoreShieldedCodeSegments(data.caption, codeSegmentsMap)
+    })
+  })
+
   const markdown = createMarkdownBlockParser()
   const markdownInline = createMarkdownInlineParser()
   const markdownEnv = {}
-  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithQuickLinks, codeSegmentsMap), markdownEnv)
+  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithFiles, codeSegmentsMap), markdownEnv)
   const tokens = []
 
   let level = 0
@@ -520,7 +677,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
       }
 
       switch (element.type) {
-        case 'inline':
+        case 'inline': {
           const anchorId = getHeadingAnchorId(markdown, tag, element, markdownEnv, parserState)
 
           if (expandableMap.has(element.content.trim())) {
@@ -549,6 +706,34 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
             break
           }
 
+          if (fileMap.has(element.content.trim())) {
+            const data = fileMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'file',
+              map: element.map,
+              src: data.src,
+              title: data.title || getFileTitleFromSrc(data.src),
+              size: data.size,
+              caption: data.caption !== ''
+                ? markdownInline.renderInline(data.caption, markdownEnv)
+                : ''
+            })
+            break
+          }
+
+          if (tag === 'p') {
+            const imageToken = parseStandaloneImageToken(element.content)
+
+            if (imageToken !== null) {
+              tokens.push({
+                ...imageToken,
+                map: element.map
+              })
+              break
+            }
+          }
+
           tokens.push({
             tag,
             map: element.map,
@@ -557,6 +742,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
             info: element.info
           })
           break
+        }
 
         case 'fence':
           pushSourceCodeToken(tokens, element, parserState)
@@ -569,36 +755,59 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
           })
           break
 
-        case 'html_block':
+        case 'html_block': {
+          const figureImageToken = parseFigureImageToken(element.content)
+
+          if (figureImageToken !== null) {
+            tokens.push({
+              ...figureImageToken,
+              map: element.map
+            })
+            break
+          }
+
           tokens.push({
             tag: 'html',
             content: element.content
           })
           break
+        }
       }
-    } else if (level === 1) {
+    } else if (level > 0) {
       const parent = tokens[tokens.length - 1]
 
       switch (element.type) {
         case 'bullet_list_open':
-          tokens.push({
-            tag: 'ul',
-            content: ''
-          })
+          if (level === 1) {
+            tokens.push({
+              tag: 'ul',
+              content: ''
+            })
+          } else {
+            parent.content += '<ul>'
+          }
           break
 
         case 'ordered_list_open':
-          tokens.push({
-            tag: 'ol',
-            content: ''
-          })
+          if (level === 1) {
+            tokens.push({
+              tag: 'ol',
+              content: ''
+            })
+          } else {
+            parent.content += '<ol>'
+          }
           break
 
         case 'table_open':
-          tokens.push({
-            tag: 'table',
-            content: ''
-          })
+          if (level === 1) {
+            tokens.push({
+              tag: 'table',
+              content: ''
+            })
+          } else {
+            parent.content += '<table>'
+          }
           break
 
         case 'list_item_open':
@@ -636,6 +845,24 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
           parent.content += '</li>'
           break
 
+        case 'bullet_list_close':
+          if (level > 1) {
+            parent.content += '</ul>'
+          }
+          break
+
+        case 'ordered_list_close':
+          if (level > 1) {
+            parent.content += '</ol>'
+          }
+          break
+
+        case 'table_close':
+          if (level > 1) {
+            parent.content += '</table>'
+          }
+          break
+
         case 'thead_close':
           parent.content += '</thead>'
           break

package/src/i18n/languages/en-US.hjson

@@ -38,6 +38,13 @@
     copied: 'Copied!',
     viewAsMarkdown: 'View as Markdown',
     viewAsMarkdownCaption: 'View this page as plain text',
+    file: {
+      label: 'File',
+      defaultTitle: 'Download file',
+      external: 'External file',
+      download: 'Download',
+      open: 'Open'
+    },
     openInChatGPT: 'Open in ChatGPT',
     openInChatGPTCaption: 'Ask ChatGPT about this page',
     openInClaude: 'Open in Claude',

package/src/i18n/languages/pt-BR.hjson

@@ -37,6 +37,13 @@
     copied: 'Copiado!',
     viewAsMarkdown: 'Ver como Markdown',
     viewAsMarkdownCaption: 'Ver esta página como texto simples',
+    file: {
+      label: 'Arquivo',
+      defaultTitle: 'Baixar arquivo',
+      external: 'Arquivo externo',
+      download: 'Baixar',
+      open: 'Abrir'
+    },
     openInChatGPT: 'Abrir no ChatGPT',
     openInChatGPTCaption: 'Pergunte ao ChatGPT sobre esta página',
     openInClaude: 'Abrir no Claude',

package/src/pages/guide/i18n-and-markdown.overview.en-US.md

@@ -45,7 +45,7 @@ See the dedicated manual pages for block-by-block reference:
 
 - [Paragraphs](/manual/content/blocks/paragraphs/overview/), [Headings](/manual/content/blocks/headings/overview/), [Unordered lists](/manual/content/blocks/unordered-lists/overview/), [Ordered lists](/manual/content/blocks/ordered-lists/overview/)
 - [Hints](/manual/content/blocks/hints/overview/), [Quote](/manual/content/blocks/quotes/overview/), [Code blocks](/manual/content/blocks/code-blocks/overview/), [Mermaid diagrams](/manual/content/blocks/mermaid-diagrams/overview/)
-- [Images](/manual/content/blocks/images/overview/), [Math & TeX](/manual/content/blocks/math-and-tex/overview/), [Expandable](/manual/content/blocks/expandable/overview/), [Tables](/manual/content/blocks/tables/overview/), [Raw HTML](/manual/content/blocks/raw-html/overview/), and [Quick Links](/manual/content/blocks/quick-links/overview/)
+- [Images](/manual/content/blocks/images/overview/), [Files](/manual/content/blocks/files/overview/), [Math & TeX](/manual/content/blocks/math-and-tex/overview/), [Expandable](/manual/content/blocks/expandable/overview/), [Tables](/manual/content/blocks/tables/overview/), [Raw HTML](/manual/content/blocks/raw-html/overview/), and [Quick Links](/manual/content/blocks/quick-links/overview/)
 
 ### Headings
 
@@ -132,6 +132,20 @@ Set `open="true"` when the block should start expanded.
 
 The expandable body supports paragraphs, lists, alerts, code blocks, Mermaid diagrams, tables, raw HTML, and quick links. Keep headings outside the expandable block in this first version, because headings inside the body are flattened to regular paragraphs to preserve the page ToC.
 
+### File Blocks
+
+Use `<d-file>` to publish downloadable attachments from repo-tracked files or external storage without leaving Markdown:
+
+```html
+<d-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
+Download the example attachment used in this manual.
+</d-file>
+```
+
+Store repo-tracked files under `public/files/` and prefer absolute site paths such as `/files/...`.
+
+`title` and `size` are optional. When `title` is omitted, the UI falls back to the file name from `src`. The caption body supports inline Markdown, and the same syntax also works with external URLs if you later move storage to R2 or another CDN.
+
 ## Adding a New Language
 
 1. Create `src/i18n/languages/xx-XX.hjson` with all UI translations

package/src/pages/guide/i18n-and-markdown.overview.pt-BR.md

@@ -45,7 +45,7 @@ Veja também as páginas dedicadas do manual para cada bloco:
 
 - [Parágrafos](/manual/content/blocks/paragraphs/overview/), [Títulos](/manual/content/blocks/headings/overview/), [Listas não ordenadas](/manual/content/blocks/unordered-lists/overview/), [Listas ordenadas](/manual/content/blocks/ordered-lists/overview/)
 - [Hints](/manual/content/blocks/hints/overview/), [Citação](/manual/content/blocks/quotes/overview/), [Blocos de código](/manual/content/blocks/code-blocks/overview/), [Diagramas Mermaid](/manual/content/blocks/mermaid-diagrams/overview/)
-- [Imagens](/manual/content/blocks/images/overview/), [Math & TeX](/manual/content/blocks/math-and-tex/overview/), [Expansível](/manual/content/blocks/expandable/overview/), [Tabelas](/manual/content/blocks/tables/overview/), [HTML bruto](/manual/content/blocks/raw-html/overview/) e [Quick Links](/manual/content/blocks/quick-links/overview/)
+- [Imagens](/manual/content/blocks/images/overview/), [Arquivos](/manual/content/blocks/files/overview/), [Math & TeX](/manual/content/blocks/math-and-tex/overview/), [Expansível](/manual/content/blocks/expandable/overview/), [Tabelas](/manual/content/blocks/tables/overview/), [HTML bruto](/manual/content/blocks/raw-html/overview/) e [Quick Links](/manual/content/blocks/quick-links/overview/)
 
 ### Títulos
 
@@ -132,6 +132,20 @@ Defina `open="true"` quando o bloco precisar começar aberto.
 
 O corpo do expansível suporta parágrafos, listas, alertas, blocos de código, diagramas Mermaid, tabelas, HTML bruto e quick links. Nesta primeira versão, mantenha títulos fora do bloco expansível, porque títulos dentro do corpo viram parágrafos comuns para preservar o ToC da página.
 
+### Blocos de Arquivo
+
+Use `<d-file>` para publicar anexos baixáveis a partir de arquivos versionados no repositório ou de storage externo sem sair do Markdown:
+
+```html
+<d-file src="/files/manual/release-checklist.txt" title="Checklist de release" size="1 KB">
+Baixe o anexo de exemplo usado neste manual.
+</d-file>
+```
+
+Guarde arquivos versionados no repositório em `public/files/` e prefira caminhos absolutos do site, como `/files/...`.
+
+`title` e `size` são opcionais. Quando `title` não é informado, a UI usa o nome do arquivo presente em `src`. O corpo do bloco funciona como legenda com Markdown inline, e a mesma sintaxe também aceita URLs externas caso você mova o storage para R2 ou outro CDN no futuro.
+
 ## Adicionando um Novo Idioma
 
 1. Crie `src/i18n/languages/xx-XX.hjson` com todas as traduções de UI

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

@@ -0,0 +1,27 @@
+## Overview
+
+Files render a download card directly inside Markdown so a page or subpage can publish attachments without leaving the normal authoring flow.
+
+They are useful for checklists, sample bundles, PDFs, release notes, and any other file that should be linked from the reading flow.
+
+## Markdown Syntax
+
+```html
+<d-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
+Download the example attachment used in this manual.
+</d-file>
+```
+
+You can also omit the caption body when the file name already provides enough context:
+
+```html
+<d-file src="/files/manual/release-checklist.txt" size="1 KB" />
+```
+
+## Notes
+
+- Store small repo-tracked attachments under `public/files/` and prefer absolute paths such as `/files/...`.
+- `src` is required. `title` and `size` are optional.
+- When `title` is omitted, the rendered card falls back to the file name from `src`.
+- The block body is rendered as an inline Markdown caption.
+- External URLs also work, so the same syntax can point to a future R2 bucket or another CDN.

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

@@ -0,0 +1,27 @@
+## Visão Geral
+
+Arquivos renderizam um card de download diretamente no Markdown para que uma page ou subpage publique anexos sem sair do fluxo normal de autoria.
+
+Eles são úteis para checklists, bundles de exemplo, PDFs, notas de release e qualquer outro arquivo que precise ficar no fluxo de leitura.
+
+## Sintaxe em Markdown
+
+```html
+<d-file src="/files/manual/release-checklist.txt" title="Checklist de release" size="1 KB">
+Baixe o anexo de exemplo usado neste manual.
+</d-file>
+```
+
+Você também pode omitir o corpo da legenda quando o nome do arquivo já fornece contexto suficiente:
+
+```html
+<d-file src="/files/manual/release-checklist.txt" size="1 KB" />
+```
+
+## Observações
+
+- Guarde anexos pequenos versionados no repositório em `public/files/` e prefira caminhos absolutos como `/files/...`.
+- `src` é obrigatório. `title` e `size` são opcionais.
+- Quando `title` não é informado, o card renderizado usa o nome do arquivo presente em `src`.
+- O corpo do bloco é renderizado como legenda com Markdown inline.
+- URLs externas também funcionam, então a mesma sintaxe pode apontar no futuro para um bucket R2 ou outro CDN.