Added references for actions, modifiers, and scopes in docs

cursorless-talon/src/cheatsheet/sections/scopes.py

@@ -9,8 +9,8 @@ def get_scopes() -> list[ListItemDescriptor]:
         "scopeType",
         {
             "argumentOrParameter": "Argument",
-            "boundedNonWhitespaceSequence": "Non-whitespace sequence bounded by surrounding pair delimeters",
-            "boundedParagraph": "Paragraph bounded by surrounding pair delimeters",
+            "boundedNonWhitespaceSequence": "Non-whitespace sequence bounded by surrounding pair delimiters",
+            "boundedParagraph": "Paragraph bounded by surrounding pair delimiters",
         },
     )
 

oxlint.config.mts

@@ -58,6 +58,7 @@ const disabledRules = [
   "react/forbid-component-props",
   "react/jsx-max-depth",
   "react/jsx-no-literals",
+  "react/no-array-index-key",
   "react/no-multi-comp",
   "react/only-export-components",
   "react/react-in-jsx-scope",

packages/app-web-docs/package.json

@@ -42,6 +42,7 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
+    "@cursorless/lib-common": "workspace:*",
     "@cursorless/lib-node-common": "workspace:*",
     "@docusaurus/module-type-aliases": "^3.10.2",
     "@docusaurus/types": "^3.10.2",

packages/app-web-docs/src/css/custom.scss

@@ -25,3 +25,8 @@
 .pointer {
   cursor: pointer;
 }
+
+.list-unstyled {
+  padding-left: 1rem;
+  list-style: none;
+}

packages/app-web-docs/src/docs/components/ReferenceEntry.tsx

@@ -0,0 +1,114 @@
+import React, { Fragment } from "react";
+import {
+  actionReferences,
+  modifierReferences,
+  scopeReferences,
+} from "@cursorless/lib-common";
+import type { ReferenceEntry } from "@cursorless/lib-common";
+
+export function ActionReference({ id }: { id: keyof typeof actionReferences }) {
+  return <ReferenceEntryComponent id={id} entry={actionReferences[id]} />;
+}
+
+export function ModifierReference({
+  id,
+}: {
+  id: keyof typeof modifierReferences;
+}) {
+  return <ReferenceEntryComponent id={id} entry={modifierReferences[id]} />;
+}
+
+export function ScopeReference({ id }: { id: keyof typeof scopeReferences }) {
+  return <ReferenceEntryComponent id={id} entry={scopeReferences[id]} />;
+}
+
+function ReferenceEntryComponent({
+  id,
+  entry,
+}: {
+  id: string;
+  entry: ReferenceEntry;
+}) {
+  return (
+    <>
+      {entry.description != null && <p>{entry.description}</p>}
+
+      <p>
+        Cursorless ID: <code>{id}</code>
+      </p>
+
+      {entry.defaultSpokenForm != null && (
+        <div className="mb-3">
+          <div>
+            Default spoken form: <code>{entry.defaultSpokenForm}</code>
+          </div>
+
+          {entry.legacySpokenForms != null && (
+            <div>
+              Legacy spoken forms:{" "}
+              {entry.legacySpokenForms.map((s, i) => (
+                <Fragment key={s}>
+                  {i > 0 && ", "}
+                  <code>{s}</code>
+                </Fragment>
+              ))}
+            </div>
+          )}
+
+          {entry.disabledByDefault && (
+            <div>
+              <strong>Disabled by default</strong>
+            </div>
+          )}
+        </div>
+      )}
+
+      {entry.syntaxes.length > 0 && (
+        <div>
+          Syntax:
+          <ul className="list-unstyled">
+            {entry.syntaxes.map((syntax, index) => (
+              <li key={index}>
+                {formatPattern(syntax.pattern, entry.defaultSpokenForm)}:{" "}
+                {formatPattern(syntax.description)}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {entry.examples.length > 0 && (
+        <div>
+          Examples:
+          <ul className="list-unstyled">
+            {entry.examples.map((example, index) => (
+              <li key={index}>
+                <code>
+                  &quot;
+                  {formatPattern(example.spokenForm, entry.defaultSpokenForm)}
+                  &quot;
+                </code>
+                : {example.description}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </>
+  );
+}
+
+function formatPattern(
+  pattern: string,
+  defaultSpokenForm?: string,
+): React.ReactNode[] {
+  return pattern.split(/(<[\w ]+>)/gu).map((part, index) => {
+    if (part.startsWith("<") && part.endsWith(">")) {
+      if (part === "<spokenForm>") {
+        return defaultSpokenForm ?? "???";
+      }
+      return <code key={index}>{part}</code>;
+    }
+    return part;
+  });
+}

packages/app-web-docs/src/docs/components/ScopeVisualizer.tsx

@@ -7,19 +7,15 @@ import type {
 import {
   prettifyLanguageName,
   prettifyScopeType,
+  scopeReferences,
   serializeScopeType,
 } from "@cursorless/lib-common";
 import { generateDecorations } from "./calculateHighlights";
 import { Code } from "./Code";
 import { H2, H3, H4, H5 } from "./Header";
 import "./ScopeSupport.css";
 import type { FacetValue, Fixture, RangeType, ScopeTests } from "./types";
-import {
-  getFacetInfo,
-  isScopeInternal,
-  nameComparator,
-  prettifyFacet,
-} from "./util";
+import { getFacetInfo, nameComparator, prettifyFacet } from "./util";
 
 interface Scopes {
   public: Scope[];
@@ -57,6 +53,10 @@ export function ScopeVisualizer({ languageId, scopeTypeType }: Props) {
     scopeTypeType != null,
   );
 
+  if (scopes.internal.length === 0 && scopes.public.length === 0) {
+    return null;
+  }
+
   const renderOptions = () => {
     return (
       <div className="mb-4">
@@ -322,7 +322,7 @@ function getScopeFixtures(
     for (const f of scope.facets) {
       f.fixtures.sort(nameComparator);
     }
-    if (isScopeInternal(scope.scopeTypeType)) {
+    if (scopeReferences[scope.scopeTypeType].private) {
       result.internal.push(scope);
     } else {
       result.public.push(scope);

packages/app-web-docs/src/docs/contributing/scopes/components/Scopes.tsx → packages/app-web-docs/src/docs/components/Scopes.tsx

@@ -1,8 +1,8 @@
 import React from "react";
 import type { ScopeTypeType } from "@cursorless/lib-common";
-import { DynamicTOC } from "../../../components/DynamicTOC";
-import { ScopeVisualizer } from "../../../components/ScopeVisualizer";
-import { ScrollToHashId } from "../../../components/ScrollToHashId";
+import { DynamicTOC } from "./DynamicTOC";
+import { ScopeVisualizer } from "./ScopeVisualizer";
+import { ScrollToHashId } from "./ScrollToHashId";
 
 interface Props {
   scopeTypeType: ScopeTypeType;

packages/app-web-docs/src/docs/components/util.ts

@@ -2,7 +2,6 @@ import type {
   PlaintextScopeSupportFacet,
   ScopeSupportFacet,
   ScopeSupportFacetInfo,
-  ScopeTypeType,
 } from "@cursorless/lib-common";
 import {
   camelCaseToAllDown,
@@ -64,16 +63,3 @@ export function nameComparator(
 ): number {
   return a.name.localeCompare(b.name, undefined, { numeric: true });
 }
-
-export function isScopeInternal(scope: ScopeTypeType): boolean {
-  switch (scope) {
-    case "disqualifyDelimiter":
-    case "pairDelimiter":
-    case "textFragment":
-    case "interior":
-    case "surroundingPairInterior":
-      return true;
-    default:
-      return false;
-  }
-}

packages/app-web-docs/src/docs/contributing/privateScopes/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Private scopes"
+}

packages/app-web-docs/src/docs/contributing/privateScopes/customRegex.mdx

@@ -0,0 +1,5 @@
+import { Scopes } from "@site/src/docs/components/Scopes";
+
+# Custom regex
+
+<Scopes scopeTypeType="customRegex" />

packages/app-web-docs/src/docs/contributing/scopes/disqualifyDelimiter.mdx → packages/app-web-docs/src/docs/contributing/privateScopes/disqualifyDelimiter.mdx

@@ -1,4 +1,4 @@
-import { Scopes } from "./components/Scopes";
+import { Scopes } from "@site/src/docs/components/Scopes";
 
 # Disqualify delimiter
 

packages/app-web-docs/src/docs/contributing/privateScopes/fieldAccess.mdx

@@ -0,0 +1,5 @@
+import { Scopes } from "@site/src/docs/components/Scopes";
+
+# Field access
+
+<Scopes scopeTypeType="private.fieldAccess" />

packages/app-web-docs/src/docs/contributing/privateScopes/interior.mdx

@@ -0,0 +1,5 @@
+import { Scopes } from "@site/src/docs/components/Scopes";
+
+# Interior
+
+<Scopes scopeTypeType="interior" />

packages/app-web-docs/src/docs/contributing/scopes/pairDelimiter.mdx → packages/app-web-docs/src/docs/contributing/privateScopes/pairDelimiter.mdx

@@ -1,4 +1,4 @@
-import { Scopes } from "./components/Scopes";
+import { Scopes } from "@site/src/docs/components/Scopes";
 
 # Pair delimiter
 

packages/app-web-docs/src/docs/contributing/privateScopes/string.mdx

@@ -0,0 +1,5 @@
+import { Scopes } from "@site/src/docs/components/Scopes";
+
+# String
+
+<Scopes scopeTypeType="string" />

packages/app-web-docs/src/docs/contributing/scopes/surroundingPairInterior.mdx → packages/app-web-docs/src/docs/contributing/privateScopes/surroundingPairInterior.mdx

@@ -1,4 +1,4 @@
-import { Scopes } from "./components/Scopes";
+import { Scopes } from "@site/src/docs/components/Scopes";
 
 # Surrounding pair interior
 

packages/app-web-docs/src/docs/contributing/privateScopes/textFragment.mdx

@@ -0,0 +1,5 @@
+import { Scopes } from "@site/src/docs/components/Scopes";
+
+# Text fragment
+
+<Scopes scopeTypeType="textFragment" />