borboleta 0.0.1 → 0.0.2

package/README.md

@@ -1,64 +1,135 @@
-# Borboleta
+# Borboleta 🦋
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.2.0.
+Convert [JSON Schema](https://json-schema.org/) definitions into [Angular Signal Forms](https://angular.dev/guide/forms/signals/overview) schema functions.
 
-## Code scaffolding
+> **Requires Angular 21+** — Signal Forms are experimental. See the [Angular docs](https://angular.dev/guide/forms/signals/validation#the-schema-function) for details.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+## Why "Borboleta"?
 
-```bash
-ng generate component component-name
-```
+*Borboleta* is Portuguese for **butterfly** — a symbol of transformation. This library transforms JSON Schema definitions into Angular Signal Forms schemas, much like a caterpillar becomes a butterfly. 🦋
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+## Installation
 
 ```bash
-ng generate --help
+npm install borboleta
 ```
 
-## Building
+Peer dependencies: `@angular/core`, `@angular/common`, `@angular/forms` (all `^21.2.0`).
 
-To build the library, run:
+## Quick start
 
-```bash
-ng build borboleta
+```typescript
+import { signal } from '@angular/core';
+import { form } from '@angular/forms/signals';
+import { toSignalSchema } from 'borboleta';
+
+const jsonSchema = {
+  type: 'object',
+  required: ['email', 'age'],
+  properties: {
+    email: { type: 'string', format: 'email' },
+    age:   { type: 'number', minimum: 18, maximum: 120 },
+    role:  { type: 'string', enum: ['admin', 'user', 'guest'] },
+  },
+};
+
+const model = signal({ email: '', age: 0, role: '' });
+const myForm = form(model, toSignalSchema(jsonSchema));
+```
+
+This generates the same validators as writing the schema by hand:
+
+```typescript
+const myForm = form(model, (s) => {
+  required(s.email);
+  email(s.email);
+  required(s.age);
+  min(s.age, 18);
+  max(s.age, 120);
+  validate(s.role, ({ value }) => {
+    const v = value();
+    if (v != null && v !== '' && !['admin', 'user', 'guest'].includes(v)) {
+      return { kind: 'enum', message: 'Must be one of: admin, user, guest' };
+    }
+    return null;
+  });
+});
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+## Supported JSON Schema keywords
+
+| JSON Schema             | Signal Forms validator        |
+| ----------------------- | ----------------------------- |
+| `required`              | `required()`                  |
+| `enum`                  | `validate()` (custom)         |
+| `minimum` / `maximum`   | `min()` / `max()`             |
+| `minLength` / `maxLength` | `minLength()` / `maxLength()` |
+| `pattern`               | `pattern()`                   |
+| `format: "email"`       | `email()`                     |
+| Nested `object`         | Recursive descent             |
+| `items` (array)         | `applyEach()`                 |
+
+## Adding custom validators
+
+Use `composeSchemas()` to layer custom validators on top of the generated ones:
+
+```typescript
+import { form, validate, required } from '@angular/forms/signals';
+import { toSignalSchema, composeSchemas } from 'borboleta';
+
+const myForm = form(
+  model,
+  composeSchemas(
+    toSignalSchema(jsonSchema),
+    (s) => {
+      // Custom: URL must use HTTPS
+      validate(s.run.url, ({ value }) => {
+        if (!value().startsWith('https://')) {
+          return { kind: 'https', message: 'URL must use HTTPS' };
+        }
+        return null;
+      });
+
+      // Custom: conditional required
+      required(s.monitor.url, {
+        when: ({ valueOf }) => valueOf(s.monitor.isMonitored),
+      });
+    },
+  ),
+);
+```
 
-### Publishing the Library
+Or just call `toSignalSchema()` inside your own schema function — no utility needed:
 
-Once the project is built, you can publish your library by following these steps:
+```typescript
+const myForm = form(model, (s) => {
+  toSignalSchema(jsonSchema)(s);
+  validate(s.run.url, /* ... */);
+});
+```
 
-1. Navigate to the `dist` directory:
+## API
 
-   ```bash
-   cd dist/borboleta
-   ```
+### `toSignalSchema<T>(jsonSchema: JsonSchema): SchemaFn<T>`
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+Converts a JSON Schema object into an Angular Signal Forms `SchemaFn<T>`. Pass the result directly to `form()` or combine it with `composeSchemas()`.
 
-## Running unit tests
+### `composeSchemas<T>(...schemas: SchemaFn<T>[]): SchemaFn<T>`
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+Combines multiple schema functions into one. Each schema is called in order on the same `SchemaPathTree`, so validators accumulate.
 
-```bash
-ng test
-```
+### `JsonSchema` (type)
 
-## Running end-to-end tests
+TypeScript interface describing the subset of JSON Schema Draft-07 that Borboleta understands.
 
-For end-to-end (e2e) testing, run:
+## Development
 
 ```bash
-ng e2e
+npm install          # Install dependencies
+npm run build        # Build the library (output: dist/borboleta/)
+npm test             # Run tests (Vitest)
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
-
-## Additional Resources
+## License
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borboleta",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/easyware-io/borboleta"