@skdx/vue 0.28.0 → 0.30.0

package/dist/utils/field-core.js

@@ -0,0 +1 @@
+var t="validity-change",e="data-skdx-field",i="data-skdx-field-name",s="data-skdx-field-message",r="data-skdx-field-description",o="data-skdx-field-error",a="data-skdx-field-character-count",n="data-skdx-field-pending",l="data-skdx-field-resubmit",d="data-skdx-form-field",h="data-skdx-form-message",u=["validity-change","invalid","change","blur"],c="data-skdx-error-summary",m=1e3;function p(t){const e=Math.abs(t),i=1===e?"character":"characters";return t<0?`You have ${e} ${i} too many`:`You have ${e} ${i} remaining`}function b(t,e,i=0){return i<=0||t>=e*i/100}var f="This field is invalid.",v="data-skdx-field-control",y=[`[${v}]`,'input:not([type="hidden"])',"select","textarea",'[role="textbox"]','[role="searchbox"]','[role="combobox"]','[role="listbox"]','[role="radiogroup"]','[role="group"]','[role="slider"]','[role="spinbutton"]','[role="checkbox"]','[role="radio"]','[role="switch"]'].join(", "),g="data-skdx-field-required-indicator",T=/* @__PURE__ */new Set(["INPUT","SELECT","TEXTAREA"]),A=/* @__PURE__ */new Set(["radiogroup","group"]),E=['input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])","button:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function I(t){return null==t?[]:(Array.isArray(t)?t:[t]).filter(t=>"string"==typeof t&&""!==t.trim())}function L(t){for(const e of Array.from(t.querySelectorAll(y)))if("true"!==e.getAttribute("aria-hidden")&&e.closest("[data-skdx-field]")===t)return e;return null}function S(t,i){return C(t,e,i)}function C(t,e,i){for(const s of Array.from(t.querySelectorAll(i)))if(s.closest(`[${e}]`)===t)return s;return null}function x(t){if(!t)return;const e=t;return"checkbox"===e.type||"radio"===e.type?e.checked:"value"in t?e.value:t.querySelector('input[aria-hidden="true"]')?.value}function R(t){return null!=t&&!1!==t&&""!==t&&!(Array.isArray(t)&&0===t.length)}function _(t,e,i){i?t.setAttribute(e,""):t.removeAttribute(e)}function D(t,...e){const i=t.split(/\s+/).filter(Boolean);for(const t of e)t&&!i.includes(t)&&i.push(t);return i.join(" ")}function k(t){return t.closest("form, skdx-form")??t.parentElement??t}function w(t){const e=L(t),i=S(t,"[data-skdx-field-error]")?.textContent?.trim()||t.getAttribute("data-skdx-field-message")||t.getAttribute("data-skdx-field-name")||"";return e?.id&&i?[{id:e.id,message:i}]:[]}function B(t){const e=C(t,d,y);if(!e?.id||"true"!==e.getAttribute("aria-invalid"))return[];const i=C(t,"data-skdx-form-field","[data-skdx-form-message]:not([hidden])")?.textContent?.trim()||t.getAttribute("data-skdx-field-name")||"";return i?[{id:e.id,message:i}]:[]}function F(t){return Array.from(t.querySelectorAll(`[${e}][data-invalid], [${d}]`)).flatMap(t=>(t.hasAttribute("data-skdx-field")?w:B)(t))}var V="__skdxFieldCheckValidity",O="__skdxFieldReset";async function M(t){const i=Array.from(t.querySelectorAll(`[${e}]`));return(await Promise.all(i.map(t=>t[V]?.()??Promise.resolve(!0)))).every(Boolean)}function q(t){for(const i of Array.from(t.querySelectorAll(`[${e}]`)))i[O]?.()}function N(t,e=document){const i=e.getElementById(t);if(!i)return;const s=i.getAttribute("role"),r=("FIELDSET"===i.tagName||null!==s&&A.has(s)?i.querySelector(E):null)??i;r.focus(),r.scrollIntoView?.({block:"center"})}var U=class{constructor(t){this.options=t,this.props={},this.root=null,this.form=null,this.control=null,this.baseDescribedBy="",this.baseLabelledBy="",this.wroteLabelledBy=!1,this.wroteRequired=!1,this.wroteDisabled=!1,this.wroteGroupDisabled=!1,this.runToken=0,this.pending=!1,this.injected=[],this.custom=[],this.characterCount=null,this.awaitingSubmit=!1,this.handleInput=()=>{const t=this.isOverLimit(this.snapshot.count),e=this.readCount();this.update({dirty:!0,filled:R(this.resolveValue()),count:e,errors:this.composeErrors(e)}),this.scheduleCountAnnouncement(e,t),("change"===this.props.mode||this.snapshot.errors.length>0)&&this.scheduleValidation()},this.handleFocusOut=()=>{const t=this.readCount();this.update({touched:!0,filled:R(this.resolveValue()),count:t,errors:this.composeErrors(t)});const e=void 0!==this.validationTimer;clearTimeout(this.validationTimer),this.validationTimer=void 0;const i=this.props.mode??"blur";(e||"blur"===i||this.snapshot.errors.length>0)&&this.runValidation()},this.handleSubmit=t=>{if(!this.form)return;const e=t.target;if(e!==this.form&&e?.closest?.("form")!==this.form||this.isEngineResubmit(t))return;this.markTouched();const i=this.runValidation({silent:this.hasErrorSummary()});if(P(i))return t.preventDefault(),this.awaitingSubmit=!0,void Promise.resolve(i).then(()=>{this.awaitingSubmit&&(this.awaitingSubmit=!1,this.resubmitIfSettled())});(i.length>0||this.pending)&&t.preventDefault()},this.snapshot={controlId:"",errors:[],valid:!0,touched:!1,dirty:!1,filled:!1,count:0,validity:null}}get state(){return this.snapshot}setProps(t){const e=this.props.value;this.props=t;const i=I(t.errors??null),s=!function(t,e){return t.length===e.length&&t.every((t,i)=>t===e[i])}(this.injected,i);s&&(this.injected=i);const r=t.value!==e;if(!s&&!r)return;const o=this.readCount();this.update({count:o,filled:R(this.resolveValue()),errors:this.composeErrors(o)})}setCharacterCount(t){if((this.characterCount?.maxLength??null)===(t?.maxLength??null)&&(this.characterCount?.threshold??0)===(t?.threshold??0))return;this.characterCount=t;const e=this.readCount();this.update({count:e,errors:this.composeErrors(e)})}readCount(){const t=this.resolveValue();return"string"==typeof t?t.length:0}countMessage(t){return(this.props.getCharacterCountMessage??p)(t)}isOverLimit(t){return null!==this.characterCount&&t>this.characterCount.maxLength}composeErrors(t=this.snapshot.count){const e=[...this.injected,...this.custom];return this.characterCount&&this.isOverLimit(t)&&e.push(this.countMessage(this.characterCount.maxLength-t)),e}scheduleCountAnnouncement(t,e){const i=this.characterCount;if(!i)return;if(clearTimeout(this.announceTimer),this.isOverLimit(t))return void(e||this.options.announce(this.countMessage(i.maxLength-t),"assertive"));if(!b(t,i.maxLength,i.threshold))return;const s=i.maxLength-t;this.announceTimer=setTimeout(()=>{this.options.announce(this.countMessage(s),"polite")},1e3)}connect(t){this.root=t,t.setAttribute(e,""),Object.defineProperty(t,V,{value:()=>this.validate(),configurable:!0,enumerable:!1,writable:!0}),Object.defineProperty(t,O,{value:()=>this.reset(),configurable:!0,enumerable:!1,writable:!0}),t.addEventListener("input",this.handleInput,!0),t.addEventListener("change",this.handleInput,!0),t.addEventListener("focusout",this.handleFocusOut,!0),this.form=t.closest("form"),this.form&&t.ownerDocument.addEventListener("submit",this.handleSubmit,!0),this.sync();const i=this.readCount();this.update({filled:R(this.resolveValue()),count:i,errors:this.composeErrors(i)})}disconnect(){clearTimeout(this.announceTimer),clearTimeout(this.validationTimer),this.validationTimer=void 0,this.awaitingSubmit=!1;const t=this.root;t&&(t.removeEventListener("input",this.handleInput,!0),t.removeEventListener("change",this.handleInput,!0),t.removeEventListener("focusout",this.handleFocusOut,!0),this.form&&t.ownerDocument.removeEventListener("submit",this.handleSubmit,!0),delete t[V],delete t[O],this.root=null,this.form=null,this.control=null)}sync(){const t=this.root;if(!t)return;const e=L(t);e!==this.control&&(this.control=e,this.baseDescribedBy=e?.getAttribute("aria-describedby")??"",this.baseLabelledBy=e?.getAttribute("aria-labelledby")??"",this.wroteLabelledBy=!1,this.wroteRequired=!1,this.wroteDisabled=!1,this.wroteGroupDisabled=!1);const{name:r}=this.props;r?t.setAttribute(i,r):t.removeAttribute(i);const o=this.snapshot.errors.join(" ");o?t.setAttribute(s,o):t.removeAttribute(s),this.applyStateAttributes(t),e&&(e.id||(e.id=this.options.controlId),e.id!==this.snapshot.controlId&&(this.snapshot={...this.snapshot,controlId:e.id,validity:this.readValidity()},this.options.onSnapshotChange(this.snapshot)),this.applyDescribedBy(t,e),this.snapshot.errors.length>0?e.setAttribute("aria-invalid","true"):e.removeAttribute("aria-invalid"),this.applyLabelledBy(t,e),this.applyConstraintState(e),this.applyStateAttributes(e))}applyDescribedBy(t,e){const i=null!==S(t,`[${r}]`),s=null!==S(t,`[${o}]`),a=D(this.baseDescribedBy,i?this.options.descriptionId:void 0,s?this.options.errorId:void 0);a?e.setAttribute("aria-describedby",a):e.removeAttribute("aria-describedby")}applyLabelledBy(t,e){const i=null!==t.ownerDocument.getElementById(this.options.labelId);this.options.grouped&&i?(e.setAttribute("aria-labelledby",D(this.baseLabelledBy,this.options.labelId)),this.wroteLabelledBy=!0):this.wroteLabelledBy&&(this.baseLabelledBy?e.setAttribute("aria-labelledby",this.baseLabelledBy):e.removeAttribute("aria-labelledby"),this.wroteLabelledBy=!1)}applyConstraintState(t){const e=T.has(t.tagName),i=!0===this.props.required,s=!0===this.props.disabled;i?(e?t.setAttribute("required",""):t.setAttribute("aria-required","true"),this.wroteRequired=!0):this.wroteRequired&&(t.removeAttribute(e?"required":"aria-required"),this.wroteRequired=!1),s?(e?t.setAttribute("disabled",""):t.setAttribute("aria-disabled","true"),this.wroteDisabled=!0):this.wroteDisabled&&(t.removeAttribute(e?"disabled":"aria-disabled"),this.wroteDisabled=!1),e||this.applyGroupDisabled(t,s)}applyGroupDisabled(t,e){const i=t.getAttribute("role");if(("FIELDSET"===t.tagName||null!==i&&A.has(i))&&(e||this.wroteGroupDisabled)){for(const i of t.querySelectorAll("input, select, textarea, button"))e?i.setAttribute("disabled",""):i.removeAttribute("disabled");this.wroteGroupDisabled=e}}validate(){return Promise.resolve(this.runValidation()).then(t=>0===t.length)}reset(){this.injected=[],this.custom=[],this.pending=!1,this.awaitingSubmit=!1,this.runToken++,clearTimeout(this.announceTimer),clearTimeout(this.validationTimer),this.validationTimer=void 0,this.markPending(!1);const t=this.readCount();this.update({touched:!1,dirty:!1,count:t,filled:R(this.resolveValue()),errors:this.composeErrors(t)}),this.sync()}markTouched(){this.snapshot.touched||this.update({touched:!0})}applyStateAttributes(t){const{errors:e,touched:i,dirty:s,filled:r,count:o}=this.snapshot;_(t,"data-invalid",e.length>0),_(t,"data-valid",0===e.length),_(t,"data-touched",i),_(t,"data-dirty",s),_(t,"data-filled",r),_(t,"data-over-limit",this.isOverLimit(o)),_(t,"data-disabled",!0===this.props.disabled)}resolveValue(){return void 0!==this.props.value?this.props.value:x(this.control)}readValidity(){return this.control?.validity??null}markPending(t){this.root&&_(this.root,n,t)}nativeMessage(){const t=this.control;return!t?.validity||t.validity.valid?null:t.validationMessage||this.props.invalidMessage||"This field is invalid."}runValidation(t={}){const e=++this.runToken,i=this.props.validate?.(this.resolveValue());return P(i)?(this.pending=!0,this.markPending(!0),Promise.resolve(i).then(i=>e!==this.runToken?this.snapshot.errors:(this.pending=!1,this.markPending(!1),this.commit(i,t)))):this.commit(i,t)}commit(t,e){if(this.custom=I(t),0===this.custom.length){const t=this.nativeMessage();t&&!this.injected.includes(t)&&(this.custom=[t])}const i=this.readCount(),s=this.composeErrors(i),r=0===this.snapshot.errors.length;this.update({errors:s,count:i,filled:R(this.resolveValue())});const o=s[0];return o&&r&&!e.silent&&this.options.announce(o,"assertive"),s}update(e){const i={...this.snapshot,...e,valid:!0,validity:this.readValidity()};i.valid=0===i.errors.length,!function(t,e){return t.controlId===e.controlId&&t.valid===e.valid&&t.touched===e.touched&&t.dirty===e.dirty&&t.filled===e.filled&&t.count===e.count&&t.validity===e.validity&&t.errors.length===e.errors.length&&t.errors.every((t,i)=>t===e.errors[i])}(this.snapshot,i)&&(this.snapshot=i,this.sync(),this.options.onSnapshotChange(i),this.root?.dispatchEvent(new CustomEvent(t,{bubbles:!0,composed:!0,detail:{valid:i.valid,errors:i.errors,touched:i.touched,dirty:i.dirty,filled:i.filled,count:i.count,validity:i.validity}})))}scheduleValidation(){clearTimeout(this.validationTimer),this.validationTimer=void 0;const t="change"===this.props.mode?this.props.validationDebounceTime??0:0;t<=0?this.runValidation():this.validationTimer=setTimeout(()=>{this.validationTimer=void 0,this.runValidation()},t)}hasErrorSummary(){return null!=this.form?.querySelector(`[${c}]`)}isEngineResubmit(t){return!!this.form?.hasAttribute("data-skdx-field-resubmit")&&(this.snapshot.errors.length>0&&t.preventDefault(),!0)}resubmitIfSettled(){const t=this.form;if(t&&"function"==typeof t.requestSubmit&&!t.querySelector("[data-skdx-field-pending]")&&!t.querySelector("[data-skdx-field][data-invalid]")){t.setAttribute(l,"");try{t.requestSubmit()}finally{t.removeAttribute(l)}}}};function P(t){return"function"==typeof t?.then}export{m as CHARACTER_COUNT_ANNOUNCE_DELAY_MS,u as ERROR_SUMMARY_RESCAN_EVENTS,a as FIELD_CHARACTER_COUNT_ATTRIBUTE,v as FIELD_CONTROL_ATTRIBUTE,y as FIELD_CONTROL_SELECTOR,r as FIELD_DESCRIPTION_ATTRIBUTE,o as FIELD_ERROR_ATTRIBUTE,c as FIELD_ERROR_SUMMARY_ATTRIBUTE,s as FIELD_MESSAGE_ATTRIBUTE,i as FIELD_NAME_ATTRIBUTE,n as FIELD_PENDING_ATTRIBUTE,g as FIELD_REQUIRED_INDICATOR_ATTRIBUTE,l as FIELD_RESUBMIT_ATTRIBUTE,e as FIELD_ROOT_ATTRIBUTE,t as FIELD_VALIDITY_CHANGE_EVENT,d as FORM_FIELD_ATTRIBUTE,h as FORM_MESSAGE_ATTRIBUTE,U as FieldController,f as NATIVE_INVALID_FALLBACK_MESSAGE,p as characterCountMessage,b as characterCountVisible,F as collectFieldErrors,k as errorSummaryScope,L as findFieldControl,N as focusFieldTarget,R as isFilled,I as normalizeMessages,x as readControlValue,q as resetFields,M as validateFields};

package/dist/utils/focus-targets.cjs

@@ -0,0 +1 @@
+const s=require("./tabbable.cjs"),o=require("./dismissal.cjs");var f={Dialog:"the Cancel button when present, then the first tabbable element, then the panel itself",Drawer:"the first tabbable element, then the panel itself",Popover:"the first tabbable element, then the panel itself"},d={Dialog:"[data-skdx-dialog-cancel]"},p={Dialog:"the dialog panel",Drawer:"the drawer panel",Popover:"the popover panel"};function u(e,n,t,r){if(!n)return null;let l;try{l=e.querySelector(n)}catch{return console.warn(`[skdx] ${r}: ${t}="${n}" is not a valid CSS selector. Falling back to the default focus target.`),null}return l||console.warn(t==="initialFocus"?`[skdx] ${r}: initialFocus="${n}" matched no element inside ${p[r]}. Falling back to ${f[r]}.`:`[skdx] ${r}: finalFocus="${n}" matched no element in the document. Falling back to the element that was focused before it opened.`),l}function h(e,n){const t=d[n];return t?e.querySelector(t):null}function c(e,n,t){const r=u(e,n,"initialFocus",t)??h(e,t);if(r){r.focus({preventScroll:!0});return}if(e.contains(document.activeElement))return;const l=e.querySelector(s.TABBABLE_SELECTOR)??e;l===e&&e.tabIndex<0&&(e.tabIndex=-1),l.focus?.({preventScroll:!0})}function i(e,n){const t=u(document,e,"finalFocus",n);return t?(t.focus({preventScroll:!0}),!0):!1}function F(e,n,t,r,l){const a=document.activeElement;return o.autoFocusEvent("open-auto-focus",r)?(c(e,n,t),!0):(document.activeElement===a&&l?.isConnected&&e.contains(a)&&l.focus({preventScroll:!0}),!1)}function b(e,n,t,r){return o.autoFocusEvent("close-auto-focus",r)?i(e,n)?!0:!t?.isConnected||t===document.body||t===document.documentElement?!1:(t.focus({preventScroll:!0}),!0):!1}exports.applyFinalFocus=i;exports.applyInitialFocus=c;exports.applyOpenAutoFocus=F;exports.resolveFocusSelector=u;exports.returnFocus=b;

package/dist/utils/focus-targets.d.cts

@@ -0,0 +1,77 @@
+import { type AutoFocusEvent } from './dismissal.cjs';
+/**
+ * Resolution of initialFocus/finalFocus selectors for overlay families
+ * (Dialog, Drawer, Popover). Uses CSS selector strings (not
+ * element handles) so members survive as attributes on `<skdx-*-content>` —
+ * a DOM node cannot cross HTML attribute boundaries.
+ *
+ * A miss falls back to the overlay's automatic target (the whole point).
+ * Wrong selectors warn on console even in production (a selector pointing at
+ * nothing is a defect regardless).
+ * @internal
+ */
+export type FocusTargetFamily = 'Dialog' | 'Drawer' | 'Popover';
+/**
+ * Resolves one focus-target selector against `root`, or returns `null` and
+ * warns when it names nothing.
+ *
+ * @param root Content for `initialFocus` (the target is part of the panel by
+ * definition, and a loose selector must not reach into the page behind it), the
+ * document for `finalFocus` (whose target is outside Content by definition).
+ * @internal
+ */
+export declare function resolveFocusSelector(root: ParentNode, selector: string | undefined, prop: 'initialFocus' | 'finalFocus', family: FocusTargetFamily): HTMLElement | null;
+/**
+ * Element initial focus should land on inside content: the selector's match or
+ * the default (a Cancel part when present, then first tabbable, then panel).
+ * @internal
+ */
+export declare function initialFocusTarget(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily): HTMLElement;
+/**
+ * Places initial focus for a native `<dialog>` after `showModal()`: the selector's match, then the family's own
+ * default target, else — unless the platform already focused inside the panel — the first tabbable, then the panel itself.
+ * @internal
+ */
+export declare function applyInitialFocus(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily): void;
+/**
+ * Sends focus where finalFocus names, resolved at document level (panel is
+ * closing and the opening element may be gone). Returns whether focus was placed.
+ * @internal
+ */
+export declare function applyFinalFocus(selector: string | undefined, family: FocusTargetFamily): boolean;
+/**
+ * The open-time focus move under its veto: `open-auto-focus` fires *before*
+ * anything moves, so a consumer preventing it keeps focus where the user left
+ * it. A native `<dialog>` is the exception — `showModal()` has already moved
+ * focus into the panel by the time any handler can run, so a veto has to put it
+ * back rather than merely decline to move it. A veto that places focus itself is the
+ * documented way to take initial focus over, so that undo only runs when the handler
+ * left focus where the platform put it.
+ *
+ * @param content the overlay panel
+ * @param selector the `initialFocus` selector, or `undefined` for the default chain
+ * @param family which overlay family, for the console warning a missed selector prints
+ * @param handler the consumer's `open-auto-focus` handler
+ * @param previouslyFocused what had focus before the platform moved it, for the undo
+ * @returns whether focus was placed inside the panel
+ * @internal
+ */
+export declare function applyOpenAutoFocus(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily, handler?: (event: AutoFocusEvent) => void, previouslyFocused?: HTMLElement | null): boolean;
+/**
+ * The close-time focus return, run on every close route (Escape, outside press,
+ * the close button, a controlled `open` flipping) so focus never strands on a
+ * panel that is going away. `close-auto-focus` fires *before* the move, and a
+ * veto leaves focus alone; otherwise `finalFocus` wins, and the element that
+ * opened the overlay is the fallback — skipped when it has left the document,
+ * since focusing a detached node silently drops focus onto `<body>`, and skipped
+ * when it *is* `<body>` or `<html>`, which means nothing was focused when the
+ * overlay opened rather than that the page root should take focus.
+ *
+ * @param selector the `finalFocus` selector, or `undefined` to go straight to the opener
+ * @param family which overlay family, for the console warning a missed selector prints
+ * @param opener the element focused before the overlay opened
+ * @param handler the consumer's `close-auto-focus` handler
+ * @returns whether focus was placed
+ * @internal
+ */
+export declare function returnFocus(selector: string | undefined, family: FocusTargetFamily, opener: HTMLElement | null | undefined, handler?: (event: AutoFocusEvent) => void): boolean;

package/dist/utils/focus-targets.d.ts

@@ -0,0 +1,77 @@
+import { type AutoFocusEvent } from './dismissal.js';
+/**
+ * Resolution of initialFocus/finalFocus selectors for overlay families
+ * (Dialog, Drawer, Popover). Uses CSS selector strings (not
+ * element handles) so members survive as attributes on `<skdx-*-content>` —
+ * a DOM node cannot cross HTML attribute boundaries.
+ *
+ * A miss falls back to the overlay's automatic target (the whole point).
+ * Wrong selectors warn on console even in production (a selector pointing at
+ * nothing is a defect regardless).
+ * @internal
+ */
+export type FocusTargetFamily = 'Dialog' | 'Drawer' | 'Popover';
+/**
+ * Resolves one focus-target selector against `root`, or returns `null` and
+ * warns when it names nothing.
+ *
+ * @param root Content for `initialFocus` (the target is part of the panel by
+ * definition, and a loose selector must not reach into the page behind it), the
+ * document for `finalFocus` (whose target is outside Content by definition).
+ * @internal
+ */
+export declare function resolveFocusSelector(root: ParentNode, selector: string | undefined, prop: 'initialFocus' | 'finalFocus', family: FocusTargetFamily): HTMLElement | null;
+/**
+ * Element initial focus should land on inside content: the selector's match or
+ * the default (a Cancel part when present, then first tabbable, then panel).
+ * @internal
+ */
+export declare function initialFocusTarget(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily): HTMLElement;
+/**
+ * Places initial focus for a native `<dialog>` after `showModal()`: the selector's match, then the family's own
+ * default target, else — unless the platform already focused inside the panel — the first tabbable, then the panel itself.
+ * @internal
+ */
+export declare function applyInitialFocus(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily): void;
+/**
+ * Sends focus where finalFocus names, resolved at document level (panel is
+ * closing and the opening element may be gone). Returns whether focus was placed.
+ * @internal
+ */
+export declare function applyFinalFocus(selector: string | undefined, family: FocusTargetFamily): boolean;
+/**
+ * The open-time focus move under its veto: `open-auto-focus` fires *before*
+ * anything moves, so a consumer preventing it keeps focus where the user left
+ * it. A native `<dialog>` is the exception — `showModal()` has already moved
+ * focus into the panel by the time any handler can run, so a veto has to put it
+ * back rather than merely decline to move it. A veto that places focus itself is the
+ * documented way to take initial focus over, so that undo only runs when the handler
+ * left focus where the platform put it.
+ *
+ * @param content the overlay panel
+ * @param selector the `initialFocus` selector, or `undefined` for the default chain
+ * @param family which overlay family, for the console warning a missed selector prints
+ * @param handler the consumer's `open-auto-focus` handler
+ * @param previouslyFocused what had focus before the platform moved it, for the undo
+ * @returns whether focus was placed inside the panel
+ * @internal
+ */
+export declare function applyOpenAutoFocus(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily, handler?: (event: AutoFocusEvent) => void, previouslyFocused?: HTMLElement | null): boolean;
+/**
+ * The close-time focus return, run on every close route (Escape, outside press,
+ * the close button, a controlled `open` flipping) so focus never strands on a
+ * panel that is going away. `close-auto-focus` fires *before* the move, and a
+ * veto leaves focus alone; otherwise `finalFocus` wins, and the element that
+ * opened the overlay is the fallback — skipped when it has left the document,
+ * since focusing a detached node silently drops focus onto `<body>`, and skipped
+ * when it *is* `<body>` or `<html>`, which means nothing was focused when the
+ * overlay opened rather than that the page root should take focus.
+ *
+ * @param selector the `finalFocus` selector, or `undefined` to go straight to the opener
+ * @param family which overlay family, for the console warning a missed selector prints
+ * @param opener the element focused before the overlay opened
+ * @param handler the consumer's `close-auto-focus` handler
+ * @returns whether focus was placed
+ * @internal
+ */
+export declare function returnFocus(selector: string | undefined, family: FocusTargetFamily, opener: HTMLElement | null | undefined, handler?: (event: AutoFocusEvent) => void): boolean;

package/dist/utils/focus-targets.js

@@ -0,0 +1 @@
+import{TABBABLE_SELECTOR as e}from"./tabbable.js";import{autoFocusEvent as t}from"./dismissal.js";var n={Dialog:"the Cancel button when present, then the first tabbable element, then the panel itself",Drawer:"the first tabbable element, then the panel itself",Popover:"the first tabbable element, then the panel itself"},o={Dialog:"[data-skdx-dialog-cancel]"},l={Dialog:"the dialog panel",Drawer:"the drawer panel",Popover:"the popover panel"};function a(e,t,o,a){if(!t)return null;let c;try{c=e.querySelector(t)}catch{return console.warn(`[skdx] ${a}: ${o}="${t}" is not a valid CSS selector. Falling back to the default focus target.`),null}return c||console.warn("initialFocus"===o?`[skdx] ${a}: initialFocus="${t}" matched no element inside ${l[a]}. Falling back to ${n[a]}.`:`[skdx] ${a}: finalFocus="${t}" matched no element in the document. Falling back to the element that was focused before it opened.`),c}function c(t,n,l){const c=a(t,n,"initialFocus",l)??function(e,t){const n=o[t];return n?e.querySelector(n):null}(t,l);if(c)return void c.focus({preventScroll:!0});if(t.contains(document.activeElement))return;const r=t.querySelector(e)??t;r===t&&t.tabIndex<0&&(t.tabIndex=-1),r.focus?.({preventScroll:!0})}function r(e,t){const n=a(document,e,"finalFocus",t);return!!n&&(n.focus({preventScroll:!0}),!0)}function s(e,n,o,l,a){const r=document.activeElement;return t("open-auto-focus",l)?(c(e,n,o),!0):(document.activeElement===r&&a?.isConnected&&e.contains(r)&&a.focus({preventScroll:!0}),!1)}function u(e,n,o,l){return!(!t("close-auto-focus",l)||!r(e,n)&&(!o?.isConnected||o===document.body||o===document.documentElement||(o.focus({preventScroll:!0}),0)))}export{r as applyFinalFocus,c as applyInitialFocus,s as applyOpenAutoFocus,a as resolveFocusSelector,u as returnFocus};

package/dist/utils/format-file-size.cjs

@@ -0,0 +1 @@
+var i=["byte","kilobyte","megabyte","gigabyte","terabyte"];function r(a,n){let t=a,e=0;for(;t>=1e3&&e<i.length-1;)t/=1e3,e+=1;return new Intl.NumberFormat(n,{style:"unit",unit:i[e],unitDisplay:"narrow",maximumFractionDigits:1}).format(t)}exports.formatFileSize=r;

package/dist/utils/format-file-size.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Formats a byte count as short, localised, readable text — `999B`, `1.5kB`,
+ * `1.2MB` — for a FileUpload file row.
+ *
+ * @param bytes - A `File.size`, in bytes.
+ * @param locale - BCP 47 tag, or omitted for the runtime's own locale.
+ * @returns The formatted size, e.g. `'1.5kB'`.
+ */
+export declare function formatFileSize(bytes: number, locale?: string): string;

package/dist/utils/format-file-size.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Formats a byte count as short, localised, readable text — `999B`, `1.5kB`,
+ * `1.2MB` — for a FileUpload file row.
+ *
+ * @param bytes - A `File.size`, in bytes.
+ * @param locale - BCP 47 tag, or omitted for the runtime's own locale.
+ * @returns The formatted size, e.g. `'1.5kB'`.
+ */
+export declare function formatFileSize(bytes: number, locale?: string): string;

package/dist/utils/format-file-size.js

@@ -0,0 +1 @@
+var t=["byte","kilobyte","megabyte","gigabyte","terabyte"];function e(e,i){let r=e,a=0;for(;r>=1e3&&a<t.length-1;)r/=1e3,a+=1;return new Intl.NumberFormat(i,{style:"unit",unit:t[a],unitDisplay:"narrow",maximumFractionDigits:1}).format(r)}export{e as formatFileSize};

package/dist/utils/glyph-data.cjs

@@ -0,0 +1 @@
+var h=1.5,l=(r,e="0 0 16 16")=>({viewBox:e,d:r,fill:!1}),M=(r,e="0 0 16 16")=>({viewBox:e,d:r,fill:!0}),a={check:l("M3 8.5l3 3 7-7"),dash:l("M4 8h8"),close:l("M4 4l8 8M12 4l-8 8"),dot:M("M8 5a3 3 0 1 0 0 6 3 3 0 1 0 0-6z"),star:M("M10 1.5l2.6 5.6 6.1.7-4.5 4.2 1.2 6-5.4-3-5.4 3 1.2-6-4.5-4.2 6.1-.7z","0 0 20 20"),"chevron-down":l("M4 6l4 4 4-4"),"chevron-right":l("M6 4l4 4-4 4"),"chevron-left":l("M10 4l-4 4 4 4"),"arrow-right":l("M3 8h10M9 4l4 4-4 4"),"arrow-left":l("M13 8H3M7 4L3 8l4 4"),"chevrons-right":l("M3 4l4 4-4 4M9 4l4 4-4 4"),"chevrons-left":l("M13 4L9 8l4 4M7 4L3 8l4 4"),play:M("M5 3.5l7 4.5-7 4.5z"),pause:M("M4.5 3h2.5v10H4.5zM9 3h2.5v10H9z")};exports.GLYPHS=a;exports.GLYPH_STROKE_WIDTH=h;

package/dist/utils/glyph-data.d.cts

@@ -0,0 +1,13 @@
+/** A built-in glyph name. */
+export type GlyphName = 'check' | 'dash' | 'close' | 'dot' | 'star' | 'chevron-down' | 'chevron-right' | 'chevron-left' | 'arrow-right' | 'arrow-left' | 'chevrons-right' | 'chevrons-left' | 'play' | 'pause';
+/** The shape behind a {@link GlyphName}. */
+export interface Glyph {
+    viewBox: string;
+    d: string;
+    /** Filled with currentColor rather than stroked. */
+    fill: boolean;
+}
+/** Stroke width every stroked glyph is drawn at. */
+export declare const GLYPH_STROKE_WIDTH = 1.5;
+/** Every built-in glyph, keyed by name. */
+export declare const GLYPHS: Record<GlyphName, Glyph>;

package/dist/utils/glyph-data.d.ts

@@ -0,0 +1,13 @@
+/** A built-in glyph name. */
+export type GlyphName = 'check' | 'dash' | 'close' | 'dot' | 'star' | 'chevron-down' | 'chevron-right' | 'chevron-left' | 'arrow-right' | 'arrow-left' | 'chevrons-right' | 'chevrons-left' | 'play' | 'pause';
+/** The shape behind a {@link GlyphName}. */
+export interface Glyph {
+    viewBox: string;
+    d: string;
+    /** Filled with currentColor rather than stroked. */
+    fill: boolean;
+}
+/** Stroke width every stroked glyph is drawn at. */
+export declare const GLYPH_STROKE_WIDTH = 1.5;
+/** Every built-in glyph, keyed by name. */
+export declare const GLYPHS: Record<GlyphName, Glyph>;

package/dist/utils/glyph-data.js

@@ -0,0 +1 @@
+var l=1.5,M=(l,M="0 0 16 16")=>({viewBox:M,d:l,fill:!1}),r=(l,M="0 0 16 16")=>({viewBox:M,d:l,fill:!0}),e={check:M("M3 8.5l3 3 7-7"),dash:M("M4 8h8"),close:M("M4 4l8 8M12 4l-8 8"),dot:r("M8 5a3 3 0 1 0 0 6 3 3 0 1 0 0-6z"),star:r("M10 1.5l2.6 5.6 6.1.7-4.5 4.2 1.2 6-5.4-3-5.4 3 1.2-6-4.5-4.2 6.1-.7z","0 0 20 20"),"chevron-down":M("M4 6l4 4 4-4"),"chevron-right":M("M6 4l4 4-4 4"),"chevron-left":M("M10 4l-4 4 4 4"),"arrow-right":M("M3 8h10M9 4l4 4-4 4"),"arrow-left":M("M13 8H3M7 4L3 8l4 4"),"chevrons-right":M("M3 4l4 4-4 4M9 4l4 4-4 4"),"chevrons-left":M("M13 4L9 8l4 4M7 4L3 8l4 4"),play:r("M5 3.5l7 4.5-7 4.5z"),pause:r("M4.5 3h2.5v10H4.5zM9 3h2.5v10H9z")};export{e as GLYPHS,l as GLYPH_STROKE_WIDTH};

package/dist/utils/id.d.cts

@@ -1,11 +1,4 @@
-/**
- * @internal Vue's `useId()` if available (3.5+), else undefined. Only valid
- * during `setup()`.
- */
+/** @internal Vue's `useId()` if available (3.5+), else undefined; only valid during `setup()`. */
 export declare function stableUid(): string | undefined;
-/**
- * @internal Generates a unique id like `skdx-<prefix>-<n>` for internal DOM
- * wiring. Must be called during `setup()`. Uses Vue 3.5's `useId()` when
- * available for SSR stability; falls back to module counter for 3.3/3.4.
- */
+/** @internal Generates a unique id like `skdx-<prefix>-<n>` for internal DOM wiring; must be called during `setup()`. */
 export declare function nextId(prefix: string): string;

package/dist/utils/id.d.ts

@@ -1,11 +1,4 @@
-/**
- * @internal Vue's `useId()` if available (3.5+), else undefined. Only valid
- * during `setup()`.
- */
+/** @internal Vue's `useId()` if available (3.5+), else undefined; only valid during `setup()`. */
 export declare function stableUid(): string | undefined;
-/**
- * @internal Generates a unique id like `skdx-<prefix>-<n>` for internal DOM
- * wiring. Must be called during `setup()`. Uses Vue 3.5's `useId()` when
- * available for SSR stability; falls back to module counter for 3.3/3.4.
- */
+/** @internal Generates a unique id like `skdx-<prefix>-<n>` for internal DOM wiring; must be called during `setup()`. */
 export declare function nextId(prefix: string): string;

package/dist/utils/injectRequired.cjs

@@ -0,0 +1 @@
+let n=require("vue");function i(r,t){const e=(0,n.inject)(r);if(!e)throw new Error(t);return e}exports.injectRequired=i;

package/dist/utils/injectRequired.d.cts

@@ -0,0 +1,8 @@
+import { type InjectionKey } from 'vue';
+/**
+ * @internal Injects a context a part cannot work without, throwing `message` when the part renders outside its root.
+ *
+ * @param key the injection key its root provides
+ * @param message the error thrown when nothing provided that key
+ */
+export declare function injectRequired<T>(key: InjectionKey<T>, message: string): T;

package/dist/utils/injectRequired.d.ts

@@ -0,0 +1,8 @@
+import { type InjectionKey } from 'vue';
+/**
+ * @internal Injects a context a part cannot work without, throwing `message` when the part renders outside its root.
+ *
+ * @param key the injection key its root provides
+ * @param message the error thrown when nothing provided that key
+ */
+export declare function injectRequired<T>(key: InjectionKey<T>, message: string): T;

package/dist/utils/injectRequired.js

@@ -0,0 +1 @@
+import{inject as r}from"vue";function e(e,t){const n=r(e);if(!n)throw new Error(t);return n}export{e as injectRequired};

package/dist/utils/liveAnnouncer.cjs

@@ -1 +1 @@
-var u=150,a="position:absolute;border:0;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;word-wrap:normal;",r=new Map;function d(n){const o=r.get(n);if(o?.node.isConnected)return o;const e=document.createElement("div");e.setAttribute("aria-live",n),e.setAttribute("aria-atomic","true"),e.setAttribute("data-skdx-live-announcer",n),e.style.cssText=a,document.body.appendChild(e);const t={node:e,timer:void 0};return r.set(n,t),t}function i(n,o="polite"){if(typeof document>"u")return;const e=n.trim();if(!e)return;const t=d(o);clearTimeout(t.timer),t.timer=setTimeout(()=>{t.timer=void 0,t.node.textContent!==e&&(t.node.textContent=e)},150)}function c(n){for(const[o,e]of r)n!==void 0&&o!==n||(clearTimeout(e.timer),e.timer=void 0,e.node.textContent="")}var m={announce:i,clear:c};function s(){return m}exports.ANNOUNCE_DEBOUNCE_MS=u;exports.announce=i;exports.clearAnnouncements=c;exports.useLiveAnnouncer=s;
+const c=require("./announcer.cjs");var u=new c.Announcer;function a(){const n=document.querySelectorAll("dialog[open]"),e=n[n.length-1]??document.body;for(const o of document.querySelectorAll("[data-skdx-live-announcer]"))o.parentElement!==e&&e.append(o)}function r(n,e="polite"){u.announce(n,e),typeof document<"u"&&a()}function t(n){u.clear(n)}var i={announce:r,clear:t};function l(){return i}exports.ANNOUNCE_DEBOUNCE_MS=c.ANNOUNCE_DEBOUNCE_MS;exports.announce=r;exports.clearAnnouncements=t;exports.useLiveAnnouncer=l;

package/dist/utils/liveAnnouncer.d.cts

@@ -1,11 +1,7 @@
-/** Which of the two singleton live regions a message is routed to. */
-export type AnnouncePoliteness = 'polite' | 'assertive';
-/** Debounce delay; collapses bursts (e.g., keystroke filtering) into one announcement. */
-export declare const ANNOUNCE_DEBOUNCE_MS = 150;
+import { type AnnouncePoliteness } from './announcer.cjs';
+export { ANNOUNCE_DEBOUNCE_MS, type AnnouncePoliteness } from './announcer.cjs';
 /**
- * Announces message to screen readers via aria-live region (polite or assertive).
- * Debounced, deduplicated (last message in burst wins), skips duplicates and
- * empty text. No-op during SSR.
+ * Announces a message to screen readers via a debounced aria-live region (polite or assertive), debounced to the last message of a burst; a repeat is re-announced, empty text is skipped.
  * @example
  * ```ts
  * announce(`${results.length} results`);
@@ -13,10 +9,7 @@ export declare const ANNOUNCE_DEBOUNCE_MS = 150;
  * ```
  */
 export declare function announce(message: string, politeness?: AnnouncePoliteness): void;
-/**
- * Clear region(s); pass politeness to clear only one. Useful between tests and
- * when navigating away from the message's context.
- */
+/** Clears the live region(s); pass `politeness` to clear only one. */
 export declare function clearAnnouncements(politeness?: AnnouncePoliteness): void;
 /** What {@link useLiveAnnouncer} returns. */
 export interface LiveAnnouncerApi {
@@ -26,8 +19,7 @@ export interface LiveAnnouncerApi {
     clear: (politeness?: AnnouncePoliteness) => void;
 }
 /**
- * Composable form of announce. Returns stable { announce, clear } pair.
- * No per-component state (process-wide singletons); safe outside setup().
+ * Composable form of {@link announce}; returns a stable `{ announce, clear }` pair safe to call outside `setup()`.
  * @example
  * ```ts
  * const { announce } = useLiveAnnouncer();

package/dist/utils/liveAnnouncer.d.ts

@@ -1,11 +1,7 @@
-/** Which of the two singleton live regions a message is routed to. */
-export type AnnouncePoliteness = 'polite' | 'assertive';
-/** Debounce delay; collapses bursts (e.g., keystroke filtering) into one announcement. */
-export declare const ANNOUNCE_DEBOUNCE_MS = 150;
+import { type AnnouncePoliteness } from './announcer.js';
+export { ANNOUNCE_DEBOUNCE_MS, type AnnouncePoliteness } from './announcer.js';
 /**
- * Announces message to screen readers via aria-live region (polite or assertive).
- * Debounced, deduplicated (last message in burst wins), skips duplicates and
- * empty text. No-op during SSR.
+ * Announces a message to screen readers via a debounced aria-live region (polite or assertive), debounced to the last message of a burst; a repeat is re-announced, empty text is skipped.
  * @example
  * ```ts
  * announce(`${results.length} results`);
@@ -13,10 +9,7 @@ export declare const ANNOUNCE_DEBOUNCE_MS = 150;
  * ```
  */
 export declare function announce(message: string, politeness?: AnnouncePoliteness): void;
-/**
- * Clear region(s); pass politeness to clear only one. Useful between tests and
- * when navigating away from the message's context.
- */
+/** Clears the live region(s); pass `politeness` to clear only one. */
 export declare function clearAnnouncements(politeness?: AnnouncePoliteness): void;
 /** What {@link useLiveAnnouncer} returns. */
 export interface LiveAnnouncerApi {
@@ -26,8 +19,7 @@ export interface LiveAnnouncerApi {
     clear: (politeness?: AnnouncePoliteness) => void;
 }
 /**
- * Composable form of announce. Returns stable { announce, clear } pair.
- * No per-component state (process-wide singletons); safe outside setup().
+ * Composable form of {@link announce}; returns a stable `{ announce, clear }` pair safe to call outside `setup()`.
  * @example
  * ```ts
  * const { announce } = useLiveAnnouncer();

package/dist/utils/liveAnnouncer.js

@@ -1 +1 @@
-var e=150,t=/* @__PURE__ */new Map;function n(e,n="polite"){if(typeof document>"u")return;const o=e.trim();if(!o)return;const i=function(e){const n=t.get(e);if(n?.node.isConnected)return n;const o=document.createElement("div");o.setAttribute("aria-live",e),o.setAttribute("aria-atomic","true"),o.setAttribute("data-skdx-live-announcer",e),o.style.cssText="position:absolute;border:0;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;word-wrap:normal;",document.body.appendChild(o);const i={node:o,timer:void 0};return t.set(e,i),i}(n);clearTimeout(i.timer),i.timer=setTimeout(()=>{i.timer=void 0,i.node.textContent!==o&&(i.node.textContent=o)},150)}function o(e){for(const[n,o]of t)void 0!==e&&n!==e||(clearTimeout(o.timer),o.timer=void 0,o.node.textContent="")}var i={announce:n,clear:o};function r(){return i}export{e as ANNOUNCE_DEBOUNCE_MS,n as announce,o as clearAnnouncements,r as useLiveAnnouncer};
+import{ANNOUNCE_DEBOUNCE_MS as n,Announcer as e}from"./announcer.js";var o=new e;function c(n,e="polite"){o.announce(n,e),typeof document<"u"&&function(){const n=document.querySelectorAll("dialog[open]"),e=n[n.length-1]??document.body;for(const n of document.querySelectorAll("[data-skdx-live-announcer]"))n.parentElement!==e&&e.append(n)}()}function t(n){o.clear(n)}var a={announce:c,clear:t};function u(){return a}export{n as ANNOUNCE_DEBOUNCE_MS,c as announce,t as clearAnnouncements,u as useLiveAnnouncer};

package/dist/utils/measure-auto-resize.cjs

@@ -0,0 +1 @@
+function a(i,s,d){const t=getComputedStyle(i),e=r=>parseFloat(r)||0,g=e(t.borderTopWidth)+e(t.borderBottomWidth),h=e(t.paddingTop)+e(t.paddingBottom),l=t.boxSizing==="border-box",n=e(t.lineHeight),u=r=>r*n+(l?h+g:0);i.style.height="auto";let o=i.scrollHeight+(l?g:-h);return d!=null&&n>0&&(o=Math.max(o,u(d))),s!=null&&n>0&&(o=Math.min(o,u(s))),o}exports.measureAutoResizeHeight=a;

package/dist/utils/measure-auto-resize.d.cts

@@ -0,0 +1,5 @@
+/**
+ * Returns the pixel height an auto-resizing `<textarea>` should be given so it
+ * shows all of its content, floored at `minRows` and capped to `maxRows`.
+ */
+export declare function measureAutoResizeHeight(node: HTMLTextAreaElement, maxRows?: number, minRows?: number): number;

package/dist/utils/measure-auto-resize.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns the pixel height an auto-resizing `<textarea>` should be given so it
+ * shows all of its content, floored at `minRows` and capped to `maxRows`.
+ */
+export declare function measureAutoResizeHeight(node: HTMLTextAreaElement, maxRows?: number, minRows?: number): number;

package/dist/utils/measure-auto-resize.js

@@ -0,0 +1 @@
+function t(t,e,o){const i=getComputedStyle(t),r=t=>parseFloat(t)||0,l=r(i.borderTopWidth)+r(i.borderBottomWidth),n=r(i.paddingTop)+r(i.paddingBottom),a="border-box"===i.boxSizing,d=r(i.lineHeight),h=t=>t*d+(a?n+l:0);t.style.height="auto";let g=t.scrollHeight+(a?l:-n);return null!=o&&d>0&&(g=Math.max(g,h(o))),null!=e&&d>0&&(g=Math.min(g,h(e))),g}export{t as measureAutoResizeHeight};

package/dist/utils/mentions.cjs

@@ -0,0 +1,2 @@
+var a=/[\p{L}\p{N}_]/u;function h(t){return t===void 0?["@"]:typeof t=="string"?[...t]:t}function d(t,e,i={}){const{allowedSpaces:n=0,requireWordBoundary:o=!0}=i,c=h(i.triggers),u=Math.max(0,Math.min(e,t.length));let f=0;for(let r=u-1;r>=0;r--){const s=t[r];if(s===`
+`||s==="\r")return null;if(c.includes(s)){const l=r>0?t[r-1]:"";return o&&l!==""&&a.test(l)?null:{trigger:s,query:t.slice(r+1,u),start:r,end:u}}if(/\s/.test(s)&&++f>n)return null}return null}function g(t,e){return t!==null&&t.start===e}function p(t,e,i,n=!0){const o=t.slice(e.end),c=n&&!/^\s/.test(o)?" ":"";return{value:t.slice(0,e.start)+i+c+o,caret:e.start+i.length+c.length}}function M(t,e){return{getBoundingClientRect:()=>{const n=t();return{x:n.left,y:n.top,top:n.top,left:n.left,bottom:n.top+n.height,right:n.left,width:0,height:n.height}},contextElement:e}}exports.caretAnchor=M;exports.findMentionToken=d;exports.insertMention=p;exports.isMentionDismissed=g;

package/dist/utils/mentions.d.cts

@@ -0,0 +1,116 @@
+/** The trigger character a Mentions field uses when it configures none. */
+export declare const DEFAULT_MENTION_TRIGGER = "@";
+/** The mention being typed: its trigger character, the text after it, and the range the pair occupies. */
+export interface MentionToken {
+    /** The trigger character that opened the token. */
+    trigger: string;
+    /** Text between the trigger character and the caret — what the item list is filtered by. */
+    query: string;
+    /** Offset of the trigger character in the field value. */
+    start: number;
+    /** Offset just past the query; always the caret offset the token was found at. */
+    end: number;
+}
+/** Where a trigger character is allowed to open a token, and what abandons one. */
+export interface MentionTokenOptions {
+    /**
+     * Trigger characters, either as an array or as one string read a character at a time.
+     * @defaultValue `'@'`
+     */
+    triggers?: string | readonly string[] | undefined;
+    /**
+     * How many spaces a query may contain before the token is abandoned.
+     * @defaultValue 0
+     */
+    allowedSpaces?: number | undefined;
+    /**
+     * Whether a trigger opens a token only at the start of the value or after a non-word character, so `user@example` is left alone.
+     * @defaultValue true
+     */
+    requireWordBoundary?: boolean | undefined;
+}
+/**
+ * The mention token the caret sits in, found by scanning backwards from the
+ * caret to the nearest trigger character.
+ *
+ * Returns `null` for every condition that ends a mention: no trigger before
+ * the caret, a line break between them, more spaces than `allowedSpaces`, a
+ * trigger that fails the word-boundary rule, or a caret that has moved out of
+ * the token. There is no token to cancel — call this again after every value,
+ * caret or selection change and the answer is the whole state.
+ *
+ * @param value the field's full text
+ * @param caret the caret offset, clamped into the value
+ * @param options the trigger and boundary rules
+ */
+export declare function findMentionToken(value: string, caret: number, options?: MentionTokenOptions): MentionToken | null;
+/**
+ * Whether an Escape recorded at `dismissedAt` still suppresses this token.
+ *
+ * Escape closes the popup while the token is still syntactically alive, so the
+ * offset of the dismissed trigger is held until {@link findMentionToken}
+ * returns `null` — which is the adapter's cue to forget it.
+ *
+ * @param token the token found for the current caret, or `null`
+ * @param dismissedAt the `start` of the token Escape closed, or `null`
+ */
+export declare function isMentionDismissed(token: MentionToken | null, dismissedAt: number | null): boolean;
+/** The field value and caret offset an insertion produces. */
+export interface MentionInsertion {
+    /** The whole field value with the token's range replaced. */
+    value: string;
+    /** Caret offset just past the inserted text, and past the appended space when one was added. */
+    caret: number;
+}
+/**
+ * Replaces a token's range with the serialized mention text.
+ *
+ * @param value the field value the token was found in
+ * @param token the token being replaced, from {@link findMentionToken}
+ * @param text the full replacement including the trigger character
+ * @param appendSpace whether a single space follows the mention, skipped when the value already continues with whitespace
+ */
+export declare function insertMention(value: string, token: MentionToken, text: string, appendSpace?: boolean): MentionInsertion;
+/** The caret's position in viewport coordinates, as an adapter measured it. */
+export interface CaretRect {
+    /** Distance in pixels from the viewport's top edge to the caret's top. */
+    top: number;
+    /** Distance in pixels from the viewport's left edge to the caret. */
+    left: number;
+    /** The caret's height in pixels, normally the field's computed line height. */
+    height: number;
+}
+/** The rectangle floating-ui reads off a positioning reference. */
+export interface AnchorRect {
+    x: number;
+    y: number;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+    width: number;
+    height: number;
+}
+/** A positioning reference that is a rectangle rather than an element. */
+export interface VirtualAnchor {
+    getBoundingClientRect(): AnchorRect;
+    /** The element the rect lives inside, so floating-ui can observe ancestor scroll and resize. */
+    contextElement: Element;
+}
+/**
+ * Wraps a caret measurement as the zero-width virtual anchor the popup is
+ * positioned against.
+ *
+ * The measurement is re-read on every call, so one anchor survives a moved
+ * caret without being rebuilt, and `contextElement` is what lets floating-ui
+ * observe the ancestor scroll and resize that make it re-read.
+ *
+ * @param measure re-reads the caret rectangle, normally closing over a {@link MeasureCaretRect}, its field and the offset
+ * @param contextElement the field the caret sits in
+ */
+export declare function caretAnchor(measure: () => CaretRect, contextElement: Element): VirtualAnchor;
+/**
+ * The caret measurement each adapter implements with its own DOM work: the
+ * viewport rectangle of the caret at `offset` inside `field`.
+ */
+export type MeasureCaretRect = (field: HTMLTextAreaElement | HTMLInputElement, offset: number) => CaretRect;