@refraction-ui/react 0.5.0 → 0.6.0

package/dist/internal/logger/index.d.ts

@@ -0,0 +1,229 @@
+/** Severity levels, ordered low -> high. */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/** Numeric ordering used for level threshold comparisons. */
+declare const LEVEL_ORDER: Record<LogLevel, number>;
+/** Bound key/value pairs attached to every record emitted by a logger. */
+type LogContext = Record<string, unknown>;
+/** A single structured log record handed to a sink. */
+interface LogRecord {
+    level: LogLevel;
+    message: string;
+    timestamp: number;
+    app: string;
+    env: TelemetryEnv;
+    /** Merged bound context (child loggers) + per-call context, post-redaction. */
+    context: LogContext;
+}
+/** A span record handed to a sink when a span ends. */
+interface SpanRecord {
+    name: string;
+    startTime: number;
+    endTime: number;
+    durationMs: number;
+    app: string;
+    env: TelemetryEnv;
+    /** Merged bound context + span attributes, post-redaction. */
+    context: LogContext;
+    /** 'ok' unless ended with an error. */
+    status: 'ok' | 'error';
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+/**
+ * Vendor-neutral telemetry sink. Engines (console, Faro, custom) implement
+ * this — no vendor type ever leaks across this boundary.
+ */
+interface TelemetrySink {
+    /** Engine name, for diagnostics. */
+    name: string;
+    /** Receive a log record. May buffer; honor flush(). */
+    log(record: LogRecord): void;
+    /** Receive a finished span. May buffer; honor flush(). */
+    span(record: SpanRecord): void;
+    /** Force-deliver any buffered records. Resolves once delivery is attempted. */
+    flush(): Promise<void>;
+}
+/** Telemetry environment — selects a behavior preset. */
+type TelemetryEnv = 'development' | 'production';
+/** Config for {@link createTelemetry} — mirrors `createAI`'s config shape. */
+interface TelemetryConfig {
+    /** Logical app/service name attached to every record. */
+    app: string;
+    /** Environment preset selector. */
+    env: TelemetryEnv;
+    /**
+     * Remote collector endpoint. When omitted, telemetry stays console-only
+     * (no network engine is constructed).
+     */
+    endpoint?: string;
+    /**
+     * Master kill switch. When `false`, a tree-shakeable noop logger is
+     * returned and zero records are ever produced. Defaults to `true`.
+     */
+    enabled?: boolean;
+    /**
+     * Fraction of records kept, 0..1. Defaults to the preset value
+     * (1 in development, 0.25 in production). Records below the sample
+     * are dropped before reaching any sink.
+     */
+    sampleRate?: number;
+    /**
+     * Context keys to strip (deep) before a record is emitted. Use for
+     * PII / secrets, e.g. `['password', 'token', 'authorization']`.
+     */
+    redactKeys?: string[];
+}
+/** A logger bound to a context. Child loggers inherit + extend that context. */
+interface Logger {
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
+    fatal(message: string, context?: LogContext): void;
+    /**
+     * Derive a logger with additional bound context (e.g.
+     * `{ sessionId, interviewId, turnId }`). Merges over the parent's context.
+     */
+    child(context: LogContext): Logger;
+    /** Begin a span. Call {@link Span.end} to record its duration. */
+    startSpan(name: string, attributes?: LogContext): Span;
+    /** Force-deliver buffered records on every sink. */
+    flush(): Promise<void>;
+}
+/** An in-flight span returned by {@link Logger.startSpan}. */
+interface Span {
+    /** End the span and emit a {@link SpanRecord}. Optionally attach error/attrs. */
+    end(opts?: {
+        error?: unknown;
+        attributes?: LogContext;
+    }): void;
+}
+/** Return type of {@link createTelemetry}. */
+interface Telemetry extends Logger {
+    /** Registered sink names, in insertion order. */
+    readonly sinks: string[];
+    /** Register an additional sink (e.g. a custom collector). */
+    addSink(sink: TelemetrySink): void;
+    /** Remove a sink by name. */
+    removeSink(name: string): void;
+}
+
+/**
+ * Behavior derived from {@link TelemetryConfig.env}. The manager reads these
+ * fields to decide level filtering, batching, sampling, and flush triggers.
+ */
+interface TelemetryPreset {
+    /** Records strictly below this level are dropped. */
+    minLevel: LogLevel;
+    /** Buffer records and deliver in batches instead of synchronously. */
+    batch: boolean;
+    /** Batch size before an automatic flush (only when `batch`). */
+    batchSize: number;
+    /** Default sample rate when config omits `sampleRate`. */
+    sampleRate: number;
+    /** Pretty, single-line console output (vs. structured JSON). */
+    pretty: boolean;
+    /**
+     * Flush buffered records on `pagehide` + `visibilitychange` (hidden),
+     * using `navigator.sendBeacon` when available.
+     */
+    beaconFlush: boolean;
+}
+/**
+ * - development: sync, pretty, level=debug, no batching, sample everything.
+ * - production: batched + sampled, level>=warn, beacon flush on page exit.
+ */
+declare const PRESETS: Record<TelemetryEnv, TelemetryPreset>;
+/** Resolve the preset for an env (defensive copy so callers can't mutate it). */
+declare function resolvePreset(env: TelemetryEnv): TelemetryPreset;
+
+/**
+ * createTelemetry — creates a telemetry manager that fans records out to
+ * registered sinks. Manager/provider pattern, mirroring `createAI`.
+ *
+ * - `enabled: false` -> tree-shakeable noop (zero emissions, no engines).
+ * - no `endpoint` -> console-only transport.
+ * - `endpoint` set -> async Faro engine is registered when the optional
+ *   peers exist; console stays as a safe fallback until then.
+ *
+ * The returned object IS a logger (root context = `{}`); `child()` derives
+ * loggers with bound context (sessionId / interviewId / turnId / ...).
+ */
+declare function createTelemetry(config: TelemetryConfig): Telemetry;
+
+interface ConsoleSinkOptions {
+    /** Single-line pretty output (vs. structured JSON). */
+    pretty?: boolean;
+    /** Console to write to (injectable for tests). Defaults to global console. */
+    console?: Pick<Console, 'debug' | 'info' | 'warn' | 'error'>;
+}
+/**
+ * Default zero-dependency transport. Used whenever no `endpoint` is set.
+ * Synchronous; `flush()` is a resolved no-op (nothing is buffered).
+ */
+declare function createConsoleSink(opts?: ConsoleSinkOptions): TelemetrySink;
+
+/**
+ * Faro-backed engine. `@grafana/faro-web-sdk` + `@grafana/faro-web-tracing`
+ * are **optional peerDependencies** — they are loaded dynamically and never
+ * referenced in this module's public types. If the peers are absent the
+ * factory resolves to `null` so the caller can fall back to console.
+ *
+ * For tests, a `transport` may be injected: an object with a `push(payload)`
+ * method. This bypasses Faro entirely (no network, no peer required).
+ */
+/** Minimal structural shape of a Faro-ish transport. Not exported. */
+interface FaroTransport {
+    push(payload: {
+        kind: 'log' | 'span';
+        record: LogRecord | SpanRecord;
+    }): void;
+}
+interface FaroEngineOptions {
+    app: string;
+    endpoint: string;
+    /**
+     * Test/override transport. When provided, the Faro peers are NOT loaded
+     * and records are forwarded straight to `transport.push`.
+     */
+    transport?: FaroTransport;
+}
+/**
+ * Construct the Faro engine. Returns `null` when the optional peers are not
+ * installed and no override transport was supplied — callers treat `null` as
+ * "fall back to console".
+ */
+declare function createFaroSink(opts: FaroEngineOptions): Promise<TelemetrySink | null>;
+
+/**
+ * Returned by {@link createTelemetry} when `enabled: false`. Every method is
+ * an empty stub, so a bundler can dead-code-eliminate call sites and the
+ * engines (console/Faro) are never imported at runtime. Zero emissions.
+ */
+declare function createNoopTelemetry(): Telemetry;
+
+/**
+ * Deep-strip any object key whose name (case-insensitive) is in `keys`.
+ * Arrays are walked; cycles are guarded; non-matching values pass through
+ * unchanged. Returns a new structure — the input is never mutated.
+ */
+declare function redact(value: LogContext, keys: string[]): LogContext;
+
+interface MockSinkExtended extends TelemetrySink {
+    /** Every log record received, in order. */
+    logs: LogRecord[];
+    /** Every span record received, in order. */
+    spans: SpanRecord[];
+    /** Number of times {@link TelemetrySink.flush} was called. */
+    flushCalls: number;
+}
+/**
+ * createMockSink — a {@link TelemetrySink} that records everything for
+ * assertions instead of doing I/O. Used to test the manager and the Faro
+ * engine without any network. Mirrors `createMockAIProvider` in `packages/ai`.
+ */
+declare function createMockSink(name?: string): MockSinkExtended;
+
+export { type ConsoleSinkOptions, type FaroEngineOptions, LEVEL_ORDER, type LogContext, type LogLevel, type LogRecord, type Logger, type MockSinkExtended, PRESETS, type Span, type SpanRecord, type Telemetry, type TelemetryConfig, type TelemetryEnv, type TelemetryPreset, type TelemetrySink, createConsoleSink, createFaroSink, createMockSink, createNoopTelemetry, createTelemetry, redact, resolvePreset };

package/dist/internal/react-analytics/index.d.cts

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import { Analytics, AnalyticsContext, AnalyticsProperties, CallOptions } from '../analytics/index.cjs';
+export { Analytics, AnalyticsConfig, AnalyticsContext, AnalyticsEvent, AnalyticsEventType, AnalyticsProperties, AnalyticsSink, CallOptions, createAnalytics } from '../analytics/index.cjs';
+
+interface AnalyticsProviderProps {
+    children: React.ReactNode;
+    /**
+     * The `Analytics` instance to expose. Construct it once with
+     * `createAnalytics(...)` from `@refraction-ui/analytics`.
+     */
+    value: Analytics;
+}
+/**
+ * AnalyticsProvider — wraps your app with analytics context.
+ *
+ * ```tsx
+ * <AnalyticsProvider value={createAnalytics({ app: 'my-app', env: 'production' })}>
+ *   <App />
+ * </AnalyticsProvider>
+ * ```
+ */
+declare function AnalyticsProvider({ children, value }: AnalyticsProviderProps): React.FunctionComponentElement<React.ProviderProps<Analytics | null>>;
+interface UseAnalyticsOptions {
+    /** When set, returns a `with({ ...scope })` child bound to the context. */
+    scope?: Partial<AnalyticsContext>;
+}
+/**
+ * useAnalytics — access the `Analytics` instance from context.
+ *
+ * Pass `{ scope }` to receive a `with(...)` child whose context is merged
+ * into every event. Must be used within an `<AnalyticsProvider>`.
+ */
+declare function useAnalytics(options?: UseAnalyticsOptions): Analytics;
+/**
+ * useTrackEvent — a stable, bound `track` for the current context.
+ *
+ * ```tsx
+ * const track = useTrackEvent()
+ * track('Signup Clicked', { plan: 'pro' })
+ * ```
+ */
+declare function useTrackEvent(options?: UseAnalyticsOptions): (event: string, properties?: AnalyticsProperties, opts?: CallOptions) => void;
+
+export { AnalyticsProvider, type AnalyticsProviderProps, type UseAnalyticsOptions, useAnalytics, useTrackEvent };

package/dist/internal/react-analytics/index.d.ts

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import { Analytics, AnalyticsContext, AnalyticsProperties, CallOptions } from '../analytics/index.js';
+export { Analytics, AnalyticsConfig, AnalyticsContext, AnalyticsEvent, AnalyticsEventType, AnalyticsProperties, AnalyticsSink, CallOptions, createAnalytics } from '../analytics/index.js';
+
+interface AnalyticsProviderProps {
+    children: React.ReactNode;
+    /**
+     * The `Analytics` instance to expose. Construct it once with
+     * `createAnalytics(...)` from `@refraction-ui/analytics`.
+     */
+    value: Analytics;
+}
+/**
+ * AnalyticsProvider — wraps your app with analytics context.
+ *
+ * ```tsx
+ * <AnalyticsProvider value={createAnalytics({ app: 'my-app', env: 'production' })}>
+ *   <App />
+ * </AnalyticsProvider>
+ * ```
+ */
+declare function AnalyticsProvider({ children, value }: AnalyticsProviderProps): React.FunctionComponentElement<React.ProviderProps<Analytics | null>>;
+interface UseAnalyticsOptions {
+    /** When set, returns a `with({ ...scope })` child bound to the context. */
+    scope?: Partial<AnalyticsContext>;
+}
+/**
+ * useAnalytics — access the `Analytics` instance from context.
+ *
+ * Pass `{ scope }` to receive a `with(...)` child whose context is merged
+ * into every event. Must be used within an `<AnalyticsProvider>`.
+ */
+declare function useAnalytics(options?: UseAnalyticsOptions): Analytics;
+/**
+ * useTrackEvent — a stable, bound `track` for the current context.
+ *
+ * ```tsx
+ * const track = useTrackEvent()
+ * track('Signup Clicked', { plan: 'pro' })
+ * ```
+ */
+declare function useTrackEvent(options?: UseAnalyticsOptions): (event: string, properties?: AnalyticsProperties, opts?: CallOptions) => void;
+
+export { AnalyticsProvider, type AnalyticsProviderProps, type UseAnalyticsOptions, useAnalytics, useTrackEvent };

package/dist/internal/react-logger/index.d.cts

@@ -0,0 +1,107 @@
+import * as React from 'react';
+import { Telemetry, TelemetryConfig, LogContext, Logger, Span } from '../logger/index.cjs';
+export { LogContext, LogLevel, LogRecord, Logger, Span, SpanRecord, Telemetry, TelemetryConfig, TelemetryEnv, TelemetrySink } from '../logger/index.cjs';
+
+interface TelemetryContextValue {
+    /** The root telemetry instance (a logger bound to the empty root context). */
+    telemetry: Telemetry;
+}
+interface TelemetryProviderProps extends TelemetryConfig {
+    children: React.ReactNode;
+}
+/**
+ * TelemetryProvider — wraps your app with telemetry context.
+ *
+ * ```tsx
+ * <TelemetryProvider app="interview-service" env="production">
+ *   <App />
+ * </TelemetryProvider>
+ * ```
+ */
+declare function TelemetryProvider({ children, ...config }: TelemetryProviderProps): React.FunctionComponentElement<React.ProviderProps<TelemetryContextValue | null>>;
+/**
+ * useTelemetry — access the root telemetry instance.
+ * Must be used within <TelemetryProvider>.
+ */
+declare function useTelemetry(): Telemetry;
+/**
+ * useLogger — derive a scoped child logger with bound context (e.g.
+ * `{ sessionId, interviewId, turnId }`). The logger is memoized so it stays
+ * stable across renders for the same scope. With no scope, the root telemetry
+ * logger is returned.
+ *
+ * Must be used within <TelemetryProvider>.
+ */
+declare function useLogger(scope?: LogContext): Logger;
+
+interface UseSpanAPI {
+    /**
+     * Begin a span tied to the provider's telemetry instance. Returns the
+     * {@link Span}; call {@link Span.end} (or {@link UseSpanAPI.end}) to record
+     * its duration. Starting a new span while one is active ends the previous
+     * one first so a single hook owns at most one in-flight span.
+     */
+    start: (name: string, attributes?: LogContext) => Span;
+    /** End the active span (no-op if none is in flight). Idempotent per span. */
+    end: (opts?: {
+        error?: unknown;
+        attributes?: LogContext;
+    }) => void;
+    /** Whether a span started by this hook is currently in flight. */
+    isActive: boolean;
+}
+/**
+ * useSpan — start/end a telemetry span tied to the provider's telemetry
+ * instance. The active span is cleaned up automatically on unmount.
+ *
+ * ```tsx
+ * const span = useSpan()
+ * useEffect(() => {
+ *   span.start('llm-call', { model: 'gpt' })
+ *   return () => span.end()
+ * }, [])
+ * ```
+ *
+ * Must be used within <TelemetryProvider>.
+ */
+declare function useSpan(): UseSpanAPI;
+
+interface TelemetryErrorBoundaryProps {
+    children: React.ReactNode;
+    /**
+     * Fallback UI rendered after an error is caught. May be a node or a render
+     * function receiving the captured error and a reset callback.
+     */
+    fallback?: React.ReactNode | ((error: Error, reset: () => void) => React.ReactNode);
+    /** Extra bound context attached to the reported error record. */
+    context?: LogContext;
+    /** Invoked after the error has been reported to the telemetry sink. */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+}
+interface TelemetryErrorBoundaryState {
+    error: Error | null;
+}
+/**
+ * TelemetryErrorBoundary — a React error boundary that reports caught render
+ * errors to the provider's telemetry sink (at `error` level) before showing
+ * an optional fallback.
+ *
+ * ```tsx
+ * <TelemetryErrorBoundary fallback={<p>Something broke.</p>}>
+ *   <App />
+ * </TelemetryErrorBoundary>
+ * ```
+ *
+ * Must be used within <TelemetryProvider>.
+ */
+declare class TelemetryErrorBoundary extends React.Component<TelemetryErrorBoundaryProps, TelemetryErrorBoundaryState> {
+    static contextType: React.Context<TelemetryContextValue | null>;
+    context: TelemetryContextValue | null;
+    state: TelemetryErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): TelemetryErrorBoundaryState;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    reset: () => void;
+    render(): React.ReactNode;
+}
+
+export { type TelemetryContextValue, TelemetryErrorBoundary, type TelemetryErrorBoundaryProps, TelemetryProvider, type TelemetryProviderProps, type UseSpanAPI, useLogger, useSpan, useTelemetry };

package/dist/internal/react-logger/index.d.ts

@@ -0,0 +1,107 @@
+import * as React from 'react';
+import { Telemetry, TelemetryConfig, LogContext, Logger, Span } from '../logger/index.js';
+export { LogContext, LogLevel, LogRecord, Logger, Span, SpanRecord, Telemetry, TelemetryConfig, TelemetryEnv, TelemetrySink } from '../logger/index.js';
+
+interface TelemetryContextValue {
+    /** The root telemetry instance (a logger bound to the empty root context). */
+    telemetry: Telemetry;
+}
+interface TelemetryProviderProps extends TelemetryConfig {
+    children: React.ReactNode;
+}
+/**
+ * TelemetryProvider — wraps your app with telemetry context.
+ *
+ * ```tsx
+ * <TelemetryProvider app="interview-service" env="production">
+ *   <App />
+ * </TelemetryProvider>
+ * ```
+ */
+declare function TelemetryProvider({ children, ...config }: TelemetryProviderProps): React.FunctionComponentElement<React.ProviderProps<TelemetryContextValue | null>>;
+/**
+ * useTelemetry — access the root telemetry instance.
+ * Must be used within <TelemetryProvider>.
+ */
+declare function useTelemetry(): Telemetry;
+/**
+ * useLogger — derive a scoped child logger with bound context (e.g.
+ * `{ sessionId, interviewId, turnId }`). The logger is memoized so it stays
+ * stable across renders for the same scope. With no scope, the root telemetry
+ * logger is returned.
+ *
+ * Must be used within <TelemetryProvider>.
+ */
+declare function useLogger(scope?: LogContext): Logger;
+
+interface UseSpanAPI {
+    /**
+     * Begin a span tied to the provider's telemetry instance. Returns the
+     * {@link Span}; call {@link Span.end} (or {@link UseSpanAPI.end}) to record
+     * its duration. Starting a new span while one is active ends the previous
+     * one first so a single hook owns at most one in-flight span.
+     */
+    start: (name: string, attributes?: LogContext) => Span;
+    /** End the active span (no-op if none is in flight). Idempotent per span. */
+    end: (opts?: {
+        error?: unknown;
+        attributes?: LogContext;
+    }) => void;
+    /** Whether a span started by this hook is currently in flight. */
+    isActive: boolean;
+}
+/**
+ * useSpan — start/end a telemetry span tied to the provider's telemetry
+ * instance. The active span is cleaned up automatically on unmount.
+ *
+ * ```tsx
+ * const span = useSpan()
+ * useEffect(() => {
+ *   span.start('llm-call', { model: 'gpt' })
+ *   return () => span.end()
+ * }, [])
+ * ```
+ *
+ * Must be used within <TelemetryProvider>.
+ */
+declare function useSpan(): UseSpanAPI;
+
+interface TelemetryErrorBoundaryProps {
+    children: React.ReactNode;
+    /**
+     * Fallback UI rendered after an error is caught. May be a node or a render
+     * function receiving the captured error and a reset callback.
+     */
+    fallback?: React.ReactNode | ((error: Error, reset: () => void) => React.ReactNode);
+    /** Extra bound context attached to the reported error record. */
+    context?: LogContext;
+    /** Invoked after the error has been reported to the telemetry sink. */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+}
+interface TelemetryErrorBoundaryState {
+    error: Error | null;
+}
+/**
+ * TelemetryErrorBoundary — a React error boundary that reports caught render
+ * errors to the provider's telemetry sink (at `error` level) before showing
+ * an optional fallback.
+ *
+ * ```tsx
+ * <TelemetryErrorBoundary fallback={<p>Something broke.</p>}>
+ *   <App />
+ * </TelemetryErrorBoundary>
+ * ```
+ *
+ * Must be used within <TelemetryProvider>.
+ */
+declare class TelemetryErrorBoundary extends React.Component<TelemetryErrorBoundaryProps, TelemetryErrorBoundaryState> {
+    static contextType: React.Context<TelemetryContextValue | null>;
+    context: TelemetryContextValue | null;
+    state: TelemetryErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): TelemetryErrorBoundaryState;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    reset: () => void;
+    render(): React.ReactNode;
+}
+
+export { type TelemetryContextValue, TelemetryErrorBoundary, type TelemetryErrorBoundaryProps, TelemetryProvider, type TelemetryProviderProps, type UseSpanAPI, useLogger, useSpan, useTelemetry };