@happyvertical/smrt-svelte 0.43.1 → 0.43.3

package/AGENTS.md

@@ -15,6 +15,7 @@ subpath you are editing. This file keeps what holds in every module.
 | `src/test-support/` + `__tests__/` | the golden-test harness and pattern for Svelte component tests | [agents/testing.md](agents/testing.md) |
 | `src/components/settings/` (`./settings`) | `SettingsCatalog`, `paginateSettingsCatalog`, and the summary-vs-detail scalability contract | [agents/settings.md](agents/settings.md) |
 | `src/components/workspace/` (`./workspace` + `./web`) | the AdminShell family and its principles, the legacy ToolsDock surface, the `./web` activity-feed and `updateAvailable` adapters, and server-side dock gates | [agents/workspace.md](agents/workspace.md) |
+| `src/web/remote-query.svelte.ts` | Svelte 5 binding for query-shaped remote pages: rows, page, totals, loading/refreshing/stale/error, retry, last-updated, and query-scoped live subscriptions (#2445) | — |
 
 ## The UI split — primitive-adoption contract (#1589)
 

package/README.md

@@ -60,6 +60,24 @@ state.
 
 ## Usage
 
+### Query-backed data surfaces
+
+Use the web binding when a table should render one remote page instead of
+hydrating its whole collection. It exposes `rows`, `page`, `total`,
+`loading`, `refreshing`, `stale`, `error`, `retry`, and `lastUpdated`.
+
+```svelte
+<script lang="ts">
+  import { remoteQuery } from '@happyvertical/smrt-svelte/web';
+  const view = remoteQuery(collection, transport);
+  // Failures remain available as view.error for reactive rendering.
+  void view.execute(request).catch(() => undefined);
+</script>
+
+{#if view.loading}<p>Loading…</p>{/if}
+{#each view.rows as row (row.id)}<div>{row.name}</div>{/each}
+```
+
 ### Provider Setup
 
 ```svelte

package/dist/web/__tests__/remote-query-harness.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+import type {
+  SmrtWebCollection,
+  SmrtWebQueryTransport,
+} from '@happyvertical/smrt-web';
+import {
+  type RemoteQueryBinding,
+  remoteQuery,
+} from '../remote-query.svelte.js';
+
+interface Props {
+  collection: SmrtWebCollection<Record<string, unknown>>;
+  transport: SmrtWebQueryTransport;
+  onReady: (view: RemoteQueryBinding<Record<string, unknown>>) => void;
+}
+
+const props: Props = $props();
+// The harness intentionally creates one binding for its component lifetime.
+// svelte-ignore state_referenced_locally
+const view = remoteQuery(props.collection, props.transport);
+// svelte-ignore state_referenced_locally
+props.onReady(view);
+</script>
+
+<output data-testid="remote-query-state">
+  {view.request?.requestId ?? 'none'}:{view.rows.map((row) => row.id).join(',')}
+</output>

package/dist/web/__tests__/remote-query-harness.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { SmrtWebCollection, SmrtWebQueryTransport } from '@happyvertical/smrt-web';
+import { type RemoteQueryBinding } from '../remote-query.svelte.js';
+interface Props {
+    collection: SmrtWebCollection<Record<string, unknown>>;
+    transport: SmrtWebQueryTransport;
+    onReady: (view: RemoteQueryBinding<Record<string, unknown>>) => void;
+}
+declare const RemoteQueryHarness: import("svelte").Component<Props, {}, "">;
+type RemoteQueryHarness = ReturnType<typeof RemoteQueryHarness>;
+export default RemoteQueryHarness;
+//# sourceMappingURL=remote-query-harness.svelte.d.ts.map

package/dist/web/__tests__/remote-query-harness.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-query-harness.svelte.d.ts","sourceRoot":"","sources":["../../../src/web/__tests__/remote-query-harness.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,2BAA2B,CAAC;AAGnC,UAAU,KAAK;IACb,UAAU,EAAE,iBAAiB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,SAAS,EAAE,qBAAqB,CAAC;IACjC,OAAO,EAAE,CAAC,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC;CACtE;AAoBD,QAAA,MAAM,kBAAkB,2CAAwC,CAAC;AACjE,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,eAAe,kBAAkB,CAAC"}

package/dist/web/__tests__/remote-query.svelte.test.js

@@ -0,0 +1,100 @@
+import { createSmrtCollection, } from '@happyvertical/smrt-web';
+import { flushSync, mount, unmount } from 'svelte';
+import { describe, expect, it, vi } from 'vitest';
+import Harness from './remote-query-harness.svelte';
+const definition = {
+    name: 'remote-query-svelte-products',
+    className: 'Product',
+    endpoint: '/products',
+    idField: 'id',
+    actions: ['list'],
+    fields: { name: { type: 'text' } },
+};
+const request = {
+    version: 1,
+    requestId: 'svelte-request',
+    mode: 'rows',
+    page: { kind: 'offset', offset: 0, limit: 10 },
+};
+function envelope(received, name) {
+    return {
+        version: 1,
+        requestId: received.requestId,
+        queryFingerprint: 'dq1_svelte_products',
+        identityField: 'id',
+        rows: [{ id: name, name }],
+        page: { kind: 'offset', offset: 0, limit: 10, hasMore: false },
+        total: { kind: 'exact', value: 1 },
+        freshness: { state: 'fresh' },
+        warnings: [],
+        truncated: false,
+    };
+}
+function mountView(collection, transport) {
+    const target = document.createElement('div');
+    document.body.appendChild(target);
+    let view = undefined;
+    const component = mount(Harness, {
+        target,
+        props: {
+            collection: collection,
+            transport,
+            onReady: (next) => {
+                view = next;
+            },
+        },
+    });
+    return {
+        target,
+        view,
+        teardown: () => {
+            unmount(component);
+            target.remove();
+        },
+    };
+}
+describe('remoteQuery', () => {
+    it('renders request and rows reactively through the Svelte binding', async () => {
+        const collection = createSmrtCollection(definition, {
+            fetchers: { list: async () => [], create: async () => ({}) },
+        });
+        const mounted = mountView(collection, {
+            query: async (received) => envelope(received, 'Ada'),
+        });
+        await mounted.view.execute(request);
+        flushSync();
+        expect(mounted.target.textContent).toContain('svelte-request:Ada');
+        mounted.teardown();
+        await collection.cleanup();
+    });
+    it('disposes an in-flight refresh and live subscription when unmounted', async () => {
+        let calls = 0;
+        let unsubscribed = false;
+        const collection = createSmrtCollection(definition, {
+            fetchers: { list: async () => [], create: async () => ({}) },
+        });
+        const mounted = mountView(collection, {
+            query: async (received, options) => {
+                calls += 1;
+                if (calls === 1)
+                    return envelope(received, 'initial');
+                return await new Promise((_resolve, reject) => {
+                    options?.signal?.addEventListener('abort', () => reject(options.signal?.reason), { once: true });
+                });
+            },
+            subscribe: () => ({
+                unsubscribe: () => {
+                    unsubscribed = true;
+                },
+            }),
+        });
+        await mounted.view.execute(request);
+        mounted.view.subscribeLive();
+        const refresh = mounted.view.refresh();
+        await vi.waitFor(() => expect(calls).toBe(2));
+        mounted.teardown();
+        await expect(refresh).rejects.toMatchObject({ name: 'AbortError' });
+        expect(unsubscribed).toBe(true);
+        await collection.cleanup();
+    });
+});

package/dist/web/index.d.ts

@@ -16,5 +16,6 @@
  */
 export { type ActivityFeedHandle, type ActivityFeedMap, type ActivityFeedOptions, activityFeed, type ShellActivityInput, } from './activity-feed.svelte.js';
 export { type LiveCollection, type LiveCollectionMutation, type LiveCollectionOptions, type LiveCollectionStatus, liveCollection, } from './live-collection.svelte.js';
+export { type RemoteQueryBinding, remoteQuery, } from './remote-query.svelte.js';
 export { type UpdateAvailableView, type UseUpdateAvailableOptions, useUpdateAvailable, } from './update-available.svelte.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/web/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,YAAY,EACZ,KAAK,kBAAkB,GACxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,cAAc,GACf,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,kBAAkB,GACnB,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,YAAY,EACZ,KAAK,kBAAkB,GACxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,cAAc,GACf,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,kBAAkB,EACvB,WAAW,GACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,kBAAkB,GACnB,MAAM,8BAA8B,CAAC"}

package/dist/web/index.js

@@ -16,4 +16,5 @@
  */
 export { activityFeed, } from './activity-feed.svelte.js';
 export { liveCollection, } from './live-collection.svelte.js';
+export { remoteQuery, } from './remote-query.svelte.js';
 export { useUpdateAvailable, } from './update-available.svelte.js';

package/dist/web/remote-query.svelte.d.ts

@@ -0,0 +1,26 @@
+import { type SmrtWebCollection, type SmrtWebDataQueryRequest, type SmrtWebDataQueryResult, type SmrtWebQueryLiveSubscription, type SmrtWebQueryRunOptions, type SmrtWebQueryState, type SmrtWebQueryTransport } from '@happyvertical/smrt-web';
+export interface RemoteQueryBinding<TData extends object = object> {
+    readonly rows: ReadonlyArray<TData>;
+    readonly page: SmrtWebQueryState<TData>['page'];
+    readonly total: SmrtWebQueryState<TData>['total'];
+    readonly loading: boolean;
+    readonly refreshing: boolean;
+    readonly stale: boolean;
+    readonly error: unknown;
+    readonly lastUpdated: number | undefined;
+    readonly request: SmrtWebDataQueryRequest | undefined;
+    execute(request: SmrtWebDataQueryRequest, options?: SmrtWebQueryRunOptions): Promise<SmrtWebDataQueryResult>;
+    refresh(options?: Omit<SmrtWebQueryRunOptions, 'mode' | 'force'>): Promise<SmrtWebDataQueryResult | undefined>;
+    retry(): Promise<SmrtWebDataQueryResult | undefined>;
+    subscribeLive(): SmrtWebQueryLiveSubscription | undefined;
+    dispose(): void;
+}
+/**
+ * Bind a canonical remote query to Svelte 5 state. The binding is query
+ * shaped: rows are only the requested page and never the entire collection.
+ * Call during component initialization so cleanup follows the component.
+ */
+export declare function remoteQuery<TData extends object>(collection: SmrtWebCollection<TData>, transport: SmrtWebQueryTransport, options?: {
+    staleTimeMs?: number;
+}): RemoteQueryBinding<TData>;
+//# sourceMappingURL=remote-query.svelte.d.ts.map

package/dist/web/remote-query.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-query.svelte.d.ts","sourceRoot":"","sources":["../../src/web/remote-query.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAE3B,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,kBAAkB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IAC/D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,uBAAuB,GAAG,SAAS,CAAC;IACtD,OAAO,CACL,OAAO,EAAE,uBAAuB,EAChC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACnC,OAAO,CACL,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,OAAO,CAAC,GACvD,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IAC/C,KAAK,IAAI,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IACrD,aAAa,IAAI,4BAA4B,GAAG,SAAS,CAAC;IAC1D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,SAAS,MAAM,EAC9C,UAAU,EAAE,iBAAiB,CAAC,KAAK,CAAC,EACpC,SAAS,EAAE,qBAAqB,EAChC,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACjC,kBAAkB,CAAC,KAAK,CAAC,CAwD3B"}

package/dist/web/remote-query.svelte.js

@@ -0,0 +1,57 @@
+import { createSmrtWebQuery, } from '@happyvertical/smrt-web';
+/**
+ * Bind a canonical remote query to Svelte 5 state. The binding is query
+ * shaped: rows are only the requested page and never the entire collection.
+ * Call during component initialization so cleanup follows the component.
+ */
+export function remoteQuery(collection, transport, options) {
+    const query = createSmrtWebQuery(collection, transport, options);
+    let snapshot = $state(query.state);
+    let activeRequest = $state(query.request);
+    const unsubscribe = query.subscribe((next) => {
+        snapshot = next;
+        activeRequest = query.request;
+    });
+    $effect(() => () => {
+        unsubscribe();
+        query.dispose();
+    });
+    const binding = {
+        get rows() {
+            return snapshot.rows;
+        },
+        get page() {
+            return snapshot.page;
+        },
+        get total() {
+            return snapshot.total;
+        },
+        get loading() {
+            return snapshot.loading;
+        },
+        get refreshing() {
+            return snapshot.refreshing;
+        },
+        get stale() {
+            return snapshot.stale;
+        },
+        get error() {
+            return snapshot.error;
+        },
+        get lastUpdated() {
+            return snapshot.lastUpdated;
+        },
+        get request() {
+            return activeRequest;
+        },
+        execute: (request, runOptions) => query.execute(request, runOptions),
+        refresh: (runOptions) => query.refresh(runOptions),
+        retry: () => query.retry(),
+        subscribeLive: () => query.subscribeLive(),
+        dispose: () => {
+            unsubscribe();
+            query.dispose();
+        },
+    };
+    return binding;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-svelte",
-  "version": "0.43.1",
+  "version": "0.43.3",
   "description": "Svelte 5 components for SMRT user management - auth, users, tenants, roles, permissions, groups",
   "type": "module",
   "smrtRawPrimitives": "strict",
@@ -123,10 +123,10 @@
     "@tanstack/db": "^0.6.14",
     "@tanstack/svelte-db": "^0.1.91",
     "esm-env": "^1.2.2",
-    "@happyvertical/smrt-types": "0.43.1",
-    "@happyvertical/smrt-web": "0.43.1",
-    "@happyvertical/smrt-languages": "0.43.1",
-    "@happyvertical/smrt-ui": "0.43.1"
+    "@happyvertical/smrt-types": "0.43.3",
+    "@happyvertical/smrt-web": "0.43.3",
+    "@happyvertical/smrt-ui": "0.43.3",
+    "@happyvertical/smrt-languages": "0.43.3"
   },
   "peerDependencies": {
     "@huggingface/transformers": ">=3.8.1",