@aceshooting/lyra-ui 2.1.0 → 2.3.0

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

@@ -1,203 +1,2 @@
-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;
-    }
-}
+export * from './mention-popover.class.js';
+//# sourceMappingURL=mention-popover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mention-popover.d.ts","sourceRoot":"","sources":["../../../src/components/mention-popover/mention-popover.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC"}