@artooi/ag-ui-web-component 0.32.0 → 0.33.0

package/src/ui/copy_payload.ts

@@ -0,0 +1,156 @@
+/** What a copied message puts on the clipboard, in both flavours. */
+export interface CopyPayload {
+  /** The plain-text flavour, structured so a table survives a paste. */
+  readonly text: string;
+  /** The rich flavour, so a table pastes as a table. */
+  readonly html: string;
+}
+
+/** Elements whose content starts on a line of its own. */
+const BLOCK_TAGS = new Set([
+  "ADDRESS",
+  "ARTICLE",
+  "ASIDE",
+  "BLOCKQUOTE",
+  "DD",
+  "DIV",
+  "DL",
+  "DT",
+  "FIGCAPTION",
+  "FIGURE",
+  "FOOTER",
+  "H1",
+  "H2",
+  "H3",
+  "H4",
+  "H5",
+  "H6",
+  "HEADER",
+  "HR",
+  "MAIN",
+  "NAV",
+  "OL",
+  "P",
+  "SECTION",
+  "UL",
+]);
+
+/**
+ * What to copy from one rendered message, in both clipboard flavours.
+ *
+ * `textContent` was the obvious answer and the wrong one. It concatenates every
+ * descendant with no separator at all, so a markdown table arrives as one run
+ * of digits with the headers welded to the first row -- unusable in a
+ * spreadsheet, and unreadable anywhere. Lists lose their bullets the same way,
+ * and paragraphs run together.
+ *
+ * So the plain flavour is serialised structurally: table rows become tab
+ * separated lines, which is the format spreadsheets parse on paste, and blocks
+ * and list items get their own lines. The rich flavour carries the markup, so a
+ * target that understands it -- a document, a chat client, a spreadsheet --
+ * gets the real table rather than a reconstruction of one.
+ *
+ * Both are taken from a **clone with the component's own buttons removed**. The
+ * code-block copy buttons are appended inside their own `pre`, so they are
+ * descendants of the bubble and `textContent` was picking their label up: a
+ * message containing a code block copied with the word for Copy sitting in the
+ * middle of it.
+ */
+export function copyPayload(root: Element): CopyPayload {
+  const clone = root.cloneNode(true) as Element;
+  // The component's own affordances, not the message. Markdown cannot produce
+  // a button, so anything matching here is chrome this element added.
+  for (const control of Array.from(clone.querySelectorAll("button"))) {
+    control.remove();
+  }
+  return { text: normalise(serialise(clone)), html: clone.innerHTML };
+}
+
+/**
+ * Walk a subtree into text, inserting newlines where the layout implies them.
+ *
+ * Nothing recurses into a `pre` or a table: both are handled whole, because
+ * their text is their layout. That is also why this needs no notion of being
+ * inside preformatted content -- there is no such position to be in.
+ */
+function serialise(node: Node): string {
+  if (node.nodeType === Node.TEXT_NODE) {
+    // Non-null for a text node; nodeValue is nullable only on document and
+    // doctype nodes, which cannot appear inside a message. Outside a pre, runs
+    // of whitespace collapse to one space -- the same collapsing the renderer
+    // does, so what is copied matches what is read.
+    return (node.nodeValue as string).replace(/\s+/g, " ");
+  }
+  if (node.nodeType !== Node.ELEMENT_NODE) {
+    return "";
+  }
+  const element = node as Element;
+  const tag = element.tagName;
+  if (tag === "BR") {
+    return "\n";
+  }
+  if (tag === "PRE") {
+    // Verbatim: its whitespace is its content.
+    return `\n\n${text(element)}\n\n`;
+  }
+  if (tag === "TABLE") {
+    return `\n\n${tableText(element)}\n\n`;
+  }
+  if (tag === "UL" || tag === "OL") {
+    return `\n\n${listText(element, tag === "OL")}\n\n`;
+  }
+  const inner = children(element);
+  return BLOCK_TAGS.has(tag) ? `\n\n${inner}\n\n` : inner;
+}
+
+/** Every child of `element`, serialised and joined. */
+function children(element: Element): string {
+  let joined = "";
+  for (const child of Array.from(element.childNodes)) {
+    joined += serialise(child);
+  }
+  return joined;
+}
+
+/**
+ * A list, one item per line, marked the way it is rendered.
+ *
+ * Built here rather than at the item, so the marker comes from the list that
+ * owns it and never from an item's parent lookup -- which has a null arm no
+ * message can produce.
+ */
+function listText(list: Element, numbered: boolean): string {
+  return Array.from(list.children)
+    .map((item, index) => `${numbered ? `${index + 1}. ` : "- "}${children(item).trim()}`)
+    .join("\n");
+}
+
+/**
+ * A table as tab-separated rows.
+ *
+ * Tabs rather than a drawn grid because that is what spreadsheets parse: a
+ * paste of tab-separated lines lands one value per cell, which is the whole
+ * point of copying a table out of an answer.
+ */
+function tableText(table: Element): string {
+  return Array.from(table.querySelectorAll("tr"))
+    .map((row) =>
+      Array.from(row.children)
+        .map((cell) => text(cell).replace(/\s+/g, " ").trim())
+        .join("\t"),
+    )
+    .join("\n");
+}
+
+/** An element's text. Never null: only documents and doctypes have none. */
+function text(element: Element): string {
+  return element.textContent as string;
+}
+
+/** Tidy the block boundaries the walk inserted generously. */
+function normalise(text: string): string {
+  return text
+    .replace(/[^\S\n]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}

package/src/ui/launcher_drag.ts

@@ -0,0 +1,182 @@
+import { clampLauncher } from "./clamp_launcher.js";
+import type { Extent, LauncherBox } from "./launcher_placement.js";
+
+/** What the drag needs from its host to do its job. */
+export interface LauncherDragOptions {
+  /**
+   * Whether the current placement lets the launcher move, read per interaction
+   * because `placement` is a live attribute. A docked rail and a full-bleed
+   * layout have nowhere to move it to.
+   */
+  readonly enabled: () => boolean;
+  /** The launcher's current box, in viewport coordinates. */
+  readonly rect: () => LauncherBox;
+  /** The viewport the launcher has to stay inside. */
+  readonly viewport: () => Extent;
+  /** Put the launcher's top-left at this point. Called per pointer move. */
+  readonly apply: (left: number, top: number) => void;
+  /**
+   * Called once per completed move, for persistence: on `pointerup` for a
+   * drag, and when the key comes up (or focus leaves) for a key press. Never
+   * per pointer move, and never per key repeat.
+   */
+  readonly commit: (left: number, top: number) => void;
+}
+
+/**
+ * How far the pointer must travel before this counts as a drag rather than a
+ * click. The launcher's first job is still to expand the panel, so a press
+ * that wanders by a pixel has to remain a press.
+ */
+const DRAG_THRESHOLD = 4;
+
+/** Keyboard step, and the larger one Shift asks for. */
+const STEP = 16;
+const COARSE_STEP = 64;
+
+/**
+ * Let the user drag the collapsed launcher anywhere on screen.
+ *
+ * The launcher is a button before it is a handle, and that ordering is the
+ * whole difficulty: every drag ends in a `click` the browser synthesises, which
+ * would expand the panel the user was only repositioning. So a completed drag
+ * arms a one-shot capture listener that eats exactly one click.
+ *
+ * Two things stop that from eating a click it should not have. A drag ending
+ * off the launcher never produces the click it armed, so the arming is cleared
+ * on the next `pointerdown` -- a pointer click is always preceded by a press,
+ * which puts the clearing ahead of any click it could reach.
+ *
+ * That leaves the clicks with no press in front of them at all: `Enter` and
+ * `Space` on the focused button, assistive technology activating it, and a host
+ * calling `click()` itself. None of those is the tail of a drag, and all of them
+ * are the only way in for someone not using a pointer, so the suppression is
+ * narrowed to clicks carrying a click count -- which is the pointer's own.
+ */
+export function enableLauncherDrag(launcher: HTMLElement, options: LauncherDragOptions): void {
+  let suppressClick = false;
+
+  launcher.addEventListener(
+    "click",
+    (event: MouseEvent) => {
+      // detail is the click count on a pointer click and zero on a keyboard,
+      // assistive or programmatic one. Only the first kind can end a drag.
+      if (!suppressClick || event.detail === 0) {
+        return;
+      }
+      suppressClick = false;
+      // Capture phase, so this runs before the expand handler bound to the
+      // same element rather than after it.
+      event.stopPropagation();
+      event.preventDefault();
+    },
+    true,
+  );
+
+  launcher.addEventListener("pointerdown", (event: PointerEvent) => {
+    // Any suppression left armed by a drag that ended elsewhere dies here,
+    // before it can reach a click belonging to this new gesture.
+    suppressClick = false;
+    if (!options.enabled()) {
+      return;
+    }
+    const start = options.rect();
+    const originX = event.clientX;
+    const originY = event.clientY;
+    let dragging = false;
+
+    const onMove = (move: PointerEvent): void => {
+      const dx = move.clientX - originX;
+      const dy = move.clientY - originY;
+      if (!dragging && Math.hypot(dx, dy) < DRAG_THRESHOLD) {
+        return;
+      }
+      dragging = true;
+      launcher.setAttribute("data-dragging", "true");
+      // Measured from the box the press started on, never from the live one:
+      // reading it each move would chase the launcher as it moves and the
+      // travel would compound.
+      const next = clampLauncher(
+        { ...start, left: start.left + dx, top: start.top + dy },
+        options.viewport(),
+      );
+      options.apply(next.left, next.top);
+    };
+
+    const onUp = (up: PointerEvent): void => {
+      window.removeEventListener("pointermove", onMove);
+      window.removeEventListener("pointerup", onUp);
+      if (!dragging) {
+        return;
+      }
+      launcher.removeAttribute("data-dragging");
+      suppressClick = true;
+      const next = clampLauncher(
+        {
+          ...start,
+          left: start.left + (up.clientX - originX),
+          top: start.top + (up.clientY - originY),
+        },
+        options.viewport(),
+      );
+      options.commit(next.left, next.top);
+    };
+
+    // Listeners on `window`, not the launcher: a fast drag outruns the pointer
+    // and would otherwise strand it mid-move with no pointerup.
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+  });
+
+  // The position this key gesture has applied but not yet persisted. The
+  // pointer path can commit inline because a drag has one unambiguous end; a
+  // key press does not, so the gesture's result is held here until it does.
+  let pending: { left: number; top: number } | null = null;
+
+  /** End a key gesture: persist what it applied, once. */
+  const settle = (): void => {
+    if (pending === null) {
+      return;
+    }
+    const { left, top } = pending;
+    pending = null;
+    options.commit(left, top);
+  };
+
+  // Keyboard parity: a pointer-only move is unreachable without a mouse, and
+  // the launcher has no equivalent control elsewhere. Arrow keys are free on a
+  // button, so Enter and Space still expand.
+  launcher.addEventListener("keydown", (event: KeyboardEvent) => {
+    if (!options.enabled()) {
+      return;
+    }
+    const step = event.shiftKey ? COARSE_STEP : STEP;
+    const rect = options.rect();
+    let moved: { left: number; top: number } | null = null;
+    if (event.key === "ArrowLeft") {
+      moved = { left: rect.left - step, top: rect.top };
+    } else if (event.key === "ArrowRight") {
+      moved = { left: rect.left + step, top: rect.top };
+    } else if (event.key === "ArrowUp") {
+      moved = { left: rect.left, top: rect.top - step };
+    } else if (event.key === "ArrowDown") {
+      moved = { left: rect.left, top: rect.top + step };
+    }
+    if (moved === null) {
+      return;
+    }
+    event.preventDefault();
+    const next = clampLauncher({ ...rect, ...moved }, options.viewport());
+    // Live feedback per key event, persistence only when the gesture ends: a
+    // held arrow repeats at the OS rate, and committing here would put that
+    // many storage writes behind a single press.
+    options.apply(next.left, next.top);
+    pending = next;
+  });
+
+  // The key coming up ends the gesture, mirroring `pointerup`. `blur` closes
+  // one whose keyup never arrives here -- focus moved on mid-press -- because a
+  // position applied but never committed is a move the host silently forgets.
+  launcher.addEventListener("keyup", settle);
+  launcher.addEventListener("blur", settle);
+}

package/src/ui/launcher_placement.ts

@@ -0,0 +1,143 @@
+/** A box in viewport coordinates. */
+export interface LauncherBox {
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** A width/height pair, in CSS pixels. */
+export interface Extent {
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The corner the panel is pinned by, and therefore grows away from: pinned
+ * `top-left` opens down and to the right. It is also the corner the resize grip
+ * must stay off, which is why the element stamps it rather than measuring it
+ * once the launcher has been moved.
+ */
+export interface ExpandCorner {
+  readonly x: "left" | "right";
+  readonly y: "top" | "bottom";
+}
+
+/** Where to put the host box, and where the launcher sits inside it. */
+export interface LauncherPlacement {
+  /** The corner the panel opens away from. */
+  readonly corner: ExpandCorner;
+  /** An `inset` shorthand for the host box. */
+  readonly hostInset: string;
+  /** An `inset` shorthand for the launcher, relative to the host box. */
+  readonly launcherInset: string;
+}
+
+/**
+ * The gutter a panel keeps from the viewport edge, matching the default
+ * `--ag-ui-inset` so an undragged widget resolves to exactly the placement it
+ * already had. Changing this moves every clamped panel.
+ */
+const EDGE_MARGIN = 24;
+
+/**
+ * Decide where a panel should open from a launcher the user has dragged.
+ *
+ * The launcher is the fixed point: wherever it was dropped is where it stays,
+ * collapsed and expanded alike. Everything here decides what happens *around*
+ * it.
+ *
+ * Two steps, and they are separate on purpose:
+ *
+ * 1. **Pick the corner with the most clear space.** For each axis, compare the
+ *    room a panel would have on either side of the launcher and pin the side
+ *    with more of it. Pinning `left` means the panel runs rightward from the
+ *    launcher's left edge, so the room that decides it is the distance from
+ *    that edge to the far side of the viewport -- not "which half of the screen
+ *    is the launcher in", which gives a different and worse answer for a
+ *    launcher near the middle.
+ *
+ * 2. **Clamp the panel into the viewport, then put the launcher back.** A
+ *    launcher near the centre of a short viewport has a panel taller than
+ *    either side, so the winning corner still overflows. Clamping moves the
+ *    host box -- and the launcher is positioned inside that box, so it would be
+ *    dragged along with it. The launcher's own inset therefore carries the
+ *    difference: zero in the ordinary case, and exactly the distance the clamp
+ *    moved the box in the case that needs it. That the launcher may end up
+ *    outside its own host box is fine; nothing clips it, and it keeps its own
+ *    pointer events.
+ *
+ * Both insets are expressed from the *same* corner, which is what stops a
+ * later panel resize from dragging the launcher: the pinned corner is the one
+ * edge a resize cannot move.
+ */
+export function launcherPlacement(
+  launcher: LauncherBox,
+  panel: Extent,
+  viewport: Extent,
+  margin: number = EDGE_MARGIN,
+): LauncherPlacement {
+  // Room for a panel pinned to each side of the launcher. A tie goes to the
+  // first branch, so the result is deterministic for a centred launcher.
+  const roomRunningRight = viewport.width - launcher.left;
+  const roomRunningLeft = launcher.left + launcher.width;
+  const roomRunningDown = viewport.height - launcher.top;
+  const roomRunningUp = launcher.top + launcher.height;
+  const corner: ExpandCorner = {
+    x: roomRunningRight >= roomRunningLeft ? "left" : "right",
+    y: roomRunningDown >= roomRunningUp ? "top" : "bottom",
+  };
+
+  // The box the panel wants, then the box it can actually have. Clamping the
+  // near edge covers the far edge too: the panel is a fixed size here, and a
+  // panel too large for the viewport is held against the near margin and left
+  // to the max-width and max-height rules rather than centred by force.
+  const wantedLeft =
+    corner.x === "left" ? launcher.left : launcher.left + launcher.width - panel.width;
+  const wantedTop =
+    corner.y === "top" ? launcher.top : launcher.top + launcher.height - panel.height;
+  const hostLeft = clamp(wantedLeft, margin, viewport.width - margin - panel.width);
+  const hostTop = clamp(wantedTop, margin, viewport.height - margin - panel.height);
+
+  const hostRight = hostLeft + panel.width;
+  const hostBottom = hostTop + panel.height;
+
+  return {
+    corner,
+    hostInset: inset({
+      top: corner.y === "top" ? hostTop : null,
+      right: corner.x === "right" ? viewport.width - hostRight : null,
+      bottom: corner.y === "bottom" ? viewport.height - hostBottom : null,
+      left: corner.x === "left" ? hostLeft : null,
+    }),
+    // Measured from the host box's pinned corner to the launcher's matching
+    // corner, so the launcher lands exactly where it was dropped.
+    launcherInset: inset({
+      top: corner.y === "top" ? launcher.top - hostTop : null,
+      right: corner.x === "right" ? hostRight - (launcher.left + launcher.width) : null,
+      bottom: corner.y === "bottom" ? hostBottom - (launcher.top + launcher.height) : null,
+      left: corner.x === "left" ? launcher.left - hostLeft : null,
+    }),
+  };
+}
+
+/**
+ * Constrain a value, with the lower bound winning a contradiction. `Math.min`
+ * first would put a panel wider than the viewport off the left edge instead of
+ * against the near margin.
+ */
+function clamp(value: number, low: number, high: number): number {
+  return Math.max(low, Math.min(value, high));
+}
+
+/** An `inset` shorthand; a null side is `auto`, so the opposite one pins it. */
+function inset(sides: {
+  top: number | null;
+  right: number | null;
+  bottom: number | null;
+  left: number | null;
+}): string {
+  const side = (value: number | null): string =>
+    value === null ? "auto" : `${Math.round(value)}px`;
+  return `${side(sides.top)} ${side(sides.right)} ${side(sides.bottom)} ${side(sides.left)}`;
+}

package/src/ui/message_actions.ts

@@ -1,3 +1,4 @@
+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. */
@@ -18,6 +19,17 @@ export interface MessageActionsOptions {
    * disagree.
    */
   text?: () => string;
+  /**
+   * The rich flavour to copy alongside `text`, as an HTML fragment. Absent
+   * means the clipboard gets plain text only, which is what this did before
+   * the option existed.
+   *
+   * It is what makes a copied table paste as a table: a spreadsheet or a chat
+   * client reads `text/html` when it is offered and falls back to the plain
+   * flavour when it is not, so the two are the same content at two fidelities
+   * rather than a choice the caller has to make.
+   */
+  html?: () => string;
   /**
    * Report a rating for this message. Absent means no feedback buttons.
    *
@@ -53,7 +65,7 @@ export function attachMessageActions(bubble: HTMLElement, options: MessageAction
   const bar = messageActionBar(bubble, options.strings);
   const text = options.text;
   if (text !== undefined) {
-    bar.appendChild(copyButton(options.strings, text));
+    bar.appendChild(copyButton(options.strings, text, options.html));
   }
   if (options.onFeedback !== undefined) {
     bar.append(
@@ -98,38 +110,102 @@ function existingBar(bubble: HTMLElement): HTMLElement | null {
   return next?.classList.contains("message-actions") === true ? (next as HTMLElement) : null;
 }
 
-/** Build one action button, labelled for screen readers rather than by glyph. */
+/**
+ * Build one action button, labelled for screen readers rather than by glyph.
+ *
+ * `icon` is icon markup rather than a text glyph, because the text glyphs these
+ * carried are the obscure end of the character set -- the copy mark in
+ * particular has no font behind it on most systems, so it rendered as a mark
+ * nobody could name on a control small enough that nobody could hit it either.
+ *
+ * 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,
-  glyph: 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);
-  const icon = document.createElement("span");
-  icon.setAttribute("aria-hidden", "true");
-  icon.textContent = glyph;
-  button.appendChild(icon);
-  return button;
+  button.dataset["tooltip"] = label;
 }
 
-function copyButton(strings: UiStrings, text: () => string): HTMLButtonElement {
-  const button = messageActionButton("copy", strings.copyMessage, "⎘");
+function copyButton(
+  strings: UiStrings,
+  text: () => string,
+  html: (() => string) | undefined,
+): HTMLButtonElement {
+  const button = messageActionButton("copy", strings.copyMessage, ICON_COPY);
   button.addEventListener("click", () => {
-    void navigator.clipboard.writeText(text()).then(
-      () => flash(button, strings.copied, strings.copyMessage),
+    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, strings.copyFailed, strings.copyMessage),
-    );
+      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,
@@ -138,7 +214,7 @@ function feedbackButton(
   const button = messageActionButton(
     rating === "up" ? "up" : "down",
     label,
-    rating === "up" ? "\u{1F44D}" : "\u{1F44E}",
+    rating === "up" ? ICON_THUMB_UP : ICON_THUMB_DOWN,
   );
   button.addEventListener("click", () => {
     // Pressed rather than removed: the rating is a standing statement about the
@@ -159,12 +235,10 @@ function feedbackButton(
  * cannot happen and cannot be covered.
  */
 function flash(button: HTMLButtonElement, message: string, label: string): void {
-  button.title = message;
-  button.setAttribute("aria-label", message);
+  setLabel(button, message);
   button.classList.add("message-action--confirmed");
   setTimeout(() => {
-    button.title = label;
-    button.setAttribute("aria-label", label);
+    setLabel(button, label);
     button.classList.remove("message-action--confirmed");
   }, CONFIRM_MS);
 }