Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,60 @@
import { describe, expect, test } from "vitest";
import type { DataTableVM } from "@toolctrl/view-models";
import { toDataTableModel } from "./dataTable.js";
function baseVm(overrides: Partial<DataTableVM> = {}): DataTableVM {
return {
columns: [
{ key: "name", labelKey: "ui.data-table.column.name" },
{ key: "amount", labelKey: "ui.data-table.column.amount", align: "right" },
],
rows: [
{ id: "row-1", cells: { name: "Alpha", amount: "10" } },
{ id: "row-2", cells: { name: "Beta", amount: "20" } },
],
...overrides,
};
}
describe("toDataTableModel", () => {
test("defaults column align to left and preserves explicit align", () => {
const model = toDataTableModel(baseVm());
expect(model.columns.map((column) => column.align)).toEqual(["left", "right"]);
expect(model.columns.map((column) => column.key)).toEqual(["name", "amount"]);
expect(model.columns.map((column) => column.labelKey)).toEqual([
"ui.data-table.column.name",
"ui.data-table.column.amount",
]);
});
test("defaults emptyLabelKey and computes rowCount", () => {
const model = toDataTableModel(baseVm());
expect(model.emptyLabelKey).toBe("ui.data-table.empty");
expect(model.rowCount).toBe(2);
const emptyModel = toDataTableModel(baseVm({ rows: [] }));
expect(emptyModel.rowCount).toBe(0);
});
test("honours a caller-supplied emptyLabelKey", () => {
const model = toDataTableModel(baseVm({ emptyLabelKey: "ui.data-table.no-results" }));
expect(model.emptyLabelKey).toBe("ui.data-table.no-results");
});
test("maps caption to captionKey and omits it when absent", () => {
const withCaption = toDataTableModel(baseVm({ caption: { labelKey: "ui.data-table.caption" } }));
expect(withCaption.captionKey).toBe("ui.data-table.caption");
const withoutCaption = toDataTableModel(baseVm());
expect(withoutCaption.captionKey).toBeUndefined();
});
test("throws when a column labelKey is not a valid i18n key", () => {
expect(() => toDataTableModel(baseVm({ columns: [{ key: "x", labelKey: "Not A Key" }] }))).toThrow();
});
test("throws when the caption labelKey is not a valid i18n key", () => {
expect(() => toDataTableModel(baseVm({ caption: { labelKey: "ui.dataTable.caption" } }))).toThrow();
});
});
@@ -0,0 +1,39 @@
import { assertI18nLabel, type DataTableModel, type DataTableVM } from "@toolctrl/view-models";
import { renderDataTable } from "@toolctrl/ui-subframe";
import { defineAdapter } from "./defineAdapter.js";
const DEFAULT_EMPTY_LABEL_KEY = "ui.data-table.empty";
/**
* Normalizes a domain {@link DataTableVM} into the {@link DataTableModel}
* prop-model the UI implementation renders. Validates every i18n key
* (columns + caption) and fills in defaults (column align, empty label,
* row count) so render implementations stay dumb.
*/
export function toDataTableModel(vm: DataTableVM): DataTableModel {
const columns = vm.columns.map((column) => {
assertI18nLabel(column);
return {
key: column.key,
labelKey: column.labelKey,
align: column.align ?? "left",
};
});
const captionKey = vm.caption ? assertI18nLabel(vm.caption).labelKey : undefined;
return {
captionKey,
columns,
rows: vm.rows,
emptyLabelKey: vm.emptyLabelKey ?? DEFAULT_EMPTY_LABEL_KEY,
rowCount: vm.rows.length,
};
}
export const dataTableAdapter = defineAdapter({
name: "dataTable",
toProps: toDataTableModel,
defaultRenderer: renderDataTable,
});
@@ -0,0 +1,21 @@
import type { UiRenderer } from "@toolctrl/view-models";
export type Adapter<VM, Model> = {
readonly name: string;
readonly toProps: (vm: VM) => Model;
readonly render: (vm: VM, renderer?: UiRenderer<Model>) => string;
};
export type DefineAdapterConfig<VM, Model> = {
readonly name: string;
readonly toProps: (vm: VM) => Model;
readonly defaultRenderer: UiRenderer<Model>;
};
export function defineAdapter<VM, Model>(config: DefineAdapterConfig<VM, Model>): Adapter<VM, Model> {
return {
name: config.name,
toProps: config.toProps,
render: (vm, renderer = config.defaultRenderer) => renderer(config.toProps(vm)),
};
}
@@ -0,0 +1,77 @@
import { describe, expect, test } from "vitest";
import type { FileBrowserData } from "@toolctrl/view-models";
import { renderFileBrowserMock } from "@toolctrl/ui-mock";
import { fileBrowserAdapter } from "./fileBrowser.js";
const vm: FileBrowserData = {
viewMode: "table",
rows: [
{
id: "file-1",
displayName: "invoice.pdf",
mimeType: "application/pdf",
sizeBytes: 1024,
createdAtIso: "2026-06-20T00:00:00.000Z",
tags: [],
source: "manual_upload",
previewStatus: "ready",
scanStatus: "clean",
thumbnailUrl: "/acme/media/file-1/thumb",
detailHref: "/acme/files/file-1",
linkedEntityLabelKey: null,
},
{
id: "file-2",
displayName: "photo.heic",
mimeType: "image/heic",
sizeBytes: 2048,
createdAtIso: "2026-06-20T00:00:00.000Z",
tags: ["site"],
source: "manual_upload",
previewStatus: "pending",
scanStatus: "pending",
thumbnailUrl: null,
detailHref: "/acme/files/file-2",
linkedEntityLabelKey: null,
},
],
filter: { entityType: null, mimeGroup: null, tags: [], assignedToUserId: null, includeArchived: false },
canWrite: true,
canDelete: false,
nextCursor: null,
emptyHeadlineKey: "files.browser.empty.headline",
emptyBodyKey: "files.browser.empty.body",
};
describe("fileBrowserAdapter hot-swap (M017)", () => {
test("normalizes the VM once via toProps", () => {
const model = fileBrowserAdapter.toProps(vm);
expect(model.rowCount).toBe(2);
expect(model.titleKey).toBe("files.browser.title");
expect(model.rows.map((row) => row.id)).toEqual(["file-1", "file-2"]);
});
test("swaps the render implementation without changing the data", () => {
const defaultHtml = fileBrowserAdapter.render(vm);
const mockHtml = fileBrowserAdapter.render(vm, renderFileBrowserMock);
expect(defaultHtml).toContain('data-ui-impl="subframe"');
expect(defaultHtml).not.toContain('data-ui-impl="mock"');
expect(mockHtml).toContain('data-ui-impl="mock"');
expect(mockHtml).not.toContain('data-ui-impl="subframe"');
expect(defaultHtml).not.toBe(mockHtml);
for (const html of [defaultHtml, mockHtml]) {
for (const row of vm.rows) {
expect(html).toContain(`data-row-id="${row.id}"`);
expect(html).toContain(row.displayName);
}
}
});
test("the default renderer is the real subframe implementation", () => {
expect(fileBrowserAdapter.name).toBe("fileBrowser");
expect(fileBrowserAdapter.render(vm)).toContain('data-ui-id="ui.files.browser"');
});
});
@@ -0,0 +1,33 @@
import type { FileBrowserData, FileBrowserModel } from "@toolctrl/view-models";
import { renderFileBrowser } from "@toolctrl/ui-subframe";
import { defineAdapter } from "./defineAdapter.js";
/**
* Normalizes the domain {@link FileBrowserData} into the {@link FileBrowserModel}
* prop-model the UI implementation renders (M015). Keeps render impls dumb so the
* Subframe / mock renderers stay swappable (M017 hot-swap drill).
*/
export function toFileBrowserModel(vm: FileBrowserData): FileBrowserModel {
return {
titleKey: "files.browser.title",
emptyHeadlineKey: vm.emptyHeadlineKey,
emptyBodyKey: vm.emptyBodyKey,
canWrite: vm.canWrite,
rows: vm.rows.map((row) => ({
id: row.id,
displayName: row.displayName,
mimeType: row.mimeType,
sizeBytes: row.sizeBytes,
detailHref: row.detailHref,
thumbnailUrl: row.thumbnailUrl,
})),
rowCount: vm.rows.length,
};
}
export const fileBrowserAdapter = defineAdapter({
name: "fileBrowser",
toProps: toFileBrowserModel,
defaultRenderer: renderFileBrowser,
});
@@ -0,0 +1,56 @@
import { describe, expect, test } from "vitest";
import type { DataTableVM } from "@toolctrl/view-models";
import { renderDataTableMock } from "@toolctrl/ui-mock";
import { dataTableAdapter } from "./dataTable.js";
const vm: DataTableVM = {
caption: { labelKey: "ui.data-table.caption" },
columns: [
{ key: "name", labelKey: "ui.data-table.column.name" },
{ key: "amount", labelKey: "ui.data-table.column.amount", align: "right" },
],
rows: [
{ id: "row-1", cells: { name: "Alpha", amount: "10" } },
{ id: "row-2", cells: { name: "Beta", amount: "20" } },
],
};
describe("dataTableAdapter hot-swap (M017)", () => {
test("normalizes the VM once via toProps", () => {
const model = dataTableAdapter.toProps(vm);
expect(model.rowCount).toBe(2);
expect(model.captionKey).toBe("ui.data-table.caption");
expect(model.columns.map((column) => column.align)).toEqual(["left", "right"]);
});
test("swaps the render implementation without changing the data", () => {
const defaultHtml = dataTableAdapter.render(vm);
const mockHtml = dataTableAdapter.render(vm, renderDataTableMock);
expect(defaultHtml.length).toBeGreaterThan(0);
expect(mockHtml.length).toBeGreaterThan(0);
// Chrome differs: only the implementation marker swaps.
expect(defaultHtml).toContain('data-ui-impl="subframe"');
expect(defaultHtml).not.toContain('data-ui-impl="mock"');
expect(mockHtml).toContain('data-ui-impl="mock"');
expect(mockHtml).not.toContain('data-ui-impl="subframe"');
expect(defaultHtml).not.toBe(mockHtml);
// Data is identical across implementations: all row ids and cell values present in both.
for (const html of [defaultHtml, mockHtml]) {
for (const row of vm.rows) {
expect(html).toContain(`data-row-id="${row.id}"`);
for (const value of Object.values(row.cells)) {
expect(html).toContain(value);
}
}
}
});
test("the default renderer is the real subframe implementation", () => {
expect(dataTableAdapter.name).toBe("dataTable");
expect(dataTableAdapter.render(vm)).toContain('data-ui-id="ui.data-table"');
});
});
@@ -0,0 +1,4 @@
export { defineAdapter, type Adapter, type DefineAdapterConfig } from "./defineAdapter.js";
export { dataTableAdapter, toDataTableModel } from "./dataTable.js";
export { fileBrowserAdapter, toFileBrowserModel } from "./fileBrowser.js";
export { taskListAdapter, toTaskListProps } from "./taskList.js";
@@ -0,0 +1,89 @@
import { describe, expect, test } from "vitest";
import type { TaskListData } from "@toolctrl/view-models";
import { renderTaskListMock } from "@toolctrl/ui-mock";
import { taskListAdapter } from "./taskList.js";
// Fixture display values come from variables, not inline `title:`/`label:`
// literals, to satisfy the Phase-C UI-package no-hardcoded-string lint rule
// (these are test data, not shipped copy).
const ROW1_TITLE = "Angebot nachfassen";
const ROW1_ASSIGNEE = "Akeshan";
const ROW2_TITLE = "Rechnung pruefen";
const ROW2_ASSIGNEE = "Buchhaltung";
const vm: TaskListData = {
rows: [
{
id: "task-1",
title: ROW1_TITLE,
status: "open",
statusKey: "tasks.status.open",
priority: "high",
priorityKey: "tasks.priority.high",
deadlineIso: "2026-06-25T08:00:00.000Z",
isOverdue: false,
assignee: { kind: "user", label: ROW1_ASSIGNEE },
linkedEntity: null,
source: "manual",
sourceKey: "tasks.source.manual",
sourceHref: null,
detailHref: "/acme/tasks/task-1",
},
{
id: "task-2",
title: ROW2_TITLE,
status: "in_progress",
statusKey: "tasks.status.in_progress",
priority: "normal",
priorityKey: "tasks.priority.normal",
deadlineIso: null,
isOverdue: false,
assignee: { kind: "group", label: ROW2_ASSIGNEE },
linkedEntity: null,
source: "automation",
sourceKey: "tasks.source.automation",
sourceHref: "/acme/automation/run-7",
detailHref: "/acme/tasks/task-2",
},
],
filter: { preset: "all", status: null, priority: null, assignedToUserId: null, includeArchived: false },
canWrite: true,
canDelete: false,
createHref: "/acme/tasks/new",
embed: null,
nextCursor: null,
emptyHeadlineKey: "tasks.list.empty.headline",
emptyBodyKey: "tasks.list.empty.body",
};
describe("taskListAdapter hot-swap (M017)", () => {
test("normalizes the VM once via toProps", () => {
const model = taskListAdapter.toProps(vm);
expect(model.rowCount).toBe(2);
expect(model.titleKey).toBe("tasks.list.title");
expect(model.rows.map((row) => row.id)).toEqual(["task-1", "task-2"]);
expect(model.rows[0]?.assigneeLabel).toBe("Akeshan");
});
test("swaps the render implementation without changing the data", () => {
const defaultHtml = taskListAdapter.render(vm);
const mockHtml = taskListAdapter.render(vm, renderTaskListMock);
expect(defaultHtml).toContain('data-ui-impl="subframe"');
expect(mockHtml).toContain('data-ui-impl="mock"');
expect(defaultHtml).not.toBe(mockHtml);
for (const html of [defaultHtml, mockHtml]) {
for (const row of vm.rows) {
expect(html).toContain(`data-row-id="${row.id}"`);
expect(html).toContain(row.title);
}
}
});
test("the default renderer is the real subframe implementation", () => {
expect(taskListAdapter.name).toBe("taskList");
expect(taskListAdapter.render(vm)).toContain('data-ui-id="ui.tasks.list"');
});
});
@@ -0,0 +1,21 @@
import { toTaskListModel, type TaskListData, type TaskListModel } from "@toolctrl/view-models";
import { renderTaskList } from "@toolctrl/ui-subframe";
import { defineAdapter } from "./defineAdapter.js";
/**
* Normalizes the domain {@link TaskListData} into the {@link TaskListModel}
* prop-model the UI implementation renders (M015). Reuses the VM's pure
* `toTaskListModel` mapper so the Subframe / mock renderers stay dumb and
* swappable (M017 hot-swap drill). Backs both the standalone `/tasks` browser
* and the embedded entity "Tasks tab" (DoD 8).
*/
export function toTaskListProps(vm: TaskListData): TaskListModel {
return toTaskListModel(vm);
}
export const taskListAdapter = defineAdapter({
name: "taskList",
toProps: toTaskListProps,
defaultRenderer: renderTaskList,
});