@cosmicdrift/kumiko-bundled-features 0.398.0 → 0.400.0

package/dist/documents/pending-file-guard.js

@@ -0,0 +1,29 @@
+import { createEntityExecutor, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import { FILE_REF_ENTITY_NAME, fileRefEntity } from "@cosmicdrift/kumiko-framework/files";
+import { DOCUMENT_ENTITY } from "./constants.js";
+const fileRefs = createEntityExecutor(FILE_REF_ENTITY_NAME, fileRefEntity).executor;
+// One live document per file (unique on tenant + file): a member who names a colleague's pending
+// upload would block the colleague's own later save of that file, because capture could no longer
+// create its document. Files a job made (system uploader) and files already bound to a record stay
+// allowed; for the latter the readGate's file-owner check covers it.
+export const rejectForeignPendingFile = async (changes, ctx) => {
+    const file = changes["file"];
+    if (typeof file !== "string" || file === ctx.previous["file"])
+        return changes;
+    if (ctx.user.roles.includes(SYSTEM_ROLE))
+        return changes;
+    const ref = await fileRefs.detail({ id: file }, createSystemUser(ctx.user.tenantId), ctx.db);
+    // skip: a missing file is rejected by the framework's own file-reference check
+    if (ref === null)
+        return changes;
+    const uploader = ref["insertedById"];
+    const unbound = ref["entityId"] === null || ref["entityId"] === undefined;
+    if (unbound &&
+        typeof uploader === "string" &&
+        uploader !== ctx.user.id &&
+        uploader !== SYSTEM_USER_ID) {
+        throw new NotFoundError(DOCUMENT_ENTITY, file);
+    }
+    return changes;
+};

package/dist/documents/queries/expiry-overview.query.d.ts

@@ -0,0 +1,10 @@
+import { type AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createExpiryOverviewQuery(access: AccessRule, expiringWithinDays: number): import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"expiry-overview", import("zod").ZodObject<{
+    entityType: import("zod").ZodOptional<import("zod").ZodString>;
+    entityId: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, {
+    expired: number;
+    expiring: number;
+    valid: number;
+    none: number;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/documents/queries/expiry-overview.query.js

@@ -0,0 +1,41 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { expiryWindow } from "../expiry.js";
+import { expiryOverviewPayloadSchema } from "../schemas.js";
+import { linkedDocumentIds, listDocuments } from "./list-page.js";
+// Counts come from the document list itself (totalCount), so they follow the same read gate
+// as the rows a user can open.
+export function createExpiryOverviewQuery(access, expiringWithinDays) {
+    return defineQueryHandler({
+        name: "expiry-overview",
+        schema: expiryOverviewPayloadSchema,
+        access,
+        liveEntities: ["filed-document", "filed-document-link"],
+        description: "Counts the documents the caller can read by validity: expired, expiring within the configured window, valid beyond it and without an expiry date; optionally for one record only.",
+        handler: async (query, ctx) => {
+            const payload = query.payload;
+            const { today, horizon } = expiryWindow(ctx, expiringWithinDays);
+            const scope = [];
+            if (payload.entityType !== undefined && payload.entityId !== undefined) {
+                const ids = await linkedDocumentIds(ctx, {
+                    entityType: payload.entityType,
+                    entityId: payload.entityId,
+                });
+                if (ids.length === 0)
+                    return { expired: 0, expiring: 0, valid: 0, none: 0 };
+                scope.push({ field: "id", op: "in", value: ids });
+            }
+            const count = async (extra) => (await listDocuments(ctx, { limit: 1, totalCount: true, filters: [...scope, ...extra] }))
+                .total ?? 0;
+            const [all, expired, expiring, valid] = await Promise.all([
+                count([]),
+                count([{ field: "validUntil", op: "lt", value: today }]),
+                count([
+                    { field: "validUntil", op: "gte", value: today },
+                    { field: "validUntil", op: "lte", value: horizon },
+                ]),
+                count([{ field: "validUntil", op: "gt", value: horizon }]),
+            ]);
+            return { expired, expiring, valid, none: all - expired - expiring - valid };
+        },
+    });
+}

package/dist/documents/queries/for-record.query.d.ts

@@ -0,0 +1,90 @@
+import { type AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createForRecordQuery(access: AccessRule, linkTargets: readonly string[]): import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"for-record", import("zod").ZodObject<{
+    entityType: import("zod").ZodString;
+    entityId: import("zod").ZodString;
+    limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    cursor: import("zod").ZodOptional<import("zod").ZodString>;
+    offset: import("zod").ZodOptional<import("zod").ZodNumber>;
+    search: import("zod").ZodOptional<import("zod").ZodString>;
+    sort: import("zod").ZodOptional<import("zod").ZodString>;
+    sortDirection: import("zod").ZodOptional<import("zod").ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    totalCount: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    filter: import("zod").ZodOptional<import("zod").ZodObject<{
+        field: import("zod").ZodString;
+        op: import("zod").ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: import("zod").ZodUnknown;
+    }, import("zod/v4/core").$strip>>;
+    filters: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+        field: import("zod").ZodString;
+        op: import("zod").ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: import("zod").ZodUnknown;
+    }, import("zod/v4/core").$strip>>>;
+}, import("zod/v4/core").$strip>, {
+    rows: Record<string, unknown>[];
+    nextCursor?: string | null | undefined;
+    total?: number | undefined;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export declare function forTypeQueryName(entityType: string): string;
+export declare function forTypeQueryQn(entityType: string): string;
+export declare function createForTypeQuery(access: AccessRule, linkTargets: readonly string[], entityType: string): import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<string, import("zod").ZodObject<{
+    limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    cursor: import("zod").ZodOptional<import("zod").ZodString>;
+    offset: import("zod").ZodOptional<import("zod").ZodNumber>;
+    search: import("zod").ZodOptional<import("zod").ZodString>;
+    sort: import("zod").ZodOptional<import("zod").ZodString>;
+    sortDirection: import("zod").ZodOptional<import("zod").ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    totalCount: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    filter: import("zod").ZodOptional<import("zod").ZodObject<{
+        field: import("zod").ZodString;
+        op: import("zod").ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: import("zod").ZodUnknown;
+    }, import("zod/v4/core").$strip>>;
+    filters: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+        field: import("zod").ZodString;
+        op: import("zod").ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: import("zod").ZodUnknown;
+    }, import("zod/v4/core").$strip>>>;
+    id: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, {
+    rows: Record<string, unknown>[];
+    nextCursor?: string | null | undefined;
+    total?: number | undefined;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/documents/queries/for-record.query.js

@@ -0,0 +1,54 @@
+import { defineQueryHandler, toKebab, } from "@cosmicdrift/kumiko-framework/engine";
+import { DocumentsQueries } from "../constants.js";
+import { forRecordPayloadSchema } from "../schemas.js";
+import { linkedDocumentIds, listDocuments } from "./list-page.js";
+const EMPTY_PAGE = { rows: [], nextCursor: null, total: 0 };
+const LIVE_ENTITIES = ["filed-document", "filed-document-link"];
+async function documentsOfRecord(ctx, linkTargets, payload) {
+    const { entityType, entityId, filter, filters, ...paging } = payload;
+    if (!linkTargets.includes(entityType))
+        return EMPTY_PAGE;
+    const ids = await linkedDocumentIds(ctx, { entityType, entityId });
+    if (ids.length === 0)
+        return EMPTY_PAGE;
+    return listDocuments(ctx, {
+        ...paging,
+        filters: [
+            { field: "id", op: "in", value: ids },
+            ...(filter !== undefined ? [filter] : []),
+            ...(filters ?? []),
+        ],
+    });
+}
+export function createForRecordQuery(access, linkTargets) {
+    return defineQueryHandler({
+        name: "for-record",
+        schema: forRecordPayloadSchema,
+        access,
+        liveEntities: LIVE_ENTITIES,
+        description: "Lists the documents linked to one record, paged and filterable like the document list; a record the caller cannot read, or a type that takes no documents, yields an empty page.",
+        handler: async (query, ctx) => documentsOfRecord(ctx, linkTargets, query.payload),
+    });
+}
+export function forTypeQueryName(entityType) {
+    return `for-${toKebab(entityType)}`;
+}
+export function forTypeQueryQn(entityType) {
+    return `${DocumentsQueries.forRecord.replace(/for-record$/, "")}${forTypeQueryName(entityType)}`;
+}
+// A relatedList tab sends only the parent id, so the host type is fixed per query.
+export function createForTypeQuery(access, linkTargets, entityType) {
+    return defineQueryHandler({
+        name: forTypeQueryName(entityType),
+        schema: forRecordPayloadSchema.omit({ entityType: true, entityId: true }).extend({
+            id: forRecordPayloadSchema.shape.entityId,
+        }),
+        access,
+        liveEntities: LIVE_ENTITIES,
+        description: `Lists the documents linked to one ${entityType} record by its id, paged and filterable like the document list; it feeds the documents tab on the ${entityType} screen.`,
+        handler: async (query, ctx) => {
+            const { id, ...rest } = query.payload;
+            return documentsOfRecord(ctx, linkTargets, { ...rest, entityType, entityId: id });
+        },
+    });
+}

package/dist/documents/queries/list-page.d.ts

@@ -0,0 +1,19 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+declare const pageSchema: z.ZodObject<{
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    nextCursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    total: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ListPage = z.infer<typeof pageSchema>;
+export type ListFilter = {
+    readonly field: string;
+    readonly op: string;
+    readonly value: unknown;
+};
+export declare function listDocuments(ctx: Pick<HandlerContext, "dispatch">, payload: Record<string, unknown>): Promise<ListPage>;
+export declare function linkedDocumentIds(ctx: Pick<HandlerContext, "dispatch">, target: {
+    readonly entityType: string;
+    readonly entityId: string;
+}): Promise<string[]>;
+export {};

package/dist/documents/queries/list-page.js

@@ -0,0 +1,36 @@
+import * as z from "zod";
+import { DocumentsQueries } from "../constants.js";
+const LINK_LIST = "documents:query:filed-document-link:list";
+const LINK_PAGE_SIZE = 200;
+const pageSchema = z.object({
+    rows: z.array(z.record(z.string(), z.unknown())),
+    nextCursor: z.string().nullable().optional(),
+    total: z.number().optional(),
+});
+export async function listDocuments(ctx, payload) {
+    return pageSchema.parse(await ctx.dispatch.query(DocumentsQueries.list, payload));
+}
+// Goes through the link list, so a record the caller cannot read yields no ids (the link's
+// parentRef gate), and a document is then fetched through the document list, which applies the
+// document's own read gate again.
+export async function linkedDocumentIds(ctx, target) {
+    const ids = [];
+    let cursor;
+    do {
+        const page = pageSchema.parse(await ctx.dispatch.query(LINK_LIST, {
+            filters: [
+                { field: "entityType", op: "eq", value: target.entityType },
+                { field: "entityId", op: "eq", value: target.entityId },
+            ],
+            limit: LINK_PAGE_SIZE,
+            ...(cursor !== undefined && { cursor }),
+        }));
+        for (const row of page.rows) {
+            const documentId = row["documentId"];
+            if (typeof documentId === "string")
+                ids.push(documentId);
+        }
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor !== undefined);
+    return ids;
+}

package/dist/documents/queries/overview.query.d.ts

@@ -0,0 +1,32 @@
+import { type AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createOverviewQuery(access: AccessRule, expiringWithinDays: number): import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"overview", import("zod").ZodObject<{
+    limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    cursor: import("zod").ZodOptional<import("zod").ZodString>;
+    offset: import("zod").ZodOptional<import("zod").ZodNumber>;
+    search: import("zod").ZodOptional<import("zod").ZodString>;
+    sort: import("zod").ZodOptional<import("zod").ZodString>;
+    sortDirection: import("zod").ZodOptional<import("zod").ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    totalCount: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    filters: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+        field: import("zod").ZodString;
+        op: import("zod").ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: import("zod").ZodUnknown;
+    }, import("zod/v4/core").$strip>>>;
+}, import("zod/v4/core").$strip>, {
+    nextCursor?: string | null | undefined;
+    total?: number | undefined;
+    rows: {
+        expiry: "expired" | "expiring" | "none" | "valid";
+    }[];
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/documents/queries/overview.query.js

@@ -0,0 +1,41 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { EXPIRING_FACET_VALUE } from "../constants.js";
+import { expiryStateOf, expiryWindow } from "../expiry.js";
+import { overviewPayloadSchema } from "../schemas.js";
+import { listDocuments } from "./list-page.js";
+const EXPIRY_FILTER_FIELD = "expiry";
+// The "expiring" facet is a moving date window, which a facet on a stored field cannot
+// express; it becomes a validUntil bound here, expired documents included. A document
+// without a date never matches it.
+function toDocumentFilters(filters, horizon) {
+    return filters.flatMap((clause) => {
+        if (clause.field !== EXPIRY_FILTER_FIELD)
+            return [clause];
+        const wantsExpiring = Array.isArray(clause.value) && clause.value.includes(EXPIRING_FACET_VALUE);
+        return wantsExpiring ? [{ field: "validUntil", op: "lte", value: horizon }] : [];
+    });
+}
+export function createOverviewQuery(access, expiringWithinDays) {
+    return defineQueryHandler({
+        name: "overview",
+        schema: overviewPayloadSchema,
+        access,
+        liveEntities: ["filed-document", "filed-document-link"],
+        description: "Lists the documents the caller can read with an expiry state per row (expired, expiring, valid, none); the expiring filter returns expired and soon-expiring documents. Powers the documents list screen.",
+        handler: async (query, ctx) => {
+            const { filters, ...paging } = query.payload;
+            const window = expiryWindow(ctx, expiringWithinDays);
+            const page = await listDocuments(ctx, {
+                ...paging,
+                filters: toDocumentFilters(filters ?? [], window.horizon),
+            });
+            return {
+                ...page,
+                rows: page.rows.map((row) => ({
+                    ...row,
+                    expiry: expiryStateOf(row["validUntil"], window),
+                })),
+            };
+        },
+    });
+}

package/dist/documents/schemas.d.ts

@@ -0,0 +1,93 @@
+import * as z from "zod";
+export declare const documentLinkPayloadSchema: z.ZodObject<{
+    documentId: z.ZodUUID;
+    entityType: z.ZodString;
+    entityId: z.ZodString;
+}, z.core.$strip>;
+export type DocumentLinkPayload = z.infer<typeof documentLinkPayloadSchema>;
+export declare const importDocumentPayloadSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    title: z.ZodString;
+    category: z.ZodString;
+    issuedAt: z.ZodOptional<z.ZodISODate>;
+    validUntil: z.ZodOptional<z.ZodISODate>;
+    fileRefId: z.ZodUUID;
+    links: z.ZodArray<z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+    }, z.core.$strip>>;
+    deleted: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ImportDocumentPayload = z.infer<typeof importDocumentPayloadSchema>;
+export declare const forRecordPayloadSchema: z.ZodObject<{
+    entityType: z.ZodString;
+    entityId: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    search: z.ZodOptional<z.ZodString>;
+    sort: z.ZodOptional<z.ZodString>;
+    sortDirection: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    totalCount: z.ZodOptional<z.ZodBoolean>;
+    filter: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ForRecordPayload = z.infer<typeof forRecordPayloadSchema>;
+export declare const overviewPayloadSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    search: z.ZodOptional<z.ZodString>;
+    sort: z.ZodOptional<z.ZodString>;
+    sortDirection: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    totalCount: z.ZodOptional<z.ZodBoolean>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type OverviewPayload = z.infer<typeof overviewPayloadSchema>;
+export declare const expiryOverviewPayloadSchema: z.ZodObject<{
+    entityType: z.ZodOptional<z.ZodString>;
+    entityId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ExpiryOverviewPayload = z.infer<typeof expiryOverviewPayloadSchema>;

package/dist/documents/schemas.js

@@ -0,0 +1,51 @@
+import * as z from "zod";
+export const documentLinkPayloadSchema = z.object({
+    documentId: z.uuid(),
+    entityType: z.string().min(1).max(64),
+    entityId: z.string().min(1).max(128),
+});
+const isoDate = z.iso.date();
+export const importDocumentPayloadSchema = z.object({
+    id: z.uuid(),
+    title: z.string().trim().min(1).max(200),
+    category: z.string().min(1),
+    issuedAt: isoDate.optional(),
+    validUntil: isoDate.optional(),
+    fileRefId: z.uuid(),
+    links: z.array(z.object({ entityType: z.string().min(1).max(64), entityId: z.string().min(1).max(128) })),
+    deleted: z.boolean().optional(),
+});
+export const forRecordPayloadSchema = z.object({
+    entityType: z.string().min(1).max(64),
+    entityId: z.string().min(1).max(128),
+    limit: z.number().int().nonnegative().max(200).optional(),
+    cursor: z.string().optional(),
+    offset: z.number().int().nonnegative().optional(),
+    search: z.string().optional(),
+    sort: z.string().optional(),
+    sortDirection: z.enum(["asc", "desc"]).optional(),
+    totalCount: z.boolean().optional(),
+    filter: z
+        .object({
+        field: z.string(),
+        op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
+        value: z.unknown(),
+    })
+        .optional(),
+    filters: z
+        .array(z.object({
+        field: z.string(),
+        op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
+        value: z.unknown(),
+    }))
+        .optional(),
+});
+export const overviewPayloadSchema = forRecordPayloadSchema.omit({
+    entityType: true,
+    entityId: true,
+    filter: true,
+});
+export const expiryOverviewPayloadSchema = z.object({
+    entityType: z.string().min(1).max(64).optional(),
+    entityId: z.string().min(1).max(128).optional(),
+});

package/dist/documents/screens.d.ts

@@ -0,0 +1,3 @@
+import { type AccessRule, type ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare const DOCUMENT_COLUMNS: readonly ["title", "category", "validUntil", "file"];
+export declare function createDocumentListScreen(access: AccessRule, categories: readonly string[]): ProjectionListScreenDefinition;

package/dist/documents/screens.js

@@ -0,0 +1,76 @@
+import { i18nKey, } from "@cosmicdrift/kumiko-framework/engine";
+import { DOCUMENTS_LIST_SCREEN_ID, DocumentsQueries, EXPIRING_FACET_VALUE } from "./constants.js";
+// The columns every document list shows; the tab and the standalone screen stay alike.
+export const DOCUMENT_COLUMNS = ["title", "category", "validUntil", "file"];
+const FIELD_PREFIX = "documents:entity:filed-document:field:";
+const CATEGORY_OPTION_PREFIX = `${FIELD_PREFIX}category:option:`;
+// A projectionList, not an entityList: the expiry state and its "expiring" filter are computed
+// per request from a moving date window, which an entityList's facets on stored fields cannot
+// express. The overview query still reads through the document list, so the read gate holds.
+export function createDocumentListScreen(access, categories) {
+    return {
+        id: DOCUMENTS_LIST_SCREEN_ID,
+        type: "projectionList",
+        query: DocumentsQueries.overview,
+        columns: [
+            { field: "title", label: `${FIELD_PREFIX}title` },
+            {
+                field: "category",
+                label: `${FIELD_PREFIX}category`,
+                renderer: { format: "enumOption", keyPrefix: CATEGORY_OPTION_PREFIX },
+            },
+            {
+                field: "validUntil",
+                label: `${FIELD_PREFIX}validUntil`,
+                renderer: { format: "date", dateStyle: "medium" },
+            },
+            {
+                field: "expiry",
+                label: "documents:list.facet.expiry",
+                sortable: false,
+                hideOnNarrow: true,
+                renderer: { format: "enumOption", keyPrefix: "documents:list.expiry." },
+            },
+            {
+                field: "file",
+                label: `${FIELD_PREFIX}file`,
+                sortable: false,
+                renderer: { format: "file" },
+            },
+        ],
+        pagination: "pages",
+        defaultSort: { field: "validUntil", dir: "asc" },
+        searchable: true,
+        facets: [
+            {
+                field: "category",
+                type: "select",
+                label: `${FIELD_PREFIX}category`,
+                options: categories.map((value) => ({
+                    value,
+                    label: `${CATEGORY_OPTION_PREFIX}${value}`,
+                })),
+            },
+            {
+                field: "expiry",
+                type: "select",
+                label: "documents:list.facet.expiry",
+                options: [{ value: EXPIRING_FACET_VALUE, label: "documents:list.facet.expiring" }],
+            },
+        ],
+        rowActions: [
+            {
+                kind: "writeHandler",
+                id: "delete",
+                label: i18nKey("kumiko.actions.delete"),
+                handler: "documents:write:filed-document:delete",
+                payload: { pick: ["id"] },
+                confirm: i18nKey("kumiko.actions.delete-confirm"),
+                style: "danger",
+            },
+        ],
+        access,
+        // The app places it with r.nav("documents:screen:list").
+        dormant: true,
+    };
+}

package/dist/documents/tab.d.ts

@@ -0,0 +1,4 @@
+import type { EditRelatedListSection } from "@cosmicdrift/kumiko-framework/engine";
+import type { DashboardStatPanel } from "@cosmicdrift/kumiko-framework/ui-types";
+export declare function documentsTab(entityType: string): EditRelatedListSection;
+export declare function documentExpiryPanels(): readonly DashboardStatPanel[];

package/dist/documents/tab.js

@@ -0,0 +1,42 @@
+import { DocumentsQueries } from "./constants.js";
+import { forTypeQueryQn } from "./queries/for-record.query.js";
+// "Documents" tab for the edit screen of a link target. The tab id is the same on every screen,
+// so deep links like ?tab=documents work across hosts.
+export function documentsTab(entityType) {
+    return {
+        id: "documents",
+        kind: "relatedList",
+        title: "documents:tab.title",
+        query: forTypeQueryQn(entityType),
+        entity: "documents:document",
+        columns: [
+            { field: "title", sortable: true },
+            { field: "category", sortable: true },
+            { field: "validUntil", sortable: true },
+            { field: "file" },
+        ],
+        searchable: true,
+        count: true,
+    };
+}
+// Stat tiles for a dashboard: how many readable documents are expired or about to expire.
+export function documentExpiryPanels() {
+    return [
+        {
+            kind: "stat",
+            id: "documents-expired",
+            label: "documents:overview.expired",
+            query: DocumentsQueries.expiryOverview,
+            valueField: "expired",
+            tone: "negative",
+        },
+        {
+            kind: "stat",
+            id: "documents-expiring",
+            label: "documents:overview.expiring",
+            query: DocumentsQueries.expiryOverview,
+            valueField: "expiring",
+            tone: "warn",
+        },
+    ];
+}

package/dist/documents/target-write-check.d.ts

@@ -0,0 +1,3 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { type Registry, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+export declare function canWriteLinkTarget(registry: Registry, entityType: string, entityId: string, user: SessionUser, db: TenantDb): Promise<boolean>;