rj-grid 0.1.0

package/dist/types/src/formula.d.ts

@@ -0,0 +1,88 @@
+export type CellValue = number | string | boolean | null | undefined;
+export type FormulaValue = number | string | boolean;
+/** 求值上下文：列顺序 + 行数 + 取值器（0 基行列） */
+export interface FormulaCtx {
+    /** 有序列标识（colId 或 field），A/B/C 按索引映射 */
+    columns: string[];
+    /** 数据行数（用于整列/相对行的边界与 #REF! 判定） */
+    rowCount: number;
+    /** 读取原始单元格值 */
+    getValue: (col: number, row: number) => CellValue;
+}
+/** 单元格坐标（0 基） */
+export interface CellCoord {
+    col: number;
+    row: number;
+}
+/** 依赖项：某段列区间内的行范围（whole=true 表示整列跨所有行） */
+export interface FormulaDep {
+    c1: number;
+    c2: number;
+    r1: number;
+    r2: number;
+    whole: boolean;
+}
+export declare const ERR: {
+    readonly REF: "#REF!";
+    readonly VALUE: "#VALUE!";
+    readonly NAME: "#NAME?";
+    readonly DIV0: "#DIV/0!";
+    readonly NUM: "#NUM!";
+    readonly NA: "#N/A";
+    readonly CIRC: "#CIRCULAR!";
+};
+/** 是否为公式文本（以 = 开头） */
+export declare function isFormula(v: any): v is string;
+export declare function lettersToCol(s: string): number;
+export declare function colToLetters(idx: number): string;
+type NumNode = {
+    t: 'num';
+    v: number;
+};
+type StrNode = {
+    t: 'str';
+    v: string;
+};
+type BoolNode = {
+    t: 'bool';
+    v: boolean;
+};
+type RefNode = {
+    t: 'ref';
+    token: string;
+};
+type FuncNode = {
+    t: 'func';
+    name: string;
+    args: AstNode[];
+};
+type BinNode = {
+    t: 'bin';
+    op: string;
+    l: AstNode;
+    r: AstNode;
+};
+type UnNode = {
+    t: 'un';
+    op: string;
+    e: AstNode;
+};
+type PctNode = {
+    t: 'pct';
+    e: AstNode;
+};
+export type AstNode = NumNode | StrNode | BoolNode | RefNode | FuncNode | BinNode | UnNode | PctNode;
+/** 对外解析：失败返回 null */
+export declare function parse(input: string): AstNode | null;
+/** 提取依赖（供依赖图 / 循环检测使用） */
+export declare function collectDeps(ast: AstNode, ctx: FormulaCtx): FormulaDep[];
+/**
+ * 求值公式，返回结果值；错误以哨兵字符串返回（不抛出）。
+ * @param input 公式文本（可含前导 =）
+ * @param ctx   求值上下文
+ * @param at    当前单元格坐标（相对/整列引用解析用）
+ */
+export declare function evaluate(input: string, ctx: FormulaCtx, at: CellCoord): FormulaValue;
+/** 解析并求值（已编译 AST 复用场景） */
+export declare function evaluateAst(ast: AstNode, ctx: FormulaCtx, at: CellCoord): FormulaValue;
+export {};

package/dist/types/src/icons.d.ts

@@ -0,0 +1,35 @@
+import type { InjectionKey, ComputedRef } from 'vue';
+/** 内置图标名（可扩展的语义键） */
+export declare const RJ_DEFAULT_ICONS: {
+    readonly sortAscending: "▲";
+    readonly sortDescending: "▼";
+    readonly sortUnSort: "⇅";
+    readonly filter: "▼";
+    readonly columnMenu: "⋮";
+    readonly rowDrag: "⠿";
+    readonly menuGeneral: "☰";
+    readonly menuFilter: "⏷";
+    readonly menuColumns: "▤";
+    readonly checked: "✓";
+    readonly indeterminate: "–";
+    readonly rowGroupOpen: "▾";
+    readonly rowGroupClose: "▸";
+    readonly expand: "▸";
+    readonly collapse: "▾";
+    readonly pin: "📌";
+    readonly visible: "👁";
+    readonly hidden: "🚫";
+    readonly remove: "✕";
+    /** 浮层/对话框关闭按钮（与 remove 同字形，语义分开便于单独覆盖） */
+    readonly close: "✕";
+    readonly add: "+";
+    readonly submenuRight: "▸";
+};
+export type RjIconName = keyof typeof RJ_DEFAULT_ICONS;
+export type RjIcons = Record<RjIconName, string>;
+/** 用户可传入的部分覆盖 */
+export type RjIconsOverride = Partial<RjIcons>;
+/** 合并默认图标与覆盖（空串/未定义不覆盖）——纯函数 */
+export declare function mergeIcons(overrides?: RjIconsOverride): RjIcons;
+/** 注入键：网格根 provide，子组件 inject 消费 */
+export declare const RJ_ICONS_KEY: InjectionKey<ComputedRef<RjIcons>>;

package/dist/types/src/locale.d.ts

@@ -0,0 +1,21 @@
+import type { InjectionKey } from 'vue';
+export type RjMessages = Record<string, string>;
+export type RjLang = 'zh' | 'en';
+/** 中文（默认）文案目录：既是内置默认，也是英文目录缺失键的回退 */
+export declare const zhCN: RjMessages;
+/** 英文文案：以中文为底，逐键覆盖，缺失键自动回退中文 */
+export declare const enUS: RjMessages;
+export declare const RJ_PRESETS: Record<RjLang, RjMessages>;
+/** 归一语言标识：zh-CN/zh_TW/en-US/en 等 → 'zh' | 'en' */
+export declare function normalizeLang(lang?: string): RjLang;
+/** 解析最终文案表：预设底 + 局部覆盖（override 优先级最高） */
+export declare function resolveMessages(lang?: string, override?: RjMessages | null): RjMessages;
+/** 插值：把 {key} 替换为 params[key] */
+export declare function interpolate(str: string, params?: Record<string, string | number>): string;
+/** 翻译查表：命中返回并插值，未命中返回 key 本身（便于发现漏译） */
+export declare function translate(messages: RjMessages, key: string, params?: Record<string, string | number>): string;
+export type RjTranslate = (key: string, params?: Record<string, string | number>) => string;
+/** 注入键：网格根 provide 翻译函数，子组件 inject 消费 */
+export declare const RJ_LOCALE_KEY: InjectionKey<RjTranslate>;
+/** 子组件默认翻译函数（未 inject 到时回退，避免单独使用时崩溃） */
+export declare const defaultTranslate: RjTranslate;

package/dist/types/src/nlq.d.ts

@@ -0,0 +1,51 @@
+import type { RjFilterModel, RjSortState } from './types';
+export type RjNlqFilterType = 'text' | 'number' | 'date' | 'select';
+/** 参与解析的列描述（由网格从列定义构建） */
+export interface RjNlqColumn {
+    colId: string;
+    field?: string;
+    title?: string;
+    filterType: RjNlqFilterType;
+    /** 额外可识别的别名（不含 title/field） */
+    aliases?: string[];
+    /** select / 低基数列的候选值，用于把口语值映射到真实值 */
+    options?: string[];
+    /** options 来自列定义（权威枚举）：此时拒绝候选之外的口语值；数据采样的 options 不拒绝 */
+    strictOptions?: boolean;
+}
+/** 单条解析出的列筛选条件 */
+export interface RjNlqClause {
+    colId: string;
+    field?: string;
+    title?: string;
+    filterType: RjNlqFilterType;
+    op: string;
+    value1?: any;
+    value2?: any;
+    /** 与前一条件是否 OR 连接 */
+    or: boolean;
+    raw: string;
+}
+/** 解析结果 */
+export interface RjNlqResult {
+    ok: boolean;
+    /** 空查询 / 无法识别 时的说明键（交由 i18n 展示） */
+    message?: 'empty' | 'unrecognized';
+    /** 按列聚合后的筛选模型（跨列 AND，与网格既有语义一致） */
+    filters: {
+        colId: string;
+        field?: string;
+        title?: string;
+        model: RjFilterModel;
+    }[];
+    sort?: RjSortState;
+    groupBy?: string;
+    groupColId?: string;
+    limit?: number;
+    search?: string;
+    clauses: RjNlqClause[];
+}
+/** 解析自然语言查询 */
+export declare function parseNLQ(text: string, columns: RjNlqColumn[]): RjNlqResult;
+/** 生成人类可读的解析摘要（供 UI 回显，key 交由上层 i18n；此处给结构串） */
+export declare function explainNLQ(r: RjNlqResult): string;

package/dist/types/src/print.d.ts

@@ -0,0 +1,37 @@
+import type { RjPrintOptions } from './types';
+export type { RjPrintOptions };
+/** 打印列描述（叶子列） */
+export interface RjPrintColumn {
+    title: string;
+    /** 期望宽度（px）；用于 colgroup 按比例分配，缩放适配时可忽略 */
+    width?: number;
+    align?: 'left' | 'center' | 'right';
+}
+/** 多级列头单元格：colSpan 之和须等于列数 */
+export interface RjPrintHeaderCell {
+    title: string;
+    colSpan: number;
+    /** 跨行（叶子列在多级表头中占据到表头底部），默认 1 */
+    rowSpan?: number;
+}
+/** buildPrintHtml 输入：列 + 可选多级列头 + 纯数据行（不含表头） */
+export interface RjPrintInput {
+    columns: RjPrintColumn[];
+    /** 外层在前，逐层向下；缺省时用 columns.title 作单层表头 */
+    headerLevels?: RjPrintHeaderCell[][];
+    /** 仅数据行；行内元素按 columns 顺序 */
+    matrix: any[][];
+    /** 与 matrix 对齐的行样式：0 普通 / 1 分组小计 / 2 总计汇总 */
+    rowStyles?: number[];
+}
+/** 页码文案模板（内置中文兜底；实际取词由调用端经 pageNumberText 注入当前语言） */
+export declare const DEFAULT_PAGE_TEXT = "\u7B2C {p} \u9875 / \u5171 {t} \u9875";
+/** 构造打印文档 HTML（纯函数，确定性输出） */
+export declare function buildPrintHtml(input: RjPrintInput, opts?: RjPrintOptions): string;
+/**
+ * 打开隐藏 iframe 并调用浏览器打印（打印对话框可「另存为 PDF」）。
+ * 返回文档 HTML 长度仅供调用方参考；打印后自动清理 iframe。
+ */
+export declare function openPrintDialog(html: string): void;
+/** 便捷封装：构造 HTML 并立即打印 */
+export declare function printHtml(input: RjPrintInput, opts?: RjPrintOptions): void;

package/dist/types/src/query.d.ts

@@ -0,0 +1,28 @@
+import type { RjColumn, RjEditorOption, RjQueryCondition, RjQueryFieldDef, RjQueryFieldKind, RjQueryOperator } from './types';
+/** 由列类型/筛选/编辑器推导查询字段类别 */
+export declare function kindOfColumn(col: RjColumn): RjQueryFieldKind;
+/** 取列的下拉候选：editor.options（静态）或 filterValueMap（枚举映射） */
+export declare function optionsOfColumn(col: RjColumn): RjEditorOption[];
+/**
+ * 从列定义派生查询字段候选池：
+ * - 跳过无 field / 内部列 / 显式 filter:false 的列；
+ * - 用 override 覆盖标题、类别或候选（宿主可为枚举列补 options）。
+ */
+export declare function deriveQueryFields(columns: RjColumn[], override?: RjQueryFieldDef[]): RjQueryFieldDef[];
+/** 各类别对应的合理运算符集合 */
+export declare function queryOpsOfKind(kind: RjQueryFieldKind): RjQueryOperator[];
+/** 新增字段时的默认运算符（取该类别最常用的一项） */
+export declare function defaultQueryOperator(kind: RjQueryFieldKind): RjQueryOperator;
+/** 条件是否已填值（刚挂字段还没输入的不参与过滤） */
+export declare function queryHasValue(c: RjQueryCondition): boolean;
+/** 生效（已填值）的条件集合 */
+export declare function activeQueryConditions(list: RjQueryCondition[]): RjQueryCondition[];
+/**
+ * 单元格原始值与单个条件比对（纯函数：调用方负责取值）。
+ * 日期类走时间戳、数值类走 Number、其余走字符串宽松比较。
+ */
+export declare function matchQueryValue(rawValue: any, c: RjQueryCondition, kind?: RjQueryFieldKind): boolean;
+/** 行是否通过全部生效条件（AND）；colOf 提供该列定义以决定取值口径与类别 */
+export declare function rowPassesQuery(row: RjRowDataLike, conds: RjQueryCondition[], colOf: (field: string) => RjColumn | undefined): boolean;
+type RjRowDataLike = Record<string, any>;
+export {};

package/dist/types/src/rowForm.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 内置行编辑弹窗的纯逻辑：表单字段推导 + 批量写入 + 按钮禁用求值。
+ * 不依赖 DOM / Vue，单测直接驱动（__tests__/rowForm.spec.ts）。
+ */
+import type { RjColumn, RjEditorConfig, RjEditorOption, RjQueryAction, RjRowData, RjRowFormConfig } from './types';
+/** 表单控件类型（由列的 editor/type 归一而来） */
+export type RjFormFieldKind = 'text' | 'number' | 'date' | 'select' | 'textarea' | 'checkbox';
+/** 单个表单字段：弹窗按此渲染，validator/col 原样带上供提交校验 */
+export interface RjFormField {
+    field: string;
+    colId: string;
+    title: string;
+    kind: RjFormFieldKind;
+    options: RjEditorOption[];
+    /** textarea 行数 */
+    rows: number;
+    validator?: RjEditorConfig['validator'];
+    col: RjColumn;
+}
+/** 列上的 editor 声明归一为配置对象（editor 可为裸类型字符串） */
+export declare function normalizeEditor(col: RjColumn): RjEditorConfig | undefined;
+/** 控件类型：editor.type 优先，否则由列预设 type 映射；custom 无法进表单，回落文本 */
+export declare function formFieldKind(col: RjColumn, editor?: RjEditorConfig): RjFormFieldKind;
+/** 由可见叶子列生成表单字段（sampleRows 用于对函数形式的 editor.options 求值） */
+export declare function buildFormFields(cols: RjColumn[], cfg: RjRowFormConfig | undefined, sampleRows: RjRowData[]): RjFormField[];
+/**
+ * 把 { field: value } 批量写入每一行（原地改，配合 applyTransaction({ update }) 使用）。
+ * changes 只含弹窗里勾选过的字段，未勾选字段天然不覆盖。
+ */
+export declare function applyFormChanges(rows: RjRowData[], changes: Record<string, any>): RjRowData[];
+/**
+ * 新增弹窗提交：由 preset 浅拷 + 表单值组装新行对象（不改动 preset 本身）。
+ * 主键/默认值等由宿主在 row-form-add 里补齐后调后端，组件只负责形状。
+ */
+export declare function createFormRow(preset: RjRowData | undefined, changes: Record<string, any>): RjRowData;
+/** 读某行在某字段上的当前值（表单预填用，走 a.b.c 路径） */
+export declare function fieldValue(row: RjRowData, field: string): any;
+/** 查询栏按钮禁用求值：布尔直通，函数按选中行判定 */
+export declare function queryActionDisabled(action: RjQueryAction, rows: RjRowData[]): boolean;
+/** 查询栏按钮确认文案求值（无 confirm 返回空串） */
+export declare function queryActionConfirm(action: RjQueryAction, rows: RjRowData[]): string;

package/dist/types/src/serverGroups.d.ts

@@ -0,0 +1,52 @@
+import type { RjRowData } from './types';
+import type { RjDisplayRow } from './useRowModel';
+/** 某组的懒取子项状态（由行模型持有，避免在纯函数里发请求） */
+export interface SgChildState {
+    /** 已取回的子项平铺序列（空数组 = 后端确认无子行；与「取数失败」不同一状态） */
+    kids?: RjRowData[];
+    /** 正在取 */
+    loading?: boolean;
+    /** 本代取数连续失败到上限：不再渲染子行、也不再登记请求（重取数/改分组/清缓存后自然恢复） */
+    error?: boolean;
+}
+/** 组元信息（按 path 索引，供子块取数参数复用，免去反解 path） */
+export interface SgGroupMeta {
+    level: number;
+    /** 该层级的分组字段 */
+    field: string;
+    /** 从根到本组的组值路径 */
+    values: any[];
+}
+/** 待取子块的组 */
+export interface SgNeedLoad extends SgGroupMeta {
+    path: string;
+}
+export interface SgFlattenOptions {
+    /** 分组字段，按层级顺序（与后端 __level 对应） */
+    fields: string[];
+    /** 行主键 */
+    keyOf: (row: RjRowData) => string | number;
+    rowHeight: number;
+    /** 被收起的组 path（默认全部展开，与后端已内联返回子行的观感一致） */
+    collapsed?: Set<string>;
+    /** path → 懒取子项状态 */
+    childMap?: Map<string, SgChildState>;
+    /** 宿主判定某组行是否可展开（对应 isServerSideGroup）；缺省时按「有子行就可展开」推断 */
+    isExpandable?: (row: RjRowData) => boolean;
+}
+export interface SgFlattenResult {
+    rows: RjDisplayRow[];
+    /** 需要发起 type:'group' 子块请求的组（调用方去重后取数，回填 childMap） */
+    needLoad: SgNeedLoad[];
+    /** 本次出现过的全部组（path → 元信息） */
+    metas: Map<string, SgGroupMeta>;
+    /** 与 rows 等长：显示下标 → 输入序列绝对下标（-1 = 非输入序列行，如懒取子行/组占位） */
+    absAt: number[];
+}
+/**
+ * 补齐组行契约字段（__path/__level/__groupField/__groupValue/__groupLabels）。
+ * 后端给全就原样返回；缺则浅拷贝补齐，不修改源对象。
+ */
+export declare function decorateGroupRow(row: RjRowData, path: string, level: number, field: string, value: any, labels: any[]): RjRowData;
+/** 平铺（可含未加载空洞）→ 显示行序列 + 待取子块 + 下标映射 */
+export declare function flattenServerGroups(items: (RjRowData | undefined)[], opts: SgFlattenOptions): SgFlattenResult;

package/dist/types/src/ssrm.d.ts

@@ -0,0 +1,102 @@
+import type { RjRowData, RjTransaction } from './types';
+/** 块加载状态（仅描述进行中的请求，已加载由覆盖度派生） */
+export interface SsrmInflight {
+    seq: number;
+    status: 'loading' | 'error';
+}
+export interface SsrmStoreOptions {
+    /** 每块行数 */
+    blockSize: number;
+    /** 缓存中最多保留的已加载块数（0/undefined = 不限）；超出按 LRU 淘汰 */
+    maxBlocksInCache?: number;
+    /** 视口外额外保留块数 */
+    cacheOverflow?: number;
+    /** 取行主键 */
+    keyOf: (row: RjRowData) => string | number;
+}
+export interface SsrmDeltaResult {
+    /** 受影响的绝对行下标（供局部重绘） */
+    changed: number[];
+    /** 需要闪烁高亮的 key */
+    flash: (string | number)[];
+    /** 结构是否发生变化（add/remove 导致行位移） */
+    structural: boolean;
+}
+export declare class SsrmStore {
+    /** 服务端总行数；-1 表示未知（尚未收到 total） */
+    rowCount: number;
+    readonly blockSize: number;
+    readonly maxBlocksInCache: number;
+    readonly cacheOverflow: number;
+    private readonly keyOf;
+    /** dense 行槽：长度 = max(rowCount,0)；undefined 表示未加载 */
+    slots: (RjRowData | undefined)[];
+    /** 每个块的进行中标记（loading / error 重试） */
+    private inflight;
+    /** 每块的最近访问时间（LRU），仅在覆盖完整时有效 */
+    private touch;
+    private clock;
+    private seq;
+    constructor(opts: SsrmStoreOptions);
+    blockIndexOf(row: number): number;
+    startRowOf(blockIndex: number): number;
+    /** 块实际结束行（不含）；末块受 rowCount 截断 */
+    endRowOf(blockIndex: number): number;
+    blockCount(): number;
+    /** 该块行区间是否被完全填充（= 已加载） */
+    isBlockLoaded(blockIndex: number): boolean;
+    /** 设定/更新总数并调整 slots 长度，保留已加载内容 */
+    configure(total: number): void;
+    reset(): void;
+    rowAt(i: number): RjRowData | undefined;
+    loadedRowCount(): number;
+    /**
+     * 规划需要请求的块：覆盖 [first-prefetch, last+prefetch] 且未加载、非进行中的块，
+     * 按「距视口中心由近及远」排序（优先补最可见处）。
+     */
+    planLoad(first: number, last: number, prefetch?: number): number[];
+    /** 标记块开始加载，返回本次请求的 seq（用于竞态守卫） */
+    beginLoad(blockIndex: number): number;
+    /** 提交块数据：seq 过期则丢弃；写入 slots；返回是否被应用 */
+    commitLoad(blockIndex: number, seq: number, rows: RjRowData[]): boolean;
+    /** 标记块加载失败（可重试） */
+    failLoad(blockIndex: number, seq: number): void;
+    isLoadingAny(): boolean;
+    /** 指定块是否正在加载中（用于 boot 块去重） */
+    isBlockBusy(blockIndex: number): boolean;
+    /**
+     * 依据保留集合淘汰「已加载且不在 keep 内」的块，按 LRU（touch 时钟）优先淘汰最久未用。
+     * 进行中的块永不淘汰。返回被淘汰的块索引。
+     */
+    prune(keep: Set<number>): number[];
+    /** keep 集合：视口块 ± cacheOverflow */
+    keepSet(first: number, last: number): Set<number>;
+    /**
+     * 对已加载内容应用增量：
+     * - update：按 key 原地替换已加载行（不位移），闪烁；
+     * - upsert：命中已加载则更新，否则忽略（服务端权威，避免破坏块区间）；
+     * - add：追加到末尾（rowCount++），闪烁；
+     * - remove：按 key 从已加载槽移除并左移尾块（structural）。
+     */
+    applyDelta(tx: RjTransaction): SsrmDeltaResult;
+}
+/**
+ * 把多次事务在「一次刷新」内合并后统一应用，降低高频推送的重排/重绘成本。
+ * 合并规则：remove 的 key 覆盖之前对同 key 的 add/update；后到的 update 覆盖先到的。
+ */
+export type SsrmTxApplier = (tx: RjTransaction) => void;
+export declare class SsrmTxBatcher {
+    private queue;
+    private scheduled;
+    private apply;
+    private defer;
+    constructor(apply: SsrmTxApplier, opts?: {
+        defer?: (fn: () => void) => void;
+    });
+    push(tx: RjTransaction): void;
+    /** 立即合并并应用队列（返回合并后的事务，便于测试/回调） */
+    flush(): RjTransaction;
+    get pending(): number;
+}
+/** 合并多笔事务为一笔：同 key 后者胜；remove 压制 add/update */
+export declare function mergeTransactions(list: RjTransaction[]): RjTransaction;

package/dist/types/src/theme.d.ts

@@ -0,0 +1,33 @@
+export interface RjThemeParams {
+    /** 预设风格：legacy=沿用内置默认；其余为 AG Grid 风格预设 */
+    preset?: 'legacy' | 'alpine' | 'quartz' | 'material';
+    /** 明暗模式：auto 由组件按系统偏好解析后传入具体值 */
+    mode?: 'light' | 'dark' | 'auto';
+    /** 主强调色（选中/悬停/焦点等派生色的基准） */
+    accentColor?: string;
+    /** 单元格/主体背景 */
+    backgroundColor?: string;
+    /** 斑马纹奇/偶行背景 */
+    oddRowBackgroundColor?: string;
+    /** 表头背景 */
+    headerBackgroundColor?: string;
+    /** 边框色 */
+    borderColor?: string;
+    /** 主文本色 */
+    foregroundColor?: string;
+    /** 次要文本色 */
+    secondaryForegroundColor?: string;
+    /** 字号 */
+    fontSize?: number | string;
+    /** 圆角 */
+    radius?: number | string;
+    /** 直接覆盖任意 --rj-* 变量（逃生舱） */
+    vars?: Record<string, string>;
+}
+/**
+ * 把主题参数编译为 CSS 变量集合（仅包含需要覆盖的键，未设置的键沿用 scss 默认）。
+ * 纯函数：无 DOM / 无时间戳 / 无随机，确定性可单测/快照。
+ */
+export declare function buildThemeVars(params?: RjThemeParams): Record<string, string>;
+/** 解析 auto → light/dark（组件侧调用，注入 matchMedia 判定结果） */
+export declare function resolveMode(mode: RjThemeParams['mode'], prefersDark: boolean): 'light' | 'dark';