@hidemikimura/chit-ui 0.1.0

package/dist/types/render/content.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Which form a message uses. Also drives the `data-content` attribute, because
+ * plain text is the one form whose whitespace has to survive.
+ *
+ * @param {Message} message
+ * @returns {'text' | 'html' | 'template' | 'element' | 'component'}
+ */
+export function contentField(message: Message): "text" | "html" | "template" | "element" | "component";
+/**
+ * The value a message's content is built from. Used to decide whether a
+ * message actually changed, so `chat-message-render` does not fire on every
+ * unrelated update.
+ *
+ * @param {Message} message
+ * @returns {unknown}
+ */
+export function contentKey(message: Message): unknown;
+/**
+ * Build (or reuse) an element for a component reference and write its props.
+ *
+ * The instance is kept across renders so the component keeps its own state; a
+ * changed reference replaces it, and changed props are assigned one by one so
+ * the component's own setters see each change.
+ *
+ * @param {ChitUI} host
+ * @param {string} key                                       Cache key.
+ * @param {(new () => HTMLElement) | string} source
+ * @param {Record<string, unknown>} [props]
+ * @returns {HTMLElement}
+ */
+export function resolveComponent(host: ChitUI, key: string, source: (new () => HTMLElement) | string, props?: Record<string, unknown>): HTMLElement;
+/**
+ * Drop cached instances for messages that are gone, so a long conversation
+ * does not hold on to elements it will never show again. Non-message entries,
+ * such as the launcher's, are left alone.
+ *
+ * @param {ChitUI} host
+ * @param {Set<string>} liveIds
+ */
+export function pruneComponents(host: ChitUI, liveIds: Set<string>): void;
+/**
+ * The component instance backing a message, when it has one.
+ *
+ * @param {ChitUI} host
+ * @param {string} id
+ * @returns {HTMLElement | undefined}
+ */
+export function componentInstance(host: ChitUI, id: string): HTMLElement | undefined;
+/**
+ * Turn a message's content into something Lit can render as a child value.
+ *
+ * All four shapes collapse here: an HTML string becomes an `unsafeHTML`
+ * directive, a Lit template passes straight through, and an element or a
+ * component becomes a Node, which Lit inserts as-is.
+ *
+ * @param {ChitUI} host
+ * @param {Message} message
+ * @returns {unknown}
+ */
+export function renderContent(host: ChitUI, message: Message): unknown;
+/** The cache key for the closed-state component. */
+export const LAUNCHER_KEY: "launcher";
+export type ComponentEntry = {
+    /**
+     * What `component` held when this was built.
+     */
+    source: (new () => HTMLElement) | string;
+    element: HTMLElement;
+    /**
+     * Last props written to the element.
+     */
+    props: Record<string, unknown>;
+};
+import type { Message } from '../types.js';
+import type { ChitUI } from '../chit-ui.js';

package/dist/types/render/launcher.d.ts

@@ -0,0 +1,18 @@
+/** @import { ChitUI } from '../chit-ui.js' */
+/**
+ * The closed state: one button.
+ *
+ * What goes inside it has three routes, in order of how much the consumer
+ * takes over:
+ *
+ * - the theme's image or label, drawn inside the themed circle;
+ * - the `launcher` slot, their markup inside that same circle;
+ * - `closed.component`, a component that draws the whole launcher — the button
+ *   then keeps only its role, and gives up its size, background, shadow and
+ *   radius, because two parties styling one box is how things end up clipped.
+ *
+ * @param {ChitUI} host
+ * @returns {import('lit').TemplateResult}
+ */
+export function renderLauncher(host: ChitUI): import("lit").TemplateResult;
+import type { ChitUI } from '../chit-ui.js';

package/dist/types/render/message-list.d.ts

@@ -0,0 +1,17 @@
+/** @import { ChitUI } from '../chit-ui.js' */
+/**
+ * The scrolling conversation.
+ *
+ * `repeat` keys on the message id so an existing bubble's DOM is reused when
+ * the consumer assigns a new array; without it Lit would reorder by position
+ * and a component message would lose its state on every insert.
+ *
+ * Clicks are handled once here and re-published as `chat-message-click`, which
+ * is how a consumer reaches a button inside a message without hunting through
+ * the shadow root.
+ *
+ * @param {ChitUI} host
+ * @returns {import('lit').TemplateResult}
+ */
+export function renderMessageList(host: ChitUI): import("lit").TemplateResult;
+import type { ChitUI } from '../chit-ui.js';

package/dist/types/render/message.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One message.
+ *
+ * `system` messages are a centred line rather than a bubble: they are the
+ * widget talking about the conversation ("an operator joined"), not a party to
+ * it, so they get no avatar, no name and no timestamp.
+ *
+ * @param {ChitUI} host
+ * @param {Message} message
+ * @returns {import('lit').TemplateResult}
+ */
+export function renderMessage(host: ChitUI, message: Message): import("lit").TemplateResult;
+import type { ChitUI } from '../chit-ui.js';
+import type { Message } from '../types.js';

package/dist/types/render/panel.d.ts

@@ -0,0 +1,10 @@
+/** @import { ChitUI } from '../chit-ui.js' */
+/**
+ * The open state. Header and footer are slots; the message list and the
+ * composer arrive in later milestones and are placeholders for now.
+ *
+ * @param {ChitUI} host
+ * @returns {import('lit').TemplateResult}
+ */
+export function renderPanel(host: ChitUI): import("lit").TemplateResult;
+import type { ChitUI } from '../chit-ui.js';

package/dist/types/styles/adopted-sheet.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A stylesheet the component owns and rewrites at runtime, appended after the
+ * component's static styles so its declarations win over them.
+ */
+export class AdoptedSheet {
+    /** @param {string} marker  Identifies the sheet in the DOM when the fallback is used. */
+    constructor(marker: string);
+    /** @param {ShadowRoot | HTMLElement | DocumentFragment} root */
+    attach(root: ShadowRoot | HTMLElement | DocumentFragment): void;
+    /**
+     * Replace the sheet's contents. Cheap to call on every update: identical CSS
+     * is ignored.
+     *
+     * @param {string} css
+     * @param {ShadowRoot | HTMLElement | DocumentFragment} root
+     */
+    write(css: string, root: ShadowRoot | HTMLElement | DocumentFragment): void;
+    detach(): void;
+    #private;
+}

package/dist/types/styles/composer.css.d.ts

@@ -0,0 +1 @@
+export const composerStyles: import("lit").CSSResult;

package/dist/types/styles/content.css.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Everything that keeps arbitrary consumer HTML inside its bubble.
+ *
+ * The widget has no say over what goes in a message, so the containment is
+ * structural rather than a list of rules per element: the content box declares
+ * its own size, refuses to grow past the bubble, and contains its layout and
+ * paint so a stray position or margin cannot escape.
+ */
+export const contentStyles: import("lit").CSSResult;

package/dist/types/styles/host.css.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Host-level concerns: the coordinate space the widget lives in, the theme
+ * fallbacks, and the transition animations.
+ *
+ * Every custom property here is a fallback only. ThemeController writes the
+ * real values into an adopted stylesheet that sits ahead of this one, and page
+ * CSS (`chit-ui { --chit-color-accent: ... }`) beats both.
+ */
+export const hostStyles: import("lit").CSSResult;

package/dist/types/styles/launcher.css.d.ts

@@ -0,0 +1 @@
+export const launcherStyles: import("lit").CSSResult;

package/dist/types/styles/message.css.d.ts

@@ -0,0 +1 @@
+export const messageStyles: import("lit").CSSResult;

package/dist/types/styles/panel.css.d.ts

@@ -0,0 +1 @@
+export const panelStyles: import("lit").CSSResult;

package/dist/types/theme/default-theme.d.ts

@@ -0,0 +1,97 @@
+export namespace defaultTheme {
+    let breakpoint: number;
+    let zIndex: number;
+    namespace font {
+        let family: string;
+        let size: number;
+    }
+    namespace closed {
+        export { CLOSED_PC as pc };
+        export let mobile: ResolvedClosed;
+    }
+    namespace open {
+        let width: number;
+        let height: number;
+        let position: "bottom-right";
+        namespace offset {
+            let x: number;
+            let y: number;
+        }
+        let radius: number;
+        let launcher: "hidden";
+        namespace header {
+            let title: null;
+            let logo: null;
+            let avatar: null;
+        }
+        namespace background {
+            let image: null;
+        }
+        namespace colors {
+            import background_1 = PALETTE.surface;
+            export { background_1 as background };
+            import text = PALETTE.ink;
+            export { text };
+            import accent = PALETTE.accent;
+            export { accent };
+            import border = PALETTE.line;
+            export { border };
+            export let shadow: string;
+            import headerBackground = PALETTE.surface;
+            export { headerBackground };
+            import headerText = PALETTE.ink;
+            export { headerText };
+            import userBubble = PALETTE.accent;
+            export { userBubble };
+            import userText = PALETTE.onAccent;
+            export { userText };
+            import assistantBubble = PALETTE.raised;
+            export { assistantBubble };
+            import assistantText = PALETTE.ink;
+            export { assistantText };
+            import systemText = PALETTE.muted;
+            export { systemText };
+            import inputBackground = PALETTE.surface;
+            export { inputBackground };
+            import inputText = PALETTE.ink;
+            export { inputText };
+            import inputPlaceholder = PALETTE.muted;
+            export { inputPlaceholder };
+        }
+        namespace animation {
+            let enter: "scale";
+            let exit: "fade";
+            let duration: number;
+            let scroll: "smooth";
+        }
+        namespace input {
+            let maxRows: number;
+            let placeholder: null;
+        }
+    }
+    namespace hidden {
+        export namespace animation_1 {
+            let exit_1: "fade";
+            export { exit_1 as exit };
+            let duration_1: number;
+            export { duration_1 as duration };
+        }
+        export { animation_1 as animation };
+    }
+}
+/** The measurements a phone falls back to when only `closed.pc` was given. */
+export const mobileClosedDefaults: Partial<ResolvedClosed>;
+/** @type {ResolvedClosed} */
+declare const CLOSED_PC: ResolvedClosed;
+import type { ResolvedClosed } from '../types.js';
+declare namespace PALETTE {
+    let accent_1: string;
+    export { accent_1 as accent };
+    export let ink: string;
+    export let muted: string;
+    export let surface: string;
+    export let raised: string;
+    export let line: string;
+    export let onAccent: string;
+}
+export {};

package/dist/types/theme/merge-theme.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Merge `override` onto `base`, recursing into plain objects.
+ *
+ * `undefined` means "say nothing" and leaves the base value alone; `null` means
+ * "clear it", so `{ image: null }` removes a default icon rather than being
+ * ignored. There are no arrays anywhere in a theme, so a plain recursive merge
+ * is enough.
+ *
+ * @template {Record<string, any>} T
+ * @param {T} base
+ * @param {Record<string, any> | undefined} override
+ * @returns {T}
+ */
+export function mergeTheme<T extends Record<string, any>>(base: T, override: Record<string, any> | undefined): T;
+/**
+ * Fill every gap in a user theme and narrow it to one device.
+ *
+ * @param {Theme | undefined} theme
+ * @param {Device} device
+ * @returns {ResolvedTheme}
+ */
+export function resolveTheme(theme: Theme | undefined, device: Device): ResolvedTheme;
+/**
+ * The breakpoint a theme asks for, readable before the full resolve (the
+ * device is not known until the breakpoint is).
+ *
+ * @param {Theme | undefined} theme
+ * @returns {number}
+ */
+export function breakpointOf(theme: Theme | undefined): number;
+import type { Theme } from '../types.js';
+import type { Device } from '../types.js';
+import type { ResolvedTheme } from '../types.js';

package/dist/types/theme/theme-to-css.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Turn a resolved theme into the custom properties the stylesheets read.
+ *
+ * Only values CSS can act on are here. Positions, animation effects, text and
+ * images that belong in markup are applied as attributes or drawn by the
+ * render functions instead.
+ *
+ * Animation durations are deliberately absent: the transition code has to know
+ * when an animation ends, so the theme is the single source of truth for them
+ * and it writes the duration onto the element as it starts. A custom property
+ * here would look like a knob that does nothing.
+ *
+ * @param {ResolvedTheme} theme
+ * @returns {Record<string, string>}
+ */
+export function themeToVariables(theme: ResolvedTheme): Record<string, string>;
+/**
+ * The stylesheet text for a resolved theme.
+ *
+ * @param {ResolvedTheme} theme
+ * @returns {string}
+ */
+export function themeToCss(theme: ResolvedTheme): string;
+import type { ResolvedTheme } from '../types.js';

package/dist/types/types.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Public types for Chit UI. This module has no runtime value; it exists so that
+ * every other file can `@import` from one place and so `tsc` can emit .d.ts.
+ */
+export type Role = "user" | "assistant" | "system";
+/**
+ * Public types for Chit UI. This module has no runtime value; it exists so that
+ * every other file can `@import` from one place and so `tsc` can emit .d.ts.
+ */
+export type MessageStatus = "sending" | "sent" | "error";
+/**
+ * Public types for Chit UI. This module has no runtime value; it exists so that
+ * every other file can `@import` from one place and so `tsc` can emit .d.ts.
+ */
+export type ChatState = "closed" | "open" | "hidden";
+/**
+ * Public types for Chit UI. This module has no runtime value; it exists so that
+ * every other file can `@import` from one place and so `tsc` can emit .d.ts.
+ */
+export type Trigger = "user" | "api";
+/**
+ * Public types for Chit UI. This module has no runtime value; it exists so that
+ * every other file can `@import` from one place and so `tsc` can emit .d.ts.
+ */
+export type Device = "pc" | "mobile";
+/**
+ * Public types for Chit UI. This module has no runtime value; it exists so that
+ * every other file can `@import` from one place and so `tsc` can emit .d.ts.
+ */
+export type Effect = "fade" | "scale" | "slide" | "none";
+/**
+ * Public types for Chit UI. This module has no runtime value; it exists so that
+ * every other file can `@import` from one place and so `tsc` can emit .d.ts.
+ */
+export type Position = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+export type MessageBase = {
+    /**
+     * Unique within the array; used as the diffing key.
+     */
+    id: string;
+    role: Role;
+    time?: string | Date | undefined;
+    name?: string | undefined;
+    avatar?: string | undefined;
+    status?: MessageStatus | undefined;
+    streaming?: boolean | undefined;
+    /**
+     * Never touched by the library.
+     */
+    meta?: unknown;
+};
+export type TextMessage = MessageBase & {
+    text: string;
+};
+export type HtmlMessage = MessageBase & {
+    html: string;
+};
+export type TemplateMessage = MessageBase & {
+    template: import("lit").TemplateResult;
+};
+export type ElementMessage = MessageBase & {
+    element: HTMLElement;
+};
+export type ComponentMessage = MessageBase & {
+    component: (new () => HTMLElement) | string;
+    props?: Record<string, unknown>;
+};
+export type Message = TextMessage | HtmlMessage | TemplateMessage | ElementMessage | ComponentMessage;
+export type Animation = {
+    enter?: Effect | undefined;
+    exit?: Effect | undefined;
+    /**
+     * ms
+     */
+    duration?: number | undefined;
+};
+export type Offset = {
+    x?: number | undefined;
+    y?: number | undefined;
+};
+export type ClosedTheme = {
+    /**
+     * Launcher edge length in px, or 'auto' to let its content decide.
+     */
+    size?: number | "auto" | undefined;
+    position?: Position | undefined;
+    offset?: Offset | undefined;
+    radius?: number | undefined;
+    /**
+     * Icon image URL; null clears the default.
+     */
+    image?: string | null | undefined;
+    label?: string | null | undefined;
+    /**
+     * A component that draws the whole launcher.
+     */
+    component?: string | (new () => HTMLElement) | null | undefined;
+    /**
+     * Properties written to that component.
+     */
+    props?: Record<string, unknown> | undefined;
+    colors?: {
+        background?: string;
+        text?: string;
+        shadow?: string;
+    } | undefined;
+    animation?: (Animation & {
+        idle?: "none" | "pulse" | "bounce";
+    }) | undefined;
+};
+export type OpenColors = {
+    background?: string | undefined;
+    text?: string | undefined;
+    accent?: string | undefined;
+    border?: string | undefined;
+    shadow?: string | undefined;
+    headerBackground?: string | undefined;
+    headerText?: string | undefined;
+    userBubble?: string | undefined;
+    userText?: string | undefined;
+    assistantBubble?: string | undefined;
+    assistantText?: string | undefined;
+    systemText?: string | undefined;
+    inputBackground?: string | undefined;
+    inputText?: string | undefined;
+    inputPlaceholder?: string | undefined;
+};
+export type OpenTheme = {
+    /**
+     * Ignored on mobile (always full screen).
+     */
+    width?: number | undefined;
+    /**
+     * Ignored on mobile (always full screen).
+     */
+    height?: number | undefined;
+    position?: Position | undefined;
+    offset?: Offset | undefined;
+    radius?: number | undefined;
+    /**
+     * Keep the launcher visible while open.
+     */
+    launcher?: "hidden" | "visible" | undefined;
+    header?: {
+        title?: string | null;
+        logo?: string | null;
+        avatar?: string | null;
+    } | undefined;
+    background?: {
+        image?: string | null;
+    } | undefined;
+    colors?: OpenColors | undefined;
+    animation?: (Animation & {
+        scroll?: "smooth" | "instant";
+    }) | undefined;
+    input?: {
+        maxRows?: number;
+        placeholder?: string | null;
+    } | undefined;
+};
+export type Theme = {
+    /**
+     * Widths below this are treated as mobile.
+     */
+    breakpoint?: number | undefined;
+    zIndex?: number | undefined;
+    font?: {
+        family?: string;
+        size?: number;
+    } | undefined;
+    closed?: ClosedTheme | {
+        pc?: ClosedTheme;
+        mobile?: ClosedTheme;
+    } | undefined;
+    open?: OpenTheme | undefined;
+    hidden?: {
+        animation?: {
+            exit?: Effect;
+            duration?: number;
+        };
+    } | undefined;
+};
+/**
+ * A theme with every gap filled in and `closed` narrowed to the device in use.
+ * This is what the render functions and the CSS generator read.
+ */
+export type ResolvedClosed = {
+    size: number | "auto";
+    position: Position;
+    offset: {
+        x: number;
+        y: number;
+    };
+    radius: number;
+    image: string | null;
+    label: string | null;
+    component: (new () => HTMLElement) | string | null;
+    props: Record<string, unknown>;
+    colors: {
+        background: string;
+        text: string;
+        shadow: string;
+    };
+    animation: {
+        enter: Effect;
+        exit: Effect;
+        duration: number;
+        idle: "none" | "pulse" | "bounce";
+    };
+};
+/**
+ * A theme with every gap filled in and `closed` narrowed to the device in use.
+ * This is what the render functions and the CSS generator read.
+ */
+export type ResolvedOpen = {
+    width: number;
+    height: number;
+    position: Position;
+    offset: {
+        x: number;
+        y: number;
+    };
+    radius: number;
+    launcher: "hidden" | "visible";
+    header: {
+        title: string | null;
+        logo: string | null;
+        avatar: string | null;
+    };
+    background: {
+        image: string | null;
+    };
+    colors: Required<OpenColors>;
+    animation: {
+        enter: Effect;
+        exit: Effect;
+        duration: number;
+        scroll: "smooth" | "instant";
+    };
+    input: {
+        maxRows: number;
+        placeholder: string | null;
+    };
+};
+/**
+ * A theme with every gap filled in and `closed` narrowed to the device in use.
+ * This is what the render functions and the CSS generator read.
+ */
+export type ResolvedTheme = {
+    breakpoint: number;
+    zIndex: number;
+    font: {
+        family: string;
+        size: number;
+    };
+    closed: ResolvedClosed;
+    open: ResolvedOpen;
+    hidden: {
+        animation: {
+            exit: Effect;
+            duration: number;
+        };
+    };
+    /**
+     * Which bucket `closed` was narrowed to.
+     */
+    device: Device;
+};