feat(gui): improve display of usages in selection view (#957)

lars-reimann · web-flow · commit fc2c9ca8491a · 2022-07-08T21:46:48.000+02:00
* feat(gui): make paragraph headings bold

* refactor(gui): extract code that counts how often the default value of a parameter is used implicitly

* refactor(gui): rename variable to be more consistent with remaining code

* feat(gui): add functions that returns whether parameter is optional/required

* fix(gui): refine cases where the default value is shown

* feat(gui): differentiate usages of parameters

* style: apply automatic fixes of linters

* feat(gui): show usage counts for other declarations in selection view

* style: apply automatic fixes of linters

* feat(gui): for function show parameter usages above parameters

Co-authored-by: lars-reimann &lt;lars-reimann@users.noreply.github.com&gt;
diff --git a/api-editor/gui/src/features/packageData/model/PythonParameter.ts b/api-editor/gui/src/features/packageData/model/PythonParameter.ts
@@ -71,6 +71,14 @@ export class PythonParameter extends PythonDeclaration {
         );
     }
 
+    isOptional(): boolean {
+        return this.defaultValue !== null && this.defaultValue !== undefined && this.isExplicitParameter();
+    }
+
+    isRequired(): boolean {
+        return (this.defaultValue === null || this.defaultValue === undefined) && this.isExplicitParameter();
+    }
+
     toString(): string {
         return `Parameter "${this.name}"`;
     }
diff --git a/api-editor/gui/src/features/packageData/selectionView/ClassView.tsx b/api-editor/gui/src/features/packageData/selectionView/ClassView.tsx
@@ -8,6 +8,7 @@ import { SectionListViewItem } from './SectionListViewItem';
 import { CompleteButton } from '../../annotations/CompleteButton';
 import { MissingAnnotationButton } from '../../annotations/MissingAnnotationButton';
 import { DataCopyButtons } from '../../annotations/DataCopyButtons';
+import { NonParameterUsageCounts } from './UsageCounts';
 
 interface ClassViewProps {
     pythonClass: PythonClass;
@@ -45,6 +46,7 @@ export const ClassView: React.FC<ClassViewProps> = function ({ pythonClass }) {
             </Stack>
             <SectionListViewItem title="Superclasses" inputElements={pythonClass.superclasses} />
             <SectionListViewItem title="Decorators" inputElements={pythonClass.decorators} />
+            <NonParameterUsageCounts declaration={pythonClass} />
         </Stack>
     );
 };
diff --git a/api-editor/gui/src/features/packageData/selectionView/FunctionView.tsx b/api-editor/gui/src/features/packageData/selectionView/FunctionView.tsx
@@ -15,6 +15,7 @@ import { selectFilter, selectSorter } from '../../ui/uiSlice';
 import { selectUsages } from '../../usages/usageSlice';
 import { MissingAnnotationButton } from '../../annotations/MissingAnnotationButton';
 import { DataCopyButtons } from '../../annotations/DataCopyButtons';
+import { NonParameterUsageCounts } from './UsageCounts';
 
 interface FunctionViewProps {
     pythonFunction: PythonFunction;
@@ -68,6 +69,8 @@ export const FunctionView: React.FC<FunctionViewProps> = function ({ pythonFunct
                 </Box>
             </Stack>
 
+            <NonParameterUsageCounts declaration={pythonFunction} />
+
             <Stack spacing={4}>
                 <Heading as="h4" size="md">
                     Sorted & Filtered Parameters
diff --git a/api-editor/gui/src/features/packageData/selectionView/ModuleView.tsx b/api-editor/gui/src/features/packageData/selectionView/ModuleView.tsx
@@ -10,6 +10,7 @@ import { PythonModule } from '../model/PythonModule';
 import { CodeComponent } from 'react-markdown/lib/ast-to-react';
 import { CompleteButton } from '../../annotations/CompleteButton';
 import { DataCopyButtons } from '../../annotations/DataCopyButtons';
+import { NonParameterUsageCounts } from './UsageCounts';
 
 // See https://github.com/remarkjs/react-markdown#use-custom-components-syntax-highlight
 const CustomCode: CodeComponent = function ({
@@ -101,6 +102,8 @@ export const ModuleView: React.FC<ModuleViewProps> = function ({ pythonModule })
                     </Text>
                 )}
             </Stack>
+
+            <NonParameterUsageCounts declaration={pythonModule} />
         </Stack>
     );
 };
diff --git a/api-editor/gui/src/features/packageData/selectionView/ParameterView.tsx b/api-editor/gui/src/features/packageData/selectionView/ParameterView.tsx
@@ -15,6 +15,7 @@ import {
 import { Bar } from 'react-chartjs-2';
 import { useAppSelector } from '../../../app/hooks';
 import { selectUsages } from '../../usages/usageSlice';
+import { ParameterUsageCounts } from './UsageCounts';
 
 ChartJS.register(CategoryScale, PointElement, LineElement, LinearScale, BarElement, Title, Tooltip);
 
@@ -24,7 +25,7 @@ interface ParameterViewProps {
 
 export const ParameterView: React.FC<ParameterViewProps> = function ({ pythonParameter }) {
     const usages = useAppSelector(selectUsages);
-    const parameterUsages = usages.valueUsages.get(pythonParameter.id);
+    const nValueUsages = usages.getValueCountsOrNull(pythonParameter);
 
     return (
         <Stack spacing={8}>
@@ -39,24 +40,34 @@ export const ParameterView: React.FC<ParameterViewProps> = function ({ pythonPar
                 </Stack>
             )}
 
-            {pythonParameter && (
+            {pythonParameter && pythonParameter.isExplicitParameter() && (
                 <Stack spacing={4}>
                     <Heading as="h4" size="md">
                         Default Value
                     </Heading>
 
-                    {pythonParameter.defaultValue ? (
+                    {pythonParameter.isOptional() ? (
                         <Stack>
-                            <ChakraText paddingLeft={4}>Code: {pythonParameter.defaultValue}</ChakraText>
+                            <ChakraText paddingLeft={4}>
+                                <Box as="span" fontWeight="bold">
+                                    Code:
+                                </Box>{' '}
+                                {pythonParameter.defaultValue}
+                            </ChakraText>
 
                             {pythonParameter.defaultValueInDocs ? (
                                 <ChakraText paddingLeft={4}>
-                                    Documentation: {pythonParameter.defaultValueInDocs}
+                                    <Box as="span" fontWeight="bold">
+                                        Documentation:
+                                    </Box>{' '}
+                                    {pythonParameter.defaultValueInDocs}
                                 </ChakraText>
                             ) : (
                                 <HStack>
                                     <ChakraText paddingLeft={4}>
-                                        Documentation:{' '}
+                                        <Box as="span" fontWeight="bold">
+                                            Documentation:
+                                        </Box>{' '}
                                         <Box as="span" color="gray.500">
                                             The documentation does not specify a default value.
                                         </Box>
@@ -72,22 +83,15 @@ export const ParameterView: React.FC<ParameterViewProps> = function ({ pythonPar
                 </Stack>
             )}
 
-            {parameterUsages && (
-                <Stack spacing={4}>
-                    <Heading as="h4" size="md">
-                        Usages
-                    </Heading>
-                    <UsageSum parameterUsages={parameterUsages} />
-                </Stack>
-            )}
+            {nValueUsages && <ParameterUsageCounts parameter={pythonParameter} />}
 
-            {parameterUsages && (
+            {nValueUsages && (
                 <Stack spacing={4}>
                     <Heading as="h4" size="md">
                         Most Common Values
                     </Heading>
                     <Box w="30vw" maxWidth="640px">
-                        <CustomBarChart parameterUsages={parameterUsages} />
+                        <CustomBarChart parameterUsages={nValueUsages} />
                     </Box>
                 </Stack>
             )}
@@ -178,13 +182,3 @@ const isStringifiedLiteral = function (value: string): boolean {
     }
     return !Number.isNaN(Number.parseFloat(value));
 };
-
-const UsageSum: React.FC<CustomBarChartProps> = function ({ parameterUsages }) {
-    let usage = 0;
-
-    parameterUsages.forEach((value) => {
-        usage += value;
-    });
-
-    return <ChakraText paddingLeft={4}>{usage}</ChakraText>;
-};
diff --git a/api-editor/gui/src/features/packageData/selectionView/UsageCounts.tsx b/api-editor/gui/src/features/packageData/selectionView/UsageCounts.tsx
@@ -0,0 +1,73 @@
+import { Box, Heading, Stack, Text as ChakraText } from '@chakra-ui/react';
+import React from 'react';
+import { PythonParameter } from '../model/PythonParameter';
+import { useAppSelector } from '../../../app/hooks';
+import { selectUsages } from '../../usages/usageSlice';
+import { PythonModule } from '../model/PythonModule';
+import { PythonClass } from '../model/PythonClass';
+import { PythonFunction } from '../model/PythonFunction';
+
+interface NonParameterUsageCountsProps {
+    declaration: PythonModule | PythonClass | PythonFunction;
+}
+
+export const NonParameterUsageCounts: React.FC<NonParameterUsageCountsProps> = function ({ declaration }) {
+    const usageStore = useAppSelector(selectUsages);
+    const nUsages = usageStore.getUsageCount(declaration);
+
+    return (
+        <Stack spacing={4}>
+            <Heading as="h4" size="md">
+                Usages
+            </Heading>
+
+            <Stack>
+                <ChakraText paddingLeft={4}>{nUsages}</ChakraText>
+            </Stack>
+        </Stack>
+    );
+};
+
+interface ParameterUsageCountsProps {
+    parameter: PythonParameter;
+}
+
+export const ParameterUsageCounts: React.FC<ParameterUsageCountsProps> = function ({ parameter }) {
+    const usageStore = useAppSelector(selectUsages);
+
+    const nExplicitUsages = usageStore.getUsageCount(parameter);
+    const nImplicitUsages = usageStore.getNumberOfImplicitUsagesOfDefaultValue(parameter);
+
+    return (
+        <Stack spacing={4}>
+            <Heading as="h4" size="md">
+                Usages
+            </Heading>
+
+            <Stack>
+                <ChakraText paddingLeft={4}>
+                    <Box as="span" fontWeight="bold">
+                        Total:
+                    </Box>{' '}
+                    {nExplicitUsages + nImplicitUsages}
+                </ChakraText>
+                {parameter.isOptional() && (
+                    <ChakraText paddingLeft={4}>
+                        <Box as="span" fontWeight="bold">
+                            Explicit:
+                        </Box>{' '}
+                        {nExplicitUsages}
+                    </ChakraText>
+                )}
+                {parameter.isOptional() && (
+                    <ChakraText paddingLeft={4}>
+                        <Box as="span" fontWeight="bold">
+                            Implicit usages of default value:
+                        </Box>{' '}
+                        {nImplicitUsages}
+                    </ChakraText>
+                )}
+            </Stack>
+        </Stack>
+    );
+};
diff --git a/api-editor/gui/src/features/usages/model/UsageCountStore.ts b/api-editor/gui/src/features/usages/model/UsageCountStore.ts
@@ -109,6 +109,18 @@ export class UsageCountStore {
         return this.valueUsages.get(parameter.id) ?? null;
     }
 
+    getNumberOfImplicitUsagesOfDefaultValue(parameter: PythonParameter): number {
+        const containingFunction = parameter.containingFunction;
+        if (!containingFunction) {
+            return 0;
+        }
+
+        const parameterUsageCount = this.getUsageCount(parameter);
+        const functionUsageCount = this.getUsageCount(containingFunction);
+
+        return functionUsageCount - parameterUsageCount;
+    }
+
     toJson(): UsageCountJson {
         return {
             schemaVersion: EXPECTED_USAGES_SCHEMA_VERSION,
@@ -136,18 +148,7 @@ export class UsageCountStore {
                 continue;
             }
 
-            const containingFunction = parameter.containingFunction;
-            if (!containingFunction) {
-                continue;
-            }
-
-            const parameterUsageCount = this.getUsageCount(parameter);
-            const functionUsageCount = this.getUsageCount(containingFunction);
-            const nImplicitUsages = functionUsageCount - parameterUsageCount;
-            if (nImplicitUsages === 0) {
-                continue;
-            }
-
+            const nImplicitUsages = this.getNumberOfImplicitUsagesOfDefaultValue(parameter);
             const nExplicitUsages = this.valueUsages.get(parameter.id)?.get(defaultValue) ?? 0;
 
             if (!this.valueUsages.has(parameter.id)) {

Original file line number	Diff line number	Diff line change
`@@ -71,6 +71,14 @@ export class PythonParameter extends PythonDeclaration {`
`71`	`71`	`);`
`72`	`72`	`}`
`73`	`73`
	`74`	`+ isOptional(): boolean {`
	`75`	`+ return this.defaultValue !== null && this.defaultValue !== undefined && this.isExplicitParameter();`
	`76`	`+ }`
	`77`	`+`
	`78`	`+ isRequired(): boolean {`
	`79`	`+ return (this.defaultValue === null \|\| this.defaultValue === undefined) && this.isExplicitParameter();`
	`80`	`+ }`
	`81`	`+`
`74`	`82`	`toString(): string {`
`75`	`83`	return `Parameter "${this.name}"`;
`76`	`84`	`}`