ngx-form-stepper 0.0.1

package/README.fr.md

@@ -0,0 +1,374 @@
+# ngx-form-stepper
+
+**ngx-form-stepper** est une librairie Angular pour créer des formulaires à étapes avec validations par champ, **extrêmement typée**.
+
+Elle empêche la création d’états invalides **au moment du développement**, pas à l’exécution.
+
+Destinée aux développeurs Angular qui veulent des formulaires robustes, typés et maintenables sans configuration complexe.
+
+## Pourquoi ?
+
+- Formulaires multi-étapes simples à déclarer
+- Validation par champ rapide à mettre en place
+- Impossible d’associer un mauvais `validator` à un `Input`
+- Valeurs toujours cohérentes avec leur type
+- Clés de retour uniques obligatoires
+- **Aucun `as const` requis**
+
+## Exemple rapide
+
+```typescript
+step1 = new Step([
+  new Input(InputType.Text, null, 'firstName', 'First name', [required('First name is required')]),
+  new Input(InputType.Text, null, 'lastName', 'Last name', [required('Last name is required')]),
+]);
+
+step2 = new Step([
+  new Input(InputType.Email, null, 'email', 'E-mail', [
+    required('E-mail is required'),
+    email('E-mail is invalid'),
+  ]),
+  new Input(InputType.Password, null, 'password', 'Password', [
+    required('Password is required'),
+    strongPassword('Password is too weak'),
+  ]),
+]);
+
+signupForm = new FormStepper([step1, step2], {
+  title: 'Sign in',
+  buttonText: { next: 'Next', previous: 'Previous', final: 'Sign up' },
+});
+
+onComplete() {
+  console.log(signupForm.values);
+}
+```
+
+```html
+<app-form-stepper [formStepper]="signupForm" (completed)="onComplete()" />
+```
+
+## Input
+
+Chaque type d’`Input` accepte uniquement les `validators` compatibles.
+
+Exemples :
+
+- `email` ❌ interdit sur `number`
+- `minLength` ❌ interdit sur `checkbox`
+- `confirm` ❌ interdit sur `select`
+
+Et uniquement les valeurs par défaut compatibles.
+
+Exemples :
+
+- `string` ❌ interdit sur `number`
+- `number` ❌ interdit sur `checkbox`
+- `string | number` ❌ interdit sur `select`
+
+Clé de retour au format camelCase.
+
+Impossible de dupliquer un `validator`.
+
+```typescript
+export class Input<
+  T extends InputType,
+  D extends InputDefaultValue<T>,
+  K extends string,
+  V extends ValidatorTuple<ValidatorsNamesOfType<T>>
+> {
+  readonly defaultValue: D;
+
+  constructor(
+    readonly type: T,
+    defaultValue: D,
+    readonly returnKey: IsCamelCase<K> extends true ? K : never,
+    readonly label: string,
+    readonly validators?: HasDuplicateValidators<V> extends true ? never : V
+  ) {
+    this.defaultValue = (
+      type === InputType.Checkbox ? (defaultValue === null ? false : defaultValue) : defaultValue
+    ) as D;
+  }
+}
+
+export enum InputType {
+  Text = 'text',
+  Password = 'password',
+  Email = 'email',
+  Number = 'number',
+  Tel = 'tel',
+  Checkbox = 'checkbox',
+  Date = 'date',
+  Select = 'select',
+}
+```
+
+## Validator
+
+Un `validator` est une fonction qu’on peut passer à un `Input`. Elle prend différents arguments comme la valeur conditionnelle ou le texte de l’erreur.
+
+```typescript
+export function minLength(min: number, errorText: string): Validator<'minLength'> {
+  const name: StandardValidatorNameFn<'minLength'> = (params: { key: string }) =>
+    `${params.key}-minLength`;
+
+  const fn = (params: { key: string }) => (control: AbstractControl<string>) => {
+    const customName: StandardValidatorName<'minLength'> = `${params.key}-minLength`;
+
+    return control.value.length < min ? { [customName]: true } : null;
+  };
+
+  return {
+    kind: 'minLength',
+    name,
+    fn,
+    errorText,
+  };
+}
+
+export type ValidatorsNames =
+  | 'required'
+  | 'check'
+  | 'confirm'
+  | 'minLength'
+  | 'maxLength'
+  | 'min'
+  | 'max'
+  | 'integer'
+  | 'pattern'
+  | 'strongPassword'
+  | 'email'
+  | 'phone'
+  | 'minDate'
+  | 'maxDate';
+```
+
+## Select
+
+Tuple d'un ou plusieurs `SelectItem`.
+
+Le `currentIndex` doit obligatoirement être un index valide du tuple ou null.
+
+```typescript
+select = new Input(
+  InputType.Select,
+  new Select(
+    [
+      { label: 'Male', value: 'male' },
+      { label: 'Female', value: 'female' },
+    ],
+    0
+  ),
+  'gender',
+  'Gender'
+);
+
+export class Select<T extends SelectItemTuple, I extends number | null> {
+  current: SelectItem | null;
+
+  constructor(readonly items: T, readonly currentIndex: HasIndex<T, I> extends true ? I : never) {
+    this.current = currentIndex === null ? null : this.items[currentIndex];
+  }
+}
+
+export type SelectItem = {
+  label: string;
+  value: string;
+};
+```
+
+## Step
+
+Impossible de dupliquer la clé de retour d’un `Input`.
+
+Tuple d’un ou plusieurs `Inputs`.
+
+```typescript
+export class Step<T extends InputTuple> {
+  constructor(
+    readonly inputs: HasDuplicateReturnKeys<T> extends true ? never : T,
+    readonly config?: StepConfig
+  ) {}
+}
+
+export type StepConfig = Readonly<{
+  title: string;
+}>;
+```
+
+## FormStepper
+
+Impossible de dupliquer la clé de retour d’un `Input` entre deux `Steps`.
+
+Objet de configuration qui dépend du nombre de `Steps`.
+
+Tuple d’une ou plusieurs `Steps`.
+
+```typescript
+export class FormStepper<T extends StepTuple> {
+  readonly values: FormStepperValues<T>;
+
+  constructor(
+    readonly steps: HasDuplicateReturnKeys<T> extends true ? never : T,
+    readonly config: T extends MultiStepTuple ? MultiStepConfig : SingleStepConfig
+  ) {
+    this.values = Object.fromEntries(
+      steps.flatMap((step) => step.inputs.map((input) => [input.returnKey, input.defaultValue]))
+    ) as FormStepperValues<T>;
+  }
+}
+
+export type SingleStepConfig = Readonly<{
+  title?: string;
+  actionText?: RedirectItem[];
+  buttonText: SingleStepButtonText;
+  footerText?: RedirectItem[];
+  classNames?: SingleStepClassNames;
+}>;
+
+export type MultiStepConfig = Readonly<{
+  title?: string;
+  actionText?: RedirectItem[];
+  buttonText: MultiStepButtonText;
+  footerText?: RedirectItem[];
+  classNames?: MultiStepClassNames;
+}>;
+```
+
+## RedirectItem[]
+
+Un `RedirectItem[]` est un tableau de string ou d’objet `RedirectUrl`, une sorte de mini langage TS permettant de créer des textes avec lien cliquable.
+
+```typescript
+actionText = ['You already have an account ?', { url: '/signin', urlText: 'Sign in' }];
+
+export type RedirectUrl = Readonly<{ url: string; urlText: string }>;
+
+export type RedirectText = string;
+
+export type RedirectItem = RedirectText | RedirectUrl;
+```
+
+## ButtonText
+
+La propriété `buttonText` du `FormStepper` dépend du nombre de `Steps`.
+
+```typescript
+export type SingleStepButtonText = string;
+
+export type MultiStepButtonText = Readonly<{
+  final: string;
+  previous: string;
+  next: string;
+}>;
+```
+
+## ClassNames
+
+Pour ajouter vos propres styles sur un `FormStepper`, je vous conseille de créer un fichier de style séparé et d'y ajouter vos class. Vous devrez ensuite importer le fichier créé dans le fichier global de styles de l'app.
+
+```typescript
+classNames: SingleStepClassNames = {
+  title: 'fs-title',
+  input: {
+    error: 'fs-input-error',
+  },
+};
+
+form = new FormStepper([this.step], { buttonText: 'Submit', classNames: this.classNames });
+```
+
+```css
+/* app/fs.css */
+
+.fs-title {
+  color: blue;
+}
+
+.fs-input-error {
+  color: red;
+}
+```
+
+```css
+/* styles.css */
+
+@import 'app/fs.css';
+```
+
+La propriété `classNames` du `FormStepper` dépend du nombre de `Steps`.
+
+```typescript
+export type SingleStepClassNames = DeepPartial<{
+  container: string;
+  title: string;
+  actionText: {
+    container: string;
+    text: string;
+    url: string;
+  };
+  step: {
+    container: string;
+    title: string;
+    form: string;
+    inputContainer: string;
+  };
+  input: {
+    container: string;
+    label: string;
+    required: string;
+    input: string;
+    errorContainer: string;
+    error: string;
+  };
+  button: {
+    container: string;
+    button: string;
+    disabled: string;
+  };
+  footerText: {
+    container: string;
+    text: string;
+    url: string;
+  };
+}>;
+
+export type MultiStepClassNames = DeepPartial<{
+  container: string;
+  title: string;
+  actionText: {
+    container: string;
+    text: string;
+    url: string;
+  };
+  step: {
+    container: string;
+    title: string;
+    form: string;
+    inputContainer: string;
+  };
+  input: {
+    container: string;
+    label: string;
+    required: string;
+    input: string;
+    errorContainer: string;
+    error: string;
+  };
+  button: {
+    container: string;
+    button: string;
+    disabled: string;
+    first: string;
+    final: string;
+    previous: string;
+    next: string;
+  };
+  footerText: {
+    container: string;
+    text: string;
+    url: string;
+  };
+}>;
+```