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

package/dist/picker/picker-machine.d.ts

@@ -0,0 +1,80 @@
+import type { Machine, Service } from "@zag-js/core";
+import { popupMachine } from "../popup/popup.js";
+import { PickerSelectionModel, type PickerColumnSignal, type PickerColumnToken, type PickerKeyboardMove, type PickerMode, type PickerSelectionNotice, type PickerSelectionProps, type PickerSelectionSnapshot, type PickerValue } from "./selection-model.js";
+/**
+ * Picker 的单一 Foundation service（T002）。
+ *
+ * 不是第二个 machine：它是锁定的上游 `popupMachine` 的显式 typed 投影 —— props / context / states /
+ * transitions / actions / effects 全部来自同一个 Popup machine，只追加选择会话的 context、refs 与事件。
+ * 工具栏（popup）形态的开合、焦点、滚动锁、portal id 与模态票据都由这一个 service 承担；
+ * 内嵌（inline）形态把所有上游打开路径守卫为 closed：没有锁、没有 portal、没有模态登记。
+ *
+ * 迁移自 specs/054-mobile-picker/spike/machine-foundation.ts（T002 + T035–T039 证据），
+ * 仅删去 spike 的 PREVIEW.SET 探针并增加离散选择/键盘/列焦点事件。
+ */
+type PopupSchema = typeof popupMachine extends Machine<infer Schema> ? Schema : never;
+export interface QwPickerSchema extends Omit<PopupSchema, "action" | "event" | "effect"> {
+    props: PopupSchema["props"] & {
+        mode: PickerMode;
+        selection?: PickerSelectionProps;
+        onSelectionNotice?: (event: PickerSelectionNotice) => void;
+    };
+    context: {
+        rendered: PopupSchema["context"]["rendered"];
+        triggerValue: PopupSchema["context"]["triggerValue"];
+        preview: PickerValue;
+        selectionSnapshot: PickerSelectionSnapshot | null;
+        surfaceTokens: readonly (PickerColumnToken | undefined)[];
+    };
+    refs: {
+        /** 构造时固定的形态；切换形态须重新挂载。 */
+        mode: PickerMode;
+        selectionModel: PickerSelectionModel;
+        selectionTransport: {
+            notice?: (event: PickerSelectionNotice) => void;
+            closeIntent: boolean;
+            session: number;
+        };
+    };
+    action: PopupSchema["action"] | "selectionInput";
+    effect: PopupSchema["effect"] | "selectionLifetime";
+    event: PopupSchema["event"] | {
+        type: "SELECTION.MOUNT";
+        columnIndex: number;
+    } | {
+        type: "SELECTION.UNMOUNT";
+        token: PickerColumnToken;
+    } | {
+        type: "SELECTION.INPUT";
+        token: PickerColumnToken;
+        signal: PickerColumnSignal;
+    } | {
+        type: "SELECTION.SELECT";
+        columnIndex: number;
+        optionIndex: number;
+    } | {
+        type: "SELECTION.MOVE";
+        columnIndex: number;
+        move: PickerKeyboardMove;
+    } | {
+        type: "SELECTION.FOCUS";
+        columnIndex: number;
+    } | {
+        type: "SELECTION.CONFIRM";
+    } | {
+        type: "SELECTION.CANCEL";
+    } | {
+        type: "SELECTION.CLOSE";
+        session: number;
+    };
+}
+export type QwPickerService = Service<QwPickerSchema>;
+export type QwPickerMachine = Machine<QwPickerSchema>;
+/** Typed pinned upstream projection: one service, the original two modal states. */
+export declare const pickerMachine: QwPickerMachine;
+/** Project the one service for the upstream Popup connector; never instantiate another. */
+export declare function toPopupService(service: Service<QwPickerSchema>): Service<PopupSchema>;
+type SelectionEvent = QwPickerSchema["event"];
+/** Keep input ordering when the machine scheduler has not consumed an earlier selection yet. */
+export declare function sendPickerSelection(service: QwPickerService, event: SelectionEvent): void;
+export {};

package/dist/picker/picker.d.ts

@@ -0,0 +1,121 @@
+import type { ModalRenderRuntime } from "../modal-render-runtime.js";
+import { connectPopup, type QwPopupProps } from "../popup/popup.js";
+import type { QwPickerSchema, QwPickerService } from "./picker-machine.js";
+import { type PickerChangeDetails, type PickerColumn, type PickerColumnSignal, type PickerColumnToken, type PickerDiagnostic, type PickerKeyboardMove, type PickerMode, type PickerScrollCommand, type PickerValue } from "./selection-model.js";
+/**
+ * Picker 公开 Core 面：props 归一化、模态 runtime 透传与 getters。
+ * 物理层是同一个 pickerMachine service（见 picker-machine.ts）：工具栏形态复用 Popup 的
+ * 遮罩/焦点/滚动锁/portal/票据；内嵌形态不进入打开态，不使用 runtime。
+ */
+/** Picker 输入。继承 Popup 同义 props；固定底部，不接受 placement。 */
+export interface QwPickerProps extends Omit<QwPopupProps, "placement"> {
+    /** 缺省 "popup"（带确定/取消工具栏）。只在构造时读取；切换形态须重新挂载。 */
+    mode?: PickerMode;
+    /** 按逻辑顺序的列。联动列由调用方在 onPreviewChange 中同步替换。 */
+    columns: readonly PickerColumn[];
+    /** 受控已提交值。传入即受控，组件只发出变更请求。 */
+    value?: PickerValue;
+    /** 非受控初值；缺省为各列第一可选项。 */
+    defaultValue?: PickerValue;
+    /** 确定按钮文字，缺省「确定」。 */
+    confirmLabel?: string;
+    /** 取消按钮文字，缺省「取消」。 */
+    cancelLabel?: string;
+    /** 工具栏确定（等待落定后）或内嵌落定时通知一次。 */
+    onValueChange?: (details: PickerChangeDetails) => void;
+    /** 预览变化时通知；取消/关闭离开时通知一次恢复后的预览。 */
+    onPreviewChange?: (details: PickerChangeDetails) => void;
+}
+/** createPickerProps 的输出：同一 Popup machine 的 context + 选择会话输入（只供 Core 读取）。 */
+export type QwPickerMachineProps = Partial<QwPickerSchema["props"]>;
+/** Core 派生的渲染数据。适配层只渲染，不判断 disabled/duplicate/selected。 */
+export interface QwResolvedPickerOption {
+    readonly index: number;
+    readonly value: string;
+    readonly label: string;
+    /** 禁用或重复值后项：可见、不可落定。 */
+    readonly disabled: boolean;
+    readonly duplicate: boolean;
+    readonly selected: boolean;
+}
+export interface QwResolvedPickerColumn {
+    readonly index: number;
+    /** 可访问列名：column.label → 「第 N 列」。 */
+    readonly label: string;
+    readonly options: readonly QwResolvedPickerOption[];
+    /** 当前预览项索引；无效时 -1（不伪造选中）。 */
+    readonly selectedIndex: number;
+    /** 没有任何可选项。 */
+    readonly empty: boolean;
+}
+type PickerNormalize = Parameters<typeof connectPopup>[1];
+type NormalizedProps = ReturnType<PickerNormalize["element"]>;
+type PopupApi = ReturnType<typeof connectPopup>;
+export type QwPickerApi = PopupApi & {
+    readonly mode: PickerMode;
+    readonly columns: readonly QwResolvedPickerColumn[];
+    /** 已提交值（受控时即调用方值）。 */
+    readonly value: PickerValue;
+    /** 滚轮当前预览。 */
+    readonly preview: PickerValue;
+    /** 所有列都有有效项且外部值有效。为 false 时确定不可用。 */
+    readonly valid: boolean;
+    /** 已按确定，正在等待滚动落定。 */
+    readonly pendingConfirm: boolean;
+    /** 选择会话是否接收输入（工具栏打开时，或内嵌）。 */
+    readonly active: boolean;
+    /** roving tabindex 的逻辑列。 */
+    readonly focusedColumn: number;
+    readonly selectedIndices: readonly number[];
+    /** 待桥执行的 scrollTo 请求。 */
+    readonly commands: readonly PickerScrollCommand[];
+    readonly diagnostics: readonly PickerDiagnostic[];
+    readonly accessibleName: string;
+    readonly confirmLabel: string;
+    readonly cancelLabel: string;
+    confirm(): void;
+    cancel(): void;
+    selectOption(columnIndex: number, optionIndex: number): void;
+    moveColumn(columnIndex: number, move: PickerKeyboardMove): void;
+    /** 机械桥：真实列节点挂载后调用；票据随 getColumnToken 发布。 */
+    mountColumn(columnIndex: number): void;
+    getColumnToken(columnIndex: number): PickerColumnToken | undefined;
+    unmountColumn(token: PickerColumnToken): void;
+    input(token: PickerColumnToken, signal: PickerColumnSignal): void;
+    getRootProps(): NormalizedProps;
+    getColumnsProps(): NormalizedProps;
+    getColumnProps(details: {
+        index: number;
+    }): NormalizedProps;
+    getOptionProps(details: {
+        columnIndex: number;
+        index: number;
+    }): NormalizedProps;
+    getIndicatorProps(): NormalizedProps;
+    getToolbarProps(): NormalizedProps;
+    getCancelProps(): NormalizedProps;
+    getConfirmProps(): NormalizedProps;
+};
+/** 未知 mode 回退 popup。 */
+export declare function resolvePickerMode(mode: unknown): PickerMode;
+/** 可访问名称：title → ariaLabel → 「选择器」。空白视为缺省。 */
+export declare function getPickerAccessibleName(props: Pick<QwPickerProps, "title" | "ariaLabel">): string;
+/** 业务值只接受 string/null 数组。 */
+export declare function isPickerValue(value: unknown): value is PickerValue;
+/** 列结构校验：label 可选字符串，options 的 value/label 为字符串，disabled 可选布尔。 */
+export declare function isPickerColumns(value: unknown): value is readonly PickerColumn[];
+/** 渲染数据：保留全部可见项，标出禁用/重复后项与当前预览项。 */
+export declare function resolvePickerColumns(columns: readonly PickerColumn[], preview?: PickerValue): readonly QwResolvedPickerColumn[];
+/** Popup 的 data 属性（placement 固定 bottom）。 */
+export declare function getPickerDataAttrs(props: Pick<QwPickerProps, "safeArea">): Record<string, string | undefined>;
+/**
+ * 公开 props → 同一 pickerMachine 的 props。机械委托 createPopupProps(props, runtime)：
+ * 受控优先、初态许可/拒绝仍由 Popup Core 决定；runtime 只在工具栏形态透传（WC 带 owner "wc:picker"）。
+ */
+export declare function createPickerProps(props: QwPickerProps, runtime?: ModalRenderRuntime): QwPickerMachineProps;
+/**
+ * 包装同一 service 的 connectPopup：继承开合/getters 与单层模态拒绝，增加滚轮 root/column/option、
+ * 工具栏 cancel/confirm getters。确定/取消/键盘/点击都只发 typed 事件，由 selection-model 决定结果。
+ */
+export declare function connectPicker(service: QwPickerService, normalize: PickerNormalize, props: QwPickerProps, runtime?: ModalRenderRuntime): QwPickerApi;
+export {};

package/dist/picker/platform.d.ts

@@ -0,0 +1,84 @@
+import type { PickerColumnSignal, PickerColumnToken, PickerScrollCommand } from "./selection-model.js";
+/**
+ * Picker 列的平台装配：监听、测量、执行 Core 的 scrollTo 与回 ACK。
+ * 只运输原始数值与 Core 票据 —— 不排序、不回退、不选值、不判断确定（那些只在 selection-model）。
+ * 各栈适配层只保留生命周期胶水：挂载后 connectPickerColumn(...)，每次渲染后 sync()，卸载时 dispose()。
+ * 模块顶层不访问 DOM；所有 DOM 读取都在调用时发生（SSR-safe）。
+ *
+ * attachPickerColumn 迁移自 specs/054-mobile-picker/spike/column-surface.ts（T039 证据）。
+ */
+/** 原始事件事实，仅作运输元数据。 */
+export type PickerRawEventFacts = {
+    type: string;
+    timeStamp: number;
+    isTrusted: boolean;
+    clientX?: number;
+    clientY?: number;
+    pointerId?: number;
+    pointerType?: string;
+    deltaX?: number;
+    deltaY?: number;
+    deltaMode?: number;
+};
+export type PickerBridgeNotice = {
+    type: "SURFACE.MOUNTED" | "SURFACE.DETACHED";
+    token: PickerColumnToken;
+} | {
+    type: "INPUT";
+    token: PickerColumnToken;
+    signal: PickerColumnSignal;
+    event?: PickerRawEventFacts;
+    sampledAt?: number;
+} | {
+    type: "RAW.POINTER.MOVE";
+    token: PickerColumnToken;
+    event: PickerRawEventFacts;
+} | {
+    type: "COMMAND.FAILED";
+    token: PickerColumnToken;
+    commandId: number;
+    reason: "unbound" | "exception";
+};
+export type PickerBridgeCommand = {
+    type: "SCROLL_TO";
+    command: PickerScrollCommand;
+} | {
+    type: "MEASURE";
+    token: PickerColumnToken;
+} | {
+    type: "FOCUS_COLUMN";
+    token: PickerColumnToken;
+};
+export interface PickerColumnBinding {
+    execute(command: PickerBridgeCommand): boolean;
+    release(): void;
+}
+export interface PickerColumnSurface {
+    readonly binding: PickerColumnBinding;
+    bind(token: PickerColumnToken, rows: readonly HTMLElement[]): PickerColumnBinding;
+    dispose(): void;
+}
+/**
+ * 一个物理列挂载：先按 Core 票据校验物理归属，再替换可换的输入绑定。
+ * 票据刷新（epoch/generation）只换 binding；真实卸载才 dispose 并送 SURFACE.DETACHED。
+ */
+export declare function attachPickerColumn(viewport: HTMLElement, initial: PickerColumnToken, rows: readonly HTMLElement[], sink: (notice: PickerBridgeNotice) => void): PickerColumnSurface;
+/** connectPicker 的 api 满足这个宿主接口；桥只调用这些运输方法。 */
+export interface PickerColumnHost {
+    readonly commands: readonly PickerScrollCommand[];
+    mountColumn(columnIndex: number): void;
+    getColumnToken(columnIndex: number): PickerColumnToken | undefined;
+    unmountColumn(token: PickerColumnToken): void;
+    input(token: PickerColumnToken, signal: PickerColumnSignal): void;
+}
+export interface PickerColumnController {
+    /** 每次渲染/更新后调用：请求挂载、按新票据换绑定、执行属于当前绑定的 scroll 命令。 */
+    sync(): void;
+    /** 真实卸载时调用一次：释放监听与观察器，并送 SURFACE.DETACHED。 */
+    dispose(): void;
+}
+/**
+ * 三栈共用的列生命周期胶水。getHost 每次返回最新 api（React/Vue/WC 每次渲染都会 connect 一次）。
+ * Core 未签发票据（工具栏关闭、会话失效）时保持物理挂载但不输入；票据回来后只换绑定。
+ */
+export declare function connectPickerColumn(getHost: () => PickerColumnHost, viewport: HTMLElement, columnIndex: number, getRows: () => readonly HTMLElement[]): PickerColumnController;

package/dist/picker/selection-connect.d.ts

@@ -0,0 +1,90 @@
+import { connectPopup, type QwPopupProps } from "../popup/popup.js";
+import type { ModalRenderRuntime } from "../modal-render-runtime.js";
+import { type QwPickerService } from "./picker-machine.js";
+import type { PickerColumnSignal, PickerColumnToken, PickerKeyboardMove } from "./selection-model.js";
+/**
+ * 机械连接层（包内）：同一 service 投影给原 Popup connector，选择输入保留 typed 队列；confirm/cancel 同步排空先前输入再请求关闭。
+ * 原生 IO 只运输捕获的票据与原始信号。connectPicker 在其上增加 ARIA/工具栏 getters。
+ */
+export declare function connectSelection(service: QwPickerService, normalize: Parameters<typeof connectPopup>[1], popupProps: QwPopupProps, runtime?: ModalRenderRuntime): {
+    popup: import("../popup/popup.js").QwPopupApi & {
+        getOriginProps(): ReturnType<((props: never) => {
+            [x: string]: any;
+        }) & ((props: ({
+            "data-selected"?: any | undefined;
+            "data-expanded"?: any | undefined;
+            "data-highlighted"?: any | undefined;
+            "data-readonly"?: any | undefined;
+            "data-indeterminate"?: any | undefined;
+            "data-invalid"?: any | undefined;
+            "data-hover"?: any | undefined;
+            "data-active"?: any | undefined;
+            "data-focus"?: any | undefined;
+            "data-focus-visible"?: any | undefined;
+            "data-disabled"?: any | undefined;
+            "data-open"?: any | undefined;
+            "data-checked"?: any | undefined;
+            "data-pressed"?: any | undefined;
+            "data-complete"?: any | undefined;
+            "data-side"?: any | undefined;
+            "data-align"?: any | undefined;
+            "data-empty"?: any | undefined;
+            "data-placeholder-shown"?: any | undefined;
+            "data-half"?: any | undefined;
+            "data-scope"?: string | undefined;
+            "data-uid"?: string | undefined;
+            "data-name"?: string | undefined;
+            "data-ownedby"?: string | undefined;
+            "data-type"?: string | undefined;
+            "data-valuetext"?: string | undefined;
+            "data-placement"?: string | undefined;
+            "data-controls"?: string | undefined;
+            "data-part"?: string | undefined;
+            "data-label"?: string | undefined;
+            "data-state"?: string | null | undefined;
+            "data-value"?: string | number | undefined;
+            "data-orientation"?: "horizontal" | "vertical" | undefined;
+            "data-count"?: number | undefined;
+            "data-index"?: number | undefined;
+        } & {
+            [x: `data-${string}`]: any;
+        }) & import("@zag-js/types").JSX.HTMLAttributes<HTMLElement> & Record<string, any>) => {
+            [x: string]: any;
+        })>;
+    };
+    snapshot: {
+        mode: import("./selection-model.js").PickerMode;
+        userRevision: number;
+        committed: (string | null)[];
+        preview: (string | null)[];
+        source: "external" | "restore" | "user";
+        selectedIndices: number[];
+        valid: boolean;
+        pendingConfirm: boolean;
+        active: boolean;
+        focusedColumn: number;
+        tokens: (PickerColumnToken | undefined)[];
+        commands: {
+            commandId: number;
+            offset: number;
+            behavior: "auto";
+            reason: "alignment" | "settlement";
+            token: {
+                serviceId: string;
+                epoch: number;
+                columnIndex: number;
+                generation: number;
+                mountEpoch: number;
+            };
+        }[];
+    };
+    mountColumn(columnIndex: number): void;
+    getColumnToken(columnIndex: number): PickerColumnToken | undefined;
+    unmountColumn(token: PickerColumnToken): void;
+    input(token: PickerColumnToken, signal: PickerColumnSignal): void;
+    select(columnIndex: number, optionIndex: number): void;
+    move(columnIndex: number, move: PickerKeyboardMove): void;
+    focusColumn(columnIndex: number): void;
+    confirm(): void;
+    cancel(): void;
+};

package/dist/picker/selection-model.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Picker 选择内核 —— 选值的唯一权威。无 DOM、无 Popup 实例、无模态状态；
+ * 唯一的模态输出是 `close` 请求，由同一 Foundation service 经继承的 Popup CLOSE 转移执行。
+ *
+ * 迁移自 specs/054-mobile-picker/spike/selection-model.ts：输入代次（epoch/generation）、
+ * 物理挂载（mountEpoch）、会话代次与等待落定的守卫原样保留（T035–T039 证据）。
+ * 本文件在其上增加：内嵌落定提交、离散选择（点击/键盘）、列焦点与重复值诊断。
+ */
+/** 按列顺序的业务值；null 表示该列没有有效项。 */
+export type PickerValue = readonly (string | null)[];
+/** popup：带工具栏，确定才提交；inline：内嵌滚轮，落定即提交。 */
+export type PickerMode = "popup" | "inline";
+export interface PickerOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface PickerColumn {
+    label?: string;
+    options: readonly PickerOption[];
+}
+export interface PickerChangeDetails {
+    value: PickerValue;
+}
+/** 选择内核输入：列与外部值。 */
+export interface PickerSelectionProps {
+    columns: readonly PickerColumn[];
+    value?: PickerValue;
+    defaultValue?: PickerValue;
+}
+/** Core 签发的列输入票据。桥只原样运输，不推导选值。 */
+export interface PickerColumnToken {
+    serviceId: string;
+    epoch: number;
+    columnIndex: number;
+    generation: number;
+    mountEpoch: number;
+}
+/** 桥测得的原始几何（像素）。rows 与该列 options 一一对应。 */
+export interface PickerGeometry {
+    viewportHeight: number;
+    scrollHeight: number;
+    scrollTop: number;
+    rows: readonly {
+        top: number;
+        height: number;
+    }[];
+}
+/** Core 输出的滚动请求；桥只执行 scrollTo 并回 ACK。 */
+export interface PickerScrollCommand {
+    token: PickerColumnToken;
+    commandId: number;
+    offset: number;
+    behavior: "auto";
+    reason: "alignment" | "settlement";
+}
+export type PickerSelectionNotice = {
+    type: "preview" | "value";
+    value: PickerValue;
+} | {
+    type: "close";
+    open: false;
+};
+/** 桥送入的原始信号；pointer/wheel/scroll 只是数值事实，落点与是否提交由 Core 决定。 */
+export type PickerColumnSignal = {
+    type: "MEASURE";
+    geometry: PickerGeometry;
+} | {
+    type: "POINTER.START";
+    pointerId: number;
+} | {
+    type: "POINTER.END" | "POINTER.CANCEL";
+    pointerId: number;
+} | {
+    type: "WHEEL";
+    deltaY: number;
+} | {
+    type: "SCROLL";
+    scrollTop: number;
+    lastCommandId?: number;
+} | {
+    type: "COMMAND.APPLIED";
+    commandId: number;
+    geometry: PickerGeometry;
+};
+/** 列内键盘移动。page-* 一次跨 5 项。 */
+export type PickerKeyboardMove = "next" | "previous" | "first" | "last" | "page-next" | "page-previous";
+/** 开发诊断：重复值后项可见但永不可选。 */
+export interface PickerDiagnostic {
+    type: "duplicate-value";
+    columnIndex: number;
+    optionIndex: number;
+    firstIndex: number;
+    value: string;
+}
+/** 可选 = 存在、未禁用、且是该值的逻辑第一项（第一项禁用也不提升后项）。 */
+export declare function isPickerOptionSelectable(column: PickerColumn, index: number): boolean;
+/** 列的第一可选值；没有可选项时为 null。 */
+export declare function getPickerFirstValue(column: PickerColumn): string | null;
+/** 值在列中的可选索引；不可选或不存在时为 -1（不伪造选中）。 */
+export declare function getPickerOptionIndex(column: PickerColumn, value: string | null): number;
+/** 重复值诊断：每个后项一条，指向逻辑第一项。 */
+export declare function getPickerDiagnostics(columns: readonly PickerColumn[]): readonly PickerDiagnostic[];
+/** 键盘目标索引：跳过禁用与重复后项；没有可去的项时返回 -1。当前无效时向下类从首项、向上类从末项找。 */
+export declare function getPickerKeyboardTarget(column: PickerColumn, current: number, move: PickerKeyboardMove): number;
+/** Core 选择会话。由 pickerMachine 的 refs 持有；context 中的 snapshot 只是它的可观察投影。 */
+export declare class PickerSelectionModel {
+    private props;
+    private accepted;
+    private restore;
+    private preview;
+    private source;
+    private externalInvalid;
+    private lastUserColumn;
+    private columns;
+    private epoch;
+    private sessionEpoch;
+    private active;
+    private disposed;
+    private pendingConfirm;
+    private inlineDirty;
+    private discreteTimer?;
+    private ownerTimer?;
+    private focusedColumn;
+    private userRevision;
+    private nextCommand;
+    private nextGeneration;
+    private nextMountEpoch;
+    private readonly serviceId;
+    private readonly notificationSink;
+    readonly mode: PickerMode;
+    constructor(serviceId: string, props: PickerSelectionProps, notificationSink: (event: PickerSelectionNotice) => void, mode?: PickerMode);
+    private observer?;
+    observe(observer: (snapshot: PickerSelectionSnapshot) => void): () => void;
+    private publish;
+    private notify;
+    get isDisposed(): boolean;
+    get snapshot(): {
+        mode: PickerMode;
+        userRevision: number;
+        committed: (string | null)[];
+        preview: (string | null)[];
+        source: "external" | "restore" | "user";
+        selectedIndices: number[];
+        valid: boolean;
+        pendingConfirm: boolean;
+        active: boolean;
+        focusedColumn: number;
+        tokens: (PickerColumnToken | undefined)[];
+        commands: {
+            commandId: number;
+            offset: number;
+            behavior: "auto";
+            reason: "alignment" | "settlement";
+            token: {
+                serviceId: string;
+                epoch: number;
+                columnIndex: number;
+                generation: number;
+                mountEpoch: number;
+            };
+        }[];
+    };
+    private previewValid;
+    private valid;
+    private token;
+    private current;
+    attach(columnIndex: number): PickerColumnToken;
+    detach(token: PickerColumnToken): void;
+    dispatch(token: PickerColumnToken, signal: PickerColumnSignal): void;
+    /** Captured identity must survive queueing; never relabel an old input. */
+    queue(token: PickerColumnToken, signal: PickerColumnSignal): void;
+    /** 离散选择（点击/键盘）：等同一次立即落定的用户选择；正在滚的本列被它取代。 */
+    select(columnIndex: number, optionIndex: number): void;
+    /**
+     * 离散选择的落定：与滚轮相同的静默窗口后才提交（内嵌）或兑现已按下的确定（工具栏）。
+     * 让框架下一次渲染才送达的联动后列先到，避免以旧后列冒充新数据（FR-011）。
+     */
+    private scheduleDiscrete;
+    private clearDiscrete;
+    /** 列内键盘移动；目标不存在时只更新列焦点。 */
+    move(columnIndex: number, move: PickerKeyboardMove): void;
+    /** 记录逻辑列焦点（roving tabindex）。不发业务通知。 */
+    focus(columnIndex: number): void;
+    private setUserPreview;
+    private clearTimer;
+    private schedule;
+    private align;
+    private settle;
+    private waiting;
+    confirm(): void;
+    private commit;
+    /** 内嵌：所有列落定且有效、并且与已提交值不同，才通知一次 value。不关闭、不使在途输入失效。 */
+    private flushInline;
+    /**
+     * 受控请求发出后：调用方在 OWNER_MS 内没有改写 value（拒绝），且用户未再操作，
+     * 则显示回到调用方的值（同外部回写路径：新代次、桥重新测量并对齐），并通知一次恢复后的预览。
+     * 工具栏若已真实关闭，会话结束即可，重开本就从已提交值开始。
+     */
+    private awaitOwner;
+    private clearOwner;
+    cancel(requestClose?: boolean): void;
+    /** Actual inherited Popup close fact, not another modal state transition. */
+    closed(): void;
+    stop(): void;
+    private invalidate;
+    update(props: PickerSelectionProps): void;
+    /** Begin a later actual Popup opening from the accepted entry value. */
+    reopened(): void;
+}
+export type PickerSelectionSnapshot = PickerSelectionModel["snapshot"];