@inglorious/ui 9.4.0 → 9.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ui",
-  "version": "9.4.0",
+  "version": "9.5.1",
   "description": "A design system for Inglorious Web with render-function components and customizable themes",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -54,6 +54,11 @@
       "import": "./src/controls/button-group/index.js"
     },
     "./button-group.css": "./src/controls/button-group/style.css",
+    "./chat": {
+      "types": "./types/data-display/chat.d.ts",
+      "import": "./src/data-display/chat/index.js"
+    },
+    "./chat.css": "./src/data-display/chat/style.css",
     "./carousel": {
       "types": "./types/data-display/carousel.d.ts",
       "import": "./src/data-display/carousel/index.js"
@@ -308,19 +313,19 @@
   "peerDependencies": {
     "@inglorious/store": "12.0.0",
     "@inglorious/utils": "5.1.0",
-    "@inglorious/web": "6.9.0"
+    "@inglorious/web": "6.9.1"
   },
   "devDependencies": {
     "@iconify-icons/fa7-brands": "^2.0.0",
     "@iconify-icons/fa7-regular": "^2.0.0",
     "@iconify-icons/fa7-solid": "^2.0.0",
     "@iconify-icons/material-symbols": "^2.0.6",
-    "@inglorious/charts": "12.2.1",
+    "@inglorious/charts": "12.2.2",
     "@inglorious/eslint-config": "1.2.0",
     "@inglorious/store": "12.0.0",
     "@inglorious/vite-plugin-jsx": "2.0.5",
     "@inglorious/vite-plugin-vue": "1.0.6",
-    "@inglorious/web": "6.9.0",
+    "@inglorious/web": "6.9.1",
     "@storybook/addon-docs": "^10.6.0",
     "@storybook/web-components-vite": "^10.6.0",
     "happy-dom": "^20.14.0",

package/src/controls/textarea/style.css

@@ -4,8 +4,13 @@
   gap: var(--iw-space-1);
   font-family: var(--iw-font-family-sans);
 
-  &.iw-textarea-full-width .iw-textarea {
+  /* The field takes the width it is given, and the box inside fills it. */
+  &.iw-textarea-full-width {
     width: 100%;
+
+    .iw-textarea {
+      width: 100%;
+    }
   }
 
   .iw-textarea-label {
@@ -19,8 +24,8 @@
     margin-inline-start: var(--iw-space-1);
   }
 
+  /* Its height is its rows', or its content's with isAutoSize. */
   .iw-textarea {
-    min-height: 3rem;
     width: min(100%, 100%);
     resize: none;
     padding: var(--iw-space-2) var(--iw-space-3);

package/src/controls/textarea/template.js

@@ -24,6 +24,7 @@ export function render(props) {
     value = "",
     placeholder = "",
     label,
+    ariaLabel,
     hint,
     error,
     size = "md",
@@ -37,6 +38,7 @@ export function render(props) {
     onChange,
     onBlur,
     onFocus,
+    onKeyDown,
     ...rest
   } = props
 
@@ -76,7 +78,7 @@ export function render(props) {
       <textarea
         id=${textareaId || nothing}
         name=${name}
-        aria-label=${fallbackLabel(textareaId, label)}
+        aria-label=${ariaLabel || fallbackLabel(textareaId, label)}
         aria-describedby=${messageId || nothing}
         aria-invalid=${error ? "true" : "false"}
         rows=${rows}
@@ -89,6 +91,7 @@ export function render(props) {
         @input=${(event) => onChange?.(event.target.value)}
         @blur=${onBlur}
         @focus=${onFocus}
+        @keydown=${onKeyDown}
         ${ref((element) => applyElementProps(element, rest))}
       ></textarea>
 

package/src/data-display/chat/chat.stories.js

@@ -0,0 +1,90 @@
+import {
+  createEntityRender,
+  notifyActionArgType,
+} from "../../stories/notify-story.js"
+import { Chat } from "."
+
+/** A chat fills its container, which sets its height. */
+const withHeight = (story) => {
+  const frame = document.createElement("div")
+  frame.style.height = "28rem"
+  const chat = story()
+  chat.style.height = "100%"
+  frame.append(chat)
+  return frame
+}
+
+const conversation = [
+  { id: "m1", role: "user", content: "Where did my money go this month?" },
+  {
+    id: "m2",
+    role: "assistant",
+    content:
+      "Rent took €900 of the €1,076 you spent. Food came next, at €173, then transport at €58.",
+  },
+  { id: "m3", role: "user", content: "How can I spend less on food?" },
+]
+
+export default {
+  title: "Data Display/Chat",
+  tags: ["autodocs"],
+  render: createEntityRender({ Chat }),
+  decorators: [withHeight],
+  argTypes: {
+    ...notifyActionArgType,
+    messages: {
+      control: "object",
+      description:
+        "Messages: `{ id, role, content }`, or `{ id, role, entity }` to render another entity, such as a generated answer.",
+    },
+    draft: { control: "text", description: "What the user is typing." },
+    isBusy: {
+      control: "boolean",
+      description: "A reply is on its way: shows it, and holds sending.",
+    },
+    error: { control: "text", description: "Why the last reply failed." },
+    suggestions: {
+      control: "object",
+      description: "Messages to start with, while the chat is empty.",
+    },
+    placeholder: { control: "text" },
+    sendLabel: { control: "text" },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A conversation and a box to write in. The chat keeps the messages and the draft; the app answers by handling `messageSend`, and adds replies with `messageAdd`, `replyStart` and `replyEnd`. Enter sends, Shift+Enter starts a new line.",
+      },
+    },
+  },
+}
+
+export const Default = {
+  args: { id: "chat", type: "Chat", messages: conversation },
+}
+
+export const Suggestions = {
+  args: {
+    id: "chatSuggestions",
+    type: "Chat",
+    messages: [],
+    suggestions: [
+      "Where did my money go this month?",
+      "Show my food expenses",
+      "I want to add an expense",
+    ],
+  },
+}
+
+export const Replying = {
+  args: { ...Default.args, id: "chatReplying", isBusy: true },
+}
+
+export const Failed = {
+  args: {
+    ...Default.args,
+    id: "chatFailed",
+    error: "Could not reach the model. Is Ollama running?",
+  },
+}

package/src/data-display/chat/handlers.js

@@ -0,0 +1,95 @@
+/**
+ * @typedef {import('../../../types/data-display/chat').ChatEntity} ChatEntity
+ * @typedef {import('../../../types/data-display/chat').ChatMessage} ChatMessage
+ */
+
+/**
+ * Fills in a chat's defaults. A chat keeps its messages and the draft being
+ * typed; who answers, and how, is the app's to decide by handling
+ * `messageSend`.
+ * @param {ChatEntity} entity
+ */
+export function create(entity) {
+  entity.messages ??= []
+  entity.draft ??= ""
+  entity.isBusy ??= false
+  entity.error ??= null
+  entity.suggestions ??= []
+  entity.messageCount ??= entity.messages.length
+}
+
+/**
+ * Keeps what the user is typing.
+ * @param {ChatEntity} entity
+ * @param {string} draft
+ */
+export function draftChange(entity, draft) {
+  entity.draft = draft
+}
+
+/**
+ * Adds the user's message: the text given, such as a suggestion picked, or
+ * else the draft, which it clears. Nothing is sent while a reply is coming,
+ * nor an empty message. Apps answer by handling this event after the chat.
+ * @param {ChatEntity} entity
+ * @param {string} [text]
+ */
+export function messageSend(entity, text) {
+  const content = (text ?? entity.draft).trim()
+  if (!content || entity.isBusy) return
+
+  addMessage(entity, { role: "user", content })
+  entity.draft = ""
+  entity.error = null
+}
+
+/**
+ * Adds a message, such as the assistant's reply: its text as `content`, or
+ * the id of an entity that renders it as `entity`.
+ * @param {ChatEntity} entity
+ * @param {Partial<ChatMessage>} message
+ */
+export function messageAdd(entity, message) {
+  addMessage(entity, { role: "assistant", ...message })
+}
+
+/**
+ * A reply is on its way: the chat says so, and waits for it to send again.
+ * @param {ChatEntity} entity
+ */
+export function replyStart(entity) {
+  entity.isBusy = true
+  entity.error = null
+}
+
+/**
+ * The reply is whole.
+ * @param {ChatEntity} entity
+ */
+export function replyEnd(entity) {
+  entity.isBusy = false
+}
+
+/**
+ * The reply failed: the chat shows why, and can send again.
+ * @param {ChatEntity} entity
+ * @param {string} error
+ */
+export function replyFail(entity, error) {
+  entity.isBusy = false
+  entity.error = error
+}
+
+/**
+ * Starts the conversation over.
+ * @param {ChatEntity} entity
+ */
+export function messagesClear(entity) {
+  entity.messages = []
+  entity.error = null
+}
+
+function addMessage(entity, message) {
+  entity.messageCount = (entity.messageCount ?? entity.messages.length) + 1
+  entity.messages.push({ id: `m${entity.messageCount}`, ...message })
+}

package/src/data-display/chat/index.js

@@ -0,0 +1,19 @@
+import * as handlers from "./handlers.js"
+import { Chat as renderers } from "./template.js"
+
+export const Chat = {
+  ...handlers,
+  ...renderers,
+  render(entity, api) {
+    const id = entity.id
+    const props = {
+      ...entity,
+      onDraftChange: (draft) => api.notify(`#${id}:draftChange`, draft),
+      onSend: (text) => api.notify(`#${id}:messageSend`, text),
+      // A message naming an entity, such as a generated answer, shows it.
+      renderEntity: (entityId) => api.render(entityId),
+    }
+
+    return this.renderChat(props)
+  },
+}

package/src/data-display/chat/style.css

@@ -0,0 +1,114 @@
+@import "../../controls/button/style.css";
+@import "../../controls/textarea/style.css";
+@import "../../feedback/alert/style.css";
+
+.iw-chat {
+  display: flex;
+  flex-direction: column;
+  gap: var(--iw-space-3);
+  block-size: 100%;
+  min-block-size: 0;
+  font-family: var(--iw-font-family-sans);
+  color: var(--iw-color-text);
+
+  .iw-chat-messages {
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    gap: var(--iw-space-4);
+    min-block-size: 0;
+    overflow-y: auto;
+    overscroll-behavior: contain;
+  }
+
+  .iw-chat-message {
+    display: flex;
+  }
+
+  .iw-chat-message-user {
+    justify-content: flex-end;
+
+    .iw-chat-message-content {
+      max-inline-size: 80%;
+      padding: var(--iw-space-2) var(--iw-space-3);
+      border-radius: var(--iw-radius-lg);
+      background: color-mix(in srgb, var(--iw-color-primary) 14%, transparent);
+      overflow-wrap: anywhere;
+    }
+  }
+
+  .iw-chat-message-assistant .iw-chat-message-content {
+    inline-size: 100%;
+    min-inline-size: 0;
+  }
+
+  /* A message's own line breaks show; the template's around it do not. */
+  .iw-chat-text {
+    white-space: pre-wrap;
+  }
+
+  .iw-chat-typing {
+    display: flex;
+    gap: var(--iw-space-1);
+    padding: var(--iw-space-2) 0;
+  }
+
+  .iw-chat-typing-dot {
+    inline-size: 0.5rem;
+    block-size: 0.5rem;
+    border-radius: 50%;
+    background: var(--iw-color-text-muted);
+    animation: iw-chat-typing 1.2s infinite ease-in-out;
+
+    &:nth-child(2) {
+      animation-delay: 0.15s;
+    }
+
+    &:nth-child(3) {
+      animation-delay: 0.3s;
+    }
+  }
+
+  .iw-chat-suggestions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--iw-space-2);
+  }
+
+  .iw-chat-composer {
+    display: flex;
+    align-items: flex-end;
+    gap: var(--iw-space-2);
+
+    .iw-textarea-field {
+      flex: 1 1 auto;
+      min-inline-size: 0;
+    }
+
+    /* The box grows with the message up to a point, then scrolls. */
+    .iw-textarea {
+      max-block-size: 10rem;
+    }
+  }
+}
+
+@keyframes iw-chat-typing {
+  0%,
+  80%,
+  100% {
+    opacity: 0.3;
+    transform: translateY(0);
+  }
+
+  40% {
+    opacity: 1;
+    transform: translateY(-0.2rem);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .iw-chat .iw-chat-typing-dot {
+    animation: none;
+    opacity: 0.6;
+  }
+}

package/src/data-display/chat/template.js

@@ -0,0 +1,209 @@
+/**
+ * @typedef {import('../../../types/data-display/chat').ChatProps} ChatProps
+ * @typedef {import('../../../types/data-display/chat').ChatMessage} ChatMessage
+ * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
+ */
+
+import { html } from "@inglorious/web"
+import { ref } from "@inglorious/web/directives/ref"
+import { repeat } from "@inglorious/web/directives/repeat"
+import { when } from "@inglorious/web/directives/when"
+
+import { Button } from "../../controls/button/index.js"
+import { Textarea } from "../../controls/textarea/index.js"
+import { Alert } from "../../feedback/alert/index.js"
+
+/** How close to the bottom, in pixels, still counts as reading the latest. */
+const PINNED_DISTANCE = 40
+const TYPING_DOTS = 3
+
+export const Chat = {
+  /**
+   * Main entrypoint for the chat template. It delegates to `renderChat` so overrides can still reuse it.
+   * A chat shows a conversation, the assistant's replies as they come, and a box to write the next message.
+   * @param {ChatProps} props The chat props.
+   * @returns {TemplateResult} The rendered chat.
+   */
+  render(props) {
+    return this.renderChat(props)
+  },
+
+  /**
+   * Renders the conversation, any error, the suggestions while it is empty, and the composer.
+   * @param {ChatProps} props The chat props.
+   * @returns {TemplateResult} The rendered chat.
+   */
+  renderChat(props) {
+    const {
+      messages = [],
+      isBusy = false,
+      error,
+      suggestions = [],
+      label = "Chat",
+    } = props
+
+    return html`<section class="iw-chat" aria-label=${label}>
+      <div
+        class="iw-chat-messages"
+        role="log"
+        aria-live="polite"
+        @scroll=${keepPinned}
+        ${ref(followLatest)}
+      >
+        ${repeat(
+          messages,
+          (message) => message.id,
+          (message) => this.renderMessage?.(props, message),
+        )}
+        ${when(isBusy, () => this.renderTyping?.(props))}
+      </div>
+      ${when(error, () => Alert.render({ severity: "error", description: error }))}
+      ${when(!messages.length && suggestions.length, () =>
+        this.renderSuggestions?.(props),
+      )}
+      ${this.renderComposer?.(props)}
+    </section>`
+  },
+
+  /**
+   * Renders one message: the user's in a bubble, the assistant's across the chat.
+   * Override to show who wrote it, or when.
+   * @param {ChatProps} props The chat props.
+   * @param {ChatMessage} message The message.
+   * @returns {TemplateResult} The rendered message.
+   */
+  renderMessage(props, message) {
+    const isUser = message.role === "user"
+    const author = isUser
+      ? (props.userLabel ?? "You")
+      : (props.assistantLabel ?? "Assistant")
+
+    return html`<article
+      class="iw-chat-message iw-chat-message-${isUser ? "user" : "assistant"}"
+      aria-label=${author}
+    >
+      <div class="iw-chat-message-content">
+        ${this.renderContent?.(props, message)}
+      </div>
+    </article>`
+  },
+
+  /**
+   * Renders what a message says: its `content`, or what `renderEntity` draws for its `entity`.
+   * @param {ChatProps} props The chat props.
+   * @param {ChatMessage} message The message.
+   * @returns {unknown} The message's content.
+   */
+  renderContent(props, message) {
+    return when(
+      message.entity && props.renderEntity,
+      () => props.renderEntity(message.entity),
+      () => html`<span class="iw-chat-text">${message.content}</span>`,
+    )
+  },
+
+  /**
+   * Renders the sign that a reply is on its way.
+   * @param {ChatProps} props The chat props.
+   * @returns {TemplateResult} The rendered indicator.
+   */
+  renderTyping(props) {
+    const author = props.assistantLabel ?? "Assistant"
+    return html`<div
+      class="iw-chat-typing"
+      role="status"
+      aria-label=${`${author} is replying`}
+    >
+      ${Array.from(
+        { length: TYPING_DOTS },
+        () => html`<span class="iw-chat-typing-dot"></span>`,
+      )}
+    </div>`
+  },
+
+  /**
+   * Renders the messages the user may start with, while the chat is empty.
+   * @param {ChatProps} props The chat props.
+   * @returns {TemplateResult} The rendered suggestions.
+   */
+  renderSuggestions(props) {
+    return html`<div class="iw-chat-suggestions">
+      ${props.suggestions.map((suggestion) =>
+        Button.render({
+          variant: "outline",
+          size: "sm",
+          children: suggestion,
+          isDisabled: props.isBusy,
+          onClick: () => props.onSend?.(suggestion),
+        }),
+      )}
+    </div>`
+  },
+
+  /**
+   * Renders the box to write a message in, which grows with it, and the button that sends it.
+   * Enter sends; Shift+Enter starts a new line.
+   * @param {ChatProps} props The chat props.
+   * @returns {TemplateResult} The rendered composer.
+   */
+  renderComposer(props) {
+    const { draft = "", isBusy = false } = props
+    const send = () => props.onSend?.()
+
+    return html`<form
+      class="iw-chat-composer"
+      @submit=${(event) => {
+        event.preventDefault()
+        send()
+      }}
+    >
+      ${Textarea.render({
+        name: "message",
+        ariaLabel: props.placeholder ?? "Message",
+        placeholder: props.placeholder ?? "Message",
+        value: draft,
+        rows: 1,
+        isAutoSize: true,
+        isFullWidth: true,
+        onChange: (value) => props.onDraftChange?.(value),
+        onKeyDown: (event) => {
+          // Enter sends, unless it closes a character being composed.
+          if (event.key !== "Enter" || event.shiftKey || event.isComposing) {
+            return
+          }
+          event.preventDefault()
+          send()
+        },
+      })}
+      ${Button.render({
+        buttonType: "submit",
+        color: "primary",
+        children: props.sendLabel ?? "Send",
+        isDisabled: isBusy || !draft.trim(),
+      })}
+    </form>`
+  },
+}
+
+/**
+ * Notes whether the user is reading the latest messages, at the bottom, or
+ * has scrolled up to read earlier ones.
+ * @param {Event} event
+ */
+function keepPinned(event) {
+  const log = event.currentTarget
+  const distance = log.scrollHeight - log.scrollTop - log.clientHeight
+  log.dataset.isPinned = String(distance < PINNED_DISTANCE)
+}
+
+/**
+ * After each render, scrolls to the latest message, unless the user has
+ * scrolled up to read.
+ * @param {Element | undefined} log
+ */
+function followLatest(log) {
+  if (!log) return
+  queueMicrotask(() => {
+    if (log.dataset.isPinned !== "false") log.scrollTop = log.scrollHeight
+  })
+}

package/src/data-display/data-display.css

@@ -2,6 +2,7 @@
 @import "./badge/style.css";
 @import "./before-after/style.css";
 @import "./carousel/style.css";
+@import "./chat/style.css";
 @import "./chip/style.css";
 @import "./data-grid/style.css";
 @import "./divider/style.css";

package/src/index.js

@@ -20,6 +20,7 @@ export { Avatar } from "./data-display/avatar/index.js"
 export { Badge } from "./data-display/badge/index.js"
 export { BeforeAfter } from "./data-display/before-after/index.js"
 export { Carousel } from "./data-display/carousel/index.js"
+export { Chat } from "./data-display/chat/index.js"
 export { Chip } from "./data-display/chip/index.js"
 export { DataGrid } from "./data-display/data-grid/index.js"
 export { Divider } from "./data-display/divider/index.js"

package/types/controls/textarea.d.ts

@@ -6,6 +6,8 @@ export interface TextareaProps {
   value?: string
   placeholder?: string
   label?: string
+  /** Names the field for assistive tech when it has no visible `label`. */
+  ariaLabel?: string
   hint?: string
   error?: string
   size?: "sm" | "md" | "lg"
@@ -19,6 +21,8 @@ export interface TextareaProps {
   onChange?: (value: string) => void
   onBlur?: () => void
   onFocus?: () => void
+  /** Called on every key press, such as to send a message on Enter. */
+  onKeyDown?: (event: KeyboardEvent) => void
   [key: string]: unknown
 }
 

package/types/data-display/chat.d.ts

@@ -0,0 +1,73 @@
+import type { Api, TemplateResult } from "@inglorious/web"
+
+/** One message of a chat: its text, or an entity that renders it. */
+export interface ChatMessage {
+  id: string
+  role: "user" | "assistant"
+  /** What the message says, as text. */
+  content?: string
+  /** The id of an entity to render as the message, such as a generated answer. */
+  entity?: string
+  [key: string]: unknown
+}
+
+/** What a chat keeps and shows. */
+export interface ChatProps {
+  id?: string
+  type?: string
+  messages?: ChatMessage[]
+  /** What the user is typing. */
+  draft?: string
+  /** A reply is on its way: the chat shows it, and does not send meanwhile. */
+  isBusy?: boolean
+  /** Why the last reply failed. */
+  error?: string | null
+  /** Messages to start with, offered while the chat is empty. */
+  suggestions?: string[]
+  /** Names the chat for assistive tech. Defaults to "Chat". */
+  label?: string
+  /** The message box's placeholder and name. Defaults to "Message". */
+  placeholder?: string
+  /** Defaults to "Send". */
+  sendLabel?: string
+  /** Who the user's messages are by, for assistive tech. Defaults to "You". */
+  userLabel?: string
+  /** Who replies. Defaults to "Assistant". */
+  assistantLabel?: string
+  onDraftChange?: (draft: string) => void
+  /** Sends `text`, such as a suggestion picked, or else the draft. */
+  onSend?: (text?: string) => void
+  /** Draws a message's `entity`. */
+  renderEntity?: (entityId: string) => unknown
+  [key: string]: unknown
+}
+
+/** A chat entity: its props, and a count that keeps message ids unique. */
+export interface ChatEntity extends ChatProps {
+  id?: string
+  type: string
+  messages: ChatMessage[]
+  messageCount?: number
+}
+
+export type ChatType = {
+  create(entity: ChatEntity): void
+  draftChange(entity: ChatEntity, draft: string): void
+  /** Adds the user's message, `text` or the draft; apps answer by handling it too. */
+  messageSend(entity: ChatEntity, text?: string): void
+  /** Adds a message, the assistant's by default. */
+  messageAdd(entity: ChatEntity, message: Partial<ChatMessage>): void
+  replyStart(entity: ChatEntity): void
+  replyEnd(entity: ChatEntity): void
+  replyFail(entity: ChatEntity, error: string): void
+  messagesClear(entity: ChatEntity): void
+  render(entity: ChatEntity, api: Api): TemplateResult
+  renderChat(props: ChatProps): TemplateResult
+  renderMessage(props: ChatProps, message: ChatMessage): TemplateResult
+  renderContent(props: ChatProps, message: ChatMessage): unknown
+  renderTyping(props: ChatProps): TemplateResult
+  renderSuggestions(props: ChatProps): TemplateResult
+  renderComposer(props: ChatProps): TemplateResult
+}
+
+export declare const Chat: ChatType

package/types/index.d.ts

@@ -16,6 +16,7 @@ export { Avatar } from "./data-display/avatar"
 export { Badge } from "./data-display/badge"
 export { BeforeAfter } from "./data-display/before-after"
 export { Carousel } from "./data-display/carousel"
+export { Chat } from "./data-display/chat"
 export { Chip } from "./data-display/chip"
 export { DataGrid } from "./data-display/data-grid"
 export { Divider } from "./data-display/divider"