@zendir/ui 0.1.0

package/dist/react/charts/unified/theme.d.ts

@@ -0,0 +1,447 @@
+import { ThemeTokens, ThemeMode, ThemeVariant } from '../../theme';
+
+/**
+ * Zendir Brand Colors (from Brand Guide v2026)
+ * Core: Electric (#3E3CFF), Purple (#9D70FF), Prussian Blue (#1B2DA0)
+ * Shades derived using 10%, 20%, 35% white/black overlays per brand guide
+ */
+export declare const ZENDIR_BRAND_COLORS: {
+    /** Electric - Primary accent (#3E3CFF) */
+    readonly electric: "#3E3CFF";
+    /** Purple - Secondary accent (#9D70FF) */
+    readonly purple: "#9D70FF";
+    /** Prussian Blue - Subsections (#1B2DA0) */
+    readonly prussianBlue: "#1B2DA0";
+    /** Black */
+    readonly black: "#000000";
+    /** White */
+    readonly white: "#FFFFFF";
+    readonly electricLighter: "#9997FF";
+    readonly electricLight: "#6B69FF";
+    readonly electricSoft: "#5250FF";
+    readonly electricDark: "#3836E6";
+    readonly electricDarker: "#3230CC";
+    readonly electricDeep: "#2926A3";
+    readonly purpleLighter: "#C9A8FF";
+    readonly purpleLight: "#B48DFF";
+    readonly purpleSoft: "#A97FFF";
+    readonly purpleDark: "#8E64E6";
+    readonly purpleDarker: "#7E5ACC";
+    readonly purpleDeep: "#5F4499";
+    readonly prussianBlueLighter: "#4A5FD6";
+    readonly prussianBlueLight: "#3548C0";
+    readonly prussianBlueSoft: "#2838B0";
+    readonly prussianBlueDark: "#182890";
+    readonly prussianBlueDarker: "#142380";
+    readonly prussianBlueDeep: "#0F1A60";
+};
+/**
+ * Official AstroUXDS Data Visualization Color Palette
+ * Per https://astrouxds.com/design-tokens/system/#data-viz
+ *
+ * These are the OFFICIAL AstroUXDS data visualization colors from the design system.
+ * Use these for pure AstroUXDS compliance (e.g., 'astro' theme).
+ *
+ * @see https://astrouxds.com/design-tokens/system/
+ */
+export declare const OFFICIAL_ASTRO_DATA_VIZ_COLORS: {
+    /** Official AstroUXDS data visualization palette (8 colors) */
+    readonly primary: readonly ["#00c7cb", "#938bdb", "#4dacff", "#70dde0", "#c9c5ed", "#92cbff", "#a1e9eb", "#b7dcff"];
+    /** Extended palette - primary + additional derived colors for 11 max */
+    readonly extended: readonly ["#00c7cb", "#938bdb", "#4dacff", "#70dde0", "#c9c5ed", "#92cbff", "#a1e9eb", "#b7dcff", "#009a9d", "#756bb8", "#2b659b"];
+    /** Sequential palettes for heatmaps using AstroUXDS colors */
+    readonly sequential: {
+        /** Teal sequential */
+        readonly teal: readonly ["#e5f9f9", "#a1e9eb", "#70dde0", "#00c7cb", "#009a9d", "#006e70"];
+        /** Purple sequential */
+        readonly purple: readonly ["#eceaf7", "#c9c5ed", "#a9a3dc", "#938bdb", "#756bb8", "#5b5299"];
+        /** Brightblue sequential */
+        readonly brightblue: readonly ["#e8f4ff", "#b7dcff", "#92cbff", "#4dacff", "#2b659b", "#1c3f5e"];
+        /** Thermal - Status colors for temperature */
+        readonly thermal: readonly ["#00c7cb", "#56f000", "#fce83a", "#ffb302", "#ff6b35", "#ff3838"];
+    };
+};
+/**
+ * Zendir-branded Data Visualization Color Palette
+ * Uses Zendir brand colors (Electric, Purple, Prussian Blue)
+ * while maintaining AstroUXDS compliance (max 11 colors, colorblind-accessible)
+ *
+ * @see https://www.astrouxds.com/patterns/data-visualization/
+ */
+export declare const ASTRO_DATA_VIZ_COLORS: {
+    /**
+     * Primary data visualization palette - Pure Zendir Brand
+     * Uses only Zendir brand colors and their derived shades
+     * Max 11 colors per AstroUXDS compliance requirement 3.2.1
+     *
+     * NOTE: Status colors (green, yellow, red) reserved for status indication only
+     */
+    mixed: ("#3E3CFF" | "#9D70FF" | "#1B2DA0" | "#6B69FF" | "#B48DFF" | "#3548C0" | "#C9A8FF" | "#9997FF" | "#3230CC" | "#7E5ACC" | "#4A5FD6")[];
+    /**
+     * Zendir Brand palette - Full brand spectrum
+     * Complete set of Zendir brand colors for maximum brand expression
+     */
+    zendir: ("#3E3CFF" | "#9D70FF" | "#1B2DA0" | "#6B69FF" | "#B48DFF" | "#3548C0" | "#C9A8FF" | "#9997FF")[];
+    /**
+     * Extended Zendir palette - All shades for complex visualizations
+     * Includes dark and light variants for maximum differentiation
+     */
+    zendirExtended: ("#3E3CFF" | "#9D70FF" | "#1B2DA0" | "#6B69FF" | "#B48DFF" | "#3548C0" | "#C9A8FF" | "#9997FF" | "#3230CC" | "#7E5ACC" | "#142380")[];
+    /**
+     * Cool palette - Blues and purples
+     * Professional Zendir-branded cool tones
+     */
+    cool: ("#3E3CFF" | "#9D70FF" | "#1B2DA0" | "#6B69FF" | "#B48DFF" | "#3548C0" | "#9997FF" | "#4A5FD6")[];
+    /**
+     * Warm accent palette - For charts needing warm tones
+     * Use sparingly - not part of Zendir brand
+     */
+    warm: string[];
+    /**
+     * Electric-Purple gradient palette (Zendir brand gradient)
+     * Matches the official brand gradient from Electric to Purple
+     */
+    electricPurple: string[];
+    /**
+     * Prussian-Electric gradient palette
+     * Deep to vibrant brand progression
+     */
+    prussianElectric: ("#3E3CFF" | "#1B2DA0" | "#6B69FF" | "#3548C0" | "#3230CC" | "#142380")[];
+    /**
+     * Full Zendir spectrum gradient
+     * Prussian Blue → Electric → Purple
+     */
+    zendirSpectrum: ("#3E3CFF" | "#9D70FF" | "#1B2DA0" | "#6B69FF" | "#B48DFF" | "#3548C0")[];
+    /**
+     * Sequential palettes for heatmaps and gradual data
+     * Zendir brand-forward gradients
+     */
+    sequential: {
+        /** Zendir Electric sequential - Primary brand gradient */
+        electric: string[];
+        /** Zendir Purple sequential - Secondary brand gradient */
+        purple: string[];
+        /** Zendir Prussian Blue sequential - Deep brand gradient */
+        prussianBlue: string[];
+        /** Zendir gradient - Electric → Purple blend */
+        brand: string[];
+        /** Thermal - Status colors for temperature (AstroUXDS compliant) */
+        thermal: string[];
+    };
+};
+/**
+ * AstroUXDS Status Colors (DO NOT MODIFY)
+ * Per https://www.astrouxds.com/patterns/status-system/
+ *
+ * These colors are RESERVED for status indication only.
+ * Per compliance requirement, do not use status colors for
+ * non-status data visualization.
+ *
+ * @see https://www.astrouxds.com/compliance/astro-design-compliance/
+ * Rule 3.1.2: Elements indicating state shall use only specified Status Colors
+ */
+export declare const STATUS_COLORS: {
+    readonly normal: "#56f000";
+    readonly standby: "#2dccff";
+    readonly caution: "#fce83a";
+    readonly serious: "#ffb302";
+    readonly critical: "#ff3838";
+    readonly off: "#a4abb6";
+};
+/**
+ * Zendir Accent Colors for UI elements (non-status)
+ * Use these for interactive elements, highlights, and branding
+ */
+export declare const ZENDIR_ACCENT_COLORS: {
+    /** Primary accent - Zendir Electric */
+    readonly primary: "#3E3CFF";
+    /** Secondary accent - Zendir Purple */
+    readonly secondary: "#9D70FF";
+    /** Tertiary accent - Zendir Prussian Blue */
+    readonly tertiary: "#1B2DA0";
+    /** Info accent - Prussian Blue Light */
+    readonly info: "#3548C0";
+    /** Highlight - Electric Light */
+    readonly highlight: "#6B69FF";
+};
+export interface EChartsTheme {
+    color: string[];
+    backgroundColor: string;
+    textStyle: {
+        color: string;
+        fontFamily: string;
+        fontSize: number;
+        textBorderWidth?: number;
+        textBorderColor?: string;
+    };
+    title: {
+        textStyle: {
+            color: string;
+            fontSize: number;
+            fontWeight: string;
+            textBorderWidth?: number;
+            textBorderColor?: string;
+        };
+        subtextStyle: {
+            color: string;
+            fontSize: number;
+            textBorderWidth?: number;
+            textBorderColor?: string;
+        };
+    };
+    legend: {
+        textStyle: {
+            color: string;
+            fontSize: number;
+            textBorderWidth?: number;
+            textBorderColor?: string;
+        };
+        inactiveColor: string;
+    };
+    tooltip: {
+        backgroundColor: string;
+        borderColor: string;
+        borderWidth: number;
+        textStyle: {
+            color: string;
+            fontSize: number;
+            textBorderWidth?: number;
+            textBorderColor?: string;
+        };
+        extraCssText: string;
+    };
+    axisPointer: {
+        lineStyle: {
+            color: string;
+            width: number;
+        };
+        crossStyle: {
+            color: string;
+            width: number;
+        };
+    };
+    xAxis: {
+        axisLine: {
+            lineStyle: {
+                color: string;
+            };
+        };
+        axisTick: {
+            lineStyle: {
+                color: string;
+            };
+        };
+        axisLabel: {
+            color: string;
+            fontSize: number;
+            fontFamily: string;
+            textBorderWidth?: number;
+            textBorderColor?: string;
+        };
+        splitLine: {
+            lineStyle: {
+                color: string;
+                type: string;
+            };
+        };
+        nameTextStyle: {
+            color: string;
+            fontSize: number;
+            textBorderWidth?: number;
+            textBorderColor?: string;
+        };
+    };
+    yAxis: {
+        axisLine: {
+            lineStyle: {
+                color: string;
+            };
+        };
+        axisTick: {
+            lineStyle: {
+                color: string;
+            };
+        };
+        axisLabel: {
+            color: string;
+            fontSize: number;
+            fontFamily: string;
+            textBorderWidth?: number;
+            textBorderColor?: string;
+        };
+        splitLine: {
+            lineStyle: {
+                color: string;
+                type: string;
+            };
+        };
+        nameTextStyle: {
+            color: string;
+            fontSize: number;
+            textBorderWidth?: number;
+            textBorderColor?: string;
+        };
+    };
+    series: {
+        line: {
+            lineStyle: {
+                width: number;
+            };
+            symbolSize: number;
+        };
+        bar: {
+            barMaxWidth: number;
+            itemStyle: {
+                borderRadius: number[];
+            };
+        };
+        pie: {
+            itemStyle: {
+                borderColor: string;
+                borderWidth: number;
+            };
+            label?: {
+                color: string;
+                textBorderWidth: number;
+                textBorderColor: string;
+                fontSize: number;
+            };
+        };
+        scatter: {
+            symbolSize: number;
+        };
+        gauge: {
+            axisLine: {
+                lineStyle: {
+                    width: number;
+                };
+            };
+        };
+    };
+    dataZoom: {
+        backgroundColor: string;
+        borderColor: string;
+        fillerColor: string;
+        handleColor: string;
+        textStyle: {
+            color: string;
+            textBorderWidth?: number;
+            textBorderColor?: string;
+        };
+    };
+    visualMap: {
+        textStyle: {
+            color: string;
+            textBorderWidth?: number;
+            textBorderColor?: string;
+        };
+        inRange: {
+            color: string[];
+        };
+    };
+    grid: {
+        borderColor: string;
+    };
+}
+/**
+ * Generate ECharts theme from Astro tokens
+ *
+ * Creates a theme that:
+ * - Uses official AstroUXDS colors for 'astro' theme variant
+ * - Uses Zendir brand colors for all other theme variants
+ * - Maintains AstroUXDS compliance (max 11 colors, 14pt min font)
+ * - Preserves status colors for their reserved purposes
+ * - Supports both dark and light modes
+ *
+ * @param tokens - Theme tokens from ThemeProvider
+ * @param mode - Current theme mode ('dark' | 'light')
+ * @param themeVariant - Optional theme variant to determine color palette
+ * @returns ECharts theme configuration
+ */
+export declare function createAstroEChartsTheme(tokens: ThemeTokens, mode: ThemeMode, themeVariant?: ThemeVariant): EChartsTheme;
+/**
+ * Get status color from value and thresholds
+ */
+export declare function getStatusColor(value: number, thresholds: {
+    critical?: number;
+    serious?: number;
+    caution?: number;
+    normal?: number;
+}): string;
+/**
+ * Get color for series by index (wraps around palette)
+ *
+ * @param index - Series index
+ * @param palette - Color palette to use (defaults to Zendir-Astro mixed)
+ * @returns Hex color string
+ *
+ * @example
+ * ```tsx
+ * // Uses Zendir-Astro fusion palette
+ * const color = getSeriesColor(0); // #3E3CFF (Zendir Electric)
+ *
+ * // Use Zendir-only palette
+ * const brandColor = getSeriesColor(0, ASTRO_DATA_VIZ_COLORS.zendir);
+ * ```
+ */
+export declare function getSeriesColor(index: number, palette?: ("#3E3CFF" | "#9D70FF" | "#1B2DA0" | "#6B69FF" | "#B48DFF" | "#3548C0" | "#C9A8FF" | "#9997FF" | "#3230CC" | "#7E5ACC" | "#4A5FD6")[]): string;
+/**
+ * Get Zendir brand color by role
+ * Use for consistent branding across the application
+ */
+export declare function getZendirAccentColor(role: keyof typeof ZENDIR_ACCENT_COLORS): string;
+/**
+ * Get appropriate palette based on data type and optional theme
+ *
+ * @param dataType - Type of data being visualized
+ * @param useAstroTheme - If true, uses official AstroUXDS colors; otherwise Zendir colors
+ * @returns Appropriate color palette
+ *
+ * @example
+ * ```tsx
+ * // For general multi-series data (Zendir brand - default)
+ * const colors = getPaletteForDataType('categorical');
+ *
+ * // For official AstroUXDS colors
+ * const astroColors = getPaletteForDataType('categorical', true);
+ *
+ * // For Zendir brand-forward charts
+ * const brandColors = getPaletteForDataType('zendir');
+ *
+ * // For official AstroUXDS palette explicitly
+ * const officialColors = getPaletteForDataType('astro-official');
+ *
+ * // For status-based data (uses reserved AstroUXDS status colors)
+ * const statusColors = getPaletteForDataType('status');
+ * ```
+ */
+export declare function getPaletteForDataType(dataType: 'categorical' | 'sequential' | 'diverging' | 'status' | 'zendir' | 'zendirExtended' | 'cool' | 'warm' | 'astro-official', useAstroTheme?: boolean): string[];
+/**
+ * Create gradient for area charts
+ */
+export declare function createAreaGradient(color: string, direction?: 'vertical' | 'horizontal'): {
+    type: 'linear';
+    x: number;
+    y: number;
+    x2: number;
+    y2: number;
+    colorStops: Array<{
+        offset: number;
+        color: string;
+    }>;
+};
+/**
+ * Format time for axis labels
+ */
+export declare function formatTimeLabel(timestamp: number, format?: 'short' | 'medium' | 'long'): string;
+/**
+ * Format number with unit suffix
+ */
+export declare function formatValueWithUnit(value: number, unit?: string, precision?: number): string;
+/**
+ * Calculate nice axis bounds
+ */
+export declare function calculateAxisBounds(values: number[], padding?: number): {
+    min: number;
+    max: number;
+};