@mpfrontend/nx-plugin 0.0.0-stage → 0.1.0

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}

package/generators.json

@@ -0,0 +1,24 @@
+{
+  "generators": {
+    "application": {
+      "factory": "./dist/generator.js",
+      "schema": "./schema.json",
+      "description": "Create a neutral Next.js consumer using MP Frontend public packages"
+    },
+    "feature": {
+      "factory": "./dist/feature-generator.js",
+      "schema": "./schemas/feature-schema.json",
+      "description": "Create a feature with ui, model, hooks, api, utils and an index.ts public entry; with a resource, a URL-driven list and detail over that generated read"
+    },
+    "route": {
+      "factory": "./dist/route-generator.js",
+      "schema": "./schemas/route-schema.json",
+      "description": "Create one Next.js route that renders a feature screen"
+    },
+    "package": {
+      "factory": "./dist/package-generator.js",
+      "schema": "./schemas/package-schema.json",
+      "description": "Create a shared package with boundary tags, a public entry and the quality targets"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@mpfrontend/nx-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panahister/mpfrontend.git",
+    "directory": "packages/nx-plugin"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./generators.json": "./generators.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "templates",
+    "generators.json",
+    "schema.json",
+    "schemas"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@nx/devkit": "23.2.1"
+  },
+  "devDependencies": {
+    "@mpfrontend/workspace-config": "0.1.0"
+  },
+  "generators": "./generators.json"
 }

package/schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,48}$"
+    },
+    "directory": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "name",
+    "directory"
+  ],
+  "additionalProperties": false
+}

package/schemas/feature-schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "type": "object",
+  "properties": {
+    "app": {
+      "type": "string",
+      "description": "The app directory, relative to the workspace root, for example apps/customer"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,48}$",
+      "description": "The feature name, kebab case"
+    },
+    "resource": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,48}$",
+      "description": "A read resource selected in the app's ftg.config.json; makes a list feature"
+    }
+  },
+  "required": [
+    "app",
+    "name"
+  ],
+  "additionalProperties": false
+}

package/schemas/package-schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,48}$",
+      "description": "The package name, kebab case; the workspace scope is added"
+    },
+    "directory": {
+      "type": "string",
+      "pattern": "^packages/[a-z][a-z0-9-]{1,48}$",
+      "description": "Defaults to packages/<name>"
+    },
+    "runtime": {
+      "enum": [
+        "universal",
+        "client",
+        "server"
+      ],
+      "description": "The runtime tag; defaults to universal"
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "additionalProperties": false
+}

package/schemas/route-schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "type": "object",
+  "properties": {
+    "app": {
+      "type": "string",
+      "description": "The app directory, relative to the workspace root"
+    },
+    "path": {
+      "type": "string",
+      "pattern": "^[a-z0-9\\[][a-zA-Z0-9\\-\\[\\]/]*$",
+      "description": "The route path under src/app, for example orders or orders/[position]"
+    },
+    "feature": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,48}$",
+      "description": "The feature whose screen the route renders"
+    },
+    "screen": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Za-z0-9]{0,79}$",
+      "description": "The screen export of the feature; defaults to <Feature>Screen"
+    }
+  },
+  "required": [
+    "app",
+    "path",
+    "feature"
+  ],
+  "additionalProperties": false
+}

package/templates/feature/list/api/server/__resource__.ts.template

@@ -0,0 +1,24 @@
+import 'server-only';
+import { listSearchParams, type ListState } from '@mpfrontend/ftg-core';
+import { bffOrigin, appId } from '../../config/server';
+import { localeRegistry } from '../../config/app';
+import { __RESOURCE_CONSTANT___LIST, type __Resource__Page } from '../../entities/__resource__';
+import { parseRead } from '__SERVER_TO_OUTPUT__/read-models.gen';
+
+/**
+ * The trusted server boundary of the resource: a list state in, only the parameters that the list protocol declares
+ * sent to the BFF, a validated response out.
+ */
+export async function read__Resource__(
+  state: ListState,
+  language: string = localeRegistry.defaultLocale,
+): Promise<__Resource__Page> {
+  const path = '/' + appId + '/__resource__?' + listSearchParams(__RESOURCE_CONSTANT___LIST, state);
+  const response = await fetch(bffOrigin + path, {
+    cache: 'no-store',
+    headers: { 'Accept-Language': language },
+    signal: AbortSignal.timeout(10000),
+  });
+  if (!response.ok) throw new Error('__RESOURCE_CONSTANT___UNAVAILABLE');
+  return parseRead('__resource__', await response.json());
+}

package/templates/feature/list/app/api/__resource__/route.ts.template

@@ -0,0 +1,24 @@
+import { read__Resource__ } from '../../../api/server/__resource__';
+import { localeRegistry } from '../../../config/app';
+import { __RESOURCE_CONSTANT___URL_STATE } from '../../../entities/__resource__';
+
+/**
+ * The app's own read route of the resource: the browser reads the list here, never the backend. The query is read
+ * with the list's URL state, so an invalid value is its default and only declared parameters reach the BFF.
+ */
+export async function GET(request: Request) {
+  try {
+    return Response.json(
+      await read__Resource__(
+        __RESOURCE_CONSTANT___URL_STATE.read(new URL(request.url).searchParams),
+        localeRegistry.negotiate(request.headers.get('Accept-Language')),
+      ),
+      { headers: { 'Cache-Control': 'no-store' } },
+    );
+  } catch {
+    return Response.json(
+      { code: '__RESOURCE_CONSTANT___UNAVAILABLE' },
+      { status: 503, headers: { 'Cache-Control': 'no-store' } },
+    );
+  }
+}

package/templates/feature/list/entities/__resource__/index.ts.template

@@ -0,0 +1,12 @@
+// The public entry of the entity. Features and server adapters import only from here.
+export {
+  itemPosition,
+  locateItem,
+  type __Resource__Item,
+  type __Resource__Page,
+} from './model/__resource__';
+export {
+  __RESOURCE_CONSTANT___LIST,
+  __RESOURCE_CONSTANT___PAGE_SIZE,
+  __RESOURCE_CONSTANT___URL_STATE,
+} from './model/__resource__-list';

package/templates/feature/list/entities/__resource__/model/__resource__-list.test.ts.template

@@ -0,0 +1,23 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { checkListProtocol, type OpenApiDocument } from '@mpfrontend/ftg-core';
+import { __RESOURCE_CONSTANT___LIST, __RESOURCE_CONSTANT___URL_STATE } from './__resource__-list';
+
+test('the list protocol sends only parameters that the captured contract declares', async () => {
+  const app = new URL('../../../../', import.meta.url);
+  const config = JSON.parse(await readFile(new URL('ftg.config.json', app), 'utf8')) as { openapi: string };
+  const contract = JSON.parse(await readFile(new URL(config.openapi, app), 'utf8')) as OpenApiDocument;
+  assert.deepEqual(checkListProtocol(contract, __RESOURCE_CONSTANT___LIST), []);
+});
+
+test('the URL state restores a linked list and falls back to its defaults for an invalid value', () => {
+  const state = __RESOURCE_CONSTANT___URL_STATE.read('page=3&search=term');
+  assert.equal(state.page, 3);
+  assert.equal(state.filters?.search, 'term');
+  assert.equal(__RESOURCE_CONSTANT___URL_STATE.serialize(state), '?page=3&search=term');
+  assert.deepEqual(
+    __RESOURCE_CONSTANT___URL_STATE.read('page=0&size=1000&search=' + 'x'.repeat(101)),
+    __RESOURCE_CONSTANT___URL_STATE.defaults,
+  );
+});

package/templates/feature/list/entities/__resource__/model/__resource__-list.ts.template

@@ -0,0 +1,24 @@
+import type { ListProtocol } from '@mpfrontend/ftg-core';
+import { listUrlState } from '@mpfrontend/data-react/shared';
+
+/**
+ * How the list operation of the resource pages and filters, as data: the parameters a request sends and where the
+ * answer holds the rows and the total. The test beside it checks it against the captured contract, so a request
+ * sends only parameters the operation declares. Add a sort or a filter here only when the contract declares it.
+ */
+export const __RESOURCE_CONSTANT___LIST: ListProtocol = {
+  operationId: '__OPERATION_ID__',
+  page: { param: 'page', encoding: 'number', first: 1 },
+  size: { param: 'size', max: 100 },
+  filters: { search: { param: 'search', maxLength: 100 } },
+  rows: ['items'],
+  total: ['total'],
+};
+
+/** The page size when the URL names none. */
+export const __RESOURCE_CONSTANT___PAGE_SIZE = 12;
+
+/** The list state that the URL owns, read the same way on the server and in the browser. It never holds the scope. */
+export const __RESOURCE_CONSTANT___URL_STATE = listUrlState(__RESOURCE_CONSTANT___LIST, {
+  size: __RESOURCE_CONSTANT___PAGE_SIZE,
+});

package/templates/feature/list/entities/__resource__/model/__resource__.test.ts.template

@@ -0,0 +1,17 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { itemPosition, locateItem } from './__resource__';
+
+test('a list position and its page and index convert both ways', () => {
+  for (const [page, index] of [
+    [1, 0],
+    [1, 11],
+    [2, 0],
+    [9, 5],
+  ] as const) {
+    assert.deepEqual(locateItem(itemPosition(page, 12, index), 12), { page, index });
+  }
+  for (const position of [0, -1, 1.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1]) {
+    assert.equal(locateItem(position, 12), undefined);
+  }
+});

package/templates/feature/list/entities/__resource__/model/__resource__.ts.template

@@ -0,0 +1,19 @@
+import type { ReadModels } from '__ENTITY_TO_OUTPUT__/read-models.gen';
+
+/** One page of the resource, as the generated contract validates it. */
+export type __Resource__Page = ReadModels['__resource__'];
+export type __Resource__Item = __Resource__Page['items'][number];
+
+/** An item's position in the list, counted from 1; the identity that a detail route links to. */
+export function itemPosition(page: number, size: number, index: number): number {
+  return (page - 1) * size + index + 1;
+}
+
+/** The page and index of a list position, or undefined for a position that cannot exist. */
+export function locateItem(
+  position: number,
+  size: number,
+): { page: number; index: number } | undefined {
+  if (!Number.isSafeInteger(position) || position < 1) return undefined;
+  return { page: Math.floor((position - 1) / size) + 1, index: (position - 1) % size };
+}

package/templates/feature/list/features/__feature__/api/__feature__-read.ts.template

@@ -0,0 +1,12 @@
+import type { __Resource__Page } from '../../../entities/__resource__';
+import { parseRead } from '__FEATURE_TO_OUTPUT__/read-models.gen';
+
+/** Reads one page in the browser through the app's own route, never the backend directly, and validates it. */
+export async function read__Feature__Page(search: string, signal: AbortSignal): Promise<__Resource__Page> {
+  const response = await fetch('/api/__resource__' + search, {
+    signal,
+    headers: { Accept: 'application/json' },
+  });
+  if (!response.ok) throw new Error('__RESOURCE_CONSTANT___UNAVAILABLE');
+  return parseRead('__resource__', await response.json());
+}

package/templates/feature/list/features/__feature__/api/__feature__.ts.template

@@ -0,0 +1,28 @@
+import 'server-only';
+import type { ListState } from '@mpfrontend/ftg-core';
+import { read__Resource__ } from '../../../api/server/__resource__';
+import {
+  locateItem,
+  __RESOURCE_CONSTANT___PAGE_SIZE,
+  type __Resource__Item,
+  type __Resource__Page,
+} from '../../../entities/__resource__';
+
+/** The first page of the list on the server, for the URL state of the request. */
+export function load__Feature__Page(state: ListState, language: string): Promise<__Resource__Page> {
+  return read__Resource__(state, language);
+}
+
+/** The item at a list position, or undefined when the position is outside the list. */
+export async function load__Feature__Item(
+  position: number,
+  language: string,
+): Promise<__Resource__Item | undefined> {
+  const location = locateItem(position, __RESOURCE_CONSTANT___PAGE_SIZE);
+  if (!location) return undefined;
+  const page = await read__Resource__(
+    { page: location.page, size: __RESOURCE_CONSTANT___PAGE_SIZE },
+    language,
+  );
+  return page.items[location.index];
+}

package/templates/feature/list/features/__feature__/hooks/use-__feature__-list.ts.template

@@ -0,0 +1,22 @@
+'use client';
+import { useScopedQuery, useTableUrlState } from '@mpfrontend/data-react';
+import { __RESOURCE_CONSTANT___URL_STATE, type __Resource__Page } from '../../../entities/__resource__';
+import { read__Feature__Page } from '../api/__feature__-read';
+
+/**
+ * The list state of the URL and the page it selects. The page is read under the access scope through the app's own
+ * route; the server's first page is used while the URL still asks for it. `null` means the server could not read it.
+ */
+export function use__Feature__List(initial: Readonly<{ search: string; page: __Resource__Page | null }>) {
+  const table = useTableUrlState(__RESOURCE_CONSTANT___URL_STATE);
+  const search = __RESOURCE_CONSTANT___URL_STATE.serialize(table);
+  const first = search === initial.search;
+  const query = useScopedQuery({
+    operation: '__resource__.list',
+    params: search,
+    read: read__Feature__Page,
+    ...(first && initial.page ? { initialData: initial.page } : {}),
+  });
+  const unavailable = query.isError || (first && initial.page === null && query.data === undefined);
+  return { table, page: query.data, unavailable };
+}

package/templates/feature/list/features/__feature__/index.ts.template

@@ -0,0 +1,3 @@
+// The public entry of the feature. Code outside the feature imports only from here.
+export { __Feature__Screen, type __Feature__ScreenProps } from './ui/__feature__-screen';
+export { __Feature__DetailScreen } from './ui/__feature__-detail-screen';

package/templates/feature/list/features/__feature__/model/__feature__-fields.ts.template

@@ -0,0 +1,4 @@
+import { resources } from '__FEATURE_TO_OUTPUT__/resources.gen';
+
+/** The display fields of the generated resource contract. */
+export const fields = resources.find((resource) => resource.name === '__resource__')!.fields;

package/templates/feature/list/features/__feature__/model/overrides/index.ts.template

@@ -0,0 +1,3 @@
+// Authored product formatting and behavior belong here; generators never overwrite this file. Visible text
+// comes from the catalogs in ../messages, for example a column label: labels = { name: t('nameColumn') }.
+export const labels: Readonly<Record<string, string>> = {};

package/templates/feature/list/features/__feature__/ui/__feature__-detail-screen.tsx.template

@@ -0,0 +1,16 @@
+import { notFound } from 'next/navigation';
+import { cookies } from 'next/headers';
+import { preferenceCookie, visitorLocale } from '../../../config/app';
+import { load__Feature__Item } from '../api/__feature__';
+import { fields } from '../model/__feature__-fields';
+import type { __Feature__ScreenProps } from './__feature__-screen';
+import { __Feature__Detail } from './__feature__-detail';
+
+/** The detail screen: a child route of the list, so an item can be linked and refreshed. */
+export async function __Feature__DetailScreen({ params, basePath }: __Feature__ScreenProps) {
+  const position = Number((await params)?.position);
+  const language = visitorLocale((await cookies()).get(preferenceCookie.name)?.value);
+  const item = await load__Feature__Item(position, language).catch(() => null);
+  if (item === undefined) notFound();
+  return <__Feature__Detail item={item} fields={fields} language={language} basePath={basePath} />;
+}

package/templates/feature/list/features/__feature__/ui/__feature__-detail.test.tsx.template

@@ -0,0 +1,28 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { __Feature__Detail } from './__feature__-detail';
+
+const fields = [{ key: 'name', type: 'string', required: true, editable: false, nullable: false }];
+
+test('the detail view renders the generated fields of one item and a way back to the list', () => {
+  const html = renderToStaticMarkup(
+    createElement(__Feature__Detail, {
+      item: { name: 'Example' } as never,
+      fields,
+      language: 'en',
+      basePath: '/list',
+    }),
+  );
+  assert.match(html, /<dt[^>]*>name<\/dt><dd[^>]*>Example<\/dd>/);
+  assert.match(html, /href="\/list"/);
+});
+
+test('an unreadable item is announced instead of rendering an empty record', () => {
+  const html = renderToStaticMarkup(
+    createElement(__Feature__Detail, { item: null, fields, language: 'en', basePath: '/list' }),
+  );
+  assert.match(html, /role="alert"/);
+  assert.doesNotMatch(html, /<dl/);
+});

package/templates/feature/list/features/__feature__/ui/__feature__-detail.tsx.template

@@ -0,0 +1,44 @@
+import { Fragment } from 'react';
+import { PageFrame } from '@mpfrontend/app-layout';
+import { Card, type DisplayField } from '@mpfrontend/ui';
+import { formatValue } from '@mpfrontend/i18n';
+import { localeRegistry } from '../../../config/app';
+import type { __Resource__Item } from '../../../entities/__resource__';
+import { messages } from '../model/messages';
+import { labels } from '../model/overrides';
+
+type Props = Readonly<{
+  item: __Resource__Item | null;
+  fields: readonly DisplayField[];
+  language: string;
+  basePath: string;
+}>;
+
+/** The detail view. `null` means the server boundary could not read the item. */
+export function __Feature__Detail({ item, fields, language, basePath }: Props) {
+  const t = messages.translator(language);
+  const values = item as Readonly<Record<string, unknown>> | null;
+  return (
+    <PageFrame title={t('title')} actions={<a href={basePath}>{t('back')}</a>}>
+      {values === null ? (
+        <p role="alert">{t('unavailable')}</p>
+      ) : (
+        <Card>
+          <dl className="grid grid-cols-[max-content_1fr] gap-x-6 gap-y-2">
+            {fields.map((field) => (
+              <Fragment key={field.key}>
+                <dt className="font-medium">{labels[field.key] ?? field.key}</dt>
+                <dd className="m-0">
+                  {formatValue(values[field.key], language, localeRegistry, {
+                    true: t('yes'),
+                    false: t('no'),
+                  })}
+                </dd>
+              </Fragment>
+            ))}
+          </dl>
+        </Card>
+      )}
+    </PageFrame>
+  );
+}

package/templates/feature/list/features/__feature__/ui/__feature__-list.tsx.template

@@ -0,0 +1,75 @@
+'use client';
+import { PageFrame } from '@mpfrontend/app-layout';
+import { Card, ResourceTable, type DisplayField } from '@mpfrontend/ui';
+import { formatValue } from '@mpfrontend/i18n';
+import { localeRegistry } from '../../../config/app';
+import { itemPosition, type __Resource__Page } from '../../../entities/__resource__';
+import { use__Feature__List } from '../hooks/use-__feature__-list';
+import { messages } from '../model/messages';
+import { labels } from '../model/overrides';
+import { detailHref } from '../utils/__feature__-href';
+
+type Props = Readonly<{
+  initialPage: __Resource__Page | null;
+  initialSearch: string;
+  fields: readonly DisplayField[];
+  language: string;
+  basePath: string;
+}>;
+
+/** The list view: it renders the page that the URL state selects and emits paging and filter intent. */
+export function __Feature__List({ initialPage, initialSearch, fields, language, basePath }: Props) {
+  const t = messages.translator(language);
+  const { table, page, unavailable } = use__Feature__List({ search: initialSearch, page: initialPage });
+  return (
+    <PageFrame title={t('title')}>
+      {unavailable ? (
+        <p
+          role="alert"
+          className="border-s-4 border-[color:var(--mp-status-warning)] bg-[color:var(--mp-status-warningsurface)] p-4"
+        >
+          {t('unavailable')}
+        </p>
+      ) : page === undefined ? (
+        <p role="status">{t('loading')}</p>
+      ) : (
+        <Card>
+          <ResourceTable
+            fields={fields}
+            rows={page.items}
+            caption={t('title')}
+            format={(value) =>
+              formatValue(value, language, localeRegistry, { true: t('yes'), false: t('no') })
+            }
+            labels={{ ...labels, detail: t('detail'), search: t('search') }}
+            detail={(row) => (
+              <a
+                href={detailHref(
+                  basePath,
+                  itemPosition(page.number, table.size, page.items.indexOf(row as never)),
+                )}
+              >
+                {t('detail')}
+              </a>
+            )}
+            control={{
+              mode: 'server',
+              ...table,
+              total: page.total,
+              filterable: ['search'],
+              text: {
+                pagination: t('pagination'),
+                previous: t('previous'),
+                next: t('next'),
+                page: (number, count) => t('pageOf', { page: number, count: count ?? number }),
+                apply: t('apply'),
+                filters: t('search'),
+              },
+            }}
+          />
+          {page.items.length === 0 && <p>{t('empty')}</p>}
+        </Card>
+      )}
+    </PageFrame>
+  );
+}

package/templates/feature/list/features/__feature__/ui/__feature__-screen.tsx.template

@@ -0,0 +1,31 @@
+import { cookies } from 'next/headers';
+import { preferenceCookie, visitorLocale } from '../../../config/app';
+import { __RESOURCE_CONSTANT___URL_STATE } from '../../../entities/__resource__';
+import { load__Feature__Page } from '../api/__feature__';
+import { fields } from '../model/__feature__-fields';
+import { __Feature__List } from './__feature__-list';
+
+export type __Feature__ScreenProps = Readonly<{
+  params?: Promise<Readonly<Record<string, string>>>;
+  searchParams?: Promise<Readonly<Record<string, string | string[] | undefined>>>;
+  basePath: string;
+}>;
+
+/**
+ * The list screen. The server reads the URL state the way the browser does and renders the first page; the browser
+ * then reads each further page through the app's own route.
+ */
+export async function __Feature__Screen({ searchParams, basePath }: __Feature__ScreenProps) {
+  const state = __RESOURCE_CONSTANT___URL_STATE.read((await searchParams) ?? {});
+  const language = visitorLocale((await cookies()).get(preferenceCookie.name)?.value);
+  const page = await load__Feature__Page(state, language).catch(() => null);
+  return (
+    <__Feature__List
+      initialPage={page}
+      initialSearch={__RESOURCE_CONSTANT___URL_STATE.serialize(state)}
+      fields={fields}
+      language={language}
+      basePath={basePath}
+    />
+  );
+}

package/templates/feature/list/features/__feature__/utils/__feature__-href.test.ts.template

@@ -0,0 +1,7 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { detailHref } from './__feature__-href';
+
+test('a detail link carries the list position in the URL', () => {
+  assert.equal(detailHref('/list', 14), '/list/14');
+});

package/templates/feature/list/features/__feature__/utils/__feature__-href.ts.template

@@ -0,0 +1,4 @@
+/** The detail URL of the item at a list position. */
+export function detailHref(basePath: string, position: number): string {
+  return basePath + '/' + position;
+}