@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.1.0

package/dist/input/list-state.d.ts

@@ -0,0 +1,118 @@
+import type { IconData } from '../base/Icon';
+import { type SelectionModes } from '../utils/data/selection';
+/** 一个选项 */
+export interface ListboxOption {
+    /** 值：选中后写回的就是它，同一列表里不能重复 */
+    value: string;
+    /** 显示的文字；类型搜索、Combobox 过滤、Select 触发框里显示的都是它 */
+    label: string;
+    /** 不可用：可以被方向键经过（读屏能听到），不能选中 */
+    disabled?: boolean;
+    /** 文字下方的说明 */
+    description?: string;
+    /** 文字前的图标 */
+    icon?: IconData;
+    /** 分组名：同名的选项排在一组，组名显示在组的第一行 */
+    group?: string;
+}
+/** 列表里的一项：选项的显示信息，加上它来自的原始数据 */
+export interface ListStateEntry<T> extends ListboxOption {
+    /** items 里对应的那一项：自定义渲染、renderValue 拿到的就是它 */
+    readonly item: T;
+}
+/**
+ * 数据 → 选项的显示信息：items 已经是 ListboxOption 时可以不写，否则必填。
+ * 后端数据直接传给 items，不用先 map 成 { value, label }：
+ *   <Select items={users} toOption={(user) => ({ value: user.id, label: user.name })} />
+ */
+export type OptionMapping<T> = [T] extends [ListboxOption | string] ? {
+    /** 数据 → 选项（值、文字、不可用、分组…）；items 是 ListboxOption 或字符串时可以不写 */
+    toOption?: (item: T) => ListboxOption;
+} : {
+    /** 数据 → 选项（值、文字、不可用、分组…） */
+    toOption: (item: T) => ListboxOption;
+};
+/**
+ * 一项数据的选项：给了 toOption 用它；没给时数据本身是 ListboxOption，或是字符串（值与文字都是它，
+ * `items={['设计', '研发']}` 这样的简单列表不用先 map 成 { value, label }）
+ */
+export declare function toListboxOption<T>(item: T, toOption?: (item: T) => ListboxOption): ListboxOption;
+/** 已选值对应的选项：item 是它来自的数据；从没在 items 里见过的值（自定义的、还没加载的）item 为 undefined */
+export interface SelectedOption<T> extends ListboxOption {
+    /** 来自的数据 */
+    item: T | undefined;
+}
+/**
+ * 按值查已选项的显示信息（在 setup 里调用）：Select、Combobox、TagsInput 显示已选项的文字都用它。
+ * 记住见过的已选项：远程搜索、过滤、分页把 items 换掉之后，不在当前 items 里的已选项仍按之前见过的文字显示，
+ * 不会退化成值本身（工号、id）。只记已选的值，不随 items 增长
+ */
+export declare function useSelectedOptions<T>(read: {
+    /** 数据 */
+    items: () => readonly T[];
+    /** 数据 → 选项 */
+    toOption: (item: T) => ListboxOption;
+}): (values: readonly string[]) => SelectedOption<T>[];
+/**
+ * useListState 的选项。按字段给读取函数（不是一个返回整个对象的 read）：
+ * 选项上万时，选择变了不该重新整理选项，各字段要分开追踪依赖
+ */
+export interface ListStateOptions<T> {
+    /** 数据 */
+    items: () => readonly T[];
+    /** 数据 → 选项；不写时 items 本身就是 ListboxOption。在 computed 里调用，读到的 props 会被追踪 */
+    toOption?: (item: T) => ListboxOption;
+    /** 已选的值 */
+    selected: () => readonly string[];
+    /** 单选或多选 */
+    mode: () => keyof SelectionModes;
+    /** 至少保留一项（单选时再点已选项不取消） */
+    required?: () => boolean;
+    /** 选择变化 */
+    onChange: (values: readonly string[]) => void;
+}
+/** 列表的状态与操作 */
+export interface ListState<T> {
+    /** 按分组排好的选项：渲染与键盘移动都按这个顺序 */
+    readonly options: readonly ListStateEntry<T>[];
+    /** 高亮（键盘或指针所在）的选项的值 */
+    readonly active: string | undefined;
+    /** 值在 options 里的位置；不在时 -1 */
+    indexOf(value: string): number;
+    /** 是否已选 */
+    isSelected(value: string): boolean;
+    /** 设置高亮项；undefined 取消高亮 */
+    setActive(value: string | undefined): void;
+    /** 高亮已选的第一项，没有已选时高亮第一个可用项（打开下拉、列表获得焦点时） */
+    activateDefault(): void;
+    /** 移动高亮：±n 项（到头时停住），或到第一项 / 最后一项；跳过不可用的项 */
+    move(step: number | 'first' | 'last'): void;
+    /** 切换一项的选中（不可用的项忽略）；返回是否发生了变化 */
+    select(value: string): boolean;
+    /** 类型搜索：按下一个字符，高亮以它开头的项；返回是否命中 */
+    typeahead(key: string): boolean;
+}
+/** 列表状态（组件 setup 里调用） */
+export declare function useListState<T>(config: ListStateOptions<T>): ListState<T>;
+/**
+ * 输入搜索词后给读屏播报结果条数（“12 个选项”“没有匹配的选项”），停顿一会儿再念（在 setup 里调用）。
+ * WAI-ARIA 的组合框模式里看不见列表的读屏用户靠它知道过滤的结果；Select 的搜索框、Combobox 用它
+ */
+export declare function useResultAnnouncement(read: () => {
+    query: string;
+    count: number;
+}): void;
+/** handleListKeydown 的选项：不同的宿主（列表、触发按钮、输入框）对空格与字母的处理不同 */
+export interface ListKeydownOptions {
+    /** 空格选中高亮项（列表、Select）；输入框里空格是文字，不选 */
+    space?: boolean;
+    /** 字母做类型搜索（列表、Select）；输入框里字母是文字 */
+    typeahead?: boolean;
+    /** Home / End 到第一项 / 最后一项，默认 true；输入框里它们移动光标 */
+    homeEnd?: boolean;
+}
+/**
+ * 列表的键盘操作：↑↓ 移动、Home / End、Page Up / Page Down、Enter（与可选的空格）选中、类型搜索。
+ * 返回是否处理了这个按键（处理了就该 preventDefault）；Enter / 空格选中时 onSelect 收到被选的值
+ */
+export declare function handleListKeydown<T>(list: ListState<T>, event: KeyboardEvent, { space, typeahead, homeEnd }?: ListKeydownOptions, onSelect?: (value: string) => void): boolean;

package/dist/input/list-state.js

@@ -0,0 +1,186 @@
+import { clamp } from "../utils/data/number.js";
+import { useLang } from "../config/context.js";
+import { announce } from "../utils/dom/announcer.js";
+import { toggleSelection } from "../utils/data/selection.js";
+import { isComposingKey } from "../utils/dom/hotkeys.js";
+import { createTypeahead } from "../utils/dom/typeahead.js";
+import { computed, onScopeDispose, ref, watch } from "vue";
+//#region src/input/list-state.ts
+/**
+* 选项列表的状态（WAI-ARIA Listbox 的数据层）：选项、高亮项、已选项、键盘移动、类型搜索。
+* 不碰 DOM：Listbox、Select、Combobox 各自决定焦点在哪（列表自己、触发按钮、输入框），
+* 高亮项用 aria-activedescendant 告诉读屏（焦点不动，Combobox 才能边输入边选）。参考 React Aria 的 useListState。
+*
+*   const list = useListState({ items: () => users, toOption: (user) => ({ value: user.id, label: user.name }),
+*     selected: () => [value], mode: () => 'single', onChange });
+*   if (handleListKeydown(list, event, { space: true, typeahead: true })) event.preventDefault();
+*/
+/**
+* 一项数据的选项：给了 toOption 用它；没给时数据本身是 ListboxOption，或是字符串（值与文字都是它，
+* `items={['设计', '研发']}` 这样的简单列表不用先 map 成 { value, label }）
+*/
+function toListboxOption(item, toOption) {
+	if (toOption) return toOption(item);
+	return typeof item === "string" ? {
+		value: item,
+		label: item
+	} : item;
+}
+/**
+* 按值查已选项的显示信息（在 setup 里调用）：Select、Combobox、TagsInput 显示已选项的文字都用它。
+* 记住见过的已选项：远程搜索、过滤、分页把 items 换掉之后，不在当前 items 里的已选项仍按之前见过的文字显示，
+* 不会退化成值本身（工号、id）。只记已选的值，不随 items 增长
+*/
+function useSelectedOptions(read) {
+	const index = computed(() => {
+		const map = /* @__PURE__ */ new Map();
+		for (const item of read.items()) {
+			const option = read.toOption(item);
+			map.set(option.value, {
+				...option,
+				item
+			});
+		}
+		return map;
+	});
+	const seen = /* @__PURE__ */ new Map();
+	return (values) => values.map((value) => {
+		const found = index.value.get(value);
+		if (found) {
+			seen.set(value, found);
+			return found;
+		}
+		return seen.get(value) ?? {
+			value,
+			label: value,
+			item: void 0
+		};
+	});
+}
+/** 按分组排序：没有分组的在前，各组按第一次出现的顺序，组内保持原顺序 */
+function grouped(options) {
+	if (!options.some((option) => option.group != null)) return options;
+	const order = /* @__PURE__ */ new Map([[void 0, []]]);
+	for (const option of options) {
+		const list = order.get(option.group) ?? [];
+		if (!order.has(option.group)) order.set(option.group, list);
+		list.push(option);
+	}
+	return [...order.values()].flat();
+}
+/** 列表状态（组件 setup 里调用） */
+function useListState(config) {
+	const active = ref();
+	const search = createTypeahead();
+	const options = computed(() => grouped(config.items().map((item) => {
+		return {
+			...toListboxOption(item, config.toOption),
+			item
+		};
+	})));
+	const indices = computed(() => new Map(options.value.map((option, index) => [option.value, index])));
+	const selected = computed(() => new Set(config.selected()));
+	const enabled = (options) => options.filter((option) => !option.disabled);
+	const state = {
+		get options() {
+			return options.value;
+		},
+		get active() {
+			return active.value !== void 0 && indices.value.has(active.value) ? active.value : void 0;
+		},
+		indexOf: (value) => indices.value.get(value) ?? -1,
+		isSelected: (value) => selected.value.has(value),
+		setActive(value) {
+			active.value = value;
+		},
+		activateDefault() {
+			const usable = enabled(state.options);
+			active.value = (usable.find((option) => state.isSelected(option.value)) ?? usable[0])?.value;
+		},
+		move(step) {
+			const usable = enabled(state.options);
+			if (!usable.length) return;
+			const index = usable.findIndex((option) => option.value === state.active);
+			let next;
+			if (step === "first") next = 0;
+			else if (step === "last") next = usable.length - 1;
+			else if (index < 0) next = step > 0 ? 0 : usable.length - 1;
+			else next = clamp(index + step, 0, usable.length - 1);
+			active.value = usable[next].value;
+		},
+		select(value) {
+			const option = state.options[state.indexOf(value)];
+			if (!option || option.disabled) return false;
+			const current = config.selected();
+			const next = toggleSelection(current, value, {
+				mode: config.mode(),
+				required: config.required?.() ?? false
+			});
+			if (next === current) return false;
+			config.onChange(next);
+			return true;
+		},
+		typeahead(key) {
+			const usable = enabled(state.options);
+			const index = usable.findIndex((option) => option.value === state.active);
+			const match = search.next(key, usable.map((option) => option.label), index);
+			if (match < 0) return false;
+			active.value = usable[match].value;
+			return true;
+		}
+	};
+	return state;
+}
+/** 搜索词停下多久之后播报结果条数（毫秒）：不在每打一个字时都念 */
+var RESULT_ANNOUNCE_DELAY = 500;
+/**
+* 输入搜索词后给读屏播报结果条数（“12 个选项”“没有匹配的选项”），停顿一会儿再念（在 setup 里调用）。
+* WAI-ARIA 的组合框模式里看不见列表的读屏用户靠它知道过滤的结果；Select 的搜索框、Combobox 用它
+*/
+function useResultAnnouncement(read) {
+	const lang = useLang();
+	let timer;
+	watch(() => read().query, (query) => {
+		clearTimeout(timer);
+		if (!query) return;
+		timer = setTimeout(() => {
+			const { count } = read();
+			announce(count > 0 ? lang.listResultCount(count) : lang.selectNoMatch);
+		}, RESULT_ANNOUNCE_DELAY);
+	});
+	onScopeDispose(() => clearTimeout(timer));
+}
+/** 一页移动几项（Page Up / Page Down） */
+var PAGE = 10;
+/**
+* 列表的键盘操作：↑↓ 移动、Home / End、Page Up / Page Down、Enter（与可选的空格）选中、类型搜索。
+* 返回是否处理了这个按键（处理了就该 preventDefault）；Enter / 空格选中时 onSelect 收到被选的值
+*/
+function handleListKeydown(list, event, { space = false, typeahead = false, homeEnd = true } = {}, onSelect) {
+	if (event.altKey || event.ctrlKey || event.metaKey || isComposingKey(event)) return false;
+	const moves = {
+		ArrowDown: 1,
+		ArrowUp: -1,
+		Home: "first",
+		End: "last",
+		PageDown: PAGE,
+		PageUp: -10
+	};
+	const move = homeEnd || event.key !== "Home" && event.key !== "End" ? moves[event.key] : void 0;
+	if (move !== void 0) {
+		list.move(move);
+		return true;
+	}
+	if (event.key === "Enter" || space && event.key === " ") {
+		const value = list.active;
+		if (value === void 0) return event.key === " ";
+		list.select(value);
+		onSelect?.(value);
+		return true;
+	}
+	return typeahead ? list.typeahead(event.key) : false;
+}
+//#endregion
+export { handleListKeydown, toListboxOption, useListState, useResultAnnouncement, useSelectedOptions };
+
+//# sourceMappingURL=list-state.js.map

package/dist/input/list-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-state.js","names":[],"sources":["../../src/input/list-state.ts"],"sourcesContent":["/**\n * 选项列表的状态（WAI-ARIA Listbox 的数据层）：选项、高亮项、已选项、键盘移动、类型搜索。\n * 不碰 DOM：Listbox、Select、Combobox 各自决定焦点在哪（列表自己、触发按钮、输入框），\n * 高亮项用 aria-activedescendant 告诉读屏（焦点不动，Combobox 才能边输入边选）。参考 React Aria 的 useListState。\n *\n *   const list = useListState({ items: () => users, toOption: (user) => ({ value: user.id, label: user.name }),\n *     selected: () => [value], mode: () => 'single', onChange });\n *   if (handleListKeydown(list, event, { space: true, typeahead: true })) event.preventDefault();\n */\nimport { computed, onScopeDispose, ref, watch } from 'vue';\nimport { useLang } from '../config/context';\nimport { announce } from '../utils/dom/announcer';\nimport type { IconData } from '../base/Icon';\nimport { isComposingKey } from '../utils/dom/hotkeys';\nimport { clamp } from '../utils/data/number';\nimport { toggleSelection, type SelectionModes } from '../utils/data/selection';\nimport { createTypeahead } from '../utils/dom/typeahead';\n\n/** 一个选项 */\nexport interface ListboxOption {\n  /** 值：选中后写回的就是它，同一列表里不能重复 */\n  value: string;\n  /** 显示的文字；类型搜索、Combobox 过滤、Select 触发框里显示的都是它 */\n  label: string;\n  /** 不可用：可以被方向键经过（读屏能听到），不能选中 */\n  disabled?: boolean;\n  /** 文字下方的说明 */\n  description?: string;\n  /** 文字前的图标 */\n  icon?: IconData;\n  /** 分组名：同名的选项排在一组，组名显示在组的第一行 */\n  group?: string;\n}\n\n/** 列表里的一项：选项的显示信息，加上它来自的原始数据 */\nexport interface ListStateEntry<T> extends ListboxOption {\n  /** items 里对应的那一项：自定义渲染、renderValue 拿到的就是它 */\n  readonly item: T;\n}\n\n/**\n * 数据 → 选项的显示信息：items 已经是 ListboxOption 时可以不写，否则必填。\n * 后端数据直接传给 items，不用先 map 成 { value, label }：\n *   <Select items={users} toOption={(user) => ({ value: user.id, label: user.name })} />\n */\nexport type OptionMapping<T> = [T] extends [ListboxOption | string]\n  ? {\n      /** 数据 → 选项（值、文字、不可用、分组…）；items 是 ListboxOption 或字符串时可以不写 */\n      toOption?: (item: T) => ListboxOption;\n    }\n  : {\n      /** 数据 → 选项（值、文字、不可用、分组…） */\n      toOption: (item: T) => ListboxOption;\n    };\n\n/**\n * 一项数据的选项：给了 toOption 用它；没给时数据本身是 ListboxOption，或是字符串（值与文字都是它，\n * `items={['设计', '研发']}` 这样的简单列表不用先 map 成 { value, label }）\n */\nexport function toListboxOption<T>(item: T, toOption?: (item: T) => ListboxOption): ListboxOption {\n  if (toOption) return toOption(item);\n  return typeof item === 'string' ? { value: item, label: item } : (item as ListboxOption);\n}\n\n/** 已选值对应的选项：item 是它来自的数据；从没在 items 里见过的值（自定义的、还没加载的）item 为 undefined */\nexport interface SelectedOption<T> extends ListboxOption {\n  /** 来自的数据 */\n  item: T | undefined;\n}\n\n/**\n * 按值查已选项的显示信息（在 setup 里调用）：Select、Combobox、TagsInput 显示已选项的文字都用它。\n * 记住见过的已选项：远程搜索、过滤、分页把 items 换掉之后，不在当前 items 里的已选项仍按之前见过的文字显示，\n * 不会退化成值本身（工号、id）。只记已选的值，不随 items 增长\n */\nexport function useSelectedOptions<T>(read: {\n  /** 数据 */\n  items: () => readonly T[];\n  /** 数据 → 选项 */\n  toOption: (item: T) => ListboxOption;\n}): (values: readonly string[]) => SelectedOption<T>[] {\n  // 按值建索引：items 变了才重建，选择变化时只查表\n  const index = computed(() => {\n    const map = new Map<string, SelectedOption<T>>();\n    for (const item of read.items()) {\n      const option = read.toOption(item);\n      map.set(option.value, { ...option, item });\n    }\n    return map;\n  });\n  const seen = new Map<string, SelectedOption<T>>();\n  return (values) =>\n    values.map((value) => {\n      const found = index.value.get(value);\n      if (found) {\n        seen.set(value, found);\n        return found;\n      }\n      return seen.get(value) ?? { value, label: value, item: undefined };\n    });\n}\n\n/**\n * useListState 的选项。按字段给读取函数（不是一个返回整个对象的 read）：\n * 选项上万时，选择变了不该重新整理选项，各字段要分开追踪依赖\n */\nexport interface ListStateOptions<T> {\n  /** 数据 */\n  items: () => readonly T[];\n  /** 数据 → 选项；不写时 items 本身就是 ListboxOption。在 computed 里调用，读到的 props 会被追踪 */\n  toOption?: (item: T) => ListboxOption;\n  /** 已选的值 */\n  selected: () => readonly string[];\n  /** 单选或多选 */\n  mode: () => keyof SelectionModes;\n  /** 至少保留一项（单选时再点已选项不取消） */\n  required?: () => boolean;\n  /** 选择变化 */\n  onChange: (values: readonly string[]) => void;\n}\n\n/** 列表的状态与操作 */\nexport interface ListState<T> {\n  /** 按分组排好的选项：渲染与键盘移动都按这个顺序 */\n  readonly options: readonly ListStateEntry<T>[];\n  /** 高亮（键盘或指针所在）的选项的值 */\n  readonly active: string | undefined;\n  /** 值在 options 里的位置；不在时 -1 */\n  indexOf(value: string): number;\n  /** 是否已选 */\n  isSelected(value: string): boolean;\n  /** 设置高亮项；undefined 取消高亮 */\n  setActive(value: string | undefined): void;\n  /** 高亮已选的第一项，没有已选时高亮第一个可用项（打开下拉、列表获得焦点时） */\n  activateDefault(): void;\n  /** 移动高亮：±n 项（到头时停住），或到第一项 / 最后一项；跳过不可用的项 */\n  move(step: number | 'first' | 'last'): void;\n  /** 切换一项的选中（不可用的项忽略）；返回是否发生了变化 */\n  select(value: string): boolean;\n  /** 类型搜索：按下一个字符，高亮以它开头的项；返回是否命中 */\n  typeahead(key: string): boolean;\n}\n\n/** 按分组排序：没有分组的在前，各组按第一次出现的顺序，组内保持原顺序 */\nfunction grouped<O extends ListboxOption>(options: readonly O[]): readonly O[] {\n  if (!options.some((option) => option.group != null)) return options;\n  const order = new Map<string | undefined, O[]>([[undefined, []]]);\n  for (const option of options) {\n    const list = order.get(option.group) ?? [];\n    if (!order.has(option.group)) order.set(option.group, list);\n    list.push(option);\n  }\n  return [...order.values()].flat();\n}\n\n/** 列表状态（组件 setup 里调用） */\nexport function useListState<T>(config: ListStateOptions<T>): ListState<T> {\n  const active = ref<string | undefined>();\n  const search = createTypeahead();\n  // 选项多（上万）时这些每次渲染要读很多遍：缓存起来，数据或选择变了才重算\n  const options = computed(() =>\n    grouped(\n      config.items().map((item): ListStateEntry<T> => {\n        const option = toListboxOption(item, config.toOption);\n        return { ...option, item };\n      }),\n    ),\n  );\n  const indices = computed(\n    () => new Map(options.value.map((option, index) => [option.value, index])),\n  );\n  const selected = computed(() => new Set(config.selected()));\n\n  const enabled = (options: readonly ListStateEntry<T>[]) =>\n    options.filter((option) => !option.disabled);\n\n  const state: ListState<T> = {\n    get options() {\n      return options.value;\n    },\n    get active() {\n      // 选项变了（过滤、异步加载）后高亮项可能已经不在了\n      return active.value !== undefined && indices.value.has(active.value)\n        ? active.value\n        : undefined;\n    },\n    indexOf: (value) => indices.value.get(value) ?? -1,\n    isSelected: (value) => selected.value.has(value),\n    setActive(value) {\n      active.value = value;\n    },\n    activateDefault() {\n      const usable = enabled(state.options);\n      active.value = (usable.find((option) => state.isSelected(option.value)) ?? usable[0])?.value;\n    },\n    move(step) {\n      const usable = enabled(state.options);\n      if (!usable.length) return;\n      const index = usable.findIndex((option) => option.value === state.active);\n      let next: number;\n      if (step === 'first') next = 0;\n      else if (step === 'last') next = usable.length - 1;\n      else if (index < 0) next = step > 0 ? 0 : usable.length - 1;\n      else next = clamp(index + step, 0, usable.length - 1);\n      active.value = usable[next]!.value;\n    },\n    select(value) {\n      const option = state.options[state.indexOf(value)];\n      if (!option || option.disabled) return false;\n      const current = config.selected();\n      const next = toggleSelection(current, value, {\n        mode: config.mode(),\n        required: config.required?.() ?? false,\n      });\n      if (next === current) return false;\n      config.onChange(next);\n      return true;\n    },\n    typeahead(key) {\n      const usable = enabled(state.options);\n      const index = usable.findIndex((option) => option.value === state.active);\n      const match = search.next(\n        key,\n        usable.map((option) => option.label),\n        index,\n      );\n      if (match < 0) return false;\n      active.value = usable[match]!.value;\n      return true;\n    },\n  };\n  return state;\n}\n\n/** 搜索词停下多久之后播报结果条数（毫秒）：不在每打一个字时都念 */\nconst RESULT_ANNOUNCE_DELAY = 500;\n\n/**\n * 输入搜索词后给读屏播报结果条数（“12 个选项”“没有匹配的选项”），停顿一会儿再念（在 setup 里调用）。\n * WAI-ARIA 的组合框模式里看不见列表的读屏用户靠它知道过滤的结果；Select 的搜索框、Combobox 用它\n */\nexport function useResultAnnouncement(read: () => { query: string; count: number }): void {\n  const lang = useLang();\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  watch(\n    () => read().query,\n    (query) => {\n      clearTimeout(timer);\n      if (!query) return;\n      timer = setTimeout(() => {\n        const { count } = read();\n        announce(count > 0 ? lang.listResultCount(count) : lang.selectNoMatch);\n      }, RESULT_ANNOUNCE_DELAY);\n    },\n  );\n  onScopeDispose(() => clearTimeout(timer));\n}\n\n/** handleListKeydown 的选项：不同的宿主（列表、触发按钮、输入框）对空格与字母的处理不同 */\nexport interface ListKeydownOptions {\n  /** 空格选中高亮项（列表、Select）；输入框里空格是文字，不选 */\n  space?: boolean;\n  /** 字母做类型搜索（列表、Select）；输入框里字母是文字 */\n  typeahead?: boolean;\n  /** Home / End 到第一项 / 最后一项，默认 true；输入框里它们移动光标 */\n  homeEnd?: boolean;\n}\n\n/** 一页移动几项（Page Up / Page Down） */\nconst PAGE = 10;\n\n/**\n * 列表的键盘操作：↑↓ 移动、Home / End、Page Up / Page Down、Enter（与可选的空格）选中、类型搜索。\n * 返回是否处理了这个按键（处理了就该 preventDefault）；Enter / 空格选中时 onSelect 收到被选的值\n */\nexport function handleListKeydown<T>(\n  list: ListState<T>,\n  event: KeyboardEvent,\n  { space = false, typeahead = false, homeEnd = true }: ListKeydownOptions = {},\n  onSelect?: (value: string) => void,\n): boolean {\n  if (event.altKey || event.ctrlKey || event.metaKey || isComposingKey(event)) return false;\n  const moves: Record<string, number | 'first' | 'last'> = {\n    ArrowDown: 1,\n    ArrowUp: -1,\n    Home: 'first',\n    End: 'last',\n    PageDown: PAGE,\n    PageUp: -PAGE,\n  };\n  const move =\n    homeEnd || (event.key !== 'Home' && event.key !== 'End') ? moves[event.key] : undefined;\n  if (move !== undefined) {\n    list.move(move);\n    return true;\n  }\n  if (event.key === 'Enter' || (space && event.key === ' ')) {\n    const value = list.active;\n    if (value === undefined) return event.key === ' ';\n    list.select(value);\n    onSelect?.(value);\n    return true;\n  }\n  return typeahead ? list.typeahead(event.key) : false;\n}\n"],"mappings":"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"}

package/dist/input/people.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 人员与组织选择器（PeoplePicker、PeoplePickerPanel）的数据：选的是人员、部门、岗位三种，数据由接入方的 source 提供。
+ *
+ *   const source: PeopleSource = {
+ *     children: (parent, signal) => http.get('/org/children', { query: { parent: parent?.id }, signal }),
+ *     search: (query, signal) => http.get('/org/search', { query: { q: query }, signal }),
+ *     positions: (signal) => http.get('/org/positions', { signal }),
+ *   };
+ *   <PeoplePicker source={source} _value={owners} />
+ *
+ * 选中的值是 PeopleEntry 的数组（带名字，回显不用再查）；同一个人、部门按 type + id 判断（peopleKey）。
+ * 组织架构不大、已经整棵在前端时用 localPeopleSource。
+ */
+/** 能选的类型 */
+export interface PeopleTypes {
+    /** 人员 */
+    user: unknown;
+    /** 部门：选中就是部门里的人（怎么展开由后端定） */
+    department: unknown;
+    /** 岗位（角色）：流程的岗位收件箱 */
+    position: unknown;
+}
+/** 能选的类型 */
+export type PeopleType = keyof PeopleTypes;
+/** 一个人员、部门或岗位 */
+export interface PeopleEntry {
+    /** 标识：同一种类型里唯一（工号、部门编码、岗位编码） */
+    id: string;
+    /** 类型 */
+    type: PeopleType;
+    /** 名字 */
+    name: string;
+    /** 说明：人员的部门与岗位、部门的上级路径；搜索结果里分辨同名的 */
+    description?: string;
+    /** 头像地址（人员）；没有时显示名字的头一个字 */
+    avatar?: string;
+    /** 部门下还有子部门或人员；false 时没有“下级”，不写时按有 */
+    hasChildren?: boolean;
+}
+/** 数据来源：接入方按自己的接口实现；signal 在换了部门、改了搜索词、关掉选择器时中止 */
+export interface PeopleSource {
+    /** 一个部门下的子部门与人员（部门在前）；parent 为 null 时是最上层 */
+    children(parent: PeopleEntry | null, signal: AbortSignal): Promise<readonly PeopleEntry[]>;
+    /** 按关键字搜，人员、部门、岗位都可以返回；不写时没有搜索框 */
+    search?(query: string, signal: AbortSignal): Promise<readonly PeopleEntry[]>;
+    /** 全部岗位；不写时没有“岗位”页 */
+    positions?(signal: AbortSignal): Promise<readonly PeopleEntry[]>;
+}
+/** 组织架构的一个节点：部门带着下级 */
+export interface PeopleNode extends PeopleEntry {
+    /** 子部门与人员 */
+    children?: readonly PeopleNode[];
+}
+/** 同一个人员、部门、岗位的键：类型加标识 */
+export declare const peopleKey: (entry: Pick<PeopleEntry, 'type' | 'id'>) => string;
+/** 去掉下级、只留这一项本身（写进选中的值、最近选过的） */
+declare const plain: ({ id, type, name, description, avatar, hasChildren }: PeopleEntry) => PeopleEntry;
+/**
+ * 整棵在前端的组织架构做成数据来源：示例、测试与规模不大的系统直接用。
+ * 搜索按名字与说明（不分大小写），岗位单独给；部门的 hasChildren 按有没有 children 填上
+ */
+export declare function localPeopleSource(tree: readonly PeopleNode[], positions?: readonly PeopleEntry[]): PeopleSource;
+/** 写进值里的一项：去掉下级与其他字段 */
+export declare const toPeopleValue: typeof plain;
+export {};

package/dist/input/people.js

@@ -0,0 +1,47 @@
+//#region src/input/people.ts
+/** 同一个人员、部门、岗位的键：类型加标识 */
+var peopleKey = (entry) => `${entry.type}:${entry.id}`;
+/** 去掉下级、只留这一项本身（写进选中的值、最近选过的） */
+var plain = ({ id, type, name, description, avatar, hasChildren }) => ({
+	id,
+	type,
+	name,
+	...description != null ? { description } : {},
+	...avatar != null ? { avatar } : {},
+	...hasChildren != null ? { hasChildren } : {}
+});
+/**
+* 整棵在前端的组织架构做成数据来源：示例、测试与规模不大的系统直接用。
+* 搜索按名字与说明（不分大小写），岗位单独给；部门的 hasChildren 按有没有 children 填上
+*/
+function localPeopleSource(tree, positions = []) {
+	const byKey = /* @__PURE__ */ new Map();
+	const all = [];
+	const visit = (level) => {
+		for (const node of level) {
+			byKey.set(peopleKey(node), node);
+			all.push(node);
+			visit(node.children ?? []);
+		}
+	};
+	visit(tree);
+	const view = (node) => plain(node.type === "department" ? {
+		...node,
+		hasChildren: !!node.children?.length
+	} : node);
+	const matches = (entry, text) => entry.name.toLocaleLowerCase().includes(text) || !!entry.description?.toLocaleLowerCase().includes(text);
+	return {
+		children: (parent) => Promise.resolve((parent ? byKey.get(peopleKey(parent))?.children ?? [] : tree).map(view)),
+		search: (query) => {
+			const text = query.trim().toLocaleLowerCase();
+			return Promise.resolve([...all.map(view), ...positions.map(plain)].filter((entry) => matches(entry, text)));
+		},
+		...positions.length > 0 ? { positions: () => Promise.resolve(positions.map(plain)) } : {}
+	};
+}
+/** 写进值里的一项：去掉下级与其他字段 */
+var toPeopleValue = plain;
+//#endregion
+export { localPeopleSource, peopleKey, toPeopleValue };
+
+//# sourceMappingURL=people.js.map

package/dist/input/people.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"people.js","names":[],"sources":["../../src/input/people.ts"],"sourcesContent":["/**\n * 人员与组织选择器（PeoplePicker、PeoplePickerPanel）的数据：选的是人员、部门、岗位三种，数据由接入方的 source 提供。\n *\n *   const source: PeopleSource = {\n *     children: (parent, signal) => http.get('/org/children', { query: { parent: parent?.id }, signal }),\n *     search: (query, signal) => http.get('/org/search', { query: { q: query }, signal }),\n *     positions: (signal) => http.get('/org/positions', { signal }),\n *   };\n *   <PeoplePicker source={source} _value={owners} />\n *\n * 选中的值是 PeopleEntry 的数组（带名字，回显不用再查）；同一个人、部门按 type + id 判断（peopleKey）。\n * 组织架构不大、已经整棵在前端时用 localPeopleSource。\n */\n\n/** 能选的类型 */\nexport interface PeopleTypes {\n  /** 人员 */\n  user: unknown;\n  /** 部门：选中就是部门里的人（怎么展开由后端定） */\n  department: unknown;\n  /** 岗位（角色）：流程的岗位收件箱 */\n  position: unknown;\n}\n\n/** 能选的类型 */\nexport type PeopleType = keyof PeopleTypes;\n\n/** 一个人员、部门或岗位 */\nexport interface PeopleEntry {\n  /** 标识：同一种类型里唯一（工号、部门编码、岗位编码） */\n  id: string;\n  /** 类型 */\n  type: PeopleType;\n  /** 名字 */\n  name: string;\n  /** 说明：人员的部门与岗位、部门的上级路径；搜索结果里分辨同名的 */\n  description?: string;\n  /** 头像地址（人员）；没有时显示名字的头一个字 */\n  avatar?: string;\n  /** 部门下还有子部门或人员；false 时没有“下级”，不写时按有 */\n  hasChildren?: boolean;\n}\n\n/** 数据来源：接入方按自己的接口实现；signal 在换了部门、改了搜索词、关掉选择器时中止 */\nexport interface PeopleSource {\n  /** 一个部门下的子部门与人员（部门在前）；parent 为 null 时是最上层 */\n  children(parent: PeopleEntry | null, signal: AbortSignal): Promise<readonly PeopleEntry[]>;\n  /** 按关键字搜，人员、部门、岗位都可以返回；不写时没有搜索框 */\n  search?(query: string, signal: AbortSignal): Promise<readonly PeopleEntry[]>;\n  /** 全部岗位；不写时没有“岗位”页 */\n  positions?(signal: AbortSignal): Promise<readonly PeopleEntry[]>;\n}\n\n/** 组织架构的一个节点：部门带着下级 */\nexport interface PeopleNode extends PeopleEntry {\n  /** 子部门与人员 */\n  children?: readonly PeopleNode[];\n}\n\n/** 同一个人员、部门、岗位的键：类型加标识 */\nexport const peopleKey = (entry: Pick<PeopleEntry, 'type' | 'id'>) => `${entry.type}:${entry.id}`;\n\n/** 去掉下级、只留这一项本身（写进选中的值、最近选过的） */\nconst plain = ({ id, type, name, description, avatar, hasChildren }: PeopleEntry): PeopleEntry => ({\n  id,\n  type,\n  name,\n  ...(description != null ? { description } : {}),\n  ...(avatar != null ? { avatar } : {}),\n  ...(hasChildren != null ? { hasChildren } : {}),\n});\n\n/**\n * 整棵在前端的组织架构做成数据来源：示例、测试与规模不大的系统直接用。\n * 搜索按名字与说明（不分大小写），岗位单独给；部门的 hasChildren 按有没有 children 填上\n */\nexport function localPeopleSource(\n  tree: readonly PeopleNode[],\n  positions: readonly PeopleEntry[] = [],\n): PeopleSource {\n  const byKey = new Map<string, PeopleNode>();\n  const all: PeopleNode[] = [];\n  const visit = (level: readonly PeopleNode[]) => {\n    for (const node of level) {\n      byKey.set(peopleKey(node), node);\n      all.push(node);\n      visit(node.children ?? []);\n    }\n  };\n  visit(tree);\n  const view = (node: PeopleNode): PeopleEntry =>\n    plain(node.type === 'department' ? { ...node, hasChildren: !!node.children?.length } : node);\n  const matches = (entry: PeopleEntry, text: string) =>\n    entry.name.toLocaleLowerCase().includes(text) ||\n    !!entry.description?.toLocaleLowerCase().includes(text);\n  return {\n    children: (parent) =>\n      Promise.resolve((parent ? (byKey.get(peopleKey(parent))?.children ?? []) : tree).map(view)),\n    search: (query) => {\n      const text = query.trim().toLocaleLowerCase();\n      return Promise.resolve(\n        [...all.map(view), ...positions.map(plain)].filter((entry) => matches(entry, text)),\n      );\n    },\n    ...(positions.length > 0 ? { positions: () => Promise.resolve(positions.map(plain)) } : {}),\n  };\n}\n\n/** 写进值里的一项：去掉下级与其他字段 */\nexport const toPeopleValue = plain;\n"],"mappings":";;AA4DA,IAAa,aAAa,UAA4C,GAAG,MAAM,KAAI,GAAI,MAAM;;AAG7F,IAAM,SAAS,EAAE,IAAI,MAAM,MAAM,aAAa,QAAQ,mBAA6C;CACjG;CACA;CACA;CACA,GAAI,eAAe,OAAO,EAAE,YAAY,IAAI,CAAC;CAC7C,GAAI,UAAU,OAAO,EAAE,OAAO,IAAI,CAAC;CACnC,GAAI,eAAe,OAAO,EAAE,YAAY,IAAI,CAAC;AAC/C;;;;;AAMA,SAAgB,kBACd,MACA,YAAoC,CAAA,GACtB;CACd,MAAM,wBAAQ,IAAI,IAAwB;CAC1C,MAAM,MAAoB,CAAA;CAC1B,MAAM,SAAS,UAAiC;EAC9C,KAAK,MAAM,QAAQ,OAAO;GACxB,MAAM,IAAI,UAAU,IAAI,GAAG,IAAI;GAC/B,IAAI,KAAK,IAAI;GACb,MAAM,KAAK,YAAY,CAAA,CAAE;EAC3B;CACF;CACA,MAAM,IAAI;CACV,MAAM,QAAQ,SACZ,MAAM,KAAK,SAAS,eAAe;EAAE,GAAG;EAAM,aAAa,CAAC,CAAC,KAAK,UAAU;CAAO,IAAI,IAAI;CAC7F,MAAM,WAAW,OAAoB,SACnC,MAAM,KAAK,kBAAkB,CAAC,CAAC,SAAS,IAAI,KAC5C,CAAC,CAAC,MAAM,aAAa,kBAAkB,CAAC,CAAC,SAAS,IAAI;CACxD,OAAO;EACL,WAAW,WACT,QAAQ,SAAS,SAAU,MAAM,IAAI,UAAU,MAAM,CAAC,CAAC,EAAE,YAAY,CAAA,IAAM,KAAA,CAAM,IAAI,IAAI,CAAC;EAC5F,SAAS,UAAU;GACjB,MAAM,OAAO,MAAM,KAAK,CAAC,CAAC,kBAAkB;GAC5C,OAAO,QAAQ,QACb,CAAC,GAAG,IAAI,IAAI,IAAI,GAAG,GAAG,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,UAAU,QAAQ,OAAO,IAAI,CAAC,CACpF;EACF;EACA,GAAI,UAAU,SAAS,IAAI,EAAE,iBAAiB,QAAQ,QAAQ,UAAU,IAAI,KAAK,CAAC,EAAE,IAAI,CAAC;CAC3F;AACF;;AAGA,IAAa,gBAAgB"}

package/dist/input/remote-items.d.ts

@@ -0,0 +1,20 @@
+/** 远程选项的加载函数：搜索词 → 选项；signal 在被后来的请求顶掉、组件卸载时中止 */
+export type OptionsLoader<T> = (query: string, signal: AbortSignal) => Promise<readonly T[]>;
+/** 远程选项的状态；没给 load 时原样用 items */
+export declare function useRemoteItems<T>(read: {
+    /** 加载函数；没有时不请求 */
+    load: () => OptionsLoader<T> | undefined;
+    /** 当前的搜索词 */
+    query: () => string;
+    /** 弹层是否打开 */
+    open: () => boolean;
+    /** 本地的选项（有 load 时是第一次结果之前的选项） */
+    items: () => readonly T[];
+}): {
+    /** 当前的选项 */
+    items: () => readonly T[];
+    /** 正在请求 */
+    loading: () => boolean;
+    /** 最后一次请求失败的原因 */
+    error: () => unknown;
+};

package/dist/input/remote-items.js

@@ -0,0 +1,36 @@
+import { useRequest } from "../utils/request/use-request.js";
+import { watch } from "vue";
+//#region src/input/remote-items.ts
+/**
+* 远程选项（Select、Combobox、TreeSelect 的 load）：弹层打开时按当前搜索词请求，之后搜索词变了停下 300 ms 再请求；
+* 只采用最后一次的结果（useRequest），结果代替 items。弹层关着不请求。
+* 第一次结果回来之前用 items：编辑页把已选的那一项放进 items，触发框一开始就有文字。
+*/
+/** 搜索词停下多久再请求（毫秒） */
+var DEBOUNCE = 300;
+/** 远程选项的状态；没给 load 时原样用 items */
+function useRemoteItems(read) {
+	const request = useRequest((query, signal) => read.load()(query, signal), {
+		params: () => read.query(),
+		debounce: DEBOUNCE,
+		immediate: false,
+		enabled: () => read.load() != null && read.open()
+	});
+	watch(read.open, (open) => {
+		if (!read.load()) return;
+		if (open) request.refresh();
+		else request.cancel();
+	}, { immediate: true });
+	return {
+		/** 当前的选项 */
+		items: () => read.load() ? request.data ?? read.items() : read.items(),
+		/** 正在请求 */
+		loading: () => request.loading,
+		/** 最后一次请求失败的原因 */
+		error: () => request.error
+	};
+}
+//#endregion
+export { useRemoteItems };
+
+//# sourceMappingURL=remote-items.js.map

package/dist/input/remote-items.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-items.js","names":[],"sources":["../../src/input/remote-items.ts"],"sourcesContent":["/**\n * 远程选项（Select、Combobox、TreeSelect 的 load）：弹层打开时按当前搜索词请求，之后搜索词变了停下 300 ms 再请求；\n * 只采用最后一次的结果（useRequest），结果代替 items。弹层关着不请求。\n * 第一次结果回来之前用 items：编辑页把已选的那一项放进 items，触发框一开始就有文字。\n */\nimport { watch } from 'vue';\nimport { useRequest } from '../utils/request/use-request';\n\n/** 远程选项的加载函数：搜索词 → 选项；signal 在被后来的请求顶掉、组件卸载时中止 */\nexport type OptionsLoader<T> = (query: string, signal: AbortSignal) => Promise<readonly T[]>;\n\n/** 搜索词停下多久再请求（毫秒） */\nconst DEBOUNCE = 300;\n\n/** 远程选项的状态；没给 load 时原样用 items */\nexport function useRemoteItems<T>(read: {\n  /** 加载函数；没有时不请求 */\n  load: () => OptionsLoader<T> | undefined;\n  /** 当前的搜索词 */\n  query: () => string;\n  /** 弹层是否打开 */\n  open: () => boolean;\n  /** 本地的选项（有 load 时是第一次结果之前的选项） */\n  items: () => readonly T[];\n}) {\n  const request = useRequest((query: string, signal) => read.load()!(query, signal), {\n    params: () => read.query(),\n    debounce: DEBOUNCE,\n    immediate: false,\n    enabled: () => read.load() != null && read.open(),\n  });\n  // 打开时立即按当前搜索词请求（不等防抖），一开始就是打开的也算；关闭时取消还在进行的\n  watch(\n    read.open,\n    (open) => {\n      if (!read.load()) return;\n      if (open) void request.refresh();\n      else request.cancel();\n    },\n    { immediate: true },\n  );\n  return {\n    /** 当前的选项 */\n    items: (): readonly T[] => (read.load() ? (request.data ?? read.items()) : read.items()),\n    /** 正在请求 */\n    loading: () => request.loading,\n    /** 最后一次请求失败的原因 */\n    error: () => request.error,\n  };\n}\n"],"mappings":";;;;;;;;;AAYA,IAAM,WAAW;;AAGjB,SAAgB,eAAkB,MAS/B;CACD,MAAM,UAAU,YAAY,OAAe,WAAW,KAAK,KAAK,CAAC,CAAE,OAAO,MAAM,GAAG;EACjF,cAAc,KAAK,MAAM;EACzB,UAAU;EACV,WAAW;EACX,eAAe,KAAK,KAAK,KAAK,QAAQ,KAAK,KAAK;CAClD,CAAC;CAED,MACE,KAAK,OACJ,SAAS;EACR,IAAI,CAAC,KAAK,KAAK,GAAG;EAClB,IAAI,MAAM,QAAa,QAAQ;OAC1B,QAAQ,OAAO;CACtB,GACA,EAAE,WAAW,KAAK,CACpB;CACA,OAAO;;EAEL,aAA4B,KAAK,KAAK,IAAK,QAAQ,QAAQ,KAAK,MAAM,IAAK,KAAK,MAAM;;EAEtF,eAAe,QAAQ;;EAEvB,aAAa,QAAQ;CACvB;AACF"}

package/dist/input/text-format.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 输入时自动分组显示的格式：值是去掉分隔的原文（13800001111），输入框里显示分好组的文字（138 0000 1111），
+ * 交给 TextField 的 format。手机号、身份证号、银行卡号有现成的，别的用 createGroupedFormat 写。
+ *
+ *   <TextField _value={phone} format={phoneFormat} />          // phone === '13800001111'
+ *   <TextField _value={card} format={createGroupedFormat({ groups: [4, 4, 4, 4, 3] })} />
+ *
+ * 只按位置分组、过滤字符，不校验内容（号段、校验位）：校验写在表单的 schema 里（phoneSchema、idCardSchema）。
+ */
+/** TextField 的显示格式 */
+export interface TextFormat {
+    /** 原文 → 显示的文字 */
+    format: (raw: string) => string;
+    /** 输入框里的文字 → 原文（去掉分隔、过滤掉不接受的字符、截到最长） */
+    parse: (text: string) => string;
+    /** 手机上弹出的键盘 */
+    inputmode?: 'numeric' | 'text' | 'tel';
+}
+/** createGroupedFormat 的选项 */
+export interface GroupedFormatOptions {
+    /** 各组的长度：[3, 4, 4] 是 3-4-4；最后一组之后的字符再按最后一组的长度接着分 */
+    groups: readonly number[];
+    /** 接受的字符，默认数字 */
+    accept?: RegExp;
+    /** 原文最长几位；默认是各组加起来 */
+    maxLength?: number;
+    /** 组之间的分隔，默认一个空格 */
+    separator?: string;
+    /** 字母转成大写（身份证的 X） */
+    uppercase?: boolean;
+    /** 手机上弹出的键盘，默认 numeric */
+    inputmode?: TextFormat['inputmode'];
+}
+/** 按位置分组的格式 */
+export declare function createGroupedFormat({ groups, accept, maxLength, separator, uppercase, inputmode, }: GroupedFormatOptions): TextFormat;
+/** 中国大陆手机号：3-4-4，11 位数字 */
+export declare const phoneFormat: TextFormat;
+/** 居民身份证号：6-8-4（地区、出生日期、顺序码与校验位），最后一位可以是 X */
+export declare const idCardFormat: TextFormat;
+/** 银行卡号：每 4 位一组，最长 19 位 */
+export declare const bankCardFormat: TextFormat;
+/**
+ * 原文里第 count 个字符之后，对应显示文字里的位置：重新格式化之后把光标放回原来那个字符的后面
+ * （在 1380|0001111 打一个字，光标停在新字符后面，而不是跳到最后）
+ */
+export declare function displayPosition(format: TextFormat, raw: string, count: number): number;

package/dist/input/text-format.js

@@ -0,0 +1,64 @@
+//#region src/input/text-format.ts
+/** 按位置分组的格式 */
+function createGroupedFormat({ groups, accept = /\d/, maxLength = groups.reduce((sum, size) => sum + size, 0), separator = " ", uppercase = false, inputmode = "numeric" }) {
+	const one = new RegExp(accept.source, accept.flags.replace("g", ""));
+	return {
+		inputmode,
+		parse: (text) => {
+			return Array.from(uppercase ? text.toUpperCase() : text).filter((char) => one.test(char)).slice(0, maxLength).join("");
+		},
+		format: (raw) => {
+			const parts = [];
+			let rest = raw;
+			for (let index = 0; rest; index++) {
+				const size = groups[Math.min(index, groups.length - 1)];
+				parts.push(rest.slice(0, size));
+				rest = rest.slice(size);
+			}
+			return parts.join(separator);
+		}
+	};
+}
+/** 中国大陆手机号：3-4-4，11 位数字 */
+var phoneFormat = {
+	...createGroupedFormat({ groups: [
+		3,
+		4,
+		4
+	] }),
+	inputmode: "tel"
+};
+/** 居民身份证号：6-8-4（地区、出生日期、顺序码与校验位），最后一位可以是 X */
+var idCardFormat = createGroupedFormat({
+	groups: [
+		6,
+		8,
+		4
+	],
+	accept: /[\dXx]/,
+	uppercase: true,
+	inputmode: "text"
+});
+/** 银行卡号：每 4 位一组，最长 19 位 */
+var bankCardFormat = createGroupedFormat({
+	groups: [4],
+	maxLength: 19
+});
+/**
+* 原文里第 count 个字符之后，对应显示文字里的位置：重新格式化之后把光标放回原来那个字符的后面
+* （在 1380|0001111 打一个字，光标停在新字符后面，而不是跳到最后）
+*/
+function displayPosition(format, raw, count) {
+	if (count <= 0) return 0;
+	const shown = format.format(raw);
+	let seen = 0;
+	for (let index = 0; index < shown.length; index++) {
+		if (format.parse(shown[index]) !== "") seen++;
+		if (seen === count) return index + 1;
+	}
+	return shown.length;
+}
+//#endregion
+export { bankCardFormat, createGroupedFormat, displayPosition, idCardFormat, phoneFormat };
+
+//# sourceMappingURL=text-format.js.map