Commit f9c0c22d by Dominik Prokop Committed by GitHub

Add documentation comments for declarative options API (#23495)

parent 3ebba56f
......@@ -16,8 +16,62 @@ import { deprecationWarning } from '../utils';
import { FieldConfigOptionsRegistry, standardFieldConfigEditorRegistry } from '../field';
export interface SetFieldConfigOptionsArgs<TFieldConfigOptions = any> {
/**
* Array of standard field config properties
*
* @example
* ```typescript
* {
* standardOptions: [FieldConfigProperty.Min, FieldConfigProperty.Max, FieldConfigProperty.Unit]
* }
* ```
*/
standardOptions?: FieldConfigProperty[];
/**
* Object specyfing standard option properties default values
*
* @example
* ```typescript
* {
* standardOptionsDefaults: {
* [FieldConfigProperty.Min]: 20,
* [FieldConfigProperty.Max]: 100
* }
* }
* ```
*/
standardOptionsDefaults?: Partial<Record<FieldConfigProperty, any>>;
/**
* Function that allows custom field config properties definition.
*
* @param builder
*
* @example
* ```typescript
* useCustomConfig: builder => {
* builder
* .addNumberInput({
* id: 'shapeBorderWidth',
* name: 'Border width',
* description: 'Border width of the shape',
* settings: {
* min: 1,
* max: 5,
* },
* })
* .addSelect({
* id: 'displayMode',
* name: 'Display mode',
* description: 'How the shape shout be rendered'
* settings: {
* options: [{value: 'fill', label: 'Fill' }, {value: 'transparent', label: 'Transparent }]
* },
* })
* }
* ```
*/
useCustomConfig?: (builder: FieldConfigEditorBuilder<TFieldConfigOptions>) => void;
}
......@@ -219,7 +273,7 @@ export class PanelPlugin<TOptions = any, TFieldConfigOptions extends object = an
* export const plugin = new PanelPlugin<ShapePanelOptions>(ShapePanel)
* .useFieldConfig({
* useCustomConfig: builder => {
builder
* builder
* .addNumberInput({
* id: 'shapeBorderWidth',
* name: 'Border width',
......
......@@ -6,11 +6,40 @@ import { NumberFieldConfigSettings, SelectFieldConfigSettings, StringFieldConfig
* Option editor registry item
*/
export interface OptionsEditorItem<TOptions, TSettings, TEditorProps, TValue> extends RegistryItem {
/**
* Path of the options property to control.
*
* @example
* Given options object of a type:
* ```ts
* interface CustomOptions {
* a: {
* b: string;
* }
* }
* ```
*
* path can be either 'a' or 'a.b'.
*/
path: (keyof TOptions & string) | string;
/**
* React component used to edit the options property
*/
editor: ComponentType<TEditorProps>;
/**
* Custom settings of the editor.
*/
settings?: TSettings;
/**
* Array of strings representing category of the options property.
*/
category?: string[];
defaultValue?: TValue;
/**
* Function that enables configuration of when option editor should be shown based on current options properties.
*
* @param currentConfig Current options values
*/
showIf?: (currentConfig: TOptions) => boolean;
}
......
......@@ -54,13 +54,49 @@ export interface FieldOverrideEditorProps<TValue, TSettings> extends Omit<Standa
}
export interface FieldConfigEditorConfig<TOptions, TSettings = any, TValue = any> {
/**
* Path of the field config property to control.
*
* @example
* Given field config object of a type:
* ```ts
* interface CustomFieldConfig {
* a: {
* b: string;
* }
* }
* ```
*
* path can be either 'a' or 'a.b'.
*/
path: (keyof TOptions & string) | string;
/**
* Name of the field config property. Will be displayed in the UI as form element label.
*/
name: string;
/**
* Description of the field config property. Will be displayed in the UI as form element description.
*/
description: string;
/**
* Array of strings representing category of the field config property. First element in the array will make option render as collapsible section.
*/
category?: string[];
/**
* Custom settings of the editor.
*/
settings?: TSettings;
/**
* Funciton that allows specifying whether or not this field config shuld apply to a given field.
* @param field
*/
shouldApply?: (field: Field) => boolean;
defaultValue?: TValue;
/**
* Function that enables configuration of when field config property editor should be shown based on current panel field config.
*
* @param currentConfig Current field config values
*/
showIf?: (currentConfig: TOptions) => boolean;
}
......
......@@ -119,12 +119,44 @@ export interface PanelOptionsEditorItem<TOptions = any, TValue = any, TSettings
extends OptionsEditorItem<TOptions, TSettings, PanelOptionsEditorProps<TValue>, TValue> {}
export interface PanelOptionsEditorConfig<TOptions, TSettings = any, TValue = any> {
/**
* Path of the option property to control.
*
* @example
* Given options object of a type:
* ```ts
* interface Options {
* a: {
* b: string;
* }
* }
* ```
*
* path can be either 'a' or 'a.b'.
*/
path: (keyof TOptions & string) | string;
/**
* Name of the option. Will be displayed in the UI as form element label.
*/
name: string;
/**
* Description of the option. Will be displayed in the UI as form element description.
*/
description: string;
/**al
* Custom settings of the editor.
*/
settings?: TSettings;
/**
* Array of strings representing category of the option. First element in the array will make option render as collapsible section.
*/
category?: string[];
defaultValue?: TValue;
/**
* Function that enables configuration of when option editor should be shown based on current panel option properties.
*
* @param currentConfig Current panel options
*/
showIf?: (currentConfig: TOptions) => boolean;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment