RSI react-spreadsheet-import ⚡️

![GitHub Workflow Status](https://img.shields.io/github/workflow/status/UgnisSoftware/react-spreadsheet-import/Node.js%20CI) ![GitHub](https://img.shields.io/github/license/UgnisSoftware/react-spreadsheet-import) [![npm](https://img.shields.io/npm/v/react-spreadsheet-import)](https://www.npmjs.com/package/react-spreadsheet-import)

``` ## Required Props ```tsx // Determines if modal is visible. isOpen: Boolean // Called when flow is closed without reaching submit. onClose: () => void // Called after user completes the flow. Provides data array, where data keys matches your field keys. onSubmit: (data, file) => void ``` ### Fields Fields describe what data you are trying to collect. ```tsx const fields = [ { // Visible in table header and when matching columns. label: "Name", // This is the key used for this field when we call onSubmit. key: "name", // Allows for better automatic column matching. Optional. alternateMatches: ["first name", "first"], // Used when editing and validating information. fieldType: { // There are 3 types - "input" / "checkbox" / "select". type: "input", }, // Used in the first step to provide an example of what data is expected in this field. Optional. example: "Stephanie", // Can have multiple validations that are visible in Validation Step table. validations: [ { // Can be "required" / "unique" / "regex" rule: "required", errorMessage: "Name is required", // There can be "info" / "warning" / "error" levels. Optional. Default "error". level: "error", }, ], }, ] as const ``` ## Optional Props ### Hooks You can transform and validate data with custom hooks. There are hooks after each step: - **uploadStepHook** - runs only once after uploading the file. - **selectHeaderStepHook** - runs only once after selecting the header row in spreadsheet. - **matchColumnsStepHook** - runs only once after column matching. Operations on data that are expensive should be done here. The last step - validation step has 2 unique hooks that run only in that step with different performance tradeoffs: - **tableHook** - runs at the start and on any change. Runs on all rows. Very expensive, but can change rows that depend on other rows. - **rowHook** - runs at the start and on any row change. Runs only on the rows changed. Fastest, most validations and transformations should be done here. Example: ```tsx { // Validation if (data.name === "John") { addError("name", { message: "No Johns allowed", level: "info" }) } // Transformation return { ...data, name: "Not John" } // Sorry John }} /> ``` ### Initial state In rare case when you need to skip the beginning of the flow, you can start the flow from any of the steps. - **initialStepState** - initial state of component that will be rendered on load. ```tsx initialStepState?: StepState type StepState = | { type: StepType.upload } | { type: StepType.selectSheet workbook: XLSX.WorkBook } | { type: StepType.selectHeader data: RawData[] } | { type: StepType.matchColumns data: RawData[] headerValues: RawData } | { type: StepType.validateData data: any[] } type RawData = Array // XLSX.workbook type is native to SheetJS and can be viewed here: https://github.com/SheetJS/sheetjs/blob/83ddb4c1203f6bac052d8c1608b32fead02ea32f/types/index.d.ts#L269 ``` Example: ```tsx import { ReactSpreadsheetImport, StepType } from "react-spreadsheet-import"; ``` ### Dates and time Excel stores dates and times as numbers - offsets from an epoch. When reading xlsx files SheetJS provides date formatting helpers. **Default date import format** is `yyyy-mm-dd`. Date parsing with SheetJS sometimes yields unexpected results, therefore thorough date validations are recommended. - **dateFormat** - sets SheetJS `dateNF` option. Can be used to format dates when importing sheet data. - **parseRaw** - sets SheetJS `raw` option. If `true`, date formatting will be applied to XLSX date fields only. Default is `true` Common date-time formats can be viewed [here](https://docs.sheetjs.com/docs/csf/features/dates/#date-and-time-number-formats). ### Other optional props ```tsx // Allows submitting with errors. Default: true allowInvalidSubmit?: boolean // Translations for each text. See customisation bellow translations?: object // Theme configuration passed to underlying Chakra-UI. See customisation bellow customTheme?: object // Specifies maximum number of rows for a single import maxRecords?: number // Maximum upload filesize (in bytes) maxFileSize?: number // Automatically map imported headers to specified fields if possible. Default: true autoMapHeaders?: boolean // When field type is "select", automatically match values if possible. Default: false autoMapSelectValues?: boolean // Headers matching accuracy: 1 for strict and up for more flexible matching. Default: 2 autoMapDistance?: number ``` ## Customisation ### Customising styles (colors, fonts) You can see default theme we use [here](https://github.com/UgnisSoftware/react-spreadsheet-import/blob/master/src/theme.ts). Your override should match this object's structure. There are 3 ways you can style the component: 1.) Change theme colors globally ```jsx ``` Screenshot 2022-04-13 at 10 24 34

2.) Change all components of the same type, like all Buttons, at the same time ```jsx ``` Screenshot 2022-04-13 at 11 04 30

3.) Change components specifically in each Step. ```jsx ``` Screenshot 2022-04-13 at 10 21 58

Underneath we use Chakra-UI, you can send in a custom theme for us to apply. Read more about themes [here](https://chakra-ui.com/docs/styled-system/theming/theme) ### Changing text (translations) You can change any text in the flow: ```tsx ``` You can see all the translation keys [here](https://github.com/UgnisSoftware/react-spreadsheet-import/blob/master/src/translationsRSIProps.ts) ## VS other libraries Flatfile vs react-spreadsheet-import and Dromo vs react-spreadsheet-import: | | RSI | Flatfile | Dromo | | ------------------------------ | -------------- | ----------- | ----------- | | Licence | MIT | Proprietary | Proprietary | | Price | Free | Paid | Paid | | Support | Github Issues | Enterprise | Enterprise | | Self-host | Yes | Paid | Paid | | Hosted solution | In development | Yes | Yes | | On-prem deployment | N/A | Yes | Yes | | Hooks | Yes | Yes | Yes | | Automatic header matching | Yes | Yes | Yes | | Data validation | Yes | Yes | Yes | | Custom styling | Yes | Yes | Yes | | Translations | Yes | Yes | Yes | | Trademarked words `Data Hooks` | No | Yes | No | React-spreadsheet-import can be used as a free and open-source alternative to Flatfile and Dromo. ## Contributing Feel free to open issues if you have any questions or notice bugs. If you want different component behaviour, consider forking the project. ## Credits Created by Ugnis. [Julita Kriauciunaite](https://github.com/JulitorK) and [Karolis Masiulis](https://github.com/masiulis). You can contact us at `info@ugnis.com`