@genispace/geniapp 0.2.0 → 0.4.0

package/dist/components/internal/workbench/types/databaseDataSource.d.ts

@@ -0,0 +1,120 @@
+export interface ParameterRefConfig {
+    type: 'parameter' | 'system';
+    source?: string;
+    systemParam?: string;
+    value?: any;
+    waitForValue?: boolean;
+}
+export interface DatabaseDataSourceConfig {
+    type: 'database-datasource';
+    datasourceId: string;
+    datasourceName?: string;
+    /** Pin a datasource version; omit to use the default version */
+    version?: number;
+    sqlQuery?: string;
+    parameters?: Record<string, any>;
+    parameterTypes?: Record<string, string>;
+    outputFields?: string[];
+    defaultSort?: DefaultSortItem[];
+    enableSort?: boolean;
+}
+export interface DatabaseDataSourceResponse {
+    success: boolean;
+    data?: {
+        rows: Record<string, any>[];
+        columns: string[];
+        totalCount: number;
+        executionTime: number;
+        pagination: {
+            page: number;
+            limit: number;
+            total: number;
+            pages: number;
+        };
+    };
+    message?: string;
+    error?: string;
+}
+export interface DatabaseDataSourceParams {
+    parameters?: Record<string, any>;
+    page?: number;
+    limit?: number;
+    offset?: number;
+    filter?: string;
+    sort?: string;
+    outputFields?: string[];
+}
+export type ComponentDataSourceType = 'dataset' | 'database-datasource' | 'external' | 'mock';
+export type UnifiedDataSourceConfig = {
+    type: 'dataset';
+    datasetConfig: any;
+} | {
+    type: 'database-datasource';
+    databaseDataSourceConfig: DatabaseDataSourceConfig;
+} | {
+    type: 'external';
+    externalConfig: any;
+} | {
+    type: 'mock';
+    mockConfig: any;
+};
+export interface DatabaseDataSourceOption {
+    id: string;
+    name: string;
+    description?: string;
+    type?: string;
+    status?: 'active' | 'inactive';
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface DatabaseFieldInfo {
+    name: string;
+    type: string;
+    description?: string;
+    nullable?: boolean;
+    defaultValue?: any;
+}
+export interface DatabaseDataSourcePreviewData {
+    fields: DatabaseFieldInfo[];
+    sampleData: Record<string, any>[];
+    totalCount?: number;
+}
+export interface UseDatabaseDataSourceReturn {
+    data: Record<string, any>[];
+    loading: boolean;
+    error: string | null;
+    pagination: {
+        total: number;
+        current_page: number;
+        total_pages: number;
+        limit: number;
+        offset: number;
+        has_more: boolean;
+    } | null;
+    isInitialized: boolean;
+    refetch: (params?: Record<string, any>) => Promise<void>;
+    clearCache: () => void;
+    exportAllData: (onProgress: (current: number, total: number) => void) => Promise<Record<string, any>[]>;
+}
+export type SupportedComponentType = 'Tree' | 'Table' | 'EditableTable' | 'Form' | 'Chart' | 'StatisticGroup' | 'Typography' | 'HeroCard' | 'CollapsePanel' | 'ProductReport' | 'ProductDetail' | 'TileGrid' | 'RingStat' | 'RadarChart' | 'List';
+export interface DefaultSortItem {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+export interface DataExtractionStrategy {
+    componentType: SupportedComponentType;
+    dataPath?: string;
+    transformFn?: (data: any[]) => any[];
+}
+export interface ErrorHandlingConfig {
+    showToast?: boolean;
+    retryAttempts?: number;
+    retryDelay?: number;
+    fallbackData?: any[];
+}
+export interface PerformanceConfig {
+    debounceTime?: number;
+    throttleTime?: number;
+    batchSize?: number;
+    lazyLoad?: boolean;
+}

package/dist/components/internal/workbench/types/datasource.d.ts

@@ -0,0 +1,117 @@
+export type FilterOperator = 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'like' | 'in' | 'not_in';
+export interface ParameterFilterCondition {
+    id: string;
+    field: string;
+    operator: FilterOperator;
+    parameterName: string;
+    fallbackValue?: any;
+    enabled: boolean;
+    description?: string;
+}
+export interface DataSourceCommunicationConfig {
+    enabled: boolean;
+    listenToParameters: string[];
+    enableDebugLog?: boolean;
+    manualListenParameters?: string[];
+    autoListenParameters?: string[];
+}
+export interface DataSourceParams {
+    parameterFilters?: ParameterFilterCondition[];
+    limit?: number;
+    offset?: number;
+    outputFields?: string[];
+    [key: string]: unknown;
+}
+export interface DataSource {
+    type: 'dataset';
+    datasetId: string;
+    datasetName?: string;
+    params: DataSourceParams;
+    [key: string]: unknown;
+}
+export interface EnhancedDataSource extends DataSource {
+    communicationConfig?: DataSourceCommunicationConfig;
+}
+export interface SchemaField {
+    name: string;
+    type: string;
+    description?: string;
+}
+export interface DatasetSchema {
+    fields: SchemaField[];
+}
+export interface ColumnConfig {
+    title: string;
+    dataIndex: string;
+    key: string;
+    width?: number | string;
+    minWidth?: number | string;
+    maxWidth?: number | string;
+    align?: string;
+    ellipsis?: boolean;
+    editable?: boolean;
+    editRequired?: boolean;
+    filterable?: boolean;
+    filterType?: 'equals' | 'like' | 'in';
+    filterMultiSelect?: boolean;
+    filterMaxTags?: number;
+    filterPassMode?: 'filter' | 'parameter';
+    filterParameterName?: string;
+    hidden?: boolean;
+    /** Pin column to the left in table renderer (horizontal scroll) */
+    frozen?: boolean;
+    fieldType?: 'VARCHAR' | 'INT8' | 'INT16' | 'INT32' | 'INT64' | 'FLOAT' | 'DOUBLE' | 'BOOL' | 'JSON' | 'ARRAY' | 'DATE' | 'DATETIME' | 'TEXT' | 'SWITCH' | 'IMAGE';
+    render?: {
+        type: 'Tag' | 'Progress' | 'Image' | 'yyyy-MM-dd' | 'yyyy-MM-dd HH:mm:ss' | 'Custom' | 'RankBadge' | 'Currency' | 'Number';
+        props?: {
+            color?: Record<string, string>;
+            text?: Record<string, string>;
+            textColor?: Record<string, string>;
+            status?: string;
+            showInfo?: boolean;
+            size?: 'small' | 'default' | 'large';
+            width?: number;
+            height?: number;
+            preview?: boolean;
+            fallback?: string;
+            render?: string;
+            customColor?: string;
+            fontWeight?: string;
+            fontFamily?: string;
+            fontStyle?: string;
+            textDecoration?: string;
+            topHighlight?: number;
+            highlightFrom?: string;
+            highlightTo?: string;
+            defaultFill?: string;
+            rankStyle?: 'square' | 'circle';
+            rankSize?: 'xs' | 'sm' | 'md';
+            medalTop?: number;
+            currencyField?: string;
+            compact?: boolean;
+            decimals?: number;
+        };
+    };
+    switchConfig?: {
+        showText?: boolean;
+        onText?: string;
+        offText?: string;
+    };
+    inputType?: 'text' | 'number' | 'color' | 'date' | 'select' | 'switch' | 'file';
+    datasource?: {
+        datasourceId?: string;
+        /** Pin a datasource version; omit to use the default version */
+        version?: number;
+        valueField?: string;
+        labelField?: string;
+    };
+    [key: string]: unknown;
+}
+export interface PaginationConfig {
+    pageSize: number;
+    current?: number;
+    showSizeChanger?: boolean;
+    showQuickJumper?: boolean;
+    showTotal?: boolean;
+    [key: string]: unknown;
+}

package/dist/components/internal/workbench/types/editors.d.ts

@@ -0,0 +1,91 @@
+import { DataSource, SchemaField, DatasetSchema, ColumnConfig, EnhancedDataSource } from './datasource';
+import { ComponentTypeName } from './components';
+
+export interface BasePropertyEditorProps {
+    component: {
+        id: string;
+        type: string;
+        props?: Record<string, unknown>;
+        dataSource?: DataSource;
+        mockData?: unknown;
+        parameterConfig?: unknown;
+        actions?: unknown[];
+        [key: string]: unknown;
+    };
+    onPropChange: (propKey: string, value: unknown) => void;
+    availablePages?: Array<{
+        key: string;
+        title: string;
+    }>;
+    availableParameters?: Array<{
+        label: string;
+        value: string;
+        type?: string;
+    }>;
+}
+export interface ComponentEditorProps extends BasePropertyEditorProps {
+    onDataSourceChange?: (dataSource: DataSource) => void;
+    onMockDataChange?: (mockData: unknown) => void;
+    onIdChange?: (id: string) => void;
+}
+export interface DataSourceEditorProps {
+    dataSource: EnhancedDataSource | null;
+    componentType: ComponentTypeName;
+    onChange: (dataSource: EnhancedDataSource) => void;
+    availableParameters?: Array<{
+        label: string;
+        value: string;
+        type?: string;
+    }>;
+}
+export interface MockDataEditorProps {
+    mockData: unknown;
+    componentType: ComponentTypeName;
+    onChange: (mockData: unknown) => void;
+}
+export interface SchemaColumnSelectorProps {
+    isOpen: boolean;
+    onOpenChange: (open: boolean) => void;
+    schema: DatasetSchema | null;
+    existingColumns: ColumnConfig[];
+    onSelect: (selectedFields: SchemaField[]) => void;
+}
+export interface PropertyConfig {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    label: string;
+    description?: string;
+    required?: boolean;
+    defaultValue?: any;
+    options?: Array<{
+        label: string;
+        value: string | number;
+    }>;
+    children?: {
+        [key: string]: PropertyConfig;
+    };
+}
+export interface ComponentTypeConfig {
+    type: ComponentTypeName;
+    title: string;
+    description: string;
+    icon: string;
+    propTypes: {
+        [key: string]: PropertyConfig;
+    };
+    dataSourceTypes?: {
+        [key: string]: {
+            label: string;
+            description?: string;
+            required?: boolean;
+            children: {
+                [key: string]: PropertyConfig;
+            };
+        };
+    };
+    mockData?: {
+        type: 'array' | 'object';
+        label: string;
+        description: string;
+        defaultValue: any;
+    };
+}

package/dist/components/internal/workbench/types/index.d.ts

@@ -0,0 +1,7 @@
+export * from '../types';
+export * from './application';
+export * from './datasource';
+export * from './components';
+export * from './renderers';
+export * from './editors';
+export * from './parameters';

package/dist/components/internal/workbench/types/parameters.d.ts

@@ -0,0 +1,59 @@
+export type ParameterValue = string | number | boolean | null | undefined | Record<string, any> | any[];
+export type ParameterRecord = Record<string, ParameterValue>;
+export interface TabParameterInfo {
+    tabId: string;
+    pageId: string;
+    parameters: ParameterRecord;
+    timestamp: number;
+}
+export interface ParameterChangeEvent {
+    key: string;
+    value: ParameterValue;
+    oldValue: ParameterValue;
+    source: 'user' | 'component' | 'system';
+    timestamp: number;
+    componentId?: string;
+}
+export type ParameterListener = (event: ParameterChangeEvent) => void;
+export interface ParameterSubscription {
+    parameterKeys: string[];
+    callback: ParameterListener;
+    componentId?: string;
+    immediate?: boolean;
+}
+export type ParameterReadyCallback = () => void;
+export interface ParameterContextValue {
+    currentTabParams: ParameterRecord;
+    getCurrentTabParams: () => ParameterRecord;
+    globalUrlParams: ParameterRecord;
+    updateTabParams: (params: Partial<ParameterRecord>, source?: 'user' | 'component' | 'system', componentId?: string) => void;
+    getTabParams: (tabId: string) => ParameterRecord;
+    cleanupTabParams: (activeTabIds: string[]) => void;
+    subscribeToParameter: (subscription: ParameterSubscription) => () => void;
+    unsubscribeFromParameter: (parameterKeys: string[], componentId?: string) => void;
+    broadcastParameterChange: (key: string, value: ParameterValue, source?: 'user' | 'component' | 'system', componentId?: string) => void;
+    markParametersReady: (parameterKeys: string[]) => void;
+    isParametersReady: (parameterKeys: string[]) => boolean;
+    subscribeToParametersReady: (parameterKeys: string[], callback: ParameterReadyCallback) => () => void;
+}
+export interface ParameterParseConfig {
+    enableJsonParsing: boolean;
+    defaultValues: ParameterRecord;
+    validationRules?: Record<string, (value: ParameterValue) => boolean>;
+}
+export interface ParameterProps {
+    pageParams?: ParameterRecord;
+    pageId?: string;
+    tabId?: string;
+}
+export interface ComponentParameterConfig {
+    enableParameterReceiving?: boolean;
+    parameterMapping?: Record<string, {
+        targetField: string;
+        targetType?: 'props' | 'dataSource' | 'filterCondition';
+        required?: boolean;
+        defaultValue?: ParameterValue;
+        transform?: (value: ParameterValue) => ParameterValue;
+    }>;
+    listenToParameters?: string[];
+}

package/dist/components/internal/workbench/types/productReport.d.ts

@@ -0,0 +1,272 @@
+import { BilingualText } from '../utils/workbenchDisplayLocale';
+import { HeroBanner } from '../components/renderers/heroCardUtils';
+import { VisibleWhen } from '../utils/visibleWhen';
+import { DatabaseDataSourceConfig } from './databaseDataSource';
+
+export type { BilingualText, HeroBanner };
+export type ProductReportViewMode = 'list' | 'table';
+export type DimensionSource = 'primary' | 'dimension';
+/** Number format vocabulary shared by summary cards and table cells. */
+export type ReportValueFormat = 'currency-compact' | 'compact-k' | 'number' | 'percent1' | 'plain';
+/** One summary KPI card; reads a single field off the summary row. */
+export interface SummaryCardConfig {
+    key?: string;
+    label: BilingualText;
+    field: string;
+    format?: ReportValueFormat;
+    /** Row field holding the currency code (e.g. 'currency'); used by currency-compact. */
+    currencyField?: string;
+    /** Accent dot color. */
+    color?: 'indigo' | 'emerald' | 'amber' | 'rose' | 'slate';
+    /** Per-card visibility rule (e.g. hide the discount card for store managers via role/app rules). */
+    visibleWhen?: VisibleWhen;
+}
+/**
+ * What happens when a dimension row is clicked: push `row[dimKeyField]` into a
+ * filter-bus param, then optionally navigate to another tab / sub-tab.
+ */
+export interface DrillConfig {
+    /** Filter-bus key (relative to filterComponentId) to receive row[dimKeyField]. */
+    emitParam: string;
+    /** 'csv' dedupe-appends a token; 'set' overwrites the single value. Default 'csv'. */
+    mode?: 'csv' | 'set';
+    then?: {
+        type: 'primaryTab';
+        key: string;
+    } | {
+        type: 'subTab';
+        key: string;
+    } | {
+        type: 'none';
+    };
+}
+/** A sub-tab inside a dimension; selecting it drives `dimension`/`groupBy`. */
+export interface SubTabConfig {
+    key: string;
+    label: BilingualText;
+    /** Injected as the `{{dimension}}` query param. */
+    dimension: string;
+    /** Injected as the `{{groupBy}}` query param. */
+    groupBy: string;
+    /** Overrides the parent dimension drill for this sub-tab. */
+    drill?: DrillConfig;
+    /** Per-sub-tab visibility rule (e.g. hide the e-commerce tab for store managers via role/app rules). */
+    visibleWhen?: VisibleWhen;
+    /** Fixed width (px) for the frozen name column in table view; overrides the shared column config. */
+    labelWidth?: number;
+}
+/** A primary tab. `source` selects which datasource feeds it. */
+export interface DimensionConfig {
+    key: string;
+    label: BilingualText;
+    /** 'primary' → databaseDataSourceConfig (PLU-like); 'dimension' → dimDataSourceConfig. */
+    source: DimensionSource;
+    /** Used when source==='dimension' and there are no sub-tabs. */
+    dimension?: string;
+    groupBy?: string;
+    subTabs?: SubTabConfig[];
+    /** Default drill for rows of this dimension; a sub-tab may override. */
+    drill?: DrillConfig;
+    /** Which sub-tab is active when entering this dimension. */
+    defaultSubTab?: string;
+    /** Field names to hide (table dataIndex + list-card item field) for this dimension across all its
+     * sub-tabs — e.g. store dims have no store-level stock, so hide 'stock'/'stock_share_pct'. */
+    hiddenFields?: string[];
+    /** Fixed width (px) for the frozen name column in table view; a sub-tab's labelWidth takes precedence. */
+    labelWidth?: number;
+    /** Show a pinned footer total row (bound to totalRowDataSourceConfig) on this dimension's table —
+     *  e.g. SW category/season/series tabs; the store dimension stays sales-only (no total). */
+    showTotalRow?: boolean;
+}
+export interface SortOptionConfig {
+    key: string;
+    label: BilingualText;
+    field: string;
+    defaultDir?: 'asc' | 'desc';
+}
+/** Per filter-bus key: how chips are labelled and how text keys clear together. */
+export interface FilterKeyConfig {
+    key: string;
+    kind: 'csv' | 'text';
+    /** Per-value chip label map (e.g. status normal→Regular, channel fp→Full Price). */
+    valueLabels?: Record<string, BilingualText>;
+    /** Text keys sharing a group clear together (e.g. code + name). */
+    textGroup?: string;
+    /** csv tokens are not shown as chips when true (still counted as active). */
+    excludeFromChips?: boolean;
+}
+/** Cell render vocabulary for report tables. */
+export type ReportCellType = 'text' | 'currency' | 'number' | 'percent' | 'trend' | 'tag' | 'thumbnail' | 'colorDot' | 'discBadge';
+export interface ReportCellProps {
+    format?: ReportValueFormat;
+    /** Per-row currency field (default 'currency'). */
+    currencyField?: string;
+    decimals?: number;
+    prefix?: string;
+    suffix?: string;
+    /** value → hex (colorDot swatch) or tone token (tag). */
+    colorMap?: Record<string, string>;
+    /** value → display label. */
+    textMap?: Record<string, BilingualText>;
+    /** value → text tone token for tag. */
+    toneMap?: Record<string, string>;
+    imageField?: string;
+    colorField?: string;
+    /** Colors that need a light border (e.g. white/beige). */
+    lightColors?: string[];
+    fallbackColor?: string;
+    /** Composite title (locale base, resolves _zh/_en). */
+    titleField?: string;
+    /** Composite sub line (e.g. plu). */
+    subField?: string;
+    /** Below this ratio (0..1) the pill turns rose; value shown as ×100 %. */
+    discountThreshold?: number;
+    /** Below this number the text turns rose and a ⚠ is appended. */
+    warnBelow?: number;
+}
+export interface ReportColumn {
+    dataIndex: string;
+    title: BilingualText;
+    align?: 'left' | 'right' | 'center';
+    /** Sticky-left frozen column. */
+    frozen?: boolean;
+    minWidth?: number;
+    maxWidth?: number;
+    render?: {
+        type: ReportCellType;
+        props?: ReportCellProps;
+    };
+}
+/** One metric inside a list-card metric grid. */
+export interface ReportMetricItem {
+    label: BilingualText;
+    field: string;
+    format?: ReportValueFormat;
+    currencyField?: string;
+    decimals?: number;
+    suffix?: string;
+    /** 'value' plain; 'trend' signed arrow; 'warnPercent' n% reddened + ⚠ below warnBelow. */
+    render?: 'value' | 'trend' | 'warnPercent';
+    warnBelow?: number;
+}
+/** A row inside a list-card. Header rows (title/text/price) render beside the
+ *  banner; body rows (metric-grid/trend-badges) render full-width below. */
+export type ReportCardRow = {
+    type: 'title';
+    titleField: string;
+    statusField?: string;
+    statusMap?: Record<string, {
+        label?: BilingualText;
+        tone?: string;
+    }>;
+} | {
+    /** Join multiple localized fields on one line (e.g. color · season). */
+    type: 'text';
+    fields: string[];
+    separator?: string;
+    size?: 'xs' | 'sm' | 'base';
+    muted?: boolean;
+} | {
+    type: 'price-row';
+    retailLabel?: BilingualText;
+    retailField: string;
+    sellingLabel?: BilingualText;
+    sellingField: string;
+    currencyField?: string;
+    discountField?: string;
+    discountThreshold?: number;
+    /** Discount "off" mode: show (1 − ratio) × 100 as `X%off` instead of the ratio. */
+    discountOff?: boolean;
+    /** Optional discount title; when set the discount renders as a labeled block instead of a bare badge. */
+    discountLabel?: BilingualText;
+    /** Pre-formatted discount string field from the datasource (e.g. "37.0% off"). When present it is shown verbatim — the front-end does no computation. */
+    discountTextField?: string;
+} | {
+    type: 'metric-grid';
+    columns?: number;
+    items: ReportMetricItem[];
+} | {
+    type: 'trend-badges';
+    /** Each badge shows an up/down arrow unless `trend:false` (then plain value). */
+    items: Array<{
+        label: BilingualText;
+        field: string;
+        suffix?: string;
+        trend?: boolean;
+    }>;
+};
+/** A list-card layout: optional banner thumbnail + ordered rows. */
+export interface CardLayoutConfig {
+    banner?: HeroBanner;
+    rows: ReportCardRow[];
+}
+export interface DetailNavConfig {
+    /** Detail page key opened on primary-row click. */
+    pageId?: string;
+    /** Row field holding the id (e.g. 'plu'). */
+    idField: string;
+    /** urlParams key passed to the opened tab (e.g. 'pluId'). */
+    urlParam: string;
+    /** Bus param also emitted with the id (e.g. 'pluId'). */
+    emitParam?: string;
+    /** Tab title; a {zh,en} pair of FIELD NAMES (e.g. {zh:'product_name_zh'}). */
+    titleField?: BilingualText | string;
+    icon?: string;
+}
+export interface ProductReportConfig {
+    title?: BilingualText;
+    filterComponentId?: string;
+    enabledViews?: ProductReportViewMode[];
+    defaultViewMode?: ProductReportViewMode;
+    /** Row-key + stale-guard field for the primary source. Default 'plu'. */
+    primaryKeyField?: string;
+    /** Row-key + stale-guard field for the dimension source. Default 'dim_key'. */
+    dimKeyField?: string;
+    summaryCards?: SummaryCardConfig[];
+    dimensions?: DimensionConfig[];
+    sortOptions?: SortOptionConfig[];
+    filterKeys?: FilterKeyConfig[];
+    tableColumns?: {
+        primary?: ReportColumn[];
+        dimension?: ReportColumn[];
+    };
+    listCard?: {
+        primary?: CardLayoutConfig;
+        dimension?: CardLayoutConfig;
+    };
+    detailNav?: DetailNavConfig;
+    /** Rows per page for server-side pagination (sent as `limit`; the /data endpoint auto-wraps LIMIT/OFFSET and returns the true COUNT(*) total). Defaults to 20 when unset. */
+    pageSize?: number;
+    /** @deprecated Legacy per-fetch row cap from the client-side infinite-scroll era. No longer read — pagination is server-side via pageSize. */
+    fetchLimit?: number;
+    /** Mobile only: freeze the first column (sticky-left) AND pin the table header below the
+     *  FilterPanel as the page scrolls. Off by default — turn on only for wide/long tables. */
+    freezeFirstColumn?: boolean;
+    /** Quick-scope pills row (store/national/retail/outlet/city…) shown under the dimension tabs.
+     *  The selected value is injected into the data-source params via pillParam (storeScope SQL
+     *  branches); visibleWhen typically gates it to store_manager so the HQ view stays unchanged. */
+    quickScope?: QuickScopeConfig;
+    /** Default true; false hides the "N items" counter (hidden on the SW product board per design). */
+    showItemCount?: boolean;
+    /** Footer total-row label (first column); used together with the dimension-level showTotalRow flag
+     *  and the injected totalRowDataSourceConfig prop. Defaults to the zh/en Total label. */
+    totalRowLabel?: BilingualText;
+}
+export interface QuickScopePill {
+    value: string;
+    label: BilingualText;
+}
+export interface QuickScopeConfig {
+    /** Param name the selected scope is injected into (storeScope SQL branches). */
+    pillParam?: string;
+    /** e.g. only render for store_manager — HQ view stays unchanged. */
+    visibleWhen?: VisibleWhen;
+    pills: QuickScopePill[];
+    /** Pill value the dynamic city label applies to. Default 'city'. */
+    cityPillValue?: string;
+    /** Dynamic city label template, e.g. 'City ({{cities}})' — rendered statically when
+     *  citiesDataSourceConfig is unset / the query fails / cities comes back empty. */
+    cityLabelTemplate?: string;
+    /** Optional tiny data source (first row's `cities` field fills the template). */
+    citiesDataSourceConfig?: DatabaseDataSourceConfig;
+}