From ace64e23583e3e371b61b2df91d1fb7fa46632cb Mon Sep 17 00:00:00 2001
From: winwin2011 <yjh2011@live.com>
Date: Sat, 7 Oct 2023 14:53:35 +0800
Subject: [PATCH] chore: add docs and fix some pr review issues

---
 packages/carbon/src/AddButton/AddButton.tsx   |  2 ++
 .../ArrayFieldItemTemplate.tsx                |  4 +++
 .../ArrayFieldTemplate/ArrayFieldTemplate.tsx |  4 +++
 .../BaseInputTemplate/BaseInputTemplate.tsx   |  6 ++++
 .../src/CheckboxWidget/CheckboxWidget.tsx     |  5 ++++
 .../src/CheckboxesWidget/CheckboxesWidget.tsx |  5 ++++
 .../src/DescriptionField/DescriptionField.tsx |  4 +++
 .../FieldErrorTemplate/FieldErrorTemplate.tsx |  1 -
 .../src/FieldTemplate/FieldTemplate.tsx       |  5 ++++
 packages/carbon/src/Form/Form.tsx             |  3 ++
 packages/carbon/src/IconButton/IconButton.tsx | 12 ++++++++
 .../ObjectFieldTemplate.tsx                   | 29 +++++++++----------
 .../carbon/src/SubmitButton/SubmitButton.tsx  |  2 ++
 packages/carbon/src/Templates/Templates.ts    |  2 ++
 .../src/TextareaWidget/TextareaWidget.tsx     |  4 +++
 packages/carbon/src/Theme/Theme.tsx           |  2 ++
 packages/carbon/src/TitleField/TitleField.tsx |  4 +++
 packages/carbon/src/Widgets/Widgets.ts        |  2 ++
 .../carbon/src/components/ConditionLabel.tsx  | 22 ++++++++++++--
 packages/carbon/src/components/Layer.tsx      |  4 +++
 packages/carbon/src/contexts.tsx              |  3 ++
 packages/carbon/src/index.ts                  |  1 +
 22 files changed, 107 insertions(+), 19 deletions(-)

diff --git a/packages/carbon/src/AddButton/AddButton.tsx b/packages/carbon/src/AddButton/AddButton.tsx
index 9400cd83cf..2f99618135 100644
--- a/packages/carbon/src/AddButton/AddButton.tsx
+++ b/packages/carbon/src/AddButton/AddButton.tsx
@@ -2,6 +2,8 @@ import { Add } from '@carbon/icons-react';
 import { Button } from '@carbon/react';
 import { FormContextType, IconButtonProps, RJSFSchema, StrictRJSFSchema, TranslatableString } from '@rjsf/utils';
 
+/** The `AddButton` renders a button that represent the `Add` action on a form
+ */
 export default function AddButton<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>({
   uiSchema,
   registry,
diff --git a/packages/carbon/src/ArrayFieldItemTemplate/ArrayFieldItemTemplate.tsx b/packages/carbon/src/ArrayFieldItemTemplate/ArrayFieldItemTemplate.tsx
index 36ce348ff5..1a9c2234b1 100644
--- a/packages/carbon/src/ArrayFieldItemTemplate/ArrayFieldItemTemplate.tsx
+++ b/packages/carbon/src/ArrayFieldItemTemplate/ArrayFieldItemTemplate.tsx
@@ -1,6 +1,10 @@
 import { useMemo } from 'react';
 import { ArrayFieldTemplateItemType, FormContextType, RJSFSchema, StrictRJSFSchema } from '@rjsf/utils';
 
+/** The `ArrayFieldTemplate` component is the template used to render all items in an array.
+ *
+ * @param props - The `ArrayFieldTemplateItemType` props for the component
+ */
 export default function ArrayFieldItemTemplate<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/ArrayFieldTemplate/ArrayFieldTemplate.tsx b/packages/carbon/src/ArrayFieldTemplate/ArrayFieldTemplate.tsx
index 8b0b623cd4..d9a627c0fa 100644
--- a/packages/carbon/src/ArrayFieldTemplate/ArrayFieldTemplate.tsx
+++ b/packages/carbon/src/ArrayFieldTemplate/ArrayFieldTemplate.tsx
@@ -11,6 +11,10 @@ import {
 } from '@rjsf/utils';
 import { Layer, LayerBackground } from '../components/Layer';
 
+/** The `ArrayFieldTemplate` component is the template used to render all items in an array.
+ *
+ * @param props - The `ArrayFieldTemplateItemType` props for the component
+ */
 export default function ArrayFieldTemplate<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/BaseInputTemplate/BaseInputTemplate.tsx b/packages/carbon/src/BaseInputTemplate/BaseInputTemplate.tsx
index e377c08a2b..56f7b7a982 100644
--- a/packages/carbon/src/BaseInputTemplate/BaseInputTemplate.tsx
+++ b/packages/carbon/src/BaseInputTemplate/BaseInputTemplate.tsx
@@ -11,6 +11,12 @@ import {
 import { TextInput } from '@carbon/react';
 import { ConditionLabel } from '../components/ConditionLabel';
 
+/** The `BaseInputTemplate` is the template to use to render the basic `<input>` component for the `core` theme.
+ * It is used as the template for rendering many of the <input> based widgets that differ by `type` and callbacks only.
+ * It can be customized/overridden for other themes or individual implementations as needed.
+ *
+ * @param props - The `WidgetProps` for this template
+ */
 export default function BaseInputTemplate<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/CheckboxWidget/CheckboxWidget.tsx b/packages/carbon/src/CheckboxWidget/CheckboxWidget.tsx
index 6ab8814e57..cc65cb8723 100644
--- a/packages/carbon/src/CheckboxWidget/CheckboxWidget.tsx
+++ b/packages/carbon/src/CheckboxWidget/CheckboxWidget.tsx
@@ -12,6 +12,11 @@ import {
 import { Checkbox } from '@carbon/react';
 import { ConditionLabel } from '../components/ConditionLabel';
 
+/** The `CheckBoxWidget` is a widget for rendering boolean properties.
+ *  It is typically used to represent a boolean.
+ *
+ * @param props - The `WidgetProps` for this component
+ */
 export default function CheckboxWidget<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/CheckboxesWidget/CheckboxesWidget.tsx b/packages/carbon/src/CheckboxesWidget/CheckboxesWidget.tsx
index fca32ff26c..785df57975 100644
--- a/packages/carbon/src/CheckboxesWidget/CheckboxesWidget.tsx
+++ b/packages/carbon/src/CheckboxesWidget/CheckboxesWidget.tsx
@@ -14,6 +14,11 @@ import {
 } from '@rjsf/utils';
 import { ConditionLabel } from '../components/ConditionLabel';
 
+/** The `CheckboxesWidget` is a widget for rendering checkbox groups.
+ *  It is typically used to represent an array of enums.
+ *
+ * @param props - The `WidgetProps` for this component
+ */
 export default function CheckboxesWidget<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/DescriptionField/DescriptionField.tsx b/packages/carbon/src/DescriptionField/DescriptionField.tsx
index ebfba40161..1d56d17b37 100644
--- a/packages/carbon/src/DescriptionField/DescriptionField.tsx
+++ b/packages/carbon/src/DescriptionField/DescriptionField.tsx
@@ -1,5 +1,9 @@
 import { DescriptionFieldProps, FormContextType, RJSFSchema, StrictRJSFSchema } from '@rjsf/utils';
 
+/** The `DescriptionField` is the template to use to render the description of a field
+ *
+ * @param props - The `DescriptionFieldProps` for this component
+ */
 export default function DescriptionField<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/FieldErrorTemplate/FieldErrorTemplate.tsx b/packages/carbon/src/FieldErrorTemplate/FieldErrorTemplate.tsx
index e7ba77039f..e8cdbc337c 100644
--- a/packages/carbon/src/FieldErrorTemplate/FieldErrorTemplate.tsx
+++ b/packages/carbon/src/FieldErrorTemplate/FieldErrorTemplate.tsx
@@ -10,7 +10,6 @@ export default function FieldErrorTemplate<
   F extends FormContextType = any
 >(props: FieldErrorProps<T, S, F>) {
   const { errors = [], idSchema } = props;
-  console.log('FieldErrorTemplate errors', errors);
   if (errors.length === 0) {
     return null;
   }
diff --git a/packages/carbon/src/FieldTemplate/FieldTemplate.tsx b/packages/carbon/src/FieldTemplate/FieldTemplate.tsx
index 08bf3ccdce..80d5d2d0c6 100644
--- a/packages/carbon/src/FieldTemplate/FieldTemplate.tsx
+++ b/packages/carbon/src/FieldTemplate/FieldTemplate.tsx
@@ -7,6 +7,11 @@ import {
   StrictRJSFSchema,
 } from '@rjsf/utils';
 
+/** The `FieldTemplate` component is the template used by `SchemaField` to render any field. It renders the field
+ * content, (label, description, children, errors and help) inside of a `WrapIfAdditional` component.
+ *
+ * @param props - The `FieldTemplateProps` for this component
+ */
 export default function FieldTemplate<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/Form/Form.tsx b/packages/carbon/src/Form/Form.tsx
index 56cf4ef28a..c301ea124f 100644
--- a/packages/carbon/src/Form/Form.tsx
+++ b/packages/carbon/src/Form/Form.tsx
@@ -3,6 +3,9 @@ import { withTheme, FormProps } from '@rjsf/core';
 import { generateTheme } from '../Theme';
 import { FormContextType, RJSFSchema, StrictRJSFSchema } from '@rjsf/utils';
 
+/** Generate a `Form` component that is customized with the `carbon` theme.
+ *
+ */
 export function generateForm<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/IconButton/IconButton.tsx b/packages/carbon/src/IconButton/IconButton.tsx
index 66829d1f32..c13bd66f9f 100644
--- a/packages/carbon/src/IconButton/IconButton.tsx
+++ b/packages/carbon/src/IconButton/IconButton.tsx
@@ -3,6 +3,9 @@ import { FormContextType, IconButtonProps, RJSFSchema, StrictRJSFSchema, Transla
 import { Button } from '@carbon/react';
 import { Copy, ArrowDown, ArrowUp, TrashCan } from '@carbon/icons-react';
 
+/** The `CopyButton` is used to render a copy action on a `Form` for elements in an array.
+ * @param props - The `IconButtonProps` props
+ */
 export function CopyButton<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(
   props: IconButtonProps<T, S, F>
 ) {
@@ -21,6 +24,9 @@ export function CopyButton<T = any, S extends StrictRJSFSchema = RJSFSchema, F e
   );
 }
 
+/** The `MoveDownButton` is used to render a move down action on a `Form` for elements in an array.
+ * @param props - The `IconButtonProps` props
+ */
 export function MoveDownButton<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(
   props: IconButtonProps<T, S, F>
 ) {
@@ -39,6 +45,9 @@ export function MoveDownButton<T = any, S extends StrictRJSFSchema = RJSFSchema,
   );
 }
 
+/** The `MoveUpButton` is used to render a move up action on a `Form` for elements in an array.
+ * @param props - The `IconButtonProps` props
+ */
 export function MoveUpButton<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(
   props: IconButtonProps<T, S, F>
 ) {
@@ -57,6 +66,9 @@ export function MoveUpButton<T = any, S extends StrictRJSFSchema = RJSFSchema, F
   );
 }
 
+/** The `RemoveButton` is used to render a remove action on a `Form` for both a existing `additionalProperties` element for an object or an existing element in an array.
+ * @param props - The `IconButtonProps` props
+ */
 export function RemoveButton<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(
   props: IconButtonProps<T, S, F>
 ) {
diff --git a/packages/carbon/src/ObjectFieldTemplate/ObjectFieldTemplate.tsx b/packages/carbon/src/ObjectFieldTemplate/ObjectFieldTemplate.tsx
index 4e448eda67..a7bf16b20c 100644
--- a/packages/carbon/src/ObjectFieldTemplate/ObjectFieldTemplate.tsx
+++ b/packages/carbon/src/ObjectFieldTemplate/ObjectFieldTemplate.tsx
@@ -1,5 +1,5 @@
 // @ts-expect-error there's no type definition for Stack
-import { Button, Stack } from '@carbon/react';
+import { Stack } from '@carbon/react';
 import {
   canExpand,
   descriptionId,
@@ -10,12 +10,16 @@ import {
   RJSFSchema,
   StrictRJSFSchema,
   titleId,
-  TranslatableString,
 } from '@rjsf/utils';
 import { useCarbonOptions } from '../contexts';
 import { Layer, LayerBackground } from '../components/Layer';
-import { Add } from '@carbon/icons-react';
 
+/** The `ObjectFieldTemplate` is the template to use to render all the inner properties of an object along with the
+ * title and description if available. If the object is expandable, then an `AddButton` is also rendered after all
+ * the properties.
+ *
+ * @param props - The `ObjectFieldTemplateProps` for this component
+ */
 export default function ObjectFieldTemplate<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
@@ -37,7 +41,6 @@ export default function ObjectFieldTemplate<
   } = props;
   const uiOptions = getUiOptions<T, S, F>(uiSchema);
   const carbonOptions = useCarbonOptions();
-  const { translateString } = registry;
   const TitleFieldTemplate = getTemplate<'TitleFieldTemplate', T, S, F>('TitleFieldTemplate', registry, uiOptions);
   const DescriptionFieldTemplate = getTemplate<'DescriptionFieldTemplate', T, S, F>(
     'DescriptionFieldTemplate',
@@ -45,9 +48,9 @@ export default function ObjectFieldTemplate<
     uiOptions
   );
   // Button templates are not overridden in the uiSchema
-  // const {
-  //   ButtonTemplates: { AddButton },
-  // } = registry.templates;
+  const {
+    ButtonTemplates: { AddButton },
+  } = registry.templates;
 
   return (
     <>
@@ -80,17 +83,13 @@ export default function ObjectFieldTemplate<
             </Layer>
           )}
           {canExpand(schema, uiSchema, formData) && (
-            <Button
-              size='sm'
-              kind='tertiary'
-              renderIcon={Add}
-              disabled={disabled || readonly}
+            <AddButton
               onClick={onAddClick(schema)}
+              disabled={disabled || readonly}
+              className='object-property-expand'
               uiSchema={uiSchema}
               registry={registry}
-            >
-              {translateString(TranslatableString.AddItemButton)}
-            </Button>
+            />
           )}
         </Stack>
       </LayerBackground>
diff --git a/packages/carbon/src/SubmitButton/SubmitButton.tsx b/packages/carbon/src/SubmitButton/SubmitButton.tsx
index 3e9c82ece7..749da89974 100644
--- a/packages/carbon/src/SubmitButton/SubmitButton.tsx
+++ b/packages/carbon/src/SubmitButton/SubmitButton.tsx
@@ -1,6 +1,8 @@
 import { Button } from '@carbon/react';
 import { FormContextType, getSubmitButtonOptions, RJSFSchema, StrictRJSFSchema, SubmitButtonProps } from '@rjsf/utils';
 
+/** The `SubmitButton` renders a button that represent the `Submit` action on a form
+ */
 export default function SubmitButton<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/Templates/Templates.ts b/packages/carbon/src/Templates/Templates.ts
index 5ca0dda5b4..933b8d09b6 100644
--- a/packages/carbon/src/Templates/Templates.ts
+++ b/packages/carbon/src/Templates/Templates.ts
@@ -12,6 +12,8 @@ import TitleField from '../TitleField';
 import ArrayFieldTemplate from '../ArrayFieldTemplate';
 import ArrayFieldItemTemplate from '../ArrayFieldItemTemplate';
 
+/** Generates a set of templates `carbon` theme uses.
+ */
 export function generateTemplates<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/TextareaWidget/TextareaWidget.tsx b/packages/carbon/src/TextareaWidget/TextareaWidget.tsx
index df2b36b294..40c1188b7a 100644
--- a/packages/carbon/src/TextareaWidget/TextareaWidget.tsx
+++ b/packages/carbon/src/TextareaWidget/TextareaWidget.tsx
@@ -3,6 +3,10 @@ import { ariaDescribedByIds, FormContextType, RJSFSchema, StrictRJSFSchema, Widg
 import { TextArea } from '@carbon/react';
 import { ConditionLabel } from '../components/ConditionLabel';
 
+/** The `TextareaWidget` is a widget for rendering input fields as textarea.
+ *
+ * @param props - The `WidgetProps` for this component
+ */
 export default function TextareaWidget<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/Theme/Theme.tsx b/packages/carbon/src/Theme/Theme.tsx
index 2b0a22f938..3dcaec6371 100644
--- a/packages/carbon/src/Theme/Theme.tsx
+++ b/packages/carbon/src/Theme/Theme.tsx
@@ -4,6 +4,8 @@ import { FormContextType, RJSFSchema, StrictRJSFSchema } from '@rjsf/utils';
 import { generateTemplates } from '../Templates';
 import { generateWidgets } from '../Widgets';
 
+/** Generates a theme for the Carbon Design System
+ */
 export function generateTheme<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/TitleField/TitleField.tsx b/packages/carbon/src/TitleField/TitleField.tsx
index dda3b4b26a..c312c830b1 100644
--- a/packages/carbon/src/TitleField/TitleField.tsx
+++ b/packages/carbon/src/TitleField/TitleField.tsx
@@ -1,6 +1,10 @@
 import { FormContextType, RJSFSchema, StrictRJSFSchema, TitleFieldProps } from '@rjsf/utils';
 import { ConditionLabel } from '../components/ConditionLabel';
 
+/** The `TitleField` is the template to use to render the title of a field
+ *
+ * @param props - The `TitleFieldProps` for this component
+ */
 export default function TitleField<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>({
   id,
   title,
diff --git a/packages/carbon/src/Widgets/Widgets.ts b/packages/carbon/src/Widgets/Widgets.ts
index 27d4f09519..953fbfc9dc 100644
--- a/packages/carbon/src/Widgets/Widgets.ts
+++ b/packages/carbon/src/Widgets/Widgets.ts
@@ -3,6 +3,8 @@ import TextareaWidget from '../TextareaWidget';
 import CheckboxWidget from '../CheckboxWidget';
 import CheckboxesWidget from '../CheckboxesWidget';
 
+/** Generates a set of widgets `carbon` theme uses.
+ */
 export function generateWidgets<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,
diff --git a/packages/carbon/src/components/ConditionLabel.tsx b/packages/carbon/src/components/ConditionLabel.tsx
index 36cf42c89c..7491df9242 100644
--- a/packages/carbon/src/components/ConditionLabel.tsx
+++ b/packages/carbon/src/components/ConditionLabel.tsx
@@ -1,7 +1,13 @@
 import { ReactNode } from 'react';
 import { CarbonOptionsContextType, useCarbonOptions } from '../contexts';
 
-function getMark(required: boolean, labelMark: CarbonOptionsContextType['labelMark']) {
+/** Get the mark for the label, marking it as required or optional
+ *
+ * @param required - Whether the field is required
+ * @param labelMark - The label mark type
+ * @returns
+ */
+function getMark(required: boolean, labelMark: CarbonOptionsContextType['labelMark']): ReactNode {
   if (required && labelMark === 'required') {
     return ' (required)';
   }
@@ -11,12 +17,22 @@ function getMark(required: boolean, labelMark: CarbonOptionsContextType['labelMa
   return null;
 }
 
-export function ConditionLabel({ hide, required, label }: { label: ReactNode; hide?: boolean; required?: boolean }) {
+/** The `ConditionLabel` render a label conditionally and append a required or optional mark
+ */
+export function ConditionLabel({
+  hide = false,
+  required = false,
+  label,
+}: {
+  label: ReactNode;
+  hide?: boolean;
+  required?: boolean;
+}) {
   const carbonOptions = useCarbonOptions();
   if (hide) {
     return null;
   }
-  const mark = getMark(required ?? false, carbonOptions.labelMark);
+  const mark = getMark(required, carbonOptions.labelMark);
   return (
     <>
       {label}
diff --git a/packages/carbon/src/components/Layer.tsx b/packages/carbon/src/components/Layer.tsx
index 8a9884bb8b..6eb555b7d5 100644
--- a/packages/carbon/src/components/Layer.tsx
+++ b/packages/carbon/src/components/Layer.tsx
@@ -3,6 +3,8 @@ import { Layer as CarbonLayer } from '@carbon/react';
 import { ReactNode } from 'react';
 import { NestDepth, useNestDepth } from '../contexts';
 
+/** The `Layer` render [a carbon layer](https://carbondesignsystem.com/guidelines/color/usage#layering-tokens), in order to create a visual hierarchy
+ */
 export function Layer({ children }: { children: ReactNode }) {
   const nestDepth = useNestDepth();
   return (
@@ -12,6 +14,8 @@ export function Layer({ children }: { children: ReactNode }) {
   );
 }
 
+/** The `LayerBackground` render a background for [a carbon layer](https://carbondesignsystem.com/guidelines/color/usage#layering-tokens)
+ */
 export function LayerBackground({ children }: { children: ReactNode }) {
   const nestDepth = useNestDepth();
   return (
diff --git a/packages/carbon/src/contexts.tsx b/packages/carbon/src/contexts.tsx
index 3ec985a7d1..9ada348fb9 100644
--- a/packages/carbon/src/contexts.tsx
+++ b/packages/carbon/src/contexts.tsx
@@ -25,6 +25,9 @@ export function useCarbonOptions() {
 
 export const NestDepthContext = createContext<number>(0);
 
+/**
+ * Get the current nest depth, used for rendering proper [carbon layers](https://carbondesignsystem.com/guidelines/color/usage#layering-tokens)
+ */
 export function useNestDepth() {
   return useContext(NestDepthContext);
 }
diff --git a/packages/carbon/src/index.ts b/packages/carbon/src/index.ts
index 0140b3f0ef..f077d79a89 100644
--- a/packages/carbon/src/index.ts
+++ b/packages/carbon/src/index.ts
@@ -4,6 +4,7 @@ export { default as Form, generateForm } from './Form';
 export { default as Templates, generateTemplates } from './Templates';
 export { default as Theme, generateTheme } from './Theme';
 export { default as Widgets, generateWidgets } from './Widgets';
+export { Layer, LayerBackground } from './components/Layer';
 
 export { CarbonOptionsProvider, useCarbonOptions } from './contexts';
 export type { CarbonOptionsContextType } from './contexts';