grafana-react 0.0.0 → 0.0.2

package/build/types/common/field-config.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Field configuration types
+ *
+ * Types for configuring how data fields are displayed in graph panels.
+ *
+ * @see https://github.com/grafana/grafana/blob/main/packages/grafana-schema/src/common/common.gen.ts
+ */
+import type { StackingMode, GraphGradientMode, LineInterpolation, BarAlignment, VisibilityMode, LineStyleFill } from './enums.js';
+import type { AxisConfig } from './axis.js';
+import type { HideSeriesConfig } from './viz-options.js';
+import type { ThresholdStyle } from '../display.js';
+/**
+ * Stacking configuration
+ *
+ * Controls how series are stacked.
+ *
+ * @example
+ * // Normal stacking
+ * { mode: 'normal' }
+ *
+ * @example
+ * // Percent stacking with group
+ * { mode: 'percent', group: 'A' }
+ */
+export interface StackingConfig {
+    /** Stacking mode */
+    mode: StackingMode;
+    /** Stack group identifier */
+    group?: string;
+}
+/**
+ * Line style configuration
+ *
+ * Controls the appearance of lines.
+ *
+ * @example
+ * // Solid line
+ * { fill: 'solid' }
+ *
+ * @example
+ * // Dashed line with custom pattern
+ * { fill: 'dash', dash: [10, 10] }
+ */
+export interface LineStyleConfig {
+    /** Line fill style */
+    fill?: LineStyleFill;
+    /** Dash pattern array [dash, gap, dash, gap, ...] */
+    dash?: number[];
+}
+/**
+ * Graph thresholds style configuration
+ *
+ * Controls how thresholds are displayed on graphs.
+ */
+export interface GraphThresholdsStyleConfig {
+    /** Threshold display mode */
+    mode: ThresholdStyle;
+}
+/**
+ * Graph field configuration
+ *
+ * Comprehensive configuration for graph panel fields (timeseries, barchart, etc.)
+ * This extends AxisConfig to include all axis options.
+ *
+ * @example
+ * // Line graph with area fill
+ * {
+ *   drawStyle: 'line',
+ *   lineWidth: 2,
+ *   fillOpacity: 20,
+ *   gradientMode: 'opacity'
+ * }
+ *
+ * @example
+ * // Bar chart with stacking
+ * {
+ *   drawStyle: 'bars',
+ *   barAlignment: 0,
+ *   stacking: { mode: 'normal' }
+ * }
+ */
+export interface GraphFieldConfig extends AxisConfig {
+    /** Draw style for the series */
+    drawStyle?: 'line' | 'bars' | 'points';
+    /** Gradient mode for fill */
+    gradientMode?: GraphGradientMode;
+    /** Threshold display style */
+    thresholdsStyle?: GraphThresholdsStyleConfig;
+    /** Line color override */
+    lineColor?: string;
+    /** Line width in pixels */
+    lineWidth?: number;
+    /** Line interpolation style */
+    lineInterpolation?: LineInterpolation;
+    /** Line style (solid, dash, dot) */
+    lineStyle?: LineStyleConfig;
+    /** Fill color override */
+    fillColor?: string;
+    /** Fill opacity (0-100) */
+    fillOpacity?: number;
+    /** Show points on lines */
+    showPoints?: VisibilityMode;
+    /** Point size in pixels */
+    pointSize?: number;
+    /** Point color override */
+    pointColor?: string;
+    /** Stacking configuration */
+    stacking?: StackingConfig;
+    /** Hide series from legend/tooltip/viz */
+    hideFrom?: HideSeriesConfig;
+    /** Bar alignment relative to time point */
+    barAlignment?: BarAlignment;
+    /** Maximum bar width in pixels */
+    barMaxWidth?: number;
+    /** Bar width factor (0-1) */
+    barWidthFactor?: number;
+    /** Connect null values (true, false, or threshold in ms) */
+    spanNulls?: boolean | number;
+    /** Insert nulls when time gap exceeds threshold (true, false, or threshold in ms) */
+    insertNulls?: boolean | number;
+    /** Transform values */
+    transform?: 'constant' | 'negative-Y';
+}

package/build/types/common/field-config.js

@@ -0,0 +1,8 @@
+/**
+ * Field configuration types
+ *
+ * Types for configuring how data fields are displayed in graph panels.
+ *
+ * @see https://github.com/grafana/grafana/blob/main/packages/grafana-schema/src/common/common.gen.ts
+ */
+export {};

package/build/types/common/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Common types export
+ *
+ * Grafana-aligned types for panel configuration.
+ * These types match the structures defined in @grafana/schema.
+ */
+export type { VizOrientation, TooltipDisplayMode, SortOrder, VisibilityMode, AxisPlacement, AxisColorMode, LineInterpolation, BarAlignment, ScaleDistributionType, StackingMode, GraphGradientMode, BigValueJustifyMode, PercentChangeColorMode, BarGaugeSizing, BarGaugeDisplayMode, BarGaugeValueMode, BarGaugeNamePlacement, TableCellHeight, PieChartType, PieChartLabels, LineStyleFill, } from './enums.js';
+export type { ScaleDistributionConfig, AxisConfig } from './axis.js';
+export type { VizTooltipOptions, ReduceDataOptions, HideSeriesConfig, TextFormattingOptions, SingleStatBaseOptions, } from './viz-options.js';
+export type { StackingConfig, LineStyleConfig, GraphThresholdsStyleConfig, GraphFieldConfig, } from './field-config.js';

package/build/types/common/index.js

@@ -0,0 +1,7 @@
+/**
+ * Common types export
+ *
+ * Grafana-aligned types for panel configuration.
+ * These types match the structures defined in @grafana/schema.
+ */
+export {};

package/build/types/common/viz-options.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Visualization options types
+ *
+ * Types for configuring tooltips, legends, and data reduction.
+ *
+ * @see https://github.com/grafana/grafana/blob/main/packages/grafana-schema/src/common/common.gen.ts
+ */
+import type { TooltipDisplayMode, SortOrder, VizOrientation } from './enums.js';
+import type { LegendCalc } from '../display.js';
+/**
+ * Tooltip configuration
+ *
+ * Controls how tooltips are displayed on hover.
+ *
+ * @example
+ * // Single series tooltip
+ * { mode: 'single', sort: 'none' }
+ *
+ * @example
+ * // Multi-series tooltip sorted descending
+ * { mode: 'multi', sort: 'desc', maxHeight: 300 }
+ */
+export interface VizTooltipOptions {
+    /** Tooltip display mode */
+    mode: TooltipDisplayMode;
+    /** Sort order for values in tooltip (defaults to 'none') */
+    sort?: SortOrder;
+    /** Maximum tooltip height in pixels */
+    maxHeight?: number;
+    /** Maximum tooltip width in pixels */
+    maxWidth?: number;
+}
+/**
+ * Data reduction options
+ *
+ * Controls how multiple values are reduced to a single value.
+ *
+ * @example
+ * // Show last non-null value
+ * { calcs: ['lastNotNull'] }
+ *
+ * @example
+ * // Show mean and max
+ * { calcs: ['mean', 'max'] }
+ */
+export interface ReduceDataOptions {
+    /** Calculations to perform (e.g., 'mean', 'max', 'last') */
+    calcs: (LegendCalc | string)[];
+    /** Field name or regex to match */
+    fields?: string;
+    /** Reduce all values, not just series */
+    values?: boolean;
+    /** Limit number of values */
+    limit?: number;
+}
+/**
+ * Hide series configuration
+ *
+ * Controls where a series is hidden from display.
+ *
+ * @example
+ * // Hide from legend only
+ * { legend: true, tooltip: false, viz: false }
+ */
+export interface HideSeriesConfig {
+    /** Hide from legend */
+    legend: boolean;
+    /** Hide from tooltip */
+    tooltip: boolean;
+    /** Hide from visualization */
+    viz: boolean;
+}
+/**
+ * Text formatting options
+ *
+ * Font size options for single-stat style panels.
+ */
+export interface TextFormattingOptions {
+    /** Title font size in pixels */
+    titleSize?: number;
+    /** Value font size in pixels */
+    valueSize?: number;
+}
+/**
+ * Single stat base options
+ *
+ * Base options shared by stat, gauge, and bar gauge panels.
+ */
+export interface SingleStatBaseOptions extends TextFormattingOptions {
+    /** Data reduction options */
+    reduceOptions?: ReduceDataOptions;
+    /** Orientation of the visualization */
+    orientation?: VizOrientation;
+}

package/build/types/common/viz-options.js

@@ -0,0 +1,8 @@
+/**
+ * Visualization options types
+ *
+ * Types for configuring tooltips, legends, and data reduction.
+ *
+ * @see https://github.com/grafana/grafana/blob/main/packages/grafana-schema/src/common/common.gen.ts
+ */
+export {};

package/build/types/display.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Common types used across components
+ */
+/** Standard Grafana color names */
+export type ThresholdColor = 'green' | 'yellow' | 'red' | 'orange' | 'blue' | 'transparent' | 'text';
+/** Threshold display style on timeseries */
+export type ThresholdStyle = 'off' | 'line' | 'area' | 'dashed' | 'line+area' | 'dashed+area';
+/** Legend placement options */
+export type LegendPlacement = 'right' | 'bottom';
+/** Legend display modes */
+export type LegendDisplayMode = 'table' | 'list' | 'hidden';
+/** Legend calculation types */
+export type LegendCalc = 'mean' | 'max' | 'min' | 'sum' | 'last' | 'lastNotNull' | 'first' | 'count';
+/** Legend configuration */
+export interface LegendConfig {
+    placement?: LegendPlacement;
+    displayMode?: LegendDisplayMode;
+    calcs?: LegendCalc[];
+    sortBy?: string;
+    sortDesc?: boolean;
+}
+/** Common Grafana units */
+export type Unit = 'percent' | 'percentunit' | 'bytes' | 'decbytes' | 'bits' | 's' | 'ms' | 'ns' | 'dtdurations' | 'dthms' | 'Bps' | 'binBps' | 'bps' | 'reqps' | 'iops' | 'ops' | 'pps' | 'short' | 'none' | string;
+/** Color modes for panels */
+export type ColorMode = 'thresholds' | 'palette-classic' | 'palette-classic-by-name' | 'fixed' | 'continuous-GrYlRd';
+/** Threshold specification formats */
+export type ThresholdSpec = Record<number, ThresholdColor | string> | [number, ThresholdColor | string][];
+/** Variable sort options */
+export type VariableSort = 'disabled' | 'alpha' | 'alpha-desc' | 'num' | 'num-desc' | 'alpha-ci' | 'alpha-ci-desc';

package/build/types/display.js

@@ -0,0 +1,4 @@
+/**
+ * Common types used across components
+ */
+export {};

package/build/types/grafana-json.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Grafana JSON output types
+ *
+ * These types represent the final Grafana dashboard JSON structure.
+ */
+export interface GrafanaGridPos {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface GrafanaTarget {
+    refId: string;
+    expr: string;
+    legendFormat?: string;
+    instant?: boolean;
+    range?: boolean;
+    format?: 'time_series' | 'table' | 'heatmap';
+    hide?: boolean;
+}
+export interface GrafanaThreshold {
+    value: number | null;
+    color: string;
+}
+export interface GrafanaThresholds {
+    mode: 'absolute' | 'percentage';
+    steps: GrafanaThreshold[];
+}
+export interface GrafanaFieldConfig {
+    defaults: {
+        color?: {
+            mode: string;
+            fixedColor?: string;
+        };
+        custom?: Record<string, unknown>;
+        mappings?: unknown[];
+        thresholds?: GrafanaThresholds;
+        unit?: string;
+        decimals?: number;
+        min?: number;
+        max?: number;
+        noValue?: string;
+    };
+    overrides?: GrafanaOverride[];
+}
+export interface GrafanaOverride {
+    matcher: {
+        id: string;
+        options: string;
+    };
+    properties: Array<{
+        id: string;
+        value: unknown;
+    }>;
+}
+export interface GrafanaPanel {
+    id: number;
+    type: string;
+    title: string;
+    description?: string;
+    gridPos: GrafanaGridPos;
+    datasource?: {
+        uid: string;
+        type?: string;
+    };
+    targets?: GrafanaTarget[];
+    fieldConfig?: GrafanaFieldConfig;
+    options?: Record<string, unknown>;
+    transformations?: unknown[];
+    repeat?: string;
+    repeatDirection?: 'v' | 'h';
+    collapsed?: boolean;
+    panels?: GrafanaPanel[];
+    /** Plugin version (for plugin panels) */
+    pluginVersion?: string;
+}
+export interface GrafanaVariable {
+    name: string;
+    type: 'query' | 'constant' | 'custom' | 'datasource' | 'textbox';
+    label?: string;
+    query?: string | {
+        query: string;
+        refId?: string;
+        qryType?: number;
+    };
+    definition?: string;
+    current?: {
+        text: string | string[];
+        value: string | string[];
+    };
+    options?: unknown[];
+    multi?: boolean;
+    includeAll?: boolean;
+    allValue?: string;
+    refresh?: number;
+    sort?: number;
+    hide?: number;
+    regex?: string;
+}
+export interface GrafanaAnnotation {
+    name: string;
+    datasource: {
+        uid: string;
+        type?: string;
+    };
+    enable: boolean;
+    hide?: boolean;
+    iconColor: string;
+    expr?: string;
+    titleFormat?: string;
+    tagKeys?: string;
+}
+export interface GrafanaLink {
+    title: string;
+    url: string;
+    type: 'link' | 'dashboards';
+    icon?: string;
+    tooltip?: string;
+    keepTime?: boolean;
+    includeVars?: boolean;
+    targetBlank?: boolean;
+    tags?: string[];
+    asDropdown?: boolean;
+}
+export interface GrafanaDashboard {
+    uid: string;
+    title: string;
+    tags?: string[];
+    editable?: boolean;
+    refresh?: string | false;
+    time?: {
+        from: string;
+        to: string;
+    };
+    timezone?: 'browser' | 'utc' | string;
+    graphTooltip?: 0 | 1 | 2;
+    panels: GrafanaPanel[];
+    templating?: {
+        list: GrafanaVariable[];
+    };
+    annotations?: {
+        list: GrafanaAnnotation[];
+    };
+    links?: GrafanaLink[];
+    schemaVersion?: number;
+    fiscalYearStartMonth?: number;
+}

package/build/types/grafana-json.js

@@ -0,0 +1,6 @@
+/**
+ * Grafana JSON output types
+ *
+ * These types represent the final Grafana dashboard JSON structure.
+ */
+export {};

package/build/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type exports
+ *
+ * Shared types and Grafana output types.
+ * Component prop types are exported from components/index.js.
+ */
+export type { ThresholdColor, ThresholdStyle, LegendPlacement, LegendDisplayMode, LegendCalc, LegendConfig, Unit, ColorMode, ThresholdSpec, VariableSort, } from './display.js';
+export type { BasePanelProps, OverrideConfig, TableColumnOverride, Transformation, } from './panel-base.js';
+export type { GrafanaDashboard, GrafanaPanel, GrafanaTarget, GrafanaVariable, GrafanaAnnotation, GrafanaLink, GrafanaGridPos, GrafanaThreshold, GrafanaThresholds, GrafanaFieldConfig, GrafanaOverride, } from './grafana-json.js';
+export type { VizOrientation, TooltipDisplayMode, SortOrder, VisibilityMode, AxisPlacement, AxisColorMode, LineInterpolation, BarAlignment, ScaleDistributionType, StackingMode, GraphGradientMode, BigValueJustifyMode, PercentChangeColorMode, BarGaugeSizing, BarGaugeDisplayMode, BarGaugeValueMode, BarGaugeNamePlacement, TableCellHeight, PieChartType, PieChartLabels, LineStyleFill, ScaleDistributionConfig, AxisConfig, VizTooltipOptions, ReduceDataOptions, HideSeriesConfig, TextFormattingOptions, SingleStatBaseOptions, StackingConfig, LineStyleConfig, GraphThresholdsStyleConfig, GraphFieldConfig, } from './common/index.js';

package/build/types/index.js

@@ -0,0 +1,7 @@
+/**
+ * Type exports
+ *
+ * Shared types and Grafana output types.
+ * Component prop types are exported from components/index.js.
+ */
+export {};

package/build/types/panel-base.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Base panel prop types shared across all panels
+ */
+import type { ReactNode } from 'react';
+import type { ThresholdSpec } from './display.js';
+export interface BasePanelProps {
+    /** Panel title */
+    title: string;
+    /** Panel description */
+    description?: string;
+    /** Override datasource for this panel (defaults to dashboard datasource) */
+    datasource?: string;
+    /** Panel width in grid units (1-24) */
+    width?: number;
+    /** Panel height in grid units */
+    height?: number;
+    /** X position (0-23) */
+    x?: number;
+    /** Y position */
+    y?: number;
+    /** Variable to repeat panel for */
+    repeat?: string;
+    /** Repeat direction */
+    repeatDirection?: 'v' | 'h';
+    /** Panel children (queries or query strings) */
+    children?: ReactNode;
+}
+/** Override configuration for field-specific styling */
+export interface OverrideConfig {
+    /** Match by query refId */
+    refId?: string;
+    /** Match by exact field name */
+    fieldName?: string;
+    /** Match by field name regex */
+    fieldRegex?: string;
+    /** Fixed color */
+    color?: string;
+    /** Color mode (shades, fixed) */
+    colorMode?: 'shades' | 'fixed';
+    /** Override display name */
+    displayName?: string;
+    /** Override thresholds */
+    thresholds?: ThresholdSpec;
+}
+/** Table column override configuration */
+export interface TableColumnOverride {
+    /** Column name to match */
+    name: string;
+    /** Display unit */
+    unit?: string;
+    /** Column width in pixels */
+    width?: number;
+}
+/** Transformation configuration */
+export interface Transformation {
+    /** Transformation type ID */
+    id: string;
+    /** Transformation options */
+    options: Record<string, unknown>;
+}
+/** Utility props for field overrides */
+export interface OverrideProps {
+    /** Field matcher */
+    match: {
+        field?: string;
+        regex?: string;
+        refId?: string;
+    };
+    /** Properties to override */
+    properties: Record<string, unknown>;
+    children?: ReactNode;
+}

package/build/types/panel-base.js

@@ -0,0 +1,4 @@
+/**
+ * Base panel prop types shared across all panels
+ */
+export {};

package/package.json

@@ -1,5 +1,69 @@
 {
   "name": "grafana-react",
-  "version": "0.0.0",
-  "description": "React DSL for Grafana dashboards - coming soon"
-}
+  "version": "0.0.2",
+  "description": "React-based DSL for creating Grafana dashboards",
+  "type": "module",
+  "license": "MIT",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "bin": {
+    "grafana-react": "./build/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js"
+    }
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kiwi-research/grafana-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kiwi-research/grafana-react/issues"
+  },
+  "homepage": "https://github.com/kiwi-research/grafana-react#readme",
+  "keywords": [
+    "grafana",
+    "dashboard",
+    "react",
+    "jsx",
+    "dsl",
+    "monitoring",
+    "visualization",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "tsc -p ./tsconfig.json",
+    "typecheck": "tsgo --noEmit -p ./tsconfig.json",
+    "lint": "pnpm run lint:prettier && pnpm run lint:eslint",
+    "lint:eslint": "eslint src/ --cache",
+    "lint:prettier": "prettier . --check",
+    "lint-fix": "pnpm run lint-fix:prettier && pnpm run lint-fix:eslint",
+    "lint-fix:eslint": "eslint src/ --cache --fix",
+    "lint-fix:prettier": "prettier . --write",
+    "test": "node --test build/**/*.test.js"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "react": "^19.2.3",
+    "tsx": "^4.21.0",
+    "@types/node": "^25.0.5",
+    "@types/react": "^19.2.7",
+    "@typescript/native-preview": "^7.0.0-dev.20260109.1",
+    "eslint": "^9.39.2",
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.52.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}