@hidemikimura/chit-ui 0.1.0 → 0.3.0

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;
   }
 
   /**
@@ -387,6 +606,27 @@ export class ChitUI extends LitElement {
     else this.#composer.onCompositionEnd();
   }
 
+  /**
+   * 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) {
+    emit(this, Events.ATTACH, { files });
+  }
+
+  /** Open the file picker from code, as the attach button does. */
+  openAttach() {
+    const field = /** @type {HTMLInputElement | null} */ (
+      this.renderRoot.querySelector('[part~="attach-input"]')
+    );
+    field?.click();
+  }
+
   // --- internal ---------------------------------------------------------
 
   /**
@@ -442,6 +682,21 @@ export class ChitUI extends LitElement {
     return this.#go('closed', 'user');
   }
 
+  /**
+   * 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 = 'api') {
+    emit(this, Events.HOME, { trigger });
+  }
+
   /**
    * @param {ChatState} to
    * @param {Trigger} trigger
@@ -493,6 +748,7 @@ export class ChitUI extends LitElement {
     this.dataset.launcherPosition = theme.closed.position;
     this.dataset.panelPosition = theme.open.position;
     this.dataset.idle = theme.closed.animation.idle;
+    this.dataset.bubbleTail = theme.open.bubble.tail;
   }
 
   /** @override */
@@ -500,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();
   }
 
   /**
@@ -546,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 };
+}

package/src/controllers/composer-controller.js

@@ -152,6 +152,7 @@ export class ComposerController {
     if (!allowed) return false;
 
     this.clear();
+    this.#host.handleSubmitted();
     return true;
   }
 
@@ -212,4 +213,5 @@ export class ComposerController {
  * @property {boolean} sendOnEnter
  * @property {number | undefined} maxLength
  * @property {import('../i18n/labels.js').Labels} currentLabels
+ * @property {() => void} handleSubmitted  Called after a submit that no listener cancelled.
  */

package/src/controllers/drag-controller.js

@@ -0,0 +1,319 @@
+// @ts-check
+
+/** @import { ReactiveController, LitElement } from 'lit' */
+/** @import { Position } from '../types.js' */
+
+/** How far a pointer may travel before the gesture counts as a drag, not a click. */
+const SLOP = 4;
+
+/** How close to the viewport edge the dragged thing may come. */
+const MARGIN = 8;
+
+/** Arrow-key step, and the bigger step Shift asks for. */
+const STEP = 8;
+const BIG_STEP = 32;
+
+/**
+ * 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 {
+  /** @type {LitElement} */
+  #host;
+
+  /** @type {DragOptions} */
+  #options;
+
+  /**
+   * Pointer state, only while a gesture is in flight.
+   *
+   * @type {{
+   *   pointer: { x: number, y: number },
+   *   displacement: { x: number, y: number },
+   *   size: { width: number, height: number },
+   *   corner: Position,
+   *   base: { x: number, y: number },
+   *   moved: boolean,
+   *   pointerId: number,
+   *   target: HTMLElement,
+   * } | undefined}
+   */
+  #from;
+
+  /** True once a gesture has passed the slop, until the click that follows it. */
+  #dragged = false;
+
+  /**
+   * @param {LitElement} host
+   * @param {DragOptions} options
+   */
+  constructor(host, options) {
+    this.#host = host;
+    this.#options = options;
+    host.addController(this);
+  }
+
+  hostConnected() {
+    // A smaller window can leave the widget hanging off the edge; placing it
+    // again runs it back through the clamp.
+    this.#onResize = () => {
+      const now = this.#options.current();
+      if (now) this.#options.onMove(now);
+    };
+    window.addEventListener('resize', this.#onResize);
+  }
+
+  hostDisconnected() {
+    if (this.#onResize) window.removeEventListener('resize', this.#onResize);
+    this.#onResize = undefined;
+  }
+
+  /** @type {(() => void) | undefined} */
+  #onResize;
+
+  /**
+   * 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() {
+    const dragged = this.#dragged;
+    this.#dragged = false;
+    return dragged;
+  }
+
+  /**
+   * 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) {
+    if (!displacement) {
+      for (const name of [this.#options.vars.x, this.#options.vars.y]) {
+        this.#host.style.removeProperty(name);
+      }
+      return undefined;
+    }
+
+    const element = this.#options.element();
+    const offset = this.#toOffset(displacement);
+    // Nothing on screen yet: write it anyway, so the thing is already in
+    // place the moment it is rendered, and let the next pass clamp it.
+    const placed = element ? this.#clamp(offset, this.#options.size()) : offset;
+
+    this.#host.style.setProperty(this.#options.vars.x, `${placed.x}px`);
+    this.#host.style.setProperty(this.#options.vars.y, `${placed.y}px`);
+    return element ? placed : undefined;
+  }
+
+  /**
+   * Begin a drag.
+   *
+   * @param {PointerEvent} event
+   * @returns {void}
+   */
+  start(event) {
+    if (!this.#options.enabled() || event.button !== 0) return;
+    const element = this.#options.element();
+    if (!element) return;
+
+    this.#from = {
+      pointer: { x: event.clientX, y: event.clientY },
+      displacement: this.#options.current() ?? { x: 0, y: 0 },
+      size: this.#options.size(),
+      corner: this.#options.corner(),
+      base: this.#options.base(),
+      moved: false,
+      pointerId: event.pointerId,
+      target: /** @type {HTMLElement} */ (event.currentTarget),
+    };
+
+    // Capture keeps the moves coming even when the pointer leaves the handle.
+    // It throws if the pointer has already gone; the drag still works without
+    // it, so there is nothing to do about that but carry on.
+    try {
+      this.#from.target.setPointerCapture(event.pointerId);
+    } catch {
+      /* no capture available */
+    }
+
+    this.#from.target.addEventListener('pointermove', this.#onPointerMove);
+    this.#from.target.addEventListener('pointerup', this.#onPointerEnd);
+    this.#from.target.addEventListener('pointercancel', this.#onPointerEnd);
+  }
+
+  /** @param {PointerEvent} event */
+  #onPointerMove = (event) => {
+    const from = this.#from;
+    if (!from || event.pointerId !== from.pointerId) return;
+
+    const dx = event.clientX - from.pointer.x;
+    const dy = event.clientY - from.pointer.y;
+    if (!from.moved && Math.hypot(dx, dy) < SLOP) return;
+
+    from.moved = true;
+    // A drag must not also select text or scroll the page under the finger.
+    event.preventDefault();
+    this.#options.onMove(
+      this.#limit(
+        { x: from.displacement.x + dx, y: from.displacement.y + dy },
+        from.base,
+        from.corner,
+        from.size,
+      ),
+    );
+  };
+
+  /** @param {PointerEvent} event */
+  #onPointerEnd = (event) => {
+    const from = this.#from;
+    if (!from || event.pointerId !== from.pointerId) return;
+
+    from.target.removeEventListener('pointermove', this.#onPointerMove);
+    from.target.removeEventListener('pointerup', this.#onPointerEnd);
+    from.target.removeEventListener('pointercancel', this.#onPointerEnd);
+    try {
+      if (from.target.hasPointerCapture(event.pointerId)) {
+        from.target.releasePointerCapture(event.pointerId);
+      }
+    } catch {
+      /* never had it */
+    }
+
+    this.#from = undefined;
+    if (!from.moved) return;
+    this.#dragged = true;
+    this.#options.onSettle(this.#options.name);
+  };
+
+  /**
+   * 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) {
+    if (!this.#options.enabled()) return false;
+    if (event.altKey || event.ctrlKey || event.metaKey) return false;
+
+    /** @type {Record<string, [number, number]>} */
+    const directions = {
+      ArrowLeft: [-1, 0],
+      ArrowRight: [1, 0],
+      ArrowUp: [0, -1],
+      ArrowDown: [0, 1],
+    };
+    const direction = directions[event.key];
+    if (!direction) return false;
+
+    const element = this.#options.element();
+    if (!element) return false;
+
+    const step = event.shiftKey ? BIG_STEP : STEP;
+    const now = this.#options.current() ?? { x: 0, y: 0 };
+    event.preventDefault();
+    this.#options.onMove(
+      this.#limit(
+        { x: now.x + direction[0] * step, y: now.y + direction[1] * step },
+        this.#options.base(),
+        this.#options.corner(),
+        this.#options.size(),
+      ),
+    );
+    this.#options.onSettle(this.#options.name);
+    return true;
+  }
+
+  /**
+   * The displacement in the terms this corner counts in.
+   *
+   * @param {{ x: number, y: number }} displacement
+   * @param {{ x: number, y: number }} [base]
+   * @param {Position} [corner]
+   * @returns {{ x: number, y: number }}
+   */
+  #toOffset(displacement, base = this.#options.base(), corner = this.#options.corner()) {
+    return {
+      x: base.x + (corner.endsWith('right') ? -displacement.x : displacement.x),
+      y: base.y + (corner.startsWith('bottom') ? -displacement.y : displacement.y),
+    };
+  }
+
+  /**
+   * As much of a displacement as this thing can take without leaving the
+   * viewport. The dragged thing sets the shared displacement, so the limit
+   * has to be expressed there rather than only in the offset it writes.
+   *
+   * The size is the size the thing means to be, not the one it happens to
+   * have: the panel's own stylesheet caps it against the space between its
+   * corner and the far edge, so measuring it while it is being pushed into
+   * that corner would read back a smaller box and let it be pushed further,
+   * squeezing it flat instead of stopping it.
+   *
+   * @param {{ x: number, y: number }} displacement
+   * @param {{ x: number, y: number }} base
+   * @param {Position} corner
+   * @param {{ width: number, height: number }} size
+   * @returns {{ x: number, y: number }}
+   */
+  #limit(displacement, base, corner, size) {
+    const offset = this.#clamp(this.#toOffset(displacement, base, corner), size);
+    return {
+      x: corner.endsWith('right') ? base.x - offset.x : offset.x - base.x,
+      y: corner.startsWith('bottom') ? base.y - offset.y : offset.y - base.y,
+    };
+  }
+
+  /**
+   * @param {{ x: number, y: number }} offset
+   * @param {{ width: number, height: number }} size
+   * @returns {{ x: number, y: number }}
+   */
+  #clamp(offset, size) {
+    return {
+      x: clamp(offset.x, window.innerWidth - size.width),
+      y: clamp(offset.y, window.innerHeight - size.height),
+    };
+  }
+}
+
+/**
+ * @param {number} value
+ * @param {number} max  The offset at which the far edge touches the viewport.
+ * @returns {number}
+ */
+function clamp(value, max) {
+  return Math.round(Math.min(Math.max(value, MARGIN), Math.max(MARGIN, max - MARGIN)));
+}
+
+/**
+ * @typedef {Object} DragOptions
+ * @property {'launcher' | 'panel'} name
+ * @property {() => boolean} enabled
+ * @property {() => HTMLElement | null} element     What moves.
+ * @property {() => { width: number, height: number }} size  How big it means to be.
+ * @property {() => Position} corner                Which corner the offset counts from.
+ * @property {() => { x: number, y: number }} base  The theme's offset, before any drag.
+ * @property {() => { x: number, y: number } | null} current  The widget's displacement now.
+ * @property {(displacement: { x: number, y: number }) => void} onMove   A new displacement.
+ * @property {(name: 'launcher' | 'panel') => void} onSettle  The gesture ended here.
+ * @property {{ x: string, y: string }} vars        The custom properties to write.
+ */

package/src/events.js

@@ -15,6 +15,9 @@ export const Events = Object.freeze({
   MESSAGE_CLICK: 'chat-message-click',
   SCROLL_TOP: 'chat-scroll-top',
   BREAKPOINT_CHANGE: 'chat-breakpoint-change',
+  HOME: 'chat-home',
+  ATTACH: 'chat-attach',
+  MOVE: 'chat-move',
 });
 
 /**