dynamic-ui-kit

A framework-agnostic, JSON-driven UI component library for building dynamic tables, forms, and modals with React.

Features

• 📋 JSON-driven configuration - Define tables and forms with simple JSON
• 🔌 Adapter pattern - Plug in any backend/API with service adapters
• 🧩 Extensible field system - Register custom field components
• ✅ Built-in validation - Comprehensive validation with conditional logic
• 🎣 Powerful hooks - Reusable state management for pagination, forms, selection
• 🔧 Config validation - Validate JSON configs at development time
• 📦 Tree-shakeable - Import only what you need

Installation

npm install dynamic-ui-kit
# or
yarn add dynamic-ui-kit

Quick Start

Using Hooks

import { usePaginatedData, useFormState } from 'dynamic-ui-kit';

function MyTable() {
  const { state, actions, getPageData } = usePaginatedData({
    initialData: myData,
    pageSize: 10,
  });

  return (
    <table>
      <tbody>
        {getPageData().map(row => (
          <tr key={row.id}>...</tr>
        ))}
      </tbody>
    </table>
  );
}

function MyForm() {
  const { values, errors, getFieldProps, handleSubmit } = useFormState({
    initialValues: { name: '', email: '' },
    sections: formConfig.sections,
    onSubmit: (data) => saveData(data),
  });

  return (
    <form onSubmit={handleSubmit}>
      <input {...getFieldProps('name')} />
      <input {...getFieldProps('email')} />
      <button type="submit">Save</button>
    </form>
  );
}

Using Service Adapters

import { createServiceAdapter } from 'dynamic-ui-kit';

const productsService = createServiceAdapter({
  baseUrl: '/api',
  entityName: 'products',
  headers: () => ({
    'Authorization': `Bearer ${getToken()}`,
  }),
});

// Fetch paginated data
const { data, total, page } = await productsService.list({
  page: 1,
  pageSize: 20,
  search: 'widget',
  sortColumn: 'name',
  sortDirection: 'asc',
});

// CRUD operations
await productsService.create({ name: 'New Product' });
await productsService.update(1, { name: 'Updated Product' });
await productsService.delete(1);

Using the Field Registry

import { 
  FieldRegistry, 
  registerField, 
  useFieldFactory 
} from 'dynamic-ui-kit';

// Register a custom field
registerField({
  type: 'color-picker',
  component: ColorPickerField,
  displayName: 'Color Picker',
});

// Use in a component
function DynamicForm({ config }) {
  const { renderSection } = useFieldFactory();
  const { values, handleChange, errors, touched } = useFormState({...});

  return (
    <form>
      {config.sections.map(section =>
        renderSection(section, values, {
          onChange: handleChange,
          errors,
          touched,
        })
      )}
    </form>
  );
}

Validating Configuration

import { validateConfig, parseConfig } from 'dynamic-ui-kit';

// Validate a config
const result = validateConfig(rawConfig);
if (!result.valid) {
  console.error('Config errors:', result.errors);
}

// Parse and normalize config
const tableConfig = parseConfig(rawTableJson, {
  generateLabels: true,
  defaultSortable: true,
});

Module Exports

The library supports tree-shaking with multiple entry points:

// Main entry (all exports)
import { usePaginatedData, validateConfig } from 'dynamic-ui-kit';

// Core utilities
import { formatValue, cn, debounce } from 'dynamic-ui-kit/core';

// Hooks only
import { useFormState, useTableSelection } from 'dynamic-ui-kit/hooks';

// Adapters
import { createServiceAdapter, createAxiosAdapter } from 'dynamic-ui-kit/adapters';

// Field system
import { FieldRegistry, TextField, baseFields } from 'dynamic-ui-kit/fields';

// Config system
import { validateFormConfig, parseTableConfig } from 'dynamic-ui-kit/config';

API Reference

Hooks

Hook	Description
usePaginatedData	Pagination, sorting, search state management
useFormState	Form values, validation, touched state
useColumnConfig	Column visibility, ordering, resizing
useTableSelection	Single/multiple row selection
useFieldFactory	Render fields from JSON config
useFieldRegistry	Access the field component registry

Adapters

Adapter	Description
createServiceAdapter	Fetch-based API adapter
createAxiosAdapter	Axios-based API adapter
createFormAdapter	Form data transformation adapter

Field Components

Component	Type
TextField	text, email, password, tel, url
NumberField	number, percent
CurrencyField	currency
TextareaField	textarea
SelectField	select
CheckboxField	checkbox
SwitchField	switch
HiddenField	hidden

Config Validators

Function	Description
validateTableConfig	Validate table JSON config
validateFormConfig	Validate form JSON config
validateConfig	Auto-detect and validate config
parseTableConfig	Parse and normalize table config
parseFormConfig	Parse and normalize form config

Components

Component	Description
TableRenderer	Configurable data table with pagination, sorting, filtering, and selection
FormRenderer	Dynamic form renderer with sections, validation, and conditional fields
DynamicModal	Modal wrapper with tabs, forms, and action buttons

Theming

The library supports light/dark theming:

• By default components follow the user's operating system preference via prefers-color-scheme.
• Components accept a theme prop with values 'system', 'light', or 'dark' to force a specific theme per component.

Using TableRenderer

import { TableRenderer } from 'dynamic-ui-kit';
import 'dynamic-ui-kit/styles';

const tableConfig = {
  columns: [
    { key: 'name', header: 'Name', sortable: true },
    { key: 'email', header: 'Email' },
    { key: 'status', header: 'Status', type: 'badge' },
  ],
  pagination: { enabled: true, pageSize: 10 },
};

function UserTable() {
  const [users, setUsers] = useState([]);
  const [page, setPage] = useState(1);

  return (
    <TableRenderer
      config={tableConfig}
      data={users}
      totalCount={100}
      page={page}
      pageSize={10}
      onPageChange={setPage}
      onRowClick={(row) => console.log('Clicked:', row)}
      selectable
      selectionMode="multiple"
      onSelectionChange={(ids) => console.log('Selected:', ids)}
      striped
      hoverable
    />
  );
}

TableRenderer Props

Prop	Type	Description
config	TableConfig	Table configuration object
data	T[]	Data array to display
totalCount	number	Total records for pagination
page	number	Current page (1-indexed)
pageSize	number	Items per page
loading	boolean	Show loading state
error	string	Error message to display
onPageChange	(page: number) => void	Page change callback
onSortChange	(sort) => void	Sort change callback
onRowClick	(row, index) => void	Row click callback
selectable	boolean	Enable row selection
selectionMode	'single' | 'multiple'	Selection mode
striped	boolean	Stripe alternate rows
hoverable	boolean	Add hover effect
bordered	boolean	Add cell borders
compact	boolean	Compact padding
stickyHeader	boolean	Sticky header on scroll
theme	'system' | 'light' | 'dark'	Theme mode for the table. Defaults to system (follows prefers-color-scheme).
renderActions	(row, index) => ReactNode	Custom actions column

Using FormRenderer

import { FormRenderer } from 'dynamic-ui-kit';
import 'dynamic-ui-kit/styles';

const formConfig = {
  id: 'product-form',
  title: 'Edit Product',
  sections: [
    {
      id: 'basic',
      title: 'Basic Information',
      columns: 2,
      fields: [
        { name: 'name', type: 'text', label: 'Product Name', required: true },
        { name: 'sku', type: 'text', label: 'SKU' },
        { name: 'description', type: 'textarea', label: 'Description', colSpan: 2 },
      ],
    },
    {
      id: 'pricing',
      title: 'Pricing',
      collapsible: true,
      fields: [
        { name: 'price', type: 'currency', label: 'Price', required: true },
        { name: 'cost', type: 'currency', label: 'Cost' },
        { 
          name: 'margin', 
          type: 'percent', 
          label: 'Margin',
          computed: { formula: '(price - cost) / price * 100', deps: ['price', 'cost'] }
        },
      ],
    },
  ],
};

function ProductForm() {
  const formRef = useRef<FormRendererRef>(null);
  const [values, setValues] = useState({ name: '', price: 0 });

  const handleSubmit = async (data) => {
    await api.post('/products', data);
  };

  return (
    <FormRenderer
      ref={formRef}
      config={formConfig}
      values={values}
      onChange={(name, value, allValues) => setValues(allValues)}
      onSubmit={handleSubmit}
      onCancel={() => history.back()}
    />
  );
}

FormRenderer Props

Prop	Type	Description
config	FormConfig	Form configuration object
values	T	Current form values (controlled)
initialValues	T	Initial values (uncontrolled)
errors	FormErrors	External validation errors
onSubmit	(values: T) => void	Form submit handler
onCancel	() => void	Cancel button handler
onChange	(name, value, values) => void	Field change handler
loading	boolean	Disable form while loading
disabled	boolean	Disable all fields
readOnly	boolean	Make all fields read-only
renderField	(props) => ReactNode	Custom field renderer
renderSection	(props) => ReactNode	Custom section renderer
hideButtons	boolean	Hide submit/cancel buttons
header	ReactNode	Custom header content
footer	ReactNode	Custom footer content

Using DynamicModal

import { DynamicModal } from 'dynamic-ui-kit';
import 'dynamic-ui-kit/styles';

function EditProductModal({ product, isOpen, onClose }) {
  return (
    <DynamicModal
      open={isOpen}
      onClose={onClose}
      title="Edit Product"
      subtitle={`Editing: ${product.name}`}
      size="lg"
      config={formConfig}
      initialValues={product}
      onSubmit={async (values) => {
        await api.put(`/products/${product.id}`, values);
        onClose();
      }}
      onDelete={async () => {
        await api.delete(`/products/${product.id}`);
        onClose();
      }}
      deleteConfirmation={{
        title: 'Delete Product',
        message: 'Are you sure? This action cannot be undone.',
        confirmLabel: 'Delete',
        confirmVariant: 'danger',
      }}
    />
  );
}

// With Tabs
function TabbedModal() {
  return (
    <DynamicModal
      open={true}
      onClose={() => {}}
      title="Product Details"
      tabs={[
        { id: 'info', label: 'Information', content: infoFormConfig },
        { id: 'pricing', label: 'Pricing', content: pricingFormConfig },
        { id: 'inventory', label: 'Inventory', content: inventoryFormConfig },
      ]}
      onSubmit={handleSave}
    />
  );
}

DynamicModal Props

Prop	Type	Description
theme	'system' | 'light' | 'dark'	(Optional) Force modal theme. Defaults to system which follows user's prefers-color-scheme.

Prop	Type	Description
open	boolean	Whether modal is visible
onClose	() => void	Close handler
title	string	Modal title
subtitle	string	Modal subtitle
size	'sm' | 'md' | 'lg' | 'xl' | 'full'	Modal size
config	FormConfig	Form configuration
tabs	ModalTab[]	Tab configurations
initialValues	T	Initial form values
onSubmit	(values: T) => void	Submit handler
onDelete	() => void	Delete handler (shows delete button)
actions	ModalAction[]	Custom action buttons
loading	boolean	Loading state
error	string	Error message
closeOnBackdropClick	boolean	Close on overlay click
closeOnEscape	boolean	Close on Escape key
deleteConfirmation	ConfirmationConfig	Delete confirmation dialog

Styling

Import the CSS styles to use the default styling:

// Import all styles
import 'dynamic-ui-kit/styles';

// Or import specific component styles
import 'dynamic-ui-kit/styles/table';
import 'dynamic-ui-kit/styles/form';
import 'dynamic-ui-kit/styles/modal';

The styles use CSS custom properties for easy theming:

:root {
  /* Table variables */
  --dui-table-primary: #3b82f6;
  --dui-table-bg: #ffffff;
  --dui-table-border-color: #e5e7eb;
  --dui-table-header-bg: #f9fafb;

  /* Form variables */
  --dui-form-primary: #3b82f6;
  --dui-form-bg: #ffffff;
  --dui-form-border-color: #d1d5db;
  --dui-form-text-error: #ef4444;

  /* Modal variables */
  --dui-modal-primary: #3b82f6;
  --dui-modal-bg: #ffffff;
  --dui-modal-overlay-bg: rgba(0, 0, 0, 0.5);
  /* ... more variables */
}

/* Dark mode is automatically supported via @media (prefers-color-scheme: dark) */

Internationalization (i18n)

The library includes built-in i18n support:

import { I18nProvider, initI18n } from 'dynamic-ui-kit';

// Initialize with Spanish
initI18n({ locale: 'es' });

// Or use the provider
function App() {
  return (
    <I18nProvider locale="es">
      <MyApp />
    </I18nProvider>
  );
}

Supported translations include form validation messages, table pagination, and more.

By default the library ships a canonical set of translations (defaultEnTranslations / defaultEsTranslations). If you want to override or extend translations from your application, pass a partial translations map to initI18n(...) — the library will deep-merge your translations with its defaults so missing keys fall back to the canonical set. You can also call getI18n().addTranslations(locale, {...}) at runtime to merge additional keys.

Configuration Examples

Table Configuration

{
  "columns": [
    { "key": "name", "header": "Product Name", "sortable": true },
    { "key": "price", "header": "Price", "type": "currency" },
    { "key": "stock", "header": "Stock", "type": "number" },
    { "key": "status", "header": "Status", "type": "badge" }
  ],
  "pagination": { "pageSize": 20 },
  "selectable": true
}

Form Configuration

{
  "entity": "product",
  "sections": [
    {
      "title": "Basic Info",
      "fields": [
        { "name": "name", "type": "text", "required": true },
        { "name": "description", "type": "textarea" },
        { 
          "name": "price", 
          "type": "currency", 
          "validation": [{ "min": 0, "message": "Price must be positive" }]
        }
      ]
    },
    {
      "title": "Inventory",
      "showWhen": { "field": "trackInventory", "operator": "eq", "value": true },
      "fields": [
        { "name": "stock", "type": "number", "min": 0 },
        { "name": "lowStockThreshold", "type": "number" }
      ]
    }
  ]
}

Development

# Install dependencies
npm install

# Build the library
npm run build

# Type check
npm run typecheck

# Run tests
npm test

# Development mode (watch)
npm run dev

License

MIT © Leandro Fusco

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.