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

package/src/ui/place/place_chip.ts

@@ -0,0 +1,146 @@
+import type { Context } from "@ag-ui/core";
+import {
+  ICON_PLACE,
+  ICON_PLACE_SHARED,
+  ICON_PLACE_WITHHELD,
+  PLACE_CONTEXT,
+} from "../../constants.js";
+import { fillUiString } from "../fill_ui_string.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "../ui_strings.js";
+import type { Place } from "./place.js";
+
+/** What identifies a place for the exclusion: its href, else its label and detail. */
+function keyOf(place: Place): string {
+  return place.href ?? `${place.label}\u0000${place.detail ?? ""}`;
+}
+
+/** Draw `text` into `el`, hiding it when there is none. */
+function setText(el: HTMLElement, text: string | undefined): void {
+  el.textContent = text ?? "";
+  el.hidden = text === undefined;
+}
+
+/**
+ * The "you are here" chip in the composer's tool row, and the context entry it stands for.
+ *
+ * The exclusion is keyed on the place: it holds across turns on the same place and lapses
+ * when a different one is read. A read of no place keeps it, so a page naming nothing
+ * mid-navigation does not undo it. Nothing persists, and nothing the host sets can lift it.
+ */
+export class PlaceChip {
+  readonly element: HTMLElement = document.createElement("div");
+  /** The same place for the collapsed bar, drawn by the same render. */
+  readonly barElement: HTMLElement = document.createElement("span");
+  readonly #barLabel: HTMLElement = document.createElement("span");
+  readonly #barDetail: HTMLElement = document.createElement("span");
+  readonly #icon: HTMLElement = document.createElement("span");
+  readonly #label: HTMLElement = document.createElement("span");
+  readonly #detail: HTMLElement = document.createElement("span");
+  readonly #toggle: HTMLButtonElement = document.createElement("button");
+  #place: Place | null = null;
+  #excluded: string | null = null;
+  #strings: UiStrings = DEFAULT_UI_STRINGS;
+
+  constructor() {
+    this.element.className = "place";
+    this.element.setAttribute("part", "place");
+    this.element.hidden = true;
+    this.#icon.className = "place-icon";
+    this.#icon.setAttribute("part", "place-icon");
+    this.#label.className = "place-label";
+    this.#label.setAttribute("part", "place-label");
+    this.#detail.className = "place-detail";
+    this.#detail.setAttribute("part", "place-detail");
+    this.#toggle.type = "button";
+    this.#toggle.className = "place-toggle";
+    this.#toggle.setAttribute("part", "place-toggle");
+    const text = document.createElement("span");
+    text.className = "place-text";
+    text.append(this.#label, this.#detail);
+    this.element.append(this.#icon, text, this.#toggle);
+    this.barElement.className = "bar-place";
+    this.barElement.setAttribute("part", "bar-place");
+    this.barElement.hidden = true;
+    this.#barLabel.className = "place-label";
+    this.#barLabel.setAttribute("part", "place-label");
+    this.#barDetail.className = "place-detail";
+    this.#barDetail.setAttribute("part", "place-detail");
+    this.barElement.append(this.#barLabel, this.#barDetail);
+  }
+
+  /** Wire the toggle for one connection, with the strings it resolved. */
+  mount(signal: AbortSignal, strings: UiStrings): void {
+    this.#strings = strings;
+    this.#toggle.addEventListener("click", () => this.#flip(), { signal });
+    this.#render();
+  }
+
+  /** Show a fresh read; null hides the chip and sends nothing. */
+  update(place: Place | null): void {
+    if (place !== null && this.#excluded !== null && this.#excluded !== keyOf(place)) {
+      this.#excluded = null;
+    }
+    this.#place = place;
+    this.#render();
+  }
+
+  /** Whether there is a place and the user withheld it, which withholds the page too. */
+  get withheld(): boolean {
+    return this.#place !== null && this.#excluded !== null;
+  }
+
+  /** The round's context entry: the place as shown, without its icon, or nothing. */
+  context(): Context[] {
+    const place = this.#place;
+    if (place === null || this.#excluded !== null) {
+      return [];
+    }
+    const sent = {
+      label: place.label,
+      ...(place.detail === undefined ? {} : { detail: place.detail }),
+      ...(place.href === undefined ? {} : { href: place.href }),
+    };
+    return [{ description: PLACE_CONTEXT, value: JSON.stringify(sent) }];
+  }
+
+  #flip(): void {
+    const place = this.#place;
+    if (place === null) {
+      return;
+    }
+    this.#excluded = this.#excluded === null ? keyOf(place) : null;
+    this.#render();
+  }
+
+  #render(): void {
+    const place = this.#place;
+    this.element.hidden = place === null;
+    this.barElement.hidden = place === null;
+    if (place === null) {
+      return;
+    }
+    const shared = this.#excluded === null;
+    this.element.toggleAttribute("data-excluded", !shared);
+    this.barElement.toggleAttribute("data-excluded", !shared);
+    if (place.icon === undefined) {
+      this.#icon.innerHTML = ICON_PLACE;
+    } else {
+      const img = document.createElement("img");
+      img.src = place.icon;
+      img.alt = "";
+      this.#icon.replaceChildren(img);
+    }
+    setText(this.#label, place.label);
+    setText(this.#detail, place.detail);
+    setText(this.#barLabel, place.label);
+    setText(this.#barDetail, place.detail);
+    this.element.title = fillUiString(
+      shared ? this.#strings.placeShared : this.#strings.placeWithheld,
+      { label: place.label },
+    );
+    const action = shared ? this.#strings.placeStopSharing : this.#strings.placeShareAgain;
+    this.#toggle.innerHTML = shared ? ICON_PLACE_SHARED : ICON_PLACE_WITHHELD;
+    this.#toggle.title = action;
+    this.#toggle.setAttribute("aria-label", action);
+  }
+}

package/src/ui/place/place_from_route.ts

@@ -0,0 +1,27 @@
+import type { RouteMap } from "../../tools/route_map.js";
+import type { Place } from "./place.js";
+
+/** A route path template as an anchored pattern, each placeholder one segment. */
+function pattern(path: string): RegExp {
+  const escaped = path
+    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+    .replace(/:[A-Za-z_][A-Za-z0-9_]*/g, "[^/]+");
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * The place a route map implies: the first route whose path template matches
+ * `pathname`, its title (else its id) as the label, its group as the detail,
+ * and the path as the href. Null when no route matches.
+ */
+export function placeFromRoute(routes: RouteMap, pathname: string): Place | null {
+  const route = routes.find((candidate) => pattern(candidate.path).test(pathname));
+  if (route === undefined) {
+    return null;
+  }
+  return {
+    label: route.title ?? route.id,
+    ...(route.group === undefined ? {} : { detail: route.group }),
+    href: pathname,
+  };
+}

package/src/ui/place/place_styles.ts

@@ -0,0 +1,108 @@
+// The place chip: where in the app the user is, drawn in the composer's tool
+// row between the attach and voice controls and Send.
+export const PLACE_STYLES: string = `
+/* One quiet pill: a mark, the place, its detail, and the eye toggle. Muted at
+   rest so it reads as a fact about the message rather than a control. It takes
+   what the row's buttons leave and shrinks before Send can leave the row: the
+   label truncates with an ellipsis and the chip's title carries it in full. */
+.place {
+  display: inline-flex;
+  align-items: center;
+  flex: 0 1 auto;
+  gap: 6px;
+  min-width: 0;
+  height: var(--_tool-btn-size);
+  box-sizing: border-box;
+  margin-inline-start: 4px;
+  padding: 0 2px 0 8px;
+  border: 1px solid var(--_border);
+  border-radius: 999px;
+  color: var(--_muted);
+  font-size: 0.85em;
+  line-height: 1;
+}
+
+.place-icon {
+  display: inline-flex;
+  flex: none;
+}
+
+.place-icon .glyph,
+.place-toggle .glyph,
+.place-icon img {
+  width: 14px;
+  height: 14px;
+}
+
+.place-icon img {
+  border-radius: 3px;
+}
+
+.place-text {
+  display: inline-flex;
+  gap: 6px;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.place-label,
+.place-detail {
+  flex: 0 1 auto;
+  min-width: 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.place-label {
+  color: var(--_fg);
+}
+
+.place-detail::before {
+  content: "\\00B7";
+  margin-inline-end: 6px;
+}
+
+.place-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: transparent;
+  color: var(--_muted);
+  cursor: pointer;
+}
+
+.place-toggle:hover {
+  background: var(--_hover);
+  color: var(--_fg);
+}
+
+/* An author display beats the user-agent rule for the hidden property, so each
+   class above that sets one says it again for the hidden state: a chip with no
+   place takes no space in the row. */
+.place[hidden],
+.place-icon[hidden],
+.place-text[hidden],
+.place-detail[hidden],
+.place-toggle[hidden] {
+  display: none;
+}
+
+/* Withheld from the next message: dashed and struck through, so the chip still
+   says where the user is while saying plainly the agent is not told. */
+.place[data-excluded] {
+  border-style: dashed;
+}
+
+.place[data-excluded] .place-label,
+.place[data-excluded] .place-detail {
+  color: var(--_muted);
+  text-decoration: line-through;
+}
+`;

package/src/ui/placement/clamp_launcher.ts

@@ -0,0 +1,38 @@
+import { SCREEN_EDGE_MARGIN } from "../../constants.js";
+import type { LauncherBox, ViewportBox } from "./launcher_placement.js";
+
+/**
+ * Keep a launcher fully on screen, and a little clear of the edge.
+ *
+ * Applied to a dragged position and again to a restored one, because the
+ * viewport that stored it may since have shrunk. A launcher parked past the
+ * edge is unreachable, and it is the only way back to a collapsed
+ * conversation.
+ *
+ * Not the panel's 24px gutter, which was rejected here on purpose: a launcher
+ * held that far in refuses the corners people actually drag it to. But not
+ * zero either -- the bubble is a circle with a drop shadow, and one flush
+ * against the boundary has its shadow cut and its curve running into the edge,
+ * which reads as clipped whether or not a pixel is actually missing.
+ */
+export function clampLauncher(
+  launcher: LauncherBox,
+  viewport: ViewportBox,
+  margin: number = SCREEN_EDGE_MARGIN,
+): { readonly left: number; readonly top: number } {
+  // The margin is given up rather than enforced where it does not fit: a
+  // viewport narrower than the bubble and its two margins would otherwise
+  // produce a lower bound above the upper one and pin it to the wrong edge.
+  const room = Math.min(margin, Math.max(0, (viewport.width - launcher.width) / 2));
+  const vertical = Math.min(margin, Math.max(0, (viewport.height - launcher.height) / 2));
+  return {
+    left: Math.max(
+      viewport.left + room,
+      Math.min(launcher.left, viewport.left + viewport.width - launcher.width - room),
+    ),
+    top: Math.max(
+      viewport.top + vertical,
+      Math.min(launcher.top, viewport.top + viewport.height - launcher.height - vertical),
+    ),
+  };
+}

package/src/ui/placement/clamp_panel.ts

@@ -0,0 +1,30 @@
+import { EDGE_MARGIN } from "../../constants.js";
+import type { ViewportBox } from "./launcher_placement.js";
+import type { PanelRect } from "./resize_handle.js";
+
+/**
+ * Hold a panel inside the viewport, keeping its size.
+ *
+ * The near edge is clamped and the far edge follows, so 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. The lower bound wins a
+ * contradiction for the same reason: `Math.min` first would put an oversized
+ * panel off the left edge instead of against the margin it can still honour.
+ */
+export function clampPanel(
+  host: PanelRect,
+  viewport: ViewportBox,
+  margin: number = EDGE_MARGIN,
+): PanelRect {
+  const width = host.right - host.left;
+  const height = host.bottom - host.top;
+  const left = Math.max(
+    viewport.left + margin,
+    Math.min(host.left, viewport.left + viewport.width - margin - width),
+  );
+  const top = Math.max(
+    viewport.top + margin,
+    Math.min(host.top, viewport.top + viewport.height - margin - height),
+  );
+  return { left, top, right: left + width, bottom: top + height };
+}