@hidemikimura/chit-ui 0.1.0

package/src/render/content.js

@@ -0,0 +1,211 @@
+// @ts-check
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+
+/** @import { ChitUI } from '../chit-ui.js' */
+/** @import { Message } from '../types.js' */
+
+/**
+ * @typedef {Object} ComponentEntry
+ * @property {(new () => HTMLElement) | string} source  What `component` held when this was built.
+ * @property {HTMLElement} element
+ * @property {Record<string, unknown>} props           Last props written to the element.
+ */
+
+/**
+ * Per-host component instances, keyed by a caller-chosen string.
+ *
+ * Messages key by `msg:<id>`; the launcher has its own key. Keeping one cache
+ * means one place decides when an element is rebuilt and when its props are
+ * merely re-assigned.
+ */
+const INSTANCES = new WeakMap();
+
+/**
+ * The cache key for a message's component.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+const messageKey = (id) => `msg:${id}`;
+
+/** The cache key for the closed-state component. */
+export const LAUNCHER_KEY = 'launcher';
+
+/** The five ways a message can carry its content. Exactly one may be present. */
+const CONTENT_FIELDS = /** @type {const} */ ([
+  'text',
+  'html',
+  'template',
+  'element',
+  'component',
+]);
+
+/**
+ * Which form a message uses. Also drives the `data-content` attribute, because
+ * plain text is the one form whose whitespace has to survive.
+ *
+ * @param {Message} message
+ * @returns {'text' | 'html' | 'template' | 'element' | 'component'}
+ */
+export function contentField(message) {
+  const present = CONTENT_FIELDS.filter((field) => field in message);
+  if (present.length === 1) return present[0];
+  if (present.length === 0) {
+    throw new Error(
+      `ChitUI: message "${message.id}" has no content. Give it one of html, template, element or component.`,
+    );
+  }
+  throw new Error(
+    `ChitUI: message "${message.id}" has ${present.join(' and ')}. Give it exactly one.`,
+  );
+}
+
+/**
+ * The value a message's content is built from. Used to decide whether a
+ * message actually changed, so `chat-message-render` does not fire on every
+ * unrelated update.
+ *
+ * @param {Message} message
+ * @returns {unknown}
+ */
+export function contentKey(message) {
+  return /** @type {Record<string, unknown>} */ (message)[contentField(message)];
+}
+
+/**
+ * The registered tag name for a `component`.
+ *
+ * Registration stays the consumer's job: the library never invents a tag name
+ * and calls `customElements.define` behind their back, because that name would
+ * then be taken globally for the life of the page.
+ *
+ * @param {(new () => HTMLElement) | string} source
+ * @returns {string}
+ */
+function tagNameOf(source) {
+  if (typeof source === 'string') return source;
+
+  const registry = /** @type {CustomElementRegistry & { getName?: (c: unknown) => string | null }} */ (
+    customElements
+  );
+  const registered = registry.getName?.(source);
+  if (registered) return registered;
+
+  const declared = /** @type {{ tagName?: string }} */ (/** @type {unknown} */ (source)).tagName;
+  if (typeof declared === 'string' && declared) return declared;
+
+  throw new Error(
+    'ChitUI: component is not registered in customElements. ' +
+      'Call customElements.define() for it, or pass its tag name as a string.',
+  );
+}
+
+/**
+ * Build (or reuse) an element for a component reference and write its props.
+ *
+ * The instance is kept across renders so the component keeps its own state; a
+ * changed reference replaces it, and changed props are assigned one by one so
+ * the component's own setters see each change.
+ *
+ * @param {ChitUI} host
+ * @param {string} key                                       Cache key.
+ * @param {(new () => HTMLElement) | string} source
+ * @param {Record<string, unknown>} [props]
+ * @returns {HTMLElement}
+ */
+export function resolveComponent(host, key, source, props = {}) {
+  let cache = INSTANCES.get(host);
+  if (!cache) {
+    cache = new Map();
+    INSTANCES.set(host, cache);
+  }
+
+  const existing = /** @type {ComponentEntry | undefined} */ (cache.get(key));
+
+  if (existing && existing.source === source) {
+    for (const [name, value] of Object.entries(props)) {
+      if (!Object.is(existing.props[name], value)) {
+        /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (existing.element))[name] = value;
+      }
+    }
+    existing.props = { ...props };
+    return existing.element;
+  }
+
+  const element = document.createElement(tagNameOf(source));
+  for (const [name, value] of Object.entries(props)) {
+    /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (element))[name] = value;
+  }
+  cache.set(key, { source, element, props: { ...props } });
+  return element;
+}
+
+/**
+ * Drop cached instances for messages that are gone, so a long conversation
+ * does not hold on to elements it will never show again. Non-message entries,
+ * such as the launcher's, are left alone.
+ *
+ * @param {ChitUI} host
+ * @param {Set<string>} liveIds
+ */
+export function pruneComponents(host, liveIds) {
+  const cache = INSTANCES.get(host);
+  if (!cache) return;
+  for (const key of cache.keys()) {
+    if (!key.startsWith('msg:')) continue;
+    if (!liveIds.has(key.slice(4))) cache.delete(key);
+  }
+}
+
+/**
+ * The component instance backing a message, when it has one.
+ *
+ * @param {ChitUI} host
+ * @param {string} id
+ * @returns {HTMLElement | undefined}
+ */
+export function componentInstance(host, id) {
+  return INSTANCES.get(host)?.get(messageKey(id))?.element;
+}
+
+/**
+ * Turn a message's content into something Lit can render as a child value.
+ *
+ * All four shapes collapse here: an HTML string becomes an `unsafeHTML`
+ * directive, a Lit template passes straight through, and an element or a
+ * component becomes a Node, which Lit inserts as-is.
+ *
+ * @param {ChitUI} host
+ * @param {Message} message
+ * @returns {unknown}
+ */
+export function renderContent(host, message) {
+  switch (contentField(message)) {
+    case 'text':
+      // A string child is rendered by Lit as a text node, so the escaping is
+      // structural: there is no parse step for markup to sneak through. Line
+      // breaks survive because the content box is pre-wrap for this form.
+      return /** @type {{ text: string }} */ (/** @type {unknown} */ (message)).text;
+
+    case 'template':
+      return /** @type {{ template: unknown }} */ (/** @type {unknown} */ (message)).template;
+
+    case 'element':
+      return /** @type {{ element: HTMLElement }} */ (/** @type {unknown} */ (message)).element;
+
+    case 'component': {
+      const carrier = /** @type {{ component: (new () => HTMLElement) | string, props?: Record<string, unknown> }} */ (
+        /** @type {unknown} */ (message)
+      );
+      return resolveComponent(host, messageKey(message.id), carrier.component, carrier.props);
+    }
+
+    default: {
+      // Only the html form goes through `sanitize`: `text` is escaped by
+      // construction, and the rest are structures the consumer built
+      // themselves rather than markup we could meaningfully clean.
+      const raw = /** @type {{ html: string }} */ (/** @type {unknown} */ (message)).html;
+      return unsafeHTML(host.sanitize ? host.sanitize(raw) : raw);
+    }
+  }
+}

package/src/render/launcher.js

@@ -0,0 +1,64 @@
+// @ts-check
+import { html, nothing } from 'lit';
+import { LAUNCHER_KEY, resolveComponent } from './content.js';
+
+/** @import { ChitUI } from '../chit-ui.js' */
+
+/**
+ * The closed state: one button.
+ *
+ * What goes inside it has three routes, in order of how much the consumer
+ * takes over:
+ *
+ * - the theme's image or label, drawn inside the themed circle;
+ * - the `launcher` slot, their markup inside that same circle;
+ * - `closed.component`, a component that draws the whole launcher — the button
+ *   then keeps only its role, and gives up its size, background, shadow and
+ *   radius, because two parties styling one box is how things end up clipped.
+ *
+ * @param {ChitUI} host
+ * @returns {import('lit').TemplateResult}
+ */
+export function renderLauncher(host) {
+  const closed = host.currentTheme.closed;
+  const labels = host.currentLabels;
+  const custom = closed.component
+    ? resolveComponent(host, LAUNCHER_KEY, closed.component, closed.props)
+    : null;
+
+  return html`
+    <button
+      part="launcher"
+      type="button"
+      aria-label=${closed.label || labels.launcher}
+      aria-expanded=${host.state === 'open'}
+      ?data-has-image=${!custom && !!closed.image}
+      ?data-custom=${!!custom}
+      @click=${() => host.toggleFromUser()}
+    >
+      ${custom ?? html`<slot name="launcher">${defaultContent(closed)}</slot>`}
+    </button>
+  `;
+}
+
+/**
+ * @param {import('../types.js').ResolvedClosed} closed
+ * @returns {unknown}
+ */
+function defaultContent(closed) {
+  if (closed.image) return nothing;
+  if (closed.label) return html`<span part="launcher-label">${closed.label}</span>`;
+  return defaultIcon();
+}
+
+/** A plain speech bubble, so the widget looks like something before theming. */
+function defaultIcon() {
+  return html`
+    <svg part="launcher-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+      <path
+        fill="currentColor"
+        d="M12 3c-4.97 0-9 3.36-9 7.5 0 2.3 1.25 4.36 3.2 5.73-.13 1.2-.6 2.3-1.36 3.2a.5.5 0 0 0 .5.82 8.2 8.2 0 0 0 3.87-1.86c.88.26 1.82.41 2.79.41 4.97 0 9-3.36 9-7.5S16.97 3 12 3Z"
+      />
+    </svg>
+  `;
+}

package/src/render/message-list.js

@@ -0,0 +1,67 @@
+// @ts-check
+import { html, nothing } from 'lit';
+import { repeat } from 'lit/directives/repeat.js';
+import { renderMessage } from './message.js';
+
+/** @import { ChitUI } from '../chit-ui.js' */
+
+/**
+ * The scrolling conversation.
+ *
+ * `repeat` keys on the message id so an existing bubble's DOM is reused when
+ * the consumer assigns a new array; without it Lit would reorder by position
+ * and a component message would lose its state on every insert.
+ *
+ * Clicks are handled once here and re-published as `chat-message-click`, which
+ * is how a consumer reaches a button inside a message without hunting through
+ * the shadow root.
+ *
+ * @param {ChitUI} host
+ * @returns {import('lit').TemplateResult}
+ */
+export function renderMessageList(host) {
+  const labels = host.currentLabels;
+  const typing = host.typing;
+  const empty = host.messages.length === 0 && !typing;
+
+  return html`
+    <div
+      part="messages"
+      role="log"
+      aria-live="polite"
+      aria-relevant="additions text"
+      aria-label=${labels.conversation}
+      @click=${(/** @type {MouseEvent} */ event) => host.handleMessageClick(event)}
+    >
+      <div part="messages-inner" class="inner">
+        ${empty ? html`<slot name="empty"></slot>` : nothing}
+        ${repeat(
+          host.messages,
+          (message) => message.id,
+          (message) => renderMessage(host, message),
+        )}
+        ${typing
+          ? html`
+              <div part="typing" role="status" aria-label=${labels.typing}>
+                ${typeof typing === 'object' && typing.html
+                  ? host.renderTypingHtml(typing.html)
+                  : html`<span class="dots" aria-hidden="true"><i></i><i></i><i></i></span>`}
+              </div>
+            `
+          : nothing}
+      </div>
+    </div>
+
+    ${host.hasUnseen
+      ? html`
+          <button
+            part="to-latest"
+            type="button"
+            @click=${() => host.scrollToBottom({ smooth: true })}
+          >
+            ${labels.toLatest}
+          </button>
+        `
+      : nothing}
+  `;
+}

package/src/render/message.js

@@ -0,0 +1,82 @@
+// @ts-check
+import { html, nothing } from 'lit';
+import { contentField, renderContent } from './content.js';
+
+/** @import { ChitUI } from '../chit-ui.js' */
+/** @import { Message } from '../types.js' */
+
+/**
+ * Format a timestamp. The consumer's `formatTime` wins; otherwise a plain
+ * locale-aware hour:minute, which is what a chat bubble wants.
+ *
+ * @param {ChitUI} host
+ * @param {string | Date} time
+ * @returns {string}
+ */
+function formatTime(host, time) {
+  const date = time instanceof Date ? time : new Date(time);
+  if (Number.isNaN(date.getTime())) return '';
+  if (host.formatTime) return host.formatTime(date);
+  return new Intl.DateTimeFormat(host.resolvedLocale, {
+    hour: '2-digit',
+    minute: '2-digit',
+  }).format(date);
+}
+
+/**
+ * One message.
+ *
+ * `system` messages are a centred line rather than a bubble: they are the
+ * widget talking about the conversation ("an operator joined"), not a party to
+ * it, so they get no avatar, no name and no timestamp.
+ *
+ * @param {ChitUI} host
+ * @param {Message} message
+ * @returns {import('lit').TemplateResult}
+ */
+export function renderMessage(host, message) {
+  if (message.role === 'system') {
+    return html`
+      <article part="message message-system" data-role="system" data-id=${message.id}>
+        <div part="message-content" data-content=${contentField(message)}>${renderContent(host, message)}</div>
+      </article>
+    `;
+  }
+
+  const meta = message.time || message.status;
+
+  return html`
+    <article
+      part="message message-${message.role}"
+      data-role=${message.role}
+      data-id=${message.id}
+      ?data-streaming=${!!message.streaming}
+      aria-busy=${message.streaming ? 'true' : 'false'}
+    >
+      ${message.avatar
+        ? html`<img part="avatar" src=${message.avatar} alt="" loading="lazy" />`
+        : nothing}
+      <div class="body">
+        ${message.name ? html`<span part="name">${message.name}</span>` : nothing}
+        <div part="bubble">
+          <div part="message-content" data-content=${contentField(message)}>${renderContent(host, message)}</div>
+          ${message.streaming ? html`<span part="cursor" aria-hidden="true"></span>` : nothing}
+        </div>
+        ${meta
+          ? html`
+              <div part="meta" class="meta">
+                ${message.time
+                  ? html`<time part="time">${formatTime(host, message.time)}</time>`
+                  : nothing}
+                ${message.status
+                  ? html`<span part="status" data-status=${message.status}>
+                      ${host.currentLabels.status[message.status]}
+                    </span>`
+                  : nothing}
+              </div>
+            `
+          : nothing}
+      </div>
+    </article>
+  `;
+}

package/src/render/panel.js

@@ -0,0 +1,77 @@
+// @ts-check
+import { html, nothing } from 'lit';
+import { renderMessageList } from './message-list.js';
+import { renderComposer } from './composer.js';
+
+/** @import { ChitUI } from '../chit-ui.js' */
+
+/**
+ * The open state. Header and footer are slots; the message list and the
+ * composer arrive in later milestones and are placeholders for now.
+ *
+ * @param {ChitUI} host
+ * @returns {import('lit').TemplateResult}
+ */
+export function renderPanel(host) {
+  const open = host.currentTheme.open;
+  const labels = host.currentLabels;
+  const title = open.header?.title ?? labels.panel;
+
+  return html`
+    <section
+      part="panel"
+      role="dialog"
+      aria-modal="false"
+      aria-label=${title}
+      tabindex="-1"
+      @keydown=${(/** @type {KeyboardEvent} */ event) => onKeydown(host, event)}
+    >
+      <header part="header">
+        <slot name="header">
+          <slot name="header-title">
+            ${open.header?.logo
+              ? html`<img part="header-logo" src=${open.header.logo} alt="" />`
+              : nothing}
+            <span part="header-heading">${title}</span>
+          </slot>
+          <span part="header-actions">
+            <slot name="header-actions"></slot>
+            <button
+              part="close-button"
+              type="button"
+              aria-label=${labels.close}
+              @click=${() => host.closeFromUser()}
+            >
+              <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+                <path
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="2"
+                  stroke-linecap="round"
+                  d="M6 6l12 12M18 6L6 18"
+                />
+              </svg>
+            </button>
+          </span>
+        </slot>
+      </header>
+
+      ${renderMessageList(host)} ${renderComposer(host)}
+
+      <slot name="footer"></slot>
+    </section>
+  `;
+}
+
+/**
+ * Esc closes the panel. It is handled here rather than on the host so that it
+ * only applies while the panel has focus inside it.
+ *
+ * @param {ChitUI} host
+ * @param {KeyboardEvent} event
+ */
+function onKeydown(host, event) {
+  if (event.key !== 'Escape' || event.defaultPrevented) return;
+  event.preventDefault();
+  host.closeFromUser();
+}

package/src/styles/adopted-sheet.js

@@ -0,0 +1,72 @@
+// @ts-check
+
+/**
+ * Constructable stylesheets landed in Safari 16.4 and we support 16, so the
+ * same fallback Lit uses applies here: a <style> element in the shadow root.
+ */
+const SUPPORTS_ADOPTING =
+  typeof ShadowRoot !== 'undefined' &&
+  'adoptedStyleSheets' in Document.prototype &&
+  'replaceSync' in CSSStyleSheet.prototype;
+
+/**
+ * A stylesheet the component owns and rewrites at runtime, appended after the
+ * component's static styles so its declarations win over them.
+ */
+export class AdoptedSheet {
+  /** @type {CSSStyleSheet | null} */
+  #sheet = null;
+  /** @type {HTMLStyleElement | null} */
+  #element = null;
+  /** @type {string} */
+  #written = '';
+  /** @type {string} */
+  #marker;
+
+  /** @param {string} marker  Identifies the sheet in the DOM when the fallback is used. */
+  constructor(marker) {
+    this.#marker = marker;
+  }
+
+  /** @param {ShadowRoot | HTMLElement | DocumentFragment} root */
+  attach(root) {
+    if (!(root instanceof ShadowRoot)) return;
+
+    if (SUPPORTS_ADOPTING) {
+      if (!this.#sheet) this.#sheet = new CSSStyleSheet();
+      if (!root.adoptedStyleSheets.includes(this.#sheet)) {
+        root.adoptedStyleSheets = [...root.adoptedStyleSheets, this.#sheet];
+      }
+      return;
+    }
+
+    if (!this.#element) {
+      this.#element = document.createElement('style');
+      this.#element.setAttribute(this.#marker, '');
+    }
+    if (this.#element.parentNode !== root) root.append(this.#element);
+  }
+
+  /**
+   * Replace the sheet's contents. Cheap to call on every update: identical CSS
+   * is ignored.
+   *
+   * @param {string} css
+   * @param {ShadowRoot | HTMLElement | DocumentFragment} root
+   */
+  write(css, root) {
+    if (css === this.#written) return;
+    this.attach(root);
+
+    if (this.#sheet) this.#sheet.replaceSync(css);
+    else if (this.#element) this.#element.textContent = css;
+    else return;
+
+    this.#written = css;
+  }
+
+  detach() {
+    this.#element?.remove();
+    this.#element = null;
+  }
+}

package/src/styles/composer.css.js

@@ -0,0 +1,108 @@
+// @ts-check
+import { css } from 'lit';
+
+export const composerStyles = css`
+  [part~='composer'] {
+    display: flex;
+    flex: none;
+    align-items: flex-end;
+    gap: 0.5em;
+    padding: 0.6em 0.75em;
+    border-top: 1px solid var(--chit-color-border);
+    background: var(--chit-color-input-bg);
+  }
+
+  [part~='input'] {
+    flex: 1 1 auto;
+    min-width: 0;
+    /* One row to start with, growing to the theme's limit. */
+    field-sizing: content;
+    max-height: calc(1.5em * var(--_chit-input-max-rows, 5) + 1em);
+    padding: 0.45em 0.6em;
+    border: 1px solid var(--chit-color-border);
+    border-radius: 12px;
+    background: var(--chit-color-input-bg);
+    color: var(--chit-color-input-text);
+    font: inherit;
+    line-height: 1.5;
+    resize: none;
+    overflow-y: auto;
+  }
+
+  [part~='input']::placeholder {
+    color: var(--chit-color-input-placeholder);
+  }
+
+  [part~='input']:focus-visible {
+    outline: 2px solid var(--chit-color-accent);
+    outline-offset: -1px;
+  }
+
+  [part~='input']:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+
+  [part~='counter'] {
+    align-self: center;
+    font-size: 0.75em;
+    color: var(--chit-color-system-text);
+    font-variant-numeric: tabular-nums;
+  }
+
+  [part~='counter'][data-over] {
+    color: #d93025;
+    font-weight: 600;
+  }
+
+  [part~='send-button'] {
+    display: grid;
+    flex: none;
+    place-items: center;
+    width: 2.4em;
+    height: 2.4em;
+    padding: 0;
+    border: 0;
+    border-radius: 50%;
+    background: var(--chit-color-accent);
+    color: #fff;
+    cursor: pointer;
+    transition: opacity 120ms ease;
+  }
+
+  [part~='send-button'] svg {
+    width: 1.1em;
+    height: 1.1em;
+  }
+
+  [part~='send-button']:disabled {
+    opacity: 0.4;
+    cursor: default;
+  }
+
+  [part~='send-button']:focus-visible {
+    outline: 2px solid var(--chit-color-accent);
+    outline-offset: 2px;
+  }
+
+  [part~='spinner'] {
+    width: 1.1em;
+    height: 1.1em;
+    border: 2px solid currentColor;
+    border-top-color: transparent;
+    border-radius: 50%;
+    animation: chit-spin 0.7s linear infinite;
+  }
+
+  @keyframes chit-spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [part~='spinner'] {
+      animation-duration: 2s;
+    }
+  }
+`;