@arbetsformedlingen/yrkesvaljaren 2.0.11 → 2.1.0

package/README.md

@@ -7,59 +7,47 @@ En robust och intelligent sökkomponent för svenska yrken, designad för hög p
 
 ### Beskrivning
 
-*   **Enkelt hitta rätt yrke för användaren** <br>Sökalgoritmen prioriterar exakta träffar, prefix, flerdelade direktträffar och innehåller-träffar. Om inga direktträffar finns kan upp till tre fuzzy-träffar visas. Viktdata används som sekundär sortering.
+*   **Enkelt hitta rätt yrke för användaren** <br>Sökalgoritmen prioriterar exakta träffar, prefix, flerdelade direktträffar och innehåller-träffar. Om inga direktträffar finns kan fuzzy-träffar visas: upp till fem när en av dem tydligt matchar roten i sökordet, annars upp till tre. Viktdata används som sekundär sortering.
 *   **Hög prestanda:** <br>Sökningen sker lokalt i webbläsaren mot inläst yrkesdata. Komponenten gör inga sökanrop till Taxonomy API.
-*   **Flexibel datahantering:** <br>Välj mellan automatiskt uppdaterad data, ett versionerat npm-datapaket eller en egen URL.
+*   **Flexibel datahantering:** <br>Versionerat npm-datapaket (rekommenderas), automatiskt uppdaterad data eller en egen URL.
 
 ---
 
 ### Installation
 
-Yrkesväljaren installeras enkelt via npm:
+Installera komponenten och datapaketet:
 
 ```bash
-npm install @arbetsformedlingen/yrkesvaljaren
+npm install @arbetsformedlingen/yrkesvaljaren @arbetsformedlingen/yrkesvaljaren-data@31
 ```
 
-När ingen datakälla anges hämtar komponenten automatiskt den senaste publicerade yrkesdatan från CDN.
+Datapaketets majorversion är taxonomiversionen: `31.x.y` innehåller taxonomi v31. Med `^31.0.0` i `package.json` får du rättningar av v31-datan men byter aldrig taxonomiversion av misstag. Installera nästa majorversion när du vill byta taxonomiversion.
 
-#### Alternativ: installera ett versionerat datapaket
+Datan registreras med `registerTaxonomy(...)` innan komponenten används. Se [Angular](#användning-i-angular) eller [HTML och andra ramverk](#användning-i-html-och-andra-ramverk).
 
-Om du vill låsa taxonomiversionen vid build time installerar du även ett versionerat datapaket:
-
-```bash
-npm install @arbetsformedlingen/yrkesvaljaren @taxonomy/yrkesvaljaren-data-v31
-```
-
-Registrera paketets data i din applikation innan komponenten används:
-
-```javascript
-import { registerTaxonomy } from '@arbetsformedlingen/yrkesvaljaren';
-import {
-  taxonomyData,
-  metadata
-} from '@taxonomy/yrkesvaljaren-data-v31';
-
-registerTaxonomy({ data: taxonomyData, metadata });
-```
-
-`af-taxonomy-url` är ett tredje, avancerat alternativ om du vill peka komponenten mot en egenhostad datafil.
+Utan registrerad data hämtar komponenten den senaste publicerade yrkesdatan från CDN. `af-taxonomy-url` är ett avancerat alternativ om du vill peka komponenten mot en egenhostad datafil.
 
 ### Användning i Angular
 
 De flesta som använder Yrkesväljaren bygger i Angular. Komponenten är en vanlig webbkomponent, så den fungerar i standalone-komponenter med eller utan zone.js.
 
-Registrera webbkomponenterna i `main.ts` innan appen startar:
+Registrera datan och webbkomponenterna i `main.ts` innan appen startar. Taxonomidatan är cirka 2 MB. Importera den dynamiskt, så hamnar den i en egen chunk. Med en statisk import hamnar den i main-bundlen och `ng build` fastnar på Angulars standardbudget (1 MB).
 
 ```ts
 // src/main.ts
 import { bootstrapApplication } from '@angular/platform-browser';
 import { defineCustomElements as defineYv } from '@arbetsformedlingen/yrkesvaljaren/loader';
+import { registerTaxonomy } from '@arbetsformedlingen/yrkesvaljaren';
 import { appConfig } from './app/app.config';
 import { App } from './app/app';
 
-defineYv(window);
-bootstrapApplication(App, appConfig).catch((err) => console.error(err));
+async function main() {
+  const { metadata, taxonomyData } = await import('@arbetsformedlingen/yrkesvaljaren-data');
+  registerTaxonomy({ data: taxonomyData, metadata });
+  defineYv(window);
+  await bootstrapApplication(App, appConfig);
+}
+main().catch((err) => console.error(err));
 ```
 
 Använd sedan komponenten i en standalone-komponent med `CUSTOM_ELEMENTS_SCHEMA` och lyssna på eventet i templaten:
@@ -89,29 +77,10 @@ export class JobPickerComponent {
 
 Uppdatera vyn via signals (eller `ChangeDetectorRef`) när ni sätter värden efter en `await`. Annars uppdateras inte vyn i zoneless-appar.
 
-**Låst dataversion i Angular:** taxonomidatan i `@taxonomy/yrkesvaljaren-data-v31` är cirka 2 MB. Importera den dynamiskt i `main.ts`, så hamnar den i en egen chunk. Med en statisk import hamnar den i main-bundlen och `ng build` fastnar på Angulars standardbudget (1 MB).
-
-```ts
-// src/main.ts
-import { bootstrapApplication } from '@angular/platform-browser';
-import { defineCustomElements as defineYv } from '@arbetsformedlingen/yrkesvaljaren/loader';
-import { registerTaxonomy } from '@arbetsformedlingen/yrkesvaljaren';
-import { appConfig } from './app/app.config';
-import { App } from './app/app';
-
-async function main() {
-  const { metadata, taxonomyData } = await import('@taxonomy/yrkesvaljaren-data-v31');
-  registerTaxonomy({ data: taxonomyData, metadata });
-  defineYv(window);
-  await bootstrapApplication(App, appConfig);
-}
-main().catch((err) => console.error(err));
-```
-
 Kompletta exempel:
 
-- [`examples/angular-wizard`](examples/angular-wizard): Yrkesväljaren i Reactive Forms via `ControlValueAccessor`.
-- [`examples/angular-multi-occupation-skills`](examples/angular-multi-occupation-skills): flera yrken med egna kompetensval via Kompetensväljarens headless-API.
+- [`examples/angular-wizard`](https://gitlab.com/arbetsformedlingen/taxonomy-dev/frontend/yrkesvaljaren/-/tree/main/examples/angular-wizard): Yrkesväljaren i Reactive Forms via `ControlValueAccessor`.
+- [`examples/angular-multi-occupation-skills`](https://gitlab.com/arbetsformedlingen/taxonomy-dev/frontend/yrkesvaljaren/-/tree/main/examples/angular-multi-occupation-skills): flera yrken med egna kompetensval via Kompetensväljarens headless-API.
 
 ### Användning i HTML och andra ramverk
 
@@ -146,6 +115,15 @@ console.log("Valt yrke:", e.detail);
 </html>
 ```
 
+**Utan Angular:** registrera datapaketets data innan komponenten används:
+
+```javascript
+import { registerTaxonomy } from '@arbetsformedlingen/yrkesvaljaren';
+import { taxonomyData, metadata } from '@arbetsformedlingen/yrkesvaljaren-data';
+
+registerTaxonomy({ data: taxonomyData, metadata });
+```
+
 **React:** koppla komponentens event med `addEventListener` via en `ref` i en `useEffect`. Det fungerar i alla React-versioner; en `onAfJobSelected`-prop fungerar inte i React 18.
 
 ### Vite
@@ -169,20 +147,21 @@ Yrkesväljaren är uppbyggd med designsystemets tokens, typografi, färger, foku
 
 ### Attribut
 
-| Attribut | Beskrivning | Typ | Standardvärde |
-|:---|:---|:---|:---|
-| `af-label` | Etikettext som visas ovanför sökfältet. | `string` | `'Välj yrke'` |
-| `disabled` | Om satt till `true`, kan väljaren inte användas med mus eller tangentbord. | `boolean` | `false` |
-| `af-label-description`| En valfri beskrivningstext som visas under etiketten. | `string` | `undefined` |
-| `af-placeholder` | Hjälptext som visas inuti sökfältet. Denna är ett bra stöd för de med kognitiv funktionsvariation - vi rekommenderar att behålla denna text (den är osynlig för skärmläsare). | `string` | `'T.ex. målare, florist, kock'` |
-| `af-error-message` | Ett anpassat felmeddelande som visas vid valideringsfel. | `string` | `undefined` |
-| `af-enable-multiple` | Om satt till `true`, tillåts val av flera yrken. | `boolean` | `false` |
-| `af-history` | Sparar användarval lokalt i webbläsarens Local Storage och visar historiken på samma domän. | `boolean` | `true` |
-| `af-required` | Om satt till `true`, måste användaren göra ett val för att fältet ska vara giltigt (obligatoriskt fält). | `boolean` | `false` |
-| `af-manual-input` | Om satt till `true`, tillåts användaren att ange ett yrke fritt via fritext som inte finns i listan. Om satt till `false` måste ett fördefinierat yrke väljas. | `boolean` | `false` |
-| `af-size` | Storleken på inputfältet. Möjliga värden: `'small'`, `'medium'`, `'large'`. | `string` | `'medium'` |
-| `af-popular` | Om satt till `true`, visas sektionen "Populära sökningar" när historiken är tom. | `boolean` | `true` |
-| `af-taxonomy-url` | Fullständig, explicit URL till en egenhostad datafil. Utelämna attributet för att använda senaste data automatiskt. | `string` | `undefined` |
+| Attribut | Property | Beskrivning | Typ | Förvalt |
+| --- | --- | --- | --- | --- |
+| `af-label` | `label` | Etikettext som visas ovanför sökfältet. | `string` | `'Välj yrke'` |
+| `disabled` | `disabled` | Om satt till `true`, kan väljaren inte användas med mus eller tangentbord. | `boolean` | `false` |
+| `af-label-description` | `labelDescription` | En valfri beskrivningstext som visas under etiketten. | `string` | `undefined` |
+| `af-placeholder` | `placeholder` | Hjälptext som visas inuti sökfältet. Denna är ett bra stöd för de med kognitiv funktionsvariation - vi rekommenderar att behålla denna text (den är osynlig för skärmläsare). | `string` | `'T.ex. målare, florist, kock'` |
+| `af-error-message` | `errorMessage` | Ett anpassat felmeddelande som visas vid valideringsfel. | `string` | `undefined` |
+| `af-enable-multiple` | `enableMultiple` | Om satt till `true`, tillåts val av flera yrken. | `boolean` | `false` |
+| `af-history` | `history` | Sparar användarval lokalt i webbläsarens Local Storage och visar historiken på samma domän. | `boolean` | `true` |
+| `af-required` | `required` | Om satt till `true`, måste användaren göra ett val för att fältet ska vara giltigt (obligatoriskt fält). | `boolean` | `false` |
+| `af-manual-input` | `manualInput` | Om satt till `true` kan användaren ange ett yrke som fritext när det inte finns i listan. | `boolean` | `false` |
+| `af-feedback` | `feedback` | Om satt till `true` kan användaren föreslå ett saknat yrke med en frivillig motivering. Förslaget skickas till Arbetsförmedlingen, se [Förslag och Piwik PRO](#förslag-och-piwik-pro). | `boolean` | `false` |
+| `af-size` | `size` | Storleken på inputfältet. Möjliga värden: `'small'`, `'medium'`, `'large'`. | `string` | `'medium'` |
+| `af-popular` | `popular` | Om satt till `true` visas sektionen "Populära sökningar" när historiken är tom. | `boolean` | `true` |
+| `af-taxonomy-url` | `taxonomyUrl` | Fullständig, explicit URL till en egenhostad datafil. Utelämna attributet för att använda senaste data automatiskt. | `string` | `undefined` |
 
 ### Riktlinjer och rekommendationer
 
@@ -190,19 +169,19 @@ Tre centrala inställningar styr användarupplevelsen och datakvaliteten i Yrkes
 
 #### Obligatorisk (`af-required`)
 * **Hur man kan resonera:** När `af-required="true"` måste användaren välja minst ett yrke för att fältet ska betraktas som giltigt. Komponenten fungerar som ett standardenligt *Form-Associated Custom Element* (FACE). Det innebär att webbläsaren automatiskt validerar fältet vid formulärinskick, förhindrar att formuläret skickas in om det är tomt, och integrerar med formulärets `validity`-status.
-* **När det rekommenderas:** I formulär och flöden där ett yrkesval är ett obligatoriskt steg i ett ärende (t.ex. inskriving, aktivtitetsrapportering).
+* **När det rekommenderas:** I formulär och flöden där ett yrkesval är ett obligatoriskt steg i ett ärende (t.ex. inskrivning och aktivitetsrapportering).
 * **När det bör undvikas:** I öppna sök- eller filtreringsvyer där användaren ska kunna söka brett, filtrera på andra parametrar (t.ex. enbart ort/geografi) eller frivilligt specificera yrke.
 
-#### Tillåt fritext (`af-manual-input`)
-* **Hur man kan resonera:** Avgör om användaren strikt måste välja ett strukturerat yrkesbegrepp ur Arbetsförmedlingens taxonomi (vilket garanterar Concept ID och SSYK-kod), eller om användaren även tillåts mata in egna fritextvärden som inte finns i taxonomin. Vid fritext visas valet *"Använd '{inmatning}'"* i listan som användaren aktivt väljer eller bekräftar med Enter.
-* **När det rekommenderas:**
-  * **Strikt taxonomi (`af-manual-input="false"` – standard & rekommenderas):** När yrkesdatan ska användas för automatisk matchning, statistiska analyser, maskininlärning eller integration mot backend-system som förutsätter Concept ID. Detta säkerställer hög datakvalitet.
-  * **Fritext tillåten (`af-manual-input="true"`):** I öppna fritextprofiler, fritextenkäter eller intresseanmälningar där det är viktigare att fånga upp vad användaren själv kallar sin roll än att få ett taxonomi-ID, eller där man inte vill blockera användare med ovanliga, nischade eller internationella titlar.
+#### Förslag på saknade yrken (`af-feedback`) och fritext (`af-manual-input`)
+* **Hur man kan resonera:** 
+  * **Förslag till Arbetsförmedlingen (`af-feedback="true"`, av som standard):** Komponenten ger användaren möjlighet att föreslå saknade yrken med en frivillig motivering. Förslaget skickas som eventet `afOnSubmitJobSuggestion`. Det når Arbetsförmedlingen bara när Arbetsförmedlingens Piwik PRO-skript finns på sidan. Du behöver ingen egen backend för detta. Vi rekommenderar att du slår på `af-feedback`, eftersom förslagen hjälper Arbetsförmedlingens taxonomiredaktion att fånga upp nya och saknade yrken.
+  * **Strikt taxonomi (`af-manual-input="false"` – standard & rekommenderas):** När yrkesdatan ska användas för automatisk matchning, statistiska analyser eller integration mot backend-system som förutsätter Concept ID. Om `af-feedback="true"` kan användaren skicka in sitt förslag men måste därefter välja ett befintligt yrke ur listan.
+  * **Fritext tillåten (`af-manual-input="true"`):** I öppna fritextprofiler, fritextenkäter eller intresseanmälningar där det är viktigare att fånga upp vad användaren själv kallar sin roll än att få ett taxonomi-ID.
 
 #### Tillåt historik (`af-history`)
-* **Hur man kan resonera:** Sparar gjorda val i webbläsarens localStorage per domän och enhet, och visar dem som "Tidigare val" när användaren fokuserar Yrkesväljaren. Det betyder att historiken kommer att visas på alla tjänster med yrkesväljare på arbetsformedlingen.se (så länge personen använder samma enhet, t.ex sin mobil).
+* **Hur man kan resonera:** Sparar gjorda val i webbläsarens localStorage per domän och enhet, och visar dem som "Tidigare val" när användaren fokuserar Yrkesväljaren. Det betyder att historiken kommer att visas på alla tjänster med yrkesväljare på arbetsformedlingen.se (så länge personen använder samma enhet, t.ex. sin mobil).
 * **När det rekommenderas:** På alla tjänster mot konsumenter.
-* **När det bör undvikas:** På delade publika terminaler eller kioskdatorer (t.ex. på Arbetsförmedlingens servicekontor) där personers tidigare sökningar inte ska sparas eller exponeras för efterföljande besökare på samma dator. Kanske är det inget hjälpsamt stöd för tjänster för Handläggare eftersom de söker måååånga olika yrken.
+* **När det bör undvikas:** På delade publika terminaler eller kioskdatorer (t.ex. på Arbetsförmedlingens servicekontor) där personers tidigare sökningar inte ska sparas eller exponeras för efterföljande besökare på samma dator. I handläggartjänster är historiken sällan till hjälp, eftersom handläggare söker på många olika yrken.
 
 ### Välj datakälla
 
@@ -214,8 +193,12 @@ Välj ett av följande sätt:
 
 En angiven `af-taxonomy-url` är den valda datakällan. Om URL:en inte kan laddas
 går komponenten till felläge och skickar `afJobDataLoadFailed`.
-<br>
 
+Från `1.1.0` (`@taxonomy/yrkesvaljaren-data-vNN`) respektive `NN.1.0` (`@arbetsformedlingen/yrkesvaljaren-data`)
+har varje post i datapaketets `taxonomyData` både `ssyk_level_4_id` (SSYK nivå 4 som concept-id) och
+`ssyk_code_2012` (den fyrsiffriga SSYK 2012-koden). Hela posttypen finns i paketets `index.d.ts`.
+Fälten är till för värdappar som läser datat direkt. Av de två fälten finns bara `ssyk_code_2012` i komponentens output.
+<br>
 ### Events
 
 | Händelse | Beskrivning |
@@ -223,6 +206,18 @@ går komponenten till felläge och skickar `afJobDataLoadFailed`.
 | `afJobSelected` | Skickas ut när användaren ändrar valet. `event.detail` innehåller `JobSelectionItem[]` som kan skickas tillbaka till `setSelection()`. |
 | `afJobDataLoadFailed` | Skickas när laddningen av yrkesdata misslyckas. |
 | `afJobValidationChange` | Skickas när komponenten kör validering efter att fältet har berörts. `event.detail` innehåller `{ isValid: boolean, errorType: 'required'|'invalidInput'|null }`. |
+| `afOnSubmitJobSuggestion` | Skickas när användaren skickar in ett förslag på saknat yrke till Arbetsförmedlingen. `event.detail` innehåller `{ selectedJobs: JobSelectionItem[], suggestionJob: string, suggestionMotivation: string }`. |
+
+### Förslag och Piwik PRO
+
+Förslag skickas automatiskt till Arbetsförmedlingens Piwik PRO när sidan har AF:s
+Piwik PRO-skript. Containern lyssnar på `afOnSubmitJobSuggestion` och registrerar förslaget som
+"AS - Designsystem - Yrkesväljaren - Inskickat förslag". Integratören behöver inte göra något,
+och sidor utan skriptet påverkas inte.
+
+Förslag och motivering kontrolleras mot vanliga personuppgifter, till exempel personnummer,
+e-post, telefonnummer, adresser, kontonummer och webbadresser. Vid träff skickas ingenting och
+användaren får rätta texten. Kontrollen minskar risken men garanterar inte att texten är anonym.
 
 ### Metoder
 
@@ -235,7 +230,7 @@ dataladdning.
 
 | Metod | Returvärde | Beskrivning |
 |:---|:---|:---|
-| `setSelection(input)` | `Promise<JobSelectionItem[]>` | Sätter eller rensar ett programmatiskt val. Returnerar komponentens normaliserade selection. |
+| `setSelection(input)` | `Promise<JobSelectionItem[]>` | Sätter eller rensar ett programmatiskt val. Returnerar komponentens normaliserade val. |
 | `setFocus()` | `Promise<void>` | Flyttar fokus till sökfältet. Används när värdappen till exempel öppnar en modal eller vill fokusera fältet efter ett fel. |
 
 #### Formulärvalidering
@@ -363,7 +358,7 @@ För att göra fältet obligatoriskt, använd `af-required`-attributet och stäl
 ></digi-service-job-selector>
 ```
 
-När detta är inställt kommer komponenten att visa ett felmeddelande om användaren klickar i och sedan lämnar fältet utan att göra ett giltigt val. Om `af-manual-input` istället är satt till `true` tillåts användaren att ange ett yrke manuellt via fritext.
+När detta är inställt kommer komponenten att visa ett felmeddelande om användaren klickar i och sedan lämnar fältet utan att göra ett giltigt val. Om `af-manual-input` i stället är satt till `true` tillåts användaren att ange ett yrke manuellt via fritext.
 <br>
 #### Lyssna på valideringsstatus (`afJobValidationChange`)
 

package/dist/cjs/{af-validation-message-Cy89nVEv.js → af-validation-message-BdR9X_qh.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-hZgOvC17.js');
+var index = require('./index-DMQDFAL7.js');
 
 const AfValidationMessage = (props, children) => {
     const extraClass = props.class || '';