Document core APIs

ui/components-react/src/components-react/newEditors/Types.ts

@@ -6,13 +6,17 @@ import type { ValueMetadata } from "./values/Metadata.js";
 import type { Value } from "./values/Values.js";
 
 /**
- *
+ * An editor specification defining single editor with a predicate that determines if the editor can be used for a given value.
+ * @beta
  */
 export interface EditorSpec {
   applies: (metaData: ValueMetadata, value: Value | undefined) => boolean;
   Editor: React.ComponentType<EditorProps>;
 }
 
+/**
+ * Base editor props that are supplied to every editor when rendering it.
+ */
 interface BaseEditorProps<TValue = Value> {
   metadata: ValueMetadata;
   onChange: (value: TValue) => void;
@@ -22,16 +26,19 @@ interface BaseEditorProps<TValue = Value> {
 }
 
 /**
- *
+ * Generic editor props that are supplied to the editor for rendering.
+ * @beta
  */
 export interface EditorProps<TValue = Value> extends BaseEditorProps<TValue> {
   value?: TValue;
 }
 
 /**
- *
+ * A type that makes a specific properties required in a type.
+ * @beta
  */
-export interface ConcreteEditorProps<TValue = Value>
-  extends BaseEditorProps<TValue> {
-  value: TValue;
-}
+export type RequiredProps<TProps, TKey extends keyof TProps> = Omit<
+  TProps,
+  TKey
+> &
+  Required<Pick<TProps, TKey>>;

ui/components-react/src/components-react/newEditors/editors/boolean/BooleanEditor.tsx

@@ -8,7 +8,8 @@ import type { EditorProps } from "../../Types.js";
 import { useBooleanEditorProps } from "./UseBooleanEditorProps.js";
 
 /**
- *
+ * Simple editor for editing boolean values.
+ * @beta
  */
 export function BooleanEditor(props: EditorProps) {
   const { value, onChange, onFinish, size, disabled } =

ui/components-react/src/components-react/newEditors/editors/boolean/UseBooleanEditorProps.ts

@@ -3,18 +3,19 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 
-import type { ConcreteEditorProps, EditorProps } from "../../Types.js";
+import type { EditorProps, RequiredProps } from "../../Types.js";
 import type { BooleanValue, Value } from "../../values/Values.js";
 import { isBooleanValue } from "../../values/Values.js";
 
 /**
- *
+ * Hooks that converts generic `EditorProps` into editor props with boolean value. If value is not boolean, it will be converted into `false`.
+ * @beta
  */
 export function useBooleanEditorProps({
   value,
   onChange,
   ...rest
-}: EditorProps): ConcreteEditorProps<BooleanValue> {
+}: EditorProps): RequiredProps<EditorProps<BooleanValue>, "value"> {
   return {
     ...rest,
     value: getBooleanValue(value),

ui/components-react/src/components-react/newEditors/editors/date/DateTimeEditor.tsx

@@ -5,14 +5,15 @@
 import * as React from "react";
 import { Button, DatePicker, Popover } from "@itwin/itwinui-react";
 import type { EditorProps } from "../../Types.js";
-import { useDateTimeEditorProps } from "./UseDateTimeEditorProps.js";
+import { useDateEditorProps } from "./UseDateEditorProps.js";
 
 /**
- *
+ * Simple editor for editing date values.
+ * @beta
  */
-export function DateTimeEditor(props: EditorProps) {
+export function DateEditor(props: EditorProps) {
   const { value, onChange, onFinish, size, disabled } =
-    useDateTimeEditorProps(props);
+    useDateEditorProps(props);
   const dateStr = value.value.toLocaleDateString();
 
   return (

ui/components-react/src/components-react/newEditors/editors/date/UseDateEditorProps.ts

@@ -0,0 +1,28 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+
+import type { EditorProps, RequiredProps } from "../../Types.js";
+import type { DateValue, Value } from "../../values/Values.js";
+import { isDateValue } from "../../values/Values.js";
+
+/**
+ * Hooks that converts generic `EditorProps` into editor props with date value. If value is not date time, it will be converted into current date.
+ * @beta
+ */
+export function useDateEditorProps({
+  value,
+  onChange,
+  ...rest
+}: EditorProps): RequiredProps<EditorProps<DateValue>, "value"> {
+  return {
+    ...rest,
+    value: getDateValue(value),
+    onChange,
+  };
+}
+
+function getDateValue(value: Value | undefined): DateValue {
+  return value && isDateValue(value) ? value : { value: new Date() };
+}

ui/components-react/src/components-react/newEditors/editors/enum/EnumEditor.tsx

@@ -8,7 +8,8 @@ import type { EditorProps } from "../../Types.js";
 import { useEnumEditorProps } from "./UseEnumEditorProps.js";
 
 /**
- *
+ * Simple editor for editing enum values.
+ * @beta
  */
 export function EnumEditor(props: EditorProps) {
   const { value, onChange, onFinish, choices, disabled, size } =

ui/components-react/src/components-react/newEditors/editors/enum/UseEnumEditorProps.ts

@@ -3,20 +3,23 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 
-import type { ConcreteEditorProps, EditorProps } from "../../Types.js";
-import type { EnumValueMetadata } from "../../values/Metadata.js";
-import type { EnumChoice, EnumValue, Value } from "../../values/Values.js";
+import type { EditorProps, RequiredProps } from "../../Types.js";
+import type { EnumChoice, EnumValueMetadata } from "../../values/Metadata.js";
+import type { EnumValue, Value } from "../../values/Values.js";
 import { isEnumValue } from "../../values/Values.js";
 
 /**
- *
+ * Hooks that converts generic `EditorProps` into editor props with enum value. If value is not enum, it will be converted into empty enum value.
+ * @beta
  */
 export function useEnumEditorProps({
   metadata,
   value,
   onChange,
   ...rest
-}: EditorProps): ConcreteEditorProps<EnumValue> & { choices: EnumChoice[] } {
+}: EditorProps): RequiredProps<EditorProps<EnumValue>, "value"> & {
+  choices: EnumChoice[];
+} {
   const choices =
     metadata.type === "enum" ? (metadata as EnumValueMetadata).choices : [];
 

ui/components-react/src/components-react/newEditors/editors/numeric/FormattedNumericInput.tsx

@@ -6,18 +6,23 @@ import * as React from "react";
 import { Input } from "@itwin/itwinui-react";
 import type { NumericValue } from "../../values/Values.js";
 
+/**
+ * Props for FormattedNumericInput component.
+ * @beta
+ */
 interface FormattedNumericInputProps {
   value: NumericValue;
   onChange: (value: NumericValue) => void;
   parseValue: (value: string) => number | undefined;
   formatValue: (num: number) => string;
+  onBlur: () => void;
   disabled?: boolean;
   size?: "small" | "large";
-  onBlur: () => void;
 }
 
 /**
- *
+ * A numeric input that allows to pass custom parsing/formatting logic to handle values with units etc.
+ * @beta
  */
 export function FormattedNumericInput({
   onChange,

ui/components-react/src/components-react/newEditors/editors/numeric/NumericEditor.tsx

@@ -8,7 +8,8 @@ import type { EditorProps } from "../../Types.js";
 import { useNumericEditorProps } from "./UseNumericEditorProps.js";
 
 /**
- *
+ * Simple editor for editing numeric values.
+ * @beta
  */
 export function NumericEditor(props: EditorProps) {
   const { value, onChange, onFinish, size, disabled } =

ui/components-react/src/components-react/newEditors/editors/numeric/QuantityInput.tsx

@@ -1,3 +1,7 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
 import * as React from "react";
 import { FormattedNumericInput } from "./FormattedNumericInput.js";
 import type { FormatterSpec, ParserSpec } from "@itwin/core-quantity";
@@ -16,7 +20,8 @@ interface QuantityInputProps
 }
 
 /**
- *
+ * A component that wraps `FormattedNumericInput` and provides a formatter and parser for quantity values.
+ * @beta
  */
 export function QuantityInput({
   formatter,

ui/components-react/src/components-react/newEditors/editors/numeric/UseNumericEditorProps.ts

@@ -3,18 +3,19 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 
-import type { ConcreteEditorProps, EditorProps } from "../../Types.js";
+import type { EditorProps, RequiredProps } from "../../Types.js";
 import type { NumericValue, Value } from "../../values/Values.js";
 import { isNumericValue } from "../../values/Values.js";
 
 /**
- *
+ * Hooks that converts generic `EditorProps` into editor props with numeric value. If value is not numeric, it will be converted into empty numeric value.
+ * @beta
  */
 export function useNumericEditorProps({
   value,
   onChange,
   ...rest
-}: EditorProps): ConcreteEditorProps<NumericValue> {
+}: EditorProps): RequiredProps<EditorProps<NumericValue>, "value"> {
   return {
     ...rest,
     value: getNumericValue(value),

ui/components-react/src/components-react/newEditors/editors/text/TextEditor.tsx

@@ -8,7 +8,8 @@ import type { EditorProps } from "../../Types.js";
 import { useTextEditorProps } from "./UseTextEditorProps.js";
 
 /**
- *
+ * Simple editor for editing text values.
+ * @beta
  */
 export function TextEditor(props: EditorProps) {
   const { value, onChange, onFinish, size, disabled } =

ui/components-react/src/components-react/newEditors/editors/text/UseTextEditorProps.ts

@@ -3,18 +3,19 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 
-import type { ConcreteEditorProps, EditorProps } from "../../Types.js";
+import type { EditorProps, RequiredProps } from "../../Types.js";
 import type { TextValue, Value } from "../../values/Values.js";
 import { isTextValue } from "../../values/Values.js";
 
 /**
- *
+ * Hooks that converts generic `EditorProps` into editor props with text value. If value is not text, it will be converted into empty text value.
+ * @beta
  */
 export function useTextEditorProps({
   value,
   onChange,
   ...rest
-}: EditorProps): ConcreteEditorProps<TextValue> {
+}: EditorProps): RequiredProps<EditorProps<TextValue>, "value"> {
   return {
     ...rest,
     value: getTextValue(value),

ui/components-react/src/components-react/newEditors/editorsRegistry/DefaultEditors.tsx

@@ -2,41 +2,66 @@
  * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
+
 import { BooleanEditor } from "../editors/boolean/BooleanEditor.js";
-import { DateTimeEditor } from "../editors/date/DateTimeEditor.js";
+import { DateEditor } from "../editors/date/DateTimeEditor.js";
 import { EnumEditor } from "../editors/enum/EnumEditor.js";
 import { NumericEditor } from "../editors/numeric/NumericEditor.js";
 import { TextEditor } from "../editors/text/TextEditor.js";
-import { OldEnumEditorSpec } from "../interop/old-editors/enum/Enum.js";
+import { EnumEditorSpec as InterOpEnumEditorSpec } from "../interop/old-editors/enum/Enum.js";
 import { EnumButtonGroupEditorSpec } from "../interop/old-editors/enum/EnumButtonGroup.js";
 
 import type { EditorSpec } from "../Types.js";
 
+/**
+ * Specification for default text editor. It applies for values whose type is "string".
+ * @beta
+ */
 export const TextEditorSpec: EditorSpec = {
   applies: (metadata) => metadata.type === "string",
   Editor: TextEditor,
 };
 
+/**
+ * Specification for default date editor. It applies for values whose type is "date".
+ * @beta
+ */
 export const DateEditorSpec: EditorSpec = {
   applies: (metadata) => metadata.type === "date",
-  Editor: DateTimeEditor,
+  Editor: DateEditor,
 };
 
+/**
+ * Specification for default boolean editor. It applies for values whose type is "bool".
+ * @beta
+ */
 export const BoolEditorSpec: EditorSpec = {
   applies: (metadata) => metadata.type === "bool",
   Editor: BooleanEditor,
 };
 
+/**
+ * Specification for default numeric editor. It applies for values whose type is "number".
+ * @beta
+ */
 export const NumericEditorSpec: EditorSpec = {
   applies: (metadata) => metadata.type === "number",
   Editor: NumericEditor,
 };
 
+/**
+ * Specification for default enum editor. It applies for values whose type is "enum".
+ * @beta
+ */
 export const EnumEditorSpec: EditorSpec = {
   applies: (metadata) => metadata.type === "enum",
   Editor: EnumEditor,
 };
 
+/**
+ * List of default editors that are used as fallback if EditorRegistry does not provide a custom editor.
+ * @internal
+ */
 export const defaultEditors: EditorSpec[] = [
   TextEditorSpec,
   BoolEditorSpec,
@@ -45,8 +70,12 @@ export const defaultEditors: EditorSpec[] = [
   EnumEditorSpec,
 ];
 
-// editors that are rewritten based on the old version that accepts editor params from `PropertyRecord`
+/**
+ * Editors that are rewritten based on the old version that accepts editor params from `PropertyRecord`. Needed to support
+ * editing customizations used through `PropertyRecord`.
+ * @internal
+ */
 export const interopEditors: EditorSpec[] = [
   EnumButtonGroupEditorSpec,
-  OldEnumEditorSpec,
+  InterOpEnumEditorSpec,
 ];