@wc-kit/core 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -16,14 +16,20 @@ export declare const arrowLeft: WcIconData;
 /** 向右箭头 */
 export declare const arrowRight: WcIconData;
 
+/** 回到顶部（顶部横线 + 上箭头，vertical-align-top 风格） */
+export declare const arrowUp: WcIconData;
+
 /**
  * 组件共享基础样式，每个组件的 static styles 中首先引入。
  */
 export declare const baseStyles: CSSResult;
 
-/** 全部内置图标，供 registerBuiltinIcons 批量注册 */
+/** 手挑内置图标（组件内部依赖 + 高频图标；与 Feather 全集重名时以这些为准） */
 export declare const builtinIcons: WcIconData[];
 
+/** 全部内置图标 = 手挑优先版 + Feather 全集其余，供 registerBuiltinIcons 批量注册 */
+export declare const builtinIconsWithFeather: WcIconData[];
+
 /** 日历（日期选择器用） */
 export declare const calendar: WcIconData;
 
@@ -225,7 +231,7 @@ declare const PRESET_SIZES: Record<string, string>;
 declare const PRESET_SIZES_2: Record<string, string>;
 
 /**
- * 批量注册全部内置图标（22 个）。
+ * 批量注册全部内置图标（手挑 23 个 + Feather 其余 268 个 = 291 个）。
  * 应用入口调用一次即可；也可以从各图标文件单独 import + registerIcon 按需注册。
  */
 export declare function registerBuiltinIcons(): void;
@@ -396,18 +402,23 @@ export declare class wcBreadcrumbItem extends LitElement {
  * 按钮
  *
  * @slot - 按钮内容
- * @slot icon - 图标（位置由 iconPosition 控制）
+ * @slot icon - 图标（位置由 iconPosition 控制；loading 时被 spinner 替换）
  * @csspart base - 按钮根元素
  * @csspart icon - 图标容器
  * @csspart content - 文案容器
  * @cssprop --wc-button-height - 按钮高度
+ * @cssprop --wc-button-ghost-hover-bg - ghost 模式悬停淡底色
+ * @cssprop --wc-button-ripple-color - 波纹颜色（默认 currentColor 45% 透明度）
+ * @cssprop --wc-button-ripple-duration - 波纹扩散时长（默认 600ms）
  */
 export declare class wcButton extends LitElement {
     static styles: CSSResult[];
     /** 组件风格（语义色） */
     theme: wcButtonTheme;
-    /** 按钮形式 */
-    variant: wcButtonVariant;
+    /** 按钮类型（形式） */
+    type: wcButtonType;
+    /** 原生按钮行为：submit / reset 仅在 wc-form 内触发提交 / 重置 */
+    htmlType: 'button' | 'submit' | 'reset';
     /** 尺寸 */
     size: wcButtonSize;
     /** 图标位置：start 左 / end 右 */
@@ -418,7 +429,14 @@ export declare class wcButton extends LitElement {
     disabled: boolean;
     /** 加载状态 */
     loading: boolean;
+    /** 幽灵模式：透明底 + 主题色边框/文字（用于深色背景；outline/dashed 悬停改为半透明淡底） */
+    ghost: boolean;
+    /** 渐变底：实色按钮改为主题色线性渐变（仅 base 变体且非 default 主题生效） */
+    gradient: boolean;
+    /** 点击波纹效果 */
+    ripple: boolean;
     private handleClick;
+    private _spawnRipple;
     /** 是否有图标（icon 插槽检测） */
     private _hasIcon;
     /** 是否有文案（默认插槽检测），两者决定纯图标方形态 */
@@ -441,6 +459,7 @@ export declare class wcButton extends LitElement {
 export declare class wcButtonGroup extends LitElement {
     static styles: CSSResult[];
     render(): TemplateResult<1>;
+    private _syncMargins;
 }
 
 export declare type wcButtonIconPosition = 'start' | 'end';
@@ -449,7 +468,7 @@ export declare type wcButtonSize = 'small' | 'medium' | 'large';
 
 export declare type wcButtonTheme = 'default' | 'primary' | 'success' | 'warning' | 'danger';
 
-export declare type wcButtonVariant = 'base' | 'outline' | 'dashed' | 'text' | 'link';
+export declare type wcButtonType = 'base' | 'outline' | 'dashed' | 'text' | 'link';
 
 /**
  * 卡片。header 区由 title / subtitle 属性或 header 插槽组成，actions 插槽
@@ -474,6 +493,7 @@ export declare type wcButtonVariant = 'base' | 'outline' | 'dashed' | 'text' | '
  * @csspart actions - 头部操作区
  * @csspart body - 内容区
  * @csspart footer - 底部
+ * @cssprop --wc-card-radius - 卡片圆角（默认 --wc-radius-medium）
  */
 export declare class wcCard extends LitElement {
     static styles: CSSResult[];
@@ -754,6 +774,84 @@ declare type wcDrawerCloseReason = 'close-btn' | 'overlay' | 'escape' | 'confirm
 
 declare type wcDrawerPlacement = 'left' | 'right' | 'top' | 'bottom';
 
+/**
+ * 下拉菜单：点击触发元素弹出菜单面板（fixed 定位，空间不足自动翻转）。
+ * 触发元素放 `slot="trigger"`，菜单项用 `wc-dropdown-item` 作为默认子元素；
+ * 支持键盘导航（↑↓ 移动高亮、Enter 选中、Esc 关闭）与点击外部关闭。
+ *
+ * @slot trigger - 触发元素
+ * @slot - 菜单项（wc-dropdown-item）
+ * @csspart trigger - 触发区
+ * @csspart base - 菜单面板
+ * @fires wc-open - 菜单展开
+ * @fires wc-close - 菜单关闭，detail.reason: 'outside' | 'escape' | 'select' | 'toggle'
+ * @fires wc-select - 选中菜单项，detail.value / detail.label（之后自动关闭）
+ * @cssprop --wc-dropdown-min-width - 面板最小宽度（默认 120px）
+ * @cssprop --wc-dropdown-max-height - 面板最大高度（默认 280px）
+ */
+export declare class wcDropdown extends LitElement {
+    static styles: CSSResult[];
+    /** 期望弹出方向（空间不足自动翻转） */
+    placement: WcPlacement;
+    /** 当前是否打开 */
+    open: boolean;
+    /** 禁用（触发器不响应点击/键盘） */
+    disabled: boolean;
+    private panelId;
+    private itemUid;
+    private activeIndex;
+    private assignedItems;
+    constructor();
+    disconnectedCallback(): void;
+    connectedCallback(): void;
+    /** 面板中的可用菜单项列表 */
+    private get enabledItems();
+    /** 打开菜单 */
+    show(): void;
+    /** 关闭菜单（不派发事件） */
+    hide(): void;
+    /** 切换开合 */
+    toggle(): void;
+    private emitClose;
+    private onDocumentClick;
+    private bindSideEffects;
+    private unbindSideEffects;
+    protected updated(changed: Map<string, unknown>): void;
+    /** 计算并应用 fixed 定位（同 Popconfirm，无箭头） */
+    private position;
+    private onSlotChange;
+    private syncActive;
+    private onPanelClick;
+    private selectItem;
+    private onTriggerClick;
+    private handleKeydown;
+    render(): TemplateResult<1>;
+}
+
+/**
+ * 下拉菜单项，必须作为 wc-dropdown 的子元素使用。
+ * `divider` 属性渲染为分隔线（忽略内容与 danger/disabled）。
+ *
+ * @slot - 菜单项文本
+ * @csspart base - 菜单项根元素
+ */
+export declare class wcDropdownItem extends LitElement {
+    static styles: CSSResult[];
+    /** 菜单项值（随 wc-select 事件的 detail.value 抛出） */
+    value: string;
+    /** 禁用 */
+    disabled: boolean;
+    /** 危险操作（红色文字） */
+    danger: boolean;
+    /** 渲染为分隔线 */
+    divider: boolean;
+    /** 键盘导航高亮态（由 wc-dropdown 管理） */
+    active: boolean;
+    /** 菜单项文本 */
+    get label(): string;
+    render(): TemplateResult<1>;
+}
+
 /**
  * 空状态。默认展示占位图形 + 「暂无数据」文案，均可用插槽自定义，
  * 另有 action 插槽放置操作按钮（如重试）。
@@ -779,6 +877,149 @@ export declare class wcEmpty extends LitElement {
     protected render(): TemplateResult;
 }
 
+/**
+ * 悬浮按钮：固定在视口角落的圆形/方形操作按钮（形态对齐 antd FloatButton）。
+ * 有 href 渲染链接，dot/count 渲染右上角徽标，tooltip 悬浮显示气泡；
+ * backtop 为「回到顶部」预设——滚动超过 visibility-height 才显示，点击滚回顶部。
+ * 组合用法见 wc-float-button-group。
+ *
+ * @example
+ * ```html
+ * <wc-float-button icon="plus" tooltip="新增"></wc-float-button>
+ * <wc-float-button backtop></wc-float-button>
+ * ```
+ *
+ * @slot icon - 图标（覆盖 icon 属性）
+ * @slot - 文字描述（覆盖 description 属性）
+ * @csspart base - 按钮本体
+ * @csspart badge - 徽标
+ * @cssprop --wc-float-button-bottom - 距视口底部距离（默认 24px）
+ * @cssprop --wc-float-button-right - 距视口右侧距离（默认 24px）
+ * @cssprop --wc-float-button-size - 按钮尺寸（默认 40px）
+ */
+export declare class wcFloatButton extends LitElement {
+    static styles: CSSResult[];
+    /** 形状 */
+    shape: wcFloatButtonShape;
+    /** 类型：default 白底 / primary 主题色底 */
+    type: wcFloatButtonType;
+    /** 图标名称（内置图标库） */
+    icon: string;
+    /** 文字描述（square 形状下显示在图标下方） */
+    description: string;
+    /** 悬浮提示内容（backtop 时缺省为「回到顶部」） */
+    tooltip: string;
+    /** 链接地址（有值渲染 <a>，否则渲染 <button>） */
+    href: string;
+    /** 链接打开方式（仅 href 存在时生效） */
+    target: string;
+    /** 禁用 */
+    disabled: boolean;
+    /** 右上角红点（忽略 count，恒显示） */
+    dot: boolean;
+    /** 右上角徽标数字（<= 0 隐藏） */
+    count: number;
+    /** 徽标数字上限，超出显示「max+」 */
+    max: number;
+    /** 回到顶部预设 */
+    backtop: boolean;
+    /** 回到顶部：滚动超过该距离（px）才显示 */
+    visibilityHeight: number;
+    private localize;
+    private tipId;
+    /** icon/description 插槽是否有内容（空容器会撑出 flex gap 偏移，需隐藏） */
+    private _hasIcon;
+    private _hasText;
+    private onIconSlotChange;
+    private onTextSlotChange;
+    private showTimer;
+    private hideTimer;
+    private onScroll;
+    private onDocumentClick;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    private bindBacktop;
+    private unbindBacktop;
+    private tooltipIsOpen;
+    /** 实际展示的提示文本（backtop 缺省取 i18n 文案） */
+    private get effectiveTooltip();
+    private showTip;
+    private hideTip;
+    /** 气泡 fixed 定位于按钮左侧，垂直居中（空间不足贴边时夹近视口） */
+    private positionTip;
+    private bindOutsideClose;
+    private unbindOutsideClose;
+    private clearTimers;
+    private onClick;
+    /** 实际展示的徽标文本 */
+    private get displayCount();
+    render(): TemplateResult;
+}
+
+/**
+ * 悬浮按钮组：子元素 `wc-float-button` 垂直堆叠于宿主上方（形态对齐
+ * antd FloatButton.Group，但按钮间用间距分离）。trigger="click"/"hover"
+ * 时变为 speed-dial：收起只显示触发按钮（plus 展开时旋转成 ×），点击/悬浮展开。
+ * group 的 shape 会同步给未显式设置 shape 的子按钮。
+ *
+ * @example
+ * ```html
+ * <wc-float-button-group trigger="click">
+ *   <wc-float-button icon="plus" tooltip="新增"></wc-float-button>
+ *   <wc-float-button icon="search" tooltip="搜索"></wc-float-button>
+ * </wc-float-button-group>
+ * ```
+ *
+ * @slot - 子按钮（wc-float-button）
+ * @csspart trigger - 触发按钮（仅 trigger 模式）
+ * @csspart items - 子按钮容器
+ * @cssprop --wc-float-button-bottom - 距视口底部距离（默认 24px）
+ * @cssprop --wc-float-button-right - 距视口右侧距离（默认 24px）
+ * @cssprop --wc-float-button-gap - 按钮间距（默认 8px）
+ * @fires wc-open - 展开
+ * @fires wc-close - 收起，detail.reason: 'outside' | 'escape' | 'toggle'
+ */
+export declare class wcFloatButtonGroup extends LitElement {
+    static styles: CSSResult[];
+    /** 形状（同步给未显式设置 shape 的子按钮与触发按钮） */
+    shape: wcFloatButtonShape;
+    /** 触发方式：空 = 子按钮常显堆叠 */
+    trigger: wcFloatButtonGroupTrigger;
+    /** 当前是否展开（仅 trigger 模式生效） */
+    open: boolean;
+    /** 触发按钮图标（默认 plus） */
+    icon: string;
+    private localize;
+    constructor();
+    disconnectedCallback(): void;
+    connectedCallback(): void;
+    /** 展开（仅 trigger 模式） */
+    show(): void;
+    /** 收起（不派发事件） */
+    hide(): void;
+    /** 切换开合 */
+    toggle(): void;
+    private emitClose;
+    private onDocumentClick;
+    private bindOutsideClose;
+    private unbindOutsideClose;
+    private handleKeydown;
+    private onTriggerClick;
+    private onHostMouseenter;
+    private onHostMouseleave;
+    private onSlotChange;
+    private syncShapes;
+    protected updated(changed: Map<string, unknown>): void;
+    render(): TemplateResult;
+}
+
+export declare type wcFloatButtonGroupTrigger = '' | 'click' | 'hover';
+
+export declare type wcFloatButtonShape = 'circle' | 'square';
+
+export declare type wcFloatButtonType = 'default' | 'primary';
+
 /**
  * 表单容器：拦截提交做整体校验，聚合校验结果。
  *
@@ -788,10 +1029,10 @@ export declare class wcEmpty extends LitElement {
  *   <wc-form-item label="用户名" name="username" required>
  *     <wc-input></wc-input>
  *   </wc-form-item>
- *   <wc-button theme="primary" type="submit">提交</wc-button>
+ *   <wc-button theme="primary" html-type="submit">提交</wc-button>
  * </wc-form>
  * ```
- * 点击 `wc-button[type=submit]` / `wc-button[type=reset]` 会触发提交流程 /
+ * 点击 `wc-button[html-type=submit]` / `wc-button[html-type=reset]` 会触发提交流程 /
  * 重置（事件委托，按钮可以是任意层级后代）。
  *
  * @slot - 放置 wc-form-item 与按钮
@@ -813,7 +1054,7 @@ export declare class wcForm extends LitElement {
     /** 触发提交流程（等同点击 submit 按钮） */
     submit(): Promise<void>;
     private onSubmit;
-    /** 委托处理 wc-button[type=submit|reset]（控件在各自 shadow 内，需用 composedPath） */
+    /** 委托处理 wc-button[html-type=submit|reset]（控件在各自 shadow 内，需用 composedPath） */
     private onHostClick;
     private focusFirstError;
     render(): TemplateResult<1>;
@@ -1157,6 +1398,7 @@ declare type wcInputStatus = 'default' | 'success' | 'warning' | 'error';
  * @slot empty - 空状态（默认渲染 wc-empty）
  * @csspart base - 列表容器
  * @csspart empty - 空状态区
+ * @cssprop --wc-list-radius - 列表圆角（默认 --wc-radius-medium）
  */
 export declare class wcList extends LitElement {
     static styles: CSSResult[];
@@ -1612,6 +1854,57 @@ declare type wcSpaceAlign = 'start' | 'center' | 'end' | 'baseline';
 
 declare type wcSpaceDirection = 'horizontal' | 'vertical';
 
+/**
+ * 组合按钮：主操作按钮 + 下拉箭头（形态对齐 antd Dropdown.Button）。
+ * 左侧主按钮派发 `wc-main-click`，右侧箭头派发 `wc-arrow-click` 并展开
+ * 内置下拉菜单。菜单项用 `wc-dropdown-item` 作为默认子元素传入。
+ *
+ * @slot - 主按钮文案
+ * @slot -（wc-dropdown-item 菜单项，自动进入下拉面板）
+ * @csspart base - 组合容器
+ * @cssprop --wc-split-button-radius - 两端保留的圆角
+ * @fires wc-main-click - 点击主按钮
+ * @fires wc-arrow-click - 点击下拉箭头（菜单随之开合）
+ */
+export declare class wcSplitButton extends LitElement {
+    static styles: CSSResult[];
+    /** 按钮风格（透传两枚按钮） */
+    theme: wcSplitButtonTheme;
+    /** 按钮类型（透传两枚按钮） */
+    type: wcSplitButtonType;
+    /** 尺寸（透传两枚按钮） */
+    size: wcSplitButtonSize;
+    /** 下拉弹出方向 */
+    placement: WcPlacement;
+    /** 禁用（透传两枚按钮与下拉） */
+    disabled: boolean;
+    /** 加载中（透传两枚按钮） */
+    loading: boolean;
+    /** 幽灵模式（透传两枚按钮） */
+    ghost: boolean;
+    /** 渐变底（透传两枚按钮） */
+    gradient: boolean;
+    /** 点击波纹（透传两枚按钮） */
+    ripple: boolean;
+    private localize;
+    private observer;
+    private get dropdown();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private syncItemSlots;
+    /** 主按钮点击：拦截原生冒泡，改派 wc-main-click */
+    private onMainClick;
+    /** 箭头点击：拦截原生冒泡（避免污染业务层），手动开合下拉并派发 wc-arrow-click */
+    private onArrowClick;
+    render(): TemplateResult<1>;
+}
+
+export declare type wcSplitButtonSize = 'small' | 'medium' | 'large';
+
+export declare type wcSplitButtonTheme = 'default' | 'primary' | 'success' | 'warning' | 'danger';
+
+export declare type wcSplitButtonType = 'base' | 'outline' | 'dashed' | 'text' | 'link';
+
 /**
  * 开关
  *
@@ -1787,7 +2080,7 @@ export declare class wcTag extends LitElement {
     /** 尺寸 */
     size: wcTagSize;
     /** 填充风格：dark 实底 / light 浅底 / outline 描边 */
-    variant: wcTagVariant;
+    type: wcTagType;
     /** 可关闭 */
     closable: boolean;
     /** 禁用 */
@@ -1801,7 +2094,7 @@ declare type wcTagSize = 'small' | 'medium' | 'large';
 
 declare type wcTagTheme = 'default' | 'primary' | 'success' | 'warning' | 'danger';
 
-declare type wcTagVariant = 'dark' | 'light' | 'outline';
+declare type wcTagType = 'dark' | 'light' | 'outline';
 
 /**
  * 排版文本。text 为正文；heading 按 level（1~6）渲染对应语义与字号，
@@ -1812,12 +2105,12 @@ declare type wcTagVariant = 'dark' | 'light' | 'outline';
  */
 export declare class wcText extends LitElement {
     static styles: CSSResult[];
-    /** 变体：正文 / 标题 */
-    variant: wcTextVariant;
+    /** 类型：正文 / 标题 */
+    type: wcTextType;
     /** 标题级别（仅 heading 生效，1~6，默认 3） */
     level: number;
     /** 语义色 */
-    type: wcTextType;
+    theme: wcTextTheme;
     /** 禁用态（灰字 + not-allowed） */
     disabled: boolean;
     private get headingLevel();
@@ -1868,9 +2161,9 @@ declare const wcTextarea_base: typeof LitElement & (new (...args: any[]) => Form
 
 declare type wcTextareaStatus = 'default' | 'success' | 'warning' | 'error';
 
-declare type wcTextType = 'default' | 'secondary' | 'success' | 'warning' | 'danger';
+declare type wcTextTheme = 'default' | 'secondary' | 'success' | 'warning' | 'danger';
 
-declare type wcTextVariant = 'text' | 'heading';
+declare type wcTextType = 'text' | 'heading';
 
 /**
  * 主题切换控制：通过 documentElement 上的 data-theme 属性驱动 tokens.css