feat: add stylesheet root and comment node

Author: davejsdev

package.json

@@ -51,5 +51,8 @@
     "typescript": "^5.8.3",
     "unbuild": "^3.6.0",
     "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "window": "^4.2.7"
   }
 }

pnpm-lock.yaml

@@ -0,0 +1,42 @@
+export type CSSCommentInlineCSSText = `/* ${string} */`;
+export type CSSCommentBlockCSSText = `/**\n${string}\n */`;
+export type CSSCommentCSSText = CSSCommentInlineCSSText | CSSCommentBlockCSSText;
+
+export type CSSCommentType = 'inline' | 'block';
+export interface CSSCommentOptions {
+  type: CSSCommentType;
+}
+
+/**
+ * A comment in a CSS stylesheet.
+ */
+export class CSSComment {
+  static defaultOptions: CSSCommentOptions = {
+    type: 'inline',
+  };
+
+  value: string;
+  type: CSSCommentType;
+
+  constructor(value: string, options: CSSCommentOptions = CSSComment.defaultOptions) {
+    this.value = value;
+    this.type = options.type;
+  }
+
+  get cssText(): CSSCommentCSSText {
+    if (this.type === 'inline') {
+      return `/* ${this.value} */`;
+    }
+
+    if (this.type === 'block') {
+      // Format the value as a block comment
+      const lines = this.value.split('\n');
+      const indentedLines = lines.map((line) => ` * ${line}`);
+      const formattedLines = indentedLines.join('\n');
+
+      return `/**\n${formattedLines}\n */`;
+    }
+
+    throw new Error('Invalid comment type');
+  }
+}

src/entities/CSSComment.ts

@@ -0,0 +1,32 @@
+// biome-ignore lint/suspicious/noTsIgnore: no types available for this package
+// @ts-ignore-next-line no-restricted-globals
+import Window from 'window';
+import type { CSSComment } from './CSSComment';
+
+const window = new Window();
+
+interface CSSStyleSheetInit extends Window.CSSStyleSheetInit {
+  nodes: CSSComment[];
+}
+
+export class CSSStyleSheet extends window.CSSStyleSheet {
+  nodes: CSSComment[];
+
+  constructor(options: CSSStyleSheetInit) {
+    super(options);
+
+    this.nodes = options.nodes || [];
+  }
+
+  append(node: CSSComment) {
+    this.nodes.push(node);
+  }
+
+  remove(node: CSSComment) {
+    this.nodes = this.nodes.filter((n) => n !== node);
+  }
+
+  get cssText() {
+    return `${this.nodes.map((node) => node.cssText).join('\n\n')}\n`;
+  }
+}

src/entities/CSSStyleSheet.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { CSSComment } from '../CSSComment';
+
+describe('CSSComment', () => {
+  it('should create a comment', () => {
+    const comment = new CSSComment('This is a comment');
+    expect(comment.cssText).toMatchSnapshot();
+  });
+  it('should create a block comment', () => {
+    const comment = new CSSComment('This is a comment', { type: 'block' });
+    expect(comment.cssText).toMatchSnapshot();
+  });
+});

src/entities/__tests__/CSSComment.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { CSSComment } from '../CSSComment';
+import { CSSStyleSheet } from '../CSSStyleSheet';
+
+describe('CSSStyleSheet', () => {
+  it('should create a stylesheet', () => {
+    const stylesheet = new CSSStyleSheet({ nodes: [] });
+    expect(stylesheet.cssText).toBe('\n');
+  });
+
+  it.each([[[]], [[new CSSComment('This is a block comment', { type: 'block' })]]])(
+    'always ends with a single blank newline',
+    (nodes) => {
+      const stylesheet = new CSSStyleSheet({ nodes });
+      expect(stylesheet.cssText.endsWith('\n')).toBe(true);
+      expect(stylesheet.cssText.endsWith('\n\n')).toBe(false);
+    },
+  );
+
+  it('should create a stylesheet with a comment', () => {
+    const stylesheet = new CSSStyleSheet({ nodes: [] });
+    const comment = new CSSComment('This is a block comment', { type: 'block' });
+    stylesheet.append(comment);
+    expect(stylesheet.cssText).toMatchSnapshot();
+  });
+});

src/entities/__tests__/CSSStyleSheet.test.ts

@@ -0,0 +1,9 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`CSSComment > should create a block comment 1`] = `
+"/**
+ * This is a comment
+ */"
+`;
+
+exports[`CSSComment > should create a comment 1`] = `"/* This is a comment */"`;

src/entities/__tests__/__snapshots__/CSSComment.test.ts.snap

@@ -0,0 +1,8 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`CSSStyleSheet > should create a stylesheet with a comment 1`] = `
+"/**
+ * This is a block comment
+ */
+"
+`;

src/entities/__tests__/__snapshots__/CSSStyleSheet.test.ts.snap

@@ -4,8 +4,8 @@
     "declarationMap": true,
     "erasableSyntaxOnly": true,
     "lib": ["DOM", "ESNext"],
-    "module": "NodeNext",
-    "moduleResolution": "nodenext",
+    "module": "preserve",
+    "moduleResolution": "bundler",
     "noFallthroughCasesInSwitch": true,
     "noUncheckedIndexedAccess": true,
     "noUnusedLocals": true,