@pillar-ai/react 0.1.13 → 0.1.14

package/dist/HelpButton.d.ts

@@ -1,8 +1,21 @@
 /**
  * HelpButton Component
  * Pre-styled button to open the help panel
+ *
+ * Styling follows the dual-class pattern:
+ * - Internal class (_pillar-help-btn): Contains default styles
+ * - Public class (pillar-help-btn): Empty by default, for user overrides
+ *
+ * Supports CSS variable customization:
+ * - --pillar-btn-primary-bg
+ * - --pillar-btn-primary-color
+ * - --pillar-btn-secondary-bg
+ * - --pillar-btn-secondary-color
+ * - --pillar-btn-ghost-color
+ * - --pillar-btn-radius
+ * - --pillar-btn-font-family
  */
-import React, { type ReactNode, type ButtonHTMLAttributes } from 'react';
+import { type ButtonHTMLAttributes, type ReactNode } from 'react';
 export interface HelpButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
     /** Button content - defaults to "Help" */
     children?: ReactNode;
@@ -22,6 +35,10 @@ export interface HelpButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
 /**
  * Pre-styled help button that integrates with Pillar
  *
+ * Uses CSS classes for styling with CSS variable support:
+ * - Internal classes (_pillar-help-btn-*): Default styles
+ * - Public classes (pillar-help-btn-*): For user overrides
+ *
  * @example
  * ```tsx
  * // Basic usage
@@ -34,6 +51,12 @@ export interface HelpButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
  * <HelpButton action="search" searchQuery="getting started">
  *   Search Help
  * </HelpButton>
+ *
+ * // Customize via CSS variables
+ * // :root { --pillar-btn-primary-bg: #8b5cf6; }
+ *
+ * // Or via public class overrides
+ * // .pillar-help-btn--primary { background: #8b5cf6; }
  * ```
  */
-export declare function HelpButton({ children, action, searchQuery, articleSlug, onClick: customOnClick, variant, size, style, disabled, ...props }: HelpButtonProps): React.ReactElement;
+export declare function HelpButton({ children, action, searchQuery, articleSlug, onClick: customOnClick, variant, size, style, disabled, className, ...props }: HelpButtonProps): JSX.Element;

package/dist/hooks/usePillarRender.d.ts

@@ -0,0 +1,101 @@
+/**
+ * usePillarRender Hook
+ *
+ * Register a React component to render inline in the chat when the agent
+ * calls an `inline_ui` tool. The component receives data from the agent
+ * and can submit results back.
+ *
+ * @example
+ * ```tsx
+ * import { usePillarRender, type PillarRenderProps } from '@pillar-ai/react';
+ *
+ * function InviteCard({ data, submit, cancel }: PillarRenderProps<{ emails: string[] }>) {
+ *   const [emails, setEmails] = useState(data.emails || []);
+ *   return (
+ *     <div>
+ *       <input
+ *         value={emails.join(',')}
+ *         onChange={(e) => setEmails(e.target.value.split(','))}
+ *       />
+ *       <button onClick={() => submit({ invited: emails })}>Send</button>
+ *       <button onClick={cancel}>Cancel</button>
+ *     </div>
+ *   );
+ * }
+ *
+ * function TeamPage() {
+ *   usePillarRender({
+ *     name: 'invite_members',
+ *     description: 'Show invite UI when user wants to add team members',
+ *     inputSchema: {
+ *       type: 'object',
+ *       properties: { emails: { type: 'array', items: { type: 'string' } } },
+ *     },
+ *     render: InviteCard,
+ *   });
+ *
+ *   return <div>Team content...</div>;
+ * }
+ * ```
+ */
+import { type ComponentType } from 'react';
+/**
+ * Props passed to the render component.
+ *
+ * @template TData - Type of the data extracted by the agent
+ */
+export interface PillarRenderProps<TData extends Record<string, unknown> = Record<string, unknown>> {
+    /** Data extracted by the agent from the conversation */
+    data: TData;
+    /** Submit result back to the agent. Call this when the user confirms/completes the action. */
+    submit: (result: unknown) => void;
+    /** Cancel/dismiss the UI. Call this when the user cancels the action. */
+    cancel: () => void;
+    /** Report loading/success/error states for visual feedback */
+    setStatus: (status: 'loading' | 'success' | 'error', message?: string) => void;
+}
+/**
+ * Schema for registering a render component.
+ *
+ * @template TData - Type of the data extracted by the agent
+ */
+export interface PillarRenderSchema<TData extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Unique name for this render context (e.g., 'invite_members').
+     * This becomes the card_type that the agent references.
+     */
+    name: string;
+    /**
+     * Human-readable description for AI matching.
+     * Describes when the agent should use this UI.
+     */
+    description: string;
+    /**
+     * Example user queries that should trigger this render context.
+     * Used for semantic matching alongside the description.
+     */
+    examples?: string[];
+    /**
+     * JSON Schema for data extraction from user query.
+     * The agent will extract structured data from the conversation
+     * to populate the `data` prop passed to your component.
+     */
+    inputSchema?: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    /**
+     * React component to render inline in the chat panel.
+     * Receives PillarRenderProps with data from the agent and callbacks.
+     */
+    render: ComponentType<PillarRenderProps<TData>>;
+}
+/**
+ * Register a single render context.
+ */
+export declare function usePillarRender<TData extends Record<string, unknown> = Record<string, unknown>>(schema: PillarRenderSchema<TData>): void;
+/**
+ * Register multiple render contexts.
+ */
+export declare function usePillarRender(schemas: PillarRenderSchema[]): void;

package/dist/hooks/usePillarTasks.d.ts

@@ -0,0 +1,59 @@
+/**
+ * usePillarTasks Hook
+ * Declarative bulk registration of task handlers with automatic cleanup.
+ *
+ * Replaces the manual useEffect + unsubscribers[] pattern with a single
+ * hook call that accepts a map of task name → handler.
+ *
+ * Uses a ref internally so handlers are always up-to-date without
+ * re-registering on every render. Re-registration only happens when
+ * the Pillar instance changes.
+ *
+ * @example
+ * ```tsx
+ * import type { Actions } from '@/lib/pillar/actions';
+ *
+ * function MyTaskHandlers() {
+ *   const router = useRouter();
+ *
+ *   usePillarTasks<Actions>({
+ *     open_settings: (data) => router.push('/settings'),
+ *     open_knowledge: (data) => router.push('/knowledge'),
+ *     update_brand_name: async (data) => {
+ *       await api.updateBrandName(data.name);
+ *       return { success: true };
+ *     },
+ *   });
+ *
+ *   return null;
+ * }
+ * ```
+ */
+import type { SyncActionDefinitions, ActionDefinitions, ActionDataType, ActionNames } from '@pillar-ai/sdk';
+/**
+ * Type-safe map of action names to handler functions.
+ *
+ * Known action names (from TActions) get typed `data` parameters with
+ * autocomplete. Arbitrary string keys are also accepted for ad-hoc tasks
+ * (e.g. "escalate", "navigate") that aren't in the actions definition.
+ *
+ * Uses an intersection of a mapped type (for typed keys) with a loose
+ * index signature (for ad-hoc keys). The index signature uses
+ * `(...args: any[]) => any` to avoid contravariance conflicts with
+ * typed handlers.
+ */
+export type TaskHandlerMap<TActions extends SyncActionDefinitions | ActionDefinitions> = {
+    [K in ActionNames<TActions>]?: (data: ActionDataType<TActions, K>) => void | unknown | Promise<void | unknown>;
+} & {
+    [key: string]: ((...args: any[]) => any) | undefined;
+};
+/**
+ * Declaratively register multiple task handlers at once.
+ *
+ * Handlers are stored in a ref so they always reflect the latest
+ * closures without causing re-registration. The effect only re-runs
+ * when the Pillar SDK instance itself changes.
+ *
+ * @param tasks - Map of task name → handler function
+ */
+export declare function usePillarTasks<TActions extends SyncActionDefinitions | ActionDefinitions = SyncActionDefinitions>(tasks: TaskHandlerMap<TActions>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pillar-ai/react",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "React SDK for Pillar product copilot — AI assistant for SaaS and web apps",
   "type": "module",
   "main": "./dist/index.esm.js",
@@ -55,7 +55,7 @@
     "react-dom": ">=17.0.0 || >=19.0.0"
   },
   "dependencies": {
-    "@pillar-ai/sdk": "^0.1.22"
+    "@pillar-ai/sdk": "^0.1.25"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^25.0.7",