@hidemikimura/chit-ui 0.1.0 → 0.2.0

package/dist/types/bundle.d.ts

@@ -1,4 +1,5 @@
 export * from "./index.js";
+export * from "./themes/index.js";
 export { repeat } from "lit/directives/repeat.js";
 export { unsafeHTML } from "lit/directives/unsafe-html.js";
 export { classMap } from "lit/directives/class-map.js";

package/dist/types/chit-ui.d.ts

@@ -213,6 +213,18 @@ export class ChitUI extends LitElement {
     handleKeydown(event: KeyboardEvent): void;
     /** @param {boolean} started */
     handleComposition(started: boolean): void;
+    /**
+     * 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: File[]): void;
+    /** Open the file picker from code, as the attach button does. */
+    openAttach(): void;
     /**
      * Render a consumer-supplied typing bubble.
      *
@@ -234,6 +246,18 @@ export class ChitUI extends LitElement {
     toggleFromUser(): Promise<boolean>;
     /** Called by the close button and by Esc. */
     closeFromUser(): Promise<boolean>;
+    /**
+     * 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?: Trigger): void;
     /** @override */
     override willUpdate(): void;
     /** @override */
@@ -249,3 +273,4 @@ import type { Labels } from './i18n/labels.js';
 import type { ChatState } from './types.js';
 import type { Device } from './types.js';
 import type { ResolvedTheme } from './types.js';
+import type { Trigger } from './types.js';

package/dist/types/events.d.ts

@@ -25,4 +25,6 @@ export const Events: Readonly<{
     MESSAGE_CLICK: "chat-message-click";
     SCROLL_TOP: "chat-scroll-top";
     BREAKPOINT_CHANGE: "chat-breakpoint-change";
+    HOME: "chat-home";
+    ATTACH: "chat-attach";
 }>;

package/dist/types/global.d.ts

@@ -15,6 +15,8 @@ export interface ChitUIEventMap {
   'chat-message-click': CustomEvent<{ message: Message; target: Element; originalEvent: MouseEvent }>;
   'chat-scroll-top': CustomEvent<Record<string, never>>;
   'chat-breakpoint-change': CustomEvent<{ device: Device }>;
+  'chat-home': CustomEvent<{ trigger: Trigger }>;
+  'chat-attach': CustomEvent<{ files: File[] }>;
 }
 
 declare global {

package/dist/types/i18n/labels.d.ts

@@ -33,10 +33,18 @@ export type Labels = {
      * Close button.
      */
     close: string;
+    /**
+     * Home button: back to the start of the conversation.
+     */
+    home: string;
     /**
      * Send button.
      */
     send: string;
+    /**
+     * Attach button beside the composer.
+     */
+    attach: string;
     /**
      * Composer textarea.
      */

package/dist/types/render/composer.d.ts

@@ -1,4 +1,3 @@
-/** @import { ChitUI } from '../chit-ui.js' */
 /**
  * The composer: a textarea that grows with its content, and a send button.
  *

package/dist/types/theme/default-theme.d.ts

@@ -20,9 +20,10 @@ export namespace defaultTheme {
         let radius: number;
         let launcher: "hidden";
         namespace header {
+            let visible: boolean;
             let title: null;
             let logo: null;
-            let avatar: null;
+            let home: boolean;
         }
         namespace background {
             let image: null;
@@ -58,6 +59,23 @@ export namespace defaultTheme {
             import inputPlaceholder = PALETTE.muted;
             export { inputPlaceholder };
         }
+        namespace bubble {
+            let radius_1: number;
+            export { radius_1 as radius };
+            export let tail: "none";
+        }
+        namespace speaker {
+            namespace assistant {
+                let name: null;
+                let avatar: null;
+            }
+            namespace user {
+                let name_1: null;
+                export { name_1 as name };
+                let avatar_1: null;
+                export { avatar_1 as avatar };
+            }
+        }
         namespace animation {
             let enter: "scale";
             let exit: "fade";
@@ -67,6 +85,9 @@ export namespace defaultTheme {
         namespace input {
             let maxRows: number;
             let placeholder: null;
+            let attach: boolean;
+            let accept: string;
+            let multiple: boolean;
         }
     }
     namespace hidden {

package/dist/types/themes/green.d.ts

@@ -0,0 +1,16 @@
+/** @import { Theme } from '../types.js' */
+/**
+ * A green messenger look: a pale blue-grey conversation background, white
+ * bubbles for them, bright green for you, tails on the top corner.
+ *
+ * This is Chit UI's own palette in that familiar shape. It carries no other
+ * product's logo, wordmark or artwork, and the greens are Chit UI's own: the
+ * deep green is dark enough that white text and the send icon clear WCAG AA
+ * on it, which the bright green of the bubbles could not do.
+ * `test/theme.test.js` re-checks every pair here, so a later tweak cannot
+ * quietly drop below AA.
+ *
+ * @type {Theme}
+ */
+export const greenTheme: Theme;
+import type { Theme } from '../types.js';

package/dist/types/themes/index.d.ts

@@ -0,0 +1 @@
+export { greenTheme } from "./green.js";

package/dist/types/types.d.ts

@@ -33,6 +33,11 @@ export type Effect = "fade" | "scale" | "slide" | "none";
  * every other file can `@import` from one place and so `tsc` can emit .d.ts.
  */
 export type Position = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+/**
+ * Public types for Chit UI. This module has no runtime value; it exists so that
+ * every other file can `@import` from one place and so `tsc` can emit .d.ts.
+ */
+export type BubbleTail = "none" | "top" | "bottom";
 export type MessageBase = {
     /**
      * Unique within the array; used as the diffing key.
@@ -40,8 +45,14 @@ export type MessageBase = {
     id: string;
     role: Role;
     time?: string | Date | undefined;
-    name?: string | undefined;
-    avatar?: string | undefined;
+    /**
+     * Overrides the theme's speaker name; null hides it.
+     */
+    name?: string | null | undefined;
+    /**
+     * Overrides the theme's speaker image; null hides it.
+     */
+    avatar?: string | null | undefined;
     status?: MessageStatus | undefined;
     streaming?: boolean | undefined;
     /**
@@ -108,6 +119,20 @@ export type ClosedTheme = {
         idle?: "none" | "pulse" | "bounce";
     }) | undefined;
 };
+/**
+ * Who is talking, as the theme describes them. A message that carries its own
+ * `name` or `avatar` wins; `null` on the message hides what the theme set.
+ */
+export type SpeakerTheme = {
+    /**
+     * Shown above the bubble.
+     */
+    name?: string | null | undefined;
+    /**
+     * Image URL for the speaker's icon.
+     */
+    avatar?: string | null | undefined;
+};
 export type OpenColors = {
     background?: string | undefined;
     text?: string | undefined;
@@ -141,21 +166,45 @@ export type OpenTheme = {
      * Keep the launcher visible while open.
      */
     launcher?: "hidden" | "visible" | undefined;
+    /**
+     * The title bar: whether it is there at all, its text, its image, and whether it offers a way back to the start.
+     */
     header?: {
+        visible?: boolean;
         title?: string | null;
         logo?: string | null;
-        avatar?: string | null;
+        home?: boolean;
     } | undefined;
     background?: {
         image?: string | null;
     } | undefined;
     colors?: OpenColors | undefined;
+    /**
+     * Bubble corner radius, and where the tail points from.
+     */
+    bubble?: {
+        radius?: number;
+        tail?: BubbleTail;
+    } | undefined;
+    /**
+     * Default name and icon per side.
+     */
+    speaker?: {
+        assistant?: SpeakerTheme;
+        user?: SpeakerTheme;
+    } | undefined;
     animation?: (Animation & {
         scroll?: "smooth" | "instant";
     }) | undefined;
+    /**
+     * Composer: rows, placeholder, and the attach button.
+     */
     input?: {
         maxRows?: number;
         placeholder?: string | null;
+        attach?: boolean;
+        accept?: string;
+        multiple?: boolean;
     } | undefined;
 };
 export type Theme = {
@@ -223,14 +272,23 @@ export type ResolvedOpen = {
     radius: number;
     launcher: "hidden" | "visible";
     header: {
+        visible: boolean;
         title: string | null;
         logo: string | null;
-        avatar: string | null;
+        home: boolean;
     };
     background: {
         image: string | null;
     };
     colors: Required<OpenColors>;
+    bubble: {
+        radius: number;
+        tail: BubbleTail;
+    };
+    speaker: {
+        assistant: Required<SpeakerTheme>;
+        user: Required<SpeakerTheme>;
+    };
     animation: {
         enter: Effect;
         exit: Effect;
@@ -240,6 +298,9 @@ export type ResolvedOpen = {
     input: {
         maxRows: number;
         placeholder: string | null;
+        attach: boolean;
+        accept: string;
+        multiple: boolean;
     };
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hidemikimura/chit-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lit-based chat widget UI: launcher, panel, themable, any HTML or Lit component as a message",
   "license": "MIT",
   "author": "Hidemi Kimura",
@@ -16,6 +16,10 @@
       "types": "./dist/types/element.d.ts",
       "default": "./src/element.js"
     },
+    "./themes.js": {
+      "types": "./dist/types/themes/index.d.ts",
+      "default": "./src/themes/index.js"
+    },
     "./dist/*": "./dist/*",
     "./package.json": "./package.json"
   },
@@ -23,6 +27,7 @@
     "src",
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": [

package/src/bundle.js

@@ -3,6 +3,7 @@
 // against, so consumers of the bundle define their message components with the
 // very same Lit instance.
 export * from './index.js';
+export * from './themes/index.js';
 export { LitElement, html, css, svg, nothing, render } from 'lit';
 export { repeat } from 'lit/directives/repeat.js';
 export { unsafeHTML } from 'lit/directives/unsafe-html.js';

package/src/chit-ui.js

@@ -387,6 +387,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 +463,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 +529,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 */

package/src/events.js

@@ -15,6 +15,8 @@ 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',
 });
 
 /**

package/src/global.d.ts

@@ -15,6 +15,8 @@ export interface ChitUIEventMap {
   'chat-message-click': CustomEvent<{ message: Message; target: Element; originalEvent: MouseEvent }>;
   'chat-scroll-top': CustomEvent<Record<string, never>>;
   'chat-breakpoint-change': CustomEvent<{ device: Device }>;
+  'chat-home': CustomEvent<{ trigger: Trigger }>;
+  'chat-attach': CustomEvent<{ files: File[] }>;
 }
 
 declare global {

package/src/i18n/labels.js

@@ -6,7 +6,9 @@
  * @property {string} panel         Accessible name of the dialog.
  * @property {string} conversation  Accessible name of the message log.
  * @property {string} close         Close button.
+ * @property {string} home          Home button: back to the start of the conversation.
  * @property {string} send          Send button.
+ * @property {string} attach        Attach button beside the composer.
  * @property {string} input         Composer textarea.
  * @property {string} typing        Announced while the other side is typing.
  * @property {string} toLatest      "Jump to newest" button.
@@ -22,7 +24,9 @@ const BUILT_IN = {
     panel: 'チャット',
     conversation: '会話',
     close: 'チャットを閉じる',
+    home: '最初に戻る',
     send: '送信',
+    attach: '画像や動画を添付',
     input: 'メッセージを入力',
     typing: '入力中',
     toLatest: '最新へ',
@@ -35,7 +39,9 @@ const BUILT_IN = {
     panel: 'Chat',
     conversation: 'Conversation',
     close: 'Close chat',
+    home: 'Back to the start',
     send: 'Send',
+    attach: 'Attach an image or video',
     input: 'Type a message',
     typing: 'Typing',
     toLatest: 'Jump to latest',

package/src/render/composer.js

@@ -4,6 +4,62 @@ import { live } from 'lit/directives/live.js';
 
 /** @import { ChitUI } from '../chit-ui.js' */
 
+/**
+ * The attach button and the file input it opens.
+ *
+ * The widget owns the picking and nothing else: it hands the chosen files to
+ * the consumer through `chat-attach` and forgets them. Uploading them, showing
+ * a preview and adding a message are all things only the consumer can do, and
+ * a half-done version here would be in the way of the real one.
+ *
+ * The input is reset after every pick so that choosing the same file twice in
+ * a row still reports the second time.
+ *
+ * @param {ChitUI} host
+ * @param {boolean} disabled
+ * @returns {import('lit').TemplateResult}
+ */
+function renderAttach(host, disabled) {
+  const labels = host.currentLabels;
+  const input = host.currentTheme.open.input;
+
+  return html`
+    <button
+      part="attach-button"
+      type="button"
+      aria-label=${labels.attach}
+      title=${labels.attach}
+      ?disabled=${disabled}
+      @click=${() => host.openAttach()}
+    >
+      <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+        <path
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          d="M20 11.5 12.2 19.3a4.6 4.6 0 0 1-6.5-6.5l7.8-7.8a3 3 0 0 1 4.3 4.3l-7.8 7.8a1.5 1.5 0 0 1-2.1-2.1l7.1-7.1"
+        />
+      </svg>
+    </button>
+    <input
+      part="attach-input"
+      type="file"
+      tabindex="-1"
+      aria-hidden="true"
+      accept=${input.accept}
+      ?multiple=${input.multiple}
+      @change=${(/** @type {Event} */ event) => {
+        const field = /** @type {HTMLInputElement} */ (event.target);
+        const files = Array.from(field.files ?? []);
+        field.value = '';
+        if (files.length) host.handleAttach(files);
+      }}
+    />
+  `;
+}
+
 /**
  * The composer: a textarea that grows with its content, and a send button.
  *
@@ -32,6 +88,8 @@ export function renderComposer(host) {
       }}
     >
       <slot name="composer">
+        ${theme.input.attach ? renderAttach(host, disabled) : nothing}
+
         <slot name="input-before"></slot>
 
         <textarea

package/src/render/message.js

@@ -45,6 +45,13 @@ export function renderMessage(host, message) {
 
   const meta = message.time || message.status;
 
+  // The theme says who is talking; a message overrides either half. `null` on
+  // the message hides what the theme set, which is how a run of replies shows
+  // the icon only on the first of them.
+  const speaker = host.currentTheme.open.speaker[message.role];
+  const avatar = message.avatar === undefined ? speaker.avatar : message.avatar;
+  const name = message.name === undefined ? speaker.name : message.name;
+
   return html`
     <article
       part="message message-${message.role}"
@@ -53,11 +60,13 @@ export function renderMessage(host, message) {
       ?data-streaming=${!!message.streaming}
       aria-busy=${message.streaming ? 'true' : 'false'}
     >
-      ${message.avatar
-        ? html`<img part="avatar" src=${message.avatar} alt="" loading="lazy" />`
-        : nothing}
+      ${avatar
+        ? html`<img part="avatar" src=${avatar} alt="" loading="lazy" />`
+        : speaker.avatar
+          ? html`<span part="avatar" data-placeholder aria-hidden="true"></span>`
+          : nothing}
       <div class="body">
-        ${message.name ? html`<span part="name">${message.name}</span>` : nothing}
+        ${name ? html`<span part="name">${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}

package/src/render/panel.js

@@ -15,7 +15,7 @@ import { renderComposer } from './composer.js';
 export function renderPanel(host) {
   const open = host.currentTheme.open;
   const labels = host.currentLabels;
-  const title = open.header?.title ?? labels.panel;
+  const title = open.header.title ?? labels.panel;
 
   return html`
     <section
@@ -26,16 +26,67 @@ export function renderPanel(host) {
       tabindex="-1"
       @keydown=${(/** @type {KeyboardEvent} */ event) => onKeydown(host, event)}
     >
+      ${open.header.visible ? renderHeader(host, title) : nothing}
+
+      ${renderMessageList(host)} ${renderComposer(host)}
+
+      <slot name="footer"></slot>
+    </section>
+  `;
+}
+
+/**
+ * The title bar.
+ *
+ * It can be left out entirely (`open.header.visible = false`), which is what a
+ * widget embedded in a host that already draws its own title bar wants — LINE
+ * LIFF, for one — rather than two stacked titles. The dialog keeps its
+ * accessible name either way: that name is read, not seen.
+ *
+ * Note that hiding it takes the close button with it. Esc and the launcher
+ * still close the panel, and the host's own chrome usually supplies the rest.
+ *
+ * @param {ChitUI} host
+ * @param {string} title
+ * @returns {import('lit').TemplateResult}
+ */
+function renderHeader(host, title) {
+  const open = host.currentTheme.open;
+  const labels = host.currentLabels;
+
+  return html`
       <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>
+            <span part="header-title">
+              ${open.header.logo
+                ? html`<img part="header-logo" src=${open.header.logo} alt="" />`
+                : nothing}
+              <span part="header-heading">${title}</span>
+            </span>
           </slot>
           <span part="header-actions">
             <slot name="header-actions"></slot>
+            ${open.header.home
+              ? html`<button
+                  part="home-button"
+                  type="button"
+                  aria-label=${labels.home}
+                  title=${labels.home}
+                  @click=${() => host.home('user')}
+                >
+                  <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+                    <path
+                      fill="none"
+                      stroke="currentColor"
+                      stroke-width="2"
+                      stroke-linejoin="round"
+                      stroke-linecap="round"
+                      d="M4 11.2 12 4l8 7.2M6.5 9.8V19h11V9.8M10 19v-4.6h4V19"
+                    />
+                  </svg>
+                </button>`
+              : nothing}
             <button
               part="close-button"
               type="button"
@@ -55,11 +106,6 @@ export function renderPanel(host) {
           </span>
         </slot>
       </header>
-
-      ${renderMessageList(host)} ${renderComposer(host)}
-
-      <slot name="footer"></slot>
-    </section>
   `;
 }
 

package/src/styles/composer.css.js

@@ -55,6 +55,45 @@ export const composerStyles = css`
     font-weight: 600;
   }
 
+  /* Out of sight, but still clickable from the button beside it. */
+  [part~='attach-input'] {
+    display: none;
+  }
+
+  [part~='attach-button'] {
+    display: grid;
+    flex: none;
+    place-items: center;
+    width: 2.4em;
+    height: 2.4em;
+    padding: 0;
+    border: 0;
+    border-radius: 50%;
+    background: transparent;
+    color: var(--chit-color-system-text);
+    cursor: pointer;
+    transition: opacity 120ms ease;
+  }
+
+  [part~='attach-button'] svg {
+    width: 1.3em;
+    height: 1.3em;
+  }
+
+  [part~='attach-button']:hover:not(:disabled) {
+    background: color-mix(in srgb, currentColor 10%, transparent);
+  }
+
+  [part~='attach-button']:focus-visible {
+    outline: 2px solid var(--chit-color-accent);
+    outline-offset: 2px;
+  }
+
+  [part~='attach-button']:disabled {
+    opacity: 0.4;
+    cursor: default;
+  }
+
   [part~='send-button'] {
     display: grid;
     flex: none;