@kb-labs/studio-hooks 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,457 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { EventHandler } from '@kb-labs/studio-event-bus';
+import { MutateOptions } from '@tanstack/react-query';
+import { theme, ThemeConfig } from 'antd';
+import { colors, spacing, typography, radius, shadows } from '@kb-labs/studio-ui-core';
+
+/**
+ * Page context — provided to every plugin page by the host.
+ */
+interface PageContext {
+    /** Page ID from the manifest */
+    pageId: string;
+    /** Plugin that owns this page */
+    pluginId: string;
+    /** Additional config passed to this page instance */
+    config: Record<string, unknown>;
+    /** User permissions applicable to this page */
+    permissions: string[];
+}
+interface PageContextProviderProps {
+    children: ReactNode;
+    value: PageContext;
+}
+declare function PageContextProvider({ children, value }: PageContextProviderProps): react_jsx_runtime.JSX.Element;
+declare function usePageContext(): PageContext;
+
+/**
+ * Access the current page context.
+ *
+ * @example
+ * ```tsx
+ * const { pageId, pluginId, permissions } = usePage();
+ * ```
+ */
+declare function usePage(): PageContext;
+
+interface UseEventBusReturn {
+    /** Publish an event. pluginId/pageId auto-injected from context. */
+    publish: <T = unknown>(event: string, payload: T) => void;
+    /** Subscribe to an event. Auto-unsubscribes on unmount. Returns manual unsubscribe fn. */
+    subscribe: <T = unknown>(event: string, handler: EventHandler<T>) => () => void;
+}
+/**
+ * EventBus hook for cross-plugin communication.
+ *
+ * @example
+ * ```tsx
+ * const bus = useEventBus();
+ * bus.publish('commit:completed', { scope });
+ * bus.subscribe('quality:scanDone', (payload) => { ... });
+ * ```
+ */
+declare function useEventBus(): UseEventBusReturn;
+
+interface UseDataOptions<T> {
+    /** Polling interval in ms (0 = no polling) */
+    pollingMs?: number;
+    /** Enable/disable the query */
+    enabled?: boolean;
+    /** Stale time override in ms */
+    staleTime?: number;
+    /** Transform response before returning */
+    select?: (data: unknown) => T;
+    /** Additional query params appended to endpoint */
+    params?: Record<string, string | number | boolean>;
+}
+interface UseDataReturn<T> {
+    data: T | undefined;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: () => Promise<unknown>;
+    isFetching: boolean;
+}
+/**
+ * Data fetching hook wrapping TanStack Query.
+ * Fetches from the platform REST API (same origin).
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading } = useData<Commit[]>('/v1/plugins/commit/history');
+ * const { data: filtered } = useData('/v1/plugins/commit/files', { params: { scope } });
+ * ```
+ */
+declare function useData<T = unknown>(endpoint: string, options?: UseDataOptions<T>): UseDataReturn<T>;
+interface UseMutateDataReturn<TInput, TOutput> {
+    mutate: (input: TInput, options?: MutateOptions<TOutput, Error, TInput>) => void;
+    mutateAsync: (input: TInput) => Promise<TOutput>;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    data: TOutput | undefined;
+}
+/**
+ * Mutation hook for POST/PUT/PATCH/DELETE.
+ *
+ * @example
+ * ```tsx
+ * const { mutateAsync } = useMutateData<CommitInput, CommitResult>('/v1/plugins/commit/create');
+ * await mutateAsync({ scope, message });
+ * ```
+ */
+declare function useMutateData<TInput = unknown, TOutput = unknown>(endpoint: string, method?: 'POST' | 'PUT' | 'PATCH' | 'DELETE'): UseMutateDataReturn<TInput, TOutput>;
+
+interface UseSSEOptions<T> {
+    /** SSE event name(s) to listen on (default: 'message') */
+    events?: string | string[];
+    /** Event that signals the stream is done (auto-closes connection) */
+    doneEvent?: string;
+    /** Enable/disable the hook (default: true) */
+    enabled?: boolean;
+    /** Auto-reconnect on error (default: false) */
+    reconnect?: boolean;
+    /** Max reconnect attempts (default: 5) */
+    maxReconnects?: number;
+    /** Base reconnect delay in ms, doubles each attempt (default: 2000) */
+    reconnectIntervalMs?: number;
+    /** Max events to keep in buffer (0 = unlimited, default: 0) */
+    maxEvents?: number;
+    /** Parse event data (default: JSON.parse) */
+    parse?: (raw: string) => T;
+    /** Query params appended to endpoint */
+    params?: Record<string, string | number | boolean>;
+    /** Called on each incoming event */
+    onEvent?: (event: T) => void;
+    /** Called on connection open */
+    onOpen?: () => void;
+    /** Called on error (before reconnect) */
+    onError?: (error: Error) => void;
+    /** Called when done event received or connection closed cleanly */
+    onDone?: () => void;
+}
+interface UseSSEReturn<T> {
+    /** Accumulated events */
+    events: T[];
+    /** Latest event received */
+    latest: T | undefined;
+    /** Whether EventSource is connected */
+    isConnected: boolean;
+    /** Last error */
+    error: Error | null;
+    /** Manually close the connection */
+    close: () => void;
+    /** Clear the event buffer */
+    clear: () => void;
+    /** Current reconnect attempt count */
+    reconnectCount: number;
+}
+/**
+ * Generic SSE hook for server-sent event streams.
+ *
+ * Pass `null` as endpoint to keep the hook mounted but inactive.
+ *
+ * @example
+ * ```tsx
+ * // Workflow logs
+ * const { events, isConnected } = useSSE<LogEvent>(
+ *   runId ? `/workflows/runs/${runId}/logs` : null,
+ *   { events: 'workflow.log', doneEvent: 'workflow.done', params: { follow: '1' } },
+ * );
+ *
+ * // Observability log stream with reconnect
+ * const { events, latest } = useSSE<LogRecord>('/logs/stream', {
+ *   params: { level: 'error' },
+ *   maxEvents: 500,
+ *   reconnect: true,
+ * });
+ * ```
+ */
+declare function useSSE<T = unknown>(endpoint: string | null, options?: UseSSEOptions<T>): UseSSEReturn<T>;
+
+interface UseInfiniteDataOptions<T, TCursor = string> {
+    /** Extract the next-page cursor from the last fetched page. Return undefined to signal "no more pages". */
+    getNextCursor: (lastPage: T) => TCursor | undefined;
+    /** Additional query params (merged with cursor on each request) */
+    params?: Record<string, string | number | boolean>;
+    /** Enable/disable the query (default: true) */
+    enabled?: boolean;
+    /** Stale time override in ms */
+    staleTime?: number;
+    /** Query param name used to pass the cursor (default: 'cursor') */
+    cursorParam?: string;
+    /** Initial cursor value (default: undefined → first page) */
+    initialCursor?: TCursor;
+}
+interface UseInfiniteDataReturn<T> {
+    /** All fetched pages */
+    pages: T[];
+    /** Flattened data from all pages (requires pages to be arrays) */
+    data: T extends Array<infer U> ? U[] : T[];
+    /** Loading first page */
+    isLoading: boolean;
+    /** Fetching any page (initial or next) */
+    isFetching: boolean;
+    /** Currently fetching next page */
+    isFetchingNextPage: boolean;
+    /** Whether more pages are available */
+    hasNextPage: boolean;
+    /** Fetch the next page */
+    fetchNextPage: () => Promise<unknown>;
+    /** Error if any */
+    error: Error | null;
+    isError: boolean;
+    /** Refetch all pages */
+    refetch: () => Promise<unknown>;
+}
+/**
+ * Infinite/cursor-based pagination hook wrapping TanStack useInfiniteQuery.
+ *
+ * Works with any cursor-based or offset-based REST endpoint.
+ *
+ * @example
+ * ```tsx
+ * // Cursor-based pagination
+ * const { data, fetchNextPage, hasNextPage } = useInfiniteData<RunsPage>(
+ *   '/workflows/runs',
+ *   {
+ *     getNextCursor: (page) => page.nextCursor,
+ *     params: { status: 'running' },
+ *   },
+ * );
+ *
+ * // Offset-based pagination
+ * const { data, fetchNextPage } = useInfiniteData<LogEntry[]>(
+ *   '/logs',
+ *   {
+ *     cursorParam: 'offset',
+ *     getNextCursor: (page) => page.length === 50 ? String(allLogs.length) : undefined,
+ *   },
+ * );
+ * ```
+ */
+declare function useInfiniteData<T = unknown, TCursor = string>(endpoint: string, options: UseInfiniteDataOptions<T, TCursor>): UseInfiniteDataReturn<T>;
+
+type WebSocketStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
+interface UseWebSocketOptions<TReceive> {
+    /** Enable/disable auto-connect on mount (default: true) */
+    enabled?: boolean;
+    /** Auto-reconnect on close/error (default: false) */
+    reconnect?: boolean;
+    /** Max reconnect attempts (default: 5) */
+    maxReconnects?: number;
+    /** Base reconnect delay in ms, doubles each attempt (default: 2000) */
+    reconnectIntervalMs?: number;
+    /** WebSocket sub-protocols */
+    protocols?: string | string[];
+    /** Parse incoming messages (default: JSON.parse) */
+    parse?: (raw: string) => TReceive;
+    /** Serialize outgoing messages (default: JSON.stringify) */
+    serialize?: (data: unknown) => string;
+    /** Max messages to keep in history (default: 100) */
+    maxMessages?: number;
+    /** Called on each received message */
+    onMessage?: (data: TReceive) => void;
+    /** Called on connection open */
+    onOpen?: (event: Event) => void;
+    /** Called on connection close */
+    onClose?: (event: CloseEvent) => void;
+    /** Called on error */
+    onError?: (event: Event) => void;
+}
+interface UseWebSocketReturn<TSend, TReceive> {
+    /** Send a typed message (auto-serialized) */
+    send: (data: TSend) => void;
+    /** Send a raw string */
+    sendRaw: (data: string | ArrayBufferLike | Blob) => void;
+    /** Received messages (most recent last) */
+    messages: TReceive[];
+    /** Latest received message */
+    latest: TReceive | undefined;
+    /** Connection status */
+    status: WebSocketStatus;
+    /** Shorthand: status === 'connected' */
+    isConnected: boolean;
+    /** Last error event */
+    error: Event | null;
+    /** Manually open the connection */
+    connect: () => void;
+    /** Manually close the connection */
+    disconnect: (code?: number, reason?: string) => void;
+    /** Clear message history */
+    clear: () => void;
+    /** Current reconnect attempt count */
+    reconnectCount: number;
+}
+/**
+ * Generic WebSocket hook for bidirectional communication.
+ *
+ * Pass `null` as url to keep the hook mounted but inactive.
+ *
+ * @example
+ * ```tsx
+ * // Agent chat
+ * const { send, messages, isConnected } = useWebSocket<UserMsg, AgentMsg>(
+ *   sessionId ? `ws://localhost:4000/agent/${sessionId}` : null,
+ * );
+ * send({ type: 'user_message', text: input });
+ *
+ * // With reconnect and callbacks
+ * const { messages, status } = useWebSocket<Command, StatusEvent>(
+ *   '/ws/deploy',
+ *   {
+ *     reconnect: true,
+ *     onMessage: (msg) => msg.done && showNotification('Deploy finished'),
+ *   },
+ * );
+ * ```
+ */
+declare function useWebSocket<TSend = unknown, TReceive = unknown>(url: string | null, options?: UseWebSocketOptions<TReceive>): UseWebSocketReturn<TSend, TReceive>;
+
+interface UsePermissionsReturn {
+    /** Check if the current user has a specific permission */
+    hasPermission: (permission: string) => boolean;
+    /** All permissions available to this page */
+    permissions: string[];
+}
+/**
+ * Atomic permission checks inside a page.
+ * Page-level permissions are enforced by the host before loading.
+ * This hook is for fine-grained control within the page.
+ *
+ * @example
+ * ```tsx
+ * const { hasPermission } = usePermissions();
+ * if (!hasPermission('commit:write')) return <ReadOnlyView />;
+ * ```
+ */
+declare function usePermissions(): UsePermissionsReturn;
+
+interface UseNavigationReturn {
+    /** Navigate to a route */
+    navigate: (path: string) => void;
+    /** Current pathname */
+    currentPath: string;
+    /** Go back in history */
+    goBack: () => void;
+    /** Open external URL in new tab */
+    openExternal: (url: string) => void;
+}
+/**
+ * Navigation hook for plugin pages.
+ *
+ * @example
+ * ```tsx
+ * const { navigate, currentPath } = useNavigation();
+ * navigate('/commit/history');
+ * ```
+ */
+declare function useNavigation(): UseNavigationReturn;
+
+type NotificationType = 'success' | 'error' | 'warning' | 'info';
+interface UseNotificationReturn {
+    notify: (options: {
+        type: NotificationType;
+        message: string;
+        description?: string;
+        duration?: number;
+    }) => void;
+    success: (message: string, description?: string) => void;
+    error: (message: string, description?: string) => void;
+    warning: (message: string, description?: string) => void;
+    info: (message: string, description?: string) => void;
+}
+/**
+ * Notification hook for plugin pages.
+ *
+ * @example
+ * ```tsx
+ * const notify = useNotification();
+ * notify.success('Commit created');
+ * notify.error('Build failed', 'Check logs for details');
+ * ```
+ */
+declare function useNotification(): UseNotificationReturn;
+
+/**
+ * Semantic tokens — theme-aware colors for backgrounds, text, borders, status.
+ * These mirror the CSS variables injected by Studio host (e.g. `var(--bg-primary)`).
+ */
+interface SemanticTokens {
+    bgPrimary: string;
+    bgSecondary: string;
+    bgTertiary: string;
+    textPrimary: string;
+    textSecondary: string;
+    textTertiary: string;
+    textInverse: string;
+    borderPrimary: string;
+    borderSecondary: string;
+    link: string;
+    linkHover: string;
+    accentSubtle: string;
+    success: string;
+    warning: string;
+    error: string;
+    info: string;
+    disabled: string;
+    shadow: string;
+}
+interface UseThemeReturn {
+    /** Current theme mode */
+    mode: 'light' | 'dark';
+    /** Ant Design design token */
+    antdToken: ReturnType<typeof theme.useToken>['token'];
+    /** KB Labs semantic tokens (theme-aware) */
+    semantic: SemanticTokens;
+    /** Raw design tokens (colors, spacing, typography, radius, shadows) */
+    tokens: {
+        colors: typeof colors;
+        spacing: typeof spacing;
+        typography: typeof typography;
+        radius: typeof radius;
+        shadows: typeof shadows;
+    };
+}
+/**
+ * Theme hook for plugin pages.
+ *
+ * Three levels of access:
+ * - `semantic` — high-level themed tokens (bgPrimary, textPrimary, success, error...)
+ * - `antdToken` — Ant Design's full design token for antd component customization
+ * - `tokens` — raw design tokens (colors, spacing, typography, radius, shadows)
+ *
+ * CSS variables (`var(--bg-primary)`, `var(--text-primary)`) are also available
+ * in stylesheets — injected by the Studio host into `:root`.
+ *
+ * @example
+ * ```tsx
+ * const { semantic, tokens, mode } = useTheme();
+ *
+ * // Semantic tokens (recommended)
+ * <div style={{ color: semantic.textPrimary, background: semantic.bgSecondary }}>
+ *
+ * // CSS variables in stylesheets
+ * // .my-component { color: var(--text-primary); }
+ *
+ * // Raw tokens for specific shades
+ * <div style={{ color: tokens.colors.primary[600] }}>
+ * ```
+ */
+declare function useTheme(): UseThemeReturn;
+
+/**
+ * Maps CSS variables from ui-core to Ant Design tokens
+ * Uses CSS variables directly via var() for automatic theme switching
+ * This adapter maintains framework-agnostic nature of ui-core
+ * All Ant Design tokens are mapped to our CSS variables for consistency
+ */
+declare function getAntDesignTokens(): ThemeConfig['token'];
+/**
+ * Gets component-specific theme configurations
+ * Uses Ant Design's components API for proper theming without CSS overrides
+ */
+declare function getAntDesignComponents(): ThemeConfig['components'];
+
+export { type NotificationType, type PageContext, PageContextProvider, type SemanticTokens, type UseDataOptions, type UseDataReturn, type UseEventBusReturn, type UseInfiniteDataOptions, type UseInfiniteDataReturn, type UseMutateDataReturn, type UseNavigationReturn, type UseNotificationReturn, type UsePermissionsReturn, type UseSSEOptions, type UseSSEReturn, type UseThemeReturn, type UseWebSocketOptions, type UseWebSocketReturn, type WebSocketStatus, getAntDesignComponents, getAntDesignTokens, useData, useEventBus, useInfiniteData, useMutateData, useNavigation, useNotification, usePage, usePageContext, usePermissions, useSSE, useTheme, useWebSocket };