add @tokens-end comment block support

UX-and-I · Jun 28, 2022 · 4be7e04 · 4be7e04
1 parent a9d3f96
commit 4be7e04
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -21,6 +21,7 @@ Display design token documentation generated from your stylesheets and icon file
     - [Disable the addon panel](#disable-the-addon-panel)
     - [Token search visibility](#token-search-visibility)
     - [Specify a custom glob for your token files](#specify-a-custom-glob-for-your-token-files)
+    - [Preserve CSS variables](#preserve-css-variables)
   - [Design Token Doc Block](#design-token-doc-block)
   - [Browser support](#browser-support)
   - [Migration from v0.x.x and v1.x.x](#migration-from-v0xx-and-v1xx)
@@ -72,6 +73,14 @@ The last step is to annotate your design tokens with a category name and a prese
 
 The presenter controls how your token previews are rendered. See the next section for a complete list of available presenters. You can omit the presenter definition if you don't want to render a preview or no presenter works with your token.
 
+By default, a token category ends with the comment block of the next category. If you want to end a category block before the next category comment, you can insert a special comment to end the block early:
+
+```css
+/**
+  * @tokens-end
+  */
+```
+
 To list your svg icons, the addon parses your svg files searching for svg elements. **Important: Only svg elements with an `id` or `data-token-name` attribute are added to the token list.** You can provide descriptions and category names for your icons using the (optional) attributes `data-token-description` and `data-token-category`.
 
 ## Available presenters
@@ -157,7 +166,7 @@ For example:
 DESIGN_TOKEN_GLOB=**/*.tokens.{css,scss,less,svg}
 ```
 
-### CSS variables
+### Preserve CSS variables
 
 By default, the addon extracts values of CSS variables at build time. As a result, presenters use fixed values at runtime. This behavior might impose limitations in some scenarios:
 

diff --git a/addon/src/parsers/postcss.parser.ts b/addon/src/parsers/postcss.parser.ts
@@ -47,57 +47,64 @@ function determineCategories(
   sourceType: TokenSourceType,
   preserveCSSVars?: boolean
 ): Category[] {
-  const categoryComments = comments.filter((comment) =>
-    comment.text.includes('@tokens ')
+  const categoryComments = comments.filter(
+    (comment) =>
+      comment.text.includes('@tokens ') || comment.text.includes('@tokens-end')
   );
 
-  return categoryComments.map((comment, index) => {
-    const nextComment = categoryComments[index + 1];
-    const nameResults = /@tokens (.+)/g.exec(comment.text);
-    const presenterResults = /@presenter (.+)/g.exec(comment.text);
+  return categoryComments
+    .map<Category | undefined>((comment, index) => {
+      if (comment.text.includes('@tokens-end')) {
+        return undefined;
+      }
 
-    const presenter: TokenPresenter = presenterResults?.[1] as TokenPresenter;
+      const nextComment = categoryComments[index + 1];
+      const nameResults = /@tokens (.+)/g.exec(comment.text);
+      const presenterResults = /@presenter (.+)/g.exec(comment.text);
 
-    if (
-      presenter &&
-      !Object.values(TokenPresenter).includes(
-        (presenter || '') as TokenPresenter
-      )
-    ) {
-      throw new Error(`Presenter "${presenter}" is not valid.`);
-    }
+      const presenter: TokenPresenter = presenterResults?.[1] as TokenPresenter;
 
-    const range: CategoryRange = {
-      from: {
-        column: comment.source?.start?.column || 0,
-        line: comment.source?.start?.line || 0
-      },
-      to: nextComment?.prev()
-        ? {
-            column: nextComment.prev()?.source?.end?.column || 0,
-            line: nextComment.prev()?.source?.end?.line || 0
-          }
-        : undefined
-    };
-
-    const source = comment.source?.input.from || '';
-
-    return {
-      name: nameResults?.[1] || '',
-      presenter,
-      range,
-      source,
-      tokens: determineTokensForCategory(
-        source,
-        range,
-        declarations,
-        comments,
-        sourceType,
+      if (
+        presenter &&
+        !Object.values(TokenPresenter).includes(
+          (presenter || '') as TokenPresenter
+        )
+      ) {
+        throw new Error(`Presenter "${presenter}" is not valid.`);
+      }
+
+      const range: CategoryRange = {
+        from: {
+          column: comment.source?.start?.column || 0,
+          line: comment.source?.start?.line || 0
+        },
+        to: nextComment?.prev()
+          ? {
+              column: nextComment.prev()?.source?.end?.column || 0,
+              line: nextComment.prev()?.source?.end?.line || 0
+            }
+          : undefined
+      };
+
+      const source = comment.source?.input.from || '';
+
+      return {
+        name: nameResults?.[1] || '',
         presenter,
-        preserveCSSVars
-      )
-    };
-  });
+        range,
+        source,
+        tokens: determineTokensForCategory(
+          source,
+          range,
+          declarations,
+          comments,
+          sourceType,
+          presenter,
+          preserveCSSVars
+        )
+      };
+    })
+    .filter<Category>(isCategory);
 }
 
 function determineTokensForCategory(
@@ -266,3 +273,7 @@ async function getNodes(
 
   return { comments, declarations, keyframes };
 }
+
+function isCategory(object: any): object is Category {
+  return !!object && !!object.presenter;
+}
diff --git a/demo-webpack5/tokens.css b/demo-webpack5/tokens.css
@@ -32,11 +32,21 @@
   --b300: hsl(240, 100%, 70%);
   --b400: hsl(240, 100%, 60%);
   --b500: hsl(240, 100%, 50%);
+
+  /**
+  * @tokens-end
+  */
+
   --b600: hsl(240, 100%, 40%);
   --b700: hsl(240, 100%, 30%);
   --b800: hsl(240, 100%, 20%);
   --b900: hsl(240, 100%, 10%);
 
+  /**
+  * @tokens Colors
+  * @presenter Color
+  */
+
   --n100: hsl(0, 0%, 90%);
   --n200: hsl(0, 0%, 80%);
   --n300: hsl(0, 0%, 70%);