@artooi/agents-web-components 0.0.0-stage → 0.1.0

package/src/ui/transcript/greeting_styles.ts

@@ -0,0 +1,171 @@
+// The empty state: the greeting over an empty conversation, and the
+// composer's travel from the centre to the foot on the first send.
+export const GREETING_STYLES: string = `
+/* Empty-state region (slot): centred while it's the only thing in the
+   list, hidden as soon as a message, card, or pending indicator renders. */
+.empty {
+  margin: auto;
+  text-align: center;
+  color: var(--_muted);
+}
+
+.empty[hidden] {
+  display: none;
+}
+
+/* The greeting layout: a greeting over an empty conversation, and the
+   composer centred beneath it until the conversation has something in it.
+
+   On by default for the page placement, where a conversation is the whole
+   route; data-greeting="off" turns it off there. An embedded panel opts in
+   with any other data-greeting value. No other placement has it: a panel
+   opened from a launcher is already mid-task, and a greeting in a corner
+   panel costs space and says little.
+
+   The greeting itself renders under every placement and is hidden here, so a
+   placement switch at runtime needs nothing from script. */
+.greeting {
+  display: none;
+}
+
+:host([placement="page"]:not([data-greeting="off"])) .greeting,
+:host([placement="embedded"][data-greeting]:not([data-greeting="off"])) .greeting {
+  display: block;
+  margin-block-end: calc(var(--_space) * 2);
+  font-family: var(--_greeting-font);
+  font-size: var(--_greeting-size);
+  font-weight: 500;
+  line-height: 1.2;
+  color: var(--_fg);
+  overflow-wrap: anywhere;
+}
+
+/* Centring is two equal flexible boxes either side of the composer rows: the
+   transcript above, which already grows, and this one below. Equal zero bases
+   make the two halves the same height whatever they hold, so the rows sit in
+   the middle of the panel below its header, and stay there as a draft, an
+   attachment tray or a hint grows them, because growth splits into both
+   halves at once.
+
+   A pseudo element rather than a node, so no host layout and nothing that
+   counts children can see it. It exists whether or not the conversation is
+   empty and only its growth changes, because a box that appears and
+   disappears is a box nothing can ever transition.
+
+   Only the rule that generates it names the placements. The one that grows it
+   needs nothing but the state: where the first rule does not apply there is no
+   box to grow. The box is empty, so its automatic basis is already zero, the
+   same as the transcript's; nothing here writes the flex shorthand, because
+   this selector is the more specific of the two and a shorthand would win
+   over the growth. */
+:host([placement="page"]:not([data-greeting="off"])) .chat::after,
+:host([placement="embedded"][data-greeting]:not([data-greeting="off"])) .chat::after {
+  content: "";
+}
+
+/* Not while a restore is in flight: a conversation a remote store is still
+   fetching is more likely to have messages than not, and centring it first
+   would drop the composer the moment they land. */
+:host([data-empty]:not([data-restoring])) .chat::after {
+  flex-grow: 1;
+}
+
+/* Only the send that leaves the empty state travels. The element arms this for
+   that one change and disarms it whenever the transcript is cleared, so a
+   restored conversation, a thread switch and a new chat all snap. Growth rather
+   than a transform, because the rows between the transcript and the composer
+   move with it, and growth is continuous where a reorder is not. Reduced motion
+   needs no rule of its own: the motion token already collapses to a frame
+   there.
+
+   The rule over the composer fades in over the same stretch. Appearing at once,
+   it was drawn across the page at the composer's destination while the
+   composer was still on its way there. */
+:host([data-composer-settling]) .chat::after {
+  transition: flex-grow var(--_motion) var(--_ease);
+}
+
+:host([data-composer-settling]) .input-row {
+  transition: border-color var(--_motion) var(--_ease);
+}
+
+/* The greeting and whatever the host slotted sit at the foot of the upper
+   half, directly over the composer, rather than floating in its middle. The
+   region is hidden once the conversation has content, so this needs no state
+   of its own. */
+:host([placement="page"]:not([data-greeting="off"]):not([data-restoring])) .empty,
+:host([placement="embedded"][data-greeting]:not([data-greeting="off"]):not([data-restoring])) .empty {
+  margin: auto auto 0;
+}
+
+/* The rule over the composer separates it from a transcript. Over nothing it
+   is a line drawn across the middle of the page. */
+:host([placement="page"][data-empty]:not([data-greeting="off"]):not([data-restoring])) .input-row,
+:host([placement="embedded"][data-greeting][data-empty]:not([data-greeting="off"]):not([data-restoring])) .input-row {
+  border-block-start-color: transparent;
+}
+
+/* On a phone the composer stays at the foot and the greeting takes the room
+   above it, which is the other way round from everything above.
+
+   Centring is a shape for a screen with room to spare: the composer reads as
+   the one thing on the page, and whichever way the rows grow there is space
+   left on both sides of them. A phone has no space to spare, and the keyboard
+   is what takes it -- opening one leaves a 426px-tall visible area with the
+   composer halfway up it and an empty band underneath, which is the half of
+   the screen a thumb is already resting on. Docked, the field sits directly
+   over the keyboard, where every chat on the platform puts it, and the
+   greeting keeps the rest.
+
+   Both rules restate the selector they override, with the breakpoint's own
+   opt-out added: this is part of the shape a host keeps its desktop layout
+   instead of, so it goes the same way as the rest of that shape. Restating
+   rather than adding conditions to the originals keeps each of those rules
+   readable as one decision, and source order settles the pair. */
+@media (max-width: 600px) {
+  :host([data-empty]:not([data-restoring]):not([data-small-viewport="off"])) .chat::after {
+    flex-grow: 0;
+  }
+
+  /* The empty region fills the transcript instead of being centred in it as a
+     block, so the two things in it can go to different places: the prompts the
+     host offers to the foot, against the composer, and the greeting to the
+     middle of what they leave.
+
+     A prompt chip is a way into the conversation. Against the field it starts,
+     it reads as one; under the greeting halfway up the panel, with the field
+     at the foot, it reads as decoration next to something else. Nothing here
+     moves them on a screen where the composer is still centred: there the
+     whole region hangs at the foot of the upper half, directly over the
+     composer, and the prompts are already against it.
+
+     Auto block margins on the greeting are what centre it, and they take the
+     free space whether or not there are prompts below to leave any, so a host
+     that offers none gets a greeting in the middle of the transcript rather
+     than one clinging to the composer.
+     The region declares a display here, which outranks the rule collapsing a
+     hidden one, so it says it is not hidden itself. Nothing sets the two
+     apart today -- the transcript writes the hidden property and the host's
+     data-empty from one expression -- and that is exactly why: a rule holding
+     because of how a method in another file happens to be written is a rule
+     holding by luck. */
+  :host([placement="page"][data-empty]:not([data-greeting="off"]):not([data-restoring]):not([data-small-viewport="off"])) .empty:not([hidden]),
+  :host([placement="embedded"][data-greeting][data-empty]:not([data-greeting="off"]):not([data-restoring]):not([data-small-viewport="off"])) .empty:not([hidden]) {
+    margin: 0;
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+  }
+
+  :host([placement="page"][data-empty]:not([data-greeting="off"]):not([data-restoring]):not([data-small-viewport="off"])) .greeting,
+  :host([placement="embedded"][data-greeting][data-empty]:not([data-greeting="off"]):not([data-restoring]):not([data-small-viewport="off"])) .greeting {
+    margin-block: auto;
+  }
+}
+
+/* Nor does the greeting paint while a restore is in flight. Hidden rather than
+   removed, so it keeps its place and nothing around it moves when it shows. */
+:host([data-restoring]) .greeting {
+  visibility: hidden;
+}
+`;

package/src/ui/transcript/groups_tool_steps.ts

@@ -0,0 +1,16 @@
+import { TOOL_DISPLAY } from "../../constants.js";
+import type { ToolDisplayMode } from "../progress/tool_call_card.js";
+
+/**
+ * Whether a new tool call folds into a step group, given the element's
+ * `toolDisplay`.
+ *
+ * The display mode alone decides, whatever the theme: `grouped` (the default,
+ * and what an unknown value reads as) folds, and the four card modes keep
+ * per-call cards. Asked as each card is built, so switching to `grouped`
+ * folds only the calls drawn afterwards; switching away flattens the groups
+ * already drawn, which the shadow CSS does from the host attribute.
+ */
+export function groupsToolSteps(mode: ToolDisplayMode): boolean {
+  return mode === TOOL_DISPLAY.GROUPED;
+}

package/src/ui/transcript/message_action_styles.ts

@@ -0,0 +1,155 @@
+// The action row under a message: copy, retry, feedback and the rest.
+// Guest: the whole coarse-pointer block near the end (the resize handle hidden,
+// the 44px touch-target tokens on :host, the 16px composer font floor).
+export const MESSAGE_ACTION_STYLES: string = `
+   The wrap is insurance rather than a fix: these buttons are glyph-only, so at
+   every width tested they fit on one line and removing the wrap changes
+   nothing. It is here because the confirmation row one release earlier did
+   overflow when it gained a third button, off the left edge and outside its own
+   card, and the difference between the two rows is only that this one's labels
+   are icons today. */
+.message-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  /* Negative, and that is the point. The answer group is a flex column with its
+     own gap, so a positive margin here pushes the row further from the message
+     it acts on than the next card is below it -- the buttons then read as
+     belonging to whatever follows. Pulling back inside the gap is what makes
+     them the message's own. */
+  margin-top: -6px;
+}
+
+/* The row's controls are icon-only, so the box is the whole target. Sized from
+   a variable a host can raise, with a floor rather than a fixed height: the
+   compact density shrinks the font, and a target that shrinks with it lands
+   under the 24px minimum that makes a control reliably tappable. It used to,
+   at roughly 20px square. */
+.message-action {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  min-width: var(--_action-size);
+  min-height: var(--_action-size);
+  padding: 4px;
+  border: none;
+  border-radius: 6px;
+  font: inherit;
+  line-height: 1.2;
+  cursor: pointer;
+  background: transparent;
+  color: var(--_muted);
+  opacity: 0.75;
+  /* The tooltip below is positioned against this box. */
+  position: relative;
+}
+
+.message-action:hover,
+.message-action:focus-visible {
+  opacity: 1;
+  background: var(--_border);
+}
+
+.message-action-icon {
+  display: inline-flex;
+  width: var(--_action-icon-size);
+  height: var(--_action-icon-size);
+}
+
+.message-action-icon .glyph {
+  width: 100%;
+  height: 100%;
+}
+
+/* The label, drawn rather than left to the browser.
+
+   A title attribute is the usual answer and covers only half the readers: it
+   never appears on keyboard focus, so tabbing onto an icon-only control shows
+   nothing at all. The attribute stays for the pointer users who expect it, and
+   this shows the same words on hover and on focus alike.
+
+   Left-aligned rather than centred because the row sits at the left edge of an
+   answer inside a scrolling column, and a centred tooltip on the first control
+   is clipped by that column. Growing rightward keeps it inside.
+
+   Not exposed to assistive technology: the button already carries the same
+   string as its accessible name, and this would be a second copy of it. */
+.message-action::after {
+  content: attr(data-tooltip);
+  position: absolute;
+  bottom: calc(100% + 4px);
+  left: 0;
+  z-index: 3;
+  padding: 3px 6px;
+  border-radius: 4px;
+  background: var(--_tooltip-bg);
+  color: var(--_tooltip-fg);
+  font-size: 11px;
+  line-height: 1.4;
+  white-space: nowrap;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity var(--_motion) var(--_ease);
+}
+
+.message-action:hover::after,
+.message-action:focus-visible::after {
+  opacity: 1;
+}
+
+/* Touch has no hover to reveal it, and a tooltip that latches open under a
+   finger covers the answer it belongs to. */
+@media (hover: none) {
+  .message-action::after {
+    content: none;
+  }
+}
+
+/* Touch. Separate from the width breakpoint in the small-viewport placement
+   rules on purpose: width decides the layout, the pointer decides which
+   controls make sense, and a touch laptop is coarse-pointered and wide while a
+   narrow desktop window is fine-pointered and small. */
+@media (pointer: coarse) {
+  /* A 6px edge strip is not a control, it is a trap that eats a scroll. The
+     corners are 14px, still under the 24px floor a target is meant to clear,
+     and the panel has other ways to be resized on a device that has a pointer
+     precise enough to grab one. */
+  .resize-handle {
+    display: none;
+  }
+
+  /* Platform guidance is 44pt on iOS and 48dp on Android. These sit at 28-30px,
+     which clears the WCAG minimum and misses both. */
+  :host {
+    --_action-size: var(--ag-ui-action-size, 44px);
+    --_tool-btn-size: var(--ag-ui-tool-btn-size, 44px);
+    --_send-size: var(--ag-ui-send-size, 44px);
+    /* Missed the first time these were raised, which left the header -- the
+       widget's primary controls, and the only way to reach history, a new chat
+       or the collapse -- at half the size of everything beside it. */
+    --_header-btn-size: var(--ag-ui-header-btn-size, 44px);
+    --_header-gap: var(--ag-ui-header-gap, 6px);
+  }
+
+  /* iOS Safari zooms the page when a control under 16px takes focus, which
+     drags the whole fixed panel with it and leaves the user pinching back out
+     of a chat they only wanted to type into. The composer inherits the widget
+     font, which is 14px by default and 13px at compact density, so it has to
+     say 16 outright -- and only ever upward, so a host that has deliberately
+     set something larger keeps it. */
+  .input {
+    font-size: max(16px, var(--_font-size));
+  }
+}
+
+.message-action[aria-pressed="true"] {
+  opacity: 1;
+  color: var(--_accent);
+}
+
+.message-action--confirmed {
+  opacity: 1;
+  color: var(--_accent);
+}
+`;

package/src/ui/transcript/message_actions.ts

@@ -0,0 +1,234 @@
+import { ICON_COPY, ICON_THUMB_DOWN, ICON_THUMB_UP } from "../../constants.js";
+import type { UiStrings } from "../ui_strings.js";
+
+/** How long a button shows its confirmation before reverting. */
+const CONFIRM_MS = 1500;
+
+/** What an action bar can do, beyond copying. */
+export interface MessageActionsOptions {
+  /** Localized strings. */
+  strings: UiStrings;
+  /**
+   * The text Copy puts on the clipboard. Absent means no copy button.
+   *
+   * A function rather than a string because a bubble's content is rewritten
+   * while it streams. Each button's option is also the statement that the
+   * button belongs, so no second flag can disagree with it.
+   */
+  text?: () => string;
+  /**
+   * The rich flavour to copy alongside `text`, as an HTML fragment. Absent
+   * means plain text only.
+   *
+   * It is what makes a copied table paste as a table: a spreadsheet or a chat
+   * client reads `text/html` when offered and falls back to the plain flavour.
+   */
+  html?: () => string;
+  /**
+   * Report a rating for this message. Absent means no feedback buttons.
+   *
+   * The component stores nothing: a rating is the host's to keep, and a
+   * write-only table nobody reads is not worth a schema.
+   */
+  onFeedback?: (rating: "up" | "down") => void;
+}
+
+/**
+ * Give one finished message bubble its row of actions.
+ *
+ * **Finished** is load-bearing. A streaming bubble reassigns its `innerHTML` on
+ * every delta, so anything attached mid-stream is discarded and rebuilt for
+ * each one -- the same constraint `attachCopyButtons` records, one level up.
+ *
+ * Retry is deliberately **not** here: it belongs to the last turn only, so the
+ * element owns it and moves it as the transcript grows. Everything on this bar
+ * is safe to offer on any message, however old.
+ *
+ * Idempotent -- a bubble already given a bar is skipped, so a re-render or a
+ * second call cannot stack rows.
+ *
+ * Passing neither `text` nor `onFeedback` builds an empty row; the element
+ * skips the call when a host has turned both off.
+ */
+export function attachMessageActions(bubble: HTMLElement, options: MessageActionsOptions): void {
+  if (existingBar(bubble) !== null) {
+    return;
+  }
+  const bar = messageActionBar(bubble, options.strings);
+  const text = options.text;
+  if (text !== undefined) {
+    bar.appendChild(copyButton(options.strings, text, options.html));
+  }
+  if (options.onFeedback !== undefined) {
+    bar.append(
+      feedbackButton("up", options.strings.feedbackUp, options.onFeedback),
+      feedbackButton("down", options.strings.feedbackDown, options.onFeedback),
+    );
+  }
+}
+
+/**
+ * The empty action row on `bubble`, created if it has none yet.
+ *
+ * Shared so a bubble that wants *only* Retry -- a failed run, which has nothing
+ * worth copying and nothing to rate -- gets the same row, the same part name
+ * and the same accessible grouping as every other message, rather than a
+ * second thing that looks like one.
+ */
+export function messageActionBar(bubble: HTMLElement, strings: UiStrings): HTMLElement {
+  const existing = existingBar(bubble);
+  if (existing !== null) {
+    return existing;
+  }
+  const bar = document.createElement("div");
+  bar.className = "message-actions";
+  bar.setAttribute("part", "message-actions");
+  // A group rather than a toolbar: these are independent actions on the message
+  // above, not a set the user arrows between.
+  bar.setAttribute("role", "group");
+  bar.setAttribute("aria-label", strings.messageActions);
+  // A **sibling**, never a child. Inside the bubble the buttons join its
+  // `textContent`, which is what Copy reads, what history persists and what
+  // every existing assertion about a message's text compares against -- so an
+  // answer would be copied back with the glyphs of the buttons that copied it.
+  // The bubble must therefore already be in the tree when this is called.
+  bubble.after(bar);
+  return bar;
+}
+
+/** The action row belonging to `bubble`, if it has one. */
+function existingBar(bubble: HTMLElement): HTMLElement | null {
+  const next = bubble.nextElementSibling;
+  return next?.classList.contains("message-actions") === true ? (next as HTMLElement) : null;
+}
+
+/**
+ * Build one action button, labelled for screen readers rather than by glyph.
+ *
+ * `icon` is icon markup rather than a text glyph: the copy mark in particular
+ * has no font behind it on most systems.
+ *
+ * The label is carried three ways, and each has a reader the others miss:
+ * `aria-label` for assistive technology, `title` for the browser's own
+ * tooltip, and `data-tooltip` for the one this component draws. The last is
+ * not redundant with the second -- a `title` never appears on keyboard focus,
+ * so without it a keyboard user has no way to see what the control does.
+ *
+ * The icon sits in its own part, so a host can restyle or replace it. A slot
+ * would be the better channel and cannot be used here: these repeat once per
+ * message, and a named slot can only be filled once.
+ */
+export function messageActionButton(
+  modifier: string,
+  label: string,
+  icon: string,
+): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = `message-action message-action--${modifier}`;
+  button.setAttribute("part", `message-action message-action-${modifier}`);
+  setLabel(button, label);
+  const holder = document.createElement("span");
+  holder.className = "message-action-icon";
+  holder.setAttribute("part", `message-action-icon message-action-icon-${modifier}`);
+  holder.setAttribute("aria-hidden", "true");
+  // Author-written markup from constants, never message content.
+  holder.innerHTML = icon;
+  button.appendChild(holder);
+  return button;
+}
+
+/** Put `label` on every channel that names this button. */
+function setLabel(button: HTMLButtonElement, label: string): void {
+  button.title = label;
+  button.setAttribute("aria-label", label);
+  button.dataset["tooltip"] = label;
+}
+
+function copyButton(
+  strings: UiStrings,
+  text: () => string,
+  html: (() => string) | undefined,
+): HTMLButtonElement {
+  const button = messageActionButton("copy", strings.copyMessage, ICON_COPY);
+  button.addEventListener("click", () => {
+    void write(text(), html?.()).then((ok) => {
+      // A denied clipboard permission is the common case, not an exception:
+      // say so on the button rather than throwing into an unhandled rejection.
+      flash(button, ok ? strings.copied : strings.copyFailed, strings.copyMessage);
+    });
+  });
+  return button;
+}
+
+/**
+ * Put the message on the clipboard, richest flavour first.
+ *
+ * Writing both flavours needs `ClipboardItem`, which not every engine that has
+ * `writeText` also has -- and even where the constructor exists the write can
+ * be refused. Neither is a failure worth reporting as one while the plain text
+ * would still have landed, so both fall through to `writeText` and only that
+ * decides what the button says.
+ */
+async function write(text: string, html: string | undefined): Promise<boolean> {
+  const clipboard = navigator.clipboard;
+  if (clipboard === undefined) {
+    return false;
+  }
+  if (html !== undefined && typeof ClipboardItem === "function") {
+    try {
+      await clipboard.write([
+        new ClipboardItem({
+          "text/plain": new Blob([text], { type: "text/plain" }),
+          "text/html": new Blob([html], { type: "text/html" }),
+        }),
+      ]);
+      return true;
+    } catch {
+      // Fall through to the plain flavour.
+    }
+  }
+  try {
+    await clipboard.writeText(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function feedbackButton(
+  rating: "up" | "down",
+  label: string,
+  report: (rating: "up" | "down") => void,
+): HTMLButtonElement {
+  const button = messageActionButton(
+    rating,
+    label,
+    rating === "up" ? ICON_THUMB_UP : ICON_THUMB_DOWN,
+  );
+  button.addEventListener("click", () => {
+    // Pressed rather than removed: the rating is a standing statement about the
+    // message, and a button that vanishes leaves no record of what was said.
+    const pressed = button.getAttribute("aria-pressed") === "true";
+    button.setAttribute("aria-pressed", pressed ? "false" : "true");
+    report(rating);
+  });
+  button.setAttribute("aria-pressed", "false");
+  return button;
+}
+
+/**
+ * Flash `message` on the button, then restore `label`.
+ *
+ * The label to restore is passed rather than read back off the element: the
+ * caller is the one that set it, and reading it would introduce a null arm that
+ * cannot happen and cannot be covered.
+ */
+function flash(button: HTMLButtonElement, message: string, label: string): void {
+  setLabel(button, message);
+  button.classList.add("message-action--confirmed");
+  setTimeout(() => {
+    setLabel(button, label);
+    button.classList.remove("message-action--confirmed");
+  }, CONFIRM_MS);
+}