Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

14.0 KB
Raw Blame
/**
 * The tooltip (src/components/overlays/tooltip/tooltip.tsx): where it hangs its panel and how wide
 * the panel may grow, the rule that decides whether a hint shows at all, and how the one
 * `TooltipLayer` reads a `data-tooltip` request.
 *
 * The panel is pinned by one horizontal edge and grows away from it, so the only width it can
 * safely take is the room between that edge and the viewport margin on the far side. A long
 * text — a background process's command, shown whole — wraps at that room instead of running off
 * a phone's screen; a short label never reaches it.
 *
 * Vertically, a panel hangs under a toolbar control, with three cases once its height is known:
 * - Given a control at the foot of the window (the composer's context ring) and a panel taller
 *   than the room left below it, then the panel stands over the control, pinned by its bottom
 *   edge, instead of running past the window's bottom.
 * - Given a panel that fits below, then it stays below, however low the control sits.
 * - Given a panel too tall for either side, then it takes the roomier one.
 *
 * The rule: a hint shows for an element with no visible text of its own, or one whose visible
 * text is cut off — never for a label the reader can already read in full. An SVG's text and
 * anything `aria-hidden` are not read as words; a hint marked as carrying what the screen does
 * not show (`data-tooltip-extra`) opens over visible text all the same.
 *
 * A shortened line nobody wrote a hint for still shows its whole text:
 * - Given a line shortened by an ellipsis or a line clamp, when the pointer rests on it (or on
 *   an ancestor-held span inside it), then it is the line asked about.
 * - Given a row control holding a title and a description, when the pointer rests anywhere on
 *   the row, then both lines are candidates, in order, so whichever is cut off can show.
 * - Given a panel that merely contains shortened rows, when the pointer rests on its padding,
 *   then nothing is asked about: a panel is not one line.
 * - Given a `<Tooltip>` wrapper or a title that scrolls its own tail into view
 *   (`data-tooltip-owned`), then no full-text hint is added inside it.
 * - The whole text shows in the code panel for a monospace line (a path), the text panel
 *   otherwise, and a blank line asks for nothing.
 *
 * The panel itself mounts only while hovered and through a portal, which a static render cannot
 * reach; what it may be drawn with (the overlay surface, token inks, the glass hook) is pinned
 * against the source. Where the app may still use a native `title` is the web app's
 * `no-native-title.test.ts`.
 */
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { createElement } from "react";
import { describe, expect, it } from "vitest";
import {
  TOOLTIP_OWNED_ATTR,
  Tooltip,
  belowTrigger,
  besideTrigger,
  hintAllowed,
  isCutOff,
  lineRequest,
  namedHint,
  readingText,
  shortenedLines,
  shortensText,
  tooltipRequest,
  type LineNode,
  type LineStyle,
  type ReadingNode,
} from "../src/components/overlays/tooltip/tooltip";
import { renderStatic } from "../src/testing";
import { SRC_DIR } from "./helpers/paths";

const VIEWPORT = { width: 1000, height: 800 };

/** A trigger box from its left/top corner and size. */
const box = (left: number, top: number, width: number, height: number) => ({
  left,
  top,
  width,
  height,
  right: left + width,
  bottom: top + height,
});

describe("belowTrigger", () => {
  it("anchors by the right edge in the right half, with the room reaching back to the left margin", () => {
    // A command line near the right of the window: the panel grows leftward from its right edge.
    expect(belowTrigger(box(700, 100, 200, 20), VIEWPORT)).toEqual({
      top: 128,
      right: 100,
      room: 892,
    });
  });

  it("anchors by the left edge in the left half, with the room reaching to the right margin", () => {
    // A phone-width card: the room, not the panel's own cap, is what keeps the text on screen.
    expect(belowTrigger(box(40, 100, 200, 20), { width: 390, height: 800 })).toEqual({
      top: 128,
      left: 40,
      room: 342,
    });
  });

  it("keeps the anchored edge inside the viewport margin", () => {
    expect(belowTrigger(box(900, 0, 100, 20), VIEWPORT).right).toBe(8);
    expect(belowTrigger(box(-20, 0, 100, 20), VIEWPORT).left).toBe(8);
  });

  it("stands a panel with no room below over a control at the foot of the window", () => {
    // The composer's context ring, 21px above the bottom edge, and its one-line hint.
    expect(belowTrigger(box(40, 747, 32, 32), VIEWPORT, 26)).toEqual({
      bottom: 61,
      left: 40,
      room: 952,
    });
  });

  it("keeps a panel that fits below there, however low its control sits", () => {
    expect(belowTrigger(box(40, 700, 32, 32), VIEWPORT, 26)).toEqual({
      top: 740,
      left: 40,
      room: 952,
    });
  });

  it("puts a panel too tall for either side on the roomier one", () => {
    expect(belowTrigger(box(40, 200, 32, 32), VIEWPORT, 700)).toMatchObject({ top: 240 });
    expect(belowTrigger(box(40, 560, 32, 32), VIEWPORT, 700)).toMatchObject({ bottom: 248 });
  });
});

describe("besideTrigger", () => {
  it("hangs to the right of a rail entry, centred on it, with the room to the right margin", () => {
    expect(besideTrigger(box(8, 200, 32, 32), VIEWPORT)).toEqual({ top: 216, left: 48, room: 944 });
  });

  it("clamps the centre into the viewport and never reports negative room", () => {
    const offscreen = besideTrigger(box(990, 900, 32, 32), VIEWPORT);
    expect(offscreen.top).toBe(792);
    expect(offscreen.room).toBe(0);
  });
});

const clip = (scrollWidth: number, clientWidth: number, scrollHeight = 16, clientHeight = 16) => ({
  scrollWidth,
  clientWidth,
  scrollHeight,
  clientHeight,
});

describe("isCutOff", () => {
  it("reads overflow on either axis as cut off", () => {
    expect(isCutOff(clip(240, 120))).toBe(true);
    expect(isCutOff(clip(100, 100, 40, 20))).toBe(true);
  });

  it("forgives the pixel of overflow layout reports for text that fits", () => {
    expect(isCutOff(clip(101, 100, 17, 16))).toBe(false);
    expect(isCutOff(clip(100, 100))).toBe(false);
  });
});

describe("hintAllowed", () => {
  it("shows the hint of an element with no text of its own (an icon, a chart mark)", () => {
    expect(hintAllowed("", [clip(24, 24)])).toBe(true);
    expect(hintAllowed("   ", [])).toBe(true);
  });

  it("shows the hint when the visible text is cut off anywhere inside", () => {
    expect(hintAllowed("A very long Session title", [clip(200, 200), clip(320, 180)])).toBe(true);
  });

  it("shows no hint for text that is fully visible, whatever the hint would add", () => {
    expect(hintAllowed("3 min ago", [clip(60, 60), clip(58, 60)])).toBe(false);
    expect(hintAllowed("Copy prompt", [])).toBe(false);
  });
});

describe("what counts as visible text, and the mark that overrides it", () => {
  const text = (value: string): ReadingNode => ({ nodeType: 3, nodeValue: value, childNodes: [] });
  const el = (
    localName: string,
    children: ReadingNode[],
    attrs: Record<string, string> = {},
  ): ReadingNode => ({
    nodeType: 1,
    nodeValue: null,
    localName,
    childNodes: children,
    getAttribute: (name) => attrs[name] ?? null,
  });

  it("skips an SVG's text and anything aria-hidden: an avatar's initial or a letter icon is no label", () => {
    const avatar = el("span", [el("svg", [el("text", [text("A")])])]);
    const caseToggle = el("button", [el("span", [text("Aa")], { "aria-hidden": "true" })]);
    const labelled = el("button", [text("Clear "), el("span", [text("exited")])]);
    expect(readingText(avatar)).toBe("");
    expect(readingText(caseToggle)).toBe("");
    expect(readingText(labelled)).toBe("Clear exited");
    expect(hintAllowed(readingText(avatar), [clip(16, 16)])).toBe(true);
  });

  it("opens a hint marked data-tooltip-extra over text that is fully visible, React's false left unmarked", () => {
    const request = (extra: string) => {
      const attrs: Record<string, string> = {
        "data-tooltip": "Their captured output is discarded too",
        "data-tooltip-extra": extra,
      };
      return tooltipRequest({ getAttribute: (name: string) => attrs[name] ?? null });
    };
    expect(request("true")?.extra).toBe(true);
    expect(request("false")?.extra).toBe(false);
    expect(hintAllowed("Clear exited", [clip(80, 80)], true)).toBe(true);
  });
});

describe("a data-tooltip request", () => {
  const el = (attrs: Record<string, string>) => ({
    getAttribute: (name: string) => attrs[name] ?? null,
  });

  it("reads the text, the kind and the side, defaulting to a label below", () => {
    expect(tooltipRequest(el({ "data-tooltip": "Rename" }))).toEqual({
      label: "Rename",
      content: "label",
      placement: "bottom",
      extra: false,
    });
    expect(
      tooltipRequest(
        el({
          "data-tooltip": "npm run dev",
          "data-tooltip-content": "code",
          "data-tooltip-placement": "right",
        }),
      ),
    ).toEqual({ label: "npm run dev", content: "code", placement: "right", extra: false });
  });

  it("asks for nothing when the text is missing or blank", () => {
    expect(tooltipRequest(el({}))).toBeNull();
    expect(tooltipRequest(el({ "data-tooltip": "  " }))).toBeNull();
  });
});

describe("a shortened line with no hint of its own", () => {
  const plain: LineStyle = { textOverflow: "clip", lineClamp: "none", fontFamily: "Inter" };
  const ellipsis: LineStyle = { ...plain, textOverflow: "ellipsis" };

  /** A hand-built element: a tag, its attributes, how it sets its text, and its children. */
  interface FakeNode extends LineNode {
    name: string;
    style: LineStyle;
    children: FakeNode[];
  }
  const node = (
    name: string,
    style: LineStyle,
    children: FakeNode[] = [],
    attrs: string[] = [],
  ): FakeNode => {
    const self: FakeNode = {
      name,
      style,
      children,
      parentElement: null,
      hasAttribute: (attr) => attrs.includes(attr),
      matches: (selector) => selector.split(",").some((s) => s.trim().split(/[[.]/)[0] === name),
      querySelectorAll: () => descendants(self),
    };
    for (const child of children) child.parentElement = self;
    return self;
  };
  const descendants = (n: FakeNode): FakeNode[] =>
    n.children.flatMap((child) => [child, ...descendants(child)]);
  const styleOf = (n: FakeNode) => n.style;

  it("counts an ellipsis or a line clamp as shortening, plain clipping as not", () => {
    expect(shortensText(ellipsis)).toBe(true);
    expect(shortensText({ ...plain, lineClamp: "2" })).toBe(true);
    expect(shortensText(plain)).toBe(false);
    expect(shortensText({ ...plain, lineClamp: "" })).toBe(false);
  });

  it("asks about the line the pointer rests on, or the shortened line around it", () => {
    const text = node("span", plain);
    const line = node("p", ellipsis, [text]);
    node("div", plain, [line]);
    expect(shortenedLines(line, styleOf)).toEqual({ at: line, lines: [line] });
    expect(shortenedLines(text, styleOf)).toEqual({ at: line, lines: [line] });
  });

  it("offers every line of a row control, title and description in order", () => {
    const title = node("span", ellipsis);
    const description = node("p", ellipsis);
    const row = node("button", plain, [node("div", plain, [title, description])]);
    expect(shortenedLines(row, styleOf)).toEqual({ at: row, lines: [title, description] });
  });

  it("asks about nothing on a panel that merely holds shortened rows", () => {
    const panel = node("div", plain, [node("button", plain, [node("span", ellipsis)])]);
    expect(shortenedLines(panel, styleOf)).toBeNull();
  });

  it("adds nothing inside a subtree whose hint someone else decides", () => {
    const scrolling = node("span", ellipsis, [node("span", plain)], [TOOLTIP_OWNED_ATTR]);
    expect(shortenedLines(scrolling, styleOf)).toBeNull();
    expect(shortenedLines(scrolling.children[0]!, styleOf)).toBeNull();
    const wrapped = node("span", plain, [node("span", ellipsis)], [TOOLTIP_OWNED_ATTR]);
    const row = node("button", plain, [wrapped, node("span", ellipsis)]);
    expect(shortenedLines(row, styleOf)?.lines).toEqual([row.children[1]]);
  });

  it("shows the whole text in the code panel for a monospace line, the text panel otherwise", () => {
    const mono = { ...ellipsis, fontFamily: 'ui-monospace, "JetBrains Mono", monospace' };
    expect(lineRequest("  feedback/review-style.md ", mono)).toEqual({
      label: "feedback/review-style.md",
      content: "code",
      placement: "bottom",
      extra: false,
    });
    expect(lineRequest("A long memory description", ellipsis)?.content).toBe("text");
    expect(lineRequest("   ", ellipsis)).toBeNull();
  });
});

describe("namedHint", () => {
  it("names a wordless mark with the words its hint shows", () => {
    expect(namedHint("Bar 3")).toEqual({
      role: "img",
      "aria-label": "Bar 3",
      "data-tooltip": "Bar 3",
    });
  });
});

describe("Tooltip", () => {
  it("wraps its trigger in the measuring span, which owns the hints inside, and renders no panel until hovered", () => {
    const html = renderStatic(
      createElement(Tooltip, { label: "Settings", className: "mt-auto", children: "gear" }),
    );
    expect(html).toBe('<span data-tooltip-owned="" class="flex mt-auto">gear</span>');
    // Deliberately no tooltip role or description: the trigger's own name is the one name.
    expect(html).not.toContain('role="tooltip"');
    expect(html).not.toContain("aria-describedby");
  });

  it("draws the panel on the overlay surface in token inks, as a glass layer that takes no clicks", () => {
    const source = readFileSync(join(SRC_DIR, "components/overlays/tooltip/tooltip.tsx"), "utf8");
    const panel = /className=\{`(ui-glass [^`]*)`\}/.exec(source);
    expect(panel, "the panel's class string").not.toBeNull();
    const tokens = panel![1]!.split(/\s+/);
    expect(tokens).toEqual(
      expect.arrayContaining([
        "ui-glass",
        "pointer-events-none",
        "border-line",
        "bg-overlay",
        "text-fg",
        "z-[60]",
      ]),
    );
    expect(source).toContain("aria-hidden");
  });
});