vitepress-template

Appearance

Component Library and UI Patterns ​

**Referenced Files in This Document** - [[package.json]](file/ui-web/package.json) - [[ArcoCompat.tsx]](file/ui-web-admin/src/components/arcocompat.tsx) - [[DataTable.tsx]](file/ui-web/src/components/datatable.tsx) - [[KPICard.tsx]](file/ui-web/src/components/kpicard.tsx) - [[ChartComponent.tsx]](file/ui-web/src/components/chartcomponent.tsx) - [[BiAgGridTable.tsx]](file/ui-web/src/components/common/aggridtable/biaggridtable.tsx) - [[index.tsx]](file/ui-web/src/components/common/aggridtable/index.tsx) - [[columnUtils.ts]](file/ui-web/src/components/common/aggridtable/columnutils.ts) - [[exports.ts]](file/ui-web/src/components/common/aggridtable/exports.ts) - [[DateRangePickerWithShortcuts.tsx]](file/ui-web/src/components/common/daterangepickerwithshortcuts/daterangepickerwithshortcuts.tsx) - [[index.tsx]](file/ui-web/src/components/common/daterangepickerwithshortcuts/index.tsx) - [[SmartFilter.tsx]](file/ui-web/src/components/common/smartfilter/smartfilter.tsx) - [[index.tsx]](file/ui-web/src/components/common/smartfilter/index.tsx) - [[SmartFilterBar.tsx]](file/ui-web/src/components/common/smartfilterbar/smartfilterbar.tsx) - [[index.tsx]](file/ui-web/src/components/common/smartfilterbar/index.tsx) - [[ProductDetailDrawer.tsx]](file/ui-web/src/components/common/productdetaildrawer/productdetaildrawer.tsx) - [[index.tsx]](file/ui-web/src/components/common/productdetaildrawer/index.tsx) - [[DerivedMetricModal.tsx]](file/ui-web/src/components/modals/derivedmetricmodal.tsx) - [[FormulaMetricModal.tsx]](file/ui-web/src/components/modals/formulametricmodal.tsx) - [[OrderMetricModal.tsx]](file/ui-web/src/components/modals/ordermetricmodal.tsx) - [[AppLayout.tsx]](file/ui-web/src/components/layout/applayout.tsx) - [[Sidebar.tsx]](file/ui-web/src/components/layout/sidebar.tsx) - [[TopNav.tsx]](file/ui-web/src/components/layout/topnav.tsx) - [[AuthGuard.tsx]](file/ui-web/src/components/authguard.tsx) - [[RealtimeChart.tsx]](file/ui-web/src/components/realtimechart.tsx) - [[MetricContentRenderer.tsx]](file/ui-web/src/components/metriccontentrenderer.tsx) - [[MetricHelpIcon.tsx]](file/ui-web/src/components/metrichelpicon.tsx) - [[MetricTooltip.tsx]](file/ui-web/src/components/metrictooltip.tsx) - [[WidgetContentRenderer.tsx]](file/ui-web/src/components/widgetcontentrenderer.tsx) - [[DashboardGridStack.tsx]](file/ui-web/src/components/dashboardgridstack.tsx) - [[AskTableChat.tsx]](file/ui-web/src/components/asktablechat.tsx) - [[FloatingChatButton.tsx]](file/ui-web/src/components/floatingchatbutton.tsx) - [[ChatContainer.tsx]](file/ui-web/src/components/chat/chatcontainer.tsx) - [[ChatComponent.tsx]](file/bi-chat/bi-chat-web/src/components/chat/chatinterface.tsx) - [[ChartRenderer.tsx]](file/bi-chat/bi-chat-web/src/components/chat/chartrenderer.tsx) - [[ChartViewer.tsx]](file/bi-chat/bi-chat-web/src/components/chat/chartviewer.tsx) - [[Sidebar.tsx]](file/bi-chat/bi-chat-web/src/components/chat/sidebar.tsx) - [[ReflectionCard.tsx]](file/bi-chat/bi-chat-web/src/components/chat/a2ui/reflectioncard.tsx) - [[TaskPlanCard.tsx]](file/bi-chat/bi-chat-web/src/components/chat/a2ui/taskplancard.tsx) - [[ThinkingProcess.tsx]](file/bi-chat/bi-chat-web/src/components/chat/a2ui/thinkingprocess.tsx) - [[button.tsx]](file/bi-chat/bi-chat-web/src/components/ui/button.tsx) - [[scroll-area.tsx]](file/bi-chat/bi-chat-web/src/components/ui/scroll-area.tsx) - [[ChatContext.tsx]](file/bi-chat/bi-chat-web/src/context/chatcontext.tsx) - [[ChatContext.tsx]](file/ui-web/src/context/chatcontext.tsx) - [[NavigationContext.tsx]](file/ui-web/src/context/navigationcontext.tsx) - [[useAgGridColumns.tsx]](file/ui-web/src/hooks/useaggridcolumns.tsx) - [[useBuiltInColumns.tsx]](file/ui-web/src/hooks/usebuiltincolumns.tsx) - [[useCustomMetrics.ts]](file/ui-web/src/hooks/usecustommetrics.ts) - [[useECharts.ts]](file/ui-web/src/hooks/useecharts.ts) - [[useLineChartParams.ts]](file/ui-web/src/hooks/uselinechartparams.ts) - [[usePersonalization.ts]](file/ui-web/src/hooks/usepersonalization.ts) - [[useTableCellMerge.tsx]](file/ui-web/src/hooks/usetablecellmerge.tsx) - [[useTableColumns.tsx]](file/ui-web/src/hooks/usetablecolumns.tsx) - [[useTableFieldUtils.ts]](file/ui-web/src/hooks/usetablefieldutils.ts) - [[useTableGrouping.ts]](file/ui-web/src/hooks/usetablegrouping.ts) - [[useTableSummary.tsx]](file/ui-web/src/hooks/usetablesummary.tsx) - [[useWidgetDateRange.ts]](file/ui-web/src/hooks/usewidgetdaterange.ts) - [[formatters.ts]](file/ui-web/src/utils/formatters.ts) - [[request.ts]](file/ui-web/src/utils/request.ts) - [[requestInterceptor.ts]](file/ui-web/src/utils/requestinterceptor.ts) - [[getConfig.tsx]](file/ui-web/src/utils/getconfig.tsx) - [[widgetDataTransform.ts]](file/ui-web/src/utils/widgetdatatransform.ts) - [[agGridConfig.ts]](file/ui-web/src/utils/aggridconfig.ts) - [[exportExcel.ts]](file/ui-web/src/utils/exportexcel.ts) - [[menu.ts]](file/ui-web/src/config/menu.ts) - [[env.ts]](file/ui-web/src/config/env.ts) - [[env.ts]](file/ui-web-admin/src/config/env.ts) - [[globals.css]](file/ui-web/src/app/globals.css) - [[globals.css]](file/ui-web-admin/src/app/globals.css) - [[layout.tsx]](file/ui-web/src/app/layout.tsx) - [[layout.tsx]](file/ui-web-admin/src/app/layout.tsx) - [[page.tsx]](file/ui-web/src/app/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/page.tsx) - [[page.tsx]](file/ui-web/src/app/dashboard/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/dashboard/page.tsx) - [[page.tsx]](file/ui-web/src/app/dashboard/analysis/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/cms/news/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/system/users/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/tenants/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/tenants/packages/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/tenants/menus/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/system/departments/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/system/roles/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/system/configs/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/system/dicts/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/system/logs/page.tsx) - [[page.tsx]](file/ui-web-admin/src/app/dashboard)/system/menus/page.tsx)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Accessibility and UX
  9. Testing and Documentation Standards
  10. Conclusion

Introduction ​

This document describes the Component Library and UI Patterns used across the tenant console applications. It focuses on the integration of Arco Design React, custom component implementations, and the design system consistency enforced via Tailwind CSS. It also documents reusable component patterns, prop interfaces, styling approaches, form and data display components, interactive elements, composition examples, theme customization, responsive design, accessibility, keyboard navigation, screen reader compatibility, testing strategies, and documentation standards.

Project Structure ​

The tenant console consists of multiple Next.js applications:

  • ui-web: primary tenant console with dashboards, analytics, and common UI components
  • ui-web-admin: admin console for tenant and system management
  • bi-chat-web: chat interface with specialized UI components and Radix primitives

Each application integrates Arco Design React for standardized UI elements and uses Tailwind CSS for styling. The ui-web application demonstrates a comprehensive component library with custom wrappers around Arco components, ECharts for charts, and Ag-Grid for advanced tables.

Diagram sources

Section sources

Core Components ​

This section highlights the foundational components that define the UI patterns and design system.

  • DataTable: A wrapper around Arco’s Table component that auto-generates columns from tabular data and supports pagination and bordered cells.
  • KPICard: A card-based component displaying KPI metrics with trend indicators and formatted values.
  • ChartComponent: A flexible ECharts wrapper supporting line, bar, pie, and area chart types with responsive resizing and cleanup.
  • BiAgGridTable: An advanced table built on Ag-Grid with column utilities, exports, and configuration helpers.
  • DateRangePickerWithShortcuts: A date range selector with preset shortcuts for quick filtering.
  • SmartFilter and SmartFilterBar: Components enabling dynamic, contextual filtering with a compact bar interface.
  • ProductDetailDrawer: A drawer for viewing product details with nested components.
  • Modals: DerivedMetricModal, FormulaMetricModal, and OrderMetricModal encapsulate metric creation/editing workflows.
  • Layout: AppLayout, Sidebar, and TopNav provide consistent navigation and branding.
  • AuthGuard: Protects routes requiring authentication.
  • RealtimeChart: Specialized charting for real-time data streams.
  • MetricRenderers: MetricContentRenderer, MetricHelpIcon, MetricTooltip, WidgetContentRenderer, and DashboardGridStack coordinate metric display and interactivity.
  • Chat Components: AskTableChat, FloatingChatButton, and ChatContainer integrate chat functionality; bi-chat-web adds Radix-based UI and A2UI cards.

Section sources

Architecture Overview ​

The component architecture follows a layered pattern:

  • Presentation Layer: Components in ui-web and ui-web-admin wrap Arco Design React and provide consistent styling via Tailwind.
  • Data Layer: Hooks and utilities manage table columns, metrics, ECharts configuration, and data transformations.
  • Integration Layer: Providers and contexts enable cross-component communication and global state.
  • Routing Layer: Next.js app directory routes map to pages that compose components.

Diagram sources

Detailed Component Analysis ​

DataTable Component ​

DataTable wraps Arco’s Table to render paginated, bordered tables from structured data. It auto-generates columns from the first row’s keys and applies localized headers for common fields.

Diagram sources

Section sources

KPICard Component ​

KPICard displays KPI metrics with trend indicators and formatted values. It selects appropriate formatting based on metric identity and renders trend icons and colors accordingly.

Diagram sources

Section sources

ChartComponent (ECharts) ​

ChartComponent initializes and configures ECharts instances for line, bar, pie, and area charts. It manages lifecycle events, responsive resizing, and cleanup.

Diagram sources

Section sources

BiAgGridTable (Ag-Grid) ​

BiAgGridTable provides an extensible table with column utilities, export capabilities, and configuration helpers. It centralizes column generation and formatting logic.

Diagram sources

Section sources

DateRangePickerWithShortcuts ​

This component augments a date range picker with preset shortcuts, simplifying common selection patterns.

Diagram sources

Section sources

SmartFilter and SmartFilterBar ​

SmartFilter enables dynamic filters with contextual suggestions; SmartFilterBar presents a compact, actionable filter bar.

Diagram sources

Section sources

ProductDetailDrawer ​

ProductDetailDrawer renders a drawer with product details and nested components for SKU and promotion plans.

Diagram sources

Section sources

Modals (Metric Creation/Edit) ​

Modals encapsulate metric creation/editing workflows:

  • DerivedMetricModal
  • FormulaMetricModal
  • OrderMetricModal

These components share consistent patterns for form rendering, validation, and submission.

Diagram sources

Section sources

Layout and Navigation ​

AppLayout, Sidebar, and TopNav provide consistent navigation and branding across pages. AuthGuard protects protected routes.

Diagram sources

Section sources

Chat Integration ​

The tenant console integrates chat via AskTableChat and FloatingChatButton. The bi-chat-web application provides a separate UI built on Radix primitives and Recharts.

Diagram sources

Section sources

Dependency Analysis ​

The ui-web application depends on Arco Design React, ECharts, Ag-Grid, and Tailwind CSS. The ui-web-admin application also integrates Arco Design React and Plasmic for rapid UI building. The bi-chat-web application uses Radix UI primitives and Recharts.

Diagram sources

Section sources

Performance Considerations ​

  • ECharts Lifecycle: ChartComponent initializes and disposes instances properly and listens to resize events to avoid memory leaks and ensure responsiveness.
  • Ag-Grid Optimization: BiAgGridTable centralizes column generation and export logic to minimize re-renders and improve performance for large datasets.
  • Conditional Rendering: Components like KPICard and DataTable conditionally render based on data presence to avoid unnecessary computations.
  • Hook-Based State: Hooks such as useECharts, useAgGridColumns, and useCustomMetrics encapsulate side effects and memoization to optimize updates.

[No sources needed since this section provides general guidance]

Accessibility and UX ​

  • Keyboard Navigation: Components leverage Arco Design React’s built-in keyboard support for dropdowns, modals, and tables. Ensure focus management and keyboard traps are handled in custom drawers and modals.
  • Screen Reader Compatibility: Use semantic HTML and ARIA attributes where necessary. Arco components generally provide ARIA-compliant markup; verify custom overlays and tooltips announce content appropriately.
  • Focus Management: FloatingChatButton and drawers should return focus to trigger elements after closing.
  • Responsive Design: Tailwind utilities and Arco’s responsive props ensure components adapt across breakpoints. Verify charts and tables scale appropriately on smaller screens.
  • Color Contrast: Maintain sufficient contrast for trend indicators and KPI values. Use theme-aware tokens where available.

[No sources needed since this section provides general guidance]

Testing and Documentation Standards ​

  • Unit Testing: Test hooks and utilities (e.g., useAgGridColumns, useCustomMetrics, formatters) with deterministic inputs and assertions on outputs.
  • Component Testing: Use React Testing Library to render components in isolation, simulate user interactions, and assert DOM changes.
  • Integration Testing: Compose components (e.g., DataTable with SmartFilterBar) and verify data flow and UI updates.
  • Documentation Standards:
    • Keep component READMEs concise with props, usage, and examples.
    • Use Storybook or a similar tool to showcase variants and states.
    • Maintain a changelog for breaking changes and deprecations.
    • Provide TypeScript interfaces for all props to enforce type safety.

[No sources needed since this section provides general guidance]

Conclusion ​

The tenant console’s component library leverages Arco Design React and Tailwind CSS to deliver a consistent, accessible, and performant UI. Custom components like DataTable, KPICard, ChartComponent, and BiAgGridTable encapsulate common patterns, while hooks and utilities optimize data handling and rendering. The integration of chat components further enriches the user experience. Adhering to the documented patterns, accessibility guidelines, and testing standards ensures maintainability and scalability across the tenant console applications.