@paymanai/payman-ask-sdk 2.0.5 → 4.0.0

package/README.md

@@ -93,6 +93,15 @@ type ChatConfig = {
       text?: string;
       icon?: boolean;
       content?: React.ReactNode;
+      suggestions?: {
+        enabled?: boolean;
+        title?: string;
+        categories: Array<{
+          label: string;
+          icon?: React.ReactNode;
+          prompts: string[];
+        }>;
+      };
     };
 
     input?: {
@@ -154,6 +163,48 @@ Leaving the `ui` block out renders a usable ChatGPT-style surface:
 
 Turn features on with booleans, and only reach for the full object form when you need custom labels, widths, or per-option toggles.
 
+## Suggested prompts
+
+Use `ui.emptyState.suggestions` when an app wants SDK-rendered prompt shortcuts on the first screen. Apps own the content; the SDK owns rendering, accessibility, click handling, responsive layout, and styling.
+
+The SDK renders categories as compact bubbles first. Clicking a category reveals that category's prompts below it; clicking a prompt sends the prompt text verbatim. On narrow screens and React Native, categories become a horizontal touch scroller so the empty state stays compact.
+
+```tsx
+const isProd = process.env.NEXT_PUBLIC_ENV === "production";
+const suggestions = {
+  enabled: true,
+  title: "Good evening\nHow can I help you today?",
+  categories: [
+    { label: "ACCOUNTS", prompts: ["Show my account balance"] },
+    { label: "PAYMENTS", prompts: ["Pay Sarah $50", "Transfer money to my savings"] },
+    ...(isProd
+      ? []
+      : [{ label: "SIMULATION TOOLS", prompts: ["Simulate a mid-stream error"] }]),
+  ],
+};
+
+<PaymanChat
+  config={{
+    ...config,
+    ui: {
+      ...config.ui,
+      emptyState: {
+        ...config.ui?.emptyState,
+        suggestions,
+      },
+    },
+  }}
+/>
+```
+
+`enabled: false` hides the bubbles without removing the data. Category and prompt arrays render in the order provided, and empty categories are ignored. Bubbles disappear after the first message because they are part of the empty state.
+
+`title` is optional and falls back to `ui.emptyState.text`. Newlines are preserved, so pass `"Good evening\nHow can I help you today?"` when you want the original two-line empty-state layout. If a single-line greeting like `"Good evening How can I help..."` is provided, the SDK inserts a dash between the greeting and question.
+
+`icon` is optional. When omitted, the SDK chooses a small built-in glyph from the category label for common labels like payments, accounts, insights, and products.
+
+Suggested prompts use the same `--payman-v2-*` CSS variables as the rest of the chat surface, so app-level theme overrides automatically apply to bubble background, text, border, hover, radius, and focus states. The React Native renderer uses native `Pressable` and `ScrollView` controls with the same category-first behavior.
+
 ## Session history
 
 Pass `ui.sessionHistory: true` and provide `workflow.id` + `session.owner.id`. `<PaymanChat/>` mounts a resizable, collapsible sidebar on desktop and a hamburger-triggered drawer on mobile. Clicking a row calls `loadSession(sessionId)` — which cancels any in-flight stream, clears the current chat, fetches the conversation history, and renders it with `isHistorical: true` (renderers skip the thinking/step UI for those rows).