@qw-ui/core 0.3.0-next.40 → 0.3.0-next.42

package/dist/footer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/footer/footer.ts"],"sourcesContent":["import { createMachine, type Machine, type Service } from \"@zag-js/core\";\nimport type { NormalizeProps, PropTypes } from \"@zag-js/types\";\n\n/** Page/section closing area: separator label, links, content text and action chips. */\nexport const FOOTER_PARTS = [\"root\", \"label\", \"links\", \"link-item\", \"link\", \"content\", \"chips\", \"chip\", \"extra\"] as const;\nexport const FOOTER_CHIP_VARIANTS = [\"plain\", \"link\"] as const;\nexport type FooterPart = (typeof FOOTER_PARTS)[number];\nexport type FooterChipVariant = (typeof FOOTER_CHIP_VARIANTS)[number];\n\nexport interface FooterLink {\n  id: string;\n  text: string;\n  href: string;\n  disabled?: boolean;\n  target?: string;\n  rel?: string;\n}\nexport interface FooterChip {\n  id: string;\n  text: string;\n  disabled?: boolean;\n  /** plain: filled pill (default); link: text-style action. */\n  variant?: FooterChipVariant;\n}\nexport interface FooterChipClickDetails { id: string; index: number }\nexport interface FooterLinkClickDetails { id: string; index: number; href?: string }\nexport interface QwFooterProps {\n  /** Separator label text above the footer content. */\n  label?: string;\n  /** Plain footer text such as a copyright line. */\n  content?: string;\n  links?: readonly FooterLink[];\n  chips?: readonly FooterChip[];\n  /** Opt-in page-level contentinfo landmark; default is a plain region. */\n  landmark?: boolean;\n  /** Accessible name of the link list; default \"页脚链接\". */\n  linksLabel?: string;\n  onChipClick?: (details: FooterChipClickDetails) => void;\n  /** Notification only; native navigation is never prevented. */\n  onLinkClick?: (details: FooterLinkClickDetails) => void;\n}\nexport interface ResolvedFooterLink extends FooterLink { index: number; href: string; safeHref?: string; disabled: boolean }\nexport interface ResolvedFooterChip extends FooterChip { index: number; disabled: boolean; variant: FooterChipVariant }\n\nconst SAFE_SCHEMES = new Set([\"http\", \"https\", \"mailto\", \"tel\"]);\n/** Relative URLs and http(s)/mailto/tel are kept; other schemes (javascript:, data:, …) are dropped. */\nexport function sanitizeFooterHref(href: unknown): string | undefined {\n  if (typeof href !== \"string\") return undefined;\n  // eslint-disable-next-line no-control-regex -- C0/DEL characters can hide a scheme from naive checks.\n  const value = href.trim().replace(/[\\x00-\\x1f\\x7f]/g, \"\");\n  if (!value) return undefined;\n  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1]?.toLowerCase();\n  if (scheme) return SAFE_SCHEMES.has(scheme) ? href.trim() : undefined;\n  return href.trim();\n}\nexport function resolveFooterLinks(links: readonly FooterLink[] | undefined): ResolvedFooterLink[] {\n  return (links ?? []).map((link, index) => {\n    const safeHref = sanitizeFooterHref(link.href);\n    return { ...link, index, href: link.href, safeHref, disabled: link.disabled === true || safeHref === undefined };\n  });\n}\nexport function resolveFooterChips(chips: readonly FooterChip[] | undefined): ResolvedFooterChip[] {\n  return (chips ?? []).map((chip, index) => ({ ...chip, index, disabled: chip.disabled === true, variant: FOOTER_CHIP_VARIANTS.includes(chip.variant!) ? chip.variant! : \"plain\" }));\n}\n\nexport interface QwFooterSchema {\n  props: QwFooterProps;\n  context: Record<string, never>;\n  state: \"idle\";\n  action: \"notifyChip\" | \"notifyLink\";\n  event: { type: \"CHIP.CLICK\"; index: number } | { type: \"LINK.CLICK\"; index: number };\n}\nexport type QwFooterMachine = Machine<QwFooterSchema>;\nexport type QwFooterService = Service<QwFooterSchema>;\n\n/** Stateless notification machine so every stack (including WC events) shares one activation path. */\nexport const footerMachine: QwFooterMachine = createMachine<QwFooterSchema>({\n  initialState: () => \"idle\",\n  on: { \"CHIP.CLICK\": { actions: [\"notifyChip\"] }, \"LINK.CLICK\": { actions: [\"notifyLink\"] } },\n  states: { idle: {} },\n  implementations: {\n    actions: {\n      notifyChip({ prop, event }) {\n        if (event.type !== \"CHIP.CLICK\") return;\n        const chip = resolveFooterChips(prop(\"chips\"))[event.index];\n        if (chip && !chip.disabled) prop(\"onChipClick\")?.({ id: chip.id, index: chip.index });\n      },\n      notifyLink({ prop, event }) {\n        if (event.type !== \"LINK.CLICK\") return;\n        const link = resolveFooterLinks(prop(\"links\"))[event.index];\n        if (link && !link.disabled) prop(\"onLinkClick\")?.({ id: link.id, index: link.index, href: link.safeHref });\n      },\n    },\n  },\n});\n\nexport interface QwFooterApi<T extends PropTypes = PropTypes> {\n  label?: string;\n  content?: string;\n  links: ResolvedFooterLink[];\n  chips: ResolvedFooterChip[];\n  getRootProps(): T[\"element\"];\n  getLabelProps(): T[\"element\"];\n  getLinksProps(): T[\"element\"];\n  getLinkItemProps(link: ResolvedFooterLink): T[\"element\"];\n  getLinkProps(link: ResolvedFooterLink): T[\"element\"];\n  getContentProps(): T[\"element\"];\n  getChipsProps(): T[\"element\"];\n  getChipProps(chip: ResolvedFooterChip): T[\"button\"];\n  getExtraProps(): T[\"element\"];\n}\nconst part = (name: FooterPart) => ({ \"data-scope\": \"footer\", \"data-part\": name });\nconst text = (value: unknown) => typeof value === \"string\" && value !== \"\" ? value : undefined;\n\nexport function connectFooter<T extends PropTypes>(service: QwFooterService, normalize: NormalizeProps<T>): QwFooterApi<T> {\n  const label = text(service.prop(\"label\")), content = text(service.prop(\"content\"));\n  const links = resolveFooterLinks(service.prop(\"links\")), chips = resolveFooterChips(service.prop(\"chips\"));\n  return {\n    label, content, links, chips,\n    getRootProps: () => normalize.element({ ...part(\"root\"), ...(service.prop(\"landmark\") ? { role: \"contentinfo\" } : {}) }),\n    getLabelProps: () => normalize.element({ ...part(\"label\"), hidden: label === undefined }),\n    getLinksProps: () => normalize.element({ ...part(\"links\"), hidden: links.length === 0, \"aria-label\": links.length ? text(service.prop(\"linksLabel\")) ?? \"页脚链接\" : undefined }),\n    getLinkItemProps: (link) => normalize.element({ ...part(\"link-item\"), \"data-value\": link.id }),\n    getLinkProps: (link) => normalize.element({ ...part(\"link\"), \"data-value\": link.id,\n      ...(link.disabled ? { \"aria-disabled\": \"true\", \"data-disabled\": \"true\" } : { href: link.safeHref, target: link.target, rel: link.rel ?? (link.target === \"_blank\" ? \"noopener noreferrer\" : undefined) }),\n      onClick() { if (!link.disabled) service.send({ type: \"LINK.CLICK\", index: link.index }); } }),\n    getContentProps: () => normalize.element({ ...part(\"content\"), hidden: content === undefined }),\n    getChipsProps: () => normalize.element({ ...part(\"chips\"), hidden: chips.length === 0 }),\n    getChipProps: (chip) => normalize.button({ ...part(\"chip\"), type: \"button\", disabled: chip.disabled, \"data-value\": chip.id, \"data-variant\": chip.variant,\n      onClick() { service.send({ type: \"CHIP.CLICK\", index: chip.index }); } }),\n    getExtraProps: () => normalize.element(part(\"extra\")),\n  };\n}\n"],"mappings":"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"}

package/dist/form/connect.d.ts

@@ -0,0 +1,6 @@
+import type { NormalizeProps, PropTypes } from "@zag-js/types";
+import { type QwFormService } from "./form.js";
+import type { QwFormApi } from "./types.js";
+export declare const FORM_PARTS: readonly ["root", "label", "content", "error-summary", "error-list", "error-item", "error-link", "footer"];
+/** Public connect. Named connectForm so package barrels do not hide other connects. */
+export declare function connectForm<T extends PropTypes>(service: QwFormService, normalize: NormalizeProps<T>): QwFormApi<T>;

package/dist/form/form.d.ts

@@ -0,0 +1,100 @@
+import { type Machine, type Service } from "@zag-js/core";
+import { type FormNamePath, type QwFormValues, type QwNamePath, type QwFormValue } from "./model.js";
+import { type FormValidationTrigger } from "./rules.js";
+import type { FormCancelReason, FormErrorField, FormFieldState, FormInteractionSnapshot, FormSubmitResult, FormSubmitStatus, FormValidationResult, QwFormFieldDefinition, QwFormProps, QwFormState } from "./types.js";
+interface Request {
+    ticket: number;
+    controller: AbortController;
+}
+type FeedbackKey = "errors" | "touched" | "validated" | "validating";
+type FormFeedback = Pick<QwFormSchema["context"], FeedbackKey>;
+interface KnownField {
+    name: FormNamePath;
+    preserve?: boolean;
+}
+interface FormRuntime {
+    feedback?: FormFeedback;
+    publishingFeedback?: boolean;
+    epoch: number;
+    next: number;
+    alive: boolean;
+    validations: Map<string, Request>;
+    submission?: Request;
+    reason: FormCancelReason;
+    valueHash: string;
+    functions: WeakMap<object, number>;
+    functionCount: number;
+    known: Map<string, KnownField>;
+    blurSeen: Set<string>;
+    suppressUser: boolean;
+    syncNative?: () => void;
+    userEcho?: {
+        key: string;
+        value: string;
+    };
+}
+export interface QwFormSchema {
+    props: QwFormProps & {
+        initialValues: QwFormValues;
+        initialErrors: FormErrorField[];
+        validateTrigger: FormValidationTrigger | FormValidationTrigger[];
+        initialInteraction?: FormInteractionSnapshot;
+    };
+    context: {
+        values: QwFormValues;
+        errors: FormErrorField[];
+        touched: string[];
+        validated: string[];
+        validating: string[];
+        submitStatus: FormSubmitStatus;
+    };
+    refs: {
+        runtime: FormRuntime;
+    };
+    state: "ready";
+    event: {
+        type: "VALUES.SET";
+        values: QwFormValues;
+    };
+    action: "setValues";
+    effect: "lifecycle" | "trackNative";
+}
+export type QwFormService = Service<QwFormSchema>;
+export type QwFormMachine = Machine<QwFormSchema>;
+/** Drop in-flight submit busy. Reconnect cannot resume the old promise. */
+export declare function normalizeFormInteraction(snapshot: FormInteractionSnapshot | undefined): FormInteractionSnapshot | undefined;
+export declare function normalizeFormFields(fields: QwFormFieldDefinition[]): QwFormFieldDefinition[];
+export declare function createFormProps(props: QwFormProps & {
+    initialInteraction?: FormInteractionSnapshot;
+}): QwFormSchema["props"];
+export declare const formMachine: QwFormMachine;
+/** Unknown and disabled choices stay stored but are not fabricated into the submit snapshot. */
+export declare function submittedFieldValue(field: QwFormFieldDefinition, value: QwFormValue | undefined): {
+    include: boolean;
+    value?: QwFormValue;
+};
+/** Headless behavior API; DOM/getter transport is composed separately. */
+export declare function connectFormBehavior(service: QwFormService): {
+    readonly values: QwFormValues;
+    readonly state: QwFormState;
+    getValues: () => QwFormValues;
+    getState: () => QwFormState;
+    getFieldState: (name: QwNamePath) => FormFieldState;
+    getInteractionSnapshot: () => FormInteractionSnapshot;
+    getFieldValue: (name: QwNamePath) => QwFormValue | undefined;
+    setFieldValue: (name: QwNamePath, value: QwFormValue | undefined) => void;
+    setFieldsValue: (patch: QwFormValues) => void;
+    setFieldErrors: (name: QwNamePath, errors: string[]) => void;
+    validateFields: (names?: QwNamePath[], options?: {
+        validateOnly?: boolean;
+        trigger?: FormValidationTrigger;
+    }) => Promise<FormValidationResult>;
+    resetFields: (names?: QwNamePath[]) => void;
+    submit: () => Promise<FormSubmitResult>;
+    cancelSubmit: () => void;
+    changeFieldFromUser: (name: QwNamePath, value: QwFormValue | undefined) => void;
+    blurField: (name: QwNamePath) => void;
+    focusField: (name: QwNamePath) => boolean;
+    initialFieldValue: (name: QwNamePath) => QwFormValue | undefined;
+};
+export {};

package/dist/form/ids.d.ts

@@ -0,0 +1,14 @@
+import { type QwNamePath } from "./model.js";
+/** HTML form id owned by one Core instance. */
+export declare function formDomId(scopeId: string): string;
+/** Accessible name target for the form landmark. */
+export declare function formLabelId(scopeId: string): string;
+/**
+ * Stable field stem. `formFieldKey` is the injective NamePath encoding.
+ * Field root id is `field:` plus this stem.
+ */
+export declare function formFieldStem(scopeId: string, name: QwNamePath): string;
+/** Actual control id shared by Input, selection and raw native inputs. */
+export declare function formControlStem(scopeId: string, name: QwNamePath): string;
+/** Field root id produced by `resolveFieldState`. */
+export declare function formFieldRootId(scopeId: string, name: QwNamePath): string;

package/dist/form/index.d.ts

@@ -0,0 +1,13 @@
+export { FORM_PARTS, connectForm } from "./connect.js";
+export { connectFormBehavior, createFormProps, formMachine, normalizeFormFields, normalizeFormInteraction, submittedFieldValue } from "./form.js";
+export { trackFormNative } from "./native.js";
+export type { FormNativePort } from "./native.js";
+export type { QwFormMachine, QwFormSchema, QwFormService } from "./form.js";
+export { formControlStem, formDomId, formFieldRootId, formFieldStem, formLabelId } from "./ids.js";
+export { cloneFormValue, cloneFormValues, formFieldKey, formFieldNativeName, formValueFingerprint, formValuesEqual, freezeFormValues, getFormValue, hasFormValue, mergeFormValues, normalizeFormNamePath, setFormValue } from "./model.js";
+export type { FormNamePath, QwFormValue, QwFormValues, QwNamePath } from "./model.js";
+export { FORM_DEFAULT_MESSAGES, FORM_MESSAGES_EN, formErrorMessage, isFormEmpty, normalizeFormRule, validateFormRule } from "./rules.js";
+export type { FormMessages, FormRule, FormRuleContext, FormRuleType, FormValidationTrigger } from "./rules.js";
+export { assertFormMethodReady, invokeFormApi } from "./methods.js";
+export { assertFormSsrProps } from "./ssr.js";
+export type { FormCancelReason, FormControlKind, FormErrorField, FormFieldState, FormFieldValidationStatus, FormInputType, FormInteractionSnapshot, FormNormalizer, FormSubmitHandler, FormSubmitResult, FormSubmitStatus, FormValidationResult, QwFormApi, QwFormFieldDefinition, QwFormProps, QwFormState } from "./types.js";

package/dist/form/index.js

@@ -0,0 +1,3 @@
+import { C as setFormValue, S as normalizeFormNamePath, _ as formValuesEqual, b as hasFormValue, f as cloneFormValue, g as formValueFingerprint, h as formFieldNativeName, m as formFieldKey, p as cloneFormValues, v as freezeFormValues, x as mergeFormValues, y as getFormValue } from "../field-DMHGIMZF.js";
+import { C as formLabelId, S as formFieldStem, _ as validateFormRule, a as connectForm, b as formDomId, c as formMachine, d as submittedFieldValue, f as FORM_DEFAULT_MESSAGES, g as normalizeFormRule, h as isFormEmpty, i as FORM_PARTS, l as normalizeFormFields, m as formErrorMessage, n as assertFormMethodReady, o as connectFormBehavior, p as FORM_MESSAGES_EN, r as invokeFormApi, s as createFormProps, t as assertFormSsrProps, u as normalizeFormInteraction, v as trackFormNative, x as formFieldRootId, y as formControlStem } from "../form-BAGkIEMY.js";
+export { FORM_DEFAULT_MESSAGES, FORM_MESSAGES_EN, FORM_PARTS, assertFormMethodReady, assertFormSsrProps, cloneFormValue, cloneFormValues, connectForm, connectFormBehavior, createFormProps, formControlStem, formDomId, formErrorMessage, formFieldKey, formFieldNativeName, formFieldRootId, formFieldStem, formLabelId, formMachine, formValueFingerprint, formValuesEqual, freezeFormValues, getFormValue, hasFormValue, invokeFormApi, isFormEmpty, mergeFormValues, normalizeFormFields, normalizeFormInteraction, normalizeFormNamePath, normalizeFormRule, setFormValue, submittedFieldValue, trackFormNative, validateFormRule };

package/dist/form/methods.d.ts

@@ -0,0 +1,5 @@
+import type { QwFormApi } from "./types.js";
+/** Live Core dispatch for a connected native method. Unknown names throw. */
+export declare function invokeFormApi(api: QwFormApi, method: string, args?: readonly unknown[]): unknown;
+/** Hosts call this before invoke. Disconnected or not-yet-ready calls throw. */
+export declare function assertFormMethodReady(ready: boolean): void;

package/dist/form/model.d.ts

@@ -0,0 +1,24 @@
+/** Finite JSON values form the public value/SSR boundary. */
+export type QwFormValue = string | number | boolean | null | QwFormValue[] | {
+    [key: string]: QwFormValue;
+};
+export type QwFormValues = Record<string, QwFormValue>;
+export type QwNamePath = string | readonly (string | number)[];
+export type FormNamePath = (string | number)[];
+/** Strings are literal single segments, never implicit dot/bracket parsing. */
+export declare function normalizeFormNamePath(name: unknown): FormNamePath;
+export declare function formFieldKey(name: QwNamePath): string;
+export declare function formFieldNativeName(name: QwNamePath): string;
+export declare function cloneFormValue(value: unknown): QwFormValue;
+export declare function cloneFormValues(values?: unknown): QwFormValues;
+/** Fresh recursively frozen validator snapshot; never freeze caller storage. */
+export declare function freezeFormValues(values: QwFormValues): Readonly<QwFormValues>;
+/** Canonical comparison keeps object key order from manufacturing dirty changes. */
+export declare function formValueFingerprint(value: QwFormValue | undefined): string;
+export declare function formValuesEqual(a: QwFormValues, b: QwFormValues | undefined): boolean;
+export declare function getFormValue(values: QwFormValues, name: QwNamePath): QwFormValue | undefined;
+export declare function hasFormValue(values: QwFormValues, name: QwNamePath): boolean;
+/** Immutable path update. Dense arrays retain explicit JSON semantics. */
+export declare function setFormValue(values: QwFormValues, name: QwNamePath, value: QwFormValue | undefined): QwFormValues;
+/** Object recursion, array replacement; all inputs and outputs are independent. */
+export declare function mergeFormValues(values: QwFormValues, patch: QwFormValues): QwFormValues;

package/dist/form/native.d.ts

@@ -0,0 +1,25 @@
+import type { SelectionFormScope } from "../selection-form.js";
+import { type QwFormValue, type QwNamePath } from "./model.js";
+import type { QwFormFieldDefinition } from "./types.js";
+/** DOM port implemented by the Form machine. Adapters do not keep a second controller. */
+export interface FormNativePort {
+    scope: SelectionFormScope & {
+        id?: string;
+    };
+    fields(): readonly QwFormFieldDefinition[];
+    value(name: QwNamePath): QwFormValue | undefined;
+    change(name: QwNamePath, value: QwFormValue | undefined): void;
+    blur(name: QwNamePath): void;
+    reset(): void;
+    suppressUser(active: boolean): void;
+    bindSync(sync: (() => void) | undefined): void;
+}
+/**
+ * One client lifecycle for raw inputs, supported native selection elements,
+ * composite blur, and a single deferred reset transaction.
+ * This listener is the only raw input/change transport. Getter props must not
+ * subscribe to the same event (Vue normalizes onChange into onInput).
+ * Selection controls keep their own reset listeners; user echoes are suppressed
+ * until this transaction finishes so they cannot overwrite the Form reset.
+ */
+export declare function trackFormNative(port: FormNativePort): () => void;

package/dist/form/rules.d.ts

@@ -0,0 +1,40 @@
+import { type FormNamePath, type QwFormValue, type QwFormValues } from "./model.js";
+export type FormValidationTrigger = "change" | "blur" | "submit" | "manual";
+export type FormRuleType = "string" | "number" | "boolean" | "array" | "email" | "url";
+export interface FormRuleContext {
+    name: FormNamePath;
+    label: string;
+    values: Readonly<QwFormValues>;
+    signal: AbortSignal;
+    messages?: Partial<FormMessages>;
+}
+export interface FormRule {
+    required?: boolean;
+    type?: FormRuleType;
+    min?: number;
+    max?: number;
+    length?: number;
+    pattern?: string;
+    flags?: string;
+    enum?: QwFormValue[];
+    message?: string;
+    trigger?: FormValidationTrigger | FormValidationTrigger[];
+    validator?: (value: QwFormValue | undefined, context: FormRuleContext) => boolean | string | void | Promise<boolean | string | void>;
+}
+export interface FormMessages {
+    required: string;
+    type: string;
+    min: string;
+    max: string;
+    length: string;
+    pattern: string;
+    enum: string;
+    validator: string;
+}
+export declare const FORM_DEFAULT_MESSAGES: Readonly<FormMessages>;
+export declare const FORM_MESSAGES_EN: Readonly<FormMessages>;
+export declare function normalizeFormRule(rule: FormRule): FormRule;
+export declare function isFormEmpty(value: QwFormValue | undefined): boolean;
+export declare function formErrorMessage(error: unknown, fallback?: string): string;
+/** One rule returns explicit errors; request ownership is checked by the Form engine. */
+export declare function validateFormRule(input: FormRule, value: QwFormValue | undefined, context: FormRuleContext): Promise<string[]>;

package/dist/form/ssr.d.ts

@@ -0,0 +1,7 @@
+import type { QwFormProps } from "./types.js";
+/**
+ * SSR accepts builtin JSON rules only.
+ * Custom validators and business handlers are runtime values: encountering one throws.
+ * Nothing is eval'd or silently dropped.
+ */
+export declare function assertFormSsrProps(props: QwFormProps): void;

package/dist/form/types.d.ts

@@ -0,0 +1,150 @@
+import type { QwInputProps } from "../input/index.js";
+import type { QwCheckboxProps } from "../checkbox/index.js";
+import type { QwRadioGroupProps } from "../radio-group/index.js";
+import type { QwSegmentedProps, QwSegmentedItem, SegmentedSelectionMode } from "../segmented/index.js";
+import type { QwFieldProps } from "../field/index.js";
+import type { QwFormValue, QwFormValues, QwNamePath, FormNamePath } from "./model.js";
+import type { FormMessages, FormRule, FormValidationTrigger } from "./rules.js";
+import type { NormalizeProps, PropTypes } from "@zag-js/types";
+export type FormControlKind = "native" | "input" | "checkbox" | "radio-group" | "segmented" | "custom";
+export type FormInputType = "text" | "email" | "tel" | "url" | "password" | "search" | "number" | "checkbox";
+export interface QwFormFieldDefinition {
+    name: QwNamePath;
+    label: string;
+    description?: string;
+    controlDescription?: string;
+    nativeName?: string;
+    control?: FormControlKind;
+    inputType?: FormInputType;
+    items?: QwSegmentedItem[];
+    selectionMode?: SegmentedSelectionMode;
+    initialValue?: QwFormValue;
+    rules?: FormRule[];
+    dependencies?: QwNamePath[];
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    preserve?: boolean;
+    validateTrigger?: FormValidationTrigger | FormValidationTrigger[];
+}
+export interface FormErrorField {
+    name: FormNamePath;
+    errors: string[];
+}
+export type FormFieldValidationStatus = "unvalidated" | "validating" | "valid" | "invalid";
+export interface FormFieldState {
+    name: FormNamePath;
+    value: QwFormValue | undefined;
+    errors: string[];
+    touched: boolean;
+    dirty: boolean;
+    validationStatus: FormFieldValidationStatus;
+    disabled: boolean;
+    readOnly: boolean;
+    required: boolean;
+}
+export type FormSubmitStatus = "idle" | "validating" | "submitting" | "success" | "invalid" | "error" | "canceled";
+/** Confirmed interaction restored after a native reconnect. In-flight validation is not included. */
+export interface FormInteractionSnapshot {
+    readonly errors: readonly FormErrorField[];
+    readonly touched: readonly string[];
+    readonly validated: readonly string[];
+    readonly submitStatus: FormSubmitStatus;
+}
+export interface QwFormState {
+    values: QwFormValues;
+    fieldStates: FormFieldState[];
+    submitting: boolean;
+    submitStatus: FormSubmitStatus;
+}
+export type FormCancelReason = "superseded" | "values-change" | "reset" | "cancel" | "fields-change" | "unmount";
+export interface FormValidationResult {
+    values: QwFormValues;
+    errorFields: FormErrorField[];
+    outOfDate: boolean;
+    canceled: boolean;
+}
+export interface FormSubmitResult {
+    status: "success" | "invalid" | "error" | "canceled";
+    values: QwFormValues;
+    errorFields: FormErrorField[];
+    error?: string;
+    reason?: FormCancelReason;
+}
+export type FormSubmitHandler = (values: QwFormValues, context: {
+    signal: AbortSignal;
+}) => void | Promise<void>;
+export interface QwFormProps {
+    id?: string;
+    label: string;
+    fields: QwFormFieldDefinition[];
+    values?: QwFormValues;
+    initialValues?: QwFormValues;
+    initialErrors?: FormErrorField[];
+    disabled?: boolean;
+    readOnly?: boolean;
+    validateTrigger?: FormValidationTrigger | FormValidationTrigger[];
+    validateFirst?: boolean;
+    focusFirstError?: boolean;
+    messages?: Partial<FormMessages>;
+    onValuesChange?: (details: {
+        values: QwFormValues;
+    }) => void;
+    onValidationChange?: (details: {
+        state: QwFormState;
+    }) => void;
+    onSubmit?: FormSubmitHandler;
+    onSubmitSuccess?: (details: {
+        values: QwFormValues;
+    }) => void;
+    onValidationFailed?: (details: {
+        values: QwFormValues;
+        errorFields: FormErrorField[];
+    }) => void;
+    onSubmitError?: (details: {
+        values: QwFormValues;
+        error: string;
+    }) => void;
+    onSubmitCancel?: (details: {
+        reason: FormCancelReason;
+    }) => void;
+}
+/** API methods always read live Core; returned state/values never expose internal storage. */
+export interface QwFormApi<T extends PropTypes = PropTypes> {
+    readonly values: QwFormValues;
+    readonly state: QwFormState;
+    getValues(): QwFormValues;
+    getFieldValue(name: QwNamePath): QwFormValue | undefined;
+    getFieldState(name: QwNamePath): FormFieldState;
+    /** Live confirmed errors, touch, and submit status. Busy submit is settled only when a new machine applies it. */
+    getInteractionSnapshot(): FormInteractionSnapshot;
+    setFieldValue(name: QwNamePath, value: QwFormValue | undefined): void;
+    setFieldsValue(values: QwFormValues): void;
+    setFieldErrors(name: QwNamePath, errors: string[]): void;
+    validateFields(names?: QwNamePath[], options?: {
+        validateOnly?: boolean;
+        trigger?: FormValidationTrigger;
+    }): Promise<FormValidationResult>;
+    submit(): Promise<FormSubmitResult>;
+    cancelSubmit(): void;
+    resetFields(names?: QwNamePath[]): void;
+    focusField(name: QwNamePath): boolean;
+    getRootProps(): T["element"];
+    getLabelProps(): T["element"];
+    getContentProps(): T["element"];
+    getErrorSummaryProps(): T["element"];
+    getErrorListProps(): T["element"];
+    getErrorItemProps(name: QwNamePath): T["element"];
+    getErrorLinkProps(name: QwNamePath): T["element"];
+    getFooterProps(): T["element"];
+    getFieldProps(name: QwNamePath): QwFieldProps;
+    getInputProps(name: QwNamePath): QwInputProps;
+    getCheckboxProps(name: QwNamePath): QwCheckboxProps;
+    getRadioGroupProps(name: QwNamePath): QwRadioGroupProps;
+    getSegmentedProps(name: QwNamePath): QwSegmentedProps;
+    getNativeControlProps(name: QwNamePath): T["input"];
+    getNativeElementProps(name: QwNamePath): Record<string, unknown>;
+    /** Spreadable readonly text group. No tab stop and no htmlFor. */
+    getReadonlyProps(name: QwNamePath): T["element"];
+}
+export type FormNormalizer<T extends PropTypes> = NormalizeProps<T>;