@cosmicdrift/kumiko-samples 0.398.0 → 0.400.0

package/samples/apps/styleguide/src/app/seed.ts

@@ -1,9 +1,14 @@
 import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
 import { buildEntityTable, createTenantDb, fetchOne } from "@cosmicdrift/kumiko-framework/db";
-import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { createEntityExecutor, createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createFileRefFromBytes,
+  createTenantFileContext,
+} from "@cosmicdrift/kumiko-framework/files";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 
 import { demoEntity } from "../features/demo/feature";
+import { inspectionEntity } from "../features/examples/feature";
 
 // Gives the list view real rows with status/flag variety. price (money)
 // stays empty — the money input shows in the edit screen, in the seed we leave
@@ -16,6 +21,8 @@ const STATUSES = ["draft", "review", "published", "archived"] as const;
 // otherwise change every run.
 export const FIRST_STYLEGUIDE_ITEM_ID = "00000000-0000-4000-8000-0000000000f1";
 
+export const FIRST_STYLEGUIDE_INSPECTION_ID = "00000000-0000-4000-8000-0000000000f2";
+
 const demoItemTable = buildEntityTable("item", demoEntity);
 
 export const seedStyleguideItems: SeedFn = async (stack) => {
@@ -58,3 +65,97 @@ export const seedStyleguideItems: SeedFn = async (stack) => {
     }
   }
 };
+
+const inspectionTable = buildEntityTable("inspection", inspectionEntity);
+
+// 1x1 PNG, enough for the thumbnail chain; the bytes only need to be a valid image.
+const SEED_PHOTO_PNG = Uint8Array.from(
+  Buffer.from(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+    "base64",
+  ),
+);
+
+// Fixed id for the inspection-checklist screenshot scenarios. Created through the executor like
+// the first demo item. Photos are real file refs attached to checkpoints.photos, created
+// server-side the way POST /files would (a not_ok checkpoint requires a photo).
+export const seedStyleguideInspection: SeedFn = async (stack) => {
+  if (await fetchOne(stack.db, inspectionTable, { id: FIRST_STYLEGUIDE_INSPECTION_ID })) return;
+  const tenantId = TestUsers.admin.tenantId;
+  const tenantDb = createTenantDb({ db: stack.db, tenantId });
+  const resolver = stack.context._fileProviderResolver;
+  const files = resolver ? createTenantFileContext(resolver, tenantId) : stack.context.files;
+
+  const photoIds: string[] = [];
+  for (const fileName of ["hose.png", "bearing.png"]) {
+    const photo = await createFileRefFromBytes(
+      {
+        db: tenantDb,
+        services: { files },
+        registry: stack.registry,
+        user: createSystemUser(tenantId),
+      },
+      {
+        fileName,
+        mimeType: "image/png",
+        data: SEED_PHOTO_PNG,
+        attachTo: {
+          entityType: "inspection",
+          fieldName: "checkpoints",
+          subField: "photos",
+          entityId: FIRST_STYLEGUIDE_INSPECTION_ID,
+        },
+      },
+    );
+    if (!photo.isSuccess) {
+      // biome-ignore lint/suspicious/noConsole: dev-seed surfaces failures in the runner log
+      console.error("[seed] styleguide inspection photo failed:", photo.error);
+      return;
+    }
+    photoIds.push(photo.data.id);
+  }
+
+  const { executor } = createEntityExecutor("inspection", inspectionEntity);
+  const res = await executor.create(
+    {
+      id: FIRST_STYLEGUIDE_INSPECTION_ID,
+      measuringDevice: "Torque wrench TW-200",
+      checkpoints: [
+        { label: "Guard fitted", kind: "check", result: "ok" },
+        {
+          label: "Hydraulic hose intact",
+          kind: "check",
+          result: "not_ok",
+          finding: "Hose chafed at the clamp, replace before next shift.",
+          photos: [photoIds[0]],
+        },
+        {
+          label: "Bolt torque (Nm)",
+          kind: "measurement",
+          min: 180,
+          max: 200,
+          measured: 190,
+          result: "ok",
+        },
+        {
+          label: "Bearing play (mm)",
+          kind: "measurement",
+          min: 0.05,
+          max: 0.2,
+          measured: 0.31,
+          result: "not_ok",
+          finding: "Play above tolerance, re-measure after re-seating.",
+          photos: [photoIds[1]],
+        },
+      ],
+      continuedOperation: "with_condition",
+      condition: "Operate at reduced load until the hose is replaced.",
+    },
+    TestUsers.admin,
+    tenantDb,
+  );
+  if (!res.isSuccess) {
+    // biome-ignore lint/suspicious/noConsole: dev-seed surfaces failures in the runner log
+    console.error("[seed] styleguide inspection failed:", res.error);
+  }
+};

package/samples/apps/styleguide/src/app/server.ts

@@ -22,7 +22,7 @@ import { aiTextDemoFeature } from "../features/widgets/ai-text-demo";
 import { widgetsFeature } from "../features/widgets/feature";
 import { workboardFeature } from "../features/workboard/feature";
 import { seedWorkboardTasks } from "../features/workboard/seed";
-import { seedStyleguideItems } from "./seed";
+import { seedStyleguideInspection, seedStyleguideItems } from "./seed";
 
 const configResolver = createConfigResolver();
 
@@ -46,7 +46,7 @@ await runDevApp({
   clientEntry: "./src/app/client.tsx",
   htmlPath: "./public/index.html",
   watchDirs: ["./src", "../../../packages/*/src"],
-  seeds: [seedStyleguideItems, seedAiConnections, seedWorkboardTasks],
+  seeds: [seedStyleguideItems, seedStyleguideInspection, seedAiConnections, seedWorkboardTasks],
   extraContext: ({ registry }) => ({
     configResolver,
     configAccessorFactory: createConfigAccessorFactory(registry, configResolver),

package/samples/apps/styleguide/src/features/examples/feature.ts

@@ -6,6 +6,7 @@
 import {
   createBooleanField,
   createDateField,
+  createEmbeddedListField,
   createEntity,
   createImageField,
   createLocatedTimestampField,
@@ -70,6 +71,65 @@ export const deliveryEntity = createEntity({
   },
 });
 
+// Inspection — the inspection-checklist recipe's protocol (sub-fields, derived result,
+// conditions), rendered as the phone checklist in the auto-form.
+const isMeasurement = { field: "kind", eq: "measurement" } as const;
+const isNotOk = { field: "result", eq: "not_ok" } as const;
+
+export const inspectionEntity = createEntity({
+  table: "read_examples_inspection",
+  fields: {
+    measuringDevice: createTextField({ personal: false, reason: "is_business_data" }),
+    checkpoints: createEmbeddedListField(
+      {
+        label: { type: "text", required: true },
+        kind: { type: "select", options: ["check", "measurement"], required: true },
+        min: { type: "number", visibleWhen: isMeasurement },
+        max: { type: "number", visibleWhen: isMeasurement },
+        measured: { type: "number", visibleWhen: isMeasurement },
+        result: {
+          type: "select",
+          options: ["ok", "not_ok"],
+          display: "radio",
+          optionTones: { ok: "ok", not_ok: "bad" },
+        },
+        finding: { type: "text", visibleWhen: isNotOk, requiredWhen: isNotOk },
+        photos: {
+          type: "images",
+          capture: "environment",
+          maxCount: 5,
+          visibleWhen: isNotOk,
+          requiredWhen: isNotOk,
+        },
+      },
+      {
+        personal: false,
+        reason: "is_business_data",
+        derived: {
+          result: {
+            op: "inRange",
+            from: ["measured", "min", "max"],
+            inside: "ok",
+            outside: "not_ok",
+            when: isMeasurement,
+          },
+        },
+      },
+    ),
+    continuedOperation: createSelectField({
+      options: ["yes", "with_condition", "no"],
+      display: "radio",
+      optionTones: { yes: "ok", with_condition: "warn", no: "bad" },
+    }),
+    condition: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      visibleWhen: { field: "continuedOperation", eq: "with_condition" },
+      requiredWhen: { field: "continuedOperation", eq: "with_condition" },
+    }),
+  },
+});
+
 const openReason =
   "demo app: any signed-in user edits the shipping, profile and delivery example " +
   "forms; there is no per-user ownership in this sample";
@@ -194,6 +254,35 @@ export const examplesFeature = defineFeature("examples", (r) => {
     },
   });
 
+  r.crud("inspection", inspectionEntity, editFormOnly);
+
+  r.screen({
+    id: "inspection-edit",
+    type: "entityEdit",
+    entity: "inspection",
+    submitLabel: "examples:inspection:submit",
+    layout: {
+      width: "full",
+      sections: [
+        {
+          columns: 1,
+          fields: [
+            "measuringDevice",
+            {
+              field: "checkpoints",
+              embeddedList: {
+                readOnlyCells: ["label", "kind", "min", "max"],
+                cardHiddenCells: ["kind"],
+                fixedRows: true,
+              },
+            },
+          ],
+        },
+        { columns: 1, fields: ["continuedOperation", "condition"] },
+      ],
+    },
+  });
+
   r.nav({ id: "examples", label: "examples:nav.examples", icon: "folder", order: 30 });
   r.nav({
     id: "shipping",
@@ -219,4 +308,12 @@ export const examplesFeature = defineFeature("examples", (r) => {
     icon: "calendar",
     order: 30,
   });
+  r.nav({
+    id: "inspection",
+    label: "examples:nav.inspection",
+    parent: "examples:nav:examples",
+    screen: "examples:screen:inspection-edit",
+    icon: "file",
+    order: 40,
+  });
 });

package/samples/apps/styleguide/src/features/examples/i18n.ts

@@ -69,4 +69,51 @@ export const EXAMPLES_I18N: Readonly<Record<string, LocalizedString>> = {
     en: "Booked at (UTC instant)",
   },
   "examples:entity:delivery:field:homeZone": { de: "Heimatzone Kurier", en: "Courier home zone" },
+  "examples:nav.inspection": { de: "Prüfprotokoll", en: "Inspection checklist" },
+  "screen:inspection-edit.title": { de: "Prüfprotokoll", en: "Inspection checklist" },
+  "screen:inspection-edit.create.title": { de: "Prüfprotokoll", en: "Inspection checklist" },
+  "screen:inspection-edit.create.subtitle": {
+    de: "Prüfpunkte abhaken oder messen, bei Abweichung Befund und Fotos erfassen.",
+    en: "Check or measure each point, record a finding and photos on deviation.",
+  },
+  "screen:inspection-edit.edit.title": { de: "Prüfprotokoll", en: "Inspection checklist" },
+  "screen:inspection-edit.edit.subtitle": {
+    de: "Prüfpunkte abhaken oder messen, bei Abweichung Befund und Fotos erfassen.",
+    en: "Check or measure each point, record a finding and photos on deviation.",
+  },
+  "examples:inspection:submit": { de: "Protokoll speichern", en: "Save protocol" },
+  "examples:entity:inspection:field:measuringDevice": { de: "Messgerät", en: "Measuring device" },
+  "examples:entity:inspection:field:checkpoints": { de: "Prüfpunkte", en: "Checkpoints" },
+  "examples:entity:inspection:field:checkpoints:cell:label": { de: "Prüfpunkt", en: "Checkpoint" },
+  "examples:entity:inspection:field:checkpoints:cell:kind": { de: "Art", en: "Kind" },
+  "examples:entity:inspection:field:checkpoints:cell:min": { de: "Min", en: "Min" },
+  "examples:entity:inspection:field:checkpoints:cell:max": { de: "Max", en: "Max" },
+  "examples:entity:inspection:field:checkpoints:cell:measured": { de: "Messwert", en: "Measured" },
+  "examples:entity:inspection:field:checkpoints:cell:result": { de: "Ergebnis", en: "Result" },
+  "examples:entity:inspection:field:checkpoints:cell:finding": { de: "Befund", en: "Finding" },
+  "examples:entity:inspection:field:checkpoints:cell:photos": { de: "Fotos", en: "Photos" },
+  "examples:entity:inspection:field:continuedOperation": {
+    de: "Weiterbetrieb",
+    en: "Continued operation",
+  },
+  "examples:entity:inspection:field:condition": { de: "Auflage", en: "Condition" },
+  "examples:entity:inspection:field:checkpoints:cell:kind:option:check": {
+    de: "Sichtprüfung",
+    en: "Check",
+  },
+  "examples:entity:inspection:field:checkpoints:cell:kind:option:measurement": {
+    de: "Messung",
+    en: "Measurement",
+  },
+  "examples:entity:inspection:field:checkpoints:cell:result:option:ok": { de: "i.O.", en: "OK" },
+  "examples:entity:inspection:field:checkpoints:cell:result:option:not_ok": {
+    de: "n.i.O.",
+    en: "Not OK",
+  },
+  "examples:entity:inspection:field:continuedOperation:option:yes": { de: "Ja", en: "Yes" },
+  "examples:entity:inspection:field:continuedOperation:option:with_condition": {
+    de: "Mit Auflage",
+    en: "With condition",
+  },
+  "examples:entity:inspection:field:continuedOperation:option:no": { de: "Nein", en: "No" },
 };

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1,6 +1,6 @@
 {
   "source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
-  "featureCount": 89,
+  "featureCount": 90,
   "features": [
     {
       "name": "account-security",
@@ -472,7 +472,7 @@
     },
     {
       "name": "channel-in-app",
-      "description": "Persists notifications to an in-app inbox table so users can retrieve them via `handlers.inbox` and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. Requires `delivery`; no external service needed — messages are stored in the app's own database.",
+      "description": "Persists notifications to an in-app inbox table so users can page through them via `queries.inbox` (cursor, total, parsed `target`) and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. A notification links to a screen when `data.target` is set with `inAppTarget(screenId, entityId?)`. The renderer shell shows a bell with a live unread badge whenever this feature is mounted. Requires `delivery`; no external service needed — messages are stored in the app's own database.",
       "toggleableDefault": null,
       "requires": [
         "delivery"
@@ -914,6 +914,35 @@
         "recommended": false
       }
     },
+    {
+      "name": "documents",
+      "description": "Filed documents with title, category, issue and expiry date and one file, shown on the records they are linked to. A document is visible only through a linked record the viewer can read, and only while the record that owns its file is readable too, so linking never widens access to the file. Documents arrive through capture rules (a file saved into a configured field) or through the system-only import for migrations, which keeps the caller's id, refuses an id another record already uses, and stamps createdAt with the import time (issuedAt carries the business date; the event store does not backdate); users link, unlink, edit and delete them. Read a record's documents with for-record, count expired and expiring ones with expiry-overview, list them with an expiry state and an expiring filter with overview (the documents list screen), and add the documents tab to a record screen with documentsTab().",
+      "toggleableDefault": null,
+      "adoptsBundledLists": true,
+      "requires": [
+        "files"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": [
+        "documents:write:filed-document:create",
+        "documents:write:filed-document:delete",
+        "documents:write:filed-document:update",
+        "documents:write:import",
+        "documents:write:link",
+        "documents:write:unlink"
+      ],
+      "uiHints": {
+        "displayLabel": "Documents",
+        "category": "data",
+        "recommended": false
+      }
+    },
     {
       "name": "feature-toggles",
       "description": "Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: \"shared\"` syncs the snapshot across instances whenever a `toggle-set` event is appended.",

package/samples/apps/use-all-bundled/kumiko/migrations/0058_documents.rebuild.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tables": ["read_filed_document_links", "read_filed_documents"]
+}

package/samples/apps/use-all-bundled/src/app/dev-app-options.ts

@@ -12,7 +12,11 @@
 
 import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import type { RunDevAppOptions } from "@cosmicdrift/kumiko-dev-server";
-import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  FILE_STORAGE_PROVIDER_ENV,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { BUNDLED_LISTS } from "../bundled-lists";
 import { AUTH_COMPOSE_OPTIONS, BOOT_FEATURES, VALIDATE_BOOT_OPTIONS } from "../run-config";
 import { ADMIN_EMAIL, ADMIN_PASSWORD, BETA_TENANT_ID, DEV_TENANT_ID } from "./auth-constants";
@@ -31,7 +35,12 @@ export const devAppOptions = {
   // it stays out of APP_FEATURES. appScreensFeature places the user-profile screen.
   features: [...BOOT_FEATURES, appScreensFeature, notesFeature, invoiceReportsFeature],
   featureToggles: true,
-  validateBootOptions: VALIDATE_BOOT_OPTIONS,
+  // documents has a file field, so the boot gate wants a storage provider; the seeded
+  // file-foundation config selects the real one, so only the validation env names it.
+  validateBootOptions: {
+    ...VALIDATE_BOOT_OPTIONS,
+    env: { [FILE_STORAGE_PROVIDER_ENV]: "inmemory", ...process.env },
+  },
   bundledLists: BUNDLED_LISTS,
   port: Number.parseInt(process.env["PORT"] ?? "4186", 10),
   clientEntry: "./src/app/client.tsx",

package/samples/apps/use-all-bundled/src/run-config.ts

@@ -43,6 +43,7 @@ import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features
 import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { createDerivativesSharpFeature } from "@cosmicdrift/kumiko-bundled-features/derivatives-sharp";
 import { createDocumentIngestFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/document-ingest-foundation";
+import { createDocumentsFeature } from "@cosmicdrift/kumiko-bundled-features/documents";
 import {
   createFeatureTogglesFeature,
   FEATURE_TOGGLES_FEATURE,
@@ -406,6 +407,12 @@ export const APP_FEATURES = [
   // user-data-rights — both mounted here.
   createFormDraftUserDataFeature(),
   createFoldersFeature(),
+  // documents: filed files visible through the records they link to; folder stands in for a host.
+  createDocumentsFeature({
+    categories: ["contract", "other"],
+    linkTargets: ["folder"],
+    adminRoles: ["TenantAdmin", "SystemAdmin"],
+  }),
   // folders-user-data: GDPR hooks for folder entities. Depends (optionally)
   // on folders + (hard) on user-data-rights — both mounted above.
   createFoldersUserDataFeature(),

package/samples/recipes/derived-fields-sql/README.md

@@ -0,0 +1,27 @@
+# Derived fields (SQL)
+
+A derived field is read-time only: no column, never in a write schema. A `sql` derived field is
+computed inside the list SELECT as the viewer, so it can be sorted on the server and never
+enters the entity cache. A viewer who cannot read a field the value depends on gets NULL.
+
+## What it shows
+
+- `coalesce`: the nickname when set, else the name.
+- `related` + `count` with a `where`: open tickets per building.
+- `related` + `first`: the title of the newest ticket.
+- `related` + `first` on a money field with `valueType: "money"`: amount and currency come
+  back in the shape of a stored money field (no key when the value is unset).
+- `sortable: true` on a derived field and an `entityList` `defaultSort` on it.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/derived-fields-sql
+bun test
+```
+
+`src/__tests__/feature.integration.test.ts` runs the list query over HTTP.

package/samples/recipes/derived-fields-sql/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-derived-fields-sql",
+  "description": "SQL derived fields on a list: coalesce, related count with a where, related first (text and money), sortable columns and a defaultSort on a derived value.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
+  }
+}

package/samples/recipes/derived-fields-sql/src/feature.ts

@@ -0,0 +1,98 @@
+import {
+  createDateField,
+  createDerivedField,
+  createEntity,
+  createMoneyField,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const openAccess = {
+  access: {
+    openToAll: { reason: "recipe: any signed-in user reads and edits; no per-user ownership" },
+  },
+} as const;
+
+export const ticketEntity = createEntity({
+  table: "read_derived_sql_tickets",
+  fields: {
+    buildingId: { type: "reference", entity: "building" },
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    status: createSelectField({ options: ["open", "inProgress", "done"] as const }),
+    openedOn: createDateField({ required: true }),
+    cost: createMoneyField(),
+  },
+  // The sortable derived columns of the building run a subquery per row over this column.
+  indexes: [{ columns: ["buildingId"] }],
+});
+
+export const buildingEntity = createEntity({
+  table: "read_derived_sql_buildings",
+  fields: {
+    name: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      searchable: true,
+    }),
+    nickname: createTextField({ personal: false, reason: "is_business_data" }),
+  },
+  // Computed inside the list SELECT as the viewer; never stored, never cached.
+  derivedFields: {
+    // First non-null of the columns, so the list shows the nickname when there is one.
+    shownName: createDerivedField({
+      valueType: "text",
+      sortable: true,
+      sql: { kind: "coalesce", fields: ["nickname", "name"] },
+    }),
+    openTickets: createDerivedField({
+      valueType: "number",
+      sortable: true,
+      sql: {
+        kind: "related",
+        entity: "ticket",
+        on: { field: "buildingId" },
+        measure: { kind: "count" },
+        where: [{ field: "status", op: "in", value: ["open", "inProgress"] }],
+      },
+    }),
+    latestTicket: createDerivedField({
+      valueType: "text",
+      sql: {
+        kind: "related",
+        entity: "ticket",
+        on: { field: "buildingId" },
+        measure: { kind: "first", field: "title", orderBy: "openedOn", direction: "desc" },
+      },
+    }),
+    // Money reads amount and currency together and has the shape of a stored money field.
+    latestCost: createDerivedField({
+      valueType: "money",
+      sortable: true,
+      sql: {
+        kind: "related",
+        entity: "ticket",
+        on: { field: "buildingId" },
+        measure: { kind: "first", field: "cost", orderBy: "openedOn", direction: "desc" },
+      },
+    }),
+  },
+});
+
+export const buildingListSort = { field: "openTickets", dir: "desc" } as const;
+
+export const derivedFieldsSqlFeature = defineFeature("derived-fields-sql", (r) => {
+  r.crud("ticket", ticketEntity, { write: openAccess, read: openAccess });
+  r.crud("building", buildingEntity, { write: openAccess, read: openAccess });
+
+  r.screen({
+    id: "building-list",
+    type: "entityList",
+    entity: "building",
+    columns: ["shownName", "openTickets", "latestTicket", "latestCost"],
+    // A derived column sorts on the server only when it is `sortable: true`.
+    defaultSort: buildingListSort,
+    access: openAccess.access,
+  });
+});

package/samples/recipes/documents/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-documents",
+  "description": "A document register on top of existing records: captured files, expiry dates and per-record visibility.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
+  }
+}

package/samples/recipes/documents/src/feature.ts

@@ -0,0 +1,66 @@
+// kumiko-feature-version: 1
+// Documents Sample
+//
+// A `contract` entity with a file field becomes a document source without knowing about the
+// documents feature: the capture rule below files every saved contract file as a document of
+// category "contract" and links it to the contract and to its property. Who sees the document
+// follows from who may read the linked records and the contract that owns the file.
+
+import { createDocumentsFeature } from "@cosmicdrift/kumiko-bundled-features/documents";
+import {
+  createEntity,
+  createFileField,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const text = () =>
+  createTextField({ personal: false, reason: "is_business_data", required: true, maxLength: 120 });
+
+export const propertyEntity = createEntity({
+  table: "read_sample_documents_properties",
+  fields: { name: text() },
+  access: { read: { PropertyReader: "all", TenantAdmin: "all" } },
+});
+
+export const contractEntity = createEntity({
+  table: "read_sample_documents_contracts",
+  fields: { name: text(), propertyId: text(), file: createFileField() },
+  access: { read: { ContractReader: "all", TenantAdmin: "all" } },
+});
+
+const access = { roles: ["PropertyReader", "ContractReader", "TenantAdmin"] };
+
+export const propertyManagement = defineFeature("property-management", (r) => {
+  r.requires({ features: ["files", "documents"] });
+  r.entity({ name: "property", ...propertyEntity });
+  r.entity({ name: "contract", ...contractEntity });
+  for (const [name, entity] of [
+    ["property", propertyEntity],
+    ["contract", contractEntity],
+  ] as const) {
+    r.writeHandler(defineEntityCreateHandler(name, entity, { access }));
+    r.writeHandler(defineEntityUpdateHandler(name, entity, { access: { roles: ["TenantAdmin"] } }));
+    r.queryHandler(defineEntityListHandler(name, entity, { access }));
+    r.queryHandler(defineEntityDetailHandler(name, entity, { access }));
+  }
+});
+
+export const documents = createDocumentsFeature({
+  categories: ["contract", "insurance"],
+  linkTargets: ["property", "contract"],
+  access,
+  capture: [
+    {
+      entity: "contract",
+      field: "file",
+      category: "contract",
+      title: (row) => `Contract ${String(row["name"])}`,
+      links: (row) => [{ entityType: "property", entityId: String(row["propertyId"]) }],
+    },
+  ],
+});

package/samples/recipes/inspection-checklist/README.md

@@ -0,0 +1,27 @@
+# Inspection checklist
+
+An embedded list as a phone inspection checklist: the inspector walks fixed rows,
+enters a measurement or a result, and documents deviations with a finding and photos.
+
+## What it shows
+
+- **Conditional cells** (`src/entities/inspection-protocol.ts`): `visibleWhen` and
+  `requiredWhen` on sub-fields and on top-level fields. The server enforces
+  `requiredWhen` on create and update and answers with one `required` path per
+  missing cell (`checkpoints.0.finding`, `condition`).
+- **Pass/fail by range**: the derived `inRange` cell turns `measured`, `min` and `max`
+  into `ok` or `not_ok` (bounds included). The server recomputes it, so a client-sent
+  result never survives a value outside the range. `when` limits it to measurement rows;
+  a check row keeps the result the inspector picked.
+- **Photos per row**: an `images` sub-field. Upload with `entityType`, `fieldName` of the
+  embedded list and `subField` of the photo cell; files are bound, tenant-checked and
+  disposed like a top-level images field, always under the embedded list's field name.
+- **Fixed rows**: `inspection-protocol:create-from-plan` copies label, kind and limits from
+  a plan; the edit screen keeps those cells read-only and the row count fixed. It sets
+  `layout.width: "full"` because the default form width pushes result, finding and photos
+  behind horizontal scroll.
+
+## Source
+
+`src/feature.ts` wires the two entities, the handler and the screen. The integration test
+covers every behavior above over real HTTP.