@tianyr/schema-antd 0.1.0 → 0.1.1

package/dist/biz-select/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * BizSelect 的类型契约。
+ *
+ * 对外只有一个「数据源」概念：能给出候选、能按编码解析名称。
+ * 具体是前端常量、一次拉全量还是关键词翻页，由源**提供了哪些能力**决定，
+ * 不再用 kind 之类的标签分类。
+ */
+import type { ReactNode } from 'react';
+import type { SelectProps } from 'antd';
+export type SelectCode = string | number;
+/** 契约层的标准选项；后端字段换名在 adapter 层做，不污染组件 */
+export interface BizOption<T = unknown> {
+    code: SelectCode;
+    name?: string;
+    disabled?: boolean;
+    /** 原始接口记录，原样带回给业务回调 */
+    raw?: T;
+}
+/** 展示模式：编码 / 编码-名称 / 名称 */
+export type DisplayMode = 'V' | 'V-L' | 'L';
+/** 前端过滤时匹配哪些字段 */
+export type SearchFields = 'code' | 'name' | 'both';
+/** 值形态：标量编码，或自带名称的对象 */
+export type ValueMode = 'primitive' | 'object';
+/**
+ * 对象值里哪个键装编码、哪个装名称。
+ * 默认 `{ code: 'value', name: 'label' }`，兼容存量 `{ value, label }` 协议。
+ */
+export interface ValueFieldMap {
+    code?: string;
+    name?: string;
+}
+export type SelectParams = Record<string, unknown>;
+/** 对象形态的值；具体键名由 valueFields 决定，所以只能约束到 Record */
+export type BizObjectValue = Record<string, unknown>;
+/**
+ * 数据源契约。只有能力声明，不认识 URL、method、低代码控件配置。
+ *
+ * 行为推导：
+ * - 只有 `options` → 同步全集，前端过滤
+ * - 只有 `load` → 需要时加载一次，前端过滤
+ * - 只有 `search` → 后端过滤
+ * - `load` + `search` → 空关键词走 load 缓存，有关键词走后端
+ */
+export interface SelectSource<P extends SelectParams = SelectParams> {
+    /** 同步全集：纯前端常量，没有请求也没有 loading */
+    options?: BizOption[];
+    /** 异步全集：一次拉完，之后前端过滤 */
+    load?: (params: P, signal?: AbortSignal) => Promise<BizOption[]>;
+    /** 关键词搜索：分页接口固定取第一页 */
+    search?: (keyword: string, params: P, signal?: AbortSignal) => Promise<BizOption[]>;
+    /** 按编码精确查：远程回显，不能用模糊搜索冒充 */
+    resolve?: (code: SelectCode, params: P, signal?: AbortSignal) => Promise<BizOption | null>;
+    /** 缺任一参数就不发请求：用空条件查可能拿到别家数据 */
+    requiredParams?: string[];
+    /** 租户/权限隔离，参与缓存键 */
+    namespace?: () => string;
+}
+/**
+ * 受控通道与搜索协议由组件接管，这些属性传进来要么被静默忽略、要么直接把控件弄坏：
+ * - `searchValue`：antd 的受控搜索框，传了会锁死用户输入（组件自己维护 keyword）
+ * - `showSearch` / `filterOption` / `optionFilterProp` / `onSearch`：搜索行为由源的能力决定
+ * - `optionLabelProp`：标签取哪个字段由 displayMode 决定
+ */
+type BaseAntProps = Omit<SelectProps, 'value' | 'defaultValue' | 'onChange' | 'options' | 'labelInValue' | 'mode' | 'onSearch' | 'searchValue' | 'showSearch' | 'filterOption' | 'optionFilterProp' | 'optionLabelProp'>;
+/** 与 antd 无关的公共属性：可编辑与只读都吃这一份 */
+interface CoreProps {
+    /** 注册名或内联源；schema 里只能是字符串 */
+    source?: string | SelectSource;
+    /** 传给 load/search/resolve，参与缓存键 */
+    params?: SelectParams;
+    /** 下拉与回显文本，默认 L */
+    displayMode?: DisplayMode;
+    /** 前端过滤匹配的字段，缺省随 displayMode 推导 */
+    searchFields?: SearchFields;
+    /** 详情已带回的名称，省掉一次 resolve */
+    seedOptions?: BizOption[];
+    /** 远程搜索防抖，默认 300ms */
+    debounceMs?: number;
+    /** 内联源需要跨实例共享缓存时显式指定 */
+    cacheKey?: string;
+    /** 门禁提示文案 */
+    blockedText?: ReactNode;
+    valueMode?: ValueMode;
+    valueFields?: ValueFieldMap;
+}
+interface PrimitiveModeProps {
+    valueMode?: 'primitive';
+    value?: SelectCode | null;
+    onChange?: (value: SelectCode | undefined, option?: BizOption) => void;
+}
+interface ObjectModeProps {
+    valueMode: 'object';
+    value?: BizObjectValue | null;
+    onChange?: (value: BizObjectValue | undefined, option?: BizOption) => void;
+}
+export type BizSelectProps = CoreProps & BaseAntProps & (PrimitiveModeProps | ObjectModeProps);
+export interface BizSelectDisplayProps extends CoreProps {
+    value?: SelectCode | BizObjectValue | null;
+    /** 只读占位 */
+    emptyText?: ReactNode;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/biz-select/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/biz-select/types.ts"],"names":[],"mappings":"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"}

package/dist/{app-select → biz-select}/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/app-select/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/biz-select/types.ts"],"names":[],"mappings":""}

package/dist/biz-select/useCandidates.d.ts

@@ -0,0 +1,40 @@
+import type { BizOption, SearchFields, SelectParams, SelectSource } from './types.js';
+export interface UseCandidatesOptions {
+    /**
+     * 注册名或内联源。解析与来源键都在 Hook 内完成：
+     * 让调用方自己拼 sourceKey 就会绕开注册名的版本身份，组件和 Hook 表现不一致。
+     */
+    source?: string | SelectSource;
+    /** 内联源需要跨实例共享缓存时显式指定；注册名自带稳定键 */
+    cacheKey?: string;
+    params?: SelectParams;
+    /** 前端过滤匹配哪些字段 */
+    searchFields: SearchFields;
+    debounceMs?: number;
+}
+export interface UseCandidatesResult {
+    /** 解析后的来源键，和组件用的是同一个身份；要传给别的 Hook 时直接用它 */
+    sourceKey: string;
+    /** 当前该给下拉看的候选：本地过滤型已按 keyword 过滤 */
+    options: BizOption[];
+    /**
+     * 回显专用候选：优先取未过滤的全集。
+     * 已选中的项可能被关键词过滤掉，用它查名称才不会退回编码。
+     */
+    echoOptions: BizOption[];
+    /** 当前关键词：搜索中不要往结果里补回已选项 */
+    keyword: string;
+    loading: boolean;
+    error: boolean;
+    /** 缺少必需参数，主动不查 */
+    blocked: boolean;
+    /** 展开下拉：`load` 型在这里才发第一次请求 */
+    open(): void;
+    /** 输入关键词：后端搜索型防抖请求；本地过滤型只更新关键字 */
+    search(keyword: string): void;
+    /** 收起下拉时清掉关键字：不发请求，避免下次打开看到上次的过滤结果 */
+    resetKeyword(): void;
+    reload(): void;
+}
+export declare function useCandidates({ source: sourceProp, cacheKey, params, searchFields, debounceMs, }: UseCandidatesOptions): UseCandidatesResult;
+//# sourceMappingURL=useCandidates.d.ts.map

package/dist/biz-select/useCandidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCandidates.d.ts","sourceRoot":"","sources":["../../src/biz-select/useCandidates.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGnF,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC/B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,iBAAiB;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB;;;OAGG;IACH,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,IAAI,IAAI,IAAI,CAAC;IACb,kCAAkC;IAClC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,sCAAsC;IACtC,YAAY,IAAI,IAAI,CAAC;IACrB,MAAM,IAAI,IAAI,CAAC;CAChB;AAuBD,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EAAE,UAAU,EAClB,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,UAAgB,GACjB,EAAE,oBAAoB,GAAG,mBAAmB,CA0S5C"}

package/dist/biz-select/useCandidates.js

@@ -0,0 +1,292 @@
+/**
+ * 候选选项：加载、搜索、防抖、取消、参数失效。
+ *
+ * 关键约束（设计文档 §5.3）：**effect / useCallback 的依赖里不出现源对象和其中的函数**。
+ * 源一律从 ref 读，依赖只保留 sourceKey / paramsKey 这类字符串。
+ * 违反这条的直接后果是：父组件每渲染一次，列表里每个单元格各发一次请求。
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { dropCandidateCache, loadCandidatesWithCache } from './cache.js';
+import { candidatesCacheKey, paramsKeyOf } from './key.js';
+import { hasRequiredParams, normalizeSource } from './normalize.js';
+import { resolveSelectSource } from './registry.js';
+import { useStableSourceKey } from './useStableSourceKey.js';
+import { filterOptions } from './format.js';
+const EMPTY_OPTIONS = [];
+export function useCandidates({ source: sourceProp, cacheKey, params, searchFields, debounceMs = 300, }) {
+    const source = resolveSelectSource(sourceProp);
+    // 订阅版本在这里：失效 / 重注册后键会变，已挂载的实例才会重新取数
+    const sourceKey = useStableSourceKey(sourceProp, cacheKey);
+    const capability = normalizeSource(source);
+    const { candidateMode, requiredParams, needsFetch } = capability;
+    const paramsKey = paramsKeyOf(params);
+    const blocked = !hasRequiredParams(requiredParams, params);
+    // 源与参数只走 ref：它们可以每帧变化，但绝不能成为 effect 依赖
+    const sourceRef = useRef(source);
+    sourceRef.current = source;
+    const paramsRef = useRef(params);
+    paramsRef.current = params;
+    const scopeRef = useRef('');
+    scopeRef.current = source?.namespace?.() ?? '';
+    // 当前作用域参与结果归属判断：只进缓存键不够，租户切换后旧候选仍会显示
+    const scope = scopeRef.current;
+    const sourceKeyRef = useRef(sourceKey);
+    sourceKeyRef.current = sourceKey;
+    const [loadState, setLoadState] = useState(null);
+    const [searchState, setSearchState] = useState(null);
+    const [keyword, setKeyword] = useState('');
+    // reload 在回调里要读当前关键词，不能进依赖（否则每次输入都换新函数）
+    const keywordRef = useRef('');
+    keywordRef.current = keyword;
+    // load 与 search 各记一份：共用会互相覆盖，一个结束就把另一个的「进行中」抹掉
+    const [loadLoading, setLoadLoading] = useState(false);
+    const [searchLoading, setSearchLoading] = useState(false);
+    const [error, setError] = useState(false);
+    /** 递增表示「需要拉一次候选」：展开下拉或手动重载 */
+    const [loadTick, setLoadTick] = useState(0);
+    /** 下拉是否展开：纯搜索型只在展开时才跟着源 / 条件变化重查 */
+    const openedRef = useRef(false);
+    const seqRef = useRef(0);
+    const abortRef = useRef(null);
+    const timerRef = useRef(null);
+    const cancelPending = useCallback(() => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        abortRef.current?.abort();
+        abortRef.current = null;
+        // 作废版本号才是正确性保障：abort 只是优化，源不认 signal 时仍会 resolve，
+        // 那时 seq 已经对不上，不会把旧结果写成 error / 空列表
+        seqRef.current += 1;
+        // 被作废的请求不再回来收尾，loading 得在这里结束：否则关掉下拉后就一直转圈
+        setSearchLoading(false);
+    }, []);
+    useEffect(() => cancelPending, [cancelPending]);
+    // 加载全集：只在展开下拉之后发生，依赖全是字符串，源从 ref 取
+    useEffect(() => {
+        const current = sourceRef.current;
+        const load = current?.load;
+        // 上一次的请求被这次变更作废（cancelled）后不会自己收尾，提前返回时必须补关 loading
+        if (!loadTick || blocked || !load) {
+            setLoadLoading(false);
+            return;
+        }
+        const key = candidatesCacheKey(scope, sourceKey, paramsKey);
+        let cancelled = false;
+        setLoadLoading(true);
+        setError(false);
+        loadCandidatesWithCache(key, () => load(paramsRef.current ?? {}, undefined))
+            .then((list) => {
+            if (!cancelled)
+                setLoadState({ sourceKey, scope, paramsKey, list });
+        })
+            .catch(() => {
+            if (!cancelled) {
+                setLoadState({ sourceKey, scope, paramsKey, list: EMPTY_OPTIONS });
+                setError(true);
+            }
+        })
+            .finally(() => {
+            if (!cancelled)
+                setLoadLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [loadTick, sourceKey, scope, paramsKey, blocked, candidateMode]);
+    // 身份变化（条件 / 来源 / 租户）：取消在途请求，旧结果靠三元比对自动失效。
+    // scope 必须在这里：租户切了但 sourceKey、paramsKey 没变，在途请求照样得作废
+    useEffect(() => {
+        cancelPending();
+        setKeyword('');
+    }, [paramsKey, sourceKey, scope, cancelPending]);
+    const runSearch = useCallback((keywordValue, key) => {
+        // 缺必需参数一律不查。open / reload 是公开入口（树、弹窗也会调），
+        // 光靠组件上的 disabled 挡不住，守卫必须收在真正发请求的这一处
+        if (blocked)
+            return;
+        const current = sourceRef.current;
+        const search = current?.search;
+        if (!search)
+            return;
+        const seq = seqRef.current + 1;
+        seqRef.current = seq;
+        const controller = new AbortController();
+        abortRef.current = controller;
+        // 归属信息在发请求时定格：结果回来后要能证明它属于哪个源、哪个租户
+        const sourceKeyAtRequest = sourceKeyRef.current;
+        const scopeAtRequest = scopeRef.current;
+        setSearchLoading(true);
+        setError(false);
+        search(keywordValue, paramsRef.current ?? {}, controller.signal)
+            .then((list) => {
+            if (seq !== seqRef.current)
+                return;
+            setSearchState({
+                sourceKey: sourceKeyAtRequest,
+                scope: scopeAtRequest,
+                paramsKey: key,
+                keyword: keywordValue,
+                list,
+            });
+        })
+            .catch(() => {
+            if (seq !== seqRef.current)
+                return;
+            setSearchState({
+                sourceKey: sourceKeyAtRequest,
+                scope: scopeAtRequest,
+                paramsKey: key,
+                keyword: keywordValue,
+                list: EMPTY_OPTIONS,
+            });
+            setError(true);
+        })
+            .finally(() => {
+            if (seq === seqRef.current)
+                setSearchLoading(false);
+        });
+    }, [blocked]);
+    const search = useCallback((keywordValue) => {
+        setKeyword(keywordValue);
+        if (blocked || !needsFetch || candidateMode === 'load')
+            return;
+        if (candidateMode !== 'search' && candidateMode !== 'hybrid')
+            return;
+        cancelPending();
+        const key = paramsKeyOf(paramsRef.current);
+        timerRef.current = setTimeout(() => {
+            timerRef.current = null;
+            runSearch(keywordValue, key);
+        }, debounceMs);
+    }, [blocked, needsFetch, candidateMode, debounceMs, cancelPending, runSearch]);
+    const searchStateRef = useRef(null);
+    searchStateRef.current = searchState;
+    const open = useCallback(() => {
+        openedRef.current = true;
+        setLoadTick((tick) => tick + 1);
+        // 纯搜索型没有全集，展开时先取一次默认候选；已经取过就不重复请求
+        const current = sourceRef.current;
+        if (!current?.search || current.load)
+            return;
+        const key = paramsKeyOf(paramsRef.current);
+        const state = searchStateRef.current;
+        // 换了源或租户，旧结果不再代表当前范围，必须重查
+        if (!state ||
+            state.sourceKey !== sourceKeyRef.current ||
+            state.scope !== scopeRef.current ||
+            state.paramsKey !== key ||
+            state.keyword !== '') {
+            runSearch('', key);
+        }
+    }, [runSearch]);
+    /** 收起下拉：清关键字并作废在途搜索，避免关掉之后才回来的结果写进状态 */
+    const resetKeyword = useCallback(() => {
+        openedRef.current = false;
+        cancelPending();
+        setKeyword('');
+    }, [cancelPending]);
+    /** 手动重取：绕开缓存。有关键词就重跑搜索，否则重拉全集 */
+    const reload = useCallback(() => {
+        cancelPending();
+        const key = paramsKeyOf(paramsRef.current);
+        const current = sourceRef.current;
+        if (keywordRef.current && current?.search) {
+            runSearch(keywordRef.current, key);
+            return;
+        }
+        if (current?.load) {
+            // 先删缓存再 bump，否则 effect 跑起来又会命中同一份
+            dropCandidateCache(candidatesCacheKey(scopeRef.current, sourceKeyRef.current, key));
+            setLoadTick((tick) => tick + 1);
+            return;
+        }
+        if (current?.search)
+            runSearch('', key);
+    }, [cancelPending, runSearch]);
+    /**
+     * 纯搜索型没有 load effect 兜底：源失效、或父字段改了条件，而下拉还开着时，
+     * 旧候选会一直挂在列表里（可能是别的仓库的记录）。这里补一次重查。
+     * 带 load 的源由加载 effect 负责，不重复发请求。
+     */
+    const identityRef = useRef({ sourceKey, paramsKey, scope });
+    useEffect(() => {
+        const previous = identityRef.current;
+        identityRef.current = { sourceKey, paramsKey, scope };
+        if (!openedRef.current)
+            return;
+        if (previous.sourceKey === sourceKey &&
+            previous.paramsKey === paramsKey &&
+            previous.scope === scope) {
+            return;
+        }
+        const current = sourceRef.current;
+        if (!current?.search || current.load)
+            return;
+        runSearch('', paramsKeyOf(paramsRef.current));
+    }, [sourceKey, paramsKey, scope, runSearch]);
+    const loadValid = Boolean(loadState &&
+        loadState.sourceKey === sourceKey &&
+        loadState.scope === scope &&
+        loadState.paramsKey === paramsKey);
+    const searchValid = Boolean(searchState &&
+        searchState.sourceKey === sourceKey &&
+        searchState.scope === scope &&
+        searchState.paramsKey === paramsKey &&
+        searchState.keyword === keyword);
+    const options = useMemo(() => {
+        if (blocked || candidateMode === 'invalid' || candidateMode === 'none')
+            return EMPTY_OPTIONS;
+        // 同步全集也要过本地过滤：filterOption=false 已关掉 antd 自带过滤，
+        // 这里不处理的话静态源在输入框里根本筛不动
+        if (candidateMode === 'sync') {
+            return filterOptions(source?.options ?? EMPTY_OPTIONS, keyword, searchFields);
+        }
+        if (candidateMode === 'load') {
+            if (!loadValid || !loadState)
+                return EMPTY_OPTIONS;
+            // 全集已在前端，关键字只做本地过滤
+            return filterOptions(loadState.list, keyword, searchFields);
+        }
+        if (candidateMode === 'hybrid') {
+            if (keyword)
+                return searchValid && searchState ? searchState.list : EMPTY_OPTIONS;
+            return loadValid && loadState ? loadState.list : EMPTY_OPTIONS;
+        }
+        return searchValid && searchState ? searchState.list : EMPTY_OPTIONS;
+    }, [
+        blocked,
+        candidateMode,
+        source,
+        loadValid,
+        loadState,
+        searchValid,
+        searchState,
+        keyword,
+        searchFields,
+    ]);
+    // 回显要用未过滤的候选：已选项可能正好被关键词筛掉
+    const echoOptions = useMemo(() => {
+        if (candidateMode === 'sync')
+            return source?.options ?? EMPTY_OPTIONS;
+        if (loadValid && loadState)
+            return loadState.list;
+        // 纯搜索型没有全集，只能用手上这批
+        return options;
+    }, [candidateMode, source, loadValid, loadState, options]);
+    return {
+        sourceKey,
+        options,
+        echoOptions,
+        keyword,
+        loading: loadLoading || searchLoading,
+        error,
+        blocked,
+        open,
+        search,
+        resetKeyword,
+        reload,
+    };
+}
+//# sourceMappingURL=useCandidates.js.map

package/dist/biz-select/useCandidates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCandidates.js","sourceRoot":"","sources":["../../src/biz-select/useCandidates.ts"],"names":[],"mappings":"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"}

package/dist/biz-select/useSelectedLabel.d.ts

@@ -0,0 +1,18 @@
+import type { BizOption, SelectCode, SelectParams, SelectSource } from './types.js';
+export type SelectedStatus = 'empty' | 'loading' | 'resolved' | 'missing' | 'blocked' | 'error';
+export interface UseSelectedLabelOptions {
+    source?: SelectSource;
+    sourceKey: string;
+    code?: SelectCode;
+    /** 对象值里自带的名称 */
+    valueName?: string;
+    seedOptions?: BizOption[];
+    candidates?: BizOption[];
+    params?: SelectParams;
+}
+export interface UseSelectedLabelResult {
+    option: BizOption | null;
+    status: SelectedStatus;
+}
+export declare function useSelectedLabel({ source, sourceKey, code, valueName, seedOptions, candidates, params, }: UseSelectedLabelOptions): UseSelectedLabelResult;
+//# sourceMappingURL=useSelectedLabel.d.ts.map

package/dist/biz-select/useSelectedLabel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSelectedLabel.d.ts","sourceRoot":"","sources":["../../src/biz-select/useSelectedLabel.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEjF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEhG,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,gBAAgB;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;IAC1B,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,cAAc,CAAC;CACxB;AAyBD,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,SAAS,EACT,IAAI,EACJ,SAAS,EACT,WAAW,EACX,UAAU,EACV,MAAM,GACP,EAAE,uBAAuB,GAAG,sBAAsB,CAgJlD"}

package/dist/biz-select/useSelectedLabel.js

@@ -0,0 +1,158 @@
+/**
+ * 已选编码 → 名称的解析。
+ *
+ * 与关键词搜索是两条独立逻辑：搜索是模糊的，回显必须精确。
+ * 优先级（设计文档 §5.6）：对象值自带的名称 → seedOptions → 已加载候选
+ * → resolve(code) → 原样显示编码并暴露状态。
+ */
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { resolveCodeWithCache } from './cache.js';
+import { paramsKeyOf, resolveCacheKey } from './key.js';
+import { hasRequiredParams, normalizeSource } from './normalize.js';
+/** 编码比对统一走字符串：后端可能把 1 和 '1' 当同一个值 */
+function sameCode(a, b) {
+    return a !== undefined && b !== undefined && String(a) === String(b);
+}
+function codeKeyOf(code) {
+    return code === undefined || code === null ? '' : `${typeof code}:${code}`;
+}
+function findOption(list, code) {
+    return list?.find((item) => item.code === code);
+}
+export function useSelectedLabel({ source, sourceKey, code, valueName, seedOptions, candidates, params, }) {
+    const capability = normalizeSource(source);
+    const { canResolve, requiredParams } = capability;
+    const paramsKey = paramsKeyOf(params);
+    const codeKey = codeKeyOf(code);
+    const scope = source?.namespace?.() ?? '';
+    const blocked = !hasRequiredParams(requiredParams, params);
+    const sourceRef = useRef(source);
+    sourceRef.current = source;
+    const paramsRef = useRef(params);
+    paramsRef.current = params;
+    const codeRef = useRef(code);
+    codeRef.current = code;
+    const [asyncResult, setAsyncResult] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const seqRef = useRef(0);
+    /**
+     * 已选项的兜底记忆。
+     *
+     * 搜索型源的候选会随关键词整批换掉，重新展开拿到的也只是默认第一页，
+     * 已选项常常不在里面；没有 resolve 就只能退回编码。按
+     * 「来源 + 租户 + 条件 + 编码」记住最近一次命中的选项，条件一变自然失效。
+     */
+    const memoryRef = useRef(null);
+    const memoryKey = `${sourceKey}|${scope}|${paramsKey}|${codeKey}`;
+    // 本地能查到就不发请求；命中结果是对象，这里只取布尔作为 effect 依赖
+    const seedHit = useMemo(() => (code === undefined ? undefined : findOption(seedOptions, code)), [seedOptions, code]);
+    const candidateHit = useMemo(() => (code === undefined ? undefined : findOption(candidates, code)), [candidates, code]);
+    const localHit = seedHit ?? candidateHit;
+    const hasLocal = Boolean(localHit);
+    // 对象值已经自带名称：展示层直接用，没有理由再发一次 resolve
+    const hasValueName = Boolean(valueName);
+    useEffect(() => {
+        if (code === undefined || hasLocal || hasValueName || !canResolve || blocked)
+            return;
+        const resolve = sourceRef.current?.resolve;
+        if (!resolve)
+            return;
+        const requested = codeRef.current;
+        const key = resolveCacheKey(scope, sourceKey, requested, paramsKey);
+        const seq = seqRef.current + 1;
+        seqRef.current = seq;
+        let cancelled = false;
+        setLoading(true);
+        // 不传 AbortSignal：这个 promise 是多个实例共享的，
+        // 单个实例卸载不能把别人的请求掐掉，只放弃自己的状态更新即可
+        resolveCodeWithCache(key, () => resolve(requested, paramsRef.current ?? {}))
+            .then((option) => {
+            if (cancelled || seq !== seqRef.current)
+                return;
+            // 接口返回了别的编码就别认：认错比认不出更糟，展示层会显示陌生名称。
+            // 数字/字符串同一编码（后端序列化常见）认下，但编码归一到值的类型：
+            // 否则选项 value 与 Select 的 value 对不上，标签等于白解析
+            const matched = option && sameCode(option.code, requested) ? { ...option, code: requested } : null;
+            setAsyncResult({ sourceKey, scope, paramsKey, codeKey, option: matched, failed: false });
+        })
+            .catch(() => {
+            if (cancelled || seq !== seqRef.current)
+                return;
+            setAsyncResult({
+                sourceKey,
+                scope,
+                paramsKey,
+                codeKey,
+                option: null,
+                failed: true,
+            });
+        })
+            .finally(() => {
+            if (!cancelled && seq === seqRef.current)
+                setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // sourceKey / paramsKey / codeKey 都是字符串，源从 ref 取，函数引用不进依赖
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [sourceKey, scope, paramsKey, codeKey, hasLocal, hasValueName, canResolve, blocked]);
+    return useMemo(() => {
+        if (code === undefined)
+            return { option: null, status: 'empty' };
+        // 命中即记账：下次候选被换掉时还能拿它兜底
+        const remember = (option) => {
+            memoryRef.current = { key: memoryKey, option };
+            return option;
+        };
+        const remembered = memoryRef.current;
+        const fallback = remembered?.key === memoryKey ? remembered.option : undefined;
+        // 1) 对象值自带的名称：详情已经给了，不必再查
+        if (valueName)
+            return { option: remember({ code, name: valueName }), status: 'resolved' };
+        // 2) 页面预置的候选
+        if (seedHit)
+            return { option: remember(seedHit), status: 'resolved' };
+        // 3) 已加载的候选
+        if (candidateHit)
+            return { option: remember(candidateHit), status: 'resolved' };
+        const asyncMatched = asyncResult &&
+            asyncResult.sourceKey === sourceKey &&
+            asyncResult.scope === scope &&
+            asyncResult.paramsKey === paramsKey &&
+            asyncResult.codeKey === codeKey;
+        if (asyncMatched && asyncResult) {
+            if (asyncResult.option)
+                return { option: remember(asyncResult.option), status: 'resolved' };
+            // 解析不到但之前见过这个编码：搜索型源的候选已被关键词换掉，别退回编码
+            if (fallback)
+                return { option: fallback, status: 'resolved' };
+            return { option: { code }, status: asyncResult.failed ? 'error' : 'missing' };
+        }
+        if (fallback)
+            return { option: fallback, status: 'resolved' };
+        if (!canResolve)
+            return { option: { code }, status: 'missing' };
+        // 用空条件查可能拿到别家数据，宁可不查
+        if (blocked)
+            return { option: { code }, status: 'blocked' };
+        if (loading)
+            return { option: { code }, status: 'loading' };
+        return { option: { code }, status: 'missing' };
+    }, [
+        code,
+        valueName,
+        seedHit,
+        candidateHit,
+        asyncResult,
+        memoryKey,
+        sourceKey,
+        scope,
+        paramsKey,
+        codeKey,
+        canResolve,
+        blocked,
+        loading,
+    ]);
+}
+//# sourceMappingURL=useSelectedLabel.js.map