chore: add docs and fix some pr review issues

Author: YuJianghao

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,

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,

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,

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,

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,

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,

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,

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;
   }

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,

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,

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>
 ) {

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,17 +41,16 @@ 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',
     registry,
     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>

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,

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,

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,

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,

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,

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,

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}

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 (

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);
 }

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';