@docsector/docsector-reader 4.3.2 → 4.4.0

package/src/components/DPage.vue

@@ -2,18 +2,24 @@
 import { ref, computed, onMounted, onBeforeUnmount, nextTick, watch } from 'vue'
 import { useStore } from 'vuex'
 import { useRoute, useRouter } from 'vue-router'
+import { useI18n } from 'vue-i18n'
 import { useQuasar } from 'quasar'
+import docsectorConfig from 'docsector.config.js'
 
 import useNavigator from '../composables/useNavigator'
 import { getReadingProgressState } from '../composables/useReadingProgress'
+import { normalizeAiAssistantConfig } from '../ai-assistant/config'
+import { getAssistantRightRailState } from '../ai-assistant/layout'
 
 import DPageAnchor from './DPageAnchor.vue'
+import DAssistantPanel from './DAssistantPanel.vue'
 import DPageMeta from './DPageMeta.vue'
 
 const store = useStore()
 const router = useRouter()
 const route = useRoute()
 const $q = useQuasar()
+const { locale } = useI18n()
 
 const { scrolling, navigate } = useNavigator()
 
@@ -35,6 +41,8 @@ const pageMinHeight = ref('calc(100vh - 86px)')
 const submenuHeight = ref('36px')
 const pageBottomInset = ref('0px')
 const readingProgress = ref(getReadingProgressState())
+const assistantConfig = normalizeAiAssistantConfig(docsectorConfig)
+const assistantEnabled = assistantConfig.enabled === true
 
 const getPageScrollContainer = () => {
   return pageScrollArea.value?.$el?.querySelector('.q-scrollarea__container') || null
@@ -96,6 +104,11 @@ const layoutMeta = computed({
   get: () => store.state.layout.meta,
   set: (value) => store.commit('layout/setMeta', value)
 })
+const layoutAssistant = computed({
+  get: () => store.state.layout.assistant,
+  set: (value) => store.commit('layout/setAssistant', value)
+})
+const assistantWidth = computed(() => store.state.layout.assistantWidth || assistantConfig.ui.drawerWidth)
 const main = computed(() => {
   switch (store.state.page.relative) {
     case '/showcase':
@@ -109,14 +122,57 @@ const main = computed(() => {
 const shouldShowBackToTopControl = computed(() => {
   return props.showBackToTopControl && readingProgress.value.hasOverflow && readingProgress.value.isVisible
 })
+const rightRailState = computed(() => getAssistantRightRailState({
+  tocOpen: layoutMeta.value,
+  assistantOpen: assistantEnabled && layoutAssistant.value,
+  screenWidth: $q.screen.width,
+  assistantWidth: assistantWidth.value,
+  mobileBreakpoint: 768
+}))
+const rightRailOpen = computed(() => {
+  return !rightRailState.value.isMobile && (rightRailState.value.showToc || rightRailState.value.showAssistant)
+})
+const mobileAssistantOpen = computed({
+  get: () => assistantEnabled && rightRailState.value.isMobile && layoutAssistant.value,
+  set: (value) => { layoutAssistant.value = value }
+})
 const backToTopRightOffset = computed(() => {
-  return layoutMeta.value && !$q.screen.lt.md ? '332px' : '24px'
+  return rightRailState.value.backToTopRightOffset
+})
+const currentMarkdownUrl = computed(() => {
+  if (store.state.page.base === 'home') {
+    return `${window.location.origin}/Homepage.${locale.value}.md`
+  }
+
+  const path = route.path.replace(/\/+$/, '')
+  return `${window.location.origin}${path || '/homepage'}.md`
+})
+const currentPageTitle = computed(() => {
+  const data = route.matched?.[0]?.meta?.data || route.meta?.data || {}
+  return data?.[locale.value]?.title || data?.['*']?.title || data?.['en-US']?.title || ''
 })
 
 const toggleSectionsTree = () => {
   layoutMeta.value = !layoutMeta.value
 }
 
+const closeAssistant = () => {
+  layoutAssistant.value = false
+}
+
+const onAssistantResize = (value) => {
+  const maxWidth = Math.max(320, Math.min(620, Math.round($q.screen.width - 480)))
+  const clamped = Math.min(maxWidth, Math.max(320, Math.round(Number(value) || 0)))
+  store.commit('layout/setAssistantWidth', clamped)
+}
+
+const setRightRailOpen = (value) => {
+  if (!value) {
+    layoutMeta.value = false
+    layoutAssistant.value = false
+  }
+}
+
 const pActive = (relative) => {
   if (relative === '/' && (store.state.page.relative === relative || store.state.page.relative === '')) {
     return 'active'
@@ -341,7 +397,9 @@ watch(() => route.fullPath, () => {
           />
         </q-btn-group>
       </q-toolbar-title>
-      <q-btn class="d-submenu__toggle" @click="toggleSectionsTree" icon="account_tree" />
+      <q-btn class="d-submenu__toggle" :class="layoutMeta ? 'active' : null" @click="toggleSectionsTree" icon="account_tree">
+        <q-tooltip>{{ $t('page.edit.anchor') }}</q-tooltip>
+      </q-btn>
     </div>
   </q-toolbar>
 
@@ -383,9 +441,42 @@ watch(() => route.fullPath, () => {
     </q-btn>
   </div>
 
-  <q-drawer elevated show-if-above side="right" v-model="layoutMeta">
-    <d-page-anchor id="anchor" />
+  <q-drawer
+    v-if="!rightRailState.isMobile"
+    elevated
+    show-if-above
+    side="right"
+    :model-value="rightRailOpen"
+    :width="rightRailState.totalWidth || 308"
+    class="d-right-rail-drawer"
+    @update:model-value="setRightRailOpen"
+  >
+    <div class="d-right-rail">
+      <div v-if="rightRailState.showToc" class="d-right-rail__toc" :style="{ width: `${rightRailState.tocWidth}px` }">
+        <d-page-anchor id="anchor" />
+      </div>
+      <q-separator v-if="rightRailState.showToc && rightRailState.showAssistant" vertical />
+      <d-assistant-panel
+        v-if="rightRailState.showAssistant"
+        class="d-right-rail__assistant"
+        :style="{ width: `${rightRailState.assistantWidth}px` }"
+        :context-title="currentPageTitle"
+        :markdown-url="currentMarkdownUrl"
+        :width="rightRailState.assistantWidth"
+        resizable
+        @resize="onAssistantResize"
+        @close="closeAssistant"
+      />
+    </div>
   </q-drawer>
+
+  <q-dialog v-if="assistantEnabled" v-model="mobileAssistantOpen" maximized>
+    <d-assistant-panel
+      :context-title="currentPageTitle"
+      :markdown-url="currentMarkdownUrl"
+      @close="closeAssistant"
+    />
+  </q-dialog>
 </q-page-container>
 </template>
 
@@ -454,10 +545,29 @@ watch(() => route.fullPath, () => {
     border-radius: 0
     margin-right: 0
 
+    &.active
+      background: rgba(255, 255, 255, 0.16)
+
   .on-left
     margin-right: 5px
   .toolbar-container
     overflow: visible
+
+.d-right-rail
+  height: 100%
+  display: flex
+  min-width: 0
+  overflow: hidden
+
+  &__toc
+    height: 100%
+    min-width: 0
+    overflow: auto
+
+  &__assistant
+    height: 100%
+    min-width: 320px
+    flex: 0 0 auto
     padding: 0
   .q-btn-group
     box-shadow: none

package/src/components/DPageAnchor.vue

@@ -15,6 +15,8 @@ const { t } = useI18n()
 const { navigate, anchor, selected: navigatorSelected } = useNavigator()
 
 const scrolling = ref(null)
+const enableScrollingTimeout = ref(null)
+const initialAnchorTimeout = ref(null)
 
 const nodes = computed(() => store.getters['page/nodes'])
 const expanded = computed({
@@ -77,13 +79,13 @@ watch(selected, () => {
 onMounted(() => {
   store.commit('layout/setMetaToggle', true)
 
-  setTimeout(() => {
+  enableScrollingTimeout.value = setTimeout(() => {
     store.commit('page/setScrolling', true)
   }, 1000)
 
   const id = route.hash.replace(/^#+/g, '')
   if (id) {
-    setTimeout(() => {
+    initialAnchorTimeout.value = setTimeout(() => {
       anchor(route.hash)
     }, 500)
   }
@@ -94,13 +96,15 @@ onBeforeUnmount(() => {
     clearTimeout(scrolling.value)
   }
 
-  store.commit('layout/setMetaToggle', false)
+  if (enableScrollingTimeout.value) {
+    clearTimeout(enableScrollingTimeout.value)
+  }
 
-  store.commit('page/resetAnchor')
-  store.commit('page/resetAnchors')
-  store.commit('page/resetNodes')
+  if (initialAnchorTimeout.value) {
+    clearTimeout(initialAnchorTimeout.value)
+  }
 
-  store.commit('page/setScrolling', false)
+  store.commit('layout/setMetaToggle', false)
 })
 </script>
 

package/src/components/DPageRichContent.vue

@@ -0,0 +1,105 @@
+<script>
+import { defineComponent, h, onMounted, onUpdated, ref } from 'vue'
+import { copyToClipboard, useQuasar } from 'quasar'
+import { useI18n } from 'vue-i18n'
+
+import {
+  decorateInlineCodeCopyTargets,
+  getInlineCodeCopyTarget
+} from './inline-code-copy'
+
+export default defineComponent({
+  name: 'DPageRichContent',
+
+  props: {
+    tag: {
+      type: String,
+      default: 'div'
+    },
+    html: {
+      type: String,
+      default: ''
+    },
+    attrs: {
+      type: Object,
+      default: null
+    }
+  },
+
+  setup(props) {
+    const rootRef = ref(null)
+    const $q = useQuasar()
+    const { t } = useI18n()
+
+    const syncInlineCodeTargets = () => {
+      decorateInlineCodeCopyTargets(rootRef.value, t('page.copyInlineCode'))
+    }
+
+    const notifyCopied = () => {
+      $q.notify({
+        message: t('page.copied'),
+        color: 'positive',
+        textColor: 'white',
+        icon: 'check',
+        position: 'top',
+        timeout: 1200
+      })
+    }
+
+    const copyInlineCode = (element) => {
+      const text = String(element?.textContent || '').trim()
+      if (!text) return
+
+      copyToClipboard(text)
+        .then(notifyCopied)
+        .catch(() => {})
+    }
+
+    const handleInlineCodeClick = (event) => {
+      const code = getInlineCodeCopyTarget(event.target, rootRef.value)
+      if (!code) return
+
+      event.preventDefault()
+      copyInlineCode(code)
+    }
+
+    const handleInlineCodeKeydown = (event) => {
+      if (event.key !== 'Enter' && event.key !== ' ') {
+        return
+      }
+
+      const code = getInlineCodeCopyTarget(event.target, rootRef.value)
+      if (!code) return
+
+      event.preventDefault()
+      copyInlineCode(code)
+    }
+
+    onMounted(syncInlineCodeTargets)
+    onUpdated(syncInlineCodeTargets)
+
+    return () => h(props.tag, {
+      ...(props.attrs || {}),
+      ref: rootRef,
+      class: ['d-page-rich-content', props.attrs?.class],
+      innerHTML: props.html,
+      onClick: handleInlineCodeClick,
+      onKeydown: handleInlineCodeKeydown
+    })
+  }
+})
+</script>
+
+<style scoped lang="sass">
+.d-page-rich-content
+  :deep(.d-copyable-inline-code)
+    cursor: copy
+    transition: background-color 0.15s ease, outline-color 0.15s ease
+
+    &:hover
+      background-color: rgba(25, 118, 210, 0.14)
+
+    &:focus-visible
+      outline: 2px solid currentColor
+      outline-offset: 2px
+</style>

package/src/components/DPageTokens.vue

@@ -23,6 +23,7 @@ import DH3 from './DH3.vue'
 import DH4 from './DH4.vue'
 import DH5 from './DH5.vue'
 import DH6 from './DH6.vue'
+import DPageRichContent from './DPageRichContent.vue'
 import DBlockSourceCode from './DBlockSourceCode.vue'
 import DBlockMermaidDiagram from './DBlockMermaidDiagram.vue'
 import DBlockBlockquote from './DBlockBlockquote.vue'
@@ -71,28 +72,34 @@ import DBlockApi from './DBlockApi.vue'
     :value="token.content"
   />
 
-  <ul
+  <d-page-rich-content
     v-else-if="token.tag === 'ul'"
-    v-bind="token.attrs || {}"
-    v-html="token.content"
-  ></ul>
-  <ol
+    tag="ul"
+    :attrs="token.attrs"
+    :html="token.content"
+  />
+  <d-page-rich-content
     v-else-if="token.tag === 'ol'"
-    v-bind="token.attrs || {}"
-    v-html="token.content"
-  ></ol>
+    tag="ol"
+    :attrs="token.attrs"
+    :html="token.content"
+  />
 
   <div
     v-else-if="token.tag === 'table'"
     class="d-table-wrapper"
   >
-    <table v-html="token.content"></table>
+    <d-page-rich-content
+      tag="table"
+      :html="token.content"
+    />
   </div>
 
-  <div
+  <d-page-rich-content
     v-else-if="token.tag === 'html'"
-    v-html="token.content"
-  ></div>
+    tag="div"
+    :html="token.content"
+  />
 
   <d-block-image
     v-else-if="token.tag === 'image'"
@@ -100,16 +107,20 @@ import DBlockApi from './DBlockApi.vue'
     :caption-html="token.captionHtml"
   />
 
-  <p
+  <d-page-rich-content
     v-else-if="token.tag === 'p'"
-    v-html="token.content"
-  ></p>
+    tag="p"
+    :html="token.content"
+  />
 
   <d-block-blockquote
     v-else-if="token.tag === 'blockquote'"
     :message="token.alertType"
   >
-    <div v-html="token.content"></div>
+    <d-page-rich-content
+      tag="div"
+      :html="token.content"
+    />
   </d-block-blockquote>
 
   <d-block-file

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

@@ -1,3 +1,5 @@
+import quasarApiExtends from './quasar-api-extends.json'
+
 const defaultInnerTabName = '__default'
 const fallbackCategoryName = 'general'
 
@@ -9,6 +11,78 @@ const isSupportedTopLevelSection = (value) => {
   return typeof value === 'string' || isPlainObject(value)
 }
 
+const mergeEntries = (baseValue, overrideValue) => {
+  if (!isPlainObject(baseValue) || !isPlainObject(overrideValue)) {
+    return overrideValue === undefined ? baseValue : overrideValue
+  }
+
+  const acc = {
+    ...baseValue
+  }
+
+  Object.entries(overrideValue).forEach(([key, value]) => {
+    acc[key] = isPlainObject(value) && isPlainObject(baseValue[key])
+      ? mergeEntries(baseValue[key], value)
+      : value
+  })
+
+  return acc
+}
+
+const resolveExtendsSource = (extendName = '', preferredSection = '') => {
+  const normalizedName = String(extendName || '').trim()
+
+  if (normalizedName === '') {
+    return undefined
+  }
+
+  if (isPlainObject(quasarApiExtends?.[preferredSection]?.[normalizedName])) {
+    return quasarApiExtends[preferredSection][normalizedName]
+  }
+
+  return Object.values(quasarApiExtends || {}).find((sectionEntries) => {
+    return isPlainObject(sectionEntries?.[normalizedName])
+  })?.[normalizedName]
+}
+
+const resolveExtendedEntries = (value, preferredSection = '', seen = new Set()) => {
+  if (Array.isArray(value)) {
+    return value.map((entry) => resolveExtendedEntries(entry, preferredSection, seen))
+  }
+
+  if (!isPlainObject(value)) {
+    return value
+  }
+
+  const extendName = typeof value.extends === 'string' ? value.extends.trim() : ''
+  const seenKey = `${preferredSection}:${extendName}`
+  const baseValue = extendName !== '' && !seen.has(seenKey)
+    ? resolveExtendsSource(extendName, preferredSection)
+    : undefined
+  const nextSeen = new Set(seen)
+
+  if (extendName !== '') {
+    nextSeen.add(seenKey)
+  }
+
+  const currentValue = {}
+
+  Object.entries(value).forEach(([key, entryValue]) => {
+    if (key === 'extends') {
+      return
+    }
+
+    currentValue[key] = resolveExtendedEntries(entryValue, preferredSection, nextSeen)
+  })
+
+  return mergeEntries(
+    baseValue === undefined
+      ? {}
+      : resolveExtendedEntries(baseValue, preferredSection, nextSeen),
+    currentValue
+  )
+}
+
 const getEntryCategories = (entry = {}) => {
   const raw = String(entry?.category || '').trim()
 
@@ -296,7 +370,9 @@ export const createApiBlockModel = (sourceName = '', apiDocument = {}) => {
   const apiSections = {}
 
   Object.entries(apiSectionsRaw).forEach(([sectionName, sectionValue]) => {
-    const sanitizedValue = pruneInternalEntries(sectionValue)
+    const sanitizedValue = pruneInternalEntries(
+      resolveExtendedEntries(sectionValue, sectionName)
+    )
 
     if (sanitizedValue !== undefined && isSupportedTopLevelSection(sanitizedValue)) {
       apiSections[sectionName] = sanitizedValue

package/src/components/inline-code-copy.js

@@ -0,0 +1,58 @@
+export const INLINE_CODE_COPY_ATTRIBUTE = 'data-docsector-inline-code-copy'
+export const INLINE_CODE_COPY_CLASS = 'd-copyable-inline-code'
+export const INLINE_CODE_COPY_SELECTOR = `[${INLINE_CODE_COPY_ATTRIBUTE}]`
+
+export const installInlineCodeCopyRenderer = (markdown) => {
+  const originalRender = markdown.renderer.rules.code_inline
+
+  markdown.renderer.rules.code_inline = (tokens, idx, options, env, self) => {
+    const token = tokens[idx]
+
+    token.attrJoin('class', INLINE_CODE_COPY_CLASS)
+    token.attrSet(INLINE_CODE_COPY_ATTRIBUTE, '')
+    token.attrSet('role', 'button')
+    token.attrSet('tabindex', '0')
+
+    if (typeof originalRender === 'function') {
+      return originalRender(tokens, idx, options, env, self)
+    }
+
+    return `<code${self.renderAttrs(token)}>${markdown.utils.escapeHtml(token.content)}</code>`
+  }
+
+  return markdown
+}
+
+export const decorateInlineCodeCopyTargets = (container, label = '') => {
+  if (!container || typeof container.querySelectorAll !== 'function') {
+    return
+  }
+
+  const normalizedLabel = String(label || '').trim()
+
+  container.querySelectorAll(INLINE_CODE_COPY_SELECTOR).forEach((element) => {
+    if (normalizedLabel) {
+      element.setAttribute('title', normalizedLabel)
+      element.setAttribute('aria-label', normalizedLabel)
+    }
+  })
+}
+
+export const getInlineCodeCopyTarget = (target, container) => {
+  const element = target?.nodeType === 3 ? target.parentElement : target
+
+  if (!element || typeof element.closest !== 'function') {
+    return null
+  }
+
+  const code = element.closest(INLINE_CODE_COPY_SELECTOR)
+  if (!code) {
+    return null
+  }
+
+  if (container && typeof container.contains === 'function' && !container.contains(code)) {
+    return null
+  }
+
+  return code
+}

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

@@ -5,6 +5,8 @@ import katex from 'katex'
 import taskLists from 'markdown-it-task-lists'
 import texmath from 'markdown-it-texmath'
 
+import { installInlineCodeCopyRenderer } from './inline-code-copy'
+
 const ALERT_MESSAGE_TYPES = new Set([
   'note',
   'tip',
@@ -850,9 +852,9 @@ const renderInlineToken = (markdown, markdownInline, element, env) => {
 }
 
 const createMarkdownBlockParser = () => {
-  const markdown = installMathSupport(new MarkdownIt({
+  const markdown = installInlineCodeCopyRenderer(installMathSupport(new MarkdownIt({
     html: true
-  }))
+  })))
 
   markdown.use(attrs, {
     leftDelimiter: ':',
@@ -869,9 +871,9 @@ const createMarkdownBlockParser = () => {
 }
 
 const createMarkdownInlineParser = () => {
-  return installMathSupport(new MarkdownIt({
+  return installInlineCodeCopyRenderer(installMathSupport(new MarkdownIt({
     html: true
-  }))
+  })) )
 }
 
 const normalizePageSectionSource = (source = '') => {