@superset-ui/legacy-plugin-chart-calendar

import CalendarChartPlugin from "@superset-ui/legacy-plugin-chart-calendar";

// Note: Utilities are internal and not exported from main entry
// They are only accessible from built lib structure
import { getFormattedUTCTime } from "@superset-ui/legacy-plugin-chart-calendar/lib/utils";

import CalendarChartPlugin from "@superset-ui/legacy-plugin-chart-calendar";

// Register the plugin with Superset
const calendarPlugin = new CalendarChartPlugin();

// The plugin is typically registered with Superset's chart registry
// and used through Superset's SuperChart component

/**
 * Main chart plugin class extending Superset's ChartPlugin
 */
export default class CalendarChartPlugin extends ChartPlugin {
  constructor();
}

/**
 * Creates a calendar heatmap visualization in the specified DOM element
 * @param {HTMLElement} element - DOM element to render the chart in
 * @param {CalendarProps} props - Chart configuration and data properties
 */
function Calendar(element, props);

interface CalendarProps {
  /** Chart data structure with metrics and timestamps */
  data: CalendarData;
  /** Chart height in pixels */
  height: number;
  /** Distance between calendar cells in pixels (default: 3) */
  cellPadding?: number;
  /** Border radius for calendar cells in pixels (default: 0) */
  cellRadius?: number;
  /** Size of square calendar cells in pixels (default: 10) */
  cellSize?: number;
  /** Time granularity for grouping (hour, day, week, month, year) */
  domainGranularity: string;
  /** Time granularity for individual cells (min, hour, day, week, month) */
  subdomainGranularity: string;
  /** Color scheme name for visualization */
  linearColorScheme: string;
  /** Whether to display the color legend */
  showLegend: boolean;
  /** Whether to display metric names as titles */
  showMetricName: boolean;
  /** Whether to display values within calendar cells */
  showValues: boolean;
  /** Number of color intensity steps */
  steps: number;
  /** Function to format time values for display */
  timeFormatter: (timestamp: number) => string;
  /** Function to format numeric values for display */
  valueFormatter: (value: number) => string;
  /** Mapping for verbose metric names */
  verboseMap: object;
}

interface CalendarData {
  /** Object mapping metric names to timestamp-value pairs */
  data: Record<string, Record<string, number>>;
  /** Domain granularity setting */
  domain: string;
  /** Number of time periods to display */
  range: number;
  /** Start timestamp in milliseconds */
  start: number;
  /** Subdomain granularity setting */
  subdomain: string;
}

/**
 * React wrapper component (internally named 'Calender') for the Calendar visualization with theming
 * @param {ReactCalendarProps} props - Component props including className and other properties  
 */
function ReactCalendar(props);

interface ReactCalendarProps {
  /** CSS class name for styling (required) */
  className: string;
  /** Additional props passed to underlying Calendar component (default: {}) */
  otherProps?: object;
}

/**
 * Transforms Superset chart props into Calendar component format
 * @param {SupersetChartProps} chartProps - Standard Superset chart properties
 * @returns {CalendarProps} Transformed properties for Calendar component
 */
function transformProps(chartProps);

interface SupersetChartProps {
  /** Chart height */
  height: number;
  /** Form data containing chart configuration */
  formData: FormData;
  /** Query results data array */
  queriesData: array;
  /** Datasource metadata with verboseMap */
  datasource: object;
}

interface FormData {
  /** Cell styling options */
  cellPadding: number;
  cellRadius: number;
  cellSize: number;
  /** Time granularity settings (snake_case in form data) */
  domainGranularity: string;
  subdomainGranularity: string;
  /** Visual options */
  linearColorScheme: string;
  showLegend: boolean;
  showMetricName: boolean;
  showValues: boolean;
  steps: number;
  /** Formatting options */
  xAxisTimeFormat: string;
  yAxisFormat: string;
}

/**
 * Control panel configuration for chart customization options
 */
const controlPanel: ControlPanelConfig;

interface ControlPanelConfig {
  /** Array of control panel sections */
  controlPanelSections: ControlPanelSection[];
  /** Override settings for specific controls */
  controlOverrides: Record<string, any>;
}

/**
 * Formats timestamp as UTC time string, adjusting for timezone offset
 * @param ts - Timestamp to format (number or string)
 * @param timeFormat - Optional D3 time format string
 * @returns Formatted time string
 */
export function getFormattedUTCTime(
  ts: number | string,
  timeFormat?: string
): string;

import CalendarChartPlugin from "@superset-ui/legacy-plugin-chart-calendar";

// Create and register the plugin
const calendarPlugin = new CalendarChartPlugin();

// Example data format expected by the calendar
const sampleData = {
  data: {
    "page_views": {
      "1640995200.0": 150,    // 2022-01-01 values
      "1641081600.0": 200,    // 2022-01-02 values
      "1641168000.0": 175     // 2022-01-03 values
    }
  },
  domain: "month",
  range: 12,
  start: 1640995200000,  // Start timestamp in milliseconds
  subdomain: "day"
};

import { getFormattedUTCTime } from "@superset-ui/legacy-plugin-chart-calendar/lib/utils";

// Format timestamps for display
const timestamp = 1640995200000;
const formatted = getFormattedUTCTime(timestamp, "%Y-%m-%d");
console.log(formatted); // "2022-01-01"

// Using different format patterns
const timeOnly = getFormattedUTCTime(timestamp, "%H:%M:%S");
const fullFormat = getFormattedUTCTime(timestamp, "%B %d, %Y");

// Example configuration for chart customization
const chartConfig = {
  cellSize: 15,           // Size of calendar cells (default: 10)
  cellPadding: 3,         // Space between cells (default: 3 in Calendar, 2 in control panel)
  cellRadius: 2,          // Border radius for cells (default: 0)
  steps: 5,               // Number of color intensity levels (default: 10)
  showLegend: true,       // Display color legend (default: true)
  showValues: false,      // Hide values in cells (default: false)
  showMetricName: true,   // Show metric name as title (default: true)
  domain_granularity: "month",    // Group by months (note: snake_case)
  subdomain_granularity: "day",   // Individual cells are days (note: snake_case)
  linearColorScheme: "blues"      // Color scheme
};

{
  "data": {
    "metric_name": {
      "timestamp_as_string": numeric_value,
      "1640995200.0": 150,
      "1641081600.0": 200
    }
  },
  "domain": "month",        // Time grouping level
  "range": 12,              // Number of domains to show
  "start": 1640995200000,   // Start time in milliseconds
  "subdomain": "day"        // Individual cell time unit
}