@hidemikimura/chit-ui 0.3.0 → 0.3.2

package/skills/chit-ui/references/recipes.md

@@ -0,0 +1,204 @@
+# Chit UI レシピ
+
+よくある組み方。どれも「発言を持っているのは利用者側」という前提の上に乗っている。
+
+## 送信から返事まで（基本形）
+
+```js
+chat.addEventListener('chat-submit', async (event) => {
+  const text = event.detail.text.trim();
+  if (!text) { event.preventDefault(); return; }
+
+  const mine = { id: crypto.randomUUID(), role: 'user', text, status: 'sending' };
+  chat.messages = [...chat.messages, mine];
+  chat.busy = true;
+  chat.loading = true;
+
+  try {
+    const reply = await api.send(text);
+    chat.messages = chat.messages
+      .map((m) => (m.id === mine.id ? { ...m, status: 'sent' } : m))
+      .concat({ id: crypto.randomUUID(), role: 'assistant', text: reply });
+  } catch {
+    chat.messages = chat.messages.map((m) =>
+      m.id === mine.id ? { ...m, status: 'error' } : m,
+    );
+    chat.messages = [...chat.messages,
+      { id: crypto.randomUUID(), role: 'system', text: '送信できませんでした' }];
+  } finally {
+    chat.loading = false;
+    chat.busy = false;
+  }
+});
+```
+
+`open.loading.auto: true` にしておけば `chat.loading` の上げ下げは要らない。送信から
+相手側の発言が増えるまで自動で出て、`timeout`（ms）を過ぎれば自分で引っ込む。
+
+## ストリーミング
+
+同じ `id` の発言を書き換えていく。`streaming: true` の間は末尾にカーソルが出て、
+`aria-busy` が立つので 1 文字ずつ読み上げられない。
+
+```js
+const id = crypto.randomUUID();
+chat.messages = [...chat.messages, { id, role: 'assistant', text: '', streaming: true }];
+
+for await (const chunk of stream) {
+  chat.messages = chat.messages.map((m) =>
+    m.id === id ? { ...m, text: m.text + chunk } : m,
+  );
+}
+
+chat.messages = chat.messages.map((m) =>
+  m.id === id ? { ...m, streaming: false } : m,
+);
+```
+
+最下部にいる読み手は自動で追従する。上にさかのぼっている読み手は動かされず、
+「最新へ」のボタンが出る。
+
+## 履歴の追い読み
+
+```js
+chat.addEventListener('chat-scroll-top', async () => {
+  if (loadingOlder || !cursor) return;
+  loadingOlder = true;
+  const older = await api.history(cursor);
+  chat.messages = [...older, ...chat.messages];   // 前に足す
+  cursor = older.at(0)?.cursor ?? null;
+  loadingOlder = false;
+});
+```
+
+このイベントは最上部に着くたびに 1 回だけ出る（居座っても繰り返さない）。
+
+## シナリオ型（ホームボタンで最初に戻す）
+
+```js
+chat.theme = { open: { header: { home: true } } };
+
+chat.addEventListener('chat-home', async (event) => {
+  if (event.detail.trigger === 'user' && !confirm('最初からやり直しますか？')) return;
+  chat.messages = [firstMessage()];
+  scenario.reset();
+});
+```
+
+ボタンを押してもウィジェットは何も消さない。どこまで戻すかは利用者が決める。
+
+## 発言の中にコンポーネントを置く
+
+```js
+class OrderCard extends HTMLElement { /* props を受け取って描く */ }
+customElements.define('order-card', OrderCard);
+
+chat.messages = [...chat.messages, {
+  id: 'order-1001',
+  role: 'assistant',
+  component: 'order-card',
+  props: { orderId: '1001', total: 4800 },
+  meta: { orderId: '1001' },
+}];
+
+chat.addEventListener('chat-message-click', (event) => {
+  const action = event.detail.target.closest('[data-action]')?.dataset.action;
+  if (action === 'detail') showOrder(event.detail.message.meta.orderId);
+});
+```
+
+同じ `id` の間はインスタンスが再利用され、変わった `props` だけ再代入される。
+`chat-message-render` の `detail.instance` でインスタンスを直接触ることもできる。
+
+## 未読バッジ
+
+```html
+<chit-ui id="chat">
+  <span slot="launcher" class="badge" hidden></span>
+</chit-ui>
+```
+
+```js
+function pushFromServer(message) {
+  chat.messages = [...chat.messages, message];
+  if (chat.state !== 'open') {
+    unread += 1;
+    badge.textContent = String(unread);
+    badge.hidden = false;
+  }
+}
+
+chat.addEventListener('chat-open', () => { unread = 0; badge.hidden = true; });
+```
+
+パネルの中で上にさかのぼっている読み手に新着が届いたかどうかは `chat.hasUnseen` でわかる。
+
+## 添付ファイル
+
+```js
+chat.theme = { open: { input: { attach: true, accept: 'image/*', multiple: false } } };
+
+chat.addEventListener('chat-attach', async (event) => {
+  const [file] = event.detail.files;
+  const url = await api.upload(file);
+  chat.messages = [...chat.messages, {
+    id: crypto.randomUUID(), role: 'user',
+    html: `<img src="${url}" alt="添付した画像">`,
+  }];
+});
+```
+
+ライブラリはアップロードもプレビューもしない。同じファイルを続けて選んでも毎回発火する。
+
+## LINE LIFF など、外側がタイトルを持つ画面
+
+```js
+chat.theme = { open: { header: { visible: false } } };
+```
+
+タイトルバーごと消えるので閉じるボタンも消える。Esc とランチャーでは閉じられる。
+`title` は描かれなくても `role="dialog"` の読み上げ名には使われる。
+
+## ドラッグで動かす
+
+```js
+chat.theme = { closed: { draggable: true }, open: { draggable: true } };
+
+chat.addEventListener('chat-move', (event) => {
+  localStorage.setItem('chit-offset', JSON.stringify(event.detail.displacement));
+});
+
+const saved = localStorage.getItem('chit-offset');
+if (saved) chat.dragOffset = JSON.parse(saved);
+```
+
+閉じた状態と開いた状態は同じずれを共有するので、片方を動かせばもう片方も動く。
+`resetPosition()` でテーマの位置に戻る。保存するかどうかは利用者の判断。
+
+## ダークモード
+
+```js
+const dark = matchMedia('(prefers-color-scheme: dark)');
+const apply = () => { chat.theme = dark.matches ? darkTheme : lightTheme; };
+dark.addEventListener('change', apply);
+apply();
+```
+
+テーマは実行中に差し替えても即座に反映される。
+
+## 入力欄を消して選択肢だけで進める
+
+```js
+chat.inputHidden = true;
+chat.messages = [...chat.messages, {
+  id: 'q1', role: 'assistant',
+  html: '<p>どちらにしますか？</p><button data-choice="a">A</button><button data-choice="b">B</button>',
+}];
+
+chat.addEventListener('chat-message-click', (event) => {
+  const choice = event.detail.target.closest('[data-choice]')?.dataset.choice;
+  if (choice) chat.submit(choice === 'a' ? 'A' : 'B');
+});
+```
+
+入力欄を消しても `submit(text)` は使えるので、選択肢からの送信で会話を進められる。

package/src/chit-ui.js

@@ -9,6 +9,8 @@ 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 { ScrollLockController } from './controllers/scroll-lock-controller.js';
+import { ViewportController } from './controllers/viewport-controller.js';
 import { renderLauncher } from './render/launcher.js';
 import { renderPanel } from './render/panel.js';
 import { resolveLabels, resolveLocale } from './i18n/labels.js';
@@ -180,6 +182,10 @@ export class ChitUI extends LitElement {
       behavior: () => this.currentTheme.open.animation.scroll,
     });
     this.#composer = new ComposerController(this);
+    // Both register themselves with the host and need nothing from us
+    // afterwards.
+    new ScrollLockController(this);
+    new ViewportController(this, { enabled: () => this.device === 'mobile' });
 
     this.#launcherDrag = new DragController(this, {
       name: 'launcher',

package/src/controllers/scroll-controller.js

@@ -49,6 +49,13 @@ export class ScrollController {
   /** The first jump after the panel opens has nothing to animate from. */
   #openingJump = true;
 
+  /**
+   * The viewport's height as of the last reading. A scroll event that arrives
+   * with a different height is the box having been resized under the reader —
+   * a keyboard opening, say — and says nothing about where they chose to be.
+   */
+  #viewportHeight = 0;
+
   /** @type {string | undefined} */
   #lastId;
   #lastCount = 0;
@@ -127,16 +134,21 @@ export class ScrollController {
 
   #bind() {
     if (!this.#viewport) return;
+    this.#viewportHeight = this.#viewport.clientHeight;
     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.
+    // without a scroll event, so the follow has to react to size too. The
+    // viewport is watched alongside the content because a keyboard opening
+    // shortens the list without touching what is in it, and the newest
+    // message would otherwise slide out of sight.
     const inner = this.#viewport.firstElementChild;
     if (inner && typeof ResizeObserver !== 'undefined') {
       this.#resize = new ResizeObserver(() => {
+        this.#viewportHeight = this.#viewport?.clientHeight ?? 0;
         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
@@ -147,6 +159,7 @@ export class ScrollController {
         this.#scrollNow({ behavior: this.#selfScrolling ? 'smooth' : 'instant' });
       });
       this.#resize.observe(inner);
+      this.#resize.observe(this.#viewport);
     }
   }
 
@@ -166,6 +179,13 @@ export class ScrollController {
     const viewport = this.#viewport;
     if (!viewport) return;
 
+    // The box changed size under this scroll, so the reader did not move:
+    // the resize handler below puts them back where they were.
+    if (viewport.clientHeight !== this.#viewportHeight) {
+      this.#viewportHeight = viewport.clientHeight;
+      return;
+    }
+
     const distance = viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight;
     const atBottom = distance <= BOTTOM_SLACK;
 

package/src/controllers/scroll-lock-controller.js

@@ -0,0 +1,185 @@
+// @ts-check
+
+/** @import { ReactiveController, LitElement } from 'lit' */
+
+/** How far a finger must travel before the gesture's direction is trusted. */
+const THRESHOLD = 3;
+
+/** Slack on the "is there anywhere left to scroll" reading, in pixels. */
+const EDGE_SLACK = 1;
+
+/** Overflow values that make an element a scroll container. */
+const SCROLLABLE = /^(auto|scroll|overlay)$/;
+
+/**
+ * Keeps a touch that lands on the open panel from scrolling the page behind
+ * it.
+ *
+ * `overscroll-behavior: contain` is on the message list already, and it does
+ * the job for the case it covers: a list that can scroll, dragged past its
+ * own end. It has nothing to say about the cases that actually leak. A short
+ * conversation does not overflow, so the list is not a scroll container at
+ * all and the touch goes straight through to the document — which is what a
+ * reader on an iPhone sees as the page sliding around underneath a chat that
+ * looks like it should be holding still. The same happens for a touch that
+ * starts on the title bar or beside the input.
+ *
+ * So the rule is decided here instead: a touch on the panel may scroll
+ * something inside the panel, and otherwise it does nothing. On the first
+ * move of each gesture the controller looks along the touch's own path —
+ * `composedPath`, so a scroller inside a consumer's component counts too —
+ * for something that can still travel in the direction the finger is going.
+ * Finding one, it stands aside for the rest of the gesture; finding none, it
+ * cancels the move, and iOS then takes the whole gesture as "not a scroll".
+ *
+ * Two touches are left alone: that is a pinch, and zooming is the reader's.
+ * A move that is no longer cancelable is left alone too — the browser has
+ * already committed to scrolling, and `overscroll-behavior` is what keeps
+ * that inside the list.
+ *
+ * @implements {ReactiveController}
+ */
+export class ScrollLockController {
+  /** @type {LitElement} */
+  #host;
+
+  /** @type {HTMLElement | null} */
+  #panel = null;
+
+  /**
+   * The gesture in flight: where it started, and what was decided about it.
+   *
+   * @type {{ x: number, y: number, verdict: 'undecided' | 'allow' | 'block' } | undefined}
+   */
+  #touch;
+
+  /** @param {LitElement} host */
+  constructor(host) {
+    this.#host = host;
+    host.addController(this);
+  }
+
+  hostUpdated() {
+    const panel = /** @type {HTMLElement | null} */ (
+      this.#host.renderRoot?.querySelector('[part~="panel"]') ?? null
+    );
+    if (panel === this.#panel) return;
+
+    this.#unbind();
+    this.#panel = panel;
+    this.#bind();
+  }
+
+  hostDisconnected() {
+    this.#unbind();
+  }
+
+  #bind() {
+    const panel = this.#panel;
+    if (!panel) return;
+    panel.addEventListener('touchstart', this.#onStart, { passive: true });
+    // Cancelling a move is the whole point, so this one cannot be passive.
+    panel.addEventListener('touchmove', this.#onMove, { passive: false });
+    panel.addEventListener('touchend', this.#onEnd, { passive: true });
+    panel.addEventListener('touchcancel', this.#onEnd, { passive: true });
+  }
+
+  #unbind() {
+    const panel = this.#panel;
+    if (!panel) return;
+    panel.removeEventListener('touchstart', this.#onStart);
+    panel.removeEventListener('touchmove', this.#onMove);
+    panel.removeEventListener('touchend', this.#onEnd);
+    panel.removeEventListener('touchcancel', this.#onEnd);
+    this.#panel = null;
+    this.#touch = undefined;
+  }
+
+  /** @param {TouchEvent} event */
+  #onStart = (event) => {
+    if (event.touches.length !== 1) {
+      this.#touch = undefined;
+      return;
+    }
+    const touch = event.touches[0];
+    this.#touch = { x: touch.clientX, y: touch.clientY, verdict: 'undecided' };
+  };
+
+  #onEnd = () => {
+    this.#touch = undefined;
+  };
+
+  /** @param {TouchEvent} event */
+  #onMove = (event) => {
+    const from = this.#touch;
+    if (!from) return;
+
+    // A second finger arriving turns this into a pinch. Hands off for the
+    // rest of the gesture, zoom included.
+    if (event.touches.length > 1) {
+      this.#touch = undefined;
+      return;
+    }
+
+    if (from.verdict === 'block') {
+      if (event.cancelable) event.preventDefault();
+      return;
+    }
+    if (from.verdict === 'allow') return;
+
+    const touch = event.touches[0];
+    const dx = touch.clientX - from.x;
+    const dy = touch.clientY - from.y;
+    // Too small to read a direction from, and too small for the browser to
+    // have started scrolling either.
+    if (Math.abs(dx) < THRESHOLD && Math.abs(dy) < THRESHOLD) return;
+
+    const vertical = Math.abs(dy) >= Math.abs(dx);
+    const allowed = this.#canScroll(event, vertical, vertical ? dy : dx);
+    from.verdict = allowed ? 'allow' : 'block';
+    if (!allowed && event.cancelable) event.preventDefault();
+  };
+
+  /**
+   * Is there something between the touch and the panel that can still scroll
+   * the way the finger is going?
+   *
+   * @param {TouchEvent} event
+   * @param {boolean} vertical
+   * @param {number} delta Positive when the finger moves down, or right.
+   * @returns {boolean}
+   */
+  #canScroll(event, vertical, delta) {
+    const panel = this.#panel;
+    if (!panel) return true;
+
+    for (const node of event.composedPath()) {
+      if (!(node instanceof HTMLElement)) continue;
+
+      if (this.#hasRoom(node, vertical, delta)) return true;
+      if (node === panel) break;
+    }
+    return false;
+  }
+
+  /**
+   * @param {HTMLElement} element
+   * @param {boolean} vertical
+   * @param {number} delta
+   * @returns {boolean}
+   */
+  #hasRoom(element, vertical, delta) {
+    const style = getComputedStyle(element);
+    const overflow = vertical ? style.overflowY : style.overflowX;
+    if (!SCROLLABLE.test(overflow)) return false;
+
+    const position = vertical ? element.scrollTop : element.scrollLeft;
+    const size = vertical ? element.clientHeight : element.clientWidth;
+    const content = vertical ? element.scrollHeight : element.scrollWidth;
+    if (content <= size + EDGE_SLACK) return false;
+
+    // A finger moving down pulls the content down, which means reading from
+    // further up: there has to be something above the current position.
+    return delta > 0 ? position > EDGE_SLACK : position < content - size - EDGE_SLACK;
+  }
+}

package/src/controllers/viewport-controller.js

@@ -0,0 +1,102 @@
+// @ts-check
+
+/** @import { ReactiveController, LitElement } from 'lit' */
+
+/**
+ * Past this the reader has pinched to zoom, and the widget stays out of it.
+ * A little over 1 because browsers report scales like 1.0000002.
+ */
+const ZOOMED = 1.01;
+
+/**
+ * Keeps the full-screen panel inside the part of the screen the reader can
+ * actually see.
+ *
+ * On a phone the panel is `position: fixed` across the whole viewport, and
+ * that viewport is not what is on screen once a keyboard slides up: the
+ * layout viewport keeps its full height, so the composer — and with it the
+ * last few messages — ends up behind the keyboard. iOS then scrolls the page
+ * to chase the focused field, which moves the fixed panel out of frame
+ * instead of helping. `dvh` is no use here either; it tracks the browser's
+ * own chrome collapsing, not the keyboard.
+ *
+ * `visualViewport` is the one thing that does report the visible box, so the
+ * panel is pinned to it: its top to `offsetTop`, its height to `height`. The
+ * composer lands just above the keyboard, and the conversation gets whatever
+ * is left.
+ *
+ * A pinch is left alone. Zooming is how a reader gets a closer look, and a
+ * panel that re-fitted itself to the magnified box would take that away by
+ * reflowing the text back to the same apparent size.
+ *
+ * @implements {ReactiveController}
+ */
+export class ViewportController {
+  /** @type {LitElement} */
+  #host;
+
+  /** @type {() => boolean} */
+  #enabled;
+
+  /** @type {(() => void) | undefined} */
+  #onChange;
+
+  /** True while the custom properties are set, to avoid pointless writes. */
+  #applied = false;
+
+  /**
+   * @param {LitElement} host
+   * @param {{ enabled: () => boolean }} options
+   */
+  constructor(host, { enabled }) {
+    this.#host = host;
+    this.#enabled = enabled;
+    host.addController(this);
+  }
+
+  hostConnected() {
+    const viewport = window.visualViewport;
+    if (!viewport) return;
+
+    this.#onChange = () => this.#apply();
+    // Resize is the keyboard arriving and leaving; scroll is iOS shifting the
+    // visible box around while it is up.
+    viewport.addEventListener('resize', this.#onChange);
+    viewport.addEventListener('scroll', this.#onChange);
+  }
+
+  hostDisconnected() {
+    const viewport = window.visualViewport;
+    if (viewport && this.#onChange) {
+      viewport.removeEventListener('resize', this.#onChange);
+      viewport.removeEventListener('scroll', this.#onChange);
+    }
+    this.#onChange = undefined;
+    this.#clear();
+  }
+
+  hostUpdated() {
+    this.#apply();
+  }
+
+  #apply() {
+    const viewport = window.visualViewport;
+    const panel = this.#host.renderRoot?.querySelector('[part~="panel"]');
+
+    if (!viewport || !panel || !this.#enabled() || viewport.scale > ZOOMED) {
+      this.#clear();
+      return;
+    }
+
+    this.#host.style.setProperty('--_chit-vv-top', `${Math.round(viewport.offsetTop)}px`);
+    this.#host.style.setProperty('--_chit-vv-height', `${Math.round(viewport.height)}px`);
+    this.#applied = true;
+  }
+
+  #clear() {
+    if (!this.#applied) return;
+    this.#host.style.removeProperty('--_chit-vv-top');
+    this.#host.style.removeProperty('--_chit-vv-height');
+    this.#applied = false;
+  }
+}

package/src/index.js

@@ -7,3 +7,37 @@ if (!customElements.get('chit-ui')) {
 
 export { ChitUI };
 export { Events } from './events.js';
+
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ *
+ * @typedef {import('./types.js').Role} Role
+ * @typedef {import('./types.js').MessageStatus} MessageStatus
+ * @typedef {import('./types.js').ChatState} ChatState
+ * @typedef {import('./types.js').Trigger} Trigger
+ * @typedef {import('./types.js').Device} Device
+ * @typedef {import('./types.js').Effect} Effect
+ * @typedef {import('./types.js').Position} Position
+ * @typedef {import('./types.js').BubbleTail} BubbleTail
+ * @typedef {import('./types.js').LoadingStyle} LoadingStyle
+ * @typedef {import('./types.js').MessageBase} MessageBase
+ * @typedef {import('./types.js').TextMessage} TextMessage
+ * @typedef {import('./types.js').HtmlMessage} HtmlMessage
+ * @typedef {import('./types.js').TemplateMessage} TemplateMessage
+ * @typedef {import('./types.js').ElementMessage} ElementMessage
+ * @typedef {import('./types.js').ComponentMessage} ComponentMessage
+ * @typedef {import('./types.js').Message} Message
+ * @typedef {import('./types.js').Animation} Animation
+ * @typedef {import('./types.js').Offset} Offset
+ * @typedef {import('./types.js').ClosedTheme} ClosedTheme
+ * @typedef {import('./types.js').OpenColors} OpenColors
+ * @typedef {import('./types.js').SpeakerTheme} SpeakerTheme
+ * @typedef {import('./types.js').LoadingTheme} LoadingTheme
+ * @typedef {import('./types.js').OpenTheme} OpenTheme
+ * @typedef {import('./types.js').Theme} Theme
+ * @typedef {import('./types.js').ResolvedClosed} ResolvedClosed
+ * @typedef {import('./types.js').ResolvedOpen} ResolvedOpen
+ * @typedef {import('./types.js').ResolvedTheme} ResolvedTheme
+ */

package/src/styles/composer.css.js

@@ -29,6 +29,24 @@ export const composerStyles = css`
     overflow-y: auto;
   }
 
+  /*
+   * iOS Safari zooms the page in whenever a field smaller than 16px takes
+   * focus, and it does not zoom back out when the field is done with — the
+   * reader is left with a widget wider than the screen and no obvious way
+   * back. Nothing in the page can undo that zoom short of pinning the
+   * viewport's scale, which would also take pinch-zoom away from everyone.
+   * So the field is kept at the size that never triggers it, and larger
+   * still if the theme's font is larger.
+   *
+   * Coarse pointers only: on a desktop the same rule would make the field
+   * stand out from the rest of the widget for no reason.
+   */
+  @media (pointer: coarse) {
+    [part~='input'] {
+      font-size: max(16px, 1em);
+    }
+  }
+
   [part~='input']::placeholder {
     color: var(--chit-color-input-placeholder);
   }

package/src/styles/panel.css.js

@@ -56,12 +56,18 @@ export const panelStyles = css`
    * A phone gets the whole screen. dvh rather than vh so the browser chrome
    * collapsing does not leave a gap, and the safe-area insets keep the header
    * clear of the notch.
+   *
+   * While a keyboard is up, the two --_chit-vv-* properties carry what is
+   * actually on screen (ViewportController fills them in from
+   * visualViewport); dvh knows nothing about a keyboard and would leave the
+   * composer behind it.
    */
   :host([data-device='mobile']) [part~='panel'],
   :host([data-device='mobile'][data-panel-position]) [part~='panel'] {
     inset: 0;
+    top: var(--_chit-vv-top, 0px);
     width: 100vw;
-    height: 100dvh;
+    height: var(--_chit-vv-height, 100dvh);
     max-width: none;
     max-height: none;
     border-radius: 0;