@pikacss/integration 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 DevilTea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# @pikacss/integration

package/dist/index.cjs

@@ -0,0 +1,402 @@
+'use strict';
+
+const node_fs = require('node:fs');
+const promises = require('node:fs/promises');
+const core = require('@pikacss/core');
+const jiti = require('jiti');
+const localPkg = require('local-pkg');
+const MagicString = require('magic-string');
+const micromatch = require('micromatch');
+const pathe = require('pathe');
+const prettier = require('prettier');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
+
+function _interopNamespaceCompat(e) {
+	if (e && typeof e === 'object' && 'default' in e) return e;
+	const n = Object.create(null);
+	if (e) {
+		for (const k in e) {
+			n[k] = e[k];
+		}
+	}
+	n.default = e;
+	return n;
+}
+
+const MagicString__default = /*#__PURE__*/_interopDefaultCompat(MagicString);
+const micromatch__default = /*#__PURE__*/_interopDefaultCompat(micromatch);
+const prettier__namespace = /*#__PURE__*/_interopNamespaceCompat(prettier);
+
+function createEventHook() {
+  const listeners = /* @__PURE__ */ new Set();
+  function trigger(payload) {
+    listeners.forEach((listener) => listener(payload));
+  }
+  function off(listener) {
+    listeners.delete(listener);
+  }
+  function on(listener) {
+    listeners.add(listener);
+    const offListener = () => off(listener);
+    return offListener;
+  }
+  return {
+    listeners,
+    trigger,
+    on,
+    off
+  };
+}
+
+function formatUnionStringType(list) {
+  return list.length > 0 ? list.map((i) => typeof i === "number" ? i : `'${i}'`).join(" | ") : "never";
+}
+function generateAutocomplete(ctx) {
+  const autocomplete = ctx.engine.config.autocomplete;
+  return [
+    "export interface Autocomplete extends _Autocomplete {",
+    `  Selector: ${formatUnionStringType([...autocomplete.selectors])}`,
+    `  StyleItemString: ${formatUnionStringType([...autocomplete.styleItemStrings])}`,
+    `  ExtraProperty: ${formatUnionStringType([...autocomplete.extraProperties])}`,
+    `  ExtraCssProperty: ${formatUnionStringType([...autocomplete.extraCssProperties])}`,
+    `  PropertiesValue: { ${Array.from(autocomplete.properties.entries(), ([k, v]) => `'${k}': ${v.join(" | ")}`).join(",")} }`,
+    `  CssPropertiesValue: { ${Array.from(autocomplete.cssProperties.entries(), ([k, v]) => `'${k}': ${formatUnionStringType(v)}`).join(",")} }`,
+    "}",
+    ""
+  ];
+}
+function generateStyleFn(ctx) {
+  const { transformedFormat } = ctx;
+  const lines = [
+    "type StyleFn_Array = (...params: StyleItem<Autocomplete>[]) => string[]",
+    "type StyleFn_String = (...params: StyleItem<Autocomplete>[]) => string",
+    "type StyleFn_Inline = (...params: StyleItem<Autocomplete>[]) => void"
+  ];
+  if (transformedFormat === "array")
+    lines.push("type StyleFn_Normal = StyleFn_Array");
+  else if (transformedFormat === "string")
+    lines.push("type StyleFn_Normal = StyleFn_String");
+  else if (transformedFormat === "inline")
+    lines.push("type StyleFn_Normal = StyleFn_Inline");
+  lines.push(
+    "type StyleFn = StyleFn_Normal & {",
+    "  str: StyleFn_String",
+    "  arr: StyleFn_Array",
+    "  inl: StyleFn_Inline",
+    "}",
+    `type StyleFnWithPreview = PreviewOverloads<StyleFn_Normal>['fn'] & {`,
+    `  str: PreviewOverloads<StyleFn_String>['fn']`,
+    `  arr: PreviewOverloads<StyleFn_Array>['fn']`,
+    `  inl: PreviewOverloads<StyleFn_Inline>['fn']`,
+    "}",
+    ""
+  );
+  return lines;
+}
+function generateGlobalDeclaration(ctx) {
+  const { fnName } = ctx;
+  return [
+    "declare global {",
+    "  /**",
+    "   * PikaCSS",
+    "   */",
+    `  const ${fnName}: StyleFn`,
+    "",
+    "  /**",
+    "   * PikaCSS Preview",
+    "   */",
+    `  const ${fnName}p: StyleFnWithPreview`,
+    "}",
+    ""
+  ];
+}
+function generateVueDeclaration(ctx) {
+  const { hasVue, fnName } = ctx;
+  if (!hasVue)
+    return [];
+  return [
+    "declare module 'vue' {",
+    "  interface ComponentCustomProperties {",
+    "    /**",
+    "     * PikaCSS",
+    "     */",
+    `    ${fnName}: StyleFn`,
+    "",
+    "    /**",
+    "     * PikaCSS Preview",
+    "     */",
+    `    ${fnName}p: StyleFnWithPreview`,
+    "  }",
+    "}",
+    ""
+  ];
+}
+async function generateOverloadContent(ctx) {
+  const paramsLines = [];
+  const fnsLines = [];
+  const usages = [...ctx.usages.values()].flat();
+  for (let i = 0; i < usages.length; i++) {
+    const usage = usages[i];
+    try {
+      const addedParamsLines = usage.params.map((param, index) => `type P${i}_${index} = ${JSON.stringify(param)}`);
+      const addedFnLines = [
+        "  /**",
+        "   * ### PikaCSS Preview",
+        "   * ```css",
+        // CSS Lines
+        ...(await prettier__namespace.format(await ctx.engine.renderPreviewStyles(...usage.params), { parser: "css" })).split("\n").map((line) => `   * \u200E${line.replace(/^(\s*)/, "$1\u200E")}`),
+        "   * ```",
+        "   */",
+        `  fn(...params: [${usage.params.map((_, index) => `p${index}: P${i}_${index}`).join(", ")}]): ReturnType<StyleFn>`
+      ];
+      paramsLines.push(...addedParamsLines);
+      fnsLines.push(...addedFnLines);
+    } catch {
+    }
+  }
+  return [
+    "interface PreviewOverloads<StyleFn extends (StyleFn_Array | StyleFn_String | StyleFn_Inline)> {",
+    ...fnsLines,
+    "  /**",
+    "   * PikaCSS Preview",
+    "   * Save the current file to see the preview.",
+    "   */",
+    `  fn(...params: Parameters<StyleFn>): ReturnType<StyleFn>`,
+    "}",
+    ...paramsLines
+  ];
+}
+async function generateTsCodegenContent(ctx) {
+  const lines = [
+    `// Auto-generated by ${ctx.currentPackageName}`,
+    `import type { Autocomplete as _Autocomplete, StyleItem } from '${ctx.currentPackageName}'`,
+    `import { createDefineEngineConfigFn } from '${ctx.currentPackageName}'`,
+    ""
+  ];
+  lines.push(...generateAutocomplete(ctx));
+  lines.push(
+    "export const defineEngineConfig: ReturnType<typeof createDefineEngineConfigFn<Autocomplete>> = createDefineEngineConfigFn<Autocomplete>()",
+    ""
+  );
+  lines.push(...generateStyleFn(ctx));
+  lines.push(...generateGlobalDeclaration(ctx));
+  lines.push(...generateVueDeclaration(ctx));
+  lines.push(...await generateOverloadContent(ctx));
+  return lines.join("\n");
+}
+
+function findFunctionCalls(code, RE) {
+  const result = [];
+  let matched = RE.exec(code);
+  while (matched != null) {
+    const fnName = matched[1];
+    const start = matched.index;
+    let end = start + fnName.length;
+    let depth = 1;
+    let inString = false;
+    while (depth > 0) {
+      end++;
+      if (inString === false && code[end] === "(")
+        depth++;
+      else if (inString === false && code[end] === ")")
+        depth--;
+      else if (inString === false && (code[end] === "'" || code[end] === '"'))
+        inString = code[end];
+      else if (inString === code[end])
+        inString = false;
+    }
+    const snippet = code.slice(start, end + 1);
+    result.push({ fnName, start, end, snippet });
+    matched = RE.exec(code);
+  }
+  return result;
+}
+const ESCAPE_REPLACE_RE = /[.*+?^${}()|[\]\\/]/g;
+function createFnUtils(fnName) {
+  const available = {
+    normal: /* @__PURE__ */ new Set([fnName]),
+    forceString: /* @__PURE__ */ new Set([`${fnName}.str`, `${fnName}['str']`, `${fnName}["str"]`, `${fnName}[\`str\`]`]),
+    forceArray: /* @__PURE__ */ new Set([`${fnName}.arr`, `${fnName}['arr']`, `${fnName}["arr"]`, `${fnName}[\`arr\`]`]),
+    forceInline: /* @__PURE__ */ new Set([`${fnName}.inl`, `${fnName}['inl']`, `${fnName}["inl"]`, `${fnName}[\`inl\`]`]),
+    // preview
+    normalPreview: /* @__PURE__ */ new Set([`${fnName}p`]),
+    forceStringPreview: /* @__PURE__ */ new Set([`${fnName}p.str`, `${fnName}p['str']`, `${fnName}p["str"]`, `${fnName}p[\`str\`]`]),
+    forceArrayPreview: /* @__PURE__ */ new Set([`${fnName}p.arr`, `${fnName}p['arr']`, `${fnName}p["arr"]`, `${fnName}p[\`arr\`]`]),
+    forceInlinePreview: /* @__PURE__ */ new Set([`${fnName}p.inl`, `${fnName}p['inl']`, `${fnName}p["inl"]`, `${fnName}p[\`inl\`]`])
+  };
+  const RE = new RegExp(`\\b(${Object.values(available).flatMap((s) => [...s].map((f) => `(${f.replace(ESCAPE_REPLACE_RE, "\\$&")})`)).join("|")})\\(`, "g");
+  return {
+    isNormal: (fnName2) => available.normal.has(fnName2) || available.normalPreview.has(fnName2),
+    isForceString: (fnName2) => available.forceString.has(fnName2) || available.forceStringPreview.has(fnName2),
+    isForceArray: (fnName2) => available.forceArray.has(fnName2) || available.forceArrayPreview.has(fnName2),
+    isForceInline: (fnName2) => available.forceInline.has(fnName2) || available.forceInlinePreview.has(fnName2),
+    isPreview: (fnName2) => available.normalPreview.has(fnName2) || available.forceStringPreview.has(fnName2) || available.forceArrayPreview.has(fnName2) || available.forceInlinePreview.has(fnName2),
+    RE
+  };
+}
+async function createCtx(options) {
+  const {
+    cwd,
+    currentPackageName,
+    target,
+    configOrPath,
+    fnName,
+    transformedFormat,
+    tsCodegen,
+    devCss
+  } = options;
+  const devCssFilepath = pathe.isAbsolute(devCss) ? pathe.resolve(devCss) : pathe.join(cwd, devCss);
+  const tsCodegenFilepath = tsCodegen === false ? null : pathe.isAbsolute(tsCodegen) ? pathe.resolve(tsCodegen) : pathe.join(cwd, tsCodegen);
+  const inlineConfig = typeof configOrPath === "object" ? configOrPath : null;
+  const specificConfigPath = typeof configOrPath === "string" ? pathe.isAbsolute(configOrPath) ? configOrPath : pathe.join(cwd, configOrPath) : null;
+  const configSources = [
+    ...specificConfigPath == null ? [] : [specificConfigPath],
+    ...["pika", "pikacss"].flatMap((name) => ["js", "ts", "cjs", "cts", "mjs", "mts"].map((ext) => `${name}.config.${ext}`)).map((name) => pathe.join(cwd, name))
+  ];
+  const targetREs = target.map((t) => micromatch__default.makeRe(t));
+  const needToTransform = (id) => targetREs.some((re) => re.test(id));
+  const ctx = {
+    cwd,
+    currentPackageName,
+    fnName,
+    fnUtils: createFnUtils(fnName),
+    transformedFormat,
+    devCssFilepath,
+    tsCodegenFilepath,
+    hasVue: localPkg.isPackageExists("vue", { paths: [cwd] }),
+    usages: /* @__PURE__ */ new Map(),
+    hooks: {
+      styleUpdated: createEventHook(),
+      tsCodegenUpdated: createEventHook()
+    },
+    loadConfig: async () => {
+      if (inlineConfig != null)
+        return { config: inlineConfig, file: null };
+      const resolvedConfigPath = configSources.find((path) => {
+        const stat = node_fs.statSync(path, { throwIfNoEntry: false });
+        return stat != null && stat.isFile();
+      });
+      if (resolvedConfigPath == null)
+        return { config: null, file: null };
+      const jiti$1 = jiti.createJiti(cwd, {
+        fsCache: false,
+        moduleCache: false
+      });
+      const config = await jiti$1.import(resolvedConfigPath, { default: true });
+      return { config, file: resolvedConfigPath };
+    },
+    init: async () => {
+      ctx.isReady = false;
+      await promises.mkdir(pathe.dirname(devCssFilepath), { recursive: true }).catch(() => {
+      });
+      await promises.writeFile(devCssFilepath, "");
+      if (tsCodegenFilepath != null) {
+        await promises.mkdir(pathe.dirname(tsCodegenFilepath), { recursive: true }).catch(() => {
+        });
+        await promises.writeFile(tsCodegenFilepath, "export function defineEngineConfig(config: any) { return config }");
+      }
+      ctx.usages.clear();
+      const { config, file } = await ctx.loadConfig().catch((error) => {
+        console.warn(`[${ctx.currentPackageName}] Failed to load config file: ${error}`);
+        return { config: null, file: null };
+      });
+      ctx.resolvedConfigPath = file;
+      ctx.engine = await core.createEngine(config ?? {});
+      ctx.engine.config.plugins.unshift({
+        name: "@pikacss/integration:dev",
+        preflightUpdated: () => ctx.hooks.styleUpdated.trigger(),
+        atomicRuleAdded: () => ctx.hooks.styleUpdated.trigger(),
+        autocompleteConfigUpdated: () => ctx.hooks.tsCodegenUpdated.trigger()
+      });
+      ctx.isReady = true;
+    },
+    isReady: false,
+    configSources,
+    resolvedConfigPath: null,
+    engine: null,
+    transform: async (code, id) => {
+      if (ctx.isReady === false || !needToTransform(id)) {
+        return;
+      }
+      ctx.usages.delete(id);
+      const functionCalls = findFunctionCalls(code, ctx.fnUtils.RE);
+      if (functionCalls.length === 0)
+        return;
+      const usages = [];
+      ctx.usages.set(id, usages);
+      const transformed = new MagicString__default(code);
+      for (const fnCall of functionCalls) {
+        const functionCallStr = fnCall.snippet;
+        const argsStr = `[${functionCallStr.slice(fnCall.fnName.length + 1, -1)}]`;
+        const args = new Function(`return ${argsStr}`)();
+        const usage = {
+          params: args
+        };
+        usages.push(usage);
+        const names = await ctx.engine.use(...args);
+        ctx.hooks.tsCodegenUpdated.trigger();
+        let transformedContent;
+        if (ctx.fnUtils.isNormal(fnCall.fnName)) {
+          transformedContent = ctx.transformedFormat === "array" ? `[${names.map((n) => `'${n}'`).join(", ")}]` : ctx.transformedFormat === "string" ? `'${names.join(" ")}'` : names.join(" ");
+        } else if (ctx.fnUtils.isForceString(fnCall.fnName)) {
+          transformedContent = `'${names.join(" ")}'`;
+        } else if (ctx.fnUtils.isForceArray(fnCall.fnName)) {
+          transformedContent = `[${names.map((n) => `'${n}'`).join(", ")}]`;
+        } else if (ctx.fnUtils.isForceInline(fnCall.fnName)) {
+          transformedContent = names.join(" ");
+        } else {
+          throw new Error(`Unexpected function name: ${fnCall.fnName}`);
+        }
+        transformed.update(fnCall.start, fnCall.end + 1, transformedContent);
+      }
+      return {
+        code: transformed.toString(),
+        map: transformed.generateMap({ hires: true })
+      };
+    },
+    writeDevCssFile: async () => {
+      if (ctx.isReady === false)
+        return;
+      let rawCss = "";
+      let css = "";
+      try {
+        rawCss = ctx.engine.renderStyles();
+        css = await prettier__namespace.format([
+          `/* Auto-generated by ${ctx.currentPackageName} */`,
+          rawCss
+        ].join("\n"), { parser: "css" });
+      } catch (error) {
+        console.warn(`[${ctx.currentPackageName}] Failed to generate CSS: ${ctx.devCssFilepath}`);
+        css = [
+          `/* ${error.message.split("\n")[0]}`,
+          "",
+          rawCss,
+          "",
+          "*/"
+        ].join("\n");
+      }
+      await promises.writeFile(ctx.devCssFilepath, css);
+    },
+    writeTsCodegenFile: async () => {
+      if (ctx.isReady === false || ctx.tsCodegenFilepath == null)
+        return;
+      const content = await generateTsCodegenContent(ctx);
+      await promises.writeFile(ctx.tsCodegenFilepath, content);
+    }
+  };
+  await ctx.init();
+  return ctx;
+}
+
+exports.createCtx = createCtx;
+Object.prototype.hasOwnProperty.call(core, '__proto__') &&
+	!Object.prototype.hasOwnProperty.call(exports, '__proto__') &&
+	Object.defineProperty(exports, '__proto__', {
+		enumerable: true,
+		value: core['__proto__']
+	});
+
+Object.keys(core).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) exports[k] = core[k];
+});

package/dist/index.d.cts

@@ -0,0 +1,74 @@
+import { EngineConfig, Engine } from '@pikacss/core';
+export * from '@pikacss/core';
+import { SourceMap } from 'magic-string';
+
+type EventHookListener<EventPayload> = (payload: EventPayload) => void | Promise<void>;
+interface EventHook<EventPayload> {
+    listeners: Set<EventHookListener<EventPayload>>;
+    trigger: (payload: EventPayload) => void;
+    on: (listener: EventHookListener<EventPayload>) => () => void;
+    off: (listener: EventHookListener<EventPayload>) => void;
+}
+declare function createEventHook<EventPayload>(): EventHook<EventPayload>;
+
+interface UsageRecord {
+    params: Parameters<Engine['use']>;
+}
+interface FnUtils {
+    isNormal: (fnName: string) => boolean;
+    isForceString: (fnName: string) => boolean;
+    isForceArray: (fnName: string) => boolean;
+    isForceInline: (fnName: string) => boolean;
+    isPreview: (fnName: string) => boolean;
+    RE: RegExp;
+}
+interface IntegrationContext {
+    cwd: string;
+    currentPackageName: string;
+    fnName: string;
+    fnUtils: FnUtils;
+    transformedFormat: 'string' | 'array' | 'inline';
+    devCssFilepath: string;
+    tsCodegenFilepath: string | null;
+    hasVue: boolean;
+    usages: Map<string, UsageRecord[]>;
+    hooks: {
+        styleUpdated: ReturnType<typeof createEventHook<void>>;
+        tsCodegenUpdated: ReturnType<typeof createEventHook<void>>;
+    };
+    loadConfig: () => Promise<{
+        config: EngineConfig;
+        file: null;
+    } | {
+        config: null;
+        file: null;
+    } | {
+        config: EngineConfig;
+        file: string;
+    }>;
+    init: () => Promise<any>;
+    isReady: boolean;
+    configSources: string[];
+    resolvedConfigPath: string | null;
+    engine: Engine;
+    transform: (code: string, id: string) => Promise<{
+        code: string;
+        map: SourceMap;
+    } | undefined>;
+    writeDevCssFile: () => Promise<void>;
+    writeTsCodegenFile: () => Promise<void>;
+}
+interface IntegrationContextOptions {
+    cwd: string;
+    currentPackageName: string;
+    target: string[];
+    configOrPath: EngineConfig | string | null | undefined;
+    fnName: string;
+    transformedFormat: 'string' | 'array' | 'inline';
+    tsCodegen: false | string;
+    devCss: string;
+}
+
+declare function createCtx(options: IntegrationContextOptions): Promise<IntegrationContext>;
+
+export { type FnUtils, type IntegrationContext, type IntegrationContextOptions, type UsageRecord, createCtx };

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+import { EngineConfig, Engine } from '@pikacss/core';
+export * from '@pikacss/core';
+import { SourceMap } from 'magic-string';
+
+type EventHookListener<EventPayload> = (payload: EventPayload) => void | Promise<void>;
+interface EventHook<EventPayload> {
+    listeners: Set<EventHookListener<EventPayload>>;
+    trigger: (payload: EventPayload) => void;
+    on: (listener: EventHookListener<EventPayload>) => () => void;
+    off: (listener: EventHookListener<EventPayload>) => void;
+}
+declare function createEventHook<EventPayload>(): EventHook<EventPayload>;
+
+interface UsageRecord {
+    params: Parameters<Engine['use']>;
+}
+interface FnUtils {
+    isNormal: (fnName: string) => boolean;
+    isForceString: (fnName: string) => boolean;
+    isForceArray: (fnName: string) => boolean;
+    isForceInline: (fnName: string) => boolean;
+    isPreview: (fnName: string) => boolean;
+    RE: RegExp;
+}
+interface IntegrationContext {
+    cwd: string;
+    currentPackageName: string;
+    fnName: string;
+    fnUtils: FnUtils;
+    transformedFormat: 'string' | 'array' | 'inline';
+    devCssFilepath: string;
+    tsCodegenFilepath: string | null;
+    hasVue: boolean;
+    usages: Map<string, UsageRecord[]>;
+    hooks: {
+        styleUpdated: ReturnType<typeof createEventHook<void>>;
+        tsCodegenUpdated: ReturnType<typeof createEventHook<void>>;
+    };
+    loadConfig: () => Promise<{
+        config: EngineConfig;
+        file: null;
+    } | {
+        config: null;
+        file: null;
+    } | {
+        config: EngineConfig;
+        file: string;
+    }>;
+    init: () => Promise<any>;
+    isReady: boolean;
+    configSources: string[];
+    resolvedConfigPath: string | null;
+    engine: Engine;
+    transform: (code: string, id: string) => Promise<{
+        code: string;
+        map: SourceMap;
+    } | undefined>;
+    writeDevCssFile: () => Promise<void>;
+    writeTsCodegenFile: () => Promise<void>;
+}
+interface IntegrationContextOptions {
+    cwd: string;
+    currentPackageName: string;
+    target: string[];
+    configOrPath: EngineConfig | string | null | undefined;
+    fnName: string;
+    transformedFormat: 'string' | 'array' | 'inline';
+    tsCodegen: false | string;
+    devCss: string;
+}
+
+declare function createCtx(options: IntegrationContextOptions): Promise<IntegrationContext>;
+
+export { type FnUtils, type IntegrationContext, type IntegrationContextOptions, type UsageRecord, createCtx };

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { EngineConfig, Engine } from '@pikacss/core';
+export * from '@pikacss/core';
+import { SourceMap } from 'magic-string';
+
+type EventHookListener<EventPayload> = (payload: EventPayload) => void | Promise<void>;
+interface EventHook<EventPayload> {
+    listeners: Set<EventHookListener<EventPayload>>;
+    trigger: (payload: EventPayload) => void;
+    on: (listener: EventHookListener<EventPayload>) => () => void;
+    off: (listener: EventHookListener<EventPayload>) => void;
+}
+declare function createEventHook<EventPayload>(): EventHook<EventPayload>;
+
+interface UsageRecord {
+    params: Parameters<Engine['use']>;
+}
+interface FnUtils {
+    isNormal: (fnName: string) => boolean;
+    isForceString: (fnName: string) => boolean;
+    isForceArray: (fnName: string) => boolean;
+    isForceInline: (fnName: string) => boolean;
+    isPreview: (fnName: string) => boolean;
+    RE: RegExp;
+}
+interface IntegrationContext {
+    cwd: string;
+    currentPackageName: string;
+    fnName: string;
+    fnUtils: FnUtils;
+    transformedFormat: 'string' | 'array' | 'inline';
+    devCssFilepath: string;
+    tsCodegenFilepath: string | null;
+    hasVue: boolean;
+    usages: Map<string, UsageRecord[]>;
+    hooks: {
+        styleUpdated: ReturnType<typeof createEventHook<void>>;
+        tsCodegenUpdated: ReturnType<typeof createEventHook<void>>;
+    };
+    loadConfig: () => Promise<{
+        config: EngineConfig;
+        file: null;
+    } | {
+        config: null;
+        file: null;
+    } | {
+        config: EngineConfig;
+        file: string;
+    }>;
+    init: () => Promise<any>;
+    isReady: boolean;
+    configSources: string[];
+    resolvedConfigPath: string | null;
+    engine: Engine;
+    transform: (code: string, id: string) => Promise<{
+        code: string;
+        map: SourceMap;
+    } | undefined>;
+    writeDevCssFile: () => Promise<void>;
+    writeTsCodegenFile: () => Promise<void>;
+}
+interface IntegrationContextOptions {
+    cwd: string;
+    currentPackageName: string;
+    target: string[];
+    configOrPath: EngineConfig | string | null | undefined;
+    fnName: string;
+    transformedFormat: 'string' | 'array' | 'inline';
+    tsCodegen: false | string;
+    devCss: string;
+}
+
+declare function createCtx(options: IntegrationContextOptions): Promise<IntegrationContext>;
+
+export { type FnUtils, type IntegrationContext, type IntegrationContextOptions, type UsageRecord, createCtx };

package/dist/index.mjs

@@ -0,0 +1,373 @@
+import { statSync } from 'node:fs';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { createEngine } from '@pikacss/core';
+export * from '@pikacss/core';
+import { createJiti } from 'jiti';
+import { isPackageExists } from 'local-pkg';
+import MagicString from 'magic-string';
+import micromatch from 'micromatch';
+import { isAbsolute, resolve, join, dirname } from 'pathe';
+import * as prettier from 'prettier';
+
+function createEventHook() {
+  const listeners = /* @__PURE__ */ new Set();
+  function trigger(payload) {
+    listeners.forEach((listener) => listener(payload));
+  }
+  function off(listener) {
+    listeners.delete(listener);
+  }
+  function on(listener) {
+    listeners.add(listener);
+    const offListener = () => off(listener);
+    return offListener;
+  }
+  return {
+    listeners,
+    trigger,
+    on,
+    off
+  };
+}
+
+function formatUnionStringType(list) {
+  return list.length > 0 ? list.map((i) => typeof i === "number" ? i : `'${i}'`).join(" | ") : "never";
+}
+function generateAutocomplete(ctx) {
+  const autocomplete = ctx.engine.config.autocomplete;
+  return [
+    "export interface Autocomplete extends _Autocomplete {",
+    `  Selector: ${formatUnionStringType([...autocomplete.selectors])}`,
+    `  StyleItemString: ${formatUnionStringType([...autocomplete.styleItemStrings])}`,
+    `  ExtraProperty: ${formatUnionStringType([...autocomplete.extraProperties])}`,
+    `  ExtraCssProperty: ${formatUnionStringType([...autocomplete.extraCssProperties])}`,
+    `  PropertiesValue: { ${Array.from(autocomplete.properties.entries(), ([k, v]) => `'${k}': ${v.join(" | ")}`).join(",")} }`,
+    `  CssPropertiesValue: { ${Array.from(autocomplete.cssProperties.entries(), ([k, v]) => `'${k}': ${formatUnionStringType(v)}`).join(",")} }`,
+    "}",
+    ""
+  ];
+}
+function generateStyleFn(ctx) {
+  const { transformedFormat } = ctx;
+  const lines = [
+    "type StyleFn_Array = (...params: StyleItem<Autocomplete>[]) => string[]",
+    "type StyleFn_String = (...params: StyleItem<Autocomplete>[]) => string",
+    "type StyleFn_Inline = (...params: StyleItem<Autocomplete>[]) => void"
+  ];
+  if (transformedFormat === "array")
+    lines.push("type StyleFn_Normal = StyleFn_Array");
+  else if (transformedFormat === "string")
+    lines.push("type StyleFn_Normal = StyleFn_String");
+  else if (transformedFormat === "inline")
+    lines.push("type StyleFn_Normal = StyleFn_Inline");
+  lines.push(
+    "type StyleFn = StyleFn_Normal & {",
+    "  str: StyleFn_String",
+    "  arr: StyleFn_Array",
+    "  inl: StyleFn_Inline",
+    "}",
+    `type StyleFnWithPreview = PreviewOverloads<StyleFn_Normal>['fn'] & {`,
+    `  str: PreviewOverloads<StyleFn_String>['fn']`,
+    `  arr: PreviewOverloads<StyleFn_Array>['fn']`,
+    `  inl: PreviewOverloads<StyleFn_Inline>['fn']`,
+    "}",
+    ""
+  );
+  return lines;
+}
+function generateGlobalDeclaration(ctx) {
+  const { fnName } = ctx;
+  return [
+    "declare global {",
+    "  /**",
+    "   * PikaCSS",
+    "   */",
+    `  const ${fnName}: StyleFn`,
+    "",
+    "  /**",
+    "   * PikaCSS Preview",
+    "   */",
+    `  const ${fnName}p: StyleFnWithPreview`,
+    "}",
+    ""
+  ];
+}
+function generateVueDeclaration(ctx) {
+  const { hasVue, fnName } = ctx;
+  if (!hasVue)
+    return [];
+  return [
+    "declare module 'vue' {",
+    "  interface ComponentCustomProperties {",
+    "    /**",
+    "     * PikaCSS",
+    "     */",
+    `    ${fnName}: StyleFn`,
+    "",
+    "    /**",
+    "     * PikaCSS Preview",
+    "     */",
+    `    ${fnName}p: StyleFnWithPreview`,
+    "  }",
+    "}",
+    ""
+  ];
+}
+async function generateOverloadContent(ctx) {
+  const paramsLines = [];
+  const fnsLines = [];
+  const usages = [...ctx.usages.values()].flat();
+  for (let i = 0; i < usages.length; i++) {
+    const usage = usages[i];
+    try {
+      const addedParamsLines = usage.params.map((param, index) => `type P${i}_${index} = ${JSON.stringify(param)}`);
+      const addedFnLines = [
+        "  /**",
+        "   * ### PikaCSS Preview",
+        "   * ```css",
+        // CSS Lines
+        ...(await prettier.format(await ctx.engine.renderPreviewStyles(...usage.params), { parser: "css" })).split("\n").map((line) => `   * \u200E${line.replace(/^(\s*)/, "$1\u200E")}`),
+        "   * ```",
+        "   */",
+        `  fn(...params: [${usage.params.map((_, index) => `p${index}: P${i}_${index}`).join(", ")}]): ReturnType<StyleFn>`
+      ];
+      paramsLines.push(...addedParamsLines);
+      fnsLines.push(...addedFnLines);
+    } catch {
+    }
+  }
+  return [
+    "interface PreviewOverloads<StyleFn extends (StyleFn_Array | StyleFn_String | StyleFn_Inline)> {",
+    ...fnsLines,
+    "  /**",
+    "   * PikaCSS Preview",
+    "   * Save the current file to see the preview.",
+    "   */",
+    `  fn(...params: Parameters<StyleFn>): ReturnType<StyleFn>`,
+    "}",
+    ...paramsLines
+  ];
+}
+async function generateTsCodegenContent(ctx) {
+  const lines = [
+    `// Auto-generated by ${ctx.currentPackageName}`,
+    `import type { Autocomplete as _Autocomplete, StyleItem } from '${ctx.currentPackageName}'`,
+    `import { createDefineEngineConfigFn } from '${ctx.currentPackageName}'`,
+    ""
+  ];
+  lines.push(...generateAutocomplete(ctx));
+  lines.push(
+    "export const defineEngineConfig: ReturnType<typeof createDefineEngineConfigFn<Autocomplete>> = createDefineEngineConfigFn<Autocomplete>()",
+    ""
+  );
+  lines.push(...generateStyleFn(ctx));
+  lines.push(...generateGlobalDeclaration(ctx));
+  lines.push(...generateVueDeclaration(ctx));
+  lines.push(...await generateOverloadContent(ctx));
+  return lines.join("\n");
+}
+
+function findFunctionCalls(code, RE) {
+  const result = [];
+  let matched = RE.exec(code);
+  while (matched != null) {
+    const fnName = matched[1];
+    const start = matched.index;
+    let end = start + fnName.length;
+    let depth = 1;
+    let inString = false;
+    while (depth > 0) {
+      end++;
+      if (inString === false && code[end] === "(")
+        depth++;
+      else if (inString === false && code[end] === ")")
+        depth--;
+      else if (inString === false && (code[end] === "'" || code[end] === '"'))
+        inString = code[end];
+      else if (inString === code[end])
+        inString = false;
+    }
+    const snippet = code.slice(start, end + 1);
+    result.push({ fnName, start, end, snippet });
+    matched = RE.exec(code);
+  }
+  return result;
+}
+const ESCAPE_REPLACE_RE = /[.*+?^${}()|[\]\\/]/g;
+function createFnUtils(fnName) {
+  const available = {
+    normal: /* @__PURE__ */ new Set([fnName]),
+    forceString: /* @__PURE__ */ new Set([`${fnName}.str`, `${fnName}['str']`, `${fnName}["str"]`, `${fnName}[\`str\`]`]),
+    forceArray: /* @__PURE__ */ new Set([`${fnName}.arr`, `${fnName}['arr']`, `${fnName}["arr"]`, `${fnName}[\`arr\`]`]),
+    forceInline: /* @__PURE__ */ new Set([`${fnName}.inl`, `${fnName}['inl']`, `${fnName}["inl"]`, `${fnName}[\`inl\`]`]),
+    // preview
+    normalPreview: /* @__PURE__ */ new Set([`${fnName}p`]),
+    forceStringPreview: /* @__PURE__ */ new Set([`${fnName}p.str`, `${fnName}p['str']`, `${fnName}p["str"]`, `${fnName}p[\`str\`]`]),
+    forceArrayPreview: /* @__PURE__ */ new Set([`${fnName}p.arr`, `${fnName}p['arr']`, `${fnName}p["arr"]`, `${fnName}p[\`arr\`]`]),
+    forceInlinePreview: /* @__PURE__ */ new Set([`${fnName}p.inl`, `${fnName}p['inl']`, `${fnName}p["inl"]`, `${fnName}p[\`inl\`]`])
+  };
+  const RE = new RegExp(`\\b(${Object.values(available).flatMap((s) => [...s].map((f) => `(${f.replace(ESCAPE_REPLACE_RE, "\\$&")})`)).join("|")})\\(`, "g");
+  return {
+    isNormal: (fnName2) => available.normal.has(fnName2) || available.normalPreview.has(fnName2),
+    isForceString: (fnName2) => available.forceString.has(fnName2) || available.forceStringPreview.has(fnName2),
+    isForceArray: (fnName2) => available.forceArray.has(fnName2) || available.forceArrayPreview.has(fnName2),
+    isForceInline: (fnName2) => available.forceInline.has(fnName2) || available.forceInlinePreview.has(fnName2),
+    isPreview: (fnName2) => available.normalPreview.has(fnName2) || available.forceStringPreview.has(fnName2) || available.forceArrayPreview.has(fnName2) || available.forceInlinePreview.has(fnName2),
+    RE
+  };
+}
+async function createCtx(options) {
+  const {
+    cwd,
+    currentPackageName,
+    target,
+    configOrPath,
+    fnName,
+    transformedFormat,
+    tsCodegen,
+    devCss
+  } = options;
+  const devCssFilepath = isAbsolute(devCss) ? resolve(devCss) : join(cwd, devCss);
+  const tsCodegenFilepath = tsCodegen === false ? null : isAbsolute(tsCodegen) ? resolve(tsCodegen) : join(cwd, tsCodegen);
+  const inlineConfig = typeof configOrPath === "object" ? configOrPath : null;
+  const specificConfigPath = typeof configOrPath === "string" ? isAbsolute(configOrPath) ? configOrPath : join(cwd, configOrPath) : null;
+  const configSources = [
+    ...specificConfigPath == null ? [] : [specificConfigPath],
+    ...["pika", "pikacss"].flatMap((name) => ["js", "ts", "cjs", "cts", "mjs", "mts"].map((ext) => `${name}.config.${ext}`)).map((name) => join(cwd, name))
+  ];
+  const targetREs = target.map((t) => micromatch.makeRe(t));
+  const needToTransform = (id) => targetREs.some((re) => re.test(id));
+  const ctx = {
+    cwd,
+    currentPackageName,
+    fnName,
+    fnUtils: createFnUtils(fnName),
+    transformedFormat,
+    devCssFilepath,
+    tsCodegenFilepath,
+    hasVue: isPackageExists("vue", { paths: [cwd] }),
+    usages: /* @__PURE__ */ new Map(),
+    hooks: {
+      styleUpdated: createEventHook(),
+      tsCodegenUpdated: createEventHook()
+    },
+    loadConfig: async () => {
+      if (inlineConfig != null)
+        return { config: inlineConfig, file: null };
+      const resolvedConfigPath = configSources.find((path) => {
+        const stat = statSync(path, { throwIfNoEntry: false });
+        return stat != null && stat.isFile();
+      });
+      if (resolvedConfigPath == null)
+        return { config: null, file: null };
+      const jiti = createJiti(cwd, {
+        fsCache: false,
+        moduleCache: false
+      });
+      const config = await jiti.import(resolvedConfigPath, { default: true });
+      return { config, file: resolvedConfigPath };
+    },
+    init: async () => {
+      ctx.isReady = false;
+      await mkdir(dirname(devCssFilepath), { recursive: true }).catch(() => {
+      });
+      await writeFile(devCssFilepath, "");
+      if (tsCodegenFilepath != null) {
+        await mkdir(dirname(tsCodegenFilepath), { recursive: true }).catch(() => {
+        });
+        await writeFile(tsCodegenFilepath, "export function defineEngineConfig(config: any) { return config }");
+      }
+      ctx.usages.clear();
+      const { config, file } = await ctx.loadConfig().catch((error) => {
+        console.warn(`[${ctx.currentPackageName}] Failed to load config file: ${error}`);
+        return { config: null, file: null };
+      });
+      ctx.resolvedConfigPath = file;
+      ctx.engine = await createEngine(config ?? {});
+      ctx.engine.config.plugins.unshift({
+        name: "@pikacss/integration:dev",
+        preflightUpdated: () => ctx.hooks.styleUpdated.trigger(),
+        atomicRuleAdded: () => ctx.hooks.styleUpdated.trigger(),
+        autocompleteConfigUpdated: () => ctx.hooks.tsCodegenUpdated.trigger()
+      });
+      ctx.isReady = true;
+    },
+    isReady: false,
+    configSources,
+    resolvedConfigPath: null,
+    engine: null,
+    transform: async (code, id) => {
+      if (ctx.isReady === false || !needToTransform(id)) {
+        return;
+      }
+      ctx.usages.delete(id);
+      const functionCalls = findFunctionCalls(code, ctx.fnUtils.RE);
+      if (functionCalls.length === 0)
+        return;
+      const usages = [];
+      ctx.usages.set(id, usages);
+      const transformed = new MagicString(code);
+      for (const fnCall of functionCalls) {
+        const functionCallStr = fnCall.snippet;
+        const argsStr = `[${functionCallStr.slice(fnCall.fnName.length + 1, -1)}]`;
+        const args = new Function(`return ${argsStr}`)();
+        const usage = {
+          params: args
+        };
+        usages.push(usage);
+        const names = await ctx.engine.use(...args);
+        ctx.hooks.tsCodegenUpdated.trigger();
+        let transformedContent;
+        if (ctx.fnUtils.isNormal(fnCall.fnName)) {
+          transformedContent = ctx.transformedFormat === "array" ? `[${names.map((n) => `'${n}'`).join(", ")}]` : ctx.transformedFormat === "string" ? `'${names.join(" ")}'` : names.join(" ");
+        } else if (ctx.fnUtils.isForceString(fnCall.fnName)) {
+          transformedContent = `'${names.join(" ")}'`;
+        } else if (ctx.fnUtils.isForceArray(fnCall.fnName)) {
+          transformedContent = `[${names.map((n) => `'${n}'`).join(", ")}]`;
+        } else if (ctx.fnUtils.isForceInline(fnCall.fnName)) {
+          transformedContent = names.join(" ");
+        } else {
+          throw new Error(`Unexpected function name: ${fnCall.fnName}`);
+        }
+        transformed.update(fnCall.start, fnCall.end + 1, transformedContent);
+      }
+      return {
+        code: transformed.toString(),
+        map: transformed.generateMap({ hires: true })
+      };
+    },
+    writeDevCssFile: async () => {
+      if (ctx.isReady === false)
+        return;
+      let rawCss = "";
+      let css = "";
+      try {
+        rawCss = ctx.engine.renderStyles();
+        css = await prettier.format([
+          `/* Auto-generated by ${ctx.currentPackageName} */`,
+          rawCss
+        ].join("\n"), { parser: "css" });
+      } catch (error) {
+        console.warn(`[${ctx.currentPackageName}] Failed to generate CSS: ${ctx.devCssFilepath}`);
+        css = [
+          `/* ${error.message.split("\n")[0]}`,
+          "",
+          rawCss,
+          "",
+          "*/"
+        ].join("\n");
+      }
+      await writeFile(ctx.devCssFilepath, css);
+    },
+    writeTsCodegenFile: async () => {
+      if (ctx.isReady === false || ctx.tsCodegenFilepath == null)
+        return;
+      const content = await generateTsCodegenContent(ctx);
+      await writeFile(ctx.tsCodegenFilepath, content);
+    }
+  };
+  await ctx.init();
+  return ctx;
+}
+
+export { createCtx };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@pikacss/integration",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.0.1",
+  "author": "DevilTea <ch19980814@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DevilTea/pikacss.git",
+    "directory": "packages/integration"
+  },
+  "bugs": {
+    "url": "https://github.com/DevilTea/pikacss/issues"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "fast-glob": "^3.3.2",
+    "jiti": "^2.4.0",
+    "local-pkg": "^1.1.1",
+    "magic-string": "^0.30.12",
+    "micromatch": "^4.0.8",
+    "pathe": "^2.0.3",
+    "prettier": "^3.2.5",
+    "@pikacss/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/micromatch": "^4.0.9"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "build:pack": "pnpm build && pnpm pack",
+    "stub": "unbuild --stub",
+    "typecheck": "pnpm typecheck:package && pnpm typecheck:test",
+    "typecheck:package": "tsc --project ./tsconfig.package.json --noEmit",
+    "typecheck:test": "tsc --project ./tsconfig.tests.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}