@emdzej/bimmerz-ui 0.1.0 → 0.2.0

package/README.md

@@ -1,11 +1,13 @@
 # @emdzej/bimmerz-ui
 
-Shared **Svelte 5** components for the bimmerz app family. Source-only —
-consumer apps' Vite + svelte-plugin compiles them. No pre-compiled output.
+Shared **Svelte 5** components + lifecycle hooks for the bimmerz app
+family (dashx, ediabasx, inpax, ncsx, …). Source-only — consumer
+apps' Vite + svelte-plugin compiles them. No pre-compiled output.
 
 ## Convention: source-only Svelte libs
 
-Svelte components ship as `.svelte` files, not pre-compiled JS. The
+Svelte components ship as `.svelte` files, rune helpers as
+`.svelte.ts` — both compiled by the consumer's Svelte plugin. The
 `package.json` carries:
 
 ```json
@@ -22,18 +24,19 @@ Svelte components ship as `.svelte` files, not pre-compiled JS. The
 }
 ```
 
-The `svelte` export condition is what the consumer's Vite plugin reads to
-locate the source. The `types` condition lets `svelte-check` resolve them
-the same way without an explicit `.d.ts` step.
+The `svelte` export condition is what the consumer's Vite plugin
+reads to locate the source. The `types` condition lets
+`svelte-check` resolve them the same way without an explicit
+`.d.ts` step.
 
-**Why:** Svelte 5's compiler output depends on the consumer's compiler
-version + rune config. Pre-compiling locks the output to whichever Svelte
-version the lib was built against and breaks tree-shaking + HMR in the
-consuming app. Letting consumers compile means every version, every dev
-mode, every runes setting works.
+**Why:** Svelte 5's compiler output depends on the consumer's
+compiler version + rune config. Pre-compiling locks the output to
+whichever Svelte version the lib was built against and breaks
+tree-shaking + HMR in the consuming app. Letting consumers compile
+means every version, every dev mode, every runes setting works.
 
-A consumer's `vite.config.ts` should also tell `optimizeDeps` about us so
-the dev server pre-bundles the source:
+A consumer's `vite.config.ts` should also tell `optimizeDeps`
+about us so the dev server pre-bundles the source:
 
 ```ts
 optimizeDeps: {
@@ -43,23 +46,20 @@ optimizeDeps: {
 
 ## Required peer setup
 
-Components use semantic colour tokens (`bg-surface`, `text-foreground`,
-`text-accent`, …) from [`@emdzej/bimmerz-theme`](../theme). Wire that
-preset into the consumer app's `tailwind.config.ts` first; the
-components break visually without it.
+Components use semantic colour tokens (`bg-surface`,
+`text-foreground`, `text-accent`, `m-stripe`, …) from
+[`@emdzej/bimmerz-theme`](../theme). Wire that preset into the
+consumer app's `tailwind.config.ts` and import its `tokens.css`
+first; the components break visually without those tokens.
 
 ## Components
 
 | Name | Purpose |
 |---|---|
-| `<Brand body="EDIABAS" suffix="X" />` | Split-colour wordmark — body in foreground, suffix in accent. |
+| `<Brand body suffix class? />` | Split-colour wordmark — body in foreground, suffix in accent. |
+| `<MStripe class? />` | BMW M tricolour bar (light-blue / dark-blue / red) used as the page-top signature. Renders the `.m-stripe` element from `@emdzej/bimmerz-theme/tokens.css`. |
 
-More to come — About dialog, Settings dialog scaffolding, Connect button,
-install picker. The existing app-specific implementations in inpax-web /
-ncsx-web / ediabasx-web are slated for consolidation here once their
-shapes stabilise.
-
-## Usage
+### `<Brand>`
 
 ```svelte
 <script lang="ts">
@@ -67,7 +67,110 @@ shapes stabilise.
 </script>
 
 <Brand body="EDIABAS" suffix="X" />
+<Brand body="DASH"    suffix="X" class="text-2xl" />
+```
+
+Default styling is `text-sm font-bold tracking-wide`. Pass extra
+Tailwind classes via `class` for hero / welcome-screen variants.
+Each consumer app picks its own `accent` colour via
+`tailwind.config.ts` extend.
+
+### `<MStripe>`
+
+```svelte
+<script lang="ts">
+  import { MStripe } from "@emdzej/bimmerz-ui";
+</script>
+
+<MStripe />
+<MStripe class="h-2" />  <!-- thicker variant -->
 ```
 
-Pair with `@emdzej/bimmerz-theme` for the colour tokens. Each consumer
-app picks its own `accent` colour via `tailwind.config.ts` extend.
+Renders three bands (`m-stripe__band--light`, `--dark`, `--red`).
+Colours resolve through the `.m-stripe` CSS in
+`@emdzej/bimmerz-theme/tokens.css` — consumer must have those
+tokens imported. Default height is 4 px.
+
+## Hooks
+
+### `useEmbeddedAutoConnect`
+
+Embedded-mode lifecycle hook for every dongle-hosted app. Browser
+builds keep the manual "Connect" button; embedded builds (those
+served by the bimmerz-box at `/dashx/`, `/inpax/`, …) wire this
+hook into `App.svelte` to **auto-connect on open**, **auto-disconnect
+on close**, and **auto-reconnect with exponential backoff** on
+transient transport drops.
+
+The hook is a **no-op when `isEmbedded === false`**, so calling it
+unconditionally from `App.svelte` is the intended pattern. Must be
+called inside a Svelte 5 component context (uses `$effect`).
+
+```svelte
+<script lang="ts">
+  import { useEmbeddedAutoConnect } from "@emdzej/bimmerz-ui";
+  import { isEmbedded } from "./lib/embedded";
+  import { app } from "./lib/state.svelte";
+  import { connect, disconnect } from "./lib/connection.svelte";
+
+  useEmbeddedAutoConnect({
+    isEmbedded,
+    connect,
+    disconnect,
+    /* Optional readiness gate — inpax/ncsx wait for the install to
+       load before connecting; dashx/ediabasx can omit this. */
+    isReady: () => app.install !== null,
+    /* Drives the auto-reconnect loop: when this flips back to
+       false (transient Wi-Fi drop, dongle reboot, bus-off), the
+       hook re-enters the backoff retry loop. */
+    isConnected: () => app.status.kind === "connected",
+  });
+</script>
+```
+
+**Behaviour:**
+
+| Event | Effect |
+|---|---|
+| Mount, `isEmbedded` + `isReady` true | Call `connect()` once. |
+| `connect()` throws | Retry with exponential backoff (1 → 2 → 4 → 8 → 16 → 30 s cap). Reset on success. |
+| `isConnected()` observed false later | Re-enter the backoff retry loop. |
+| `beforeunload` / `pagehide` | Fire-and-forget `disconnect()` so the dongle WebSocket closes cleanly. Both events handled — `pagehide` covers mobile Safari's bfcache. |
+| `isEmbedded` false | Hook does nothing. Manual Connect button stays in charge. |
+
+**Options:**
+
+```ts
+interface AutoConnectOptions {
+  isEmbedded: boolean;
+  connect: () => Promise<void>;
+  disconnect: () => Promise<void>;
+  isReady?: () => boolean;          // default: always ready
+  isConnected?: () => boolean;      // omit to attempt only once
+  maxBackoffMs?: number;            // default 30_000
+  initialBackoffMs?: number;        // default 1_000
+  log?: (msg: string, level?: "info" | "warn" | "error") => void;
+}
+```
+
+**Where to use it:**
+
+- **dashx-web** — `connect()` opens the RPC CAN session at
+  `${origin}/rpc/can/0`. No `isReady` gate needed.
+- **ediabasx-web** — `connect()` opens the ediabasx RPC session at
+  `${origin}/rpc/ediabasx`. No `isReady` gate needed.
+- **inpax-web** / **ncsx-web** — `connect()` opens the ediabasx-server
+  RPC session over WebSocket. `isReady` should return true once the
+  remote install has loaded; otherwise the hook idles until then.
+
+**Why centralise this**: every embedded app needs the same
+lifecycle (connect on mount, clean disconnect on close, retry on
+transient failure). Without the shared hook each app drifts —
+different backoff curves, different unload event sets, different
+reconnect semantics. One implementation, four consumers.
+
+## Versioning
+
+`0.2.0` adds the `useEmbeddedAutoConnect` hook. `Brand` + `MStripe`
+APIs are unchanged from `0.1.x`. SemVer minor — existing consumers
+upgrade without code changes.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@emdzej/bimmerz-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
-  "description": "Shared Svelte 5 components for the bimmerz app family — About dialog, Settings scaffolding, Connect button, brand wordmark, install picker. Source-only — consumer apps' Vite compiles them.",
+  "description": "Shared Svelte 5 components + lifecycle hooks for the bimmerz app family — brand wordmark, M-stripe, embedded-mode auto-connect hook. Source-only — consumer apps' Vite compiles them.",
   "svelte": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {

package/src/index.ts

@@ -14,3 +14,13 @@
 
 export { default as Brand } from "./Brand.svelte";
 export { default as MStripe } from "./MStripe.svelte";
+
+/* Embedded-mode lifecycle hook — shared across every dongle-hosted
+   app (dashx / ediabasx / inpax / ncsx). Browser builds keep the
+   manual Connect button; embedded builds wire this hook into
+   App.svelte to auto-connect on mount + auto-disconnect on
+   beforeunload + auto-reconnect with backoff on transient drops. */
+export {
+  useEmbeddedAutoConnect,
+  type AutoConnectOptions,
+} from "./useEmbeddedAutoConnect.svelte.js";

package/src/useEmbeddedAutoConnect.svelte.ts

@@ -0,0 +1,187 @@
+/**
+ * `useEmbeddedAutoConnect` — shared embedded-mode lifecycle hook
+ * for every bimmerz app (dashx / ediabasx / inpax / ncsx / …).
+ *
+ * Embedded builds run inside the bimmerz-box dongle and serve the
+ * SPA at a fixed path (`/dashx/`, `/inpax/`, …) with the backend
+ * always at `window.location.origin`. The user opening the page
+ * explicitly navigated to the dongle — there's no ambiguity about
+ * what to connect to, so the "Connect" button is friction the
+ * embedded form factor doesn't need.
+ *
+ * What the hook does, called once from `App.svelte`:
+ *
+ *   1. **On mount** — if `isEmbedded` is true AND optional
+ *      `isReady()` gate returns true (inpax/ncsx use this to wait
+ *      for the install to load), kick off `connect()` once.
+ *   2. **Auto-reconnect** — when `isConnected()` is observed to
+ *      flip back to false (transient Wi-Fi drop, dongle reboot,
+ *      bus-off recovery), retry with exponential backoff
+ *      (1 s → 2 → 4 → 8 → 16 → 30 s cap). Successful connect
+ *      resets the backoff.
+ *   3. **On unload / unmount** — call `disconnect()` so the
+ *      dongle-side WebSocket closes cleanly instead of waiting
+ *      on TCP keep-alive. Avoids "duplicate session" rejection
+ *      on the next visit if the dongle tracks single-client
+ *      sessions per endpoint.
+ *
+ * The hook is **a no-op when `isEmbedded === false`**. Browser
+ * builds keep their manual Connect button — Web Serial picker
+ * needs a user gesture anyway, so auto-connect couldn't help.
+ *
+ * Must be called inside a Svelte 5 component context (uses
+ * `$effect`).
+ */
+
+export interface AutoConnectOptions {
+  /**
+   * Whether this build is the dongle-embedded variant. When
+   * false the hook does nothing.
+   */
+  isEmbedded: boolean;
+
+  /**
+   * Open the bus / RPC session. May throw — the hook catches and
+   * schedules a retry. Should be idempotent (a second call while
+   * already connected should not error or duplicate work).
+   */
+  connect: () => Promise<void>;
+
+  /**
+   * Tear down the connection. Called on `beforeunload`. Should be
+   * fast and tolerant of being called while already disconnected.
+   */
+  disconnect: () => Promise<void>;
+
+  /**
+   * Reactive readiness check — return true when the app is ready
+   * to connect. Used by inpax/ncsx to wait for the install to
+   * load; dashx/ediabasx can omit it (always ready).
+   */
+  isReady?: () => boolean;
+
+  /**
+   * Reactive connection-state read. Drives auto-reconnect: when
+   * this flips from true to false the hook starts a backoff loop.
+   * If omitted the hook only ever attempts a single connect.
+   */
+  isConnected?: () => boolean;
+
+  /**
+   * Cap on the exponential backoff (ms). Default 30 000.
+   */
+  maxBackoffMs?: number;
+
+  /**
+   * Initial backoff (ms). Default 1 000.
+   */
+  initialBackoffMs?: number;
+
+  /**
+   * Optional logger. The hook is intentionally quiet by default —
+   * embedded mode runs unattended for hours, log spam isn't useful.
+   * Supply this if you want connect attempts surfaced (a project
+   * usually wires it to its bimmerz-logger category).
+   */
+  log?: (message: string, level?: "info" | "warn" | "error") => void;
+}
+
+const DEFAULT_INITIAL_BACKOFF_MS = 1_000;
+const DEFAULT_MAX_BACKOFF_MS = 30_000;
+
+export function useEmbeddedAutoConnect(options: AutoConnectOptions): void {
+  /* Browser builds: do nothing. Calling the hook unconditionally
+     from App.svelte is the intended pattern; this guard is what
+     makes that cheap. */
+  if (!options.isEmbedded) return;
+
+  const initial = options.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;
+  const cap = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+  const log = options.log ?? (() => undefined);
+
+  /* Connection-state loop. $effect re-runs whenever its tracked
+     reactive deps (`isReady()` + `isConnected()`) change. Each run
+     either:
+       • exits silently (already connected, or not ready), or
+       • starts an attempt → retry loop until success or unmount.
+     The cleanup cancels any pending retry so a re-run doesn't
+     stack timers. */
+  $effect(() => {
+    /* Read both gates synchronously so the effect tracks them. */
+    const ready = options.isReady ? options.isReady() : true;
+    const connected = options.isConnected ? options.isConnected() : false;
+
+    if (!ready) {
+      log("auto-connect: waiting for ready", "info");
+      return;
+    }
+    if (connected) {
+      /* Already connected — nothing to do. The effect re-runs if
+         `isConnected()` flips back to false. */
+      return;
+    }
+
+    let cancelled = false;
+    let backoff = initial;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const attempt = async (): Promise<void> => {
+      if (cancelled) return;
+      try {
+        log(`auto-connect: attempting (backoff was ${backoff} ms)`, "info");
+        await options.connect();
+        backoff = initial;
+        log("auto-connect: success", "info");
+        /* Don't re-loop — the effect's next re-run (driven by
+           `isConnected()` going true) is what handles the
+           steady-state "connected" branch. */
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log(`auto-connect: failed (${msg}); retry in ${backoff} ms`, "warn");
+        const wait = backoff;
+        backoff = Math.min(backoff * 2, cap);
+        if (!cancelled) {
+          timer = setTimeout(() => {
+            timer = null;
+            void attempt();
+          }, wait);
+        }
+      }
+    };
+
+    void attempt();
+
+    return () => {
+      cancelled = true;
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+  });
+
+  /* Clean shutdown on tab close. `beforeunload` is the canonical
+     signal; we register only in embedded mode so browser builds
+     never pay the cost. Disconnect is fire-and-forget — by the
+     time the promise resolves the page might be gone, that's
+     fine. */
+  $effect(() => {
+    if (typeof window === "undefined") return;
+    const handler = (): void => {
+      try {
+        void options.disconnect().catch(() => undefined);
+      } catch {
+        /* swallow */
+      }
+    };
+    window.addEventListener("beforeunload", handler);
+    /* `pagehide` is the mobile-Safari-friendly counterpart — fires
+       when the tab is suspended / put into the back/forward cache.
+       Adding both is safe; the disconnect is idempotent. */
+    window.addEventListener("pagehide", handler);
+    return () => {
+      window.removeEventListener("beforeunload", handler);
+      window.removeEventListener("pagehide", handler);
+    };
+  });
+}