@cloudflare/ai-search-snippet 0.0.36 → 0.0.38

package/dist/main.d.ts

@@ -48,15 +48,27 @@ export declare class ChatBubbleSnippet extends HTMLElement {
     private container;
     private isExpanded;
     private isMinimized;
+    private translationsOverride;
+    private resolvedTranslations;
     private handleBubbleClick;
     private handleCloseClick;
     private handleMinimizeClick;
     private handleClearClick;
-    static get observedAttributes(): readonly ["api-url", "placeholder", "theme", "hide-branding"];
+    static get observedAttributes(): readonly ["api-url", "placeholder", "theme", "hide-branding", "translations"];
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * Get the current translations object.
+     */
+    get translations(): Translations | null;
+    /**
+     * Override any user-facing string. Omitted keys fall back to English defaults.
+     */
+    set translations(value: Translations | null | undefined);
+    private syncTranslationsFromAttribute;
+    private rerenderAfterTranslationsChange;
     private getProps;
     private initializeClient;
     private render;
@@ -96,16 +108,34 @@ export declare class ChatPageSnippet extends HTMLElement {
     private sessions;
     private currentSessionId;
     private sidebarCollapsed;
+    private translationsOverride;
+    private resolvedTranslations;
     private handleClearClick;
     private handleNewChatClick;
     private handleToggleSidebarClick;
     private handleChatListClick;
     private handleMessageEvent;
-    static get observedAttributes(): readonly ["api-url", "placeholder", "theme", "hide-branding"];
+    static get observedAttributes(): readonly ["api-url", "placeholder", "theme", "hide-branding", "translations"];
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * Get the current translations object.
+     */
+    get translations(): Translations | null;
+    /**
+     * Override any user-facing string. Omitted keys fall back to English defaults.
+     */
+    set translations(value: Translations | null | undefined);
+    private syncTranslationsFromAttribute;
+    /**
+     * Replace the stored title of any still-default-titled session with the
+     * current `newChatButton` translation, so the sidebar reflects the active
+     * language after a translations change.
+     */
+    private refreshDefaultSessionTitles;
+    private rerenderAfterTranslationsChange;
     private getProps;
     private initializeClient;
     private render;
@@ -153,6 +183,14 @@ declare interface ChatSession {
     messages: Message[];
     createdAt: number;
     updatedAt: number;
+    /**
+     * True while the session still carries the default (auto-generated) title.
+     * Set to false once auto-titled from the first user message, or explicitly
+     * renamed. Absent on sessions persisted before this field existed; those
+     * are treated as having a default title iff the title string still matches
+     * the current `newChatButton` translation (legacy behavior).
+     */
+    titleIsDefault?: boolean;
 }
 
 declare type ChatTextResponse = {
@@ -162,6 +200,16 @@ declare type ChatTextResponse = {
 
 declare type ChatTypes = ChatResult | ChatTextResponse | ChatError;
 
+export declare const DEFAULT_TRANSLATIONS: Required<Translations>;
+
+/**
+ * Merge user-provided translations with built-in defaults.
+ *
+ * Performs a shallow merge so any omitted keys fall back to English. If
+ * `loadingMessages` is provided, it fully replaces the default array.
+ */
+export declare function mergeTranslations(user?: Translations | null): Required<Translations>;
+
 declare interface Message {
     id: string;
     role: 'user' | 'assistant' | 'system';
@@ -179,10 +227,6 @@ declare interface RequestState {
     timestamp: number;
 }
 
-/**
- * Search Bar Snippet
- * A search bar with results display
- */
 declare class SearchBarSnippet extends HTMLElement {
     private shadow;
     private client;
@@ -194,15 +238,31 @@ declare class SearchBarSnippet extends HTMLElement {
     private currentSearchController;
     private loadingMessageInterval;
     private loadingMessageIndex;
+    private translationsOverride;
+    private resolvedTranslations;
     private handleInputChange;
     private handleInputKeydownEnter;
     private handleInputKeydownEscape;
     private handleSearchButtonClick;
-    static get observedAttributes(): readonly ["api-url", "placeholder", "max-results", "debounce-ms", "theme", "hide-branding", "show-url", "show-date", "hide-thumbnails", "see-more", "request-options"];
+    static get observedAttributes(): readonly ["api-url", "placeholder", "max-results", "max-render-results", "debounce-ms", "theme", "hide-branding", "show-url", "show-date", "hide-thumbnails", "see-more", "request-options", "translations"];
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * Get the current translations object. Mirrors the property getter.
+     */
+    get translations(): Translations | null;
+    /**
+     * Override any user-facing string. Omitted keys fall back to English defaults.
+     */
+    set translations(value: Translations | null | undefined);
+    /**
+     * Re-render preserving the current query and re-running the search so
+     * results remain visible after a translations change at runtime.
+     */
+    private rerender;
+    private syncTranslationsFromAttribute;
     private getProps;
     private getRequestOptions;
     private initializeClient;
@@ -250,17 +310,35 @@ export declare class SearchModalSnippet extends HTMLElement {
     private currentSearchController;
     private loadingMessageInterval;
     private loadingMessageIndex;
+    private translationsOverride;
+    private resolvedTranslations;
     private handleGlobalKeydown;
     private handleInputChange;
     private handleInputKeydown;
     private handleBackdropClick;
     private savedBodyStyles;
     private savedHtmlOverflow;
-    static get observedAttributes(): readonly ["api-url", "placeholder", "max-results", "theme", "shortcut", "use-meta-key", "debounce-ms", "hide-branding", "show-url", "show-date", "hide-thumbnails", "see-more", "request-options"];
+    static get observedAttributes(): readonly ["api-url", "placeholder", "max-results", "max-render-results", "theme", "shortcut", "use-meta-key", "debounce-ms", "hide-branding", "show-url", "show-date", "hide-thumbnails", "see-more", "request-options", "translations"];
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * Get the current translations object.
+     */
+    get translations(): Translations | null;
+    /**
+     * Override any user-facing string. Omitted keys fall back to English defaults.
+     */
+    set translations(value: Translations | null | undefined);
+    /**
+     * Re-render while preserving open state and the current query. Results are
+     * re-fetched so the list reflects the updated translation strings around
+     * them (counts, footer hints, etc.). Selection resets to none — the same
+     * behavior as the immediate post-search state.
+     */
+    private rerender;
+    private syncTranslationsFromAttribute;
     private getProps;
     private getRequestOptions;
     private initializeClient;
@@ -360,8 +438,10 @@ export declare interface SearchSnippetProps {
     apiUrl: string;
     /** Input placeholder text */
     placeholder?: string;
-    /** Maximum search results to display  */
+    /** Maximum search results to request from the API */
     maxResults?: number;
+    /** Maximum search results to render in the UI (caps the visible list and drives the "see more" affordance) */
+    maxRenderResults?: number;
     /** Input debounce delay in milliseconds (search-bar only) */
     debounceMs?: number;
     /** Color scheme */
@@ -376,11 +456,151 @@ export declare interface SearchSnippetProps {
     hideThumbnails?: boolean;
     /** URL template for "See more" link. The search query is appended URL-encoded. Example: "https://example.com/search?q=" */
     seeMore?: string;
+    /**
+     * Override any user-facing string. Omitted keys fall back to English defaults.
+     *
+     * @example
+     * ```ts
+     * element.translations = { placeholder: 'Busca aquí...' };
+     * ```
+     */
+    translations?: Translations;
 }
 
+export declare type Theme = 'light' | 'dark' | 'auto';
+
 /**
- * Core type definitions for the Search Snippet Library
+ * Translation utilities for component user-facing strings.
+ *
+ * Users override any subset of translations via the `translations` attribute
+ * (JSON string) or property (plain object). Missing keys fall back to the
+ * built-in English defaults.
+ *
+ * @example
+ * ```html
+ * <search-bar-snippet translations='{"placeholder":"Busca aqu\u00ed..."}'></search-bar-snippet>
+ * ```
+ *
+ * @example
+ * ```ts
+ * element.translations = { placeholder: 'Busca aquí...' };
+ * ```
  */
-export declare type Theme = 'light' | 'dark' | 'auto';
+/**
+ * All user-facing strings rendered by the snippet components.
+ *
+ * All keys are optional; unspecified keys fall back to English defaults.
+ * Strings can contain `{name}` tokens that are interpolated at render time.
+ */
+export declare interface Translations {
+    /** Aria label for loading spinners. Default: "Loading" */
+    loadingAriaLabel?: string;
+    /** Bold prefix for error messages. Default: "Error:" */
+    errorPrefix?: string;
+    /** Message shown when the `api-url` attribute is missing. */
+    missingApiUrlError?: string;
+    /** Branding prefix before the product link. Default: "Powered by" */
+    poweredBy?: string;
+    /** Branding link label. Default: "Cloudflare AI Search" */
+    poweredByLinkLabel?: string;
+    /** Search input placeholder text. */
+    placeholder?: string;
+    /** Search submit button text and aria-label. */
+    searchButtonLabel?: string;
+    /** Aria-label for the search input on the bar variant. */
+    searchInputAriaLabel?: string;
+    /** Aria-label for the modal results list. */
+    searchResultsAriaLabel?: string;
+    /** Title shown before a user enters a query (bar variant). */
+    emptyStateTitle?: string;
+    /** Description shown before a user enters a query (bar variant). */
+    emptyStateDescription?: string;
+    /** Description shown before a user enters a query (modal variant). */
+    modalEmptyStateDescription?: string;
+    /** Title shown when a search returns no results (bar variant). */
+    noResultsTitle?: string;
+    /** Description shown when a search returns no results (bar variant). Supports `{query}`. */
+    noResultsDescription?: string;
+    /** Title shown when a search returns no results (modal variant). */
+    modalNoResultsTitle?: string;
+    /** Description shown when a search returns no results (modal variant). Supports `{query}`. */
+    modalNoResultsDescription?: string;
+    /** Bar results count when exactly 1 result. Supports `{n}`. */
+    resultsCount?: string;
+    /** Bar results count when multiple results. Supports `{n}`. */
+    resultsCountPlural?: string;
+    /** Bar/modal results count when truncated. Supports `{n}` and `{total}`. */
+    resultsCountOverflow?: string;
+    /** Modal footer results count when exactly 1 result. Supports `{n}`. */
+    modalResultsCount?: string;
+    /** Modal footer results count when multiple results. Supports `{n}`. */
+    modalResultsCountPlural?: string;
+    /** Modal footer count shown with the zero-results state. */
+    modalResultsCountZero?: string;
+    /** Modal footer text shown with the error state. */
+    modalResultsCountError?: string;
+    /** Label for the "see more" link when `see-more` is configured. */
+    seeMoreResults?: string;
+    /** Modal footer hint next to the ↑ ↓ keys. */
+    navigateHint?: string;
+    /** Modal footer hint next to the ↵ key. */
+    selectHint?: string;
+    /** Modal footer hint next to the Esc key. */
+    closeHint?: string;
+    /** Chat header title. */
+    chatTitle?: string;
+    /** Chat input placeholder text. */
+    chatPlaceholder?: string;
+    /** Aria-label for the chat textarea. */
+    chatInputAriaLabel?: string;
+    /** Chat send button text. */
+    sendButtonLabel?: string;
+    /** Chat send button aria-label. */
+    sendButtonAriaLabel?: string;
+    /** Empty chat state title. */
+    chatEmptyTitle?: string;
+    /** Empty chat state description. */
+    chatEmptyDescription?: string;
+    /** User message avatar text. Default: "U" */
+    userAvatar?: string;
+    /** Assistant message avatar text. Default: "AI" */
+    assistantAvatar?: string;
+    /** Fallback for chat errors with no message. */
+    unknownError?: string;
+    /** Aria-label for the floating chat bubble button. */
+    openChatAriaLabel?: string;
+    /** Aria-label for the clear-history icon button. */
+    clearHistoryAriaLabel?: string;
+    /** Aria-label for the minimize icon button. */
+    minimizeAriaLabel?: string;
+    /** Aria-label for the close icon button. */
+    closeAriaLabel?: string;
+    /** Sidebar heading on the chat-page variant. */
+    historyTitle?: string;
+    /** New-chat button label. */
+    newChatButton?: string;
+    /** Clear-chat header button label. */
+    clearChatButton?: string;
+    /** Tooltip for the sidebar toggle button. */
+    toggleSidebarTitle?: string;
+    /** Tooltip for a per-session delete button. */
+    deleteChatTitle?: string;
+    /** Empty sessions list message. */
+    noChatsYet?: string;
+    /** Label for "one day ago" in the sessions list. */
+    yesterday?: string;
+    /** Relative timestamp for < 1 minute ago. */
+    justNow?: string;
+    /** Relative timestamp for exactly 1 minute ago. Supports `{n}`. */
+    minuteAgo?: string;
+    /** Relative timestamp for 2-59 minutes ago. Supports `{n}`. */
+    minutesAgo?: string;
+    /** Relative timestamp for exactly 1 hour ago. Supports `{n}`. */
+    hourAgo?: string;
+    /** Relative timestamp for 2-23 hours ago. Supports `{n}`. */
+    hoursAgo?: string;
+    /** Cycling loading messages shown during search/streaming. Provide the full array to override. */
+    loadingMessages?: string[];
+}
 
 export { }