@hidemikimura/chit-ui 0.1.0

package/src/controllers/breakpoint-controller.js

@@ -0,0 +1,82 @@
+// @ts-check
+import { Events, emit } from '../events.js';
+
+/** @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 {
+  /** @type {LitElement} */
+  #host;
+  /** @type {MediaQueryList | null} */
+  #query = null;
+  /** @type {number} */
+  #breakpoint = 0;
+  /** @type {Device} */
+  #device = 'pc';
+  /** Set once the first measurement is in, so start-up is not a "change". */
+  #measured = false;
+
+  /** @param {LitElement} host */
+  constructor(host) {
+    this.#host = host;
+    host.addController(this);
+  }
+
+  /** @returns {Device} */
+  get device() {
+    return this.#device;
+  }
+
+  hostDisconnected() {
+    this.#query?.removeEventListener('change', this.#onChange);
+    this.#query = null;
+  }
+
+  /**
+   * 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) {
+    if (breakpoint === this.#breakpoint && this.#query) return;
+    this.#breakpoint = breakpoint;
+    this.#query?.removeEventListener('change', this.#onChange);
+    this.#query = window.matchMedia(`(max-width: ${breakpoint - 1}px)`);
+    this.#query.addEventListener('change', this.#onChange);
+    this.#apply(this.#query.matches ? 'mobile' : 'pc');
+  }
+
+  /** @param {MediaQueryListEvent} event */
+  #onChange = (event) => {
+    this.#apply(event.matches ? 'mobile' : 'pc');
+  };
+
+  /**
+   * Record the device and announce it, unless this is the first measurement —
+   * start-up is not a change. A later flip is announced whether it came from
+   * the viewport resizing or from the theme moving the breakpoint, because
+   * either way the answer a consumer asked for is now different.
+   *
+   * @param {Device} device
+   */
+  #apply(device) {
+    if (device === this.#device && this.#host.dataset.device) return;
+
+    this.#device = device;
+    this.#host.dataset.device = device;
+    this.#host.requestUpdate();
+
+    if (this.#measured) emit(this.#host, Events.BREAKPOINT_CHANGE, { device });
+    this.#measured = true;
+  }
+}

package/src/controllers/composer-controller.js

@@ -0,0 +1,215 @@
+// @ts-check
+import { Events, emit } from '../events.js';
+
+/** @import { ReactiveController, LitElement } from 'lit' */
+
+/** Browsers that size a textarea to its content need no JS help. */
+const SUPPORTS_FIELD_SIZING =
+  typeof CSS !== 'undefined' && CSS.supports?.('field-sizing', 'content');
+
+/**
+ * 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 {
+  /** @type {LitElement & ComposerHost} */
+  #host;
+
+  #value = '';
+
+  /** True between compositionstart and compositionend. */
+  #composing = false;
+
+  /**
+   * True for one turn of the event loop after a composition ends.
+   *
+   * WebKit dispatches the Enter that confirmed an IME candidate as a plain
+   * keydown *after* compositionend, with `isComposing` already false — so
+   * without this flag, confirming a Japanese candidate would send the message.
+   */
+  #justComposed = false;
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  #composedTimer;
+
+  /** @param {LitElement & ComposerHost} host */
+  constructor(host) {
+    this.#host = host;
+    host.addController(this);
+  }
+
+  /** @returns {string} */
+  get value() {
+    return this.#value;
+  }
+
+  set value(next) {
+    this.#value = next ?? '';
+    const input = this.#input;
+    if (input && input.value !== this.#value) input.value = this.#value;
+    this.#grow();
+    this.#syncDerived();
+  }
+
+  /** @returns {boolean} True while an IME candidate window is open. */
+  get composing() {
+    return this.#composing;
+  }
+
+  /** @returns {number} Characters typed, counted by code point. */
+  get length() {
+    return Array.from(this.#value).length;
+  }
+
+  /** @returns {boolean} Whether the current text could be sent right now. */
+  get canSend() {
+    if (this.#host.busy || this.#host.inputDisabled) return false;
+    if (this.#value.trim() === '') return false;
+    const limit = this.#host.maxLength;
+    return limit === undefined || this.length <= limit;
+  }
+
+  hostDisconnected() {
+    clearTimeout(this.#composedTimer);
+  }
+
+  hostUpdated() {
+    const input = this.#input;
+    if (input && input.value !== this.#value) input.value = this.#value;
+    this.#grow();
+    this.#syncDerived();
+  }
+
+  /** @returns {HTMLTextAreaElement | null} */
+  get #input() {
+    return /** @type {HTMLTextAreaElement | null} */ (
+      this.#host.renderRoot.querySelector('[part~="input"]')
+    );
+  }
+
+  /** @param {Event} event */
+  onInput(event) {
+    this.#value = /** @type {HTMLTextAreaElement} */ (event.target).value;
+    this.#grow();
+    this.#syncDerived();
+    emit(this.#host, Events.INPUT, { value: this.#value });
+  }
+
+  onCompositionStart() {
+    this.#composing = true;
+  }
+
+  onCompositionEnd() {
+    this.#composing = false;
+    this.#justComposed = true;
+    clearTimeout(this.#composedTimer);
+    this.#composedTimer = setTimeout(() => {
+      this.#justComposed = false;
+    }, 0);
+  }
+
+  /** @param {KeyboardEvent} event */
+  onKeydown(event) {
+    if (event.key !== 'Enter') return;
+    if (!this.#host.sendOnEnter) return;
+    // Shift+Enter is a newline; the others are the browser's or the page's.
+    if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return;
+
+    // Chrome, Edge and Firefox mark the confirming Enter on the event itself.
+    // Older engines only set keyCode 229.
+    if (event.isComposing || event.keyCode === 229) return;
+    // Safari's post-compositionend Enter, and Android soft keyboards that send
+    // Enter while a composition is still open.
+    if (this.#composing || this.#justComposed) return;
+
+    event.preventDefault();
+    this.submit();
+  }
+
+  /**
+   * 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) {
+    const value = text ?? this.#value;
+    if (text === undefined && !this.canSend) return false;
+    if (text !== undefined && (this.#host.busy || this.#host.inputDisabled)) return false;
+    if (value.trim() === '') return false;
+
+    const allowed = emit(this.#host, Events.SUBMIT, { text: value }, { cancelable: true });
+    if (!allowed) return false;
+
+    this.clear();
+    return true;
+  }
+
+  clear() {
+    this.value = '';
+    this.focus();
+  }
+
+  focus() {
+    this.#input?.focus();
+  }
+
+  /** Grow the box with its content, up to the theme's row limit. */
+  #grow() {
+    if (SUPPORTS_FIELD_SIZING) return;
+    const input = this.#input;
+    if (!input) return;
+    input.style.height = 'auto';
+    input.style.height = `${input.scrollHeight}px`;
+  }
+
+  /**
+   * Update the parts that depend on the typed text without a re-render.
+   */
+  #syncDerived() {
+    const root = this.#host.renderRoot;
+
+    const send = /** @type {HTMLButtonElement | null} */ (
+      root.querySelector('[part~="send-button"]')
+    );
+    if (send) send.disabled = !this.canSend;
+
+    const input = this.#input;
+    const counter = /** @type {HTMLElement | null} */ (root.querySelector('[part~="counter"]'));
+    const limit = this.#host.maxLength;
+    if (limit === undefined) return;
+
+    const remaining = limit - this.length;
+    const over = remaining < 0;
+    input?.setAttribute('aria-invalid', over ? 'true' : 'false');
+
+    if (!counter) return;
+    counter.textContent = String(remaining);
+    counter.toggleAttribute('data-over', over);
+    // The digits alone ("-14") say nothing out loud, so the counter carries a
+    // sentence for assistive tech while showing just the number.
+    const labels = this.#host.currentLabels;
+    const template = over ? labels.overLimit : labels.charactersLeft;
+    counter.setAttribute('aria-label', template.replace('{n}', String(Math.abs(remaining))));
+    counter.hidden = this.length <= limit * 0.8;
+  }
+}
+
+/**
+ * @typedef {Object} ComposerHost
+ * @property {boolean} busy
+ * @property {boolean} inputDisabled
+ * @property {boolean} sendOnEnter
+ * @property {number | undefined} maxLength
+ * @property {import('../i18n/labels.js').Labels} currentLabels
+ */

package/src/controllers/scroll-controller.js

@@ -0,0 +1,252 @@
+// @ts-check
+import { Events, emit } from '../events.js';
+
+/** @import { ReactiveController, LitElement } from 'lit' */
+/** @import { Message } from '../types.js' */
+
+/** How close to the end still counts as "at the bottom", in pixels. */
+const BOTTOM_SLACK = 24;
+
+/**
+ * How long to keep treating the viewport as "ours" after starting a smooth
+ * scroll, when the browser has no scrollend event to tell us it finished.
+ */
+const SMOOTH_GRACE_MS = 700;
+
+/**
+ * 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 {
+  /** @type {LitElement & { messages: Message[] }} */
+  #host;
+  /** @type {() => 'smooth' | 'instant'} */
+  #preferredBehavior;
+  /** @type {HTMLElement | null} */
+  #viewport = null;
+  /** @type {ResizeObserver | null} */
+  #resize = null;
+
+  #atBottom = true;
+  #hasUnseen = false;
+  #atTop = false;
+  #followAfterRender = true;
+
+  /**
+   * True while a scroll we started is still animating. Scroll events during
+   * that window report positions we caused, not where the reader went.
+   */
+  #selfScrolling = false;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  #selfScrollTimer;
+  /** The first jump after the panel opens has nothing to animate from. */
+  #openingJump = true;
+
+  /** @type {string | undefined} */
+  #lastId;
+  #lastCount = 0;
+
+  /**
+   * @param {LitElement & { messages: Message[] }} host
+   * @param {{ behavior: () => 'smooth' | 'instant' }} options
+   */
+  constructor(host, { behavior }) {
+    this.#host = host;
+    this.#preferredBehavior = behavior;
+    host.addController(this);
+  }
+
+  /** @returns {boolean} True when newer content arrived while scrolled up. */
+  get hasUnseen() {
+    return this.#hasUnseen;
+  }
+
+  /** @returns {boolean} */
+  get atBottom() {
+    return this.#atBottom;
+  }
+
+  hostDisconnected() {
+    this.#unbind();
+    clearTimeout(this.#selfScrollTimer);
+  }
+
+  /**
+   * 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() {
+    const messages = this.#host.messages;
+    const last = messages[messages.length - 1];
+    const grew = messages.length > this.#lastCount;
+    const newTail = last?.id !== this.#lastId;
+
+    this.#lastId = last?.id;
+    this.#lastCount = messages.length;
+
+    if (!grew && !newTail) return;
+
+    // Their own message always scrolls into view: they just pressed send.
+    if (this.#atBottom || last?.role === 'user') this.#followAfterRender = true;
+    else this.#hasUnseen = true;
+  }
+
+  hostUpdated() {
+    const viewport = /** @type {HTMLElement | null} */ (
+      this.#host.renderRoot.querySelector('[part~="messages"]')
+    );
+
+    if (viewport !== this.#viewport) {
+      this.#unbind();
+      this.#viewport = viewport;
+      this.#bind();
+      // A freshly opened panel starts at the newest message, with no animation
+      // to watch: there was nothing on screen to move away from.
+      if (viewport) {
+        this.#atBottom = true;
+        this.#hasUnseen = false;
+        this.#followAfterRender = true;
+        this.#openingJump = true;
+      }
+    }
+
+    if (this.#followAfterRender) {
+      const behavior = this.#followBehavior;
+      this.#followAfterRender = false;
+      this.#scrollNow({ behavior });
+    }
+  }
+
+  #bind() {
+    if (!this.#viewport) return;
+    this.#viewport.addEventListener('scroll', this.#onScroll, { passive: true });
+    // Precise end-of-scroll where it exists (Chrome 114, Firefox 109,
+    // Safari 17.4); the timer below covers the rest.
+    this.#viewport.addEventListener('scrollend', this.#onScrollEnd);
+
+    // Images finishing and streamed text growing both change the height
+    // without a scroll event, so the follow has to react to size too.
+    const inner = this.#viewport.firstElementChild;
+    if (inner && typeof ResizeObserver !== 'undefined') {
+      this.#resize = new ResizeObserver(() => {
+        if (!this.#atBottom) return;
+        // Content settling (an image loading, a tall block laying out) right
+        // after a message arrived must not cut the follow short, so while our
+        // own animation is running it is re-aimed rather than replaced. With
+        // nothing in flight this is a streamed reply growing, and that is
+        // followed instantly: an animation restarted every few tens of
+        // milliseconds never lands.
+        this.#scrollNow({ behavior: this.#selfScrolling ? 'smooth' : 'instant' });
+      });
+      this.#resize.observe(inner);
+    }
+  }
+
+  #unbind() {
+    this.#viewport?.removeEventListener('scroll', this.#onScroll);
+    this.#viewport?.removeEventListener('scrollend', this.#onScrollEnd);
+    this.#resize?.disconnect();
+    this.#resize = null;
+    this.#viewport = null;
+  }
+
+  #onScrollEnd = () => {
+    this.#endSelfScroll();
+  };
+
+  #onScroll = () => {
+    const viewport = this.#viewport;
+    if (!viewport) return;
+
+    const distance = viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight;
+    const atBottom = distance <= BOTTOM_SLACK;
+
+    // Our own animation passing through the middle of the list is not the
+    // reader scrolling up.
+    if (this.#selfScrolling) {
+      if (atBottom) this.#endSelfScroll();
+      return;
+    }
+
+    if (atBottom !== this.#atBottom) {
+      this.#atBottom = atBottom;
+      if (atBottom && this.#hasUnseen) {
+        this.#hasUnseen = false;
+        this.#host.requestUpdate();
+      }
+    }
+
+    // One event per visit to the top, so a consumer loading older messages is
+    // not asked again while the reader sits there.
+    const atTop = viewport.scrollTop <= 0;
+    if (atTop && !this.#atTop) emit(this.#host, Events.SCROLL_TOP, {});
+    this.#atTop = atTop;
+  };
+
+  /**
+   * @param {{ smooth?: boolean }} [options] Defaults to the theme's setting.
+   */
+  scrollToBottom({ smooth } = {}) {
+    const behavior =
+      smooth === undefined ? this.#followBehavior : smooth ? 'smooth' : 'instant';
+    this.#scrollNow({ behavior });
+
+    if (this.#hasUnseen) {
+      this.#hasUnseen = false;
+      this.#host.requestUpdate();
+    }
+  }
+
+  /**
+   * What the next follow should look like: the theme's choice, unless the
+   * reader asked for less motion, or this is the jump that happens as the
+   * panel opens.
+   *
+   * @returns {'smooth' | 'instant'}
+   */
+  get #followBehavior() {
+    if (this.#openingJump) return 'instant';
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return 'instant';
+    return this.#preferredBehavior();
+  }
+
+  /** @param {{ behavior?: 'smooth' | 'instant' }} [options] */
+  #scrollNow({ behavior = 'instant' } = {}) {
+    const viewport = this.#viewport;
+    if (!viewport) return;
+
+    this.#openingJump = false;
+    if (behavior === 'smooth') this.#beginSelfScroll();
+
+    viewport.scrollTo({ top: viewport.scrollHeight, behavior });
+    this.#atBottom = true;
+    this.#atTop = false;
+    this.#hasUnseen = false;
+  }
+
+  #beginSelfScroll() {
+    this.#selfScrolling = true;
+    clearTimeout(this.#selfScrollTimer);
+    this.#selfScrollTimer = setTimeout(() => this.#endSelfScroll(), SMOOTH_GRACE_MS);
+  }
+
+  #endSelfScroll() {
+    if (!this.#selfScrolling) return;
+    this.#selfScrolling = false;
+    clearTimeout(this.#selfScrollTimer);
+
+    // Take a reading now that the viewport has settled.
+    const viewport = this.#viewport;
+    if (!viewport) return;
+    const distance = viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight;
+    this.#atBottom = distance <= BOTTOM_SLACK;
+  }
+}