import type{LitElement}from'lit';import{attachInternalsSafely,createFallbackInternals}from'./element-internals.js';import{getFormOwner,installCustomErrorProperty,setFormOwner,type FormOwnerValue}from'./direct-form-associated.js';export{attachInternalsSafely,createFallbackInternals};export{getFormOwner,installCustomErrorProperty,setFormOwner,type FormOwnerValue,};type Constructor<T> =new(...args:any[])=>T;
/**
* Builds the session-history/autofill state for a control whose public value is a string array.
* The state is private to one FACE control, so its key only needs to remain self-consistent; using
* the current submission name keeps direct callback tests and browser diagnostics intuitive while
* the reader below intentionally treats the entries as name-independent.
*/
export declare function createStringArrayFormDataState(name:string,values:readonly string[]):FormData;
/**
* Reads a string-array FACE state without depending on the control's current `name`. A form owner
* can rename a control between persistence and restoration; the browser still restores the state
* that belongs to that element. Wrong state shapes fail closed to an empty value.
*/
export declare function readStringArrayFormDataState(state:string|File|FormData|null):string[];
/**
* What `ElementInternals.setFormValue()` accepts for both the submission entry and the
* session-history/autofill state.
*/
export type FormSubmissionValue=File|string|FormData|null;
/**
* The seam that lets {@linkcode FormAssociated} carry a value of any type.
*
* The mixin owns the *behaviour* (synchronous accessors, dirty/default tracking, the interaction
* signal, barred-validation short-circuiting, anchored validity layering, reset and state
* restoration); an adapter supplies only the type-dependent facts the behaviour needs — what
* "empty" is, how the value reaches `setFormValue()`, whether a given value counts as missing, and
* how it round-trips through the reflected `value` content attribute. Every member except
* {@linkcode empty} and {@linkcode toFormValue} has a documented default, so the smallest useful
* adapter is two lines.
*
* Without this seam a control whose value is not a string had no choice but to hand-roll the entire
* `ElementInternals` dance, which is why dirty/default tracking was copy-pasted four different ways
* and `formResetCallback` was simply missing from one control: the duplication, not any one file,
* was the defect.
*/
export interface FormValueAdapter<TValue>{
/**
* The value of a control that has never been assigned one, the value a form reset falls back to
* when no `value` attribute is present, and the substitute for a `null`/`undefined` assignment.
*
* Handed to every instance by reference, so it must be treated as immutable — freeze an array or
* object empty value rather than letting one instance's mutation reach every other.
*/
readonly empty:TValue;
/**
* Serializes the live value into the entry the owning `<form>` submits. Returning `null` omits
* the control from `FormData` entirely, exactly as an unchecked native checkbox does.
*/
toFormValue(value:TValue):FormSubmissionValue;
/**
* Serializes the session-history/autofill state, when it must differ from the submission entry —
* an unchecked checkbox submits nothing but still has to *restore* as unchecked, and a
* multi-valued control submits one entry per value but restores from a single `FormData`
* ({@linkcode createStringArrayFormDataState} builds that shape).
*
* Omitted entirely means "the state is the submission value", which is `setFormValue()`'s own
* one-argument behaviour — not the same as returning `null`, which would erase the state.
*/
toFormState?(value:TValue):FormSubmissionValue;
/**
* Whether this value counts as missing for `valueMissing`. Defaults to
* {@linkcode isEmptyFormValue}, which is `=== ''` for a string and never assumes it for anything
* else. Override it whenever the default is wrong for the type — a `0`-valued rating is empty,
* an epoch `Date` is not.
*/
isEmpty?(value:TValue):boolean;
/**
* Parses the reflected `value` content attribute (never `null` — an absent attribute is handled
* by the mixin and does not reach here). Defaults to the identity, which is only correct when
* `TValue` is `string`; any other type must supply one or its declarative markup is ignored.
*/
fromAttribute?(attribute:string):TValue;
/**
* Serializes the reset default back to the `value` content attribute. Returning `null` removes
* the attribute. Defaults to `String(value)`, which is only meaningful when `TValue` is `string`.
*/
toAttribute?(value:TValue):string|null;
/**
* Reads back what {@linkcode toFormState} (or {@linkcode toFormValue}) persisted, for
* `formStateRestoreCallback`. Defaults to "a string state restores verbatim, anything else falls
* back to {@linkcode empty}" — the string mixin's long-standing behaviour, which fails closed
* rather than restoring a wrongly-shaped state.
*/
fromFormState?(state:FormSubmissionValue):TValue;}
/** An adapter with every optional member resolved, so the mixin never branches on `undefined`. */
type ResolvedFormValueAdapter<TValue> =Required<Omit<FormValueAdapter<TValue>,'toFormState'>> &Pick<FormValueAdapter<TValue>,'toFormState'>;
/**
* The default `valueMissing` emptiness test: `null`/`undefined`, the empty string, an empty array,
* and an empty plain object are missing; everything else — including `0`, `false`, a `Date`, a
* `File`, and any class instance — is a real value.
*
* Deliberately conservative about objects: only a *plain* object is inspected by key count, because
* `Object.keys()` reports `0` for a populated `FormData`, `Map` or `Set` and would silently call a
* filled-in control empty. Reflection is guarded because this is a public helper and the default
* adapter path accepts consumer-defined values: a revoked or hostile Proxy is a real, non-empty
* value rather than permission to abort the control's validation/update transaction.
*/
export declare function isEmptyFormValue(value:unknown):boolean;
/**
* The string adapter — the mixin's default, and a byte-for-byte statement of the behaviour every
* existing consumer already has. Exported so a control that wraps or extends the string contract
* can spread it rather than restating it.
*/
export declare const stringFormValueAdapter:ResolvedFormValueAdapter<string>;
/**
* The shape {@linkcode isBarredFromValidation} reads. Every member is optional because the same
* predicate answers for the mixin and for the eighteen controls that drive `ElementInternals`
* directly, and those differ in which barring conditions they can even express (`<lr-checkbox>`
* has no `readonly`, `<lr-rating>` has no fieldset-independent `effectiveDisabled`, and a control
* constructed under a DOM shim has no real `ElementInternals` at all).
*/
export interface ValidationCandidate{
/** Own `disabled` OR any inherited disablement (fieldset, owning group). Preferred over `disabled`. */
readonly effectiveDisabled?:boolean;readonly disabled?:boolean;readonly readonly?:boolean;}
/**
* Whether constraint validation must not run for this control — the single predicate behind every
* "barred from constraint validation" condition, so no control can implement three of the four and
* silently miss the fourth (`<lr-rating required readonly>` reported `valueMissing` while
* `<lr-otp-input required readonly>` did not, because the `readonly` bar was copy-pasted into four
* files and never reached the fifth).
*
* A barred control is neither `:valid` nor `:invalid` natively — verified against a real
* `<input required disabled>` and `<input required readonly>`, both of which match neither — so
* publishing `:state(invalid)`/`:state(user-invalid)` from a disabled required field is what makes
* the documented `lr-input:state(user-invalid) { border-color: red }` rule paint every disabled
* field red.
*
* `internals.willValidate` is consulted last and only for a real `ElementInternals`: it folds in the
* platform conditions this library does not model itself (fieldset cascading, a `<datalist>`
* ancestor), but the `createFallbackInternals()` substitute reports `false` unconditionally, and
* treating that as "barred" would silently disable validation everywhere `attachInternals()` is
* missing.
*/
export declare function isBarredFromValidation(host:ValidationCandidate,internals?:ElementInternals):boolean;
/**
* Public surface a `FormAssociated`-mixed element exposes to consumers and subclasses.
*
* `TValue` defaults to `string`, so every existing reference to the bare
* `FormAssociatedInterface` keeps its exact former meaning.
*/
export interface FormAssociatedInterface<TValue=string>{internals:ElementInternals;get name():string;set name(next:string|null);value:TValue;defaultValue:TValue;customError:string|null;disabled:boolean;required:boolean;readonly effectiveDisabled:boolean;
/** Browser-resolved owner on read; accepts an owner id, form element, or `null` on write. */
get form():HTMLFormElement|null;set form(owner:FormOwnerValue);readonly labels:NodeList;readonly validity:ValidityState;readonly validationMessage:string;readonly willValidate:boolean;setFormValue(next:TValue):void;getForm():HTMLFormElement|null;checkValidity():boolean;reportValidity():boolean;setCustomValidity(message:string):void;resetValidity():void;formResetCallback():void;formStateRestoreCallback(state:FormSubmissionValue,reason:'autocomplete'|'restore'):void;}
/** Subclass-only transaction seam retained in the mixin's explicit constructor return type. */
export declare class FormAssociatedSubclassInterface<TValue=string>{protected captureLiveValueCheckpoint():{readonly value:TValue;readonly dirty:boolean;};protected restoreLiveValueCheckpoint(checkpoint:{readonly value:TValue;readonly dirty:boolean;}):void;}
/**
* Mixin that turns a Lit component into a form-associated custom element via
* `ElementInternals`, so it participates in native `<form>` submission,
* validation, and reset — matching Web Awesome's free form controls.
*
* `value` uses a hand-written accessor (`noAccessor`) so `setFormValue` runs
* synchronously on assignment rather than on the async update cycle.
*
* The value type is a parameter, not a fixture. `FormAssociated(Base)` is the string control every
* existing consumer already has — `TValue` defaults to `string` and the supplied-adapter branches
* below all collapse to the literal code that shipped before. `FormAssociated(Base, adapter)`
* carries any other type through the same one implementation: `Date`, `string[]`, a structured
* record. See {@linkcode FormValueAdapter} for the facts an adapter supplies; everything else
* — the synchronous `noAccessor` accessors, dirty/default tracking, the `input`/`change`/`focusout`
* interaction signal, `isBarredFromValidation()` short-circuiting, anchored intrinsic/custom
* validity layering, `formResetCallback` (restores the default, clears dirty and interacted, and
* deliberately preserves a `setCustomValidity()` message) — is type-independent and is not
* reimplemented per value type.
*
* The explicit return-type annotation is required so TypeScript can emit a
* declaration file for the (otherwise anonymous) mixin class (avoids TS4094).
*/
export declare function FormAssociated<T extends Constructor<LitElement>,TValue=string>(Base:T,valueAdapter?:FormValueAdapter<TValue>):T&Constructor<FormAssociatedInterface<TValue> &FormAssociatedSubclassInterface<TValue>>;