@happyvertical/smrt-svelte 0.51.4 → 0.51.5

package/AGENTS.md

@@ -16,6 +16,7 @@ subpath you are editing. This file keeps what holds in every module.
 | `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) | — |
+| `src/web/list-data-surface.svelte.ts` (`mountListDataSurface`) | One-call registration of an existing, non-`DataTable` list (already mirroring a headless `DataTableController`) as a mounted `DataSurfaceDescriptor` — a same-behavior port of `registerContentListDataSurface`'s registration/translation logic (`@happyvertical/smrt-content/svelte`), generalized off ContentList's view-mode concept, so any custom list markup can adopt it directly instead of hand-mirroring the registry contract. Not yet unified behind a shared `@happyvertical/smrt-ui/data` implementation (#2917) — this copy is currently ahead; see its own module doc comment for the current, authoritative list of divergences #2917 must adopt rather than assume parity (#2906) | — |
 | `src/web/webmcp-provider.ts` | Provider config for generated data/model WebMCP tools: definitions, effect policy, namespace, budget, legacy/canonical filters, and fetcher seams (#2520) | — |
 | `src/web/webmcp-ui.ts` | Fixed, low-cardinality WebMCP adapter over the Provider's mounted form-control and data-surface registries (#2521) | — |
 | `src/web/webmcp.svelte.ts` (`useWebMcpTool`) | Component-owned bespoke WebMCP tool. Routes through `@happyvertical/smrt-web`'s `registerWebMcpBespokeTool`, so it shares the fail-closed effect classification and `effects` exposure policy of generated tools — undeclared `annotations` classify destructive and are excluded by default. `namespace` and `maxTools` never apply to a bespoke tool (#2586) | — |

package/README.md

@@ -144,6 +144,44 @@ should be discoverable:
 </Provider>
 ```
 
+A page with its own hand-rolled list markup — not `DataTable` — that already
+mirrors a headless `DataTableController`'s search/filters/sort/page/selection
+can register that same registry in one call with `mountListDataSurface`
+(`@happyvertical/smrt-svelte/web`) instead of hand-writing the registration:
+
+```ts
+import { createDataTableController } from '@happyvertical/smrt-ui/data';
+import { mountListDataSurface } from '@happyvertical/smrt-svelte/web';
+
+const controller = createDataTableController();
+const handle = mountListDataSurface({
+  registry: surfaces,
+  descriptor: myListDescriptor,
+  controller,
+  context: { totalRows, queryFingerprint },
+  refresh: () => reload(),
+});
+
+// Only `controller` is observed automatically. App-owned `context` is a
+// one-time snapshot at mount — publish a fresh one whenever totalRows,
+// queryFingerprint, or freshness changes (an $effect keyed on those values
+// is the usual place):
+handle.update({ totalRows, queryFingerprint });
+
+// on unmount:
+handle.destroy();
+```
+
+It mirrors `controller` into the registry, translates visible table commands
+back into `controller.dispatch()` calls, and routes the fixed
+`refresh`/`retry`/`focus`/`reveal`/`highlight` controls to callbacks; any
+other `controlId` goes through an `onControl` escape hatch (denied by
+default) — except a canonical table-control id (`set-filters`, `reset`,
+`set-page`, … the full `DATA_TABLE_SURFACE_CONTROL_IDS` list from
+`@happyvertical/smrt-ui/data`), which is always intercepted first and never
+reaches `onControl`, even under a custom label. See
+`docs/data-surface-conformance.md` for the full contract.
+
 The default prefix is `smrt_ui_`. Configure `ui.prefix` when multiple Providers
 must coexist in one document; the same prefix cannot be registered twice. The
 six derived names are reserved through the document-global tool-name lock, so
@@ -306,7 +344,7 @@ importable, even if it appears in `dist/`.
 | `@happyvertical/smrt-svelte/workspace/live` | `systemFeed` — the AdminShell system scope (jobs/schedules/dispatch) polled from an app status endpoint; deliberately carries no `smrt-web` dependency |
 | `@happyvertical/smrt-svelte/browser-ai` | Browser AI client (STT/TTS/LLM adapters, capability detection) |
 | `@happyvertical/smrt-svelte/browser-ai/svelte` | Svelte AI components (VoiceInput, CapabilityGate, etc.) |
-| `@happyvertical/smrt-svelte/web` | `smrt-web` live-query bindings (`liveCollection`, `activityFeed`, `useUpdateAvailable`) |
+| `@happyvertical/smrt-svelte/web` | `smrt-web` live-query bindings (`liveCollection`, `activityFeed`, `useUpdateAvailable`) plus `mountListDataSurface` (custom-list data-surface registration) |
 | `@happyvertical/smrt-svelte/i18n/server` | Server-side i18n resolver (Node only) |
 
 Domain-agnostic UI lives in `@happyvertical/smrt-ui`. There is no `ui`,

package/dist/web/__tests__/list-data-surface.fixture.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+import type {
+  DataSurfaceDescriptor,
+  DataSurfaceRegistry,
+  DataTableController,
+} from '@happyvertical/smrt-ui/data';
+import {
+  type ListDataSurfaceContext,
+  mountListDataSurface,
+} from '../list-data-surface.svelte.js';
+
+let {
+  registry,
+  descriptor,
+  controller,
+  context,
+  onRefresh,
+  onStar,
+}: {
+  registry: DataSurfaceRegistry;
+  descriptor: DataSurfaceDescriptor;
+  controller: DataTableController;
+  context: ListDataSurfaceContext;
+  onRefresh?: () => boolean | Promise<boolean>;
+  onStar?: (payload: unknown) => boolean;
+} = $props();
+
+let starredCount = $state(0);
+let filterText = $state('');
+
+$effect(() => {
+  const handle = mountListDataSurface({
+    registry,
+    descriptor,
+    controller,
+    context,
+    refresh: onRefresh,
+    onControl: (controlId, payload) => {
+      if (controlId === 'star') {
+        starredCount += 1;
+        return onStar ? onStar(payload) : true;
+      }
+      return false;
+    },
+  });
+  const unsubscribe = controller.subscribe(() => {
+    filterText = String(controller.getState().filters[0]?.value ?? '');
+  });
+  return () => {
+    unsubscribe();
+    handle.destroy();
+  };
+});
+</script>
+
+<ul data-testid="custom-list">
+  <li data-testid="filter-text">{filterText}</li>
+</ul>
+<p data-testid="starred-count">{starredCount}</p>

package/dist/web/__tests__/list-data-surface.fixture.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { DataSurfaceDescriptor, DataSurfaceRegistry, DataTableController } from '@happyvertical/smrt-ui/data';
+import { type ListDataSurfaceContext } from '../list-data-surface.svelte.js';
+type $$ComponentProps = {
+    registry: DataSurfaceRegistry;
+    descriptor: DataSurfaceDescriptor;
+    controller: DataTableController;
+    context: ListDataSurfaceContext;
+    onRefresh?: () => boolean | Promise<boolean>;
+    onStar?: (payload: unknown) => boolean;
+};
+declare const ListDataSurface: import("svelte").Component<$$ComponentProps, {}, "">;
+type ListDataSurface = ReturnType<typeof ListDataSurface>;
+export default ListDataSurface;
+//# sourceMappingURL=list-data-surface.fixture.svelte.d.ts.map

package/dist/web/__tests__/list-data-surface.fixture.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-data-surface.fixture.svelte.d.ts","sourceRoot":"","sources":["../../../src/web/__tests__/list-data-surface.fixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,gCAAgC,CAAC;AAEvC,KAAK,gBAAgB,GAAI;IACxB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,qBAAqB,CAAC;IAClC,UAAU,EAAE,mBAAmB,CAAC;IAChC,OAAO,EAAE,sBAAsB,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;CACxC,CAAC;AAiDF,QAAA,MAAM,eAAe,sDAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/dist/web/__tests__/list-data-surface.svelte.test.js

@@ -0,0 +1,106 @@
+/**
+ * Component-lifecycle proof for `mountListDataSurface` (#2906), in the same
+ * conformance style as `data-surface-conformance.integration.svelte.test.ts`:
+ * a real Svelte component mounts a custom (non-DataTable) list, the registry
+ * drives it with commands, and unmounting the component tears the
+ * registration down. The registration/translation logic itself is unit
+ * tested directly against the registry in `list-data-surface.test.ts`.
+ */
+import { createDataSurfaceRegistry, createDataTableController, } from '@happyvertical/smrt-ui/data';
+import { render, screen } from '@testing-library/svelte';
+import { describe, expect, it, vi } from 'vitest';
+import Fixture from './list-data-surface.fixture.svelte';
+const identity = {
+    surfaceId: 'fixture-list',
+    kind: 'list',
+};
+function descriptor() {
+    return {
+        version: 1,
+        identity,
+        schemaVersion: 1,
+        label: 'Fixture list',
+        rowKey: 'id',
+        columns: [
+            { id: 'id', label: 'ID', capabilities: ['read', 'project'] },
+            {
+                id: 'title',
+                label: 'Title',
+                capabilities: ['read', 'search', 'filter', 'sort', 'project'],
+                operators: { filter: ['contains'] },
+            },
+        ],
+        query: {
+            modes: ['rows', 'count'],
+            projectableColumnIds: ['id', 'title'],
+            filterableColumnIds: ['title'],
+            sortableColumnIds: ['title'],
+        },
+        controls: [
+            { id: 'set-filters', label: 'Filter' },
+            { id: 'refresh', label: 'Refresh' },
+            { id: 'star', label: 'Star selected' },
+        ],
+        actions: [],
+        limits: { maxQueryRows: 50, maxQueryBytes: 10_000, maxSelectionSize: 5 },
+    };
+}
+describe('mountListDataSurface (component integration)', () => {
+    it('drives a mounted custom list from the registry and tears down on unmount', async () => {
+        const registry = createDataSurfaceRegistry();
+        const controller = createDataTableController();
+        const onRefresh = vi.fn().mockResolvedValue(true);
+        const { unmount } = render(Fixture, {
+            props: {
+                registry,
+                descriptor: descriptor(),
+                controller,
+                context: { totalRows: 3, queryFingerprint: 'fixture-1' },
+                onRefresh,
+            },
+        });
+        expect(screen.getByTestId('filter-text').textContent).toBe('');
+        const before = registry.inspect(identity);
+        expect(before?.state.totalRows).toBe(3);
+        const filtered = await registry.execute({
+            version: 1,
+            commandId: 'filter-1',
+            identity,
+            expectedRevision: before?.revision ?? 0,
+            controlId: 'set-filters',
+            payload: {
+                filters: [{ columnId: 'title', operator: 'contains', value: 'draft' }],
+            },
+        });
+        expect(filtered.ok).toBe(true);
+        expect(screen.getByTestId('filter-text').textContent).toBe('draft');
+        const refreshed = await registry.execute({
+            version: 1,
+            commandId: 'refresh-1',
+            identity,
+            expectedRevision: registry.inspect(identity)?.revision ?? 0,
+            controlId: 'refresh',
+        });
+        expect(refreshed.ok).toBe(true);
+        expect(onRefresh).toHaveBeenCalledOnce();
+        const starred = await registry.execute({
+            version: 1,
+            commandId: 'star-1',
+            identity,
+            expectedRevision: registry.inspect(identity)?.revision ?? 0,
+            controlId: 'star',
+        });
+        expect(starred.ok).toBe(true);
+        expect(screen.getByTestId('starred-count').textContent).toBe('1');
+        unmount();
+        // Unmounting tore down the mounted surface — the identity is gone.
+        expect(registry.inspect(identity)).toBeUndefined();
+        await expect(registry.execute({
+            version: 1,
+            commandId: 'after-unmount',
+            identity,
+            expectedRevision: 0,
+            controlId: 'refresh',
+        })).resolves.toMatchObject({ ok: false, reason: 'not_found' });
+    });
+});