Add Code Parameters Builder

packages/components/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## 1.6.0 (2024-02-29)
+
+### Features
+
+- Add Code Parameters Builder (#32)
+
 ## 1.5.0 (2024-02-28)
 
 ### Features

packages/components/README.md

@@ -11,6 +11,10 @@
 - `useFormBuilder` allows to create declarative forms.
 - `createUseDataHook` allows to create `useData` hook to get data through data source api.
 
+### Utils
+
+- `CodeParametersBuilder` allows to create parameters for custom code.
+
 ## Update Grafana Styles
 
 1. Clone and build Grafana locally.

packages/components/package.json

@@ -83,5 +83,5 @@
     "typecheck": "tsc --emitDeclarationOnly false --noEmit"
   },
   "types": "dist/index.d.ts",
-  "version": "1.5.0"
+  "version": "1.6.0"
 }

packages/components/src/index.ts

@@ -3,5 +3,6 @@ import { TEST_IDS } from './constants';
 export * from './components';
 export { createUseDataHook, useFormBuilder } from './hooks';
 export * from './types';
+export { CodeParameterItem, CodeParametersBuilder } from './utils';
 
 export const formSelectors = TEST_IDS.form;

packages/components/src/utils/code-parameters-builder.test.ts

@@ -0,0 +1,80 @@
+import { CodeEditorSuggestionItemKind } from '@grafana/ui';
+
+import { CodeParameterItem, CodeParametersBuilder } from './code-parameters-builder';
+
+describe('CodeParametersBuilder', () => {
+  const parameters = new CodeParametersBuilder({
+    detail: 'all object and methods',
+    items: {
+      grafana: {
+        detail: 'grafana object',
+        items: {
+          method: new CodeParameterItem<() => null>('grafana method', CodeEditorSuggestionItemKind.Method),
+          value: new CodeParameterItem<string>('grafana value', CodeEditorSuggestionItemKind.Property),
+        },
+      },
+      panel: {
+        detail: 'panel object',
+        items: {
+          id: new CodeParameterItem<number>('panel id', CodeEditorSuggestionItemKind.Property),
+        },
+      },
+      element: new CodeParameterItem<HTMLElement>('element', CodeEditorSuggestionItemKind.Property),
+    },
+  });
+
+  it('Should build suggestions', () => {
+    expect(parameters.suggestions).toEqual([
+      {
+        detail: 'all object and methods',
+        kind: CodeEditorSuggestionItemKind.Constant,
+        label: 'context',
+      },
+      {
+        detail: 'grafana object',
+        kind: CodeEditorSuggestionItemKind.Property,
+        label: 'context.grafana',
+      },
+      {
+        detail: 'grafana method',
+        kind: CodeEditorSuggestionItemKind.Method,
+        label: 'context.grafana.method',
+      },
+      {
+        detail: 'grafana value',
+        kind: CodeEditorSuggestionItemKind.Property,
+        label: 'context.grafana.value',
+      },
+      {
+        detail: 'panel object',
+        kind: CodeEditorSuggestionItemKind.Property,
+        label: 'context.panel',
+      },
+      {
+        detail: 'panel id',
+        kind: CodeEditorSuggestionItemKind.Property,
+        label: 'context.panel.id',
+      },
+      {
+        detail: 'element',
+        kind: CodeEditorSuggestionItemKind.Property,
+        label: 'context.element',
+      },
+    ]);
+  });
+
+  it('Should validate types', () => {
+    const payload = {
+      grafana: {
+        method: () => null,
+        value: 'hello',
+      },
+      panel: {
+        id: 123,
+      },
+      element: document.createElement('div'),
+    };
+
+    expect(parameters.create(payload)).toEqual(payload);
+  });
+});

packages/components/src/utils/code-parameters-builder.ts

@@ -0,0 +1,114 @@
+import { CodeEditorSuggestionItem, CodeEditorSuggestionItemKind } from '@grafana/ui';
+
+/**
+ * Code Parameter Group
+ */
+interface CodeParameterGroup {
+  /**
+   * Detail
+   *
+   * @type {string}
+   */
+  detail: string;
+
+  /**
+   * Items
+   */
+  items: Record<string, CodeParameterGroup | CodeParameterItem>;
+}
+
+/**
+ * Parameter Item
+ */
+export class CodeParameterItem<TValue = unknown> {
+  /**
+   * Specify for type validation
+   */
+  value: TValue = {} as TValue;
+
+  constructor(
+    public detail: string,
+    public kind: CodeEditorSuggestionItemKind = CodeEditorSuggestionItemKind.Property
+  ) {}
+}
+
+/**
+ * Convert group to payload object
+ */
+type PayloadForGroup<TGroup extends CodeParameterGroup> = {
+  [Key in keyof TGroup['items']]: TGroup['items'][Key] extends CodeParameterGroup
+    ? PayloadForGroup<TGroup['items'][Key]>
+    : TGroup['items'][Key] extends CodeParameterItem
+      ? TGroup['items'][Key]['value']
+      : unknown;
+};
+
+/**
+ * Code Parameters Builder
+ */
+export class CodeParametersBuilder<TGroup extends CodeParameterGroup> {
+  /**
+   * Built Suggestions based on config
+   */
+  suggestions: CodeEditorSuggestionItem[] = [];
+
+  constructor(group: TGroup, basePath = 'context') {
+    /**
+     * Add base suggestion
+     */
+    this.suggestions.push({
+      label: basePath,
+      kind: CodeEditorSuggestionItemKind.Constant,
+      detail: group.detail,
+    });
+
+    /**
+     * Add all suggestions
+     */
+    this.addSuggestions(basePath, group);
+  }
+
+  /**
+   * Add suggestions
+   * @param path
+   * @param group
+   * @private
+   */
+  private addSuggestions(path: string, group: CodeParameterGroup) {
+    Object.entries(group.items).forEach(([key, item]) => {
+      const itemPath = `${path}.${key}`;
+
+      /**
+       * Group
+       */
+      if ('items' in item) {
+        this.suggestions.push({
+          label: itemPath,
+          detail: item.detail,
+          kind: CodeEditorSuggestionItemKind.Property,
+        });
+
+        this.addSuggestions(itemPath, item);
+
+        return;
+      }
+
+      /**
+       * Item
+       */
+      this.suggestions.push({
+        label: itemPath,
+        detail: item.detail,
+        kind: item.kind,
+      });
+    });
+  }
+
+  /**
+   * Create payload method for type validation
+   * @param payload
+   */
+  create(payload: PayloadForGroup<TGroup>) {
+    return payload;
+  }
+}

packages/components/src/utils/index.ts

@@ -1 +1,2 @@
+export * from './code-parameters-builder';
 export * from './form-builder';