@anov/cic-standard-sdk 0.0.20 → 0.0.21

package/dist/types/cic.manifest.d.ts

@@ -1,367 +0,0 @@
-/**
- * =========================================================
- * CIC Manifest 是 CIC 内容包的"运行时装配说明书"
- *
- *
- * 与 CIC Config 的区别：
- * ┌─────────────────┬──────────────────┐
- * │ CIC Config      │ CIC Manifest     │
- * ├─────────────────┼──────────────────┤
- * │ 描述"是什么"    │ 描述"怎么运行"   │
- * │ 组件、数据、结构│ 加载、解析、执行 │
- * │ 平台无关        │ 平台相关         │
- * │ 可序列化数据    │ 运行时配置       │
- * └─────────────────┴──────────────────┘
- *
- *
- * 核心职责：
- * - 声明运行时环境要求
- * - 定义模块解析规则（公共依赖：importmap / global / cdn）
- * - 配置组件加载与注册策略（install / init / 自定义调用）
- * - 声明导出策略（公共依赖排除列表）、平台能力要求
- * =========================================================
- */
-/**
- * CIC Manifest 主接口
- */
-export interface CICManifest {
-    /**
-     * Manifest 版本
-     * @example "1.0.0"
-     */
-    version: string;
-    /**
-     * 运行时引擎
-     * 声明此 CIC 需要的运行环境
-     */
-    engine: RuntimeEngine;
-    /**
-     * 模块解析
-     * 定义如何解析和加载模块（公共依赖）
-     */
-    modules: ModuleResolution;
-    /**
-     * 组件配置（可选）
-     * 定义组件加载和注册规则
-     */
-    components?: ComponentConfig;
-    /**
-     * 导出策略（可选）
-     *
-     * 场景：不同平台导出 CIC Config 时，需要排除公共依赖（宿主统一注入）。
-     */
-    export?: ManifestExportConfig;
-    /**
-     * 扩展配置（可选）
-     * 平台特定或自定义配置
-     */
-    extensions?: Record<string, any>;
-}
-/**
- * 运行时引擎
- */
-export interface RuntimeEngine {
-    /**
-     * 平台类型
-     * @example "web" | "node" | "mini-program" | "desktop"
-     */
-    platform: string;
-    /**
-     * 运行时类型
-     * @example "vue3" | "vue2" | "react" | "angular" | "vanilla"
-     */
-    runtime: string;
-    /**
-     * 运行时版本约束（可选）
-     * @example "^3.0.0"
-     */
-    version?: string;
-}
-/**
- * 模块解析配置
- */
-export interface ModuleResolution {
-    /**
-     * 解析策略
-     * - importmap: 使用 Import Maps（推荐）
-     * - global: 使用全局变量
-     * - hybrid: 混合模式（优先 importmap，失败降级 global/cdn）
-     */
-    strategy: 'importmap' | 'global' | 'hybrid';
-    /**
-     * Import Map（strategy 为 importmap 或 hybrid 时可用）
-     *
-     * importMap 与 importMapFile 二选一即可。
-     */
-    importMap?: ImportMap;
-    /**
-     * Import Map 文件路径（可选）
-     * 如果提供此字段，运行时将尝试从指定路径加载 Import Map 配置
-     * @example "./importmap.json"
-     */
-    importMapFile?: string;
-    /**
-     * 外部依赖（可选）
-     * 声明由宿主环境提供的依赖
-     *
-     * 约束建议：
-     * - 同一个 id 不要写两条 externals（避免歧义）
-     * - 需要“importmap + global”时，用 strategy=hybrid + fallback 表达“主 + 兜底”
-     */
-    externals?: ExternalDep[];
-    /**
-     * 基础路径（可选）
-     * 影响 importMapFile、相对 URL 等解析
-     * @example "./" | "/static/cic/" | "https://cdn.example.com/cic/"
-     */
-    baseURL?: string;
-    /**
-     * 预加载模块（可选）
-     * @example ["vue","vue-router"]
-     */
-    preload?: string[];
-    /**
-     * 模块别名（可选）
-     * @example { "@/": "./src/", "@components/": "./src/components/" }
-     */
-    alias?: Record<string, string>;
-    /**
-     * 降级策略（可选）
-     *
-     * 当 strategy=hybrid 且 importmap 解析/加载失败时的兜底方案。
-     * @example { "strategy": "global", "mapping": { "vue": "window.Vue" } }
-     */
-    fallback?: ModuleFallback;
-}
-/**
- * Import Map 配置
- */
-export interface ImportMap {
-    /**
-     * 模块映射
-     */
-    imports: Record<string, string>;
-    /**
-     * 作用域映射（可选）
-     */
-    scopes?: Record<string, Record<string, string>>;
-}
-/**
- * 外部依赖声明
- */
-export interface ExternalDep {
-    /**
-     * 模块 ID
-     * @example "vue" | "@arco-design/web-vue"
-     */
-    id: string;
-    /**
-     * 提供方式
-     * - global: 全局变量
-     * - import: 通过 importmap
-     * - cdn: CDN 加载
-     */
-    provide: 'global' | 'import' | 'cdn';
-    /**
-     * 全局变量路径（provide 为 global 时）
-     * @example "window.Vue" | "wx" | "globalThis.echarts"
-     */
-    global?: string;
-    /**
-     * CDN URL（provide 为 cdn 时）
-     * @example "https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"
-     */
-    url?: string;
-    /**
-     * 版本约束（可选）
-     * @example "^3.0.0"
-     */
-    version?: string;
-    /**
-     * 是否必需（可选）
-     * @default true
-     */
-    required?: boolean;
-    /**
-     * 可用性校验（可选）
-     * 用于判断 global/cdn 是否已就绪
-     * @example "typeof window.Vue !== 'undefined'"
-     */
-    checkScript?: string;
-    /**
-     * 依赖项（可选）
-     *
-     * 说明：这里用于表达“加载顺序/前置条件”，不是 CICConfig.deps 的替代品。
-     * @example ["vue"]
-     */
-    dependencies?: string[];
-}
-/**
- * 模块降级配置
- */
-export interface ModuleFallback {
-    /**
-     * 兜底策略
-     * - global: 从全局变量读取
-     * - cdn: 走备用 CDN
-     */
-    strategy: 'global' | 'cdn';
-    /**
-     * 映射：模块 id -> 全局路径或 CDN 相对路径
-     * @example { "vue": "window.Vue" }
-     */
-    mapping?: Record<string, string>;
-    /**
-     * CDN 基础路径（strategy=cdn 时可用）
-     * @example "https://backup-cdn.example.com/libs/"
-     */
-    cdnBase?: string;
-}
-/**
- * 组件配置
- */
-export interface ComponentConfig {
-    /**
-     * 默认策略（可选）
-     * - global: 全局注册
-     * - local: 局部注册
-     * - lazy: 懒加载
-     * @default "global"
-     */
-    strategy?: 'global' | 'local' | 'lazy';
-    /**
-     * 组件适配器
-     * 为特定组件定义加载规则
-     */
-    adapters?: ComponentAdapter[];
-    /**
-     * 全局注册前缀（可选）
-     * @example "Cic"
-     */
-    prefix?: string;
-    /**
-     * 命名规则（可选）
-     * @example "kebab-case" | "PascalCase" | "camelCase"
-     */
-    naming?: 'kebab-case' | 'PascalCase' | 'camelCase' | string;
-    /**
-     * 简易注册表（可选）
-     *
-     * 组件名 -> 模块 id/路径
-     * @example { "ECharts": "@anov/charts", "DataTable": "@anov/components" }
-     */
-    registry?: Record<string, string>;
-}
-/**
- * 组件适配器
- */
-export interface ComponentAdapter {
-    /**
-     * 匹配模式
-     * 支持通配符
-     * @example "echarts" | "@arco-design/*" | "*"
-     */
-    match: string;
-    /**
-     * 适配器类型
-     * - plugin: Vue/React 插件（install/use）
-     * - component: 单个组件
-     * - module: 需要初始化的模块（init 等）
-     * - global: 全局对象（window.echarts 等）
-     */
-    kind: 'plugin' | 'component' | 'module' | 'global';
-    /**
-     * 注册配置（可选）
-     *
-     * 用于解决不同组件库/组件需要不同调用方式的问题：
-     * - install/use：插件注册
-     * - init：模块初始化
-     * - register：自定义注册
-     */
-    register?: {
-        /**
-         * 注册方法
-         * @example "install" | "use" | "init" | "register"
-         */
-        method?: string;
-        /**
-         * 注册目标
-         * @example "app" | "Vue" | "window"
-         */
-        target?: string;
-        /**
-         * 初始化参数
-         */
-        options?: Record<string, any>;
-    };
-    /**
-     * 是否必需（可选）
-     * @default true
-     */
-    required?: boolean;
-    /**
-     * 依赖项（可选）
-     *
-     * 说明：这里的 dependencies 仅用于表达“组件注册/初始化”的前置依赖（顺序/就绪条件），
-     * 不是 CICConfig.deps 的替代品。
-     * @example ["vue"]
-     */
-    dependencies?: string[];
-    /**
-     * 是否异步（可选）
-     * @default false
-     */
-    async?: boolean;
-    /**
-     * 组件实例初始化（可选）
-     *
-     * 场景：某些组件在渲染后默认隐藏，需要对组件“实例”主动调用 init 才会显示/运行。
-     *
-     * 前提（以 Vue3 为例）：组件需要通过 expose 暴露出 init 方法，运行时装配器通过 ref/proxy
-     * 拿到实例后执行调用。
-     */
-    instanceInit?: {
-        /**
-         * 触发时机
-         * - mounted: 组件挂载完成后
-         * - ready: 运行时认为实例可用时（框架自定义时机）
-         * @default "mounted"
-         */
-        when?: 'mounted' | 'ready';
-        /**
-         * 要调用的实例方法名
-         * @example "init"
-         */
-        method: string;
-        /**
-         * 初始化参数（可选）
-         */
-        options?: Record<string, any>;
-        /**
-         * 调用前的就绪判断（可选）
-         * @example "typeof instance.init === 'function'"
-         */
-        guard?: string;
-    };
-    /**
-     * 全局对象名称（kind=global 时可用）
-     * @example "echarts"
-     */
-    globalName?: string;
-}
-export interface ManifestExportConfig {
-    /**
-     * 导出 CIC Config 时，从 config.deps 中排除这些依赖 id
-     * @example ["vue","vue-router","pinia"]
-     */
-    excludeDeps?: string[];
-    /**
-     * 说明原因（可选）
-     * @example "由宿主统一注入"
-     */
-    reason?: string;
-}
-export declare const CICManifestExample: CICManifest;
-export declare const CICManifestMinimal: CICManifest;
-export declare const CICManifestReact: CICManifest;
-export declare const CICManifestMiniProgram: CICManifest;

package/dist/types/runtime.manifest.d.ts

@@ -1,265 +0,0 @@
-import type { CICManifest } from './cic.manifest';
-/**
- * runtime.manifest.d.ts
- *
- * runtime.manifest.json 的完整 TypeScript 类型定义。
- *
- * 对应概念：
- *   RuntimeManifest   —— 顶层结构（供给表）
- *   CICManifest       —— cic.manifest.json 的类型（需求表）
- *   ResolvedManifest  —— loader 完成匹配后写入 window.__MANIFEST__ 的结构
- */
-/** semver 版本字符串，如 "3.4.21" */
-type SemverString = string;
-/** semver 版本范围，如 "^3.0.0" "~1.2.0" "4.x" */
-type SemverRange = string;
-/** 相对或绝对 URL 路径 */
-type UrlPath = string;
-/** ES 模块 import specifier，如 "vue" "@anov/core" "cdn/button" */
-type ModuleSpecifier = string;
-/** window 上的属性路径，如 "Vue" "echarts" "MyLib.Core" */
-type WindowPath = string;
-/**
- * 脚本文件格式。
- * 决定 manifest-loader 用何种方式加载该文件：
- *   umd  → <script src>           执行后将自身挂到 window
- *   esm  → fetch + blob URL       或 importMap 直接映射
- */
-type BindingFormat = 'umd' | 'esm';
-/**
- * Global binding：将依赖以 UMD/IIFE 形式挂载到 window 上。
- *
- * 使用场景：
- *   - 应用代码通过 window.Vue / window.echarts 访问
- *   - 需要 shimB（global → esm）时作为 UMD 源
- */
-interface GlobalBinding {
-    /**
-     * 挂载到 window 上的属性路径。
-     * 支持链式路径，如 "MyLib.Core"（对应 window.MyLib.Core）。
-     */
-    window: WindowPath;
-    /**
-     * 开发模式下的脚本路径（本地文件系统或 devServer 路径）。
-     * runtime.engine.mode === 'development' 时使用。
-     */
-    src: UrlPath;
-    /**
-     * 生产模式下的脚本路径。
-     * runtime.engine.mode !== 'development' 时使用。
-     * null 表示生产模式由宿主环境注入，loader 不负责加载。
-     */
-    prodSrc?: UrlPath | null;
-    /**
-     * 文件格式。
-     * 未填时 loader 尝试从文件名猜测（.mjs/.esm → esm，其余 → umd）。
-     * 强烈建议显式声明，避免猜测错误。
-     */
-    format?: BindingFormat;
-}
-/**
- * ESM binding：将依赖注册到 importMap，供 import specifier 使用。
- *
- * 使用场景：
- *   - 应用代码通过 import { ref } from 'vue' 访问
- *   - importMap 直接映射 specifier → 物理文件路径
- */
-interface EsmBinding {
-    /**
-     * 注册到 importMap 的键名（import specifier）。
-     * 如 "vue"、"@anov/core"、"cdn/button"。
-     */
-    specifier: ModuleSpecifier;
-    /**
-     * 开发模式下的 ESM 文件路径。
-     */
-    src: UrlPath;
-    /**
-     * 生产模式下的 ESM 文件路径。
-     * null 表示生产模式由宿主的 importMap 提供，loader 不注册。
-     */
-    prodSrc?: UrlPath | null;
-    /**
-     * 文件格式，ESM binding 固定为 'esm'。
-     * 显式声明可避免 loader 误判。
-     */
-    format?: 'esm';
-}
-/**
- * 一个依赖可以同时提供 global 和 esm 两种 binding，
- * 也可以只提供其中一种。
- *
- * loader 会根据需求方（cic.external）声明的 consume 类型，
- * 选择合适的 binding，必要时自动插入 shim：
- *
- *   供给 global + 需求 esm  → shimB（global → esm data: URL）
- *   供给 esm   + 需求 global → shimA（import() 后挂到 window）
- */
-interface ProvideBindings {
-    global?: GlobalBinding;
-    esm?: EsmBinding;
-}
-/**
- * 依赖的导出接口声明。
- *
- * 主要用于 shimB 场景：当 global binding 需要被转换为 ESM 时，
- * loader 需要知道该库导出了哪些具名符号，才能生成完整的 shim 模块：
- *
- *   const __m = window['Vue']
- *   export default __m
- *   export const { ref, reactive, computed, ... } = __m  ← 来自 named
- *
- * 若 named 为空，shim 只有 default export，
- * import { ref } from 'vue' 将返回 undefined。
- */
-interface ExportsDeclaration {
-    /**
-     * 具名导出列表。
-     * shimB 场景下用于生成 export const { ... } = __m 语句。
-     */
-    named: string[];
-    /**
-     * 是否有 default export。
-     * true  → export default __m
-     * false → 无 default（如 pinia，只有具名导出）
-     */
-    default: boolean;
-}
-/**
- * runtime 能提供的一个依赖的完整描述。
- * provides 字典的值类型。
- */
-interface ProvideEntry {
-    /** 该依赖的实际版本号（具体版本，如 "3.4.21"）。用于与需求方的版本范围做校验。 */
-    version: SemverString;
-    /**
-     * 导出接口声明。
-     * shimB 场景必填，否则生成的 shim 模块缺少具名导出。
-     */
-    exports?: ExportsDeclaration;
-    /**
-     * 供给形态。至少声明一种：
-     *   只有 global → 只能满足 consume: 'global'，consume: 'esm' 需走 shimB
-     *   只有 esm    → 只能满足 consume: 'esm'，  consume: 'global' 需走 shimA
-     *   两种都有    → 直连满足所有需求，无需 shim（性能最优）
-     */
-    bindings: ProvideBindings;
-}
-/**
- * 标准 importMap 结构（W3C 规范子集）。
- * 目前只使用 imports，暂不支持 scopes。
- */
-interface ImportMap {
-    /**
-     * specifier → URL 的映射表。
-     * 支持路径前缀映射（键以 "/" 结尾），如 "cdn/" → "./anov-prod/mgt/ui/"。
-     */
-    imports: Record<ModuleSpecifier, UrlPath>;
-}
-type EnginePlatform = 'web' | 'electron' | 'miniapp';
-type EngineRuntime = 'vue3' | 'vue2' | 'react' | 'svelte';
-type EngineMode = 'development' | 'production' | 'staging';
-interface EngineDescriptor {
-    /** 运行平台 */
-    platform: EnginePlatform;
-    /** JS 框架运行时 */
-    runtime: EngineRuntime;
-    /** 框架版本范围（semver range） */
-    version: SemverRange;
-    /**
-     * 运行模式。
-     * loader 根据此字段决定使用 binding.src 还是 binding.prodSrc。
-     */
-    mode: EngineMode;
-    /**
-     * 开发服务器基础 URL。
-     * mode === 'development' 时有效，用于拼接相对路径的绝对地址。
-     */
-    baseURL?: string;
-}
-/**
- * 运行时环境变量表。
- * loader 将其展开到 window.__ENV__。
- * cic.manifest 中的同名字段会覆盖 runtime 的默认值。
- */
-type EnvRecord = Record<string, string | number | boolean>;
-/**
- * runtime.manifest.json 的完整结构。
- *
- * 定位：平台/运行时的"供给表"，描述运行环境能提供什么。
- * 与 cic.manifest.json（应用"需求表"）相对，由 manifest-loader 完成匹配。
- */
-export interface RuntimeManifest {
-    /**
-     * manifest 文件自身的版本号。
-     * 用于 loader 做格式兼容判断，遵循 semver。
-     */
-    version: SemverString;
-    /** 运行时引擎描述 */
-    engine: EngineDescriptor;
-    /**
-     * 依赖供给表。
-     * key 为依赖 id（通常与 npm 包名一致），value 为供给描述。
-     *
-     * @example
-     * {
-     *   "vue": { version: "3.4.21", bindings: { esm: { specifier: "vue", src: "..." } } },
-     *   "@anov/core": { ... }
-     * }
-     */
-    provides: Record<string, ProvideEntry>;
-    /**
-     * 基础 importMap。
-     * 通常用于声明路径前缀映射（如 "cdn/" → 本地路径），
-     * 不包含具体依赖的 specifier 映射（由 provides 动态生成）。
-     *
-     * 合并优先级（低 → 高）：
-     *   runtime.importMap < 供需匹配生成 < cic.modules.importMap
-     */
-    importMap?: ImportMap;
-    /**
-     * 运行时默认环境变量。
-     * cic.env 中的同名字段会覆盖此处的值。
-     */
-    env?: EnvRecord;
-    /**
-     * importMap 注入后需要预加载的模块路径列表。
-     *
-     * ⚠️  不能写在 HTML 的 <link rel="modulepreload"> 里，原因：
-     *     HTML 解析阶段触发 modulepreload 时 importMap 尚未存在，
-     *     模块图中的 specifier 无法映射，导致解析失败。
-     *     由 loader 在 importMap 注入后动态插入，才能保证正确解析。
-     *
-     * 通常包含运行时核心的 vendor chunk、libs chunk 和入口 chunk。
-     */
-    preload?: UrlPath[];
-    /**
-     * 默认应用入口模块路径。
-     * 若 cic.entry 未声明，loader 使用此值作为 import() 的目标。
-     */
-    entry?: UrlPath;
-    /** 预留扩展字段，loader 不处理，原样透传到 window.__MANIFEST__.runtime */
-    extensions?: Record<string, unknown>;
-}
-/** manifest-loader 完成后写入 window.__MANIFEST__ 的结构 */
-export interface ResolvedManifest {
-    /** 原始 runtime.manifest 内容 */
-    runtime: RuntimeManifest;
-    /** 原始 cic.manifest 内容 */
-    cic: CICManifest;
-    /** 最终注入到页面的完整 importMap（三方合并结果） */
-    importMap: Record<ModuleSpecifier, UrlPath>;
-    /** 合并后的环境变量（runtime.env 被 cic.env 覆盖） */
-    env: EnvRecord;
-}
-declare global {
-    interface Window {
-        /** loader 完成后可 await 的 Promise，resolve 值为 ResolvedManifest */
-        __manifestReady: Promise<ResolvedManifest>;
-        /** loader 完成后写入的完整解析结果 */
-        __MANIFEST__: ResolvedManifest;
-        /** 合并后的环境变量，等同于 __MANIFEST__.env */
-        __ENV__: EnvRecord;
-    }
-}
-export {};