feat: Add CSS support (#75)

Co-authored-by: Amaresh  S M <[email protected]>

Author: nzakas

docs/adding-languages.md

@@ -0,0 +1,62 @@
+# Adding Languages
+
+To add a language to Code Explorer, follow these steps.
+
+## Step 1: Add a logo
+
+Add an SVG logo into the `public/languages/` directory.
+
+## Step 2: Update `src/hooks/use-explorer.ts`
+
+1. Update the `Language` type to contain an entry for the new language.
+1. Create a new mode variable that defines the primary parsing mode (such as `jsonMode` or `cssMode`).
+1. Update the `Code` type to include an entry for the new language.
+1. Create a new options variable that defines the options for the new language (such as `JsonOptions` or `CssOptions`).
+1. Update the `ExplorerState` type to include getters and setters for the new language's language options.
+1. Update the `useExplorer` variable to include the default options for the new language.
+
+## Step 3: Update `src/lib/const.ts`
+
+1. Import the type for the new language options from `src/hooks/use-explorer.ts`.
+1. Add an entry in the `languages` variable for the new language.
+1. Export a new variable describing the available modes for the new language (such as `jsonModes` or `cssModes`).
+1. Default the default code for the new language (such as `defaultJsonCode` or `defaultCssCode`).
+1. Add an entry in the `defaultCode` variable for the new language's default code.
+1. Export a variable containing the default options for the new language (such as `defaultJsonOptions` or `defaultCssOptions`).
+
+## Step 4: Update `src/hooks/use-explorer.ts` (yes, again)
+
+Now import the default options for the new language from `src/lib/const.ts`.
+
+## Step 5: Update `src/components/options.tsx`
+
+1. Import the new language mode type from `src/hooks/use-explorer` (such as `JsonMode` or `CssMode`).
+1. Import the available modes for the new language from `src/hooks/const` (such as `jsonModes` or `cssModes`).
+1. Create an options panel for the new language (such as `JsonPanel` or `CssPanel`).
+1. Update the `Panel` variable to use the new options panel.
+
+## Step 6: Update `src/components/editor.ts`
+
+1. Install the appropriate CodeMirror plugin for the new language.
+1. Update the `languageExtensions` variable to include the new language CodeMirror plugin.
+
+## Step 7: Add AST components
+
+In the `src/components/ast` directory, create two files:
+
+1. `{new language}-ast.tsx`
+1. `{new language}-ast-tree-item.tsx`
+
+Replace `{new language}` with the name of the language. You can copy existing files for other languages to get started.
+
+In `{new language}-ast-tree-item.tsx`, update the name of the options type and the exported component to match the new language.
+
+Next, install the ESLint language plugin for the new language.
+
+In `{new language}-ast.tsx`:
+
+1. Update language references to point to the new language.
+1. Import the ESLint language plugin to parse the code.
+1. Set the `defaultValue` in the accordion to the name of the root node for the new language AST.
+
+Last, update `src/components/index.tsx` to import `{new language}-ast.tsx` and update `Ast` to include the new language.

package-lock.json

@@ -33,10 +33,12 @@
     "node": ">= 20"
   },
   "dependencies": {
+    "@codemirror/lang-css": "^6.3.1",
     "@codemirror/lang-javascript": "^6.2.2",
     "@codemirror/lang-json": "^6.0.1",
     "@codemirror/lang-markdown": "^6.2.5",
     "@codemirror/language": "^6.10.3",
+    "@eslint/css": "^0.1.0",
     "@eslint/js": "^9.9.0",
     "@eslint/json": "^0.4.1",
     "@eslint/markdown": "^6.1.1",

package.json

@@ -0,0 +1,38 @@
+import {
+	AccordionContent,
+	AccordionItem,
+	AccordionTrigger,
+} from "@/components/ui/accordion";
+import { TreeEntry } from "../tree-entry";
+import type { FC } from "react";
+
+type ASTNode = {
+	readonly type: string;
+	readonly [key: string]: unknown;
+};
+
+type CssAstTreeItemProperties = {
+	readonly index: number;
+	readonly data: ASTNode;
+};
+
+export const CssAstTreeItem: FC<CssAstTreeItemProperties> = ({
+	data,
+	index,
+}) => (
+	<AccordionItem
+		value={`${index}-${data.type}`}
+		className="border border-card rounded-lg overflow-hidden"
+	>
+		<AccordionTrigger className="text-sm bg-card px-4 py-3 capitalize">
+			{data.type}
+		</AccordionTrigger>
+		<AccordionContent className="p-4 border-t">
+			<div className="space-y-1">
+				{Object.entries(data).map(item => (
+					<TreeEntry key={item[0]} data={item} />
+				))}
+			</div>
+		</AccordionContent>
+	</AccordionItem>
+);

public/languages/css.svg

@@ -0,0 +1,37 @@
+import css from "@eslint/css";
+import { Accordion } from "@/components/ui/accordion";
+import { Editor } from "@/components/editor";
+import { useExplorer } from "@/hooks/use-explorer";
+import { CssAstTreeItem } from "./css-ast-tree-item";
+import type { FC } from "react";
+import { parseError } from "@/lib/parse-error";
+import { ErrorState } from "../error-boundary";
+
+export const CssAst: FC = () => {
+	const { code, cssOptions, viewModes } = useExplorer();
+	const { astView } = viewModes;
+	const { cssMode } = cssOptions;
+	const language = css.languages[cssMode];
+	const result = language.parse({ body: code.css });
+
+	if (!result.ok) {
+		const message = parseError(result.errors[0]);
+		return <ErrorState message={message} />;
+	}
+
+	const ast = JSON.stringify(result.ast, null, 2);
+
+	if (astView === "tree") {
+		return (
+			<Accordion
+				type="multiple"
+				className="px-8 font-mono space-y-3"
+				defaultValue={["0-StyleSheet"]}
+			>
+				<CssAstTreeItem data={result.ast} index={0} />
+			</Accordion>
+		);
+	}
+
+	return <Editor readOnly value={ast} />;
+};

src/components/ast/css-ast-tree-item.tsx

@@ -3,6 +3,7 @@
 import { useExplorer } from "@/hooks/use-explorer";
 import { JavascriptAst } from "./javascript-ast";
 import { JsonAst } from "./json-ast";
+import { CssAst } from "./css-ast";
 import { MarkdownAst } from "./markdown-ast";
 import type { FC } from "react";
 
@@ -14,6 +15,8 @@ export const Ast: FC = () => {
 			return <MarkdownAst />;
 		case "json":
 			return <JsonAst />;
+		case "css":
+			return <CssAst />;
 		default:
 			return <JavascriptAst />;
 	}

src/components/ast/css-ast.tsx

@@ -6,6 +6,7 @@ import CodeMirror from "@uiw/react-codemirror";
 import { json } from "@codemirror/lang-json";
 import { javascript } from "@codemirror/lang-javascript";
 import { markdown } from "@codemirror/lang-markdown";
+import { css } from "@codemirror/lang-css";
 import { EditorView } from "@codemirror/view";
 import { EditorState } from "@codemirror/state";
 import clsx from "clsx";
@@ -21,6 +22,7 @@ const languageExtensions: Record<string, (isJSX?: boolean) => LanguageSupport> =
 		javascript: (isJSX: boolean = false) => javascript({ jsx: isJSX }),
 		json: () => json(),
 		markdown: () => markdown(),
+		css: () => css(),
 	};
 
 type EditorProperties = {

src/components/ast/index.tsx

@@ -66,6 +66,10 @@ const MarkdownPanel: React.FC = () => {
 	);
 };
 
+const CssPanel: React.FC = () => {
+	return null;
+};
+
 const JavaScriptPanel = () => {
 	const explorer = useExplorer();
 	const { jsOptions, setJsOptions } = explorer;
@@ -129,6 +133,8 @@ const Panel = ({ language }: { language: string }) => {
 			return <JSONPanel />;
 		case "markdown":
 			return <MarkdownPanel />;
+		case "css":
+			return <CssPanel />;
 		default:
 			return <JavaScriptPanel />;
 	}

src/components/editor.tsx

@@ -11,16 +11,23 @@ import {
 	defaultJsOptions,
 	defaultJsonOptions,
 	defaultMarkdownOptions,
+	defaultCssOptions,
 	defaultPathIndex,
 	defaultViewModes,
 } from "../lib/const";
 export type SourceType = Exclude<Options["sourceType"], undefined>;
 export type Version = Exclude<Options["ecmaVersion"], undefined>;
-export type Language = "javascript" | "json" | "markdown";
+export type Language = "javascript" | "json" | "markdown" | "css";
 export type JsonMode = "json" | "jsonc" | "json5";
 export type MarkdownMode = "commonmark" | "gfm";
+export type CssMode = "css";
 
-export type Code = { javascript: string; json: string; markdown: string };
+export type Code = {
+	javascript: string;
+	json: string;
+	markdown: string;
+	css: string;
+};
 export type JsOptions = {
 	parser: string;
 	sourceType: SourceType;
@@ -36,6 +43,10 @@ export type MarkdownOptions = {
 	markdownMode: MarkdownMode;
 };
 
+export type CssOptions = {
+	cssMode: CssMode;
+};
+
 export type PathIndex = {
 	index: number;
 	indexes: number;
@@ -66,6 +77,9 @@ type ExplorerState = {
 	markdownOptions: MarkdownOptions;
 	setMarkdownOptions: (markdownOptions: MarkdownOptions) => void;
 
+	cssOptions: CssOptions;
+	setCssOptions: (cssOptions: CssOptions) => void;
+
 	wrap: boolean;
 	setWrap: (wrap: boolean) => void;
 
@@ -115,6 +129,9 @@ export const useExplorer = create<ExplorerState>()(
 					jsonOptions: defaultJsonOptions,
 					setJsonOptions: jsonOptions => set({ jsonOptions }),
 
+					cssOptions: defaultCssOptions,
+					setCssOptions: cssOptions => set({ cssOptions }),
+
 					markdownOptions: defaultMarkdownOptions,
 					setMarkdownOptions: markdownOptions =>
 						set({ markdownOptions }),