@hidemikimura/chit-ui 0.2.0 → 0.3.1

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/controllers/scroll-lock-controller.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Keeps a touch that lands on the open panel from scrolling the page behind
+ * it.
+ *
+ * `overscroll-behavior: contain` is on the message list already, and it does
+ * the job for the case it covers: a list that can scroll, dragged past its
+ * own end. It has nothing to say about the cases that actually leak. A short
+ * conversation does not overflow, so the list is not a scroll container at
+ * all and the touch goes straight through to the document — which is what a
+ * reader on an iPhone sees as the page sliding around underneath a chat that
+ * looks like it should be holding still. The same happens for a touch that
+ * starts on the title bar or beside the input.
+ *
+ * So the rule is decided here instead: a touch on the panel may scroll
+ * something inside the panel, and otherwise it does nothing. On the first
+ * move of each gesture the controller looks along the touch's own path —
+ * `composedPath`, so a scroller inside a consumer's component counts too —
+ * for something that can still travel in the direction the finger is going.
+ * Finding one, it stands aside for the rest of the gesture; finding none, it
+ * cancels the move, and iOS then takes the whole gesture as "not a scroll".
+ *
+ * Two touches are left alone: that is a pinch, and zooming is the reader's.
+ * A move that is no longer cancelable is left alone too — the browser has
+ * already committed to scrolling, and `overscroll-behavior` is what keeps
+ * that inside the list.
+ *
+ * @implements {ReactiveController}
+ */
+export class ScrollLockController implements ReactiveController {
+    /** @param {LitElement} host */
+    constructor(host: LitElement);
+    hostUpdated(): void;
+    hostDisconnected(): void;
+    #private;
+}
+import type { ReactiveController } from 'lit';
+import type { LitElement } from 'lit';

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

@@ -0,0 +1,38 @@
+/**
+ * Keeps the full-screen panel inside the part of the screen the reader can
+ * actually see.
+ *
+ * On a phone the panel is `position: fixed` across the whole viewport, and
+ * that viewport is not what is on screen once a keyboard slides up: the
+ * layout viewport keeps its full height, so the composer — and with it the
+ * last few messages — ends up behind the keyboard. iOS then scrolls the page
+ * to chase the focused field, which moves the fixed panel out of frame
+ * instead of helping. `dvh` is no use here either; it tracks the browser's
+ * own chrome collapsing, not the keyboard.
+ *
+ * `visualViewport` is the one thing that does report the visible box, so the
+ * panel is pinned to it: its top to `offsetTop`, its height to `height`. The
+ * composer lands just above the keyboard, and the conversation gets whatever
+ * is left.
+ *
+ * A pinch is left alone. Zooming is how a reader gets a closer look, and a
+ * panel that re-fitted itself to the magnified box would take that away by
+ * reflowing the text back to the same apparent size.
+ *
+ * @implements {ReactiveController}
+ */
+export class ViewportController implements ReactiveController {
+    /**
+     * @param {LitElement} host
+     * @param {{ enabled: () => boolean }} options
+     */
+    constructor(host: LitElement, { enabled }: {
+        enabled: () => boolean;
+    });
+    hostConnected(): void;
+    hostDisconnected(): void;
+    hostUpdated(): void;
+    #private;
+}
+import type { ReactiveController } from 'lit';
+import type { LitElement } from 'lit';

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/index.d.ts

@@ -1,4 +1,166 @@
 /// <reference path="./global.d.ts" />
 export { ChitUI };
 export { Events } from "./events.js";
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Role = import("./types.js").Role;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type MessageStatus = import("./types.js").MessageStatus;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ChatState = import("./types.js").ChatState;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Trigger = import("./types.js").Trigger;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Device = import("./types.js").Device;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Effect = import("./types.js").Effect;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Position = import("./types.js").Position;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type BubbleTail = import("./types.js").BubbleTail;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type LoadingStyle = import("./types.js").LoadingStyle;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type MessageBase = import("./types.js").MessageBase;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type TextMessage = import("./types.js").TextMessage;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type HtmlMessage = import("./types.js").HtmlMessage;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type TemplateMessage = import("./types.js").TemplateMessage;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ElementMessage = import("./types.js").ElementMessage;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ComponentMessage = import("./types.js").ComponentMessage;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Message = import("./types.js").Message;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Animation = import("./types.js").Animation;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Offset = import("./types.js").Offset;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ClosedTheme = import("./types.js").ClosedTheme;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type OpenColors = import("./types.js").OpenColors;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type SpeakerTheme = import("./types.js").SpeakerTheme;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type LoadingTheme = import("./types.js").LoadingTheme;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type OpenTheme = import("./types.js").OpenTheme;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Theme = import("./types.js").Theme;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ResolvedClosed = import("./types.js").ResolvedClosed;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ResolvedOpen = import("./types.js").ResolvedOpen;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ResolvedTheme = import("./types.js").ResolvedTheme;
 import { ChitUI } from './chit-ui.js';

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.1",
   "description": "Lit-based chat widget UI: launcher, panel, themable, any HTML or Lit component as a message",
   "license": "MIT",
   "author": "Hidemi Kimura",