@unblind/react 0.1.0-alpha.9 → 0.1.0-beta.1

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { QueryClient, QueryClientConfig } from '@tanstack/react-query';
 import React$1, { ReactNode } from 'react';
 import { StringValue } from 'ms';
-import uPlot from 'uplot';
+import uPlot$1 from 'uplot';
 
 type UnblindClientConfig = {
     /**
@@ -50,7 +50,7 @@ type UnblindClientProviderProps = {
  *   return (
  *     <>
  *       <button onClick={() => refresh()}>Refresh</button>
- *       <TimeseriesChart metrics={["cpu"]} />
+ *       <Timeseries metrics={["cpu"]} />
  *     </>
  *   );
  * }
@@ -58,20 +58,14 @@ type UnblindClientProviderProps = {
  */
 declare function useRefresh(): () => Promise<void>;
 
-interface TooltipItem {
-    metric: MetricMetadata;
-    serie: uPlot.Series;
-    color: string;
-    value?: number;
-    formattedValue?: string;
-    attributes?: Record<string, string>;
-}
-type TooltipLayout = "auto" | "group-by-metric" | "flat";
-type TooltipFormat = "original" | "suffix" | "title";
 interface TooltipProps {
     timestamp: number;
-    items: TooltipItem[];
+    tooltipSerieList: TooltipSerie[];
     timeZone?: string;
+    stacked?: boolean;
+    invertSort?: boolean;
+    visibilityLimit?: number;
+    disableSuggestedLabel?: boolean;
 }
 
 /**
@@ -83,29 +77,21 @@ type MetricType = "gauge" | "sum" | "histogram" | "summary" | "exphistogram";
  * Aggregation operators available for metric queries.
  */
 type AggregationOperator = "avg" | "sum" | "max" | "min" | "p90" | "p99" | "p50";
-/**
- * Attribute filter with a specific value.
- */
-interface AttributeWithValue {
-    name: string;
-    value: string;
-}
 /**
  * Metric metadata returned by the API.
  */
 interface MetricMetadata {
     name: string;
     description: string;
-    displayName?: string;
+    suggestedLabel?: string;
     unit: {
         code?: string;
-        name?: string;
-        synonym?: string;
-        category?: string;
     };
     type: MetricType;
-    operator?: AggregationOperator;
 }
+type LabeledMetricMetadata = MetricMetadata & {
+    label?: string;
+};
 /**
  * List of metric metadata.
  */
@@ -117,7 +103,6 @@ interface Serie {
     metric: string;
     attributes?: Record<string, string>;
     values: Array<number>;
-    queryName?: string;
     queryIndex: number;
     isEmpty?: boolean;
 }
@@ -125,7 +110,6 @@ interface Serie {
  * Query definition for timeseries requests.
  */
 interface TimeseriesQuery {
-    queryName?: string;
     metrics: Array<string>;
     groupBy?: Array<string>;
     operator?: AggregationOperator;
@@ -143,19 +127,20 @@ type ChartType = "bar" | "line" | "area" | "step" | "spline";
 type TimeRange = StringValue;
 interface Log {
     timestamp: number;
-    trace_id?: string;
-    span_id?: string;
-    severity_text: Severity;
+    traceId?: string;
+    spanId?: string;
+    logId?: string;
+    severity: Severity;
     attributes?: Record<string, string>;
-    service_name?: string;
     body?: string;
+    serviceName?: string;
 }
 /**
  * Default paginated response structure
  */
 type PaginatedResponse<T> = {
     data: Array<T>;
-    next_page?: string;
+    nextPage?: string;
 };
 /**
  * Different severity values based on OTEL
@@ -217,11 +202,6 @@ interface ChartVisualConfig {
      * Optional color configuration
      */
     colors?: Colors;
-    /**
-     * Optional order for rendering results.
-     * Defaults to false
-     */
-    sortByValues?: boolean;
     /**
      * Optional to fill charts.
      *
@@ -232,13 +212,61 @@ interface ChartVisualConfig {
      * Optional tooltip configuration.
      */
     tooltip?: TooltipConfig;
+    /**
+     * Chart type. Defaults to "line".
+     */
+    type?: ChartType;
+    /**
+     * Optional threshold
+     */
+    thresholds?: Array<Threshold>;
+    /**
+     * Optional min value
+     */
+    min?: number;
+    /**
+     * Optional max value
+     */
+    max?: number;
+    /**
+     * Optional boolean to hide both axis
+     */
+    hideAxis?: boolean;
+    /**
+     * Optional boolean to hide cursor
+     */
+    hideCursor?: boolean;
+    /**
+     * Optional boolean to display relative time axis
+     *
+     * e.g. a day ago ------ a few seconds ago
+     */
+    relativeTimeAxis?: boolean;
+    /**
+     * Unit of measurement for the value.
+     *
+     * Supports standard unit identifiers:
+     * - Data: 'bytes', 'decbytes', 'bits', 'decbits'
+     * - Time: 'ms', 's', 'm', 'h', 'd'
+     * - Throughput: 'Bps', 'Mbps', 'Gbps'
+     * - Percentage: 'percent', 'percentunit'
+     * - And many more standard units
+     *
+     */
+    unit?: string;
+    /**
+     * Optional invert value order.
+     * Defaults to false
+     */
+    invertSort?: boolean;
+    /**
+     * Disables suggested label
+     */
+    disableSuggestedLabel?: boolean;
 }
 interface TooltipConfig {
-    layout?: TooltipLayout;
-    format?: TooltipFormat;
-    hideAttributeKey?: boolean;
-    hideAttributes?: boolean;
-    hideMetric?: boolean;
+    hide?: boolean;
+    visibilityLimit?: number;
 }
 /**
  * Appearance configuration for Unblind components.
@@ -246,7 +274,7 @@ interface TooltipConfig {
  * Allows consumers to override internal UI components used for
  * loading, empty, and error states.
  *
- * Overrides can be provided globally via UnblindScope or
+ * Overrides can be provided globally via Scope or
  * locally per component.
  *
  * This API customizes presentation only; component state and data
@@ -259,9 +287,37 @@ type Appearance = {
         Empty?: React.ComponentType;
         Tooltip?: React.ComponentType<TooltipProps>;
     };
-} & ChartVisualConfig;
+};
+type ThresholdLevel = "info" | "warning" | "error" | "ok";
+type ThresholdLineType = "line" | "dashed" | "bold";
+type LineThreshold = {
+    value: number;
+    type?: ThresholdLineType;
+    level?: ThresholdLevel;
+    label?: string;
+};
+type RangeThreshold = {
+    from: number;
+    to?: number;
+    type?: ThresholdLineType;
+    level?: ThresholdLevel;
+    label?: string;
+};
+type Threshold = LineThreshold | RangeThreshold;
+interface TooltipSerie {
+    metric: LabeledMetricMetadata;
+    serie: uPlot.Series;
+    color: string;
+    value?: number;
+    formattedValue?: string;
+    attributes?: Record<string, string>;
+}
+interface LabeledMetric {
+    name: string;
+    label: string;
+}
 
-type UnblindScopeConfig = TimeseriesQueryConfig & {
+type ScopeConfig = TimeseriesQueryConfig & ChartVisualConfig & {
     /**
      * Optional appearance configuration for all components
      * within this scope.
@@ -274,7 +330,7 @@ type UnblindScopeConfig = TimeseriesQueryConfig & {
      *
      * @example
      * ```tsx
-     * <UnblindScope
+     * <Scope
      *   appearance={{
      *     components: {
      *       Loading: CustomLoading,
@@ -283,16 +339,16 @@ type UnblindScopeConfig = TimeseriesQueryConfig & {
      *   }}
      * >
      *   <App />
-     * </UnblindScope>
+     * </Scope>
      * ```
      */
     appearance?: Appearance;
 };
-type UnblindScopeProps = UnblindScopeConfig & {
+type ScopeProps = ScopeConfig & {
     children?: React$1.ReactNode;
 };
 /**
- * UnblindScope provides scoped configuration for all Unblind components (charts, logs, etc).
+ * Scope provides scoped configuration for all Unblind components (charts, logs, etc).
  * This includes default time ranges, intervals, attributes, groupBy, operator, appearance, and colors.
  *
  * When nested, child scopes inherit defaults from parent scopes and can override specific values.
@@ -301,26 +357,26 @@ type UnblindScopeProps = UnblindScopeConfig & {
  *
  * @example
  * ```tsx
- * import { UnblindScope } from '@unblind/react';
+ * import { Scope } from '@unblind/react';
  *
  * function App() {
  *   return (
- *     <UnblindScope
+ *     <Scope
  *       appearance={{ components: { Loading: CustomLoading } }}
  *       timeRange="24h"
  *     >
  *       // Components here use 24h and CustomLoading
  *
- *       <UnblindScope timeRange="1h">
+ *       <Scope timeRange="1h">
  *         // Components here use 1h but still inherit CustomLoading
- *       </UnblindScope>
- *     </UnblindScope>
+ *       </Scope>
+ *     </Scope>
  *   );
  * }
  * ```
  */
-declare function UnblindScope({ children, timeRange, startTime, endTime, interval, attributes, groupBy, operator, appearance, }: UnblindScopeProps): react_jsx_runtime.JSX.Element;
-type UseScopeReturn = TimeseriesQueryConfig & {
+declare function Scope({ children, timeRange, startTime, endTime, interval, attributes, groupBy, operator, appearance, tooltip, colors, fill, hideAxis, hideCursor, relativeTimeAxis, invertSort, disableSuggestedLabel, }: ScopeProps): react_jsx_runtime.JSX.Element;
+type UseScopeReturn = TimeseriesQueryConfig & ChartVisualConfig & {
     timeRange: TimeRange;
     appearance: {
         components: {
@@ -329,14 +385,10 @@ type UseScopeReturn = TimeseriesQueryConfig & {
             Empty: React$1.ComponentType;
             Tooltip?: React$1.ComponentType<TooltipProps>;
         };
-        colors: Colors;
-        sortByValues?: boolean;
-        fill?: boolean;
-        tooltip?: TooltipConfig;
     };
 };
 /**
- * Hook to access the scoped configuration from UnblindScope.
+ * Hook to access the scoped configuration from Scope.
  * Returns all configuration including time range, attributes,
  * groupBy, operator, colors, and UI components.
  *
@@ -350,13 +402,13 @@ type UseScopeReturn = TimeseriesQueryConfig & {
  */
 declare function useScope(): UseScopeReturn;
 
-type UnblindProviderProps = UnblindClientProviderProps & UnblindScopeProps & {
+type UnblindProviderProps = UnblindClientProviderProps & ScopeProps & {
     children?: React.ReactNode;
 };
 /**
  * UnblindProvider is required for all Unblind hooks to work.
  * It sets up both the QueryClientProvider (for React Query) and the Unblind configuration context.
- * This is a convenience wrapper around UnblindClientProvider and UnblindScope.
+ * This is a convenience wrapper around `UnblindClientProvider` and `Scope`.
  *
  * @example
  * ```tsx
@@ -371,7 +423,7 @@ type UnblindProviderProps = UnblindClientProviderProps & UnblindScopeProps & {
  * }
  * ```
  */
-declare function UnblindProvider({ children, queryClient, apiBaseUrl, fetchImpl, timeRange, startTime, endTime, interval, attributes, groupBy, operator, appearance, }: UnblindProviderProps): react_jsx_runtime.JSX.Element;
+declare function UnblindProvider({ children, queryClient, apiBaseUrl, fetchImpl, timeRange, startTime, endTime, interval, attributes, groupBy, operator, appearance, tooltip, colors, fill, hideAxis, hideCursor, relativeTimeAxis, invertSort, disableSuggestedLabel, }: UnblindProviderProps): react_jsx_runtime.JSX.Element;
 
 interface UseMetricsReturn {
     metrics: MetricMetadataList | undefined;
@@ -392,12 +444,13 @@ interface UseTimeseriesParams extends Pick<TimeseriesQueryConfig, "timeRange" |
      */
     queries: Array<TimeseriesQuery>;
 }
+interface UseTimeseriesData {
+    series: Serie[];
+    times: number[];
+    metadata: Record<string, MetricMetadata>;
+}
 interface UseTimeseriesReturn {
-    data: {
-        series: Serie[];
-        times: number[];
-        metadata: Record<string, MetricMetadata>;
-    };
+    data: UseTimeseriesData;
     isLoading: boolean;
     isFetching: boolean;
     hasError: boolean;
@@ -409,7 +462,7 @@ interface UseTimeseriesReturn {
  * @param params - Configuration object with queries, and either timeRange or startTime/endTime, plus optional interval.
  * @returns Object containing timeseries data, loading states, and error state.
  */
-declare function useTimeseries({ queries, timeRange, startTime, endTime, interval, }: UseTimeseriesParams): UseTimeseriesReturn;
+declare function useTimeseries(params: UseTimeseriesParams): UseTimeseriesReturn;
 
 interface Usage {
     period: {
@@ -437,13 +490,18 @@ interface UseUsageReturn {
  * @param params - Configuration object with optional timeRange.
  * @returns Object containing usage data, loading state, and error state.
  */
-declare function useUsage({ timeRange, startTime, endTime, }: UseUsageParams): UseUsageReturn;
+declare function useUsage(params: UseUsageParams): UseUsageReturn;
 
 type UseLogsParams = {
     /**
      * Array of filters to apply to the logs query.
      */
-    filters: Array<AttributeWithValue>;
+    attributes?: Record<string, Array<string>>;
+    body?: Array<string>;
+    severity?: Array<string>;
+    traceId?: string;
+    spanId?: string;
+    logId?: string;
 } & TimeConfig;
 interface UseLogsReturn {
     logs: Array<Log>;
@@ -460,33 +518,30 @@ interface UseLogsReturn {
  * @param params - Configuration object with timeRange and filters.
  * @returns Object containing logs data, loading states, and pagination controls.
  */
-declare function useLogs({ timeRange, filters, startTime, endTime, }: UseLogsParams): UseLogsReturn;
-
-declare function useTheme(): boolean;
+declare function useLogs(props: UseLogsParams): UseLogsReturn;
 
-type TimeseriesChartProps = Exclude<TimeseriesQueryConfig, "startTime" | "endTime" | "timeRange"> & {
+type TimeseriesProps = Exclude<TimeseriesQueryConfig, "startTime" | "endTime" | "timeRange"> & ChartVisualConfig & {
     /**
      * Metric name(s) to display in the chart.
      *
-     * Optional: a single string name.
-     */
-    metrics: Array<string> | string;
-    /**
-     * Chart type. Defaults to "line".
-     */
-    type?: ChartType;
-    /**
-     * Unit of measurement for the value.
+     * @example  Single metric
+     * ```jsx
+     * <Timeseries metrics="nodejs.eventloop.p50" />
+     * ```
      *
-     * Supports standard unit identifiers:
-     * - Data: 'bytes', 'decbytes', 'bits', 'decbits'
-     * - Time: 'ms', 's', 'm', 'h', 'd'
-     * - Throughput: 'Bps', 'Mbps', 'Gbps'
-     * - Percentage: 'percent', 'percentunit'
-     * - And many more standard units
+     * @example
+     * Multiple metrics
+     * ```jsx
+     * <Timeseries metrics={["nodejs.eventloop.p50", "..."]} />
+     * ```
      *
+     * @example
+     * Labeled metrics
+     * ```jsx
+     * <Timeseries metrics={{ name: "nodejs.eventloop.p50", label: "P50" ]} />
+     * ```
      */
-    unit?: string;
+    metrics: Array<LabeledMetric> | Array<string> | string;
     /**
      * Optional className for the chart container.
      */
@@ -495,40 +550,45 @@ type TimeseriesChartProps = Exclude<TimeseriesQueryConfig, "startTime" | "endTim
      * Optional appearance configuration for this chart
      */
     appearance?: Appearance;
+    /**
+     * Hook to get request data
+     */
+    onResponse?: (response: UseTimeseriesReturn) => void;
 };
 /**
- * TimeseriesChart component that displays time series data for the given metrics.
- * It uses values from the UnblindProvider for timeRange, attributes, groupBy, and operator
- * if not explicitly provided as props.
+ * Displays a time series chart.
+ * Uses values from <UnblindProvider> or <Scope>
+ * when they are not explicitly provided as props.
  *
- * @example Using [UnblindProvider]
+ * @example
  * ```tsx
- * <UnblindProvider timeRange="1h">
- *   <TimeseriesChart metrics={["host.cpu"]} />
- *   <TimeseriesChart metrics={["host.memory"]} />
- * </UnblindProvider>
+ *  <Timeseries
+ *    metrics="host.cpu"
+ *    attributes={{ "host.region": ["us-east-2"] }}
+ *    groupBy={["host.name"]}
+ *   />
  * ```
  *
- * @example Using <UnblindScope>
+ * @example Using `<Scope>`
  * ```tsx
- * <UnblindScope timeRange="1h">
- *   <TimeseriesChart metrics={["host.cpu"]} />
- *   <TimeseriesChart metrics={["host.memory"]} />
- * </UnblindScope>
+ * <Scope timeRange="1h">
+ *   <Timeseries metrics="host.cpu" />
+ *   <Timeseries metrics="host.memory" />
+ * </Scope>
  * ```
  */
-declare function TimeseriesChart({ metrics, operator: propOperator, attributes: propAttributes, groupBy: propGroupBy, interval: propInterval, type, className, appearance: propAppearance, unit: propUnit, }: TimeseriesChartProps): react_jsx_runtime.JSX.Element;
+declare function Timeseries({ metrics, operator: propOperator, attributes: propAttributes, groupBy: propGroupBy, interval: propInterval, type, className, appearance: propAppearance, tooltip: propTooltip, onResponse, ...chartStyleProps }: TimeseriesProps): react_jsx_runtime.JSX.Element;
 
 interface ChartProps extends ChartVisualConfig {
     times: Array<number>;
     series: Serie[];
-    metadata: Record<string, MetricMetadata>;
+    metadata: Record<string, LabeledMetricMetadata>;
     type: ChartType;
+    invertSort?: boolean;
     className?: string;
     timeZone?: string;
-    options?: uPlot.Options;
-    unit?: string;
-    tooltipAppearance?: React.ComponentType<TooltipProps>;
+    options?: uPlot$1.Options;
+    tooltipComponent?: React.ComponentType<TooltipProps>;
 }
 /**
  * Renders a chart for time series data
@@ -539,4 +599,4 @@ declare function Empty(): react_jsx_runtime.JSX.Element;
 declare function Error(): react_jsx_runtime.JSX.Element;
 declare function Loading(): react_jsx_runtime.JSX.Element;
 
-export { type AggregationOperator, type Appearance, type AttributeWithValue, Chart, type ChartProps, type ChartType, type ChartVisualConfig, type Colors, Empty, Error, type Interval, Loading, type Log, type MetricMetadata, type MetricMetadataList, type MetricType, type PaginatedResponse, type Serie, type Severity, type TimeConfig, type TimeRange, TimeseriesChart, type TimeseriesChartProps, type TimeseriesQuery, type TimeseriesQueryConfig, type TooltipProps, type UnblindClientConfig, UnblindProvider, type UnblindProviderProps, UnblindScope, type UnblindScopeConfig, type UnblindScopeProps, type Usage, type UseLogsParams, type UseLogsReturn, type UseMetricsReturn, type UseScopeReturn, type UseTimeseriesParams, type UseTimeseriesReturn, type UseUsageParams, type UseUsageReturn, useLogs, useMetrics, useRefresh, useScope, useTheme, useTimeseries, useUsage };
+export { type AggregationOperator, type Appearance, Chart, type ChartProps, type ChartType, type ChartVisualConfig, type Colors, Empty, Error, type Interval, Loading, type Log, type MetricMetadata, type MetricMetadataList, type MetricType, type PaginatedResponse, Scope, type ScopeConfig, type ScopeProps, type Serie, type Severity, type TimeConfig, type TimeRange, Timeseries, type TimeseriesProps, type TimeseriesQuery, type TimeseriesQueryConfig, type TooltipProps, type UnblindClientConfig, UnblindProvider, type UnblindProviderProps, type Usage, type UseLogsParams, type UseLogsReturn, type UseMetricsReturn, type UseScopeReturn, type UseTimeseriesParams, type UseTimeseriesReturn, type UseUsageParams, type UseUsageReturn, useLogs, useMetrics, useRefresh, useScope, useTimeseries, useUsage };