@skdx/web-components 0.28.0 → 0.30.0

package/dist/mentions/Mentions.d.cts

@@ -0,0 +1,318 @@
+import { LitElement, type TemplateResult } from 'lit';
+import { type CaretRect, type MentionToken } from '../internal/mentions.cjs';
+import type { SkdxMentionsInput } from './MentionsInput.cjs';
+/** @internal Selector for an entry that is still an option and still live. */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
+/** Default `getResultCountLabel`: `"1 result available"` / `"3 results available"`. */
+export declare function defaultGetResultCountLabel(count: number): string;
+/** One mentionable entry as data, for the `options` property. */
+export interface SkdxMentionsOptionData {
+    /** Identifier carried on the value-change detail when this entry is inserted. */
+    value: string;
+    /** Text rendered for the entry, falling back to its value. */
+    label?: string;
+    /** Trigger character this entry belongs to, defaulting to the first configured one. */
+    trigger?: string;
+    /** Excludes this entry from insertion and from every highlight. */
+    disabled?: boolean;
+}
+/** Narrows Items against the active query, or `'manual'` to leave filtering to the consumer. */
+export type SkdxMentionsFilter = 'manual' | ((itemText: string, query: string) => boolean | number);
+/** Builds the text that replaces the typed token when an entry is chosen. */
+export type SkdxMentionsSerializer = (item: {
+    /** The chosen Item's `value`. */
+    value: string;
+    /** The chosen Item's `text-value`, or its rendered text. */
+    textValue: string;
+    /** The trigger character of the token being replaced. */
+    trigger: string;
+}) => string;
+/** Default `serialize`: the trigger character followed by the entry's text. */
+export declare const defaultMentionSerializer: SkdxMentionsSerializer;
+/** The mention an insertion wrote, and the range of text it replaced. */
+export interface SkdxMentionsInsertedMention {
+    /** Trigger character of the token that was replaced. */
+    trigger: string;
+    /** The inserted Item's `value`. */
+    value: string;
+    /** The text `serialize` produced and the field now contains. */
+    text: string;
+    /** Offset of the replaced token's trigger character. */
+    start: number;
+    /** Offset just past the replaced token's query. */
+    end: number;
+}
+/** The `detail` a `value-change` CustomEvent carries; `mention` is null for an ordinary keystroke. */
+export interface SkdxMentionsValueChangeDetail {
+    /** The field's whole text after the change. */
+    value: string;
+    /** The text held before this change, or `null` when there was none. */
+    previousValue: string | null;
+    /** What drove the change. */
+    reason: 'keyboard' | 'pointer' | 'programmatic';
+    /** The entry just inserted and the range it replaced, or `null`. */
+    mention: SkdxMentionsInsertedMention | null;
+}
+/** The `detail` a `query-change` CustomEvent carries, or `null` once no mention is being typed. */
+export type SkdxMentionsQueryChangeDetail = MentionToken;
+/** Why virtual focus moved: a key, a pointer, or an internal re-seed. */
+export type SkdxMentionsHighlightReason = 'keyboard' | 'pointer' | 'auto';
+/** The `detail` a `highlight-change` CustomEvent carries, naming values rather than element ids. */
+export interface SkdxMentionsHighlightChangeDetail {
+    /** The highlighted entry's value, or `null` when nothing is highlighted. */
+    value: string | null;
+    /** The value the highlight held before this move, or `null`. */
+    previousValue: string | null;
+    /** What moved the highlight. */
+    reason: SkdxMentionsHighlightReason;
+}
+/** What an `<skdx-mentions-item>` registers about itself, so a key can insert it by id. */
+export interface SkdxMentionsItemEntry {
+    /** The value reported on the value-change detail when this entry is inserted. */
+    value: string;
+    /** The entry's `text-value`, or its rendered text — matched by `filter`, written by `serialize`. */
+    text: string;
+    /** The trigger character this entry belongs to. */
+    trigger: string;
+}
+declare const SkdxMentions_base: typeof LitElement & (new (...args: any[]) => import("../index.cjs").SkdxFormAssociated) & {
+    formAssociated: boolean;
+};
+/**
+ * `<skdx-mentions>` is a multi-line field whose trigger characters open a caret-anchored listbox over one token, leaving the rest of the text and the caret alone.
+ *
+ * @example
+ * ```html
+ * <skdx-mentions aria-label="Message">
+ *   <skdx-mentions-input placeholder="Say something…"></skdx-mentions-input>
+ *   <skdx-mentions-content>
+ *     <skdx-mentions-item value="alice">Alice</skdx-mentions-item>
+ *     <skdx-mentions-empty>No matches</skdx-mentions-empty>
+ *   </skdx-mentions-content>
+ * </skdx-mentions>
+ * ```
+ *
+ * @fires value-change - Fires with `{ value, previousValue, reason, mention }` whenever the field's text changes. `value` is the whole text, never the mention alone; `mention` names the entry just inserted and the range it replaced, and is `null` for an ordinary keystroke.
+ * @fires query-change - Fires with `{ trigger, query, start, end }` whenever the token under the caret changes, and with `null` once no mention is being typed. This is the hook an async collection is loaded from.
+ * @fires open-change - Fires with the new open state (boolean) whenever the popup opens or closes.
+ * @fires highlight-change - Fires with `{ value, previousValue, reason }` whenever virtual focus moves.
+ * @fires open-change-complete - Fires with the new open state after `<skdx-mentions-content>`'s enter or exit animation has finished. Not cancelable: the change has already happened.
+ *
+ * @slot option - Per-entry content for the derived anatomy, addressed by `data-value` — this package's form of the `renderOption` hook the other ports take as a function.
+ */
+export declare class SkdxMentions extends SkdxMentions_base {
+    static styles: import("lit").CSSResult;
+    /**
+     * The field's whole text, for controlled usage; pair it with `value-change`.
+     * @default '' — an empty field.
+     */
+    value: string;
+    /**
+     * Initial text of the field, and the text a form reset restores.
+     * @default '' — the field starts empty.
+     */
+    defaultValue: string;
+    /**
+     * Characters that open a mention when typed at a word boundary, read one character at a time from a string.
+     * @default '@' — a single people-mention trigger.
+     */
+    triggers: string | readonly string[];
+    /**
+     * The mentionable collection as data, rendered as one Item per entry.
+     * @default undefined — author the Item children by hand.
+     */
+    options?: readonly SkdxMentionsOptionData[];
+    /**
+     * How Items are narrowed against the active query, the substring between the trigger and the caret.
+     * @default 'manual' — the consumer renders only matching Items.
+     */
+    filter: SkdxMentionsFilter;
+    /**
+     * Builds the text that replaces the typed token when an entry is chosen.
+     * @default (item) => `${item.trigger}${item.textValue}` — the trigger followed by the entry's text.
+     */
+    serialize: SkdxMentionsSerializer;
+    /**
+     * Whether a single space follows an inserted mention so typing continues cleanly.
+     * @default true — skipped where the text already carries on with whitespace.
+     */
+    appendSpace: boolean;
+    /**
+     * How many spaces a query may contain before the mention is abandoned.
+     * @default 0 — the first space ends the mention.
+     */
+    allowedSpaces: number;
+    /**
+     * Whether a trigger only opens a mention at the start of the value or after a non-word character.
+     * @default true — which is what keeps `user@example.com` silent.
+     */
+    requireWordBoundary: boolean;
+    /**
+     * Whether the suggestion popup is open; pair it with `open-change`.
+     * @default false — the popup opens when a trigger is typed.
+     */
+    open: boolean;
+    /**
+     * Initial open state, applied once on connect if `open` was not authored.
+     * @default false
+     */
+    defaultOpen: boolean;
+    /**
+     * Keeps the first entry highlighted whenever the filtered list changes while open.
+     * @default true — the opposite of Combobox, so Enter always has a target.
+     */
+    autoHighlight: boolean;
+    /**
+     * Wraps arrow navigation around the ends of the entry list.
+     * @default true — set false to clamp at the ends.
+     */
+    loop: boolean;
+    /**
+     * Marks entries as in flight and suppresses the result-count announcement.
+     * @default false
+     */
+    loading: boolean;
+    /**
+     * Grows the field to fit its content instead of showing a scrollbar.
+     * @default false
+     */
+    autoResize: boolean;
+    /**
+     * The field's opening size, and the floor auto-resize will not shrink below.
+     * @default 2 — the platform's own `rows` default.
+     */
+    minRows: number;
+    /**
+     * Caps auto-resize growth to this many rows, based on computed line-height.
+     * @default undefined — the field grows without a limit.
+     */
+    maxRows?: number;
+    /**
+     * Disables the field so no mention can ever open, and blocks every edit.
+     * @default false
+     */
+    disabled: boolean;
+    /**
+     * Makes the field read-only, suspending trigger detection but keeping it focusable.
+     * @default false
+     */
+    readOnly: boolean;
+    /**
+     * Marks the field as invalid, exposed as `aria-invalid` and `data-invalid`.
+     * @default false
+     */
+    invalid: boolean;
+    /**
+     * Name used as the `FormData` entry key; submits the field's whole text.
+     * @default undefined — the field submits nothing at all.
+     */
+    name?: string;
+    /**
+     * Id of the `<form>` this field submits into, so it can live outside that subtree.
+     * @default undefined — submits into the nearest ancestor form.
+     */
+    formId?: string;
+    /**
+     * Marks the field required for native constraint validation while its text is empty.
+     * @default false
+     */
+    required: boolean;
+    /**
+     * Formats the count announced whenever the rendered entry count changes while open.
+     * @default defaultGetResultCountLabel — e.g. `"3 results available"`
+     */
+    getResultCountLabel: (count: number) => string;
+    /**
+     * Placeholder text forwarded to the derived Input, ignored under manual composition.
+     * @default undefined — no placeholder is derived.
+     */
+    placeholder?: string | undefined;
+    /** Id for `<skdx-mentions-content>` and the Input's `aria-controls`. */
+    contentId: string;
+    /** Id of the virtually-focused entry, or `null` when nothing is highlighted. */
+    activeId: string | null;
+    /** @internal The `<skdx-mentions-input>` descendant that owns the textarea. */
+    inputHost: SkdxMentionsInput | null;
+    /** @internal The mounted `<skdx-mentions-content>`, registered so Input knows something else owns Escape. */
+    contentEl: HTMLElement | null;
+    /** @internal The token last derived from the text and the caret, or `null`. */
+    token: MentionToken | null;
+    private dismissedAt;
+    /** Moves keyboard focus to the text field, which is where this component keeps real DOM focus. */
+    focus(options?: FocusOptions): void;
+    /** The configured trigger characters, one per entry. @internal */
+    get triggerList(): readonly string[];
+    /** The trigger an Item with no `trigger` of its own belongs to. @internal */
+    get defaultTrigger(): string;
+    private changes;
+    /** @internal Sets `value` and dispatches `value-change`; a no-op if unchanged. */
+    setValue(next: string, reason?: SkdxMentionsValueChangeDetail['reason'], mention?: SkdxMentionsInsertedMention | null): void;
+    /** @internal Sets `open` and dispatches `open-change`; clears the highlight on close. */
+    setOpen(open: boolean): void;
+    /** @internal Sets the active token and dispatches `query-change`; a no-op if unchanged. */
+    setToken(token: MentionToken | null): void;
+    /**
+     * Re-derives the token, the dismissal and the open state from the text and
+     * the caret together — the whole detection state, with nothing carried over.
+     *
+     * Detection is suspended, not merely closed, while `disabled` or `readOnly`:
+     * no token is derived, so no `query-change` fires and no `data-trigger` lands.
+     * @internal
+     */
+    refreshToken(value: string, caret: number): void;
+    /** @internal Closes the popup on Escape, leaving the text and the caret untouched. */
+    dismiss(): void;
+    /** @internal Whether item text survives the current filter and the active query. */
+    matchesFilter(itemText: string): boolean;
+    /**
+     * Whether an Item is an option for the active token at all: an entry
+     * addressing another trigger is excluded exactly as a filter rejection is.
+     * @internal
+     */
+    matchesToken(itemTrigger: string, itemText: string): boolean;
+    /** @internal Visible entries, ranked by a numeric filter predicate via inline CSS `order`. */
+    visibleOptions(): HTMLElement[];
+    /** @internal The caret rectangle the popup is anchored to, measured fresh. */
+    measureCaret(): CaretRect;
+    /**
+     * Replaces the active token with the serialized entry, moves the caret past
+     * it and closes; reports whether there was anything to insert.
+     * @internal
+     */
+    insertItem(id: string, reason: SkdxMentionsValueChangeDetail['reason']): boolean;
+    /** @internal Sets the virtually-focused entry id, reporting the move by value. */
+    setActiveId(id: string | null, reason?: SkdxMentionsHighlightReason): void;
+    private previousHighlight;
+    private readonly itemRegistry;
+    /** @internal Called by rendered entries so a key can insert one by id. */
+    registerItem(id: string, entry: SkdxMentionsItemEntry): void;
+    /** @internal Called when an entry unmounts or stops being an option. */
+    unregisterItem(id: string): void;
+    /** @internal The registered entry for an id, or `undefined` if no longer rendered. */
+    getItem(id: string): SkdxMentionsItemEntry | undefined;
+    private reseedFrame?;
+    private scheduleReseed;
+    private notify;
+    private readonly itemObserver;
+    private announceResultCount;
+    private maybeAutoHighlight;
+    private seeded;
+    private _anatomyOptionsRef?;
+    connectedCallback(): void;
+    private observeOptions;
+    private readonly fillAnatomy;
+    disconnectedCallback(): void;
+    private hasUpdatedOnce;
+    private teardownOpenChangeComplete?;
+    protected updated(changed: Map<string, unknown>): void;
+    private syncFormState;
+    /** Restores the live `defaultValue` and closes any open popup; fires no change event. */
+    formResetCallback(): void;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-mentions': SkdxMentions;
+    }
+}
+export {};

package/dist/mentions/Mentions.d.ts

@@ -0,0 +1,318 @@
+import { LitElement, type TemplateResult } from 'lit';
+import { type CaretRect, type MentionToken } from '../internal/mentions.js';
+import type { SkdxMentionsInput } from './MentionsInput.js';
+/** @internal Selector for an entry that is still an option and still live. */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
+/** Default `getResultCountLabel`: `"1 result available"` / `"3 results available"`. */
+export declare function defaultGetResultCountLabel(count: number): string;
+/** One mentionable entry as data, for the `options` property. */
+export interface SkdxMentionsOptionData {
+    /** Identifier carried on the value-change detail when this entry is inserted. */
+    value: string;
+    /** Text rendered for the entry, falling back to its value. */
+    label?: string;
+    /** Trigger character this entry belongs to, defaulting to the first configured one. */
+    trigger?: string;
+    /** Excludes this entry from insertion and from every highlight. */
+    disabled?: boolean;
+}
+/** Narrows Items against the active query, or `'manual'` to leave filtering to the consumer. */
+export type SkdxMentionsFilter = 'manual' | ((itemText: string, query: string) => boolean | number);
+/** Builds the text that replaces the typed token when an entry is chosen. */
+export type SkdxMentionsSerializer = (item: {
+    /** The chosen Item's `value`. */
+    value: string;
+    /** The chosen Item's `text-value`, or its rendered text. */
+    textValue: string;
+    /** The trigger character of the token being replaced. */
+    trigger: string;
+}) => string;
+/** Default `serialize`: the trigger character followed by the entry's text. */
+export declare const defaultMentionSerializer: SkdxMentionsSerializer;
+/** The mention an insertion wrote, and the range of text it replaced. */
+export interface SkdxMentionsInsertedMention {
+    /** Trigger character of the token that was replaced. */
+    trigger: string;
+    /** The inserted Item's `value`. */
+    value: string;
+    /** The text `serialize` produced and the field now contains. */
+    text: string;
+    /** Offset of the replaced token's trigger character. */
+    start: number;
+    /** Offset just past the replaced token's query. */
+    end: number;
+}
+/** The `detail` a `value-change` CustomEvent carries; `mention` is null for an ordinary keystroke. */
+export interface SkdxMentionsValueChangeDetail {
+    /** The field's whole text after the change. */
+    value: string;
+    /** The text held before this change, or `null` when there was none. */
+    previousValue: string | null;
+    /** What drove the change. */
+    reason: 'keyboard' | 'pointer' | 'programmatic';
+    /** The entry just inserted and the range it replaced, or `null`. */
+    mention: SkdxMentionsInsertedMention | null;
+}
+/** The `detail` a `query-change` CustomEvent carries, or `null` once no mention is being typed. */
+export type SkdxMentionsQueryChangeDetail = MentionToken;
+/** Why virtual focus moved: a key, a pointer, or an internal re-seed. */
+export type SkdxMentionsHighlightReason = 'keyboard' | 'pointer' | 'auto';
+/** The `detail` a `highlight-change` CustomEvent carries, naming values rather than element ids. */
+export interface SkdxMentionsHighlightChangeDetail {
+    /** The highlighted entry's value, or `null` when nothing is highlighted. */
+    value: string | null;
+    /** The value the highlight held before this move, or `null`. */
+    previousValue: string | null;
+    /** What moved the highlight. */
+    reason: SkdxMentionsHighlightReason;
+}
+/** What an `<skdx-mentions-item>` registers about itself, so a key can insert it by id. */
+export interface SkdxMentionsItemEntry {
+    /** The value reported on the value-change detail when this entry is inserted. */
+    value: string;
+    /** The entry's `text-value`, or its rendered text — matched by `filter`, written by `serialize`. */
+    text: string;
+    /** The trigger character this entry belongs to. */
+    trigger: string;
+}
+declare const SkdxMentions_base: typeof LitElement & (new (...args: any[]) => import("../index.js").SkdxFormAssociated) & {
+    formAssociated: boolean;
+};
+/**
+ * `<skdx-mentions>` is a multi-line field whose trigger characters open a caret-anchored listbox over one token, leaving the rest of the text and the caret alone.
+ *
+ * @example
+ * ```html
+ * <skdx-mentions aria-label="Message">
+ *   <skdx-mentions-input placeholder="Say something…"></skdx-mentions-input>
+ *   <skdx-mentions-content>
+ *     <skdx-mentions-item value="alice">Alice</skdx-mentions-item>
+ *     <skdx-mentions-empty>No matches</skdx-mentions-empty>
+ *   </skdx-mentions-content>
+ * </skdx-mentions>
+ * ```
+ *
+ * @fires value-change - Fires with `{ value, previousValue, reason, mention }` whenever the field's text changes. `value` is the whole text, never the mention alone; `mention` names the entry just inserted and the range it replaced, and is `null` for an ordinary keystroke.
+ * @fires query-change - Fires with `{ trigger, query, start, end }` whenever the token under the caret changes, and with `null` once no mention is being typed. This is the hook an async collection is loaded from.
+ * @fires open-change - Fires with the new open state (boolean) whenever the popup opens or closes.
+ * @fires highlight-change - Fires with `{ value, previousValue, reason }` whenever virtual focus moves.
+ * @fires open-change-complete - Fires with the new open state after `<skdx-mentions-content>`'s enter or exit animation has finished. Not cancelable: the change has already happened.
+ *
+ * @slot option - Per-entry content for the derived anatomy, addressed by `data-value` — this package's form of the `renderOption` hook the other ports take as a function.
+ */
+export declare class SkdxMentions extends SkdxMentions_base {
+    static styles: import("lit").CSSResult;
+    /**
+     * The field's whole text, for controlled usage; pair it with `value-change`.
+     * @default '' — an empty field.
+     */
+    value: string;
+    /**
+     * Initial text of the field, and the text a form reset restores.
+     * @default '' — the field starts empty.
+     */
+    defaultValue: string;
+    /**
+     * Characters that open a mention when typed at a word boundary, read one character at a time from a string.
+     * @default '@' — a single people-mention trigger.
+     */
+    triggers: string | readonly string[];
+    /**
+     * The mentionable collection as data, rendered as one Item per entry.
+     * @default undefined — author the Item children by hand.
+     */
+    options?: readonly SkdxMentionsOptionData[];
+    /**
+     * How Items are narrowed against the active query, the substring between the trigger and the caret.
+     * @default 'manual' — the consumer renders only matching Items.
+     */
+    filter: SkdxMentionsFilter;
+    /**
+     * Builds the text that replaces the typed token when an entry is chosen.
+     * @default (item) => `${item.trigger}${item.textValue}` — the trigger followed by the entry's text.
+     */
+    serialize: SkdxMentionsSerializer;
+    /**
+     * Whether a single space follows an inserted mention so typing continues cleanly.
+     * @default true — skipped where the text already carries on with whitespace.
+     */
+    appendSpace: boolean;
+    /**
+     * How many spaces a query may contain before the mention is abandoned.
+     * @default 0 — the first space ends the mention.
+     */
+    allowedSpaces: number;
+    /**
+     * Whether a trigger only opens a mention at the start of the value or after a non-word character.
+     * @default true — which is what keeps `user@example.com` silent.
+     */
+    requireWordBoundary: boolean;
+    /**
+     * Whether the suggestion popup is open; pair it with `open-change`.
+     * @default false — the popup opens when a trigger is typed.
+     */
+    open: boolean;
+    /**
+     * Initial open state, applied once on connect if `open` was not authored.
+     * @default false
+     */
+    defaultOpen: boolean;
+    /**
+     * Keeps the first entry highlighted whenever the filtered list changes while open.
+     * @default true — the opposite of Combobox, so Enter always has a target.
+     */
+    autoHighlight: boolean;
+    /**
+     * Wraps arrow navigation around the ends of the entry list.
+     * @default true — set false to clamp at the ends.
+     */
+    loop: boolean;
+    /**
+     * Marks entries as in flight and suppresses the result-count announcement.
+     * @default false
+     */
+    loading: boolean;
+    /**
+     * Grows the field to fit its content instead of showing a scrollbar.
+     * @default false
+     */
+    autoResize: boolean;
+    /**
+     * The field's opening size, and the floor auto-resize will not shrink below.
+     * @default 2 — the platform's own `rows` default.
+     */
+    minRows: number;
+    /**
+     * Caps auto-resize growth to this many rows, based on computed line-height.
+     * @default undefined — the field grows without a limit.
+     */
+    maxRows?: number;
+    /**
+     * Disables the field so no mention can ever open, and blocks every edit.
+     * @default false
+     */
+    disabled: boolean;
+    /**
+     * Makes the field read-only, suspending trigger detection but keeping it focusable.
+     * @default false
+     */
+    readOnly: boolean;
+    /**
+     * Marks the field as invalid, exposed as `aria-invalid` and `data-invalid`.
+     * @default false
+     */
+    invalid: boolean;
+    /**
+     * Name used as the `FormData` entry key; submits the field's whole text.
+     * @default undefined — the field submits nothing at all.
+     */
+    name?: string;
+    /**
+     * Id of the `<form>` this field submits into, so it can live outside that subtree.
+     * @default undefined — submits into the nearest ancestor form.
+     */
+    formId?: string;
+    /**
+     * Marks the field required for native constraint validation while its text is empty.
+     * @default false
+     */
+    required: boolean;
+    /**
+     * Formats the count announced whenever the rendered entry count changes while open.
+     * @default defaultGetResultCountLabel — e.g. `"3 results available"`
+     */
+    getResultCountLabel: (count: number) => string;
+    /**
+     * Placeholder text forwarded to the derived Input, ignored under manual composition.
+     * @default undefined — no placeholder is derived.
+     */
+    placeholder?: string | undefined;
+    /** Id for `<skdx-mentions-content>` and the Input's `aria-controls`. */
+    contentId: string;
+    /** Id of the virtually-focused entry, or `null` when nothing is highlighted. */
+    activeId: string | null;
+    /** @internal The `<skdx-mentions-input>` descendant that owns the textarea. */
+    inputHost: SkdxMentionsInput | null;
+    /** @internal The mounted `<skdx-mentions-content>`, registered so Input knows something else owns Escape. */
+    contentEl: HTMLElement | null;
+    /** @internal The token last derived from the text and the caret, or `null`. */
+    token: MentionToken | null;
+    private dismissedAt;
+    /** Moves keyboard focus to the text field, which is where this component keeps real DOM focus. */
+    focus(options?: FocusOptions): void;
+    /** The configured trigger characters, one per entry. @internal */
+    get triggerList(): readonly string[];
+    /** The trigger an Item with no `trigger` of its own belongs to. @internal */
+    get defaultTrigger(): string;
+    private changes;
+    /** @internal Sets `value` and dispatches `value-change`; a no-op if unchanged. */
+    setValue(next: string, reason?: SkdxMentionsValueChangeDetail['reason'], mention?: SkdxMentionsInsertedMention | null): void;
+    /** @internal Sets `open` and dispatches `open-change`; clears the highlight on close. */
+    setOpen(open: boolean): void;
+    /** @internal Sets the active token and dispatches `query-change`; a no-op if unchanged. */
+    setToken(token: MentionToken | null): void;
+    /**
+     * Re-derives the token, the dismissal and the open state from the text and
+     * the caret together — the whole detection state, with nothing carried over.
+     *
+     * Detection is suspended, not merely closed, while `disabled` or `readOnly`:
+     * no token is derived, so no `query-change` fires and no `data-trigger` lands.
+     * @internal
+     */
+    refreshToken(value: string, caret: number): void;
+    /** @internal Closes the popup on Escape, leaving the text and the caret untouched. */
+    dismiss(): void;
+    /** @internal Whether item text survives the current filter and the active query. */
+    matchesFilter(itemText: string): boolean;
+    /**
+     * Whether an Item is an option for the active token at all: an entry
+     * addressing another trigger is excluded exactly as a filter rejection is.
+     * @internal
+     */
+    matchesToken(itemTrigger: string, itemText: string): boolean;
+    /** @internal Visible entries, ranked by a numeric filter predicate via inline CSS `order`. */
+    visibleOptions(): HTMLElement[];
+    /** @internal The caret rectangle the popup is anchored to, measured fresh. */
+    measureCaret(): CaretRect;
+    /**
+     * Replaces the active token with the serialized entry, moves the caret past
+     * it and closes; reports whether there was anything to insert.
+     * @internal
+     */
+    insertItem(id: string, reason: SkdxMentionsValueChangeDetail['reason']): boolean;
+    /** @internal Sets the virtually-focused entry id, reporting the move by value. */
+    setActiveId(id: string | null, reason?: SkdxMentionsHighlightReason): void;
+    private previousHighlight;
+    private readonly itemRegistry;
+    /** @internal Called by rendered entries so a key can insert one by id. */
+    registerItem(id: string, entry: SkdxMentionsItemEntry): void;
+    /** @internal Called when an entry unmounts or stops being an option. */
+    unregisterItem(id: string): void;
+    /** @internal The registered entry for an id, or `undefined` if no longer rendered. */
+    getItem(id: string): SkdxMentionsItemEntry | undefined;
+    private reseedFrame?;
+    private scheduleReseed;
+    private notify;
+    private readonly itemObserver;
+    private announceResultCount;
+    private maybeAutoHighlight;
+    private seeded;
+    private _anatomyOptionsRef?;
+    connectedCallback(): void;
+    private observeOptions;
+    private readonly fillAnatomy;
+    disconnectedCallback(): void;
+    private hasUpdatedOnce;
+    private teardownOpenChangeComplete?;
+    protected updated(changed: Map<string, unknown>): void;
+    private syncFormState;
+    /** Restores the live `defaultValue` and closes any open popup; fires no change event. */
+    formResetCallback(): void;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-mentions': SkdxMentions;
+    }
+}
+export {};

package/dist/mentions/Mentions.js

@@ -0,0 +1,5 @@
+var b=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var n=(o,a,e,r)=>{for(var t=r>1?void 0:r?O(a,e):a,l=o.length-1,u;l>=0;l--)(u=o[l])&&(t=(r?u(a,e,t):u(t))||t);return r&&t&&b(a,e,t),t};import{css as I,html as T,LitElement as R}from"lit";import{property as s}from"lit/decorators.js";import{hasAuthoredParts as k,hasGeneratedContent as A}from"../internal/authored.js";import{decideControllable as C,decideReset as x}from"../internal/controllable.js";import{customElement as M}from"../internal/define.js";import{emit as p}from"../internal/events.js";import{FormAssociated as S}from"../internal/form-associated.js";import{nextId as E}from"../internal/ids.js";import{DEFAULT_MENTION_TRIGGER as c,findMentionToken as F,insertMention as H,isMentionDismissed as q}from"../internal/mentions.js";import{notifyOpenChangeComplete as w}from"../internal/open-change-complete.js";import{defaultOptionsFilter as V}from"../internal/options.js";import{optOutBoolean as f}from"../internal/positioning.js";import{filterKeeps as N,sortByScore as L}from"../internal/scored-filter.js";import{announce as B}from"../utils/live-announcer.js";import{measureCaretRect as D}from"./caret-rect.js";import{MENTIONS_FAMILY as v}from"./family.js";import{fillMentionsAnatomy as _,MENTIONS_ANATOMY_GENERATED as y,MENTIONS_RENDER_SLOTS as z,refreshMentionsAnatomyText as G}from"./MentionsAnatomy.js";var g='[role="option"]:not([data-disabled])';function U(o){return`${o} result${o===1?"":"s"} available`}var $=o=>`${o.trigger}${o.textValue}`;function W(o,a){return o===null||a===null?o===a:o.trigger===a.trigger&&o.query===a.query&&o.start===a.start&&o.end===a.end}var i=class extends S(R){constructor(){super(...arguments);this.value="";this.defaultValue="";this.triggers=c;this.filter="manual";this.serialize=$;this.appendSpace=!0;this.allowedSpaces=0;this.requireWordBoundary=!0;this.open=!1;this.defaultOpen=!1;this.autoHighlight=!0;this.loop=!0;this.loading=!1;this.autoResize=!1;this.minRows=2;this.disabled=!1;this.readOnly=!1;this.invalid=!1;this.required=!1;this.getResultCountLabel=U;this.contentId=E("skdx-mentions-content");this.activeId=null;this.inputHost=null;this.contentEl=null;this.token=null;this.dismissedAt=null;this.previousHighlight=null;this.itemRegistry=new Map;this.itemObserver=new MutationObserver(()=>{this.announceResultCount(),this.visibleOptions()});this.seeded=!1;this.fillAnatomy=()=>{if(k(this,y,z)){this._anatomyOptionsRef=void 0;return}this.options!==this._anatomyOptionsRef||!A(this,y)?(this._anatomyOptionsRef=this.options,_(this),this.observeOptions()):G(this)};this.hasUpdatedOnce=!1}focus(e){this.inputHost?.focus(e)}get triggerList(){let e=this.triggers;return typeof e=="string"?[...e]:e}get defaultTrigger(){return this.triggerList[0]??c}changes(e,r){return C({controlled:void 0,uncontrolled:e},r).emit}setValue(e,r="programmatic",t=null){if(!this.changes(this.value,e))return;let l=this.value;this.value=e,p(this,"value-change",{value:e,previousValue:l,reason:r,mention:t}),this.notify()}setOpen(e){this.changes(this.open,e)&&(this.open=e,e||this.setActiveId(null),p(this,"open-change",e),this.notify())}setToken(e){W(this.token,e)||(this.token=e,p(this,"query-change",e===null?null:{...e}),this.notify())}refreshToken(e,r){let t=this.disabled||this.readOnly?null:F(e,r,{triggers:this.triggers,allowedSpaces:this.allowedSpaces,requireWordBoundary:this.requireWordBoundary});t===null&&(this.dismissedAt=null);let l=t!==null&&!q(t,this.dismissedAt);this.setToken(t),this.setOpen(l)}dismiss(){this.token!==null&&(this.dismissedAt=this.token.start),this.setOpen(!1)}matchesFilter(e){let r;return this.filter!=="manual"?r=this.filter:this.options&&(r=V),!r||N(r(e,this.token?.query??""))}matchesToken(e,r){let t=this.token?.trigger;return t!==void 0&&e!==t?!1:this.matchesFilter(r)}visibleOptions(){let e=this.filter;if(typeof e!="function")return Array.from(this.querySelectorAll(g));let r=this.token?.query??"";return L(this,g,t=>{let l=this.itemRegistry.get(t);if(!l)return null;let u=e(l.text,r);return typeof u=="number"?u:null})}measureCaret(){let e=this.inputHost?.field??null;return e?D(e,this.token?.end??e.selectionStart??0):{top:0,left:0,height:0}}insertItem(e,r){let t=this.itemRegistry.get(e),l=this.inputHost,u=l?.field??null,h=this.token;if(!t||!l||!u||!h||this.disabled||this.readOnly)return!1;let m=this.serialize({value:t.value,textValue:t.text,trigger:h.trigger}),d=H(u.value,h,m,this.appendSpace);return l.applyInsertion(d.value,d.caret),this.setValue(d.value,r,{trigger:h.trigger,value:t.value,text:m,start:h.start,end:h.end}),this.refreshToken(d.value,d.caret),!0}setActiveId(e,r="auto"){this.activeId=e;let t=e?this.itemRegistry.get(e)?.value??null:null;if(t!==this.previousHighlight){let l=this.previousHighlight;this.previousHighlight=t,p(this,"highlight-change",{value:t,previousValue:l,reason:r})}this.notify()}registerItem(e,r){this.itemRegistry.set(e,r)}unregisterItem(e){this.itemRegistry.delete(e),this.activeId===e&&this.scheduleReseed()}getItem(e){return this.itemRegistry.get(e)}scheduleReseed(){this.reseedFrame===void 0&&(this.reseedFrame=requestAnimationFrame(()=>{if(this.reseedFrame=void 0,this.activeId===null)return;let e=this.visibleOptions();e.some(r=>r.id===this.activeId)||this.setActiveId(e[0]?.id??null)}))}notify(){v.notify(this),this.requestUpdate()}announceResultCount(){!this.open||this.loading||B(this.getResultCountLabel(this.querySelectorAll(g).length))}maybeAutoHighlight(){!this.autoHighlight||!this.open||this.activeId!==null||requestAnimationFrame(()=>{if(!this.autoHighlight||!this.open||this.activeId!==null)return;let e=this.visibleOptions()[0];e&&this.setActiveId(e.id)})}connectedCallback(){super.connectedCallback();let e=this.querySelector("skdx-mentions-content")?.id;e&&(this.contentId=e),this.seeded||(this.seeded=!0,this.hasAttribute("value")||(this.value=this.defaultValue),this.hasAttribute("open")||(this.open=this.defaultOpen)),this.observeOptions(),queueMicrotask(this.fillAnatomy)}observeOptions(){this.itemObserver.disconnect(),this.itemObserver.observe(this.querySelector("skdx-mentions-content")??this,{childList:!0,subtree:!0,attributeFilter:["data-disabled","role"]})}disconnectedCallback(){this.itemObserver.disconnect(),this.reseedFrame!==void 0&&cancelAnimationFrame(this.reseedFrame),this.reseedFrame=void 0,this.teardownOpenChangeComplete?.(),super.disconnectedCallback()}updated(e){let r=!this.hasUpdatedOnce;this.hasUpdatedOnce=!0,this.fillAnatomy(),this.syncFormState(),(e.has("disabled")||e.has("readOnly"))&&(this.disabled||this.readOnly)&&(this.setToken(null),this.setOpen(!1)),(e.has("open")||e.has("loading"))&&this.open&&this.announceResultCount(),this.maybeAutoHighlight(),(e.has("filter")||e.has("triggers"))&&requestAnimationFrame(()=>this.visibleOptions()),e.size>0&&v.notify(this),e.has("open")&&!r&&(this.teardownOpenChangeComplete?.(),this.teardownOpenChangeComplete=w(()=>this.contentEl,this.open,t=>p(this,"open-change-complete",t)))}syncFormState(){this.setFormValue(this.value);let e=this.inputHost?.field;e&&this.mirrorValidity(e)}formResetCallback(){let e=x({controlled:void 0,uncontrolled:this.value},this.defaultValue);e.write&&(this.value=e.value??""),this.dismissedAt=null,this.setToken(null),this.setOpen(!1)}render(){return T`<slot @slotchange=${this.fillAnatomy}></slot>`}};i.styles=I`
+    :host {
+      display: contents;
+    }
+  `,n([s({type:String})],i.prototype,"value",2),n([s({type:String,attribute:"default-value"})],i.prototype,"defaultValue",2),n([s({type:String})],i.prototype,"triggers",2),n([s({attribute:!1})],i.prototype,"options",2),n([s({attribute:!1})],i.prototype,"filter",2),n([s({attribute:!1})],i.prototype,"serialize",2),n([s({converter:f,attribute:"append-space"})],i.prototype,"appendSpace",2),n([s({type:Number,attribute:"allowed-spaces"})],i.prototype,"allowedSpaces",2),n([s({converter:f,attribute:"require-word-boundary"})],i.prototype,"requireWordBoundary",2),n([s({type:Boolean,reflect:!0})],i.prototype,"open",2),n([s({type:Boolean,attribute:"default-open"})],i.prototype,"defaultOpen",2),n([s({converter:f,attribute:"auto-highlight"})],i.prototype,"autoHighlight",2),n([s({converter:f,attribute:"loop"})],i.prototype,"loop",2),n([s({type:Boolean,reflect:!0})],i.prototype,"loading",2),n([s({type:Boolean,attribute:"auto-resize",reflect:!0})],i.prototype,"autoResize",2),n([s({type:Number,attribute:"min-rows"})],i.prototype,"minRows",2),n([s({type:Number,attribute:"max-rows"})],i.prototype,"maxRows",2),n([s({type:Boolean,reflect:!0})],i.prototype,"disabled",2),n([s({type:Boolean,attribute:"read-only",reflect:!0})],i.prototype,"readOnly",2),n([s({type:Boolean,reflect:!0})],i.prototype,"invalid",2),n([s({type:String,reflect:!0})],i.prototype,"name",2),n([s({type:String,attribute:"form",reflect:!0})],i.prototype,"formId",2),n([s({type:Boolean,reflect:!0})],i.prototype,"required",2),n([s({attribute:!1})],i.prototype,"getResultCountLabel",2),n([s({type:String})],i.prototype,"placeholder",2),i=n([M("skdx-mentions")],i);export{g as OPTION_SELECTOR,i as SkdxMentions,U as defaultGetResultCountLabel,$ as defaultMentionSerializer};

package/dist/mentions/MentionsAnatomy.cjs

@@ -0,0 +1 @@
+"use strict";var d=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var b=(e,t)=>{for(var n in t)d(e,n,{get:t[n],enumerable:!0})},x=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of p(t))!u.call(e,i)&&i!==n&&d(e,i,{get:()=>t[i],enumerable:!(r=c(t,i))||r.enumerable});return e};var A=e=>x(d({},"__esModule",{value:!0}),e);var k={};b(k,{MENTIONS_ANATOMY_GENERATED:()=>m,MENTIONS_RENDER_SLOTS:()=>E,fillMentionsAnatomy:()=>S,refreshMentionsAnatomyText:()=>h});module.exports=A(k);var o=require("../internal/host-attributes.cjs"),a=require("../internal/options.cjs"),v=require("./MentionsInput.cjs"),y=require("./MentionsPortal.cjs"),N=require("./MentionsContent.cjs"),O=require("./MentionsItem.cjs"),T=require("./MentionsEmpty.cjs"),m="data-skdx-mentions-generated",E=["option"],f="No results";function M(e,t){return e.map(n=>{let r=document.createElement("skdx-mentions-item");r.setAttribute("value",n.value),n.trigger&&r.setAttribute("trigger",n.trigger),n.disabled&&r.setAttribute("disabled","");let i=n.label??n.value,s=t.get(n.value);return s?(r.setAttribute("text-value",i),r.append((0,a.stampRenderSlot)(s))):r.textContent=i,r})}function S(e){let t=(0,a.renderSlotContent)(e,"option"),n=(0,o.claimHostAttributes)(e),r=(0,o.resolveHostLabel)(n,e.placeholder),i=document.createElement("skdx-mentions-input");i.setAttribute(m,""),e.placeholder&&i.setAttribute("placeholder",e.placeholder),(0,o.applyHostAttributes)(i,n,["aria-label"]),(0,o.setOptionalAttribute)(i,"aria-label",r);let s=document.createElement("skdx-mentions-empty");s.textContent=f;let l=document.createElement("skdx-mentions-content");l.setAttribute(m,""),(0,o.setOptionalAttribute)(l,"aria-label",r),l.append(...M(e.options??[],t),s),e.replaceChildren(i,l)}function h(e){let t=e.querySelector("skdx-mentions-input");t&&(e.placeholder?t.setAttribute("placeholder",e.placeholder):t.removeAttribute("placeholder"))}0&&(module.exports={MENTIONS_ANATOMY_GENERATED,MENTIONS_RENDER_SLOTS,fillMentionsAnatomy,refreshMentionsAnatomyText});