Add support for parsing parenthesized expressions (#2527)

nex3 · Goodwine · web-flow · commit d067c3a0dd77 · 2025-03-03T17:30:34.000-08:00
Co-authored-by: Carlos (Goodwine) &lt;2022649+Goodwine@users.noreply.github.com&gt;
diff --git a/pkg/sass-parser/CHANGELOG.md b/pkg/sass-parser/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 * Add support for parsing null literals.
 
+* Add support for parsing parenthesized expressions.
+
 ## 0.4.15
 
 * Add support for parsing list expressions.
diff --git a/pkg/sass-parser/lib/index.ts b/pkg/sass-parser/lib/index.ts
@@ -108,6 +108,11 @@ export {
   NumberExpressionProps,
   NumberExpressionRaws,
 } from './src/expression/number';
+export {
+  ParenthesizedExpression,
+  ParenthesizedExpressionProps,
+  ParenthesizedExpressionRaws,
+} from './src/expression/parenthesized';
 export {
   ImportList,
   ImportListObjectProps,
diff --git a/pkg/sass-parser/lib/src/expression/__snapshots__/parenthesized.test.ts.snap b/pkg/sass-parser/lib/src/expression/__snapshots__/parenthesized.test.ts.snap
@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`a parenthesized expression toJSON 1`] = `
+{
+  "inParens": <foo>,
+  "inputs": [
+    {
+      "css": "@#{(foo)}",
+      "hasBOM": false,
+      "id": "<input css _____>",
+    },
+  ],
+  "raws": {},
+  "sassType": "parenthesized",
+  "source": <1:4-1:9 in 0>,
+}
+`;
diff --git a/pkg/sass-parser/lib/src/expression/convert.ts b/pkg/sass-parser/lib/src/expression/convert.ts
@@ -15,6 +15,7 @@ import {ListExpression} from './list';
 import {MapExpression} from './map';
 import {NullExpression} from './null';
 import {NumberExpression} from './number';
+import {ParenthesizedExpression} from './parenthesized';
 import {StringExpression} from './string';
 
 /** The visitor to use to convert internal Sass nodes to JS. */
@@ -36,6 +37,8 @@ const visitor = sassInternal.createExpressionVisitor<Expression>({
   visitMapExpression: inner => new MapExpression(undefined, inner),
   visitNullExpression: inner => new NullExpression(undefined, inner),
   visitNumberExpression: inner => new NumberExpression(undefined, inner),
+  visitParenthesizedExpression: inner =>
+    new ParenthesizedExpression(undefined, inner),
 });
 
 /** Converts an internal expression AST node into an external one. */
diff --git a/pkg/sass-parser/lib/src/expression/from-props.ts b/pkg/sass-parser/lib/src/expression/from-props.ts
@@ -13,6 +13,7 @@ import {ListExpression} from './list';
 import {MapExpression} from './map';
 import {NullExpression} from './null';
 import {NumberExpression} from './number';
+import {ParenthesizedExpression} from './parenthesized';
 import {StringExpression} from './string';
 
 /** Constructs an expression from {@link ExpressionProps}. */
@@ -21,6 +22,7 @@ export function fromProps(props: ExpressionProps): Expression {
   if ('left' in props) return new BinaryOperationExpression(props);
   if ('separator' in props) return new ListExpression(props);
   if ('nodes' in props) return new MapExpression(props);
+  if ('inParens' in props) return new ParenthesizedExpression(props);
   if ('name' in props) {
     if (typeof props.name === 'string') {
       return new FunctionExpression(props as FunctionExpressionProps);
diff --git a/pkg/sass-parser/lib/src/expression/index.ts b/pkg/sass-parser/lib/src/expression/index.ts
@@ -18,6 +18,10 @@ import {ListExpression, ListExpressionProps} from './list';
 import {MapExpression, MapExpressionProps} from './map';
 import {NullExpression, NullExpressionProps} from './null';
 import {NumberExpression, NumberExpressionProps} from './number';
+import {
+  ParenthesizedExpression,
+  ParenthesizedExpressionProps,
+} from './parenthesized';
 import type {StringExpression, StringExpressionProps} from './string';
 
 /**
@@ -35,6 +39,7 @@ export type AnyExpression =
   | MapExpression
   | NullExpression
   | NumberExpression
+  | ParenthesizedExpression
   | StringExpression;
 
 /**
@@ -52,6 +57,7 @@ export type ExpressionType =
   | 'map'
   | 'null'
   | 'number'
+  | 'parenthesized'
   | 'string';
 
 /**
@@ -70,6 +76,7 @@ export type ExpressionProps =
   | MapExpressionProps
   | NullExpressionProps
   | NumberExpressionProps
+  | ParenthesizedExpressionProps
   | StringExpressionProps;
 
 /**
diff --git a/pkg/sass-parser/lib/src/expression/parenthesized.test.ts b/pkg/sass-parser/lib/src/expression/parenthesized.test.ts
@@ -0,0 +1,135 @@
+// Copyright 2025 Google Inc. Use of this source code is governed by an
+// MIT-style license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import {ParenthesizedExpression, StringExpression} from '../..';
+import * as utils from '../../../test/utils';
+
+describe('a parenthesized expression', () => {
+  let node: ParenthesizedExpression;
+  function describeNode(
+    description: string,
+    create: () => ParenthesizedExpression,
+  ): void {
+    describe(description, () => {
+      beforeEach(() => void (node = create()));
+
+      it('has sassType parenthesized', () =>
+        expect(node.sassType).toBe('parenthesized'));
+
+      it('has an expression', () =>
+        expect(node).toHaveStringExpression('inParens', 'foo'));
+    });
+  }
+
+  describeNode('parsed', () => utils.parseExpression('(foo)'));
+
+  describeNode(
+    'constructed manually',
+    () => new ParenthesizedExpression({inParens: {text: 'foo'}}),
+  );
+
+  describeNode('constructed from ExpressionProps', () =>
+    utils.fromExpressionProps({inParens: {text: 'foo'}}),
+  );
+
+  describe('assigned new', () => {
+    beforeEach(() => void (node = utils.parseExpression('(foo)')));
+
+    describe('expression', () => {
+      it("removes the old expression's parent", () => {
+        const oldInParens = node.inParens;
+        node.inParens = {text: 'zip'};
+        expect(oldInParens.parent).toBeUndefined();
+      });
+
+      it('assigns the expression explicitly', () => {
+        const inParens = new StringExpression({text: 'zip'});
+        node.inParens = inParens;
+        expect(node.inParens).toBe(inParens);
+        expect(node).toHaveStringExpression('inParens', 'zip');
+      });
+
+      it('assigns the expression as ExpressionProps', () => {
+        node.inParens = {text: 'zip'};
+        expect(node).toHaveStringExpression('inParens', 'zip');
+      });
+    });
+  });
+
+  describe('stringifies', () => {
+    beforeEach(() => void (node = utils.parseExpression('(foo)')));
+
+    it('without raws', () => expect(node.toString()).toBe('(foo)'));
+
+    it('with afterOpen', () => {
+      node.raws.afterOpen = '/**/';
+      expect(node.toString()).toBe('(/**/foo)');
+    });
+
+    it('with beforeClose', () => {
+      node.raws.beforeClose = '/**/';
+      expect(node.toString()).toBe('(foo/**/)');
+    });
+  });
+
+  describe('clone', () => {
+    let original: ParenthesizedExpression;
+    beforeEach(() => {
+      original = utils.parseExpression('(foo)');
+      // TODO: remove this once raws are properly parsed
+      original.raws.afterOpen = '  ';
+    });
+
+    describe('with no overrides', () => {
+      let clone: ParenthesizedExpression;
+      beforeEach(() => void (clone = original.clone()));
+
+      describe('has the same properties:', () => {
+        it('inParens', () =>
+          expect(clone).toHaveStringExpression('inParens', 'foo'));
+
+        it('raws', () => expect(clone.raws).toEqual({afterOpen: '  '}));
+
+        it('source', () => expect(clone.source).toBe(original.source));
+      });
+
+      describe('creates a new', () => {
+        it('self', () => expect(clone).not.toBe(original));
+
+        for (const attr of ['inParens', 'raws'] as const) {
+          it(attr, () => expect(clone[attr]).not.toBe(original[attr]));
+        }
+      });
+    });
+
+    describe('overrides', () => {
+      describe('inParens', () => {
+        it('defined', () =>
+          expect(
+            original.clone({inParens: {text: 'zip'}}),
+          ).toHaveStringExpression('inParens', 'zip'));
+
+        it('undefined', () =>
+          expect(original.clone({inParens: undefined})).toHaveStringExpression(
+            'inParens',
+            'foo',
+          ));
+      });
+
+      describe('raws', () => {
+        it('defined', () =>
+          expect(original.clone({raws: {beforeClose: '  '}}).raws).toEqual({
+            beforeClose: '  ',
+          }));
+
+        it('undefined', () =>
+          expect(original.clone({raws: undefined}).raws).toEqual({
+            afterOpen: '  ',
+          }));
+      });
+    });
+  });
+
+  it('toJSON', () => expect(utils.parseExpression('(foo)')).toMatchSnapshot());
+});
diff --git a/pkg/sass-parser/lib/src/expression/parenthesized.ts b/pkg/sass-parser/lib/src/expression/parenthesized.ts
@@ -0,0 +1,97 @@
+// Copyright 2025 Google Inc. Use of this source code is governed by an
+// MIT-style license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import * as postcss from 'postcss';
+
+import {LazySource} from '../lazy-source';
+import {NodeProps} from '../node';
+import type * as sassInternal from '../sass-internal';
+import * as utils from '../utils';
+import {Expression, ExpressionProps} from '.';
+import {convertExpression} from './convert';
+import {fromProps} from './from-props';
+
+/**
+ * The initializer properties for {@link ParenthesizedExpression}.
+ *
+ * @category Expression
+ */
+export interface ParenthesizedExpressionProps extends NodeProps {
+  inParens: Expression | ExpressionProps;
+  raws?: ParenthesizedExpressionRaws;
+}
+
+/**
+ * Raws indicating how to precisely serialize a {@link ParenthesizedExpression}.
+ *
+ * @category Expression
+ */
+export interface ParenthesizedExpressionRaws {
+  /** The whitespace after the opening parenthesis. */
+  afterOpen?: string;
+
+  /** The whitespace before the closing parenthesis. */
+  beforeClose?: string;
+}
+
+/**
+ * An expression representing a parenthesized Sass expression.
+ *
+ * @category Expression
+ */
+export class ParenthesizedExpression extends Expression {
+  readonly sassType = 'parenthesized' as const;
+  declare raws: ParenthesizedExpressionRaws;
+
+  /** The expression within the parentheses. */
+  get inParens(): Expression {
+    return this._inParens;
+  }
+  set inParens(inParens: Expression | ExpressionProps) {
+    // TODO - postcss/postcss#1957: Mark this as dirty
+    if (this._inParens) this._inParens.parent = undefined;
+    if (!('sassType' in inParens)) inParens = fromProps(inParens);
+    inParens.parent = this;
+    this._inParens = inParens;
+  }
+  private declare _inParens: Expression;
+
+  constructor(defaults: ParenthesizedExpressionProps);
+  /** @hidden */
+  constructor(_: undefined, inner: sassInternal.ParenthesizedExpression);
+  constructor(defaults?: object, inner?: sassInternal.ParenthesizedExpression) {
+    super(defaults);
+    if (inner) {
+      this.source = new LazySource(inner);
+      this.inParens = convertExpression(inner.expression);
+    }
+  }
+
+  clone(overrides?: Partial<ParenthesizedExpressionProps>): this {
+    return utils.cloneNode(this, overrides, ['raws', 'inParens']);
+  }
+
+  toJSON(): object;
+  /** @hidden */
+  toJSON(_: string, inputs: Map<postcss.Input, number>): object;
+  toJSON(_?: string, inputs?: Map<postcss.Input, number>): object {
+    return utils.toJSON(this, ['inParens'], inputs);
+  }
+
+  /** @hidden */
+  toString(): string {
+    return (
+      '(' +
+      (this.raws.afterOpen ?? '') +
+      this.inParens +
+      (this.raws.beforeClose ?? '') +
+      ')'
+    );
+  }
+
+  /** @hidden */
+  get nonStatementChildren(): ReadonlyArray<Expression> {
+    return [this.inParens];
+  }
+}
diff --git a/pkg/sass-parser/lib/src/sass-internal.ts b/pkg/sass-parser/lib/src/sass-internal.ts
@@ -378,6 +378,10 @@ declare namespace SassInternal {
     readonly value: number;
     readonly unit: string;
   }
+
+  class ParenthesizedExpression extends Expression {
+    readonly expression: Expression;
+  }
 }
 
 const sassInternal = (
@@ -438,6 +442,7 @@ export type BooleanExpression = SassInternal.BooleanExpression;
 export type ColorExpression = SassInternal.ColorExpression;
 export type NullExpression = SassInternal.NullExpression;
 export type NumberExpression = SassInternal.NumberExpression;
+export type ParenthesizedExpression = SassInternal.ParenthesizedExpression;
 
 export interface StatementVisitorObject<T> {
   visitAtRootRule(node: AtRootRule): T;
@@ -469,7 +474,6 @@ export interface StatementVisitorObject<T> {
 
 export interface ExpressionVisitorObject<T> {
   visitBinaryOperationExpression(node: BinaryOperationExpression): T;
-  visitStringExpression(node: StringExpression): T;
   visitBooleanExpression(node: BooleanExpression): T;
   visitColorExpression(node: ColorExpression): T;
   visitFunctionExpression(node: FunctionExpression): T;
@@ -479,6 +483,8 @@ export interface ExpressionVisitorObject<T> {
   visitMapExpression(node: MapExpression): T;
   visitNullExpression(node: NullExpression): T;
   visitNumberExpression(node: NumberExpression): T;
+  visitParenthesizedExpression(node: ParenthesizedExpression): T;
+  visitStringExpression(node: StringExpression): T;
 }
 
 export const createExpressionVisitor = sassInternal.createExpressionVisitor;
