knight-ui 1.1.5 → 1.1.7

package/component/navigation/Navigation.d.ts

@@ -1,5 +1,6 @@
 import React from "react";
 import { AbstractUI, type UIProps, type UIState } from "../../base";
+import { type LayoutSiderContextValue } from "../basic/Layout";
 export interface NavItem {
     key: string;
     label: string;
@@ -12,7 +13,26 @@ type TriggerMode = "hover" | "click";
  * 导航菜单。
  */
 export declare class Navigation extends AbstractUI<NavigationProps, NavigationState> {
+    /** 放进 Layout.Sider 时自动跟着折叠 —— 折叠钮只改 Sider 自己的 state, 子组件靠这个 context 才看得见。 */
+    static contextType: React.Context<LayoutSiderContextValue>;
+    context: LayoutSiderContextValue | null;
     constructor(props: NavigationProps);
+    /** 上一次更新时的折叠态。null 只在 componentDidMount 之前成立(那时不可能有更新)。 */
+    private _lastCollapsed;
+    componentDidMount(): void;
+    /** 折叠态三级: 显式 isCollapsed > 所在 Sider 的折叠态 > 自己的 defaultIsCollapsed。 */
+    private isCollapsed;
+    /**
+     * 折叠态**翻转那一帧**要做的两件事: 通知外部, 以及把展开的子菜单收起来。
+     *
+     * 判断"那一刻"要知道上一次的折叠态, 而折叠态可能来自 context —— context 不在 prevProps 里, 所以自己记一笔
+     * (基线在 componentDidMount 落地)。注意"折叠态"在 Sider 里是**延迟版**的: 侧栏宽度先走完, context 才翻,
+     * 所以这两件事都落在"图标出现"那一帧上, 而不是点下去就凭空发生。
+     *
+     * 为什么收起子菜单: 折叠态下子项本来就画不出来(iconOnly 会把内联子项整段拿掉), 但 openKeys 还留着 ——
+     * 再展开侧栏时子菜单会**自己弹回来**。用户按了折叠, 期望的是"收起来", 而不是"暂时看不见"。
+     */
+    private syncCollapseState;
     componentDidUpdate(prevProps: Readonly<NavigationProps>): void;
     protected OnRenderContent(): React.ReactElement;
     private renderItem;
@@ -24,19 +44,39 @@ export declare class Navigation extends AbstractUI<NavigationProps, NavigationSt
     private select;
 }
 export interface NavigationProps extends UIProps {
+    /** 菜单数据。**key 在一份菜单里必须唯一**(选中/展开/回调都用它)。折叠后每行只剩图标, 所以每一项都该配
+        icon —— 没有图标的那一行在折叠态就是**一行空白**(描边和 hover 气泡还在, 但看起来像坏了)。
+        子菜单写在 NavItem.children 里: 竖排逐级内联(每级多缩进 16px), 横排的浮层只画一层。 */
     items?: NavItem[];
+    /** 竖排(默认): 子菜单**内联**在下方, 点父项展开; 横排: 子菜单是浮层, 由 trigger 决定怎么开。
+        折叠只对竖排有意义 —— 横排没有"收成图标"这回事, 传了 isCollapsed 也不会把标签收掉。 */
     mode?: "horizontal" | "vertical";
+    /** 折叠态(收成只显示图标)。不传时读所在 Layout.Sider 的折叠态, 再退到 defaultIsCollapsed。 */
     isCollapsed?: boolean;
+    /** 非受控初始值。放进 Sider 时以 Sider 的折叠态为准, 它只是独立使用时的起点。 */
     defaultIsCollapsed?: boolean;
+    /**
+     * 折叠态变化回调 —— 不管这一下是谁改的(传进来的 isCollapsed / 所在 Sider 的折叠钮 / 自己的默认值)。
+     * 要"用户点下按钮那一刻"就用 Layout.Sider 的 onCollapseChange; 这个是"菜单内容真的换成图标形态了"
+     * 那一刻(在 Sider 里比按钮晚一个过渡时长)。挂载时不发。
+     */
     onCollapseChange?: (isCollapsed: boolean) => void;
-    /** 水平模式子菜单触发方式，默认 "hover" */
+    /** 横排子菜单的触发方式, 默认 "hover"(鼠标移入就开)。竖排不看它 —— 竖排一律点击展开。 */
     trigger?: TriggerMode;
+    /** 受控: 当前展开的子菜单 key。传了它菜单就不自己改内部 state, 只发 onOpenChange, 由调用方回写。
+        **要传新数组**(内部按引用比较, 原地 push 不会同步)。折叠那一刻会发一次 [] —— 受控方要照着自己置空。 */
     openKeys?: string[];
+    /** 非受控初始展开项。只在挂载时读一次(受控的 openKeys 优先)。 */
     defaultOpenKeys?: string[];
+    /** 受控: 当前选中项。单选时点谁换谁; multiple 时叠加/取消。传新数组的理由同 openKeys。 */
     selectedKeys?: string[];
+    /** 非受控初始选中项。只在挂载时读一次(受控的 selectedKeys 优先)。 */
     defaultSelectedKeys?: string[];
+    /** 多选: 再点已选中项就取消, 选中项可以有好几个。默认单选 —— 点谁谁亮, 与已有选中项无关。 */
     multiple?: boolean;
+    /** 选中回调。受控/非受控都会发(受控方靠它拿新值回写), 点已选中项也会发一次。 */
     onSelect?: (key: string) => void;
+    /** 展开集合变化回调: 点父项开/关, 以及折叠那一刻被清空(收到 [])。叶子项永远不发。 */
     onOpenChange?: (openKeys: string[]) => void;
 }
 interface NavigationState extends UIState {

package/component/plus/Chat.d.ts

@@ -49,6 +49,9 @@ export interface ChatProps extends UIProps {
     onRetry?: (msg: ChatMessage, index: number) => void;
     loading?: boolean;
     emptyContent?: React.ReactNode;
+    /** 面板底色。缺省走 .ku-chat-surface(暗 #131620 / 亮 #f5f6f8, 即灰阶第 1 档), 与 AIChatDialogue /
+        AIChatInput 同一档。 */
+    backgroundColor?: string;
     showInput?: boolean;
     placeholder?: string;
     sendText?: string;

package/component/plus/CodeEditor.d.ts

@@ -26,7 +26,7 @@ export declare class CodeEditor extends AbstractUI<CodeEditorProps, CodeEditorSt
     getEditor(): any;
     /** Monaco 挂载回调 */
     private OnEditorMount;
-    /** 挂载前配置 Monaco 环境，稳定诊断/IntelliSense */
+    /** 挂载前配置 Monaco 环境: 先登记代码面主题, 再稳定诊断/IntelliSense */
     private beforeMount;
     /** 切换语言 — 更新内部状态 + 回调 + 直接操作 Monaco 模型 */
     private handleLanguageChange;
@@ -57,8 +57,9 @@ export interface CodeEditorProps extends UIProps {
     width?: number | string;
     /** 编辑器最小宽度(px) */
     minWidth?: number;
-    /** Monaco 主题 @default "vs-dark" —— 代码面按 VS Code 自己的暗色一套, **不随本库明暗主题变化** */
-    theme?: "vs-dark" | "light" | "hc-black";
+    /** Monaco 主题 @default "ku-code" —— `vs-dark` 原样继承, 只把底换成灰阶第 1 档 #131620(见
+        tokens/codeTheme.ts)。**不随本库明暗主题变化**: 两个主题下代码面都是这一块深底。 */
+    theme?: "ku-code" | "vs-dark" | "light" | "hc-black";
     /** 只读 @default false */
     readOnly?: boolean;
     /** 显示缩略图 @default false */

package/component/plus/CodeHighlight.d.ts

@@ -21,8 +21,9 @@ export declare class CodeHighlight extends AbstractUI<CodeHighlightProps, CodeHi
 export interface CodeHighlightProps extends UIProps {
     code?: string;
     language?: string;
-    /** Monaco 主题 @default "vs-dark" —— 代码面按 VS Code 自己的暗色一套, **不随本库明暗主题变化** */
-    theme?: "vs-dark" | "light" | "hc-black";
+    /** Monaco 主题 @default "ku-code" —— `vs-dark` 原样继承, 只把底换成灰阶第 1 档 #131620(见
+        tokens/codeTheme.ts)。**不随本库明暗主题变化**: 两个主题下代码面都是这一块深底。 */
+    theme?: "ku-code" | "vs-dark" | "light" | "hc-black";
     showLineNumbers?: boolean;
     height?: number | string;
     maxHeight?: number | string;

package/component/plus/JsonViewer.d.ts

@@ -26,8 +26,9 @@ export interface JsonViewerProps extends UIProps {
     readOnly?: boolean;
     onChange?: (value: string) => void;
     height?: number;
-    /** Monaco 主题 @default "vs-dark" —— 代码面按 VS Code 自己的暗色一套, **不随本库明暗主题变化** */
-    theme?: "vs-dark" | "light";
+    /** Monaco 主题 @default "ku-code" —— `vs-dark` 原样继承, 只把底换成灰阶第 1 档 #131620(见
+        tokens/codeTheme.ts)。**不随本库明暗主题变化**: 两个主题下代码面都是这一块深底。 */
+    theme?: "ku-code" | "vs-dark" | "light";
 }
 interface JsonViewerState extends UIState {
     lastExternalValue: string;

package/component/tokens/codeTheme.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 代码面的 Monaco 主题 —— 只改一件事: 把 `vs-dark` 的底(#1e1e1e)换成本库灰阶第 1 档 #131620,
+ * 其余**全部继承 vs-dark**(`inherit: true` + 空 rules)。
+ *
+ * 为什么只改底: 语法配色是一整套(几十个槽位), 换任何一个都得重新标定一遍; 而代码面与页面脱节
+ * 的地方只有"底"这一处 —— #1e1e1e 是中性深灰, 页面是带蓝的深灰, 两块并排就是两种黑。底对上之后,
+ * 剩下的中性灰面(建议列表 / 悬停气泡 / 缩略图)面积小, 且都要用户主动触发才出现, 不在第一眼里。
+ *
+ * **底色是固定的 #131620, 不跟 `--ku-grey-1` 随主题翻转。** 亮色的 grey-1 是 #f5f6f8(近白),
+ * 而 vs-dark 的语法色(#9cdcfe / #dcdcaa / #ce9178…)是给深底配的浅色 —— 铺在近白底上会大面积糊掉。
+ * 所以代码面在**两个主题下都是这一块深底**, 与「代码面不随主题变化」是同一条取向(见 README「代码面」
+ * 一节)。也正因为如此这里必须写死字面量: Monaco 的 colors 只吃 #RRGGBB, CSS 变量在这里无效 ——
+ * 和它 options 里 fontSize 只吃数字是同一类限制。
+ */
+export declare const KU_CODE_THEME = "ku-code";
+/**
+ * 注册代码面主题。
+ *
+ * **必须在 `beforeMount` 里调用**: @monaco-editor/react 的顺序是 beforeMount → editor.create →
+ * setTheme, 赶在 create 之前登记, 那个名字才已经存在。
+ *
+ * 每次挂载都重新 define、不加"只注册一次"的模块开关: defineTheme 只是登记一份定义(不应用),
+ * 开销可忽略; 而开关一旦因为 Monaco 实例被重建或重新加载而失真, 表现是"主题悄悄不生效",
+ * 比多登记一次难查得多。
+ */
+export declare function ensureKuCodeTheme(monaco: any): void;

package/component/tokens/index.d.ts

@@ -14,8 +14,9 @@
  * `rgb` / `hex` / `valueToHex` / `contentStep` / `contentColor` / `contentHex`。它们服务的两个
  * 消费者现在都不存在了 ——
  *   ① 内容色板不需要读色: 字符串拼装就够了(这正是 contentVar 存在的理由);
- *   ② Monaco 那一版已整体撤掉: 代码面现在完全用 VS 自带的 `vs-dark`, 不注册自定义主题,
- *      于是 `valueToHex`(为"只吃 #RRGGBB 的注册表"而写)也一并没了用处。
+ *   ② Monaco 那一版已整体撤掉, 代码面现在用 VS 自带的 `vs-dark`, 只换底(见 ./codeTheme.ts)。
+ *      它是**写死一个字面量**进 Monaco 的注册表, 不需要把 CSS 值读出来 —— 所以
+ *      `valueToHex`(为"读了再转 #RRGGBB"而写)依然没有用处。
  * 所以按"整族剪"处理, 一个不留 —— 养一批无人调用的导出, 比真要用时重写它们(~70 行:
  * `getComputedStyle` + 展开嵌套 `var()` + 十六进制转换)贵得多。
  *