ngx-form-stepper 0.0.10 → 0.0.12

package/README.md

@@ -2,7 +2,7 @@
 
 [🇫🇷 Lire la version française](https://github.com/rayaneriahi/ngx-form-stepper/blob/main/README.fr.md)
 
-**ngx-form-stepper** is an Angular library to create multi-step forms with field-level validations, **extremely typed**.
+**ngx-form-stepper** is an Angular library that allows you to create multi-step forms with field-level validation, **extremely strongly typed**.
 
 It prevents creating invalid states **at development time**, not at runtime.
 
@@ -62,26 +62,6 @@ onComplete() {
 
 ## Input
 
-Each `Input` type only accepts compatible `validators`.
-
-Examples :
-
-- `email` ❌ forbidden on `number`
-- `minLength` ❌ forbidden on `checkbox`
-- `confirm` ❌ forbidden on `select`
-
-And only default values that are compatible.
-
-Examples :
-
-- `string` ❌ forbidden on `number`
-- `number` ❌ forbidden on `checkbox`
-- `string | number` ❌ forbidden on `select`
-
-Return key must be camelCase.
-
-Duplicating a `validator` is impossible.
-
 ```typescript
 export class Input<
   T extends InputType,
@@ -116,6 +96,28 @@ export enum InputType {
 }
 ```
 
+Each `Input` type only accepts compatible default values.
+
+```typescript
+export type InputDefaultValue<T extends InputType> = T extends InputType.Text
+  ? string | null
+  : T extends InputType.Password
+  ? string | null
+  : T extends InputType.Email
+  ? string | null
+  : T extends InputType.Number
+  ? number | null
+  : T extends InputType.Tel
+  ? string | null
+  : T extends InputType.Checkbox
+  ? boolean | null
+  : T extends InputType.Date
+  ? Date | null
+  : T extends InputType.Select
+  ? Select<SelectItemTuple, number | null>
+  : never;
+```
+
 ## Validator
 
 A `validator` is a function that can be passed to an `Input`. It takes different arguments like conditional values or error text.
@@ -156,6 +158,52 @@ export type ValidatorsNames =
   | 'maxDate';
 ```
 
+Each `Input` type only accepts compatible validators.
+
+```typescript
+export type ValidatorsNamesOfType<T extends InputType> = T extends InputType.Text
+  ? 'required' | 'confirm' | 'minLength' | 'maxLength' | 'pattern'
+  : T extends InputType.Password
+  ? 'required' | 'confirm' | 'strongPassword' | 'pattern'
+  : T extends InputType.Email
+  ? 'required' | 'confirm' | 'email'
+  : T extends InputType.Number
+  ? 'required' | 'confirm' | 'min' | 'max' | 'integer'
+  : T extends InputType.Tel
+  ? 'required' | 'confirm' | 'phone'
+  : T extends InputType.Checkbox
+  ? 'check'
+  : T extends InputType.Date
+  ? 'required' | 'confirm' | 'minDate' | 'maxDate'
+  : T extends InputType.Select
+  ? 'required'
+  : never;
+```
+
+## Reusing typed validators
+
+**ngx-form-stepper** allows you to factor them out, then create groups of `validators` that are compatible only with a given `Input` type:
+
+```typescript
+reqVal: Validator<'required'> = required('Field is required');
+
+emailValidators: ValidatorTuple<ValidatorsNamesOfType<InputType.Email>> = [
+  reqVal,
+  email('E-mail is not valid'),
+];
+```
+
+What is impossible (and intentional)
+
+```typescript
+// ❌ Compilation error
+const badValidators: ValidatorTuple<ValidatorsNamesOfType<InputType.Number>> = [
+  email('Invalid email'),
+];
+```
+
+This error is detected at compile time, even before running the application.
+
 ## Select
 
 Tuple of one or more `SelectItem`.
@@ -190,9 +238,25 @@ export type SelectItem = {
 };
 ```
 
-## Step
+Assigning an invalid currentIndex is impossible.
 
-Impossible to duplicate an `Input` return key.
+```typescript
+// ❌ Compilation error
+invalid = new Input(
+  InputType.Select,
+  new Select(
+    [
+      { label: 'Male', value: 'male' },
+      { label: 'Female', value: 'female' },
+    ],
+    5
+  ),
+  'gender',
+  'Gender'
+);
+```
+
+## Step
 
 Tuple of one or more `Inputs`.
 
@@ -209,12 +273,20 @@ export type StepConfig = Readonly<{
 }>;
 ```
 
+Duplication of `returnKey` is forbidden (and intentional)
+
+```typescript
+// ❌ Compilation error
+new Step([
+  new Input(InputType.Text, null, 'name', 'First name'),
+  new Input(InputType.Text, null, 'name', 'Last name'),
+]);
+```
+
 ## FormStepper
 
 Impossible to duplicate an `Input` return key between two `Steps`.
 
-Configuration object depending on the number of `Steps`.
-
 Tuple of one or more `Steps`.
 
 ```typescript
@@ -230,7 +302,11 @@ export class FormStepper<T extends StepTuple> {
     ) as FormStepperValues<T>;
   }
 }
+```
+
+Configuration object depending on the number of `Steps`.
 
+```typescript
 export type SingleStepConfig = Readonly<{
   title?: string;
   actionText?: RedirectItem[];
@@ -253,7 +329,7 @@ export type MultiStepConfig = Readonly<{
 A `RedirectItem[]` is an array of strings or `RedirectUrl` objects, a kind of mini TS language to create texts with clickable links.
 
 ```typescript
-actionText = ['You already have an account ?', { url: '/signin', urlText: 'Sign in' }];
+actionText = ['You already have an account?', { url: '/signin', urlText: 'Sign in' }];
 
 export type RedirectUrl = Readonly<{ url: string; urlText: string }>;
 
@@ -288,7 +364,10 @@ classNames: SingleStepClassNames = {
   },
 };
 
-form = new FormStepper([this.step], { buttonText: 'Submit', classNames: this.classNames });
+form = new FormStepper([this.step], {
+  buttonText: 'Submit',
+  classNames: this.classNames,
+});
 ```
 
 ```css
@@ -384,3 +463,10 @@ export type MultiStepClassNames = DeepPartial<{
   };
 }>;
 ```
+
+## In summary
+
+- Common errors are impossible
+- Types guide the implementation
+- The final form is always consistent
+- The compiler becomes an ally

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-form-stepper",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rayaneriahi/ngx-form-stepper.git"