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

package/src/ui/shell/build_launcher.ts

@@ -0,0 +1,79 @@
+import { ICON_LAUNCHER } from "../../constants.js";
+import type { UiStrings } from "../ui_strings.js";
+import { iconElement } from "./icon_element.js";
+
+/** The launcher's parts, owned by the element, and what fills them. */
+export interface LauncherOptions {
+  readonly launcher: HTMLButtonElement;
+  readonly badge: HTMLElement;
+  readonly railLabel: HTMLElement;
+  /** The bottom bar's wrapper, which holds the launcher and the history button. */
+  readonly bar: HTMLElement;
+  /** The bottom bar's history button, a sibling of the launcher in the bar. */
+  readonly barHistory: HTMLButtonElement;
+  /** The place beside the title, which its owner shows and hides. */
+  readonly barPlace: HTMLElement;
+  readonly titleText: string;
+  readonly iconUrl: string | null;
+  readonly strings: UiStrings;
+  readonly signal: AbortSignal;
+  readonly onOpen: () => void;
+  readonly onHistory: () => void;
+}
+
+/**
+ * Build what a collapsed widget shrinks to: a round floating button, the slim
+ * edge rail under `placement="sidebar"`, or the strip along the bottom edge
+ * under `collapse-to="bar"` -- one element, shaped by the stylesheet. The
+ * element mounts the bar wrapper as a sibling of the panel, so it survives the
+ * panel being hidden.
+ *
+ * The wrapper is there for the bar's history button: a button cannot nest in
+ * a button, so the strip is the launcher and the history button side by side.
+ * Outside the bar the wrapper draws no box and the history button is not
+ * drawn, so the launcher lays out against the host exactly as it did alone.
+ */
+export function buildLauncher(options: LauncherOptions): void {
+  const { launcher, badge, railLabel, bar, barHistory, barPlace } = options;
+  launcher.className = "launcher";
+  launcher.type = "button";
+  launcher.setAttribute("part", "launcher");
+  launcher.setAttribute("aria-label", options.strings.expand);
+  badge.className = "launcher-badge";
+  badge.setAttribute("part", "launcher-badge");
+  // The count is announced through the launcher's own label, so the badge is
+  // decoration to a screen reader rather than a second, context-free number.
+  badge.setAttribute("aria-hidden", "true");
+  badge.hidden = true;
+  // Only the edge rail shows this. A full-height column carrying one small
+  // icon reads as a coloured stripe rather than a way back into a
+  // conversation -- it is the widest collapsed state there is and the one
+  // that says least about itself. Written here and hidden in CSS everywhere
+  // else, because the launcher is one element shaped by placement.
+  railLabel.className = "rail-label";
+  railLabel.setAttribute("part", "rail-label");
+  railLabel.setAttribute("aria-hidden", "true");
+  railLabel.textContent = options.titleText;
+  launcher.replaceChildren(
+    iconElement("launcher", "launcher-icon", ICON_LAUNCHER, options.iconUrl),
+    railLabel,
+    badge,
+  );
+  launcher.addEventListener("click", options.onOpen, { signal: options.signal });
+  bar.className = "dock-bar";
+  bar.setAttribute("part", "bar");
+  barHistory.className = "bar-history";
+  barHistory.type = "button";
+  barHistory.setAttribute("part", "bar-history");
+  barHistory.title = options.strings.chatHistory;
+  barHistory.setAttribute("aria-label", options.strings.chatHistory);
+  // A glyph rather than the header's icon slot: a slot name may appear once
+  // per shadow root, and the header's history button already holds it.
+  const glyph = document.createElement("span");
+  glyph.className = "bar-history-glyph";
+  glyph.setAttribute("aria-hidden", "true");
+  glyph.textContent = "\u2630";
+  barHistory.replaceChildren(glyph);
+  barHistory.addEventListener("click", options.onHistory, { signal: options.signal });
+  bar.replaceChildren(launcher, barPlace, barHistory);
+}

package/src/ui/shell/collapse_glyph.ts

@@ -0,0 +1,42 @@
+import {
+  ICON_CHEVRON_DOWN,
+  ICON_CHEVRON_LEFT,
+  ICON_CHEVRON_RIGHT,
+  ICON_CHEVRON_UP,
+  ICON_PANEL_CLOSE_LEFT,
+  ICON_PANEL_CLOSE_RIGHT,
+} from "../../constants.js";
+
+/**
+ * The collapse control's mark for the element's `data-collapse-icon`,
+ * `placement` and `data-side`, read live by the caller.
+ *
+ * Unset, or a value it does not name, follows the placement: a docked column
+ * (`sidebar`, and the undocumented `side`) hides sideways into its edge, so it
+ * takes the panel mark, and everything else -- the corners, `full`,
+ * `embedded`, an unknown placement -- keeps the chevron down. The panel mark
+ * points into the edge the panel docks to, so it is mirrored for either docked
+ * placement on `data-side="left"`, whether it was chosen or defaulted. The
+ * chevrons are absolute.
+ */
+export function collapseGlyph(
+  choice: string | null,
+  placement: string | null,
+  side: string | null,
+): string {
+  switch (choice) {
+    case "chevron-up":
+      return ICON_CHEVRON_UP;
+    case "chevron-down":
+      return ICON_CHEVRON_DOWN;
+    case "chevron-left":
+      return ICON_CHEVRON_LEFT;
+    case "chevron-right":
+      return ICON_CHEVRON_RIGHT;
+  }
+  const docked = placement === "sidebar" || placement === "side";
+  if (choice !== "panel-close" && !docked) {
+    return ICON_CHEVRON_DOWN;
+  }
+  return docked && side === "left" ? ICON_PANEL_CLOSE_LEFT : ICON_PANEL_CLOSE_RIGHT;
+}

package/src/ui/shell/frame_styles.ts

@@ -0,0 +1,147 @@
+// The panel itself and its header: title, icon holder and header controls.
+export const FRAME_STYLES: string = `
+.chat {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  background: var(--_bg);
+  border: 1px solid var(--_border);
+  border-radius: var(--_panel-radius);
+  box-shadow: var(--_shadow);
+  overflow: hidden;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--_border);
+  background: var(--_header-bg);
+  color: var(--_header-fg);
+}
+
+/* The header is the panel's title bar: on the placements that let the widget
+   be moved it drags the whole thing, matching the launcher's own drag. The
+   selector lists those placements rather than asking JS to stamp an attribute,
+   because a cursor that appears one frame late reads as a control that only
+   sometimes exists. touch-action keeps a finger drag here moving the panel
+   instead of scrolling the page behind it. */
+:host(:not([placement])) .header,
+:host([placement=""]) .header,
+:host([placement="floating"]) .header,
+:host([placement="bottom-left"]) .header {
+  cursor: move;
+  touch-action: none;
+}
+
+/* A host that turned the drag off keeps a header that says so. */
+:host([data-launcher-drag="false"]) .header {
+  cursor: auto;
+  touch-action: auto;
+}
+
+/* A panel that is the screen has nowhere to go, so its header refuses the drag
+   and must not offer it. No selector can see that a host has sized the panel to
+   the window, so the placement stamps this from the measurement that refuses the
+   drag. :host is carried for the specificity, not the scope, as below. Before the
+   dragging rule, so a drag the header did take keeps its grabbing cursor. */
+:host .header[data-fills-screen] {
+  cursor: auto;
+}
+
+/* :host is carried for the specificity, not the scope: the placement rules
+   above are a host selector plus a class plus an attribute, and a bare
+   .header[data-dragging] loses to them -- silently, because the drag still
+   works and only the cursor is wrong. */
+:host .header[data-dragging] {
+  cursor: grabbing;
+}
+
+/* The cursor inherits, so a control a host slots into the header would show
+   the drag cursor over something the drag deliberately ignores. Named to
+   match the controls panel_drag steps aside for. */
+.header ::slotted(:is(button, a, input, select, textarea)) {
+  cursor: pointer;
+}
+
+.header-title {
+  flex: 1;
+  min-width: 0;
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Header / launcher icon holder: a slot, with a data-icon-url <img>
+   fallback, sized via --ag-ui-icon-size. */
+.icon-holder {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--_icon-size);
+  height: var(--_icon-size);
+  line-height: 1;
+}
+
+.icon-img {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  border-radius: var(--_icon-radius);
+}
+
+.header-controls {
+  display: flex;
+  gap: var(--_header-gap);
+  flex: none;
+}
+
+/* Under every theme: once the host sets the header text, the header behind the
+   buttons is the host's colour, so their rest opacity goes. The frame's 0.85
+   lets the header through the glyph, which took white on a mid-blue header from
+   5.1:1 to 4.2:1. With the header text set, the opacity below reads a colour,
+   which no opacity can be, so it is invalid at computed-value time and falls to
+   the initial 1; unset, it reads the fallback. The glyph is each theme's own
+   business: this inherits the header text, and a theme that draws the buttons
+   in another ink reads the same switch to yield. */
+.header-btn {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  width: var(--_header-btn-size);
+  height: var(--_header-btn-size);
+  border: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  line-height: 1;
+  padding: 0;
+  border-radius: 6px;
+  cursor: pointer;
+  opacity: var(--_header-fg-set, 0.85);
+}
+
+/* The square is the host's own when it set one; otherwise it is mixed from the
+   header text when the host set that, so it reads on any header the host
+   painted; otherwise it is the theme's own. See the alias in the token defaults. */
+.header-btn:hover {
+  opacity: 1;
+  background: var(--_header-btn-hover);
+}
+
+/* Every built-in header mark is a drawn glyph at the composer's size; the theme
+   toggle's holder takes that size too, so its moon matches its neighbours. */
+.header-btn .glyph,
+.header-btn .icon-holder {
+  width: var(--_glyph-size);
+  height: var(--_glyph-size);
+}
+`;

package/src/ui/shell/glyph_slot.ts

@@ -0,0 +1,12 @@
+/**
+ * A `<slot>` a host can project its own mark into, falling back to one of the
+ * built-in glyphs. The markup is an author-written constant, never user or
+ * server data, so it is assigned directly rather than sanitised.
+ */
+export function glyphSlot(slotName: string, className: string, markup: string): HTMLSlotElement {
+  const slot = document.createElement("slot");
+  slot.name = slotName;
+  slot.className = className;
+  slot.innerHTML = markup;
+  return slot;
+}

package/src/ui/shell/header_button.ts

@@ -0,0 +1,22 @@
+/**
+ * Build a header control button: a named slot a host can project markup into,
+ * with the built-in glyph (static SVG markup from `constants.ts`) as the slot's
+ * fallback.
+ *
+ * The slot is what lets a host replace the mark with its own `<img>` or
+ * `<svg>` rather than only restyle it through the `part`; the same
+ * slot-with-fallback idiom the header icon uses.
+ */
+export function headerButton(modifier: string, label: string, glyph: string): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = `header-btn header-btn--${modifier}`;
+  button.setAttribute("part", `header-button ${modifier}-button`);
+  button.title = label;
+  button.setAttribute("aria-label", label);
+  const slot = document.createElement("slot");
+  slot.name = `icon-${modifier}`;
+  slot.innerHTML = glyph;
+  button.append(slot);
+  return button;
+}

package/src/ui/shell/icon_element.ts

@@ -0,0 +1,33 @@
+/**
+ * An icon holder wrapping a `<slot>` so a host can project custom markup;
+ * with an `<img>` as the slot's fallback when an icon URL is configured, or
+ * the given glyph markup when it is not.
+ *
+ * `iconUrl` is the caller's to read rather than defaulted here, because the
+ * three marks answer it differently: the header's is `data-icon-url`, the
+ * launcher's falls back to it from an attribute of its own, and the theme
+ * toggle never takes an image at all.
+ */
+export function iconElement(
+  slotName: string,
+  part: string,
+  fallbackGlyph: string | null,
+  iconUrl: string | null,
+): HTMLSpanElement {
+  const holder = document.createElement("span");
+  holder.className = "icon-holder";
+  holder.setAttribute("part", part);
+  const slot = document.createElement("slot");
+  slot.name = slotName;
+  if (iconUrl !== null) {
+    const img = document.createElement("img");
+    img.className = "icon-img";
+    img.src = iconUrl;
+    img.alt = "";
+    slot.append(img);
+  } else if (fallbackGlyph !== null) {
+    slot.innerHTML = fallbackGlyph;
+  }
+  holder.append(slot);
+  return holder;
+}

package/src/ui/shell/is_unread_badge_enabled.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether the launcher's unread badge is shown.
+ *
+ * The unread badge, unlike every other affordance here, is on by default:
+ * a collapsed widget is the one state where an answer can arrive with nothing
+ * on screen to say so. `data-unread-badge="false"` turns it off for a host
+ * that drives its own chrome from the `ag-ui-unread` event.
+ */
+export function isUnreadBadgeEnabled(element: Element): boolean {
+  return element.getAttribute("data-unread-badge") !== "false";
+}

package/src/ui/shell/read_launcher_icon_url.ts

@@ -0,0 +1,9 @@
+/**
+ * The launcher's own image URL. `data-launcher-icon-url` lets the collapsed
+ * button carry a different mark from the header's — a product logo reads at
+ * 22px in a header bar but rarely at 26px in a circle — and falls back to the
+ * header icon so a single `data-icon-url` still feeds both.
+ */
+export function readLauncherIconUrl(element: Element): string | null {
+  return element.getAttribute("data-launcher-icon-url") ?? element.getAttribute("data-icon-url");
+}

package/src/ui/shell/theme_styles.ts

@@ -0,0 +1,11 @@
+// The density presets: token overrides only. The themes live in ui/themes.
+export const THEME_STYLES: string = `
+/* ── Density ────────────────────────────────────────────────────────────── */
+:host([density="compact"]) {
+  --_font-size: var(--ag-ui-font-size, 13px);
+  --_space: var(--ag-ui-space, 6px);
+  --_pad: var(--ag-ui-pad, 10px);
+  --_msg-pad: var(--ag-ui-msg-pad, 5px 9px);
+  --_msg-radius: var(--ag-ui-msg-radius, 10px);
+}
+`;