<?php
namespace nur\v\model;

/**
 * Interface IFormManager: interface pour un gestionnaire de formulaire
 */
interface IFormManager {
  /** réinitialiser l'objet */
  function resetManager($options=null, ?array $schema=null): void;

  /** changer les options du formulaire et le schéma par défaut */
  function push($options=null, ?array $schema=null): void;
  /** restaurer les options du formulaire et le schéma par défaut précédents */
  function pop(): void;

  /**
   * tester si on est à l'intérieur d'un formulaire (i.e la méthode
   * {@link start()} a été appelée)
   */
  function started(): bool;

  /** commencer un formulaire */
  function start($options=null, ?array $schema=null): array;

  /** terminer le formulaire */
  function end(): array;

  /**
   * commencer une section. une section permet d'organiser un ensemble de champs
   * de formulaires
   *
   * si une section est en cours, la terminer avant de commencer la nouvelle
   * section
   */
  function section($options=null): array;

  /** terminer la section en cours */
  function endSection(): array;

  /**
   * commencer un groupe. dans un groupe, tous les éléments sont automatiquement
   * "nus", parce que c'est le groupe qui organise la mise en page des éléments
   * qui le composent.
   *
   * si un groupe est en cours, le terminer avant de commencer le nouveau groupe
   */
  function group($options=null): array;

  /** terminer le groupe en cours */
  function endGroup(): array;

  /** valeur fixe */
  function fixed($label, string $name, $value, ?array $options=null): array;

  /** champ caché */
  function hidden(string $name, $value, ?array $options=null): array;
  function hiddens(array $values, string ...$names): array;

  /** champ texte */
  function text($label, string $name, $value, ?array $options=null): array;
  function texts($label, array $values, string ...$names): array;

  /** champ mot de passe */
  function password($label, string $name, $value, ?array $options=null): array;

  /** champ liste de valeurs */
  function select($label, string $name, $value, ?array $options=null): array;

  /** case à cocher */
  function checkbox($text, string $name, $value, ?bool $checked=null, ?array $options=null): array;
  /** liste de cases à cocher */
  function checkboxes($label, string $name, $values, ?array $options=null): array;

  /** bouton radio */
  function radiobutton($text, string $name, $value, ?bool $checked=null, ?array $options=null): array;
  /** liste de boutons radio */
  function radiobuttons($label, string $name, $value, ?array $options): array;

  /** champ zone de texte */
  function textarea($label, string $name, $value, ?array $options=null): array;

  /** champ envoi de fichier */
  function file($label, string $name, ?array $options=null): array;

  /** soumission de formulaire */
  function submit($options=null): array;

  /** raz de formulaire */
  function reset($options=null): array;
}