Show languages in the docs sidebar

changelog/2025-02-addedLanguagesToDocs.md

@@ -0,0 +1,6 @@
+---
+tags: [documentation]
+pullRequest: 2859
+---
+
+- Added languages sidebar to documents page. Here you can see the supported scope facets for each language.

packages/common/src/index.ts

@@ -93,6 +93,7 @@ export * from "./types/TreeSitter";
 export * from "./types/tutorial.types";
 export * from "./util";
 export * from "./util/camelCaseToAllDown";
+export * from "./util/capitalize";
 export * from "./util/clientSupportsFallback";
 export * from "./util/CompositeKeyDefaultMap";
 export * from "./util/CompositeKeyMap";

packages/common/src/util/capitalize.ts

@@ -0,0 +1,3 @@
+export function capitalize(str: string) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

packages/cursorless-org-docs/src/css/custom.css

@@ -28,3 +28,23 @@
 .hidden {
   display: none;
 }
+
+.card {
+  border: 1px solid rgba(0, 0, 0, 0.175);
+  margin-bottom: 1rem;
+}
+
+.card-header {
+  background-color: #f8f9fa;
+  border-bottom: 1px solid rgba(0, 0, 0, 0.125);
+  padding: 0.5rem 1rem;
+  cursor: pointer;
+}
+
+.card-body {
+  padding: 1rem;
+}
+
+.facet-name {
+  font-weight: 600;
+}

packages/cursorless-org-docs/src/docs/user/languages/c.mdx

@@ -1,4 +1,4 @@
-import Language from "./Language";
+import { Language } from "./components/Language";
 
 # C
 

packages/cursorless-org-docs/src/docs/user/languages/clojure.mdx

@@ -1,4 +1,4 @@
-import Language from "./Language";
+import { Language } from "./components/Language";
 
 # Clojure
 

packages/cursorless-org-docs/src/docs/user/languages/Language.tsx → packages/cursorless-org-docs/src/docs/user/languages/components/Language.tsx

@@ -1,10 +1,10 @@
 import React from "react";
-import ScopeSupport from "./ScopeSupport";
+import { ScopeSupport } from "./ScopeSupport";
 
 interface Props {
   languageId: string;
 }
 
-export default function Language({ languageId }: Props) {
+export function Language({ languageId }: Props) {
   return <ScopeSupport languageId={languageId} />;
 }

packages/cursorless-org-docs/src/docs/user/languages/components/ScopeSupport.tsx

@@ -0,0 +1,80 @@
+import {
+  ScopeSupportFacetLevel,
+  languageScopeSupport,
+  scopeSupportFacets,
+} from "@cursorless/common";
+import React from "react";
+import { ScopeSupportForLevel } from "./ScopeSupportForLevel";
+
+interface Props {
+  languageId: string;
+}
+
+export function ScopeSupport({ languageId }: Props): JSX.Element {
+  const scopesSorted = [...scopeSupportFacets].sort();
+  const scopeSupport = languageScopeSupport[languageId] ?? {};
+
+  const supportedScopes = scopesSorted.filter(
+    (facet) => scopeSupport[facet] === ScopeSupportFacetLevel.supported,
+  );
+  const supportedLegacyScopes = scopesSorted.filter(
+    (facet) => scopeSupport[facet] === ScopeSupportFacetLevel.supportedLegacy,
+  );
+  const unsupportedScopes = scopesSorted.filter(
+    (facet) => scopeSupport[facet] === ScopeSupportFacetLevel.unsupported,
+  );
+  const unspecifiedScopes = scopesSorted.filter(
+    (facet) => scopeSupport[facet] == null,
+  );
+
+  return (
+    <>
+      <h2>Scopes</h2>
+
+      <ScopeSupportForLevel
+        facets={supportedScopes}
+        title="Supported facets"
+        subtitle="These facets are supported"
+        expanded
+      />
+
+      <ScopeSupportForLevel
+        facets={supportedLegacyScopes}
+        title="Supported Legacy facets"
+        subtitle="These facets are supported with the legacy implementation and should be migrated to the new implementation"
+      />
+
+      <ScopeSupportForLevel
+        facets={unsupportedScopes}
+        title="Unsupported facets"
+        subtitle="These facets are not supported yet and needs a developer to implement them"
+        description={
+          <>
+            We would happily accept{" "}
+            <a href="https://www.cursorless.org/docs/contributing/adding-a-new-scope">
+              contributions
+            </a>
+          </>
+        }
+      />
+
+      <ScopeSupportForLevel
+        facets={unspecifiedScopes}
+        title="Unspecified facets"
+        subtitle="These facets are unspecified"
+        description={
+          <>
+            Note that in many instances we actually do support these scopes and
+            facets, but we have not yet updated 'languageScopeSupport' to
+            reflect this fact.
+            <br />
+            We would happily accept{" "}
+            <a href="https://www.cursorless.org/docs/contributing/adding-a-new-scope">
+              contributions
+            </a>
+          </>
+        }
+      />
+    </>
+  );
+}

packages/cursorless-org-docs/src/docs/user/languages/components/ScopeSupportForLevel.tsx

@@ -0,0 +1,119 @@
+import {
+  camelCaseToAllDown,
+  capitalize,
+  groupBy,
+  type ScopeSupportFacet,
+  type ScopeSupportFacetInfo,
+  scopeSupportFacetInfos,
+  type ScopeType,
+  type SimpleScopeTypeType,
+} from "@cursorless/common";
+import React, { useState } from "react";
+
+interface Props {
+  facets: ScopeSupportFacet[];
+  title: string;
+  subtitle: string;
+  description?: React.ReactNode;
+  expanded?: boolean;
+}
+
+export function ScopeSupportForLevel({
+  facets,
+  title,
+  subtitle,
+  description,
+  expanded: expandedProp,
+}: Props): JSX.Element | null {
+  const [expanded, setExpanded] = useState(expandedProp ?? false);
+
+  if (facets.length === 0) {
+    return null;
+  }
+
+  const renderBody = () => {
+    if (!expanded) {
+      return null;
+    }
+
+    const facetInfos = facets.map(
+      (facet): AugmentedFacetInfo => ({
+        facet,
+        ...scopeSupportFacetInfos[facet],
+      }),
+    );
+    const scopeGroups: Map<string, AugmentedFacetInfo[]> = groupBy(
+      facetInfos,
+      (facetInfo) => serializeScopeType(facetInfo.scopeType),
+    );
+    const scopeTypes = Array.from(scopeGroups.keys()).sort();
+
+    return (
+      <div className="card-body">
+        {description && <p>{description}</p>}
+
+        {scopeTypes.map((scopeType) => {
+          const facetInfos = scopeGroups.get(scopeType) ?? [];
+          return (
+            <div key={scopeType}>
+              <h4>{prettifyScopeType(scopeType)}</h4>
+              <ul>
+                {facetInfos.map((facetInfo) => {
+                  return (
+                    <li key={facetInfo.facet}>
+                      <span className="facet-name" title={facetInfo.facet}>
+                        {prettifyFacet(facetInfo.facet)}
+                      </span>
+                      : {facetInfo.description}
+                    </li>
+                  );
+                })}
+              </ul>
+            </div>
+          );
+        })}
+      </div>
+    );
+  };
+
+  return (
+    <div className="card">
+      <div className="card-header" onClick={() => setExpanded(!expanded)}>
+        <h3>{title}</h3>
+        {subtitle}
+      </div>
+
+      {renderBody()}
+    </div>
+  );
+}
+
+interface AugmentedFacetInfo extends ScopeSupportFacetInfo {
+  facet: ScopeSupportFacet;
+}
+
+function prettifyScopeType(scopeType: string): string {
+  return capitalize(camelCaseToAllDown(scopeType));
+}
+
+function prettifyFacet(facet: ScopeSupportFacet): string {
+  const parts = facet.split(".").map(camelCaseToAllDown);
+  if (parts.length === 1) {
+    return capitalize(parts[0]);
+  }
+  const isIteration = parts[parts.length - 1] === "iteration";
+  if (isIteration) {
+    parts.pop();
+  }
+  const name = capitalize(parts.slice(1).join(" "));
+  return isIteration ? `${name} (iteration)` : name;
+}
+
+function serializeScopeType(
+  scopeType: SimpleScopeTypeType | ScopeType,
+): string {
+  if (typeof scopeType === "string") {
+    return scopeType;
+  }
+  return scopeType.type;
+}

packages/cursorless-org-docs/src/docs/user/languages/cpp.mdx

@@ -1,4 +1,4 @@
-import Language from "./Language";
+import { Language } from "./components/Language";
 
 # C++
 

packages/cursorless-org-docs/src/docs/user/languages/csharp.mdx

@@ -1,4 +1,4 @@
-import Language from "./Language";
+import { Language } from "./components/Language";
 
 # C#
 

packages/cursorless-org-docs/src/docs/user/languages/css.mdx

@@ -1,4 +1,4 @@
-import Language from "./Language";
+import { Language } from "./components/Language";
 
 # CSS
 

packages/cursorless-org-docs/src/docs/user/languages/dart.mdx

@@ -1,5 +1,5 @@
-import Language from "./Language";
+import { Language } from "./components/Language";
 
-# dart
+# Dart
 
 <Language languageId="dart"></Language>

packages/cursorless-org-docs/src/docs/user/languages/go.mdx

@@ -1,4 +1,4 @@
-import Language from "./Language";
+import { Language } from "./components/Language";
 
 # Go
 

packages/cursorless-org-docs/src/docs/user/languages/html.mdx

@@ -1,4 +1,4 @@
-import Language from "./Language";
+import { Language } from "./components/Language";
 
 # HTML
 

packages/cursorless-org-docs/src/docs/user/languages/java.mdx

@@ -1,4 +1,4 @@
-import Language from "./Language";
+import { Language } from "./components/Language";
 
 # Java