@unblind/react 0.1.0-alpha.2 → 0.1.0-alpha.20

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 = {
     /**
@@ -18,7 +18,7 @@ type UnblindClientConfig = {
     fetchImpl?: typeof fetch;
 };
 type UnblindClientProviderProps = {
-    children: ReactNode;
+    children?: ReactNode;
     /**
      * Optional QueryClient instance. If not provided, a new one will be created.
      * Useful if you already have a QueryClientProvider in your app and want to reuse it.
@@ -38,31 +38,6 @@ type UnblindClientProviderProps = {
      */
     fetchImpl?: typeof fetch;
 };
-/**
- * UnblindClientProvider sets up the QueryClientProvider (for React Query)
- * and the Unblind client configuration context.
- *
- * @example
- * ```tsx
- * import { UnblindClientProvider } from '@unblind/react';
- *
- * function App() {
- *   return (
- *     <UnblindClientProvider apiBaseUrl="/api/unblind">
- *       <YourComponents />
- *     </UnblindClientProvider>
- *   );
- * }
- * ```
- */
-declare function UnblindClientProvider({ children, queryClient: providedQueryClient, queryClientConfig: providedQueryClientConfig, apiBaseUrl, fetchImpl, }: UnblindClientProviderProps): react_jsx_runtime.JSX.Element;
-/**
- * Access the Unblind client configuration.
- *
- * @throws Error if called outside of an UnblindClientProvider.
- * This ensures that QueryClientProvider is always available for hooks.
- */
-declare function useUnblindClientConfig(): UnblindClientConfig;
 /**
  * Hook to refresh all timeseries data.
  * Invalidates all queries with the 'unblind' and 'timeseries' keys,
@@ -75,7 +50,7 @@ declare function useUnblindClientConfig(): UnblindClientConfig;
  *   return (
  *     <>
  *       <button onClick={() => refresh()}>Refresh</button>
- *       <TimeseriesChart metrics={["cpu"]} />
+ *       <Timeseries metrics={["cpu"]} />
  *     </>
  *   );
  * }
@@ -83,17 +58,13 @@ declare function useUnblindClientConfig(): UnblindClientConfig;
  */
 declare function useRefresh(): () => Promise<void>;
 
-interface TooltipItem {
-    metric: string | HTMLElement | undefined;
-    color: string;
-    value?: number;
-    formattedValue?: string;
-    attributes?: Record<string, any>;
-}
 interface TooltipProps {
     timestamp: number;
-    items: TooltipItem[];
+    tooltipSerieList: TooltipSerie[];
     timeZone?: string;
+    stacked?: boolean;
+    invertSort?: boolean;
+    visibilityLimit?: number;
 }
 
 /**
@@ -105,13 +76,6 @@ 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.
  */
@@ -137,7 +101,7 @@ type MetricMetadataList = Array<MetricMetadata>;
  */
 interface Serie {
     metric: string;
-    attributes: Array<AttributeWithValue>;
+    attributes?: Record<string, string>;
     values: Array<number>;
     queryName?: string;
     queryIndex: number;
@@ -156,7 +120,7 @@ interface TimeseriesQuery {
 /**
  * Chart types available
  */
-type ChartType = "bar" | "line" | "area" | "step";
+type ChartType = "bar" | "line" | "area" | "step" | "spline";
 /**
  * Time Range definition:
  *
@@ -165,28 +129,32 @@ type ChartType = "bar" | "line" | "area" | "step";
 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
  * https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitytext
  */
 type Severity = "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL";
-type Colors = Array<string> | ((serie: Serie, index: number) => string);
+type Colors = Array<string> | {
+    fill: Array<string>;
+    border: Array<string>;
+} | ((serie: Serie, index: number, type: ChartType, isFilling?: boolean) => string);
 /**
- * Interval expressed in milliseconds.
+ * Interval expressed in seconds.
  */
 type Interval = number;
 type TimeConfig = {
@@ -196,12 +164,12 @@ type TimeConfig = {
      */
     timeRange?: TimeRange;
     /**
-     * Optional start time (Unix timestamp in milliseconds).
+     * Optional start time (Unix timestamp in seconds).
      * If provided along with endTime, takes priority over timeRange.
      */
     startTime?: number;
     /**
-     * Optional end time (Unix timestamp in milliseconds).
+     * Optional end time (Unix timestamp in seconds).
      * If provided along with startTime, takes priority over timeRange.
      */
     endTime?: number;
@@ -212,7 +180,7 @@ type TimeConfig = {
  */
 type TimeseriesQueryConfig = TimeConfig & {
     /**
-     * Optional interval in milliseconds. If not provided, will use interval from the provider.
+     * Optional interval in seconds. If not provided, will use interval from the provider.
      */
     interval?: Interval;
     /**
@@ -237,10 +205,66 @@ interface ChartVisualConfig {
      */
     colors?: Colors;
     /**
-     * Optional order for rendering results.
+     * Optional to fill charts.
+     *
+     * Bar and area charts are filled by default.
+     */
+    fill?: boolean;
+    /**
+     * 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
      */
-    orderByValues?: boolean;
+    invertSort?: boolean;
+}
+interface TooltipConfig {
+    hide?: boolean;
+    visibilityLimit?: number;
 }
 /**
  * Appearance configuration for Unblind components.
@@ -248,7 +272,7 @@ interface ChartVisualConfig {
  * 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
@@ -261,15 +285,33 @@ type Appearance = {
         Empty?: React.ComponentType;
         Tooltip?: React.ComponentType<TooltipProps>;
     };
-} & ChartVisualConfig;
-type TimeseriesProps = TimeseriesQueryConfig & {
-    /**
-     * Array of metric names to display in the chart.
-     */
-    metrics: Array<string>;
 };
+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: MetricMetadata;
+    serie: uPlot.Series;
+    color: string;
+    value?: number;
+    formattedValue?: string;
+    attributes?: Record<string, string>;
+}
 
-type UnblindScopeConfig = TimeseriesQueryConfig & {
+type ScopeConfig = TimeseriesQueryConfig & ChartVisualConfig & {
     /**
      * Optional appearance configuration for all components
      * within this scope.
@@ -282,7 +324,7 @@ type UnblindScopeConfig = TimeseriesQueryConfig & {
      *
      * @example
      * ```tsx
-     * <UnblindScope
+     * <Scope
      *   appearance={{
      *     components: {
      *       Loading: CustomLoading,
@@ -291,16 +333,16 @@ type UnblindScopeConfig = TimeseriesQueryConfig & {
      *   }}
      * >
      *   <App />
-     * </UnblindScope>
+     * </Scope>
      * ```
      */
     appearance?: Appearance;
 };
-type UnblindScopeProps = UnblindScopeConfig & {
-    children: React$1.ReactNode;
+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.
@@ -309,26 +351,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, }: ScopeProps): react_jsx_runtime.JSX.Element;
+type UseScopeReturn = TimeseriesQueryConfig & ChartVisualConfig & {
     timeRange: TimeRange;
     appearance: {
         components: {
@@ -337,12 +379,10 @@ type UseScopeReturn = TimeseriesQueryConfig & {
             Empty: React$1.ComponentType;
             Tooltip?: React$1.ComponentType<TooltipProps>;
         };
-        colors: Colors;
-        orderByValues?: boolean;
     };
 };
 /**
- * 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.
  *
@@ -356,13 +396,13 @@ type UseScopeReturn = TimeseriesQueryConfig & {
  */
 declare function useScope(): UseScopeReturn;
 
-type UnblindProviderProps = UnblindClientProviderProps & UnblindScopeProps & {
-    children: React.ReactNode;
+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
@@ -377,7 +417,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, }: UnblindProviderProps): react_jsx_runtime.JSX.Element;
 
 interface UseMetricsReturn {
     metrics: MetricMetadataList | undefined;
@@ -398,12 +438,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;
@@ -415,10 +456,13 @@ 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 {
-    date: string;
+    period: {
+        startTime: number;
+        endTime: number;
+    };
     metrics: {
         units: number;
     };
@@ -440,13 +484,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>;
@@ -463,15 +512,24 @@ 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 useLogs(props: UseLogsParams): UseLogsReturn;
 
-declare function useTheme(): boolean;
-
-type TimeseriesChartProps = TimeseriesProps & {
+type TimeseriesProps = Exclude<TimeseriesQueryConfig, "startTime" | "endTime" | "timeRange"> & ChartVisualConfig & {
     /**
-     * Chart type. Defaults to "line".
+     * Metric name(s) to display in the chart.
+     *
+     * @example  Single metric
+     * ```jsx
+     * <Timeseries metrics="nodejs.eventloop.p50" />
+     * ```
+     *
+     * @example
+     * Multiple metrics
+     * ```jsx
+     * <Timeseries metrics={["nodejs.eventloop.p50", "..."]} />
+     * ```
      */
-    type?: ChartType;
+    metrics: Array<string> | string;
     /**
      * Optional className for the chart container.
      */
@@ -480,45 +538,53 @@ type TimeseriesChartProps = TimeseriesProps & {
      * 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, timeRange: propTimeRange, startTime: propStartTime, endTime: propEndTime, interval: propInterval, type, className, appearance: propAppearance, }: TimeseriesChartProps): react_jsx_runtime.JSX.Element;
+declare function Timeseries({ metrics, operator: propOperator, attributes: propAttributes, groupBy: propGroupBy, interval: propInterval, type, className, appearance: propAppearance, unit: propUnit, thresholds: propThresholds, min: propMin, max: propMax, colors: propColors, tooltip: propTooltip, fill: propFill, hideAxis: propHideAxis, hideCursor: propHideCursor, relativeTimeAxis: propRelativeTimeAxis, onResponse, invertSort: propInvertSort, }: TimeseriesProps): react_jsx_runtime.JSX.Element;
 
 interface ChartProps extends ChartVisualConfig {
     times: Array<number>;
     series: Serie[];
     metadata: Record<string, MetricMetadata>;
-    type: "bar" | "line" | "area" | "step";
+    type: ChartType;
+    invertSort?: boolean;
     className?: string;
     timeZone?: string;
-    options?: uPlot.Options;
-    tooltipAppearance?: React.ComponentType<TooltipProps>;
+    options?: uPlot$1.Options;
+    tooltipComponent?: React.ComponentType<TooltipProps>;
 }
 /**
  * Renders a chart for time series data
  */
 declare function Chart(props: ChartProps): react_jsx_runtime.JSX.Element;
 
-declare function Divider({ className, ...props }: React$1.ComponentPropsWithoutRef<"hr">): react_jsx_runtime.JSX.Element;
+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, Divider, type Interval, type Log, type MetricMetadata, type MetricMetadataList, type MetricType, type PaginatedResponse, type Serie, type Severity, type TimeConfig, type TimeRange, TimeseriesChart, type TimeseriesChartProps, type TimeseriesProps, type TimeseriesQuery, type TimeseriesQueryConfig, type TooltipProps, type UnblindClientConfig, UnblindClientProvider, type UnblindClientProviderProps, 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, useUnblindClientConfig, 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 };