@cosmicdrift/kumiko-framework 0.222.0 → 0.224.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.222.0",
+  "version": "0.224.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.222.0",
+    "@cosmicdrift/kumiko-types": "0.224.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.222.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.224.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/boot-validator.test.ts

@@ -1355,6 +1355,119 @@ describe("boot-validator", () => {
       ];
       expect(() => validateBoot(features)).not.toThrow();
     });
+
+    test("accepts display: checkboxes with columns and maxRows", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({
+                  options: ["a", "b", "c"] as const,
+                  display: "checkboxes",
+                  columns: 2,
+                  maxRows: 3,
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("rejects columns without display: checkboxes", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({ options: ["a", "b"] as const, columns: 2 }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/columns.*display.*checkboxes/);
+    });
+
+    test("rejects columns when display is explicitly dropdown", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({
+                  options: ["a", "b"] as const,
+                  display: "dropdown",
+                  columns: 2,
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/columns.*display.*checkboxes/);
+    });
+
+    test("rejects maxRows without display: checkboxes", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({ options: ["a", "b"] as const, maxRows: 3 }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/maxRows.*display.*checkboxes/);
+    });
+
+    test("rejects maxRows below 1", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({
+                  options: ["a", "b"] as const,
+                  display: "checkboxes",
+                  maxRows: 0,
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/invalid maxRows/);
+    });
+
+    test("rejects non-integer maxRows", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({
+                  options: ["a", "b"] as const,
+                  display: "checkboxes",
+                  maxRows: 1.5,
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/invalid maxRows/);
+    });
   });
 
   describe("image variants", () => {

package/src/engine/boot-validator/entity-handler.ts

@@ -1,7 +1,12 @@
 import type { BlurRegion, VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
 import { VARIANT_NAME_PATTERN } from "../../derivatives/variant-key";
 import { parseRefTarget } from "../parse-ref-target";
-import type { EmbeddedFieldDef, EntityDefinition, FeatureDefinition } from "../types";
+import type {
+  EmbeddedFieldDef,
+  EntityDefinition,
+  FeatureDefinition,
+  MultiSelectFieldDef,
+} from "../types";
 
 export const FILE_FIELD_TYPES = new Set(["file", "image", "files", "images"]);
 
@@ -676,6 +681,32 @@ function validateEmbeddedListMetadata(
 // default — wenn gesetzt — ist eine Teilmenge der options. Beides würde
 // auch im Zod-Schema bei runtime fehlschlagen, der Boot-Catch ist nur
 // die früheste Stelle für klare Fehlermeldungen.
+function validateCheckboxDisplayOptions(
+  field: MultiSelectFieldDef,
+  fieldName: string,
+  entityName: string,
+): void {
+  if (field.display === "checkboxes") {
+    if (field.maxRows !== undefined && (!Number.isInteger(field.maxRows) || field.maxRows < 1)) {
+      throw new Error(
+        `MultiSelect field "${fieldName}" on entity "${entityName}" has invalid maxRows "${field.maxRows}" — must be a positive integer.`,
+      );
+    }
+    // skip: checkboxes is the valid display for these options — the checks below only apply to other displays
+    return;
+  }
+  if (field.columns !== undefined) {
+    throw new Error(
+      `MultiSelect field "${fieldName}" on entity "${entityName}" sets columns, which is only valid with display: "checkboxes".`,
+    );
+  }
+  if (field.maxRows !== undefined) {
+    throw new Error(
+      `MultiSelect field "${fieldName}" on entity "${entityName}" sets maxRows, which is only valid with display: "checkboxes".`,
+    );
+  }
+}
+
 export function validateMultiSelectFields(feature: FeatureDefinition): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
@@ -697,6 +728,8 @@ export function validateMultiSelectFields(feature: FeatureDefinition): void {
           }
         }
       }
+
+      validateCheckboxDisplayOptions(field, fieldName, entityName);
     }
   }
 }

package/src/engine/factories.ts

@@ -162,25 +162,32 @@ export function createSelectField<
 }
 
 /**
- * Multi-Select-Field — N Werte aus einer festen Options-Liste.
+ * Multi-select field — N values from a fixed option list.
  *
- * Storage: jsonb-Array<string>. Jeder Eintrag muss in `options` enthalten
- * sein (Boot-Validator). UI-Renderer rendert das als Checkbox-Group oder
- * Multi-Select-Dropdown.
+ * Storage: jsonb-Array<string>. Every entry must be in `options`
+ * (boot-validator). Renders as a combobox dropdown by default; set
+ * `display: "checkboxes"` to render every option as a visible checkbox with
+ * a select-all toggle instead.
  *
  * ```ts
  * licenceClasses: createMultiSelectField({
  *   options: ["B", "BE", "C", "C1", "CE", "C1E", "D", "D1"] as const,
  *   default: ["B"],
  * }),
+ *
+ * languages: createMultiSelectField({
+ *   options: ["en", "de", "es", "fr", "it"] as const,
+ *   display: "checkboxes",
+ *   columns: 2,
+ * }),
  * ```
  *
  * Caller-API:
  *   Write: `{ licenceClasses: ["B", "BE", "C1"] }`
  *   Read:  `{ licenceClasses: ["B", "BE", "C1"] }`
  *
- * Wann statt `select`: wenn mehrere Werte gleichzeitig erlaubt sind.
- * Wann statt `embedded` mit Booleans: bei mehr als ~5 Optionen.
+ * Use instead of `select` when more than one value can be chosen at once.
+ * Use instead of `embedded` with booleans once there are more than ~5 options.
  */
 export function createMultiSelectField<const TOptions extends readonly string[]>(
   opts: { options: TOptions } & Partial<