vitepress-template

Appearance

Dashboard System ​

**Referenced Files in This Document** - [[dashboard.ts]](file/ui-web/src/types/dashboard.ts) - [[DashboardGridStack.tsx]](file/ui-web/src/components/dashboardgridstack.tsx) - [[WidgetContentRenderer.tsx]](file/ui-web/src/components/widgetcontentrenderer.tsx) - [[useECharts.ts]](file/ui-web/src/hooks/useecharts.ts) - [[RealtimeChart.tsx]](file/ui-web/src/components/realtimechart.tsx) - [[page.tsx]](file/ui-web/src/app/dashboard/page.tsx) - [[useBiStore.ts]](file/ui-web/src/store/usebistore.ts)

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. Troubleshooting Guide
  9. Conclusion

Introduction ​

This document describes the Dashboard System, the core visualization interface of the tenant console. It covers the grid-based layout architecture using GridStack, drag-and-drop widget management, real-time metric rendering with ECharts 6.x, and the dashboard configuration system. It also documents widget customization options, responsive layout patterns, state management for persistence and user preferences, and integration with backend APIs for real-time data updates.

Project Structure ​

The dashboard system centers around a grid container that hosts multiple widgets. Each widget renders its own visualization via a content renderer and supports editing, deletion, and dynamic parameter changes. The system integrates with ECharts for charts and uses a shared store for global BI metadata.

Diagram sources

Section sources

Core Components ​

  • Grid container and layout engine: GridStack-based container that manages widget placement, resizing, and dragging.
  • Widget renderer: A content router that selects the appropriate visualization component for each widget type.
  • Chart hooks: ECharts integration via a reusable hook and a dedicated realtime chart component.
  • Types and configuration: Strongly typed widget model and configuration structures.
  • State management: Global store for BI metadata and user preferences.

Section sources

Architecture Overview ​

The dashboard composes a grid container that initializes GridStack, creates per-widget React roots, and mounts content renderers. Widgets expose controls for editing, deleting, and adjusting parameters. Charts are rendered using ECharts through a shared hook and a specialized realtime component.

Diagram sources

Detailed Component Analysis ​

GridStack-Based Layout and Drag-and-Drop ​

  • Grid initialization: Configures GridStack with fixed column count, spacing, and disabled animations to reduce flicker. Enables/disables drag/resize based on edit mode.
  • Widget lifecycle: Creates a DOM element per widget, attaches gs-* attributes, and mounts a React root to render the WidgetCard. Tracks mounted widgets and their roots to support updates and removal.
  • Position synchronization: On drag/resize end events, reads the GridStack engine nodes and writes back updated x/y/w/h to the widget list, then persists layout.
  • Loading-aware updates: Renders only the subset of widgets whose loading state has changed to minimize re-renders.

Diagram sources

Section sources

Widget Rendering and Customization ​

  • Type routing: The renderer selects the appropriate content component based on widget type (card, table, line, pie).
  • Parameter controls: For line charts, exposes metric selection, granularity, and period comparison toggles. For pie charts, allows dimension selection persisted to local storage.
  • Editing and deletion: Opens modal dialogs to edit or delete widgets, updating both UI state and backend layout.
  • Date range and sorting: Provides time range pickers and sorting controls, propagating changes to parent handlers.

Diagram sources

Section sources

Real-Time Metric Rendering with ECharts 6.x ​

  • ECharts hook: Encapsulates initialization, option setting, resize observation, and cleanup. Accepts dependencies to re-render when inputs change.
  • Realtime chart: Specialized component for streaming data, formatting timestamps, and applying smooth line styling with area fill.
  • Integration pattern: Widgets can leverage the hook to render charts, while the realtime component targets live streams.

Diagram sources

Section sources

Dashboard Configuration System and Types ​

  • Widget model: Defines widget identity, position, size, type, and data payload. Includes configuration fields for chart parameters and search filters.
  • Templates and metadata: Supports template-driven widgets and dimension/field dictionaries for display and formatting.

Diagram sources

Section sources

State Management for Persistence and Preferences ​

  • Global BI store: Initializes and holds user, operational info, menus, and quick menu preferences. Exposes methods to refresh menus and toggle quick menu items.
  • Widget preferences: Pie dimension selections are cached in local storage keyed by the selected metric to persist user choices across sessions.

Diagram sources

Section sources

Responsive Layout Patterns ​

  • Fixed column grid: GridStack configured with a fixed column count and compact cell height to maintain consistent sizing across devices.
  • Minimum size constraints: Each widget type defines minimum width/height to prevent overly small components.
  • Content area sizing: Widget content areas use flexbox with overflow hidden to adapt to container sizes.

Section sources

Backend Integration and Data Flows ​

  • Preview and save: Adding a widget triggers a preview call to fetch initial data, then persists the layout to the backend. Deleting a widget removes it locally and saves the updated layout.
  • Real-time updates: The dashboard page simulates periodic updates to realtime data; in practice, integrate WebSocket or polling to backend endpoints.

Diagram sources

Section sources

Examples and How-To Guides ​

  • Add a new widget

    • Open the add modal, select widget type and template (or metric for pie), compute default position, call preview to fetch data, then persist layout to backend.
    • Reference: [DashboardGridStack.tsx]

  • Configure chart types and parameters

    • For line charts, choose granularity, metrics, and period comparison; for pie charts, select the dimension; changes propagate to callbacks and are persisted.
    • Reference: [WidgetContentRenderer.tsx]

  • Implement a custom visualization component

  • Integrate with backend APIs for real-time data

    • Replace simulated intervals with WebSocket listeners or polling endpoints; use the existing hooks to initialize and update charts.
    • References:

Dependency Analysis ​

The dashboard system exhibits low coupling between components, with clear separation of concerns:

  • Grid container depends on GridStack and React roots for rendering.
  • Widget renderer depends on content components and shared metadata from the BI store.
  • Chart integrations rely on the ECharts hook and optional realtime component.
  • State is centralized in the BI store, accessed by both grid and widgets.

Diagram sources

Section sources

Performance Considerations ​

  • Minimize re-renders: Only render widgets whose loading state changed; avoid full-grid updates on partial changes.
  • Disable animations: GridStack animation disabled to prevent layout thrashing during drag/resize.
  • Lazy initialization: Import GridStack dynamically to defer heavy initialization until needed.
  • Efficient chart updates: Use the ECharts hook to dispose and recreate instances when options change, preventing memory leaks and stale configurations.
  • Local caching: Persist frequently used widget preferences (e.g., pie dimension) in local storage to avoid repeated lookups.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

  • GridStack fails to initialize

    • Verify the grid container exists and GridStack is imported dynamically. Check for errors in the initialization block and ensure the DOM is ready.
    • Reference: [DashboardGridStack.tsx]

  • Widgets not appearing after adding

    • Confirm that new widgets are appended to the grid and that the React root is created and mounted. Check the add-to-grid routine and rendered IDs tracking.
    • Reference: [DashboardGridStack.tsx]

  • Drag/resize does not persist

    • Ensure dragstop/resizestop handlers are firing and that the widget list is updated with new positions. Verify skipNextUpdate logic is not blocking updates.
    • Reference: [DashboardGridStack.tsx]

  • ECharts not rendering or resizing

    • Confirm the container ref is present and the hook is invoked with a valid option. Check that the container is visible and the ResizeObserver is observing the element.
    • References:

  • Pie dimension preference not applied

Section sources

Conclusion ​

The Dashboard System provides a robust, extensible foundation for building interactive, customizable dashboards. Its GridStack-based layout, modular widget rendering, and ECharts integration enable rich visualizations with strong performance characteristics. By leveraging the provided hooks, types, and state management patterns, developers can add new widget types, integrate backend data sources, and implement responsive, real-time experiences tailored to tenant needs.