@aithe/aithe-ui 26.2.2 → 26.3.1

package/dist/components/feedback/toast.d.ts

@@ -1,17 +1,34 @@
-import { AitheElement } from '../../base/aithe-element';
+import { AitheElement } from '../../core/aithe-element';
 /**
- * Auto-dismiss toast message.
+ * Auto-dismiss toast message displayed at the top of the viewport.
+ * 自动消失的轻提示消息，显示在视口顶部。
+ *
+ * @slot - Default slot (unused; content driven by `content` property). 默认插槽（未使用，内容由 content 属性控制）。
+ * @fires aithe-close - Emitted when the toast auto-dismisses after duration. 自动消失后触发。
+ * @example
+ * ```html
+ * <aithe-toast content="Saved successfully" type="success" duration="2400"></aithe-toast>
+ * ```
  */
 export declare class AitheToast extends AitheElement {
+    /** Toast message text. 提示消息文本。 */
     content: string;
+    /** Display title for the toast (shown as tooltip). 提示消息的显示标题（作为工具提示）。 */
+    title: string;
+    /** Icon name to display before the content. 在内容前显示的图标名称。 */
+    icon: string;
+    /** Toast color variant. 提示颜色类型。 */
     type: 'default' | 'success' | 'warning' | 'danger';
+    /** Auto-dismiss duration in milliseconds. 自动消失时长（毫秒）。 */
     duration: number;
+    /** Whether the toast is currently visible. 是否当前可见。 */
     visible: boolean;
     private timer;
     static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(changed: Map<string, unknown>): void;
+    /** Starts the auto-dismiss timer. 启动自动消失计时器。 */
     private startTimer;
     render(): import("lit-html").TemplateResult<1>;
 }

package/dist/components/feedback/toast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toast.d.ts","sourceRoot":"","sources":["../../../src/components/feedback/toast.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD;;GAEG;AACH,qBACa,UAAW,SAAQ,YAAY;IACd,OAAO,SAAM;IACb,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAa;IAC/D,QAAQ,SAAQ;IACA,OAAO,UAAQ;IAE3D,OAAO,CAAC,KAAK,CAAK;IAElB,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAiCpB;IAEF,iBAAiB,IAAI,IAAI;IAKzB,oBAAoB,IAAI,IAAI;IAK5B,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMtD,OAAO,CAAC,UAAU;IAYlB,MAAM;CAKP"}
+{"version":3,"file":"toast.d.ts","sourceRoot":"","sources":["../../../src/components/feedback/toast.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD;;;;;;;;;;GAUG;AACH,qBACa,UAAW,SAAQ,YAAY;IAC1C,kCAAkC;IACN,OAAO,SAAM;IACzC,yEAAyE;IAC7C,KAAK,SAAM;IACvC,4DAA4D;IAChC,IAAI,SAAM;IACtC,mCAAmC;IACP,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAa;IAC3F,yDAAyD;IAC7B,QAAQ,SAAQ;IAC5C,sDAAsD;IACV,OAAO,UAAQ;IAE3D,OAAO,CAAC,KAAK,CAAK;IAElB,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAyCpB;IAEF,iBAAiB,IAAI,IAAI;IAKzB,oBAAoB,IAAI,IAAI;IAK5B,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMtD,gDAAgD;IAChD,OAAO,CAAC,UAAU;IAYlB,MAAM;CAeP"}

package/dist/components/feedback/toast.js

@@ -0,0 +1,142 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { css, html, nothing } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+import { AitheElement } from '../../core/aithe-element';
+import { aitheBaseStyles } from '../../core/styles';
+/**
+ * Auto-dismiss toast message displayed at the top of the viewport.
+ * 自动消失的轻提示消息，显示在视口顶部。
+ *
+ * @slot - Default slot (unused; content driven by `content` property). 默认插槽（未使用，内容由 content 属性控制）。
+ * @fires aithe-close - Emitted when the toast auto-dismisses after duration. 自动消失后触发。
+ * @example
+ * ```html
+ * <aithe-toast content="Saved successfully" type="success" duration="2400"></aithe-toast>
+ * ```
+ */
+let AitheToast = class AitheToast extends AitheElement {
+    constructor() {
+        super(...arguments);
+        /** Toast message text. 提示消息文本。 */
+        this.content = '';
+        /** Display title for the toast (shown as tooltip). 提示消息的显示标题（作为工具提示）。 */
+        this.title = '';
+        /** Icon name to display before the content. 在内容前显示的图标名称。 */
+        this.icon = '';
+        /** Toast color variant. 提示颜色类型。 */
+        this.type = 'default';
+        /** Auto-dismiss duration in milliseconds. 自动消失时长（毫秒）。 */
+        this.duration = 2400;
+        /** Whether the toast is currently visible. 是否当前可见。 */
+        this.visible = true;
+        this.timer = 0;
+    }
+    static { this.styles = [
+        aitheBaseStyles,
+        css `
+      :host {
+        position: fixed;
+        top: 24px;
+        left: 50%;
+        z-index: var(--aithe-z-popover);
+        transform: translateX(-50%);
+      }
+
+      .toast {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--aithe-space-2);
+        min-width: 220px;
+        padding: var(--aithe-space-3) var(--aithe-space-4);
+        border: 1px solid var(--aithe-color-border);
+        border-radius: var(--aithe-container-radius-full);
+        background: var(--aithe-color-surface-elevated);
+        box-shadow: var(--aithe-shadow-3);
+        color: var(--aithe-color-text);
+      }
+
+      .toast-icon {
+        flex-shrink: 0;
+        color: var(--aithe-color-text-muted);
+      }
+
+      .success {
+        border-color: rgba(53, 166, 111, 0.28);
+      }
+
+      .warning {
+        border-color: rgba(209, 143, 41, 0.28);
+      }
+
+      .danger {
+        border-color: rgba(223, 82, 107, 0.28);
+      }
+    `,
+    ]; }
+    connectedCallback() {
+        super.connectedCallback();
+        this.startTimer();
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        globalThis.clearTimeout(this.timer);
+    }
+    updated(changed) {
+        if (changed.has('content') || changed.has('duration') || changed.has('visible')) {
+            this.startTimer();
+        }
+    }
+    /** Starts the auto-dismiss timer. 启动自动消失计时器。 */
+    startTimer() {
+        globalThis.clearTimeout(this.timer);
+        if (!this.visible || !this.duration) {
+            return;
+        }
+        this.timer = globalThis.setTimeout(() => {
+            this.visible = false;
+            this.emit('aithe-close');
+        }, this.duration);
+    }
+    render() {
+        if (!this.visible || !this.content)
+            return html ``;
+        const toastIcon = this.icon
+            ? html `
+          <aithe-icon class="toast-icon" name=${this.icon} size="16"></aithe-icon>
+        `
+            : nothing;
+        return html `
+      <div class=${classMap({ toast: true, [this.type]: true })} title=${this.title}>
+        ${toastIcon}${this.content}
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], AitheToast.prototype, "content", void 0);
+__decorate([
+    property({ type: String })
+], AitheToast.prototype, "title", void 0);
+__decorate([
+    property({ type: String })
+], AitheToast.prototype, "icon", void 0);
+__decorate([
+    property({ type: String })
+], AitheToast.prototype, "type", void 0);
+__decorate([
+    property({ type: Number })
+], AitheToast.prototype, "duration", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], AitheToast.prototype, "visible", void 0);
+AitheToast = __decorate([
+    customElement('aithe-toast')
+], AitheToast);
+export { AitheToast };

package/dist/components/feedback/tooltip.d.ts

@@ -1,18 +1,41 @@
 import type { PropertyValues } from 'lit';
 import { AitheAnchoredOverlayElement } from '../../core/anchored-overlay';
+/**
+ * Tooltip overlay that appears on hover/focus over an anchor element.
+ * 工具提示浮层，在悬停/聚焦锚点元素时显示。
+ *
+ * @slot - Default slot for the anchor element. 锚点元素内容。
+ * @slot content - Custom tooltip content (overrides `content` property). 自定义工具提示内容。
+ * @fires aithe-dropdown-change - Inherited from AnchoredOverlay; emitted on open state change. 开关状态变更时触发。
+ * @example
+ * ```html
+ * <aithe-tooltip content="Help text here" placement="top">
+ *   <button>Hover me</button>
+ * </aithe-tooltip>
+ * ```
+ */
 export declare class AitheTooltip extends AitheAnchoredOverlayElement {
+    /** Tooltip text content. 工具提示文本内容。 */
     content: string;
+    /** Display title for the tooltip anchor (shown as native tooltip). 工具提示锚点的显示标题（作为原生工具提示）。 */
+    title: string;
+    /** Icon name to display before the tooltip content. 在工具提示内容前显示的图标名称。 */
+    icon: string;
+    /** Tooltip placement relative to anchor. 工具提示相对于锚点的位置。 */
     placement: 'top' | 'right' | 'bottom' | 'left';
-    private tooltip?;
+    private readonly tooltip?;
     private readonly tooltipId;
     static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
     protected get panelElement(): HTMLElement | null;
     protected updated(changed: PropertyValues<this>): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    private showTooltip;
-    private hideTooltip;
-    private handleKeydown;
+    /** Shows the tooltip on hover/focus. 悬停/聚焦时显示工具提示。 */
+    private readonly showTooltip;
+    /** Hides the tooltip on unhover/unfocus. 取消悬停/聚焦时隐藏工具提示。 */
+    private readonly hideTooltip;
+    /** Hides tooltip on Escape key. 按 Escape 键隐藏工具提示。 */
+    private readonly handleKeydown;
     render(): import("lit-html").TemplateResult<1>;
 }
 //# sourceMappingURL=tooltip.d.ts.map

package/dist/components/feedback/tooltip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tooltip.d.ts","sourceRoot":"","sources":["../../../src/components/feedback/tooltip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAI1C,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAI1E,qBACa,YAAa,SAAQ,2BAA2B;IAC/B,OAAO,SAAM;IACb,SAAS,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAS;IAEhE,OAAO,CAAC,OAAO,CAAC,CAAc;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAElD,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAsBpB;IAEF,SAAS,KAAK,YAAY,IAAI,WAAW,GAAG,IAAI,CAE/C;IAED,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAatD,iBAAiB,IAAI,IAAI;IASzB,oBAAoB,IAAI,IAAI;IAS5B,OAAO,CAAC,WAAW,CAEjB;IAEF,OAAO,CAAC,WAAW,CAEjB;IAEF,OAAO,CAAC,aAAa,CAInB;IAEF,MAAM;CAYP"}
+{"version":3,"file":"tooltip.d.ts","sourceRoot":"","sources":["../../../src/components/feedback/tooltip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAI1C,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAMrE;;;;;;;;;;;;;GAaG;AACH,qBACa,YAAa,SAAQ,2BAA2B;IAC3D,sCAAsC;IACV,OAAO,SAAM;IACzC,6FAA6F;IACjE,KAAK,SAAM;IACvC,wEAAwE;IAC5C,IAAI,SAAM;IACtC,0DAA0D;IAC9B,SAAS,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAS;IAEhE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAc;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAElD,MAAM,CAAC,QAAQ,CAAC,MAAM,0DA8BpB;IAEF,SAAS,KAAK,YAAY,IAAI,WAAW,GAAG,IAAI,CAE/C;IAED,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAatD,iBAAiB,IAAI,IAAI;IASzB,oBAAoB,IAAI,IAAI;IAS5B,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAE1B;IAEF,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAE1B;IAEF,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAI5B;IAEF,MAAM;CAmBP"}

package/dist/components/feedback/tooltip.js

@@ -0,0 +1,153 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { css, html, nothing } from 'lit';
+import { customElement, property, query } from 'lit/decorators.js';
+import { AitheAnchoredOverlayElement } from '../../core/anchored-overlay';
+import { aitheBaseStyles, aithePanelStyles } from '../../core/styles';
+import { uid } from '../../utils/utils';
+const ARIA_DESCRIBED_BY = 'aria-describedby';
+/**
+ * Tooltip overlay that appears on hover/focus over an anchor element.
+ * 工具提示浮层，在悬停/聚焦锚点元素时显示。
+ *
+ * @slot - Default slot for the anchor element. 锚点元素内容。
+ * @slot content - Custom tooltip content (overrides `content` property). 自定义工具提示内容。
+ * @fires aithe-dropdown-change - Inherited from AnchoredOverlay; emitted on open state change. 开关状态变更时触发。
+ * @example
+ * ```html
+ * <aithe-tooltip content="Help text here" placement="top">
+ *   <button>Hover me</button>
+ * </aithe-tooltip>
+ * ```
+ */
+let AitheTooltip = class AitheTooltip extends AitheAnchoredOverlayElement {
+    constructor() {
+        super(...arguments);
+        /** Tooltip text content. 工具提示文本内容。 */
+        this.content = '';
+        /** Display title for the tooltip anchor (shown as native tooltip). 工具提示锚点的显示标题（作为原生工具提示）。 */
+        this.title = '';
+        /** Icon name to display before the tooltip content. 在工具提示内容前显示的图标名称。 */
+        this.icon = '';
+        /** Tooltip placement relative to anchor. 工具提示相对于锚点的位置。 */
+        this.placement = 'top';
+        this.tooltipId = uid('aithe-tooltip');
+        /** Shows the tooltip on hover/focus. 悬停/聚焦时显示工具提示。 */
+        this.showTooltip = () => {
+            this.open = true;
+        };
+        /** Hides the tooltip on unhover/unfocus. 取消悬停/聚焦时隐藏工具提示。 */
+        this.hideTooltip = () => {
+            this.open = false;
+        };
+        /** Hides tooltip on Escape key. 按 Escape 键隐藏工具提示。 */
+        this.handleKeydown = (event) => {
+            if (event.key === 'Escape') {
+                this.open = false;
+            }
+        };
+    }
+    static { this.styles = [
+        aitheBaseStyles,
+        aithePanelStyles('.tooltip'),
+        css `
+      :host {
+        display: inline-flex;
+      }
+
+      .tooltip-icon {
+        flex-shrink: 0;
+        color: var(--aithe-color-text-muted);
+      }
+
+      .tooltip {
+        position: fixed;
+        z-index: var(--aithe-z-tooltip);
+        display: inline-flex;
+        align-items: center;
+        gap: var(--aithe-space-2);
+        max-width: min(280px, calc(100vw - 24px));
+        padding: var(--aithe-space-2) var(--aithe-space-3);
+        border-radius: var(--aithe-container-radius-md);
+        background: color-mix(in srgb, var(--aithe-color-surface-elevated) 84%, transparent);
+        color: var(--aithe-color-text);
+        font-size: var(--aithe-font-size-sm);
+        line-height: var(--aithe-line-height-base);
+        box-shadow: var(--aithe-shadow-2);
+        pointer-events: none;
+      }
+    `,
+    ]; }
+    get panelElement() {
+        return this.tooltip ?? null;
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.has('open')) {
+            const anchor = this.anchorElement;
+            if (this.open) {
+                anchor.setAttribute(ARIA_DESCRIBED_BY, this.tooltipId);
+            }
+            else if (anchor.getAttribute(ARIA_DESCRIBED_BY) === this.tooltipId) {
+                anchor.removeAttribute(ARIA_DESCRIBED_BY);
+            }
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('mouseenter', this.showTooltip);
+        this.addEventListener('mouseleave', this.hideTooltip);
+        this.addEventListener('focusin', this.showTooltip);
+        this.addEventListener('focusout', this.hideTooltip);
+        this.addEventListener('keydown', this.handleKeydown);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('mouseenter', this.showTooltip);
+        this.removeEventListener('mouseleave', this.hideTooltip);
+        this.removeEventListener('focusin', this.showTooltip);
+        this.removeEventListener('focusout', this.hideTooltip);
+        this.removeEventListener('keydown', this.handleKeydown);
+    }
+    render() {
+        const tooltipIcon = this.icon
+            ? html `
+          <aithe-icon class="tooltip-icon" name=${this.icon} size="14"></aithe-icon>
+        `
+            : nothing;
+        return html `
+      <slot></slot>
+      ${this.open
+            ? html `
+            <div id=${this.tooltipId} class="tooltip" role="tooltip">
+              ${tooltipIcon}
+              <slot name="content">${this.content}</slot>
+            </div>
+          `
+            : null}
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], AitheTooltip.prototype, "content", void 0);
+__decorate([
+    property({ type: String })
+], AitheTooltip.prototype, "title", void 0);
+__decorate([
+    property({ type: String })
+], AitheTooltip.prototype, "icon", void 0);
+__decorate([
+    property({ type: String })
+], AitheTooltip.prototype, "placement", void 0);
+__decorate([
+    query('.tooltip')
+], AitheTooltip.prototype, "tooltip", void 0);
+AitheTooltip = __decorate([
+    customElement('aithe-tooltip')
+], AitheTooltip);
+export { AitheTooltip };

package/dist/components/form/AGENTS.md

@@ -0,0 +1,43 @@
+# src/components/form/ — 表单组件（18个）
+
+## 组件列表
+
+| 组件                | 标签                     | 说明                              |
+| ------------------- | ------------------------ | --------------------------------- |
+| `autoform.ts`       | `<aithe-autoform>`       | JSON 驱动的自动表单，支持联动规则 |
+| `autoform-item.ts`  | `<aithe-autoform-item>`  | 自动表单项，三段式布局            |
+| `checkbox.ts`       | `<aithe-checkbox>`       | 复选框                            |
+| `checkbox-group.ts` | `<aithe-checkbox-group>` | 复选框组                          |
+| `radio.ts`          | `<aithe-radio>`          | 单选框                            |
+| `radio-group.ts`    | `<aithe-radio-group>`    | 单选框组                          |
+| `select.ts`         | `<aithe-select>`         | 下拉选择器，单选/多选             |
+| `switch.ts`         | `<aithe-switch>`         | 开关切换                          |
+| `color-picker.ts`   | `<aithe-color-picker>`   | 颜色选择器                        |
+| `combobox.ts`       | `<aithe-combobox>`       | 组合框，可搜索下拉带自由输入      |
+| `date-picker.ts`    | `<aithe-date-picker>`    | 日期选择器                        |
+| `time-picker.ts`    | `<aithe-time-picker>`    | 时间选择器                        |
+| `slider.ts`         | `<aithe-slider>`         | 滑块，数值范围选择                |
+| `rate.ts`           | `<aithe-rate>`           | 评分，星级评分                    |
+| `form.ts`           | `<aithe-form>`           | 表单容器，带验证                  |
+| `form-item.ts`      | `<aithe-form-item>`      | 表单项，带标签和验证              |
+| `upload.ts`         | `<aithe-upload>`         | 文件上传                          |
+| `transfer.ts`       | `<aithe-transfer>`       | 穿梭框，双列表数据转移            |
+
+## 编码规范
+
+- 继承 `AitheElement`，使用 `@customElement` 装饰器
+- 表单组件通过 `value` 属性和 `aithe-change` 事件实现双向绑定
+- 验证通过 `rules` 属性或 `form` 容器统一管理
+- 导入使用 `@components/form/xxx` 路径别名
+- 中英文双语 JSDoc 注释
+
+## 关键约定
+
+- `aithe-form` 通过 `ref` 获取表单实例，调用 `validate()` / `reset()` 方法
+- `aithe-autoform` 的 JSON Schema 定义在 `docs/autoform.md` 中详细说明
+- `aithe-autoform` 支持 `initial-values` 属性设置初始值（覆盖 `dft`），`show-submit` 控制内置提交按钮显隐，`submit()` 方法编程触发提交
+- `aithe-autoform` 操作区使用 `<aithe-button-group>` 包裹 slot 和内置提交按钮
+- `aithe-select` 开关状态变更事件名为 `aithe-dropdown-change`（替代已废弃的 `aithe-open-change`）
+- `aithe-combobox` 在原生 input 事件中调用 `event.stopPropagation()`
+- 日期/时间选择器内部依赖 `floating` 模块做面板定位
+- 新增组件需同步更新 `src/index.ts` 和 `docs/api/form/`

package/dist/components/form/autoform-item.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @file JSON-driven auto form item / JSON 驱动的自动表单项
+ * @description 单个表单项容器，固定三段式布局：顶部（图标+label+tooltip）、
+ *              中部（输入控件）、底部（description+校验错误提示）。
+ *              Single form item container with fixed three-section layout:
+ *              top (icon + label + tooltip), middle (input control),
+ *              bottom (description + validation error).
+ */
+import { nothing } from 'lit';
+import { AitheElement } from '../../core/aithe-element';
+import type { FormRule, FormItemOption } from '../../core/autoform';
+import '../display/label.js';
+/**
+ * JSON-driven auto form item with three-section layout and validation.
+ * JSON 驱动的自动表单项，三段式布局，支持校验。
+ *
+ * @slot - Default slot for the form control element. 表单控件元素内容。
+ * ### Events
+ * - **aithe-change** — Emitted when the field value changes, with `{ name, value }`. 字段值变更时触发。
+ * @example
+ * ```html
+ * <aithe-autoform-item
+ *   name="email"
+ *   type="input"
+ *   label="Email"
+ *   icon="mail"
+ *   tooltip="Your work email"
+ *   description="We will never share your email."
+ *   required
+ * ></aithe-autoform-item>
+ * ```
+ */
+export declare class AitheAutoformItem extends AitheElement {
+    /** Field unique identifier. 字段唯一标识。 */
+    name: string;
+    /** Control type: input | textarea | select | radio | checkbox | switch | number | slider | date-picker | time-picker | rate | color-picker. 控件类型。 */
+    type: AutoformItemType;
+    /** Label text. 标签文本。 */
+    label: string;
+    /** Icon name displayed before the label. 标签前显示的图标名称。 */
+    icon: string;
+    /** Tooltip text shown on hover. 悬停提示文本。 */
+    tooltip: string;
+    /** Description text below the control. 控件下方的说明文字。 */
+    description: string;
+    /** Default value. 缺省值。 */
+    dft: string;
+    /** Placeholder text. 占位提示文本。 */
+    placeholder: string;
+    /** Whether the field is disabled. 是否禁用。 */
+    disabled: boolean;
+    /** Whether the field is required. 是否必填。 */
+    required: boolean;
+    /** Validation regex pattern string. 校验正则表达式字符串。 */
+    pattern: string;
+    /** Validation failure message. 校验失败提示语。 */
+    message: string;
+    /** Options for select/radio/checkbox. 选择类控件的选项。 */
+    options: FormItemOption[];
+    /** Current field value. 当前字段值。 */
+    value: string;
+    /** Input type attribute for type="input". input 控件的 type 属性。 */
+    inputType: string;
+    /** Minimum value for number/slider. 数字/滑块最小值。 */
+    min: string;
+    /** Maximum value for number/slider. 数字/滑块最大值。 */
+    max: string;
+    /** Step value for number/slider/rate. 数字/滑块/评分步长。 */
+    step: string;
+    /** Number of rows for textarea. 文本域行数。 */
+    rows: string;
+    /** Whether to validate on every change. 是否在每次变更时实时校验。 */
+    validateOnChange: boolean;
+    /** Internal validation error message. 内部校验错误消息。 */
+    private errorMsg;
+    /** Dependency field names. 依赖字段名称列表。 */
+    dependencies: string[];
+    /** Dependency rules. 依赖联动规则。 */
+    rules: FormRule[];
+    /** Current values of dependency fields. 依赖字段的当前值。 */
+    dependencyValues: Record<string, unknown>;
+    /** Whether the field is visible (controlled by dependency rules). 字段是否可见（由依赖规则控制）。 */
+    private _visible;
+    /** Whether the field is disabled by dependency rules. 是否被依赖规则禁用。 */
+    private _ruleDisabled;
+    /** Options computed by dependency rules. 依赖规则计算的选项。 */
+    private _ruleOptions;
+    /** Whether the field is visible (controlled by dependency rules). 字段是否可见（由依赖规则控制）。 */
+    get visible(): boolean;
+    static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
+    /** Initializes value from default if empty. 初始化时若值为空则使用缺省值。 */
+    connectedCallback(): void;
+    private pendingClear;
+    /** Applies dependency rules when dependencyValues or rules change. Also emits change after a clear rule resets the value. 依赖值或规则变更时应用联动规则，clear 规则重置值后触发 change 事件。 */
+    protected updated(changed: Map<string, unknown>): void;
+    /** Evaluates all dependency rules and updates visibility, disabled state, options, and value accordingly. 评估所有依赖规则，更新可见性、禁用状态、选项和值。 */
+    private applyRules;
+    /** Validates the field and sets error state. Skips validation if hidden. 校验字段并设置错误状态，隐藏时跳过校验。 */
+    validate(): boolean;
+    /** Clears the validation error. 清除校验错误。 */
+    clearError(): void;
+    /** Returns the current validation error message. 返回当前校验错误消息。 */
+    getError(): string;
+    /** Returns the current field value. 返回当前字段值。 */
+    getFieldValue(): unknown;
+    /** Handles input/textarea/number change events. 处理 input/textarea/number 的变更事件。 */
+    private readonly handleInputChange;
+    /** Handles switch toggle change. 处理开关组件的切换事件。 */
+    private readonly handleSwitchChange;
+    /** Handles select dropdown change. 处理下拉选择器的变更事件。 */
+    private readonly handleSelectChange;
+    /** Handles radio group selection change. 处理单选框组的变更事件。 */
+    private readonly handleRadioChange;
+    /** Handles checkbox group change, serializes selected values to JSON string. 处理复选框组的变更事件，将选中值序列化为 JSON 字符串。 */
+    private readonly handleCheckboxChange;
+    /** Handles slider value change. 处理滑块组件的变更事件。 */
+    private readonly handleSliderChange;
+    /** Handles rate component value change. 处理评分组件的变更事件。 */
+    private readonly handleRateChange;
+    /** Handles color picker value change. 处理颜色选择器的变更事件。 */
+    private readonly handleColorPickerChange;
+    /** Handles date picker value change. 处理日期选择器的变更事件。 */
+    private readonly handleDatePickerChange;
+    /** Handles time picker value change. 处理时间选择器的变更事件。 */
+    private readonly handleTimePickerChange;
+    /** Handles combobox value change. 处理组合框的变更事件。 */
+    private readonly handleComboboxChange;
+    /** Renders the appropriate form control based on type. Falls back to input for unknown types. 根据控件类型渲染对应的表单控件，未知类型回退为 input。 */
+    private renderControl;
+    /** Renders radio button options for radio group. 渲染单选框组的选项。 */
+    private renderRadioOptions;
+    /** Renders checkbox options for checkbox group. 渲染复选框组的选项。 */
+    private renderCheckboxOptions;
+    /** Parses checkbox value from JSON string or array to a string array. 将复选框值从 JSON 字符串或数组解析为字符串数组。 */
+    private parseCheckboxValue;
+    render(): import("lit-html").TemplateResult<1> | typeof nothing;
+}
+/** Autoform item control type. Built-in types plus any custom registered type. 自动表单项控件类型，包含内置类型和自定义注册类型。 */
+export type AutoformItemType = 'input' | 'textarea' | 'select' | 'radio' | 'checkbox' | 'switch' | 'number' | 'slider' | 'rate' | 'color-picker' | 'date-picker' | 'time-picker' | 'combobox' | string;
+/** Autoform item option for select/radio/checkbox. 选择类控件选项。 */
+export type { FormItemOption } from '../../core/autoform';
+//# sourceMappingURL=autoform-item.d.ts.map

package/dist/components/form/autoform-item.d.ts.map

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