vanjs-jsf 0.3.1 → 0.4.0

package/README.md

@@ -1,134 +1,344 @@
-# 📦 VanJS-JSF a JSON Schema Form Library for VanJS
-
-**Generate dynamic UI forms effortlessly with TypeScript and JSON Schema, powered by the JSON Schema Form Headless UI framework.**
-
-## Description
-
-This library aims to provide a robust and flexible solution for dynamically generating user interface (UI) forms using JSON Schema definitions. It is built on **TypeScript** for type safety and leverages the powerful [JSON Schema Form Headless UI](https://github.com/remoteoss/json-schema-form) framework, which you can find documented [here](https://json-schema-form.vercel.app). It ensures a lightweight, modern, accessible, and customizable form-building experience.
-
-### Features
-
-- [x] **Dynamic Form Generation**: Create forms directly from JSON Schema, reducing repetitive coding tasks.
-- [x] **Customizable**: Tailor form styles, layouts, and behaviours to meet specific UI/UX requirements.
-- [x] **Headless UI Integration**: Utilize Headless UI's components for accessible and modern interfaces.
-- [x] **TypeScript-first Approach**: Enjoy strong typing and enhanced developer experience with TypeScript.
-- [x] **Validation Support**: Easily integrate JSON Schema-based validation for seamless user input handling.
-- [ ] **Extensible Architecture**: Add custom widgets, field types, and behaviours as needed.
-
-### Available components
-The currently supported form element types are:
- - text = "text"
- - number = "number"
- - textarea = "textarea"
- - select = "select"
- - radio = "radio"
- - date = "date" (Pikaday)
- - code = "code" (CodeMirror with JSON, JavaScript, TypeScript support)
- - fieldset = "fieldset"
-
-### Use Cases
-
-- Quickly generate forms for dashboards, admin panels, and dynamic web applications.
-- Prototype or test form-based UIs with minimal setup.
-- Build reusable form components for your projects.
-
-## Getting Started
-
-1. Install the library:
-
-  ```bash
-  npm install vanjs-jsf
-  ```
-
-2. Import and define your JSON Schema with `x-jsf-presentation` hints:
-
-  ```typescript
-  import van from "vanjs-core";
-  import { jsform } from "vanjs-jsf";
-
-  const { div, h1, p, button } = van.tags;
-
-  const schema = {
-    type: "object",
-    properties: {
-      userName: {
-        type: "string",
-        title: "Name",
-        "x-jsf-presentation": { inputType: "text" },
-      },
-      age: {
-        type: "number",
-        title: "Age",
-        "x-jsf-presentation": { inputType: "number" },
-      },
-    },
-    required: ["userName"],
-    "x-jsf-order": ["userName", "age"],
-  };
-  ```
-
-3. Create a config with initial values and render the form:
-
-  ```typescript
-  const initialValues = { userName: "Simon" };
-  const config = {
-    strictInputType: false,
-    initialValues: initialValues,
-    formValues: initialValues,
-  };
-
-  const handleOnSubmit = (e: Event) => {
-    e.preventDefault();
-    const values = config.formValues;
-    alert(`Submitted: ${JSON.stringify(values, null, 2)}`);
-  };
-
-  van.add(
-    document.body,
-    div(
-      h1("json-schema-form + VanJS"),
-      p("Dynamic form generated from JSON Schema."),
-      jsform(
-        {
-          name: "my-jsf-form",
-          schema: schema,
-          config: config,
-          onsubmit: handleOnSubmit,
-        },
-        button({ type: "submit" }, "Submit")
-      )
-    )
-  );
-  ```
-
-## Development
-
-```bash
-npm install          # Install dependencies
-npm run dev          # Start Vite dev server (port 3030)
-npm run build        # Bundle with esbuild → dist/index.js
-npm run types        # Generate type declarations → dist/*.d.ts
-npm run lint         # Run ESLint
-npm run lint:fix     # Run ESLint with auto-fix
-```
-
-## Publishing
-
-1. Update the version in `package.json`
-2. Run the publish script:
-
-```bash
-./publish.sh
-```
-
-This cleans `dist/`, rebuilds the bundle and type declarations, and publishes to npm.
-
-The package is available at: https://www.npmjs.com/package/vanjs-jsf
-
-## Contributing
-
-Contributions are welcome! Please submit a pull request if you have ideas, feedback, or improvements. Your contributions will help make this library more robust and useful for the community.
-
-## License
-
-This project is licensed under the Apache 2 License. For details, see the [LICENSE](./LICENSE) file.
+# VanJS-JSF — a JSON Schema Form Library for VanJS
+
+**Generate dynamic UI forms effortlessly with TypeScript and JSON Schema, powered by the JSON Schema Form Headless UI framework.**
+
+## Description
+
+This library provides a robust and flexible solution for dynamically generating user interface (UI) forms using JSON Schema definitions. It is built on **TypeScript** for type safety and leverages the powerful [JSON Schema Form Headless UI](https://github.com/remoteoss/json-schema-form) framework, which you can find documented [here](https://json-schema-form.vercel.app). It ensures a lightweight, modern, accessible, and customizable form-building experience.
+
+### Features
+
+- [x] **Dynamic Form Generation**: Create forms directly from JSON Schema, reducing repetitive coding tasks.
+- [x] **Theming API**: Inject CSS classes for every form element via a `theme` object — works with Tailwind, Bootstrap, or any CSS framework.
+- [x] **Layout Map**: Control per-field spatial distribution (e.g. grid column spans) without coupling CSS classes to JSON Schema.
+- [x] **Customizable**: Tailor form styles, layouts, and behaviours to meet specific UI/UX requirements.
+- [x] **Headless UI Integration**: Utilize Headless UI's components for accessible and modern interfaces.
+- [x] **TypeScript-first Approach**: Enjoy strong typing and enhanced developer experience with TypeScript.
+- [x] **Validation Support**: Easily integrate JSON Schema-based validation for seamless user input handling.
+- [ ] **Extensible Architecture**: Add custom widgets, field types, and behaviours as needed.
+
+### Available components
+
+The currently supported form element types are:
+
+- text = "text"
+- number = "number"
+- textarea = "textarea"
+- select = "select"
+- radio = "radio"
+- date = "date" (Pikaday)
+- code = "code" (CodeMirror with JSON, JavaScript, TypeScript support)
+- fieldset = "fieldset"
+- file = "file" (drag & drop, with configurable `readAs` mode and size validation)
+
+## Getting Started
+
+1. Install the library:
+
+```bash
+npm install vanjs-jsf
+```
+
+2. Import and define your JSON Schema with `x-jsf-presentation` hints:
+
+```typescript
+import van from "vanjs-core";
+import { jsform } from "vanjs-jsf";
+
+const { div, h1, p, button } = van.tags;
+
+const schema = {
+  type: "object",
+  properties: {
+    userName: {
+      type: "string",
+      title: "Name",
+      "x-jsf-presentation": { inputType: "text" },
+    },
+    age: {
+      type: "number",
+      title: "Age",
+      "x-jsf-presentation": { inputType: "number" },
+    },
+  },
+  required: ["userName"],
+  "x-jsf-order": ["userName", "age"],
+};
+```
+
+3. Create a config with initial values and render the form:
+
+```typescript
+const initialValues = { userName: "Simon" };
+const config = {
+  strictInputType: false,
+  initialValues: initialValues,
+  formValues: initialValues,
+};
+
+const handleOnSubmit = (e: Event) => {
+  e.preventDefault();
+  const values = config.formValues;
+  alert(`Submitted: ${JSON.stringify(values, null, 2)}`);
+};
+
+van.add(
+  document.body,
+  div(
+    h1("json-schema-form + VanJS"),
+    p("Dynamic form generated from JSON Schema."),
+    jsform(
+      {
+        name: "my-jsf-form",
+        schema: schema,
+        config: config,
+        onsubmit: handleOnSubmit,
+      },
+      button({ type: "submit" }, "Submit"),
+    ),
+  ),
+);
+```
+
+## File Upload Field
+
+The `file` field type renders a drag & drop zone with file info display. Define it in your schema:
+
+```typescript
+const schema = {
+  type: "object",
+  properties: {
+    document: {
+      type: "string",
+      title: "Upload Document",
+      description: "PDF or image, max 5 MB",
+      "x-jsf-presentation": {
+        inputType: "file",
+        accept: ".pdf,.png,.jpg",
+        maxSizeMB: 5,
+        readAs: "auto",
+      },
+    },
+  },
+  "x-jsf-order": ["document"],
+};
+```
+
+### `readAs` modes
+
+| Value              | Behaviour                                                                                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"auto"` (default) | Text extensions (json, csv, txt, xml, yaml, md, html, css, js, ts, sql, etc.) are read as text. All other files are read as binary and returned as base64. |
+| `"text"`           | Always reads the file as text (`readAsText`).                                                                                                              |
+| `"dataURL"`        | Returns a data URL string (`readAsDataURL`).                                                                                                               |
+| `"arrayBuffer"`    | Reads as ArrayBuffer and returns base64 (`readAsArrayBuffer`).                                                                                             |
+
+The file content is stored in `formValues` under the field name. Additional metadata is stored as `<fieldName>__fileName`, `<fieldName>__fileSize`, and `<fieldName>__fileType`.
+
+## Theming
+
+By default, vanjs-jsf applies minimal semantic CSS classes (e.g. `jsf-dropzone`, `jsf-file-info`). You can import the default styles:
+
+```typescript
+import "vanjs-jsf/dist/jsf-defaults.css";
+```
+
+To fully customize the appearance, pass a `theme` object to `jsform()`. Theme classes apply to every element type in the form. Per-field classes defined in `x-jsf-presentation` (e.g. `class`, `titleClass`, `containerClass`) take priority over theme classes.
+
+```typescript
+import { jsform, JsfTheme } from "vanjs-jsf";
+
+const myTheme: JsfTheme = {
+  // Structure
+  container: "mb-4",
+  label: "block text-sm font-medium text-gray-700 mb-1",
+  description: "text-gray-500 text-xs mb-1",
+  error: "text-red-500 text-xs mt-1",
+  requiredIndicator: "text-red-500 ml-1",
+
+  // Inputs
+  input: "w-full border border-gray-300 rounded px-3 py-2",
+  textarea: "w-full border border-gray-300 rounded px-3 py-2 resize-y",
+  select: "w-full border border-gray-300 rounded px-3 py-2",
+  option: "bg-white",
+
+  // Radio
+  radioGroup: "flex flex-col gap-2",
+  radioLabel: "flex items-center gap-2 cursor-pointer",
+  radioInput: "accent-blue-500",
+
+  // Fieldset
+  fieldset: "border border-gray-200 rounded p-4",
+  legend: "text-sm font-semibold text-gray-700",
+
+  // File upload
+  dropZone:
+    "border-2 border-dashed border-gray-300 rounded-lg p-6 text-center cursor-pointer hover:border-blue-400 transition-colors",
+  dropZoneActive:
+    "border-2 border-dashed border-blue-500 rounded-lg p-6 text-center cursor-pointer bg-blue-50",
+  dropZoneText: "text-gray-500 text-sm m-0",
+  fileInfoBar: "mt-2 flex items-center gap-2",
+  fileName: "font-semibold",
+  fileSize: "text-gray-400 text-sm",
+  fileClearButton:
+    "text-sm border border-gray-300 rounded px-2 py-0.5 hover:bg-gray-100",
+  fileReading: "mt-2 text-gray-400 text-sm",
+};
+
+const formEl = jsform({
+  schema: mySchema,
+  config: { initialValues: {}, formValues: {} },
+  theme: myTheme,
+  onsubmit: handleSubmit,
+});
+```
+
+### JsfTheme properties
+
+| Property            | Applies to                                             |
+| ------------------- | ------------------------------------------------------ |
+| `container`         | Wrapper `<div>` of each field                          |
+| `label`             | `<label>` elements                                     |
+| `description`       | Description `<div>` below the label                    |
+| `error`             | Error `<p>` below the input                            |
+| `requiredIndicator` | `<span>` with "\*" next to required field labels       |
+| `input`             | `<input>` for text, number, and date fields            |
+| `textarea`          | `<textarea>` elements                                  |
+| `select`            | `<select>` elements                                    |
+| `option`            | `<option>` elements inside selects                     |
+| `radioGroup`        | Container `<div>` for radio options                    |
+| `radioLabel`        | `<label>` wrapping each radio option                   |
+| `radioInput`        | `<input type="radio">` elements                        |
+| `fieldset`          | `<fieldset>` elements                                  |
+| `legend`            | `<legend>` elements (falls back to `label` if not set) |
+| `dropZone`          | File drop zone container (normal state)                |
+| `dropZoneActive`    | File drop zone during dragover                         |
+| `dropZoneText`      | Text inside the drop zone                              |
+| `fileInfoBar`       | Container for uploaded file info                       |
+| `fileName`          | File name `<strong>`                                   |
+| `fileSize`          | File size `<small>`                                    |
+| `fileClearButton`   | "Clear" button                                         |
+| `fileReading`       | "Reading file..." indicator                            |
+
+## Layout
+
+The `layout` attribute lets you assign extra CSS classes to specific field containers by name, without modifying the JSON Schema. This is useful for controlling column spans in CSS grid layouts.
+
+```typescript
+import { jsform, JsfTheme, JsfLayout } from "vanjs-jsf";
+
+const theme: JsfTheme = {
+  container: "mb-4",
+  input: "w-full border rounded px-3 py-2",
+  label: "block text-sm font-medium mb-1",
+};
+
+const layout: JsfLayout = {
+  host: "col-span-2",    // full row
+  dbname: "col-span-2",  // full row
+  // port, user, password, schema → no entry → default 1 column
+};
+
+const formEl = jsform({
+  schema: connectionSchema,
+  config: { initialValues: {}, formValues: {} },
+  theme,
+  layout,
+});
+```
+
+Wrap the form in a grid container to activate the column distribution:
+
+```css
+.jsf-grid > form {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 0 1rem;
+}
+```
+
+```typescript
+const { div } = van.tags;
+van.add(document.body, div({ class: "jsf-grid" }, formEl));
+```
+
+This produces a layout like:
+
+```text
+┌─────────────── host ────────────────┐
+│ 192.168.1.176                       │
+├────── port ──────┬──── user ────────┤
+│ 5432             │ wolfops          │
+├──── password ────┬──── schema ──────┤
+│ ••••••••         │ public           │
+├─────────────── dbname ──────────────┤
+│ wolfops_dev                         │
+└─────────────────────────────────────┘
+```
+
+### Nested fields
+
+For fields inside a fieldset, `layout` supports both the full path and the short name:
+
+```typescript
+const layout: JsfLayout = {
+  "connection.host": "col-span-2",  // by full path
+  port: "col-span-1",              // by short name (also works for nested)
+};
+```
+
+The full path (`fieldset.fieldName`) is checked first, then the short name.
+
+### Class resolution order
+
+For each element, the resolved class follows this priority:
+
+1. **Per-field class** from `x-jsf-presentation` (e.g. `class`, `titleClass`, `containerClass`)
+2. **Theme class** from the `theme` object
+3. **Empty string** (no class applied)
+
+Layout classes are appended *after* the resolved container class, so they combine with both per-field and theme classes.
+
+### Visibility
+
+Hidden fields receive the `jsf-hidden` CSS class instead of inline `display: none`. Make sure your CSS includes:
+
+```css
+.jsf-hidden {
+  display: none;
+}
+```
+
+This is included in `jsf-defaults.css`.
+
+## Development
+
+```bash
+npm install          # Install dependencies
+npm run dev          # Start Vite dev server (port 3030)
+npm run build        # Bundle with esbuild → dist/index.js
+npm run types        # Generate type declarations → dist/*.d.ts
+npm run lint         # Run ESLint
+npm run lint:fix     # Run ESLint with auto-fix
+```
+
+## Publishing
+
+1. Update the version in `package.json`
+2. Run the publish script with your npm OTP:
+
+```bash
+./publish.sh <otp>
+```
+
+This cleans `dist/`, rebuilds the bundle and type declarations, copies `jsf-defaults.css` to `dist/`, and publishes to npm.
+
+The package is available at: https://www.npmjs.com/package/vanjs-jsf
+
+## Contributing
+
+Contributions are welcome! Please submit a pull request if you have ideas, feedback, or improvements. Your contributions will help make this library more robust and useful for the community.
+
+## License
+
+This project is licensed under the Apache 2 License. For details, see the [LICENSE](./LICENSE) file.

package/dist/VanJsfField.d.ts

@@ -16,11 +16,12 @@ export declare class VanJsfField extends VanJSComponent {
     isVisibleState: State<boolean>;
     errorState: State<string>;
     theme: JsfTheme;
+    layoutClass: string;
     /** Used by file fields to pass file metadata to formValues */
     fileNameValue: string;
     fileSizeValue: string;
     fileTypeValue: string;
-    constructor(field: Record<string, unknown>, initVal: MultiType, handleChange: (field: VanJsfField, value: MultiType) => void, theme?: JsfTheme);
+    constructor(field: Record<string, unknown>, initVal: MultiType, handleChange: (field: VanJsfField, value: MultiType) => void, theme?: JsfTheme, layoutClass?: string);
     get inputType(): string;
     get label(): string;
     get class(): string;

package/dist/VanJsfField.js

@@ -12,6 +12,7 @@ const { div, p, input, label, textarea, legend, link, fieldset, span, select, op
 var FieldType;
 (function (FieldType) {
     FieldType["text"] = "text";
+    FieldType["password"] = "password";
     FieldType["code"] = "code";
     FieldType["number"] = "number";
     FieldType["textarea"] = "textarea";
@@ -44,17 +45,19 @@ export class VanJsfField extends VanJSComponent {
     isVisibleState;
     errorState;
     theme;
+    layoutClass;
     /** Used by file fields to pass file metadata to formValues */
     fileNameValue = "";
     fileSizeValue = "";
     fileTypeValue = "";
-    constructor(field, initVal, handleChange, theme = {}) {
+    constructor(field, initVal, handleChange, theme = {}, layoutClass = "") {
         super();
         this.field = field;
         this.name = field.name;
         this.iniVal = initVal;
         this.handleChange = handleChange;
         this.theme = theme;
+        this.layoutClass = layoutClass;
         this.isVisibleState = van.state(this.field.isVisible);
         this.errorState = van.state("");
     }
@@ -167,9 +170,10 @@ export class VanJsfField extends VanJSComponent {
     render() {
         let el;
         const baseContainer = resolve(this.containerClass, this.theme.container);
+        const containerCls = this.layoutClass ? `${baseContainer} ${this.layoutClass}` : baseContainer;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const props = {
-            class: () => this.isVisible ? baseContainer : `${baseContainer} jsf-hidden`.trim(),
+            class: () => this.isVisible ? containerCls : `${containerCls} jsf-hidden`.trim(),
         };
         switch (this.inputType) {
             case FieldType.text:
@@ -181,6 +185,21 @@ export class VanJsfField extends VanJSComponent {
                     oninput: (e) => this.handleChange(this, e.target.value),
                 }), this.renderError());
                 break;
+            case FieldType.password:
+                // Password is rendered with type="password" so the user agent
+                // masks the value as it is typed. Otherwise behaves identically
+                // to a text input — same theme.input class, same oninput
+                // wiring. autocomplete="new-password" hints to browsers that
+                // this is a credential entry form, not a "remember me" field.
+                el = div(props, this.renderLabel(), this.renderDescription(), input({
+                    id: this.name,
+                    type: "password",
+                    autocomplete: "new-password",
+                    class: resolve(this.class, this.theme.input),
+                    value: this.iniVal,
+                    oninput: (e) => this.handleChange(this, e.target.value),
+                }), this.renderError());
+                break;
             case FieldType.textarea:
                 el = div(props, this.renderLabel(), this.renderDescription(), textarea({
                     id: this.name,

package/dist/VanJsfForm.js

@@ -10,7 +10,8 @@ class VanJsfForm {
     formFields;
     formValues;
     theme;
-    constructor(jsonSchema, config, isValid, theme = {}) {
+    layout;
+    constructor(jsonSchema, config, isValid, theme = {}, layout = {}) {
         // Bind methods to instance. Needed to pass functions as props to child components
         //this.handleSubmit = this.handleSubmit.bind(this);
         this.handleFieldChange = this.handleFieldChange.bind(this);
@@ -19,6 +20,7 @@ class VanJsfForm {
         this.config = config;
         this.isValid = isValid || undefined;
         this.theme = theme;
+        this.layout = layout;
         // Working with parameters
         const initialValues = { ...config?.initialValues };
         this.headlessForm = createHeadlessForm(jsonSchema, config);
@@ -100,7 +102,8 @@ class VanJsfForm {
                 field.fields = this.processFields(field.fields, initialValues, formValues, fieldPath);
             }
             // Create and return a new VanJsfField instance for this field
-            return new VanJsfField(field, initVal, this.handleFieldChange, this.theme);
+            const fieldLayout = this.layout[fieldPath] || this.layout[field.name] || "";
+            return new VanJsfField(field, initVal, this.handleFieldChange, this.theme, fieldLayout);
         });
     }
 }
@@ -115,7 +118,8 @@ export function jsform(attributes, ...children) {
         config.formValues = {};
     const isValid = attributes.isValid;
     const theme = attributes.theme ?? {};
-    const vanJsfForm = new VanJsfForm(attributes.schema, config, isValid, theme);
+    const layout = attributes.layout ?? {};
+    const vanJsfForm = new VanJsfForm(attributes.schema, config, isValid, theme, layout);
     const fields = vanJsfForm.formFields.map((field) => field.render());
     const childrenWithFields = [...fields, ...children]; // Concatenate fields with other children
     const originalOnSubmit = attributes.onsubmit;

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { jsform } from "./VanJsfForm";
-export type { JsfTheme } from "./theme";
+export type { JsfTheme, JsfLayout } from "./theme";