fix: pickup root comments in template (#107)

* fix: pickup root comments in template

* fix: test propHandler

Author: elevatebart

src/parse-template.ts

@@ -5,6 +5,7 @@ import cacher from './utils/cacher'
 
 export interface TemplateParserOptions {
   functional: boolean
+  rootLeadingComment: string
 }
 
 export type Handler = (
@@ -25,8 +26,16 @@ export default function parseTemplate(
         ? pug.render(tpl.content, { filename: filePath })
         : tpl.content
     const ast = cacher(() => compile(template, { comments: true }).ast, template)
+    const rootLeadingCommentArray = /^<!--(.+)-->/.exec(template.trim())
+    const rootLeadingComment =
+      rootLeadingCommentArray && rootLeadingCommentArray.length > 1
+        ? rootLeadingCommentArray[1].trim()
+        : ''
     if (ast) {
-      traverse(ast, documentation, handlers, { functional: !!tpl.attrs.functional })
+      traverse(ast, documentation, handlers, {
+        functional: !!tpl.attrs.functional,
+        rootLeadingComment,
+      })
     }
   }
 }

src/template-handlers/__tests__/propHandler.ts

@@ -20,7 +20,7 @@ describe('slotHandler', () => {
       { comments: true },
     ).ast
     if (ast) {
-      traverse(ast, doc, [propHandler], { functional: true })
+      traverse(ast, doc, [propHandler], { functional: true, rootLeadingComment: '' })
       expect(doc.toObject().props).toMatchObject({ size: { type: { name: 'undefined' } } })
     } else {
       fail()
@@ -40,7 +40,7 @@ describe('slotHandler', () => {
       { comments: true },
     ).ast
     if (ast) {
-      traverse(ast, doc, [propHandler], { functional: true })
+      traverse(ast, doc, [propHandler], { functional: true, rootLeadingComment: '' })
       expect(doc.toObject().props).toMatchObject({ name: { type: { name: 'undefined' } } })
     } else {
       fail()
@@ -58,7 +58,7 @@ describe('slotHandler', () => {
       { comments: true },
     ).ast
     if (ast) {
-      traverse(ast, doc, [propHandler], { functional: true })
+      traverse(ast, doc, [propHandler], { functional: true, rootLeadingComment: '' })
       expect(doc.toObject().props).toBeUndefined()
     } else {
       fail()
@@ -76,7 +76,7 @@ describe('slotHandler', () => {
       { comments: true },
     ).ast
     if (ast) {
-      traverse(ast, doc, [propHandler], { functional: true })
+      traverse(ast, doc, [propHandler], { functional: true, rootLeadingComment: '' })
       expect(doc.toObject().props).toBeUndefined()
     } else {
       fail()

src/template-handlers/__tests__/slotHandler.ts

@@ -9,6 +9,28 @@ describe('slotHandler', () => {
     doc = new Documentation()
   })
 
+  it('should pick comments at the beginning of templates', () => {
+    const ast = compile(
+      [
+        '<slot name="first">',
+        '  <div>',
+        '    <h1>titleof the template</h1>',
+        '  </div>',
+        '</slot>',
+      ].join('\n'),
+      { comments: true },
+    ).ast
+    if (ast) {
+      traverse(ast, doc, [slotHandler], {
+        functional: false,
+        rootLeadingComment: '@slot first slot found',
+      })
+      expect(doc.toObject().slots.first).toMatchObject({ description: 'first slot found' })
+    } else {
+      fail()
+    }
+  })
+
   it('should pick comments before slots', () => {
     const ast = compile(
       [
@@ -21,7 +43,7 @@ describe('slotHandler', () => {
       { comments: true },
     ).ast
     if (ast) {
-      traverse(ast, doc, [slotHandler], { functional: false })
+      traverse(ast, doc, [slotHandler], { functional: false, rootLeadingComment: '' })
       expect(doc.toObject().slots.default).toMatchObject({ description: 'a default slot' })
     } else {
       fail()
@@ -40,7 +62,7 @@ describe('slotHandler', () => {
       { comments: true },
     ).ast
     if (ast) {
-      traverse(ast, doc, [slotHandler], { functional: false })
+      traverse(ast, doc, [slotHandler], { functional: false, rootLeadingComment: '' })
       expect(doc.toObject().slots.oeuf).toMatchObject({ description: 'a slot named oeuf' })
     } else {
       fail()

src/template-handlers/slotHandler.ts

@@ -1,7 +1,12 @@
 import { ASTElement, ASTNode } from 'vue-template-compiler'
 import { Documentation } from '../Documentation'
+import { TemplateParserOptions } from '../parse-template'
 
-export default function slotHandler(documentation: Documentation, templateAst: ASTElement) {
+export default function slotHandler(
+  documentation: Documentation,
+  templateAst: ASTElement,
+  options: TemplateParserOptions,
+) {
   if (templateAst.tag === 'slot') {
     const bindings = extractAndFilterAttr(templateAst.attrsMap)
     let name = 'default'
@@ -13,6 +18,7 @@ export default function slotHandler(documentation: Documentation, templateAst: A
     const slotDescriptor = documentation.getSlotDescriptor(name)
 
     slotDescriptor.bindings = bindings
+    let comment = ''
     if (templateAst.parent) {
       const slotSiblings: ASTNode[] = templateAst.parent.children
       // First find the position of the slot in the list
@@ -42,13 +48,17 @@ export default function slotHandler(documentation: Documentation, templateAst: A
             templateAst.parent.tag === 'slot' && templateAst.parent.children[0] === potentialComment
           )
         ) {
-          const comment = potentialComment.text.trim()
-          if (comment.search(/\@slot/) !== -1) {
-            slotDescriptor.description = comment.replace('@slot', '').trim()
-          }
+          comment = potentialComment.text.trim()
+
           break
         }
       }
+    } else if (options.rootLeadingComment.length) {
+      comment = options.rootLeadingComment
+    }
+
+    if (comment.length && comment.search(/\@slot/) !== -1) {
+      slotDescriptor.description = comment.replace('@slot', '').trim()
     }
   }
 }

tests/components/root-slot/Wrapper.vue

@@ -0,0 +1,8 @@
+<template>
+  <!-- @slot Use this slot default -->
+  <slot name="wrapper">
+    <button>
+      Click Me
+    </button>
+  </slot>
+<template>

tests/components/root-slot/root-slot.test.ts

@@ -0,0 +1,21 @@
+import * as path from 'path'
+import { ComponentDoc } from '../../../src/Documentation'
+import { parse } from '../../../src/main'
+
+const button = path.join(__dirname, './Wrapper.vue')
+let docButton: ComponentDoc
+
+describe('tests wrapper with root slot', () => {
+  beforeEach(done => {
+    docButton = parse(button)
+    done()
+  })
+
+  it('should have a slot.', () => {
+    expect(Object.keys(docButton.slots).length).toEqual(1)
+  })
+
+  it('should have a wrapper slot.', () => {
+    expect(docButton.slots.wrapper.description).toBe('Use this slot default')
+  })
+})