Improved documentation regarding internal scopes (#3086)

Author: AndreasArvidsson

data/scopeSupportFacetInfos.md

@@ -119,7 +119,7 @@
 
 ### disqualifyDelimiter
 
-- `disqualifyDelimiter` Used to disqualify a token from being treated as a surrounding pair delimiter. This will usually be operators containing `>` or `<`, eg `<`, `<=`, `->`, etc
+- `disqualifyDelimiter` Internally used to disqualify a token from being treated as a surrounding pair delimiter. This will usually be operators containing `>` or `<`, eg `<`, `<=`, `->`, etc.
 
 ### document
 
@@ -259,7 +259,7 @@
 
 ### pairDelimiter
 
-- `pairDelimiter` A pair delimiter, eg parentheses, brackets, braces, quotes, etc
+- `pairDelimiter` Internally used to add additional language specific surrounding pair delimiters in addition to the text based definitions. eg `r"`.
 
 ### paragraph
 
@@ -336,11 +336,11 @@
 
 ### textFragment
 
-- `textFragment.comment.block` Text fragment consisting of a block comment
-- `textFragment.comment.line` Text fragment consisting of a line comment
-- `textFragment.element` Text fragment consisting of a xml element interior
-- `textFragment.string.multiLine` Text fragment consisting of a multi-line string
-- `textFragment.string.singleLine` Text fragment consisting of a single-line string
+- `textFragment.comment.block` Internally used text fragment consisting of a block comment
+- `textFragment.comment.line` Internally used text fragment consisting of a line comment
+- `textFragment.element` Internally used text fragment consisting of a xml element interior
+- `textFragment.string.multiLine` Internally used text fragment consisting of a multi-line string
+- `textFragment.string.singleLine` Internally used text fragment consisting of a single-line string
 
 ### token
 

packages/common/src/scopeSupportFacets/scopeSupportFacetInfos.ts

@@ -474,38 +474,6 @@ export const scopeSupportFacetInfos: Record<
     scopeType: "string",
   },
 
-  "textFragment.comment.line": {
-    description: "Text fragment consisting of a line comment",
-    scopeType: "textFragment",
-  },
-  "textFragment.comment.block": {
-    description: "Text fragment consisting of a block comment",
-    scopeType: "textFragment",
-  },
-  "textFragment.string.singleLine": {
-    description: "Text fragment consisting of a single-line string",
-    scopeType: "textFragment",
-  },
-  "textFragment.string.multiLine": {
-    description: "Text fragment consisting of a multi-line string",
-    scopeType: "textFragment",
-  },
-  "textFragment.element": {
-    description: "Text fragment consisting of a xml element interior",
-    scopeType: "textFragment",
-  },
-
-  disqualifyDelimiter: {
-    description:
-      "Used to disqualify a token from being treated as a surrounding pair delimiter. This will usually be operators containing `>` or `<`, eg `<`, `<=`, `->`, etc",
-    scopeType: "disqualifyDelimiter",
-  },
-  pairDelimiter: {
-    description:
-      "A pair delimiter, eg parentheses, brackets, braces, quotes, etc",
-    scopeType: "pairDelimiter",
-  },
-
   "branch.if": {
     description: "An if branch",
     scopeType: "branch",
@@ -1044,6 +1012,43 @@ export const scopeSupportFacetInfos: Record<
     description: "A unit in a css rule set",
     scopeType: "unit",
   },
+
+  // Internal scope facets
+
+  "textFragment.comment.line": {
+    description: "Internally used text fragment consisting of a line comment",
+    scopeType: "textFragment",
+  },
+  "textFragment.comment.block": {
+    description: "Internally used text fragment consisting of a block comment",
+    scopeType: "textFragment",
+  },
+  "textFragment.string.singleLine": {
+    description:
+      "Internally used text fragment consisting of a single-line string",
+    scopeType: "textFragment",
+  },
+  "textFragment.string.multiLine": {
+    description:
+      "Internally used text fragment consisting of a multi-line string",
+    scopeType: "textFragment",
+  },
+  "textFragment.element": {
+    description:
+      "Internally used text fragment consisting of a xml element interior",
+    scopeType: "textFragment",
+  },
+
+  disqualifyDelimiter: {
+    description:
+      "Internally used to disqualify a token from being treated as a surrounding pair delimiter. This will usually be operators containing `>` or `<`, eg `<`, `<=`, `->`, etc.",
+    scopeType: "disqualifyDelimiter",
+  },
+  pairDelimiter: {
+    description:
+      'Internally used to add additional language specific surrounding pair delimiters in addition to the text based definitions. eg `r"`.',
+    scopeType: "pairDelimiter",
+  },
 };
 
 function documentIter(

packages/cursorless-org-docs/src/docs/components/Header.css

@@ -0,0 +1,3 @@
+.anchor-with-sticky-navbar {
+  scroll-margin-top: calc(var(--ifm-navbar-height) + 0.5rem);
+}

packages/cursorless-org-docs/src/docs/components/Header.tsx

@@ -1,5 +1,6 @@
 import { uriEncodeHashId } from "@cursorless/common";
 import React from "react";
+import "./Header.css";
 
 interface Props {
   className?: string;
@@ -35,8 +36,7 @@ function renderHeader(
       id={encodedId}
       title={title}
       className={
-        "scope-header anchorWithStickyNavbar_IncK" +
-        (className ? " " + className : "")
+        "anchor-with-sticky-navbar" + (className ? " " + className : "")
       }
     >
       {children}

packages/cursorless-org-docs/src/docs/components/ScopeVisualizer.tsx

@@ -52,6 +52,24 @@ export function ScopeVisualizer({ languageId, scopeTypeType }: Props) {
     scopeTypeType != null,
   );
 
+  const renderPublicScopesHeader = () => {
+    return <H2>Scopes</H2>;
+  };
+
+  const renderInternalScopesHeader = () => {
+    return (
+      <>
+        <H2>Internal scopes</H2>
+
+        <p>
+          The following are internal scopes. They are not intended for user
+          interaction or spoken use. These scopes exist solely for internal
+          Cursorless functionality.
+        </p>
+      </>
+    );
+  };
+
   const renderOptions = () => {
     return (
       <div className="mb-4">
@@ -76,61 +94,60 @@ export function ScopeVisualizer({ languageId, scopeTypeType }: Props) {
     );
   };
 
-  const renderInternalScopes = () => {
-    if (scopes.internal.length === 0) {
-      return null;
-    }
-    return (
-      <>
-        <H2>Internal scopes</H2>
-
-        {languageId && (
-          <p>
-            The following are internal scopes. They are not intended for user
-            interaction or spoken use. These scopes exist solely for internal
-            Cursorless functionality.
-          </p>
-        )}
-
-        {scopes.internal.map((scope) =>
-          renderScope(
-            languageId,
-            scopeTypeType,
-            rangeType,
-            renderWhitespace,
-            scope,
-          ),
-        )}
-      </>
+  const renderScopes = (scopes: Scope[]) => {
+    return scopes.map((scope) =>
+      renderScope(
+        languageId,
+        scopeTypeType,
+        rangeType,
+        renderWhitespace,
+        scope,
+      ),
     );
   };
 
-  return (
-    <>
-      <H2>Scopes</H2>
-
-      {languageId && (
+  // Specific language. Public scopes followed by (optional) internal scopes.
+  if (languageId != null) {
+    return (
+      <>
         <p>
           Below are visualizations of all our scope tests for this language.
           These were created primarily for testing purposes rather than as
           documentation. There are quite a few, and they may feel a bit
           overwhelming from a documentation standpoint.
         </p>
-      )}
 
-      {renderOptions()}
+        {renderPublicScopesHeader()}
+        {renderOptions()}
+        {renderScopes(scopes.public)}
 
-      {scopes.public.map((scope) =>
-        renderScope(
-          languageId,
-          scopeTypeType,
-          rangeType,
-          renderWhitespace,
-          scope,
-        ),
-      )}
+        {scopes.internal.length > 0 && (
+          <>
+            {renderInternalScopesHeader()}
+            {renderScopes(scopes.internal)}
+          </>
+        )}
+      </>
+    );
+  }
 
-      {renderInternalScopes()}
+  // Specific public scope
+  if (scopes.public.length > 0) {
+    return (
+      <>
+        {renderPublicScopesHeader()}
+        {renderOptions()}
+        {renderScopes(scopes.public)}
+      </>
+    );
+  }
+
+  // Specific internal scope
+  return (
+    <>
+      {renderInternalScopesHeader()}
+      {renderOptions()}
+      {renderScopes(scopes.internal)}
     </>
   );
 }
@@ -295,7 +312,7 @@ function getScopeFixtures(
     .forEach((scope) => {
       scope.facets.sort(facetComparator);
       scope.facets.forEach((f) => f.fixtures.sort(nameComparator));
-      if (scopeTypeType == null && isScopeInternal(scope.scopeTypeType)) {
+      if (isScopeInternal(scope.scopeTypeType)) {
         result.internal.push(scope);
       } else {
         result.public.push(scope);