feat(work-items): add query editor for SystemLink Work Items data source

src/datasources/work-items/WorkItemsDataSource.test.ts

@@ -0,0 +1,64 @@
+import { WorkItemsDataSource } from './WorkItemsDataSource';
+import { setupDataSource } from 'test/fixtures';
+import { OrderByOptions, OutputType, WorkItemTypeOptions } from './types';
+
+describe('WorkItemsDataSource', () => {
+  it('applies expected default query values', () => {
+    const [ds] = setupDataSource(WorkItemsDataSource);
+
+    const query = ds.prepareQuery({ refId: 'A' });
+
+    expect(query.outputType).toBe(OutputType.Properties);
+    expect(query.types).toEqual([WorkItemTypeOptions.All]);
+    expect(query.orderBy).toBe(OrderByOptions.UPDATED_AT);
+    expect(query.descending).toBe(true);
+    expect(query.take).toBe(1000);
+  });
+
+  it('normalizes invalid types and preserves explicit take values', () => {
+    const [ds] = setupDataSource(WorkItemsDataSource);
+
+    const query = ds.prepareQuery({
+      refId: 'A',
+      types: [],
+      take: 12000,
+    });
+
+    expect(query.types).toEqual([WorkItemTypeOptions.All]);
+    expect(query.take).toBe(12000);
+  });
+
+  it('defaults take when it is negative or not finite', () => {
+    const [ds] = setupDataSource(WorkItemsDataSource);
+
+    const negativeTakeQuery = ds.prepareQuery({ refId: 'A', take: -1 });
+    const nanTakeQuery = ds.prepareQuery({ refId: 'A', take: Number.NaN });
+
+    expect(negativeTakeQuery.take).toBe(1000);
+    expect(nanTakeQuery.take).toBe(1000);
+  });
+
+  it('returns a placeholder frame', async () => {
+    const [ds] = setupDataSource(WorkItemsDataSource);
+
+    const result = await ds.runQuery({ refId: 'A' }, { scopedVars: {} } as any);
+    expect(result.fields[0].name).toBe('message');
+  });
+
+  it('tests datasource connection against the work-items service endpoint', async () => {
+    const [ds] = setupDataSource(WorkItemsDataSource);
+    const postSpy = jest.spyOn(ds, 'post').mockResolvedValue({} as any);
+
+    const result = await ds.testDatasource();
+
+    expect(postSpy).toHaveBeenCalledWith('/niworkitem/v1/query-workitems', { take: 1 });
+    expect(result.status).toBe('success');
+  });
+
+  it('bubbles up exception when datasource connectivity check fails', async () => {
+    const [ds] = setupDataSource(WorkItemsDataSource);
+    jest.spyOn(ds, 'post').mockRejectedValue(new Error('Failed'));
+
+    await expect(ds.testDatasource()).rejects.toThrow('Failed');
+  });
+});

src/datasources/work-items/WorkItemsDataSource.ts

@@ -0,0 +1,90 @@
+import {
+  DataFrameDTO,
+  DataQueryRequest,
+  DataSourceInstanceSettings,
+  FieldType,
+  MetricFindValue,
+  TestDataSourceResponse,
+} from '@grafana/data';
+import { BackendSrv, TemplateSrv, getBackendSrv, getTemplateSrv } from '@grafana/runtime';
+import { DataSourceBase } from 'core/DataSourceBase';
+import {
+  OrderByOptions,
+  OutputType,
+  WorkItemsDataSourceOptions,
+  WorkItemsQuery,
+  WorkItemTypeOptions,
+} from './types';
+
+export class WorkItemsDataSource extends DataSourceBase<WorkItemsQuery, WorkItemsDataSourceOptions> {
+  constructor(
+    readonly instanceSettings: DataSourceInstanceSettings<WorkItemsDataSourceOptions>,
+    readonly backendSrv: BackendSrv = getBackendSrv(),
+    readonly templateSrv: TemplateSrv = getTemplateSrv()
+  ) {
+    super(instanceSettings, backendSrv, templateSrv);
+  }
+
+  baseUrl = `${this.instanceSettings.url}/niworkitem/v1`;
+  queryWorkItemsUrl = `${this.baseUrl}/query-workitems`;
+
+  defaultQuery = {
+    outputType: OutputType.Properties,
+    types: [WorkItemTypeOptions.All],
+    orderBy: OrderByOptions.UPDATED_AT,
+    descending: true,
+    take: 1000,
+  };
+
+  public prepareQuery(query: WorkItemsQuery): WorkItemsQuery {
+    const prepared = super.prepareQuery(query);
+
+    return {
+      ...prepared,
+      outputType: prepared.outputType ?? this.defaultQuery.outputType,
+      orderBy: prepared.orderBy ?? this.defaultQuery.orderBy,
+      descending: prepared.descending ?? this.defaultQuery.descending,
+      types: this.normalizeTypes(prepared.types),
+      take: this.normalizeTake(prepared.take),
+    };
+  }
+
+  isTypesValid(types?: WorkItemTypeOptions[]): boolean {
+    return Boolean(types && types.length > 0);
+  }
+
+  normalizeTypes(types?: WorkItemTypeOptions[]): WorkItemTypeOptions[] {
+    return this.isTypesValid(types) ? [...types!] : [...this.defaultQuery.types];
+  }
+
+  normalizeTake(take?: number): number {
+    return Number.isFinite(take) && (take as number) >= 0 ? (take as number) : this.defaultQuery.take;
+  }
+
+  async runQuery(query: WorkItemsQuery, _options: DataQueryRequest<WorkItemsQuery>): Promise<DataFrameDTO> {
+    return {
+      refId: query.refId,
+      name: query.refId,
+      fields: [
+        {
+          name: 'message',
+          type: FieldType.string,
+          values: ['Work Items datasource query implementation will be added in follow-up stories.'],
+        },
+      ],
+    };
+  }
+
+  shouldRunQuery(query: WorkItemsQuery): boolean {
+    return !query.hide;
+  }
+
+  async testDatasource(): Promise<TestDataSourceResponse> {
+    await this.post(this.queryWorkItemsUrl, { take: 1 });
+    return { status: 'success', message: 'Data source connected and authentication successful!' };
+  }
+
+  async metricFindQuery(): Promise<MetricFindValue[]> {
+    return [];
+  }
+}

src/datasources/work-items/components/WorkItemsQueryEditor.test.tsx

@@ -0,0 +1,48 @@
+import { fireEvent } from '@testing-library/react';
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { setupRenderer } from 'test/fixtures';
+import { takeErrorMessages } from '../constants/QueryEditor.constants';
+import { WorkItemsDataSource } from '../WorkItemsDataSource';
+import { OutputType } from '../types';
+import { WorkItemsQueryEditor } from './WorkItemsQueryEditor';
+
+describe('WorkItemsQueryEditor', () => {
+  it('renders controls', () => {
+    const render = setupRenderer(WorkItemsQueryEditor, WorkItemsDataSource);
+
+    render({});
+
+    expect(screen.getByRole('radio', { name: OutputType.Properties })).toBeTruthy();
+    expect(screen.getByRole('radio', { name: OutputType.TotalCount })).toBeTruthy();
+    expect(screen.getByText('Type')).toBeTruthy();
+    expect(screen.getByText('OrderBy')).toBeTruthy();
+    expect(screen.getByText('Descending')).toBeTruthy();
+    expect(screen.getByText('Take')).toBeTruthy();
+  });
+
+  it('hides properties-only controls for total count output', async () => {
+    const render = setupRenderer(WorkItemsQueryEditor, WorkItemsDataSource);
+
+    render({});
+    await userEvent.click(screen.getByRole('radio', { name: OutputType.TotalCount }));
+
+    expect(screen.queryByText('OrderBy')).toBeNull();
+    expect(screen.queryByText('Descending')).toBeNull();
+    expect(screen.queryByText('Take')).toBeNull();
+  });
+
+  it('shows take validation error and suppresses query execution for invalid take input', () => {
+    const render = setupRenderer(WorkItemsQueryEditor, WorkItemsDataSource);
+
+    const [onChange, onRunQuery] = render({});
+    const takeInput = screen.getByRole('spinbutton');
+
+    fireEvent.change(takeInput, { target: { value: '-5' } });
+    fireEvent.blur(takeInput);
+
+    expect(screen.getByText(takeErrorMessages.greaterOrEqualToZero)).toBeTruthy();
+    expect(onChange).not.toHaveBeenCalled();
+    expect(onRunQuery).not.toHaveBeenCalled();
+  });
+});

src/datasources/work-items/components/WorkItemsQueryEditor.tsx

@@ -0,0 +1,135 @@
+import React, { useCallback, useMemo, useState } from 'react';
+import { QueryEditorProps, SelectableValue } from '@grafana/data';
+import { AutoSizeInput, Combobox, ComboboxOption, InlineSwitch, MultiCombobox, RadioButtonGroup, Stack } from '@grafana/ui';
+import { InlineField } from 'core/components/InlineField';
+import { validateNumericInput } from 'core/utils';
+import { WorkItemsDataSource } from '../WorkItemsDataSource';
+import { TAKE_LIMIT, takeErrorMessages, tooltips } from '../constants/QueryEditor.constants';
+import {
+  OrderBy,
+  OrderByOptions,
+  OutputType,
+  WorkItemsQuery,
+  WorkItemTypeOptions,
+  WorkItemTypes,
+} from '../types';
+
+type Props = QueryEditorProps<WorkItemsDataSource, WorkItemsQuery>;
+
+export function WorkItemsQueryEditor({ query, onChange, onRunQuery, datasource }: Props) {
+  query = datasource.prepareQuery(query);
+  const [takeInvalidMessage, setTakeInvalidMessage] = useState<string>('');
+
+  const selectedTypes = useMemo(
+    () => (query.types ?? []).map((type) => ({ label: WorkItemTypes.find((option) => option.value === type)?.label ?? type, value: type })),
+    [query.types]
+  );
+
+  const typeOptions = useMemo(
+    () => WorkItemTypes.map((option) => ({ label: option.label, value: option.value })),
+    []
+  );
+
+  const handleQueryChange = useCallback((newQuery: WorkItemsQuery, runQuery = true): void => {
+    onChange(newQuery);
+    if (runQuery) {
+      onRunQuery();
+    }
+  }, [onChange, onRunQuery]);
+
+  const onOutputTypeChange = (value: OutputType) => {
+    handleQueryChange({ ...query, outputType: value });
+  };
+
+  const onTypesChange = (items: Array<ComboboxOption<WorkItemTypeOptions>>) => {
+    const types = items.map((item) => item.value).filter(Boolean) as WorkItemTypeOptions[];
+    handleQueryChange({ ...query, types: datasource.normalizeTypes(types) });
+  };
+
+  const onOrderByChange = (item: SelectableValue<OrderByOptions>) => {
+    handleQueryChange({ ...query, orderBy: item.value as OrderByOptions });
+  };
+
+  const onDescendingChange = (isDescendingChecked: boolean) => {
+    handleQueryChange({ ...query, descending: isDescendingChecked });
+  };
+
+  const onTakeChange = (event: React.FormEvent<HTMLInputElement>) => {
+    const value = parseInt((event.target as HTMLInputElement).value, 10);
+    if (Number.isNaN(value) || value < 0) {
+      setTakeInvalidMessage(takeErrorMessages.greaterOrEqualToZero);
+      return;
+    }
+
+    if (value > TAKE_LIMIT) {
+      setTakeInvalidMessage(takeErrorMessages.lessOrEqualToTenThousand);
+      return;
+    }
+
+    setTakeInvalidMessage('');
+    handleQueryChange({ ...query, take: value });
+  };
+
+  return (
+    <Stack direction='column' gap={0}>
+      <InlineField label="Output" labelWidth={25} tooltip={tooltips.outputType}>
+        <RadioButtonGroup
+          options={Object.values(OutputType).map((value) => ({ label: value, value })) as SelectableValue[]}
+          onChange={onOutputTypeChange}
+          value={query.outputType}
+        />
+      </InlineField>
+
+      <InlineField label="Type" labelWidth={25} tooltip={tooltips.types}>
+        <MultiCombobox
+          placeholder="Select work item types"
+          options={typeOptions}
+          value={selectedTypes}
+          onChange={onTypesChange}
+          width='auto'
+          minWidth={65}
+          maxWidth={65}
+        />
+      </InlineField>
+
+      {query.outputType === OutputType.Properties && (
+        <>
+          <InlineField label="OrderBy" labelWidth={25} tooltip={tooltips.orderBy}>
+            <Combobox
+              options={OrderBy}
+              placeholder="Select a field to set query order"
+              onChange={onOrderByChange}
+              value={query.orderBy}
+              width={26}
+            />
+          </InlineField>
+
+          <InlineField label="Descending" labelWidth={25} tooltip={tooltips.descending}>
+            <InlineSwitch
+              onChange={event => onDescendingChange(event.currentTarget.checked)}
+              value={query.descending}
+            />
+          </InlineField>
+
+          <InlineField
+            label="Take"
+            labelWidth={25}
+            tooltip={tooltips.take}
+            invalid={!!takeInvalidMessage}
+            error={takeInvalidMessage}
+          >
+            <AutoSizeInput
+              minWidth={26}
+              maxWidth={26}
+              type='number'
+              defaultValue={query.take}
+              onBlur={onTakeChange}
+              placeholder="Enter record count"
+              onKeyDown={(event) => { validateNumericInput(event); }}
+            />
+          </InlineField>
+        </>
+      )}
+    </Stack>
+  );
+}

src/datasources/work-items/constants/QueryEditor.constants.ts

@@ -0,0 +1,14 @@
+export const TAKE_LIMIT = 10000;
+
+export const takeErrorMessages = {
+  greaterOrEqualToZero: 'Enter a value greater than or equal to 0',
+  lessOrEqualToTenThousand: 'Enter a value less than or equal to 10,000',
+};
+
+export const tooltips = {
+  outputType: 'Select whether to return work item properties or only total count.',
+  types: 'Choose one or more work item types to query.',
+  orderBy: 'Select which property to sort by for properties output.',
+  descending: 'Toggle descending sort order for properties output.',
+  take: 'Set the maximum number of work items to return. Maximum is 10,000.',
+};

src/datasources/work-items/module.ts

@@ -0,0 +1,8 @@
+import { DataSourcePlugin } from '@grafana/data';
+import { HttpConfigEditor } from 'core/components/HttpConfigEditor';
+import { WorkItemsDataSource } from './WorkItemsDataSource';
+import { WorkItemsQueryEditor } from './components/WorkItemsQueryEditor';
+
+export const plugin = new DataSourcePlugin(WorkItemsDataSource)
+  .setConfigEditor(HttpConfigEditor)
+  .setQueryEditor(WorkItemsQueryEditor);

src/datasources/work-items/plugin.json

@@ -0,0 +1,15 @@
+{
+  "type": "datasource",
+  "name": "SystemLink Work Items",
+  "id": "ni-slworkitems-datasource",
+  "metrics": true,
+  "info": {
+    "author": {
+      "name": "NI"
+    },
+    "logos": {
+      "small": "img/logo-ni.svg",
+      "large": "img/logo-ni.svg"
+    }
+  }
+}