@klodd/ds 5.3.0 → 5.4.1

package/SKILL.md

@@ -42,6 +42,65 @@ Denna Skill fångar både reglerna ("vad") och resonemanget ("varför").
 - `references/04-locked-decisions/` — låsta beslut. Förklara, ändra inte.
 - `references/05-open-decisions/` — öppna punkter. Presentera alternativen.
 
+## Asynkrona operationer
+
+Apps med polling-driven progress (AI-analys, bank-synk, batch-jobs)
+delar `KloddDS.AsyncProgress` (5.3.0+).
+
+**CSS-komponent**: `.async-progress` (i `css/components/async-progress.css`).
+BEM-element: `__header`, `__bar-track`, `__bar`, `__hint`, `__label`,
+`__pct`. Döljs via `[hidden]`-attributet i alla states utom under
+pågående polling. Bar-fyll via `--async-progress-accent`-token
+(default `--accent-9`) — app/scope kan override:a utan att forka.
+
+**JS-klass**: `window.KloddDS.AsyncProgress` (i `js/async-progress.js`).
+Konfigurerbar via konstruktor-objekt:
+
+```javascript
+const progress = new KloddDS.AsyncProgress({
+  progressEl: HTMLElement,    // .async-progress-elementet
+  pollUrl: String,            // GET-endpoint som returnerar JSON-kontrakt
+  pollInterval: 3000,         // ms (default)
+  initialPct: 5,
+  initialLabel: "Startar...",
+  stageLabels: {              // map: stage → string ELLER function(data, elapsedMs)
+    fetching: "Hämtar data...",
+    processing: (data, elapsedMs) =>
+      elapsedMs > 15000 ? "Slutför..." : "Bearbetar..."
+  },
+  simulation: {               // valfri smooth-progress när backend pinnar pct
+    triggerStage: "processing",
+    startPct: 75, cap: 95,
+    ratePerSec: 0.25
+  },
+  transform: (data) => ({...}),  // valfri: normalisera app-specifik payload
+  onComplete: (data) => {},
+  onError: (msg) => {},
+  maxErrors: 5,
+  doneLabel: "Klar"
+});
+progress.start();   // visar progressEl + startar polling
+progress.stop();    // stoppar interval (terminal states gör det automatiskt)
+```
+
+**Backend-kontrakt**: `pollUrl` ska returnera JSON med
+`{ status, stage, pct, label }`. Status-domän:
+
+- `pending` — inte startad
+- `done` — klar (triggar onComplete)
+- `failed` — fel (triggar onError efter maxErrors)
+- Anything else (app-definierad) — pågående; app kontrollerar stage-labels
+
+Apps vars endpoint redan returnerar exakt kontraktet behöver inte
+`transform`-callbacken. Apps med prefix-payload (t.ex. Jubb's
+`analysis_*`/`application_*`-fält i samma endpoint) använder
+`transform` för att normalisera klient-sidigt — undviker fult
+fetch-patch-mönster.
+
+**Använd när**: en operation tar >2s och användaren ska se att den
+händer. Apps idag: Jubb bolagsanalys + brevgenerering (5.3.0
+migration). Ekonom bank-synk har endpoint, UI kommer i nästa sprint.
+
 ## Komponent-val
 1. Kolla `references/02-components.md` för befintlig komponent
 2. Föredra komposition över fork

package/js/async-progress.js

@@ -52,12 +52,21 @@
     // som analysis_*/application_*) och behover normaliseras till
     // kontraktet. Default = identity.
     transform: null,
+    // fetchFn() -> Promise<{ status, stage, pct, label, ... }>.
+    // Overskriver intern fetch(pollUrl). Anvands av demo-sidor (mock-
+    // poller utan riktigt endpoint) och tester (deterministisk
+    // injection utan global fetch-patch). Per ADR 0016. Default
+    // = null -> intern fetch.
+    fetchFn: null,
   };
 
   class AsyncProgress {
     constructor(config) {
-      if (!config || !config.progressEl || !config.pollUrl) {
-        throw new Error("AsyncProgress: progressEl + pollUrl är obligatoriska");
+      if (!config || !config.progressEl) {
+        throw new Error("AsyncProgress: progressEl ar obligatorisk");
+      }
+      if (!config.pollUrl && !config.fetchFn) {
+        throw new Error("AsyncProgress: pollUrl eller fetchFn maste anges");
       }
       this.cfg = Object.assign({}, DEFAULTS, config);
       this.progressEl = this.cfg.progressEl;
@@ -127,12 +136,20 @@
 
     async _poll() {
       try {
-        const res = await fetch(this.cfg.pollUrl);
-        if (!res.ok) {
-          this._handleFetchError(`HTTP ${res.status}`);
-          return;
+        // fetchFn overskriver intern fetch (ADR 0016). Konsumenten
+        // ansvarar for HTTP-errors -> rejicera promise. Intern fetch
+        // mappar !res.ok till _handleFetchError som vanligt.
+        let data;
+        if (typeof this.cfg.fetchFn === "function") {
+          data = await this.cfg.fetchFn();
+        } else {
+          const res = await fetch(this.cfg.pollUrl);
+          if (!res.ok) {
+            this._handleFetchError(`HTTP ${res.status}`);
+            return;
+          }
+          data = await res.json();
         }
-        let data = await res.json();
         if (typeof this.cfg.transform === "function") {
           data = this.cfg.transform(data);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klodd/ds",
-  "version": "5.3.0",
+  "version": "5.4.1",
   "description": "Klodd shared design system - tokens, components, JS",
   "main": "css/index.css",
   "bin": {

package/references/02-components.md

@@ -71,6 +71,57 @@ För varje entry gäller:
 - **Anvand:** Native `<dialog>` (centrerad modal) eller `<dialog class="sheet">` (bottom-attached)
 - **INTE:** Tooltip eller dropdown (egna komponenter)
 - **Tokens:** `--surface-raised/-overlay`, `--border-subtle`, `--shadow-float`, `--z-overlay`, `--safe-bottom`
+- **Centrering:** `dialog.dialog:modal`-regeln (5.2.5) override:ar UA-stylesheet
+  med `!important` pa position/inset/margin/transform. Doumenterat undantag fran
+  kvalitetsbar regel 7 - UA's `dialog:modal` har implicit prioritering bortom
+  standard specificity-cascading.
+
+#### Completion-dialog (async-operation done)
+
+Vanlig instans: visa "X ar klart" + primar-action efter att en
+asynkron operation (AsyncProgress) slagit `done`. Anvands av Jubb's
+bolagsanalys + brevgenerering, och planerat for Ekonom bank-synk.
+
+```html
+<dialog class="dialog" id="my-complete-dialog">
+  <div class="dialog__header">
+    <h2 class="heading-3">Operationen ar klar</h2>
+  </div>
+  <div class="dialog__body">
+    <p>Beskrivande text + ev. CTA-kontext.</p>
+  </div>
+  <div class="dialog__footer">
+    <button class="btn btn--primary" id="view-btn">Visa resultat</button>
+  </div>
+</dialog>
+```
+
+JS-monster:
+
+```javascript
+const dlg = document.getElementById("my-complete-dialog");
+
+// Oppna via showModal() - native focus-trap + ESC + ::backdrop
+dlg.showModal();
+
+// Stang via backdrop-klick (event.target == dialog-elementet)
+dlg.addEventListener("click", (e) => {
+  if (e.target === dlg) dlg.close();
+});
+
+// Primar action - app-specifik (oftast navigation + reload)
+document.getElementById("view-btn").addEventListener("click", () => {
+  window.location.href = "/result#anchor";
+  window.location.reload();
+});
+```
+
+Footer-varianter:
+- En primar knapp (Visa resultat / Bekrafta) - default
+- Sekundar + primar (Avbryt + Bekrafta) - destruktiva eller reversibla actions
+- `.btn--danger` som primar - actions som tar bort/forstor data
+
+Se /design-sidan "Completion Dialog"-sektionen for visuella exempel.
 
 ### icon (`icon.css`)
 - **Blocks:** `.icon`, `.icon-custom` (sibling - wrapper for handritade SVG som Lucide saknar)

package/references/04-locked-decisions/0016-async-progress-fetch-fn.md

@@ -0,0 +1,112 @@
+# 0016 - AsyncProgress fetchFn-option
+
+## Status
+
+Locked (2026-05-19).
+
+## Context
+
+`KloddDS.AsyncProgress` (introducerad 5.3.0) använder intern `fetch()`
+mot `pollUrl` för att hämta progress-payload. Konstruktor-validering
+kastar fel om `pollUrl` saknas. Det fungerar för app-konsumenter
+(Jubb's bolagsanalys, Ekonom's bank-synk) men blockerar två scenarier:
+
+1. **Demo-sidor (`/design` i Jubb)**: ingen riktig polling-endpoint
+   existerar. För att demonstrera komponenten visuellt har vi tidigare
+   tvingats köra parallell setTimeout-driven simulering vid sidan av
+   AsyncProgress-klassen - dupplicerar logik och visar inte hur
+   konsumenten faktiskt använder klassen.
+
+2. **Enhetstester**: tester måste idag mocka `window.fetch` globalt
+   eller köra ett riktigt test-endpoint för att verifiera
+   stage-byten, simulation-curve, done/failed-callbacks etc.
+   fetch-monkey-patch är fult och påverkar andra tester i samma
+   suite.
+
+Båda problemen löser sig genom en opt-in `fetchFn`-option som
+överskuggar den interna fetch-mekanismen.
+
+## Decision
+
+Lägg till `fetchFn`-option på AsyncProgress-konstruktor:
+
+```javascript
+new KloddDS.AsyncProgress({
+  // Ny option:
+  fetchFn: null,    // default: använd intern fetch(pollUrl)
+
+  // Existerande:
+  progressEl, pollUrl, pollInterval, ...
+})
+```
+
+**Signatur**: `fetchFn: () => Promise<PollPayload>` där
+`PollPayload = { status, stage, pct, label, ...passthrough }`
+(samma kontrakt som backend-endpoint).
+
+**Använding i poll-loopen**:
+
+```javascript
+const data = this._options.fetchFn
+  ? await this._options.fetchFn()
+  : await fetch(this._options.pollUrl).then(r => r.json());
+```
+
+**Validering**: konstruktor kastar fel om **både** `pollUrl` och
+`fetchFn` saknas. Tidigare räckte det med pollUrl - nu accepteras
+endera.
+
+## Consequences
+
+**Positiva**:
+- Design-sidan kan använda den faktiska AsyncProgress-komponenten
+  med mock-poller istället för parallell setTimeout-simulering. En
+  källa till sanning för komponentens beteende.
+- Enhetstester kan injicera deterministisk mock-poller utan att
+  monkey-patcha global `fetch`.
+- API-tillägget är opt-in: existerande konsumenter (Jubb's
+  brief-progress.js wrapper, framtida Ekonom bank-synk UI) påverkas
+  inte - de fortsätter använda `pollUrl` och får default-beteende.
+
+**Negativa**:
+- Publik API-utökning kräver minor-bump (5.3.0 → 5.4.0).
+- Två kodvägar i poll-loopen (intern fetch vs fetchFn) - liten
+  komplexitetsökning. Defensiv if-branch.
+
+## Implementation notes
+
+- `transform`-callbacken (introducerad 5.3.0) appliceras på resultatet
+  oavsett om data kommer från fetchFn eller intern fetch. Konsekvens:
+  apps kan kombinera fetchFn (mock) + transform (normalize app-payload)
+  i samma instans.
+- Vid HTTP-fel via `fetchFn` ansvarar konsumenten för att kasta
+  Error/rejicera promise. AsyncProgress räknar konsekutiva
+  fel mot `maxErrors` som vanligt.
+
+## Användning
+
+```javascript
+function createMockPoller(steps) {
+  let i = 0;
+  return () => Promise.resolve(
+    i < steps.length
+      ? steps[i++]
+      : { status: "done", stage: null, pct: 100, label: "Klar" }
+  );
+}
+
+new KloddDS.AsyncProgress({
+  progressEl: document.getElementById("demo-progress"),
+  fetchFn: createMockPoller([
+    { status: "generating", stage: null, pct: 25, label: "Steg 1..." },
+    { status: "generating", stage: null, pct: 50, label: "Steg 2..." },
+    { status: "generating", stage: null, pct: 75, label: "Steg 3..." },
+    { status: "done", stage: null, pct: 100, label: "Klar" },
+  ]),
+  pollInterval: 1500,
+  onComplete: () => console.log("done!"),
+});
+```
+
+Skapad ihop med deploy 5.4.0 (2026-05-19). Diskussion i sprint
+"async-progress-fetch-fn-deploy".