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

package/src/ui/placement/launcher_drag.ts

@@ -0,0 +1,206 @@
+import { clampLauncher } from "./clamp_launcher.js";
+import type { LauncherBox, ViewportBox } 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: () => ViewportBox;
+  /** 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;
+  /**
+   * Ends the launcher's own listeners when aborted. The launcher outlives the
+   * element's connection to the document and this is called on every connect,
+   * so without it a re-inserted element moved one arrow press two steps.
+   */
+  readonly signal: AbortSignal;
+}
+
+/**
+ * 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;
+  const { signal } = options;
+
+  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();
+    },
+    { capture: true, signal },
+  );
+
+  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);
+        window.removeEventListener("pointercancel", 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.
+      //
+      // pointercancel matters on touch, where it is routine rather than
+      // exceptional: the browser takes the pointer back for a scroll or a system
+      // gesture and never sends pointerup. Without this the move listeners stay
+      // attached and the drag stamp never clears, which leaves the launcher
+      // following a finger that has stopped and the element believing a gesture
+      // is still in flight.
+      window.addEventListener("pointermove", onMove);
+      window.addEventListener("pointerup", onUp);
+      window.addEventListener("pointercancel", onUp);
+    },
+    { signal },
+  );
+
+  // 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;
+    },
+    { signal },
+  );
+
+  // 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, { signal });
+  launcher.addEventListener("blur", settle, { signal });
+}

package/src/ui/placement/launcher_placement.ts

@@ -0,0 +1,133 @@
+import { SCREEN_EDGE_MARGIN } from "../../constants.js";
+import { clampPanel } from "./clamp_panel.js";
+import { placeWidget } from "./place_widget.js";
+
+/** A box in viewport coordinates. */
+export interface LauncherBox {
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The part of the screen a widget may rest in: a width and height, and the
+ * corner they start from.
+ *
+ * The origin is not always zero. A host can reserve the edges its own chrome
+ * occupies, and a panel clamped against a viewport that starts at the top-left
+ * of the screen will happily park itself underneath a sticky header -- where it
+ * cannot be reached, and where collapsing it only hides it further.
+ */
+export interface ViewportBox extends Extent {
+  readonly left: number;
+  readonly top: 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;
+}
+
+/**
+ * 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: ViewportBox,
+  screen: Extent,
+  margin: number = SCREEN_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.
+  //
+  // Measured against the usable box's own edges, not against its width and
+  // height as if it started at the origin. The launcher's coordinates are the
+  // screen's, while the extents have already had the host's reserved edges
+  // taken out of them, so mixing the two understates the room on one side and
+  // overstates it on the other -- by the same reserved inset, in opposite
+  // directions, which is what makes the comparison flip rather than merely
+  // drift. The clamp below reads `viewport.left`/`top`; this had to as well.
+  const roomRunningRight = viewport.left + viewport.width - launcher.left;
+  const roomRunningLeft = launcher.left + launcher.width - viewport.left;
+  const roomRunningDown = viewport.top + viewport.height - launcher.top;
+  const roomRunningUp = launcher.top + launcher.height - viewport.top;
+  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. The launcher
+  // is not moved by that clamp -- it is the fixed point of this gesture, so its
+  // own inset carries the difference and it can end up outside the host box.
+  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 host = clampPanel(
+    {
+      left: wantedLeft,
+      top: wantedTop,
+      right: wantedLeft + panel.width,
+      bottom: wantedTop + panel.height,
+    },
+    viewport,
+    margin,
+  );
+
+  // The usable box decides where things may rest; the screen is what the
+  // resulting insets are measured from. They are the same only when the host
+  // has reserved nothing.
+  return { corner, ...placeWidget(host, launcher, corner, screen) };
+}

package/src/ui/placement/launcher_styles.ts

@@ -0,0 +1,189 @@
+// The launcher a collapsed widget shrinks to: the round button, its unread
+// badge, and the sidebar's edge rail, which is the same element styled again.
+export const LAUNCHER_STYLES: string = `
+/* ── Launcher ───────────────────────────────────────────────────────────────
+   What a collapsed widget shrinks to: a round floating button by default, the
+   sidebar's slim edge rail under that placement. A sibling of the panel, so it
+   survives the panel being hidden, and the only part of a collapsed widget
+   that takes pointer events. */
+.launcher {
+  display: flex;
+  position: absolute;
+  inset: var(--_launcher-inset);
+  align-items: center;
+  justify-content: center;
+  width: var(--_launcher-size);
+  height: var(--_launcher-size);
+  padding: 0;
+  border: none;
+  border-radius: var(--_launcher-radius);
+  background: var(--_launcher-bg);
+  color: var(--_launcher-fg);
+  box-shadow: var(--_shadow);
+  font: inherit;
+  cursor: pointer;
+  pointer-events: auto;
+  /* A touch drag on the launcher moves it; without this the page scrolls under
+     the finger instead and the launcher never moves at all. */
+  touch-action: none;
+  opacity: 0;
+  transform: scale(0.4);
+  visibility: hidden;
+  transition:
+    opacity var(--_motion) var(--_ease),
+    transform var(--_motion) var(--_ease-pop),
+    visibility var(--_motion) var(--_ease);
+}
+
+/* The launcher grows out of the corner the panel shrank into. It stays laid
+   out at rest rather than display:none, which is what lets it animate both in
+   and out: an unrendered element has no before-change style to transition
+   from, and one flipping display to none cannot transition at all. visibility
+   keeps it unpaintable, untabbable and unclickable in between, so the expanded
+   panel's own controls underneath stay reachable. */
+:host([collapsed]) .launcher {
+  opacity: 1;
+  transform: none;
+  visibility: visible;
+}
+
+:host([collapsed]) .launcher:hover {
+  transform: scale(1.06);
+}
+
+:host([collapsed]) .launcher:active {
+  transform: scale(0.94);
+}
+
+/* A drag is a press and a hover at the same time, so both scale rules above are
+   live throughout it. Cancelling them is what keeps the launcher the size of
+   the thing under the pointer while it travels; the position itself comes from
+   inset, which nothing here transitions, so it tracks the pointer exactly. */
+:host([collapsed]) .launcher[data-dragging] {
+  transform: none;
+  cursor: grabbing;
+}
+
+.launcher .icon-holder {
+  width: var(--_launcher-icon-size);
+  height: var(--_launcher-icon-size);
+}
+
+/* The unread badge rides the launcher's top-right corner. The ring in the
+   widget's own background is what separates it from the launcher underneath,
+   whatever colour the host themes either one. */
+.launcher-badge {
+  position: absolute;
+  top: -2px;
+  right: -2px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  min-width: var(--_badge-size);
+  height: var(--_badge-size);
+  padding: 0 5px;
+  border-radius: 999px;
+  background: var(--_badge-bg);
+  color: var(--_badge-fg);
+  font-size: var(--_badge-font-size);
+  font-weight: 600;
+  line-height: 1;
+  box-shadow: 0 0 0 2px var(--_bg);
+}
+
+.launcher-badge[hidden] {
+  display: none;
+}
+
+/* The sidebar collapses to an edge rail instead: full height, square, flush
+   against the dock. It slides in with the panel rather than popping. */
+/* The edge rail. It reads as the docked edge of a panel rather than a coloured
+   stripe: the surface the panel is made of, a border on the side it docks
+   against, and the accent kept for the icon -- a full-height slab of accent is
+   the loudest thing on the page and says the least about itself.
+
+   Content sits at the top rather than centred, because a control floating in
+   the middle of a screen-high column has nothing to belong to. */
+:host([placement="sidebar"][collapsed]) .launcher {
+  inset: 0;
+  width: auto;
+  height: auto;
+  flex-direction: column;
+  align-items: center;
+  justify-content: flex-start;
+  gap: 12px;
+  padding-top: 14px;
+  border: 0;
+  border-inline-start: 1px solid var(--_border);
+  border-radius: 0;
+  background: var(--_bg);
+  color: var(--_fg);
+  box-shadow: none;
+  transform: none;
+}
+
+:host([placement="sidebar"][data-side="left"][collapsed]) .launcher {
+  border-inline-start: 0;
+  border-inline-end: 1px solid var(--_border);
+}
+
+/* The icon keeps the accent, so there is one obvious thing to press.
+
+   The glyph is sized here rather than left to fill the holder. A glyph in an
+   icon holder takes the holder's whole box by default, which is right where the
+   holder is only a box and wrong the moment it becomes a filled circle: the
+   mark then runs edge to edge and reads as a square crammed into a disc. The
+   proportion is the floating launcher's own -- a 26px glyph in a 56px bubble --
+   so the two collapsed states look like the same widget. */
+:host([placement="sidebar"][collapsed]) .launcher .icon-holder {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 34px;
+  height: 34px;
+  border-radius: 50%;
+  background: var(--_header-bg);
+  color: var(--_header-fg);
+}
+
+:host([placement="sidebar"][collapsed]) .launcher .icon-holder .glyph,
+:host([placement="sidebar"][collapsed]) .launcher .icon-holder .icon-img {
+  width: 16px;
+  height: 16px;
+}
+
+/* Written down the rail, which is the only direction it fits. Reading upward
+   is the convention for a right-hand edge and matches how a docked panel's
+   label is set everywhere it appears. */
+.rail-label {
+  display: none;
+}
+
+:host([placement="sidebar"][collapsed]) .rail-label {
+  display: block;
+  writing-mode: vertical-rl;
+  transform: rotate(180deg);
+  max-height: calc(100% - 96px);
+  overflow: hidden;
+  font-size: 0.9em;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+:host([placement="sidebar"][data-side="left"][collapsed]) .rail-label {
+  writing-mode: vertical-rl;
+  transform: none;
+}
+
+/* Every transition in the stylesheet is timed by --_motion, so collapsing it to a
+   frame is the whole reduced-motion story: states still change (and display
+   still flips at the end of its discrete transition), nothing travels. */
+@media (prefers-reduced-motion: reduce) {
+  :host {
+    --_motion: var(--ag-ui-motion, 0.001s);
+  }
+}
+`;

package/src/ui/placement/page_styles.ts

@@ -0,0 +1,47 @@
+// The page and full placements: a full-bleed surface with a reading column.
+export const PAGE_STYLES: string = `
+/* Page: full-bleed background with a centred reading column capped at
+   --ag-ui-content-max-width, where "full" is edge-to-edge and left-aligned.
+   The column comes from symmetric auto padding on the scroll area and
+   composer rather than a per-row wrapper, so user pills still right-align and
+   the assistant well spans the column. */
+:host([placement="page"]) {
+  --_inset: var(
+    --ag-ui-inset,
+    calc(var(--_viewport-inset-top) + var(--_keyboard-inset-top)) var(--_viewport-inset-right)
+      var(--_viewport-inset-bottom) var(--_viewport-inset-left)
+  );
+  --_width: var(--ag-ui-width, var(--_viewport-width));
+  --_height: var(--ag-ui-height, var(--_viewport-height));
+  --_max-width: var(--ag-ui-max-width, var(--_viewport-width));
+  --_max-height: var(--ag-ui-max-height, var(--_viewport-height));
+  --_panel-radius: var(--ag-ui-panel-radius, 0);
+}
+
+:host([placement="page"]) .messages {
+  padding-inline: max(var(--_pad), calc((100% - var(--_content-max-width)) / 2));
+}
+
+:host([placement="page"]) .input-row {
+  padding-inline: max(12px, calc((100% - var(--_content-max-width)) / 2));
+}
+
+/* The rows between the message list and the composer line up with the column
+   too. Chips and tray are padding-based while palette and hint are
+   margin-based, so each gets its own inline axis nudged by the same gutter. */
+:host([placement="page"]) .skill-chips,
+:host([placement="page"]) .attachment-tray {
+  padding-inline: max(12px, calc((100% - var(--_content-max-width)) / 2));
+}
+
+:host([placement="page"]) .skill-palette,
+:host([placement="page"]) .skill-hint {
+  margin-inline: max(12px, calc((100% - var(--_content-max-width)) / 2));
+}
+
+/* In the reading column the assistant well uses the full width; the user
+   message stays a right-aligned pill (its default align-self + max-width). */
+:host([placement="page"]) .message--assistant {
+  max-width: 100%;
+}
+`;