Joyfill

https://docs.joyfill.io
Admin
Joyfill is an embeddable form builder platform providing SDKs and APIs for web and mobile...
Tokens:118,075
Snippets:892
Trust Score:8.8
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup React Project for Joyfill

Source: https://docs.joyfill.io/web/guides/sample-projects-react

Commands to initialize a new React application and install the required Joyfill components package.

```bash
npx create-react-app my-joyfill-app
cd my-joyfill-app
npm install @joyfill/components
```

--------------------------------

### Start Development Server

Source: https://docs.joyfill.io/web/guides/sample-projects-js-module

Executes the start script to launch the development server.

```bash
npm start
```

--------------------------------

### Install Joyfill Components SDK

Source: https://docs.joyfill.io/web/getting-started/Getting-Started

Commands to install the SDK using common package managers.

```bash
# Using npm
npm install @joyfill/components

# Using yarn
yarn add @joyfill/components

# Using pnpm
pnpm add @joyfill/components
```

--------------------------------

### Install Joyfill Components and Parcel

Source: https://docs.joyfill.io/web/guides/sample-projects-js-module

Set up a new project and install the necessary dependencies for Joyfill Components and Parcel, a build tool.

```bash
mkdir my-joyfill-app
cd my-joyfill-app
npm init -y
npm install @joyfill/components@latest
npm install --save-dev parcel
```

--------------------------------

### Install Joyfill Components via npm

Source: https://docs.joyfill.io/web/guides/pdf-generator-self-hosted

Use npm to install the Joyfill components package in your project.

```bash
npm install --save @joyfill/components
```

--------------------------------

### Complete JoyDoc Integration Example

Source: https://docs.joyfill.io/web/guides/formulas

This example demonstrates how to integrate JoyDoc with formula support enabled. It shows setting up the initial document state with fields and formulas, and handling updates via the onChange callback.

```jsx
import { useState } from 'react';
import { JoyDoc } from '@builttocreate/joyfill-components';

function InvoiceForm() {
  const [document, setDocument] = useState({
    _id: 'invoice_doc',
    identifier: 'invoice',
    name: 'Invoice Form',
    fields: [
      { _id: 'unit_price', type: 'number', value: 0 },
      { _id: 'quantity', type: 'number', value: 0 },
      { _id: 'discount_percent', type: 'number', value: 0 },
      {
        _id: 'subtotal',
        type: 'number',
        title: 'Subtotal',
        value: 0,
        formulas: [{ formula: 'calculateSubtotal', key: 'value' }]
      },
      {
        _id: 'discount_amount',
        type: 'number',
        title: 'Discount',
        value: 0,
        formulas: [{ formula: 'calculateDiscount', key: 'value' }]
      },
      {
        _id: 'total',
        type: 'number',
        title: 'Total',
        value: 0,
        formulas: [{ formula: 'calculateTotal', key: 'value' }]
      }
    ],
    formulas: [
      {
        _id: 'calculateSubtotal',
        desc: 'Calculate subtotal before discount',
        expression: 'unit_price * quantity'
      },
      {
        _id: 'calculateDiscount',
        desc: 'Calculate discount amount',
        expression: 'subtotal * (discount_percent / 100)'
      },
      {
        _id: 'calculateTotal',
        desc: 'Calculate final total',
        expression: 'subtotal - discount_amount'
      }
    ],
    files: [/* ... */]
  });

  return (
    <JoyDoc
      doc={document}
      features={{
        formulas: true  // Enable formulas
      }}
      onChange={(changelogs, updatedDoc) => {
        // Formulas are automatically resolved
        // updatedDoc contains all calculated values
        console.log('Document updated:', updatedDoc);
        setDocument(updatedDoc);
      }}
    />
  );
}

```

--------------------------------

### Complete Angular Integration Example

Source: https://docs.joyfill.io/web/guides/sample-projects-angular

A full implementation example of the AppComponent including error handling and saving state management.

```typescript
import { Component, OnInit, inject } from '@angular/core';
import { CommonModule } from '@angular/common';
import { JoyDoc } from '@joyfill/components/dist/joyfill.min.js';

import { JoyfillService } from './joyfill.service';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule],
  template: `
    <main>
      <header>
        <h1>🎉 Joyfill Components</h1>
        <p>Angular v17+ Integration Example</p>
        <button (click)="handleSave()" [disabled]="isSaving">
          {{ isSaving ? 'Saving...' : 'Save' }}
        </button>
      </header> 
      <div id="joyfill-target"></div>
    </main>
  `,
  styleUrl: './app.component.css'
})
export class AppComponent implements OnInit {

  joyfillService: JoyfillService = inject(JoyfillService);
  
  identifer = '<REPLACE WITH YOUR TEMPLATE IDENTIFIER>';
  pendingTemplate = {};
  isSaving = false;

  ngOnInit() {
    this.initJoyfill();
  }

  async initJoyfill() { 
    try {
      const template = await this.joyfillService.getTemplate(this.identifer);

      JoyDoc(
        document.getElementById('joyfill-target'),
        {
          doc: template,
          onChange: (changelogs, data) => {
            /**
             * changelogs - the individual changes
             * data - the entire new template with all changes applied
             */
            console.log(changelogs, data);
            this.pendingTemplate = data;
          },
          onError: (error) => {
            console.error('Joyfill error:', error);
          }
        }
      );
    } catch (error) {
      console.error('Error initializing Joyfill:', error);
    }
  }

  async handleSave() {
    if (this.isSaving) return;
    
    this.isSaving = true;
    try {
      const updatedTemplate = await this.joyfillService.updateTemplate(
        this.identifer, 
        this.pendingTemplate
      );
      console.log('Updated template:', updatedTemplate);
      alert('Template saved successfully!');
    } catch (error) {
      console.error('Error saving template:', error);
      alert('Error saving template');
    } finally {
      this.isSaving = false;
    }
  }

}
```

--------------------------------

### Install Joyfill Components

Source: https://docs.joyfill.io/web/guides/joydoc-exporter

Use a package manager to add the Joyfill components library to your project.

```bash
npm install --save @joyfill/components
```

```bash
yarn add @joyfill/components
```

--------------------------------

### Implement onFileDelete in fieldSettings

Source: https://docs.joyfill.io/web/guides/event-handling

Example of handling file deletion with confirmation and storage cleanup.

```jsx
// Configure in fieldSettings
const fieldSettings = {
  field: {
    onFileDelete: async (params, urlObject) => {
      console.log('File deleted:', urlObject);

      // Show confirmation dialog
      const confirmed = await showConfirmDialog(
        `Are you sure you want to delete ${urlObject.fileName}?`
      );

      if (confirmed) {
        // Delete from storage service
        await deleteFromStorage(urlObject.filePath);
      }

      return confirmed;
    }
  }
};

<JoyDoc
  fieldSettings={fieldSettings}
/>
```

--------------------------------

### Navigating with GotoConfig

Source: https://docs.joyfill.io/ios/guides/external-navigation

Examples of using GotoConfig to navigate to specific targets with different focus and modal behaviors.

```swift
// Navigate to a row and open its form for editing
let status = editor.goto("page_123/fieldPosition_456/row_789", gotoConfig: GotoConfig(open: true))

// Navigate to a field and trigger onFocus
let status = editor.goto("page_123/fieldPosition_456", gotoConfig: GotoConfig(focus: true))

// Navigate to a specific cell, open the row form, and focus the cell
let status = editor.goto("page_123/fieldPosition_456/row_789/column_012", gotoConfig: GotoConfig(open: true, focus: true))
```

--------------------------------

### Create Form with Default Document

Source: https://docs.joyfill.io/web/getting-started/Getting-Started

Example of initializing a form using getDefaultDocument and handling submission.

```jsx
import React, { useState } from 'react';
import { JoyDoc, getDefaultDocument } from '@joyfill/components';

function MyForm() {
  const [document, setDocument] = useState(() => {
    // Create a default document
    const doc = getDefaultDocument();

    // Add a text field
    doc.fields.push({
      _id: 'name-field',
      identifier: 'name',
      type: 'text',
      title: 'Your Name',
      value: '',
      file: doc.files[0]._id
    });

    // Add field position for layout
    doc.files[0].pages[0].fieldPositions.push({
      _id: 'name-position',
      field: 'name-field',
      x: 0,
      y: 0,
      width: 1,
      height: 1,
      displayType: 'original'
    });

    return doc;
  });

  const handleChange = (changelogs, updatedDoc) => {
    console.log('Form changed:', changelogs);
    setDocument(updatedDoc);
  };

  const handleSubmit = () => {
    // Extract form data
    const formData = {};
    document.fields.forEach(field => {
      formData[field.identifier] = field.value;
    });

    console.log('Form data:', formData);
    alert(`Hello, ${formData.name || 'Anonymous'}!`);
  };

  return (
    <div>
      <h1>My First Joyfill Form</h1>
      <JoyDoc
        doc={document}
        onChange={handleChange}
        mode="fill"
        width={816}
        height={600}
      />
      <button onClick={handleSubmit} style={{ marginTop: '20px' }}>
        Submit Form
      </button>
    </div>
  );
}

export default MyForm;
```

--------------------------------

### Install Joyfill Components via yarn

Source: https://docs.joyfill.io/web/guides/pdf-generator-self-hosted

Use yarn to add the Joyfill components package to your project.

```bash
yarn add @joyfill/components
```

--------------------------------

### PDF Export Response Example

Source: https://docs.joyfill.io/api/documents/create-a-document-pdf-export-using-raw-json-payload

This example shows the structure of a successful response when creating a document PDF export, providing URLs for downloading and previewing the generated file.

```json
{
  "download_url": "String",
  "preview_url": "String"
}
```

--------------------------------

### Implement onFileClick in fieldSettings

Source: https://docs.joyfill.io/web/guides/event-handling

Example of handling file clicks to open files in a new tab.

```jsx
// Configure in fieldSettings
const fieldSettings = {
  field: {
    onFileClick: (params, urlObject) => {
      console.log('File clicked:', urlObject);

      // Open file in new tab
      window.open(urlObject.url, '_blank');
    }
  }
};

<JoyDoc
  fieldSettings={fieldSettings}
/>
```

--------------------------------

### Basic Calculation Example

Source: https://docs.joyfill.io/web/guides/formulas

This example demonstrates a basic calculation for an invoice total using JoyDoc. The total is automatically recalculated when price or quantity changes.

```jsx
import { JoyDoc } from '@builttocreate/joyfill-components';

function InvoiceForm() {
  const [document, setDocument] = useState({
    fields: [
      { _id: 'price', type: 'number', value: 25.50 },
      { _id: 'quantity', type: 'number', value: 3 },
      {
        _id: 'total',
        type: 'number',
        title: 'Total',
        value: 0,
        formulas: [{ formula: 'calculateTotal', key: 'value' }]
      }
    ],
    formulas: [
      {
        _id: 'calculateTotal',
        desc: 'Calculate total price',
        expression: 'price * quantity'
      }
    ],
    files: [/* ... */]
  });

  return (
    <JoyDoc
      doc={document}
      features={{ formulas: true }}
      onChange={(changelogs, updatedDoc) => {
        // When price or quantity changes, total is automatically recalculated
        setDocument(updatedDoc);
      }}
    />
  );
}
```

--------------------------------

### Joyfill `onUploadAsync` Usage Example

Source: https://docs.joyfill.io/web/getting-started/Listening-for-changes

Example of implementing the `onUploadAsync` callback in a React component to handle file uploads and process responses.

```jsx
import { useState } from "react";
import { JoyDoc } from "@joyfill/components";

function MyForm() {
  const [document, setDocument] = useState(initialDocument);

  const handleUploadAsync = async (params, fileUploads) => {
    console.log("onUploadAsync: ", params, fileUploads);

    const resultPromises = await fileUploads.map(async (fileUpload) => {
      console.log("files uploaded");
      const dataUri = await getDataUriForFileUpload(fileUpload);
      return uploadFileAsync(params.identifier, dataUri);
    });

    return Promise.all(resultPromises)
      .then((responses) => {
        const finalResponse = Array.isArray(responses[0])
          ? responses[0]
          : responses;

        return finalResponse;
      })
      .catch((error) => {
        if (error) return;
      });
  };

  const handleChange = (changelogs, updatedDoc) => {
    console.log("Document changed:", changelogs);

    // Process each changelog
    changelogs.forEach((changelog) => {
      if (changelog.target === "field.update") {
        console.log("Field updated:", changelog.fieldId);
        console.log("Multi upload:", changelog.multi);

        // Check if this was a table field upload
        if (changelog.rowId && changelog.columnId) {
          console.log("Table field upload:", {
            fieldId: changelog.fieldId,
            rowId: changelog.rowId,
            columnId: changelog.columnId,
          });
        } else if (changelog.multi === true) {
          console.log(
            "Multiple images uploaded to normal field:",
            changelog.fieldId
          );
        }
      }
    });

    // Update document state
    setDocument(updatedDoc);
  };

  return (
    <JoyDoc
      doc={document}
      onChange={handleChange}
      onUploadAsync={handleUploadAsync}
    />
  );
}

// Helper functions
const getDataUriForFileUpload = async (file) => {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result);
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
};

const uploadFileAsync = async (identifier, dataUri, tableContext = null) => {
  const uploadData = {
    identifier,
    dataUri,
    ...(tableContext && {
      rowId: tableContext.rowId,
      columnId: tableContext.columnId,
    }),
  };

  const response = await fetch("/api/upload", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(uploadData),
  });

  const result = await response.json();
  return {
    _id: `upload-${Date.now()}`,
    url: result.url,
    fileName: result.fileName,
    filePath: result.filePath,
  };
};

```

--------------------------------

### Implement onFileUploadAsync in fieldSettings

Source: https://docs.joyfill.io/web/guides/event-handling

Example of configuring custom upload logic within fieldSettings.

```jsx
// Configure in fieldSettings
const fieldSettings = {
  field: {
    onFileUploadAsync: async (params, fileUploads) => {
      console.log('Field-specific upload:', params.fieldId, fileUploads);

      // Custom upload logic for this specific field
      const uploadPromises = fileUploads.map(async (file) => {
        const uploadedFile = await customUploadService(file, params.fieldId);

        return {
          url: uploadedFile.url,
          fileName: uploadedFile.fileName,
          filePath: uploadedFile.filePath
        };
      });

      return await Promise.all(uploadPromises);
    }
  }
};

<JoyDoc
  fieldSettings={fieldSettings}
/>
```

--------------------------------

### Table Operations Example

Source: https://docs.joyfill.io/web/guides/formulas

This example demonstrates how to perform operations on table data, including summing item revenues and filtering for high-value items. It shows access methods for table rows and columns.

```jsx
{
  fields: [
    {
      _id: 'orderItems',
      type: 'table',
      value: [
        { _id: 'r1', cells: { itemName: 'Widget', price: 10, quantity: 2 } },
        { _id: 'r2', cells: { itemName: 'Gadget', price: 20, quantity: 3 } },
        { _id: 'r3', cells: { itemName: 'Thing', price: 15, quantity: 1 } }
      ]
    },
    {
      _id: 'totalRevenue',
      type: 'number',
      title: 'Total Revenue',
      value: 0,
      formulas: [{ formula: 'calculateRevenue', key: 'value' }]
    },
    {
      _id: 'highValueCount',
      type: 'number',
      title: 'High Value Items',
      value: 0,
      formulas: [{ formula: 'countHighValue', key: 'value' }]
    }
  ],
  formulas: [
    {
      _id: 'calculateRevenue',
      desc: 'Sum of all item prices times quantities',
      expression: 'sum(map(orderItems, (row) => row.price * row.quantity))'
    },
    {
      _id: 'countHighValue',
      desc: 'Count items with revenue > 50',
      expression: 'length(filter(orderItems, (row) => row.price * row.quantity > 50))'
    }
  ]
}

**Table Access:**

* `table1[0]` - Access first row (zero-indexed)

* `table1[0].columnName` - Access specific column in first row

* In lambda functions: `(row) => row.columnName` - Access column by field ID
```

--------------------------------

### Implement Basic JoyDoc Component

Source: https://docs.joyfill.io/web/getting-started/Getting-Started

Basic setup for rendering a JoyDoc component with state management for document changes.

```jsx
import React, { useState } from 'react';
import { JoyDoc } from '@joyfill/components';

function App() {
  const [document, setDocument] = useState({
    _id: 'my-document',
    identifier: 'my-document',
    name: 'My First Form',
    files: [{
      _id: 'file1',
      name: 'Main File',
      pages: [{
        _id: 'page1',
        name: 'Page 1',
        fieldPositions: []
      }]
    }],
    fields: []
  });

  const handleChange = (changelogs, updatedDoc) => {
    console.log('Document changed:', changelogs);
    setDocument(updatedDoc);
  };

  return (
    <div style={{ width: '100%', maxWidth: '816px', margin: '0 auto' }}>
      <JoyDoc
        doc={document}
        onChange={handleChange}
        mode="edit"
        width={816}
        height={1056}
      />
    </div>
  );
}

export default App;
```

--------------------------------

### Example Usage of Form Component

Source: https://docs.joyfill.io/kotlin/changelogs/migration-guide

Demonstrates how to use the Form component with a rememberEditor and Mode.fill. This usage pattern remains consistent between v1 and v2.

```kotlin
Form(
    editor = rememberEditor(document = doc),
    mode = Mode.fill,
)
```

--------------------------------

### Basic Image Upload Handler

Source: https://docs.joyfill.io/kotlin/guides/image-upload-handling

Implement the `onUpload` callback to handle image uploads. This basic example returns a static URL.

```kotlin
Form(
    editor = rememberDocumentEditor(json),
    onUpload = { event ->
        listOf("https://picsum.photos/200/300")
    }
)
```

--------------------------------

### Implement onFileClick in JoyDoc

Source: https://docs.joyfill.io/web/getting-started/Listening-for-changes

Example showing how to handle file click events to open files or perform type-specific actions.

```jsx
function MyForm() {
  const handleFileClick = async (params, urlObject) => {
    console.log("File clicked:", {
      params,
      urlObject,
    });

    const { fieldId, fieldIdentifier } = params;
    const { url, fileName, _id: fileId } = urlObject;

    console.log("File details:", {
      fieldId,
      fieldIdentifier,
      fileId,
      fileName,
      url,
    });

    // Open file in new tab
    window.open(url, "_blank");

    // Or handle file action based on file type
    const fileExtension = fileName.split(".").pop().toLowerCase();
    if (["jpg", "jpeg", "png", "gif"].includes(fileExtension)) {
      // Handle image files
      console.log("Image file clicked:", fileName);
    } else if (["pdf"].includes(fileExtension)) {
      // Handle PDF files
      console.log("PDF file clicked:", fileName);
    }
  };

  const fieldSettings = {
    field: {
      onFileClick: async (params, urlObject) => {
        console.log("onFileClick: ", params, urlObject);
      },
    },
  };

  return <JoyDoc doc={document} onFileClick={handleFileClick} />;
}
```

--------------------------------

### Implement onChange Event Handler

Source: https://docs.joyfill.io/web/getting-started/Listening-for-changes

Example of handling document changes and updating state using the onChange prop.

```jsx
function MyForm() {
  const [document, setDocument] = useState(initialDocument);

  const handleChange = (changelogs, updatedDoc) => {
    console.log('Document changed:', changelogs);

    // Process each changelog
    changelogs.forEach(changelog => {
      console.log('Change type:', changelog.target);
      console.log('Field ID:', changelog.fieldId);
      console.log('Change data:', changelog.change);
    });

    // Update document state
    setDocument(updatedDoc);
  };

  return (
    <JoyDoc
      doc={document}
      onChange={handleChange}
    />
  );
}
```

--------------------------------

### Complete Data Population and Extraction Example

Source: https://docs.joyfill.io/web/guides/populating-and-extracting-data

A React component demonstrating both populating text/table fields and extracting data from them.

```jsx
import React, { useState } from "react";
import JoyDoc from "./JoyDoc";

const MyForm = () => {
  const [doc, setDoc] = useState(initialDoc);

  // Populate data function
  const populateData = () => {
    const updatedDoc = { ...doc };
    const updatedFields = [...doc.fields];

    // Populate text field
    const nameField = updatedFields.find((field) => field._id === "name-field");
    if (nameField) {
      nameField.value = "Jane Smith";
    }

    // Populate table field
    const tableField = updatedFields.find(
      (field) => field._id === "68ef815e4c716f176ea8d2ba"
    );
    if (tableField && tableField.type === "table") {
    
      const cells = {};
    
      tableField.tableColumns.forEach((column) => {
        if (column.type === "text") {
          cells[column._id] = "Table cell data";
        }
      });

      tableField.value = [{ _id: "row1", deleted: false, cells: { ...cells } }];
      tableField.rowOrder = ["row1"];
    }

    updatedDoc.fields = updatedFields;
    setDoc(updatedDoc);
  };

  // Extract data function
  const extractData = () => {
  
    // Extract text field
    const nameField = doc.fields.find((field) => field._id === "name-field");
    console.log("Name:", nameField?.value);

    // Extract table data
    const tableField = doc.fields.find(
      (field) => field._id === "68ef815e4c716f176ea8d2ba"
    );
    
    if (tableField && tableField.type === "table") {
    
      const tableData = tableField.value.map((row) => {
      
        const rowData = {};
       
        Object.keys(row.cells).forEach((columnId) => {
       
          const column = tableField.tableColumns.find(
            (col) => col._id === columnId
          );
       
          rowData[column.title] = row.cells[columnId];
       
        });
        return rowData;
        
      });
      console.log("Table data:", tableData);
    }
  };

  return (
    <div>
      <button onClick={populateData}>Populate Data</button>
      <button onClick={extractData}>Extract Data</button>

      <JoyDoc
        doc={doc}
        onChange={(changelog, updatedDoc) => {
          setDoc(updatedDoc);
        }}
      />
    </div>
  );
};
```

--------------------------------

### Implement onFileUploadAsync in JoyDoc

Source: https://docs.joyfill.io/web/getting-started/Listening-for-changes

Example showing how to handle file uploads and process field updates within the JoyDoc component.

```jsx
import { useState } from "react";
import { JoyDoc } from "@joyfill-components";

function MyForm() {
  const [document, setDocument] = useState(initialDocument);

  const handleFileUploadAsync = async (params, fileUploads) => {
    console.log("onFileUploadAsync params:", params);
    console.log("onFileUploadAsync files:", fileUploads);

    const uploadPromises = fileUploads.map(async (file) => {
      const dataUri = await getDataUriForFileUpload(file);
      return uploadFileAsync(params.identifier, dataUri);
    });

    const results = await Promise.all(uploadPromises);
    return results;
  };

  const handleChange = (changelogs, updatedDoc) => {
    console.log("Document changed:", changelogs);

    // Process each changelog
    changelogs.forEach((changelog) => {
      if (changelog.target === "field.update") {
        console.log("Field updated:", changelog.fieldId);

        // Check if this was a table field upload
        if (changelog.rowId && changelog.columnId) {
          console.log("Table field upload completed:", {
            fieldId: changelog.fieldId,
            rowId: changelog.rowId,
            columnId: changelog.columnId,
            multi: changelog.multi,
          });
        } else {
          console.log("Normal field upload completed:", {
            fieldId: changelog.fieldId,
            multi: changelog.multi,
          });
        }
      }
    });

    setDocument(updatedDoc);
  };

  const fieldSettings = {
    field: {
      onFileUploadAsync: async (params, fileUploads) => {
        console.log("onFileUploadAsync: ", params, fileUploads);
        return {
          _id: new Date().getTime(),
          url: "sampleImageUrl",
        };
      },
    },
  };
  
  return (
    <JoyDoc
      doc={document}
      onChange={handleChange}
			fieldSettings={fieldSettings}
    />
  );
}
```

--------------------------------

### File Upload/Capture Handlers: v2

Source: https://docs.joyfill.io/kotlin/changelogs/migration-guide

v2 example for handling file uploads and captures with ComponentEvent, demonstrating type checking on the source editor.

```kotlin
Form(
    onUpload = { e: ComponentEvent<joyfill.editors.file.AbstractFileEditor> ->
        // Optional: narrow by editor type
        when (val src = e.source) {
            is joyfill.editors.image.ImageEditor -> listOf("https://.../img1")
            is joyfill.editors.signature.SignatureEditor -> listOf("https://.../sig1")
            else -> emptyList()
        }
    },
    onCapture = { e: ComponentEvent<joyfill.editors.components.AbstractCompStringEditor> ->
        // Example for barcode/text-capable components
        when (e.source) {
            is joyfill.editors.barcode.BarcodeEditor -> "scanned-barcode"
            else -> null
        }
    },
)
```

--------------------------------

### OpenAPI Specification for Retrieve Group

Source: https://docs.joyfill.io/api/groups/retrieve-a-group

This OpenAPI 3.1.0 specification defines the GET /groups/{identifier} endpoint for retrieving group details. It includes parameters, request/response examples, and security schemes.

```yaml
openapi: 3.1.0
info:
  title: joyfill
  version: '1.1'
servers:
  - url: https://api-joy.joyfill.io/v1
security:
  - sec0: []
paths:
  /groups/{identifier}:
    get:
      summary: Retrieve a group
      operationId: retrieve-a-group
      parameters:
        - name: identifier
          in: path
          schema:
            type: string
          required: true
        - name: Authorization
          in: header
          description: >-
            Supports both API Key and User Access Token authorization. See
            https://joyfill.mintlify.app/api/authentication
          schema:
            type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: |-                    {
                      "_id": "String",
                      "identifer": "String",
                      "title": "String"
                    }
              schema:
                type: object
                properties:
                  _id:
                    type: string
                    example: String
                  identifer:
                    type: string
                    example: String
                  title:
                    type: string
                    example: String
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: |-                    {
                      "message": "Not Found"
                    }
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Found
      deprecated: false
      security: []
components:
  securitySchemes:
    sec0:
      type: http
      scheme: basic

```

--------------------------------

### Show Field When Another Field Is Filled

Source: https://docs.joyfill.io/web/guides/conditional-logic

This example demonstrates how to make a field visible (`show`) only when another specified field (`main_field`) has any value. The `hidden: true` property ensures the field starts out concealed.

```json
{
  _id: 'conditional_field',
  type: 'text',
  title: 'Additional Information',
  value: '',
  hidden: true,  // Start hidden
  logic: {
    action: 'show',
    eval: 'and',
    conditions: [
      {
        file: 'file1',
        page: 'page1',
        field: 'main_field',
        condition: '*=',  // is filled
        value: null        // Not needed for "is filled"
      }
    ]
  }
}
```

--------------------------------

### OpenAPI Specification for Listing Groups

Source: https://docs.joyfill.io/api/groups/list-all-groups

This OpenAPI 3.1.0 specification defines the GET /groups endpoint for listing all groups. It includes parameters for pagination and authorization, along with response examples for success and error cases.

```yaml
openapi: 3.1.0
info:
  title: joyfill
  version: '1.1'
servers:
  - url: https://api-joy.joyfill.io/v1
security:
  - sec0: []
paths:
  /groups:
    get:
      summary: List all groups
      operationId: list-all-groups
      parameters:
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. Limit can range
            between 1 and 100, and the default is 25.
          schema:
            type: integer
            format: int32
            default: 25
        - name: page
          in: query
          description: >-
            An integer for use with pagination. For instance, if limit is set to
            25 and you set page to 2 then results 26-50 will be returned.
          schema:
            type: integer
            format: int32
            default: 1
        - name: Authorization
          in: header
          description: >-
            Supports both API Key and User Access Token authorization. See
            https://joyfill.mintlify.app/api/authentication
          schema:
            type: string
      responses:
        '200':
          description: '200'
          content:
            text/plain:
              examples:
                Result:
                  value: |- 
                    {
                      "data": [Object, Object, ...]
                    }
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: |- 
                    {
                      "message": "Not Found"
                    }
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Not Found
      deprecated: false
      security: []
components:
  securitySchemes:
    sec0:
      type: http
      scheme: basic

```

--------------------------------

### Complete HTML Example for Joyfill Integration

Source: https://docs.joyfill.io/web/guides/sample-projects-js-module

This HTML file sets up the basic structure for a web page that will host a Joyfill form. It includes essential meta tags, CSS for styling, a container for the form, and a script tag to load the Joyfill module from './index.js'. Ensure that './index.js' is correctly referenced and contains the necessary Joyfill initialization code.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Joyfill Form - ES Module</title>
    <meta charset="UTF-8" />
    <style>
      body {
          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
          max-width: 800px;
          margin: 0 auto;
          padding: 20px;
          background-color: #f5f5f5;
      }

      .container {
          background: white;
          border-radius: 8px;
          padding: 30px;
          box-shadow: 0 2px 10px rgba(0,0,0,0.1);
      }

      h1 {
          color: #333;
          text-align: center;
          margin-bottom: 30px;
      }

      #joyfill-container {
          min-height: 500px;
      }
    </style>
  </head>
  <body>
    <div class="container">
      <h1>Contact Us</h1>
      <div id="joyfill-container"></div>
    </div>

    <script type="module" src="./index.js"></script>
  </body>
</html>
```

--------------------------------

### Navigator Initialization and Usage

Source: https://docs.joyfill.io/web/guides/external-navigation

Demonstrates how to initialize the Navigator and use its `goto` method for navigation within a JoyDoc component.

```APIDOC
## Navigator Initialization and Usage

### Description
Instantiate `Navigator` and pass it to the `JoyDoc` component via the `navigator` prop. Then call `navigator.goto(path)` with a path string whenever you want to navigate.

### Request Example
```jsx
import { JoyDoc, Navigator } from '@joyfill/components';

const navigator = new Navigator();

<JoyDoc navigator={navigator} doc={doc} mode="fill" />

// Later, from your code:
navigator.goto('page_123');
avigator.goto('page_123/fieldPosition_456');
```
```

--------------------------------

### Initialize Navigator and Use goto API

Source: https://docs.joyfill.io/web/guides/external-navigation

Instantiate the Navigator and pass it to the JoyDoc component. Then, use the navigator instance to navigate to specific pages or fields within the form.

```jsx
import { JoyDoc, Navigator } from '@joyfill/components';

const navigator = new Navigator();

<JoyDoc navigator={navigator} doc={doc} mode="fill" />

// Later, from your code:
navigator.goto('page_123');
avigator.goto('page_123/fieldPosition_456');
```

--------------------------------

### Schema Version Error Example

Source: https://docs.joyfill.io/web/guides/schema-validation

This example shows the structure of an error object when the document's schema version is incompatible with the SDK version (`ERROR_SCHEMA_VERSION`).

```json
{
  code: 'ERROR_SCHEMA_VERSION',
  message: 'Error detected with targeted schema version.',
  error: 'The targeted version of 1.0.0 is not supported. Version 2.0.0 must be used.',
  details: {
    schemaVersion: '2.0.0',
    sdkVersion: '3.1.4'
  }
}
```

--------------------------------

### Conditional Logic Example

Source: https://docs.joyfill.io/web/guides/formulas

This example shows how to implement conditional logic for calculating a grade based on a score using the 'iff' function. The result is 'B' when the score is 85.

```jsx
{
  fields: [
    { _id: 'score', type: 'number', value: 85 },
    {
      _id: 'grade',
      type: 'text',
      title: 'Grade',
      value: '',
      formulas: [{ formula: 'calculateGrade', key: 'value' }]
    }
  ],
  formulas: [
    {
      _id: 'calculateGrade',
      desc: 'Calculate grade based on score',
      expression: 'iff(score >= 90, "A", iff(score >= 80, "B", "C"))'
    }
  ]
}
// Result: grade = "B" when score = 85
```

--------------------------------

### Implement JoyDoc Form in React

Source: https://docs.joyfill.io/web/guides/sample-projects-react

A complete React component example demonstrating how to initialize the JoyDoc component, handle form changes, focus/blur events, and save the document state to a backend API.

```jsx
import React, { useState, useCallback } from 'react';
import { JoyDoc } from '@joyfill/components';

const JoyDocForm = () => {
  const [doc, setDoc] = useState(null);
  const [isLoading, setIsLoading] = useState(false);

  // Complete contact form example
  const contactForm = {
    "_id": "68f231604484695c16d65f97",
    "identifier": "doc_68f231604484695c16d65f97",
    "name": "New Doc",
    "files": [
        {
            "_id": "68f231607dee0bbd73994f87",
            "name": "New File",
            "pageOrder": [
                "68f23160b929e32e60e663a0"
            ],
            "pages": [
                {
                    "_id": "68f23160b929e32e60e663a0",
                    "name": "New Page",
                    "width": 816,
                    "height": 1056,
                    "rowHeight": 8,
                    "cols": 8,
                    "fieldPositions": [
                        {
                            "_id": "68f23164c57b7fe946d32b1b",
                            "type": "text",
                            "displayType": "original",
                            "x": 0,
                            "y": 0,
                            "width": 4,
                            "height": 8,
                            "field": "68f23164886cdb084afec912"
                        },
                        {
                            "_id": "68f231663b6a898390b23fec",
                            "type": "textarea",
                            "displayType": "original",
                            "x": 4,
                            "y": 0,
                            "width": 4,
                            "height": 23,
                            "field": "68f2316612113f6141fac40a"
                        },
                        {
                            "_id": "68f231673dc5e58c883c8437",
                            "type": "number",
                            "displayType": "original",
                            "x": 0,
                            "y": 8,
                            "width": 4,
                            "height": 8,
                            "field": "68f23167998040ea25a54fa8"
                        },
                        {
                            "_id": "68f231796f5ea38ae37f951b",
                            "type": "text",
                            "displayType": "original",
                            "x": 0,
                            "y": 16,
                            "width": 4,
                            "height": 8,
                            "field": "68f23179479739cf0883d27e"
                        }
                    ],
                    "layout": "grid",
                    "presentation": "normal",
                    "padding": 24
                }
            ],
            "styles": {
                "margin": 4
            }
        }
    ],
    "fields": [
        {
            "file": "68f231607dee0bbd73994f87",
            "_id": "68f23164886cdb084afec912",
            "type": "text",
            "title": "Name",
            "identifier": "field_68f23164886cdb084afec912"
        },
        {
            "file": "68f231607dee0bbd73994f87",
            "_id": "68f2316612113f6141fac40a",
            "type": "textarea",
            "title": "Comments",
            "identifier": "field_68f2316612113f6141fac40a",
            "value": ""
        },
        {
            "file": "68f231607dee0bbd73994f87",
            "_id": "68f23167998040ea25a54fa8",
            "type": "number",
            "title": "Phone number",
            "identifier": "field_68f23167998040ea25a54fa8"
        },
        {
            "file": "68f231607dee0bbd73994f87",
            "_id": "68f23179479739cf0883d27e",
            "type": "text",
            "title": "Email",
            "identifier": "field_68f23179479739cf0883d27e"
        }
    ],
    "type": "document"
  };

  const handleChange = useCallback((changelogs, updatedDoc) => {
    console.log('Form updated:', updatedDoc);
    console.log('Changes:', changelogs);
    setDoc(updatedDoc);
  }, []);

  const handleError = useCallback((error) => {
    console.error('Form error:', error);
  }, []);

  const handleFocus = useCallback((fieldId, fieldData) => {
    console.log('Field focused:', fieldId);
  }, []);

  const handleBlur = useCallback((fieldId, fieldData) => {
    console.log('Field blurred:', fieldId);
  }, []);

  const saveForm = async () => {
    if (!doc) return;

    setIsLoading(true);
    try {
      const response = await fetch('/api/contact', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(doc)
      });

      if (response.ok) {
        console.log('Form saved successfully');
        alert('Form saved successfully!');
      } else {
        console.error('Failed to save form');
        alert('Failed to save form');
      }
    } catch (error) {
```

--------------------------------

### Schema Validation Error Example

Source: https://docs.joyfill.io/web/guides/schema-validation

This example illustrates the structure of an error object when the document structure does not match the expected schema (`ERROR_SCHEMA_VALIDATION`), including details about the specific validation failures.

```json
{
  code: 'ERROR_SCHEMA_VALIDATION',
  message: 'Error detected during schema validation',
  details: {
    schemaVersion: '2.0.0',
    sdkVersion: '3.1.4'
  },
  errors: [
    {
      instancePath: '/fields/0',
      schemaPath: '#/properties/fields/items/required',
      keyword: 'required',
      params: { missingProperty: 'type' },
      message: "must have required property 'type'"
    }
  ]
}
```

--------------------------------

### String Operations Example

Source: https://docs.joyfill.io/web/guides/formulas

This example demonstrates combining text fields to create a full name using the 'concat' function. The result is 'John Doe' when first_name is 'John' and last_name is 'Doe'.

```jsx
{
  fields: [
    { _id: 'first_name', type: 'text', value: 'John' },
    { _id: 'last_name', type: 'text', value: 'Doe' },
    {
      _id: 'full_name',
      type: 'text',
      title: 'Full Name',
      value: '',
      formulas: [{ formula: 'combineNames', key: 'value' }]
    }
  ],
  formulas: [
    {
      _id: 'combineNames',
      desc: 'Combine first and last name',
      expression: 'concat(first_name, " ", last_name)'
    }
  ]
}
// Result: full_name = "John Doe"
```

--------------------------------

### Build for Production

Source: https://docs.joyfill.io/web/guides/sample-projects-js-module

This command builds the project for production, optimizing files for deployment. The output is placed in the `dist/` folder.

```bash
npm run build
```

--------------------------------

### GET /users/{identifier}

Source: https://docs.joyfill.io/api/users/retrieve-a-user

Retrieves a specific user by their identifier.

```APIDOC
## GET /users/{identifier}

### Description
Retrieve a user from the Joyfill platform using their unique identifier.

### Method
GET

### Endpoint
https://api-joy.joyfill.io/v1/users/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The unique identifier of the user.

### Response
#### Success Response (200)
- **type** (string) - User type
- **identifer** (string) - User identifier
- **group** (string) - User group

#### Response Example
{
  "type": "String",
  "identifer": "String",
  "group": "String"
}
```

--------------------------------

### Complete Form Structure with Logic

Source: https://docs.joyfill.io/web/guides/conditional-logic

This example demonstrates a full form configuration with fields and pages, including logic to conditionally show or hide elements based on user input. Ensure fields are initially hidden if they are meant to appear based on logic.

```jsx
{
  fields: [
    {
      _id: 'customer_type',
      type: 'dropdown',
      title: 'Customer Type',
      value: '',
      options: [
        { _id: 'opt1', value: 'individual' },
        { _id: 'opt2', value: 'business' }
      ]
    },
    {
      _id: 'business_name',
      type: 'text',
      title: 'Business Name',
      value: '',
      hidden: true,  // Hidden by default
      logic: {
        action: 'show',
        eval: 'and',
        conditions: [
          {
            file: 'file1',
            page: 'page1',
            field: 'customer_type',
            condition: '=',
            value: 'business'
          }
        ]
      }
    },
    {
      _id: 'individual_ssn',
      type: 'text',
      title: 'Social Security Number',
      value: '',
      hidden: true,  // Hidden by default
      logic: {
        action: 'show',
        eval: 'and',
        conditions: [
          {
            file: 'file1',
            page: 'page1',
            field: 'customer_type',
            condition: '=',
            value: 'individual'
          }
        ]
      }
    },
    {
      _id: 'total_amount',
      type: 'number',
      title: 'Total Amount',
      value: 0
    },
    {
      _id: 'discount_field',
      type: 'number',
      title: 'Discount',
      value: 0,
      logic: {
        action: 'hide',
        eval: 'and',
        conditions: [
          {
            file: 'file1',
            page: 'page1',
            field: 'total_amount',
            condition: '<',
            value: 1000
          }
        ]
      }
    }
  ],
  files: [
    {
      _id: 'file1',
      pages: [
        {
          _id: 'page1',
          name: 'Customer Information',
          fieldPositions: [
            // ... field positions
          ]
        },
        {
          _id: 'page2',
          name: 'Additional Details',
          hidden: true,
          logic: {
            action: 'show',
            eval: 'and',
            conditions: [
              {
                file: 'file1',
                page: 'page1',
                field: 'total_amount',
                condition: '>',
                value: 5000
              }
            ]
          },
          fieldPositions: [
            // ... field positions
          ]
        }
      ]
    }
  ]
}
```
Tokens:
Raw