@gravity-ui/querieskit 1.0.3 → 1.1.0

package/src/types/navigation.ts

@@ -0,0 +1,199 @@
+import {ReactNode} from 'react';
+import type {LoadPathSuggestions} from './pathEditor';
+
+export type NavigationLocation = {
+    cluster: string | undefined;
+    path: string | undefined;
+};
+
+export type NavigationAction<TArg> = {
+    id: string;
+    title: string;
+    content: ReactNode;
+    hidden?: boolean;
+    disabled?: boolean;
+    qa?: string;
+    onClick: (arg: TArg) => void;
+};
+
+export type NavigationHeaderAction = NavigationAction<NavigationLocation>;
+
+export type NavigationCluster = {
+    id: string;
+    title: string;
+    icon?: ReactNode;
+    color?: string;
+    backgroundColor?: string;
+    description?: string;
+};
+
+export type NavigationItemKind = 'folder' | 'file' | 'table' | 'link' | 'unknown';
+
+export type NavigationItem = {
+    path: string;
+    title: string;
+    icon?: ReactNode;
+    kind?: NavigationItemKind;
+    targetPathBroken?: boolean;
+    hasChildren?: boolean;
+    disabled?: boolean;
+};
+
+export type NavigationSortOrder = 'asc' | 'desc';
+
+export type NavigationItemRowRenderData<T extends NavigationItem = NavigationItem> = {
+    item: T;
+    index: number;
+    isActive: boolean;
+    isParentRow: boolean;
+};
+
+export type NavigationClusterRowRenderData<T extends NavigationCluster = NavigationCluster> = {
+    cluster: T;
+    index: number;
+    isActive: boolean;
+};
+
+export type RenderNavigationItem<T extends NavigationItem = NavigationItem> = (
+    data: NavigationItemRowRenderData<T>,
+) => ReactNode;
+
+export type RenderNavigationCluster<T extends NavigationCluster = NavigationCluster> = (
+    data: NavigationClusterRowRenderData<T>,
+) => ReactNode;
+
+export type NavigationDetailTabRenderContext = {
+    search: string;
+    onSearchUpdate?: (value: string) => void;
+    searchPlaceholder?: string;
+};
+
+export type NavigationDetailTab = {
+    id: string;
+    title: string;
+    content?: ReactNode;
+    renderContent?: (ctx: NavigationDetailTabRenderContext) => ReactNode;
+    hidden?: boolean;
+    disabled?: boolean;
+};
+
+export type NavigationAsyncConfig = {
+    loading?: boolean;
+    loaded?: boolean;
+    errorContent?: ReactNode;
+};
+
+export type NavigationSchemaSortOrder = 'ascending' | 'descending';
+
+export type NavigationSchemaColumn = {
+    name: string;
+    type?: string;
+    sortOrder?: NavigationSchemaSortOrder;
+    required?: boolean;
+    [key: string]: unknown;
+};
+
+export type NavigationSchemaConfig<
+    TColumn extends NavigationSchemaColumn = NavigationSchemaColumn,
+> = NavigationAsyncConfig & {
+    columns: TColumn[];
+};
+
+export type NavigationCellValue = ReactNode;
+
+export type NavigationPreviewRow = Record<string, NavigationCellValue>;
+
+export type NavigationPreviewConfig<TRow extends NavigationPreviewRow = NavigationPreviewRow> =
+    NavigationAsyncConfig & {
+        columns: string[];
+        rows: TRow[];
+    };
+
+export type NavigationViewRow = NavigationPreviewRow;
+
+export type NavigationViewSectionAction<TRow extends NavigationViewRow = NavigationViewRow> =
+    NavigationAction<NavigationViewSection<TRow>>;
+
+export type NavigationViewSection<TRow extends NavigationViewRow = NavigationViewRow> =
+    NavigationAsyncConfig & {
+        id: string;
+        title: ReactNode;
+        columns: string[];
+        rows: TRow[];
+        expanded?: boolean;
+        defaultExpanded?: boolean;
+        onExpandedChange?: (expanded: boolean) => void;
+        actions?: Array<NavigationViewSectionAction<TRow>>;
+    };
+
+export type NavigationViewConfig<TRow extends NavigationViewRow = NavigationViewRow> =
+    NavigationAsyncConfig & {
+        sections: Array<NavigationViewSection<TRow>>;
+    };
+
+export type NavigationMetaItem = {
+    name: string;
+    value: NavigationCellValue;
+    [key: string]: unknown;
+};
+
+export type NavigationMetaGroup<TItem extends NavigationMetaItem = NavigationMetaItem> = {
+    title?: string;
+    items: TItem[];
+};
+
+export type NavigationMetaConfig<TItem extends NavigationMetaItem = NavigationMetaItem> =
+    NavigationAsyncConfig & {
+        groups: Array<NavigationMetaGroup<TItem>>;
+    };
+
+export type NavigationDetailConfig = {
+    tabs: NavigationDetailTab[];
+    defaultTab?: string;
+    hasSearch?: boolean;
+    searchPlaceholder?: string;
+    actions?: NavigationHeaderAction[];
+    emptyContent?: ReactNode;
+};
+
+export type ResolveNavigationDetail<T extends NavigationItem = NavigationItem> = (
+    item: T,
+) => NavigationDetailConfig | undefined;
+
+export type NavigationDetailConfigFactory<T extends NavigationItem = NavigationItem> = (
+    item: T,
+) => NavigationDetailConfig;
+
+export type NavigationSearchConfig = {
+    value?: string;
+    onUpdate?: (value: string) => void;
+};
+
+export type NavigationSortConfig = {
+    value?: NavigationSortOrder;
+    onUpdate?: (sort: NavigationSortOrder) => void;
+};
+
+export type NavigationListStateConfig = {
+    loading?: boolean;
+    error?: boolean | ReactNode;
+    hasMore?: boolean;
+    onLoadMore?: () => void;
+};
+
+export type NavigationHeaderConfig = {
+    actions?: NavigationHeaderAction[];
+    onLoadSuggestions?: LoadPathSuggestions;
+};
+
+export type NavigationDetailPanelConfig<TItem extends NavigationItem = NavigationItem> = {
+    openedItem?: TItem;
+    onItemOpen?: (item: TItem) => void;
+    onClose?: () => void;
+    resolve?: ResolveNavigationDetail<TItem>;
+    search?: string;
+    onSearchUpdate?: (value: string) => void;
+    activeTab?: string;
+    onTabUpdate?: (tab: string) => void;
+    actions?: NavigationHeaderAction[];
+};

package/src/types/pathEditor.ts

@@ -0,0 +1,29 @@
+import {ReactNode} from 'react';
+import type {NavigationItemKind} from './navigation';
+
+export type PathEditorSuggestion = {
+    parentPath: string;
+    childPath: string;
+    path: string;
+    icon?: ReactNode;
+    kind?: NavigationItemKind;
+    targetPathBroken?: boolean;
+};
+
+export type PathEditorSuggestionFilter = (
+    suggestions: PathEditorSuggestion[],
+) => PathEditorSuggestion[];
+
+export type PathEditorEventPayload = {
+    path: string;
+};
+
+export type LoadPathSuggestionsParams = {
+    path: string;
+    customFilter: PathEditorSuggestionFilter | undefined;
+    cluster: string | undefined;
+};
+
+export type LoadPathSuggestions = (
+    params: LoadPathSuggestionsParams,
+) => void | Promise<PathEditorSuggestion[]>;

package/src/widgets/DashboardCharts/DashboardCharts.scss

@@ -0,0 +1,25 @@
+.qp-dashboard-charts {
+    box-sizing: border-box;
+    min-width: 0;
+    min-height: 480px;
+    background: var(--g-color-base-background);
+
+    &__dashboard {
+        min-height: 100%;
+    }
+
+    &__modal {
+        --g-modal-width: calc(100vw - var(--g-spacing-10));
+        --g-modal-max-width: 1200px;
+        --g-modal-height: calc(100vh - var(--g-spacing-10));
+        --g-modal-max-height: 720px;
+
+        overflow: hidden;
+    }
+
+    &__empty {
+        min-height: 320px;
+        border: 1px dashed var(--g-color-line-generic);
+        border-radius: var(--g-border-radius-m);
+    }
+}

package/src/widgets/DashboardCharts/DashboardCharts.tsx

@@ -0,0 +1,214 @@
+import React, {useCallback, useMemo, useState} from 'react';
+import {ChartSeries} from '@gravity-ui/charts';
+import {Flex, Modal} from '@gravity-ui/uikit';
+import {ChartEditor, ChartEditorProps} from '../../modules';
+import {AddChartButton, Chart, Dashboard} from '../../components';
+import {ChartData} from '../../modules/ChartEditor/types';
+import type {DashboardChartsProps, DashboardItem} from './types';
+import {EmptyDashboardPlaceholder} from './internal/EmptyDashboardPlaceholder';
+import {CHART_TYPE_ICONS} from './helpers/chartTypeIcons';
+import {ConfigLayout} from '@gravity-ui/dashkit';
+import i18n from './i18n';
+import cn from 'bem-cn-lite';
+import './DashboardCharts.scss';
+
+const block = cn('qp-dashboard-charts');
+
+export const DashboardCharts = ({
+    chartItems: customerChartsItems,
+    defaultLayout,
+    dataSource,
+    emptyTitle,
+    emptyDescription,
+    chartEditorProps,
+    dashboardProps,
+    onItemsChange,
+    onLayoutChange,
+    className,
+    gap = 1,
+}: DashboardChartsProps) => {
+    const [innerChartItems, setInnerChartItems] = useState<DashboardItem[]>(
+        customerChartsItems ?? [],
+    );
+
+    const chartItems = customerChartsItems ?? innerChartItems;
+
+    const [draftChart, setDraftChart] = useState<{
+        id?: string;
+        chartSeries: ChartEditorProps['chartSeriesMap'];
+        formValues: ChartEditorProps['formValues'];
+    } | null>(null);
+
+    const allowedCharts = useMemo(
+        () => Object.keys(dataSource) as ChartSeries['type'][],
+        [dataSource],
+    );
+
+    const handleChartSelect = (chartType: ChartSeries['type']) => {
+        const chartSeries = dataSource[chartType];
+
+        if (chartSeries) {
+            const dataIds = Object.keys(chartSeries);
+
+            setDraftChart({
+                chartSeries,
+                formValues: {
+                    dataIds: dataIds.length ? [dataIds[0]] : [],
+                    axisType: 'linear',
+                },
+            });
+        }
+    };
+
+    const handleCancelDraft = () => {
+        setDraftChart(null);
+    };
+
+    const handleSubmitChart = (chart: ChartData) => {
+        if (!draftChart) return;
+
+        const newChart = {
+            id: draftChart.id ?? crypto.randomUUID().replace(/-/g, ''),
+            chartData: chart,
+        };
+
+        const actualChartItems = draftChart.id
+            ? chartItems.map((ch) => (ch.id === newChart.id ? newChart : ch))
+            : [...chartItems, newChart];
+
+        setDraftChart(null);
+        setInnerChartItems(actualChartItems);
+        onItemsChange?.(actualChartItems);
+    };
+
+    const handleEditChart = useCallback(
+        (id: string, chart: DashboardItem['chartData']) => {
+            const chartType = chart.series.data[0].type;
+            const chartSeries = dataSource[chartType];
+
+            if (!chartSeries) return;
+
+            const selectedDataIds = chart.series.data.map((s) => s.seriesId);
+
+            setDraftChart({
+                id,
+                chartSeries,
+                formValues: {
+                    dataIds: selectedDataIds,
+                    chartTitle: chart.title?.text,
+                    xTitle: chart.xAxis?.title?.text,
+                    yTitle: chart.yAxis?.[0].title?.text,
+                    showLegend: chart?.legend?.enabled,
+                    axisType: chart.xAxis?.type,
+                    axisCategories: chart.xAxis?.categories,
+                },
+            });
+        },
+        [dataSource],
+    );
+
+    const handleDeleteChart = useCallback(
+        (id: string) => {
+            const newChartItems = chartItems.filter((item) => item.id !== id);
+
+            setInnerChartItems(newChartItems);
+
+            onItemsChange?.(newChartItems);
+        },
+        [chartItems, onItemsChange],
+    );
+
+    const handleLayoutChange = (patchedLayout: ConfigLayout[]) => {
+        onLayoutChange?.(patchedLayout);
+    };
+
+    const dashboardItems = useMemo(
+        () =>
+            chartItems.map(({id, chartData}) => ({
+                id,
+                content: (
+                    <Chart
+                        key={id}
+                        data={chartData}
+                        controlsVisibility="hover"
+                        onPencilEdit={() => handleEditChart(id, chartData)}
+                        actions={[
+                            {
+                                text: i18n('action_delete-chart'),
+                                onClick: () => handleDeleteChart(id),
+                            },
+                        ]}
+                    />
+                ),
+            })),
+        [chartItems, handleEditChart, handleDeleteChart],
+    );
+
+    return (
+        <React.Fragment>
+            <Flex
+                as="section"
+                direction="column"
+                width="100%"
+                height="100%"
+                gap={gap}
+                className={block(null, className)}
+            >
+                <AddChartButton
+                    text={i18n('action_add-chart')}
+                    options={allowedCharts.map((chartType) => ({
+                        value: chartType,
+                        text: chartType,
+                        icon: CHART_TYPE_ICONS[chartType],
+                    }))}
+                    onSelect={handleChartSelect}
+                    disabled={allowedCharts.length === 0}
+                />
+
+                {chartItems.length > 0 ? (
+                    <Dashboard
+                        items={dashboardItems}
+                        defaultLayout={defaultLayout}
+                        onLayoutChange={handleLayoutChange}
+                        className={block('dashboard')}
+                        {...dashboardProps}
+                    />
+                ) : (
+                    <EmptyDashboardPlaceholder
+                        emptyTitle={emptyTitle}
+                        emptyDescription={emptyDescription}
+                    />
+                )}
+            </Flex>
+
+            <Modal
+                open={Boolean(draftChart)}
+                onOpenChange={(open) => {
+                    if (!open) {
+                        setDraftChart(null);
+                    }
+                }}
+                contentOverflow="auto"
+                contentClassName={block('modal')}
+            >
+                {draftChart && (
+                    <ChartEditor
+                        chartSeriesMap={draftChart.chartSeries}
+                        formValues={draftChart.formValues}
+                        onSubmit={handleSubmitChart}
+                        onCancel={handleCancelDraft}
+                        axisVariants={['linear', 'datetime', 'logarithmic']}
+                        formProps={{
+                            labels: {
+                                submitLabel: draftChart.id
+                                    ? i18n('action_save-chart')
+                                    : i18n('action_add-chart'),
+                            },
+                        }}
+                        {...chartEditorProps}
+                    />
+                )}
+            </Modal>
+        </React.Fragment>
+    );
+};

package/src/widgets/DashboardCharts/helpers/chartTypeIcons.ts

@@ -0,0 +1,33 @@
+import {
+    BranchesRight,
+    ChartAreaStacked,
+    ChartBar,
+    ChartColumn,
+    ChartLine,
+    ChartPie,
+    ChartTreemap,
+    Circles4Square,
+    Circles5Random,
+    CirclesConcentric,
+    Funnel,
+    ListTimeline,
+    SquareBars,
+} from '@gravity-ui/icons';
+import type {ChartSeries} from '@gravity-ui/charts';
+import type {IconData} from '@gravity-ui/uikit';
+
+export const CHART_TYPE_ICONS: Record<ChartSeries['type'], IconData> = {
+    area: ChartAreaStacked,
+    'bar-x': ChartColumn,
+    'bar-y': ChartBar,
+    funnel: Funnel,
+    heatmap: Circles4Square,
+    line: ChartLine,
+    pie: ChartPie,
+    radar: CirclesConcentric,
+    sankey: BranchesRight,
+    scatter: Circles5Random,
+    treemap: ChartTreemap,
+    waterfall: SquareBars,
+    'x-range': ListTimeline,
+};

package/src/widgets/DashboardCharts/i18n/dicts.ts

@@ -0,0 +1,4 @@
+import en from './en.json';
+import ru from './ru.json';
+
+export default {en, ru};

package/src/widgets/DashboardCharts/i18n/en.json

@@ -0,0 +1,7 @@
+{
+  "action_add-chart": "Add chart",
+  "action_save-chart": "Save",
+  "action_delete-chart": "Delete",
+  "context_no-charts": "No charts yet",
+  "context_add-first-chart": "Add a chart to start building your dashboard"
+}

package/src/widgets/DashboardCharts/i18n/index.ts

@@ -0,0 +1,5 @@
+import {addI18Keysets} from '../../../i18n';
+
+import dicts from './dicts';
+
+export default addI18Keysets('qp:dashboard-charts', dicts);

package/src/widgets/DashboardCharts/i18n/ru.json

@@ -0,0 +1,7 @@
+{
+  "action_add-chart": "Добавить график",
+  "action_save-chart": "Сохранить",
+  "action_delete-chart": "Удалить",
+  "context_no-charts": "Графиков пока нет",
+  "context_add-first-chart": "Добавьте график, чтобы начать собирать дашборд"
+}

package/src/widgets/DashboardCharts/index.ts

@@ -0,0 +1,2 @@
+export {DashboardCharts} from './DashboardCharts';
+export type {DashboardChartsProps} from './types';

package/src/widgets/DashboardCharts/internal/EmptyDashboardPlaceholder.tsx

@@ -0,0 +1,26 @@
+import React, {ReactNode} from 'react';
+import {Flex, Text} from '@gravity-ui/uikit';
+import i18n from '../i18n';
+import cn from 'bem-cn-lite';
+
+type EmptyDashboardPlaceholderProps = {
+    emptyTitle?: ReactNode;
+    emptyDescription?: ReactNode;
+};
+
+const block = cn('qp-empty-dashboard-placeholder');
+
+export const EmptyDashboardPlaceholder = ({
+    emptyTitle,
+    emptyDescription,
+}: EmptyDashboardPlaceholderProps) => {
+    const resolvedEmptyTitle = emptyTitle ?? i18n('context_no-charts');
+    const resolvedEmptyDescription = emptyDescription ?? i18n('context_add-first-chart');
+
+    return (
+        <Flex direction="column" centerContent gap={1} className={block('empty')}>
+            <Text variant="subheader-2">{resolvedEmptyTitle}</Text>
+            <Text color="secondary">{resolvedEmptyDescription}</Text>
+        </Flex>
+    );
+};

package/src/widgets/DashboardCharts/story/DashboardCharts.stories.scss

@@ -0,0 +1,6 @@
+.qp-dashboard-charts-story {
+    box-sizing: border-box;
+    height: 720px;
+    padding: var(--g-spacing-4);
+    background: var(--g-color-base-background);
+}

package/src/widgets/DashboardCharts/story/DashboardCharts.stories.tsx

@@ -0,0 +1,77 @@
+import React from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {action} from 'storybook/actions';
+
+import {DashboardCharts} from '../DashboardCharts';
+import {
+    advancedChartItems,
+    advancedChartsDataSource,
+    advancedChartsLayout,
+    allChartTypesDataSource,
+    commonChartItems,
+    commonChartsDataSource,
+    commonChartsLayout,
+} from './mockData';
+
+import './DashboardCharts.stories.scss';
+
+const meta: Meta<typeof DashboardCharts> = {
+    title: 'Widgets/DashboardCharts',
+    component: DashboardCharts,
+    tags: ['autodocs'],
+    parameters: {layout: 'fullscreen'},
+    args: {
+        onItemsChange: action('onItemsChange'),
+        onLayoutChange: action('onLayoutChange'),
+    },
+    render: (args) => (
+        <div className="qp-dashboard-charts-story">
+            <DashboardCharts {...args} />
+        </div>
+    ),
+};
+
+export default meta;
+type Story = StoryObj<typeof DashboardCharts>;
+
+/**
+ * Start with an empty dashboard and use the Add chart menu to create any chart type
+ * supported by `@gravity-ui/charts`.
+ */
+export const Default: Story = {
+    args: {
+        dataSource: allChartTypesDataSource,
+    },
+};
+
+/**
+ * A practical monitoring dashboard with the most common cartesian and circular charts.
+ * Every card can be dragged, resized and opened in the chart editor.
+ */
+export const CommonCharts: Story = {
+    args: {
+        dataSource: commonChartsDataSource,
+        chartItems: commonChartItems,
+        defaultLayout: commonChartsLayout,
+        dashboardProps: {
+            grid: {cols: 6, rowHeight: 72, gap: 12, compactType: 'vertical'},
+            focusable: true,
+        },
+    },
+};
+
+/**
+ * Less common visualizations for hierarchy, flow, changes, profiles, density,
+ * conversion and execution intervals.
+ */
+export const AdvancedCharts: Story = {
+    args: {
+        dataSource: advancedChartsDataSource,
+        chartItems: advancedChartItems,
+        defaultLayout: advancedChartsLayout,
+        dashboardProps: {
+            grid: {cols: 8, rowHeight: 72, gap: 12, compactType: 'vertical'},
+            focusable: true,
+        },
+    },
+};