DocSpace-client/packages/shared/components/email-input/EmailInput.mdx

167 lines
5.5 KiB
Plaintext
Raw Normal View History

2024-03-21 14:09:55 +00:00
// (c) Copyright Ascensio System SIA 2009-2024
2024-03-17 23:13:02 +00:00
//
// This program is a free software product.
// You can redistribute it and/or modify it under the terms
// of the GNU Affero General Public License (AGPL) version 3 as published by the Free Software
// Foundation. In accordance with Section 7(a) of the GNU AGPL its Section 15 shall be amended
// to the effect that Ascensio System SIA expressly excludes the warranty of non-infringement of
// any third-party rights.
//
// This program is distributed WITHOUT ANY WARRANTY, without even the implied warranty
// of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. For details, see
// the GNU AGPL at: http://www.gnu.org/licenses/agpl-3.0.html
//
// You can contact Ascensio System SIA at Lubanas st. 125a-25, Riga, Latvia, EU, LV-1021.
//
// The interactive user interfaces in modified source and object code versions of the Program must
// display Appropriate Legal Notices, as required under Section 5 of the GNU AGPL version 3.
//
// Pursuant to Section 7(b) of the License you must retain the original Product logo when
// distributing the program. Pursuant to Section 7(e) we decline to grant you any rights under
// trademark law for use of our trademarks.
//
// All the Product's GUI elements, including illustrations and icon sets, as well as technical writing
// content are licensed under the terms of the Creative Commons Attribution-ShareAlike 4.0
// International. See the License terms at http://creativecommons.org/licenses/by-sa/4.0/legalcode
import { Meta, Story, ArgsTable, Canvas } from "@storybook/blocks";
2023-12-06 15:40:58 +00:00
import { EmailInput } from "./";
import * as stories from "./EmailInput.stories.js";
<Meta
title="Components/EmailInput"
component={EmailInput}
parameters={{
source: {
code: stories.basic,
},
}}
argTypes={{
onValidateInput: { action: "onValidateInput", table: { disable: true } },
onChange: { action: "onChange", table: { disable: true } },
}}
/>
# EmailInput
Email entry field with advanced capabilities for validation based on setting
<Canvas>
<Story story={stories.basic} name="Default" />
</Canvas>
### Properties
You can apply all properties of the `TextInput` component to the component
<ArgsTable story="Default" />
### Validate email
Our validation algorithm based on [RFC 5322 email address parser](https://www.npmjs.com/package/email-addresses).
For email validating you should use instance of EmailSettings class with following settings:
```js
const settings = new EmailSettings();
settings.allowDomainPunycode = false;
settings.allowLocalPartPunycode = false;
settings.allowDomainIp = false;
settings.allowStrictLocalPart = true;
settings.allowSpaces = false;
settings.allowName = false;
settings.allowLocalDomainName = false;
```
```js
import { EmailInput, utils } from "@docspace/shared/components";
const { EmailSettings } = utils.email;
const emailSettings = new EmailSettings();
emailSettings.toObject(); /* returned Object with default settings:
{
allowDomainPunycode: false,
allowLocalPartPunycode: false,
allowDomainIp: false,
allowStrictLocalPart: true,
allowSpaces: false,
allowName: false,
allowLocalDomainName: false
}
*/
email.allowName = true; // set allowName setting to true
emailSettings.toObject(); /* returned Object with NEW settings:
{
allowDomainPunycode: false,
allowLocalPartPunycode: false,
allowDomainIp: false,
allowStrictLocalPart: true,
allowSpaces: false,
allowName: true,
allowLocalDomainName: false
}
*/
```
### Custom validate email
You should use custom validation with the `customValidate` prop. This prop contains function for your custom validation input value. Function must return object with following parameters: `value`: string value of input, `isValid`: boolean result of validating, `errors`(optional): array of errors.
#### Base colors:
| Сomponent actions | isValid | border-color |
| ----------------- | :-----: | :--------------------------------------------------------------: |
| `:focus` | `false` | ![#c30](https://placehold.it/15/c30/000000?text=+) #c30 |
| `:focus` | `true` | ![#2DA7DB](https://placehold.it/15/2DA7DB/000000?text=+) #2DA7DB |
| `:hover` | `false` | ![#c30](https://placehold.it/15/c30/000000?text=+) #c30 |
| `:hover` | `true` | ![#D0D5DA](https://placehold.it/15/D0D5DA/000000?text=+) #D0D5DA |
| `default` | `false` | ![#c30](https://placehold.it/15/c30/000000?text=+) #c30 |
| `default` | `true` | ![#D0D5DA](https://placehold.it/15/D0D5DA/000000?text=+) #D0D5DA |
```jsx
import React from "react";
import {EmailInput } from "@docspace/shared/components";
const onChange = (e) => {
// your event handling
customValidate(e.target.value);
};
const customValidate = (value) => {
const isValid = !!(value && value.length > 0);
return {
value,
isValid: isValid,
errors: isValid ? [] : ["incorrect email"],
};
};
const onValidateInput = (result) => {
console.log("onValidateInput", result);
};
<EmailInput
customValidate={customValidate}
onChange={onChange}
onValidateInput={onValidateInput}
/>;
```
```jsx
import { EmailSettings } from "@docspace/shared/utils/email";
const settings = new EmailSettings();
settings.allowDomainPunycode = true;
```
```jsx
<EmailInput
name="email"
placeholder="email"
emailSettings={settings}
onValidateInput={result =>
console.log("onValidateInput", result.value, result.isValid, result.errors);
}
/>
```