React Datatable

The datetable package is built on top of @tanstack/react-table and chakra-ui to create a datatable. This hook simplifies to initialize the state management for controlling the datatable, and it offers several predefined tables and controls in to enhance data visualization.

Installation

npm install @tanstack/react-table @chakra-ui/react @emotion/react @bsol-oss/react-datatable5

For form validation features with internationalization support, also install:

npm install ajv ajv-formats ajv-i18n

Usage

Hook

The DataTable and DataTableServer utilize hook to add props.

const datatable = useDataTable();
const datatableServer = useDataTableServer({ url: '<some-url>' });

DataTable

<DataTable columns={columns} data={data} {...datatable}>
  <DataDisplay />
</DataTable>

DataTableServer

<DataTableServer columns={columns} {...datatable}>
  <DataDisplay />
</DataTableServer>

Example Url generated by the DataTableServer

GET http://localhost:8081/api/g/core_people?offset=0&limit=10&sorting[0][id]=id&sorting[0][desc]=false&where[0][id]=last_name&where[0][value]=nicenice&searching=good

DefaultTable

<DataTable columns={columns} data={data} {...datatable}>
  <DefaultTable />
</DataTable>

TableCardContainer, TableCards, DefaultCard

<DataTable columns={columns} data={data} {...datatable}>
  <TableCardContainer>
    <TableCards<Product>
      renderTitle={(row) => {
        return (
          <DefaultCard
            {...{
              row: row,
              imageColumnId: 'thumbnail',
              titleColumnId: 'title',
              tagColumnId: 'rating',
              tagIcon: MdStarRate,
            }}
          />
        );
      }}
    />
  </TableCardContainer>
  <TablePagination />
</DataTable>

DataDisplay

<DataTable columns={columns} data={data} {...datatable}>
  <DataDisplay />
</DataTable>

Form Validation with AJV and Internationalization

The package now includes built-in JSON Schema validation using AJV (Another JSON Schema Validator) with format support and comprehensive internationalization (i18n) capabilities, including full Traditional Chinese (Hong Kong/Taiwan) support.

Features

• JSON Schema Validation: Full JSON Schema Draft 7 support
• Format Validation: Built-in support for date, time, email, UUID, and other formats via ajv-formats
• Multi-language Support: Complete i18n support with Traditional Chinese (Hong Kong/Taiwan) and Simplified Chinese
• Enhanced Error Messages: Culturally appropriate error messages in multiple languages
• Automatic Validation: Validation occurs before form submission and confirmation
• Custom Error Display: Collapsible error panels with localized validation feedback

Supported Languages

• 🇺🇸 English (en) - Default language
• 🇭🇰 Traditional Chinese - Hong Kong (zh-HK) - 繁體中文（香港）
• 🇹🇼 Traditional Chinese - Taiwan (zh-TW) - 繁體中文（台灣）
• 🇨🇳 Simplified Chinese (zh-CN, zh) - 简体中文

Basic Usage with Internationalization

import {
  FormRoot,
  FormBody,
  validateData,
  SupportedLocale,
} from '@bsol-oss/react-datatable5';

const schema = {
  type: 'object',
  required: ['email', 'age'],
  properties: {
    email: {
      type: 'string',
      format: 'email',
    },
    age: {
      type: 'integer',
      minimum: 18,
      maximum: 120,
    },
    name: {
      type: 'string',
      minLength: 2,
      maxLength: 50,
    },
  },
};

// Use Traditional Chinese (Hong Kong) for validation errors
<FormRoot
  schema={schema}
  validationLocale="zh-HK"
  /* other props */
>
  <FormBody />
</FormRoot>;

Language-specific Examples

Traditional Chinese (Hong Kong):

<FormRoot
  schema={schema}
  validationLocale="zh-HK"
  /* other props */
>
  <FormBody />
</FormRoot>

Traditional Chinese (Taiwan):

<FormRoot
  schema={schema}
  validationLocale="zh-TW"
  /* other props */
>
  <FormBody />
</FormRoot>

Simplified Chinese:

<FormRoot
  schema={schema}
  validationLocale="zh-CN"
  /* other props */
>
  <FormBody />
</FormRoot>

Manual Validation with Internationalization

You can also use the validation utilities directly with language support:

import {
  validateData,
  ValidationResult,
  SupportedLocale,
} from '@bsol-oss/react-datatable5';

// Validate with Traditional Chinese (Hong Kong) error messages
const result: ValidationResult = validateData(formData, schema, {
  locale: 'zh-HK',
});

if (!result.isValid) {
  console.log('驗證錯誤:', result.errors);
  // Error messages will be in Traditional Chinese
}

// Check supported locales
import {
  getSupportedLocales,
  isLocaleSupported,
} from '@bsol-oss/react-datatable5';

const supportedLocales = getSupportedLocales(); // ['en', 'zh-HK', 'zh-TW', 'zh-CN', 'zh']
const isSupported = isLocaleSupported('zh-HK'); // true

Validation Error Structure

interface ValidationError {
  field: string; // The field that failed validation
  message: string; // User-friendly error message (localized)
  value?: unknown; // The current value that failed
  schemaPath?: string; // JSON Schema path for debugging
}

Dynamic Language Switching

import { SupportedLocale } from '@bsol-oss/react-datatable5';

const MyForm = () => {
  const [locale, setLocale] = useState<SupportedLocale>('zh-HK');

  return (
    <div>
      {/* Language selector */}
      <select
        value={locale}
        onChange={(e) => setLocale(e.target.value as SupportedLocale)}
      >
        <option value="en">English</option>
        <option value="zh-HK">繁體中文（香港）</option>
        <option value="zh-TW">繁體中文（台灣）</option>
        <option value="zh-CN">简体中文</option>
      </select>

      {/* Form with dynamic locale */}
      <FormRoot
        schema={schema}
        validationLocale={locale}
        /* other props */
      >
        <FormBody />
      </FormRoot>
    </div>
  );
};

Example Validation Messages

English:

• "email is required"
• "Invalid email format"
• "Must be at least 18"

Traditional Chinese (Hong Kong/Taiwan):

• "email 為必填"
• "無效的 email 格式"
• "必須至少為 18"

Simplified Chinese:

• "email 为必填"
• "无效的 email 格式"
• "必须至少为 18"

Supported Validation Types

• Type validation: string, number, integer, boolean, object, array
• Format validation: email, date, time, date-time, uuid, uri, etc.
• String constraints: minLength, maxLength, pattern (regex)
• Numeric constraints: minimum, maximum, multipleOf
• Array constraints: minItems, maxItems, uniqueItems
• Object constraints: required properties, additionalProperties
• Enum validation: restricted value sets

All validation types are fully supported across all languages with culturally appropriate translations.

For more details of props and examples, please review the stories in storybook platform.

Documentation

Additional documentation is available in the docs/ directory:

General Guides

• DataTable Server Usage - Server-side DataTable integration guide
• DefaultForm Usage - Comprehensive form component guide
• Validation & i18n - Validation and internationalization setup
• Deployment Guide - Deployment instructions

IdPicker Customization

• IdPicker Quick Reference - ⚡ Quick guide to IdPicker customization
• IdPicker Custom Display - Customize how items appear in the combobox
• IdPicker Labels - Customize UI labels (buttons, placeholders, messages)

Development

npm install
npm run storybook

deployment

npm version prerelease --preid=beta
npm publish