@hidemikimura/chit-ui 0.2.0 → 0.3.0

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

@@ -34,6 +34,12 @@ export class ChitUI extends LitElement {
         };
         typing: {
             type: ObjectConstructor;
+            noAccessor: boolean;
+        };
+        loading: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            noAccessor: boolean;
         };
         busy: {
             type: BooleanConstructor;
@@ -83,10 +89,6 @@ export class ChitUI extends LitElement {
     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} */
@@ -119,6 +121,63 @@ export class ChitUI extends LitElement {
     sanitize: ((html: string) => string) | undefined;
     /** @type {((time: Date) => string) | undefined} */
     formatTime: ((time: Date) => string) | undefined;
+    /** The launcher's drag, for the render function to hook up. */
+    get launcherDrag(): DragController;
+    /** The panel's drag, likewise. */
+    get panelDrag(): DragController;
+    set dragOffset(value: {
+        x: number;
+        y: number;
+    } | null);
+    /**
+     * How far the reader has dragged the widget from where the theme put it, in
+     * screen pixels, or null when it is still there.
+     *
+     * There is one of these for the whole widget rather than one per state: the
+     * launcher and the panel are the same widget wearing two shapes, so moving
+     * either moves both, and the panel opens where the launcher was left.
+     *
+     * @type {{ x: number, y: number } | null}
+     */
+    get dragOffset(): {
+        x: number;
+        y: number;
+    } | null;
+    /** Forget the dragged position and go back to what the theme says. */
+    resetPosition(): void;
+    /**
+     * The composer calls this once a submit has gone out and no listener
+     * cancelled it. Listening for `chat-submit` here instead would be wrong:
+     * this element's own listener runs before the consumer's, so it cannot see
+     * a `preventDefault()` that is still to come.
+     *
+     * @returns {void}
+     */
+    handleSubmitted(): void;
+    set loading(value: boolean);
+    /**
+     * Show the "waiting for an answer" indicator. Turning this on turns
+     * `typing` off, for the reason given above.
+     *
+     * @type {boolean}
+     */
+    get loading(): boolean;
+    set typing(value: boolean | {
+        html: string;
+    });
+    /**
+     * Show the "typing" bubble: `true`, or `{ html }` for your own markup.
+     *
+     * Turning this on turns `loading` off. The two describe the same pause in
+     * the conversation — one says a person is writing, the other that a server
+     * has not answered yet — and showing both would leave the reader to work
+     * out the difference.
+     *
+     * @type {boolean | { html: string }}
+     */
+    get typing(): boolean | {
+        html: string;
+    };
     set state(value: ChatState);
     /**
      * Current state. Assigning it starts the transition, exactly as calling the
@@ -270,6 +329,7 @@ import { LitElement } from 'lit';
 import type { Theme } from './types.js';
 import type { Message } from './types.js';
 import type { Labels } from './i18n/labels.js';
+import { DragController } from './controllers/drag-controller.js';
 import type { ChatState } from './types.js';
 import type { Device } from './types.js';
 import type { ResolvedTheme } from './types.js';

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

@@ -49,6 +49,10 @@ export type ComposerHost = {
     sendOnEnter: boolean;
     maxLength: number | undefined;
     currentLabels: import("../i18n/labels.js").Labels;
+    /**
+     * Called after a submit that no listener cancelled.
+     */
+    handleSubmitted: () => void;
 };
 import type { ReactiveController } from 'lit';
 import type { LitElement } from 'lit';

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

@@ -0,0 +1,118 @@
+/**
+ * Moves one thing — the launcher or the panel — around the viewport.
+ *
+ * What a gesture produces is not a position but a displacement: how far the
+ * reader has dragged the widget from wherever the theme put it, in screen
+ * pixels. The host keeps one such displacement for the whole widget and hands
+ * it to both controllers, which is what makes the two states travel together:
+ * drag the launcher into a corner and the panel opens in that same corner,
+ * because both are the theme's position plus the same shift.
+ *
+ * Each controller then turns the displacement into the terms its own corner
+ * uses — at a right-hand corner, moving right means a smaller offset — and
+ * writes it into the two custom properties the stylesheet already reads. The
+ * offset lives on the host as an inline property, which outranks the theme's
+ * sheet and the page's CSS: a reader who dragged the widget somewhere means
+ * it, and until the drag is cleared theirs is the most specific word on where
+ * it goes.
+ *
+ * @implements {ReactiveController}
+ */
+export class DragController implements ReactiveController {
+    /**
+     * @param {LitElement} host
+     * @param {DragOptions} options
+     */
+    constructor(host: LitElement, options: DragOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * True when the gesture that just ended was a drag. Reading it clears it, so
+     * the click a pointer-up fires can be skipped exactly once.
+     *
+     * @returns {boolean}
+     */
+    consumeDrag(): boolean;
+    /**
+     * Put this thing where the displacement says, within the viewport.
+     *
+     * @param {{ x: number, y: number } | null} displacement
+     * @returns {{ x: number, y: number } | undefined} Where it ended up, when it is on screen.
+     */
+    place(displacement: {
+        x: number;
+        y: number;
+    } | null): {
+        x: number;
+        y: number;
+    } | undefined;
+    /**
+     * Begin a drag.
+     *
+     * @param {PointerEvent} event
+     * @returns {void}
+     */
+    start(event: PointerEvent): void;
+    /**
+     * Move with the arrow keys, so the same thing can be done without a pointer.
+     *
+     * @param {KeyboardEvent} event
+     * @returns {boolean} True when the key was used.
+     */
+    nudge(event: KeyboardEvent): boolean;
+    #private;
+}
+export type DragOptions = {
+    name: "launcher" | "panel";
+    enabled: () => boolean;
+    /**
+     * What moves.
+     */
+    element: () => HTMLElement | null;
+    /**
+     * How big it means to be.
+     */
+    size: () => {
+        width: number;
+        height: number;
+    };
+    /**
+     * Which corner the offset counts from.
+     */
+    corner: () => Position;
+    /**
+     * The theme's offset, before any drag.
+     */
+    base: () => {
+        x: number;
+        y: number;
+    };
+    /**
+     * The widget's displacement now.
+     */
+    current: () => {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * A new displacement.
+     */
+    onMove: (displacement: {
+        x: number;
+        y: number;
+    }) => void;
+    /**
+     * The gesture ended here.
+     */
+    onSettle: (name: "launcher" | "panel") => void;
+    /**
+     * The custom properties to write.
+     */
+    vars: {
+        x: string;
+        y: string;
+    };
+};
+import type { ReactiveController } from 'lit';
+import type { LitElement } from 'lit';
+import type { Position } from '../types.js';

package/dist/types/events.d.ts

@@ -27,4 +27,5 @@ export const Events: Readonly<{
     BREAKPOINT_CHANGE: "chat-breakpoint-change";
     HOME: "chat-home";
     ATTACH: "chat-attach";
+    MOVE: "chat-move";
 }>;

package/dist/types/global.d.ts

@@ -1,5 +1,5 @@
 import type { ChitUI } from './chit-ui.js';
-import type { Message, ChatState, Trigger, Device } from './types.js';
+import type { Message, ChatState, Trigger, Device, Position } from './types.js';
 
 export interface ChitUIEventMap {
   'chat-submit': CustomEvent<{ text: string }>;
@@ -17,6 +17,12 @@ export interface ChitUIEventMap {
   'chat-breakpoint-change': CustomEvent<{ device: Device }>;
   'chat-home': CustomEvent<{ trigger: Trigger }>;
   'chat-attach': CustomEvent<{ files: File[] }>;
+  'chat-move': CustomEvent<{
+    target: 'launcher' | 'panel';
+    position: Position;
+    offset: { x: number; y: number };
+    displacement: { x: number; y: number };
+  }>;
 }
 
 declare global {

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

@@ -53,6 +53,14 @@ export type Labels = {
      * Announced while the other side is typing.
      */
     typing: string;
+    /**
+     * Announced while waiting for an answer.
+     */
+    loading: string;
+    /**
+     * The panel's drag handle.
+     */
+    move: string;
     /**
      * "Jump to newest" button.
      */

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

@@ -1,4 +1,3 @@
-/** @import { ChitUI } from '../chit-ui.js' */
 /**
  * The scrolling conversation.
  *

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

@@ -19,6 +19,7 @@ export namespace defaultTheme {
         }
         let radius: number;
         let launcher: "hidden";
+        let draggable: boolean;
         namespace header {
             let visible: boolean;
             let title: null;
@@ -64,6 +65,13 @@ export namespace defaultTheme {
             export { radius_1 as radius };
             export let tail: "none";
         }
+        namespace loading {
+            export let auto: boolean;
+            export let style: "spinner";
+            let text_1: null;
+            export { text_1 as text };
+            export let timeout: number;
+        }
         namespace speaker {
             namespace assistant {
                 let name: null;

package/dist/types/types.d.ts

@@ -102,6 +102,10 @@ export type ClosedTheme = {
      */
     image?: string | null | undefined;
     label?: string | null | undefined;
+    /**
+     * Let the reader move it around the viewport.
+     */
+    draggable?: boolean | undefined;
     /**
      * A component that draws the whole launcher.
      */
@@ -119,6 +123,31 @@ export type ClosedTheme = {
         idle?: "none" | "pulse" | "bounce";
     }) | undefined;
 };
+/**
+ * The wait between sending and the answer arriving.
+ */
+export type LoadingStyle = "dots" | "spinner" | "text";
+/**
+ * The wait between sending and the answer arriving.
+ */
+export type LoadingTheme = {
+    /**
+     * Show it from `chat-submit` until the next message from the other side.
+     */
+    auto?: boolean | undefined;
+    /**
+     * What it looks like.
+     */
+    style?: LoadingStyle | undefined;
+    /**
+     * Wording beside the animation, or on its own for `'text'`.
+     */
+    text?: string | null | undefined;
+    /**
+     * ms after which it gives up on its own; 0 leaves it to the consumer.
+     */
+    timeout?: number | undefined;
+};
 /**
  * Who is talking, as the theme describes them. A message that carries its own
  * `name` or `avatar` wins; `null` on the message hides what the theme set.
@@ -166,6 +195,10 @@ export type OpenTheme = {
      * Keep the launcher visible while open.
      */
     launcher?: "hidden" | "visible" | undefined;
+    /**
+     * Let the reader move the panel by its title bar.
+     */
+    draggable?: boolean | undefined;
     /**
      * The title bar: whether it is there at all, its text, its image, and whether it offers a way back to the start.
      */
@@ -193,6 +226,10 @@ export type OpenTheme = {
         assistant?: SpeakerTheme;
         user?: SpeakerTheme;
     } | undefined;
+    /**
+     * The wait for an answer.
+     */
+    loading?: LoadingTheme | undefined;
     animation?: (Animation & {
         scroll?: "smooth" | "instant";
     }) | undefined;
@@ -241,6 +278,7 @@ export type ResolvedClosed = {
         y: number;
     };
     radius: number;
+    draggable: boolean;
     image: string | null;
     label: string | null;
     component: (new () => HTMLElement) | string | null;
@@ -271,6 +309,7 @@ export type ResolvedOpen = {
     };
     radius: number;
     launcher: "hidden" | "visible";
+    draggable: boolean;
     header: {
         visible: boolean;
         title: string | null;
@@ -289,6 +328,7 @@ export type ResolvedOpen = {
         assistant: Required<SpeakerTheme>;
         user: Required<SpeakerTheme>;
     };
+    loading: Required<LoadingTheme>;
     animation: {
         enter: Effect;
         exit: Effect;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hidemikimura/chit-ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Lit-based chat widget UI: launcher, panel, themable, any HTML or Lit component as a message",
   "license": "MIT",
   "author": "Hidemi Kimura",

package/src/chit-ui.js

@@ -8,6 +8,7 @@ import { BreakpointController } from './controllers/breakpoint-controller.js';
 import { ThemeController } from './controllers/theme-controller.js';
 import { ScrollController } from './controllers/scroll-controller.js';
 import { ComposerController } from './controllers/composer-controller.js';
+import { DragController } from './controllers/drag-controller.js';
 import { renderLauncher } from './render/launcher.js';
 import { renderPanel } from './render/panel.js';
 import { resolveLabels, resolveLocale } from './i18n/labels.js';
@@ -56,7 +57,8 @@ export class ChitUI extends LitElement {
     state: { type: String, reflect: true, noAccessor: true },
     theme: { type: Object },
     messages: { type: Array },
-    typing: { type: Object },
+    typing: { type: Object, noAccessor: true },
+    loading: { type: Boolean, reflect: true, noAccessor: true },
     busy: { type: Boolean, reflect: true },
     inputDisabled: { type: Boolean, reflect: true, attribute: 'input-disabled' },
     inputHidden: { type: Boolean, reflect: true, attribute: 'input-hidden' },
@@ -72,6 +74,12 @@ export class ChitUI extends LitElement {
   /** @type {ChatState} */
   #state = 'closed';
 
+  /** @type {boolean | { html: string }} */
+  #typing = false;
+
+  /** @type {boolean} */
+  #loading = false;
+
   /**
    * Set by the widget's own event handlers just before they move the state, so
    * the events can say the move came from a person rather than from code.
@@ -115,9 +123,6 @@ export class ChitUI extends LitElement {
     /** @type {Message[]} Rendered as given. The library never mutates this. */
     this.messages = [];
 
-    /** @type {boolean | { html: string }} Show the "typing" bubble. */
-    this.typing = false;
-
     /** @type {boolean} Lock the composer while a reply is in flight. */
     this.busy = false;
 
@@ -175,6 +180,220 @@ export class ChitUI extends LitElement {
       behavior: () => this.currentTheme.open.animation.scroll,
     });
     this.#composer = new ComposerController(this);
+
+    this.#launcherDrag = new DragController(this, {
+      name: 'launcher',
+      enabled: () => this.currentTheme.closed.draggable,
+      element: () => this.#part('launcher'),
+      size: () => boxOf(this.#part('launcher')),
+      corner: () => this.currentTheme.closed.position,
+      base: () => this.currentTheme.closed.offset,
+      current: () => this.#dragOffset,
+      onMove: (displacement) => this.#moveTo(displacement),
+      onSettle: (name) => this.#announceMove(name),
+      vars: { x: '--chit-launcher-offset-x', y: '--chit-launcher-offset-y' },
+    });
+
+    this.#panelDrag = new DragController(this, {
+      name: 'panel',
+      // On a phone the panel is the whole screen; there is nowhere to move it.
+      enabled: () => this.currentTheme.open.draggable && this.device === 'pc',
+      element: () => this.#part('panel'),
+      // What the theme asks for, capped by the window — never the measured
+      // box, which shrinks as the panel is pushed towards its own corner.
+      size: () => {
+        const open = this.currentTheme.open;
+        return {
+          width: Math.min(open.width, window.innerWidth - 16),
+          height: Math.min(open.height, window.innerHeight - 16),
+        };
+      },
+      corner: () => this.currentTheme.open.position,
+      base: () => this.currentTheme.open.offset,
+      current: () => this.#dragOffset,
+      onMove: (displacement) => this.#moveTo(displacement),
+      onSettle: (name) => this.#announceMove(name),
+      vars: { x: '--chit-panel-offset-x', y: '--chit-panel-offset-y' },
+    });
+  }
+
+  /** @type {DragController} */
+  #launcherDrag;
+
+  /** @type {DragController} */
+  #panelDrag;
+
+  /**
+   * @param {string} name
+   * @returns {HTMLElement | null}
+   */
+  #part(name) {
+    return /** @type {HTMLElement | null} */ (
+      this.renderRoot?.querySelector(`[part~="${name}"]`) ?? null
+    );
+  }
+
+  /** The launcher's drag, for the render function to hook up. */
+  get launcherDrag() {
+    return this.#launcherDrag;
+  }
+
+  /** The panel's drag, likewise. */
+  get panelDrag() {
+    return this.#panelDrag;
+  }
+
+  /**
+   * How far the reader has dragged the widget from where the theme put it, in
+   * screen pixels, or null when it is still there.
+   *
+   * There is one of these for the whole widget rather than one per state: the
+   * launcher and the panel are the same widget wearing two shapes, so moving
+   * either moves both, and the panel opens where the launcher was left.
+   *
+   * @type {{ x: number, y: number } | null}
+   */
+  get dragOffset() {
+    return this.#dragOffset;
+  }
+
+  set dragOffset(value) {
+    this.#dragOffset = value ? { x: value.x, y: value.y } : null;
+    this.#place();
+  }
+
+  /** Forget the dragged position and go back to what the theme says. */
+  resetPosition() {
+    this.dragOffset = null;
+  }
+
+  /** @type {{ x: number, y: number } | null} */
+  #dragOffset = null;
+
+  /**
+   * @param {{ x: number, y: number }} displacement
+   * @returns {void}
+   */
+  #moveTo(displacement) {
+    this.#dragOffset = displacement;
+    this.#place();
+  }
+
+  /** Put both shapes where the displacement says. */
+  #place() {
+    this.#launcherDrag.place(this.#dragOffset);
+    this.#panelDrag.place(this.#dragOffset);
+  }
+
+  /**
+   * @param {'launcher' | 'panel'} name
+   * @returns {void}
+   */
+  #announceMove(name) {
+    if (!this.#dragOffset) return;
+    const theme = this.currentTheme;
+    const side = name === 'launcher' ? theme.closed : theme.open;
+    const drag = name === 'launcher' ? this.#launcherDrag : this.#panelDrag;
+    emit(this, Events.MOVE, {
+      target: name,
+      position: side.position,
+      // The thing that was dragged is on screen by definition, so `place`
+      // gives the offset it actually landed on, clamp included.
+      offset: drag.place(this.#dragOffset) ?? side.offset,
+      displacement: { ...this.#dragOffset },
+    });
+  }
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  #loadingTimer;
+
+  /**
+   * The ids present when the wait began. A reply is anything from the other
+   * side that was not among them; the consumer's own echo of what the reader
+   * just sent is not an answer and must not end the wait.
+   *
+   * @type {Set<string> | undefined}
+   */
+  #waitFrom;
+
+  /**
+   * The composer calls this once a submit has gone out and no listener
+   * cancelled it. Listening for `chat-submit` here instead would be wrong:
+   * this element's own listener runs before the consumer's, so it cannot see
+   * a `preventDefault()` that is still to come.
+   *
+   * @returns {void}
+   */
+  handleSubmitted() {
+    this.#startWaiting();
+  }
+
+  /** Begin the automatic wait, if the theme asked for one. */
+  #startWaiting() {
+    const loading = this.currentTheme.open.loading;
+    if (!loading.auto) return;
+
+    this.#waitFrom = new Set(this.messages.map((message) => message.id));
+    this.loading = true;
+    this.#clearLoadingTimer();
+    if (loading.timeout > 0) {
+      this.#loadingTimer = setTimeout(() => {
+        this.#loadingTimer = undefined;
+        this.#stopWaiting();
+      }, loading.timeout);
+    }
+  }
+
+  /** End it, however it ended. */
+  #stopWaiting() {
+    this.#clearLoadingTimer();
+    this.#waitFrom = undefined;
+    this.loading = false;
+  }
+
+  #clearLoadingTimer() {
+    if (this.#loadingTimer !== undefined) clearTimeout(this.#loadingTimer);
+    this.#loadingTimer = undefined;
+  }
+
+  /**
+   * Show the "typing" bubble: `true`, or `{ html }` for your own markup.
+   *
+   * Turning this on turns `loading` off. The two describe the same pause in
+   * the conversation — one says a person is writing, the other that a server
+   * has not answered yet — and showing both would leave the reader to work
+   * out the difference.
+   *
+   * @type {boolean | { html: string }}
+   */
+  get typing() {
+    return this.#typing;
+  }
+
+  set typing(value) {
+    const previous = this.#typing;
+    if (value === previous) return;
+    this.#typing = value;
+    this.requestUpdate('typing', previous);
+    if (value) this.loading = false;
+  }
+
+  /**
+   * Show the "waiting for an answer" indicator. Turning this on turns
+   * `typing` off, for the reason given above.
+   *
+   * @type {boolean}
+   */
+  get loading() {
+    return this.#loading;
+  }
+
+  set loading(value) {
+    const previous = this.#loading;
+    if (value === previous) return;
+    this.#loading = value;
+    this.requestUpdate('loading', previous);
+    if (value) this.typing = false;
   }
 
   /**
@@ -537,6 +756,26 @@ export class ChitUI extends LitElement {
     const live = new Set(this.messages.map((message) => message.id));
     pruneComponents(this, live);
     this.#announceRenders(live);
+
+    // An answer has arrived when a message from the other side appears that
+    // was not there when the wait began.
+    // The shape on screen has just changed, so whatever is there now needs to
+    // be put where the drag left the widget — and clamped to today's window.
+    if (this.#dragOffset) this.#place();
+
+    if (this.#waitFrom) {
+      const answered = this.messages.some(
+        (message) =>
+          message.role !== 'user' && !(/** @type {Set<string>} */ (this.#waitFrom).has(message.id)),
+      );
+      if (answered) this.#stopWaiting();
+    }
+  }
+
+  /** @override */
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#clearLoadingTimer();
   }
 
   /**
@@ -583,3 +822,15 @@ export class ChitUI extends LitElement {
     `;
   }
 }
+
+/**
+ * The size of something on screen, or nothing at all when it is not there.
+ *
+ * @param {HTMLElement | null} element
+ * @returns {{ width: number, height: number }}
+ */
+function boxOf(element) {
+  if (!element) return { width: 0, height: 0 };
+  const box = element.getBoundingClientRect();
+  return { width: box.width, height: box.height };
+}