@kubb/react-fabric 0.1.8 → 0.2.0

package/README.md

@@ -21,6 +21,282 @@
 </div>
 <br />
 
+Kubb Fabric is a language-agnostic toolkit for generating code and files using JSX and TypeScript.
+It offers a lightweight layer for file generation while orchestrating the overall process of creating and managing files.
+
+> [!WARNING]
+> Fabric is under active development. Until a stable 1.0 release, minor versions may occasionally include breaking changes. Please check release notes and PR titles for breaking changes.
+
+# Features
+
+- 🎨 Declarative file generation — Create files effortlessly using JSX or JavaScript syntax.
+- 📦 Cross-runtime support — Works seamlessly with Node.js and Bun.
+- 🧩 Built-in debugging utilities — Simplify development and inspect generation flows with ease.
+- ⚡ Fast and lightweight — Minimal overhead, maximum performance.
+
+## Write a TypeScript file
+
+Below is a minimal example showing how `createApp` works together with plugins and parsers via `app.use`.
+
+```ts
+import { createApp } from '@kubb/fabric-core'
+import { fsPlugin } from '@kubb/fabric-core/plugins'
+import { typescriptParser, createParser } from '@kubb/fabric-core/parsers'
+
+const app = createApp()
+
+app.use(fsPlugin, {
+  dryRun: false,
+  onBeforeWrite: (path, data) => {
+    console.log('About to write:', path)
+  },
+  clean: { path: './generated' },
+})
+
+app.use(typescriptParser)
+
+await app.addFile({
+  baseName: 'index.ts',
+  path: './generated/index.ts',
+  sources: [
+    { value: 'export const x = 1', isExportable: true },
+  ],
+})
+
+await app.write()
+
+```
+
+# API Reference
+
+## Core
+### `createApp(options?): App`
+Returns an app instance with:
+- `app.use(pluginOrParser, ...options) => App` — register plugins and parsers.
+- `app.addFile(...files)` — queue in-memory files to generate.
+- `app.files` — getter with all queued files.
+- `app.context` — internal context holding events, options, FileManager, installed plugins/parsers.
+
+### `defineApp(instance?): () => App`
+Factory to create your own `createApp` with an optional bootstrap `instance(app)` called on creation.
+
+### App events (emitted by the core during processing)
+- `start`
+- `end`
+- `render { app }`
+- `file:add { files }`
+- `write:start { files }`
+- `write:end { files }`
+- `file:start { file, index, total }`
+- `file:end { file, index, total }`
+- `process:start { files }`
+- `process:progress { file, source, processed, percentage, total }`
+- `process:end { files }`
+
+
+## Plugins
+#### `fsPlugin`
+Writes files to disk on `process:progress`, supports dry runs and cleaning an output folder before writing.
+
+```
+import { fsPlugin } from '@kubb/fabric-core/plugins'
+```
+
+| Option | Type                                                                 | Default | Description                                                           |
+|---|----------------------------------------------------------------------|---|-----------------------------------------------------------------------|
+| dryRun | `boolean`                                                            | `false` | If true, do not write files to disk.               |
+| onBeforeWrite | `(path: string, data: string \| undefined) => void \| Promise<void>` | — | Called right before each file write on `process:progress`.            |
+| clean | `{ path: string }`                                                   | — | If provided, removes the directory at `path` before writing any files. |
+
+Injected `app.write` options (via `fsPlugin`):
+
+| Option | Type                             | Default | Description |
+|---|----------------------------------|---|---|
+| extension | `Record<Extname, Extname \| ''>` | — | Maps input file extensions to output extensions. When set, the matching parser (by extNames) is used. |
+
+#### `barrelPlugin`
+Generates `index.ts` barrel files per folder at `process:end`. `writeEntry` creates a single entry barrel at `root`.
+
+```
+import { barrelPlugin } from '@kubb/fabric-core/plugins'
+```
+
+| Option | Type                                       | Default | Description |
+|---|--------------------------------------------|---|---|
+| root | `string`                                   | — | Root directory to generate barrel files for. |
+| mode | `'all' \| 'named' \| 'propagate' \| false` | — | Controls how exports are generated: all exports, only named exports, propagate (skip barrels), or disabled. |
+| dryRun | `boolean`                                  | `false` | If true, computes barrels but skips writing. |
+
+Injected `app.writeEntry` parameters (via `barrelPlugin`):
+
+| Param | Type                                       | Description |
+|---|--------------------------------------------|---|
+| root | `string`                                   | Root directory where the entry `index.ts` should be created. |
+| mode | `'all' \| 'named' \| 'propagate' \| false` | Controls which export style to use for the entry barrel. |
+
+#### `progressPlugin`
+Shows a CLI progress bar by listening to core events.
+
+```
+import { progressPlugin } from '@kubb/fabric-core/plugins'
+```
+
+| Option | Type | Default | Description                                                                             |
+|---|---|---|-----------------------------------------------------------------------------------------|
+| — | — | — | This plugin has no options, it displays a CLI progress bar by listening to core events. |
+
+
+#### `graphPlugin`
+Shows a graph of all files
+
+```
+import { graphPlugin } from '@kubb/fabric-core/plugins'
+```
+
+| Option | Type      | Default | Description                                   |
+|--------|-----------|---------|-----------------------------------------------|
+| root   | `string`  |         | Root directory where to start searching from. |
+| open   | `boolean` | false   | Open a webpage with the generated graph       |
+
+
+#### `reactPlugin`
+Enables rendering React components to the terminal or to a string. Useful for CLI UIs and templating.
+
+```
+import { reactPlugin } from '@kubb/react-fabric/plugins'
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| stdout | `NodeJS.WriteStream` | — | Optional output stream used to print the rendered content while the app is running. If set, the output is written progressively. |
+| stdin | `NodeJS.ReadStream` | — | Optional input stream for interactive components. |
+| stderr | `NodeJS.WriteStream` | — | Optional error output stream. |
+| debug | `boolean` | — | When true, logs render/unmount information to the console to aid debugging. |
+
+Injected methods (via `reactPlugin`):
+
+| Method | Signature | Description                                                                                        |
+|---|---|----------------------------------------------------------------------------------------------------|
+| `render` | `(App: React.ElementType) => Promise<void> \| void` | Render a React component tree to the terminal and emit the core `start` event.                     |
+| `renderToString` | `(App: React.ElementType) => Promise<string> \| string` | Render a React component tree and return the final output as a string (without writing to stdout). |
+| `waitUntilExit` | `() => Promise<void>` | Wait until the rendered app exits, resolves when unmounted and emits the core `end` event.         |
+
+#### `createPlugin`
+
+Factory to declare a plugin that can be registered via `app.use`.
+
+| Field | Required | Description                                                                                                               |
+|---|---|---------------------------------------------------------------------------------------------------------------------------|
+| `name` | Yes | String identifier of your plugin.                                                                                         |
+| `install(app, options)` | Yes | Called when the plugin is registered. You can subscribe to core events and perform side effects here.                     |
+| `inject?(app, options)` | No | Return synchronously the runtime methods/properties to merge into `app` (e.g. `write`, `render`). This must not be async. |
+
+Example:
+
+```ts
+import { createApp } from '@kubb/fabric-core'
+import { createPlugin } from '@kubb/fabric-core/plugins'
+
+const helloPlugin = createPlugin<{ name?: string }, { sayHello: (msg?: string) => void }>({
+  name: 'helloPlugin',
+  install(app, options) {
+    app.context.events.on('start', () => {
+      console.log('App started')
+    })
+  },
+  inject(app, options) {
+    return {
+      sayHello(msg = options?.name ?? 'world') {
+        console.log(`Hello ${msg}!`)
+      },
+    }
+  },
+})
+
+const app = createApp()
+await app.use(helloPlugin, { name: 'Fabric' })
+app.sayHello() // -> Hello Fabric!
+```
+
+## Parsers
+#### `typescriptParser`
+
+Prints TS/JS imports/exports and sources, supports extname mapping for generated import/export paths.
+
+```
+import { typescriptParser } from '@kubb/fabric-core/parsers'
+```
+
+| Option | Type | Default | Description                                                                                 |
+|---|---|---|---------------------------------------------------------------------------------------------|
+| file | `KubbFile.File` | -| File that will be used to be parsed.                                                        |
+| extname | `string` | `'.ts'` | Extension to use when emitting import/export paths (e.g., rewrite `./file` to `./file.ts`). |
+
+#### `tsxParser`
+
+Delegates to `typescriptParser` with TSX printing settings.
+
+```
+import { tsxParser } from '@kubb/fabric-core/parsers'
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| file | `KubbFile.File` | -| File that will be used to be parsed.                                                        |
+| extname | `string` | `'.tsx'` | Extension to use when emitting import/export paths for TSX/JSX files. |
+
+#### `defaultParser`
+
+Fallback parser used when no extension mapping is provided to `app.write`.
+
+```
+import { defaultParser } @kubb/fabric-core/parsers`
+```
+
+| Option | Type | Default | Description                                                              |
+|---|---|---|--------------------------------------------------------------------------|
+| file | `KubbFile.File` | -| File that will be used to be parsed.                                                        |
+
+#### `createParser`
+Factory to declare a parser that can be registered via `app.use` and selected by `extNames` during `app.write`.
+
+| Field | Required | Description                                                                                                     |
+|---|---|-----------------------------------------------------------------------------------------------------------------|
+| `name` | Yes | String identifier of your parser.                                                                               |
+| `extNames` | Yes | List of file extensions this parser can handle (e.g. ['.ts']). Use `undefined` for the default parser fallback. |
+| `install(app, options)` | No | Optional setup when the parser is registered (subscribe to events, set state, etc.).                            |
+| `parse(file, { extname })` | Yes | Must return the final string that will be written for the given file.                                           |
+
+Example:
+
+```ts
+import { createApp } from '@kubb/fabric-core'
+import { createParser } from '@kubb/fabric-core/parsers'
+
+const vueParser = createParser<{ banner?: string }>({
+  name: 'vueParser',
+  extNames: ['.vue'],
+  async install(app, options) {
+    // Optional setup
+  },
+  async parse(file, { extname }) {
+    const banner = file.options?.banner ?? ''
+    const sources = file.sources.map(s => s.value).join('\n')
+    return `${banner}\n${sources}`
+  },
+})
+
+const app = createApp()
+app.use(vueParser)
+app.use(fsPlugin); // make it possible to write to the filesystem
+
+app.write({ extension: { '.vue': '.ts' } })
+```
+
+> [!NOTE]
+> - `app.use` accepts both plugins and parsers. The `fsPlugin` handles I/O and adds `app.write`. Parsers decide how files are converted to strings for specific extensions.
+> - When extension mapping is provided to `app.write`, Fabric picks a parser whose `extNames` include the file’s extension. Otherwise, the default parser is used.
+
 ## Supporting Kubb
 
 Kubb uses an MIT-licensed open source project with its ongoing development made possible entirely by the support of Sponsors. If you would like to become a sponsor, please consider:

package/dist/{Runtime-DWlDUeLZ.js → Runtime-CatKeybQ.js}

@@ -15393,11 +15393,11 @@ var Runtime = class {
 		const originalError = console.error;
 		console.error = (data) => {
 			const message = typeof data === "string" ? data : data === null || data === void 0 ? void 0 : data.message;
-			if (message.match(/Encountered two children with the same key/gi)) return;
-			if (message.match(/React will try to recreat/gi)) return;
-			if (message.match(/Each child in a list should have a unique/gi)) return;
-			if (message.match(/The above error occurred in the <KubbErrorBoundary/gi)) return;
-			if (message.match(/A React Element from an older version of React was render/gi)) return;
+			if (message === null || message === void 0 ? void 0 : message.match(/Encountered two children with the same key/gi)) return;
+			if (message === null || message === void 0 ? void 0 : message.match(/React will try to recreat/gi)) return;
+			if (message === null || message === void 0 ? void 0 : message.match(/Each child in a list should have a unique/gi)) return;
+			if (message === null || message === void 0 ? void 0 : message.match(/The above error occurred in the <KubbErrorBoundary/gi)) return;
+			if (message === null || message === void 0 ? void 0 : message.match(/A React Element from an older version of React was render/gi)) return;
 			originalError(data);
 		};
 		const logRecoverableError = typeof reportError === "function" ? reportError : console.error;
@@ -15479,4 +15479,4 @@ async function _getOutput(node) {
 
 //#endregion
 export { Root as a, _classPrivateFieldInitSpec as i, _classPrivateFieldGet2 as n, RootContext as o, _classPrivateFieldSet2 as r, Runtime as t };
-//# sourceMappingURL=Runtime-DWlDUeLZ.js.map
+//# sourceMappingURL=Runtime-CatKeybQ.js.map