@hidemikimura/chit-ui 0.1.0

package/src/controllers/state-controller.js

@@ -0,0 +1,316 @@
+// @ts-check
+import { Events, emit } from '../events.js';
+
+/** @import { ReactiveController, LitElement } from 'lit' */
+/** @import { ChatState, Trigger, Effect } from '../types.js' */
+
+/**
+ * @typedef {{ effect: Effect, duration: number }} AnimationSpec
+ * @typedef {(from: ChatState, to: ChatState, phase: 'enter' | 'exit') => AnimationSpec} AnimationResolver
+ *
+ * @typedef {Object} StateControllerOptions
+ * @property {AnimationResolver} animation   Which effect and duration to play.
+ * @property {() => boolean} keepsLauncher   True when the launcher stays visible behind an open panel.
+ * @property {() => void} onOpened           Called once the panel is open and settled.
+ */
+
+/** Which `part` carries the visible element of each state. */
+const PART_FOR_STATE = /** @type {const} */ ({
+  closed: 'launcher',
+  open: 'panel',
+  hidden: null,
+});
+
+/**
+ * Owns everything about moving between closed / open / hidden.
+ *
+ * The host's `state` property changes the instant it is assigned; what the DOM
+ * shows lags behind it for as long as the transition animation runs. That
+ * lagging value is `renderedState`, and the render functions key off it — so a
+ * panel animating out is still in the DOM while `state` already reads 'closed'.
+ *
+ * @implements {ReactiveController}
+ */
+export class StateController {
+  /** @type {LitElement & { state: ChatState }} */
+  #host;
+  /** @type {AnimationResolver} */
+  #resolveAnimation;
+  /** @type {() => boolean} */
+  #keepsLauncher;
+  /** @type {() => void} */
+  #onOpened;
+
+  /** Logical state: the target of the most recent transition. */
+  #current = /** @type {ChatState} */ ('closed');
+  /** What the DOM is showing right now. */
+  #rendered = /** @type {ChatState} */ ('closed');
+
+  /** Guards the host's own `state` setter against re-entering us. */
+  #applying = false;
+  /** Bumped per transition so a superseded one can bail out after an await. */
+  #generation = 0;
+  /** @type {((settled: boolean) => void) | null} */
+  #settle = null;
+  /** @type {(() => void) | null} */
+  #stopWaiting = null;
+  /** @type {boolean} */
+  #restoreFocusToLauncher = false;
+
+  /**
+   * @param {LitElement & { state: ChatState }} host
+   * @param {StateControllerOptions} options
+   */
+  constructor(host, { animation, keepsLauncher, onOpened }) {
+    this.#host = host;
+    this.#resolveAnimation = animation;
+    this.#keepsLauncher = keepsLauncher;
+    this.#onOpened = onOpened;
+    host.addController(this);
+  }
+
+  /** @returns {ChatState} What the DOM currently shows. */
+  get renderedState() {
+    return this.#rendered;
+  }
+
+  /** @returns {boolean} True while the host's own setter must not call us back. */
+  get applying() {
+    return this.#applying;
+  }
+
+  hostConnected() {
+    this.#current = this.#host.state;
+    this.#rendered = this.#host.state;
+    this.#host.dataset.renderedState = this.#rendered;
+  }
+
+  hostDisconnected() {
+    this.#stopWaiting?.();
+    this.#stopWaiting = null;
+    this.#settle?.(false);
+    this.#settle = null;
+  }
+
+  hostUpdated() {
+    this.#host.dataset.renderedState = this.#rendered;
+  }
+
+  /**
+   * Move to `to`, running the before-event, the animations and the completion
+   * events in order.
+   *
+   * @param {ChatState} to
+   * @param {Trigger} trigger
+   * @returns {Promise<boolean>} false when a listener cancelled it, or when a
+   *   later transition superseded this one.
+   */
+  request(to, trigger) {
+    const from = this.#current;
+    if (to === from) return Promise.resolve(true);
+
+    if (!this.#announceIntent(from, to, trigger)) {
+      this.#assign(from);
+      return Promise.resolve(false);
+    }
+
+    // A transition already in flight loses: snap the DOM to where it was
+    // heading, tell its caller it did not finish, and start over from there.
+    this.#interrupt();
+
+    this.#current = to;
+    this.#assign(to);
+    emit(this.#host, Events.STATE_CHANGE, { from, to, trigger });
+
+    return this.#run(from, to, trigger);
+  }
+
+  /**
+   * Fire the cancelable before-event for this transition, if it has one.
+   *
+   * @param {ChatState} from
+   * @param {ChatState} to
+   * @param {Trigger} trigger
+   * @returns {boolean} false when a listener called preventDefault().
+   */
+  #announceIntent(from, to, trigger) {
+    if (to === 'open') {
+      return emit(this.#host, Events.BEFORE_OPEN, { from, trigger }, { cancelable: true });
+    }
+    if (to === 'closed' && from === 'open') {
+      return emit(this.#host, Events.BEFORE_CLOSE, { from, trigger }, { cancelable: true });
+    }
+    return true;
+  }
+
+  #interrupt() {
+    this.#generation += 1;
+    this.#stopWaiting?.();
+    this.#stopWaiting = null;
+    this.#settle?.(false);
+    this.#settle = null;
+    if (this.#rendered !== this.#current) {
+      this.#rendered = this.#current;
+      this.#host.requestUpdate();
+    }
+  }
+
+  /**
+   * @param {ChatState} from
+   * @param {ChatState} to
+   * @param {Trigger} trigger
+   * @returns {Promise<boolean>}
+   */
+  #run(from, to, trigger) {
+    const generation = this.#generation;
+    /** @type {Promise<boolean>} */
+    const settled = new Promise((resolve) => {
+      this.#settle = resolve;
+    });
+
+    void (async () => {
+      this.#restoreFocusToLauncher = this.#focusIsInsidePanel();
+      await this.#host.updateComplete;
+      if (generation !== this.#generation) return;
+
+      const leaving = this.#elementFor(from);
+      if (leaving && !this.#launcherSurvives(from, to)) {
+        await this.#animate(leaving, 'exit', this.#resolveAnimation(from, to, 'exit'));
+        if (generation !== this.#generation) return;
+      }
+
+      this.#rendered = to;
+      this.#host.requestUpdate();
+      await this.#host.updateComplete;
+      if (generation !== this.#generation) return;
+
+      const arriving = this.#elementFor(to);
+      if (arriving) {
+        await this.#animate(arriving, 'enter', this.#resolveAnimation(from, to, 'enter'));
+        if (generation !== this.#generation) return;
+      }
+
+      this.#announceArrival(from, to, trigger);
+      this.#manageFocus(to);
+
+      this.#settle?.(true);
+      this.#settle = null;
+    })();
+
+    return settled;
+  }
+
+  /**
+   * Whether the element of `from` survives the transition and so must not play
+   * an exit animation. Only the launcher can, and only when the theme asks to
+   * keep it visible behind an open panel.
+   *
+   * @param {ChatState} from
+   * @param {ChatState} to
+   * @returns {boolean}
+   */
+  #launcherSurvives(from, to) {
+    return from === 'closed' && to === 'open' && this.#keepsLauncher();
+  }
+
+  /**
+   * @param {ChatState} from
+   * @param {ChatState} to
+   * @param {Trigger} trigger
+   */
+  #announceArrival(from, to, trigger) {
+    if (from === 'hidden') emit(this.#host, Events.SHOW, { from, to });
+    if (to === 'hidden') {
+      emit(this.#host, Events.HIDE, { from, to });
+      return;
+    }
+    if (to === 'open') emit(this.#host, Events.OPEN, { from, trigger });
+    else if (to === 'closed' && from === 'open') emit(this.#host, Events.CLOSE, { from, trigger });
+  }
+
+  /** @param {ChatState} to */
+  #manageFocus(to) {
+    if (to === 'open') {
+      this.#onOpened();
+      return;
+    }
+    if (to === 'closed' && this.#restoreFocusToLauncher) {
+      this.#elementFor('closed')?.focus();
+    }
+    this.#restoreFocusToLauncher = false;
+  }
+
+  #focusIsInsidePanel() {
+    const active = this.#host.renderRoot instanceof ShadowRoot
+      ? this.#host.renderRoot.activeElement
+      : null;
+    const panel = this.#elementFor('open');
+    return !!(active && panel && (active === panel || panel.contains(active)));
+  }
+
+  /**
+   * @param {ChatState} state
+   * @returns {HTMLElement | null}
+   */
+  #elementFor(state) {
+    const part = PART_FOR_STATE[state];
+    if (!part) return null;
+    return /** @type {HTMLElement | null} */ (
+      this.#host.renderRoot.querySelector(`[part~="${part}"]`)
+    );
+  }
+
+  /**
+   * Assign the host's `state` without the setter calling us back.
+   *
+   * @param {ChatState} state
+   */
+  #assign(state) {
+    if (this.#host.state === state) return;
+    this.#applying = true;
+    this.#host.state = state;
+    this.#applying = false;
+  }
+
+  /**
+   * Play one CSS animation and resolve when it ends. Resolves immediately when
+   * there is nothing to play; falls back to a timer in case `animationend`
+   * never arrives (a backgrounded tab, a display:none ancestor).
+   *
+   * @param {HTMLElement} element
+   * @param {'enter' | 'exit'} phase
+   * @param {AnimationSpec} spec
+   * @returns {Promise<void>}
+   */
+  #animate(element, phase, spec) {
+    const { effect, duration } = spec;
+    const skip =
+      effect === 'none' ||
+      duration <= 0 ||
+      window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    if (skip) return Promise.resolve();
+
+    return new Promise((resolve) => {
+      let finished = false;
+      /** @param {Event} [event] */
+      const finish = (event) => {
+        if (event && event.target !== element) return;
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        element.removeEventListener('animationend', finish);
+        element.removeAttribute('data-anim');
+        element.style.removeProperty('--_chit-anim-duration');
+        if (this.#stopWaiting === finish) this.#stopWaiting = null;
+        resolve();
+      };
+
+      element.dataset.effect = effect;
+      element.dataset.anim = phase;
+      element.style.setProperty('--_chit-anim-duration', `${duration}ms`);
+      element.addEventListener('animationend', finish);
+      const timer = setTimeout(finish, duration + 50);
+      this.#stopWaiting = finish;
+    });
+  }
+}

package/src/controllers/theme-controller.js

@@ -0,0 +1,75 @@
+// @ts-check
+import { resolveTheme, breakpointOf } from '../theme/merge-theme.js';
+import { themeToCss } from '../theme/theme-to-css.js';
+import { AdoptedSheet } from '../styles/adopted-sheet.js';
+
+/** @import { ReactiveController, LitElement } from 'lit' */
+/** @import { Theme, ResolvedTheme, Device } from '../types.js' */
+
+/**
+ * Turns the `theme` property into the custom properties everything else reads.
+ *
+ * The generated sheet is adopted *after* the component's own stylesheets, so a
+ * theme value beats the fallback declared alongside the rules that use it.
+ * Page CSS still wins over both: a `chit-ui { --chit-color-accent: ... }` rule
+ * lives in the outer tree, and the outer tree takes precedence over `:host`.
+ *
+ * @implements {ReactiveController}
+ */
+export class ThemeController {
+  /** @type {LitElement} */
+  #host;
+  /** @type {AdoptedSheet} */
+  #sheet = new AdoptedSheet('data-chit-theme');
+  /** @type {ResolvedTheme} */
+  #resolved;
+
+  /**
+   * @param {LitElement} host
+   * @param {{ device: () => Device }} options
+   */
+  constructor(host, { device }) {
+    this.#host = host;
+    this.#resolved = resolveTheme(undefined, device());
+  }
+
+  /** @returns {ResolvedTheme} The theme in force, defaults filled in. */
+  get current() {
+    return this.#resolved;
+  }
+
+  hostConnected() {
+    this.#write();
+  }
+
+  hostDisconnected() {
+    this.#sheet.detach();
+  }
+
+  /**
+   * The breakpoint a theme asks for. Needed before `apply`, because the device
+   * cannot be decided until the breakpoint is known.
+   *
+   * @param {Theme | undefined} theme
+   * @returns {number}
+   */
+  static breakpointOf(theme) {
+    return breakpointOf(theme);
+  }
+
+  /**
+   * Re-resolve for the current theme and device. Cheap to call on every update:
+   * the stylesheet is only rewritten when the generated text actually changes.
+   *
+   * @param {Theme | undefined} theme
+   * @param {Device} device
+   */
+  apply(theme, device) {
+    this.#resolved = resolveTheme(theme, device);
+    this.#write();
+  }
+
+  #write() {
+    this.#sheet.write(themeToCss(this.#resolved), this.#host.renderRoot);
+  }
+}

package/src/element.js

@@ -0,0 +1,4 @@
+// @ts-check
+// Side-effect free entry: exports the class without registering a tag name,
+// so the caller can pick their own.
+export { ChitUI } from './chit-ui.js';

package/src/events.js

@@ -0,0 +1,33 @@
+// @ts-check
+
+/** Every event this library dispatches. Never write the string literals elsewhere. */
+export const Events = Object.freeze({
+  SUBMIT: 'chat-submit',
+  BEFORE_OPEN: 'chat-before-open',
+  OPEN: 'chat-open',
+  BEFORE_CLOSE: 'chat-before-close',
+  CLOSE: 'chat-close',
+  HIDE: 'chat-hide',
+  SHOW: 'chat-show',
+  STATE_CHANGE: 'chat-state-change',
+  INPUT: 'chat-input',
+  MESSAGE_RENDER: 'chat-message-render',
+  MESSAGE_CLICK: 'chat-message-click',
+  SCROLL_TOP: 'chat-scroll-top',
+  BREAKPOINT_CHANGE: 'chat-breakpoint-change',
+});
+
+/**
+ * Dispatch a composed, bubbling CustomEvent from the host.
+ *
+ * @param {HTMLElement} host
+ * @param {string} name
+ * @param {unknown} detail
+ * @param {{ cancelable?: boolean }} [options]
+ * @returns {boolean} false when a listener called preventDefault().
+ */
+export function emit(host, name, detail, { cancelable = false } = {}) {
+  return host.dispatchEvent(
+    new CustomEvent(name, { detail, bubbles: true, composed: true, cancelable }),
+  );
+}

package/src/global.d.ts

@@ -0,0 +1,25 @@
+import type { ChitUI } from './chit-ui.js';
+import type { Message, ChatState, Trigger, Device } from './types.js';
+
+export interface ChitUIEventMap {
+  'chat-submit': CustomEvent<{ text: string }>;
+  'chat-before-open': CustomEvent<{ from: ChatState; trigger: Trigger }>;
+  'chat-open': CustomEvent<{ from: ChatState; trigger: Trigger }>;
+  'chat-before-close': CustomEvent<{ from: ChatState; trigger: Trigger }>;
+  'chat-close': CustomEvent<{ from: ChatState; trigger: Trigger }>;
+  'chat-hide': CustomEvent<{ from: ChatState; to: 'hidden' }>;
+  'chat-show': CustomEvent<{ from: 'hidden'; to: ChatState }>;
+  'chat-state-change': CustomEvent<{ from: ChatState; to: ChatState; trigger: Trigger }>;
+  'chat-input': CustomEvent<{ value: string }>;
+  'chat-message-render': CustomEvent<{ message: Message; element: HTMLElement; instance?: HTMLElement }>;
+  'chat-message-click': CustomEvent<{ message: Message; target: Element; originalEvent: MouseEvent }>;
+  'chat-scroll-top': CustomEvent<Record<string, never>>;
+  'chat-breakpoint-change': CustomEvent<{ device: Device }>;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'chit-ui': ChitUI;
+  }
+  interface HTMLElementEventMap extends ChitUIEventMap {}
+}

package/src/i18n/labels.js

@@ -0,0 +1,72 @@
+// @ts-check
+
+/**
+ * @typedef {Object} Labels
+ * @property {string} launcher      Accessible name of the closed-state button.
+ * @property {string} panel         Accessible name of the dialog.
+ * @property {string} conversation  Accessible name of the message log.
+ * @property {string} close         Close button.
+ * @property {string} send          Send button.
+ * @property {string} input         Composer textarea.
+ * @property {string} typing        Announced while the other side is typing.
+ * @property {string} toLatest      "Jump to newest" button.
+ * @property {{ sending: string, sent: string, error: string }} status  Delivery state of one's own message.
+ * @property {string} charactersLeft  Counter, with {n} for the number remaining.
+ * @property {string} overLimit       Counter past the limit, with {n} for the excess.
+ */
+
+/** @type {Record<string, Labels>} */
+const BUILT_IN = {
+  ja: {
+    launcher: 'チャットを開く',
+    panel: 'チャット',
+    conversation: '会話',
+    close: 'チャットを閉じる',
+    send: '送信',
+    input: 'メッセージを入力',
+    typing: '入力中',
+    toLatest: '最新へ',
+    status: { sending: '送信中', sent: '送信済み', error: '送信できませんでした' },
+    charactersLeft: '残り {n} 文字',
+    overLimit: '{n} 文字超過しています',
+  },
+  en: {
+    launcher: 'Open chat',
+    panel: 'Chat',
+    conversation: 'Conversation',
+    close: 'Close chat',
+    send: 'Send',
+    input: 'Type a message',
+    typing: 'Typing',
+    toLatest: 'Jump to latest',
+    status: { sending: 'Sending', sent: 'Sent', error: 'Not delivered' },
+    charactersLeft: '{n} characters left',
+    overLimit: '{n} characters over the limit',
+  },
+};
+
+/**
+ * The language the widget speaks: the `locale` property, else the document's,
+ * else the browser's. Everything locale-dependent — labels and timestamps
+ * alike — goes through this, so they cannot disagree.
+ *
+ * @param {string | undefined} locale
+ * @returns {string | undefined} undefined means "whatever the browser uses".
+ */
+export function resolveLocale(locale) {
+  return locale || document.documentElement.lang || undefined;
+}
+
+/**
+ * Pick the label set for a locale, falling back to English for anything we do
+ * not ship. `overrides` is the host's `labels` property.
+ *
+ * @param {string | undefined} locale
+ * @param {Partial<Labels> | undefined} [overrides]
+ * @returns {Labels}
+ */
+export function resolveLabels(locale, overrides) {
+  const lang = (resolveLocale(locale) || 'en').toLowerCase();
+  const base = BUILT_IN[lang] ?? BUILT_IN[lang.split('-')[0]] ?? BUILT_IN.en;
+  return overrides ? { ...base, ...overrides } : base;
+}

package/src/index.js

@@ -0,0 +1,9 @@
+// @ts-check
+import { ChitUI } from './chit-ui.js';
+
+if (!customElements.get('chit-ui')) {
+  customElements.define('chit-ui', ChitUI);
+}
+
+export { ChitUI };
+export { Events } from './events.js';

package/src/render/composer.js

@@ -0,0 +1,72 @@
+// @ts-check
+import { html, nothing } from 'lit';
+import { live } from 'lit/directives/live.js';
+
+/** @import { ChitUI } from '../chit-ui.js' */
+
+/**
+ * The composer: a textarea that grows with its content, and a send button.
+ *
+ * The whole thing can be replaced through the `composer` slot; a consumer who
+ * does that calls `host.submit(text)` themselves. `input-before` and
+ * `input-after` are the lighter option, for an attach or emoji button beside
+ * the box the library still owns.
+ *
+ * @param {ChitUI} host
+ * @returns {import('lit').TemplateResult | typeof nothing}
+ */
+export function renderComposer(host) {
+  if (host.inputHidden) return nothing;
+
+  const labels = host.currentLabels;
+  const theme = host.currentTheme.open;
+  const disabled = host.busy || host.inputDisabled;
+  const placeholder = host.placeholder ?? theme.input.placeholder ?? labels.input;
+
+  return html`
+    <form
+      part="composer"
+      @submit=${(/** @type {SubmitEvent} */ event) => {
+        event.preventDefault();
+        host.submit();
+      }}
+    >
+      <slot name="composer">
+        <slot name="input-before"></slot>
+
+        <textarea
+          part="input"
+          rows="1"
+          .value=${live(host.value)}
+          placeholder=${placeholder}
+          aria-label=${labels.input}
+          ?disabled=${disabled}
+          aria-describedby=${host.maxLength === undefined ? nothing : 'chit-counter'}
+          @input=${(/** @type {Event} */ event) => host.handleInput(event)}
+          @keydown=${(/** @type {KeyboardEvent} */ event) => host.handleKeydown(event)}
+          @compositionstart=${() => host.handleComposition(true)}
+          @compositionend=${() => host.handleComposition(false)}
+        ></textarea>
+
+        <slot name="input-after"></slot>
+
+        ${host.maxLength === undefined
+          ? nothing
+          : html`<span part="counter" id="chit-counter" aria-live="polite" hidden></span>`}
+
+        <button
+          part="send-button"
+          type="submit"
+          aria-label=${labels.send}
+          ?disabled=${!host.canSend}
+        >
+          ${host.busy
+            ? html`<span part="spinner" aria-hidden="true"></span>`
+            : html`<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+                <path fill="currentColor" d="M3.4 20.4 21 12 3.4 3.6 3.39 10.2 15.6 12 3.39 13.8z" />
+              </svg>`}
+        </button>
+      </slot>
+    </form>
+  `;
+}