@teppen/react-ui 1.10.1 → 2.0.0

package/README.md

@@ -7,6 +7,7 @@ This is a React component library that provides some useful UI elements for your
 This library includes the following components:
 
 - Table: A simple Table. (1.0.0 ～) (※ Not compatible with 0.\*.\*)
+- FileUploader: A drop area and file picker with file type and size checks.
 
 ## Installation
 
@@ -210,8 +211,8 @@ export default App;
 A component that displays a table based on the row and column information passed as arguments. The table component has the following features:
 
 - Pagination function
-- Sorting function
-- Filtering function (only when `label` is set in the column information)
+- Sorting function (except for columns that use `render` while `editable` is false, or that set `disableSort`)
+- Filtering function (only when `label` is set in the column information; the same columns as sorting are excluded, and `disableFilter` turns it off)
 - Editing function (only when `editable` is true and `onCellBlur` is set in the column information)
 - Checkbox function
 - Paste function
@@ -219,7 +220,13 @@ A component that displays a table based on the row and column information passed
 
 #### Arguments
 
-The table component only accepts the arguments `rows`, `cols`, `initialCondition`, `onClickRow`, `onUpdateRow`, `applyRowFormatting`, `conditionalFormattings`. Details for each argument are described below.
+The table component accepts the arguments `id`, `rows`, `cols`, `initialCondition`, `onClickRow`, `onUpdateRow`, `onPasteError`, `errorHandler`, `applyRowFormatting`, `checkbox`, `conditionalFormattings`, `maxHeight` and `maxWidth`. Details for each argument are described below.
+
+All of these types are exported from the package, e.g. `import type { TTableColumn, TPropsTable } from "@teppen/react-ui";`.
+
+##### id
+
+`id` is used for the element ids inside the table. It is optional; without it, each table gets a unique id automatically.
 
 ##### rows
 
@@ -227,11 +234,13 @@ The table component only accepts the arguments `rows`, `cols`, `initialCondition
 
 ```ts
 export type DataObject = {
-  [key: string]: number | string;
+  [key: string]: number | string | Date;
   id: number | string;
 };
 ```
 
+The row objects you pass are given back unchanged to callbacks such as `onClickRow`, `onCellBlur` and `checkbox`, so `Date` values stay `Date` objects.
+
 ※ `onClick` property has been deprecated since version 1.0.0 in favor of the new Table argument `onClickRow`
 
 ##### cols
@@ -241,7 +250,7 @@ In `cols`, you specify the data to be displayed in the table from left to right.
 it is not necessary to always include the key `label`, but it is required for some functions, so it is recommended to set it.
 
 ```ts
-export type TColumnType = "string" | "number" | "select";
+export type TColumnType = "string" | "number" | "select" | "date" | "datetime";
 
 export type TTableColumn = {
   key: string;
@@ -252,6 +261,8 @@ export type TTableColumn = {
   options: { value: string; label: string }[]; // Only When "type" is "select"
   editable?: boolean;
   render?: (value: string | number, row: DataObject) => React.ReactNode; // Only When "editable" is false
+  // When "type" is "date" or "datetime", "render" is required and "editable" must be false:
+  // render: (value: Date) => React.ReactNode;
   allowEmpty?: boolean; // Only When "type" is "select"
   constraints?: {
     maxLength?: number; // Only when "type" is "string"
@@ -270,7 +281,7 @@ export type TTableColumn = {
 ```
 
 ※ TColumnType no longer supports `component` since version 1.0.0. Instead, `render`
-is now supported, allowing for sorting and filtering functions that were not previously supported by `component`.
+is now supported. Columns that use `render` (when `editable` is false) are not sortable or filterable, because what they display may differ from the underlying value.
 
 ##### initialCondition
 
@@ -297,11 +308,36 @@ type TOnClickRow = (row: DataObject) => void;
 
 In `onUpdateRow`, You can define the behavior when you paste data from Excel or spreadsheets into a table. This is optional.
 For multi-line data, this function is executed one line at a time.
+Pasted data is read as tab-separated cells, as copied from Excel or Google Sheets. For number columns, values such as `1,000` are accepted.
 
 ```ts
 type TOnUpdateRow = (newRow: DataObject, oldRow: DataObject) => void;
 ```
 
+##### onPasteError
+
+In `onPasteError`, you can handle pasted data that cannot be applied, for example when it does not fit in the table or targets a column that is not editable. This is optional; if it is not set, the message is shown with `window.alert`.
+Invalid values are reported to `errorHandler` instead.
+
+```ts
+type TOnPasteError = (error: {
+  type: "NOT_ENOUGH_ROWS" | "NOT_ENOUGH_COLUMNS" | "NOT_EDITABLE_COLUMN";
+  message: string;
+}) => void;
+```
+
+##### errorHandler
+
+In `errorHandler`, you can handle values that break a column's `constraints` (when editing a cell or pasting). This is optional; if it is not set, the errors are shown with `window.alert`.
+
+```ts
+type TErrorHandler = (errors: TErrorValidation[]) => void;
+```
+
+##### maxHeight / maxWidth
+
+CSS sizes (e.g. `"600px"`) that limit the table area. The table scrolls inside it.
+
 ##### applyRowFormatting
 
 In `applyRowFormatting`, depending on the status of each row, you can define the format of the row using TailwindCSS classes. In principle, TailwindCSS classes other than background and text color are not guaranteed to work, but any class can be specified.
@@ -343,6 +379,37 @@ type TConditionalFormatting = {
 };
 ```
 
+### FileUploader Component
+
+A drop area that also opens the file picker when clicked.
+
+```tsx
+import { FileUploader } from "@teppen/react-ui";
+
+<FileUploader
+  allowedExtensions={[".pdf", ".xlsx"]}
+  maxFileSize={10 * 1024 * 1024}
+  onFilesAdded={(files) => console.log(files)}
+  onFilesRejected={(files) => console.log("rejected", files)}
+/>;
+```
+
+Files are checked as follows:
+
+- With only `allowedExtensions`, only the extension is checked. With only `acceptedFileTypes` (MIME types such as `"image/*"`), only the MIME type is checked.
+- With neither or both, a file is accepted if it matches either list. The defaults cover common images, Office documents, PDF, text and archives.
+- Files larger than `maxFileSize` (bytes) are rejected.
+
+For a custom UI, use the `useFileUploader` hook, which returns the props for the drop area and the hidden file input.
+
+## Breaking changes since 1.10.2
+
+- Table callbacks (`onClickRow`, `applyRowFormatting`, `checkbox`, `onCellBlur`, `onUpdateRow`) receive the row objects passed in `rows` as they are. Before, some of them received copies in which `Date` values had become ISO strings.
+- FileUploader: when only `allowedExtensions` or only `acceptedFileTypes` is given, files are checked against that list alone. Before, files that matched the other (default) list were also accepted.
+- Read-only columns without `render` can now be sorted and filtered. Use `disableSort` / `disableFilter` to turn this off.
+- Copying a `datetime` cell gives `YYYY-MM-DD HH:mm:ss` in local time instead of an ISO string in UTC.
+- Pasted text is split only on tabs, so a value such as `a,b` stays in one cell.
+
 ## License
 
 This library is licensed under MIT license. See LICENSE file for more information.