@tianyr/schema-antd 0.1.0 → 0.2.0

package/dist/biz-select/resolveBatch.js

@@ -0,0 +1,124 @@
+/**
+ * 批量按值解析：把「一屏几十个编码各发一次」收成一次请求。
+ *
+ * 只在源声明了 `resolveMany` 时才批量；没声明就退回逐条，和以前完全一样。
+ * 所以这块是**加速**，不是新的解析体系：批量结果按编码拆开写进同一条
+ * `resolveCache`，之后任何单条 resolve 都直接命中。
+ *
+ * 为什么不放进组件：逐行 resolve 是表格列的需求，单个下拉只有一个值。
+ * 由页面显式调一次、把结果当 `seedOptions` 传下去，比在组件里攒时间窗更可预测
+ * ——批窗口对详情页是纯延迟，一次批量失败又会同时打掉整列的错误态。
+ */
+import { dropResolvedCache, peekResolved, resolveCodeWithCache } from './cache.js';
+import { isEmptyValue } from './format.js';
+import { lookupKeyOf, paramsKeyOf, resolveCacheKey } from './key.js';
+import { hasRequiredParams } from './normalize.js';
+/** 每批最多多少个编码。接口有更小的上限时由调用方传 batchSize */
+export const DEFAULT_BATCH_SIZE = 100;
+/**
+ * 单条解析：源只声明了批量接口时，批量一条等价于单条，
+ * 不必逼调用方再写一个一模一样的 `resolve`。
+ */
+export function resolveOne(source, value, params) {
+    if (source?.resolve)
+        return source.resolve(value, params);
+    if (!source?.resolveMany)
+        return Promise.resolve(null);
+    return source.resolveMany([value], params).then((list) => {
+        const hit = (list ?? []).find((item) => lookupKeyOf(item.value) === lookupKeyOf(value));
+        // 编码归一到调用方的类型：否则选项 value 与 Select 的 value 对不上，标签等于白解析
+        return hit ? { ...hit, value } : null;
+    });
+}
+/** 去掉空值、按 `lookupKeyOf` 去重，保持出现顺序 */
+function uniqueCodes(codes) {
+    const seen = new Set();
+    const out = [];
+    for (const code of codes) {
+        if (isEmptyValue(code))
+            continue;
+        const key = lookupKeyOf(code);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(code);
+    }
+    return out;
+}
+function chunkOf(list, size) {
+    const chunks = [];
+    for (let index = 0; index < list.length; index += size) {
+        chunks.push(list.slice(index, index + size));
+    }
+    return chunks;
+}
+function indexByCode(list) {
+    const map = new Map();
+    for (const option of list ?? []) {
+        if (!option || isEmptyValue(option.value))
+            continue;
+        map.set(lookupKeyOf(option.value), option);
+    }
+    return map;
+}
+export async function resolveCodes(options) {
+    const { source, sourceKey, batchSize = DEFAULT_BATCH_SIZE } = options;
+    const params = options.params ?? {};
+    const paramsKey = paramsKeyOf(options.params);
+    const scope = options.scope ?? source?.namespace?.() ?? '';
+    const byCode = new Map();
+    const missing = [];
+    const unique = uniqueCodes(options.codes);
+    if (!unique.length)
+        return { byCode, missing, blocked: false, requests: 0 };
+    // 缺参数时不查：用空条件查可能拿到别家数据，批量只会放大这个问题
+    if (!hasRequiredParams(source?.requiredParams, params)) {
+        return { byCode, missing: unique.map(lookupKeyOf), blocked: true, requests: 0 };
+    }
+    const collect = (code, option) => {
+        if (!option) {
+            missing.push(lookupKeyOf(code));
+            return;
+        }
+        // 接口可能把 1 回成 '1'：值类型归到调用方给的那个，展示与回显才对得上
+        byCode.set(lookupKeyOf(code), option.value === code ? option : { ...option, value: code });
+    };
+    const waits = [];
+    const misses = [];
+    for (const code of unique) {
+        const key = resolveCacheKey(scope, sourceKey, code, paramsKey);
+        if (options.force)
+            dropResolvedCache(key);
+        const hit = peekResolved(key);
+        if (hit) {
+            // 已解析过的不占批量请求的位置
+            waits.push(hit.then((option) => collect(code, option)));
+            continue;
+        }
+        misses.push(code);
+    }
+    let requests = 0;
+    for (const codes of chunkOf(misses, Math.max(1, batchSize))) {
+        if (source?.resolveMany) {
+            requests += 1;
+            const index = source.resolveMany(codes, params).then(indexByCode);
+            for (const code of codes) {
+                const key = resolveCacheKey(scope, sourceKey, code, paramsKey);
+                // 逐条登记：同键的单条请求能和这批共享同一份 promise，批量不会绕开在途去重
+                const pending = resolveCodeWithCache(key, () => index.then((map) => map.get(lookupKeyOf(code)) ?? null));
+                waits.push(pending.then((option) => collect(code, option)));
+            }
+            continue;
+        }
+        // 没有批量接口就是逐条，和以前一样；调用方据 requests 判断该不该加接口
+        for (const code of codes) {
+            requests += 1;
+            const key = resolveCacheKey(scope, sourceKey, code, paramsKey);
+            waits.push(resolveCodeWithCache(key, () => resolveOne(source, code, params)).then((option) => collect(code, option)));
+        }
+    }
+    // 批量失败时这一片全部落空：不自动降级成逐条重试，否则一次故障会放大成 N 个请求
+    await Promise.all(waits);
+    return { byCode, missing, blocked: false, requests };
+}
+//# sourceMappingURL=resolveBatch.js.map

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

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

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

@@ -0,0 +1,5 @@
+import { normalizeBizSelectSchema } from './compile.js';
+export { normalizeBizSelectSchema };
+export type { BizSelectSchemaProps, ParamsFromEntry } from './compile.js';
+export declare function registerBizSelectField(): void;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/biz-select/schema.tsx"],"names":[],"mappings":"AAWA,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAGrD,OAAO,EAAE,wBAAwB,EAAE,CAAC;AACpC,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEvE,wBAAgB,sBAAsB,IAAI,IAAI,CA+B7C"}

package/dist/biz-select/schema.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * BizSelect 的字段类型注册。
+ *
+ * 刻意不自动执行：包默认只提供标准 antd 控件，使用方需要时调一次
+ * `registerBizSelectField()`。单选和多选一起注册，不然使用方要记住调两次。
+ */
+import { registerField } from '../registry.js';
+import { BizMultiSelect } from './BizMultiSelect.js';
+import { BizMultiSelectDisplay } from './BizMultiSelectDisplay.js';
+import { BizSelect } from './BizSelect.js';
+import { BizSelectDisplay } from './BizSelectDisplay.js';
+import { normalizeBizSelectSchema } from './compile.js';
+export { normalizeBizSelectSchema };
+export function registerBizSelectField() {
+    registerField('BizSelect', {
+        component: BizSelect,
+        normalize: normalizeBizSelectSchema,
+        // 只读态复用同一套解析，不挂载交互组件
+        renderRead: (value, props) => (_jsx(BizSelectDisplay, { value: value, ...props })),
+    }, { override: true });
+    registerField('BizMultiSelect', {
+        component: BizMultiSelect,
+        normalize: normalizeBizSelectSchema,
+        renderRead: (value, props) => (_jsx(BizMultiSelectDisplay, { value: value, ...props })),
+    }, { override: true });
+}
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/biz-select/schema.tsx"],"names":[],"mappings":";AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAGrD,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAGpC,MAAM,UAAU,sBAAsB;IACpC,aAAa,CACX,WAAW,EACX;QACE,SAAS,EAAE,SAAS;QACpB,SAAS,EAAE,wBAAwB;QACnC,qBAAqB;QACrB,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAC5B,KAAC,gBAAgB,IACf,KAAK,EAAE,KAAc,KAChB,KAA0C,GAC/C,CACH;KACF,EACD,EAAE,QAAQ,EAAE,IAAI,EAAE,CACnB,CAAC;IAEF,aAAa,CACX,gBAAgB,EAChB;QACE,SAAS,EAAE,cAAc;QACzB,SAAS,EAAE,wBAAwB;QACnC,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAC5B,KAAC,qBAAqB,IACpB,KAAK,EAAE,KAAc,KAChB,KAA+C,GACpD,CACH;KACF,EACD,EAAE,QAAQ,EAAE,IAAI,EAAE,CACnB,CAAC;AACJ,CAAC"}

package/dist/biz-select/source-id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 注册名的来源键格式。
+ *
+ * 单独成一个文件是为了打断 `key.ts ↔ registry.ts` 的循环依赖：
+ * 两边都要拼同一个字符串，格式漂移会让缓存清不掉。
+ */
+export declare function nameSourceKey(name: string, version: number): string;
+//# sourceMappingURL=source-id.d.ts.map

package/dist/biz-select/source-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-id.d.ts","sourceRoot":"","sources":["../../src/biz-select/source-id.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnE"}

package/dist/biz-select/source-id.js

@@ -0,0 +1,10 @@
+/**
+ * 注册名的来源键格式。
+ *
+ * 单独成一个文件是为了打断 `key.ts ↔ registry.ts` 的循环依赖：
+ * 两边都要拼同一个字符串，格式漂移会让缓存清不掉。
+ */
+export function nameSourceKey(name, version) {
+    return `n:${name}@${version}`;
+}
+//# sourceMappingURL=source-id.js.map

package/dist/biz-select/source-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-id.js","sourceRoot":"","sources":["../../src/biz-select/source-id.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,OAAe;IACzD,OAAO,KAAK,IAAI,IAAI,OAAO,EAAE,CAAC;AAChC,CAAC"}

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

@@ -0,0 +1,160 @@
+/**
+ * BizSelect 的类型契约。
+ *
+ * 对外只有一个「数据源」概念：能给出候选、能按值解析名称。
+ * 具体是前端常量、一次拉全量还是关键词翻页，由源**提供了哪些能力**决定，
+ * 不再用 kind 之类的标签分类。
+ *
+ * 选项统一用 `value` / `label`：组件是渲染层，和 antd 同词汇，存量字典可以直接用。
+ * 后端记录叫 `code` / `name`、`userId` / `userName` 都不影响契约——
+ * 那是数据入口的方言，由源的 `recordFields` 映射一次，运行时只有一种形状。
+ */
+import type { ReactNode } from 'react';
+import type { SelectProps } from 'antd';
+export type SelectValue = string | number;
+/**
+ * 契约层的标准选项。
+ *
+ * `label` 刻意限定为字符串：它要参与前端过滤匹配、要回写进对象值。
+ * 富文本标签不在范围内，需要时走 `renderRead` 或注册自定义字段类型。
+ */
+export interface BizOption<T = unknown> {
+    value: SelectValue;
+    label?: string;
+    disabled?: boolean;
+    /** 原始接口记录，原样带回给业务回调 */
+    raw?: T;
+}
+/** 展示模式：值 / 值-名称 / 名称 */
+export type DisplayMode = 'V' | 'V-L' | 'L';
+/** 前端过滤时匹配哪些字段 */
+export type SearchFields = 'value' | 'label' | 'both';
+/** 值形态：标量值，或自带名称的对象 */
+export type ValueMode = 'primitive' | 'object';
+/**
+ * 源返回的记录里，哪个字段是值、哪个字段是名称。
+ * 不给就按 `{ value, label }` 原样使用。
+ *
+ * 和 `ValueFieldMap` 是两条通道，只是形状相同：
+ * - 本类型在**源工厂**上声明，管「接口记录怎么读」（`tenantUserId` → `value`）
+ * - `ValueFieldMap` 在组件 / schema 上声明，管「值对象怎么存」（`userId` → 值）
+ */
+export interface RecordFieldNames {
+    value?: string;
+    label?: string;
+}
+/**
+ * 对象值里哪个键装值、哪个键装名称。
+ * 默认 `{ value: 'value', label: 'label' }`；后端存 `{ code, name }` 时配成对应的键。
+ *
+ * 只管存储形状，不参与读接口记录，见 `RecordFieldNames`。
+ */
+export interface ValueFieldMap {
+    value?: string;
+    label?: string;
+}
+export type SelectParams = Record<string, unknown>;
+/** 对象形态的值；具体键名由 valueFields 决定，所以只能约束到 Record */
+export type BizObjectValue = Record<string, unknown>;
+/** 多选的值：标量数组或对象数组 */
+export type SelectValues = SelectValue[] | BizObjectValue[];
+/**
+ * 数据源契约。只有能力声明，不认识 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?: (value: SelectValue, params: P, signal?: AbortSignal) => Promise<BizOption | null>;
+    /**
+     * 批量按值精确查：一屏几十个编码收成一次请求。
+     *
+     * 只有接口真的支持 IN 过滤时才声明——参数名对不上、或有返回条数上限都不算支持，
+     * 声明了却查不全，会把「接口没返回」当成「记录不存在」。
+     * 返回的记录和 `search` 用同一份 `recordFields`；形状不同就在函数里先归一化。
+     */
+    resolveMany?: (values: SelectValue[], params: P, signal?: AbortSignal) => Promise<BizOption[]>;
+    /** 缺任一参数就不发请求：用空条件查可能拿到别家数据 */
+    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;
+    /** 对象值里哪个键装值/名称，默认 `{ value, label }` */
+    valueFields?: ValueFieldMap;
+}
+interface PrimitiveModeProps {
+    valueMode?: 'primitive';
+    value?: SelectValue | null;
+    onChange?: (value: SelectValue | 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?: SelectValue | BizObjectValue | null;
+    /** 只读占位 */
+    emptyText?: ReactNode;
+}
+interface MultiPrimitiveModeProps {
+    valueMode?: 'primitive';
+    value?: SelectValue[] | SelectValue | null;
+    /**
+     * 清空时给 `undefined` 而不是 `[]`：与 `ctx.clear()` 一致，
+     * 也让 antd 的 `required` 规则天然生效（它拿空数组没辙）。
+     */
+    onChange?: (value: SelectValue[] | undefined, options: BizOption[]) => void;
+}
+interface MultiObjectModeProps {
+    valueMode: 'object';
+    value?: BizObjectValue[] | BizObjectValue | null;
+    onChange?: (value: BizObjectValue[] | undefined, options: BizOption[]) => void;
+}
+export type BizMultiSelectProps = CoreProps & BaseAntProps & (MultiPrimitiveModeProps | MultiObjectModeProps);
+export interface BizMultiSelectDisplayProps extends CoreProps {
+    value?: SelectValues | SelectValue | BizObjectValue | null;
+    /** 只读占位 */
+    emptyText?: ReactNode;
+    /** 多值分隔符，默认 `、`（与 read.tsx 保持一致） */
+    separator?: string;
+}
+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"}