@cosmicdrift/kumiko-samples 0.399.0 → 0.400.0

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.

package/samples/recipes/inspection-checklist/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-inspection-checklist",
+  "description": "Embedded list as a phone inspection checklist: conditional fields, derived pass/fail, photos per row.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
+  }
+}

package/samples/recipes/inspection-checklist/src/entities/inspection-plan.ts

@@ -0,0 +1,24 @@
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEmbeddedListField,
+  createEntity,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const inspectionPlanEntity = createEntity({
+  table: "read_sample_inspection_plans",
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    checkpoints: createEmbeddedListField(
+      {
+        label: { type: "text", required: true },
+        kind: { type: "select", options: ["check", "measurement"], required: true },
+        min: { type: "number" },
+        max: { type: "number" },
+      },
+      { personal: false, reason: "is_business_data" },
+    ),
+  },
+});
+
+export const inspectionPlanTable = buildEntityTable("inspection-plan", inspectionPlanEntity);

package/samples/recipes/inspection-checklist/src/entities/inspection-protocol.ts

@@ -0,0 +1,72 @@
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEmbeddedListField,
+  createEntity,
+  createSelectField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const isMeasurement = { field: "kind", eq: "measurement" } as const;
+const isNotOk = { field: "result", eq: "not_ok" } as const;
+
+export const inspectionProtocolEntity = createEntity({
+  table: "read_sample_inspection_protocols",
+  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,
+          accept: ["jpg", "jpeg", "png"],
+          visibleWhen: isNotOk,
+          requiredWhen: isNotOk,
+        },
+        documents: { type: "files", maxCount: 3 },
+        approvedBy: { type: "text", access: { write: ["Admin"] } },
+      },
+      {
+        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" },
+    }),
+  },
+});
+
+export const inspectionProtocolTable = buildEntityTable(
+  "inspection-protocol",
+  inspectionProtocolEntity,
+);

package/samples/recipes/inspection-checklist/src/feature.ts

@@ -0,0 +1,33 @@
+// Inspection Checklist Sample
+// Shows: an embedded list as a phone inspection checklist.
+//   - visibleWhen / requiredWhen on cells and top-level fields (server-enforced)
+//   - a derived pass/fail cell (inRange) that the server recomputes
+//   - an images cell per row, uploaded with the `subField` multipart part
+//   - fixed rows copied from a plan, only the result cells stay editable
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { inspectionPlanEntity } from "./entities/inspection-plan";
+import { inspectionProtocolEntity } from "./entities/inspection-protocol";
+import { createFromPlan } from "./handlers/create-from-plan.write";
+import { inspectionProtocolEditScreen } from "./screens/inspection-protocol-edit.screen";
+
+export { inspectionPlanEntity } from "./entities/inspection-plan";
+export { inspectionProtocolEntity } from "./entities/inspection-protocol";
+
+const inspectorAccess = { access: { roles: ["Admin", "Inspector"] } } as const;
+
+export const inspectionChecklistFeature = defineFeature("inspection-checklist", (r) => {
+  r.requires({ features: ["files"] });
+
+  r.crud("inspection-plan", inspectionPlanEntity, {
+    write: inspectorAccess,
+    read: inspectorAccess,
+  });
+  r.crud("inspection-protocol", inspectionProtocolEntity, {
+    write: inspectorAccess,
+    read: inspectorAccess,
+  });
+  r.writeHandler(createFromPlan);
+
+  r.screen(inspectionProtocolEditScreen);
+});

package/samples/recipes/inspection-checklist/src/handlers/create-from-plan.write.ts

@@ -0,0 +1,38 @@
+import { createEntityExecutor, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { inspectionPlanEntity } from "../entities/inspection-plan";
+import { inspectionProtocolEntity } from "../entities/inspection-protocol";
+
+const { executor: planExecutor } = createEntityExecutor("inspection-plan", inspectionPlanEntity);
+const { executor: protocolExecutor } = createEntityExecutor(
+  "inspection-protocol",
+  inspectionProtocolEntity,
+);
+
+const planRows = z.array(
+  z.object({
+    label: z.string(),
+    kind: z.enum(["check", "measurement"]),
+    min: z.number().optional(),
+    max: z.number().optional(),
+  }),
+);
+
+// Copies only the plan's fixed columns; result, finding and photos stay empty for the inspector.
+export const createFromPlan = defineWriteHandler({
+  name: "inspection-protocol:create-from-plan",
+  schema: z.object({ planId: z.uuid() }),
+  access: { roles: ["Admin", "Inspector"] },
+  handler: async (event, ctx) => {
+    const plan = await planExecutor.detail({ id: event.payload.planId }, event.user, ctx.db);
+    if (!plan) return failNotFound("inspection-plan", event.payload.planId);
+    const checkpoints = planRows.parse(plan["checkpoints"]).map(({ label, kind, min, max }) => ({
+      label,
+      kind,
+      ...(min !== undefined ? { min } : {}),
+      ...(max !== undefined ? { max } : {}),
+    }));
+    return protocolExecutor.create({ checkpoints }, event.user, ctx.db);
+  },
+});

package/samples/recipes/inspection-checklist/src/screens/inspection-protocol-edit.screen.ts

@@ -0,0 +1,27 @@
+import type { EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+export const inspectionProtocolEditScreen: EntityEditScreenDefinition = {
+  id: "inspection-protocol-edit",
+  type: "entityEdit",
+  entity: "inspection-protocol",
+  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"] },
+    ],
+  },
+};