@qw-ui/core 0.3.0-next.8 → 0.3.0

package/dist/textarea/textarea.d.ts

@@ -1,50 +1,167 @@
 import type { MachineSchema, Service } from "@zag-js/core";
 import type { PropTypes, NormalizeProps } from "@zag-js/types";
+/**
+ * 平台快照与 sink。字段与 `contracts/platform.md` 逐字一致。
+ * 平台模块可以各自声明同结构类型；这里是 Core 侧事实源。
+ */
+export type TextAreaBoxSizing = "border-box" | "content-box";
+export type TextAreaClipboardFailure = "unsupported" | "denied" | "aborted" | "stale";
+export interface TextAreaControlSnapshot {
+    /** 当前 textarea.value，原样返回。 */
+    readonly value: string;
+    /**
+     * 控件自身的 disabled 属性结果，含 fieldset 与第一个 legend 的例外。
+     * 不解释 readOnly、maxLength 或是否接受该值。
+     */
+    readonly disabled: boolean;
+}
+export interface TextAreaSizeSnapshot {
+    /** height 临时为 auto 时读到的 scrollHeight。含 padding，不含 border。 */
+    readonly scrollHeight: number;
+    /** 行内可用尺寸，单位 px。为 0 表示尚未布局。 */
+    readonly inlineSize: number;
+    /** 已解析成 px 的行高。关键字未能解析时视为无效度量。 */
+    readonly lineHeight: number;
+    readonly paddingBlockSize: number;
+    readonly borderBlockSize: number;
+    readonly boxSizing: TextAreaBoxSizing;
+    /** display 不是 none，且具有非零布局盒。 */
+    readonly visible: boolean;
+}
+export interface TextAreaEditEvent {
+    readonly type: "input" | "composition-start" | "composition-update" | "composition-end";
+    readonly value: string;
+}
+export interface TextAreaResetNotice {
+    /** 必须是该次 reset 派发完全结束后的值。 */
+    readonly defaultPrevented: boolean;
+}
+export interface TextAreaPlatformClient {
+    readControl(): TextAreaControlSnapshot;
+    measureIntrinsic(): TextAreaSizeSnapshot;
+    writeValue(value: string, defaultValue: string): void;
+    writeHeight(height: number | undefined): void;
+    focus(): void;
+    blur(): void;
+    readClipboardText(): Promise<string>;
+}
+export interface TextAreaPlatformSink {
+    commit(client: TextAreaPlatformClient): void;
+    changed(): void;
+    edit(event: TextAreaEditEvent): void;
+    focusChanged(focused: boolean): void;
+    reset(notice: TextAreaResetNotice): void;
+    detach(): void;
+}
+export interface TextAreaHeightInput {
+    readonly autoSize: boolean;
+    /** 缺省与非法值由 Core 先规范成不小于 1 的整数，缺省 4。 */
+    readonly rows: number;
+    /**
+     * 可选上限。缺省、非有限，或 floor 后不大于 0 时不封顶。
+     * floor 后小于 rows 时，有效上限等于 rows。只在 autoSize 时参与计算。
+     */
+    readonly maxRows?: number;
+    readonly metrics: TextAreaSizeSnapshot | undefined;
+}
+export interface TextAreaPasteDetail {
+    value: string;
+    status: "accepted" | "unavailable";
+    reason?: TextAreaClipboardFailure;
+}
+/** 原生事件 detail。框架 onChange 仍是字符串；这些回调只给原生传输。 */
+interface TextAreaNativeCallbacks {
+    onTextareaValue?: (detail: {
+        value: string;
+    }) => void;
+    onTextareaChange?: (detail: {
+        value: string;
+    }) => void;
+    onTextareaClear?: (detail: {
+        value: "";
+    }) => void;
+    onTextareaPaste?: (detail: TextAreaPasteDetail) => void;
+    onTextareaFocus?: (detail: {
+        focused: boolean;
+    }) => void;
+}
 /**
  * TextArea 公共 props 契约（双栈共享）。
+ * autoSize 保持布尔。可选 maxRows 只在自动高度时封顶。
  */
 export interface QwTextAreaProps {
     /** 唯一 id 前缀。 */
     id?: string;
-    /** 受控值。 */
+    /** 受控值。传入任意字符串（含 ""）即为受控。 */
     value?: string;
-    /** 非受控初始值。 */
+    /** 非受控初始值，也是 reset 目标。 */
     defaultValue?: string;
     /** 占位符。 */
     placeholder?: string;
-    /** 最大字符数。 */
+    /** 最大字符数。仅有限整数 > 0 时生效。 */
     maxLength?: number;
+    /** 最小长度。仅有限整数 > 0 时反射为 minlength。 */
+    minLength?: number;
     /** 禁用态。 */
     disabled?: boolean;
-    /** 只读态。 */
+    /** 只读态。可聚焦、可选择、可提交，不可编辑。 */
     readOnly?: boolean;
-    /** 可视行数（影响最小高度）。 */
+    /** 可视行数（最小高度）。小于 1 或非有限时按 4。 */
     rows?: number;
-    /** 自适应高度。 */
+    /**
+     * 自动高度的行数上限。仅 autoSize 为 true 且 floor 后大于 0 时生效。
+     * 小于 rows 时高度仍不低于 rows。缺省或非法值不封顶。
+     */
+    maxRows?: number;
+    /** 自适应高度。布尔，不接受 { minRows, maxRows } 对象。 */
     autoSize?: boolean;
     /** 显示底部操作按钮。 */
     showActions?: boolean;
     /** name 属性。 */
     name?: string;
-    /** 输入变化回调。 */
+    /** 外部 form 的 id。 */
+    form?: string;
+    /** 内层 textarea required。 */
+    required?: boolean;
+    /** 为 true 时写 aria-invalid。 */
+    invalid?: boolean;
+    /** textarea aria-label。 */
+    accessibleLabel?: string;
+    /** textarea aria-labelledby。 */
+    labelledBy?: string;
+    /** 并入 textarea aria-describedby。 */
+    describedBy?: string;
+    /** textarea aria-errormessage。 */
+    errorId?: string;
+    /** 清除按钮 aria-label，默认「清除内容」。 */
+    clearLabel?: string;
+    /** 粘贴按钮 aria-label，默认「粘贴并识别」。 */
+    pasteLabel?: string;
+    /** 清除按钮可见文字，默认「一键清除」。 */
+    clearText?: string;
+    /** 识别按钮可见文字，默认「粘贴并识别」。 */
+    pasteText?: string;
+    /** 仅 final commit。 */
     onChange?: (value: string) => void;
-    /** 清空回调。 */
+    /** 清空成功时。 */
     onClear?: () => void;
-    /** 粘贴并识别回调，参数为粘贴的文本。 */
+    /** 仅识别成功。参数是替换用的文本。 */
     onPasteRecognize?: (value: string) => void;
+    /** 识别失败或 ticket 过期。 */
+    onPasteError?: (reason: TextAreaClipboardFailure) => void;
     /** 聚焦回调。 */
     onFocus?: () => void;
     /** 失焦回调。 */
     onBlur?: () => void;
 }
-/**
- * 内部 schema，用于 createMachine 类型推导。
- */
 interface TextAreaSchema extends MachineSchema {
-    props: QwTextAreaProps;
+    props: QwTextAreaProps & TextAreaNativeCallbacks;
     context: {
-        value: string;
+        uncontrolled: string;
         focused: boolean;
+        composing: boolean;
+        draft: string;
+        controlDisabled: boolean;
     };
     computed: {
         charCount: number;
@@ -53,62 +170,68 @@ interface TextAreaSchema extends MachineSchema {
     };
     state: "idle";
     event: {
-        type: "VALUE.SET";
-        value: string;
-    } | {
-        type: "VALUE.CLEAR";
-    } | {
-        type: "FOCUS.SET";
-        focused: boolean;
-    } | {
-        type: "PASTE_RECOGNIZE";
-        value?: string;
+        type: "NOP";
     };
-    action: "setValue" | "clearValue" | "setFocused" | "invokeOnClear" | "pasteValue" | "invokeOnPasteRecognize" | "invokeOnFocus" | "invokeOnBlur";
+    action: "noop";
 }
+export type { TextAreaSchema };
 /**
- * TextArea zag.js machine。
- * 所有交互逻辑唯一来源：value、focus、clear、pasteRecognize。
+ * UTF-16 安全截断。maxLength 为空、非有限，或 floor 后不大于 0 时原样返回。
  */
-export declare const machine: import("@zag-js/core").Machine<TextAreaSchema>;
+export declare function clampUtf16(value: string, maxLength: number | undefined): string;
+/**
+ * 自动高度像素。下限是 rows；有效 maxRows 把 border-box 再夹住。
+ * 无法度量时返回 undefined，调用方不得写成 0。不读取 DOM。
+ */
+export declare function computeTextAreaHeight(input: TextAreaHeightInput): number | undefined;
 /**
- * TextArea api 类型（由 connect 返回）。
+ * TextArea zag.js machine。
+ * 值、草稿、ticket 与高度结论都在这里；没有第二份 value watcher。
  */
+export declare const machine: import("@zag-js/core").Machine<TextAreaSchema>;
+/** connect 返回的业务 api。 */
 export interface TextAreaApi<T extends PropTypes = PropTypes> {
-    /** 当前输入值。 */
+    /** 已提交值。 */
     value: string;
-    /** 当前是否聚焦。 */
+    /** 组合期间为草稿，否则为已提交值。供原生视图投影，不替代 writeValue。 */
+    displayValue: string;
+    /** field 是否聚焦。 */
     focused: boolean;
-    /** 当前字符数。 */
+    /** 是否处于草稿阶段。 */
+    composing: boolean;
+    /** 草稿阶段用草稿的 UTF-16 长度，否则用已提交值。 */
     charCount: number;
-    /** 是否有字数限制。 */
+    /** 是否存在有限正整数上限。 */
     hasMaxLength: boolean;
-    /** 是否显示清除按钮。 */
+    /** 已提交值非空，且未禁用、非只读。 */
     showClear: boolean;
-    /** 清空输入。 */
+    /** 规范化后的正整数上限；没有上限时为 undefined。 */
+    limit: number | undefined;
+    showActions: boolean;
+    clearText: string;
+    pasteText: string;
+    fieldId: string;
+    counterId: string;
+    /** 把已提交值和高度投影到平台。组合期间不写值。 */
+    project(): void;
+    /** 平台 sink。同一 service 返回同一对象。 */
+    getPlatformSink(): TextAreaPlatformSink;
     clear(): void;
-    /** 触发粘贴并识别回调（可传入剪贴板文本，自动填入）。 */
+    /** 传入字符串则直接按识别提交；不传则读剪贴板。 */
     pasteRecognize(value?: string): void;
-    /** 根容器 prop-getter。 */
     getRootProps(): T["element"];
-    /** textarea 元素 prop-getter。 */
     getTextareaProps(): T["textarea"];
-    /** 底部栏 prop-getter。 */
     getBottomBarProps(): T["element"];
-    /** 字数统计 prop-getter。 */
     getCounterProps(): T["element"];
-    /** 清除按钮 prop-getter。 */
     getClearButtonProps(): T["button"];
-    /** 粘贴按钮 prop-getter。 */
     getPasteButtonProps(): T["button"];
 }
 /**
- * connect：把 service 接成业务友好的 prop-getter。
- * 适配层只需调用 connect(service, normalizeProps)。
+ * connect：把 service 接成 prop-getter。适配层不在这里之外做接受与否的判断。
  */
 export declare function connect<T extends PropTypes>(service: Service<TextAreaSchema>, normalizeProps: NormalizeProps<T>): TextAreaApi<T>;
 /**
- * 把 QwTextAreaProps 转成 machine context（默认值收口）。
+ * 把 QwTextAreaProps 转成 machine props（默认值收口）。
+ * 缺省文案是 zh-CN；适配层传入的 locale 优先。
  */
 export declare function createTextAreaProps(props?: QwTextAreaProps): Partial<QwTextAreaProps>;
-export {};