@anov/cic-standard-sdk 0.0.1 → 0.0.3

package/dist/sdk/CICSDK.d.ts

@@ -0,0 +1,70 @@
+import type { CICConfig, ComponentInstance, DataSourceItem, CICPage, Meta, Layout, Registry, Variables, Dependency } from '../types';
+import type { ICICSDK } from './ICICSDK';
+export type { CICConfig, ComponentInstance, DataSourceItem, CICPage, Meta, Layout, Registry, Variables, Dependency, ICICSDK };
+/**
+ * CIC SDK 类
+ * 提供对 CIC 配置的封装访问与操作
+ */
+export declare class CICSDK implements ICICSDK {
+    private config;
+    private static validator;
+    private static validate;
+    private static schemaHash;
+    constructor(config: CICConfig);
+    getConfig(): CICConfig;
+    findComponent(id: string): ComponentInstance | undefined;
+    findPageByComponent(componentId: string): CICPage | undefined;
+    getVariable(scopeContext: {
+        pageId?: string;
+        componentId?: string;
+    }, key: string): any;
+    getVariableByRef(ref: string): any;
+    walkComponents(callback: (component: ComponentInstance, page: CICPage, parent?: ComponentInstance) => void | boolean): void;
+    /**
+     * 全面配置校验 (基于 JSON Schema)
+     */
+    static validateConfig(config: CICConfig): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * 按路径获取对象值（支持 a.b[0].c 语法）
+     */
+    static getValueByPath(obj: any, path: string, fallback?: any): any;
+    /**
+     * 深度遍历组件树（纯函数递归版本）
+     * 用于单独处理某个组件树片段
+     */
+    static traverseTree(root: ComponentInstance | ComponentInstance[], callback: (component: ComponentInstance, parent?: ComponentInstance) => void | boolean, parent?: ComponentInstance): void;
+    /** 创建 DataSource */
+    static createDataSource: (input: unknown, options?: import("./generators/common").CreateOptions) => import("./generators/common").Result<DataSourceItem>;
+    static validateDataSource: (input: unknown) => import("./generators/common").Result<null>;
+    static normalizeDataSource: (input: unknown, options?: import("./generators/common").CreateOptions) => DataSourceItem;
+    /** 创建 Component */
+    static createComponent: (input: unknown, options?: import("./generators/common").CreateOptions) => import("./generators/common").Result<ComponentInstance>;
+    static validateComponent: (input: unknown) => import("./generators/common").Result<null>;
+    static normalizeComponent: (input: unknown, options?: import("./generators/common").CreateOptions) => ComponentInstance;
+    /** 创建 Page */
+    static createPage: (input: unknown, options?: import("./generators/common").CreateOptions) => import("./generators/common").Result<CICPage>;
+    static validatePage: (input: unknown) => import("./generators/common").Result<null>;
+    static normalizePage: (input: unknown, options?: import("./generators/common").CreateOptions) => CICPage;
+    /** 创建 Meta/Layout */
+    static createMeta: (input: unknown) => import("./generators/common").Result<Meta>;
+    static createLayout: (input: unknown) => import("./generators/common").Result<Layout>;
+    static validateMeta: (input: unknown) => import("./generators/common").Result<null>;
+    static validateLayout: (input: unknown) => import("./generators/common").Result<null>;
+    static normalizeMeta: (input: unknown) => Meta;
+    static normalizeLayout: (input: unknown) => Layout;
+    /** 创建 Variables */
+    static createVariables: (input: unknown) => import("./generators/common").Result<Variables>;
+    static validateVariables: (input: unknown) => import("./generators/common").Result<null>;
+    static normalizeVariables: (input: unknown) => Variables;
+    /** 创建 Dependency */
+    static createDependency: (input: unknown) => import("./generators/common").Result<Dependency>;
+    static validateDependency: (input: unknown) => import("./generators/common").Result<null>;
+    static normalizeDependency: (input: unknown) => Dependency;
+    /** 创建 Registry 组件项 */
+    static createRegistryComponent: (input: unknown) => import("./generators/common").Result<import("../types/registry").RegistryComponents>;
+    static validateRegistryComponent: (input: unknown) => import("./generators/common").Result<null>;
+    static normalizeRegistryComponent: (input: unknown) => import("../types/registry").RegistryComponents;
+}

package/dist/sdk/ICICSDK.d.ts

@@ -0,0 +1,43 @@
+import { CICConfig } from '../types';
+import { CICPage } from '../types/page';
+import { ComponentInstance } from '../types/componets';
+/**
+ * CIC SDK 接口定义
+ * 定义了 SDK 必须提供的核心能力，实现与定义解耦。
+ */
+export interface ICICSDK {
+    /**
+     * 获取当前完整的配置对象
+     */
+    getConfig(): CICConfig;
+    /**
+     * 按 ID 查找组件实例
+     * @param id 组件 ID
+     */
+    findComponent(id: string): ComponentInstance | undefined;
+    /**
+     * 查找组件所属的页面
+     * @param componentId 组件 ID
+     */
+    findPageByComponent(componentId: string): CICPage | undefined;
+    /**
+     * 获取变量值
+     * 遵循作用域链：Component -> Page -> Global
+     * @param scopeContext 作用域上下文 { pageId?, componentId? }
+     * @param key 变量名
+     */
+    getVariable(scopeContext: {
+        pageId?: string;
+        componentId?: string;
+    }, key: string): any;
+    /**
+     * 通过引用字符串获取变量
+     * @param ref 引用字符串 (e.g. "global.theme", "page:p1.title")
+     */
+    getVariableByRef(ref: string): any;
+    /**
+     * 遍历所有组件
+     * @param callback 回调函数，返回 false 可终止遍历
+     */
+    walkComponents(callback: (component: ComponentInstance, page: CICPage, parent?: ComponentInstance) => void | boolean): void;
+}

package/dist/sdk/generators/ajv.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Ajv 单例与子 Schema 校验器
+ * 说明：复用项目主 Schema（Draft-07），按需编译子定义（#/definitions/...）。
+ * 注意：strict 关闭以兼容联合与 const/enum 的复杂组合。
+ */
+import Ajv from 'ajv';
+export declare const getAjv: () => Ajv;
+export declare const getValidator: (ref: string) => any;
+export declare const getValidatorByType: (typeName: string) => any;

package/dist/sdk/generators/common.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 生成器通用工具与类型
+ * 说明：统一 Result/Options 定义与常用规范化工具（uuid/url/数组/数值）。
+ * 原则：严格模式默认不做隐式容错；仅在 defaults 显式提供时才补齐默认值。
+ */
+export type Result<T> = {
+    ok: boolean;
+    value?: T;
+    errors?: any[];
+};
+export type CreateOptions = {
+    defaults?: Record<string, any>;
+    generateId?: boolean;
+    strict?: boolean;
+    throw?: boolean;
+};
+/** 将值规范为数组 */
+export declare const ensureArray: <T>(v: any) => T[];
+/** 判断为有限正数 */
+export declare const isPositive: (n: any) => boolean;
+/** 生成 uuid（浏览器环境降级） */
+export declare const uuid: () => any;
+/** 规范 http(s) 链接 */
+export declare const httpUrl: (s: any, fallback?: string) => string;
+/** 规范 ws(s) 链接 */
+export declare const wsUrl: (s: any, fallback?: string) => string;

package/dist/sdk/generators/component.d.ts

@@ -0,0 +1,5 @@
+import { Result, CreateOptions } from './common';
+import { ComponentInstance } from '../../types/componets';
+export declare const validateComponent: (input: unknown) => Result<null>;
+export declare const createComponent: (input: unknown, options?: CreateOptions) => Result<ComponentInstance>;
+export declare const normalizeComponent: (input: unknown, options?: CreateOptions) => ComponentInstance;

package/dist/sdk/generators/dataSource.d.ts

@@ -0,0 +1,5 @@
+import { Result, CreateOptions } from './common';
+import { DataSourceItem } from '../../types/dataSources';
+export declare const validateDataSource: (input: unknown) => Result<null>;
+export declare const createDataSource: (input: unknown, options?: CreateOptions) => Result<DataSourceItem>;
+export declare const normalizeDataSource: (input: unknown, options?: CreateOptions) => DataSourceItem;

package/dist/sdk/generators/dependency.d.ts

@@ -0,0 +1,5 @@
+import { Result } from './common';
+import { Dependency } from '../../types/deps';
+export declare const validateDependency: (input: unknown) => Result<null>;
+export declare const createDependency: (input: unknown) => Result<Dependency>;
+export declare const normalizeDependency: (input: unknown) => Dependency;

package/dist/sdk/generators/meta.d.ts

@@ -0,0 +1,8 @@
+import { Result } from './common';
+import { Meta, Layout } from '../../types/meta';
+export declare const validateMeta: (input: unknown) => Result<null>;
+export declare const validateLayout: (input: unknown) => Result<null>;
+export declare const createMeta: (input: unknown) => Result<Meta>;
+export declare const createLayout: (input: unknown) => Result<Layout>;
+export declare const normalizeMeta: (input: unknown) => Meta;
+export declare const normalizeLayout: (input: unknown) => Layout;

package/dist/sdk/generators/page.d.ts

@@ -0,0 +1,5 @@
+import { Result, CreateOptions } from './common';
+import { CICPage } from '../../types/page';
+export declare const validatePage: (input: unknown) => Result<null>;
+export declare const createPage: (input: unknown, options?: CreateOptions) => Result<CICPage>;
+export declare const normalizePage: (input: unknown, options?: CreateOptions) => CICPage;

package/dist/sdk/generators/registry.d.ts

@@ -0,0 +1,5 @@
+import { Result } from './common';
+import { RegistryComponents } from '../../types/registry';
+export declare const validateRegistryComponent: (input: unknown) => Result<null>;
+export declare const createRegistryComponent: (input: unknown) => Result<RegistryComponents>;
+export declare const normalizeRegistryComponent: (input: unknown) => RegistryComponents;

package/dist/sdk/generators/variables.d.ts

@@ -0,0 +1,5 @@
+import { Result } from './common';
+import { Variables } from '../../types/variables';
+export declare const validateVariables: (input: unknown) => Result<null>;
+export declare const createVariables: (input: unknown) => Result<Variables>;
+export declare const normalizeVariables: (input: unknown) => Variables;

package/dist/types/componets.d.ts

@@ -0,0 +1,49 @@
+import { CICEventMap } from './events';
+import { Data } from './data';
+/** 通用表达式（用于条件、模板等） */
+export type Expr = string;
+/** 样式值可以是静态或表达式 */
+export type StyleValue = string | number | Expr;
+/** component 引用：字符串或 object 描述 */
+export type ComponentRef = string | {
+    type: "id";
+    value: string;
+};
+export type LogicRef = string | {
+    type: "url" | "code";
+    value: string;
+};
+/**
+ * 组件的语义分类（view/container/logic）
+ * - view: 可视化渲染组件
+ * - container: 容器，包含 children
+ * - logic: 逻辑/脚本组件
+ */
+export type ComponentType = 'view' | 'container' | 'logic';
+/** 组件实例 */
+export interface ComponentBase {
+    id: string;
+    props?: Record<string, any>;
+    style?: Record<string, StyleValue>;
+    events?: CICEventMap;
+    data?: Data;
+    deps?: string[];
+    extensions?: Record<string, any>;
+}
+export interface ViewComponentInstance extends ComponentBase {
+    role: 'view';
+    component: ComponentRef;
+    children?: never;
+}
+export interface ContainerComponentInstance extends ComponentBase {
+    role: 'container';
+    children: ComponentInstance[];
+    component?: never;
+}
+export interface LogicComponentInstanceRef extends ComponentBase {
+    role: 'logic';
+    component: LogicRef;
+    children?: never;
+}
+/** 组件实例（view/container/logic 类型） */
+export type ComponentInstance = ViewComponentInstance | ContainerComponentInstance | LogicComponentInstanceRef;

package/dist/types/data.d.ts

@@ -0,0 +1,35 @@
+/** 字段映射配置 */
+export interface IMapping {
+    use: boolean;
+    mapFields: Array<{
+        /** 源字段名 */
+        field: string;
+        /** 目标字段名 */
+        mapField: string;
+        /** 映射值或公式 */
+        value?: any;
+        /** 映射类型：默认(普通映射)、copy(复制) const(常量)、formula(公式) */
+        type?: 'copy' | 'const' | 'formula';
+        /** 描述 */
+        description?: string;
+    }>;
+}
+/** 转换规则配置 */
+export interface IConverse {
+    use: boolean;
+    data: Array<{
+        /** 转换代码 */
+        code: string;
+        /** 依赖变量列表（用于响应式重执行） */
+        depeedVars?: Array<string>;
+    }>;
+}
+/** 数据配置 */
+export interface Data {
+    /** 数据ID */
+    id: string;
+    /** 字段映射配置 */
+    mapping?: IMapping;
+    /** 转换规则配置 */
+    converse?: IConverse;
+}

package/dist/types/dataSources.d.ts

@@ -0,0 +1,38 @@
+export type Milliseconds = number;
+export interface DataSourceBase {
+    id: string;
+    type: string;
+    order?: number;
+    pollInterval?: Milliseconds;
+    transform?: string | ((res: any) => any);
+}
+export interface DataSourceRest extends DataSourceBase {
+    type: "rest";
+    url: string;
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    headers?: Record<string, string>;
+    params?: Record<string, any>;
+    body?: any;
+    timeout?: Milliseconds;
+}
+export interface DataSourceWebSocket extends DataSourceBase {
+    type: "websocket";
+    url: string;
+    protocols?: string | string[];
+    subscribeMessage?: any;
+    heartbeat?: {
+        interval: Milliseconds;
+        message: any;
+    };
+}
+export interface DataSourceStatic extends DataSourceBase {
+    type: "static";
+    value: any;
+}
+export interface DataSourceFunction extends DataSourceBase {
+    type: "function";
+    code: string;
+    timeout?: Milliseconds;
+}
+/** 数据源项（rest/websocket/static/function 类型） */
+export type DataSourceItem = DataSourceRest | DataSourceWebSocket | DataSourceStatic | DataSourceFunction;

package/dist/types/deps.d.ts

@@ -0,0 +1,71 @@
+/** 资源类型 */
+export type ResourceType = 'js' | 'css' | 'font' | 'image' | 'json' | 'wasm' | 'other';
+/** JS 格式 */
+export type JSFormat = 'esm' | 'umd' | 'iife' | 'cjs';
+/**
+ * 公共字段
+ */
+export interface BaseDependency {
+    /** 全局唯一 ID，用于运行时索引 */
+    id: string;
+    /** 可选：人类可读名称（展示用） */
+    name?: string;
+    /** 版本号（语义化版本 / 字体权重皆可） */
+    version?: string;
+    /** 资源 URL，可以是绝对地址或相对地址 */
+    url?: string;
+    /** 本地路径（构建后使用） */
+    localPath?: string;
+    /** 分组：方便批量加载 */
+    group?: string;
+    /** 加载策略 */
+    strategy?: {
+        /** 预加载/预取 */
+        preload?: boolean | 'module' | 'style';
+        prefetch?: boolean;
+        /** 是否异步加载 */
+        async?: boolean;
+        /** 仅在某些条件下加载（如主题） */
+        when?: string;
+    };
+}
+/** JS 资源 */
+export interface JSDependency extends BaseDependency {
+    type: 'js';
+    format: JSFormat;
+    crossOrigin?: 'anonymous' | 'use-credentials';
+    module?: boolean;
+}
+/** CSS */
+export interface CSSDependency extends BaseDependency {
+    type: 'css';
+    media?: string;
+}
+/** 字体 */
+export interface FontDependency extends BaseDependency {
+    type: 'font';
+    family?: string;
+    weight?: number | string;
+    style?: 'normal' | 'italic';
+}
+/** 图片 */
+export interface ImageDependency extends BaseDependency {
+    type: 'image';
+    mime?: string;
+}
+/** JSON */
+export interface JSONDependency extends BaseDependency {
+    type: 'json';
+}
+/** WASM */
+export interface WasmDependency extends BaseDependency {
+    type: 'wasm';
+    init?: 'async' | 'sync';
+}
+/** 其他 */
+export interface OtherDependency extends BaseDependency {
+    type: 'other';
+    kind?: string;
+}
+/** 依赖项 */
+export type Dependency = JSDependency | CSSDependency | FontDependency | ImageDependency | JSONDependency | WasmDependency | OtherDependency;

package/dist/types/events.d.ts

@@ -0,0 +1,133 @@
+/** 所有事件大类 */
+export type EventType = 'vars' | 'navigate' | 'comp' | 'toggle' | 'camera' | 'material' | 'custom' | string;
+/** 变量事件动作 */
+export type VarsAction = 'add' | 'update' | 'delete';
+/** 跳转事件动作 */
+export type NavigateAction = 'internal' | 'external';
+/** 组件事件动作 */
+export type CompAction = 'add' | 'update' | 'delete';
+/** 切换事件动作 */
+export type ToggleAction = 'visibility';
+/** 相机动作 */
+export type CameraAction = 'focus';
+/** 材质动作 */
+export type MaterialAction = 'change';
+/** 自定义动作 */
+export type CustomAction = 'local' | 'remote';
+export interface VarsParams {
+    key: string;
+    value: any;
+    exclude?: string[];
+}
+export interface NavigateInternalParams {
+    name: string;
+    params?: Record<string, any>;
+}
+export interface NavigateExternalParams {
+    url: string;
+    openNewTab?: boolean;
+}
+export interface CompParams {
+    comps: string[];
+    props?: Record<string, any>;
+}
+export interface ToggleParams {
+    show?: string[];
+    hide?: string[];
+}
+export interface CameraFocusParams {
+    target: string | number;
+    duration?: number;
+}
+export interface MaterialChangeParams {
+    target: string;
+    materials: string;
+}
+export interface CustomLocalParams {
+    code: string;
+    depends?: string[];
+}
+export interface CustomRemoteParams {
+    url: string;
+    depends?: string[];
+}
+export type ConditionOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not-in' | 'exists' | 'not-exists';
+export interface KeyCondition {
+    key: string;
+    op?: ConditionOperator;
+    value?: any;
+}
+/** 表达式条件：支持如 "ctx.id === 5 && ctx.level > 1" */
+export interface ExpressionCondition {
+    expression: string;
+}
+/** 多条件（AND） + 表达式 */
+export type EventCondition = KeyCondition | KeyCondition[] | ExpressionCondition;
+/** 不同事件类型对应不同结构 */
+/** 变量事件 */
+export interface VarsEvent {
+    type: 'vars';
+    action: VarsAction;
+    params: VarsParams;
+}
+/** 内部跳转事件 */
+export interface NavigateInternalEvent {
+    type: 'navigate';
+    action: 'internal';
+    params: NavigateInternalParams;
+}
+/** 外部跳转事件 */
+export interface NavigateExternalEvent {
+    type: 'navigate';
+    action: 'external';
+    params: NavigateExternalParams;
+}
+/** 组件事件 */
+export interface CompEvent {
+    type: 'comp';
+    action: CompAction;
+    params: CompParams;
+}
+/** 显示隐藏切换事件 */
+export interface ToggleEvent {
+    type: 'toggle';
+    action: 'visibility';
+    params: ToggleParams;
+}
+/** 相机事件 */
+export interface CameraEvent {
+    type: 'camera';
+    action: 'focus';
+    params: CameraFocusParams;
+}
+/** 材质事件 */
+export interface MaterialEvent {
+    type: 'material';
+    action: 'change';
+    params: MaterialChangeParams;
+}
+/** 自定义本地事件 */
+export interface CustomLocalEvent {
+    type: 'custom';
+    action: 'local';
+    params: CustomLocalParams;
+}
+/** 自定义远程事件 */
+export interface CustomRemoteEvent {
+    type: 'custom';
+    action: 'remote';
+    params: CustomRemoteParams;
+}
+/** 最终事件联合类型 */
+export type CICEvent = VarsEvent | NavigateInternalEvent | NavigateExternalEvent | CompEvent | ToggleEvent | CameraEvent | MaterialEvent | CustomLocalEvent | CustomRemoteEvent;
+/** 带调度信息 */
+export type CICEventWithMeta = CICEvent & {
+    order: number;
+    delay?: number;
+    condition?: EventCondition;
+};
+/** 某组件的所有事件
+ * 说明：定义了 CIC 项目中组件的所有事件，包含事件类型、动作、参数、调度顺序、延迟时间和条件。
+ * （key: 事件名, value: 处理逻辑数组）
+ */
+export type CICEventMap = Record<string, CICEventWithMeta[]>;

package/dist/types/index.d.ts

@@ -0,0 +1,23 @@
+import { Meta, Layout } from './meta';
+import { Registry } from './registry';
+import { Variables } from './variables';
+import { Dependency } from './deps';
+import { CICPage, ComponentInstance, DataSourceItem } from './page';
+/**
+ * CIC 配置定义
+ * 说明：定义了 CIC 项目的全局配置，包含版本、元数据、页面、组件、变量、依赖等。
+ */
+export interface CICConfig {
+    version: string;
+    meta: Meta;
+    pages: CICPage[];
+    registry?: Registry;
+    variables?: Variables;
+    deps?: Dependency[];
+    extensions?: Record<string, any>;
+}
+/**
+ * CIC 类型定义
+ * 说明：定义了 CIC 项目中使用的各种类型，包括元数据、布局、页面、组件、变量、依赖项等。
+ */
+export type { Meta, Layout, CICPage, Registry, Variables, Dependency, ComponentInstance, DataSourceItem };

package/dist/types/meta.d.ts

@@ -0,0 +1,54 @@
+/**布局配置 */
+export interface Layout {
+    /** 布局类型: free(自由布局) 或 grid(网格布局) */
+    type: "free" | "grid";
+    config: {
+        /**
+         * 设计稿宽度
+         * @minimum 1
+         * @default 1920
+         */
+        width: number;
+        /**
+         * 设计稿高度
+         * @minimum 1
+         * @default 1080
+         */
+        height: number;
+        /**
+         * 缩放模式
+         * @default "aspectFit"
+         */
+        scaleMode: "aspectFit" | "fill";
+    };
+}
+/**
+ * 项目元信息
+ * 包含项目的基本信息、布局配置、语言、创建时间、更新时间、作者和扩展信息。
+ */
+export interface Meta {
+    /** 项目唯一标识符 */
+    projectId?: string;
+    /** 项目名称 */
+    projectName?: string;
+    /** 项目描述 */
+    description?: string;
+    /** 布局配置 */
+    layout?: Layout;
+    /** 语言代码 (e.g. zh-CN, en-US) */
+    language?: string;
+    /**
+     * 创建时间 (ISO 8601)
+     * @format date-time
+     */
+    createTime?: string;
+    /**
+     * 更新时间 (ISO 8601)
+     * @format date-time
+     */
+    updateTime?: string;
+    /** 作者 */
+    author?: string;
+    /** 扩展字段 */
+    extensions?: Record<string, any>;
+}

package/dist/types/page.d.ts

@@ -0,0 +1,17 @@
+import { ComponentInstance } from './componets';
+import { DataSourceItem } from './dataSources';
+import { Layout } from './meta';
+/**
+ * CIC 页面定义
+ * 说明：定义了 CIC 中页面的结构，包含页面 ID、名称、路径、布局、组件等。
+ */
+interface CICPage {
+    id: string;
+    name: string;
+    path: string;
+    layout?: Layout;
+    components?: ComponentInstance[];
+    dataSources?: DataSourceItem[];
+    extensions?: Record<string, any>;
+}
+export type { CICPage, ComponentInstance, DataSourceItem };

package/dist/types/registry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 注册中心组件项
+ * 说明：定义了 CIC 项目中组件注册中心的组件项，包含组件 ID、类型和配置。
+*/
+export interface RegistryComponents {
+    id: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    author?: string;
+    defaultProps?: Record<string, any>;
+    data?: any;
+    deps?: string[];
+}
+/**
+ * 注册表
+ */
+export interface Registry {
+    components?: RegistryComponents[];
+    /**插件后期可扩展 */
+    plugins?: Record<string, any>;
+}