knight-ui 1.0.0

package/base/AbstractComponent.d.ts

@@ -0,0 +1,29 @@
+import React from "react";
+/**
+ * AbstractComponentPro — 新一代抽象组件基类.
+ * 仅提供 rootRef + cx() 工具，不覆写任何 React 生命周期。
+ * 与旧 AbstractComponent 保持独立，Flow 逐步迁移后合并。
+ */
+export declare abstract class AbstractComponent<P extends ComponentProps = ComponentProps, S extends ComponentState = ComponentState> extends React.Component<P, S> {
+    /** 根 DOM 引用 */
+    protected rootRef: React.RefObject<HTMLDivElement>;
+    /** 空实现 — 承接子类 super.componentDidMount() 调用 */
+    componentDidMount(): void;
+    /** 空实现 — 承接子类 super.componentDidUpdate() 调用 */
+    componentDidUpdate(_prevProps: Readonly<P>, _prevState: Readonly<S>, _snapshot?: any): void;
+    /** 空实现 — 承接子类 super.componentWillUnmount() 调用 */
+    componentWillUnmount(): void;
+    /** 合并 CSS 类名，过滤空值 */
+    cx(...classes: (string | false | null | undefined)[]): string;
+}
+/** 组件属性 */
+export interface ComponentProps {
+    /** 组件ID */
+    id?: string;
+}
+/** 组件状态 */
+export interface ComponentState {
+}
+/** 组件数据 */
+export interface ComponentData {
+}

package/base/AbstractUI.d.ts

@@ -0,0 +1,45 @@
+import React from "react";
+import { AbstractComponent, ComponentProps, ComponentState } from "./AbstractComponent";
+/**
+ * AbstractUIPro — 新 UI 组件基类.
+ * 核心改进: 基类 render() 统一渲染外层容器(style/className/disabled),
+ * 子类只需实现 OnRenderContent() 返回内部内容.
+ * 子组件的 Props 继承 UIProps 即自动获得所有通用属性.
+ */
+export declare abstract class AbstractUI<P extends UIProps = UIProps, S extends UIState = UIState> extends AbstractComponent<P, S> {
+    constructor(props: P);
+    componentDidUpdate(prevProps: Readonly<P>, _prevState: Readonly<S>, _snapshot?: any): void;
+    /** 渲染内部内容 — 子类返回自身 DOM 结构(不含外层容器) */
+    protected abstract OnRenderContent(): React.ReactElement;
+    /** 设置激活/聚焦状态 — 仅需要聚焦态的组件覆写 */
+    protected OnSetActive(active: boolean): void;
+    /** 受控/非受控统一取值 */
+    protected OnGetControlledValue<T>(defaultValue: T, value?: T): T;
+    /** CSS 类名合并(全称别名,委托给继承的 cx()) */
+    protected classNames(...classes: (string | false | null | undefined)[]): string;
+    /** 获取根元素通用属性 — 子类在 OnRenderContent() 的根元素上展开使用, 用于绑定 rootRef + data-disabled */
+    protected OnGetRootProps(): {
+        ref: React.RefObject<any>;
+        "data-disabled": string | undefined;
+    };
+    /** 获取禁用样式 */
+    protected OnGetDisabledStyle(): React.CSSProperties;
+    render(): React.ReactNode;
+}
+/** UI 组件通用属性 — 子组件 Props 继承此接口 */
+export interface UIProps extends ComponentProps {
+    /** 原生 CSS 所有属性(含 width/height/margin/padding/flex/grid 等) */
+    style?: React.CSSProperties;
+    /** CSS 类名(追加到根元素) */
+    className?: string;
+    /** 是否可见 */
+    visible?: boolean;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 子内容 */
+    children?: React.ReactNode;
+}
+/** UI 组件通用状态 */
+export interface UIState extends ComponentState {
+    visible: boolean;
+}

package/base/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./AbstractComponent";
+export * from "./AbstractUI";

package/component/_internal/BodyScrollLock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * BodyScrollLock — body 滚动锁定(引用计数).
+ * 多个浮层同时打开时只有第一个加锁、最后一个解锁.
+ */
+export declare class BodyScrollLock {
+    private static count;
+    /** 锁定 body 滚动(引用计数+1) */
+    static lock(): void;
+    /** 解锁 body 滚动(引用计数-1,归零才真正解锁) */
+    static unlock(): void;
+    /** 是否已锁定 */
+    static get isLocked(): boolean;
+}

package/component/_internal/ClickOutside.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ClickOutside — 点击外部检测.
+ * 用于下拉面板/Popover/Select 等浮层组件的外部点击关闭.
+ *
+ * 用法:
+ *   const listener = ClickOutside.on(element, () => this.close());
+ *   // 组件卸载时:
+ *   ClickOutside.off(listener);
+ */
+export declare class ClickOutside {
+    /**
+     * 注册点击外部监听.
+     * @param el       监听的 DOM 元素(点击此元素外部时触发回调)
+     * @param callback 回调函数
+     * @param useCapture 是否在捕获阶段处理(默认 true,防止事件被阻止冒泡)
+     * @returns 返回监听器引用,用于 off() 注销
+     */
+    static on(el: HTMLElement, callback: () => void, useCapture?: boolean): (e: MouseEvent) => void;
+    /** 注销点击外部监听 */
+    static off(handler: (e: MouseEvent) => void, useCapture?: boolean): void;
+}

package/component/_internal/Mask.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+/**
+ * Mask — 遮罩层组件.
+ * 用于 Modal/SideSheet/Drawer 等浮层的背景遮罩.
+ */
+export declare class Mask {
+    /**
+     * 渲染遮罩层.
+     * @param zIndex  层级
+     * @param opacity 透明度(0-1),浮层组件根据动画状态传入
+     * @param onClick 点击遮罩回调
+     * @param duration 过渡时长(ms)
+     */
+    static render(zIndex: number, opacity: number, onClick?: () => void, duration?: number): React.ReactElement;
+}

package/component/_internal/OverlayZIndex.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OverlayZIndex — 浮层 z-index 栈管理.
+ * 每创建一个浮层实例递增,保证嵌套浮层层叠顺序正确.
+ */
+export declare class OverlayZIndex {
+    private static current;
+    /** 获取下一个可用 z-index */
+    static next(): number;
+    /** 释放一个 z-index(浮层关闭时调用) */
+    static release(): void;
+    /** 获取当前最大 z-index */
+    static peak(): number;
+}

package/component/_internal/Portal.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+/**
+ * Portal — createPortal 封装.
+ * 将子节点渲染到指定 DOM 容器,默认为 document.body.
+ */
+export declare class Portal {
+    /** 渲染子节点到目标容器 */
+    static render(children: React.ReactNode, container?: HTMLElement): React.ReactPortal;
+}

package/component/_internal/index.d.ts

@@ -0,0 +1,5 @@
+export { Portal } from "./Portal";
+export { Mask } from "./Mask";
+export { OverlayZIndex } from "./OverlayZIndex";
+export { BodyScrollLock } from "./BodyScrollLock";
+export { ClickOutside } from "./ClickOutside";

package/component/_tokens/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 编程式 Token 访问 — 读取 :root 上定义的 --ku-* CSS 变量.
+ * 主要用于组件内需要动态计算样式值时通过 JS 获取 token 值.
+ */
+export declare const Tokens: {
+    primary: () => string;
+    primaryHover: () => string;
+    primaryActive: () => string;
+    primaryDisabled: () => string;
+    primaryLightDefault: () => string;
+    primaryLightHover: () => string;
+    primaryLightActive: () => string;
+    success: () => string;
+    warning: () => string;
+    danger: () => string;
+    info: () => string;
+    bgDeepest: () => string;
+    bgPanel: () => string;
+    bgElevated: () => string;
+    bgHover: () => string;
+    bgBorder: () => string;
+    textPrimary: () => string;
+    textSecondary: () => string;
+    textPlaceholder: () => string;
+    textDisabled: () => string;
+    fontSize: (key: "xs" | "sm" | "base" | "md" | "lg") => string;
+    radius: (key: "xs" | "sm" | "base" | "md" | "lg" | "xl") => string;
+    spacing: (key: "xs" | "sm" | "base" | "md" | "lg" | "xl") => string;
+    zMask: () => number;
+    zOverlay: () => number;
+    zModal: () => number;
+    zToast: () => number;
+};

package/component/_types/base.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 共享类型定义。
+ */
+/** 组件尺寸 */
+export type ComponentSize = "small" | "default" | "large";
+/** 校验状态(仅改变视觉,不阻止输入) */
+export type ValidateStatus = "default" | "warning" | "error" | "success";
+/** 通用回调 — 值优先(value-first)模式 */
+export type OnChangeCallback<T = any> = (value: T, event?: React.SyntheticEvent) => void;
+/** 组件方向 */
+export type Direction = "ltr" | "rtl";
+/** 弹出层触发方式 */
+export type OverlayTrigger = "click" | "hover" | "focus" | "contextMenu" | "custom";
+/** 弹出层位置 */
+export type OverlayPosition = "top" | "topLeft" | "topRight" | "bottom" | "bottomLeft" | "bottomRight" | "left" | "leftTop" | "leftBottom" | "right" | "rightTop" | "rightBottom";
+/** 按钮变体 */
+export type ButtonVariant = "primary" | "secondary" | "tertiary" | "warning" | "danger";
+/** 按钮主题(亮/暗) */
+export type ButtonTheme = "light" | "solid" | "borderless";

package/component/_types/index.d.ts

@@ -0,0 +1 @@
+export * from "./base";

package/component/ai/AIChatDialogue.d.ts

@@ -0,0 +1,44 @@
+import React from "react";
+import { AbstractUI, type UIProps, type UIState } from "../../base";
+type AIRole = "user" | "assistant";
+export interface AIMessage {
+    id?: string | number;
+    role: AIRole;
+    content: React.ReactNode;
+    avatar?: string;
+    name?: string;
+    time?: string;
+    status?: "pending" | "streaming" | "done" | "error";
+}
+/**
+ * AI 对话展示。
+ */
+export declare class AIChatDialogue extends AbstractUI<AIChatDialogueProps, UIState> {
+    private listRef;
+    private listEl;
+    constructor(props: AIChatDialogueProps);
+    componentDidMount(): void;
+    componentWillUnmount(): void;
+    componentDidUpdate(prevProps: Readonly<AIChatDialogueProps>): void;
+    private onListWheel;
+    private setListRef;
+    private scrollToBottom;
+    private renderAvatar;
+    private renderActionBtn;
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface AIChatDialogueProps extends UIProps {
+    dataSource?: AIMessage[];
+    typing?: boolean;
+    userAvatar?: string;
+    assistantAvatar?: string;
+    userNickname?: string;
+    assistantNickname?: string;
+    showAvatar?: boolean;
+    showNickname?: boolean;
+    maxHeight?: number;
+    emptyContent?: React.ReactNode;
+    onCopy?: (msg: AIMessage) => void;
+    onRetry?: (msg: AIMessage, index: number) => void;
+}
+export {};

package/component/ai/AIChatInput.d.ts

@@ -0,0 +1,45 @@
+import React from "react";
+import { AbstractUI, type UIProps, type UIState } from "../../base";
+export interface Attachment {
+    id?: string;
+    name: string;
+    size?: number;
+    type?: string;
+    url?: string;
+}
+/**
+ * AI 聊天输入框。
+ */
+export declare class AIChatInput extends AbstractUI<AIChatInputProps, AIChatInputState> {
+    private textareaRef;
+    constructor(props: AIChatInputProps);
+    componentDidUpdate(prevProps: Readonly<AIChatInputProps>, prevState: Readonly<AIChatInputState>): void;
+    componentDidMount(): void;
+    componentWillUnmount(): void;
+    private onTextareaWheel;
+    private autoResize;
+    private handleSend;
+    private handleKeyDown;
+    private handleChange;
+    private handleRemoveAttachment;
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface AIChatInputProps extends UIProps {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    onSend?: (value: string, attachments: Attachment[]) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    loading?: boolean;
+    attachments?: Attachment[];
+    /** 最小行数 @default 1 */
+    minRows?: number;
+    /** 最大行数,超出后滚动 @default 4 */
+    maxRows?: number;
+}
+interface AIChatInputState extends UIState {
+    value: string;
+    attachments: Attachment[];
+}
+export {};

package/component/ai/Sidebar.d.ts

@@ -0,0 +1,38 @@
+import React from "react";
+import { AbstractUI, type UIProps, type UIState } from "../../base";
+interface SidebarItem {
+    key: string;
+    label: React.ReactNode;
+    icon?: React.ReactNode;
+    children?: SidebarItem[];
+    disabled?: boolean;
+}
+/**
+ * AI 侧边栏。
+ */
+export declare class Sidebar extends AbstractUI<SidebarProps, SidebarState> {
+    constructor(props: SidebarProps);
+    componentDidUpdate(prevProps: Readonly<SidebarProps>): void;
+    private handleItemClick;
+    private toggleExpand;
+    private findItem;
+    private renderItems;
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface SidebarProps extends UIProps {
+    items?: SidebarItem[];
+    activeKey?: string;
+    defaultActiveKey?: string;
+    defaultExpandedKeys?: string[];
+    collapsed?: boolean;
+    width?: number;
+    collapsedWidth?: number;
+    header?: React.ReactNode;
+    footer?: React.ReactNode;
+    onChange?: (key: string) => void;
+}
+interface SidebarState extends UIState {
+    activeKey: string;
+    expandedKeys: string[];
+}
+export {};

package/component/ai/index.d.ts

@@ -0,0 +1,6 @@
+export { AIChatInput } from "./AIChatInput";
+export type { AIChatInputProps, Attachment } from "./AIChatInput";
+export { AIChatDialogue } from "./AIChatDialogue";
+export type { AIChatDialogueProps, AIMessage } from "./AIChatDialogue";
+export { Sidebar } from "./Sidebar";
+export type { SidebarProps } from "./Sidebar";

package/component/basic/Button.d.ts

@@ -0,0 +1,36 @@
+import React from "react";
+import { AbstractUI, type UIProps, type UIState } from "../../base";
+import type { ComponentSize, ButtonVariant, ButtonTheme } from "../_types";
+declare class ButtonGroup extends AbstractUI<ButtonGroupProps, UIState> {
+    static displayName: string;
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface ButtonGroupProps extends UIProps {
+}
+/**
+ * 按钮。
+ */
+export declare class Button extends AbstractUI<ButtonProps, UIState> {
+    static Group: typeof ButtonGroup;
+    /** 按钮聚焦 */
+    focus(): void;
+    /** 按钮失焦 */
+    blur(): void;
+    protected OnRenderContent(): React.ReactElement;
+    private getFontSize;
+    private getPadding;
+    private getColorStyle;
+}
+export interface ButtonProps extends UIProps {
+    type?: ButtonVariant;
+    theme?: ButtonTheme;
+    size?: ComponentSize;
+    shape?: "circle" | "round";
+    icon?: React.ReactNode;
+    iconPosition?: "left" | "right";
+    loading?: boolean;
+    block?: boolean;
+    htmlType?: "button" | "submit" | "reset";
+    onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+}
+export {};

package/component/basic/Divider.d.ts

@@ -0,0 +1,28 @@
+import React from "react";
+import { AbstractUI, type UIProps, type UIState } from "../../base";
+/**
+ * 分割线。
+ * 支持水平/垂直布局、虚线、带文字对齐.
+ *
+ * 用法:
+ *   <Divider />
+ *   <Divider layout="vertical" />
+ *   <Divider dashed>分割文字</Divider>
+ *   <Divider align="left">左侧文字</Divider>
+ */
+export declare class Divider extends AbstractUI<DividerProps, UIState> {
+    protected OnRenderContent(): React.ReactElement;
+    private normalizeMargin;
+}
+export interface DividerProps extends UIProps {
+    /** 布局方向 */
+    layout?: "horizontal" | "vertical";
+    /** 是否虚线 */
+    dashed?: boolean;
+    /** 带文字时的对齐方式 */
+    align?: "left" | "center" | "right";
+    /** 外边距(快捷属性), 支持 number(px) 或 string */
+    margin?: string | number;
+    /** 分割线颜色 */
+    color?: string;
+}

package/component/basic/FloatButton.d.ts

@@ -0,0 +1,53 @@
+import React from "react";
+import { AbstractUI, type UIProps, type UIState } from "../../base";
+/**
+ * 悬浮按钮组。Group API.
+ * 多个 FloatButton 垂直或水平排列.
+ */
+declare class FloatButtonGroup extends AbstractUI<FloatButtonGroupProps, FloatButtonGroupState> {
+    static displayName: string;
+    constructor(props: FloatButtonGroupProps);
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface FloatButtonGroupProps extends UIProps {
+    /** 触发按钮图标 */
+    icon?: React.ReactNode;
+    /** 位置 */
+    position?: {
+        right?: number;
+        bottom?: number;
+        left?: number;
+        top?: number;
+    };
+    /** 尺寸 */
+    size?: number;
+    /** 展开方向 */
+    direction?: "vertical" | "horizontal";
+}
+interface FloatButtonGroupState extends UIState {
+    open: boolean;
+}
+/**
+ * 悬浮操作按钮。
+ * 固定在页面右下角,支持组合 FloatButton.Group.
+ */
+export declare class FloatButton extends AbstractUI<FloatButtonProps, UIState> {
+    static Group: typeof FloatButtonGroup;
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface FloatButtonProps extends UIProps {
+    /** 图标 */
+    icon?: React.ReactNode;
+    /** 点击回调 */
+    onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+    /** 位置 */
+    position?: {
+        right?: number;
+        bottom?: number;
+        left?: number;
+        top?: number;
+    };
+    /** 尺寸 */
+    size?: number;
+}
+export {};

package/component/basic/Grid.d.ts

@@ -0,0 +1,41 @@
+import React from "react";
+import { AbstractUI, type UIProps, type UIState } from "../../base";
+/**
+ * 栅格行。Row API.
+ * 支持 gutter(间距)、justify(水平对齐)、align(垂直对齐).
+ */
+export declare class Row extends AbstractUI<RowProps, UIState> {
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface RowProps extends UIProps {
+    /** 列间距(px 或 [水平, 垂直]) */
+    gutter?: number | [number, number];
+    /** 水平对齐: start | end | center | space-around | space-between */
+    justify?: "start" | "end" | "center" | "space-around" | "space-between";
+    /** 垂直对齐: top | middle | bottom */
+    align?: "top" | "middle" | "bottom";
+    /** 是否自动换行 */
+    wrap?: boolean;
+}
+/**
+ * 栅格列。Col API.
+ * 24 栅格系统,支持 span/offset/order.
+ */
+export declare class Col extends AbstractUI<ColProps, UIState> {
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface ColProps extends UIProps {
+    /** 列占据的栅格数(1-24,默认 24) */
+    span?: number;
+    /** 左侧偏移栅格数 */
+    offset?: number;
+    /** 排序 */
+    order?: number;
+    /** 响应式配置(xs < 576px, sm >= 576px, md >= 768px, lg >= 992px, xl >= 1200px, xxl >= 1600px) */
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    xxl?: number;
+}

package/component/basic/Icon.d.ts

@@ -0,0 +1,30 @@
+import React from "react";
+import { AbstractUI, type UIProps, type UIState } from "../../base";
+import { ICON_PATHS as GENERATED_PATHS } from "./icon-paths.generated";
+/** Backward-compatible aliases for old short names → generated camelCase names */
+declare const ALIASES: Record<string, string>;
+/**
+ * Icon 组件 — 基于 SVG path 数据渲染。
+ * 所有图标使用面型 fill 渲染, 通过 fillRule=evenodd 实现镂空轮廓效果.
+ * Solid 风格 (info/warning/danger/success) 使用 mask 镂空.
+ */
+export declare class Icon extends AbstractUI<IconProps, UIState> {
+    private static _maskIdCounter;
+    private _maskId;
+    private getMaskId;
+    protected OnRenderContent(): React.ReactElement;
+    private renderSvg;
+    private renderFallback;
+    private getSize;
+}
+export type IconSize = "extraSmall" | "small" | "default" | "large" | "extraLarge";
+export type IconType = keyof typeof GENERATED_PATHS | keyof typeof ALIASES;
+export interface IconProps extends UIProps {
+    type?: IconType;
+    size?: IconSize;
+    color?: string;
+    spin?: boolean;
+    rotate?: number;
+    onClick?: (e: React.MouseEvent) => void;
+}
+export {};

package/component/basic/Layout.d.ts

@@ -0,0 +1,43 @@
+import React from "react";
+import { AbstractUI, type UIProps, type UIState } from "../../base";
+declare class LayoutHeader extends AbstractUI<UIProps, UIState> {
+    static displayName: string;
+    protected OnRenderContent(): React.ReactElement;
+}
+declare class LayoutSider extends AbstractUI<LayoutSiderProps, LayoutSiderState> {
+    static displayName: string;
+    constructor(props: LayoutSiderProps);
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface LayoutSiderProps extends UIProps {
+    width?: number;
+    collapsedWidth?: number;
+    defaultCollapsed?: boolean;
+    trigger?: boolean;
+}
+interface LayoutSiderState extends UIState {
+    collapsed: boolean;
+}
+declare class LayoutContent extends AbstractUI<UIProps, UIState> {
+    static displayName: string;
+    protected OnRenderContent(): React.ReactElement;
+}
+declare class LayoutFooter extends AbstractUI<UIProps, UIState> {
+    static displayName: string;
+    protected OnRenderContent(): React.ReactElement;
+}
+/**
+ * 布局容器 — 复合组件: Layout + Layout.Header/Sider/Content/Footer.
+ *
+ */
+export declare class Layout extends AbstractUI<LayoutProps, UIState> {
+    static Header: typeof LayoutHeader;
+    static Sider: typeof LayoutSider;
+    static Content: typeof LayoutContent;
+    static Footer: typeof LayoutFooter;
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface LayoutProps extends UIProps {
+    hasSider?: boolean;
+}
+export {};