@happyvertical/smrt-svelte 0.38.1 → 0.38.3

package/dist/web/__tests__/activity-feed.svelte.test.js

@@ -0,0 +1,235 @@
+/**
+ * Unit tests for the AdminShell activity feed adapter's reconciliation core
+ * (#1779).
+ *
+ * These exercise {@link ActivityFeedReconciler} — the pure diff between a set of
+ * live rows and the shell activity registry — against a REAL {@link ShellState}.
+ * Per repo policy nothing here is mocked: the shell, its activity events, and
+ * the mapping are all real; the reconciler is fed plain row arrays that stand in
+ * for successive live-collection ticks (`liveCollection`'s engine is exercised
+ * separately in `activity-feed.integration.svelte.test.ts`). This isolates the
+ * mapping / create-update-remove / ownership behavior the adapter guarantees.
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import { createShellState } from '../../components/workspace/admin-shell/state.svelte.js';
+import { ActivityFeedReconciler, } from '../activity-feed.svelte.js';
+/** Editorial map: a job row → focus-scope activity, or `null` for a draft. */
+const mapJob = (row) => {
+    if (row.draft)
+        return null;
+    return {
+        kind: 'render-job',
+        scope: 'focus',
+        label: row.title,
+        status: row.state,
+        progress: row.progress ?? null,
+    };
+};
+/** Record every activity event the shell emits, for sequence assertions. */
+function recordEvents(shell) {
+    const events = [];
+    const stop = shell.watchActivities((event) => events.push(event));
+    return { events, stop };
+}
+describe('ActivityFeedReconciler', () => {
+    const teardown = [];
+    afterEach(() => {
+        for (const fn of teardown.splice(0))
+            fn();
+    });
+    function setup() {
+        const shell = createShellState();
+        const recorded = recordEvents(shell);
+        teardown.push(recorded.stop);
+        const reconciler = new ActivityFeedReconciler(shell, mapJob);
+        return { shell, reconciler, events: recorded.events };
+    }
+    it('upserts a shell activity when a row first appears', () => {
+        const { shell, reconciler, events } = setup();
+        reconciler.reconcile([
+            { id: 'job-1', title: 'Render intro', state: 'running', progress: 20 },
+        ]);
+        const activities = shell.listActivities();
+        expect(activities).toHaveLength(1);
+        expect(activities[0]).toMatchObject({
+            id: 'job-1',
+            kind: 'render-job',
+            scope: 'focus',
+            label: 'Render intro',
+            status: 'running',
+            progress: 20,
+        });
+        // The activity id defaults to the row id, and the shell stamped createdAt.
+        expect(activities[0].createdAt).toBeTruthy();
+        // A single create event (upsert), no transition/remove.
+        expect(events.map((e) => e.type)).toEqual(['upsert']);
+    });
+    it('updates the activity in place when a row changes (status transition)', () => {
+        const { shell, reconciler, events } = setup();
+        reconciler.reconcile([
+            { id: 'job-1', title: 'Render intro', state: 'running', progress: 20 },
+        ]);
+        const createdAt = shell.listActivities()[0].createdAt;
+        // Same row id, advanced progress + status flip → an UPDATE, not a second
+        // create, and the shell reports it as a `transition` (status changed).
+        reconciler.reconcile([
+            { id: 'job-1', title: 'Render intro', state: 'completed', progress: 100 },
+        ]);
+        const activities = shell.listActivities();
+        expect(activities).toHaveLength(1);
+        expect(activities[0]).toMatchObject({
+            id: 'job-1',
+            status: 'completed',
+            progress: 100,
+        });
+        // createdAt preserved across the update (update went through updateActivity,
+        // not a fresh upsert that would re-stamp it).
+        expect(activities[0].createdAt).toBe(createdAt);
+        expect(events.map((e) => e.type)).toEqual(['upsert', 'transition']);
+    });
+    it('performs no shell mutation when a reconcile tick is unchanged', () => {
+        const { reconciler, events } = setup();
+        const rows = [
+            { id: 'job-1', title: 'Render intro', state: 'running', progress: 20 },
+        ];
+        reconciler.reconcile(rows);
+        // Re-feed identical content (a common no-op reactive tick): a new array with
+        // an equal-but-distinct row object. Must not emit a second event.
+        reconciler.reconcile([{ ...rows[0] }]);
+        expect(events.map((e) => e.type)).toEqual(['upsert']);
+    });
+    it('removes the activity when its row vanishes from the collection', () => {
+        const { shell, reconciler, events } = setup();
+        reconciler.reconcile([
+            { id: 'job-1', title: 'Render intro', state: 'running' },
+            { id: 'job-2', title: 'Render outro', state: 'queued' },
+        ]);
+        expect(shell.listActivities()).toHaveLength(2);
+        // job-1 gone from the next tick → removed; job-2 unchanged → left alone.
+        reconciler.reconcile([
+            { id: 'job-2', title: 'Render outro', state: 'queued' },
+        ]);
+        const remaining = shell.listActivities();
+        expect(remaining).toHaveLength(1);
+        expect(remaining[0].id).toBe('job-2');
+        expect(events.map((e) => e.type)).toEqual([
+            'upsert', // job-1 create
+            'upsert', // job-2 create
+            'remove', // job-1 removed
+        ]);
+    });
+    it('treats a row that maps to null as absent (excluded, then removed when it flips)', () => {
+        const { shell, reconciler } = setup();
+        // A draft row maps to null → never becomes an activity.
+        reconciler.reconcile([
+            { id: 'job-1', title: 'Draft', state: 'queued', draft: true },
+        ]);
+        expect(shell.listActivities()).toHaveLength(0);
+        // It leaves draft → now an activity appears.
+        reconciler.reconcile([
+            { id: 'job-1', title: 'Published', state: 'running' },
+        ]);
+        expect(shell.listActivities()).toHaveLength(1);
+        // It goes back to draft (maps to null again) → activity is removed.
+        reconciler.reconcile([
+            { id: 'job-1', title: 'Published', state: 'running', draft: true },
+        ]);
+        expect(shell.listActivities()).toHaveLength(0);
+    });
+    it('lets the map decouple the activity id from the row id', () => {
+        const shell = createShellState();
+        const reconciler = new ActivityFeedReconciler(shell, (row) => ({
+            id: `activity:${row.id}`,
+            kind: 'render-job',
+            scope: 'system',
+            label: row.title,
+            status: row.state,
+        }));
+        reconciler.reconcile([{ id: 'job-1', title: 'Job', state: 'running' }]);
+        const activities = shell.listActivities();
+        expect(activities).toHaveLength(1);
+        expect(activities[0].id).toBe('activity:job-1');
+    });
+    it('routes an activity to the shell edge for its scope', () => {
+        const { shell, reconciler } = setup();
+        reconciler.reconcile([{ id: 'job-1', title: 'Job', state: 'running' }]);
+        // scope 'focus' homes to the right edge (SCOPE_EDGES.focus === 'right').
+        expect(shell.listActivities({ edge: 'right' })).toHaveLength(1);
+    });
+    it('re-homes the activity to the new edge when its scope changes (no explicit edge)', () => {
+        const shell = createShellState();
+        // Map keys scope off the row so a later tick can change it; no `edge` set.
+        const reconciler = new ActivityFeedReconciler(shell, (row) => ({
+            kind: 'render-job',
+            // Reuse the unused `draft` flag as a cheap "move to system scope" toggle.
+            scope: row.draft ? 'system' : 'focus',
+            label: row.title,
+            status: row.state,
+        }));
+        reconciler.reconcile([{ id: 'job-1', title: 'Job', state: 'running' }]);
+        // Focus → right edge.
+        expect(shell.listActivities({ edge: 'right' })).toHaveLength(1);
+        expect(shell.listActivities({ edge: 'bottom' })).toHaveLength(0);
+        // Scope flips to system; the map still sets no explicit edge. The activity
+        // must RE-DERIVE its edge from the new scope (system → bottom), not stay
+        // pinned to the old right edge.
+        reconciler.reconcile([
+            { id: 'job-1', title: 'Job', state: 'running', draft: true },
+        ]);
+        expect(shell.listActivities({ edge: 'right' })).toHaveLength(0);
+        expect(shell.listActivities({ edge: 'bottom' })).toHaveLength(1);
+        expect(shell.listActivities()[0].scope).toBe('system');
+    });
+    it('clears a previously-set optional field when a later mapping drops it', () => {
+        const shell = createShellState();
+        // Map emits `message`/`detailHref` only while the job is running.
+        const reconciler = new ActivityFeedReconciler(shell, (row) => ({
+            kind: 'render-job',
+            scope: 'focus',
+            label: row.title,
+            status: row.state,
+            ...(row.state === 'running'
+                ? { message: 'Rendering frames', detailHref: '/jobs/job-1' }
+                : {}),
+        }));
+        reconciler.reconcile([{ id: 'job-1', title: 'Job', state: 'running' }]);
+        let activity = shell.listActivities()[0];
+        expect(activity.message).toBe('Rendering frames');
+        expect(activity.detailHref).toBe('/jobs/job-1');
+        // The job completes → the map no longer emits message/detailHref. Those
+        // stale values must be CLEARED, not retained from the previous mapping.
+        reconciler.reconcile([{ id: 'job-1', title: 'Job', state: 'completed' }]);
+        activity = shell.listActivities()[0];
+        expect(activity.status).toBe('completed');
+        expect(activity.message).toBeUndefined();
+        expect(activity.detailHref).toBeUndefined();
+    });
+    it('dispose() removes exactly the feed activities and stops reconciling', () => {
+        const { shell, reconciler, events } = setup();
+        // An activity from ANOTHER source the feed must never touch.
+        shell.upsertActivity({
+            id: 'external-1',
+            label: 'External',
+            kind: 'other',
+            scope: 'app',
+            status: 'running',
+        });
+        reconciler.reconcile([
+            { id: 'job-1', title: 'Render intro', state: 'running' },
+        ]);
+        expect(shell.listActivities()).toHaveLength(2);
+        reconciler.dispose();
+        // Only the feed's own activity was retracted; the external one survives.
+        const remaining = shell.listActivities();
+        expect(remaining).toHaveLength(1);
+        expect(remaining[0].id).toBe('external-1');
+        expect(reconciler.isDisposed).toBe(true);
+        // Reconciling after dispose is a no-op (no new activities, no events).
+        const eventsBefore = events.length;
+        reconciler.reconcile([
+            { id: 'job-2', title: 'Late job', state: 'running' },
+        ]);
+        expect(shell.listActivities()).toHaveLength(1);
+        expect(events.length).toBe(eventsBefore);
+    });
+});

package/dist/web/activity-feed.svelte.d.ts

@@ -0,0 +1,210 @@
+/**
+ * AdminShell activity feed adapter — bridge a `@happyvertical/smrt-web` live
+ * collection into the AdminShell activity registry (#1779, part of the WASD
+ * AdminShell epic #1766).
+ *
+ * This is a thin, OPT-IN CONSUMER of already-shipped infrastructure, not a new
+ * generated surface. It sits at the intersection of two existing contracts:
+ *
+ *  - the runes-reactive {@link liveCollection} view over a `SmrtWebCollection`
+ *    (`@happyvertical/smrt-svelte/web`, slice A of #1761), and
+ *  - the `ShellState` activity registry (`upsertActivity` / `updateActivity` /
+ *    `removeActivity`, from `components/workspace/admin-shell`).
+ *
+ * The app supplies (a) the `@smrt()` DOMAIN collection (a `SmrtWebCollection`)
+ * and (b) an editorial {@link ActivityFeedMap} that turns each row into the
+ * shell-facing activity fields (`kind`, `scope`, `label`, `progress`, …). The
+ * adapter reconciles the mapped rows against the shell as rows appear, change,
+ * and vanish, and returns a disposer that removes the activities it created.
+ *
+ * ── Why it lives behind the `/web` opt-in entry ─────────────────────────────
+ * `liveCollection` pulls the client-data engine (`@tanstack/db` +
+ * `@tanstack/svelte-db`). Keeping this adapter in the `/web` subpath keeps that
+ * engine OUT of the AdminShell core: nothing under `components/workspace/` may
+ * import this module, so `@happyvertical/smrt-svelte/workspace` stays
+ * transport-agnostic and TanStack-free (a hard constraint of #1766). The app
+ * wires the adapter at the edge, next to where it already opts into `/web`.
+ *
+ * ── Engine-absorption boundary ──────────────────────────────────────────────
+ * No `@tanstack/*` type appears here. The adapter reconciles against the plain
+ * DTO rows exposed by {@link liveCollection} (which already strips the engine's
+ * `$`-prefixed virtual props), so the engine stays swappable behind the same
+ * boundary the rest of `/web` respects.
+ *
+ * ── Reconciliation, not change-diffing ──────────────────────────────────────
+ * Rather than decode the engine's change payload, the adapter re-derives the
+ * activity set from the current live rows on every reactive tick (via an
+ * internal `$effect` over `view.rows`) and diffs it against what it last pushed
+ * to the shell. This is robust to the change-notification shape (which is
+ * engine-internal) and mirrors how the runtime's own consumers treat a change
+ * as a "something moved, re-read" signal.
+ */
+import type { SmrtWebCollection, SmrtWebRow } from '@happyvertical/smrt-web';
+import type { ShellState } from '../components/workspace/admin-shell/state.svelte.js';
+import type { ShellActivity } from '../components/workspace/admin-shell/types.js';
+/**
+ * The shell-facing fields an {@link ActivityFeedMap} produces for one row — the
+ * editorial half of a {@link ShellActivity}. The adapter owns the bookkeeping
+ * fields (`id`, `createdAt`, `updatedAt`), so they are omitted here; `id` may be
+ * supplied to decouple the activity id from the row id (it defaults to the row's
+ * `id`). Everything a consumer legitimately controls (`kind`, `scope`, `label`,
+ * `status`, `subject`, `progress`, `detailHref`, `message`, `edge`, `cancel`)
+ * passes straight through.
+ */
+export type ShellActivityInput = Omit<ShellActivity, 'id' | 'createdAt' | 'updatedAt'> & {
+    /**
+     * Explicit activity id. Defaults to the row's `id` when omitted — the common
+     * case (one activity per row). Supply it only to map a row onto a
+     * differently-keyed activity.
+     */
+    id?: string;
+};
+/**
+ * Map one live-collection row to its shell activity fields, or `null` to
+ * exclude the row from the feed.
+ *
+ * Returning `null` is a first-class signal: a row that maps to `null` is NOT an
+ * activity (e.g. a draft the shell should ignore), and a row that STOPS mapping
+ * to an activity — flips from a value to `null` — is removed from the shell,
+ * exactly as if it had vanished from the collection. This lets the editorial map
+ * gate which rows surface without the consumer filtering the collection.
+ *
+ * @typeParam TData - the row DTO shape carried by the collection.
+ */
+export type ActivityFeedMap<TData extends object> = (row: SmrtWebRow<TData>) => ShellActivityInput | null;
+/**
+ * Options for {@link activityFeed}.
+ *
+ * @typeParam TData - the row DTO shape carried by {@link collection}.
+ */
+export interface ActivityFeedOptions<TData extends object> {
+    /**
+     * The domain live collection to bridge — a `SmrtWebCollection` from
+     * `@happyvertical/smrt-web` (e.g. built by the app's `createSmrtCollection`
+     * over its `@smrt()` class). Its rows drive the feed.
+     */
+    collection: SmrtWebCollection<TData>;
+    /**
+     * The editorial mapping from a row to its shell activity fields (or `null` to
+     * exclude the row). See {@link ActivityFeedMap}.
+     */
+    map: ActivityFeedMap<TData>;
+    /** The AdminShell state whose activity registry this feed drives. */
+    shell: ShellState;
+    /**
+     * Forwarded to the underlying {@link liveCollection}: trigger the collection's
+     * first load eagerly when the feed is created. Defaults to `true`.
+     */
+    preload?: boolean;
+}
+/**
+ * A handle to a running {@link activityFeed}. Call {@link dispose} to detach the
+ * feed and remove every activity it created; read {@link isDisposed} to check.
+ */
+export interface ActivityFeedHandle {
+    /**
+     * Detach the feed: remove every activity this feed still owns from the shell
+     * and stop reconciling. Idempotent. The underlying live-query subscription is
+     * torn down by Svelte when the hosting component unmounts (that is where
+     * `activityFeed` must be called); call this to remove the feed's activities
+     * sooner, or when tearing a feed down without unmounting.
+     */
+    dispose(): void;
+    /** True once {@link dispose} has run. */
+    readonly isDisposed: boolean;
+}
+/**
+ * The pure reconciliation core of {@link activityFeed}: it owns the diff between
+ * a set of live rows and the shell's activity registry, with NO Svelte reactive
+ * or client-data-engine dependency. {@link activityFeed} wraps one of these in a
+ * `$effect` over a {@link liveCollection} view; this split keeps the mapping /
+ * create-update-remove / ownership logic testable against a real `ShellState`
+ * with plain row arrays (mock only externals — see the `__tests__`).
+ *
+ * @internal Not part of the public surface — use {@link activityFeed}.
+ * @typeParam TData - the row DTO shape being reconciled.
+ */
+export declare class ActivityFeedReconciler<TData extends object> {
+    private readonly shell;
+    private readonly map;
+    /**
+     * Activities this feed currently owns, keyed by activity id, each with the
+     * last resolved input + fingerprint so a reconcile can tell created / changed
+     * / unchanged apart and remove exactly its own set on teardown.
+     */
+    private readonly owned;
+    private disposed;
+    constructor(shell: ShellState, map: ActivityFeedMap<TData>);
+    /** True once {@link dispose} has run. */
+    get isDisposed(): boolean;
+    /**
+     * Reconcile `rows` against the owned activity set: upsert newly-appearing
+     * activities, update changed ones, remove vanished ones. A pure diff — an
+     * unchanged tick (same rows, same mappings) performs ZERO shell mutations.
+     * No-op once disposed.
+     */
+    reconcile(rows: ReadonlyArray<SmrtWebRow<TData>>): void;
+    /**
+     * Retract exactly this feed's activities from the shell and stop reconciling.
+     * Idempotent. Activities owned by other sources are left untouched.
+     */
+    dispose(): void;
+}
+/**
+ * Bridge a `@happyvertical/smrt-web` live collection into an AdminShell's
+ * activity registry: each mapped row becomes a {@link ShellActivity} that
+ * appears, updates, and disappears in the shell as the collection changes.
+ *
+ * MUST be called during Svelte component initialization — it delegates to
+ * {@link liveCollection} (which installs a `$effect`) and installs its own
+ * reconciliation `$effect`. Both bind to the calling component's lifecycle, so
+ * the live subscription and reconciliation tear down automatically on unmount.
+ * Unmount ALSO auto-retracts the feed's activities from the shell (via an
+ * `$effect` teardown), so they never linger after the host component is gone —
+ * no manual cleanup required. The returned {@link ActivityFeedHandle.dispose}
+ * retracts them SOONER (without unmounting) and is idempotent, so calling it and
+ * then unmounting is safe.
+ *
+ * Lifecycle per row:
+ *  - a row that newly maps to an activity → `shell.upsertActivity(...)` (creates
+ *    it, stamping `createdAt`);
+ *  - an owned row whose mapping changes → `shell.updateActivity(id, patch)`
+ *    (preserves `createdAt`, bumps `updatedAt`, and the shell emits a
+ *    `transition` event when `status` changed — driving toasts);
+ *  - a row that vanishes, or whose mapping flips to `null` →
+ *    `shell.removeActivity(id)`.
+ *
+ * Only activities this feed created are ever touched: activities pushed to the
+ * shell by other sources (or a second feed) are left untouched, and `dispose`
+ * removes exactly this feed's set.
+ *
+ * @typeParam TData - the row DTO shape carried by {@link ActivityFeedOptions.collection}.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { activityFeed } from '@happyvertical/smrt-svelte/web';
+ *   import { useAdminShell } from '@happyvertical/smrt-svelte/workspace';
+ *   import { createSmrtCollection } from '@happyvertical/smrt-web';
+ *   import { getCollectionDefinition } from '@happyvertical/smrt-virt-web';
+ *
+ *   const shell = useAdminShell();
+ *   const encodes = createSmrtCollection(getCollectionDefinition('encodes'), {});
+ *
+ *   // Reconciles `encodes` rows into the shell's Focus scope; disposes on unmount.
+ *   activityFeed({
+ *     collection: encodes,
+ *     shell,
+ *     map: (row) => ({
+ *       kind: 'video-encode',
+ *       scope: 'focus',
+ *       label: row.title,
+ *       status: row.state,          // 'running' | 'completed' | …
+ *       progress: row.progress,
+ *     }),
+ *   });
+ * </script>
+ * ```
+ */
+export declare function activityFeed<TData extends object>(options: ActivityFeedOptions<TData>): ActivityFeedHandle;
+//# sourceMappingURL=activity-feed.svelte.d.ts.map

package/dist/web/activity-feed.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-feed.svelte.d.ts","sourceRoot":"","sources":["../../src/web/activity-feed.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qDAAqD,CAAC;AACtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8CAA8C,CAAC;AAGlF;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,aAAa,EACb,IAAI,GAAG,WAAW,GAAG,WAAW,CACjC,GAAG;IACF;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,CAAC,KAAK,SAAS,MAAM,IAAI,CAClD,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,KACnB,kBAAkB,GAAG,IAAI,CAAC;AAE/B;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,KAAK,SAAS,MAAM;IACvD;;;;OAIG;IACH,UAAU,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACrC;;;OAGG;IACH,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAC5B,qEAAqE;IACrE,KAAK,EAAE,UAAU,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,OAAO,IAAI,IAAI,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AA+GD;;;;;;;;;;GAUG;AACH,qBAAa,sBAAsB,CAAC,KAAK,SAAS,MAAM;IAUpD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAVtB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAC1D,OAAO,CAAC,QAAQ,CAAS;gBAGN,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC;IAG9C,yCAAyC;IACzC,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI;IA+CvD;;;OAGG;IACH,OAAO,IAAI,IAAI;CAMhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,YAAY,CAAC,KAAK,SAAS,MAAM,EAC/C,OAAO,EAAE,mBAAmB,CAAC,KAAK,CAAC,GAClC,kBAAkB,CAyCpB"}