@vavt/react-ui 1.0.0

package/dist/types/Checkbox/type.d.cts

@@ -0,0 +1,55 @@
+import type { HTMLAttributes, InputHTMLAttributes, ReactNode } from 'react';
+/** 多选框尺寸：小 (sm) | 中等 (md) | 大 (lg) */
+export type CheckboxSize = 'sm' | 'md' | 'lg';
+/** 多选框选项绑定的值类型 */
+export type CheckboxValue = string | number | boolean;
+/** Checkbox 根原生 input DOM 元素类型 */
+export type CheckboxRef = HTMLInputElement;
+/** CheckboxGroup 根 DOM 容器元素类型 */
+export type CheckboxGroupRef = HTMLDivElement;
+/**
+ * Checkbox 单体组件属性接口
+ */
+export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'defaultValue' | 'checked' | 'defaultChecked' | 'onChange'> {
+    /** 受控模式：当前是否选中 */
+    checked?: boolean;
+    /** 非受控模式：初始是否选中，默认为 false */
+    defaultChecked?: boolean;
+    /** 多选框绑定的值（在 CheckboxGroup 中使用时必填） */
+    value?: CheckboxValue;
+    /** 多选框文本标签（也可通过 children 传入） */
+    label?: ReactNode;
+    /** 是否禁用交互，默认为 false */
+    disabled?: boolean;
+    /** 是否使用带边框的卡片形态，默认为 false */
+    bordered?: boolean;
+    /** 是否呈现半选不确定状态，默认为 false */
+    indeterminate?: boolean;
+    /** 原生表单 name 字段 */
+    name?: string;
+    /** 控件尺寸，默认为 `md` */
+    size?: CheckboxSize;
+    /** 选中状态发生变化时的回调函数 */
+    onChange?: (value: CheckboxValue | undefined, checked: boolean) => void;
+}
+/**
+ * CheckboxGroup 多选框组属性接口
+ */
+export interface CheckboxGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange'> {
+    /** 受控模式：当前选中的值数组 */
+    value?: CheckboxValue[];
+    /** 非受控模式：初始选中的值数组 */
+    defaultValue?: CheckboxValue[];
+    /** 是否禁用整组所有多选框，默认为 false */
+    disabled?: boolean;
+    /** 整组是否采用带边框卡片样式，默认为 false */
+    bordered?: boolean;
+    /** 整组下属多选框统一的原生表单 name 字段 */
+    name?: string;
+    /** 整组统一尺寸大小，默认为 `md` */
+    size?: CheckboxSize;
+    /** 子节点列表（通常为一组 Checkbox） */
+    children?: ReactNode;
+    /** 选中值数组发生变化时的回调函数 */
+    onChange?: (value: CheckboxValue[]) => void;
+}

package/dist/types/Checkbox/type.d.ts

@@ -0,0 +1,55 @@
+import type { HTMLAttributes, InputHTMLAttributes, ReactNode } from 'react';
+/** 多选框尺寸：小 (sm) | 中等 (md) | 大 (lg) */
+export type CheckboxSize = 'sm' | 'md' | 'lg';
+/** 多选框选项绑定的值类型 */
+export type CheckboxValue = string | number | boolean;
+/** Checkbox 根原生 input DOM 元素类型 */
+export type CheckboxRef = HTMLInputElement;
+/** CheckboxGroup 根 DOM 容器元素类型 */
+export type CheckboxGroupRef = HTMLDivElement;
+/**
+ * Checkbox 单体组件属性接口
+ */
+export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'defaultValue' | 'checked' | 'defaultChecked' | 'onChange'> {
+    /** 受控模式：当前是否选中 */
+    checked?: boolean;
+    /** 非受控模式：初始是否选中，默认为 false */
+    defaultChecked?: boolean;
+    /** 多选框绑定的值（在 CheckboxGroup 中使用时必填） */
+    value?: CheckboxValue;
+    /** 多选框文本标签（也可通过 children 传入） */
+    label?: ReactNode;
+    /** 是否禁用交互，默认为 false */
+    disabled?: boolean;
+    /** 是否使用带边框的卡片形态，默认为 false */
+    bordered?: boolean;
+    /** 是否呈现半选不确定状态，默认为 false */
+    indeterminate?: boolean;
+    /** 原生表单 name 字段 */
+    name?: string;
+    /** 控件尺寸，默认为 `md` */
+    size?: CheckboxSize;
+    /** 选中状态发生变化时的回调函数 */
+    onChange?: (value: CheckboxValue | undefined, checked: boolean) => void;
+}
+/**
+ * CheckboxGroup 多选框组属性接口
+ */
+export interface CheckboxGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange'> {
+    /** 受控模式：当前选中的值数组 */
+    value?: CheckboxValue[];
+    /** 非受控模式：初始选中的值数组 */
+    defaultValue?: CheckboxValue[];
+    /** 是否禁用整组所有多选框，默认为 false */
+    disabled?: boolean;
+    /** 整组是否采用带边框卡片样式，默认为 false */
+    bordered?: boolean;
+    /** 整组下属多选框统一的原生表单 name 字段 */
+    name?: string;
+    /** 整组统一尺寸大小，默认为 `md` */
+    size?: CheckboxSize;
+    /** 子节点列表（通常为一组 Checkbox） */
+    children?: ReactNode;
+    /** 选中值数组发生变化时的回调函数 */
+    onChange?: (value: CheckboxValue[]) => void;
+}

package/dist/types/Col/Col.d.cts

@@ -0,0 +1,3 @@
+import type { ColProps } from './type.cjs';
+declare const Col: import("react").ForwardRefExoticComponent<ColProps & import("react").RefAttributes<HTMLElement>>;
+export default Col;

package/dist/types/Col/Col.d.ts

@@ -0,0 +1,3 @@
+import type { ColProps } from './type.js';
+declare const Col: import("react").ForwardRefExoticComponent<ColProps & import("react").RefAttributes<HTMLElement>>;
+export default Col;

package/dist/types/Col/index.d.cts

@@ -0,0 +1,5 @@
+import Col from './Col.cjs';
+/** Col 栅格列组件 */
+export declare const VlCol: import("react").ForwardRefExoticComponent<import("./type.cjs").ColProps & import("react").RefAttributes<HTMLElement>>;
+export type { ColProps, ColSize, ColSizeObject, ColRef } from './type.cjs';
+export default Col;

package/dist/types/Col/index.d.ts

@@ -0,0 +1,5 @@
+import Col from './Col.js';
+/** Col 栅格列组件 */
+export declare const VlCol: import("react").ForwardRefExoticComponent<import("./type.js").ColProps & import("react").RefAttributes<HTMLElement>>;
+export type { ColProps, ColSize, ColSizeObject, ColRef } from './type.js';
+export default Col;

package/dist/types/Col/type.d.cts

@@ -0,0 +1,41 @@
+import type { HTMLAttributes, ElementType } from 'react';
+/** 响应式栅格断点配置对象 */
+export interface ColSizeObject {
+    /** 占用的栅格格数 (0-24) */
+    span?: number;
+    /** 左侧偏移的栅格格数 (0-24) */
+    offset?: number;
+    /** 向右移动的栅格格数 (0-24) */
+    push?: number;
+    /** 向左拉取的栅格格数 (0-24) */
+    pull?: number;
+}
+/** 单个断点的值类型：数字格数或配置对象 */
+export type ColSize = number | ColSizeObject;
+/** Col 根 DOM 元素类型 */
+export type ColRef = HTMLElement;
+/**
+ * Col 组件属性接口
+ */
+export interface ColProps extends HTMLAttributes<HTMLElement> {
+    /** 自定义渲染的 HTML 标签，默认为 `'div'` */
+    tag?: ElementType;
+    /** 栅格占据的格数 (0-24)，默认为 24 */
+    span?: number;
+    /** 栅格左侧的间隔格数 (0-24)，默认为 0 */
+    offset?: number;
+    /** 栅格向右移动格数 (0-24)，默认为 0 */
+    push?: number;
+    /** 栅格向左拉取格数 (0-24)，默认为 0 */
+    pull?: number;
+    /** `<768px` 超小屏幕响应式栅格配置 */
+    xs?: ColSize;
+    /** `≥768px` 小屏幕响应式栅格配置 */
+    sm?: ColSize;
+    /** `≥992px` 中等屏幕响应式栅格配置 */
+    md?: ColSize;
+    /** `≥1200px` 大屏幕响应式栅格配置 */
+    lg?: ColSize;
+    /** `≥1920px` 超大屏幕响应式栅格配置 */
+    xl?: ColSize;
+}

package/dist/types/Col/type.d.ts

@@ -0,0 +1,41 @@
+import type { HTMLAttributes, ElementType } from 'react';
+/** 响应式栅格断点配置对象 */
+export interface ColSizeObject {
+    /** 占用的栅格格数 (0-24) */
+    span?: number;
+    /** 左侧偏移的栅格格数 (0-24) */
+    offset?: number;
+    /** 向右移动的栅格格数 (0-24) */
+    push?: number;
+    /** 向左拉取的栅格格数 (0-24) */
+    pull?: number;
+}
+/** 单个断点的值类型：数字格数或配置对象 */
+export type ColSize = number | ColSizeObject;
+/** Col 根 DOM 元素类型 */
+export type ColRef = HTMLElement;
+/**
+ * Col 组件属性接口
+ */
+export interface ColProps extends HTMLAttributes<HTMLElement> {
+    /** 自定义渲染的 HTML 标签，默认为 `'div'` */
+    tag?: ElementType;
+    /** 栅格占据的格数 (0-24)，默认为 24 */
+    span?: number;
+    /** 栅格左侧的间隔格数 (0-24)，默认为 0 */
+    offset?: number;
+    /** 栅格向右移动格数 (0-24)，默认为 0 */
+    push?: number;
+    /** 栅格向左拉取格数 (0-24)，默认为 0 */
+    pull?: number;
+    /** `<768px` 超小屏幕响应式栅格配置 */
+    xs?: ColSize;
+    /** `≥768px` 小屏幕响应式栅格配置 */
+    sm?: ColSize;
+    /** `≥992px` 中等屏幕响应式栅格配置 */
+    md?: ColSize;
+    /** `≥1200px` 大屏幕响应式栅格配置 */
+    lg?: ColSize;
+    /** `≥1920px` 超大屏幕响应式栅格配置 */
+    xl?: ColSize;
+}

package/dist/types/Cron/Cron.d.cts

@@ -0,0 +1,3 @@
+import type { CronProps } from './type.cjs';
+declare const Cron: import("react").ForwardRefExoticComponent<CronProps & import("react").RefAttributes<HTMLDivElement>>;
+export default Cron;

package/dist/types/Cron/Cron.d.ts

@@ -0,0 +1,3 @@
+import type { CronProps } from './type.js';
+declare const Cron: import("react").ForwardRefExoticComponent<CronProps & import("react").RefAttributes<HTMLDivElement>>;
+export default Cron;

package/dist/types/Cron/CronField.d.cts

@@ -0,0 +1,14 @@
+import type { CronFieldSpec, CronFieldValue } from './expression.cjs';
+/** 字段编辑器属性 */
+export interface CronFieldProps {
+    /** 字段规格 */
+    spec: CronFieldSpec;
+    /** 当前结构化取值 */
+    value: CronFieldValue;
+    /** 是否禁用全部控件 */
+    disabled?: boolean;
+    /** 取值变更回调 */
+    onChange: (value: CronFieldValue) => void;
+}
+declare const CronField: ({ spec, value, disabled, onChange }: CronFieldProps) => import("react").JSX.Element;
+export default CronField;

package/dist/types/Cron/CronField.d.ts

@@ -0,0 +1,14 @@
+import type { CronFieldSpec, CronFieldValue } from './expression.js';
+/** 字段编辑器属性 */
+export interface CronFieldProps {
+    /** 字段规格 */
+    spec: CronFieldSpec;
+    /** 当前结构化取值 */
+    value: CronFieldValue;
+    /** 是否禁用全部控件 */
+    disabled?: boolean;
+    /** 取值变更回调 */
+    onChange: (value: CronFieldValue) => void;
+}
+declare const CronField: ({ spec, value, disabled, onChange }: CronFieldProps) => import("react").JSX.Element;
+export default CronField;

package/dist/types/Cron/CronPanel.d.cts

@@ -0,0 +1,27 @@
+import type { CronMode, CronParsed } from './expression.cjs';
+import type { CronShortcut } from './type.cjs';
+/** 编辑面板属性 */
+export interface CronPanelProps {
+    /** 当前表达式（已确保可解析） */
+    parsed: CronParsed;
+    /** 表达式方言 */
+    mode: CronMode;
+    /** 是否包含年字段 */
+    hasYear: boolean;
+    /** 是否只读 */
+    readonly?: boolean;
+    /** 快捷预设列表 */
+    shortcuts?: CronShortcut[];
+    /** 是否展示语义说明 */
+    showDescription?: boolean;
+    /** 是否展示执行时间预览 */
+    showPreview?: boolean;
+    /** 预览条数 */
+    previewCount?: number;
+    /** 表达式变更回调（已保证合法） */
+    onChange: (expression: string) => void;
+    /** 手动输入非法时的回调 */
+    onInvalid?: (expression: string, message: string) => void;
+}
+declare const CronPanel: ({ parsed, mode, hasYear, readonly, shortcuts, showDescription, showPreview, previewCount, onChange, onInvalid }: CronPanelProps) => import("react").JSX.Element;
+export default CronPanel;

package/dist/types/Cron/CronPanel.d.ts

@@ -0,0 +1,27 @@
+import type { CronMode, CronParsed } from './expression.js';
+import type { CronShortcut } from './type.js';
+/** 编辑面板属性 */
+export interface CronPanelProps {
+    /** 当前表达式（已确保可解析） */
+    parsed: CronParsed;
+    /** 表达式方言 */
+    mode: CronMode;
+    /** 是否包含年字段 */
+    hasYear: boolean;
+    /** 是否只读 */
+    readonly?: boolean;
+    /** 快捷预设列表 */
+    shortcuts?: CronShortcut[];
+    /** 是否展示语义说明 */
+    showDescription?: boolean;
+    /** 是否展示执行时间预览 */
+    showPreview?: boolean;
+    /** 预览条数 */
+    previewCount?: number;
+    /** 表达式变更回调（已保证合法） */
+    onChange: (expression: string) => void;
+    /** 手动输入非法时的回调 */
+    onInvalid?: (expression: string, message: string) => void;
+}
+declare const CronPanel: ({ parsed, mode, hasYear, readonly, shortcuts, showDescription, showPreview, previewCount, onChange, onInvalid }: CronPanelProps) => import("react").JSX.Element;
+export default CronPanel;

package/dist/types/Cron/describe.d.cts

@@ -0,0 +1,10 @@
+/**
+ * 把 Cron 表达式翻译成中文说明，如「每天 09:30:00 执行」。
+ *
+ * 描述基于字段原文而不是展开后的值集合：`星号/5` 要读成「每 5 分钟」而不是「0、5、10……分」，
+ * 所以这里复用 fieldToEditor 拿到「类型 + 参数」，再按类型选措辞。编辑器表达不了的字段
+ * 直接回显原文，宁可朴素也不要说错。
+ */
+import type { CronParsed } from './expression.cjs';
+/** 生成中文说明。 */
+export declare const describeCron: (parsed: CronParsed) => string;

package/dist/types/Cron/describe.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 把 Cron 表达式翻译成中文说明，如「每天 09:30:00 执行」。
+ *
+ * 描述基于字段原文而不是展开后的值集合：`星号/5` 要读成「每 5 分钟」而不是「0、5、10……分」，
+ * 所以这里复用 fieldToEditor 拿到「类型 + 参数」，再按类型选措辞。编辑器表达不了的字段
+ * 直接回显原文，宁可朴素也不要说错。
+ */
+import type { CronParsed } from './expression.js';
+/** 生成中文说明。 */
+export declare const describeCron: (parsed: CronParsed) => string;

package/dist/types/Cron/expression.d.cts

@@ -0,0 +1,188 @@
+/**
+ * Cron 表达式的方言规格、解析、展开与序列化。
+ *
+ * 设计约束：
+ * 1. 一个字段文本可能是逗号分隔的多个段（如 `0-10,20,30-40/2`）。求值和描述只关心「展开后的值集合」，
+ *    因此 expandField 始终按段解析，与编辑器能否用单一类型表达无关；
+ * 2. 编辑器需要「类型 + 参数」的结构化状态，但并非所有合法字段都能被单一类型表达。无法表达时落为
+ *    `custom` 并保留原文，保证粘贴进来的表达式不会被编辑器悄悄改写；
+ * 3. Unix 与 Quartz 的差异集中在 FIELD_SPECS 与 modeFields 两处，其余逻辑共享，避免方言判断散落各处。
+ */
+/** Cron 表达式方言：标准 Unix 五段 | Quartz 六/七段 */
+export type CronMode = 'unix' | 'quartz';
+/** Cron 字段名 */
+export type CronFieldName = 'second' | 'minute' | 'hour' | 'dayOfMonth' | 'month' | 'dayOfWeek' | 'year';
+/** 字段编辑器的取值类型 */
+export type CronFieldKind = 'every' | 'unspecified' | 'range' | 'step' | 'list' | 'last' | 'weekday' | 'nth' | 'custom';
+/** 字段编辑器的结构化取值 */
+export type CronFieldValue = 
+/** `*` 每一个值 */
+{
+    kind: 'every';
+}
+/** `?` 不指定（仅 Quartz 的日、周字段） */
+ | {
+    kind: 'unspecified';
+}
+/** `a-b` 连续区间 */
+ | {
+    kind: 'range';
+    from: number;
+    to: number;
+}
+/** `a-b/n` 每 n 个单位；起止为 null 时取字段边界，即 `a/n` 与 `星号/n` */
+ | {
+    kind: 'step';
+    from: number | null;
+    to: number | null;
+    step: number;
+}
+/** `a,b,c` 枚举 */
+ | {
+    kind: 'list';
+    values: number[];
+}
+/** `L` 本月最后一天 / `L-n` 最后一天前 n 天 / `LW` 最后一个工作日 / `nL` 本月最后一个周 n */
+ | {
+    kind: 'last';
+    offset: number;
+    weekday: boolean;
+    dayOfWeek: number | null;
+}
+/** `nW` 离 n 号最近的工作日 */
+ | {
+    kind: 'weekday';
+    day: number;
+}
+/** `n#m` 本月第 m 个周 n */
+ | {
+    kind: 'nth';
+    dayOfWeek: number;
+    nth: number;
+}
+/** 编辑器无法用单一类型表达的合法字段，保留原文 */
+ | {
+    kind: 'custom';
+    text: string;
+};
+/** 单个字段的方言规格 */
+export type CronFieldSpec = {
+    name: CronFieldName;
+    /** 中文字段名 */
+    label: string;
+    /** 允许的最小值 */
+    min: number;
+    /** 允许的最大值 */
+    max: number;
+    /** 文本别名到数值的映射（如 JAN=1、MON=2） */
+    aliases?: Record<string, number>;
+    /** 是否允许 `?` */
+    allowUnspecified?: boolean;
+    /** 是否允许 `L` 系列写法 */
+    allowLast?: boolean;
+    /** 是否允许 `nW` */
+    allowWeekday?: boolean;
+    /** 是否允许 `n#m` */
+    allowNth?: boolean;
+    /** 解析时允许但会被归一化的额外取值（Unix 周字段的 7 等价于 0） */
+    wrap?: {
+        from: number;
+        to: number;
+    };
+};
+/** 各方言的字段规格表。方言差异只在这里声明。 */
+export declare const FIELD_SPECS: Record<CronMode, Record<CronFieldName, CronFieldSpec | undefined>>;
+/** 按方言与是否包含年字段返回字段顺序。 */
+export declare const modeFields: (mode: CronMode, withYear?: boolean) => CronFieldName[];
+/** 取字段规格；方言不支持该字段时抛错，避免调用方静默拿到 undefined。 */
+export declare const getFieldSpec: (mode: CronMode, field: CronFieldName) => CronFieldSpec;
+/** 星期数值到中文名的映射，按字段规格的最小值推导方言偏移。 */
+export declare const weekdayLabel: (value: number, spec: CronFieldSpec) => string;
+/** 月份数值到中文名。 */
+export declare const monthLabel: (value: number) => string;
+/** 字段解析失败时抛出，携带字段名以便面板把错误定位到具体 Tab。 */
+export declare class CronFieldError extends Error {
+    readonly field: CronFieldName;
+    constructor(field: CronFieldName, message: string);
+}
+/** `L` 系列与 `W`、`#` 只能作为整段出现，展开时单独记录，不进入数值集合。 */
+export type CronDayRule = 
+/** `L-n`：本月最后一天前 n 天（n 为 0 表示最后一天） */
+{
+    type: 'lastDayOfMonth';
+    offset: number;
+}
+/** `LW`：本月最后一个工作日 */
+ | {
+    type: 'lastWeekdayOfMonth';
+}
+/** `nW`：离 n 号最近的工作日 */
+ | {
+    type: 'nearestWeekday';
+    day: number;
+}
+/** `nL`：本月最后一个周 n */
+ | {
+    type: 'lastDayOfWeek';
+    dayOfWeek: number;
+}
+/** `n#m`：本月第 m 个周 n */
+ | {
+    type: 'nthDayOfWeek';
+    dayOfWeek: number;
+    nth: number;
+};
+/** 字段展开结果：数值集合 + 特殊日规则 + 是否为 `*` / `?`。 */
+export type CronFieldMatch = {
+    /** 命中的数值集合，已升序去重。特殊规则不写入这里。 */
+    values: number[];
+    /** `L` / `W` / `#` 规则 */
+    rules: CronDayRule[];
+    /** 是否为 `*`（不限定） */
+    wildcard: boolean;
+    /** 是否为 `?`（不指定） */
+    unspecified: boolean;
+};
+/** 把字段文本展开为可用于求值的匹配集合。 */
+export declare const expandField: (text: string, spec: CronFieldSpec) => CronFieldMatch;
+/** 全部字段名，与求值顺序一致（由粗到细便于逐层收敛）。 */
+export declare const ALL_FIELDS: CronFieldName[];
+/** 各字段原文。方言不含的字段补等价默认值：Unix 无秒字段即固定在 0 秒触发。 */
+export type CronFields = Record<CronFieldName, string>;
+/** 解析成功的表达式：原文 + 展开结果，求值与描述都只依赖它。 */
+export type CronParsed = {
+    mode: CronMode;
+    /** 表达式是否显式包含年字段 */
+    hasYear: boolean;
+    fields: CronFields;
+    matches: Record<CronFieldName, CronFieldMatch>;
+};
+/** 解析结果。失败时带上字段名，面板据此把错误定位到具体 Tab。 */
+export type CronParseResult = {
+    ok: true;
+    value: CronParsed;
+} | {
+    ok: false;
+    message: string;
+    field?: CronFieldName;
+};
+/** 字段是否限定了取值：`*` 与 `?` 都不算限定。 */
+export declare const isRestricted: (match: CronFieldMatch) => boolean;
+/**
+ * 解析表达式。
+ *
+ * 宽容之处：Quartz 的日/周只要有一个不限定就放行（`0 0 12 * * *` 这类粘贴进来的写法照常工作）；
+ * 严格之处：两者同时为 `?` 或同时被限定都会报错——前者没有任何日期可命中，后者在 Quartz 里行为未定义。
+ */
+export declare const parseCron: (expression: string, mode: CronMode) => CronParseResult;
+/** 按方言的字段顺序拼回表达式。 */
+export declare const stringifyCron: (fields: CronFields, mode: CronMode, hasYear?: boolean) => string;
+/** 方言的默认表达式：Unix 每分钟，Quartz 每分钟的第 0 秒。 */
+export declare const defaultExpression: (mode: CronMode, hasYear?: boolean) => string;
+/**
+ * 字段原文转编辑器状态。无法用单一类型表达时落为 `custom` 保留原文，
+ * 避免打开面板就把用户的 `0-10,20,30-40/2` 改写成别的东西。
+ */
+export declare const fieldToEditor: (text: string, spec: CronFieldSpec) => CronFieldValue;
+/** 编辑器状态转字段原文。 */
+export declare const editorToField: (value: CronFieldValue, spec: CronFieldSpec) => string;