.github/PULL_REQUEST_TEMPLATE.md

@@ -24,6 +24,7 @@
     <!-- When that happens, the check's config should be updated/overridden in the theme-app-extension config -->
     <!-- see packages/node/configs/theme-app-extension.yml -->
     - [ ] If applicable, I've updated the `theme-app-extension.yml` config
+  - [ ] I've made a PR to update the [shopify.dev theme check docs](https://github.com/Shopify/shopify-dev/tree/main/content/storefronts/themes/tools/theme-check/checks) if applicable (link PR here).
 
 <!-- Public API changes, new features -->
 - [ ] I included a minor bump `changeset`

README.md

@@ -14,7 +14,7 @@
 
 <div align="center">
 
-🗣 [Slack](https://join.slack.com/t/shopifypartners/shared_invite/zt-sdr2quab-mGkzkttZ2hnVm0~8noSyvw) | 💬 [Discussions](https://github.com/Shopify/theme-tools/discussions) | 📝 [Changelog](./CHANGELOG.md)
+🗣 [Slack](https://join.slack.com/t/shopifypartners/shared_invite/zt-sdr2quab-mGkzkttZ2hnVm0~8noSyvw) | 📝 [Changelog](https://github.com/Shopify/theme-tools/blob/main/packages/vscode-extension/CHANGELOG.md)
 
 </div>
 

dev.yml

@@ -0,0 +1,8 @@
+name: theme-tools
+
+dev.edition: 2024
+
+up:
+  - node:
+      version: v22.14.0
+      yarn: v1.22.22

package.json

@@ -53,5 +53,6 @@
     "webpack": "^5.94.0",
     "webpack-cli": "^5.0.0",
     "webpack-dev-server": "^4.11.1"
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

packages/liquid-html-parser/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @shopify/liquid-html-parser
 
+## 2.5.0
+
+### Minor Changes
+
+- c4bbf3b5: [LiquidDoc]: Add parser support for @description annotations. These can be placed anywhere within the header, and can span numerous lines.
+- d9dbc265: - Support parsing incomplete content_for tags in completion context
+  - Support content_for param completion
+- 2db3047f: Support `render` param completion based on liquid docs
+
+  - If you defined liquid doc parameters on a snippet, they will appear as completion options
+    for parameters when rendered by a `render` tag.
+
+- 261c2958: Support liquid doc inner tags completion + hover
+
+  - `@param`, `@description`, `@example` will support code completion
+    whenever being typed inside of `doc` tag
+  - `@param`, `@description`, `@example` can be hovered to show their
+    help doc
+
 ## 2.4.0
 
 ### Minor Changes

packages/liquid-html-parser/grammar/liquid-html.ohm

@@ -133,14 +133,18 @@ Liquid <: Helpers {
     contentForType (argumentSeparatorOptionalComma contentForTagArgument) (space* ",")? space*
 
   contentForTagArgument = listOf<contentForNamedArgument<delimTag>, argumentSeparatorOptionalComma>
+  completionModeContentForTagArgument = listOf<contentForNamedArgument<delimTag>, argumentSeparatorOptionalComma> (argumentSeparator? (liquidVariableLookup<delimTag>))?
   contentForNamedArgument<delim> = (variableSegment ("." variableSegment)*) space* ":" space* (liquidExpression<delim>)
 
   contentForType = liquidString<delimTag>
 
   liquidTagInclude = liquidTagRule<"include", liquidTagRenderMarkup>
   liquidTagRender = liquidTagRule<"render", liquidTagRenderMarkup>
   liquidTagRenderMarkup =
-    snippetExpression renderVariableExpression? renderAliasExpression? (argumentSeparatorOptionalComma tagArguments) (space* ",")? space*
+    snippetExpression renderVariableExpression? renderAliasExpression? renderArguments
+
+  renderArguments = (argumentSeparatorOptionalComma tagArguments) (space* ",")? space*
+  completionModeRenderArguments = (argumentSeparatorOptionalComma tagArguments) (space* ",")? space* (argumentSeparator? liquidVariableLookup<delimTag> space*)?
   snippetExpression = liquidString<delimTag> | variableSegmentAsLookup
   renderVariableExpression = space+ ("for" | "with") space+ liquidExpression<delimTag>
   renderAliasExpression = space+ "as" space+ variableSegment
@@ -393,13 +397,18 @@ LiquidDoc <: Helpers {
   LiquidDocNode =
     | paramNode
     | exampleNode
+    | descriptionNode
     | fallbackNode
-
+    
   // By default, space matches new lines as well. We override it here to make writing rules easier.
   strictSpace = " " | "\t"
   // We use this as an escape hatch to stop matching TextNode and try again when one of these characters is encountered
   openControl:= "@" | end
 
+  descriptionNode = "@description" strictSpace* descriptionContent
+  descriptionContent = anyExceptStar<endOfDescription>
+  endOfDescription = strictSpace* openControl
+
   paramNode = "@param" strictSpace* paramType? strictSpace* (optionalParamName | paramName) (strictSpace* "-")? strictSpace* paramDescription
   paramType = "{" strictSpace* paramTypeContent strictSpace* "}"
   paramTypeContent = anyExceptStar<("}"| strictSpace)>
@@ -546,20 +555,44 @@ StrictLiquidHTML <: LiquidHTML {
 
 WithPlaceholderLiquid <: Liquid {
   liquidFilter<delim> := space* "|" space* identifier (space* ":" space* filterArguments<delim> (space* ",")?)?
+  liquidTagContentForMarkup :=
+    contentForType (argumentSeparatorOptionalComma completionModeContentForTagArgument) (space* ",")? space*
+  liquidTagRenderMarkup :=
+    snippetExpression renderVariableExpression? renderAliasExpression? completionModeRenderArguments
   liquidTagName := (letter | "█") (alnum | "_")*
   variableSegment := (letter | "_" | "█") (identifierCharacter | "█")*
+  liquidDoc :=
+    liquidDocStart
+      liquidDocBody
+    liquidDocEnd?
 }
 
 WithPlaceholderLiquidStatement <: LiquidStatement {
   liquidFilter<delim> := space* "|" space* identifier (space* ":" space* filterArguments<delim> (space* ",")?)?
+  liquidTagContentForMarkup :=
+    contentForType (argumentSeparatorOptionalComma completionModeContentForTagArgument) (space* ",")? space*
+  liquidTagRenderMarkup :=
+    snippetExpression renderVariableExpression? renderAliasExpression? completionModeRenderArguments
   liquidTagName := (letter | "█") (alnum | "_")*
   variableSegment := (letter | "_" | "█") (identifierCharacter | "█")*
+  liquidDoc :=
+    liquidDocStart
+      liquidDocBody
+    liquidDocEnd?
 }
 
 WithPlaceholderLiquidHTML <: LiquidHTML {
   liquidFilter<delim> := space* "|" space* identifier (space* ":" space* filterArguments<delim> (space* ",")?)?
+  liquidTagContentForMarkup :=
+    contentForType (argumentSeparatorOptionalComma completionModeContentForTagArgument) (space* ",")? space*
+  liquidTagRenderMarkup :=
+    snippetExpression renderVariableExpression? renderAliasExpression? completionModeRenderArguments
   liquidTagName := (letter | "█") (alnum | "_")*
   variableSegment := (letter | "_" | "█") (identifierCharacter | "█")*
   leadingTagNameTextNode := (letter | "█") (alnum | "-" | ":" | "█")*
   trailingTagNameTextNode := (alnum | "-" | ":" | "█")+
+  liquidDoc :=
+    liquidDocStart
+      liquidDocBody
+    liquidDocEnd?
 }

packages/liquid-html-parser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/liquid-html-parser",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Liquid HTML parser by Shopify",
   "author": "CP Clermont <cp.clermont@shopify.com>",
   "homepage": "https://github.com/Shopify/theme-tools/tree/main/packages/liquid-html-parser#readme",

packages/liquid-html-parser/src/stage-1-cst.spec.ts

@@ -6,8 +6,7 @@ import {
   LiquidCST,
   ConcreteLiquidTagLiquid,
 } from './stage-1-cst';
-import { BLOCKS, VOID_ELEMENTS } from './grammar';
-import { NamedTags } from './types';
+import { VOID_ELEMENTS } from './grammar';
 import { deepGet } from './utils';
 
 describe('Unit: Stage 1 (CST)', () => {
@@ -561,11 +560,11 @@ describe('Unit: Stage 1 (CST)', () => {
                 expectPath(cst, '0.markup.variable').to.equal(null);
               }
               expectPath(cst, '0.markup.alias').to.equal(alias);
-              expectPath(cst, '0.markup.args').to.have.lengthOf(namedArguments.length);
+              expectPath(cst, '0.markup.renderArguments').to.have.lengthOf(namedArguments.length);
               namedArguments.forEach(({ name, valueType }, i) => {
-                expectPath(cst, `0.markup.args.${i}.type`).to.equal('NamedArgument');
-                expectPath(cst, `0.markup.args.${i}.name`).to.equal(name);
-                expectPath(cst, `0.markup.args.${i}.value.type`).to.equal(valueType);
+                expectPath(cst, `0.markup.renderArguments.${i}.type`).to.equal('NamedArgument');
+                expectPath(cst, `0.markup.renderArguments.${i}.name`).to.equal(name);
+                expectPath(cst, `0.markup.renderArguments.${i}.value.type`).to.equal(valueType);
               });
               expectPath(cst, '0.whitespaceStart').to.equal(null);
               expectPath(cst, '0.whitespaceEnd').to.equal('-');
@@ -1237,7 +1236,7 @@ describe('Unit: Stage 1 (CST)', () => {
           expectPath(cst, '0.type').to.equal('LiquidRawTag');
           expectPath(cst, '0.name').to.equal('doc');
           expectPath(cst, '0.children.0.type').to.equal('LiquidDocExampleNode');
-          expectPath(cst, '0.children.0.exampleContent.value').to.equal('');
+          expectPath(cst, '0.children.0.content.value').to.equal('');
         });
 
         it('should parse example tag with content that has leading whitespace', () => {
@@ -1247,11 +1246,9 @@ describe('Unit: Stage 1 (CST)', () => {
           expectPath(cst, '0.name').to.equal('doc');
           expectPath(cst, '0.children.0.type').to.equal('LiquidDocExampleNode');
           expectPath(cst, '0.children.0.name').to.equal('example');
-          expectPath(cst, '0.children.0.exampleContent.value').to.equal('hello there');
-          expectPath(cst, '0.children.0.exampleContent.locStart').to.equal(
-            testStr.indexOf('hello there'),
-          );
-          expectPath(cst, '0.children.0.exampleContent.locEnd').to.equal(
+          expectPath(cst, '0.children.0.content.value').to.equal('hello there');
+          expectPath(cst, '0.children.0.content.locStart').to.equal(testStr.indexOf('hello there'));
+          expectPath(cst, '0.children.0.content.locEnd').to.equal(
             testStr.indexOf('hello there') + 'hello there'.length,
           );
         });
@@ -1268,7 +1265,7 @@ describe('Unit: Stage 1 (CST)', () => {
           expectPath(cst, '0.name').to.equal('doc');
           expectPath(cst, '0.children.0.type').to.equal('LiquidDocExampleNode');
           expectPath(cst, '0.children.0.name').to.equal('example');
-          expectPath(cst, '0.children.0.exampleContent.value').to.equal(
+          expectPath(cst, '0.children.0.content.value').to.equal(
             '\n          This is an example\n          It supports multiple lines\n',
           );
         });
@@ -1282,7 +1279,7 @@ describe('Unit: Stage 1 (CST)', () => {
           cst = toCST(testStr);
           expectPath(cst, '0.children.0.type').to.equal('LiquidDocExampleNode');
           expectPath(cst, '0.children.0.name').to.equal('example');
-          expectPath(cst, '0.children.0.exampleContent.value').to.equal(
+          expectPath(cst, '0.children.0.content.value').to.equal(
             '\n          This is an example\n',
           );
           expectPath(cst, '0.children.1.type').to.equal('LiquidDocParamNode');
@@ -1300,7 +1297,7 @@ describe('Unit: Stage 1 (CST)', () => {
           expectPath(cst, '0.name').to.equal('doc');
           expectPath(cst, '0.children.0.type').to.equal('LiquidDocExampleNode');
           expectPath(cst, '0.children.0.name').to.equal('example');
-          expectPath(cst, '0.children.0.exampleContent.value').to.equal(
+          expectPath(cst, '0.children.0.content.value').to.equal(
             'hello      there        my    friend\n          This is an example\n          It supports multiple lines\n',
           );
         });
@@ -1312,9 +1309,73 @@ describe('Unit: Stage 1 (CST)', () => {
         {% enddoc %}`;
           cst = toCST(testStr);
           expectPath(cst, '0.children.0.type').to.equal('LiquidDocExampleNode');
-          expectPath(cst, '0.children.0.exampleContent.value').to.equal('hello there\n');
+          expectPath(cst, '0.children.0.content.value').to.equal('hello there\n');
           expectPath(cst, '0.children.1.type').to.equal('LiquidDocExampleNode');
-          expectPath(cst, '0.children.1.exampleContent.value').to.equal('second example\n');
+          expectPath(cst, '0.children.1.content.value').to.equal('second example\n');
+        });
+
+        it('should parse @description node', () => {
+          const testStr = `{% doc %} @description {%- enddoc %}`;
+          cst = toCST(testStr);
+          expectPath(cst, '0.type').to.equal('LiquidRawTag');
+          expectPath(cst, '0.name').to.equal('doc');
+          expectPath(cst, '0.children.0.type').to.equal('LiquidDocDescriptionNode');
+          expectPath(cst, '0.children.0.content.value').to.equal('');
+        });
+
+        it('should parse @description node', () => {
+          const testStr = `{% doc %}
+          @description This is a description
+          @description This is a second description
+          {% enddoc %}`;
+          cst = toCST(testStr);
+          expectPath(cst, '0.children.0.type').to.equal('LiquidDocDescriptionNode');
+          expectPath(cst, '0.children.0.content.value').to.equal('This is a description\n');
+
+          expectPath(cst, '0.children.1.type').to.equal('LiquidDocDescriptionNode');
+          expectPath(cst, '0.children.1.content.value').to.equal('This is a second description\n');
+        });
+
+        it('should parse and strip whitespace from description tag with content that has leading whitespace', () => {
+          const testStr = `{% doc %} @description         hello there       {%- enddoc %}`;
+          cst = toCST(testStr);
+          expectPath(cst, '0.type').to.equal('LiquidRawTag');
+          expectPath(cst, '0.name').to.equal('doc');
+          expectPath(cst, '0.children.0.type').to.equal('LiquidDocDescriptionNode');
+          expectPath(cst, '0.children.0.name').to.equal('description');
+          expectPath(cst, '0.children.0.content.value').to.equal('hello there');
+          expectPath(cst, '0.children.0.content.locStart').to.equal(testStr.indexOf('hello there'));
+          expectPath(cst, '0.children.0.content.locEnd').to.equal(
+            testStr.indexOf('hello there') + 'hello there'.length,
+          );
+        });
+
+        it('should parse description node with whitespace and new lines', () => {
+          const testStr = `{% doc %}
+          @description hello      there        my    friend
+          This is a description
+          It supports multiple lines
+        {% enddoc %}`;
+          cst = toCST(testStr);
+          expectPath(cst, '0.type').to.equal('LiquidRawTag');
+          expectPath(cst, '0.name').to.equal('doc');
+          expectPath(cst, '0.children.0.type').to.equal('LiquidDocDescriptionNode');
+          expectPath(cst, '0.children.0.name').to.equal('description');
+          expectPath(cst, '0.children.0.content.value').to.equal(
+            'hello      there        my    friend\n          This is a description\n          It supports multiple lines\n',
+          );
+        });
+
+        it('should parse multiple description nodes', () => {
+          const testStr = `{% doc %}
+          @description hello there
+          @description second description
+        {% enddoc %}`;
+          cst = toCST(testStr);
+          expectPath(cst, '0.children.0.type').to.equal('LiquidDocDescriptionNode');
+          expectPath(cst, '0.children.0.content.value').to.equal('hello there\n');
+          expectPath(cst, '0.children.1.type').to.equal('LiquidDocDescriptionNode');
+          expectPath(cst, '0.children.1.content.value').to.equal('second description\n');
         });
       }
     });
@@ -1714,6 +1775,26 @@ describe('Unit: Stage 1 (CST)', () => {
       expectPath(cst, '0.markup.filters.0.args.1.type').to.equal('NamedArgument');
       expectPath(cst, '0.markup.filters.0.args.2.type').to.equal('VariableLookup');
     });
+
+    it('should parse incomplete parameters for content_for tags', () => {
+      const toCST = (source: string) => toLiquidHtmlCST(source, { mode: 'completion' });
+
+      cst = toCST(`{% content_for "blocks", id: 1, cl█ %}`);
+
+      expectPath(cst, '0.markup.type').to.equal('ContentForMarkup');
+      expectPath(cst, '0.markup.args.0.type').to.equal('NamedArgument');
+      expectPath(cst, '0.markup.args.1.type').to.equal('VariableLookup');
+    });
+
+    it('should parse incomplete parameters for render tags', () => {
+      const toCST = (source: string) => toLiquidHtmlCST(source, { mode: 'completion' });
+
+      cst = toCST(`{% render "example-snippet", id: 2, foo█ %}`);
+
+      expectPath(cst, '0.markup.type').to.equal('RenderMarkup');
+      expectPath(cst, '0.markup.renderArguments.0.type').to.equal('NamedArgument');
+      expectPath(cst, '0.markup.renderArguments.1.type').to.equal('VariableLookup');
+    });
   });
 
   function makeExpectPath(message: string) {