@happyvertical/smrt-ui 0.51.39 → 0.52.0

package/dist/components/data/SortableHeader.svelte

@@ -0,0 +1,169 @@
+<!--
+  SortableHeader — a sortable column header for a hand-rolled table.
+
+  Renders the `<th>` itself so `aria-sort` sits on the column header. The
+  control inside is a link when `href` is given (server-sorted lists keep the
+  sort in the URL; build it with `listSortHref`) or a button calling `onSort`
+  (client-sorted lists; compute the next sort with `toggleListSort`) — or
+  pass a list's state (`createUrlListSort` / `createLocalListSort`) as `list`
+  and it supplies all three. Both are
+  reachable by Tab and activated with Enter (a button also with Space). The
+  indicator shows ↑/↓ on the sorted column and a faint ↕ on the others.
+
+  Use `as="div"` with `role="columnheader"` semantics for grid layouts that
+  are not a `<table>`.
+
+  Style hooks (set on the header or an ancestor): `--sortable-header-padding`
+  (the control's padding) and `--sortable-header-font-weight` (default 600;
+  `inherit` takes the surrounding head row's weight).
+-->
+<script lang="ts">
+import type { Snippet } from 'svelte';
+import {
+  type ListSort,
+  type ListSortSpec,
+  listSortActionLabel,
+  listSortAria,
+} from './list-sort.js';
+import type { ListSortState } from './list-sort-state.svelte.js';
+
+interface Props {
+  /** Id of the column this header sorts by. */
+  columnId: string;
+  /** Column name shown in the header and used in the sort announcement. */
+  label: string;
+  /** The list's sort state; supplies `sort`, `spec`, `href`, and `onSort`. */
+  list?: ListSortState;
+  /** Current sort of the list. */
+  sort?: ListSort | null;
+  /** Link to the list sorted by this column (server-sorted lists). */
+  href?: string;
+  /** Called on activation (client-sorted lists). */
+  onSort?: (columnId: string) => void;
+  /** The list's sort spec; gives the column's first direction for the label. */
+  spec?: ListSortSpec;
+  /** Render a table `th` (default) or a `div` column header for grid layouts. */
+  as?: 'th' | 'div';
+  /** Horizontal alignment of the header content. */
+  align?: 'start' | 'center' | 'end';
+  /** Extra class names. */
+  class?: string;
+  children?: Snippet;
+}
+
+let {
+  columnId,
+  label,
+  list,
+  sort: sortProp,
+  href: hrefProp,
+  onSort: onSortProp,
+  spec: specProp,
+  as = 'th',
+  align = 'start',
+  class: className = '',
+  children,
+}: Props = $props();
+
+const sort = $derived(list ? list.sort : sortProp);
+const spec = $derived(list ? list.spec : specProp);
+const href = $derived(list ? list.href(columnId) : hrefProp);
+const onSort = $derived(
+  list ? (id: string) => void list.toggle(id) : onSortProp,
+);
+const aria = $derived(listSortAria(sort, columnId));
+const active = $derived(aria !== 'none');
+const actionLabel = $derived(listSortActionLabel(sort, columnId, label, spec));
+</script>
+
+{#snippet content()}
+  <span class="sortable-header__label">
+    {#if children}{@render children()}{:else}{label}{/if}
+  </span>
+  <span class="sortable-header__icon" class:is-active={active} aria-hidden="true">
+    {#if aria === 'ascending'}↑{:else if aria === 'descending'}↓{:else}↕{/if}
+  </span>
+{/snippet}
+
+<svelte:element
+  this={as}
+  class={`sortable-header sortable-header--${align} ${className}`}
+  class:is-sorted={active}
+  scope={as === 'th' ? 'col' : undefined}
+  role={as === 'div' ? 'columnheader' : undefined}
+  aria-sort={aria}
+  data-sort-column={columnId}
+>
+  {#if href}
+    <a
+      class="sortable-header__control"
+      {href}
+      aria-label={actionLabel}
+      data-sveltekit-noscroll
+      data-sveltekit-keepfocus
+      data-sveltekit-replacestate
+      onclick={() => onSort?.(columnId)}
+    >
+      {@render content()}
+    </a>
+  {:else}
+    <button
+      type="button"
+      class="sortable-header__control"
+      aria-label={actionLabel}
+      onclick={() => onSort?.(columnId)}
+    >
+      {@render content()}
+    </button>
+  {/if}
+</svelte:element>
+
+<style>
+  .sortable-header {
+    padding: 0;
+    font-weight: inherit;
+    text-align: start;
+  }
+  .sortable-header--center {
+    text-align: center;
+  }
+  .sortable-header--end {
+    text-align: end;
+  }
+  .sortable-header__control {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25rem;
+    min-height: 2.75rem;
+    width: 100%;
+    padding: var(--sortable-header-padding, 0.5rem 0.75rem);
+    border: 0;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    font-weight: var(--sortable-header-font-weight, 600);
+    text-align: inherit;
+    text-decoration: none;
+    cursor: pointer;
+  }
+  .sortable-header--center .sortable-header__control {
+    justify-content: center;
+  }
+  .sortable-header--end .sortable-header__control {
+    justify-content: flex-end;
+  }
+  .sortable-header__control:hover .sortable-header__label {
+    text-decoration: underline;
+  }
+  .sortable-header__control:focus-visible {
+    outline: 2px solid var(--color-focus, var(--color-primary, currentColor));
+    outline-offset: -2px;
+  }
+  .sortable-header__icon {
+    opacity: 0.35;
+    font-size: 0.85em;
+  }
+  .sortable-header__icon.is-active {
+    opacity: 1;
+  }
+</style>

package/dist/components/data/SortableHeader.svelte.d.ts

@@ -0,0 +1,30 @@
+import type { Snippet } from 'svelte';
+import { type ListSort, type ListSortSpec } from './list-sort.js';
+import type { ListSortState } from './list-sort-state.svelte.js';
+interface Props {
+    /** Id of the column this header sorts by. */
+    columnId: string;
+    /** Column name shown in the header and used in the sort announcement. */
+    label: string;
+    /** The list's sort state; supplies `sort`, `spec`, `href`, and `onSort`. */
+    list?: ListSortState;
+    /** Current sort of the list. */
+    sort?: ListSort | null;
+    /** Link to the list sorted by this column (server-sorted lists). */
+    href?: string;
+    /** Called on activation (client-sorted lists). */
+    onSort?: (columnId: string) => void;
+    /** The list's sort spec; gives the column's first direction for the label. */
+    spec?: ListSortSpec;
+    /** Render a table `th` (default) or a `div` column header for grid layouts. */
+    as?: 'th' | 'div';
+    /** Horizontal alignment of the header content. */
+    align?: 'start' | 'center' | 'end';
+    /** Extra class names. */
+    class?: string;
+    children?: Snippet;
+}
+declare const SortableHeader: import("svelte").Component<Props, {}, "">;
+type SortableHeader = ReturnType<typeof SortableHeader>;
+export default SortableHeader;
+//# sourceMappingURL=SortableHeader.svelte.d.ts.map

package/dist/components/data/SortableHeader.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SortableHeader.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/data/SortableHeader.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,YAAY,EAGlB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGjE,UAAU,KAAK;IACb,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,gCAAgC;IAChC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,8EAA8E;IAC9E,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,+EAA+E;IAC/E,EAAE,CAAC,EAAE,IAAI,GAAG,KAAK,CAAC;IAClB,kDAAkD;IAClD,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IACnC,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA0DD,QAAA,MAAM,cAAc,2CAAwC,CAAC;AAC7D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AACxD,eAAe,cAAc,CAAC"}

package/dist/components/data/__tests__/CollectionList.test.js

@@ -0,0 +1,37 @@
+import { render, screen } from '@testing-library/svelte';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+import CollectionList from '../CollectionList.svelte';
+const items = [
+    { id: 'a', title: 'First' },
+    { id: 'b', title: 'Second' },
+];
+describe('CollectionList', () => {
+    it.each([
+        'list',
+        'divided',
+        'grid',
+        'gallery',
+    ])('renders the %s layout', (layout) => {
+        const { container } = render(CollectionList, {
+            props: { items, itemKey: 'id', title: 'title', layout },
+        });
+        expect(container.querySelector(`ul.collection--${layout}`)).not.toBeNull();
+        expect(screen.getByText('First')).toBeInTheDocument();
+    });
+    it('selects an item with its labelled checkbox', async () => {
+        const onselectionchange = vi.fn();
+        render(CollectionList, {
+            props: {
+                items,
+                itemKey: 'id',
+                title: 'title',
+                layout: 'gallery',
+                selectable: true,
+                onselectionchange,
+            },
+        });
+        await userEvent.click(screen.getByRole('checkbox', { name: 'Select Second' }));
+        expect(onselectionchange).toHaveBeenCalledWith(new Set(['b']));
+    });
+});

package/dist/components/data/__tests__/DataTable.test.js

@@ -53,6 +53,35 @@ describe('DataTable', () => {
         await userEvent.click(screen.getByRole('button', { name: 'Clear sorting for Name' }));
         expect(nameHeader).not.toHaveAttribute('aria-sort');
     });
+    it('starts a date/count column descending and toggles without clearing when not clearable', async () => {
+        render(DataTable, {
+            props: {
+                data,
+                columns: [
+                    columns[0],
+                    {
+                        id: 'age',
+                        label: 'Age',
+                        accessor: 'age',
+                        sortable: true,
+                        sortFirstDirection: 'desc',
+                    },
+                ],
+                sortable: true,
+                sortClearable: false,
+            },
+        });
+        const ageHeader = screen.getByRole('columnheader', { name: 'Age' });
+        await userEvent.click(screen.getByRole('button', { name: 'Sort Age descending' }));
+        expect(ageHeader).toHaveAttribute('aria-sort', 'descending');
+        const firstCell = () => screen.getAllByRole('row')[1]?.textContent ?? '';
+        expect(firstCell()).toContain('Linus');
+        await userEvent.click(screen.getByRole('button', { name: 'Sort Age ascending' }));
+        expect(ageHeader).toHaveAttribute('aria-sort', 'ascending');
+        expect(firstCell()).toContain('Ada');
+        await userEvent.click(screen.getByRole('button', { name: 'Sort Age descending' }));
+        expect(ageHeader).toHaveAttribute('aria-sort', 'descending');
+    });
     it('announces the next action for each rule in a multi-column sort', async () => {
         const multiSortColumns = [columns[0], { ...columns[1], sortable: true }];
         render(DataTable, {
@@ -729,3 +758,50 @@ describe('DataTable', () => {
         await expectNoA11yViolations(container);
     });
 });
+describe('DataTable phoneLayout', () => {
+    it('keeps the scrolling table unless asked for cards', () => {
+        const { container } = render(DataTable, {
+            props: { data, columns, caption: 'People' },
+        });
+        expect(container.querySelector('.data-table-container--phone-cards')).toBeNull();
+    });
+    it('marks the container for the phone card layout and keeps the table semantics', () => {
+        const { container } = render(DataTable, {
+            props: { data, columns, caption: 'People', phoneLayout: 'cards' },
+        });
+        expect(container.querySelector('.data-table-container.data-table-container--phone-cards')).not.toBeNull();
+        expect(screen.getByRole('table', { name: 'People' })).toBeInTheDocument();
+        expect(screen.getAllByRole('row')).toHaveLength(3);
+    });
+    it('gives cards explicit table roles and a visible column label per cell', async () => {
+        const { container } = render(DataTable, {
+            props: { data, columns, caption: 'People', phoneLayout: 'cards' },
+        });
+        // Explicit roles survive the block/grid restyle (WebKit drops implicit
+        // table roles once display changes).
+        expect(container.querySelector('table')).toHaveAttribute('role', 'table');
+        for (const row of container.querySelectorAll('tr')) {
+            expect(row).toHaveAttribute('role', 'row');
+        }
+        for (const header of container.querySelectorAll('thead th')) {
+            expect(header).toHaveAttribute('role', 'columnheader');
+        }
+        const cells = container.querySelectorAll('tbody td[data-column-id]');
+        expect(cells.length).toBeGreaterThan(0);
+        for (const cell of cells) {
+            expect(cell).toHaveAttribute('role', 'cell');
+            const column = columns.find((candidate) => candidate.id === cell.getAttribute('data-column-id'));
+            expect(cell).toHaveAttribute('data-label', column?.label);
+        }
+        // The header stays in the accessibility tree (visually hidden, not removed).
+        expect(screen.getAllByRole('columnheader').length).toBe(columns.length);
+        await expectNoA11yViolations(container);
+    });
+    it('adds no explicit roles or labels outside cards mode', () => {
+        const { container } = render(DataTable, {
+            props: { data, columns, caption: 'People' },
+        });
+        expect(container.querySelector('table')).not.toHaveAttribute('role');
+        expect(container.querySelector('[data-label]')).toBeNull();
+    });
+});

package/dist/components/data/__tests__/DataTableController.test.js

@@ -118,6 +118,41 @@ describe('DataTableController', () => {
             { columnId: 'age', direction: 'asc' },
         ]);
     });
+    it('starts a column at its first direction and toggles without clearing when not clearable', () => {
+        const controller = createDataTableController({ initialState: state });
+        const toggle = () => controller.dispatch({
+            type: 'toggleSorting',
+            columnId: 'age',
+            firstDirection: 'desc',
+            clearable: false,
+        });
+        toggle();
+        expect(controller.snapshot().state.sorting).toEqual([
+            { columnId: 'age', direction: 'desc' },
+        ]);
+        toggle();
+        expect(controller.snapshot().state.sorting).toEqual([
+            { columnId: 'age', direction: 'asc' },
+        ]);
+        toggle();
+        expect(controller.snapshot().state.sorting).toEqual([
+            { columnId: 'age', direction: 'desc' },
+        ]);
+        // Clearable (default) with a desc-first column: desc -> asc -> cleared.
+        const cycling = createDataTableController({ initialState: state });
+        const cycle = () => cycling.dispatch({
+            type: 'toggleSorting',
+            columnId: 'age',
+            firstDirection: 'desc',
+        });
+        cycle();
+        cycle();
+        expect(cycling.snapshot().state.sorting).toEqual([
+            { columnId: 'age', direction: 'asc' },
+        ]);
+        cycle();
+        expect(cycling.snapshot().state.sorting).toEqual([]);
+    });
     it('proposes controlled transitions without mutating until the host reconciles state', () => {
         const onStateChange = vi.fn();
         const controller = createDataTableController({ state, onStateChange });

package/dist/components/data/__tests__/SortableHeader.test.js

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fireEvent, render, screen } from '@testing-library/svelte';
+import { describe, expect, it, vi } from 'vitest';
+import ListSortSelect from '../ListSortSelect.svelte';
+import SortableHeader from '../SortableHeader.svelte';
+const spec = {
+    columns: [{ id: 'published', firstDirection: 'desc' }, 'title'],
+    default: { columnId: 'published', direction: 'desc' },
+};
+describe('SortableHeader', () => {
+    it('marks the sorted column with aria-sort and an arrow, and labels the next action', () => {
+        render(SortableHeader, {
+            props: {
+                columnId: 'published',
+                label: 'Published',
+                sort: spec.default,
+                spec,
+                as: 'div',
+            },
+        });
+        const header = screen.getByRole('columnheader');
+        expect(header.getAttribute('aria-sort')).toBe('descending');
+        expect(header.textContent).toContain('↓');
+        expect(screen.getByRole('button', { name: 'Sort by Published, ascending' })).toBeTruthy();
+    });
+    it('calls onSort from a button (keyboard-activatable) for client lists', async () => {
+        const onSort = vi.fn();
+        render(SortableHeader, {
+            props: {
+                columnId: 'title',
+                label: 'Title',
+                sort: spec.default,
+                spec,
+                onSort,
+                as: 'div',
+            },
+        });
+        const header = screen.getByRole('columnheader');
+        expect(header.getAttribute('aria-sort')).toBe('none');
+        const button = screen.getByRole('button', {
+            name: 'Sort by Title, ascending',
+        });
+        await fireEvent.click(button);
+        expect(onSort).toHaveBeenCalledWith('title');
+    });
+    it('renders a link for server-sorted lists', () => {
+        render(SortableHeader, {
+            props: {
+                columnId: 'title',
+                label: 'Title',
+                sort: { columnId: 'title', direction: 'asc' },
+                spec,
+                href: '/list?sort=title&dir=desc',
+                as: 'div',
+            },
+        });
+        const link = screen.getByRole('link', {
+            name: 'Sort by Title, descending',
+        });
+        expect(link.getAttribute('href')).toBe('/list?sort=title&dir=desc');
+        expect(screen.getByRole('columnheader').getAttribute('aria-sort')).toBe('ascending');
+    });
+});
+describe('ListSortSelect', () => {
+    it('offers plain-language orders and reports the chosen sort', async () => {
+        const onChange = vi.fn();
+        render(ListSortSelect, {
+            props: {
+                columns: [
+                    { id: 'published', label: 'Published', kind: 'date' },
+                    { id: 'title', label: 'Title' },
+                ],
+                sort: spec.default,
+                onChange,
+            },
+        });
+        const select = screen.getByLabelText('Sort by');
+        expect([...select.options].map((option) => option.textContent)).toEqual([
+            'Published, newest first',
+            'Published, oldest first',
+            'Title, A–Z',
+            'Title, Z–A',
+        ]);
+        expect(select.value).toBe('published:desc');
+        await fireEvent.change(select, { target: { value: 'title:asc' } });
+        expect(onChange).toHaveBeenCalledWith({
+            columnId: 'title',
+            direction: 'asc',
+        });
+    });
+});
+describe('SortableHeader style hooks', () => {
+    it('reads its control weight from --sortable-header-font-weight (default 600)', () => {
+        const source = readFileSync(join(process.cwd().endsWith('packages/smrt-ui')
+            ? process.cwd()
+            : join(process.cwd(), 'packages/smrt-ui'), 'src/components/data/SortableHeader.svelte'), 'utf8');
+        expect(source).toMatch(/font-weight:\s*var\(--sortable-header-font-weight,\s*600\)/);
+        expect(source).toMatch(/padding:\s*var\(--sortable-header-padding,/);
+    });
+});

package/dist/components/data/__tests__/link-step-surface.test.js

@@ -0,0 +1,172 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createDataSurfaceRegistry } from '../data-surface.js';
+import { registerLinkSurface, resolveLinkTarget } from '../link-surface.js';
+import { registerStepSurface } from '../step-surface.js';
+const links = [
+    { id: 'events', label: 'Events', href: '/s/events', group: 'Content' },
+    { id: 'articles', label: 'Articles', href: '/s/articles', group: 'Content' },
+    { id: 'ads', label: 'Advertising', href: '/s/ads' },
+];
+let sequence = 0;
+function command(surfaceId, kind, controlId, expectedRevision, payload) {
+    sequence += 1;
+    return {
+        version: 1,
+        commandId: `c${sequence}`,
+        identity: { surfaceId, kind },
+        expectedRevision,
+        controlId,
+        ...(payload === undefined ? {} : { payload: payload }),
+    };
+}
+describe('link surface', () => {
+    it('resolves by id, label, and unique prefix; refuses ambiguity', () => {
+        expect(resolveLinkTarget('events', links)).toBe('/s/events');
+        expect(resolveLinkTarget({ target: 'ARTICLES' }, links)).toBe('/s/articles');
+        expect(resolveLinkTarget({ page: 'adv' }, links)).toBe('/s/ads');
+        expect(resolveLinkTarget('a', links)).toBeNull();
+        expect(resolveLinkTarget({ nope: 1 }, links)).toBeNull();
+    });
+    it('publishes links without hrefs and navigates through the open control', async () => {
+        const registry = createDataSurfaceRegistry();
+        const navigate = vi.fn();
+        const handle = registerLinkSurface({
+            registry,
+            surfaceId: 'site-sections',
+            label: 'Site sections',
+            description: 'Pages in this site',
+            links,
+            navigate,
+        });
+        const snapshot = registry.inspect({
+            surfaceId: 'site-sections',
+            kind: 'list',
+        });
+        expect(JSON.stringify(snapshot?.state)).not.toContain('/s/');
+        expect(snapshot?.state.links).toEqual([
+            { id: 'events', label: 'Events', group: 'Content' },
+            { id: 'articles', label: 'Articles', group: 'Content' },
+            { id: 'ads', label: 'Advertising' },
+        ]);
+        const ok = await registry.execute(command('site-sections', 'list', 'open', snapshot?.revision ?? 0, {
+            target: 'Events',
+        }));
+        expect(ok.ok).toBe(true);
+        expect(navigate).toHaveBeenCalledWith('/s/events');
+        const refused = await registry.execute(command('site-sections', 'list', 'open', snapshot?.revision ?? 0, {
+            target: 'https://evil.example',
+        }));
+        expect(refused.ok).toBe(false);
+        handle.update({ state: { active: 'events' } });
+        expect(registry.inspect({ surfaceId: 'site-sections', kind: 'list' })?.revision).toBe((snapshot?.revision ?? 0) + 1);
+        handle.destroy();
+        expect(registry.list()).toHaveLength(0);
+    });
+});
+describe('step surface', () => {
+    const steps = [
+        { id: 'town', label: 'Your town' },
+        { id: 'features', label: 'Features' },
+        { id: 'live', label: 'Go live' },
+    ];
+    const identity = { surfaceId: 'new-site-steps', kind: 'custom' };
+    it('advances a non-writing step through the page handler', async () => {
+        const registry = createDataSurfaceRegistry();
+        const next = vi.fn(() => true);
+        const handle = registerStepSurface({
+            registry,
+            surfaceId: 'new-site-steps',
+            label: 'New site steps',
+            description: 'Start a new town site',
+            steps,
+            current: 'town',
+            next,
+        });
+        const before = registry.inspect(identity);
+        expect(before?.state).toMatchObject({
+            current: 'town',
+            currentLabel: 'Your town',
+            stepNumber: 1,
+            stepCount: 3,
+            nextWrites: false,
+            awaitingPerson: false,
+        });
+        const result = await registry.execute(command('new-site-steps', 'custom', 'next', before?.revision ?? 0));
+        expect(result.ok).toBe(true);
+        expect(next).toHaveBeenCalledTimes(1);
+        handle.update({
+            current: 'features',
+            steps: [{ ...steps[0], complete: true }, steps[1], steps[2]],
+        });
+        const after = registry.inspect(identity);
+        expect(after?.state.current).toBe('features');
+        expect(after?.state.steps).toEqual([
+            { id: 'town', label: 'Your town', status: 'complete' },
+            { id: 'features', label: 'Features', status: 'current' },
+            { id: 'live', label: 'Go live', status: 'upcoming' },
+        ]);
+    });
+    it('refuses when the page handler rejects the step (validation failed)', async () => {
+        const registry = createDataSurfaceRegistry();
+        registerStepSurface({
+            registry,
+            surfaceId: 'new-site-steps',
+            label: 'New site steps',
+            description: 'Start a new town site',
+            steps,
+            current: 'town',
+            next: () => false,
+        });
+        const result = await registry.execute(command('new-site-steps', 'custom', 'next', 1));
+        expect(result.ok).toBe(false);
+    });
+    it('never presses a writing step: it shows the button and waits for the person', async () => {
+        const registry = createDataSurfaceRegistry();
+        const create = vi.fn();
+        const showNext = vi.fn();
+        const handle = registerStepSurface({
+            registry,
+            surfaceId: 'new-site-steps',
+            label: 'New site steps',
+            description: 'Start a new town site',
+            steps,
+            current: 'features',
+            next: create,
+            nextWrites: true,
+            showNext,
+        });
+        const result = await registry.execute(command('new-site-steps', 'custom', 'next', 1));
+        expect(result.ok).toBe(true);
+        expect(create).not.toHaveBeenCalled();
+        expect(showNext).toHaveBeenCalledTimes(1);
+        expect(registry.inspect(identity)?.state).toMatchObject({
+            nextWrites: true,
+            awaitingPerson: true,
+        });
+        handle.update({ current: 'live', nextWrites: false });
+        expect(registry.inspect(identity)?.state.awaitingPerson).toBe(false);
+    });
+    it('goes back and jumps only to available steps', async () => {
+        const registry = createDataSurfaceRegistry();
+        const back = vi.fn();
+        const goTo = vi.fn();
+        registerStepSurface({
+            registry,
+            surfaceId: 'new-site-steps',
+            label: 'New site steps',
+            description: 'Start a new town site',
+            steps: [{ ...steps[0], complete: true }, steps[1], steps[2]],
+            current: 'features',
+            back,
+            goTo,
+        });
+        expect((await registry.execute(command('new-site-steps', 'custom', 'back', 1)))
+            .ok).toBe(true);
+        expect(back).toHaveBeenCalled();
+        expect((await registry.execute(command('new-site-steps', 'custom', 'go-to', 1, {
+            target: 'Go live',
+        }))).ok).toBe(false);
+        expect((await registry.execute(command('new-site-steps', 'custom', 'go-to', 1, 'your town'))).ok).toBe(true);
+        expect(goTo).toHaveBeenCalledWith('town');
+    });
+});