# Vocphone JavaScript Library

Lightweight form rendering and submission helper for VocPhone projects. This library renders JSON-driven forms into the DOM, collects values (FormData or plain objects), and supports auto-submit to an API endpoint.

## Documentation

- **[Full API & Field Reference →](./docs/forms-lib.md)**
  - [renderForm](./docs/forms-lib.md#renderform)
  - [Field Types](./docs/forms-lib.md#field-types) — text, select, radio, checkbox, boolean, file, avatar, tags, timezone, users, audio_select, table, field-select, row, group
  - [Default Values](./docs/forms-lib.md#default-values)
  - [Validation](./docs/forms-lib.md#validation)
  - [Bootstrap Integration](./docs/forms-lib.md#bootstrap-integration)
  - [Value Extraction](./docs/forms-lib.md#value-extraction)
  - [Form Submission](./docs/forms-lib.md#form-submission)
  - [CSS Class Reference](./docs/forms-lib.md#css-class-reference)
  - [TypeScript Types](./docs/forms-lib.md#typescript-types)

---

## Quick Start

Install dependencies and build (if developing locally):

```bash
npm install
npm run build
```

Include the bundle from a CDN (UMD/global) or import as a module in your app.

## CDN Usage

**Global UMD bundle:**

```html
<div id="render-form"></div>
<script src="https://cdn.jsdelivr.net/npm/voc-lib-js@latest/dist/main.global.js"></script>
<script>
    const rendered = VocLibJs.FormsLib.renderForm('#render-form', formSchema);
    rendered.onSubmit((data) => {
        console.log([...data.entries()]);
    });
</script>
```

**ES Module:**

```html
<div id="render-form"></div>
<script type="module">
    import { FormsLib } from 'https://cdn.jsdelivr.net/npm/voc-lib-js@latest/dist/main.mjs';
    const rendered = FormsLib.renderForm('#render-form', formSchema);
    console.log(rendered.getValues(false)); // plain object
</script>
```

## NPM / Framework Usage

```bash
npm install voc-lib-js
```

```vue
<script setup>
import { onMounted, ref } from 'vue';
import { FormsLib } from 'voc-lib-js';

const formRef = ref(null);

onMounted(() => {
    formRef.value = FormsLib.renderForm('#render-form', formSchema);
});
</script>

<template>
    <div id="render-form"></div>
</template>
```

Works the same in React, Angular, Svelte, or vanilla JS.

## Example Form Schema

```json
{
    "id": "user-registration",
    "code": "reg_001",
    "form_name": "User Registration",
    "default_values": {
        "country": "usa"
    },
    "submit_config": {
        "url": "https://api.example.com/forms/submit",
        "api_token": "<token>"
    },
    "fields": [
        {
            "type": "row",
            "items": [
                { "label": "First Name", "key": "first_name", "type": "text", "required": true },
                { "label": "Last Name",  "key": "last_name",  "type": "text", "required": true }
            ]
        },
        { "label": "Email",    "key": "email",    "type": "email",    "required": true },
        { "label": "Password", "key": "password", "type": "password", "required": true },
        {
            "label": "Country", "key": "country", "type": "select",
            "options": [
                { "label": "United States", "value": "usa" },
                { "label": "Canada",        "value": "canada" }
            ]
        },
        {
            "label": "Notification Emails",
            "key": "notify_emails",
            "type": "tags",
            "tag_types": ["email"],
            "hint_text": "Press <b>Enter</b> or <b>,</b> after each address."
        }
    ]
}
```

## Reading Values & Submission

```js
const rendered = FormsLib.renderForm('#render-form', formSchema);

// FormData (default — ideal for file uploads)
const data = rendered.getValues();
console.log(data.get('email'));

// Plain object
const obj = rendered.getValues(false);
console.log(obj);

// Manual submit handler
rendered.onSubmit((data, event) => {
    fetch('/api/submit', { method: 'POST', body: data });
});

// Auto-submit: provide submit_config in the schema or options —
// the library posts automatically and calls onSubmitResult with (response, error)
```

For the full API including all field types, validation options, Bootstrap integration, and CSS class reference see **[docs/forms-lib.md](./docs/forms-lib.md)**.

## Contributing

1. Fork the repo and create a feature branch.
2. Run `npm install` and `npm run build` to test locally.
3. Open test pages from `tests-local/vanilla/forms-lib/` in a browser to manually verify field behaviour.
4. Open a PR with a clear description.

## License

MIT