@bsol-oss/react-datatable5 12.0.0-beta.56 → 12.0.0-beta.58

package/README.md

@@ -8,6 +8,12 @@ The datetable package is built on top of `@tanstack/react-table` and `chakra-ui`
 npm install @tanstack/react-table @chakra-ui/react @emotion/react @bsol-oss/react-datatable5
 ```
 
+For form validation features with internationalization support, also install:
+
+```bash
+npm install ajv ajv-formats ajv-i18n
+```
+
 ## Usage
 
 ### Hook
@@ -82,6 +88,192 @@ GET http://localhost:8081/api/g/core_people?offset=0&limit=10&sorting[0][id]=id&
 </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
+
+```tsx
+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):**
+```tsx
+<FormRoot 
+  schema={schema} 
+  validationLocale="zh-HK"
+  /* other props */
+>
+  <FormBody />
+</FormRoot>
+```
+
+**Traditional Chinese (Taiwan):**
+```tsx
+<FormRoot 
+  schema={schema} 
+  validationLocale="zh-TW"
+  /* other props */
+>
+  <FormBody />
+</FormRoot>
+```
+
+**Simplified Chinese:**
+```tsx
+<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:
+
+```tsx
+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
+
+```tsx
+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
+
+```tsx
+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.
 
 ## Development

package/dist/index.d.ts

@@ -11,10 +11,12 @@ import { RankingInfo } from '@tanstack/match-sorter-utils';
 import { UseQueryResult } from '@tanstack/react-query';
 import { JSONSchema7 } from 'json-schema';
 import { ForeignKeyProps as ForeignKeyProps$1 } from '@/components/Form/components/fields/StringInputField';
+import { SupportedLocale as SupportedLocale$1 } from '@/components/Form/utils/validation';
 import { AxiosRequestConfig } from 'axios';
 import * as react_hook_form from 'react-hook-form';
 import { UseFormReturn, FieldValues, SubmitHandler } from 'react-hook-form';
 import { RenderProps, Props } from '@bsol-oss/dayzed-react19';
+import * as ajv_i18n_localize_types from 'ajv-i18n/localize/types';
 
 interface DensityToggleButtonProps {
     icon?: React__default.ReactElement;
@@ -547,6 +549,7 @@ interface FormRootProps<TData extends FieldValues> {
     requestOptions?: AxiosRequestConfig;
     getUpdatedData?: () => TData | Promise<TData> | void;
     customErrorRenderer?: (error: unknown) => ReactNode;
+    validationLocale?: SupportedLocale$1;
 }
 interface CustomJSONSchema7Definition extends JSONSchema7 {
     variant: string;
@@ -563,7 +566,7 @@ declare const idPickerSanityCheck: (column: string, foreign_key?: {
     column?: string | undefined;
     display_column?: string | undefined;
 } | undefined) => void;
-declare const FormRoot: <TData extends FieldValues>({ schema, idMap, setIdMap, form, serverUrl, translate, children, order, ignore, include, onSubmit, rowNumber, requestOptions, getUpdatedData, customErrorRenderer, }: FormRootProps<TData>) => react_jsx_runtime.JSX.Element;
+declare const FormRoot: <TData extends FieldValues>({ schema, idMap, setIdMap, form, serverUrl, translate, children, order, ignore, include, onSubmit, rowNumber, requestOptions, getUpdatedData, customErrorRenderer, validationLocale, }: FormRootProps<TData>) => react_jsx_runtime.JSX.Element;
 
 interface DefaultFormProps<TData extends FieldValues> {
     formConfig: Omit<FormRootProps<TData>, "children">;
@@ -600,6 +603,29 @@ interface GetVariantProps {
     selectable: boolean;
 }
 interface DatePickerProps extends Props {
+    onDateSelected?: (obj: {
+        date: Date;
+    }) => void;
+    selected: Date | Date[];
+    firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    showOutsideDays?: boolean;
+    date?: Date;
+    minDate?: Date;
+    maxDate?: Date;
+    monthsToDisplay?: number;
+    labels?: {
+        monthNamesShort: string[];
+        weekdayNamesShort: string[];
+        backButtonLabel?: string;
+        forwardButtonLabel?: string;
+    };
+    render?: (dayzedData: any) => React__default.ReactNode;
+}
+interface DatePickerLabels {
+    monthNamesShort: string[];
+    weekdayNamesShort: string[];
+    backButtonLabel?: string;
+    forwardButtonLabel?: string;
 }
 
 interface GetMultiDatesProps {
@@ -638,6 +664,54 @@ interface RecordDisplayProps {
 }
 declare const RecordDisplay: ({ object, boxProps, translate, prefix, }: RecordDisplayProps) => react_jsx_runtime.JSX.Element;
 
+declare const localize: {
+    en: () => void;
+    'zh-HK': ajv_i18n_localize_types.Localize;
+    'zh-TW': ajv_i18n_localize_types.Localize;
+    'zh-CN': ajv_i18n_localize_types.Localize;
+    zh: ajv_i18n_localize_types.Localize;
+};
+type SupportedLocale = keyof typeof localize;
+interface ValidationError {
+    field: string;
+    message: string;
+    value?: unknown;
+    schemaPath?: string;
+}
+interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+}
+interface ValidationOptions {
+    locale?: SupportedLocale;
+}
+/**
+ * Validates data against a JSON Schema using AJV with i18n support
+ * @param data - The data to validate
+ * @param schema - The JSON Schema to validate against
+ * @param options - Validation options including locale
+ * @returns ValidationResult containing validation status and errors
+ */
+declare const validateData: (data: unknown, schema: JSONSchema7, options?: ValidationOptions) => ValidationResult;
+/**
+ * Creates a reusable validator function for a specific schema with i18n support
+ * @param schema - The JSON Schema to create validator for
+ * @param locale - The locale to use for error messages
+ * @returns A function that validates data against the schema
+ */
+declare const createSchemaValidator: (schema: JSONSchema7, locale?: SupportedLocale) => (data: unknown) => ValidationResult;
+/**
+ * Get available locales for validation error messages
+ * @returns Array of supported locale codes
+ */
+declare const getSupportedLocales: () => SupportedLocale[];
+/**
+ * Check if a locale is supported
+ * @param locale - The locale to check
+ * @returns Boolean indicating if the locale is supported
+ */
+declare const isLocaleSupported: (locale: string) => locale is "en" | "zh-HK" | "zh-TW" | "zh-CN" | "zh";
+
 declare module "@tanstack/react-table" {
     interface ColumnMeta<TData extends RowData, TValue> {
         /**
@@ -710,4 +784,4 @@ declare module "@tanstack/react-table" {
     }
 }
 
-export { type CalendarProps, CardHeader, type CardHeaderProps, type CustomJSONSchema7Definition, DataDisplay, type DataDisplayProps, type DataResponse, DataTable, type DataTableDefaultState, type DataTableProps, DataTableServer, type DataTableServerProps, type DatePickerProps, DefaultCardTitle, DefaultForm, type DefaultFormProps, DefaultTable, type DefaultTableProps, DensityToggleButton, type DensityToggleButtonProps, type EditFilterButtonProps, EditSortingButton, type EditSortingButtonProps, type EditViewButtonProps, EmptyState, type EmptyStateProps, ErrorAlert, type ErrorAlertProps, FilterDialog, FormBody, FormRoot, type FormRootProps, FormTitle, type GetColumnsConfigs, type GetDateColorProps, type GetMultiDatesProps, type GetRangeDatesProps, type GetStyleProps, type GetVariantProps, GlobalFilter, PageSizeControl, type PageSizeControlProps, Pagination, type RangeCalendarProps, type RangeDatePickerProps, RecordDisplay, type RecordDisplayProps, ReloadButton, type ReloadButtonProps, ResetFilteringButton, ResetSelectionButton, ResetSortingButton, type Result, RowCountText, Table, TableBody, type TableBodyProps, TableCardContainer, type TableCardContainerProps, TableCards, type TableCardsProps, TableComponent, TableControls, type TableControlsProps, TableDataDisplay, type TableDataDisplayProps, TableFilter, TableFilterTags, TableFooter, type TableFooterProps, TableHeader, type TableHeaderProps, type TableHeaderTexts, TableLoadingComponent, type TableLoadingComponentProps, type TableProps, type TableRendererProps, type TableRowSelectorProps, TableSelector, TableSorter, TableViewer, TextCell, type TextCellProps, type UseDataTableProps, type UseDataTableReturn, type UseDataTableServerProps, type UseDataTableServerReturn, type UseFormProps, ViewDialog, getColumns, getMultiDates, getRangeDates, idPickerSanityCheck, useDataTable, useDataTableContext, useDataTableServer, useForm, widthSanityCheck };
+export { type CalendarProps, CardHeader, type CardHeaderProps, type CustomJSONSchema7Definition, DataDisplay, type DataDisplayProps, type DataResponse, DataTable, type DataTableDefaultState, type DataTableProps, DataTableServer, type DataTableServerProps, type DatePickerLabels, type DatePickerProps, DefaultCardTitle, DefaultForm, type DefaultFormProps, DefaultTable, type DefaultTableProps, DensityToggleButton, type DensityToggleButtonProps, type EditFilterButtonProps, EditSortingButton, type EditSortingButtonProps, type EditViewButtonProps, EmptyState, type EmptyStateProps, ErrorAlert, type ErrorAlertProps, FilterDialog, FormBody, FormRoot, type FormRootProps, FormTitle, type GetColumnsConfigs, type GetDateColorProps, type GetMultiDatesProps, type GetRangeDatesProps, type GetStyleProps, type GetVariantProps, GlobalFilter, PageSizeControl, type PageSizeControlProps, Pagination, type RangeCalendarProps, type RangeDatePickerProps, RecordDisplay, type RecordDisplayProps, ReloadButton, type ReloadButtonProps, ResetFilteringButton, ResetSelectionButton, ResetSortingButton, type Result, RowCountText, type SupportedLocale, Table, TableBody, type TableBodyProps, TableCardContainer, type TableCardContainerProps, TableCards, type TableCardsProps, TableComponent, TableControls, type TableControlsProps, TableDataDisplay, type TableDataDisplayProps, TableFilter, TableFilterTags, TableFooter, type TableFooterProps, TableHeader, type TableHeaderProps, type TableHeaderTexts, TableLoadingComponent, type TableLoadingComponentProps, type TableProps, type TableRendererProps, type TableRowSelectorProps, TableSelector, TableSorter, TableViewer, TextCell, type TextCellProps, type UseDataTableProps, type UseDataTableReturn, type UseDataTableServerProps, type UseDataTableServerReturn, type UseFormProps, type ValidationError, type ValidationOptions, type ValidationResult, ViewDialog, createSchemaValidator, getColumns, getMultiDates, getRangeDates, getSupportedLocales, idPickerSanityCheck, isLocaleSupported, useDataTable, useDataTableContext, useDataTableServer, useForm, validateData, widthSanityCheck };