From f9c0c22d858524fd5985b0b3bc41868a3fef83ae Mon Sep 17 00:00:00 2001 From: Dominik Prokop Date: Fri, 10 Apr 2020 13:29:48 +0200 Subject: [PATCH] Add documentation comments for declarative options API (#23495) --- .../grafana-data/src/panel/PanelPlugin.ts | 56 ++++++++++++++++++- .../src/types/OptionsUIRegistryBuilder.ts | 29 ++++++++++ .../grafana-data/src/types/fieldOverrides.ts | 36 ++++++++++++ packages/grafana-data/src/types/panel.ts | 32 +++++++++++ 4 files changed, 152 insertions(+), 1 deletion(-) diff --git a/packages/grafana-data/src/panel/PanelPlugin.ts b/packages/grafana-data/src/panel/PanelPlugin.ts index d6c348d0d12..6b8331e31e6 100644 --- a/packages/grafana-data/src/panel/PanelPlugin.ts +++ b/packages/grafana-data/src/panel/PanelPlugin.ts @@ -16,8 +16,62 @@ import { deprecationWarning } from '../utils'; import { FieldConfigOptionsRegistry, standardFieldConfigEditorRegistry } from '../field'; export interface SetFieldConfigOptionsArgs { + /** + * 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>; + + /** + * 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) => void; } @@ -219,7 +273,7 @@ export class PanelPlugin(ShapePanel) * .useFieldConfig({ * useCustomConfig: builder => { - builder + * builder * .addNumberInput({ * id: 'shapeBorderWidth', * name: 'Border width', diff --git a/packages/grafana-data/src/types/OptionsUIRegistryBuilder.ts b/packages/grafana-data/src/types/OptionsUIRegistryBuilder.ts index 0e21c3660e9..758872fd4e3 100644 --- a/packages/grafana-data/src/types/OptionsUIRegistryBuilder.ts +++ b/packages/grafana-data/src/types/OptionsUIRegistryBuilder.ts @@ -6,11 +6,40 @@ import { NumberFieldConfigSettings, SelectFieldConfigSettings, StringFieldConfig * Option editor registry item */ export interface OptionsEditorItem 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; + /** + * 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; } diff --git a/packages/grafana-data/src/types/fieldOverrides.ts b/packages/grafana-data/src/types/fieldOverrides.ts index 34b4abe8cb9..ad15f871f4e 100644 --- a/packages/grafana-data/src/types/fieldOverrides.ts +++ b/packages/grafana-data/src/types/fieldOverrides.ts @@ -54,13 +54,49 @@ export interface FieldOverrideEditorProps extends Omit { + /** + * 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; } diff --git a/packages/grafana-data/src/types/panel.ts b/packages/grafana-data/src/types/panel.ts index 6c964cd964e..36f9534507a 100644 --- a/packages/grafana-data/src/types/panel.ts +++ b/packages/grafana-data/src/types/panel.ts @@ -119,12 +119,44 @@ export interface PanelOptionsEditorItem, TValue> {} export interface PanelOptionsEditorConfig { + /** + * 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; }