@pisell/materials 6.11.37 → 6.11.38

package/es/components/Pagination/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { PaginationProps } from 'antd';
 import './index.less';
 declare const Pagination: (props: PaginationProps) => JSX.Element | null;

package/es/components/PisellBasicGrid/PisellBasicGrid.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import type { PisellBasicGridProps } from './types';
 import './PisellBasicGrid.less';
 /**

package/es/components/PisellCards/components/GraphicTextCard/GraphicTextCard.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { GraphicTextCardProps } from './types';
 import './GraphicTextCard.less';
 /**

package/es/components/PisellCards/components/MultilevelCard/hooks/useMultilevelCardExpand.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { MultilevelCardTrigger } from '../types';
 /**
  * 管理 MultilevelCard 的展开/收起状态

package/es/components/PisellCards/components/PisellImageCard/PisellImageCard.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { PisellImageCardProps } from './types';
 import './PisellImageCard.less';
 /**

package/es/components/PisellCards/components/PisellImageCard/hooks/useImageLoad.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 /**
  * 图片加载状态管理 Hook
  * @param src - 图片地址

package/es/components/PisellCards/components/TabCard/TabCard.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import './TabCard.less';
 declare const Provider: (props: any) => JSX.Element;
 export default Provider;

package/es/components/PisellCards/components/TextCard/TextCard.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import './TextCard.less';
 /**
  * Provider 包装器

package/es/components/PisellCards/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 declare const PisellCards: {
     TabCard: (props: any) => JSX.Element;
     TextCard: (props: any) => JSX.Element;

package/es/components/PisellFields/index.d.ts

@@ -9,6 +9,7 @@
  * <PisellFields.Number value={123} viewMode="readonly" />
  * <PisellFields.Currency value={1000} currencySymbol="$" />
  */
+/// <reference types="react" />
 declare const PisellFields: {
     SingleLineText: import("react").NamedExoticComponent<import("../pisellSingleLineText").PisellSingleLineTextProps>;
     LongText: import("react").NamedExoticComponent<import("../pisellLongText").PisellLongTextProps>;

package/es/components/PisellLayouts/index.d.ts

@@ -13,11 +13,12 @@
  *   <Content />
  * </PisellLayouts.ScrollView>
  */
+/// <reference types="react" />
 declare const PisellLayouts: {
     BasicGrid: <T>(props: import("../PisellBasicGrid").PisellBasicGridProps<T>) => JSX.Element;
     ScrollView: import("react").ForwardRefExoticComponent<Omit<import("../PisellScrollView").PisellScrollViewProps, "ref"> & import("react").RefAttributes<import("../PisellScrollView").PisellScrollViewRef>>;
     FloorMapLayout: <T_1 extends import("../pisellFloorMapLayout").FloorMapItemBase = import("../pisellFloorMapLayout").FloorMapItemBase>(props: import("../pisellFloorMapLayout").PisellFloorMapLayoutProps<T_1> & {
-        ref?: import("react").Ref<import("../pisellFloorMapLayout").PisellFloorMapLayoutRef> | undefined;
+        ref?: import("react").Ref<import("../pisellFloorMapLayout").PisellFloorMapLayoutRef | null> | undefined;
     }) => import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
     Layout: import("../pisellLayout").CompoundedComponent;
     Content: import("react").FC<import("../pisellLayout/content").PisellContentProps>;

package/es/components/appVersionControl/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { AppVersionControlProps } from './types';
 import './index.less';
 declare const AppVersionControl: (props: AppVersionControlProps) => JSX.Element;

package/es/components/auto-complete-number/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { AutoCompleteProps, InputNumberProps } from "antd";
 interface AutoCompleteNumberProps {
     autoCompleteProps: AutoCompleteProps;

package/es/components/badge/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { BadgeProps as OriginalBadgeprops } from 'antd';
 import './index.less';
 export interface Badgeprops extends OriginalBadgeprops {

package/es/components/batch-editor/fields/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 declare const _default: {
     price: import("react").FC<import("./Price").PriceProps>;
     image: (props: import("./Image").ImageProps) => JSX.Element | null;

package/es/components/batch-editor/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import "./index.less";
 interface BatchEditorProps {
     columns: any[];

package/es/components/calendar/index.d.ts

@@ -1,2 +1,3 @@
+/// <reference types="react" />
 declare const Calendar: (props: any) => JSX.Element;
 export default Calendar;

package/es/components/cardPro/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import './index.less';
 declare const _default: (props: any) => JSX.Element;
 export default _default;

package/es/components/checkbox/index.d.ts

@@ -1,2 +1,3 @@
+/// <reference types="react" />
 declare const Checkbox: (props: any) => JSX.Element;
 export default Checkbox;

package/es/components/classicLayout/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import "./index.less";
 declare const ClassicLayout: (props: any) => JSX.Element;
 export default ClassicLayout;

package/es/components/config-provider/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { ConfigProviderProps as OriginalConfigProviderProps } from "antd/es/config-provider";
 import "dayjs/locale/zh-cn";
 import "dayjs/locale/ja";

package/es/components/dataSourceComponents/dataSourceForm/utils.d.ts

@@ -44,7 +44,7 @@ export declare const withDataSource: <P extends unknown>(WrappedComponent: React
 }) => JSX.Element;
 export declare const withOptions: <P extends unknown>(WrappedComponent: React.ComponentType<P>) => (props: P & {
     options?: any;
-    optionSourceType?: "default" | "custom" | "api" | undefined;
+    optionSourceType?: "custom" | "default" | "api" | undefined;
     labelField: string;
     valueField: string;
     extraParams?: Record<string, any> | undefined;

package/es/components/dataSourceComponents/dataSourceTable/hooks/useDrawerState.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 declare const useDrawerState: (operationContent?: {
     [key: string]: import("react").ReactNode;
 } | undefined) => any;

package/es/components/dataSourceComponents/dataSourceTable/hooks/useTableProps.d.ts

@@ -19,7 +19,7 @@ interface UseTablePropsProps {
  */
 declare const useTableProps: (props: UseTablePropsProps) => {
     currentComponentId: any;
-    title: number | boolean | React.ReactFragment | JSX.Element | (() => React.ReactNode) | null | undefined;
+    title: number | boolean | JSX.Element | React.ReactFragment | (() => React.ReactNode) | null | undefined;
     pagination: {
         total: number;
         current: number;
@@ -28,7 +28,7 @@ declare const useTableProps: (props: UseTablePropsProps) => {
         showSizeChanger: boolean;
     };
     columns: import("./useColumns").Column[];
-    subTitle: number | boolean | React.ReactFragment | JSX.Element | (() => React.ReactNode) | null | undefined;
+    subTitle: number | boolean | JSX.Element | React.ReactFragment | (() => React.ReactNode) | null | undefined;
     buttons: any[] | null;
     filter: {
         dom: any;
@@ -54,7 +54,7 @@ declare const useTableProps: (props: UseTablePropsProps) => {
         width: number;
         align: "center" | "left" | "right";
         fixed: false | "left" | "right";
-        type: "link" | "button";
+        type: "button" | "link";
         items: OperationItem[];
     } | undefined;
     operationContent?: {

package/es/components/dataSourceComponents/fields/RecordListWrapper/index.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="react" />
 declare const RecordListWrapperWithDataSource: (props: import("./type").RecordListWrapperProps & import("../../dataSourceForm/utils").WithModeProps & import("../../dataSourceForm/utils").WithFormItemProps & {
     options?: any;
-    optionSourceType?: "default" | "custom" | "api" | undefined;
+    optionSourceType?: "custom" | "default" | "api" | undefined;
     labelField: string;
     valueField: string;
     extraParams?: Record<string, any> | undefined;

package/es/components/dataSourceComponents/fields/Select/index.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="react" />
 declare const SelectWithDataSource: (props: import("antd").SelectProps<any, import("antd/es/select").DefaultOptionType> & import("../../dataSourceForm/utils").WithModeProps & import("../../dataSourceForm/utils").WithFormItemProps & {
     options?: any;
-    optionSourceType?: "default" | "custom" | "api" | undefined;
+    optionSourceType?: "custom" | "default" | "api" | undefined;
     labelField: string;
     valueField: string;
     extraParams?: Record<string, any> | undefined;

package/es/components/dataSourceComponents/fields/Tabs/index.d.ts

@@ -2,7 +2,7 @@
 /** 包装 DataSource 层（提供数据源上下文） */
 declare const FormItemTabs: (props: import("./type").TabsProps & import("../../dataSourceForm/utils").WithModeProps & import("../../dataSourceForm/utils").WithFormItemProps & {
     options?: any;
-    optionSourceType?: "default" | "custom" | "api" | undefined;
+    optionSourceType?: "custom" | "default" | "api" | undefined;
     labelField: string;
     valueField: string;
     extraParams?: Record<string, any> | undefined;

package/es/components/dataSourceComponents/fields/Upload/ReadPretty.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { UploadProps } from './type';
 import './ReadPretty.less';
 declare const UploadReadPretty: (props: UploadProps) => JSX.Element | null;

package/es/components/dataSourceComponents/fields/index.d.ts

@@ -35,7 +35,7 @@ declare const formFieldMap: {
     };
     FormItemSelect: (props: import("antd").SelectProps<any, import("antd/es/select").DefaultOptionType> & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
         options?: any;
-        optionSourceType?: "default" | "custom" | "api" | undefined;
+        optionSourceType?: "custom" | "default" | "api" | undefined;
         labelField: string;
         valueField: string;
         extraParams?: Record<string, any> | undefined;
@@ -62,7 +62,7 @@ declare const formFieldMap: {
     FormItemIconSelect: import("react").FC<import("./IconSelect/type").IconSelectProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps>;
     FormItemRecordListWrapper: (props: import("./RecordListWrapper/type").RecordListWrapperProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
         options?: any;
-        optionSourceType?: "default" | "custom" | "api" | undefined;
+        optionSourceType?: "custom" | "default" | "api" | undefined;
         labelField: string;
         valueField: string;
         extraParams?: Record<string, any> | undefined;
@@ -72,7 +72,7 @@ declare const formFieldMap: {
     }) => JSX.Element;
     FormItemTabs: (props: import("./Tabs/type").TabsProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
         options?: any;
-        optionSourceType?: "default" | "custom" | "api" | undefined;
+        optionSourceType?: "custom" | "default" | "api" | undefined;
         labelField: string;
         valueField: string;
         extraParams?: Record<string, any> | undefined;
@@ -113,7 +113,7 @@ declare const getFieldComponent: (fieldComponent: string) => import("react").FC<
     Group: import("react").FC<import("./Radio/type").RadioGroupProps & import("../dataSourceForm/utils").WithModeProps>;
 }) | ((props: import("antd").SelectProps<any, import("antd/es/select").DefaultOptionType> & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
     options?: any;
-    optionSourceType?: "default" | "custom" | "api" | undefined;
+    optionSourceType?: "custom" | "default" | "api" | undefined;
     labelField: string;
     valueField: string;
     extraParams?: Record<string, any> | undefined;
@@ -122,7 +122,7 @@ declare const getFieldComponent: (fieldComponent: string) => import("react").FC<
     extraParams?: Record<string, any> | undefined;
 }) => JSX.Element) | import("react").FC<import("./TimePicker/type").TimePickerProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./DateRangePicker/type").DateRangePickerProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./Upload/type").UploadProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./Translation/type").TranslationProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./IconSelect/type").IconSelectProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | ((props: import("./RecordListWrapper/type").RecordListWrapperProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
     options?: any;
-    optionSourceType?: "default" | "custom" | "api" | undefined;
+    optionSourceType?: "custom" | "default" | "api" | undefined;
     labelField: string;
     valueField: string;
     extraParams?: Record<string, any> | undefined;
@@ -131,7 +131,7 @@ declare const getFieldComponent: (fieldComponent: string) => import("react").FC<
     extraParams?: Record<string, any> | undefined;
 }) => JSX.Element) | ((props: import("./Tabs/type").TabsProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
     options?: any;
-    optionSourceType?: "default" | "custom" | "api" | undefined;
+    optionSourceType?: "custom" | "default" | "api" | undefined;
     labelField: string;
     valueField: string;
     extraParams?: Record<string, any> | undefined;

package/es/components/date-picker/datePickerCpt.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { PickerDateProps } from 'antd/es/date-picker/generatePicker';
 import { Dayjs } from 'dayjs';
 import './index.less';

package/es/components/date-picker/index.d.ts

@@ -1,2 +1,3 @@
+/// <reference types="react" />
 declare const DatePicker: (props: any) => JSX.Element;
 export default DatePicker;

package/es/components/drag-sort-tree/TreeItem/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import './index.less';
 import { ValueProps, SortType } from '../types';
 declare type IdType = string | number;

package/es/components/drag-sort-tree/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import './index.less';
 import { SortType } from './types';
 declare const DragSortTree: (props: SortType) => JSX.Element;

package/es/components/dropdown/index.d.ts

@@ -1,2 +1,3 @@
+/// <reference types="react" />
 declare const Dropdown: (props: any) => JSX.Element;
 export default Dropdown;

package/es/components/filter/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { FilterProps } from "./types";
 declare const Filter: (props: FilterProps) => JSX.Element | null;
 export default Filter;

package/es/components/list/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import "./index.less";
 declare const List: {
     (props: any): JSX.Element;

package/es/components/lowCodePage/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 declare type LowCodePageProps = {
     id: number;
 };

package/es/components/page/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { ConfigProviderProps } from '../config-provider';
 interface PageProps extends ConfigProviderProps {
     variablesConfig?: {

package/es/components/pisellAdjustPrice/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import './index.less';
 import { PisellAdjustPriceProps } from './type';
 declare const PisellAdjustPrice: (props: PisellAdjustPriceProps) => JSX.Element;

package/es/components/pisellCard/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { CardProps } from 'antd';
 import './index.less';
 export interface PisellCardProps extends CardProps {

package/es/components/pisellDatePicker/datePickerCpt.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { PickerDateProps } from 'antd/es/date-picker/generatePicker';
 import { Dayjs } from 'dayjs';
 import './detePickerCpt.less';

package/es/components/pisellFilter/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { PisellFilterProps } from './type';
 declare const PisellFilter: (props: PisellFilterProps) => JSX.Element;
 export default PisellFilter;

package/es/components/pisellFloorMapLayout/PisellFloorMapLayout.d.ts

@@ -5,8 +5,9 @@
 import React from 'react';
 import type { FloorMapItemBase, PisellFloorMapLayoutProps, PisellFloorMapLayoutRef } from './types';
 import './PisellFloorMapLayout.less';
+/** 空间布局根组件：阅读/编辑、列表与平面图双模式，ref 见 {@link PisellFloorMapLayoutRef} */
 declare const PisellFloorMapLayout: <T extends FloorMapItemBase = FloorMapItemBase>(props: PisellFloorMapLayoutProps<T> & {
-    ref?: React.Ref<PisellFloorMapLayoutRef> | undefined;
+    ref?: React.Ref<PisellFloorMapLayoutRef | null> | undefined;
 }) => React.ReactElement;
 export { PisellFloorMapLayout };
 export default PisellFloorMapLayout;

package/es/components/pisellFloorMapLayout/PisellFloorMapLayout.js

@@ -42,6 +42,11 @@ import { locales } from '@pisell/utils';
 import { initFloorMapLayoutLocales } from "./utils/floorMapCanvasDisplay";
 import "./PisellFloorMapLayout.less";
 var PREFIX = 'pisell-floor-map-layout';
+
+/**
+ * 布局根实现（由 {@link PisellFloorMapLayout} forwardRef 包裹）。
+ * 负责：上下文与 props 合并、编辑态/阅读态分支、Transform 视口、图元层与工具栏联动。
+ */
 function PisellFloorMapLayoutInner(props, ref) {
   var _engineCtx$engine, _config$sceneElements;
   var layoutCtx = useFloorMapLayoutContext();
@@ -138,6 +143,8 @@ function PisellFloorMapLayoutInner(props, ref) {
     toggleSelectedLayoutLock = edit.toggleSelectedLayoutLock,
     duplicateSelectedElement = edit.duplicateSelectedElement,
     deleteSelectedElement = edit.deleteSelectedElement;
+
+  /** 当前画布下的 mapLayer：全局 `mapLayer` 与画布级配置合并，供 MapLayer / 吸附等读取 */
   var effectiveMapLayer = useMemo(function () {
     var _canvas$mapLayer;
     if (!isFloorMapView || !config || !currentCanvasId) {
@@ -160,6 +167,8 @@ function PisellFloorMapLayoutInner(props, ref) {
     var z = (_zoom$defaultScale = zoom.defaultScale) !== null && _zoom$defaultScale !== void 0 ? _zoom$defaultScale : 1;
     return "fmap-".concat(currentCanvasId !== null && currentCanvasId !== void 0 ? currentCanvasId : 'na', "-bp").concat(bp, "-z").concat(z);
   }, [isFloorMapView, currentCanvasId, effectiveMapLayer === null || effectiveMapLayer === void 0 ? void 0 : effectiveMapLayer.boundingPadding, zoom.defaultScale]);
+
+  /** 供顶栏 Tab 使用：合并草稿画布等后的画布列表 */
   var canvasesForTabs = useMemo(function () {
     return config ? mergeCanvasesForTabs(config) : [];
   }, [config]);
@@ -171,18 +180,21 @@ function PisellFloorMapLayoutInner(props, ref) {
       return c.enabled;
     }).length;
   }, [canvasesForTabs]);
+
+  /** 阅读态是否展示画布 Tab：多启用画布或配置了 `canvasTabsBarTrailing` 时出现 */
   var showReadModeCanvasTabsBar = useMemo(function () {
     if (!isFloorMapView || mode !== 'read' || !config) return false;
     if (hasCanvasTabsBarTrailing) return true;
     return enabledCanvasCount > 1;
   }, [isFloorMapView, mode, config, hasCanvasTabsBarTrailing, enabledCanvasCount]);
+
+  /** 阅读态画布 Tab 工具条的无障碍标签（随引擎语言初始化文案） */
   var readCanvasTabsAriaLabel = useMemo(function () {
     initFloorMapLayoutLocales(engineLocale);
     return locales.getText('pisell-floor-map-layout.read-canvas-tabs.aria');
   }, [engineLocale]);
 
-  /** 编辑态始终保留顶栏 Tab（单画布也要能「添加画布」）；仅阅读态在单画布时可隐藏 Tab 行 */
-  var showEditCompactTopBar = isFloorMapView && mode === 'edit' && Boolean(config) && !useFullTopChrome;
+  /** 加载遮罩上的文案 */
   var loadingLabel = useMemo(function () {
     initFloorMapLayoutLocales(engineLocale);
     return locales.getText('pisell-floor-map-layout.loading');
@@ -217,9 +229,11 @@ function PisellFloorMapLayoutInner(props, ref) {
     };
   }, [isFloorMapView, mode, config === null || config === void 0 ? void 0 : config.canvasUi.canEdit, selectedId, items, engineLocale, toggleSelectedLayoutLock, duplicateSelectedElement, deleteSelectedElement]);
   var cellSize = cellSizeProp !== null && cellSizeProp !== void 0 ? cellSizeProp : DEFAULT_CELL_SIZE;
+  /** 图元间距（像素）：由 mapLayer.gap 解析 */
   var itemGap = useMemo(function () {
     return gapToPx(effectiveMapLayer === null || effectiveMapLayer === void 0 ? void 0 : effectiveMapLayer.gap);
   }, [effectiveMapLayer === null || effectiveMapLayer === void 0 ? void 0 : effectiveMapLayer.gap]);
+  /** 平面图坐标始终按像素；非平面图沿用 props `itemUnit` */
   var effectiveItemUnit = isFloorMapView ? 'pixel' : itemUnit;
   var metrics = useFloorMapTransformMetrics({
     items: items,
@@ -258,6 +272,11 @@ function PisellFloorMapLayoutInner(props, ref) {
   var useFullTopChrome = isFloorMapView && mode === 'edit' && (fsMode === 'locked' || fsMode === 'toggle' && isFullscreen);
   /** toggle 时左下 Dock 展示全屏；locked/disabled 不传 API */
   var dockToggleFullscreen = isFloorMapView && fsMode === 'toggle' ? toggleFullscreen : undefined;
+
+  /** 编辑态始终保留顶栏 Tab（单画布也要能「添加画布」）；仅阅读态在单画布时可隐藏 Tab 行 */
+  var showEditCompactTopBar = isFloorMapView && mode === 'edit' && Boolean(config) && !useFullTopChrome;
+
+  /** 右下角视口控件：平面图下默认带出全屏按钮（若当前策略允许 toggle） */
   var viewControlsConfig = useMemo(function () {
     var _controls$showFullscr;
     if (!isFloorMapView) return controls;
@@ -266,10 +285,14 @@ function PisellFloorMapLayoutInner(props, ref) {
     });
   }, [isFloorMapView, controls, dockToggleFullscreen]);
   var topBarExtraActions = null;
+
+  /** 从侧栏/调色板拖入画布时，地图区高亮态（用于 dragleave/over 判定） */
   var _useState = useState(false),
     _useState2 = _slicedToArray(_useState, 2),
     mapPaletteDragActive = _useState2[0],
     setMapPaletteDragActive = _useState2[1];
+
+  /** 全局 dragend 时清除调色板拖入高亮，避免松手在画布外仍保持 active */
   useEffect(function () {
     var clear = function clear() {
       return setMapPaletteDragActive(false);
@@ -279,6 +302,10 @@ function PisellFloorMapLayoutInner(props, ref) {
       return window.removeEventListener('dragend', clear);
     };
   }, []);
+
+  /**
+   * 桌面端：在画布 drop 层释放拖拽时，解析 dataTransfer 并在场景坐标下落位图元。
+   */
   var handlePaletteDropOnCanvas = useCallback(function (e) {
     e.preventDefault();
     e.stopPropagation();
@@ -297,6 +324,10 @@ function PisellFloorMapLayoutInner(props, ref) {
       recordIds: payload.recordIds
     });
   }, [isFloorMapView, mode, placeSceneElementFromPaletteDrop]);
+
+  /**
+   * 触摸拖拽模拟 drop：由 {@link useFloorMapPaletteTouchDrag} 在松手时调用，逻辑同桌面 drop。
+   */
   var applyPaletteTouchDropInScene = useCallback(function (payload, cx, cy) {
     if (!isFloorMapView || mode !== 'edit') return;
     placeSceneElementFromPaletteDrop(cx, cy, {
@@ -316,9 +347,15 @@ function PisellFloorMapLayoutInner(props, ref) {
     setMapPaletteDragActive: setMapPaletteDragActive,
     onDropInScene: applyPaletteTouchDropInScene
   });
+
+  /** 平面图下未配置对应 kind 的 `renderItemByKind` 时的占位渲染 */
   var fallbackPlaceholderRender = useCallback(function (item) {
     return renderFloorMapFallbackPlaceholder(item);
   }, []);
+
+  /**
+   * 统一图元渲染入口：平面图优先按 kind 查 `renderItemByKind`，校验绑定/配置问题后回退占位或 `renderItem`。
+   */
   var effectiveRenderItem = useCallback(function (item, index, options) {
     var merged = item;
     var kind = merged === null || merged === void 0 ? void 0 : merged.elementKind;
@@ -344,10 +381,14 @@ function PisellFloorMapLayoutInner(props, ref) {
     }
     return renderItem(item, index, options);
   }, [isFloorMapView, floorMapConfigProp, dataSources, renderItemByKind, renderItem, fallbackPlaceholderRender, onElementRenderError]);
+
+  /** 点击图元：编辑态同步选中 id，并透传业务 `onItemClick` */
   var handleItemClick = useCallback(function (item, index, e) {
     if (isFloorMapView && mode === 'edit') setSelectedId(item.id);
     onItemClick === null || onItemClick === void 0 || onItemClick(item, index, e);
   }, [isFloorMapView, mode, onItemClick, setSelectedId]);
+
+  /** 对外 ref：缩放/复位/套合视口/保存布局，见 {@link PisellFloorMapLayoutRef} */
   useImperativeHandle(ref, function () {
     return {
       zoomIn: function zoomIn() {
@@ -492,7 +533,8 @@ function PisellFloorMapLayoutInner(props, ref) {
       minWidth: 0,
       overflow: 'hidden'
     },
-    onClick: handleMapAreaBackgroundClick,
+    onClick: handleMapAreaBackgroundClick
+    /* 编辑态：侧栏 palette 拖入时 enter/over 维持 drop 合法态，leave 出地图区则取消高亮 */,
     onDragEnter: function onDragEnter(e) {
       if (!isFloorMapView || mode !== 'edit') return;
       if (!isFloorMapPaletteDrag(e.dataTransfer)) return;
@@ -661,6 +703,8 @@ function PisellFloorMapLayoutInner(props, ref) {
     }))));
   }))));
 }
+
+/** 空间布局根组件：阅读/编辑、列表与平面图双模式，ref 见 {@link PisellFloorMapLayoutRef} */
 var PisellFloorMapLayout = /*#__PURE__*/React.forwardRef(PisellFloorMapLayoutInner);
 export { PisellFloorMapLayout };
 export default PisellFloorMapLayout;

package/es/components/pisellFloorMapLayout/types.d.ts

@@ -587,18 +587,18 @@ export declare type FloorMapViewportOverlayRenderArgs<T extends FloorMapItemBase
     mode: 'read' | 'edit';
 };
 /**
- * PisellFloorMapLayout Ref 方法
- * @description 供外部调用缩放、复位、区域定位等
+ * `PisellFloorMapLayout` 通过 ref 暴露的 imperative API。
+ * 缩放/复位委托内部 `react-zoom-pan-pinch`；`fitBounds` / `saveLayout` 依赖当前画布与编辑状态。
  */
 export interface PisellFloorMapLayoutRef {
-    /** 放大 */
+    /** 在允许范围内放大一级（与右下角「+」一致） */
     zoomIn: () => void;
-    /** 缩小 */
+    /** 在允许范围内缩小一级（与右下角「−」一致） */
     zoomOut: () => void;
-    /** 复位到默认缩放与位置 */
+    /** 重置 transform 为初始 scale 与 initialPosition（与「复位」控件一致） */
     reset: () => void;
-    /** 区域定位：使所有 items 落在视口内 */
+    /** 计算内容包盒并将视口平移/缩放至全部图元可见 */
     fitBounds: () => void;
-    /** 提交当前布局草稿（与顶栏/侧栏「保存」一致） */
+    /** 触发与顶栏/侧栏相同的保存流程（无 `onSave` 时内部可能为 no-op，由 hook 决定） */
     saveLayout: () => void;
 }

package/es/components/pisellFloorMapLayout/types.js

@@ -147,6 +147,6 @@ export var FLOOR_MAP_IMAGE_ELEMENT_KIND = 'floorMapImage';
  */
 
 /**
- * PisellFloorMapLayout Ref 方法
- * @description 供外部调用缩放、复位、区域定位等
+ * `PisellFloorMapLayout` 通过 ref 暴露的 imperative API。
+ * 缩放/复位委托内部 `react-zoom-pan-pinch`；`fitBounds` / `saveLayout` 依赖当前画布与编辑状态。
  */

package/es/components/pisellGridPro/GridView/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import './index.less';
 import { GridViewProps } from './type';
 export type { GridViewProps };

package/es/components/pisellGridPro/components/DataCard/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { DataCardProps } from './types';
 export type { DataCardProps };
 import './index.less';

package/es/components/pisellInformationEntry/Scan/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import './index.less';
 export interface ScanProps {
     onChange: (val: string) => void;

package/es/components/pisellInput/components/BankCard/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { InputProps } from 'antd';
 import { PisellContextType } from "../../../pisell-config-provider/context";
 import './index.less';

package/es/components/pisellInput/components/Copy/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { InputProps, ButtonProps } from 'antd';
 import { PisellContextType } from "../../../pisell-config-provider/context";
 export interface CopyProps extends InputProps {

package/es/components/pisellInput/components/SecurityCode/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { InputProps } from 'antd';
 import './index.less';
 import { PisellContextType } from "../../../pisell-config-provider/context";

package/es/components/pisellInput/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { InputProps } from 'antd';
 import { PisellContextType } from '../pisell-config-provider/context';
 declare const PisellInput: {

package/es/components/pisellLoading/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import { SpinProps } from 'antd';
 import './index.less';
 declare type MaskType = {