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,121 @@
import type { VMState } from "../index.js";
/**
* Files browser view-model (AK-P4a §9). Pure function: the loader builds it once
* server-side, the UI only renders. No React, no Prisma, no app imports
* (DoD A.3). All texts are i18n keys.
*
* URLs (`thumbnailUrl`, `detailHref`) ALWAYS point at the auth-proxy route
* (AD-23) or internal routes, NEVER at a raw S3 URL — the loader builds them and
* passes them in here so the VM stays routing-agnostic + pure.
*/
export type FilePreviewStatus = "pending" | "generating" | "ready" | "failed" | "not_supported";
export type FileScanStatus = "pending" | "clean" | "infected" | "skipped";
export type FileViewMode = "table" | "grid";
export interface FileBrowserRow {
readonly id: string;
readonly displayName: string;
readonly mimeType: string;
readonly sizeBytes: number;
readonly createdAtIso: string;
readonly tags: readonly string[];
readonly source: string;
readonly previewStatus: FilePreviewStatus;
readonly scanStatus: FileScanStatus;
/** Proxy-route URL of the thumbnail (or null while not yet `ready`). */
readonly thumbnailUrl: string | null;
/** Internal detail route (e.g. `/acme/files/<id>`). */
readonly detailHref: string;
/** Label of the linked target entity (i18n key) or null. */
readonly linkedEntityLabelKey: string | null;
}
export interface FileBrowserFilterState {
readonly entityType: string | null;
readonly mimeGroup: string | null;
readonly tags: readonly string[];
readonly assignedToUserId: string | null;
readonly includeArchived: boolean;
}
export interface FileBrowserData {
readonly viewMode: FileViewMode;
readonly rows: readonly FileBrowserRow[];
readonly filter: FileBrowserFilterState;
readonly canWrite: boolean;
readonly canDelete: boolean;
/** Cursor of the next page (null = last page). */
readonly nextCursor: string | null;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
}
export type FileBrowserVM = VMState<FileBrowserData>;
/**
* Normalized prop-model the UI implementation renders (M015 Subframe-adapter
* contract). The ui-app adapter maps {@link FileBrowserData} -> this model once,
* then the ui-subframe / ui-mock renderers stay dumb (hot-swap drill, M017).
*/
export interface FileBrowserModelRow {
readonly id: string;
readonly displayName: string;
readonly mimeType: string;
readonly sizeBytes: number;
readonly detailHref: string;
readonly thumbnailUrl: string | null;
}
export interface FileBrowserModel {
readonly titleKey: string;
readonly emptyHeadlineKey: string;
readonly emptyBodyKey: string;
readonly canWrite: boolean;
readonly rows: readonly FileBrowserModelRow[];
readonly rowCount: number;
}
export interface BuildFileBrowserVMInput {
readonly viewMode?: FileViewMode;
readonly rows: readonly FileBrowserRow[];
readonly filter: FileBrowserFilterState;
readonly canWrite: boolean;
readonly canDelete: boolean;
readonly nextCursor?: string | null;
}
export function buildFileBrowserVM(input: BuildFileBrowserVMInput): FileBrowserVM {
const viewMode: FileViewMode = input.viewMode ?? "table";
if (input.rows.length === 0) {
// Empty stays a `ready` state with a plain-text empty state (DoD 23) so the
// filter/toggle bar and upload CTA remain visible.
return {
status: "ready",
data: {
viewMode,
rows: [],
filter: input.filter,
canWrite: input.canWrite,
canDelete: input.canDelete,
nextCursor: null,
emptyHeadlineKey: "files.browser.empty.headline",
emptyBodyKey: "files.browser.empty.body",
},
};
}
return {
status: "ready",
data: {
viewMode,
rows: input.rows,
filter: input.filter,
canWrite: input.canWrite,
canDelete: input.canDelete,
nextCursor: input.nextCursor ?? null,
emptyHeadlineKey: "files.browser.empty.headline",
emptyBodyKey: "files.browser.empty.body",
},
};
}
@@ -0,0 +1,106 @@
import type { VMState } from "../index.js";
import type { FilePreviewStatus, FileScanStatus } from "./file-browser.vm.js";
/**
* File detail view-model (AK-P4a §9). Pure function, i18n keys only.
* Preview/download URLs point at the auth-proxy route (AD-23).
*/
export interface FileLinkedEntity {
readonly entityType: string;
readonly entityId: string;
readonly linkRole: string | null;
/** Internal route to the target entity (loader-built) or null. */
readonly href: string | null;
}
export interface FileDetailData {
readonly id: string;
readonly displayName: string;
readonly mimeType: string;
readonly sizeBytes: number;
readonly createdAtIso: string;
readonly tags: readonly string[];
readonly notes: string | null;
readonly source: string;
readonly previewStatus: FilePreviewStatus;
readonly scanStatus: FileScanStatus;
/** Proxy URL of the preview (or null). */
readonly previewUrl: string | null;
/** Proxy URL of the original for download. */
readonly downloadUrl: string;
readonly assignedToUserId: string | null;
readonly linkedEntities: readonly FileLinkedEntity[];
/** Plain-text hint key when previewStatus=not_supported/failed. */
readonly previewFallbackKey: string | null;
/** Plain-text key when scanStatus=infected (download blocked) or pending. */
readonly scanNoticeKey: string | null;
readonly canWrite: boolean;
readonly canDelete: boolean;
readonly canAdmin: boolean;
/** Regenerating the preview only makes sense when it failed. */
readonly canRegeneratePreview: boolean;
}
export type FileDetailVM = VMState<FileDetailData>;
export interface BuildFileDetailVMInput {
readonly id: string;
readonly displayName: string;
readonly mimeType: string;
readonly sizeBytes: number;
readonly createdAtIso: string;
readonly tags: readonly string[];
readonly notes: string | null;
readonly source: string;
readonly previewStatus: FilePreviewStatus;
readonly scanStatus: FileScanStatus;
readonly previewUrl: string | null;
readonly downloadUrl: string;
readonly assignedToUserId: string | null;
readonly linkedEntities: readonly FileLinkedEntity[];
readonly canWrite: boolean;
readonly canDelete: boolean;
readonly canAdmin: boolean;
}
function previewFallbackKey(status: FilePreviewStatus): string | null {
if (status === "not_supported") return "files.detail.preview.notSupported";
if (status === "failed") return "files.detail.preview.failed";
if (status === "pending" || status === "generating") return "files.detail.preview.pending";
return null;
}
function scanNoticeKey(status: FileScanStatus): string | null {
if (status === "infected") return "files.detail.scan.infected";
if (status === "pending") return "files.detail.scan.pending";
return null;
}
export function buildFileDetailVM(input: BuildFileDetailVMInput): FileDetailVM {
return {
status: "ready",
data: {
id: input.id,
displayName: input.displayName,
mimeType: input.mimeType,
sizeBytes: input.sizeBytes,
createdAtIso: input.createdAtIso,
tags: input.tags,
notes: input.notes,
source: input.source,
previewStatus: input.previewStatus,
scanStatus: input.scanStatus,
// An infected file never exposes a preview URL (fail-closed).
previewUrl: input.scanStatus === "infected" ? null : input.previewUrl,
downloadUrl: input.downloadUrl,
assignedToUserId: input.assignedToUserId,
linkedEntities: input.linkedEntities,
previewFallbackKey: previewFallbackKey(input.previewStatus),
scanNoticeKey: scanNoticeKey(input.scanStatus),
canWrite: input.canWrite,
canDelete: input.canDelete,
canAdmin: input.canAdmin,
canRegeneratePreview: input.canWrite && input.previewStatus === "failed",
},
};
}
@@ -0,0 +1,63 @@
import type { VMState } from "../index.js";
/**
* Upload view view-model (AK-P4a §9). Pure function, i18n keys only.
* Describes the multi-file queue with per-file progress + plain-text errors
* (HEIC hint, too large, MIME blocked, network abort).
*/
export type FileUploadItemStatus = "queued" | "uploading" | "processing" | "done" | "error";
export interface FileUploadQueueItem {
readonly clientId: string;
readonly filename: string;
readonly sizeBytes: number;
readonly status: FileUploadItemStatus;
/** 0..100 */
readonly progressPercent: number;
/** i18n key of the error message (only when status=error). */
readonly errorKey: string | null;
/** Plain-text hint key (e.g. HEIC will be converted to JPG). */
readonly noticeKey: string | null;
readonly canRetry: boolean;
}
export interface FileUploadData {
readonly canWrite: boolean;
readonly chunkSizeBytes: number;
readonly maxFileSizeBytes: number;
readonly maxParallelUploads: number;
readonly items: readonly FileUploadQueueItem[];
readonly dropzoneHeadlineKey: string;
readonly dropzoneBodyKey: string;
readonly heicNoticeKey: string;
}
export type FileUploadVM = VMState<FileUploadData>;
export const FILE_UPLOAD_CHUNK_SIZE_BYTES = 5 * 1024 * 1024; // 5 MB
export const FILE_UPLOAD_MAX_FILE_SIZE_BYTES = 500 * 1024 * 1024; // 500 MB
export const FILE_UPLOAD_MAX_PARALLEL = 3;
export interface BuildFileUploadVMInput {
readonly canWrite: boolean;
readonly items?: readonly FileUploadQueueItem[];
readonly chunkSizeBytes?: number;
readonly maxFileSizeBytes?: number;
readonly maxParallelUploads?: number;
}
export function buildFileUploadVM(input: BuildFileUploadVMInput): FileUploadVM {
return {
status: "ready",
data: {
canWrite: input.canWrite,
chunkSizeBytes: input.chunkSizeBytes ?? FILE_UPLOAD_CHUNK_SIZE_BYTES,
maxFileSizeBytes: input.maxFileSizeBytes ?? FILE_UPLOAD_MAX_FILE_SIZE_BYTES,
maxParallelUploads: input.maxParallelUploads ?? FILE_UPLOAD_MAX_PARALLEL,
items: input.items ?? [],
dropzoneHeadlineKey: "files.upload.dropzone.headline",
dropzoneBodyKey: "files.upload.dropzone.body",
heicNoticeKey: "files.upload.notice.heic",
},
};
}
@@ -0,0 +1,115 @@
import { describe, expect, it } from "vitest";
import {
buildFileBrowserVM,
buildFileDetailVM,
buildFileUploadVM,
FILE_UPLOAD_CHUNK_SIZE_BYTES,
FILE_UPLOAD_MAX_FILE_SIZE_BYTES,
type BuildFileDetailVMInput,
type FileBrowserFilterState,
type FileBrowserRow,
} from "../index.js";
const I18N_KEY = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
const filter: FileBrowserFilterState = {
entityType: null,
mimeGroup: null,
tags: [],
assignedToUserId: null,
includeArchived: false,
};
describe("buildFileBrowserVM", () => {
it("returns a ready empty-state with i18n keys when there are no rows", () => {
const vm = buildFileBrowserVM({ rows: [], filter, canWrite: true, canDelete: false });
expect(vm.status).toBe("ready");
if (vm.status !== "ready") throw new Error("expected ready");
expect(vm.data.rows).toHaveLength(0);
expect(vm.data.viewMode).toBe("table");
expect(vm.data.emptyHeadlineKey).toMatch(I18N_KEY);
expect(vm.data.emptyBodyKey).toMatch(I18N_KEY);
});
it("passes rows through and honours the view mode + cursor", () => {
const row: FileBrowserRow = {
id: "f1",
displayName: "foto.heic",
mimeType: "image/heic",
sizeBytes: 1234,
createdAtIso: "2026-06-19T08:00:00.000Z",
tags: ["baustelle"],
source: "manual_upload",
previewStatus: "ready",
scanStatus: "clean",
thumbnailUrl: "/acme/media/f1/thumb",
detailHref: "/acme/files/f1",
linkedEntityLabelKey: null,
};
const vm = buildFileBrowserVM({ viewMode: "grid", rows: [row], filter, canWrite: true, canDelete: true, nextCursor: "cur2" });
if (vm.status !== "ready") throw new Error("expected ready");
expect(vm.data.viewMode).toBe("grid");
expect(vm.data.rows[0]?.thumbnailUrl).toBe("/acme/media/f1/thumb");
expect(vm.data.nextCursor).toBe("cur2");
// Proxy/intern, nie rohe S3-URL.
expect(vm.data.rows[0]?.thumbnailUrl?.startsWith("http")).toBe(false);
});
});
describe("buildFileDetailVM", () => {
const base: BuildFileDetailVMInput = {
id: "f1",
displayName: "vertrag.pdf",
mimeType: "application/pdf",
sizeBytes: 9999,
createdAtIso: "2026-06-19T08:00:00.000Z",
tags: [],
notes: null,
source: "manual_upload",
previewStatus: "ready",
scanStatus: "clean",
previewUrl: "/acme/media/f1/preview",
downloadUrl: "/acme/media/f1/original",
assignedToUserId: null,
linkedEntities: [],
canWrite: true,
canDelete: false,
canAdmin: false,
};
it("withholds the preview URL when the file is infected (fail-closed)", () => {
const vm = buildFileDetailVM({ ...base, scanStatus: "infected", previewUrl: "/acme/media/f1/preview" });
if (vm.status !== "ready") throw new Error("expected ready");
expect(vm.data.previewUrl).toBeNull();
expect(vm.data.scanNoticeKey).toMatch(I18N_KEY);
});
it("offers regenerate only for writers on a failed preview", () => {
expect(buildFileDetailVM({ ...base, previewStatus: "failed" }).status).toBe("ready");
const failedWriter = buildFileDetailVM({ ...base, previewStatus: "failed", canWrite: true });
const failedReader = buildFileDetailVM({ ...base, previewStatus: "failed", canWrite: false });
if (failedWriter.status !== "ready" || failedReader.status !== "ready") throw new Error("expected ready");
expect(failedWriter.data.canRegeneratePreview).toBe(true);
expect(failedReader.data.canRegeneratePreview).toBe(false);
expect(failedWriter.data.previewFallbackKey).toMatch(I18N_KEY);
});
it("emits a not-supported fallback key", () => {
const vm = buildFileDetailVM({ ...base, previewStatus: "not_supported", previewUrl: null });
if (vm.status !== "ready") throw new Error("expected ready");
expect(vm.data.previewFallbackKey).toBe("files.detail.preview.notSupported");
});
});
describe("buildFileUploadVM", () => {
it("exposes the chunk/size/parallel defaults and i18n keys", () => {
const vm = buildFileUploadVM({ canWrite: true });
if (vm.status !== "ready") throw new Error("expected ready");
expect(vm.data.chunkSizeBytes).toBe(FILE_UPLOAD_CHUNK_SIZE_BYTES);
expect(vm.data.maxFileSizeBytes).toBe(FILE_UPLOAD_MAX_FILE_SIZE_BYTES);
expect(vm.data.maxParallelUploads).toBe(3);
expect(vm.data.heicNoticeKey).toMatch(I18N_KEY);
expect(vm.data.dropzoneHeadlineKey).toMatch(I18N_KEY);
});
});