@mochi-css/config 3.0.0

package/README.md

@@ -0,0 +1,136 @@
+# 🧁 Mochi-CSS/config
+
+This package is part of the [Mochi-CSS project](https://github.com/Niikelion/mochi-css).
+It provides the shared configuration layer - types, config file loading, and config resolution - used by all Mochi-CSS integrations (Vite, PostCSS, Next.js).
+
+---
+
+## Installation
+
+```bash
+npm i @mochi-css/config --save-dev
+```
+
+---
+
+## `mochi.config.ts`
+
+Place a `mochi.config.mts` (or `.cts`, `.ts`, `.mjs`, `.cjs`, `.js`) file in your project root to configure all Mochi-CSS integrations in one place.
+
+```typescript
+// mochi.config.mts
+import { defineConfig } from "@mochi-css/config"
+
+export default defineConfig({
+    roots: ["src"],
+    splitCss: true,
+})
+```
+
+All Mochi-CSS integrations automatically load this file - you don't need to pass the same options to each plugin separately.
+
+---
+
+## API
+
+### `defineConfig`
+
+Identity helper that provides full type inference for your config file.
+
+```typescript
+function defineConfig(config: MochiConfig): MochiConfig
+```
+
+---
+
+### `loadConfig`
+
+Finds and loads the nearest `mochi.config.*` file. Returns `{}` if no file is found.
+
+```typescript
+async function loadConfig(cwd?: string): Promise<MochiConfig>
+```
+
+Searched file names (in order): `mochi.config.mts`, `mochi.config.cts`, `mochi.config.ts`, `mochi.config.mjs`, `mochi.config.cjs`, `mochi.config.js`.
+
+---
+
+### `resolveConfig`
+
+Merges a file config, inline plugin options, and defaults into a fully resolved config.
+Runs all `MochiPlugin.onConfigResolved` hooks in order.
+
+```typescript
+async function resolveConfig(
+    fileConfig: MochiConfig,
+    inlineOpts?: MochiConfig,
+    defaults?: Partial<ResolvedConfig>,
+): Promise<ResolvedConfig>
+```
+
+**Merge behaviour:**
+- Arrays (`roots`, `extractors`, `esbuildPlugins`): file config + inline options concatenated, falling back to defaults
+- Scalar values (`splitCss`, `tmpDir`): inline options take precedence over file config, then defaults
+- Callbacks (`onDiagnostic`): both callbacks are called when both are provided
+
+---
+
+## Types
+
+### `MochiConfig`
+
+The user-facing config. All fields are optional.
+
+| Field            | Type               | Description                                               |
+|------------------|--------------------|-----------------------------------------------------------|
+| `roots`          | `RootEntry[]`      | Directories scanned for source files (default: `["src"]`) |
+| `extractors`     | `StyleExtractor[]` | Style extractors - merged with defaults from integrations |
+| `splitCss`  | `boolean`          | Emit per-source-file CSS instead of one global file       |
+| `onDiagnostic`   | `OnDiagnostic`     | Callback for warnings and non-fatal errors                |
+| `esbuildPlugins` | `EsbuildPlugin[]`  | esbuild plugins forwarded to the bundler                  |
+| `plugins`        | `MochiPlugin[]`    | Mochi plugins - run after config is resolved              |
+| `tmpDir`         | `string`           | Manifest/styles output directory                          |
+
+### `ResolvedConfig`
+
+Same as `MochiConfig` but with required fields and no `plugins` key. Produced by `resolveConfig`.
+
+### `MochiPlugin`
+
+Hook interface for extending the resolved config.
+
+```typescript
+interface MochiPlugin {
+    name: string
+    onConfigResolved?: (config: ResolvedConfig) => Promise<ResolvedConfig> | ResolvedConfig
+}
+```
+
+---
+
+## Writing a Plugin
+
+```typescript
+import type { MochiPlugin } from "@mochi-css/config"
+import { myExtractor } from "./myExtractor"
+
+export const myPlugin: MochiPlugin = {
+    name: "my-plugin",
+    onConfigResolved(config) {
+        return {
+            ...config,
+            extractors: [...config.extractors, myExtractor],
+        }
+    },
+}
+```
+
+```typescript
+// mochi.config.ts
+import { defineConfig } from "@mochi-css/config"
+import { myPlugin } from "./myPlugin"
+
+export default defineConfig({
+    plugins: [myPlugin],
+})
+```

package/dist/index.d.mts

@@ -0,0 +1,93 @@
+import { AstPostProcessor, OnDiagnostic, OnDiagnostic as OnDiagnostic$1, RootEntry, RootEntry as RootEntry$1, StyleExtractor, StyleExtractor as StyleExtractor$1 } from "@mochi-css/builder";
+
+//#region src/merge.d.ts
+declare function mergeArrays<T>(a: T[] | undefined, b: T[] | undefined): T[] | undefined;
+type Callback<T extends unknown[]> = (...args: T) => void;
+declare function mergeCallbacks<T extends unknown[]>(a: Callback<T> | undefined, b: Callback<T> | undefined): Callback<T> | undefined;
+//#endregion
+//#region src/plugin/TransformationPipeline.d.ts
+type Transformation<T, Args extends unknown[]> = (value: T, ...args: Args) => T | Promise<T>;
+interface TransformationHookProvider<T, Args extends unknown[] = [], Data = void> {
+  registerTransformation(transformation: Transformation<T, Args>, data: Data): void;
+}
+interface TransformationUser<T, Args extends unknown[] = []> {
+  transform(value: T, ...args: Args): Promise<T>;
+}
+declare class TransformationPipeline<T, Args extends unknown[] = []> implements TransformationHookProvider<T, Args>, TransformationUser<T, Args> {
+  private readonly transformations;
+  registerTransformation(transformation: Transformation<T, Args>): void;
+  transform(value: T, ...args: Args): Promise<T>;
+  getTransformations(): Transformation<T, Args>[];
+}
+type TransformationWithContext<T, Args extends unknown[], Data> = {
+  fn: Transformation<T, Args>;
+  ctx: Data;
+};
+type TransformationFilter<Data, Args extends unknown[]> = (this: void, data: Data, ...args: Args) => boolean;
+declare class FilteredTransformationPipeline<T, Data, Args extends unknown[] = []> implements TransformationHookProvider<T, Args, Data>, TransformationUser<T, Args> {
+  private filter;
+  private readonly transformations;
+  constructor(filter: TransformationFilter<Data, Args>);
+  registerTransformation(transformation: Transformation<T, Args>, data: Data): void;
+  transform(value: T, ...args: Args): Promise<T>;
+  getTransformations(): TransformationWithContext<T, Args, Data>[];
+}
+//#endregion
+//#region src/plugin/Context.d.ts
+type FileTransformOptions = {
+  filePath: string;
+};
+type FileTransformData = {
+  filter?: string;
+};
+type FileTransformationHookProvider = TransformationHookProvider<string, [FileTransformOptions], FileTransformData>;
+interface AnalysisTransformHookProvider {
+  register(hook: AstPostProcessor): void;
+}
+declare class AnalysisHookCollector implements AnalysisTransformHookProvider {
+  private readonly hooks;
+  register(hook: AstPostProcessor): void;
+  getHooks(): AstPostProcessor[];
+}
+interface PluginContext {
+  readonly sourceTransform: FileTransformationHookProvider;
+  readonly analysisTransform: AnalysisTransformHookProvider;
+}
+declare class FullContext implements PluginContext {
+  readonly sourceTransform: FilteredTransformationPipeline<string, FileTransformData, [FileTransformOptions]>;
+  readonly analysisTransform: AnalysisHookCollector;
+  getAnalysisHooks(): AstPostProcessor[];
+}
+//#endregion
+//#region src/plugin/Plugin.d.ts
+interface Plugin<Config$1 extends object> {
+  name: string;
+  onConfigResolved?(this: void, config: Config$1): Promise<Config$1> | Config$1;
+  onLoad?(context: PluginContext): void;
+}
+//#endregion
+//#region src/config/index.d.ts
+interface Config {
+  roots: RootEntry$1[];
+  extractors: StyleExtractor$1[];
+  splitCss: boolean;
+  onDiagnostic?: OnDiagnostic$1;
+  plugins: Plugin<Config>[];
+  tmpDir?: string;
+  debug?: boolean;
+}
+type MochiPlugin = Plugin<Config>;
+declare function defineConfig(config: Partial<Config>): Partial<Config>;
+declare function resolveConfig(fileConfig: Partial<Config>, inlineConfig?: Partial<Config>, defaults?: Partial<Config>): Promise<Config>;
+declare function loadConfig(cwd?: string): Promise<Partial<Config>>;
+//#endregion
+//#region src/styledIdPlugin.d.ts
+/**
+ * Returns a MochiPlugin that injects stable `s-` class IDs into every `styled()` call.
+ * - Registers a `sourceTransform` for runtime source injection (Vite/Next `transform` hook).
+ * - Registers an `analysisTransform` for CSS extraction via direct AST mutation.
+ */
+declare function styledIdPlugin(): MochiPlugin;
+//#endregion
+export { type AnalysisTransformHookProvider, Config, FullContext, MochiPlugin, type OnDiagnostic, type PluginContext, type RootEntry, type StyleExtractor, type TransformationHookProvider, TransformationPipeline, type TransformationUser, defineConfig, loadConfig, mergeArrays, mergeCallbacks, resolveConfig, styledIdPlugin };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { AstPostProcessor, OnDiagnostic, OnDiagnostic as OnDiagnostic$1, RootEntry, RootEntry as RootEntry$1, StyleExtractor, StyleExtractor as StyleExtractor$1 } from "@mochi-css/builder";
+
+//#region src/merge.d.ts
+declare function mergeArrays<T>(a: T[] | undefined, b: T[] | undefined): T[] | undefined;
+type Callback<T extends unknown[]> = (...args: T) => void;
+declare function mergeCallbacks<T extends unknown[]>(a: Callback<T> | undefined, b: Callback<T> | undefined): Callback<T> | undefined;
+//#endregion
+//#region src/plugin/TransformationPipeline.d.ts
+type Transformation<T, Args extends unknown[]> = (value: T, ...args: Args) => T | Promise<T>;
+interface TransformationHookProvider<T, Args extends unknown[] = [], Data = void> {
+  registerTransformation(transformation: Transformation<T, Args>, data: Data): void;
+}
+interface TransformationUser<T, Args extends unknown[] = []> {
+  transform(value: T, ...args: Args): Promise<T>;
+}
+declare class TransformationPipeline<T, Args extends unknown[] = []> implements TransformationHookProvider<T, Args>, TransformationUser<T, Args> {
+  private readonly transformations;
+  registerTransformation(transformation: Transformation<T, Args>): void;
+  transform(value: T, ...args: Args): Promise<T>;
+  getTransformations(): Transformation<T, Args>[];
+}
+type TransformationWithContext<T, Args extends unknown[], Data> = {
+  fn: Transformation<T, Args>;
+  ctx: Data;
+};
+type TransformationFilter<Data, Args extends unknown[]> = (this: void, data: Data, ...args: Args) => boolean;
+declare class FilteredTransformationPipeline<T, Data, Args extends unknown[] = []> implements TransformationHookProvider<T, Args, Data>, TransformationUser<T, Args> {
+  private filter;
+  private readonly transformations;
+  constructor(filter: TransformationFilter<Data, Args>);
+  registerTransformation(transformation: Transformation<T, Args>, data: Data): void;
+  transform(value: T, ...args: Args): Promise<T>;
+  getTransformations(): TransformationWithContext<T, Args, Data>[];
+}
+//#endregion
+//#region src/plugin/Context.d.ts
+type FileTransformOptions = {
+  filePath: string;
+};
+type FileTransformData = {
+  filter?: string;
+};
+type FileTransformationHookProvider = TransformationHookProvider<string, [FileTransformOptions], FileTransformData>;
+interface AnalysisTransformHookProvider {
+  register(hook: AstPostProcessor): void;
+}
+declare class AnalysisHookCollector implements AnalysisTransformHookProvider {
+  private readonly hooks;
+  register(hook: AstPostProcessor): void;
+  getHooks(): AstPostProcessor[];
+}
+interface PluginContext {
+  readonly sourceTransform: FileTransformationHookProvider;
+  readonly analysisTransform: AnalysisTransformHookProvider;
+}
+declare class FullContext implements PluginContext {
+  readonly sourceTransform: FilteredTransformationPipeline<string, FileTransformData, [FileTransformOptions]>;
+  readonly analysisTransform: AnalysisHookCollector;
+  getAnalysisHooks(): AstPostProcessor[];
+}
+//#endregion
+//#region src/plugin/Plugin.d.ts
+interface Plugin<Config$1 extends object> {
+  name: string;
+  onConfigResolved?(this: void, config: Config$1): Promise<Config$1> | Config$1;
+  onLoad?(context: PluginContext): void;
+}
+//#endregion
+//#region src/config/index.d.ts
+interface Config {
+  roots: RootEntry$1[];
+  extractors: StyleExtractor$1[];
+  splitCss: boolean;
+  onDiagnostic?: OnDiagnostic$1;
+  plugins: Plugin<Config>[];
+  tmpDir?: string;
+  debug?: boolean;
+}
+type MochiPlugin = Plugin<Config>;
+declare function defineConfig(config: Partial<Config>): Partial<Config>;
+declare function resolveConfig(fileConfig: Partial<Config>, inlineConfig?: Partial<Config>, defaults?: Partial<Config>): Promise<Config>;
+declare function loadConfig(cwd?: string): Promise<Partial<Config>>;
+//#endregion
+//#region src/styledIdPlugin.d.ts
+/**
+ * Returns a MochiPlugin that injects stable `s-` class IDs into every `styled()` call.
+ * - Registers a `sourceTransform` for runtime source injection (Vite/Next `transform` hook).
+ * - Registers an `analysisTransform` for CSS extraction via direct AST mutation.
+ */
+declare function styledIdPlugin(): MochiPlugin;
+//#endregion
+export { type AnalysisTransformHookProvider, Config, FullContext, MochiPlugin, type OnDiagnostic, type PluginContext, type RootEntry, type StyleExtractor, type TransformationHookProvider, TransformationPipeline, type TransformationUser, defineConfig, loadConfig, mergeArrays, mergeCallbacks, resolveConfig, styledIdPlugin };
+//# sourceMappingURL=index.d.ts.map