@piying-lib/angular-daisyui 1.2.0 → 1.2.2

package/fesm2022/piying-lib-angular-daisyui-extension.mjs

@@ -26,13 +26,28 @@ import { TemplatePortal } from '@angular/cdk/portal';
 import { takeWhile } from 'rxjs/operators';
 
 const routerLinkActiveOptions = { exact: false };
+/*
+ * MenuTreeNFCC - 导航菜单树组件
+ *
+ * 用途: 用于显示具有层级结构的导航菜单，支持多种导航项类型（basic/divider/group）
+ * 特性:
+ *   - 支持横向和纵向布局
+ *   - 支持不同尺寸显示
+ *   - 可自定义菜单项模板
+ *   - 集成 Angular Router，支持路由激活状态显示
+ *
+ * 使用场景: 侧边栏导航、顶部导航菜单等需要层级结构的导航场景
+ */
 class MenuTreeNFCC {
     static __version = 2;
     routerLinkActiveOptions = routerLinkActiveOptions;
     StrOrTemplateComponent = StrOrTemplateComponent;
     templateRef = viewChild.required('templateRef');
+    /** 菜单项列表 */
     list = input([], ...(ngDevMode ? [{ debugName: "list" }] : []));
+    /** 尺寸大小 */
     size = input(...(ngDevMode ? [undefined, { debugName: "size" }] : []));
+    /** 方向 */
     direction = input(...(ngDevMode ? [undefined, { debugName: "direction" }] : []));
     #theme = inject(ThemeService);
     wrapperClass$ = computed(() => {
@@ -71,12 +86,27 @@ const SubsetMatchOptions = {
 function goPage(value) {
     return { type: 'go', value };
 }
+/*
+ * PaginationNFCC - 分页组件
+ *
+ * 用途: 用于分页显示大量数据，支持自定义每页条数和跳转页面
+ * 特性:
+ *   - 支持横向和纵向布局
+ *   - 可配置每页显示条数选项
+ *   - 支持自定义页码标签
+ *   - 集成 piying-view 字段系统，自动同步分页属性
+ *
+ * 使用场景: 数据表格分页、列表分页等需要分页功能的场景
+ */
 class PaginationNFCC {
     static __version = 2;
     StrOrTemplateComponent = StrOrTemplateComponent;
     templateRef = viewChild.required('templateRef');
+    /** 方向 */
     direction = input(...(ngDevMode ? [undefined, { debugName: "direction" }] : []));
+    /** 每页条数选项 */
     sizeOptions = input(...(ngDevMode ? [undefined, { debugName: "sizeOptions" }] : []));
+    /** 每页条数标签函数 */
     optionsLabel = input(...(ngDevMode ? [undefined, { debugName: "optionsLabel" }] : []));
     value = model.required(...(ngDevMode ? [{ debugName: "value" }] : []));
     // todo 临时兼容
@@ -167,6 +197,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
             args: [{ selector: 'app-pagination', imports: [AttributesDirective, PurePipe, FormsModule, MergeClassPipe], template: "<ng-template #templateRef let-attr=\"attributes\">\n  <div\n    [class]=\"'flex items-center gap-2' | mergeClass: attr()?.class\"\n    [attributes]=\"attr()\"\n    [excludes]=\"['class']\"\n  >\n    @if (sizeOptions(); as sizeOptions) {\n      <select class=\"select w-20\" [ngModel]=\"value().size\" (ngModelChange)=\"pageSizeChange($event)\">\n        @for (item of sizeOptions; track $index) {\n          <option [ngValue]=\"item\">\n            {{ optionsLabel() ? (optionsLabel()! | pure: item : value().index : count()) : item }}\n          </option>\n        }\n      </select>\n    }\n    <div [class]=\"wrapperClass$()\">\n      <button\n        class=\"join-item btn p-0 w-(--size)\"\n        [disabled]=\"value().index === 0\"\n        (click)=\"gotoPage(0)\"\n      >\n        \u00AB\n      </button>\n      @for (item of pageRange$$(); track $index) {\n        @if (item.type === 'go') {\n          <button\n            class=\"join-item btn p-0 w-(--size)\"\n            [aria-label]=\"item.value + 1\"\n            [class.btn-active]=\"item.value === value().index\"\n            (click)=\"gotoPage(item.value)\"\n          >\n            {{ item.value + 1 }}\n          </button>\n        } @else if (item.type === 'prev') {\n          <button class=\"join-item btn p-0 w-(--size)\" (click)=\"gotoPage(value().index - 5)\">\n            <\n          </button>\n        } @else if (item.type === 'next') {\n          <button class=\"join-item btn p-0 w-(--size)\" (click)=\"gotoPage(value().index + 5)\">\n            >\n          </button>\n        }\n      }\n      <button\n        class=\"join-item btn p-0 w-(--size)\"\n        [disabled]=\"value().index === maxPageCount$$() - 1\"\n        (click)=\"gotoPage(maxPageCount$$() - 1)\"\n      >\n        \u00BB\n      </button>\n    </div>\n  </div>\n</ng-template>\n" }]
         }], propDecorators: { templateRef: [{ type: i0.ViewChild, args: ['templateRef', { isSignal: true }] }], direction: [{ type: i0.Input, args: [{ isSignal: true, alias: "direction", required: false }] }], sizeOptions: [{ type: i0.Input, args: [{ isSignal: true, alias: "sizeOptions", required: false }] }], optionsLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "optionsLabel", required: false }] }], value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: true }] }, { type: i0.Output, args: ["valueChange"] }], valueChange: [{ type: i0.Output, args: ["valueChange"] }], count: [{ type: i0.Input, args: [{ isSignal: true, alias: "count", required: true }] }] } });
 
+/*
+ * TableRowFGC - 表格行组件
+ *
+ * 用途: 作为表格行的容器组件，用于包裹表格行内的字段组
+ * 特性:
+ *   - 作为表格行的基类组件
+ *   - 支持字段组功能
+ *
+ * 使用场景: table使用
+ */
 class TableRowFGC extends PiyingViewGroupBase {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.14", ngImport: i0, type: TableRowFGC, deps: null, target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.14", type: TableRowFGC, isStandalone: true, selector: "tr", providers: [], usesInheritance: true, ngImport: i0, template: "@for (field of children$$(); track $index) {\n  <ng-container\n    *ngTemplateOutlet=\"fieldTemplateRef(); context: { $implicit: field, injector }\"\n  ></ng-container>\n}\n", dependencies: [{ kind: "directive", type: NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }, { kind: "ngmodule", type: FormsModule }] });
@@ -194,13 +234,33 @@ function createDefaultColDefineFn(isHeader, content, context) {
         },
     }), actions.wrappers.set([{ type: isHeader ? ThWC : TdWC }]));
 }
+/*
+ * TableNFCC - 数据表格组件
+ *
+ * 用途: 用于显示和管理大量结构化数据，支持丰富的列定义和行操作
+ * 特性:
+ *   - 支持表头、表体、表脚三部分的自定义渲染
+ *   - 支持列组定义，可配置列的显示内容和格式
+ *   - 支持行展开功能（ExpandOneTableCell）
+ *   - 集成 piying-view Schema 系统，支持动态数据和验证
+ *   - 支持排序、状态管理等高级功能
+ *
+ * 使用场景: 数据列表展示、管理后台、报表等需要表格形式展示数据的场景
+ *
+ * 核心类型:
+ *   - ItemCell: 列内容定义（字符串/Schema/函数）
+ *   - ColumnDefine: 列定义（head/body/foot）
+ *   - TableItemDefine2: 表格完整定义（行+列）
+ */
 class TableNFCC {
     static __version = 2;
     templateRef = viewChild.required('templateRef');
     #field = inject(PI_VIEW_FIELD_TOKEN$1);
     StrOrTemplateComponent = StrOrTemplateComponent;
+    /** 表格定义 */
     define = input(...(ngDevMode ? [undefined, { debugName: "define" }] : []));
     // todo待修改
+    /** 数据列表 */
     data = input([], ...(ngDevMode ? [{ debugName: "data" }] : []));
     injector = inject(Injector);
     data$$ = computed(() => {
@@ -208,12 +268,17 @@ class TableNFCC {
         return Array.isArray(data) ? data : data();
     }, ...(ngDevMode ? [{ debugName: "data$$" }] : []));
     #status = inject(TABLE_STATUS_TOKEN, { optional: true });
+    /** 是否启用斑马纹效果 */
     zebra = input(...(ngDevMode ? [undefined, { debugName: "zebra" }] : []));
+    /** 固定配置 */
     pin = input(...(ngDevMode ? [undefined, { debugName: "pin" }] : []));
+    /** 尺寸大小 */
     size = input(...(ngDevMode ? [undefined, { debugName: "size" }] : []));
+    /** 跟踪函数 */
     trackBy = input((key, value) => {
         return key;
     }, ...(ngDevMode ? [{ debugName: "trackBy" }] : []));
+    /** 分页配置 */
     pagination = input(...(ngDevMode ? [undefined, { debugName: "pagination" }] : []));
     type = input(...(ngDevMode ? [undefined, { debugName: "type" }] : []));
     #theme = inject(ThemeService);
@@ -392,6 +457,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
         }] });
 
 class inputSortDirective {
+    /** 排序键 */
     key = input.required(...(ngDevMode ? [{ debugName: "key" }] : []));
     inputSort = signal(0, ...(ngDevMode ? [{ debugName: "inputSort" }] : []));
     #el = inject(ElementRef).nativeElement;
@@ -438,6 +504,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
                 args: ['change']
             }] } });
 
+/*
+ * SortHeaderWC - 排序列头包装器组件
+ *
+ * 用途: 用于表格列的排序控制，通常与 Table 组件配合使用
+ * 特性:
+ *   - 显示排序图标和排序状态
+ *   - 支持点击触发排序
+ *   - 集成 piying-view 字段系统
+ *   - 支持通过 props 设置排序 key
+ *
+ * 使用场景: 表格列需要排序功能时作为列的包装器使用
+ */
 class SortHeaderWC {
     static __version = 2;
     templateRef = viewChild.required('templateRef');
@@ -559,6 +637,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
             type: Injectable
         }] });
 
+/*
+ * TableCheckboxAllWC - 表格全选复选框包装器组件
+ *
+ * 用途: 用于表格的全选功能，控制所有行的选中状态
+ * 特性:
+ *   - 显示全选/取消全选按钮
+ *   - 同步表格行的选中状态
+ *   - 集成 CheckboxService 进行状态管理
+ *   - 集成 piying-view 字段系统
+ *
+ * 使用场景: 表格需要批量操作时，用于控制所有行的选中状态
+ */
 class TableCheckboxAllWC {
     field$$ = inject(PI_VIEW_FIELD_TOKEN);
     props$$ = computed(() => this.field$$().props(), ...(ngDevMode ? [{ debugName: "props$$" }] : []));
@@ -586,6 +676,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
             args: [{ selector: 'app-table-checkbox-all', imports: [InsertFieldDirective], template: "<ng-template #templateRef let-attr=\"attributes\">\n  <ng-container insertField></ng-container>\n</ng-template>\n" }]
         }], ctorParameters: () => [], propDecorators: { templateRef: [{ type: i0.ViewChild, args: ['templateRef', { isSignal: true }] }] } });
 
+/*
+ * TableCheckboxOneWC - 表格单选复选框包装器组件
+ *
+ * 用途: 用于表格单行的复选框控制，管理单行的选中状态
+ * 特性:
+ *   - 显示单行的复选框
+ *   - 同步单行的选中状态到服务
+ *   - 集成 CheckboxService 进行状态管理
+ *   - 集成 piying-view 字段系统
+ *
+ * 使用场景: 表格需要批量操作时，用于控制单行的选中状态
+ */
 class TableCheckboxOneWC {
     static __version = 2;
     templateRef = viewChild.required('templateRef');
@@ -730,6 +832,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
             type: Injectable
         }] });
 
+/*
+ * TableExpandOneTableCell - 表格行展开单元格组件
+ *
+ * 用途: 用于表格行的展开控制，显示和控制行的展开状态
+ * 特性:
+ *   - 显示展开/收起按钮
+ *   - 控制行的展开状态
+ *   - 集成 TableExpandService 进行状态管理
+ *   - 集成 piying-view 字段系统
+ *
+ * 使用场景: 表格行需要展开显示详细信息的场景
+ */
 class TableExpandOneTableCell {
     static __version = 2;
     templateRef = viewChild.required('templateRef');
@@ -835,34 +949,36 @@ class CdkConnectedOverlay {
     _position;
     _scrollStrategyFactory = inject(CDK_CONNECTED_OVERLAY_SCROLL_STRATEGY);
     _ngZone = inject(NgZone);
-    /** Origin for the connected overlay. */
+    /** 弹窗触发原点 */
     origin = input.required(...(ngDevMode ? [{ debugName: "origin" }] : []));
-    /** Registered connected position pairs. */
+    /** 已注册的连接位置对 */
     positions = input(...(ngDevMode ? [undefined, { debugName: "positions" }] : []));
     positions$$ = computed(() => {
         const pos = this.positions();
         return pos && pos.length ? pos : defaultPositionList;
     }, ...(ngDevMode ? [{ debugName: "positions$$" }] : []));
-    /** The offset in pixels for the overlay connection point on the x-axis */
+    /** 弹窗连接点相对于原点的 x 轴偏移量（像素） */
     offsetX = input(...(ngDevMode ? [undefined, { debugName: "offsetX" }] : []));
-    /** The offset in pixels for the overlay connection point on the y-axis */
+    /** 弹窗连接点相对于原点的 y 轴偏移量（像素） */
     offsetY = input(...(ngDevMode ? [undefined, { debugName: "offsetY" }] : []));
+    /** 弹窗配置 */
     overlayConfig = input(...(ngDevMode ? [undefined, { debugName: "overlayConfig" }] : []));
-    /** Margin between the overlay and the viewport edges. */
+    /** 弹窗与视口边缘之间的间距（像素） */
     viewportMargin = input(0, ...(ngDevMode ? [{ debugName: "viewportMargin" }] : []));
     open = model(false, ...(ngDevMode ? [{ debugName: "open" }] : []));
-    /** Whether the overlay can be closed by user interaction. */
+    /** 是否可以通过用户交互关闭弹窗 */
     disableClose = input(false, ...(ngDevMode ? [{ debugName: "disableClose" }] : []));
-    /** CSS selector which to set the transform origin. */
+    /** 用于设置 transform origin 的 CSS 选择器 */
     transformOriginSelector = input(...(ngDevMode ? [undefined, { debugName: "transformOriginSelector" }] : []));
-    /** Whether or not the overlay should be locked when scrolling. */
+    /** 滚动时是否锁定弹窗位置 */
     lockPosition = input(false, ...(ngDevMode ? [{ debugName: "lockPosition" }] : []));
-    /** Whether the overlay's width and height can be constrained to fit within the viewport. */
+    /** 弹窗的宽高是否可以被约束以适应视口 */
     flexibleDimensions = input(false, ...(ngDevMode ? [{ debugName: "flexibleDimensions" }] : []));
-    /** Whether the overlay can grow after the initial open when flexible positioning is turned on. */
+    /** 在启用灵活定位后，弹窗是否可以在首次打开后增长 */
     growAfterOpen = input(false, ...(ngDevMode ? [{ debugName: "growAfterOpen" }] : []));
-    /** Whether the overlay can be pushed on-screen if none of the provided positions fit. */
+    /** 如果提供的位置都不合适，弹窗是否可以被推到屏幕上 */
     push = input(false, ...(ngDevMode ? [{ debugName: "push" }] : []));
+    /** 弹窗宽度是否与原点宽度匹配 */
     matchWidth = input(false, ...(ngDevMode ? [{ debugName: "matchWidth" }] : []));
     /** Event emitted when the backdrop is clicked. */
     backdropClick = new EventEmitter();
@@ -1087,16 +1203,33 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
                 type: Output
             }] } });
 
+/*
+ * PickerRefFCC - 选择器引用组件
+ *
+ * 用途: 用于触发选择器弹窗，支持自定义触发器和内容区域
+ * 特性:
+ *   - 支持自定义触发器内容（trigger）
+ *   - 支持自定义弹窗内容（content）
+ *   - 支持选择后自动关闭（changeClose）
+ *   - 基于 CDK Overlay 实现弹窗定位
+ *   - 实现了 ControlValueAccessor 接口，可直接用于表单
+ *
+ * 使用场景: 选择器、下拉选择、日期时间选择等需要弹窗选择的场景
+ */
 class PickerRefFCC extends BaseControl {
     static index = 0;
     SelectorlessOutlet = SelectorlessOutlet;
     static __version = 2;
     templateRef = viewChild.required('templateRef');
     PiyingView = PiyingView;
+    /** 触发器内容 */
     trigger = input(...(ngDevMode ? [undefined, { debugName: "trigger" }] : []));
+    /** 弹窗内容 */
     content = input(...(ngDevMode ? [undefined, { debugName: "content" }] : []));
+    /** 选择后是否自动关闭 */
     changeClose = input(...(ngDevMode ? [undefined, { debugName: "changeClose" }] : []));
     isOpen$ = signal(false, ...(ngDevMode ? [{ debugName: "isOpen$" }] : []));
+    /** 弹窗配置 */
     overlayConfig = input(...(ngDevMode ? [undefined, { debugName: "overlayConfig" }] : []));
     position$ = signal('', ...(ngDevMode ? [{ debugName: "position$" }] : []));
     parentPyOptions = inject(PI_INPUT_OPTIONS_TOKEN, { optional: true });
@@ -1166,15 +1299,31 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
                     ], changeDetection: ChangeDetectionStrategy.OnPush, template: "<ng-template #templateRef let-attr=\"attributes\">\n  <div cdkOverlayOrigin #trigger=\"cdkOverlayOrigin\" [attributes]=\"attr()\" (click)=\"openRef()\">\n    <ng-container\n      [selectlessOutlet]=\"PiyingView\"\n      [selectlessOutletInputs]=\"triggerInput$$()\"\n    ></ng-container>\n  </div>\n\n  <ng-template\n    cdkConnectedOverlay\n    [origin]=\"trigger\"\n    [open]=\"isOpen$()\"\n    [overlayConfig]=\"overlayConfig()\"\n    (detach)=\"isOpen$.set(false)\"\n    (overlayOutsideClick)=\"outsideClick()\"\n  >\n    <ng-container\n      [selectlessOutlet]=\"PiyingView\"\n      [selectlessOutletInputs]=\"contentInput$$()\"\n      [selectlessOutletOutputs]=\"contentOutput$$()\"\n    ></ng-container>\n  </ng-template>\n</ng-template>\n" }]
         }], propDecorators: { templateRef: [{ type: i0.ViewChild, args: ['templateRef', { isSignal: true }] }], trigger: [{ type: i0.Input, args: [{ isSignal: true, alias: "trigger", required: false }] }], content: [{ type: i0.Input, args: [{ isSignal: true, alias: "content", required: false }] }], changeClose: [{ type: i0.Input, args: [{ isSignal: true, alias: "changeClose", required: false }] }], overlayConfig: [{ type: i0.Input, args: [{ isSignal: true, alias: "overlayConfig", required: false }] }] } });
 
+/*
+ * OptionListFCC - 选项列表组件
+ *
+ * 用途: 用于显示可选择的选项列表，支持自定义选项模板和转换规则
+ * 特性:
+ *   - 支持动态选项数据（options）
+ *   - 支持自定义选项模板（optionTemplate）
+ *   - 支持选项转换器（optionConvert）
+ *   - 实现了 ControlValueAccessor 接口，可直接用于表单
+ *   - 集成 piying-view 字段系统
+ *
+ * 使用场景: 下拉选择、单选列表、选项选择等需要选项列表的场景
+ */
 class OptionListFCC extends BaseControl {
     static __version = 2;
     StrOrTemplateComponent = StrOrTemplateComponent;
     PiyingView = PiyingView;
     templateRef = viewChild.required('templateRef');
+    /** 选项列表 */
     options = input([], ...(ngDevMode ? [{ debugName: "options", transform: (input) => input ?? [] }] : [{
             transform: (input) => input ?? [],
         }]));
+    /** 选项模板 */
     optionTemplate = input(...(ngDevMode ? [undefined, { debugName: "optionTemplate" }] : []));
+    /** 选项转换器 */
     optionConvert = input(DefaultOptionConvert, ...(ngDevMode ? [{ debugName: "optionConvert", transform: (input) => ({ ...DefaultOptionConvert, ...input }) }] : [{
             transform: (input) => ({ ...DefaultOptionConvert, ...input }),
         }]));
@@ -1221,12 +1370,26 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
                     ], template: "<ng-template #liGroup let-item>\n  <!-- todo open\u6D4B\u8BD5 -->\n  <details open>\n    <summary>{{ item.label }}</summary>\n    <ul>\n      @for (child of item.children; track $index) {\n        <ng-container\n          *ngTemplateOutlet=\"itemTemplate; context: { $implicit: child }\"\n        ></ng-container>\n      }\n    </ul>\n  </details>\n</ng-template>\n<ng-template #itemTemplate let-option>\n  @let rOption = transformOption | pure: option : optionConvert();\n  @let template = optionTemplate()?.[rOption.type];\n  @if (template) {\n    <ng-container\n      [selectlessOutlet]=\"PiyingView\"\n      [selectlessOutletInputs]=\"getInput$$ | pure: template\"\n    ></ng-container>\n  } @else if (rOption.type === 'option') {\n    <li (click)=\"selectOption(rOption)\">\n      <button [class]=\"activateClass | pure: rOption.value : value$()\">\n        <ng-template\n          [selectlessOutlet]=\"StrOrTemplateComponent\"\n          [selectlessOutletInputs]=\"optionInput | pure: rOption.label\"\n        ></ng-template>\n      </button>\n    </li>\n  } @else if (rOption.type === 'group') {\n    <li>\n      <details open>\n        <summary>\n          <ng-template\n            [selectlessOutlet]=\"StrOrTemplateComponent\"\n            [selectlessOutletInputs]=\"optionInput | pure: rOption.label\"\n          ></ng-template>\n        </summary>\n        <ul>\n          @for (child of rOption.children; track $index) {\n            <ng-container\n              *ngTemplateOutlet=\"itemTemplate; context: { $implicit: child }\"\n            ></ng-container>\n          }\n        </ul>\n      </details>\n    </li>\n  }\n</ng-template>\n\n<ng-template #templateRef let-attr=\"attributes\">\n  <ul class=\"menu\">\n    @for (option of options(); track $index) {\n      <ng-container *ngTemplateOutlet=\"itemTemplate; context: { $implicit: option }\"></ng-container>\n    }\n  </ul>\n</ng-template>\n" }]
         }], propDecorators: { templateRef: [{ type: i0.ViewChild, args: ['templateRef', { isSignal: true }] }], options: [{ type: i0.Input, args: [{ isSignal: true, alias: "options", required: false }] }], optionTemplate: [{ type: i0.Input, args: [{ isSignal: true, alias: "optionTemplate", required: false }] }], optionConvert: [{ type: i0.Input, args: [{ isSignal: true, alias: "optionConvert", required: false }] }] } });
 
+/*
+ * ListTemplateNFCC - 列表模板组件
+ *
+ * 用途: 用于基于模板渲染列表数据，支持动态上下文传递
+ * 特性:
+ *   - 支持自定义模板（template）
+ *   - 支持列表数据渲染（list）
+ *   - 支持传递父级和项的上下文信息
+ *   - 集成 piying-view 字段系统
+ *
+ * 使用场景: 动态列表渲染、模板化列表展示等需要基于模板渲染列表的场景
+ */
 class ListTemplateNFCC {
     static __version = 2;
     StrOrTemplateComponent = StrOrTemplateComponent;
     PiyingView = PiyingView;
     templateRef = viewChild.required('templateRef');
+    /** 模板 */
     template = input.required(...(ngDevMode ? [{ debugName: "template" }] : []));
+    /** 列表数据 */
     list = input([], ...(ngDevMode ? [{ debugName: "list" }] : []));
     parentPyOptions = inject(PI_INPUT_OPTIONS_TOKEN, { optional: true });
     field = inject(PI_VIEW_FIELD_TOKEN);
@@ -1252,16 +1415,37 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
             args: [{ selector: 'app-list-template', imports: [SelectorlessOutlet, PurePipe], template: "<ng-template #templateRef let-attr=\"attributes\">\n  @for (child of list(); track $index) {\n    <ng-container\n      [selectlessOutlet]=\"PiyingView\"\n      [selectlessOutletInputs]=\"templateInput$$ | pure: child\"\n    ></ng-container>\n  }\n</ng-template>\n" }]
         }], propDecorators: { templateRef: [{ type: i0.ViewChild, args: ['templateRef', { isSignal: true }] }], template: [{ type: i0.Input, args: [{ isSignal: true, alias: "template", required: true }] }], list: [{ type: i0.Input, args: [{ isSignal: true, alias: "list", required: false }] }] } });
 
+/*
+ * EditableGroupFGC - 可编辑组组件
+ *
+ * 用途: 用于动态管理可增删的组数据，支持键值对和单值两种模式
+ * 特性:
+ *   - 支持添加和删除组项
+ *   - 支持横向和纵向布局
+ *   - 支持设置最小长度限制
+ *   - 支持自定义新增项的初始值
+ *   - 支持键值对模式（通过 groupKeySchema）
+ *   - 集成 piying-view 字段系统
+ *
+ * 使用场景: 动态表单项、可增删的数据组、键值对列表等需要动态管理组数据的场景
+ */
 class EditableGroupFGC extends PiyingViewGroupBase {
     static __version = 2;
     templateRef = viewChild.required('templateRef');
     PiyingView = PiyingView;
+    /** 布局方式 */
     layout = input('row', ...(ngDevMode ? [{ debugName: "layout" }] : []));
+    /** 是否禁用添加 */
     disableAdd = input(false, ...(ngDevMode ? [{ debugName: "disableAdd" }] : []));
+    /** 添加模式 */
     addMode = input(0, ...(ngDevMode ? [{ debugName: "addMode" }] : []));
+    /** 是否禁用删除 */
     disableRemove = input(false, ...(ngDevMode ? [{ debugName: "disableRemove" }] : []));
+    /** 添加位置 */
     addPosition = input('bottom', ...(ngDevMode ? [{ debugName: "addPosition" }] : []));
+    /** 初始值生成函数 */
     initValue = input(...(ngDevMode ? [undefined, { debugName: "initValue" }] : []));
+    /** 最小长度 */
     minLength = input(0, ...(ngDevMode ? [{ debugName: "minLength" }] : []));
     isRecord$$ = computed(() => {
         return !!this.field$$().form.control.config$().groupKeySchema;
@@ -1349,10 +1533,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
         }], propDecorators: { templateRef: [{ type: i0.ViewChild, args: ['templateRef', { isSignal: true }] }], layout: [{ type: i0.Input, args: [{ isSignal: true, alias: "layout", required: false }] }], disableAdd: [{ type: i0.Input, args: [{ isSignal: true, alias: "disableAdd", required: false }] }], addMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "addMode", required: false }] }], disableRemove: [{ type: i0.Input, args: [{ isSignal: true, alias: "disableRemove", required: false }] }], addPosition: [{ type: i0.Input, args: [{ isSignal: true, alias: "addPosition", required: false }] }], initValue: [{ type: i0.Input, args: [{ isSignal: true, alias: "initValue", required: false }] }], minLength: [{ type: i0.Input, args: [{ isSignal: true, alias: "minLength", required: false }] }] } });
 
 const Empty_Array = [];
+/*
+ * CheckboxListFGC - 复选框列表组件
+ *
+ * 用途: 用于显示可多选的复选框列表，支持动态选项和自定义配置
+ * 特性:
+ *   - 支持动态复选框选项（options）
+ *   - 支持自定义每个选项的 Schema 和属性
+ *   - 实现了 ControlValueAccessor 接口，可直接用于表单
+ *   - 基于 piying-view 字段系统，支持动态验证和状态管理
+ *   - 支持值的增删操作
+ *
+ * 使用场景: 多选列表、权限选择、标签选择等需要多选功能的场景
+ */
 class CheckboxListFGC extends PiyingViewGroupBase {
     static __version = 2;
     templateRef = viewChild.required('templateRef');
     PiyingView = PiyingView;
+    /** 选项列表 */
     options = input(...(ngDevMode ? [undefined, { debugName: "options" }] : []));
     #parentPyOptions = inject(PI_INPUT_OPTIONS_TOKEN, { optional: true });
     templateSchema$$ = computed(() => {
@@ -1415,6 +1613,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
                     ], template: "<ng-template #templateRef let-attr=\"attributes\" let-events=\"events\">\n  @for (item of options(); track $index) {\n    <ng-container\n      [selectlessOutlet]=\"PiyingView\"\n      [selectlessOutletInputs]=\"\n        schemaOptions$$ | pure: (schemaItemFn | pure: templateSchema$$() : item) : item : value$$()\n      \"\n      [selectlessOutletOutputs]=\"modelOutput | pure: item.value\"\n    ></ng-container>\n  }\n</ng-template>\n" }]
         }], propDecorators: { templateRef: [{ type: i0.ViewChild, args: ['templateRef', { isSignal: true }] }], options: [{ type: i0.Input, args: [{ isSignal: true, alias: "options", required: false }] }] } });
 
+/*
+ * logicGroupFGC - 逻辑组组件
+ *
+ * 用途: 用于根据逻辑条件控制子组件的激活状态
+ * 特性:
+ *   - 根据 FieldLogicGroup 的激活状态显示子组件
+ *   - 自动过滤未激活的子组件
+ *   - 集成 piying-view 字段系统
+ *
+ * 使用场景: 条件显示、逻辑控制、动态表单等需要根据逻辑条件控制组件显示的场景
+ */
 class logicGroupFGC extends PiyingViewGroupBase {
     static __version = 2;
     templateRef = viewChild.required('templateRef');
@@ -1447,6 +1656,18 @@ var component_index = /*#__PURE__*/Object.freeze({
     logicGroupFGC: logicGroupFGC
 });
 
+/*
+ * FilterOptionNFCC - 过滤选项组件
+ *
+ * 用途: 用于显示过滤输入框，通常与 OptionList 组件配合使用
+ * 特性:
+ *   - 显示过滤输入框
+ *   - 从 context 中获取搜索内容
+ *   - 阻止键盘事件冒泡
+ *   - 集成 piying-view 字段系统
+ *
+ * 使用场景: 选项列表需要本地过滤功能时，用于输入过滤条件
+ */
 class FilterOptionNFCC {
     static __version = 2;
     templateRef = viewChild.required('templateRef');
@@ -1463,6 +1684,19 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
             args: [{ selector: 'app-filter-option', imports: [FormsModule, CssPrefixPipe, MergeClassPipe, AttributesDirective, FormsModule], template: "<ng-template #templateRef let-attr=\"attributes\">\n  <input\n    type=\"text\"\n    [attributes]=\"attr?.()\"\n    [excludes]=\"['class']\"\n    [class]=\"attr?.().class | mergeClass: 'input' | cssPrefix\"\n    [(ngModel)]=\"content\"\n    (keydown)=\"stopKeyboardListen($event)\"\n  />\n</ng-template>\n" }]
         }], propDecorators: { templateRef: [{ type: i0.ViewChild, args: ['templateRef', { isSignal: true }] }] } });
 
+/*
+ * OptionListLocalFilterWC - 选项列表本地过滤包装器组件
+ *
+ * 用途: 用于在客户端对选项列表进行本地过滤筛选
+ * 特性:
+ *   - 支持输入搜索内容进行过滤
+ *   - 支持自定义过滤函数（filterWith）
+ *   - 支持自定义过滤选项组件（filterDefine）
+ *   - 自动同步过滤状态到选项列表
+ *   - 集成 piying-view 字段系统
+ *
+ * 使用场景: 选项列表数据量较小，需要在客户端进行筛选的场景
+ */
 class OptionListLocalFilterWC {
     static __version = 2;
     templateRef = viewChild.required('templateRef');
@@ -1518,6 +1752,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.14", ngImpo
 
 var wrapper_index = /*#__PURE__*/Object.freeze({
     __proto__: null,
+    FilterOptionNFCC: FilterOptionNFCC,
     OptionListLocalFilterWC: OptionListLocalFilterWC,
     SortHeaderWC: SortHeaderWC,
     TableCheckboxAllWC: TableCheckboxAllWC,