@hyacine/helper 0.0.1

package/src/runtime.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Runtime API for Hyacine Plugin System
+ *
+ * This module provides runtime utilities that are available to runtime-only plugins.
+ * The actual implementation is generated by the plugin system at build time.
+ *
+ * Usage in runtime-only plugins:
+ * ```typescript
+ * import { getInjectPointSelector } from '@hyacine/helper/runtime';
+ *
+ * export function init(options: Record<string, unknown>) {
+ *   const selector = getInjectPointSelector('footer');
+ *   const element = document.querySelector(selector);
+ *   console.log('Plugin initialized with options:', options);
+ *   // ...
+ * }
+ * ```
+ */
+/**
+ * Runtime-only 插件的 init 函数类型签名
+ * @param options - 从编译时传递到运行时的配置选项，由插件系统在生成时序列化
+ */
+export type PluginInitFunction<O> = (options: O) => void;
+
+/**
+ * 获取注入点对应的 CSS 选择器
+ * @param injectPoint - 注入点名称
+ * @returns CSS 选择器字符串
+ * @throws {Error} 如果映射表中不包含该 injectPoint
+ */
+export declare function getInjectPointSelector(injectPoint: string): string;
+
+/**
+ * Script 标签配置选项
+ */
+export interface ScriptOptions {
+  /**
+   * script 标签的 src 属性（外部脚本）
+   */
+  src?: string;
+  /**
+   * script 标签的内联内容（内联脚本）
+   */
+  content?: string;
+  /**
+   * script 标签的类型，默认为 "text/javascript"
+   */
+  type?: string;
+  /**
+   * 是否异步加载脚本
+   */
+  async?: boolean;
+  /**
+   * 是否延迟加载脚本
+   */
+  defer?: boolean;
+  /**
+   * 跨域设置
+   */
+  crossOrigin?: "anonymous" | "use-credentials";
+  /**
+   * 脚本的完整性校验值（Subresource Integrity）
+   */
+  integrity?: string;
+  /**
+   * 其他自定义属性
+   */
+  attributes?: Record<string, string>;
+}
+
+/**
+ * Link CSS 标签配置选项
+ */
+export interface LinkCSSOptions {
+  /**
+   * link 标签的 href 属性（CSS 文件路径）
+   */
+  href: string;
+  /**
+   * 跨域设置
+   */
+  crossOrigin?: "anonymous" | "use-credentials";
+  /**
+   * 资源的完整性校验值（Subresource Integrity）
+   */
+  integrity?: string;
+  /**
+   * 媒体查询条件
+   */
+  media?: string;
+  /**
+   * 其他自定义属性
+   */
+  attributes?: Record<string, string>;
+}
+
+/**
+ * 向 head 或 body 注入 script 标签
+ *
+ * @param options - Script 标签配置选项
+ * @param target - 注入目标，默认为 'head'
+ * @returns 创建的 script 元素
+ * @throws {Error} 如果既没有提供 src 也没有提供 content
+ *
+ * @example
+ * ```typescript
+ * // 注入外部脚本到 head
+ * injectScript({
+ *   src: 'https://example.com/script.js',
+ *   async: true
+ * });
+ *
+ * // 注入内联脚本到 body
+ * injectScript({
+ *   content: 'console.log("Hello from inline script");'
+ * }, 'body');
+ *
+ * // 注入带有完整性校验的外部脚本
+ * injectScript({
+ *   src: 'https://cdn.example.com/library.js',
+ *   integrity: 'sha384-xxx',
+ *   crossOrigin: 'anonymous'
+ * });
+ * ```
+ */
+export declare function injectScript(
+  options: ScriptOptions,
+  target?: "head" | "body",
+): HTMLScriptElement;
+
+/**
+ * 向 head 注入 link CSS 标签
+ *
+ * @param options - Link CSS 标签配置选项
+ * @returns 创建的 link 元素
+ *
+ * @example
+ * ```typescript
+ * // 注入外部 CSS
+ * injectLinkCSS({
+ *   href: 'https://example.com/style.css'
+ * });
+ *
+ * // 注入带有媒体查询的 CSS
+ * injectLinkCSS({
+ *   href: '/mobile.css',
+ *   media: '(max-width: 768px)'
+ * });
+ *
+ * // 注入带有完整性校验的 CSS
+ * injectLinkCSS({
+ *   href: 'https://cdn.example.com/library.css',
+ *   integrity: 'sha384-xxx',
+ *   crossOrigin: 'anonymous'
+ * });
+ * ```
+ */
+export declare function injectLinkCSS(options: LinkCSSOptions): HTMLLinkElement;

package/src/runtime.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Integration tests for runtime API
+ *
+ * This file ensures that the runtime module correctly re-exports
+ * all functionality from its sub-modules.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { PluginInitFunction } from "./runtime";
+import { getInjectPointSelector, injectLinkCSS, injectScript } from "./runtime";
+
+describe("Runtime API re-exports", () => {
+  test("应该正确导出 PluginInitFunction 类型", () => {
+    // 类型测试 - 确保类型可以正常使用
+    const validInit: PluginInitFunction = (options) => {
+      console.log(options);
+    };
+    expect(typeof validInit).toBe("function");
+  });
+
+  test("应该正确导出 getInjectPointSelector", () => {
+    expect(typeof getInjectPointSelector).toBe("function");
+    expect(getInjectPointSelector.name).toBe("getInjectPointSelector");
+  });
+
+  test("应该正确导出 injectScript", () => {
+    expect(typeof injectScript).toBe("function");
+    expect(injectScript.name).toBe("injectScript");
+  });
+
+  test("应该正确导出 injectLinkCSS", () => {
+    expect(typeof injectLinkCSS).toBe("function");
+    expect(injectLinkCSS.name).toBe("injectLinkCSS");
+  });
+});

package/src/runtime.ts

@@ -0,0 +1,20 @@
+/**
+ * Runtime API for Hyacine Plugin System
+ *
+ * This module provides runtime utilities that are available to runtime-only plugins.
+ *
+ * Note: In production, these functions will use the global inject points map
+ * that is initialized by the generated runtime file.
+ */
+
+/**
+ * Runtime-only 插件的 init 函数类型签名
+ * @param options - 从编译时传递到运行时的配置选项,由插件系统在生成时序列化
+ */
+export type PluginInitFunction<O = Record<string, unknown>> = (options: O) => void;
+
+// Re-export inject point API
+export { getInjectPointSelector } from "./inject-point";
+
+// Re-export DOM injection API
+export { injectLinkCSS, injectScript, type LinkCSSOptions, type ScriptOptions } from "./dom-inject";