@wpmvc/fields

JSKit Fields

JSKit Fields is a flexible, extensible React field/component library for building dynamic, maintainable forms in WordPress plugins and applications. It supports a wide range of field types, grouping, conditional logic, and custom layouts—all with a simple, declarative configuration.

---

Installation

Install via your preferred package manager:

npm install @wpmvc/fields
# or
yarn add @wpmvc/fields
# or
pnpm add @wpmvc/fields

---

Features

• Comprehensive field types: Text, number, switch, checkbox, color, select, radio, slider, toggle group, repeater, tabs, group, panel, border, dimension, notice, row, and more.
• Composable: Nest fields inside groups, panels, tabs, repeaters, and rows.
• Declarative config: Define your form structure with a simple JS object.
• Conditional logic: Show/hide fields based on attribute values.
• TypeScript support: Strongly typed for safety and autocompletion.

---

Field Types Overview

Below is a quick reference table of all available field types. Click any field type to jump to its configuration and usage example.

Field Type	Description	Example Section
text	Single line text input	Text
number	Numeric input	Number
switch	Toggle switch	Switch
checkbox	Checkbox input	Checkbox
tabs	Tabbed field groups	Tabs
color	Color picker	Color
colors	Color palette/group	Colors
group	Grouped fields	Group
border	Border settings	Border
dimension	Dimension input	Dimension
notice	Info/warning/error notice	Notice
panel	Collapsible panel group	Panel
radio	Radio button group	Radio
select	Dropdown select	Select
slider	Range slider	Slider
toggleGroup	Toggle button group	Toggle Group
repeater	Repeatable field group	Repeater
row	Row layout for fields	Row

---

Usage Example

You can use JSKit Fields by passing a fields config and state handlers to the <Fields /> component.

Recommended: Use the useAttributes hook to manage attributes state.

import { Fields, useAttributes } from '@wpmvc/fields';

const fields = {
  text: {
    type: 'text',
    label: 'Text Field',
    description: 'A simple text input',
    required: true,
  },
  // ...other fields
};

function MyForm() {
  const [attributes, setAttributes] = useAttributes({});

  return (
    <Fields
      fields={fields}
      attributes={attributes}
      setAttributes={setAttributes}
    />
  );
}

---

Registering Custom Components

You can extend or override field types by passing a components prop to <Fields />.
This allows you to register your own custom field components or replace existing ones.

import { Fields, useAttributes } from '@wpmvc/fields';
import MyCustomField from './MyCustomField';

const fields = {
  custom: {
    type: 'custom',
    label: 'Custom Field',
    description: 'This is a custom field.',
  },
};

const components = {
  custom: MyCustomField,
  // You can override built-in types too, e.g. text: MyTextField
};

function MyForm() {
  const [attributes, setAttributes] = useAttributes({});

  return (
    <Fields
      fields={fields}
      attributes={attributes}
      setAttributes={setAttributes}
      components={components}
    />
  );
}

---

Using Fields in Gutenberg Block InspectorControls

You can easily use JSKit Fields inside a Gutenberg block’s InspectorControls panel to provide a dynamic, extensible settings UI for your block.

import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody } from '@wordpress/components';
import { Fields, useAttributes } from '@wpmvc/fields';

const fields = {
  text: {
    type: 'text',
    label: 'Text Field',
    description: 'A simple text input',
    required: true,
  },
  color: {
    type: 'color',
    label: 'Color Picker',
    description: 'Pick a color',
  },
  // ...add more fields as needed
};

export default function Edit({ attributes, setAttributes }) {
  return (
    <>
      <InspectorControls>
          <Fields
            fields={fields}
            attributes={attributes}
            setAttributes={setAttributes}
          />
      </InspectorControls>
      {/* ...your block output... */}
    </>
  );
}

Tips:

• Pass your block’s attributes and setAttributes directly to <Fields /> for seamless integration.
• You can use all field types and custom components as shown in previous sections.

---

Field Configuration Examples

Each field type is configured using a simple JavaScript object. You can nest, combine, and customize these fields to create advanced forms.

---

Text

A single-line text input.

{
  type: 'text',
  label: 'Text Field',
  description: 'A simple text input',
  required: true,
}

---

Number

A numeric input with optional min, max, and step.

{
  type: 'number',
  label: 'Number Field',
  min: 0,
  max: 100,
  description: 'A number input',
}

---

Switch

A boolean toggle switch.

{
  type: 'switch',
  label: 'Switch Field',
  description: 'A toggle switch',
}

---

Checkbox

A single checkbox input.

{
  type: 'checkbox',
  label: 'Checkbox Field',
  description: 'A single checkbox',
}

---

Tabs

Tabbed navigation for grouping fields.

{
  type: 'tabs',
  label: 'Tabs Field',
  items: {
    tab1: { label: 'Tab 1', fields: {} },
    tab2: {
      label: 'Tab 2',
      fields: {
        tab1: { type: 'text', label: 'Tab 1 Content' },
        tab2: { type: 'number', label: 'Tab 2 Content' },
      },
    },
  },
}

---

Color

A color picker input.

{
  type: 'color',
  label: 'Color Picker',
  description: 'Pick a color',
}

---

Colors

A palette or group of color pickers.

{
  type: 'colors',
  label: 'Color Palette',
  items: {
    color: {
      label: 'Color',
      showByDefault: true,
      colors: {
        default: { label: 'Default' },
        hover: { label: 'Hover' },
      },
    },
    background: {
      label: 'Background',
      showByDefault: false,
      colors: {
        default: { label: 'Default' },
        hover: { label: 'Hover' },
      },
    },
  },
  description: 'Choose from palette',
}

---

Group

Group multiple fields together.

{
  type: 'group',
  label: 'Group Field',
  fields: {
    groupText: { type: 'text', label: 'Group Text' },
    groupNumber: { type: 'number', label: 'Group Number' },
  },
}

---

Border

Border settings input.

{
  type: 'border',
  label: 'Border Field',
  description: 'Set border properties',
}

---

Dimension

Input for width, height, or other dimensions.

{
  type: 'dimension',
  label: 'Dimension Field',
  description: 'Set width and height',
}

---

Notice

Display an informational, warning, or error notice.

{
  type: 'notice',
  notice: 'This is an info notice.',
  status: 'info', // can be 'info', 'warning', 'error', etc.
}

---

Panel

A collapsible panel for grouping fields.

{
  type: 'panel',
  label: 'Panel Field',
  fields: {
    panelText: { type: 'text', label: 'Panel Text' },
    panelSwitch: { type: 'switch', label: 'Panel Switch' },
  },
}

---

Radio

A group of radio buttons.

{
  type: 'radio',
  label: 'Radio Field',
  options: [
    { label: 'Radio 1', value: '1' },
    { label: 'Radio 2', value: '2' },
  ],
  description: 'Choose one',
}

---

Select

A dropdown select input.

{
  type: 'select',
  label: 'Select Field',
  options: [
    { label: 'Select 1', value: '1' },
    { label: 'Select 2', value: '2' },
  ],
  description: 'Select an option',
}

---

Slider

A range slider input.

{
  type: 'slider',
  label: 'Slider Field',
  min: 0,
  max: 10,
  description: 'Slide to choose',
}

---

Toggle Group

A group of toggle buttons.

{
  type: 'toggleGroup',
  label: 'Toggle Group Field',
  options: [
    { label: 'A', value: 'a' },
    { label: 'B', value: 'b' },
    { label: 'C', value: 'c' },
  ],
  description: 'Toggle between options',
}

---

Repeater

Repeatable group of fields.

{
  type: 'repeater',
  label: 'Repeater Field',
  fields: {
    repeaterText: { type: 'text', label: 'Repeater Text' },
    repeaterNumber: { type: 'number', label: 'Repeater Number' },
  },
  description: 'Add multiple items',
}

---

Row

Layout fields in a row.

{
  type: 'row',
  label: 'Row Field',
  fields: {
    rowText: { type: 'text', label: 'Row Text' },
    rowSwitch: { type: 'number', label: 'Row Number' },
  },
}

---

Tips & Best Practices

• Nesting: You can nest fields inside group, panel, tabs, repeater, and row for advanced layouts.
• Conditional Logic: Add a condition function to any field to control its visibility based on current attributes.
• Custom Components: Pass a components prop to <Fields /> to override or extend field types.
• TypeScript: All field configs are fully typed for safety and autocompletion.

---

License

MIT