@smarter.sh/ui-chat 0.7.1 → 0.9.0

package/dist/types/src/components/DocsDialog/Component.d.ts

@@ -0,0 +1,8 @@
+import { type DocSection } from "@/components/DocsDialog/data";
+import "@/components/DocsDialog/styles.css";
+interface DocsDialogProps {
+    onClose: () => void;
+    sections?: DocSection[];
+}
+declare function DocsDialog({ onClose, sections }: DocsDialogProps): import("react").JSX.Element;
+export default DocsDialog;

package/dist/types/src/components/DocsDialog/data.d.ts

@@ -0,0 +1,18 @@
+/** A technical reference that the Docs dialog links to. */
+export interface DocLink {
+    title: string;
+    url: string;
+    description: string;
+}
+/** A tab of the Docs dialog: the technical references for one audience. */
+export interface DocSection {
+    title: string;
+    description: string;
+    links: DocLink[];
+}
+/** The technical references for prompt engineers, who build LLMClients in the sandbox. */
+export declare const PROMPT_ENGINEER_LINKS: DocLink[];
+/** The technical references for software engineers, who build the applications that host them. */
+export declare const SOFTWARE_ENGINEER_LINKS: DocLink[];
+/** The tabs of the Docs dialog, from left to right. The first one is selected when it opens. */
+export declare const DOC_SECTIONS: DocSection[];

package/dist/types/src/components/DocsDialog/index.d.ts

@@ -0,0 +1,2 @@
+import DocsDialog from "@/components/DocsDialog/Component";
+export default DocsDialog;

package/dist/types/src/components/SmarterChat/Component.d.ts

@@ -12,9 +12,13 @@
  * The user can resize the chat and the Console by dragging the separator between them, and can
  * hide the Console, which slides out to the right. In sandbox mode, the thread also displays
  * Smarter's system, tool and meta data messages. In production mode, it displays only the
- * conversation, as the LLMClient's users see it. The Console's server logs follow the mode: DEBUG
+ * conversation, as the LLMClient's users see it, and the Console and its toggle button are hidden. The Console's server logs follow the mode: DEBUG
  * and above in sandbox mode, and the server's own log level in production mode. A new chat also
- * clears the Console's server logs.
+ * clears the Console's server logs. Sandbox mode also has a Docs button, which opens a dialog of
+ * links to the technical references for prompt engineers and software engineers.
+ *
+ * The LLMClient's styles (its manifest's spec.config.styles) set its logo, which is displayed in
+ * the header, its avatars, its background image, its fonts and its colors. See lib/styles.ts.
  *
  * This is the component that the @smarter.sh/ui-chat npm package exports, and that the Smarter web
  * console's LLMClient prompt workbench renders. See main.tsx.
@@ -22,5 +26,5 @@
 import "@chatscope/chat-ui-kit-styles/dist/default/styles.min.css";
 import type { SmarterChatProps } from "@/types";
 import "@/components/SmarterChat/styles.css";
-declare function SmarterChat({ apiUrl, apiKey, toggleMetadata, csrfCookieName, csrftoken, debugCookieName, debugCookieExpiration, debugMode, sessionCookieName, sessionCookieExpiration, showConsole, cookieDomain, smarterRequestId, logStreamUrl, streamProgress, }: SmarterChatProps): import("react").JSX.Element;
+declare function SmarterChat({ apiUrl, apiKey, toggleMetadata, csrfCookieName, csrftoken, debugCookieName, debugCookieExpiration, debugMode, sessionCookieName, sessionCookieExpiration, cookiePath, showConsole, cookieDomain, smarterRequestId, logStreamUrl, streamProgress, }: SmarterChatProps): import("react").JSX.Element;
 export default SmarterChat;

package/dist/types/src/components/SmarterChat/icons.d.ts

@@ -15,3 +15,5 @@ export declare function ConsoleIcon({ visible }: {
 export declare function SandboxIcon(): import("react").JSX.Element;
 /** A shield: production mode, which displays the conversation only, as its users see it. (bi-shield-check) */
 export declare function ProductionIcon(): import("react").JSX.Element;
+/** An open book: the Docs dialog, which links to the technical references. (bi-book) */
+export declare function DocsIcon(): import("react").JSX.Element;

package/dist/types/src/contract.gen.d.ts

@@ -59,6 +59,10 @@ export interface PromptChatApiChatbotV1 {
     id: number;
     name: string;
     provider?: string | null;
+    /**
+     * The look of the chat: the manifest's spec.config.styles, with snake_case keys.
+     */
+    styles?: PromptChatApiStyles | null;
     /**
      * The url of the LLMClient's prompt api.
      */
@@ -66,6 +70,54 @@ export interface PromptChatApiChatbotV1 {
     version?: string | null;
     [k: string]: unknown;
 }
+/**
+ * The look of the LLMClient's chat: its manifest's ``spec.config.styles``, with snake_case keys.
+ *
+ * Smarter Chat applies it as css custom properties. Every setting is optional, and one that is
+ * left out keeps the chat's default.
+ *
+ * This interface was referenced by `SmarterChatAPIContract`'s JSON-Schema
+ * via the `definition` "PromptChatApiStyles".
+ */
+export interface PromptChatApiStyles {
+    app_background_image_size?: ("cover" | "contain" | "auto") | null;
+    app_background_image_url?: string | null;
+    app_logo_url?: string | null;
+    assistant_avatar_url?: string | null;
+    border_radius?: string | null;
+    buttons?: PromptChatApiStyleSection | null;
+    conversation_header?: PromptChatApiStyleSection | null;
+    font_family?: string | null;
+    font_size?: string | null;
+    google_font?: string | null;
+    incoming_message?: PromptChatApiStyleSection | null;
+    main_container?: PromptChatApiStyleSection | null;
+    message_input?: PromptChatApiStyleSection | null;
+    message_list?: PromptChatApiStyleSection | null;
+    outgoing_message?: PromptChatApiStyleSection | null;
+    typing_indicator?: PromptChatApiStyleSection | null;
+    user_avatar_url?: string | null;
+    [k: string]: unknown;
+}
+/**
+ * A section of the LLMClient's styles: the colors of one of chatscope's components.
+ *
+ * A section has only the settings that its component has, in the manifest's
+ * ``spec.config.styles``. See :mod:`smarter.apps.llmclient.manifest.models.llmclient.styles`.
+ *
+ * This interface was referenced by `SmarterChatAPIContract`'s JSON-Schema
+ * via the `definition` "PromptChatApiStyleSection".
+ */
+export interface PromptChatApiStyleSection {
+    background_color?: string | null;
+    border_color?: string | null;
+    color?: string | null;
+    editor_background_color?: string | null;
+    info_color?: string | null;
+    link_color?: string | null;
+    placeholder_color?: string | null;
+    [k: string]: unknown;
+}
 /**
  * A choice of a chat completion.
  *
@@ -555,6 +607,10 @@ export interface PromptChatApiLLMClient {
     id: number;
     name: string;
     provider?: string | null;
+    /**
+     * The look of the chat: the manifest's spec.config.styles, with snake_case keys.
+     */
+    styles?: PromptChatApiStyles | null;
     /**
      * The url of the LLMClient's prompt api.
      */

package/dist/types/src/embed/EmbedApp.d.ts

@@ -0,0 +1,10 @@
+import type { EmbedOptions } from "./options";
+export declare const PANEL_ID = "smarter-chat-embed-panel";
+export interface EmbedAppProps {
+    options: EmbedOptions;
+    /** Whether the launcher is open. The element owns this state, so that page scripts can open and close it. */
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+declare function EmbedApp(props: EmbedAppProps): import("react").JSX.Element;
+export default EmbedApp;

package/dist/types/src/embed/assets.d.ts

@@ -0,0 +1,7 @@
+export declare const CDN_BASE_URL: string;
+/** The url of the directory of a script, or of jsDelivr's copy of the package, if it has no url. */
+export declare function scriptBaseUrl(script: Element | null | undefined): string;
+/** Remembers the directory of the running script. Called once, by index.ts, when the script first runs. */
+export declare function captureBaseUrl(script?: Element | null | undefined): string;
+/** The url of one of the embed script's files, e.g. assetUrl("mermaid/mermaid.js"). */
+export declare function assetUrl(path: string): string;

package/dist/types/src/embed/autoMount.d.ts

@@ -0,0 +1,18 @@
+/** The attribute that marks the elements that the script added, with their chatbot's url. */
+export declare const AUTO_ATTRIBUTE = "data-smarter-chat-auto";
+export type EmbedConfig = Record<string, unknown>;
+declare global {
+    interface Window {
+        SmarterChatConfig?: EmbedConfig | EmbedConfig[];
+    }
+}
+/** The configurations of the script tag's data- attributes and of window.SmarterChatConfig, as attributes. */
+export declare function configurations(script: Element | null | undefined, globalConfig: EmbedConfig | EmbedConfig[] | null | undefined): Record<string, string>[];
+/**
+ * Adds a <smarter-chat> element for a configuration, unless the page has one for its chatbot already.
+ *
+ * @returns The new element, or null if none was added.
+ */
+export declare function mountChat(attributes: Record<string, string>, doc?: Document): HTMLElement | null;
+/** Adds the configurations' elements once the page's body exists. */
+export declare function autoMount(script: Element | null | undefined, globalConfig: EmbedConfig | EmbedConfig[] | null | undefined, doc?: Document): void;

package/dist/types/src/embed/css.d.ts

@@ -0,0 +1,15 @@
+export declare const ASSETS_PLACEHOLDER = "__SMARTER_CHAT_ASSETS__/";
+export declare const FONT_STYLE_ID = "smarter-chat-embed-fonts";
+/** Adds css to the embed's stylesheet. Called by the modules that the embed build generates for css imports. */
+export declare function addCss(css: string): void;
+/** The embed's css, with the urls of its own files. */
+export declare function embedCss(): string;
+/** The @font-face rules of a stylesheet. */
+export declare function fontFaceRules(css: string): string[];
+/** Adds the @font-face rules of the css to the document's head, once. */
+export declare function hoistFontFaces(css: string, doc?: Document): void;
+/**
+ * Applies the css to a shadow root: as a constructable stylesheet, shared by every chat on the page, where the
+ * browser supports them, or else as a style element.
+ */
+export declare function applyCss(root: ShadowRoot, css: string): void;

package/dist/types/src/embed/element.d.ts

@@ -0,0 +1,19 @@
+import { type EmbedOptionsResult } from "./options";
+export declare const ELEMENT_NAME = "smarter-chat";
+export declare const TOGGLE_EVENT = "smarter-chat-toggle";
+export declare class SmarterChatElement extends HTMLElement {
+    #private;
+    static observedAttributes: ("chatbot" | "color" | "label" | "open" | "debug" | "width" | "height" | "position" | "api-key" | "mode" | "z-index" | "session-cookie-name" | "cookie-path" | "stream-progress")[];
+    /** The element's options, from its attributes. */
+    get options(): EmbedOptionsResult;
+    /** Whether the launcher is open. */
+    get isOpen(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    open(): void;
+    close(): void;
+    toggle(): void;
+}
+/** Defines <smarter-chat>, unless the page already has, e.g. with another copy of the embed script. */
+export declare function defineElement(registry?: CustomElementRegistry): void;

package/dist/types/src/embed/index.d.ts

@@ -0,0 +1,17 @@
+import { type EmbedConfig } from "./autoMount";
+import "./styles.css";
+/** The api of window.SmarterChat. */
+export interface SmarterChatEmbedApi {
+    version: string;
+    /** Opens the launchers, or the launcher of one chatbot, by its url. */
+    open: (chatbot?: string) => void;
+    close: (chatbot?: string) => void;
+    toggle: (chatbot?: string) => void;
+    /** Adds a chat to the page, as window.SmarterChatConfig does. */
+    mount: (config: EmbedConfig) => HTMLElement | null;
+}
+declare global {
+    interface Window {
+        SmarterChat?: SmarterChatEmbedApi;
+    }
+}

package/dist/types/src/embed/mermaid.d.ts

@@ -0,0 +1,2 @@
+/** The entry point of the embed script's separate build of mermaid, embed/mermaid/mermaid.js. See vite.config.ts. */
+export { default } from "mermaid";

package/dist/types/src/embed/mermaidImport.d.ts

@@ -0,0 +1 @@
+export declare const importMermaid: () => Promise<typeof import("mermaid")>;

package/dist/types/src/embed/options.d.ts

@@ -0,0 +1,69 @@
+export type EmbedMode = "launcher" | "inline";
+export type EmbedPosition = "bottom-right" | "bottom-left";
+export interface EmbedOptions {
+    /** The url of the deployed LLMClient, e.g. https://support.3141-5926-5359.api.example.com/ */
+    chatbot: string;
+    /** A Smarter api key, for LLMClients that require one. It is public, as is everything in a web page. */
+    apiKey: string | null;
+    /** "launcher": a button in a corner of the page that opens the chat. "inline": the chat, in the page. */
+    mode: EmbedMode;
+    /** The launcher's corner. */
+    position: EmbedPosition;
+    /** Whether the launcher starts open. */
+    open: boolean;
+    /** The launcher's accessible name, and the chat panel's. */
+    label: string;
+    /** The launcher button's background color. */
+    color: string;
+    /** The width of the inline chat, or of the launcher's panel. */
+    width: string;
+    /** The height of the inline chat, or of the launcher's panel. */
+    height: string;
+    /** The launcher's z-index. */
+    zIndex: number;
+    /** The cookie in which the chat saves its session's key. */
+    sessionCookieName: string;
+    /** The path of the chat's cookies. "/" keeps one chat session across the website. */
+    cookiePath: string;
+    /** Display a running prompt's progress. */
+    streamProgress: boolean;
+    /** Log to the browser console. */
+    debug: boolean;
+}
+/** The result of reading the options: the options, or why they can't be used. */
+export type EmbedOptionsResult = {
+    options: EmbedOptions;
+    error: null;
+} | {
+    options: null;
+    error: string;
+};
+/** The attributes that a <smarter-chat> element reads, in kebab-case. */
+export declare const OPTION_ATTRIBUTES: readonly ["chatbot", "api-key", "mode", "position", "open", "label", "color", "width", "height", "z-index", "session-cookie-name", "cookie-path", "stream-progress", "debug"];
+export declare const DEFAULT_LABEL = "Chat";
+export declare const DEFAULT_COLOR = "#ff5733";
+export declare const DEFAULT_Z_INDEX = 2147483000;
+/** A boolean attribute: present and empty, or "true", is true. "false" is false. Missing is the default. */
+export declare function booleanOption(value: string | null | undefined, defaultValue: boolean): boolean;
+/** The url, if it is an http(s) url, normalized to end with a slash, else null. */
+export declare function chatbotUrl(value: string | null | undefined): string | null;
+/**
+ * The default session cookie of a chatbot: one per chatbot host, so that two chatbots on one website keep separate
+ * chat sessions, e.g. smarter_chat_support_3141_5926_5359_api_example_com.
+ */
+export declare function defaultSessionCookieName(chatbot: string): string;
+/**
+ * The options of a <smarter-chat> element.
+ *
+ * @param get Returns the value of an attribute, by its kebab-case name, or null if it is missing.
+ * @param defaultMode The mode, if the attributes don't say: "inline" for an element in the page, and "launcher"
+ *   for the element that the script tag adds.
+ */
+export declare function parseOptions(get: (name: (typeof OPTION_ATTRIBUTES)[number]) => string | null, defaultMode?: EmbedMode): EmbedOptionsResult;
+/** A camelCase name in kebab-case, e.g. apiKey to api-key. */
+export declare function kebabCase(name: string): string;
+/**
+ * The attributes of a configuration object, e.g. window.SmarterChatConfig's, or a script tag's dataset: kebab-case
+ * names, and string values. Values that are null, undefined, objects or functions are left out.
+ */
+export declare function configAttributes(config: Record<string, unknown>): Record<string, string>;

package/dist/types/src/lib/cookie.d.ts

@@ -1,7 +1,8 @@
 /**
  * Cookie management for Smarter Chat: the Django CSRF cookie, which it reads, and the chat
  * session and debug cookies, which it sets for the page's path, so that each LLMClient's
- * workbench has its own chat session.
+ * workbench has its own chat session, or for the path that the cookie names, e.g. "/" for a chat
+ * that follows the visitor across a website.
  */
 import type { CookieMeta } from "../types";
 /**
@@ -12,6 +13,6 @@ import type { CookieMeta } from "../types";
 export declare function inCookieDomain(hostname: string, domain: string | null | undefined): boolean;
 /** The cookie's value: its preset value, else the browser's cookie, else defaultValue. */
 export declare function getCookie(cookie: CookieMeta, defaultValue?: string | null): string | null;
-/** Sets the cookie for the page's path, or deletes it when value is empty. */
+/** Sets the cookie for its path (by default, the page's), or deletes it when value is empty. */
 export declare function setCookie(cookie: CookieMeta, value: string | boolean | null | undefined): void;
-export declare function cookieMetaFactory(name: string, expiration: number | null, domain: string | undefined, value?: string | null): CookieMeta;
+export declare function cookieMetaFactory(name: string, expiration: number | null, domain: string | undefined, value?: string | null, path?: string | null): CookieMeta;

package/dist/types/src/lib/mermaidImport.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Imports mermaid, which lib/mermaid.ts does the first time that a message has a diagram.
+ *
+ * In the npm package and the web console, the page's bundler splits mermaid into chunks, which are downloaded only
+ * then. The embed script, a single classic script, can't be split that way, so its build replaces this module with
+ * src/embed/mermaidImport.ts, which imports a separate build of mermaid from beside the script. See vite.config.ts.
+ */
+export declare const importMermaid: () => Promise<typeof import("mermaid")>;

package/dist/types/src/lib/styles.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The LLMClient's styles: its manifest's spec.config.styles, which the config api returns, with
+ * snake_case keys, as llmclient.styles.
+ *
+ * chatscope's theme (@chatscope/chat-ui-kit-styles) is compiled from scss variables, so its colors
+ * can't be changed at run time. Instead, the styles become css custom properties (variables) on the
+ * chat's root element, e.g. --smarter-chat-header-bg, which styles.css applies to chatscope's
+ * components, with chatscope's (or Smarter's) own value as the fallback. A setting that is left out
+ * changes nothing.
+ *
+ * The backend validates every value. They are checked again here, because a page may embed a chat
+ * from any Smarter platform: a value that isn't a plain css value is ignored.
+ */
+import { type CSSProperties } from "react";
+import type { Contract } from "@/types";
+export type ChatStyles = Contract.PromptChatApiStyles;
+export type ChatStyleSection = Contract.PromptChatApiStyleSection;
+/** The id of the stylesheet link of the LLMClient's Google font. */
+export declare const GOOGLE_FONT_LINK_ID = "smarter-chat-google-font";
+/** The value, if it is a plain css value. */
+export declare function safeCssValue(value: string | null | undefined): string | null;
+/** The url, if it is an https url that can be used in css' url(). */
+export declare function safeImageUrl(value: string | null | undefined): string | null;
+/** The url of the Google Fonts stylesheet of a font, or null if the name isn't a font's. */
+export declare function googleFontUrl(name: string | null | undefined): string | null;
+/** The font stack: fontFamily, or the Google font, or null for chatscope's. */
+export declare function fontFamily(styles: ChatStyles | null | undefined): string | null;
+/**
+ * The css variables of the styles, for the chat's root element's style.
+ *
+ * @param styles The LLMClient's styles, or nothing.
+ * @returns The variables, without those of the settings that are not set, or not valid.
+ */
+export declare function styleVariables(styles: ChatStyles | null | undefined): CSSProperties;
+/**
+ * Loads the Google font of the styles, once per page, with a stylesheet link in the page's head.
+ *
+ * @param name The font's name, from the Google Fonts catalog, or nothing.
+ */
+export declare function useGoogleFont(name: string | null | undefined): void;

package/dist/types/src/types.d.ts

@@ -54,6 +54,8 @@ export interface CookieMeta {
     domain: string;
     /** A value to use instead of the cookie's. */
     value: string | null;
+    /** The path that Smarter Chat sets the cookie for. Empty or missing means the page's path. */
+    path?: string | null;
 }
 export interface ChatCookies {
     csrfCookie: CookieMeta;
@@ -87,6 +89,11 @@ export interface SmarterChatProps {
     /** The name of the cookie in which Smarter Chat saves the chat session's key. */
     sessionCookieName?: string;
     sessionCookieExpiration?: number;
+    /**
+     * The path of the session and debug cookies. By default, the page's path, so that each page has its own chat
+     * session. "/" keeps one chat session as the visitor moves from page to page of a website.
+     */
+    cookiePath?: string | null;
     /** @deprecated Not used. Django's session cookie is sent with each request, as is. */
     authSessionCookieName?: string;
     /** Show the Console, which displays the chat's configuration and history. */