fix hover support and refactor getsnippetdefinition

Author: EvilGenius13

.changeset/beige-boxes-lay.md

@@ -0,0 +1,13 @@
+---
+'@shopify/theme-language-server-common': minor
+---
+
+Add hover support for @example in liquid doc tags
+EX:
+
+```liquid
+{% doc %}
+  @example
+  {{ product }}
+{% enddoc %}
+```

packages/theme-language-server-common/src/hover/providers/RenderSnippetHoverProvider.spec.ts

@@ -16,31 +16,41 @@ describe('Module: RenderSnippetHoverProvider', async () => {
           name: 'title',
           description: 'The title of the product',
           type: 'string',
+          nodeType: 'param',
         },
         {
           name: 'border-radius',
           description: 'The border radius in px',
           type: 'number',
+          nodeType: 'param',
         },
         {
           name: 'no-type',
           description: 'This parameter has no type',
           type: null,
+          nodeType: 'param',
         },
         {
           name: 'no-description',
           description: null,
           type: 'string',
+          nodeType: 'param',
         },
         {
           name: 'no-type-or-description',
           description: null,
           type: null,
+          nodeType: 'param',
         },
       ],
       examples: [
         {
           content: '{{ product }}',
+          nodeType: 'example',
+        },
+        {
+          content: '{{ product.title }}',
+          nodeType: 'example',
         },
       ],
     },
@@ -68,10 +78,10 @@ describe('Module: RenderSnippetHoverProvider', async () => {
   });
 
   describe('hover', () => {
-    it('should return snippet definition with all parameters', async () => {
+    it('should return snippet definition with all parameters and examples', async () => {
       await expect(provider).to.hover(
         `{% render 'product-car█d' %}`,
-        '### product-card\n\n**Parameters:**\n- `title`: string - The title of the product\n- `border-radius`: number - The border radius in px\n- `no-type` - This parameter has no type\n- `no-description`: string\n- `no-type-or-description`\n\n**Examples:**\n\`\`\`liquid\n{{ product }}\n\`\`\`',
+        '### product-card\n\n**Parameters:**\n- `title`: string - The title of the product\n- `border-radius`: number - The border radius in px\n- `no-type` - This parameter has no type\n- `no-description`: string\n- `no-type-or-description`\n\n**Examples:**\n```liquid\n{{ product }}\n```\n```liquid\n{{ product.title }}\n```',
       );
     });
 

packages/theme-language-server-common/src/hover/providers/RenderSnippetHoverProvider.ts

@@ -62,7 +62,7 @@ export class RenderSnippetHoverProvider implements BaseHoverProvider {
 
     if (liquidDoc.examples?.length) {
       const examples = liquidDoc.examples
-        ?.map(({ content }) => `\`\`\`liquid\n${content}\n\`\`\``)
+        ?.map(({ content }) => `\`\`\`liquid\n${content.trimStart().trimEnd()}\n\`\`\``)
         .join('\n');
 
       parts.push('', '**Examples:**', examples);

packages/theme-language-server-common/src/liquidDoc.spec.ts

@@ -47,26 +47,31 @@ describe('Unit: makeGetLiquidDocDefinitions', () => {
             name: 'firstParam',
             description: 'The first param',
             type: 'String',
+            nodeType: 'param',
           },
           {
             name: 'secondParam',
             description: 'The second param',
             type: 'Number',
+            nodeType: 'param',
           },
           {
             name: 'paramWithNoType',
             description: 'param with no type',
             type: null,
+            nodeType: 'param',
           },
           {
             name: 'paramWithOnlyName',
             description: null,
             type: null,
+            nodeType: 'param',
           },
           {
             name: 'paramWithNoDescription',
             description: null,
             type: 'Number',
+            nodeType: 'param',
           },
         ],
         examples: [],
@@ -87,7 +92,12 @@ describe('Unit: makeGetLiquidDocDefinitions', () => {
       name: 'product-card',
       liquidDoc: {
         parameters: [],
-        examples: [{ content: '\n          {{ product }}\n' }],
+        examples: [
+          {
+            content: '\n          {{ product }}\n',
+            nodeType: 'example',
+          },
+        ],
       },
     });
   });
@@ -106,7 +116,12 @@ describe('Unit: makeGetLiquidDocDefinitions', () => {
       name: 'product-card',
       liquidDoc: {
         parameters: [],
-        examples: [{ content: '\n          {{ product }}\n          {{ product.title }}\n' }],
+        examples: [
+          {
+            content: '\n          {{ product }}\n          {{ product.title }}\n',
+            nodeType: 'example',
+          },
+        ],
       },
     });
   });
@@ -124,8 +139,49 @@ describe('Unit: makeGetLiquidDocDefinitions', () => {
     expect(result).to.deep.equal({
       name: 'product-card',
       liquidDoc: {
-        parameters: [{ name: 'product', description: 'The product', type: 'String' }],
-        examples: [{ content: '\n          {{ product }} // This is an example\n' }],
+        parameters: [
+          {
+            name: 'product',
+            description: 'The product',
+            type: 'String',
+            nodeType: 'param',
+          },
+        ],
+        examples: [
+          {
+            content: '\n          {{ product }} // This is an example\n',
+            nodeType: 'example',
+          },
+        ],
+      },
+    });
+  });
+
+  it('should extract multiple examples from @example annotations', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @example
+          {{ product }}
+          @example
+          {{ product.title }}
+        {% enddoc %}
+      `);
+
+    const result = getSnippetDefinition(ast, 'product-card');
+    expect(result).to.deep.equal({
+      name: 'product-card',
+      liquidDoc: {
+        parameters: [],
+        examples: [
+          {
+            content: '\n          {{ product }}\n',
+            nodeType: 'example',
+          },
+          {
+            content: '\n          {{ product.title }}\n',
+            nodeType: 'example',
+          },
+        ],
       },
     });
   });

packages/theme-language-server-common/src/liquidDoc.ts

@@ -19,43 +19,48 @@ type LiquidDocDefinition = {
   examples?: LiquidDocExample[]; //  I don't think we need an array but maybe we'll allow multiple examples
 };
 
-export type LiquidDocParameter = {
+interface LiquidDocNode {
+  nodeType: 'param' | 'example';
+}
+
+export interface LiquidDocParameter extends LiquidDocNode {
   name: string;
   description: string | null;
   type: string | null;
-};
+  nodeType: 'param';
+}
 
-export type LiquidDocExample = {
+export interface LiquidDocExample extends LiquidDocNode {
   content: string;
-};
+  nodeType: 'example';
+}
 
 export function getSnippetDefinition(
   snippet: LiquidHtmlNode,
   snippetName: string,
 ): SnippetDefinition {
-  const parameters: LiquidDocParameter[] = visit<SourceCodeType.LiquidHtml, LiquidDocParameter>(
-    snippet,
-    {
-      LiquidDocParamNode(node: LiquidDocParamNode) {
-        return {
-          name: node.paramName.value,
-          description: node.paramDescription?.value ?? null,
-          type: node.paramType?.value ?? null,
-        };
-      },
+  const nodes: (LiquidDocParameter | LiquidDocExample)[] = visit<
+    SourceCodeType.LiquidHtml,
+    LiquidDocParameter | LiquidDocExample
+  >(snippet, {
+    LiquidDocParamNode(node: LiquidDocParamNode) {
+      return {
+        name: node.paramName.value,
+        description: node.paramDescription?.value ?? null,
+        type: node.paramType?.value ?? null,
+        nodeType: 'param',
+      };
     },
-  );
-
-  const examples: LiquidDocExample[] = visit<SourceCodeType.LiquidHtml, LiquidDocExample>(
-    snippet,
-    {
-      LiquidDocExampleNode(node: LiquidDocExampleNode) {
-        return {
-          content: node.exampleContent.value,
-        };
-      },
+    LiquidDocExampleNode(node: LiquidDocExampleNode) {
+      return {
+        content: node.exampleContent.value,
+        nodeType: 'example',
+      };
     },
-  );
+  });
+
+  const parameters = nodes.filter((node): node is LiquidDocParameter => node.nodeType === 'param');
+  const examples = nodes.filter((node): node is LiquidDocExample => node.nodeType === 'example');
 
   return {
     name: snippetName,