@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/tooltip.gts

@@ -0,0 +1,212 @@
+// Pretui — Tooltip: a short description of its trigger, shown on hover and focus.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { guidFor } from '@ember/object/internals';
+import { modifier } from 'ember-modifier';
+import { listen, listenDocumentCapture } from '../focus';
+
+// The element a Tooltip describes. The trigger arrives as a caller block, so
+// the component finds it rather than receiving it — the first thing in the
+// wrapper the keyboard can reach, falling back to the wrapper's first element
+// child for a non-focusable trigger (a static badge, a truncated cell).
+const TRIGGER_SELECTOR =
+  'a[href], button, input, select, textarea, [tabindex], [role]';
+
+export interface TooltipSignature {
+  Args: {
+    content: string;
+    side?: 'top' | 'bottom' | 'left' | 'right';
+    /**
+     * Name the trigger instead of describing it. `aria-describedby` is the
+     * APG recommendation and the default here; Web Awesome deliberately ships
+     * `aria-labelledby` because several screen readers announce a description
+     * inconsistently (or not at all) on a control that already has a name.
+     * Set this when the tooltip text IS the control's name — an icon-only
+     * button whose only label is its tip.
+     */
+    labels?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLSpanElement;
+}
+
+/**
+ * Always-dark (both modes — "the lining").
+ *
+ * **Rebuilt 2026-08-13.** The previous version carried `role='tooltip'` and
+ * nothing else: no id, no `aria-describedby`, and the bubble sat in the DOM
+ * permanently with only `opacity` animated — so its text was read as ambient
+ * page content next to every trigger, forever, and no assistive technology
+ * could tell it apart from the trigger's own content. It also failed two of
+ * WCAG 1.4.13's three conditions: not dismissible (no Escape) and not
+ * hoverable (`pointer-events: none`, so a magnified reader could never move
+ * onto the bubble).
+ *
+ * What it does now:
+ *
+ * - **Association.** The bubble gets a generated id and a modifier wires
+ *   `aria-describedby` (or `aria-labelledby` with `@labels`) onto the first
+ *   focusable descendant — the trigger is a caller block, so the component
+ *   cannot put the attribute there itself. The modifier restores whatever was
+ *   there before on teardown, so it composes with a caller's own value.
+ * - **Presence.** Hidden state is `visibility: hidden`, not opacity alone, so
+ *   the bubble leaves the accessibility tree between reveals. A directly
+ *   referenced `aria-describedby` target is still announced while hidden —
+ *   that is the accname rule this pattern is built on.
+ * - **Dismissible.** Escape hides it, in the capture phase, while it is open.
+ * - **Hoverable.** `pointer-events` are live and a transparent bridge spans
+ *   the 6px gap, so the pointer can travel from trigger to bubble.
+ *
+ * The reveal is state-driven rather than pure CSS because Escape needs a
+ * dismissed flag; the state is only ever written from event handlers, never
+ * during render.
+ */
+export class Tooltip extends Component<TooltipSignature> {
+  @tracked private hovered = false;
+  @tracked private focused = false;
+  @tracked private dismissed = false;
+  tipId = `${guidFor(this)}-tip`;
+  get side() {
+    return this.args.side ?? 'top';
+  }
+  get shown() {
+    return (this.hovered || this.focused) && !this.dismissed;
+  }
+  /** Wires the tip onto the yielded trigger and puts it back on teardown. */
+  describeTrigger = modifier(
+    (el: HTMLElement, [id, labels]: [string, boolean | undefined]) => {
+      let attr = labels ? 'aria-labelledby' : 'aria-describedby';
+      let trigger =
+        Array.from(el.querySelectorAll<HTMLElement>(TRIGGER_SELECTOR)).find(
+          (candidate) => candidate.id !== id,
+        ) ?? (el.firstElementChild as HTMLElement | null);
+      if (!trigger || trigger.id === id) return;
+      let previous = trigger.getAttribute(attr);
+      trigger.setAttribute(attr, previous ? `${previous} ${id}` : id);
+      return () => {
+        if (previous === null) {
+          trigger.removeAttribute(attr);
+        } else {
+          trigger.setAttribute(attr, previous);
+        }
+      };
+    },
+  );
+  onEnter = () => {
+    this.hovered = true;
+  };
+  onLeave = () => {
+    this.hovered = false;
+    this.dismissed = false;
+  };
+  onFocusIn = () => {
+    this.focused = true;
+  };
+  onFocusOut = () => {
+    this.focused = false;
+    this.dismissed = false;
+  };
+  // WCAG 1.4.13 "Dismissible". Capture phase + stopPropagation so one Escape
+  // means exactly one thing — hide THIS tip — and never also closes the
+  // dialog the trigger happens to live in.
+  onKey = (e: Event) => {
+    if (!this.shown) return;
+    if ((e as KeyboardEvent).key !== 'Escape') return;
+    e.stopPropagation();
+    this.dismissed = true;
+  };
+  <template>
+    <span
+      class='pretui-tipwrap'
+      data-test-pretui-tooltip
+      {{this.describeTrigger this.tipId @labels}}
+      {{listen 'mouseenter' this.onEnter}}
+      {{listen 'mouseleave' this.onLeave}}
+      {{listen 'focusin' this.onFocusIn}}
+      {{listen 'focusout' this.onFocusOut}}
+      ...attributes
+    >
+      {{yield}}
+      <span
+        role='tooltip'
+        id={{this.tipId}}
+        class='pretui-tooltip'
+        data-side={{this.side}}
+        data-open={{if this.shown 'true'}}
+      >{{@content}}</span>
+      {{#if this.shown}}
+        <span
+          class='pretui-tip-key'
+          {{listenDocumentCapture 'keydown' this.onKey}}
+        ></span>
+      {{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-tipwrap {
+          position: relative;
+          display: inline-flex;
+        }
+        .pretui-tip-key {
+          display: none;
+        }
+        .pretui-tooltip {
+          position: absolute;
+          /* kit stacking scale (pretui-css.gts): a tooltip describes whatever
+             is under the pointer, which may be an item inside a dropdown or a
+             popover, so it is the highest non-modal tier. */
+          z-index: var(--pretui-z-tooltip, 80);
+          background: var(--tooltip, var(--boxel-dark));
+          color: var(--tooltip-foreground, var(--boxel-light));
+          font-size: var(--text-ui-sm, 11.5px);
+          font-weight: 500;
+          padding: 4px 8px;
+          border-radius: 6px;
+          box-shadow: 0 4px 14px var(--shadow-ink-strong, rgb(0 0 0 / 0.16));
+          white-space: nowrap;
+          width: max-content;
+          opacity: 0;
+          /* `visibility`, not opacity alone: an opacity-0 bubble is still in
+             the accessibility tree and still hit-testable. Hidden here means
+             hidden to everyone — while a DIRECT aria-describedby reference
+             still resolves its text, which is the whole point. */
+          visibility: hidden;
+          transition: opacity 120ms ease, visibility 0s linear 120ms;
+        }
+        .pretui-tooltip[data-open='true'] {
+          opacity: 1;
+          visibility: visible;
+          transition: opacity 120ms ease, visibility 0s;
+        }
+        /* WCAG 1.4.13 "Hoverable": the pointer must be able to travel onto the
+           bubble without it vanishing. The gap between trigger and bubble is
+           bridged by a transparent extension of the bubble's own box. */
+        .pretui-tooltip::before {
+          content: '';
+          position: absolute;
+          inset: -6px;
+        }
+        .pretui-tooltip[data-side='top'] {
+          bottom: calc(100% + 6px);
+          left: 50%;
+          transform: translateX(-50%);
+        }
+        .pretui-tooltip[data-side='bottom'] {
+          top: calc(100% + 6px);
+          left: 50%;
+          transform: translateX(-50%);
+        }
+        .pretui-tooltip[data-side='left'] {
+          right: calc(100% + 6px);
+          top: 50%;
+          transform: translateY(-50%);
+        }
+        .pretui-tooltip[data-side='right'] {
+          left: calc(100% + 6px);
+          top: 50%;
+          transform: translateY(-50%);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/tooltip.md

@@ -0,0 +1,53 @@
+## What it is
+
+A short label that appears on hover or keyboard focus, positioned against the element it wraps. Use it for naming icon-only controls and for abbreviating a value that is already visible. It is not a place to put information the user _needs_ — the content is one line, unselectable, and vanishes the moment the pointer leaves. If the user must read or interact with it, use **Popover**; if it is a persistent hint under a field, use **FormField**'s description slot; if it is a status message, use **Alert** or **Toast**.
+
+## The contract
+
+```
+@content (string, required), @side? ('top'|'bottom'|'left'|'right', default 'top')
+<:default> — the trigger, rendered inline
+```
+
+That is the whole API, and the smallness is the point. Two decisions follow from it.
+
+**It is CSS-only.** There is no JavaScript, no timer, no state. The reveal is `:hover` / `:focus-within` on the wrapper toggling opacity. Consequences: it is prerender-safe (nothing to run before hydration), it cannot leak a timer, and it costs zero on a page with two hundred of them — which matters, because tooltips are what you sprinkle across a dense table. The cost is no show/hide delay, so tooltips flash as the pointer crosses a toolbar.
+
+**Positioning is `position: absolute` against a `position: relative` wrapper, with no collision handling.** A tooltip on a control at the right edge of the viewport will overflow it. `@side` is a static choice, not a preference. This is a deliberate departure from the rest of the kit's overlays, which use the `anchorTo` measuring modifier — the trade is made for prerender safety and per-instance cost.
+
+The tooltip is **always dark**, in both light and dark modes — the kit calls this "the lining". It is a deliberate constant so the affordance reads identically everywhere.
+
+## Prior art
+
+**Web Awesome `wa-tooltip`** is the fullest: `placement`, `distance`, `skidding`, `open`, `disabled`, `show-delay` (150ms) / `hide-delay`, `trigger` (`'hover focus'`, also `click`/`manual`), `without-arrow`, and a `for` attribute associating the tooltip to a trigger _by id_ rather than by wrapping it. **Radix `Tooltip`** requires a `Provider` so a group shares `delayDuration` and `skipDelayDuration` — cross the toolbar quickly and subsequent tooltips appear instantly, which is the single best tooltip detail in the ecosystem. **React Spectrum** adds warmup/cooldown timing and is explicit that tooltips must never contain interactive content.
+
+Pretui is smaller than all three on purpose, and it is worth being clear that here the kit is _behind_, not ahead: no delay, no group coordination, no collision flip, no arrow. What it buys is a component with no runtime at all.
+
+One place Pretui is genuinely better: `@content` is a plain string, not a slot. Radix and Web Awesome accept arbitrary children, which invites people to put buttons and links inside tooltips — an accessibility disaster that every one of those libraries then documents against. Making the type `string` makes the mistake unrepresentable.
+
+## Accessibility
+
+Governing rules: APG **Tooltip** pattern (still marked as under review upstream, and widely regarded as the least settled pattern in the APG) and **WCAG 2.1 SC 1.4.13 Content on Hover or Focus**, which requires hover/focus-triggered content to be _dismissible_ (Escape without moving the pointer), _hoverable_ (the pointer can move onto it without it disappearing), and _persistent_ (it stays until dismissed, the pointer leaves, or it is no longer valid).
+
+Pretui's honest scorecard:
+
+- `role="tooltip"` is present on the bubble. **But the bubble is not associated with the trigger** — there is no `aria-describedby` and no `aria-labelledby`, and no id is generated. A screen-reader user focusing the trigger is told nothing. Since the tooltip is rendered unconditionally in the DOM (only opacity changes), the text is also read as ordinary adjacent content, at all times, whether or not the tooltip is showing. This is the component's most serious defect.
+- Worth noting what the field has learned here: `wa-tooltip` deliberately uses **`aria-labelledby`, not `aria-describedby`**, with a comment that it gives the most consistent screen-reader result — several readers only announce `describedby` on a genuinely focusable element, whereas `labelledby` reads on first focus. The APG recommends `describedby`. Whichever Pretui adopts, adopting _one_ is the fix.
+- **Not dismissible** (SC 1.4.13): no Escape handling.
+- **Not hoverable** (SC 1.4.13): `pointer-events: none` on the bubble means moving the pointer onto the tooltip is impossible. For a one-line label this rarely matters in practice, but it is a literal failure of the criterion.
+- Persistent: passes — there is no timeout.
+- `white-space: nowrap` means long content will not wrap and will overflow rather than reflow.
+- `:focus-within` correctly covers keyboard focus, so the _visual_ affordance is keyboard-reachable even though the semantic one is missing.
+
+Do not ship a tooltip as the only name for an icon button until the association gap is closed — give the button an `aria-label` as well.
+
+## Theming
+
+`--tooltip` and `--tooltip-foreground` (the always-dark pair a theme must define for _both_ modes, not just light), `--shadow-ink-strong`, `--text-ui-sm`. Radius (6px), padding and the 6px offset are hard-coded. A theme that defines only a light value for `--tooltip` will produce a light-on-light tooltip in dark mode — this is the one token here that is easy to get wrong.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Short string only. Rich hover content is **HoverCard**. Accept `delayDuration`
+as `@openDelay`. WCAG 1.4.13: hoverable, dismissable (Esc), persistent.

package/bundled-realms/pretui/components/tooltip.usage.gts

@@ -0,0 +1,64 @@
+// Pretui — Tooltip usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Tooltip } from './tooltip';
+import { Button } from './button';
+import { SIDE_OPTIONS } from '../demo-structure';
+
+// Note: Pretui Tooltip is CSS-only — it reveals on hover/focus-within, with
+// no floating-ui positioning or JS listeners (prerender-safe by design).
+// Dropped knobs: offset (fixed 6px gap, no arg); variant (single always-dark
+// treatment — "the lining"); the six boxel-tooltip-* CSS-variable knobs
+// (CSS knob layer not yet ported).
+class TooltipUsage extends GlimmerComponent {
+  @tracked content = 'Tooltip Content';
+  @tracked side = 'top';
+  setContent = (v: string) => (this.content = v);
+  setSide = (v: string) => (this.side = v);
+  get sideVal() {
+    return this.side as 'top' | 'bottom' | 'left' | 'right';
+  }
+  <template>
+    <FreestyleUsage
+      @name='Tooltip'
+      @description='Tooltips provide additional information when hovering over an element. Pretui Tooltip is CSS-only — it reveals on hover and focus-within, always dark in both modes, with no JS positioning.'
+    >
+      <:example>
+        <Tooltip @content={{this.content}} @side={{this.sideVal}}>
+          <Button @tone='neutral' @appearance='outlined'>Button With Tooltip</Button>
+        </Tooltip>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='side'
+          @description='The positioning of the tooltip relative to the reference element.'
+          @value={{this.side}}
+          @options={{SIDE_OPTIONS}}
+          @defaultValue='top'
+          @onInput={{this.setSide}}
+        />
+        <Args.String
+          @name='content'
+          @description='Tooltip text. Replaces the :content block — Pretui Tooltip takes a plain string.'
+          @value={{this.content}}
+          @required={{true}}
+          @onInput={{this.setContent}}
+        />
+        <Args.Yield
+          @description='The element the tooltip is attached to; the tooltip reveals on its hover and focus-within.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+// Menu’s page moved to demo-menu.gts with the 2026-08-13 rebuild — the
+// component grew submenus, checkmark/radio items, the full APG keyboard
+// contract and a shared MenuNode tree with CommandPalette, which is more
+// than a page in this file should carry.
+
+export const DEMOS_TOOLTIP: Record<string, unknown> = {
+  Tooltip: TooltipUsage,
+};