@klodd/ds 5.2.7 → 5.4.0

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/css/components/async-progress.css

@@ -0,0 +1,70 @@
+/* ================================================================
+   components/async-progress.css
+
+   Generisk polling-driven progress-UI for asynkrona operationer.
+   Backend-kontrakt: { status, stage, pct, label }.
+
+   Anvands av:
+   - Jubb /jobb/{id} (bolagsanalys + brevgenerering)
+   - Ekonom bank-synk (planerad)
+   - Framtida appar med asynkrona operationer
+
+   Ersatter .brief-progress (Jubb-specifik) som lyftes till
+   generaliserad .async-progress under 5.3.0-sprinten.
+
+   Samma visuella formspraket som .pipeline-progress (6px-bar,
+   0.6s ease-in-out width-transition, sunken-track) men sibling-
+   block i stallet for shared - tydligare BEM-namn per use-case.
+
+   Blocks:
+     .async-progress  - root, dolj med [hidden] vid pending/done/failed
+
+   BEM-element:
+     __header     - flex-row: label vänster, pct hoger
+     __bar-track  - bakgrund-track 6px hojd
+     __bar        - accent-fyllning, width transition
+     __hint       - hint-text under bar (valfri)
+     __label      - inline label-element
+     __pct        - inline pct-element
+
+   Tokens: --surface-sunken, --async-progress-accent (default
+   --accent-9), --text-default, --text-muted, --space-6/-8/-12/-16,
+   --radius-full, --fs-12/-13.
+
+   --async-progress-accent-token tillater app/scope-override av
+   bar-fillfargen utan att forka komponenten. Default = --accent-9
+   (app:s accent via data-app-theming).
+   ================================================================ */
+
+.async-progress {
+  margin: var(--space-12) 0 var(--space-16);
+}
+
+.async-progress__header {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  margin-bottom: var(--space-8);
+  font-size: var(--fs-13);
+  color: var(--text-default);
+}
+
+.async-progress__bar-track {
+  height: 6px;
+  background: var(--surface-sunken);
+  border-radius: var(--radius-full);
+  overflow: hidden;
+}
+
+.async-progress__bar {
+  height: 100%;
+  background: var(--async-progress-accent, var(--accent-9));
+  border-radius: inherit;
+  transition: width 0.6s ease-in-out;
+}
+
+.async-progress__hint {
+  margin: var(--space-6) 0 0;
+  font-size: var(--fs-12);
+  color: var(--text-muted);
+}

package/css/components/progress-bar.css

@@ -1,37 +1,28 @@
 /* ================================================================
    components/progress-bar.css
 
-   Två sibling-blocks for polling-driven progress-UI:
-
    .pipeline-progress  - overst pa /korningar nar DigestRun pagar
-                         (cron-morning/cron-alert/cron-signals)
-   .brief-progress     - pa /jobb/{id} nar bolagsanalys eller
-                         brevgenerering pagar (job_briefs)
+                         (cron-morning/cron-alert/cron-signals i Jubb)
+
+   Visuellt formspraket: 6px-bar, 0.6s ease-in-out width-transition,
+   accent-9-fill, sunken-track.
 
-   Samma visuella formspraket (6px-bar, 0.6s ease-in-out width-transition,
-   accent-9-fill, sunken-track) men separata block-klasser sa de inte krockar
-   med varandra. Olika DOM-id:n och olika underlag (digest_runs vs
-   job_briefs) - hade kunnat slas ihop till en .progress-bar med
-   modifiers, men kept separata for tydligare BEM-block per use-case.
+   Sibling-block .async-progress lever i async-progress.css for
+   generiska asynkrona operationer (Jubb bolagsanalys, Ekonom bank-
+   synk, framtida appar). Bagge delar visuellt språk men har egna
+   block-namn for tydligare BEM-blockning per use-case.
 
    Blocks:
      .pipeline-progress  - root, /korningar
-     .brief-progress     - root, /jobb/{id}
 
-   BEM-element (samma per block):
+   BEM-element:
      __header     - flex-row: label vänster, pct hoger
      __bar-track  - bakgrund-track 6px hojd
      __bar        - accent-fyllning, width transition
-     __sub        - sub-text under bar (.pipeline-progress)
-     __hint       - hint-text under bar (.brief-progress)
+     __sub        - sub-text under bar
      __label      - inline label-element (anvandbart pa /design)
      __pct        - inline pct-element (anvandbart pa /design)
 
-   Lyftad fran jubb.css 2026-05-18 till komponent-mappen sa /design
-   kan ladda bara denna fil utan att dra in hela Jubb-domain-CSS:n
-   (per Calles brief 2026-05-07: ingenting i styleguiden far paverka
-   appens overiga CSS).
-
    Tokens: --surface-sunken, --accent-9, --text-default, --text-muted,
    --space-6/-8/-12/-16, --radius-full, --fs-12/-13.
    ================================================================ */
@@ -72,39 +63,3 @@
   font-size: var(--fs-12);
   color: var(--text-muted);
 }
-
-
-/* ─── .brief-progress (/jobb/{id}) ─────────────────────────────── */
-
-.brief-progress {
-  margin: var(--space-12) 0 var(--space-16);
-}
-
-.brief-progress__header {
-  display: flex;
-  justify-content: space-between;
-  align-items: baseline;
-  margin-bottom: var(--space-8);
-  font-size: var(--fs-13);
-  color: var(--text-default);
-}
-
-.brief-progress__bar-track {
-  height: 6px;
-  background: var(--surface-sunken);
-  border-radius: var(--radius-full);
-  overflow: hidden;
-}
-
-.brief-progress__bar {
-  height: 100%;
-  background: var(--accent-9);
-  border-radius: inherit;
-  transition: width 0.6s ease-in-out;
-}
-
-.brief-progress__hint {
-  margin: var(--space-6) 0 0;
-  font-size: var(--fs-12);
-  color: var(--text-muted);
-}

package/css/index.css

@@ -36,6 +36,7 @@
 @import './components/divider.css';
 @import './components/progress.css';
 @import './components/progress-bar.css';
+@import './components/async-progress.css';
 @import './components/tooltip.css';
 @import './components/dropdown.css';
 

package/js/async-progress.js

@@ -0,0 +1,224 @@
+/* @klodd/ds - AsyncProgress
+ *
+ * Generisk polling-driven progress-controller for asynkrona
+ * operationer. Backend-kontrakt: GET pollUrl → JSON
+ * { status, stage, pct, label }.
+ *
+ * Status-domän:
+ *   pending     - inte startat
+ *   <ev. app>   - app-specifika status under generating
+ *   done        - klart (triggar onComplete)
+ *   failed      - fel (triggar onError efter maxErrors)
+ *
+ * Lyftad fran Jubb's brief-progress.js (sprint 5.3.0). Vet inte
+ * om AI, Claude, banker eller specifika apps - bara om kontraktet.
+ *
+ * Anvandning:
+ *
+ *   const progress = new KloddDS.AsyncProgress({
+ *     progressEl: document.getElementById("my-progress"),
+ *     pollUrl: "/api/foo/123/progress",
+ *     stageLabels: {
+ *       step_a: "Forsta steget...",
+ *       step_b: (data) => data.pct < 50 ? "Forsta..." : "Slutfor...",
+ *     },
+ *     simulation: { triggerStage: "step_b", startPct: 75, cap: 95, ratePerSec: 0.25 },
+ *     onComplete: () => openModal(),
+ *     onError: (msg) => showToast(msg, "error"),
+ *   });
+ *   progress.start();
+ *
+ * Krav pa progressEl (BEM .async-progress):
+ *   - id="..." (en barn-element querySelector via id)
+ *   - innehåller __label, __pct och __bar med data-element-attribut
+ *     ELLER querySelectable via .async-progress__label etc.
+ *   - kan ha [hidden] satt - start() tar bort attributet
+ */
+(function (root) {
+  "use strict";
+
+  const DEFAULTS = {
+    pollInterval: 3000,
+    initialPct: 5,
+    initialLabel: "Startar...",
+    stageLabels: {},
+    simulation: null,
+    onComplete: null,
+    onError: null,
+    maxErrors: 5,
+    doneLabel: "Klar",
+    // transform(data) -> { status, stage, pct, label, ...passthrough }.
+    // Anvands nar backend-payload har app-specifika faltnamn (prefix
+    // 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) {
+        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;
+      this.barEl = this.progressEl.querySelector(".async-progress__bar");
+      this.labelEl = this.progressEl.querySelector(".async-progress__label");
+      this.pctEl = this.progressEl.querySelector(".async-progress__pct");
+
+      this.pollTimer = null;
+      this.consecutiveErrors = 0;
+      this.simulationStart = null;
+      this.lastStage = null;
+      this.completed = false;
+      this.failed = false;
+    }
+
+    start() {
+      this.progressEl.removeAttribute("hidden");
+      this._setBar(this.cfg.initialPct, this.cfg.initialLabel);
+      this.simulationStart = null;
+      this.lastStage = null;
+      this.completed = false;
+      this.failed = false;
+      this.consecutiveErrors = 0;
+      if (this.pollTimer !== null) return;
+      // Forsta poll efter 100ms sa ev. fetch-patches (auth-tokens etc)
+      // hinner appliceras.
+      setTimeout(() => this._poll(), 100);
+      this.pollTimer = setInterval(() => this._poll(), this.cfg.pollInterval);
+    }
+
+    stop() {
+      if (this.pollTimer !== null) {
+        clearInterval(this.pollTimer);
+        this.pollTimer = null;
+      }
+    }
+
+    _setBar(pct, label) {
+      const clampedPct = Math.max(0, Math.min(100, Math.round(pct)));
+      if (this.barEl) this.barEl.style.width = clampedPct + "%";
+      if (this.pctEl) this.pctEl.textContent = clampedPct + "%";
+      if (this.labelEl && label) this.labelEl.textContent = label;
+    }
+
+    _getLabel(data, elapsedSim) {
+      if (data.status === "done") return this.cfg.doneLabel;
+      const stageEntry = this.cfg.stageLabels[data.stage];
+      if (typeof stageEntry === "function") {
+        return stageEntry(data, elapsedSim);
+      }
+      if (typeof stageEntry === "string") {
+        return stageEntry;
+      }
+      // Fallback: backend's label
+      return data.label || this.cfg.initialLabel;
+    }
+
+    _applySimulation(realPct, data) {
+      const sim = this.cfg.simulation;
+      if (!sim || data.stage !== sim.triggerStage) return realPct;
+      if (this.simulationStart == null) return realPct;
+      const elapsedSec = (Date.now() - this.simulationStart) / 1000;
+      const simulated = sim.startPct + elapsedSec * sim.ratePerSec;
+      const capped = Math.min(simulated, sim.cap);
+      return Math.max(realPct, capped);
+    }
+
+    async _poll() {
+      try {
+        // 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();
+        }
+        if (typeof this.cfg.transform === "function") {
+          data = this.cfg.transform(data);
+        }
+        this.consecutiveErrors = 0;
+
+        // Stage-byte: trigga simulation-timer
+        const sim = this.cfg.simulation;
+        if (sim) {
+          if (data.stage === sim.triggerStage && this.lastStage !== sim.triggerStage) {
+            this.simulationStart = Date.now();
+          } else if (data.stage !== sim.triggerStage) {
+            this.simulationStart = null;
+          }
+        }
+        this.lastStage = data.stage;
+
+        // Terminal states
+        if (data.status === "failed") {
+          if (this.failed) return;
+          this.failed = true;
+          this.stop();
+          this.progressEl.setAttribute("hidden", "");
+          if (typeof this.cfg.onError === "function") {
+            this.cfg.onError(data.label || "Operationen misslyckades.");
+          }
+          return;
+        }
+
+        if (data.status === "done") {
+          if (this.completed) return;
+          this.completed = true;
+          this._setBar(100, this.cfg.doneLabel);
+          this.stop();
+          if (typeof this.cfg.onComplete === "function") {
+            this.cfg.onComplete(data);
+          }
+          return;
+        }
+
+        // Pågående: render pct + label
+        const realPct = data.pct || 0;
+        const elapsedSim = this.simulationStart
+          ? Date.now() - this.simulationStart
+          : null;
+        const effectivePct = this._applySimulation(realPct, data);
+        const label = this._getLabel(data, elapsedSim);
+        this._setBar(effectivePct, label);
+      } catch (err) {
+        this._handleFetchError(err.message || String(err));
+      }
+    }
+
+    _handleFetchError(msg) {
+      this.consecutiveErrors += 1;
+      if (this.consecutiveErrors >= this.cfg.maxErrors) {
+        if (this.failed) return;
+        this.failed = true;
+        this.stop();
+        this.progressEl.setAttribute("hidden", "");
+        if (typeof this.cfg.onError === "function") {
+          this.cfg.onError(`Polling-fel efter ${this.cfg.maxErrors} forsok: ${msg}`);
+        }
+      }
+    }
+  }
+
+  // Exponera pa KloddDS-namespace. Skapa objektet om det inte finns
+  // (defensiv mot oklar laddningsordning - om async-progress.js laddas
+  // fore index.js).
+  root.KloddDS = root.KloddDS || {};
+  root.KloddDS.AsyncProgress = AsyncProgress;
+})(typeof window !== "undefined" ? window : globalThis);

package/package.json

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

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".