@happyvertical/smrt-ui 0.51.38 → 0.52.0

package/dist/components/data/__tests__/list-sort-state.svelte.test.js

@@ -0,0 +1,71 @@
+import { fireEvent, render, screen } from '@testing-library/svelte';
+import { describe, expect, it, vi } from 'vitest';
+import ListSortSelect from '../ListSortSelect.svelte';
+import { createLocalListSort, createUrlListSort, } from '../list-sort-state.svelte.js';
+import SortableHeader from '../SortableHeader.svelte';
+const spec = {
+    columns: [{ id: 'published', firstDirection: 'desc' }, 'title'],
+    default: { columnId: 'published', direction: 'desc' },
+};
+describe('list sort state', () => {
+    it('local: starts at the default and toggles', () => {
+        const list = createLocalListSort(spec);
+        expect(list.sort).toEqual(spec.default);
+        list.toggle('title');
+        expect(list.sort).toEqual({ columnId: 'title', direction: 'asc' });
+        list.toggle('title');
+        expect(list.sort).toEqual({ columnId: 'title', direction: 'desc' });
+        expect(list.href('title')).toBeUndefined();
+    });
+    it('url: reads the URL, links headers, and navigates on set', async () => {
+        let url = new URL('https://x.test/list?sort=title&dir=asc&page=3');
+        const navigate = vi.fn((href) => {
+            url = new URL(href, url);
+        });
+        const list = createUrlListSort(spec, { url: () => url, navigate });
+        expect(list.sort).toEqual({ columnId: 'title', direction: 'asc' });
+        expect(list.href('title')).toBe('/list?sort=title&dir=desc');
+        expect(list.href('published')).toBe('/list');
+        await list.set({ columnId: 'published', direction: 'asc' });
+        expect(navigate).toHaveBeenCalledWith('/list?sort=published&dir=asc');
+    });
+    it('ignores an undeclared column or unknown direction on set', async () => {
+        const local = createLocalListSort(spec);
+        local.set({ columnId: 'secret_score', direction: 'asc' });
+        expect(local.sort).toEqual(spec.default);
+        local.set({ columnId: 'title', direction: 'sideways' });
+        expect(local.sort).toEqual(spec.default);
+        local.set({ columnId: 'title', direction: 'asc' });
+        expect(local.sort).toEqual({ columnId: 'title', direction: 'asc' });
+        // An invalid initial sort starts at the default.
+        expect(createLocalListSort(spec, { columnId: 'nope', direction: 'asc' }).sort).toEqual(spec.default);
+        const navigate = vi.fn();
+        const url = new URL('https://x.test/list');
+        const remote = createUrlListSort(spec, { url: () => url, navigate });
+        await remote.set({ columnId: 'secret_score', direction: 'desc' });
+        await remote.set(null);
+        expect(navigate).not.toHaveBeenCalled();
+    });
+    it('drives SortableHeader and ListSortSelect through `list`', async () => {
+        const list = createLocalListSort(spec);
+        render(SortableHeader, {
+            props: { list, columnId: 'title', label: 'Title', as: 'div' },
+        });
+        const header = screen.getByRole('columnheader');
+        expect(header.getAttribute('aria-sort')).toBe('none');
+        await fireEvent.click(screen.getByRole('button', { name: 'Sort by Title, ascending' }));
+        expect(list.sort).toEqual({ columnId: 'title', direction: 'asc' });
+        render(ListSortSelect, {
+            props: {
+                list,
+                columns: [
+                    { id: 'published', label: 'Published', kind: 'date' },
+                    { id: 'title', label: 'Title' },
+                ],
+            },
+        });
+        const select = screen.getByLabelText('Sort by');
+        await fireEvent.change(select, { target: { value: 'published:desc' } });
+        expect(list.sort).toEqual(spec.default);
+    });
+});

package/dist/components/data/__tests__/list-sort.test.js

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { compareListValues, isValidListSort, listSortAria, listSortHref, listSortOrderBy, listSortSearchParams, parseListSort, sortListRows, toggleListSort, } from '../list-sort.js';
+const spec = {
+    columns: [
+        { id: 'published', firstDirection: 'desc' },
+        'title',
+        { id: 'views', firstDirection: 'desc' },
+    ],
+    default: { columnId: 'published', direction: 'desc' },
+};
+describe('list sort', () => {
+    it('parses the URL, falling back to the default for unknown values', () => {
+        expect(parseListSort(new URLSearchParams(''), spec)).toEqual(spec.default);
+        expect(parseListSort(new URLSearchParams('sort=title&dir=desc'), spec)).toEqual({
+            columnId: 'title',
+            direction: 'desc',
+        });
+        expect(parseListSort(new URLSearchParams('sort=title'), spec)).toEqual({
+            columnId: 'title',
+            direction: 'asc',
+        });
+        expect(parseListSort(new URLSearchParams('sort=views'), spec)).toEqual({
+            columnId: 'views',
+            direction: 'desc',
+        });
+        expect(parseListSort(new URLSearchParams('sort=password&dir=asc'), spec)).toEqual(spec.default);
+        expect(parseListSort(new URLSearchParams('dir=asc'), spec)).toEqual({
+            columnId: 'published',
+            direction: 'asc',
+        });
+        expect(parseListSort(new URLSearchParams('sort=title&dir=sideways'), spec)).toEqual({
+            columnId: 'title',
+            direction: 'asc',
+        });
+    });
+    it('toggles asc/desc and starts a new column at its first direction', () => {
+        const start = spec.default;
+        expect(toggleListSort(start, 'published', spec)).toEqual({
+            columnId: 'published',
+            direction: 'asc',
+        });
+        expect(toggleListSort({ columnId: 'published', direction: 'asc' }, 'published', spec)).toEqual(start);
+        expect(toggleListSort(start, 'title', spec)).toEqual({
+            columnId: 'title',
+            direction: 'asc',
+        });
+        expect(toggleListSort(start, 'views', spec)).toEqual({
+            columnId: 'views',
+            direction: 'desc',
+        });
+        expect(toggleListSort(start, 'nope', spec)).toBe(start);
+        expect(isValidListSort(spec, { columnId: 'nope', direction: 'asc' })).toBe(false);
+    });
+    it('writes the sort to the URL, omits the default, and resets the page', () => {
+        const params = listSortSearchParams('status=draft&page=3', { columnId: 'title', direction: 'asc' }, spec);
+        expect(params.toString()).toBe('status=draft&sort=title&dir=asc');
+        expect(listSortSearchParams('sort=title&dir=asc&page=2', spec.default, spec).toString()).toBe('');
+        expect(listSortSearchParams('sort=title&dir=asc&page=2', { columnId: 'title', direction: 'asc' }, spec).toString()).toBe('sort=title&dir=asc&page=2');
+        expect(listSortHref(new URL('https://x.test/a?page=2'), { columnId: 'views', direction: 'desc' }, spec)).toBe('/a?sort=views&dir=desc');
+        expect(listSortHref(new URL('https://x.test/a?page=2'), spec.default, spec)).toBe('/a?page=2');
+    });
+    it('reports aria-sort', () => {
+        expect(listSortAria(spec.default, 'published')).toBe('descending');
+        expect(listSortAria({ columnId: 'title', direction: 'asc' }, 'title')).toBe('ascending');
+        expect(listSortAria(spec.default, 'title')).toBe('none');
+    });
+    it('sorts rows stably with empty values last in both directions', () => {
+        const rows = [
+            { id: 1, at: '2026-01-02' },
+            { id: 2, at: null },
+            { id: 3, at: '2026-03-01' },
+            { id: 4, at: '2026-01-02' },
+        ];
+        const value = (row) => row.at;
+        expect(sortListRows(rows, { columnId: 'at', direction: 'desc' }, value).map((r) => r.id)).toEqual([3, 1, 4, 2]);
+        expect(sortListRows(rows, { columnId: 'at', direction: 'asc' }, value).map((r) => r.id)).toEqual([1, 4, 3, 2]);
+        expect(compareListValues('item 2', 'item 10', 'asc')).toBeLessThan(0);
+        expect(compareListValues(new Date('2026-01-01'), new Date('2025-01-01'), 'desc')).toBeLessThan(0);
+    });
+    it('builds ORDER BY only from the allow-list', () => {
+        const map = {
+            published: 'COALESCE(c.publish_date, c.created_at)',
+            title: 'c.title',
+        };
+        expect(listSortOrderBy(spec.default, map)).toBe('COALESCE(c.publish_date, c.created_at) DESC NULLS LAST');
+        expect(listSortOrderBy({ columnId: 'title', direction: 'asc' }, map, {
+            nulls: false,
+        })).toBe('c.title ASC');
+        expect(() => listSortOrderBy({ columnId: 'title; drop', direction: 'asc' }, map)).toThrow();
+    });
+});

package/dist/components/data/__tests__/surface-navigation.test.js

@@ -0,0 +1,121 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createDataSurfaceRegistry } from '../data-surface.js';
+import { registerLinkSurface } from '../link-surface.js';
+import { hasPendingSurfaceNavigation, trackSurfaceNavigation, whenSurfaceNavigationSettled, } from '../surface-navigation.js';
+const links = [{ id: 'events', label: 'Events', href: '/s/events' }];
+function deferred() {
+    let resolve;
+    const promise = new Promise((r) => {
+        resolve = r;
+    });
+    return { promise, resolve };
+}
+function openCommand(revision = 1) {
+    return {
+        version: 1,
+        commandId: `open-${Math.random()}`,
+        identity: { surfaceId: 'site-sections', kind: 'list' },
+        expectedRevision: revision,
+        controlId: 'open',
+        payload: { target: 'Events' },
+    };
+}
+describe('whenSurfaceNavigationSettled', () => {
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('waits for a link surface navigation and the new page to register', async () => {
+        const registry = createDataSurfaceRegistry();
+        const navigation = deferred();
+        registerLinkSurface({
+            registry,
+            surfaceId: 'site-sections',
+            label: 'Site sections',
+            description: 'Pages',
+            links,
+            navigate: () => navigation.promise,
+        });
+        const result = await registry.execute(openCommand());
+        // The command answers at once; the page change is still running.
+        expect(result.ok).toBe(true);
+        expect(hasPendingSurfaceNavigation(registry)).toBe(true);
+        let settled = false;
+        const waiting = whenSurfaceNavigationSettled(registry, {
+            quietMs: 20,
+        }).then(() => {
+            settled = true;
+        });
+        await new Promise((r) => setTimeout(r, 30));
+        expect(settled).toBe(false);
+        // The new page mounts its surface as the navigation finishes.
+        navigation.resolve();
+        await Promise.resolve();
+        registry.register({
+            descriptor: {
+                version: 1,
+                identity: { surfaceId: 'events', kind: 'list' },
+                schemaVersion: 1,
+                label: 'Events',
+                rowKey: 'id',
+                columns: [
+                    { id: 'id', label: 'ID', capabilities: ['read'], role: 'row-key' },
+                ],
+                query: { modes: ['rows'], projectableColumnIds: ['id'] },
+                controls: [],
+                actions: [],
+                limits: { maxQueryRows: 1, maxQueryBytes: 1000, maxSelectionSize: 1 },
+            },
+            getSnapshot: () => ({ revision: 1, state: {}, selection: null }),
+        });
+        await waiting;
+        expect(settled).toBe(true);
+        expect(hasPendingSurfaceNavigation(registry)).toBe(false);
+    });
+    it('resolves after a quiet period when nothing navigates', async () => {
+        const registry = createDataSurfaceRegistry();
+        const started = Date.now();
+        await whenSurfaceNavigationSettled(registry, { quietMs: 10 });
+        expect(Date.now() - started).toBeLessThan(1_000);
+    });
+    it('gives up after the timeout, and a failed navigation still settles', async () => {
+        const registry = createDataSurfaceRegistry();
+        void trackSurfaceNavigation(registry, new Promise(() => { }));
+        const started = Date.now();
+        await whenSurfaceNavigationSettled(registry, {
+            quietMs: 5,
+            timeoutMs: 40,
+        });
+        expect(Date.now() - started).toBeLessThan(1_000);
+        const other = createDataSurfaceRegistry();
+        const failing = trackSurfaceNavigation(other, Promise.reject(new Error('nope')));
+        await expect(failing).rejects.toThrow('nope');
+        await whenSurfaceNavigationSettled(other, { quietMs: 5 });
+        expect(hasPendingSurfaceNavigation(other)).toBe(false);
+    });
+    it('keeps waiting while a watched source keeps changing', async () => {
+        const registry = createDataSurfaceRegistry();
+        const listeners = new Set();
+        const tools = {
+            subscribe(listener) {
+                listeners.add(listener);
+                return () => listeners.delete(listener);
+            },
+        };
+        let settled = false;
+        const waiting = whenSurfaceNavigationSettled(registry, {
+            quietMs: 30,
+            alsoWatch: [tools],
+        }).then(() => {
+            settled = true;
+        });
+        for (let i = 0; i < 3; i += 1) {
+            await new Promise((r) => setTimeout(r, 15));
+            for (const listener of listeners)
+                listener({ type: 'registered' });
+        }
+        expect(settled).toBe(false);
+        await waiting;
+        expect(settled).toBe(true);
+        expect(listeners.size).toBe(0);
+    });
+});

package/dist/components/data/data-surface.d.ts

@@ -21,4 +21,5 @@ export declare function normalizeDataSurfaceQueryRequest(value: DataSurfaceQuery
 export declare function normalizeDataSurfaceActionRequest(value: DataSurfaceActionRequest): DataSurfaceActionRequest;
 /** Create an isolated registry; applications choose how it is exposed. */
 export declare function createDataSurfaceRegistry(): DataSurfaceRegistry;
+export * from './surface-navigation.js';
 //# sourceMappingURL=data-surface.d.ts.map

package/dist/components/data/data-surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-surface.d.ts","sourceRoot":"","sources":["../../../src/components/data/data-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,wBAAwB,EAOxB,qBAAqB,EAMrB,uBAAuB,EAEvB,mBAAmB,EAMnB,mBAAmB,EAGnB,yBAAyB,EAC1B,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,2BAA2B,EAC3B,2BAA2B,EAC3B,+BAA+B,EAC/B,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,4BAA4B,EAC5B,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,6BAA6B,EAC7B,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAEnC,iFAAiF;AACjF,eAAO,MAAM,8BAA8B,SAAU,CAAC;AAEtD,sEAAsE;AACtE,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD,mEAAmE;AACnE,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAypBnD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,qBAAqB,GAC3B,qBAAqB,CAgSvB;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,mBAAmB,GACzB,mBAAmB,CAsBrB;AAED,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,yBAAyB,GAC/B,yBAAyB,CAoC3B;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,uBAAuB,GAC7B,uBAAuB,CA+FzB;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,wBAAwB,GAC9B,wBAAwB,CAmD1B;AAmED,0EAA0E;AAC1E,wBAAgB,yBAAyB,IAAI,mBAAmB,CAka/D"}
+{"version":3,"file":"data-surface.d.ts","sourceRoot":"","sources":["../../../src/components/data/data-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,wBAAwB,EAOxB,qBAAqB,EAMrB,uBAAuB,EAEvB,mBAAmB,EAMnB,mBAAmB,EAGnB,yBAAyB,EAC1B,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,4BAA4B,EAC5B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,qBAAqB,EACrB,2BAA2B,EAC3B,2BAA2B,EAC3B,+BAA+B,EAC/B,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,4BAA4B,EAC5B,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,6BAA6B,EAC7B,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAEnC,iFAAiF;AACjF,eAAO,MAAM,8BAA8B,SAAU,CAAC;AAEtD,sEAAsE;AACtE,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD,mEAAmE;AACnE,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAypBnD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,qBAAqB,GAC3B,qBAAqB,CAgSvB;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,mBAAmB,GACzB,mBAAmB,CAsBrB;AAED,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,yBAAyB,GAC/B,yBAAyB,CAoC3B;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,uBAAuB,GAC7B,uBAAuB,CA+FzB;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,wBAAwB,GAC9B,wBAAwB,CAmD1B;AAmED,0EAA0E;AAC1E,wBAAgB,yBAAyB,IAAI,mBAAmB,CAka/D;AACD,cAAc,yBAAyB,CAAC"}

package/dist/components/data/data-surface.js

@@ -1259,3 +1259,4 @@ export function createDataSurfaceRegistry() {
         },
     };
 }
+export * from './surface-navigation.js';

package/dist/components/data/index.d.ts

@@ -10,5 +10,11 @@ export * from './DataTablePerformance.js';
 export * from './DataTableVirtualization.js';
 export * from './data-surface.js';
 export * from './data-table-surface.js';
+export { default as ListSortSelect } from './ListSortSelect.svelte';
+export * from './link-surface.js';
+export * from './list-sort.js';
+export * from './list-sort-state.svelte.js';
+export { default as SortableHeader } from './SortableHeader.svelte';
+export * from './step-surface.js';
 export * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/data/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/data/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,OAAO,IAAI,cAAc,EACzB,OAAO,IAAI,WAAW,GACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC1D,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/data/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,OAAO,IAAI,cAAc,EACzB,OAAO,IAAI,WAAW,GACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC1D,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACpE,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACpE,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/dist/components/data/index.js

@@ -10,4 +10,10 @@ export * from './DataTablePerformance.js';
 export * from './DataTableVirtualization.js';
 export * from './data-surface.js';
 export * from './data-table-surface.js';
+export { default as ListSortSelect } from './ListSortSelect.svelte';
+export * from './link-surface.js';
+export * from './list-sort.js';
+export * from './list-sort-state.svelte.js';
+export { default as SortableHeader } from './SortableHeader.svelte';
+export * from './step-surface.js';
 export * from './types.js';

package/dist/components/data/link-surface.d.ts

@@ -0,0 +1,79 @@
+/**
+ * A navigation list (a menu, a tab row, a section list) as a mounted data
+ * surface, so an agent can move a person between pages without a REST path.
+ *
+ * A view intent can only dispatch a registry command, so "go to page X" needs
+ * a mounted surface whose visible control performs the navigation. This
+ * registers one: the links are published in the snapshot state
+ * (`state.links`: id, label, description, group — never an href an agent
+ * could steer), and each declared control resolves its payload to one of
+ * those links (or to a caller-built href) and hands it to `navigate`.
+ *
+ * Navigation is a read-only view-state change: nothing is created or changed.
+ */
+import type { DataSurfaceDescriptor, DataSurfaceJsonValue, DataSurfaceKind, DataSurfaceRegistry, DataSurfaceSubject } from '@happyvertical/smrt-types';
+export interface LinkSurfaceItem {
+    /** Stable id, e.g. the nav item or tab id. */
+    id: string;
+    /** Plain label a person sees in the menu. */
+    label: string;
+    href: string;
+    description?: string;
+    /** Group or section heading the link sits under, if any. */
+    group?: string;
+}
+export interface LinkSurfaceControl {
+    id: string;
+    label: string;
+    description?: string;
+    /**
+     * Resolve a command payload to an href, or `null` to refuse. Defaults to
+     * {@link resolveLinkTarget} over the published links.
+     */
+    resolve?: (payload: DataSurfaceJsonValue | undefined, links: readonly LinkSurfaceItem[]) => string | null;
+}
+export interface LinkSurfaceOptions {
+    registry: DataSurfaceRegistry;
+    surfaceId: string;
+    kind?: DataSurfaceKind;
+    subject?: DataSurfaceSubject;
+    label: string;
+    description: string;
+    links: readonly LinkSurfaceItem[];
+    /** Defaults to one `open` control over the published links. */
+    controls?: readonly LinkSurfaceControl[];
+    /**
+     * Perform the navigation. Return its promise (e.g. SvelteKit's `goto`):
+     * the command does not wait for it, since the new page may unmount this
+     * surface, but it is tracked on the registry, so
+     * `whenSurfaceNavigationSettled(registry)` resolves only once it finished
+     * and the new page's surfaces registered.
+     */
+    navigate: (href: string) => unknown;
+    /** Extra JSON state published alongside the links (e.g. the active id). */
+    state?: Record<string, DataSurfaceJsonValue>;
+}
+export interface LinkSurfaceHandle {
+    update(next: {
+        links?: readonly LinkSurfaceItem[];
+        state?: Record<string, DataSurfaceJsonValue>;
+    }): void;
+    destroy(): void;
+}
+/** Cap on published links (and the surface's query limit). */
+export declare const LINK_SURFACE_MAX_LINKS = 200;
+/**
+ * The string an agent passed: `"Events"` or `{ target: "Events" }` (also
+ * `id` / `label` / `section` / `tab` / `page`).
+ */
+export declare function linkTargetFromPayload(payload: DataSurfaceJsonValue | undefined): string | null;
+/**
+ * Resolve a payload to one link's href: by id, then exact label, then a unique
+ * label prefix, all case-insensitive. Ambiguity resolves to `null`.
+ */
+export declare function resolveLinkTarget(payload: DataSurfaceJsonValue | undefined, links: readonly LinkSurfaceItem[]): string | null;
+/** The descriptor {@link registerLinkSurface} mounts. */
+export declare function linkSurfaceDescriptor(options: Pick<LinkSurfaceOptions, 'surfaceId' | 'kind' | 'subject' | 'label' | 'description' | 'controls'>): DataSurfaceDescriptor;
+/** Mount a navigation list on a data-surface registry. */
+export declare function registerLinkSurface(options: LinkSurfaceOptions): LinkSurfaceHandle;
+//# sourceMappingURL=link-surface.d.ts.map

package/dist/components/data/link-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-surface.d.ts","sourceRoot":"","sources":["../../../src/components/data/link-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAEnB,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,CACR,OAAO,EAAE,oBAAoB,GAAG,SAAS,EACzC,KAAK,EAAE,SAAS,eAAe,EAAE,KAC9B,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,IAAI,EAAE;QACX,KAAK,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;QACnC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;KAC9C,GAAG,IAAI,CAAC;IACT,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAe1C;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,oBAAoB,GAAG,SAAS,GACxC,MAAM,GAAG,IAAI,CASf;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,GAAG,SAAS,EACzC,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,MAAM,GAAG,IAAI,CAaf;AAaD,yDAAyD;AACzD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,IAAI,CACX,kBAAkB,EAClB,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,GAAG,UAAU,CACxE,GACA,qBAAqB,CAqCvB;AAED,0DAA0D;AAC1D,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,kBAAkB,GAC1B,iBAAiB,CAiDnB"}

package/dist/components/data/link-surface.js

@@ -0,0 +1,155 @@
+/**
+ * A navigation list (a menu, a tab row, a section list) as a mounted data
+ * surface, so an agent can move a person between pages without a REST path.
+ *
+ * A view intent can only dispatch a registry command, so "go to page X" needs
+ * a mounted surface whose visible control performs the navigation. This
+ * registers one: the links are published in the snapshot state
+ * (`state.links`: id, label, description, group — never an href an agent
+ * could steer), and each declared control resolves its payload to one of
+ * those links (or to a caller-built href) and hands it to `navigate`.
+ *
+ * Navigation is a read-only view-state change: nothing is created or changed.
+ */
+import { trackSurfaceNavigation } from './surface-navigation.js';
+/** Cap on published links (and the surface's query limit). */
+export const LINK_SURFACE_MAX_LINKS = 200;
+const DEFAULT_CONTROLS = [
+    {
+        id: 'open',
+        label: 'Open',
+        description: 'Go to one of the listed pages. Payload: { target } — a link id or its label.',
+    },
+];
+function normalize(value) {
+    return value.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+/**
+ * The string an agent passed: `"Events"` or `{ target: "Events" }` (also
+ * `id` / `label` / `section` / `tab` / `page`).
+ */
+export function linkTargetFromPayload(payload) {
+    if (typeof payload === 'string')
+        return payload.trim() ? payload : null;
+    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+        for (const key of ['target', 'id', 'label', 'section', 'tab', 'page']) {
+            const value = payload[key];
+            if (typeof value === 'string' && value.trim())
+                return value;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a payload to one link's href: by id, then exact label, then a unique
+ * label prefix, all case-insensitive. Ambiguity resolves to `null`.
+ */
+export function resolveLinkTarget(payload, links) {
+    const target = linkTargetFromPayload(payload);
+    if (!target)
+        return null;
+    const wanted = normalize(target);
+    const byId = links.find((link) => normalize(link.id) === wanted);
+    if (byId)
+        return byId.href;
+    const byLabel = links.filter((link) => normalize(link.label) === wanted);
+    if (byLabel.length === 1)
+        return byLabel[0].href;
+    if (byLabel.length > 1)
+        return null;
+    const byPrefix = links.filter((link) => normalize(link.label).startsWith(wanted));
+    return byPrefix.length === 1 ? byPrefix[0].href : null;
+}
+function publishedLinks(links) {
+    return links.slice(0, LINK_SURFACE_MAX_LINKS).map((link) => ({
+        id: link.id,
+        label: link.label,
+        ...(link.description ? { description: link.description } : {}),
+        ...(link.group ? { group: link.group } : {}),
+    }));
+}
+/** The descriptor {@link registerLinkSurface} mounts. */
+export function linkSurfaceDescriptor(options) {
+    const columns = [
+        { id: 'id', label: 'ID', capabilities: ['read'], role: 'row-key' },
+        { id: 'label', label: 'Name', capabilities: ['read'] },
+        { id: 'description', label: 'About', capabilities: ['read'] },
+        { id: 'group', label: 'Group', capabilities: ['read'] },
+    ];
+    return {
+        version: 1,
+        identity: {
+            kind: options.kind ?? 'list',
+            surfaceId: options.surfaceId,
+            ...(options.subject ? { subject: options.subject } : {}),
+        },
+        schemaVersion: 1,
+        label: options.label,
+        description: options.description,
+        rowKey: 'id',
+        columns,
+        query: {
+            modes: ['rows'],
+            projectableColumnIds: columns.map((column) => column.id),
+            filterableColumnIds: [],
+            sortableColumnIds: [],
+        },
+        controls: (options.controls ?? DEFAULT_CONTROLS).map((control) => ({
+            id: control.id,
+            label: control.label,
+            ...(control.description ? { description: control.description } : {}),
+        })),
+        actions: [],
+        limits: {
+            maxQueryRows: LINK_SURFACE_MAX_LINKS,
+            maxQueryBytes: 200_000,
+            maxSelectionSize: 1,
+        },
+    };
+}
+/** Mount a navigation list on a data-surface registry. */
+export function registerLinkSurface(options) {
+    let links = [...options.links];
+    let extraState = { ...(options.state ?? {}) };
+    let revision = 1;
+    const controls = new Map((options.controls ?? DEFAULT_CONTROLS).map((control) => [
+        control.id,
+        control,
+    ]));
+    const dispose = options.registry.register({
+        descriptor: linkSurfaceDescriptor(options),
+        getSnapshot: () => ({
+            revision,
+            state: { ...extraState, links: publishedLinks(links) },
+            selection: null,
+        }),
+        execute: (command) => {
+            const control = controls.get(command.controlId);
+            if (!control)
+                return { ok: false };
+            const href = (control.resolve ?? resolveLinkTarget)(command.payload, links);
+            if (!href)
+                return { ok: false };
+            void trackSurfaceNavigation(options.registry, options.navigate(href));
+            return undefined;
+        },
+    });
+    return {
+        update(next) {
+            const nextLinks = next.links ? [...next.links] : links;
+            const nextState = next.state ? { ...next.state } : extraState;
+            const changed = JSON.stringify(publishedLinks(nextLinks)) !==
+                JSON.stringify(publishedLinks(links)) ||
+                JSON.stringify(nextState) !== JSON.stringify(extraState) ||
+                nextLinks.length !== links.length ||
+                nextLinks.some((link, index) => link.href !== links[index]?.href);
+            links = nextLinks;
+            extraState = nextState;
+            if (changed)
+                revision += 1;
+        },
+        destroy() {
+            dispose();
+        },
+    };
+}

package/dist/components/data/list-sort-state.svelte.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reactive list-sort state for pages — the one object a list's headers
+ * (`SortableHeader list={...}`), phone picker (`ListSortSelect list={...}`),
+ * rows (`sortListRows(rows, list.sort, ...)`), and data surface (`sort` /
+ * `onSort`) share. Call during component initialisation.
+ *
+ * - `createUrlListSort(spec, { url, navigate })` — server-paginated lists:
+ *   the sort lives in the URL (`?sort=&dir=`); headers are links, and `set`
+ *   navigates. Framework-agnostic: pass the router's current URL and its
+ *   navigate function (SvelteKit: `() => page.url` and `goto`).
+ * - `createLocalListSort(spec)` — lists that load every row: page state.
+ */
+import { type ListSort, type ListSortSpec } from './list-sort.js';
+export interface ListSortState {
+    readonly sort: ListSort;
+    readonly spec: ListSortSpec;
+    /** Link to the list after activating `columnId`'s header (URL lists only). */
+    href(columnId: string): string | undefined;
+    /** Activate a header: toggle `columnId` (URL lists: the link navigates). */
+    toggle(columnId: string): void | Promise<void>;
+    /**
+     * Apply a sort (headers, the "Sort by" picker, agents). A sort naming an
+     * undeclared column or an unknown direction is ignored.
+     */
+    set(sort: ListSort): void | Promise<void>;
+}
+export interface UrlListSortOptions {
+    /** The current URL (reactive, e.g. SvelteKit's `page.url`). */
+    url: () => URL | {
+        pathname: string;
+        search: string;
+        searchParams: URLSearchParams;
+    };
+    /** Navigate to a same-page href (keep focus and scroll, replace history). */
+    navigate: (href: string) => void | Promise<void>;
+}
+export declare function createUrlListSort(spec: ListSortSpec, options: UrlListSortOptions): ListSortState;
+export declare function createLocalListSort(spec: ListSortSpec, initial?: ListSort): ListSortState;
+//# sourceMappingURL=list-sort-state.svelte.d.ts.map

package/dist/components/data/list-sort-state.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-sort-state.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/data/list-sort-state.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,YAAY,EAIlB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,8EAA8E;IAC9E,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC3C,4EAA4E;IAC5E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,GAAG,EAAE,MACD,GAAG,GACH;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,eAAe,CAAA;KAAE,CAAC;IACxE,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,kBAAkB,GAC1B,aAAa,CAef;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,QAAQ,GACjB,aAAa,CAkBf"}