@hidemikimura/chit-ui 0.1.0 → 0.3.0

package/dist/types/bundle.d.ts

@@ -1,4 +1,5 @@
 export * from "./index.js";
+export * from "./themes/index.js";
 export { repeat } from "lit/directives/repeat.js";
 export { unsafeHTML } from "lit/directives/unsafe-html.js";
 export { classMap } from "lit/directives/class-map.js";

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
@@ -213,6 +272,18 @@ export class ChitUI extends LitElement {
     handleKeydown(event: KeyboardEvent): void;
     /** @param {boolean} started */
     handleComposition(started: boolean): void;
+    /**
+     * Report files the reader picked with the attach button.
+     *
+     * Nothing is uploaded, previewed or added to the conversation here: the
+     * widget does not own `messages` and has nowhere to send bytes.
+     *
+     * @param {File[]} files
+     * @returns {void}
+     */
+    handleAttach(files: File[]): void;
+    /** Open the file picker from code, as the attach button does. */
+    openAttach(): void;
     /**
      * Render a consumer-supplied typing bubble.
      *
@@ -234,6 +305,18 @@ export class ChitUI extends LitElement {
     toggleFromUser(): Promise<boolean>;
     /** Called by the close button and by Esc. */
     closeFromUser(): Promise<boolean>;
+    /**
+     * Ask to start the conversation over.
+     *
+     * The widget only announces it: `messages` belongs to the consumer, so
+     * clearing it, replaying a scenario or asking for confirmation first are all
+     * theirs to do. Cancelling the event is not offered for the same reason —
+     * there is nothing here to cancel.
+     *
+     * @param {Trigger} [trigger='api']
+     * @returns {void}
+     */
+    home(trigger?: Trigger): void;
     /** @override */
     override willUpdate(): void;
     /** @override */
@@ -246,6 +329,8 @@ 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';
+import type { Trigger } 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

@@ -25,4 +25,7 @@ export const Events: Readonly<{
     MESSAGE_CLICK: "chat-message-click";
     SCROLL_TOP: "chat-scroll-top";
     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 }>;
@@ -15,6 +15,14 @@ export interface ChitUIEventMap {
   'chat-message-click': CustomEvent<{ message: Message; target: Element; originalEvent: MouseEvent }>;
   'chat-scroll-top': CustomEvent<Record<string, never>>;
   '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

@@ -33,10 +33,18 @@ export type Labels = {
      * Close button.
      */
     close: string;
+    /**
+     * Home button: back to the start of the conversation.
+     */
+    home: string;
     /**
      * Send button.
      */
     send: string;
+    /**
+     * Attach button beside the composer.
+     */
+    attach: string;
     /**
      * Composer textarea.
      */
@@ -45,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/composer.d.ts

@@ -1,4 +1,3 @@
-/** @import { ChitUI } from '../chit-ui.js' */
 /**
  * The composer: a textarea that grows with its content, and a send 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,10 +19,12 @@ export namespace defaultTheme {
         }
         let radius: number;
         let launcher: "hidden";
+        let draggable: boolean;
         namespace header {
+            let visible: boolean;
             let title: null;
             let logo: null;
-            let avatar: null;
+            let home: boolean;
         }
         namespace background {
             let image: null;
@@ -58,6 +60,30 @@ export namespace defaultTheme {
             import inputPlaceholder = PALETTE.muted;
             export { inputPlaceholder };
         }
+        namespace bubble {
+            let radius_1: number;
+            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;
+                let avatar: null;
+            }
+            namespace user {
+                let name_1: null;
+                export { name_1 as name };
+                let avatar_1: null;
+                export { avatar_1 as avatar };
+            }
+        }
         namespace animation {
             let enter: "scale";
             let exit: "fade";
@@ -67,6 +93,9 @@ export namespace defaultTheme {
         namespace input {
             let maxRows: number;
             let placeholder: null;
+            let attach: boolean;
+            let accept: string;
+            let multiple: boolean;
         }
     }
     namespace hidden {

package/dist/types/themes/green.d.ts

@@ -0,0 +1,16 @@
+/** @import { Theme } from '../types.js' */
+/**
+ * A green messenger look: a pale blue-grey conversation background, white
+ * bubbles for them, bright green for you, tails on the top corner.
+ *
+ * This is Chit UI's own palette in that familiar shape. It carries no other
+ * product's logo, wordmark or artwork, and the greens are Chit UI's own: the
+ * deep green is dark enough that white text and the send icon clear WCAG AA
+ * on it, which the bright green of the bubbles could not do.
+ * `test/theme.test.js` re-checks every pair here, so a later tweak cannot
+ * quietly drop below AA.
+ *
+ * @type {Theme}
+ */
+export const greenTheme: Theme;
+import type { Theme } from '../types.js';

package/dist/types/themes/index.d.ts

@@ -0,0 +1 @@
+export { greenTheme } from "./green.js";

package/dist/types/types.d.ts

@@ -33,6 +33,11 @@ export type Effect = "fade" | "scale" | "slide" | "none";
  * 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";
+/**
+ * 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 BubbleTail = "none" | "top" | "bottom";
 export type MessageBase = {
     /**
      * Unique within the array; used as the diffing key.
@@ -40,8 +45,14 @@ export type MessageBase = {
     id: string;
     role: Role;
     time?: string | Date | undefined;
-    name?: string | undefined;
-    avatar?: string | undefined;
+    /**
+     * Overrides the theme's speaker name; null hides it.
+     */
+    name?: string | null | undefined;
+    /**
+     * Overrides the theme's speaker image; null hides it.
+     */
+    avatar?: string | null | undefined;
     status?: MessageStatus | undefined;
     streaming?: boolean | undefined;
     /**
@@ -91,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.
      */
@@ -108,6 +123,45 @@ 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.
+ */
+export type SpeakerTheme = {
+    /**
+     * Shown above the bubble.
+     */
+    name?: string | null | undefined;
+    /**
+     * Image URL for the speaker's icon.
+     */
+    avatar?: string | null | undefined;
+};
 export type OpenColors = {
     background?: string | undefined;
     text?: string | undefined;
@@ -141,21 +195,53 @@ 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.
+     */
     header?: {
+        visible?: boolean;
         title?: string | null;
         logo?: string | null;
-        avatar?: string | null;
+        home?: boolean;
     } | undefined;
     background?: {
         image?: string | null;
     } | undefined;
     colors?: OpenColors | undefined;
+    /**
+     * Bubble corner radius, and where the tail points from.
+     */
+    bubble?: {
+        radius?: number;
+        tail?: BubbleTail;
+    } | undefined;
+    /**
+     * Default name and icon per side.
+     */
+    speaker?: {
+        assistant?: SpeakerTheme;
+        user?: SpeakerTheme;
+    } | undefined;
+    /**
+     * The wait for an answer.
+     */
+    loading?: LoadingTheme | undefined;
     animation?: (Animation & {
         scroll?: "smooth" | "instant";
     }) | undefined;
+    /**
+     * Composer: rows, placeholder, and the attach button.
+     */
     input?: {
         maxRows?: number;
         placeholder?: string | null;
+        attach?: boolean;
+        accept?: string;
+        multiple?: boolean;
     } | undefined;
 };
 export type Theme = {
@@ -192,6 +278,7 @@ export type ResolvedClosed = {
         y: number;
     };
     radius: number;
+    draggable: boolean;
     image: string | null;
     label: string | null;
     component: (new () => HTMLElement) | string | null;
@@ -222,15 +309,26 @@ export type ResolvedOpen = {
     };
     radius: number;
     launcher: "hidden" | "visible";
+    draggable: boolean;
     header: {
+        visible: boolean;
         title: string | null;
         logo: string | null;
-        avatar: string | null;
+        home: boolean;
     };
     background: {
         image: string | null;
     };
     colors: Required<OpenColors>;
+    bubble: {
+        radius: number;
+        tail: BubbleTail;
+    };
+    speaker: {
+        assistant: Required<SpeakerTheme>;
+        user: Required<SpeakerTheme>;
+    };
+    loading: Required<LoadingTheme>;
     animation: {
         enter: Effect;
         exit: Effect;
@@ -240,6 +338,9 @@ export type ResolvedOpen = {
     input: {
         maxRows: number;
         placeholder: string | null;
+        attach: boolean;
+        accept: string;
+        multiple: boolean;
     };
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hidemikimura/chit-ui",
-  "version": "0.1.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",
@@ -16,6 +16,10 @@
       "types": "./dist/types/element.d.ts",
       "default": "./src/element.js"
     },
+    "./themes.js": {
+      "types": "./dist/types/themes/index.d.ts",
+      "default": "./src/themes/index.js"
+    },
     "./dist/*": "./dist/*",
     "./package.json": "./package.json"
   },
@@ -23,6 +27,7 @@
     "src",
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": [

package/src/bundle.js

@@ -3,6 +3,7 @@
 // against, so consumers of the bundle define their message components with the
 // very same Lit instance.
 export * from './index.js';
+export * from './themes/index.js';
 export { LitElement, html, css, svg, nothing, render } from 'lit';
 export { repeat } from 'lit/directives/repeat.js';
 export { unsafeHTML } from 'lit/directives/unsafe-html.js';