JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 442
  • Score
    100M100P100Q87003F
  • License MIT

Forms block for 23blocks SDK - dynamic forms, schemas, submissions, and form management

Package Exports

  • @23blocks/block-forms
  • @23blocks/block-forms/package.json

Readme

@23blocks/block-forms

Forms block for the 23blocks SDK - dynamic forms, schemas, and submissions.

npm version License: MIT

Installation

npm install @23blocks/block-forms @23blocks/transport-http

Overview

This package provides form building and submission functionality including:

  • Forms - Form definitions and configurations
  • Form Schemas - Field definitions and validations
  • Form Instances - Individual form submissions
  • Form Sets - Groups of related forms

Quick Start

import { createHttpTransport } from '@23blocks/transport-http';
import { createFormsBlock } from '@23blocks/block-forms';

const transport = createHttpTransport({
  baseUrl: 'https://api.yourapp.com',
  headers: () => {
    const token = localStorage.getItem('access_token');
    return token ? { Authorization: `Bearer ${token}` } : {};
  },
});

const forms = createFormsBlock(transport, {
  apiKey: 'your-api-key',
});

// List forms
const { data: formList } = await forms.forms.list();

// Submit a form
const submission = await forms.formInstances.submit({
  formId: 'form-id',
  data: {
    name: 'John Doe',
    email: 'john@example.com',
    message: 'Hello!',
  },
});

Services

forms - Form Management

// List forms
const { data: formList } = await forms.forms.list({
  limit: 20,
  status: 'active',
});

// Get form by ID
const form = await forms.forms.get('form-id');

// Create form
const newForm = await forms.forms.create({
  name: 'Contact Form',
  description: 'Contact us form',
  status: 'active',
  schemaId: 'schema-id',
});

// Update form
await forms.forms.update('form-id', {
  name: 'Updated Contact Form',
  status: 'inactive',
});

// Delete form
await forms.forms.delete('form-id');

formSchemas - Schema Management

// List schemas
const { data: schemas } = await forms.formSchemas.list();

// Get schema by ID
const schema = await forms.formSchemas.get('schema-id');

// Create schema
const newSchema = await forms.formSchemas.create({
  name: 'Contact Schema',
  fields: [
    {
      name: 'name',
      type: 'text',
      label: 'Your Name',
      required: true,
      validation: { minLength: 2, maxLength: 100 },
    },
    {
      name: 'email',
      type: 'email',
      label: 'Email Address',
      required: true,
    },
    {
      name: 'message',
      type: 'textarea',
      label: 'Message',
      required: true,
      validation: { minLength: 10, maxLength: 1000 },
    },
    {
      name: 'priority',
      type: 'select',
      label: 'Priority',
      options: ['low', 'medium', 'high'],
      defaultValue: 'medium',
    },
  ],
});

// Update schema
await forms.formSchemas.update('schema-id', {
  fields: [
    // updated fields
  ],
});

// Delete schema
await forms.formSchemas.delete('schema-id');

formInstances - Form Submissions

// List submissions
const { data: submissions } = await forms.formInstances.list({
  formId: 'form-id',
  status: 'submitted',
});

// Get submission by ID
const submission = await forms.formInstances.get('instance-id');

// Create a draft instance
const draft = await forms.formInstances.create({
  formId: 'form-id',
  data: {
    name: 'John',
  },
  status: 'draft',
});

// Update draft
await forms.formInstances.update('instance-id', {
  data: {
    name: 'John Doe',
    email: 'john@example.com',
  },
});

// Submit form
const submitted = await forms.formInstances.submit({
  formId: 'form-id',
  data: {
    name: 'John Doe',
    email: 'john@example.com',
    message: 'Hello, I have a question...',
  },
});

// Delete submission
await forms.formInstances.delete('instance-id');

formSets - Form Set Management

// List form sets
const { data: sets } = await forms.formSets.list();

// Get form set by ID
const formSet = await forms.formSets.get('set-id');

// Create form set
const newSet = await forms.formSets.create({
  name: 'Onboarding Forms',
  description: 'Forms required for new user onboarding',
  formReferences: [
    { formId: 'form-1', order: 1, required: true },
    { formId: 'form-2', order: 2, required: false },
    { formId: 'form-3', order: 3, required: true },
  ],
});

// Update form set
await forms.formSets.update('set-id', {
  formReferences: [
    { formId: 'form-1', order: 1, required: true },
    { formId: 'form-2', order: 2, required: true },
  ],
});

// Delete form set
await forms.formSets.delete('set-id');

Types

import type {
  Form,
  FormSchema,
  FormInstance,
  FormSet,
  FormReference,
  CreateFormRequest,
  CreateFormSchemaRequest,
  CreateFormInstanceRequest,
  SubmitFormInstanceRequest,
  CreateFormSetRequest,
} from '@23blocks/block-forms';

Form

Property Type Description
id string Form ID
uniqueId string Unique identifier
name string Form name
description string Form description
status string active, inactive, archived
schemaId string Associated schema ID
schema FormSchema Schema details

FormSchema

Property Type Description
id string Schema ID
name string Schema name
fields Field[] Field definitions
validations object Form-level validations

FormInstance

Property Type Description
id string Instance ID
formId string Parent form ID
data object Submitted data
status string draft, submitted, approved, rejected
submittedAt Date Submission timestamp

Error Handling

import { isBlockErrorException, ErrorCodes } from '@23blocks/contracts';

try {
  await forms.formInstances.submit({
    formId: 'form-id',
    data: { name: '' }, // Invalid - name is required
  });
} catch (error) {
  if (isBlockErrorException(error)) {
    switch (error.code) {
      case ErrorCodes.VALIDATION_ERROR:
        console.log('Form validation failed:', error.meta?.errors);
        break;
      case ErrorCodes.NOT_FOUND:
        console.log('Form not found');
        break;
    }
  }
}

License

MIT - Copyright (c) 2024 23blocks