orbcafe-ui 1.0.8 → 1.1.0

package/README.md

@@ -22,6 +22,7 @@
 | `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` |
+| `DetailInfo` | 标准详情页容器（信息块 + Tabs + 底部表格 + AI/搜索） | `src/components/DetailInfo` | `src/components/DetailInfo/README.md` |
 | `PageLayout` | 页面壳层（Header + Navigation + Content） | `src/components/PageLayout` | `src/components/PageLayout/README.md` |
 
 ### 文档查阅顺序（推荐）
@@ -36,6 +37,7 @@
 - `GraphReport Hooks`：`src/components/GraphReport/Hooks/README.md`
 - `StdReport Hooks`：`src/components/StdReport/Hooks/README.md`
 - `PageLayout Hooks`：`src/components/PageLayout/Hooks/README.md`
+- `DetailInfo` 模块文档：`src/components/DetailInfo/README.md`
 
 ---
 
@@ -105,6 +107,101 @@ module.exports = {
 }
 ```
 
+### Next.js App Router 最小接入（推荐）
+
+```tsx
+// app/page.tsx (Server Component)
+import HomeClientPage from './HomeClientPage';
+
+export default function Page() {
+  return <HomeClientPage />;
+}
+```
+
+```tsx
+// app/HomeClientPage.tsx (Client Component)
+'use client';
+
+import { CAppPageLayout } from 'orbcafe-ui';
+
+export default function HomeClientPage() {
+  return <CAppPageLayout appTitle="ORBCAFE" menuData={[]} />;
+}
+```
+
+---
+
+## Next.js 16 兼容性说明（务必阅读）
+
+官方 example 已按 Next.js `16.1.6` 调整，接入时请遵循以下规则：
+
+### 1. 动态路由参数必须在 Server Page 解包
+
+在 Next 16 中，`params` / `searchParams` 是 Promise 语义。  
+不要在 Client Page 里直接把它当普通对象枚举或访问属性。
+
+推荐写法：
+
+```tsx
+// app/detail/[id]/page.tsx (Server Component)
+import DetailClientPage from './DetailClientPage';
+
+interface PageProps {
+  params: Promise<{ id: string }>;
+}
+
+export default async function Page({ params }: PageProps) {
+  const { id } = await params;
+  return <DetailClientPage rowId={id} />;
+}
+```
+
+### 2. Client Component 避免首屏依赖不稳定值
+
+Hydration mismatch 常见来源：
+
+- 首屏直接使用 `usePathname()` 结果做高亮
+- `Date.now()` / `Math.random()` 直接参与首屏渲染
+- 仅在浏览器可用的数据（`window` / `localStorage`）首屏参与结构分支
+
+建议：
+
+- 用 `mounted`（`useEffect` 后置为 `true`）再启用这类 UI 高亮/分支
+- 浏览器侧状态在 `useEffect` 中读取
+- 保持 SSR 首屏与 CSR 首帧 DOM 结构一致
+
+### 3. 常见报错对照
+
+- `searchParams is a Promise and must be unwrapped with React.use()`  
+  根因：在错误层级直接同步访问了 `searchParams`。
+- `params are being enumerated`  
+  根因：对 `params` 做了 `Object.keys/entries` 或扩展操作。
+- `Hydration failed because the server rendered HTML didn't match the client`  
+  根因：SSR 与 CSR 首屏输出不一致（通常由路由状态或浏览器变量引起）。
+
+---
+
+## 官方 Example 验证命令
+
+提交前建议至少执行：
+
+```bash
+# 1) 构建组件库
+npm run build
+
+# 2) 校验 examples
+cd examples
+npm run lint
+npx tsc --noEmit
+```
+
+如果只想快速看运行效果：
+
+```bash
+cd examples
+npm run dev
+```
+
 ---
 
 ## Internationalization (i18n)

package/dist/index.d.mts

@@ -88,6 +88,39 @@ interface UseNavigationIslandResult {
  */
 declare const useNavigationIsland: (options?: UseNavigationIslandOptions) => UseNavigationIslandResult;
 
+type CMessageBoxType = 'success' | 'warning' | 'error' | 'info' | 'default';
+type MessageContent = string | ReactNode;
+interface MessageOptions {
+    title?: string;
+    onClose?: () => void;
+    onConfirm?: () => void;
+    confirmText?: string;
+    cancelText?: string;
+    showCancel?: boolean;
+    maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+}
+interface MessageEvent {
+    type: CMessageBoxType;
+    content: MessageContent;
+    options?: MessageOptions;
+}
+declare class MessageManager {
+    private listener;
+    register(listener: (event: MessageEvent | null) => void): void;
+    unregister(): void;
+    show(type: CMessageBoxType, content: MessageContent, options?: MessageOptions): void;
+    hide(): void;
+}
+declare const messageManager: MessageManager;
+declare const message: {
+    success: (content: MessageContent, options?: MessageOptions) => void;
+    error: (content: MessageContent, options?: MessageOptions) => void;
+    warning: (content: MessageContent, options?: MessageOptions) => void;
+    info: (content: MessageContent, options?: MessageOptions) => void;
+    show: (type: CMessageBoxType, content: MessageContent, options?: MessageOptions) => void;
+    hide: () => void;
+};
+
 /**
  * @file 10_Frontend/components/sap/ui/Common/Molecules/CMessageBox.tsx
  *
@@ -120,7 +153,6 @@ declare const useNavigationIsland: (options?: UseNavigationIslandOptions) => Use
  * --------------------------
  */
 
-type CMessageBoxType = 'success' | 'warning' | 'error' | 'info' | 'default';
 interface CMessageBoxProps {
     open: boolean;
     title?: string;
@@ -134,6 +166,7 @@ interface CMessageBoxProps {
     type?: CMessageBoxType;
 }
 declare const CMessageBox: React__default.FC<CMessageBoxProps>;
+declare const GlobalMessage: React__default.FC;
 
 interface CustomizeAgentSettings {
     baseUrl: string;
@@ -344,6 +377,7 @@ interface CTableProps {
     quickCreate?: CTableQuickCreateConfig;
     quickEdit?: CTableQuickEditConfig;
     quickDelete?: CTableQuickDeleteConfig;
+    serviceUrl?: string;
 }
 interface CTableHeadProps {
     columns: any[];
@@ -517,13 +551,14 @@ interface CSmartFilterProps {
         layoutId: string | null;
     }>;
     variantService?: IVariantService;
+    serviceUrl?: string;
 }
 /**
  * CSmartFilter Component
  *
  * Renders a filter bar with "Go" button, variant management, and "Adapt Filters" capability.
  */
-declare const CSmartFilter: ({ fields, filters, onFilterChange, variants, currentVariantId, onVariantLoad, onVariantSave, onVariantDelete, onVariantSetDefault, onSearch, loading, appId, tableKey, currentLayout, currentLayoutId, layoutRefs, variantService }: CSmartFilterProps) => react_jsx_runtime.JSX.Element;
+declare const CSmartFilter: ({ fields, filters, onFilterChange, variants, currentVariantId, onVariantLoad, onVariantSave, onVariantDelete, onVariantSetDefault, onSearch, loading, appId, tableKey, currentLayout, currentLayoutId, layoutRefs, variantService, serviceUrl }: CSmartFilterProps) => react_jsx_runtime.JSX.Element;
 
 interface CStandardPageProps {
     /** Page Title */
@@ -932,6 +967,109 @@ interface CCustomizeAgentProps {
 }
 declare const CCustomizeAgent: ({ open, onClose, value, onSaveAll, modelOptions, promptLangOptions, analysisTemplateOptions, responseTemplateOptions, defaultAnalysisTemplateId, defaultResponseTemplateId, }: CCustomizeAgentProps) => react_jsx_runtime.JSX.Element;
 
+interface DetailInfoField {
+    id: string;
+    label: string;
+    value: ReactNode;
+    searchableText?: string;
+}
+interface DetailInfoSection {
+    id: string;
+    title: string;
+    fields: DetailInfoField[];
+    columns?: 1 | 2 | 3;
+}
+interface DetailInfoTab {
+    id: string;
+    label: string;
+    description?: string;
+    content?: ReactNode;
+    sections?: DetailInfoSection[];
+    fields?: DetailInfoField[];
+}
+interface DetailInfoSearchHit {
+    source: 'section' | 'tab';
+    sourceId: string;
+    sourceSectionId?: string;
+    sourceTitle: string;
+    fieldId: string;
+    fieldLabel: string;
+    fieldValue: string;
+}
+interface DetailInfoAiConfig {
+    enabled?: boolean;
+    placeholder?: string;
+    onSubmit?: (query: string, context: {
+        query: string;
+        hits: DetailInfoSearchHit[];
+        activeTabId?: string;
+        sections: DetailInfoSection[];
+        tabs: DetailInfoTab[];
+    }) => Promise<string | void> | string | void;
+    onVoiceInput?: () => void;
+}
+interface DetailInfoTableConfig {
+    title?: string;
+    tableProps: Omit<CTableProps, 'filterConfig'>;
+}
+interface CDetailInfoPageProps {
+    title: string;
+    subtitle?: string;
+    sections: DetailInfoSection[];
+    tabs?: DetailInfoTab[];
+    defaultTabId?: string;
+    table?: DetailInfoTableConfig;
+    ai?: DetailInfoAiConfig;
+    rightHeaderSlot?: ReactNode;
+    searchBarWidth?: number | string;
+    onClose?: () => void;
+    closeLabel?: string;
+}
+
+declare const CDetailInfoPage: ({ title, subtitle, sections, tabs, defaultTabId, table, ai, rightHeaderSlot, searchBarWidth, onClose, closeLabel, }: CDetailInfoPageProps) => react_jsx_runtime.JSX.Element;
+
+type DetailInfoSearchMode = 'idle' | 'search' | 'ai';
+interface UseDetailInfoOptions {
+    sections: DetailInfoSection[];
+    tabs?: DetailInfoTab[];
+    defaultTabId?: string;
+    ai?: DetailInfoAiConfig;
+}
+interface UseDetailInfoResult {
+    query: string;
+    setQuery: (value: string) => void;
+    activeTabId?: string;
+    setActiveTabId: (value: string) => void;
+    searchMode: DetailInfoSearchMode;
+    hits: DetailInfoSearchHit[];
+    statusText: string;
+    aiResponse: string;
+    searching: boolean;
+    handleSubmit: () => Promise<void>;
+    clearResult: () => void;
+}
+declare const useDetailInfo: ({ sections, tabs, defaultTabId, ai, }: UseDetailInfoOptions) => UseDetailInfoResult;
+
+interface CDetailSearchAiBarProps {
+    value: string;
+    onChange: (value: string) => void;
+    onSubmit: () => void;
+    onVoiceInput?: () => void;
+    onClear?: () => void;
+    placeholder: string;
+    statusText?: string;
+    loading?: boolean;
+    compact?: boolean;
+    showStatusText?: boolean;
+}
+declare const CDetailSearchAiBar: ({ value, onChange, onSubmit, onVoiceInput, onClear, placeholder, statusText, loading, compact, showStatusText, }: CDetailSearchAiBarProps) => react_jsx_runtime.JSX.Element;
+
+interface CDetailSectionCardProps {
+    section: DetailInfoSection;
+    highlightQuery?: string;
+}
+declare const CDetailSectionCard: ({ section, highlightQuery }: CDetailSectionCardProps) => react_jsx_runtime.JSX.Element;
+
 type OrbcafeLocale = 'en' | 'zh' | 'fr' | 'de' | 'ja' | 'ko';
 declare const en: {
     readonly 'common.cancel': "Cancel";
@@ -1061,6 +1199,12 @@ declare const en: {
     readonly 'graph.unassigned': "Unassigned";
     readonly 'graph.column.reportHours': "Report Hours";
     readonly 'graph.column.billableHours': "Billable Hours";
+    readonly 'detail.searchAi.placeholder': "Search fields, or ask AI if no match...";
+    readonly 'detail.searchAi.matches': "{count} matches found";
+    readonly 'detail.searchAi.noMatch': "No matching field found.";
+    readonly 'detail.searchAi.autoAiFallback': "No direct match. Triggering AI analysis...";
+    readonly 'detail.searchAi.aiResultTitle': "AI Insight";
+    readonly 'detail.table.title': "Related Records";
     readonly 'quickCreate.newItem': "New Item";
     readonly 'quickCreate.createWithTitle': "Create {title}";
     readonly 'quickEdit.editWithTitle': "Edit {title}";
@@ -1152,4 +1296,98 @@ declare const usePageLayout: ({ menuData, initialNavigationCollapsed, }?: UsePag
     navigationMaxHeight: number;
 };
 
-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 };
+interface MarkdownRendererProps {
+    markdown?: string;
+    content?: string;
+    className?: string;
+    enableMath?: boolean;
+    enableMermaid?: boolean;
+    enableThinkBlock?: boolean;
+    codeCopyable?: boolean;
+    codeLineNumbers?: boolean;
+}
+declare const MarkdownRenderer: ({ markdown, content, className, enableMath, enableMermaid, enableThinkBlock, codeCopyable, codeLineNumbers, }: MarkdownRendererProps) => react_jsx_runtime.JSX.Element;
+
+interface CodeBlockProps {
+    code: string;
+    language?: string;
+    copyable?: boolean;
+    showLineNumbers?: boolean;
+    wrapLongLines?: boolean;
+    maxHeight?: number | string;
+}
+declare const CodeBlock: ({ code, language, copyable, showLineNumbers, wrapLongLines, maxHeight, }: CodeBlockProps) => react_jsx_runtime.JSX.Element;
+
+interface MathBlockProps {
+    expression: string;
+    inline?: boolean;
+    allowKatex?: boolean;
+}
+declare const MathBlock: ({ expression, inline, allowKatex }: MathBlockProps) => react_jsx_runtime.JSX.Element | null;
+
+interface MermaidBlockProps {
+    code: string;
+    title?: string;
+    height?: number | string;
+    enabled?: boolean;
+}
+declare const MermaidBlock: ({ code, title, height, enabled, }: MermaidBlockProps) => react_jsx_runtime.JSX.Element;
+
+type TableAlign = 'left' | 'center' | 'right';
+interface ParsedMarkdownTable {
+    headers: string[];
+    aligns: TableAlign[];
+    rows: string[][];
+}
+interface TableBlockProps {
+    markdown?: string;
+    table?: ParsedMarkdownTable;
+    maxHeight?: number | string;
+}
+declare const parseMarkdownTable: (markdown: string) => ParsedMarkdownTable | null;
+declare const TableBlock: ({ markdown, table, maxHeight }: TableBlockProps) => react_jsx_runtime.JSX.Element;
+
+interface ThinkBlockProps {
+    content: string;
+    title?: string;
+    defaultExpanded?: boolean;
+    isStreaming?: boolean;
+}
+declare const ThinkBlock: ({ content, title, defaultExpanded, isStreaming, }: ThinkBlockProps) => react_jsx_runtime.JSX.Element;
+
+declare const renderMarkdown: (markdown: string, options?: Omit<MarkdownRendererProps, "markdown" | "content">) => ReactNode;
+
+type PageTransitionVariant = 'none' | 'fade' | 'slide-up' | 'slide-left' | 'scale';
+interface CPageTransitionProps {
+    children: ReactNode;
+    transitionKey?: string | number;
+    variant?: PageTransitionVariant;
+    durationMs?: number;
+    delayMs?: number;
+    easing?: string;
+    disabled?: boolean;
+    sx?: SxProps<Theme>;
+}
+/**
+ * Lightweight page transition wrapper.
+ * - GPU-friendly properties only (opacity/transform)
+ * - no layout-thrashing animation
+ * - respects reduced-motion automatically
+ */
+declare const CPageTransition: ({ children, transitionKey, variant, durationMs, delayMs, easing, disabled, sx, }: CPageTransitionProps) => react_jsx_runtime.JSX.Element;
+declare const PAGE_TRANSITION_PRESETS: {
+    subtle: {
+        variant: "fade";
+        durationMs: number;
+    };
+    smooth: {
+        variant: "slide-up";
+        durationMs: number;
+    };
+    snappy: {
+        variant: "scale";
+        durationMs: number;
+    };
+};
+
+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, CDetailInfoPage, type CDetailInfoPageProps, CDetailSearchAiBar, type CDetailSearchAiBarProps, CDetailSectionCard, type CDetailSectionCardProps, 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, CPageTransition, type CPageTransitionProps, 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, CodeBlock, type CodeBlockProps, type CustomizeAgentSavePayload, type CustomizeAgentSettings, type CustomizeAgentTemplateOption, type DateOperator, type DetailInfoAiConfig, type DetailInfoField, type DetailInfoSearchHit, type DetailInfoSearchMode, type DetailInfoSection, type DetailInfoTab, type DetailInfoTableConfig, type FilterField, type FilterOperator, type FilterType, type FilterValue, GlobalMessage, 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, MarkdownRenderer, type MarkdownRendererProps, MathBlock, type MathBlockProps, MermaidBlock, type MermaidBlockProps, type MessageContent, type MessageEvent, type MessageOptions, NavigationIsland, type NavigationIslandProps, type NumberOperator, ORBCAFE_I18N_MESSAGES, type OrbcafeI18nContextValue, OrbcafeI18nProvider, type OrbcafeI18nProviderProps, type OrbcafeLocale, type OrbcafeLocaleMessages, type OrbcafeMessageKey, type OrbcafeMessageParams, PAGE_TRANSITION_PRESETS, type PageTransitionVariant, type ParsedMarkdownTable, type ReportColumn, type ReportFilter, type ReportMetadata, type SelectOperator, type TableAlign, TableBlock, type TableBlockProps, type TextOperator, ThinkBlock, type ThinkBlockProps, TreeMenu, type TreeMenuItem, type UseAmapEmbedUrlOptions, type UseDetailInfoOptions, type UseDetailInfoResult, 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, message, messageManager, parseMarkdownTable, renderMarkdown, useAmapEmbedUrl, useDetailInfo, useGoogleMapEmbedUrl, useGraphChartData, useGraphInteraction, useGraphReport, useNavigationIsland, useOrbcafeI18n, usePageLayout, useStandardReport };