@cosmicdrift/kumiko-samples 0.421.0 → 0.424.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +11 -1
  3. package/packages/bundled-features/src/document-draft/README.md +84 -0
  4. package/packages/bundled-features/src/document-draft/changes.json +8 -0
  5. package/packages/bundled-features/src/document-draft/entity.ts +125 -0
  6. package/packages/bundled-features/src/document-draft/feature.ts +56 -0
  7. package/packages/bundled-features/src/document-draft/handlers/blocks.query.ts +63 -0
  8. package/packages/bundled-features/src/document-draft/handlers/by-subject.query.ts +50 -0
  9. package/packages/bundled-features/src/document-draft/handlers/create.write.ts +110 -0
  10. package/packages/bundled-features/src/document-draft/handlers/discard.write.ts +32 -0
  11. package/packages/bundled-features/src/document-draft/handlers/finalize.write.ts +103 -0
  12. package/packages/bundled-features/src/document-draft/handlers/patch.write.ts +86 -0
  13. package/packages/bundled-features/src/document-draft/handlers/revise.write.ts +46 -0
  14. package/packages/bundled-features/src/document-draft/handlers/save.write.ts +53 -0
  15. package/packages/bundled-features/src/document-draft/i18n.ts +22 -0
  16. package/packages/bundled-features/src/document-draft/index.ts +21 -0
  17. package/packages/bundled-features/src/document-draft/lib.ts +77 -0
  18. package/packages/bundled-features/src/document-draft/options.ts +51 -0
  19. package/packages/bundled-features/src/document-draft/payloads.ts +45 -0
  20. package/packages/bundled-features/src/document-draft/screens/editor-screen.ts +17 -0
  21. package/packages/bundled-features/src/document-draft/user-data.ts +63 -0
  22. package/packages/bundled-features/src/document-draft/web/client-plugin.tsx +20 -0
  23. package/packages/bundled-features/src/document-draft/web/constants.ts +56 -0
  24. package/packages/bundled-features/src/document-draft/web/editor-screen.tsx +418 -0
  25. package/packages/bundled-features/src/document-draft/web/i18n.ts +54 -0
  26. package/packages/bundled-features/src/document-draft/web/index.ts +14 -0
  27. package/packages/bundled-features/src/helpdesk/changes.json +6 -0
  28. package/packages/bundled-features/src/shared/index.ts +6 -0
  29. package/packages/bundled-features/src/{signature → shared}/subject-scope.ts +17 -6
  30. package/packages/bundled-features/src/signature/changes.json +6 -0
  31. package/packages/bundled-features/src/signature/feature.ts +1 -1
  32. package/packages/bundled-features/src/signature/handlers/cancel.write.ts +1 -1
  33. package/packages/bundled-features/src/signature/handlers/issue-link.write.ts +1 -1
  34. package/packages/bundled-features/src/signature/handlers/request.write.ts +1 -1
  35. package/packages/bundled-features/src/signature/handlers/revoke-link.write.ts +1 -1
  36. package/packages/bundled-features/src/signature/handlers/sign-in-person.write.ts +1 -1
  37. package/packages/bundled-features/src/signature/options.ts +2 -1
  38. package/packages/bundled-features/src/signature/subject-queries.ts +1 -1
  39. package/packages/bundled-features/src/template-resolver/README.md +1 -0
  40. package/packages/bundled-features/src/template-resolver/api.ts +3 -1
  41. package/packages/bundled-features/src/template-resolver/boot-rules.ts +5 -0
  42. package/packages/bundled-features/src/template-resolver/changes.json +36 -0
  43. package/packages/bundled-features/src/template-resolver/compile-document-body.ts +51 -6
  44. package/packages/bundled-features/src/template-resolver/document-print-only.ts +1 -0
  45. package/packages/bundled-features/src/template-resolver/feature.ts +15 -1
  46. package/packages/bundled-features/src/template-resolver/handlers/create-variant.write.ts +134 -0
  47. package/packages/bundled-features/src/template-resolver/handlers/document-base.ts +3 -0
  48. package/packages/bundled-features/src/template-resolver/handlers/overview.query.ts +44 -1
  49. package/packages/bundled-features/src/template-resolver/handlers/patch-draft.write.ts +12 -1
  50. package/packages/bundled-features/src/template-resolver/handlers/template-write.ts +111 -11
  51. package/packages/bundled-features/src/template-resolver/handlers/toggle-status.write.ts +29 -4
  52. package/packages/bundled-features/src/template-resolver/handlers/upsert-tenant.write.ts +1 -0
  53. package/packages/bundled-features/src/template-resolver/handlers/variants.query.ts +89 -0
  54. package/packages/bundled-features/src/template-resolver/i18n.ts +1 -0
  55. package/packages/bundled-features/src/template-resolver/index.ts +26 -0
  56. package/packages/bundled-features/src/template-resolver/seeding.ts +16 -1
  57. package/packages/bundled-features/src/template-resolver/template-delivery-policy.ts +56 -6
  58. package/packages/bundled-features/src/template-resolver/template-edit-policy.ts +5 -5
  59. package/packages/bundled-features/src/template-resolver/template-meta.ts +1 -0
  60. package/packages/bundled-features/src/template-resolver/template-variants.ts +50 -0
  61. package/packages/bundled-features/src/template-resolver/web/document-images.ts +29 -8
  62. package/packages/bundled-features/src/template-resolver/web/document-tiptap-content.tsx +10 -1
  63. package/packages/bundled-features/src/template-resolver/web/document-tiptap-toolbar.tsx +10 -4
  64. package/packages/bundled-features/src/template-resolver/web/i18n.ts +26 -0
  65. package/packages/bundled-features/src/template-resolver/web/index.ts +5 -0
  66. package/packages/bundled-features/src/template-resolver/web/qualified-names.ts +5 -0
  67. package/packages/bundled-features/src/template-resolver/web/system-placeholders.ts +17 -0
  68. package/packages/bundled-features/src/tenant/changes.json +7 -0
  69. package/packages/bundled-features/src/tenant/handlers/update-member-roles.write.ts +1 -1
  70. package/packages/bundled-features/src/tenant/i18n.ts +0 -1
  71. package/packages/bundled-features/src/tenant-inactivity/changes.json +7 -0
  72. package/packages/bundled-features/src/tenant-inactivity/constants.ts +1 -1
  73. package/packages/bundled-features/src/tenant-lifecycle/changes.json +7 -0
  74. package/packages/bundled-features/src/tenant-lifecycle/constants.ts +1 -1
  75. package/samples/apps/ui-walkthrough/src/run-config.ts +1 -0
  76. package/samples/apps/use-all-bundled/feature-manifest.json +37 -1
  77. package/samples/apps/use-all-bundled/kumiko/migrations/0069_document-draft.rebuild.json +4 -0
  78. package/samples/apps/use-all-bundled/src/app/client.tsx +3 -0
  79. package/samples/apps/use-all-bundled/src/run-config.ts +8 -0
  80. package/samples/recipes/list-table-options/README.md +9 -1
  81. package/samples/recipes/list-table-options/src/feature.ts +28 -1
@@ -1,3 +1,4 @@
1
+ import { isDeepStrictEqual } from "node:util";
1
2
  import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
2
3
  import {
3
4
  type HandlerContext,
@@ -6,6 +7,7 @@ import {
6
7
  SYSTEM_TENANT_ID,
7
8
  type TemplateVariables,
8
9
  type TenantId,
10
+ type TenantWriteTarget,
9
11
  type WriteResult,
10
12
  } from "@cosmicdrift/kumiko-framework/engine";
11
13
  import {
@@ -15,18 +17,23 @@ import {
15
17
  type WriteFailure,
16
18
  writeFailure,
17
19
  } from "@cosmicdrift/kumiko-framework/errors";
20
+ import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
18
21
  import { requireForTenant } from "../../shared/index.ts";
22
+ import { patchIssue } from "../document-op-blocks.ts";
19
23
  import type { TemplateWriteScope } from "../layout-regions.ts";
20
24
  import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
21
- import { activationChanges, serializeTemplateDraft } from "../template-draft.ts";
25
+ import { deliveryPolicyOf, findVariantsEntry } from "../template-delivery-policy.ts";
26
+ import { activationChanges, serializeTemplateDraft, toWorkingRow } from "../template-draft.ts";
22
27
  import { refuseReservedSystemLayoutSlug } from "../template-edit-policy.ts";
23
28
  import { isSystemOnlyTemplate } from "../template-system-only.ts";
24
- import type { TemplateValidation } from "../template-validation.ts";
29
+ import { resolveTemplateVariables, type TemplateValidation } from "../template-validation.ts";
30
+ import { readVariantOf, VARIANT_KIND, variantOfMatchesSlug } from "../template-variants.ts";
25
31
  import type { ContentFormat, TemplateKind } from "../web/constants.ts";
26
32
  import { TemplateResolverErrors } from "../web/qualified-names.ts";
27
33
  import { executor } from "./shared.ts";
28
34
  import {
29
35
  evaluateTemplateWrite,
36
+ parseStoredJson,
30
37
  type TemplateWriteInput,
31
38
  type TemplateWriteResult,
32
39
  } from "./template-gates.ts";
@@ -48,6 +55,7 @@ export type WrittenTemplateRow = {
48
55
  readonly id: string;
49
56
  readonly slug: string;
50
57
  readonly isNew: boolean;
58
+ readonly version: number;
51
59
  readonly validation: TemplateValidation | null;
52
60
  };
53
61
 
@@ -59,6 +67,10 @@ export type TemplateRowWrite = {
59
67
  readonly status: "draft" | "active";
60
68
  readonly variables: TemplateVariables;
61
69
  readonly payload: TemplateRowPayload;
70
+ /** Stored linkedResources JSON for a row that is created; an update never touches them. */
71
+ readonly linkedResources?: string;
72
+ /** The caller typed this schema itself (upsert); a variant then must match its base instead of being re-synced. */
73
+ readonly explicitVariableSchema?: true;
62
74
  /** The row version the edit was made against; null means no own row may exist yet. */
63
75
  readonly expectedVersion?: number | null;
64
76
  };
@@ -170,6 +182,91 @@ function versionConflictFor(
170
182
  );
171
183
  }
172
184
 
185
+ // A tenant row under `<base>:<name>` of a base with variants must declare that base; otherwise the
186
+ // policy would serve it as a variant while schema sync never runs for it.
187
+ function refuseVariantOfSlugMismatch(
188
+ registry: HandlerContext["registry"],
189
+ scope: TemplateWriteScope,
190
+ payload: TemplateRowWrite["payload"],
191
+ ): WriteFailure | null {
192
+ const declaredBase = readVariantOf(payload.meta);
193
+ const requiredBase =
194
+ scope === "tenant"
195
+ ? findVariantsEntry(deliveryPolicyOf(registry).tenantEditable, payload)?.slug
196
+ : undefined;
197
+ const missesRequiredBase = requiredBase !== undefined && declaredBase !== requiredBase;
198
+ if (!missesRequiredBase && variantOfMatchesSlug(payload.slug, payload.meta)) return null;
199
+ return writeFailure(
200
+ new ValidationError({ fields: [patchIssue("meta.variantOf", "invalid_variant_of")] }),
201
+ );
202
+ }
203
+
204
+ function storedKeyOf(data: unknown): { readonly id: string; readonly version: number } {
205
+ const id = propertyOf(data, "id");
206
+ const version = propertyOf(propertyOf(data, "data"), "version");
207
+ if ((typeof id !== "string" && typeof id !== "number") || typeof version !== "number") {
208
+ throw new Error("template write: executor result carries no id and version");
209
+ }
210
+ return { id: String(id), version };
211
+ }
212
+
213
+ // The base as the tenant sees it: its own row (open draft included), else the served system default.
214
+ export async function baseVariableSchemaOf(
215
+ db: TenantWriteTarget["db"],
216
+ tenantId: string,
217
+ baseSlug: string,
218
+ locale: string,
219
+ ): Promise<unknown> {
220
+ const where = { slug: baseSlug, kind: VARIANT_KIND, locale };
221
+ const own = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
222
+ ...where,
223
+ tenantId,
224
+ });
225
+ if (own !== undefined) return parseStoredJson(toWorkingRow(own, tenantId).variableSchema);
226
+ const system = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
227
+ ...where,
228
+ tenantId: SYSTEM_TENANT_ID,
229
+ scope: "system",
230
+ status: "active",
231
+ });
232
+ return system === undefined ? undefined : parseStoredJson(system.variableSchema);
233
+ }
234
+
235
+ type VariantSchemaOutcome =
236
+ | { readonly refused: WriteFailure }
237
+ | { readonly payload: TemplateRowWrite["payload"]; readonly variables: TemplateVariables };
238
+
239
+ // A variant follows its base: a write that sends no schema of its own stores the base's current one,
240
+ // so a base that gains a variable does not lock its variants. A caller that sends a different
241
+ // schema explicitly is refused.
242
+ async function syncVariantSchema(
243
+ args: TemplateRowWrite,
244
+ db: TenantWriteTarget["db"],
245
+ ): Promise<VariantSchemaOutcome> {
246
+ const { payload } = args;
247
+ const baseSlug = readVariantOf(payload.meta);
248
+ const unchanged = { payload, variables: args.variables };
249
+ if (args.scope !== "tenant" || baseSlug === null) return unchanged;
250
+ const baseSchema = await baseVariableSchemaOf(db, args.tenantId, baseSlug, payload.locale);
251
+ if (!isPlainObject(baseSchema)) return unchanged;
252
+ if (args.explicitVariableSchema === true) {
253
+ if (isDeepStrictEqual(baseSchema, payload.variableSchema)) return unchanged;
254
+ return {
255
+ refused: writeFailure(
256
+ new ValidationError({
257
+ fields: [
258
+ patchIssue("variableSchema", "variables_inherited_from_base", { slug: baseSlug }),
259
+ ],
260
+ }),
261
+ ),
262
+ };
263
+ }
264
+ return {
265
+ payload: { ...payload, variableSchema: baseSchema },
266
+ variables: resolveTemplateVariables(args.ctx.registry, payload.slug, baseSchema),
267
+ };
268
+ }
269
+
173
270
  function refuseScopeViolation(
174
271
  registry: HandlerContext["registry"],
175
272
  scope: TemplateWriteScope,
@@ -177,6 +274,7 @@ function refuseScopeViolation(
177
274
  payload: TemplateRowWrite["payload"],
178
275
  ): WriteResult<never> | WriteFailure | null {
179
276
  return (
277
+ refuseVariantOfSlugMismatch(registry, scope, payload) ??
180
278
  refuseTenantScopeUnderSystemTenant(scope, tenantId) ??
181
279
  refuseReservedSystemLayoutSlug(scope, payload, "slug") ??
182
280
  refuseSystemOnlyTenantOverride(registry, scope, payload.slug, payload.kind)
@@ -190,10 +288,13 @@ function refuseScopeViolation(
190
288
  export async function writeTemplateRow(
191
289
  args: TemplateRowWrite,
192
290
  ): Promise<WriteResult<WrittenTemplateRow>> {
193
- const { ctx, user, tenantId, scope, status, payload } = args;
194
- const refused = refuseScopeViolation(ctx.registry, scope, tenantId, payload);
291
+ const { ctx, user, tenantId, scope, status } = args;
292
+ const refused = refuseScopeViolation(ctx.registry, scope, tenantId, args.payload);
195
293
  if (refused !== null) return refused;
196
294
  const { db, streamTenantId } = requireForTenant(ctx, tenantId);
295
+ const synced = await syncVariantSchema(args, db);
296
+ if ("refused" in synced) return synced.refused;
297
+ const { payload, variables } = synced;
197
298
 
198
299
  const gated = gateTemplateWrite(
199
300
  {
@@ -202,7 +303,7 @@ export async function writeTemplateRow(
202
303
  contentFormat: payload.contentFormat,
203
304
  content: payload.content,
204
305
  rawMeta: payload.meta,
205
- variables: args.variables,
306
+ variables,
206
307
  },
207
308
  status,
208
309
  );
@@ -250,6 +351,7 @@ export async function writeTemplateRow(
250
351
  isSuccess: true,
251
352
  data: {
252
353
  id: String(existing.id),
354
+ version: storedKeyOf(result.data).version,
253
355
  slug: payload.slug,
254
356
  isNew: false,
255
357
  validation: evaluated.validation,
@@ -260,7 +362,7 @@ export async function writeTemplateRow(
260
362
  const result = await executor.create(
261
363
  {
262
364
  ...fields,
263
- linkedResources: "{}",
365
+ linkedResources: args.linkedResources ?? "{}",
264
366
  tenantId,
265
367
  draft: null,
266
368
  ...(status === "active" ? activationChanges(null) : {}),
@@ -270,14 +372,12 @@ export async function writeTemplateRow(
270
372
  { streamTenantId },
271
373
  );
272
374
  if (!result.isSuccess) return result;
273
- // @cast-boundary db-row — executor.create returns a row from
274
- // INSERT RETURNING; the { id } shape is guaranteed because the primary key is in the
275
- // RETURNING clause.
276
- const createdRow = result.data as { id: string | number };
375
+ const created = storedKeyOf(result.data);
277
376
  return {
278
377
  isSuccess: true,
279
378
  data: {
280
- id: String(createdRow.id),
379
+ id: created.id,
380
+ version: created.version,
281
381
  slug: payload.slug,
282
382
  isNew: true,
283
383
  validation: evaluated.validation,
@@ -12,6 +12,7 @@ import {
12
12
  type WriteFailure,
13
13
  writeFailure,
14
14
  } from "@cosmicdrift/kumiko-framework/errors";
15
+ import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
15
16
  import * as z from "zod";
16
17
  import { requireForTenant } from "../../shared/index.ts";
17
18
  import type { TemplateResourceRow } from "../table.ts";
@@ -23,8 +24,10 @@ import {
23
24
  type TemplateEditPolicy,
24
25
  templateEditAccess,
25
26
  } from "../template-edit-policy.ts";
27
+ import { readVariantOf } from "../template-variants.ts";
26
28
  import { executor } from "./shared.ts";
27
- import { publishGateIssues } from "./template-gates.ts";
29
+ import { publishGateIssues, storedRecord } from "./template-gates.ts";
30
+ import { baseVariableSchemaOf } from "./template-write.ts";
28
31
 
29
32
  type TemplateStatus = "active" | "archived";
30
33
  export type StatusTarget = "own" | "system";
@@ -65,13 +68,34 @@ function planStatusChange(
65
68
  ctx: HandlerContext,
66
69
  row: TemplateResourceRow,
67
70
  status: TemplateStatus,
71
+ baseSchema: Record<string, unknown> | undefined,
68
72
  ): StatusPlan {
69
73
  if (status === "archived") return { ok: true, changes: { status } };
70
- const issues = publishGateIssues(ctx.registry, toWorkingRow(row, row.tenantId));
74
+ const syncedSchema =
75
+ baseSchema === undefined ? {} : { variableSchema: JSON.stringify(baseSchema) };
76
+ const issues = publishGateIssues(ctx.registry, {
77
+ ...toWorkingRow(row, row.tenantId),
78
+ ...syncedSchema,
79
+ });
71
80
  if (issues.length > 0) {
72
81
  return { ok: false, failure: writeFailure(new ValidationError({ fields: [...issues] })) };
73
82
  }
74
- return { ok: true, changes: { ...parseTemplateDraft(row.draft), ...activationChanges(row) } };
83
+ return {
84
+ ok: true,
85
+ changes: { ...parseTemplateDraft(row.draft), ...syncedSchema, ...activationChanges(row) },
86
+ };
87
+ }
88
+
89
+ // A variant goes live with the base's current variables, so a base that gained a variable is gated and served consistently.
90
+ async function baseSchemaForPublish(
91
+ db: LoadedTarget["db"],
92
+ row: TemplateResourceRow,
93
+ ): Promise<Record<string, unknown> | undefined> {
94
+ if (row.scope !== "tenant") return undefined;
95
+ const baseSlug = readVariantOf(storedRecord(toWorkingRow(row, row.tenantId).meta));
96
+ if (baseSlug === null) return undefined;
97
+ const schema = await baseVariableSchemaOf(db, row.tenantId, baseSlug, row.locale);
98
+ return isPlainObject(schema) ? schema : undefined;
75
99
  }
76
100
 
77
101
  type LoadedTarget = Pick<Awaited<ReturnType<typeof loadTargetRow>>, "db" | "scoped">;
@@ -84,7 +108,8 @@ export async function changeRowStatus(
84
108
  row: TemplateResourceRow,
85
109
  status: TemplateStatus,
86
110
  ): Promise<WriteResult<{ readonly id: string; readonly status: TemplateStatus }>> {
87
- const plan = planStatusChange(ctx, row, status);
111
+ const baseSchema = status === "active" ? await baseSchemaForPublish(target.db, row) : undefined;
112
+ const plan = planStatusChange(ctx, row, status, baseSchema);
88
113
  if (!plan.ok) return plan.failure;
89
114
  const result = await executor.update(
90
115
  { id: row.id, version: row.version, changes: plan.changes },
@@ -42,6 +42,7 @@ export function makeUpsertTenantWrite(policy: TemplateEditPolicy) {
42
42
  event.payload.variableSchema,
43
43
  ),
44
44
  payload: event.payload,
45
+ explicitVariableSchema: true,
45
46
  });
46
47
  },
47
48
  });
@@ -0,0 +1,89 @@
1
+ import { selectMany } from "@cosmicdrift/kumiko-framework/db";
2
+ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
3
+ import * as z from "zod";
4
+ import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
5
+ import { deliveryPolicyOf, isRowServed } from "../template-delivery-policy.ts";
6
+ import {
7
+ isVariantSlugOf,
8
+ readVariantOf,
9
+ VARIANT_KIND,
10
+ VARIANT_SEPARATOR,
11
+ } from "../template-variants.ts";
12
+ import { ACTIVE_TEMPLATE_STATUS, FALLBACK_LOCALE, SYSTEM_TENANT_ID } from "../web/constants.ts";
13
+ import { localeSchema, templateSlugSchema } from "./shared.ts";
14
+ import { parseStoredJson } from "./template-gates.ts";
15
+
16
+ const VARIANT_ROW_LIMIT = 500;
17
+
18
+ export type VariantSummary = {
19
+ readonly slug: string;
20
+ readonly title: string | null;
21
+ readonly scope: "system" | "tenant";
22
+ readonly locale: string;
23
+ };
24
+
25
+ // Tenant rows win over system rows of the same slug, the requested locale over the fallback locale.
26
+ function precedence(row: TemplateResourceRow, locale: string): number {
27
+ return (row.tenantId === SYSTEM_TENANT_ID ? 1 : 0) + (row.locale === locale ? 0 : 2);
28
+ }
29
+
30
+ export const variantsQuery = defineQueryHandler({
31
+ name: "variants",
32
+ schema: z.object({ baseSlug: templateSlugSchema, locale: localeSchema }),
33
+ access: {
34
+ openToAll: {
35
+ reason:
36
+ "lists only slug, title, scope and locale of the variants the caller's own tenant can print; " +
37
+ "whoever may create a document from the base template must be able to pick a variant, " +
38
+ "and the app's role names are unknown here",
39
+ },
40
+ },
41
+ description:
42
+ "Lists the active variants of a PDF document template (kind document-pdf, slug <baseSlug>:<name>) that the caller's tenant can use: the app's system variants and the tenant's own, each with slug, title (text or a translation key), scope (system or tenant) and locale. A tenant variant replaces a system variant of the same slug. Only published variants appear, and tenant variants only while the app still allows variants for the base template. Pass a returned slug as the variant when rendering the document.",
43
+ handler: async (query, ctx) => {
44
+ const { baseSlug, locale } = query.payload;
45
+ const locales = locale === FALLBACK_LOCALE ? [locale] : [locale, FALLBACK_LOCALE];
46
+ const rows: TemplateResourceRow[] = [];
47
+ for (const rowLocale of locales) {
48
+ const found = await selectMany<TemplateResourceRow>(
49
+ ctx.db,
50
+ templateResourcesTable,
51
+ {
52
+ kind: VARIANT_KIND,
53
+ status: ACTIVE_TEMPLATE_STATUS,
54
+ locale: rowLocale,
55
+ tenantId: { in: [query.user.tenantId, SYSTEM_TENANT_ID] },
56
+ // Slugs are kebab segments joined by ":", so the base slug holds no LIKE wildcard.
57
+ slug: { like: `${baseSlug}${VARIANT_SEPARATOR}%` },
58
+ },
59
+ { limit: VARIANT_ROW_LIMIT },
60
+ );
61
+ rows.push(...found);
62
+ }
63
+ // Delivery does not depend on the caller: a SystemAdmin sees the same list as the tenant's users.
64
+ const deliveryPolicy = deliveryPolicyOf(ctx.registry);
65
+ const delivered = rows.filter(
66
+ (row) =>
67
+ isVariantSlugOf(row.slug, baseSlug) &&
68
+ readVariantOf(parseStoredJson(row.meta)) === baseSlug &&
69
+ isRowServed(deliveryPolicy, row),
70
+ );
71
+ const best = new Map<string, TemplateResourceRow>();
72
+ for (const row of delivered) {
73
+ const current = best.get(row.slug);
74
+ if (current === undefined || precedence(row, locale) < precedence(current, locale)) {
75
+ best.set(row.slug, row);
76
+ }
77
+ }
78
+ return [...best.values()]
79
+ .map(
80
+ (row): VariantSummary => ({
81
+ slug: row.slug,
82
+ title: row.title,
83
+ scope: row.tenantId === SYSTEM_TENANT_ID ? "system" : "tenant",
84
+ locale: row.locale,
85
+ }),
86
+ )
87
+ .sort((a, b) => a.slug.localeCompare(b.slug));
88
+ },
89
+ });
@@ -25,4 +25,5 @@ export const TEMPLATE_RESOLVER_I18N: Readonly<Record<string, { readonly en: stri
25
25
  [handlerTitleKey(H.applyLayout)]: { en: "Apply PDF layout" },
26
26
  [handlerTitleKey(H.createLayout)]: { en: "Create PDF layout" },
27
27
  [handlerTitleKey(H.publishTemplates)]: { en: "Publish several templates" },
28
+ [handlerTitleKey(H.createVariant)]: { en: "Create PDF template variant" },
28
29
  };
@@ -12,6 +12,10 @@ export {
12
12
  collectDocumentImageVariables,
13
13
  collectDocumentResourceKeys,
14
14
  compileDocumentBodyToHandlebars,
15
+ type DocumentImageEntry,
16
+ type DocumentImageValue,
17
+ type DocumentRecordImage,
18
+ documentImageEntriesOf,
15
19
  toResourceDataUri,
16
20
  } from "./compile-document-body.ts";
17
21
  export {
@@ -19,15 +23,24 @@ export {
19
23
  flattenFramesForPreview,
20
24
  readTopLevelFrames,
21
25
  } from "./document-frames.ts";
26
+ export { allowedBlocksFor } from "./document-op-blocks.ts";
27
+ export {
28
+ applyDocumentOps,
29
+ type DocumentOp,
30
+ documentBlocksOf,
31
+ documentOpsSchema,
32
+ } from "./document-ops.ts";
22
33
  export {
23
34
  type DocumentViolation,
24
35
  type DocumentViolationCode,
25
36
  documentViolationsToFieldIssues,
26
37
  flattenParagraphsToLineBreaks,
38
+ parseDocumentJson,
27
39
  type SanitizeBodyResult,
28
40
  type SanitizeHtmlResult,
29
41
  sanitizeDocumentHtml,
30
42
  sanitizeTemplateBody,
43
+ serializeDocumentJson,
31
44
  } from "./document-sanitizer.ts";
32
45
  export { createTemplateResolverFeature, type TemplateResolverOptions } from "./feature.ts";
33
46
  export type { LayoutSourceResponse, LayoutSourceRow } from "./handlers/layout-source.query.ts";
@@ -82,6 +95,11 @@ export {
82
95
  } from "./table.ts";
83
96
  export { type TemplateBundle, templateBundleSchema } from "./template-bundle.ts";
84
97
  export type { TemplateDeliveryPolicy } from "./template-delivery-policy.ts";
98
+ export {
99
+ diffTemplateBlocks,
100
+ splitTemplateBlocks,
101
+ type TemplateDiffBlock,
102
+ } from "./template-diff.ts";
85
103
  export {
86
104
  type TemplateEditPolicy,
87
105
  type TenantEditableTemplate,
@@ -120,6 +138,14 @@ export {
120
138
  type TemplateValidation,
121
139
  validateTemplatePlaceholders,
122
140
  } from "./template-validation.ts";
141
+ export {
142
+ isVariantSlugOf,
143
+ readVariantOf,
144
+ VARIANT_NAME_MAX_LENGTH,
145
+ VARIANT_UNKNOWN_REASON,
146
+ variantNameSchema,
147
+ variantSlug,
148
+ } from "./template-variants.ts";
123
149
  export {
124
150
  type UserContentEntryRow,
125
151
  userContentEntriesTable,
@@ -42,6 +42,7 @@ import { activeStampChanges, servedStampChanges } from "./template-draft.ts";
42
42
  import { refuseReservedLayoutSlug } from "./template-edit-policy.ts";
43
43
  import { templateSlugSchema } from "./template-meta.ts";
44
44
  import { variablesFromSchema } from "./template-validation.ts";
45
+ import { variantOfMatchesSlug } from "./template-variants.ts";
45
46
  import { type ContentFormat, TEXT_BLOCK_KIND, type UpsertKind } from "./web/constants.ts";
46
47
  import { TEMPLATE_RESOLVER_FEATURE, TemplateResolverHandlers } from "./web/qualified-names.ts";
47
48
 
@@ -83,6 +84,8 @@ export type SeedSystemTemplateOptions = {
83
84
  * system admin uploaded through resource-upload. */
84
85
  readonly linkedResources?: Record<string, string>;
85
86
  readonly meta?: unknown;
87
+ /** Seeds the template as a variant of this base slug (kind `document-pdf`, slug `<variantOf>:<name>`); the app must also list the base with `variants: true` in tenantEditable for tenants to get their own. */
88
+ readonly variantOf?: string;
86
89
  readonly title?: string;
87
90
  /** Translatable title for the overview and designer, stored in the title column; the client
88
91
  * shows the translation and falls back to the key. Mutually exclusive with `title`. */
@@ -108,6 +111,17 @@ function seedTitleColumn(opts: SeedSystemTemplateOptions, label: string): string
108
111
  return opts.titleI18nKey ?? opts.title ?? null;
109
112
  }
110
113
 
114
+ function seedRawMeta(opts: SeedSystemTemplateOptions, label: string): unknown {
115
+ const rawMeta =
116
+ opts.variantOf === undefined
117
+ ? opts.meta
118
+ : { ...(isPlainObject(opts.meta) ? opts.meta : {}), variantOf: opts.variantOf };
119
+ if (!variantOfMatchesSlug(opts.slug, rawMeta)) {
120
+ throw new Error(`${label} rejected: invalid_variant_of (slug must be <variantOf>:<name>)`);
121
+ }
122
+ return rawMeta;
123
+ }
124
+
111
125
  export async function seedSystemTemplate(
112
126
  db: DbConnection,
113
127
  opts: SeedSystemTemplateOptions,
@@ -128,12 +142,13 @@ export async function seedSystemTemplate(
128
142
  throw new Error(`${label} rejected: reserved_layout_slug`);
129
143
  }
130
144
  const title = seedTitleColumn(opts, label);
145
+ const rawMeta = seedRawMeta(opts, label);
131
146
  const evaluated = evaluateTemplateWrite({
132
147
  kind: opts.kind,
133
148
  scope: "system",
134
149
  contentFormat: opts.contentFormat,
135
150
  content: opts.content,
136
- rawMeta: opts.meta,
151
+ rawMeta,
137
152
  variables: variablesFromSchema(opts.variableSchema ?? {}),
138
153
  resourceKeys: Object.keys(opts.linkedResources ?? {}),
139
154
  });
@@ -1,14 +1,64 @@
1
1
  import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
2
2
  import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
3
+ import { isVariantSlugOf, readVariantOf, VARIANT_KIND } from "./template-variants.ts";
3
4
  import { SYSTEM_TENANT_ID, TENANT_LAYOUT_SLUG_PREFIX } from "./web/constants.ts";
4
5
  import { TEMPLATE_RESOLVER_FEATURE } from "./web/qualified-names.ts";
5
6
 
6
7
  type DeliveryTarget = { readonly kind: string; readonly slug: string };
8
+ type PolicyEntry = DeliveryTarget & { readonly variants?: true };
9
+
10
+ type PolicyTarget = DeliveryTarget & {
11
+ /** Stored JSON text or a payload object; undefined when the caller has no row or payload yet. */
12
+ readonly meta?: unknown;
13
+ };
14
+
15
+ function variantOfOfMeta(meta: unknown): string | null {
16
+ if (typeof meta !== "string") return readVariantOf(meta);
17
+ try {
18
+ return readVariantOf(JSON.parse(meta));
19
+ } catch {
20
+ return null;
21
+ }
22
+ }
23
+
24
+ // An exact-slug entry always wins, so a separate template that merely has a ":" in its slug
25
+ // is never taken for a variant of another entry.
26
+ export function findVariantsEntry<Entry extends PolicyEntry>(
27
+ entries: readonly Entry[],
28
+ target: DeliveryTarget,
29
+ ): Entry | undefined {
30
+ if (entries.some((entry) => entry.kind === target.kind && entry.slug === target.slug)) {
31
+ return undefined;
32
+ }
33
+ return entries.find(
34
+ (entry) =>
35
+ entry.variants === true &&
36
+ entry.kind === VARIANT_KIND &&
37
+ entry.kind === target.kind &&
38
+ isVariantSlugOf(target.slug, entry.slug),
39
+ );
40
+ }
41
+
42
+ // An entry covers its own slug and, with `variants`, the variants of a PDF template: targets whose
43
+ // meta.variantOf is the entry's slug. A target without meta (slug-only pre-check) is judged by
44
+ // slug alone; writeTemplateRow then requires the variantOf.
45
+ export function findPolicyEntry<Entry extends PolicyEntry>(
46
+ entries: readonly Entry[],
47
+ target: PolicyTarget,
48
+ ): Entry | undefined {
49
+ const exact = entries.find((entry) => entry.kind === target.kind && entry.slug === target.slug);
50
+ if (exact !== undefined) return exact;
51
+ const variantsEntry = findVariantsEntry(entries, target);
52
+ if (variantsEntry === undefined) return undefined;
53
+ return target.meta === undefined || variantOfOfMeta(target.meta) === variantsEntry.slug
54
+ ? variantsEntry
55
+ : undefined;
56
+ }
7
57
 
8
58
  // What decides whether a tenant row may be served. Independent of who reads: delivery must not
9
59
  // change with the caller's roles, so this is not the edit policy.
10
60
  export type TemplateDeliveryPolicy = {
11
- readonly tenantEditable: readonly DeliveryTarget[];
61
+ readonly tenantEditable: readonly PolicyEntry[];
12
62
  /** Kinds of collections mounted with an explicit `access`; their tenant rows are edited by design. */
13
63
  readonly collectionKinds: readonly string[];
14
64
  };
@@ -26,12 +76,12 @@ function unlocksTenantLayouts(policy: TemplateDeliveryPolicy): boolean {
26
76
 
27
77
  export function isTenantOverrideServed(
28
78
  policy: TemplateDeliveryPolicy,
29
- target: DeliveryTarget,
79
+ target: PolicyTarget,
30
80
  ): boolean {
31
81
  return (
32
82
  policy.collectionKinds.includes(target.kind) ||
33
83
  (isTenantLayout(target) && unlocksTenantLayouts(policy)) ||
34
- policy.tenantEditable.some((entry) => entry.kind === target.kind && entry.slug === target.slug)
84
+ findPolicyEntry(policy.tenantEditable, target) !== undefined
35
85
  );
36
86
  }
37
87
 
@@ -39,17 +89,17 @@ export function isTenantOverrideServed(
39
89
  // is listed in tenantEditable. For these a system row of the same slug must win.
40
90
  export function isServedByCollectionOnly(
41
91
  policy: TemplateDeliveryPolicy,
42
- target: DeliveryTarget,
92
+ target: PolicyTarget,
43
93
  ): boolean {
44
94
  return (
45
95
  policy.collectionKinds.includes(target.kind) &&
46
- !policy.tenantEditable.some((entry) => entry.kind === target.kind && entry.slug === target.slug)
96
+ findPolicyEntry(policy.tenantEditable, target) === undefined
47
97
  );
48
98
  }
49
99
 
50
100
  export function isRowServed(
51
101
  policy: TemplateDeliveryPolicy,
52
- row: DeliveryTarget & { readonly tenantId: string },
102
+ row: PolicyTarget & { readonly tenantId: string },
53
103
  ): boolean {
54
104
  return row.tenantId === SYSTEM_TENANT_ID || isTenantOverrideServed(policy, row);
55
105
  }
@@ -13,7 +13,7 @@ import {
13
13
  } from "@cosmicdrift/kumiko-framework/errors";
14
14
  import type { TemplateWriteScope } from "./layout-regions.ts";
15
15
  import { type TemplateResourceRow, templateResourcesTable } from "./table.ts";
16
- import { isTenantLayout } from "./template-delivery-policy.ts";
16
+ import { findPolicyEntry, isTenantLayout } from "./template-delivery-policy.ts";
17
17
  import { isSystemAdmin } from "./template-draft.ts";
18
18
  import { TENANT_LAYOUT_SLUG_PREFIX, type TemplateKind } from "./web/constants.ts";
19
19
  import { TemplateResolverErrors } from "./web/qualified-names.ts";
@@ -22,13 +22,15 @@ export type TenantEditableTemplate = {
22
22
  readonly kind: TemplateKind;
23
23
  readonly slug: string;
24
24
  readonly access: RoleAccessRule;
25
+ /** Lets a tenant create variants (`<slug>:<name>`) of this PDF template; they follow this entry's access and delivery. Only for kind `document-pdf`. */
26
+ readonly variants?: true;
25
27
  };
26
28
 
27
29
  export type TemplateEditPolicy = {
28
30
  readonly tenantEditable: readonly TenantEditableTemplate[];
29
31
  };
30
32
 
31
- type EditTarget = { readonly slug: string; readonly kind: string };
33
+ type EditTarget = { readonly slug: string; readonly kind: string; readonly meta?: unknown };
32
34
  type EditUser = Pick<SessionUser, "roles">;
33
35
 
34
36
  const SYSTEM_ADMIN_ROLE = "SystemAdmin";
@@ -48,9 +50,7 @@ export function mayEditTemplate(
48
50
  ): boolean {
49
51
  if (isSystemAdmin(user)) return true;
50
52
  if (isTenantLayout(target)) return mayEditTenantLayouts(policy, user);
51
- const entry = policy.tenantEditable.find(
52
- (candidate) => candidate.slug === target.slug && candidate.kind === target.kind,
53
- );
53
+ const entry = findPolicyEntry(policy.tenantEditable, target);
54
54
  return entry !== undefined && hasAccess(user, entry.access);
55
55
  }
56
56
 
@@ -81,6 +81,7 @@ export const pdfAttachmentFileNamePatternSchema = singleLine(200)
81
81
  const pdfMetaSchema = z
82
82
  .object({
83
83
  layoutSlug: templateSlugSchema.optional(),
84
+ variantOf: templateSlugSchema.optional(),
84
85
  pageFormat: z.enum(PDF_PAGE_FORMATS).optional(),
85
86
  orientation: z.enum(PDF_ORIENTATIONS).optional(),
86
87
  printBackground: z.boolean().optional(),