@hidemikimura/chit-ui 0.1.0

package/dist/types/chit-ui.d.ts

@@ -0,0 +1,251 @@
+/** @import { Message, Theme, ChatState, Trigger, Effect, Device, ResolvedTheme } from './types.js' */
+/** @import { Labels } from './i18n/labels.js' */
+/**
+ * The chat widget.
+ *
+ * One custom element, one shadow root. Everything inside is drawn by plain
+ * functions in `render/` and driven by the reactive controllers in
+ * `controllers/`; no nested custom elements, so `::part()` and the theme's
+ * custom properties reach every corner without being forwarded.
+ *
+ * @element chit-ui
+ *
+ * @slot launcher - Replaces the whole closed-state button content.
+ * @slot header - Replaces the panel header.
+ * @slot header-title - Replaces only the title area of the header.
+ * @slot header-actions - Extra buttons beside the close button.
+ * @slot footer - Below the composer (disclaimers, attribution).
+ */
+export class ChitUI extends LitElement {
+    /** @override */
+    static override styles: import("lit").CSSResult[];
+    /** @override */
+    static override properties: {
+        state: {
+            type: StringConstructor;
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+        theme: {
+            type: ObjectConstructor;
+        };
+        messages: {
+            type: ArrayConstructor;
+        };
+        typing: {
+            type: ObjectConstructor;
+        };
+        busy: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        inputDisabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            attribute: string;
+        };
+        inputHidden: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            attribute: string;
+        };
+        placeholder: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        sendOnEnter: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            attribute: string;
+        };
+        maxLength: {
+            type: NumberConstructor;
+            reflect: boolean;
+            attribute: string;
+        };
+        focusOnOpen: {
+            type: StringConstructor;
+            reflect: boolean;
+            attribute: string;
+        };
+        locale: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        labels: {
+            type: ObjectConstructor;
+        };
+        messageStyles: {
+            type: StringConstructor;
+        };
+    };
+    /** @type {Theme} Partial; unset keys fall back to the default theme. */
+    theme: Theme;
+    /** @type {Message[]} Rendered as given. The library never mutates this. */
+    messages: Message[];
+    /** @type {boolean | { html: string }} Show the "typing" bubble. */
+    typing: boolean | {
+        html: string;
+    };
+    /** @type {boolean} Lock the composer while a reply is in flight. */
+    busy: boolean;
+    /** @type {boolean} */
+    inputDisabled: boolean;
+    /** @type {boolean} */
+    inputHidden: boolean;
+    /** @type {string | undefined} */
+    placeholder: string | undefined;
+    /** @type {boolean} */
+    sendOnEnter: boolean;
+    /** @type {number | undefined} */
+    maxLength: number | undefined;
+    /**
+     * Focus the composer once the open transition finishes. 'auto' focuses on
+     * PC only, so a phone keyboard never pops up unasked.
+     *
+     * Named focusOnOpen rather than autofocus: HTMLElement.autofocus is a
+     * standard boolean property and cannot carry a third value.
+     *
+     * @type {'auto' | 'always' | 'never'}
+     */
+    focusOnOpen: "auto" | "always" | "never";
+    /** @type {string | undefined} */
+    locale: string | undefined;
+    /** @type {Partial<Labels> | undefined} Overrides for the built-in UI strings. */
+    labels: Partial<Labels> | undefined;
+    /** @type {string} Extra CSS applied inside message content. */
+    messageStyles: string;
+    /** @type {((html: string) => string) | undefined} Applied to `html` messages only. */
+    sanitize: ((html: string) => string) | undefined;
+    /** @type {((time: Date) => string) | undefined} */
+    formatTime: ((time: Date) => string) | undefined;
+    set state(value: ChatState);
+    /**
+     * Current state. Assigning it starts the transition, exactly as calling the
+     * matching method would.
+     *
+     * @type {ChatState}
+     */
+    get state(): ChatState;
+    /** @returns {Device} Which theme bucket the viewport currently falls in. */
+    get device(): Device;
+    /**
+     * The theme in force for this device, every gap filled in.
+     *
+     * @returns {ResolvedTheme}
+     */
+    get currentTheme(): ResolvedTheme;
+    /** @returns {Labels} */
+    get currentLabels(): Labels;
+    /**
+     * The language in force: the `locale` property, else the document's.
+     * Labels and timestamps both read it, so a page in Japanese does not end up
+     * with Japanese buttons and American clock times.
+     *
+     * @returns {string | undefined}
+     */
+    get resolvedLocale(): string | undefined;
+    /** @returns {ChatState} What the DOM is showing, which lags `state` while animating. */
+    get renderedState(): ChatState;
+    /** @returns {boolean} True when messages arrived while the reader was scrolled up. */
+    get hasUnseen(): boolean;
+    set value(next: string);
+    /**
+     * What is currently typed in the composer.
+     *
+     * Not a reactive property on purpose: a keystroke would otherwise re-render
+     * the whole shadow tree, every message included.
+     *
+     * @type {string}
+     */
+    get value(): string;
+    /** @returns {boolean} Whether what is typed could be sent right now. */
+    get canSend(): boolean;
+    /** @returns {Promise<boolean>} Resolves once the open animation has finished. */
+    open(): Promise<boolean>;
+    /** @returns {Promise<boolean>} */
+    close(): Promise<boolean>;
+    /** @returns {Promise<boolean>} */
+    hide(): Promise<boolean>;
+    /** @returns {Promise<boolean>} From `hidden` back to the launcher. A no-op otherwise. */
+    show(): Promise<boolean>;
+    /** @returns {Promise<boolean>} */
+    toggle(): Promise<boolean>;
+    /**
+     * Send what is in the composer, or the given text, as `chat-submit`.
+     *
+     * Adding the message to `messages` stays the consumer's job; the widget only
+     * reports that someone pressed send.
+     *
+     * @param {string} [text]
+     * @returns {boolean} False when there was nothing to send.
+     */
+    submit(text?: string): boolean;
+    /** Empty the composer and put the caret back in it. */
+    clearInput(): void;
+    /**
+     * Scroll the conversation to the newest message.
+     *
+     * @param {{ smooth?: boolean }} [options]
+     */
+    scrollToBottom(options?: {
+        smooth?: boolean;
+    }): void;
+    /**
+     * The content container of one message, once it has been drawn.
+     *
+     * @param {string} id
+     * @returns {HTMLElement | null}
+     */
+    getMessageElement(id: string): HTMLElement | null;
+    /**
+     * Put the caret in the composer.
+     *
+     * This obeys the caller, not `focusOnOpen`: someone who calls it has asked
+     * for focus. `focusOnOpen` only governs what happens by itself on open.
+     *
+     * @returns {boolean} False when there is no composer to focus.
+     */
+    focusInput(): boolean;
+    /** @param {Event} event */
+    handleInput(event: Event): void;
+    /** @param {KeyboardEvent} event */
+    handleKeydown(event: KeyboardEvent): void;
+    /** @param {boolean} started */
+    handleComposition(started: boolean): void;
+    /**
+     * Render a consumer-supplied typing bubble.
+     *
+     * @param {string} markup
+     * @returns {unknown}
+     */
+    renderTypingHtml(markup: string): unknown;
+    /**
+     * Re-publish a click inside a message as `chat-message-click`.
+     *
+     * `composedPath()[0]` rather than `event.target`: the target is retargeted to
+     * the message container once the event leaves a component's shadow root, and
+     * the consumer wants the element actually clicked.
+     *
+     * @param {MouseEvent} event
+     */
+    handleMessageClick(event: MouseEvent): void;
+    /** Called by the launcher; the resulting events report `trigger: 'user'`. */
+    toggleFromUser(): Promise<boolean>;
+    /** Called by the close button and by Esc. */
+    closeFromUser(): Promise<boolean>;
+    /** @override */
+    override willUpdate(): void;
+    /** @override */
+    override updated(): void;
+    /** @override */
+    override render(): import("lit-html").TemplateResult<1>;
+    #private;
+}
+import { LitElement } from 'lit';
+import type { Theme } from './types.js';
+import type { Message } from './types.js';
+import type { Labels } from './i18n/labels.js';
+import type { ChatState } from './types.js';
+import type { Device } from './types.js';
+import type { ResolvedTheme } from './types.js';

package/dist/types/controllers/breakpoint-controller.d.ts

@@ -0,0 +1,29 @@
+/** @import { ReactiveController, LitElement } from 'lit' */
+/** @import { Device } from '../types.js' */
+/**
+ * Tracks whether the viewport is narrow enough to count as a phone.
+ *
+ * Uses matchMedia rather than a resize listener: it only fires when the
+ * boundary is actually crossed, so nothing runs while the user drags a window
+ * around inside one bucket.
+ *
+ * @implements {ReactiveController}
+ */
+export class BreakpointController implements ReactiveController {
+    /** @param {LitElement} host */
+    constructor(host: LitElement);
+    /** @returns {Device} */
+    get device(): Device;
+    hostDisconnected(): void;
+    /**
+     * Point the controller at a breakpoint. Safe to call on every update; the
+     * media query is only rebuilt when the value actually changes.
+     *
+     * @param {number} breakpoint
+     */
+    observe(breakpoint: number): void;
+    #private;
+}
+import type { ReactiveController } from 'lit';
+import type { Device } from '../types.js';
+import type { LitElement } from 'lit';

package/dist/types/controllers/composer-controller.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Owns the composer: what has been typed, whether an IME is mid-composition,
+ * and when a keystroke counts as "send".
+ *
+ * The typed text is deliberately not a reactive property. A keystroke would
+ * otherwise re-render the whole shadow tree, `repeat` over every message
+ * included; instead the two things that depend on it — the send button's
+ * enabled state and the character counter — are updated in place.
+ *
+ * @implements {ReactiveController}
+ */
+export class ComposerController implements ReactiveController {
+    /** @param {LitElement & ComposerHost} host */
+    constructor(host: LitElement & ComposerHost);
+    set value(next: string);
+    /** @returns {string} */
+    get value(): string;
+    /** @returns {boolean} True while an IME candidate window is open. */
+    get composing(): boolean;
+    /** @returns {number} Characters typed, counted by code point. */
+    get length(): number;
+    /** @returns {boolean} Whether the current text could be sent right now. */
+    get canSend(): boolean;
+    hostDisconnected(): void;
+    hostUpdated(): void;
+    /** @param {Event} event */
+    onInput(event: Event): void;
+    onCompositionStart(): void;
+    onCompositionEnd(): void;
+    /** @param {KeyboardEvent} event */
+    onKeydown(event: KeyboardEvent): void;
+    /**
+     * Hand the text to the consumer and clear the box.
+     *
+     * The text is passed as typed: leading and trailing newlines are theirs to
+     * keep or strip, since only they know whether the message is prose or code.
+     *
+     * @param {string} [text]  Defaults to what is in the box.
+     * @returns {boolean} False when there was nothing to send.
+     */
+    submit(text?: string): boolean;
+    clear(): void;
+    focus(): void;
+    #private;
+}
+export type ComposerHost = {
+    busy: boolean;
+    inputDisabled: boolean;
+    sendOnEnter: boolean;
+    maxLength: number | undefined;
+    currentLabels: import("../i18n/labels.js").Labels;
+};
+import type { ReactiveController } from 'lit';
+import type { LitElement } from 'lit';

package/dist/types/controllers/scroll-controller.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Keeps the conversation pinned to the newest message while the reader is at
+ * the bottom, and gets out of the way the moment they scroll up.
+ *
+ * Two things follow from that rule. A reply arriving while the reader is up in
+ * the history must not yank them down — it raises the "jump to latest" button
+ * instead. And their own message always scrolls into view, because they just
+ * pressed send and expect to see it.
+ *
+ * @implements {ReactiveController}
+ */
+export class ScrollController implements ReactiveController {
+    /**
+     * @param {LitElement & { messages: Message[] }} host
+     * @param {{ behavior: () => 'smooth' | 'instant' }} options
+     */
+    constructor(host: LitElement & {
+        messages: Message[];
+    }, { behavior }: {
+        behavior: () => "smooth" | "instant";
+    });
+    /** @returns {boolean} True when newer content arrived while scrolled up. */
+    get hasUnseen(): boolean;
+    /** @returns {boolean} */
+    get atBottom(): boolean;
+    hostDisconnected(): void;
+    /**
+     * Runs before the render, so a decision made here lands in the same frame.
+     * Whether the conversation grew is knowable from the array alone; only the
+     * scrolling itself has to wait for the DOM.
+     */
+    hostUpdate(): void;
+    hostUpdated(): void;
+    /**
+     * @param {{ smooth?: boolean }} [options] Defaults to the theme's setting.
+     */
+    scrollToBottom({ smooth }?: {
+        smooth?: boolean;
+    }): void;
+    #private;
+}
+import type { ReactiveController } from 'lit';
+import type { LitElement } from 'lit';
+import type { Message } from '../types.js';

package/dist/types/controllers/state-controller.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Owns everything about moving between closed / open / hidden.
+ *
+ * The host's `state` property changes the instant it is assigned; what the DOM
+ * shows lags behind it for as long as the transition animation runs. That
+ * lagging value is `renderedState`, and the render functions key off it — so a
+ * panel animating out is still in the DOM while `state` already reads 'closed'.
+ *
+ * @implements {ReactiveController}
+ */
+export class StateController implements ReactiveController {
+    /**
+     * @param {LitElement & { state: ChatState }} host
+     * @param {StateControllerOptions} options
+     */
+    constructor(host: LitElement & {
+        state: ChatState;
+    }, { animation, keepsLauncher, onOpened }: StateControllerOptions);
+    /** @returns {ChatState} What the DOM currently shows. */
+    get renderedState(): ChatState;
+    /** @returns {boolean} True while the host's own setter must not call us back. */
+    get applying(): boolean;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    hostUpdated(): void;
+    /**
+     * Move to `to`, running the before-event, the animations and the completion
+     * events in order.
+     *
+     * @param {ChatState} to
+     * @param {Trigger} trigger
+     * @returns {Promise<boolean>} false when a listener cancelled it, or when a
+     *   later transition superseded this one.
+     */
+    request(to: ChatState, trigger: Trigger): Promise<boolean>;
+    #private;
+}
+export type AnimationSpec = {
+    effect: Effect;
+    duration: number;
+};
+export type AnimationResolver = (from: ChatState, to: ChatState, phase: "enter" | "exit") => AnimationSpec;
+export type StateControllerOptions = {
+    /**
+     * Which effect and duration to play.
+     */
+    animation: AnimationResolver;
+    /**
+     * True when the launcher stays visible behind an open panel.
+     */
+    keepsLauncher: () => boolean;
+    /**
+     * Called once the panel is open and settled.
+     */
+    onOpened: () => void;
+};
+import type { ReactiveController } from 'lit';
+import type { ChatState } from '../types.js';
+import type { Trigger } from '../types.js';
+import type { LitElement } from 'lit';
+import type { Effect } from '../types.js';

package/dist/types/controllers/theme-controller.d.ts

@@ -0,0 +1,47 @@
+/** @import { ReactiveController, LitElement } from 'lit' */
+/** @import { Theme, ResolvedTheme, Device } from '../types.js' */
+/**
+ * Turns the `theme` property into the custom properties everything else reads.
+ *
+ * The generated sheet is adopted *after* the component's own stylesheets, so a
+ * theme value beats the fallback declared alongside the rules that use it.
+ * Page CSS still wins over both: a `chit-ui { --chit-color-accent: ... }` rule
+ * lives in the outer tree, and the outer tree takes precedence over `:host`.
+ *
+ * @implements {ReactiveController}
+ */
+export class ThemeController implements ReactiveController {
+    /**
+     * The breakpoint a theme asks for. Needed before `apply`, because the device
+     * cannot be decided until the breakpoint is known.
+     *
+     * @param {Theme | undefined} theme
+     * @returns {number}
+     */
+    static breakpointOf(theme: Theme | undefined): number;
+    /**
+     * @param {LitElement} host
+     * @param {{ device: () => Device }} options
+     */
+    constructor(host: LitElement, { device }: {
+        device: () => Device;
+    });
+    /** @returns {ResolvedTheme} The theme in force, defaults filled in. */
+    get current(): ResolvedTheme;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Re-resolve for the current theme and device. Cheap to call on every update:
+     * the stylesheet is only rewritten when the generated text actually changes.
+     *
+     * @param {Theme | undefined} theme
+     * @param {Device} device
+     */
+    apply(theme: Theme | undefined, device: Device): void;
+    #private;
+}
+import type { ReactiveController } from 'lit';
+import type { ResolvedTheme } from '../types.js';
+import type { Theme } from '../types.js';
+import type { Device } from '../types.js';
+import type { LitElement } from 'lit';

package/dist/types/element.d.ts

@@ -0,0 +1 @@
+export { ChitUI } from "./chit-ui.js";

package/dist/types/events.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Dispatch a composed, bubbling CustomEvent from the host.
+ *
+ * @param {HTMLElement} host
+ * @param {string} name
+ * @param {unknown} detail
+ * @param {{ cancelable?: boolean }} [options]
+ * @returns {boolean} false when a listener called preventDefault().
+ */
+export function emit(host: HTMLElement, name: string, detail: unknown, { cancelable }?: {
+    cancelable?: boolean;
+}): boolean;
+/** Every event this library dispatches. Never write the string literals elsewhere. */
+export const Events: Readonly<{
+    SUBMIT: "chat-submit";
+    BEFORE_OPEN: "chat-before-open";
+    OPEN: "chat-open";
+    BEFORE_CLOSE: "chat-before-close";
+    CLOSE: "chat-close";
+    HIDE: "chat-hide";
+    SHOW: "chat-show";
+    STATE_CHANGE: "chat-state-change";
+    INPUT: "chat-input";
+    MESSAGE_RENDER: "chat-message-render";
+    MESSAGE_CLICK: "chat-message-click";
+    SCROLL_TOP: "chat-scroll-top";
+    BREAKPOINT_CHANGE: "chat-breakpoint-change";
+}>;

package/dist/types/global.d.ts

@@ -0,0 +1,25 @@
+import type { ChitUI } from './chit-ui.js';
+import type { Message, ChatState, Trigger, Device } from './types.js';
+
+export interface ChitUIEventMap {
+  'chat-submit': CustomEvent<{ text: string }>;
+  'chat-before-open': CustomEvent<{ from: ChatState; trigger: Trigger }>;
+  'chat-open': CustomEvent<{ from: ChatState; trigger: Trigger }>;
+  'chat-before-close': CustomEvent<{ from: ChatState; trigger: Trigger }>;
+  'chat-close': CustomEvent<{ from: ChatState; trigger: Trigger }>;
+  'chat-hide': CustomEvent<{ from: ChatState; to: 'hidden' }>;
+  'chat-show': CustomEvent<{ from: 'hidden'; to: ChatState }>;
+  'chat-state-change': CustomEvent<{ from: ChatState; to: ChatState; trigger: Trigger }>;
+  'chat-input': CustomEvent<{ value: string }>;
+  'chat-message-render': CustomEvent<{ message: Message; element: HTMLElement; instance?: HTMLElement }>;
+  'chat-message-click': CustomEvent<{ message: Message; target: Element; originalEvent: MouseEvent }>;
+  'chat-scroll-top': CustomEvent<Record<string, never>>;
+  'chat-breakpoint-change': CustomEvent<{ device: Device }>;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'chit-ui': ChitUI;
+  }
+  interface HTMLElementEventMap extends ChitUIEventMap {}
+}

package/dist/types/i18n/labels.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The language the widget speaks: the `locale` property, else the document's,
+ * else the browser's. Everything locale-dependent — labels and timestamps
+ * alike — goes through this, so they cannot disagree.
+ *
+ * @param {string | undefined} locale
+ * @returns {string | undefined} undefined means "whatever the browser uses".
+ */
+export function resolveLocale(locale: string | undefined): string | undefined;
+/**
+ * Pick the label set for a locale, falling back to English for anything we do
+ * not ship. `overrides` is the host's `labels` property.
+ *
+ * @param {string | undefined} locale
+ * @param {Partial<Labels> | undefined} [overrides]
+ * @returns {Labels}
+ */
+export function resolveLabels(locale: string | undefined, overrides?: Partial<Labels> | undefined): Labels;
+export type Labels = {
+    /**
+     * Accessible name of the closed-state button.
+     */
+    launcher: string;
+    /**
+     * Accessible name of the dialog.
+     */
+    panel: string;
+    /**
+     * Accessible name of the message log.
+     */
+    conversation: string;
+    /**
+     * Close button.
+     */
+    close: string;
+    /**
+     * Send button.
+     */
+    send: string;
+    /**
+     * Composer textarea.
+     */
+    input: string;
+    /**
+     * Announced while the other side is typing.
+     */
+    typing: string;
+    /**
+     * "Jump to newest" button.
+     */
+    toLatest: string;
+    /**
+     * Delivery state of one's own message.
+     */
+    status: {
+        sending: string;
+        sent: string;
+        error: string;
+    };
+    /**
+     * Counter, with {n} for the number remaining.
+     */
+    charactersLeft: string;
+    /**
+     * Counter past the limit, with {n} for the excess.
+     */
+    overLimit: string;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+/// <reference path="./global.d.ts" />
+export { ChitUI };
+export { Events } from "./events.js";
+import { ChitUI } from './chit-ui.js';

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

@@ -0,0 +1,15 @@
+/** @import { ChitUI } from '../chit-ui.js' */
+/**
+ * The composer: a textarea that grows with its content, and a send button.
+ *
+ * The whole thing can be replaced through the `composer` slot; a consumer who
+ * does that calls `host.submit(text)` themselves. `input-before` and
+ * `input-after` are the lighter option, for an attach or emoji button beside
+ * the box the library still owns.
+ *
+ * @param {ChitUI} host
+ * @returns {import('lit').TemplateResult | typeof nothing}
+ */
+export function renderComposer(host: ChitUI): import("lit").TemplateResult | typeof nothing;
+import type { ChitUI } from '../chit-ui.js';
+import { nothing } from 'lit';