@singlebase/elements 0.3.0 → 0.6.0

package/dist/elements/chat.d.ts

@@ -0,0 +1,455 @@
+import { LitElement, type PropertyValues, type TemplateResult } from "lit";
+import { type SinglebaseChatMessages } from "../chat-messages.js";
+import { type Block, type ChatFormat } from "../utils/markdown.js";
+export type ChatMode = "chat" | "rag";
+export type ChatEmbed = "page" | "inline" | "launcher";
+export type ChatGlow = "subtle" | "vivid" | "off";
+export type ChatExportFormat = "md" | "txt" | "json" | "copy";
+/** `auto` docks when there's room; `none` removes the list and its toggle. */
+export type ChatSidebar = "auto" | "open" | "closed" | "none";
+/** What the chat needs from a client: `llm.call`, and nothing else. */
+export type ChatClient = {
+    llm: {
+        call<T = unknown>(method: string, payload?: unknown, options?: {
+            signal?: AbortSignal;
+        }): Promise<T>;
+    };
+};
+/** A row of `llm.list_chats`. */
+export interface ChatSummary {
+    _id: string;
+    title: string | null;
+    bookmarked?: boolean;
+    message_count?: number;
+    _created_at?: string;
+    _modified_at?: string;
+}
+/** A text file attached to one message, sent to the model as retrieval. */
+export interface ChatAttachment {
+    name: string;
+    size: number;
+    content: string;
+}
+export interface ChatMessage {
+    /** Local identity, stable across renders. */
+    key: string;
+    /** The server's message id, once known. Bookmark and delete need it. */
+    id: string | null;
+    role: "user" | "assistant";
+    /** The text. For replies, the FOLLOWUPS tail is already split off. */
+    content: string;
+    at: number;
+    bookmarked: boolean;
+    /** Retrieved documents the reply used, as the server recorded them. */
+    sources: Record<string, unknown>[];
+    followups: string[];
+    phase: "pending" | "streaming" | "done" | "error";
+    error?: string;
+    stopped?: boolean;
+    feedback?: "up" | "down";
+    attachments?: ChatAttachment[];
+    execTime?: number;
+    model?: string;
+}
+/**
+ * Draws a fenced block the host knows about, e.g. ```order {"id":"A-1"}```.
+ * Return a Lit template, a DOM node or text; return null to fall back to code.
+ */
+export type ChatBlockRenderer = (source: string, context: {
+    lang: string;
+    message: ChatMessage;
+}) => unknown;
+/**
+ * Runs before each message is sent. Return the payload (changed or not), a new
+ * payload, or `false` to cancel. Anything else stops the send.
+ */
+export type ChatBeforeSend = (payload: Record<string, unknown>, context: {
+    chatId: string | null;
+    isNew: boolean;
+    message: ChatMessage;
+}) => Record<string, unknown> | false | Promise<Record<string, unknown> | false>;
+/** Runs after a reply is parsed. Return the blocks to draw. */
+export type ChatAfterParse = (blocks: Block[], context: {
+    message: ChatMessage;
+    format: ChatFormat;
+}) => Block[];
+export interface ChatPrompt {
+    label?: string;
+    text: string;
+}
+/** Every setting in one object, keyed by property name. */
+export interface ChatConfig {
+    /** The client to chat with. Defaults to the page's SinglebaseClient(). */
+    client: ChatClient | null;
+    /** Opens this saved chat. */
+    chatId: string;
+    embed: ChatEmbed;
+    mode: ChatMode;
+    format: ChatFormat;
+    renderers: Record<string, ChatBlockRenderer>;
+    beforeSend: ChatBeforeSend | null;
+    afterParse: ChatAfterParse | null;
+    glow: ChatGlow;
+    position: "right" | "left";
+    sidebar: ChatSidebar;
+    showTitle: boolean;
+    assistantName: string;
+    logoUrl: string;
+    heading: string;
+    description: string;
+    eyebrow: string;
+    prompts: string | (string | ChatPrompt)[];
+    bubbleText: string;
+    greetingBubble: boolean;
+    unreadBadge: boolean;
+    allowUpload: boolean;
+    allowExport: boolean;
+    allowRaw: boolean;
+    allowCopy: boolean;
+    allowRegenerate: boolean;
+    allowBookmark: boolean;
+    allowDelete: boolean;
+    allowRename: boolean;
+    allowFeedback: boolean;
+    showTime: boolean;
+    showComposer: boolean;
+    footnote: string;
+    brandingText: string;
+    brandingUrl: string;
+    branding: boolean;
+    followups: boolean;
+    showFollowups: boolean;
+    showSources: boolean;
+    showNewChat: boolean;
+    showBookmarked: boolean;
+    allowSearch: boolean;
+    autoTitle: boolean;
+    model: string;
+    params: Record<string, unknown>;
+    systemMessage: string;
+    retrieval: Record<string, unknown>[];
+    metadata: Record<string, unknown>;
+    messages: Partial<SinglebaseChatMessages>;
+    theme: "light" | "dark";
+    radius: "sharp" | "default" | "round";
+}
+/** A readable view of whatever shape the server recorded for a source. */
+export declare function describeSource(source: Record<string, unknown>, n: number): {
+    n: number;
+    title: string;
+    path: string;
+    collection: string;
+    updated: string;
+    text: string;
+    score: number | null;
+};
+/**
+ * An AI chat workspace backed by the `llm.*` service.
+ *
+ *   <singlebase-chat></singlebase-chat>
+ *   <singlebase-chat embed="inline" mode="rag" retrieval='[{"type":"kdb","namespace":"docs"}]'></singlebase-chat>
+ *   <singlebase-chat embed="launcher" greeting-bubble unread-badge></singlebase-chat>
+ *
+ * Conversations live on the server, scoped to the signed-in user: the list
+ * comes from `llm.list_chats`, a thread from `llm.get_chat`, and each turn is
+ * one `llm.chat`. Titles and follow-up questions never add turns to the
+ * conversation — titles come from `llm.generate`, follow-ups from the reply.
+ */
+export declare class SinglebaseChat extends LitElement {
+    static styles: import("lit").CSSResult[];
+    /** An explicit client. Omit it and the page's SinglebaseClient() is used. */
+    accessor client: ChatClient | null;
+    accessor messages: Partial<SinglebaseChatMessages>;
+    accessor theme: "light" | "dark" | undefined;
+    /** Corner preset for this element: `sharp`, `default` or `round`. */
+    accessor radius: "sharp" | "default" | "round" | undefined;
+    /** `chat` free-form, `rag` grounded with citations, `rich` charts and tables. */
+    accessor mode: ChatMode;
+    /**
+     * How much of a reply is formatted: `raw` (the text as written), `plain`
+     * (light formatting), `advanced` (+ tables, CSV, JSON and SVG) or `rich`
+     * (+ callouts, charts, images and `renderers`). Copy and export always use
+     * the original text.
+     */
+    accessor format: ChatFormat;
+    /** Your own fenced blocks, by language. Drawn at the `rich` level. */
+    accessor renderers: Record<string, ChatBlockRenderer>;
+    /**
+     * Preflight for every message: gets the `llm.chat` payload, returns it
+     * (changed or not), or `false` to cancel. May be async.
+     */
+    accessor beforeSend: ChatBeforeSend | null;
+    /** Rewrites a reply's parsed blocks before they're drawn. Returns the blocks. */
+    accessor afterParse: ChatAfterParse | null;
+    accessor glow: ChatGlow;
+    /** Ask the model for follow-up questions with each reply. */
+    accessor followups: boolean;
+    /** The "Cited sources" cards and the "Searched n sources" row under answers. */
+    accessor showSources: boolean;
+    /** The New chat button. */
+    accessor showNewChat: boolean;
+    /** The pinned "Bookmarked" group in the chat list. */
+    accessor showBookmarked: boolean;
+    /** Show the follow-up questions under the latest reply. */
+    accessor showFollowups: boolean;
+    /** The search box in the chat list. */
+    accessor allowSearch: boolean;
+    /** Replace the provisional title with a model-written one after the first reply. */
+    accessor autoTitle: boolean;
+    /** Model for new turns; empty uses the chat's, then the project default. */
+    accessor model: string;
+    accessor params: Record<string, unknown>;
+    /** Extra instructions, sent when a chat is created. */
+    accessor systemMessage: string;
+    /** Retrieval sources sent with every turn: `[{"type":"kdb","namespace":"docs"}]`. */
+    accessor retrieval: Record<string, unknown>[];
+    /** Stored on each user message. Never sent to the model. */
+    accessor metadata: Record<string, unknown>;
+    accessor embed: ChatEmbed;
+    /** Launcher side. */
+    accessor position: "right" | "left";
+    /**
+     * The chat list: `auto` docks it when there's room, `open` / `closed` set
+     * how it starts, `none` removes it and its toggle entirely.
+     */
+    accessor sidebar: ChatSidebar;
+    accessor showTitle: boolean;
+    /** Opens this chat on load. */
+    accessor chatIdAttr: string;
+    /** Used in placeholders, exports and labels. Never shown above messages. */
+    accessor assistantName: string;
+    accessor logoUrl: string;
+    accessor heading: string;
+    accessor description: string;
+    /** The small label above the heading. Unset uses the mode's; `""` hides it. */
+    accessor eyebrow: string | undefined;
+    /**
+     * Suggested prompts: `|`-separated in markup, an array in JavaScript.
+     * `"none"` or `[]` shows no suggestions.
+     */
+    accessor prompts: string | (string | ChatPrompt)[];
+    accessor bubbleText: string;
+    accessor greetingBubble: boolean;
+    accessor unreadBadge: boolean;
+    accessor allowUpload: boolean;
+    accessor allowExport: boolean;
+    /** Copy buttons on messages. */
+    accessor allowCopy: boolean;
+    /** Regenerate on the latest reply. */
+    accessor allowRegenerate: boolean;
+    /** Bookmark buttons for chats and messages. */
+    accessor allowBookmark: boolean;
+    /** Delete buttons for chats and messages. */
+    accessor allowDelete: boolean;
+    /** Renaming a chat from its title or the chat list. */
+    accessor allowRename: boolean;
+    /** The helpful / not helpful buttons on replies. */
+    accessor allowFeedback: boolean;
+    /**
+     * The message box. Off, the chat only shows the conversation — pair it with
+     * `chat-id` to display a saved chat read-only.
+     */
+    accessor showComposer: boolean;
+    /** Message times in the toolbars. */
+    accessor showTime: boolean;
+    /**
+     * The line under the composer. Unset uses the default ("{name} can make
+     * mistakes…"); an empty string hides it.
+     */
+    accessor footnote: string | undefined;
+    /** A per-reply toggle between the formatted answer and the text as written. */
+    accessor allowRaw: boolean;
+    /** The "Chat by Singlebase" credit. A plain link — it makes no request. */
+    accessor branding: boolean;
+    /** The credit's text. Empty uses the element's default ("… by Singlebase"). */
+    accessor brandingText: string;
+    /** Where the credit links to. Only http(s); anything else uses singlebase.cloud. */
+    accessor brandingUrl: string;
+    private accessor chatList;
+    private accessor listState;
+    private accessor activeId;
+    private accessor chatTitle;
+    private accessor bookmarked;
+    private accessor msgs;
+    private accessor loadingThread;
+    private accessor threadError;
+    private accessor busy;
+    private accessor draft;
+    private accessor files;
+    private accessor search;
+    private accessor sidebarOpen;
+    private accessor width;
+    private accessor panel;
+    private accessor menuOpen;
+    private accessor editingKey;
+    private accessor editDraft;
+    private accessor editingTitle;
+    private accessor renamingId;
+    private accessor toast;
+    private accessor copiedKey;
+    private accessor retrievalOpen;
+    private accessor rawKeys;
+    private accessor hasSidebarContent;
+    private accessor sorts;
+    private accessor arrivedKey;
+    private accessor dragging;
+    private accessor showJump;
+    private accessor offline;
+    private accessor isOpen;
+    private accessor expanded;
+    private accessor bubble;
+    private accessor seen;
+    private accessor mobile;
+    private run;
+    private abort;
+    private revealTimer;
+    private timers;
+    private toastTimer;
+    private stick;
+    private renamed;
+    private observer;
+    private observed;
+    private media;
+    private focusNext;
+    private bubbleScheduled;
+    private pendingChatId;
+    get msg(): SinglebaseChatMessages;
+    /** An explicit `.client`, else the page default. */
+    get resolvedClient(): ChatClient | null;
+    /** The open conversation's id, or null for a new chat. */
+    get chatId(): string | null;
+    /** The open conversation's messages. */
+    get thread(): readonly ChatMessage[];
+    /** `format`, falling back to the default for anything unknown. */
+    private get formatLevel();
+    /** The loaded chat list. */
+    get chats(): readonly ChatSummary[];
+    /**
+     * Every setting in one object, keyed by property name:
+     *
+     *     chat.config = { client, mode: "rag", format: "rich", retrieval: [...], chatId: "…" };
+     *
+     * Unknown keys are ignored. `chatId` opens that chat; reading `config`
+     * returns the current settings with `chatId` as the open chat.
+     */
+    set config(value: Partial<ChatConfig>);
+    /**
+     * Changes settings on the fly. Only the keys you pass change; the chat keeps
+     * its conversation and re-renders in place. Returns the element, so calls chain.
+     *
+     *     chat.configure({ format: "rich" }).configure({ theme: "dark" });
+     */
+    configure(options: Partial<ChatConfig>): this;
+    get config(): Partial<ChatConfig>;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changed: PropertyValues<this>): void;
+    firstUpdated(): void;
+    updated(): void;
+    private onNetwork;
+    private onMedia;
+    private later;
+    private emit;
+    private get docked();
+    private get panelDocked();
+    /** Starts a new, empty conversation. */
+    newChat(): void;
+    /** Opens a saved conversation. */
+    openChat(id: string): Promise<void>;
+    /** Sends a message; with no argument, sends the composer's text. */
+    send(text?: string): Promise<void>;
+    /** Stops waiting for, or revealing, the current reply. */
+    stop(): void;
+    /** Downloads the open conversation, or copies it as Markdown. */
+    exportChat(format?: ChatExportFormat): void;
+    /** Inline and launcher: fill the window. */
+    expand(): void;
+    collapse(): void;
+    /** Launcher: open the panel. */
+    open(): void;
+    /** Launcher: close the panel. */
+    close(): void;
+    private userMessage;
+    private systemPrompt;
+    private payloadFor;
+    private runTurn;
+    private failTurn;
+    /**
+     * The service answers in one piece; this reveals it progressively so it
+     * reads like a stream. Capped at about a second and a half.
+     */
+    private reveal;
+    /** Cancels any request or reveal in flight. */
+    private halt;
+    private retitle;
+    private applyTitle;
+    /**
+     * Enter and blur both land here. Saving on Enter directly (not via blur())
+     * matters: blur never fires on an input that doesn't have focus.
+     */
+    private commitTitle;
+    private commitRename;
+    private renameChat;
+    private fromServer;
+    private loadChats;
+    private upsertChat;
+    private touchChat;
+    private resetViewState;
+    private deleteOnServer;
+    private regenerate;
+    private retry;
+    private saveEdit;
+    private toggleRaw;
+    private copy;
+    private toggleMessageBookmark;
+    private toggleChatBookmark;
+    /** Removed at once; the server call waits out the undo window. */
+    private deleteMessage;
+    private deleteChat;
+    private feedback;
+    private showToast;
+    /** Ends the current toast, committing whatever it was holding back. */
+    private flushToast;
+    private undo;
+    private addFiles;
+    private scrollToBottom;
+    private onScroll;
+    private jumpToLatest;
+    private onKeydown;
+    private onComposerKey;
+    private onComposerInput;
+    private onDragEnter;
+    private onDragLeave;
+    private onDrop;
+    render(): TemplateResult<1>;
+    private renderLauncher;
+    private renderWorkspace;
+    private renderSidebar;
+    private renderThreadRow;
+    private renderHeader;
+    private renderExportMenu;
+    /** The suggestion cards. `[]` or `"none"` shows none; unset uses the mode's. */
+    private promptList;
+    private renderWelcome;
+    private renderThread;
+    private renderUser;
+    private pillLabel;
+    private renderBot;
+    private renderAnswer;
+    private renderInline;
+    private renderBlock;
+    private renderList;
+    private renderCode;
+    /** A host renderer for this language, at the rich level only. */
+    private renderCustom;
+    private renderTable;
+    private renderJsonBlock;
+    private renderChart;
+    private renderPanel;
+    private renderComposer;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "singlebase-chat": SinglebaseChat;
+    }
+}

package/dist/elements/uploader.d.ts

@@ -50,6 +50,8 @@ export interface UploaderConfig {
     allowRename: boolean;
     autoUpload: boolean;
     branding: boolean;
+    brandingText: string;
+    brandingUrl: string;
     logoUrl: string;
     logoText: string;
     heading: string;
@@ -67,6 +69,7 @@ export interface UploaderConfig {
     messages: Partial<SinglebaseUploadMessages>;
     theme: "light" | "dark";
     density: "comfortable" | "compact";
+    radius: "sharp" | "default" | "round";
     onComplete: SinglebaseUploader["onComplete"];
     onError: SinglebaseUploader["onError"];
 }
@@ -93,6 +96,8 @@ export declare class SinglebaseUploader extends LitElement {
     accessor messages: Partial<SinglebaseUploadMessages>;
     accessor theme: "light" | "dark" | undefined;
     accessor density: "comfortable" | "compact" | undefined;
+    /** Corner preset for this element: `sharp`, `default` or `round`. */
+    accessor radius: "sharp" | "default" | "round" | undefined;
     /**
      * `full` is the card with a dropzone and a reviewable list, `compact` the
      * one-line attachments row, `button` a single control that uploads as soon
@@ -107,6 +112,10 @@ export declare class SinglebaseUploader extends LitElement {
     accessor autoUpload: boolean;
     /** The "Files by Singlebase" credit. A plain link — it makes no request. */
     accessor branding: boolean;
+    /** The credit's text. Empty uses the element's default ("… by Singlebase"). */
+    accessor brandingText: string;
+    /** Where the credit links to. Only http(s); anything else uses singlebase.cloud. */
+    accessor brandingUrl: string;
     accessor logoUrl: string;
     accessor logoText: string;
     accessor heading: string;
@@ -168,6 +177,11 @@ export declare class SinglebaseUploader extends LitElement {
      * Unknown keys are ignored. Reading it returns the current settings.
      */
     set config(value: Partial<UploaderConfig>);
+    /**
+     * Changes settings on the fly. Only the keys you pass change; staged files
+     * stay. Returns the element, so calls chain.
+     */
+    configure(options: Partial<UploaderConfig>): this;
     get config(): Partial<UploaderConfig>;
     /** Drops every staged file and any notice. */
     clear(): void;