@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/media-card/media-card.js

@@ -0,0 +1,273 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing, svg } from 'lit';
+import { property } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { expandIcon } from '../../internal/icons.js';
+import { safeLinkHref as validateLinkHref, safeMediaSrc as validateMediaSrc, } from '../../internal/safe-url.js';
+import { styles } from './media-card.styles.js';
+/** Validates `url` for an `<img>`/`<video>` source. Kept as a public wrapper
+ * so existing imports and generated API metadata remain stable. */
+export function safeMediaSrc(url) {
+    return validateMediaSrc(url);
+}
+/** Validates `url` for the library's download/open link sinks. Kept as a
+ * public wrapper so existing imports and generated API metadata remain stable. */
+export function safeLinkHref(url) {
+    return validateLinkHref(url);
+}
+function detectKind(mimeType) {
+    const mt = mimeType.trim().toLowerCase();
+    if (mt.startsWith('image/'))
+        return 'image';
+    if (mt.startsWith('video/'))
+        return 'video';
+    return 'file';
+}
+// Mirrors the shared icon set's viewBox/stroke conventions
+// (internal/icons.ts's chevronIcon()/closeIcon()/etc.), and is visually
+// identical to `<lyra-attachment-chip>`'s and `<lyra-document-preview>`'s
+// own local `fileGlyph()` -- duplicated rather than imported (these are
+// three independently consumable components, and icons.ts is off limits
+// here) but kept pixel-identical so a "generic file" affordance reads the
+// same wherever it shows up in the library.
+const ICON_VIEW_BOX = '0 0 24 24';
+const ICON_STROKE_WIDTH = '1.75';
+function fileGlyph() {
+    return svg `
+    <svg
+      width="1em"
+      height="1em"
+      viewBox=${ICON_VIEW_BOX}
+      fill="none"
+      stroke="currentColor"
+      stroke-width=${ICON_STROKE_WIDTH}
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    ><path d="M6 2h8l6 6v12a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2Z"></path><polyline points="14 2 14 8 20 8"></polyline></svg>
+  `;
+}
+/**
+ * `<lyra-media-card>` — a lightweight inline preview for one already-sent,
+ * already-available attachment inside a rendered chat message body (e.g.
+ * plugged into `<lyra-chat-message>`'s `attachments` slot, or embedded
+ * directly by a markdown/message renderer). Distinct from two other,
+ * similarly-named components in this family: `<lyra-document-preview>` is a
+ * fuller viewer with header chrome and an async server-side-conversion
+ * state machine (`status="converting"`), and `<lyra-attachment-chip>` is a
+ * pre-send queued-file chip with upload progress. This component has
+ * neither concern — it only ever shows a `src` that's already final.
+ *
+ * **Format dispatch.** `kind` selects `'image'` (a plain `<img>`), `'video'`
+ * (a plain `<video controls>`), or `'file'` (an icon + filename chip with a
+ * download/open affordance). Leave `kind` unset to auto-detect from
+ * `mime-type` (`image/*` / `video/*` / anything else -> `'file'`);
+ * explicitly setting `kind` always wins over detection.
+ *
+ * **Safe-URL checking.** `src` is validated before it's ever assigned to an
+ * `<img>`/`<video>` `src` or an `<a href>` — only `http:`/`https:`/`blob:`
+ * (plus `data:` for a *media* `src` only) or a scheme-relative/relative URL
+ * with no scheme at all pass; anything else (`javascript:`, `vbscript:`,
+ * and similarly suspicious schemes) is rejected. `safeMediaSrc()` and
+ * `safeLinkHref()` share a platform-URL-based validator; their sink-specific
+ * allowlists explain why `data:` gets two different answers depending on
+ * where it is used. An `image`/`video` `kind` whose `src` fails the
+ * media-src check falls back to the generic file-chip rendering — this is
+ * the "plain preview unavailable state" a dangerous URL degrades to, rather
+ * than ever reaching a real media/anchor sink. That fallback also re-checks
+ * `src` against the stricter href allowlist for its own download affordance,
+ * but since the href allowlist is a strict subset of the media-src allowlist,
+ * that re-check can only ever change the outcome for a direct/auto-detected
+ * `kind="file"` `src` — an `image`/`video` `src` that already failed the
+ * wider media-src check necessarily fails the narrower href check too, so
+ * the fallback for those two kinds is always the plain, unclickable `span`.
+ *
+ * **The `video` case renders its open affordance separately from `base`.**
+ * `image`/`file` wrap their *entire* card in one native `<button>`/`<a>` —
+ * safe because an `<img>` and a plain icon+text chip have no interactive
+ * content of their own to conflict with. A `<video controls>` element is
+ * itself interactive content (its own play/seek/volume controls), and HTML
+ * forbids nesting interactive content inside a `<button>`/`<a>` — doing so
+ * anyway would also make every click on the video's own controls bubble up
+ * and spuriously fire `lyra-open`. So for `kind="video"`, `base` is a plain,
+ * non-interactive wrapper around `[part="media"]`, and a small separate
+ * `[part="open-button"]` (not one of this component's originally-scoped
+ * parts, added as the "explicit view/open affordance" the class is free to
+ * provide) is the thing that actually fires `lyra-open`.
+ *
+ * **Navigation.** This component never navigates on its own for `image`/
+ * `video` — activating the card only fires `lyra-open`; a host decides what
+ * "open" means (a lightbox, a new tab, whatever). The `file`-chip case is
+ * the one exception: when `src` passes the (stricter) href safety check, the
+ * chip is a real `<a href download>` so a bare drop-in still does something
+ * useful — but `lyra-open` fires first and is `cancelable`; a host that
+ * calls `preventDefault()` on it suppresses that default download/open so it
+ * can substitute its own handling instead.
+ *
+ * @customElement lyra-media-card
+ * @event lyra-open - The card (or, for `kind="video"`, its `open-button`)
+ * was activated. `detail: { src, filename }`. Cancelable — see the class
+ * doc's "Navigation" section for what calling `preventDefault()` on it does
+ * in the `file`-chip case.
+ * @csspart base - The root interactive/container element. A `<button>` for
+ * `kind="image"`, a plain wrapper `<div>` for `kind="video"`, and either an
+ * `<a>` (when `src` passes the href safety check) or a plain `<span>`
+ * (otherwise) for the `file`-chip fallback.
+ * @csspart media - The `<img>` or `<video>` element.
+ * @csspart file-icon - The generic file glyph, shown only in the file-chip fallback.
+ * @csspart filename - The filename text, shown only in the file-chip fallback.
+ * @csspart open-button - The explicit "open" affordance rendered next to
+ * `[part="media"]` for `kind="video"` only — see the class doc.
+ */
+export class LyraMediaCard extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** The media URL. Always re-validated against a safe-scheme allowlist
+         *  before use — see the class doc. */
+        this.src = '';
+        /** Drives auto-detection when `kind` is unset. */
+        this.mimeType = '';
+        /** Shown in the file-chip fallback, used as the download link's suggested
+         *  filename, and folded into the accessible name of the whole card. */
+        this.filename = '';
+        /** Alt text for the image case (and reused as a video label fallback).
+         *  Falls back to `filename`, then a generic per-kind description. */
+        this.alt = '';
+        /** A CSS length (e.g. `"16rem"`); once set, overrides the
+         *  `--lyra-media-card-max-height` custom property for this instance only —
+         *  same contract as `<lyra-document-preview>`'s identically-named prop. */
+        this.maxHeight = '';
+        this.onActivate = () => {
+            this.emitOpen();
+        };
+        // The file-chip's `<a>` provides a real default action (download/open the
+        // resource) so a bare drop-in works with no host wiring, but `lyra-open`
+        // fires first and is cancelable -- a host that preventDefault()s it is
+        // suppressing exactly that default, so the native click also needs
+        // stopping or the download/navigation would proceed anyway.
+        this.onLinkClick = (e) => {
+            if (this.emitOpen().defaultPrevented)
+                e.preventDefault();
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    /** Effective kind used for rendering — `kind` if explicitly set,
+     *  otherwise detected from `mime-type`. */
+    get resolvedKind() {
+        return this.kind ?? detectKind(this.mimeType);
+    }
+    get displayFilename() {
+        return this.filename || 'Untitled file';
+    }
+    /** Accessible name for the card's own actionable element (`base` or, for
+     *  video, `open-button`) — always phrased as the action it performs. */
+    get accessibleLabel() {
+        const name = this.filename || this.alt;
+        return name ? `Open ${name}` : `Open ${this.resolvedKind} attachment`;
+    }
+    get imgAlt() {
+        return this.alt || this.filename || 'Image attachment';
+    }
+    get videoLabel() {
+        return this.alt || this.filename || 'Video attachment';
+    }
+    /** Per-instance override for `--lyra-media-card-max-height`, applied
+     *  inline on `[part="base"]` -- the only mechanism that reliably wins
+     *  over the `:host{}`-declared default from outside the shadow root. */
+    get baseStyle() {
+        return this.maxHeight ? `--lyra-media-card-max-height:${this.maxHeight}` : nothing;
+    }
+    emitOpen() {
+        // Matches whichever safe-URL sink actually rendered (see the class doc):
+        // falls back to a trimmed raw src so a whitespace-padded, otherwise-unsafe
+        // src still reports the same value the DOM would show if it were safe.
+        const src = safeMediaSrc(this.src) ?? safeLinkHref(this.src) ?? this.src.trim();
+        return this.emit('lyra-open', { src, filename: this.filename });
+    }
+    renderImage(src) {
+        return html `
+      <button part="base" type="button" style=${this.baseStyle} aria-label=${this.accessibleLabel} @click=${this.onActivate}>
+        <img part="media" src=${src} alt=${this.imgAlt} />
+      </button>
+    `;
+    }
+    renderVideo(src) {
+        return html `
+      <div part="base" style=${this.baseStyle}>
+        <video part="media" controls src=${src} aria-label=${this.videoLabel}></video>
+        <button part="open-button" type="button" aria-label=${this.accessibleLabel} @click=${this.onActivate}>
+          ${expandIcon()}
+        </button>
+      </div>
+    `;
+    }
+    renderFileFallback() {
+        const href = safeLinkHref(this.src);
+        const name = this.displayFilename;
+        const content = html `
+      <span part="file-icon" aria-hidden="true">${fileGlyph()}</span>
+      <span part="filename" title=${name}>${name}</span>
+    `;
+        if (href) {
+            return html `
+        <a
+          part="base"
+          href=${href}
+          style=${this.baseStyle}
+          download=${this.filename || ''}
+          aria-label=${this.accessibleLabel}
+          @click=${this.onLinkClick}
+        >
+          ${content}
+        </a>
+      `;
+        }
+        // No safe link target -- the "plain preview unavailable state" the class
+        // doc describes: the filename/icon still display, but nothing is
+        // clickable (there's nothing safe to point a download/open affordance
+        // at, and no built-in lightbox to fall back to for this kind).
+        return html `<span part="base" style=${this.baseStyle}>${content}</span>`;
+    }
+    render() {
+        const kind = this.resolvedKind;
+        if (kind === 'image') {
+            const src = safeMediaSrc(this.src);
+            if (src)
+                return this.renderImage(src);
+            return this.renderFileFallback();
+        }
+        if (kind === 'video') {
+            const src = safeMediaSrc(this.src);
+            if (src)
+                return this.renderVideo(src);
+            return this.renderFileFallback();
+        }
+        return this.renderFileFallback();
+    }
+}
+__decorate([
+    property()
+], LyraMediaCard.prototype, "src", void 0);
+__decorate([
+    property({ reflect: true })
+], LyraMediaCard.prototype, "kind", void 0);
+__decorate([
+    property({ attribute: 'mime-type' })
+], LyraMediaCard.prototype, "mimeType", void 0);
+__decorate([
+    property()
+], LyraMediaCard.prototype, "filename", void 0);
+__decorate([
+    property()
+], LyraMediaCard.prototype, "alt", void 0);
+__decorate([
+    property({ attribute: 'max-height' })
+], LyraMediaCard.prototype, "maxHeight", void 0);
+defineElement('media-card', LyraMediaCard);

package/dist/components/media-card/media-card.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/media-card/media-card.styles.js

@@ -0,0 +1,132 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: inline-block;
+    max-inline-size: 100%;
+    /* Consumer-tunable cap so one oversized image/video can't blow out a
+       chat bubble -- same naming/contract as lyra-document-preview's
+       identical --lyra-document-preview-max-height. Width already caps at
+       100% of whatever the host message body allows. */
+    --lyra-media-card-max-height: 20rem;
+  }
+
+  /* -- base: shared chrome for every kind's root element (button/div/a/span) */
+  [part='base'] {
+    display: block;
+    box-sizing: border-box;
+    max-inline-size: 100%;
+    border: 1px solid var(--lyra-color-border);
+    border-radius: var(--lyra-radius);
+    background: var(--lyra-color-surface);
+    overflow: hidden;
+    font: inherit;
+    color: var(--lyra-color-text);
+    text-decoration: none;
+  }
+  /* Reset native button/anchor chrome only where "base" is actually one of
+     those (image and file-with-a-safe-link cases) -- a plain div/span never
+     had any to begin with, so this is harmless there too. */
+  button[part='base'],
+  a[part='base'] {
+    cursor: pointer;
+    padding: 0;
+    -webkit-tap-highlight-color: transparent;
+    transition:
+      border-color var(--lyra-transition-fast),
+      background-color var(--lyra-transition-fast);
+  }
+  button[part='base']:hover,
+  a[part='base']:hover {
+    border-color: var(--lyra-color-brand);
+  }
+  [part='base']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+
+  /* -- image / video media ------------------------------------------- */
+  img[part='media'] {
+    display: block;
+    max-inline-size: 100%;
+    max-block-size: var(--lyra-media-card-max-height);
+    object-fit: contain;
+  }
+  video[part='media'] {
+    display: block;
+    max-inline-size: 100%;
+    max-block-size: var(--lyra-media-card-max-height);
+  }
+
+  /* -- video: base is a plain non-interactive wrapper around the video
+     plus its own separate open-button -- see the class doc for why video
+     doesn't reuse the whole-card-button pattern image/file use. */
+  div[part='base'] {
+    position: relative;
+    display: inline-block;
+  }
+  [part='open-button'] {
+    position: absolute;
+    inset-block-start: var(--lyra-space-s);
+    inset-inline-end: var(--lyra-space-s);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-inline-size: min(var(--lyra-icon-button-size), 2rem);
+    min-block-size: min(var(--lyra-icon-button-size), 2rem);
+    padding: 0;
+    border: none;
+    border-radius: var(--lyra-radius);
+    background: color-mix(in srgb, var(--lyra-color-surface) 78%, transparent);
+    color: var(--lyra-color-text);
+    cursor: pointer;
+    -webkit-tap-highlight-color: transparent;
+    transition: background-color var(--lyra-transition-fast);
+  }
+  [part='open-button']:hover {
+    background: var(--lyra-color-surface);
+  }
+  [part='open-button']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+  [part='open-button'] svg {
+    display: block;
+  }
+
+  /* -- file-chip fallback (kind="file", or an image/video src that failed
+     the safe-URL check) ------------------------------------------------ */
+  span[part='base'],
+  a[part='base'] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--lyra-space-s);
+    padding: var(--lyra-space-xs) var(--lyra-space-s);
+  }
+  [part='file-icon'] {
+    display: inline-flex;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: center;
+    font-size: 1.25rem;
+    color: var(--lyra-color-text-quiet);
+  }
+  [part='file-icon'] svg {
+    display: block;
+  }
+  [part='filename'] {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-weight: 600;
+    font-size: 0.8125rem;
+    color: var(--lyra-color-text);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    button[part='base'],
+    a[part='base'],
+    [part='open-button'] {
+      transition: none !important;
+    }
+  }
+`;

package/dist/components/mention-popover/mention-popover.d.ts

@@ -0,0 +1,203 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+/** One candidate row — an `@`-mentionable person/entity, or a `/`-command. */
+export interface MentionItem {
+    id: string;
+    label: string;
+    description?: string;
+    /** Literal icon hint (e.g. an emoji), rendered next to `label` -- same
+     *  "opaque string, not a registry lookup" convention as
+     *  `<lyra-tool-call-chip>`'s/`<lyra-tool-select-dialog>`'s own `icon`. */
+    icon?: string;
+}
+/** Predicate deciding whether `item` matches a (already-trimmed, already-lowercased) `query`.
+ *  Mirrors `<lyra-combobox>`'s `OptionFilter` convention -- override `filter` to replace the
+ *  built-in case-insensitive label/description substring match entirely. */
+export type MentionFilter = (item: MentionItem, query: string) => boolean;
+export interface MentionSelectDetail {
+    id: string;
+    label: string;
+}
+/**
+ * `<lyra-mention-popover>` — a caret-anchored, keyboard-navigable popover for
+ * `@`-mention and `/`-slash-command autocomplete inside a plain-text
+ * `<textarea>`/`<input>` the host owns (e.g. `<lyra-chat-composer>`'s own
+ * textarea, though this component has no dependency on that or any other
+ * specific input). It never takes DOM focus itself — the same "focus stays
+ * put, `aria-activedescendant` conveys the active row" pattern
+ * `<lyra-select>`/`<lyra-combobox>` use for their own listbox — so a host
+ * must apply `aria-activedescendant` to its *own* input element, pointing at
+ * whatever `activeDescendantId` currently returns.
+ *
+ * Integration contract (entirely the host's responsibility — this component
+ * never inspects the text control's value or listens to it directly):
+ * 1. Detect a mention/command trigger (e.g. `@`/`/` at the start of a word)
+ *    in the host's own `input` handling.
+ * 2. Set `anchor` (the `<textarea>`/`<input>` itself, or any element for
+ *    plain whole-element anchoring — see "Positioning" below), `items`, and
+ *    `query` (the text typed since the trigger character), then flip
+ *    `open = true`.
+ * 3. Forward every `keydown` the input receives, while `open`, through
+ *    `handleKeyDown()` — it returns `true` when it consumed the key (so the
+ *    host's own handler should stop, e.g. skip submitting the message on an
+ *    Enter that actually picked a mention) and `false` otherwise.
+ * 4. Set `open = false` whenever the query stops looking like an active
+ *    mention context (a space typed, the trigger character deleted, the
+ *    input blurred, …) — `lyra-mention-close` fires automatically from that
+ *    (see below), there is no separate "tell it to close" call needed.
+ * 5. Keep the host's own input's `aria-activedescendant` (and, optionally,
+ *    `aria-controls`, via `listboxId`) in sync with `activeDescendantId` —
+ *    this component has no DOM of the host's to attach that to itself.
+ *
+ * Positioning: when `anchor` is a plain `<textarea>` or single-line text
+ * `<input>`, this component measures exactly where the caret currently
+ * paints (`caretClientRect()`, the standard hidden-mirror-element technique
+ * — see that function's own doc) and positions against that single point
+ * with `internal/positioner.js`'s `place()`, so the popup tracks the caret
+ * rather than sitting under the whole textarea. Any other `anchor` element
+ * (or a text control this component fails to measure, e.g. one with
+ * `display: none`) falls back to `place(anchor, popup)` against the whole
+ * element — the same whole-element anchoring `<lyra-combobox>`/
+ * `<lyra-select>` use for their own popups. Re-measures on every `anchor`/
+ * `query` change while open (a keystroke moves the caret, so a fresh `query`
+ * is the proxy for "the caret may have moved"); a caret that moves for a
+ * reason other than typing (e.g. a mouse click elsewhere in the text while
+ * the popover happens to still be open) is not separately tracked — the
+ * host can force a re-measure by toggling `open` or reassigning `anchor`.
+ *
+ * Filtering happens internally against `items` (mirroring `<lyra-combobox>`'s
+ * filter-predicate convention via `filter`, rather than requiring the host to
+ * pre-filter): the default predicate is a case-insensitive substring match
+ * against `label`/`description`, overridable via `filter`.
+ *
+ * There is no persisted "selection" the way a real listbox has one — a
+ * mention is either committed (closing the popover) or the popover is
+ * dismissed with nothing chosen — so `aria-selected="true"` marks whichever
+ * row is currently *active* (what Enter/Tab would commit right now), per the
+ * WAI-ARIA combobox-with-list-autocomplete pattern, rather than tracking a
+ * separate persisted value the way `<lyra-combobox>`'s own `aria-selected`
+ * does.
+ *
+ * @example
+ * ```html
+ * <textarea id="composer"></textarea>
+ * <lyra-mention-popover id="mentions"></lyra-mention-popover>
+ * <script>
+ *   const textarea = document.getElementById('composer');
+ *   const popover = document.getElementById('mentions');
+ *
+ *   textarea.addEventListener('keydown', (e) => {
+ *     if (popover.open && popover.handleKeyDown(e)) return; // consumed
+ *     // ...the host's own Enter-to-send handling, etc.
+ *   });
+ *   textarea.addEventListener('input', () => {
+ *     // host's own '@'/'/' + query detection, then:
+ *     popover.anchor = textarea;
+ *     popover.items = candidates;
+ *     popover.query = detectedQuery;
+ *     popover.open = detectedQuery !== null;
+ *   });
+ *   textarea.addEventListener('blur', () => (popover.open = false));
+ *
+ *   popover.addEventListener('lyra-mention-select', (e) => {
+ *     // splice `${e.detail.label}` into the textarea at the trigger offset
+ *   });
+ *   popover.addEventListener('lyra-mention-close', () => {
+ *     textarea.removeAttribute('aria-activedescendant');
+ *   });
+ *
+ *   // Whenever the popover re-renders its active row (e.g. after every
+ *   // ArrowUp/ArrowDown handleKeyDown() call above), sync the host's own
+ *   // input so assistive tech announces the current candidate:
+ *   const syncActiveDescendant = () => {
+ *     if (popover.open && popover.activeDescendantId) {
+ *       textarea.setAttribute('aria-activedescendant', popover.activeDescendantId);
+ *     } else {
+ *       textarea.removeAttribute('aria-activedescendant');
+ *     }
+ *   };
+ * </script>
+ * ```
+ *
+ * @customElement lyra-mention-popover
+ * @event lyra-mention-select - An item was committed (Enter/Tab/click). `detail: { id, label }`.
+ * @event lyra-mention-close - The popover was dismissed with no selection — Escape, or `open`
+ * transitioning to `false` by any other means (a direct host assignment included). Never fires
+ * for a close that followed a `lyra-mention-select` commit.
+ * @csspart listbox - The popover's root element (`role="listbox"`).
+ * @csspart option - A candidate row (`role="option"`).
+ * @csspart option-icon - A row's leading icon glyph, when `icon` is set.
+ * @csspart option-label - Wrapper around a row's label/description.
+ * @csspart option-description - A row's optional secondary line, when `description` is set.
+ * @csspart empty - The "no matches" message, shown when `items`/`query` produce zero rows.
+ */
+export declare class LyraMentionPopover extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** The element to position the popup relative to. When this is a plain
+     *  `<textarea>`/single-line text `<input>`, positioning is caret-precise
+     *  (see the class doc); any other element anchors the whole popup under
+     *  that element's own box, the same as `<lyra-combobox>`'s trigger. */
+    anchor?: HTMLElement;
+    /** The full candidate set, pre-`query`-filtering. */
+    items: MentionItem[];
+    /** The text typed since the trigger character (`@`/`/`/…) — drives the
+     *  built-in internal filtering (see `filter` to override it). */
+    query: string;
+    /** Whether the popover is shown. */
+    open: boolean;
+    /** Overrides the built-in case-insensitive label/description substring match. */
+    filter: MentionFilter | null;
+    /** Message shown when `items` (post-`query`-filtering) is empty. */
+    emptyText: string;
+    /** Accessible name for the `role="listbox"` popup. */
+    label: string;
+    private activeIndex;
+    private readonly _listboxId;
+    private cleanup?;
+    private virtualAnchor;
+    private _isFirstUpdate;
+    private _suppressCloseEvent;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    disconnectedCallback(): void;
+    /** The current candidate set: `items` filtered by `query` via `filter`
+     *  (or the built-in default). Empty `query` returns `items` unfiltered. */
+    get filteredItems(): MentionItem[];
+    /** The `id` of the currently-highlighted row for the host to apply as its
+     *  own input's `aria-activedescendant` — `null` while closed or when
+     *  `filteredItems` is empty (nothing to point at). See the class doc's
+     *  `@example` for the full wiring. */
+    get activeDescendantId(): string | null;
+    /** The `id` of the `role="listbox"` popup, for a host that also wants to
+     *  wire `aria-controls` on its own input (screen-reader support for
+     *  `aria-controls` is inconsistent, so `activeDescendantId` remains the
+     *  load-bearing piece; this is a supplementary nicety). */
+    get listboxId(): string;
+    /**
+     * The host's own text-control keydown handler calls this while the
+     * popover is open. Returns `true` when the key was intercepted
+     * (`preventDefault()` already called) and the host should not also act on
+     * it; `false` when the host's normal handling should proceed untouched --
+     * including ArrowDown/ArrowUp/Enter/Tab when there are zero filtered rows
+     * to act on, so e.g. the host's own textarea still moves its caret a line
+     * normally rather than having the keystroke silently eaten.
+     */
+    handleKeyDown(e: KeyboardEvent): boolean;
+    private clampedIndex;
+    private rowId;
+    private commit;
+    private reposition;
+    /** Resolves what to actually hand `place()` -- a caret-precise virtual
+     *  point for a measurable text control, `anchor` itself otherwise. See the
+     *  class doc's "Positioning" section. */
+    private resolveAnchorElement;
+    private onListboxMouseDown;
+    private onListboxClick;
+    private renderRow;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-mention-popover': LyraMentionPopover;
+    }
+}