> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Profile completion

## Functional description

***

### Main feature

The profile entry web component allows users to **declare** and **update** their household characteristics and equipment in order to **personalize energy insights and calculations**.

The profile entry is organized into **5 main categories**, each grouping a set of related questions :

* **General information** : Number of occupants, Surface ...
* **Housing** : residence type (Apartement or house), construction period,
* **Main equipment** : Heating, cooling, ...
* **Other equipment** : cooking, appliances (washing machine, ...), ...
* **Lifestyle** : Absence from home, hot water usage, ...

By default, the client sees :

* A **structured stepper** guiding users through the input process by structuring their journey across the five profile categories
* A **progress indicator** showing completion status through the input process
* **Pre-filled data** if already known (from previous declarations or contracts)

***

### Detailed features

**Step 1 — General information**

Collects the main characteristics of the user's household:

| Field | Description |
| - | - |
| Type of residency | Primary or secondary residence |
| Occupancy type | Owner or tenant |
| Surface area | Living area in m² |
| Number of occupants | Total number of people in the household |
| Heating type | Main energy source for heating (electricity, gas, etc.) |
| Sanitary hot water | Energy source for hot water (electric, gas, solar, collective, other/none) |

**Step 2 — Housing**

Collects structural characteristics of the dwelling:

| Field | Description |
| - | - |
| Housing type | House or apartment |
| House specificities | Shared wall, multiple floors, veranda, converted attic (if house) |
| Apartment placement | Floor level: ground floor, mid-floor, last floor with/without converted attic (if apartment) |
| Year of construction | Used to estimate insulation quality |
| Natural light | Window surface intensity: high, mid, low |
| Renovation | Whether walls, windows, or attic have been renovated |

**Step 3 — Main equipment**

Collects information about the main energy-consuming equipment:

| Section | Fields |
| - | - |
| Principal heating | System type, heated surface |
| Secondary heating | Energy source, system type, heated surface |
| Wood insert | Presence, cubic meters of wood consumed per year |
| Target room temperature | Living room target temperature |
| Air conditioning | Presence, mean air-conditioned surface, target temperature |
| Electric vehicle | Presence, brand, model, journey type, home charging frequency, mileage |
| Swimming pool | Presence, months of use per year, heating equipment type |

**Step 4 — Other equipment**

Collects the household appliances inventory:

| Section | Fields |
| - | - |
| Cooking | Equipment quantities (gas/induction/ceramic cooktop, oven, microwave…) + gas supply source if applicable |
| Audiovisual | Quantities of TVs, computers, other audio equipment |
| Household appliances | Quantities of fridges, freezers, washing machines, dishwashers, dryers, etc. |
| Leisure & comfort | Aquarium, wine cellar, jacuzzi / balneo presence |
| Lighting | Type of lighting: halogen, LED, or mixed |

**Step 5 — Lifestyle**

Collects the occupants' daily habits:

| Field | Description |
| - | - |
| Wash type | Shower, bath, or mixed |
| Shutters at night | Whether shutters are closed at night |
| Weekend absences | Frequency of absences during weekends |
| Summer absences | Number of weeks out of residence during hot periods |
| Winter absences | Number of weeks out of residence during cold periods |

**Profile completion indicator**

A progress indicator is displayed to encourage users to complete all sections.

The completion percentage is computed server-side and reflects the proportion of answered fields.

**Navigation to a specific step via `active-step-section`**

The tenant can open the form directly on a specific step by passing the `active-step-section` attribute. This is especially useful when used alongside `dtn-profile-read` and its `profile-goto` event, enabling a seamless navigation flow between the read view and the edit form.

Valid values: `general` | `housing` | `equipment` | `otherEquipment` | `lifestyle`

If the value is absent or invalid, the form opens on the first step.

**Navigation within the stepper**

Once the form is opened, users can navigate through the different steps using the **Previous** and **Next** buttons.

* **Previous** navigates to the preceding step.
* **Next** validates the current step, saves any valid changes and navigates to the following step.

The form also provides actions to exit the stepper :

* **Save and exit**, available on all steps except the last one.
* **Finish**, available only on the last step.

Both actions save any valid changes made by the user. Once the action has been successfully processed, a `dtn:profile-saved` event is emitted. This event allows the host application to react accordingly, for example by navigating away from the form or redirecting the user after completing the profile journey.

<Note>
  Note: `dtn:profile-saved` is emitted only when users click **Save and exit** or **Finish**. No event is emitted if the save operation fails. Navigating between steps using **Previous** and **Next** does not emit this event.
</Note>

Below is an illustrative example describing how to use this event:

```javascript theme={null}
window.addEventListener('dtn:profile-saved', (event) => {
  const { step, hasBeenModified, totalSteps } = event.detail;
  const isLastStep = step.position === totalSteps

  // Navigate to dtn-profile-read only when the user clicks the Finish button
  // and submits a new version of their profile.
  if (isLastStep && hasBeenModified) {
     document.querySelector('dtn-profile-read').style.display = "block";
  }
});
```

**Hiding heating-related questions**

To support different usage scenarios, the Web Component provides the `disable-heating-fields` input, which allows all heating-related questions to be hidden. When this input is set to `true`, all questions associated with heating are removed from the data entry flow.

***

### Error and information messages handling

The form may display messages in the following cases:

**Use case 1: GET profile API error (400/500)**

An error component is displayed in place of the form, indicating that the profile could not be loaded.

**Use case 2: PUT profile save error (400/500)**

An error toaster notification is displayed at the top of the component, informing the user that their profile could not be saved and inviting them to retry.

**Use case 3: Successful save**

A success toaster notification is displayed:

* Generic success message after saving any step except the last
* Specific completion message after saving the last step (Lifestyle), indicating that the profile entry is complete

**Use case 4: Field-level validation errors**

Inline error messages are displayed **directly beneath the invalid input field** as soon as the field is touched or dirtied by the user. Three variants exist:

| Validator | Message displayed |
| - | - |
| `min` | *La valeur saisie doit être supérieure ou égale à `{min}`* |
| `max` | *La valeur saisie doit être inférieure ou égale à `{max}`* |
| Other / generic | *La valeur saisie est invalide* |

These messages are projected into the Étincelle `<etc-form-field>` slot via `<etc-error>`, so they inherit the design system's error styling (red text below the field).

**Use case 5: Form-level alert above the navigation buttons**

If the user attempts to navigate to the next step while the current step's form group is **invalid**, a **danger alert banner** (`<etc-alert type="danger">`) is displayed above the Next / Finish button with the message:

<Warning>
  *Some entered information is invalid.*
</Warning>

This alert is visible on every step (General, Housing, Equipment, Other equipment, Lifestyle) and disappears as soon as the form group becomes valid.

***

### State handling

#### Loading state handling

When the profile data takes time to load (slow network or API response > 300 ms), a skeleton screen is displayed to:

* Indicate that data is loading
* Preview the stepper layout before content appears

#### Saving state handling

When the user clicks **Save & Exit** or **Finish**, the clicked button displays a **loading indicator** while the profile changes are being saved. All stepper actions are temporarily disabled until the save request completes, preventing duplicate submissions and unintended interactions.

<Note>
  A loading indicator is only displayed for **Save & Exit** and **Finish** actions. Although clicking **Next** also triggers a save operation, it is handled asynchronously while navigating to the next step. It allows the navigation flow to continue seamlessly.
</Note>

***

### Responsiveness

The `dtn-profile` web component is fully responsive.

***

### Provider customization

The component inherits the provider's design system via the Étincelle Design System and supports the following customization:

* **Brand colors** applied via CSS custom properties from the provider's stylesheet
* **Radius overrides** for card and button shapes

For more details, refer to the \['How to parameter a web component' section].

***

### Language management

The web component supports multiple languages.

* `fr-FR`
* `en-US`

***

### Accessibility

The component is developed following the RGAA (French General Accessibility Improvement Framework) requirements and accessibility best practices.

Examples of RGAA accessibility requirements implemented in the `dtn-profile` web component include :

* Each form step is navigable by keyboard
* Form validation errors are announced to screen readers via a screen reader notifier service
* Success and error notifications (save result) are announced to assistive technologies
* The stepper navigation respects focus management when switching steps

<Note>
  The accessibility of this web component does not imply that the entire page where it is integrated is accessible. Accessibility compliance must be assessed at page level, including any surrounding content, custom code, and third-party components provided by the integrating application.
</Note>

***

### API used to display and save profile data

Profile data is provided by the **Profile API**:

* **GET /profile** — fetches the current user profile to pre-fill the form
* **PUT /profile** — saves the profile section after each step validation

***

[Integration of the web component 'Profil completion'](/docs/DeveloperTools/HomeInteface/05-home-basic/03-profil-completion)