RIC-136 — Document "select all" in the candidates list (redesigned toolbar)

• Ticket: RIC-136 — Seleziona tutti nella lista candidati
• Goal (from ticket): Update the guide to the latest UI, explaining how to select all suppliers and contact them.
• Repo: factorybook-user-guide (Docusaurus; docs content in Italian).
• Scope (agreed): Full audit of the "Selezione fornitori" section of docs/acquisti/step.mdx, including the new per-card Aggiungi ai contatti action, plus a consistency check of related FAQ entries. Re-capture the affected screenshots from the running app.

Problem

The candidates-list toolbar was redesigned in the webapp. The current guide prose is stale:

• docs/acquisti/step.mdx (≈ lines 42–46) describes the toolbar as a single row of actions plus a filter row where Con quotazione / Con messaggi are checkboxes and Seleziona tutti is a checkbox on the right.
• The new UI instead has a two-row toolbar: an add/search row, then a select+contact row where select-all is a button, the filters are toggle switches, and Contatta Fornitori sits in the same row. Each candidate card also gained an Aggiungi ai contatti split button.

Ground truth — the redesigned UI (verified from webapp source)

Source: webapp/src/mfb/pages/purchasing/components/QuotationRequestCandidatesList/ (QuotationRequestCandidatesList.tsx, .lang.ts, QuotationCandidateCard.tsx) and webapp/src/mfb/pages/companysite/view/components/AddToContactsButton.tsx.

Row 1 — add suppliers + search

• Aggiungi fornitori (add_private_supplier) — opens a dialog to add specific suppliers (search, or pick from a contact list).
• Importa fornitori (import_suppliers) — bulk import of suppliers.
• Search box (right) — filter candidates by name.
• Ricerca automatica — now a conditional info/alert box with a Ricerca automatica button. It appears only while the request is in SELEZIONE FORNITORI and another automatic search can run (or shows "in progress" / "limit reached" variants). It is no longer a permanent box.

Row 2 — selection + contact (this is the ticket's focus)

• Seleziona tutti i candidati (select_all_candidates) — an outlined button on the left. When every selectable candidate is already selected, the same button flips to Cancella selezione (clear_selection). This is the bulk "select all / clear" control.
  • Available on all plans, including Free (all-or-none bulk selection).
  • The button is disabled outside the candidate-editing states (only enabled in SELEZIONE FORNITORI / ANALISI OFFERTE), and when there is nothing to select.
• Filtra: (filter_label) label followed by two toggle switches: Con quotazione (with-quotation) and Con messaggi (with-messages).
• Contatta Fornitori (confirm-selected) — button on the right; disabled until at least one supplier is selected. Contacts the selected candidates (free of charge; requires a verified company).

Per candidate card

• Selection checkbox (single-supplier selection) — a function of the Base / Premium plans only. On Free / Presenza it is gated and the page shows the alert "Con il tuo piano puoi contattare tutti i fornitori candidati insieme (tutti o nessuno)…" (alert.quotation_request_select_candidates).
• Logo + name + external-link icon, province, contacted date, reason for candidacy, state badges (existing, unchanged).
• Aggiungi ai contatti (AddToContactsButton) — a split button: the main part toggles between Aggiungi ai contatti and Nei contatti; the chevron opens the full contact dialog (contact type Fornitore/Lead/Nessuno, optional referent, notes, add to / create contact lists). This saves the supplier to the user's address book and lists, independently of contacting them for this RFQ.

Design — documentation changes

A. docs/acquisti/step.mdx — section "Selezione fornitori"

Rewrite the toolbar walkthrough (the "Sopra l'elenco si trovano" bullets and the select/contact prose, ≈ lines 42–61) to match the two-row toolbar, keeping the page's existing state-based organization and the StateLabel components.

1. Toolbar description — replace the single-row bullets with the two rows:
   • Row 1: Aggiungi fornitori (add specific suppliers), Importa fornitori (bulk import), the search box, and the conditional Ricerca automatica box (describe it as appearing to launch/repeat the automatic search).
   • Row 2: the Seleziona tutti i candidati / Cancella selezione button, the Filtra: toggles Con quotazione / Con messaggi, and the Contatta Fornitori button.
2. Select + contact prose — explain: choose candidates (bulk via the button, or one-by-one via the card checkbox on Base/Premium), optionally narrow the list with the Filtra: toggles, then press Contatta Fornitori to send the request to the selected suppliers. Keep the note that the selection can be resumed later, and the info admonition that contacting suppliers is free and requires a verified company.
3. "Selezione dei candidati e piani" subsection — keep; its text (bulk = all plans incl. Free; single = Base/Premium; Free alert wording) is verified still accurate. Only adjust wording if the surrounding rewrite requires it (e.g. "checkbox Seleziona tutti" → the button).
4. New short paragraph — Aggiungi ai contatti — each card has an Aggiungi ai contatti button that saves the supplier to your rubrica / contact lists, independently of contacting them for this RFQ; the button reads Nei contatti once saved and its chevron opens the management dialog. Cross-link to Elenco Connessioni and Liste di Contatti — do not re-document the dialog (already covered there).
5. Rest-of-section audit — scan the remaining "Selezione fornitori" prose (e.g. the filters mention around line 83, "Analisi delle offerte") for any other stale "checkbox / a destra" wording and fix in passing.

B. docs/faq.mdx — consistency check

Lines ≈ 106 and 308 already state: bulk Seleziona tutti on all plans, single-supplier selection on Base/Premium. Verify these remain consistent with the rewritten section; adjust only if wording drifted. No screenshot dependency. Likely no change.

Screenshots (re-captured from the running app — Stage 2)

Follow the repo screenshot workflow (demo account [email protected], chrome-devtools MCP, viewport 1423×867 @2x, save to static/img/screenshots/ with kebab-case Italian names, reuse existing filenames so references don't change).

• acquisti-lista-candidati.png (primary) — the full candidates list with the new toolbar and at least one card showing the Aggiungi ai contatti button.
• acquisti-candidati-selezione-free.png — the Free-plan state: select-all button present, per-card checkboxes gated, the plan alert visible.
• acquisti-candidati-stati.png — re-capture only if the redesigned toolbar is visible above the status badges (keep the section visually consistent).

Demo data: an RFQ owned by the demo account in SELEZIONE FORNITORI state with several realistic candidate suppliers (plausible Italian company names, provinces). Reuse the existing per-screen seeder if one already produces this list; otherwise add a new descriptively-named Docs…Seeder in ../factorybook/backend/database/seeders/ (idempotent, calls DemoUserSeeder). Handle the Free-plan screenshot per the pattern already used for the current acquisti-candidati-selezione-free.png.

Out of scope

• Any change to the webapp itself (this is a docs-only ticket).
• Re-documenting the Aggiungi ai contatti dialog internals (already in connessioni/elenco.mdx).
• Restructuring the page away from its RFQ-state organization.

Success criteria

• The "Selezione fornitori" section of step.mdx accurately describes the two-row toolbar, the Seleziona tutti i candidati / Cancella selezione button, the Filtra: toggles, Contatta Fornitori, and the per-card Aggiungi ai contatti (with cross-links).
• Plan-tier rules (bulk = all plans; single = Base/Premium) remain correct and consistent between step.mdx and faq.mdx.
• The affected screenshots show the current UI and their filenames/paths still resolve in the built site.
• No stale "checkbox / Seleziona tutti a destra / filtri come checkbox" wording remains in the section.
• Docusaurus builds without broken links or MDX errors.