orbcafe-ui 1.0.6 → 1.0.8

package/README.md

@@ -10,6 +10,35 @@
 
 ---
 
+## 组件总目录（先看这里）
+
+下表用于快速判断“该用哪个组件、去哪个目录、看哪份细节文档”。
+
+| 模块 | 典型用途 | 代码目录 | 先看文档 |
+| --- | --- | --- | --- |
+| `Atoms` | 基础输入/按钮/文本等原子能力，作为上层组件基础件 | `src/components/Atoms` | `src/components/Atoms/README.md` |
+| `Molecules` | 组合型基础组件（如统一消息框） | `src/components/Molecules` | `src/components/Molecules/README.md` |
+| `Navigation-Island` | 左侧导航树、折叠导航、菜单路由入口 | `src/components/Navigation-Island` | `src/components/Navigation-Island/README.md` |
+| `StdReport` | 标准报表主容器（筛选、表格、分页、变体、布局） | `src/components/StdReport` | `src/components/StdReport/README.md` |
+| `GraphReport` | 图形报表弹窗（KPI、图表、联动、AI 输入区） | `src/components/GraphReport` | `src/components/GraphReport/README.md` |
+| `CustomizeAgent` | AI 参数与 Prompt 模板设置弹窗 | `src/components/CustomizeAgent` | `src/components/CustomizeAgent/README.md` |
+| `PageLayout` | 页面壳层（Header + Navigation + Content） | `src/components/PageLayout` | `src/components/PageLayout/README.md` |
+
+### 文档查阅顺序（推荐）
+
+1. 先看模块根 README：了解能力边界、最小接入示例。  
+2. 再看模块 `Hooks/README.md`：确认状态管理、参数、返回值与联动方式。  
+3. 最后看模块详细设计文档（如 `graphreport.md`）：理解内部结构与扩展点。  
+
+### 常用文档索引
+
+- `GraphReport` 详细设计：`src/components/GraphReport/graphreport.md`
+- `GraphReport Hooks`：`src/components/GraphReport/Hooks/README.md`
+- `StdReport Hooks`：`src/components/StdReport/Hooks/README.md`
+- `PageLayout Hooks`：`src/components/PageLayout/Hooks/README.md`
+
+---
+
 ## 重点组件：CMessageBox（请优先使用）
 
 `CMessageBox` 是标准体系里用于统一提示/确认交互的基础分子组件，适用于：

package/dist/index.d.mts

@@ -135,6 +135,25 @@ interface CMessageBoxProps {
 }
 declare const CMessageBox: React__default.FC<CMessageBoxProps>;
 
+interface CustomizeAgentSettings {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    promptLang: string;
+    analysisPrompt: string;
+    responsePrompt: string;
+}
+interface CustomizeAgentTemplateOption {
+    id: string;
+    label: string;
+}
+interface CustomizeAgentSavePayload {
+    settings: CustomizeAgentSettings;
+    analysisTemplateId?: string;
+    responseTemplateId?: string;
+}
+
+type GraphRow = Record<string, unknown>;
 interface GraphReportFieldMapping {
     primaryDimension: string;
     secondaryDimension: string;
@@ -151,6 +170,111 @@ interface GraphReportConfig {
     topN?: number;
     fieldMapping?: Partial<GraphReportFieldMapping>;
     statusFlagValues?: string[];
+    interaction?: {
+        enabled?: boolean;
+    };
+    aiAssistant?: {
+        enabled?: boolean;
+        placeholder?: string;
+        submitLabel?: string;
+        defaultPrompt?: string;
+        onSubmit?: (prompt: string, context: {
+            filters: GraphReportInteractionState;
+            model: GraphReportModel;
+        }) => void | Promise<void>;
+        onVoiceInput?: () => void;
+        settings?: CustomizeAgentSettings;
+        onSaveAll?: (payload: {
+            settings: CustomizeAgentSettings;
+            analysisTemplateId?: string;
+            responseTemplateId?: string;
+        }) => void | Promise<void>;
+        analysisTemplateOptions?: Array<{
+            id: string;
+            label: string;
+        }>;
+        responseTemplateOptions?: Array<{
+            id: string;
+            label: string;
+        }>;
+        defaultAnalysisTemplateId?: string;
+        defaultResponseTemplateId?: string;
+        modelOptions?: string[];
+        promptLangOptions?: string[];
+    };
+}
+interface GraphReportInteractionState {
+    primaryDimension?: string;
+    secondaryDimension?: string;
+    status?: string;
+}
+interface GraphReportKpis {
+    totalRecords: number;
+    totalReportHours: number;
+    totalBillableHours: number;
+    efficiency: number;
+    totalAmount: number;
+    flaggedCount: number;
+}
+interface GraphBarDatum {
+    name: string;
+    value: number;
+}
+interface GraphLineDatum {
+    name: string;
+    value: number;
+}
+interface GraphComboDatum {
+    name: string;
+    barValue: number;
+    lineValue: number;
+}
+interface GraphHeatmapDatum {
+    x: string;
+    y: string;
+    value: number;
+}
+interface GraphPieDatum {
+    name: string;
+    value: number;
+    percent: number;
+}
+interface GraphFishboneBranch {
+    title: string;
+    causes: string[];
+}
+interface GraphWaterfallDatum {
+    name: string;
+    value: number;
+    type?: 'delta' | 'total';
+}
+interface GraphMapLocation {
+    lat: number;
+    lng: number;
+    name?: string;
+}
+interface GraphTableColumn {
+    id: string;
+    label: string;
+    align?: 'left' | 'center' | 'right';
+}
+interface GraphReportModel {
+    title: string;
+    kpis: GraphReportKpis;
+    charts: {
+        billableByPrimary: GraphBarDatum[];
+        efficiencyBySecondary: GraphBarDatum[];
+        statusDistribution: GraphPieDatum[];
+        lineByDate?: GraphLineDatum[];
+        comboByPrimary?: GraphComboDatum[];
+        heatmapPrimarySecondary?: GraphHeatmapDatum[];
+        waterfallBillable?: GraphWaterfallDatum[];
+        fishboneStatusCauses?: GraphFishboneBranch[];
+    };
+    table: {
+        columns: GraphTableColumn[];
+        rows: GraphRow[];
+    };
 }
 
 interface CTableQuickCreateConfig {
@@ -607,6 +731,207 @@ declare const useStandardReport: ({ metadata, fetchData, initialRowsPerPage, row
     refresh: () => void;
 };
 
+interface CGraphReportProps {
+    open: boolean;
+    onClose: () => void;
+    model: GraphReportModel;
+    tableContent: ReactNode;
+    extraCharts?: ReactNode;
+    interaction?: {
+        enabled?: boolean;
+        filters: GraphReportInteractionState;
+        fieldMapping: GraphReportFieldMapping;
+        onPrimaryDimensionClick: (value: string) => void;
+        onSecondaryDimensionClick: (value: string) => void;
+        onStatusClick: (value: string) => void;
+        onClearFilter: (field: keyof GraphReportInteractionState) => void;
+        onClearAll: () => void;
+    };
+    aiAssistant?: GraphReportConfig['aiAssistant'];
+}
+declare const CGraphReport: ({ open, onClose, model, tableContent, extraCharts, interaction, aiAssistant, }: CGraphReportProps) => react_jsx_runtime.JSX.Element;
+
+interface UseGraphReportOptions {
+    rows: GraphRow[];
+    config?: GraphReportConfig;
+}
+interface UseGraphReportResult {
+    fieldMapping: GraphReportFieldMapping;
+    model: GraphReportModel;
+}
+declare const useGraphReport: ({ rows, config }: UseGraphReportOptions) => UseGraphReportResult;
+
+interface UseGraphChartDataOptions {
+    bars?: GraphBarDatum[];
+    lines?: GraphLineDatum[];
+    combos?: GraphComboDatum[];
+    heatmap?: GraphHeatmapDatum[];
+    pies?: GraphPieDatum[];
+    waterfalls?: GraphWaterfallDatum[];
+}
+interface UseGraphChartDataResult {
+    bars: GraphBarDatum[];
+    lines: GraphLineDatum[];
+    combos: GraphComboDatum[];
+    heatmap: GraphHeatmapDatum[];
+    pies: GraphPieDatum[];
+    waterfalls: GraphWaterfallDatum[];
+}
+declare const useGraphChartData: ({ bars, lines, combos, heatmap, pies, waterfalls, }: UseGraphChartDataOptions) => UseGraphChartDataResult;
+
+interface UseGoogleMapEmbedUrlOptions {
+    apiKey?: string;
+    query?: string;
+    zoom?: number;
+    mapType?: 'roadmap' | 'satellite';
+}
+declare const useGoogleMapEmbedUrl: ({ apiKey, query, zoom, mapType, }: UseGoogleMapEmbedUrlOptions) => string;
+interface UseAmapEmbedUrlOptions {
+    keyword?: string;
+    location?: GraphMapLocation;
+}
+declare const useAmapEmbedUrl: ({ keyword, location }: UseAmapEmbedUrlOptions) => string;
+
+interface UseGraphInteractionResult {
+    filters: GraphReportInteractionState;
+    setFilter: (field: keyof GraphReportInteractionState, value?: string) => void;
+    clearFilter: (field: keyof GraphReportInteractionState) => void;
+    clearAll: () => void;
+    hasActiveFilters: boolean;
+    applyRows: (rows: GraphRow[], fieldMapping: GraphReportFieldMapping) => GraphRow[];
+}
+declare const useGraphInteraction: (initialFilters?: GraphReportInteractionState) => UseGraphInteractionResult;
+
+interface CGraphChartsProps {
+    billableByPrimary: GraphBarDatum[];
+    efficiencyBySecondary: GraphBarDatum[];
+    statusDistribution: GraphPieDatum[];
+    interaction?: {
+        filters?: GraphReportInteractionState;
+        onPrimaryDimensionClick?: (value: string) => void;
+        onSecondaryDimensionClick?: (value: string) => void;
+        onStatusClick?: (value: string) => void;
+    };
+}
+declare const CGraphCharts: ({ billableByPrimary, efficiencyBySecondary, statusDistribution, interaction, }: CGraphChartsProps) => react_jsx_runtime.JSX.Element;
+
+interface CGraphKpiCardsProps {
+    kpis: GraphReportKpis;
+}
+declare const CGraphKpiCards: ({ kpis }: CGraphKpiCardsProps) => react_jsx_runtime.JSX.Element;
+
+interface CChartCardProps {
+    title: string;
+    subtitle?: string;
+    children: ReactNode;
+}
+declare const CChartCard: ({ title, subtitle, children }: CChartCardProps) => react_jsx_runtime.JSX.Element;
+
+interface CBarChartProps {
+    data: GraphBarDatum[];
+    orientation?: 'horizontal' | 'vertical';
+    valueSuffix?: string;
+    minHeight?: number;
+    activeName?: string;
+    onItemClick?: (item: GraphBarDatum) => void;
+}
+declare const CBarChart: ({ data, orientation, valueSuffix, minHeight, activeName, onItemClick, }: CBarChartProps) => react_jsx_runtime.JSX.Element;
+
+interface CLineChartProps {
+    data: GraphLineDatum[];
+    color?: string;
+    valueSuffix?: string;
+    height?: number;
+}
+declare const CLineChart: ({ data, color, valueSuffix, height, }: CLineChartProps) => react_jsx_runtime.JSX.Element;
+
+interface CComboChartProps {
+    data: GraphComboDatum[];
+    barColor?: string;
+    lineColor?: string;
+    height?: number;
+}
+declare const CComboChart: ({ data, barColor, lineColor, height, }: CComboChartProps) => react_jsx_runtime.JSX.Element;
+
+interface CHeatmapChartProps {
+    data: GraphHeatmapDatum[];
+}
+declare const CHeatmapChart: ({ data }: CHeatmapChartProps) => react_jsx_runtime.JSX.Element;
+
+interface CPieChartProps {
+    data: GraphPieDatum[];
+    variant?: 'pie' | 'donut';
+    colors?: string[];
+    size?: number;
+    activeName?: string;
+    onItemClick?: (item: GraphPieDatum) => void;
+}
+declare const CPieChart: ({ data, variant, colors, size, activeName, onItemClick, }: CPieChartProps) => react_jsx_runtime.JSX.Element;
+
+interface CFishboneChartProps {
+    effect: string;
+    branches: GraphFishboneBranch[];
+}
+declare const CFishboneChart: ({ effect, branches }: CFishboneChartProps) => react_jsx_runtime.JSX.Element;
+
+interface CWaterfallChartProps {
+    data: GraphWaterfallDatum[];
+    height?: number;
+}
+declare const CWaterfallChart: ({ data, height }: CWaterfallChartProps) => react_jsx_runtime.JSX.Element;
+
+interface CGoogleMapChartProps {
+    apiKey?: string;
+    query?: string;
+    embedUrl?: string;
+    zoom?: number;
+    mapType?: 'roadmap' | 'satellite';
+    height?: number;
+}
+declare const CGoogleMapChart: ({ apiKey, query, embedUrl, zoom, mapType, height, }: CGoogleMapChartProps) => react_jsx_runtime.JSX.Element;
+
+interface CAmapChartProps {
+    keyword?: string;
+    location?: GraphMapLocation;
+    embedUrl?: string;
+    height?: number;
+}
+declare const CAmapChart: ({ keyword, location, embedUrl, height, }: CAmapChartProps) => react_jsx_runtime.JSX.Element;
+
+interface GoogleMapEmbedOptions {
+    apiKey: string;
+    query: string;
+    zoom?: number;
+    mapType?: 'roadmap' | 'satellite';
+}
+declare const buildGoogleMapEmbedUrl: ({ apiKey, query, zoom, mapType, }: GoogleMapEmbedOptions) => string;
+declare const buildGoogleMapIframe: (options: GoogleMapEmbedOptions, height?: number) => string;
+
+interface AmapEmbedOptions {
+    keyword?: string;
+    location?: {
+        lng: number;
+        lat: number;
+        name?: string;
+    };
+    src?: string;
+}
+declare const buildAmapEmbedUrl: ({ keyword, location, src, }: AmapEmbedOptions) => string;
+
+interface CCustomizeAgentProps {
+    open: boolean;
+    onClose: () => void;
+    value: CustomizeAgentSettings;
+    onSaveAll?: (payload: CustomizeAgentSavePayload) => void | Promise<void>;
+    modelOptions?: string[];
+    promptLangOptions?: string[];
+    analysisTemplateOptions?: CustomizeAgentTemplateOption[];
+    responseTemplateOptions?: CustomizeAgentTemplateOption[];
+    defaultAnalysisTemplateId?: string;
+    defaultResponseTemplateId?: string;
+}
+declare const CCustomizeAgent: ({ open, onClose, value, onSaveAll, modelOptions, promptLangOptions, analysisTemplateOptions, responseTemplateOptions, defaultAnalysisTemplateId, defaultResponseTemplateId, }: CCustomizeAgentProps) => react_jsx_runtime.JSX.Element;
+
 type OrbcafeLocale = 'en' | 'zh' | 'fr' | 'de' | 'ja' | 'ko';
 declare const en: {
     readonly 'common.cancel': "Cancel";
@@ -769,6 +1094,13 @@ interface CAppHeaderUser {
     avatarText?: string;
     avatarSrc?: string;
 }
+interface CAppHeaderUserMenuItem {
+    key: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    onClick?: () => void;
+    disabled?: boolean;
+}
 interface CAppHeaderProps {
     appTitle: string;
     logo?: ReactNode;
@@ -781,6 +1113,9 @@ interface CAppHeaderProps {
     searchPlaceholder?: string;
     onSearch?: (query: string) => void;
     user?: CAppHeaderUser;
+    onUserSetting?: () => void;
+    onUserLogout?: () => void;
+    userMenuItems?: CAppHeaderUserMenuItem[];
     leftSlot?: ReactNode;
     rightSlot?: ReactNode;
 }
@@ -794,6 +1129,9 @@ interface CAppPageLayoutProps {
     localeOptions?: OrbcafeLocale[];
     onLocaleChange?: (locale: OrbcafeLocale) => void;
     user?: CAppHeaderUser;
+    onUserSetting?: () => void;
+    onUserLogout?: () => void;
+    userMenuItems?: CAppHeaderUserMenuItem[];
     logo?: ReactNode;
     onSearch?: (query: string) => void;
     rightHeaderSlot?: ReactNode;
@@ -801,9 +1139,9 @@ interface CAppPageLayoutProps {
     contentSx?: SxProps<Theme>;
 }
 
-declare const CAppPageLayout: ({ appTitle, menuData, children, showNavigation, locale, localeLabel, localeOptions, onLocaleChange, user, logo, onSearch, rightHeaderSlot, leftHeaderSlot, contentSx, }: CAppPageLayoutProps) => react_jsx_runtime.JSX.Element;
+declare const CAppPageLayout: ({ appTitle, menuData, children, showNavigation, locale, localeLabel, localeOptions, onLocaleChange, user, onUserSetting, onUserLogout, userMenuItems, logo, onSearch, rightHeaderSlot, leftHeaderSlot, contentSx, }: CAppPageLayoutProps) => react_jsx_runtime.JSX.Element;
 
-declare const CAppHeader: ({ appTitle, logo, mode, onToggleMode, locale: localeProp, localeLabel, localeOptions, onLocaleChange, searchPlaceholder, onSearch, user, leftSlot, rightSlot, }: CAppHeaderProps) => react_jsx_runtime.JSX.Element;
+declare const CAppHeader: ({ appTitle, logo, mode, onToggleMode, locale: localeProp, localeLabel, localeOptions, onLocaleChange, searchPlaceholder, onSearch, user, onUserSetting, onUserLogout, userMenuItems, leftSlot, rightSlot, }: CAppHeaderProps) => react_jsx_runtime.JSX.Element;
 
 interface UsePageLayoutOptions {
     menuData?: TreeMenuItem[];
@@ -814,4 +1152,4 @@ declare const usePageLayout: ({ menuData, initialNavigationCollapsed, }?: UsePag
     navigationMaxHeight: number;
 };
 
-export { Button, type ButtonProps, CAppHeader, type CAppHeaderProps, type CAppHeaderUser, CAppPageLayout, type CAppPageLayoutProps, CLayoutManagement, type CLayoutManagementProps, CLayoutManager, type CLayoutManagerProps, CMessageBox, type CMessageBoxProps, type CMessageBoxType, CPageLayout, type CPageLayoutProps, CSmartFilter, type CSmartFilterProps, CSmartTable, CStandardPage, type CStandardPageProps, CTable, CTableBody, type CTableBodyProps, CTableCell, type CTableCellProps, CTableContainer, type CTableContainerProps, CTableHead, type CTableHeadProps, type CTableProps, type CTableQuickCreateConfig, type CTableQuickDeleteConfig, type CTableQuickEditConfig, CTableRow, type CTableRowProps, CVariantManagement, type CVariantManagementProps, CVariantManager, type DateOperator, type FilterField, type FilterOperator, type FilterType, type FilterValue, type IVariantService, type LayoutMetadata, NavigationIsland, type NavigationIslandProps, type NumberOperator, ORBCAFE_I18N_MESSAGES, type OrbcafeI18nContextValue, OrbcafeI18nProvider, type OrbcafeI18nProviderProps, type OrbcafeLocale, type OrbcafeLocaleMessages, type OrbcafeMessageKey, type OrbcafeMessageParams, type ReportColumn, type ReportFilter, type ReportMetadata, type SelectOperator, type TextOperator, TreeMenu, type TreeMenuItem, type UseNavigationIslandOptions, type UseNavigationIslandResult, type UsePageLayoutOptions, type UseStandardReportOptions, type VariantMetadata, buttonVariants, useNavigationIsland, useOrbcafeI18n, usePageLayout, useStandardReport };
+export { type AmapEmbedOptions, Button, type ButtonProps, CAmapChart, type CAmapChartProps, CAppHeader, type CAppHeaderProps, type CAppHeaderUser, type CAppHeaderUserMenuItem, CAppPageLayout, type CAppPageLayoutProps, CBarChart, type CBarChartProps, CChartCard, type CChartCardProps, CComboChart, type CComboChartProps, CCustomizeAgent, type CCustomizeAgentProps, CFishboneChart, type CFishboneChartProps, CGoogleMapChart, type CGoogleMapChartProps, CGraphCharts, CGraphKpiCards, CGraphReport, type CGraphReportProps, CHeatmapChart, type CHeatmapChartProps, CLayoutManagement, type CLayoutManagementProps, CLayoutManager, type CLayoutManagerProps, CLineChart, type CLineChartProps, CMessageBox, type CMessageBoxProps, type CMessageBoxType, CPageLayout, type CPageLayoutProps, CPieChart, type CPieChartProps, CSmartFilter, type CSmartFilterProps, CSmartTable, CStandardPage, type CStandardPageProps, CTable, CTableBody, type CTableBodyProps, CTableCell, type CTableCellProps, CTableContainer, type CTableContainerProps, CTableHead, type CTableHeadProps, type CTableProps, type CTableQuickCreateConfig, type CTableQuickDeleteConfig, type CTableQuickEditConfig, CTableRow, type CTableRowProps, CVariantManagement, type CVariantManagementProps, CVariantManager, CWaterfallChart, type CWaterfallChartProps, type CustomizeAgentSavePayload, type CustomizeAgentSettings, type CustomizeAgentTemplateOption, type DateOperator, type FilterField, type FilterOperator, type FilterType, type FilterValue, type GoogleMapEmbedOptions, type GraphBarDatum, type GraphComboDatum, type GraphFishboneBranch, type GraphHeatmapDatum, type GraphLineDatum, type GraphMapLocation, type GraphPieDatum, type GraphReportConfig, type GraphReportFieldMapping, type GraphReportInteractionState, type GraphReportKpis, type GraphReportModel, type GraphRow, type GraphTableColumn, type GraphWaterfallDatum, type IVariantService, type LayoutMetadata, NavigationIsland, type NavigationIslandProps, type NumberOperator, ORBCAFE_I18N_MESSAGES, type OrbcafeI18nContextValue, OrbcafeI18nProvider, type OrbcafeI18nProviderProps, type OrbcafeLocale, type OrbcafeLocaleMessages, type OrbcafeMessageKey, type OrbcafeMessageParams, type ReportColumn, type ReportFilter, type ReportMetadata, type SelectOperator, type TextOperator, TreeMenu, type TreeMenuItem, type UseAmapEmbedUrlOptions, type UseGoogleMapEmbedUrlOptions, type UseGraphChartDataOptions, type UseGraphChartDataResult, type UseGraphInteractionResult, type UseGraphReportOptions, type UseGraphReportResult, type UseNavigationIslandOptions, type UseNavigationIslandResult, type UsePageLayoutOptions, type UseStandardReportOptions, type VariantMetadata, buildAmapEmbedUrl, buildGoogleMapEmbedUrl, buildGoogleMapIframe, buttonVariants, useAmapEmbedUrl, useGoogleMapEmbedUrl, useGraphChartData, useGraphInteraction, useGraphReport, useNavigationIsland, useOrbcafeI18n, usePageLayout, useStandardReport };