@akropolys/kiku 1.5.18 → 1.6.0

package/README.md

@@ -1,30 +1,16 @@
 # @akropolys/kiku
 
-> Plug-and-play React AI chat, search, and commerce UI components.
+[![npm](https://img.shields.io/npm/v/@akropolys/kiku?color=orange)](https://www.npmjs.com/package/@akropolys/kiku) [![License](https://img.shields.io/npm/l/@akropolys/kiku)](https://github.com/akropolys/sdk/blob/main/LICENSE) [![TypeScript](https://img.shields.io/badge/types-included-blue)](https://www.typescriptlang.org/)
 
-Kiku is the ready-made UI layer for Akropolys. Drop in a floating chat button, a search bar with AI-powered results, a product comparison matrix, or a full checkout modal — all styled, animated, and wired to the Akropolys backend out of the box.
-
-If you want full control over the UI, use [`@akropolys/sdk`](https://www.npmjs.com/package/@akropolys/sdk) directly.
+**[Docs](https://akropolys.io/docs)**  •  **[GitHub](https://github.com/akropolys/sdk)**
 
 ---
 
-## Install
-
-```bash
-npm install @akropolys/kiku @akropolys/sdk
-# or
-pnpm add @akropolys/kiku @akropolys/sdk
-```
-
-**Import the stylesheet once in your app entry point:**
-
-```ts
-import '@akropolys/kiku/styles.css';
-```
+## The pre-built UI for a smarter search bar.
 
----
+`@akropolys/kiku` is the ready-made front end for [`@akropolys/sdk`](https://www.npmjs.com/package/@akropolys/sdk) — a chat button, a search bar, a per-product "ask about this" prompt — so you don't have to design a search experience from scratch. Drop one in and it's already wired up to plain-language search.
 
-## Quick start
+Want to build your own UI instead? Use `@akropolys/sdk` directly and skip this package.
 
 ```tsx
 import { AkropolysProvider } from '@akropolys/sdk';
@@ -34,169 +20,39 @@ import '@akropolys/kiku/styles.css';
 export default function App() {
   return (
     <AkropolysProvider
-      siteId="your-site-id"
-      apiUrl="https://api.akropolys.io"
-      apiToken="your-api-token"
+      siteId={process.env.NEXT_PUBLIC_AKROPOLYS_SITE_ID}
+      apiToken={process.env.NEXT_PUBLIC_AKROPOLYS_API_TOKEN}
     >
-      {/* Floating chat button — renders the full AI shopping assistant */}
-      <KikuButton label="Chat with Kiku" />
+      <KikuButton />
     </AkropolysProvider>
   );
 }
 ```
 
----
-
 ## Components
 
-### `<KikuButton />` — Floating AI chat assistant
-
-```tsx
-import { KikuButton } from '@akropolys/kiku';
-
-<KikuButton
-  label="Ask Kiku"
-  title="Shopping Assistant"
-  placeholder="What are you looking for?"
-  theme="dark"              // 'light' | 'dark' | AkropolysTheme
-  chips={['Best phones', 'Laptops under KSh 50K']}
-  onSelectSource={(src) => console.log(src)}
-/>
-```
-
----
-
-### `<KikuChat />` — Inline embedded chat widget
-
-```tsx
-import { KikuChat } from '@akropolys/kiku';
-
-<KikuChat
-  title="AI Shopping Assistant"
-  placeholder="Ask about anything in our store…"
-  defaultCurrency="KES"
-/>
-```
-
----
-
-### `<SearchBar />` — Debounced AI search with dropdown
-
-```tsx
-import { SearchBar } from '@akropolys/kiku';
-
-<SearchBar
-  placeholder="Search products…"
-  limit={8}
-  debounceMs={300}
-  onSelect={(result) => {
-    window.location.href = result.product.url;
-  }}
-/>
-```
-
----
-
-### `<Sparkle />` — Per-product AI assistant button
-
-```tsx
-import { Sparkle } from '@akropolys/kiku';
-
-// Place next to any product on a listing or detail page
-<Sparkle productName="Samsung Galaxy S24" />
-```
-
----
-
-### `<ComparisonMatrix />` — Side-by-side product comparison table
-
-```tsx
-import { ComparisonMatrix } from '@akropolys/kiku';
-
-// sources come from useKiku() or useSearch()
-<ComparisonMatrix sources={sources} defaultCurrency="KES" />
-```
-
----
-
-### `<CartBadge />` — Cart item count badge
-
-```tsx
-import { CartBadge } from '@akropolys/kiku';
-
-<CartBadge className="my-badge" />
-```
-
----
-
-### `<CartDrawer />` — Slide-out cart drawer
-
-```tsx
-import { CartDrawer } from '@akropolys/kiku';
-
-<CartDrawer trigger={<button>🛒 Cart</button>} theme="dark" />
-```
-
----
-
-### `<CheckoutModal />` — Full checkout modal (M-Pesa + extensible)
-
-```tsx
-import { CheckoutModal } from '@akropolys/kiku';
-
-<CheckoutModal onClose={() => setOpen(false)} theme="dark" />
-```
-
----
-
-## Theming
-
-All components accept a `theme` prop. Pass `'light'` | `'dark'` for the built-in modes, or pass an `AkropolysTheme` object for full control:
-
-```tsx
-<KikuButton
-  theme={{
-    primaryColor: '#6d28d9',
-    backgroundColor: '#0f0f0f',
-    textColor: '#f5f5f5',
-    fontFamily: 'Inter, sans-serif',
-    borderRadius: '12px',
-  }}
-/>
-```
-
-Alternatively, override CSS variables globally in your stylesheet:
-
-```css
-:root {
-  --hsk-primary: #6d28d9;
-  --hsk-bg: #0f0f0f;
-  --hsk-text: #f5f5f5;
-  --hsk-font: 'Inter', sans-serif;
-  --hsk-border-radius: 12px;
-}
-```
-
----
+| Component | What it does |
+|---|---|
+| `<KikuButton />` | Floating chat assistant |
+| `<KikuChat />` | Chat widget embedded inline on the page |
+| `<SearchBar />` | Search box with a live results dropdown |
+| `<Sparkle />` | Small "ask about this" button next to a product |
+| `<ComparisonMatrix />` | Side-by-side product comparison |
+| `<VoiceButton />` | Speak a query instead of typing it |
+| `<VisualSearch />` | Search by uploading a photo |
 
-## Using the headless SDK instead
-
-If you want to build your own UI from scratch, install only the core:
+## Install
 
 ```bash
-npm install @akropolys/sdk
+npm install @akropolys/kiku @akropolys/sdk
 ```
 
-```tsx
-import { useKiku } from '@akropolys/sdk';
-
-const { send, messages, loading, streaming } = useKiku({
-  onToken: (token) => appendToMyUI(token),
-  onMeta: (meta) => showProducts(meta.sources),
-  onDone: (full) => saveToDatabase(full),
-});
+```ts
+import '@akropolys/kiku/styles.css';
 ```
 
+[Read the full docs →](https://akropolys.io/docs)
+
 ---
 
 ## License

package/dist/index.d.mts

@@ -78,11 +78,11 @@ interface SparkleProps {
     onResult?: (results: SearchResult[]) => void;
     /** Override the backdrop colour (any CSS colour/gradient) */
     backdropColor?: string;
-    /** Override backdrop blur — e.g. "8px" or 8 */
+    /** Override backdrop blur — e.g. "8px" or 8 */
     backdropBlur?: string | number;
     /** Extra classes on the trigger button */
     className?: string;
-    /** Called when user clicks a result — return false to prevent default navigation */
+    /** Called when user clicks a result — return false to prevent default navigation */
     onNavigate?: (result: SearchResult) => boolean | void;
     theme?: AkropolysTheme;
     classNames?: {
@@ -96,23 +96,6 @@ interface SparkleProps {
 }
 declare function Sparkle({ productName, limit, onResult, backdropColor, backdropBlur, className, onNavigate, theme, classNames, product, children, }: SparkleProps): React.JSX.Element;
 
-declare function CartBadge({ className }: {
-    className?: string;
-}): React.JSX.Element | null;
-
-declare function CartDrawer({ trigger, className, theme }: {
-    trigger?: React.ReactNode;
-    className?: string;
-    theme?: 'light' | 'dark' | AkropolysTheme;
-}): React.JSX.Element;
-
-declare function CheckoutModal({ onClose, theme, customStyles, hskThemeAttr }: {
-    onClose: () => void;
-    theme?: string;
-    customStyles?: React.CSSProperties;
-    hskThemeAttr?: string;
-}): React.ReactPortal;
-
 interface ComparisonMatrixProps {
     sources: ChatSource[];
     defaultCurrency?: string;
@@ -163,4 +146,4 @@ interface VisualSearchProps {
  */
 declare function VisualSearch({ onResults, onError, categoryHint, className, disabled, }: VisualSearchProps): React.JSX.Element;
 
-export { CartBadge, CartDrawer, ChatWidget, type ChatWidgetProps, CheckoutModal, ComparisonMatrix, KikuButton, type KikuButtonProps, ChatWidget as KikuChat, type ChatWidgetProps as KikuChatProps, SearchBar, type SearchBarProps, Sparkle, VisualSearch, type VisualSearchProps, VoiceButton, type VoiceButtonProps };
+export { ChatWidget, type ChatWidgetProps, ComparisonMatrix, KikuButton, type KikuButtonProps, ChatWidget as KikuChat, type ChatWidgetProps as KikuChatProps, SearchBar, type SearchBarProps, Sparkle, VisualSearch, type VisualSearchProps, VoiceButton, type VoiceButtonProps };

package/dist/index.d.ts

@@ -78,11 +78,11 @@ interface SparkleProps {
     onResult?: (results: SearchResult[]) => void;
     /** Override the backdrop colour (any CSS colour/gradient) */
     backdropColor?: string;
-    /** Override backdrop blur — e.g. "8px" or 8 */
+    /** Override backdrop blur — e.g. "8px" or 8 */
     backdropBlur?: string | number;
     /** Extra classes on the trigger button */
     className?: string;
-    /** Called when user clicks a result — return false to prevent default navigation */
+    /** Called when user clicks a result — return false to prevent default navigation */
     onNavigate?: (result: SearchResult) => boolean | void;
     theme?: AkropolysTheme;
     classNames?: {
@@ -96,23 +96,6 @@ interface SparkleProps {
 }
 declare function Sparkle({ productName, limit, onResult, backdropColor, backdropBlur, className, onNavigate, theme, classNames, product, children, }: SparkleProps): React.JSX.Element;
 
-declare function CartBadge({ className }: {
-    className?: string;
-}): React.JSX.Element | null;
-
-declare function CartDrawer({ trigger, className, theme }: {
-    trigger?: React.ReactNode;
-    className?: string;
-    theme?: 'light' | 'dark' | AkropolysTheme;
-}): React.JSX.Element;
-
-declare function CheckoutModal({ onClose, theme, customStyles, hskThemeAttr }: {
-    onClose: () => void;
-    theme?: string;
-    customStyles?: React.CSSProperties;
-    hskThemeAttr?: string;
-}): React.ReactPortal;
-
 interface ComparisonMatrixProps {
     sources: ChatSource[];
     defaultCurrency?: string;
@@ -163,4 +146,4 @@ interface VisualSearchProps {
  */
 declare function VisualSearch({ onResults, onError, categoryHint, className, disabled, }: VisualSearchProps): React.JSX.Element;
 
-export { CartBadge, CartDrawer, ChatWidget, type ChatWidgetProps, CheckoutModal, ComparisonMatrix, KikuButton, type KikuButtonProps, ChatWidget as KikuChat, type ChatWidgetProps as KikuChatProps, SearchBar, type SearchBarProps, Sparkle, VisualSearch, type VisualSearchProps, VoiceButton, type VoiceButtonProps };
+export { ChatWidget, type ChatWidgetProps, ComparisonMatrix, KikuButton, type KikuButtonProps, ChatWidget as KikuChat, type ChatWidgetProps as KikuChatProps, SearchBar, type SearchBarProps, Sparkle, VisualSearch, type VisualSearchProps, VoiceButton, type VoiceButtonProps };