@materialui-reactjs/admin 1.0.6 → 2.0.1

package/README.md

@@ -1,453 +1,587 @@
-# @materialui-reactjs/admin
-
-A React component and utility library for building modern admin applications, including admin dashboards, CRUD interfaces, data tables, forms, charts, navigation, and reusable layouts.
-
-The package provides multiple subpath exports so applications can import only the feature groups they need. It is designed to provide a consistent and reusable architecture for React-based admin systems.
-
-## Features
-
-* Reusable admin dashboard components
-* CRUD components for list, detail, update, and import workflows
-* Form components for common and advanced input scenarios
-* File and image upload components
-* Data tables, pagination, search, tabs, and modal components
-* Sidebar and top navigation components
-* ECharts-based chart components
-* Loading and spinner components
-* API and data-handling helpers
-* Environment configuration utilities
-* Routing and validation helpers
-* Drag-and-drop and sortable components
-* CKEditor integration
-* React Select integration
-* MUI Date and Time Picker integration
-* Redux Toolkit integration
-* Bootstrap and MUI based UI components
-
-## Package Structure
-
-The package exposes different feature groups through subpath exports:
-
-| Import Path                            | Description                                                                |
-| -------------------------------------- | -------------------------------------------------------------------------- |
-| `@materialui-reactjs/admin`            | Main exports for commonly used components                                  |
-| `@materialui-reactjs/admin/form`       | Form fields, form builders, and upload components                          |
-| `@materialui-reactjs/admin/hook`       | Hooks and helpers for list, detail, update, and import workflows           |
-| `@materialui-reactjs/admin/utils`      | API, routing, environment, validation, and utility helpers                 |
-| `@materialui-reactjs/admin/meta`       | Tables, tabs, pagination, modals, headers, search, and other UI components |
-| `@materialui-reactjs/admin/sidebar`    | Sidebar navigation                                                         |
-| `@materialui-reactjs/admin/single`     | Single-resource CRUD components                                            |
-| `@materialui-reactjs/admin/top-navbar` | Top navigation                                                             |
-| `@materialui-reactjs/admin/echarts`    | ECharts components                                                         |
-| `@materialui-reactjs/admin/loader`     | Loading and spinner components                                             |
-
-## Main Components
-
-### Form Components
-
-The `form` package provides reusable components for building complex admin forms.
-
-* `AdvancedMultiSelect`
-* `AsxhUImages`
-* `BoxAddRow`
-* `CheckTreeBox`
-* `CusForm`
-* `DateInput`
-* `DateTimeInput`
-* `Editor`
-* `EfFile`
-* `EfImage`
-* `EfImages`
-* `PImage`
-* `SelectAddRowBox`
-* `SelectAddRowBoxAdvanced`
-* `SelectBox`
-* `UDragFile`
-* `UFile`
-* `UFiles`
-* `UImages`
-
-These components support:
-
-* Standard form inputs
-* Select and multi-select fields
-* Tree-based selection
-* Date and time inputs
-* Rich text editing
-* File uploads
-* Image uploads
-* Dynamic form rows
-* Drag-and-drop file handling
-
-### Meta UI Components
-
-The `meta` package contains reusable UI components for admin pages.
-
-* `BtnGroup`
-* `CardTable`
-* `CusTooltip`
-* `ElfinderModal`
-* `Error403`
-* `Error404`
-* `Head`
-* `HeaderDetail`
-* `HeaderIndex`
-* `HeaderUpdate`
-* `ModalForm`
-* `Navtabs`
-* `Pagination`
-* `PDFEmbed`
-* `ScrollTable`
-* `SearchBox`
-* `SortableItem`
-
-These components can be used to build:
-
-* Index pages
-* Detail pages
-* Update pages
-* Data tables
-* Search interfaces
-* Pagination
-* Navigation tabs
-* Modal forms
-* Page headers
-* Error pages
-* Scrollable tables
-
-### Single-Page CRUD Components
-
-The `single` package provides reusable components for building CRUD pages around a single resource.
-
-* `List`
-* `Detail`
-* `Update`
-* `UpdateDetail`
-* `UpdateTableDetail`
-* `Import`
-* `Fields`
-
-A typical resource can be structured as:
-
-```text
-Resource
-├── List
-├── Detail
-├── Update
-└── Import
-```
-
-This structure is useful for applications that use a consistent CRUD architecture across multiple resources.
-
-### Layout Components
-
-#### Sidebar
-
-The sidebar package provides navigation components for admin dashboards.
-
-```ts
-import { Sidebar } from "@materialui-reactjs/admin/sidebar";
-```
-
-It also exports:
-
-* `MenuItem`
-* `SidebarProps`
-
-#### Top Navbar
-
-The top navigation component provides the main navigation header for an admin application.
-
-```ts
-import { TopNavbar } from "@materialui-reactjs/admin/top-navbar";
-```
-
-### ECharts Components
-
-The `echarts` package provides reusable chart components based on ECharts.
-
-* `BarChart`
-* `LineChart`
-* `MultiBarChart`
-* `MultiLineChart`
-* `PieChart`
-
-Example:
-
-```tsx
-import { BarChart } from "@materialui-reactjs/admin/echarts";
-
-export default function DashboardChart() {
-  return <BarChart />;
-}
-```
-
-### Loader
-
-The `loader` package provides loading indicators.
-
-* `SpinnerLoader`
-
-Example:
-
-```tsx
-import { SpinnerLoader } from "@materialui-reactjs/admin/loader";
-
-export default function Loading() {
-  return <SpinnerLoader />;
-}
-```
-
-## Hooks
-
-The `hook` package provides reusable helpers for common admin data workflows.
-
-Available helpers include:
-
-* `fetchHookData`
-* `handleHookClickPage`
-* `handleHookSeachForm`
-* `handleHookChange`
-* `convertQueryToSort`
-* `convertSortToQuery`
-
-These helpers can be used to standardize:
-
-* API data loading
-* Pagination
-* Search
-* Sorting
-* Form changes
-* List/detail/update workflows
-
-Example:
-
-```ts
-import {
-  fetchHookData,
-  handleHookClickPage,
-  handleHookChange,
-} from "@materialui-reactjs/admin/hook";
-```
-
-## Utilities
-
-The `utils` package provides common utilities for admin applications.
-
-Available utilities include:
-
-* `callFetchApi`
-* `callFetchApiToken`
-* `createQueryString`
-* `loadEnv`
-* `getEnv`
-* `CusRoute`
-
-Example:
-
-```ts
-import {
-  callFetchApi,
-  callFetchApiToken,
-  createQueryString,
-} from "@materialui-reactjs/admin/utils";
-```
-
-## Installation
-
-Install the package using npm:
-
-```bash
-npm install @materialui-reactjs/admin
-```
-
-Or using yarn:
-
-```bash
-yarn add @materialui-reactjs/admin
-```
-
-Or using pnpm:
-
-```bash
-pnpm add @materialui-reactjs/admin
-```
-
-## Basic Usage
-
-Components can be imported directly from their corresponding subpath.
-
-```tsx
-import { Sidebar } from "@materialui-reactjs/admin/sidebar";
-import { TopNavbar } from "@materialui-reactjs/admin/top-navbar";
-import { CardTable } from "@materialui-reactjs/admin/meta";
-import { CusForm } from "@materialui-reactjs/admin/form";
-
-export default function AdminLayout() {
-  return (
-    <>
-      <TopNavbar />
-      <Sidebar />
-      <CardTable />
-      <CusForm />
-    </>
-  );
-}
-```
-
-## Import by Feature Group
-
-### Form
-
-```tsx
-import {
-  CusForm,
-  DateInput,
-  DateTimeInput,
-  SelectBox,
-} from "@materialui-reactjs/admin/form";
-```
-
-### Meta
-
-```tsx
-import {
-  CardTable,
-  Pagination,
-  SearchBox,
-  ModalForm,
-} from "@materialui-reactjs/admin/meta";
-```
-
-### Sidebar
-
-```tsx
-import { Sidebar } from "@materialui-reactjs/admin/sidebar";
-```
-
-### Top Navbar
-
-```tsx
-import { TopNavbar } from "@materialui-reactjs/admin/top-navbar";
-```
-
-### ECharts
-
-```tsx
-import {
-  BarChart,
-  LineChart,
-  PieChart,
-} from "@materialui-reactjs/admin/echarts";
-```
-
-### Loader
-
-```tsx
-import { SpinnerLoader } from "@materialui-reactjs/admin/loader";
-```
-
-### Utilities
-
-```tsx
-import {
-  callFetchApi,
-  callFetchApiToken,
-  loadEnv,
-  getEnv,
-} from "@materialui-reactjs/admin/utils";
-```
-
-## Styles and CSS
-
-The package provides CSS files for its components.
-
-Import the main stylesheet:
-
-```ts
-import "@materialui-reactjs/admin/style.css";
-```
-
-Some component groups may also import their own internal CSS automatically.
-
-Make sure your application's build configuration supports CSS imports from npm packages.
-
-## Dependencies
-
-This package is built with and integrates with the following libraries.
-
-### UI and Styling
-
-| Package               | Purpose                                       |
-| --------------------- | --------------------------------------------- |
-| `@mui/material`       | Material UI components and UI system          |
-| `@mui/x-date-pickers` | Date and time picker components for MUI       |
-| `@emotion/react`      | Emotion styling engine                        |
-| `@emotion/styled`     | Styled components powered by Emotion          |
-| `bootstrap`           | CSS framework and responsive layout utilities |
-
-### React and State Management
-
-| Package              | Purpose                         |
-| -------------------- | ------------------------------- |
-| `react`              | Core React library              |
-| `react-dom`          | React DOM rendering             |
-| `@reduxjs/toolkit`   | Redux state management          |
-| `react-redux`        | React bindings for Redux        |
-| `react-router-dom`   | Client-side routing             |
-| `react-helmet-async` | Managing document head metadata |
-
-### Form and Editor
-
-| Package                     | Purpose                            |
-| --------------------------- | ---------------------------------- |
-| `@ckeditor/ckeditor5-react` | CKEditor React integration         |
-| `react-select`              | Select and multi-select components |
-| `date-fns`                  | Date manipulation and formatting   |
-| `decimal.js`                | Precise decimal calculations       |
-
-### Drag and Drop / Sorting
-
-| Package              | Purpose                              |
-| -------------------- | ------------------------------------ |
-| `@dnd-kit/sortable`  | Sortable drag-and-drop functionality |
-| `@dnd-kit/utilities` | Utilities for dnd-kit                |
-| `@hello-pangea/dnd`  | Drag-and-drop components for React   |
-| `react-sortablejs`   | React integration for SortableJS     |
-| `sortablejs`         | Drag-and-drop sorting engine         |
-
-### Charts
-
-| Package             | Purpose                                |
-| ------------------- | -------------------------------------- |
-| `echarts`           | Charting and data visualization engine |
-| `echarts-for-react` | React wrapper for ECharts              |
-
-### Utilities and Notifications
-
-| Package                     | Purpose                                              |
-| --------------------------- | ---------------------------------------------------- |
-| `jquery`                    | DOM manipulation and third-party library integration |
-| `sweetalert2`               | Alerts, confirmations, and notifications             |
-| `sweetalert2-react-content` | React integration for SweetAlert2                    |
-
-## Requirements
-
-The package is designed for modern React applications.
-
-Current core versions include:
-
-* React `19.2.x`
-* React DOM `19.2.x`
-* React Router `7.x`
-* MUI `9.x`
-* MUI X Date Pickers `9.x`
-* Redux Toolkit `2.x`
-* Bootstrap `5.x`
-* ECharts `6.x`
-
-For the exact versions used by a particular release, check the package's `package.json`.
-
-## License
-
-MIT
+# @materialui-reactjs/admin
+
+A React component and utility library for building modern admin applications, including admin dashboards, CRUD interfaces, data tables, forms, charts, navigation, and reusable layouts.
+
+The package provides multiple subpath exports so applications can import only the feature groups they need. It is designed to provide a consistent and reusable architecture for React-based admin systems.
+
+## Features
+
+- Reusable admin dashboard components
+- CRUD components for list, detail, update, and import workflows
+- Form components for common and advanced input scenarios
+- File and image upload components
+- Data tables, pagination, search, tabs, and modal components
+- Sidebar and top navigation components
+- ECharts-based chart components
+- Loading and spinner components
+- API and data-handling helpers
+- Environment configuration utilities
+- Routing and validation helpers
+- Drag-and-drop and sortable components
+- CKEditor integration
+- React Select integration
+- MUI Date and Time Picker integration
+- Redux Toolkit integration
+- Bootstrap and MUI based UI components
+
+## Package Structure
+
+The package exposes different feature groups through subpath exports:
+
+| Import Path                            | Description                                                                |
+| -------------------------------------- | -------------------------------------------------------------------------- |
+| `@materialui-reactjs/admin`            | Main exports for commonly used components                                  |
+| `@materialui-reactjs/admin/form`       | Form fields, form builders, and upload components                          |
+| `@materialui-reactjs/admin/hook`       | Hooks and helpers for list, detail, update, and import workflows           |
+| `@materialui-reactjs/admin/utils`      | API, routing, environment, validation, and utility helpers                 |
+| `@materialui-reactjs/admin/meta`       | Tables, tabs, pagination, modals, headers, search, and other UI components |
+| `@materialui-reactjs/admin/sidebar`    | Sidebar navigation                                                         |
+| `@materialui-reactjs/admin/single`     | Single-resource CRUD components                                            |
+| `@materialui-reactjs/admin/top-navbar` | Top navigation                                                             |
+| `@materialui-reactjs/admin/echarts`    | ECharts components                                                         |
+| `@materialui-reactjs/admin/loader`     | Loading and spinner components                                             |
+
+## Main Components
+
+### Form Components
+
+The `form` package provides reusable components for building complex admin forms.
+
+- `AdvancedMultiSelect`
+- `AsxhUImages`
+- `BoxAddRow`
+- `CheckTreeBox`
+- `CusForm`
+- `DateInput`
+- `DateTimeInput`
+- `Editor`
+- `EfFile`
+- `EfImage`
+- `EfImages`
+- `PImage`
+- `SelectAddRowBox`
+- `SelectAddRowBoxAdvanced`
+- `SelectBox`
+- `UDragFile`
+- `UFile`
+- `UFiles`
+- `UImages`
+
+These components support:
+
+- Standard form inputs
+- Select and multi-select fields
+- Tree-based selection
+- Date and time inputs
+- Rich text editing
+- File uploads
+- Image uploads
+- Dynamic form rows
+- Drag-and-drop file handling
+
+### Meta UI Components
+
+The `meta` package contains reusable UI components for admin pages.
+
+- `BtnGroup`
+- `CardTable`
+- `CusTooltip`
+- `ElfinderModal`
+- `Error403`
+- `Error404`
+- `Head`
+- `HeaderDetail`
+- `HeaderIndex`
+- `HeaderUpdate`
+- `ModalForm`
+- `Navtabs`
+- `Pagination`
+- `PDFEmbed`
+- `ScrollTable`
+- `SearchBox`
+- `SortableItem`
+
+These components can be used to build:
+
+- Index pages
+- Detail pages
+- Update pages
+- Data tables
+- Search interfaces
+- Pagination
+- Navigation tabs
+- Modal forms
+- Page headers
+- Error pages
+- Scrollable tables
+
+### Single-Page CRUD Components
+
+The `single` package provides reusable components for building CRUD pages around a single resource.
+
+- `List`
+- `Detail`
+- `Update`
+- `UpdateDetail`
+- `UpdateTableDetail`
+- `Import`
+- `Fields`
+
+A typical resource can be structured as:
+
+```text
+Resource
+├── List
+├── Detail
+├── Update
+└── Import
+```
+
+This structure is useful for applications that use a consistent CRUD architecture across multiple resources.
+
+### Layout Components
+
+#### Sidebar
+
+The sidebar package provides navigation components for admin dashboards.
+
+```ts
+import { Sidebar } from "@materialui-reactjs/admin/sidebar";
+```
+
+It also exports:
+
+- `MenuItem`
+- `SidebarProps`
+
+#### Top Navbar
+
+The top navigation component provides the main navigation header for an admin application.
+
+```ts
+import { TopNavbar } from "@materialui-reactjs/admin/top-navbar";
+```
+
+### ECharts Components
+
+The `echarts` package provides reusable chart components based on ECharts.
+
+- `BarChart`
+- `LineChart`
+- `MultiBarChart`
+- `MultiLineChart`
+- `PieChart`
+
+Example:
+
+```tsx
+import { BarChart } from "@materialui-reactjs/admin/echarts";
+
+export default function DashboardChart() {
+    return <BarChart />;
+}
+```
+
+### Loader
+
+The `loader` package provides loading indicators.
+
+- `SpinnerLoader`
+
+Example:
+
+```tsx
+import { SpinnerLoader } from "@materialui-reactjs/admin/loader";
+
+export default function Loading() {
+    return <SpinnerLoader />;
+}
+```
+
+## Hooks
+
+The `hook` package provides reusable helpers for common admin data workflows.
+
+Available helpers include:
+
+- `fetchHookData`
+- `handleHookClickPage`
+- `handleHookSeachForm`
+- `handleHookChange`
+- `convertQueryToSort`
+- `convertSortToQuery`
+
+These helpers can be used to standardize:
+
+- API data loading
+- Pagination
+- Search
+- Sorting
+- Form changes
+- List/detail/update workflows
+
+Example:
+
+```ts
+import {
+    fetchHookData,
+    handleHookClickPage,
+    handleHookChange,
+} from "@materialui-reactjs/admin/hook";
+```
+
+## Utilities
+
+The `utils` package provides common utilities for admin applications.
+
+Available utilities include:
+
+- `callFetchApi`
+- `callFetchApiToken`
+- `createQueryString`
+- `loadEnv`
+- `getEnv`
+- `reloadEnv`
+- `escapeHtml`
+- `CusRoute`
+
+Example:
+
+```ts
+import {
+    callFetchApi,
+    callFetchApiToken,
+    createQueryString,
+} from "@materialui-reactjs/admin/utils";
+```
+
+## Installation
+
+Install the package using npm:
+
+```bash
+npm install @materialui-reactjs/admin
+```
+
+Or using yarn:
+
+```bash
+yarn add @materialui-reactjs/admin
+```
+
+Or using pnpm:
+
+```bash
+pnpm add @materialui-reactjs/admin
+```
+
+### Runtime configuration (`/env.json`)
+
+The package reads its runtime configuration from `/env.json` served at the app root.
+Recognised keys: `API_URL`, `ADMIN_URI`, `UPLOADS_URL`, `STATIC_URL`, `SECRET_KEY`.
+
+```json
+{
+    "API_URL": "https://example.com/api",
+    "ADMIN_URI": "/admin",
+    "UPLOADS_URL": "https://example.com/uploads",
+    "STATIC_URL": "https://example.com/static",
+    "SECRET_KEY": "..."
+}
+```
+
+Notes:
+
+- The file is fetched once, in the background — it never blocks the module graph, and a
+  missing or invalid `env.json` is **not** fatal. Values simply resolve to `""`.
+- Read values at any time with `getEnv()`, and force a retry with `reloadEnv()`.
+- `SECRET_KEY` is sent as the `Secret-Key` request header. It is visible to the browser —
+  never put a real privileged credential here; treat it as a shared public identifier only.
+
+### jQuery
+
+Form validation (`Validator`) requires jQuery, declared as a peer dependency.
+Load it **before** rendering any form component:
+
+```ts
+import "jquery";
+```
+
+If jQuery is missing, the error thrown points at this requirement instead of failing
+silently during import.
+
+## Basic Usage
+
+Components can be imported directly from their corresponding subpath.
+
+```tsx
+import { Sidebar } from "@materialui-reactjs/admin/sidebar";
+import { TopNavbar } from "@materialui-reactjs/admin/top-navbar";
+import { CardTable } from "@materialui-reactjs/admin/meta";
+import { CusForm } from "@materialui-reactjs/admin/form";
+
+export default function AdminLayout() {
+    return (
+        <>
+            <TopNavbar />
+            <Sidebar />
+            <CardTable />
+            <CusForm />
+        </>
+    );
+}
+```
+
+## Import by Feature Group
+
+### Form
+
+```tsx
+import { CusForm, DateInput, DateTimeInput, SelectBox } from "@materialui-reactjs/admin/form";
+```
+
+### Meta
+
+```tsx
+import { CardTable, Pagination, SearchBox, ModalForm } from "@materialui-reactjs/admin/meta";
+```
+
+### Sidebar
+
+```tsx
+import { Sidebar } from "@materialui-reactjs/admin/sidebar";
+```
+
+### Top Navbar
+
+```tsx
+import { TopNavbar } from "@materialui-reactjs/admin/top-navbar";
+```
+
+### ECharts
+
+```tsx
+import { BarChart, LineChart, PieChart } from "@materialui-reactjs/admin/echarts";
+```
+
+### Loader
+
+```tsx
+import { SpinnerLoader } from "@materialui-reactjs/admin/loader";
+```
+
+### Utilities
+
+```tsx
+import {
+    callFetchApi,
+    callFetchApiToken,
+    loadEnv,
+    getEnv,
+    reloadEnv,
+} from "@materialui-reactjs/admin/utils";
+```
+
+## Styles and CSS
+
+> **Changed in 2.0.0.** The main entry no longer auto-imports the stylesheet. Import it
+> explicitly, as shown below. See [CHANGELOG.md](./CHANGELOG.md) for the migration note.
+
+The package provides CSS files for its components.
+
+Import the main stylesheet:
+
+```ts
+import "@materialui-reactjs/admin/style.css";
+```
+
+If you use Font Awesome Pro (shipped with this package), import it too:
+
+```ts
+import "@materialui-reactjs/admin/fontawesome.css";
+```
+
+Why the explicit import: the main stylesheet is ~1.4 MB (material-dashboard, jQuery UI,
+elFinder, icon fonts). Bundling it into the main entry forced every consumer to download
+all of it even when using a single component.
+
+Some component groups import their own small internal CSS automatically — that is fine.
+
+Make sure your application's build configuration supports CSS imports from npm packages.
+
+## Module formats
+
+Both ESM and CommonJS builds are published.
+
+| Format | Entry           | Resolved by                                                 |
+| ------ | --------------- | ----------------------------------------------------------- |
+| ESM    | `dist/**/*.js`  | `import` (bundlers, Vite, webpack, Node ESM)                |
+| CJS    | `dist/**/*.cjs` | `require` (Jest's default resolver, webpack 4, legacy Node) |
+
+```ts
+// ESM
+import { CardTable } from "@materialui-reactjs/admin";
+```
+
+```js
+// CommonJS
+const { CardTable } = require("@materialui-reactjs/admin");
+```
+
+> **Note:** this is a browser library. Several components import `bootstrap` at module
+> scope, which touches `document` on load. Under `require()` you therefore still need a
+> DOM environment (e.g. Jest's `jsdom` test environment, or a bundler targeting browsers).
+
+## Dependencies
+
+This package is built with and integrates with the following libraries.
+
+### UI and Styling
+
+| Package               | Purpose                                       |
+| --------------------- | --------------------------------------------- |
+| `@mui/material`       | Material UI components and UI system          |
+| `@mui/x-date-pickers` | Date and time picker components for MUI       |
+| `@emotion/react`      | Emotion styling engine                        |
+| `@emotion/styled`     | Styled components powered by Emotion          |
+| `bootstrap`           | CSS framework and responsive layout utilities |
+
+### React and State Management
+
+| Package              | Purpose                         |
+| -------------------- | ------------------------------- |
+| `react`              | Core React library              |
+| `react-dom`          | React DOM rendering             |
+| `@reduxjs/toolkit`   | Redux state management          |
+| `react-redux`        | React bindings for Redux        |
+| `react-router-dom`   | Client-side routing             |
+| `react-helmet-async` | Managing document head metadata |
+
+### Form and Editor
+
+| Package                     | Purpose                            |
+| --------------------------- | ---------------------------------- |
+| `@ckeditor/ckeditor5-react` | CKEditor React integration         |
+| `react-select`              | Select and multi-select components |
+| `date-fns`                  | Date manipulation and formatting   |
+| `decimal.js`                | Precise decimal calculations       |
+
+### Drag and Drop / Sorting
+
+| Package              | Purpose                              |
+| -------------------- | ------------------------------------ |
+| `@dnd-kit/sortable`  | Sortable drag-and-drop functionality |
+| `@dnd-kit/utilities` | Utilities for dnd-kit                |
+| `@hello-pangea/dnd`  | Drag-and-drop components for React   |
+| `react-sortablejs`   | React integration for SortableJS     |
+| `sortablejs`         | Drag-and-drop sorting engine         |
+
+### Charts
+
+| Package             | Purpose                                |
+| ------------------- | -------------------------------------- |
+| `echarts`           | Charting and data visualization engine |
+| `echarts-for-react` | React wrapper for ECharts              |
+
+### Utilities and Notifications
+
+| Package                     | Purpose                                              |
+| --------------------------- | ---------------------------------------------------- |
+| `jquery`                    | DOM manipulation and third-party library integration |
+| `sweetalert2`               | Alerts, confirmations, and notifications             |
+| `sweetalert2-react-content` | React integration for SweetAlert2                    |
+
+## Testing
+
+Unit tests use [Vitest](https://vitest.dev) with [React Testing Library](https://testing-library.com/react/).
+Test sources live in `test/` and are kept out of the published package (`files` only ships `dist`).
+
+| Command                 | Purpose                                   |
+| ----------------------- | ----------------------------------------- |
+| `npm test`              | Run the suite once                        |
+| `npm run test:watch`    | Watch mode                                |
+| `npm run test:coverage` | V8 coverage report                        |
+| `npm run typecheck`     | `tsc` for both `src` and `test`           |
+| `npm run lint`          | ESLint (flat config)                      |
+| `npm run format`        | Prettier write                            |
+| `npm run format:check`  | Prettier check — **gated** in `verify`/CI |
+| `npm run verify`        | `format:check → lint → typecheck → test`  |
+
+`verify` and CI both run `format:check` first, so code that drifts from the
+Prettier config fails fast instead of accumulating as unreviewed diff noise.
+
+`ckeditor5` is declared as an **optional** peer dependency: it is only needed if you use
+the `Editor` component. The editor build (`src/ckeditor/`) is plain TypeScript that
+imports from `ckeditor5`, so CKEditor is **never** bundled into this package — the
+consumer installs it and their bundler tree-shakes it, so an app only ever ships a
+single copy of CKEditor.
+
+```bash
+npm test              # run once
+npm run test:watch    # watch mode
+npm run test:coverage # + coverage report (./coverage)
+npm run typecheck     # tsc for src and test
+```
+
+Coverage config lives in `vitest.config.ts` (kept separate from `vite.config.ts` so the
+library build is never affected by test settings). The suite focuses on the behaviour
+that is easy to regress silently:
+
+| Area                            | What is locked down                                                                              |
+| ------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `checkUploadFile`               | rejects (never hangs) on bad extension, oversize, empty list; honours a custom `RegExp`          |
+| `checkPermission`               | fail-closed, recurses into `subs`, respects `status`, `groupId` guards                           |
+| `escapeHtml` / `showMessage`    | escapes all 5 HTML metacharacters, `type` allowlist, `{ raw: true }` opt-in                      |
+| `getIdParams`                   | `edit`/`detail` routes, trailing segments, nested routes, custom pattern                         |
+| `Env`                           | 404 and network errors resolve to `{}` instead of rejecting; single fetch; `reloadEnv()`         |
+| `Validator`                     | resolves jQuery lazily; clear error when jQuery is missing                                       |
+| Upload components               | object URLs are cached, revoked on remove and on unmount, and never recreated on re-render       |
+| `CardTable`                     | raw API data is never injected as HTML (`selecthtml` without `func`)                             |
+| `SpinnerLoader`                 | children still render when `loading` is `undefined`                                              |
+| `SingleIndex`                   | 403 on missing permission, page from the query string, pagination re-fetches, `DELETE` on delete |
+| `SearchBox`                     | reads `filter[field]` dynamically so inputs reflect the active filter                            |
+| `RatioKeyVal`                   | radio `id`s are unique and stable across re-renders (`useId`, not `Math.random`)                 |
+| File hooks                      | an empty `FileList` yields `null`, not `undefined`, so the key survives JSON                     |
+| `deepMerge` / `handleObjChange` | nested `{a}{b}` field names rebuild the object; `deepMerge` does not mutate its inputs           |
+| `Sidebar`                       | menus are filtered by `module`/`status`/`isPer`; active state tracks `currentPath`               |
+| ECharts wrappers                | each `series` entry becomes its own series; `visible` triggers `resize()`                        |
+
+Test helpers live in `test/helpers/`:
+
+- `makeFile(name, { size })` — a `File` with a controllable size
+- `makeFileList(files)` — a `FileList` (jsdom has no constructor for it)
+- `withTimeout(promise)` — fails loudly if a promise never settles
+
+## Requirements
+
+The package is designed for modern React applications.
+
+Current core versions include:
+
+- React `19.3.x`
+- React DOM `19.3.x`
+- React Router `7.x`
+- MUI `9.x`
+- MUI X Date Pickers `9.x`
+- Redux Toolkit `2.x`
+- Bootstrap `5.x`
+- ECharts `6.x`
+
+For the exact versions used by a particular release, check the package's `package.json`.
+
+Node `>=20.19.0` is required (Vite 8's floor for consumers). CI runs on Node 24 because
+the dev-only `jsdom@30` needs a newer runtime.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md). The `2.4.0` release fixes three packaging bugs
+found by installing the packed tarball into a clean project, and adds a consumer
+smoke test to CI to prevent regressions of that kind. `2.3.0` adds tests for the
+form components; `2.2.0` was a type-safety pass over the public API; `2.1.1` fixed
+a 27.7 MB stylesheet caused by inlined webfonts; `2.1.0` was a test-coverage pass,
+and `2.0.0` contained the breaking change where the main stylesheet is no longer
+auto-imported.