# Context

How much of the context window the conversation has used.

Source: https://webjs.dev/ui/docs/ai-elements/context

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { progressClass } from '#components/ui/progress.ts';

const usage = {
  input: 8420,
  output: 1260,
  reasoning: 980,
  limit: 128000,
};

const used = usage.input + usage.output + usage.reasoning;
const percent = Math.round((used / usage.limit) * 100);

function formatTokens(value: number) {
  if (value < 1000) return String(value);
  return `${(value / 1000).toFixed(1).replace(/\.0$/, '')}k`;
}

const rows = [
  { label: 'Input', value: usage.input },
  { label: 'Output', value: usage.output },
  { label: 'Reasoning', value: usage.reasoning },
];

// The class on <ui-hover-card-content> lands on the card panel, as shadcn's
// className on HoverCardContent does.
export default function ContextDemo() {
  return html`
    <div class="flex justify-center py-12">
      <ui-hover-card open-delay="10" close-delay="100">
        <ui-hover-card-trigger>
          <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${buttonClass({ variant: 'outline', size: 'sm' })}>
            ${percent}% context
          </button>
        </ui-hover-card-trigger>
        <ui-hover-card-content class="flex w-64 flex-col gap-3">
          <div class="flex items-center justify-between gap-3 text-sm">
            <span data-slot="hover-card-title" class="font-medium">Context</span>
            <span class="text-muted-foreground">${formatTokens(used)} / ${formatTokens(usage.limit)}</span>
          </div>
          <progress data-slot="progress" value=${percent} max="100" aria-label="Context used" class=${progressClass()}></progress>
          <div class="flex flex-col gap-1 text-sm">
            ${rows.map((row) => html`
              <div class="flex justify-between gap-3">
                <span class="text-muted-foreground">${row.label}</span>
                <span>${formatTokens(row.value)}</span>
              </div>
            `)}
          </div>
        </ui-hover-card-content>
      </ui-hover-card>
    </div>
  `;
}
```

Context shows how much of the model's context window the conversation has used. It is a [Hover Card](https://webjs.dev/ui/docs/components/hover-card) with a [Progress](https://webjs.dev/ui/docs/components/progress) bar.

## Installation

Context is built with the [Hover Card](https://webjs.dev/ui/docs/components/hover-card) and [Progress](https://webjs.dev/ui/docs/components/progress) components.

```bash
npx @webjsdev/ui add hover-card progress
```

### Install the following dependencies:

```bash
npx @webjsdev/ui add hover-card progress
```

### Copy and paste the following code into your project.

````ts title="components/ui/hover-card.ts"
/**
 * HoverCard: popover-like panel triggered by hover with configurable
 * open / close delays. Tier-2. The content uses the native Popover API
 * in `popover="manual"` mode for top-layer rendering; the custom
 * element owns the hover-with-linger state machine and JS positioning.
 *
 * shadcn parity:
 *   HoverCard          → <ui-hover-card open-delay close-delay>
 *   HoverCardTrigger   → <ui-hover-card-trigger>
 *   HoverCardContent   → <ui-hover-card-content side align side-offset align-offset>
 *
 * Attributes on <ui-hover-card>:
 *   `open`:        boolean (reflected). Open state.
 *   `open-delay`:  ms, default 700. Hover delay before opening.
 *   `close-delay`: ms, default 300. Linger delay before closing once
 *                  cursor leaves trigger + content.
 *
 * Attributes on <ui-hover-card-content>:
 *   `side`:         "top" | "right" | "bottom" (default) | "left".
 *   `align`:        "center" (default) | "start" | "end".
 *   `side-offset`:  number, default 4. Pixels between trigger and content.
 *   `align-offset`: number, default 0. Pixels of cross-axis shift.
 *
 * Events:
 *   `ui-open-change` on <ui-hover-card>: `{ detail: { open } }` on every open
 *   and close, shadcn's `onOpenChange`. The `open` attribute is reflected too.
 *
 * Programmatic API on <ui-hover-card>: `.show()` · `.hide()`.
 *
 * Keyboard:
 *   Tab      from the trigger into the card, whose content stays open while it
 *            holds focus, so links and buttons inside it are reachable
 *   Escape   dismiss the card, returning focus to the trigger when the card
 *            held it
 *
 * A11y (owned by the element, mostly nothing to supply):
 *   The trigger opens on focus as well as hover and carries `aria-haspopup` /
 *   `aria-expanded` / `aria-controls`. The panel is a `role="dialog"`, which
 *   REQUIRES an accessible name, so the element always gives it one, from the
 *   first of: an `aria-label` / `aria-labelledby` you put on
 *   `<ui-hover-card-content>`, a `[data-slot="hover-card-title"]` or heading
 *   inside the card, or the trigger itself (the card is about whatever the
 *   trigger names). Escape dismisses it and hands focus back when the card had
 *   it, and the content keeps itself open while focus is inside.
 *   What you DO supply: a name for the trigger control if it is icon-only, and
 *   ideally a title node in the card so its name describes the card rather
 *   than falling back to the trigger's text.
 *   Touch: the hover and focus linger paths are gated to pointer devices, so on
 *   a no-hover device the card is tap-toggled and dismissed by an outside tap
 *   (#745). Do not remove that gate to "fix" keyboard behaviour.
 *
 * Design tokens used: --popover, --popover-foreground, --border.
 *
 * @example
 * ```html
 * <ui-hover-card open-delay="700" close-delay="300">
 *   <ui-hover-card-trigger>
 *     <a href="/user/vivek">@vivek</a>
 *   </ui-hover-card-trigger>
 *   <ui-hover-card-content>
 *     <div class="flex gap-3">
 *       <img class="size-10 rounded-full" src="/avatars/vivek.jpg" alt="Vivek Khandelwal">
 *       <div>
 *         <div class="text-sm font-semibold" data-slot="hover-card-title">Vivek Khandelwal</div>
 *         <p class="text-sm text-muted-foreground">Builds the platform, not against it.</p>
 *         <a class="text-sm underline" href="/user/vivek/posts">Read the posts</a>
 *       </div>
 *     </div>
 *   </ui-hover-card-content>
 * </ui-hover-card>
 * ```
 */
import { WebComponent, html, prop } from '@webjsdev/core';
import { cn, ensureId, takeAuthoredClass } from '../lib/utils.ts';
import { onBeforeCache } from '../lib/dom.ts';
import { positionFloating } from './floating.ts';
import type { PopoverSide, PopoverAlign } from './popover.ts';

// `fixed m-0` opts out of the UA `[popover]` auto-centering margin so
// JS-computed top/left from positionFloating lands correctly. shadcn's
// visual layer sits on top. `not-open:hidden` hides a closed panel, which
// the UA `[popover]:not(:popover-open)` rule cannot do once any author
// `display` applies (see popoverContentClass).
export const hoverCardContentClass = (): string =>
  'fixed w-64 m-0 rounded-md border bg-popover p-4 text-popover-foreground shadow-md z-50 origin-(--radix-hover-card-content-transform-origin) outline-hidden not-open:hidden';

// --------------------------------------------------------------------------
// <ui-hover-card>
// --------------------------------------------------------------------------

export class UiHoverCard extends WebComponent({
  open: prop(Boolean, { reflect: true }),
  // `openDelay` / `closeDelay` ride the `open-delay` / `close-delay`
  // attributes (shadcn parity), read as typed props.
  openDelay: Number,
  closeDelay: Number,
}) {
  _showTimer: number | undefined;
  _hideTimer: number | undefined;

  _keyHandler = (e: KeyboardEvent): void => this._onKeyDown(e);

  constructor() {
    super();
    this.open = false;
    this.openDelay = 700;
    this.closeDelay = 300;
  }

  _disposeBeforeCache?: () => void;

  connectedCallback(): void {
    super.connectedCallback?.();
    // webjs projects slotted light-DOM children after the first render, so
    // the trigger control is not in place at connect. Defer to the next
    // frame, when the projection has run.
    if (typeof requestAnimationFrame === 'function') {
      requestAnimationFrame(() => this._wireAria());
    }
    // Close before the page is cached for back/forward so a restored snapshot
    // does not come back frozen open (#766).
    this._disposeBeforeCache = onBeforeCache(() => { this.open = false; });
  }

  disconnectedCallback(): void {
    this._unbindEscape();
    this._disposeBeforeCache?.();
    super.disconnectedCallback?.();
  }

  // A hover card can hold interactive content and cover what is under it, so a
  // keyboard user needs a way out that is not "tab through the whole card".
  // Bound only WHILE OPEN so a closed card cannot swallow Escape.
  _onKeyDown(e: KeyboardEvent): void {
    if (e.key !== 'Escape' || !this.open) return;
    e.preventDefault();
    this._dismiss();
  }

  // Immediate, unlike hide()'s close-delay linger, since a dismissal is
  // deliberate. Focus moves out BEFORE the panel hides: the content is
  // popover="manual", so hiding it while a descendant holds focus drops focus
  // to <body> and the user loses their place on the page.
  _suppressReopen = false;

  _dismiss(): void {
    clearTimeout(this._showTimer);
    clearTimeout(this._hideTimer);
    this._closeReleasingFocus();
  }

  _focusIsInContent(): boolean {
    if (typeof document === 'undefined') return false;
    const content = this.querySelector('ui-hover-card-content');
    const active = document.activeElement;
    return !!content && !!active && content.contains(active);
  }

  _bindEscape(): void {
    if (typeof document === 'undefined') return;
    document.addEventListener('keydown', this._keyHandler);
  }

  _unbindEscape(): void {
    if (typeof document === 'undefined') return;
    document.removeEventListener('keydown', this._keyHandler);
  }

  // The trigger also opens on focus (see the @focusin handler), so it is
  // keyboard-reachable: expose the popup relationship on the focusable
  // control. aria-expanded is refreshed on every open transition.
  _control(): HTMLElement | null {
    const t = this.querySelector('ui-hover-card-trigger');
    if (!t) return null;
    return (
      t.querySelector<HTMLElement>('a[href], button, [tabindex], [role="button"]') ??
      (t as HTMLElement)
    );
  }

  _wireAria(): void {
    const control = this._control();
    if (!control) return;
    control.setAttribute('aria-haspopup', 'dialog');
    control.setAttribute('aria-expanded', String(this.open));
    const content = this.querySelector<HTMLElement>('ui-hover-card-content [role="dialog"]');
    if (!content) return;
    control.setAttribute('aria-controls', ensureId(content, 'ui-hovercard'));
    this._nameContent(content, control);
  }

  // role="dialog" REQUIRES an accessible name. Without one a screen reader
  // announces a bare "dialog" with no hint of what it holds, which is an ARIA
  // defect rather than a missing nicety. Three sources, most specific first:
  //   1. what the author put on <ui-hover-card-content>, which always wins
  //   2. a title node inside the card (the dialog.ts idiom)
  //   3. the trigger, since the card is ABOUT whatever the trigger names
  //      ("@vivek" names that user's card). Same fallback the dropdown menu
  //      already uses to label its panel back to its trigger.
  // Source 3 is what makes the name unconditional: there is no shape of this
  // component that can end up with an unnamed dialog role.
  _nameContent(content: HTMLElement, control: HTMLElement): void {
    const host = this.querySelector('ui-hover-card-content');
    // aria-labelledby is checked FIRST because it beats aria-label per accname,
    // matching dialog / alert-dialog / toggle. Checking aria-label first would
    // name this panel by the attribute that loses everywhere else, so an author
    // writing both would get a different name here than in a dialog.
    const authoredLabelledBy = host?.getAttribute('aria-labelledby');
    if (authoredLabelledBy) {
      content.setAttribute('aria-labelledby', authoredLabelledBy);
      return;
    }
    const authoredLabel = host?.getAttribute('aria-label');
    if (authoredLabel) {
      content.setAttribute('aria-label', authoredLabel);
      // This method re-runs on every open change, and the fallback below writes
      // aria-labelledby unconditionally. So a card named from its title on an
      // earlier pass still carries that reference, and it would outrank the
      // author's aria-label. Drop it, as dialog / alert-dialog do.
      content.removeAttribute('aria-labelledby');
      return;
    }
    // Already named by an earlier pass (this runs again on every open change).
    if (content.hasAttribute('aria-label') || content.hasAttribute('aria-labelledby')) return;
    const title = content.querySelector<HTMLElement>(
      '[data-slot="hover-card-title"], h1, h2, h3, h4, h5, h6',
    );
    content.setAttribute(
      'aria-labelledby',
      title
        ? ensureId(title, 'ui-hovercard-title')
        : ensureId(control, 'ui-hovercard-trigger'),
    );
  }

  // Back-compat getter.
  get isOpen(): boolean { return this.open; }

  show(): void {
    // A keyboard dismissal has to stick: _dismiss() moves focus to the trigger,
    // and that focusin lands right back here, which would reopen the card and
    // make Escape look broken. The guard is released once the transfer flushes.
    if (this._suppressReopen) return;
    clearTimeout(this._hideTimer);
    this._showTimer = window.setTimeout(() => { this.open = true; }, this.openDelay);
  }

  hide(): void {
    clearTimeout(this._showTimer);
    // Clear the PENDING hide before scheduling the next one. Overwriting the
    // handle alone orphans the old timer, which then fires on its own and
    // closes the card after a later show() thought it had cancelled the close.
    // Reachable whenever two leave paths fire without a show() between them,
    // and the focus linger below doubles how many of those paths exist.
    clearTimeout(this._hideTimer);
    this._hideTimer = window.setTimeout(() => {
      // The card KEEPS ITSELF OPEN while focus is inside it. That is what makes
      // in-card content Tab-reachable and what both doc surfaces promise, and a
      // mouseleave can schedule this close while a keyboard user still holds
      // focus on an in-card link. Closing then would pull the card out from
      // under them, so leave it open: the content's own focusout schedules the
      // close once focus has actually left, and that pass takes this branch.
      if (this._focusIsInContent()) return;
      this.open = false;
    }, this.closeDelay);
  }

  // Every close of this popover="manual" panel owes the same focus care, not
  // just Escape. The focus linger added here makes in-card content Tab-
  // reachable, so a user CAN be holding focus on a link inside the card when a
  // mouseleave-scheduled close fires; hiding the panel then drops focus to
  // <body>. Guarded, so a close while focus is elsewhere leaves it alone.
  //
  // The reopen suppression is what makes this terminate. Moving focus to the
  // trigger fires the trigger's own focusin, which calls show() and would
  // reopen the card the close just closed. It is released on the next
  // macrotask, once that synchronous focus transfer has been refused, so a
  // genuinely new hover or a fresh Tab back in still opens the card.
  _closeReleasingFocus(): void {
    this._suppressReopen = true;
    if (this._focusIsInContent()) this._control()?.focus();
    this.open = false;
    setTimeout(() => { this._suppressReopen = false; }, 0);
  }

  // Touch open: there is no hover delay and no mouseleave to close it, so open
  // immediately and arm a one-shot outside-tap dismiss (a tap anywhere outside
  // this card closes it). Deferred a tick so the opening tap itself does not
  // immediately dismiss it.
  openByTouch(): void {
    clearTimeout(this._showTimer);
    clearTimeout(this._hideTimer);
    this.open = true;
    const onOutside = (ev: Event): void => {
      // Close on an outside tap; also self-remove if the card was already
      // closed by other means (a re-tap toggle), so the listener never lingers.
      if (!this.open || !this.contains(ev.target as Node)) {
        // Same focus care as every other close path: the card may hold focus.
        this._closeReleasingFocus();
        document.removeEventListener('pointerdown', onOutside, true);
      }
    };
    setTimeout(() => document.addEventListener('pointerdown', onOutside, true), 0);
  }

  render() {
    return html`<div
      data-slot="hover-card"
      data-state=${this.open ? 'open' : 'closed'}
    ><slot></slot></div>`;
  }

  updated(changedProperties: Map<string, unknown>): void {
    if (!changedProperties.has('open')) return;
    if (changedProperties.get('open') === undefined) return;
    // Bind synchronously rather than in the microtask below, which bails on
    // engines with no Popover API: Escape has to work regardless of that.
    if (this.open) this._bindEscape();
    else this._unbindEscape();
    this.dispatchEvent(new CustomEvent('ui-open-change', { detail: { open: this.open }, bubbles: true }));
    // Wait one microtask for <ui-hover-card-content>'s inner [popover]
    // element to commit; we drive its showPopover() / hidePopover() and
    // refresh the trigger's aria-expanded.
    queueMicrotask(() => {
      this._wireAria();
      this._syncContent();
    });
  }

  _syncContent(): void {
    // Same nested-popover pattern as tooltip: <ui-hover-card-content>
    // renders an inner <div popover="manual">; the Popover API lives on
    // that inner div, not the host.
    const popover = this.querySelector<HTMLElement>('ui-hover-card-content [popover]');
    const host = this.querySelector<HTMLElement>('ui-hover-card-content');
    if (!popover || !popover.isConnected) return;
    const p = popover as HTMLElement & {
      showPopover?: () => void;
      hidePopover?: () => void;
      matches: (s: string) => boolean;
    };
    if (typeof p.showPopover !== 'function') return;
    if (this.open) {
      if (!p.matches(':popover-open')) p.showPopover();
      if (host) this._reposition(host, popover);
    } else if (p.matches(':popover-open')) {
      p.hidePopover();
    }
  }

  _reposition(contentHost: HTMLElement, popover: HTMLElement): void {
    const trigger = this.querySelector<HTMLElement>('ui-hover-card-trigger');
    if (!trigger) return;
    positionFloating(trigger, popover, {
      side: (contentHost.getAttribute('side') ?? 'bottom') as PopoverSide,
      align: (contentHost.getAttribute('align') ?? 'center') as PopoverAlign,
      sideOffset: Number(contentHost.getAttribute('side-offset') ?? 4),
      alignOffset: Number(contentHost.getAttribute('align-offset') ?? 0),
      radix: this.localName.slice(3),
    });
  }
}
UiHoverCard.register('ui-hover-card');

// --------------------------------------------------------------------------
// <ui-hover-card-trigger>
// --------------------------------------------------------------------------

export class UiHoverCardTrigger extends WebComponent {
  render() {
    return html`<div
      data-slot="hover-card-trigger"
      @mouseenter=${this._onEnter}
      @mouseleave=${this._onLeave}
      @focusin=${this._onEnter}
      @focusout=${this._onLeave}
      @click=${this._onClick}
    ><slot></slot></div>`;
  }

  // Hover/focus open + close are MOUSE affordances. On a no-hover (touch)
  // device, iOS Safari still fires SYNTHETIC mouseenter/mouseleave (and
  // focusin/focusout from the inner link) around a tap, which would otherwise
  // immediately re-close a tap-opened card. Gate the hover handlers to pointer
  // devices so on touch the card is driven only by the tap path (#745).
  _noHover = (): boolean => !!window.matchMedia?.('(hover: none)').matches;
  _onEnter = (): void => {
    if (this._noHover()) return;
    (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
  };
  _onLeave = (): void => {
    if (this._noHover()) return;
    (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
  };

  // Touch path. A touch device has no `mouseenter`, so a tap would fall through
  // to the inner `<a href>` and navigate. On a no-hover device the trigger tap
  // TOGGLES the card and NEVER navigates (the real link is reachable inside the
  // opened card). It must ALWAYS preventDefault, including while open: the
  // client router pushState()s on any bubble-phase `<a>` click that is not
  // defaultPrevented, so a re-tap that fell through would push a history entry
  // every time and Back would need N presses (#745).
  _onClick = (e: Event): void => {
    if (!window.matchMedia?.('(hover: none)').matches) return;
    const card = this.closest('ui-hover-card') as UiHoverCard | null;
    if (!card) return;
    e.preventDefault();
    e.stopPropagation();
    if (card.open) card.open = false;
    else card.openByTouch();
  };
}
UiHoverCardTrigger.register('ui-hover-card-trigger');

// --------------------------------------------------------------------------
// <ui-hover-card-content>
// The mouseenter/mouseleave handlers keep the card open while the cursor
// is over the content itself (so it does not close during a brief
// mouseleave on the trigger if the user is moving toward the card).
// focusin/focusout mirror that linger for the KEYBOARD: the trigger closes
// the card on its own focusout, so without these, Tabbing from the trigger
// toward the card scheduled the close before focus could land inside, and
// the interactive content the JSDoc example shows was unreachable.
// --------------------------------------------------------------------------

export class UiHoverCardContent extends WebComponent {
  _authored: string | null = null;

  // shadcn's className on HoverCardContent lands on the card panel (a `w-80`,
  // say), so the class written on this host moves there, read once at first
  // render.
  render() {
    this._authored = takeAuthoredClass(this, null);
    return html`<div
      data-slot="hover-card-content"
      role="dialog"
      popover="manual"
      class=${cn(hoverCardContentClass(), this._authored)}
      @mouseenter=${this._onEnter}
      @mouseleave=${this._onLeave}
      @focusin=${this._onEnter}
      @focusout=${this._onLeave}
    ><slot></slot></div>`;
  }

  // Hover/focus open + close are MOUSE affordances. On a no-hover (touch)
  // device, iOS Safari still fires SYNTHETIC mouseenter/mouseleave (and
  // focusin/focusout from the inner link) around a tap, which would otherwise
  // immediately re-close a tap-opened card. Gate the hover handlers to pointer
  // devices so on touch the card is driven only by the tap path (#745).
  _noHover = (): boolean => !!window.matchMedia?.('(hover: none)').matches;
  _onEnter = (): void => {
    if (this._noHover()) return;
    (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
  };
  _onLeave = (): void => {
    if (this._noHover()) return;
    (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
  };
}
UiHoverCardContent.register('ui-hover-card-content');
````

### Update the import paths to match your project setup.

## Usage

```ts
<ui-hover-card open-delay="10" close-delay="100">
  <ui-hover-card-trigger>
    <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${buttonClass({ variant: 'outline', size: 'sm' })}>
      ${percent}% context
    </button>
  </ui-hover-card-trigger>
  <ui-hover-card-content class="flex w-64 flex-col gap-3">
    <div class="flex items-center justify-between gap-3 text-sm">
      <span data-slot="hover-card-title" class="font-medium">Context</span>
      <span class="text-muted-foreground">${used} / ${limit}</span>
    </div>
    <progress data-slot="progress" value=${percent} max="100" aria-label="Context used" class=${progressClass()}></progress>
  </ui-hover-card-content>
</ui-hover-card>
```

The class on `<ui-hover-card-content>` lands on the card panel.

## AI SDK

Read usage from the metadata on the agent's message. In the `'use server'` action that streams the reply, `messageMetadata` runs when the stream finishes.

```ts title="modules/chat/actions/chat.server.ts"
'use server';
import { streamText } from 'ai';

export async function* chat(messages: ModelMessage[]) {
  const result = streamText({ model, messages });
  yield* result.toUIMessageStream({
    messageMetadata: ({ part }) => {
      if (part.type === 'finish') return { usage: part.totalUsage };
    },
  });
}
```

```ts
const usage = message.metadata?.usage;
const used = (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0);
const percent = Math.round((used / limit) * 100);
```

`limit` is the model's context window. The AI SDK does not send it, so set it from the model you use. See [AI SDK](https://webjs.dev/ui/docs/helpers/ai-sdk) for streaming the parts to a component.

## Migrating from AI SDK Elements

If you used Context from [AI SDK Elements](https://elements.ai-sdk.dev), its wrapper lives in `components/ai-elements/context.tsx`. In a WebJs app it becomes this pattern, built from WebJs UI components. Each export of the wrapper maps onto a part:

| AI SDK Elements | WebJs UI |
| --- | --- |
| `Context` | A `<ui-hover-card open-delay close-delay>`. Keep the used and max tokens, the usage and the model id in your component. |
| `ContextTrigger` | A `<ui-hover-card-trigger>` holding a button with `buttonClass({ variant: 'outline', size: 'sm' })`, showing the percent used. |
| `ContextContent` | A `<ui-hover-card-content>`. |
| `ContextContentHeader` | The used and max tokens, and a `<progress>` with `progressClass()` and `aria-label="Context used"`. |
| `ContextContentBody, ContextContentFooter and the usage parts` | Plain rows inside the card, as the demo's Input, Output and Reasoning rows. |
