@pillar-ai/react 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# @pillar-ai/react
+
+React bindings for the Pillar Embedded Help SDK.
+
+## Installation
+
+```bash
+npm install @pillar-ai/react
+```
+
+## Quick Start
+
+Wrap your app with `PillarProvider`:
+
+```tsx
+import { PillarProvider } from '@pillar-ai/react';
+
+function App() {
+  return (
+    <PillarProvider helpCenter="your-help-center" publicKey="pk_live_xxx">
+      <MyApp />
+    </PillarProvider>
+  );
+}
+```
+
+## Components
+
+### PillarProvider
+
+The root provider that initializes the SDK and provides context to child components.
+
+```tsx
+<PillarProvider
+  helpCenter="your-help-center"
+  publicKey="pk_live_xxx"
+  config={{
+    panel: { position: 'right' },
+    floatingButton: { enabled: true },
+    theme: { mode: 'system' },
+  }}
+>
+  {children}
+</PillarProvider>
+```
+
+### Tooltip
+
+Attach contextual tooltips to any element:
+
+```tsx
+import { Tooltip } from '@pillar-ai/react';
+
+<Tooltip tooltipId="welcome-tooltip">
+  <button>Hover me for help</button>
+</Tooltip>;
+```
+
+### PillarPanel
+
+For custom panel placement (when using `container: 'manual'`):
+
+```tsx
+import { PillarProvider, PillarPanel } from '@pillar-ai/react';
+
+function App() {
+  return (
+    <PillarProvider
+      helpCenter="your-help-center"
+      publicKey="pk_live_xxx"
+      config={{ panel: { container: 'manual' } }}
+    >
+      <div className="layout">
+        <main>Your content</main>
+        <PillarPanel className="sidebar-panel" />
+      </div>
+    </PillarProvider>
+  );
+}
+```
+
+## Hooks
+
+### usePillar
+
+Access the SDK instance and state:
+
+```tsx
+import { usePillar } from '@pillar-ai/react';
+
+function MyComponent() {
+  const { isReady, isOpen, pillar } = usePillar();
+
+  if (!isReady) return <div>Loading...</div>;
+
+  return <div>Panel is {isOpen ? 'open' : 'closed'}</div>;
+}
+```
+
+### useHelpPanel
+
+Control the help panel:
+
+```tsx
+import { useHelpPanel } from '@pillar-ai/react';
+
+function HelpButton() {
+  const { open, close, toggle, isOpen } = useHelpPanel();
+
+  return (
+    <button onClick={toggle}>{isOpen ? 'Close Help' : 'Get Help'}</button>
+  );
+}
+```
+
+## Type-Safe Actions
+
+Define custom actions with full TypeScript support:
+
+```tsx
+import { PillarProvider, usePillar } from '@pillar-ai/react';
+import type { ActionDefinitions } from '@pillar-ai/react';
+
+// Define your actions
+const actions = {
+  openSettings: {
+    type: 'navigate' as const,
+    label: 'Open Settings',
+    description: 'Navigate to settings page',
+  },
+  showNotification: {
+    type: 'trigger' as const,
+    label: 'Show Notification',
+    description: 'Display a notification',
+    dataSchema: {
+      message: { type: 'string' as const, required: true },
+    },
+  },
+} satisfies ActionDefinitions;
+
+function App() {
+  return (
+    <PillarProvider
+      helpCenter="your-help-center"
+      publicKey="pk_live_xxx"
+      actions={actions}
+      onTask={(type, data) => {
+        // TypeScript knows the exact shape of data based on type
+        if (type === 'showNotification') {
+          console.log(data.message); // Typed!
+        }
+      }}
+    >
+      <MyApp />
+    </PillarProvider>
+  );
+}
+```
+
+## License
+
+MIT

package/dist/HelpButton.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { type ButtonHTMLAttributes, type ReactNode } from 'react';
+export interface HelpButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
+    /** Button content - defaults to "Help" */
+    children?: ReactNode;
+    /** What to open when clicked */
+    action?: 'toggle' | 'open' | 'chat' | 'search';
+    /** Initial search query (when action is 'search') */
+    searchQuery?: string;
+    /** Article slug to open (when action is 'open') */
+    articleSlug?: string;
+    /** Custom click handler (overrides action) */
+    onClick?: () => void;
+    /** Visual variant */
+    variant?: 'primary' | 'secondary' | 'ghost';
+    /** Button size */
+    size?: 'sm' | 'md' | 'lg';
+}
+/**
+ * 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
+ * <HelpButton>Get Help</HelpButton>
+ *
+ * // Open chat directly
+ * <HelpButton action="chat">Ask AI</HelpButton>
+ *
+ * // Search with query
+ * <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, className, ...props }: HelpButtonProps): JSX.Element;

package/dist/PillarPanel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * PillarPanel Component
+ * Renders the Pillar help panel at a custom location in the DOM
+ */
+import React, { type CSSProperties, type HTMLAttributes } from 'react';
+export interface PillarPanelProps extends HTMLAttributes<HTMLDivElement> {
+    /** Custom class name for the container */
+    className?: string;
+    /** Custom inline styles for the container */
+    style?: CSSProperties;
+}
+/**
+ * Renders the Pillar help panel at a custom location in the DOM.
+ * Use this when you want to control where the panel is rendered instead of
+ * having it automatically appended to document.body.
+ *
+ * **Important**: When using this component, set `panel.container: 'manual'` in your
+ * PillarProvider config to prevent automatic mounting.
+ *
+ * @example
+ * ```tsx
+ * <PillarProvider
+ *   helpCenter="my-help"
+ *   publicKey="pk_xxx"
+ *   config={{ panel: { container: 'manual' } }}
+ * >
+ *   <div className="my-layout">
+ *     <Sidebar />
+ *     <PillarPanel className="help-panel-container" />
+ *     <MainContent />
+ *   </div>
+ * </PillarProvider>
+ * ```
+ */
+export declare function PillarPanel({ className, style, ...props }: PillarPanelProps): React.ReactElement;

package/dist/PillarProvider.d.ts

@@ -0,0 +1,118 @@
+/**
+ * PillarProvider
+ * Context provider that initializes and manages the Pillar SDK
+ */
+import { Pillar, type PillarConfig, type PillarEvents, type PillarState, type TaskExecutePayload, type ThemeConfig } from '@pillar-ai/sdk';
+import React, { type ReactNode, type ComponentType } from 'react';
+/**
+ * Props passed to custom card components.
+ */
+export interface CardComponentProps<T = Record<string, unknown>> {
+    /** Data extracted by the AI for this action */
+    data: T;
+    /** Called when user confirms the action */
+    onConfirm: (modifiedData?: Record<string, unknown>) => void;
+    /** Called when user cancels the action */
+    onCancel: () => void;
+    /** Called to report state changes (loading, success, error) */
+    onStateChange?: (state: 'loading' | 'success' | 'error', message?: string) => void;
+}
+/**
+ * A React component that can be used as a custom card renderer.
+ */
+export type CardComponent<T = Record<string, unknown>> = ComponentType<CardComponentProps<T>>;
+export interface PillarContextValue {
+    /** The Pillar SDK instance */
+    pillar: Pillar | null;
+    /** Current SDK state */
+    state: PillarState;
+    /** Whether the SDK is ready */
+    isReady: boolean;
+    /** Whether the panel is currently open */
+    isPanelOpen: boolean;
+    /** Open the help panel */
+    open: (options?: {
+        view?: string;
+        article?: string;
+        search?: string;
+        focusInput?: boolean;
+    }) => void;
+    /** Close the help panel */
+    close: () => void;
+    /** Toggle the help panel */
+    toggle: () => void;
+    /** Open a specific article */
+    openArticle: (slug: string) => void;
+    /** Open a specific category */
+    openCategory: (slug: string) => Promise<void>;
+    /** Perform a search */
+    search: (query: string) => void;
+    /** Navigate to a specific view */
+    navigate: (view: string, params?: Record<string, string>) => void;
+    /** Update the panel theme at runtime */
+    setTheme: (theme: Partial<ThemeConfig>) => void;
+    /** Enable or disable the text selection "Ask AI" popover */
+    setTextSelectionEnabled: (enabled: boolean) => void;
+    /** Subscribe to SDK events */
+    on: <K extends keyof PillarEvents>(event: K, callback: (data: PillarEvents[K]) => void) => () => void;
+}
+export interface PillarProviderProps {
+    /** Help center subdomain or identifier */
+    helpCenter: string;
+    /** Public API key */
+    publicKey: string;
+    /**
+     * Additional SDK configuration
+     *
+     * Notable options:
+     * - `panel.useShadowDOM`: Whether to isolate styles in Shadow DOM (default: false).
+     *   Set to false to let custom cards inherit your app's CSS (Tailwind, etc.)
+     */
+    config?: Omit<PillarConfig, 'helpCenter' | 'publicKey'>;
+    /**
+     * Handler called when a task action is triggered from the chat.
+     * Use this to handle AI-suggested actions like opening modals, navigating, etc.
+     *
+     * @example
+     * ```tsx
+     * <PillarProvider
+     *   helpCenter="my-app"
+     *   publicKey="pk_..."
+     *   onTask={(task) => {
+     *     switch (task.name) {
+     *       case 'invite_team_member':
+     *         openInviteModal(task.data);
+     *         break;
+     *       case 'open_settings':
+     *         router.push('/settings');
+     *         break;
+     *     }
+     *   }}
+     * >
+     * ```
+     */
+    onTask?: (task: TaskExecutePayload) => void;
+    /**
+     * Custom card components to render for inline_ui type actions.
+     * Map card type names to React components that will render the inline UI.
+     *
+     * @example
+     * ```tsx
+     * import { InviteMembersCard } from './cards/InviteMembersCard';
+     *
+     * <PillarProvider
+     *   helpCenter="my-app"
+     *   publicKey="pk_..."
+     *   cards={{
+     *     invite_members: InviteMembersCard,
+     *     confirm_delete: ConfirmDeleteCard,
+     *   }}
+     * >
+     * ```
+     */
+    cards?: Record<string, CardComponent>;
+    /** Children components */
+    children: ReactNode;
+}
+export declare function PillarProvider({ helpCenter, publicKey, config, onTask, cards, children, }: PillarProviderProps): React.ReactElement;
+export declare function usePillarContext(): PillarContextValue;

package/dist/Tooltip.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tooltip Component
+ * Wrapper component that adds tooltip functionality to children
+ */
+import React, { type ReactNode, type CSSProperties } from 'react';
+export interface TooltipProps {
+    /** Unique tooltip ID that matches a tooltip in your Pillar dashboard */
+    tooltipId: string;
+    /** Trigger behavior: hover, click, focus, or icon (shows info icon) */
+    trigger?: 'hover' | 'click' | 'focus' | 'icon';
+    /** Tooltip position relative to the target */
+    position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    /** Children elements to attach the tooltip to */
+    children: ReactNode;
+    /** Additional class name for the wrapper */
+    className?: string;
+    /** Additional inline styles for the wrapper */
+    style?: CSSProperties;
+    /** Whether the wrapper should be a span (inline) or div (block) */
+    inline?: boolean;
+}
+/**
+ * Tooltip wrapper component that adds Pillar tooltip functionality to children
+ *
+ * @example
+ * ```tsx
+ * <Tooltip tooltipId="feature-explanation" trigger="hover">
+ *   <button>Learn More</button>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Tooltip tooltipId="input-help" trigger="icon">
+ *   <label>Email Address</label>
+ * </Tooltip>
+ * ```
+ */
+export declare function Tooltip({ tooltipId, trigger, position, children, className, style, inline, }: TooltipProps): React.ReactElement;

package/dist/hooks/useHelpPanel.d.ts

@@ -0,0 +1,48 @@
+/**
+ * useHelpPanel Hook
+ * Panel-specific controls and state
+ */
+export interface UseHelpPanelResult {
+    /** Whether the panel is currently open */
+    isOpen: boolean;
+    /** Open the panel */
+    open: (options?: {
+        view?: string;
+        article?: string;
+        search?: string;
+    }) => void;
+    /** Close the panel */
+    close: () => void;
+    /** Toggle the panel */
+    toggle: () => void;
+    /** Open a specific article in the panel */
+    openArticle: (slug: string) => void;
+    /** Open a specific category in the panel */
+    openCategory: (slug: string) => Promise<void>;
+    /** Open search with a query */
+    openSearch: (query?: string) => void;
+    /** Open the AI chat */
+    openChat: () => void;
+}
+/**
+ * Hook for panel-specific controls
+ *
+ * @example
+ * ```tsx
+ * function HelpButton() {
+ *   const { isOpen, toggle, openChat } = useHelpPanel();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={toggle}>
+ *         {isOpen ? 'Close' : 'Help'}
+ *       </button>
+ *       <button onClick={openChat}>
+ *         Ask AI
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useHelpPanel(): UseHelpPanelResult;

package/dist/hooks/usePillar.d.ts

@@ -0,0 +1,59 @@
+/**
+ * usePillar Hook
+ * Access Pillar SDK instance and state with optional type-safe onTask
+ */
+import type { SyncActionDefinitions, ActionDefinitions, ActionDataType, ActionNames } from '@pillar-ai/sdk';
+import { type PillarContextValue } from '../PillarProvider';
+export type UsePillarResult = PillarContextValue;
+/**
+ * Extended result with type-safe onTask method.
+ *
+ * @template TActions - The action definitions for type inference
+ */
+export interface TypedUsePillarResult<TActions extends SyncActionDefinitions | ActionDefinitions> extends Omit<PillarContextValue, 'pillar'> {
+    pillar: PillarContextValue['pillar'];
+    /**
+     * Type-safe task handler registration.
+     *
+     * @param taskName - The action name (autocompleted from your actions)
+     * @param handler - Handler function with typed data parameter
+     * @returns Unsubscribe function
+     */
+    onTask: <TName extends ActionNames<TActions>>(taskName: TName, handler: (data: ActionDataType<TActions, TName>) => void) => () => void;
+}
+/**
+ * Hook to access the Pillar SDK instance and state
+ *
+ * @example Basic usage (untyped)
+ * ```tsx
+ * function MyComponent() {
+ *   const { isReady, open, close, isPanelOpen } = usePillar();
+ *
+ *   if (!isReady) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <button onClick={() => open()}>
+ *       {isPanelOpen ? 'Close Help' : 'Get Help'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Type-safe onTask with action definitions
+ * ```tsx
+ * import { actions } from '@/lib/pillar/actions';
+ *
+ * function MyComponent() {
+ *   const { pillar, onTask } = usePillar<typeof actions>();
+ *
+ *   useEffect(() => {
+ *     // TypeScript knows data has { type, url, name }
+ *     const unsub = onTask('add_new_source', (data) => {
+ *       console.log(data.url); // ✓ Typed!
+ *     });
+ *     return unsub;
+ *   }, [onTask]);
+ * }
+ * ```
+ */
+export declare function usePillar<TActions extends SyncActionDefinitions | ActionDefinitions = SyncActionDefinitions>(): TypedUsePillarResult<TActions>;

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @pillar-ai/react - React bindings for Pillar Embedded Help SDK
+ *
+ * @example
+ * ```tsx
+ * import { PillarProvider, Tooltip, PillarPanel, usePillar, useHelpPanel } from '@pillar-ai/react';
+ *
+ * function App() {
+ *   return (
+ *     <PillarProvider helpCenter="your-help-center" publicKey="pk_live_xxx">
+ *       <MyApp />
+ *     </PillarProvider>
+ *   );
+ * }
+ *
+ * function MyApp() {
+ *   const { isReady } = usePillar();
+ *   const { toggle } = useHelpPanel();
+ *
+ *   return (
+ *     <div>
+ *       <Tooltip tooltipId="welcome-tooltip">
+ *         <h1>Welcome!</h1>
+ *       </Tooltip>
+ *       <button onClick={toggle}>Get Help</button>
+ *     </div>
+ *   );
+ * }
+ *
+ * // Custom panel placement example:
+ * function AppWithCustomPanel() {
+ *   return (
+ *     <PillarProvider
+ *       helpCenter="your-help-center"
+ *       publicKey="pk_live_xxx"
+ *       config={{ panel: { container: 'manual' } }}
+ *     >
+ *       <div className="layout">
+ *         <PillarPanel className="custom-panel" />
+ *         <main>Your content</main>
+ *       </div>
+ *     </PillarProvider>
+ *   );
+ * }
+ * ```
+ */
+export { PillarProvider, usePillarContext, type PillarContextValue, type PillarProviderProps, type CardComponentProps, type CardComponent, } from './PillarProvider';
+export { PillarPanel, type PillarPanelProps } from './PillarPanel';
+export { Tooltip, type TooltipProps } from './Tooltip';
+export { useHelpPanel, type UseHelpPanelResult } from './hooks/useHelpPanel';
+export { usePillar, type UsePillarResult, type TypedUsePillarResult } from './hooks/usePillar';
+export type { FloatingButtonConfig, PanelConfig, PillarConfig, PillarEvents, PillarState, ResolvedConfig, ResolvedThemeConfig, TaskExecutePayload, TextSelectionConfig, ThemeColors, ThemeConfig, ThemeMode, TooltipsConfig, CardCallbacks, CardRenderer, SidebarTabConfig, ActionDefinitions, SyncActionDefinitions, ActionDataType, ActionNames, } from '@pillar-ai/sdk';