bonsai-search 3.0.8

package/dist/index.d.cts

@@ -0,0 +1,312 @@
+//#region src/types.d.ts
+/** Size configuration for srcset generation */
+interface SrcSetSize {
+  /** Width in pixels */
+  width: number;
+  /** Height in pixels */
+  height: number;
+  /** Crop mode (e.g., 'crop_center', 'crop_top') */
+  crop: string;
+}
+/** Map of SDK class names to additional classes to add */
+type ClassAdditions = Record<string, string[]>;
+interface BonsaiSearchConfig {
+  /** The container element where the search UI will be rendered */
+  container: HTMLElement;
+  /** API key for authentication */
+  apiKey: string;
+  /** Tenant/Organization ID */
+  baseUrl?: string;
+  /** Placeholder text for search input */
+  placeholder?: string;
+  /** Array of search suggestion strings */
+  suggestions?: string[];
+  /** Debounce delay in milliseconds for search-as-you-type (0 = disabled) */
+  debounceMs?: number;
+  /** Maximum number of results to display */
+  maxResults?: number;
+  /** Request timeout in milliseconds */
+  timeoutMs?: number;
+  /** Hostname for image CDN (e.g., 'mmlafleur.com') - used for srcset generation */
+  imageHostname?: string;
+  /** Whether to generate srcset attributes for product images */
+  generateSrcSet?: boolean;
+  /** Array of sizes for srcset generation */
+  srcSetSizes?: SrcSetSize[];
+  /** Map of SDK class names to additional classes to add to those elements */
+  classAdditions?: ClassAdditions;
+  /** Whether to render price in result cards (default: false for backward compatibility) */
+  renderPrice?: boolean;
+  /** If true, show price with title in caption. If false, render price in separate element (default: true) */
+  renderPriceWithTitle?: boolean;
+  /** Callback to transform price before rendering (e.g., for formatting) */
+  onPrice?: (result: SearchResult, price: string, parent?: HTMLElement) => string;
+  /** Callback to customize image element after creation. sdk is the BonsaiSearch instance. */
+  onImg?: (result: SearchResult, imgElement: HTMLImageElement, wrapperElement: HTMLElement, sdk: any) => void;
+  /** Callback fired when search is initiated */
+  onSearch?: (query: string) => void;
+  /**
+   * Callback fired when initial results are received (from Meilisearch).
+   * In v3, this is called immediately when the "results" SSE event is received.
+   */
+  onResults?: (results: SearchResult[]) => void;
+  /**
+   * Callback fired when AI-scored results and recommendations are received.
+   * In v3, this is called when the "ai" SSE event is received (after LLM processing).
+   */
+  onAi?: (data: AiEventData) => void;
+  /** Callback fired when an error occurs */
+  onError?: (error: Error) => void;
+  /** Object-fit CSS property for result images. Accepts "cover" or "contain". Defaults to "cover". */
+  imageObjectFit?: "cover" | "contain";
+  /** Whether to enable markdown rendering for recommendation text. Defaults to false. */
+  markdown?: boolean;
+  /** Label for featured/recommended items section (default: "Featured Items") */
+  featuredItemsLabel?: string;
+  /** Label for additional items when recommendations exist (default: "More Items") */
+  moreItemsLabel?: string;
+  /** Label for items when no recommendations (default: "Items") */
+  itemsLabel?: string;
+}
+/** Data received from the "ai" SSE event */
+interface AiEventData {
+  /** Whether the AI scoring was successful */
+  success: boolean;
+  /** AI recommendations */
+  recommendations: Recommendation[];
+  /** AI-scored results (filtered by minimum relevancy) */
+  results: SearchResult[];
+  /** Number of results after AI filtering */
+  count: number;
+  /** Maximum relevancy score across all results */
+  maxRelevance: number;
+  /** Error message if AI scoring failed */
+  error?: string;
+}
+/** Data received from the "results" SSE event */
+interface ResultsEventData {
+  /** Whether the search was successful */
+  success: boolean;
+  /** The search query */
+  query: string;
+  /** Initial search results (before AI scoring) */
+  results: SearchResult[];
+  /** Number of results */
+  count: number;
+  /** Initial product count from Meilisearch */
+  initialProductCount: number;
+  /** Error message if search failed */
+  error?: string;
+}
+interface SearchResult {
+  id: string;
+  name: string;
+  handle: string;
+  vendor: string | null;
+  productType: string | null;
+  tags: string[];
+  vectorScore: number;
+  relevancyScore: number;
+  reasoning: string;
+  image: string | null;
+  price: string | null;
+  compareAtPrice: string | null;
+  description: string | null;
+  publicUrl: string;
+  type: "product" | "context";
+}
+interface Recommendation {
+  text: string;
+  productIds: string[];
+  relevancyScore: number;
+  reasoning: string;
+}
+interface SearchResponse {
+  success: boolean;
+  query: string;
+  hydeQuery: string;
+  hydeReasoning: string;
+  count: number;
+  results: SearchResult[];
+  recommendations?: Recommendation[];
+  error?: string;
+}
+interface Suggestion {
+  id: string;
+  suggestion: string;
+}
+//#endregion
+//#region src/bonsai-search-webcomponent.d.ts
+/**
+ * Web Component for Bonsai Search
+ * Fully encapsulated with Shadow DOM, no inherited styles
+ *
+ * Usage:
+ * <bonsai-search
+ *   api-key="your-api-key"
+ *   base-url="https://api.hibonsai.com/rest/search/v2/"
+ *   placeholder="Describe what you're looking for..."
+ *   suggestions='["suggestion 1", "suggestion 2"]'
+ *   max-results="20"
+ *   render-price
+ *   brand-color="#0A5B3B"
+ *   text-color="#303030"
+ *   muted-color="#9CA3AF"
+ *   input-bg="#f5f5f5"
+ *   card-bg="#f5f5f5"
+ *   image-object-fit="cover"
+ *   featured-items-label="Featured Items"
+ *   more-items-label="More Items"
+ *   items-label="Items">
+ * </bonsai-search>
+ */
+declare class BonsaiSearchElement extends HTMLElement {
+  private search;
+  private shadow;
+  private container;
+  static get observedAttributes(): string[];
+  constructor();
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+  private render;
+  private updateStyles;
+  private initialize;
+  setSuggestion(suggestion: string): void;
+  clear(): void;
+  focus(): void;
+  private getDefaultCSS;
+}
+//#endregion
+//#region src/bonsai-searchbar-webcomponent.d.ts
+/**
+ * Web Component for Bonsai Search Bar
+ * Fully encapsulated with Shadow DOM, no inherited styles
+ *
+ * Usage:
+ * <bonsai-searchbar
+ *   search-path="/ai-search"
+ *   placeholder="Describe what you're looking for..."
+ *   suggestions='["suggestion 1", "suggestion 2"]'
+ *   brand-color="#0A5B3B"
+ *   text-color="#303030"
+ *   muted-color="#9CA3AF"
+ *   input-background="#f5f5f5"
+ *   input-opacity="1"
+ *   close-button>
+ * </bonsai-searchbar>
+ */
+declare class BonsaiSearchBarElement extends HTMLElement {
+  private searchBar;
+  private shadow;
+  private container;
+  static get observedAttributes(): string[];
+  constructor();
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+  private render;
+  private updateStyles;
+  private initialize;
+  setQuery(query: string): void;
+  submit(): void;
+  clear(): void;
+  private getDefaultCSS;
+}
+//#endregion
+//#region src/index.d.ts
+declare class BonsaiSearch {
+  private config;
+  private state;
+  private container;
+  private searchBar;
+  private searchInput;
+  private actionsContainer;
+  private submitBtn;
+  private loadingState;
+  private loadingTextInner;
+  private doneState;
+  private resetBtn;
+  private suggestionsDropdown;
+  private poweredBy;
+  private resultsContainer;
+  private query;
+  private loadingIndex;
+  private loadingInterval;
+  private debounceTimer;
+  private abortController;
+  private loadingStates;
+  constructor(config: BonsaiSearchConfig);
+  /** Get the SDK version */
+  static get version(): string;
+  /** Infer base URL from script tag or use current origin */
+  private inferBaseUrl;
+  /** Build class name string with any configured additional classes */
+  private buildClassName;
+  /** Apply a shadow part name for external styling */
+  private applyPart;
+  /** Validate configuration */
+  private validateConfig;
+  /** Render the search UI */
+  private render;
+  /** Render suggestions in the dropdown */
+  private renderSuggestions;
+  /** Attach event listeners */
+  private attachEventListeners;
+  /** Handle input focus */
+  private handleFocus;
+  /** Handle input blur */
+  private handleBlur;
+  /** Handle input change */
+  private handleInput;
+  /** Handle key down */
+  private handleKeyDown;
+  /** Handle suggestion click */
+  private handleSuggestionClick;
+  /** Handle search submit using Server-Sent Events */
+  private handleSubmit;
+  /** Parse SSE events from a buffer string */
+  private parseSSEEvents;
+  /** Handle reset */
+  private handleReset;
+  /** Set the current state and update UI */
+  private setState;
+  /** Update action buttons visibility based on state */
+  private updateActionButtons;
+  /** Update input state (disabled only during loading) */
+  private updateInputState;
+  /** Start loading animation */
+  private startLoadingAnimation;
+  /** Update loading text position */
+  private updateLoadingText;
+  /** Stop loading animation */
+  private stopLoadingAnimation;
+  /** Show recommendations loading indicator */
+  private showRecommendationsLoading;
+  /** Hide recommendations loading indicator */
+  private hideRecommendationsLoading;
+  /** Render search results */
+  private renderResults;
+  /** Generate srcset attribute for an image URL */
+  private getSrcSet;
+  /** Resolve an image value that may be a string URL or an object with sourceUrl/source_url */
+  private resolveImageUrl;
+  /** Create a result card */
+  private createResultCard;
+  /** Render empty state */
+  private renderEmpty;
+  /** Render error state */
+  private renderError;
+  /** Check for query parameter in URL or localStorage */
+  private checkForQueryParam;
+  /** Set a suggestion programmatically and trigger search */
+  setSuggestion(suggestion: string): void;
+  /** Clear the search and results */
+  clear(): void;
+  /** Focus the search input */
+  focus(): void;
+  /** Destroy the instance and clean up */
+  destroy(): void;
+}
+//#endregion
+export { AiEventData, BonsaiSearch, BonsaiSearchBarElement, BonsaiSearchConfig, BonsaiSearchElement, ClassAdditions, Recommendation, ResultsEventData, SearchResponse, SearchResult, SrcSetSize, Suggestion };

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+//#region src/types.d.ts
+/** Size configuration for srcset generation */
+interface SrcSetSize {
+  /** Width in pixels */
+  width: number;
+  /** Height in pixels */
+  height: number;
+  /** Crop mode (e.g., 'crop_center', 'crop_top') */
+  crop: string;
+}
+/** Map of SDK class names to additional classes to add */
+type ClassAdditions = Record<string, string[]>;
+interface BonsaiSearchConfig {
+  /** The container element where the search UI will be rendered */
+  container: HTMLElement;
+  /** API key for authentication */
+  apiKey: string;
+  /** Tenant/Organization ID */
+  baseUrl?: string;
+  /** Placeholder text for search input */
+  placeholder?: string;
+  /** Array of search suggestion strings */
+  suggestions?: string[];
+  /** Debounce delay in milliseconds for search-as-you-type (0 = disabled) */
+  debounceMs?: number;
+  /** Maximum number of results to display */
+  maxResults?: number;
+  /** Request timeout in milliseconds */
+  timeoutMs?: number;
+  /** Hostname for image CDN (e.g., 'mmlafleur.com') - used for srcset generation */
+  imageHostname?: string;
+  /** Whether to generate srcset attributes for product images */
+  generateSrcSet?: boolean;
+  /** Array of sizes for srcset generation */
+  srcSetSizes?: SrcSetSize[];
+  /** Map of SDK class names to additional classes to add to those elements */
+  classAdditions?: ClassAdditions;
+  /** Whether to render price in result cards (default: false for backward compatibility) */
+  renderPrice?: boolean;
+  /** If true, show price with title in caption. If false, render price in separate element (default: true) */
+  renderPriceWithTitle?: boolean;
+  /** Callback to transform price before rendering (e.g., for formatting) */
+  onPrice?: (result: SearchResult, price: string, parent?: HTMLElement) => string;
+  /** Callback to customize image element after creation. sdk is the BonsaiSearch instance. */
+  onImg?: (result: SearchResult, imgElement: HTMLImageElement, wrapperElement: HTMLElement, sdk: any) => void;
+  /** Callback fired when search is initiated */
+  onSearch?: (query: string) => void;
+  /**
+   * Callback fired when initial results are received (from Meilisearch).
+   * In v3, this is called immediately when the "results" SSE event is received.
+   */
+  onResults?: (results: SearchResult[]) => void;
+  /**
+   * Callback fired when AI-scored results and recommendations are received.
+   * In v3, this is called when the "ai" SSE event is received (after LLM processing).
+   */
+  onAi?: (data: AiEventData) => void;
+  /** Callback fired when an error occurs */
+  onError?: (error: Error) => void;
+  /** Object-fit CSS property for result images. Accepts "cover" or "contain". Defaults to "cover". */
+  imageObjectFit?: "cover" | "contain";
+  /** Whether to enable markdown rendering for recommendation text. Defaults to false. */
+  markdown?: boolean;
+  /** Label for featured/recommended items section (default: "Featured Items") */
+  featuredItemsLabel?: string;
+  /** Label for additional items when recommendations exist (default: "More Items") */
+  moreItemsLabel?: string;
+  /** Label for items when no recommendations (default: "Items") */
+  itemsLabel?: string;
+}
+/** Data received from the "ai" SSE event */
+interface AiEventData {
+  /** Whether the AI scoring was successful */
+  success: boolean;
+  /** AI recommendations */
+  recommendations: Recommendation[];
+  /** AI-scored results (filtered by minimum relevancy) */
+  results: SearchResult[];
+  /** Number of results after AI filtering */
+  count: number;
+  /** Maximum relevancy score across all results */
+  maxRelevance: number;
+  /** Error message if AI scoring failed */
+  error?: string;
+}
+/** Data received from the "results" SSE event */
+interface ResultsEventData {
+  /** Whether the search was successful */
+  success: boolean;
+  /** The search query */
+  query: string;
+  /** Initial search results (before AI scoring) */
+  results: SearchResult[];
+  /** Number of results */
+  count: number;
+  /** Initial product count from Meilisearch */
+  initialProductCount: number;
+  /** Error message if search failed */
+  error?: string;
+}
+interface SearchResult {
+  id: string;
+  name: string;
+  handle: string;
+  vendor: string | null;
+  productType: string | null;
+  tags: string[];
+  vectorScore: number;
+  relevancyScore: number;
+  reasoning: string;
+  image: string | null;
+  price: string | null;
+  compareAtPrice: string | null;
+  description: string | null;
+  publicUrl: string;
+  type: "product" | "context";
+}
+interface Recommendation {
+  text: string;
+  productIds: string[];
+  relevancyScore: number;
+  reasoning: string;
+}
+interface SearchResponse {
+  success: boolean;
+  query: string;
+  hydeQuery: string;
+  hydeReasoning: string;
+  count: number;
+  results: SearchResult[];
+  recommendations?: Recommendation[];
+  error?: string;
+}
+interface Suggestion {
+  id: string;
+  suggestion: string;
+}
+//#endregion
+//#region src/bonsai-search-webcomponent.d.ts
+/**
+ * Web Component for Bonsai Search
+ * Fully encapsulated with Shadow DOM, no inherited styles
+ *
+ * Usage:
+ * <bonsai-search
+ *   api-key="your-api-key"
+ *   base-url="https://api.hibonsai.com/rest/search/v2/"
+ *   placeholder="Describe what you're looking for..."
+ *   suggestions='["suggestion 1", "suggestion 2"]'
+ *   max-results="20"
+ *   render-price
+ *   brand-color="#0A5B3B"
+ *   text-color="#303030"
+ *   muted-color="#9CA3AF"
+ *   input-bg="#f5f5f5"
+ *   card-bg="#f5f5f5"
+ *   image-object-fit="cover"
+ *   featured-items-label="Featured Items"
+ *   more-items-label="More Items"
+ *   items-label="Items">
+ * </bonsai-search>
+ */
+declare class BonsaiSearchElement extends HTMLElement {
+  private search;
+  private shadow;
+  private container;
+  static get observedAttributes(): string[];
+  constructor();
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+  private render;
+  private updateStyles;
+  private initialize;
+  setSuggestion(suggestion: string): void;
+  clear(): void;
+  focus(): void;
+  private getDefaultCSS;
+}
+//#endregion
+//#region src/bonsai-searchbar-webcomponent.d.ts
+/**
+ * Web Component for Bonsai Search Bar
+ * Fully encapsulated with Shadow DOM, no inherited styles
+ *
+ * Usage:
+ * <bonsai-searchbar
+ *   search-path="/ai-search"
+ *   placeholder="Describe what you're looking for..."
+ *   suggestions='["suggestion 1", "suggestion 2"]'
+ *   brand-color="#0A5B3B"
+ *   text-color="#303030"
+ *   muted-color="#9CA3AF"
+ *   input-background="#f5f5f5"
+ *   input-opacity="1"
+ *   close-button>
+ * </bonsai-searchbar>
+ */
+declare class BonsaiSearchBarElement extends HTMLElement {
+  private searchBar;
+  private shadow;
+  private container;
+  static get observedAttributes(): string[];
+  constructor();
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+  private render;
+  private updateStyles;
+  private initialize;
+  setQuery(query: string): void;
+  submit(): void;
+  clear(): void;
+  private getDefaultCSS;
+}
+//#endregion
+//#region src/index.d.ts
+declare class BonsaiSearch {
+  private config;
+  private state;
+  private container;
+  private searchBar;
+  private searchInput;
+  private actionsContainer;
+  private submitBtn;
+  private loadingState;
+  private loadingTextInner;
+  private doneState;
+  private resetBtn;
+  private suggestionsDropdown;
+  private poweredBy;
+  private resultsContainer;
+  private query;
+  private loadingIndex;
+  private loadingInterval;
+  private debounceTimer;
+  private abortController;
+  private loadingStates;
+  constructor(config: BonsaiSearchConfig);
+  /** Get the SDK version */
+  static get version(): string;
+  /** Infer base URL from script tag or use current origin */
+  private inferBaseUrl;
+  /** Build class name string with any configured additional classes */
+  private buildClassName;
+  /** Apply a shadow part name for external styling */
+  private applyPart;
+  /** Validate configuration */
+  private validateConfig;
+  /** Render the search UI */
+  private render;
+  /** Render suggestions in the dropdown */
+  private renderSuggestions;
+  /** Attach event listeners */
+  private attachEventListeners;
+  /** Handle input focus */
+  private handleFocus;
+  /** Handle input blur */
+  private handleBlur;
+  /** Handle input change */
+  private handleInput;
+  /** Handle key down */
+  private handleKeyDown;
+  /** Handle suggestion click */
+  private handleSuggestionClick;
+  /** Handle search submit using Server-Sent Events */
+  private handleSubmit;
+  /** Parse SSE events from a buffer string */
+  private parseSSEEvents;
+  /** Handle reset */
+  private handleReset;
+  /** Set the current state and update UI */
+  private setState;
+  /** Update action buttons visibility based on state */
+  private updateActionButtons;
+  /** Update input state (disabled only during loading) */
+  private updateInputState;
+  /** Start loading animation */
+  private startLoadingAnimation;
+  /** Update loading text position */
+  private updateLoadingText;
+  /** Stop loading animation */
+  private stopLoadingAnimation;
+  /** Show recommendations loading indicator */
+  private showRecommendationsLoading;
+  /** Hide recommendations loading indicator */
+  private hideRecommendationsLoading;
+  /** Render search results */
+  private renderResults;
+  /** Generate srcset attribute for an image URL */
+  private getSrcSet;
+  /** Resolve an image value that may be a string URL or an object with sourceUrl/source_url */
+  private resolveImageUrl;
+  /** Create a result card */
+  private createResultCard;
+  /** Render empty state */
+  private renderEmpty;
+  /** Render error state */
+  private renderError;
+  /** Check for query parameter in URL or localStorage */
+  private checkForQueryParam;
+  /** Set a suggestion programmatically and trigger search */
+  setSuggestion(suggestion: string): void;
+  /** Clear the search and results */
+  clear(): void;
+  /** Focus the search input */
+  focus(): void;
+  /** Destroy the instance and clean up */
+  destroy(): void;
+}
+//#endregion
+export { AiEventData, BonsaiSearch, BonsaiSearchBarElement, BonsaiSearchConfig, BonsaiSearchElement, ClassAdditions, Recommendation, ResultsEventData, SearchResponse, SearchResult, SrcSetSize, Suggestion };