@artooi/ag-ui-web-component 0.44.0 → 0.46.0

package/src/ui/themes/soft_tokens.ts

@@ -0,0 +1,28 @@
+// The soft theme's tokens: rounded, with surfaces tinted from the accent.
+export const SOFT_TOKENS: string = `
+/* ── Soft ─────────────────────────────────────────────────────────────────
+   Seeds, plus two surfaces mixed from the accent: a faint wash for the panel
+   chrome and a stronger tint for the user's turns. */
+:host([theme~="soft"]) {
+  --_bg: var(--ag-ui-bg, light-dark(#fdfcff, #17161d));
+  --_fg: var(--ag-ui-fg, light-dark(#1f1d2b, #ebe9f5));
+  --_accent: var(--ag-ui-accent, light-dark(#6a4fd8, #a593ff));
+  --_tint: var(--ag-ui-tint, color-mix(in oklch, var(--_accent) 5%, var(--_bg)));
+  --_tint-2: var(--ag-ui-tint-2, color-mix(in oklch, var(--_accent) 13%, var(--_bg)));
+  --_header-bg: var(--ag-ui-header-bg, var(--_tint));
+  --_user-bg: var(--ag-ui-user-bg, var(--_tint-2));
+  --_border: var(--ag-ui-border, color-mix(in oklch, var(--_accent) 14%, var(--_bg)));
+  --_radius: var(--ag-ui-radius, 16px);
+  --_frame-radius: var(--ag-ui-frame-radius, var(--ag-ui-radius, 24px));
+  --_msg-radius: var(--ag-ui-msg-radius, 18px);
+  --_composer-radius: var(--ag-ui-composer-radius, 22px);
+  --_frame-shadow: var(--ag-ui-frame-shadow, 0 2px 6px light-dark(rgb(30 20 60 / 0.05), rgb(0 0 0 / 0.3)), 0 30px 60px -28px light-dark(color-mix(in oklch, var(--_accent) 45%, transparent), rgb(0 0 0 / 0.75)));
+  --_launcher-size: var(--ag-ui-launcher-size, 56px);
+  --_launcher-bg: var(--ag-ui-launcher-bg, var(--_accent));
+  --_launcher-fg: var(--ag-ui-launcher-fg, var(--_on-accent));
+  --_launcher-radius: var(--ag-ui-launcher-radius, 20px);
+  --_launcher-icon-size: var(--ag-ui-launcher-icon-size, 24px);
+  --_chart-1: var(--ag-ui-chart-1, var(--_accent));
+  --_chart-2: var(--ag-ui-chart-2, color-mix(in oklch, var(--_accent) 38%, var(--_bg)));
+}
+`;

package/src/ui/themes/theme_hosts.ts

@@ -0,0 +1,14 @@
+/**
+ * The host selectors theme rules hang off, as one record so every theme
+ * module spells them the same way.
+ *
+ * Classic and code keep today's structure, so the structural rules the newer
+ * themes share apply to every element that wears neither. Quiet is the
+ * default, so its own structure applies to every element that wears no other
+ * built-in theme -- including one whose theme is a word the library does not
+ * know, which is how a host's own named theme starts from Quiet.
+ */
+export const THEME_HOST = {
+  modern: ':host(:not([theme~="classic"], [theme~="code"]))',
+  quiet: ':host(:not([theme~="classic"], [theme~="code"], [theme~="soft"], [theme~="ledger"]))',
+} as const;

package/src/ui/transcript/attachment_chip_styles.ts

@@ -0,0 +1,116 @@
+// An attachment chip, in the tray and in a sent message alike, the drop
+// outline, and the note a cancelled run leaves, which sits here only
+// because no rule moved in the split.
+export const ATTACHMENT_CHIP_STYLES: string = `
+/* A chip carries its own text colour because it carries its own background.
+   The same chip renders in two places with opposite inherited colours: the
+   composer tray gives it the panel's, a sent user bubble gives it the user
+   foreground, which is white on the stock light theme and near-invisible
+   against the chip. Pairing the colour with the background it belongs to makes
+   both placements read alike. Overridden below for an errored chip, which
+   keeps its red. */
+.attachment-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  /* Without this the 100% below caps the content box, so the chip still
+     overflows its container by its own padding and border. Invisible while a
+     character cap kept names short; routine once the container is what bounds
+     the name. */
+  box-sizing: border-box;
+  max-width: 100%;
+  padding: 4px 8px;
+  border: 1px solid var(--_border);
+  border-radius: 999px;
+  background: var(--_assistant-bg);
+  color: var(--_text);
+  font-size: 0.85em;
+  position: relative;
+}
+
+.attachment-chip--error {
+  border-color: var(--_danger);
+  color: var(--_danger);
+}
+
+/* The type mark. Painted from currentColor, so it carries the chip's state
+   with it and turns red along with an errored one; muted by opacity rather
+   than a colour, which is what keeps that true. Sized from the chip's own text
+   rather than --ag-ui-glyph-size, the way an icon holder's glyph takes the
+   holder's size: the composer's 18px buttons would make a chip button-height. */
+.attachment-chip-icon {
+  display: inline-flex;
+  flex: none;
+  opacity: 0.75;
+}
+
+.attachment-chip-icon .glyph {
+  width: 1.25em;
+  height: 1.25em;
+}
+
+/* No character cap: the chip is already max-width 100%, so its container is
+   what bounds the name, and a fixed cap only truncated names the chip had room
+   for. min-width: 0 is what lets the flex item shrink past its content, so the
+   ellipsis appears at the container edge instead of the chip overflowing. */
+.attachment-chip-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+}
+
+.attachment-chip-size {
+  color: var(--_muted);
+  white-space: nowrap;
+}
+
+.attachment-chip--error .attachment-chip-size {
+  color: var(--_danger);
+}
+
+/* The progress bar fills as the file uploads. */
+.attachment-chip-bar {
+  flex-basis: 100%;
+  height: 3px;
+  border-radius: 2px;
+  background: var(--_border);
+  overflow: hidden;
+}
+
+.attachment-chip-bar-fill {
+  height: 100%;
+  background: var(--_accent);
+  transition: width 0.15s ease;
+}
+
+.attachment-chip-remove,
+.attachment-chip-retry {
+  border: none;
+  background: none;
+  color: inherit;
+  cursor: pointer;
+  padding: 0;
+  line-height: 1;
+  opacity: 0.7;
+}
+
+.attachment-chip-remove:hover,
+.attachment-chip-retry:hover {
+  opacity: 1;
+}
+
+/* A subtle outline while a file is dragged over the shell. */
+.chat--dragover {
+  outline: 2px dashed var(--_accent);
+  outline-offset: -4px;
+}
+
+/* Muted "⏹ Stopped" line after a cancelled run — a note, not an error bubble. */
+.stopped-note {
+  align-self: flex-start;
+  color: var(--_muted);
+  font-size: 12px;
+  padding: 2px 4px;
+}
+`;

package/src/ui/transcript/build_transcript.ts

@@ -0,0 +1,67 @@
+import type { UiStrings } from "../ui_strings.js";
+
+/** The transcript's parts, owned by the element, and what fills them. */
+export interface TranscriptOptions {
+  readonly messages: HTMLElement;
+  readonly jumpButton: HTMLButtonElement;
+  readonly emptyWrap: HTMLElement;
+  /** The greeting's text node, kept by the element so a new user name updates it. */
+  readonly greetingText: HTMLElement;
+  /** The starter chips, or `null` when the host configured none. */
+  readonly starters: HTMLElement | null;
+  readonly strings: UiStrings;
+}
+
+/**
+ * Ready the message list, its jump-to-latest control and the empty state.
+ *
+ * The empty state is built but not put into the list: the element mounts the
+ * scroller, the quote offer and the announcer first and appends it after, so
+ * the scroller's observers see the list fill exactly as they always have.
+ */
+export function buildTranscript(options: TranscriptOptions): void {
+  const { messages, jumpButton, emptyWrap, strings } = options;
+  messages.className = "messages";
+  messages.setAttribute("part", "messages");
+  messages.setAttribute("role", "log");
+  // NOT a live region. The streaming bubble's innerHTML is replaced inside
+  // this element on every animation frame, and `role="log"` already implies
+  // polite announcement whose default `aria-relevant` includes text
+  // additions -- so a screen reader was asked to re-announce the whole answer
+  // tens of times as it streamed. `aria-live="off"` is an explicit override
+  // of the role's implicit value, which is why the role can stay: the log
+  // semantics are what let the transcript be navigated as one, and only the
+  // announcing is the defect. Status goes to the announcer instead.
+  messages.setAttribute("aria-live", "off");
+  messages.setAttribute("aria-label", strings.conversation);
+
+  jumpButton.className = "jump-latest";
+  jumpButton.type = "button";
+  jumpButton.setAttribute("part", "jump-latest");
+  jumpButton.textContent = strings.jumpToLatest;
+
+  // Empty-state region: a host slot at the top of the list, hidden as soon as
+  // anything renders.
+  emptyWrap.className = "empty";
+  emptyWrap.setAttribute("part", "empty");
+  // The greeting heads the empty state, in a slot of its own: a host that
+  // replaces the starters keeps the greeting, and a host that replaces the
+  // greeting keeps the starters. A div rather than a heading, because this
+  // sits inside somebody else's page, which owns the document outline.
+  const greeting = document.createElement("div");
+  greeting.className = "greeting";
+  greeting.setAttribute("part", "greeting");
+  const greetingSlot = document.createElement("slot");
+  greetingSlot.name = "greeting";
+  greetingSlot.append(options.greetingText);
+  greeting.append(greetingSlot);
+  const emptySlot = document.createElement("slot");
+  emptySlot.name = "empty";
+  // Fallback content, so a host that slots its own gets exactly that and
+  // nothing of ours: the starters live *inside* the slot rather than beside
+  // it, which is the difference between an offer and an imposition.
+  if (options.starters !== null) {
+    emptySlot.append(options.starters);
+  }
+  emptyWrap.replaceChildren(greeting, emptySlot);
+}

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);
+}
+`;