@akropolys/kiku 1.0.0

package/README.md

@@ -0,0 +1,204 @@
+# @akropolys/kiku
+
+> Plug-and-play React AI chat, search, and commerce UI components.
+
+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.
+
+---
+
+## 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';
+```
+
+---
+
+## Quick start
+
+```tsx
+import { AkropolysProvider } from '@akropolys/sdk';
+import { KikuButton } from '@akropolys/kiku';
+import '@akropolys/kiku/styles.css';
+
+export default function App() {
+  return (
+    <AkropolysProvider
+      siteId="your-site-id"
+      apiUrl="https://api.akropolys.io"
+      apiToken="your-api-token"
+    >
+      {/* Floating chat button — renders the full AI shopping assistant */}
+      <KikuButton label="Chat with Kiku" />
+    </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;
+}
+```
+
+---
+
+## Using the headless SDK instead
+
+If you want to build your own UI from scratch, install only the core:
+
+```bash
+npm install @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),
+});
+```
+
+---
+
+## License
+
+MIT © Akropolys

package/dist/index.d.mts

@@ -0,0 +1,109 @@
+import React from 'react';
+import { SearchResult, AkropolysTheme, ChatSource, Product } from '@akropolys/sdk';
+
+interface SearchBarProps {
+    placeholder?: string;
+    limit?: number;
+    /** Debounce in ms — default 300 for smooth type-ahead */
+    debounceMs?: number;
+    onSelect?: (result: SearchResult) => void;
+    className?: string;
+    inputClassName?: string;
+    dropdownClassName?: string;
+    renderResult?: (result: SearchResult) => React.ReactNode;
+    theme?: AkropolysTheme;
+    classNames?: {
+        root?: string;
+        input?: string;
+        dropdown?: string;
+        row?: string;
+    };
+}
+declare function SearchBar({ placeholder, limit, debounceMs, onSelect, className, inputClassName, dropdownClassName, renderResult, theme, classNames, }: SearchBarProps): React.JSX.Element;
+
+interface ChatWidgetProps {
+    title?: string;
+    placeholder?: string;
+    emptyStateText?: string;
+    emptyStateSuggestions?: string;
+    defaultCurrency?: string;
+    className?: string;
+    theme?: AkropolysTheme;
+    classNames?: {
+        root?: string;
+        header?: string;
+        messageBubble?: string;
+        input?: string;
+    };
+    onSelectSource?: (source: ChatSource) => void;
+}
+declare function ChatWidget({ title, placeholder, emptyStateText, emptyStateSuggestions, defaultCurrency, className, theme, classNames, onSelectSource }: ChatWidgetProps): React.JSX.Element;
+
+interface KikuButtonProps {
+    label?: string;
+    title?: string;
+    placeholder?: string;
+    backdropColor?: string;
+    backdropBlur?: string | number;
+    className?: string;
+    onSelectSource?: (source: ChatSource) => void;
+    defaultCurrency?: string;
+    chips?: string[];
+    theme?: 'light' | 'dark' | AkropolysTheme;
+    classNames?: {
+        button?: string;
+        overlay?: string;
+        panel?: string;
+        input?: string;
+        sendButton?: string;
+    };
+}
+declare function KikuButton({ label, title, placeholder, backdropColor, backdropBlur, className, onSelectSource, defaultCurrency, chips, theme, classNames, }: KikuButtonProps): React.JSX.Element;
+
+interface SparkleProps {
+    productName: string;
+    limit?: number;
+    onResult?: (results: SearchResult[]) => void;
+    /** Override the backdrop colour (any CSS colour/gradient) */
+    backdropColor?: string;
+    /** 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 */
+    onNavigate?: (result: SearchResult) => boolean | void;
+    theme?: AkropolysTheme;
+    classNames?: {
+        button?: string;
+        backdrop?: string;
+        card?: string;
+        item?: string;
+    };
+    product?: Product;
+}
+declare function Sparkle({ productName, limit, onResult, backdropColor, backdropBlur, className, onNavigate, theme, classNames, product, }: 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;
+}
+declare function ComparisonMatrix({ sources, defaultCurrency }: ComparisonMatrixProps): React.JSX.Element | null;
+
+export { CartBadge, CartDrawer, ChatWidget, type ChatWidgetProps, CheckoutModal, ComparisonMatrix, KikuButton, type KikuButtonProps, ChatWidget as KikuChat, type ChatWidgetProps as KikuChatProps, SearchBar, type SearchBarProps, Sparkle };

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import React from 'react';
+import { SearchResult, AkropolysTheme, ChatSource, Product } from '@akropolys/sdk';
+
+interface SearchBarProps {
+    placeholder?: string;
+    limit?: number;
+    /** Debounce in ms — default 300 for smooth type-ahead */
+    debounceMs?: number;
+    onSelect?: (result: SearchResult) => void;
+    className?: string;
+    inputClassName?: string;
+    dropdownClassName?: string;
+    renderResult?: (result: SearchResult) => React.ReactNode;
+    theme?: AkropolysTheme;
+    classNames?: {
+        root?: string;
+        input?: string;
+        dropdown?: string;
+        row?: string;
+    };
+}
+declare function SearchBar({ placeholder, limit, debounceMs, onSelect, className, inputClassName, dropdownClassName, renderResult, theme, classNames, }: SearchBarProps): React.JSX.Element;
+
+interface ChatWidgetProps {
+    title?: string;
+    placeholder?: string;
+    emptyStateText?: string;
+    emptyStateSuggestions?: string;
+    defaultCurrency?: string;
+    className?: string;
+    theme?: AkropolysTheme;
+    classNames?: {
+        root?: string;
+        header?: string;
+        messageBubble?: string;
+        input?: string;
+    };
+    onSelectSource?: (source: ChatSource) => void;
+}
+declare function ChatWidget({ title, placeholder, emptyStateText, emptyStateSuggestions, defaultCurrency, className, theme, classNames, onSelectSource }: ChatWidgetProps): React.JSX.Element;
+
+interface KikuButtonProps {
+    label?: string;
+    title?: string;
+    placeholder?: string;
+    backdropColor?: string;
+    backdropBlur?: string | number;
+    className?: string;
+    onSelectSource?: (source: ChatSource) => void;
+    defaultCurrency?: string;
+    chips?: string[];
+    theme?: 'light' | 'dark' | AkropolysTheme;
+    classNames?: {
+        button?: string;
+        overlay?: string;
+        panel?: string;
+        input?: string;
+        sendButton?: string;
+    };
+}
+declare function KikuButton({ label, title, placeholder, backdropColor, backdropBlur, className, onSelectSource, defaultCurrency, chips, theme, classNames, }: KikuButtonProps): React.JSX.Element;
+
+interface SparkleProps {
+    productName: string;
+    limit?: number;
+    onResult?: (results: SearchResult[]) => void;
+    /** Override the backdrop colour (any CSS colour/gradient) */
+    backdropColor?: string;
+    /** 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 */
+    onNavigate?: (result: SearchResult) => boolean | void;
+    theme?: AkropolysTheme;
+    classNames?: {
+        button?: string;
+        backdrop?: string;
+        card?: string;
+        item?: string;
+    };
+    product?: Product;
+}
+declare function Sparkle({ productName, limit, onResult, backdropColor, backdropBlur, className, onNavigate, theme, classNames, product, }: 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;
+}
+declare function ComparisonMatrix({ sources, defaultCurrency }: ComparisonMatrixProps): React.JSX.Element | null;
+
+export { CartBadge, CartDrawer, ChatWidget, type ChatWidgetProps, CheckoutModal, ComparisonMatrix, KikuButton, type KikuButtonProps, ChatWidget as KikuChat, type ChatWidgetProps as KikuChatProps, SearchBar, type SearchBarProps, Sparkle };