@docsearch/sidepanel-js 4.4.0

package/README.md

@@ -0,0 +1,47 @@
+# @docsearch/sidepanel-js
+
+JavaScript package for [DocSearch Sidepanel](http://docsearch.algolia.com/), a standalone Ask AI chat panel.
+
+## Installation
+
+```bash
+yarn add @docsearch/sidepanel-js
+# or
+npm install @docsearch/sidepanel-js
+```
+
+## Get started
+
+If you don’t want to use a package manager, you can use a standalone endpoint:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@docsearch/sidepanel-js@4"></script>
+```
+
+To get started, you need a [`container`](https://docsearch.algolia.com/docs/api#container) for your DocSearch Sidepanel component to go in. If you don’t have one already, you can insert one into your markup:
+
+```html
+<div id="docsearch-sidepanel"></div>
+```
+
+Then, insert DocSearch Sidepanel into it by calling the [`sidepanel`](https://docsearch.algolia.com/docs/api) function and providing the container. It can be a [CSS selector](https://developer.mozilla.org/en-us/docs/web/css/css_selectors) or an [Element](https://developer.mozilla.org/en-us/docs/web/api/htmlelement).
+
+Make sure to provide a [`container`](https://docsearch.algolia.com/docs/api#container) (for example, a `div`).
+
+```js app.js
+import sidepanel from '@docsearch/sidepanel-js';
+
+import '@docsearch/css/dist/sidepanel.css';
+
+sidepanel({
+  container: '#docsearch-sidepanel',
+  indexName: 'YOUR_INDEX_NAME',
+  appId: 'YOUR_APP_ID',
+  apiKey: 'YOUR_SEARCH_API_KEY',
+  assistantId: 'YOUR_ASSISTANT_ID',
+});
+```
+
+## Documentation
+
+[Read documentation →](https://docsearch.algolia.com)

package/dist/esm/index.d.ts

@@ -0,0 +1,300 @@
+interface SidepanelShortcuts {
+    /**
+     * Enable/disable the Ctrl/Cmd+I shortcut to toggle the DocSearch sidepanel.
+     *
+     * @default true
+     */
+    'Ctrl/Cmd+I'?: boolean;
+}
+
+type DocSearchTheme = 'dark' | 'light';
+
+type AskAiSearchParameters = {
+    facetFilters?: string[];
+    filters?: string;
+    attributesToRetrieve?: string[];
+    restrictSearchableAttributes?: string[];
+    distinct?: boolean;
+};
+
+type AlgoliaLogoTranslations = Partial<{
+    poweredByText: string;
+}>;
+
+type ConversationScreenTranslations = Partial<{
+    /**
+     * Text shown as an LLM disclaimer.
+     */
+    conversationDisclaimer: string;
+    /**
+     * Text shown while assistant is reasoning.
+     */
+    reasoningText: string;
+    /**
+     * Text show while assistant is thinking.
+     */
+    thinkingText: string;
+    /**
+     * Text shown while assistant is preparing tool call.
+     */
+    preToolCallText: string;
+    /**
+     * Text shown while assistant is performing search tool call.
+     */
+    searchingText: string;
+    /**
+     * Text shown while assistant is finished performing tool call.
+     */
+    toolCallResultText: string;
+    /**
+     * Text shown describing related sources.
+     */
+    relatedSourcesText: string;
+    /**
+     * Message that's shown when user has stopped the streaming of a message.
+     */
+    stoppedStreamingText: string;
+    /**
+     * Text shown for copy button on code snippets.
+     **/
+    copyButtonText: string;
+    /**
+     * Message shown after clicking copy.
+     **/
+    copyButtonCopiedText: string;
+    /**
+     * Title for thumbs up feedback icon.
+     **/
+    likeButtonTitle: string;
+    /**
+     * Title for thumbs down feedback icon.
+     **/
+    dislikeButtonTitle: string;
+    /**
+     * Message displayed after feedback action.
+     **/
+    thanksForFeedbackText: string;
+}>;
+
+type NewConversationScreenTranslations = Partial<{
+    /**
+     * Title to be shown on the new conversation/starting screen.
+     **/
+    titleText: string;
+    /**
+     * Introduction text displayed on the new conversation/starting screen.
+     **/
+    introductionText: string;
+}>;
+
+type PromptFormTranslations = Partial<{
+    /**
+     * Initial placeholder for the prompt input.
+     **/
+    promptPlaceholderText: string;
+    /**
+     * Placeholder text for wile a conversation is streaming.
+     **/
+    promptAnsweringText: string;
+    /**
+     * Placeholder text for after a question has already been asked.
+     **/
+    promptAskAnotherQuestionText: string;
+    /**
+     * Disclaimer text displayed beneath the prompt form.
+     **/
+    promptDisclaimerText: string;
+    promptLabelText: string;
+    promptAriaLabelText: string;
+}>;
+
+type PanelVariant = 'floating' | 'inline';
+type PanelSide = 'left' | 'right';
+
+type HeaderTranslations = Partial<{
+    /**
+     * The main title text shown on the header.
+     **/
+    title: string;
+    /**
+     * The title text shown on the conversation history screen.
+     **/
+    conversationHistoryTitle: string;
+    /**
+     * The text shown on the start a conversation button.
+     **/
+    newConversationText: string;
+    /**
+     * The text shown on the view conversation history button.
+     **/
+    viewConversationHistoryText: string;
+}>;
+
+type SidepanelTranslations = Partial<{
+    /**
+     * Translation texts for the Sidepanel header.
+     **/
+    header: HeaderTranslations;
+    /**
+     * Translation texts for the prompt form.
+     **/
+    promptForm: PromptFormTranslations;
+    /**
+     * Translation texts for the conversation screen.
+     **/
+    conversationScreen: ConversationScreenTranslations;
+    /**
+     * Translation texts for the new conversation/starting screen.
+     **/
+    newConversationScreen: NewConversationScreenTranslations;
+    /**
+     * Translation text for the Algolia logo.
+     **/
+    logo: AlgoliaLogoTranslations;
+}>;
+type SidepanelProps$1 = {
+    /**
+     * Variant of the Sidepanel positioning.
+     *
+     * - `inline` pushes page content when opened
+     * - `floating` is positioned above all other content on page.
+     *
+     * @default 'floating'
+     */
+    variant?: PanelVariant;
+    /**
+     * Side of the page which the panel will originate from.
+     *
+     * @default 'right'
+     */
+    side?: PanelSide;
+    /**
+     * The selector of the element to push when Sidepanel opens with `inline` variant.
+     *
+     * @default `'#root, main, .app, body'`
+     */
+    pushSelector?: string;
+    /**
+     * Width of the Sidepanel (px or any CSS width).
+     *
+     * @default `360px`
+     **/
+    width?: number | string;
+    /**
+     * Width when expanded (px or any CSS width).
+     *
+     * @default `580px`
+     **/
+    expandedWidth?: number | string;
+    /**
+     * The container element where the panel should be portaled to.
+     *
+     * @default `document.body`
+     */
+    portalContainer?: DocumentFragment | Element | null;
+    /**
+     * Enables displaying suggested questions on new conversation screen.
+     *
+     * @default false
+     */
+    suggestedQuestions?: boolean;
+    /**
+     * Translations specific to the Sidepanel panel.
+     **/
+    translations?: SidepanelTranslations;
+    /**
+     * Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.
+     *
+     * @default `{ 'Ctrl/Cmd+I': true }`
+     */
+    keyboardShortcuts?: SidepanelShortcuts;
+};
+
+type SidepanelButtonTranslations = Partial<{
+    /**
+     * Text to be displayed when button has variant: `inline`.
+     *
+     * @default 'Ask AI'
+     **/
+    buttonText: string;
+    /**
+     * Aria label text for the button.
+     *
+     * @default 'Ask AI'
+     **/
+    buttonAriaLabel: string;
+}>;
+type ButtonVariant = 'floating' | 'inline';
+type SidepanelButtonProps = {
+    /**
+     * Variant of the button positioning and styling.
+     *
+     * - `inline` displays the button inline where rendered, with extra text
+     * - `floating` displays the button floating in bottom right of screen with just icon.
+     *
+     * @default 'floating'
+     **/
+    variant?: ButtonVariant;
+    /**
+     * Translations specific to the Sidepanel button.
+     **/
+    translations?: SidepanelButtonTranslations;
+    /**
+     * Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.
+     *
+     * @default `{ 'Ctrl/Cmd+I': true }`
+     */
+    keyboardShortcuts?: SidepanelShortcuts;
+};
+
+type DocSearchSidepanelProps = {
+    /**
+     * The assistant ID to use for the ask AI feature.
+     */
+    assistantId: string;
+    /**
+     * Public api key with search permissions for the index.
+     */
+    apiKey: string;
+    /**
+     * Algolia application id used by the search client.
+     */
+    appId: string;
+    /**
+     * The index name to use for the ask AI feature. Your assistant will search this index for relevant documents.
+     */
+    indexName: string;
+    /**
+     * The search parameters to use for the ask AI feature.
+     */
+    searchParameters?: AskAiSearchParameters;
+    /**
+     * Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.
+     *
+     * @default `{ 'Ctrl/Cmd+I': true }`
+     */
+    keyboardShortcuts?: SidepanelShortcuts;
+    /**
+     * Theme overrides applied to the Sidepanel button and panel.
+     *
+     * @default 'light'
+     */
+    theme?: DocSearchTheme;
+    /**
+     * Props specific to the Sidepanel button.
+     */
+    button?: Omit<SidepanelButtonProps, 'keyboardShortcuts'>;
+    /**
+     * Props specific to the Sidepanel panel.
+     */
+    panel?: Omit<SidepanelProps$1, 'keyboardShortcuts'>;
+};
+
+type SidepanelProps = DocSearchSidepanelProps & {
+    container: HTMLElement | string;
+    environment?: typeof window;
+};
+declare function sidepanel(props: SidepanelProps): () => void;
+
+export { sidepanel as default };
+export type { SidepanelProps };