@bsol-oss/react-datatable5 13.0.1-beta.11 → 13.0.1-beta.12

package/README.md

@@ -1,330 +1,263 @@
-# React Datatable
+# @bsol-oss/react-datatable5
 
-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.
+A powerful React component library built on top of `@tanstack/react-table` and `@chakra-ui/react` v3 that provides advanced data table and form components with built-in filtering, sorting, pagination, and JSON Schema validation.
 
-## Installation
-
-```bash
-npm install @tanstack/react-table @chakra-ui/react @emotion/react @bsol-oss/react-datatable5
-```
+## Features
 
-For form validation features with internationalization support, also install:
+### 📊 DataTable Components
 
-```bash
-npm install ajv ajv-formats ajv-i18n
-```
+- **Client-side DataTable**: Full-featured table with local state management
+- **Server-side DataTable**: API-integrated table with automatic data fetching
+- Advanced filtering (text, range, select, tag, boolean, dateRange, custom)
+- Column sorting and reordering
+- Pagination and row selection
+- Responsive design with mobile-friendly card views
+- Density controls and column visibility
+- Customizable display components
 
-## Usage
+### 📝 Form Components
 
-### Hook
+- **JSON Schema-based forms**: Auto-generate forms from JSON Schema
+- **AJV validation**: Full Draft 7 JSON Schema validation support
+- Multi-language validation support (en, zh-HK, zh-TW, zh-CN)
+- Custom error messages via schema configuration
+- Field types: String, Number, Boolean, Date, DateTime, Enum, ID Picker, Tag, File
+- Read-only form viewers
+- Built-in form state management with `react-hook-form`
 
-The `DataTable` and `DataTableServer` utilize hook to add props.
+### 📅 Date & Time Pickers
 
-```tsx
-const datatable = useDataTable();
-const datatableServer = useDataTableServer({ url: '<some-url>' });
-```
+- Custom date/time picker components
+- Built-in calendar implementation (no external dependencies)
+- `dayjs` integration for date formatting and manipulation
+- Timezone support (default: Asia/Hong_Kong)
 
-### DataTable
+## Installation
 
-```tsx
-<DataTable columns={columns} data={data} {...datatable}>
-  <DataDisplay />
-</DataTable>
+```bash
+npm install @bsol-oss/react-datatable5
 ```
 
-### DataTableServer
-
-```tsx
-<DataTableServer columns={columns} {...datatable}>
-  <DataDisplay />
-</DataTableServer>
-```
+### Peer Dependencies
 
-Example Url generated by the DataTableServer
+This library requires the following peer dependencies to be installed in your project:
 
-```
-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
+```bash
+npm install react@^19.0.0 react-dom@^19.0.0
+npm install @chakra-ui/react@^3.19.1
+npm install @tanstack/react-table@^8.21.2
+npm install @tanstack/react-query@^5.66.9
+npm install react-hook-form@^7.54.2
+npm install ajv@^8.12.0 ajv-formats@^3.0.1 ajv-errors@^3.0.0
+npm install dayjs@^1.11.13
+npm install react-icons@^5.4.0
+npm install axios@^1.13.2
 ```
 
-### DefaultTable
+See `package.json` for the complete list of peer dependencies.
 
-```tsx
-<DataTable columns={columns} data={data} {...datatable}>
-  <DefaultTable />
-</DataTable>
-```
+## Quick Start
 
-### TableCardContainer, TableCards, DefaultCard
+### Client-side DataTable
 
 ```tsx
-<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>
-```
+import {
+  useDataTable,
+  DataTable,
+  DefaultTable,
+} from '@bsol-oss/react-datatable5';
 
-### DataDisplay
+const columns = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+  },
+];
+
+const data = [
+  { name: 'John Doe', email: 'john@example.com' },
+  { name: 'Jane Smith', email: 'jane@example.com' },
+];
+
+function MyTable() {
+  const datatable = useDataTable({
+    default: {
+      pageSize: 20,
+      sorting: [{ id: 'name', desc: false }],
+    },
+  });
 
-```tsx
-<DataTable columns={columns} data={data} {...datatable}>
-  <DataDisplay />
-</DataTable>
+  return (
+    <DataTable columns={columns} data={data} {...datatable}>
+      <DefaultTable />
+    </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
+### Server-side DataTable
 
-- **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
+```tsx
+import {
+  useDataTableServer,
+  DataTableServer,
+  DefaultTable,
+  Pagination,
+} from '@bsol-oss/react-datatable5';
 
-#### Supported Languages
+function MyServerTable() {
+  const datatable = useDataTableServer({
+    url: 'https://api.example.com/data',
+    default: { pageSize: 10 },
+  });
 
-- **🇺🇸 English (en)** - Default language
-- **🇭🇰 Traditional Chinese - Hong Kong (zh-HK)** - 繁體中文（香港）
-- **🇹🇼 Traditional Chinese - Taiwan (zh-TW)** - 繁體中文（台灣）
-- **🇨🇳 Simplified Chinese (zh-CN, zh)** - 简体中文
+  return (
+    <DataTableServer columns={columns} {...datatable}>
+      <DefaultTable />
+      <Pagination />
+    </DataTableServer>
+  );
+}
+```
 
-#### Basic Usage with Internationalization
+### Form with JSON Schema
 
 ```tsx
-import {
-  FormRoot,
-  FormBody,
-  validateData,
-  SupportedLocale,
-} from '@bsol-oss/react-datatable5';
+import { FormRoot, FormBody } from '@bsol-oss/react-datatable5';
 
 const schema = {
   type: 'object',
-  required: ['email', 'age'],
+  required: ['username', 'email'],
   properties: {
-    email: {
+    username: {
       type: 'string',
-      format: 'email',
-    },
-    age: {
-      type: 'integer',
-      minimum: 18,
-      maximum: 120,
+      minLength: 3,
+      errorMessages: {
+        required: 'Username is required',
+        minLength: 'Username must be at least 3 characters',
+      },
     },
-    name: {
+    email: {
       type: 'string',
-      minLength: 2,
-      maxLength: 50,
+      format: 'email',
+      errorMessages: {
+        required: 'Email is required',
+        format: 'Invalid email format',
+      },
     },
   },
 };
 
-// Use Traditional Chinese (Hong Kong) for validation errors
-<FormRoot
-  schema={schema}
-  validationLocale="zh-HK"
-  /* other props */
->
-  <FormBody />
-</FormRoot>;
+function MyForm() {
+  return (
+    <FormRoot
+      schema={schema}
+      validationLocale="en"
+      onSubmit={async (data) => {
+        console.log('Submitted:', data);
+      }}
+    >
+      <FormBody />
+    </FormRoot>
+  );
+}
 ```
 
-#### Language-specific Examples
-
-**Traditional Chinese (Hong Kong):**
+## Documentation
 
-```tsx
-<FormRoot
-  schema={schema}
-  validationLocale="zh-HK"
-  /* other props */
->
-  <FormBody />
-</FormRoot>
-```
+- [Server-side DataTable Usage](./docs/DATATABLE_SERVER_USAGE.md)
+- [ID Picker Guide](./docs/IDPICKER_GUIDE.md)
+- [Enum Picker Translation](./docs/ENUMPICKER_TRANSLATION.md)
+- [i18n Migration Guide](./docs/I18N_MIGRATION_GUIDE.md)
+- [Validation Guide](./VALIDATION_GUIDE.md)
+- [Deployment Guide](./docs/deployment.md)
 
-**Traditional Chinese (Taiwan):**
+## Development
 
-```tsx
-<FormRoot
-  schema={schema}
-  validationLocale="zh-TW"
-  /* other props */
->
-  <FormBody />
-</FormRoot>
-```
+### Storybook
 
-**Simplified Chinese:**
+View interactive examples and component documentation:
 
-```tsx
-<FormRoot
-  schema={schema}
-  validationLocale="zh-CN"
-  /* other props */
->
-  <FormBody />
-</FormRoot>
+```bash
+npm run storybook
 ```
 
-#### Manual Validation with Internationalization
+Stories are organized by feature:
 
-You can also use the validation utilities directly with language support:
+- `DataTable/` - Client-side table examples
+- `DataTableServer/` - Server-side table examples
+- `Form/` - Form component examples
+- `DatePicker/` - Date/time picker examples
 
-```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',
-});
+### Build
 
-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
+```bash
+npm run build
 ```
 
-#### Validation Error Structure
+### Lint
 
-```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
-}
+```bash
+npm run lint
 ```
 
-#### Dynamic Language Switching
-
-```tsx
-import { SupportedLocale } from '@bsol-oss/react-datatable5';
+### Format
 
-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>
-  );
-};
+```bash
+npm run format
 ```
 
-#### Example Validation Messages
-
-**English:**
-
-- "email is required"
-- "Invalid email format"
-- "Must be at least 18"
-
-**Traditional Chinese (Hong Kong/Taiwan):**
+## Key Features
 
-- "email 為必填"
-- "無效的 email 格式"
-- "必須至少為 18"
+### Column Customization
 
-**Simplified Chinese:**
+Define custom filters and display options in column metadata:
 
-- "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
+```tsx
+{
+  id: 'status',
+  meta: {
+    displayName: 'Status',
+    filterVariant: 'select',
+    filterOptions: [
+      { label: 'Active', value: 'active' },
+      { label: 'Inactive', value: 'inactive' }
+    ]
+  }
+}
+```
 
-Additional documentation is available in the `docs/` directory:
+### Label Objects
 
-### General Guides
+Components use label objects from schema context for internationalization:
 
-- **[DataTable Server Usage](./docs/DATATABLE_SERVER_USAGE.md)** - Server-side DataTable integration guide
-- **[DefaultForm Usage](./docs/DEFAULTFORM_USAGE.md)** - Comprehensive form component guide
-- **[Validation & i18n](./docs/VALIDATION_I18N.md)** - Validation and internationalization setup
-- **[i18n Migration Guide](./docs/I18N_MIGRATION_GUIDE.md)** - Migrate from react-i18next to label objects
-- **[Deployment Guide](./docs/deployment.md)** - Deployment instructions
+```tsx
+<FormRoot
+  schema={schema}
+  idPickerLabels={{
+    typeToSearch: 'Type to search...',
+    total: 'Total',
+    // ... other labels
+  }}
+>
+  <FormBody />
+</FormRoot>
+```
 
-### IdPicker Customization
+## Requirements
 
-- **[IdPicker Quick Reference](./docs/IDPICKER_QUICK_REFERENCE.md)** - ⚡ Quick guide to IdPicker customization
-- **[IdPicker Custom Display](./docs/IDPICKER_CUSTOM_DISPLAY.md)** - Customize how items appear in the combobox
-- **[IdPicker Labels](./docs/IDPICKER_LABELS.md)** - Customize UI labels (buttons, placeholders, messages)
+- React 19+
+- @chakra-ui/react 3.19+
+- TypeScript (for type definitions)
 
-## Development
+## License
 
-```
-npm install
-npm run storybook
-```
+MIT
 
-## deployment
+## Repository
 
-```
-npm version prerelease --preid=beta
-npm publish
-```
+[GitHub](https://github.com/bsol-oss/react-datatable5)

package/dist/index.d.ts

@@ -153,7 +153,16 @@ declare const TableControls: ({ fitTableWidth, fitTableHeight, children, showGlo
 
 declare const TableFilter: () => react_jsx_runtime.JSX.Element;
 
-declare const TableFilterTags: () => react_jsx_runtime.JSX.Element;
+interface TableFilterTagsProps {
+    filterTagsOptions?: {
+        column: string;
+        options: {
+            label: string;
+            value: string;
+        }[];
+    }[];
+}
+declare const TableFilterTags: ({ filterTagsOptions, }?: TableFilterTagsProps) => react_jsx_runtime.JSX.Element | null;
 
 interface TableProps extends TableRootProps {
     showLoading?: boolean;
@@ -468,6 +477,9 @@ interface DataTableLabel {
     globalFilterPlaceholder: string;
     trueLabel: string;
     falseLabel: string;
+    noFiltersMatchText: string;
+    filterByLabel: string;
+    filterLabelsPlaceholder: string;
 }
 interface DataTableContextProps<TData = unknown> extends Omit<DataTableProps, 'translate'> {
     table: Table$1<TData>;
@@ -1444,4 +1456,4 @@ declare module '@tanstack/react-table' {
     }
 }
 
-export { CalendarDisplay, type CalendarDisplayProps, type CalendarEvent, type CalendarProps, CardHeader, type CardHeaderProps, type CustomJSONSchema7, type CustomJSONSchema7Definition, DataDisplay, type DataDisplayProps, type DataResponse, DataTable, type DataTableDefaultState, type DataTableProps, DataTableServer, type DataTableServerProps, DatePickerContext, DatePickerInput, type DatePickerInputProps, type DatePickerLabels, type DatePickerProps, type DateTimePickerLabels, DefaultCardTitle, DefaultForm, type DefaultFormProps, DefaultTable, type DefaultTableProps, DefaultTableServer, type DefaultTableServerProps, DensityToggleButton, type DensityToggleButtonProps, type EditFilterButtonProps, EditSortingButton, type EditSortingButtonProps, type EditViewButtonProps, EmptyState, type EmptyStateProps, type EnumPickerLabels, ErrorAlert, type ErrorAlertProps, type ErrorMessageConfig, type ErrorMessageResult, type FieldErrorConfig, type FilePickerLabels, type FilePickerMediaFile, type FilePickerProps, FilterDialog, FormBody, type FormButtonLabels, FormRoot, type FormRootProps, FormTitle, type GetColumnsConfigs, type GetDateColorProps, type GetMultiDatesProps, type GetRangeDatesProps, type GetStyleProps, type GetVariantProps, GlobalFilter, type IdPickerLabels, type LoadInitialValuesParams, type LoadInitialValuesResult, MediaLibraryBrowser, type MediaLibraryBrowserProps, PageSizeControl, type PageSizeControlProps, Pagination, type QueryParams, type RangeCalendarProps, type RangeDatePickerLabels, type RangeDatePickerProps, RecordDisplay, type RecordDisplayProps, ReloadButton, type ReloadButtonProps, ResetFilteringButton, ResetSelectionButton, ResetSortingButton, type Result, RowCountText, SelectAllRowsToggle, type SelectAllRowsToggleProps, 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, type TagPickerProps, TextCell, type TextCellProps, type TimePickerLabels, type Translate, type UseDataTableProps, type UseDataTableReturn, type UseDataTableServerProps, type UseDataTableServerReturn, type UseFormProps, type ValidationErrorType, ViewDialog, buildErrorMessages, buildFieldErrors, buildRequiredErrors, convertToAjvErrorsFormat, createErrorMessage, defaultRenderDisplay, getColumns, getMultiDates, getRangeDates, idPickerSanityCheck, useDataTable, useDataTableContext, useDataTableServer, useForm, widthSanityCheck };
+export { CalendarDisplay, type CalendarDisplayProps, type CalendarEvent, type CalendarProps, CardHeader, type CardHeaderProps, type CustomJSONSchema7, type CustomJSONSchema7Definition, DataDisplay, type DataDisplayProps, type DataResponse, DataTable, type DataTableDefaultState, type DataTableProps, DataTableServer, type DataTableServerProps, DatePickerContext, DatePickerInput, type DatePickerInputProps, type DatePickerLabels, type DatePickerProps, type DateTimePickerLabels, DefaultCardTitle, DefaultForm, type DefaultFormProps, DefaultTable, type DefaultTableProps, DefaultTableServer, type DefaultTableServerProps, DensityToggleButton, type DensityToggleButtonProps, type EditFilterButtonProps, EditSortingButton, type EditSortingButtonProps, type EditViewButtonProps, EmptyState, type EmptyStateProps, type EnumPickerLabels, ErrorAlert, type ErrorAlertProps, type ErrorMessageConfig, type ErrorMessageResult, type FieldErrorConfig, type FilePickerLabels, type FilePickerMediaFile, type FilePickerProps, FilterDialog, FormBody, type FormButtonLabels, FormRoot, type FormRootProps, FormTitle, type GetColumnsConfigs, type GetDateColorProps, type GetMultiDatesProps, type GetRangeDatesProps, type GetStyleProps, type GetVariantProps, GlobalFilter, type IdPickerLabels, type LoadInitialValuesParams, type LoadInitialValuesResult, MediaLibraryBrowser, type MediaLibraryBrowserProps, PageSizeControl, type PageSizeControlProps, Pagination, type QueryParams, type RangeCalendarProps, type RangeDatePickerLabels, type RangeDatePickerProps, RecordDisplay, type RecordDisplayProps, ReloadButton, type ReloadButtonProps, ResetFilteringButton, ResetSelectionButton, ResetSortingButton, type Result, RowCountText, SelectAllRowsToggle, type SelectAllRowsToggleProps, Table, TableBody, type TableBodyProps, TableCardContainer, type TableCardContainerProps, TableCards, type TableCardsProps, TableComponent, TableControls, type TableControlsProps, TableDataDisplay, type TableDataDisplayProps, TableFilter, TableFilterTags, type TableFilterTagsProps, TableFooter, type TableFooterProps, TableHeader, type TableHeaderProps, type TableHeaderTexts, TableLoadingComponent, type TableLoadingComponentProps, type TableProps, type TableRendererProps, type TableRowSelectorProps, TableSelector, TableSorter, TableViewer, type TagPickerProps, TextCell, type TextCellProps, type TimePickerLabels, type Translate, type UseDataTableProps, type UseDataTableReturn, type UseDataTableServerProps, type UseDataTableServerReturn, type UseFormProps, type ValidationErrorType, ViewDialog, buildErrorMessages, buildFieldErrors, buildRequiredErrors, convertToAjvErrorsFormat, createErrorMessage, defaultRenderDisplay, getColumns, getMultiDates, getRangeDates, idPickerSanityCheck, useDataTable, useDataTableContext, useDataTableServer, useForm, widthSanityCheck };